rfc9622v5.txt   rfc9622.txt 
skipping to change at line 371 skipping to change at line 371
transport Protocol Stack on which data can be sent to and/or received transport Protocol Stack on which data can be sent to and/or received
from a Remote Endpoint (i.e., a logical connection that, depending on from a Remote Endpoint (i.e., a logical connection that, depending on
the kind of transport, can be bidirectional or unidirectional, and the kind of transport, can be bidirectional or unidirectional, and
that can use a stream protocol or a datagram protocol). Connections that can use a stream protocol or a datagram protocol). Connections
are presented consistently to the application, irrespective of are presented consistently to the application, irrespective of
whether the underlying transport is connectionless or connection whether the underlying transport is connectionless or connection
oriented. Connections can be created from Preconnections in three oriented. Connections can be created from Preconnections in three
ways: ways:
* initiating the Preconnection (i.e., creating a Connection from the * initiating the Preconnection (i.e., creating a Connection from the
Preconnection, actively opening, as in a client; see Initiate() in Preconnection, actively opening, as in a client; see Initiate in
Section 7.1), Section 7.1),
* listening on the Preconnection (i.e., creating a Listener based on * listening on the Preconnection (i.e., creating a Listener based on
the Preconnection, passively opening, as in a server; see Listen() the Preconnection, passively opening, as in a server; see Listen
in Section 7.2), or in Section 7.2), or
* a rendezvous for the Preconnection (i.e., peer-to-peer connection * a rendezvous for the Preconnection (i.e., peer-to-peer connection
establishment; see Rendezvous() in Section 7.3). establishment; see Rendezvous in Section 7.3).
Once a Connection is established, data can be sent and received on it Once a Connection is established, data can be sent and received on it
in the form of Messages. The API supports the preservation of in the form of Messages. The API supports the preservation of
message boundaries via both explicit Protocol Stack support and message boundaries via both explicit Protocol Stack support and
application support through a Message Framer that finds message application support through a Message Framer that 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
can have implementation-specific default handlers. can have implementation-specific default handlers.
skipping to change at line 736 skipping to change at line 736
recommendations: recommendations:
* Actions, events, and errors in implementations of the Transport * Actions, events, and errors in implementations of the Transport
Services API SHOULD use the names assigned to them in this Services API SHOULD use the names assigned to them in this
document, subject to capitalization, punctuation, and other document, subject to capitalization, punctuation, and other
typographic conventions in the language of the implementation, typographic conventions in the language of the implementation,
unless the implementation itself uses different names for unless the implementation itself uses different names for
substantially equivalent objects for networking by convention. substantially equivalent objects for networking by convention.
* Transport Services systems SHOULD implement each Selection * Transport Services systems SHOULD implement each Selection
Property, Connection Property, and Message Context Property Property, Connection Property, and MessageContext Property
specified in this document. These features SHOULD be implemented specified in this document. These features SHOULD be implemented
even when, in a specific implementation, it will always result in even when, in a specific implementation, it will always result in
no operation, e.g., there is no action when the API specifies a no operation, e.g., there is no action when the API specifies a
Property that is not available in a transport protocol implemented Property that is not available in a transport protocol implemented
on a specific platform. For example, if TCP is the only on a specific platform. For example, if TCP is the only
underlying transport protocol, the Message Property msgOrdered can underlying transport protocol, the Message Property msgOrdered can
be implemented (trivially, as a no-op) as disabling the be implemented (trivially, as a no-op) as disabling the
requirement for ordering will not have any effect on delivery requirement for ordering will not have any effect on delivery
order for Connections over TCP. Similarly, the msgLifetime order for Connections over TCP. Similarly, the msgLifetime
Message Property can be implemented but ignored, as the Message Property can be implemented but ignored, as the
skipping to change at line 935 skipping to change at line 935
RemoteSpecifier.WithHopLimit(HopLimit) RemoteSpecifier.WithHopLimit(HopLimit)
Calling Listen on a Preconnection with a multicast group address Calling Listen on a Preconnection with a multicast group address
specified as the Remote Endpoint Identifier will trigger the specified as the Remote Endpoint Identifier will trigger the
Transport Services Implementation to join the multicast group to Transport Services Implementation to join the multicast group to
receive Messages. This Listener will create one Connection for each receive Messages. This Listener will create one Connection for each
Remote Endpoint sending to the group, with the Local Endpoint Remote Endpoint sending to the group, with the Local Endpoint
Identifier specified as a group address. The set of Connection Identifier specified as a group address. The set of Connection
objects created forms a Connection Group. The receiving interface objects created forms a Connection Group. The receiving interface
can be restricted by passing it as part of the LocalSpecifier or can be restricted by passing it as part of the LocalSpecifier or
queried through the Message Context on the Messages received (see queried through the MessageContext on the Messages received (see
Section 9.1.1 for further details). Section 9.1.1 for further details).
Specifying WithHopLimit sets the Time To Live (TTL) field in the Specifying WithHopLimit sets the Time To Live (TTL) field in the
header of IPv4 packets or the Hop Count field in the header of IPv6 header of IPv4 packets or the Hop Count field in the header of IPv6
packets. packets.
The following API calls can be used to configure a Preconnection The following API calls can be used to configure a Preconnection
before calling Listen: before calling Listen:
LocalSpecifier.WithSingleSourceMulticastGroupIP(GroupAddress, LocalSpecifier.WithSingleSourceMulticastGroupIP(GroupAddress,
skipping to change at line 1035 skipping to change at line 1035
QUICRemoteSpecifier.WithHostName("example.com") QUICRemoteSpecifier.WithHostName("example.com")
QUICRemoteSpecifier.WithPort(8443) QUICRemoteSpecifier.WithPort(8443)
QUICRemoteSpecifier.WithProtocol(QUIC) QUICRemoteSpecifier.WithProtocol(QUIC)
RemoteSpecifiers := [ RemoteSpecifier, QUICRemoteSpecifier ] RemoteSpecifiers := [ RemoteSpecifier, QUICRemoteSpecifier ]
6.1.4. Endpoint Examples 6.1.4. Endpoint Examples
The following examples of Endpoints show common usage patterns. The following examples of Endpoints show common usage patterns.
Specify a Remote Endpoint using a hostname "example.com" and a Specify a Remote Endpoint using a hostname example.com and a service
service name "https", which tells the system to use the default port name https, which tells the system to use the default port for HTTPS
for HTTPS (443): (443):
RemoteSpecifier := NewRemoteEndpoint() RemoteSpecifier := NewRemoteEndpoint()
RemoteSpecifier.WithHostName("example.com") RemoteSpecifier.WithHostName("example.com")
RemoteSpecifier.WithService("https") RemoteSpecifier.WithService("https")
Specify a Remote Endpoint using an IPv6 address and remote port: Specify a Remote Endpoint using an IPv6 address and remote port:
RemoteSpecifier := NewRemoteEndpoint() RemoteSpecifier := NewRemoteEndpoint()
RemoteSpecifier.WithIPAddress(2001:db8:4920:e29d:a420:7461:7073:a) RemoteSpecifier.WithIPAddress(2001:db8:4920:e29d:a420:7461:7073:a)
RemoteSpecifier.WithPort(443) RemoteSpecifier.WithPort(443)
skipping to change at line 1069 skipping to change at line 1069
LocalSpecifier.WithInterface("en0") LocalSpecifier.WithInterface("en0")
Specify a Local Endpoint using a local interface name and local port: Specify a Local Endpoint using a local interface name and local port:
LocalSpecifier := NewLocalEndpoint() LocalSpecifier := NewLocalEndpoint()
LocalSpecifier.WithInterface("en0") LocalSpecifier.WithInterface("en0")
LocalSpecifier.WithPort(443) LocalSpecifier.WithPort(443)
As an alternative to specifying an interface name for the Local As an alternative to specifying an interface name for the Local
Endpoint, an application can express more fine-grained preferences Endpoint, an application can express more fine-grained preferences
using the Interface Instance or Type Selection Property; see using the interface Selection Property; see Section 6.2.11. However,
Section 6.2.11. However, if the application specifies Selection if the application specifies Selection Properties that are
Properties that are inconsistent with the Local Endpoint, this will inconsistent with the Local Endpoint, this will result in an error
result in an error once the application attempts to open a once the application attempts to open a Connection.
Connection.
Specify a Local Endpoint using a STUN server: Specify a Local Endpoint using a STUN server:
LocalSpecifier := NewLocalEndpoint() LocalSpecifier := NewLocalEndpoint()
LocalSpecifier.WithStunServer(address, port, credentials) LocalSpecifier.WithStunServer(address, port, credentials)
6.1.5. Multicast Examples 6.1.5. Multicast Examples
The following examples show how multicast groups can be used. The following examples show how multicast groups can be used.
skipping to change at line 1502 skipping to change at line 1501
Default: Empty (not setting a preference for any PvD) Default: Empty (not setting a preference for any PvD)
Similar to interface (see Section 6.2.11), this property allows the Similar to interface (see Section 6.2.11), this property allows the
application to control path selection by selecting which specific PvD application to control path selection by selecting which specific PvD
or categories of PvDs it wants to Require, Prohibit, Prefer, or or categories of PvDs it wants to Require, Prohibit, Prefer, or
Avoid. Provisioning Domains define consistent sets of network Avoid. Provisioning Domains define consistent sets of network
properties that might be more specific than network interfaces properties that might be more specific than network interfaces
[RFC7556]. [RFC7556].
As with interface instances and types, this property is a set of As with interface, this property is a set of tuples of (Enumerated)
tuples of (Enumerated) PvD identifier and preference. It can either PvD identifier and preference. It can either be implemented directly
be implemented directly as such or be implemented to make one as such or be implemented to make one preference available for each
preference available for each interface and interface type available interface and interface type available on the system.
on the system.
The identification of a specific PvD is specific to the The identification of a specific PvD is specific to the
implementation or system. [RFC8801] defines how to use an FQDN to implementation or system. [RFC8801] defines how to use an FQDN to
identify a PvD when advertised by a network, but systems might also identify a PvD when advertised by a network, but systems might also
use other locally relevant identifiers such as string names or use other locally relevant identifiers such as string names or
Integers to identify PvDs. As with requiring specific interfaces, Integers to identify PvDs. As with requiring specific interfaces,
requiring a specific PvD strictly limits the path selection. requiring a specific PvD strictly limits the path selection.
Categories or types of PvDs are also defined to be specific to the Categories or types of PvDs are also defined to be specific to the
implementation or system. These can be useful to identify a service implementation or system. These can be useful to identify a service
skipping to change at line 1540 skipping to change at line 1538
Default: Avoid for Listeners and Rendezvous Connections; Prefer for Default: Avoid for Listeners and Rendezvous Connections; Prefer for
other Connections other Connections
This property allows the application to express a preference for the This property allows the application to express a preference for the
use of temporary local addresses, sometimes called "privacy" use of temporary local addresses, sometimes called "privacy"
addresses [RFC8981]. Temporary addresses are generally used to addresses [RFC8981]. Temporary addresses are generally used to
prevent linking connections over time when a stable address, prevent linking connections over time when a stable address,
sometimes called a "permanent" address, is not needed. There are sometimes called a "permanent" address, is not needed. There are
some caveats to note when specifying this property. First, if an some caveats to note when specifying this property. First, if an
application Requires the use of temporary addresses, the resulting application requires the use of temporary addresses, the resulting
Connection cannot use IPv4 because temporary addresses do not exist Connection cannot use IPv4 because temporary addresses do not exist
in IPv4. Second, temporary local addresses might involve trading off in IPv4. Second, temporary local addresses might involve trading off
privacy for performance. For instance, temporary addresses (e.g., privacy for performance. For instance, temporary addresses (e.g.,
[RFC8981]) can interfere with resumption mechanisms that some [RFC8981]) can interfere with resumption mechanisms that some
protocols rely on to reduce initial latency. protocols rely on to reduce initial latency.
6.2.14. Multipath Transport 6.2.14. Multipath Transport
Name: multipath Name: multipath
skipping to change at line 1585 skipping to change at line 1583
than the one initially used, it is necessary to set the than the one initially used, it is necessary to set the
advertisesAltaddr property (see Section 6.2.15). advertisesAltaddr property (see Section 6.2.15).
Setting this property to Active can have privacy implications. It Setting this property to Active can have privacy implications. It
enables the transport to establish connectivity using alternate paths enables the transport to establish connectivity using alternate paths
that might result in users being linkable across the multiple paths, that might result in users being linkable across the multiple paths,
even if the advertisesAltaddr property (see Section 6.2.15) is set to even if the advertisesAltaddr property (see Section 6.2.15) is set to
false. false.
Note that Multipath Transport has no corresponding Selection Property Note that Multipath Transport has no corresponding Selection Property
of type Preference. Enumeration values other than Disabled are of type "Preference". Enumeration values other than Disabled are
interpreted as a preference for choosing protocols that can make use interpreted as a preference for choosing protocols that can make use
of multiple paths. The Disabled value implies a requirement not to of multiple paths. The Disabled value implies a requirement not to
use multiple paths in parallel but does not prevent choosing a use multiple paths in parallel but does not prevent choosing a
protocol that is capable of using multiple paths, e.g., it does not protocol that is capable of using multiple paths, e.g., it does not
prevent choosing TCP but prevents sending the MP_CAPABLE option in prevent choosing TCP but prevents sending the MP_CAPABLE option in
the TCP handshake. the TCP handshake.
6.2.15. Advertisement of Alternative Addresses 6.2.15. Advertisement of Alternative Addresses
Name: advertisesAltaddr Name: advertisesAltaddr
skipping to change at line 1707 skipping to change at line 1705
secure connection (e.g., serverCertificate or clientCertificate). secure connection (e.g., serverCertificate or clientCertificate).
Specifying security parameters from enumerated values (e.g., specific Specifying security parameters from enumerated values (e.g., specific
ciphersuites) might constrain which transport protocols can be ciphersuites) might constrain which transport protocols can be
selected during Connection establishment. selected during Connection establishment.
Security configuration parameters are specified in the Security configuration parameters are specified in the
preestablishment phase and are created as follows: preestablishment phase and are created as follows:
SecurityParameters := NewSecurityParameters() SecurityParameters := NewSecurityParameters()
Specific parameters are added using a call to Set() on the Specific parameters are added using a call to Set on the
SecurityParameters. SecurityParameters.
As with the rest of the Transport Services API, the exact names of As with the rest of the Transport Services API, the exact names of
parameters and/or values of enumerations (e.g., ciphersuites) used in parameters and/or values of enumerations (e.g., ciphersuites) used in
the security parameters are specific to the system or implementation the security parameters are specific to the system or implementation
and ought to be chosen to follow the principle of least surprise for and ought to be chosen to follow the principle of least surprise for
users of the platform/language environment in question. users of the platform/language environment in question.
For security parameters that are enumerations of known values, such For security parameters that are enumerations of known values, such
as TLS ciphersuites, implementations are responsible for exposing the as TLS ciphersuites, implementations are responsible for exposing the
skipping to change at line 2232 skipping to change at line 2230
Connection Group using the same approach as that used in Connection Group using the same approach as that used in
Section 9.1.3.2: when allocating available network capacity among Section 9.1.3.2: when allocating available network capacity among
Connections in a Connection Group, sends on Connections with Connections in a Connection Group, sends on Connections with
numerically lower Priority values will be prioritized over sends on numerically lower Priority values will be prioritized over sends on
Connections that have numerically higher Priority values. Capacity Connections that have numerically higher Priority values. Capacity
will be shared among these Connections according to the connScheduler will be shared among these Connections according to the connScheduler
property (Section 8.1.5). See Section 9.2.6 for more details. property (Section 8.1.5). See Section 9.2.6 for more details.
7.5. Adding and Removing Endpoints on a Connection 7.5. Adding and Removing Endpoints on a Connection
Transport protocols that are explicitly multipath aware are expected Transport protocols that are explicitly multipath-aware are expected
to automatically manage the set of Remote Endpoints that they are to automatically manage the set of Remote Endpoints that they are
communicating with and the paths to those endpoints. A PathChange communicating with and the paths to those endpoints. A PathChange
event, described in Section 8.3.2, will be generated when the path event, described in Section 8.3.2, will be generated when the path
changes. changes.
However, in some cases, it is necessary to explicitly indicate to a However, in some cases, it is necessary to explicitly indicate to a
Connection that a new Remote Endpoint has become available for use or Connection that a new Remote Endpoint has become available for use or
indicate that a Remote Endpoint is no longer available. This is most indicate that a Remote Endpoint is no longer available. This is most
common in the case of peer-to-peer connections using Trickle ICE common in the case of peer-to-peer connections using Trickle ICE
[RFC8838]. [RFC8838].
skipping to change at line 2323 skipping to change at line 2321
Depending on the status of the Connection, the queried Connection Depending on the status of the Connection, the queried Connection
Properties will include different information: Properties will include different information:
* The Connection state, which can be one of the following: * The Connection state, which can be one of the following:
Establishing, Established, Closing, or Closed (see Establishing, Established, Closing, or Closed (see
Section 8.1.11.1). Section 8.1.11.1).
* Whether the Connection can be used to send data (see * Whether the Connection can be used to send data (see
Section 8.1.11.2). A Connection cannot be used for sending if the Section 8.1.11.2). A Connection cannot be used for sending if the
Connection was created with the Selection Property direction set Connection was created with the Selection Property direction set
to unidirectional receive or if a Message marked as Final was sent to Unidirectional receive or if a Message marked as Final was sent
over this Connection. See also Section 9.1.3.5. over this Connection. See also Section 9.1.3.5.
* Whether the Connection can be used to receive data (see * Whether the Connection can be used to receive data (see
Section 8.1.11.3). A Connection cannot be used for receiving if Section 8.1.11.3). A Connection cannot be used for receiving if
the Connection was created with the Selection Property direction the Connection was created with the Selection Property direction
set to unidirectional send or if a Message marked as Final was set to Unidirectional send or if a Message marked as Final was
received (see Section 9.3.3.3). The latter is only supported by received (see Section 9.3.3.3). The latter is only supported by
certain transport protocols, e.g., by TCP as a half-closed certain transport protocols, e.g., by TCP as a half-closed
connection. connection.
* For Connections that are Established, Closing, or Closed: * For Connections that are Established, Closing, or Closed:
Connection Properties (Section 8.1) of the actual protocols that Connection Properties (Section 8.1) of the actual protocols that
were selected and instantiated, and Selection Properties that the were selected and instantiated, and Selection Properties that the
application specified on the Preconnection. Selection Properties application specified on the Preconnection. Selection Properties
of type Preference will be exposed as Boolean values indicating of type "Preference" will be exposed as Boolean values indicating
whether or not the property applies to the selected transport. whether or not the property applies to the selected transport.
Note that the instantiated Protocol Stack might not match all Note that the instantiated Protocol Stack might not match all
Protocol Selection Properties that the application specified on Protocol Selection Properties that the application specified on
the Preconnection. the Preconnection.
* For Connections that are Established: Transport Services system * For Connections that are Established: Transport Services system
implementations ought to provide information concerning the implementations ought to provide information concerning the
path(s) used by the Protocol Stack. This can be derived from path(s) used by the Protocol Stack. This can be derived from
local PvD information, measurements by the Protocol Stack, or local PvD information, measurements by the Protocol Stack, or
other sources. For example, a transport system that is configured other sources. For example, a transport system that is configured
skipping to change at line 2491 skipping to change at line 2489
and/or receive data without any urgency. This can, for example, and/or receive data without any urgency. This can, for example,
be used to select Protocol Stacks with scavenger transmission be used to select Protocol Stacks with scavenger transmission
control and/or to assign the traffic to a lower-effort service. control and/or to assign the traffic to a lower-effort service.
Transport Services systems that map the requested capacity profile Transport Services systems that map the requested capacity profile
to per-connection DSCP signaling SHOULD assign the DSCP "Less than to per-connection DSCP signaling SHOULD assign the DSCP "Less than
best effort" PHB [RFC8622]. best effort" PHB [RFC8622].
Low Latency/Interactive: The application is interactive and prefers Low Latency/Interactive: The application is interactive and prefers
loss to latency. Response time SHOULD be optimized at the expense loss to latency. Response time SHOULD be optimized at the expense
of delay variation and efficient use of the available capacity of delay variation and efficient use of the available capacity
when sending on this Connection. The "Low Latency/Interactive" when sending on this Connection. The Low Latency/Interactive
value of the capacity profile can be used by the system to disable value of the capacity profile can be used by the system to disable
the coalescing of multiple small Messages into larger packets the coalescing of multiple small Messages into larger packets
(Nagle algorithm (see Section 4.2.3.4 of [RFC1122])); to prefer (Nagle algorithm (see Section 4.2.3.4 of [RFC1122])); to prefer
immediate acknowledgement from the peer endpoint when supported by immediate acknowledgement from the peer endpoint when supported by
the underlying transport; and so on. Transport Services systems the underlying transport; and so on. Transport Services systems
that map the requested capacity profile to per-connection DSCP that map the requested capacity profile to per-connection DSCP
signaling without multiplexing SHOULD assign a DSCP Assured signaling without multiplexing SHOULD assign a DSCP Assured
Forwarding (AF41, AF42, AF43, and AF44) PHB [RFC2597]. Inelastic Forwarding (AF41, AF42, AF43, and AF44) PHB [RFC2597]. Inelastic
traffic that is expected to conform to the configured network traffic that is expected to conform to the configured network
service rate could be mapped to the DSCP Expedited Forwarding PHBs service rate could be mapped to the DSCP Expedited Forwarding PHBs
skipping to change at line 2679 skipping to change at line 2677
8.1.11.4. Maximum Message Size Before Fragmentation or Segmentation 8.1.11.4. Maximum Message Size Before Fragmentation or Segmentation
Name: singularTransmissionMsgMaxLen Name: singularTransmissionMsgMaxLen
Type: Integer (non-negative) or Not applicable Type: Integer (non-negative) or Not applicable
This property, if applicable, represents the maximum Message size This property, if applicable, represents the maximum Message size
that can be sent without incurring network-layer fragmentation at the that can be sent without incurring network-layer fragmentation at the
sender. It is specified as a number of bytes and is less than or sender. It is specified as a number of bytes and is less than or
equal to the Maximum Message Size on Send. It exposes a readable equal to the maximum Message Size on Send. It exposes a readable
value to the application based on the Maximum Packet Size (MPS). The value to the application based on the Maximum Packet Size (MPS). The
value of this property can change over time (and can be updated via value of this property can change over time (and can be updated via
Datagram Packetization Layer Path MTU Discovery (DPLPMTUD) Datagram Packetization Layer Path MTU Discovery (DPLPMTUD)
[RFC8899]). This value allows a sending stack to avoid unwanted [RFC8899]). This value allows a sending stack to avoid unwanted
fragmentation at the network layer or segmentation by the transport fragmentation at the network layer or segmentation by the transport
layer before choosing the message size and/or after a SendError layer before choosing the message size and/or after a SendError
occurs indicating an attempt to send a Message that is too large. A occurs indicating an attempt to send a Message that is too large. A
Transport Services API could express Not applicable in an Transport Services API could express Not applicable in an
environment-typical way, e.g., as a Union type or special value environment-typical way, e.g., as a Union type or special value
(e.g., 0). (e.g., 0).
skipping to change at line 2729 skipping to change at line 2727
These properties are included here because the feature Suggest These properties are included here because the feature Suggest
timeout to the peer is part of the minimal set of Transport Services timeout to the peer is part of the minimal set of Transport Services
[RFC8923], where this feature was categorized as "functional". This [RFC8923], where this feature was categorized as "functional". This
means that when a Transport Services system offers this feature, the means that when a Transport Services system offers this feature, the
Transport Services API has to expose an interface to the application. Transport Services API has to expose an interface to the application.
Otherwise, the implementation might violate assumptions by the Otherwise, the implementation might violate assumptions by the
application, which could cause the application to fail. application, which could cause the application to fail.
All of the below properties are optional (e.g., it is possible to All of the below properties are optional (e.g., it is possible to
specify User Timeout Enabled as true but not specify an Advertised specify tcp.userTimeoutValue as true but not specify a
User Timeout value; in this case, the TCP default will be used). tcp.userTimeoutValue value; in this case, the TCP default will be
These properties reflect the API extension specified in Section 3 of used). These properties reflect the API extension specified in
[RFC5482]. Section 3 of [RFC5482].
8.2.1. Advertised User Timeout 8.2.1. Advertised User Timeout
Name: tcp.userTimeoutValue Name: tcp.userTimeoutValue
Type: Integer (positive) Type: Integer (positive)
Default: the TCP default Default: the TCP default
This time value is advertised via the TCP User Timeout Option (UTO) This time value is advertised via the TCP User Timeout Option (UTO)
[RFC5482] to the Remote Endpoint, which can use it to adapt its own [RFC5482] to the Remote Endpoint, which can use it to adapt its own
Timeout for aborting the Connection (see Section 8.1.3) value. connTimeout (see Section 8.1.3) value.
8.2.2. User Timeout Enabled 8.2.2. User Timeout Enabled
Name: tcp.userTimeoutEnabled Name: tcp.userTimeoutEnabled
Type: Boolean Type: Boolean
Default: false Default: false
This property controls whether the TCP UTO is enabled for a This property controls whether the TCP UTO is enabled for a
skipping to change at line 2803 skipping to change at line 2801
Connection -> PathChange<> Connection -> PathChange<>
9. Data Transfer 9. Data Transfer
Data is sent and received as Messages, which allows the application Data is sent and received as Messages, which allows the application
to communicate the boundaries of the data being transferred. to communicate the boundaries of the data being transferred.
9.1. Messages and Framers 9.1. Messages and Framers
Each Message has an optional Message Context, which allows adding Each Message has an optional MessageContext, which allows adding
Message Properties, to identify Send events related to a specific Message Properties, to identify Send events related to a specific
Message or to inspect metadata related to the Message sent. Framers Message or to inspect metadata related to the Message sent. Framers
can be used to extend or modify the Message data with additional can be used to extend or modify the Message data with additional
information that can be processed at the receiver to detect message information that can be processed at the receiver to detect message
boundaries. boundaries.
9.1.1. Message Contexts 9.1.1. Message Contexts
Using the MessageContext object, the application can set and retrieve Using the MessageContext object, the application can set and retrieve
metadata of the Message, including Message Properties (see metadata of the Message, including Message Properties (see
Section 9.1.3) and framing metadata (see Section 9.1.2.2). Section 9.1.3) and framing metadata (see Section 9.1.2.2).
Therefore, a MessageContext object can be passed to the Send action Therefore, a MessageContext object can be passed to the Send action
and is returned by each event related to Send and Receive. and is returned by each event related to Send and Receive.
Message Properties can be set and queried using the Message Context: Message Properties can be set and queried using the MessageContext:
MessageContext.add(property, value) MessageContext.add(property, value)
PropertyValue := MessageContext.get(property) PropertyValue := MessageContext.get(property)
These Message Properties can be generic properties or Protocol- These Message Properties can be generic properties or Protocol-
specific Properties. specific Properties.
For MessageContexts returned by Send events (see Section 9.2.2) and For MessageContexts returned by Send events (see Section 9.2.2) and
Receive events (see Section 9.3.2), the application can query Receive events (see Section 9.3.2), the application can query
information about the Local and Remote Endpoint: information about the Local and Remote Endpoint:
skipping to change at line 2949 skipping to change at line 2947
httpFramer := NewHTTPMessageFramer() httpFramer := NewHTTPMessageFramer()
... ...
messageContext := NewMessageContext() messageContext := NewMessageContext()
messageContext.add(httpFramer, "accept", "text/html") messageContext.add(httpFramer, "accept", "text/html")
9.1.3. Message Properties 9.1.3. Message Properties
Applications needing to annotate the Messages they send with extra Applications needing to annotate the Messages they send with extra
information (for example, to control how data is scheduled and information (for example, to control how data is scheduled and
processed by the transport protocols supporting the Connection) can processed by the transport protocols supporting the Connection) can
include this information in the Message Context passed to the Send include this information in the MessageContext passed to the Send
action. For other uses of the Message Context, see Section 9.1.1. action. For other uses of the MessageContext, see Section 9.1.1.
Message Properties are per-Message, not per-Send, if partial Messages Message Properties are per-Message, not per-Send, if partial Messages
are sent (Section 9.2.3). All data blocks associated with a single are sent (Section 9.2.3). All data blocks associated with a single
Message share properties specified in the Message Contexts. For Message share properties specified in the MessageContexts. For
example, it would not make sense to have the beginning of a Message example, it would not make sense to have the beginning of a Message
expire and then allow the end of the Message to still be sent. expire and then allow the end of the Message to still be sent.
A MessageContext object contains metadata for the Messages to be sent A MessageContext object contains metadata for the Messages to be sent
or received. or received.
messageData := "hello" messageData := "hello"
messageContext := NewMessageContext() messageContext := NewMessageContext()
messageContext.add(parameter, value) messageContext.add(parameter, value)
Connection.Send(messageData, messageContext) Connection.Send(messageData, messageContext)
skipping to change at line 3116 skipping to change at line 3114
If true, this indicates a Message is the last that the application If true, this indicates a Message is the last that the application
will send on a Connection. This allows underlying protocols to will send on a Connection. This allows underlying protocols to
indicate to the Remote Endpoint that the Connection has been indicate to the Remote Endpoint that the Connection has been
effectively closed in the sending direction. For example, TCP-based effectively closed in the sending direction. For example, TCP-based
Connections can send a FIN once a Message marked as Final has been Connections can send a FIN once a Message marked as Final has been
completely sent, indicated by marking endOfMessage. Protocols that completely sent, indicated by marking endOfMessage. Protocols that
do not support signaling the end of a Connection in a given direction do not support signaling the end of a Connection in a given direction
will ignore this property. will ignore this property.
A Final Message must always be sorted to the end of a list of A Final Message must always be sorted to the end of a list of
Messages. The Final property overrides Priority and any other Messages. The final property overrides Priority and any other
property that would reorder Messages. If another Message is sent property that would reorder 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.
9.1.3.6. Sending Corruption Protection Length 9.1.3.6. Sending Corruption Protection Length
Name: msgChecksumLen Name: msgChecksumLen
Type: Integer (non-negative) or Full Coverage Type: Integer (non-negative) or Full Coverage
skipping to change at line 3323 skipping to change at line 3321
next Send action. next Send action.
9.2.2.2. Expired 9.2.2.2. Expired
Connection -> Expired<messageContext> Connection -> Expired<messageContext>
The Expired event occurs when a previous Send action expired before The Expired event occurs when a previous Send action expired before
completion, i.e., when the Message was not sent before its Lifetime completion, i.e., when the Message was not sent before its Lifetime
(see Section 9.1.3.1) expired. This is separate from SendError, as (see Section 9.1.3.1) expired. This is separate from SendError, as
it is an expected behavior for partially reliable transports. The it is an expected behavior for partially reliable transports. The
Expired event contains a reference to the Message Context of the Expired event contains a reference to the MessageContext of the
Message to which it applies. Message to which it applies.
9.2.2.3. SendError 9.2.2.3. SendError
Connection -> SendError<messageContext, reason?> Connection -> SendError<messageContext, reason?>
A SendError occurs when a Message was not sent due to an error A SendError occurs when a Message was not sent due to an error
condition: an attempt to send a Message that is too large for the condition: an attempt to send a Message that is too large for the
system and Protocol Stack to handle, some failure of the underlying system and Protocol Stack to handle, some failure of the underlying
Protocol Stack, or a set of Message Properties not consistent with Protocol Stack, or a set of Message Properties not consistent with
the Connection's transport properties. The SendError contains a the Connection's transport properties. The SendError contains a
reference to the Message Context of the Message to which it applies. reference to the MessageContext of the Message to which it applies.
9.2.3. Partial Sends 9.2.3. 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
might be too large for the application to hold in memory at one time might be too large for the application to hold in memory at one time
or the length of the Message might be unknown or unbounded. or the length of the Message might 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
skipping to change at line 3393 skipping to change at line 3391
9.2.5. Send on Active Open: InitiateWithSend 9.2.5. 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, Connection := Preconnection.InitiateWithSend(messageData,
messageContext?, messageContext?,
timeout?) 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" using the Message passed to InitiateWithSend as "safely replayable" using the
safelyReplayable property. This allows the Transport Services system safelyReplayable property. This allows the Transport Services system
to make use of 0-RTT establishment in case this is supported by the to make use of 0-RTT establishment in case this is supported by the
available Protocol Stacks. When the selected stack or stacks do not available Protocol Stacks. When the selected stack or stacks do not
support transmitting data upon connection establishment, support transmitting data upon connection establishment,
InitiateWithSend is identical to Initiate followed by Send. InitiateWithSend is identical to Initiate followed by Send.
Neither partial sends nor send batching are supported by Neither partial sends nor send batching are supported by
InitiateWithSend. InitiateWithSend.
skipping to change at line 3541 skipping to change at line 3539
continue to receive more of the same Message, the application must 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
flag is delivered or a ReceiveError occurs. All partial blocks of a flag is delivered or a ReceiveError occurs. All partial blocks of a
single Message are delivered in order without gaps. This event does single Message are delivered in order without gaps. This event does
not support delivering non-contiguous partial Messages. For example, not support delivering non-contiguous partial Messages. For example,
if Message A is divided into three pieces (A1, A2, and A3), Message B if Message A is divided into three pieces (A1, A2, and A3), Message B
is divided into three pieces (B1, B2, and B3), and preserveOrder is is divided into three pieces (B1, B2, and B3), and preserveOrder is
not Required, the ReceivedPartial could deliver them in a sequence not Require, the ReceivedPartial could deliver them in a sequence
like this: A1, B1, B2, A2, A3, B3. This is because the like this: A1, B1, B2, A2, A3, B3. This is because the
MessageContext allows the application to identify the pieces as MessageContext allows the application to identify the pieces as
belonging to Message A and B, respectively. However, a sequence like belonging to Message A and B, respectively. However, a sequence like
A1, A3 will never occur. A1, A3 will never occur.
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 could still be delivered if one of the the ReceivedPartial event could still be delivered if one of the
following conditions is true: following conditions is true:
skipping to change at line 3615 skipping to change at line 3613
the peer application to adjust the msgChecksumLen property (see the peer application to adjust the msgChecksumLen property (see
Section 9.1.3.6). Section 9.1.3.6).
In contrast, internal protocol reception errors (e.g., loss causing In contrast, internal protocol reception errors (e.g., loss causing
retransmissions in TCP) are not signaled by this event. Conditions retransmissions in TCP) are not signaled by this event. Conditions
that irrevocably lead to the termination of the Connection are that irrevocably lead to the termination of the Connection are
signaled using ConnectionError (see Section 10). signaled using ConnectionError (see Section 10).
9.3.3. Receive Message Properties 9.3.3. Receive Message Properties
Each Message Context could contain metadata from protocols in the Each MessageContext could 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 through additional read-only Message dependent. These are exposed through 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 9.1.1) passed by the receive event. The metadata values in Section 9.1.1) passed by the receive event. The metadata values in
the following subsections are supported. the following subsections are supported.
9.3.3.1. Property Specific to UDP and UDP-Lite: ECN 9.3.3.1. Property Specific to UDP and UDP-Lite: 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
skipping to change at line 3651 skipping to change at line 3649
Thus, receivers might wish to perform additional checks for early Thus, receivers might wish to perform additional checks for early
data to ensure that it is safely replayable. If TLS 1.3 is available data to ensure that it is safely replayable. If TLS 1.3 is available
and the recipient Message was sent as part of early data, the and the recipient Message was sent as part of early data, the
corresponding metadata carries a flag indicating as such. If early corresponding metadata carries a flag indicating as such. If early
data is enabled, applications should check this metadata field for data is enabled, applications should check this metadata field for
Messages received during Connection establishment and respond Messages received during Connection establishment and respond
accordingly. accordingly.
9.3.3.3. Receiving Final Messages 9.3.3.3. Receiving Final Messages
The Message Context can indicate whether or not this Message is the The MessageContext can indicate whether or not this Message is the
Final Message on a Connection. For any Message that is marked as last 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 can be marked delivered. This corresponds to the final property that can be marked
on a sent Message; see Section 9.1.3.5. on a sent Message; see Section 9.1.3.5.
Some transport protocols and peers do not support signaling of the Some transport protocols and peers do not support signaling of the
final property. Therefore, applications SHOULD NOT rely on receiving final property. Therefore, applications SHOULD NOT rely on receiving
a Message marked Final to know that the sending endpoint is done a Message marked Final to know that the sending endpoint is done
sending on a Connection. sending on a Connection.
skipping to change at line 4222 skipping to change at line 4220
Time duration types are implementation specific. For instance, it Time duration types are implementation specific. For instance, it
could be a number of seconds, a number of milliseconds, or a struct could be a number of seconds, a number of milliseconds, or a struct
timeval in C; in C++, it could be a user-defined Duration class. timeval in C; in C++, it could be a user-defined Duration class.
Appendix B. Convenience Functions Appendix B. Convenience Functions
B.1. Adding Preference Properties B.1. Adding Preference Properties
TransportProperties will frequently need to set Selection Properties TransportProperties will frequently need to set Selection Properties
of type Preference; therefore, implementations can provide special of type "Preference"; therefore, implementations can provide special
actions for adding each preference level, i.e., actions for adding each preference level, i.e.,
TransportProperties.Set(some_property, avoid) is equivalent to TransportProperties.Set(some_property, avoid) is equivalent to
TransportProperties.Avoid(some_property): TransportProperties.Avoid(some_property):
TransportProperties.Require(property) TransportProperties.Require(property)
TransportProperties.Prefer(property) TransportProperties.Prefer(property)
TransportProperties.NoPreference(property) TransportProperties.NoPreference(property)
TransportProperties.Avoid(property) TransportProperties.Avoid(property)
TransportProperties.Prohibit(property) TransportProperties.Prohibit(property)
 End of changes. 31 change blocks. 
46 lines changed or deleted 44 lines changed or added

This html diff was produced by rfcdiff 1.48.