This document defines a set of ECMAScript APIs in WebIDL to allow data to be sent and received between a browser and server, implementing pluggable protocols underneath with common APIs on top. APIs specific to QUIC are also provided. This specification is being developed in conjunction with a protocol specification developed by the IETF QUIC Working Group.

Introduction

This specification uses pluggable protocols, with QUIC [[!QUIC-TRANSPORT]] as one such protocol, to send data to and receive data from servers. It can be used like WebSockets but with support for multiple streams, unidirectional streams, out-of-order delivery, and reliable as well as unreliable transport.

The API presented in this specification represents a preliminary proposal based on work-in-progress within the IETF QUIC WG. Since the QUIC transport specification is a work-in-progress, both the protocol and API are likely to change significantly going forward.

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-1]], as this specification uses that specification and terminology.

Terminology

The EventHandler interface, representing a callback used for event handlers, and the ErrorEvent interface are defined in [[!HTML51]].

The concepts queue a task, fires a simple event and networking task source are defined in [[!HTML51]].

The term finished reading means that the application has read all available data up to the STREAM frame with the FIN bit set, which causes the [[\Readable]] slot to be set to false.

The terms event, event handlers and event handler event types are defined in [[!HTML51]].

When referring to exceptions, the terms throw and create are defined in [[!WEBIDL-1]].

The terms fulfilled, rejected, resolved, pending and settled used in the context of Promises are defined in [[!ECMASCRIPT-6.0]].

UnidirectionalStreamsTransport Mixin

A UnidirectionalStreamsTransport can send and receive unidirectional streams. Data within a stream is delivered in order, but data between streams may be delivered out of order. Data is generally sent reliably, but retransmissions may be disabled or the stream may aborted to produce a form of unreliability. All stream data is encrypted and congestion-controlled.

interface mixin UnidirectionalStreamsTransport {
  Promise<SendStream> createSendStream (optional SendStreamParameters parameters);
  attribute EventHandler    onreceivestream;
};

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

Add SendStream to the UnidirectionalStreamsTransport

To add the SendStream to the UnidirectionalStreamsTransport run the following steps:

  1. Let stream be the newly created SendStream object.

  2. Add stream to transport's [[\OutgoingStreams]] internal slot.

  3. Continue the following steps in the background.

  4. Create stream's associated underlying transport.

SendStreamParameters Dictionary

The QuicStreamParameters dictionary includes information relating to stream configuration.

dictionary SendStreamParameters {
              bool disableRetransmissions = false;
};

Dictionary SendStreamParameters Members

disableRetransmissions of type bool, defaulting to false

disableRetransmissions, with a default of false. If true, the stream will be sent without retransmissions. If false, the stream will be sent with retransmissions. If the WebTransport is unable to send without retransmissions, it may ignore this value.

ReceiveStreamEvent

The receivestream event uses the ReceiveStreamEvent interface.

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

Constructors

ReceiveStreamEvent
Parameter Type Nullable Optional Description
type DOMString
eventInitDict ReceiveStreamEventInit

Attributes

stream of type ReceiveStream, readonly

The stream attribute represents the ReceiveStream object associated with the event.

The ReceiveStreamEventInit dictionary includes information on the configuration of the stream.

dictionary ReceiveStreamEventInit : EventInit {
              ReceiveStream stream;
};

Dictionary ReceiveStreamEventInit Members

stream of type ReceiveStream

The ReceiveStream object associated with the event.

BidirectionalStreamsTransport Mixin

A BidirectionalStreamsTransport can send and receive bidirectional streams. Data within a stream is delivered in order, but data between streams may be delivered out of order. Data is generally sent reliably, but retransmissions may be disabled or the stream may aborted to produce a form of unreliability. All stream data is encrypted and congestion-controlled.

interface BidirectionalStreamsTransport {
    Promise<BidirectionalStream> createBidirectionalStream ();
    attribute EventHandler             onbidirectionalstream;
};

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

