This document defines a set of ECMAScript APIs in WebIDL to allow data to be sent and received from another browser or device implementing the QUIC protocol. This specification is being developed in conjunction with a protocol specification developed by the IETF QUIC Working Group.

The API is based on preliminary work done in the W3C ORTC Community Group.

Introduction

This specification extends the WebRTC specification [[!WEBRTC]] to enable the use of QUIC [[!QUIC-TRANSPORT]] to exchange arbitrary data with remote peers using NAT-traversal technologies such as ICE, STUN, and TURN. Since QUIC can be multiplexed on the same port as RTP, RTCP, DTLS, STUN and TURN, this specification is compatible with all the functionality defined in [[!WEBRTC]], including communication using audio/video media and SCTP data channels.

While this specification defines an interface to QUIC streams, by utilizing a QUIC stream per message, it is possible to implement support for message-based communications (such as RTCDataChannel) on top. While the QUIC transport defined in [[!QUIC-TRANSPORT]] is reliable, support for unreliable communications is achievable via use of timers or through future extensions to the QUIC protocol.

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

The RTCIceTransport and RTCCertificate interfaces and the RTCDtlsFingerprint dictionary are defined in [[!WEBRTC]].

RTCQuicTransport Interface

The RTCQuicTransport includes information relating to QUIC transport.

Overview

An RTCQuicTransport instance can be associated to one or more RTCQuicBidirectionalStream, RTCQuicSendStream, or RTCQuicReceiveStream instances.

The QUIC API presented in this and the subsequent section 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.

Operation

The QUIC transport protocol is described in [[!QUIC-TRANSPORT]]. A RTCQuicTransport instance is constructed using an RTCIceTransport and an optional sequence of RTCCertificate objects. An RTCQuicTransport object in the "closed" or "failed" states can be garbage-collected when it is no longer referenced.

The QUIC negotiation occurs between transport endpoints determined via ICE. Multiplexing of QUIC with STUN, TURN, DTLS, RTP and RTCP is supported within [[QUIC-TRANSPORT]].

A newly constructed RTCQuicTransport MUST listen and respond to incoming QUIC packets before start() is called. However, to complete the negotiation it is necessary to verify the remote fingerprint by computing fingerprints for the selected remote certificate using the digest algorithms provided in remoteParameters.fingerprints[].algorithm. If a calculated fingerprint and algorithm matches a fingerprint and algorithm included in remoteParameters.fingerprints[], the remote fingerprint is verified. After the QUIC handshake exchange completes (but before the remote fingerprint is verified) incoming media packets may be received. A modest buffer MUST be provided to avoid loss of media prior to remote fingerprint validation (which can begin after start() is called).

Interface Definition

        [ Constructor (RTCIceTransport transport, optional sequence<RTCCertificate> certificates), Exposed=Window]
interface RTCQuicTransport : RTCStatsProvider {
    readonly        attribute RTCIceTransport          transport;
    readonly        attribute RTCQuicTransportState    state;
    RTCQuicParameters     getLocalParameters ();
    RTCQuicParameters?    getRemoteParameters ();
    sequence<RTCCertificate> getCertificates ();
    sequence<ArrayBuffer> getRemoteCertificates ();
    void                  start (RTCQuicParameters remoteParameters);
    void                  stop ();
    RTCQuicBidirectionalStream         createBidirectionalStream ();
    RTCQuicSendStream                  createSendStream ();
                    attribute EventHandler             onstatechange;
                    attribute EventHandler             onerror;
                    attribute EventHandler             onreceivestreamwithdata;
                    attribute EventHandler             onbidirectionalstreamwithdata;
};

Constructors

