@aztec-foundation/ipc-runtime 7.0.0-nightly.20261014 → 7.0.0-nightly.20261024

package/dest/frame_reader.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Reassembles length-prefixed frames (`u32 len | len bytes`) from stream
+ * chunks. Chunks are queued as they arrive and each frame is copied out once
+ * it is complete, so a large frame costs one copy rather than one per chunk,
+ * and memory grows only with the bytes the peer has actually sent.
+ */
+export declare class FrameReader {
+    private chunks;
+    private buffered;
+    push(chunk: Buffer): void;
+    /** The next frame's length prefix, once its 4 bytes have arrived. */
+    peekLength(): number | undefined;
+    /** The next whole frame, length prefix included, once it has fully arrived. */
+    next(): Buffer | undefined;
+    private copyOut;
+    private consume;
+}

package/dest/frame_reader.js

@@ -0,0 +1,68 @@
+/**
+ * Reassembles length-prefixed frames (`u32 len | len bytes`) from stream
+ * chunks. Chunks are queued as they arrive and each frame is copied out once
+ * it is complete, so a large frame costs one copy rather than one per chunk,
+ * and memory grows only with the bytes the peer has actually sent.
+ */
+export class FrameReader {
+    chunks = [];
+    buffered = 0;
+    push(chunk) {
+        this.chunks.push(chunk);
+        this.buffered += chunk.length;
+    }
+    /** The next frame's length prefix, once its 4 bytes have arrived. */
+    peekLength() {
+        if (this.buffered < 4) {
+            return undefined;
+        }
+        const head = this.chunks[0];
+        if (head.length >= 4) {
+            return head.readUInt32LE(0);
+        }
+        return this.copyOut(4, /*consume=*/ false).readUInt32LE(0);
+    }
+    /** The next whole frame, length prefix included, once it has fully arrived. */
+    next() {
+        const len = this.peekLength();
+        if (len === undefined || this.buffered < 4 + len) {
+            return undefined;
+        }
+        return this.copyOut(4 + len, /*consume=*/ true);
+    }
+    copyOut(n, consume) {
+        const head = this.chunks[0];
+        if (head.length >= n) {
+            if (consume) {
+                this.consume(n);
+            }
+            return head.subarray(0, n);
+        }
+        const out = Buffer.allocUnsafe(n);
+        let copied = 0;
+        for (const chunk of this.chunks) {
+            copied += chunk.copy(out, copied, 0, Math.min(chunk.length, n - copied));
+            if (copied === n) {
+                break;
+            }
+        }
+        if (consume) {
+            this.consume(n);
+        }
+        return out;
+    }
+    consume(n) {
+        this.buffered -= n;
+        while (n > 0) {
+            const head = this.chunks[0];
+            if (head.length <= n) {
+                n -= head.length;
+                this.chunks.shift();
+            }
+            else {
+                this.chunks[0] = head.subarray(n);
+                n = 0;
+            }
+        }
+    }
+}

package/dest/frame_reader.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dest/frame_reader.test.js

@@ -0,0 +1,37 @@
+import { test } from "node:test";
+import * as assert from "node:assert/strict";
+import { FrameReader } from "./frame_reader.js";
+function frame(payload) {
+    const header = Buffer.allocUnsafe(4);
+    header.writeUInt32LE(payload.length, 0);
+    return Buffer.concat([header, payload]);
+}
+test("reassembles a frame split across chunks, including a split prefix", () => {
+    const payload = Buffer.alloc(300_000);
+    for (let i = 0; i < payload.length; i++)
+        payload[i] = i & 0xff;
+    const bytes = frame(payload);
+    const reader = new FrameReader();
+    const cuts = [1, 3, 9, 1000, 150_000, bytes.length];
+    let start = 0;
+    for (const cut of cuts) {
+        assert.equal(reader.next(), undefined);
+        reader.push(bytes.subarray(start, cut));
+        start = cut;
+    }
+    assert.deepEqual(reader.next(), bytes);
+    assert.equal(reader.next(), undefined);
+});
+test("yields several frames from one chunk and keeps the remainder", () => {
+    const a = frame(Buffer.from([1, 2]));
+    const b = frame(Buffer.from([]));
+    const c = frame(Buffer.from([3, 4, 5]));
+    const reader = new FrameReader();
+    reader.push(Buffer.concat([a, b, c.subarray(0, 5)]));
+    assert.deepEqual(reader.next(), a);
+    assert.deepEqual(reader.next(), b);
+    assert.equal(reader.next(), undefined);
+    assert.equal(reader.peekLength(), 3);
+    reader.push(c.subarray(5));
+    assert.deepEqual(reader.next(), c);
+});

