Draft: draft-ietf-taps-arch

Commentary: Address issue Add more intro section , with friendly diagrams  why we use events , messages , and racing 
 To me the document is in very good shape , but there are several things that just appear , and a few short paras and maybe a simple picture could help avoid people giving - up before they know the document is useful to them . We seem to not introduce it nicely , I 'd suggest : This is n't scarey ( draw a simple familiar figure to start our story , that the reader immediately recognises ) Sockets v Streams ... we speak of messages , let 's explain early that they ae all you need for any app . Events ... we know these are " nromal " - but let 's say we provide an eevent - driven interface . it would even be worth saying why thsi is much better ( Tommy - Apple have been doing this from the start , can you perhaps say why it is beautiful ? ) Comments follow : Section : Background . The last part of this section suddenly introduces messages . I know it is just an example , but readers may be already looking here at whether this is an interface to TCP or UDP or something else ... and I think we do not really tackle that earlier enough . One way to help that would be to draw a diagram that looks something like this , in this section : + -----------------------------------------------------+ + ------------------------+----------------------------+ | + ------------------------|----------------------------+ + ------------------------|----------------------------+ | + ------------------------|----------------------------+ + ------------------------|----------------------------+ + ------------------------|----------------------------+ + -----------------------------------------------------+ And the say that the Transport Services API provides message - oriented communication using transport protocols ( e.g. UDP , TCP , etc ) . I 'd also mention the words /data transfer/ somewhere . Providing a simpler earlier diagram may also be slightly easier on the new reader . In the same way , the intro should explain a little of the idea of /events/ - common enough to some , but may be unexpected for a new reader . 
 I suspect you 're already writing this sort of approach : I think it would be super nice if the background / intro text clearly had a para expalining that this is a call - back based API . I do suspect that many people coming to this will be atrracted because the new API is simple and provides a more modern interface . The rationale for why we design it to enable multiple transports , etc , is the " detail inside the engine " the fact it delivers what they want is the first point to make:- ) . 
 does close this issue ? 
 Yes , I think so . 
 lgtm modulo commentsLGTM !
Paragraph (version B):
The model for using sockets for networking can be represented as
follows: applications create connections and transfer data using the
socket API, which provides the interface to the implementations of
UDP and TCP (typically implemented in the system's kernel), which in
turn send data over the available network layer interfaces.
Paragraph (version B):
The Transport Services architecture maintains this general model of
interaction, but aims to both modernize the API surface exposed for
transport protocols and enrich the capabilities of the transport
system implementation.
Paragraph (version B):
The Transport Services API I-D.ietf-taps-interface defines the
mechanism for an application to create and monitor network
connections, and transfer data.  The Implementation I-D.ietf-taps-
impl is responsible for mapping the API into the various available
transport protocols and managing the available network interfaces and
paths.
Paragraph (version B):
There are a few key departures that Transport Services makes from the
sockets API: it presents an asynchronous, event-driven API; it uses
messages for respresenting data transfer to applications; and it
assumes an implementation that can use multiple IP addresses,
multiple protocols, multiple paths, and provide multiple application
streams.
Paragraph (version B):
Originally, sockets presented a blocking interface for establishing
connections and transferring data.  However, most modern applications
interact with the network asynchronously.  When sockets are presented
as an asynchronous interface, they generally use a try-and-fail
model.  If the application wants to read, but data has not yet been
received from the peer, the call to read will fail.  The application
then waits for a notification that it should try again.
Paragraph (version B):
All interaction with a Transport Services system is expected to be
asynchronous, and use an event-driven model unlike sockets events.
For example, if the application wants to read, its call to read will
not fail, but will deliver an event containing the received data once
it is available.
Paragraph (version B):
The Transport Services API also delivers events regarding the
lifetime of a connection and changes to available network links,
which were not previously made explicit in sockets.
Paragraph (version B):
Using asynchronous events allows for a much simpler interaction model
when establishing connections and transferring data.  Events in time
more closely reflect the nature of interactions over networks, as
opposed to how sockets represent network resources as file system
objects that may be temporarily unavailable.
Paragraph (version B):
Sockets provide a message interface for datagram protocols like UDP,
but provide an unstructured stream abstraction for TCP.  While TCP
does indeed provide the ability to send and receive data as streams,
most applications need to interpret structure within these streams.
HTTP/1.1 uses character delimiters to segment messages over a stream;
TLS record headers carry a version, content type, and length; and
HTTP/2 uses frames to segment its headers and bodies.
Paragraph (version B):
In order to more closely match the way applications use the network,
the Transport Services API respresents data as messages.  Messages
seamlessly work with transport protocols that support datagrams or
records, but can also be used over a stream by defining the
application-layer framing being used framing.
Paragraph (version B):
Sockets, for protocols like TCP, are generally limited to connecting
to a single address over a single interface.  They also present a
single stream to the application.  Software layers built upon sockets
often propagate this limitation of a single-address single-stream
model.  The Transport Services architecture is designed to handle
multiple candidate endpoints, protocols, and paths; and support
multipath and multistreaming protocols.
Paragraph (version B):
Transport Services implementations are meant to be flexible at
connection establishment time, considering many different options and
trying to select the most optimal combinations (gathering and
racing).  This requires applications to provide higher-level
endpoints than IP addresses, such as hostnames and URLs, which are
used by a Transport Services implementation for resolution, path
selection, and racing.
Paragraph (version B):
Flexibility after connection establishment is also important.
Transport protocols that can migrate between multiple network layer
interfaces need to be able to process and react to interface changes.
Protocols that support multiple application-layer streams need to
support initiating and receiving new streams using existing
connections.