When the RTCQuicTransport constructor is invoked, the user agent MUST run the following steps:
  1. Let transport be the first argument.
  2. If transport is in the "closed" state, throw an InvalidStateError and abort these steps.
  3. If transport has been used to construct another RTCQuicTransport whose [[\QuicTransportState]] slot is not "closed", throw an InvalidStateError and abort these steps.
  4. Let certificates be the second argument if provided, null otherwise.
  5. If certificates is non-null and is non-empty, check that the expires attribute of each RTCCertificate object is in the future. If a certificate has expired, throw an InvalidAccessError and abort these steps.
  6. Let quictransport be a newly constructed RTCQuicTransport object.
  7. Let quictransport have a [[\QuicTransportWritableStreams]] internal slot representing a sequence of RTCQuicWritableStream objects, initialized to empty.
  8. Let quictransport have a [[\QuicTransportReadableStreams]] internal slot representing a sequence of RTCQuicReadableStream objects, initialized to empty.
  9. Let quictransport have a [[\QuicTransportState]] internal slot, initialized to "new".
  10. Let quictransport have a [[\Certificates]] internal slot.
  11. If certificates is non-null and is non-empty, initialize the [[\Certificates]] internal slot to certificates.
  12. If certificates is null or is empty, generate a certificate using the default key generation algorithm and store it in the [[\Certificates]] internal slot.
  13. Return quictransport.
RTCQuicTransport
Parameter Type Nullable Optional Description
transport RTCIceTransport
certificates sequence<RTCCertificate>

Attributes

transport of type RTCIceTransport, readonly

The associated RTCIceTransport instance.

state of type RTCQuicTransportState, readonly

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

onstatechange of type EventHandler

This event handler, of event handler event type statechange, MUST be fired any time the [[\QuicTransportState]] slot changes.

onerror of type EventHandler

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

onreceivestreamwithdata of type EventHandler

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

onbidirectionalstreamwithdata of type EventHandler

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

Methods

getLocalParameters

getLocalParameters() obtains the QUIC parameters of the local RTCQuicTransport upon construction. If multiple certificates were provided in the constructor, then multiple fingerprints will be returned, one for each certificate. getLocalParameters().role always returns the default role of a newly constructed RTCQuicTransport; for a browser this will be auto.

No parameters.
Return type: RTCQuicParameters
getRemoteParameters

getRemoteParameters() obtains the remote QUIC parameters passed in the start() method. Prior to calling start(), null is returned.

No parameters.
Return type: RTCQuicParameters, nullable
getCertificates

getCertificates() returns the value of the RTCQuicTransport's [[\Certificates]]> internal slot.

No parameters.
Return type: sequence<RTCCertificate>
getRemoteCertificates

getRemoteCertificates() returns the certificate chain in use by the remote side, with each certificate encoded in binary Distinguished Encoding Rules (DER) [[!X690]]. getRemoteCertificates() returns an empty list prior to selection of the remote certificate, which is completed once RTCQuicTransportState transitions to connected.

No parameters.
Return type: sequence<ArrayBuffer>
start

Start QUIC transport negotiation with the parameters of the remote QUIC transport, including verification of the remote fingerprint. Only a single QUIC transport can be multiplexed over an ICE transport. Therefore if a RTCQuicTransport object quicTransportB is constructed with an RTCIceTransport object iceTransport previously used to construct another RTCQuicTransport object quicTransportA, then if quicTransportB.start() is called prior to having called quicTransportA.stop(), then throw an InvalidStateError.

If start is called after a previous start call, or if state is closed, throw an InvalidStateError.

If all of the values of remoteParameters.fingerprints[j].algorithm are unsupported, where j goes from 0 to the number of fingerprints, throw a NotSupportedError.

Parameter Type Nullable Optional Description
remoteParameters RTCQuicParameters
Return type: void
stop

Stops and closes the RTCQuicTransport object. This triggers an "Immediate Close," as described in [[QUIC-TRANSPORT]] section 6.13.3.

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

  1. Let transport be the RTCQuicTransport on which stop is invoked.
  2. If transport's [[\QuicTransportState]] is "closed" then abort these steps.
  3. Set transport's [[\QuicTransportState]] to "closed".
  4. Start the "Immediate Close" procedure by sending an APPLICATION_CLOSE frame.
No parameters.
Return type: void
createBidirectionalStream

Creates an RTCQuicBidirectionalStream object. Since [[QUIC-TRANSPORT]] only defines reliable QUIC streams, createBidectionalStream only supports creation of reliable streams.

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

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

  2. If transport's state is not connected throw an InvalidStateError and abort these steps.

  3. Let stream be a newly created RTCQuicBidirectionalStream object.

  4. Add stream to transport's [[\QuicTransportWritableStreams]] internal slot.

  5. Add stream to transport's [[\QuicTransportReadableStreams]] internal slot.

  6. Return stream and continue the following steps in the background.

  7. Create stream's associated underlying data transport.

