@aztec-foundation/ipc-runtime 0.0.1-commit.b66364b

package/dest/errors.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Errors thrown by the ipc-runtime transports and process backends.
+ *
+ * The cross-layer contract is the bare `retry` property, not these classes:
+ * an error with `retry === true` failed for environmental reasons (process
+ * death, machine load, a broken connection) and the operation may be retried;
+ * `retry === false` (or no `retry` property at all) means retrying cannot
+ * help. Consumers should feature-detect the property rather than import
+ * these types, so the convention survives package boundaries.
+ */
+export declare class IpcError extends Error {
+    readonly retry: boolean;
+    constructor(message: string, retry: boolean, options?: {
+        cause?: unknown;
+    });
+}
+/** The connection to the server broke while calls were in flight or before they could be sent. */
+export declare class IpcTransportError extends IpcError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The spawned server process exited; carries the exit cause and, when captured, the log path. */
+export declare class IpcProcessExitedError extends IpcError {
+    readonly code: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly logPath?: string | undefined;
+    constructor(message: string, code: number | null, signal: NodeJS.Signals | null, logPath?: string | undefined);
+}
+/**
+ * The server process could not be started. Environmental failures (spawn
+ * raced a loaded machine, a wedged process hit the connect backstop) are
+ * retryable; configuration failures (binary not found) are not.
+ */
+export declare class IpcSpawnError extends IpcError {
+}

package/dest/errors.js

@@ -0,0 +1,43 @@
+/**
+ * Errors thrown by the ipc-runtime transports and process backends.
+ *
+ * The cross-layer contract is the bare `retry` property, not these classes:
+ * an error with `retry === true` failed for environmental reasons (process
+ * death, machine load, a broken connection) and the operation may be retried;
+ * `retry === false` (or no `retry` property at all) means retrying cannot
+ * help. Consumers should feature-detect the property rather than import
+ * these types, so the convention survives package boundaries.
+ */
+export class IpcError extends Error {
+    retry;
+    constructor(message, retry, options) {
+        super(message, options);
+        this.retry = retry;
+        this.name = new.target.name;
+    }
+}
+/** The connection to the server broke while calls were in flight or before they could be sent. */
+export class IpcTransportError extends IpcError {
+    constructor(message, options) {
+        super(message, /*retry=*/ true, options);
+    }
+}
+/** The spawned server process exited; carries the exit cause and, when captured, the log path. */
+export class IpcProcessExitedError extends IpcError {
+    code;
+    signal;
+    logPath;
+    constructor(message, code, signal, logPath) {
+        super(message, /*retry=*/ true);
+        this.code = code;
+        this.signal = signal;
+        this.logPath = logPath;
+    }
+}
+/**
+ * The server process could not be started. Environmental failures (spawn
+ * raced a loaded machine, a wedged process hit the connect backstop) are
+ * retryable; configuration failures (binary not found) are not.
+ */
+export class IpcSpawnError extends IpcError {
+}

package/dest/index.d.ts

