An Abstract Application Layer Interface to Transport Services

4.1.1. Server Example

This is an example of how an application might listen for incoming Connections using the Transport Services Interface, and receive a request, and send a response.¶

LocalSpecifier := NewLocalEndpoint()
LocalSpecifier.WithInterface("any")
LocalSpecifier.WithService("https")

TransportProperties := NewTransportProperties()
TransportProperties.Require(preserve-msg-boundaries)
// Reliable Data Transfer and Preserve Order are Required by default

SecurityParameters := NewSecurityParameters()
SecurityParameters.Set('identity', identity)
SecurityParameters.Set('keypair', privateKey, publicKey)

// Specifying a remote endpoint is optional when using Listen()
Preconnection := NewPreconnection(LocalSpecifier,
                                  TransportProperties,
                                  SecurityParameters)

Listener := Preconnection.Listen()

Listener -> ConnectionReceived<Connection>

// Only receive complete messages in a Conn.Received handler
Connection.Receive()

Connection -> Received<messageDataRequest, messageContext>

//---- Receive event handler begin ----
Connection.Send(messageDataResponse)
Connection.Close()

// Stop listening for incoming Connections
// (this example supports only one Connection)
Listener.Stop()
//---- Receive event handler end ----

4.1.2. Client Example

This is an example of how an application might open two Connections to a remote application using the Transport Services Interface, and send a request as well as receive a response on each of them.¶

RemoteSpecifier := NewRemoteEndpoint()
RemoteSpecifier.WithHostname("example.com")
RemoteSpecifier.WithService("https")

TransportProperties := NewTransportProperties()
TransportProperties.Require(preserve-msg-boundaries)
// Reliable Data Transfer and Preserve Order are Required by default

SecurityParameters := NewSecurityParameters()
TrustCallback := NewCallback({
  // Verify identity of the remote endpoint, return the result
})
SecurityParameters.SetTrustVerificationCallback(TrustCallback)

// Specifying a local endpoint is optional when using Initiate()
Preconnection := NewPreconnection(RemoteSpecifier,
                                  TransportProperties,
                                  SecurityParameters)

Connection := Preconnection.Initiate()
Connection2 := Connection.Clone()

Connection -> Ready<>
Connection2 -> Ready<>

//---- Ready event handler for any Connection C begin ----
C.Send(messageDataRequest)

// Only receive complete messages
C.Receive()
//---- Ready event handler for any Connection C end ----

Connection -> Received<messageDataResponse, messageContext>
Connection2 -> Received<messageDataResponse, messageContext>

// Close the Connection in a Receive event handler
Connection.Close()
Connection2.Close()

4.1.3. Peer Example

This is an example of how an application might establish a connection with a peer using Rendezvous(), send a Message, and receive a Message.¶

LocalSpecifier := NewLocalEndpoint()
LocalSpecifier.WithPort(9876)

RemoteSpecifier := NewRemoteEndpoint()
RemoteSpecifier.WithHostname("example.com")
RemoteSpecifier.WithPort(9877)

TransportProperties := NewTransportProperties()
TransportProperties.Require(preserve-msg-boundaries)
// Reliable Data Transfer and Preserve Order are Required by default

SecurityParameters := NewSecurityParameters()
SecurityParameters.Set('identity', identity)
SecurityParameters.Set('keypair', privateKey, publicKey)

TrustCallback := New Callback({
  // Verify identity of the remote endpoint, return the result
})
SecurityParameters.SetTrustVerificationCallback(trustCallback)

// Both local and remote endpoint must be specified
Preconnection := NewPreconnection(LocalSpecifier,
                                  RemoteSpecifier,
                                  TransportProperties,
                                  SecurityParameters)

Preconnection.Rendezvous()

Preconnection -> RendezvousDone<Connection>

//---- Ready event handler begin ----
Connection.Send(messageDataRequest)

// Only receive complete messages
Connection.Receive()
//---- Ready event handler end ----

Connection -> Received<messageDataResponse, messageContext>

// Close the Connection in a Receive event handler
Connection.Close()

4.2.1. Transport Property Names

Transport Properties are referred to by property names. For the purposes of this document, these names are alphanumeric strings in which words may be separated by hyphens. These names serve two purposes:¶

• Allowing different components of a TAPS implementation to pass Transport Properties, e.g., between a language frontend and a policy manager, or as a representation of properties retrieved from a file or other storage.¶
• Making the code of different TAPS implementations look similar. While individual programming languages may preclude strict adherence to the aforementioned naming convention (for instance, by prohibiting the use of hyphens in symbols), users interacting with multiple implementations will still benefit from the consistency resulting from the use of visually similar symbols.¶

