@aztec/foundation 0.1.0-alpha10

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

@@ -0,0 +1,23 @@
+import request from 'supertest';
+import { TestState, TestNote } from '../fixtures/test_state.js';
+import { JsonRpcServer } from './json_rpc_server.js';
+
+test('test an RPC function with a primitive parameter', async () => {
+  const server = new JsonRpcServer(new TestState([new TestNote('a'), new TestNote('b')]), { TestNote }, {}, true);
+  const response = await request(server.getApp().callback())
+    .post('/getNote')
+    .send({ params: [0] });
+  expect(response.status).toBe(200);
+  expect(response.text).toBe(JSON.stringify({ result: JSON.stringify({ type: 'TestNote', data: 'a' }) }));
+});
+
+test('test an RPC function with an array of classes', async () => {
+  const server = new JsonRpcServer(new TestState([]), { TestNote }, {}, true);
+  const response = await request(server.getApp().callback())
+    .post('/addNotes')
+    .send({
+      params: [[{ data: 'a' }, { data: 'b' }, { data: 'c' }]],
+    });
+  expect(response.status).toBe(200);
+  expect(response.text).toBe(JSON.stringify({ result: JSON.stringify([{ data: 'a' }, { data: 'b' }, { data: 'c' }]) }));
+});

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

@@ -0,0 +1,124 @@
+import http from 'http';
+import Router from 'koa-router';
+import cors from '@koa/cors';
+import compress from 'koa-compress';
+import Koa from 'koa';
+import bodyParser from 'koa-bodyparser';
+
+import { createLogger } from '../../log/index.js';
+import { ClassConverterInput } from '../class_converter.js';
+import { JsonProxy } from './json_proxy.js';
+import { JsonStringify } from '../convert.js';
+
+/**
+ * JsonRpcServer.
+ * Minimal, dev-friendly mechanism to create a server from an object.
+ */
+export class JsonRpcServer {
+  proxy: JsonProxy;
+  constructor(
+    private handler: object,
+    stringClassMap: ClassConverterInput,
+    objectClassMap: ClassConverterInput,
+    private createApi: boolean,
+    private disallowedMethods: string[] = [],
+    private log = createLogger('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(err);
+        ctx.status = 400;
+        ctx.body = { error: err.message };
+      }
+    };
+    const app = new Koa();
+    app.on('error', error => {
+      this.log(`KOA app-level error. ${JsonStringify({ error })}`);
+    });
+    app.use(compress({ br: false } as any));
+    app.use(bodyParser());
+    app.use(cors());
+    app.use(exceptionHandler);
+    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);
+    // Find all our endpoints from the handler methods
+
+    if (this.createApi) {
+      // "API mode" where an endpoint is created for each method
+      for (const method of Object.getOwnPropertyNames(proto)) {
+        // Ignore if not a function or function is not allowed
+        if (
+          method === 'constructor' ||
+          typeof proto[method] !== 'function' ||
+          this.disallowedMethods.includes(method)
+        ) {
+          continue;
+        }
+        router.post(`/${method}`, async (ctx: Koa.Context) => {
+          const { params = [], jsonrpc, id } = ctx.request.body as any;
+          const result = await this.proxy.call(method, params);
+          ctx.body = { jsonrpc, id, result: JsonStringify(result) };
+          ctx.status = 200;
+        });
+      }
+    } else {
+      // "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 = { error: `Invalid method name: ${method}` };
+        }
+        const result = await this.proxy.call(method, params);
+
+        ctx.body = {
+          jsonrpc,
+          id,
+          result: JsonStringify(result),
+        };
+        ctx.status = 200;
+      });
+    }
+
+    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);
+  }
+}

package/src/log/console.ts