Add BidirectionalStream to the BidirectionalStreamsTransport

To add the BidirectionalStream to the BidirectionalStreamsTransport run the following steps:

  1. Let stream be the newly created BidirectionalStream object.

  2. Add stream to transport's [[\IncomingStreams]] internal slot.

  3. Add stream to transport's [[\OutgoingStreams]] internal slot.

  4. Continue the following steps in the background.

  5. Create stream's associated underlying transport.

BidirectionalStreamEvent

The bidirectionalstream event uses the BidirectionalStreamEvent interface.

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

Constructors

BidirectionalStreamEvent
Parameter Type Nullable Optional Description
type DOMString
eventInitDict BidirectionalStreamEventInit

Attributes

stream of type BidirectionalStream, readonly

The stream attribute represents the BidirectionalStream object associated with the event.

The BidirectionalStreamEventInit dictionary includes information on the configuration of the stream.

dictionary BidirectionalStreamEventInit : EventInit {
    BidirectionalStream stream;
};

Dictionary BidirectionalStreamEventInit Members

stream of type BidirectionalStream

The BidirectionalStream object associated with the event.

DatagramTransport Mixin

A DatagramTransport can send and receive datagrams. Datagrams are sent out of order, unreliably, and have a limited maximum size. Datagrams are encrypted and congestion controlled.

interface mixin DatagramTransport {
    readonly attribute unsigned short         maxDatagramSize;
    Promise<void>                        readyToSendDatagram ();
    Promise<boolean>                     sendDatagram (Uint8Array data);
    Promise<sequence<Uint8Array>> receiveDatagrams ();
};

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>>

WebTransport Mixin

The WebTransport includes the methods common to all transports, such as state, state changes, and the ability to close the transport.

interface mixin WebTransport {
  readonly attribute WebTransportState state;
  void                                  close (WebTransportCloseInfo closeInfo);
           attribute EventHandler       onstatechange;
           attribute EventHandler       onerror;
};

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"
};
Enumeration description
new

The WebTransport object has been created and has not started negotiating yet.

connecting

The transport is in the process of negotiating a secure connection. Once a secure connection is negotiated, incoming data can flow through.

connected

The transport has completed negotiation of a secure connection. Outgoing data and media can now flow through.

closed

The transport has been closed intentionally via a call to close() or receipt of a closing message from the remote side. When the WebTransport's internal [[\WebTransportState]] slot transitions to closed the user agent MUST run the following steps:

  1. Let transport be the WebTransport.
  2. For each IncomingStream in transport's [[\IncomingStreams]] internal slot run the following:
    1. Let stream be the IncomingStream.
    2. Set stream's [[\Readable]] slot to false.
    3. Clear the stream's read buffer.
    4. Remove the stream from the transport's [[\IncomingStreams]] internal slot.
  3. For each OutgoingStream in transport's [[\OutgoingStreams]] internal slot run the following:
    1. Let stream be the OutgoingStream.
    2. Set stream's [[\Writable]] slot to false.
    3. Clear the stream's write buffer.
    4. Remove the stream from the transport's [[\OutgoingStreams]] internal slot.
failed

The transport has been closed as the result of an error (such as receipt of an error alert). When the WebTransport's internal [[\WebTransportState]] slot transitions to failed the user agent MUST run the following steps:

  1. Let transport be the WebTransport.
  2. For each IncomingStream in transport's [[\IncomingStreams]] internal slot run the following:
    1. Let stream be the IncomingStream.
    2. Set stream's [[\Readable]] slot to false.
    3. Clear the stream's read buffer.
    4. Remove the stream from the transport's [[\IncomingStreams]] internal slot.
  3. For each OutgoingStream in transport's [[\OutgoingStreams]] internal slot run the following:
    1. Set stream's [[\Writable]] slot to false.
    2. Clear the stream's write buffer.
    3. Remove the stream from the transport's [[\OutgoingStreams]] internal slot.

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 = "";
};