@@ -0,0 +1,8 @@
+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 { 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";
+export { findIpcRuntimeNapi, loadIpcRuntimeNapi, type Platform, } from "./native_loader.js";

package/dest/index.js

@@ -0,0 +1,7 @@
+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 { UdsIpcClient } from "./uds_client.js";
+export { UdsIpcServer } from "./uds_server.js";
+export { NapiShmSyncClient, NapiShmAsyncClient, createNapiShmSyncClient, createNapiShmAsyncClient, } from "./shm_client.js";
+export { findIpcRuntimeNapi, loadIpcRuntimeNapi, } from "./native_loader.js";

package/dest/native_loader.d.ts

@@ -0,0 +1,16 @@
+export type Platform = "x86_64-linux" | "x86_64-darwin" | "aarch64-linux" | "aarch64-darwin";
+/**
+ * Resolve the path of `ipc_runtime_napi.node` for the current platform.
+ * Returns null if either the platform is unsupported or the artifact is
+ * absent (typical reason: ipc-runtime/bootstrap.sh hasn't run yet).
+ */
+export declare function findIpcRuntimeNapi(customPath?: string): string | null;
+/**
+ * Load `ipc_runtime_napi.node` and return its native exports
+ * (`MsgpackClient`, `MsgpackClientAsync`). Throws a descriptive error when
+ * the addon cannot be located or fails to dlopen.
+ */
+export declare function loadIpcRuntimeNapi(customPath?: string): {
+    MsgpackClient: new (shmName: string, clientId?: number) => any;
+    MsgpackClientAsync: new (shmName: string, clientId?: number) => any;
+};

package/dest/native_loader.js

@@ -0,0 +1,81 @@
+// Locate the prebuilt ipc_runtime_napi.node addon shipped with this package.
+//
+// The addon is built by `ipc-runtime/bootstrap.sh` (CMake target
+// `ipc_runtime_napi`) and copied into `build/<arch>-<os>/` next to this
+// package's `package.json`. Resolution walks up from this file's URL to the
+// first `package.json` adjacent to a `build/` directory — that's the
+// package root in both `file:`-linked and published consumption.
+import { createRequire } from "node:module";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+const PLATFORM_TO_BUILD_DIR = {
+    "x86_64-linux": "amd64-linux",
+    "x86_64-darwin": "amd64-macos",
+    "aarch64-linux": "arm64-linux",
+    "aarch64-darwin": "arm64-macos",
+};
+function detectPlatform() {
+    const arch = process.arch;
+    const platform = process.platform;
+    if (arch === "x64" && platform === "linux")
+        return "x86_64-linux";
+    if (arch === "x64" && platform === "darwin")
+        return "x86_64-darwin";
+    if (arch === "arm64" && platform === "linux")
+        return "aarch64-linux";
+    if (arch === "arm64" && platform === "darwin")
+        return "aarch64-darwin";
+    return null;
+}
+function findPackageRoot() {
+    // `import.meta.url` after tsc compile points at the .js file under
+    // <pkg>/dest/...; climb until we find package.json with a sibling build/.
+    let currentDir = path.dirname(fileURLToPath(import.meta.url));
+    const root = path.parse(currentDir).root;
+    while (currentDir !== root) {
+        const packageJsonPath = path.join(currentDir, "package.json");
+        if (fs.existsSync(packageJsonPath)) {
+            const buildDir = path.join(currentDir, "build");
+            if (fs.existsSync(buildDir)) {
+                return currentDir;
+            }
+        }
+        currentDir = path.dirname(currentDir);
+    }
+    return null;
+}
+/**
+ * Resolve the path of `ipc_runtime_napi.node` for the current platform.
+ * Returns null if either the platform is unsupported or the artifact is
+ * absent (typical reason: ipc-runtime/bootstrap.sh hasn't run yet).
+ */
+export function findIpcRuntimeNapi(customPath) {
+    if (customPath) {
+        return fs.existsSync(customPath) ? path.resolve(customPath) : null;
+    }
+    const platform = detectPlatform();
+    if (!platform)
+        return null;
+    const packageRoot = findPackageRoot();
+    if (!packageRoot)
+        return null;
+    const buildDir = PLATFORM_TO_BUILD_DIR[platform];
+    const candidate = path.join(packageRoot, "build", buildDir, "ipc_runtime_napi.node");
+    return fs.existsSync(candidate) ? candidate : null;
+}
+/**
+ * Load `ipc_runtime_napi.node` and return its native exports
+ * (`MsgpackClient`, `MsgpackClientAsync`). Throws a descriptive error when
+ * the addon cannot be located or fails to dlopen.
+ */
+export function loadIpcRuntimeNapi(customPath) {
+    const addonPath = findIpcRuntimeNapi(customPath);
+    if (!addonPath) {
+        throw new Error("Could not locate ipc_runtime_napi.node. Build with `ipc-runtime/bootstrap.sh` " +
+            "or set the optional `customPath` argument to point at a prebuilt addon.");
+    }
+    // createRequire so this works in both ESM and CJS callers.
+    const require = createRequire(import.meta.url);
+    return require(addonPath);
+}

package/dest/shm_client.d.ts

@@ -0,0 +1,73 @@
+import { IpcClientAsync, IpcClientSync } from "./types.js";
+/**
+ * Minimum surface a NAPI msgpack client must expose. Satisfied by the
+ * `MsgpackClient` / `MsgpackClientAsync` classes exported from this
+ * package's own `ipc_runtime_napi.node` addon (see ipc-runtime/cpp/napi/),
+ * which wraps the C++ ipc::IpcClient.
+ *
+ * The interface is exposed for tests / consumers that want to inject a
+ * mock or alternative implementation; the standard production path is the
+ * `createNapiShm{Sync,Async}Client` factories below, which load the
+ * prebuilt addon shipped in this package's `build/<arch>-<os>/` directory.
+ *
+ * Note on the async contract: `MsgpackClientAsync.call` is *fire and
+ * forget*. Responses arrive via `setResponseCallback` in COMPLETION order on
+ * a background-thread → main-thread bridge (Napi::ThreadSafeFunction), each
+ * carrying its echoed request id. The TS wrapper below owns the pending map
+ * and pairs responses to callers by id.
+ */
+export interface NapiMsgpackClientSync {
+    call(input: Buffer): Buffer;
+    close(): void;
+}
+export interface NapiMsgpackClientAsync {
+    setResponseCallback(cb: (requestId: bigint, response: Buffer) => void): void;
+    call(requestId: bigint, input: Buffer): void;
+    acquire(): void;
+    release(): void;
+    /** Stop the native poll thread, release any held TSFN ref, close the client. */
+    close(): void;
+}
+/** Wraps a sync NAPI msgpack client behind the IpcClientSync interface. */
+export declare class NapiShmSyncClient implements IpcClientSync {
+    private inner;
+    constructor(inner: NapiMsgpackClientSync);
+    call(input: Uint8Array): Uint8Array;
+    destroy(): void;
+}
+/**
+ * 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.
+ *
+ * `acquire` / `release` are reference-count hooks the NAPI exposes so the
+ * libuv loop is kept alive only while requests are outstanding — without
+ * them a `node script.js` would never exit naturally.
+ */
+export declare class NapiShmAsyncClient implements IpcClientAsync {
+    private inner;
+    private readonly pending;
+    private nextRequestId;
+    private destroyed;
+    constructor(inner: NapiMsgpackClientAsync);
+    call(input: Uint8Array): Promise<Uint8Array>;
+    destroy(): Promise<void>;
+}
+export interface CreateNapiShmOptions {
+    /** MPSC client slot id (default 0). Distinct clients on the same shmName must use distinct slots. */
+    clientId?: number;
+    /** Override addon path lookup. Rarely needed; useful for tests / unusual deployments. */
+    customAddonPath?: string;
+}
+/**
+ * Factories that load the bundled `ipc_runtime_napi.node` addon and
+ * construct an MPSC-SHM client wrapped behind the `IpcClient*` interface.
+ * Matches the transport used by `ipc::make_server` on the C++ side, so any
+ * server started via that helper accepts these clients directly.
+ */
+export declare function createNapiShmSyncClient(shmName: string, options?: CreateNapiShmOptions): NapiShmSyncClient;
+export declare function createNapiShmAsyncClient(shmName: string, options?: CreateNapiShmOptions): NapiShmAsyncClient;

package/dest/shm_client.js

@@ -0,0 +1,133 @@
+import { loadIpcRuntimeNapi } from "./native_loader.js";
+/** Wraps a sync NAPI msgpack client behind the IpcClientSync interface. */
+export class NapiShmSyncClient {
+    inner;
+    constructor(inner) {
+        this.inner = inner;
+    }
+    call(input) {
+        const buf = Buffer.isBuffer(input)
+            ? input
+            : Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+        const resp = this.inner.call(buf);
+        return new Uint8Array(resp.buffer, resp.byteOffset, resp.byteLength);
+    }
+    destroy() {
+        this.inner.close();
+    }
+}
+/**
+ * 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.
+ *
+ * `acquire` / `release` are reference-count hooks the NAPI exposes so the
+ * libuv loop is kept alive only while requests are outstanding — without
+ * them a `node script.js` would never exit naturally.
+ */
+export class NapiShmAsyncClient {
+    inner;
+    pending = new Map();
+    nextRequestId = (BigInt(Math.floor(Math.random() * 0xffffffff)) << 16n) + 1n;
+    destroyed = false;
+    constructor(inner) {
+        this.inner = inner;
+        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);
+            if (cb) {
+                this.pending.delete(requestId);
+                cb.resolve(new Uint8Array(response));
+                if (this.pending.size === 0) {
+                    this.inner.release();
+                }
+            }
+            else {
+                // SHM rings persist across occupants (slot reclaim / reattach), so a
+                // frame addressed to a previous occupant's id is an anticipated
+                // leftover — discard it and keep serving live calls. Log it so that if
+                // a genuinely lost pairing ever hangs a caller, the evidence is in the
+                // log rather than silently dropped. Don't release: no acquire was
+                // taken for an orphan response.
+                console.warn(`NapiShmAsyncClient: discarding response for unknown request id ${requestId} ` +
+                    "(stale frame from a previous ring occupant?)");
+            }
+        });
+    }
+    call(input) {
+        if (this.destroyed) {
+            return Promise.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) {
+                this.inner.acquire();
+            }
+            this.pending.set(requestId, { 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) {
+                    this.inner.release();
+                }
+                reject(err instanceof Error
+                    ? err
+                    : new Error(`SHM async call failed: ${String(err)}`));
+            }
+        });
+    }
+    async destroy() {
+        if (this.destroyed) {
+            return;
+        }
+        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);
+        }
+        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
+        // destroyed with calls in flight.
+        this.inner.close();
+    }
+}
+/**
+ * Factories that load the bundled `ipc_runtime_napi.node` addon and
+ * construct an MPSC-SHM client wrapped behind the `IpcClient*` interface.
+ * Matches the transport used by `ipc::make_server` on the C++ side, so any
+ * server started via that helper accepts these clients directly.
+ */
+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));
+}
+export function createNapiShmAsyncClient(shmName, options = {}) {
+    const napi = loadIpcRuntimeNapi(options.customAddonPath);
+    return new NapiShmAsyncClient(
+    // 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.MsgpackClientAsync(shmName)
+        : new napi.MsgpackClientAsync(shmName, options.clientId));
+}

