findings(E-1,E-2,E-3,E-6): ngspice service generations + credit-bounded event transport

Adapted from codex/asyncify-execution-owner-core 3753320. Service side mirrors
the occ-service shape (E-1 watchdogs, E-2 fail-all + boot-death fix — onerror
now rejects the in-flight boot waiter instead of stranding it, E-3
onmessageerror terminal, Blob URL revoked, per-generation evtQueue cleared on
retirement).

E-6 transport bounds (worker hunks re-applied inside the emscripten-6
em-pthread else-branch — the codex file predates that split, so this is a
re-application, not a cherry-pick):
- batch cut at 512 lines / 1 MiB exact JSON-UTF-8 bytes, measured before a
  line is retained; a single line > 1 MiB flushes the accepted prefix then
  stops the event stream terminally (never retained);
- posting gated by a 64-frame / 8 MiB unacked credit window; each frame
  carries { eventSequence, eventBytes } and is released only by an exact
  { sequence, bytes } ack; any mismatched ack is terminal;
- the service mirrors the same 64-frame / 8 MiB bound on its pre-handler
  queue, acks after handing a frame to __ngspiceOnEvent, and retires the
  generation on invalid credit; { fatal } frames retire the worker.

Tests: ngspice-service.test.ts (11, ported) — watchdogs, crash/bootError/
decode-fault settlement + recovery, out-of-order ids, sync postMessage throw,
stale-generation event drops, fatal-frame retirement. tests/tools/
ngspice-worker-batch-unit.ts (node:vm over the production worker source;
`npm run ngspice:worker-batch`) — bounded ordered chunks, byte-pressure
flush, 100k-chunk credit storm, over-limit line, exact ack lease. e2e harness
twin updated to speak the ack protocol (adds __ngspiceServiceTestHooks).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Istvan Matejcsok 2026-08-19 15:48:41 +02:00
commit 0b8e7186d4
6 changed files with 1591 additions and 114 deletions

View file