Dictionary WebTransportCloseInfo Members

errorCode of type unsigned short, defaulting to 0.

The error code.

reason of type DOMString, defaulting to ""

The reason for closing the WebTransport

QuicTransportBase Interface

The QuicTransportBase is the base interface for QuicTransport. Most of the functionality of a QuicTransport is in the base class to allow for other subclasses (such as a p2p variant) to share the same interface.

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;

QuicTransport Interface

The QuicTransport is a subclass of QuicTransportBase focused on client/server use cases.

Interface Definition

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

Constructors

When the QuicTransport constructor is invoked, the user agent MUST run the following steps:
  1. If port is 0, throw an NotSupportedError and abort these steps.
  2. Let transport be a newly constructed QuicTransport object.
  3. Let transport have a [[\OutgoingStreams]] internal slot representing a sequence of OutgoingStream objects, initialized to empty.
  4. Let transport have a [[\IncomingStreams]] internal slot representing a sequence of IncomingStream objects, initialized to empty.
  5. Let transport have a [[\WebTransportState]] internal slot, initialized to "connecting".
  6. Let transport have a [[\ReceivedDatagrams]] internal slot representing a queue of Uint8Array, initialized to empty.
  7. Let transport have a [[\ReceiveDatagramsPromise]] internal slot representing a Promise<sequence<Uint8Array>>?, initialized to null.
  8. Run these steps in parallel:
    1. Let clientOrigin be transport's relevant settings object's origin, serialized.
    2. Establish a QUIC connection to the address identified by the given host and port following the procedures in [[WEB-TRANSPORT-QUIC]] section 3 and using clientOrigin as the "origin of the client" referenced in section 3.2.
    3. If the connection fails, set transport's [[\WebTransportState]] internal slot to "failed" and abort these steps.
    4. Set transport's [[\WebTransportState]] internal slot to "connected".
  9. Return transport.
QuicTransport
Parameter Type Nullable Optional Description
host DOMString The host to connect to.
port unsigned short The port to connect to.

Interface Mixin OutgoingStream

An OutgoingStream is a stream that can be written to, as either a SendStream or a BidirectionalStream

      [ Exposed=Window ]
interface mixin OutgoingStream {
    readonly attribute boolean writable;
    readonly attribute unsigned long writeBufferedAmount;
    readonly attribute Promise<StreamAbortInfo> writingAborted;
    void write (StreamWriteParameters data);
    void abortWriting (StreamAbortInfo abortInfo);
    Promise<void> waitForWriteBufferedAmountBelow(unsigned long threshold);
};

Overview

The OutgoingStream will initialize with the following:

  1. Let stream be the OutgoingStream.
  2. Let stream have a [[\Writable]] internal slot initialized to true.
  3. Let stream have a [[\WriteBufferedAmount]] internal slot initialized to zero.

Attributes

writable of type boolean readonly

The writable attribute represents whether data can be written to the OutgoingStream. On getting it MUST return the value of the [[\Writable]] slot.

writeBufferedAmount of type unsigned long, readonly

The writeBufferedAmount attribute represents the number of bytes of application data that have been queued using write but that, as of the last time the event loop started executing a task, had not yet been transmitted to the network. This includes any data sent during the execution of the current task, regardless of whether the user agent is able to transmit text asynchronously with script execution. This does not include framing overhead incurred by the protocol, or buffering done by the operating system or network hardware. On getting, it MUST return the value of the OutgoingStream's [[\WriteBufferedAmount]] internal slot.

writingAborted of type StreamAbortInfo readonly

The writingAborted attribute represents a promise that resolves when the a message from the remote side aborting the stream is received. For QUIC, that message is a STOP_SENDING frame. When the stream receives this mesage, the user agent MUST run the following:

  1. Let stream be the OutgoingStream object.
  2. Set stream's [[\Writable]] slot to false.
  3. Clear the stream's write buffer.
  4. Let transport be the WebTransport, which the stream was created from.
  5. Remove the stream from the transport's [[\OutgoingStreams]] internal slot.
  6. resolve the promise with the resulting StreamAbortInfo with the errorCode set to the value from the aborting message from the remote side.