@@ -0,0 +1,45 @@
+/* eslint-disable no-console */
+
+/**
+ * Logger is a utility type that represents a logging function that accepts any number of arguments.
+ * It is used to provide customizable logging functionality, allowing developers to easily log messages
+ * with optional prefixes and custom formatting or output destinations.
+ */
+export type Logger = (...args: any[]) => void;
+
+/**
+ * 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 createLogger(prefix?: string): Logger {
+  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,86 @@
+import debug from 'debug';
+
+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);
+  }
+}
+
+/**
+ * A debug logger.
+ */
+export type DebugLogger = (...args: any[]) => void;
+
+/**
+ * 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 createDebugLogger(name: string): DebugLogger {
+  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,3 @@
+export * from './console.js';
+export * from './debug.js';
+export * from './log_history.js';

package/src/log/log_history.test.ts

@@ -0,0 +1,87 @@
+import { jest } from '@jest/globals';
+import { createDebugLogger, enableLogs } from './debug.js';
+import { LogHistory } from './log_history.js';
+
+jest.useFakeTimers({ doNotFake: ['performance'] });
+
+describe('log history', () => {
+  let debug: (...any: any) => void;
+  let logHistory: LogHistory;
+  const timestemp = new Date().toISOString();
+  const name = 'test:a';
+
+  beforeEach(() => {
+    debug = createDebugLogger(name);
+    enableLogs(name);
+    logHistory = new LogHistory();
+  });
+
+  it('keeps debug logs', () => {
+    logHistory.enable();
+    expect(logHistory.getLogs()).toEqual([]);
+    debug('0');
+    debug('1', 2);
+    debug('2', { key: ['value'] }, Buffer.alloc(2));
+    expect(logHistory.getLogs()).toEqual([
+      [timestemp, name, '0'],
+      [timestemp, name, '1', 2],
+      [timestemp, name, '2', { key: ['value'] }, Buffer.alloc(2)],
+    ]);
+  });
+
+  it('does not keep logs if not enabled', () => {
+    debug('0');
+    debug('1', 2);
+    expect(logHistory.getLogs()).toEqual([]);
+  });
+
+  it('returns last n logs', () => {
+    logHistory.enable();
+    expect(logHistory.getLogs()).toEqual([]);
+    debug('0');
+    debug('1');
+    debug('2');
+    debug('3');
+    debug('4');
+    expect(logHistory.getLogs(2)).toEqual([
+      [timestemp, name, '3'],
+      [timestemp, name, '4'],
+    ]);
+  });
+
+  it('only keeps logs with enabled namespace', () => {
+    logHistory.enable();
+    const name2 = 'test:b';
+    const debug2 = createDebugLogger(name2);
+    debug('0');
+    debug2('zero');
+    expect(logHistory.getLogs()).toEqual([[timestemp, name, '0']]);
+
+    enableLogs(`${name},${name2}`);
+    debug('1', 2);
+    debug2('one', 3);
+    expect(logHistory.getLogs()).toEqual([
+      [timestemp, name, '0'],
+      [timestemp, name, '1', 2],
+      [timestemp, name2, 'one', 3],
+    ]);
+  });
+
+  it('clears all logs', () => {
+    logHistory.enable();
+    debug('0');
+    debug('1');
+    debug('2');
+    logHistory.clear();
+    expect(logHistory.getLogs()).toEqual([]);
+  });
+
+  it('clears first n logs', () => {
+    logHistory.enable();
+    debug('0');
+    debug('1');
+    debug('2');
+    logHistory.clear(2);
+    expect(logHistory.getLogs()).toEqual([[timestemp, name, '2']]);
+  });
+});

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/mutex/index.ts

@@ -0,0 +1,83 @@
+import { MutexDatabase } from './mutex_database.js';
+
+export * from './mutex_database.js';
+
+/**
+ * Mutex class provides a mutual exclusion mechanism for critical sections of code using a named lock.
+ * The lock is acquired and released via the `lock` and `unlock` methods. Locks can be optionally pinged
+ * to keep them alive when they are held for longer durations, avoiding unintended release due to timeouts.
+ *
+ * The underlying lock state is managed in a MutexDatabase instance which can be shared across multiple Mutex instances.
+ * This allows for synchronization between different parts of an application or even across different instances of an application.
+ *
+ * @example
+ * const mutex = new Mutex(mutexDatabase, 'myLock');
+ * await mutex.lock();
+ * // Critical section here
+ * await mutex.unlock();
+ */
+export class Mutex {
+  private id = 0;
+  private pingTimeout!: NodeJS.Timeout;
+
+  constructor(
+    private readonly db: MutexDatabase,
+    private readonly name: string,
+    private readonly timeout = 5000,
+    private readonly tryLockInterval = 2000,
+    private readonly pingInterval = 2000,
+  ) {}
+
+  /**
+   * Acquire a lock on the mutex. If 'untilAcquired' is true, the method will keep trying to acquire the lock until it
+   * successfully acquires it. If 'untilAcquired' is false, the method will try to acquire the lock once and return
+   * immediately with a boolean indicating if the lock has been acquired or not.
+   *
+   * @param untilAcquired - Optional parameter, set to true by default. If true, the method will keep trying to acquire the lock until success. If false, the method will try only once and return a boolean value.
+   * @returns A Promise that resolves to true if the lock has been acquired, or false when 'untilAcquired' is false and the lock could not be immediately acquired.
+   */
+  public async lock(untilAcquired = true) {
+    while (true) {
+      if (await this.db.acquireLock(this.name, this.timeout)) {
+        const id = this.id;
+        this.pingTimeout = setTimeout(() => this.ping(id), this.pingInterval);
+        return true;
+      }
+
+      if (!untilAcquired) {
+        return false;
+      }
+      await new Promise(resolve => setTimeout(resolve, this.tryLockInterval));
+    }
+  }
+
+  /**
+   * Unlocks the mutex, allowing other instances to acquire the lock.
+   * This method also clears the internal ping timeout and increments the internal ID
+   * to ensure stale pings do not extend the lock after it has been released.
+   *
+   * @returns A promise that resolves once the lock has been released in the database.
+   */
+  public async unlock() {
+    clearTimeout(this.pingTimeout);
+    this.id++;
+    await this.db.releaseLock(this.name);
+  }
+
+  /**
+   * Periodically extends the lock's lifetime by updating the database record with a new expiration time.
+   * This method is called recursively using setTimeout. If the id passed to the ping method does not match
+   * the current lock instance's id, it means the lock has been released or acquired by another instance
+   * and the ping should not proceed further.
+   *
+   * @param id - The id of the current lock instance.
+   */
+  private async ping(id: number) {
+    if (id !== this.id) {
+      return;
+    }
+
+    await this.db.extendLock(this.name, this.timeout);
+    this.pingTimeout = setTimeout(() => this.ping(id), this.pingInterval);
+  }
+}