Transport Property Names are hierarchically organized in the form [<Namespace>.]<PropertyName>.¶

• The Namespace component MUST be empty for well-known, generic properties, i.e., for properties that are not specific to a protocol and are defined in an RFC.¶
• Protocol Specific Properties MUST use the protocol acronym as the Namespace, e.g., tcp for TCP specific Transport Properties. For IETF protocols, property names under these namespaces SHOULD be defined in an RFC.¶
• Vendor or implementation specific properties MUST use a string identifying the vendor or implementation as the Namespace.¶

Namespaces for each of the keywords provided in the IANA protocol numbers registry (see https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml), reformatted where necessary to conform to an implementation's naming conventions, are reserved for Protocol Specific Properties and MUST NOT be used for vendor or implementation-specific properties.¶

4.2.2. Transport Property Types

Transport Properties can have one of a set of data types:¶

• Boolean: can take the values true and false; representation is implementation-dependent.¶
• Integer: can take positive or negative numeric integer values; range and representation is implementation-dependent.¶
• Numeric: can take positive or negative numeric values; range and representation is implementation-dependent.¶
• Enumeration: can take one value of a finite set of values, dependent on the property itself. The representation is implementation dependent.¶
• Preference: can take one of five values (Prohibit, Avoid, Ignore, Prefer, Require) for the level of preference of a given property during protocol selection; see Section 5.2. When querying, a Preference is of type Boolean, with true indicating that the Selection Property has been applied.¶
• Tuple: An ordered grouping of multiple value types. In this this document, it is written as a list in brackets, e.g., (Enumeration, Preference) The composition of types and their order depends on the property and is fixed for the property. The actual representation is implementation-dependent.¶
• Collection: An unordered grouping of one or more values of the same type. The actual representation, e.g. as a set or an array, is implementation-dependent.¶

For types Integer and Numeric, special values can be defined per property; it is up to implementations how these special values are represented (e.g., by using -1 for an otherwise non-negative value).¶

5.1.1. Using Multicast Endpoints

Specifying a multicast group address on a Local Endpoint will indicate to the transport system that the resulting connection will be used to receive multicast messages. The Remote Endpoint can be used to filter incoming multicast from specific senders. Such a Preconnection will only support calling Listen(), not Initiate(). The accepted Connections are receive-only.¶

Similarly, specifying a multicast group address on the Remote Endpoint will indicate that the resulting connection will be used to send multicast messages.¶

5.1.2. Endpoint Aliases

An Endpoint can have an alternative definition when using different protocols. For example, a server that supports both TLS/TCP and QUIC may be accessible on two different port numbers depending on which protocol is used.¶

To support this, Endpoint Objects can specify "aliases". An Endpoint can have multiple aliases set.¶

RemoteSpecifier.AddAlias(AlternateRemoteSpecifier)

In order to scope an alias to a specific transport protocol, an Endpoint can specify a protocol identifier. These identifiers MUST only be set for aliases.¶

RemoteSpecifier.WithProtocol(QUIC)

The following example shows a case where "example.com" has a server running on port 443, with an alternate port of 8443 for QUIC.¶

RemoteSpecifier := NewRemoteEndpoint()
RemoteSpecifier.WithHostname("example.com")
RemoteSpecifier.WithPort(443)

QUICRemoteSpecifier := NewRemoteEndpoint()
QUICRemoteSpecifier.WithHostname("example.com")
QUICRemoteSpecifier.WithPort(8443)
QUICRemoteSpecifier.WithProtocol(QUIC)

RemoteSpecifier.AddAlias(QUICRemoteSpecifier)

5.1.3. Endpoint Examples

The following examples of Endpoints show common usage patterns.¶

Specify a Remote Endpoint using a hostname and service name:¶

RemoteSpecifier := NewRemoteEndpoint()
RemoteSpecifier.WithHostname("example.com")
RemoteSpecifier.WithService("https")

Specify a Remote Endpoint using an IPv6 address and remote port:¶

RemoteSpecifier := NewRemoteEndpoint()
RemoteSpecifier.WithIPv6Address(2001:db8:4920:e29d:a420:7461:7073:0a)
RemoteSpecifier.WithPort(443)

Specify a Remote Endpoint using an IPv4 address and remote port:¶

RemoteSpecifier := NewRemoteEndpoint()
RemoteSpecifier.WithIPv4Address(192.0.2.21)
RemoteSpecifier.WithPort(443)

Specify a Local Endpoint using a local interface name and local port:¶

LocalSpecifier := NewLocalEndpoint()
LocalSpecifier.WithInterface("en0")
LocalSpecifier.WithPort(443)

