Draft: draft-ietf-taps-interface

Commentary: ( Gracefully , he he :) ) 
 Ah , I see , sorry ! I just committed a fix ; is it better now ? The new text describing the Closed Event is only this : 
 Still , it says that this means either everything has been delivered , or the peer has closed the connection . Does this mean I would get two events on a clean TCP close ? 
 No , one : because the Connection was " closed " . Case 1 in the sentence , where it says " Close Action " , refers to the call made by the local application - the application made the call , and it terminated correctly . The remote close is the other case leading to a Connection being closed - since it does n't say " abort " or " forcefully closed " , it 's the same thing , a graceful close . So ... there are two reasons leading to one thing happening , and when that one thing is over , the applications gets an Event . I 'm not sure how you read this differently ... it 's clear to me . Would this variant help ? 
 I 've read this again , and I think it 's OK . 
 Can we explain in the start of the connection termination section a specific list of the different end states / events a connection can have ? ( Either Closed or ConnectionError , for example ) . 
 Note to self : also add some introductory text for this section as requested by in : " This section would benefit from some introductory sentences on the different ways to terminate a connection , i.e. local and remote actions and Connection errors . " 
 Done - please take a look at the new intro . 
 This section would benefit from some introductory sentences on the different ways to terminate a connection , i.e. local and remote actions and Connection errors . 
 these are analogous to connection - level things that generate events . 
 We can clarify that Close / Abort causes an event on the connection . We should also state that CloseGroup / AbortGroup causes same the event on all Connections that are grouped . Close -Closed CloseGroup -Closed x N Abort -ConnectionError(aborted ) AbortGroup -ConnectionError(aborted ) x N 
 A couple of minor queriesI am still missing a clear statement whether a developer can rely on eventually receiving either a Closed event or a ConnectionError event per Connection . From this text I still do n't understand when TAPS sends Closed < . Is it ( 1 ) in response to a Close ( ) , when all data has been delivered , or when the remote endpoint has closed ? Is it the first of these two events to occur ?
