Draft: draft-ietf-taps-interface

Commentary: I also fixed some capitalization errors in passing . 
 for consistency ; e.g. , a few now have dashes instead . Make sure to fix all references to these names . 
 Yesterday , I said " I can do this tomorrow " . Oh how naive . This is just to apologize - it will take longer ... sorry ! 
 Examples : should be : many more . Thoughts ? This is a large and painful effort , so I 'm checking first :) 
 We have referred to the section titles ? I agree this is incorrect and we should refer to the name of the property . I am surprised no one has noticed this before . 
 It dates back to a time before we introduced the names , but I agree it 's surprising that noone noticed it . 
 Interim : let 's do this for API draft , yes . 
 Yesterday , I said " I can do this tomorrow " . Oh how naive . This is just to apologize - it will take longer ... sorry !
Paragraph (version A):
delivery order for Connections over TCP.  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 B):
delivery order for Connections over TCP.  Similarly, the
"msgLifetime" 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):
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):
Similar to "interface" (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 A):
The policy for using multiple paths is specified using the separate
"multipath-policy" property, see multipath-policy below.  To enable
the peer endpoint to initiate additional paths towards a local
address other than the one initially used, it is necessary to set the
Alternative Addresses property (see altaddr below).
Paragraph (version A):
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 B):
The policy for using multiple paths is specified using the separate
"multipathPolicy" property, see multipath-policy below.  To enable
the peer endpoint to initiate additional paths towards a local
address other than the one initially used, it is necessary to set the
"advertisesAltaddr" property (see altaddr below).
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 "advertisesAltaddr" property (see altaddr below) is set
to false.
Paragraph (version A):
Once Initiate is called, the candidate Protocol Stack(s) may cause
one or more candidate transport-layer connections to be created to
the specified Remote Endpoint.  The caller may immediately begin
sending Messages on the Connection (see sending) after calling
Initiate(); note that any data marked "Safely Replayable" that is
sent while the Connection is being established may be sent multiple
times or on multiple candidates.
Paragraph (version B):
Once Initiate is called, the candidate Protocol Stack(s) may cause
one or more candidate transport-layer connections to be created to
the specified Remote Endpoint.  The caller may immediately begin
sending Messages on the Connection (see sending) after calling
Initiate(); note that any data marked as "safely replayable" that is
sent while the Connection is being established may be sent multiple
times or on multiple candidates.
Paragraph (version A):
Calling Clone on a Connection yields a Connection Group containing
two Connections: the parent Connection on which Clone was called, and
a resulting cloned Connection.  The new Connection is actively
openend, and it will send a Ready Event or an EstablishmentError
Event.  Calling Clone on any of these Connections adds another
Connection to the Connection Group.  Connections in a Connection
Group share all Connection Properties except "Connection Priority"
(see conn-priority), and these Connection Properties are entangled:
Changing one of the Connection Properties on one Connection in the
Connection Group automatically changes the Connection Property for
all others.  For example, changing "Timeout for aborting Connection"
(see conn-timeout) on one Connection in a Connection Group will
automatically make the same change to this Connection Property for
all other Connections in the Connection Group.  Like all other
Properties, "Connection Priority" is copied to the new Connection
when calling Clone(), but in this case, a later change to the
"Connection Priority" on one Connection does not change it on the
other Connections in the same Connection Group.
Paragraph (version B):
Calling Clone on a Connection yields a Connection Group containing
two Connections: the parent Connection on which Clone was called, and
a resulting cloned Connection.  The new Connection is actively
openend, and it will send a Ready Event or an EstablishmentError
Event.  Calling Clone on any of these Connections adds another
Connection to the Connection Group.  Connections in a Connection
Group share all Connection Properties except "connPriority" (see
conn-priority), and these Connection Properties are entangled:
Changing one of the Connection Properties on one Connection in the
Connection Group automatically changes the Connection Property for
all others.  For example, changing "connTimeout" (see conn-timeout)
on one Connection in a Connection Group will automatically make the
same change to this Connection Property for all other Connections in
the Connection Group.  Like all other Properties, "connPriority" is
copied to the new Connection when calling Clone(), but in this case,
a later change to the "connPriority" on one Connection does not
change it on the other Connections in the same Connection Group.
Paragraph (version A):
The "Connection Priority" Connection Property operates on Connections
in a Connection Group using the same approach as in msg-priority:
when allocating available network capacity among Connections in a
Connection Group, sends on Connections with higher Priority values
will be prioritized over sends on Connections that have lower
Priority values.  Capacity will be shared among these Connections
according to the Connection Group Transmission Scheduler property
(conn-scheduler).  See priority-in-taps for more.
Paragraph (version B):
The "connPriority" Connection Property operates on Connections in a
Connection Group using the same approach as in msg-priority: when
allocating available network capacity among Connections in a
Connection Group, sends on Connections with higher Priority values
will be prioritized over sends on Connections that have lower
Priority values.  Capacity will be shared among these Connections
according to the "connScheduler" property (conn-scheduler).  See
priority-in-taps for more.
Paragraph (version A):
Whether the connection can be used to send data.  A connection can
not be used for sending if the connection was created with the
Selection Property "Direction of Communication" set to
"unidirectional receive" or if a Message marked as "Final" was
sent over this connection.  See also msg-final.
Paragraph (version A):
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 B):
Whether the connection can be used to send data.  A connection can
not be used for sending if the connection was created with the
Selection Property "direction" set to "unidirectional receive" or
if a Message marked as "Final" was sent over this connection.  See
also msg-final.
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" 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):
This property controls whether the "Timeout for aborting Connection"
(see conn-timeout) may be changed based on a UTO option received from
the remote peer.  This boolean becomes false when "Timeout for
aborting Connection" (see conn-timeout) is used.
Paragraph (version B):
This property controls whether the "connTimeout" (see conn-timeout)
may be changed based on a UTO option received from the remote peer.
This boolean becomes false when "connTimeout" (see conn-timeout) is
used.
Paragraph (version A):
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 Protocol Stack must be able to
provide ordering if the msgOrdered property of a Message is enabled.
Sending a Message with Message Properties inconsistent with the
Selection Properties of the Connection yields an error.
Paragraph (version A):
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 sent without any reliability guarantees.  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 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 Protocol Stack must be able to
provide ordering if the "msgOrdered" property of a Message is
enabled.  Sending a Message with Message Properties inconsistent with
the Selection Properties of the Connection yields an error.
Paragraph (version B):
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 "reliability" is
set to "Require" and a protocol with configurable per-Message
reliability is used, setting "msgReliable" to "false" for a
particular Message will allow this Message to be sent without any
reliability guarantees.  Changing the "msgReliable" Message Property
is only possible for Connections that were established enabling the
Selection Property "perMsgReliability".
Paragraph (version A):
Setting a Message's Lifetime to infinite indicates that the
application does not wish to apply a time constraint on the
transmission of the Message, but it does not express a need for
reliable delivery; reliability is adjustable per Message via the
"Reliable Data Transfer (Message)" property (see msg-reliable-
message).  The type and units of Lifetime are implementation-
specific.
Paragraph (version B):
Setting a Message's Lifetime to infinite indicates that the
application does not wish to apply a time constraint on the
transmission of the Message, but it does not express a need for
reliable delivery; reliability is adjustable per Message via the
"perMsgReliability" property (see msg-reliable-message).  The type
and units of Lifetime are implementation-specific.
Paragraph (version A):
Note that this property is not a per-message override of the
Connection Priority - see conn-priority.  The Priority properties may
interact, but can be used independently and be realized by different
mechanisms; see priority-in-taps.
Paragraph (version B):
Note that this property is not a per-message override of
"connPriority" - see conn-priority.  The priority properties may
interact, but can be used independently and be realized by different
mechanisms; see priority-in-taps.
Paragraph (version A):
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 A):
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 B):
If true, "safelyReplayable" 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" by
enabling this property.  To enable protocol selection to choose such
a protocol, "safelyReplayable" needs to be added to the
TransportProperties passed to the Preconnection.  If such a protocol
was chosen, disabling "safelyReplayable" on individual messages MUST
result in a SendError.
Paragraph (version A):
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 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 "msgReliable"
property on Messages is only possible for Connections that were
established enabling the Selection Property "perMsgReliability".
When this is not the case, changing "msgReliable" will generate an
error.
Paragraph (version A):
This enumerated property specifies the application's preferred
tradeoffs for sending this Message; it is a per-Message override of
the Capacity Profile connection property (see prop-cap-profile).  If
it is not configured by the application before sending, this
property's default value will be based on the Connection Property
"connCapacityProfile" of the Connection associated with the Send
Action.
Paragraph (version B):
This enumerated property specifies the application's preferred
tradeoffs for sending this Message; it is a per-Message override of
the "connCapacityProfile" Connection Property (see prop-cap-profile).
If it is not configured by the application before sending, this
property's default value will be based on the Connection Property
"connCapacityProfile" of the Connection associated with the Send
Action.
Paragraph (version A):
Some transport protocols can deliver arbitrarily sized Messages, but
other protocols constrain the maximum Message size.  Applications can
query the Connection Property "Maximum Message size on send" (conn-
max-msg-send) to determine the maximum size allowed for a single
Message.  If a Message is too large to fit in the Maximum Message
Size for the Connection, the Send will fail with a SendError event
(send-error).  For example, it is invalid to send a Message over a
UDP connection that is larger than the available datagram sending
size.
Paragraph (version B):
Some transport protocols can deliver arbitrarily sized Messages, but
other protocols constrain the maximum Message size.  Applications can
query the Connection Property "sendMsgMaxLen" (conn-max-msg-send) to
determine the maximum size allowed for a single Message.  If a
Message is too large to fit in the Maximum Message Size for the
Connection, the Send will fail with a SendError event (send-error).
For example, it is invalid to send a Message over a UDP connection
that is larger than the available datagram sending size.
Paragraph (version A):
Whenever possible, a messageContext should be provided to declare the
Message passed to InitiateWithSend as "Safely Replayable".  This
allows the Transport Services system to make use of 0-RTT
establishment in case this is supported by the available protocol
stacks.  When the selected stack(s) do not support transmitting data
upon connection establishment, InitiateWithSend is identical to
Initiate() followed by Send().
Paragraph (version B):
Whenever possible, a messageContext should be provided to declare the
Message passed to InitiateWithSend as "safely replayable" using the
"safelyReplayable" property.  This allows the Transport Services
system to make use of 0-RTT establishment in case this is supported
by the available protocol stacks.  When the selected stack(s) do not
support transmitting data upon connection establishment,
InitiateWithSend is identical to Initiate() followed by Send().
Paragraph (version A):
The Transport Services API provides two properties to allow a sender
to signal the relative priority of data transmission: the Priority
Message Property msg-priority, and the Connection Priority Connection
Property conn-priority.  These properties are designed to allow the
expression and implementation of a wide variety of approaches to
transmission priority in the transport and application layer,
including those which do not appear on the wire (affecting only
sender-side transmission scheduling) as well as those that do (e.g.
I-D.ietf-httpbis-priority.
Paragraph (version B):
The Transport Services API provides two properties to allow a sender
to signal the relative priority of data transmission: "msgPriority"
msg-priority and "connPriority" conn-priority.  These properties are
designed to allow the expression and implementation of a wide variety
of approaches to transmission priority in the transport and
application layer, including those which do not appear on the wire
(affecting only sender-side transmission scheduling) as well as those
that do (e.g.  I-D.ietf-httpbis-priority.
Paragraph (version A):
The Transport Services API does order Connection Priority over the
Priority Message Property.  In the absense of other externalities
(e.g., transport-layer flow control), a priority 1 Message on a
priority 0 Connection will be sent before a priority 0 Message on a
priority 1 Connection in the same group.
Paragraph (version A):
Once a Connection is established, it can be used for receiving data
(unless the "Direction of Communication" property is set to
"unidirectional send").  As with sending, the data is received in
Messages.  Receiving is an asynchronous operation, in which each call
to Receive enqueues a request to receive new data from the
connection.  Once data has been received, or an error is encountered,
an event will be delivered to complete any pending Receive requests
(see receive-events).  If Messages arrive at the Transport Services
system before Receive requests are issued, ensuing Receive requests
will first operate on these Messages before awaiting any further
Messages.
Paragraph (version B):
The Transport Services API does order "connPriority" over
"msgPriority".  In the absense of other externalities (e.g.,
transport-layer flow control), a priority 1 Message on a priority 0
Connection will be sent before a priority 0 Message on a priority 1
Connection in the same group.
Paragraph (version B):
Once a Connection is established, it can be used for receiving data
(unless the "direction" property is set to "unidirectional send").
As with sending, the data is received in Messages.  Receiving is an
asynchronous operation, in which each call to Receive enqueues a
request to receive new data from the connection.  Once data has been
received, or an error is encountered, an event will be delivered to
complete any pending Receive requests (see receive-events).  If
Messages arrive at the Transport Services system before Receive
requests are issued, ensuing Receive requests will first operate on
these Messages before awaiting any further Messages.
Paragraph (version A):
A ReceiveError occurs when data is received by the underlying
Protocol Stack that cannot be fully retrieved or parsed, and when it
is useful for the application to be notified of such errors.  For
example, a ReceiveError can indicate that a Message (identified via
the MessageContext) that was being partially received previously, but
had not completed, encountered an error and will not be completed.
This can be useful for an application, which may want to use this
error as a hint to remove previously received Message parts from
memory.  As another example, if an incoming Message does not fulfill
the Required Minimum Corruption Protection Coverage for Receiving
property (see conn-recv-checksum), an application can use this error
as a hint to inform the peer application to adjust the Sending
Corruption Protection Length property (see msg-checksum).
Paragraph (version B):
A ReceiveError occurs when data is received by the underlying
Protocol Stack that cannot be fully retrieved or parsed, and when it
is useful for the application to be notified of such errors.  For
example, a ReceiveError can indicate that a Message (identified via
the MessageContext) that was being partially received previously, but
had not completed, encountered an error and will not be completed.
This can be useful for an application, which may want to use this
error as a hint to remove previously received Message parts from
memory.  As another example, if an incoming Message does not fulfill
the "recvChecksumLen" property (see conn-recv-checksum), an
application can use this error as a hint to inform the peer
application to adjust the "msgChecksumLen" property (see msg-
checksum).
Paragraph (version A):
The Message Context can indicate whether or not this Message is the
Final Message on a Connection.  For any Message that is marked as
Final, the application can assume that there will be no more Messages
received on the Connection once the Message has been completely
delivered.  This corresponds to the Final property that may be marked
on a sent Message, see msg-final.
Paragraph (version A):
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 B):
The Message Context can indicate whether or not this Message is the
Final Message on a Connection.  For any Message that is marked as
Final, the application can assume that there will be no more Messages
received on the Connection once the Message has been completely
delivered.  This corresponds to the "final" property that may be
marked on a sent Message, see msg-final.
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):
"noFragmentation": Setting this avoids network-layer
fragmentation.  Messages exceeding the transport's current
estimate of its maximum packet size (the
singularTransmissionMsgMaxLen Connection Property) can result in
transport segmentation when permitted, or generate an error.  When
used with transports running over IP version 4 the Don't Fragment
bit will be set to avoid on-path IP fragmentation (RFC8304).
Paragraph (version A):
"noSegmentation": When set, this property limits the message size
to the transport's current estimate of its maximum packet size
(the singularTransmissionMsgMaxLen Connection Property).  Messages
larger than this size generate an error.  Setting this avoids
transport-layer segmentation and network-layer fragmentation.
When used with transports running over IP version 4 the Don't
Fragment bit will be set to avoid on-path IP fragmentation
(RFC8304).
Paragraph (version B):
"noFragmentation": Setting this avoids network-layer
fragmentation.  Messages exceeding the transport's current
estimate of its maximum packet size (the
"singularTransmissionMsgMaxLen" Connection Property) can result in
transport segmentation when permitted, or generate an error.  When
used with transports running over IP version 4 the Don't Fragment
bit will be set to avoid on-path IP fragmentation (RFC8304).
Paragraph (version B):
"noSegmentation": When set, this property limits the message size
to the transport's current estimate of its maximum packet size
(the "singularTransmissionMsgMaxLen" Connection Property).
Messages larger than this size generate an error.  Setting this
avoids transport-layer segmentation and network-layer
fragmentation.  When used with transports running over IP version
4 the Don't Fragment bit will be set to avoid on-path IP
fragmentation (RFC8304).
Paragraph (version A):
the Transport Services API mappings for MPTCP are identical to TCP.
MPTCP adds support for multipath properties, such as "multipath" and
"multipath-policy".
Paragraph (version B):
the Transport Services API mappings for MPTCP are identical to TCP.
MPTCP adds support for multipath properties, such as "multipath" and
"multipathPolicy".