As an alternative to specifying an interface name for the Local Endpoint, an application can express more fine-grained preferences using the Interface Instance or Type Selection Property, see Section 5.2.11. However, if the application specifies Selection Properties that are inconsistent with the Local Endpoint, this will result in an Error once the application attempts to open a Connection.¶

Specify a Local Endpoint using a STUN server:¶

LocalSpecifier := NewLocalEndpoint()
LocalSpecifier.WithStunServer(address, port, credentials)

Specify a Local Endpoint using a Any-Source Multicast group to join on a named local interface:¶

LocalSpecifier := NewLocalEndpoint()
LocalSpecifier.WithIPv4Address(233.252.0.0)
LocalSpecifier.WithInterface("en0")

Source-Specific Multicast requires setting both a Local and Remote Endpoint:¶

LocalSpecifier := NewLocalEndpoint()
LocalSpecifier.WithIPv4Address(232.1.1.1)
LocalSpecifier.WithInterface("en0")

RemoteSpecifier := NewRemoteEndpoint()
RemoteSpecifier.WithIPv4Address(192.0.2.22)

5.2.1. Reliable Data Transfer (Connection)

Name:

reliability¶

Type:

Preference¶

Default:

Require¶

This property specifies whether the application needs to use a transport protocol that ensures that all data is received at the Remote Endpoint without corruption. When reliable data transfer is enabled, this also entails being notified when a Connection is closed or aborted.¶

5.2.2. Preservation of Message Boundaries

Name:

preserveMsgBoundaries¶

Type:

Preference¶

Default:

Prefer¶

This property specifies whether the application needs or prefers to use a transport protocol that preserves message boundaries.¶

5.2.3. Configure Per-Message Reliability

Name:

perMsgReliability¶

Type:

Preference¶

Default:

Ignore¶

This property specifies whether an application considers it useful to indicate its reliability requirements on a per-Message basis. This property applies to Connections and Connection Groups.¶

5.2.4. Preservation of Data Ordering

Name:

preserveOrder¶

Type:

Preference¶

Default:

Require¶

This property specifies whether the application wishes to use a transport protocol that can ensure that data is received by the application on the other end in the same order as it was sent.¶

5.2.5. Use 0-RTT Session Establishment with a Safely Replayable Message

Name:

zeroRttMsg¶

Type:

Preference¶

Default:

Ignore¶

This property specifies whether an application would like to supply a Message to the transport protocol before Connection establishment that will then be reliably transferred to the other side before or during Connection establishment. This Message can potentially be received multiple times (i.e., multiple copies of the message data may be passed to the Remote Endpoint). See also Section 8.1.3.4. Note that disabling this property has no effect for protocols that are not connection-oriented and do not protect against duplicated messages, e.g., UDP.¶

5.2.6. Multistream Connections in Group

Name:

multistreaming¶

Type:

Preference¶

Default:

Prefer¶

This property specifies that the application would prefer multiple Connections within a Connection Group to be provided by streams of a single underlying transport connection where possible.¶

5.2.7. Full Checksum Coverage on Sending

Name:

perMsgChecksumLenSend¶

Type:

Preference¶

Default:

Require¶

This property specifies the application's need for protection against corruption for all data transmitted on this Connection. Disabling this property could enable later control of the sender checksum coverage (see Section 8.1.3.6).¶

5.2.8. Full Checksum Coverage on Receiving

Name:

perMsgChecksumLenRecv¶

Type:

Preference¶

Default:

Require¶

This property specifies the application's need for protection against corruption for all data received on this Connection. Disabling this property could enable later control of the required minimum receiver checksum coverage (see Section 7.1.1).¶

5.2.9. Congestion control

Name:

congestionControl¶

Type:

Preference¶

Default:

Require¶

This property specifies whether the application would like the Connection to be congestion controlled or not. Note that if a Connection is not congestion controlled, an application using such a Connection SHOULD itself perform congestion control in accordance with [RFC2914] or use a circuit breaker in accordance with [RFC8084], whichever is appropriate. Also note that reliability is usually combined with congestion control in protocol implementations, rendering "reliable but not congestion controlled" a request that is unlikely to succeed. If the Connection is congestion controlled, performing additional congestion control in the application can have negative performance implications.¶

5.2.10. Keep alive

Name:

keepAlive¶

Type:

Preference¶

Default:

Ignore¶

This property specifies whether the application would like the Connection to send keep-alive packets or not. Note that if a Connection determines that keep-alive packets are being sent, the applicaton should itself avoid generating additional keep alive messages. Note that when supported, the system will use the default period for generation of the keep alive-packets. (See also Section 7.1.4).¶

5.2.11. Interface Instance or Type

Name:

interface¶

Type:

Collection of (Preference, Enumeration)¶

