@aztec/foundation 0.0.0-test.0

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

@@ -0,0 +1,376 @@
+import cors from '@koa/cors';
+import http from 'http';
+import { type default as Application, default as Koa } from 'koa';
+import bodyParser from 'koa-bodyparser';
+import compress from 'koa-compress';
+import Router from 'koa-router';
+import type { AddressInfo } from 'net';
+import { format, inspect } from 'util';
+import { ZodError } from 'zod';
+
+import { type Logger, createLogger } from '../../log/index.js';
+import { promiseWithResolvers } from '../../promise/utils.js';
+import { type ApiSchema, type ApiSchemaFor, parseWithOptionals, schemaHasMethod } from '../../schemas/index.js';
+import { jsonStringify } from '../convert.js';
+import { assert } from '../js_utils.js';
+
+export type DiagnosticsData = {
+  id: number | string | null;
+  method: string;
+  params: any[];
+  headers: http.IncomingHttpHeaders;
+};
+
+export type DiagnosticsMiddleware = (ctx: DiagnosticsData, next: () => Promise<void>) => Promise<void>;
+
+export class SafeJsonRpcServer {
+  /**
+   * The HTTP server accepting remote requests.
+   * This member field is initialized when the server is started.
+   */
+  private httpServer?: http.Server;
+
+  constructor(
+    /** 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,
+    /** Health check function */
+    private readonly healthCheck: StatusCheckFn = () => true,
+    /** Additional middlewares */
+    private extraMiddlewares: Application.Middleware[] = [],
+    /** Logger */
+    private log = createLogger('json-rpc:server'),
+  ) {}
+
+  public isHealthy(): boolean | Promise<boolean> {
+    return this.healthCheck();
+  }
+
+  /**
+   * Get an express app object.
+   * @param prefix - Our server prefix.
+   * @returns The app object.
+   */
+  public getApp(prefix = '') {
+    const router = this.getRouter(prefix);
+
+    const exceptionHandler = async (ctx: Koa.Context, next: () => Promise<void>) => {
+      try {
+        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) {
+          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.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 },
+          };
+        } else {
+          ctx.status = 500;
+          ctx.body = { jsonrpc: '2.0', id: null, error: { code: -32600, message: err.message ?? 'Internal error' } };
+        }
+      }
+    };
+
+    const jsonResponse = async (ctx: Koa.Context, next: () => Promise<void>) => {
+      try {
+        await next();
+        if (ctx.body && typeof ctx.body === 'object') {
+          ctx.body = jsonStringify(ctx.body);
+        }
+      } catch (err: any) {
+        ctx.status = 500;
+        ctx.body = { jsonrpc: '2.0', error: { code: -32700, message: `Unable to serialize response: ${err.message}` } };
+      }
+    };
+
+    const app = new Koa();
+    app.on('error', error => {
+      this.log.error(`Error on API handler: ${error}`);
+    });
+
+    app.use(compress({ br: false }));
+    app.use(jsonResponse);
+    for (const middleware of this.extraMiddlewares) {
+      app.use(middleware);
+    }
+    app.use(exceptionHandler);
+    app.use(bodyParser({ jsonLimit: '50mb', enableTypes: ['json'], detectJSON: () => true }));
+    app.use(cors());
+    app.use(router.routes());
+    app.use(router.allowedMethods());
+
+    return app;
+  }
+
+  /**
+   * Get a router object wrapping our RPC class.
+   * @param prefix - The server prefix.
+   * @returns The router object.
+   */
+  private getRouter(prefix: string) {
+    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 } };
+      } else {
+        ctx.status = 200;
+        const result = await this.proxy.call(method, params);
+        ctx.body = { jsonrpc, id, result };
+      }
+    });
+
+    return router;
+  }
+
+  /**
+   * Start this server with koa.
+   * @param port - Port number.
+   * @param prefix - Prefix string.
+   */
+  public start(port: number, prefix = ''): void {
+    if (this.httpServer) {
+      throw new Error('Server is already listening');
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-misused-promises
+    this.httpServer = http.createServer(this.getApp(prefix).callback());
+    this.httpServer.listen(port);
+  }
+
+  /**
+   * Stops the HTTP server
+   */
+  public stop(): Promise<void> {
+    if (!this.httpServer) {
+      return Promise.resolve();
+    }
+
+    const { promise, resolve, reject } = promiseWithResolvers<void>();
+    this.httpServer.close(err => {
+      if (err) {
+        reject(err);
+      } else {
+        resolve();
+      }
+    });
+    return promise;
+  }
+
+  /**
+   * Explicitly calls an RPC method.
+   * @param methodName - The RPC method.
+   * @param jsonParams - The RPC parameters.
+   * @returns The remote result.
+   */
+  public async call(methodName: string, jsonParams: any[] = []) {
+    return await this.proxy.call(methodName, jsonParams);
+  }
+}
+
+export type StatusCheckFn = () => boolean | Promise<boolean>;
+
+interface Proxy {
+  hasMethod(methodName: string): boolean;
+  call(methodName: string, jsonParams?: any[]): Promise<any>;
+}
+
+/**
+ * Forwards calls to a handler. Relies on a schema definition to validate and convert inputs
+ * before forwarding calls, and then converts outputs into JSON using default conversions.
+ */
+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>) {
+    this.schema = schema;
+  }
+
+  /**
+   * Call an RPC method.
+   * @param methodName - The RPC method.
+   * @param jsonParams - The RPC parameters.
+   * @returns The remote result.
+   */
+  public async call(methodName: string, jsonParams: any[] = []) {
+    this.log.debug(format(`request`, methodName, jsonParams));
+
+    assert(Array.isArray(jsonParams), `Params to ${methodName} is not an array: ${jsonParams}`);
+    assert(schemaHasMethod(this.schema, methodName), `Method ${methodName} not found in schema`);
+    const method = this.handler[methodName as keyof T];
+    assert(typeof method === 'function', `Method ${methodName} is not a function`);
+    const args = await parseWithOptionals(jsonParams, this.schema[methodName].parameters());
+    const ret = await method.apply(this.handler, args);
+    this.log.debug(format('response', methodName, ret));
+    return ret;
+  }
+
+  public hasMethod(methodName: string): boolean {
+    return schemaHasMethod(this.schema, methodName) && typeof this.handler[methodName as keyof T] === 'function';
+  }
+}
+
+class NamespacedSafeJsonProxy implements Proxy {
+  private readonly proxies: Record<string, Proxy> = {};
+
+  constructor(handlers: NamespacedApiHandlers) {
+    for (const [namespace, [handler, schema]] of Object.entries(handlers)) {
+      this.proxies[namespace] = new SafeJsonProxy(handler, schema);
+    }
+  }
+
+  public call(namespacedMethodName: string, jsonParams: any[] = []) {
+    const [namespace, methodName] = namespacedMethodName.split('_', 2);
+    assert(namespace && methodName, `Invalid namespaced method name: ${namespacedMethodName}`);
+    const handler = this.proxies[namespace];
+    assert(handler, `Namespace not found: ${namespace}`);
+    return handler.call(methodName, jsonParams);
+  }
+
+  public hasMethod(namespacedMethodName: string): boolean {
+    const [namespace, methodName] = namespacedMethodName.split('_', 2);
+    const handler = this.proxies[namespace];
+    return handler?.hasMethod(methodName);
+  }
+}
+
+export type NamespacedApiHandlers = Record<string, ApiHandler>;
+
+export type ApiHandler<T extends object = any> = [T, ApiSchemaFor<T>, StatusCheckFn?];
+
+export function makeHandler<T extends object>(handler: T, schema: ApiSchemaFor<T>): ApiHandler<T> {
+  return [handler, schema];
+}
+
+function makeAggregateHealthcheck(namedHandlers: NamespacedApiHandlers, log?: Logger): StatusCheckFn {
+  return async () => {
+    try {
+      const results = await Promise.all(
+        Object.entries(namedHandlers).map(([name, [, , healthCheck]]) => [name, healthCheck ? healthCheck() : true]),
+      );
+      const failed = results.filter(([_, result]) => !result);
+      if (failed.length > 0) {
+        log?.warn(`Health check failed for ${failed.map(([name]) => name).join(', ')}`);
+        return false;
+      }
+      return true;
+    } catch (err) {
+      log?.error(`Error during health check`, err);
+      return false;
+    }
+  };
+}
+
+export type SafeJsonRpcServerOptions = {
+  http200OnError: boolean;
+  healthCheck?: StatusCheckFn;
+  log?: Logger;
+  middlewares?: Application.Middleware[];
+};
+
+/**
+ * Creates a single SafeJsonRpcServer from multiple handlers.
+ * @param servers - List of handlers to be combined.
+ * @returns A single JsonRpcServer with namespaced methods.
+ */
+export function createNamespacedSafeJsonRpcServer(
+  handlers: NamespacedApiHandlers,
+  options: Partial<Omit<SafeJsonRpcServerOptions, 'healthcheck'>> = {
+    log: createLogger('json-rpc:server'),
+  },
+): SafeJsonRpcServer {
+  const { middlewares, http200OnError, log } = options;
+  const proxy = new NamespacedSafeJsonProxy(handlers);
+  const healthCheck = makeAggregateHealthcheck(handlers, log);
+  return new SafeJsonRpcServer(proxy, http200OnError, healthCheck, middlewares, log);
+}
+
+export function createSafeJsonRpcServer<T extends object = any>(
+  handler: T,
+  schema: ApiSchemaFor<T>,
+  options: Partial<SafeJsonRpcServerOptions> = {},
+) {
+  const { http200OnError, log, healthCheck, middlewares: extraMiddlewares } = options;
+  const proxy = new SafeJsonProxy(handler, schema);
+  return new SafeJsonRpcServer(proxy, http200OnError, healthCheck, extraMiddlewares, log);
+}
+
+/**
+ * Creates a router for handling a plain status request that will return 200 status when running.
+ * @param getCurrentStatus - List of health check functions to run.
+ * @param apiPrefix - The prefix to use for all api requests
+ * @returns - The router for handling status requests.
+ */
+export function createStatusRouter(getCurrentStatus: StatusCheckFn, apiPrefix = '') {
+  const router = new Router({ prefix: `${apiPrefix}` });
+  router.get('/status', async (ctx: Koa.Context) => {
+    let ok: boolean;
+    try {
+      ok = (await getCurrentStatus()) === true;
+    } catch (err) {
+      ok = false;
+    }
+
+    ctx.status = ok ? 200 : 500;
+  });
+  return router;
+}
+
+/**
+ * Wraps a JsonRpcServer in a nodejs http server and starts it.
+ * Installs a status router that calls to the isHealthy method to the server.
+ * Returns once starts listening unless noWait is set.
+ * @returns A running http server.
+ */
+export async function startHttpRpcServer(
+  rpcServer: Pick<SafeJsonRpcServer, 'getApp' | 'isHealthy'>,
+  options: {
+    host?: string;
+    port?: number | string;
+    apiPrefix?: string;
+    timeoutMs?: number;
+    noWait?: boolean;
+  } = {},
+): Promise<http.Server & { port: number }> {
+  const app = rpcServer.getApp(options.apiPrefix);
+
+  const statusRouter = createStatusRouter(rpcServer.isHealthy.bind(rpcServer), options.apiPrefix);
+  app.use(statusRouter.routes()).use(statusRouter.allowedMethods());
+
+  // eslint-disable-next-line @typescript-eslint/no-misused-promises
+  const httpServer = http.createServer(app.callback());
+  if (options.timeoutMs) {
+    httpServer.timeout = options.timeoutMs;
+  }
+
+  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());
+
+  // Wait until listen callback is called
+  if (!options.noWait) {
+    await promise;
+  }
+
+  const port = (httpServer.address() as AddressInfo).port;
+  return Object.assign(httpServer, { port });
+}

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

