@aztec/foundation 0.22.0 → 0.24.0

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

@@ -0,0 +1,60 @@
+import { format } from 'util';
+
+import { createDebugLogger } from '../../log/index.js';
+import { ClassConverter, JsonClassConverterInput, StringClassConverterInput } from '../class_converter.js';
+import { convertFromJsonObj, convertToJsonObj } from '../convert.js';
+import { assert, hasOwnProperty } from '../js_utils.js';
+
+const debug = createDebugLogger('json-rpc:json_proxy');
+
+/**
+ * A map of class names to class constructors.
+ */
+export type ClassMaps = {
+  /** The String class map */
+  stringClassMap: StringClassConverterInput;
+  /** The object class map */
+  objectClassMap: JsonClassConverterInput;
+};
+
+/**
+ * Handles conversion of objects over the write.
+ * Delegates to a ClassConverter object.
+ */
+export class JsonProxy {
+  classConverter: ClassConverter;
+  constructor(
+    private handler: object,
+    private stringClassMap: StringClassConverterInput,
+    private objectClassMap: JsonClassConverterInput,
+  ) {
+    this.classConverter = new ClassConverter(stringClassMap, objectClassMap);
+  }
+  /**
+   * Call an RPC method.
+   * @param methodName - The RPC method.
+   * @param jsonParams - The RPG parameters.
+   * @param skipConversion - Whether to skip conversion of the parameters.
+   * @returns The remote result.
+   */
+  public async call(methodName: string, jsonParams: any[] = [], skipConversion = false) {
+    debug(format(`JsonProxy:call`, methodName, jsonParams));
+    // Get access to our class members
+    const proto = Object.getPrototypeOf(this.handler);
+    assert(hasOwnProperty(proto, methodName), `JsonProxy: Method ${methodName} not found!`);
+    assert(Array.isArray(jsonParams), `JsonProxy: ${methodName} params not an array: ${jsonParams}`);
+    // convert the params from json representation to classes
+    let convertedParams = jsonParams;
+    if (!skipConversion) {
+      convertedParams = jsonParams.map(param => convertFromJsonObj(this.classConverter, param));
+    }
+    debug(format('JsonProxy:call', methodName, '<-', convertedParams));
+    const rawRet = await (this.handler as any)[methodName](...convertedParams);
+    let ret = rawRet;
+    if (!skipConversion) {
+      ret = convertToJsonObj(this.classConverter, rawRet);
+    }
+    debug(format('JsonProxy:call', methodName, '->', ret));
+    return ret;
+  }
+}

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

