@jterrazz/test 16.1.1 → 17.0.0

package/dist/shared-serve.js

@@ -0,0 +1,365 @@
+import { n as refusal, t as invariant } from "./shared-refusal.js";
+import { t as pause } from "./shared-pause.js";
+import "node:module";
+import { resolve } from "node:path";
+import { execSync, spawn, spawnSync } from "node:child_process";
+import { Socket, createServer } from "node:net";
+import { once } from "node:events";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+//#region src/services/process/listening.ts
+async function findFreePort() {
+	return await new Promise((resolve, reject) => {
+		const server = createServer();
+		server.listen(0, () => {
+			const address = server.address();
+			if (address === null || typeof address === "string") {
+				server.close();
+				reject(invariant("a server listening on port 0 answered no port"));
+				return;
+			}
+			const { port } = address;
+			server.close(() => {
+				resolve(port);
+			});
+		});
+		server.on("error", reject);
+	});
+}
+async function firstAnswering(urls) {
+	return (await Promise.all(urls.map(async (url) => await answers(url) ? url : void 0))).find((url) => url !== void 0);
+}
+async function answers(url) {
+	try {
+		await fetch(url, { redirect: "manual" });
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/services/process/port-in-use.ts
+const PORT_IN_USE = /EADDRINUSE|address already in use|port \d+ is already in use/iu;
+function lessonOf(reason, output, port) {
+	if (!PORT_IN_USE.test(output)) return reason;
+	return {
+		fix: port === void 0 ? "have the command listen on the `PORT` it is handed, a free one, or stop the process holding the port it binds" : `stop the process holding port ${String(port)}, or drop the \`port\` option so a free one is picked`,
+		found: "the server could not bind its port, which another process already holds",
+		why: "A process is handed a free port unless `port` pins one, and a port another process holds is not free."
+	};
+}
+//#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. */
+const SIGNALS_GROUPS = process.platform !== "win32";
+const GROUP_POLL_MS = 1e3;
+const GROUP_SETTLE_MS = 50;
+const STRAYS_SOURCE = `
+const { execFileSync } = require('node:child_process');
+const strays = JSON.parse(process.argv[1] ?? '[]');
+const listed = (column) => {
+    let listing = '';
+    try { listing = execFileSync('ps', ['-A', '-o', 'pid=,' + column + '='], { encoding: 'utf8', maxBuffer: 67108864 }); } catch {}
+    return new Map(listing.split('\\n').flatMap((line) => {
+        const found = /^\\s*(\\d+)\\s(.*)$/u.exec(line);
+        return found === null ? [] : [[Number(found[1]), found[2]]];
+    }));
+};
+const names = (path, program) => path === program || path.endsWith('/' + program);
+const strayPids = () => {
+    const commands = listed('command');
+    return [...listed('comm')]
+        .filter(([pid, executable]) => {
+            const command = commands.get(pid) ?? '';
+            return pid !== process.pid && strays.some((stray) =>
+                (names(executable, stray.program) || names(command.split(' ')[0], stray.program)) && stray.holds.every((word) => command.includes(word)));
+        })
+        .map(([pid]) => pid);
+};
+const signalStrays = (signal) => {
+    for (const pid of strays.length === 0 ? [] : strayPids()) {
+        try { process.kill(-pid, signal); } catch {}
+        try { process.kill(pid, signal); } catch {}
+    }
+};
+`;
+/** Its arguments are the strays, then the group. With strays to reap, it outlives the group: a stray outlives the group that spawned it. */
+const WATCHDOG = `${STRAYS_SOURCE}
+const group = -Number(process.argv[2]);
+const gone = () => { try { process.kill(group, 0); return false; } catch { return true; } };
+const end = () => {
+    try { process.kill(group, 'SIGTERM'); } catch { if (strays.length === 0) process.exit(0); }
+    signalStrays('SIGTERM');
+    setTimeout(() => { try { process.kill(group, 'SIGKILL'); } catch {} signalStrays('SIGKILL'); process.exit(0); }, ${KILL_GRACE_MS});
+};
+process.stdin.on('end', end);
+process.stdin.on('error', end);
+process.stdin.resume();
+setInterval(() => { if (strays.length === 0 && gone()) process.exit(0); }, ${GROUP_POLL_MS});
+`;
+/** Its argument is the strays: each gets SIGTERM, and SIGKILL when it outlives the grace. */
+const REAPER = `${STRAYS_SOURCE}
+signalStrays('SIGTERM');
+const deadline = Date.now() + ${KILL_GRACE_MS};
+const settle = () => {
+    if (strayPids().length === 0) return;
+    if (Date.now() >= deadline) { signalStrays('SIGKILL'); return; }
+    setTimeout(settle, ${GROUP_SETTLE_MS});
+};
+settle();
+`;
+function groupRunning(group) {
+	try {
+		process.kill(group, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function endedBy(group, deadline) {
+	if (!groupRunning(group)) return true;
+	if (Date.now() >= deadline) return false;
+	await pause(GROUP_SETTLE_MS);
+	return await endedBy(group, deadline);
+}
+async function groupEnded(group, withinMs) {
+	return await endedBy(group, Date.now() + withinMs);
+}
+/** Resolves once the child is reaped, at once for one reaped already. */
+async function reaped(child) {
+	if (child.exitCode !== null || child.signalCode !== null) return;
+	await once(child, "exit");
+}
+/** The child's whole group where groups are signalled, the child alone where they are not or the group is gone; nothing for a child that never started. */
+function signalGroup(child, signal = "SIGTERM") {
+	if (child.pid === void 0) return false;
+	if (SIGNALS_GROUPS) try {
+		process.kill(-child.pid, signal);
+		return true;
+	} catch {}
+	return child.kill(signal);
+}
+//#endregion
+//#region src/services/process/serve.ts
+var serve_exports = /* @__PURE__ */ __exportAll({
+	ServedProcess: () => ServedProcess,
+	runToCompletion: () => runToCompletion
+});
+const DEFAULT_READY_TIMEOUT = 3e4;
+const READY_POLL_INTERVAL_MS = 250;
+function watchGroup(groupId, strays) {
+	const args = [
+		"-e",
+		WATCHDOG,
+		JSON.stringify(strays),
+		String(groupId)
+	];
+	const watchdog = spawn(process.execPath, args, {
+		detached: true,
+		env: {
+			...process.env,
+			NODE_OPTIONS: void 0
+		},
+		stdio: [
+			"pipe",
+			"ignore",
+			"ignore"
+		]
+	});
+	watchdog.on("error", () => {
+		watchdog.stdin?.destroy();
+	});
+	watchdog.unref();
+	if (watchdog.stdin instanceof Socket) watchdog.stdin.unref();
+	return watchdog;
+}
+async function reapStrays(strays) {
+	const args = [
+		"-e",
+		REAPER,
+		JSON.stringify(strays)
+	];
+	await (strays.length > 0 ? reaped(spawn(process.execPath, args, { stdio: "ignore" })) : null);
+}
+function runToCompletion(command, env) {
+	execSync(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. */
+var ServedProcess = class {
+	port = null;
+	child = null;
+	extraEnv;
+	specification;
+	options;
+	exited = false;
+	output = "";
+	root;
+	strays;
+	watchdog = null;
+	constructor(options, root, specification = "website", extraEnv = {}) {
+		this.extraEnv = extraEnv;
+		this.strays = options.strays ?? [];
+		this.specification = specification;
+		this.options = options;
+		this.root = root;
+	}
+	async start() {
+		this.runBefore();
+		const banner = this.options.ready instanceof RegExp ? this.options.ready : null;
+		const port = banner ? null : this.options.port ?? await findFreePort();
+		this.spawnServer(port);
+		const deadline = Date.now() + this.timeout();
+		return (banner ? await this.awaitBanner(banner, deadline) : await this.awaitAnswer(port ?? 0, deadline)) ?? await this.refuse({
+			fix: "run the command by hand and correct what its output names",
+			found: "the server command exited before it was ready",
+			why: "A process is handed to the chain once it is ready, and one that exits never is."
+		});
+	}
+	environment(port) {
+		return {
+			...process.env,
+			ASTRO_DEV_BACKGROUND: "1",
+			ASTRO_PREVIEW_BACKGROUND: "1",
+			...typeof this.options.env === "function" ? {} : this.options.env,
+			...this.extraEnv,
+			...port === null ? {} : { PORT: String(port) }
+		};
+	}
+	spawnServer(port) {
+		const child = spawn(this.options.command, [], {
+			cwd: this.workingDirectory(),
+			detached: SIGNALS_GROUPS,
+			env: this.environment(port),
+			shell: true,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		this.child = child;
+		this.exited = false;
+		if (child.pid !== void 0 && SIGNALS_GROUPS) this.watchdog = watchGroup(child.pid, this.strays);
+		const collect = (data) => {
+			this.output += String(data);
+		};
+		child.stdout?.on("data", collect);
+		child.stderr?.on("data", collect);
+		child.on("close", () => {
+			this.exited = true;
+		});
+		child.on("error", (error) => {
+			collect(`${String(error)}\n`);
+		});
+	}
+	async awaitBanner(banner, deadline) {
+		while (!this.exited) {
+			banner.lastIndex = 0;
+			const found = banner.exec(this.output);
+			if (found) return await this.bannerPort(banner, found[1]);
+			if (Date.now() >= deadline) return await this.refuse({
+				fix: "correct the pattern to what the server prints, or raise `timeout`",
+				found: `the server did not print ${String(banner)} within ${this.timeout()}ms`,
+				why: "A process is ready once its output matches `ready`, within `timeout`."
+			});
+			await pause(READY_POLL_INTERVAL_MS);
+		}
+		return null;
+	}
+	async bannerPort(banner, group) {
+		const captured = Number(group);
+		if (!Number.isInteger(captured)) return await this.refuse({
+			fix: "capture the port alone in the pattern's one group, e.g. /listening on (\\d+)/",
+			found: `the ready pattern ${String(banner)} matched, and its capture group is not a port ("${group}")`,
+			why: "A RegExp `ready` is read over the output, and its one capture group is the port."
+		});
+		this.port = captured;
+		return `http://127.0.0.1:${captured}`;
+	}
+	async awaitAnswer(port, deadline) {
+		const baseUrls = [`http://127.0.0.1:${port}`, `http://[::1]:${port}`];
+		const path = typeof this.options.ready === "string" ? this.options.ready : "/";
+		while (!this.exited) {
+			const answering = await firstAnswering(baseUrls.map((baseUrl) => `${baseUrl}${path}`));
+			if (answering !== void 0) {
+				this.port = port;
+				return answering.slice(0, answering.length - path.length);
+			}
+			if (Date.now() >= deadline) return await this.refuse({
+				fix: "correct `ready` to a path the server answers, have it listen on `PORT`, or raise `timeout`",
+				found: `the server did not answer on ${baseUrls.map((baseUrl) => `${baseUrl}${path}`).join(" or ")} within ${this.timeout()}ms, whatever address it printed above`,
+				why: "A process is ready once its `ready` path answers, within `timeout`."
+			});
+			await pause(READY_POLL_INTERVAL_MS);
+		}
+		return null;
+	}
+	timeout() {
+		return this.options.timeout ?? DEFAULT_READY_TIMEOUT;
+	}
+	async refuse(reason) {
+		await this.stop();
+		const lesson = lessonOf(reason, this.output, this.options.port);
+		throw new Error(refusal({
+			fix: lesson.fix,
+			found: `specification.${this.specification}(): ${lesson.found}.\nCommand: ${this.options.command}\nOutput:\n${this.output}`,
+			read: "docs/reference/services.md#process-the-one-shape-an-external-process-takes",
+			why: lesson.why
+		}));
+	}
+	workingDirectory() {
+		const { cwd = "." } = this.options;
+		return resolve(this.root, typeof cwd === "function" ? cwd() : cwd);
+	}
+	/** Must exit 0: a failed build is reported as such, not as a later missing file. */
+	runBefore() {
+		const { before } = this.options;
+		if (before === void 0) return;
+		const outcome = spawnSync(before, [], {
+			cwd: this.workingDirectory(),
+			env: this.environment(null),
+			encoding: "utf8",
+			shell: true
+		});
+		if (outcome.status !== 0) throw new Error(refusal({
+			fix: "run the command by hand and correct what its output names",
+			found: `specification.${this.specification}(): \`before\` exited ${outcome.status ?? "without a status"}.\nCommand: ${before}\nOutput:\n${outcome.stdout + outcome.stderr}`,
+			read: "docs/reference/services.md#process-the-one-shape-an-external-process-takes",
+			why: "A process's `before` must exit 0 before the process starts."
+		}));
+	}
+	async stop() {
+		const { child } = this;
+		if (!child) return;
+		this.child = null;
+		await endGroup(child);
+		await reapStrays(this.strays);
+		this.watchdog?.kill("SIGKILL");
+		this.watchdog = null;
+	}
+};
+async function endGroup(child) {
+	if (child.pid === void 0) return;
+	const leaderReaped = reaped(child);
+	signalGroup(child, "SIGTERM");
+	if (!await groupEnded(-child.pid, 2e3)) signalGroup(child, "SIGKILL");
+	await leaderReaped;
+}
+//#endregion
+export { signalGroup as a, SIGNALS_GROUPS as i, serve_exports as n, KILL_GRACE_MS as r, ServedProcess as t };
+
+//# sourceMappingURL=shared-serve.js.map

package/dist/shared-service-images.js

@@ -0,0 +1,10 @@
+//#region src/services/containers/service-images.ts
+/** Pinned by the digest of the multi-platform index: a tag moves under the suite. Bumped by hand. */
+const SERVICE_IMAGES = {
+	postgres: "postgres:17-alpine@sha256:b0f9560a2de083e2cc7382e75f808c7381a32852a7ec49117deedb300e552b24",
+	redis: "redis:7-alpine@sha256:858f009f9709ce576febc734aa78b8f6d624b82571f9ddb6bda4377c833b3499"
+};
+//#endregion
+export { SERVICE_IMAGES as t };
+
+//# sourceMappingURL=shared-service-images.js.map

package/dist/shared-services.global-setup.js

@@ -0,0 +1,179 @@
+import { n as refusal } from "./shared-refusal.js";
+import { a as field, i as RunContainers, o as serveContainers, r as TestcontainersAdapter, t as OWNER_LABEL } from "./shared-testcontainers.adapter.js";
+import { t as loadPeer } from "./shared-peer.js";
+import { t as SERVICE_IMAGES } from "./shared-service-images.js";
+import { t as setupEntry } from "./shared-setup-entry.js";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { hostname } from "node:os";
+//#region src/services/containers/orphans.ts
+const SESSION_LABEL = "org.testcontainers.session-id";
+const REAPER_LABEL = "org.testcontainers.ryuk";
+const ENDED = /* @__PURE__ */ new Set(["dead", "exited"]);
+/** Dead only when it names this host and no process answers its pid; another host's process is never taken for dead. */
+function ownerAlive(owner, host = hostname(), probe = (pid) => process.kill(pid, 0)) {
+	const separator = owner.lastIndexOf(":");
+	const pid = Number(owner.slice(separator + 1));
+	if (separator === -1 || owner.slice(0, separator) !== host || !Number.isSafeInteger(pid) || pid <= 0) return true;
+	try {
+		probe(pid);
+		return true;
+	} catch (error) {
+		return Reflect.get(new Object(error), "code") !== "ESRCH";
+	}
+}
+function orphans(containers, alive) {
+	const reaped = new Set(containers.filter((container) => container.State === "running" && container.Labels[REAPER_LABEL] === "true").map((reaper) => reaper.Labels[SESSION_LABEL]));
+	return containers.filter((container) => {
+		if (container.Labels[REAPER_LABEL] === "true") return false;
+		const owner = container.Labels[OWNER_LABEL];
+		if (owner !== void 0 && container.Labels["com.jterrazz.test.reuse"] !== "true" && !alive(owner)) return true;
+		const session = container.Labels[SESSION_LABEL];
+		return session !== void 0 && session !== "" && ENDED.has(container.State) && !reaped.has(session);
+	}).map((container) => container.Id);
+}
+/** A removal that fails is skipped: a sweep never fails the run. */
+async function sweepOrphans(runtime, alive = ownerAlive) {
+	const lists = await Promise.all([SESSION_LABEL, OWNER_LABEL].map(async (label) => await runtime.listContainers({
+		all: true,
+		filters: { label: [label] }
+	})));
+	const found = orphans([...new Map(lists.flat().map((container) => [container.Id, container])).values()], alive);
+	return (await Promise.allSettled(found.map(async (id) => {
+		await runtime.getContainer(id).remove({
+			force: true,
+			v: true
+		});
+		return id;
+	}))).flatMap((outcome) => outcome.status === "fulfilled" ? [outcome.value] : []);
+}
+//#endregion
+//#region src/services/containers/services.global-setup.ts
+/** Every project's setup joins the one run's containers. Default images are pulled in the background, so the first file waits on a pull at most once; a project declaring no service needs no Docker. */
+const DOCKER_ABSENT = "no Docker daemon answered";
+/** `connect` stands in for the runtime's own client lookup, so the refusal is reachable without a daemon to stop. */
+async function prepareDocker(connect) {
+	const { getContainerRuntimeClient, ImageName } = await loadPeer("testcontainers", "a declared service", async () => await import("testcontainers"));
+	let client;
+	try {
+		client = await (connect ?? getContainerRuntimeClient)();
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		throw new Error(refusal({
+			fix: "start Docker (Docker Desktop, OrbStack, colima or another) and run again",
+			found: `a declared service asked for Docker, and ${DOCKER_ABSENT} (${reason})`,
+			read: "docs/reference/services.md#one-container-per-run",
+			why: "A declared service runs in a container, so a project that declares one needs a Docker daemon."
+		}), { cause: error });
+	}
+	await Promise.all([sweepOrphans(client.container.dockerode).catch(() => []), ...Object.values(SERVICE_IMAGES).map(async (image) => {
+		const name = ImageName.fromString(image);
+		if (await client.image.exists(name)) return;
+		try {
+			await client.image.pull(name);
+		} catch {}
+	})]);
+}
+function servicesSetup() {
+	return setupEntry(import.meta.dirname, "services");
+}
+function packageVersion() {
+	let dir = import.meta.dirname;
+	while (!existsSync(join(dir, "package.json"))) {
+		const parent = dirname(dir);
+		if (parent === dir) return "unversioned";
+		dir = parent;
+	}
+	const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+	return String(field(manifest, "version"));
+}
+const RUN_SERVICES = Symbol.for(`@jterrazz/test.run-services@${packageVersion()}`);
+function settled(prepare) {
+	const prepared = (async () => {
+		try {
+			await prepare();
+			return null;
+		} catch (error) {
+			return error instanceof Error ? error : new Error(refusal({
+				fix: "restart the Docker runtime, or reinstall the `testcontainers` peer",
+				found: `preparing Docker threw ${String(error)}, which is no Error`,
+				read: "docs/start/set-up-a-project.md#what-to-install",
+				why: "A service starts only on a Docker runtime that answers, through the peer that drives it."
+			}));
+		}
+	})();
+	return async () => {
+		const refused = await prepared;
+		if (refused !== null) throw refused;
+	};
+}
+const DOCKER = {
+	create: (request) => new TestcontainersAdapter(request),
+	prepare: prepareDocker,
+	serve: serveContainers
+};
+async function open({ create, prepare, serve }) {
+	const containers = new RunContainers(create, settled(prepare));
+	const served = await serve(containers);
+	return {
+		close: async () => {
+			await served.close();
+			await containers.stop();
+		},
+		url: served.url
+	};
+}
+function runServices(seams) {
+	let holders = 0;
+	let opened = null;
+	const forget = () => {
+		opened = null;
+		Reflect.deleteProperty(globalThis, RUN_SERVICES);
+	};
+	return { enter: async () => {
+		opened ??= open(seams);
+		const current = opened;
+		let served;
+		try {
+			served = await current;
+		} catch (error) {
+			forget();
+			throw error;
+		}
+		holders += 1;
+		let left = false;
+		return {
+			leave: async () => {
+				if (left) return;
+				left = true;
+				holders -= 1;
+				if (holders > 0) return;
+				forget();
+				await served.close();
+			},
+			url: served.url
+		};
+	} };
+}
+function isRunServices(value) {
+	return typeof field(value, "enter") === "function";
+}
+function theRun(seams) {
+	const found = Reflect.get(globalThis, RUN_SERVICES);
+	if (isRunServices(found)) return found;
+	const created = runServices(seams);
+	Reflect.set(globalThis, RUN_SERVICES, created);
+	return created;
+}
+async function setup(project, seams = {}) {
+	const joined = await theRun({
+		...DOCKER,
+		...seams
+	}).enter();
+	project.provide("serviceContainers", joined.url);
+	return joined.leave;
+}
+//#endregion
+export { setup as i, prepareDocker as n, servicesSetup as r, DOCKER_ABSENT as t };
+
+//# sourceMappingURL=shared-services.global-setup.js.map