package/dest/index.d.ts

@@ -1,7 +1,7 @@
 export type { IpcClientAsync, IpcClientSync } from "./types.js";
 export { MAX_FRAME_SIZE, CONNECT_RETRY_BUDGET_MS, DEFAULT_RING_SIZE, SOCKET_BACKLOG, DEFAULT_CALL_TIMEOUT_NS, } from "./types.js";
 export { IpcError, IpcTransportError, IpcProcessExitedError, IpcSpawnError, } from "./errors.js";
-export { SpawnedProcessBackend, type SpawnedProcessBackendOptions, type SpawnedTransport, } from "./spawned_backend.js";
+export { SpawnedProcessBackend, SpawnedProcessBackendSync, type SpawnedProcessBackendOptions, type SpawnedTransport, } from "./spawned_backend.js";
 export { UdsIpcClient, type UdsIpcClientConnectOptions } from "./uds_client.js";
 export { UdsIpcServer, type IpcServerHandler } from "./uds_server.js";
 export { NapiShmSyncClient, NapiShmAsyncClient, createNapiShmSyncClient, createNapiShmAsyncClient, type NapiMsgpackClientSync, type NapiMsgpackClientAsync, } from "./shm_client.js";

package/dest/index.js

@@ -1,6 +1,6 @@
 export { MAX_FRAME_SIZE, CONNECT_RETRY_BUDGET_MS, DEFAULT_RING_SIZE, SOCKET_BACKLOG, DEFAULT_CALL_TIMEOUT_NS, } from "./types.js";
 export { IpcError, IpcTransportError, IpcProcessExitedError, IpcSpawnError, } from "./errors.js";
-export { SpawnedProcessBackend, } from "./spawned_backend.js";
+export { SpawnedProcessBackend, SpawnedProcessBackendSync, } from "./spawned_backend.js";
 export { UdsIpcClient } from "./uds_client.js";
 export { UdsIpcServer } from "./uds_server.js";
 export { NapiShmSyncClient, NapiShmAsyncClient, createNapiShmSyncClient, createNapiShmAsyncClient, } from "./shm_client.js";

package/dest/native_loader.d.ts

@@ -11,6 +11,6 @@ export declare function findIpcRuntimeNapi(customPath?: string): string | null;
  * the addon cannot be located or fails to dlopen.
  */
 export declare function loadIpcRuntimeNapi(customPath?: string): {
-    MsgpackClient: new (shmName: string, clientId?: number) => any;
+    MsgpackClient: new (shmName: string, clientId?: number, serverPid?: number) => any;
     MsgpackClientAsync: new (shmName: string, clientId?: number) => any;
 };

package/dest/pending_queue.d.ts

