spawnfile 0.1.14 → 0.1.18

package/dist/deployment/organizationHandoffAuthorityFsClient.js

@@ -1,11 +1,33 @@
 import { fork } from "node:child_process";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
+import { createOrganizationHandoffAuthorityError, parseOrganizationHandoffAuthorityFailureDetail, PUBLICATION_BUDGET_MS } from "./organizationHandoffAuthorityFsBudget.js";
 const VERSION = "spawnfile.organization-handoff-fs-worker.v1";
 const MAX_BYTES = 32_768;
-const fail = () => { throw new Error("Organization handoff authority failed"); };
+/**
+ * The client deadline must exceed the worker's own convergence budget, or the
+ * client times out first and replaces a diagnosable worker failure with an
+ * opaque one. The margin covers fork/IPC latency and event-loop lag.
+ */
+const REQUEST_DEADLINE_MS = PUBLICATION_BUDGET_MS + 3_000;
+/**
+ * Startup deadline for the worker's ready handshake. This bounds a hung or
+ * broken helper; it is not a latency budget for process startup.
+ *
+ * Measured ready latency for eight concurrently forked source-mode helpers on
+ * a host at eleven times CPU oversubscription is 67-411ms, so this is margin
+ * rather than a fix — the observed startup failures were the helper's own
+ * liveness watchdog killing it, not this deadline expiring. It is sized above
+ * that measurement because CI forks far more helpers at once, and a caller
+ * initializes several clients in sequence, which bounds the worst case.
+ */
+const READY_DEADLINE_MS = 5_000;
+const DISPOSE_GRACE_MS = 1_000;
+const fail = (code, state) => {
+    throw createOrganizationHandoffAuthorityError({ code, ...(state === undefined ? {} : { state }) });
+};
 const bytes = (value) => Buffer.byteLength(value, "utf8");
