@fungi.computer/oyster 0.0.0-stage → 0.1.0

package/dist/computer-terminal.js

@@ -0,0 +1,410 @@
+import { AppError } from "@fungi.computer/agar";
+import { computerTerminalInformationSchema, } from "@fungi.computer/agar/computer";
+import { LONG, nanoid } from "@fungi.computer/cairn";
+import { RpcTarget } from "@fungi.computer/capnweb";
+import * as Schema from "effect/Schema";
+import * as SchemaTransformation from "effect/SchemaTransformation";
+const terminalControlEventSchema = Schema.Union([
+    Schema.Struct({
+        type: Schema.Literal("ready"),
+        information: computerTerminalInformationSchema,
+    }),
+    Schema.Struct({ type: Schema.Literals(["exit", "error"]) }),
+]);
+const terminalFrameSchema = Schema.Union([
+    Schema.fromJsonString(terminalControlEventSchema),
+    Schema.instanceOf(ArrayBuffer),
+    Schema.instanceOf(Blob),
+    Schema.instanceOf(Uint8Array),
+]);
+const decodeTerminalFrame = Schema.decodeUnknownSync(terminalFrameSchema);
+const terminalFailureSchema = Schema.toType(Schema.Defect()).pipe(Schema.decodeTo(Schema.String, SchemaTransformation.transform({
+    decode: (failure) => String(failure),
+    encode: (message) => message,
+})));
+const decodeTerminalFailure = Schema.decodeUnknownSync(terminalFailureSchema);
+const terminalSizeSchema = Schema.Struct({
+    cols: Schema.Number.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isBetween({ minimum: 2, maximum: 500 }))),
+    rows: Schema.Number.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isBetween({ minimum: 2, maximum: 300 }))),
+});
+const decodeTerminalSize = Schema.decodeUnknownSync(terminalSizeSchema);
+const decodeTerminalInput = Schema.decodeUnknownSync(Schema.instanceOf(Uint8Array));
+class ComputerTerminalHostImplementation extends RpcTarget {
+    #sessions = new Set();
+    #terminalUrl;
+    #computerId;
+    #connectSocket;
+    #hostWindow;
+    #ensureAccess;
+    #mountSignal;
+    #abort = () => {
+        this[Symbol.dispose]();
+    };
+    #disposed = false;
+    constructor(options) {
+        super();
+        this.#terminalUrl = options.terminalUrl;
+        this.#computerId = options.computerId;
+        this.#connectSocket = options.connect;
+        this.#hostWindow = options.hostWindow;
+        this.#ensureAccess = options.ensureAccess;
+        this.#mountSignal = options.mountSignal;
+        this.#mountSignal?.addEventListener("abort", this.#abort, { once: true });
+        if (this.#mountSignal?.aborted)
+            this.#abort();
+    }
+    /** Open an admitted PTY and retain its session across transport reconnects. */
+    async open(size) {
+        if (this.#disposed)
+            throw new Error("App Computer terminal is closed");
+        const session = new ComputerTerminalSession({
+            terminalUrl: this.#terminalUrl,
+            computerId: this.#computerId,
+            connect: this.#connectSocket,
+            hostWindow: this.#hostWindow,
+            ensureAccess: this.#ensureAccess,
+            mountSignal: this.#mountSignal,
+            release: (terminal) => {
+                this.#sessions.delete(terminal);
+            },
+        });
+        this.#sessions.add(session);
+        try {
+            await session.start(decodeTerminalSize(size));
+            return session;
+        }
+        catch (error) {
+            session[Symbol.dispose]();
+            throw error;
+        }
+    }
+    /** Close every terminal when the App window's host lifetime ends. */
+    [Symbol.dispose]() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        this.#mountSignal?.removeEventListener("abort", this.#abort);
+        for (const session of this.#sessions)
+            session[Symbol.dispose]();
+        this.#sessions.clear();
+    }
+}
+/** Construct the shared terminal owner with host policy and transport edges. */
+export const ComputerTerminalHost = ComputerTerminalHostImplementation;
+class ComputerTerminalSession extends RpcTarget {
+    #controller = new AbortController();
+    #abort = () => {
+        this[Symbol.dispose]();
+    };
+    #release;
+    #hostWindow;
+    #computerId;
+    #connectSocket;
+    #ensureAccess;
+    #mountSignal;
+    #output;
+    #input;
+    #outputController;
+    #inputController;
+    #terminalUrl;
+    #sessionId = nanoid(LONG);
+    #size = { cols: 80, rows: 24 };
+    #socket;
+    #connectPromise;
+    #accessPromise;
+    #retryTimer;
+    #leaseTimer;
+    // A refused peer session must never extend this session's admitted lease.
+    #leaseExpiresAt;
+    #attempt = 0;
+    #sawOutput = false;
+    #deadShell = false;
+    #closed = false;
+    #outputDone = false;
+    #information;
+    #informationWait;
+    #resolveInformation;
+    #rejectInformation;
+    constructor(options) {
+        super();
+        this.#terminalUrl = options.terminalUrl;
+        this.#computerId = options.computerId;
+        this.#connectSocket = options.connect;
+        this.#hostWindow = options.hostWindow;
+        this.#ensureAccess = options.ensureAccess;
+        this.#mountSignal = options.mountSignal;
+        this.#release = options.release;
+        this.#output = new ReadableStream({
+            start: (controller) => {
+                this.#outputController = controller;
+            },
+            cancel: () => {
+                this.#outputDone = true;
+                return this.close();
+            },
+        });
+        this.#input = new WritableStream({
+            start: (controller) => {
+                this.#inputController = controller;
+            },
+            write: (chunk) => this.#write(chunk),
+            close: () => this.close(),
+            abort: () => this.close(),
+        });
+        this.#mountSignal?.addEventListener("abort", this.#abort, { once: true });
+        if (this.#mountSignal?.aborted)
+            this.#abort();
+    }
+    async start(size) {
+        this.#size = size;
+        await this.#connect();
+    }
+    information() {
+        if (this.#closed)
+            return Promise.reject(new Error("Computer terminal is closed"));
+        if (this.#information !== undefined)
+            return Promise.resolve(this.#information);
+        this.#informationWait ??= new Promise((resolve, reject) => {
+            this.#resolveInformation = resolve;
+            this.#rejectInformation = reject;
+        });
+        return this.#informationWait;
+    }
+    output() {
+        if (this.#closed)
+            return Promise.reject(new Error("Computer terminal is closed"));
+        return Promise.resolve(this.#output);
+    }
+    input() {
+        if (this.#closed)
+            return Promise.reject(new Error("Computer terminal is closed"));
+        return Promise.resolve(this.#input);
+    }
+    async resize(size) {
+        const nextSize = decodeTerminalSize(size);
+        await this.#ensureLease();
+        const socket = await this.#readySocket();
+        socket.send(JSON.stringify({ type: "resize", ...nextSize }));
+        this.#size = nextSize;
+    }
+    close() {
+        this[Symbol.dispose]();
+        return Promise.resolve();
+    }
+    [Symbol.dispose]() {
+        this.#shutdown();
+    }
+    async #write(chunk) {
+        const bytes = decodeTerminalInput(chunk);
+        await this.#ensureLease();
+        const socket = await this.#readySocket();
+        socket.send(bytes);
+    }
+    async #readySocket() {
+        while (!this.#closed) {
+            if (this.#socket?.readyState === WebSocket.OPEN)
+                return this.#socket;
+            await (this.#connectPromise ?? this.#connect());
+        }
+        throw new Error("Computer terminal is closed");
+    }
+    #connect() {
+        if (this.#closed)
+            return Promise.reject(new Error("Computer terminal is closed"));
+        if (this.#connectPromise !== undefined)
+            return this.#connectPromise;
+        const connecting = this.#openSocket().finally(() => {
+            if (this.#connectPromise === connecting)
+                this.#connectPromise = undefined;
+        });
+        this.#connectPromise = connecting;
+        return connecting;
+    }
+    async #openSocket() {
+        const configuration = await this.#ensureCurrent();
+        const terminalUrl = configuration.terminalUrl ?? this.#terminalUrl;
+        this.#terminalUrl = terminalUrl;
+        this.#attempt += 1;
+        this.#sawOutput = false;
+        this.#deadShell = false;
+        const socket = this.#connectSocket(terminalUrl, {
+            session: this.#sessionId,
+            ...this.#size,
+        });
+        socket.binaryType = "arraybuffer";
+        this.#socket = socket;
+        socket.addEventListener("message", (event) => {
+            if (this.#closed || socket !== this.#socket)
+                return;
+            try {
+                const frame = decodeTerminalFrame(event.data);
+                void this.#writeOutput(frame).catch((error) => {
+                    this.#fail(decodeTerminalFailure(error));
+                });
+            }
+            catch (error) {
+                this.#fail(decodeTerminalFailure(error));
+            }
+        });
+        socket.addEventListener("close", () => {
+            this.#socketClosed(socket);
+        });
+        socket.addEventListener("error", () => {
+            /* The close event owns reconnect and teardown. */
+        });
+        await new Promise((resolve, reject) => {
+            const onOpen = () => {
+                socket.removeEventListener("open", onOpen);
+                socket.removeEventListener("close", onClose);
+                resolve();
+            };
+            const onClose = () => {
+                socket.removeEventListener("open", onOpen);
+                socket.removeEventListener("close", onClose);
+                reject(new Error("Computer terminal connection closed"));
+            };
+            socket.addEventListener("open", onOpen, { once: true });
+            socket.addEventListener("close", onClose, { once: true });
+        });
+    }
+    async #writeOutput(frame) {
+        if (Schema.is(terminalControlEventSchema)(frame)) {
+            switch (frame.type) {
+                case "ready":
+                    this.#information = frame.information;
+                    this.#resolveInformation?.(frame.information);
+                    this.#resolveInformation = undefined;
+                    this.#rejectInformation = undefined;
+                    return;
+                case "error":
+                    return;
+                case "exit":
+                    this.#deadShell = true;
+                    return;
+            }
+        }
+        let bytes;
+        if (frame instanceof ArrayBuffer)
+            bytes = new Uint8Array(frame);
+        else if (frame instanceof Blob)
+            bytes = new Uint8Array(await frame.arrayBuffer());
+        else
+            bytes = frame;
+        if (this.#closed)
+            return;
+        this.#sawOutput = true;
+        this.#outputController?.enqueue(bytes);
+    }
+    #socketClosed(socket) {
+        if (this.#closed || socket !== this.#socket)
+            return;
+        this.#socket = undefined;
+        if (this.#deadShell || !this.#sawOutput)
+            this.#sessionId = nanoid(LONG);
+        const delay = Math.min(30_000, 3_000 + this.#attempt * 3_000);
+        this.#retryTimer = this.#hostWindow.setTimeout(() => {
+            this.#retryTimer = undefined;
+            void this.#connect().catch((error) => {
+                this.#fail(decodeTerminalFailure(error));
+            });
+        }, delay);
+    }
+    async #ensureLease() {
+        if (this.#closed)
+            throw new Error("Computer terminal is closed");
+        const expiresAt = this.#leaseExpiresAt;
+        if (expiresAt === undefined ||
+            expiresAt === null ||
+            expiresAt <= Date.now())
+            await this.#ensureCurrent();
+    }
+    #ensureCurrent() {
+        if (this.#closed)
+            return Promise.reject(new Error("Computer terminal is closed"));
+        this.#accessPromise ??= this.#checkCurrent()
+            .then((selection) => {
+            this.#scheduleLeaseCheck();
+            return selection;
+        })
+            .finally(() => {
+            this.#accessPromise = undefined;
+        });
+        return this.#accessPromise;
+    }
+    async #checkCurrent() {
+        if (this.#closed)
+            throw new Error("Computer terminal is closed");
+        let configuration;
+        try {
+            configuration = await this.#ensureAccess(this.#controller.signal);
+        }
+        catch (error) {
+            const failure = decodeTerminalFailure(error);
+            this.#fail(failure);
+            throw new Error(failure, { cause: error });
+        }
+        this.#controller.signal.throwIfAborted();
+        if (this.#computerId === null ||
+            configuration.computerId !== this.#computerId) {
+            const error = new AppError("The selected Computer changed. Retry on the original Computer.", { code: "CAPABILITY_DENIED", retryable: false });
+            this.#shutdown(error);
+            throw error;
+        }
+        if (configuration.terminalUrl === null) {
+            const error = new AppError("Computer terminal is unavailable", {
+                code: "CAPABILITY_DENIED",
+                retryable: false,
+            });
+            this.#shutdown(error);
+            throw error;
+        }
+        this.#leaseExpiresAt = this.#ensureAccess.leaseExpiresAt?.();
+        return configuration;
+    }
+    #scheduleLeaseCheck() {
+        if (this.#leaseTimer !== undefined)
+            this.#hostWindow.clearTimeout(this.#leaseTimer);
+        this.#leaseTimer = undefined;
+        if (this.#closed)
+            return;
+        const expiresAt = this.#leaseExpiresAt;
+        if (expiresAt === undefined || expiresAt === null)
+            return;
+        this.#leaseTimer = this.#hostWindow.setTimeout(() => {
+            this.#leaseTimer = undefined;
+            void this.#ensureCurrent().catch((error) => {
+                this.#fail(decodeTerminalFailure(error));
+            });
+        }, Math.max(0, expiresAt - Date.now()));
+    }
+    #fail(message) {
+        this.#shutdown(new Error(message));
+    }
+    #shutdown(error) {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#rejectInformation?.(error ?? new Error("Computer terminal is closed"));
+        this.#rejectInformation = undefined;
+        this.#resolveInformation = undefined;
+        if (error !== undefined) {
+            this.#outputDone = true;
+            this.#outputController?.error(error);
+            this.#inputController?.error(error);
+        }
+        else if (!this.#outputDone) {
+            this.#outputDone = true;
+            this.#outputController?.close();
+        }
+        this.#controller.abort();
+        this.#mountSignal?.removeEventListener("abort", this.#abort);
+        if (this.#retryTimer !== undefined)
+            this.#hostWindow.clearTimeout(this.#retryTimer);
+        if (this.#leaseTimer !== undefined)
+            this.#hostWindow.clearTimeout(this.#leaseTimer);
+        const socket = this.#socket;
+        this.#socket = undefined;
+        socket?.close();
+        this.#release(this);
+    }
+}

