Draft: draft-ietf-taps-arch

Commentary: Integrate  's comments from This does not yet address  '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  document wording : Section : Introduction It looks to me like we should have a reference after:/the BSD socket ( ) interface./ Section : Background . < < separate issue on missing backgroundSection : 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 does n'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  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 ) . < < separate comment 
 Closing this , we can discuss details in PR 
 lgtm
Paragraph (version A):
Many APIs to perform transport networking have been deployed, perhaps
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
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.
Paragraph (version B):
Many APIs to perform transport networking have been deployed, perhaps
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
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.
Paragraph (version A):
Pre-Establishment (preestablishment) encompasses the properties
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
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.
Paragraph (version B):
Pre-Establishment (preestablishment) encompasses the properties
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
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.
Paragraph (version A):
Termination (termination) focuses on the methods by which data
transmission is ceased, and state is torn down in the transport.
Paragraph (version B):
Termination (termination) focuses on the methods by which data
transmission is stopped, and state is torn down in the transport.
Paragraph (version A):
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
for the source or destination of a connection.  Endpoint can vary
in levels of specificity, and can be resolved to more concrete
identities.
Paragraph (version B):
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
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).
Paragraph (version A):
Local Endpoint: The Local Endpoint represents the application's
name for itself that it wants to use for transport connections.
For example, a local IP address and port.
Paragraph (version A):
Path Selection Properties: The Path Selection Properties consist
of the options that an application may set to influence the
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.
Paragraph (version A):
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
of generic transport protocol features.  These options come in the
form of requirements, prohibitions, and preferences.  Examples
include reliability, service class, multipath support, and fast
open support.
Paragraph (version B):
Local Endpoint: The Local Endpoint represents the application's
name for itself that it uses for transport connections.  For
example, a local IP address and port.
Paragraph (version B):
Path Selection Properties: The Path Selection Properties consist
of the options that an application may set to influence the
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.
Paragraph (version B):
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
of generic transport protocol features.  These options can take
the form of requirements, prohibitions, and preferences.  Examples
include reliability, service class, multipath support, and fast
open support.
Paragraph (version A):
Specific Protocol Properties: The Specific Protocol Properties
refer to the subset of Protocol Properties options that apply to a
single protocol (transport protocol, IP, or security protocol).
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
should be used.
Paragraph (version A):
Initiate is the primary action that an application can take to
create a Connection to a remote endpoint, and prepare any required
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
state.  The process of identifying options for connecting, such as
resolution of the Remote Endpoint, occurs in response the Initiate
call.
Paragraph (version B):
Specific Protocol Properties: The Specific Protocol Properties
refer to the subset of Protocol Properties options that apply to a
single protocol (transport protocol, IP, or security protocol).
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
should then be used..
Paragraph (version B):
Initiate: The primary action that an application can take to
create a Connection to a Remote Endpoint, and prepare any required
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
state.  The process of identifying options for connecting, such as
resolution of the Remote Endpoint, occurs in response the Initiate
call.
Paragraph (version A):
Listen is the action of marking a Listener as willing to accept
incoming Connections.  The Listener will then create Connection
objects as incoming connections are accepted (events).
Paragraph (version A):
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
connection from that endpoint.  This corresponds, for example, to
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.
Paragraph (version B):
Listen: The action of marking a Listener as willing to accept
incoming Connections.  The Listener will then create Connection
objects as incoming connections are accepted (events).
Paragraph (version B):
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
connection from that endpoint.  This corresponds, for example, to
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.
Paragraph (version A):
Message: A Message object is a unit of data that can be
represented as bytes that can be transferred between two endpoints
over a transport connection.  The bytes within a Message are
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
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.
Paragraph (version A):
Send is the action to transmit a Message or partial Message over a
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).
Paragraph (version A):
Receive is an action that indicates that the application is ready
to asynchronously accept a Message over a Connection from a Remote
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
application.
Paragraph (version B):
Message: A Message object is a unit of data that can be
represented as bytes that can be transferred between two endpoints
over a transport connection.  The bytes within a Message are
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
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.
Paragraph (version B):
Send: The action to transmit a Message or partial Message over a
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).
Paragraph (version B):
Receive: An action that indicates that the application is ready to
asynchronously accept a Message over a Connection from a Remote
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
application.
Paragraph (version A):
Close is the action an application may take on a Connection to
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.
Paragraph (version A):
Abort is an action the application may take on a Connection to
indicate a Close, but with the additional indication that the
transport system should not attempt to deliver any outstanding
data.
Paragraph (version B):
Close: The action an application may take on a Connection to
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.
Paragraph (version B):
Abort: The action the application may take on a Connection to
indicate a Close, but with the additional indication that the
transport system should not attempt to deliver any outstanding
data.
Paragraph (version A):
The Transport System Implementation Concepts define the set of
objects used internally to a system or library to provide the
functionality of transport networking, as required by the abstract
interface.
Paragraph (version A):
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.
Paragraph (version A):
Path: A Path represents an available set of properties of a
network route on which packets may be sent or received.
Paragraph (version A):
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.
Paragraph (version A):
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).
Paragraph (version A):
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
Connections, or only certain ones depending on the runtime context
and properties of the Connection.
Paragraph (version A):
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.
Paragraph (version B):
The Transport System Implementation Concepts define the set of
objects used internally to a system or library to provide the
functionality required to provide a transport service across a
network, as required by the abstract interface.
Paragraph (version B):
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.
Paragraph (version B):
Path: Represents an available set of properties that a Local
Endpoint may use to send or receive packets with a Remote
Endpoint.
Paragraph (version B):
Protocol Instance: A single instance of one protocol, including
any state it has necessary to establish connectivity or send and
receive Messages.
Paragraph (version B):
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).
Paragraph (version B):
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).
Paragraph (version B):
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).
Paragraph (version B):
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
Connections, or only certain ones depending on the runtime context
and properties of the Connection.
Paragraph (version B):
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.