import { abortSignalToPromise } from "../utils/abortSignal.js"; import { OwnerAggregated } from "../utils/owner/aggregated.js"; import { Owner } from "../utils/owner/owner.js"; import { jsonRpcTransportFromUri } from "./transports/factory.js"; import { JsonRpcTransportFallback } from "./transports/fallback.js"; import { JsonRpcError, JsonRpcPayload, JsonRpcResponse, JsonRpcTransport, JsonRpcTransportRequestOptions, } from "./transports/index.js"; function openTransports( urls: readonly [string, ...string[]], config?: { timeout?: number }, ): Owner { const transportOwners = Array.from(new Set(urls), (url) => jsonRpcTransportFromUri(url, config), ); return OwnerAggregated.from(transportOwners).map( (transports) => new JsonRpcTransportFallback([...transports]), ); } /** * Applies a transformation function to a value if the transformer is provided. * * @param value - The value to be transformed. * @param transformer - An optional transformation function. * @returns The transformed value if a transformer is provided, otherwise the original value. * * @example * ```typescript * const result = transform(5, (x) => x * 2); // Outputs 10 * const resultWithoutTransformer = transform(5); // Outputs 5 * ``` */ function transform(value: unknown, transformer?: (i: unknown) => unknown) { if (transformer) { return transformer(value); } return value; } /** * @deprecated Used only by the legacy positional constructor. Use the static * {@link RequestorJsonRpc.new} or {@link RequestorJsonRpc.open} methods. */ export type RequestorJsonRpcConfig = { fallbacks?: string[]; timeout?: number; maxConcurrent?: number; transport?: JsonRpcTransport; }; export class RequestorJsonRpc { public readonly maxConcurrent?: number; private concurrent = 0; private readonly pending: (() => void)[] = []; public readonly transport: JsonRpcTransport; private id = 0; /** * Creates a Requestor using legacy positional arguments. * * @param url_ - The URL of the JSON-RPC server. * @param timeout - The timeout for requests in milliseconds * @deprecated Use {@link RequestorJsonRpc.new} with a borrowed Transport or * {@link RequestorJsonRpc.open} when creating Transports. */ constructor( private readonly url_: string, config?: RequestorJsonRpcConfig, private readonly onError?: (err: unknown) => Promise | void, ) { this.maxConcurrent = config?.maxConcurrent; if (config?.transport) { this.transport = config.transport; } else { this.transport = openTransports( [url_, ...(config?.fallbacks ?? [])], config, ).value; } } /** * Creates a Requestor that borrows an existing Transport. * The caller manages the transport's lifecycle. * * Do not share a WebSocket transport across requestors: request IDs can collide, * mixing up responses or leaving requests unresolved. Reuse one requestor, or * create separate transports with {@link RequestorJsonRpc.open}. */ static new({ transport, maxConcurrent, onError, }: { transport: JsonRpcTransport; maxConcurrent?: number; onError?: (err: unknown) => Promise | void; }): RequestorJsonRpc { return new RequestorJsonRpc("", { transport, maxConcurrent }, onError); } /** Opens a Requestor with ownership of its default transports. */ static open({ urls: [url, ...fallbacks], onError, ...config }: { urls: readonly [string, ...string[]]; timeout?: number; maxConcurrent?: number; onError?: (err: unknown) => Promise | void; }): Owner { const transportOwner = openTransports([url, ...fallbacks], config); return transportOwner.map((transport) => RequestorJsonRpc.new({ transport, ...config, onError, }), ); } /** * Returns the URL of the JSON-RPC server. * * @returns The URL of the JSON-RPC server. * @deprecated URL belongs to Transport construction and is unavailable for * Requestors created with {@link RequestorJsonRpc.new}. */ get url(): string { return this.url_; } /** * request a JSON-RPC method. * * @param rpcMethod - The JSON-RPC method. * @param params - Params for the method. * @param inTransformers - An array of input transformers. * @param outTransformer - An output transformer function. * @returns Method response. */ async request( rpcMethod: string, params: unknown[], // eslint-disable-next-line @typescript-eslint/no-explicit-any inTransformers?: (((_: any) => unknown) | undefined)[], // eslint-disable-next-line @typescript-eslint/no-explicit-any outTransformer?: (_: any) => unknown, options?: JsonRpcTransportRequestOptions, ): Promise { const payload = this.buildPayload( rpcMethod, inTransformers ? await Promise.all( params .concat( Array.from( new Array(Math.max(inTransformers.length - params.length, 0)), ), ) .map((v, i) => transform(v, inTransformers[i])), ) : params, ); try { return await transform( await this.requestPayload(payload, options), outTransformer, ); } catch (err: unknown) { if (!this.onError) { throw err; } await this.onError(err); } } async requestPayload( payload: JsonRpcPayload, options?: JsonRpcTransportRequestOptions, ): Promise { if ( this.maxConcurrent !== undefined && this.concurrent >= this.maxConcurrent ) { options?.signal?.throwIfAborted(); let resolvePending: (() => void) | undefined; const pending = new Promise((resolve) => { resolvePending = resolve; this.pending.push(resolve); }); try { await (options?.signal ? Promise.race([pending, abortSignalToPromise(options.signal)]) : pending); } catch (cause) { const index = resolvePending ? this.pending.indexOf(resolvePending) : -1; if (index !== -1) { this.pending.splice(index, 1); } else { this.pending.shift()?.(); } throw cause; } } const res: JsonRpcResponse = await (async () => { this.concurrent += 1; try { return await this.transport.request(payload, options); } finally { this.concurrent -= 1; this.pending.shift()?.(); } })(); if (res.id !== payload.id) { throw new Error(`Id mismatched, got ${res.id}, expected ${payload.id}`); } if (res.error != null) { throw new JsonRpcError(res.error); } return res.result; } /** * Builds a JSON-RPC payload for the given method and parameters. * * @param method - The JSON-RPC method name. * @param req - The parameters for the JSON-RPC method. * @returns The JSON-RPC payload. */ buildPayload(method: string, req: unknown[]): JsonRpcPayload { return { id: this.id++, method, params: req, jsonrpc: "2.0", }; } }