package/dist/computer.d.ts

@@ -0,0 +1,60 @@
+export { ComputerTerminalHost, type ComputerTerminalAccess, type ComputerTerminalConnect, type ComputerTerminalHostOptions, type ComputerTerminalSelection, } from "./computer-terminal.js";
+/** Computer routes supplied by the host; execution stays in the Computer runtime. */
+export declare const computerSlots: {
+    readonly ports: {
+        readonly id: string;
+        readonly version: number;
+        readonly base: "/computer/";
+        readonly methods: {
+            readonly list: {
+                readonly kind: "json";
+                readonly method: "GET";
+                readonly path: "ports";
+            };
+            readonly expose: {
+                readonly kind: "json";
+                readonly method: "POST";
+                readonly path: "ports/expose";
+            };
+            readonly unexpose: {
+                readonly kind: "json";
+                readonly method: "POST";
+                readonly path: "ports/unexpose";
+            };
+        };
+    };
+    readonly processes: {
+        readonly id: string;
+        readonly version: number;
+        readonly base: "/computer/";
+        readonly methods: {
+            readonly start: {
+                readonly kind: "json";
+                readonly method: "POST";
+                readonly path: "processes/start";
+            };
+            readonly list: {
+                readonly kind: "json";
+                readonly method: "GET";
+                readonly path: "processes";
+            };
+            readonly kill: {
+                readonly kind: "json";
+                readonly method: "POST";
+                readonly path: "processes/kill";
+            };
+        };
+    };
+    readonly terminal: {
+        readonly id: string;
+        readonly version: number;
+        readonly base: "/computer/";
+        readonly methods: {
+            readonly open: {
+                readonly kind: "transport";
+                readonly method: "GET";
+                readonly path: "terminal";
+            };
+        };
+    };
+};