@@ -0,0 +1,28 @@
+/** Request ids stay below 2^30 so V8 keeps them as small integers (no heap allocation per call). */
+export declare const REQUEST_ID_SPACE: number;
+/** A call awaiting its response. */
+export interface PendingCall {
+    requestId: number;
+    resolve: (data: Uint8Array) => void;
+    reject: (error: unknown) => void;
+}
+/**
+ * In-flight calls in issue order, paired to responses by request id. Servers
+ * that answer in order (e.g. a serial `run()` loop) always match the head, so
+ * the common path is a shift and an integer compare; out-of-order responses
+ * fall back to a search. Ids start at a random point so a stale frame from a
+ * previous occupant of the channel is unlikely to pair with a live call.
+ */
+export declare class PendingQueue {
+    private calls;
+    private nextRequestId;
+    get length(): number;
+    /** Enqueues a call under a fresh request id and returns the id. */
+    push(resolve: PendingCall["resolve"], reject: PendingCall["reject"]): number;
+    /** Removes the most recently pushed call (to unwind a failed send). */
+    pop(): PendingCall | undefined;
+    /** Removes and returns the call for `requestId`, or undefined if none is pending. */
+    take(requestId: number): PendingCall | undefined;
+    /** Removes and returns every pending call. */
+    drain(): PendingCall[];
+}

package/dest/pending_queue.js

@@ -0,0 +1,42 @@
+/** Request ids stay below 2^30 so V8 keeps them as small integers (no heap allocation per call). */
+export const REQUEST_ID_SPACE = 2 ** 30;
+/**
+ * In-flight calls in issue order, paired to responses by request id. Servers
+ * that answer in order (e.g. a serial `run()` loop) always match the head, so
+ * the common path is a shift and an integer compare; out-of-order responses
+ * fall back to a search. Ids start at a random point so a stale frame from a
+ * previous occupant of the channel is unlikely to pair with a live call.
+ */
+export class PendingQueue {
+    calls = [];
+    nextRequestId = Math.floor(Math.random() * REQUEST_ID_SPACE);
+    get length() {
+        return this.calls.length;
+    }
+    /** Enqueues a call under a fresh request id and returns the id. */
+    push(resolve, reject) {
+        const requestId = this.nextRequestId;
+        this.nextRequestId = (requestId + 1) % REQUEST_ID_SPACE;
+        this.calls.push({ requestId, resolve, reject });
+        return requestId;
+    }
+    /** Removes the most recently pushed call (to unwind a failed send). */
+    pop() {
+        return this.calls.pop();
+    }
+    /** Removes and returns the call for `requestId`, or undefined if none is pending. */
+    take(requestId) {
+        const calls = this.calls;
+        if (calls.length > 0 && calls[0].requestId === requestId) {
+            return calls.shift();
+        }
+        const i = calls.findIndex((c) => c.requestId === requestId);
+        return i === -1 ? undefined : calls.splice(i, 1)[0];
+    }
+    /** Removes and returns every pending call. */
+    drain() {
+        const calls = this.calls;
+        this.calls = [];
+        return calls;
+    }
+}

package/dest/shm_client.d.ts

@@ -1,4 +1,4 @@
-import { IpcClientAsync, IpcClientSync } from "./types.js";
+import { IpcClientAsync, IpcClientSync, IpcErrorMapper } from "./types.js";
 /**
  * Minimum surface a NAPI msgpack client must expose. Satisfied by the
  * `MsgpackClient` / `MsgpackClientAsync` classes exported from this
@@ -21,8 +21,8 @@ export interface NapiMsgpackClientSync {
     close(): void;
 }
 export interface NapiMsgpackClientAsync {
-    setResponseCallback(cb: (requestId: bigint, response: Buffer) => void): void;
-    call(requestId: bigint, input: Buffer): void;
+    setResponseCallback(cb: (requestId: number, response: Buffer) => void): void;
+    call(requestId: number, input: Buffer): void;
     acquire(): void;
     release(): void;
     /** Stop the native poll thread, release any held TSFN ref, close the client. */