@ -0,0 +1,434 @@
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
vi.mock("./ngspice-worker.js?raw", () => ({ default: "// fake ngspice worker" }));
vi.mock("./wasm-assets", () => ({
resolveWasmBase: vi.fn(async () => "/wasm"),
}));
import {
installNgspiceService,
type NgspiceRequest,
type NgspiceResponse,
} from "./ngspice-service";
import { resolveWasmBase } from "./wasm-assets";
const mockedResolveWasmBase = vi.mocked(resolveWasmBase);
const TEST_BOOT_TIMEOUT_MS = 1_000;
const TEST_RESPONSE_TIMEOUT_MS = 5_000;
type MessageListener = (event: MessageEvent) => void;
class FakeWorker {
static instances: FakeWorker[] = [];
onmessage: MessageListener | null = null;
onerror: ((event: ErrorEvent) => void) | null = null;
onmessageerror: ((event: MessageEvent) => void) | null = null;
readonly postMessage = vi.fn();
readonly terminate = vi.fn();
private readonly messageListeners = new Set<MessageListener>();
constructor() {
FakeWorker.instances.push(this);
}
addEventListener(type: string, listener: EventListenerOrEventListenerObject): void {
if (type === "message") this.messageListeners.add(listener as MessageListener);
}
removeEventListener(type: string, listener: EventListenerOrEventListenerObject): void {
if (type === "message") this.messageListeners.delete(listener as MessageListener);
}
emitMessage(data: unknown): void {
const event = { data } as MessageEvent;
this.onmessage?.(event);
for (const listener of [...this.messageListeners]) listener(event);
}
emitError(message: string): void {
this.onerror?.({ message } as ErrorEvent);
}
emitMessageError(): void {
this.onmessageerror?.({} as MessageEvent);
}
}
const commandRequest = (cmd = "run"): NgspiceRequest => ({ kind: "command", cmd });
const service = () => {
const installed = globalThis.ngspiceService;
if (!installed) throw new Error("ngspice service was not installed");
return installed;
};
async function waitForWorker(index: number): Promise<FakeWorker> {
await vi.waitFor(() => expect(FakeWorker.instances.length).toBeGreaterThan(index));
return FakeWorker.instances[index]!;
}
async function readyRequest(
workerIndex: number,
requestBody: NgspiceRequest = commandRequest(),
): Promise<{ worker: FakeWorker; request: Promise<NgspiceResponse>; id: number }> {
const request = service().request(requestBody);
const worker = await waitForWorker(workerIndex);
worker.emitMessage({ ready: true });
await vi.waitFor(() => expect(worker.postMessage).toHaveBeenCalledTimes(1));
const [{ id }] = worker.postMessage.mock.calls[0] as [{ id: number }];
return { worker, request, id };
}
describe("ngspice service worker lifetime", () => {
beforeEach(() => {
FakeWorker.instances = [];
mockedResolveWasmBase.mockReset();
mockedResolveWasmBase.mockResolvedValue("/wasm");
vi.stubGlobal("window", { location: { href: "https://pcbjam.test/editor" } });
vi.stubGlobal("Worker", FakeWorker);
let nextBlob = 1;
vi.spyOn(URL, "createObjectURL").mockImplementation(
() => `blob:ngspice-test-${nextBlob++}`,
);
vi.spyOn(URL, "revokeObjectURL").mockImplementation(() => undefined);
delete globalThis.ngspiceService;
delete globalThis.__ngspiceOnEvent;
installNgspiceService(vi.fn(), {
bootTimeoutMs: TEST_BOOT_TIMEOUT_MS,
responseTimeoutMs: TEST_RESPONSE_TIMEOUT_MS,
});
});
afterEach(() => {
delete globalThis.ngspiceService;
delete globalThis.__ngspiceOnEvent;
vi.useRealTimers();
vi.unstubAllGlobals();
vi.restoreAllMocks();
});
it("bounds a never-ready generation, retires it, and boots a fresh worker", async () => {
vi.useFakeTimers();
const timedOut = service().request(commandRequest("never ready"));
await vi.advanceTimersByTimeAsync(0);
const deadWorker = FakeWorker.instances[0]!;
expect(deadWorker).toBeDefined();
await vi.advanceTimersByTimeAsync(TEST_BOOT_TIMEOUT_MS);
await expect(timedOut).resolves.toEqual({
error: expect.stringContaining(
`ngspice_service boot timed out after ${TEST_BOOT_TIMEOUT_MS} ms`,
),
});
expect(deadWorker.terminate).toHaveBeenCalledTimes(1);
expect(URL.revokeObjectURL).toHaveBeenCalledWith("blob:ngspice-test-1");
expect(vi.getTimerCount()).toBe(0);
// The old listener was removed and the slot is retired. A late ready frame
// cannot resurrect this generation.
deadWorker.emitMessage({ ready: true });
const recovered = service().request(commandRequest("fresh"));
await vi.advanceTimersByTimeAsync(0);
const freshWorker = FakeWorker.instances[1]!;
expect(freshWorker).toBeDefined();
freshWorker.emitMessage({ ready: true });
await vi.advanceTimersByTimeAsync(0);
const [{ id }] = freshWorker.postMessage.mock.calls[0] as [{ id: number }];
freshWorker.emitMessage({ id, res: { ret: 0 } });
await expect(recovered).resolves.toEqual({ ret: 0 });
expect(freshWorker.terminate).not.toHaveBeenCalled();
expect(vi.getTimerCount()).toBe(0);
});
it("bounds delivery resolution and never creates a late retired worker", async () => {
vi.useFakeTimers();
let releaseBase!: (base: string) => void;
mockedResolveWasmBase.mockImplementationOnce(
() => new Promise<string>((resolve) => {
releaseBase = resolve;
}),
);
const timedOut = service().request(commandRequest("resolve forever"));
await vi.advanceTimersByTimeAsync(0);
expect(FakeWorker.instances).toHaveLength(0);
await vi.advanceTimersByTimeAsync(TEST_BOOT_TIMEOUT_MS);
await expect(timedOut).resolves.toEqual({
error: expect.stringContaining(
`ngspice_service boot timed out after ${TEST_BOOT_TIMEOUT_MS} ms`,
),
});
expect(FakeWorker.instances).toHaveLength(0);
expect(vi.getTimerCount()).toBe(0);
// Delivery may still finish because the underlying fetch is not abortable
// here. Its retired generation must not create a Worker or replace the
// fresh slot which the next exact request owns.
releaseBase("/stale-wasm");
await vi.advanceTimersByTimeAsync(0);
expect(FakeWorker.instances).toHaveLength(0);
const recovered = service().request(commandRequest("fresh"));
await vi.advanceTimersByTimeAsync(0);
const freshWorker = FakeWorker.instances[0]!;
expect(freshWorker).toBeDefined();
freshWorker.emitMessage({ ready: true });
await vi.advanceTimersByTimeAsync(0);
const [{ id }] = freshWorker.postMessage.mock.calls[0] as [{ id: number }];
freshWorker.emitMessage({ id, res: { ret: 0 } });
await expect(recovered).resolves.toEqual({ ret: 0 });
expect(vi.getTimerCount()).toBe(0);
});
it("retires a ready-but-silent generation and settles all concurrent ids", async () => {
vi.useFakeTimers();
const first = service().request(commandRequest("silent one"));
await vi.advanceTimersByTimeAsync(0);
const deadWorker = FakeWorker.instances[0]!;
deadWorker.emitMessage({ ready: true });
await vi.advanceTimersByTimeAsync(0);
const second = service().request(commandRequest("silent two"));
await vi.advanceTimersByTimeAsync(0);
expect(deadWorker.postMessage).toHaveBeenCalledTimes(2);
const [{ id: firstId }] = deadWorker.postMessage.mock.calls[0] as [
{ id: number },
];
const [{ id: secondId }] = deadWorker.postMessage.mock.calls[1] as [
{ id: number },
];
expect(firstId).not.toBe(secondId);
await vi.advanceTimersByTimeAsync(TEST_RESPONSE_TIMEOUT_MS);
const timeout =
`ngspice_service response timed out after ${TEST_RESPONSE_TIMEOUT_MS} ms`;
await expect(first).resolves.toEqual({ error: timeout });
await expect(second).resolves.toEqual({ error: timeout });
expect(deadWorker.terminate).toHaveBeenCalledTimes(1);
expect(URL.revokeObjectURL).toHaveBeenCalledWith("blob:ngspice-test-1");
expect(vi.getTimerCount()).toBe(0);
const recovered = service().request(commandRequest("recovered"));
await vi.advanceTimersByTimeAsync(0);
const freshWorker = FakeWorker.instances[1]!;
freshWorker.emitMessage({ ready: true });
await vi.advanceTimersByTimeAsync(0);
const [{ id: freshId }] = freshWorker.postMessage.mock.calls[0] as [
{ id: number },
];
let recoveredSettled = false;
const observed = recovered.then((response) => {
recoveredSettled = true;
return response;
});
// Even a late old-generation callback carrying the current numeric id is
// ignored. The replacement remains live until its own Worker answers.
deadWorker.emitMessage({ id: freshId, res: { ret: 99 } });
await Promise.resolve();
expect(recoveredSettled).toBe(false);
expect(freshWorker.terminate).not.toHaveBeenCalled();
freshWorker.emitMessage({ id: freshId, res: { ret: 0 } });
await expect(observed).resolves.toEqual({ ret: 0 });
expect(vi.getTimerCount()).toBe(0);
});
it("settles a first request when the worker crashes before ready and retries", async () => {
const firstRequest = service().request(commandRequest("first"));
const firstWorker = await waitForWorker(0);
firstWorker.emitError("boot trap");
await expect(firstRequest).resolves.toEqual({
error: expect.stringContaining("ngspice_service crashed: boot trap"),
});
expect(firstWorker.terminate).toHaveBeenCalledTimes(1);
const retry = await readyRequest(1, commandRequest("retry"));
retry.worker.emitMessage({ id: retry.id, res: { ret: 0 } });
await expect(retry.request).resolves.toEqual({ ret: 0 });
});
it("fails every exact pending request on a runtime crash and ignores stale callbacks", async () => {
const first = await readyRequest(0, commandRequest("one"));
const alsoPending = service().request(commandRequest("two"));
await vi.waitFor(() => expect(first.worker.postMessage).toHaveBeenCalledTimes(2));
first.worker.emitError("wasm trap");
await expect(first.request).resolves.toEqual({
error: "ngspice_service crashed: wasm trap",
});
await expect(alsoPending).resolves.toEqual({
error: "ngspice_service crashed: wasm trap",
});
expect(first.worker.terminate).toHaveBeenCalledTimes(1);
const second = await readyRequest(1, commandRequest("recovered"));
let secondSettled = false;
const observedSecond = second.request.then((response) => {
secondSettled = true;
return response;
});
first.worker.emitMessage({ id: second.id, res: { ret: 99 } });
first.worker.emitError("late old error");
await Promise.resolve();
expect(secondSettled).toBe(false);
expect(second.worker.terminate).not.toHaveBeenCalled();
second.worker.emitMessage({ id: second.id, res: { ret: 0 } });
await expect(observedSecond).resolves.toEqual({ ret: 0 });
});
it("keeps requests concurrent and correlates out-of-order responses by id", async () => {
const first = await readyRequest(0, commandRequest("slow"));
const secondRequest = service().request(commandRequest("fast"));
await vi.waitFor(() => expect(first.worker.postMessage).toHaveBeenCalledTimes(2));
const [{ id: secondId }] = first.worker.postMessage.mock.calls[1] as [
{ id: number },
];
first.worker.emitMessage({ id: secondId, res: { ret: 2 } });
await expect(secondRequest).resolves.toEqual({ ret: 2 });
let firstSettled = false;
const observedFirst = first.request.then((response) => {
firstSettled = true;
return response;
});
await Promise.resolve();
expect(firstSettled).toBe(false);
first.worker.emitMessage({ id: first.id, res: { ret: 1 } });
await expect(observedFirst).resolves.toEqual({ ret: 1 });
});
it("turns bootError into a response and keeps the next generation retryable", async () => {
const failedRequest = service().request(commandRequest());
const failedWorker = await waitForWorker(0);
failedWorker.emitMessage({ bootError: "initialization failed" });
await expect(failedRequest).resolves.toEqual({
error: expect.stringContaining(
"ngspice_service boot failed: initialization failed",
),
});
expect(failedWorker.terminate).toHaveBeenCalledTimes(1);
const retry = await readyRequest(1);
retry.worker.emitMessage({ id: retry.id, res: { ret: 0 } });
await expect(retry.request).resolves.toEqual({ ret: 0 });
});
it("fails all boot and runtime waiters on decode errors, then recovers", async () => {
const bootRequest = service().request(commandRequest("boot-one"));
const alsoBooting = service().request(commandRequest("boot-two"));
const bootWorker = await waitForWorker(0);
bootWorker.emitMessageError();
await expect(bootRequest).resolves.toEqual({
error: expect.stringContaining("ngspice_service crashed: message decode failed"),
});
await expect(alsoBooting).resolves.toEqual({
error: expect.stringContaining("ngspice_service crashed: message decode failed"),
});
const runtime = await readyRequest(1, commandRequest("runtime"));
const alsoPending = service().request(commandRequest("also-runtime"));
await vi.waitFor(() => expect(runtime.worker.postMessage).toHaveBeenCalledTimes(2));
runtime.worker.emitMessageError();
await expect(runtime.request).resolves.toEqual({
error: "ngspice_service crashed: message decode failed",
});
await expect(alsoPending).resolves.toEqual({
error: "ngspice_service crashed: message decode failed",
});
const recovered = await readyRequest(2, commandRequest("recovered"));
recovered.worker.emitMessage({ id: recovered.id, res: { ret: 0 } });
await expect(recovered.request).resolves.toEqual({ ret: 0 });
});
it("settles a synchronous postMessage failure without leaking its pending id", async () => {
const failedRequest = service().request(commandRequest("bad post"));
const worker = await waitForWorker(0);
worker.postMessage.mockImplementationOnce(() => {
throw new DOMException("cannot clone", "DataCloneError");
});
worker.emitMessage({ ready: true });
await expect(failedRequest).resolves.toEqual({
error: expect.stringContaining("ngspice_service request failed: DataCloneError"),
});
const retry = service().request(commandRequest("good post"));
await vi.waitFor(() => expect(worker.postMessage).toHaveBeenCalledTimes(2));
const [{ id }] = worker.postMessage.mock.calls[1] as [{ id: number }];
worker.emitMessage({ id, res: { ret: 0 } });
await expect(retry).resolves.toEqual({ ret: 0 });
// A late reply for the failed request cannot consume the recovered request.
const [{ id: failedId }] = worker.postMessage.mock.calls[0] as [{ id: number }];
expect(id).not.toBe(failedId);
});
it("drops queued events and late event callbacks from a retired generation", async () => {
const first = await readyRequest(0);
first.worker.emitMessage({
evt: { kind: "char", lines: ["old"] },
eventSequence: 1,
eventBytes: 31,
});
first.worker.emitError("worker died");
await expect(first.request).resolves.toEqual({
error: "ngspice_service crashed: worker died",
});
const events: string[] = [];
globalThis.__ngspiceOnEvent = (event) => events.push(event.lines?.[0] ?? event.kind);
const second = await readyRequest(1);
first.worker.emitMessage({
evt: { kind: "char", lines: ["late old"] },
eventSequence: 2,
eventBytes: 36,
});
second.worker.emitMessage({
evt: { kind: "char", lines: ["new"] },
eventSequence: 1,
eventBytes: 31,
});
second.worker.emitMessage({ id: second.id, res: { ret: 0 } });
await expect(second.request).resolves.toEqual({ ret: 0 });
expect(events).toEqual(["new"]);
});
it("retires a worker whose bounded event stream reports a fatal line", async () => {
const first = await readyRequest(0, commandRequest("oversize output"));
first.worker.emitMessage({
fatal: "ngspice event line exceeds 1048576 UTF-8 bytes",
});
await expect(first.request).resolves.toEqual({
error: "ngspice_service crashed: event stream failure: "
+ "ngspice event line exceeds 1048576 UTF-8 bytes",
});
expect(first.worker.terminate).toHaveBeenCalledTimes(1);
expect(URL.revokeObjectURL).toHaveBeenCalledWith("blob:ngspice-test-1");
const recovered = await readyRequest(1, commandRequest("fresh generation"));
recovered.worker.emitMessage({ id: recovered.id, res: { ret: 0 } });
await expect(recovered.request).resolves.toEqual({ ret: 0 });
});
});

