index.html

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="utf-8">
  <title>
    Direct Sockets API
  </title>
  <script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove" defer></script>
  <script class='remove'>
    var respecConfig = {
      specStatus: "unofficial",
      github: {
        repoURL: "WICG/direct-sockets",
        branch: "main"
      },
      group: "wicg",
      editors: [
        {
          name: "Andrew Rayskiy",
          company: "Google Inc.",
          companyURL: "https://google.com",
          w3cid: 135463
        }
      ],
      formerEditors: [
        {
          name: "Eric Willigers",
          company: "Google Inc.",
          companyURL: "https://google.com",
          w3cid: 67534
        },
      ],
      latestVersion: null,
      xref: ["web-platform", "streams", "permissions-policy", "HTML", "infra", "DOM", "webidl", "isolated-contexts"],
      // eventually add mdn: true, and caniuse: "direct-sockets"
    };
  </script>
</head>

<body data-cite="Direct Sockets">
  <section id="abstract">
    <p>
      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.
    </p>
  </section>

  <section id="sotd">
    This is a work in progress. All <a
      href="https://github.com/WICG/direct-sockets">contributions</a> welcome.
  </section>

  <section data-dfn-for="TCPSocket">
    <h2>
      {{TCPSocket}} interface
    </h2>

    <pre class="idl">
      [
        Exposed=(Window,DedicatedWorker),
        SecureContext,
        IsolatedContext
      ]
      interface TCPSocket {
        constructor(DOMString remoteAddress,
                    unsigned short remotePort,
                    optional TCPSocketOptions options = {});

        readonly attribute Promise&lt;TCPSocketOpenInfo> opened;
        readonly attribute Promise&lt;undefined> closed;

        Promise&lt;undefined> close();
      };
    </pre>

    <p>
      Methods on this interface typically complete asynchronously, queuing work on the
      <dfn>TCPSocket task source</dfn>.

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

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

    <section>
      <h3><dfn>constructor()</dfn> method</h3>

      <aside class="example">
        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.

        <pre class="js">
          const socket = new TCPSocket(/*remoteAddress=*/, /*remotePort=*/, /*options=*/);
        </pre>

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

        <pre class="js">
          const { readable, writable } = await socket.opened;
        </pre>

        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.
      </aside>

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

      <ol>
        <li>
          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}}.
        <li>
          If |options|["{{TCPSocketOptions/keepAliveDelay}}"] is less than 1,000, throw a
          {{TypeError}}.
        <li>
          If |options|["{{TCPSocketOptions/sendBufferSize}}"] is equal to 0, throw a {{TypeError}}.
        <li>
          If |options|["{{TCPSocketOptions/receiveBufferSize}}"] is equal to 0, throw a
          {{TypeError}}.
        <li>
          Perform the following steps [=in parallel=].
          <ol>
            <li>
              Invoke the operating system to open a TCP socket using the given |remoteAddress| and
              |remotePort| and the connection parameters (or their defaults) specified in |options|.
            <li>
              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:
              <ol>
                <li>
                  [=Reject=] the {{TCPSocket/[[openedPromise]]}} with a "{{NetworkError}}"
                  {{DOMException}}.
                <li>
                  [=Reject=] the {{TCPSocket/[[closedPromise]]}} with a "{{NetworkError}}"
                  {{DOMException}}.
              </ol>
            <li>
              On success, [=queue a global task=] on the [=relevant global object=] of
              [=this=] using the [=TCPSocket task source=] to run the
              following steps:
              <ol>
                <li>
                  [=initialize TCPSocket readable stream|Initialize=] {{TCPSocket/[[readable]]}}.
                <li>
                  [=initialize TCPSocket writable stream|Initialize=] {{TCPSocket/[[writable]]}}.
                <li>
                  Let |openInfo:TCPSocketOpenInfo| be a new {{TCPSocketOpenInfo}}.
                <li>
                  Set |openInfo|["{{TCPSocketOpenInfo/readable}}"] to
                  [=this=].{{TCPSocket/[[readable]]}}.
                <li>
                  Set |openInfo|["{{TCPSocketOpenInfo/writable}}"] to
                  [=this=].{{TCPSocket/[[writable]]}}.
                <li>
                  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}}"].
                <li>
                  [=Resolve=] [=this=].{{TCPSocket/[[openedPromise]]}} with |openInfo|.
              </ol>
          </ol>
      </ol>

      <section data-dfn-for="TCPSocketOptions">
        <h4><dfn>TCPSocketOptions</dfn> dictionary</h4>

        <pre class="idl">
          enum SocketDnsQueryType {
            "ipv4",
            "ipv6"
          };

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

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

            SocketDnsQueryType dnsQueryType;
          };
        </pre>

        <dl>
          <dt>
            <dfn>sendBufferSize</dfn> member
          </dt>
          <dd>
            The requested send buffer size, in bytes.
            If not specified, then platform-specific default value will be used.
          </dd>
          <dt>
            <dfn>receiveBufferSize</dfn> member
          </dt>
          <dd>
            The requested receive buffer size, in bytes.
            If not specified, then platform-specific default value will be used.
          </dd>
          <dt>
            <dfn>noDelay</dfn> member
          </dt>
          <dd>
            Enables the `TCP_NODELAY` option,
            disabling <a href="https://en.wikipedia.org/wiki/Nagle%27s_algorithm">Nagle's
              algorithm</a>.
            <div class="note">
              No-Delay is disabled by default.
            </div>
          </dd>
          <dt>
            <dfn>keepAliveDelay</dfn> member
          </dt>
          <dd>
            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:
            <ol>
              <li>
                On Linux & ChromeOS `keepAliveDelay` is applied to `TCP_KEEPIDLE` and
                `TCP_KEEPINTVL`;
              <li>
                On MacOS `keepAliveDelay` affects `TCP_KEEPALIVE`;
              <li>
                On Windows `keepAliveDelay` is replicated to `keepalivetime` and `keepaliveinterval`
                of <a href="https://learn.microsoft.com/en-us/windows/win32/winsock/sio-keepalive-vals">`SIO_KEEPALIVE_VALS`</a>.
            </ol>
            <div class="note">
              Keep-Alive is disabled by default.
            </div>
          </dd>
          <dt>
            <dfn>dnsQueryType</dfn> member
          </dt>
          <dd>
            Indicates whether IPv4 or IPv6 record should be returned during DNS lookup.
            If omitted, the OS will select the record type(s) to be queried automatically
            depending on IPv4/IPv6 settings and reachability.
          </dd>
        </dl>

      </section>

    </section>

    <section>
      <h3>{{TCPSocket/[[readable]]}} attribute (internal)</h3>

      <aside class="example">
        An application receiving data from a TCP socket will typically use the {{ReadableStream}}
        like this:

        <pre class="js">
          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();
        </pre>
      </aside>

      The steps to <dfn data-lt="initialize TCPSocket readable stream">initialize the TCPSocket
      readable stream</dfn> are:

      <ol>
        <li>
          Let |stream:ReadableStream| be a [=new=] {{ReadableStream}}.
        <li>
          Let |pullAlgorithm| be the following steps:
          <ol>
            <li>
              Let |desiredSize| be the
              [=ReadableStream/desired size to fill up to the high water mark=] for
              [=this=].{{TCPSocket/[[readable]]}}.
            <li>
              If [=this=].{{TCPSocket/[[readable]]}}'s [=ReadableStream/current BYOB request view=]
              is non-null, then set |desiredSize| to [=this=].{{TCPSocket/[[readable]]}}'s
              [=ReadableStream/current BYOB request view=]'s [=BufferSource/byte length=].
            <li>
              Run the following steps in parallel:
              <ol>
                <li>
                  Invoke the operating system to read up to |desiredSize| bytes from the socket,
                  placing the result in the [=byte sequence=] |bytes|.
                <li>
                  [=Queue a global task=] on the [=relevant global object=] of
                  [=this=] using the [=TCPSocket task source=] to run the
                  following steps:
                  <ol>
                    <li>
                      If the connection was closed gracefully, run the following steps:
                      <ol>
                        <li>
                          Invoke [=ReadableStream/close=] on [=this=].{{TCPSocket/[[readable]]}}.
                        <li>
                          Invoke the steps to [=handle closing the TCPSocket readable stream=].
                      </ol>
                      <div class="note">
                        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.
                      </div>
                    <li>
                      If no errors were encountered, then:
                      <ol>
                        <li>
                          If [=this=].{{TCPSocket/[[readable]]}}'s
                          [=ReadableStream/current BYOB request view=] is non-null,
                          then [=ArrayBufferView/write=] |bytes| into
                          [=this=].{{TCPSocket/[[readable]]}}'s
                          [=ReadableStream/current BYOB request view=], and set
                          |view| to [=this=].{{TCPSocket/[[readable]]}}'s
                          [=ReadableStream/current BYOB request view=].
                        <li>
                          Otherwise, set |view| to the result of
                          [=ArrayBufferView/create|creating=] a {{Uint8Array}} from
                          |bytes| in [=this=]'s [=relevant Realm=].
                        <li>
                          [=ReadableStream/Enqueue=] |view| into
                          [=this=].{{TCPSocket/[[readable]]}}.
                      </ol>
                    <li>
                      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=].
                  </ol>
              </ol>
            <li>
              Return [=a promise resolved with=] `undefined`.
          </ol>

        <li>
          Let |cancelAlgorithm| be the following steps:
          <ol>
            <li>
              Invoke the steps to [=handle closing the TCPSocket readable stream=].
            <li>
              Return [=a promise resolved with=] `undefined`.
          </ol>
        <li>
          [=ReadableStream/Set up with byte reading support=] |stream| with
          <i>[=ReadableStream/set up with byte reading support/pullAlgorithm=]</i>
          set to |pullAlgorithm|,
          <i>[=ReadableStream/set up with byte reading support/cancelAlgorithm=]</i>
          set to |cancelAlgorithm|, and
          <i>[=ReadableStream/set up with byte reading support/highWaterMark=]</i>
          set to an implementation-defined value.
        <li>Set [=this=].{{TCPSocket/[[readable]]}} to |stream|.
      </ol>

      To <dfn>handle closing the TCPSocket readable stream</dfn> perform the following steps:

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

    </section>

    <section>
      <h3>{{TCPSocket/[[writable]]}} attribute (internal)</h3>

      <aside class="example">
        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.

        <pre class="js">
          const encoder = new TextEncoder();

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

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

          writer.releaseLock();
        </pre>

        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.
      </aside>

      The steps to <dfn data-lt="initialize TCPSocket writable stream">initialize the TCPSocket
      writable stream</dfn> are:

      <ol>
        <li>
          Let |stream:WritableStream| be a [=new=] {{WritableStream}}.
        <li>
          Let |signal:AbortSignal| be |stream|'s [=WritableStream/signal=].
        <li>
          Let |writeAlgorithm| be the following steps, given |chunk|:
          <ol>
            <li>
              Let |promise:Promise| be [=a new promise=].
            <li>
              Assert: |signal| is not [=AbortSignal/aborted=].
            <li>
              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|.
            <li>
              [=Get a copy of the buffer source=] |source| and save the result in
              |bytes|.
            <li>
              [=In parallel=], run the following steps:
              <ol>
                <li>
                  Invoke the operating system to write |bytes| to the socket.

                  <div class="note">
                    The operating system may return from this operation once
                    |bytes| has been queued for transmission rather than after it
                    has been transmitted.
                  </div>
                <li>
                  [=Queue a global task=] on the [=relevant global object=] of
                  [=this=] using the [=TCPSocket task source=] to run the
                  following steps:
                  <ol>
                    <li>
                      If the chunk was successfully written, [=resolve=] |promise| with `undefined`.

                      <div class="note">
                        [[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.
                      </div>
                    <li>
                      If a network or operating system error was encountered:
                      <ol>
                        <li>
                          [=Reject=] |promise| with a "{{NetworkError}}"
                          {{DOMException}}.
                        <li>
                          Invoke the steps to [=handle closing the TCPSocket writable
                          stream=].
                      </ol>
                    <li>
                      If |signal| is [=AbortSignal/aborted=], [=reject=] |promise|
                      with |signal|'s [=AbortSignal/abort reason=].
                  </ol>
              </ol>
            <li>
              Return |promise|.
          </ol>
        <li>
          Let |abortAlgorithm| be the following steps:
          <ol>
            <li>
              Let |promise| be [=a new promise=].
            <li>
              Run the following steps [=in parallel=]:
              <ol>
                <li>
                  Invoke the operating system to shutdown the socket for writing.
                <li>
                  [=Queue a global task=] on the [=relevant global object=] of
                  [=this=] using the [=TCPSocket task source=] to run the
                  following steps:
                  <ol>
                    <li>
                      Invoke the steps to [=handle closing the TCPSocket writable stream=].
                    <li>
                      [=Resolve=] |promise| with `undefined`.
                  </ol>
              </ol>
            <li>
              Return |promise|.
          </ol>
        <li>
          Let |closeAlgorithm| be the following steps:
          <ol>
            <li>
              Let |promise| be [=a new promise=].
            <li>
              Run the following steps [=in parallel=].
              <ol>
                <li>
                  Invoke the operating system to shutdown the socket for writing.
                <li>
                  [=Queue a global task=] on the [=relevant global object=] of
                  [=this=] using the [=TCPSocket task source=] to run the
                  following steps:
                  <ol>
                    <li>
                      Invoke the steps to [=handle closing the TCPSocket writable stream=].
                    <li>
                      If |signal| is [=AbortSignal/aborted=], [=reject=] |promise|
                      with |signal|'s [=AbortSignal/abort reason=].
                    <li>
                      [=Resolve=] |promise| with `undefined`.
                  </ol>
              </ol>
            <li>
              Return |promise|.
          </ol>
        <li>
          [=WritableStream/Set up=] |stream| with
          <i>[=WritableStream/set up/writeAlgorithm=]</i>
          set to |writeAlgorithm|,
          <i>[=WritableStream/set up/abortAlgorithm=]</i>
          set to |abortAlgorithm|,
          <i>[=WritableStream/set up/closeAlgorithm=]</i>
          set to |closeAlgorithm|,
          <i>[=WritableStream/set up/highWaterMark=]</i>
          set to an implementation-defined value.
        <li>
          [=AbortSignal/Add=] the following abort steps to |signal|:
          <ol>
            <li>
              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.
          </ol>
        <li>Set [=this=].{{TCPSocket/[[writable]]}} to |stream|.
      </ol>

      To <dfn>handle closing the TCPSocket writable stream</dfn> perform the following steps:

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

    </section>

    <section>
      <h3><dfn>opened</dfn> attribute</h3>

      <aside class="example">
        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.

        <pre class="js">
          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|...
        </pre>
      </aside>

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

      <section data-dfn-for="TCPSocketOpenInfo">
        <h4><dfn>TCPSocketOpenInfo</dfn> dictionary</h4>

        <pre class="idl">
          dictionary TCPSocketOpenInfo {
            ReadableStream readable;
            WritableStream writable;

            DOMString remoteAddress;
            unsigned short remotePort;

            DOMString localAddress;
            unsigned short localPort;
          };
        </pre>

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

      </section>
    </section>

    <section>
      <h3><dfn>closed</dfn> attribute</h3>

      <aside class="example">
        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.

        <pre class="js">
          socket.closed.then(() => console.log("Closed"), () => console.log("Errored"));
        </pre>

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

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

    <section>
      <h3><dfn>close()</dfn> method</h3>

      <aside class="example">
        When communication with the port is no longer required it can be closed
        and the associated resources released by the system.

        <p>
          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()}}.

        <pre class="js">
          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();
        </pre>

        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()}}.

        <pre class="js">
          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;
        </pre>

      </aside>

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

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

    </section>
  </section>

  <section data-dfn-for="UDPSocket">
    <h2>
      {{UDPSocket}} interface
    </h2>

    <pre class="idl">
      [
        Exposed=(Window,DedicatedWorker),
        SecureContext,
        IsolatedContext
      ]
      interface UDPSocket {
        constructor(optional UDPSocketOptions options = {});

        readonly attribute Promise&lt;UDPSocketOpenInfo> opened;
        readonly attribute Promise&lt;undefined> closed;

        Promise&lt;undefined> close();
      };
    </pre>

    Methods on this interface typically complete asynchronously, queuing work on the
    <dfn>UDPSocket task source</dfn>.

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

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

    <section>
      <h3><dfn>constructor()</dfn> method</h3>

      <aside class="example">
        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.

        <pre class="js">
          const socket = new UDPSocket(/*options=*/);
        </pre>

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

        <pre class="js">
          const { readable, writable } = await socket.opened;
        </pre>

        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.
      </aside>

      {{UDPSocket}} can operate in either {{UDPSocket/connected}} or {{UDPSocket/bound}} <dfn>mode</dfn> which
      is decided based on the provided set of constructor options.

      <ul>
        <li>
          In <dfn>connected</dfn> {{UDPSocket/mode}}, the UDP socket is associated with a specific destination
          IP address and port number. This means that any data sent using the socket is automatically
          sent to the specified destination without the need to specify the address and port every
          time. This {{UDPSocket/mode}} is assumed when {{UDPSocketOptions/remoteAddress}} and
          {{UDPSocketOptions/remotePort}} are specified in {{UDPSocketOptions}}.
          <div class="note">
            This {{UDPSocket/mode}} is useful for applications that require a constant communication channel
            between two endpoints, such as real-time streaming applications.
          </div>
        <li>
          In <dfn>bound</dfn> {{UDPSocket/mode}}, the UDP socket is bound to a specific local IP address and port
          number. This means that any data received on that IP address and port is delivered to the
          socket. Similarly, any data sent using the socket is sent from the bound IP address and
          port. This {{UDPSocket/mode}} is assumed when {{UDPSocketOptions/localAddress}} is specified in
          {{UDPSocketOptions}}.
          <div class="note">
            This {{UDPSocket/mode}} is useful for applications that need to listen for incoming data on a
            specific port or interface, such as server applications that receive incoming messages
            from multiple clients.
          </div>
      </ul>

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

      <ol>
        <li>
          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}}.
        <li>
          If only one of |options|["{{UDPSocketOptions/remoteAddress}}"] and
          |options|["{{UDPSocketOptions/remotePort}}"] is specified, throw a {{TypeError}}.
        <li>
          Alternatively, if both |options|["{{UDPSocketOptions/remoteAddress}}"] and
          |options|["{{UDPSocketOptions/remotePort}}"] are specified, assume {{UDPSocket/connected}}
          {{UDPSocket/mode}}.
        <li>
          If |options|["{{UDPSocketOptions/localPort}}"] is equal to 0 or specified without
          |options|["{{UDPSocketOptions/localAddress}}"], throw a {{TypeError}}.
        <li>
          If |options|["{{UDPSocketOptions/localAddress}}"] is specified:
          <ol>
            <li>
              If {{UDPSocket/connected}} {{UDPSocket/mode}} was previously inferred, throw a {{TypeError}}.
            <li>
              If |options|["{{UDPSocketOptions/localAddress}}"] is not a valid IP address,
              throw a {{TypeError}}.
            <li>
              Assume {{UDPSocket/bound}} {{UDPSocket/mode}}.
          </ol>
        <li>
          If no {{UDPSocket/mode}} has been inferred at this point, throw a {{TypeError}}.
        <li>
          If |options|["{{UDPSocketOptions/dnsQueryType}}"] is specified in {{UDPSocket/bound}}
          {{UDPSocket/mode}}, throw a {{TypeError}}.
         <li>
          If |options|["{{UDPSocketOptions/ipv6Only}}"] is specified:
          <ol>
            <li>
              If inferred {{UDPSocket/mode}} is {{UDPSocket/connected}}, throw a {{TypeError}}.
            <li>
              If |options|["{{UDPSocketOptions/localAddress}}"] is not equal to the IPv6
              unspecified address (`::`), throw a {{TypeError}}.
          </ol>
        <li>
          If |options|["{{UDPSocketOptions/sendBufferSize}}"] is equal to 0, throw a {{TypeError}}.
        <li>
          If |options|["{{UDPSocketOptions/receiveBufferSize}}"] is equal to 0, throw a
          {{TypeError}}.
        <li>
          Perform the following steps [=in parallel=].
          <ol>
            <li>
              Invoke the operating system to open a UDP socket using the inferred
              {{UDPSocket/mode}} and the parameters (or their defaults) specified in |options|.
            <li>
              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:
              <ol>
                <li>
                  [=Reject=] the {{UDPSocket/[[openedPromise]]}} with a "{{NetworkError}}"
                  {{DOMException}}.
                <li>
                  [=Reject=] the {{UDPSocket/[[closedPromise]]}} with a "{{NetworkError}}"
                  {{DOMException}}.
              </ol>
            <li>
              On success, [=queue a global task=] on the [=relevant global object=] of
              [=this=] using the [=UDPSocket task source=] to run the following steps:
              <ol>
                <li>
                  [=initialize UDPSocket readable stream|Initialize=] {{UDPSocket/[[readable]]}}.
                <li>
                  [=initialize UDPSocket writable stream|Initialize=] {{UDPSocket/[[writable]]}}.
                <li>
                  Let |openInfo:UDPSocketOpenInfo| be a new {{UDPSocketOpenInfo}}.
                <li>
                  Set |openInfo|["{{UDPSocketOpenInfo/readable}}"] to
                  [=this=].{{UDPSocket/[[readable]]}}.
                <li>
                  Set |openInfo|["{{UDPSocketOpenInfo/writable}}"] to
                  [=this=].{{UDPSocket/[[writable]]}}.
                <li>
                  Populate the remaining fields of |openInfo| using the information provided by the
                  operating system:
                  <ul>
                    <li>
                      For {{UDPSocket/bound}} {{UDPSocket/mode}}, populate only
                      |openInfo|["{{UDPSocketOpenInfo/localAddress}}"] and
                      |openInfo|["{{UDPSocketOpenInfo/localPort}}"].
                    <li>
                      For {{UDPSocket/connected}} {{UDPSocket/mode}}, populate
                      |openInfo|["{{UDPSocketOpenInfo/localAddress}}"] and
                      |openInfo|["{{UDPSocketOpenInfo/localPort}}"] as well as
                      |openInfo|["{{UDPSocketOpenInfo/remoteAddress}}"] and
                      |openInfo|["{{UDPSocketOpenInfo/remotePort}}"].
                  </ul>
                <li>
                  Resolve [=this=].{{UDPSocket/[[openedPromise]]}} with |openInfo|.
              </ol>
          </ol>
      </ol>

      <section data-dfn-for="UDPSocketOptions">
        <h4><dfn>UDPSocketOptions</dfn> dictionary</h4>

        <pre class="idl">
          dictionary UDPSocketOptions {
            DOMString remoteAddress;
            [EnforceRange] unsigned short remotePort;

            DOMString localAddress;
            [EnforceRange] unsigned short localPort;

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

            SocketDnsQueryType dnsQueryType;
            boolean ipv6Only;
          };
        </pre>

        <dl>
          <dt>
            <dfn>remoteAddress</dfn> member
          </dt>
          <dd>
            The remote IP address to connect the socket to.
          </dd>
          <dt>
            <dfn>remotePort</dfn> member
          </dt>
          <dd>
            The remote port to connect the socket to.
          </dd>
          <dt>
            <dfn>localAddress</dfn> member
          </dt>
          <dd>
            The local IP address to bind the socket to.
          </dd>
          <dt>
            <dfn>localPort</dfn> member
          </dt>
          <dd>
            The local port to bind the socket to. Leave this field empty to let the OS pick one on
            its own.
          </dd>
          <dt>
            <dfn>sendBufferSize</dfn> member
          </dt>
          <dd>
            The requested send buffer size, in bytes.
            If not specified, then platform-specific default value will be used.
          </dd>
          <dt>
            <dfn>receiveBufferSize</dfn> member
          </dt>
          <dd>
            The requested receive buffer size, in bytes.
            If not specified, then platform-specific default value will be used.
          </dd>
          <dt>
            <dfn>dnsQueryType</dfn> member
          </dt>
          <dd>
            Indicates whether IPv4 or IPv6 record should be returned during DNS lookup.
            If omitted, the OS will select the record type(s) to be queried automatically
            depending on IPv4/IPv6 settings and reachability.
            <div class="note">
              This field can only be supplied in {{UDPSocket/connected}} {{UDPSocket/mode}}.
            </div>
          </dd>
          <dt>
            <dfn>ipv6Only</dfn> member
          </dt>
          <dd>
            Enables or disables `IPV6_V6ONLY` to either restrict connections to IPv6 only or
            allow both IPv4/IPv6 connections.
            <div class="note">
              This field can only be supplied in {{UDPSocket/bound}} {{UDPSocket/mode}} when
              `localAddress` is equal to the IPv6 unspecified address (`::`).
            </div>
            <div class="note">
              Leave this field empty to retain default platform-defined behavior
              (`true` on Windows and `false` on Posix).
            </div>
          </dd>
        </dl>
      </section>

      <section data-dfn-for="UDPMessage">

        <h4><dfn>UDPMessage</dfn> dictionary</h4>

        {{UDPSocket/[[readable]]}} and {{UDPSocket/[[writable]]}} streams operate on
        {{UDPMessage}} objects.

        <pre class="idl">
          dictionary UDPMessage {
            BufferSource data;
            DOMString remoteAddress;
            unsigned short remotePort;
            SocketDnsQueryType dnsQueryType;
          };
        </pre>

        <dl>
          <dt>
            <dfn>data</dfn> member
          </dt>
          <dd>
            The user message represented as {{BufferSource}}.
            <div class="note">
              For {{UDPSocket/[[readable]]}} the underlying type is always {{Uint8Array}}.
            </div>
          </dd>
          <dt>
            <dfn>remoteAddress</dfn> member
          </dt>
          <dd>
            The remote address where the message came from or where it should be send to.
            <div class="note">
              <ul>
                <li>
                  In {{UDPSocket/connected}} {{UDPSocket/mode}} this field is always unspecified; attempting to
                  set it while writing will throw (see {{UDPSocket/[[writable]]}}).
                <li>
                  In {{UDPSocket/bound}} {{UDPSocket/mode}} this field represents the remote host that this
                  packet came from for {{UDPSocket/[[readable]]}} or instructs the socket about
                  the destination host for {{UDPSocket/[[writable]]}}.
              </ul>
            </div>
          </dd>
          <dt>
            <dfn>remotePort</dfn> member
          </dt>
          <dd>
            The remote port where the message came from or where it should be sent to.
            <div class="note">
              <ul>
                <li>
                  In {{UDPSocket/connected}} {{UDPSocket/mode}} this field is always unspecified; attempting to set it while
                  writing will throw (see {{UDPSocket/[[writable]]}}).
                <li>
                  In {{UDPSocket/bound}} {{UDPSocket/mode}} this field represents the remote port that this packet came from for
                  {{UDPSocket/[[readable]]}} or instructs the socket about the destination port for
                  {{UDPSocket/[[writable]]}}.
              </ul>
            </div>
          </dd>
          <dt>
            <dfn>dnsQueryType</dfn> member
          </dt>
          <dd>
            Indicates whether IPv4 or IPv6 record should be returned during DNS lookup.
            If omitted, the OS will select the record type(s) to be queried automatically
            depending on IPv4/IPv6 settings and reachability.
            <div class="note">
              This field is always unset for {{UDPMessage}} instances received from
              {{UDPSocket/[[readable]]}} stream regardless of socket's operating {{UDPSocket/mode}}.
              For {{UDPSocket/[[writable]]}} this can only be specified in {{UDPSocket/bound}} {{UDPSocket/mode}};
              attempting to set the field in {{UDPSocket/connected}} {{UDPSocket/mode}} will throw.
            </div>
          </dd>
        </dl>

      </section>

    </section>

    <section>
      <h3>{{UDPSocket/[[readable]]}} attribute (internal)</h3>

      <aside class="example">
        An application receiving data from a UDP socket will typically use the {{ReadableStream}}
        like this:

        <pre class="js">
          const { readable } = await socket.opened;

          const reader = readable.getReader();

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

            // In {{UDPSocket/bound}} {{UDPSocket/mode}}:
            const { data, remoteAddress, remotePort } = value;
            // Do something with |data|, |remoteAddress| and |remotePort|...
          }

          reader.releaseLock();
        </pre>
      </aside>

      The steps to <dfn data-lt="initialize UDPSocket readable stream">initialize the UDPSocket
      readable stream</dfn> are:

      <ol>
        <li>
          Let |stream:ReadableStream| be a [=new=] {{ReadableStream}}.
        <li>
          Let |pullAlgorithm| be the following steps:
          <ol>
            <li>
              Let |desiredSize| be the
              [=ReadableStream/desired size to fill up to the high water mark=] for
              [=this=].{{UDPSocket/[[readable]]}}.
            <li>
              Run the following steps in parallel:
              <ol>
                <li>
                  Invoke the operating system to provide up to |desiredSize| UDP packets from the
                  socket.
                <li>
                  [=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:
                  <ol>
                    <li>
                      If no errors were encountered, for each packet received run the following
                      steps:
                      <ol>
                        <li>
                          Let |bytes| be a [=byte sequence=] containing the packet payload.
                        <li>
                          Let |buffer| be a [=new=] {{ArrayBuffer}} created from |bytes|.
                        <li>
                          Let |chunk| be a [=new=] {{Uint8Array}} view over |buffer|,
                          who's length is the length of |bytes|.
                        <li>
                          Let |message:UDPMessage| be a new {{UDPMessage}}.
                        <li>
                          Set |message|["{{UDPMessage/data}}"] to |chunk|.
                        <li>
                          If the socket is operating in {{UDPSocket/bound}} {{UDPSocket/mode}}:
                          <ol>
                            <li>
                              Set |message|["{{UDPMessage/remoteAddress}}"] to the source address
                              of the packet.
                            <li>
                              Set |message|["{{UDPMessage/remotePort}}"] to the source port of the
                              packet.
                          </ol>
                        <li>
                          Invoke [=ReadableStream/enqueue=] on
                          [=this=].{{UDPSocket/[[readable]]}} with |message|.
                      </ol>
                    <li>
                      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=].
                  </ol>
              </ol>
            <li>
              Return [=a promise resolved with=] `undefined`.
          </ol>
        <li>
          Let |cancelAlgorithm| be the following steps:
          <ol>
            <li>
              Invoke the steps to [=handle closing the UDPSocket readable stream=].
            <li>
              Return [=a promise resolved with=] `undefined`.
          </ol>
        <li>
          [=ReadableStream/Set up=] |stream| with
          <i>[=ReadableStream/set up/pullAlgorithm=]</i>
          set to |pullAlgorithm|,
          <i>[=ReadableStream/set up/cancelAlgorithm=]</i>
          set to |cancelAlgorithm|,
          <i>[=ReadableStream/set up/highWaterMark=]</i>
          [=ReadableStream/Set up=] |stream| with
          set to an implementation-defined value.
        <li>
          Set [=this=].{{UDPSocket/[[readable]]}} to |stream|.
      </ol>

      To <dfn>handle closing the UDPSocket readable stream</dfn> perform the following steps:

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

    </section>

    <section>
      <h3>{{UDPSocket/[[writable]]}} attribute (internal)</h3>

      <aside class="example">
        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.

        <pre class="js">
          const encoder = new TextEncoder();

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

          // In {{UDPSocket/connected}} {{UDPSocket/mode}}:
          const message = {
            data: encoder.encode("PING")
          };

          // In {{UDPSocket/bound}} {{UDPSocket/mode}}:
          const message = {
            data: encoder.encode("PING"),
            remoteAddress: ...,
            remotePort: ...
          };

          await writer.ready;
          await writer.write(message);

          writer.releaseLock();
        </pre>

        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.
      </aside>

      The steps to <dfn data-lt="initialize UDPSocket writable stream">initialize the UDPSocket
      writable stream</dfn> are:

      <ol>
        <li>
          Let |stream:WritableStream| be a [=new=] {{WritableStream}}.
        <li>
          Let |signal:AbortSignal| be |stream|'s [=WritableStream/signal=].
        <li>
          Let |writeAlgorithm| be the following steps, given |chunk|:
          <ol>
            <li>
              Let |promise:Promise| be [=a new promise=].
            <li>
              Assert: |signal| is not [=AbortSignal/aborted=].
            <li>
              Let |message:UDPMessage| be a new {{UDPMessage}}.
            <li>
              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|.
            <li>
              If either |message|["{{UDPMessage/remoteAddress}}"],
              |message|["{{UDPMessage/remotePort}}"] or
              |message|["{{UDPMessage/dnsQueryType}}"] <b>is specified</b> in
              {{UDPSocket/connected}} {{UDPSocket/mode}}, reject |promise| with a
              {{TypeError}} and return |promise|.
            <li>
              If either |message|["{{UDPMessage/remoteAddress}}"]
              or |message|["{{UDPMessage/remotePort}}"] <b>is not specified</b> in
              {{UDPSocket/bound}} {{UDPSocket/mode}}, reject |promise| with a
              {{TypeError}} and return |promise|.
            <li>
              [=Get a copy of the buffer source=] |message|["{{UDPMessage/data}}"] and save the
              result in |bytes|.
            <li>
              [=In parallel=], run the following steps:
              <ol>
                <li>
                  Invoke the operating system to send |bytes| to the socket.
                  <ul>
                    <li>
                      In {{UDPSocket/connected}} {{UDPSocket/mode}} the data is routed to the
                      address/port specified upon construction.
                    <li>
                      In {{UDPSocket/bound}} {{UDPSocket/mode}} the data is routed to
                      |message|["{{UDPMessage/remoteAddress}}"] and
                      |message|["{{UDPMessage/remotePort}}"].
                      |message|["{{UDPMessage/dnsQueryType}}"] can be optionally supplied to
                      control whether DNS resolution routine returns an IPv4 or an IPv6 record.
                  </ul>
                  <div class="note">
                    The operating system may return from this operation once
                    |bytes| has been queued for transmission rather than after it
                    has been transmitted.
                  </div>
                <li>
                  [=Queue a global task=] on the [=relevant global object=] of
                  [=this=] using the [=UDPSocket task source=] to run the
                  following steps:
                  <ol>
                    <li>
                      If the data was successfully written, [=resolve=] |promise| with `undefined`.
                    <li>
                      If a network or operating system error was encountered:
                      <ol>
                        <li>
                          [=Reject=] |promise| with a "{{NetworkError}}"
                          {{DOMException}}.
                        <li>
                          Invoke the steps to [=handle closing the UDPSocket writable
                          stream=].
                      </ol>
                    <li>
                      If |signal| is [=AbortSignal/aborted=], [=reject=] |promise|
                      with |signal|'s [=AbortSignal/abort reason=].
                  </ol>
              </ol>
            <li>
              Return |promise|.
          </ol>
        <li>
          Let |abortAlgorithm| be the following steps:
          <ol>
            <li>
              Invoke the steps to [=handle closing the UDPSocket writable stream=].
            <li>
              Return [=a promise resolved with=] `undefined`.
          </ol>
        <li>
          Let |closeAlgorithm| be the following steps:
          <ol>
            <li>
              Invoke the steps to [=handle closing the UDPSocket writable stream=].
            <li>
              Return [=a promise resolved with=] `undefined`.
          </ol>
        <li>
          [=WritableStream/Set up=] |stream| with
          <i>[=WritableStream/set up/writeAlgorithm=]</i>
          set to |writeAlgorithm|,
          <i>[=WritableStream/set up/abortAlgorithm=]</i>
          set to |abortAlgorithm|,
          <i>[=WritableStream/set up/closeAlgorithm=]</i>
          set to |closeAlgorithm|,
          <i>[=WritableStream/set up/highWaterMark=]</i>
          set to an implementation-defined value.
        <li>
          [=AbortSignal/Add=] the following abort steps to |signal|:
          <ol>
            <li>
              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.
          </ol>
        <li>
          Set [=this=].{{UDPSocket/[[writable]]}} to |stream|.
      </ol>

      To <dfn>handle closing the UDPSocket writable stream</dfn> perform the following steps:

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

    </section>

    <section>
      <h3><dfn>opened</dfn> attribute</h3>

      <aside class="example">
        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.

        <pre class="js">
          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|...
        </pre>
      </aside>

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

      <section data-dfn-for="UDPSocketOpenInfo">
        <h4><dfn>UDPSocketOpenInfo</dfn> dictionary</h4>

        <pre class="idl">
          dictionary UDPSocketOpenInfo {
            ReadableStream readable;
            WritableStream writable;

            DOMString remoteAddress;
            unsigned short remotePort;

            DOMString localAddress;
            unsigned short localPort;
          };
        </pre>

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

      </section>
    </section>

    <section>
      <h3><dfn>closed</dfn> attribute</h3>

      <aside class="example">
        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.

        <pre class="js">
          socket.closed.then(() => console.log("Closed"), () => console.log("Errored"));
        </pre>

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

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

    <section>
      <h3><dfn>close()</dfn> method</h3>

      <aside class="example">
        When communication with the port is no longer required it can be closed
        and the associated resources released by the system.

        <p>
          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()}}.

        <pre class="js">
          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();
        </pre>

        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`.{{UDPSocket/close()}}.

        <pre class="js">
          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;
        </pre>

      </aside>

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

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

    </section>
  </section>

  <section data-dfn-for="TCPServerSocket">
    <h2>
      {{TCPServerSocket}} interface
    </h2>

    <pre class="idl">
      [
        Exposed=(Window,DedicatedWorker),
        SecureContext,
        IsolatedContext
      ]
      interface TCPServerSocket {
        constructor(DOMString localAddress,
                    optional TCPServerSocketOptions options = {});

        readonly attribute Promise&lt;TCPServerSocketOpenInfo> opened;
        readonly attribute Promise&lt;undefined> closed;

        Promise&lt;undefined> close();
      };
    </pre>

    <p>
      Methods on this interface typically complete asynchronously, queuing work on the
      <dfn>TCPServerSocket task source</dfn>.

    <p>
      Instances of {{TCPServerSocket}} are created with the internal slots described in the
      following
      table:

    <table class="simple" data-dfn-for="TCPServerSocket">
      <tr>
        <th>Internal slot
        <th>Initial value
        <th>Description (non-normative)
      <tr>
        <td><dfn>[[\readable]]</dfn>
        <td>`null`
        <td>A {{ReadableStream}} used to accept incoming connections.
      <tr>
        <td><dfn>[[\openedPromise]]</dfn>
        <td>`new Promise`
        <td>A {{Promise}} used to wait for the socket to be opened. Corresponds to the
          {{TCPServerSocket/opened}} member.
      <tr>
        <td><dfn>[[\closedPromise]]
        <td>`new Promise`
        <td>A {{Promise}} used to wait for the socket to close or error. Corresponds to the
          {{TCPServerSocket/closed}} member.
    </table>

    <section>
      <h3><dfn>constructor()</dfn> method</h3>

      <aside class="example">
        In order to accept incoming TCP connections a listening socket must be requested first.
        The socket object constructor allows the site to specify necessary parameters which control
        what interfaces the socket is supposed to listen on and how many connections can be queued
        up.

        Once {{TCPServerSocket/opened}} has resolved, {{TCPServerSocketOpenInfo/readable}}
        can be accessed to get the {{ReadableStream}} instance to start accepting connections to the
        server.
      </aside>

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

      <ol>
        <li>
          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}}.
        <li>
          If |localAddress| is not a valid IP address, throw a {{TypeError}}.
        <li>
          If |options|["{{TCPServerSocketOptions/localPort}}"] is equal to 0, throw a {{TypeError}}.
        <li>
          If |options|["{{TCPServerSocketOptions/backlog}}"] is equal to 0, throw a {{TypeError}}.
        <li>
          If |options|["{{TCPServerSocketOptions/ipv6Only}}"] is true but `localAddress` is not equal
          to the IPv6 unspecified address (`::`), throw a {{TypeError}}.
        <li>
          Perform the following steps [=in parallel=].
          <ol>
            <li>
              Invoke the operating system to open a TCP server socket using the given |localAddress|
              and the connection parameters (or their defaults) specified in |options|.
            <li>
              If this fails for any reason, [=queue a global task=] on the [=relevant global
              object=] of [=this=] using the [=TCPServerSocket task source=] to run the
              following steps:
              <ol>
                <li>
                  [=Reject=] the {{TCPServerSocket/[[openedPromise]]}} with a "{{NetworkError}}"
                  {{DOMException}}.
                <li>
                  [=Reject=] the {{TCPServerSocket/[[closedPromise]]}} with a "{{NetworkError}}"
                  {{DOMException}}.
              </ol>
            <li>
              On success, [=queue a global task=] on the [=relevant global object=] of
              [=this=] using the [=TCPServerSocket task source=] to run the following steps:
              <ol>
                <li>
                  [=initialize TCPServerSocket readable stream|Initialize=] {{TCPServerSocket/[[readable]]}}.
                <li>
                  Let |openInfo:TCPServerSocketOpenInfo| be a new {{TCPServerSocketOpenInfo}}.
                <li>
                  Set |openInfo|["{{TCPServerSocketOpenInfo/readable}}"] to
                  [=this=].{{TCPServerSocket/[[readable]]}}.
                <li>
                  Populate the remaining fields of |openInfo| using the information provided by the
                  operating system:
                  |openInfo|["{{TCPServerSocketOpenInfo/localAddress}}"] and
                  |openInfo|["{{TCPServerSocketOpenInfo/localPort}}"].
                <li>
                  [=Resolve=] [=this=].{{TCPServerSocket/[[openedPromise]]}} with |openInfo|.
              </ol>
          </ol>
      </ol>

      <section data-dfn-for="TCPServerSocketOptions">
        <h4><dfn>TCPServerSocketOptions</dfn> dictionary</h4>
        <pre class="idl">
          dictionary TCPServerSocketOptions {
            [EnforceRange] unsigned short localPort;
            [EnforceRange] unsigned long backlog;

            boolean ipv6Only;
          };
        </pre>

        <dl>
          <dt>
            <dfn>localPort</dfn> member
          </dt>
          <dd>
            The port to open the socket on.
            <div class="note">
              Leave this field empty to let the OS pick one on its own.
            </div>
          </dd>
          <dt>
            <dfn>backlog</dfn> member
          </dt>
          <dd>
            The size of the OS accept queue.
            <div class="note">
              Leave this field empty to let the OS pick a reasonable platform-specific default.
            </div>
          </dd>
          <dt>
            <dfn>ipv6Only</dfn> member
          </dt>
          <dd>
            Enables or disables `IPV6_V6ONLY` to either restrict connections to IPv6 only or
            allow both IPv4/IPv6 connections.
            <div class="note">
              This field can only be supplied when `localAddress` is equal to the IPv6
              unspecified address (`::`).
            </div>
            <div class="note">
              Leave this field empty to retain default platform-defined behavior
              (`true` on Windows and `false` on Posix).
            </div>
          </dd>
        </dl>

      </section>

    </section>

    <section>
      <h3>{{TCPServerSocket/[[readable]]}} attribute (internal)</h3>

      <aside class="example">
        An application listening for incoming connections on a {{TCPServerSocket}} will typically
        use the {{ReadableStream}} like this:

        <pre class="js">
          const { readable } = await socket.opened;
          const reader = readable.getReader();

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

          reader.releaseLock();
        </pre>
      </aside>

      The steps to <dfn data-lt="initialize TCPServerSocket readable stream">initialize the
      TCPServerSocket readable stream</dfn> are:

      <ol>
        <li>
          Let |stream:ReadableStream| be a [=new=] {{ReadableStream}}.
        <li>
          Let |pullAlgorithm| be the following steps:
          <ol>
            <li>
              Let |desiredSize| be the
              <a
                href="https://streams.spec.whatwg.org/#desired-size-to-fill-a-streams-internal-queue">desired
                size</a>
              of [=this=].{{TCPServerSocket/[[readable]]}}'s
              <a href="https://streams.spec.whatwg.org/#internal-queues">internal queue</a>.
            <li>
              Run the following steps in parallel:
              <ol>
                <li>
                  Invoke the operating system to accept up to |desiredSize| incoming connections.
                <li>
                  [=Queue a global task=] on the [=relevant global object=] of
                  [=this=] using the [=TCPServerSocket task source=] to run the following steps:
                  <ol>
                    <li>
                      If the connection was closed gracefully, run the following steps:
                      <ol>
                        <li>
                          Invoke [=ReadableStream/close=] on [=this=].{{TCPServerSocket/[[readable]]}}.
                        <li>
                          Invoke the steps to [=handle closing the TCPServerSocket readable stream=].
                      </ol>
                    <li>
                      If no errors were encountered run the following steps:
                      <ol>
                        <li>
                          Let |tcpSocket| be a [=new=] {{TCPSocket}} accepted by the operating system.
                        <li>
                          Invoke [=ReadableStream/enqueue=] on
                          [=this=].{{TCPServerSocket/[[readable]]}} with |tcpSocket|.
                      </ol>
                    <li>
                      If a network or operating system error was encountered, invoke
                      [=ReadableStream/error=] on [=this=].{{TCPServerSocket/[[readable]]}} with
                      a "{{NetworkError}}" {{DOMException}} and invoke the steps
                      to [=handle closing the TCPServerSocket readable stream=].
                  </ol>
              </ol>
            <li>
              Return [=a promise resolved with=] `undefined`.
          </ol>

        <li>
          Let |cancelAlgorithm| be the following steps:
          <ol>
            <li>
              Invoke the steps to [=handle closing the TCPServerSocket readable stream=].
            <li>
              Return [=a promise resolved with=] `undefined`.
          </ol>
        <li>
          [=ReadableStream/Set up=] |stream| with
          <a
            href="https://streams.spec.whatwg.org/#readablestream-set-up-pullalgorithm">pullAlgorithm</a>
          set to |pullAlgorithm|,
          <a
            href="https://streams.spec.whatwg.org/#readablestream-set-up-cancelalgorithm">cancelAlgorithm</a>
          set to |cancelAlgorithm|,
          <a
            href="https://streams.spec.whatwg.org/#readablestream-set-up-highwatermark">highWaterMark</a>
          set to an implementation-defined value.
        <li>Set [=this=].{{TCPServerSocket/[[readable]]}} to |stream|.
      </ol>

      To <dfn>handle closing the TCPServerSocket readable stream</dfn> run the following steps
      [=in parallel=]:

      <ol>
        <li>
          Invoke the operating system to close the socket.
        <li>
          [=Queue a global task=] on the [=relevant global object=] of
          [=this=] using the [=TCPServerSocket task source=] to
          [=resolve=] [=this=].{{TCPServerSocket/[[closedPromise]]}}
          with `undefined`.
      </ol>

    </section>

    <section>
      <h3><dfn>opened</dfn> attribute</h3>

      <aside class="example">
        {{TCPServerSocket/opened}} is an attribute containing all information about the socket.
        Once it is resolved, the developer can use {{TCPSocketOpenInfo/readable}} to accept new
        connections to the server.

        <pre class="js">
          const { readable } = await socket.opened;

          const reader = readable.getReader();
          // Accept new connection to the socket using |reader|...
        </pre>
      </aside>

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

      <section data-dfn-for="TCPServerSocketOpenInfo">
        <h4><dfn>TCPServerSocketOpenInfo</dfn> dictionary</h4>

        <pre class="idl">
          dictionary TCPServerSocketOpenInfo {
            ReadableStream readable;

            DOMString localAddress;
            unsigned short localPort;
          };
        </pre>

        <dl>
          <dt>
            <dfn>readable</dfn> member
          </dt>
          <dd>
            The readable side of the socket. Set to {{TCPServerSocket/[[readable]]}}.
          </dd>
          <dt>
            <dfn>localAddress</dfn> member
          </dt>
          <dd>
            Local IP address that the socket is bound to.
          </dd>
          <dt>
            <dfn>localPort</dfn> member
          </dt>
          <dd>
            Local port that the socket is bound to.
          </dd>
        </dl>

      </section>
    </section>

    <section>
      <h3><dfn>closed</dfn> attribute</h3>

      <aside class="example">
        The {{TCPServerSocket/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.

        <pre class="js">
          socket.closed.then(() => console.log("Closed"), () => console.log("Errored"));
        </pre>

        Note that {{TCPServerSocket/closed}} will be automatically resolved or rejected once
        {{TCPServerSocket/[[readable]]}} reaches a closed or errored state respectively.
      </aside>

      When called, returns the [=this=].{{TCPServerSocket/[[closedPromise]]}}.
    </section>

    <section>
      <h3><dfn>close()</dfn> method</h3>

      <aside class="example">
        When listening to new connections is no longer required, the socket can be closed
        and the associated resources released by the system.

        <p>
          Calling `socket.`{{TCPServerSocket/close()}} implicitly invokes
          `opened.`{{TCPServerSocketOpenInfo/readable}}`.`{{ReadableStream/cancel()}}.
          If the application has previously called
          `opened.`{{TCPServerSocketOpenInfo/readable}}`.`{{ReadableStream/getReader()}},
          the stream is locked and the socket cannot be closed. This forces the developer to
          decide how to handle any accept operations that are in progress.

      </aside>

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

      <ol>
        <li>
          If [=this=].{{TCPServerSocket/[[openedPromise]]}} is rejected or not yet resolved,
          [=reject=] with "{{InvalidStateError}}" {{DOMException}}.
        <li>
          If [=this=].{{TCPServerSocket/[[closedPromise]]}} is settled, return
          [=this=].{{TCPServerSocket/[[closedPromise]]}}.
        <li>
          If [=this=].{{TCPServerSocket/[[readable]]}} is <a
            href="https://streams.spec.whatwg.org/#lock">locked</a>,
          [=reject=] with "{{InvalidStateError}}" {{DOMException}}.
        <li>
          Let |cancelPromise:Promise| be the result of invoking
          [=ReadableStream/cancel=] on [=this=].{{TCPServerSocket/[[readable]]}}.
        <li>
          Set |cancelPromise|.[[\PromiseIsHandled]] to true.
        <li>
          Return [=this=].{{TCPServerSocket/[[closedPromise]]}}.
      </ol>

    </section>
  </section>

  <section id="integrations">
    <h2>Integrations</h2>

    <section id="permissions-policy">
      <h3>Permissions Policy</h3>

      <p>
        This specification defines a feature that controls whether {{TCPSocket}} and {{UDPSocket}}
        classes may be created.

      <p>
        The feature name for this feature is "<dfn
          data-dfn-for="policy-controlled feature"><code>direct-sockets</code></dfn>"`.

      <p>
        The default allowlist for this feature is `'self'`.

      <div class="note">
        A document’s permission policy determines whether a
        `new TCPSocket(...)`, `new UDPSocket(...)` or `new TCPServerSocket(...)` call rejects with
        a {{"NotAllowedError"}} {{DOMException}}.
      </div>

    </section>
  </section>

  <section class="informative" data-cite="security">
    <h2>Security and privacy considerations</h2>

    <ul>
      <li>See <a
          href="https://github.com/WICG/direct-sockets/blob/main/docs/explainer.md#security-considerations">
          Explainer</a>.
      </li>
    </ul>

  </section>

  <section id="idl-index"></section>

  <section id="conformance"></section>

</body>

</html>