@jterrazz/test 18.0.0 → 18.0.1

package/dist/shared-serve.js

@@ -1,11 +1,13 @@
 import { n as refusal } from "./shared-refusal.js";
 import { n as untilDeadline } from "./shared-pause.js";
-import { t as listenedPort } from "./shared-listened-port.js";
+import "./shared-listened-port.js";
 import "node:module";
 import { resolve } from "node:path";
 import { execSync, spawn, spawnSync } from "node:child_process";
-import { Socket, connect, createServer } from "node:net";
+import { randomInt } from "node:crypto";
+import { Socket, connect } from "node:net";
 import { once } from "node:events";
+import { createSocket } from "node:dgram";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
@@ -19,13 +21,6 @@ var __exportAll = (all, no_symbols) => {
 };
 //#endregion
 //#region src/services/process/listening.ts
-async function findFreePort() {
-	const server = createServer();
-	const port = await listenedPort(server);
-	server.close();
-	await once(server, "close");
-	return port;
-}
 async function firstAnswering(urls) {
 	return (await Promise.all(urls.map(async (url) => await answers(url) ? url : void 0))).find((url) => url !== void 0);
 }
@@ -98,6 +93,69 @@ async function refuseHeldPort(port, specification, command) {
 	}));
 }
 //#endregion
+//#region src/services/process/port-reservation.ts
+const DRAWN_PORTS = {
+	first: 1e4,
+	last: 32767
+};
+function draw() {
+	return randomInt(DRAWN_PORTS.first, DRAWN_PORTS.last + 1);
+}
+async function claimPort(port) {
+	const socket = createSocket("udp4");
+	const failure = await new Promise((resolve) => {
+		socket.on("error", resolve);
+		socket.bind({
+			address: "127.0.0.1",
+			port
+		}, () => {
+			resolve(void 0);
+		});
+	});
+	if (failure === void 0) {
+		socket.unref();
+		return {
+			port,
+			release: closing(socket)
+		};
+	}
+	socket.close();
+	return failure instanceof Error && "code" in failure && failure.code === "EADDRINUSE" ? void 0 : {
+		port,
+		release: () => void 0
+	};
+}
+function closing(socket) {
+	let open = true;
+	return () => {
+		if (open) {
+			open = false;
+			socket.close();
+		}
+	};
+}
+async function reserveFreePort(pick = draw) {
+	for (let attempt = 0; attempt < 64; attempt += 1) {
+		const reservation = await claimPort(pick());
+		if (reservation === void 0) continue;
+		if (await holdingHost(reservation.port) === void 0) return reservation;
+		reservation.release();
+	}
+}
+/** The port a served process is handed (the one `port` pins, else a drawn one) reserved for it, or the lesson of why none could be. */
+async function reservePort(pinned, pick = draw) {
+	if (pinned !== void 0) return await claimPort(pinned) ?? {
+		fix: "drop the `port` option so each process is handed a free one, or run the specifications that pin it one at a time",
+		found: `port ${String(pinned)}, which \`port\` pins, is reserved by another served process on this machine`,
+		why: "A port is one served process's at a time, and a server sharing it would answer in the other's place."
+	};
+	return await reserveFreePort(pick) ?? {
+		fix: "stop the servers holding the ports of that range, or pin a free one with `port`",
+		found: `no free port in ${String(DRAWN_PORTS.first)}-${String(DRAWN_PORTS.last)} after ${String(64)} draws`,
+		why: "A process is handed a port drawn below the range the OS hands unasked ports from, and one nothing holds."
+	};
+}
+//#endregion
 //#region src/services/process/process-group.ts
 const KILL_GRACE_MS = 2e3;
 /** outside: Windows has no process groups to signal through a negative pid. */
@@ -241,7 +299,7 @@ function runToCompletion(command, env) {
 		stdio: "pipe"
 	});
 }