View file

@ -83,107 +83,304 @@ export function ngspiceWorkerBlobParts(glueHref: string): string[] {
];
}
export function installNgspiceService(log: (msg: string) => void): void {
export interface NgspiceServiceWatchdogs {
/** Maximum time from the first request until a new generation announces `ready`. */
bootTimeoutMs?: number;
/** Maximum time for any one request in a ready generation to answer. */
responseTimeoutMs?: number;
}
// These are last-resort failure bounds, not normal scheduling deadlines.
// SPICE startup and foreground simulations can be expensive on slow devices,
// so production defaults deliberately leave a large margin.
export const NGSPICE_BOOT_TIMEOUT_MS = 2 * 60_000;
export const NGSPICE_RESPONSE_TIMEOUT_MS = 30 * 60_000;
export function installNgspiceService(
log: (msg: string) => void,
watchdogs: NgspiceServiceWatchdogs = {},
): void {
if (globalThis.ngspiceService) return;
const bootTimeoutMs =
watchdogs.bootTimeoutMs ?? NGSPICE_BOOT_TIMEOUT_MS;
const responseTimeoutMs =
watchdogs.responseTimeoutMs ?? NGSPICE_RESPONSE_TIMEOUT_MS;
interface WorkerSlot {
generation: number;
worker?: Worker;
workerUrl?: string;
failed: boolean;
ready: Promise<WorkerSlot>;
bootTimer?: ReturnType<typeof setTimeout>;
rejectBoot?: (reason?: unknown) => void;
removeBootListener?: () => void;
}
interface PendingRequest {
generation: number;
resolve: (res: NgspiceResponse) => void;
timer: ReturnType<typeof setTimeout>;
}
let nextId = 1;
const pending = new Map<number, (res: NgspiceResponse) => void>();
let workerP: Promise<Worker> | null = null;
let nextGeneration = 1;
const pending = new Map<number, PendingRequest>();
let workerSlot: WorkerSlot | null = null;
// Events can arrive before the client stub installs __ngspiceOnEvent
// (the handler comes with the first editor-side ngSpice_Init).
const evtQueue: NgspiceEvent[] = [];
const dispatchEvt = (evt: NgspiceEvent) => {
interface QueuedEventFrame {
generation: number;
evt: NgspiceEvent;
sequence: number;
bytes: number;
}
const MAX_QUEUED_EVENT_FRAMES = 64;
const MAX_QUEUED_EVENT_BYTES = 8 * 1024 * 1024;
const evtQueue: QueuedEventFrame[] = [];
let evtQueueBytes = 0;
const ackEvent = (slot: WorkerSlot, frame: QueuedEventFrame): boolean => {
if (slot.failed || workerSlot !== slot || !slot.worker) return false;
try {
slot.worker.postMessage({
eventAck: { sequence: frame.sequence, bytes: frame.bytes },
});
return true;
} catch (error) {
retireWorker(slot, `ngspice_service event acknowledgment failed: ${String(error)}`);
return false;
}
};
const dispatchEvt = (
slot: WorkerSlot,
evt: NgspiceEvent,
sequence: number,
bytes: number,
) => {
if (slot.failed || workerSlot !== slot) return;
if (!Number.isSafeInteger(sequence) || sequence < 1
|| !Number.isSafeInteger(bytes) || bytes < 1
|| bytes > MAX_QUEUED_EVENT_BYTES) {
retireWorker(slot, "ngspice_service sent invalid event-frame credit");
return;
}
const frame = { generation: slot.generation, evt, sequence, bytes };
const handler = globalThis.__ngspiceOnEvent;
if (handler) {
while (evtQueue.length) handler(evtQueue.shift()!);
while (evtQueue.length) {
const queued = evtQueue.shift()!;
evtQueueBytes -= queued.bytes;
if (queued.generation !== slot.generation) continue;
handler(queued.evt);
if (!ackEvent(slot, queued)) return;
}
handler(evt);
ackEvent(slot, frame);
} else {
evtQueue.push(evt);
if (evtQueue.length >= MAX_QUEUED_EVENT_FRAMES
|| evtQueueBytes > MAX_QUEUED_EVENT_BYTES - bytes) {
retireWorker(slot, "ngspice_service event-frame queue exceeded credit");
return;
}
evtQueue.push(frame);
evtQueueBytes += bytes;
}
};
const failAllPending = (why: string) => {
for (const [, resolve] of pending) resolve({ error: why });
pending.clear();
const failPending = (generation: number, why: string): void => {
for (const [id, request] of pending) {
if (request.generation !== generation) continue;
pending.delete(id);
clearTimeout(request.timer);
request.resolve({ error: why });
}
};
const ensureWorker = (): Promise<Worker> => {
if (!workerP) {
workerP = (async () => {
const retireWorker = (slot: WorkerSlot, why: string): void => {
if (slot.failed) return;
slot.failed = true;
if (slot.bootTimer !== undefined) {
clearTimeout(slot.bootTimer);
slot.bootTimer = undefined;
}
slot.removeBootListener?.();
slot.removeBootListener = undefined;
failPending(slot.generation, why);
for (let i = evtQueue.length - 1; i >= 0; --i) {
if (evtQueue[i]!.generation === slot.generation) {
evtQueueBytes -= evtQueue[i]!.bytes;
evtQueue.splice(i, 1);
}
}
if (workerSlot === slot) workerSlot = null;
try {
slot.worker?.terminate();
} catch {
/* already gone */
}
if (slot.workerUrl) {
try {
URL.revokeObjectURL(slot.workerUrl);
} catch {
/* URL cleanup must not prevent exact wait settlement */
}
slot.workerUrl = undefined;
}
const reject = slot.rejectBoot;
slot.rejectBoot = undefined;
reject?.(new Error(why));
};
const ensureWorker = (): Promise<WorkerSlot> => {
if (!workerSlot) {
const slot = {
generation: nextGeneration++,
failed: false,
} as WorkerSlot;
// Publish the generation before its async boot reaches the first await.
// This also lets every continuation test exact slot ownership directly.
workerSlot = slot;
// The editor is parked for this entire operation, including delivery
// discovery. Start the generation deadline before resolveWasmBase(): a
// hung manifest/CDN lookup must settle the exact wait just like a Worker
// which never announces ready.
const bootDeadline = new Promise<never>((_resolve, reject) => {
slot.rejectBoot = reject;
slot.bootTimer = setTimeout(() => {
if (slot.failed || workerSlot !== slot) return;
const why =
`ngspice_service boot timed out after ${bootTimeoutMs} ms`;
log(`[ngspice] ${why} — resetting service`);
retireWorker(slot, why);
}, bootTimeoutMs);
});
const boot = (async () => {
const base = await resolveWasmBase("ngspice_service");
if (slot.failed || workerSlot !== slot) {
throw new Error(
"ngspice_service worker retired during delivery resolution",
);
}
const glue = new URL(`${base}/ngspice_service.js`, window.location.href).href;
log(`[ngspice] booting ngspice_service from ${base}`);
const worker = new Worker(
URL.createObjectURL(
new Blob(ngspiceWorkerBlobParts(glue), { type: "text/javascript" }),
),
slot.workerUrl = URL.createObjectURL(
new Blob(ngspiceWorkerBlobParts(glue), { type: "text/javascript" }),
);
const worker = new Worker(slot.workerUrl);
slot.worker = worker;
worker.onmessage = (e) => {
if (slot.failed || workerSlot !== slot) return;
const data = e.data ?? {};
if (data.fatal) {
failWorker(`event stream failure: ${String(data.fatal)}`);
return;
}
if (data.evt) {
dispatchEvt(data.evt as NgspiceEvent);
dispatchEvt(
slot,
data.evt as NgspiceEvent,
data.eventSequence,
data.eventBytes,
);
return;
}
if (typeof data.id !== "number") return;
const resolve = pending.get(data.id);
if (resolve) {
const request = pending.get(data.id);
if (request?.generation === slot.generation) {
pending.delete(data.id);
resolve(data.res as NgspiceResponse);
clearTimeout(request.timer);
request.resolve(data.res as NgspiceResponse);
}
};
// A dead worker (hard ngspice fault) must not strand the editor
// suspended in an EM_ASYNC_JS bridge: fail everything in flight and
// make the next request boot a fresh worker.
worker.onerror = (e) => {
log(`[ngspice] worker error: ${e.message} — resetting service`);
failAllPending(`ngspice_service crashed: ${e.message}`);
workerP = null;
try {
worker.terminate();
} catch {
/* already gone */
}
const failWorker = (detail: string) => {
const why = `ngspice_service crashed: ${detail}`;
log(`[ngspice] worker error: ${detail} — resetting service`);
retireWorker(slot, why);
};
worker.onerror = (e) => failWorker(e.message || "worker error");
worker.onmessageerror = () => failWorker("message decode failed");
await new Promise<void>((resolve, reject) => {
await new Promise<void>((resolve) => {
const onFirst = (e: MessageEvent) => {
if (e.data?.ready) {
worker.removeEventListener("message", onFirst);
if (slot.bootTimer !== undefined) {
clearTimeout(slot.bootTimer);
slot.bootTimer = undefined;
}
slot.removeBootListener?.();
slot.removeBootListener = undefined;
slot.rejectBoot = undefined;
resolve();
} else if (e.data?.bootError) {
reject(new Error(e.data.bootError));
const why = `ngspice_service boot failed: ${String(e.data.bootError)}`;
retireWorker(slot, why);
}
};
worker.addEventListener("message", onFirst);
slot.removeBootListener = () =>
worker.removeEventListener("message", onFirst);
});
if (slot.failed || workerSlot !== slot) {
throw new Error("ngspice_service worker retired during boot");
}
log("[ngspice] ngspice_service ready");
return worker;
})().catch((e) => {
workerP = null; // a failed boot must stay retryable
return slot;
})();
slot.ready = Promise.race([boot, bootDeadline]).catch((e) => {
// A late failure from a retired generation must not clear a replacement
// which a re-entrant caller has already started.
retireWorker(slot, `ngspice_service unavailable: ${String(e)}`);
throw e;
});
}
return workerP;
return workerSlot.ready;
};
const post = (slot: WorkerSlot, req: NgspiceRequest): Promise<NgspiceResponse> => {
const worker = slot.worker;
if (!worker || slot.failed || workerSlot !== slot) {
return Promise.resolve({ error: "ngspice_service worker is unavailable" });
}
const id = nextId++;
return new Promise<NgspiceResponse>((resolve) => {
const timer = setTimeout(() => {
if (pending.get(id)?.generation !== slot.generation) return;
const why =
`ngspice_service response timed out after ${responseTimeoutMs} ms`;
log(`[ngspice] ${why} — resetting service`);
retireWorker(slot, why);
}, responseTimeoutMs);
pending.set(id, { generation: slot.generation, resolve, timer });
try {
worker.postMessage({ id, req });
} catch (error) {
pending.delete(id);
clearTimeout(timer);
resolve({ error: `ngspice_service request failed: ${String(error)}` });
}
});
};
const request = async (req: NgspiceRequest): Promise<NgspiceResponse> => {
let worker: Worker;
let slot: WorkerSlot;
try {
worker = await ensureWorker();
slot = await ensureWorker();
} catch (e) {
return { error: `ngspice_service unavailable: ${e}` };
}
const id = nextId++;
return new Promise<NgspiceResponse>((resolve) => {
pending.set(id, resolve);
worker.postMessage({ id, req });
});
return post(slot, req);
};
globalThis.ngspiceService = { request };

View file

@ -11,11 +11,13 @@
* host -> worker { id, req } req.kind: init | circ | command |
* get_vec_info | cur_plot | all_plots |
* all_vecs | running | cm_input_path
* host -> worker { eventAck: { sequence, bytes } } releases event credit
* worker -> host { id, res }
* worker -> host { evt } unsolicited event stream:
* worker -> host { evt, eventSequence, eventBytes } unsolicited events:
* { evt: { kind: "char"|"stat", lines: [...] } } batched console/status
* { evt: { kind: "bg", finished: bool } } BGThreadRunning
* { evt: { kind: "exit", status, immediate, quit } } ControlledExit
* worker -> host { fatal } terminal event-transport failure
* boot: one-shot { ready: true } | { bootError }.
*/
const GLUE = self.NGSPICE_GLUE_URL;
@ -50,27 +52,169 @@ const modP = NgspiceService({
// --- event stream -----------------------------------------------------------
// char/stat lines are batched per microtask: a chatty simulation can emit
// thousands of SendChar lines per second, and one postMessage per line would
// swamp the editor's main thread. bg/exit events flush the pending batch first
// so relative order is preserved.
// swamp the editor's main thread. A native call can emit synchronously for the
// whole request, so a microtask is not itself a memory bound. Measure the exact
// UTF-8 size of JSON.stringify(lines) before retaining each line and flush at
// either limit. bg/exit events flush first so relative order is preserved.
// E-6: batches are cut at MAX_EVENT_BATCH_* and posting is gated by the
// MAX_EVENT_UNACKED_* credit window — the host acks each frame with its exact
// { sequence, bytes } after taking ownership.
const EVT_CHAR = 0, EVT_STAT = 1, EVT_BG = 2, EVT_EXIT = 3;
let pendingLines = null; // { kind, lines } of the open batch
const MAX_EVENT_BATCH_LINES = 512;
const MAX_EVENT_BATCH_UTF8_BYTES = 1024 * 1024;
const MAX_EVENT_UNACKED_FRAMES = 64;
const MAX_EVENT_UNACKED_UTF8_BYTES = 8 * 1024 * 1024;
let pendingLines = null; // { kind, lines, utf8Bytes } of the open batch
let flushQueued = false;
let eventStreamFailure = null;
let nextEventSequence = 1;
let unackedEventBytes = 0;
const unackedEvents = new Map();
function utf8Bytes(text) {
let bytes = 0;
for (let i = 0; i < text.length; ++i) {
const unit = text.charCodeAt(i);
if (unit <= 0x7f) {
bytes += 1;
} else if (unit <= 0x7ff) {
bytes += 2;
} else if (unit >= 0xd800 && unit <= 0xdbff) {
const next = i + 1 < text.length ? text.charCodeAt(i + 1) : 0;
if (next >= 0xdc00 && next <= 0xdfff) {
bytes += 4;
++i;
} else {
bytes += 3;
}
} else {
bytes += 3;
}
}
return bytes;
}
// Exact byte count for one JSON string without allocating its serialized form.
// Modern JSON.stringify escapes lone surrogates as \udxxx; paired surrogates
// become one four-byte UTF-8 scalar. Control characters use either a two-byte
// short escape or a six-byte \u00xx escape.
function jsonStringUtf8Bytes(text) {
let bytes = 2; // opening and closing quotes
for (let i = 0; i < text.length; ++i) {
const unit = text.charCodeAt(i);
if (unit === 0x22 || unit === 0x5c) {
bytes += 2;
} else if (unit <= 0x1f) {
bytes += unit === 0x08 || unit === 0x09 || unit === 0x0a
|| unit === 0x0c || unit === 0x0d ? 2 : 6;
} else if (unit <= 0x7f) {
bytes += 1;
} else if (unit <= 0x7ff) {
bytes += 2;
} else if (unit >= 0xd800 && unit <= 0xdbff) {
const next = i + 1 < text.length ? text.charCodeAt(i + 1) : 0;
if (next >= 0xdc00 && next <= 0xdfff) {
bytes += 4;
++i;
} else {
bytes += 6;
}
} else if (unit >= 0xdc00 && unit <= 0xdfff) {
bytes += 6;
} else {
bytes += 3;
}
}
return bytes;
}
function flushLines() {
flushQueued = false;
if (pendingLines) {
const batch = pendingLines;
pendingLines = null;
postMessage({ evt: { kind: batch.kind, lines: batch.lines } });
postEvent({ kind: batch.kind, lines: batch.lines });
}
}
function stopEventStream(reason) {
if (!eventStreamFailure) {
// Detach the not-yet-transferred batch before reporting terminal state.
// Frames already posted remain bounded by the unacknowledged credit set.
pendingLines = null;
flushQueued = false;
eventStreamFailure = reason;
postMessage({ fatal: reason });
}
throw new RangeError(eventStreamFailure);
}
function postEvent(evt) {
const eventBytes = utf8Bytes(JSON.stringify(evt));
if (unackedEvents.size >= MAX_EVENT_UNACKED_FRAMES
|| eventBytes > MAX_EVENT_UNACKED_UTF8_BYTES
|| unackedEventBytes > MAX_EVENT_UNACKED_UTF8_BYTES - eventBytes) {
stopEventStream(
`ngspice event transport exceeded ${MAX_EVENT_UNACKED_FRAMES} frames or `
+ `${MAX_EVENT_UNACKED_UTF8_BYTES} unacknowledged UTF-8 bytes`);
}
if (nextEventSequence > Number.MAX_SAFE_INTEGER) {
stopEventStream("ngspice event sequence space exhausted");
}
const eventSequence = nextEventSequence++;
unackedEvents.set(eventSequence, eventBytes);
unackedEventBytes += eventBytes;
try {
postMessage({ evt, eventSequence, eventBytes });
} catch (error) {
unackedEvents.delete(eventSequence);
unackedEventBytes -= eventBytes;
stopEventStream(`ngspice event postMessage failed: ${String(error)}`);
}
}
function acknowledgeEvent(ack) {
const sequence = ack && ack.sequence;
const bytes = ack && ack.bytes;
const retained = unackedEvents.get(sequence);
if (!Number.isSafeInteger(sequence) || !Number.isSafeInteger(bytes)
|| retained === undefined || retained !== bytes
|| bytes < 0 || bytes > unackedEventBytes) {
stopEventStream("ngspice event acknowledgment did not match an exact frame");
}
unackedEvents.delete(sequence);
unackedEventBytes -= bytes;
}
function onEmit(kind, text, a, b) {
if (eventStreamFailure) throw new RangeError(eventStreamFailure);
if (kind === EVT_CHAR || kind === EVT_STAT) {
const k = kind === EVT_CHAR ? "char" : "stat";
const line = String(text);
const lineBytes = jsonStringUtf8Bytes(line);
if (lineBytes + 2 > MAX_EVENT_BATCH_UTF8_BYTES) {
// Every earlier line was accepted while capacity existed. Transfer it
// before refusing this line, which is measured but never retained.
flushLines();
stopEventStream(
`ngspice event line exceeds ${MAX_EVENT_BATCH_UTF8_BYTES} UTF-8 bytes`);
}
if (pendingLines && pendingLines.kind !== k) flushLines();
if (!pendingLines) pendingLines = { kind: k, lines: [] };
pendingLines.lines.push(text);
if (pendingLines) {
const nextBytes = pendingLines.utf8Bytes + 1 + lineBytes;
if (pendingLines.lines.length >= MAX_EVENT_BATCH_LINES
|| nextBytes > MAX_EVENT_BATCH_UTF8_BYTES) {
flushLines();
}
}
if (!pendingLines) pendingLines = { kind: k, lines: [], utf8Bytes: 2 };
pendingLines.utf8Bytes += (pendingLines.lines.length ? 1 : 0) + lineBytes;
pendingLines.lines.push(line);
if (pendingLines.lines.length >= MAX_EVENT_BATCH_LINES
|| pendingLines.utf8Bytes >= MAX_EVENT_BATCH_UTF8_BYTES) {
flushLines();
}
if (!flushQueued) {
flushQueued = true;
queueMicrotask(flushLines);
@ -79,9 +223,9 @@ function onEmit(kind, text, a, b) {
}
flushLines();
if (kind === EVT_BG) {
postMessage({ evt: { kind: "bg", finished: !!a } });
postEvent({ kind: "bg", finished: !!a });
} else if (kind === EVT_EXIT) {
postMessage({ evt: { kind: "exit", status: a, immediate: !!(b & 1), quit: !!(b & 2) } });
postEvent({ kind: "exit", status: a, immediate: !!(b & 1), quit: !!(b & 2) });
}
}
@ -91,9 +235,17 @@ modP.then((mod) => {
}, (e) => postMessage({ bootError: String(e) }));
// --- request dispatch -------------------------------------------------------
onmessage = async (e) => {
const { id, req } = e.data;
self.onmessage = async (e) => {
const { id, req, eventAck } = e.data;
if (eventAck) {
acknowledgeEvent(eventAck);
return;
}
if (typeof id !== "number") return;
if (eventStreamFailure) {
postMessage({ id, res: { error: eventStreamFailure } });
return;
}
let res;
const transfer = [];
try {