No parameters.
createSendStream

Creates an RTCQuicSendStream object. Since [[QUIC-TRANSPORT]] only defines reliable QUIC streams, createSendStream only supports creation of reliable streams.

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

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

  2. If transport's state is not connected throw an InvalidStateError and abort these steps.

  3. Let stream be a newly created RTCQuicSendStream object.

  4. Add stream to transport's [[\QuicTransportWritableStreams]] internal slot.

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

  6. Create stream's associated underlying data transport.

No parameters.
Return type: RTCQuicSendStream

RTCQuicParameters Dictionary

The RTCQuicParameters dictionary includes information relating to QUIC configuration.

dictionary RTCQuicParameters {
             RTCQuicRole                  role = "auto";
             sequence<RTCDtlsFingerprint> fingerprints;
};

Dictionary RTCQuicParameters Members

role of type RTCQuicRole, defaulting to "auto"

The QUIC role, with a default of auto.

fingerprints of type sequence<RTCDtlsFingerprint>

Sequence of fingerprints, at least one fingerprint for each certificate (with one computed with the digest algorithm used in the certificate signature).

ReceiveStreamWithDataEvent

The receivestreamwithdata event uses the ReceiveStreamWithDataEvent interface.

        [ Constructor (DOMString type, ReceiveStreamWithDataEventInit eventInitDict), Exposed=Window]
interface ReceiveStreamWithDataEvent : Event {
    readonly        attribute RTCQuicReceiveStream stream;
};

Constructors

ReceiveStreamWithDataEvent
Parameter Type Nullable Optional Description
type DOMString
eventInitDict ReceiveStreamWithDataEventInit

Attributes

stream of type RTCQuicReceiveStream, readonly

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

The ReceiveStreamWithDataEventInit dictionary includes information on the configuration of the QUIC stream.

dictionary ReceiveStreamWithDataEventInit : EventInit {
             RTCQuicReceiveStream stream;
};

Dictionary ReceiveStreamWithDataEventInit Members

stream of type RTCQuicReceiveStream

The RTCQuicReceiveStream object associated with the event.

BidirectionalStreamWithDataEvent

The bidirectionalstreamwithdata event uses the BidirectionalStreamWithDataEvent interface.

        [ Constructor (DOMString type, BidirectionalStreamWithDataEventInit eventInitDict), Exposed=Window]
interface BidirectionalStreamWithDataEvent : Event {
    readonly        attribute RTCQuicBidirectionalStream stream;
};

Constructors

BidirectionalStreamWithDataEvent
Parameter Type Nullable Optional Description
type DOMString
eventInitDict BidirectionalStreamWithDataEventInit

Attributes

stream of type RTCQuicBidirectionalStream, readonly

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

The BidirectionalStreamWithDataEventInit dictionary includes information on the configuration of the QUIC stream.

dictionary BidirectionalStreamWithDataEventInit : EventInit {
             RTCQuicBidirectionalStream stream;
};

Dictionary BidirectionalStreamWithDataEventInit Members

stream of type RTCQuicBidirectionalStream

The RTCQuicBidirectionalStream object associated with the event.

RTCQuicRole Enum

RTCQuicRole indicates the role of the QUIC transport.

enum RTCQuicRole {
    "auto",
    "client",
    "server"
};
Enumeration description
auto

The QUIC role is determined based on the resolved ICE role: the ICE controlled role acts as the QUIC client and the ICE controlling role acts as the QUIC server.

client

The QUIC client role.

server

The QUIC server role.

QUIC role determination

To diagnose QUIC role issues, an application may wish to determine the desired and actual QUIC role of an RTCQuicTransport. For a browser implementing ORTC, a RTCQuicTransport object assumes a QUIC role of auto upon construction. This implies that the QUIC role is determined by the ICE role. Since getLocalParameters().role always returns the role assigned to an RTCQuicTransport object upon construction (auto for a browser), the getLocalParameters method cannot be used to determine the desired or actual role of an RTCQuicTransport.

An application can determine the desired role of an RTCQuicTransport from the value of remoteParameters.role passed to RTCQuicTransport.start(remoteParameters). If remoteParameters.role is server then the desired role of the RTCQuicTransport is client. If remoteParameters.role is client then the desired role of the RTCQuicTransport is server.

