net: add synchronous, role-neutral net.BoundHandle

Add net.BoundHandle, a synchronous TCP bind primitive that mirrors POSIX
bind(2): the socket is bound to a local address but stays role-agnostic
until it is adopted as a server (server.listen()) or a client
(new net.Socket({ handle }) followed by connect()).

Constructing a net.BoundHandle binds inline via the existing
uv_tcp_bind() path, so the kernel-assigned address (including the
ephemeral port when port is 0) is available immediately via
boundHandle.address(), and bind errors throw synchronously.

Adoption transfers ownership of the underlying handle; afterwards
address() and close() throw ERR_SOCKET_HANDLE_ADOPTED. An un-adopted
handle is released with close() or via Symbol.dispose (using).

The handle is passed in-process rather than as a file descriptor, so it
also works on Windows.

Author: guybedford

doc/api/errors.md

@@ -2972,6 +2972,14 @@ disconnected socket.
 
 A call was made and the UDP subsystem was not running.
 
+<a id="ERR_SOCKET_HANDLE_ADOPTED"></a>
+
+### `ERR_SOCKET_HANDLE_ADOPTED`
+
+An operation was attempted on a [`BoundHandle`][] that had already been adopted
+by a [`net.Server`][] or [`net.Socket`][]. Once a bound handle is adopted, its
+`address()` and `close()` methods can no longer be used.
+
 <a id="ERR_SOURCE_MAP_CORRUPT"></a>
 
 ### `ERR_SOURCE_MAP_CORRUPT`
@@ -4552,6 +4560,7 @@ An error occurred trying to allocate memory. This should never happen.
 [`--force-fips`]: cli.md#--force-fips
 [`--no-addons`]: cli.md#--no-addons
 [`--unhandled-rejections`]: cli.md#--unhandled-rejectionsmode
+[`BoundHandle`]: net.md#class-netboundhandle
 [`Class: assert.AssertionError`]: assert.md#class-assertassertionerror
 [`ERR_INCOMPATIBLE_OPTION_PAIR`]: #err_incompatible_option_pair
 [`ERR_INVALID_ARG_TYPE`]: #err_invalid_arg_type
@@ -4595,7 +4604,9 @@ An error occurred trying to allocate memory. This should never happen.
 [`http`]: http.md
 [`https`]: https.md
 [`libuv Error handling`]: https://docs.libuv.org/en/v1.x/errors.html
+[`net.Server`]: net.md#class-netserver
 [`net.Socket.write()`]: net.md#socketwritedata-encoding-callback
+[`net.Socket`]: net.md#class-netsocket
 [`net`]: net.md
 [`new URL(input)`]: url.md#new-urlinput-base
 [`new URLPattern(input)`]: url.md#new-urlpatternstring-baseurl-options

doc/api/net.md

@@ -523,8 +523,12 @@ Start a server listening for connections on a given `handle` that has
 already been bound to a port, a Unix domain socket, or a Windows named pipe.
 
 The `handle` object can be either a server, a socket (anything with an
-underlying `_handle` member), or an object with an `fd` member that is a
-valid file descriptor.
+underlying `_handle` member), a [`BoundHandle`][], or an object with an `fd`
+member that is a valid file descriptor.
+
+When `handle` is a [`BoundHandle`][], the server adopts the already-bound
+socket and starts listening on it. Adoption consumes the bound handle (see
+[ownership transfer][`BoundHandle`]).
 
 Listening on a file descriptor is not supported on Windows.
 
@@ -769,6 +773,12 @@ changes:
     access to specific IP addresses, IP ranges, or IP subnets.
   * `fd` {number} If specified, wrap around an existing socket with
     the given file descriptor, otherwise a new socket will be created.
+  * `handle` {net.BoundHandle} If specified, wrap around the bound socket from a
+    [`BoundHandle`][]. A subsequent
+    [`socket.connect()`][`socket.connect()`] uses the bound handle as the
+    connection's source binding (honoring the bound local address and port).
+    Adoption consumes the bound handle (see
+    [ownership transfer][`BoundHandle`]).
   * `keepAlive` {boolean} If set to `true`, it enables keep-alive functionality on
     the socket immediately after the connection is established, similarly on what
     is done in [`socket.setKeepAlive()`][]. **Default:** `false`.
