adding docs for WebTransport (#22310)

Fixes #22281

files/en-us/web/api/webtransport/close/index.md

@@ -0,0 +1,74 @@
+---
+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/)

files/en-us/web/api/webtransport/closed/index.md

@@ -0,0 +1,72 @@
+---
+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';
+
+async function initTransport(url) {
+  // Initialize transport connection
+  const transport = new WebTransport(url);
+
+  // 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}.`);
+  }
+}
+```
+
+## 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/)

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

files/en-us/web/api/webtransport/createunidirectionalstream/index.md

@@ -0,0 +1,96 @@
+---
+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", "", "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();
+  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}`);
+  }
+}
+```
+
+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}}
+
+## 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/)