@@ -0,0 +1,269 @@
+import cors from '@koa/cors';
+import http from 'http';
+import Koa from 'koa';
+import bodyParser from 'koa-bodyparser';
+import compress from 'koa-compress';
+import Router from 'koa-router';
+
+import { createDebugLogger } from '../../log/index.js';
+import { JsonClassConverterInput, StringClassConverterInput } from '../class_converter.js';
+import { convertBigintsInObj } from '../convert.js';
+import { ClassMaps, JsonProxy } from './json_proxy.js';
+
+/**
+ * JsonRpcServer.
+ * Minimal, dev-friendly mechanism to create a server from an object.
+ */
+export class JsonRpcServer {
+  /**
+   * The proxy object.
+   */
+  public proxy: JsonProxy;
+  constructor(
+    private handler: object,
+    private stringClassMap: StringClassConverterInput,
+    private objectClassMap: JsonClassConverterInput,
+    /** List of methods to disallow from calling remotely */
+    public readonly disallowedMethods: string[] = [],
+    private log = createDebugLogger('aztec:foundation:json-rpc:server'),
+  ) {
+    this.proxy = new JsonProxy(handler, stringClassMap, objectClassMap);
+  }
+
+  /**
+   * 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) {
+        this.log.error(err);
+        if (err instanceof SyntaxError) {
+          ctx.status = 400;
+          ctx.body = {
+            jsonrpc: '2.0',
+            id: null,
+            error: {
+              code: -32700,
+              message: 'Parse error',
+            },
+          };
+        } else {
+          ctx.status = 500;
+          ctx.body = {
+            jsonrpc: '2.0',
+            id: null,
+            error: {
+              code: -32603,
+              message: 'Internal error',
+            },
+          };
+        }
+      }
+    };
+    const app = new Koa();
+    app.on('error', error => {
+      this.log.error(`Error on API handler: ${error}`);
+    });
+    app.use(exceptionHandler);
+    app.use(compress({ br: false } as any));
+    app.use(
+      bodyParser({
+        jsonLimit: '10mb',
+        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 });
+    const proto = Object.getPrototypeOf(this.handler);
+    // "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;
+      // Ignore if not a function
+      if (method === 'constructor' || typeof proto[method] !== 'function' || this.disallowedMethods.includes(method)) {
+        ctx.status = 400;
+        ctx.body = {
+          jsonrpc,
+          id,
+          error: {
+            code: -32601,
+            message: `Method not found: ${method}`,
+          },
+        };
+      } else {
+        try {
+          const result = await this.proxy.call(method, params);
+          ctx.body = {
+            jsonrpc,
+            id,
+            result: convertBigintsInObj(result),
+          };
+          ctx.status = 200;
+        } catch (err: any) {
+          // Propagate the error message to the client. Plenty of the errors are expected to occur (e.g. adding
+          // a duplicate recipient) so this is necessary.
+          ctx.status = 400;
+          ctx.body = {
+            jsonrpc,
+            id,
+            error: {
+              // TODO assign error codes - https://github.com/AztecProtocol/aztec-packages/issues/2633
+              code: -32000,
+              message: err.message,
+            },
+          };
+        }
+      }
+    });
+
+    return router;
+  }
+
+  /**
+   * Start this server with koa.
+   * @param port - Port number.
+   * @param prefix - Prefix string.
+   */
+  public start(port: number, prefix = '') {
+    const httpServer = http.createServer(this.getApp(prefix).callback());
+    httpServer.listen(port);
+  }
+
+  /**
+   * Get a list of methods.
+   * @returns A list of methods.
+   */
+  public getMethods(): string[] {
+    return Object.getOwnPropertyNames(Object.getPrototypeOf(this.handler));
+  }
+
+  /**
+   * Gets the class maps that were used to create the proxy.
+   * @returns The string & object class maps.
+   */
+  public getClassMaps(): ClassMaps {
+    return { stringClassMap: this.stringClassMap, objectClassMap: this.objectClassMap };
+  }
+
+  /**
+   * Call an RPC method.
+   * @param methodName - The RPC method.
+   * @param jsonParams - The RPG parameters.
+   * @param skipConversion - Whether to skip conversion of the parameters.
+   * @returns The remote result.
+   */
+  public async call(methodName: string, jsonParams: any[] = [], skipConversion: boolean) {
+    return await this.proxy.call(methodName, jsonParams, skipConversion);
+  }
+}
+
+/**
+ * Creates a router for handling a plain status request that will return 200 status when running.
+ * @param apiPrefix - The prefix to use for all api requests
+ * @returns - The router for handling status requests.
+ */
+export function createStatusRouter(apiPrefix = '') {
+  const router = new Router({ prefix: `${apiPrefix}` });
+  router.get('/status', (ctx: Koa.Context) => {
+    ctx.status = 200;
+  });
+  return router;
+}
+
+/**
+ * Creates an http server that forwards calls to the underlying instance and starts it on the given port.
+ * @param instance - Instance to wrap in a JSON-RPC server.
+ * @param jsonRpcFactoryFunc - Function that wraps the instance in a JSON-RPC server.
+ * @param port - Port to listen in.
+ * @returns A running http server.
+ */
+export function startHttpRpcServer<T>(
+  name: string,
+  instance: T,
+  jsonRpcFactoryFunc: (instance: T) => JsonRpcServer,
+  port: string | number,
+): http.Server {
+  const rpcServer = jsonRpcFactoryFunc(instance);
+
+  const namespacedServer = createNamespacedJsonRpcServer([{ [name]: rpcServer }]);
+
+  const app = namespacedServer.getApp();
+
+  const httpServer = http.createServer(app.callback());
+  httpServer.listen(port);
+
+  return httpServer;
+}
+/**
+ * List of namespace to server instance.
+ */
+export type ServerList = {
+  /** name of the service to be used for namespacing */
+  [name: string]: JsonRpcServer;
+}[];
+
+/**
+ * Creates a single JsonRpcServer from multiple servers.
+ * @param servers - List of servers to be combined into a single server, passed as ServerList.
+ * @returns A single JsonRpcServer with namespaced methods.
+ */
+export function createNamespacedJsonRpcServer(
+  servers: ServerList,
+  log = createDebugLogger('aztec:foundation:json-rpc:multi-server'),
+): JsonRpcServer {
+  const handler = {} as any;
+  const disallowedMethods: string[] = [];
+  const classMapsArr: ClassMaps[] = [];
+
+  for (const serverEntry of servers) {
+    const [namespace, server] = Object.entries(serverEntry)[0];
+    const serverMethods = server.getMethods();
+
+    for (const method of serverMethods) {
+      const namespacedMethod = `${namespace}_${method}`;
+
+      handler[namespacedMethod] = (...args: any[]) => {
+        return server.call(method, args, true);
+      };
+    }
+
+    // get the combined disallowed methods from all servers.
+    disallowedMethods.push(...server.disallowedMethods.map(method => `${namespace}_${method}`));
+    // get the combined classmaps from all servers.
+    const classMap = server.getClassMaps();
+    classMapsArr.push({
+      stringClassMap: classMap.stringClassMap,
+      objectClassMap: classMap.objectClassMap,
+    });
+  }
+
+  // Get the combined stringClassMap & objectClassMap from all servers
+  const classMaps = classMapsArr.reduce(
+    (acc, curr) => {
+      return {
+        stringClassMap: { ...acc.stringClassMap, ...curr.stringClassMap },
+        objectClassMap: { ...acc.objectClassMap, ...curr.objectClassMap },
+      };
+    },
+    { stringClassMap: {}, objectClassMap: {} } as ClassMaps,
+  );
+
+  return new JsonRpcServer(Object.create(handler), classMaps.stringClassMap, classMaps.objectClassMap, [], log);
+}