package/src/mutex/mutex.test.ts

@@ -0,0 +1,75 @@
+import { jest } from '@jest/globals';
+import { Mutex } from './index.js';
+import { MutexDatabase } from './mutex_database.js';
+
+/**
+ * Sleep function for introducing a delay in the execution of code.
+ * Returns a Promise that resolves after the specified number of milliseconds.
+ *
+ * @param ms - The number of milliseconds to pause the execution.
+ * @returns A Promise that resolves after the specified delay.
+ */
+export function sleep(ms: number) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Type that transforms the properties of an object into jest.Mock instances,
+ * allowing for easy mocking and testing of functions and methods.
+ */
+type Mockify<T> = {
+  [P in keyof T]: jest.Mock;
+};
+
+describe('mutex', () => {
+  let db: Mockify<MutexDatabase>;
+  let mutex: Mutex;
+  const mutexName = 'test-mutex';
+  const timeout = 500;
+  const tryLockInterval = 100;
+  const pingInterval = 200;
+
+  beforeEach(() => {
+    db = {
+      acquireLock: jest.fn().mockImplementation(() => false),
+      extendLock: jest.fn().mockImplementation(() => {
+        (db.acquireLock.mockResolvedValueOnce as any)(false);
+      }),
+      releaseLock: jest.fn().mockImplementation(() => {
+        (db.acquireLock.mockResolvedValueOnce as any)(true);
+      }),
+    } as any;
+    (db.acquireLock.mockResolvedValueOnce as any)(true);
+
+    mutex = new Mutex(db as MutexDatabase, mutexName, timeout, tryLockInterval, pingInterval);
+  });
+
+  it('cannot lock if locked', async () => {
+    const result: string[] = [];
+    const fn1 = async (runAfterLocked: () => Promise<void>) => {
+      await mutex.lock();
+      const pm = runAfterLocked();
+      await sleep(500);
+      result.push('fn1');
+      await mutex.unlock();
+      return pm;
+    };
+
+    const fn2 = async () => {
+      await mutex.lock();
+      result.push('fn2');
+      await mutex.unlock();
+    };
+
+    await fn1(fn2);
+    expect(result).toEqual(['fn1', 'fn2']);
+  });
+
+  it('automatically extend the expiry time of the lock', async () => {
+    await mutex.lock();
+    await sleep(1000);
+    await mutex.unlock();
+
+    expect(db.extendLock).toHaveBeenCalledWith(mutexName, timeout);
+  });
+});