Methods

write

Buffer the given data to be written to the network when possible. When the remote WebTransport receives data for this stream for the first time, it will trigger the creation of the corresponding remote IncomingStream. When the write method is called, the user agent MUST run the following steps:

  1. Let data be the first argument.
  2. Let stream be the OutgoingStream object on which data is to be sent.
  3. if length of data.data is 0 and data.finished is false, throw a NotSupportedError and abort these steps.
  4. If stream's [[\Writable]] slot is false, throw an InvalidStateError and abort these steps.
  5. Increase the value of stream's [[\WriteBufferedAmount]] slot by the length of data.data in bytes.
  6. Queue data.data for transmission on stream's underlying transport.
  7. if data.finish is set to true, run the following:
    1. Queue a message with an indication that this is the last data for the stream ( for QUIC, this is a STREAM frame with the FIN bit set.)
    2. Set stream's [[\Writable]] slot to false.
    3. Let transport be the WebTransport, which the stream was created from.
    4. Remove the stream from the transport's [[\OutgoingStreams]] internal slot.
    The actual transmission of data occurs in parallel. If sending data leads to a transport-level error, the application will be notified asynchronously through the WebTransport's onerror EventHandler.
Parameter Type Nullable Optional Description
data StreamWriteParameters
Return type: void
abortWriting

A hard shutdown of the OutgoingStream. It may be called regardless of whether the OutgoingStream was created by the local or remote peer. When the abortWriting() method is called, the user agent MUST run the following steps:

  1. Let stream be the OutgoingStream object which is about to abort writing.
  2. If stream's [[\Writable]] slot is false, throw an InvalidStateError and abort these steps.
  3. Set stream's [[\Writable]] slot to false.
  4. Clear the stream's write buffer.
  5. Let transport be the WebTransport, which the stream was created from.
  6. Remove the stream from the transport's [[\OutgoingStreams]] internal slot.
  7. Let abortInfo be the first argument.
  8. Start the closing procedure by sending a RST_STREAM frame with its error code set to the value of abortInfo.errorCode.
Parameter Type Nullable Optional Description
abortInfo StreamAbortInfo
Return type: void
waitForWriteBufferedAmountBelow

waitForWriteBufferedAmountBelow resolves the promise when the data queued in the write buffer falls below the given threshold. If waitForWriteBufferedAmountBelow is called multiple times, multiple promises could be resolved when the write buffer falls below the threshold for each promise. The Promise will be rejected with a newly created InvalidStateError if the stream's [[\Writable]] slot transitions from true to false and the promise isn't settled. When the waitForWriteBufferedAmountBelow method is called, the user agent MUST run the following steps:

  1. Let stream be the OutgoingStream object on which waitForWriteBufferedAmountBelow was invoked.
  2. Let p be a new promise.
  3. If stream's [[\Writable]] slot is false, reject p with a newly created InvalidStateError and abort these steps.
  4. Let threshold be the first argument.
  5. When stream's [[\WriteBufferedAmount]]] slot decreases from above threshold to less than or equal to it, resolve p with undefined.
Parameter Type Nullable Optional Description
threshold unsigned long
Return type: Promise<void>

StreamWriteParameters Dictionary

The StreamWriteParameters dictionary includes information relating to the data to be written with OutgoingStream.write.

dictionary StreamWriteParameters {
  Uint8Array data;
  boolean finished = false;
};

Dictionary StreamWriteParameters Members

data of type Uint8Array.

The data to be written.

finished of type boolean.

Set to true if this is the last data to be written. For QUIC, this will result in a STREAM frame with the FIN bit set.