Default:

Empty (not setting a preference for any interface)¶

This property allows the application to select any specific network interfaces or categories of interfaces it wants to Require, Prohibit, Prefer, or Avoid. Note that marking a specific interface as Require strictly limits path selection to that single interface, and often leads to less flexible and resilient connection establishment.¶

In contrast to other Selection Properties, this property is a tuple of an (Enumerated) interface identifier and a preference, and can either be implemented directly as such, or for making one preference available for each interface and interface type available on the system.¶

The set of valid interface types is implementation- and system-specific. For example, on a mobile device, there may be Wi-Fi and Cellular interface types available; whereas on a desktop computer, Wi-Fi and Wired Ethernet interface types might be available. An implementation should provide all types that are supported on the local system to all remote systems, to allow applications to be written generically. For example, if a single implementation is used on both mobile devices and desktop devices, it should define the Cellular interface type for both systems, since an application might wish to always prohibit cellular.¶

The set of interface types is expected to change over time as new access technologies become available. The taxonomy of interface types on a given Transport Services system is implementation-specific.¶

Interface types should not be treated as a proxy for properties of interfaces such as metered or unmetered network access. If an application needs to prohibit metered interfaces, this should be specified via Provisioning Domain attributes (see Section 5.2.12) or another specific property.¶

5.2.12. Provisioning Domain Instance or Type

Name:

pvd¶

Type:

Collection of (Preference, Enumeration)¶

Default:

Empty (not setting a preference for any PvD)¶

Similar to interface instances and types (see Section 5.2.11), this property allows the application to control path selection by selecting which specific Provisioning Domain (PvD) or categories of PVDs it wants to Require, Prohibit, Prefer, or Avoid. Provisioning Domains define consistent sets of network properties that may be more specific than network interfaces [RFC7556].¶

As with interface instances and types, this property is a tuple of an (Enumerated) PvD identifier and a preference, and can either be implemented directly as such, or for making one preference available for each interface and interface type available on the system.¶

The identification of a specific PvD is implementation- and system-specific, because there is currently no portable standard format for a PvD identifier. For example, this identifier might be a string name or an integer. As with requiring specific interfaces, requiring a specific PvD strictly limits the path selection.¶

Categories or types of PvDs are also defined to be implementation- and system-specific. These can be useful to identify a service that is provided by a PvD. For example, if an application wants to use a PvD that provides a Voice-Over-IP service on a Cellular network, it can use the relevant PvD type to require a PvD that provides this service, without needing to look up a particular instance. While this does restrict path selection, it is broader than requiring specific PvD instances or interface instances, and should be preferred over these options.¶

5.2.13. Use Temporary Local Address

Name:

useTemporaryLocalAddress¶

Type:

Preference¶

Default:

Avoid for Listeners and Rendezvous Connections. Prefer for other Connections.¶

This property allows the application to express a preference for the use of temporary local addresses, sometimes called "privacy" addresses [RFC4941]. Temporary addresses are generally used to prevent linking connections over time when a stable address, sometimes called "permanent" address, is not needed. There are some caveats to note when specifying this property. First, if an application Requires the use of temporary addresses, the resulting Connection cannot use IPv4, because temporary addresses do not exist in IPv4. Second, temporary local addresses might involve trading off privacy for performance. For instance, temporary addresses can interfere with resumption mechanisms that some protocols rely on to reduce initial latency.¶

5.2.14. Multi-Paths Transport

Name:

multipath¶

Type:

Enumeration¶

Default:

Disabled for connections created through initiate and rendezvous, Passive for listeners¶

This property specifies whether and how applications want to take advantage of transferring data across multiple paths between the same end hosts. Using multiple paths allows connections to migrate between interfaces or aggregate bandwidth as availability and performance properties change. Possible values are:¶

Disabled:

The connection will not use multiple paths once established, even if the chosen transport supports using multiple paths.¶

Active:

The connection will negotiate the use of multiple paths if the chosen transport supports this.¶

Passive:

The connection will support the use of multiple paths if the remote endpoint requests it.¶

The policy for using multiple paths is specified using the separate multipath-policy property, see Section 7.1.7 below. To enable the peer endpoint to initiate additional paths towards a local address other than the one initially used, it is necessary to set the Alternative Addresses property (see Section 5.2.15 below).¶

Setting this property to "Active", can have privacy implications: It enables the transport to establish connectivity using alternate paths that might result in users being linkable across the multiple paths, even if the Advertisement of Alternative Addresses property (see Section 5.2.15 below) is set to false.¶