-const name = (value) => typeof value === "string" && /^(?:[a-f0-9]{128}|[a-f0-9]{142})\.json$/u.test(value) ? value : fail();
+const name = (value) => typeof value === "string" && /^(?:[a-f0-9]{128}|[a-f0-9]{142})\.json$/u.test(value) ? value : fail("invalid_name");
 class Client {
     #child;
     #closed = false;
@@ -16,10 +38,10 @@ class Client {
         this.#child = child;
         let settleExit;
         this.#exited = new Promise((resolve) => { settleExit = resolve; });
-        const settle = () => { this.rejectPending(); settleExit(); };
+        const settle = () => { this.rejectPending("worker_exited"); settleExit(); };
         child.on("message", (raw) => this.message(raw));
-        child.on("error", () => this.rejectPending());
-        child.on("disconnect", () => this.rejectPending());
+        child.on("error", () => this.rejectPending("worker_errored"));
+        child.on("disconnect", () => this.rejectPending("worker_disconnected"));
         child.once("exit", settle);
         if (child.exitCode !== null || child.signalCode !== null)
             settle();
@@ -29,8 +51,11 @@ class Client {
         child.stderr?.resume();
     }
     terminal() { return this.#child.exitCode !== null || this.#child.signalCode !== null; }
-    rejectPending() { for (const pending of this.#pending.values())
-        pending.reject(); this.#pending.clear(); }
+    rejectPending(code) {
+        for (const pending of this.#pending.values())
+            pending.reject({ code });
+        this.#pending.clear();
+    }
     message(raw) {
         if (!raw || typeof raw !== "object")
             return;
@@ -46,23 +71,44 @@ class Client {
             return;
         this.#pending.delete(value.id);
         if (value.ok !== true || value.content !== undefined && typeof value.content !== "string"
-            || value.created !== undefined && typeof value.created !== "boolean")
-            pending.reject();
-        else
-            pending.resolve(value);
+            || value.created !== undefined && typeof value.created !== "boolean") {
+            // The worker reports which budget or invariant failed. Preserve it: a
+            // bare failure here is what made this path undiagnosable from CI logs.
+            pending.reject(parseOrganizationHandoffAuthorityFailureDetail(value.failure) ?? { code: "worker_rejected" });
+            return;
+        }
+        pending.resolve(value);
     }
     request(op, file, content) {
-        if (this.#closed || content !== undefined && bytes(content) > MAX_BYTES)
-            return Promise.reject(new Error("Organization handoff authority failed"));
+        if (this.#closed)
+            return Promise.reject(createOrganizationHandoffAuthorityError({ code: "client_closed" }));
+        if (content !== undefined && bytes(content) > MAX_BYTES)
+            return Promise.reject(createOrganizationHandoffAuthorityError({ code: "content_too_large", state: `bytes=${bytes(content)} limit=${MAX_BYTES}` }));
         const id = this.#next++;
         const packet = { version: VERSION, id, op, name: name(file), ...(content === undefined ? {} : { content }) };
-        if (bytes(JSON.stringify(packet)) > MAX_BYTES)
-            return Promise.reject(new Error("Organization handoff authority failed"));
-        return new Promise((resolve, reject) => { const timer = setTimeout(() => { this.#pending.delete(id); reject(new Error("Organization handoff authority failed")); }, 3_000); this.#pending.set(id, { resolve: (value) => { clearTimeout(timer); resolve(value); }, reject: () => { clearTimeout(timer); reject(new Error("Organization handoff authority failed")); } }); if (!this.#child.send(packet)) {
-            clearTimeout(timer);
-            this.#pending.delete(id);
-            reject(new Error("Organization handoff authority failed"));
-        } });
+        const size = bytes(JSON.stringify(packet));
+        if (size > MAX_BYTES)
+            return Promise.reject(createOrganizationHandoffAuthorityError({ code: "packet_too_large", state: `bytes=${size} limit=${MAX_BYTES}` }));
+        return new Promise((resolve, reject) => {
+            const startedAt = performance.now();
+            const settle = (detail) => {
+                clearTimeout(timer);
+                reject(createOrganizationHandoffAuthorityError(detail ?? { code: "request_failed" }));
+            };
+            const timer = setTimeout(() => {
+                this.#pending.delete(id);
+                settle({ budget: "client_request", code: "client_request_deadline", elapsedMs: performance.now() - startedAt, limitMs: REQUEST_DEADLINE_MS, state: `op=${op}` });
+            }, REQUEST_DEADLINE_MS);
+            this.#pending.set(id, {
+                reject: (detail) => settle(detail === undefined ? detail : { ...detail, state: `${detail.state === undefined ? "" : `${detail.state} `}op=${op}` }),
+                resolve: (value) => { clearTimeout(timer); resolve(value); }
+            });
+            if (!this.#child.send(packet)) {
+                clearTimeout(timer);
+                this.#pending.delete(id);
+                reject(createOrganizationHandoffAuthorityError({ code: "worker_send_failed", state: `op=${op}` }));
+            }
+        });
     }
     async create(file, content) {
         const result = await this.request("create", file, content);
@@ -74,7 +120,7 @@ class Client {
         if (this.#closed)
             return;
         this.#closed = true;
-        this.rejectPending();
+        this.rejectPending("client_disposed");
         if (!this.terminal()) {
             if (this.#child.connected) {
                 try {
@@ -86,7 +132,7 @@ class Client {
         }
         let clear;
         const graceful = await Promise.race([this.#exited.then(() => true), new Promise((resolve) => {
-                const timer = setTimeout(() => resolve(false), 1_000);
+                const timer = setTimeout(() => resolve(false), DISPOSE_GRACE_MS);
                 clear = () => clearTimeout(timer);
             })]);
         clear?.();
@@ -108,17 +154,26 @@ export const initializeOrganizationHandoffAuthorityFsClient = async (options) =>
     const child = fork(workerPath, [], { cwd: options.cwd, env: { SPAWNFILE_AUTHORITY_FS_ANCHOR: JSON.stringify({ dev: options.dev, ino: options.ino, uid: options.uid, parent_pid: options.parentPid ?? process.pid }) }, silent: true, ...(tsxLoader === undefined ? {} : { execArgv: ["--import", tsxLoader] }) });
     const client = new Client(child);
     options.testOnChildStarted?.(child);
+    const startedAt = performance.now();
+    let detail = { code: "worker_ready_failed" };
     try {
         await new Promise((resolve, reject) => {
             let timer;
             const message = (raw) => { if (typeof raw === "object" && raw !== null && raw.ready === true)
                 doneResolve(); };
-            const exited = () => doneReject();
-            const errored = () => doneReject();
+            const exited = () => doneReject("worker_exited_before_ready");
+            const errored = () => doneReject("worker_errored_before_ready");
             const clean = () => { clearTimeout(timer); child.off("message", message); child.off("exit", exited); child.off("error", errored); };
             function doneResolve() { clean(); resolve(); }
-            function doneReject() { clean(); reject(new Error("Organization handoff authority failed")); }
-            timer = setTimeout(doneReject, 3_000);
+            function doneReject(code) {
+                clean();
+                detail = {
+                    budget: "worker_ready", code, elapsedMs: performance.now() - startedAt, limitMs: READY_DEADLINE_MS,
+                    state: `source=${String(tsWorker)} exit=${String(child.exitCode)} signal=${String(child.signalCode)}`
+                };
+                reject(createOrganizationHandoffAuthorityError(detail));
+            }
+            timer = setTimeout(() => doneReject("worker_ready_deadline"), READY_DEADLINE_MS);
             child.on("message", message);
             child.once("exit", exited);
             child.once("error", errored);
@@ -127,6 +182,6 @@ export const initializeOrganizationHandoffAuthorityFsClient = async (options) =>
     }
     catch {
         await client.dispose();
-        return fail();
+        throw createOrganizationHandoffAuthorityError(detail);
     }
 };

package/dist/deployment/organizationHandoffAuthorityFsElection.d.ts

@@ -0,0 +1,21 @@
+import type { Stats } from "node:fs";
+export type AuthorityLeafStat = Stats;
+export type AuthorityLstat = (name: string) => Promise<AuthorityLeafStat>;
+export interface AuthorityLeafInspector {
+    /** Every leaf that could legitimately hold the other end of a two-link publication. */
+    aliasesOf(name: string): readonly string[];
+    /**
+     * Whether an observed publication race is one the caller may retry.
+     *
+     * `true` permits a retry, `false` fails closed, and `null` reports that the
+     * leaf is simply absent.
+     */
+    expectedElectionState(name: string): Promise<boolean | null>;
+    /** Stat a leaf, rejecting anything that is not an ordinary owned record. */
+    statFile(name: string): Promise<AuthorityLeafStat | null>;
+}
+export interface AuthorityLeafInspectorOptions {
+    readonly lstat?: AuthorityLstat;
+    readonly owner?: number;
+}
+export declare const createAuthorityLeafInspector: (options?: AuthorityLeafInspectorOptions) => AuthorityLeafInspector;

package/dist/deployment/organizationHandoffAuthorityFsElection.js

@@ -0,0 +1,57 @@
+import { lstat as nodeLstat } from "node:fs/promises";
+import { OrganizationHandoffAuthorityFailure } from "./organizationHandoffAuthorityFsBudget.js";
+/**
+ * Leaf inspection and link-election admission for the organization handoff
+ * filesystem authority.
+ *
+ * These three functions decide whether a failed read may be retried or must
+ * fail closed, which makes them the authority's most consequential branch and
+ * the reason they live behind an injectable `lstat`: the interesting states
+ * are mid-race interleavings that cannot be staged on a real filesystem.
+ */
+const MAX_BYTES = 32_768;
+const fail = (code) => { throw new OrganizationHandoffAuthorityFailure({ code }); };
+export const createAuthorityLeafInspector = (options = {}) => {
+    const lstat = options.lstat ?? nodeLstat;
+    const owner = options.owner;
+    const statFile = async (name) => {
+        const stat = await lstat(name).catch((error) => error.code === "ENOENT" ? null : fail("lstat_failed"));
+        if (stat === null)
+            return null;
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink > 2 || stat.size > MAX_BYTES || (stat.mode & 0o077) !== 0
+            || owner !== undefined && stat.uid !== owner)
+            return fail("leaf_not_ordinary");
+        return stat;
+    };
+    const aliasesOf = (name) => [
+        `${name}.pending`, `${name}.recovery`,
+        ...(name.endsWith(".pending") ? [name.slice(0, -".pending".length)] : []),
+        ...(name.endsWith(".recovery") ? [name.slice(0, -".recovery".length)] : [])
+    ];
+    const expectedElectionState = async (name) => {
+        let stat = await statFile(name);
+        if (stat === null)
+            return null;
+        if (stat.nlink === 1)
+            return true;
+        for (const alias of aliasesOf(name)) {
+            const counterpart = await lstat(alias).catch((error) => error.code === "ENOENT" ? null : fail("election_lstat_failed"));
+            if (counterpart?.isFile() && !counterpart.isSymbolicLink() && counterpart.nlink === 2 && counterpart.dev === stat.dev && counterpart.ino === stat.ino)
+                return true;
+        }
+        // The counterpart may have disappeared just before this check. Accept only
+        // the resulting ordinary single-link state, never an unknown hard link.
+        //
+        // The leaf itself may also have gone: the helper that won the election
+        // unlinks its staging sidecar immediately after linking the final record,
+        // so a peer that observed the sidecar at two links can find it absent one
+        // syscall later. That is an absence, not an unknown link. Reporting it as
+        // a rejected election turned a benign, converging race into a hard failure
+        // for the losing publisher.
+        stat = await statFile(name);
+        if (stat === null)
+            return null;
+        return stat.nlink === 1;
+    };
+    return { aliasesOf, expectedElectionState, statFile };
+};