Draft: draft-ietf-taps-arch

Commentary: A complete arch . read - through , leading to a couple of nit fixes and other minor suggestions
Paragraph (version A):
This document proposal an architecture for exposing transport
protocol features to applications for network communication, the
Transport Services architecture.  In contrast to what is provided by
most existing Application Programming Interfaces (APIs), Transport
Services is based on an asynchronous, event-driven interaction
pattern; it uses messages for representing data transfer to
applications; and it assumes an implementation that can use multiple
IP addresses, multiple protocols, and multiple paths, and provide
multiple application streams.  This document further defines common
terminology and concepts to be used in definitions of Transport
Services APIs and implementations.
Paragraph (version B):
This document describes an architecture for exposing transport
protocol features to applications for network communication, the
Transport Services architecture.  The Transport Services Application
Programming Interface (API) is based on an asynchronous, event-driven
interaction pattern.  It uses messages for representing data transfer
to applications, and it assumes an implementation that can use
multiple IP addresses, multiple protocols, and multiple paths, and
provide multiple application streams.  This document further defines
common terminology and concepts to be used in definitions of
Transport Services APIs and implementations.
Paragraph (version A):
This document is developed in parallel with the specification of the
Transport Services API I-D.ietf-taps-interface and Implementation
Guidelines I-D.ietf-taps-impl.  Although following the Transport
Services Architecture does not require that all APIs and
implementations are identical, a common minimal set of features
represented in a consistent fashion will enable applications to be
easily ported from one system to another.
Paragraph (version B):
This document was developed in parallel with the specification of the
Transport Services API I-D.ietf-taps-interface and Implementation
Guidelines I-D.ietf-taps-impl.  Although following the Transport
Services Architecture does not require that all APIs and
implementations are identical, a common minimal set of features
represented in a consistent fashion will enable applications to be
easily ported from one system to another.
Paragraph (version A):
design explains the design principles that guide the Transport
Services API.  These principles are intended to make sure that
transport protocols can continue to be enhanced and evolve without
requiring too many changes by application developers.
Paragraph (version B):
design explains the design principles behind the Transport
Services API.  These principles are intended to make sure that
transport protocols can continue to be enhanced and evolve without
requiring too many changes by application developers.
Paragraph (version A):
There are key differences between the architecture of the Transport
Services system and the architecture of the sockets API: it presents
an asynchronous, event-driven API; it uses messages for representing
data transfer to applications; and it assumes an implementation that
can use multiple IP addresses, multiple protocols, multiple paths,
and provide multiple application streams.
Paragraph (version B):
There are key differences between the architecture of the Transport
Services system and the architecture of the sockets API: the
Transport Services API is asynchronous and event-driven; it uses
messages for representing data transfer to applications, and it
assumes an implementation that can use multiple IP addresses,
multiple protocols, multiple paths, and provide multiple application
streams.
Paragraph (version A):
The Transport Services API represents data as messages, so that it
more closely matches the way applications use the network.  Messages
seamlessly work with transport protocols that support datagrams or
records, but can also be used over a stream by defining an
application-layer framer datatransfer.  When framing protocols are
placed on top of unstructured streams, the messages used in the API
represent the framed messages within the stream.  In the absence of a
framer, protocols that deal only in byte streams, such as TCP,
represent their data in each direction as a single, long message.
Paragraph (version B):
The Transport Services API represents data as messages, so that it
more closely matches the way applications use the network.  Messages
seamlessly work with transport protocols that support datagrams or
records, but can also be used over a stream by defining an
application-layer framer (datatransfer).  When framing protocols are
placed on top of unstructured streams, the messages used in the API
represent the framed messages within the stream.  In the absence of a
framer, protocols that deal only in byte streams, such as TCP,
represent their data in each direction as a single, long message.
Paragraph (version A):
The diagram below provides a high-level view of the actions and
events during the lifetime of a connection.  Note that some actions
are alternatives (e.g., whether to initiate a connection or to listen
for incoming connections), others are optional (e.g., setting
Connection and Message Properties in Pre-Establishment), or have been
omitted for brevity.
Paragraph (version B):
The diagram below provides a high-level view of the actions and
events during the lifetime of a connection.  Note that some actions
are alternatives (e.g., whether to initiate a connection or to listen
for incoming connections), while others are optional (e.g., setting
Connection and Message Properties in Pre-Establishment) or have been
omitted for brevity.
Paragraph (version A):
Connection: A Connection object represents one or more active
transport protocol instances that can send and/or receive Messages
between local and remote systems.  It holds state pertaining to
the underlying transport protocol instances and any ongoing data
transfers.  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.  It can also
represent a pool of transport protocol instance, e.g., a set of
TCP and QUIC connections to equivalent endpoints, or a stream of a
multi-streaming transport protocol instance.
Paragraph (version B):
Connection: A Connection object represents one or more active
transport protocol instances that can send and/or receive Messages
between local and remote systems.  It holds state pertaining to
the underlying transport protocol instances and any ongoing data
transfers.  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.  It can also
represent a pool of transport protocol instances, e.g., a set of
TCP and QUIC connections to equivalent endpoints, or a stream of a
multi-streaming transport protocol instance.
Paragraph (version A):
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 enable the transmission of Messages.  For
some protocols, this will initiate a client-to-server style
handshake; for other protocols, this will 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):
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 enable the transmission of Messages.  For
some protocols, this will initiate a client-to-server style
handshake; for other protocols, this will just establish local
state.  The process of identifying options for connecting, such as
resolution of the Remote Endpoint, occurs in response to the
Initiate call.
Paragraph (version A):
Message Properties: Message Properties can be used to annotate
specific Messages.  These properties might only apply to how
Message is sent (such as how the transport will treat
prioritization and reliability), but can also include properties
that specific protocols encode and communicate to the Remote
Endpoint.  Message Properties MAY be set on a Preconnection to
define default properties for sending.  When receiving Messages,
Message Properties can contain information about the received
Message, such as metadata generated at the receiver and
information signalled by the remote endpoint.
Paragraph (version B):
Message Properties: Message Properties can be used to annotate
specific Messages.  These properties might only apply to how a
Message is sent (such as how the transport will treat
prioritization and reliability), but can also include properties
that specific protocols encode and communicate to the Remote
Endpoint.  Message Properties MAY be set on a Preconnection to
define default properties for sending.  When receiving Messages,
Message Properties can contain information about the received
Message, such as metadata generated at the receiver and
information signalled by the remote endpoint.
Paragraph (version A):
Path Selection: Path Selection represents the act of choosing one
or more paths that are available to use based on the Selection
Properties provided by the application, the policies and
heuristics of a Transport Services system.
Paragraph (version B):
Path Selection: Path Selection represents the act of choosing one
or more paths that are available to use based on the Selection
Properties provided by the application, and the policies and
heuristics of a Transport Services system.