feat: schemas for revolver transports

Author: doomsower

src/dev/RevolverTransport.test.ts

@@ -54,8 +54,10 @@ function createClient(
           url: s3.url,
         },
       ],
-      cooldown: 100,
-      retryCount: 2,
+      defaultCooldown: 100,
+      defaultHTTPOptions: {
+        retryCount: 2,
+      },
       ...opts,
     }),
   });
@@ -208,7 +210,7 @@ it("should not overrotate when hadling parallel requests", async () => {
         url: s2.url,
       },
     ],
-    cooldown: 60_000,
+    defaultCooldown: 60_000,
   });
   const resp = await Promise.all([
     client.request({ method: "eth_blockNumber" }),
@@ -227,7 +229,7 @@ it("request should fail when all transports are broken", async () => {
   s1.stop();
   s2.stop();
   s3.stop();
-  const client = createClient({ cooldown: 60_000 });
+  const client = createClient({ defaultCooldown: 60_000 });
   await expect(client.getBlockNumber()).rejects.toThrow(
     NoAvailableTransportsError,
   );
@@ -239,7 +241,7 @@ it("subscription should fail when all transports are broken", async () => {
   s3.stop();
   const onError = vi.fn();
   const onBlockNumber = vi.fn();
-  const client = createClient({ cooldown: 60_000 });
+  const client = createClient({ defaultCooldown: 60_000 });
   unwatch = client.watchBlockNumber({
     onBlockNumber,
     onError,

src/dev/RevolverTransport.ts

@@ -1,6 +1,5 @@
 import {
   BaseError,
-  type ClientConfig,
   type EIP1193RequestFn,
   HttpRequestError,
   type HttpTransport,
@@ -16,14 +15,30 @@ import {
   withRetry,
 } from "viem";
 import type { HttpRpcClientOptions } from "viem/utils";
-import type { ILogger, NetworkType } from "../sdk/index.js";
+import { z } from "zod/v4";
+import { type ILogger, NetworkType } from "../sdk/index.js";
+import { httpTransportConfigSchema } from "./transports.js";
 
-export interface ProviderConfig {
-  name: string;
-  url: string;
-  cooldown?: number;
-  httpClientOptions?: HttpRpcClientOptions | undefined;
-}
+export const providerConfigSchema = z.object({
+  /**
+   * Provider name for display purposes
+   */
+  name: z.string(),
+  /**
+   * Provider URL
+   */
+  url: z.url(),
+  /**
+   * How long, in milliseconds, to wait before try this provider again
+   */
+  cooldown: z.number().optional(),
+  /**
+   * HTTP transport options to use for this provider
+   */
+  httpClientOptions: httpTransportConfigSchema.optional(),
+});
+
+export type ProviderConfig = z.infer<typeof providerConfigSchema>;
 
 interface TransportEntry {
   name: string;
@@ -49,23 +64,42 @@ type OnResponseFn = (
   ...args: Parameters<Required<HttpRpcClientOptions>["onResponse"]>
 ) => ReturnType<Required<HttpRpcClientOptions>["onResponse"]>;
 
+export const SelectionStrategy = z.enum(["simple", "ordered"]);
+
 /**
  * How to select the next transport
  * - simple: selects next transport after current that is not in cooldown by checking all transports in cyclic order
  * - ordered: will select first available transport that is not in cooldown
  */
-export type SelectionStrategy = "simple" | "ordered";
+export type SelectionStrategy = z.infer<typeof SelectionStrategy>;
+
+export const revolverTransportConfigSchema = z.object({
+  network: NetworkType,
+  /**
+   * Providers to use
+   */
+  providers: z.array(providerConfigSchema),
+  /**
+   * How to select the next transport
+   * Defaults to "simple"
+   */
+  selectionStrategy: SelectionStrategy.optional(),
+  /** The key of the transport. */
+  key: z.string().optional(),
+  /** The name of the transport. */
+  name: z.string().optional(),
+  /**
+   * Default HTTP options to use for all providers, can be overridden by provider config
+   */
+  defaultHTTPOptions: httpTransportConfigSchema.optional(),
+  /**
+   * Default cooldown, in milliseconds, to wait before try this transport again
+   */
+  defaultCooldown: z.number().optional(),
+});
 
-export interface RevolverTransportConfig {
-  network: NetworkType;
-  providers: ProviderConfig[];
+export type RevolverTransportConfig = {
   logger?: ILogger;
-  key?: TransportConfig["key"] | undefined;
-  name?: TransportConfig["name"] | undefined;
-  pollingInterval?: ClientConfig["pollingInterval"] | undefined;
-  retryCount?: TransportConfig["retryCount"] | undefined;
-  retryDelay?: TransportConfig["retryDelay"] | undefined;
-  timeout?: TransportConfig["timeout"] | undefined;
   /**
    * When single http transport should retry?
    * Defaults to some less strict criteria, so it'll retry "blockNumber from the future" errors
@@ -78,10 +112,6 @@ export interface RevolverTransportConfig {
   shouldRetry?:
     | ((iter: { count: number; error: Error }) => Promise<boolean> | boolean)
     | undefined;
-  /**
-   * Allow batching of json-rpc requests
-   */
-  batch?: boolean | undefined;
   /**
    * Spying function that also returns provider name in additional to the request
    */
@@ -105,16 +135,7 @@ export interface RevolverTransportConfig {
     oldTransportName: string,
     reason?: BaseError,
   ) => void | Promise<void>;
-  /**
-   * How long, in milliseconds, to wait before try this transport again
-   */
-  cooldown?: number | undefined;
-  /**
-   * How to select the next transport
-   * Defaults to "simple"
-   */
-  selectionStrategy?: SelectionStrategy;
-}
+} & z.infer<typeof revolverTransportConfigSchema>;
 
 export class NoAvailableTransportsError extends BaseError {
   constructor(cause?: Error) {
@@ -184,11 +205,8 @@ export class RevolverTransport
       ({ url, name, cooldown, httpClientOptions }): TransportEntry => ({
         name,
         transport: http(url, {
+          ...config.defaultHTTPOptions,
           ...httpClientOptions,
-          retryCount: config.retryCount,
-          retryDelay: config.retryDelay,
-          timeout: config.timeout,
-          batch: !!config.batch,
           key: name,
           name: name,
           onFetchRequest: this.#config.onRequest
@@ -209,8 +227,8 @@ export class RevolverTransport
     const selectionStrategy = config.selectionStrategy ?? "simple";
     this.#selector =
       selectionStrategy === "simple"
-        ? new SimpleTransportSelector(transports, config.cooldown)
-        : new OrderedTransportSelector(transports, config.cooldown);
+        ? new SimpleTransportSelector(transports, config.defaultCooldown)
+        : new OrderedTransportSelector(transports, config.defaultCooldown);
   }
 
   public get value(): RevolverTransportValue {
@@ -241,8 +259,8 @@ export class RevolverTransport
 
         // for explanation, see shouldRetry comment
         const resp = await withRetry(() => transport.request(r), {
-          delay: this.#config.retryDelay,
-          retryCount: this.#config.retryCount,
+          delay: this.#config.defaultHTTPOptions?.retryDelay,
+          retryCount: this.#config.defaultHTTPOptions?.retryCount,
           shouldRetry: this.#config.shouldRetry,
         });
         this.#requests.delete(r);
@@ -275,10 +293,10 @@ export class RevolverTransport
       name: "revolver",
       type: "revolver",
       request: this.request,
-      retryCount: this.#config.retryCount,
-      methods: undefined,
-      retryDelay: this.#config.retryDelay,
-      timeout: this.#config.timeout,
+      retryCount: this.#config.defaultHTTPOptions?.retryCount,
+      methods: this.#config.defaultHTTPOptions?.methods,
+      retryDelay: this.#config.defaultHTTPOptions?.retryDelay,
+      timeout: this.#config.defaultHTTPOptions?.timeout,
     };
   }
 

src/dev/index.ts

@@ -12,4 +12,5 @@ export * from "./mint/index.js";
 export * from "./providers.js";
 export * from "./RevolverTransport.js";
 export * from "./replaceStorage.js";
+export * from "./transports.js";
 export * from "./types.js";

src/dev/transports.ts

@@ -0,0 +1,49 @@
+import { z } from "zod/v4";
+
+export const httpTransportConfigSchema = z.object({
+  /**
+   * Whether to enable Batch JSON-RPC.
+   * @link https://www.jsonrpc.org/specification#batch
+   */
+  batch: z
+    .union([
+      z.boolean(),
+      z.object({
+        /** The maximum number of JSON-RPC requests to send in a batch. @default 1_000 */
+        batchSize: z.number().optional(),
+        /** The maximum number of milliseconds to wait before sending a batch. @default 0 */
+        wait: z.number().optional(),
+      }),
+    ])
+    .optional(),
+  /**
+   * Request configuration to pass to `fetch`.
+   * @link https://developer.mozilla.org/en-US/docs/Web/API/fetch
+   */
+  fetchOptions: z.record(z.string(), z.any()).optional(),
+  /**
+   * Methods to include or exclude from executing RPC requests.
+   **/
+  methods: z
+    .union([
+      z.object({
+        include: z.array(z.string()).optional(),
+      }),
+      z.object({
+        exclude: z.array(z.string()).optional(),
+      }),
+    ])
+    .optional(),
+  /**
+   * The max number of times to retry.
+   **/
+  retryCount: z.number().optional(),
+  /**
+   * The base delay (in ms) between retries.
+   **/
+  retryDelay: z.number().optional(),
+  /**
+   * The timeout (in ms) for the HTTP request. Default: 10_000
+   **/
+  timeout: z.number().optional(),
+});