@mostra/worker 0.0.0-placeholder → 0.1.0

package/package.json

@@ -1,7 +1,56 @@
 {
   "name": "@mostra/worker",
-  "version": "0.0.0-placeholder",
-  "description": "Placeholder for Mostra's first release, which publishes through trusted publishing.",
+  "version": "0.1.0",
+  "description": "The process that runs one artifact version's server code: server functions, action runs and live producers.",
   "license": "Apache-2.0",
-  "repository": { "type": "git", "url": "git+https://github.com/mostra-dev/mostra.git" }
-}
+  "author": "The Mostra Authors",
+  "homepage": "https://github.com/mostra-dev/mostra/tree/main/packages/worker#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mostra-dev/mostra.git",
+    "directory": "packages/worker"
+  },
+  "bugs": "https://github.com/mostra-dev/mostra/issues",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "@mostra/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@mostra/protocol": "0.1.0",
+    "@mostra/server": "0.1.0"
+  },
+  "devDependencies": {
+    "@mostra/tools": "0.0.0",
+    "@types/node": "24.19.1",
+    "tsdown": "0.23.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.3"
+  },
+  "bin": {
+    "mostra-worker": "./dist/main.js"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -b",
+    "test": "vitest run",
+    "api": "mostra-tools api"
+  }
+}

package/src/channel-thread.ts

@@ -0,0 +1,127 @@
+/**
+ * The worker's channel thread (D124): owns the connection to the supervisor, so the artifact's
+ * main thread can block on a secret (`secret()` is synchronous, INTERFACES §2.4) while the reply
+ * still arrives, and so the watchdog's ping is answered from what the main thread last wrote into
+ * shared memory, which is how a blocked event loop shows (D62). Every other line passes through to
+ * the main thread unchanged.
+ */
+import { connect, Socket } from "node:net";
+import { parentPort, workerData } from "node:worker_threads";
+import { encodeLine, LineSplitter, WORKER_METHODS } from "@mostra/protocol";
+import { SECRET_SLOT, type SharedState, sharedViews } from "./shared.ts";
+
+interface ThreadData {
+  readonly channel: string;
+  readonly shared: SharedState;
+}
+
+const data = workerData as ThreadData;
+const port = parentPort;
+if (!port) throw new Error("The channel thread runs only as a worker thread.");
+const views = sharedViews(data.shared);
+
+function open(channel: string): Socket {
+  if (channel.startsWith("fd:")) {
+    const socket = new Socket({ fd: Number(channel.slice(3)), readable: true, writable: true });
+    return socket;
+  }
+  if (channel.startsWith("unix:")) return connect(channel.slice(5));
+  throw new Error(`Unknown channel ${channel}.`);
+}
+
+const socket = open(data.channel);
+const splitter = new LineSplitter();
+let nextSecret = 1;
+let pendingSecret: string | undefined;
+
+function write(line: string): void {
+  socket.write(line);
+}
+
+function deliverSecret(status: "ok" | "error", text: string): void {
+  const bytes = new TextEncoder().encode(text);
+  const length = Math.min(bytes.length, views.secretBytes.length);
+  views.secretBytes.set(bytes.subarray(0, length));
+  Atomics.store(views.control, SECRET_SLOT.length, length);
+  Atomics.store(views.control, SECRET_SLOT.status, status === "ok" ? 0 : 1);
+  Atomics.store(views.control, SECRET_SLOT.state, 2);
+  Atomics.notify(views.control, SECRET_SLOT.state);
+}
+
+function onLine(line: string): void {
+  let message: { id?: unknown; method?: unknown; result?: unknown; error?: unknown } | undefined;
+  try {
+    message = JSON.parse(line) as typeof message;
+  } catch {
+    message = undefined;
+  }
+  if (message && message.method === WORKER_METHODS.ping && message.id !== undefined) {
+    const now = Date.now();
+    const beat = Number(Atomics.load(views.beat, 0));
+    const waiting = Atomics.load(views.control, SECRET_SLOT.state) === 1;
+    write(
+      encodeLine({
+        jsonrpc: "2.0",
+        id: message.id as string,
+        result: {
+          blockedMs: waiting ? 0 : Math.max(0, now - beat),
+          waitingForSecret: waiting,
+          heapUsed: Number(Atomics.load(views.beat, 1)),
+        },
+      }),
+    );
+    return;
+  }
+  if (message && typeof message.id === "string" && message.id === pendingSecret) {
+    pendingSecret = undefined;
+    if (message.error !== undefined) {
+      const error = message.error as {
+        data?: { code?: string; message?: string };
+        message?: string;
+      };
+      deliverSecret(
+        "error",
+        JSON.stringify({
+          code: error.data?.code ?? "MOSTRA_SECRET_MISSING",
+          message: error.data?.message ?? error.message ?? "The secret could not be read.",
+        }),
+      );
+    } else {
+      deliverSecret(
+        "ok",
+        typeof message.result === "object" && message.result !== null
+          ? String((message.result as { value?: unknown }).value ?? "")
+          : "",
+      );
+    }
+    return;
+  }
+  port?.postMessage({ type: "line", line });
+}
+
+socket.setEncoding("utf8");
+socket.on("data", (chunk: string) => {
+  for (const line of splitter.push(chunk)) onLine(line);
+});
+const closed = (): void => port?.postMessage({ type: "closed" });
+socket.on("end", closed);
+socket.on("close", closed);
+socket.on("error", closed);
+
+port.on("message", (message: { type: string; line?: string; name?: string }) => {
+  if (message.type === "line" && message.line !== undefined) write(message.line);
+  else if (message.type === "secret" && message.name !== undefined) {
+    const id = `secret-${nextSecret++}`;
+    pendingSecret = id;
+    write(
+      encodeLine({
+        jsonrpc: "2.0",
+        id,
+        method: WORKER_METHODS.secret,
+        params: { name: message.name },
+      }),
+    );
+  } else if (message.type === "end") {
+    socket.end();
+  }
+});

