@orkestrel/test 0.0.10 → 0.0.12

package/dist/src/server/index.d.ts

@@ -1,11 +1,13 @@
 import { Server } from 'node:net';
 import { Socket } from 'node:net';
+import { Stats } from 'node:fs';
 import { WaitOptions } from '@orkestrel/test';
 
-/** A name-keyed cookie store a test drives one origin with, filled from real responses. */
+/** Holds a name-keyed cookie store a test drives one origin with, filled from real responses. */
 export declare interface CookieJarInterface {
     /**
-     * The `Cookie` request header naming every stored cookie, or `undefined` while the jar holds none.
+     * Reports the `Cookie` request header naming every stored cookie, or `undefined` while the jar
+     * holds none.
      */
     readonly header: string | undefined;
     /**
@@ -100,13 +102,14 @@ export declare function createScratch(options?: ScratchOptions): ScratchInterfac
  */
 export declare function destroyScratch(scratch: ScratchInterface, options?: WaitOptions): Promise<void>;
 
-/** Options for reading a source inventory. */
+/** Configures a source inventory read. */
 export declare interface InventoryOptions {
-    /** The file extensions to include, each written with its leading dot. */
+    /** Lists the file extensions to include, each written with its leading dot. */
     readonly extensions?: readonly string[];
     /**
-     * The root-relative path keys to exclude. A key excludes itself and every key below it, matched
-     * on whole segments, so `excluded` drops `excluded/file.ts` and keeps `excluded-other/file.ts`.
+     * Lists the root-relative path keys to exclude. A key excludes itself and every key below it,
+     * matched on whole segments, so `excluded` drops `excluded/file.ts` and keeps
+     * `excluded-other/file.ts`.
      */
     readonly exclude?: readonly string[];
 }
@@ -116,7 +119,7 @@ export declare interface InventoryOptions {
  *
  * @param key - The root-relative key to test.
  * @param exclusions - The normalized root-relative exclusion keys.
- * @returns Whether an exclusion names the key or one of its ancestors.
+ * @returns True if an exclusion names the key or one of its ancestors; false otherwise.
  */
 export declare function isExcluded(key: string, exclusions: readonly string[]): boolean;
 
@@ -139,14 +142,14 @@ export declare function isExcluded(key: string, exclusions: readonly string[]):
  */
 export declare function isRunning(pid: number): boolean;
 
-/** A server a test owns, listening on an ephemeral loopback port until the test releases it. */
+/** Holds a server a test owns, listening on an ephemeral loopback port until the test releases it. */
 export declare interface LoopbackInterface {
     /**
-     * The `http` origin for the assigned port, without a trailing slash. A TLS server answers on the
-     * same port under `https`.
+     * Names the `http` origin for the assigned port, without a trailing slash. A TLS server answers
+     * on the same port under `https`.
      */
     readonly url: string;
-    /** The ephemeral port the host assigned. */
+    /** Holds the ephemeral port the host assigned. */
     readonly port: number;
     /**
      * Drops every live connection on a server that carries `closeAllConnections`, stops listening, and
@@ -162,13 +165,33 @@ export declare interface LoopbackInterface {
  *
  * @param current - The identity read from the path now.
  * @param allocation - The identity recorded when the directory was allocated.
- * @returns Whether the device, the index node, and the creation time all match.
+ * @returns True if the device, the index node, and the creation time all match; false otherwise.
  * @remarks All three fields are compared because none of them alone identifies an allocation. A
  * device is shared by every directory on one filesystem, an index node is reused once its directory
  * is removed, and a creation time repeats within the host's timestamp resolution.
  */
 export declare function matchesIdentity(current: ScratchIdentity, allocation: ScratchIdentity): boolean;
 
+/**
+ * Reads the `code` an unknown thrown value carries.
+ *
+ * @param error - The thrown value to read.
+ * @returns The string `code` the value carries, or `undefined` when it carries none.
+ * @remarks The read is contained on its own terms: a value that is not an object, one carrying no
+ * `code`, and one carrying a `code` that is not a string all answer `undefined`. A null-prototype
+ * object is read the same way, because the key is tested with `in` rather than through
+ * `hasOwnProperty`.
+ */
+export declare function readErrorCode(error: unknown): string | undefined;
+
+/**
+ * Reads the identity of one allocated directory off a host status.
+ *
+ * @param status - The status read from the directory's path.
+ * @returns The device, index node, and creation time that together name the allocation.
+ */
+export declare function readIdentity(status: Stats): ScratchIdentity;
+
 /**
  * Reads files from selected targets below a root directory.
  *
@@ -185,17 +208,17 @@ export declare function matchesIdentity(current: ScratchIdentity, allocation: Sc
 export declare function readInventory(root: URL | string, targets: readonly string[], options?: InventoryOptions): Readonly<Record<string, string>>;
 
 /**
- * The attempts `removeTree` makes before rethrowing a retryable removal error.
+ * Caps the attempts `removeTree` makes before rethrowing a retryable removal error.
  */
 export declare const REMOVE_TREE_MAX_ATTEMPTS = 10;
 
 /**
- * The synchronous delay, in milliseconds, `removeTree` waits between attempts.
+ * Names the synchronous delay, in milliseconds, `removeTree` waits between attempts.
  */
 export declare const REMOVE_TREE_RETRY_DELAY_MS = 100;
 
 /**
- * The error codes `removeTree` retries; every other code rethrows immediately.
+ * Names the error codes `removeTree` retries; every other code rethrows immediately.
  */
 export declare const REMOVE_TREE_RETRYABLE_CODES: readonly string[];
 
@@ -248,6 +271,20 @@ export declare function removeTree(path: string): void;
  */
 export declare function requestUpgrade(port: number, options?: UpgradeOptions): Promise<UpgradeResult>;
 
+/**
+ * Resolves a target that stays below a root directory, refusing an escape.
+ *
+ * @param root - The absolute root directory.
+ * @param target - The relative or absolute target to resolve.
+ * @returns The absolute target below the root.
+ * @throws An `Error` reading `Path outside scratch directory: <target>` when the target escapes the
+ * root.
+ * @remarks This is {@link resolveContained} with the refusal every contained scratch operation makes
+ * of an escape, so the check and its one message are stated once. Read `resolveContained` where an
+ * escape is an answer rather than a refusal.
+ */
+export declare function requireContained(root: string, target: string): string;
+
 /**
  * Resolves a target that stays below a root directory.
  *
@@ -257,19 +294,19 @@ export declare function requestUpgrade(port: number, options?: UpgradeOptions):
  */
 export declare function resolveContained(root: string, target: string): string | undefined;
 
-/** The fields that together identify one allocated directory on its host. */
+/** Represents the fields that together identify one allocated directory on its host. */
 export declare interface ScratchIdentity {
-    /** The identifier of the device holding the directory. */
+    /** Holds the identifier of the device holding the directory. */
     readonly device: number;
-    /** The number of the directory's index node on that device. */
+    /** Holds the number of the directory's index node on that device. */
     readonly inode: number;
-    /** The directory's creation time in milliseconds. */
+    /** Holds the directory's creation time in milliseconds. */
     readonly birth: number;
 }
 
-/** A temporary directory a test owns, writes into, reads back, and removes when it is done. */
+/** Holds a temporary directory a test owns, writes into, reads back, and removes when it is done. */
 export declare interface ScratchInterface {
-    /** The absolute path of the allocated directory. */
+    /** Holds the absolute path of the allocated directory. */
     readonly path: string;
     /**
      * Writes a file, creating each parent directory that does not exist.
@@ -296,7 +333,8 @@ export declare interface ScratchInterface {
      * Reports whether a path exists without following its final symbolic link.
      *
      * @param target - A relative or absolute path contained by the scratch directory.
-     * @returns True when the entry exists, including a symbolic link whose target is missing.
+     * @returns True if the entry exists, including a symbolic link whose target is
+     * missing; false otherwise.
      * @throws When the path escapes the scratch directory or its root is a symbolic link or file.
      */
     has(target: string): boolean;
@@ -353,23 +391,23 @@ export declare interface ScratchInterface {
     destroy(): void;
 }
 
-/** Options for allocating a scratch directory. */
+/** Configures a scratch directory allocation. */
 export declare interface ScratchOptions {
     /**
-     * The existing directory in which to create the allocation. Defaults to the host temporary
+     * Names the existing directory in which to create the allocation. Defaults to the host temporary
      * directory. Allocation throws when this path is missing, a symbolic link, or not a directory.
      */
     readonly parent?: string;
     /**
-     * The name fragment that starts the generated directory name. Allocation throws when this value
-     * contains `/` or `\`. Both are refused on every host, so the rule does not vary by host. A
+     * Holds the name fragment that starts the generated directory name. Allocation throws when this
+     * value contains `/` or `\`. Both are refused on every host, so the rule does not vary by host. A
      * fragment carrying no separator is one path segment and cannot steer the allocation, so
      * `release-0..2-` allocates.
      */
     readonly prefix?: string;
     /**
-     * Files to write on allocation, keyed by path below the scratch directory. Allocation removes its
-     * directory and rethrows when a key escapes or the host refuses a write.
+     * Holds the files to write on allocation, keyed by path below the scratch directory. Allocation
+     * removes its directory and rethrows when a key escapes or the host refuses a write.
      */
     readonly files?: Readonly<Record<string, string>>;
 }
@@ -449,23 +487,23 @@ export declare function supportsFileLinks(): boolean;
 export declare function supportsMode(): boolean;
 
 /**
- * Options for driving a client upgrade request.
+ * Configures a client upgrade request.
  *
  * @remarks The time bounds and abort signal bound the wait for the server's answer, so a server
  * that accepts the connection and never answers ends the call rather than parking it.
  */
 export declare interface UpgradeOptions extends WaitOptions {
-    /** The request path, written with its leading slash. Defaults to `/`. */
+    /** Names the request path, written with its leading slash. Defaults to `/`. */
     readonly path?: string;
     /**
-     * The subprotocol tokens the request offers. They are sent as one comma-separated
+     * Lists the subprotocol tokens the request offers. They are sent as one comma-separated
      * `Sec-WebSocket-Protocol` field, and an empty or omitted list sends no field at all.
      */
     readonly protocols?: readonly string[];
 }
 
 /**
- * What one server did with a client upgrade request.
+ * Represents what one server did with a client upgrade request.
  *
  * @remarks `claimed` is the discriminant. The claimed arm carries `protocol`, the subprotocol the
  * server selected, which is `undefined` when it selected none; a claimed upgrade produced no plain

package/dist/src/server/index.js

@@ -4,19 +4,19 @@ import { request } from "node:http";
 import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { waitForDelay } from "../core/index.js";
+import { checkBounds, waitForDelay } from "../core/index.js";
 import { once } from "node:events";
 //#region src/server/constants.ts
 /**
-* The attempts `removeTree` makes before rethrowing a retryable removal error.
+* Caps the attempts `removeTree` makes before rethrowing a retryable removal error.
 */
 var REMOVE_TREE_MAX_ATTEMPTS = 10;
 /**
-* The synchronous delay, in milliseconds, `removeTree` waits between attempts.
+* Names the synchronous delay, in milliseconds, `removeTree` waits between attempts.
 */
 var REMOVE_TREE_RETRY_DELAY_MS = 100;
 /**
-* The error codes `removeTree` retries; every other code rethrows immediately.
+* Names the error codes `removeTree` retries; every other code rethrows immediately.
 */
 var REMOVE_TREE_RETRYABLE_CODES = Object.freeze([
 	"EBUSY",
@@ -39,11 +39,54 @@ function resolveContained(root, target) {
 	return candidate;
 }
 /**
+* Resolves a target that stays below a root directory, refusing an escape.
+*
+* @param root - The absolute root directory.
+* @param target - The relative or absolute target to resolve.
+* @returns The absolute target below the root.
+* @throws An `Error` reading `Path outside scratch directory: <target>` when the target escapes the
+* root.
+* @remarks This is {@link resolveContained} with the refusal every contained scratch operation makes
+* of an escape, so the check and its one message are stated once. Read `resolveContained` where an
+* escape is an answer rather than a refusal.
+*/
+function requireContained(root, target) {
+	const candidate = resolveContained(root, target);
+	if (candidate === void 0) throw new Error(`Path outside scratch directory: ${target}`);
+	return candidate;
+}
+/**
+* Reads the identity of one allocated directory off a host status.
+*
+* @param status - The status read from the directory's path.
+* @returns The device, index node, and creation time that together name the allocation.
+*/
+function readIdentity(status) {
+	return {
+		birth: status.birthtimeMs,
+		device: status.dev,
+		inode: status.ino
+	};
+}
+/**
+* Reads the `code` an unknown thrown value carries.
+*
+* @param error - The thrown value to read.
+* @returns The string `code` the value carries, or `undefined` when it carries none.
+* @remarks The read is contained on its own terms: a value that is not an object, one carrying no
+* `code`, and one carrying a `code` that is not a string all answer `undefined`. A null-prototype
+* object is read the same way, because the key is tested with `in` rather than through
+* `hasOwnProperty`.
+*/
+function readErrorCode(error) {
+	return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" ? error.code : void 0;
+}
+/**
 * Reports whether two directory identities name the same allocation.
 *
 * @param current - The identity read from the path now.
 * @param allocation - The identity recorded when the directory was allocated.
-* @returns Whether the device, the index node, and the creation time all match.
+* @returns True if the device, the index node, and the creation time all match; false otherwise.
 * @remarks All three fields are compared because none of them alone identifies an allocation. A
 * device is shared by every directory on one filesystem, an index node is reused once its directory
 * is removed, and a creation time repeats within the host's timestamp resolution.
@@ -56,7 +99,7 @@ function matchesIdentity(current, allocation) {
 *
 * @param key - The root-relative key to test.
 * @param exclusions - The normalized root-relative exclusion keys.
-* @returns Whether an exclusion names the key or one of its ancestors.
+* @returns True if an exclusion names the key or one of its ancestors; false otherwise.
 */
 function isExcluded(key, exclusions) {
 	return exclusions.some((rule) => rule === "" || key === rule || key.startsWith(`${rule}/`));
@@ -78,7 +121,7 @@ function createLink(path, source) {
 	try {
 		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;
+		if (readErrorCode(error) !== "EPERM") throw error;
 		const resolved = resolve(dirname(path), source);
 		const status = statSync(resolved, { throwIfNoEntry: false });
 		if (status !== void 0 && !status.isDirectory()) throw error;
@@ -107,7 +150,7 @@ function removeTree(path) {
 		});
 		return;
 	} catch (error) {
-		const code = typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" ? error.code : void 0;
+		const code = readErrorCode(error);
 		if (code === void 0 || !REMOVE_TREE_RETRYABLE_CODES.includes(code) || attempt >= 10) throw error;
 		Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
 	}
@@ -230,8 +273,7 @@ function isRunning(pid) {
 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");
+	checkBounds("Socket", budget, interval);
 	const signal = options?.signal;
 	signal?.throwIfAborted();
 	if (socket.closed) return;
@@ -298,8 +340,7 @@ async function waitForSocketClose(socket, options) {
 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");
+	checkBounds("Scratch", budget, interval);
 	const start = performance.now();
 	let refusal;
 	while (true) {
@@ -348,8 +389,7 @@ async function destroyScratch(scratch, options) {
 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");
+	checkBounds("Upgrade", budget, interval);
 	const signal = options?.signal;
 	signal?.throwIfAborted();
 	const path = options?.path ?? "/";
@@ -568,18 +608,11 @@ function createScratch(options) {
 	const prefix = options?.prefix ?? "orkestrel-test-";
 	if (prefix.includes("/") || prefix.includes("\\")) throw new Error("Scratch prefix must be a name fragment");
 	const path = mkdtempSync(`${parent}${sep}${prefix}`);
-	const allocated = statSync(path);
-	const allocation = {
-		birth: allocated.birthtimeMs,
-		device: allocated.dev,
-		inode: allocated.ino
-	};
-	const outside = "Path outside scratch directory";
+	const allocation = readIdentity(statSync(path));
 	const unremovable = "Scratch directory is not a removable target";
 	try {
 		for (const [target, text] of Object.entries(options?.files ?? {})) {
-			const candidate = resolveContained(path, target);
-			if (candidate === void 0) throw new Error(`${outside}: ${target}`);
+			const candidate = requireContained(path, target);
 			mkdirSync(dirname(candidate), { recursive: true });
 			writeFileSync(candidate, text);
 		}
@@ -590,16 +623,14 @@ function createScratch(options) {
 	const scratch = {
 		path,
 		write(target, text) {
-			const candidate = resolveContained(path, target);
-			if (candidate === void 0) throw new Error(`${outside}: ${target}`);
+			const candidate = requireContained(path, target);
 			if (!scratch.has(".")) throw new Error("Scratch directory does not exist");
 			mkdirSync(dirname(candidate), { recursive: true });
 			writeFileSync(candidate, text);
 			return candidate;
 		},
 		read(target) {
-			const candidate = resolveContained(path, target);
-			if (candidate === void 0) throw new Error(`${outside}: ${target}`);
+			const candidate = requireContained(path, target);
 			if (!scratch.has(target)) return void 0;
 			const status = statSync(candidate, { throwIfNoEntry: false });
 			if (status === void 0) return void 0;
@@ -607,8 +638,7 @@ function createScratch(options) {
 			return readFileSync(candidate, "utf8");
 		},
 		has(target) {
-			const candidate = resolveContained(path, target);
-			if (candidate === void 0) throw new Error(`${outside}: ${target}`);
+			const candidate = requireContained(path, target);
 			const rootStatus = lstatSync(path, { throwIfNoEntry: false });
 			if (rootStatus === void 0) return false;
 			if (rootStatus.isSymbolicLink()) throw new Error("Scratch directory is a symbolic link");
@@ -616,8 +646,7 @@ function createScratch(options) {
 			return lstatSync(candidate, { throwIfNoEntry: false }) !== void 0;
 		},
 		names(target = ".") {
-			const candidate = resolveContained(path, target);
-			if (candidate === void 0) throw new Error(`${outside}: ${target}`);
+			const candidate = requireContained(path, target);
 			if (!scratch.has(".")) throw new Error("Scratch directory does not exist");
 			const status = statSync(candidate, { throwIfNoEntry: false });
 			if (status === void 0) throw new Error(`Scratch path does not exist: ${target}`);
@@ -625,8 +654,7 @@ function createScratch(options) {
 			return readdirSync(candidate).sort();
 		},
 		ensure(target) {
-			const candidate = resolveContained(path, target);
-			if (candidate === void 0) throw new Error(`${outside}: ${target}`);
+			const candidate = requireContained(path, target);
 			if (!scratch.has(".")) throw new Error("Scratch directory does not exist");
 			const status = statSync(candidate, { throwIfNoEntry: false });
 			if (status !== void 0 && !status.isDirectory()) throw new Error(`Scratch path is not a directory: ${target}`);
@@ -634,36 +662,24 @@ function createScratch(options) {
 			return candidate;
 		},
 		link(target, source) {
-			const candidate = resolveContained(path, target);
-			if (candidate === void 0) throw new Error(`${outside}: ${target}`);
+			const candidate = requireContained(path, target);
 			if (!scratch.has(".")) throw new Error("Scratch directory does not exist");
 			mkdirSync(dirname(candidate), { recursive: true });
 			createLink(candidate, source);
 			return candidate;
 		},
 		remove(target) {
-			const candidate = resolveContained(path, target);
-			if (candidate === void 0) throw new Error(`${outside}: ${target}`);
+			const candidate = requireContained(path, target);
 			if (candidate === path) throw new Error(`${unremovable}: ${target}`);
 			if (!scratch.has(".")) throw new Error("Scratch directory does not exist");
 			const status = lstatSync(candidate, { throwIfNoEntry: false });
-			if (status !== void 0) {
-				if (matchesIdentity({
-					birth: status.birthtimeMs,
-					device: status.dev,
-					inode: status.ino
-				}, allocation)) throw new Error(`${unremovable}: ${target}`);
-			}
+			if (status !== void 0 && matchesIdentity(readIdentity(status), allocation)) throw new Error(`${unremovable}: ${target}`);
 			removeTree(candidate);
 		},
 		destroy() {
 			const status = lstatSync(path, { throwIfNoEntry: false });
 			if (status === void 0) return;
-			if (!matchesIdentity({
-				birth: status.birthtimeMs,
-				device: status.dev,
-				inode: status.ino
-			}, allocation)) return;
+			if (!matchesIdentity(readIdentity(status), allocation)) return;
 			removeTree(path);
 		}
 	};
@@ -732,6 +748,6 @@ function createCookieJar() {
 	};
 }
 //#endregion
-export { REMOVE_TREE_MAX_ATTEMPTS, REMOVE_TREE_RETRYABLE_CODES, REMOVE_TREE_RETRY_DELAY_MS, createCookieJar, createLink, createLoopback, createScratch, destroyScratch, isExcluded, isRunning, matchesIdentity, readInventory, removeTree, requestUpgrade, resolveContained, supportsBytes, supportsCase, supportsDirectoryLinks, supportsFileLinks, supportsMode, waitForSocketClose };
+export { REMOVE_TREE_MAX_ATTEMPTS, REMOVE_TREE_RETRYABLE_CODES, REMOVE_TREE_RETRY_DELAY_MS, createCookieJar, createLink, createLoopback, createScratch, destroyScratch, isExcluded, isRunning, matchesIdentity, readErrorCode, readIdentity, readInventory, removeTree, requestUpgrade, requireContained, resolveContained, supportsBytes, supportsCase, supportsDirectoryLinks, supportsFileLinks, supportsMode, waitForSocketClose };
 
 //# sourceMappingURL=index.js.map