@@ -0,0 +1 @@
+export { createJsonRpcTestSetup, type JsonRpcTestContext } from './integration.js';

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

@@ -0,0 +1,35 @@
+import type http from 'http';
+
+import type { ApiSchemaFor } from '../../schemas/api.js';
+import { makeFetch } from '../client/fetch.js';
+import { type SafeJsonRpcClientOptions, createSafeJsonRpcClient } from '../client/safe_json_rpc_client.js';
+import {
+  type SafeJsonRpcServer,
+  type SafeJsonRpcServerOptions,
+  createSafeJsonRpcServer,
+  startHttpRpcServer,
+} from '../server/safe_json_rpc_server.js';
+
+export type JsonRpcTestContext<T extends object> = {
+  server: SafeJsonRpcServer;
+  client: T;
+  httpServer: http.Server & { port: number };
+  url: string;
+};
+
+export async function createJsonRpcTestSetup<T extends object>(
+  handler: T,
+  schema: ApiSchemaFor<T>,
+  serverOptions: Partial<SafeJsonRpcServerOptions> = {},
+  clientOptions: SafeJsonRpcClientOptions = {},
+): Promise<JsonRpcTestContext<T>> {
+  const server = createSafeJsonRpcServer<T>(handler, schema, serverOptions);
+  const httpServer = await startHttpRpcServer(server, { host: '127.0.0.1' });
+  const noRetryFetch = makeFetch([], true);
+  const url = `http://127.0.0.1:${httpServer.port}`;
+  const client = createSafeJsonRpcClient<T>(url, schema, {
+    fetch: noRetryFetch,
+    ...clientOptions,
+  });
+  return { server, client, httpServer, url };
+}

