Draft: draft-ietf-taps-interface

Commentary: ... such as : using CamlCase instead of dashes for property names . Also : fixes consistency problem of apostrophs / quotation marks ( ` vs " ) 
 I 'll just merge this now , to avoid conflicts with a new PR I 'm writing ( I 'd like to continue using camlCase for property names ) . Moving to camlCase has been discussed on the list , and the other things here - ensuring uniform appearance of quotation marks , and replacing " -1 " with special values - seem quite non - controversial . 
 I am going to query /bandwidth efficiency/ - since this sounds like it should be measured in b / Hz , which is n't at all what this draft are talking about . In fact , I did not see anything in the text about the efficiency or the use of bandwith ... as I read , it is all about capacity sharing tradeoffs . I suspect the tyerm should be " capacity - seeking " or we just say latency - seeking rather than capacity - seeking ? And while I am digging here ... how about /to use multiple paths in parallel in order to maximize bandwidth / to use multiple paths in parallel in maximize use of available capacity/.
Paragraph (version B):
For types Integer and Numeric, special values can be defined per
property; it is up to implementations how these special values are
represented (e.g., by using -1 for an otherwise non-negative value).
Paragraph (version A):
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 this 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 "msg-ordered" 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 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 this 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):
This property specifies the minimum 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.  A
value of 0 means that no checksum is required, and -1 means that the
entire Message is protected by a checksum.  Only full coverage is
guaranteed, any other requests are advisory, meaning that full
coverage is applied anyway.
Paragraph (version B):
This property specifies the minimum 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.  A
value of 0 means that no checksum is required, and "Full Coverage"
means that the entire Message is protected by a checksum.  Only "Full
Coverage" is guaranteed, any other requests are advisory, meaning
that "Full Coverage" is applied anyway.
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 with the Selection Property 'Configure Per-Message
Reliability' enabled.  When this is not the case, changing it will
generate an error.  Disabling this property indicates that the
transport system may disable retransmissions or other reliability
mechanisms for this particular Message, but such disabling is not
guaranteed.
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 with the Selection Property "Configure Per-Message
Reliability" enabled.  When this is not the case, changing it will
generate an error.  Disabling this property indicates that the
transport system may disable retransmissions or other reliability
mechanisms for this particular Message, but such disabling is not
guaranteed.
Paragraph (version A):
Once a Connection is established, it can be used for receiving data.
As with sending, data is received in terms of 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 system before Receive requests are
issued, ensuing Receive requests will first operate on these Messages
before awaiting any further Messages.
Paragraph (version B):
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, data is received in terms
of 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 system
before Receive requests are issued, ensuing Receive requests will
first operate on these Messages before awaiting any further Messages.
Paragraph (version A):
This property specifies after how many retransmissions to inform the
application about "Excessive Retransmissions".  The special value -1
means that this notification is disabled.
Paragraph (version A):
This property specifies the part of the received data that needs to
be covered by a checksum.  It is given in Bytes.  A value of 0 means
that no checksum is required, and the special value -1 indicates full
checksum coverage.
Paragraph (version B):
This property specifies after how many retransmissions to inform the
application about "Excessive Retransmissions".
Paragraph (version B):
This property specifies the part of the received data that needs to
be covered by a checksum.  It is given in Bytes.  A value of 0 means
that no checksum is required.
Paragraph (version A):
This property specifies how long to wait before deciding that a
Connection has failed when trying to reliably deliver data to the
destination.  Adjusting this Property will only take effect when the
underlying stack supports reliability.  The special value -1 means
that this timeout is not scheduled to happen.  This can be a valid
choice with unreliable data transfer (e.g., when UDP is the
underlying transport protocol).
Paragraph (version B):
This property specifies how long to wait before deciding that a
Connection has failed when trying to reliably deliver data to the
destination.  Adjusting this Property will only take effect when the
underlying stack supports reliability.  The special value "Disabled"
means that this timeout is not scheduled to happen.  This can be a
valid choice with unreliable data transfer (e.g., when UDP is the
underlying transport protocol).
Paragraph (version A):
This property specifies the desired network treatment for traffic
sent by the application and the tradeoffs the application is prepared
to make in path and protocol selection to receive that desired
treatment.  When the capacity profile is set to a value other than
Default, the transport system SHOULD select paths and configure
protocols to optimize the tradeoff between delay, delay variation,
and bandwidth efficiency based on the capacity profile specified.
How this is realized is implementation-specific.  The Capacity
Profile MAY also be used to set priorities on the wire for Protocol
Stacks supporting prioritization.  Recommendations for use with DSCP
are provided below for each profile; note that when a Connection is
multiplexed, the guidelines in Section 6 of RFC7657 apply.
Paragraph (version B):
This property specifies the desired network treatment for traffic
sent by the application and the tradeoffs the application is prepared
to make in path and protocol selection to receive that desired
treatment.  When the capacity profile is set to a value other than
Default, the transport system SHOULD select paths and configure
protocols to optimize the tradeoff between delay, delay variation,
and efficient use of the available capacity based on the capacity
profile specified.  How this is realized is implementation-specific.
The Capacity Profile MAY also be used to set priorities on the wire
for Protocol Stacks supporting prioritization.  Recommendations for
use with DSCP are provided below for each profile; note that when a
Connection is multiplexed, the guidelines in Section 6 of RFC7657
apply.
Paragraph (version A):
The application is interactive, and prefers loss to latency.
Response time should be optimized at the expense of bandwidth
efficiency and delay variation when sending on this connection.
This can be used by the system to disable the coalescing of
multiple small Messages into larger packets (Nagle's algorithm);
to prefer immediate acknowledgment from the peer endpoint when
supported by the underlying transport; and so on.  Transport
system implementations that map the requested capacity profile
onto per-connection DSCP signaling without multiplexing SHOULD
assign a DSCP Assured Forwarding (AF41,AF42,AF43,AF44) RFC2597
PHB.  Inelastic traffic that is expected to conform to the
configured network service rate could be mapped to the DSCP
Expedited Forwarding RFC3246 or RFC5865 PHBs.
Paragraph (version A):
The application prefers loss to latency but is not interactive.
Response time should be optimized at the expense of bandwidth
efficiency and delay variation 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 application expects to send/receive data at a constant rate
after Connection establishment.  Delay and delay variation should
be minimized at the expense of bandwidth efficiency.  This implies
that the Connection may fail if the desired rate cannot be
maintained across the Path.  A transport may interpret this
capacity profile as preferring a circuit breaker RFC8084 to a
rate-adaptive congestion controller.  Transport system
implementations that map the requested capacity profile onto per-
connection DSCP signaling without multiplexing SHOULD assign a
DSCP Assured Forwarding (AF31,AF32,AF33,AF34) RFC2597 PHB.
Paragraph (version B):
The application is interactive, and prefers loss to latency.
Response time should be optimized at the expense of delay
variation and efficient use of the available capacity when sending
on this connection.  This can be used by the system to disable the
coalescing of multiple small Messages into larger packets (Nagle's
algorithm); to prefer immediate acknowledgment from the peer
endpoint when supported by the underlying transport; and so on.
Transport system implementations that map the requested capacity
profile onto per-connection DSCP signaling without multiplexing
SHOULD assign a DSCP Assured Forwarding (AF41,AF42,AF43,AF44)
RFC2597 PHB.  Inelastic traffic that is expected to conform to the
configured network service rate could be mapped to the DSCP
Expedited Forwarding RFC3246 or RFC5865 PHBs.
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 B):
The application expects to send/receive data at a constant rate
after Connection establishment.  Delay and delay variation should
be minimized at the expense of efficient use of the available
capacity.  This implies that the Connection may fail if the
desired rate cannot be maintained across the Path.  A transport
may interpret this capacity profile as preferring a circuit
breaker RFC8084 to a rate-adaptive congestion controller.
Transport system implementations that map the requested capacity
profile onto per-connection DSCP signaling without multiplexing
SHOULD assign a DSCP Assured Forwarding (AF31,AF32,AF33,AF34)
RFC2597 PHB.
Paragraph (version A):
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 data transfer useful.  It is given in bits per
second.  The special value -1 indicates that no bound is specified.
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 data transfer useful.  It is given in bits per
second.  The special value "Unlimited" indicates that no bound is
specified.