Draft: draft-ietf-taps-impl

Commentary: NB : This reviewer may be unreasonably biased against unnecessary mention of event - driven interaction patterns . Viewed in concert with the other pre - requisite TAPS documents , the text of this draft is quite readable and represents a useful collection of implementation considerations for various components of a transport services system . My biggest point of concern is the fluctuating level of detail between the different Sections , leading to speculations about who might have written what . Some Sections remain quite general and avoid making too many assumptions about the underlying software architecture . Others discuss a specific implementation approach in some detail . In particular Section 6 ( Message Framers ) stands out from the rest of the text . Language that relates to event - driven interaction patterns is almost exclusively found in this Section , where different types of events are " generated " , " delivered " , " received " or " handled " by and between various components . In the rare cases where events are mentioned in the other Sections , they are often associated with other verbs like " notify " , " cause " , " provoke " or even " call " ( see , e.g. , Section 4.5 or Section 8) . Indeed , the text in most of these other Sections would require only very minor edits to avoid any reference to an event - driven architecture altogether ( examples below ) . It is interesting that the same can not easily be said of Section 6 , alone . Overall , the text could benefit from an edit pass that normalizes language and ( use of ) terms and adds a few more references to related documents . Other than that , I have few issues with it . Below are a few remarks and suggestions to cherry - pick from , as usual . Quoting from 4.4.1 . Determining Successful Establishment : Not only is the term " Ready event " used without any sort of context or introduction , it is the first point in the text where familiarity with a specific event type is implied . The intent of the whole sentence could be much better conveyed without this terminological baggage . Suggestion : From later in the section , quoting : While it is reasonable to mention the specific error type here ( although a reference to the document where it is defined is still missing ) , would n't the following suffice ? Quoting from 4.5 . Establishing multiplexed connections : Should n't events rather be " emitted " or " triggered " instead of ( ambiguously ) " called " ? It is gratifying to observe that Sections 4.6 and 4.7 on the other hand entirely avoid specific references to an event - based architecture , instead speaking of , e.g. , " passing " Connection objects to the application . Quoting from 6 . Implementing Message Framers : Given that this section is the only place in the text where concepts and language centered around an event - based implementation are consistently used , it would be appropriate to point this out in its introduction : Quoting 4.4.1 . Determining Successful Establishment : The adverb " differently " is too far removed from " select " , becoming ambiguous and could be wrongly understood to modify " connected " instead . Suggestion : Quoting 4.6 . Handling connectionless protocols : The reference to the section is ungrammatical . About 5 . Implementing Sending and Receiving Data : Might it not be helpful to conclude the introduction with some examples : UDP Datagrams , TCP streams , HTTP responses ? About 5.1.1 . Message Properties : The list of Message Properties is given without any sort of context or introduction . What 's the story here , is this an exhaustive list or just a list of those properties that can be adjusted to modify the send and receive behavior ? Quoting 5.2 . Sending Messages : That sentence is exceedingly hard to parse . Quoting 5.3 . Handling of data for fast - open protocols : Possibly intentional redundant wording , but unfortunately distracting . 
 LGMTThanks for taking care of the edits ! Just a nit and a question . I assume you deliberately skipped the comment from the issue about event - based terminology in Section 6 , not thinking it was needed as we reference the API draft for the terminology ?
