@earendil-works/chord 1.5.0 → 1.5.1

package/dist/node/workers/index.js

@@ -0,0 +1,7 @@
+// Chord v2's workers component (`@earendil-works/chord/workers`, slice 10 §3, §4): a forked worker process per
+// address of a host kind, started on demand, stopped when idle, never restarted by itself, its plugins shipped from the
+// server; `workerMain` is the worker's side (also `@earendil-works/chord/workers/child`, without esbuild). Node-only.
+export { nodeBaseInputs } from "./base.js";
+export * from "./child.js";
+export { createWorkers, } from "./workers.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/node/workers/index.ts"],"names":[],"mappings":"AAAA,+GAA+G;AAC/G,wHAAwH;AACxH,sHAAsH;AAEtH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,cAAc,YAAY,CAAC;AAC3B,OAAO,EACN,aAAa,GAMb,MAAM,cAAc,CAAC","sourcesContent":["// Chord v2's workers component (`@earendil-works/chord/workers`, slice 10 §3, §4): a forked worker process per\n// address of a host kind, started on demand, stopped when idle, never restarted by itself, its plugins shipped from the\n// server; `workerMain` is the worker's side (also `@earendil-works/chord/workers/child`, without esbuild). Node-only.\n\nexport { nodeBaseInputs } from \"./base.ts\";\nexport * from \"./child.ts\";\nexport {\n\tcreateWorkers,\n\ttype WorkerState,\n\ttype Workers,\n\ttype WorkersBuilt,\n\ttype WorkersError,\n\ttype WorkersOptions,\n} from \"./workers.ts\";\n"]}

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

@@ -0,0 +1,30 @@
+import type { Context } from "../../context/index.ts";
+/** A held lock: `release` frees it (the process's exit does too). */
+export type ProcessLock = {
+    release(): Promise<void>;
+};
+/** Where a lock lives: an abstract socket (Linux, Android), a named pipe (Windows) or a socket file (elsewhere). */
+export type LockAddress = {
+    readonly kind: "abstract" | "pipe" | "file";
+    readonly address: string;
+};
+/**
+ * Takes the lock `name`, waiting while another process holds it (until `context` aborts: rejects with its reason).
+ * Throws what listening throws besides "in use", and for a stale socket file (macOS, the BSDs) an error naming it.
+ */
+export declare function processLock(name: string, context: Context): Promise<ProcessLock>;
+/**
+ * Removes the socket file of the lock `name` when nobody accepts on it (a holder killed without its exit hooks left
+ * it); resolves with whether it did. Abstract sockets and named pipes end with their holder: nothing to clear. Only one
+ * process clears a name, one clear at a time: two clearers could both find it stale, one remove it, a new holder take
+ * it, and the other remove the new holder's file.
+ */
+export declare function clearStaleLock(name: string, context: Context): Promise<boolean>;
+/** `clearStaleLock` at `lock`: a socket file nobody accepts on is removed. */
+export declare function clearStaleLockAt(lock: LockAddress, context: Context): Promise<boolean>;
+/**
+ * Takes the lock at `lock`, waiting while it is held. A socket file nobody accepts on (a crashed holder's) fails closed:
+ * taking it over races another taker (two could both unlink and listen), so the error names the file to remove.
+ */
+export declare function lockAt(lock: LockAddress, context: Context): Promise<ProcessLock>;
+//# sourceMappingURL=lock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../../src/node/workers/lock.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAEtD,qEAAqE;AACrE,MAAM,MAAM,WAAW,GAAG;IAAE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC;AAEvD,oHAAoH;AACpH,MAAM,MAAM,WAAW,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpG;;;GAGG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,CAEtF;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAErF;AAYD,8EAA8E;AAC9E,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAU5F;AAiBD;;;GAGG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,CAmCtF"}

package/dist/node/workers/lock.js