The RTCQuicTransport.transport.onstatechange EventHandler can be used to determine whether an RTCQuicTransport transitions to the desired role. When RTCQuicTransport.transport.state transitions to connected, if RTCQuicTransport.transport.role is controlled then the role of the RTCQuicTransport is client. If RTCQuicTransport.transport.role is controlling then the role of the RTCQuicTransport is server.

RTCQuicTransportState Enum

RTCQuicTransportState indicates the state of the QUIC transport.

enum RTCQuicTransportState {
    "new",
    "connecting",
    "connected",
    "closed",
    "failed"
};
Enumeration description
new

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

connecting

QUIC is in the process of negotiating a secure connection and verifying the remote fingerprint. Once a secure connection is negotiated (but prior to verification of the remote fingerprint, enabled by calling start()), incoming data can flow through.

connected

QUIC has completed negotiation of a secure connection and verified the remote fingerprint. Outgoing data and media can now flow through.

closed

The QUIC connection has been closed intentionally via a call to stop() or receipt of a closing frame as described in [[QUIC-TRANSPORT]]. When the RTCQuicTransport's internal [[\QuicTransportState]] slot transitions to closed the user agent MUST run the following steps:

  1. Let transport be the RTCQuicTransport.
  2. For each RTCQuicReadableStream in transport's [[\QuicTransportReadableStreams]] internal slot run the following:
    1. Let stream be the RTCQuicReadableStream.
    2. Set stream's [[\Readable]] slot to false.
    3. Clear the stream's read buffer.
    4. Remove the stream from the transport's [[\QuicTransportReadableStreams]] internal slot.
  3. For each RTCQuicWritableStream in transport's [[\QuicTransportWritableStreams]] internal slot run the following:
    1. Let stream be the RTCQuicWritableStream.
    2. Set stream's [[\Writable]] slot to false.
    3. Clear the stream's write buffer.
    4. Remove the stream from the transport's [[\QuicTransportWritableStreams]] internal slot.
failed

The QUIC connection has been closed as the result of an error (such as receipt of an error alert or a failure to validate the remote fingerprint). When the RTCQuicTransport's internal [[\QuicTransportState]] slot transitions to failed the user agent MUST run the following steps:

  1. Let transport be the RTCQuicTransport.
  2. For each RTCQuicReadableStream in transport's [[\QuicTransportReadableStreams]] internal slot run the following:
    1. Let stream be the RTCQuicReadableStream.
    2. Set stream's [[\Readable]] slot to false.
    3. Clear the stream's read buffer.
    4. Remove the stream from the transport's [[\QuicTransportReadableStreams]] internal slot.
  3. For each RTCQuicWritableStream in transport's [[\QuicTransportWritableStreams]] internal slot run the following:
    1. Let stream be the RTCQuicWritableStream.
    2. Set stream's [[\Writable]] slot to false.
    3. Clear the stream's write buffer.
    4. Remove the stream from the transport's [[\QuicTransportWritableStreams]] internal slot.

QUIC Stream API

The QUIC Stream API includes information relating to a QUIC stream.

Overview

RTCQuicBidirectionalStream, RTCQuicSendStream, and RTCQuicReceiveStream instances are associated to a RTCQuicTransport instance.

Operation

A RTCQuicBidirectionalStream can be created in the following ways:

  1. Using the RTCQuicTransport.createBidirectionalStream
  2. Getting a bidirectionalstreamwithdata event on the RTCQuicTransport

A RTCQuicSendStream can be created in the following ways:

  1. Using the RTCQuicTransport.createSendStream

A RTCQuicReceiveStream can be created in the following ways:

  1. Getting a receivestreamwithdata event on the RTCQuicTransport

Interface Mixin RTCQuicWritableStream

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

Overview

The RTCQuicWritableStream will initialize with the following:

  1. Let stream be the RTCQuicWritableStream.
  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 RTCQuicWritableStream. 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 RTCQuicWritableStream's [[\WriteBufferedAmount]] internal slot.

writingAborted of type RTCQuicStreamAbortInfo readonly