@@ -37,12 +37,9 @@ export declare class NapiShmSyncClient implements IpcClientSync {
 }
 /**
  * Wraps the fire-and-forget async NAPI msgpack client behind the
- * `IpcClientAsync` interface. Owns a map of pending calls keyed by request
- * id; the C++ background polling thread invokes `setResponseCallback` once
- * per response (in completion order), and this wrapper pairs it to its
- * caller by the echoed id. Ids start at a random point per client so a
- * stale frame left in a recycled SHM ring slot by a previous occupant
- * cannot pair with a live call.
+ * `IpcClientAsync` interface. The C++ background polling thread invokes
+ * `setResponseCallback` once per response (in completion order), and this
+ * wrapper pairs it to its caller by the echoed id (see PendingQueue).
  *
  * `acquire` / `release` are reference-count hooks the NAPI exposes so the
  * libuv loop is kept alive only while requests are outstanding — without
@@ -50,11 +47,12 @@ export declare class NapiShmSyncClient implements IpcClientSync {
  */
 export declare class NapiShmAsyncClient implements IpcClientAsync {
     private inner;
+    private readonly mapError?;
     private readonly pending;
-    private nextRequestId;
     private destroyed;
-    constructor(inner: NapiMsgpackClientAsync);
+    constructor(inner: NapiMsgpackClientAsync, mapError?: IpcErrorMapper | undefined);
     call(input: Uint8Array): Promise<Uint8Array>;
+    private fail;
     destroy(): Promise<void>;
 }
 export interface CreateNapiShmOptions {
@@ -62,6 +60,15 @@ export interface CreateNapiShmOptions {
     clientId?: number;
     /** Override addon path lookup. Rarely needed; useful for tests / unusual deployments. */
     customAddonPath?: string;
+    /** Applied to every rejected call's error. */
+    mapError?: IpcErrorMapper;
+    /**
+     * Sync client only: the server's pid. A sync call holds the main thread, so
+     * nothing else can notice the server dying; with the pid, a call to a dead
+     * server throws (with `serverExited`, `exitCode` and `signal` set) instead
+     * of waiting forever. Calls have no deadline either way.
+     */
+    serverPid?: number;
 }
 /**
  * Factories that load the bundled `ipc_runtime_napi.node` addon and

package/dest/shm_client.js

@@ -1,4 +1,5 @@
 import { loadIpcRuntimeNapi } from "./native_loader.js";
+import { PendingQueue } from "./pending_queue.js";
 /** Wraps a sync NAPI msgpack client behind the IpcClientSync interface. */
 export class NapiShmSyncClient {
     inner;
@@ -18,12 +19,9 @@ export class NapiShmSyncClient {
 }
 /**
  * Wraps the fire-and-forget async NAPI msgpack client behind the
- * `IpcClientAsync` interface. Owns a map of pending calls keyed by request
- * id; the C++ background polling thread invokes `setResponseCallback` once
- * per response (in completion order), and this wrapper pairs it to its
- * caller by the echoed id. Ids start at a random point per client so a
- * stale frame left in a recycled SHM ring slot by a previous occupant
- * cannot pair with a live call.
+ * `IpcClientAsync` interface. The C++ background polling thread invokes
+ * `setResponseCallback` once per response (in completion order), and this
+ * wrapper pairs it to its caller by the echoed id (see PendingQueue).
  *
  * `acquire` / `release` are reference-count hooks the NAPI exposes so the
  * libuv loop is kept alive only while requests are outstanding — without
@@ -31,22 +29,22 @@ export class NapiShmSyncClient {
  */
 export class NapiShmAsyncClient {
     inner;
-    pending = new Map();
-    nextRequestId = (BigInt(Math.floor(Math.random() * 0xffffffff)) << 16n) + 1n;
+    mapError;
+    pending = new PendingQueue();
     destroyed = false;
-    constructor(inner) {
+    constructor(inner, mapError) {
         this.inner = inner;
+        this.mapError = mapError;
         this.inner.setResponseCallback((requestId, response) => {
             if (this.destroyed) {
                 // Late response delivered after destroy(); the native close already
                 // balanced the TSFN reference.
                 return;
             }
-            const cb = this.pending.get(requestId);
+            const cb = this.pending.take(requestId);
             if (cb) {
-                this.pending.delete(requestId);
                 cb.resolve(new Uint8Array(response));
-                if (this.pending.size === 0) {
+                if (this.pending.length === 0) {
                     this.inner.release();
                 }
             }
@@ -64,32 +62,39 @@ export class NapiShmAsyncClient {
     }
     call(input) {
         if (this.destroyed) {
-            return Promise.reject(new Error("NapiShmAsyncClient: call() after destroy()"));
+            return new Promise((_, reject) => this.fail(reject, new Error("NapiShmAsyncClient: call() after destroy()")));
         }
         const buf = Buffer.isBuffer(input)
             ? input
             : Buffer.from(input.buffer, input.byteOffset, input.byteLength);
         return new Promise((resolve, reject) => {
-            const requestId = this.nextRequestId++;
-            if (this.pending.size === 0) {
+            if (this.pending.length === 0) {
                 this.inner.acquire();
             }
-            this.pending.set(requestId, { resolve, reject });
+            const requestId = this.pending.push(resolve, reject);
             try {
                 this.inner.call(requestId, buf);
             }
             catch (err) {
-                // Send failed — unwind the map entry we just added.
-                this.pending.delete(requestId);
-                if (this.pending.size === 0) {
+                // Send failed — unwind the entry we just added.
+                this.pending.pop();
+                if (this.pending.length === 0) {
                     this.inner.release();
                 }
-                reject(err instanceof Error
+                this.fail(reject, err instanceof Error
                     ? err
                     : new Error(`SHM async call failed: ${String(err)}`));
             }
         });
     }
+    fail(reject, err) {
+        if (this.mapError) {
+            this.mapError(err).then(reject, reject);
+        }
+        else {
+            reject(err);
+        }
+    }
     async destroy() {
         if (this.destroyed) {
             return;
@@ -97,12 +102,11 @@ export class NapiShmAsyncClient {
         this.destroyed = true;
         // Reject anything still in flight.
         const err = new Error("ipc-runtime SHM client destroyed before response");
-        for (const cb of this.pending.values()) {
-            cb.reject(err);
+        for (const cb of this.pending.drain()) {
+            this.fail(cb.reject, err);
         }
-        this.pending.clear();
         // Stops the native poll thread and releases the TSFN reference taken
-        // when the map went 0 → 1 — without this, Node never exits when
+        // when the queue went 0 → 1 — without this, Node never exits when
         // destroyed with calls in flight.
         this.inner.close();
     }
@@ -116,11 +120,9 @@ export class NapiShmAsyncClient {
 export function createNapiShmSyncClient(shmName, options = {}) {
     const napi = loadIpcRuntimeNapi(options.customAddonPath);
     return new NapiShmSyncClient(
-    // Omit the slot id when not given so the native side self-allocates a free
-    // slot (kAutoClientId) instead of aliasing every client onto slot 0.
-    options.clientId === undefined
-        ? new napi.MsgpackClient(shmName)
-        : new napi.MsgpackClient(shmName, options.clientId));
+    // An undefined slot id makes the native side self-allocate a free slot
+    // (kAutoClientId) instead of aliasing every client onto slot 0.
+    new napi.MsgpackClient(shmName, options.clientId, options.serverPid));
 }
 export function createNapiShmAsyncClient(shmName, options = {}) {
     const napi = loadIpcRuntimeNapi(options.customAddonPath);
@@ -129,5 +131,5 @@ export function createNapiShmAsyncClient(shmName, options = {}) {
     // slot (kAutoClientId) instead of aliasing every client onto slot 0.
     options.clientId === undefined
         ? new napi.MsgpackClientAsync(shmName)
-        : new napi.MsgpackClientAsync(shmName, options.clientId));
+        : new napi.MsgpackClientAsync(shmName, options.clientId), options.mapError);
 }

package/dest/shm_client.test.js

@@ -35,7 +35,7 @@ test("shm async client discards a stale frame and still resolves the live call",
     const liveId = addon.sent[0].requestId;
     // A leftover frame from a ring's previous occupant: unknown id. Must be
     // discarded — not resolve the live call, not reject anything.
-    addon.deliver(liveId ^ 0xdeadbeefn, Buffer.from([0xba, 0xad]));
+    addon.deliver(liveId ^ 0x5eadbee, Buffer.from([0xba, 0xad]));
     // The real response still pairs and resolves.
     addon.deliver(liveId, Buffer.from([9, 9]));
     assert.deepEqual(await pending, new Uint8Array([9, 9]));

package/dest/spawned_backend.d.ts

@@ -1,4 +1,4 @@
-import { IpcClientAsync } from "./types.js";
+import { IpcClientAsync, IpcClientSync } from "./types.js";
 export type SpawnedTransport = "uds" | "shm";
 export interface SpawnedProcessBackendOptions {
     /** Absolute path of the server binary to spawn. Callers resolve it (and fail with retry=false if missing). */
@@ -23,6 +23,20 @@ export interface SpawnedProcessBackendOptions {
      * still reject (with retry=true); only later calls see the fresh process.
      */
     respawn?: boolean;
+    /**
+     * Unref the child process (and, over UDS, the idle socket) so a backend
+     * that is never destroy()ed cannot hold the Node event loop open. Calls in
+     * flight still keep the loop alive until their response arrives.
+     */
+    unref?: boolean;
+    /**
+     * Also unref the child's stdout/stderr pipes, which exist only when
+     * `logger` is set. Separate from `unref` because those pipes are how the
+     * caller sees the child's output: unref'ing them lets the process exit with
+     * log lines still unread, so it is opt-in even when the child itself is
+     * unref'd.
+     */
+    unrefStdio?: boolean;
     /** SHM only: fixed client slot id. When unset the client self-allocates a free slot. */
     clientId?: number;
     /** SHM only: override the native addon path. */
@@ -50,6 +64,7 @@ export declare class SpawnedProcessBackend implements IpcClientAsync {
     static spawn(options: SpawnedProcessBackendOptions): Promise<SpawnedProcessBackend>;
     getIpcPath(): string;
     call(input: Uint8Array): Promise<Uint8Array>;
+    private callWithRespawn;
     sendProcessSignal(signal: NodeJS.Signals): void;
     destroy(): Promise<void>;
     /** Return the live incarnation, lazily respawning one when allowed. */
@@ -59,6 +74,12 @@ export declare class SpawnedProcessBackend implements IpcClientAsync {
      * actually happened: the socket breaks before the child's 'exit' event
      * lands, so wait a short grace for exit attribution before giving up and
      * rethrowing the transport error as-is.
+     *
+     * A broken connection to a process that is still running is retired by
+     * killing that process. The client cannot reconnect, so otherwise the
+     * backend would keep the dead connection, failing every later call, never
+     * respawning, and leaving the server running for the life of the caller.
+     * Killing it routes the failure through the ordinary death path instead.
      */
     private attributeCallError;
     /** Spawn the server process and connect to it; kills the child on any failure. */
@@ -70,3 +91,27 @@ export declare class SpawnedProcessBackend implements IpcClientAsync {
     private asSpawnError;
     private cleanupIpcPath;
 }
+/**
+ * A synchronous IpcClientSync backed by a spawned server process, for callers
+ * whose API cannot await (BarretenbergSync and friends). Shares process setup,
+ * stale-path removal and the connect backstop with SpawnedProcessBackend; only
+ * the request path differs, blocking in the NAPI client instead of returning a
+ * promise.
+ *
+ * SHM only: a synchronous request needs the shared-memory client, as a socket
+ * round trip cannot block the event loop without deadlocking it. Construction
+ * is still async — the server has to come up before the first call — so only
+ * call() and destroy() are synchronous.
+ */
+export declare class SpawnedProcessBackendSync implements IpcClientSync {
+    private readonly options;
+    private readonly child;
+    private readonly client;
+    private readonly ipcPath;
+    private readonly logPath?;
+    private destroyed;
+    private constructor();
+    static spawn(options: SpawnedProcessBackendOptions): Promise<SpawnedProcessBackendSync>;
+    call(input: Uint8Array): Uint8Array;
+    destroy(): void;
+}