net.BoundSocket

History

Allows for the synchronous creation of a pre-bound socket, that can be passed to listen() or new net.Socket() later on. For listen() this enables synchronous port reservation, while for new net.Socket(), it allows control over the local egress port/IP, via bind(2) semantics.

A BoundSocket binds either a TCP endpoint (host or port) or a Unix domain/named-pipe endpoint (path); the two are mutually exclusive. For a path, the file system entry is reserved in the constructor, so conflicts such as EADDRINUSE throw synchronously exactly as a TCP bind does. On Linux a leading '\0' in path selects the abstract namespace (no file system entry); an abstract path on any other platform throws ERR_INVALID_ARG_VALUE.

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. Closing a pipe BoundSocket removes its file system entry; abstract and TCP binds have none to remove.

When a pipe BoundSocket bound to a source path is adopted as a client, that path is reported as the socket's localAddress once it connects.

When an adopted BoundSocket connects to a numeric IP literal, connect(2) is issued synchronously, so socket.localAddress is resolved once socket.connect() returns. Connection failures are still reported via a deferred 'error' event.

import net from 'node:net';

const bound = new net.BoundSocket();
const { port } = bound.address();
console.log(`Reserved port ${port} for server`);

const server = net.createServer();
server.listen(bound); // Adopt as a server, or pass to new net.Socket() instead.

JavaScript

net.BoundSocket Constructor

History

new net.BoundSocket(options?): net.BoundSocket

Attributes

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.

reusePort?:boolean

Sets SO_REUSEPORT, allowing multiple sockets to bind the same address and port for kernel-level load balancing. Support is platform-dependent. Default: false.

path:string

Binds a Unix domain socket (or Windows named pipe) at the given path instead of a TCP endpoint. A leading '\0' selects the Linux abstract namespace. Mutually exclusive with host, port, ipv6Only, and reusePort; combining them throws ERR_INVALID_ARG_VALUE.

boundSocket.address

History

boundSocket.address(): Object | string

Returns:Object | string

For a TCP bind, an object with address, family, and port properties, as server.address() returns. For a pipe bind, the bound path string, as server.address() returns for a pipe server.

Returns the bound local address. When bound with port: 0, port is the OS-assigned ephemeral port.

boundSocket.isPipe

History

Attributes

boolean

true when the socket was bound with a path (a Unix domain socket or Windows named pipe), false for a TCP bind. The getter's presence on net.BoundSocket.prototype also serves as a capability probe for path support.

boundSocket.fd

History

boundSocket.fd(): integer

Returns:integer

The underlying OS file descriptor, or -1 on platforms that do not expose one for sockets (such as Windows).

Returns the file descriptor of the bound socket. Ownership remains with the BoundSocket, so the descriptor must not be closed by the caller. The descriptor is only available before the handle is adopted; afterwards it belongs to the adopting net.Server or net.Socket and fd() throws ERR_SOCKET_HANDLE_ADOPTED.

boundSocket.close

History

boundSocket.close(): void

Releases the bound socket. Only needed when the handle is never adopted.

boundSocket[Symbol.dispose]

History

boundSocket[Symbol.dispose](): void

Closes the handle if it has not been adopted or closed; otherwise a no-op.