The writingAborted attribute represents a promise that resolves when the STOP_SENDING frame is received from the RTCQuicReadableStream. When the stream receives a STOP_SENDING frame from its corresponding RTCQuicReadableStream, the user agent MUST run the following:

  1. Let stream be the RTCQuicWritableStream object.
  2. Set stream's [[\Writable]] slot to false.
  3. Clear the stream's write buffer.
  4. Let transport be the RTCQuicTransport, which the stream was created from.
  5. Remove the stream from the transport's [[\QuicTransportWritableStreams]] internal slot.
  6. resolve the promise with the resulting RTCQuicStreamAbortInfo with the errorCode set to the value from the STOP_SENDING frame.

Methods

write

Writes data to the stream. When the remote RTCQuicTransport receives the STREAM frame from this stream for the first time, it will trigger the creation of the corresponding remote stream. 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 RTCQuicWritableStream 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 data transport.
  7. if data.finish is set to true, run the following:
    1. Queue a STREAM frame with the FIN bit set.
    2. Set stream's [[\Writable]] slot to false.
    3. Let transport be the RTCQuicTransport, which the stream was created from.
    4. Remove the stream from the transport's [[\QuicTransportWritableStreams]] internal slot.
    The actual transmission of data occurs in parallel. If sending data leads to a QUIC-level error, the application will be notified asynchronously through the RTCQuicTransport's onerror EventHandler.
Parameter Type Nullable Optional Description
data RTCQuicStreamWriteParameters
Return type: void
abortWriting

A hard shutdown of the RTCQuicWritable stream. It may be called regardless of whether the RTCQuicWritableStream object 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 RTCQuicWritableStream 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 RTCQuicTransport, which the stream was created from.
  6. Remove the stream from the transport's [[\QuicTransportWritableStreams]] 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 RTCQuicStreamAbortInfo
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 RTCQuicWritableStream 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>

Interface Mixin RTCQuicReadableStream

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

Overview

The RTCQuicReadableStream will initialize with the following:

  1. Let stream be the RTCQuicReadableStream.
  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 RTCQuicReadableStream. On getting, it MUST return the value of the RTCQuicReadableStream'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 RTCQuicReadableStream's [[\ReadableAmount]] internal slot.

readingAborted of type RTCQuicStreamAbortInfo readonly

The readingAborted attribute represents a promise that resolves when the RST_STREAM frame is received from the RTCQuicWritableStream. When the stream receives a RST_STREAM frame from its corresponding RTCQuicWritableStream, the user agent MUST run the following:

  1. Let stream be the RTCQuicReadableStream object
  2. Set stream's [[\Readable]] slot to false.
  3. Clear the stream's read buffer.
  4. Let transport be the RTCQuicTransport, which the stream was created from.
  5. Remove the stream from the transport's [[\QuicTransportReadableStreams]] internal slot.
  6. resolve the promise with the resulting RTCQuicStreamAbortInfo with errorCode set to the value of the errror code from the RST_STREAM frame.

Methods

readInto

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

  1. Let stream be the RTCQuicReadableStream 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 RTCQuicStreamReadResult 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 FIN bit being read, 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 RTCQuicTransport, which the stream was created from.
    4. Remove the stream from the transport's [[\QuicTransportReadableStreams]] internal slot.
  10. Else, set result's finished to false.
  11. Return result.
Parameter Type Nullable Optional Description
data Uint8Array
abortReading

A hard shutdown of the RTCQuicReadableStream. It may be called regardless of whether the RTCQuicReadableStream 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 RTCQuicReadableStream 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 RTCQuicTransport, which the stream was created from.
  6. Remove the stream from the transport's [[\QuicTransportReadableStreams]] internal slot.
  7. Let abortInfo be the first argument.
  8. Start the closing procedure by sending a STOP_SENDING frame with its error code set to the value of abortInfo.errorCode.
Parameter Type Nullable Optional Description
abortInfo RTCQuicStreamAbortInfo
Return type: void
waitForReadable

waitForReadable waits for data to become available, or for the RTCQuicReadableStream 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 STREAM frame with the FIN bit set has been received. 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 RTCQuicReadableStream 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>

Interface RTCQuicStream

        [ Exposed=Window ]
        interface RTCQuicStream {
            readonly attribute unsigned long long streamId;
            readonly attribute RTCQuicTransport transport;
        };
        

