@aztec/bb.js 0.0.1-alpha.7 → 0.0.1-commit.21caa21

package/src/bb_backends/node/native_shm_async.ts

@@ -0,0 +1,266 @@
+import { createRequire } from 'module';
+import { spawn, ChildProcess } from 'child_process';
+import { openSync, closeSync } from 'fs';
+import { IMsgpackBackendAsync } from '../interface.js';
+import { findNapiBinary, findPackageRoot } from './platform.js';
+
+// Import the NAPI module
+// The addon is built to the nodejs_module directory
+const addonPath = findNapiBinary();
+// Try loading, but don't throw if it doesn't exist (will be caught in constructor)
+let addon: any = null;
+try {
+  if (addonPath) {
+    const require = createRequire(findPackageRoot()!);
+    addon = require(addonPath);
+  }
+} catch (err) {
+  // Addon not built yet or not available
+  addon = null;
+}
+
+let instanceCounter = 0;
+
+/**
+ * Asynchronous shared memory backend that communicates with bb binary via shared memory.
+ * Uses NAPI module with background thread polling for async operations.
+ * Supports request pipelining - multiple requests can be in flight simultaneously.
+ *
+ * Architecture (matches socket backend pattern):
+ * - bb acts as the SERVER, TypeScript is the CLIENT
+ * - bb creates the shared memory region
+ * - TypeScript connects via NAPI wrapper (MsgpackClientAsync)
+ * - TypeScript manages promise queue (single-threaded, no mutex needed)
+ * - C++ background thread polls for responses, calls JavaScript callback
+ * - JavaScript callback pops queue and resolves promises in FIFO order
+ */
+export class BarretenbergNativeShmAsyncBackend implements IMsgpackBackendAsync {
+  private process: ChildProcess;
+  private client: any; // NAPI MsgpackClientAsync instance
+  private logFd?: number; // File descriptor for logs
+
+  // Queue of pending callbacks for pipelined requests
+  // Responses come back in FIFO order, so we match them with queued callbacks
+  private pendingCallbacks: Array<{
+    resolve: (data: Uint8Array) => void;
+    reject: (error: Error) => void;
+  }> = [];
+
+  private constructor(process: ChildProcess, client: any, logFd?: number) {
+    this.process = process;
+    this.client = client;
+    this.logFd = logFd;
+
+    // Register our response handler with the C++ client
+    // This callback will be invoked from the background thread via ThreadSafeFunction
+    this.client.setResponseCallback((responseBuffer: Buffer) => {
+      this.handleResponse(responseBuffer);
+    });
+  }
+
+  /**
+   * Handle response from C++ background thread
+   * Dequeues the next pending callback and resolves it (FIFO order)
+   */
+  private handleResponse(responseBuffer: Buffer): void {
+    // Response is complete - dequeue the next pending callback (FIFO)
+    const callback = this.pendingCallbacks.shift();
+    if (callback) {
+      callback.resolve(new Uint8Array(responseBuffer));
+    } else {
+      // This shouldn't happen - response without a pending request
+      console.warn('Received response but no pending callback');
+    }
+
+    // If no more pending callbacks, release ref to allow process to exit
+    if (this.pendingCallbacks.length === 0) {
+      this.client.release();
+    }
+  }
+
+  /**
+   * Create and initialize an async shared memory backend.
+   * @param bbBinaryPath Path to bb binary
+   * @param threads Optional number of threads (defaults to min(32, num_cpus))
+   * @param logger Optional logger function for bb output
+   */
+  static async new(
+    bbBinaryPath: string,
+    threads?: number,
+    logger?: (msg: string) => void,
+  ): Promise<BarretenbergNativeShmAsyncBackend> {
+    if (!addon || !addon.MsgpackClientAsync) {
+      throw new Error('Shared memory async NAPI not available.');
+    }
+
+    // Create a unique shared memory name
+    const shmName = `bb-async-${process.pid}-${instanceCounter++}`;
+
+    // If threads not set use num cpu cores, max 32 (same as socket backend)
+    const hwc = threads ? threads.toString() : '1';
+    const env = { ...process.env, HARDWARE_CONCURRENCY: hwc };
+
+    // Set up file logging if logger is provided
+    // Direct file redirection bypasses Node event loop - logs are written even if process hangs
+    let logFd: number | undefined;
+    let logPath: string | undefined;
+    if (logger) {
+      logPath = `/tmp/${shmName}.log`;
+      logFd = openSync(logPath, 'w');
+      logger(`BB process logs redirected to: ${logPath}`);
+    }
+
+    // Spawn bb process with shared memory mode
+    // Use larger ring buffers for async mode to support pipelining
+    const args = [
+      'msgpack',
+      'run',
+      '--input',
+      `${shmName}.shm`,
+      '--request-ring-size',
+      `${1024 * 1024 * 4}`,
+      '--response-ring-size',
+      `${1024 * 1024 * 4}`,
+    ];
+    const bbProcess = spawn(bbBinaryPath, args, {
+      stdio: ['ignore', logFd ?? 'ignore', logFd ?? 'ignore'],
+      env,
+    });
+
+    // Disconnect from event loop so process can exit without waiting for bb
+    // The bb process has parent death monitoring (prctl on Linux, kqueue on macOS)
+    // so it will automatically exit when Node.js exits
+    bbProcess.unref();
+
+    // Track if process has exited
+    let processExited = false;
+    let exitError: Error | null = null;
+
+    bbProcess.on('error', err => {
+      processExited = true;
+      exitError = new Error(`Native backend process error: ${err.message}`);
+    });
+
+    bbProcess.on('exit', (code, signal) => {
+      processExited = true;
+      if (code !== null && code !== 0) {
+        exitError = new Error(`Native backend process exited with code ${code}`);
+      } else if (signal && signal !== 'SIGTERM') {
+        exitError = new Error(`Native backend process killed with signal ${signal}`);
+      }
+    });
+
+    // Wait for bb to create shared memory
+    // Retry connection every 100ms for up to 5 seconds (longer than sync for thread startup)
+    const retryInterval = 100; // ms
+    const timeout = 5000; // ms
+    const maxAttempts = Math.floor(timeout / retryInterval);
+    let client: any = null;
+
+    try {
+      for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        // Check if bb process has exited before attempting connection
+        if (processExited) {
+          throw exitError || new Error('Native backend process exited unexpectedly during startup');
+        }
+
+        // Wait before attempting connection (except first attempt)
+        if (attempt > 0) {
+          await new Promise(resolve => setTimeout(resolve, retryInterval));
+        }
+
+        try {
+          // Create NAPI async client
+          client = new addon.MsgpackClientAsync(shmName);
+          break; // Success!
+        } catch (err: any) {
+          // Connection failed, will retry
+          if (attempt === maxAttempts - 1) {
+            // Last attempt failed - check one more time if process exited
+            if (processExited && exitError) {
+              throw exitError;
+            }
+            throw new Error(`Failed to connect to shared memory after ${timeout}ms: ${err.message}`);
+          }
+        }
+      }
+
+      if (!client) {
+        throw new Error('Failed to create client connection');
+      }
+
+      return new BarretenbergNativeShmAsyncBackend(bbProcess, client, logFd);
+    } finally {
+      // If we failed to connect, ensure the process is killed and log file closed
+      if (!client) {
+        bbProcess.kill('SIGKILL');
+        if (logFd !== undefined) {
+          try {
+            closeSync(logFd);
+          } catch (e) {
+            // Ignore errors during cleanup
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Send a msgpack request asynchronously.
+   * Supports pipelining - can be called multiple times before awaiting responses.
+   * Use Promise.all() to send multiple requests concurrently.
+   *
+   * Example:
+   *   const results = await Promise.all([
+   *     backend.call(buf1),
+   *     backend.call(buf2),
+   *     backend.call(buf3)
+   *   ]);
+   *
+   * @param inputBuffer The msgpack-encoded request
+   * @returns Promise resolving to msgpack-encoded response
+   */
+  async call(inputBuffer: Uint8Array): Promise<Uint8Array> {
+    return new Promise((resolve, reject) => {
+      // If this is the first pending callback, acquire ref to keep event loop alive
+      if (this.pendingCallbacks.length === 0) {
+        this.client.acquire();
+      }
+
+      // Enqueue this promise's callbacks (FIFO order)
+      this.pendingCallbacks.push({ resolve, reject });
+
+      try {
+        // Send request to shared memory (synchronous write)
+        // C++ call() no longer returns a promise - we manage them here
+        this.client.call(Buffer.from(inputBuffer));
+      } catch (err: any) {
+        // Send failed - dequeue the callback we just added and reject
+        this.pendingCallbacks.pop();
+
+        // If queue is now empty, release ref to allow exit
+        if (this.pendingCallbacks.length === 0) {
+          this.client.release();
+        }
+
+        reject(new Error(`Shared memory async call failed: ${err.message}`));
+      }
+    });
+  }
+
+  async destroy(): Promise<void> {
+    // Kill the bb process
+    // Background thread and callbacks will be cleaned up by OS on process exit
+    this.process.kill('SIGTERM');
+    this.process.removeAllListeners();
+
+    // Close log file if open
+    if (this.logFd !== undefined) {
+      try {
+        closeSync(this.logFd);
+      } catch (e) {
+        // Ignore errors during cleanup
+      }
+    }
+  }
+}

package/src/bb_backends/node/native_socket.ts

@@ -0,0 +1,326 @@
+import { spawn, ChildProcess } from 'child_process';
+import * as net from 'net';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { IMsgpackBackendAsync } from '../interface.js';
+import { findPackageRoot } from './platform.js';
+import readline from 'readline';
+
+/**
+ * Asynchronous native backend that communicates with bb binary via Unix Domain Socket.
+ * Uses event-based I/O with a state machine to handle partial reads.
+ *
+ * Architecture: bb acts as the SERVER, TypeScript is the CLIENT
+ * - bb creates the socket and listens for connections
+ * - TypeScript waits for socket file to exist, then connects
+ *
+ * Protocol:
+ * - Request: 4-byte little-endian length + msgpack buffer
+ * - Response: 4-byte little-endian length + msgpack buffer
+ */
+export class BarretenbergNativeSocketAsyncBackend implements IMsgpackBackendAsync {
+  private process: ChildProcess;
+  private socket: net.Socket | null = null;
+  private socketPath: string;
+  private connectionPromise: Promise<void>;
+  private connectionTimeout: NodeJS.Timeout | null = null;
+
+  // Queue of pending callbacks for pipelined requests
+  // Responses come back in FIFO order, so we match them with queued callbacks
+  private pendingCallbacks: Array<{
+    resolve: (data: Uint8Array) => void;
+    reject: (error: Error) => void;
+  }> = [];
+
+  // State machine for reading responses
+  private readingLength: boolean = true;
+  private lengthBuffer: Buffer = Buffer.alloc(4);
+  private lengthBytesRead: number = 0;
+  private responseLength: number = 0;
+  private responseBuffer: Buffer | null = null;
+  private responseBytesRead: number = 0;
+
+  constructor(bbBinaryPath: string, threads?: number, logger?: (msg: string) => void) {
+    // Create a unique socket path in temp directory
+    this.socketPath = path.join(os.tmpdir(), `bb-${process.pid}-${Date.now()}.sock`);
+
+    // Ensure socket path doesn't already exist (cleanup from previous crashes)
+    if (fs.existsSync(this.socketPath)) {
+      fs.unlinkSync(this.socketPath);
+    }
+
+    let connectionResolve: (() => void) | null = null;
+    let connectionReject: ((error: Error) => void) | null = null;
+
+    this.connectionPromise = new Promise<void>((resolve, reject) => {
+      connectionResolve = resolve;
+      connectionReject = reject;
+    });
+
+    // If threads not set use num cpu cores, max 32.
+    const hwc = threads ? threads.toString() : Math.min(32, os.cpus.length).toString();
+    const env = { ...process.env, HARDWARE_CONCURRENCY: '1' };
+
+    // Spawn bb process - it will create the socket server
+    const args = ['msgpack', 'run', '--input', this.socketPath];
+    this.process = spawn(bbBinaryPath, args, {
+      stdio: ['ignore', logger ? 'pipe' : 'ignore', logger ? 'pipe' : 'ignore'],
+      env,
+    });
+
+    // Disconnect from event loop so process can exit without waiting for bb
+    // The bb process has parent death monitoring (prctl on Linux, kqueue on macOS)
+    // so it will automatically exit when Node.js exits
+    this.process.unref();
+
+    if (logger) {
+      logger("Logger attached to bb process. DON'T FORGET TO DESTROY THE BACKEND to allow Node.js to exit.");
+      readline.createInterface({ input: this.process.stdout! }).on('line', logger);
+      readline.createInterface({ input: this.process.stderr! }).on('line', logger);
+    }
+
+    this.process.on('error', err => {
+      if (connectionReject) {
+        connectionReject(new Error(`Native backend process error: ${err.message}`));
+        connectionReject = null;
+        connectionResolve = null;
+      }
+      // Reject all pending callbacks
+      const error = new Error(`Native backend process error: ${err.message}`);
+      for (const callback of this.pendingCallbacks) {
+        callback.reject(error);
+      }
+      this.pendingCallbacks = [];
+    });
+
+    this.process.on('exit', (code, signal) => {
+      const errorMsg =
+        code !== null && code !== 0
+          ? `Native backend process exited with code ${code}`
+          : signal && signal !== 'SIGTERM'
+            ? `Native backend process killed with signal ${signal}`
+            : 'Native backend process exited unexpectedly';
+
+      if (connectionReject) {
+        connectionReject(new Error(errorMsg));
+        connectionReject = null;
+        connectionResolve = null;
+      }
+      // Reject all pending callbacks
+      const error = new Error(errorMsg);
+      for (const callback of this.pendingCallbacks) {
+        callback.reject(error);
+      }
+      this.pendingCallbacks = [];
+    });
+
+    // Wait for bb to create socket file, then connect
+    this.waitForSocketAndConnect()
+      .then(() => {
+        if (connectionResolve) {
+          connectionResolve();
+          connectionResolve = null;
+          connectionReject = null;
+        }
+      })
+      .catch(err => {
+        if (connectionReject) {
+          connectionReject(err);
+          connectionReject = null;
+          connectionResolve = null;
+        }
+      });
+
+    // Set a timeout for connection
+    this.connectionTimeout = setTimeout(() => {
+      if (connectionReject) {
+        connectionReject(new Error('Timeout waiting for bb socket connection'));
+        connectionReject = null;
+        connectionResolve = null;
+        this.cleanup();
+      }
+    }, 5000);
+  }
+
+  private async waitForSocketAndConnect(): Promise<void> {
+    // Poll for socket file to exist (bb is creating it)
+    const startTime = Date.now();
+    while (!fs.existsSync(this.socketPath)) {
+      if (Date.now() - startTime > 5000) {
+        throw new Error('Timeout waiting for bb to create socket file');
+      }
+      await new Promise(resolve => setTimeout(resolve, 50));
+    }
+
+    // Additional check: ensure it's actually a socket
+    const stats = fs.statSync(this.socketPath);
+    if (!stats.isSocket()) {
+      throw new Error(`Path exists but is not a socket: ${this.socketPath}`);
+    }
+
+    // Connect to bb's socket server as a client
+    return new Promise<void>((resolve, reject) => {
+      this.socket = net.connect(this.socketPath);
+
+      // Disable Nagle's algorithm for lower latency
+      this.socket.setNoDelay(true);
+
+      // Set up event handlers
+      this.socket.once('connect', () => {
+        // Socket starts referenced - will be unreferenced when no callbacks pending
+
+        // Clear connection timeout on successful connection
+        if (this.connectionTimeout) {
+          clearTimeout(this.connectionTimeout);
+          this.connectionTimeout = null;
+        }
+        resolve();
+      });
+
+      this.socket.once('error', err => {
+        reject(new Error(`Failed to connect to bb socket: ${err.message}`));
+      });
+
+      // Set up data handler after connection is established
+      this.socket.on('data', (chunk: Buffer) => {
+        this.handleData(chunk);
+      });
+
+      // Handle ongoing errors after initial connection
+      this.socket.on('error', err => {
+        // Reject all pending callbacks
+        const error = new Error(`Socket error: ${err.message}`);
+        for (const callback of this.pendingCallbacks) {
+          callback.reject(error);
+        }
+        this.pendingCallbacks = [];
+      });
+
+      this.socket.on('end', () => {
+        // Reject all pending callbacks
+        const error = new Error('Socket connection ended unexpectedly');
+        for (const callback of this.pendingCallbacks) {
+          callback.reject(error);
+        }
+        this.pendingCallbacks = [];
+      });
+    });
+  }
+
+  private handleData(chunk: Buffer): void {
+    let offset = 0;
+
+    while (offset < chunk.length) {
+      if (this.readingLength) {
+        // Reading 4-byte length prefix
+        const bytesToCopy = Math.min(4 - this.lengthBytesRead, chunk.length - offset);
+        chunk.copy(this.lengthBuffer, this.lengthBytesRead, offset, offset + bytesToCopy);
+        this.lengthBytesRead += bytesToCopy;
+        offset += bytesToCopy;
+
+        if (this.lengthBytesRead === 4) {
+          // Length is complete, switch to reading data
+          this.responseLength = this.lengthBuffer.readUInt32LE(0);
+          this.responseBuffer = Buffer.alloc(this.responseLength);
+          this.responseBytesRead = 0;
+          this.readingLength = false;
+        }
+      } else {
+        // Reading response data
+        const bytesToCopy = Math.min(this.responseLength - this.responseBytesRead, chunk.length - offset);
+        chunk.copy(this.responseBuffer!, this.responseBytesRead, offset, offset + bytesToCopy);
+        this.responseBytesRead += bytesToCopy;
+        offset += bytesToCopy;
+
+        if (this.responseBytesRead === this.responseLength) {
+          // Response is complete - dequeue the next pending callback (FIFO)
+          const callback = this.pendingCallbacks.shift();
+          if (callback) {
+            callback.resolve(new Uint8Array(this.responseBuffer!));
+          } else {
+            // This shouldn't happen - response without a pending request
+            console.warn('Received response but no pending callback');
+          }
+
+          // If no more pending callbacks, unref socket to allow process to exit
+          if (this.pendingCallbacks.length === 0 && this.socket) {
+            this.socket.unref();
+          }
+
+          // Reset state for next message
+          this.readingLength = true;
+          this.lengthBytesRead = 0;
+          this.responseLength = 0;
+          this.responseBuffer = null;
+          this.responseBytesRead = 0;
+        }
+      }
+    }
+  }
+
+  async call(inputBuffer: Uint8Array): Promise<Uint8Array> {
+    // Wait for connection to be established
+    await this.connectionPromise;
+
+    if (!this.socket) {
+      throw new Error('Socket not connected');
+    }
+
+    return new Promise((resolve, reject) => {
+      // If this is the first pending callback, ref the socket to keep event loop alive
+      if (this.pendingCallbacks.length === 0) {
+        this.socket!.ref();
+      }
+
+      // Enqueue this promise's callbacks (FIFO order)
+      this.pendingCallbacks.push({ resolve, reject });
+
+      // Write request: 4-byte little-endian length + msgpack data
+      // Socket will buffer these if needed, maintaining order
+      const lengthBuf = Buffer.alloc(4);
+      lengthBuf.writeUInt32LE(inputBuffer.length, 0);
+      this.socket!.write(lengthBuf);
+      this.socket!.write(inputBuffer);
+    });
+  }
+
+  private cleanup(): void {
+    // Reject any remaining pending callbacks
+    const error = new Error('Backend connection closed');
+    for (const callback of this.pendingCallbacks) {
+      callback.reject(error);
+    }
+    this.pendingCallbacks = [];
+
+    try {
+      // Remove all event listeners to prevent hanging
+      if (this.socket) {
+        this.socket.removeAllListeners();
+        // Unref so socket doesn't keep event loop alive
+        // this.socket.unref();
+        this.socket.destroy();
+      }
+    } catch (e) {
+      // Ignore errors during cleanup
+    }
+
+    // Clear connection timeout if still pending
+    if (this.connectionTimeout) {
+      clearTimeout(this.connectionTimeout);
+      this.connectionTimeout = null;
+    }
+
+    // Remove process event listeners and unref to not block event loop
+    this.process.removeAllListeners();
+    // this.process.unref();
+
+    // Don't try to unlink socket - bb owns it and will clean it up
+  }
+
+  async destroy(): Promise<void> {
+    this.cleanup();
+    this.process.kill('SIGTERM');
+    this.process.removeAllListeners();
+  }
+}