spawnfile 0.1.13 → 0.1.17

package/dist/target/dockerTargetExecFile.js

@@ -0,0 +1,194 @@
+import { spawn } from "node:child_process";
+const ERROR = "Docker target command failed";
+const OUTPUT_CAP = 65_536;
+const TERM_GRACE_MS = 50;
+const KILL_GRACE_MS = 250;
+export class DockerTargetExecutionError extends Error {
+    kind;
+    constructor(kind) {
+        super(ERROR);
+        this.name = "DockerTargetExecutionError";
+        this.kind = kind;
+    }
+}
+export class DockerTargetCommandFailure extends DockerTargetExecutionError {
+    code;
+    stderr;
+    stdoutBytes;
+    constructor(code, stderr, stdoutBytes) {
+        super("failed");
+        this.name = "DockerTargetCommandFailure";
+        this.code = code;
+        this.stderr = stderr;
+        this.stdoutBytes = stdoutBytes;
+    }
+}
+const decode = (chunks) => {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks));
+    }
+    catch {
+        throw new DockerTargetExecutionError("failed");
+    }
+};
+/**
+ * Docker target probe/build transport with exact stdin and bounded tree teardown.
+ * POSIX children lead a private process group so timeout/abort cannot strand a
+ * buildx descendant that inherited the CLI's stdio handles.
+ */
+export const createBoundedDockerTargetExecFile = () => (file, args, options) => {
+    if (typeof file !== "string" || file.length < 1 || file.includes("\0")
+        || !Array.isArray(args) || args.some((arg) => typeof arg !== "string" || arg.includes("\0"))
+        || !options || !Number.isSafeInteger(options.timeout) || options.timeout < 1
+        || options.timeout > 120_000
+        || options.signal !== undefined && !(options.signal instanceof AbortSignal)
+        || options.stdin !== undefined && !(options.stdin instanceof Uint8Array)) {
+        return Promise.reject(new DockerTargetExecutionError("failed"));
+    }
+    if (options.signal?.aborted) {
+        return Promise.reject(new DockerTargetExecutionError("aborted"));
+    }
+    return new Promise((resolve, reject) => {
+        const grouped = process.platform !== "win32";
+        let child;
+        try {
+            child = spawn(file, args, {
+                detached: grouped,
+                shell: false,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+        }
+        catch {
+            reject(new DockerTargetExecutionError("failed"));
+            return;
+        }
+        const stdout = [];
+        const stderr = [];
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let terminal;
+        let settled = false;
+        let termTimer;
+        let killTimer;
+        const groupAbsent = () => {
+            if (!grouped || !child.pid)
+                return false;
+            try {
+                process.kill(-child.pid, 0);
+                return false;
+            }
+            catch (error) {
+                return error.code === "ESRCH";
+            }
+        };
+        const signalTree = (signal) => {
+            try {
+                if (grouped && child.pid)
+                    process.kill(-child.pid, signal);
+                else
+                    child.kill(signal);
+            }
+            catch { /* only a later ESRCH liveness probe proves quiescence */ }
+        };
+        const destroyPipes = () => {
+            child.stdin.on("error", () => undefined);
+            child.stdout.on("error", () => undefined);
+            child.stderr.on("error", () => undefined);
+            child.stdin.destroy();
+            child.stdout.destroy();
+            child.stderr.destroy();
+        };
+        const cleanup = () => {
+            clearTimeout(timeoutTimer);
+            if (termTimer)
+                clearTimeout(termTimer);
+            if (killTimer)
+                clearTimeout(killTimer);
+            options.signal?.removeEventListener("abort", onAbort);
+        };
+        const finish = (error, unresolved = false) => {
+            if (settled || !unresolved && !groupAbsent())
+                return;
+            settled = true;
+            cleanup();
+            destroyPipes();
+            reject(error);
+        };
+        const terminate = (kind) => {
+            if (terminal || settled)
+                return;
+            terminal = new DockerTargetExecutionError(kind);
+            signalTree("SIGTERM");
+            termTimer = setTimeout(() => {
+                signalTree("SIGKILL");
+                destroyPipes();
+                const started = Date.now();
+                const poll = () => {
+                    if (!terminal || settled)
+                        return;
+                    if (groupAbsent()) {
+                        finish(terminal);
+                        return;
+                    }
+                    signalTree("SIGKILL");
+                    if (Date.now() - started >= KILL_GRACE_MS) {
+                        finish(new DockerTargetExecutionError("cleanup_failed"), true);
+                        return;
+                    }
+                    killTimer = setTimeout(poll, 10);
+                };
+                poll();
+            }, TERM_GRACE_MS);
+        };
+        const append = (target, chunk, output) => {
+            const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            if (output === "stdout")
+                stdoutBytes += value.byteLength;
+            else
+                stderrBytes += value.byteLength;
+            if (stdoutBytes > OUTPUT_CAP || stderrBytes > OUTPUT_CAP) {
+                terminate("failed");
+                return;
+            }
+            target.push(Buffer.from(value));
+        };
+        function onAbort() { terminate("aborted"); }
+        child.stdout.on("data", (chunk) => append(stdout, chunk, "stdout"));
+        child.stderr.on("data", (chunk) => append(stderr, chunk, "stderr"));
+        child.stdin.on("error", () => terminate("failed"));
+        child.on("error", () => terminate("failed"));
+        child.on("close", (code) => {
+            if (terminal || settled)
+                return;
+            settled = true;
+            cleanup();
+            try {
+                const stderrText = decode(stderr);
+                const stdoutText = decode(stdout);
+                if (code !== 0) {
+                    reject(new DockerTargetCommandFailure(code ?? -1, stderrText, Buffer.byteLength(stdoutText, "utf8")));
+                    return;
+                }
+                resolve({ stderr: stderrText, stdout: stdoutText });
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        const timeoutTimer = setTimeout(() => terminate("timeout"), options.timeout);
+        if (options.signal?.aborted) {
+            terminate("aborted");
+            return;
+        }
+        try {
+            const input = options.stdin === undefined ? undefined
+                : Buffer.from(options.stdin.buffer, options.stdin.byteOffset, options.stdin.byteLength);
+            child.stdin.end(input);
+        }
+        catch {
+            terminate("failed");
+        }
+    });
+};
+export const defaultDockerTargetExecFile = createBoundedDockerTargetExecFile();

package/dist/target/dockerWorldClock.d.ts

@@ -0,0 +1,17 @@
+import type { DockerTargetExecutors } from "./dockerCommandExecutor.js";
+import type { DockerWorldServiceExecutor } from "./dockerWorldServiceProvider.js";
+import type { WorldServiceAuthorityReader } from "./dockerWorldServiceStore.js";
+import { type TargetWorldClockReceipt } from "./worldClock.js";
+export declare const TARGET_WORLD_CLOCK_ERROR = "Target world clock query failed";
+export interface DockerWorldClockOptions {
+    readonly authorityStore: WorldServiceAuthorityReader;
+    readonly context: string;
+    readonly contentExecutor: DockerTargetExecutors["publicArtifact"];
+    readonly executor: DockerWorldServiceExecutor;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs: number;
+}
+export interface WorldClockReader {
+    query(raw: unknown): Promise<TargetWorldClockReceipt>;
+}
+export declare const createDockerWorldClockReader: (input: DockerWorldClockOptions) => WorldClockReader;

package/dist/target/dockerWorldClock.js

@@ -0,0 +1,111 @@
+import { SpawnfileError } from "../shared/index.js";
+import { inspectDockerWorldService, sameWorldServiceValue, worldServiceSpecForBinding, } from "./dockerWorldServiceLifecycle.js";
+import { createCanonicalWorldServiceActivationBytes, createTargetTopologyActivationReceiptDigest, createWorldServiceActivationDigest, parseWorldServiceActivation, } from "./topologyActivation.js";
+import { createTargetWorldClockReceipt, MAX_TARGET_WORLD_CLOCK_BYTES, parseTargetWorldClockRequest, } from "./worldClock.js";
+export const TARGET_WORLD_CLOCK_ERROR = "Target world clock query failed";
+const CONTEXT = /^[a-z][a-z0-9_-]{0,63}$/u;
+const fail = () => { throw new SpawnfileError("runtime_error", TARGET_WORLD_CLOCK_ERROR); };
+const options = (raw) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)
+        || typeof raw.context !== "string" || !CONTEXT.test(raw.context)
+        || typeof raw.contentExecutor !== "function" || typeof raw.executor !== "function"
+        || !raw.authorityStore || typeof raw.authorityStore.loadService !== "function"
+        || !Number.isSafeInteger(raw.timeoutMs) || raw.timeoutMs < 1 || raw.timeoutMs > 120_000
+        || raw.signal !== undefined && !(raw.signal instanceof AbortSignal))
+        return fail();
+    return raw;
+};
+const queryScript = [
+    "import http from \"node:http\";",
+    "const [rawPort,pathname]=process.argv.slice(1);const port=Number(rawPort);",
+    "const fail=()=>{process.exitCode=1;};",
+    "if(!Number.isSafeInteger(port)||port<1||port>65535||pathname!==\"/v1/world/clock\")fail();",
+    "else http.get({headers:{accept:\"application/json\"},host:\"127.0.0.1\",path:pathname,port},response=>{",
+    "const media=response.headers[\"content-type\"];if(response.statusCode!==200||typeof media!==\"string\"||!media.toLowerCase().startsWith(\"application/json\")){response.resume();fail();return;}",
+    `const chunks=[];let size=0;response.on("data",chunk=>{size+=chunk.length;if(size>${MAX_TARGET_WORLD_CLOCK_BYTES}){response.destroy();fail();}else chunks.push(chunk);});`,
+    "response.on(\"end\",()=>{if(process.exitCode!==1)process.stdout.write(Buffer.concat(chunks));});response.on(\"error\",fail);",
+    "}).on(\"error\",fail);",
+].join("\n");
+const bytes = async (optionsValue, args) => {
+    const result = await optionsValue.contentExecutor("docker", [
+        "--context", optionsValue.context, "container", "exec", ...args,
+    ], { signal: optionsValue.signal, timeout: optionsValue.timeoutMs }).catch(fail);
+    if (!result || !(result.bytes instanceof Uint8Array)
+        || result.bytes.byteLength < 2 || result.bytes.byteLength > MAX_TARGET_WORLD_CLOCK_BYTES)
+        return fail();
+    return result.bytes;
+};
+const json = (raw) => {
+    try {
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(raw));
+    }
+    catch {
+        return fail();
+    }
+};
+class DockerWorldClockReader {
+    #options;
+    constructor(input) { this.#options = options(input); }
+    async query(raw) {
+        let request;
+        try {
+            request = parseTargetWorldClockRequest(raw);
+        }
+        catch {
+            return fail();
+        }
+        const binding = await this.#options.authorityStore
+            .loadService(request.world_service_handle).catch(fail);
+        const authorization = binding.resolution.authorization;
+        if (binding.world_service_handle !== request.world_service_handle
+            || authorization.run_id !== request.run_id
+            || authorization.descriptor_digest !== request.descriptor_digest
+            || !sameWorldServiceValue(authorization.selected_target, request.selected_target))
+            return fail();
+        const spec = worldServiceSpecForBinding(binding);
+        const before = await inspectDockerWorldService(binding.container_id, spec, this.#options).catch(fail);
+        if (!before || before.containerId !== binding.container_id || before.status !== "running")
+            return fail();
+        const markerBytes = await bytes(this.#options, [
+            binding.container_id, "/bin/cat",
+            `${spec.evidenceMountPath}/.spawnfile/world-service-activated.v1`,
+        ]);
+        let marker;
+        try {
+            marker = parseWorldServiceActivation(json(markerBytes));
+            if (new TextDecoder().decode(markerBytes) !== createCanonicalWorldServiceActivationBytes(marker)
+                || marker.run_id !== request.run_id
+                || marker.topology_receipt_digest !== request.topology_receipt_digest
+                || marker.topology_request_digest !== request.topology_request_digest
+                || createWorldServiceActivationDigest(marker) !== request.activation_digest)
+                return fail();
+            const activationBody = {
+                activation_digest: request.activation_digest, bundle_digest: marker.bundle_digest,
+                receipt_digest: `sha256:${"0".repeat(64)}`, run_id: marker.run_id,
+                state: "activated", topology_receipt_digest: marker.topology_receipt_digest,
+                topology_request_digest: marker.topology_request_digest,
+                version: "spawnfile.target-topology-activation-receipt.v1",
+            };
+            if (createTargetTopologyActivationReceiptDigest(activationBody)
+                !== request.activation_receipt_digest)
+                return fail();
+        }
+        catch {
+            return fail();
+        }
+        const observed = json(await bytes(this.#options, [
+            binding.container_id, "/usr/local/bin/node", "--input-type=module", "-e",
+            queryScript, String(request.endpoint.internal_port), request.endpoint.path,
+        ]));
+        const after = await inspectDockerWorldService(binding.container_id, spec, this.#options).catch(fail);
+        if (!after || after.containerId !== before.containerId || after.status !== "running")
+            return fail();
+        try {
+            return createTargetWorldClockReceipt({ observation: observed, request });
+        }
+        catch {
+            return fail();
+        }
+    }
+}
+export const createDockerWorldClockReader = (input) => new DockerWorldClockReader(input);

package/dist/target/dockerWorldReadiness.d.ts

@@ -0,0 +1,17 @@
+import type { DockerTargetExecutors } from "./dockerCommandExecutor.js";
+import { type DockerWorldServiceExecutor } from "./dockerWorldServiceProvider.js";
+import type { WorldServiceAuthorityReader } from "./dockerWorldServiceStore.js";
+import { type TargetWorldReadinessReceipt } from "./worldReadiness.js";
+export declare const TARGET_WORLD_READINESS_ERROR = "Target world readiness query failed";
+export interface DockerWorldReadinessOptions {
+    readonly authorityStore: WorldServiceAuthorityReader;
+    readonly context: string;
+    readonly contentExecutor: DockerTargetExecutors["publicArtifact"];
+    readonly executor: DockerWorldServiceExecutor;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs: number;
+}
+export interface WorldReadinessReader {
+    query(raw: unknown): Promise<TargetWorldReadinessReceipt>;
+}
+export declare const createDockerWorldReadinessReader: (options: DockerWorldReadinessOptions) => WorldReadinessReader;

package/dist/target/dockerWorldReadiness.js

@@ -0,0 +1,119 @@
+import { SpawnfileError } from "../shared/index.js";
+import { types as nodeTypes } from "node:util";
+import { inspectDockerWorldService, sameWorldServiceValue, worldServiceSpecForBinding } from "./dockerWorldServiceLifecycle.js";
+import { createTargetWorldReadinessReceipt, MAX_TARGET_WORLD_READINESS_BYTES, parseTargetWorldReadinessRequest } from "./worldReadiness.js";
+export const TARGET_WORLD_READINESS_ERROR = "Target world readiness query failed";
+const CONTEXT_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/u;
+const fail = () => {
+    throw new SpawnfileError("runtime_error", TARGET_WORLD_READINESS_ERROR);
+};
+const validOptions = (raw) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw) || nodeTypes.isProxy(raw)
+        || Object.getPrototypeOf(raw) !== Object.prototype)
+        return fail();
+    const descriptors = Object.getOwnPropertyDescriptors(raw);
+    const required = [
+        "authorityStore", "context", "contentExecutor", "executor", "timeoutMs"
+    ];
+    const expected = Object.hasOwn(descriptors, "signal") ? [...required, "signal"] : required;
+    const keys = Reflect.ownKeys(raw);
+    if (keys.length !== expected.length
+        || keys.some((key) => typeof key !== "string" || !expected.includes(key))
+        || Object.values(descriptors).some((descriptor) => !descriptor.enumerable || !("value" in descriptor)))
+        return fail();
+    const values = Object.fromEntries(expected.map((key) => [key, descriptors[key].value]));
+    if (typeof values.context !== "string" || !CONTEXT_PATTERN.test(values.context)
+        || typeof values.contentExecutor !== "function"
+        || typeof values.executor !== "function"
+        || !values.authorityStore || typeof values.authorityStore.loadService !== "function"
+        || !Number.isSafeInteger(values.timeoutMs) || values.timeoutMs < 1
+        || values.timeoutMs > 120_000
+        || values.signal !== undefined && !(values.signal instanceof AbortSignal))
+        return fail();
+    return Object.freeze(values);
+};
+const exactBinding = async (request, options) => {
+    const binding = await options.authorityStore.loadService(request.world_service_handle);
+    const authorization = binding.resolution.authorization;
+    if (binding.world_service_handle !== request.world_service_handle
+        || authorization.run_id !== request.run_id
+        || authorization.descriptor_digest !== request.descriptor_digest
+        || !sameWorldServiceValue(authorization.selected_target, request.selected_target))
+        return fail();
+    return binding;
+};
+const queryScript = [
+    "import http from \"node:http\";",
+    "const [rawPort, pathname] = process.argv.slice(1);",
+    "const port = Number(rawPort);",
+    "const fail = () => { process.exitCode = 1; };",
+    "if (!Number.isSafeInteger(port) || port < 1 || port > 65535 || pathname !== \"/v1/world/readiness\") fail();",
+    "else http.get({headers:{accept:\"application/json\"},host:\"127.0.0.1\",path:pathname,port}, response => {",
+    "const mediaType = response.headers[\"content-type\"];",
+    "if (response.statusCode !== 200 || typeof mediaType !== \"string\" || !mediaType.toLowerCase().startsWith(\"application/json\")) { response.resume(); fail(); return; }",
+    "const chunks = []; let size = 0;",
+    `response.on("data", chunk => { size += chunk.length; if (size > ${MAX_TARGET_WORLD_READINESS_BYTES}) { response.destroy(); fail(); } else chunks.push(chunk); });`,
+    "response.on(\"end\", () => { if (process.exitCode !== 1) process.stdout.write(Buffer.concat(chunks)); });",
+    "response.on(\"error\", fail);",
+    "}).on(\"error\", fail);"
+].join("\n");
+const queryWorld = async (containerId, request, options) => {
+    try {
+        const result = await options.contentExecutor("docker", [
+            "--context", options.context,
+            "container", "exec",
+            containerId,
+            "/usr/local/bin/node",
+            "--input-type=module",
+            "-e",
+            queryScript,
+            String(request.endpoint.internal_port),
+            request.endpoint.path
+        ], {
+            signal: options.signal,
+            timeout: options.timeoutMs
+        });
+        if (!result || !(result.bytes instanceof Uint8Array)
+            || result.bytes.byteLength < 2
+            || result.bytes.byteLength > MAX_TARGET_WORLD_READINESS_BYTES)
+            return fail();
+        const text = new TextDecoder("utf-8", { fatal: true }).decode(result.bytes);
+        return JSON.parse(text);
+    }
+    catch {
+        return fail();
+    }
+};
+class DockerWorldReadinessReader {
+    #options;
+    constructor(options) {
+        this.#options = validOptions(options);
+    }
+    async query(raw) {
+        let request;
+        try {
+            request = parseTargetWorldReadinessRequest(raw);
+        }
+        catch {
+            return fail();
+        }
+        const binding = await exactBinding(request, this.#options).catch(fail);
+        const spec = worldServiceSpecForBinding(binding);
+        const before = await inspectDockerWorldService(binding.container_id, spec, this.#options).catch(fail);
+        if (!before || before.containerId !== binding.container_id
+            || before.status !== "running")
+            return fail();
+        const document = await queryWorld(binding.container_id, request, this.#options);
+        const after = await inspectDockerWorldService(binding.container_id, spec, this.#options).catch(fail);
+        if (!after || after.containerId !== before.containerId
+            || after.status !== "running")
+            return fail();
+        try {
+            return createTargetWorldReadinessReceipt({ document, request });
+        }
+        catch {
+            return fail();
+        }
+    }
+}
+export const createDockerWorldReadinessReader = (options) => new DockerWorldReadinessReader(options);

package/dist/target/dockerWorldService.d.ts

@@ -0,0 +1,23 @@
+import { type TargetResourceReceipt } from "./contracts.js";
+import { type TargetJournalStore } from "./journal.js";
+import { type WorldServiceResolver } from "./dockerWorldServiceAuthority.js";
+import { type DockerWorldServiceExecutor } from "./dockerWorldServiceProvider.js";
+import { type WorldServiceAuthorityStore } from "./dockerWorldServiceStore.js";
+type OperationResult = {
+    readonly receipt: TargetResourceReceipt;
+    readonly receiptBytes: string;
+};
+export interface DockerWorldServiceOperationsOptions {
+    readonly authorityStore: WorldServiceAuthorityStore;
+    readonly context: unknown;
+    readonly executor: DockerWorldServiceExecutor;
+    readonly journal: TargetJournalStore;
+    readonly resolver: WorldServiceResolver;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: unknown;
+}
+export interface DockerWorldServiceOperations {
+    execute(raw: unknown): Promise<OperationResult>;
+}
+export declare const createDockerWorldServiceOperations: (options: DockerWorldServiceOperationsOptions) => DockerWorldServiceOperations;
+export {};