RtcTransport

1. Introduction

The RtcTransport API is a low-level API used for sending and receiving datagrams over a secure peer-to-peer transport.

The transport is consent-based, meaning that the connection must be accepted by the remote peer before any application data can be sent.

It provides application-level packet scheduling, giving applications full control over packet pacing and bandwidth estimation. Additionally, transport feedback is sent back to the sender and fed into a circuit-breaker, which protects the network by disallowing packets to be sent if abusive behavior is detected.

The API has been designed in a modular fashion to allow wire formats, transport establishment mechanics, and feedback formats to evolve over time.

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC2119] and [RFC8174] when, and only when, they appear in all capitals, as shown here.

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL], as this specification uses that specification and terminology.

3. Concepts

Circuit Breaker

A mechanism used to protect the network by detecting and stoping abusive behavior.

Network Route

A specific route between a local and a remote peer.

Transport Format

A combination of a wire format and a Transport Header.

Transport Header

A transport level header included in packets that carries feedback information from the remote peer, used in conjuction with the Circuit Breaker to detect and prevent abusive network behavior.

Writable

A Network Route is considered Writable when it has been verified that the remote peer can successfully receive packets over that specific Network Route.

4. The RtcTransport Interface

[Exposed=(Window,Worker)]
interface RtcTransport {
  constructor(RtcTransportConfig config);
  static readonly attribute FrozenArray<RtcTransportFormat> supportedFormats;
  readonly attribute RtcNetworkRouteController networkRouteController;
  attribute EventHandler ontransportstatus;
  attribute EventHandler onpendingpacketssentinfo;
  attribute EventHandler onpendingpacketsreceived;
  attribute EventHandler onerror;
  attribute EventHandler onfeedbacksent;
  undefined setFormat(RtcTransportFormat format);
  undefined sendPackets(sequence<RtcPacketToSend> packets, RtcNetworkRoute networkRoute);
  undefined setRemoteFingerprints(sequence<ArrayBuffer> fingerprint);
  Promise<boolean> establishEncryption(RtcNetworkRoute networkRoute);
  sequence<RtcPacketSentInfo> getPacketSentInfo();
  sequence<RtcPacketReceived> getReceivedPacket();
};

4.1. Internal slots

An RtcTransport object has the following internal slots.

4.2. Constructor

constructor(config)

When the RtcTransport() constructor is invoked, the user agent MUST run the following steps:

1. Let transport be a new RtcTransport object.

2. Set transport’s [[Format]] internal slot to undefined.

3. Set transport’s [[PendingSendPackets]] internal slot to a new empty queue.

4. Set transport’s [[PendingSentInfo]] internal slot to a new empty queue.

5. Set transport’s [[PendingReceivedPackets]] internal slot to a new empty queue.

6. Set transport’s [[EncryptionContext]] internal slot to undefined.

7. Set transport’s [[RemoteFingerprints]] internal slot to undefined.

8. Set transport’s [[LastScheduledPacketInfo]] internal slot to undefined.

9. If config’s transportControllerType member is "automaticIceController", set transport’s [[RouteController]] internal slot to a new RtcAutomaticIceController object.

10. If config’s transportControllerType member is "manualIceController", set transport’s [[RouteController]] internal slot to a new RtcManualIceController object.

11. Return transport.

4.3. Attributes

supportedFormats, of type FrozenArray<RtcTransportFormat>, readonly

Returns a list of supported RtcTransportFormats.

networkRouteController, of type RtcNetworkRouteController, readonly

Returns the controller associated with this transport.

ontransportstatus, of type EventHandler

Fired when the circuit-breaker disables or re-enables the transport.

onpendingpacketssentinfo, of type EventHandler

Fired when there is new packet sent info to retrieve.

onpendingpacketsreceived, of type EventHandler

Fired when there are new received packets to retrieve.

onerror, of type EventHandler

Fired on buffer overflows (sent info, feedback, or receive buffers).

onfeedbacksent, of type EventHandler

Fired when the transport automatically generates and sends protocol-level feedback.

4.4. Methods

setFormat(format)

When the setFormat(format) method is invoked, the user agent MUST run the following steps:

1. Let transport be the RtcTransport object on which the method was invoked.

2. If transport’s [[Format]] internal slot is not undefined, throw an InvalidStateError.

3. If format is the RtcTransportFormat value "ICE-DTLS/V0" and transport’s [[RouteController]] internal slot is neither an RtcAutomaticIceController nor an RtcManualIceController object, throw a NotSupportedError.

   In this version of the specification, the only supported RtcTransportFormat is "ICE-DTLS/V0", which is compatible with all available route controllers (RtcAutomaticIceController and RtcManualIceController).

