@aztec/foundation 0.62.0 → 0.63.0

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

@@ -1,3 +1,6 @@
+import { z } from 'zod';
+
+import { type ApiSchemaFor, optional, schemas } from '../../schemas/index.js';
 import { sleep } from '../../sleep/index.js';
 
 /**
@@ -5,6 +8,15 @@ import { sleep } from '../../sleep/index.js';
  */
 export class TestNote {
   constructor(private data: string) {}
+
+  static get schema() {
+    return z.object({ data: z.string() }).transform(({ data }) => new TestNote(data));
+  }
+
+  toJSON() {
+    return { data: this.data };
+  }
+
   /**
    * Create a string representation of this class.
    * @returns The string representation.
@@ -22,13 +34,26 @@ export class TestNote {
   }
 }
 
+export interface TestStateApi {
+  getNote: (index: number) => Promise<TestNote | undefined>;
+  getNotes: (limit?: number) => Promise<TestNote[]>;
+  getNotes2: (limit: bigint | undefined) => Promise<TestNote[]>;
+  getNotes3: (limit?: number) => Promise<TestNote[]>;
+  clear: () => Promise<void>;
+  addNotes: (notes: TestNote[]) => Promise<TestNote[]>;
+  fail: () => Promise<void>;
+  count: () => Promise<number>;
+  getStatus: () => Promise<{ status: string; count: bigint }>;
+  getTuple(): Promise<[string, string | undefined, number]>;
+}
+
 /**
  * Represents a simple state management for TestNote instances.
  * Provides functionality to get a note by index and add notes asynchronously.
  * Primarily used for testing JSON RPC-related functionalities.
  */
-export class TestState {
-  constructor(private notes: TestNote[]) {}
+export class TestState implements TestStateApi {
+  constructor(public notes: TestNote[]) {}
   /**
    * Retrieve the TestNote instance at the specified index from the notes array.
    * This method allows getting a desired TestNote from the collection of notes
@@ -37,9 +62,40 @@ export class TestState {
    * @param index - The index of the TestNote to be retrieved from the notes array.
    * @returns The TestNote instance corresponding to the given index.
    */
-  getNote(index: number): TestNote {
+  async getNote(index: number): Promise<TestNote> {
+    await sleep(0.1);
     return this.notes[index];
   }
+
+  fail(): Promise<void> {
+    throw new Error('Test state failed');
+  }
+
+  async count(): Promise<number> {
+    await sleep(0.1);
+    return this.notes.length;
+  }
+
+  async getNotes(limit?: number): Promise<TestNote[]> {
+    await sleep(0.1);
+    return limit ? this.notes.slice(0, limit) : this.notes;
+  }
+
+  async getNotes2(limit: bigint | undefined): Promise<TestNote[]> {
+    await sleep(0.1);
+    return limit ? this.notes.slice(0, Number(limit)) : this.notes;
+  }
+
+  async getNotes3(limit = 1): Promise<TestNote[]> {
+    await sleep(0.1);
+    return limit ? this.notes.slice(0, Number(limit)) : this.notes;
+  }
+
+  async clear(): Promise<void> {
+    await sleep(0.1);
+    this.notes = [];
+  }
+
   /**
    * Add an array of TestNote instances to the current TestState's notes.
    * This function simulates asynchronous behavior by waiting for a duration
@@ -56,4 +112,32 @@ export class TestState {
     await sleep(notes.length);
     return this.notes;
   }
+
+  async forceClear() {
+    await sleep(0.1);
+    this.notes = [];
+  }
+
+  async getStatus(): Promise<{ status: string; count: bigint }> {
+    await sleep(0.1);
+    return { status: 'ok', count: BigInt(this.notes.length) };
+  }
+
+  async getTuple(): Promise<[string, string | undefined, number]> {
+    await sleep(0.1);
+    return ['a', undefined, 1];
+  }
 }
+
+export const TestStateSchema: ApiSchemaFor<TestStateApi> = {
+  getNote: z.function().args(z.number()).returns(TestNote.schema.optional()),
+  getNotes: z.function().args(optional(schemas.Integer)).returns(z.array(TestNote.schema)),
+  getNotes2: z.function().args(optional(schemas.BigInt)).returns(z.array(TestNote.schema)),
+  getNotes3: z.function().args(optional(schemas.Integer)).returns(z.array(TestNote.schema)),
+  clear: z.function().returns(z.void()),
+  addNotes: z.function().args(z.array(TestNote.schema)).returns(z.array(TestNote.schema)),
+  fail: z.function().returns(z.void()),
+  count: z.function().returns(z.number()),
+  getStatus: z.function().returns(z.object({ status: z.string(), count: schemas.BigInt })),
+  getTuple: z.function().returns(z.tuple([z.string(), optional(z.string()), z.number()])),
+};

package/src/json-rpc/index.ts

@@ -1,8 +1 @@
-export {
-  StringClassConverterInput,
-  JsonClassConverterInput as ObjClassConverterInput,
-  JsonEncodedClass,
-  ClassConverter,
-} from './class_converter.js';
-
-export { JsonStringify } from './convert.js';
+export { jsonStringify } from './convert.js';

package/src/json-rpc/js_utils.ts

@@ -1,4 +1,5 @@
 // Make sure this property was not inherited
+// TODO(palla): Delete this file
 
 /**
  * Does this own the property?

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

@@ -1,2 +1 @@
-export * from './json_rpc_server.js';
-export { JsonProxy } from './json_proxy.js';
+export * from './safe_json_rpc_server.js';

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

@@ -0,0 +1,336 @@
+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 { type AddressInfo } from 'net';
+import { format, inspect } from 'util';
+import { ZodError } from 'zod';
+
+import { type DebugLogger, createDebugLogger } 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 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,
+    /** Health check function */
+    private readonly healthCheck: StatusCheckFn = () => true,
+    /** Logger */
+    private log = createDebugLogger('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 {
+          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 } as any));
+    app.use(jsonResponse);
+    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;
+        ctx.body = { jsonrpc, id, error: { code: -32601, message: `Method not found: ${method}` } };
+      } else {
+        const result = await this.proxy.call(method, params);
+        ctx.body = { jsonrpc, id, result };
+        ctx.status = 200;
+      }
+    });
+
+    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');
+    }
+
+    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 = createDebugLogger('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 = 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?: DebugLogger): 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;
+    }
+  };
+}
+
+/**
+ * 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,
+  log = createDebugLogger('json-rpc:server'),
+): SafeJsonRpcServer {
+  const proxy = new NamespacedSafeJsonProxy(handlers);
+  const healthCheck = makeAggregateHealthcheck(handlers, log);
+  return new SafeJsonRpcServer(proxy, healthCheck, log);
+}
+
+export function createSafeJsonRpcServer<T extends object = any>(
+  handler: T,
+  schema: ApiSchemaFor<T>,
+  healthCheck?: StatusCheckFn,
+) {
+  const proxy = new SafeJsonProxy(handler, schema);
+  return new SafeJsonRpcServer(proxy, healthCheck);
+}
+
+/**
+ * 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());
+
+  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,24 @@
+import type http from 'http';
+
+import { type ApiSchemaFor } from '../../schemas/api.js';
+import { makeFetch } from '../client/fetch.js';
+import { createSafeJsonRpcClient } from '../client/safe_json_rpc_client.js';
+import { startHttpRpcServer } from '../server/safe_json_rpc_server.js';
+import { type SafeJsonRpcServer, createSafeJsonRpcServer } from '../server/safe_json_rpc_server.js';
+
+export type JsonRpcTestContext<T extends object> = {
+  server: SafeJsonRpcServer;
+  client: T;
+  httpServer: http.Server & { port: number };
+};
+
+export async function createJsonRpcTestSetup<T extends object>(
+  handler: T,
+  schema: ApiSchemaFor<T>,
+): Promise<JsonRpcTestContext<T>> {
+  const server = createSafeJsonRpcServer<T>(handler, schema);
+  const httpServer = await startHttpRpcServer(server, { host: '127.0.0.1' });
+  const noRetryFetch = makeFetch([], true);
+  const client = createSafeJsonRpcClient<T>(`http://127.0.0.1:${httpServer.port}`, schema, false, false, noRetryFetch);
+  return { server, client, httpServer };
+}

package/src/log/logger.ts

@@ -12,7 +12,8 @@ export type LogLevel = (typeof LogLevels)[number];
 
 function getLogLevel() {
   const envLogLevel = process.env.LOG_LEVEL?.toLowerCase() as LogLevel;
-  const defaultNonTestLogLevel = process.env.DEBUG === undefined ? ('info' as const) : ('debug' as const);
+  const defaultNonTestLogLevel =
+    process.env.DEBUG === undefined || process.env.DEBUG === '' ? ('info' as const) : ('debug' as const);
   const defaultLogLevel = process.env.NODE_ENV === 'test' ? ('silent' as const) : defaultNonTestLogLevel;
   return LogLevels.includes(envLogLevel) ? envLogLevel : defaultLogLevel;
 }

package/src/schemas/api.ts

@@ -0,0 +1,47 @@
+import { type z } from 'zod';
+
+import { type ZodNullableOptional } from './utils.js';
+
+// Forces usage of ZodNullableOptional in parameters schemas so we properly accept nulls for optional parameters.
+type ZodParameterTypeFor<T> = undefined extends T
+  ? ZodNullableOptional<z.ZodType<T, z.ZodTypeDef, any>>
+  : z.ZodType<T, z.ZodTypeDef, any>;
+
+type ZodReturnTypeFor<T> = z.ZodType<T, z.ZodTypeDef, any>;
+
+// This monstruosity is used for mapping function arguments to their schema representation.
+// The complexity is required to satisfy ZodTuple which requires a fixed length tuple and
+// has a very annoying type of [] | [ZodTypeAny, ...ZodTypeAny], and most types fail to match
+// the second option. While a purely recursive approach works, it fails when trying to deal
+// with optional arguments (ie optional items in the tuple), and ts does not really like them
+// during a recursion and fails with infinite stack depth.
+// This type appears to satisfy everyone. Everyone but me.
+type ZodMapParameterTypes<T> = T extends []
+  ? []
+  : T extends [item: infer Head, ...infer Rest]
+  ? [ZodParameterTypeFor<Head>, ...{ [K in keyof Rest]: ZodParameterTypeFor<Rest[K]> }]
+  : T extends [item?: infer Head, ...infer Rest]
+  ? [ZodNullableOptional<ZodParameterTypeFor<Head>>, ...{ [K in keyof Rest]: ZodParameterTypeFor<Rest[K]> }]
+  : never;
+
+/** Maps all functions in an interface to their schema representation. */
+export type ApiSchemaFor<T> = {
+  [K in keyof T]: T[K] extends (...args: infer Args) => Promise<infer Ret>
+    ? z.ZodFunction<z.ZodTuple<ZodMapParameterTypes<Args>, z.ZodUnknown>, ZodReturnTypeFor<Ret>>
+    : never;
+};
+
+/** Generic Api schema not bounded to a specific implementation. */
+export type ApiSchema = {
+  [key: string]: z.ZodFunction<z.ZodTuple<any, any>, z.ZodTypeAny>;
+};
+
+/** Return whether an API schema defines a valid function schema for a given method name. */
+export function schemaHasMethod(schema: ApiSchema, methodName: string) {
+  return (
+    typeof methodName === 'string' &&
+    Object.hasOwn(schema, methodName) &&
+    typeof schema[methodName].parameters === 'function' &&
+    typeof schema[methodName].returnType === 'function'
+  );
+}