@@ -1627,6 +1637,85 @@ This property represents the state of the connection as a string.
 * If the stream is readable and not writable, it is `readOnly`.
 * If the stream is not readable and writable, it is `writeOnly`.
 
+## Class: `net.BoundHandle`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+A role-neutral wrapper over a synchronously bound TCP socket, mirroring POSIX
+`bind(2)`, which is role-agnostic until `listen()` or `connect()`. It is adopted
+by exactly one server (via [`server.listen()`][]) or socket (via the `handle`
+option of [`new net.Socket()`][`new net.Socket(options)`]). Adoption transfers
+ownership of the socket; afterwards `address()` and `close()` throw
+[`ERR_SOCKET_HANDLE_ADOPTED`][]. A handle that is never adopted must be closed
+to avoid leaking the socket.
+
+```mjs
+import net from 'node:net';
+
+const bound = new net.BoundHandle({ host: '127.0.0.1', port: 0 });
+const { port } = bound.address();
+
+const server = net.createServer();
+server.listen(bound); // Adopt as a server, or pass to new net.Socket() instead.
+```
+
+### `new net.BoundHandle([options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `options` {Object}
+  * `host` {string} Local address to bind. Must be a numeric IP literal; no DNS
+    resolution is performed. **Default:** `'0.0.0.0'`, or `'::'` when
+    `ipv6Only` is `true`.
+  * `port` {number} Local port. `0` requests an OS-assigned ephemeral port.
+    **Default:** `0`.
+  * `ipv6Only` {boolean} Sets `IPV6_V6ONLY`, disabling dual-stack support so the
+    socket binds IPv6 only. Only meaningful for IPv6 binds. **Default:**
+    `false`.
+
+Synchronously binds a TCP socket. Because `bind(2)` is a local, non-blocking
+system call, the bind happens inline and errors (such as `EADDRINUSE`,
+`EADDRNOTAVAIL`, `EACCES`, or `EINVAL`) are thrown synchronously. The
+kernel-assigned address, including the ephemeral port chosen when `port` is `0`,
+is available immediately via
+[`boundHandle.address()`][`net.BoundHandle.address()`].
+
+This is the synchronous, role-neutral counterpart to the bind performed
+internally by [`server.listen()`][] and [`socket.connect()`][], analogous to
+[`dgram` `socket.bindSync()`][].
+
+### `boundHandle.address()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {Object} An object with `address`, `family`, and `port` properties,
+  as [`server.address()`][] returns.
+
+Returns the bound local address. When bound with `port: 0`, `port` is the
+OS-assigned ephemeral port.
+
+### `boundHandle.close()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Releases the bound socket. Only needed when the handle is never adopted.
+
+### `boundHandle[Symbol.dispose]()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Closes the handle if it has not been adopted or closed; otherwise a no-op.
+
 ## `net.connect()`
 
 Aliases to
@@ -2097,10 +2186,14 @@ net.isIPv6('fhqwhgads'); // returns false
 [`'error'`]: #event-error_1
 [`'listening'`]: #event-listening
 [`'timeout'`]: #event-timeout
+[`BoundHandle`]: #class-netboundhandle
+[`ERR_SOCKET_HANDLE_ADOPTED`]: errors.md#err_socket_handle_adopted
 [`EventEmitter`]: events.md#class-eventemitter
 [`child_process.fork()`]: child_process.md#child_processforkmodulepath-args-options
+[`dgram` `socket.bindSync()`]: dgram.md#socketbindsyncoptions
 [`dns.lookup()`]: dns.md#dnslookuphostname-options-callback
 [`dns.lookup()` hints]: dns.md#supported-getaddrinfo-flags
+[`net.BoundHandle.address()`]: #boundhandleaddress
 [`net.Server`]: #class-netserver
 [`net.Socket`]: #class-netsocket
 [`net.connect()`]: #netconnect
