Direct Sockets API

This specification defines an API that allows web applications to talk to servers and devices that have their own protocols incompatible with those available on the web.

{{TCPSocket}} interface

      [Exposed=(Window,Worker), SecureContext]
      interface TCPSocket {
        constructor(DOMString remoteAddress,
                    unsigned short remotePort,
                    optional TCPSocketOptions options = {});

        readonly attribute Promise<TCPSocketOpenInfo> opened;
        readonly attribute Promise<undefined> closed;

        Promise<undefined> close();
      };

Methods on this interface typically complete asynchronously, queuing work on the TCPSocket task source.

Instances of {{TCPSocket}} are created with the internal slots described in the following table:

Internal slot	Initial value	Description (non-normative)
[[\readable]]	`null`	A {{ReadableStream}} that receives data from the socket
[[\writable]]	`null`	A {{WritableStream}} that transmits data to the socket
[[\openedPromise]]	`new Promise`	A {{Promise}} used to wait for the socket to be opened. Corresponds to the {{TCPSocket/opened}} member.
[[\closedPromise]]	`new Promise`	A {{Promise}} used to wait for the socket to close or error. Corresponds to the {{TCPSocket/closed}} member.

constructor() method

In order to communicate via TCP a socket connection must be requested first. The socket object constructor allows the site to specify the necessary parameters which control how data is transmitted and received.

          const socket = new TCPSocket(/*remoteAddress=*/, /*remotePort=*/, /*options=*/);

The developer should wait for the {{TCPSocket/opened}} promise to be resolved to gain access to {{TCPSocketOpenInfo/readable}} and {{TCPSocketOpenInfo/writable}} streams.

          const { readable, writable } = await socket.opened;

Once {{TCPSocket/opened}} has resolved, the {{TCPSocketOpenInfo/readable}} and {{TCPSocketOpenInfo/writable}} can be accessed to get the {{ReadableStream}} and {{WritableStream}} instances for receiving data from and sending data to the socket.

The {{TCPSocket/constructor()}} steps are:

If [=this=]'s [=relevant global object=]'s [=associated Document=] is not [=allowed to use=] the [=policy-controlled feature=] named "[=policy-controlled feature/direct-sockets=]", throw a "{{NotAllowedError}}" {{DOMException}}.
If |options|["{{TCPSocketOptions/keepAliveDelay}}"] is less than 1,000, throw a {{TypeError}}.
If |options|["{{TCPSocketOptions/sendBufferSize}}"] is equal to 0, throw a {{TypeError}}.
If |options|["{{TCPSocketOptions/receiveBufferSize}}"] is equal to 0, throw a {{TypeError}}.
Perform the following steps [=in parallel=].
1. Invoke the operating system to open the TCP socket using the given |remoteAddress| and |remotePort| and the connection parameters (or their defaults) specified in |options|.
2. If this fails for any reason, [=queue a global task=] on the [=relevant global object=] of [=this=] using the [=TCPSocket task source=] to run the following steps:
  1. [=Reject=] the {{TCPSocket/[[openedPromise]]}} with a "{{NetworkError}}" {{DOMException}}.
  2. [=Reject=] the {{TCPSocket/[[closedPromise]]}} with a "{{NetworkError}}" {{DOMException}}.
3. On success, [=queue a global task=] on the [=relevant global object=] of [=this=] using the [=TCPSocket task source=] to run the following steps:
  1. [=initialize TCPSocket readable stream|Initialize=] {{TCPSocket/[[readable]]}}.
  2. [=initialize TCPSocket writable stream|Initialize=] {{TCPSocket/[[writable]]}}.
  3. Let |openInfo:TCPSocketOpenInfo| be a new {{TCPSocketOpenInfo}}.
  4. Set |openInfo|["{{TCPSocketOpenInfo/readable}}"] to [=this=].{{TCPSocket/[[readable]]}}.
  5. Set |openInfo|["{{TCPSocketOpenInfo/writable}}"] to [=this=].{{TCPSocket/[[writable]]}}.
  6. Populate the remaining fields of |openInfo| using the information provided by the operating system: |openInfo|["{{TCPSocketOpenInfo/remoteAddress}}"], |openInfo|["{{TCPSocketOpenInfo/remotePort}}"], |openInfo|["{{TCPSocketOpenInfo/localAddress}}"] and |openInfo|["{{TCPSocketOpenInfo/localPort}}"].
  7. [=Resolve=] [=this=].{{TCPSocket/[[openedPromise]]}} with |openInfo|.