4. Set transport’s [[Format]] internal slot to format.

sendPackets(packets, networkRoute)

When the sendPackets(packets, networkRoute) method is invoked, the user agent MUST run the following steps:

1. Let transport be the RtcTransport object on which the method was invoked.

2. If transport’s [[EncryptionContext]] internal slot is undefined, throw an InvalidStateError.

3. If networkRoute is not Writable, throw an exception.

4. If packets is empty, return.

5. Let lastInfo be transport’s [[LastScheduledPacketInfo]] internal slot.

6. For each packet in packets:

   1. If packet is the first item in packets:

      1. If lastInfo is not undefined:

         1. If packet’s id is less than or equal to lastInfo’s ID, throw a RangeError.

         2. If packet’s sendTime is less than lastInfo’s send time, throw a RangeError.

   2. Otherwise:

      1. Let previousPacket be the item in packets immediately preceding packet.

      2. If packet’s id is less than or equal to previousPacket’s id, throw a RangeError.

      3. If packet’s sendTime is less than previousPacket’s sendTime, throw a RangeError.

   3. Let now be the current high resolution time.

   4. If packet’s sendTime is greater than now + 100ms, throw a RangeError.

7. Enqueue all items in packets into transport’s [[PendingSendPackets]] queue.

8. Let lastPacket be the last item in packets.

9. Set transport’s [[LastScheduledPacketInfo]] to a new record containing lastPacket’s id as ID and lastPacket’s sendTime as send time.

What type of exceptions should be thrown when the various checks fail?

What should the acceptable range for the send time be? What if the send time is in the past?

Decide what to do if the networkRoute becomes non-writable before packets were scheduled for sending.

Describe how sendPackets interacts with the circuit breaker.

There should be some text describing how sending is done and what the expected behavior should be.

setRemoteFingerprints(fingerprint)

When the setRemoteFingerprints(fingerprint) method is invoked, the user agent MUST run the following steps:

1. Let transport be the RtcTransport object on which the method was invoked.

2. If transport’s [[RemoteFingerprints]] internal slot is not undefined, throw an InvalidStateError.

3. Set transport’s [[RemoteFingerprints]] internal slot to fingerprint.

Should there be any validation of the fingerprints? Is there a particular standard we expect them to adhere to?

establishEncryption(networkRoute)

When the establishEncryption(networkRoute) method is invoked, the user agent MUST run the following steps:

1. Let transport be the RtcTransport object on which the method was invoked.

2. Let p be a new promise.

3. If transport’s [[EncryptionContext]] internal slot is not undefined, resolve p with true and return p.

4. If transport’s [[RemoteFingerprints]] internal slot is undefined, reject p with an InvalidStateError and return p.

5. If networkRoute is not writable, resolve p with false and return p.

6. Run the following steps in parallel:

   1. Start or continue the encryption establishment process over networkRoute to establish a secure transport connection.

   2. As part of the encryption establishment process, the user agent MUST verify that the certificate presented by the remote peer matches one of the fingerprints stored in transport’s [[RemoteFingerprints]] internal slot. If the verification fails, the encryption establishment process fails.

      The specific encryption mechanism depends on the configured RtcTransportFormat. For example, for the RtcTransportFormat value "ICE-DTLS/V0", this corresponds to performing a DTLS handshake and verifying the remote certificate against the fingerprints.

   3. If the encryption establishment process completes successfully:

      1. Set transport’s [[EncryptionContext]] internal slot to the established encryption context.

      2. Resolve p with true.

   4. If the encryption establishment process fails or times out:

      1. Resolve p with false.

7. Return p.

getPacketSentInfo()

When the getPacketSentInfo() method is invoked, the user agent MUST run the following steps:

1. Let transport be the RtcTransport object on which the method was invoked.

2. Let result be a new empty list.

3. While transport’s [[PendingSentInfo]] queue is not empty:

   1. Append the result of dequeueing from transport’s [[PendingSentInfo]] queue to result.

4. Return result.

getReceivedPacket()

When the getReceivedPacket() method is invoked, the user agent MUST run the following steps:

1. Let transport be the RtcTransport object on which the method was invoked.

2. Let result be a new empty list.

3. While transport’s [[PendingReceivedPackets]] queue is not empty:

   1. Append the result of dequeueing from transport’s [[PendingReceivedPackets]] queue to result.

4. Return result.

5. ICE Controllers

5.1. RtcManualIceController