package/src/log/console.ts

@@ -0,0 +1,39 @@
+/* eslint-disable no-console */
+import { 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,83 @@
+import debug from 'debug';
+
+import { 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);
+}

package/src/log/index.ts

@@ -0,0 +1,5 @@
+export * from './console.js';
+export * from './debug.js';
+export * from './logger.js';
+export * from './log_history.js';
+export * from './log_fn.js';

package/src/log/log_fn.ts

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

package/src/log/log_history.ts

@@ -0,0 +1,44 @@
+import { setPreDebugLogHook } from './debug.js';
+
+/**
+ * LogHistory is a utility class that provides the ability to store and manage debug logs.
+ * It can be enabled to record logs along with their timestamps, retrieve a specified number
+ * of recent logs, or clear stored logs based on a given count. This can be useful for debugging
+ * purposes, monitoring application activities, and maintaining log history.
+ */
+export class LogHistory {
+  private logs: any[][] = [];
+
+  /**
+   * Enables the logging of debug messages with timestamps.
+   * Hooks into the pre-debug log and stores each log entry along with its timestamp in the logs array.
+   */
+  public enable() {
+    setPreDebugLogHook((...args: any[]) => {
+      this.logs.push([new Date().toISOString(), ...args]);
+    });
+  }
+
+  /**
+   * Retrieves a specified number of logs from the end of the log history or all logs if no argument is provided.
+   * The logs are ordered chronologically, with the oldest logs at the beginning of the array.
+   *
+   * @param last - Optional number representing the amount of recent logs to return. Defaults to 0, which returns all logs.
+   * @returns An array of log arrays, each containing a timestamp and log arguments.
+   */
+  public getLogs(last = 0) {
+    return last ? this.logs.slice(-last) : this.logs;
+  }
+
+  /**
+   * Clear a specified number of logs from the beginning of the logs array.
+   * If no count is provided, it will clear all logs.
+   *
+   * @param count - The number of logs to be removed (default: total logs length).
+   */
+  public clear(count = this.logs.length) {
+    this.logs = this.logs.slice(count);
+  }
+}
+
+export const logHistory = new LogHistory();

package/src/log/logger.ts

