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

package/src/uds_client.ts

@@ -0,0 +1,250 @@
+import * as net from "node:net";
+import { IpcTransportError } from "./errors.js";
+import {
+  IpcClientAsync,
+  CONNECT_RETRY_BUDGET_MS,
+  MAX_FRAME_SIZE,
+} from "./types.js";
+
+interface PendingCall {
+  resolve: (resp: Uint8Array) => void;
+  reject: (err: Error) => void;
+}
+
+export interface UdsIpcClientConnectOptions {
+  /** Mark the socket as unref'd so it doesn't keep the Node event loop alive when idle. */
+  unref?: boolean;
+  /**
+   * Retry budget (ms) for the initial connect when the server has bound the
+   * path but not yet called listen(). Set to 0 to fail immediately on
+   * ECONNREFUSED. Default CONNECT_RETRY_BUDGET_MS (5000).
+   */
+  connectTimeoutMs?: number;
+}
+
+/**
+ * Async IPC client over a Unix Domain Socket. Wire format matches the C++
+ * ipc::IpcServer/IpcClient socket transport: 4-byte little-endian length
+ * prefix, 8-byte little-endian request id, then the msgpack payload (the
+ * length counts the id plus the payload), per direction.
+ *
+ * Supports pipelining: each call carries a unique request id which the
+ * server echoes on the response, so responses are paired to callers by id
+ * and the server may complete requests in any order. Ids start at a random
+ * point per connection.
+ */
+export class UdsIpcClient implements IpcClientAsync {
+  private buffer: Buffer = Buffer.alloc(0);
+  private pending = new Map<bigint, PendingCall>();
+  private nextRequestId =
+    (BigInt(Math.floor(Math.random() * 0xffffffff)) << 16n) + 1n;
+  private destroyed = false;
+  /** Set once the socket has errored/closed; new calls fail fast. */
+  private closed = false;
+
+  private constructor(private conn: net.Socket) {
+    conn.on("data", (chunk) => this.onData(chunk));
+    conn.on("error", (err) =>
+      this.failAll(
+        new IpcTransportError(`UdsIpcClient: socket error: ${err.message}`, {
+          cause: err,
+        }),
+      ),
+    );
+    conn.on("close", () =>
+      this.failAll(new IpcTransportError("socket closed")),
+    );
+  }
+
+  static async connect(
+    socketPath: string,
+    opts?: UdsIpcClientConnectOptions,
+  ): Promise<UdsIpcClient> {
+    const conn = await connectWithRetry(
+      socketPath,
+      opts?.connectTimeoutMs ?? CONNECT_RETRY_BUDGET_MS,
+    );
+    conn.setNoDelay(true);
+    if (opts?.unref) conn.unref();
+    return new UdsIpcClient(conn);
+  }
+
+  /** Number of in-flight calls awaiting a response. */
+  get inflight(): number {
+    return this.pending.size;
+  }
+
+  /** Underlying socket — exposed for ref/unref control (event-loop tuning). */
+  get socket(): net.Socket {
+    return this.conn;
+  }
+
+  async call(input: Uint8Array): Promise<Uint8Array> {
+    if (this.destroyed) {
+      throw new IpcTransportError("UdsIpcClient: call() after destroy()");
+    }
+    if (this.closed) {
+      throw new IpcTransportError(
+        "UdsIpcClient: call() on a closed/errored socket",
+      );
+    }
+    return new Promise<Uint8Array>((resolve, reject) => {
+      const requestId = this.nextRequestId++;
+      this.pending.set(requestId, { resolve, reject });
+      const header = Buffer.allocUnsafe(12);
+      header.writeUInt32LE(input.length + 8, 0); // length counts id + payload
+      header.writeBigUInt64LE(requestId, 4);
+      this.conn.write(header);
+      this.conn.write(input);
+    });
+  }
+
+  async destroy(): Promise<void> {
+    this.destroyed = true;
+    this.conn.removeAllListeners();
+    this.conn.destroy();
+    this.failAll(new IpcTransportError("UdsIpcClient destroyed"));
+  }
+
+  private onData(chunk: Buffer): void {
+    this.buffer =
+      this.buffer.length === 0
+        ? Buffer.from(chunk)
+        : Buffer.concat([this.buffer, chunk]);
+    while (this.buffer.length >= 4) {
+      const len = this.buffer.readUInt32LE(0);
+      if (len > MAX_FRAME_SIZE) {
+        // Corrupt/malicious frame — close instead of buffering up to the
+        // claimed size.
+        this.conn.destroy();
+        this.failAll(
+          new IpcTransportError(
+            `UdsIpcClient: oversized frame (${len} bytes exceeds MAX_FRAME_SIZE)`,
+          ),
+        );
+        return;
+      }
+      if (len < 8) {
+        // Shorter than the request-id field: the server speaks the id-less
+        // protocol. Fail loudly instead of misparsing.
+        this.conn.destroy();
+        this.failAll(
+          new IpcTransportError(
+            `UdsIpcClient: ${len}-byte frame is shorter than the request-id field — ` +
+              "IPC protocol mismatch (envelope ids); update the peer binary/package",
+          ),
+        );
+        return;
+      }
+      if (this.buffer.length < 4 + len) return;
+      const requestId = this.buffer.readBigUInt64LE(4);
+      const payload = this.buffer.subarray(12, 4 + len);
+      this.buffer = this.buffer.subarray(4 + len);
+      const next = this.pending.get(requestId);
+      if (next) {
+        this.pending.delete(requestId);
+        next.resolve(new Uint8Array(payload));
+      } else {
+        // A response that pairs with no pending call means the stream's
+        // correlation is broken — fail everything loudly rather than
+        // continuing on a connection we can no longer trust.
+        this.conn.destroy();
+        this.failAll(
+          new IpcTransportError(
+            `UdsIpcClient: response for unknown request id ${requestId} — protocol desync`,
+          ),
+        );
+        return;
+      }
+    }
+  }
+
+  private failAll(err: Error): void {
+    this.closed = true;
+    const pending = [...this.pending.values()];
+    this.pending.clear();
+    for (const p of pending) p.reject(err);
+  }
+}
+
+/**
+ * Connect to `socketPath`, retrying "server not ready" errors until
+ * `timeoutMs` elapses: ENOENT (socket file not created yet), ECONNREFUSED
+ * (the window between the server's bind() and listen()), EAGAIN (Linux
+ * reports this for a UDS connect when the accept backlog is momentarily
+ * full), and ECONNRESET (a connect racing the server's accept loop under
+ * connection churn). Other errors fail immediately. Each attempt is also
+ * capped at the remaining budget, so a bound-but-never-accepting server
+ * cannot hang the connect past the deadline.
+ */
+async function connectWithRetry(
+  socketPath: string,
+  timeoutMs: number,
+): Promise<net.Socket> {
+  const deadline = Date.now() + timeoutMs;
+  let attempt = 0;
+  let lastErr: Error | undefined;
+  while (true) {
+    try {
+      const remainingMs = Math.max(1, deadline - Date.now());
+      return await attemptConnect(socketPath, remainingMs);
+    } catch (err) {
+      lastErr = err as Error;
+      const code = (err as NodeJS.ErrnoException).code;
+      if (
+        code !== "ECONNREFUSED" &&
+        code !== "ECONNRESET" &&
+        code !== "ENOENT" &&
+        code !== "ETIMEDOUT" &&
+        code !== "EAGAIN"
+      ) {
+        throw new IpcTransportError(
+          `UdsIpcClient: connect failed: ${lastErr.message}`,
+          { cause: lastErr },
+        );
+      }
+      if (Date.now() >= deadline) {
+        throw new IpcTransportError(
+          `UdsIpcClient: connect timed out: ${lastErr.message}`,
+          { cause: lastErr },
+        );
+      }
+      const delay = Math.min(50, 5 * 2 ** attempt++);
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+}
+
+function attemptConnect(
+  socketPath: string,
+  timeoutMs: number,
+): Promise<net.Socket> {
+  return new Promise<net.Socket>((resolve, reject) => {
+    const conn = net.createConnection(socketPath);
+    const cleanup = () => {
+      conn.removeListener("connect", onConnect);
+      conn.removeListener("error", onError);
+      clearTimeout(timer);
+    };
+    const onError = (err: Error) => {
+      cleanup();
+      conn.destroy();
+      reject(err);
+    };
+    const onConnect = () => {
+      cleanup();
+      resolve(conn);
+    };
+    const timer = setTimeout(() => {
+      cleanup();
+      conn.destroy();
+      const err: NodeJS.ErrnoException = new Error(
+        `connect attempt timed out after ${timeoutMs}ms`,
+      );
+      err.code = "ETIMEDOUT";
+      reject(err);
+    }, timeoutMs);
+    conn.once("connect", onConnect);
+    conn.once("error", onError);
+  });
+}

package/src/uds_server.ts

@@ -0,0 +1,166 @@
+import * as net from "node:net";
+import * as fs from "node:fs";
+import { MAX_FRAME_SIZE } from "./types.js";
+
+/**
+ * Handler signature mirrors the C++ ipc::IpcServer::Handler: receive raw
+ * bytes, return raw bytes. msgpack decode/encode and command dispatch are
+ * the caller's responsibility (or the codegen's, when a generated dispatcher
+ * is wired in).
+ */
+export type IpcServerHandler = (
+  clientId: number,
+  request: Uint8Array,
+) => Promise<Uint8Array> | Uint8Array;
+
+/**
+ * UDS server with the same wire format as UdsIpcClient and the C++
+ * ipc::IpcServer socket transport: 4-byte LE length prefix, 8-byte LE request
+ * id (echoed on the response), then the payload; the length counts the id
+ * plus the payload. Accepts multiple concurrent connections; handler
+ * invocations are serialised per-connection.
+ *
+ * Signal handling is the caller's responsibility (unlike the C++ server's
+ * install_default_signal_handlers); the socket file is unlinked on close()
+ * and best-effort on process exit.
+ */
+export class UdsIpcServer {
+  private server: net.Server;
+  private nextClientId = 0;
+  private connections = new Set<net.Socket>();
+  private readonly unlinkOnExit = () => {
+    try {
+      fs.unlinkSync(this.socketPath);
+    } catch {
+      /* may already be gone */
+    }
+  };
+
+  private constructor(
+    server: net.Server,
+    private socketPath: string,
+  ) {
+    this.server = server;
+  }
+
+  static async listen(
+    socketPath: string,
+    handler: IpcServerHandler,
+  ): Promise<UdsIpcServer> {
+    try {
+      fs.unlinkSync(socketPath);
+    } catch {
+      /* socket file may not exist; ignore */
+    }
+
+    const server = net.createServer();
+    const instance = new UdsIpcServer(server, socketPath);
+    server.on("connection", (conn) => instance.handleConnection(conn, handler));
+
+    await new Promise<void>((resolve, reject) => {
+      const onError = (err: Error) => {
+        server.removeListener("listening", onListening);
+        reject(err);
+      };
+      const onListening = () => {
+        server.removeListener("error", onError);
+        resolve();
+      };
+      server.once("error", onError);
+      server.once("listening", onListening);
+      server.listen(socketPath);
+    });
+
+    // Restrict the socket to the owner, matching the C++ server (and the
+    // 0600 mode used for SHM segments).
+    fs.chmodSync(socketPath, 0o600);
+
+    // Best-effort cleanup if the process exits without close().
+    process.on("exit", instance.unlinkOnExit);
+
+    return instance;
+  }
+
+  async close(): Promise<void> {
+    // Force-close live connections (matching the C++ server's shutdown) so close()
+    // resolves promptly instead of blocking until every client happens to disconnect.
+    for (const conn of this.connections) {
+      conn.destroy();
+    }
+    this.connections.clear();
+    await new Promise<void>((resolve) => this.server.close(() => resolve()));
+    process.removeListener("exit", this.unlinkOnExit);
+    try {
+      fs.unlinkSync(this.socketPath);
+    } catch {
+      /* may already be gone */
+    }
+  }
+
+  private handleConnection(conn: net.Socket, handler: IpcServerHandler): void {
+    const clientId = this.nextClientId++;
+    this.connections.add(conn);
+    conn.on("close", () => this.connections.delete(conn));
+    let buffer = Buffer.alloc(0);
+    let chain: Promise<void> = Promise.resolve();
+
+    conn.on("data", (chunk: Buffer) => {
+      buffer =
+        buffer.length === 0
+          ? Buffer.from(chunk)
+          : Buffer.concat([buffer, chunk]);
+      while (buffer.length >= 4) {
+        const len = buffer.readUInt32LE(0);
+        if (len > MAX_FRAME_SIZE) {
+          // Corrupt/malicious frame — drop the connection instead of
+          // buffering up to the claimed size.
+          conn.destroy(
+            new Error(
+              `UdsIpcServer: oversized frame (${len} bytes exceeds MAX_FRAME_SIZE)`,
+            ),
+          );
+          return;
+        }
+        if (len < 8) {
+          // Shorter than the request-id field: the peer speaks the id-less
+          // protocol. Drop the connection with a clear reason.
+          conn.destroy(
+            new Error(
+              `UdsIpcServer: ${len}-byte frame is shorter than the request-id field — ` +
+                "IPC protocol mismatch (envelope ids); update the peer binary/package",
+            ),
+          );
+          return;
+        }
+        if (buffer.length < 4 + len) break;
+        const requestId = buffer.readBigUInt64LE(4);
+        // Copy into a standalone Buffer (not a subarray view, and not a plain Uint8Array): handlers
+        // decode with msgpackr, which relies on Buffer semantics for correct string/binary decoding.
+        const payload = Buffer.from(buffer.subarray(12, 4 + len));
+        buffer = buffer.subarray(4 + len);
+
+        const prev = chain;
+        chain = (async () => {
+          await prev;
+          try {
+            const resp = await handler(clientId, payload);
+            const header = Buffer.allocUnsafe(12);
+            header.writeUInt32LE(resp.length + 8, 0); // length counts id + payload
+            header.writeBigUInt64LE(requestId, 4);
+            conn.write(header);
+            conn.write(resp);
+          } catch (err) {
+            conn.destroy(err as Error);
+          }
+        })();
+        void chain.catch(() => {
+          /* errors already handled by destroying the connection */
+        });
+      }
+    });
+
+    conn.on("error", () => {
+      /* swallowed — clients reconnect */
+    });
+  }
+}