[Exposed=(Window,Worker)]
interface RtcManualIceController {
  undefined gatherHostCandidates();
  Promise<undefined> gatherSrflxCandidates(IceServer iceServer);
  Promise<boolean> refreshSrflxCandidate(LocalIceCandidate localCandidate);
  Promise<undefined> gatherRelayCandidates(IceServer server, unsigned long requestedLifetimeInSeconds);
  Promise<unsigned long> refreshRelayCandidate(LocalIceCandidate relayCandidate, unsigned long requestedLifetimeInSeconds);
  IceCandidatePair createCandidatePair(LocalIceCandidate local, RemoteIceCandidate remote);
  Promise<IceProbeResult> probeCandidatePair(IceCandidatePair candidatePair);
  attribute EventHandler oncandidategathered;
  attribute EventHandler oncandidateremoved;
  attribute EventHandler onmaxpayloadsizeupdate;
  attribute EventHandler onerror;
};

gatherHostCandidates()

Will continuously gather host candidates.

gatherSrflxCandidates(iceServer)

Gathers server reflexive candidates.

refreshSrflxCandidate(localCandidate)

Sends a STUN ping to the IceServer used to discover this candidate, used to keep the candidate (NAT binding) alive. Returns a boolean indicating whether a successful STUN response was received or not.

gatherRelayCandidates(server, requestedLifetimeInSeconds)

Gathers relay candidates.

refreshRelayCandidate(relayCandidate, requestedLifetimeInSeconds)

Sends a STUN packet with a LIFETIME attribute included, used to extend the TURN allocation. Returns the actual lifetime granted by the server.

createCandidatePair(local, remote)

Creates an IceCandidatePair that represents a possible network route.

probeCandidatePair(candidatePair)

Probes the candidate pair to check if it’s (still) viable and what the RTT is.

oncandidategathered, of type EventHandler

Fired when a local candidate has been found.

oncandidateremoved, of type EventHandler

Fired when a local candidate has been removed.

onmaxpayloadsizeupdate, of type EventHandler

Fired when the max payload size of some IceCandidatePair is updated.

onerror, of type EventHandler

Fired on candidate gathering errors.

5.2. RtcAutomaticIceController

[Exposed=(Window,Worker)]
interface RtcAutomaticIceController {
  undefined SetIceServers(sequence<IceServer> servers);
  undefined gatherCandidates();
  undefined AddRemoteCandidate(RemoteIceCandidate remoteCandidate);
  attribute EventHandler oncandidategathered;
  attribute EventHandler oncandidateremoved;
  attribute EventHandler onmaxpayloadsizeupdate;
  attribute EventHandler oncandidatepairupdated;
  attribute EventHandler onerror;
};

SetIceServers(servers)

Sets the ICE servers used by the controller.

gatherCandidates()

Starts the continuous gathering of candidates.

AddRemoteCandidate(remoteCandidate)

Adds a candidate discovered from the remote peer.

oncandidategathered, of type EventHandler

Fired when a local candidate has been found.

oncandidateremoved, of type EventHandler

Fired when a local candidate has been removed.

onmaxpayloadsizeupdate, of type EventHandler

Fired when the max payload size is updated.

oncandidatepairupdated, of type EventHandler

Fired whenever a new IceCandidatePair has been selected.

onerror, of type EventHandler

Fired on candidate gathering errors.

6. Helper Types

6.1. RtcTransportConfig

dictionary RtcTransportConfig {
  required DOMString name;
  required RtcNetworkRouteControllerType transportControllerType;
  required sequence<RTCCertificate> certificates;
};

name, of type DOMString

A name useful for debugging/devtools.

transportControllerType, of type RtcNetworkRouteControllerType

Determines the ICE controller type.

certificates, of type sequence<RTCCertificate>

The certificates to use for DTLS.

6.2. RtcPacketToSend

dictionary RtcPacketToSend {
  long long id;
  ArrayBuffer data;
  DOMHighResTimeStamp sendTime;
};

id, of type long long

Monotonically increasing packet ID.

data, of type ArrayBuffer

The byte buffer to be sent.

sendTime, of type DOMHighResTimeStamp

The timestamp describing when the packet should be put on the wire.

6.3. RtcPacketSentInfo

dictionary RtcPacketSentInfo {
  long long id;
  long long packetSizeBytes;
  DOMHighResTimeStamp sendTime;
};

id, of type long long

The ID of the packet.

packetSizeBytes, of type long long

The size of the packet in bytes.

sendTime, of type DOMHighResTimeStamp

The actual timestamp that the packet was put on the wire.