@@ -0,0 +1,180 @@
+// Process locks (slice 10 §3): one live worker per address. A lock is a listening socket the
+// kernel owns for the holder's lifetime (an abstract socket on Linux and Android, a named pipe on Windows, a socket file
+// elsewhere), so there is no race between two would-be holders; a socket file a crashed holder left fails closed for a
+// taker (the error names it: a takeover would race another taker), and only the one process that starts the holders of
+// a name clears it (decision "Stale lock files are cleared by the starter"). A child finding the lock held waits
+// without polling: it connects to the holder's socket, which the holder never answers, and tries again when that
+// connection closes (the holder exited).
+import { createHash } from "node:crypto";
+import { unlinkSync } from "node:fs";
+import { lstat, mkdir, unlink } from "node:fs/promises";
+import { connect, createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/**
+ * Takes the lock `name`, waiting while another process holds it (until `context` aborts: rejects with its reason).
+ * Throws what listening throws besides "in use", and for a stale socket file (macOS, the BSDs) an error naming it.
+ */
+export async function processLock(name, context) {
+    return lockAt(await lockAddress(name), context);
+}
+/**
+ * Removes the socket file of the lock `name` when nobody accepts on it (a holder killed without its exit hooks left
+ * it); resolves with whether it did. Abstract sockets and named pipes end with their holder: nothing to clear. Only one
+ * process clears a name, one clear at a time: two clearers could both find it stale, one remove it, a new holder take
+ * it, and the other remove the new holder's file.
+ */
+export async function clearStaleLock(name, context) {
+    return clearStaleLockAt(await lockAddress(name), context);
+}
+/** Where the lock `name` lives on this platform. */
+async function lockAddress(name) {
+    const key = createHash("sha256").update(name).digest("hex").slice(0, 32);
+    if (process.platform === "win32")
+        return { kind: "pipe", address: `\\\\.\\pipe\\chord-lock-${key}` };
+    if (process.platform === "linux" || process.platform === "android") {
+        return { kind: "abstract", address: `\0chord-lock-${key}` };
+    }
+    return { kind: "file", address: await socketPath(`chord-lock-${key}.sock`) };
+}
+/** `clearStaleLock` at `lock`: a socket file nobody accepts on is removed. */
+export async function clearStaleLockAt(lock, context) {
+    context.abortSignal?.throwIfAborted();
+    if (lock.kind !== "file" || !(await nobodyAccepts(lock.address)))
+        return false;
+    try {
+        await unlink(lock.address);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+/** A connect's errors that mean nobody accepts on the path: a socket file nobody listens on, or no socket there. */
+const NOBODY_ACCEPTS = new Set(["ECONNREFUSED", "ENOTSOCK"]);
+/** Whether the path `address` exists and nobody accepts on it. */
+function nobodyAccepts(address) {
+    return new Promise((resolve) => {
+        const socket = connect(address);
+        socket.once("connect", () => {
+            socket.destroy();
+            resolve(false);
+        });
+        socket.once("error", (error) => resolve(NOBODY_ACCEPTS.has(error.code ?? "")));
+    });
+}
+/**
+ * Takes the lock at `lock`, waiting while it is held. A socket file nobody accepts on (a crashed holder's) fails closed:
+ * taking it over races another taker (two could both unlink and listen), so the error names the file to remove.
+ */
+export async function lockAt(lock, context) {
+    const { address } = lock;
+    const file = lock.kind === "file";
+    // Connections are kept open, never answered: a waiter learns of the release when its connection closes.
+    const waiters = new Set();
+    const server = createServer((socket) => {
+        waiters.add(socket);
+        socket.on("error", () => { });
+        socket.once("close", () => waiters.delete(socket));
+    });
+    for (;;) {
+        context.abortSignal?.throwIfAborted();
+        if (await listened(server, address))
+            break;
+        const held = await waitWhileHeld(address, context);
+        if (!held && file) {
+            throw new Error(`lock: ${address} is a stale lock file (no process holds it); remove it if no worker runs`);
+        }
+    }
+    const removeFile = () => {
+        try {
+            unlinkSync(address);
+        }
+        catch {
+            // Gone already.
+        }
+    };
+    if (file)
+        process.once("exit", removeFile);
+    return {
+        release: () => new Promise((resolve, reject) => {
+            if (file)
+                process.removeListener("exit", removeFile);
+            server.close((error) => (error ? reject(error) : resolve()));
+            // Waiters see their connections close (and `close` waits for them).
+            for (const socket of waiters)
+                socket.destroy();
+        }),
+    };
+}
+/** Whether `server` now listens on `address`; `false` when it is in use. */
+function listened(server, address) {
+    return new Promise((resolve, reject) => {
+        const failed = (error) => {
+            if (error.code === "EADDRINUSE")
+                resolve(false);
+            else
+                reject(error);
+        };
+        server.once("error", failed);
+        server.listen(address, () => {
+            server.removeListener("error", failed);
+            resolve(true);
+        });
+    });
+}
+/**
+ * Connects to the holder of `address` and resolves when that connection closes or the address is gone (`true`: try
+ * again), or with `false` when nobody accepts on it (a leftover socket file); `context`'s abort rejects.
+ */
+function waitWhileHeld(address, context) {
+    return new Promise((resolve, reject) => {
+        const signal = context.abortSignal;
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const socket = connect(address);
+        const abort = () => {
+            socket.destroy();
+            reject(signal?.reason);
+        };
+        signal?.addEventListener("abort", abort, { once: true });
+        const settle = (held) => {
+            signal?.removeEventListener("abort", abort);
+            resolve(held);
+        };
+        let connected = false;
+        socket.once("connect", () => {
+            connected = true;
+        });
+        socket.on("error", (error) => {
+            // A regular file at the path is ENOTSOCK on macOS (ECONNREFUSED on Linux); retrying would spin.
+            if (!connected && NOBODY_ACCEPTS.has(error.code ?? ""))
+                settle(false);
+        });
+        socket.once("close", () => settle(true));
+    });
+}
+/** sun_path holds 104 bytes on macOS and the BSDs, the terminating NUL included. */
+const MAX_SOCKET_PATH_BYTES = 103;
+/**
+ * A lock socket's path: in the temporary directory, or, when that does not fit in sun_path (a deep TMPDIR), in a
+ * private per-user directory under /tmp that only its owner can reach.
+ */
+async function socketPath(file) {
+    const preferred = join(tmpdir(), file);
+    if (Buffer.byteLength(preferred) <= MAX_SOCKET_PATH_BYTES)
+        return preferred;
+    const uid = process.getuid?.() ?? 0;
+    const directory = `/tmp/chord-lock-${uid}`;
+    await mkdir(directory, { mode: 0o700, recursive: true });
+    const stats = await lstat(directory);
+    if (!stats.isDirectory() || stats.uid !== uid || (stats.mode & 0o077) !== 0) {
+        throw new Error(`lock directory ${directory} must be a directory only its owner can access`);
+    }
+    return join(directory, file);
+}
+//# sourceMappingURL=lock.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../../src/node/workers/lock.ts"],"names":[],"mappings":"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","sourcesContent":["// Process locks (slice 10 §3): one live worker per address. A lock is a listening socket the\n// kernel owns for the holder's lifetime (an abstract socket on Linux and Android, a named pipe on Windows, a socket file\n// elsewhere), so there is no race between two would-be holders; a socket file a crashed holder left fails closed for a\n// taker (the error names it: a takeover would race another taker), and only the one process that starts the holders of\n// a name clears it (decision \"Stale lock files are cleared by the starter\"). A child finding the lock held waits\n// without polling: it connects to the holder's socket, which the holder never answers, and tries again when that\n// connection closes (the holder exited).\n\nimport { createHash } from \"node:crypto\";\nimport { unlinkSync } from \"node:fs\";\nimport { lstat, mkdir, unlink } from \"node:fs/promises\";\nimport { connect, createServer, type Server, type Socket } from \"node:net\";\nimport { tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport type { Context } from \"../../context/index.ts\";\n\n/** A held lock: `release` frees it (the process's exit does too). */\nexport type ProcessLock = { release(): Promise<void> };\n\n/** Where a lock lives: an abstract socket (Linux, Android), a named pipe (Windows) or a socket file (elsewhere). */\nexport type LockAddress = { readonly kind: \"abstract\" | \"pipe\" | \"file\"; readonly address: string };\n\n/**\n * Takes the lock `name`, waiting while another process holds it (until `context` aborts: rejects with its reason).\n * Throws what listening throws besides \"in use\", and for a stale socket file (macOS, the BSDs) an error naming it.\n */\nexport async function processLock(name: string, context: Context): Promise<ProcessLock> {\n\treturn lockAt(await lockAddress(name), context);\n}\n\n/**\n * Removes the socket file of the lock `name` when nobody accepts on it (a holder killed without its exit hooks left\n * it); resolves with whether it did. Abstract sockets and named pipes end with their holder: nothing to clear. Only one\n * process clears a name, one clear at a time: two clearers could both find it stale, one remove it, a new holder take\n * it, and the other remove the new holder's file.\n */\nexport async function clearStaleLock(name: string, context: Context): Promise<boolean> {\n\treturn clearStaleLockAt(await lockAddress(name), context);\n}\n\n/** Where the lock `name` lives on this platform. */\nasync function lockAddress(name: string): Promise<LockAddress> {\n\tconst key = createHash(\"sha256\").update(name).digest(\"hex\").slice(0, 32);\n\tif (process.platform === \"win32\") return { kind: \"pipe\", address: `\\\\\\\\.\\\\pipe\\\\chord-lock-${key}` };\n\tif (process.platform === \"linux\" || process.platform === \"android\") {\n\t\treturn { kind: \"abstract\", address: `\\0chord-lock-${key}` };\n\t}\n\treturn { kind: \"file\", address: await socketPath(`chord-lock-${key}.sock`) };\n}\n\n/** `clearStaleLock` at `lock`: a socket file nobody accepts on is removed. */\nexport async function clearStaleLockAt(lock: LockAddress, context: Context): Promise<boolean> {\n\tcontext.abortSignal?.throwIfAborted();\n\tif (lock.kind !== \"file\" || !(await nobodyAccepts(lock.address))) return false;\n\ttry {\n\t\tawait unlink(lock.address);\n\t\treturn true;\n\t} catch (error) {\n\t\tif ((error as NodeJS.ErrnoException).code === \"ENOENT\") return false;\n\t\tthrow error;\n\t}\n}\n\n/** A connect's errors that mean nobody accepts on the path: a socket file nobody listens on, or no socket there. */\nconst NOBODY_ACCEPTS = new Set([\"ECONNREFUSED\", \"ENOTSOCK\"]);\n\n/** Whether the path `address` exists and nobody accepts on it. */\nfunction nobodyAccepts(address: string): Promise<boolean> {\n\treturn new Promise<boolean>((resolve) => {\n\t\tconst socket = connect(address);\n\t\tsocket.once(\"connect\", () => {\n\t\t\tsocket.destroy();\n\t\t\tresolve(false);\n\t\t});\n\t\tsocket.once(\"error\", (error: NodeJS.ErrnoException) => resolve(NOBODY_ACCEPTS.has(error.code ?? \"\")));\n\t});\n}\n\n/**\n * Takes the lock at `lock`, waiting while it is held. A socket file nobody accepts on (a crashed holder's) fails closed:\n * taking it over races another taker (two could both unlink and listen), so the error names the file to remove.\n */\nexport async function lockAt(lock: LockAddress, context: Context): Promise<ProcessLock> {\n\tconst { address } = lock;\n\tconst file = lock.kind === \"file\";\n\t// Connections are kept open, never answered: a waiter learns of the release when its connection closes.\n\tconst waiters = new Set<Socket>();\n\tconst server = createServer((socket) => {\n\t\twaiters.add(socket);\n\t\tsocket.on(\"error\", () => {});\n\t\tsocket.once(\"close\", () => waiters.delete(socket));\n\t});\n\tfor (;;) {\n\t\tcontext.abortSignal?.throwIfAborted();\n\t\tif (await listened(server, address)) break;\n\t\tconst held = await waitWhileHeld(address, context);\n\t\tif (!held && file) {\n\t\t\tthrow new Error(`lock: ${address} is a stale lock file (no process holds it); remove it if no worker runs`);\n\t\t}\n\t}\n\tconst removeFile = (): void => {\n\t\ttry {\n\t\t\tunlinkSync(address);\n\t\t} catch {\n\t\t\t// Gone already.\n\t\t}\n\t};\n\tif (file) process.once(\"exit\", removeFile);\n\treturn {\n\t\trelease: () =>\n\t\t\tnew Promise<void>((resolve, reject) => {\n\t\t\t\tif (file) process.removeListener(\"exit\", removeFile);\n\t\t\t\tserver.close((error) => (error ? reject(error) : resolve()));\n\t\t\t\t// Waiters see their connections close (and `close` waits for them).\n\t\t\t\tfor (const socket of waiters) socket.destroy();\n\t\t\t}),\n\t};\n}\n\n/** Whether `server` now listens on `address`; `false` when it is in use. */\nfunction listened(server: Server, address: string): Promise<boolean> {\n\treturn new Promise<boolean>((resolve, reject) => {\n\t\tconst failed = (error: NodeJS.ErrnoException): void => {\n\t\t\tif (error.code === \"EADDRINUSE\") resolve(false);\n\t\t\telse reject(error);\n\t\t};\n\t\tserver.once(\"error\", failed);\n\t\tserver.listen(address, () => {\n\t\t\tserver.removeListener(\"error\", failed);\n\t\t\tresolve(true);\n\t\t});\n\t});\n}\n\n/**\n * Connects to the holder of `address` and resolves when that connection closes or the address is gone (`true`: try\n * again), or with `false` when nobody accepts on it (a leftover socket file); `context`'s abort rejects.\n */\nfunction waitWhileHeld(address: string, context: Context): Promise<boolean> {\n\treturn new Promise<boolean>((resolve, reject) => {\n\t\tconst signal = context.abortSignal;\n\t\tif (signal?.aborted) {\n\t\t\treject(signal.reason);\n\t\t\treturn;\n\t\t}\n\t\tconst socket = connect(address);\n\t\tconst abort = (): void => {\n\t\t\tsocket.destroy();\n\t\t\treject(signal?.reason);\n\t\t};\n\t\tsignal?.addEventListener(\"abort\", abort, { once: true });\n\t\tconst settle = (held: boolean): void => {\n\t\t\tsignal?.removeEventListener(\"abort\", abort);\n\t\t\tresolve(held);\n\t\t};\n\t\tlet connected = false;\n\t\tsocket.once(\"connect\", () => {\n\t\t\tconnected = true;\n\t\t});\n\t\tsocket.on(\"error\", (error: NodeJS.ErrnoException) => {\n\t\t\t// A regular file at the path is ENOTSOCK on macOS (ECONNREFUSED on Linux); retrying would spin.\n\t\t\tif (!connected && NOBODY_ACCEPTS.has(error.code ?? \"\")) settle(false);\n\t\t});\n\t\tsocket.once(\"close\", () => settle(true));\n\t});\n}\n\n/** sun_path holds 104 bytes on macOS and the BSDs, the terminating NUL included. */\nconst MAX_SOCKET_PATH_BYTES = 103;\n\n/**\n * A lock socket's path: in the temporary directory, or, when that does not fit in sun_path (a deep TMPDIR), in a\n * private per-user directory under /tmp that only its owner can reach.\n */\nasync function socketPath(file: string): Promise<string> {\n\tconst preferred = join(tmpdir(), file);\n\tif (Buffer.byteLength(preferred) <= MAX_SOCKET_PATH_BYTES) return preferred;\n\tconst uid = process.getuid?.() ?? 0;\n\tconst directory = `/tmp/chord-lock-${uid}`;\n\tawait mkdir(directory, { mode: 0o700, recursive: true });\n\tconst stats = await lstat(directory);\n\tif (!stats.isDirectory() || stats.uid !== uid || (stats.mode & 0o077) !== 0) {\n\t\tthrow new Error(`lock directory ${directory} must be a directory only its owner can access`);\n\t}\n\treturn join(directory, file);\n}\n"]}

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

@@ -0,0 +1,46 @@
+import { type Context } from "../../context/index.ts";
+import type { Address } from "../../contracts/index.ts";
+import type { Principal } from "../../data/index.ts";
+import type { Host, LoadReport, PluginFacet } from "../../host/index.ts";
+import type { JsonValue } from "../../json.ts";
+import { type Link } from "../../link/index.ts";
+import type { Watchable } from "../../watch.ts";
+import type { HostPackages } from "../plugins/evaluate.ts";
+import { type CrossedError } from "./control.ts";
+/** What the app's function gets. */
+export type WorkerStart = {
+    readonly address: Address;
+    /** The start data the server's `start(address)` gave. */
+    readonly start: JsonValue;
+    /** The link to the server: `connect` it before anything slow (`started` goes out then). */
+    readonly parent: Link;
+    readonly plugins: WorkerPlugins;
+    /** Registers a closer: closers run in reverse order at shutdown. */
+    onClose(closer: (context: Context) => Promise<void> | void): void;
+};
+/** The worker's plugins: the shipped scripts of its kind, loaded on its host; the server's reloads applied to it. */
+export interface WorkerPlugins {
+    /** Loads `host` with the start message's scripts of `kind` and `core` (the app's own facets). */
+    load<P extends Principal>(host: Host<P>, options: {
+        readonly kind: string;
+        readonly core: readonly PluginFacet<P>[];
+    }, context: Context): Promise<LoadReport>;
+}
+/** What the app's function returns: extra keep-alive counts (busy while any is nonzero). */
+export type WorkerResult = {
+    readonly busy?: Watchable<Readonly<Record<string, number>>>;
+};
+/** What `workerMain` takes besides the app's function. */
+export type WorkerMainOptions = {
+    /** The host packages by specifier: this process's own instances (functions cannot cross IPC). */
+    readonly hostPackages: HostPackages;
+    /** What crosses as `fatal` for an error (never the original message unless this returns it). */
+    readonly redact: (error: unknown) => CrossedError;
+    readonly onError: (error: unknown) => void;
+};
+/**
+ * Runs this process as a worker: `fn` once the start message arrived and the lock is taken. An uncaught error or a
+ * throwing `fn` sends `fatal` (redacted) and exits.
+ */
+export declare function workerMain(fn: (start: WorkerStart, context: Context) => Promise<WorkerResult | undefined>, options: WorkerMainOptions): void;
+//# sourceMappingURL=main.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/node/workers/main.ts"],"names":[],"mappings":"AAKA,OAAO,EAAsB,KAAK,OAAO,EAAmB,MAAM,wBAAwB,CAAC;AAC3F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAgB,MAAM,qBAAqB,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAyB,KAAK,IAAI,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EACN,KAAK,YAAY,EAOjB,MAAM,cAAc,CAAC;AAGtB,oCAAoC;AACpC,MAAM,MAAM,WAAW,GAAG;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,oEAAoE;IACpE,OAAO,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;CAClE,CAAC;AAEF,qHAAqH;AACrH,MAAM,WAAW,aAAa;IAC7B,iGAAiG;IACjG,IAAI,CAAC,CAAC,SAAS,SAAS,EACvB,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EACb,OAAO,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,CAAC,CAAC,CAAC,EAAE,CAAA;KAAE,EAC5E,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,UAAU,CAAC,CAAC;CACvB;AAED,4FAA4F;AAC5F,MAAM,MAAM,YAAY,GAAG;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC;AAE3F,0DAA0D;AAC1D,MAAM,MAAM,iBAAiB,GAAG;IAC/B,iGAAiG;IACjG,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,gGAAgG;IAChG,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,YAAY,CAAC;IAClD,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,UAAU,CACzB,EAAE,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,EAC/E,OAAO,EAAE,iBAAiB,GACxB,IAAI,CAGN"}

package/dist/node/workers/main.js

@@ -0,0 +1,230 @@
+// The worker's side (slice 10 §3): `workerMain` reads the start message, takes the address's lock, makes the link to
+// the server (`started` goes out when the app's host listens on it), runs the app's function with a plugin runtime over
+// the shipped scripts, reports `ready` and each idle flip, applies reloads, and on `shutdown`, the parent's disconnect,
+// `SIGTERM` or `SIGINT` aborts its context, runs the app's closers in reverse order and exits.
+import { BACKGROUND_CONTEXT, withAbortSignal } from "../../context/index.js";
+import { ipcLink } from "../../link/index.js";
+import { createPluginRuntime } from "../plugins/runtime.js";
+import { controlOf, crossed, crossedReport, envelope, } from "./control.js";
+import { processLock } from "./lock.js";
+/**
+ * Runs this process as a worker: `fn` once the start message arrived and the lock is taken. An uncaught error or a
+ * throwing `fn` sends `fatal` (redacted) and exits.
+ */
+export function workerMain(fn, options) {
+    // `process` is the IPC port of a forked child.
+    new Worker(process, options).run(fn);
+}
+/** How long a shutdown's closers get before the worker exits anyway: 3 s. */
+const FORCED_EXIT = 3_000;
+class Worker {
+    #port;
+    #options;
+    #controller = new AbortController();
+    #context;
+    #closers = [];
+    #start = Promise.withResolvers();
+    /** Reloads that arrived, applied one after another once `fn` returned. */
+    #reloads = [];
+    #loaded;
+    #ready = false;
+    #reloading = false;
+    #busy;
+    /** The last idle state sent. */
+    #idle;
+    #stopping = false;
+    constructor(port, options) {
+        this.#port = port;
+        this.#options = options;
+        this.#context = withAbortSignal(this.#controller.signal, BACKGROUND_CONTEXT);
+        port.on("message", (message) => this.#message(controlOf(message)));
+        port.on("disconnect", () => void this.#shutdown());
+        for (const signal of ["SIGTERM", "SIGINT"])
+            process.once(signal, () => void this.#shutdown());
+        process.once("uncaughtException", (error) => this.#fatal(error));
+        process.once("unhandledRejection", (error) => this.#fatal(error));
+    }
+    /** Takes the lock, makes the parent link, runs `fn`, then reports `ready` and applies reloads. */
+    run(fn) {
+        // A throw while shutting down is the shutdown's own cancellation (its `ctx` aborted): no fatal, the closers run.
+        void this.#run(fn).catch((error) => {
+            if (!this.#stopping)
+                this.#fatal(error);
+        });
+    }
+    async #run(fn) {
+        const message = await this.#start.promise;
+        await processLock(message.lock, this.#context);
+        const parent = new ParentLink(ipcLink(this.#port), () => this.#send({ kind: "started" }));
+        const runtime = createPluginRuntime();
+        const plugins = {
+            load: async (host, { kind, core }, context) => {
+                this.#loaded = { host: host, runtime };
+                return runtime.load(host, { kind, core, scripts: message.scripts, modules: this.#options.hostPackages }, context);
+            },
+        };
+        let report = { failed: [] };
+        const loading = {
+            load: async (host, options, context) => {
+                report = await plugins.load(host, options, context);
+                return report;
+            },
+        };
+        const start = {
+            address: message.address,
+            start: message.start,
+            parent,
+            plugins: loading,
+            onClose: (closer) => void this.#closers.push(closer),
+        };
+        const result = await fn(start, this.#context);
+        if (this.#stopping)
+            return;
+        this.#busy = result?.busy;
+        await this.#follow();
+        this.#ready = true;
+        const failed = new Set(report.failed.map(({ plugin }) => plugin));
+        const added = message.scripts.map(({ plugin }) => plugin.name).filter((name) => !failed.has(name));
+        const loaded = { plugins: { added, changed: [], removed: [] }, failed: report.failed, objects: [] };
+        this.#idle = this.#isIdle();
+        this.#send({ kind: "ready", idle: this.#idle, report: crossedReport(loaded) });
+        void this.#applyReloads();
+    }
+    /** Follows the host's activity and the app's `busy`: each idle flip is reported. */
+    async #follow() {
+        const sources = [];
+        if (this.#loaded !== undefined)
+            sources.push(this.#loaded.host.activity);
+        if (this.#busy !== undefined)
+            sources.push(this.#busy);
+        for (const source of sources) {
+            const watch = await source.watch(this.#context);
+            watch.start(async () => this.#flip());
+        }
+    }
+    /** Whether every count is zero: the host's references, jobs and lingering objects, the app's `busy`, no reload. */
+    #isIdle() {
+        if (this.#reloading)
+            return false;
+        const activity = this.#loaded?.host.activity.value;
+        if (activity !== undefined && activity.references + activity.jobs + activity.lingering > 0)
+            return false;
+        return Object.values(this.#busy?.value ?? {}).every((count) => count === 0);
+    }
+    /** Reports the idle state when it flipped (after `ready`). */
+    #flip() {
+        if (!this.#ready)
+            return;
+        const idle = this.#isIdle();
+        if (idle === this.#idle)
+            return;
+        this.#idle = idle;
+        this.#send({ kind: "idle", idle });
+    }
+    /** A control message from the server. */
+    #message(message) {
+        if (message === undefined)
+            return;
+        switch (message.kind) {
+            case "start":
+                this.#start.resolve(message);
+                return;
+            case "shutdown":
+                void this.#shutdown();
+                return;
+            case "reload":
+                // A worker shutting down applies no reload (its exit answers it).
+                if (this.#stopping)
+                    return;
+                this.#reloads.push(message.scripts);
+                if (this.#ready)
+                    void this.#applyReloads();
+        }
+    }
+    /** Applies the reloads that arrived, one after another, each answered `reloaded`. */
+    async #applyReloads() {
+        if (this.#reloading || this.#reloads.length === 0)
+            return;
+        const loaded = this.#loaded;
+        this.#reloading = true;
+        this.#flip();
+        for (let scripts = this.#reloads.shift(); scripts !== undefined && !this.#stopping; scripts = this.#reloads.shift()) {
+            if (loaded === undefined) {
+                this.#send({ kind: "reloaded", error: { message: "worker: plugins.load was never called" } });
+                continue;
+            }
+            try {
+                const report = await loaded.runtime.reload(loaded.host, scripts, this.#context);
+                this.#send({ kind: "reloaded", report: crossedReport(report) });
+            }
+            catch (error) {
+                this.#send({ kind: "reloaded", error: crossed(error) });
+            }
+        }
+        this.#reloading = false;
+        this.#flip();
+    }
+    /** Aborts the context, runs the closers in reverse order and exits (forced after 3 s). */
+    async #shutdown() {
+        if (this.#stopping)
+            return;
+        this.#stopping = true;
+        this.#controller.abort(new Error("worker: shutting down"));
+        setTimeout(() => process.exit(0), FORCED_EXIT).unref();
+        const context = BACKGROUND_CONTEXT;
+        for (const closer of this.#closers.reverse()) {
+            try {
+                await closer(context);
+            }
+            catch (error) {
+                this.#options.onError(error);
+            }
+        }
+        process.exit(0);
+    }
+    /** Sends `fatal` with the redacted error, then exits. */
+    #fatal(error) {
+        this.#options.onError(error);
+        let redacted;
+        try {
+            redacted = this.#options.redact(error);
+        }
+        catch {
+            redacted = { message: "worker: fatal error" };
+        }
+        if (!this.#port.connected)
+            process.exit(1);
+        // `process.send` takes a callback once the message is out.
+        process.send(envelope({ kind: "fatal", error: redacted }), () => process.exit(1));
+    }
+    /** Sends a control message; dropped when the server is gone. */
+    #send(message) {
+        if (this.#port.connected)
+            process.send?.(envelope(message), undefined, undefined, () => { });
+    }
+}
+/** The link to the server as the app gets it: `started` goes out when the app's host sets its listener (`connect`). */
+class ParentLink {
+    #inner;
+    #started;
+    constructor(inner, started) {
+        this.#inner = inner;
+        this.#started = started;
+    }
+    send(message) {
+        this.#inner.send(message);
+    }
+    onMessage(listener) {
+        this.#inner.onMessage(listener);
+        const started = this.#started;
+        this.#started = undefined;
+        started?.();
+    }
+    close() {
+        this.#inner.close();
+    }
+    onClose(listener) {
+        this.#inner.onClose(listener);
+    }
+}
+//# sourceMappingURL=main.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../../src/node/workers/main.ts"],"names":[],"mappings":"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","sourcesContent":["// The worker's side (slice 10 §3): `workerMain` reads the start message, takes the address's lock, makes the link to\n// the server (`started` goes out when the app's host listens on it), runs the app's function with a plugin runtime over\n// the shipped scripts, reports `ready` and each idle flip, applies reloads, and on `shutdown`, the parent's disconnect,\n// `SIGTERM` or `SIGINT` aborts its context, runs the app's closers in reverse order and exits.\n\nimport { BACKGROUND_CONTEXT, type Context, withAbortSignal } from \"../../context/index.ts\";\nimport type { Address } from \"../../contracts/index.ts\";\nimport type { Principal } from \"../../data/index.ts\";\nimport type { Host, LoadReport, PluginFacet, ReloadReport } from \"../../host/index.ts\";\nimport type { JsonValue } from \"../../json.ts\";\nimport { type IpcPort, ipcLink, type Link } from \"../../link/index.ts\";\nimport type { Watchable } from \"../../watch.ts\";\nimport type { HostPackages } from \"../plugins/evaluate.ts\";\nimport { createPluginRuntime, type PluginScript } from \"../plugins/runtime.ts\";\nimport {\n\ttype CrossedError,\n\tcontrolOf,\n\tcrossed,\n\tcrossedReport,\n\tenvelope,\n\ttype FromWorker,\n\ttype ToWorker,\n} from \"./control.ts\";\nimport { processLock } from \"./lock.ts\";\n\n/** What the app's function gets. */\nexport type WorkerStart = {\n\treadonly address: Address;\n\t/** The start data the server's `start(address)` gave. */\n\treadonly start: JsonValue;\n\t/** The link to the server: `connect` it before anything slow (`started` goes out then). */\n\treadonly parent: Link;\n\treadonly plugins: WorkerPlugins;\n\t/** Registers a closer: closers run in reverse order at shutdown. */\n\tonClose(closer: (context: Context) => Promise<void> | void): void;\n};\n\n/** The worker's plugins: the shipped scripts of its kind, loaded on its host; the server's reloads applied to it. */\nexport interface WorkerPlugins {\n\t/** Loads `host` with the start message's scripts of `kind` and `core` (the app's own facets). */\n\tload<P extends Principal>(\n\t\thost: Host<P>,\n\t\toptions: { readonly kind: string; readonly core: readonly PluginFacet<P>[] },\n\t\tcontext: Context,\n\t): Promise<LoadReport>;\n}\n\n/** What the app's function returns: extra keep-alive counts (busy while any is nonzero). */\nexport type WorkerResult = { readonly busy?: Watchable<Readonly<Record<string, number>>> };\n\n/** What `workerMain` takes besides the app's function. */\nexport type WorkerMainOptions = {\n\t/** The host packages by specifier: this process's own instances (functions cannot cross IPC). */\n\treadonly hostPackages: HostPackages;\n\t/** What crosses as `fatal` for an error (never the original message unless this returns it). */\n\treadonly redact: (error: unknown) => CrossedError;\n\treadonly onError: (error: unknown) => void;\n};\n\n/**\n * Runs this process as a worker: `fn` once the start message arrived and the lock is taken. An uncaught error or a\n * throwing `fn` sends `fatal` (redacted) and exits.\n */\nexport function workerMain(\n\tfn: (start: WorkerStart, context: Context) => Promise<WorkerResult | undefined>,\n\toptions: WorkerMainOptions,\n): void {\n\t// `process` is the IPC port of a forked child.\n\tnew Worker(process as unknown as IpcPort, options).run(fn);\n}\n\n/** How long a shutdown's closers get before the worker exits anyway: 3 s. */\nconst FORCED_EXIT = 3_000;\n\nclass Worker {\n\treadonly #port: IpcPort;\n\treadonly #options: WorkerMainOptions;\n\treadonly #controller = new AbortController();\n\treadonly #context: Context;\n\treadonly #closers: ((context: Context) => Promise<void> | void)[] = [];\n\treadonly #start = Promise.withResolvers<Extract<ToWorker, { readonly kind: \"start\" }>>();\n\t/** Reloads that arrived, applied one after another once `fn` returned. */\n\treadonly #reloads: (readonly PluginScript[])[] = [];\n\t#loaded: { readonly host: Host<Principal>; readonly runtime: ReturnType<typeof createPluginRuntime> } | undefined;\n\t#ready = false;\n\t#reloading = false;\n\t#busy: Watchable<Readonly<Record<string, number>>> | undefined;\n\t/** The last idle state sent. */\n\t#idle: boolean | undefined;\n\t#stopping = false;\n\n\tconstructor(port: IpcPort, options: WorkerMainOptions) {\n\t\tthis.#port = port;\n\t\tthis.#options = options;\n\t\tthis.#context = withAbortSignal(this.#controller.signal, BACKGROUND_CONTEXT);\n\t\tport.on(\"message\", (message) => this.#message(controlOf<ToWorker>(message)));\n\t\tport.on(\"disconnect\", () => void this.#shutdown());\n\t\tfor (const signal of [\"SIGTERM\", \"SIGINT\"] as const) process.once(signal, () => void this.#shutdown());\n\t\tprocess.once(\"uncaughtException\", (error) => this.#fatal(error));\n\t\tprocess.once(\"unhandledRejection\", (error) => this.#fatal(error));\n\t}\n\n\t/** Takes the lock, makes the parent link, runs `fn`, then reports `ready` and applies reloads. */\n\trun(fn: (start: WorkerStart, context: Context) => Promise<WorkerResult | undefined>): void {\n\t\t// A throw while shutting down is the shutdown's own cancellation (its `ctx` aborted): no fatal, the closers run.\n\t\tvoid this.#run(fn).catch((error: unknown) => {\n\t\t\tif (!this.#stopping) this.#fatal(error);\n\t\t});\n\t}\n\n\tasync #run(fn: (start: WorkerStart, context: Context) => Promise<WorkerResult | undefined>): Promise<void> {\n\t\tconst message = await this.#start.promise;\n\t\tawait processLock(message.lock, this.#context);\n\t\tconst parent = new ParentLink(ipcLink(this.#port), () => this.#send({ kind: \"started\" }));\n\t\tconst runtime = createPluginRuntime();\n\t\tconst plugins: WorkerPlugins = {\n\t\t\tload: async (host, { kind, core }, context) => {\n\t\t\t\tthis.#loaded = { host: host as unknown as Host<Principal>, runtime };\n\t\t\t\treturn runtime.load(\n\t\t\t\t\thost,\n\t\t\t\t\t{ kind, core, scripts: message.scripts, modules: this.#options.hostPackages },\n\t\t\t\t\tcontext,\n\t\t\t\t);\n\t\t\t},\n\t\t};\n\t\tlet report: LoadReport = { failed: [] };\n\t\tconst loading: WorkerPlugins = {\n\t\t\tload: async (host, options, context) => {\n\t\t\t\treport = await plugins.load(host, options, context);\n\t\t\t\treturn report;\n\t\t\t},\n\t\t};\n\t\tconst start: WorkerStart = {\n\t\t\taddress: message.address,\n\t\t\tstart: message.start,\n\t\t\tparent,\n\t\t\tplugins: loading,\n\t\t\tonClose: (closer) => void this.#closers.push(closer),\n\t\t};\n\t\tconst result = await fn(start, this.#context);\n\t\tif (this.#stopping) return;\n\t\tthis.#busy = result?.busy;\n\t\tawait this.#follow();\n\t\tthis.#ready = true;\n\t\tconst failed = new Set(report.failed.map(({ plugin }) => plugin));\n\t\tconst added = message.scripts.map(({ plugin }) => plugin.name).filter((name) => !failed.has(name));\n\t\tconst loaded: ReloadReport = { plugins: { added, changed: [], removed: [] }, failed: report.failed, objects: [] };\n\t\tthis.#idle = this.#isIdle();\n\t\tthis.#send({ kind: \"ready\", idle: this.#idle, report: crossedReport(loaded) });\n\t\tvoid this.#applyReloads();\n\t}\n\n\t/** Follows the host's activity and the app's `busy`: each idle flip is reported. */\n\tasync #follow(): Promise<void> {\n\t\tconst sources: Watchable<unknown>[] = [];\n\t\tif (this.#loaded !== undefined) sources.push(this.#loaded.host.activity);\n\t\tif (this.#busy !== undefined) sources.push(this.#busy);\n\t\tfor (const source of sources) {\n\t\t\tconst watch = await source.watch(this.#context);\n\t\t\twatch.start(async () => this.#flip());\n\t\t}\n\t}\n\n\t/** Whether every count is zero: the host's references, jobs and lingering objects, the app's `busy`, no reload. */\n\t#isIdle(): boolean {\n\t\tif (this.#reloading) return false;\n\t\tconst activity = this.#loaded?.host.activity.value;\n\t\tif (activity !== undefined && activity.references + activity.jobs + activity.lingering > 0) return false;\n\t\treturn Object.values(this.#busy?.value ?? {}).every((count) => count === 0);\n\t}\n\n\t/** Reports the idle state when it flipped (after `ready`). */\n\t#flip(): void {\n\t\tif (!this.#ready) return;\n\t\tconst idle = this.#isIdle();\n\t\tif (idle === this.#idle) return;\n\t\tthis.#idle = idle;\n\t\tthis.#send({ kind: \"idle\", idle });\n\t}\n\n\t/** A control message from the server. */\n\t#message(message: ToWorker | undefined): void {\n\t\tif (message === undefined) return;\n\t\tswitch (message.kind) {\n\t\t\tcase \"start\":\n\t\t\t\tthis.#start.resolve(message);\n\t\t\t\treturn;\n\t\t\tcase \"shutdown\":\n\t\t\t\tvoid this.#shutdown();\n\t\t\t\treturn;\n\t\t\tcase \"reload\":\n\t\t\t\t// A worker shutting down applies no reload (its exit answers it).\n\t\t\t\tif (this.#stopping) return;\n\t\t\t\tthis.#reloads.push(message.scripts);\n\t\t\t\tif (this.#ready) void this.#applyReloads();\n\t\t}\n\t}\n\n\t/** Applies the reloads that arrived, one after another, each answered `reloaded`. */\n\tasync #applyReloads(): Promise<void> {\n\t\tif (this.#reloading || this.#reloads.length === 0) return;\n\t\tconst loaded = this.#loaded;\n\t\tthis.#reloading = true;\n\t\tthis.#flip();\n\t\tfor (\n\t\t\tlet scripts = this.#reloads.shift();\n\t\t\tscripts !== undefined && !this.#stopping;\n\t\t\tscripts = this.#reloads.shift()\n\t\t) {\n\t\t\tif (loaded === undefined) {\n\t\t\t\tthis.#send({ kind: \"reloaded\", error: { message: \"worker: plugins.load was never called\" } });\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\ttry {\n\t\t\t\tconst report = await loaded.runtime.reload(loaded.host, scripts, this.#context);\n\t\t\t\tthis.#send({ kind: \"reloaded\", report: crossedReport(report) });\n\t\t\t} catch (error) {\n\t\t\t\tthis.#send({ kind: \"reloaded\", error: crossed(error) });\n\t\t\t}\n\t\t}\n\t\tthis.#reloading = false;\n\t\tthis.#flip();\n\t}\n\n\t/** Aborts the context, runs the closers in reverse order and exits (forced after 3 s). */\n\tasync #shutdown(): Promise<void> {\n\t\tif (this.#stopping) return;\n\t\tthis.#stopping = true;\n\t\tthis.#controller.abort(new Error(\"worker: shutting down\"));\n\t\tsetTimeout(() => process.exit(0), FORCED_EXIT).unref();\n\t\tconst context = BACKGROUND_CONTEXT;\n\t\tfor (const closer of this.#closers.reverse()) {\n\t\t\ttry {\n\t\t\t\tawait closer(context);\n\t\t\t} catch (error) {\n\t\t\t\tthis.#options.onError(error);\n\t\t\t}\n\t\t}\n\t\tprocess.exit(0);\n\t}\n\n\t/** Sends `fatal` with the redacted error, then exits. */\n\t#fatal(error: unknown): void {\n\t\tthis.#options.onError(error);\n\t\tlet redacted: CrossedError;\n\t\ttry {\n\t\t\tredacted = this.#options.redact(error);\n\t\t} catch {\n\t\t\tredacted = { message: \"worker: fatal error\" };\n\t\t}\n\t\tif (!this.#port.connected) process.exit(1);\n\t\t// `process.send` takes a callback once the message is out.\n\t\t(process.send as (message: unknown, callback: () => void) => void)(\n\t\t\tenvelope({ kind: \"fatal\", error: redacted }),\n\t\t\t() => process.exit(1),\n\t\t);\n\t}\n\n\t/** Sends a control message; dropped when the server is gone. */\n\t#send(message: FromWorker): void {\n\t\tif (this.#port.connected) process.send?.(envelope(message), undefined, undefined, () => {});\n\t}\n}\n\n/** The link to the server as the app gets it: `started` goes out when the app's host sets its listener (`connect`). */\nclass ParentLink implements Link {\n\treadonly #inner: Link;\n\t#started: (() => void) | undefined;\n\n\tconstructor(inner: Link, started: () => void) {\n\t\tthis.#inner = inner;\n\t\tthis.#started = started;\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\tconst started = this.#started;\n\t\tthis.#started = undefined;\n\t\tstarted?.();\n\t}\n\n\tclose(): void {\n\t\tthis.#inner.close();\n\t}\n\n\tonClose(listener: () => void): void {\n\t\tthis.#inner.onClose(listener);\n\t}\n}\n"]}

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

@@ -0,0 +1,42 @@
+import type { Link } from "../../link/index.ts";
+import { type FromWorker, type ToWorker } from "./control.ts";
+/** How a worker process is started: the bootstrap options of the workers component. */
+export type ForkOptions = {
+    readonly entry: string;
+    readonly execArgv?: readonly string[];
+    readonly env?: Readonly<Record<string, string>>;
+    /** Its output; without it, mirrored to this process's own. */
+    readonly onOutput?: (stream: "stdout" | "stderr", chunk: Uint8Array) => void;
+};
+/** How a worker process ended. */
+export type Exit = {
+    readonly code: number | null;
+    readonly signal: NodeJS.Signals | null;
+};
+/** What a worker process tells as it happens. */
+export type ProcessEvents = {
+    readonly control: (message: FromWorker) => void;
+    /** Its link was closed by this side (the heartbeat, a protocol error) while the child may live. */
+    readonly linkLost: () => void;
+    /** Its link was closed by the child's side (it exits, or it closed its IPC channel and may live on). */
+    readonly linkClosed: () => void;
+    readonly exited: (exit: Exit) => void;
+};
+/** One forked worker process. */
+export declare class WorkerProcess {
+    #private;
+    readonly pid: number;
+    readonly startedAt: number;
+    /** The link to the child's host, made at the fork. */
+    readonly link: Link;
+    /** Resolves with its exit; every process it spawned is killed then. */
+    readonly exited: Promise<Exit>;
+    constructor(options: ForkOptions, events: ProcessEvents);
+    /** The last bytes it wrote to stderr, if any. */
+    get stderrTail(): string | undefined;
+    /** Sends a control message; dropped when the child is gone (its exit tells). */
+    send(message: ToWorker): void;
+    /** Kills the child and every process it spawned. */
+    kill(): void;
+}
+//# sourceMappingURL=process.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../../src/node/workers/process.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAEhD,OAAO,EAAuB,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAEnF,uFAAuF;AACvF,MAAM,MAAM,WAAW,GAAG;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,EAAE,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;CAC7E,CAAC;AAEF,kCAAkC;AAClC,MAAM,MAAM,IAAI,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAA;CAAE,CAAC;AAE5F,iDAAiD;AACjD,MAAM,MAAM,aAAa,GAAG;IAC3B,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,CAAC;IAChD,mGAAmG;IACnG,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC;IAC9B,wGAAwG;IACxG,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;CACtC,CAAC;AAQF,iCAAiC;AACjC,qBAAa,aAAa;;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,SAAc;IAChC,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAI/B,YAAY,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAmCtD;IAED,iDAAiD;IACjD,IAAI,UAAU,IAAI,MAAM,GAAG,SAAS,CAEnC;IAED,gFAAgF;IAChF,IAAI,CAAC,OAAO,EAAE,QAAQ,GAAG,IAAI,CAE5B;IAED,oDAAoD;IACpD,IAAI,IAAI,IAAI,CAEX;CAWD"}