Paragraph (version A):
The process of connection establishment completes when one leaf node
of the tree has successfully completed negotiation with the Remote
Endpoint, or else all nodes of the tree have failed to connect.  The
first leaf node to complete its connection is then used by the
application to send and receive data.
Paragraph (version B):
The process of connection establishment completes when one leaf node
of the tree has successfully completed negotiation with the Remote
Endpoint, or else all nodes of the tree have failed to connect.  The
first leaf node to complete its connection is then used by the
application to send and receive data.  This is signalled to the
application using the Ready event in the API (Section 7.1 of I-
D.ietf-taps-interface).
Paragraph (version A):
Implementations may select the criteria by which a leaf node is
considered to be successfully connected differently on a per-protocol
basis.  If the only protocol being used is a transport protocol with
a clear handshake, like TCP, then the obvious choice is to declare
that node "connected" when the last packet of the three-way handshake
has been received.  If the only protocol being used is an
connectionless protocol, like UDP, the implementation may consider
the node fully "connected" the moment it determines a route is
present, before sending any packets on the network, see further
connectionless-racing.
Paragraph (version B):
On a per-protocol basis, implementations may select different
criteria by which a leaf node is considered to be successfully
connected.  If the only protocol being used is a transport protocol
with a clear handshake, like TCP, then the obvious choice is to
declare that node "connected" when the last packet of the three-way
handshake has been received.  If the only protocol being used is an
connectionless protocol, like UDP, the implementation may consider
the node fully "connected" the moment it determines a route is
present, before sending any packets on the network, see further
connectionless-racing.
Paragraph (version A):
not generate a Ready event for the Connection until TLS is
established.
Paragraph (version A):
If all of the leaf nodes fail to connect during racing, i.e. none of
the configurations that satisfy all requirements given in the
Transport Properties actually work over the available paths, then the
transport system should notify the application with an InitiateError
event.  An InitiateError event should also be generated in case the
transport system finds no usable candidates to race.
Paragraph (version B):
not generate a Ready event for the Connection until the TLS handshake
is complete.
Paragraph (version B):
If all of the leaf nodes fail to connect during racing, i.e. none of
the configurations that satisfy all requirements given in the
Transport Properties actually work over the available paths, then the
transport system should report an InitiateError to the application.
An InitiateError event should also be generated in case the transport
system finds no usable candidates to race.
Paragraph (version A):
called until data is received.  Instead, calling the
ConnectionReceived event could be delayed until the first Message
arrives.
Paragraph (version B):
delivered until data is received.  Instead, delivering the
ConnectionReceived event could be delayed until the first Message
arrives.
Paragraph (version A):
However, this can cause a problem if a specific peer is not reachable
over the network using the connectionless protocol, or data cannot be
exchanged with the peer for any other reason.  To mitigate this, an
application can use a Message Framer message-framers on top of a
connectionless protocol to only mark a specific connection attempt as
ready when some data has been received, or after some application-
level handshake has been performed.
Paragraph (version B):
However, this can cause a problem if a specific peer is not reachable
over the network using the connectionless protocol, or data cannot be
exchanged with the peer for any other reason.  To mitigate this, an
application can use a Message Framer (message-framers) on top of a
connectionless protocol to only mark a specific connection attempt as
ready when some data has been received, or after some application-
level handshake has been performed.
Paragraph (version A):
The most basic mapping for sending a Message is an abstraction of
datagrams, in which the transport protocol naturally deals in
discrete packets.  Each Message here corresponds to a single
datagram.  Generally, these will be short enough that sending and
receiving will always use a complete Message.
Paragraph (version A):
For protocols that expose byte-streams, the only delineation provided
by the protocol is the end of the stream in a given direction.  Each
Message in this case corresponds to the entire stream of bytes in a
direction.  These Messages may be quite long, in which case they can
be sent in multiple parts.
Paragraph (version A):
Protocols that provide the framing (such as length-value protocols,
or protocols that use delimiters) may support Message sizes that do
not fit within a single datagram.  Each Message for framing protocols
corresponds to a single frame, which may be sent either as a complete
Message in the underlying protocol, or in multiple parts.
Paragraph (version B):
The most basic mapping for sending a Message is an abstraction of
datagrams, in which the transport protocol naturally deals in
discrete packets (such as UDP).  Each Message here corresponds to a
single datagram.  Generally, these will be short enough that sending
and receiving will always use a complete Message.
Paragraph (version B):
For protocols that expose byte-streams (such as TCP), the only
delineation provided by the protocol is the end of the stream in a
given direction.  Each Message in this case corresponds to the entire
stream of bytes in a direction.  These Messages may be quite long, in
which case they can be sent in multiple parts.
Paragraph (version B):
Protocols that provide the framing (such as length-value protocols,
or protocols that use delimiters like HTTP/1.1) may support Message
sizes that do not fit within a single datagram.  Each Message for
framing protocols corresponds to a single frame, which may be sent
either as a complete Message in the underlying protocol, or in
multiple parts.
Paragraph (version B):
The API allows various properties to be associated with each Message,
which should be implemented as discussed below.
Paragraph (version A):
to understand where messages end, either via a supplied or because
the top-level protocol in the established Protocol Stack preserves
message boundaries.  If the top-level protocol only supports a byte-
stream and no framers were supported, the application can control the
flow of received data by specifying the minimum number of bytes of
Message content it wants to receive at one time.
Paragraph (version B):
to understand where messages end, either via a supplied Message
Framer or because the top-level protocol in the established Protocol
Stack preserves message boundaries.  If the top-level protocol only
supports a byte-stream and no framers were supported, the application
can control the flow of received data by specifying the minimum
number of bytes of Message content it wants to receive at one time.
Paragraph (version A):
If the application has 0-RTT data to send during handshake(s), it
needs to provide this data before the handshakes have begun.  When
racing, this means that the data should be provided before the
process of connection establishment has begun.  If the application
wants to send 0-RTT data, it must indicate this to the implementation
by setting the "Safely Replayable" send parameter to true when
sending the data.  In general, 0-RTT data may be replayed (for
example, if a TCP SYN contains data, and the SYN is retransmitted,
the data will be retransmitted as well but may be considered as a new
connection instead of a retransmission).  Also, when racing
connections, different leaf nodes have the opportunity to send the
same data independently.  If data is truly safely replayable, this
should be permissible.
Paragraph (version B):
If the application has 0-RTT data to send during handshake(s), it
needs to provide this data before the handshakes have begun.  If the
application wants to send 0-RTT data, it must indicate this to the
implementation by setting the "Safely Replayable" send parameter to
true when sending the data.  In general, 0-RTT data may be replayed
(for example, if a TCP SYN contains data, and the SYN is
retransmitted, the data will be retransmitted as well but may be
considered as a new connection instead of a retransmission).  When
racing connections, different leaf nodes have the opportunity to send
the same data independently.  If data is truly safely replayable,
this is permissible.
Paragraph (version A):
Common Message Framers can be provided by a Transport Services
implementation, but an implementation ought to allow custom Message
Framers to be defined by the application or some other piece of
software.  This section describes one possible API for defining
Message Framers as an example.
Paragraph (version B):
Common Message Framers can be provided by a Transport Services
implementation, but an implementation ought to allow custom Message
Framers to be defined by the application or some other piece of
software.  This section describes one possible API for defining
Message Framers, as an example.