package/dist/computer.js

@@ -0,0 +1,33 @@
+import { computerPorts, computerProcesses, computerTerminal, } from "@fungi.computer/agar/computer";
+export { ComputerTerminalHost, } from "./computer-terminal.js";
+/** Computer routes supplied by the host; execution stays in the Computer runtime. */
+export const computerSlots = {
+    ports: {
+        id: computerPorts.id,
+        version: computerPorts.version,
+        base: "/computer/",
+        methods: {
+            list: { kind: "json", method: "GET", path: "ports" },
+            expose: { kind: "json", method: "POST", path: "ports/expose" },
+            unexpose: { kind: "json", method: "POST", path: "ports/unexpose" },
+        },
+    },
+    processes: {
+        id: computerProcesses.id,
+        version: computerProcesses.version,
+        base: "/computer/",
+        methods: {
+            start: { kind: "json", method: "POST", path: "processes/start" },
+            list: { kind: "json", method: "GET", path: "processes" },
+            kill: { kind: "json", method: "POST", path: "processes/kill" },
+        },
+    },
+    terminal: {
+        id: computerTerminal.id,
+        version: computerTerminal.version,
+        base: "/computer/",
+        methods: {
+            open: { kind: "transport", method: "GET", path: "terminal" },
+        },
+    },
+};

