Draft: draft-ietf-taps-interface

Commentary: This contains a mix of normalising editorial work , corrections to text and other issues . 
 OLD : Among the Functional and Optimizing Features , some were common across all or nearly all transport protocols , while others could be seen as features that , if specified , would only be useful with a subset of protocols , but would not harm the functionality of other protocols . Suggest NEW : Some Functional and Optimizing Features are common across all or nearly all transport protocols . Other features might only be useful with a subset of protocols , but would not harm the functionality of other protocols . 
 Re - reading this in context , I proposed a simpler one - word addition as a part of PR . 
 sec 5.2.7 I am not sure what this sentence means : " Disabling this property may enable to control checksum coverage later . " 
 This text is confusing in several ways . Before I offer a rewrite , I have some questions , to which I 'm sure others will be able to remind me of the reasons we arrived here . ( a ) I think the param in 5.2.7 and 5.2.8 may also be about a default for sending and receiving for the established connection , if so ... each of these needs to supply an integer as per Section 8.1.3.6 ... ? ( b ) If this is n't to establish the default , and only for influencing the selected protocol for a " connection " , why do we have separate send and receive properties for partial coverage ? ( The only protocols I know can support this for both of the directions ... ) ( c ) I really do n't understand how we arrived at " 8.1.3.6 " . I think any practical use will need to be able to set the " Corruption Protection Length " for send and receive independently . Yet we finally only have one parameter . .... I 'd be happy to propose text if someone can restore my understanding of what was intended . 
 Re : ( a ): I think this was n't about an Integer , but about protocol choice ( only for influencing the selected protocols , as you say under ( b ) ) . Re : ( b ): I think this was only a general thing before , and later divided ( I do n't fully remember why ) . I think , however , that it 's a different thing to say " I 'm going to actively race this protocol " and " I 'm going to also listen for incoming packets with this protocol " . So that 's the distinction between these two , IIRC . Re : ( c ): What would a " Corruption Protection Length " parameter for receiving accomplish ? With UDP - Lite , you only learn about it after the fact , but you can only generally accept to get such packets ( as per 5.2.8 ) , but then you can only learn about the length parameter that was used , not influence it , I think . 
 OK on ( a ) . You describe ( b ) as somewhat useful , maybe the text should say this . On ( c ) I still this still needs a send and receive number because SEND Minimum coverage and RECV Minimum coverage are two different things in RFC 3828 , Sect 3.3 . : A UDP - Lite receiver does not generally see the coverage value used in datagrams , it therefore needs to configure what min coverage it expects for the receiver stack to check before passing the datagram upwards ( this could be per socket / connection ) . The receiver is probably clearer in RFC5097 , Sect 1.3 , which counts datagrams with the non - deliverable coverage “ EndpointViolCoverage ” . At the sender , each datagram needs to set an appropriate coverage ( this typically needs to be per message ) . 
 Just for the record , I agree with all points of above . 
 Thought to now be addressed as a part of PR to API
