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

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

@@ -8,9 +8,7 @@ const log = createLogger('json-rpc:json_rpc_client');
 
 export type JsonRpcFetch = (
   host: string,
-  rpcMethod: string,
   body: any,
-  useApiEndpoints: boolean,
   extraHeaders?: Record<string, string>,
   noRetry?: boolean,
 ) => Promise<{ response: any; headers: { get: (header: string) => string | null | undefined } }>;
@@ -27,45 +25,35 @@ export type JsonRpcFetch = (
  */
 export async function defaultFetch(
   host: string,
-  rpcMethod: string,
-  body: any,
-  useApiEndpoints: boolean,
+  body: unknown,
   extraHeaders: Record<string, string> = {},
   noRetry = false,
 ): Promise<{ response: any; headers: { get: (header: string) => string | null | undefined } }> {
-  log.debug(format(`JsonRpcClient.fetch`, host, rpcMethod, '->', body));
+  log.debug(format(`JsonRpcClient.fetch`, host, '->', body));
   let resp: Response;
   try {
-    if (useApiEndpoints) {
-      resp = await fetch(`${host}/${rpcMethod}`, {
-        method: 'POST',
-        body: jsonStringify(body),
-        headers: { 'content-type': 'application/json', ...extraHeaders },
-      });
-    } else {
-      resp = await fetch(host, {
-        method: 'POST',
-        body: jsonStringify({ ...body, method: rpcMethod }),
-        headers: { 'content-type': 'application/json', ...extraHeaders },
-      });
-    }
+    resp = await fetch(host, {
+      method: 'POST',
+      body: jsonStringify(body),
+      headers: { 'content-type': 'application/json', ...extraHeaders },
+    });
   } catch (err) {
-    const errorMessage = `Error fetching from host ${host} with method ${rpcMethod}: ${inspect(err)}`;
+    const errorMessage = `Error fetching from host ${host}: ${inspect(err)}`;
     throw new Error(errorMessage);
   }
 
   let responseJson;
   try {
     responseJson = await resp.json();
-  } catch (err) {
+  } catch {
     if (!resp.ok) {
       throw new Error(resp.statusText);
     }
-    throw new Error(`Failed to parse body as JSON: ${resp.text()}`);
+    throw new Error(`Failed to parse body as JSON: ${await resp.text()}`);
   }
 
   if (!resp.ok) {
-    const errorMessage = `Error ${resp.status} from server ${host} on ${rpcMethod}: ${responseJson.error.message}`;
+    const errorMessage = `Error ${resp.status} from server ${host}: ${responseJson.error.message}`;
     if (noRetry || (resp.status >= 400 && resp.status < 500)) {
       throw new NoRetryError(errorMessage);
     } else {
@@ -84,17 +72,10 @@ export async function defaultFetch(
  * @returns A fetch function.
  */
 export function makeFetch(retries: number[], defaultNoRetry: boolean, log?: Logger): typeof defaultFetch {
-  return async (
-    host: string,
-    rpcMethod: string,
-    body: any,
-    useApiEndpoints: boolean,
-    extraHeaders: Record<string, string> = {},
-    noRetry?: boolean,
-  ) => {
+  return async (host: string, body: unknown, extraHeaders: Record<string, string> = {}, noRetry?: boolean) => {
     return await retry(
-      () => defaultFetch(host, rpcMethod, body, useApiEndpoints, extraHeaders, noRetry ?? defaultNoRetry),
-      `JsonRpcClient request ${rpcMethod} to ${host}`,
+      () => defaultFetch(host, body, extraHeaders, noRetry ?? defaultNoRetry),
+      `JsonRpcClient request to ${host}`,
       makeBackoff(retries),
       log,
       false,

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

@@ -1,27 +1,67 @@
 import { format } from 'util';
 
 import { type Logger, createLogger } from '../../log/pino-logger.js';
+import { type PromiseWithResolvers, promiseWithResolvers } from '../../promise/utils.js';
 import { type ApiSchema, type ApiSchemaFor, schemaHasMethod } from '../../schemas/api.js';
+import { jsonStringify } from '../convert.js';
 import { type JsonRpcFetch, defaultFetch } from './fetch.js';
 
+// batch window of 0 would capture all requests in the current sync iteration of the event loop
+// and send them all at once in a single batch
+// minimal latency
+const DEFAULT_BATCH_WINDOW_MS = 0;
+
+// the maximum size of a batched request
+const DEFAULT_MAX_BATCH_SIZE = 100;
+
+// 10 mb
+const DEFAULT_MAX_REQUESTY_BODY_SIZE = 10 * 1024 * 1024;
+
 export type SafeJsonRpcClientOptions = {
-  useApiEndpoints?: boolean;
   namespaceMethods?: string | false;
   fetch?: JsonRpcFetch;
   log?: Logger;
+  batchWindowMS?: number;
+  maxBatchSize?: number;
+  maxRequestBodySize?: number;
   onResponse?: (res: {
     response: any;
     headers: { get: (header: string) => string | null | undefined };
   }) => Promise<void>;
 };
 
+type JsonRpcRequest = {
+  jsonrpc: '2.0';
+  id?: number;
+  method: string;
+  params?: Array<any>;
+};
+
+type JsonRpcResponse =
+  | {
+      jsonrpc: '2.0';
+      id?: number;
+      result: any;
+    }
+  | {
+      jsonrpc: '2.0';
+      id?: number;
+      error: { code: number; data?: any; message: string };
+    };
+
+// expose helpful information on the RPC clients such that we can recognize them later
+const SEND_BATCH = Symbol('JsonRpcClient.sendBatch');
+const CLIENT_ID = Symbol('JsonRpcClient.clientId');
+
+let nextClientId = 1;
+// keep a reference to clients so that we can force send a batch
+const clients = new Map<number, WeakRef<{ [SEND_BATCH]: () => Promise<void> }>>();
+
 /**
  * Creates a Proxy object that delegates over RPC and validates outputs against a given schema.
  * The server is expected to be a JsonRpcServer.
  * @param host - The host URL.
  * @param schema - The api schema to validate returned data against.
- * @param useApiEndpoints - Whether to use the API endpoints or the default RPC endpoint.
- * @param namespaceMethods - String value (or false/empty) to namespace all methods sent to the server. e.g. 'getInfo' -\> 'pxe_getInfo'
  * @param fetch - The fetch implementation to use.
  */
 export function createSafeJsonRpcClient<T extends object>(
@@ -31,25 +71,164 @@ export function createSafeJsonRpcClient<T extends object>(
 ): T {
   const fetch = config.fetch ?? defaultFetch;
   const log = config.log ?? createLogger('json-rpc:client');
-  const { useApiEndpoints = false, namespaceMethods = false } = config;
+  const {
+    namespaceMethods = false,
+    batchWindowMS = DEFAULT_BATCH_WINDOW_MS,
+    maxBatchSize = DEFAULT_MAX_BATCH_SIZE,
+    maxRequestBodySize = DEFAULT_MAX_REQUESTY_BODY_SIZE,
+  } = config;
 
   let id = 0;
+  let sendBatchTimeoutHandle: NodeJS.Timeout | undefined;
+  const queue: Array<{
+    request: JsonRpcRequest;
+    deferred: PromiseWithResolvers<JsonRpcResponse>;
+    encodedLength: number;
+  }> = [];
+
+  const sendBatch = async (): Promise<void> => {
+    if (sendBatchTimeoutHandle !== undefined) {
+      clearTimeout(sendBatchTimeoutHandle);
+      sendBatchTimeoutHandle = undefined;
+    }
+
+    const rpcCalls: typeof queue = [];
+    let bodySize = 0;
+
+    while (queue.length > 0 && rpcCalls.length < maxBatchSize && bodySize < maxRequestBodySize) {
+      const item = queue[0];
+      if (!item) {
+        break;
+      }
+
+      const tmpBodySize = bodySize + item.encodedLength;
+      if (tmpBodySize >= maxRequestBodySize) {
+        break;
+      }
+
+      bodySize = tmpBodySize;
+      queue.shift();
+      rpcCalls.push(item);
+    }
+
+    // no-op
+    if (rpcCalls.length === 0) {
+      return;
+    }
+
+    // schedule another call if there are more items to send
+    if (queue.length > 0) {
+      // eslint-disable-next-line @typescript-eslint/no-misused-promises
+      sendBatchTimeoutHandle = setTimeout(sendBatch, batchWindowMS);
+    }
+
+    log.debug(`Executing JSON-RPC batch of size: ${rpcCalls.length} body size: ${bodySize} bytes`, {
+      methods: rpcCalls.map(({ request }) => request.method),
+    });
+    try {
+      const { response, headers } = await fetch(
+        host,
+        rpcCalls.map(({ request }) => request),
+      );
+
+      if (config.onResponse) {
+        await config.onResponse({ response, headers });
+      }
+
+      if (!Array.isArray(response) || response.length !== rpcCalls.length) {
+        log.warn(
+          `Invalid response received from JSON-RPC server. Expected array of responses of length ${rpcCalls.length}`,
+          { response },
+        );
+        for (let i = 0; i < rpcCalls.length; i++) {
+          const { request, deferred } = rpcCalls[i];
+          deferred.resolve({
+            id: request.id,
+            jsonrpc: '2.0',
+            error: {
+              code: -32000,
+              data: response,
+              message: response.message ?? 'Failed request',
+            },
+          });
+        }
+      } else {
+        for (let i = 0; i < response.length; i++) {
+          const resp: JsonRpcResponse = response[i];
+          const { request, deferred } = rpcCalls[i];
+
+          if (resp.id !== request.id) {
+            log.warn(`Invalid response received at index ${i} from JSON-RPC server: id mismatch`, {
+              requestMethod: request.method,
+              requestId: request.id,
+              responseId: resp.id,
+            });
+            deferred.resolve({
+              id: request.id,
+              jsonrpc: '2.0',
+              error: {
+                code: -32001,
+                data: resp,
+                message: 'RPC id mismatch',
+              },
+            });
+          } else {
+            deferred.resolve(resp);
+          }
+        }
+      }
+    } catch (err) {
+      // Re-throw ComponentsVersionsError immediately without converting to JSON-RPC error
+      // This ensures version mismatch errors are surfaced to the user instead of being hidden
+      if (err && typeof err === 'object' && 'name' in err && err.name === 'ComponentsVersionsError') {
+        // Reject all pending requests with the version error
+        for (let i = 0; i < rpcCalls.length; i++) {
+          rpcCalls[i].deferred.reject(err);
+        }
+        return; // Return early, the promises are already rejected
+      }
+      log.warn(`Failed to fetch from the remote server`, err);
+      for (let i = 0; i < rpcCalls.length; i++) {
+        const { request, deferred } = rpcCalls[i];
+        deferred.resolve({
+          id: request.id,
+          jsonrpc: '2.0',
+          error: {
+            code: -32000,
+            data: err,
+            message: (err as any).message ?? 'Failed request',
+          },
+        });
+      }
+    }
+  };
+
   const request = async (methodName: string, params: any[]): Promise<any> => {
     if (!schemaHasMethod(schema, methodName)) {
       throw new Error(`Unspecified method ${methodName} in client schema`);
     }
     const method = namespaceMethods ? `${namespaceMethods}_${methodName}` : methodName;
-    const body = { jsonrpc: '2.0', id: id++, method, params };
+    const body: JsonRpcRequest = { jsonrpc: '2.0', id: id++, method, params };
+
+    const deferred = promiseWithResolvers<JsonRpcResponse>();
+    const encodedLength = jsonStringify(body).length;
+    if (encodedLength >= maxRequestBodySize) {
+      throw new Error(`Request body too large: ${encodedLength}`);
+    }
+
+    queue.push({ request: body, deferred, encodedLength });
+
+    if (sendBatchTimeoutHandle === undefined) {
+      // eslint-disable-next-line @typescript-eslint/no-misused-promises
+      sendBatchTimeoutHandle = setTimeout(sendBatch, batchWindowMS);
+    }
 
     log.debug(format(`request`, method, params));
-    const { response, headers } = await fetch(host, method, body, useApiEndpoints);
+    const response = await deferred.promise;
     log.debug(format(`result`, method, response));
 
-    if (config.onResponse) {
-      await config.onResponse({ response, headers });
-    }
-    if (response.error) {
-      throw response.error;
+    if ('error' in response) {
+      throw new Error(response.error.message, { cause: response.error });
     }
     // TODO(palla/schemas): Find a better way to handle null responses (JSON.stringify(null) is string "null").
     if ([null, undefined, 'null', 'undefined'].includes(response.result)) {
@@ -58,10 +237,44 @@ export function createSafeJsonRpcClient<T extends object>(
     return (schema as ApiSchema)[methodName].returnType().parseAsync(response.result);
   };
 
-  const proxy: any = {};
+  const clientId = nextClientId++;
+  const proxy: any = { [CLIENT_ID]: clientId, [SEND_BATCH]: sendBatch };
   for (const method of Object.keys(schema)) {
-    proxy[method] = (...params: any[]) => request(method, params);
+    // attach the clientId to the promise so that if we want to trigger a batch immediately, we can do that
+    proxy[method] = (...params: any[]) => Object.assign(request(method, params), { [CLIENT_ID]: clientId });
   }
 
+  clients.set(clientId, new WeakRef(proxy));
+
   return proxy as T;
 }
+
+/**
+ * Triggers a batch to be sent immediately
+ */
+export async function batch<T extends readonly unknown[]>(
+  values: T,
+): Promise<{ -readonly [P in keyof T]: Awaited<T[P]> }> {
+  const clientIdsSeen = new Set<number>();
+
+  await Promise.allSettled(
+    values.map(val => {
+      if (typeof val === 'object' && val && Object.hasOwn(val, CLIENT_ID)) {
+        const clientId = (val as { [CLIENT_ID]: any })[CLIENT_ID];
+        if (typeof clientId === 'number') {
+          if (clientIdsSeen.has(clientId)) {
+            return;
+          }
+
+          clientIdsSeen.add(clientId);
+          const client = clients.get(clientId)?.deref();
+          if (client) {
+            return client[SEND_BATCH]();
+          }
+        }
+      }
+    }),
+  );
+
+  return Promise.all(values);
+}

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

@@ -10,21 +10,14 @@ const log = createLogger('json-rpc:json_rpc_client:undici');
 export { Agent };
 
 export function makeUndiciFetch(client = new Agent()): JsonRpcFetch {
-  return async (
-    host: string,
-    rpcMethod: string,
-    body: any,
-    useApiEndpoints: boolean,
-    extraHeaders: Record<string, string> = {},
-    noRetry = false,
-  ) => {
-    log.trace(`JsonRpcClient.fetch: ${host} ${rpcMethod}`, { host, rpcMethod, body });
-    let resp: Dispatcher.ResponseData<string>;
+  return async (host: string, body: unknown, extraHeaders: Record<string, string> = {}, noRetry = false) => {
+    log.trace(`JsonRpcClient.fetch: ${host}`, { host, body });
+    let resp: Dispatcher.ResponseData;
     try {
-      resp = await client.request<string>({
+      resp = await client.request({
         method: 'POST',
         origin: new URL(host),
-        path: useApiEndpoints ? rpcMethod : '/',
+        path: '/',
         body: jsonStringify(body),
         headers: {
           ...extraHeaders,
@@ -32,7 +25,7 @@ export function makeUndiciFetch(client = new Agent()): JsonRpcFetch {
         },
       });
     } catch (err) {
-      const errorMessage = `Error fetching from host ${host} with method ${rpcMethod}: ${String(err)}`;
+      const errorMessage = `Error fetching from host ${host}: ${String(err)}`;
       throw new Error(errorMessage);
     }
 
@@ -40,7 +33,7 @@ export function makeUndiciFetch(client = new Agent()): JsonRpcFetch {
     const responseOk = resp.statusCode >= 200 && resp.statusCode <= 299;
     try {
       responseJson = await resp.body.json();
-    } catch (err) {
+    } catch {
       if (!responseOk) {
         throw new Error('HTTP ' + resp.statusCode);
       }
@@ -48,7 +41,7 @@ export function makeUndiciFetch(client = new Agent()): JsonRpcFetch {
     }
 
     if (!responseOk) {
-      const errorMessage = `Error ${resp.statusCode} response from server ${host} on ${rpcMethod}: ${responseJson.error.message}`;
+      const errorMessage = `Error ${resp.statusCode} response from server ${host}: ${responseJson}`;
       if (noRetry || (resp.statusCode >= 400 && resp.statusCode < 500)) {
         throw new NoRetryError(errorMessage);
       } else {

package/src/json-rpc/convert.ts

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

package/src/json-rpc/errors.ts

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

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

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

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

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

package/src/json-rpc/index.ts

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