6.4. RtcPacketReceived

dictionary RtcPacketReceived {
  ArrayBuffer data;
  DOMHighResTimeStamp receiveTime;
  RtcNetworkRoute networkRoute;
};

data, of type ArrayBuffer

The byte buffer received.

receiveTime, of type DOMHighResTimeStamp

The timestamp of packet receipt.

networkRoute, of type RtcNetworkRoute

The route the packet arrived on.

6.5. IceServer

dictionary IceServer {
  required DOMString url;
  required DOMString username;
  required DOMString credentials;
};

url, of type DOMString

The URL of the ICE server.

username, of type DOMString

The username used for credential verification.

credentials, of type DOMString

The credentials for authentication.

6.6. IceCandidateType

enum IceCandidateType {
  "host",
  "srflx",
  "prflx",
  "relay"
};

"host"

Host candidate.

"srflx"

Server reflexive candidate.

"prflx"

Peer reflexive candidate.

"relay"

Relay candidate.

6.7. LocalIceCandidate

[Exposed=(Window,Worker)]
interface LocalIceCandidate {
  readonly attribute DOMString ufrag;
  readonly attribute DOMString pwd;
  readonly attribute DOMString address;
  readonly attribute unsigned short port;
  readonly attribute IceCandidateType type;
  readonly attribute unsigned short networkCost;
};

ufrag, of type DOMString, readonly

ICE user fragment.

pwd, of type DOMString, readonly

ICE password.

address, of type DOMString, readonly

IP Address of the candidate.

port, of type unsigned short, readonly

Port of the candidate.

type, of type IceCandidateType, readonly

The candidate type.

networkCost, of type unsigned short, readonly

The costs associated with network route utilization.

6.8. RemoteIceCandidate

dictionary RemoteIceCandidate {
  required DOMString ufrag;
  required DOMString pwd;
  required DOMString address;
  required unsigned short port;
  required IceCandidateType type;
  unsigned short networkCost;
};

ufrag, of type DOMString

Remote ICE user fragment.

pwd, of type DOMString

Remote ICE password.

address, of type DOMString

Remote IP Address of the candidate.

port, of type unsigned short

Remote Port of the candidate.

type, of type IceCandidateType

The remote candidate type.

networkCost, of type unsigned short

The remote costs associated with network route utilization.

6.9. IceCandidatePair

[Exposed=(Window,Worker)]
interface IceCandidatePair {
  readonly attribute LocalIceCandidate localCandidate;
  readonly attribute RemoteIceCandidate remoteCandidate;
};

localCandidate, of type LocalIceCandidate, readonly

Local candidate component.

remoteCandidate, of type RemoteIceCandidate, readonly

Remote candidate component.

6.10. IceCandidateGatheredEvent

[Exposed=(Window,Worker)]
interface IceCandidateGatheredEvent : Event {
  readonly attribute (DOMString or IceServer or RemoteIceCandidate) source;
  readonly attribute LocalIceCandidate candidate;
  readonly attribute unsigned long networkCost;
  readonly attribute unsigned long? allocationLifetime;
};

source, of type (DOMString or IceServer or RemoteIceCandidate), readonly

Gathering source descriptor.

candidate, of type LocalIceCandidate, readonly

The gathered candidate.

networkCost, of type unsigned long, readonly

Costs of the network utilized.

allocationLifetime, of type unsigned long, readonly, nullable

Lifetime of allocation granted by allocation servers.

6.11. IceProbeResult

dictionary IceProbeResult {
  DOMHighResTimeStamp rtt;
};

rtt, of type DOMHighResTimeStamp

Round-trip time discovered by the probe.

6.12. Type Definitions and Rest Enums

typedef (RtcManualIceController or RtcAutomaticIceController) RtcNetworkRouteController;
typedef IceCandidatePair RtcNetworkRoute;

enum RtcTransportFormat {
  "ICE-DTLS/V0"
};

enum RtcNetworkRouteControllerType {
  "automaticIceController",
  "manualIceController"
};

RtcNetworkRouteController

Union type describing the underlying ICE route controller.

RtcNetworkRoute

Underlying network route identifier.

"ICE-DTLS/V0"

Wire format utilizing ICE for connection establishment and DTLS as a wire format with Transport Header iteration version 0.

"automaticIceController"

Automatically managed ICE candidates route controller.

"manualIceController"

Manually managed ICE candidates route controller.

7. Security and Privacy Considerations

7.1. Network Route Exposure

7.2. Circuit Breaker

7.3. Encryption

7.4. Buffer Overflows