Paragraph (version B):
This specification treats Events and Errors similarly.  Errors, just
as any other Events, may occur asynchronously in network
applications.  However, it is recommended that implementations of
this interface also return Errors immediately, according to the error
handling idioms of the implementation platform, for errors that can
be immediately detected, such as inconsistency in Transport
Properties.  An error can provide an optional reason to the
application with further details about why the error occurred.
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):
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 A):
The examples in this section presume that a transport protocol is
available between the endpoints that provides Reliable Data Transfer,
Preservation of data ordering, and Preservation of Message
Boundaries.  In this case, the application can choose to receive only
complete messages.
Paragraph (version A):
If none of the available transport protocols provides Preservation of
Message Boundaries, but there is a transport protocol that provides a
reliable ordered byte stream, an application may receive this byte
stream as partial Messages and transform it into application-layer
Messages.  Alternatively, an application may provide a Message
Framer, which can transform a byte stream into a sequence of Messages
(framing).
Paragraph (version B):
The examples in this section presume that a transport protocol is
available between the Local and Remote Endpoints that provides
Reliable Data Transfer, Preservation of data ordering, and
Preservation of Message Boundaries.  In this case, the application
can choose to receive only complete messages.
Paragraph (version B):
If none of the available transport protocols provides Preservation of
Message Boundaries, but there is a transport protocol that provides a
reliable ordered byte stream, an application could receive this byte
stream as partial Messages and transform it into application-layer
Messages.  Alternatively, an application might provide a Message
Framer, which can transform a byte stream into a sequence of Messages
(framing).
Paragraph (version B):
Transport Properties are divided into Selection, Connection, and
Message Properties.  Selection Properties (see selection-props) can
only be set during pre-establishment.  They are only used to specify
which paths and protocol stacks can be used and are preferred by the
application.  Although Connection Properties (see connection-props)
can be set during pre-establishment, they may be changed later.  They
are used to inform decisions made during establishment and to fine-
tune the established connection.
The behavior of the selected protocol stack(s) when sending Messages
is controlled by Message Properties (see message-props).
Paragraph (version A):
Making code of different TAPS implementations look similar.  While
individual programming languages may preclude strict adherence to
the aforementioned naming convention (for instance, by prohibiting
the use of hyphens in symbols), users interacting with multiple
implementations will still benefit from the consistency resulting
from the use of visually similar symbols.
Paragraph (version B):
Making the code of different TAPS implementations look similar.
While individual programming languages may preclude strict
adherence to the aforementioned naming convention (for instance,
by prohibiting the use of hyphens in symbols), users interacting
with multiple implementations will still benefit from the
consistency resulting from the use of visually similar symbols.
Paragraph (version A):
Protocol Specific Properties MUST use the protocol acronym as
Namespace, e.g., "tcp" for TCP specific Transport Properties.  For
IETF protocols, property names under these namespaces SHOULD be
defined in an RFC.
Paragraph (version A):
Vendor or implementation specific properties MUST use a string
identifying the vendor or implementation as Namespace.
Paragraph (version B):
Protocol Specific Properties MUST use the protocol acronym as the
Namespace, e.g., "tcp" for TCP specific Transport Properties.  For
IETF protocols, property names under these namespaces SHOULD be
defined in an RFC.
Paragraph (version B):
Vendor or implementation specific properties MUST use a string
identifying the vendor or implementation as the Namespace.
Paragraph (version A):
There is no interoperability benefit in tightly defining how the
interface is presented to application programmers across diverse
platforms.  However, maintaining the "shape" of the abstract
interface across these platforms reduces the effort for programmers
who learn the transport services interface to then apply their
knowledge across multiple platforms.
Paragraph (version B):
There is no interoperability benefit in tightly defining how the
interface is presented to application programmers across diverse
platforms.  However, maintaining the "shape" of the abstract
interface across different platforms reduces the effort for
programmers who learn the transport services interface to then apply
their knowledge to another platform.
Paragraph (version B):
Implementations of this interface SHOULD implement each Selection
Property, Connection Property, and Message Context Property
specified in this document.  Each interface SHOULD be implemented
even when in a specific implementation/platform it will always
result in no operation, e.g. there is no action when the API
specifies a Property that is not available in a transport protocol
implemented on a specific platform.  For example, if TCP is the
only underlying transport protocol, the Message Property
"msgOrdered" can be implemented even if disabling ordering will
not have any effect TCP because the API does not guarantee out-of-
order delivery.  Similarly, the "msg-lifetime" Message Property
can be implemented but ignored, as the description of this
Property states that "it is not guaranteed that a Message will not
be sent when its Lifetime has expired".
Paragraph (version A):
The Pre-Establishment phase allows applications to specify properties
for the Connections they are about to make, or to query the API about
potential Connections they could make.
Paragraph (version B):
The Pre-Establishment phase allows applications to specify properties
for the Connections that they are about to make, or to query the API
about potential Connections they could make.
Paragraph (version A):
As an alternative to specifying an interface name for the Local
Endpoint, an application can express more fine-grained preferences
using the "Interface Instance or Type" Selection Property, see prop-
interface.  However, if the application specifies Selection
Properties which are inconsistent with the Local Endpoint, this will
result in an error once the application attempts to open a
Connection.
Paragraph (version B):
As an alternative to specifying an interface name for the Local
Endpoint, an application can express more fine-grained preferences
using the "Interface Instance or Type" Selection Property, see prop-
interface.  However, if the application specifies Selection
Properties that are inconsistent with the Local Endpoint, this will
result in an Error once the application attempts to open a
Connection.
Paragraph (version B):
The implementation MUST ensure an outcome that is consistent with all
application requirements expressed using Require and Prohibit.  While
preferences expressed using Prefer and Avoid influence protocol and
path selection as well, outcomes can vary given the same Selection
Properties, because the available protocols and paths can differ
across systems and contexts.  However, implementations are
RECOMMENDED to seek to provide a consistent outcome to an
application, given the same set of Selection Properties.
Paragraph (version B):
Note that application preferences can conflict with each other.  For
example, if an application indicates a preference for a specific path
by specifying an interface, but also a preference for a protocol, a
situation might occur in which the preferred protocol is not
available on the preferred path.  In such cases, implementations
SHOULD prioritize Selection Properties that select paths over those
that select protocols.  Therefore, the transport system SHOULD race
the path first, ignoring the protocol preference if a specific
protocol does not work on the path.
Paragraph (version B):
Selection Properties of type "Preference" might often be frequently
used.  Implementations MAY therefore provide additional convenience
functions to simplify use, see preference-conv for examples.  In
addition, implementations MAY provide a mechanism to create
TransportProperties objects that are preconfigured for common use
cases as outlined in property-profiles.
Paragraph (version A):
An implementation of this interface must provide sensible defaults
for Selection Properties.  The recommended default values for each
property below represent a configuration that can be implemented over
TCP.  If these default values are used and TCP is not supported by a
Transport Services implementation, then an application using the
default set of Properties might not succeed in establishing a
connection.  Using the same default values for independent Transport
Services implementations can be beneficial when applications are
ported between different implementations, even if this default could
lead to a connection failure, as, for example, an application needs
to be explicitly designed to support a connectionless mode.  In this
case, the application can recognize the failure and explicitly
specify a different set of Protocol Selection Properties that result
in a usable protocol.  If default values other than those recommended
below are used, it is recommended to clearly document the
differences.
Paragraph (version B):
An implementation of this interface must provide sensible defaults
for Selection Properties.  The recommended default values for each
property below represent a configuration that can be implemented over
TCP.  If these default values are used and TCP is not supported by a
Transport Services implementation, then an application using the
default set of Properties might not succeed in establishing a
connection.  Using the same default values for independent Transport
Services implementations can be beneficial when applications are
ported between different implementations/platforms, even if this
default could lead to a connection failure, as, for example, an
application needs to be explicitly designed to support a
connectionless mode.  In this case, the application can recognize the
failure and explicitly specify a different set of Protocol Selection
Properties that result in a usable protocol.  If default values other
than those recommended below are used, it is recommended to clearly
document any differences.
Paragraph (version A):
This property specifies whether the application needs to use a
transport protocol that ensures that all data is received on the
other side without corruption.  This also entails being notified when
a Connection is closed or aborted when reliable data transfer is
enabled.
Paragraph (version B):
This property specifies whether the application needs to use a
transport protocol that ensures that all data is received at the
Remote Endpoint without corruption.  When reliable data transfer is
enabled, this also entails being notified when a Connection is closed
or aborted.
Paragraph (version B):
This property specifies whether an application would like to supply a
Message to the transport protocol before Connection establishment
that will then be reliably transferred to the other side before or
during Connection establishment.  This Message can potentially be
received multiple times (i.e., multiple copies of the message data
may be passed to the Remote Endpoint).  See also msg-
safelyreplayable.  Note that disabling this property has no effect
for protocols that are not connection-oriented and do not protect
against duplicated messages, e.g., UDP.
Paragraph (version A):
This property specifies whether the application desires protection
against corruption for all data transmitted on this Connection.
Disabling this property may enable to control checksum coverage later
(see msg-checksum).
Paragraph (version B):
This property specifies the application's need for protection against
corruption for all data transmitted on this Connection.  Disabling
this property could enable later control of the sender checksum
coverage (see msg-checksum).
Paragraph (version A):
This property specifies whether the application desires protection
against corruption for all data received on this Connection.
Paragraph (version B):
This property specifies the application's need for protection against
corruption for all data received on this Connection.  Disabling this
property could enable later control of the required minimum receiver
checksum coverage (see recvChecksumLen).
Paragraph (version A):
This property specifies whether the application would like the
Connection to be congestion controlled or not.  Note that if a
Connection is not congestion controlled, an application using such a
Connection should itself perform congestion control in accordance
with RFC2914.  Also note that reliability is usually combined with
congestion control in protocol implementations, rendering "reliable
but not congestion controlled" a request that is unlikely to succeed.
Paragraph (version B):
This property specifies whether the application would like the
Connection to be congestion controlled or not.  Note that if a
Connection is not congestion controlled, an application using such a
Connection SHOULD itself perform congestion control in accordance
with RFC2914, RFC2119.  Also note that reliability is usually
combined with congestion control in protocol implementations,
rendering "reliable but not congestion controlled" a request that is
unlikely to succeed.
Paragraph (version B):
This property allows the application to select any specific network
interfaces or categories of interfaces it wants to "Require",
"Prohibit", "Prefer", or "Avoid".  Note that marking a specific
interface as "Require" strictly limits path selection to that single
interface, and often leads to less flexible and resilient connection
establishment.
Paragraph (version A):
The set of valid interface types is implementation- and system-
specific.  For example, on a mobile device, there may be "Wi-Fi" and
"Cellular" interface types available; whereas on a desktop computer,
there may be "Wi-Fi" and "Wired Ethernet" interface types available.
An implementation should provide all types that are supported on the
local system to all remote systems, to allow applications to be
written generically.  For example, if a single implementation is used
on both mobile devices and desktop devices, it should define the
"Cellular" interface type for both systems, since an application may
want to always "Prohibit Cellular".
Paragraph (version B):
The set of valid interface types is implementation- and system-
specific.  For example, on a mobile device, there may be "Wi-Fi" and
"Cellular" interface types available; whereas on a desktop computer,
"Wi-Fi" and "Wired Ethernet" interface types might be available.  An
implementation should provide all types that are supported on the
local system to all remote systems, to allow applications to be
written generically.  For example, if a single implementation is used
on both mobile devices and desktop devices, it should define the
"Cellular" interface type for both systems, since an application
might wish to always "Prohibit Cellular".
Paragraph (version A):
Similar to interface instances and types (see prop-interface), this
property allows the application to control path selection by
selecting which specific Provisioning Domains or categories of
Provisioning Domains it wants to "Require", "Prohibit", "Prefer", or
"Avoid".  Provisioning Domains define consistent sets of network
properties that may be more specific than network interfaces RFC7556.
Paragraph (version A):
Categories or types of PvDs are also defined to be implementation-
and system-specific.  These may be useful to identify a service that
is provided by a PvD.  For example, if an application wants to use a
PvD that provides a Voice-Over-IP service on a Cellular network, it
can use the relevant PvD type to require some PvD that provides this
service, without needing to look up a particular instance.  While
this does restrict path selection, it is broader than requiring
specific PvD instances or interface instances, and should be
preferred over these options.
Paragraph (version B):
Similar to interface instances and types (see prop-interface), this
property allows the application to control path selection by
selecting which specific Provisioning Domain (PvD) or categories of
PVDs it wants to "Require", "Prohibit", "Prefer", or "Avoid".
Provisioning Domains define consistent sets of network properties
that may be more specific than network interfaces RFC7556.
Paragraph (version B):
The identification of a specific PvD is implementation- and system-
specific, because there is currently no portable standard format for
a PvD identifier.  For example, this identifier might be a string
name or an integer.  As with requiring specific interfaces, requiring
a specific PvD strictly limits the path selection.
Paragraph (version B):
Categories or types of PvDs are also defined to be implementation-
and system-specific.  These can be useful to identify a service that
is provided by a PvD.  For example, if an application wants to use a
PvD that provides a Voice-Over-IP service on a Cellular network, it
can use the relevant PvD type to require a PvD that provides this
service, without needing to look up a particular instance.  While
this does restrict path selection, it is broader than requiring
specific PvD instances or interface instances, and should be
preferred over these options.
Paragraph (version B):
This property allows the application to express a preference for the
use of temporary local addresses, sometimes called "privacy"
addresses RFC4941.  Temporary addresses are generally used to prevent
linking connections over time when a stable address, sometimes called
"permanent" address, is not needed.  Note that if an application
Requires the use of temporary addresses, the resulting Connection
cannot use IPv4, because temporary addresses do not exist in IPv4.
Paragraph (version A):
Setting this property to "Active", may have privacy implications: It
enables the transport to establish connectivity using alternate paths
that may make users linkable across multiple paths, even if the
Advertisement of Alternative Addresses property (see altaddr below)
is set to false.
Paragraph (version B):
Setting this property to "Active", can have privacy implications: It
enables the transport to establish connectivity using alternate paths
that might result in users being linkable across the multiple paths,
even if the Advertisement of Alternative Addresses property (see
altaddr below) is set to false.
Paragraph (version A):
Note that this may have privacy implications because it may make
users linkable across multiple paths.  Also, note that setting this
to false does not prevent the local transport system from
_establishing_ connectivity using alternate paths (see multipath-mode
above); it only prevents _proactive advertisement_ of addresses.
Paragraph (version A):
This property specifies whether an application considers it useful to
be informed when an ICMP error message arrives that does not force
termination of a connection.  When set to true, received ICMP errors
will be available as SoftErrors, see soft-errors.  Note that even if
a protocol supporting this property is selected, not all ICMP errors
will necessarily be delivered, so applications cannot rely on
receiving them.
Paragraph (version B):
This property specifies whether an application considers it useful to
be informed when an ICMP error message arrives that does not force
termination of a connection.  When set to true, received ICMP errors
are available as SoftErrors, see soft-errors.  Note that even if a
protocol supporting this property is selected, not all ICMP errors
will necessarily be delivered, so applications cannot rely upon
receiving them RFC8085.
Paragraph (version A):
Most security parameters, e.g., TLS ciphersuites, local identity and
private key, etc., may be configured statically.  Others are
dynamically configured during connection establishment.  Thus, we
partition security parameters and callbacks based on their place in
the lifetime of connection establishment.  Similar to Transport
Properties, both parameters and callbacks are inherited during
cloning (see groups).
Paragraph (version B):
Most security parameters, e.g., TLS ciphersuites, local identity and
private key, etc., may be configured statically.  Others are
dynamically configured during connection establishment.  Security
parameters and callbacks are partitioned based on their place in the
lifetime of connection establishment.  Similar to Transport
Properties, both parameters and callbacks are inherited during
cloning (see groups).
Paragraph (version A):
Before a Connection can be used for data transfer, it must be
established.  Establishment ends the pre-establishment phase; all
transport properties and cryptographic parameter specification must
be complete before establishment, as these will be used to select
candidate Paths and Protocol Stacks for the Connection.
Establishment may be active, using the Initiate() Action; passive,
using the Listen() Action; or simultaneous for peer-to-peer, using
the Rendezvous() Action.  These Actions are described in the
subsections below.
Paragraph (version B):
Before a Connection can be used for data transfer, it needs to be
established.  Establishment ends the pre-establishment phase; all
transport properties and cryptographic parameter specification must
be complete before establishment, as these will be used to select
candidate Paths and Protocol Stacks for the Connection.
Establishment may be active, using the Initiate() Action; passive,
using the Listen() Action; or simultaneous for peer-to-peer, using
the Rendezvous() Action.  These Actions are described in the
subsections below.
Paragraph (version A):
An EstablishmentError occurs either when the set of transport
properties and security parameters cannot be fulfilled on a
Connection for initiation (e.g. the set of available Paths and/or
Protocol Stacks meeting the constraints is empty) or reconciled with
the local and/or remote Endpoints; when the remote specifier cannot
be resolved; or when no transport-layer connection can be established
to the remote Endpoint (e.g. because the remote Endpoint is not
accepting connections, the application is prohibited from opening a
Connection by the operating system, or the establishment attempt has
timed out for any other reason).
Paragraph (version A):
See also initiate-and-send to combine Connection establishment and
transmission of the first message in a single action.
Paragraph (version B):
An EstablishmentError occurs either when the set of transport
properties and security parameters cannot be fulfilled on a
Connection for initiation (e.g., the set of available Paths and/or
Protocol Stacks meeting the constraints is empty) or reconciled with
the Local and/or Remote Endpoints; when the remote specifier cannot
be resolved; or when no transport-layer connection can be established
to the Remote Endpoint (e.g., because the Remote Endpoint is not
accepting connections, the application is prohibited from opening a
Connection by the operating system, or the establishment attempt has
timed out for any other reason).
Paragraph (version B):
Connection establishment and transmission of the first message can be
combined in a single action initiate-and-send.
Paragraph (version B):
After calling Stop(), the Listener object can be disposed of.
Paragraph (version A):
The Resolve() call returns a list of Preconnection Objects, that
represent the concrete addresses, local and server reflexive, on
which a Rendezvous() for the Preconnection will listen for incoming
Connections.  These resolved Preconnections will share all other
Properties with the Preconnection from which they are derived, though
some Properties may be made more-specific by the resolution process.
This list can be passed to a peer via a signalling protocol, such as
SIP RFC3261 or WebRTC RFC7478, to configure the remote.
Paragraph (version A):
Calling Clone on a Connection yields a group of two Connections: the
parent Connection on which Clone was called, and the resulting cloned
Connection.  These connections are "entangled" with each other, and
become part of a Connection Group.  Calling Clone on any of these two
Connections adds a third Connection to the Connection Group, and so
on.  Connections in a Connection Group generally share Connection
Properties.  However, there may be exceptions, such as "Priority
(Connection)", see conn-priority.  Like all other Properties,
Priority is copied to the new Connection when calling Clone(), but it
is not entangled: Changing Priority on one Connection does not change
it on the other Connections in the same Connection Group.
Paragraph (version A):
Connections will be in the same group if the application previously
called Clone.  Passive Connections can also be added to the same
group - e.g., when a Listener receives a new Connection that is just
a new stream of an already active multi-streaming protocol instance.
Paragraph (version B):
Calling Clone on a Connection yields a group of Connections: the
parent Connection on which Clone was called, and a resulting cloned
Connection.  The connections within a group are "entangled" with each
other, and become part of a Connection Group.  Calling Clone on any
of these Connections adds another Connection to the Connection Group,
and so on.  Connections in a Connection Group generally share
Connection Properties.  However, there may be exceptions, such as
"Priority (Connection)", see conn-priority.  Like all other
Properties, Priority is copied to the new Connection when calling
Clone(), but it is not entangled: Changing Priority on one Connection
does not change it on the other Connections in the same Connection
Group.
Paragraph (version B):
Connections will belong to the same group if the application
previously called Clone.  Passive Connections can also be added to
the same group - e.g., when a Listener receives a new Connection that
is just a new stream of an already active multi-streaming protocol
instance.
Paragraph (version A):
If the underlying protocol supports multi-streaming, it is natural to
use this functionality to implement Clone.  In that case, entangled
Connections are multiplexed together, giving them similar treatment
not only inside endpoints but also across the end-to-end Internet
path.
Paragraph (version A):
Note that calling Clone() may result in on-the-wire signaling, e.g.,
to open a new connection, depending on the underlying Protocol Stack.
When Clone() leads to multiple connections being opened instead of
multi-streaming, the transport 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 system to implement prioritization within a
Connection Group TCP-COUPLING RFC8699.
Paragraph (version A):
Connection Properties represent the configuration and state of the
selected Protocol Stack(s) backing a Connection.  These Connection
Properties may be Generic, applying regardless of transport protocol,
or Specific, applicable to a single implementation of a single
transport protocol stack.  Generic Connection Properties are defined
in connection-props below.  Specific Protocol Properties are defined
in a transport- and implementation-specific way, and must not be
assumed to apply across different protocols.  Attempts to set
Specific Protocol Properties on a protocol stack not containing that
specific protocol are simply ignored, and do not raise an error;
however, too much reliance by an application on Specific Protocol
Properties may significantly reduce the flexibility of a transport
services implementation.
Paragraph (version B):
Connection Properties represent the configuration and state of the
selected Protocol Stack(s) backing a Connection.  These Connection
Properties may be Generic, applying regardless of transport protocol,
or Specific, applicable to a single implementation of a single
transport protocol stack.  Generic Connection Properties are defined
in connection-props below.  Specific Protocol Properties are defined
in a transport- and implementation-specific way, and MUST NOT be
assumed to apply across different protocols.  Attempts to set
Specific Protocol Properties on a protocol stack not containing that
specific protocol are simply ignored, and do not raise an error;
however, too much reliance by an application on Specific Protocol
Properties can significantly reduce the flexibility of a transport
services implementation.
Paragraph (version A):
Whether the connection can be used to receive data.  A connection
can not be used for reading if the connection was created with the
Selection Property "Direction of Communication" set to
"unidirectional send" or if a Message marked as "Final" was
received, see receiving-final-messages.  The latter is only
supported by certain transport protocols, e.g., by TCP as half-
closed connection.
Paragraph (version B):
Whether the connection can be used to receive data.  A connection
cannot be used for reading if the connection was created with the
Selection Property "Direction of Communication" set to
"unidirectional send" or if a Message marked as "Final" was
received, see receiving-final-messages.  The latter is only
supported by certain transport protocols, e.g., by TCP as half-
closed connection.
Paragraph (version A):
For Connections that are Established, Closing, or Closed:
Selection (selection-props) and Connection Properties (connection-
props) of the actual protocols that were selected and
instantiated.  Selection Properties indicate whether or not the
Connection has or offers a certain Selection Property.  Note that
the actually instantiated protocol stack may not match all
Protocol Selection Properties that the application specified on
the Preconnection.  For example, a certain Protocol Selection
Property that an application specified as Preferred may not
actually be present in the chosen protocol stack because none of
the currently available transport protocols had this feature.
Paragraph (version B):
For Connections that are Established, Closing, or Closed:
Selection (selection-props) and Connection Properties (connection-
props) of the actual protocols that were selected and
instantiated.  Selection Properties indicate whether or not the
Connection has or offers a certain Selection Property.  The
actually instantiated protocol stack might not match all Protocol
Selection Properties that the application specified on the
Preconnection.  For example, a certain Protocol Selection Property
that an application specified as Preferred might not actually be
present in the chosen protocol stack because none of the currently
available transport protocols had this feature.
Paragraph (version A):
Note that many Connection Properties have a corresponding Selection
Property which enables applications to express their preference for
protocols providing a supporting transport feature.
Paragraph (version B):
Many Connection Properties have a corresponding Selection Property
that enables applications to express their preference for protocols
providing a supporting transport feature.
Paragraph (version B):
This property specifies the minimum number of bytes in a received
message that need to be covered by a checksum.  A special value of 0
means that no checksum is permitted.  A receiving Endpoint will not
forward messages to the application that have less coverage.  The
application is responsible for handling any corruption within the
non-protected part of the message RFC8085.
Paragraph (version A):
The application provides no information about its expected
capacity profile.  Transport system implementations that map the
requested capacity profile onto per-connection DSCP signaling
SHOULD assign the DSCP Default Forwarding RFC2474 PHB.
Paragraph (version B):
The application prefers loss to latency, but is not interactive.
Response time should be optimized at the expense of delay
variation and efficient use of the available capacity when sending
on this connection.  Transport system implementations that map the
requested capacity profile onto per-connection DSCP signaling
without multiplexing SHOULD assign a DSCP Assured Forwarding
(AF21,AF22,AF23,AF24) RFC2597 PHB.
Paragraph (version A):
The connection should only attempt to migrate between different
paths when the original path is lost or becomes unusable.  The
actual thresholds to declare a path unusable are implementation
specific.
Paragraph (version A):
The connection should attempt to minimize the latency for
interactive traffic patterns by transmitting data across multiple
paths when it is beneficial to do so.  The goal of minimizing the
latency will be balanced against the cost of each of these paths,
meaning that depending on the cost of the lower-latency path, the
scheduling might choose to use a higher-latency path.  Traffic can
be scheduled such that data may be transmitted on multiple paths
in parallel to achieve the lowest latency possible.  The specific
scheduling algorithm is implementation-specific.
Paragraph (version A):
The connection should attempt to use multiple paths in parallel in
order to maximize bandwidth and possibly overcome bandwidth
limitations of the individual paths.  The actual strategy is
implementation specific.
Paragraph (version A):
Note that this is a local choice - the peer endpoint can choose a
different policy.
Paragraph (version B):
The connection ought only to attempt to migrate between different
paths when the original path is lost or becomes unusable.  The
thresholds used to declare a path unusable are implementation
specific.
Paragraph (version B):
The connection ought only to attempt to minimize the latency for
interactive traffic patterns by transmitting data across multiple
paths when this is beneficial.  The goal of minimizing the latency
will be balanced against the cost of each of these paths.
Depending on the cost of the lower-latency path, the scheduling
might choose to use a higher-latency path.  Traffic can be
scheduled such that data may be transmitted on multiple paths in
parallel to achieve a lower latency.  The specific scheduling
algorithm is implementation-specific.
Paragraph (version B):
The connection ought to attempt to use multiple paths in parallel
to maximize available capacity and possibly overcome the capacity
limitations of the individual paths.  The actual strategy is
implementation specific.
Paragraph (version B):
Note that this is a local choice - the Remote Endpoint can choose a
different policy.
Paragraph (version B):
This property specifies an upper-bound rate that a transfer is not
expected to exceed (even if flow control and congestion control allow
higher rates), and/or a lower-bound rate below which the application
does not deem a will be useful.  These are specified in bits per
second.  The special value "Unlimited" indicates that no bound is
specified.
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.  This property 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 I-D.ietf-tsvwg-
datagram-plpmtud.
Paragraph (version A):
This property represents the maximum Message size that can be sent
using a send operation.
Paragraph (version B):
This property represents the maximum Message size that an application
can send.
Paragraph (version A):
This numeric property represents the maximum Message size that can be
received.
Paragraph (version A):
These properties specify configurations for the User Timeout Option
(UTO), in case TCP becomes the chosen transport protocol.
Implementation is optional and of course only sensible if TCP is
implemented in the transport system.
Paragraph (version B):
This numeric property represents the maximum Message size that an
application can receive.
Paragraph (version A):
This time value is advertised via the TCP User Timeout Option (UTO)
RFC5482 at the remote endpoint to adapt its own "Timeout for aborting
Connection" (see conn-timeout) value accordingly.
Paragraph (version B):
This time value is advertised via the TCP User Timeout Option (UTO)
RFC5482 at the Remote Endpoint to adapt its own "Timeout for aborting
Connection" (see conn-timeout) value.
Paragraph (version A):
Although most applications communicate over a network using well-
formed Messages, the boundaries and metadata of the Messages are
often not directly communicated by the transport protocol itself.
For example, HTTP applications send and receive HTTP messages over a
byte-stream transport, requiring that the boundaries of HTTP messages
be parsed out from the stream of bytes.
Paragraph (version A):
Message Framers allow extending a Connection's Protocol Stack to
define how to encapsulate or encode outbound Messages, and how to
decapsulate or decode inbound data into Messages.  Message Framers
allow message boundaries to be preserved when using a Connection
object, even when using byte-stream transports.  This facility is
designed based on the fact that many of the current application
protocols evolved over TCP, which does not provide message boundary
preservation, and since many of these protocols require message
boundaries to function, each application layer protocol has defined
its own framing.
Paragraph (version B):
Although most applications communicate over a network using well-
formed Messages, the boundaries and metadata of the Messages are
often not directly communicated by the transport protocol itself.
For example, HTTP applications send and receive HTTP messages over a
byte-stream transport, requiring that the boundaries of HTTP messages
be parsed from the stream of bytes.
Paragraph (version B):
Message Framers allow extending a Connection's Protocol Stack to
define how to encapsulate or encode outbound Messages, and how to
decapsulate or decode inbound data into Messages.  Message Framers
allow message boundaries to be preserved when using a Connection
object, even when using byte-stream transports.  This is designed
based on the fact that many of the current application protocols
evolved over TCP, which does not provide message boundary
preservation, and since many of these protocols require message
boundaries to function, each application layer protocol has defined
its own framing.
Paragraph (version A):
Note that Message Properties are per-Message, not per-Send if partial
Messages are sent (send-partial).  All data blocks associated with a
single Message share properties specified in the Message Contexts.
For example, it would not make sense to have the beginning of a
Message expire, but allow the end of a Message to still be sent.
Paragraph (version B):
Applications can need to annotate the Messages they send with extra
information to control how data is scheduled and processed by the
transport protocols in the Connection.  Therefore a message context
containing these properties can be passed to the Send Action.  For
other uses of the message context, see msg-ctx.
Paragraph (version B):
Message Properties are per-Message, not per-Send if partial Messages
are sent (send-partial).  All data blocks associated with a single
Message share properties specified in the Message Contexts.  For
example, it would not make sense to have the beginning of a Message
expire, but allow the end of a Message to still be sent.
Paragraph (version B):
A MessageContext object contains metadata for the Messages to be sent
or received.
Paragraph (version B):
The simpler form of Send, which does not take any messageContext, is
equivalent to passing a default MessageContext without adding any
Message Properties.
Paragraph (version A):
Properties may be added to a MessageContext object only before the
context is used for sending.  Once a messageContext has been used
with a Send call, modifying any of its properties is invalid.
Paragraph (version A):
Message Properties may be inconsistent with the properties of the
Protocol Stacks underlying the Connection on which a given Message is
sent.  For example, a Connection must provide reliability to allow
setting an infinite value for the lifetime property of a Message.
Sending a Message with Message Properties inconsistent with the
Selection Properties of the Connection yields an error.
Paragraph (version B):
Properties can be added to a MessageContext object only before the
context is used for sending.  Once a messageContext has been used
with a Send call, it is invalid to modify any of its properties.
Paragraph (version B):
The Message Properties could be inconsistent with the properties of
the Protocol Stacks underlying the Connection on which a given
Message is sent.  For example, a Connection must provide reliability
to allow setting an infinite value for the lifetime property of a
Message.  Sending a Message with Message Properties inconsistent with
the Selection Properties of the Connection yields an error.
Paragraph (version B):
Connection Properties describe the default behavior for all Messages
on a Connection.  If a Message Property contradicts a Connection
Property, and if this per-Message behavior can be supported, it
overrides the Connection Property for the specific Message.  For
example, if "Reliable Data Transfer (Connection)" is set to "Require"
and a protocol with configurable per-Message reliability is used,
setting "Reliable Data Transfer (Message)" to "false" for a
particular Message will allow this Message to be unreliably
delivered.  Changing the Reliable Data Transfer property on Messages
is only possible for Connections that were established enabling the
Selection Property "Configure Per-Message Reliability".
Paragraph (version A):
Lifetime specifies how long a particular Message can wait to be sent
to the remote endpoint before it is irrelevant and no longer needs to
be (re-)transmitted.  This is a hint to the transport system - it is
not guaranteed that a Message will not be sent when its Lifetime has
expired.
Paragraph (version A):
If true, it specifies that the receiver-side transport protocol stack
may only deliver the Message to the receiving application after the
previous ordered Message which was passed to the same Connection via
the Send Action, when such a Message exists.  If false, the Message
may be delivered to the receiving application out of order.  This
property is used for protocols that support preservation of data
ordering, see prop-ordering, but allow out-of-order delivery for
certain messages, e.g., by multiplexing independent messages onto
different streams.
Paragraph (version B):
If false, the Message is delivered to the receiving application
without preserving the ordering.  This property is used for protocols
that support preservation of data ordering, see prop-ordering, but
allow out-of-order delivery for certain messages, e.g., by
multiplexing independent messages onto different streams.
Paragraph (version A):
If true, it specifies that a Message is safe to send to the remote
endpoint more than once for a single Send Action.  It is used to mark
data safe for certain 0-RTT establishment techniques, where
retransmission of the 0-RTT data may cause the remote application to
receive the Message multiple times.
Paragraph (version B):
If true, Safely Replayable specifies that a Message is safe to send
to the Remote Endpoint more than once for a single Send Action.  It
marks the data as safe for certain 0-RTT establishment techniques,
where retransmission of the 0-RTT data may cause the remote
application to receive the Message multiple times.
Paragraph (version B):
For protocols that do not protect against duplicated messages, e.g.,
UDP, all messages need to be marked as "Safely Replayable".  To
enable protocol selection to choose such a protocol, "Safely
Replayable" needs to be added to the TransportProperties passed to
the Preconnection.  If such a protocol was chosen, disabling "Safely
Replayable" on individual messages MUST result in a SendError.
Paragraph (version A):
If true, this Message is the last one that the application will send
on a Connection.  This allows underlying protocols to indicate to the
Remote Endpoint that the Connection has been effectively closed in
the sending direction.  For example, TCP-based Connections can send a
FIN once a Message marked as Final has been completely sent,
indicated by marking endOfMessage.  Protocols that do not support
signalling the end of a Connection in a given direction will ignore
this property.
Paragraph (version B):
If true, this indicates a Message is the last that the application
will send on a Connection.  This allows underlying protocols to
indicate to the Remote Endpoint that the Connection has been
effectively closed in the sending direction.  For example, TCP-based
Connections can send a FIN once a Message marked as Final has been
completely sent, indicated by marking endOfMessage.  Protocols that
do not support signalling the end of a Connection in a given
direction will ignore this property.
Paragraph (version B):
A Final Message must always be sorted to the end of a list of
Messages.  The Final property overrides Priority and any other
property that would re-order Messages.  If another Message is sent
after a Message marked as Final has already been sent on a
Connection, the Send Action for the new Message will cause a
SendError Event.
Paragraph (version B):
This property specifies the minimum length of the section of a sent
Message, starting from byte 0, that the application requires to be
delivered without corruption due to lower layer errors.  It is used
to specify options for simple integrity protection via checksums.  A
value of 0 means that no checksum is required, and "Full Coverage"
means that the entire Message needs to be protected by a checksum.
Only "Full Coverage" is guaranteed, any other requests are advisory,
which may result in "Full Coverage" being applied.
Paragraph (version B):
When true, this property specifies that a Message should be sent in
such a way that the transport protocol ensures all data is received
on the other side without corruption.  Changing the "Reliable Data
Transfer" property on Messages is only possible for Connections that
were established enabling the Selection Property "Configure Per-
Message Reliability".  When this is not the case, changing
"msgReliable" will generate an error.
Paragraph (version A):
This property specifies that a message should be sent and received as
a single packet without network-layer fragmentation, if possible.
Attempts to send a message with this property set with a size greater
to the transport's current estimate of its maximum transmission
segment size will result in a "SendError".  When used with transports
supporting this functionality and running over IP version 4, the
Don't Fragment bit will be set.
Paragraph (version A):
The most basic form of sending on a connection involves enqueuing a
single Data block as a complete Message, with default Message
Properties.
Paragraph (version B):
The most basic form of sending on a connection involves enqueuing a
single Data block as a complete Message with default Message
Properties.
Paragraph (version A):
A SendError occurs when a Message could not be 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 to which it applies.
Paragraph (version A):
To reduce the overhead of sending multiple small Messages on a
Connection, the application may want to batch several Send Actions
together.  This provides a hint to the system that the sending of
these Messages should be coalesced when possible, and that sending
any of the batched Messages may be delayed until the last Message in
the batch is enqueued.
Paragraph (version B):
To reduce the overhead of sending multiple small Messages on a
Connection, the application could batch several Send Actions
together.  This provides a hint to the system that the sending of
these Messages ought to be coalesced when possible, and that sending
any of the batched Messages can be delayed until the last Message in
the batch is enqueued.
Paragraph (version A):
Note that maxLength does not guarantee that the application will
receive that many bytes if they are available; the interface may
return ReceivedPartial events with less data than maxLength according
to implementation constraints.  Note also that maxLength and
minIncompleteLength are intended only to manage buffering, and are
not interpreted as a receiver preference for message reordering.
Paragraph (version B):
The maxLength argument indicates the maximum size of a Message in
bytes that the application is currently prepared to receive.  The
default value for maxLength is infinite.  If an incoming Message is
larger than the minimum of this size and the maximum Message size on
receive for the Connection's Protocol Stack, it will be delivered via
ReceivedPartial events (receive-partial).
Paragraph (version B):
Note that maxLength does not guarantee that the application will
receive that many bytes if they are available; the interface could
return ReceivedPartial events with less data than maxLength according
to implementation constraints.  Note also that maxLength and
minIncompleteLength are intended only to manage buffering, and are
not interpreted as a receiver preference for message reordering.
Paragraph (version B):
If a complete Message cannot be delivered in one event, one part of
the Message can be delivered with a ReceivedPartial event.  To
continue to receive more of the same Message, the application must
invoke Receive again.
Paragraph (version A):
A ReceiveError occurs when data is received by the underlying
Protocol Stack that cannot be fully retrieved or parsed, or when some
other indication is received that reception has failed.  In contrast,
conditions that irrevocably lead to the termination of the Connection
are signaled using ConnectionError instead (see termination).
Paragraph (version A):
The ReceiveError event passes an optional associated MessageContext.
This may indicate that a Message that was being partially received
previously, but had not completed, encountered an error and will not
be completed.
Paragraph (version B):
A ReceiveError occurs when data is received by the underlying
Protocol Stack that cannot be fully retrieved or parsed, or when some
other indication is received that reception has failed.  In contrast,
conditions that irrevocably lead to the termination of the Connection
are instead signaled using ConnectionError (see termination).
Paragraph (version B):
The ReceiveError event passes an optional associated MessageContext.
This can indicate that a Message that was being partially received
previously, but had not completed, encountered an error and will not
be completed.
Paragraph (version A):
When available, Message metadata carries the value of the Explicit
Congestion Notification (ECN) field.  This information can be used
for logging and debugging purposes, and for building applications
which need access to information about the transport internals for
their own operation.  This property is specific to UDP and UDP-Lite
because these protocols do not implement congestion control, and
hence expose this functionality to the application.
Paragraph (version A):
In some cases it may be valuable to know whether data was read as
part of early data transfer (before connection establishment has
finished).  This is useful if applications need to treat early data
separately, e.g., if early data has different security properties
than data sent after connection establishment.  In the case of TLS
1.3, client early data can be replayed maliciously (see RFC8446).
Thus, receivers may wish to perform additional checks for early data
to ensure it is safely replayable.  If TLS 1.3 is available and the
recipient Message was sent as part of early data, the corresponding
metadata carries a flag indicating as such.  If early data is
enabled, applications should check this metadata field for Messages
received during connection establishment and respond accordingly.
Paragraph (version B):
When available, Message metadata carries the value of the Explicit
Congestion Notification (ECN) field.  This information can be used
for logging and debugging, and for building applications that need
access to information about the transport internals for their own
operation.  This property is specific to UDP and UDP-Lite because
these protocols do not implement congestion control, and hence expose
this functionality to the application.
Paragraph (version B):
In some cases it can be valuable to know whether data was read as
part of early data transfer (before connection establishment has
finished).  This is useful if applications need to treat early data
separately, e.g., if early data has different security properties
than data sent after connection establishment.  In the case of TLS
1.3, client early data can be replayed maliciously (see RFC8446).
Thus, receivers might wish to perform additional checks for early
data to ensure it is safely replayable.  If TLS 1.3 is available and
the recipient Message was sent as part of early data, the
corresponding metadata carries a flag indicating as such.  If early
data is enabled, applications should check this metadata field for
Messages received during connection establishment and respond
accordingly.
Paragraph (version B):
Some transport protocols and peers do not support signaling of the
Final property.  Applications therefore should not rely on receiving
a Message marked Final to know that the sending endpoint is done
sending on a connection.
Paragraph (version A):
The Closed Event can inform the application that the Remote Endpoint
has closed the Connection; however, there is no guarantee that a
remote Close will indeed be signaled.
Paragraph (version A):
A ConnectionError informs the application that data to could not be
delivered after a timeout, or the other side has aborted the
Connection; however, there is no guarantee that an Abort will indeed
be signaled.
Paragraph (version A):
As this interface is designed to be independent of an
implementation's concurrency model, the details of how exactly
actions are handled, and how events are dispatched, are
implementation dependent.
Paragraph (version B):
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 B):
A ConnectionError informs the application that: 1) data could not be
delivered after a timeout, or 2) the other side has aborted the
Connection.  There is no guarantee that an Abort will indeed be
signaled.
Paragraph (version B):
This interface is designed to be independent of an implementation's
concurrency model.  The details of how exactly actions are handled,
and how events are dispatched, are implementation dependent.
Paragraph (version A):
No events will occur on a Connection after it is Closed; i.e.,
after a Closed<> event, an InitiateError<> or ConnectionError<> on
that connection.  To ensure this ordering, Closed<> will not occur
on a Connection while other events on the Connection are still
locally outstanding (i.e., known to the interface and waiting to
be dealt with by the application).  ConnectionError<> may occur
after Closed<>, but the interface must gracefully handle all cases
where the application ignores these errors.
Paragraph (version B):
No events will occur on a Connection after it is Closed; i.e.,
after a Closed<> event, an InitiateError<> or ConnectionError<> on
that connection.  To ensure this ordering, Closed<> will not occur
on a Connection while other events on the Connection are still
locally outstanding (i.e., known to the interface and waiting to
be dealt with by the application).  ConnectionError<> can occur
after Closed<>, but the interface must gracefully handle all cases
where the application ignores these errors.
Paragraph (version A):
This document describes a generic API for interacting with a
transport services (TAPS) system.  Part of this API includes
configuration details for transport security protocols, as discussed
in security-parameters.  It does not recommend use (or disuse) of
specific algorithms or protocols.  Any API-compatible transport
security protocol should work in a TAPS system.  Security
considerations for these protocols should be discussed in the
respective specifications.
Paragraph (version B):
This document describes a generic API for interacting with a
transport services (TAPS) system.  Part of this API includes
configuration details for transport security protocols, as discussed
in security-parameters.  It does not recommend use (or disuse) of
specific algorithms or protocols.  Any API-compatible transport
security protocol ought to work in a TAPS system.  Security
considerations for these protocols are discussed in the respective
specifications.
Paragraph (version A):
In either case, the TAPS API is an internal interface that is used to
change information locally between two systems.  However, as the
transport system is responsible for network communication, it is in
the position to potentially share any information provided by the
application with the network or another communication peer.  Most of
the information provided over the TAPS API are useful to configure
and select protocols and paths and are not necessarily privacy
sensitive.  Still, there is some information that could be privacy
sensitive because it might reveal usage characteristics and habits of
the user of an application.
Paragraph (version A):
Of course any communication over a network reveals usage
characteristics, as all packets, as well as their timing and size,
are part of the network-visible wire image RFC8546.  However, the
selection of a protocol and its configuration also impacts which
information is visible, potentially in clear text, and which other
entities can access it.  In most cases, information provided for
protocol and path selection should not directly translate to
information that can be observed by network devices on the path.  But
there might be specific configuration information that is intended
for path exposure, such as e.g. a DiffServ codepoint setting, that is
either provided directly by the application or indirectly configured
over a traffic profile.
Paragraph (version A):
Further, applications should be aware that communication attempts can
lead to more than one connection establishment.  This is the case,
for example, when the transport system also executes name resolution,
when support mechanisms such as TURN or ICE are used to establish
connectivity, if protocols or paths are raised, or if a path fails
and fallback or re-establishment is supported in the transport
system.