StreamAbortInfo Dictionary

The StreamAbortInfo dictionary includes information relating to the error code for aborting an incoming or outgoing stream. (For QUIC, in either a RST_STREAM frame or a STOP_SENDING frame).

dictionary StreamAbortInfo {
                unsigned short errorCode = 0;
          };
          

Dictionary StreamAbortInfo Members

errorCode of type unsigned short.

The error code. The default value of 0 means "CLOSING."

Interface Mixin IncomingStream

An IncomingStream is a stream that can be read from, as either a ReceiveStream or a BidirectionalStream

[ Exposed=Window ]
interface mixin IncomingStream {
    readonly attribute boolean readable;
    readonly attribute unsigned long readableAmount;
    readonly attribute Promise<StreamAbortInfo> readingAborted;
    StreamReadResult readInto (Uint8Array data);
    void abortReading (StreamAbortInfo abortInfo);
    Promise<void>   waitForReadable(unsigned long amount);
};

Overview

The IncomingStream will initialize with the following:

  1. Let stream be the IncomingStream.
  2. Let stream have a [[\Readable]] internal slot initialized to true.
  3. Let stream have a [[\ReadableAmount]] internal slot initialized to zero.

Attributes

readable of type boolean, readonly

The readable attribute represents whether data can be read from the IncomingStream. On getting, it MUST return the value of the IncomingStream's [[\Readable]] slot.

readableAmount of type unsigned long, readonly

The readableAmount attribute represents the number of bytes buffered for access by readInto but that, as of the last time the event loop started executing a task, had not yet been read. This does not include framing overhead incurred by the protocol, or buffers associated with the network hardware. On getting, it MUST return the value of the IncomingStream's [[\ReadableAmount]] internal slot.

readingAborted of type StreamAbortInfo readonly

The readingAborted attribute represents a promise that resolves when the a message is received inidicating the remote side aborted the stream. For QUIC, this is a RST_STREAM frame. When the stream receives this message, the user agent MUST run the following:

  1. Let stream be the IncomingStream object for which the abort message was received.
  2. Set stream's [[\Readable]] slot to false.
  3. Clear the stream's read buffer.
  4. Let transport be the WebTransport, which the stream was created from.
  5. Remove the stream from the transport's [[\IncomingStreams]] internal slot.
  6. resolve the promise with the resulting StreamAbortInfo with errorCode set to the value of the errror code from the abot message.

Methods

readInto

Reads from the IncomingStream into the buffer specified by the first argument and returns StreamReadResult. When the readInto method is called, the user agent MUST run the following steps:

  1. Let stream be the IncomingStream object on which readInto is invoked.
  2. If stream's [[\Readable]] slot is false, throw an InvalidStateError, then abort these steps.
  3. Let data be the first argument.
  4. Let result be the StreamReadResult to be returned.
  5. If stream has finished reading, return result with amount set to 0 and finished set to true and abort these steps.
  6. Transfer data from the read buffer into data.
  7. Decrease the value of stream's [[\ReadableAmount]] slot by the length of data in bytes.
  8. Set result's amount to the size of data in bytes.
  9. If the data includes up to the indication of the end of the stream (for QUIC, the FIN bit), then run the following steps:
    1. Set result's finished to true.
    2. Set the stream's [[\Readable]] slot to false.
    3. Let transport be the WebTransport, which the stream was created from.
    4. Remove the stream from the transport's [[\IncomingStreams]] internal slot.
  10. Else, set result's finished to false.
  11. Return result.
Parameter Type Nullable Optional Description
data Uint8Array
Return type: StreamReadResult
abortReading