@@ -0,0 +1,137 @@
+import debug from 'debug';
+import isNode from 'detect-node';
+import { isatty } from 'tty';
+
+import { LogData, LogFn } from './log_fn.js';
+
+// Matches a subset of Winston log levels
+const LogLevels = ['silent', 'error', 'warn', 'info', 'verbose', 'debug'] as const;
+const DefaultLogLevel = process.env.NODE_ENV === 'test' ? ('silent' as const) : ('info' as const);
+
+/**
+ * A valid log severity level.
+ */
+export type LogLevel = (typeof LogLevels)[number];
+
+const envLogLevel = process.env.LOG_LEVEL?.toLowerCase() as LogLevel;
+const currentLevel = LogLevels.includes(envLogLevel) ? envLogLevel : DefaultLogLevel;
+
+/** Log function that accepts an exception object */
+type ErrorLogFn = (msg: string, err?: Error | unknown, data?: LogData) => void;
+
+/**
+ * Logger that supports multiple severity levels.
+ */
+export type Logger = { [K in LogLevel]: LogFn } & { /** Error log function */ error: ErrorLogFn };
+
+/**
+ * Logger that supports multiple severity levels and can be called directly to issue a debug statement.
+ * Intended as a drop-in replacement for the debug module.
+ */
+export type DebugLogger = LogFn & Logger;
+
+/**
+ * Creates a new DebugLogger for the current module, defaulting to the LOG_LEVEL env var.
+ * If DEBUG="[module]" env is set, will enable debug logging if the module matches.
+ * Uses npm debug for debug level and console.error for other levels.
+ * @param name - Name of the module.
+ * @returns A debug logger.
+ */
+export function createDebugLogger(name: string): DebugLogger {
+  const debugLogger = debug(name);
+  if (currentLevel === 'debug') {
+    debugLogger.enabled = true;
+  }
+
+  const logger = {
+    silent: () => {},
+    error: (msg: string, err?: unknown, data?: LogData) => logWithDebug(debugLogger, 'error', fmtErr(msg, err), data),
+    warn: (msg: string, data?: LogData) => logWithDebug(debugLogger, 'warn', msg, data),
+    info: (msg: string, data?: LogData) => logWithDebug(debugLogger, 'info', msg, data),
+    verbose: (msg: string, data?: LogData) => logWithDebug(debugLogger, 'verbose', msg, data),
+    debug: (msg: string, data?: LogData) => logWithDebug(debugLogger, 'debug', msg, data),
+  };
+  return Object.assign((msg: string, data?: LogData) => logWithDebug(debugLogger, 'debug', msg, data), logger);
+}
+
+/** A callback to capture all logs. */
+export type LogHandler = (level: LogLevel, namespace: string, msg: string, data?: LogData) => void;
+
+const logHandlers: LogHandler[] = [];
+
+/**
+ * Registers a callback for all logs, whether they are emitted in the current log level or not.
+ * @param handler - Callback to be called on every log.
+ */
+export function onLog(handler: LogHandler) {
+  logHandlers.push(handler);
+}
+
+/**
+ * Logs args to npm debug if enabled or log level is debug, console.error otherwise.
+ * @param debug - Instance of npm debug.
+ * @param level - Intended log level.
+ * @param args - Args to log.
+ */
+function logWithDebug(debug: debug.Debugger, level: LogLevel, msg: string, data?: LogData) {
+  for (const handler of logHandlers) {
+    handler(level, debug.namespace, msg, data);
+  }
+
+  msg = data ? `${msg} ${fmtLogData(data)}` : msg;
+  if (debug.enabled) {
+    if (level !== 'debug') {
+      msg = `${level.toUpperCase()} ${msg}`;
+    }
+    debug(msg);
+  } else if (LogLevels.indexOf(level) <= LogLevels.indexOf(currentLevel)) {
+    printLog(`${getPrefix(debug, level)} ${msg}`);
+  }
+}
+
+/**
+ * Returns a log prefix that emulates that of npm debug. Uses colors if in node and in a tty.
+ * @param debugLogger - Instance of npm debug logger.
+ * @param level - Intended log level (printed out if strictly above current log level).
+ * @returns Log prefix.
+ */
+function getPrefix(debugLogger: debug.Debugger, level: LogLevel) {
+  const levelLabel = currentLevel !== level ? ` ${level.toUpperCase()}` : '';
+  const prefix = `${debugLogger.namespace.replace(/^aztec:/, '')}${levelLabel}`;
+  if (!isNode || !isatty(process.stderr.fd)) {
+    return prefix;
+  }
+  const colorIndex = debug.selectColor(debugLogger.namespace) as number;
+  const colorCode = '\u001B[3' + (colorIndex < 8 ? colorIndex : '8;5;' + colorIndex);
+  return `  ${colorCode};1m${prefix}\u001B[0m`;
+}
+
+/**
+ * Outputs to console error.
+ * @param msg - What to log.
+ */
+function printLog(msg: string) {
+  // eslint-disable-next-line no-console
+  console.error(msg);
+}
+
+/**
+ * Concatenates a log message and an exception.
+ * @param msg - Log message
+ * @param err - Error to log
+ * @returns A string with both the log message and the error message.
+ */
+function fmtErr(msg: string, err?: Error | unknown): string {
+  const errStr = err && [(err as Error).name, (err as Error).message].filter(x => !!x).join(' ');
+  return err ? `${msg}: ${errStr || err}` : msg;
+}
+
+/**
+ * Formats structured log data as a string for console output.
+ * @param data - Optional log data.
+ */
+function fmtLogData(data?: LogData): string {
+  return Object.entries(data ?? {})
+    .map(([key, value]) => `${key}=${value}`)
+    .join(' ');
+}