TCPSocketOptions dictionary

          dictionary TCPSocketOptions {
            [EnforceRange] unsigned long sendBufferSize;
            [EnforceRange] unsigned long receiveBufferSize;

            boolean noDelay = false;
            [EnforceRange] unsigned long keepAliveDelay;
          };

sendBufferSize member

The requested send buffer size, in bytes. If not specified, then platform-specific default value will be used.

receiveBufferSize member

The requested receive buffer size, in bytes. If not specified, then platform-specific default value will be used.

noDelay member

Enables the `TCP_NODELAY` option, disabling Nagle's algorithm.

No-Delay is disabled by default.

keepAliveDelay member

If specified, enables TCP Keep-Alive by setting `SO_KEEPALIVE` option on the socket to `true`. The way the actual delay is set is platform-specific:

On Linux & ChromeOS `keepAliveDelay` is applied to `TCP_KEEPIDLE` and `TCP_KEEPINTVL`;
On MacOS `keepAliveDelay` affects `TCP_KEEPALIVE`;
On Windows `keepAliveDelay` is replicated to `keepalivetime` and `keepaliveinterval` of `SIO_KEEPALIVE_VALS`.

Keep-Alive is disabled by default.

{{TCPSocket/[[readable]]}} attribute (internal)

An application receiving data from a TCP socket will typically use the {{ReadableStream}} like this:

          const { readable } = await socket.opened;

          const reader = readable.getReader();

          while (true) {
            const { value, done } = await reader.read();
            if (done) {
              // |reader| has been canceled.
              break;
            }
            // Do something with |value|...
          }

          reader.releaseLock();

The steps to initialize the TCPSocket readable stream are:

Let |stream:ReadableStream| be a [=new=] {{ReadableStream}}.
Let |pullAlgorithm| be the following steps:
1. Let |desiredSize| be the desired size of [=this=].{{TCPSocket/[[readable]]}}'s internal queue.
2. Run the following steps in parallel:
  1. Invoke the operating system to read up to |desiredSize| bytes from the socket, placing the result in the [=byte sequence=] |bytes|.
  2. [=Queue a global task=] on the [=relevant global object=] of [=this=] using the [=TCPSocket task source=] to run the following steps:
    1. If the connection was closed gracefully, run the following steps:
      1. Invoke [=ReadableStream/close=] on [=this=].{{TCPSocket/[[readable]]}}.
      2. Invoke the steps to [=handle closing the TCPSocket readable stream=].
      This is triggered by the peer sending a packet with the FIN flag set and is typically indicated by the operating system returning 0 bytes when asked for more data from the socket.
    2. If no errors were encountered run the following steps:
      1. Let |buffer| be a [=new=] {{ArrayBuffer}} created from |bytes|.
      2. Let |chunk| be a [=new=] {{Uint8Array}} view over |buffer|, who's length is the length of |bytes|.
      3. Invoke [=ReadableStream/enqueue=] on [=this=].{{TCPSocket/[[readable]]}} with |chunk|.
    3. If a network or operating system error was encountered, invoke [=ReadableStream/error=] on [=this=].{{TCPSocket/[[readable]]}} with a "{{NetworkError}}" {{DOMException}} and invoke the steps to [=handle closing the TCPSocket readable stream=].
3. Return [=a promise resolved with=] `undefined`.
Let |cancelAlgorithm| be the following steps:
1. Invoke the steps to [=handle closing the TCPSocket readable stream=].
2. Return [=a promise resolved with=] `undefined`.
[=ReadableStream/Set up=] |stream| with pullAlgorithm set to |pullAlgorithm|, cancelAlgorithm set to |cancelAlgorithm|, highWaterMark set to an implementation-defined value.
Set [=this=].{{TCPSocket/[[readable]]}} to |stream|.

To handle closing the TCPSocket readable stream perform the following steps:

If [=this=].{{TCPSocket/[[writable]]}} is active, abort these steps.
Run the following steps [=in parallel=].
1. Invoke the operating system to close the socket.
2. [=Queue a global task=] on the [=relevant global object=] of [=this=] using the [=TCPSocket task source=] to run the following steps:
  - If [=this=].{{TCPSocket/[[writable]]}} is errored, [=reject=] [=this=].{{TCPSocket/[[closedPromise]]}} with [=this=].{{TCPSocket/[[writable]]}}.`[[storedPromise]]`.
  - Otherwise, if [=this=].{{TCPSocket/[[readable]]}} is errored, [=reject=] [=this=].{{TCPSocket/[[closedPromise]]}} with [=this=].{{TCPSocket/[[readable]]}}.`[[storedPromise]]`.
  - Otherwise, [=resolve=] [=this=].{{TCPSocket/[[closedPromise]]}} with `undefined`.

