import crypto from "node:crypto"; import net from "node:net"; import { RANDOM_PORT_MAX, RANDOM_PORT_MIN, RANDOM_PORT_RETRIES } from "./constants"; const CONNECT_PROBE_TIMEOUT_MS = 500; export function ensureValidPort(port: number | undefined, name: string): number | undefined { if (port === undefined) { return undefined; } if (!Number.isInteger(port) || port <= 0 || port > 65535) { throw new Error(`${name} must be an integer between 1 and 65535`); } return port; } /** * Tries to connect to a port on the given host. Returns true if something * is already listening (i.e. the port is in use). Returns false on connection * refused, on any other socket error, or when the probe takes longer than * `timeoutMs` — under WSL2 mirrored networking the kernel can silently drop * the SYN to an unbound loopback port, so an unbounded connect would hang * forever and deadlock isPortAvailable. * * Used alongside canBindPort because it detects ports where a listener is * bound with SO_REUSEADDR (Node's default on macOS), which a bind-only check * would miss. */ function isPortInUse( port: number, host: string, timeoutMs = CONNECT_PROBE_TIMEOUT_MS, ): Promise { return new Promise((resolve) => { const socket = net.createConnection({ port, host }); let settled = false; const done = (v: boolean) => { if (settled) return; settled = true; socket.destroy(); resolve(v); }; socket.once("connect", () => done(true)); socket.once("error", () => done(false)); setTimeout(() => done(false), timeoutMs).unref(); }); } /** * Tries to bind a port on the given host. Returns true if the bind succeeds * (port is free). Closes immediately on success. * * This catches Windows "phantom" port reservations: Hyper-V/WSL silently * reserve random port ranges at boot that don't appear in netstat or via a * connect probe (nothing is listening, so connect-check thinks the port is * free) — but bind fails with "Only one usage of each socket address". A * connect-only check causes kandev's backend to choose a reserved port and * then die when it tries to actually listen on it. */ function canBindPort(port: number, host: string): Promise { return new Promise((resolve) => { const server = net.createServer(); server.once("error", () => resolve(false)); server.listen(port, host, () => { server.close(() => resolve(true)); }); }); } /** * Checks if a port is available by probing both IPv4 and IPv6 loopback. * * Uses BOTH a connect check and a bind check: * - connect: detects ports where a listener is bound with SO_REUSEADDR * (Node's default on macOS — bind-only check would falsely succeed) * - bind: detects Windows phantom reservations (Hyper-V/WSL) and * ports in TIME_WAIT that connect-only check misses * * The port is available IFF nobody answers a connect AND a fresh bind * succeeds — covers macOS, Linux, and Windows. */ async function isPortAvailable(port: number): Promise { // Run connect probes first, then the bind probe — they cannot share the // port concurrently. On loopback, server.listen() completes in the kernel // before a connect SYN to the same address is processed, so a concurrent // canBindPort+isPortInUse pair can answer each other and report a free // port as occupied. Sequencing keeps the bind probe's temporary listener // out of the connect probes' view. const [v4InUse, v6InUse] = await Promise.all([ isPortInUse(port, "127.0.0.1"), isPortInUse(port, "::1"), ]); if (v4InUse || v6InUse) return false; return canBindPort(port, "127.0.0.1"); } async function reserveSpecificPort(port: number, host = "127.0.0.1"): Promise { return new Promise((resolve) => { const server = net.createServer(); server.on("error", () => resolve(null)); server.listen(port, host, () => resolve(server)); }); } export async function pickAvailablePort( preferred: number, retries = RANDOM_PORT_RETRIES, ): Promise { if (await isPortAvailable(preferred)) { return preferred; } for (let i = 0; i < retries; i += 1) { const candidate = crypto.randomInt(RANDOM_PORT_MIN, RANDOM_PORT_MAX + 1); if (await isPortAvailable(candidate)) { return candidate; } } throw new Error(`Unable to find a free port after ${retries + 1} attempts`); } export async function pickAndReservePort( preferred: number, retries = RANDOM_PORT_RETRIES, ): Promise<{ port: number; release: () => Promise }> { if (await isPortAvailable(preferred)) { const reservedPreferred = await reserveSpecificPort(preferred); if (reservedPreferred) { return { port: preferred, release: () => new Promise((resolve) => reservedPreferred.close(() => resolve())), }; } } for (let i = 0; i < retries; i += 1) { const candidate = crypto.randomInt(RANDOM_PORT_MIN, RANDOM_PORT_MAX + 1); if (!(await isPortAvailable(candidate))) continue; const reserved = await reserveSpecificPort(candidate); if (reserved) { return { port: candidate, release: () => new Promise((resolve) => reserved.close(() => resolve())), }; } } throw new Error(`Unable to reserve a free port after ${retries + 1} attempts`); } // Exported for tests only. export const __testing = { isPortInUse, isPortAvailable };