Change:
Integrate Gorry's comments from This does not yet address Gorry's two other issues, which cover the background section, or potentially moving the transport implementation earlier in the document.
These issues mostly relate to the ARCH document wording: Section: Introduction It looks to me like we should have a reference after:/the BSD socket() interface./ Section: Background. > Section: Transport Services Architecture and Concepts The Application box seems one character wider than the TAPS boxes. i know apps are important to APIs, but suspect this is just a typo with extra '-' characters! /primarily offer knobs that are applicable to multiple transports/ Understand /knobs/, but suspect someone who does not speak English as a first language could be most puzzled, can we use a different word please? This may be something: /by which data transmission is ceased/ To me this doesn't read as common English and would be: /by which data transmission is stopped/ /by which data transmission ceases/ /Endpoint can vary in levels of specificity/ /Endpoint/ and /vary..specificity/ ... does it really vary, this seems difficult to pin down. Is this better as: /An Endpoint may be specified at various levels/? /that it wants to use for transport connections/ ... surely it does use it, or is more intended (if so, what)? Is it simpler as: /that it uses for transport connections/ /paths between itself and the Remote Endpoint/ I think strictly speaking, it is not between the App and the remote endpoint, but the local and remote endpoints, so could I suggest: /paths between the Local Endpoint and the Remote Endpoint/ /These options can come in the form of / could this be written: /These options can take the form of / -- appears multiple times in the ID. /Examples of options which may influence/ should be: /Examples of options that may influence/ /but that if this protocol is employed, a particular set of options should be used./ understood, is it even clearer (or not) as: /but that if this protocol is employed, a particular set of options should then be used./ In Section: Establishment Actions and Data Transfer Objects and Actions and Termination Actions:: I read this as definitions of terms, but there is no syntax that helps someone understand this. Would it look foolish to include a colon or something after each term (as for the case currently defining message), so it is super clear that this is the defining para? In Section: Establishment Actions /Connection to a remote endpoint/ Could remote endpoint be capitalised here to be consistent with earlier? /for example, to a TCP simultaneous open./ do we need an info reference here. (Sadly, many people will not know what this is). In Section: Data Transfer Objects and Actions / Messages may or may not be usable if incomplete or corrupted. / Agree, but not entirely clear, so I think we should explain to the reader. Could we say: /If a received Message is incomplete or corrupted, it may or may not be usable by a specific application./ In Section: Transport System Implementation Concepts /the functionality of transport networking/ what is transport networking? - either define or rephrase, e.g. as: /the functionality required to provide a transport service across a network/ In Section: Connection Group: /Connection Group: A Connections Group/ mixed single and plural, suggest: /Connection Group: A Connection Group/ /Path: A Path represents an available set of properties of a network route on which packets may be sent or received./ I'm not so happy with this. I know people use terms in various ways but to me this is not a route. I'd prefer something like: /Path: A Path represents an available set of properties that a Local Endpoint may use to send or receive packets with a Remote Endpoint./ I think we need to define /candidate/ in some way, e.g. something like: a path or protocol identified in the gathering stage over which a connection may be attempted in the racing stage/. Also I'd much prefer to actually the two terms (as we currently do in the earlier figure): /Candidate Gathering/ and /Candidate Racing/ The present contents of, provides a set of definitions which are fine... /Transport System Implementation Concepts/ but I really wonder if I could suggest something slightly different. I wonder if we could call this /Transport System Concepts/ and move this way forward in the document to provide a nice early introduction of these terms (with forward refs to sections where these are discussed - if that appeals. Things I'd like to see in this section: /Transport System Implementation Concepts/ Can we add a couple of sentences on gathering and racing, just to explain this using the terms used in the /lifetime of a connection/ figure. Can we create small subsections on /Cached State/ and /System Policy/ I think the subsection section titles below should be changed: /Gathering//Candidate Gathering/ and /Candidate Racing/Candidate Racing/ /### Message Framing, Parsing, and Serialization {#framing}/ This subsection appears out-of sequence. (Actually this could really help the reader if made a little easier to read and placed ahead of discussing the details). >
Closing this, we can discuss details in PR
lgtm

Discussion:
1. Many APIs to perform transport networking have been deployed, perhaps <del> the most widely known and imitated being the BSD socket() interface. The names and functions between these APIs are not consistent, and vary depending on the protocol being used.  For example, sending and receiving on a stream of data is conceptually the same between operating on an unencrypted Transmission Control Protocol (TCP) stream and operating on an encrypted Transport Layer Security (TLS) I-D.ietf-tls-tls13 stream over TCP, but applications cannot use the same socket send() and recv() calls on top of both kinds of connections.  Similarly, terminology for the implementation of protocols offering transport services vary based on the context of </del> <ins> the most widely known and imitated being the BSD socket() POSIX interface.  The names and functions between these APIs are not consistent, and vary depending on the protocol being used.  For example, sending and receiving on a stream of data is conceptually the same between operating on an unencrypted Transmission Control Protocol (TCP) stream and operating on an encrypted Transport Layer Security (TLS) I-D.ietf-tls-tls13 stream over TCP, but applications cannot use the same socket send() and recv() calls on top of both kinds of connections.  Similarly, terminology for the implementation of protocols offering transport services vary based on the context of </ins> the protocols themselves.  This variety can lead to confusion when trying to understand the similarities and differences between protocols, and how applications can use them effectively.

that an application can pass to describe its intent, requirements, prohibitions, and preferences for its networking operations.  For any system that provides generic Transport Services, these <del> properties should primarily offer knobs that are applicable to multiple transports.  Properties may have a large impact on the rest of the aspects of the interface: they can modify how establishment occurs, they can influence the expectations around data transfer, and they determine the set of events that will be supported. </del> <ins> properties should primarily be defined to apply to multiple transports.  Properties may have a large impact on the rest of the aspects of the interface: they can modify how establishment occurs, they can influence the expectations around data transfer, and they determine the set of events that will be supported. </ins> Establishment (establishment) focuses on the actions that an application takes on the basic objects to prepare for data

state or updating maintenance options. Termination (termination) focuses on the methods by which data <del> transmission is ceased, and state is torn down in the transport. </del> <ins> transmission is stopped, and state is torn down in the transport. </ins> The diagram below provides a high-level view of the actions taken during the lifetime of a connection.

Endpoint: An Endpoint represents one side of a transport connection.  Endpoints can be Local Endpoints or Remote Endpoints, and respectively represent an identity that the application uses <del> for the source or destination of a connection.  Endpoint can vary in levels of specificity, and can be resolved to more concrete identities. </del> <ins> for the source or destination of a connection.  An Endpoint may be specified at various levels, and an Endpoint with wider scope (such as a hostname) can be resolved to more concrete identities (such as IP addresses). </ins> Remote Endpoint: The Remote Endpoint represents the application's name for a peer that can participate in a transport connection.

service name/port. Local Endpoint: The Local Endpoint represents the application's <del> name for itself that it wants to use for transport connections. For example, a local IP address and port. </del> <ins> name for itself that it uses for transport connections.  For example, a local IP address and port. </ins> Path Selection Properties: The Path Selection Properties consist of the options that an application may set to influence the <del> selection of paths between itself and the Remote Endpoint.  These options can come in the form of requirements, prohibitions, or preferences.  Examples of options which may influence path selection include the interface type (such as a Wi-Fi Ethernet connection, or a Cellular LTE connection), characteristics of the path that are locally known like Maximum Transmission Unit (MTU) or discovered like Path MTU (PMTU), or predicted based on cached information like expected throughput or latency. </del> <ins> selection of paths between the Local Endpoint and the Remote Endpoint.  These options can take the form of requirements, prohibitions, or preferences.  Examples of options that may influence path selection include the interface type (such as a Wi- Fi Ethernet connection, or a Cellular LTE connection), characteristics of the path that are locally known like Maximum Transmission Unit (MTU) or discovered like Path MTU (PMTU), or predicted based on cached information like expected throughput or latency. </ins> Protocol Selection Properties: The Protocol Selection Properties consist of the options that an application may set to influence the selection of transport protocol, or to configure the behavior <del> of generic transport protocol features.  These options come in the form of requirements, prohibitions, and preferences.  Examples </del> <ins> of generic transport protocol features.  These options can take the form of requirements, prohibitions, and preferences.  Examples </ins> include reliability, service class, multipath support, and fast open support.

The presence of such Properties does not necessarily require that a specific protocol must be used when a Connection is established, but that if this protocol is employed, a particular set of options <del> should be used. </del> <ins> should then be used.. </ins> 4.1.3. <del> Initiate is the primary action that an application can take to create a Connection to a remote endpoint, and prepare any required </del> <ins> Initiate: The primary action that an application can take to create a Connection to a Remote Endpoint, and prepare any required </ins> local or remote state to be able to send and/or receive Messages. For some protocols, this may initiate a client-to-server style handshake; for other protocols, this may just establish local

resolution of the Remote Endpoint, occurs in response the Initiate call. <del> Listen is the action of marking a Listener as willing to accept </del> <ins> Listen: The action of marking a Listener as willing to accept </ins> incoming Connections.  The Listener will then create Connection objects as incoming connections are accepted (events). <del> Rendezvous is the action of establishing a peer-to-peer connection with a remote endpoint.  It simultaneously attempts to initiate a connection to a remote endpoint whilst listening for an incoming </del> <ins> Rendezvous: The action of establishing a peer-to-peer connection with a Remote Endpoint.  It simultaneously attempts to initiate a connection to a Remote Endpoint whilst listening for an incoming </ins> connection from that endpoint.  This corresponds, for example, to <del> a TCP simultaneous open.  The process of identifying options for the connection, such as resolution of the Remote Endpoint, occurs during the Rendezvous call.  If successful, the rendezvous call returns a Connection object to represent the established peer-to- peer connection. </del> <ins> a TCP simultaneous open RFC0793.  The process of identifying options for the connection, such as resolution of the Remote Endpoint, occurs during the Rendezvous call.  If successful, the rendezvous call returns a Connection object to represent the established peer-to-peer connection. </ins> 4.1.4.

assumed to be ordered within the Message.  If an application does not care about the order in which a peer receives two distinct spans of bytes, those spans of bytes are considered independent <del> Messages.  Messages may or may not be usable if incomplete or corrupted.  Boundaries of a Message may or may not be understood or transmitted by transport protocols.  Specifically, what one application considers to be two Messages sent on a stream-based transport may be treated as a single Message by the application on the other side. Send is the action to transmit a Message or partial Message over a </del> <ins> Messages.  If a received Message is incomplete or corrupted, it may or may not be usable by certain applications.  Boundaries of a Message may or may not be understood or transmitted by transport protocols.  Specifically, what one application considers to be two Messages sent on a stream-based transport may be treated as a single Message by the application on the other side. Send: The action to transmit a Message or partial Message over a </ins> Connection to a Remote Endpoint.  The interface to Send may include options specific to how the Message's content is to be sent.  Status of the Send operation may be delivered back to the application in an event (events). <del> Receive is an action that indicates that the application is ready to asynchronously accept a Message over a Connection from a Remote </del> <ins> Receive: An action that indicates that the application is ready to asynchronously accept a Message over a Connection from a Remote </ins> Endpoint, while the Message content itself will be delivered in an event (events).  The interface to Receive may include options specific to the Message that is to be delivered to the

4.1.6. <del> Close is the action an application may take on a Connection to </del> <ins> Close: The action an application may take on a Connection to </ins> indicate that it no longer intends to send data, is no longer willing to receive data, and that the protocol should signal this state to the remote endpoint if applicable. <del> Abort is an action the application may take on a Connection to </del> <ins> Abort: The action the application may take on a Connection to </ins> indicate a Close, but with the additional indication that the transport system should not attempt to deliver any outstanding data.

The Transport System Implementation Concepts define the set of objects used internally to a system or library to provide the <del> functionality of transport networking, as required by the abstract interface. Connection Group: A Connections Group is a set of Connections that share properties.  For multiplexing transport protocols, the Connection Group defines the set of Connections that can be multiplexed together. Path: A Path represents an available set of properties of a network route on which packets may be sent or received. Protocol Instance: A Protocol Instance is a single instance of one protocol, including any state it has necessary to establish connectivity or send and receive Messages. Protocol Stack: A Protocol Stack is a set of Protocol Instances (including relevant application, security, transport, or Internet protocols) that are used together to establish connectivity or send and receive Messages.  A single stack may be simple (a single transport protocol instance over IP), or complex (multiple application protocol streams going through a single security and transport protocol, over IP; or, a multi-path transport protocol over multiple transport sub-flows). System Policy: System Policy represents the input from an operating system or other global preferences that can constrain or influence how an implementation will gather candidate paths and protocols (gathering) and race the candidates during establishment (racing).  Specific aspects of the System Policy may apply to all </del> <ins> functionality required to provide a transport service across a network, as required by the abstract interface. Connection Group: A set of Connections that share properties.  For multiplexing transport protocols, the Connection Group defines the set of Connections that can be multiplexed together. Path: Represents an available set of properties that a Local Endpoint may use to send or receive packets with a Remote Endpoint. Protocol Instance: A single instance of one protocol, including any state it has necessary to establish connectivity or send and receive Messages. Protocol Stack: A set of Protocol Instances (including relevant application, security, transport, or Internet protocols) that are used together to establish connectivity or send and receive Messages.  A single stack may be simple (a single transport protocol instance over IP), or complex (multiple application protocol streams going through a single security and transport protocol, over IP; or, a multi-path transport protocol over multiple transport sub-flows). Candidate Path: One path that is available to an application and conforms to the Path Selection Properties and System Policy. Candidate Paths are identified during the gathering phase (gathering) and may be used during the racing phase (racing). Candidate Protocol Stack: One protocol stack that may be used by an application for a connection, of which there may be several. Candidate Protocol Stacks are identified during the gathering phase (gathering) and may be started during the racing phase (racing). System Policy: Represents the input from an operating system or other global preferences that can constrain or influence how an implementation will gather candidate paths and protocol stacks (gathering) and race the candidates during establishment (racing). Specific aspects of the System Policy may apply to all </ins> Connections, or only certain ones depending on the runtime context and properties of the Connection. <del> Cached State: Cached State is the state and history that the implementation keeps for each set of associated endpoints that have been used previously.  This can include DNS results, TLS session state, previous success and quality of transport protocols over certain paths. </del> <ins> Cached State: The state and history that the implementation keeps for each set of associated endpoints that have been used previously.  This can include DNS results, TLS session state, previous success and quality of transport protocols over certain paths. </ins> 4.2.1.