Enumeration values other than "Disabled" are interpreted as a preference for choosing protocols that can make use of multiple paths. The "Disabled" value implies a requirement not to use multiple paths in parallel but does not prevent choosing a protocol that is capable of using multiple paths, e.g., it does not prevent choosing TCP, but prevents sending the MP_CAPABLE option in the TCP handshake.¶

5.2.15. Advertisement of Alternative Addresses

Name:

advertises-altaddr¶

Type:

Boolean¶

Default:

False¶

This property specifies whether alternative addresses, e.g., of other interfaces, should be advertised to the peer endpoint by the protocol stack. Advertising these addresses enables the peer-endpoint to establish additional connectivity, e.g., for connection migration or using multiple paths.¶

Note that this can have privacy implications because it might result in users being linkable across the multiple paths. Also, note that setting this to false does not prevent the local transport system from establishing connectivity using alternate paths (see Section 5.2.14 above); it only prevents proactive advertisement of addresses.¶

5.2.16. Direction of communication

Name:

direction¶

Type:

Enumeration¶

Default:

Bidirectional¶

This property specifies whether an application wants to use the connection for sending and/or receiving data. Possible values are:¶

Bidirectional:

The connection must support sending and receiving data¶

Unidirectional send:

The connection must support sending data, and the application cannot use the connection to receive any data¶

Unidirectional receive:

The connection must support receiving data, and the application cannot use the connection to send any data¶

Since unidirectional communication can be supported by transports offering bidirectional communication, specifying unidirectional communication may cause a transport stack that supports bidirectional communication to be selected.¶

5.2.17. Notification of ICMP soft error message arrival

Name:

softErrorNotify¶

Type:

Preference¶

Default:

Ignore¶

This property specifies whether an application considers it useful to be informed when an ICMP error message arrives that does not force termination of a connection. When set to true, received ICMP errors are available as SoftErrors, see Section 7.3.1. Note that even if a protocol supporting this property is selected, not all ICMP errors will necessarily be delivered, so applications cannot rely upon receiving them [RFC8085].¶

5.2.18. Initiating side is not the first to write

Name:

activeReadBeforeSend¶

Type:

Preference¶

Default:

Ignore¶

The most common client-server communication pattern involves the client actively opening a connection, then sending data to the server. The server listens (passive open), reads, and then answers. This property specifies whether an application wants to diverge from this pattern - either by actively opening with Initiate(), immediately followed by reading, or passively opening with Listen(), immediately followed by writing. This property is ignored when establishing connections using Rendezvous(). Requiring this property limits the choice of mappings to underlying protocols, which can reduce efficiency. For example, it prevents the transport system from mapping Connections to SCTP streams, where the first transmitted data takes the role of an active open signal [I-D.ietf-taps-impl].¶

5.3.1. Pre-Connection Parameters

Common parameters such as TLS ciphersuites are known to implementations. Clients should use common safe defaults for these values whenever possible. However, as discussed in [RFC8922], many transport security protocols require specific security parameters and constraints from the client at the time of configuration and actively during a handshake. These configuration parameters need to be specified in the pre-connection phase and are created as follows:¶

SecurityParameters := NewSecurityParameters()

Security configuration parameters and sample usage follow:¶

• Local identity and private keys: Used to perform private key operations and prove one's identity to the Remote Endpoint. (Note, if private keys are not available, e.g., since they are stored in hardware security modules (HSMs), handshake callbacks must be used. See below for details.)¶

SecurityParameters.Set('identity', identity)
SecurityParameters.Set('keypair', privateKey, publicKey)

• Supported algorithms: Used to restrict what parameters are used by underlying transport security protocols. When not specified, these algorithms should use known and safe defaults for the system. Parameters include: ciphersuites, supported groups, and signature algorithms. These parameters take a collection of supported algorithms as parameter.¶

