From 2e6ca16ef48881b33f3420e6174566932f1b7805 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Tue, 15 Nov 2022 15:14:37 +0000 Subject: [PATCH 1/6] adding docs for WebTransport --- .../en-us/web/api/webtransport/close/index.md | 75 +++++ .../web/api/webtransport/closed/index.md | 67 +++++ .../createbidirectionalstream/index.md | 101 +++++++ .../createunidirectionalstream/index.md | 78 ++++++ .../web/api/webtransport/datagrams/index.md | 73 +++++ .../incomingbidirectionalstreams/index.md | 81 ++++++ .../incomingunidirectionalstreams/index.md | 72 +++++ files/en-us/web/api/webtransport/index.md | 92 +++++++ .../en-us/web/api/webtransport/ready/index.md | 62 +++++ .../api/webtransport/webtransport/index.md | 89 ++++++ files/en-us/web/api/webtransport_api/index.md | 256 ++++++++++++++++++ .../webtransportbidirectionalstream/index.md | 110 ++++++++ .../readable/index.md | 43 +++ .../writable/index.md | 43 +++ .../webtransportdatagramduplexstream/index.md | 87 ++++++ .../en-us/web/api/webtransporterror/index.md | 73 +++++ .../web/api/webtransporterror/source/index.md | 46 ++++ .../streamErrorCode/index.md | 46 ++++ .../webtransporterror/index.md | 56 ++++ files/jsondata/GroupData.json | 13 + 20 files changed, 1563 insertions(+) create mode 100644 files/en-us/web/api/webtransport/close/index.md create mode 100644 files/en-us/web/api/webtransport/closed/index.md create mode 100644 files/en-us/web/api/webtransport/createbidirectionalstream/index.md create mode 100644 files/en-us/web/api/webtransport/createunidirectionalstream/index.md create mode 100644 files/en-us/web/api/webtransport/datagrams/index.md create mode 100644 files/en-us/web/api/webtransport/incomingbidirectionalstreams/index.md create mode 100644 files/en-us/web/api/webtransport/incomingunidirectionalstreams/index.md create mode 100644 files/en-us/web/api/webtransport/index.md create mode 100644 files/en-us/web/api/webtransport/ready/index.md create mode 100644 files/en-us/web/api/webtransport/webtransport/index.md create mode 100644 files/en-us/web/api/webtransport_api/index.md create mode 100644 files/en-us/web/api/webtransportbidirectionalstream/index.md create mode 100644 files/en-us/web/api/webtransportbidirectionalstream/readable/index.md create mode 100644 files/en-us/web/api/webtransportbidirectionalstream/writable/index.md create mode 100644 files/en-us/web/api/webtransportdatagramduplexstream/index.md create mode 100644 files/en-us/web/api/webtransporterror/index.md create mode 100644 files/en-us/web/api/webtransporterror/source/index.md create mode 100644 files/en-us/web/api/webtransporterror/streamErrorCode/index.md create mode 100644 files/en-us/web/api/webtransporterror/webtransporterror/index.md diff --git a/files/en-us/web/api/webtransport/close/index.md b/files/en-us/web/api/webtransport/close/index.md new file mode 100644 index 000000000000000..2149d2f546c9fd4 --- /dev/null +++ b/files/en-us/web/api/webtransport/close/index.md @@ -0,0 +1,75 @@ +--- +title: WebTransport.close() +slug: Web/API/WebTransport/close +page-type: web-api-instance-method +tags: + - API + - close + - Experimental + - Property + - Reference + - WebTransport + - WebTransport API +browser-compat: api.WebTransport.close +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`close()`** method of the {{domxref("WebTransport")}} interface closes an ongoing WebTransport session. + +{{AvailableInWorkers}} + +## Syntax + +```js +close(info) +``` + +### Parameters + +- `info` {{optional_inline}} + - : An object containing the following properties: + - `closeCode` + - : A number representing the error code for the error. + - `reason` + - : A string representing the reason for closing the `WebTransport`. + +### Return value + +`undefined`. + +### Exceptions + +- {{domxref("WebTransportError")}} + - : Thrown if `close()` is invoked while the WebTransport is in the process of connecting. + +## Examples + +```js +const url = 'https://example.com:4999/wt'; +// Initialize transport connection +const transport = new WebTransport(url); + +// ... + +transport.close({ + closeCode: 017, + reason: 'CloseButtonPressed' +}); +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransport/closed/index.md b/files/en-us/web/api/webtransport/closed/index.md new file mode 100644 index 000000000000000..4b670bd0c2695f2 --- /dev/null +++ b/files/en-us/web/api/webtransport/closed/index.md @@ -0,0 +1,67 @@ +--- +title: WebTransport.closed +slug: Web/API/WebTransport/closed +page-type: web-api-instance-property +tags: + - API + - closed + - Experimental + - Property + - Reference + - WebTransport + - WebTransport API +browser-compat: api.WebTransport.closed +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`closed`** read-only property of the {{domxref("WebTransport")}} interface returns a promise that resolves when the transport is closed. + +{{AvailableInWorkers}} + +## Value + +A {{jsxref("Promise")}} that resolves to an object containing the following properties: + +- `closeCode` + - : A number representing the error code for the error. +- `reason` + - : A string representing the reason for closing the `WebTransport`. + +## Examples + +```js +const url = 'https://example.com:4999/wt'; +// Initialize transport connection +const transport = new WebTransport(url); + +async function initTransport(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}.`); + } + + // The connection can be used once ready fulfills + await transport.ready; + + // ... +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransport/createbidirectionalstream/index.md b/files/en-us/web/api/webtransport/createbidirectionalstream/index.md new file mode 100644 index 000000000000000..2da0df4b867381c --- /dev/null +++ b/files/en-us/web/api/webtransport/createbidirectionalstream/index.md @@ -0,0 +1,101 @@ +--- +title: WebTransport.createBidirectionalStream() +slug: Web/API/WebTransport/createBidirectionalStream +page-type: web-api-instance-method +tags: + - API + - createBidirectionalStream + - Experimental + - Property + - Reference + - WebTransport + - WebTransport API +browser-compat: api.WebTransport.createBidirectionalStream +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`createBidirectionalStream()`** method of the {{domxref("WebTransport")}} interface opens a bidirectional stream; it returns a {{domxref("WebTransportBidirectionalStream")}} object containing `readable` and `writable` properties, which can be used to reliably read from and write to the server. + +"Reliable" means that transmission and order of data are guaranteed. This provides slower delivery (albeit faster than with WebSockets) than {{domxref("WebTransport.datagrams", "datagrams")}}, but is needed in situations where reliability and ordering are important, like chat applications. + +{{AvailableInWorkers}} + +## Syntax + +```js +createBidirectionalStream() +``` + +### Parameters + +None. + +### Return value + +A {{domxref("WebTransportBidirectionalStream")}} object. + +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : Thrown if `createBidirectionalStream()` is invoked while the WebTransport is closed or failed. + +## Examples + +An initial function is used to get references to the {{domxref("WebTransportBidirectionalStream.readable")}} and {{domxref("WebTransportBidirectionalStream.writable")}} properties. These are references to `ReadableStream` and `WritableStream` instances, which can be used to read from and write to the server. + +```js +async function setUpBidirectional() { + const stream = await transport.createBidirectionalStream(); + // stream is a WebTransportBidirectionalStream + // stream.readable is a ReadableStream + const readable = stream.readable; + // stream.writable is a WritableStream + const writable = stream.writable; + + ... +} +``` + +Reading from the `ReadableStream` can then be done as follows: + +```js +async function readData(readable) { + const reader = readable.getReader(); + while (true) { + const {value, done} = await reader.read(); + if (done) { + break; + } + // value is a Uint8Array. + console.log(value); + } +} +``` + +And writing to the `WritableStream` can be done like this: + +```js +async function writeData(writable) { + const writer = writable.getWriter(); + const data1 = new Uint8Array([65, 66, 67]); + const data2 = new Uint8Array([68, 69, 70]); + writer.write(data1); + writer.write(data2); +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransport/createunidirectionalstream/index.md b/files/en-us/web/api/webtransport/createunidirectionalstream/index.md new file mode 100644 index 000000000000000..67416f068b68dd9 --- /dev/null +++ b/files/en-us/web/api/webtransport/createunidirectionalstream/index.md @@ -0,0 +1,78 @@ +--- +title: WebTransport.createUnidirectionalStream() +slug: Web/API/WebTransport/createUnidirectionalStream +page-type: web-api-instance-method +tags: + - API + - createUnidirectionalStream + - Experimental + - Property + - Reference + - WebTransport + - WebTransport API +browser-compat: api.WebTransport.createUnidirectionalStream +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`createUnidirectionalStream()`** method of the {{domxref("WebTransport")}} interface opens a unidirectional stream; it returns a {{domxref("WritableStream")}} object that can be used to reliably write data to the server. + +"Reliable" means that transmission and order of data are guaranteed. This provides slower delivery (albeit faster than with WebSockets) than {{domxref("WebTransport.datagrams", "datagrams")}}, but is needed in situations where reliability and ordering are important, like chat applications. + +{{AvailableInWorkers}} + +## Syntax + +```js +createUnidirectionalStream() +``` + +### Parameters + +None. + +### Return value + +A {{domxref("WritableStream")}} object. + +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : Thrown if `createUnidirectionalStream()` is invoked while the WebTransport is closed or failed. + +## Examples + +Use the `createUnidirectionalStream()` method to get a reference to a {{domxref("WritableStream")}}. From this you can {{domxref("WritableStream.getWriter", "get a writer")}} to allow data to be written to the stream and sent to the server. + +```js +async function writeData() { + const stream = await transport.createUnidirectionalStream(); + const writer = stream.writable.getWriter(); + const data1 = new Uint8Array([65, 66, 67]); + const data2 = new Uint8Array([68, 69, 70]); + writer.write(data1); + writer.write(data2); + + try { + await writer.close(); + console.log('All data has been sent.'); + } catch (error) { + console.error(`An error occurred: ${error}`); + } +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransport/datagrams/index.md b/files/en-us/web/api/webtransport/datagrams/index.md new file mode 100644 index 000000000000000..f4434d7416b1cdc --- /dev/null +++ b/files/en-us/web/api/webtransport/datagrams/index.md @@ -0,0 +1,73 @@ +--- +title: WebTransport.datagrams +slug: Web/API/WebTransport/datagrams +page-type: web-api-instance-property +tags: + - API + - datagrams + - Experimental + - Property + - Reference + - WebTransport + - WebTransport API +browser-compat: api.WebTransport.datagrams +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`datagrams`** read-only property of the {{domxref("WebTransport")}} interface returns a {{domxref("WebTransportDatagramDuplexStream")}} instance that can be used to send and receive datagrams — unreliable data transmission. + +"Unreliable" means that transmission of data is not guaranteed, nor is arrival in a specific order. This is fine in some situations and provides very fast delivery. For example, you might want to transmit regular game state updates where each message supersedes the last one that arrives, and order is not important. + +{{AvailableInWorkers}} + +## Value + +A {{domxref("WebTransportDatagramDuplexStream")}} object. + +## Examples + +### Writing an outgoing datagram + +The {{domxref("WebTransportDatagramDuplexStream.writable")}} property returns a {{domxref("WritableStream")}} object that you can write data to using a writer, for transmission to the server: + +```js +const writer = transport.datagrams.writable.getWriter(); +const data1 = new Uint8Array([65, 66, 67]); +const data2 = new Uint8Array([68, 69, 70]); +writer.write(data1); +writer.write(data2); +``` + +### Reading an incoming datagram + +The {{domxref("WebTransportDatagramDuplexStream.readable")}} property returns a {{domxref("ReadableStream")}} object that you can use to receive data from the server: + +```js +async function readData() { + const reader = transport.datagrams.readable.getReader(); + while (true) { + const {value, done} = await reader.read(); + if (done) { + break; + } + // value is a Uint8Array. + console.log(value); + } +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransport/incomingbidirectionalstreams/index.md b/files/en-us/web/api/webtransport/incomingbidirectionalstreams/index.md new file mode 100644 index 000000000000000..92a890e06381242 --- /dev/null +++ b/files/en-us/web/api/webtransport/incomingbidirectionalstreams/index.md @@ -0,0 +1,81 @@ +--- +title: WebTransport.incomingBidirectionalStreams +slug: Web/API/WebTransport/incomingBidirectionalStreams +page-type: web-api-instance-property +tags: + - API + - Experimental + - incomingBidirectionalStreams + - Property + - Reference + - WebTransport + - WebTransport API +browser-compat: api.WebTransport.incomingBidirectionalStreams +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`incomingBidirectionalStreams`** read-only property of the {{domxref("WebTransport")}} interface represents one or more bidirectional streams opened by the server. Returns a {{domxref("ReadableStream")}} of {{domxref("WebTransportBidirectionalStream")}} objects. Each one can be used to reliably read data from the server and write data back to it. + +"Reliable" means that transmission and order of data are guaranteed. This provides slower delivery (albeit faster than with WebSockets) than {{domxref("WebTransport.datagrams", "datagrams")}}, but is needed in situations where reliability and ordering are important, like chat applications. + +{{AvailableInWorkers}} + +## Value + +A {{domxref("ReadableStream")}} of {{domxref("WebTransportBidirectionalStream")}} objects. + +## Examples + +An initial function is used to read the {{domxref("WebTransportBidirectionalStream")}} objects from the {{domxref("ReadableStream")}}. For each one, the {{domxref("WebTransportBidirectionalStream.readable")}} and {{domxref("WebTransportBidirectionalStream.writable")}} values are passed to other functions to read from and write to those streams. + +```js +async function receiveBidirectional() { + const bds = transport.incomingBidirectionalStreams; + const reader = bds.getReader(); + while (true) { + const {done, value} = await reader.read(); + if (done) { + break; + } + // value is an instance of WebTransportBidirectionalStream + await readData(value.readable); + await writeData(value.writable); + } +} + +async function readData(readable) { + const reader = readable.getReader(); + while (true) { + const {value, done} = await reader.read(); + if (done) { + break; + } + // value is a Uint8Array. + console.log(value); + } +} + +async function writeData(writable) { + const writer = writable.getWriter(); + const data1 = new Uint8Array([65, 66, 67]); + const data2 = new Uint8Array([68, 69, 70]); + writer.write(data1); + writer.write(data2); +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransport/incomingunidirectionalstreams/index.md b/files/en-us/web/api/webtransport/incomingunidirectionalstreams/index.md new file mode 100644 index 000000000000000..680e6e642f01da0 --- /dev/null +++ b/files/en-us/web/api/webtransport/incomingunidirectionalstreams/index.md @@ -0,0 +1,72 @@ +--- +title: WebTransport.incomingUnidirectionalStreams +slug: Web/API/WebTransport/incomingUnidirectionalStreams +page-type: web-api-instance-property +tags: + - API + - Experimental + - incomingUnidirectionalStreams + - Property + - Reference + - WebTransport + - WebTransport API +browser-compat: api.WebTransport.incomingUnidirectionalStreams +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`incomingUnidirectionalStreams`** read-only property of the {{domxref("WebTransport")}} interface represents one or more unidirectional streams opened by the server. Returns a {{domxref("ReadableStream")}} of {{domxref("WebTransportReceiveStream")}} objects. Each one can be used to reliably read data from the server. + +"Reliable" means that transmission and order of data are guaranteed. This provides slower delivery (albeit faster than with WebSockets) than {{domxref("WebTransport.datagrams", "datagrams")}}, but is needed in situations where reliability and ordering are important, like chat applications. + +{{AvailableInWorkers}} + +## Value + +A {{domxref("ReadableStream")}} of {{domxref("WebTransportReceiveStream")}} objects. + +## Examples + +An initial function is used to read the {{domxref("WebTransportReceiveStream")}} objects from the {{domxref("ReadableStream")}}. Each object is then passed to another function to read from those streams. + +```js +async function receiveUnidirectional() { + const uds = transport.incomingUnidirectionalStreams; + const reader = uds.getReader(); + while (true) { + const {done, value} = await reader.read(); + if (done) { + break; + } + // value is an instance of WebTransportReceiveStream + await readData(value); + } +} + +async function readData(receiveStream) { + const reader = receiveStream.getReader(); + while (true) { + const {done, value} = await reader.read(); + if (done) { + break; + } + // value is a Uint8Array + console.log(value); + } +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransport/index.md b/files/en-us/web/api/webtransport/index.md new file mode 100644 index 000000000000000..8eeecaa3ee1ca5c --- /dev/null +++ b/files/en-us/web/api/webtransport/index.md @@ -0,0 +1,92 @@ +--- +title: WebTransport +slug: Web/API/WebTransport +page-type: web-api-interface +tags: + - API + - Experimental + - Interface + - Reference + - WebTransport + - WebTransport API +browser-compat: api.WebTransport +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`WebTransport`** interface of the {{domxref("WebTransport API", "WebTransport API", "", "nocode")}} provides functionality to enable a user agent to connect to an HTTP/3 server, initiate reliable and unreliable transport in either or both directions, and close the connection once it is no longer needed. + +{{InheritanceDiagram}} + +{{AvailableInWorkers}} + +## Constructor + +- {{domxref("WebTransport.WebTransport", "WebTransport()")}} + - : Creates a new `WebTransport` object instance. + +## Instance properties + +- {{domxref("WebTransport.closed", "closed")}} {{ReadOnlyInline}} + - : Returns a promise that resolves when the transport is closed. +- {{domxref("WebTransport.datagrams", "datagrams")}} {{ReadOnlyInline}} + - : Returns a {{domxref("WebTransportDatagramDuplexStream")}} instance that can be used to send and receive datagrams. +- {{domxref("WebTransport.incomingBidirectionalStreams", "incomingBidirectionalStreams")}} {{ReadOnlyInline}} + - : Represents one or more bidirectional streams opened by the server. Returns a {{domxref("ReadableStream")}} of {{domxref("WebTransportBidirectionalStream")}} objects. Each one can be used to read data from the server and write data back to it. +- {{domxref("WebTransport.incomingUnidirectionalStreams", "incomingUnidirectionalStreams")}} {{ReadOnlyInline}} + - : Represents one or more unidirectional streams opened by the server. Returns a {{domxref("ReadableStream")}} of {{domxref("WebTransportReceiveStream")}} objects. Each one can be used to read data from the server. +- {{domxref("WebTransport.ready", "ready")}} {{ReadOnlyInline}} + - : Returns a promise that resolves when the transport is ready to use. + +## Instance methods + +- {{domxref("WebTransport.close", "close()")}} + - : Closes an ongoing WebTransport session. +- {{domxref("WebTransport.createBidirectionalStream", "createBidirectionalStream()")}} + - : Opens a bidirectional stream; returns a {{domxref("WebTransportBidirectionalStream")}} object containing `readable` and `writable` properties, which can be used to read from and write to the server. +- {{domxref("WebTransport.createUnidirectionalStream", "createUnidirectionalStream()")}} + - : Opens a unidirectional stream; returns a {{domxref("WritableStream")}} object that can be used to write to the server. + +## Examples + +The following snippet shows how you'd connect to an HTTP/3 server by passing its URL to the {{domxref("WebTransport.WebTransport", "WebTransport()")}} constructor. Note that the scheme needs to be HTTPS, and the port number needs to be explicitly specified. Once the {{domxref("WebTransport.ready")}} promise fulfills, you can start using the connection. + +Also note that you can respond to the connection closing by waiting for the {{domxref("WebTransport.closed")}} promise to fulfill. Errors returned by WebTransport operations are of type {{domxref("WebTransportError")}}, and contain additional data on top of the standard {{domxref("DOMException")}} set. + +```js +const url = 'https://example.com:4999/wt'; +// Initialize transport connection +const transport = new WebTransport(url); + +async function initTransport(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}.`); + } + + // The connection can be used once ready fulfills + await transport.ready; + + // ... +} +``` + +For other example code, see the individual property and method pages. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransport/ready/index.md b/files/en-us/web/api/webtransport/ready/index.md new file mode 100644 index 000000000000000..558d443ba5bcae2 --- /dev/null +++ b/files/en-us/web/api/webtransport/ready/index.md @@ -0,0 +1,62 @@ +--- +title: WebTransport.ready +slug: Web/API/WebTransport/ready +page-type: web-api-instance-property +tags: + - API + - Experimental + - Property + - ready + - Reference + - WebTransport + - WebTransport API +browser-compat: api.WebTransport.ready +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`ready`** read-only property of the {{domxref("WebTransport")}} interface returns a promise that resolves when the transport is ready to use. + +{{AvailableInWorkers}} + +## Value + +A {{jsxref("Promise")}} that resolves to `undefined`. + +## Examples + +```js +const url = 'https://example.com:4999/wt'; +// Initialize transport connection +const transport = new WebTransport(url); + +async function initTransport(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}.`); + } + + // The connection can be used once ready fulfills + await transport.ready; + + // ... +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransport/webtransport/index.md b/files/en-us/web/api/webtransport/webtransport/index.md new file mode 100644 index 000000000000000..314be567e28d6df --- /dev/null +++ b/files/en-us/web/api/webtransport/webtransport/index.md @@ -0,0 +1,89 @@ +--- +title: WebTransport() +slug: Web/API/WebTransport/WebTransport +page-type: web-api-constructor +tags: + - API + - Constructor + - Experimental + - Reference + - WebTransport + - WebTransport API +browser-compat: api.WebTransport.WebTransport +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`WebTransport()`** constructor creates a new +{{domxref("WebTransport")}} object instance. + +{{AvailableInWorkers}} + +## Syntax + +```js-nolint +new WebTransport(url, options) +``` + +### Parameters + +- `url` + - : A string representing the URL of the HTTP/3 server to connect to. The scheme needs to be HTTPS, and the port number needs to be explicitly specified. +- `options` {{optional_inline}} + - : An object containing the following properties: + - `serverCertificateHashes` {{optional_inline}} + - : An array of `WebTransportHash` objects. If specified, it allows the website to connect to a server by authenticating the certificate against the expected certificate hash instead of using the Web public key infrastructure (PKI). This feature allows Web developers to connect to WebTransport servers that would normally find obtaining a publicly trusted certificate challenging, such as hosts that are not publically routable, or ephemeral hosts like virtual machines. + +`WebTransportHash` objects contain two properties: + +- `algorithm` + - : A string representing the algorithm to use to verify the hash. Any hash using an unknown algorithm will be ignored. +- `value` + - : A `BufferSource` representing the hash value. + +### Exceptions + +- `NotSupportedError` {{domxref("DOMException")}} + - : Thrown if `serverCertificateHashes` is specified but the transport protocol does not support this feature. +- `SyntaxError` {{domxref("DOMException")}} + - : Thrown if the specified `url` is invalid, if the scheme is not HTTPS, or if the URL includes a fragment. + +## Examples + +### Basic connection + +```js +const url = 'https://example.com:4999/wt'; +// Initialize transport connection +const transport = new WebTransport(url); + +async function initTransport(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}.`); + } + + // The connection can be used once ready fulfills + await transport.ready; + + // ... +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransport_api/index.md b/files/en-us/web/api/webtransport_api/index.md new file mode 100644 index 000000000000000..3dd7163b5e77596 --- /dev/null +++ b/files/en-us/web/api/webtransport_api/index.md @@ -0,0 +1,256 @@ +--- +title: WebTransport API +slug: Web/API/WebTransport_API +page-type: web-api-overview +tags: + - API + - Experimental + - Landing + - Overview + - Reference + - WebTransport API +browser-compat: + - api.WebTransport +--- + +{{seecompattable}}{{DefaultAPISidebar("WebTransport API")}}{{SecureContext_Header}} + +The **WebTransport API** provides a modern update to {{domxref("WebSockets API", "WebSockets", "", "nocode")}}, transmitting data between client and server using [HTTP/3 Transport](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/). WebTransport provides support for multiple streams, unidirectional streams, and out-of-order delivery. It enables reliable transport via {{domxref("Streams API", "streams", "", "nocode")}} and unreliable transport via UDP-like datagrams. + +{{AvailableInWorkers}} + +## Concepts and usage + +[HTTP/3](https://en.wikipedia.org/wiki/HTTP/3) has been in progress since 2018. It is based on Google's QUIC protocol (which is itself based on UDP), and fixes several issues around the classic TCP protocol, on which HTTP and WebSockets are based. + +These include: + +- Head-of-line blocking: HTTP/2 allows multiplexing, so a single connection can stream multiple resources simultaneously. However, if a single resource fails, all other resources on that connection are held up until any missing packets are retransmitted. With QUIC, only the failing resource is affected. + +- Faster performance: QUIC is more performant than TCP in many ways. QUIC can handle security features itself, rather than handling responsibility off to other protocols like TLS, meaning fewer round trips. And streams provide better transport efficiency than the older packet mechanism. This can make a significant difference, especially on high-latency networks. + +- Better network transitions: QUIC uses a unique connection ID to handle the source and destination of each request to ensure that packets are delivered correctly. This ID can persist between different networks, meaning that for example a download can continue interrupted if you switch from Wifi to a mobile network. HTTP/2 on the other hand uses IP addresses as identifiers, so network transitions can be problematic. + +- Unreliable transport: HTTP/3 supports unreliable data transmission via datagrams. + +The WebTransport API provides low-level access to two-way communication via HTTP/3, taking advantage of the above benefits, and supporting both reliable and unreliable data transmission. + +### Initial connection + +To open a connection to an HTTP/3 server, you pass its URL to the {{domxref("WebTransport.WebTransport", "WebTransport()")}} constructor. Note that the scheme needs to be HTTPS, and the port number needs to be explicitly specified. Once the {{domxref("WebTransport.ready")}} promise fulfills, you can start using the connection. + +Also note that you can respond to the connection closing by waiting for the {{domxref("WebTransport.closed")}} promise to fulfill. Errors returned by WebTransport operations are of type {{domxref("WebTransportError")}}, and contain additional data on top of the standard {{domxref("DOMException")}} set. + +```js +const url = 'https://example.com:4999/wt'; +// Initialize transport connection +const transport = new WebTransport(url); + +async function initTransport(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}.`); + } + + // The connection can be used once ready fulfills + await transport.ready; + + // ... +} +``` + +### Unreliable transmission via datagrams + +"Unreliable" means that transmission of data is not guaranteed, nor is arrival in a specific order. This is fine in some situations and provides very fast delivery. For example, you might want to transmit regular game state updates where each message supersedes the last one that arrives, and order is not important. + +Unreliable data transmission is handled via the {{domxref("WebTransport.datagram")}} property — this returns a {{domxref("WebTransportDatagramDuplexStream")}} object containing everything you need to send datagrams to the server, and receive them back. + +The {{domxref("WebTransportDatagramDuplexStream.writable")}} property returns a {{domxref("WritableStream")}} object that you can write data to using a writer, for transmission to the server: + +```js +const writer = transport.datagrams.writable.getWriter(); +const data1 = new Uint8Array([65, 66, 67]); +const data2 = new Uint8Array([68, 69, 70]); +writer.write(data1); +writer.write(data2); +``` + +The {{domxref("WebTransportDatagramDuplexStream.readable")}} property returns a {{domxref("ReadableStream")}} object that you can use to receive data from the server: + +```js +async function readData() { + const reader = transport.datagrams.readable.getReader(); + while (true) { + const {value, done} = await reader.read(); + if (done) { + break; + } + // value is a Uint8Array. + console.log(value); + } +} +``` + +### Reliable transmission via streams + +"Reliable" means that transmission and order of data are guaranteed. This provides slower delivery (albeit faster than with WebSockets), and is needed in situations where reliability and ordering are important, like chat applications. + +### Unidirectional transmission + +To open a unidirectional stream from a user agent, you use the {{domxref("WebTransport.createUnidirectionalStream()")}} method to get a reference to a {{domxref("WritableStream")}}. From this you can {{domxref("WritableStream.getWriter", "get a writer")}} to allow data to be written to the stream and sent to the server. + +```js +async function writeData() { + const stream = await transport.createUnidirectionalStream(); + const writer = stream.writable.getWriter(); + const data1 = new Uint8Array([65, 66, 67]); + const data2 = new Uint8Array([68, 69, 70]); + writer.write(data1); + writer.write(data2); + + try { + await writer.close(); + console.log('All data has been sent.'); + } catch (error) { + console.error(`An error occurred: ${error}`); + } +} +``` + +Note also the use of the {{domxref("WritableStream.close()")}} method to close the associated HTTP/3 connection once all data has been sent. + +If the server opens a unidirectional stream to transmit data to the client, this can be accessed via the {{domxref("WebTransport.incomingUnidirectionalStreams")}} property, which returns a {{domxref("ReadableStream")}} of `WebTransportReceiveStream` objects. Each one can be used to read {{jsxref("Uint8Array")}} instances sent by the server. + +In this case, the first thing to do is set up a function to read a `WebTransportReceiveStream`. These objects inherit from the `ReadableStream` class, so can be used in just the same way: + +```js +async function readData(receiveStream) { + const reader = receiveStream.getReader(); + while (true) { + const {done, value} = await reader.read(); + if (done) { + break; + } + // value is a Uint8Array + console.log(value); + } +} +``` + +Next, call {{domxref("WebTransport.incomingUnidirectionalStreams")}} and get a reference to the reader available on the `ReadableStream` it returns, and then use the reader to read the data from the server. Each chunk is a `WebTransportReceiveStream`, and we use the `readFrom()` set up earlier to read them: + +```js +async function receiveUnidirectional() { + const uds = transport.incomingUnidirectionalStreams; + const reader = uds.getReader(); + while (true) { + const {done, value} = await reader.read(); + if (done) { + break; + } + // value is an instance of WebTransportReceiveStream + await readData(value); + } +} +``` + +NOTE, NEED TO FIND OUT WHETHER THE CHUNKS ACTUALLY ARE WebTransportReceiveStream S, OR JUST READABLESTREAM OBJECTS, AS I'M NOT SURE RIGHT NOW. IT IS PRETTY DIFFICULT TO TEST THIS + +#### Bidirectional transmission + +To open a bidirectional stream from a user agent, you use the {{domxref("WebTransport.createBidirectionalStream()")}} method to get a reference to a {{domxref("WebTransportBidirectionalStream")}}. In the same way as the {{domxref("WebTransportDatagramDuplexStream")}}, this contains `readable` and `writable` properties returning references to `ReadableStream` and `WritableStream` instances, which can be used to read from and write to the server. + +```js +async function setUpBidirectional() { + const stream = await transport.createBidirectionalStream(); + // stream is a WebTransportBidirectionalStream + // stream.readable is a ReadableStream + const readable = stream.readable; + // stream.writable is a WritableStream + const writable = stream.writable; + + ... +} +``` + +Reading from the `ReadableStream` can then be done as follows: + +```js +async function readData(readable) { + const reader = readable.getReader(); + while (true) { + const {value, done} = await reader.read(); + if (done) { + break; + } + // value is a Uint8Array. + console.log(value); + } +} +``` + +And writing to the `WritableStream` can be done like this: + +```js +async function writeData(writable) { + const writer = writable.getWriter(); + const data1 = new Uint8Array([65, 66, 67]); + const data2 = new Uint8Array([68, 69, 70]); + writer.write(data1); + writer.write(data2); +} +``` + +If the server opens a bidirectional stream to transmit data to and receive it from the client, this can be accessed via the {{domxref("WebTransport.incomingBidirectionalStreams")}} property, which returns a {{domxref("ReadableStream")}} of `WebTransportBidirectionalStream` objects. Each one can be used to read and write {{jsxref("Uint8Array")}} instances as shown above. However, as with the unidirectional example, you need an initial function to read the bidirectional stream in the first place: + +```js +async function receiveBidirectional() { + const bds = transport.incomingBidirectionalStreams; + const reader = bds.getReader(); + while (true) { + const {done, value} = await reader.read(); + if (done) { + break; + } + // value is an instance of WebTransportBidirectionalStream + await readData(value.readable); + await writeData(value.writable); + } +} +``` + +## Interfaces + +- {{domxref("WebTransport")}} + - : Provides functionality to enable a user agent to connect to an HTTP/3 server, initiate reliable and unreliable transport in either or both directions, and close the connection once it is no longer needed. +- {{domxref("WebTransportBidirectionalStream")}} + - : Represents a bidirectional stream created by a server or a client that can be used for reliable transport. Provides access to a {{domxref("ReadableStream")}} for reading incoming data, and a {{domxref("WritableStream")}} for writing outgoing data. +- {{domxref("WebTransportDatagramDuplexStream")}} + - : Represents a duplex stream that can be used for unreliable transport of datagrams between client and server. Provides access to a {{domxref("ReadableStream")}} for reading incoming datagrams, a {{domxref("WritableStream")}} for writing outgoing datagrams, and various settings and statistics related to the stream. +- {{domxref("WebTransportError")}} + - : Represents an error related to the WebTransport API, which can arise from server errors, network connection problems, or client-initiated abort operations (for example, arising from a {{domxref("WritableStream.abort()")}} call). + +## Examples + +For complete examples, see: + +- [WebTransport over HTTP/3 client](https://webtransport.day/) +- [WebTransport (BYOB) Echo with WebCodecs in Worker](https://webrtc.internaut.com/wc/wtSender4/) + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransportbidirectionalstream/index.md b/files/en-us/web/api/webtransportbidirectionalstream/index.md new file mode 100644 index 000000000000000..2f1587f6ad32ddc --- /dev/null +++ b/files/en-us/web/api/webtransportbidirectionalstream/index.md @@ -0,0 +1,110 @@ +--- +title: WebTransportBidirectionalStream +slug: Web/API/WebTransportBidirectionalStream +page-type: web-api-interface +tags: + - API + - Experimental + - Interface + - Reference + - WebTransport API + - WebTransportBidirectionalStream +browser-compat: api.WebTransportBidirectionalStream +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`WebTransportBidirectionalStream`** interface of the {{domxref("WebTransport API", "WebTransport API", "", "nocode")}} represents a bidirectional stream created by a server or a client that can be used for reliable transport. Provides access to a {{domxref("ReadableStream")}} for reading incoming data, and a {{domxref("WritableStream")}} for writing outgoing data. + +{{InheritanceDiagram}} + +{{AvailableInWorkers}} + +## Instance properties + +- {{domxref("WebTransportBidirectionalStream.readable", "readable")}} {{ReadOnlyInline}} + - : Returns a {{domxref("ReadableStream")}} instance that can be used to read incoming data. +- {{domxref("WebTransportBidirectionalStream.writable", "writable")}} {{ReadOnlyInline}} + - : Returns a {{domxref("WritableStream")}} instance that can be used to write outgoing data. + +## Examples + +### Bidirectional transmission initiated by the user agent + +To open a bidirectional stream from a user agent, you use the {{domxref("WebTransport.createBidirectionalStream()")}} method to get a reference to a {{domxref("WebTransportBidirectionalStream")}}. The `readable` and `writable` properties return references to `ReadableStream` and `WritableStream` instances, which can be used to read from and write to the server. + +```js +async function setUpBidirectional() { + const stream = await transport.createBidirectionalStream(); + // stream is a WebTransportBidirectionalStream + // stream.readable is a ReadableStream + const readable = stream.readable; + // stream.writable is a WritableStream + const writable = stream.writable; + + ... +} +``` + +Reading from the `ReadableStream` can then be done as follows: + +```js +async function readData(readable) { + const reader = readable.getReader(); + while (true) { + const {value, done} = await reader.read(); + if (done) { + break; + } + // value is a Uint8Array. + console.log(value); + } +} +``` + +And writing to the `WritableStream` can be done like this: + +```js +async function writeData(writable) { + const writer = writable.getWriter(); + const data1 = new Uint8Array([65, 66, 67]); + const data2 = new Uint8Array([68, 69, 70]); + writer.write(data1); + writer.write(data2); +} +``` + +### Bidirectional transmission initiated by the server + +If the server opens a bidirectional stream to transmit data to and receive it from the client, this can be accessed via the {{domxref("WebTransport.incomingBidirectionalStreams")}} property, which returns a {{domxref("ReadableStream")}} of `WebTransportBidirectionalStream` objects. Each one can be used to read and write {{jsxref("Uint8Array")}} instances as shown above. However, you need an initial function to read the bidirectional stream in the first place: + +```js +async function receiveBidirectional() { + const bds = transport.incomingBidirectionalStreams; + const reader = bds.getReader(); + while (true) { + const {done, value} = await reader.read(); + if (done) { + break; + } + // value is an instance of WebTransportBidirectionalStream + await readData(value.readable); + await writeData(value.writable); + } +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransportbidirectionalstream/readable/index.md b/files/en-us/web/api/webtransportbidirectionalstream/readable/index.md new file mode 100644 index 000000000000000..3305850833ad6b0 --- /dev/null +++ b/files/en-us/web/api/webtransportbidirectionalstream/readable/index.md @@ -0,0 +1,43 @@ +--- +title: WebTransportBidirectionalStream.readable +slug: Web/API/WebTransportBidirectionalStream/readable +page-type: web-api-instance-property +tags: + - API + - Experimental + - Property + - readable + - Reference + - WebTransport + - WebTransport API +browser-compat: api.WebTransportBidirectionalStream.readable +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`readable`** read-only property of the {{domxref("WebTransportBidirectionalStream")}} interface returns a {{domxref("ReadableStream")}} instance that can be used to reliably read incoming data. + +{{AvailableInWorkers}} + +## Value + +A {{domxref("ReadableStream")}}. + +## Examples + +See the main {{domxref("WebTransportBidirectionalStream")}} interface page. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransportbidirectionalstream/writable/index.md b/files/en-us/web/api/webtransportbidirectionalstream/writable/index.md new file mode 100644 index 000000000000000..fe13ae0bf07ef8d --- /dev/null +++ b/files/en-us/web/api/webtransportbidirectionalstream/writable/index.md @@ -0,0 +1,43 @@ +--- +title: WebTransportBidirectionalStream.writable +slug: Web/API/WebTransportBidirectionalStream/writable +page-type: web-api-instance-property +tags: + - API + - Experimental + - Property + - Reference + - WebTransport + - WebTransport API + - writable +browser-compat: api.WebTransportBidirectionalStream.writable +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`writable`** read-only property of the {{domxref("WebTransportBidirectionalStream")}} interface returns a {{domxref("WritableStream")}} instance that can be used to write outgoing data. + +{{AvailableInWorkers}} + +## Value + +A {{domxref("WritableStream")}}. + +## Examples + +See the main {{domxref("WebTransportBidirectionalStream")}} interface page. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransportdatagramduplexstream/index.md b/files/en-us/web/api/webtransportdatagramduplexstream/index.md new file mode 100644 index 000000000000000..9fc379e3054fc39 --- /dev/null +++ b/files/en-us/web/api/webtransportdatagramduplexstream/index.md @@ -0,0 +1,87 @@ +--- +title: WebTransportDatagramDuplexStream +slug: Web/API/WebTransportDatagramDuplexStream +page-type: web-api-interface +tags: + - API + - Experimental + - Interface + - Reference + - WebTransport API + - WebTransportDatagramDuplexStream +browser-compat: api.WebTransportDatagramDuplexStream +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`WebTransportDatagramDuplexStream`** interface of the {{domxref("WebTransport API", "WebTransport API", "", "nocode")}} represents a duplex stream that can be used for unreliable transport of datagrams between client and server. Provides access to a {{domxref("ReadableStream")}} for reading incoming datagrams, a {{domxref("WritableStream")}} for writing outgoing datagrams, and various settings and statistics related to the stream. + +This is accessed via the {{domxref("WebTransport.datagram")}} property. + +{{InheritanceDiagram}} + +{{AvailableInWorkers}} + +## Instance properties + +- {{domxref("WebTransportDatagramDuplexStream.incomingHighWaterMark", "incomingHighWaterMark")}} + - : Gets or sets the high water mark for incoming chunks of data — this is the maximum size, in chunks, that the incoming {{domxref("ReadableStream")}}'s internal queue can reach before it is considered full. See [Internal queues and queuing strategies](/en-US/docs/Web/API/Streams_API/Concepts#internal_queues_and_queuing_strategies) for more information. +- {{domxref("WebTransportDatagramDuplexStream.incomingMaxAge", "incomingMaxAge")}} + - : Gets or sets the maximum age for incoming datagrams, in milliseconds. Returns `null` if no maximum age has been set. +- {{domxref("WebTransportDatagramDuplexStream.maxDatagramSize", "maxDatagramSize")}} {{ReadOnlyInline}} + - : Returns the maximum allowable size of outgoing datagrams, in bytes, that can be written to {{domxref("WebTransportDatagramDuplexStream.writable", "writable")}}. +- {{domxref("WebTransportDatagramDuplexStream.outgoingHighWaterMark", "outgoingHighWaterMark")}} + - : Gets or sets the high water mark for outgoing chunks of data — this is the maximum size, in chunks, that the outgoing {{domxref("WritableStream")}}'s internal queue can reach before it is considered full. See [Internal queues and queuing strategies](/en-US/docs/Web/API/Streams_API/Concepts#internal_queues_and_queuing_strategies) for more information. +- {{domxref("WebTransportDatagramDuplexStream.outgoingMaxAge", "outgoingMaxAge")}} + - : Gets or sets the maximum age for outgoing datagrams, in milliseconds. Returns `null` if no maximum age has been set. +- {{domxref("WebTransportDatagramDuplexStream.readable", "readable")}} {{ReadOnlyInline}} + - : Returns a {{domxref("ReadableStream")}} instance that can be used to read incoming datagrams from the stream. +- {{domxref("WebTransportDatagramDuplexStream.writable", "writable")}} {{ReadOnlyInline}} + - : Returns a {{domxref("WritableStream")}} instance that can be used to write outgoing datagrams to the stream. + +## Examples + +### Writing outgoing datagrams + +The {{domxref("WebTransportDatagramDuplexStream.writable", "writable")}} property returns a {{domxref("WritableStream")}} object that you can write data to using a writer, for transmission to the server: + +```js +const writer = transport.datagrams.writable.getWriter(); +const data1 = new Uint8Array([65, 66, 67]); +const data2 = new Uint8Array([68, 69, 70]); +writer.write(data1); +writer.write(data2); +``` + +### Reading incoming datagrams + +The {{domxref("WebTransportDatagramDuplexStream.readable", "readable")}} property returns a {{domxref("ReadableStream")}} object that you can use to receive data from the server: + +```js +async function readData() { + const reader = transport.datagrams.readable.getReader(); + while (true) { + const {value, done} = await reader.read(); + if (done) { + break; + } + // value is a Uint8Array. + console.log(value); + } +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransporterror/index.md b/files/en-us/web/api/webtransporterror/index.md new file mode 100644 index 000000000000000..7ea74012cf8a574 --- /dev/null +++ b/files/en-us/web/api/webtransporterror/index.md @@ -0,0 +1,73 @@ +--- +title: WebTransportError +slug: Web/API/WebTransportError +page-type: web-api-interface +tags: + - API + - Experimental + - Interface + - Reference + - WebTransport API + - WebTransportError +browser-compat: api.WebTransportError +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`WebTransportError`** interface of the {{domxref("WebTransport API", "WebTransport API", "", "nocode")}} represents an error related to the API, which can arise from server errors, network connection problems, or client-initiated abort operations (for example, arising from a {{domxref("WritableStream.abort()")}} call). + +{{InheritanceDiagram}} + +{{AvailableInWorkers}} + +## Constructor + +- {{domxref("WebTransportError.WebTransportError", "WebTransportError()")}} + - : Creates a new `WebTransportError` object instance. + +## Instance properties + +_Inherits properties from its parent, {{DOMxRef("DOMException")}}._ + +- {{domxref("WebTransportError.source", "source")}} {{ReadOnlyInline}} + - : Returns an enumerated value indicating the source of the error—can be either `stream` or `session`. +- {{domxref("WebTransportError.streamErrorCode", "streamErrorCode")}} {{ReadOnlyInline}} + - : Returns a number in the range 0-255 indicating the application protocol error code for this error, or `null` if one is not available. + +## Examples + +```js +const url = 'https://example.com:4999/wt'; +// Initialize transport connection +const transport = new WebTransport(url); + +async function initTransport(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}.`); + } + + // The connection can be used once ready fulfills + await transport.ready; + + // ... +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransporterror/source/index.md b/files/en-us/web/api/webtransporterror/source/index.md new file mode 100644 index 000000000000000..a583e637a7c4dc6 --- /dev/null +++ b/files/en-us/web/api/webtransporterror/source/index.md @@ -0,0 +1,46 @@ +--- +title: WebTransportError.source +slug: Web/API/WebTransportError/source +page-type: web-api-instance-property +tags: + - API + - Experimental + - Property + - Reference + - source + - WebTransportError + - WebTransport API +browser-compat: api.WebTransportError.source +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`source`** read-only property of the {{domxref("WebTransportError")}} interface returns an enumerated value indicating the source of the error. + +{{AvailableInWorkers}} + +## Value + +An enumerated value; can be either `stream` or `session`. + +## Examples + +```js +// some kind of WebTransport error +console.log(error.source) +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransporterror/streamErrorCode/index.md b/files/en-us/web/api/webtransporterror/streamErrorCode/index.md new file mode 100644 index 000000000000000..e50e5ccce27d70f --- /dev/null +++ b/files/en-us/web/api/webtransporterror/streamErrorCode/index.md @@ -0,0 +1,46 @@ +--- +title: WebTransportError.streamErrorCode +slug: Web/API/WebTransportError/streamErrorCode +page-type: web-api-instance-property +tags: + - API + - Experimental + - Property + - Reference + - streamErrorCode + - WebTransportError + - WebTransport API +browser-compat: api.WebTransportError.streamErrorCode +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`streamErrorCode`** read-only property of the {{domxref("WebTransportError")}} interface returns a number in the range 0-255 indicating the application protocol error code for this error, or `null` if one is not available. + +{{AvailableInWorkers}} + +## Value + +A number, or `null`. + +## Examples + +```js +// some kind of WebTransport error +console.log(error.streamErrorCode) +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransporterror/webtransporterror/index.md b/files/en-us/web/api/webtransporterror/webtransporterror/index.md new file mode 100644 index 000000000000000..b8d5e8146f37099 --- /dev/null +++ b/files/en-us/web/api/webtransporterror/webtransporterror/index.md @@ -0,0 +1,56 @@ +--- +title: WebTransportError() +slug: Web/API/WebTransportError/WebTransportError +page-type: web-api-constructor +tags: + - API + - Constructor + - Experimental + - Reference + - WebTransportError + - WebTransport API +browser-compat: api.WebTransportError.WebTransportError +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`WebTransportError()`** constructor creates a new +{{domxref("WebTransportError")}} object instance. + +{{AvailableInWorkers}} + +## Syntax + +```js-nolint +new WebTransportError(init) +``` + +### Parameters + +- `init` {{optional_inline}} + - : An object containing the following properties: + - `message` + - : A string describing the error that has occurred. + - `streamErrorCode` + - : A number in the range 0-255 indicating the application protocol error code for this error. + +## Examples + +A developer would not use this constructor manually. A new `WebTransportError` object is constructed when an error related to WebTransport occurs, for example a server error or network connection problem. + +MAYBE INCLUDE A SMALL EXAMPLE HERE? + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/jsondata/GroupData.json b/files/jsondata/GroupData.json index 3ae30a8d47fd9b3..86925771e9e2581 100644 --- a/files/jsondata/GroupData.json +++ b/files/jsondata/GroupData.json @@ -1953,6 +1953,19 @@ "properties": ["Window.sessionStorage", "Window.localStorage"], "events": ["Window: storage"] }, + "WebTransport API": { + "overview": ["WebTransport API"], + "guides": [], + "interfaces": [ + "WebTransport", + "WebTransportBidirectionalStream", + "WebTransportDatagramDuplexStream", + "WebTransportError" + ], + "methods": [], + "properties": [], + "events": [] + }, "Web Workers API": { "overview": ["Web Workers API"], "guides": [ From 00ca908f8334e28d5453c0aab432e82ffdb0507f Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Tue, 15 Nov 2022 15:43:01 +0000 Subject: [PATCH 2/6] fix path casing error --- .../{streamErrorCode => streamerrorcode}/index.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename files/en-us/web/api/webtransporterror/{streamErrorCode => streamerrorcode}/index.md (100%) diff --git a/files/en-us/web/api/webtransporterror/streamErrorCode/index.md b/files/en-us/web/api/webtransporterror/streamerrorcode/index.md similarity index 100% rename from files/en-us/web/api/webtransporterror/streamErrorCode/index.md rename to files/en-us/web/api/webtransporterror/streamerrorcode/index.md From ea7866e3bd306eff949181e59ec73feabeea0a7c Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Wed, 16 Nov 2022 08:15:37 +0000 Subject: [PATCH 3/6] add WebTransportDatagramDuplexStream members, fix code examples --- .../en-us/web/api/webtransport/close/index.md | 1 - .../web/api/webtransport/closed/index.md | 7 ++- .../createunidirectionalstream/index.md | 2 +- files/en-us/web/api/webtransport/index.md | 7 ++- .../en-us/web/api/webtransport/ready/index.md | 7 ++- .../api/webtransport/webtransport/index.md | 7 ++- files/en-us/web/api/webtransport_api/index.md | 11 ++-- .../incominghighwatermark/index.md | 61 +++++++++++++++++++ .../incomingmaxage/index.md | 61 +++++++++++++++++++ .../webtransportdatagramduplexstream/index.md | 4 +- .../maxdatagramsize/index.md | 58 ++++++++++++++++++ .../outgoinghighwatermark/index.md | 61 +++++++++++++++++++ .../outgoingmaxage/index.md | 60 ++++++++++++++++++ .../readable/index.md | 45 ++++++++++++++ .../writable/index.md | 45 ++++++++++++++ .../en-us/web/api/webtransporterror/index.md | 28 +++++---- .../web/api/webtransporterror/source/index.md | 22 ++++++- .../streamerrorcode/index.md | 22 ++++++- .../webtransporterror/index.md | 23 ++++++- 19 files changed, 494 insertions(+), 38 deletions(-) create mode 100644 files/en-us/web/api/webtransportdatagramduplexstream/incominghighwatermark/index.md create mode 100644 files/en-us/web/api/webtransportdatagramduplexstream/incomingmaxage/index.md create mode 100644 files/en-us/web/api/webtransportdatagramduplexstream/maxdatagramsize/index.md create mode 100644 files/en-us/web/api/webtransportdatagramduplexstream/outgoinghighwatermark/index.md create mode 100644 files/en-us/web/api/webtransportdatagramduplexstream/outgoingmaxage/index.md create mode 100644 files/en-us/web/api/webtransportdatagramduplexstream/readable/index.md create mode 100644 files/en-us/web/api/webtransportdatagramduplexstream/writable/index.md diff --git a/files/en-us/web/api/webtransport/close/index.md b/files/en-us/web/api/webtransport/close/index.md index 2149d2f546c9fd4..b6f8cf8c61b0eac 100644 --- a/files/en-us/web/api/webtransport/close/index.md +++ b/files/en-us/web/api/webtransport/close/index.md @@ -56,7 +56,6 @@ transport.close({ closeCode: 017, reason: 'CloseButtonPressed' }); -} ``` ## Specifications diff --git a/files/en-us/web/api/webtransport/closed/index.md b/files/en-us/web/api/webtransport/closed/index.md index 4b670bd0c2695f2..f11c7bb0d42d6d0 100644 --- a/files/en-us/web/api/webtransport/closed/index.md +++ b/files/en-us/web/api/webtransport/closed/index.md @@ -32,10 +32,11 @@ A {{jsxref("Promise")}} that resolves to an object containing the following prop ```js const url = 'https://example.com:4999/wt'; -// Initialize transport connection -const transport = new WebTransport(url); -async function initTransport(transport) { +async function initTransport(url) { + // Initialize transport connection + const transport = new WebTransport(url); + // Respond to connection closing try { await transport.closed; diff --git a/files/en-us/web/api/webtransport/createunidirectionalstream/index.md b/files/en-us/web/api/webtransport/createunidirectionalstream/index.md index 67416f068b68dd9..6d3a4323d29b7d5 100644 --- a/files/en-us/web/api/webtransport/createunidirectionalstream/index.md +++ b/files/en-us/web/api/webtransport/createunidirectionalstream/index.md @@ -42,7 +42,7 @@ A {{domxref("WritableStream")}} object. ## Examples -Use the `createUnidirectionalStream()` method to get a reference to a {{domxref("WritableStream")}}. From this you can {{domxref("WritableStream.getWriter", "get a writer")}} to allow data to be written to the stream and sent to the server. +Use the `createUnidirectionalStream()` method to get a reference to a {{domxref("WritableStream")}}. From this you can {{domxref("WritableStream.getWriter", "get a writer", "", "nocode")}} to allow data to be written to the stream and sent to the server. ```js async function writeData() { diff --git a/files/en-us/web/api/webtransport/index.md b/files/en-us/web/api/webtransport/index.md index 8eeecaa3ee1ca5c..137af14f5663b07 100644 --- a/files/en-us/web/api/webtransport/index.md +++ b/files/en-us/web/api/webtransport/index.md @@ -55,10 +55,11 @@ Also note that you can respond to the connection closing by waiting for the {{do ```js const url = 'https://example.com:4999/wt'; -// Initialize transport connection -const transport = new WebTransport(url); -async function initTransport(transport) { +async function initTransport(url) { + // Initialize transport connection + const transport = new WebTransport(url); + // Respond to connection closing try { await transport.closed; diff --git a/files/en-us/web/api/webtransport/ready/index.md b/files/en-us/web/api/webtransport/ready/index.md index 558d443ba5bcae2..be0d0125405a8f5 100644 --- a/files/en-us/web/api/webtransport/ready/index.md +++ b/files/en-us/web/api/webtransport/ready/index.md @@ -27,10 +27,11 @@ A {{jsxref("Promise")}} that resolves to `undefined`. ```js const url = 'https://example.com:4999/wt'; -// Initialize transport connection -const transport = new WebTransport(url); -async function initTransport(transport) { +async function initTransport(url) { + // Initialize transport connection + const transport = new WebTransport(url); + // Respond to connection closing try { await transport.closed; diff --git a/files/en-us/web/api/webtransport/webtransport/index.md b/files/en-us/web/api/webtransport/webtransport/index.md index 314be567e28d6df..f6614294a0064c1 100644 --- a/files/en-us/web/api/webtransport/webtransport/index.md +++ b/files/en-us/web/api/webtransport/webtransport/index.md @@ -54,10 +54,11 @@ new WebTransport(url, options) ```js const url = 'https://example.com:4999/wt'; -// Initialize transport connection -const transport = new WebTransport(url); -async function initTransport(transport) { +async function initTransport(url) { + // Initialize transport connection + const transport = new WebTransport(url); + // Respond to connection closing try { await transport.closed; diff --git a/files/en-us/web/api/webtransport_api/index.md b/files/en-us/web/api/webtransport_api/index.md index 3dd7163b5e77596..d99af151a574da0 100644 --- a/files/en-us/web/api/webtransport_api/index.md +++ b/files/en-us/web/api/webtransport_api/index.md @@ -43,10 +43,11 @@ Also note that you can respond to the connection closing by waiting for the {{do ```js const url = 'https://example.com:4999/wt'; -// Initialize transport connection -const transport = new WebTransport(url); -async function initTransport(transport) { +async function initTransport(url) { + // Initialize transport connection + const transport = new WebTransport(url); + // Respond to connection closing try { await transport.closed; @@ -66,7 +67,7 @@ async function initTransport(transport) { "Unreliable" means that transmission of data is not guaranteed, nor is arrival in a specific order. This is fine in some situations and provides very fast delivery. For example, you might want to transmit regular game state updates where each message supersedes the last one that arrives, and order is not important. -Unreliable data transmission is handled via the {{domxref("WebTransport.datagram")}} property — this returns a {{domxref("WebTransportDatagramDuplexStream")}} object containing everything you need to send datagrams to the server, and receive them back. +Unreliable data transmission is handled via the {{domxref("WebTransport.datagrams")}} property — this returns a {{domxref("WebTransportDatagramDuplexStream")}} object containing everything you need to send datagrams to the server, and receive them back. The {{domxref("WebTransportDatagramDuplexStream.writable")}} property returns a {{domxref("WritableStream")}} object that you can write data to using a writer, for transmission to the server: @@ -120,7 +121,7 @@ async function writeData() { } ``` -Note also the use of the {{domxref("WritableStream.close()")}} method to close the associated HTTP/3 connection once all data has been sent. +Note also the use of the {{domxref("WritableStreamDefaultWriter.close()")}} method to close the associated HTTP/3 connection once all data has been sent. If the server opens a unidirectional stream to transmit data to the client, this can be accessed via the {{domxref("WebTransport.incomingUnidirectionalStreams")}} property, which returns a {{domxref("ReadableStream")}} of `WebTransportReceiveStream` objects. Each one can be used to read {{jsxref("Uint8Array")}} instances sent by the server. diff --git a/files/en-us/web/api/webtransportdatagramduplexstream/incominghighwatermark/index.md b/files/en-us/web/api/webtransportdatagramduplexstream/incominghighwatermark/index.md new file mode 100644 index 000000000000000..c9828293b29462c --- /dev/null +++ b/files/en-us/web/api/webtransportdatagramduplexstream/incominghighwatermark/index.md @@ -0,0 +1,61 @@ +--- +title: WebTransportDatagramDuplexStream.incomingHighWaterMark +slug: Web/API/WebTransportDatagramDuplexStream/incomingHighWaterMark +page-type: web-api-instance-property +tags: + - API + - Experimental + - incomingHighWaterMark + - Property + - Reference + - WebTransport + - WebTransport API +browser-compat: api.WebTransportDatagramDuplexStream.incomingHighWaterMark +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`incomingHighWaterMark`** property of the {{domxref("WebTransportDatagramDuplexStream")}} interface gets or sets the high water mark for incoming chunks of data — this is the maximum size, in chunks, that the incoming {{domxref("ReadableStream")}}'s internal queue can reach before it is considered full. See [Internal queues and queuing strategies](/en-US/docs/Web/API/Streams_API/Concepts#internal_queues_and_queuing_strategies) for more information. + +{{AvailableInWorkers}} + +## Value + +A number. + +## Examples + +```js +const url = 'https://example.com:4999/wt'; + +async function initTransport(url) { + // Initialize transport connection + const transport = new WebTransport(url); + + // The connection can be used once ready fulfills + await transport.ready; + + const datagrams = transport.datagrams; + + // set incomingHighWaterMark + datagrams.incomingHighWaterMark = 20000; + + // get incomingHighWaterMark + console.log(datagrams.incomingHighWaterMark); +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransportdatagramduplexstream/incomingmaxage/index.md b/files/en-us/web/api/webtransportdatagramduplexstream/incomingmaxage/index.md new file mode 100644 index 000000000000000..cb240581677de26 --- /dev/null +++ b/files/en-us/web/api/webtransportdatagramduplexstream/incomingmaxage/index.md @@ -0,0 +1,61 @@ +--- +title: WebTransportDatagramDuplexStream.incomingMaxAge +slug: Web/API/WebTransportDatagramDuplexStream/incomingMaxAge +page-type: web-api-instance-property +tags: + - API + - Experimental + - incomingMaxAge + - Property + - Reference + - WebTransport + - WebTransport API +browser-compat: api.WebTransportDatagramDuplexStream.incomingMaxAge +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`incomingMaxAge`** property of the {{domxref("WebTransportDatagramDuplexStream")}} interface gets or sets the maximum age for incoming datagrams, in milliseconds. + +{{AvailableInWorkers}} + +## Value + +A number, or `null` if no maximum age has been set. + +## Examples + +```js +const url = 'https://example.com:4999/wt'; + +async function initTransport(url) { + // Initialize transport connection + const transport = new WebTransport(url); + + // The connection can be used once ready fulfills + await transport.ready; + + const datagrams = transport.datagrams; + + // set incomingMaxAge + datagrams.incomingMaxAge = 2000; + + // get incomingMaxAge + console.log(datagrams.incomingMaxAge); +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransportdatagramduplexstream/index.md b/files/en-us/web/api/webtransportdatagramduplexstream/index.md index 9fc379e3054fc39..fee815fac28732f 100644 --- a/files/en-us/web/api/webtransportdatagramduplexstream/index.md +++ b/files/en-us/web/api/webtransportdatagramduplexstream/index.md @@ -16,7 +16,9 @@ browser-compat: api.WebTransportDatagramDuplexStream The **`WebTransportDatagramDuplexStream`** interface of the {{domxref("WebTransport API", "WebTransport API", "", "nocode")}} represents a duplex stream that can be used for unreliable transport of datagrams between client and server. Provides access to a {{domxref("ReadableStream")}} for reading incoming datagrams, a {{domxref("WritableStream")}} for writing outgoing datagrams, and various settings and statistics related to the stream. -This is accessed via the {{domxref("WebTransport.datagram")}} property. +This is accessed via the {{domxref("WebTransport.datagrams")}} property. + +"Unreliable" means that transmission of data is not guaranteed, nor is arrival in a specific order. This is fine in some situations and provides very fast delivery. For example, you might want to transmit regular game state updates where each message supersedes the last one that arrives, and order is not important. {{InheritanceDiagram}} diff --git a/files/en-us/web/api/webtransportdatagramduplexstream/maxdatagramsize/index.md b/files/en-us/web/api/webtransportdatagramduplexstream/maxdatagramsize/index.md new file mode 100644 index 000000000000000..9203df7c96330de --- /dev/null +++ b/files/en-us/web/api/webtransportdatagramduplexstream/maxdatagramsize/index.md @@ -0,0 +1,58 @@ +--- +title: WebTransportDatagramDuplexStream.maxDatagramSize +slug: Web/API/WebTransportDatagramDuplexStream/maxDatagramSize +page-type: web-api-instance-property +tags: + - API + - Experimental + - maxDatagramSize + - Property + - Reference + - WebTransport + - WebTransport API +browser-compat: api.WebTransportDatagramDuplexStream.maxDatagramSize +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`maxDatagramSize`** read-only property of the {{domxref("WebTransportDatagramDuplexStream")}} interface returns the maximum allowable size of outgoing datagrams, in bytes, that can be written to {{domxref("WebTransportDatagramDuplexStream.writable", "writable")}}. + +{{AvailableInWorkers}} + +## Value + +A number. + +## Examples + +```js +const url = 'https://example.com:4999/wt'; + +async function initTransport(url) { + // Initialize transport connection + const transport = new WebTransport(url); + + // The connection can be used once ready fulfills + await transport.ready; + + const datagrams = transport.datagrams; + + // get maxDatagramSize + console.log(datagrams.maxDatagramSize); +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransportdatagramduplexstream/outgoinghighwatermark/index.md b/files/en-us/web/api/webtransportdatagramduplexstream/outgoinghighwatermark/index.md new file mode 100644 index 000000000000000..525666558c9aaaa --- /dev/null +++ b/files/en-us/web/api/webtransportdatagramduplexstream/outgoinghighwatermark/index.md @@ -0,0 +1,61 @@ +--- +title: WebTransportDatagramDuplexStream.outgoingHighWaterMark +slug: Web/API/WebTransportDatagramDuplexStream/outgoingHighWaterMark +page-type: web-api-instance-property +tags: + - API + - Experimental + - outgoingHighWaterMark + - Property + - Reference + - WebTransport + - WebTransport API +browser-compat: api.WebTransportDatagramDuplexStream.outgoingHighWaterMark +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`outgoingHighWaterMark`** property of the {{domxref("WebTransportDatagramDuplexStream")}} interface gets or sets the high water mark for outgoing chunks of data — this is the maximum size, in chunks, that the outgoing {{domxref("WritableStream")}}'s internal queue can reach before it is considered full. See [Internal queues and queuing strategies](/en-US/docs/Web/API/Streams_API/Concepts#internal_queues_and_queuing_strategies) for more information. + +{{AvailableInWorkers}} + +## Value + +A number. + +## Examples + +```js +const url = 'https://example.com:4999/wt'; + +async function initTransport(url) { + // Initialize transport connection + const transport = new WebTransport(url); + + // The connection can be used once ready fulfills + await transport.ready; + + const datagrams = transport.datagrams; + + // set outgoingHighWaterMark + datagrams.outgoingHighWaterMark = 20000; + + // get outgoingHighWaterMark + console.log(datagrams.outgoingHighWaterMark); +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransportdatagramduplexstream/outgoingmaxage/index.md b/files/en-us/web/api/webtransportdatagramduplexstream/outgoingmaxage/index.md new file mode 100644 index 000000000000000..e30d4445ef242eb --- /dev/null +++ b/files/en-us/web/api/webtransportdatagramduplexstream/outgoingmaxage/index.md @@ -0,0 +1,60 @@ +--- +title: WebTransportDatagramDuplexStream.outgoingMaxAge +slug: Web/API/WebTransportDatagramDuplexStream/outgoingMaxAge +tags: + - API + - Experimental + - outgoingMaxAge + - Property + - Reference + - WebTransport + - WebTransport API +browser-compat: api.WebTransportDatagramDuplexStream.outgoingMaxAge +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`outgoingMaxAge`** property of the {{domxref("WebTransportDatagramDuplexStream")}} interface gets or sets the maximum age for outgoing datagrams, in milliseconds. + +{{AvailableInWorkers}} + +## Value + +A number, or `null` if no maximum age has been set. + +## Examples + +```js +const url = 'https://example.com:4999/wt'; + +async function initTransport(url) { + // Initialize transport connection + const transport = new WebTransport(url); + + // The connection can be used once ready fulfills + await transport.ready; + + const datagrams = transport.datagrams; + + // set outgoingMaxAge + datagrams.outgoingMaxAge = 2000; + + // get outgoingMaxAge + console.log(datagrams.outgoingMaxAge); +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransportdatagramduplexstream/readable/index.md b/files/en-us/web/api/webtransportdatagramduplexstream/readable/index.md new file mode 100644 index 000000000000000..9487930d2d6859f --- /dev/null +++ b/files/en-us/web/api/webtransportdatagramduplexstream/readable/index.md @@ -0,0 +1,45 @@ +--- +title: WebTransportDatagramDuplexStream.readable +slug: Web/API/WebTransportDatagramDuplexStream/readable +page-type: web-api-instance-property +tags: + - API + - Experimental + - Property + - readable + - Reference + - WebTransport + - WebTransport API +browser-compat: api.WebTransportDatagramDuplexStream.readable +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`readable`** read-only property of the {{domxref("WebTransportDatagramDuplexStream")}} interface returns a {{domxref("ReadableStream")}} instance that can be used to unreliably read incoming datagrams from the stream. + +"Unreliably" means that transmission of data is not guaranteed, nor is arrival in a specific order. This is fine in some situations and provides very fast delivery. For example, you might want to transmit regular game state updates where each message supersedes the last one that arrives, and order is not important. + +{{AvailableInWorkers}} + +## Value + +A {{domxref("ReadableStream")}}. + +## Examples + +See the main {{domxref("WebTransportDatagramDuplexStream")}} interface page. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransportdatagramduplexstream/writable/index.md b/files/en-us/web/api/webtransportdatagramduplexstream/writable/index.md new file mode 100644 index 000000000000000..15e44d120e4abb1 --- /dev/null +++ b/files/en-us/web/api/webtransportdatagramduplexstream/writable/index.md @@ -0,0 +1,45 @@ +--- +title: WebTransportDatagramDuplexStream.writable +slug: Web/API/WebTransportDatagramDuplexStream/writable +page-type: web-api-instance-property +tags: + - API + - Experimental + - Property + - Reference + - WebTransport + - WebTransport API + - writable +browser-compat: api.WebTransportDatagramDuplexStream.writable +--- + +{{APIRef("WebTransport API")}}{{seecompattable}}{{SecureContext_Header}} + +The **`writable`** read-only property of the {{domxref("WebTransportDatagramDuplexStream")}} interface returns a {{domxref("WritableStream")}} instance that can be used to unreliably write outgoing datagrams to the stream. + +"Unreliably" means that transmission of data is not guaranteed, nor is arrival in a specific order. This is fine in some situations and provides very fast delivery. For example, you might want to transmit regular game state updates where each message supersedes the last one that arrives, and order is not important. + +{{AvailableInWorkers}} + +## Value + +A {{domxref("WritableStream")}}. + +## Examples + +See the main {{domxref("WebTransportDatagramDuplexStream")}} interface page. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using WebTransport](https://web.dev/webtransport/) +- {{domxref("WebSockets API", "WebSockets API", "", "nocode")}} +- {{domxref("Streams API", "Streams API", "", "nocode")}} +- [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/) diff --git a/files/en-us/web/api/webtransporterror/index.md b/files/en-us/web/api/webtransporterror/index.md index 7ea74012cf8a574..ee1292dea149e23 100644 --- a/files/en-us/web/api/webtransporterror/index.md +++ b/files/en-us/web/api/webtransporterror/index.md @@ -37,23 +37,25 @@ _Inherits properties from its parent, {{DOMxRef("DOMException")}}._ ## Examples ```js -const url = 'https://example.com:4999/wt'; -// Initialize transport connection -const transport = new WebTransport(url); +const url = "notaurl"; + +async function initTransport(url) { -async function initTransport(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}.`); - } + // Initialize transport connection + const transport = new WebTransport(url); - // The connection can be used once ready fulfills - await transport.ready; + // The connection can be used once ready fulfills + await transport.ready; - // ... + // ... + } catch(error) { + const msg = `Transport initialization failed. + Reason: ${error.message}. + Source: ${error.source}. + Error code: ${error.streamErrorCode}.` + console.log(msg); + } } ``` diff --git a/files/en-us/web/api/webtransporterror/source/index.md b/files/en-us/web/api/webtransporterror/source/index.md index a583e637a7c4dc6..a77f4cce803a136 100644 --- a/files/en-us/web/api/webtransporterror/source/index.md +++ b/files/en-us/web/api/webtransporterror/source/index.md @@ -26,8 +26,26 @@ An enumerated value; can be either `stream` or `session`. ## Examples ```js -// some kind of WebTransport error -console.log(error.source) +const url = "notaurl"; + +async function initTransport(url) { + + try { + // Initialize transport connection + const transport = new WebTransport(url); + + // The connection can be used once ready fulfills + await transport.ready; + + // ... + } catch(error) { + const msg = `Transport initialization failed. + Reason: ${error.message}. + Source: ${error.source}. + Error code: ${error.streamErrorCode}.` + console.log(msg); + } +} ``` ## Specifications diff --git a/files/en-us/web/api/webtransporterror/streamerrorcode/index.md b/files/en-us/web/api/webtransporterror/streamerrorcode/index.md index e50e5ccce27d70f..b29a6c4cf4cd410 100644 --- a/files/en-us/web/api/webtransporterror/streamerrorcode/index.md +++ b/files/en-us/web/api/webtransporterror/streamerrorcode/index.md @@ -26,8 +26,26 @@ A number, or `null`. ## Examples ```js -// some kind of WebTransport error -console.log(error.streamErrorCode) +const url = "notaurl"; + +async function initTransport(url) { + + try { + // Initialize transport connection + const transport = new WebTransport(url); + + // The connection can be used once ready fulfills + await transport.ready; + + // ... + } catch(error) { + const msg = `Transport initialization failed. + Reason: ${error.message}. + Source: ${error.source}. + Error code: ${error.streamErrorCode}.` + console.log(msg); + } +} ``` ## Specifications diff --git a/files/en-us/web/api/webtransporterror/webtransporterror/index.md b/files/en-us/web/api/webtransporterror/webtransporterror/index.md index b8d5e8146f37099..b53d6f2b3ba40b8 100644 --- a/files/en-us/web/api/webtransporterror/webtransporterror/index.md +++ b/files/en-us/web/api/webtransporterror/webtransporterror/index.md @@ -38,7 +38,28 @@ new WebTransportError(init) A developer would not use this constructor manually. A new `WebTransportError` object is constructed when an error related to WebTransport occurs, for example a server error or network connection problem. -MAYBE INCLUDE A SMALL EXAMPLE HERE? +```js +const url = "notaurl"; + +async function initTransport(url) { + + try { + // Initialize transport connection + const transport = new WebTransport(url); + + // The connection can be used once ready fulfills + await transport.ready; + + // ... + } catch(error) { + const msg = `Transport initialization failed. + Reason: ${error.message}. + Source: ${error.source}. + Error code: ${error.streamErrorCode}.` + console.log(msg); + } +} +``` ## Specifications From 30ada9a018f0e200ab85fa82b774e32f16f939fc Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Mon, 19 Dec 2022 08:06:31 +0000 Subject: [PATCH 4/6] Update files/en-us/web/api/webtransport_api/index.md Co-authored-by: Michael[tm] Smith --- files/en-us/web/api/webtransport_api/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/webtransport_api/index.md b/files/en-us/web/api/webtransport_api/index.md index d99af151a574da0..4035ff782674a85 100644 --- a/files/en-us/web/api/webtransport_api/index.md +++ b/files/en-us/web/api/webtransport_api/index.md @@ -27,7 +27,7 @@ These include: - Head-of-line blocking: HTTP/2 allows multiplexing, so a single connection can stream multiple resources simultaneously. However, if a single resource fails, all other resources on that connection are held up until any missing packets are retransmitted. With QUIC, only the failing resource is affected. -- Faster performance: QUIC is more performant than TCP in many ways. QUIC can handle security features itself, rather than handling responsibility off to other protocols like TLS, meaning fewer round trips. And streams provide better transport efficiency than the older packet mechanism. This can make a significant difference, especially on high-latency networks. +- Faster performance: QUIC is more performant than TCP in many ways. QUIC can handle security features itself, rather than handing responsibility off to other protocols like TLS, meaning fewer round trips. And streams provide better transport efficiency than the older packet mechanism. This can make a significant difference, especially on high-latency networks. - Better network transitions: QUIC uses a unique connection ID to handle the source and destination of each request to ensure that packets are delivered correctly. This ID can persist between different networks, meaning that for example a download can continue interrupted if you switch from Wifi to a mobile network. HTTP/2 on the other hand uses IP addresses as identifiers, so network transitions can be problematic. From a054c75c92287aebcfb34e18f2dc095047eef8be Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Mon, 19 Dec 2022 08:06:42 +0000 Subject: [PATCH 5/6] Update files/en-us/web/api/webtransport_api/index.md Co-authored-by: Michael[tm] Smith --- files/en-us/web/api/webtransport_api/index.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/files/en-us/web/api/webtransport_api/index.md b/files/en-us/web/api/webtransport_api/index.md index 4035ff782674a85..f98045608bb055c 100644 --- a/files/en-us/web/api/webtransport_api/index.md +++ b/files/en-us/web/api/webtransport_api/index.md @@ -158,8 +158,6 @@ async function receiveUnidirectional() { } ``` -NOTE, NEED TO FIND OUT WHETHER THE CHUNKS ACTUALLY ARE WebTransportReceiveStream S, OR JUST READABLESTREAM OBJECTS, AS I'M NOT SURE RIGHT NOW. IT IS PRETTY DIFFICULT TO TEST THIS - #### Bidirectional transmission To open a bidirectional stream from a user agent, you use the {{domxref("WebTransport.createBidirectionalStream()")}} method to get a reference to a {{domxref("WebTransportBidirectionalStream")}}. In the same way as the {{domxref("WebTransportDatagramDuplexStream")}}, this contains `readable` and `writable` properties returning references to `ReadableStream` and `WritableStream` instances, which can be used to read from and write to the server. From 9534ed36622ac58c60ac60b0b8b88520585b89fd Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Mon, 19 Dec 2022 08:48:07 +0000 Subject: [PATCH 6/6] Update confusing basic example, and add explanation of close and abort behavior --- .../en-us/web/api/webtransport/closed/index.md | 16 ++++++++++------ .../createunidirectionalstream/index.md | 18 ++++++++++++++++++ files/en-us/web/api/webtransport/index.md | 16 ++++++++++------ .../en-us/web/api/webtransport/ready/index.md | 16 ++++++++++------ .../web/api/webtransport/webtransport/index.md | 18 ++++++++++-------- files/en-us/web/api/webtransport_api/index.md | 16 ++++++++++------ 6 files changed, 68 insertions(+), 32 deletions(-) diff --git a/files/en-us/web/api/webtransport/closed/index.md b/files/en-us/web/api/webtransport/closed/index.md index f11c7bb0d42d6d0..6a1493dcc14c609 100644 --- a/files/en-us/web/api/webtransport/closed/index.md +++ b/files/en-us/web/api/webtransport/closed/index.md @@ -37,18 +37,22 @@ async function initTransport(url) { // Initialize transport connection const transport = new WebTransport(url); - // Respond to connection closing + // The connection can be used once ready fulfills + await transport.ready; + + // ... +} + +// ... + +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}.`); } - - // The connection can be used once ready fulfills - await transport.ready; - - // ... } ``` diff --git a/files/en-us/web/api/webtransport/createunidirectionalstream/index.md b/files/en-us/web/api/webtransport/createunidirectionalstream/index.md index 6d3a4323d29b7d5..c8bd8f141b0870a 100644 --- a/files/en-us/web/api/webtransport/createunidirectionalstream/index.md +++ b/files/en-us/web/api/webtransport/createunidirectionalstream/index.md @@ -44,6 +44,8 @@ A {{domxref("WritableStream")}} object. Use the `createUnidirectionalStream()` method to get a reference to a {{domxref("WritableStream")}}. From this you can {{domxref("WritableStream.getWriter", "get a writer", "", "nocode")}} to allow data to be written to the stream and sent to the server. +Use the {{domxref("WritableStreamDefaultWriter.close", "close()")}} method of the resulting {{domxref("WritableStreamDefaultWriter")}} to close the associated HTTP/3 connection. The browser tries to send all pending data before actually closing the associated connection. + ```js async function writeData() { const stream = await transport.createUnidirectionalStream(); @@ -62,6 +64,22 @@ async function writeData() { } ``` +You can also use {{domxref("WritableStreamDefaultWriter.abort()")}} to abruptly terminate the stream. When using `abort()`, the browser may discard any pending data that hasn't yet been sent. + +```js +// ... + +const stream = await transport.createUnidirectionalStream(); +const writer = ws.getWriter(); + +// ... + +writer.write(...); +writer.write(...); +await writer.abort(); +// Not all the data may have been written. +``` + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/webtransport/index.md b/files/en-us/web/api/webtransport/index.md index 137af14f5663b07..2ac8b3adef35cad 100644 --- a/files/en-us/web/api/webtransport/index.md +++ b/files/en-us/web/api/webtransport/index.md @@ -60,18 +60,22 @@ async function initTransport(url) { // Initialize transport connection const transport = new WebTransport(url); - // Respond to connection closing + // The connection can be used once ready fulfills + await transport.ready; + + // ... +} + +// ... + +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}.`); } - - // The connection can be used once ready fulfills - await transport.ready; - - // ... } ``` diff --git a/files/en-us/web/api/webtransport/ready/index.md b/files/en-us/web/api/webtransport/ready/index.md index be0d0125405a8f5..ad43e3dc70b796a 100644 --- a/files/en-us/web/api/webtransport/ready/index.md +++ b/files/en-us/web/api/webtransport/ready/index.md @@ -32,18 +32,22 @@ async function initTransport(url) { // Initialize transport connection const transport = new WebTransport(url); - // Respond to connection closing + // The connection can be used once ready fulfills + await transport.ready; + + // ... +} + +// ... + +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}.`); } - - // The connection can be used once ready fulfills - await transport.ready; - - // ... } ``` diff --git a/files/en-us/web/api/webtransport/webtransport/index.md b/files/en-us/web/api/webtransport/webtransport/index.md index f6614294a0064c1..70ccab35a6bd6f0 100644 --- a/files/en-us/web/api/webtransport/webtransport/index.md +++ b/files/en-us/web/api/webtransport/webtransport/index.md @@ -50,8 +50,6 @@ new WebTransport(url, options) ## Examples -### Basic connection - ```js const url = 'https://example.com:4999/wt'; @@ -59,18 +57,22 @@ async function initTransport(url) { // Initialize transport connection const transport = new WebTransport(url); - // Respond to connection closing + // The connection can be used once ready fulfills + await transport.ready; + + // ... +} + +// ... + +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}.`); } - - // The connection can be used once ready fulfills - await transport.ready; - - // ... } ``` diff --git a/files/en-us/web/api/webtransport_api/index.md b/files/en-us/web/api/webtransport_api/index.md index f98045608bb055c..846f04f173e6a8d 100644 --- a/files/en-us/web/api/webtransport_api/index.md +++ b/files/en-us/web/api/webtransport_api/index.md @@ -48,18 +48,22 @@ async function initTransport(url) { // Initialize transport connection const transport = new WebTransport(url); - // Respond to connection closing + // The connection can be used once ready fulfills + await transport.ready; + + // ... +} + +// ... + +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}.`); } - - // The connection can be used once ready fulfills - await transport.ready; - - // ... } ```