@orkestrel/test 0.0.7 → 0.0.9

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

@@ -1,4 +1,56 @@
 import { Server } from 'node:net';
+import { Socket } from 'node:net';
+import { WaitOptions } from '@orkestrel/test';
+
+/** 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.
+     */
+    readonly header: string | undefined;
+    /**
+     * Reads one stored cookie value.
+     *
+     * @param name - The cookie name.
+     * @returns The stored value, or `undefined` when the jar holds no cookie of that name.
+     */
+    read(name: string): string | undefined;
+    /**
+     * Applies every `Set-Cookie` field a response carries.
+     *
+     * @param response - The response whose `Set-Cookie` fields are applied.
+     * @returns Those fields unmodified, in the order the response carried them.
+     * @remarks Selection is by name alone. A field spelling `Max-Age=0` deletes its cookie and every
+     * other field stores or replaces one, so `Domain`, `Path`, `Expires`, and `Secure` are read past
+     * rather than honoured. Nothing outlives the jar.
+     */
+    capture(response: Response): readonly string[];
+}
+
+/**
+ * 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.
+ */
+export declare function createCookieJar(): CookieJarInterface;
+
+/**
+ * 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.
+ */
+export declare function createLink(path: string, source: string): void;
 
 /**
  * Starts a server on an ephemeral IPv4 loopback port.
@@ -21,6 +73,33 @@ export declare function createLoopback(server: Server): Promise<LoopbackInterfac
  */
 export declare function createScratch(options?: ScratchOptions): ScratchInterface;
 
+/**
+ * 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.
+ */
+export declare function destroyScratch(scratch: ScratchInterface, options?: WaitOptions): Promise<void>;
+
 /** Options for reading a source inventory. */
 export declare interface InventoryOptions {
     /** The file extensions to include, each written with its leading dot. */
@@ -41,6 +120,25 @@ export declare interface InventoryOptions {
  */
 export declare function isExcluded(key: string, exclusions: readonly string[]): boolean;
 
+/**
+ * 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.
+ */
+export declare function isRunning(pid: number): boolean;
+
 /** A server a test owns, listening on an ephemeral loopback port until the test releases it. */
 export declare interface LoopbackInterface {
     /**
@@ -112,10 +210,44 @@ export declare const REMOVE_TREE_RETRYABLE_CODES: readonly string[];
  * `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.
  */
 export declare function removeTree(path: string): void;
 
+/**
+ * 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' }
+ * ```
+ */
+export declare function requestUpgrade(port: number, options?: UpgradeOptions): Promise<UpgradeResult>;
+
 /**
  * Resolves a target that stays below a root directory.
  *
@@ -192,10 +324,13 @@ export declare interface ScratchInterface {
      * @param target - The relative or absolute contained path where the link is created. Unlike
      * `node:fs`'s `symlinkSync(target, path)` vocabulary, this interface consistently calls the
      * contained path the target.
-     * @param source - The link text naming the pointed-at path. It may name a path outside the scratch
-     * directory and is not containment-checked.
+     * @param source - The destination path the link points at. The stored value is a path naming that
+     * destination, but its exact text is not promised. The path may name a destination outside the
+     * scratch directory and is not containment-checked.
      * @throws When the target escapes the scratch directory, the scratch root is missing, a symbolic
-     * link, or a file, or the host refuses to create the link.
+     * link, or a file, or the host refuses to create the link, including a host that creates no
+     * symbolic link when the source names an existing non-directory.
+     * @remarks {@link createLink} owns the host-specific link mechanism.
      */
     link(target: string, source: string): void;
     /**
@@ -237,4 +372,126 @@ export declare interface ScratchOptions {
     readonly files?: Readonly<Record<string, string>>;
 }
 
+/**
+ * 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.
+ */
+export declare function supportsBytes(): boolean;
+
+/**
+ * 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.
+ */
+export declare function supportsCase(): boolean;
+
+/**
+ * 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.
+ */
+export declare function supportsDirectoryLinks(): boolean;
+
+/**
+ * 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.
+ */
+export declare function supportsFileLinks(): boolean;
+
+/**
+ * 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.
+ */
+export declare function supportsMode(): boolean;
+
+/**
+ * Options for driving 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 `/`. */
+    readonly path?: string;
+    /**
+     * 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.
+ *
+ * @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
+ * answer, so it carries no status and the `101` on the wire is deliberately not reported as one.
+ * The refused arm carries `status`, the plain answer's status, and no subprotocol.
+ */
+export declare type UpgradeResult = {
+    readonly claimed: true;
+    readonly protocol: string | undefined;
+} | {
+    readonly claimed: false;
+    readonly status: number;
+};
+
+/**
+ * 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.
+ */
+export declare function waitForSocketClose(socket: Socket, options?: WaitOptions): Promise<void>;
+
 export { }