SecurityParameters.Set('supported-group', 'secp256k1')
SecurityParameters.Set('ciphersuite, 'TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256')
SecurityParameters.Set('signature-algorithm', 'ed25519')

• Pre-Shared Key import: Used to install pre-shared keying material established out-of-band. Each pre-shared keying material is associated with some identity that typically identifies its use or has some protocol-specific meaning to the Remote Endpoint.¶

SecurityParameters.Set('pre-shared-key', key, identity)

• Session cache management: Used to tune session cache capacity, lifetime, and other policies.¶

SecurityParameters.Set('max-cached-sessions', 16)
SecurityParameters.Set('cached-session-lifetime-seconds', 3600)

5.3.2. Connection Establishment Callbacks

Security decisions, especially pertaining to trust, are not static. Once configured, parameters may also be supplied during connection establishment. These are best handled as client-provided callbacks. Security handshake callbacks that may be invoked during connection establishment include:¶

• Trust verification callback: Invoked when a Remote Endpoint's trust must be validated before the handshake protocol can continue.¶

TrustCallback := NewCallback({
  // Handle trust, return the result
})
SecurityParameters.SetTrustVerificationCallback(trustCallback)

• Identity challenge callback: Invoked when a private key operation is required, e.g., when local authentication is requested by a remote.¶

ChallengeCallback := NewCallback({
  // Handle challenge
})
SecurityParameters.SetIdentityChallengeCallback(challengeCallback)

7.1.1. Required Minimum Corruption Protection Coverage for Receiving

Name:

recvChecksumLen¶

Type:

Integer, with special value Full Coverage¶

Default:

Full Coverage¶

This property specifies the minimum number of bytes in a received message that need to be covered by a checksum. A special value of 0 means that no checksum is permitted. A receiving Endpoint will not forward messages to the application that have less coverage. The application is responsible for handling any corruption within the non-protected part of the message [RFC8085].¶

7.1.2. Connection Priority

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. No guarantees of a specific behavior regarding Connection Priority are given; a transport system may ignore this property. See Section 8.2.6 for more details.¶

7.1.3. Timeout for Aborting Connection

Name:

connTimeout¶

Type:

Numeric, with special value Disabled¶

Default:

Disabled¶

This property specifies how long to wait before deciding that an active Connection has failed when trying to reliably deliver data to the Remote Endpoint. 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.¶

7.1.4. Timeout for keep alive packets

Name:

keepaliveTimeout¶

Type:

Numeric, with special value Default¶

Default:

Default¶

A transport system can request a protocol that supports sending keep alive packets Section 5.2.10. This property specifies the maximum time an idle connection (one for which no transport packets have been sent) should wait before the Local Endpoint sends a keep-alive packet to the Remote Endpoint. Adjusting this Property will only take effect when the underlying stack supports sending keep-alive packets. Guidance on setting this value for datagram transports is provided in [RFC8085]. The special value Default means that this timeout will use the default for the selected transport. A value greater than the connection timeout (Section 7.1.3) will disable the sending of keep-alive packets.¶

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 markings on the wire for Protocol Stacks supporting this. 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] Per Hop Behaviour (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 might fail if the desired rate cannot be maintained across the Path. A transport can 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 for transferring data across multiple paths between the same end hosts if Parallel Use of Multiple Paths is not set to Disabled (see Section 5.2.14). Possible values are:¶

Handover:

The connection ought only to attempt to migrate between different paths when the original path is lost or becomes unusable. The thresholds used to declare a path unusable are implementation specific.¶

Interactive:

The connection ought only to attempt to minimize the latency for interactive traffic patterns by transmitting data across multiple paths when this is beneficial. The goal of minimizing the latency will be balanced against the cost of each of these paths. Depending on the cost of the lower-latency path, the scheduling might choose to use a higher-latency path. Traffic can be scheduled such that data may be transmitted on multiple paths in parallel to achieve a lower latency. The specific scheduling algorithm is implementation-specific.¶

Aggregate:

The connection ought to attempt to use multiple paths in parallel to maximize available capacity and possibly overcome the capacity limitations of the individual paths. The actual strategy is implementation specific.¶

Note that this is a local choice - the Remote Endpoint can choose a different policy.¶

7.1.8. Bounds on Send or Receive Rate

Name:

minSendRate / minRecvRate / maxSendRate / maxRecvRate¶

Type:

Numeric (with special value Unlimited) / Numeric (with special value Unlimited) / Numeric (with special value Unlimited) / Numeric (with special value Unlimited)¶

Default:

Unlimited / Unlimited / 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 it will be useful. These are specified in bits per second. The special value Unlimited indicates that no bound is specified.¶

7.1.9. Group Connection Limit

Name:

groupConnLimit¶

Type:

Numeric (with special value Unlimited)¶

Default:

Unlimited¶

This property controls the number of Connections that can be accepted from a peer as new members of the Connection's group. Similar to SetNewConnectionLimit(), this limits the number of ConnectionReceived Events that will occur, but constrained to the group of the Connection associated with this property. For a multi-streaming transport, this limits the number of allowed streams.¶

7.1.10. Read-only Connection Properties

The following generic Connection Properties are read-only, i.e. they cannot be changed by an application.¶

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.3) value.¶

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.3) 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.3) is used.¶

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. Path change

This event notifies the application when at least one of the paths underlying a Connection has changed. Changes occur on a single path when the PMTU changes as well as when multiple paths are used and paths are added or removed, or a handover has been performed.¶

Connection -> PathChange<>

8.1.1. Message Contexts

