@aztec/foundation 0.0.0-test.1 → 0.0.1-commit.023c3e5

package/src/json-rpc/client/undici.ts

@@ -1,3 +1,5 @@
+import { promisify } from 'node:util';
+import { gunzip as gunzipCb, gzip as gzipCb } from 'node:zlib';
 import { Agent, type Dispatcher } from 'undici';
 
 import { createLogger } from '../../log/pino-logger.js';
@@ -5,50 +7,59 @@ import { NoRetryError } from '../../retry/index.js';
 import { jsonStringify } from '../convert.js';
 import type { JsonRpcFetch } from './fetch.js';
 
+const gzip = promisify(gzipCb);
+const gunzip = promisify(gunzipCb);
+
 const log = createLogger('json-rpc:json_rpc_client:undici');
 
+/** Minimum request size in bytes to trigger compression. */
+const COMPRESSION_THRESHOLD = 1024;
+
 export { Agent };
 
 export function makeUndiciFetch(client = new Agent()): JsonRpcFetch {
-  return async (
-    host: string,
-    rpcMethod: string,
-    body: any,
-    useApiEndpoints: boolean,
-    extraHeaders: Record<string, string> = {},
-    noRetry = false,
-  ) => {
-    log.trace(`JsonRpcClient.fetch: ${host} ${rpcMethod}`, { host, rpcMethod, body });
-    let resp: Dispatcher.ResponseData<string>;
+  return async (host: string, body: unknown, extraHeaders: Record<string, string> = {}, noRetry = false) => {
+    log.trace(`JsonRpcClient.fetch: ${host}`, { host, body });
+    let resp: Dispatcher.ResponseData;
     try {
-      resp = await client.request<string>({
+      const jsonBody = Buffer.from(jsonStringify(body));
+      const shouldCompress = jsonBody.length >= COMPRESSION_THRESHOLD;
+      resp = await client.request({
         method: 'POST',
         origin: new URL(host),
-        path: useApiEndpoints ? rpcMethod : '/',
-        body: jsonStringify(body),
+        path: '/',
+        body: shouldCompress ? await gzip(jsonBody) : jsonBody,
         headers: {
           ...extraHeaders,
           'content-type': 'application/json',
+          ...(shouldCompress && { 'content-encoding': 'gzip' }),
+          'accept-encoding': 'gzip',
         },
       });
     } catch (err) {
-      const errorMessage = `Error fetching from host ${host} with method ${rpcMethod}: ${String(err)}`;
+      const errorMessage = `Error fetching from host ${host}: ${String(err)}`;
       throw new Error(errorMessage);
     }
 
     let responseJson: any;
     const responseOk = resp.statusCode >= 200 && resp.statusCode <= 299;
+    const contentEncoding = resp.headers['content-encoding'];
     try {
-      responseJson = await resp.body.json();
-    } catch (err) {
+      if (contentEncoding === 'gzip') {
+        const jsonBuffer = await gunzip(await resp.body.arrayBuffer());
+        responseJson = JSON.parse(jsonBuffer.toString('utf-8'));
+      } else {
+        responseJson = await resp.body.json();
+      }
+    } catch {
       if (!responseOk) {
         throw new Error('HTTP ' + resp.statusCode);
       }
-      throw new Error(`Failed to parse body as JSON: ${await resp.body.text()}`);
+      throw new Error(`Failed to parse body as JSON. encoding: ${contentEncoding}, body: ${await resp.body.text()}`);
     }
 
     if (!responseOk) {
-      const errorMessage = `Error ${resp.statusCode} response from server ${host} on ${rpcMethod}: ${responseJson.error.message}`;
+      const errorMessage = `Error ${resp.statusCode} response from server ${host}: ${responseJson}`;
       if (noRetry || (resp.statusCode >= 400 && resp.statusCode < 500)) {
         throw new NoRetryError(errorMessage);
       } else {

package/src/json-rpc/convert.ts

@@ -8,16 +8,7 @@ import type { ZodFor } from '../schemas/types.js';
  * @param schema - Zod schema.
  * @returns Result of parsing json with schema.
  */
-export function jsonParseWithSchema<T>(json: string, schema: ZodFor<T>): Promise<T> {
-  return schema.parseAsync(JSON.parse(json));
-}
-/**
- * Parses a json string and then feeds it to a zod schema.
- * @param json - JSON string.
- * @param schema - Zod schema.
- * @returns Result of parsing json with schema.
- */
-export function jsonParseWithSchemaSync<T>(json: string, schema: ZodFor<T>): T {
+export function jsonParseWithSchema<T>(json: string, schema: ZodFor<T>): T {
   return schema.parse(JSON.parse(json));
 }
 
@@ -26,7 +17,7 @@ export function jsonParseWithSchemaSync<T>(json: string, schema: ZodFor<T>): T {
  * @param obj - The object to be stringified.
  * @returns The resulting string.
  */
-export function jsonStringify(obj: object, prettify?: boolean): string {
+export function jsonStringify(obj: unknown, prettify?: boolean): string {
   return JSON.stringify(
     obj,
     (_key, value) => {
@@ -55,7 +46,7 @@ export function jsonStringify(obj: object, prettify?: boolean): string {
 export function tryJsonStringify(obj: any, prettify?: boolean): string | undefined {
   try {
     return jsonStringify(obj, prettify);
-  } catch (e) {
+  } catch {
     return undefined;
   }
 }

package/src/json-rpc/errors.ts

@@ -0,0 +1,6 @@
+export class BadRequestError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'BadRequestError';
+  }
+}

package/src/json-rpc/fixtures/class_a.ts

@@ -2,7 +2,10 @@
  * Test class for testing string converter.
  */
 export class ToStringClass {
-  constructor(/** A value */ public readonly x: string, /** Another value */ public readonly y: string) {}
+  constructor(
+    /** A value */ public readonly x: string,
+    /** Another value */ public readonly y: string,
+  ) {}
 
   toString(): string {
     return [this.x, this.y].join('-');

package/src/json-rpc/fixtures/class_b.ts

@@ -2,7 +2,10 @@
  * Test class for testing string converter.
  */
 export class ToStringClass {
-  constructor(/** A value */ public readonly x: string, /** Another value */ public readonly y: string) {}
+  constructor(
+    /** A value */ public readonly x: string,
+    /** Another value */ public readonly y: string,
+  ) {}
 
   toString(): string {
     return [this.x, this.y].join('-');

package/src/json-rpc/index.ts

@@ -1 +1,2 @@
-export { jsonStringify, jsonParseWithSchema, jsonParseWithSchemaSync, tryJsonStringify } from './convert.js';
+export { jsonStringify, jsonParseWithSchema, tryJsonStringify } from './convert.js';
+export { BadRequestError } from './errors.js';

package/src/json-rpc/server/safe_json_rpc_server.ts

@@ -23,6 +23,21 @@ export type DiagnosticsData = {
 
 export type DiagnosticsMiddleware = (ctx: DiagnosticsData, next: () => Promise<void>) => Promise<void>;
 
+export type SafeJsonRpcServerConfig = {
+  /** Maximum batch size for batched rpc requests */
+  maxBatchSize: number;
+  /** Return an HTTP 200 status code on errors, but include an error object as per the JSON RPC spec */
+  http200OnError: boolean;
+  /** The maximum body size the server will accept */
+  maxBodySizeBytes: string;
+};
+
+const defaultServerConfig: SafeJsonRpcServerConfig = {
+  http200OnError: false,
+  maxBatchSize: 100,
+  maxBodySizeBytes: '1mb',
+};
+
 export class SafeJsonRpcServer {
   /**
    * The HTTP server accepting remote requests.
@@ -30,21 +45,26 @@ export class SafeJsonRpcServer {
    */
   private httpServer?: http.Server;
 
+  private config: SafeJsonRpcServerConfig;
+
   constructor(
-    /** The proxy object to delegate requests to. */
+    /** The proxy object to delegate requests to */
     private readonly proxy: Proxy,
-    /**
-     *  Return an HTTP 200 status code on errors, but include an error object
-     *  as per the JSON RPC spec
-     */
-    private http200OnError = false,
+    config: Partial<SafeJsonRpcServerConfig> = {},
     /** Health check function */
     private readonly healthCheck: StatusCheckFn = () => true,
     /** Additional middlewares */
     private extraMiddlewares: Application.Middleware[] = [],
     /** Logger */
     private log = createLogger('json-rpc:server'),
-  ) {}
+  ) {
+    this.config = { ...defaultServerConfig, ...config };
+
+    // handle empty string
+    if (!this.config.maxBodySizeBytes) {
+      this.config.maxBodySizeBytes = defaultServerConfig.maxBodySizeBytes;
+    }
+  }
 
   public isHealthy(): boolean | Promise<boolean> {
     return this.healthCheck();
@@ -63,20 +83,13 @@ export class SafeJsonRpcServer {
         await next();
       } catch (err: any) {
         const method = (ctx.request.body as any)?.method ?? 'unknown';
-        this.log.warn(`Error in JSON RPC server call ${method}: ${inspect(err)}`);
-        if (err instanceof SyntaxError) {
+        this.log.warn(`Uncaught error in JSON RPC server call ${method}: ${inspect(err)}`);
+        if (err && 'name' in err && err.name === 'BadRequestError') {
           ctx.status = 400;
-          ctx.body = { jsonrpc: '2.0', id: null, error: { code: -32700, message: `Parse error: ${err.message}` } };
-        } else if (err instanceof ZodError) {
-          const message = err.issues.map(e => `${e.message} (${e.path.join('.')})`).join('. ') || 'Validation error';
+          ctx.body = { jsonrpc: '2.0', id: null, error: { code: -32000, message: `Bad request: ${err.message}` } };
+        } else if (err && err instanceof SyntaxError) {
           ctx.status = 400;
-          ctx.body = { jsonrpc: '2.0', id: null, error: { code: -32701, message } };
-        } else if (this.http200OnError) {
-          ctx.body = {
-            jsonrpc: '2.0',
-            id: null,
-            error: { code: err.code || -32600, data: err.data, message: err.message },
-          };
+          ctx.body = { jsonrpc: '2.0', id: null, error: { code: -32700, message: `Parse error: ${err.message}` } };
         } else {
           ctx.status = 500;
           ctx.body = { jsonrpc: '2.0', id: null, error: { code: -32600, message: err.message ?? 'Internal error' } };
@@ -107,7 +120,12 @@ export class SafeJsonRpcServer {
       app.use(middleware);
     }
     app.use(exceptionHandler);
-    app.use(bodyParser({ jsonLimit: '50mb', enableTypes: ['json'], detectJSON: () => true }));
+    app.use(
+      bodyParser({
+        jsonLimit: this.config.maxBodySizeBytes,
+        enableTypes: ['json'],
+      }),
+    );
     app.use(cors());
     app.use(router.routes());
     app.use(router.allowedMethods());
@@ -124,23 +142,93 @@ export class SafeJsonRpcServer {
     const router = new Router({ prefix });
     // "JSON RPC mode" where a single endpoint is used and the method is given in the request body
     router.post('/', async (ctx: Koa.Context) => {
-      const { params = [], jsonrpc, id, method } = ctx.request.body as any;
-      // Fail if not a registered function in the proxy
-      if (typeof method !== 'string' || method === 'constructor' || !this.proxy.hasMethod(method)) {
-        ctx.status = 400;
-        const code = -32601;
-        const message = `Method not found: ${method}`;
-        ctx.body = { jsonrpc, id, error: { code, message } };
+      if (Array.isArray(ctx.request.body)) {
+        if (ctx.request.body.length > this.config.maxBatchSize) {
+          ctx.status = this.config.http200OnError ? 200 : 400;
+          ctx.body = {
+            jsonrpc: '2.0',
+            error: {
+              code: -32600,
+              message: `Batch request exceeds maximum allowed size of ${this.config.maxBatchSize}`,
+            },
+            id: null,
+          };
+          return;
+        }
+        const resp = await this.processBatch(ctx.request.body);
+        if (Array.isArray(resp)) {
+          ctx.status = 200;
+          ctx.body = resp;
+        } else {
+          ctx.status = this.config.http200OnError ? 200 : 400;
+          ctx.body = resp;
+        }
       } else {
-        ctx.status = 200;
-        const result = await this.proxy.call(method, params);
-        ctx.body = { jsonrpc, id, result };
+        const resp = await this.processRequest(ctx.request.body);
+        if ('error' in resp) {
+          ctx.status = this.config.http200OnError ? 200 : 400;
+        }
+
+        ctx.body = resp;
       }
     });
 
     return router;
   }
 
+  private async processBatch(requests: any[]) {
+    if (requests.length === 0) {
+      return { jsonrpc: '2.0', error: { code: -32600, message: 'Invalid Request' }, id: null };
+    }
+    const results = await Promise.allSettled(requests.map(req => this.processRequest(req)));
+    return results.map(res => {
+      if (res.status === 'fulfilled') {
+        return res.value;
+      }
+
+      this.log.warn(`Uncaught error executing request in batch: ${res.reason}.`);
+      return { jsonrpc: '2.0', error: { code: -32600, message: 'Invalid Request' }, id: null };
+    });
+  }
+
+  private async processRequest(request: any) {
+    if (!request || typeof request !== 'object') {
+      return { jsonrpc: '2.0', error: { code: -32600, message: 'Invalid Request' }, id: null };
+    }
+
+    const { params = [], jsonrpc = '2.0', id, method } = request;
+    if (typeof method !== 'string' || !method) {
+      return { jsonrpc: '2.0', id, error: { code: -32600, message: `Invalid request` } };
+    }
+
+    // Fail if not a registered function in the proxy
+    if (typeof method !== 'string' || method === 'constructor' || !this.proxy.hasMethod(method)) {
+      return { jsonrpc, id, error: { code: -32601, message: `Method not found: ${method}` } };
+    } else {
+      try {
+        const result = await this.proxy.call(method, params);
+        return { jsonrpc, id, result };
+      } catch (err: any) {
+        if (err && err instanceof ZodError) {
+          const message = err.issues.map(e => `${e.message} (${e.path.join('.')})`).join('. ') || 'Validation error';
+          return { jsonrpc: '2.0', id, error: { code: -32701, message } };
+        } else if (err) {
+          return {
+            jsonrpc,
+            id,
+            error: { code: -32702, data: err.data, message: err.message },
+          };
+        } else {
+          return {
+            jsonrpc,
+            id,
+            error: { code: -32702, message: 'Error executing request' },
+          };
+        }
+      }
+    }
+  }
+
   /**
    * Start this server with koa.
    * @param port - Port number.
@@ -201,7 +289,10 @@ export class SafeJsonProxy<T extends object = any> implements Proxy {
   private log = createLogger('json-rpc:proxy');
   private schema: ApiSchema;
 
-  constructor(private handler: T, schema: ApiSchemaFor<T>) {
+  constructor(
+    private handler: T,
+    schema: ApiSchemaFor<T>,
+  ) {
     this.schema = schema;
   }
 
@@ -265,7 +356,10 @@ function makeAggregateHealthcheck(namedHandlers: NamespacedApiHandlers, log?: Lo
   return async () => {
     try {
       const results = await Promise.all(
-        Object.entries(namedHandlers).map(([name, [, , healthCheck]]) => [name, healthCheck ? healthCheck() : true]),
+        Object.entries(namedHandlers).map(async ([name, [, , healthCheck]]) => [
+          name,
+          healthCheck ? await healthCheck() : true,
+        ]),
       );
       const failed = results.filter(([_, result]) => !result);
       if (failed.length > 0) {
@@ -280,12 +374,13 @@ function makeAggregateHealthcheck(namedHandlers: NamespacedApiHandlers, log?: Lo
   };
 }
 
-export type SafeJsonRpcServerOptions = {
-  http200OnError: boolean;
-  healthCheck?: StatusCheckFn;
-  log?: Logger;
-  middlewares?: Application.Middleware[];
-};
+export type SafeJsonRpcServerOptions = Partial<
+  SafeJsonRpcServerConfig & {
+    healthCheck: StatusCheckFn;
+    log: Logger;
+    middlewares: Application.Middleware[];
+  }
+>;
 
 /**
  * Creates a single SafeJsonRpcServer from multiple handlers.
@@ -294,24 +389,22 @@ export type SafeJsonRpcServerOptions = {
  */
 export function createNamespacedSafeJsonRpcServer(
   handlers: NamespacedApiHandlers,
-  options: Partial<Omit<SafeJsonRpcServerOptions, 'healthcheck'>> = {
-    log: createLogger('json-rpc:server'),
-  },
+  options: Omit<SafeJsonRpcServerOptions, 'healthcheck'> = {},
 ): SafeJsonRpcServer {
-  const { middlewares, http200OnError, log } = options;
+  const { middlewares, log } = options;
   const proxy = new NamespacedSafeJsonProxy(handlers);
   const healthCheck = makeAggregateHealthcheck(handlers, log);
-  return new SafeJsonRpcServer(proxy, http200OnError, healthCheck, middlewares, log);
+  return new SafeJsonRpcServer(proxy, options, healthCheck, middlewares, log);
 }
 
 export function createSafeJsonRpcServer<T extends object = any>(
   handler: T,
   schema: ApiSchemaFor<T>,
-  options: Partial<SafeJsonRpcServerOptions> = {},
+  options: SafeJsonRpcServerOptions = {},
 ) {
-  const { http200OnError, log, healthCheck, middlewares: extraMiddlewares } = options;
+  const { log, healthCheck, middlewares: extraMiddlewares } = options;
   const proxy = new SafeJsonProxy(handler, schema);
-  return new SafeJsonRpcServer(proxy, http200OnError, healthCheck, extraMiddlewares, log);
+  return new SafeJsonRpcServer(proxy, options, healthCheck, extraMiddlewares, log);
 }
 
 /**
@@ -326,7 +419,7 @@ export function createStatusRouter(getCurrentStatus: StatusCheckFn, apiPrefix =
     let ok: boolean;
     try {
       ok = (await getCurrentStatus()) === true;
-    } catch (err) {
+    } catch {
       ok = false;
     }
 
@@ -364,7 +457,7 @@ export async function startHttpRpcServer(
 
   const { promise, resolve } = promiseWithResolvers<void>();
   const listenPort = options.port ? (typeof options.port === 'string' ? parseInt(options.port) : options.port) : 0;
-  httpServer.listen(listenPort, options.host, () => resolve());
+  httpServer.listen({ host: options.host, port: listenPort, reuseAddress: true }, () => resolve());
 
   // Wait until listen callback is called
   if (!options.noWait) {

package/src/json-rpc/test/integration.ts

@@ -20,7 +20,7 @@ export type JsonRpcTestContext<T extends object> = {
 export async function createJsonRpcTestSetup<T extends object>(
   handler: T,
   schema: ApiSchemaFor<T>,
-  serverOptions: Partial<SafeJsonRpcServerOptions> = {},
+  serverOptions: SafeJsonRpcServerOptions = {},
   clientOptions: SafeJsonRpcClientOptions = {},
 ): Promise<JsonRpcTestContext<T>> {
   const server = createSafeJsonRpcServer<T>(handler, schema, serverOptions);

package/src/log/console.ts

@@ -7,7 +7,10 @@ import type { LogFn } from './log_fn.js';
  * which can be useful for controlling the format of the output or redirecting logs to a different destination.
  */
 class ConsoleLogger {
-  constructor(private prefix: string, private logger: (...args: any[]) => void = console.log) {}
+  constructor(
+    private prefix: string,
+    private logger: (...args: any[]) => void = console.log,
+  ) {}
 
   /**
    * Log messages with the specified prefix using the provided logger.

package/src/log/gcloud-logger-config.ts

@@ -13,10 +13,6 @@ const GOOGLE_CLOUD_TRACE_SAMPLED = 'logging.googleapis.com/trace_sampled';
  */
 export const GoogleCloudLoggerConfig = {
   messageKey: 'message',
-  // Same as pino.stdTimeFunctions.isoTime but uses "timestamp" key instead of "time"
-  timestamp(): string {
-    return `,"timestamp":"${new Date(Date.now()).toISOString()}"`;
-  },
   formatters: {
     log(object: Record<string, unknown>): Record<string, unknown> {
       // Add trace context attributes following Cloud Logging structured log format described
@@ -39,12 +35,12 @@ export const GoogleCloudLoggerConfig = {
       // Severity labels https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#LogSeverity
       let severity: string;
 
-      switch (label as pino.Level | keyof typeof customLevels) {
+      switch (label as pino.Level | keyof CustomLevels) {
         case 'trace':
         case 'debug':
+        case 'verbose':
           severity = 'DEBUG';
           break;
-        case 'verbose':
         case 'info':
           severity = 'INFO';
           break;
@@ -68,4 +64,4 @@ export const GoogleCloudLoggerConfig = {
 } satisfies pino.LoggerOptions;
 
 // Define custom logging levels for pino. Duplicate from pino-logger.ts.
-const customLevels = { verbose: 25 };
+type CustomLevels = { verbose: 25 };

package/src/log/index.ts

@@ -1,6 +1,6 @@
 export * from './console.js';
-export * from './debug.js';
-export * from './pino-logger.js';
-export * from './log_history.js';
-export * from './log_fn.js';
 export * from './libp2p_logger.js';
+export * from './log_fn.js';
+export * from './noir_debug_log_util.js';
+export * from './pino-logger.js';
+export * from './log-levels.js';

package/src/log/libp2p_logger.ts

@@ -2,15 +2,17 @@ import type { ComponentLogger, Logger } from '@libp2p/interface';
 
 import { getLogLevelFromFilters } from './log-filters.js';
 import type { LogLevel } from './log-levels.js';
-import { logFilters, logger } from './pino-logger.js';
+import { type LoggerBindings, logFilters, logger } from './pino-logger.js';
 
 /**
  * Creates a libp2p compatible logger that wraps our pino logger.
  * This adapter implements the ComponentLogger interface required by libp2p.
+ * @param namespace - Base namespace for the logger
+ * @param bindings - Optional bindings to pass to the logger (actor, instanceId)
  */
-export function createLibp2pComponentLogger(namespace: string): ComponentLogger {
+export function createLibp2pComponentLogger(namespace: string, bindings?: LoggerBindings): ComponentLogger {
   return {
-    forComponent: (component: string) => createLibp2pLogger(`${namespace}:${component}`),
+    forComponent: (component: string) => createLibp2pLogger(`${namespace}:${component}`, bindings),
   };
 }
 
@@ -24,16 +26,21 @@ function replaceFormatting(message: string) {
   return message.replace(/(%p|%a)/g, '%s');
 }
 
-function createLibp2pLogger(component: string): Logger {
+function createLibp2pLogger(component: string, bindings?: LoggerBindings): Logger {
   // Create a direct pino logger instance for libp2p that supports string interpolation
-  const log = logger.child({ module: component }, { level: getLogLevelFromFilters(logFilters, component) });
+  const actor = bindings?.actor;
+  const instanceId = bindings?.instanceId;
+  const log = logger.child(
+    { module: component, ...(actor && { actor }), ...(instanceId && { instanceId }) },
+    { level: getLogLevelFromFilters(logFilters, component) },
+  );
 
   const logIfEnabled = (level: LogLevel, message: string, ...args: unknown[]) => {
     if (!log.isLevelEnabled(level)) {
       return;
     }
 
-    log[level](replaceFormatting(message), ...args);
+    log[level](replaceFormatting(message), ...formatArgs(message, args));
   };
 
   // Default log level is trace as this is super super noisy
@@ -45,7 +52,7 @@ function createLibp2pLogger(component: string): Logger {
     enabled: log.isLevelEnabled('debug'),
     error(message: string, ...args: unknown[]) {
       // We write error outputs as debug as they are often expected, e.g. connection errors can happen in happy paths
-      logIfEnabled('debug', message, ...args);
+      logIfEnabled('debug', `error: ${message}`, ...args);
     },
 
     debug(message: string, ...args: unknown[]) {
@@ -65,3 +72,22 @@ function createLibp2pLogger(component: string): Logger {
     },
   });
 }
+
+function formatArgs(message: string, args: unknown[]) {
+  if (!args) {
+    return args;
+  }
+  return args.map(arg => {
+    if (
+      typeof arg === 'object' &&
+      arg &&
+      'err' in arg &&
+      arg.err instanceof Error &&
+      'type' in arg.err &&
+      arg.err.type === 'AbortError'
+    ) {
+      delete arg.err; // Remove the AbortError from the logs
+    }
+    return arg;
+  });
+}

package/src/log/log_fn.ts

@@ -1,5 +1,5 @@
 /** Structured log data to include with the message. */
-export type LogData = Record<string, string | number | bigint | boolean | { toString(): string } | undefined>;
+export type LogData = Record<string, string | number | bigint | boolean | { toString(): string } | undefined | null>;
 
 /** A callable logger instance. */
 export type LogFn = (msg: string, data?: unknown) => void;

package/src/log/noir_debug_log_util.ts

@@ -0,0 +1,21 @@
+interface Printable {
+  toString(): string;
+}
+
+/**
+ * Format a debug string filling in `'{0}'` entries with their
+ * corresponding values from the args array, amd `'{}'` with the whole array.
+ *
+ * @param formatStr - str of form `'this is a string with some entries like {0} and {1}'`
+ * @param args - array of fields to fill in the string format entries with
+ * @returns formatted string
+ */
+export function applyStringFormatting(formatStr: string, args: Printable[]): string {
+  return formatStr
+    .replace(/{(\d+)}/g, (match, index) => {
+      return typeof args[index] === 'undefined' ? match : args[index].toString();
+    })
+    .replace(/{}/g, (_match, _index) => {
+      return args.toString();
+    });
+}

package/src/log/pino-logger-server.ts

@@ -0,0 +1,25 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+import { type LoggerBindings, addLogBindingsHandler, removeLogBindingsHandler } from './pino-logger.js';
+
+/** AsyncLocalStorage for logger bindings context propagation (Node.js only). */
+const bindingsStorage = new AsyncLocalStorage<LoggerBindings>();
+
+/** Returns the current bindings from AsyncLocalStorage, if any. */
+export function getBindings(): LoggerBindings | undefined {
+  return bindingsStorage.getStore();
+}
+
+/**
+ * Runs a callback within a bindings context. All loggers created within the callback
+ * will automatically inherit the bindings (actor, instanceId) via the log bindings handler.
+ */
+export async function withLoggerBindings<T>(bindings: LoggerBindings, callback: () => Promise<T>): Promise<T> {
+  const handler = () => bindingsStorage.getStore();
+  addLogBindingsHandler(handler);
+  try {
+    return await bindingsStorage.run(bindings, callback);
+  } finally {
+    removeLogBindingsHandler(handler);
+  }
+}