package/dest/shm_client.test.d.ts

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

package/dest/shm_client.test.js

@@ -0,0 +1,60 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { NapiShmAsyncClient } from "./shm_client.js";
+/**
+ * Drives NapiShmAsyncClient through a mock addon, so the id-pairing logic is
+ * testable without the native module or a live server.
+ */
+class MockAddon {
+    deliver;
+    sent = [];
+    acquires = 0;
+    releases = 0;
+    closed = false;
+    setResponseCallback(cb) {
+        this.deliver = cb;
+    }
+    call(requestId, input) {
+        this.sent.push({ requestId, input });
+    }
+    acquire() {
+        this.acquires++;
+    }
+    release() {
+        this.releases++;
+    }
+    close() {
+        this.closed = true;
+    }
+}
+test("shm async client discards a stale frame and still resolves the live call", async () => {
+    const addon = new MockAddon();
+    const client = new NapiShmAsyncClient(addon);
+    const pending = client.call(new Uint8Array([1, 2, 3]));
+    assert.equal(addon.sent.length, 1);
+    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]));
+    // The real response still pairs and resolves.
+    addon.deliver(liveId, Buffer.from([9, 9]));
+    assert.deepEqual(await pending, new Uint8Array([9, 9]));
+    // Refcount stayed balanced: one acquire for the call, one release when the
+    // live response drained the map (the stale frame must not release).
+    assert.equal(addon.acquires, 1);
+    assert.equal(addon.releases, 1);
+    await client.destroy();
+});
+test("shm async client pairs out-of-order responses to the right callers", async () => {
+    const addon = new MockAddon();
+    const client = new NapiShmAsyncClient(addon);
+    const a = client.call(new Uint8Array([0xaa]));
+    const b = client.call(new Uint8Array([0xbb]));
+    const [idA, idB] = addon.sent.map((s) => s.requestId);
+    // Complete in reverse order; each caller must get its own payload.
+    addon.deliver(idB, Buffer.from([2]));
+    addon.deliver(idA, Buffer.from([1]));
+    assert.deepEqual(await b, new Uint8Array([2]));
+    assert.deepEqual(await a, new Uint8Array([1]));
+    await client.destroy();
+});