Using the MessageContext object, the application can set and retrieve meta-data of the message, including Message Properties (see Section 8.1.3) and framing meta-data (see Section 8.1.2.2). Therefore, a MessageContext object can be passed to the Send action and is returned by each Send and Receive related event.¶

Message Properties can be set and queried using the Message Context:¶

MessageContext.add(scope?, parameter, value)
PropertyValue := MessageContext.get(scope?, property)

To get or set Message Properties, the optional scope parameter is 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.¶

For MessageContexts returned by send Events (see Section 8.2.2) and receive Events (see Section 8.3.2), the application can query information about the local and Remote Endpoint:¶

RemoteEndpoint := MessageContext.GetRemoteEndpoint()
LocalEndpoint := MessageContext.GetLocalEndpoint()

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 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 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].¶

framer := NewHTTPMessageFramer()
Preconnection.AddFramer(framer)

messageContext := NewMessageContext()
messageContext.add(framer, key, value)
Connection.Send(messageData, messageContext)

messageContext.get(framer, key) -> value

httpFramer := NewHTTPMessageFramer()
...
messageContext := NewMessageContext()
messageContext.add(httpFramer, "accept", "text/html")

8.1.3. Message Properties

Applications needing to annotate the Messages they send with extra information (for example, to control how data is scheduled and processed by the transport protocols supporting the Connection) can include this information in the Message Context passed to the Send Action. For other uses of the message context, see Section 8.1.1.¶

Message Properties are per-Message, not per-Send if partial Messages are sent (Section 8.2.3). All data blocks associated with a single Message share properties specified in the Message Contexts. For example, it would not make sense to have the beginning of a Message expire, but allow the end of a Message to still be sent.¶

A MessageContext object contains metadata for the Messages to be sent or received.¶

messageData := "hello"
messageContext := NewMessageContext()
messageContext.add(parameter, value)
Connection.Send(messageData, messageContext)

The simpler form of Send, which does not take any messageContext, is equivalent to passing a default MessageContext without adding any Message Properties.¶

If an application wants to override Message Properties for a specific message, it can acquire an empty MessageContext Object and add all desired Message Properties to that Object. It can then reuse the same messageContext Object for sending multiple Messages with the same properties.¶

Properties can be added to a MessageContext object only before the context is used for sending. Once a messageContext has been used with a Send call, it is invalid to modify any of its properties.¶

The Message Properties could be inconsistent with the properties of the Protocol Stacks underlying the Connection on which a given Message is sent. For example, a Protocol Stack must be able to provide ordering if the msgOrdered property of a Message is enabled. Sending a Message with Message Properties inconsistent with the Selection Properties of the Connection yields an error.¶

Connection Properties describe the default behavior for all Messages on a Connection. If a Message Property contradicts a Connection Property, and if this per-Message behavior can be supported, it overrides the Connection Property for the specific Message. For example, if Reliable Data Transfer (Connection) is set to Require and a protocol with configurable per-Message reliability is used, setting Reliable Data Transfer (Message) to false for a particular Message will allow this Message to be unreliably delivered. Changing the Reliable Data Transfer property on Messages is only possible for Connections that were established enabling the Selection Property Configure Per-Message Reliability.¶

The following Message Properties are supported:¶

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.10.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.2.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. 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.3), 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.¶

Connection -> Sent<messageContext>

Connection -> Expired<messageContext>

Connection -> SendError<messageContext, reason?>

8.2.3. Partial Sends

It is not always possible for an application to send all 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, or the length of the Message may be unknown or unbounded.¶

Partial Message sending is supported by passing an endOfMessage boolean parameter to the Send Action. This value is always true by default, and the simpler forms of Send are equivalent to passing true for endOfMessage.¶

The following example sends a Message in two separate calls to Send.¶

messageContext := NewMessageContext()
messageContext.add(parameter, value)

messageData := "hel"
endOfMessage := false
Connection.Send(messageData, messageContext, endOfMessage)

messageData := "lo"
endOfMessage := true
Connection.Send(messageData, messageContext, endOfMessage)

All data sent with the same MessageContext object will be treated as belonging to the same Message, and will constitute an in-order series until the endOfMessage is marked.¶

8.2.4. Batching Sends

To reduce the overhead of sending multiple small Messages on a Connection, the application could batch several Send Actions together. This provides a hint to the system that the sending of these Messages ought to be coalesced when possible, and that sending any of the batched Messages can be delayed until the last Message in the batch is enqueued.¶

The semantics for starting and ending a batch can be implementation-specific, but need to allow multiple Send Actions to be enqueued.¶

Connection.StartBatch()
Connection.Send(messageData)
Connection.Send(messageData)
Connection.EndBatch()

8.2.5. Send on Active Open: InitiateWithSend