package/dist/event-recipients.d.ts

@@ -0,0 +1,57 @@
+import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
+/** The emitting installation as the host attested it on the emit's frame. */
+export type HostEventSource = Readonly<{
+    installationId: string;
+    appId: string;
+    releaseId: string;
+}>;
+/** One accepted event, as a host recipient receives it. */
+export type HostRecipientEvent = Readonly<{
+    source: HostEventSource;
+    type: string;
+    eventId: string;
+    payload: Readonly<{
+        type: string;
+        timestamp: string;
+        data: unknown;
+    }>;
+}>;
+/** One recipient's delivery record for one event. */
+export type RecipientDelivery = Readonly<{
+    recipient: string;
+    eventId: string;
+    type: string;
+    state: "pending" | "delivered" | "failed";
+    attempts: number;
+    /** The last failed attempt's host-owned diagnostic, never guest text. */
+    lastError: string | null;
+    updatedAt: number;
+}>;
+/**
+ * Retained D5 baseline: a ten-second attempt bound, and a terminal failure
+ * after six failed attempts (the first plus one per retry delay).
+ */
+export declare const RECIPIENT_ATTEMPT_MS = 10000;
+export declare const RECIPIENT_RETRY_DELAYS_MS: readonly [10000, 60000, 300000, 1800000, 7200000];
+/** The owner's SQLite records, its alarm and the one typed delivery port. */
+export declare function createRecipientDeliveries(options: {
+    sql: WatchdogSqliteOwner["sql"];
+    now(): number;
+    /** Schedule the owner's next drain no later than `at`. */
+    wake(at: number): Promise<void>;
+    /** Deliver one event to one recipient; a rejection is one failed attempt. */
+    deliver(recipient: string, event: HostRecipientEvent): Promise<void>;
+    attemptMs?: number;
+}): {
+    /**
+     * Record one pending row per recipient (idempotent per event id). The
+     * caller commits it with its other rows and then wakes for `now`.
+     */
+    enqueue(event: HostRecipientEvent, recipients: readonly string[]): number;
+    /** Attempt every due row once, record each outcome, and re-arm for the next retry. */
+    drain(): Promise<void>;
+    /** The earliest pending retry, if any. */
+    nextDue: () => number | null;
+    /** Recent deliveries to one recipient, newest first. */
+    deliveries(recipient: string): RecipientDelivery[];
+};