-/** Any HTTP status counts as ready. The child runs in its own process group so `stop()` kills a `next start` grandchild too, and a watchdog kills that group when the run dies before `stop()`; both reap the strays it declares, the processes it spawns outside its group. */
+/** Any HTTP status counts as ready, since the port it is handed is reserved for it until `stop()`: no other served process is handed it, and no socket is handed it by chance. The child runs in its own process group so `stop()` kills a `next start` grandchild too, and a watchdog kills that group when the run dies before `stop()`; both reap the strays it declares, the processes it spawns outside its group. */
 var ServedProcess = class {
 	port = null;
 	child = null;
@@ -249,6 +307,7 @@ var ServedProcess = class {
 	extraEnv;
 	specification;
 	options;
+	reservation = null;
 	exited = false;
 	output = "";
 	root;
@@ -265,7 +324,7 @@ var ServedProcess = class {
 		await refuseHeldPort(this.options.port, this.specification, this.options.command);
 		this.runBefore();
 		const banner = this.options.ready instanceof RegExp ? this.options.ready : null;
-		const port = banner ? null : this.options.port ?? await findFreePort();
+		const port = banner ? null : await this.reserve();
 		this.spawnServer(port);
 		return (banner ? await this.awaitBanner(banner) : await this.awaitAnswer(port ?? 0)) ?? await this.refuse({
 			fix: "run the command by hand and correct what its output names",
@@ -273,6 +332,14 @@ var ServedProcess = class {
 			why: "A process is handed to the chain once it is ready, and one that exits never is."
 		});
 	}
+	async reserve() {
+		const reserved = await reservePort(this.options.port);
+		if ("release" in reserved) {
+			this.reservation = reserved;
+			return reserved.port;
+		}
+		return await this.refuse(reserved);
+	}
 	environment(port) {
 		return {
 			...process.env,
@@ -392,6 +459,8 @@ var ServedProcess = class {
 		}));
 	}
 	async stop() {
+		this.reservation?.release();
+		this.reservation = null;
 		const { child } = this;
 		if (!child) return;
 		this.child = null;

package/docs/reference/services.md

@@ -49,15 +49,15 @@ A site's dev server, an API the site calls, the bundler a simulator loads from:
 
 The options type is `ProcessOptions`, one shape for the one external process every specification starts.
 
-| Option    | Means                                                                                                                                                                                                                                                                                                                             |
-| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `command` | the shell command that starts it, receiving the chosen port as `PORT`                                                                                                                                                                                                                                                             |
-| `ready`   | a **path** polled until it answers (default `/`), or a **RegExp** over the child's output whose one capture group is the port                                                                                                                                                                                                     |
-| `port`    | a fixed port instead of a free one the OS assigns; a port another process already answers on (`127.0.0.1` or `::1`, the hosts readiness asks) is refused before the command runs, since it would answer in the server's place, and a server that cannot bind it (`EADDRINUSE`) is refused naming this option, whatever it printed |
-| `cwd`     | a working directory relative to the project root, or a function returning one, called when the process starts (once per file, for a spec that lays a fresh project for each)                                                                                                                                                      |
-| `env`     | the child's environment: an object, or a function of the services started beside it                                                                                                                                                                                                                                               |
-| `before`  | a one-shot command run ONCE per evaluation of the specification module (under vitest's default isolation, once per test file), which must exit 0: a build, a migration, a fixture load; it runs with the same `env` as the command, so a build that reads a variable reads it here too                                            |
-| `timeout` | the readiness budget, in milliseconds (default 30 000)                                                                                                                                                                                                                                                                            |
+| Option    | Means                                                                                                                                                                                                                                                                                                                                                                   |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `command` | the shell command that starts it, receiving the chosen port as `PORT`                                                                                                                                                                                                                                                                                                   |
+| `ready`   | a **path** polled until it answers (default `/`), or a **RegExp** over the child's output whose one capture group is the port                                                                                                                                                                                                                                           |
+| `port`    | a fixed port instead of a free one the framework draws; a port another served process holds, or another process already answers on (`127.0.0.1` or `::1`, the hosts readiness asks) is refused before the command runs, since it would answer in the server's place, and a server that cannot bind it (`EADDRINUSE`) is refused naming this option, whatever it printed |
+| `cwd`     | a working directory relative to the project root, or a function returning one, called when the process starts (once per file, for a spec that lays a fresh project for each)                                                                                                                                                                                            |
+| `env`     | the child's environment: an object, or a function of the services started beside it                                                                                                                                                                                                                                                                                     |
+| `before`  | a one-shot command run ONCE per evaluation of the specification module (under vitest's default isolation, once per test file), which must exit 0: a build, a migration, a fixture load; it runs with the same `env` as the command, so a build that reads a variable reads it here too                                                                                  |
+| `timeout` | the readiness budget, in milliseconds (default 30 000)                                                                                                                                                                                                                                                                                                                  |
 
 It sits in a `services` record like any other service, so it starts after the databases and can be handed their connection strings, and it is stopped with the specification:
 
@@ -82,6 +82,10 @@ export const { cleanup, website } = await specification.website({
 });
 ```
 
+**A port is one process's at a time.** The port handed as `PORT` is drawn between 10000 and 32767, below the range every OS hands unasked ports from (a `listen(0)`, a stub's port, an outgoing connection), so no other socket is handed it by chance while the command starts. It is reserved from the draw until the process stops, against every served process of the machine whatever run started it, so files running in parallel never share one; a draw that finds no free port in 64 tries is refused. A `port` two processes pin at once is held by the first, and the second is refused before its command runs.
+
+**Any status the `ready` path answers is the server's.** Nothing else can answer on a port reserved that way: the one process that could is one started by hand on that very number while the command starts.
+
 **Its URL is known once it is ready.** `url` read at declaration time is refused: a process started beside others reads theirs from the started services record: `env: (services) => ...`, `server: (services) => ...`.
 
 **The framework ends what it started.** A process is spawned detached (its own process group on POSIX), and on teardown the whole group is sent `SIGTERM`, escalating to `SIGKILL` after a 2 s grace, so what the command forked (a watcher, a background server) dies with it instead of outliving the run. On POSIX, a run that dies before its teardown (killed, `SIGKILL` included) ends the group all the same: a watchdog outside the group holds a pipe from the run, and when the pipe closes it sends the group the same `SIGTERM`, then `SIGKILL`. Every served process is ended the same way, by the same code: a website's server, a mobile run's Appium server, a cli document's services. A mobile run's Appium server owns more than its group: the WebDriverAgent it starts for the simulator runs in a group of its own, and the teardown and the watchdog end it as well ([Mobile specs](../guides/mobile-specs.md#the-simulator-and-what-the-run-leaves-on-it)).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jterrazz/test",
-    "version": "18.0.0",
+    "version": "18.0.1",
     "description": "Declarative testing framework for HTTP APIs, CLIs, background jobs, websites, mobile apps, rendered components and the rules a project ships: one entry point, real infrastructure and a real browser, golden-file assertions, plus an oxlint convention plugin.",
     "keywords": [
         "api-testing",