For application-layer protocols where the Connection initiator also sends the first message, the InitiateWithSend() action combines Connection initiation with a first Message sent:¶

Connection := Preconnection.InitiateWithSend(messageData, messageContext?, timeout?)

Whenever possible, a messageContext should be provided to declare the Message passed to InitiateWithSend as Safely Replayable. This allows the transport system to make use of 0-RTT establishment in case this is supported by the available protocol stacks. When the selected stack(s) do not support transmitting data upon connection establishment, InitiateWithSend is identical to Initiate() followed by Send().¶

Neither partial sends nor send batching are supported by InitiateWithSend().¶

The Events that may be sent after InitiateWithSend() are equivalent to those that would be sent by an invocation of Initiate() followed immediately by an invocation of Send(), with the caveat that a send failure that occurs because the Connection could not be established will not result in a SendError separate from the InitiateError signaling the failure of Connection establishment.¶

8.2.6. Priority in TAPS

The Transport Services interface provides two properties to allow a sender to signal the relative priority of data transmission: the Priority Message Property Section 8.1.3.2, and the Connection Priority Connection Property Section 7.1.2. These properties are designed to allow the expression and implementation of a wide variety of approaches to transmission priority in the transport and application layer, including those which do not appear on the wire (affecting only sender-side transmission scheduling) as well as those that do (e.g. [I-D.ietf-httpbis-priority].¶

A Transport Services system gives no guarantees about how its expression of relative priorities will be realized; for example, if a transport stack that only provides a single in-order reliable stream is selected, prioritization information can only be ignored. However, the Transport Services system will seek to ensure that performance of relatively-prioritized connections and messages is not worse with respect to those connections and messages than an equivalent configuration in which all prioritization properties are left at their defaults.¶

The Transport Services interface does order Connection Priority over the Priority Message Property. In the absense of other externalities (e.g., transport-layer flow control), a priority 1 Message on a priority 0 Connection will be sent before a priority 0 Message on a priority 1 Connection in the same group.¶

8.3.1. Enqueuing Receives

Receive takes two parameters to specify the length of data that an application is willing to receive, both of which are optional and have default values if not specified.¶

Connection.Receive(minIncompleteLength?, maxLength?)

By default, Receive will try to deliver complete Messages in a single event (Section 8.3.2.1).¶

The application can set a minIncompleteLength value to indicate the smallest partial Message data size in bytes that should be delivered in response to this Receive. By default, this value is infinite, which means that only complete Messages should be delivered (see 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 associated receive event will be triggered only when at least that many bytes are available, or the Message is complete with fewer bytes, or the system needs to free up memory. Applications should 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 of shorter complete Messages or memory issues.¶

The maxLength argument indicates the maximum size of a Message in bytes that the application is currently prepared to receive. The default value for maxLength is infinite. If an incoming Message is larger than the minimum of this size and the maximum Message size on receive for the Connection's Protocol Stack, it will be delivered via ReceivedPartial events (Section 8.3.2.2).¶

Note that maxLength does not guarantee that the application will receive that many bytes if they are available; the interface could return ReceivedPartial events with less data than maxLength according to implementation constraints. Note also that maxLength and minIncompleteLength are intended only to manage buffering, and are not interpreted as a receiver preference for message reordering.¶

8.3.2. Receive Events

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 provide backpressure to the transport stack when it is temporarily not ready to receive messages.¶

The interface should allow the application to correlate which call to Receive resulted in a particular Receive Event. The manner in which this correlation is indicated is implementation-specific.¶

Connection -> Received<messageData, messageContext>

Connection -> ReceivedPartial<messageData, messageContext, endOfMessage>

Connection -> ReceiveError<messageContext, reason?>

8.3.3. Receive Message Properties

Each Message Context may contain metadata from protocols in the Protocol Stack; which metadata is available is Protocol Stack dependent. These are exposed though additional read-only Message Properties that can be queried from the MessageContext object (see Section 8.1.1) passed by the receive event. The following metadata values are supported:¶

A.2.1. reliable-inorder-stream

This profile provides reliable, in-order transport service with congestion control. TCP is an example of a protocol that provides this service. It should consist of the following properties:¶

A.2.2. reliable-message

This profile provides message-preserving, reliable, in-order transport service with congestion control. SCTP is an example of a protocol that provides this service. It should consist of the following properties:¶

A.2.3. unreliable-datagram

This profile provides unreliable datagram transport service. An example of a protocol that provides this service is UDP. It consists of the following properties:¶

Applications that choose this Transport Property Profile for latency reasons should also consider setting an appropriate Capacity Profile Property, see Section 7.1.6 and could benefit from controlling checksum coverage, see Section 5.2.7 and Section 5.2.8.¶