@fungi.computer/computer 0.0.0-stage → 0.1.0

package/dist/process-inventory.js

@@ -0,0 +1,427 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { z } from "zod";
+import { computerProcessSchema, processStartInputSchema, mintComputerProcessId, ComputerProcessLimitError, ComputerPortReservedError, ComputerPortConflictError, ComputerPortLimitError, isComputerReservedPort, maximumExposedPorts, maximumProcessRecords, maximumRunningProcesses, } from "./operation-contract.js";
+import { ComputerOperationConflictError } from "./operation-record.js";
+function toProcess(row) {
+    return computerProcessSchema.parse({
+        id: row.id,
+        command: row.command,
+        cwd: row.cwd,
+        port: row.port,
+        state: row.state,
+        exitCode: row.exit_code,
+        sync: row.sync,
+        startedAt: row.started_at,
+        endedAt: row.ended_at,
+    });
+}
+/**
+ * Bump when `computer_processes`' columns change. Pre-release data is
+ * disposable (no migrations before launch): a mismatch resets the table
+ * to the fresh schema instead of a strict-table write throwing on an old
+ * row shape. Tracked in a dedicated row, not `PRAGMA user_version`: that
+ * pragma returns SQLITE_AUTH against a real Durable Object's SQLite
+ * storage (confirmed in workerd; node:sqlite does not enforce the same
+ * sandbox, so a unit test against it alone would hide this).
+ */
+const processSchemaVersion = 2;
+/** Computer-owned replay identities; computerd owns execution and exit observations. */
+export class ComputerProcessInventory {
+    #storage;
+    #now;
+    constructor(storage, now) {
+        this.#storage = storage;
+        this.#now = now;
+        storage.transactionSync(() => {
+            storage.sql.exec("CREATE TABLE IF NOT EXISTS computer_schema_meta (id INTEGER PRIMARY KEY CHECK (id = 0), version INTEGER NOT NULL) STRICT");
+            const seenVersion = storage.sql
+                .exec("SELECT version FROM computer_schema_meta WHERE id = 0")
+                .toArray()[0]?.version ?? 0;
+            if (seenVersion !== processSchemaVersion) {
+                storage.sql.exec("DROP TABLE IF EXISTS computer_processes");
+                storage.sql.exec("DROP TABLE IF EXISTS computer_exposed_ports");
+                storage.sql.exec("DELETE FROM computer_schema_meta WHERE id = 0");
+                storage.sql.exec("INSERT INTO computer_schema_meta (id, version) VALUES (0, ?)", processSchemaVersion);
+            }
+            storage.sql.exec("CREATE TABLE IF NOT EXISTS computer_processes (id TEXT PRIMARY KEY, request_scope TEXT NOT NULL, request_id TEXT NOT NULL, input_hash TEXT NOT NULL, command TEXT NOT NULL, cwd TEXT, port INTEGER, state TEXT NOT NULL CHECK (state IN ('running','exited')), exit_code INTEGER, sync TEXT NOT NULL DEFAULT 'unknown' CHECK (sync IN ('synced','pending','unknown')), started_at INTEGER NOT NULL, ended_at INTEGER, CHECK ((state = 'running') = (ended_at IS NULL)), UNIQUE(request_scope, request_id)) STRICT");
+            storage.sql.exec("CREATE TABLE IF NOT EXISTS computer_exposed_ports (port INTEGER PRIMARY KEY CHECK (port BETWEEN 1 AND 65535), process_id TEXT) STRICT");
+        });
+    }
+    #matching(input, inputHash, accept) {
+        const row = this.#storage.sql
+            .exec("SELECT * FROM computer_processes WHERE request_scope = ? AND request_id = ?", input.requestScope, input.requestId)
+            .toArray()[0];
+        if (row === undefined)
+            return undefined;
+        accept?.();
+        if (row.input_hash !== inputHash)
+            throw new ComputerOperationConflictError();
+        const process = toProcess(row);
+        // Admission may still be dispatching: a receipt alone does not prove liveness.
+        return process.state === "running"
+            ? { ...process, state: "uncertain" }
+            : process;
+    }
+    /** A replay does not boot a backend or redispatch an exited command. */
+    replay(input, inputHash, accept) {
+        return this.#storage.transactionSync(() => {
+            return this.#matching(input, inputHash, accept);
+        });
+    }
+    /** Reserve the process and only a newly created exposure in one transaction. */
+    admit(input, inputHash, accept) {
+        return this.#storage.transactionSync(() => {
+            accept();
+            const existing = this.#matching(input, inputHash);
+            if (existing !== undefined)
+                return { process: existing, created: false };
+            const now = this.#now();
+            const running = this.#storage.sql
+                .exec("SELECT COUNT(*) AS count FROM computer_processes WHERE state = 'running' AND request_scope = ?", input.requestScope)
+                .toArray()[0]?.count ?? maximumRunningProcesses;
+            if (running >= maximumRunningProcesses)
+                throw new ComputerProcessLimitError();
+            const id = mintComputerProcessId();
+            if (input.port !== undefined) {
+                if (isComputerReservedPort(input.port))
+                    throw new ComputerPortReservedError(input.port);
+                const exposure = this.#storage.sql
+                    .exec("SELECT process_id FROM computer_exposed_ports WHERE port = ?", input.port)
+                    .toArray()[0];
+                if (exposure !== undefined && exposure.process_id !== null)
+                    throw new ComputerPortConflictError();
+                if (exposure === undefined) {
+                    const ports = this.#storage.sql
+                        .exec("SELECT COUNT(*) AS count FROM computer_exposed_ports")
+                        .toArray()[0]?.count ?? maximumExposedPorts;
+                    if (ports >= maximumExposedPorts)
+                        throw new ComputerPortLimitError();
+                    this.#storage.sql.exec("INSERT INTO computer_exposed_ports (port, process_id) VALUES (?, ?)", input.port, id);
+                }
+            }
+            this.#storage.sql.exec("INSERT INTO computer_processes (id, request_scope, request_id, input_hash, command, cwd, port, state, started_at) VALUES (?, ?, ?, ?, ?, ?, ?, 'running', ?)", id, input.requestScope, input.requestId, inputHash, input.command, input.cwd ?? null, input.port ?? null, now);
+            // Each scope retains its own newest 64 rows, including running processes.
+            this.#storage.sql.exec("DELETE FROM computer_processes WHERE request_scope = ? AND state = 'exited' AND id NOT IN (SELECT id FROM computer_processes WHERE request_scope = ? AND state = 'exited' ORDER BY started_at DESC, id DESC LIMIT MAX(0, ? - (SELECT COUNT(*) FROM computer_processes WHERE request_scope = ? AND state = 'running')))", input.requestScope, input.requestScope, maximumProcessRecords, input.requestScope);
+            return { process: this.#require(id), created: true };
+        });
+    }
+    exited(id, exitCode, sync = "unknown") {
+        return this.#storage.transactionSync(() => {
+            this.#storage.sql.exec("UPDATE computer_processes SET state = 'exited', exit_code = ?, sync = ?, ended_at = ? WHERE id = ? AND state = 'running'", exitCode, sync, this.#now(), id);
+            this.#storage.sql.exec("DELETE FROM computer_exposed_ports WHERE process_id = ?", id);
+            return this.#require(id);
+        });
+    }
+    /** Retain a failed dispatch receipt: retrying that key cannot create new work. */
+    release(id) {
+        const row = this.get(id);
+        if (row?.state === "running")
+            this.exited(id, null);
+    }
+    /**
+     * Upgrade an already-exited row's sync verdict once a background drain
+     * (one that gave up synchronously at its deadline) resolves it. A
+     * no-op if the row was evicted or never exited: pending rows must be
+     * updatable here, not only running ones.
+     */
+    resync(id, sync) {
+        this.#storage.transactionSync(() => {
+            this.#storage.sql.exec("UPDATE computer_processes SET sync = ? WHERE id = ? AND state = 'exited'", sync, id);
+        });
+    }
+    get(id) {
+        const row = this.#storage.sql
+            .exec("SELECT * FROM computer_processes WHERE id = ?", id)
+            .toArray()[0];
+        return row === undefined ? undefined : toProcess(row);
+    }
+    list() {
+        return this.#storage.sql
+            .exec("SELECT * FROM computer_processes ORDER BY started_at DESC, id DESC")
+            .toArray()
+            .map(toProcess);
+    }
+    #require(id) {
+        const found = this.get(id);
+        if (found === undefined)
+            throw new Error(`Computer process record is missing: ${id}`);
+        return found;
+    }
+}
+/** How long a tail read may stay silent before the process counts as live. */
+export const liveProbeMs = 750;
+const lostCodeSchema = z.object({ code: z.enum(["EEXEC_LOST", "ENOENT"]) });
+const busyCodeSchema = z.object({ code: z.literal("EEXEC_BUSY") });
+/**
+ * A replaced container runtime (the package's fence) or an execution computerd
+ * no longer holds (its retention elapsed) both prove the process is gone.
+ */
+function lostExecution(error) {
+    return lostCodeSchema.safeParse(error).success;
+}
+/** Classify a failed attach: busy is live, lost is gone, anything else is unknown. */
+function failedObservation(error) {
+    if (error === undefined)
+        return { state: "uncertain" };
+    // computerd admits one live subscriber; the Computer's own watcher holding
+    // it proves the execution is still live.
+    if (busyCodeSchema.safeParse(error).success)
+        return { state: "running" };
+    return lostExecution(error)
+        ? { state: "exited", exitCode: null, sync: "unknown" }
+        : { state: "uncertain" };
+}
+async function readExitCode(runtime, id) {
+    const env_1 = { stack: [], error: void 0, hasError: false };
+    try {
+        const replay = __addDisposableResource(env_1, await runtime.getExec(id, { resume: "full" }), false);
+        const reader = replay.getReader();
+        let exitCode = null;
+        for (;;) {
+            const next = await reader.read();
+            if (next.done)
+                break;
+            if (next.value.name === "exit")
+                exitCode = next.value.code;
+        }
+        return exitCode;
+    }
+    catch (e_1) {
+        env_1.error = e_1;
+        env_1.hasError = true;
+    }
+    finally {
+        __disposeResources(env_1);
+    }
+}
+/**
+ * How long a drain may keep waiting for EOF once an exit has already been
+ * observed, before giving up: a backgrounded child (for example
+ * `node server.js &`) can hold the transport open long past its own
+ * parent's exit, and nothing here may hang on that forever.
+ */
+export const postExitDrainDeadlineMs = 2_000;
+const drainTimedOut = Symbol("computer-process-drain-timed-out");
+/**
+ * Keep reading past the deadline so a slow-but-real pull still lands as
+ * "synced" instead of leaving the row stuck at "pending" forever; an
+ * error gives up without claiming anything new. The caller already
+ * handed off disposal to whoever awaits this.
+ */
+async function drainInBackground(reader) {
+    try {
+        for (;;) {
+            const next = await reader.read();
+            if (next.done)
+                return "synced";
+        }
+    }
+    catch (cause) {
+        console.error("Computer process background drain failed", cause);
+        return "pending";
+    }
+}
+/**
+ * Keep reading `reader` past an already-observed exit, bounded: the read
+ * that reaches EOF is the one that runs computerd's post-command pull
+ * (the contract in computer-execution-backends.md), so the ordinary case
+ * still waits for it and reports "synced". If the deadline passes
+ * first, hands back a `settleLater` promise that keeps draining in the
+ * background and resolves once that real EOF finally arrives -- the
+ * caller must keep the reader alive for it (not dispose it) and is
+ * responsible for keeping its own host alive too (a Durable Object's
+ * `waitUntil`), and for applying the eventual upgrade. This is also what
+ * keeps a backgrounded child holding the transport open (for example
+ * `node server.js &`) from hanging the caller synchronously.
+ */
+async function drainPastExit(reader) {
+    let timer;
+    const expired = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            resolve(drainTimedOut);
+        }, postExitDrainDeadlineMs);
+    });
+    try {
+        for (;;) {
+            const next = await Promise.race([reader.read(), expired]);
+            if (next === drainTimedOut)
+                return { sync: "pending", settleLater: drainInBackground(reader) };
+            if (next.done)
+                return { sync: "synced" };
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Observe one execution without consuming its output: a tail attach emits
+ * nothing for a live process, closes at once for an exited one, and fails
+ * for one computerd no longer holds.
+ */
+export async function observeProcess(runtime, id) {
+    let tail;
+    try {
+        tail = await runtime.getExec(id, { resume: "tail" });
+    }
+    catch (error) {
+        return failedObservation(error instanceof Error ? error : undefined);
+    }
+    const reader = tail.getReader();
+    // Not a `using` disposal: the "pending" branch below hands the reader
+    // to a background continuation and must not dispose it out from under
+    // that continuation.
+    const dispose = () => {
+        reader.releaseLock();
+        tail[Symbol.dispose]();
+    };
+    const silent = Symbol("silent");
+    let timer;
+    let settleLater;
+    try {
+        const first = await Promise.race([
+            reader.read(),
+            new Promise((resolve) => {
+                timer = setTimeout(() => {
+                    resolve(silent);
+                }, liveProbeMs);
+            }),
+        ]);
+        if (first === silent)
+            return { state: "running" };
+        if (first.done) {
+            try {
+                return {
+                    state: "exited",
+                    exitCode: await readExitCode(runtime, id),
+                    sync: "unknown",
+                };
+            }
+            catch (cause) {
+                console.error("Computer process observation cleanup failed", cause);
+                return { state: "exited", exitCode: null, sync: "unknown" };
+            }
+        }
+        if (first.value.name === "exit") {
+            // Keep draining to EOF, bounded, before reporting exited: that read
+            // is the one that runs computerd's post-command Workspace pull.
+            // Returning immediately disposes the reader first (the `finally`
+            // below cancels it), which skips that pull instead of waiting for
+            // it; waiting unboundedly can hang on a backgrounded child that
+            // still holds the transport open past this execution's own exit.
+            const exitCode = first.value.code;
+            const drained = await drainPastExit(reader);
+            settleLater = drained.settleLater;
+            if (settleLater !== undefined)
+                return { state: "exited", exitCode, sync: drained.sync, settleLater };
+            return { state: "exited", exitCode, sync: drained.sync };
+        }
+        return { state: "running" };
+    }
+    catch (error) {
+        return failedObservation(error instanceof Error ? error : undefined);
+    }
+    finally {
+        clearTimeout(timer);
+        if (settleLater === undefined) {
+            await reader.cancel().catch((cause) => {
+                console.error("Computer process observation cleanup failed", cause);
+                return undefined;
+            });
+            dispose();
+        }
+        else {
+            void settleLater.finally(dispose);
+        }
+    }
+}
+/**
+ * Drain `run` to its exit, bounded past that exit the same way
+ * `observeProcess` is, and determine whether its files reached the
+ * Workspace. `undefined` if the stream broke or was replaced before any
+ * exit was observed -- there is nothing to record.
+ */
+export async function drainProcessExit(run) {
+    const reader = run.getReader();
+    const dispose = () => {
+        reader.releaseLock();
+        run[Symbol.dispose]();
+    };
+    let exitCode;
+    let sync = "unknown";
+    let settleLater;
+    try {
+        for (;;) {
+            const next = await reader.read();
+            if (next.done)
+                break;
+            if (next.value.name === "exit") {
+                exitCode = next.value.code;
+                const drained = await drainPastExit(reader);
+                sync = drained.sync;
+                settleLater = drained.settleLater;
+                break;
+            }
+        }
+    }
+    finally {
+        if (settleLater === undefined)
+            dispose();
+    }
+    if (exitCode === undefined)
+        return undefined;
+    if (settleLater !== undefined)
+        return { exitCode, sync, settleLater: settleLater.finally(dispose) };
+    return { exitCode, sync };
+}

package/dist/pull-pending.d.ts

@@ -0,0 +1,26 @@
+import type { SyncRetryScheduler } from "@fungi.computer/cloudflare-computer";
+/**
+ * A faithful, in-memory delegate for `@cloudflare/computer`'s own
+ * `retryScheduler` option: the library's documented host-owned durable
+ * storage boundary for a post-command pull that failed (`onPullPending`,
+ * from `runPostPull`'s catch branch -- "the workspace library cannot own
+ * a Durable Object alarm"). `get`, `schedule` and `clear` store and return
+ * the library's real intents, so its own dedup-by-runtimeId and
+ * exponential backoff (`Workspace.retryPendingSync`) stay correct for
+ * whoever wires an alarm to drive it. A wrapper that invents its own
+ * signal instead -- for example, one whose `get` always reports no
+ * existing intent, to make the library call `schedule` on every failure
+ * -- would break that dedup and backoff for an actual retry.
+ *
+ * This Computer does not yet call `retryPendingSync` from anywhere (no
+ * Durable Object alarm is wired to it), so a pending backend only clears
+ * when that retry runs and succeeds; it does not self-heal if the
+ * underlying problem goes away on its own. It is also in-memory only: it
+ * does not survive a Durable Object eviction. Both are known, bounded
+ * limitations, not a second compatibility path -- the real fix is wiring
+ * an alarm to `retryPendingSync`, a separate change.
+ */
+export declare class PullPendingTracker {
+    #private;
+    readonly scheduler: SyncRetryScheduler;
+}

package/dist/pull-pending.js

@@ -0,0 +1,35 @@
+/**
+ * A faithful, in-memory delegate for `@cloudflare/computer`'s own
+ * `retryScheduler` option: the library's documented host-owned durable
+ * storage boundary for a post-command pull that failed (`onPullPending`,
+ * from `runPostPull`'s catch branch -- "the workspace library cannot own
+ * a Durable Object alarm"). `get`, `schedule` and `clear` store and return
+ * the library's real intents, so its own dedup-by-runtimeId and
+ * exponential backoff (`Workspace.retryPendingSync`) stay correct for
+ * whoever wires an alarm to drive it. A wrapper that invents its own
+ * signal instead -- for example, one whose `get` always reports no
+ * existing intent, to make the library call `schedule` on every failure
+ * -- would break that dedup and backoff for an actual retry.
+ *
+ * This Computer does not yet call `retryPendingSync` from anywhere (no
+ * Durable Object alarm is wired to it), so a pending backend only clears
+ * when that retry runs and succeeds; it does not self-heal if the
+ * underlying problem goes away on its own. It is also in-memory only: it
+ * does not survive a Durable Object eviction. Both are known, bounded
+ * limitations, not a second compatibility path -- the real fix is wiring
+ * an alarm to `retryPendingSync`, a separate change.
+ */
+export class PullPendingTracker {
+    #intents = new Map();
+    scheduler = {
+        get: (backend) => Promise.resolve(this.#intents.get(backend)),
+        schedule: (intent) => {
+            this.#intents.set(intent.backend, intent);
+            return Promise.resolve();
+        },
+        clear: (backend) => {
+            this.#intents.delete(backend);
+            return Promise.resolve();
+        },
+    };
+}