Attributes

streamId of type unsigned long long, readonly

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

transport of type RTCQuicTransport, readonly

The readonly attribute referring to the related RTCQuicTransport object.

Interface RTCQuicBidirectionalStream

        [ Exposed=Window ]
        interface RTCQuicBidirectionalStream : RTCQuicStream {
        };
        RTCQuicBidirectionalStream includes RTCQuicWritableStream;
        RTCQuicBidirectionalStream includes RTCQuicReadableStream;
        

Interface RTCQuicSendStream

        [ Exposed=Window ]
        interface RTCQuicSendStream : RTCQuicStream {
        };
        RTCQuicSendStream includes RTCQuicWritableStream;
        

Interface RTCQuicReceiveStream

        [ Exposed=Window ]
        interface RTCQuicReceiveStream : RTCQuicStream {
        };
        RTCQuicReceiveStream includes RTCQuicReadableStream;
        

RTCQuicStreamWriteParameters Dictionary

The RTCQuicStreamWriteParameters dictionary includes information relating to the data to be written with RTCQuicWritableStream.write.

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

Dictionary RTCQuicStreamWriteParameters 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. This will result in a STREAM frame with the FIN bit set.

RTCQuicStreamReadResult Dictionary

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

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

Dictionary RTCQuicStreamReadResult Members

amount of type unsigned long.

The amount of data read in bytes.

finished of type boolean.

Set to true if the RTCQuicReadableStream has finished reading.

RTCQuicStreamAbortInfo Dictionary

The RTCQuicStreamAbortInfo dictionary includes information relating to the error code for aborting a QUIC stream. This could be used either in a RST_STREAM frame or STOP_SENDING frame.

dictionary RTCQuicStreamAbortInfo {
             unsigned short errorCode = 0;
        };
        

Dictionary RTCQuicStreamAbortInfo Members

errorCode of type unsigned short.

The error code used in the RST_STREAM or STOP_SENDING frame. The default value of 0 means "STOPPING."

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. The overall security considerations of the APIs and protocols used in WebRTC are described in [[RTCWEB-SECURITY-ARCH]].

Impact on same origin policy

The QUIC API enables data to be communicated between browsers and other devices, including other browsers.

This means that data can be shared between applications running in different browsers, or between an application running in the same browser and something that is not a browser. This is an extension to the Web model which has had barriers against sending data between entities with different origins.

This specification provides no user prompts or chrome indicators for communication; it assumes that once the Web page has been allowed to access data, it is free to share that data with other entities as it chooses. Peer-to-peer exchanges of data via QUIC can therefore occur without any user explicit consent or involvement.

Impact on local network

Since the browser is an active platform executing in a trusted network environment (inside the firewall), it is important to limit the damage that the browser can do to other elements on the local network, and it is important to protect data from interception, manipulation and modification by untrusted participants.

Mitigations include:

These measures are specified in the relevant IETF documents.

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.

Persistent information

Utilizing the generateCertificate API in [[!WEBRTC]], it is possible to generate and store certificates that can subsequently be reused in constructing RTCQuicTransport objects. These persistent certificates can therefore be used to identify a user.

Event summary

The following events fire on RTCQuicTransport objects:

Event name Interface Fired when...
error ErrorEvent The RTCQuicTransport object has encountered an error.
statechange Event The RTCQuicTransportState changed.
receivestreamwithdata ReceiveStreamWithDataEvent A new RTCQuicReceiveStream is dispatched to the script in response to the remote peer creating a send only QUIC stream and sending data on it. Prior to receivestreamwithdata firing, the RTCQuicReceiveStream is added to RTCQuicTransport's[[\QuicTransportReadableStreams]] internal slot.
bidirectionalstreamwithdata BidirectionalStreamWithDataEvent A new RTCQuicBidirectionalStream is dispatched to the script in response to the remote peer creating a bidirectional QUIC stream and sending data on it. Prior to bidirectionalstreamwithdata firing, the RTCQuicBidirectionalStream is added to both the RTCQuicTransport's [[\QuicTransportReadableStreams]] and [[\QuicTransportWritableStreams]] internal slot.

Examples

      

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 RTCQuicTransport and RTCQuicStream objects were initially described in the W3C ORTC CG, and have been adapted for use in this specification.