Paragraph (version B):
It derives specific path and protocol selection properties and
supported transport features from the analysis provided in RFC8095,
RFC8923, and RFC8922.  The design encourages implementations
underneath the interface to dynamically choose a transport protocol
depending on an application's choices rather than statically binding
applications to a protocol at compile time.  Nevertheless, the
Transport Services API also provides applications with a way to
override transport selection and instantiate a specific stack, e.g.,
to support servers wishing to listen to a specific protocol.
However, forcing a specific transport stack choice is discouraged for
general use, because it can reduce portability.
Paragraph (version A):
Explicit support for transport-specific features to be applied
should that particular transport be part of a chosen Protocol
Stack.
Paragraph (version A):
An application primarily interacts with this API through two Objects:
Preconnections and Connections.  A Preconnection represents a set of
properties and constraints on the selection and configuration of
paths and protocols to establish a Connection with a Remote Endpoint.
A Connection represents a transport Protocol Stack on which data can
be sent to and/or received from a Remote Endpoint (i.e., depending on
the kind of transport, connections can be bi-directional or
unidirectional).  Connections can be created from Preconnections in
three ways: by initiating the Preconnection (i.e., actively opening,
as in a client), through listening on the Preconnection (i.e.,
passively opening, as in a server), or rendezvousing on the
Preconnection (i.e.  peer to peer establishment).
Paragraph (version A):
Once a Connection is established, data can be sent and received on it
in the form of Messages.  The interface supports the preservation of
message boundaries both via explicit Protocol Stack support, and via
application support through a Message Framer which finds message
boundaries in a stream.  Messages are received asynchronously through
event handlers registered by the application.  Errors and other
notifications also happen asynchronously on the Connection.  It is
not necessary for an application to handle all Events; some Events
may have implementation-specific default handlers.  The application
should not assume that ignoring Events (e.g., Errors) is always safe.
Paragraph (version B):
An application primarily interacts with this API through two Objects:
Preconnections and Connections.  A Preconnection represents a set of
properties and constraints on the selection and configuration of
paths and protocols to establish a Connection with a Remote Endpoint.
A Connection represents an instance of a transport Protocol Stack on
which data can be sent to and/or received from a Remote Endpoint
(i.e., depending on the kind of transport, connections can be bi-
directional or unidirectional).  Connections can be created from
Preconnections in three ways: by initiating the Preconnection (i.e.,
actively opening, as in a client), through listening on the
Preconnection (i.e., passively opening, as in a server), or
rendezvousing on the Preconnection (i.e.  peer to peer
establishment).
Paragraph (version B):
Once a Connection is established, data can be sent and received on it
in the form of Messages.  The interface supports the preservation of
message boundaries both via explicit Protocol Stack support, and via
application support through a Message Framer that finds message
boundaries in a stream.  Messages are received asynchronously through
event handlers registered by the application.  Errors and other
notifications also happen asynchronously on the Connection.  It is
not necessary for an application to handle all Events; some Events
may have implementation-specific default handlers.  The application
should not assume that ignoring Events (e.g., Errors) is always safe.
Paragraph (version B):
A new Connection created by Clone can have a Message Framer assigned
via the optional "framer" parameter of the Clone Action.  If this
parameter is not supplied, the stack of Message Framers associated
with a Connection is copied to the cloned Connection when calling
Clone.  Then, a cloned Connection has the same stack of Message
Framers as the Connection from which they are Cloned, but these
Framers may internally maintain per-Connection state.
Paragraph (version B):
If the underlying protocol supports multi-streaming, it is natural to
use this functionality to implement Clone.  In that case, Connections
in a Connection Group are multiplexed together, giving them similar
treatment not only inside endpoints, but also across the end-to-end
Internet path.
Paragraph (version B):
Note that calling Clone() can result in on-the-wire signaling, e.g.,
to open a new transport connection, depending on the underlying
Protocol Stack.  When Clone() leads to the opening of multiple such
connections, the Transport Services system will ensure consistency of
Connection Properties by uniformly applying them to all underlying
connections in a group.  Even in such a case, there are possibilities
for a Transport Services system to implement prioritization within a
Connection Group TCP-COUPLING RFC8699.
Paragraph (version B):
The application expects to send/receive data at a constant rate
after Connection establishment.  Delay and delay variation should
be minimized at the expense of efficient use of the available
capacity.  This implies that the Connection might fail if the Path
is unable to maintain the desired rate.  A transport can interpret
this capacity profile as preferring a circuit breaker RFC8084 to a
rate-adaptive congestion controller.  Transport system
implementations that map the requested capacity profile onto per-
connection DSCP signaling without multiplexing SHOULD assign a
DSCP Assured Forwarding (AF31,AF32,AF33,AF34) RFC2597 PHB.
Paragraph (version B):
When set to true, this property will initiate new Connections using
as little cached information (such as session tickets or cookies) as
possible from previous connections that are not in the same
Connection Group.  Any state generated by this Connection will only
be shared with Connections in the same Connection Group.  Cloned
Connections will use saved state from within the Connection Group.
This is used for separating Connection Contexts as specified in I-
D.ietf-taps-arch.
Paragraph (version A):
This property, if applicable, represents the maximum Message size
that can be sent without incurring network-layer fragmentation or
transport layer segmentation at the sender.  It exposes the Maximum
Packet Size (MPS) as described in Datagram PLPMTUD I-D.ietf-tsvwg-
datagram-plpmtud.
Paragraph (version B):
This property, if applicable, represents the maximum Message size
that can be sent without incurring network-layer fragmentation or
transport layer segmentation at the sender.  It exposes the Maximum
Packet Size (MPS) as described in Datagram PLPMTUD RFC8899.
Paragraph (version B):
This property specifies the priority of a Message, relative to other
Messages sent over the same Connection.
Paragraph (version B):
The Expired Event occurs when a previous Send Action expired before
completion; i.e. when the Message was not sent before its Lifetime
(see msg-lifetime) expired.  This is separate from SendError, as it
is an expected behavior for partially reliable transports.  The
Expired Event contains a reference to the Message Context of the
Message to which it applies.
Paragraph (version B):
A SendError occurs when a Message was not sent due to an error
condition: an attempt to send a Message which is too large for the
system and Protocol Stack to handle, some failure of the underlying
Protocol Stack, or a set of Message Properties not consistent with
the Connection's transport properties.  The SendError contains a
reference to the Message Context of the Message to which it applies.
Paragraph (version B):
A Transport Services system gives no guarantees about how its
expression of relative priorities will be realized.  However, the
Transport Services system will seek to ensure that performance of
relatively-prioritized connections and messages is not worse with
respect to those connections and messages than an equivalent
configuration in which all prioritization properties are left at
their defaults.
Paragraph (version A):
The Closed Event informs the application that the Remote Endpoint has
closed the Connection.  There is no guarantee that a remote Close
will indeed be signaled.
Paragraph (version A):
A ConnectionError informs the application that: 1) data could not be
delivered to the peer after a timeout, or 2) the Connection has been
aborted (e.g., because the peer has called Abort).  There is no
guarantee that an Abort will indeed be signaled.
Paragraph (version B):
A Connection can be terminated i) by the Local Endpoint (i.e., the
application calls the Close, CloseGroup, Abort or AbortGroup Action),
ii) by the Remote Endpoint (i.e., the remote application calls the
Close, CloseGroup, Abort or AbortGroup Action), or iii) because of an
error (e.g., a timeout).  A local call of the Close Action will cause
the Connection to either send a Closed Event or a ConnectionError
Event, and a local call of the CloseGroup Action will cause all of
the Connections in the group to either send a Closed Event or a
ConnectionError Event.  A local call of the Abort Action will cause
the Connection to send a ConnectionError Event, indicating local
Abort as a reason, and a local call of the AbortGroup Action will
cause all of the Connections in the group to send a ConnectionError
Event, indicating local Abort as a reason.
Paragraph (version B):
Remote Action calls map to Events similar to local calls (e.g., a
remote Close causes the Connection to either send a Closed Event or a
ConnectionError Event), but, different from local Action calls, it is
not guaranteed that such Events will indeed be invoked.  When an
application needs to free resources associated with a Connection, it
should therefore not rely on the invocation of such Events due to
termination calls from the Remote Endpoint, but instead use the local
termination Actions.
Paragraph (version B):
Close terminates a Connection after satisfying all the requirements
that were specified regarding the delivery of Messages that the
application has already given to the Transport Services system.  Upon
successfully satisfying all these requirements, the Connection will
send the Closed Event.  For example, if reliable delivery was
requested for a Message handed over before calling Close, the Closed
Event will signify that this Message has indeed been delivered.  This
Action does not affect any other Connection in the same Connection
Group.
Paragraph (version B):
The Closed Event informs the application that a Close Action has
successfully completed, or that the Remote Endpoint has closed the
Connection.  There is no guarantee that a remote Close will be
signaled.
Paragraph (version B):
Abort terminates a Connection without delivering any remaining
Messages.  This action does not affect any other Connection that is
entangled with this one in a Connection Group.  When the Abort Action
has finished, the Connection will send a ConnectionError Event,
indicating local Abort as a reason.
Paragraph (version B):
CloseGroup gracefully terminates a Connection and any other
Connections in the same Connection Group.  For example, all of the
Connections in a group might be streams of a single session for a
multistreaming protocol; closing the entire group will close the
underlying session.  See also groups.  All Connections in the group
will send a Closed Event when the CloseGroup Action was successful.
As with Close, any Messages remaining to be processed on a Connection
will be handled prior to closing.
Paragraph (version B):
AbortGroup terminates a Connection and any other Connections that are
in the same Connection Group without delivering any remaining
Messages.  When the AbortGroup Action has finished, all Connections
in the group will send a ConnectionError Event, indicating local
Abort as a reason.
Paragraph (version B):
A ConnectionError informs the application that: 1) data could not be
delivered to the peer after a timeout, or 2) the Connection has been
aborted (e.g., because the peer has called Abort).  There is no
guarantee that an Abort from the peer will be signaled.