An Abstract Application Programming Interface (API) for Transport Services
Extracted elements (30)
Default Selection Property values are chosen to represent a configuration implementable over TCP, so that applications using defaults behave predictably across Transport Services Systems. Using consistent defaults benefits portability, even when TCP is not available on a given system.
The API is message-oriented rather than stream-oriented. Where the underlying transport does not provide message framing, application-assisted Message Framers are used. This abstraction allows a unified API across datagram and stream-oriented transports without exposing the framing difference to the application.
The Transport Services API is designed as an abstract, language- and platform-independent interface intended to replace the BSD Socket API. It enables dynamic selection of transport protocols and network paths at runtime, allowing faster deployment of new protocols without requiring application changes.
When path and protocol preferences conflict, path selection is prioritized over protocol selection. This ordering is chosen because interface type preferences often reflect user cost concerns (e.g., avoiding cellular data charges), which are higher-stakes than protocol preferences.
The Transport Services API is explicitly intended to replace the BSD Socket API as the common transport interface. Implementations have significant freedom in presenting the API to programmers but SHOULD use the names assigned in this document, subject to language typographic conventions, to maintain consistency across implementations.
Applications MUST be able to constrain the security protocols and versions that the Transport Services System will use, via the allowedSecurityProtocols parameter or an equivalent mechanism, to prevent use of protocols with unknown or weak security properties.
At least one Local Endpoint MUST be specified if the Preconnection is used to Listen. At least one Remote Endpoint MUST be specified if the Preconnection is used to Initiate. Both Local and Remote Endpoints MUST be specified for peer-to-peer Rendezvous.
Connections that use Transport Services SHOULD use security in general. For compatibility with endpoints lacking transport security, applications can initialize SecurityParameters to indicate disabled or opportunistic security. Opportunistic security allows connections without security but still attempts unauthenticated security if available.
If a Connection is not congestion controlled, an application using it SHOULD itself perform congestion control per RFC 2914 or use a circuit breaker per RFC 8084. If the Connection is congestion controlled, performing additional congestion control in the application can have negative performance implications.
Message Framers MUST be added to the Preconnection during the preestablishment phase; they cannot be added after Connection establishment.
Namespaces for keywords in the IANA 'Protocol Numbers' registry are reserved for Protocol-specific Properties and MUST NOT be used for vendor-specific or implementation-specific Properties.
Once Initiate or Listen has been called, any changes to the Preconnection MUST NOT have any effect on the resulting Connection or Listener. The Preconnection may be reused afterward.
Protocol-specific Transport Property names MUST use the protocol acronym as the Namespace (e.g., tcp.userTimeoutValue). Vendor-specific Properties MUST be placed in a Namespace starting with underscore ('_'). IETF protocol-specific Property names MUST be specified in an RFC from the IETF Stream after IETF Review.
The API MUST NOT permit an Endpoint object to be configured with multiple Endpoint Identifiers of the same type (e.g., two IP addresses). Two IP addresses are represented as two separate Endpoint objects.
The implementation MUST ensure outcomes consistent with all Require and Prohibit preferences. When conflict arises between path and protocol preferences, the Transport Services System SHOULD determine the preferred path first, regardless of protocol preferences, to provide consistency across implementations.
Transport Services Systems SHOULD implement each Selection Property, Connection Property, and MessageContext Property specified in this document, even when a specific implementation will always result in a no-op (e.g., msgOrdered when only TCP is available).
Setting the multipath property to Active (Section 6.2.14) or enabling advertisesAltaddr (Section 6.2.15) can result in users being linkable across multiple paths, even if address advertisement is disabled. The API exposes these privacy implications explicitly so applications can make informed choices.
The Transport Services System resolves endpoint names internally when Initiate, Listen, or Rendezvous is called. Privacy considerations for the timing of this name resolution—specifically whether resolution is performed early (via Preconnection.Resolve()) or deferred—are given in Section 13, as early resolution can expose DNS queries before a connection is actually needed.
The useTemporaryLocalAddress property (Section 6.2.13) allows applications to prefer temporary ('privacy') IPv6 addresses (RFC 8981) to prevent linking connections over time. However, temporary addresses cannot be used with IPv4, and they may interfere with protocol resumption mechanisms that reduce latency.
A Connection object represents an instance of a transport Protocol Stack supporting Send and/or Receive. Connections can be created from Preconnections via Initiate (active open), Listen (passive open), or Rendezvous (peer-to-peer); they are presented consistently to the application regardless of whether the underlying transport is connectionless or connection-oriented.
A Message Framer (Section 9.1.2) allows applications to define how Message boundaries are found in a byte-stream transport. Framers transform sequences of Messages into byte-streams and vice versa and must be registered on the Preconnection before establishment.
A Preconnection object represents a potential Connection and holds Local Endpoints, Remote Endpoints, TransportProperties, and SecurityParameters. It is a passive data structure used as a template to create Connections via Initiate, Listen, or Rendezvous; changes to a Preconnection after Connection creation have no effect on the Connection.
Connection Groups are created by cloning an existing Connection (Connection.Clone()), which produces a new Connection sharing Transport Properties, Security Parameters, and scheduling context with the original. Multistream transports may map grouped Connections to streams of a single underlying transport connection.
SecurityParameters holds cryptographic configuration including allowedSecurityProtocols, serverCertificate, clientCertificate, pinnedServerCertificate (array of certificate chains), alpn (ALPN values), supportedGroup, ciphersuite, signatureAlgorithm, session cache options, and preSharedKey. It also supports callbacks: TrustVerificationCallback and IdentityChallengeCallback.
Selection Properties use a five-level Preference Enumeration: Require (only select protocols/paths providing the property), Prefer, No Preference, Avoid, and Prohibit (only select protocols/paths not providing the property). Most Selection Properties default to values implementable over TCP.
The Listener.SetNewConnectionLimit(value) mechanism allows servers to rate-limit inbound Connection delivery. Each ConnectionReceived event decrements the limit; when it reaches zero, no further Connections are delivered until the limit is raised. Default is Infinite.
The multipath Selection Property (Section 6.2.14) takes values Disabled, Active, or Passive. Active negotiates multipath use if the transport supports it; Passive supports multipath if the remote requests it; Disabled prevents using multiple paths in parallel but does not prevent selecting a multipath-capable protocol. The multipathPolicy Connection Property (Section 8.1.7) separately controls the policy for using multiple paths.
The Rendezvous action supports simultaneous peer-to-peer Connection establishment. It listens on Local Endpoint candidates while also trying to establish outward connections to Remote Endpoint candidates, using an ICE-like probing approach (RFC 8445) when multiple candidates exist. The Preconnection.Resolve() action discovers NAT bindings via STUN/TURN before Rendezvous.
Trust verification and identity challenge callbacks block Connection establishment progress. Trust verification allows the application to verify a Remote Endpoint's X.509 certificate (RFC 5280) or other credential before the handshake continues. Applications SHOULD use common safe defaults for ciphersuite parameters.
A Connection progresses through: preestablishment (Preconnection configured) → establishment (Initiate/Listen/Rendezvous called, Ready or EstablishmentError fired) → data transfer (Send/Receive events) → termination (Close or Abort, then Closed event). Ordering of operations and events is defined in Section 11.