Draft: draft-ietf-taps-impl

Commentary: These are mostly wording changes for clarification . Feel free to cherry pick . 
 Ca n't find any problems here - this looks good . 
 This LGTM , many thanks !
Paragraph (version A):
Connection objects represent the interface between the application
and the implementation to manage transport state, and conduct data
transfer.  During the process of establishment (conn-establish), the
Connection will be unbound to a specific transport flow, since there
may be multiple candidate Protocol Stacks being raced.  Once the
Connection is established, the object should be considered mapped to
a specific Protocol Stack.  The notion of a Connection maps to many
different protocols, depending on the Protocol Stack.  For example,
the Connection may ultimately represent the interface into a TCP
connection, a TLS session over TCP, a UDP flow with fully-specified
local and remote endpoints, a DTLS session, a SCTP stream, a QUIC
stream, or an HTTP/2 stream.
Paragraph (version B):
Connection objects represent the interface between the application
and the implementation to manage transport state, and conduct data
transfer.  During the process of establishment (conn-establish), the
Connection will be unbound to a specific transport flow, since there
may be multiple candidate Protocol Stacks being raced.  Once the
Connection is established, its interface maps actions and events to
the details of the chosen Protocol Stack.  For example, the same
Connection object may ultimately represent the interface into a TCP
connection, a TLS session over TCP, a UDP flow with fully-specified
local and remote endpoints, a DTLS session, a SCTP stream, a QUIC
stream, or an HTTP/2 stream.
Paragraph (version A):
During pre-establishment the application specifies the Endpoints to
be used for communication as well as its preferences via Selection
Properties and, if desired, also Connection Properties.  Generally,
Connection Properties should be configured as early as possible,
because they can serve as input to decisions that are made by the
implementation (e.g., the Capacity Profile can guide usage of a
protocol offering scavenger-type congestion control).
Paragraph (version B):
During pre-establishment the application specifies one or more
Endpoints to be used for communication as well as protocol
preferences and constraints via Selection Properties and, if desired,
also Connection Properties.  Generally, Connection Properties should
be configured as early as possible, because they can serve as input
to decisions that are made by the implementation (e.g., the Capacity
Profile can guide usage of a protocol offering scavenger-type
congestion control).
Paragraph (version A):
Branching between paths is the first in the list because results
across multiple interfaces are likely not related to one another:
endpoint resolution may return different results, especially when
using locally resolved host and service names, and which protocols
are supported and preferred may differ across interfaces.  Thus, if
multiple paths are attempted, the overall connection can be seen as a
race between the available paths or interfaces.
Paragraph (version B):
where a lower number indicates higher precedence and therefore higher
placement in the tree.  Branching between paths is the first in the
list because results across multiple interfaces are likely not
related to one another: endpoint resolution may return different
results, especially when using locally resolved host and service
names, and which protocols are supported and preferred may differ
across interfaces.  Thus, if multiple paths are attempted, the
overall connection can be seen as a race between the available paths
or interfaces.
Paragraph (version A):
For protocol stacks with multiple handshakes, the decision becomes
more nuanced.  If the protocol stack involves both TLS and TCP, an
implementation could determine that a leaf node is connected after
the TCP handshake is complete, or it can wait for the TLS handshake
to complete as well.  The benefit of declaring completion when the
TCP handshake finishes, and thus stopping the race for other branches
of the tree, is that there will be less burden on the network from
other connection attempts.  On the other hand, by waiting until the
TLS handshake is complete, an implementation avoids the scenario in
which a TCP handshake completes quickly, but TLS negotiation is
either very slow or fails altogether in particular network conditions
or to a particular endpoint.  To avoid the issue of TLS possibly
failing, the implementation should not generate a Ready event for the
Connection until TLS is established.
Paragraph (version B):
For protocol stacks with multiple handshakes, the decision becomes
more nuanced.  If the protocol stack involves both TLS and TCP, an
implementation could determine that a leaf node is connected after
the TCP handshake is complete, or it can wait for the TLS handshake
to complete as well.  The benefit of declaring completion when the
TCP handshake finishes, and thus stopping the race for other branches
of the tree, is reduced burden on the network and remote endpoints
from further connection attempts that are likely to be abandoned.  On
the other hand, by waiting until the TLS handshake is complete, an
implementation avoids the scenario in which a TCP handshake completes
quickly, but TLS negotiation is either very slow or fails altogether
in particular network conditions or to a particular endpoint.  To
avoid the issue of TLS possibly failing, the implementation should
not generate a Ready event for the Connection until TLS is
established.
Paragraph (version A):
Connected protocols such as TCP and TLS-over-TCP have a strong
mapping between the Local and Remote Endpoints (five-tuple) and their
protocol connection state.  These map into Connection objects.
Whenever a new inbound handshake is being started, the Listener
should generate a new Connection object and pass it to the
application.
Paragraph (version B):
Connected protocols such as TCP and TLS-over-TCP have a strong
mapping between the Local and Remote Endpoints (four-tuple) and their
protocol connection state.  These map into Connection objects.
Whenever a new inbound handshake is being started, the Listener
should generate a new Connection object and pass it to the
application.
Paragraph (version A):
Unconnected protocols such as UDP and UDP-lite generally do not
provide the same mechanisms that connected protocols do to offer
Connection objects.  Implementations should wait for incoming packets
for unconnected protocols on a listening port and should perform
five-tuple matching of packets to either existing Connection objects
or the creation of new Connection objects.  On platforms with
facilities to create a "virtual connection" for unconnected protocols
implementations should use these mechanisms to minimise the handling
of datagrams intended for already created Connection objects.
Paragraph (version B):
Unconnected protocols such as UDP and UDP-lite generally do not
provide the same mechanisms that connected protocols do to offer
Connection objects.  Implementations should wait for incoming packets
for unconnected protocols on a listening port and should perform
four-tuple matching of packets to either existing Connection objects
or the creation of new Connection objects.  On platforms with
facilities to create a "virtual connection" for unconnected protocols
implementations should use these mechanisms to minimise the handling
of datagrams intended for already created Connection objects.
Paragraph (version A):
Protocols that provide multiplexing of streams into a single five-
tuple can listen both for entirely new connections (a new HTTP/2
stream on a new TCP connection, for example) and for new sub-
connections (a new HTTP/2 stream on an existing connection).  If the
abstraction of Connection presented to the application is mapped to
the multiplexed stream, then the Listener should deliver new
Connection objects in the same way for either case.  The
implementation should allow the application to introspect the
Connection Group marked on the Connections to determine the grouping
of the multiplexing.
Paragraph (version B):
Protocols that provide multiplexing of streams into a single four-
tuple can listen both for entirely new connections (a new HTTP/2
stream on a new TCP connection, for example) and for new sub-
connections (a new HTTP/2 stream on an existing connection).  If the
abstraction of Connection presented to the application is mapped to
the multiplexed stream, then the Listener should deliver new
Connection objects in the same way for either case.  The
implementation should allow the application to introspect the
Connection Group marked on the Connections to determine the grouping
of the multiplexing.
Paragraph (version A):
An implementation should use this information, when possible, to
determine preference between candidate paths, endpoints, and protocol
options.  Eligible options that historically had significantly better
performance than others should be selected first when gathering
candidates (see gathering) to ensure better performance for the
application.
Paragraph (version B):
An implementation should use this information, when possible, to
influence preference between candidate paths, endpoints, and protocol
options.  Eligible options that historically had significantly better
performance than others should be selected first when gathering
candidates (see gathering) to ensure better performance for the
application.