Merge 2e6ca16 into 05fe933

mdn · Nov 15, 2022 · 45c419a · 45c419a
2 parents 05fe933 + 2e6ca16
commit 45c419a
Show file tree

Hide file tree

Showing 20 changed files with 1,563 additions and 0 deletions.
diff --git a/files/en-us/web/api/webtransport/close/index.md 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
@@ -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
@@ -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
@@ -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
@@ -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/)