Attributes

onreceivestream of type EventHandler

This event handler, of event handler event type receivestream, MUST be fired on when data is received from a newly created remote ReceiveStream for the first time.

Methods

createSendStream

Creates an SendStream object.

When createSendStream is called, the user agent MUST run the following steps:

1. Let transport be the UnidirectionalStreamsTransport on which createSendStream is invoked.

2. If transport's state is "closed" or "failed", immediately return a new rejected promise with a newly created InvalidStateError and abort these steps.

3. If transport's state is "connected", immediately return a new resolved promise with a newly created SendStream object, add the SendStream to the transport and abort these steps.

4. Let p be a new promise.

5. Return p and continue the following steps in the background.

6. Resolve p with a newly created SendStream object and add the SendStream to the transport when all of the following conditions are met:

   1. The transport's state has transitioned to "connected"

   2. Stream creation flow control is not being violated by exceeding the max stream limit set by the remote endpoint, as specified in [[QUIC-TRANSPORT]].

   3. p has not been settled

7. Reject p with a newly created InvalidStateError when all of the following conditions are met:

   1. The transport's state transitions to "closed" or "failed"

   2. p has not been settled

No parameters.

Return type: Promise<SendStream>

Procedures

SendStreamParameters Dictionary

The QuicStreamParameters dictionary includes information relating to stream configuration.

dictionary SendStreamParameters {
              bool disableRetransmissions = false;
};

ReceiveStreamEvent

The receivestream event uses the ReceiveStreamEvent interface.

        [ Constructor (DOMString type, ReceiveStreamEventInit eventInitDict), Exposed=Window]
interface ReceiveStreamEvent : Event {
    readonly attribute ReceiveStream stream;
};

dictionary ReceiveStreamEventInit : EventInit {
              ReceiveStream stream;
};

Attributes

onbidirectionalstream of type EventHandler

This event handler, of event handler event type bidirectionalstream, MUST be fired when data is received from a newly created remote BidirectionalStream for the first time.

Methods

createBidirectionalStream

Creates an BidirectionalStream object.

When createBidectionalStream is called, the user agent MUST run the following steps:

1. Let transport be the BidirectionalStreamsTransport on which createBidectionalStream is invoked.

2. If transport's state is "closed" or "failed", immediately return a new rejected promise with a newly created InvalidStateError and abort these steps.

3. If transport's state is "connected", immediately return a new resolved promise with a newly created BidirectionalStream object, add the BidirectionalStream to the transport and abort these steps.

4. Let p be a new promise.

5. Return p and continue the following steps in the background.

6. Resolve p with a newly created BidirectionalStream object and add the BidirectionalStream to the transport when all of the following conditions are met:

   1. The transport's state has transitioned to "connected"

   2. Stream creation flow control is not being violated by exceeding the max stream limit set by the remote endpoint, as specified in [[QUIC-TRANSPORT]].

   3. p has not been settled

7. Reject p with a newly created InvalidStateError when all of the following conditions are met:

   1. The transport's state transitions to "closed" or "failed"

   2. p has not been settled

No parameters.

Return type: Promise<BidirectionalStream>

Procedures

BidirectionalStreamEvent

The bidirectionalstream event uses the BidirectionalStreamEvent interface.

        [ Constructor (DOMString type, BidirectionalStreamEventInit eventInitDict), Exposed=Window]
interface BidirectionalStreamEvent : Event {
    readonly        attribute BidirectionalStream stream;
};

dictionary BidirectionalStreamEventInit : EventInit {
    BidirectionalStream stream;
};

Attributes

maxDatagramSize of type unsigned short, readonly

The maximum size data that may be passed to sendDatagram.

Methods

readyToSendDatagram

Returns a promise that will be resolved when the DatagramTransport can send a datagram.

When readyToSendDatagram is called, the user agent MUST run the following steps:

1. Let p be a new promise.

2. Let transport be the DatagramTransport on which readyToSendDatagram is invoked.

3. Return p and continue the following steps in the background.

1. If transport can send a datagram, imediately resolve p and abort these steps.

2. If transport's state is "failed" or "closed" immediately reject p with a newly created InvalidStateError and abort these steps.

3. If transport is blocked from sending a datagram due to congestion control, resolve p when transport is no longer blocked.

4. reject p with a newly created InvalidStateError if the transport's state transitions to "failed" or "closed".

No parameters.

Return type: Promise<void>

sendDatagram

Sends a datagram.

When sendDatagram is called, the user agent MUST run the following steps:

1. Let data be the first argument.

2. Let transport be the DatagramTransport on which sendDatagram is invoked.

3. If transport's state is not connected return a promise rejected with a newly created InvalidStateError and abort these steps.

4. If data is too large to fit into a datagram, return a promise rejected with a newly created InvalidArgumentError and abort these steps.

5. If transport is unable to send the datagram due to congestion control, return a promise rejected with a newly created InvalidStateError and abort these steps.

6. Let p be a new promise.

7. Return p and continue the following steps in the background.

1. Send data in a datagram.

2. When an ack is received for the sent datagram, resolve p with true.

3. When the datagram is detemined to be lost, resolve p with false.

Parameter	Type	Nullable	Optional	Description
data	Uint8Array	✘	✘

Return type: Promise<boolean>

receiveDatagrams

If datagrams have been received since the last call to receiveDatagrams(), return a new promise resolved with all of the received datagrams.

If not, return a new promise that will resolve when more datagrams are received, resolved with all datagrams received.

If too many datagrams are queued between calls to receiveDatagrams(), the implementation may drop datagrams and replace them with a null value in the sequence of datagrams returned in the next call to receiveDatagrams(). One null value may represent many dropped datagrams.