package/src/mutex/mutex_database.ts

@@ -0,0 +1,9 @@
+/**
+ * Represents a mutual exclusion (mutex) database interface.
+ * Provides functionality for acquiring, extending, and releasing locks on resources to ensure exclusive access and prevent conflicts in concurrent applications.
+ */
+export interface MutexDatabase {
+  acquireLock(name: string, timeout: number): Promise<boolean>;
+  extendLock(name: string, timeout: number): Promise<void>;
+  releaseLock(name: string): Promise<void>;
+}

package/src/retry/index.ts

@@ -0,0 +1,78 @@
+import { createLogger } from '../log/index.js';
+import { sleep } from '../sleep/index.js';
+import { Timer } from '../timer/index.js';
+
+/**
+ * Generates a backoff sequence for retrying operations with an increasing delay.
+ * The backoff sequence follows this pattern: 1, 1, 1, 2, 4, 8, 16, 32, 64, ...
+ * This generator can be used in combination with the `retry` function to perform
+ * retries with exponential backoff and capped at 64 seconds between attempts.
+ *
+ * @returns A generator that yields the next backoff value in seconds as an integer.
+ */
+export function* backoffGenerator() {
+  const v = [1, 1, 1, 2, 4, 8, 16, 32, 64];
+  let i = 0;
+  while (true) {
+    yield v[Math.min(i++, v.length - 1)];
+  }
+}
+
+/**
+ * Retry a given asynchronous function with a specific backoff strategy, until it succeeds or backoff generator ends.
+ * It logs the error and retry interval in case an error is caught. The function can be named for better log output.
+ *
+ * @param fn - The asynchronous function to be retried.
+ * @param name - The optional name of the operation, used for logging purposes.
+ * @param backoff - The optional backoff generator providing the intervals in seconds between retries. Defaults to a predefined series.
+ * @param log - Logger to use for logging.
+ * @returns A Promise that resolves with the successful result of the provided function, or rejects if backoff generator ends.
+ */
+export async function retry<Result>(
+  fn: () => Promise<Result>,
+  name = 'Operation',
+  backoff = backoffGenerator(),
+  log = createLogger('aztec:foundation:retry'),
+) {
+  while (true) {
+    try {
+      return await fn();
+    } catch (err: any) {
+      const s = backoff.next().value;
+      if (s === undefined) {
+        throw err;
+      }
+      log(`${name} failed. Will retry in ${s}s...`);
+      log(err);
+      await sleep(s * 1000);
+      continue;
+    }
+  }
+}
+
+/**
+ * Retry an asynchronous function until it returns a truthy value or the specified timeout is exceeded.
+ * The function is retried periodically with a fixed interval between attempts. The operation can be named for better error messages.
+ * Will never timeout if the value is 0.
+ *
+ * @param fn - The asynchronous function to be retried, which should return a truthy value upon success or undefined otherwise.
+ * @param name - The optional name of the operation, used for generating timeout error message.
+ * @param timeout - The optional maximum time, in seconds, to keep retrying before throwing a timeout error. Defaults to 0 (never timeout).
+ * @param interval - The optional interval, in seconds, between retry attempts. Defaults to 1 second.
+ * @returns A Promise that resolves with the successful (truthy) result of the provided function, or rejects if timeout is exceeded.
+ */
+export async function retryUntil<T>(fn: () => Promise<T | undefined>, name = '', timeout = 0, interval = 1) {
+  const timer = new Timer();
+  while (true) {
+    const result = await fn();
+    if (result) {
+      return result;
+    }
+
+    await sleep(interval * 1000);
+
+    if (timeout && timer.s() > timeout) {
+      throw new Error(name ? `Timeout awaiting ${name}` : 'Timeout');
+    }
+  }
+}