package/dest/spawned_backend.d.ts

@@ -0,0 +1,72 @@
+import { IpcClientAsync } 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). */
+    binaryPath: string;
+    /** Binary name used in error messages and log labels. */
+    binaryName: string;
+    /** Prefix for the per-instance ipc path (socket / shm name). */
+    instancePrefix: string;
+    /** Argv template; each '{path}' is replaced with the backend's ipc path. */
+    ipcPathArgs: string[];
+    transport: SpawnedTransport;
+    /** Receives the child's stdout/stderr lines. Without it, output is captured to a temp log file. */
+    logger?: (msg: string) => void;
+    connectTimeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+    extraArgs?: string[];
+    /**
+     * Respawn the server on the next call() after it dies, instead of failing all
+     * subsequent calls. Only safe for stateless servers: a respawned process
+     * remembers nothing, so any server-side session state (forks, cursors) held
+     * by callers would silently dangle. In-flight calls at the time of death
+     * still reject (with retry=true); only later calls see the fresh process.
+     */
+    respawn?: 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. */
+    napiPath?: string;
+}
+/**
+ * An IpcClientAsync backed by a spawned server process. Owns the process
+ * lifecycle end to end: spawn, connect (raced against child death, with a
+ * kill-on-expiry backstop), death detection, optional lazy respawn, and
+ * teardown with SIGTERM→SIGKILL escalation. Failures surface as IpcError
+ * subclasses whose `retry` property tells callers whether the operation may
+ * be retried; no process or transport state is exposed on the API.
+ */
+export declare class SpawnedProcessBackend implements IpcClientAsync {
+    private readonly options;
+    private current?;
+    private starting?;
+    private destroying;
+    /** Set when the process died and respawn is disabled; fails all later calls. */
+    private exitError?;
+    private readonly respawn;
+    private readonly ipcPath;
+    private readonly logPath?;
+    private constructor();
+    static spawn(options: SpawnedProcessBackendOptions): Promise<SpawnedProcessBackend>;
+    getIpcPath(): string;
+    call(input: Uint8Array): Promise<Uint8Array>;
+    sendProcessSignal(signal: NodeJS.Signals): void;
+    destroy(): Promise<void>;
+    /** Return the live incarnation, lazily respawning one when allowed. */
+    private ensureUp;
+    /**
+     * Convert a failed call into the death of the process when that is what
+     * 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.
+     */
+    private attributeCallError;
+    /** Spawn the server process and connect to it; kills the child on any failure. */
+    private spawnIncarnation;
+    /** Handles an incarnation's death: reject/replace state so later calls behave per the respawn policy. */
+    private onIncarnationExit;
+    private connectClient;
+    /** Wrap a spawn/connect failure as IpcSpawnError and point at the captured log. */
+    private asSpawnError;
+    private cleanupIpcPath;
+}