{{TCPSocket/[[writable]]}} attribute (internal)

To write individual chunks of data to the socket a {{WritableStreamDefaultWriter}} can be created and released as necessary. This example uses a `TextEncoder` to encode a {{DOMString}} as the necessary {{Uint8Array}} for transmission.

          const encoder = new TextEncoder();

          const { writable } = await socket.opened;
          const writer = writable.getWriter();

          await writer.write(encoder.encode("PING"));

          writer.releaseLock();

The {{WritableStreamDefaultWriter/write()}} method returns a {{Promise}} which resolves when data has been written. While having some data available in the transmit buffer is important to maintain good throughput awaiting this {{Promise}} before generating too many chunks of data is a good practice to avoid excessive buffering.

The steps to initialize the TCPSocket writable stream are:

Let |stream:WritableStream| be a [=new=] {{WritableStream}}.
Let |signal:AbortSignal| be |stream|'s [=WritableStream/signal=].
Let |writeAlgorithm| be the following steps, given |chunk|:
1. Let |promise:Promise| be [=a new promise=].
2. Assert: |signal| is not [=AbortSignal/aborted=].
3. If |chunk| cannot be [=converted to an IDL value=] of type {{BufferSource}}, reject |promise| with a {{TypeError}} and return |promise|. Otherwise, save the result of the conversion in |source:BufferSource|.
4. [=Get a copy of the buffer source=] |source| and save the result in |bytes|.
5. [=In parallel=], run the following steps:
  1. Invoke the operating system to write |bytes| to the socket.
    The operating system may return from this operation once |bytes| has been queued for transmission rather than after it has been transmitted.
  2. [=Queue a global task=] on the [=relevant global object=] of [=this=] using the [=TCPSocket task source=] to run the following steps:
    1. If the chunk was successfully written, [=resolve=] |promise| with `undefined`.
      [[STREAMS]] specifies that |writeAlgorithm| will only be invoked after the {{Promise}} returned by a previous invocation of this algorithm has resolved. For efficiency an implementation is allowed to resolve this {{Promise}} early in order to coalesce multiple chunks waiting in the {{WritableStream}}'s internal queue into a single request to the operating system.
    2. If a network or operating system error was encountered:
      1. [=Reject=] |promise| with a "{{NetworkError}}" {{DOMException}}.
      2. Invoke the steps to [=handle closing the TCPSocket writable stream=].
    3. If |signal| is [=AbortSignal/aborted=], [=reject=] |promise| with |signal|'s [=AbortSignal/abort reason=].
6. Return |promise|.
Let |abortAlgorithm| be the following steps:
1. Let |promise| be [=a new promise=].
2. Run the following steps [=in parallel=]:
  1. Invoke the operating system to shutdown the socket for writing.
  2. [=Queue a global task=] on the [=relevant global object=] of [=this=] using the [=TCPSocket task source=] to run the following steps:
    1. Invoke the steps to [=handle closing the TCPSocket writable stream=].
    2. [=Resolve=] |promise| with `undefined`.
3. Return |promise|.
Let |closeAlgorithm| be the following steps:
1. Let |promise| be [=a new promise=].
2. Run the following steps [=in parallel=].
  1. Invoke the operating system to shutdown the socket for writing.
  2. [=Queue a global task=] on the [=relevant global object=] of [=this=] using the [=TCPSocket task source=] to run the following steps:
    1. Invoke the steps to [=handle closing the TCPSocket writable stream=].
    2. If |signal| is [=AbortSignal/aborted=], [=reject=] |promise| with |signal|'s [=AbortSignal/abort reason=].
    3. [=Resolve=] |promise| with `undefined`.
3. Return |promise|.
[=WritableStream/Set up=] |stream| with writeAlgorithm set to |writeAlgorithm|, abortAlgorithm set to |abortAlgorithm|, closeAlgorithm set to |closeAlgorithm|, highWaterMark set to an implementation-defined value.
[=AbortSignal/Add=] the following abort steps to |signal|:
1. Cause any invocation of the operating system to write to the socket to return as soon as possible no matter how much data has been written.
Set [=this=].{{TCPSocket/[[writable]]}} to |stream|.

To handle closing the TCPSocket writable stream perform the following steps:

If [=this=].{{TCPSocket/[[readable]]}} is active, abort these steps.
Run the following steps [=in parallel=].
1. Invoke the operating system to close the socket.
2. [=Queue a global task=] on the [=relevant global object=] of [=this=] using the [=TCPSocket task source=] to run the following steps:
  - If [=this=].{{TCPSocket/[[readable]]}} is errored, [=reject=] [=this=].{{TCPSocket/[[closedPromise]]}} with [=this=].{{TCPSocket/[[readable]]}}.`[[storedPromise]]`.
  - Otherwise, if [=this=].{{TCPSocket/[[writable]]}} is errored, [=reject=] [=this=].{{TCPSocket/[[closedPromise]]}} with [=this=].{{TCPSocket/[[writable]]}}.`[[storedPromise]]`.
  - Otherwise, [=resolve=] [=this=].{{TCPSocket/[[closedPromise]]}} with `undefined`.

opened attribute

The {{TCPSocket/opened}} is an attribute containing all information about the socket. Once it is resolved, the developer can use the {{TCPSocketOpenInfo/readable}} and {{TCPSocketOpenInfo/writable}} to read from and write to the socket.

          const { readable, writable } = await socket.opened;

          const reader = readable.getReader();
          // Read from the socket using |reader|...

          const writer = writable.getWriter();
          // Write to the socket using |writer|...

When called, returns the [=this=].{{TCPSocket/[[openedPromise]]}}.

TCPSocketOpenInfo dictionary

          dictionary TCPSocketOpenInfo {
            ReadableStream readable;
            WritableStream writable;

            DOMString remoteAddress;
            unsigned short remotePort;

            DOMString localAddress;
            unsigned short localPort;
          };

readable member: The readable side of the socket. Set to {{TCPSocket/[[readable]]}}.
writable member: The writable side of the socket. Set to {{TCPSocket/[[writable]]}}.
remoteAddress member: Resolved remote IP address that the socket is connected to.
remotePort member: Remote port that the socket is connected to.
localAddress member: Local IP address that the socket is bound to.
localPort member: Local port that the socket is bound to.

closed attribute

The {{TCPSocket/closed}} is an attribute that keeps track of the socket state. It gets resolved if the socket is closed gracefully (i.e. by the user) or rejected in case of an error.

          socket.closed.then(() => console.log("Closed"), () => console.log("Errored"));

Note that {{TCPSocket/closed}} will be automatically rejected or resolved once both {{TCPSocket/[[readable]]}} and {{TCPSocket/[[writable]]}} reach a closed or errored state.

When called, returns the [=this=].{{TCPSocket/[[closedPromise]]}}.

close() method

When communication with the port is no longer required it can be closed and the associated resources released by the system.

Calling `socket.`{{TCPSocket/close()}} implicitly invokes `opened.`{{TCPSocketOpenInfo/readable}}`.`{{ReadableStream/cancel()}} and `opened.`{{TCPSocketOpenInfo/writable}}`.`{{WritableStream/abort()}} in order to clear any buffered data. If the application has called `opened.`{{TCPSocketOpenInfo/readable}}`.`{{ReadableStream/getReader()}} or `opened.`{{TCPSocketOpenInfo/writable}}`.`{{WritableStream/getWriter()}} the stream is locked and the socket cannot be closed. This forces the developer to decide how to handle any read or write operations that are in progress. For example, to ensure that all buffered data has been transmitted before the socket is closed the application must await the {{Promise}} returned by `writer.`{{WritableStreamDefaultWriter/close()}}.

          const encoder = new TextEncoder();
          const { writable } = await socket.opened;
          const writer = writable.getWriter();

          writer.write(encoder.encode("A long message that will take..."));
          await writer.close();
          await socket.close();

To discard any unsent data the application could instead call `writer.`{{WritableStreamDefaultWriter/abort()}}. If a loop is being used to read data from the socket, then it must be exited before calling `socket`.{{TCPSocket/close()}}.

          const { readable } = await socket.opened;
          const reader = readable.getReader();

          async function readUntilClosed() {
            while (true) {
              const { value, done } = await reader.read();
              if (done) {
                // |reader| has been canceled.
                break;
              }
              // Do something with |value|...
            }

            await socket.close();
          }

          const read_complete = readUntilClosed();

          // Sometime later...
          reader.releaseLock();
          await read_complete;

The {{TCPSocket/close()}} method steps are:

If [=this=].{{TCPSocket/[[openedPromise]]}} is rejected or not yet resolved, [=reject=] with "{{InvalidStateError}}" {{DOMException}}.
If [=this=].{{TCPSocket/[[closedPromise]]}} is settled, return [=this=].{{TCPSocket/[[closedPromise]]}}.
If [=this=].{{TCPSocket/[[readable]]}} or [=this=].{{TCPSocket/[[writable]]}} are locked, [=reject=] with "{{InvalidStateError}}" {{DOMException}}.
Let |cancelPromise:Promise| be the result of invoking [=ReadableStream/cancel=] on [=this=].{{TCPSocket/[[readable]]}}.
Set |cancelPromise|.[[\PromiseIsHandled]] to true.
Let |abortPromise:Promise| be the result of invoking [=WritableStream/abort=] on [=this=].{{TCPSocket/[[writable]]}}.
Set |abortPromise|.[[\PromiseIsHandled]] to true.
Return [=this=].{{TCPSocket/[[closedPromise]]}}.

{{UDPSocket}} interface

      [Exposed=(Window,Worker), SecureContext]
      interface UDPSocket {
        constructor(UDPSocketOptions options);

        readonly attribute Promise<UDPSocketOpenInfo> opened;
        readonly attribute Promise<undefined> closed;

        Promise<undefined> close();
      };

Methods on this interface typically complete asynchronously, queuing work on the UDPSocket task source.

Instances of {{UDPSocket}} are created with the internal slots described in the following table:

Internal slot	Initial value	Description (non-normative)
[[\readable]]	`null`	A {{ReadableStream}} that receives data from the socket
[[\writable]]	`null`	A {{WritableStream}} that transmits data to the socket
[[\openedPromise]]	`new Promise`	A {{Promise}} used to wait for the socket to be opened. Corresponds to the {{UDPSocket/opened}} member.
[[\closedPromise]]	`new Promise`	A {{Promise}} used to wait for the socket to close or error. Corresponds to the {{UDPSocket/closed}} member.

constructor() method

In order to communicate via UDP a socket must be opened first. The socket object constructor allows the site to specify the necessary parameters which control how data is transmitted and received.

          const socket = new UDPSocket(/*remoteAddress=*/, /*remotePort=*/, /*options=*/);

The developer should wait for the {{UDPSocket/opened}} promise to be resolved to gain access to {{UDPSocketOpenInfo/readable}} and {{UDPSocketOpenInfo/writable}} streams.

          const { readable, writable } = await socket.opened;

Once {{UDPSocket/opened}} has resolved, the {{UDPSocketOpenInfo/readable}} and {{UDPSocketOpenInfo/writable}} can be accessed to get the {{ReadableStream}} and {{WritableStream}} instances for receiving data from and sending data to the socket.

The {{UDPSocket/constructor()}} steps are:

If [=this=]'s [=relevant global object=]'s [=associated Document=] is not [=allowed to use=] the [=policy-controlled feature=] named "[=policy-controlled feature/direct-sockets=]", throw a "{{NotAllowedError}}" {{DOMException}}.
If |options|["{{UDPSocketOptions/sendBufferSize}}"] is equal to 0, throw a {{TypeError}}.
If |options|["{{UDPSocketOptions/receiveBufferSize}}"] is equal to 0, throw a {{TypeError}}.
Perform the following steps [=in parallel=].
1. Invoke the operating system to open the UDP socket using the given |remoteAddress| and |remotePort| and the parameters (or their defaults) specified in |options|.
2. If this fails for any reason, [=queue a global task=] on the [=relevant global object=] of [=this=] using the [=UDPSocket task source=] to run the following steps:
  1. [=Reject=] the {{UDPSocket/[[openedPromise]]}} with a "{{NetworkError}}" {{DOMException}}.
  2. [=Reject=] the {{UDPSocket/[[closedPromise]]}} with a "{{NetworkError}}" {{DOMException}}.
3. On success, [=queue a global task=] on the [=relevant global object=] of [=this=] using the [=UDPSocket task source=] to run the following steps:
  1. [=initialize UDPSocket readable stream|Initialize=] {{UDPSocket/[[readable]]}}.
  2. [=initialize UDPSocket writable stream|Initialize=] {{UDPSocket/[[writable]]}}.
  3. Let |openInfo:UDPSocketOpenInfo| be a new {{UDPSocketOpenInfo}}.
  4. Set |openInfo|["{{UDPSocketOpenInfo/readable}}"] to [=this=].{{UDPSocket/[[readable]]}}.
  5. Set |openInfo|["{{UDPSocketOpenInfo/writable}}"] to [=this=].{{UDPSocket/[[writable]]}}.
  6. Populate the remaining fields of |openInfo| using the information provided by the operating system: |openInfo|["{{UDPSocketOpenInfo/remoteAddress}}"], |openInfo|["{{UDPSocketOpenInfo/remotePort}}"], |openInfo|["{{UDPSocketOpenInfo/localAddress}}"] and |openInfo|["{{UDPSocketOpenInfo/localPort}}"].
  7. Resolve [=this=].{{UDPSocket/[[openedPromise]]}} with |openInfo|.

