The WebTransport()
constructor creates a new WebTransport
object instance.
Note: This feature is available in Web Workers
The WebTransport()
constructor creates a new WebTransport
object instance.
Note: This feature is available in Web Workers
js
new WebTransport(url) new WebTransport(url, options)
url
A string representing the URL of the HTTP/3 server to connect to. The scheme must be HTTPS, and the port number needs to be explicitly specified.
options
Optional
An object that may have the following properties:
allowPooling
Optional
A boolean value. If true
, the network connection for this WebTransport
can be shared with a pool of other HTTP/3 sessions. By default the value is false
, and the connection cannot be shared.
congestionControl
Optional
A string indicating the application's preference that the congestion control algorithm used when sending data over this connection be tuned for either throughput or low-latency. This is a hint to the user agent. The allowed values are: default
(default), throughput
, and low-latency
.
requireUnreliable
Optional
A boolean value. If true
, the connection cannot be established over HTTP/2 if an HTTP/3 connection is not possible. By default the value is false
.
serverCertificateHashes
Optional
An array of objects, each defining the hash value of a server certificate along with the name of the algorithm that was used to generate it. This option is only supported for transports using dedicated connections (allowPooling
is false
).
If specified, the browser will attempt to authenticate the certificate provided by the server against the provided certificate hash(es) in order to connect, instead of using the Web public key infrastructure (PKI). If any hashes match, the browser knows that the server has possession of a trusted certificate and will connect as normal. If empty the user agent uses the same PKI certificate verification procedures it would use for a normal fetch operation.
This feature allows developers to connect to WebTransport servers that would normally find obtaining a publicly trusted certificate challenging, such as hosts that are not publicly routable, or ephemeral hosts like virtual machines.
Note: The web application might typically fetch the hashes from a trusted intermediary. For example, you might use a cloud provider to provision VMs that run your WebTransport servers. The provider has trusted access to the server and can request its certificate, generate hashes, and provide these to the application via an API (which is mediated via PKI), or a cloud console. The web application can now connect directly to the VM-hosted server using the supplied hashes, even though the VM itself does not have a long-lived TLS certificate.
The certificate must be an X.509v3 certificate that has a validity period of less that 2 weeks, and the current time must be within that validity period. The format of the public key in the certificate depends on the implementation, but must minimally include ECDSA with the secp256r1 (NIST P-256) named group, and must not include RSA keys. An ECSDA key is therefore an interoperable default public key format. A user agent may add further requirements; these will be listed in the browser compatibility section if known.
Each object in the array has the following properties:
algorithm
A string with the value: sha-256
(case-insensitive). Note that this string represents the algorithm to use to verify the hash, and that any hash using an unknown algorithm will be ignored. At time of writing, SHA-256
is the only hash algorithm listed in the specification.
value
An ArrayBuffer
or TypedArray
containing the hash value.
NotSupportedError
DOMException
Thrown if serverCertificateHashes
is specified but the transport protocol does not support this feature.
SyntaxError
Thrown if the specified url
is invalid, if the scheme is not HTTPS, or if the URL includes a fragment.
TypeError
Thrown if a serverCertificateHashes
is set for a non-dedicated connection (in other words, if allowPooling
is true
).
This example shows how you might construct a WebTransport
using just a URL, wait for it to connect, and then monitor the transport and report when it has closed.
First we define an async
method that takes an URL and uses it to construct the WebTransport
object. No constructor options are specified, so the connection uses default options: dedicated connection, support for unreliable transports is not required, default congestion control, and normal Web PKI authentication with the server. Note that the scheme needs to be HTTPS, and the port number needs to be explicitly specified.
Once the WebTransport.ready
promise fulfills, you can start using the connection.
js
async function initTransport(url) { // Initialize transport connection const transport = new WebTransport(url); // The connection can be used once ready fulfills await transport.ready; return transport; }
You can respond to the connection closing by waiting for the WebTransport.closed
promise to fulfill. Errors returned by WebTransport
operations are of type WebTransportError
, and contain additional data on top of the standard DOMException
set.
The closeTransport()
method below shows how. Within a try...catch
block it uses await
to wait for the closed
promise to fulfill or reject, and then reports whether or not the connection closed intentionally or due to error.
js
async function closeTransport(transport) { // Respond to connection closing try { await transport.closed; console.log(`The HTTP/3 connection to ${url} closed gracefully.`); } catch (error) { console.error(`The HTTP/3 connection to ${url} closed due to ${error}.`); } }
We might call the asynchronous functions above in their own asynchronous function, as shown below.
js
// Use the transport async function useTransport(url) { const transport = await initTransport(url); // Use the transport object to send and receive data // ... // When done, close the transport await closeTransport(transport); } const url = "https://example.com:4999/wt"; useTransport(url);
The example below shows the code to construct a WebTransport
that specifies the serverCertificateHashes
option. In this case the array contains two hashes, both encoded using the SHA-256 algorithm. Note that the allowPooling
option must be false
(the default).
js
const transport = new WebTransport(url, { serverCertificateHashes: [ { algorithm: "sha-256", value: "5a155927eba7996228455e4721e6fe5f739ae15db6915d765e5db302b4f8a274", }, { algorithm: "sha-256", value: "7d7094e7a8d3097feff3b5ee84fa5cab58e4de78f38bcfdee5ea8b51f4bfa8fd", }, ], });
Specification |
---|
WebTransport # dom-webtransport-webtransport |
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Internet Explorer | Opera | Safari | WebView Android | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | |
WebTransport |
97 | 97 | 114 | No | 83 | No | 97 | 97 | 114 | 68 | No | 18.0 |
options_allowPooling_parameter |
No | No | 114 | No | No | No | No | No | 114 | No | No | No |
options_congestionControl_parameter |
No | No | 114 | No | No | No | No | No | 114 | No | No | No |
options_requireUnreliable_parameter |
No | No | 114 | No | No | No | No | No | 114 | No | No | No |
options_serverCertificateHashes_parameter |
100 | 100 | No | No | 86 | No | 100 | 100 | No | 69 | No | 19.0 |
© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/WebTransport