draft-ietf-taps-interface-08.txt   draft-ietf-taps-interface-09.txt 
skipping to change at page 1, line 24 skipping to change at page 1, line 24
University of Glasgow University of Glasgow
P. Tiesel P. Tiesel
TU Berlin TU Berlin
C. Wood C. Wood
Cloudflare Cloudflare
T. Pauly T. Pauly
Apple Inc. Apple Inc.
July 27, 2020 July 27, 2020
An Abstract Application Layer Interface to Transport Services An Abstract Application Layer Interface to Transport Services
draft-ietf-taps-interface-08 draft-ietf-taps-interface-09
Abstract Abstract
This document describes an abstract application programming This document describes an abstract application programming
interface, API, to the transport layer, following the Transport interface, API, to the transport layer, following the Transport
Services Architecture. It supports the asynchronous, atomic Services Architecture. It supports the asynchronous, atomic
transmission of messages over transport protocols and network paths transmission of messages over transport protocols and network paths
dynamically selected at runtime. It is intended to replace the dynamically selected at runtime. It is intended to replace the
traditional BSD sockets API as the common interface to the transport traditional BSD sockets API as the common interface to the transport
layer, in an environment where endpoints could select from multiple layer, in an environment where endpoints could select from multiple
skipping to change at page 2, line 30 skipping to change at page 2, line 30
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Terminology and Notation . . . . . . . . . . . . . . . . . . 5 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 5
3. Overview of Interface Design . . . . . . . . . . . . . . . . 6 3. Overview of Interface Design . . . . . . . . . . . . . . . . 6
4. API Summary . . . . . . . . . . . . . . . . . . . . . . . . . 7 4. API Summary . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.1. Usage Examples . . . . . . . . . . . . . . . . . . . . . 8 4.1. Usage Examples . . . . . . . . . . . . . . . . . . . . . 7
4.1.1. Server Example . . . . . . . . . . . . . . . . . . . 8 4.1.1. Server Example . . . . . . . . . . . . . . . . . . . 8
4.1.2. Client Example . . . . . . . . . . . . . . . . . . . 9 4.1.2. Client Example . . . . . . . . . . . . . . . . . . . 9
4.1.3. Peer Example . . . . . . . . . . . . . . . . . . . . 10 4.1.3. Peer Example . . . . . . . . . . . . . . . . . . . . 10
4.2. Transport Properties . . . . . . . . . . . . . . . . . . 11 4.2. Transport Properties . . . . . . . . . . . . . . . . . . 11
4.2.1. Transport Property Names . . . . . . . . . . . . . . 12 4.2.1. Transport Property Names . . . . . . . . . . . . . . 12
4.2.2. Transport Property Types . . . . . . . . . . . . . . 13 4.2.2. Transport Property Types . . . . . . . . . . . . . . 13
4.3. Scope of the Interface Definition . . . . . . . . . . . . 14 4.3. Scope of the Interface Definition . . . . . . . . . . . . 14
5. Pre-Establishment Phase . . . . . . . . . . . . . . . . . . . 15 5. Pre-Establishment Phase . . . . . . . . . . . . . . . . . . . 15
5.1. Specifying Endpoints . . . . . . . . . . . . . . . . . . 15 5.1. Specifying Endpoints . . . . . . . . . . . . . . . . . . 15
5.2. Specifying Transport Properties . . . . . . . . . . . . . 18 5.2. Specifying Transport Properties . . . . . . . . . . . . . 18
skipping to change at page 3, line 20 skipping to change at page 3, line 20
5.2.17. Notification of ICMP soft error message arrival . . . 27 5.2.17. Notification of ICMP soft error message arrival . . . 27
5.2.18. Initiating side is not the first to write . . . . . . 27 5.2.18. Initiating side is not the first to write . . . . . . 27
5.3. Specifying Security Parameters and Callbacks . . . . . . 28 5.3. Specifying Security Parameters and Callbacks . . . . . . 28
5.3.1. Pre-Connection Parameters . . . . . . . . . . . . . . 28 5.3.1. Pre-Connection Parameters . . . . . . . . . . . . . . 28
5.3.2. Connection Establishment Callbacks . . . . . . . . . 29 5.3.2. Connection Establishment Callbacks . . . . . . . . . 29
6. Establishing Connections . . . . . . . . . . . . . . . . . . 29 6. Establishing Connections . . . . . . . . . . . . . . . . . . 29
6.1. Active Open: Initiate . . . . . . . . . . . . . . . . . . 30 6.1. Active Open: Initiate . . . . . . . . . . . . . . . . . . 30
6.2. Passive Open: Listen . . . . . . . . . . . . . . . . . . 31 6.2. Passive Open: Listen . . . . . . . . . . . . . . . . . . 31
6.3. Peer-to-Peer Establishment: Rendezvous . . . . . . . . . 32 6.3. Peer-to-Peer Establishment: Rendezvous . . . . . . . . . 32
6.4. Connection Groups . . . . . . . . . . . . . . . . . . . . 33 6.4. Connection Groups . . . . . . . . . . . . . . . . . . . . 33
7. Sending Data . . . . . . . . . . . . . . . . . . . . . . . . 35 7. Managing Connections . . . . . . . . . . . . . . . . . . . . 35
7.1. Basic Sending . . . . . . . . . . . . . . . . . . . . . . 35 7.1. Generic Connection Properties . . . . . . . . . . . . . . 36
7.2. Sending Replies . . . . . . . . . . . . . . . . . . . . . 36 7.1.1. Retransmission Threshold Before Excessive
7.3. Send Events . . . . . . . . . . . . . . . . . . . . . . . 36 Retransmission Notification . . . . . . . . . . . . . 37
7.3.1. Sent . . . . . . . . . . . . . . . . . . . . . . . . 37 7.1.2. Required Minimum Corruption Protection Coverage for
7.3.2. Expired . . . . . . . . . . . . . . . . . . . . . . . 37 Receiving . . . . . . . . . . . . . . . . . . . . . . 37
7.3.3. SendError . . . . . . . . . . . . . . . . . . . . . . 37 7.1.3. Priority (Connection) . . . . . . . . . . . . . . . . 37
7.4. Message Contexts . . . . . . . . . . . . . . . . . . . . 37 7.1.4. Timeout for Aborting Connection . . . . . . . . . . . 37
7.5. Message Properties . . . . . . . . . . . . . . . . . . . 38 7.1.5. Connection Group Transmission Scheduler . . . . . . . 38
7.5.1. Lifetime . . . . . . . . . . . . . . . . . . . . . . 39 7.1.6. Capacity Profile . . . . . . . . . . . . . . . . . . 38
7.5.2. Priority . . . . . . . . . . . . . . . . . . . . . . 40 7.1.7. Policy for using Multi-Path Transports . . . . . . . 40
7.5.3. Ordered . . . . . . . . . . . . . . . . . . . . . . . 40 7.1.8. Bounds on Send or Receive Rate . . . . . . . . . . . 40
7.5.4. Safely Replayable . . . . . . . . . . . . . . . . . . 41 7.1.9. Read-only Connection Properties . . . . . . . . . . . 41
7.5.5. Final . . . . . . . . . . . . . . . . . . . . . . . . 41 7.2. TCP-specific Properties: User Timeout Option (UTO) . . . 42
7.5.6. Corruption Protection Length . . . . . . . . . . . . 42 7.2.1. Advertised User Timeout . . . . . . . . . . . . . . . 42
7.5.7. Reliable Data Transfer (Message) . . . . . . . . . . 42 7.2.2. User Timeout Enabled . . . . . . . . . . . . . . . . 42
7.5.8. Message Capacity Profile Override . . . . . . . . . . 42 7.2.3. Timeout Changeable . . . . . . . . . . . . . . . . . 43
7.5.9. No Fragmentation . . . . . . . . . . . . . . . . . . 43 7.3. Connection Lifecycle Events . . . . . . . . . . . . . . . 43
7.6. Partial Sends . . . . . . . . . . . . . . . . . . . . . . 43 7.3.1. Soft Errors . . . . . . . . . . . . . . . . . . . . . 43
7.7. Batching Sends . . . . . . . . . . . . . . . . . . . . . 44 7.3.2. Excessive retransmissions . . . . . . . . . . . . . . 43
7.8. Send on Active Open: InitiateWithSend . . . . . . . . . . 44 8. Data Transfer . . . . . . . . . . . . . . . . . . . . . . . . 43
8. Receiving Data . . . . . . . . . . . . . . . . . . . . . . . 44 8.1. Messages and Framers . . . . . . . . . . . . . . . . . . 43
8.1. Enqueuing Receives . . . . . . . . . . . . . . . . . . . 45 8.1.1. Message Contexts . . . . . . . . . . . . . . . . . . 44
8.2. Receive Events . . . . . . . . . . . . . . . . . . . . . 46 8.1.2. Message Framers . . . . . . . . . . . . . . . . . . . 44
8.2.1. Received . . . . . . . . . . . . . . . . . . . . . . 46 8.1.3. Message Properties . . . . . . . . . . . . . . . . . 46
8.2.2. ReceivedPartial . . . . . . . . . . . . . . . . . . . 46 8.2. Sending Data . . . . . . . . . . . . . . . . . . . . . . 51
8.2.3. ReceiveError . . . . . . . . . . . . . . . . . . . . 47 8.2.1. Basic Sending . . . . . . . . . . . . . . . . . . . . 52
8.3. Receive Message Properties . . . . . . . . . . . . . . . 47 8.2.2. Sending Replies . . . . . . . . . . . . . . . . . . . 52
8.3.1. UDP(-Lite)-specific Property: ECN . . . . . . . . . . 47 8.2.3. Send Events . . . . . . . . . . . . . . . . . . . . . 52
8.3.2. Early Data . . . . . . . . . . . . . . . . . . . . . 48 8.2.4. Partial Sends . . . . . . . . . . . . . . . . . . . . 54
8.3.3. Receiving Final Messages . . . . . . . . . . . . . . 48 8.2.5. Batching Sends . . . . . . . . . . . . . . . . . . . 54
9. Message Framers . . . . . . . . . . . . . . . . . . . . . . . 48 8.2.6. Send on Active Open: InitiateWithSend . . . . . . . . 55
9.1. Adding Message Framers to Connections . . . . . . . . . . 50
9.2. Framing Meta-Data . . . . . . . . . . . . . . . . . . . . 50 8.3. Receiving Data . . . . . . . . . . . . . . . . . . . . . 55
10. Managing Connections . . . . . . . . . . . . . . . . . . . . 50 8.3.1. Enqueuing Receives . . . . . . . . . . . . . . . . . 56
10.1. Generic Connection Properties . . . . . . . . . . . . . 52 8.3.2. Receive Events . . . . . . . . . . . . . . . . . . . 56
10.1.1. Retransmission Threshold Before Excessive 8.3.3. Receive Message Properties . . . . . . . . . . . . . 58
Retransmission Notification . . . . . . . . . . . . 52 9. Connection Termination . . . . . . . . . . . . . . . . . . . 59
10.1.2. Required Minimum Corruption Protection Coverage for 10. Connection State and Ordering of Operations and Events . . . 60
Receiving . . . . . . . . . . . . . . . . . . . . . 52 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 61
10.1.3. Priority (Connection) . . . . . . . . . . . . . . . 53 12. Security Considerations . . . . . . . . . . . . . . . . . . . 61
10.1.4. Timeout for Aborting Connection . . . . . . . . . . 53 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 63
10.1.5. Connection Group Transmission Scheduler . . . . . . 53 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 63
10.1.6. Capacity Profile . . . . . . . . . . . . . . . . . . 54 14.1. Normative References . . . . . . . . . . . . . . . . . . 63
10.1.7. Policy for using Multi-Path Transports . . . . . . . 55 14.2. Informative References . . . . . . . . . . . . . . . . . 64
10.1.8. Bounds on Send or Receive Rate . . . . . . . . . . . 56 Appendix A. Convenience Functions . . . . . . . . . . . . . . . 67
10.1.9. Read-only Connection Properties . . . . . . . . . . 56 A.1. Adding Preference Properties . . . . . . . . . . . . . . 67
10.2. TCP-specific Properties: User Timeout Option (UTO) . . . 57
10.2.1. Advertised User Timeout . . . . . . . . . . . . . . 58
10.2.2. User Timeout Enabled . . . . . . . . . . . . . . . . 58
10.2.3. Timeout Changeable . . . . . . . . . . . . . . . . . 58
10.3. Connection Lifecycle Events . . . . . . . . . . . . . . 58
10.3.1. Soft Errors . . . . . . . . . . . . . . . . . . . . 59
10.3.2. Excessive retransmissions . . . . . . . . . . . . . 59
11. Connection Termination . . . . . . . . . . . . . . . . . . . 59
12. Connection State and Ordering of Operations and Events . . . 60
13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 61
14. Security Considerations . . . . . . . . . . . . . . . . . . . 61
15. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 62
16. References . . . . . . . . . . . . . . . . . . . . . . . . . 63
16.1. Normative References . . . . . . . . . . . . . . . . . . 63
16.2. Informative References . . . . . . . . . . . . . . . . . 64
Appendix A. Convenience Functions . . . . . . . . . . . . . . . 66
A.1. Adding Preference Properties . . . . . . . . . . . . . . 66
A.2. Transport Property Profiles . . . . . . . . . . . . . . . 67 A.2. Transport Property Profiles . . . . . . . . . . . . . . . 67
A.2.1. reliable-inorder-stream . . . . . . . . . . . . . . . 67 A.2.1. reliable-inorder-stream . . . . . . . . . . . . . . . 67
A.2.2. reliable-message . . . . . . . . . . . . . . . . . . 67 A.2.2. reliable-message . . . . . . . . . . . . . . . . . . 67
A.2.3. unreliable-datagram . . . . . . . . . . . . . . . . . 68 A.2.3. unreliable-datagram . . . . . . . . . . . . . . . . . 68
Appendix B. Relationship to the Minimal Set of Transport Appendix B. Relationship to the Minimal Set of Transport
Services for End Systems . . . . . . . . . . . . . . 68 Services for End Systems . . . . . . . . . . . . . . 68
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 72 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 72
1. Introduction 1. Introduction
skipping to change at page 8, line 10 skipping to change at page 7, line 41
in the form of Messages. The interface supports the preservation of in the form of Messages. The interface supports the preservation of
message boundaries both via explicit Protocol Stack support, and via message boundaries both via explicit Protocol Stack support, and via
application support through a Message Framer which finds message application support through a Message Framer which finds message
boundaries in a stream. Messages are received asynchronously through boundaries in a stream. Messages are received asynchronously through
event handlers registered by the application. Errors and other event handlers registered by the application. Errors and other
notifications also happen asynchronously on the Connection. It is notifications also happen asynchronously on the Connection. It is
not necessary for an application to handle all events; some events not necessary for an application to handle all events; some events
may have implementation-specific default handlers. The application may have implementation-specific default handlers. The application
should not assume that ignoring events (e.g. errors) is always safe. should not assume that ignoring events (e.g. errors) is always safe.
Section 5, Section 6, Section 7, Section 8, and Section 11 describe Section 5, Section 6, Section 8.2, Section 8.3, and Section 9
the details of application interaction with Objects through Actions describe the details of application interaction with Objects through
and Events in each phase of a Connection, following the phases (Pre- Actions and Events in each phase of a Connection, following the
Establishment, Establishment, Data Transfer, and Termination) phases (Pre-Establishment, Establishment, Data Transfer, and
described in Section 4.1 of [I-D.ietf-taps-arch]. Termination) described in Section 4.1 of [I-D.ietf-taps-arch].
4.1. Usage Examples 4.1. Usage Examples
The following usage examples illustrate how an application might use The following usage examples illustrate how an application might use
a Transport Services Interface to: a Transport Services Interface to:
o Act as a server, by listening for incoming connections, receiving o Act as a server, by listening for incoming connections, receiving
requests, and sending responses, see Section 4.1.1. requests, and sending responses, see Section 4.1.1.
o Act as a client, by connecting to a remote endpoint using o Act as a client, by connecting to a remote endpoint using
skipping to change at page 8, line 44 skipping to change at page 8, line 28
Preservation of data ordering, and Preservation of Message Preservation of data ordering, and Preservation of Message
Boundaries. In this case, the application can choose to receive only Boundaries. In this case, the application can choose to receive only
complete messages. complete messages.
If none of the available transport protocols provides Preservation of If none of the available transport protocols provides Preservation of
Message Boundaries, but there is a transport protocol that provides a Message Boundaries, but there is a transport protocol that provides a
reliable ordered byte stream, an application may receive this byte reliable ordered byte stream, an application may receive this byte
stream as partial Messages and transform it into application-layer stream as partial Messages and transform it into application-layer
Messages. Alternatively, an application may provide a Message Messages. Alternatively, an application may provide a Message
Framer, which can transform a byte stream into a sequence of Messages Framer, which can transform a byte stream into a sequence of Messages
(Section 9). (Section 8.1.2).
4.1.1. Server Example 4.1.1. Server Example
This is an example of how an application might listen for incoming This is an example of how an application might listen for incoming
Connections using the Transport Services Interface, receive a Connections using the Transport Services Interface, receive a
request, and send a response. request, and send a response.
LocalSpecifier := NewLocalEndpoint() LocalSpecifier := NewLocalEndpoint()
LocalSpecifier.WithInterface("any") LocalSpecifier.WithInterface("any")
LocalSpecifier.WithService("https") LocalSpecifier.WithService("https")
skipping to change at page 12, line 9 skipping to change at page 12, line 9
Each application using the Transport Services Interface declares its Each application using the Transport Services Interface declares its
preferences for how the transport service should operate using preferences for how the transport service should operate using
properties at each stage of the lifetime of a connection using properties at each stage of the lifetime of a connection using
Transport Properties, as defined in [I-D.ietf-taps-arch]. Transport Properties, as defined in [I-D.ietf-taps-arch].
Transport Properties are divided into Selection, Connection, and Transport Properties are divided into Selection, Connection, and
Message Properties. Selection Properties (see Section 5.2) can only Message Properties. Selection Properties (see Section 5.2) can only
be set during pre-establishment. They are only used to specify which be set during pre-establishment. They are only used to specify which
paths and protocol stacks can be used and are preferred by the paths and protocol stacks can be used and are preferred by the
application. Connection Properties (see Section 10.1) can also be application. Connection Properties (see Section 7.1) can also be set
set during pre-establishment but may be changed later. They are used during pre-establishment but may be changed later. They are used to
to inform decisions made during establishment and to fine-tune the inform decisions made during establishment and to fine-tune the
established connection. established connection.
The behavior of the selected protocol stack(s) when sending Messages The behavior of the selected protocol stack(s) when sending Messages
is controlled by Message Properties (see Section 7.5). is controlled by Message Properties (see Section 8.1.3).
All Transport Properties, regardless of the phase in which they are All Transport Properties, regardless of the phase in which they are
used, are organized within a single namespace. This enables setting used, are organized within a single namespace. This enables setting
them as defaults in earlier stages and querying them in later stages: them as defaults in earlier stages and querying them in later stages:
o Connection Properties can be set on Preconnections o Connection Properties can be set on Preconnections
o Message Properties can be set on Preconnections, Connections and o Message Properties can be set on Preconnections, Connections and
Messages Messages
skipping to change at page 15, line 18 skipping to change at page 15, line 18
The Pre-Establishment phase allows applications to specify properties The Pre-Establishment phase allows applications to specify properties
for the Connections they are about to make, or to query the API about for the Connections they are about to make, or to query the API about
potential Connections they could make. potential Connections they could make.
A Preconnection Object represents a potential Connection. It has A Preconnection Object represents a potential Connection. It has
state that describes properties of a Connection that might exist in state that describes properties of a Connection that might exist in
the future. This state comprises Local Endpoint and Remote Endpoint the future. This state comprises Local Endpoint and Remote Endpoint
Objects that denote the endpoints of the potential Connection (see Objects that denote the endpoints of the potential Connection (see
Section 5.1), the Selection Properties (see Section 5.2), any Section 5.1), the Selection Properties (see Section 5.2), any
preconfigured Connection Properties (Section 10.1), and the security preconfigured Connection Properties (Section 7.1), and the security
parameters (see Section 5.3): parameters (see Section 5.3):
Preconnection := NewPreconnection(LocalEndpoint?, Preconnection := NewPreconnection(LocalEndpoint?,
RemoteEndpoint?, RemoteEndpoint?,
TransportProperties, TransportProperties,
SecurityParams) SecurityParams)
The Local Endpoint MUST be specified if the Preconnection is used to The Local Endpoint MUST be specified if the Preconnection is used to
Listen() for incoming Connections, but is OPTIONAL if it is used to Listen() for incoming Connections, but is OPTIONAL if it is used to
Initiate() connections. If no Local Endpoint is specified, the Initiate() connections. If no Local Endpoint is specified, the
Transport System will assign an ephemeral local port to the Transport System will assign an ephemeral local port to the
Connection. The Remote Endpoint MUST be specified if the Connection. The Remote Endpoint MUST be specified if the
Preconnection is used to Initiate() Connections, but is OPTIONAL if Preconnection is used to Initiate() Connections, but is OPTIONAL if
it is used to Listen() for incoming Connections. The Local Endpoint it is used to Listen() for incoming Connections. The Local Endpoint
and the Remote Endpoint MUST both be specified if a peer-to-peer and the Remote Endpoint MUST both be specified if a peer-to-peer
Rendezvous is to occur based on the Preconnection. Rendezvous is to occur based on the Preconnection.
Transport Properties MUST always be specified while security Transport Properties MUST always be specified while security
parameters are OPTIONAL. parameters are OPTIONAL.
If Message Framers are used (see Section 9), they MUST be added to If Message Framers are used (see Section 8.1.2), they MUST be added
the Preconnection during pre-establishment. to the Preconnection during pre-establishment.
5.1. Specifying Endpoints 5.1. Specifying Endpoints
The transport services API uses the Local Endpoint and Remote The transport services API uses the Local Endpoint and Remote
Endpoint Objects to refer to the endpoints of a transport connection. Endpoint Objects to refer to the endpoints of a transport connection.
Actions on these Objects can be used to represent various different Actions on these Objects can be used to represent various different
types of endpoint identifiers, such as IP addresses, DNS names, and types of endpoint identifiers, such as IP addresses, DNS names, and
interface names, as well as port numbers and service names. interface names, as well as port numbers and service names.
Specify a Remote Endpoint using a hostname and service name: Specify a Remote Endpoint using a hostname and service name:
skipping to change at page 19, line 48 skipping to change at page 19, line 48
For an existing Connection, the Transport Properties can be queried For an existing Connection, the Transport Properties can be queried
any time by using the following call on the Connection Object: any time by using the following call on the Connection Object:
TransportProperties := Connection.GetTransportProperties() TransportProperties := Connection.GetTransportProperties()
A Connection gets its Transport Properties either by being explicitly A Connection gets its Transport Properties either by being explicitly
configured via a Preconnection, by configuration after establishment, configured via a Preconnection, by configuration after establishment,
or by inheriting them from an antecedent via cloning; see Section 6.4 or by inheriting them from an antecedent via cloning; see Section 6.4
for more. for more.
Section 10.1 provides a list of Connection Properties, while Section 7.1 provides a list of Connection Properties, while Selection
Selection Properties are listed in the subsections below. Note that Properties are listed in the subsections below. Note that many
many properties are only considered during establishment, and can not properties are only considered during establishment, and can not be
be changed after a Connection is established; however, they can be changed after a Connection is established; however, they can be
queried. The return type of a queried Selection Property is Boolean, queried. The return type of a queried Selection Property is Boolean,
where "true" means that the Selection Property has been applied and where "true" means that the Selection Property has been applied and
"false" means that the Selection Property has not been applied. Note "false" means that the Selection Property has not been applied. Note
that "true" does not mean that a request has been honored. For that "true" does not mean that a request has been honored. For
example, if "Congestion control" was requested with preference level example, if "Congestion control" was requested with preference level
"Prefer", but congestion control could not be supported, querying the "Prefer", but congestion control could not be supported, querying the
"congestionControl" property yields the value "false". If preference "congestionControl" property yields the value "false". If preference
level "Avoid" was used for "Congestion control", and, as requested, level "Avoid" was used for "Congestion control", and, as requested,
the Connection is not congestion controlled, querying the the Connection is not congestion controlled, querying the
"congestionControl" property also yields the value "false". "congestionControl" property also yields the value "false".
skipping to change at page 21, line 46 skipping to change at page 21, line 46
Type: Preference Type: Preference
Default: Ignore Default: Ignore
This property specifies whether an application would like to supply a This property specifies whether an application would like to supply a
Message to the transport protocol before Connection establishment, Message to the transport protocol before Connection establishment,
which will then be reliably transferred to the other side before or which will then be reliably transferred to the other side before or
during Connection establishment, potentially multiple times (i.e., during Connection establishment, potentially multiple times (i.e.,
multiple copies of the message data may be passed to the Remote multiple copies of the message data may be passed to the Remote
Endpoint). See also Section 7.5.4. Note that disabling this Endpoint). See also Section 8.1.3.4. Note that disabling this
property has no effect for protocols that are not connection-oriented property has no effect for protocols that are not connection-oriented
and do not protect against duplicated messages, e.g., UDP. and do not protect against duplicated messages, e.g., UDP.
5.2.6. Multistream Connections in Group 5.2.6. Multistream Connections in Group
Name: multistreaming Name: multistreaming
Type: Preference Type: Preference
Default: Prefer Default: Prefer
skipping to change at page 22, line 28 skipping to change at page 22, line 28
Name: perMsgChecksumLenSend Name: perMsgChecksumLenSend
Type: Preference Type: Preference
Default: Require Default: Require
This property specifies whether the application desires protection This property specifies whether the application desires protection
against corruption for all data transmitted on this Connection. against corruption for all data transmitted on this Connection.
Disabling this property may enable to control checksum coverage later Disabling this property may enable to control checksum coverage later
(see Section 7.5.6). (see Section 8.1.3.6).
5.2.8. Full Checksum Coverage on Receiving 5.2.8. Full Checksum Coverage on Receiving
Name: perMsgChecksumLenRecv Name: perMsgChecksumLenRecv
Type: Preference Type: Preference
Default: Require Default: Require
This property specifies whether the application desires protection This property specifies whether the application desires protection
skipping to change at page 25, line 40 skipping to change at page 25, line 40
established, even if the chosen transport supports using multiple established, even if the chosen transport supports using multiple
paths. paths.
Active: The connection will negotiate the use of multiple paths if Active: The connection will negotiate the use of multiple paths if
the chosen transport supports this. the chosen transport supports this.
Passive: The connection will support the use of multiple paths if Passive: The connection will support the use of multiple paths if
the remote endpoint requests it. the remote endpoint requests it.
The policy for using multiple paths is specified using the separate The policy for using multiple paths is specified using the separate
"multipath-policy" property, see Section 10.1.7 below. To enable the "multipath-policy" property, see Section 7.1.7 below. To enable the
peer endpoint to initiate additional paths towards a local address peer endpoint to initiate additional paths towards a local address
other than the one initially used, it is necessary to set the other than the one initially used, it is necessary to set the
Alternative Addresses property (see Section 5.2.14 below). Alternative Addresses property (see Section 5.2.14 below).
Setting this property to "Active", may have privacy implications: It Setting this property to "Active", may have privacy implications: It
enables the transport to establish connectivity using alternate paths enables the transport to establish connectivity using alternate paths
that may make users linkable across multiple paths, even if the that may make users linkable across multiple paths, even if the
Advertisement of Alternative Addresses property (see Section 5.2.14 Advertisement of Alternative Addresses property (see Section 5.2.14
below) is set to false. below) is set to false.
skipping to change at page 27, line 17 skipping to change at page 27, line 17
5.2.16. Notification of excessive retransmissions 5.2.16. Notification of excessive retransmissions
Name: retransmitNotify Name: retransmitNotify
Type: Preference Type: Preference
Default: Ignore Default: Ignore
This property specifies whether an application considers it useful to This property specifies whether an application considers it useful to
be informed in case sent data was retransmitted more often than a be informed in case sent data was retransmitted more often than a
certain threshold (see Section 10.1.1 for configuration of this certain threshold (see Section 7.1.1 for configuration of this
threshold). threshold).
5.2.17. Notification of ICMP soft error message arrival 5.2.17. Notification of ICMP soft error message arrival
Name: softErrorNotify Name: softErrorNotify
Type: Preference Type: Preference
Default: Ignore Default: Ignore
This property specifies whether an application considers it useful to This property specifies whether an application considers it useful to
be informed when an ICMP error message arrives that does not force be informed when an ICMP error message arrives that does not force
termination of a connection. When set to true, received ICMP errors termination of a connection. When set to true, received ICMP errors
will be available as SoftErrors, see Section 10.3.1. Note that even will be available as SoftErrors, see Section 7.3.1. Note that even
if a protocol supporting this property is selected, not all ICMP if a protocol supporting this property is selected, not all ICMP
errors will necessarily be delivered, so applications cannot rely on errors will necessarily be delivered, so applications cannot rely on
receiving them. receiving them.
5.2.18. Initiating side is not the first to write 5.2.18. Initiating side is not the first to write
Name: activeReadBeforeSend Name: activeReadBeforeSend
Type: Preference Type: Preference
skipping to change at page 30, line 29 skipping to change at page 30, line 29
necessary for candidate selection. necessary for candidate selection.
The Initiate() Action returns a Connection object. Once Initiate() The Initiate() Action returns a Connection object. Once Initiate()
has been called, any changes to the Preconnection MUST NOT have any has been called, any changes to the Preconnection MUST NOT have any
effect on the Connection. However, the Preconnection can be reused, effect on the Connection. However, the Preconnection can be reused,
e.g., to Initiate another Connection. e.g., to Initiate another Connection.
Once Initiate is called, the candidate Protocol Stack(s) may cause Once Initiate is called, the candidate Protocol Stack(s) may cause
one or more candidate transport-layer connections to be created to one or more candidate transport-layer connections to be created to
the specified remote endpoint. The caller may immediately begin the specified remote endpoint. The caller may immediately begin
sending Messages on the Connection (see Section 7) after calling sending Messages on the Connection (see Section 8.2) after calling
Initiate(); note that any data marked "Safely Replayable" that is Initiate(); note that any data marked "Safely Replayable" that is
sent while the Connection is being established may be sent multiple sent while the Connection is being established may be sent multiple
times or on multiple candidates. times or on multiple candidates.
The following Events may be sent by the Connection after Initiate() The following Events may be sent by the Connection after Initiate()
is called: is called:
Connection -> Ready<> Connection -> Ready<>
The Ready Event occurs after Initiate has established a transport- The Ready Event occurs after Initiate has established a transport-
layer connection on at least one usable candidate Protocol Stack over layer connection on at least one usable candidate Protocol Stack over
at least one candidate Path. No Receive Events (see Section 8) will at least one candidate Path. No Receive Events (see Section 8.3)
occur before the Ready Event for Connections established using will occur before the Ready Event for Connections established using
Initiate. Initiate.
Connection -> EstablishmentError<reason?> Connection -> EstablishmentError<reason?>
An EstablishmentError occurs either when the set of transport An EstablishmentError occurs either when the set of transport
properties and security parameters cannot be fulfilled on a properties and security parameters cannot be fulfilled on a
Connection for initiation (e.g. the set of available Paths and/or Connection for initiation (e.g. the set of available Paths and/or
Protocol Stacks meeting the constraints is empty) or reconciled with Protocol Stacks meeting the constraints is empty) or reconciled with
the local and/or remote Endpoints; when the remote specifier cannot the local and/or remote Endpoints; when the remote specifier cannot
be resolved; or when no transport-layer connection can be established be resolved; or when no transport-layer connection can be established
to the remote Endpoint (e.g. because the remote Endpoint is not to the remote Endpoint (e.g. because the remote Endpoint is not
accepting connections, the application is prohibited from opening a accepting connections, the application is prohibited from opening a
Connection by the operating system, or the establishment attempt has Connection by the operating system, or the establishment attempt has
timed out for any other reason). timed out for any other reason).
See also Section 7.8 to combine Connection establishment and See also Section 8.2.6 to combine Connection establishment and
transmission of the first message in a single action. transmission of the first message in a single action.
6.2. Passive Open: Listen 6.2. Passive Open: Listen
Passive open is the Action of waiting for Connections from remote Passive open is the Action of waiting for Connections from remote
Endpoints, commonly used by servers in client-server interactions. Endpoints, commonly used by servers in client-server interactions.
Passive open is supported by this interface through the Listen Action Passive open is supported by this interface through the Listen Action
and returns a Listener object: and returns a Listener object:
Listener := Preconnection.Listen() Listener := Preconnection.Listen()
skipping to change at page 34, line 5 skipping to change at page 34, line 5
Connection := Connection.Clone() Connection := Connection.Clone()
Calling Clone on a Connection yields a group of two Connections: the Calling Clone on a Connection yields a group of two Connections: the
parent Connection on which Clone was called, and the resulting cloned parent Connection on which Clone was called, and the resulting cloned
Connection. These connections are "entangled" with each other, and Connection. These connections are "entangled" with each other, and
become part of a Connection Group. Calling Clone on any of these two become part of a Connection Group. Calling Clone on any of these two
Connections adds a third Connection to the Connection Group, and so Connections adds a third Connection to the Connection Group, and so
on. Connections in a Connection Group generally share Connection on. Connections in a Connection Group generally share Connection
Properties. However, there may be exceptions, such as "Priority Properties. However, there may be exceptions, such as "Priority
(Connection)", see Section 10.1.3. Like all other Properties, (Connection)", see Section 7.1.3. Like all other Properties,
Priority is copied to the new Connection when calling Clone(), but it Priority is copied to the new Connection when calling Clone(), but it
is not entangled: Changing Priority on one Connection does not change is not entangled: Changing Priority on one Connection does not change
it on the other Connections in the same Connection Group. it on the other Connections in the same Connection Group.
It is also possible to check which Connections belong to the same It is also possible to check which Connections belong to the same
Connection Group. Calling GroupedConnections() on a specific Connection Group. Calling GroupedConnections() on a specific
Connection returns a set of all Connections in the same group. Connection returns a set of all Connections in the same group.
[]Connection := Connection.GroupedConnections() []Connection := Connection.GroupedConnections()
Connections will be in the same group if the application previously Connections will be in the same group if the application previously
called Clone. Passive Connections can also be added to the same called Clone. Passive Connections can also be added to the same
group - e.g., when a Listener receives a new Connection that is just group - e.g., when a Listener receives a new Connection that is just
a new stream of an already active multi-streaming protocol instance. a new stream of an already active multi-streaming protocol instance.
Changing one of the Connection Properties on one Connection in the Changing one of the Connection Properties on one Connection in the
group changes it for all others. Message Properties, however, are group changes it for all others. Message Properties, however, are
not entangled. For example, changing "Timeout for aborting not entangled. For example, changing "Timeout for aborting
Connection" (see Section 10.1.4) on one Connection in a group will Connection" (see Section 7.1.4) on one Connection in a group will
automatically change this Connection Property for all Connections in automatically change this Connection Property for all Connections in
the group in the same way. However, changing "Lifetime" (see the group in the same way. However, changing "Lifetime" (see
Section 7.5.1) of a Message will only affect a single Message on a Section 8.1.3.1) of a Message will only affect a single Message on a
single Connection, entangled or not. single Connection, entangled or not.
If the underlying protocol supports multi-streaming, it is natural to If the underlying protocol supports multi-streaming, it is natural to
use this functionality to implement Clone. In that case, entangled use this functionality to implement Clone. In that case, entangled
Connections are multiplexed together, giving them similar treatment Connections are multiplexed together, giving them similar treatment
not only inside endpoints but also across the end-to-end Internet not only inside endpoints but also across the end-to-end Internet
path. path.
Note that calling Clone() may result in on-the-wire signaling, e.g., Note that calling Clone() may result in on-the-wire signaling, e.g.,
to open a new connection, depending on the underlying Protocol Stack. to open a new connection, depending on the underlying Protocol Stack.
skipping to change at page 34, line 50 skipping to change at page 34, line 50
Connection Properties by uniformly applying them to all underlying Connection Properties by uniformly applying them to all underlying
connections in a group. Even in such a case, there are possibilities connections in a group. Even in such a case, there are possibilities
for a transport system to implement prioritization within a for a transport system to implement prioritization within a
Connection Group [TCP-COUPLING] [RFC8699]. Connection Group [TCP-COUPLING] [RFC8699].
Attempts to clone a Connection can result in a CloneError: Attempts to clone a Connection can result in a CloneError:
Connection -> CloneError<reason?> Connection -> CloneError<reason?>
The Connection Property "Priority" operates on entangled Connections The Connection Property "Priority" operates on entangled Connections
as in Section 7.5.2: when allocating available network capacity among as in Section 8.1.3.2: when allocating available network capacity
Connections in a Connection Group, sends on Connections with higher among Connections in a Connection Group, sends on Connections with
Priority values will be prioritized over sends on Connections with higher Priority values will be prioritized over sends on Connections
lower Priority values. A transport system implementation should, if with lower Priority values. A transport system implementation
possible, assign each Connection the capacity share (M-N) x C / M, should, if possible, assign each Connection the capacity share (M-N)
where N is the Connection's Priority value, M is the maximum Priority x C / M, where N is the Connection's Priority value, M is the maximum
value used by all Connections in the group and C is the total Priority value used by all Connections in the group and C is the
available capacity. However, the Priority setting is purely total available capacity. However, the Priority setting is purely
advisory, and no guarantees are given about the way capacity is advisory, and no guarantees are given about the way capacity is
shared. Each implementation is free to implement a way to share shared. Each implementation is free to implement a way to share
capacity that it sees fit. capacity that it sees fit.
7. Sending Data 7. Managing Connections
Once a Connection has been established, it can be used for sending During pre-establishment and after establishment, connections can be
data. Data is sent as Messages, which allow the application to configured and queried using Connection Properties, and asynchronous
communicate the boundaries of the data being transferred. By information may be available about the state of the connection via
default, Send enqueues a complete Message, and takes optional per- Soft Errors.
Message properties (see Section 7.1). All Send actions are
asynchronous, and deliver events (see Section 7.3). Sending partial
Messages for streaming large data is also supported (see
Section 7.6).
Messages are sent on a Connection using the Send action: 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 Section 7.1 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.
Connection.Send(messageData, messageContext?, endOfMessage?) The application can set and query Connection Properties on a per-
Connection basis. Connection Properties that are not read-only can
be set during pre-establishment (see Section 5.2), as well as on
connections directly using the SetProperty action:
where messageData is the data object to send. Connection.SetProperty(property, value)
The optional messageContext parameter allows adding Message Note that changing one of the Connection Properties on one Connection
Properties as described in Section 7.5. Moreover, the messageContext in a Connection Group will also change it for all other Connections
can be used to identify Send Events related to a specific Message of that group; see further Section 6.4.
(see Section 7.3) or to inspect meta-data related to the Message sent
(see Section 7.4).
The optional endOfMessage parameter supports partial sending and is At any point, the application can query Connection Properties.
described in Section 7.6.
Framers can be used to extend or modify the message data with ConnectionProperties := Connection.GetProperties()
additional information that can be processed at the receiver to
detect message boundaries. This is further decribed in Section 9.
7.1. Basic Sending Depending on the status of the connection, the queried Connection
Properties will include different information:
The most basic form of sending on a connection involves enqueuing a o The connection state, which can be one of the following:
single Data block as a complete Message, with default Message Establishing, Established, Closing, or Closed.
Properties.
messageData := "hello" o Whether the connection can be used to send data. A connection can
Connection.Send(messageData) not be used for sending if the connection was created with the
The interpretation of a Message to be sent is dependent on the Selection Property "Direction of Communication" set to
implementation, and on the constraints on the Protocol Stacks implied "unidirectional receive" or if a Message marked as "Final" was
by the Connection's transport properties. For example, a Message may sent over this connection, see Section 8.1.3.5.
be a single datagram for UDP Connections; or an HTTP Request for HTTP
Connections.
Some transport protocols can deliver arbitrarily sized Messages, but o Whether the connection can be used to receive data. A connection
other protocols constrain the maximum Message size. Applications can can not be used for reading if the connection was created with the
query the Connection Property "Maximum Message size on send" Selection Property "Direction of Communication" set to
(Section 10.1.9.3) to determine the maximum size allowed for a single "unidirectional send" or if a Message marked as "Final" was
Message. If a Message is too large to fit in the Maximum Message received, see Section 8.3.3.3. The latter is only supported by
Size for the Connection, the Send will fail with a SendError event certain transport protocols, e.g., by TCP as half-closed
(Section 7.3.3). For example, it is invalid to send a Message over a connection.
UDP connection that is larger than the available datagram sending
size.
7.2. Sending Replies o For Connections that are Establishing: Transport Properties that
the application specified on the Preconnection, see Section 5.2.
When a message is sent in response to a message received, the o For Connections that are Established, Closing, or Closed:
application may use the Message Context of the received Message to Selection (Section 5.2) and Connection Properties (Section 7.1) of
construct a Message Context for the reply. 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.
replyMessageContext := requestMessageContext.reply() o For Connections that are Established, additional properties of the
path(s) in use. These properties can be derived from the local
provisioning domain [RFC7556], measurements by the Protocol Stack,
or other sources.
By using the "replyMessageContext", the transport system is informed 7.1. Generic Connection Properties
that the message to be sent is a response and can map the response to
the same underlying transport connection or stream the request was
received from. The concept of Message Contexts is described in
Section 7.4.
7.3. Send Events Generic Connection Properties are defined independent of the chosen
protocol stack and therefore available on all Connections.
Like all Actions in this interface, the Send Action is asynchronous. Note that many Connection Properties have a corresponding Selection
There are several Events that can be delivered in response to Sending Property which enables applications to express their preference for
a Message. Exactly one Event (Sent, Expired, or SendError) will be protocols providing a supporting transport feature.
delivered in response to each call to Send.
Note that if partial Sends are used (Section 7.6), there will still 7.1.1. Retransmission Threshold Before Excessive Retransmission
be exactly one Send Event delivered for each call to Send. For Notification
example, if a Message expired while two requests to Send data for
that Message are outstanding, there will be two Expired events
delivered.
The interface should allow the application to correlate which Send Name: retransmitNotifyThreshold
Action resulted in a particular Send Event. The manner in which this
correlation is indicated is implementation-specific.
7.3.1. Sent Type: Integer, with special value "Disabled"
Connection -> Sent<messageContext> Default: Disabled
The Sent Event occurs when a previous Send Action has completed, This property specifies after how many retransmissions to inform the
i.e., when the data derived from the Message has been passed down or application about "Excessive Retransmissions".
through the underlying Protocol Stack and is no longer the
responsibility of this interface. The exact disposition of the
Message (i.e., whether it has actually been transmitted, moved into a
buffer on the network interface, moved into a kernel buffer, and so
on) when the Sent Event occurs is implementation-specific. The Sent
Event contains a reference to the Message to which it applies.
Sent Events allow an application to obtain an understanding of the 7.1.2. Required Minimum Corruption Protection Coverage for Receiving
amount of buffering it creates. That is, if an application calls the
Send Action multiple times without waiting for a Sent Event, it has
created more buffer inside the transport system than an application
that always waits for the Sent Event before calling the next Send
Action.
7.3.2. Expired Name: recvChecksumLen
Connection -> Expired<messageContext> Type: Integer, with special value "Full Coverage"
The Expired Event occurs when a previous Send Action expired before Default: Full Coverage
completion; i.e. when the Message was not sent before its Lifetime
(see Section 7.5.1) expired. This is separate from SendError, as it
is an expected behavior for partially reliable transports. The
Expired Event contains a reference to the Message to which it
applies.
7.3.3. SendError 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.
Connection -> SendError<messageContext, reason?> 7.1.3. Priority (Connection)
A SendError occurs when a Message could not be sent due to an error Name: connPrio
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.
7.4. Message Contexts Type: Integer
Default: 100
This Property is a non-negative integer representing the relative
inverse priority (i.e., a lower value reflects a higher priority) of
this Connection relative to other Connections in the same Connection
Group. It has no effect on Connections not part of a Connection
Group. As noted in Section 6.4, this property is not entangled when
Connections are cloned, i.e., changing the Priority on one Connection
in a Connection Group does not change it on the other Connections in
the same Connection Group.
7.1.4. Timeout for Aborting Connection
Name: connTimeout
Type: Numeric, with special value "Disabled"
Default: Disabled
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).
7.1.5. Connection Group Transmission Scheduler
Name: connScheduler
Type: Enumeration
Default: Weighted Fair Queueing (see Section 3.6 in [RFC8260])
This property specifies which scheduler should be used among
Connections within a Connection Group, see Section 6.4. The set of
schedulers can be taken from [RFC8260].
7.1.6. Capacity Profile
Name: connCapacityProfile
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.
The following values are valid for the Capacity Profile:
Default: 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.
Scavenger: The application is not interactive. It expects to send
and/or receive data without any urgency. This can, for example,
be used to select protocol stacks with scavenger transmission
control and/or to assign the traffic to a lower-effort service.
Transport system implementations that map the requested capacity
profile onto per-connection DSCP signaling SHOULD assign the DSCP
Less than Best Effort [RFC8622] PHB.
Low Latency/Interactive: 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.
Low Latency/Non-Interactive: 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.
Constant-Rate Streaming: 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.
Capacity-Seeking: The application expects to send/receive data at
the maximum rate allowed by its congestion controller over a
relatively long period of time. Transport system implementations
that map the requested capacity profile onto per-connection DSCP
signaling without multiplexing SHOULD assign a DSCP Assured
Forwarding (AF11,AF12,AF13,AF14) [RFC2597] PHB per Section 4.8 of
[RFC4594].
The Capacity Profile for a selected protocol stack may be modified on
a per-Message basis using the Transmission Profile Message Property;
see Section 8.1.3.8.
7.1.7. Policy for using Multi-Path Transports
Name: multipath-policy
Type: Enumeration
Default: Handover
This property specifies the local policy of transferring data across
multiple paths between the same end hosts if Parallel Use of Multiple
Paths not set to Disabled (see Section 5.2.13). Possible values are:
Handover: 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.
Interactive: 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.
Aggregate: 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.
Note that this is a local choice - the peer endpoint can choose a
different policy.
7.1.8. Bounds on Send or Receive Rate
Name: maxSendRate / maxRecvRate
Type: Numeric (with special value "Unlimited") / Numeric (with
special value "Unlimited")
Default: Unlimited / Unlimited
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.
7.1.9. Read-only Connection Properties
The following generic Connection Properties are read-only, i.e. they
cannot be changed by an application.
7.1.9.1. Maximum Message Size Concurrent with Connection Establishment
Name: zeroRttMsgMaxLen
Type: Integer
This property represents the maximum Message size that can be sent
before or during Connection establishment, see also Section 8.1.3.4.
It is given in Bytes.
7.1.9.2. Maximum Message Size Before Fragmentation or Segmentation
Name: singularTransmissionMsgMaxLen
Type: Integer
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].
7.1.9.3. Maximum Message Size on Send
Name: sendMsgMaxLen
Type: Integer
This property represents the maximum Message size that can be sent
using a send operation.
7.1.9.4. Maximum Message Size on Receive
Name: recvMsgMaxLen
Type: Integer
This numeric property represents the maximum Message size that can be
received.
7.2. TCP-specific Properties: User Timeout Option (UTO)
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.
These TCP-specific properties are included here because the feature
"Suggest timeout to the peer" is part of the minimal set of transport
services [I-D.ietf-taps-minset], where this feature was categorized
as "functional". This means that when an implementation offers this
feature, it has to expose an interface to it to the application.
Otherwise, the implementation might violate assumptions by the
application, which could cause the application to fail.
All of the below properties are optional (e.g., it is possible to
specify "User Timeout Enabled" as true, but not specify an Advertised
User Timeout value; in this case, the TCP default will be used).
7.2.1. Advertised User Timeout
Name: tcp.userTimeoutValue
Type: Integer
Default: the TCP default
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 Section 7.1.4) value accordingly.
7.2.2. User Timeout Enabled
Name: tcp.userTimeout
Type: Boolean
Default: false
This property controls whether the UTO option is enabled for a
connection. This applies to both sending and receiving.
7.2.3. Timeout Changeable
Name: tcp.userTimeoutRecv
Type: Boolean
Default: true
This property controls whether the "Timeout for aborting Connection"
(see Section 7.1.4) may be changed based on a UTO option received
from the remote peer. This boolean becomes false when "Timeout for
aborting Connection" (see Section 7.1.4) is used.
7.3. Connection Lifecycle Events
During the lifetime of a connection there are events that can occur
when configured.
7.3.1. Soft Errors
Asynchronous introspection is also possible, via the SoftError Event.
This event informs the application about the receipt and contents of
an ICMP error message related to the Connection. This will only
happen if the underlying protocol stack supports access to soft
errors; however, even if the underlying stack supports it, there is
no guarantee that a soft error will be signaled.
Connection -> SoftError<>
7.3.2. Excessive retransmissions
This event notifies the application of excessive retransmissions,
based on a configured threshold (see Section 7.1.1). This will only
happen if the underlying protocol stack supports reliability and,
with it, such notifications.
Connection -> ExcessiveRetransmission<>
8. Data Transfer
Data is sent and received as Messages, which allows the application
to communicate the boundaries of the data being transferred.
8.1. Messages and Framers
Each Message has an optional Message Context, which allows to add
Message Properties, identify Send Events related to a specific
Message or to inspect meta-data related to the Message sent. Framers
can be used to extend or modify the message data with additional
information that can be processed at the receiver to detect message
boundaries.
8.1.1. Message Contexts
Using the MessageContext object, the application can set and retrieve Using the MessageContext object, the application can set and retrieve
meta-data of the message, including Message Properties (see meta-data of the message, including Message Properties (see
Section 7.5) and framing meta-data (see Section 9.2). Therefore, a Section 8.1.3) and framing meta-data (see Section 8.1.2.2).
MessageContext object can be passed to the Send action and is Therefore, a MessageContext object can be passed to the Send action
returned by each Send and Receive related event. and is returned by each Send and Receive related event.
Message Properties can be set and queried using the Message Context: Message Properties can be set and queried using the Message Context:
MessageContext.add(scope?, parameter, value) MessageContext.add(scope?, parameter, value)
PropertyValue := MessageContext.get(scope?, property) PropertyValue := MessageContext.get(scope?, property)
To get or set Message Properties, the optional scope parameter is To get or set Message Properties, the optional scope parameter is
left empty. To get or set meta-data for a Framer, the application left empty. To get or set meta-data for a Framer, the application
has to pass a reference to this Framer as the scope parameter. has to pass a reference to this Framer as the scope parameter.
For MessageContexts returned by send events (see Section 7.3) and For MessageContexts returned by send events (see Section 8.2.3) and
receive events (see Section 8.2), the application can query receive events (see Section 8.3.2), the application can query
information about the local and remote endpoint: information about the local and remote endpoint:
RemoteEndpoint := MessageContext.GetRemoteEndpoint() RemoteEndpoint := MessageContext.GetRemoteEndpoint()
LocalEndpoint := MessageContext.GetLocalEndpoint() LocalEndpoint := MessageContext.GetLocalEndpoint()
Message Contexts can also be used to send messages in reply to other Message Contexts can also be used to send messages in reply to other
messages, see Section 7.2 for details. messages, see Section 8.2.2 for details.
7.5. Message Properties 8.1.2. Message Framers
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.
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.
To use a Message Framer, the application adds it to its Preconnection
object. Then, the Message Framer can intercept all calls to Send()
or Receive() on a Connection to add Message semantics, in addition to
interacting with the setup and teardown of the Connection. A Framer
can start sending data before the application sends data if the
framing protocol requires a prefix or handshake (see [RFC8229] for an
example of such a framing protocol).
Initiate() Send() Receive() Close()
| | ^ |
| | | |
+----v----------v---------+----------v-----+
| Connection |
+----+----------+---------^----------+-----+
| | | |
| +-----------------+ |
| | Messages | |
| +-----------------+ |
| | | |
+----v----------v---------+----------v-----+
| Framer(s) |
+----+----------+---------^----------+-----+
| | | |
| +-----------------+ |
| | Byte-stream | |
| +-----------------+ |
| | | |
+----v----------v---------+----------v-----+
| Transport Protocol Stack |
+------------------------------------------+
Note that while Message Framers add the most value when placed above
a protocol that otherwise does not preserve message boundaries, they
can also be used with datagram- or message-based protocols. In these
cases, they add an additional transformation to further encode or
encapsulate, and can potentially support packing multiple
application-layer Messages into individual transport datagrams.
The API to implement a Message Framer can vary depending on the
implementation; guidance on implementing Message Framers can be found
in [I-D.ietf-taps-impl].
8.1.2.1. Adding Message Framers to Connections
The Message Framer object can be added to one or more Preconnections
to run on top of transport protocols. Multiple Framers may be added.
If multiple Framers are added, the last one added runs first when
framing outbound messages, and last when parsing inbound data.
The following example adds a basic HTTP Message Framer to a
Preconnection:
framer := NewHTTPMessageFramer()
Preconnection.AddFramer(framer)
8.1.2.2. Framing Meta-Data
When sending Messages, applications can add specific Message values
to a MessageContext (Section 8.1.1) that is intended for a Framer.
This can be used, for example, to set the type of a Message for a TLV
format. The namespace of values is custom for each unique Message
Framer.
messageContext := NewMessageContext()
messageContext.add(framer, key, value)
Connection.Send(messageData, messageContext)
When an application receives a MessageContext in a Receive event, it
can also look to see if a value was set by a specific Message Framer.
messageContext.get(framer, key) -> value
For example, if an HTTP Message Framer is used, the values could
correspond to HTTP headers:
httpFramer := NewHTTPMessageFramer()
...
messageContext := NewMessageContext()
messageContext.add(httpFramer, "accept", "text/html")
8.1.3. Message Properties
Applications may need to annotate the Messages they send with extra Applications may need to annotate the Messages they send with extra
information to control how data is scheduled and processed by the information to control how data is scheduled and processed by the
transport protocols in the Connection. Therefore a message context transport protocols in the Connection. Therefore a message context
containing these properties can be passed to the Send Action. For containing these properties can be passed to the Send Action. For
other uses of the message context, see Section 7.4. other uses of the message context, see Section 8.1.1.
Note that Message Properties are per-Message, not per-Send if partial Note that Message Properties are per-Message, not per-Send if partial
Messages are sent (Section 7.6). All data blocks associated with a Messages are sent (Section 8.2.4). All data blocks associated with a
single Message share properties specified in the Message Contexts. single Message share properties specified in the Message Contexts.
For example, it would not make sense to have the beginning of a 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. Message expire, but allow the end of a Message to still be sent.
A MessageContext object contains metadata for Messages to be sent or A MessageContext object contains metadata for Messages to be sent or
received. received.
messageData := "hello" messageData := "hello"
messageContext := NewMessageContext() messageContext := NewMessageContext()
messageContext.add(parameter, value) messageContext.add(parameter, value)
skipping to change at page 39, line 36 skipping to change at page 48, line 5
example, if "Reliable Data Transfer (Connection)" is set to "Require" example, if "Reliable Data Transfer (Connection)" is set to "Require"
and a protocol with configurable per-Message reliability is used, and a protocol with configurable per-Message reliability is used,
setting "Reliable Data Transfer (Message)" to "false" for a setting "Reliable Data Transfer (Message)" to "false" for a
particular Message will allow this Message to be unreliably particular Message will allow this Message to be unreliably
delivered. Note that changing the Reliable Data Transfer property on delivered. Note that changing the Reliable Data Transfer property on
Messages is only possible for Connections that were established with Messages is only possible for Connections that were established with
the Selection Property "Configure Per-Message Reliability" enabled. the Selection Property "Configure Per-Message Reliability" enabled.
The following Message Properties are supported: The following Message Properties are supported:
7.5.1. Lifetime 8.1.3.1. Lifetime
Name: msgLifetime Name: msgLifetime
Type: Numeric Type: Numeric
Default: infinite Default: infinite
Lifetime specifies how long a particular Message can wait to be sent 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 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 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 not guaranteed that a Message will not be sent when its Lifetime has
expired. expired.
Setting a Message's Lifetime to infinite indicates that the Setting a Message's Lifetime to infinite indicates that the
application does not wish to apply a time constraint on the application does not wish to apply a time constraint on the
transmission of the Message, but it does not express a need for transmission of the Message, but it does not express a need for
reliable delivery; reliability is adjustable per Message via the reliable delivery; reliability is adjustable per Message via the
"Reliable Data Transfer (Message)" property (see Section 7.5.7). The "Reliable Data Transfer (Message)" property (see Section 8.1.3.7).
type and units of Lifetime are implementation-specific. The type and units of Lifetime are implementation-specific.
7.5.2. Priority 8.1.3.2. Priority
Name: msgPrio Name: msgPrio
Type: Integer (non-negative) Type: Integer (non-negative)
Default: 100 Default: 100
This property represents a hierarchy of priorities. It can specify This property represents a hierarchy of priorities. It can specify
the priority of a Message, relative to other Messages sent over the the priority of a Message, relative to other Messages sent over the
same Connection. same Connection.
A Message with Priority 0 will yield to a Message with Priority 1, A Message with Priority 0 will yield to a Message with Priority 1,
which will yield to a Message with Priority 2, and so on. Priorities which will yield to a Message with Priority 2, and so on. Priorities
may be used as a sender-side scheduling construct only, or be used to may be used as a sender-side scheduling construct only, or be used to
specify priorities on the wire for Protocol Stacks supporting specify priorities on the wire for Protocol Stacks supporting
prioritization. prioritization.
Note that this property is not a per-message override of the Note that this property is not a per-message override of the
connection Priority - see Section 10.1.3. Both Priority properties connection Priority - see Section 7.1.3. Both Priority properties
may interact, but can be used independently and be realized by may interact, but can be used independently and be realized by
different mechanisms. different mechanisms.
7.5.3. Ordered 8.1.3.3. Ordered
Name: msgOrdered Name: msgOrdered
Type: Boolean Type: Boolean
Default: true Default: true
If true, it specifies that the receiver-side transport protocol stack If true, it specifies that the receiver-side transport protocol stack
may only deliver the Message to the receiving application after the may only deliver the Message to the receiving application after the
previous ordered Message which was passed to the same Connection via previous ordered Message which was passed to the same Connection via
the Send Action, when such a Message exists. If false, the Message the Send Action, when such a Message exists. If false, the Message
may be delivered to the receiving application out of order. This may be delivered to the receiving application out of order. This
property is used for protocols that support preservation of data property is used for protocols that support preservation of data
ordering, see Section 5.2.4, but allow out-of-order delivery for ordering, see Section 5.2.4, but allow out-of-order delivery for
certain messages, e.g., by multiplexing independent messages onto certain messages, e.g., by multiplexing independent messages onto
different streams. different streams.
7.5.4. Safely Replayable 8.1.3.4. Safely Replayable
Name: safelyReplayable Name: safelyReplayable
Type: Boolean Type: Boolean
Default: false Default: false
If true, it specifies that a Message is safe to send to the remote 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 endpoint more than once for a single Send Action. It is used to mark
data safe for certain 0-RTT establishment techniques, where data safe for certain 0-RTT establishment techniques, where
skipping to change at page 41, line 27 skipping to change at page 49, line 45
receive the Message multiple times. receive the Message multiple times.
Note that for protocols that do not protect against duplicated Note that for protocols that do not protect against duplicated
messages, e.g., UDP, all messages MUST be marked as "Safely messages, e.g., UDP, all messages MUST be marked as "Safely
Replayable". In order to enable protocol selection to choose such a Replayable". In order to enable protocol selection to choose such a
protocol, "Safely Replayable" MUST be added to the protocol, "Safely Replayable" MUST be added to the
TransportProperties passed to the Preconnection. If such a protocol TransportProperties passed to the Preconnection. If such a protocol
was chosen, disabling "Safely Replayable" on individual messages MUST was chosen, disabling "Safely Replayable" on individual messages MUST
result in a SendError. result in a SendError.
7.5.5. Final 8.1.3.5. Final
Name: final Name: final
Type: Boolean Type: Boolean
Default: false Default: false
If true, this Message is the last one that the application will send If true, this Message is the last one that the application will send
on a Connection. This allows underlying protocols to indicate to the on a Connection. This allows underlying protocols to indicate to the
Remote Endpoint that the Connection has been effectively closed in Remote Endpoint that the Connection has been effectively closed in
the sending direction. For example, TCP-based Connections can send a the sending direction. For example, TCP-based Connections can send a
FIN once a Message marked as Final has been completely sent, FIN once a Message marked as Final has been completely sent,
indicated by marking endOfMessage. Protocols that do not support indicated by marking endOfMessage. Protocols that do not support
signalling the end of a Connection in a given direction will ignore signalling the end of a Connection in a given direction will ignore
this property. this property.
Note that a Final Message must always be sorted to the end of a list Note that a Final Message must always be sorted to the end of a list
skipping to change at page 42, line 5 skipping to change at page 50, line 20
signalling the end of a Connection in a given direction will ignore signalling the end of a Connection in a given direction will ignore
this property. this property.
Note that a Final Message must always be sorted to the end of a list Note that a Final Message must always be sorted to the end of a list
of Messages. The Final property overrides Priority and any other of Messages. The Final property overrides Priority and any other
property that would re-order Messages. If another Message is sent property that would re-order Messages. If another Message is sent
after a Message marked as Final has already been sent on a after a Message marked as Final has already been sent on a
Connection, the Send Action for the new Message will cause a Connection, the Send Action for the new Message will cause a
SendError Event. SendError Event.
7.5.6. Corruption Protection Length 8.1.3.6. Corruption Protection Length
Name: msgChecksumLen Name: msgChecksumLen
Type: Integer (non-negative with special value "Full Coverage") Type: Integer (non-negative with special value "Full Coverage")
Default: Full Coverage Default: Full Coverage
This property specifies the minimum length of the section of the This property specifies the minimum length of the section of the
Message, starting from byte 0, that the application requires to be Message, starting from byte 0, that the application requires to be
delivered without corruption due to lower layer errors. It is used delivered without corruption due to lower layer errors. It is used
to specify options for simple integrity protection via checksums. A to specify options for simple integrity protection via checksums. A
value of 0 means that no checksum is required, and "Full Coverage" value of 0 means that no checksum is required, and "Full Coverage"
means that the entire Message is protected by a checksum. Only "Full means that the entire Message is protected by a checksum. Only "Full
Coverage" is guaranteed, any other requests are advisory, meaning Coverage" is guaranteed, any other requests are advisory, meaning
that "Full Coverage" is applied anyway. that "Full Coverage" is applied anyway.
7.5.7. Reliable Data Transfer (Message) 8.1.3.7. Reliable Data Transfer (Message)
Name: msgReliable Name: msgReliable
Type: Boolean Type: Boolean
Default: true Default: true
When true, this property specifies that a message should be sent in When true, this property specifies that a message should be sent in
such a way that the transport protocol ensures all data is received such a way that the transport protocol ensures all data is received
on the other side without corruption. Changing the "Reliable Data on the other side without corruption. Changing the "Reliable Data
Transfer" property on Messages is only possible for Connections that Transfer" property on Messages is only possible for Connections that
were established with the Selection Property "Configure Per-Message were established with the Selection Property "Configure Per-Message
Reliability" enabled. When this is not the case, changing it will Reliability" enabled. When this is not the case, changing it will
generate an error. Disabling this property indicates that the generate an error. Disabling this property indicates that the
transport system may disable retransmissions or other reliability transport system may disable retransmissions or other reliability
mechanisms for this particular Message, but such disabling is not mechanisms for this particular Message, but such disabling is not
guaranteed. guaranteed.
7.5.8. Message Capacity Profile Override 8.1.3.8. Message Capacity Profile Override
Name: msgCapacityProfile Name: msgCapacityProfile
Type: Enumeration Type: Enumeration
This enumerated property specifies the application's preferred This enumerated property specifies the application's preferred
tradeoffs for sending this Message; it is a per-Message override of tradeoffs for sending this Message; it is a per-Message override of
the Capacity Profile connection property (see Section 10.1.6). the Capacity Profile connection property (see Section 7.1.6).
7.5.9. No Fragmentation 8.1.3.9. No Fragmentation
Name: noFragmentation Name: noFragmentation
Type: Boolean Type: Boolean
Default: false Default: false
This property specifies that a message should be sent and received as This property specifies that a message should be sent and received as
a single packet without network-layer fragmentation, if possible. a single packet without network-layer fragmentation, if possible.
Attempts to send a message with this property set with a size greater Attempts to send a message with this property set with a size greater
to the transport's current estimate of its maximum transmission to the transport's current estimate of its maximum transmission
segment size will result in a "SendError". When used with transports segment size will result in a "SendError". When used with transports
supporting this functionality and running over IP version 4, the supporting this functionality and running over IP version 4, the
Don't Fragment bit will be set. Don't Fragment bit will be set.
7.6. Partial Sends 8.2. Sending Data
Once a Connection has been established, it can be used for sending
Messages. By default, Send enqueues a complete Message, and takes
optional per-Message properties (see Section 8.2.1). All Send
actions are asynchronous, and deliver events (see Section 8.2.3).
Sending partial Messages for streaming large data is also supported
(see Section 8.2.4).
Messages are sent on a Connection using the Send action:
Connection.Send(messageData, messageContext?, endOfMessage?)
where messageData is the data object to send, and messageContext
allows adding Message Properties, identifying Send Events related to
a specific Message or inspecting meta-data related to the Message
sent (see Section 8.1.1).
The optional endOfMessage parameter supports partial sending and is
described in Section 8.2.4.
8.2.1. Basic Sending
The most basic form of sending on a connection involves enqueuing a
single Data block as a complete Message, with default Message
Properties.
messageData := "hello"
Connection.Send(messageData)
The interpretation of a Message to be sent is dependent on the
implementation, and on the constraints on the Protocol Stacks implied
by the Connection's transport properties. For example, a Message may
be a single datagram for UDP Connections; or an HTTP Request for HTTP
Connections.
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"
(Section 7.1.9.3) 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
(Section 8.2.3.3). For example, it is invalid to send a Message over
a UDP connection that is larger than the available datagram sending
size.
8.2.2. Sending Replies
When a message is sent in response to a message received, the
application may use the Message Context of the received Message to
construct a Message Context for the reply.
replyMessageContext := requestMessageContext.reply()
By using the "replyMessageContext", the transport system is informed
that the message to be sent is a response and can map the response to
the same underlying transport connection or stream the request was
received from. The concept of Message Contexts is described in
Section 8.1.1.
8.2.3. Send Events
Like all Actions in this interface, the Send Action is asynchronous.
There are several Events that can be delivered in response to Sending
a Message. Exactly one Event (Sent, Expired, or SendError) will be
delivered in response to each call to Send.
Note that if partial Sends are used (Section 8.2.4), there will still
be exactly one Send Event delivered for each call to Send. For
example, if a Message expired while two requests to Send data for
that Message are outstanding, there will be two Expired events
delivered.
The interface should allow the application to correlate which Send
Action resulted in a particular Send Event. The manner in which this
correlation is indicated is implementation-specific.
8.2.3.1. Sent
Connection -> Sent<messageContext>
The Sent Event occurs when a previous Send Action has completed,
i.e., when the data derived from the Message has been passed down or
through the underlying Protocol Stack and is no longer the
responsibility of this interface. The exact disposition of the
Message (i.e., whether it has actually been transmitted, moved into a
buffer on the network interface, moved into a kernel buffer, and so
on) when the Sent Event occurs is implementation-specific. The Sent
Event contains a reference to the Message to which it applies.
Sent Events allow an application to obtain an understanding of the
amount of buffering it creates. That is, if an application calls the
Send Action multiple times without waiting for a Sent Event, it has
created more buffer inside the transport system than an application
that always waits for the Sent Event before calling the next Send
Action.
8.2.3.2. Expired
Connection -> Expired<messageContext>
The Expired Event occurs when a previous Send Action expired before
completion; i.e. when the Message was not sent before its Lifetime
(see Section 8.1.3.1) expired. This is separate from SendError, as
it is an expected behavior for partially reliable transports. The
Expired Event contains a reference to the Message to which it
applies.
8.2.3.3. SendError
Connection -> SendError<messageContext, reason?>
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.
8.2.4. Partial Sends
It is not always possible for an application to send all data It is not always possible for an application to send all data
associated with a Message in a single Send Action. The Message data associated with a Message in a single Send Action. The Message data
may be too large for the application to hold in memory at one time, may be too large for the application to hold in memory at one time,
or the length of the Message may be unknown or unbounded. or the length of the Message may be unknown or unbounded.
Partial Message sending is supported by passing an endOfMessage Partial Message sending is supported by passing an endOfMessage
boolean parameter to the Send Action. This value is always true by boolean parameter to the Send Action. This value is always true by
default, and the simpler forms of Send are equivalent to passing true default, and the simpler forms of Send are equivalent to passing true
for endOfMessage. for endOfMessage.
skipping to change at page 44, line 5 skipping to change at page 54, line 37
Connection.Send(messageData, messageContext, endOfMessage) Connection.Send(messageData, messageContext, endOfMessage)
messageData := "lo" messageData := "lo"
endOfMessage := true endOfMessage := true
Connection.Send(messageData, messageContext, endOfMessage) Connection.Send(messageData, messageContext, endOfMessage)
All data sent with the same MessageContext object will be treated as All data sent with the same MessageContext object will be treated as
belonging to the same Message, and will constitute an in-order series belonging to the same Message, and will constitute an in-order series
until the endOfMessage is marked. until the endOfMessage is marked.
7.7. Batching Sends 8.2.5. Batching Sends
To reduce the overhead of sending multiple small Messages on a To reduce the overhead of sending multiple small Messages on a
Connection, the application may want to batch several Send Actions Connection, the application may want to batch several Send Actions
together. This provides a hint to the system that the sending of together. This provides a hint to the system that the sending of
these Messages should be coalesced when possible, and that sending these Messages should be coalesced when possible, and that sending
any of the batched Messages may be delayed until the last Message in any of the batched Messages may be delayed until the last Message in
the batch is enqueued. the batch is enqueued.
The semantics for starting and ending a batch can be implementation- The semantics for starting and ending a batch can be implementation-
specific, but need to allow multiple Send Actions to be enqueued. specific, but need to allow multiple Send Actions to be enqueued.
Connection.StartBatch() Connection.StartBatch()
Connection.Send(messageData) Connection.Send(messageData)
Connection.Send(messageData) Connection.Send(messageData)
Connection.EndBatch() Connection.EndBatch()
7.8. Send on Active Open: InitiateWithSend 8.2.6. Send on Active Open: InitiateWithSend
For application-layer protocols where the Connection initiator also For application-layer protocols where the Connection initiator also
sends the first message, the InitiateWithSend() action combines sends the first message, the InitiateWithSend() action combines
Connection initiation with a first Message sent: Connection initiation with a first Message sent:
Connection := Preconnection.InitiateWithSend(messageData, messageContext?, timeout?) Connection := Preconnection.InitiateWithSend(messageData, messageContext?, timeout?)
Whenever possible, a messageContext should be provided to declare the Whenever possible, a messageContext should be provided to declare the
Message passed to InitiateWithSend as "Safely Replayable". This Message passed to InitiateWithSend as "Safely Replayable". This
allows the transport system to make use of 0-RTT establishment in allows the transport system to make use of 0-RTT establishment in
skipping to change at page 44, line 48 skipping to change at page 55, line 36
Neither partial sends nor send batching are supported by Neither partial sends nor send batching are supported by
InitiateWithSend(). InitiateWithSend().
The Events that may be sent after InitiateWithSend() are equivalent The Events that may be sent after InitiateWithSend() are equivalent
to those that would be sent by an invocation of Initiate() followed to those that would be sent by an invocation of Initiate() followed
immediately by an invocation of Send(), with the caveat that a send immediately by an invocation of Send(), with the caveat that a send
failure that occurs because the Connection could not be established failure that occurs because the Connection could not be established
will not result in a SendError separate from the InitiateError will not result in a SendError separate from the InitiateError
signaling the failure of Connection establishment. signaling the failure of Connection establishment.
8. Receiving Data 8.3. Receiving Data
Once a Connection is established, it can be used for receiving data Once a Connection is established, it can be used for receiving data
(unless the "Direction of Communication" property is set to (unless the "Direction of Communication" property is set to
"unidirectional send"). As with sending, data is received in terms "unidirectional send"). As with sending, data is received in terms
of Messages. Receiving is an asynchronous operation, in which each of Messages. Receiving is an asynchronous operation, in which each
call to Receive enqueues a request to receive new data from the call to Receive enqueues a request to receive new data from the
connection. Once data has been received, or an error is encountered, connection. Once data has been received, or an error is encountered,
an event will be delivered to complete any pending Receive requests an event will be delivered to complete any pending Receive requests
(see Section 8.2). If Messages arrive at the transport system before (see Section 8.3.2). If Messages arrive at the transport system
Receive requests are issued, ensuing Receive requests will first before Receive requests are issued, ensuing Receive requests will
operate on these Messages before awaiting any further Messages. first operate on these Messages before awaiting any further Messages.
8.1. Enqueuing Receives 8.3.1. Enqueuing Receives
Receive takes two parameters to specify the length of data that an Receive takes two parameters to specify the length of data that an
application is willing to receive, both of which are optional and application is willing to receive, both of which are optional and
have default values if not specified. have default values if not specified.
Connection.Receive(minIncompleteLength?, maxLength?) Connection.Receive(minIncompleteLength?, maxLength?)
By default, Receive will try to deliver complete Messages in a single By default, Receive will try to deliver complete Messages in a single
event (Section 8.2.1). event (Section 8.3.2.1).
The application can set a minIncompleteLength value to indicate the The application can set a minIncompleteLength value to indicate the
smallest partial Message data size in bytes that should be delivered smallest partial Message data size in bytes that should be delivered
in response to this Receive. By default, this value is infinite, in response to this Receive. By default, this value is infinite,
which means that only complete Messages should be delivered (see which means that only complete Messages should be delivered (see
Section 8.2.2 and Section 9 for more information on how this is Section 8.3.2.2 and Section 8.1.2 for more information on how this is
accomplished). If this value is set to some smaller value, the accomplished). If this value is set to some smaller value, the
associated receive event will be triggered only when at least that associated receive event will be triggered only when at least that
many bytes are available, or the Message is complete with fewer many bytes are available, or the Message is complete with fewer
bytes, or the system needs to free up memory. Applications should bytes, or the system needs to free up memory. Applications should
always check the length of the data delivered to the receive event always check the length of the data delivered to the receive event
and not assume it will be as long as minIncompleteLength in the case and not assume it will be as long as minIncompleteLength in the case
of shorter complete Messages or memory issues. of shorter complete Messages or memory issues.
The maxLength argument indicates the maximum size of a Message in The maxLength argument indicates the maximum size of a Message in
bytes the application is currently prepared to receive. The default bytes the application is currently prepared to receive. The default
value for maxLength is infinite. If an incoming Message is larger value for maxLength is infinite. If an incoming Message is larger
than the minimum of this size and the maximum Message size on receive than the minimum of this size and the maximum Message size on receive
for the Connection's Protocol Stack, it will be delivered via for the Connection's Protocol Stack, it will be delivered via
ReceivedPartial events (Section 8.2.2). ReceivedPartial events (Section 8.3.2.2).
Note that maxLength does not guarantee that the application will Note that maxLength does not guarantee that the application will
receive that many bytes if they are available; the interface may receive that many bytes if they are available; the interface may
return ReceivedPartial events with less data than maxLength according return ReceivedPartial events with less data than maxLength according
to implementation constraints. Note also that maxLength and to implementation constraints. Note also that maxLength and
minIncompleteLength are intended only to manage buffering, and are minIncompleteLength are intended only to manage buffering, and are
not interpreted as a receiver preference for message reordering. not interpreted as a receiver preference for message reordering.
8.2. Receive Events 8.3.2. Receive Events
Each call to Receive will be paired with a single Receive Event, Each call to Receive will be paired with a single Receive Event,
which can be a success or an error. This allows an application to which can be a success or an error. This allows an application to
provide backpressure to the transport stack when it is temporarily provide backpressure to the transport stack when it is temporarily
not ready to receive messages. not ready to receive messages.
The interface should allow the application to correlate which call to The interface should allow the application to correlate which call to
Receive resulted in a particular Receive Event. The manner in which Receive resulted in a particular Receive Event. The manner in which
this correlation is indicated is implementation-specific. this correlation is indicated is implementation-specific.
8.2.1. Received 8.3.2.1. Received
Connection -> Received<messageData, messageContext> Connection -> Received<messageData, messageContext>
A Received event indicates the delivery of a complete Message. It A Received event indicates the delivery of a complete Message. It
contains two objects, the received bytes as messageData, and the contains two objects, the received bytes as messageData, and the
metadata and properties of the received Message as messageContext. metadata and properties of the received Message as messageContext.
The messageData object provides access to the bytes that were The messageData object provides access to the bytes that were
received for this Message, along with the length of the byte array. received for this Message, along with the length of the byte array.
The messageContext is provided to enable retrieving metadata about The messageContext is provided to enable retrieving metadata about
the message and referring to the message, e.g., to send replies and the message and referring to the message, e.g., to send replies and
map responses to their requests. See Section 7.4 for details. map responses to their requests. See Section 8.1.1 for details.
See Section 9 for handling Message framing in situations where the See Section 8.1.2 for handling Message framing in situations where
Protocol Stack only provides a byte-stream transport. the Protocol Stack only provides a byte-stream transport.
8.2.2. ReceivedPartial 8.3.2.2. ReceivedPartial
Connection -> ReceivedPartial<messageData, messageContext, endOfMessage> Connection -> ReceivedPartial<messageData, messageContext, endOfMessage>
If a complete Message cannot be delivered in one event, one part of If a complete Message cannot be delivered in one event, one part of
the Message may be delivered with a ReceivedPartial event. In order the Message may be delivered with a ReceivedPartial event. In order
to continue to receive more of the same Message, the application must to continue to receive more of the same Message, the application must
invoke Receive again. invoke Receive again.
Multiple invocations of ReceivedPartial deliver data for the same Multiple invocations of ReceivedPartial deliver data for the same
Message by passing the same MessageContext, until the endOfMessage Message by passing the same MessageContext, until the endOfMessage
skipping to change at page 47, line 10 skipping to change at page 57, line 47
If the minIncompleteLength in the Receive request was set to be If the minIncompleteLength in the Receive request was set to be
infinite (indicating a request to receive only complete Messages), infinite (indicating a request to receive only complete Messages),
the ReceivedPartial event may still be delivered if one of the the ReceivedPartial event may still be delivered if one of the
following conditions is true: following conditions is true:
o the underlying Protocol Stack supports message boundary o the underlying Protocol Stack supports message boundary
preservation, and the size of the Message is larger than the preservation, and the size of the Message is larger than the
buffers available for a single message; buffers available for a single message;
o the underlying Protocol Stack does not support message boundary o the underlying Protocol Stack does not support message boundary
preservation, and the Message Framer (see Section 9) cannot preservation, and the Message Framer (see Section 8.1.2) cannot
determine the end of the message using the buffer space it has determine the end of the message using the buffer space it has
available; or available; or
o the underlying Protocol Stack does not support message boundary o the underlying Protocol Stack does not support message boundary
preservation, and no Message Framer was supplied by the preservation, and no Message Framer was supplied by the
application application
Note that in the absence of message boundary preservation or a Note that in the absence of message boundary preservation or a
Message Framer, all bytes received on the Connection will be Message Framer, all bytes received on the Connection will be
represented as one large Message of indeterminate length. represented as one large Message of indeterminate length.
8.2.3. ReceiveError 8.3.2.3. ReceiveError
Connection -> ReceiveError<messageContext, reason?> Connection -> ReceiveError<messageContext, reason?>
A ReceiveError occurs when data is received by the underlying A ReceiveError occurs when data is received by the underlying
Protocol Stack that cannot be fully retrieved or parsed, or when some Protocol Stack that cannot be fully retrieved or parsed, or when some
other indication is received that reception has failed. In contrast, other indication is received that reception has failed. In contrast,
conditions that irrevocably lead to the termination of the Connection conditions that irrevocably lead to the termination of the Connection
are signaled using ConnectionError instead (see Section 11). are signaled using ConnectionError instead (see Section 9).
The ReceiveError event passes an optional associated MessageContext. The ReceiveError event passes an optional associated MessageContext.
This may indicate that a Message that was being partially received This may indicate that a Message that was being partially received
previously, but had not completed, encountered an error and will not previously, but had not completed, encountered an error and will not
be completed. be completed.
8.3. Receive Message Properties 8.3.3. Receive Message Properties
Each Message Context may contain metadata from protocols in the Each Message Context may contain metadata from protocols in the
Protocol Stack; which metadata is available is Protocol Stack Protocol Stack; which metadata is available is Protocol Stack
dependent. These are exposed though additional read-only Message dependent. These are exposed though additional read-only Message
Properties that can be queried from the MessageContext object (see Properties that can be queried from the MessageContext object (see
Section 7.4) passed by the receive event. The following metadata Section 8.1.1) passed by the receive event. The following metadata
values are supported: values are supported:
8.3.1. UDP(-Lite)-specific Property: ECN 8.3.3.1. UDP(-Lite)-specific Property: ECN
When available, Message metadata carries the value of the Explicit When available, Message metadata carries the value of the Explicit
Congestion Notification (ECN) field. This information can be used Congestion Notification (ECN) field. This information can be used
for logging and debugging purposes, and for building applications for logging and debugging purposes, and for building applications
which need access to information about the transport internals for which need access to information about the transport internals for
their own operation. This property is specific to UDP and UDP-Lite their own operation. This property is specific to UDP and UDP-Lite
because these protocols do not implement congestion control, and because these protocols do not implement congestion control, and
hence expose this functionality to the application. hence expose this functionality to the application.
8.3.2. Early Data 8.3.3.2. Early Data
In some cases it may be valuable to know whether data was read as In some cases it may be valuable to know whether data was read as
part of early data transfer (before connection establishment has part of early data transfer (before connection establishment has
finished). This is useful if applications need to treat early data finished). This is useful if applications need to treat early data
separately, e.g., if early data has different security properties separately, e.g., if early data has different security properties
than data sent after connection establishment. In the case of TLS than data sent after connection establishment. In the case of TLS
1.3, client early data can be replayed maliciously (see [RFC8446]). 1.3, client early data can be replayed maliciously (see [RFC8446]).
Thus, receivers may wish to perform additional checks for early data 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 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 recipient Message was sent as part of early data, the corresponding
metadata carries a flag indicating as such. If early data is metadata carries a flag indicating as such. If early data is
enabled, applications should check this metadata field for Messages enabled, applications should check this metadata field for Messages
received during connection establishment and respond accordingly. received during connection establishment and respond accordingly.
8.3.3. Receiving Final Messages 8.3.3.3. Receiving Final Messages
The Message Context can indicate whether or not this Message is the 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 Message on a Connection. For any Message that is marked as
Final, the application can assume that there will be no more Messages Final, the application can assume that there will be no more Messages
received on the Connection once the Message has been completely received on the Connection once the Message has been completely
delivered. This corresponds to the Final property that may be marked delivered. This corresponds to the Final property that may be marked
on a sent Message, see Section 7.5.5. on a sent Message, see Section 8.1.3.5.
Some transport protocols and peers may not support signaling of the Some transport protocols and peers may not support signaling of the
Final property. Applications therefore should not rely on receiving Final property. Applications therefore should not rely on receiving
a Message marked Final to know that the other endpoint is done a Message marked Final to know that the other endpoint is done
sending on a connection. sending on a connection.
Any calls to Receive once the Final Message has been delivered will Any calls to Receive once the Final Message has been delivered will
result in errors. result in errors.
9. Message Framers 9. Connection Termination
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.
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.
To use a Message Framer, the application adds it to its Preconnection
object. Then, the Message Framer can intercept all calls to Send()
or Receive() on a Connection to add Message semantics, in addition to
interacting with the setup and teardown of the Connection. A Framer
can start sending data before the application sends data if the
framing protocol requires a prefix or handshake (see [RFC8229] for an
example of such a framing protocol).
Initiate() Send() Receive() Close()
| | ^ |
| | | |
+----v----------v---------+----------v-----+
| Connection |
+----+----------+---------^----------+-----+
| | | |
| +-----------------+ |
| | Messages | |
| +-----------------+ |
| | | |
+----v----------v---------+----------v-----+
| Framer(s) |
+----+----------+---------^----------+-----+
| | | |
| +-----------------+ |
| | Byte-stream | |
| +-----------------+ |
| | | |
+----v----------v---------+----------v-----+
| Transport Protocol Stack |
+------------------------------------------+
Note that while Message Framers add the most value when placed above
a protocol that otherwise does not preserve message boundaries, they
can also be used with datagram- or message-based protocols. In these
cases, they add an additional transformation to further encode or
encapsulate, and can potentially support packing multiple
application-layer Messages into individual transport datagrams.
The API to implement a Message Framer can vary depending on the
implementation; guidance on implementing Message Framers can be found
in [I-D.ietf-taps-impl].
9.1. Adding Message Framers to Connections
The Message Framer object can be added to one or more Preconnections
to run on top of transport protocols. Multiple Framers may be added.
If multiple Framers are added, the last one added runs first when
framing outbound messages, and last when parsing inbound data.
The following example adds a basic HTTP Message Framer to a
Preconnection:
framer := NewHTTPMessageFramer()
Preconnection.AddFramer(framer)
9.2. Framing Meta-Data
When sending Messages, applications can add specific Message values
to a MessageContext (Section 7.4) that is intended for a Framer.
This can be used, for example, to set the type of a Message for a TLV
format. The namespace of values is custom for each unique Message
Framer.
messageContext := NewMessageContext()
messageContext.add(framer, key, value)
Connection.Send(messageData, messageContext)
When an application receives a MessageContext in a Receive event, it
can also look to see if a value was set by a specific Message Framer.
messageContext.get(framer, key) -> value
For example, if an HTTP Message Framer is used, the values could
correspond to HTTP headers:
httpFramer := NewHTTPMessageFramer()
...
messageContext := NewMessageContext()
messageContext.add(httpFramer, "accept", "text/html")
10. Managing Connections
During pre-establishment and after establishment, connections can be
configured and queried using Connection Properties, and asynchronous
information may be available about the state of the connection via
Soft Errors.
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 Section 10.1 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.
The application can set and query Connection Properties on a per-
Connection basis. Connection Properties that are not read-only can
be set during pre-establishment (see Section 5.2), as well as on
connections directly using the SetProperty action:
Connection.SetProperty(property, value)
Note that changing one of the Connection Properties on one Connection
in a Connection Group will also change it for all other Connections
of that group; see further Section 6.4.
At any point, the application can query Connection Properties.
ConnectionProperties := Connection.GetProperties()
Depending on the status of the connection, the queried Connection
Properties will include different information:
o The connection state, which can be one of the following:
Establishing, Established, Closing, or Closed.
o 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 Section 7.5.5.
o 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 Section 8.3.3. The latter is only supported by
certain transport protocols, e.g., by TCP as half-closed
connection.
o For Connections that are Establishing: Transport Properties that
the application specified on the Preconnection, see Section 5.2.
o For Connections that are Established, Closing, or Closed:
Selection (Section 5.2) and Connection Properties (Section 10.1)
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.
o For Connections that are Established, additional properties of the
path(s) in use. These properties can be derived from the local
provisioning domain [RFC7556], measurements by the Protocol Stack,
or other sources.
10.1. Generic Connection Properties
Generic Connection Properties are defined independent of the chosen
protocol stack and therefore available on all Connections.
Note that many Connection Properties have a corresponding Selection
Property which enables applications to express their preference for
protocols providing a supporting transport feature.
10.1.1. Retransmission Threshold Before Excessive Retransmission
Notification
Name: retransmitNotifyThreshold
Type: Integer, with special value "Disabled"
Default: Disabled
This property specifies after how many retransmissions to inform the
application about "Excessive Retransmissions".
10.1.2. Required Minimum Corruption Protection Coverage for Receiving
Name: recvChecksumLen
Type: Integer, with special value "Full Coverage"
Default: Full Coverage
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.
10.1.3. Priority (Connection)
Name: connPrio
Type: Integer
Default: 100
This Property is a non-negative integer representing the relative
inverse priority (i.e., a lower value reflects a higher priority) of
this Connection relative to other Connections in the same Connection
Group. It has no effect on Connections not part of a Connection
Group. As noted in Section 6.4, this property is not entangled when
Connections are cloned, i.e., changing the Priority on one Connection
in a Connection Group does not change it on the other Connections in
the same Connection Group.
10.1.4. Timeout for Aborting Connection
Name: connTimeout
Type: Numeric, with special value "Disabled"
Default: Disabled
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).
10.1.5. Connection Group Transmission Scheduler
Name: connScheduler
Type: Enumeration
Default: Weighted Fair Queueing (see Section 3.6 in [RFC8260])
This property specifies which scheduler should be used among
Connections within a Connection Group, see Section 6.4. The set of
schedulers can be taken from [RFC8260].
10.1.6. Capacity Profile
Name: connCapacityProfile
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.
The following values are valid for the Capacity Profile:
Default: 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.
Scavenger: The application is not interactive. It expects to send
and/or receive data without any urgency. This can, for example,
be used to select protocol stacks with scavenger transmission
control and/or to assign the traffic to a lower-effort service.
Transport system implementations that map the requested capacity
profile onto per-connection DSCP signaling SHOULD assign the DSCP
Less than Best Effort [RFC8622] PHB.
Low Latency/Interactive: 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.
Low Latency/Non-Interactive: 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.
Constant-Rate Streaming: 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.
Capacity-Seeking: The application expects to send/receive data at
the maximum rate allowed by its congestion controller over a
relatively long period of time. Transport system implementations
that map the requested capacity profile onto per-connection DSCP
signaling without multiplexing SHOULD assign a DSCP Assured
Forwarding (AF11,AF12,AF13,AF14) [RFC2597] PHB per Section 4.8 of
[RFC4594].
The Capacity Profile for a selected protocol stack may be modified on
a per-Message basis using the Transmission Profile Message Property;
see Section 7.5.8.
10.1.7. Policy for using Multi-Path Transports
Name: multipath-policy
Type: Enumeration
Default: Handover
This property specifies the local policy of transferring data across
multiple paths between the same end hosts if Parallel Use of Multiple
Paths not set to Disabled (see Section 5.2.13). Possible values are:
Handover: 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.
Interactive: 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.
Aggregate: 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.
Note that this is a local choice - the peer endpoint can choose a
different policy.
10.1.8. Bounds on Send or Receive Rate
Name: maxSendRate / maxRecvRate
Type: Numeric (with special value "Unlimited") / Numeric (with
special value "Unlimited")
Default: Unlimited / Unlimited
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.
10.1.9. Read-only Connection Properties
The following generic Connection Properties are read-only, i.e. they
cannot be changed by an application.
10.1.9.1. Maximum Message Size Concurrent with Connection Establishment
Name: zeroRttMsgMaxLen
Type: Integer
This property represents the maximum Message size that can be sent
before or during Connection establishment, see also Section 7.5.4.
It is given in Bytes.
10.1.9.2. Maximum Message Size Before Fragmentation or Segmentation
Name: singularTransmissionMsgMaxLen
Type: Integer
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].
10.1.9.3. Maximum Message Size on Send
Name: sendMsgMaxLen
Type: Integer
This property represents the maximum Message size that can be sent
using a send operation.
10.1.9.4. Maximum Message Size on Receive
Name: recvMsgMaxLen
Type: Integer
This numeric property represents the maximum Message size that can be
received.
10.2. TCP-specific Properties: User Timeout Option (UTO)
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.
These TCP-specific properties are included here because the feature
"Suggest timeout to the peer" is part of the minimal set of transport
services [I-D.ietf-taps-minset], where this feature was categorized
as "functional". This means that when an implementation offers this
feature, it has to expose an interface to it to the application.
Otherwise, the implementation might violate assumptions by the
application, which could cause the application to fail.
All of the below properties are optional (e.g., it is possible to
specify "User Timeout Enabled" as true, but not specify an Advertised
User Timeout value; in this case, the TCP default will be used).
10.2.1. Advertised User Timeout
Name: tcp.userTimeoutValue
Type: Integer
Default: the TCP default
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 Section 10.1.4) value accordingly.
10.2.2. User Timeout Enabled
Name: tcp.userTimeout
Type: Boolean
Default: false
This property controls whether the UTO option is enabled for a
connection. This applies to both sending and receiving.
10.2.3. Timeout Changeable
Name: tcp.userTimeoutRecv
Type: Boolean
Default: true
This property controls whether the "Timeout for aborting Connection"
(see Section 10.1.4) may be changed based on a UTO option received
from the remote peer. This boolean becomes false when "Timeout for
aborting Connection" (see Section 10.1.4) is used.
10.3. Connection Lifecycle Events
During the lifetime of a connection there are events that can occur
when configured.
10.3.1. Soft Errors
Asynchronous introspection is also possible, via the SoftError Event.
This event informs the application about the receipt and contents of
an ICMP error message related to the Connection. This will only
happen if the underlying protocol stack supports access to soft
errors; however, even if the underlying stack supports it, there is
no guarantee that a soft error will be signaled.
Connection -> SoftError<>
10.3.2. Excessive retransmissions
This event notifies the application of excessive retransmissions,
based on a configured threshold (see Section 10.1.1). This will only
happen if the underlying protocol stack supports reliability and,
with it, such notifications.
Connection -> ExcessiveRetransmission<>
11. Connection Termination
Close terminates a Connection after satisfying all the requirements Close terminates a Connection after satisfying all the requirements
that were specified regarding the delivery of Messages that the that were specified regarding the delivery of Messages that the
application has already given to the transport system. For example, application has already given to the transport system. For example,
if reliable delivery was requested for a Message handed over before if reliable delivery was requested for a Message handed over before
calling Close, the transport system will ensure that this Message is calling Close, the transport system will ensure that this Message is
indeed delivered. If the Remote Endpoint still has data to send, it indeed delivered. If the Remote Endpoint still has data to send, it
cannot be received after this call. cannot be received after this call.
Connection.Close() Connection.Close()
skipping to change at page 59, line 46 skipping to change at page 60, line 4
The Closed Event can inform the application that the Remote Endpoint The Closed Event can inform the application that the Remote Endpoint
has closed the Connection; however, there is no guarantee that a has closed the Connection; however, there is no guarantee that a
remote Close will indeed be signaled. remote Close will indeed be signaled.
Connection -> Closed<> Connection -> Closed<>
Abort terminates a Connection without delivering remaining data: Abort terminates a Connection without delivering remaining data:
Connection.Abort() Connection.Abort()
A ConnectionError informs the application that data to could not be A ConnectionError informs the application that data to could not be
delivered after a timeout, or the other side has aborted the delivered after a timeout, or the other side has aborted the
Connection; however, there is no guarantee that an Abort will indeed Connection; however, there is no guarantee that an Abort will indeed
be signaled. be signaled.
Connection -> ConnectionError<reason?> Connection -> ConnectionError<reason?>
12. Connection State and Ordering of Operations and Events 10. Connection State and Ordering of Operations and Events
As this interface is designed to be independent of an As this interface is designed to be independent of an
implementation's concurrency model, the details of how exactly implementation's concurrency model, the details of how exactly
actions are handled, and how events are dispatched, are actions are handled, and how events are dispatched, are
implementation dependent. implementation dependent.
Each transition of connection state is associated with one of more Each transition of connection state is associated with one of more
events: events:
o Ready<> occurs when a Connection created with Initiate() or o Ready<> occurs when a Connection created with Initiate() or
skipping to change at page 61, line 23 skipping to change at page 61, line 38
o No events will occur on a Connection after it is Closed; i.e., o No events will occur on a Connection after it is Closed; i.e.,
after a Closed<> event, an InitiateError<> or ConnectionError<> on after a Closed<> event, an InitiateError<> or ConnectionError<> on
that connection. To ensure this ordering, Closed<> will not occur that connection. To ensure this ordering, Closed<> will not occur
on a Connection while other events on the Connection are still on a Connection while other events on the Connection are still
locally outstanding (i.e., known to the interface and waiting to locally outstanding (i.e., known to the interface and waiting to
be dealt with by the application). ConnectionError<> may occur be dealt with by the application). ConnectionError<> may occur
after Closed<>, but the interface must gracefully handle all cases after Closed<>, but the interface must gracefully handle all cases
where application ignores these errors. where application ignores these errors.
13. IANA Considerations 11. IANA Considerations
RFC-EDITOR: Please remove this section before publication. RFC-EDITOR: Please remove this section before publication.
This document has no Actions for IANA. Later versions of this This document has no Actions for IANA. Later versions of this
document may create IANA registries for generic transport property document may create IANA registries for generic transport property
names and transport property namespaces (see Section 4.2.1). names and transport property namespaces (see Section 4.2.1).
14. Security Considerations 12. Security Considerations
This document describes a generic API for interacting with a This document describes a generic API for interacting with a
transport services (TAPS) system. Part of this API includes transport services (TAPS) system. Part of this API includes
configuration details for transport security protocols, as discussed configuration details for transport security protocols, as discussed
in Section 5.3. It does not recommend use (or disuse) of specific in Section 5.3. It does not recommend use (or disuse) of specific
algorithms or protocols. Any API-compatible transport security algorithms or protocols. Any API-compatible transport security
protocol should work in a TAPS system. Security consideration for protocol should work in a TAPS system. Security consideration for
these protocols should be discussed in the respective specifications. these protocols should be discussed in the respective specifications.
The desribed API is used to exchange information between an The desribed API is used to exchange information between an
skipping to change at page 62, line 46 skipping to change at page 63, line 14
innovations and new protocols in the transport system but at the same innovations and new protocols in the transport system but at the same
time may reduce transparency of the underlying communication actions time may reduce transparency of the underlying communication actions
to the application itself. The TAPS API is designed such that to the application itself. The TAPS API is designed such that
protocol and path selection can be limited to a small and controlled protocol and path selection can be limited to a small and controlled
set if required by the application for functional or security set if required by the application for functional or security
purposes. Further, TAPS implementations should provide an interface purposes. Further, TAPS implementations should provide an interface
to poll information about which protocol and path is currently in use to poll information about which protocol and path is currently in use
as well as provide logging about the communication events of each as well as provide logging about the communication events of each
connection. connection.
15. Acknowledgements 13. Acknowledgements
This work has received funding from the European Union's Horizon 2020 This work has received funding from the European Union's Horizon 2020
research and innovation programme under grant agreements No. 644334 research and innovation programme under grant agreements No. 644334
(NEAT) and No. 688421 (MAMI). (NEAT) and No. 688421 (MAMI).
This work has been supported by Leibniz Prize project funds of DFG - This work has been supported by Leibniz Prize project funds of DFG -
German Research Foundation: Gottfried Wilhelm Leibniz-Preis 2011 (FKZ German Research Foundation: Gottfried Wilhelm Leibniz-Preis 2011 (FKZ
FE 570/4-1). FE 570/4-1).
This work has been supported by the UK Engineering and Physical This work has been supported by the UK Engineering and Physical
skipping to change at page 63, line 23 skipping to change at page 63, line 38
its "Toppforsk" programme through the "OCARINA" project. its "Toppforsk" programme through the "OCARINA" project.
Thanks to Stuart Cheshire, Josh Graessley, David Schinazi, and Eric Thanks to Stuart Cheshire, Josh Graessley, David Schinazi, and Eric
Kinnear for their implementation and design efforts, including Happy Kinnear for their implementation and design efforts, including Happy
Eyeballs, that heavily influenced this work. Thanks to Laurent Chuat Eyeballs, that heavily influenced this work. Thanks to Laurent Chuat
and Jason Lee for initial work on the Post Sockets interface, from and Jason Lee for initial work on the Post Sockets interface, from
which this work has evolved. Thanks to Maximilian Franke for asking which this work has evolved. Thanks to Maximilian Franke for asking
good questions based on implementation experience and for good questions based on implementation experience and for
contributing text, e.g., on multicast. contributing text, e.g., on multicast.
16. References 14. References
16.1. Normative References 14.1. Normative References
[I-D.ietf-taps-arch] [I-D.ietf-taps-arch]
Pauly, T., Trammell, B., Brunstrom, A., Fairhurst, G., Pauly, T., Trammell, B., Brunstrom, A., Fairhurst, G.,
Perkins, C., Tiesel, P., and C. Wood, "An Architecture for Perkins, C., Tiesel, P., and C. Wood, "An Architecture for
Transport Services", draft-ietf-taps-arch-08 (work in Transport Services", draft-ietf-taps-arch-08 (work in
progress), July 2020. progress), July 2020.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
skipping to change at page 64, line 9 skipping to change at page 64, line 23
[RFC8303] Welzl, M., Tuexen, M., and N. Khademi, "On the Usage of [RFC8303] Welzl, M., Tuexen, M., and N. Khademi, "On the Usage of
Transport Features Provided by IETF Transport Protocols", Transport Features Provided by IETF Transport Protocols",
RFC 8303, DOI 10.17487/RFC8303, February 2018, RFC 8303, DOI 10.17487/RFC8303, February 2018,
<https://www.rfc-editor.org/info/rfc8303>. <https://www.rfc-editor.org/info/rfc8303>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
<https://www.rfc-editor.org/info/rfc8446>. <https://www.rfc-editor.org/info/rfc8446>.
16.2. Informative References 14.2. Informative References
[I-D.ietf-taps-impl] [I-D.ietf-taps-impl]
Brunstrom, A., Pauly, T., Enghardt, T., Grinnemo, K., Brunstrom, A., Pauly, T., Enghardt, T., Grinnemo, K.,
Jones, T., Tiesel, P., Perkins, C., and M. Welzl, Jones, T., Tiesel, P., Perkins, C., and M. Welzl,
"Implementing Interfaces to Transport Services", draft- "Implementing Interfaces to Transport Services", draft-
ietf-taps-impl-07 (work in progress), July 2020. ietf-taps-impl-07 (work in progress), July 2020.
[I-D.ietf-taps-minset] [I-D.ietf-taps-minset]
Welzl, M. and S. Gjessing, "A Minimal Set of Transport Welzl, M. and S. Gjessing, "A Minimal Set of Transport
Services for End Systems", draft-ietf-taps-minset-11 (work Services for End Systems", draft-ietf-taps-minset-11 (work
skipping to change at page 68, line 39 skipping to change at page 68, line 41
| | | | | |
| congestionControl | ignore | | congestionControl | ignore |
| | | | | |
| preserveMsgBoundaries | require | | preserveMsgBoundaries | require |
| | | | | |
| safely replayable | true | | safely replayable | true |
+-----------------------+---------+ +-----------------------+---------+
Applications that choose this Transport Property Profile for latency Applications that choose this Transport Property Profile for latency
reasons should also consider setting the Capacity Profile Property, reasons should also consider setting the Capacity Profile Property,
see Section 10.1.6 accordingly and my benefit from controlling see Section 7.1.6 accordingly and my benefit from controlling
checksum coverage, see Section 5.2.7 and Section 5.2.8. checksum coverage, see Section 5.2.7 and Section 5.2.8.
Appendix B. Relationship to the Minimal Set of Transport Services for Appendix B. Relationship to the Minimal Set of Transport Services for
End Systems End Systems
[I-D.ietf-taps-minset] identifies a minimal set of transport services [I-D.ietf-taps-minset] identifies a minimal set of transport services
that end systems should offer. These services make all non-security- that end systems should offer. These services make all non-security-
related transport features of TCP, MPTCP, UDP, UDP-Lite, SCTP and related transport features of TCP, MPTCP, UDP, UDP-Lite, SCTP and
LEDBAT available that 1) require interaction with the application, LEDBAT available that 1) require interaction with the application,
and 2) do not get in the way of a possible implementation over TCP and 2) do not get in the way of a possible implementation over TCP
skipping to change at page 69, line 16 skipping to change at page 69, line 19
[I-D.ietf-taps-minset], which refers to the primitives in "pass 2" [I-D.ietf-taps-minset], which refers to the primitives in "pass 2"
(Section 4) of [RFC8303] for further details on the implementation (Section 4) of [RFC8303] for further details on the implementation
with TCP, MPTCP, UDP, UDP-Lite, SCTP and LEDBAT. with TCP, MPTCP, UDP, UDP-Lite, SCTP and LEDBAT.
o Connect: "Initiate" Action (Section 6.1). o Connect: "Initiate" Action (Section 6.1).
o Listen: "Listen" Action (Section 6.2). o Listen: "Listen" Action (Section 6.2).
o Specify number of attempts and/or timeout for the first o Specify number of attempts and/or timeout for the first
establishment message: "timeout" parameter of "Initiate" establishment message: "timeout" parameter of "Initiate"
(Section 6.1) or "InitiateWithSend" Action (Section 7.8). (Section 6.1) or "InitiateWithSend" Action (Section 8.2.6).
o Disable MPTCP: "Parallel Use of Multiple Paths" Property o Disable MPTCP: "Parallel Use of Multiple Paths" Property
(Section 5.2.13). (Section 5.2.13).
o Hand over a message to reliably transfer (possibly multiple times) o Hand over a message to reliably transfer (possibly multiple times)
before connection establishment: "InitiateWithSend" Action before connection establishment: "InitiateWithSend" Action
(Section 7.8). (Section 8.2.6).
o Change timeout for aborting connection (using retransmit limit or o Change timeout for aborting connection (using retransmit limit or
time value): "Timeout for Aborting Connection" property, using a time value): "Timeout for Aborting Connection" property, using a
time value (Section 10.1.4). time value (Section 7.1.4).
o Timeout event when data could not be delivered for too long: o Timeout event when data could not be delivered for too long:
"ConnectionError" Event (Section 11). "ConnectionError" Event (Section 9).
o Suggest timeout to the peer: "TCP-specific Property: User Timeout" o Suggest timeout to the peer: "TCP-specific Property: User Timeout"
(Section 10.2). (Section 7.2).
o Notification of Excessive Retransmissions (early warning below o Notification of Excessive Retransmissions (early warning below
abortion threshold): "Notification of excessive retransmissions" abortion threshold): "Notification of excessive retransmissions"
property (Section 5.2.16). property (Section 5.2.16).
o Notification of ICMP error message arrival: "Notification of ICMP o Notification of ICMP error message arrival: "Notification of ICMP
soft error message arrival" property (Section 5.2.17). soft error message arrival" property (Section 5.2.17).
o Choose a scheduler to operate between streams of an association: o Choose a scheduler to operate between streams of an association:
"Connection Group Transmission Scheduler" property "Connection Group Transmission Scheduler" property
(Section 10.1.5). (Section 7.1.5).
o Configure priority or weight for a scheduler: "Priority o Configure priority or weight for a scheduler: "Priority
(Connection)" property (Section 10.1.3). (Connection)" property (Section 7.1.3).
o "Specify checksum coverage used by the sender" and "Disable o "Specify checksum coverage used by the sender" and "Disable
checksum when sending": "Corruption Protection Length" property checksum when sending": "Corruption Protection Length" property
(Section 7.5.6) and "Full Checksum Coverage on Sending" property (Section 8.1.3.6) and "Full Checksum Coverage on Sending" property
(Section 5.2.7). (Section 5.2.7).
o "Specify minimum checksum coverage required by receiver" and o "Specify minimum checksum coverage required by receiver" and
"Disable checksum requirement when receiving": "Required Minimum "Disable checksum requirement when receiving": "Required Minimum
Corruption Protection Coverage for Receiving" property Corruption Protection Coverage for Receiving" property
(Section 10.1.2) and "Full Checksum Coverage on Receiving" (Section 7.1.2) and "Full Checksum Coverage on Receiving" property
property (Section 5.2.8). (Section 5.2.8).
o "Specify DF" field and "Request not to bundle messages": the "No o "Specify DF" field and "Request not to bundle messages": the "No
Fragmentation" Message Property combines both of these requests, Fragmentation" Message Property combines both of these requests,
i.e. if a request not to bundle messages is made, this also turns i.e. if a request not to bundle messages is made, this also turns
off fragmentation (i.e., sets DF=1) in the case of a protocol that off fragmentation (i.e., sets DF=1) in the case of a protocol that
allows this (only UDP and UDP-Lite, which cannot bundle messages allows this (only UDP and UDP-Lite, which cannot bundle messages
anyway) (Section 7.5.9). anyway) (Section 8.1.3.9).
o Get max. transport-message size that may be sent using a non- o Get max. transport-message size that may be sent using a non-
fragmented IP packet from the configured interface: "Maximum fragmented IP packet from the configured interface: "Maximum
Message Size Before Fragmentation or Segmentation" property Message Size Before Fragmentation or Segmentation" property
(Section 10.1.9.2). (Section 7.1.9.2).
o Get max. transport-message size that may be received from the o Get max. transport-message size that may be received from the
configured interface: "Maximum Message Size on Receive" property configured interface: "Maximum Message Size on Receive" property
(Section 10.1.9.4). (Section 7.1.9.4).
o Obtain ECN field: "ECN" is a defined UDP(-Lite)-specific read-only o Obtain ECN field: "ECN" is a defined UDP(-Lite)-specific read-only
Message Property of the MessageContext object (Section 8.3.1). Message Property of the MessageContext object (Section 8.3.3.1).
o "Specify DSCP field", "Disable Nagle algorithm", "Enable and o "Specify DSCP field", "Disable Nagle algorithm", "Enable and
configure a "Low Extra Delay Background Transfer"": as suggested configure a "Low Extra Delay Background Transfer"": as suggested
in Section 5.5 of [I-D.ietf-taps-minset], these transport features in Section 5.5 of [I-D.ietf-taps-minset], these transport features
are collectively offered via the "Capacity Profile" property are collectively offered via the "Capacity Profile" property
(Section 10.1.6). Per-Message control is offered via the "Message (Section 7.1.6). Per-Message control is offered via the "Message
Capacity Profile Override" property (Section 7.5.8). Capacity Profile Override" property (Section 8.1.3.8).
o Close after reliably delivering all remaining data, causing an o Close after reliably delivering all remaining data, causing an
event informing the application on the other side: this is offered event informing the application on the other side: this is offered
by the "Close" Action with slightly changed semantics in line with by the "Close" Action with slightly changed semantics in line with
the discussion in Section 5.2 of [I-D.ietf-taps-minset] the discussion in Section 5.2 of [I-D.ietf-taps-minset]
(Section 11). (Section 9).
o "Abort without delivering remaining data, causing an event o "Abort without delivering remaining data, causing an event
informing the application on the other side" and "Abort without informing the application on the other side" and "Abort without
delivering remaining data, not causing an event informing the delivering remaining data, not causing an event informing the
application on the other side": this is offered by the "Abort" application on the other side": this is offered by the "Abort"
action without promising that this is signaled to the other side. action without promising that this is signaled to the other side.
If it is, a "ConnectionError" Event will fire at the peer If it is, a "ConnectionError" Event will fire at the peer
(Section 11). (Section 9).
o "Reliably transfer data, with congestion control", "Reliably o "Reliably transfer data, with congestion control", "Reliably
transfer a message, with congestion control" and "Unreliably transfer a message, with congestion control" and "Unreliably
transfer a message": data is transferred via the "Send" action transfer a message": data is transferred via the "Send" action
(Section 7). Reliability is controlled via the "Reliable Data (Section 8.2). Reliability is controlled via the "Reliable Data
Transfer (Connection)" (Section 5.2.1) property and the "Reliable Transfer (Connection)" (Section 5.2.1) property and the "Reliable
Data Transfer (Message)" Message Property (Section 7.5.7). Data Transfer (Message)" Message Property (Section 8.1.3.7).
Transmitting data as a message or without delimiters is controlled Transmitting data as a message or without delimiters is controlled
via Message Framers (Section 9). The choice of congestion control via Message Framers (Section 8.1.2). The choice of congestion
is provided via the "Congestion control" property (Section 5.2.9). control is provided via the "Congestion control" property
(Section 5.2.9).
o Configurable Message Reliability: the "Lifetime" Message Property o Configurable Message Reliability: the "Lifetime" Message Property
implements a time-based way to configure message reliability implements a time-based way to configure message reliability
(Section 7.5.1). (Section 8.1.3.1).
o "Ordered message delivery (potentially slower than unordered)" and o "Ordered message delivery (potentially slower than unordered)" and
"Unordered message delivery (potentially faster than ordered)": "Unordered message delivery (potentially faster than ordered)":
these two transport features are controlled via the Message these two transport features are controlled via the Message
Property "Ordered" (Section 7.5.3). Property "Ordered" (Section 8.1.3.3).
o Request not to delay the acknowledgement (SACK) of a message: o Request not to delay the acknowledgement (SACK) of a message:
should the protocol support it, this is one of the transport should the protocol support it, this is one of the transport
features the transport system can apply when an application uses features the transport system can apply when an application uses
the "Capacity Profile" Property (Section 10.1.6) or the "Message the "Capacity Profile" Property (Section 7.1.6) or the "Message
Capacity Profile Override" Message Property (Section 7.5.8) with Capacity Profile Override" Message Property (Section 8.1.3.8) with
value "Low Latency/Interactive". value "Low Latency/Interactive".
o Receive data (with no message delimiting): "Received" Event o Receive data (with no message delimiting): "Received" Event
(Section 8.2.1). See Section 9 for handling Message framing in (Section 8.3.2.1). See Section 8.1.2 for handling Message framing
situations where the Protocol Stack only provides a byte-stream in situations where the Protocol Stack only provides a byte-stream
transport. transport.
o Receive a message: "Received" Event (Section 8.2.1), using Message o Receive a message: "Received" Event (Section 8.3.2.1), using
Framers (Section 9). Message Framers (Section 8.1.2).
o Information about partial message arrival: "ReceivedPartial" Event o Information about partial message arrival: "ReceivedPartial" Event
(Section 8.2.2). (Section 8.3.2.2).
o Notification of send failures: "Expired" Event (Section 7.3.2) and o Notification of send failures: "Expired" Event (Section 8.2.3.2)
"SendError" Event (Section 7.3.3). and "SendError" Event (Section 8.2.3.3).
o Notification that the stack has no more user data to send: o Notification that the stack has no more user data to send:
applications can obtain this information via the "Sent" Event applications can obtain this information via the "Sent" Event
(Section 7.3.1). (Section 8.2.3.1).
o Notification to a receiver that a partial message delivery has o Notification to a receiver that a partial message delivery has
been aborted: "ReceiveError" Event (Section 8.2.3). been aborted: "ReceiveError" Event (Section 8.3.2.3).
Authors' Addresses Authors' Addresses
Brian Trammell (editor) Brian Trammell (editor)
Google Switzerland GmbH Google Switzerland GmbH
Gustav-Gull-Platz 1 Gustav-Gull-Platz 1
8004 Zurich 8004 Zurich
Switzerland Switzerland
Email: ietf@trammell.ch Email: ietf@trammell.ch
 End of changes. 134 change blocks. 
804 lines changed or deleted 792 lines changed or added

This html diff was produced by rfcdiff 1.46. The latest version is available from http://tools.ietf.org/tools/rfcdiff/