Draft: draft-pauly-taps-arch

Commentary: Incorporate Preconnection into the architecture and API draft . 
 Looks good . I pushed a commit to complete the change of the list style to include the implementation concepts section .
Paragraph (version A):
A Connection is the fundamental object used by an application
for all interaction with a peer and data transfer.  It is
generally capable of bi-directional communication.  It has
state that represents the capability of being able to send or
receive content between its local and remote endpoints.  This
capability may be based merely on the existence of a path
between the two endpoints and an application's permission to
send and receive on its local endpoint; or may represent
successful protocol handshakes at one or more layers that are
pre-requisites to receiving content.
Paragraph (version A):
A Listener is any object that can be used to prepare a
Connection with a remote endpoint without initiation by the
local application.  That is, it can passively accept
initiations for Connections made by another endpoint.
Paragraph (version A):
An Endpoint represents one side of a transport connection.  It
is a concept that represents how an application views itself or
a peer that may vary in levels of specificity.  Examples
include "IP address + port", "hostname + port", and "DNS
service name".
Paragraph (version A):
The Remote Endpoint in a properties [MICHAEL: I can't parse "in
a properties" here.  Should this be removed?] represents the
application's view of a peer that can participate in a
transport connection.
Paragraph (version A):
The Local Endpoint in a properties [MICHAEL: I can't parse "in
a properties" here.  Should this be removed?] represents the
application's view of itself that it wants to use for transport
connections.  This may be optional, or may be generic (a wild
card address, for example).
Paragraph (version A):
Path Selection Properties consist of the options that an
application may set to influence the selection of path 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 expected
throughput or latency.
Paragraph (version A):
Protocol Selection Properties consist of the options that an
application may set to influence the selection of transport
protocol, 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 A):
Specific Protocol Properties refers 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, but that if this protocol is employed, a
particular set of options should be used.  This is critical to
allow compatibility with Protocol Properties on peers.
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 content.  For some protocols, this may initiate a
server-to-client style handshake; for other protocols, this may
just establish local state; and for peer-to-peer protocols,
this may begin the process of a simultaneous open.
Paragraph (version A):
Listen is the action of marking a Listener as willing to accept
incoming Connections.
Paragraph (version A):
Content 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 unit of Content are assumed to
be ordered within the unit itself.  That is, 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 units of Content.  Content may or may not be usable
if incomplete or corrupted.  Boundaries of Content may or may
not be understood or transmitted by transport protocols.  That
is, what one application considers to be two units of Content
sent on a stream-based transport may be treated as a single
unit of Content by the application on the other side.
Paragraph (version A):
Send is the action to transmit Content over a Connection to a
remote endpoint.  The interface to Send may include options
specific to how this 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 the indication that the application is ready to
asynchronously accept Content over a Connection from a Remote
Endpoint, while the Content itself will be delivered in an
event events.  The interface to Receive may include options
specific to the Content that is to be delivered to the
application.
Paragraph (version B):
Preconnection: A Preconnection object is a representation of a
potential connection.  It has state that describes parameters of a
Connection that might exist in the future: the Local Endpoint from
which that Connection will be established, the Remote Endpoint to
which it will connect, and Path Selection Properties, Protocol
Selection Properties, and Specific Protocol Properties that
influence the choice of transport that Connection will use.  A
Preconnection can be fully specified and represent a single
possible Connection, or it can be partially specified such that it
represents a family of possible Connections.  The Local Endpoint
MUST be specified if the Preconnection is used to Listen() for
incoming connections, but is OPTIONAL if it is used to Initiate()
connections.  The Remote Endpoint MUST be specified in the
Preconnection is used to Initiate() connections, but is OPTIONAL
if it is used to Listen() for incoming connections.
Paragraph (version B):
Connection: A Connection object represents an active transport
protocol instance that can send and/or receive Content between a
Local Endpoint and a Remote Endpoint.  It holds state pertaining
to the underlying transport protocol instance and any ongoing data
transfer.  This represents, for example, an active connection in a
connection-oriented protocol such as TCP, or a fully-specified
5-tuple for a connectionless protocol such as UDP.
Paragraph (version B):
Listener: A Listener object accepts incoming transport protocol
connections from Remote Endpoints and generates corresponding
Connection objects.  It is created from a Preconnection object
that specifies the type of incoming connections it will accept.
Paragraph (version B):
Endpoint: An Endpoint represents one side of a transport
connection.  It is a concept that represents how an application
views itself or a peer that may vary in levels of specificity.
Examples include "IP address + port", "hostname + port", and "DNS
service name".
Paragraph (version B):
Remote Endpoint: The Remote Endpoint represents the application's
name for a peer that can participate in a transport connection.
For example, a DNS name for the peer.
Paragraph (version B):
Local Endpoint: The Local Endpoint represents the application's
name for itself that it wants to use for transport connections.
For example, a local interface name or address.
Paragraph (version B):
Path Selection Properties: The Path Selection Properties consist
of the options that an application may set on a Preconnection to
influence the selection of path 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 expected throughput or latency.
Paragraph (version B):
Protocol Selection Properties: The Protocol Selection Properties
consist of the options that an application may set on a
Preconnection to influence the selection of transport protocol,
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):
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 on a Preconnection does not
necessarily require that a specific protocol must be used when a
Connection is established from that Preconnection, but that if
this protocol is employed, a particular set of options should be
used.  This is critical to allow compatibility with Protocol
Properties on peers.
Paragraph (version B):
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 content.
For some protocols, this may initiate a server-to-client style
handshake; for other protocols, this may just establish local
state; and for peer-to-peer protocols, this may begin the process
of a simultaneous open.  The Initiate() action consumes a
Preconnection object and creates a Connection object.  Resolution
of the remote endpoint identifier occurs during the Initiate()
call.
Paragraph (version B):
Listen() is the action of marking a Listener as willing to accept
incoming Connections.  It consumes a Preconnection object.  The
Listener will then create Connection objects as incoming
connections are accepted.
Paragraph (version B):
Content: A Content 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 unit of Content
are assumed to be ordered within the unit itself.  That is, 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 units of Content.  Content may or may not be usable if
incomplete or corrupted.  Boundaries of Content may or may not be
understood or transmitted by transport protocols.  That is, what
one application considers to be two units of Content sent on a
stream-based transport may be treated as a single unit of Content
by the application on the other side.
Paragraph (version B):
Send() is the action to transmit Content over a Connection to a
remote endpoint.  The interface to Send may include options
specific to how this 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() is an action that indicates that the application is
ready to asynchronously accept Content over a Connection from a
Remote Endpoint, while the Content itself will be delivered in an
event events.  The interface to Receive may include options
specific to the Content that is to be delivered to the
application.
Paragraph (version A):
A Connection Ready event signals to an application that a given
Connection is ready to send and/or receive Content.  If the
Connection relies on handshakes to establish state between
peers, then it is assumed that these steps have been taken.
Paragraph (version A):
A Connection Finished event signals to an application that a
given Connection is no longer usable for sending or receiving
Content.  This should deliver a useful error to the
application.
Paragraph (version A):
A Connection Received event signals to an application that a
given Listener has passively received a Connection.
Paragraph (version A):
A Content Received event delivers received content to the
application, based on a Receive action.  This may include an
error if the action failed.
Paragraph (version A):
A Content Sent event notifies the application of the status of
its Send action.  This may be an error, an indication that
Content has been processed by the protocol stack, or
potentially [MICHAEL: Why "potentially" - because you're not
sure about it?  If it may be such an indication, "potentially"
should be removed (this seems like the right thing to do for
me).] an indication that Content has been acknowledged by a
peer.
Paragraph (version A):
A Path Properties Changed event notifies the application that
some property of the Connection has changed that may influence
how and where data is sent and/or received.
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):
Connection Ready: A Connection Ready event signals to an
application that a given Connection is ready to send and/or
receive Content.  If the Connection relies on handshakes to
establish state between peers, then it is assumed that these steps
have been taken.
Paragraph (version B):
Connection Finished: A Connection Finished event signals to an
application that a given Connection is no longer usable for
sending or receiving Content.  This should deliver a useful error
to the application.
Paragraph (version B):
Connection Received: A Connection Received event signals to an
application that a given Listener has passively received a
Connection.
Paragraph (version B):
Content Received: A Content Received event delivers received
content to the application, based on a Receive action.  This may
include an error if the action failed.
Paragraph (version B):
Content Sent: A Content Sent event notifies the application of the
status of its Send action.  This may be an error, an indication
that Content has been processed by the protocol stack, or
potentially [MICHAEL: Why "potentially" - because you're not sure
about it?  If it may be such an indication, "potentially" should
be removed (this seems like the right thing to do for me).] an
indication that Content has been acknowledged by a peer.
Paragraph (version B):
Path Properties Changed: A Path Properties Changed event notifies
the application that some property of the Connection has changed
that may influence how and where data is sent and/or received.
Paragraph (version B):
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 B):
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 A):
For multiplexing transport protocols, a Connection Group is a
set of Connections that can be multiplexed together.
Paragraph (version A):
A Path represents an available set of properties of a network
route on which packets may be sent or received.
Paragraph (version A):
A Protocol Instance is a single instance of one protocol,
including any state it has necessary to establish connectivity
or send and receive content.
Paragraph (version A):
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 content.  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):
A Transport Service System Policy defines the algorithm it uses
to take connection properties from the application, and
determine how it will gather candidate paths and protocols
gathering and race the candidates during establishment racing.
Paragraph (version A):
The Association Cache holds the state 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 A):
Protocol Racing is the act of attempting, or scheduling
attempts for, multiple Protocol Stacks that differ based on the
composition of protocols or the options used for protocols.
Paragraph (version A):
Path Racing is the act of attempting, or scheduling attempts
for, multiple Protocol Stacks that differ based on a selection
from the available Paths.
Paragraph (version A):
Endpoint Racing is the act of attempting, or scheduling
attempts for, multiple Protocol Stacks that differ based on the
specific representation of the remote and local endpoints, such
as IP addresses resolved from a DNS hostname.
Paragraph (version B):
Connection Group: For multiplexing transport protocols, a
Connection Group is a set of Connections that can be multiplexed
together.
Paragraph (version B):
Path: A Path represents an available set of properties of a
network route on which packets may be sent or received.
Paragraph (version B):
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 content.
Paragraph (version B):
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 content.  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):
System Policy: A Transport Service System Policy defines the
algorithm it uses to take connection properties from the
application, and determine how it will gather candidate paths and
protocols gathering and race the candidates during establishment
racing.
Paragraph (version B):
Association Cache: The Association Cache holds the state 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):
Path Selection: Path Selection represents the act of choosing one
or more paths that are available to use based on the Path
Selection Properties provided by the application, and a Transport
Services system's policies and heuristics.
Paragraph (version B):
Protocol Selection: Protocol Selection represents the act of
choosing one or more sets of protocol options that are available
to use based on the Protocol Properties provided by the
application, and a Transport Services system's policies and
heuristics.
Paragraph (version B):
Protocol Option Racing: Protocol Racing is the act of attempting
to establish, or scheduling attempts to establish, multiple
Protocol Stacks that differ based on the composition of protocols
or the options used for protocols.
Paragraph (version B):
Path Racing: Path Racing is the act of attempting to establish, or
scheduling attempts to establish, multiple Protocol Stacks that
differ based on a selection from the available Paths.
Paragraph (version B):
Endpoint Racing: Endpoint Racing is the act of attempting to
establish, or scheduling attempts to establish, multiple Protocol
Stacks that differ based on the specific representation of the
remote and local endpoints, such as IP addresses resolved from a
DNS hostname.