@orkestrel/test 0.0.7 → 0.0.9

package/dist/src/server/index.cjs

@@ -1,9 +1,12 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_buffer = require("node:buffer");
 let node_fs = require("node:fs");
+let node_http = require("node:http");
+let node_os = require("node:os");
 let node_path = require("node:path");
 let node_url = require("node:url");
+let _src_core = require("../core/index.cjs");
 let node_events = require("node:events");
-let node_os = require("node:os");
 //#region src/server/constants.ts
 /**
 * The attempts `removeTree` makes before rethrowing a retryable removal error.
@@ -60,6 +63,30 @@ function isExcluded(key, exclusions) {
 	return exclusions.some((rule) => rule === "" || key === rule || key.startsWith(`${rule}/`));
 }
 /**
+* Creates a symbolic link with a directory-junction fallback for hosts that refuse symbolic links.
+*
+* @param path - The path where the link is created.
+* @param source - The destination path the link points at.
+* @throws The original link error when its code is not `EPERM`, or when the source names an
+* existing non-directory; otherwise, any error from inspecting the source or creating the junction.
+* @remarks Only `EPERM` from the first symbolic-link attempt triggers the fallback. The fallback
+* resolves the source against the link's directory. An existing non-directory rethrows the original
+* `EPERM`, while a directory or missing source is passed to a junction attempt. A missing source is
+* accepted to create a dangling junction. Where the host creates a junction, its stored value is the
+* resolved absolute path.
+*/
+function createLink(path, source) {
+	try {
+		(0, node_fs.symlinkSync)(source, path);
+	} catch (error) {
+		if ((typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" ? error.code : void 0) !== "EPERM") throw error;
+		const resolved = (0, node_path.resolve)((0, node_path.dirname)(path), source);
+		const status = (0, node_fs.statSync)(resolved, { throwIfNoEntry: false });
+		if (status !== void 0 && !status.isDirectory()) throw error;
+		(0, node_fs.symlinkSync)(resolved, path, "junction");
+	}
+}
+/**
 * Removes a directory tree, retrying past a transient Windows handle-release race.
 *
 * @param path - The absolute directory to remove.
@@ -70,7 +97,8 @@ function isExcluded(key, exclusions) {
 * `rmSync` `maxRetries`/`retryDelay` options do not cover this error class on that host: probed
 * against a real held directory, they neither delay nor retry before rethrowing, so the retry
 * is implemented here with a synchronous sleep instead. Ten attempts 100ms apart bound the wait
-* at roughly one second.
+* at roughly one second. A hold that outlasts that second is {@link destroyScratch}'s case, which
+* retries every refusal inside a caller's budget rather than the codes named here.
 */
 function removeTree(path) {
 	for (let attempt = 1;; attempt++) try {
@@ -154,6 +182,372 @@ function readInventory(root, targets, options) {
 	}
 	return Object.fromEntries(Array.from(contents).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0));
 }
+/**
+* Reports whether a process id names a live process.
+*
+* @param pid - The process id to read.
+* @returns True if a process holds that id at the moment of the call; false otherwise, including a
+* pid the host refuses.
+* @throws Nothing. Every host refusal reads as false.
+* @remarks This is an instantaneous observation rather than a claim of ownership. A host reuses a
+* process id after the process holding it exits, so a true answer says some process holds that id now
+* and never says it is the process the caller started. Two host answers are worth knowing. A POSIX
+* host refuses signal `0` to a process another user owns with `EPERM`, and that refusal reads as
+* false here. A pid of `0` names the caller's own process group on POSIX and the system idle process
+* on Windows, so it reads as true on both without naming a process anyone started.
+*
+* A Linux zombie — a process that has exited and whose parent has not reaped it — still accepts
+* signal `0`, so its `/proc` status is read and a `Z` state reads as false.
+*/
+function isRunning(pid) {
+	try {
+		process.kill(pid, 0);
+	} catch {
+		return false;
+	}
+	if (process.platform !== "linux") return true;
+	try {
+		const status = (0, node_fs.readFileSync)(`/proc/${String(pid)}/stat`, "utf8");
+		const boundary = status.lastIndexOf(") ");
+		return boundary < 0 || status.slice(boundary + 2, boundary + 3) !== "Z";
+	} catch {
+		return false;
+	}
+}
+/**
+* Waits for a socket to close, accepting a peer reset as a forced close.
+*
+* @param socket - The socket to wait on. One that has already closed resolves without listening.
+* @param options - The time bounds and abort signal.
+* @returns A promise that resolves when the socket emits `close`.
+* @throws The socket's own error when its code is not `ECONNRESET`, the abort reason, or an `Error`
+* when a bound is invalid or the socket does not close within the budget.
+* @remarks Default budget: `1000` milliseconds. A reset is the peer forcing the connection down, and
+* the socket still emits `close` afterwards, so `ECONNRESET` is waited past rather than raised while
+* every other error ends the wait. The interval is validated for consistency with the wait family but
+* is not used, because this helper parks on the socket's events. Both listeners are removed on every
+* settlement, so a caller may wait on one socket repeatedly.
+*/
+async function waitForSocketClose(socket, options) {
+	const budget = options?.budget ?? 1e3;
+	const interval = options?.interval ?? 10;
+	if (!Number.isFinite(budget) || budget < 0) throw new Error("Socket budget must be finite and non-negative");
+	if (!Number.isFinite(interval) || interval < 0) throw new Error("Socket interval must be finite and non-negative");
+	const signal = options?.signal;
+	signal?.throwIfAborted();
+	if (socket.closed) return;
+	const closed = Promise.withResolvers();
+	const failed = Promise.withResolvers();
+	const expiry = Promise.withResolvers();
+	const aborted = Promise.withResolvers();
+	const subscription = new AbortController();
+	socket.on("close", closed.resolve);
+	socket.on("error", failed.resolve);
+	signal?.addEventListener("abort", () => aborted.reject(signal.reason), {
+		once: true,
+		signal: subscription.signal
+	});
+	const timer = setTimeout(() => {
+		expiry.reject(/* @__PURE__ */ new Error(`Socket did not close within ${budget}ms`));
+	}, budget);
+	try {
+		const error = await Promise.race([
+			closed.promise.then(() => void 0),
+			failed.promise,
+			expiry.promise,
+			aborted.promise
+		]);
+		if (error === void 0) return;
+		if (error.code !== "ECONNRESET") throw error;
+		await Promise.race([
+			closed.promise,
+			expiry.promise,
+			aborted.promise
+		]);
+	} finally {
+		clearTimeout(timer);
+		subscription.abort();
+		socket.off("close", closed.resolve);
+		socket.off("error", failed.resolve);
+	}
+}
+/**
+* Destroys a scratch directory, retrying until the host releases it.
+*
+* @param scratch - The scratch directory to destroy.
+* @param options - The time bounds and abort signal.
+* @returns A promise that resolves once `destroy()` returns without throwing.
+* @throws The abort reason, or an `Error` when a bound is invalid or the budget elapses. The
+* exhaustion error carries the last host refusal as its `cause`.
+* @remarks Default budget: `10000` milliseconds. Default interval: `25` milliseconds. A host holds a
+* directory for a short interval after the process that held it exits, and a just-stopped child's
+* working directory is the case this exists for, so removal is attempted until the host lets go
+* rather than exactly once. {@link ScratchInterface.destroy} stays synchronous and is unchanged; this
+* is the bounded retry around it. A directory nothing releases still fails, with the host's own
+* refusal as the `cause`.
+*
+* Every refusal is retried, deliberately, and that is wider than {@link removeTree}'s policy: that
+* one retries the codes {@link REMOVE_TREE_RETRYABLE_CODES} names and rethrows the rest at once.
+* The hold this waits out is not classifiable across hosts — Windows reports a working-directory
+* hold as `EPERM`, POSIX hosts and network filesystems report their own — so a code list here would
+* be a list of the hosts it had been run on. The residual is the cost of that: a fault no wait can
+* clear, such as a path removed from under the allocation or a permission the process never had,
+* spends the whole budget before it surfaces, and it surfaces wrapped in the exhaustion error with
+* the host's refusal as `cause` rather than by identity. Pass a shorter `budget` or a `signal`
+* wherever a caller must bound that cost.
+*/
+async function destroyScratch(scratch, options) {
+	const budget = options?.budget ?? 1e4;
+	const interval = options?.interval ?? 25;
+	if (!Number.isFinite(budget) || budget < 0) throw new Error("Scratch budget must be finite and non-negative");
+	if (!Number.isFinite(interval) || interval < 0) throw new Error("Scratch interval must be finite and non-negative");
+	const start = performance.now();
+	let refusal;
+	while (true) {
+		options?.signal?.throwIfAborted();
+		try {
+			scratch.destroy();
+			return;
+		} catch (error) {
+			refusal = error;
+		}
+		if (performance.now() - start >= budget) throw new Error(`Scratch directory was not destroyed within ${budget}ms`, { cause: refusal });
+		await (0, _src_core.waitForDelay)(interval);
+	}
+}
+/**
+* Drives a real client upgrade request against a loopback port and reports what the server did.
+*
+* @param port - The port the server listens on at `127.0.0.1`.
+* @param options - Optional request path, offered subprotocols, time bounds, and abort signal.
+* @returns A promise resolving to the server's answer: a claimed upgrade with the protocol it
+* selected, or a refusal with the status it answered.
+* @throws The client's own transport error, such as the `ECONNREFUSED` a closed port answers, the
+* abort reason, or an `Error` when a bound is invalid or the server does not answer within the
+* budget.
+* @remarks Default budget: `1000` milliseconds. The request carries `Connection: Upgrade` and
+* `Upgrade: websocket`, which is what makes a server's `upgrade` handler the one that answers it.
+* The `upgrade`, `response`, and `error` events are mutually exclusive in practice and the promise
+* settles on whichever arrives first, so a second event changes nothing. The client socket is
+* destroyed before every settlement, on the claimed path because an upgraded socket is detached from
+* the request and outlives it otherwise. The request is made with no agent, so no pooled connection
+* survives the call to keep a suite's event loop alive.
+*
+* A server that accepts the connection and answers nothing raises no transport error, so the budget
+* is what ends that call: the rejection names the port and path it was waiting on. The interval is
+* validated for consistency with the wait family but is not used, because this helper parks on the
+* request's events.
+*
+* A `101` is the claimed path's status on the wire and is deliberately not reported: `status` is the
+* refused arm's member, and a claimed upgrade produced no plain answer.
+* @example
+* ```ts
+* const answer = await requestUpgrade(loopback.port, { path: '/socket', protocols: ['chat'] })
+* // { claimed: true, protocol: 'chat' }
+* ```
+*/
+async function requestUpgrade(port, options) {
+	const budget = options?.budget ?? 1e3;
+	const interval = options?.interval ?? 10;
+	if (!Number.isFinite(budget) || budget < 0) throw new Error("Upgrade budget must be finite and non-negative");
+	if (!Number.isFinite(interval) || interval < 0) throw new Error("Upgrade interval must be finite and non-negative");
+	const signal = options?.signal;
+	signal?.throwIfAborted();
+	const path = options?.path ?? "/";
+	const target = `127.0.0.1:${port}${path}`;
+	const headers = {
+		connection: "Upgrade",
+		upgrade: "websocket"
+	};
+	const protocols = options?.protocols ?? [];
+	if (protocols.length > 0) headers["sec-websocket-protocol"] = protocols.join(", ");
+	const request = (0, node_http.request)({
+		agent: false,
+		headers,
+		host: "127.0.0.1",
+		path,
+		port
+	});
+	const settled = Promise.withResolvers();
+	const expiry = Promise.withResolvers();
+	const aborted = Promise.withResolvers();
+	const subscription = new AbortController();
+	request.on("upgrade", (response, socket) => {
+		const protocol = response.headers["sec-websocket-protocol"];
+		socket.destroy();
+		settled.resolve({
+			claimed: true,
+			protocol
+		});
+	});
+	request.on("response", (response) => {
+		const status = response.statusCode;
+		response.destroy();
+		request.destroy();
+		if (status === void 0) {
+			settled.reject(/* @__PURE__ */ new Error(`Upgrade request to ${target} was answered without a status`));
+			return;
+		}
+		settled.resolve({
+			claimed: false,
+			status
+		});
+	});
+	request.on("error", (error) => {
+		request.destroy();
+		settled.reject(error);
+	});
+	signal?.addEventListener("abort", () => aborted.reject(signal.reason), {
+		once: true,
+		signal: subscription.signal
+	});
+	const timer = setTimeout(() => {
+		expiry.reject(/* @__PURE__ */ new Error(`Upgrade request to ${target} was not answered within ${budget}ms`));
+	}, budget);
+	request.end();
+	try {
+		return await Promise.race([
+			settled.promise,
+			expiry.promise,
+			aborted.promise
+		]);
+	} finally {
+		clearTimeout(timer);
+		subscription.abort();
+		request.destroy();
+	}
+}
+/**
+* Checks whether this host links a directory, by creating one link and reading through it.
+*
+* @returns True if the created link reports as a symbolic link, resolves to a directory, and reaches
+* the destination's contents; false otherwise, including every host refusal.
+* @throws Nothing the attempt itself raises. Failing to allocate the probe directory, and failing to
+* remove it afterwards, both propagate.
+* @remarks `symlinkSync(source, target, 'junction')` creates a directory junction on Windows, which
+* needs no privilege, and Node ignores the type argument off Windows, so one call covers both hosts.
+* The answer is false on a filesystem carrying neither reparse points nor symbolic links. Every call
+* probes and cleans up after itself, so a host whose answer changes is read again rather than
+* remembered.
+*/
+function supportsDirectoryLinks() {
+	const directory = (0, node_fs.mkdtempSync)((0, node_path.join)((0, node_os.tmpdir)(), "orkestrel-test-directory-links-"));
+	try {
+		const source = (0, node_path.join)(directory, "source");
+		const link = (0, node_path.join)(directory, "link");
+		(0, node_fs.mkdirSync)(source);
+		(0, node_fs.writeFileSync)((0, node_path.join)(source, "marker.txt"), "marked");
+		(0, node_fs.symlinkSync)(source, link, "junction");
+		return (0, node_fs.lstatSync)(link).isSymbolicLink() && (0, node_fs.statSync)(link).isDirectory() && (0, node_fs.readFileSync)((0, node_path.join)(link, "marker.txt"), "utf8") === "marked";
+	} catch {
+		return false;
+	} finally {
+		removeTree(directory);
+	}
+}
+/**
+* Checks whether this host links a file, by creating one link and reading the file through it.
+*
+* @returns True if the file's contents are readable through the link; false otherwise, including
+* every host refusal.
+* @throws Nothing the attempt itself raises. Failing to allocate the probe directory, and failing to
+* remove it afterwards, both propagate.
+* @remarks `symlinkSync(source, target, 'file')` needs the symbolic-link privilege, which Windows
+* grants under Developer Mode or administrator rights and refuses with `EPERM` otherwise, so the
+* answer is true on POSIX and on a privileged Windows host. Where it is false, no mechanism reaches a
+* file through a link and a proof that reads one back cannot run. This is a separate question from
+* {@link supportsDirectoryLinks}, which an unprivileged Windows host answers true through a junction
+* while answering this one false.
+*/
+function supportsFileLinks() {
+	const directory = (0, node_fs.mkdtempSync)((0, node_path.join)((0, node_os.tmpdir)(), "orkestrel-test-file-links-"));
+	try {
+		const source = (0, node_path.join)(directory, "source.txt");
+		const link = (0, node_path.join)(directory, "link.txt");
+		(0, node_fs.writeFileSync)(source, "linked");
+		(0, node_fs.symlinkSync)(source, link, "file");
+		return (0, node_fs.readFileSync)(link, "utf8") === "linked";
+	} catch {
+		return false;
+	} finally {
+		removeTree(directory);
+	}
+}
+/**
+* Checks whether POSIX permission bits round-trip through this host's `chmod` and `stat`.
+*
+* @returns True if a directory created with mode `0o700` reports that mode back; false otherwise,
+* including every host refusal.
+* @throws Nothing the attempt itself raises. Failing to allocate the probe directory, and failing to
+* remove it afterwards, both propagate.
+* @remarks POSIX reports `mode & 0o777 === 0o700` and Windows reports `0o666` regardless, so the
+* answer is true on POSIX and false on Windows. Storing a bit is a narrower question than enforcing
+* it: a POSIX host running as uid `0` stores every bit faithfully and bypasses the access check the
+* bits describe, so a caller that needs a permission to be enforced probes the refusal it needs
+* rather than reading this.
+*/
+function supportsMode() {
+	const directory = (0, node_fs.mkdtempSync)((0, node_path.join)((0, node_os.tmpdir)(), "orkestrel-test-mode-"));
+	try {
+		const path = (0, node_path.join)(directory, "moded");
+		(0, node_fs.mkdirSync)(path, { mode: 448 });
+		return ((0, node_fs.statSync)(path).mode & 511) === 448;
+	} catch {
+		return false;
+	} finally {
+		removeTree(directory);
+	}
+}
+/**
+* Checks whether this host treats two names differing only by case as distinct files.
+*
+* @returns True if `A` and `a` hold the contents each was written with; false otherwise, including
+* every host refusal.
+* @throws Nothing the attempt itself raises. Failing to allocate the probe directory, and failing to
+* remove it afterwards, both propagate.
+* @remarks The names `A` and `a` differ by case and by nothing else, which is what makes the reading
+* an answer about case folding rather than an answer about two unrelated files. A case-folding volume
+* routes the second write onto the first entry, so reading the first back returns the second's
+* contents and the answer is false. The answer is true on a typical POSIX host and false on a
+* case-folding Windows or macOS volume.
+*/
+function supportsCase() {
+	const directory = (0, node_fs.mkdtempSync)((0, node_path.join)((0, node_os.tmpdir)(), "orkestrel-test-case-"));
+	try {
+		const upper = (0, node_path.join)(directory, "A");
+		const lower = (0, node_path.join)(directory, "a");
+		(0, node_fs.writeFileSync)(upper, "upper");
+		(0, node_fs.writeFileSync)(lower, "lower");
+		return (0, node_fs.readFileSync)(upper, "utf8") === "upper" && (0, node_fs.readFileSync)(lower, "utf8") === "lower";
+	} catch {
+		return false;
+	} finally {
+		removeTree(directory);
+	}
+}
+/**
+* Checks whether this host accepts a filename carrying a raw byte no UTF-8 decoder resolves.
+*
+* @returns True if a name ending in byte `0x80` is written and read back; false otherwise, including
+* every host refusal.
+* @throws Nothing the attempt itself raises. Failing to allocate the probe directory, and failing to
+* remove it afterwards, both propagate.
+* @remarks Byte `0x80` is an invalid UTF-8 lead byte. POSIX stores the name verbatim and Windows
+* rejects it with `ENOENT`, so the answer is true on POSIX and false on Windows. The path is passed
+* as a `Buffer` because the byte survives no string round trip.
+*/
+function supportsBytes() {
+	const directory = (0, node_fs.mkdtempSync)((0, node_path.join)((0, node_os.tmpdir)(), "orkestrel-test-bytes-"));
+	try {
+		const name = node_buffer.Buffer.concat([node_buffer.Buffer.from(`${directory}${node_path.sep}`), node_buffer.Buffer.from([128])]);
+		(0, node_fs.writeFileSync)(name, "raw");
+		return (0, node_fs.readFileSync)(name, "utf8") === "raw";
+	} catch {
+		return false;
+	} finally {
+		removeTree(directory);
+	}
+}
 //#endregion
 //#region src/server/factories.ts
 /**
@@ -244,7 +638,7 @@ function createScratch(options) {
 			if (candidate === void 0) throw new Error(`${outside}: ${target}`);
 			if (!scratch.has(".")) throw new Error("Scratch directory does not exist");
 			(0, node_fs.mkdirSync)((0, node_path.dirname)(candidate), { recursive: true });
-			(0, node_fs.symlinkSync)(source, candidate);
+			createLink(candidate, source);
 		},
 		remove(target) {
 			const candidate = resolveContained(path, target);
@@ -303,16 +697,60 @@ async function createLoopback(server) {
 		}
 	};
 }
+/**
+* Creates a cookie jar that records a real response's cookies and replays them as one header.
+*
+* @returns The rendered request header, and the members that read and capture cookies.
+* @remarks Selection is by name alone: no `Domain` or `Path` matching, no `Expires` or `Secure`
+* handling, and no persistence beyond the jar. That is what a test driving one origin over one path
+* needs, and a fixture needing a browser's cookie store needs a browser rather than this.
+*/
+function createCookieJar() {
+	const cookies = /* @__PURE__ */ new Map();
+	return {
+		get header() {
+			const pairs = [...cookies].map(([name, value]) => `${name}=${value}`);
+			return pairs.length === 0 ? void 0 : pairs.join("; ");
+		},
+		read(name) {
+			return cookies.get(name);
+		},
+		capture(response) {
+			const fields = response.headers.getSetCookie();
+			for (const field of fields) {
+				const boundary = field.indexOf(";");
+				const pair = boundary < 0 ? field : field.slice(0, boundary);
+				const separator = pair.indexOf("=");
+				if (separator < 1) continue;
+				const name = pair.slice(0, separator);
+				if (/;\s*max-age\s*=\s*0\s*(?:;|$)/iu.test(field)) cookies.delete(name);
+				else cookies.set(name, pair.slice(separator + 1));
+			}
+			return fields;
+		}
+	};
+}
 //#endregion
 exports.REMOVE_TREE_MAX_ATTEMPTS = REMOVE_TREE_MAX_ATTEMPTS;
 exports.REMOVE_TREE_RETRYABLE_CODES = REMOVE_TREE_RETRYABLE_CODES;
 exports.REMOVE_TREE_RETRY_DELAY_MS = REMOVE_TREE_RETRY_DELAY_MS;
+exports.createCookieJar = createCookieJar;
+exports.createLink = createLink;
 exports.createLoopback = createLoopback;
 exports.createScratch = createScratch;
+exports.destroyScratch = destroyScratch;
 exports.isExcluded = isExcluded;
+exports.isRunning = isRunning;
 exports.matchesIdentity = matchesIdentity;
 exports.readInventory = readInventory;
 exports.removeTree = removeTree;
+exports.requestUpgrade = requestUpgrade;
 exports.resolveContained = resolveContained;
+exports.supportsBytes = supportsBytes;
+exports.supportsCase = supportsCase;
+exports.supportsDirectoryLinks = supportsDirectoryLinks;
+exports.supportsFileLinks = supportsFileLinks;
+exports.supportsMode = supportsMode;
+exports.waitForSocketClose = waitForSocketClose;
 
 //# sourceMappingURL=index.cjs.map