@@ -2116,6 +2209,7 @@ net.isIPv6('fhqwhgads'); // returns false
 [`net.getDefaultAutoSelectFamilyAttemptTimeout()`]: #netgetdefaultautoselectfamilyattempttimeout
 [`new net.Socket(options)`]: #new-netsocketoptions
 [`readable.setEncoding()`]: stream.md#readablesetencodingencoding
+[`server.address()`]: #serveraddress
 [`server.close()`]: #serverclosecallback
 [`server.dropMaxConnection`]: #serverdropmaxconnection
 [`server.listen()`]: #serverlisten

lib/internal/errors.js

@@ -1788,6 +1788,8 @@ E('ERR_SOCKET_CONNECTION_TIMEOUT',
 E('ERR_SOCKET_DGRAM_IS_CONNECTED', 'Already connected', Error);
 E('ERR_SOCKET_DGRAM_NOT_CONNECTED', 'Not connected', Error);
 E('ERR_SOCKET_DGRAM_NOT_RUNNING', 'Not running', Error);
+E('ERR_SOCKET_HANDLE_ADOPTED',
+  'The bound handle has already been adopted by a server or socket', Error);
 E('ERR_SOURCE_MAP_CORRUPT', `The source map for '%s' does not exist or is corrupt.`, Error);
 E('ERR_SOURCE_MAP_MISSING_SOURCE', `Cannot find '%s' imported from the source map for '%s'`, Error);
 E('ERR_SRI_PARSE',

lib/net.js

@@ -118,6 +118,7 @@ const {
     ERR_SOCKET_CLOSED,
     ERR_SOCKET_CLOSED_BEFORE_CONNECTION,
     ERR_SOCKET_CONNECTION_TIMEOUT,
+    ERR_SOCKET_HANDLE_ADOPTED,
   },
   genericNodeError,
 } = require('internal/errors');
@@ -135,6 +136,7 @@ const {
   validateFunction,
   validateInt32,
   validateNumber,
+  validateObject,
   validatePort,
   validateString,
 } = require('internal/validators');
@@ -363,6 +365,105 @@ const kBytesRead = Symbol('kBytesRead');
 const kBytesWritten = Symbol('kBytesWritten');
 const kSetTOS = Symbol('kSetTOS');
 
+// Internal: adopt the underlying handle, transferring ownership to a
+// Server/Socket. Used by server.listen() and the Socket constructor.
+const kBoundHandleConsume = Symbol('kBoundHandleConsume');
+
+// A thin, role-neutral wrapper over a synchronously bound libuv TCP handle,
+// mirroring POSIX bind(2): the socket is bound to a local address but has not
+// chosen a role. It neither listens nor connects until it is adopted by exactly
+// one Server (via server.listen()) or Socket (via new net.Socket({ handle })).
+// Adoption transfers ownership of the underlying handle; an un-adopted
+// BoundHandle must be closed by the caller.
+//
+// bind(2) is a local, non-blocking system call, so binding happens inline in
+// the constructor and errors throw synchronously. The host must be a numeric IP
+// literal: no DNS resolution is performed.
+class BoundHandle {
+  #handle;
+
+  constructor(options = kEmptyObject) {
+    validateObject(options, 'options');
+
+    const port = validatePort(options.port ?? 0, 'options.port');
+
+    const ipv6Only = options.ipv6Only ?? false;
+    validateBoolean(ipv6Only, 'options.ipv6Only');
+
+    let { host } = options;
+    let addressType;
+    if (host === undefined || host === null) {
+      host = ipv6Only ? DEFAULT_IPV6_ADDR : DEFAULT_IPV4_ADDR;
+      addressType = ipv6Only ? 6 : 4;
+    } else {
+      validateString(host, 'options.host');
+      addressType = isIP(host);
+      if (addressType === 0) {
+        throw new ERR_INVALID_ARG_VALUE(
+          'options.host', host,
+          'must be a numeric IP address; net.BoundHandle does not perform DNS resolution');
+      }
+    }
+
+    let flags = 0;
+    if (ipv6Only) {
+      flags |= TCPConstants.UV_TCP_IPV6ONLY;
+    }
+
+    const handle = new TCP(TCPConstants.SOCKET);
+    const err = addressType === 6 ?
+      handle.bind6(host, port, flags) :
+      handle.bind(host, port, flags);
+    if (err) {
+      handle.close();
+      throw new ExceptionWithHostPort(err, 'bind', host, port);
+    }
+
+    this.#handle = handle;
+  }
+
+  // The kernel-assigned local address; reflects the OS-assigned ephemeral port
+  // when the bind requested port 0.
+  address() {
+    if (this.#handle === null) {
+      throw new ERR_SOCKET_HANDLE_ADOPTED();
+    }
+    const out = {};
+    const err = this.#handle.getsockname(out);
+    if (err) {
+      throw new ErrnoException(err, 'address');
+    }
+    return out;
+  }
+
+  // Release the socket if it is never adopted, preventing an fd/handle leak.
+  close() {
+    if (this.#handle === null) {
+      throw new ERR_SOCKET_HANDLE_ADOPTED();
+    }
+    this.#handle.close();
+    this.#handle = null;
+  }
+
+  // Enables `using bound = net.bindSync(...)`: closes an un-adopted handle and
+  // is a no-op once the handle has been adopted or closed.
+  [SymbolDispose]() {
+    if (this.#handle !== null) {
+      this.#handle.close();
+      this.#handle = null;
+    }
+  }
+
+  [kBoundHandleConsume]() {
+    if (this.#handle === null) {
+      throw new ERR_SOCKET_HANDLE_ADOPTED();
+    }
+    const handle = this.#handle;
+    this.#handle = null;
+    return handle;
+  }
+}
+
 function Socket(options) {
   if (!(this instanceof Socket)) return new Socket(options);
   if (options?.objectMode) {
@@ -420,8 +521,19 @@ function Socket(options) {
   options.decodeStrings = false;
   stream.Duplex.call(this, options);
 
+  // A BoundHandle from net.bindSync() is bound but not connected, so the read
+  // flow must not start until a later connect() completes.
+  let boundNotConnected = false;
   if (options.handle) {
-    this._handle = options.handle; // private
+    // A BoundHandle is adopted here, transferring ownership of its underlying
+    // handle so a subsequent connect() drives it as the connection's source
+    // binding.
+    if (options.handle instanceof BoundHandle) {
+      this._handle = options.handle[kBoundHandleConsume]();
+      boundNotConnected = true;
+    } else {
+      this._handle = options.handle; // private
+    }
     this[async_id_symbol] = getNewAsyncId(this._handle);
   } else if (options.fd !== undefined) {
     const { fd } = options;
@@ -492,7 +604,7 @@ function Socket(options) {
 
   // If we have a handle, then start the flow of data into the
   // buffer.  if not, then this will happen when we connect
-  if (this._handle && options.readable !== false) {
+  if (this._handle && options.readable !== false && !boundNotConnected) {
     if (options.pauseOnCreate) {
       // Stop the handle from reading and pause the stream
       this._handle.reading = false;
@@ -2144,6 +2256,22 @@ Server.prototype.listen = function(...args) {
     toNumber(args.length > 1 && args[1]) ||
     toNumber(args.length > 2 && args[2]);  // (port, host, backlog)
 
+  // (boundHandle[, ...]) or ({ handle: boundHandle }[, ...]) from
+  // net.bindSync(): adopt the bound handle, transferring ownership so the
+  // BoundHandle can no longer close it.
+  let boundHandle = null;
+  if (options instanceof BoundHandle) {
+    boundHandle = options;
+  } else if (options.handle instanceof BoundHandle) {
+    boundHandle = options.handle;
+  }
+  if (boundHandle !== null) {
+    this._handle = boundHandle[kBoundHandleConsume]();
+    this[async_id_symbol] = this._handle.getAsyncId();
+    this._listeningId++;
+    listenInCluster(this, null, -1, -1, backlogFromArgs, undefined, true);
+    return this;
+  }
   options = options._handle || options.handle || options;
   const flags = getFlags(options);
   //  Refresh the id to make the previous call invalid
@@ -2573,6 +2701,7 @@ module.exports = {
     SocketAddress ??= require('internal/socketaddress').SocketAddress;
     return SocketAddress;
   },
+  BoundHandle,
   connect,
   createConnection: connect,
   createServer,