package/src/log/console.ts

@@ -0,0 +1,39 @@
+/* eslint-disable no-console */
+import type { LogFn } from './log_fn.js';
+
+/**
+ * ConsoleLogger is a utility class that provides customizable console logging functionality.
+ * It allows setting a custom prefix for log messages and an optional custom logger function,
+ * 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) {}
+
+  /**
+   * Log messages with the specified prefix using the provided logger.
+   * By default, it uses 'console.log' as the logger but can be overridden
+   * during ConsoleLogger instantiation. This method allows for easy
+   * organization and readability of log messages in the console.
+   *
+   * @param args - The data to be logged, any number of arguments can be passed to this function.
+   */
+  public log(...args: any[]) {
+    this.logger(`${this.prefix}:`, ...args);
+  }
+}
+
+/**
+ * Creates a Logger function with an optional prefix for log messages.
+ * If a prefix is provided, the created logger will prepend it to each log message.
+ * If no prefix is provided, the default console.log will be returned.
+ *
+ * @param prefix - The optional string to prepend to each log message.
+ * @returns A Logger function that accepts any number of arguments and logs them with the specified prefix.
+ */
+export function createConsoleLogger(prefix?: string): LogFn {
+  if (prefix) {
+    const logger = new ConsoleLogger(prefix, console.log);
+    return (...args: any[]) => logger.log(...args);
+  }
+  return console.log;
+}