A hard shutdown of the IncomingStream. It may be called regardless of whether the IncomingStream object was created by the local or remote peer. When the abortReading() method is called, the user agent MUST run the following steps:

  1. Let stream be the IncomingStream object which is about to abort reading.
  2. If stream's [[\Readable]] slot is false, throw an InvalidStateError and abort these steps.
  3. Set stream's [[\Readable]] slot to false.
  4. Clear the stream's read buffer.
  5. Let transport be the WebTransport, which the stream was created from.
  6. Remove the stream from the transport's [[\IncomingStreams]] internal slot.
  7. Let abortInfo be the first argument.
  8. Start the closing procedure by sending a message to the remote side indicating that the stream has been aborted (for QUIC, this is a STOP_SENDING frame) with its error code set to the value of abortInfo.errorCode.
Parameter Type Nullable Optional Description
abortInfo StreamAbortInfo
Return type: void
waitForReadable

waitForReadable waits for data to become available, or for the IncomingStream to be finished reading. It resolves the promise when the data queued in the read buffer increases above the amount provided as an argument or when a message is received with an end indication (for QUIC, a STREAM frame with the FIN bit set). If waitForReadable is called multiple times, multiple promises could be resolved. The Promise will be rejected with a newly created InvalidStateError if the stream's [[\Readable]] slot transitions from true to false and the promise isn't settled. When the waitForReadable method is called, the user agent MUST run the following steps:

  1. Let stream be the IncomingStream on which waitForReadable is invoked.
  2. Let p be a new promise.
  3. If stream's [[\Readable]] slot is false, reject p with a newly created InvalidStateError and abort these steps.
  4. Let amount be the first argument.
  5. Resolve p with undefined when any of the following conditions are met:
    1. The [[\ReadableAmount]] increases from below the value of amount to greater than or equal to it.
    2. stream receives a STREAM frame with the FIN bit set and [[\ReadableAmount]] is less than amount.
Parameter Type Nullable Optional Description
amount unsigned long
Return type: Promise<void>

StreamReadResult Dictionary

The StreamReadResult dictionary includes information relating to the result returned from readInto.

dictionary StreamReadResult {
                unsigned long amount;
                boolean finished = false;
          };
          

Dictionary StreamReadResult Members

amount of type unsigned long.

The amount of data read in bytes.

finished of type boolean.

Set to true if the IncomingStream has finished reading.

Interface WebTransportStream

A collection of common attributes and methods of all streams.

      [ Exposed=Window ]
      interface WebTransportStream {
          readonly attribute unsigned long long streamId;
          readonly attribute WebTransport transport;
      };
      

Attributes

streamId of type unsigned long long, readonly

The readonly attribute referring to the ID of the TransportStream object.

transport of type WebTransport, readonly

The readonly attribute referring to the related WebTransport object.

Interface BidirectionalStream

      [ Exposed=Window ]
      interface BidirectionalStream : WebTransportStream {
      };
      BidirectionalStream includes OutgoingStream;
      BidirectionalStream includes IncomingStream;
      

Interface SendStream

      [ Exposed=Window ]
      interface SendStream : WebTransportStream {
      };
      SendStream includes OutgoingStream;
      

Interface ReceiveStream

      [ Exposed=Window ]
      interface ReceiveStream : WebTransportStream {
      };
      ReceiveStream includes IncomingStream;
      

Http3Transport Interface

The Http3Transport is ***

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;

Constructors

When the Http3Transport constructor is invoked, the user agent MUST run the following steps:
  1. Let transport be a newly constructed Http3Transport object with state "connecting".
  2. Let transport have a [[\OutgoingStreams]] internal slot representing a sequence of OutgoingStream objects, initialized to empty.
  3. Let transport have a [[\IncomingStreams]] internal slot representing a sequence of IncomingStream objects, initialized to empty.
  4. Let transport have a [[\ReceivedDatagrams]] internal slot representing a queue of Uint8Array, initialized to empty.
  5. Let transport have a [[\ReceiveDatagramsPromise]] internal slot representing a Promise<sequence<Uint8Array>>?, initialized to null.
  6. Run these steps in parallel:
    1. Either establish an HTTP/3 connection or reuse an existing HTTP/3 connection to the host specificed by the url, as specified in [[WEB-TRANSPORT-HTTP3]].
    2. If there is no such HTTP/3 connection to reuse and the establishment of a new HTTP/3 connection, set transport's [[\WebTransportState]] internal slot to "failed" and abort these steps.
    3. Once a connection an HTTP/3 connection is established, follow the steps specified in [[WEB-TRANSPORT-HTTP3]] section 4 for establishing a WebTransport session within the HTTP/3 connection.
    4. If the establishment of the WebTransport session fails, set transport's [[\WebTransportState]] internal slot to "failed" and abort these steps.
    5. Once a session has been established, set transport's [[\WebTransportState]] internal slot to "connected" and abort these steps.
  7. Return transport.