UDPSocketOptions dictionary

          dictionary UDPSocketOptions {
            required DOMString remoteAddress;
            [EnforceRange] required unsigned short remotePort;

            [EnforceRange] unsigned long sendBufferSize;
            [EnforceRange] unsigned long receiveBufferSize;
          };

remoteAddress member: The remote IP address to connect the socket to.
remotePort member: The remote port to connect the socket to.
sendBufferSize member: The requested send buffer size, in bytes. If not specified, then platform-specific default value will be used.
receiveBufferSize member: The requested receive buffer size, in bytes. If not specified, then platform-specific default value will be used.

{{UDPSocket/[[readable]]}} attribute (internal)

An application receiving data from a UDP socket will typically use the {{ReadableStream}} like this:

          const { readable } = await socket.opened;

          const reader = readable.getReader();

          while (true) {
            const { value, done } = await reader.read();
            if (done) {
              // |reader| has been canceled.
              break;
            }
            const { data } = value;
            // Do something with |data|...
          }

          reader.releaseLock();

The steps to initialize the UDPSocket readable stream are:

Let |stream:ReadableStream| be a [=new=] {{ReadableStream}}.
Let |pullAlgorithm| be the following steps:
1. Let |desiredSize| be the desired size of [=this=].{{UDPSocket/[[readable]]}}'s internal queue.
2. Run the following steps in parallel:
  1. Invoke the operating system to provide up to |desiredSize| UDP packets from the socket.
  2. [=Queue a global task=] on the [=relevant global object=] of [=this=] using the [=UDPSocket task source=] to run the following steps for each received packet:
    1. If no errors were encountered, for each packet received run the following steps:
      1. Let |bytes| be a [=byte sequence=] containing the packet payload.
      2. Let |buffer| be a [=new=] {{ArrayBuffer}} created from |bytes|.
      3. Let |chunk| be a [=new=] {{Uint8Array}} view over |buffer|, who's length is the length of |bytes|.
      4. Let |message:UDPMessage| be a new {{UDPMessage}}.
      5. Set |message|["{{UDPMessage/data}}"] to |chunk|.
      6. Set |message|["{{UDPMessage/remoteAddress}}"] to the source address of the packet.
      7. Set |message|["{{UDPMessage/remotePort}}"] to the source port of the packet.
      8. Invoke [=ReadableStream/enqueue=] on [=this=].{{UDPSocket/[[readable]]}} with |message|.
    2. If a network or operating system error was encountered, invoke [=ReadableStream/error=] on [=this=].{{UDPSocket/[[readable]]}} with a "{{NetworkError}}" {{DOMException}}, discard other packets and invoke the steps to [=handle closing the UDPSocket readable stream=].
3. Return [=a promise resolved with=] `undefined`.
Let |cancelAlgorithm| be the following steps:
1. Invoke the steps to [=handle closing the UDPSocket readable stream=].
2. Return [=a promise resolved with=] `undefined`.
[=ReadableStream/Set up=] |stream| with pullAlgorithm set to |pullAlgorithm|, cancelAlgorithm set to |cancelAlgorithm|, highWaterMark set to an implementation-defined value.
Set [=this=].{{UDPSocket/[[readable]]}} to |stream|.

To handle closing the UDPSocket readable stream perform the following steps:

If [=this=].{{UDPSocket/[[writable]]}} is active, abort these steps.
Run the following steps [=in parallel=].
1. Invoke the operating system to close the socket.
2. [=Queue a global task=] on the [=relevant global object=] of [=this=] using the [=UDPSocket task source=] to run the following steps:
  - If [=this=].{{UDPSocket/[[writable]]}} is errored, [=reject=] [=this=].{{UDPSocket/[[closedPromise]]}} with [=this=].{{UDPSocket/[[writable]]}}.`[[storedPromise]]`.
  - Otherwise, if [=this=].{{UDPSocket/[[readable]]}} is errored, [=reject=] [=this=].{{UDPSocket/[[closedPromise]]}} with [=this=].{{UDPSocket/[[readable]]}}.`[[storedPromise]]`.
  - Otherwise, [=resolve=] [=this=].{{UDPSocket/[[closedPromise]]}} with `undefined`.

UDPMessage dictionary

          dictionary UDPMessage {
            BufferSource data;
            DOMString remoteAddress;
            unsigned short remotePort;
          };

data member: The user message represented as {{BufferSource}}.
Note that for {{UDPSocket/[[readable]]}} the underlying type is always {{Uint8Array}}.
remoteAddress member: The remote address where the message came from.
remotePort member: The remote port where the message came from.