package/src/log/debug.ts

@@ -0,0 +1,104 @@
+import debug from 'debug';
+
+import type { LogFn } from './log_fn.js';
+
+let preLogHook: ((...args: any[]) => void) | undefined;
+let postLogHook: ((...args: any[]) => void) | undefined;
+
+/**
+ * Process and handle the logging of messages through custom hooks and the given logger.
+ * This function checks if the logger's namespace is enabled, executes any preLogHook functions, logs the message using the provided logger, and then executes any postLogHook functions.
+ *
+ * @param logger - The debug logger instance to be used for logging.
+ * @param args - The arguments to be passed to the logger and any hook functions.
+ */
+function theFunctionThroughWhichAllLogsPass(logger: any, ...args: any[]) {
+  if (!debug.enabled(logger.namespace)) {
+    return;
+  }
+  if (preLogHook) {
+    preLogHook(logger.namespace, ...args);
+  }
+  logger(...args);
+  if (postLogHook) {
+    postLogHook(logger.namespace, ...args);
+  }
+}
+
+/**
+ * Return a logger, meant to be silent by default and verbose during debugging.
+ * @param name - The module name of the logger.
+ * @returns A callable log function.
+ */
+export function createDebugOnlyLogger(name: string): LogFn {
+  const logger = debug(name);
+  return (...args: any[]) => theFunctionThroughWhichAllLogsPass(logger, ...args);
+}
+
+/**
+ * Set a function to be called before each log message is handled by the debug logger.
+ * The hook function will receive the logger namespace and any arguments passed to the logger.
+ * This can be useful for adding additional context, filtering logs, or performing side-effects
+ * based on logged messages.
+ *
+ * @param fn - The function to be called before each log message.
+ */
+export function setPreDebugLogHook(fn: (...args: any[]) => void) {
+  preLogHook = fn;
+}
+
+/**
+ * Set a callback function to be executed after each log is written by the debug logger.
+ * This allows additional behavior or side effects to occur after a log has been written,
+ * such as sending logs to external services, formatting output, or triggering events.
+ *
+ * @param fn - The callback function to be executed after each log. It receives the same arguments as the original log function call.
+ */
+export function setPostDebugLogHook(fn: (...args: any[]) => void) {
+  postLogHook = fn;
+}
+
+/**
+ * Enable logs for the specified namespace(s) or wildcard pattern(s).
+ * This function activates the logging functionality for the given
+ * namespace(s) or pattern(s), allowing developers to selectively display
+ * debug logs that match the provided string(s).
+ *
+ * @param str - The namespace(s) or wildcard pattern(s) for which logs should be enabled.
+ */
+export function enableLogs(str: string) {
+  debug.enable(str);
+}
+
+/**
+ * Check if the logging is enabled for a given namespace.
+ * The input 'str' represents the namespace for which the log status is being checked.
+ * Returns true if the logging is enabled, otherwise false.
+ *
+ * @param str - The namespace string used to determine if logging is enabled.
+ * @returns A boolean indicating whether logging is enabled for the given namespace.
+ */
+export function isLogEnabled(str: string) {
+  return debug.enabled(str);
+}
+
+/**
+ * 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
+ */
+interface Printable {
+  toString(): 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/gcloud-logger-config.ts

@@ -0,0 +1,71 @@
+import type { pino } from 'pino';
+
+/* eslint-disable camelcase */
+
+const GOOGLE_CLOUD_TRACE_ID = 'logging.googleapis.com/trace';
+const GOOGLE_CLOUD_SPAN_ID = 'logging.googleapis.com/spanId';
+const GOOGLE_CLOUD_TRACE_SAMPLED = 'logging.googleapis.com/trace_sampled';
+
+/**
+ * Pino configuration for google cloud observability. Tweaks message and timestamp,
+ * adds trace context attributes, and injects severity level.
+ * Adapted from https://cloud.google.com/trace/docs/setup/nodejs-ot#config-structured-logging.
+ */
+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
+      // in https://cloud.google.com/logging/docs/structured-logging#special-payload-fields
+      const { trace_id, span_id, trace_flags, ...rest } = object;
+
+      if (trace_id && span_id) {
+        return {
+          [GOOGLE_CLOUD_TRACE_ID]: trace_id,
+          [GOOGLE_CLOUD_SPAN_ID]: span_id,
+          [GOOGLE_CLOUD_TRACE_SAMPLED]: trace_flags ? trace_flags === '01' : undefined,
+          trace_flags, // Keep the original trace_flags for otel-pino-stream
+          ...rest,
+        };
+      }
+      return object;
+    },
+    level(label: string, level: number): object {
+      // Inspired by https://github.com/pinojs/pino/issues/726#issuecomment-605814879
+      // 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) {
+        case 'trace':
+        case 'debug':
+          severity = 'DEBUG';
+          break;
+        case 'verbose':
+        case 'info':
+          severity = 'INFO';
+          break;
+        case 'warn':
+          severity = 'WARNING';
+          break;
+        case 'error':
+          severity = 'ERROR';
+          break;
+        case 'fatal':
+          severity = 'CRITICAL';
+          break;
+        default:
+          severity = 'DEFAULT';
+          break;
+      }
+
+      return { severity, level };
+    },
+  },
+} satisfies pino.LoggerOptions;
+
+// Define custom logging levels for pino. Duplicate from pino-logger.ts.
+const customLevels = { verbose: 25 };

package/src/log/index.ts

@@ -0,0 +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';