@earendil-works/chord 1.4.0 → 1.5.1

package/dist/node/workers/process.js

@@ -0,0 +1,125 @@
+// A worker process as the server sees it (slice 10 §3): forked with V8 serialization as a
+// detached process group (the whole tree can be killed), stdout and stderr piped (the stderr tail kept, both mirrored to
+// the server's own when the app takes no output), its IPC link made at the fork so the child's `hello` and early holds
+// are queued, never lost; control messages, the link's close and the exit are told as they happen.
+import { fork } from "node:child_process";
+import { ipcLink } from "../../link/index.js";
+import { controlOf, envelope } from "./control.js";
+/** How much of a worker's stderr is kept for its failure: 4 KiB. */
+const STDERR_TAIL = 4096;
+/** A control message to a child that is gone: dropped (its exit or link close tells). */
+const ignoreSendError = () => { };
+/** One forked worker process. */
+export class WorkerProcess {
+    pid;
+    startedAt = Date.now();
+    /** The link to the child's host, made at the fork. */
+    link;
+    /** Resolves with its exit; every process it spawned is killed then. */
+    exited;
+    #child;
+    #stderr = "";
+    constructor(options, events) {
+        const child = fork(options.entry, [], {
+            env: { ...process.env, ...options.env },
+            execArgv: [...(options.execArgv ?? [])],
+            detached: true,
+            serialization: "advanced",
+            stdio: ["ignore", "pipe", "pipe", "ipc"],
+        });
+        this.#child = child;
+        this.pid = child.pid ?? -1;
+        for (const stream of ["stdout", "stderr"]) {
+            child[stream]?.on("data", (chunk) => {
+                if (stream === "stderr")
+                    this.#stderr = (this.#stderr + chunk.toString("utf8")).slice(-STDERR_TAIL);
+                if (options.onOutput !== undefined)
+                    options.onOutput(stream, chunk);
+                else
+                    process[stream].write(chunk);
+            });
+        }
+        this.link = new TellingLink(ipcLink(child), events);
+        child.on("message", (message) => {
+            const control = controlOf(message);
+            if (control !== undefined)
+                events.control(control);
+        });
+        this.exited = new Promise((resolve) => {
+            const ended = (exit) => {
+                // However the leader ended, nothing it spawned outlives it.
+                this.#killGroup();
+                resolve(exit);
+                events.exited(exit);
+            };
+            child.once("exit", (code, signal) => ended({ code, signal }));
+            // A fork that failed (no `exit` follows).
+            child.once("error", () => {
+                if (child.pid === undefined)
+                    ended({ code: null, signal: null });
+            });
+        });
+    }
+    /** The last bytes it wrote to stderr, if any. */
+    get stderrTail() {
+        return this.#stderr === "" ? undefined : this.#stderr;
+    }
+    /** Sends a control message; dropped when the child is gone (its exit tells). */
+    send(message) {
+        if (this.#child.connected)
+            this.#child.send(envelope(message), ignoreSendError);
+    }
+    /** Kills the child and every process it spawned. */
+    kill() {
+        if (!this.#killGroup())
+            this.#child.kill("SIGKILL");
+    }
+    /** Kills the process group; `false` when there is none. */
+    #killGroup() {
+        try {
+            process.kill(-this.pid, "SIGKILL");
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/** A link that also tells who closed it (`linkLost`: this side, `linkClosed`: the child's), whoever listens to it. */
+class TellingLink {
+    #inner;
+    #events;
+    #listener;
+    #closed = false;
+    constructor(inner, events) {
+        this.#inner = inner;
+        this.#events = events;
+        inner.onClose(() => {
+            const here = this.#closed;
+            this.#closed = true;
+            this.#listener?.();
+            if (!here)
+                events.linkClosed();
+        });
+    }
+    send(message) {
+        this.#inner.send(message);
+    }
+    onMessage(listener) {
+        this.#inner.onMessage(listener);
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#events.linkLost();
+        this.#inner.close();
+    }
+    onClose(listener) {
+        if (this.#closed)
+            listener();
+        else
+            this.#listener = listener;
+    }
+}
+//# sourceMappingURL=process.js.map

package/dist/node/workers/process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.js","sourceRoot":"","sources":["../../../src/node/workers/process.ts"],"names":[],"mappings":"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","sourcesContent":["// A worker process as the server sees it (slice 10 §3): forked with V8 serialization as a\n// detached process group (the whole tree can be killed), stdout and stderr piped (the stderr tail kept, both mirrored to\n// the server's own when the app takes no output), its IPC link made at the fork so the child's `hello` and early holds\n// are queued, never lost; control messages, the link's close and the exit are told as they happen.\n\nimport { type ChildProcess, fork } from \"node:child_process\";\nimport type { Link } from \"../../link/index.ts\";\nimport { ipcLink } from \"../../link/index.ts\";\nimport { controlOf, envelope, type FromWorker, type ToWorker } from \"./control.ts\";\n\n/** How a worker process is started: the bootstrap options of the workers component. */\nexport type ForkOptions = {\n\treadonly entry: string;\n\treadonly execArgv?: readonly string[];\n\treadonly env?: Readonly<Record<string, string>>;\n\t/** Its output; without it, mirrored to this process's own. */\n\treadonly onOutput?: (stream: \"stdout\" | \"stderr\", chunk: Uint8Array) => void;\n};\n\n/** How a worker process ended. */\nexport type Exit = { readonly code: number | null; readonly signal: NodeJS.Signals | null };\n\n/** What a worker process tells as it happens. */\nexport type ProcessEvents = {\n\treadonly control: (message: FromWorker) => void;\n\t/** Its link was closed by this side (the heartbeat, a protocol error) while the child may live. */\n\treadonly linkLost: () => void;\n\t/** Its link was closed by the child's side (it exits, or it closed its IPC channel and may live on). */\n\treadonly linkClosed: () => void;\n\treadonly exited: (exit: Exit) => void;\n};\n\n/** How much of a worker's stderr is kept for its failure: 4 KiB. */\nconst STDERR_TAIL = 4096;\n\n/** A control message to a child that is gone: dropped (its exit or link close tells). */\nconst ignoreSendError = (): void => {};\n\n/** One forked worker process. */\nexport class WorkerProcess {\n\treadonly pid: number;\n\treadonly startedAt = Date.now();\n\t/** The link to the child's host, made at the fork. */\n\treadonly link: Link;\n\t/** Resolves with its exit; every process it spawned is killed then. */\n\treadonly exited: Promise<Exit>;\n\treadonly #child: ChildProcess;\n\t#stderr = \"\";\n\n\tconstructor(options: ForkOptions, events: ProcessEvents) {\n\t\tconst child = fork(options.entry, [], {\n\t\t\tenv: { ...process.env, ...options.env },\n\t\t\texecArgv: [...(options.execArgv ?? [])],\n\t\t\tdetached: true,\n\t\t\tserialization: \"advanced\",\n\t\t\tstdio: [\"ignore\", \"pipe\", \"pipe\", \"ipc\"],\n\t\t});\n\t\tthis.#child = child;\n\t\tthis.pid = child.pid ?? -1;\n\t\tfor (const stream of [\"stdout\", \"stderr\"] as const) {\n\t\t\tchild[stream]?.on(\"data\", (chunk: Buffer) => {\n\t\t\t\tif (stream === \"stderr\") this.#stderr = (this.#stderr + chunk.toString(\"utf8\")).slice(-STDERR_TAIL);\n\t\t\t\tif (options.onOutput !== undefined) options.onOutput(stream, chunk);\n\t\t\t\telse process[stream].write(chunk);\n\t\t\t});\n\t\t}\n\t\tthis.link = new TellingLink(ipcLink(child), events);\n\t\tchild.on(\"message\", (message: unknown) => {\n\t\t\tconst control = controlOf<FromWorker>(message);\n\t\t\tif (control !== undefined) events.control(control);\n\t\t});\n\t\tthis.exited = new Promise<Exit>((resolve) => {\n\t\t\tconst ended = (exit: Exit): void => {\n\t\t\t\t// However the leader ended, nothing it spawned outlives it.\n\t\t\t\tthis.#killGroup();\n\t\t\t\tresolve(exit);\n\t\t\t\tevents.exited(exit);\n\t\t\t};\n\t\t\tchild.once(\"exit\", (code, signal) => ended({ code, signal }));\n\t\t\t// A fork that failed (no `exit` follows).\n\t\t\tchild.once(\"error\", () => {\n\t\t\t\tif (child.pid === undefined) ended({ code: null, signal: null });\n\t\t\t});\n\t\t});\n\t}\n\n\t/** The last bytes it wrote to stderr, if any. */\n\tget stderrTail(): string | undefined {\n\t\treturn this.#stderr === \"\" ? undefined : this.#stderr;\n\t}\n\n\t/** Sends a control message; dropped when the child is gone (its exit tells). */\n\tsend(message: ToWorker): void {\n\t\tif (this.#child.connected) this.#child.send(envelope(message), ignoreSendError);\n\t}\n\n\t/** Kills the child and every process it spawned. */\n\tkill(): void {\n\t\tif (!this.#killGroup()) this.#child.kill(\"SIGKILL\");\n\t}\n\n\t/** Kills the process group; `false` when there is none. */\n\t#killGroup(): boolean {\n\t\ttry {\n\t\t\tprocess.kill(-this.pid, \"SIGKILL\");\n\t\t\treturn true;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n}\n\n/** A link that also tells who closed it (`linkLost`: this side, `linkClosed`: the child's), whoever listens to it. */\nclass TellingLink implements Link {\n\treadonly #inner: Link;\n\treadonly #events: Pick<ProcessEvents, \"linkLost\" | \"linkClosed\">;\n\t#listener: (() => void) | undefined;\n\t#closed = false;\n\n\tconstructor(inner: Link, events: Pick<ProcessEvents, \"linkLost\" | \"linkClosed\">) {\n\t\tthis.#inner = inner;\n\t\tthis.#events = events;\n\t\tinner.onClose(() => {\n\t\t\tconst here = this.#closed;\n\t\t\tthis.#closed = true;\n\t\t\tthis.#listener?.();\n\t\t\tif (!here) events.linkClosed();\n\t\t});\n\t}\n\n\tsend(message: Uint8Array): void {\n\t\tthis.#inner.send(message);\n\t}\n\n\tonMessage(listener: (message: Uint8Array) => void): void {\n\t\tthis.#inner.onMessage(listener);\n\t}\n\n\tclose(): void {\n\t\tif (this.#closed) return;\n\t\tthis.#closed = true;\n\t\tthis.#events.linkLost();\n\t\tthis.#inner.close();\n\t}\n\n\tonClose(listener: () => void): void {\n\t\tif (this.#closed) listener();\n\t\telse this.#listener = listener;\n\t}\n}\n"]}

package/dist/node/workers/workers.d.ts

@@ -0,0 +1,122 @@
+import type { Context } from "../../context/index.ts";
+import type { Address, HostKind, KindShape } from "../../contracts/index.ts";
+import type { Params } from "../../contracts/internal.ts";
+import { type Principal } from "../../data/index.ts";
+import type { Host } from "../../host/index.ts";
+import type { JsonValue } from "../../json.ts";
+import { type BatchError } from "../../state/internal.ts";
+import type { Watchable } from "../../watch.ts";
+import type { BaseInputs } from "../plugins/base-inputs.ts";
+import type { Plugins, RolloutStep } from "../plugins/plugins.ts";
+import { type CrossedError } from "./control.ts";
+/** What `createWorkers` takes. `kind`, `entry`, `execArgv` and `env` are bootstrap; the functions are called per use. */
+export type WorkersOptions<P extends Principal, K extends KindShape> = {
+    /** The facet kind its workers load (`"worker"`), shipped by the plugins component. */
+    readonly kind: string;
+    /**
+     * The worker's entry module (it calls `workerMain`), bundled with the base code it imports by `build`; its Node flags
+     * (their `--conditions` resolve the bundle's imports too) and its environment.
+     */
+    readonly entry: string;
+    readonly execArgv?: readonly string[];
+    readonly env?: Readonly<Record<string, string>>;
+    /**
+     * The private directory the worker base's files are written into at the first fork, its own while the component is
+     * open (emptied first, removed at `close`; never touched after it, so a later start may own it then): one that stays
+     * the same between starts lets Node's compile cache know them; none: a new temporary directory.
+     */
+    readonly baseDir?: string;
+    /**
+     * Node's compile cache for the workers (`NODE_COMPILE_CACHE` in their environment unless `env` sets it): forks load
+     * the base and the packages it imports from compiled code; none: the server's environment decides.
+     */
+    readonly compileCache?: string;
+    /** The route's `authorize`: whether `principal` may reach `address` (synchronous). */
+    readonly authorize: (principal: P, address: Address<K>) => boolean;
+    /** Who the worker at `address` is (stamped on its link). */
+    readonly principal: (address: Address<K>) => P;
+    /** The worker's start data (JSON), before each start; abortable (`close`), a throw fails the start. */
+    readonly start: (address: Address<K>, context: Context) => Promise<JsonValue> | JsonValue;
+    /** The lock one live worker of `address` holds (across processes). */
+    readonly lock: (address: Address<K>) => string;
+    /** How long a worker idles before it is stopped: 5 minutes by default. */
+    readonly idleMs?: () => number;
+    readonly plugins: Plugins;
+    /** A worker's output; without it, mirrored to this process's own. */
+    readonly onOutput?: (address: Address<K>, stream: "stdout" | "stderr", chunk: Uint8Array) => void;
+    readonly onError: (error: WorkersError) => void;
+};
+/**
+ * One address's worker (R5): running or on its way, or failed (until `retry` or a rollout) with a public error: a fixed
+ * message (`worker failed to start`, `worker exited (SIGSEGV)`) or the child's redacted `fatal`.
+ */
+export type WorkerState = {
+    readonly status: "starting" | "running" | "stopping";
+    readonly pid: number;
+    readonly startedAt: number;
+} | {
+    readonly status: "failed";
+    readonly error: CrossedError;
+    readonly at: number;
+};
+/** What the component reports (and the state's watch listeners that threw). */
+export type WorkersError = {
+    readonly kind: "worker_failed";
+    readonly address: string;
+    /** The full error (a start's throw, a crash, the child's `fatal`): for the app's logs, never public. */
+    readonly error: unknown;
+    readonly stderrTail?: string;
+} | {
+    /** The app's `authorize` threw: the hold is refused (`forbidden`), the error stays private. */
+    readonly kind: "authorize_failed";
+    readonly address: string;
+    readonly error: unknown;
+} | {
+    readonly kind: "worker_exited";
+    readonly address: string;
+    readonly code: number | null;
+    readonly signal: string | null;
+} | {
+    /** A running worker's link was lost (the heartbeat, a protocol error): it was stopped, its holders start anew. */
+    readonly kind: "worker_link_lost";
+    readonly address: string;
+    readonly error: unknown;
+} | BatchError;
+/** How a worker base's build ended: built (the files it read), or failed (esbuild's failure). */
+export type WorkersBuilt = {
+    readonly kind: "built";
+    readonly inputs: BaseInputs;
+} | {
+    readonly kind: "failed";
+    readonly error: unknown;
+};
+/** The workers component. */
+export interface Workers<K extends KindShape> {
+    /** Per address key its `WorkerState`; no entry when stopped or never started. A JSON watchable. */
+    readonly state: Watchable<Readonly<Record<string, WorkerState>>>;
+    /**
+     * Bundles the worker base, once (a start waits for it, and starts it when nothing did). Never rejects: how it ended
+     * (`built`: the files it was built from with their bytes' hashes, the app's base code for its workers). Every start
+     * fails while it failed.
+     */
+    build(): Promise<WorkersBuilt>;
+    /** How the build ended, once it did. */
+    readonly built: WorkersBuilt | undefined;
+    /** Suspends `address` while it has holders (`RouteHandle.suspend`), then stops its worker. */
+    stop(address: Address<K>, context: Context): Promise<void>;
+    /** Clears `address`'s failure and suspension: it starts again now if held (`RouteHandle.retry`). */
+    retry(address: Address<K>, context: Context): Promise<void>;
+    /** A rollout step shipping the kind's current set to every worker, one result per worker (§4). */
+    step(name: string): RolloutStep;
+    /**
+     * Cancels starts, stops every worker, then removes the worker base's files once every worker exited (also when
+     * `context` ends the wait first); new starts reject `released/closed`.
+     */
+    close(context: Context): Promise<void>;
+}
+/**
+ * Creates the workers component on `host`: it routes `Kind` itself (`host.route`, before `load`). Its worker base is
+ * not built yet (`build`).
+ */
+export declare function createWorkers<P extends Principal, N extends string, Q extends Params>(host: Host<P>, Kind: HostKind<N, Q>, options: WorkersOptions<P, HostKind<N, Q>>, context: Context): Workers<HostKind<N, Q>>;
+//# sourceMappingURL=workers.d.ts.map

package/dist/node/workers/workers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workers.d.ts","sourceRoot":"","sources":["../../../src/node/workers/workers.ts"],"names":[],"mappings":"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"}