@cfasim-ui/wasm 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfasim-ui/wasm",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "description": "WebAssembly integration for cfasim-ui",
   "license": "Apache-2.0",
@@ -20,7 +20,7 @@
     "./vite": "./src/vitePlugin.js"
   },
   "dependencies": {
-    "@cfasim-ui/shared": "0.10.0"
+    "@cfasim-ui/shared": "0.11.0"
   },
   "peerDependencies": {
     "vue": "^3.5.0"

package/src/wasm.worker.ts

@@ -1,12 +1,22 @@
+// Subpath imports keep Vue out of the worker: the package barrel re-exports
+// `useUrlParams`, which imports it.
 import {
   postWithTransfer,
   postModelOutputsWithTransfer,
   postErrorWithTransfer,
 } from "@cfasim-ui/shared/transfer";
+import type { WasmTrapKind } from "@cfasim-ui/shared/transfer";
+import {
+  describeWasmTrap,
+  describeWasmInitTrap,
+  isWasmTrap,
+} from "@cfasim-ui/shared/workerError";
 import type { WorkerMessage } from "./messages.js";
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-const modulePromises = new Map<string, Promise<Record<string, any>>>();
+type WasmModule = Record<string, any>;
+
+const modulePromises = new Map<string, Promise<WasmModule>>();
 
 const baseUrl = import.meta.env.BASE_URL ?? "/";
 
@@ -19,8 +29,7 @@ function wasmVersion(model: string): string | undefined {
   return __CFASIM_WASM_VERSIONS__?.[model];
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function ensureModule(model: string): Promise<Record<string, any>> {
+function ensureModule(model: string): Promise<WasmModule> {
   if (!modulePromises.has(model)) {
     const promise = (async () => {
       const dir = `${self.location.origin}${baseUrl}wasm/${model}/`;
@@ -35,6 +44,9 @@ function ensureModule(model: string): Promise<Record<string, any>> {
       } else {
         await mod.default();
       }
+      // cfasim-model's panic recorder (releases after 0.10.0). Installed after
+      // init so it chains onto any hook the model's start function set.
+      mod.__cfasim_install_panic_hook?.();
       return mod;
     })();
     promise.catch(() => {
@@ -47,9 +59,10 @@ function ensureModule(model: string): Promise<Record<string, any>> {
 
 self.onmessage = async (event: MessageEvent<WorkerMessage>) => {
   const { id, model, fn, args } = event.data;
+  let mod: WasmModule | undefined;
   try {
     const t0 = performance.now();
-    const mod = await ensureModule(model);
+    mod = await ensureModule(model);
     const result = mod[fn](...args);
     const elapsed = Math.round((performance.now() - t0) * 10) / 10;
     console.log(`[wasm-worker] ${model}.${fn} ${elapsed}ms`);
@@ -81,6 +94,33 @@ self.onmessage = async (event: MessageEvent<WorkerMessage>) => {
       postWithTransfer(self, id, result);
     }
   } catch (error) {
-    postErrorWithTransfer(self, id, error);
+    if (!isWasmTrap(error)) {
+      const text = error instanceof Error ? error.message : String(error);
+      console.error(`[wasm-worker] ${model}.${fn} failed: ${text}`, error);
+      postErrorWithTransfer(self, id, error);
+      return;
+    }
+    // The instance is unusable after a trap: a panic does not unwind, so
+    // destructors never ran, and the glue keeps a half-initialized instance
+    // when init trapped. The main thread replaces the worker on `trap`.
+    const trapMessage = (error as Error).message;
+    let message: string;
+    let trap: WasmTrapKind;
+    if (mod) {
+      const takePanic = mod.__cfasim_take_panic;
+      let panic: string | undefined;
+      try {
+        panic = takePanic?.() as string | undefined;
+      } catch {
+        // Reading the string allocates, which can trap again after an OOM.
+      }
+      message = describeWasmTrap(trapMessage, panic, !!takePanic);
+      trap = "call";
+    } else {
+      message = describeWasmInitTrap(trapMessage);
+      trap = "init";
+    }
+    console.error(`[wasm-worker] ${model}.${fn} failed: ${message}`, error);
+    postErrorWithTransfer(self, id, new Error(message), { trap });
   }
 };

package/src/wasmWorkerApi.test.ts

@@ -0,0 +1,189 @@
+import { describe, it, expect, vi, beforeAll } from "vitest";
+import type { WorkerMessage } from "./messages.js";
+
+class FakeWorker extends EventTarget {
+  static instances: FakeWorker[] = [];
+  posted: WorkerMessage[] = [];
+  terminated = false;
+
+  constructor() {
+    super();
+    FakeWorker.instances.push(this);
+  }
+
+  postMessage(message: WorkerMessage) {
+    this.posted.push(message);
+  }
+
+  terminate() {
+    this.terminated = true;
+  }
+
+  reply(data: Record<string, unknown>) {
+    this.dispatchEvent(new MessageEvent("message", { data }));
+  }
+
+  fail(message: string) {
+    const e = new Event("error") as Event & { message: string };
+    e.message = message;
+    this.dispatchEvent(e);
+  }
+
+  static current(): FakeWorker {
+    return FakeWorker.instances[FakeWorker.instances.length - 1];
+  }
+}
+
+let runWasm: typeof import("./wasmWorkerApi.js").runWasm;
+let cancelWasm: typeof import("./wasmWorkerApi.js").cancelWasm;
+
+beforeAll(async () => {
+  vi.stubGlobal("Worker", FakeWorker);
+  ({ runWasm, cancelWasm } = await import("./wasmWorkerApi.js"));
+});
+
+function lastPosted(w: FakeWorker): WorkerMessage {
+  return w.posted[w.posted.length - 1];
+}
+
+const PANIC = "Model panicked at src/lib.rs:21:9: rate must be <= 5, got 9";
+
+describe("runWasm", () => {
+  it("resolves a plain result by request id", async () => {
+    const w = FakeWorker.current();
+    const p = runWasm("m", "double", "2");
+    const { id } = lastPosted(w);
+    w.reply({ id: id + 1000, result: "not mine" });
+    w.reply({ id, result: 4 });
+    await expect(p).resolves.toBe(4);
+  });
+
+  it("rejects an ordinary error, even an empty one, and keeps the worker", async () => {
+    const w = FakeWorker.current();
+    const p = runWasm("m", "fallible", "9");
+    w.reply({ id: lastPosted(w).id, error: "rate must be <= 5, got 9" });
+    await expect(p).rejects.toThrow("rate must be <= 5, got 9");
+    const empty = runWasm("m", "fallible", "");
+    w.reply({ id: lastPosted(w).id, error: "" });
+    await expect(empty).rejects.toThrow();
+    expect(w.terminated).toBe(false);
+    expect(FakeWorker.current()).toBe(w);
+  });
+
+  it("replaces the worker after a trap and re-sends the other calls", async () => {
+    const old = FakeWorker.current();
+    const trapped = runWasm("m", "boom", "9");
+    const survivor = runWasm("m", "ok", "3");
+    const trappedId = old.posted[old.posted.length - 2].id;
+    const survivorId = lastPosted(old).id;
+
+    old.reply({ id: trappedId, error: PANIC, trap: "call" });
+    await expect(trapped).rejects.toThrow(PANIC);
+
+    const fresh = FakeWorker.current();
+    expect(old.terminated).toBe(true);
+    expect(fresh).not.toBe(old);
+    expect(fresh.posted).toEqual([
+      { id: survivorId, model: "m", fn: "ok", args: ["3"] },
+    ]);
+
+    // Late events from the retired worker are ignored; the fresh one answers.
+    old.reply({ id: survivorId, result: "stale" });
+    old.fail("stale worker error");
+    fresh.reply({ id: survivorId, result: 6 });
+    await expect(survivor).resolves.toBe(6);
+
+    // The replacement is live for new calls.
+    const next = runWasm("m", "ok", "4");
+    fresh.reply({ id: lastPosted(fresh).id, result: 8 });
+    await expect(next).resolves.toBe(8);
+  });
+
+  it("fails queued repeats of the trapped call instead of re-sending them", async () => {
+    const old = FakeWorker.current();
+    const first = runWasm("m", "boom", "9");
+    const repeat = runWasm("m", "boom", "9");
+    const other = runWasm("m", "boom", "1");
+    const firstId = old.posted[old.posted.length - 3].id;
+    const otherId = lastPosted(old).id;
+
+    old.reply({ id: firstId, error: PANIC, trap: "call" });
+    await expect(first).rejects.toThrow(PANIC);
+    await expect(repeat).rejects.toThrow(PANIC);
+
+    const fresh = FakeWorker.current();
+    expect(fresh.posted.map((m) => m.id)).toEqual([otherId]);
+    fresh.reply({ id: otherId, result: 1 });
+    await expect(other).resolves.toBe(1);
+  });
+
+  it("fails every queued call into a model whose init trapped", async () => {
+    const old = FakeWorker.current();
+    const init = runWasm("broken", "a");
+    const sameModel = runWasm("broken", "b", "x");
+    const otherModel = runWasm("fine", "a");
+    const initId = old.posted[old.posted.length - 3].id;
+    const otherId = lastPosted(old).id;
+
+    const message = "Model panicked or aborted while initializing";
+    vi.useFakeTimers();
+    try {
+      old.reply({ id: initId, error: message, trap: "init" });
+      await expect(init).rejects.toThrow(message);
+      await expect(sameModel).rejects.toThrow(message);
+
+      const fresh = FakeWorker.current();
+      expect(old.terminated).toBe(true);
+      expect(fresh.posted.map((m) => m.id)).toEqual([otherId]);
+      fresh.reply({ id: otherId, result: "ok" });
+      await expect(otherModel).resolves.toBe("ok");
+
+      // Within the retry window a new call into that model is rejected
+      // without reaching the worker; afterwards it is sent again.
+      await expect(runWasm("broken", "a")).rejects.toThrow(message);
+      expect(fresh.posted).toHaveLength(1);
+      vi.advanceTimersByTime(2000);
+      const later = runWasm("broken", "a");
+      expect(fresh.posted).toHaveLength(2);
+      fresh.reply({ id: lastPosted(fresh).id, result: "fixed" });
+      await expect(later).resolves.toBe("fixed");
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("fails pending calls on a worker error and starts fresh after a short wait", async () => {
+    vi.useFakeTimers();
+    try {
+      const w = FakeWorker.current();
+      const p = runWasm("m", "slow");
+      w.fail("Worker failed to load");
+      await expect(p).rejects.toThrow("Worker failed to load");
+
+      // Within the retry window the same rejection comes back, no spawn.
+      await expect(runWasm("m", "ok", "0")).rejects.toThrow(
+        "Worker failed to load",
+      );
+      expect(FakeWorker.current()).toBe(w);
+
+      vi.advanceTimersByTime(2000);
+      const retry = runWasm("m", "ok", "1");
+      const fresh = FakeWorker.current();
+      expect(fresh).not.toBe(w);
+      expect(w.terminated).toBe(true);
+      fresh.reply({ id: lastPosted(fresh).id, result: 2 });
+      await expect(retry).resolves.toBe(2);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("cancelWasm rejects in-flight calls with 'cancelled'", async () => {
+    const w = FakeWorker.current();
+    const p = runWasm("m", "slow");
+    cancelWasm();
+    await expect(p).rejects.toThrow("cancelled");
+    expect(w.terminated).toBe(true);
+    expect(FakeWorker.current()).not.toBe(w);
+  });
+});

package/src/wasmWorkerApi.ts

@@ -1,4 +1,4 @@
-import type { TransferableResponse } from "@cfasim-ui/shared";
+import type { TransferableResponse, WasmTrapKind } from "@cfasim-ui/shared";
 import {
   unwrapResponse,
   describeWorkerError,
@@ -8,15 +8,28 @@ import type { WorkerMessage } from "./messages.js";
 
 let lastId = 0;
 
-// Rejects keyed by request id so `cancelWasm` can fail in-flight promises
-// when we terminate the worker mid-run, and so worker-level errors can drain
-// every pending call at once.
-const pendingRejects = new Map<number, (reason: Error) => void>();
+interface Pending {
+  message: WorkerMessage;
+  resolve: (value: unknown) => void;
+  reject: (reason: Error) => void;
+}
+
+// In-flight calls keyed by request id. `cancelWasm` fails them when it
+// terminates the worker mid-run, worker-level errors drain them all at once,
+// and a trap re-sends the survivors to the replacement worker.
+const pending = new Map<number, Pending>();
 
-// Set once the worker fires an `error` / `messageerror` event. Subsequent
-// `runWasm` calls short-circuit with this error so the caller sees a real
-// rejection instead of waiting forever on a worker that will never reply.
+// Set when the worker fires an `error` / `messageerror` event, which fails
+// every pending call. A `runWasm` after `WORKER_RETRY_MS` starts a fresh
+// worker; sooner ones get the same rejection, so a worker script that never
+// loads costs one spawn per retry window, not one per slider tick.
 let workerDeadError: Error | null = null;
+let workerDiedAt = 0;
+const WORKER_RETRY_MS = 2000;
+
+// Models whose initialization trapped, with the same retry window: each
+// retry costs a worker and a module load.
+const initTraps = new Map<string, { error: Error; at: number }>();
 
 function newWorker(): Worker {
   const w = new Worker(new URL("./wasm.worker.ts", import.meta.url), {
@@ -25,50 +38,112 @@ function newWorker(): Worker {
   function failAll(message: string) {
     if (workerDeadError) return;
     workerDeadError = new Error(message);
-    const rejects = Array.from(pendingRejects.values());
-    pendingRejects.clear();
-    for (const reject of rejects) reject(workerDeadError);
+    workerDiedAt = Date.now();
+    const entries = Array.from(pending.values());
+    pending.clear();
+    for (const entry of entries) entry.reject(workerDeadError);
   }
+  // Events from a worker that has since been replaced are stale: its
+  // requests were re-sent to, or failed with, the current worker.
   w.addEventListener("error", (e: ErrorEvent) => {
+    if (w !== worker) return;
     failAll(describeWorkerError(e));
   });
   w.addEventListener("messageerror", () => {
+    if (w !== worker) return;
     failAll(MESSAGEERROR_TEXT);
   });
+  w.addEventListener("message", (event: MessageEvent<TransferableResponse>) => {
+    if (w !== worker) return;
+    const data = event.data;
+    const entry = data && pending.get(data.id);
+    if (!entry) return;
+    pending.delete(data.id);
+    if (data.error !== undefined) {
+      const error = new Error(data.error);
+      if (data.trap) replaceWorker(entry.message, data.trap, error);
+      entry.reject(error);
+    } else {
+      entry.resolve(unwrapResponse(data));
+    }
+  });
   return w;
 }
 
 let worker = newWorker();
 
+function restartWorker(): void {
+  worker.terminate();
+  workerDeadError = null;
+  worker = newWorker();
+}
+
+function sameCall(a: WorkerMessage, b: WorkerMessage): boolean {
+  return (
+    a.model === b.model &&
+    a.fn === b.fn &&
+    a.args.length === b.args.length &&
+    a.args.every((arg, i) => arg === b.args[i])
+  );
+}
+
+/**
+ * Replace the worker after a trap, since the old instance may be poisoned
+ * (a panic never unwinds). Other in-flight calls move to the new worker,
+ * except those that would trap the same way: the same call again, or any
+ * call into a model whose init trapped. Calls with other inputs are re-sent
+ * even though they may trap too, each costing another replacement: failing
+ * them would report an error for inputs that might work and never retry.
+ */
+function replaceWorker(
+  trapped: WorkerMessage,
+  kind: WasmTrapKind,
+  error: Error,
+): void {
+  if (kind === "init") {
+    initTraps.set(trapped.model, { error, at: Date.now() });
+  }
+  restartWorker();
+  for (const [id, entry] of Array.from(pending)) {
+    const doomed =
+      kind === "init"
+        ? entry.message.model === trapped.model
+        : sameCall(entry.message, trapped);
+    if (doomed) {
+      pending.delete(id);
+      entry.reject(error);
+    } else {
+      worker.postMessage(entry.message);
+    }
+  }
+}
+
 export function runWasm(
   model: string,
   fn: string,
   ...args: string[]
 ): Promise<unknown> {
   if (workerDeadError) {
-    return Promise.reject(workerDeadError);
+    // The worker's module failed to load or it posted something unreadable.
+    // That can be transient (a dev server restart), so try a fresh one
+    // rather than failing every call for the rest of the page's life.
+    if (Date.now() - workerDiedAt < WORKER_RETRY_MS) {
+      return Promise.reject(workerDeadError);
+    }
+    restartWorker();
+  }
+  const initTrap = initTraps.get(model);
+  if (initTrap) {
+    if (Date.now() - initTrap.at < WORKER_RETRY_MS) {
+      return Promise.reject(initTrap.error);
+    }
+    initTraps.delete(model);
   }
   return new Promise((resolve, reject) => {
     const id = ++lastId;
-    // Capture the current worker so a later `cancelWasm` that swaps the
-    // worker reference doesn't leave the listener attached to a fresh
-    // (unrelated) worker.
-    const myWorker = worker;
-    pendingRejects.set(id, reject);
-
-    function listener(event: MessageEvent<TransferableResponse>) {
-      if (event.data?.id !== id) return;
-      myWorker.removeEventListener("message", listener);
-      pendingRejects.delete(id);
-      if (event.data.error) {
-        reject(new Error(event.data.error));
-      } else {
-        resolve(unwrapResponse(event.data));
-      }
-    }
-
-    myWorker.addEventListener("message", listener);
-    myWorker.postMessage({ id, model, fn, args } as WorkerMessage);
+    const message: WorkerMessage = { id, model, fn, args };
+    pending.set(id, { message, resolve, reject });
+    worker.postMessage(message);
   });
 }
 
@@ -80,13 +155,11 @@ export function runWasm(
  * known to be obsolete (e.g. the user has changed inputs).
  */
 export function cancelWasm(): void {
-  if (pendingRejects.size === 0) return;
-  worker.terminate();
-  const rejects = Array.from(pendingRejects.values());
-  pendingRejects.clear();
-  workerDeadError = null;
-  worker = newWorker();
-  for (const reject of rejects) {
-    reject(new Error("cancelled"));
+  if (pending.size === 0) return;
+  const entries = Array.from(pending.values());
+  pending.clear();
+  restartWorker();
+  for (const entry of entries) {
+    entry.reject(new Error("cancelled"));
   }
 }