Change:
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), wouldn't the following suffice? Quoting from 4.5. Establishing multiplexed connections: Shouldn'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 added 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?

Discussion:
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 <del> application to send and receive data. </del> <ins> 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). </ins> Successes and failures of a given attempt should be reported up to parent nodes (towards the trunk of the tree).  For example, in the

4.4.1. <del> 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 </del> <ins> 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 </ins> 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

quickly, but TLS negotiation is either very slow or fails altogether in particular network conditions or to a particular endpoint.  To avoid the issue of TLS possibly failing, the implementation should <del> not generate a Ready event for the Connection until TLS is established. </del> <ins> not generate a Ready event for the Connection until the TLS handshake is complete. </ins> 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 <del> 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. </del> <ins> 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. </ins> 4.5.

called without Messages being handed over, it cannot be guaranteed that the Remote Endpoint will have any way to know about this, and hence a passive endpoint's ConnectionReceived event might not be <del> called until data is received.  Instead, calling the </del> <ins> delivered until data is received.  Instead, delivering the </ins> ConnectionReceived event could be delayed until the first Message arrives.

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 <del> application can use a Message Framer message-framers on top of a </del> <ins> application can use a Message Framer (message-framers) on top of a </ins> 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.

The most basic mapping for sending a Message is an abstraction of datagrams, in which the transport protocol naturally deals in <del> 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. </del> <ins> 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. </ins> <del> 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. </del> <ins> 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. </ins> Protocols that provide the framing (such as length-value protocols, <del> 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. </del> <ins> 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. </ins> 5.1.

5.1.1. <ins> The API allows various properties to be associated with each Message, which should be implemented as discussed below. </ins> "msgLifetime": this should be implemented by removing the Message from the queue of pending Messages after the Lifetime has expired. A queue of pending Messages within the transport system

complete Message, the implementation should wait until an entire Message (datagram, stream, or frame) is read before delivering any Message content to the application.  This requires the implementation <del> 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. </del> <ins> 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. </ins> If a Connection finishes before a requested Receive action can be satisfied, the Transport Services API should deliver any partial

connection. If the application has 0-RTT data to send during handshake(s), it <del> 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. </del> <ins> 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. </ins> Once the application has provided its 0-RTT data, a Transport Services implementation should keep a copy of this data and provide

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 <del> Message Framers as an example. </del> <ins> Message Framers, as an example. </ins> 6.1.