package/src/schemas/index.ts

@@ -0,0 +1,5 @@
+export * from './api.js';
+export * from './parse.js';
+export * from './schemas.js';
+export * from './utils.js';
+export * from './types.js';

package/src/schemas/parse.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+
+import { times } from '../collection/array.js';
+
+/** Parses the given arguments using a tuple from the provided schemas. */
+export function parse<T extends [] | [z.ZodTypeAny, ...z.ZodTypeAny[]]>(args: IArguments, ...schemas: T) {
+  return z.tuple(schemas).parse(args);
+}
+
+/**
+ * Parses the given arguments against a tuple, allowing empty for optional items.
+ * @dev Zod doesn't like tuplues with optional items. See https://github.com/colinhacks/zod/discussions/949.
+ */
+export function parseWithOptionals<T extends z.AnyZodTuple>(args: any[], schema: T): T['_output'] {
+  const missingCount = schema.items.length - args.length;
+  const optionalCount = schema.items.filter(isOptional).length;
+  const toParse =
+    missingCount > 0 && missingCount <= optionalCount ? args.concat(times(missingCount, () => undefined)) : args;
+  return schema.parse(toParse);
+}
+
+function isOptional(schema: z.ZodTypeAny) {
+  try {
+    return schema.isOptional();
+  } catch (err) {
+    // See https://github.com/colinhacks/zod/issues/1911
+    return schema._def.typeName === 'ZodOptional';
+  }
+}