receiveDatagrams() may only be called once at a time. If a promised returned from a previous call is still unresolved, the user agent MUST return a new promise rejected with an InvalidStateError.

Return type: Promise<sequence<Uint8Array>>

Attributes

state of type WebTransportState, readonly

The current state of the transport. On getting, it MUST return the value of the [[\WebTransportState]] internal slot.

onstatechange of type EventHandler

This event handler, of event handler event type statechange, MUST be fired any time the [[\WebTransportState]] slot changes, unless the state changes due to calling close.

onerror of type EventHandler

This event handler, of event handler event type error, MUST be fired on reception of an error; an implementation SHOULD include error information in error.message (defined in [[!HTML51]] Section 7.1.3.8.2). This event MUST be fired before the onstatechange event.

Methods

close

Closes the WebTransport object. For QUIC, this triggers an Immediate Close as described in [[QUIC-TRANSPORT]] section 10.3.

When close is called, the user agent MUST run the following steps:

1. Let transport be the WebTransport on which close is invoked.
2. If transport's [[\WebTransportState]] is "closed" then abort these steps.
3. Set transport's [[\WebTransportState]] to "closed".
4. Let closeInfo be the first argument.
5. For QUIC, start the Immediate Close procedure by sending an CONNECTION_CLOSE frame with its error code value set to the value of closeInfo.errorCode and its reason value set to the value of closeInfo.reason.

No parameters.

Return type: void

Parameter	Type	Nullable	Optional	Description
closeInfo	WebTransportCloseInfo	✘	✘

WebTransportState Enum

WebTransportState indicates the state of the transport.

enum WebTransportState {
    "new",
    "connecting",
    "connected",
    "closed",
    "failed"
};

WebTransportCloseInfo Dictionary

The WebTransportCloseInfo dictionary includes information relating to the error code for closing a WebTransport. For QUIC, this information is used to set the error code and reason for an CONNECTION_CLOSE frame.

dictionary WebTransportCloseInfo {
    unsigned short errorCode = 0;
    DOMString reason = "";
};

Overview

A QuicTransportBase is a UnidirectionalStreamsTransport, a BidirectionalStreamsTransport, and a DatagramTransport. SendStreams and ReceiveStreams are implemented with unidirectional QUIC streams as defined in [[!QUIC-TRANSPORT]]. BidirectionalStreams are implemented with bidirectional QUIC streams as defined in [[!QUIC-TRANSPORT]]. Datagrams are implemented with QUIC datagrams as defined in [[QUIC-DATAGRAM]].

Interface Definition

interface QuicTransportBase {
};

QuicTransportBase includes UnidirectionalStreamsTransport;
QuicTransportBase includes BidirectionalStreamsTransport;
QuicTransportBase includes DatagramTransport;
QuicTransportBase includes WebTransport;

Interface Definition

[ Constructor (DOMString host, unsigned short port), Exposed=Window]
interface QuicTransport : QuicTransportBase {
};

Overview

An Http3Transport is a UnidirectionalStreamsTransport, a BidirectionalStreamsTransport, and a DatagramTransport. SendStreams, ReceiveStreams, and BidirectionalStreams are implemented with HTTP/3 streams as defined in [[WEB-TRANSPORT-HTTP3]]. Datagrams are implemented with QUIC datagrams as defined in [[WEB-TRANSPORT-HTTP3]].

Interface Definition

[ Constructor (DOMString url), Exposed=Window]
interface Http3Transport {
};

Http3Transport includes UnidirectionalStreamsTransport;
Http3Transport includes BidirectionalStreamsTransport;
Http3Transport includes DatagramTransport;
Http3Transport includes WebTransport;

Confidentiality of Communications

The fact that communication is taking place cannot be hidden from adversaries that can observe the network, so this has to be regarded as public information.

All of the transport protocols described in this document use either TLS [[TLS13]] or a semantically equivalent protocol, thus providing all of the security properties of TLS, including confidentiality and integrity of the traffic. Both QuicTransport and Http3Transport use the same certificate verification mechanism as outbound HTTP requests, thus relying on the same public key infrastructure for authentication of the remote server. In WebTransport, certificate verification errors are fatal; no interstitial allowing bypassing certificate validation is available.

State Persistence

WebTransport by itself does not create any new unique identifiers or new ways to persistently store state, nor does it automatically expose any of the existing persistent state to the server. For instance, none of the transports defined in this document automatically send cookies, support HTTP authentication or caching invalidation mechanisms. Since they use TLS, they may support TLS session tickets, which could be used by the server (though not by passive network observers) to correlate different connections from the same client. This is not specific to WebTransport by itself, but rather an inherent property of all TLS-based protocols; thus, this is out-of-scope for this specification.

Protocol Security

WebTransport imposes a common set of requirements on all of the protocols, described in [[WEB-TRANSPORT-OVERVIEW]]. Notable ones include:

1. All transports must ensure that the remote server is aware that the connection in question originates from a Web application; this is required to prevent cross-protocol attacks. QUIC-based transports use [[ALPN]] for that purpose.
2. All transports must allow the server to filter connections based on the origin of the resource originating the transport session.
3. All transports require the user agents to continually verify that the server is still interested in talking to them (concept commonly known as "Consent Freshness").

Protocol security considersations related to the individual transports are described in the Security Considerations sections of the corresponding protocol documents, [[WEB-TRANSPORT-QUIC]] and [[WEB-TRANSPORT-HTTP3]].

Networking APIs can be commonly used to scan the local network for available hosts, and thus be used for fingerprinting and other forms of attacks. WebTransport follows the WebSocket approach to this problem: the specific connection error is not returned until an endpoint is verified to be a WebTransport endpoint; thus, the Web application cannot distinguish between a non-existing endpoint and the endpoint that is not willing to accept connections from the Web.