Draft: draft-ietf-taps-interface

Commentary: de - duplicates some properties in 7.3 . and 12 moves up some message properties missing in 7.3 . make type definition consistent across all properties This ignores Classification and Applicability labels which are subject to removal in another PR moving Selection and Connections properties up . Section 12.3 will most likely be replaces with a table then . 
 I want to convert 12.3 to a table once all properties have been moved up . I guess it is useful to include types in the table and put relations as footnotes into the table . 
 I think I understand " connection niceness " , I do know how that would be used . As I look through things today , I 'm less sure about how expressing message niceness is actually needed , and if so - what sort of machinery you 'd need to properly handle a message niceness property . My own mental model is that a sender that cares about " niceness " will keep its output queue low , and that it can itself maintain some notions about which threads / messages / whatever are most important to send next . What does the stack need to do in addition ? Maybe I am really missing something here ( please tell me ) . 
 I think per - message niceness is an artefact of not being sure how this will map onto multi - streaming . E.g. , if this is NOT implemented as " one ( TAPS ) Connection = one stream of a transport " , then maybe multiple streams could be used underneath the API , and per - message niceness could be used to assign a message to a stream based on a Niceness value . Then , however , per - connection Niceness becomes irrelevant . My conclusion is that we should keep it in there for now , but mark it with a " DISCUSS " so we remember to decide for either per - message or per - connection Niceness depending on how we intend to implement multi - streaming . ( my personal preference is to have per - connection Niceness only , and hence map " one ( TAPS ) connection is one stream " ) 
 let 's land this now , though , and have the niceness discussion in another issue / at the interim ... 
 I see I 'm late for the party ... but just for the record , now that I managed to give it a close read , I also agree with this :) 
 Alright , then I think this is ready to is fine
Paragraph (version A):
Changing one of these Protocol Properties on one Connection in the
group changes it for all others.  Per-Message Protocol Properties,
however, are not entangled.  For example, changing "Timeout for
aborting Connection" (see timeout) on one Connection in a group will
automatically change this Protocol Property for all Connections in
the group in the same way.  However, changing "Lifetime" (see send-
lifetime) of a Message will only affect a single Message on a single
Connection, entangled or not.
Paragraph (version B):
Changing one of these Protocol Properties on one Connection in the
group changes it for all others.  Per-Message Protocol Properties,
however, are not entangled.  For example, changing "Timeout for
aborting Connection" (see timeout) on one Connection in a group will
automatically change this Protocol Property for all Connections in
the group in the same way.  However, changing "Lifetime" (see msg-
lifetime) of a Message will only affect a single Message on a single
Connection, entangled or not.
Paragraph (version A):
The Expired Event occurs when a previous Send Action expired before
completion; i.e. when the Message was not sent before its Lifetime
(see send-lifetime) expired.  This is separate from SendError, as it
is an expected behavior for partially reliable transports.  The
Expired Event contains an implementation-specific reference to the
Message to which it applies.
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 an implementation-specific reference to the
Message to which it applies.
Paragraph (version A):
This property is a numeric (non-negative) value that represents an
unbounded hierarchy of priorities.  It can specify the priority of a
Message, relative to other Messages sent over the same Connection.
Paragraph (version B):
This property represents an unbounded hierarchy of priorities.  It
can specify the priority of a Message, relative to other Messages
sent over the same Connection.
Paragraph (version A):
Ordered is a boolean property.  If true, it specifies that a Message
should be delivered to the other side after the previous Message
which was passed to the same Connection via the Send Action.  If
false, the Message may be delivered 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.
Paragraph (version A):
Idempotent is a boolean property.  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 A):
Final is a boolean property.  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, it specifies that a Message should be delivered to the other
side after the previous Message which was passed to the same
Connection via the Send Action.  If false, the Message may be
delivered 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.
Paragraph (version B):
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, 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 A):
This numeric property specifies the length of the section of the
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.  By
default, the entire Message is protected by a checksum.  A value of 0
means that no checksum is required, and a special value (e.g. -1) can
be used to indicate the default.  Only full coverage is guaranteed,
any other requests are advisory.
Paragraph (version B):
This property specifies the length of the section of the 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.  By default,
the entire Message is protected by a checksum.  A value of 0 means
that no checksum is required, and a special value (e.g. -1) can be
used to indicate the default.  Only full coverage is guaranteed, any
other requests are advisory.
Paragraph (version A):
The message passed to InitiateWithIdempotentSend() is, as suggested
by the name, considered to be idempotent (see send-idempotent)
regardless of declared message properties or defaults.  If protocol
stacks supporting 0-RTT establishment with idempotent data are
available on the Preconnection, then 0-RTT establishment may be used
with the given message when establishing candidate connections.  For
a non-idemponent initial message, or when the selected stack(s) do
not support 0-RTT establishment, InitiateWithIdempotentSend is
identical to Initiate() followed by Send().
Paragraph (version B):
The message passed to InitiateWithIdempotentSend() is, as suggested
by the name, considered to be idempotent (see msg-idempotent)
regardless of declared message properties or defaults.  If protocol
stacks supporting 0-RTT establishment with idempotent data are
available on the Preconnection, then 0-RTT establishment may be used
with the given message when establishing candidate connections.  For
a non-idemponent initial message, or when the selected stack(s) do
not support 0-RTT establishment, InitiateWithIdempotentSend is
identical to Initiate() followed by Send().
Paragraph (version A):
See final.
Paragraph (version B):
Boolean Message Property - see final.
Paragraph (version A):
See msg-ordered.
Paragraph (version B):
Boolean Message Property - see msg-ordered.
Paragraph (version A):
This property specifies whether an application would like to supply a
Message to the transport protocol before Connection establishment,
which will then be reliably transferred to the other side before or
during Connection establishment, potentially multiple times.  See
also send-idempotent.  The default is to not have this option.
Paragraph (version A):
See msg-idempotent.  The application can query the maximum size of a
message that can be sent idempotent, see size-idempotent.
Paragraph (version B):
This property specifies whether an application would like to supply a
Message to the transport protocol before Connection establishment,
which will then be reliably transferred to the other side before or
during Connection establishment, potentially multiple times.  See
also msg-idempotent.  The default is to not have this option.
Paragraph (version B):
Boolean Message Property - see msg-idempotent.
Paragraph (version A):
See msg-checksum.
Paragraph (version B):
Integer Message Property - see msg-checksum.
Paragraph (version B):
Integer Message Property - see msg-niceness.
Paragraph (version B):
Note that this property is not a per-message override of the
connection Niceness - see conn-niceness.  Both Niceness properties
may interact, but can be used indepentendly and be realized by
different mechanisms.
Paragraph (version A):
This property represents the maximum Message size that can be sent
before or during Connection establishment, see also send-idempotent.
It is given in Bytes.  This property is read-only.
Paragraph (version B):
This property represents the maximum Message size that can be sent
before or during Connection establishment, see also msg-idempotent.
It is given in Bytes.  This property is read-only.
Paragraph (version A):
See msg-lifetime.
Paragraph (version B):
Integer Message Property - see msg-lifetime.