{{UDPSocket/[[writable]]}} attribute (internal)

          const encoder = new TextEncoder();

          const { writable } = await socket.opened;
          const writer = writable.getWriter();

          const message = {
            data: encoder.encode("PING")
          };

          await writer.write(message);

          writer.releaseLock();

The steps to initialize the UDPSocket writable stream are:

Let |stream:WritableStream| be a [=new=] {{WritableStream}}.
Let |signal:AbortSignal| be |stream|'s [=WritableStream/signal=].
Let |writeAlgorithm| be the following steps, given |chunk|:
1. Let |promise:Promise| be [=a new promise=].
2. Assert: |signal| is not [=AbortSignal/aborted=].
3. Let |message:UDPMessage| be a new {{UDPMessage}}.
4. If |chunk| cannot be [=converted to an IDL value=] of type {{UDPMessage}}, reject |promise| with a {{TypeError}} and return |promise|. Otherwise, save the result of the conversion in |message|.
5. If either |message|["{{UDPMessage/remoteAddress}}"] or |message|["{{UDPMessage/remotePort}}"] is specified, reject |promise| with a {{TypeError}} and return |promise|.
  The |message|["{{UDPMessage/remoteAddress}}"] and |message|["{{UDPMessage/remotePort}}"] currently have no effect on sending packets since the UDP socket is only allowed to operate in the connected mode.
6. [=Get a copy of the buffer source=] |message|["{{UDPMessage/data}}"] and save the result in |bytes|.
7. [=In parallel=], run the following steps:
  1. Invoke the operating system to send |bytes| to the socket.
    The operating system may return from this operation once |bytes| has been queued for transmission rather than after it has been transmitted.
  2. [=Queue a global task=] on the [=relevant global object=] of [=this=] using the [=UDPSocket task source=] to run the following steps:
    1. If the data was successfully written, [=resolve=] |promise| with `undefined`.
    2. If a network or operating system error was encountered:
      1. [=Reject=] |promise| with a "{{NetworkError}}" {{DOMException}}.
      2. Invoke the steps to [=handle closing the UDPSocket writable stream=].
    3. If |signal| is [=AbortSignal/aborted=], [=reject=] |promise| with |signal|'s [=AbortSignal/abort reason=].
8. Return |promise|.
Let |abortAlgorithm| be the following steps:
1. Invoke the steps to [=handle closing the UDPSocket writable stream=].
2. Return [=a promise resolved with=] `undefined`.
Let |closeAlgorithm| be the following steps:
1. Invoke the steps to [=handle closing the UDPSocket writable stream=].
2. Return [=a promise resolved with=] `undefined`.
[=WritableStream/Set up=] |stream| with writeAlgorithm set to |writeAlgorithm|, abortAlgorithm set to |abortAlgorithm|, closeAlgorithm set to |closeAlgorithm|, highWaterMark set to an implementation-defined value.
[=AbortSignal/Add=] the following abort steps to |signal|:
1. Cause any invocation of the operating system to write to the socket to return as soon as possible no matter how much data has been written.
Set [=this=].{{UDPSocket/[[writable]]}} to |stream|.

To handle closing the UDPSocket writable stream perform the following steps:

If [=this=].{{UDPSocket/[[readable]]}} is active, abort these steps.
Run the following steps [=in parallel=].
1. Invoke the operating system to close the socket.
2. [=Queue a global task=] on the [=relevant global object=] of [=this=] using the [=UDPSocket task source=] to run the following steps:
  - If [=this=].{{UDPSocket/[[readable]]}} is errored, [=reject=] [=this=].{{UDPSocket/[[closedPromise]]}} with [=this=].{{UDPSocket/[[readable]]}}.`[[storedPromise]]`.
  - Otherwise, if [=this=].{{UDPSocket/[[writable]]}} is errored, [=reject=] [=this=].{{UDPSocket/[[closedPromise]]}} with [=this=].{{UDPSocket/[[writable]]}}.`[[storedPromise]]`.
  - Otherwise, [=resolve=] [=this=].{{UDPSocket/[[closedPromise]]}} with `undefined`.

opened attribute

The {{UDPSocket/opened}} is an attribute containing all information about the socket. Once it is resolved, the developer can use the {{UDPSocketOpenInfo/readable}} and {{UDPSocketOpenInfo/writable}} to read from and write to the socket.

          const { readable, writable } = await socket.opened;

          const reader = readable.getReader();
          // Read from the socket using |reader|...

          const writer = writable.getWriter();
          // Write to the socket using |writer|...

