spawnfile 0.1.12 → 0.1.14

package/dist/deployment/organizationHandoffAuthorityFsWorker.js

@@ -0,0 +1,285 @@
+import { constants } from "node:fs";
+import { link, lstat, open, unlink } from "node:fs/promises";
+const VERSION = "spawnfile.organization-handoff-fs-worker.v1";
+const MAX_BYTES = 32_768;
+// Store keys encode either a 64-character pending key or a 71-character
+// `opaque_` handoff handle. No other leaf namespace is reachable.
+const NAME = /^(?:[a-f0-9]{128}|[a-f0-9]{142})\.json$/u;
+const owner = typeof process.getuid === "function" ? process.getuid() : undefined;
+const fail = () => { throw new Error("Organization handoff authority failed"); };
+const bytes = (value) => Buffer.byteLength(value, "utf8");
+const waitForPublisher = async () => new Promise((resolve) => setTimeout(resolve, 2));
+const validName = (value) => typeof value === "string" && NAME.test(value) ? value : fail();
+const validRequest = (raw) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw) || Object.getPrototypeOf(raw) !== Object.prototype)
+        return fail();
+    const value = raw;
+    if (value.version !== VERSION || !Number.isSafeInteger(value.id) || typeof value.op !== "string" || (value.op !== "read" && value.op !== "write" && value.op !== "create"))
+        return fail();
+    const content = value.content;
+    const keys = Object.keys(value).sort();
+    const expected = value.op === "read" ? ["id", "name", "op", "version"] : ["content", "id", "name", "op", "version"];
+    if (keys.length !== expected.length || keys.some((key, index) => key !== expected[index]))
+        return fail();
+    if (content !== undefined && (typeof content !== "string" || bytes(content) > MAX_BYTES))
+        return fail();
+    return { version: VERSION, id: value.id, op: value.op, name: validName(value.name), ...(content === undefined ? {} : { content }) };
+};
+const send = (value) => {
+    const serialized = JSON.stringify(value);
+    if (bytes(serialized) > MAX_BYTES || typeof process.send !== "function")
+        process.exit(1);
+    process.send(JSON.parse(serialized));
+};
+const statFile = async (name) => {
+    const stat = await lstat(name).catch((error) => error.code === "ENOENT" ? null : fail());
+    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();
+    return stat;
+};
+const read = async (name) => {
+    let before = await statFile(name);
+    if (before === null)
+        return null;
+    if (before.nlink === 2) {
+        const aliases = [
+            `${name}.pending`, `${name}.recovery`,
+            ...(name.endsWith(".pending") ? [name.slice(0, -".pending".length)] : []),
+            ...(name.endsWith(".recovery") ? [name.slice(0, -".recovery".length)] : [])
+        ];
+        let match;
+        for (const alias of aliases) {
+            const stat = await lstat(alias).catch((error) => error.code === "ENOENT" ? null : fail());
+            if (stat && stat.isFile() && !stat.isSymbolicLink() && stat.nlink === 2 && stat.dev === before.dev && stat.ino === before.ino) {
+                if (match)
+                    return fail();
+                match = alias;
+            }
+        }
+        if (!match) {
+            // The counterpart can be unlinked between the two lstat calls by the
+            // helper that won this link election. Re-read only if that left this
+            // same checked file with its ordinary single link.
+            const current = await statFile(name);
+            if (current === null)
+                return null;
+            if (current.nlink !== 1)
+                return fail();
+            before = current;
+        }
+        // Reading the canonical record completes a crashed publisher. An
+        // intermediate-name reader may be racing that publisher, so it merely
+        // observes the linked content and lets its normal publish path converge.
+        if (match && !name.endsWith(".pending") && !name.endsWith(".recovery")) {
+            await unlink(match).catch((error) => { if (error.code !== "ENOENT")
+                fail(); });
+            await sync();
+            before = await statFile(name);
+            if (before === null)
+                return fail();
+        }
+    }
+    const handle = await open(name, constants.O_RDONLY | constants.O_NOFOLLOW).catch((error) => error.code === "ENOENT" ? null : fail());
+    if (handle === null)
+        return null;
+    try {
+        const stat = await handle.stat();
+        // A simultaneous helper may complete the observed link publication while
+        // this descriptor is open, reducing nlink from two to one. That is the
+        // sole permitted link-count transition; inode, device, size, and all
+        // increases remain fail-closed.
+        if (!stat.isFile() || stat.nlink < 1 || stat.nlink > before.nlink || stat.dev !== before.dev || stat.ino !== before.ino || stat.size !== before.size)
+            return fail();
+        return await handle.readFile({ encoding: "utf8" });
+    }
+    catch {
+        return fail();
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+};
+const sync = async () => { const handle = await open(".", constants.O_RDONLY | constants.O_DIRECTORY).catch(fail); try {
+    await handle.sync();
+}
+finally {
+    await handle.close().catch(() => undefined);
+} };
+const expectedElectionState = async (name) => {
+    let stat = await statFile(name);
+    if (stat === null)
+        return null;
+    if (stat.nlink === 1)
+        return true;
+    const aliases = [
+        `${name}.pending`, `${name}.recovery`,
+        ...(name.endsWith(".pending") ? [name.slice(0, -".pending".length)] : []),
+        ...(name.endsWith(".recovery") ? [name.slice(0, -".recovery".length)] : [])
+    ];
+    for (const alias of aliases) {
+        const counterpart = await lstat(alias).catch((error) => error.code === "ENOENT" ? null : fail());
+        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.
+    stat = await statFile(name);
+    return stat?.nlink === 1;
+};
+const readDuringPublication = async (name, attempt = 0) => {
+    try {
+        return await read(name);
+    }
+    catch {
+        // Re-validate the leaf before retrying. This permits only a checked,
+        // ordinary one/two-link publication race; symlinks, mode/owner drift,
+        // extra links, and other malformed states still fail immediately.
+        const election = await expectedElectionState(name);
+        if (election === null)
+            return null;
+        if (attempt >= 32 || election !== true)
+            return fail();
+        await waitForPublisher();
+        return readDuringPublication(name, attempt + 1);
+    }
+};
+const write = async (name, content, attempt = 0) => {
+    if (attempt > 32)
+        return fail();
+    const joinOrRetry = async () => {
+        const published = await readDuringPublication(name);
+        if (published !== null) {
+            if (published !== content)
+                return fail();
+            return false;
+        }
+        await waitForPublisher();
+        return write(name, content, attempt + 1);
+    };
+    const existing = await readDuringPublication(name);
+    if (existing !== null) {
+        if (existing !== content)
+            fail();
+        return false;
+    }
+    const pending = `${name}.pending`;
+    const recovery = `${name}.recovery`;
+    const incomplete = await readDuringPublication(pending);
+    if (incomplete !== null && incomplete !== content && !content.startsWith(incomplete))
+        return fail();
+    if (incomplete !== null && incomplete !== content) {
+        const recovered = await readDuringPublication(recovery);
+        if (recovered !== null && recovered !== content)
+            return fail();
+        if (recovered === null) {
+            const handle = await open(recovery, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600).catch((error) => error.code === "EEXIST" ? null : fail());
+            if (handle === null) {
+                await waitForPublisher();
+                return write(name, content, attempt + 1);
+            }
+            try {
+                await handle.writeFile(content, "utf8");
+                await handle.sync();
+            }
+            finally {
+                await handle.close().catch(() => undefined);
+            }
+            const staged = await readDuringPublication(recovery);
+            if (staged === null && await readDuringPublication(name) === content)
+                return false;
+            if (staged !== content)
+                return fail();
+            await sync();
+        }
+        const recoveredLinked = await link(recovery, name).then(() => true).catch((error) => {
+            if (error.code === "EEXIST")
+                return false;
+            if (error.code === "ENOENT")
+                return null;
+            return fail();
+        });
+        if (recoveredLinked !== true)
+            return joinOrRetry();
+        await sync();
+        await unlink(recovery).catch((error) => { if (error.code !== "ENOENT")
+            fail(); });
+        await sync();
+        if (await readDuringPublication(name) !== content)
+            fail();
+        return true;
+    }
+    if (incomplete === null) {
+        const handle = await open(pending, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600).catch((error) => error.code === "EEXIST" ? null : fail());
+        if (handle === null) {
+            await waitForPublisher();
+            return write(name, content, attempt + 1);
+        }
+        try {
+            await handle.writeFile(content, "utf8");
+            await handle.sync();
+        }
+        finally {
+            await handle.close().catch(() => undefined);
+        }
+        const staged = await readDuringPublication(pending);
+        if (staged === null && await readDuringPublication(name) === content)
+            return false;
+        if (staged !== content)
+            return fail();
+        await sync();
+    }
+    const linked = await link(pending, name).then(() => true).catch((error) => {
+        if (error.code === "EEXIST")
+            return false;
+        if (error.code === "ENOENT")
+            return null;
+        return fail();
+    });
+    if (linked !== true)
+        return joinOrRetry();
+    await sync();
+    await unlink(pending).catch((error) => { if (error.code !== "ENOENT")
+        fail(); });
+    await sync();
+    if (await readDuringPublication(name) !== content)
+        fail();
+    return true;
+};
+let anchor;
+let queue = Promise.resolve();
+const start = async () => {
+    const raw = process.env.SPAWNFILE_AUTHORITY_FS_ANCHOR;
+    if (!raw)
+        return fail();
+    const expected = JSON.parse(raw);
+    const stat = await lstat(".");
+    if (!stat.isDirectory() || stat.isSymbolicLink() || stat.dev !== expected.dev || stat.ino !== expected.ino
+        || (stat.mode & 0o077) !== 0 || owner !== undefined && stat.uid !== expected.uid
+        || !Number.isSafeInteger(expected.parent_pid) || expected.parent_pid < 1 || process.ppid !== expected.parent_pid)
+        return fail();
+    anchor = expected;
+    send({ version: VERSION, ready: true });
+};
+process.on("message", (raw) => {
+    queue = queue.then(async () => {
+        const request = validRequest(raw);
+        if (!anchor)
+            return fail();
+        const stat = await lstat(".");
+        if (stat.dev !== anchor.dev || stat.ino !== anchor.ino || (stat.mode & 0o077) !== 0)
+            return fail();
+        const result = request.op === "read"
+            ? { content: await read(request.name) }
+            : { created: request.content === undefined ? fail() : await write(request.name, request.content) };
+        send({ version: VERSION, id: request.id, ok: true, ...(result.content === null ? {} : { content: result.content }), ...(request.op === "create" ? { created: result.created } : {}) });
+    }).catch(() => send({ version: VERSION, id: typeof raw === "object" && raw !== null && Number.isSafeInteger(raw.id) ? raw.id : 0, ok: false }));
+});
+process.on("disconnect", () => process.exit(0));
+// IPC disconnect covers a cooperative parent shutdown. ppid surveillance also
+// covers abrupt parent death, where an orphan might otherwise retain its cwd.
+setInterval(() => { if (!anchor || process.ppid !== anchor.parent_pid)
+    process.exit(0); }, 100).unref();
+void start().catch(() => process.exit(1));

package/dist/deployment/organizationHandoffAuthorityFsWorkerParent.fixture.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/deployment/organizationHandoffAuthorityFsWorkerParent.fixture.js

@@ -0,0 +1,26 @@
+import { fork } from "node:child_process";
+import { createRequire } from "node:module";
+import { lstat } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+const directory = process.argv[2];
+if (typeof directory !== "string")
+    process.exit(1);
+const stat = await lstat(directory).catch(() => undefined);
+if (!stat?.isDirectory())
+    process.exit(1);
+const worker = fork(fileURLToPath(new URL("./organizationHandoffAuthorityFsWorker.ts", import.meta.url)), [], {
+    cwd: directory,
+    env: { SPAWNFILE_AUTHORITY_FS_ANCHOR: JSON.stringify({ dev: stat.dev, ino: stat.ino, uid: typeof process.getuid === "function" ? process.getuid() : undefined, parent_pid: process.pid }) },
+    execArgv: ["--import", createRequire(import.meta.url).resolve("tsx")],
+    silent: true
+});
+worker.stdout?.resume();
+worker.stderr?.resume();
+worker.once("message", (message) => {
+    if (message?.ready !== true || typeof process.send !== "function")
+        process.exit(1);
+    process.send({ worker_pid: worker.pid });
+});
+// Keep the fixture parent alive until the test kills it; the worker must then
+// notice its changed ppid and exit on its own.
+setInterval(() => undefined, 1_000);

package/dist/deployment/organizationHandoffAuthorityStore.d.ts

@@ -0,0 +1,41 @@
+import { createOrganizationHandoffCapabilityPending, type OrganizationHandoffCapabilityFinalized, type OrganizationHandoffCapabilityPending, type OrganizationHandoffDockerObservation } from "./organizationHandoffAuthorityTypes.js";
+import { type OrganizationHandoffAuthorityFsClient, type OrganizationHandoffAuthorityFsClientOptions } from "./organizationHandoffAuthorityFsClient.js";
+export declare const resolveOrganizationHandoffAuthorityRoot: () => string;
+export interface OrganizationHandoffAuthorityStore {
+    begin(input: Parameters<typeof createOrganizationHandoffCapabilityPending>[0]): Promise<{
+        readonly created: boolean;
+        readonly pending: OrganizationHandoffCapabilityPending;
+    }>;
+    close(input: {
+        readonly expectedHandoff: unknown;
+        readonly organizationHandoffHandle: unknown;
+    }): Promise<void>;
+    dispose(): Promise<void>;
+    finalize(pendingKey: unknown, container: {
+        readonly containerId: unknown;
+        readonly deploymentLabels: unknown;
+    }): Promise<OrganizationHandoffCapabilityFinalized>;
+    observeDockerMutation(pendingKey: unknown, container: {
+        readonly containerId: unknown;
+        readonly deploymentLabels: unknown;
+        readonly imageId: unknown;
+    }): Promise<OrganizationHandoffDockerObservation>;
+    readDockerMutation(pendingKey: unknown): Promise<OrganizationHandoffDockerObservation | null>;
+    reserve(input: Parameters<typeof createOrganizationHandoffCapabilityPending>[0]): Promise<OrganizationHandoffCapabilityPending>;
+    resolver: {
+        resolve(input: {
+            authorization: unknown;
+            signal?: AbortSignal;
+        }): Promise<unknown>;
+    };
+}
+export interface OrganizationHandoffAuthorityStoreTestHooks {
+    beforeLeafOperation?(kind: "close" | "finalize" | "reserve" | "resolve"): Promise<void>;
+    duringLeafOperation?(kind: "reserve", operation: () => Promise<void>): Promise<void>;
+}
+export interface OrganizationHandoffAuthorityStoreInitializeOptions {
+    readonly testHooks?: OrganizationHandoffAuthorityStoreTestHooks;
+    readonly testInitializeFsClient?: (options: OrganizationHandoffAuthorityFsClientOptions) => Promise<OrganizationHandoffAuthorityFsClient>;
+    readonly workerPath?: string;
+}
+export declare const initializeOrganizationHandoffAuthorityStore: (options?: OrganizationHandoffAuthorityStoreInitializeOptions) => Promise<OrganizationHandoffAuthorityStore>;