package/src/index.ts

@@ -0,0 +1,22 @@
+/**
+ * `@mostra/worker`: the process that runs one artifact version's server code (ARCHITECTURE §7,
+ * RT-03). The supervisor starts it through a `WorkerLauncher` (D124) and speaks the worker channel
+ * of `@mostra/protocol` to it; nothing imports it as a library except launchers that need its
+ * entry point.
+ *
+ * ```ts
+ * import { workerEntry } from "@mostra/worker";
+ * spawn(process.execPath, [workerEntry(), "--channel", "unix:/tmp/w.sock", "--version-dir", dir]);
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { fileURLToPath } from "node:url";
+
+export { runWorker, type WorkerOptions } from "./worker.ts";
+
+/** The absolute path of the worker's process entry, `main.js` (or `main.ts` from source). */
+export function workerEntry(): string {
+  const extension = import.meta.url.endsWith(".ts") ? ".ts" : ".js";
+  return fileURLToPath(new URL(`./main${extension}`, import.meta.url));
+}

package/src/main.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * `@mostra/worker`'s process entry (`dist/main.js`): `main.js --channel fd:4|unix:<path>
+ * --version-dir <dir> [--source-dir <dir>] [--modules <node_modules>]`. A launcher starts it for one artifact version
+ * (D124); the first request on the channel is `worker/start`.
+ */
+import { parseArgs } from "node:util";
+import { runWorker } from "./worker.ts";
+
+const { values } = parseArgs({
+  options: {
+    channel: { type: "string" },
+    "version-dir": { type: "string" },
+    "source-dir": { type: "string" },
+    modules: { type: "string" },
+  },
+  strict: true,
+});
+if (!values.channel || !values["version-dir"]) {
+  process.stderr.write(
+    "usage: main.js --channel fd:<n>|unix:<path> --version-dir <dir> [--source-dir <dir>] [--modules <node_modules>]\n",
+  );
+  process.exit(2);
+}
+await runWorker({
+  channel: values.channel,
+  versionDir: values["version-dir"],
+  ...(values["source-dir"] ? { sourceDir: values["source-dir"] } : {}),
+  ...(values.modules ? { modules: values.modules } : {}),
+});

package/src/shared.ts

@@ -0,0 +1,50 @@
+/**
+ * The memory the worker's main thread and its channel thread share: the event loop's heartbeat,
+ * the heap in use, and one slot for a synchronous secret read.
+ */
+
+/** Where a secret read stands, in `control`. */
+export const SECRET_SLOT = {
+  /** 0 idle, 1 the main thread waits, 2 the answer is in `secretBytes`. */
+  state: 0,
+  /** The answer's length in bytes. */
+  length: 1,
+  /** 0 the value, 1 a JSON `{ code, message }` error. */
+  status: 2,
+} as const;
+
+/** The largest secret answer the slot holds: a 64 KiB value, or an error. */
+const SECRET_BYTES = 256 * 1024;
+
+/** The shared buffers, as they cross to the channel thread. */
+export interface SharedState {
+  readonly control: SharedArrayBuffer;
+  readonly beat: SharedArrayBuffer;
+  readonly secret: SharedArrayBuffer;
+}
+
+/** Typed views of the shared buffers. */
+export interface SharedViews {
+  readonly control: Int32Array;
+  /** `[0]`: the last heartbeat, in ms since the epoch; `[1]`: the heap in use, in bytes. */
+  readonly beat: BigInt64Array;
+  readonly secretBytes: Uint8Array;
+}
+
+/** Allocates the shared buffers. */
+export function createSharedState(): SharedState {
+  return {
+    control: new SharedArrayBuffer(4 * 4),
+    beat: new SharedArrayBuffer(8 * 2),
+    secret: new SharedArrayBuffer(SECRET_BYTES),
+  };
+}
+
+/** The typed views of `state`. */
+export function sharedViews(state: SharedState): SharedViews {
+  return {
+    control: new Int32Array(state.control),
+    beat: new BigInt64Array(state.beat),
+    secretBytes: new Uint8Array(state.secret),
+  };
+}