Code change:
Starting to address This is an early review, to check if we like the structure. I'd also like help filling out the SCTP section!
I can also help with SCTP, which I would do in the same style that I suggest above (for TCP, in my example of "Abort") - also later.
We've updated Implementation mapping details for most protocols with , but we didn't tackle SCTP yet.
I'm fine with this being assigned to me. However, it's more than just writing the SCTP text. Here's the relevant part of what I wrote in PR : I don't suggest to delete much of the text that's there but definitely amend it with the RFC reference at least for what's covered in RFC 8303. There's a very direct line from this type of text in RFC 8303 to the original specs, so I do believe that should be helpful. That's (obviously) post-Montreal though!
NAME please send a PR along these lines.
LGTM modulo mwelzl changes.I think this is a good step forward. This said, I think we should describe things focusing on the transport's API call to be made (in line with the spec - that's why we have RFCs 8303 and 8304) rather than protocol internals. E.g., rather than saying that Abort on a TCP connection transmits a RST, I think we should simply say that Abort calls ABORT.TCP [RFC 8303, Section 4.1]. I can take care of these things, later. I'd still like to focus more on the API doc at this time.

Related discussion:
text: 9. <ins> Each protocol that can run as part of a Transport Services implementation defines both its API mapping as well as implementation details. API mappings for a protocol apply most to Connections in which the given protocol is the "top" of the Protocol Stack.  For example, the mapping of the "Send" function for TCP applies to Connections in which the application directly sends over TCP.  If HTTP/2 is used on top of TCP, the HTTP/2 mappings take precendence. Each protocol has a notion of Connectedness.  Possible values for Connectedness are: Unconnected.  Unconnected protocols do not establish explicit state between endpoints, and do not perform a handshake during Connection establishment. Connected.  Connected protocols establish state between endpoints, and perform a handshake during Connection establishment.  The handshake may be 0-RTT to send data or resume a session, but bidirectional traffic is required to confirm connectedness. Multiplexing Connected.  Multiplexing Connected protocols share properties with Connected protocols, but also explictly support opening multiple application-level flows.  This means that they can support cloning new Connection objects without a new explicit handshake. Protocols also define a notion of Data Unit.  Possible values for Data Unit are: Byte-stream.  Byte-stream protocols do not define any Message boundaries of their own apart from the end of a stream in each direction. Datagram.  Datagram protocols define Message boundaries at the same level of transmission, such that only complete (not partial) Messages are supported. Message.  Message protocols support Message boundaries that can be sent and received either as complete or partial Messages.  Maximum Message lengths can be defined, and Messages can be partially reliable. </ins> 9.1. <del> Connection lifetime for TCP translates fairly simply into the the abstraction presented to an application.  When the TCP three-way handshake is complete, its layer of the Protocol Stack can be considered Ready (established).  This event will cause racing of Protocol Stack options to complete if TCP is the top-level protocol, at which point the application can be notified that the Connection is Ready to send and receive. If the application sends a Close, that can translate to a graceful termination of the TCP connection, which is performed by sending a FIN to the remote endpoint.  If the application sends an Abort, then the TCP state can be closed abruptly, leading to a RST being sent to the peer. Without a layer of framing (a top-level protocol in the established Protocol Stack that preserves message boundaries, or an application- supplied deframer) on top of TCP, the receiver side of the transport system implementation can only treat the incoming stream of bytes as a single Message, terminated by a FIN when the Remote Endpoint closes the Connection. </del> <ins> Connectedness: Connected Data Unit: Byte-stream API mappings for TCP are as follows: TCP connections between two hosts map directly to Connection objects. Calling "Initiate" on a TCP Connection causes it to reserve a local port, and send a SYN to the Remote Endpoint. Early idempotent data is sent on a TCP Connection in the SYN, as TCP Fast Open data. A TCP Connection is ready once the three-way handshake is complete. TCP can throw various errors during connection setup. Specifically, it is important to handle a RST being sent by the peer during the handshake. Once established, TCP throws errors whenever the connection is disconnected, such as due to receive a RST from the peer; or hitting a TCP retransmission timeout. Calling "Listen" for TCP binds a local port and prepares it to receive inbound SYN packets from peers. TCP Listeners will deliver new connections once they have replied to an inbound SYN with a SYN-ACK. Calling "Clone" on a TCP Connection creates a new Connection with equivalent parameters.  The two Connections are otherwise independent. TCP does not on its own preserve Message boundaries.  Calling "Send" on a TCP connection lays out the bytes on the TCP send stream without any other delineation.  Any Message marked as Final will cause TCP to send a FIN once the Message has been completely written. TCP delivers a stream of bytes without any Message delineation. All data delivered in the "Received" or "ReceivedPartial" event will be part of a single stream-wide Message that is marked Final (unless a MessageFramer is used).  EndOfMessage will be delivered when the TCP Connection has received a FIN from the peer. Calling "Close" on a TCP Connection indicates that the Connection should be gracefully closed by sending a FIN to the peer and waiting for a FIN-ACK before delivering the "Closed" event. Calling "Abort" on a TCP Connection indicates that the Connection should be immediately closed by sending a RST to the peer. </ins> 9.2. <del> UDP as a direct transport does not provide any handshake or connectivity state, so the notion of the transport protocol becoming Ready or established is degenerate.  Once the system has validated that there is a route on which to send and receive UDP datagrams, the protocol is considered Ready.  Similarly, a Close or Abort has no meaning to the on-the-wire protocol, but simply leads to the local state being torn down. </del> <ins> Connectedness: Unconnected </ins> <del> When sending and receiving messages over UDP, each Message should correspond to a single UDP datagram.  The Message can contain metadata about the packet, such as the ECN bits applied to the packet. </del> <ins> Data Unit: Datagram </ins> <del> 9.3. </del> <ins> API mappings for UDP are as follows: </ins> <del> To support sender-side stream schedulers (which are implemented on the sender side), a receiver-side Transport System should always support message interleaving RFC8260. </del> <ins> UDP connections represent a pair of specific IP addresses and ports on two hosts. </ins> <del> SCTP messages can be very large.  To allow the reception of large messages in pieces, a "partial flag" can be used to inform a (native SCTP) receiving application that a message is incomplete.  After receiving the "partial flag", this application would know that the next receive calls will only deliver remaining parts of the same message (i.e., no messages or partial messages will arrive on other streams until the message is complete) (see Section 8.1.20 in RFC6458).  The "partial flag" can therefore facilitate the implementation of the receiver buffer in the receiving application, at the cost of limiting multiplexing and temporarily creating head- of-line blocking delay at the receiver. </del> <ins> Calling "Initiate" on a UDP Connection causes it to reserve a local port, but does not generate any traffic. </ins> <del> When a Transport System transfers a Message, it seems natural to map the Message object to SCTP messages in order to support properties such as "Ordered" or "Lifetime" (which maps onto partially reliable delivery with a SCTP_PR_SCTP_TTL policy RFC6458).  However, since multiplexing of Connections onto SCTP streams may happen, and would be hidden from the application, the Transport System requires a per- stream receiver buffer anyway, so this potential benefit is lost and the "partial flag" becomes unnecessary for the system. </del> <ins> Early data on a UDP Connection does not have any special meaning. The data is sent whenever the Connection is Ready. </ins> <del> The problem of long messages either requiring large receiver-side buffers or getting in the way of multiplexing is addressed by message interleaving RFC8260, which is yet another reason why a receivers- side transport system supporting SCTP should implement this mechanism. </del> <ins> A UDP Connection is ready once the system has reserved a local port and has a path to send to the Remote Endpoint. </ins> <del> 9.4. </del> <ins> UDP Connections can only generate errors on initiation due to port conflicts on the local system. Once in use, UDP throws errors upon receiving ICMP notifications indicating failures in the network. Calling "Listen" for UDP binds a local port and prepares it to receive inbound UDP datagrams from peers. UDP Listeners will deliver new connections once they have received traffic from a new Remote Endpoint. Calling "Clone" on a UDP Connection creates a new Connection with equivalent parameters.  The two Connections are otherwise independent. Calling "Send" on a UDP connection sends the data as the payload of a complete UDP datagram.  Marking Messages as Final does not change anything in the datagram's contents. UDP only delivers complete Messages to "Received", each of which represents a single datagram received in a UDP packet. Calling "Close" on a UDP Connection releases the local port reservation. Calling "Abort" on a UDP Connection is identical to calling "Close". 9.3. </ins> The mapping of a TLS stream abstraction into the application is <del> equivalent to the contract provided by TCP (see tcp).  The Ready state should be determined by the completion of the TLS handshake, which involves potentially several more round trips beyond the TCP handshake.  The application should not be notified that the Connection is Ready until TLS is established. </del> <ins> equivalent to the contract provided by TCP (see tcp), and builds upon many of the actions of TCP connections. Connectedness: Connected Data Unit: Byte-stream Connection objects represent a single TLS connection running over a TCP connection between two hosts. Calling "Initiate" on a TLS Connection causes it to first initiate a TCP connection.  Once the TCP protocol is Ready, the TLS handshake will be performed as a client (starting by sending a "client_hello", and so on). Early idempotent data is supported by TLS 1.3, and sends encrypted application data in the first TLS message when performing session resumption.  For older versions of TLS, or if a session is not being resumed, the initial data will be delayed until the TLS handshake is complete.  TCP Fast Option can also be enabled automatically. A TLS Connection is ready once the underlying TCP connection is Ready, and TLS handshake is also complete and keys have been established to encrypt application data. In addition to TCP initiation errors, TLS can generate errors during its handshake.  Examples of error include a failure of the peer to successfully authenticate, the peer rejecting the local authentication, or a failure to match versions or algorithms. TLS connections will generate TCP errors, or errors due to failures to rekey or decrypt received messages. Calling "Listen" for TLS listens on TCP, and sets up received connections to perform server-side TLS handshakes. TLS Listeners will deliver new connections once they have successfully completed both TCP and TLS handshakes. As with TCP, calling "Clone" on a TLS Connection creates a new Connection with equivalent parameters.  The two Connections are otherwise independent. Like TCP, TLS does not preserve message boundaries.  Although application data is framed natively in TLS, there is not a general guarantee that these TLS messages represent semantically meaningful application stream boundaries.  Rather, sending data on a TLS Connection only guarantees that the application data will be transmitted in an encrypted form.  Marking Messages as Final causes a "close_notify" to be generated once the data has been written. Like TCP, TLS delivers a stream of bytes without any Message delineation.  The data is decrypted prior to being delivered to the application.  If a "close_notify" is received, the stream-wide Message will be delivered with EndOfMessage set. Calling "Close" on a TLS Connection indicates that the Connection should be gracefully closed by sending a "close_notify" to the peer and waiting for a corresponding "close_notify" before delivering the "Closed" event. Calling "Abort" on a TCP Connection indicates that the Connection should be immediately closed by sending a "close_notify", optionally preceded by "user_canceled", to the peer. Implementations do not need to wait to receive "close_notify" before delivering the "Closed" event. 9.4. DTLS follows the same behavior as TLS (tls), with the notable exception of not inheriting behavior directly from TCP.  Differences from TLS are detailed below, and all cases not explicitly mentioned should be considered the same as TLS. Connectedness: Connected Data Unit: Datagram Connection objects represent a single DTLS connection running over a set of UDP ports between two hosts. Calling "Initiate" on a DTLS Connection causes it reserve a UDP local port, and begin sending handshake messages to the peer over UDP.  These messages are reliable, and will be automatically retransmitted. A DTLS Connection is ready once the TLS handshake is complete and keys have been established to encrypt application data. Sending over DTLS does preserve message boundaries in the same way that UDP datagrams do.  Marking a Message as Final does send a "close_notify" like TLS. Receiving over DTLS delivers one decrypted Message for each received DTLS datagram.  If a "close_notify" is received, a Message will be delivered that is marked as Final. </ins> 9.5.