Http3Transport
Parameter Type Nullable Optional Description
url DOMString The url specifying the host to connect to and the path to pass to it.

Privacy and Security Considerations

This section is non-normative; it specifies no new behaviour, but instead summarizes information already present in other parts of the specification.

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.

Since the QUIC protocol utilizes a cryptographic negotiation based on TLS 1.3 [[TLS13]] in order to encrypt communications, it provides confidentiality.

Event summary

The following events fire on transport objects:

Event name Interface Fired when...
error ErrorEvent The WebTransport object has encountered an error.
statechange Event The WebTransportState changed.
receivestream ReceiveStreamEvent A new ReceiveStream is dispatched to the script in response to the remote peer creating a send-only stream and sending data on it. Prior to receivestream firing, the ReceiveStream is added to WebTransport's [[\IncomingStreams]] internal slot.
bidirectionalstream BidirectionalStreamEvent A new BidirectionalStream is dispatched to the script in response to the remote peer creating a bidirectional stream and sending data on it. Prior to bidirectionalstream firing, the BidirectionalStream is added to the WebTransport's [[\IncomingStreams]] and [[\OutgoingStreams]] internal slots.

Examples

Unreliable delivery

Unreliable delivery can be achieved by creating many streams with retransmissions disabled, each transporting a single small message.

let transport = getTransport();
let messages = getMessages();
for (msg in messages) {
  transport.createSendStream({disableRetransmissions: true}).write({data: msg, finished: true});
}

Sending a buffer of datagrams

Sending a buffer of datagrams can be achieved by using the sendDatagram and readyToSendDatagram methods. In the following example datagrams are only sent if the DatagramTransport is ready to send, however the sending is not blocked on the ACK promise returned from sendDatagram (these are ignored in this example).

const transport = getTransport();
const datagrams = getDatagramsToSend();
datagrams.forEach((datagram) => {
  await transport.readyToSendDatagram();
  transport.sendDatagram(datagram);
});

Sending datagrams at a fixed rate

Sending datagrams at a fixed rate regardless if the transport is ready to send can be achieved by simply using sendDatagram and not using the readyToSendDatagram method. More complex scenarios can utilize the readyToSendDatagram method.

// Sends datagrams every 100 ms.
const transport = getTransport();
setInterval(() => {
  transport.sendDatagram(createDatagram());
}, 100);

Receiving datagrams

Receiving datagrams can be achieved by calling receiveDatagrams() method, remembering to check for null values indicating that packets are not being processed quickly enough.

      const transport = getTransport();
      const datagrams = await transport.receiveDatagrams();
      for (let data of datagrams) {
        if (data == null) {
          // Log that datagrams were lost. Look into making the event handler faster
          // or reducing the send rate of the remote side.
        } else {
          // Process the data
        }
      };
      

Change Log

This section will be removed before publication.

Acknowledgements

The editors wish to thank the Working Group chairs and Team Contact, Harald Alvestrand, Stefan Håkansson, Bernard Aboba and Dominique Hazaël-Massieux, for their support. Contributions to this specification were provided by Robin Raymond.

The QuicTransport and QuicStream objects were initially described in the W3C ORTC CG, and have been adapted for use in this specification.