When called, returns the [=this=].{{UDPSocket/[[openedPromise]]}}.

UDPSocketOpenInfo dictionary

          dictionary UDPSocketOpenInfo {
            ReadableStream readable;
            WritableStream writable;

            DOMString remoteAddress;
            unsigned short remotePort;

            DOMString localAddress;
            unsigned short localPort;
          };

readable member: The readable side of the socket. Set to {{UDPSocket/[[readable]]}}.
writable member: The writable side of the socket. Set to {{UDPSocket/[[writable]]}}.
remoteAddress member: Resolved remote IP address that the socket is communicating with.
remotePort member: Remote port that the socket is communicating with.
localAddress member: Local IP address that the socket is bound to.
localPort member: Local port that the socket is bound to.

closed attribute

The {{UDPSocket/closed}} is an attribute that keeps track of the socket state. It gets resolved if the socket is closed gracefully (i.e. by the user) or rejected in case of an error.

          socket.closed.then(() => console.log("Closed"), () => console.log("Errored"));

Note that {{UDPSocket/closed}} will be automatically rejected or resolved once both {{UDPSocket/[[readable]]}} and {{UDPSocket/[[writable]]}} reach a closed or errored state.

When called, returns the [=this=].{{UDPSocket/[[closedPromise]]}}.

close() method

When communication with the port is no longer required it can be closed and the associated resources released by the system.

Calling `socket.`{{UDPSocket/close()}} implicitly invokes `opened.`{{UDPSocketOpenInfo/readable}}`.`{{ReadableStream/cancel()}} and `opened.`{{UDPSocketOpenInfo/writable}}`.`{{WritableStream/abort()}} in order to clear any buffered data. If the application has called `opened.`{{UDPSocketOpenInfo/readable}}`.`{{ReadableStream/getReader()}} or `opened.`{{UDPSocketOpenInfo/writable}}`.`{{WritableStream/getWriter()}} the stream is locked and the socket cannot be closed. This forces the developer to decide how to handle any read or write operations that are in progress. For example, to ensure that all buffered data has been transmitted before the socket is closed the application must await the {{Promise}} returned by `writer.`{{WritableStreamDefaultWriter/close()}}.

          const encoder = new TextEncoder();
          const { writable } = await socket.opened;
          const writer = writable.getWriter();

          const message = {
            data: encoder.encode("A long message that will take...")
          };

          writer.write(message);
          await writer.close();
          await socket.close();

          const { readable } = await socket.opened;
          const reader = readable.getReader();

          async function readUntilClosed() {
            while (true) {
              const { value, done } = await reader.read();
              if (done) {
                // |reader| has been canceled.
                break;
              }
              const { data } = value;
              // Do something with |data|...
            }

            await socket.close();
          }

          const readComplete = readUntilClosed();

          // Sometime later...
          reader.releaseLock();
          await readComplete;

The {{UDPSocket/close()}} method steps are:

If [=this=].{{UDPSocket/[[openedPromise]]}} is rejected or not yet resolved, [=reject=] with "{{InvalidStateError}}" {{DOMException}}.
If [=this=].{{UDPSocket/[[closedPromise]]}} is settled, return [=this=].{{UDPSocket/[[closedPromise]]}}.
If [=this=].{{UDPSocket/[[readable]]}} or [=this=].{{UDPSocket/[[writable]]}} are locked, [=reject=] with "{{InvalidStateError}}" {{DOMException}}.
Let |cancelPromise:Promise| be the result of invoking [=ReadableStream/cancel=] on [=this=].{{UDPSocket/[[readable]]}}.
Set |cancelPromise|.[[\PromiseIsHandled]] as handled.
Let |abortPromise:Promise| be the result of invoking [=WritableStream/abort=] on [=this=].{{UDPSocket/[[writable]]}}.
Set |abortPromise|.[[\PromiseIsHandled]] as handled.
Return [=this=].{{UDPSocket/[[closedPromise]]}}.

{{TCPSocket}} interface

constructor() method

TCPSocketOptions dictionary

{{TCPSocket/[[readable]]}} attribute (internal)

{{TCPSocket/[[writable]]}} attribute (internal)

opened attribute

TCPSocketOpenInfo dictionary

closed attribute

close() method

{{UDPSocket}} interface

constructor() method

UDPSocketOptions dictionary

{{UDPSocket/[[readable]]}} attribute (internal)

UDPMessage dictionary

{{UDPSocket/[[writable]]}} attribute (internal)

opened attribute

UDPSocketOpenInfo dictionary

closed attribute

close() method

Integrations

Permissions Policy

Security and privacy considerations