@metamask/network-controller
Version:
Provides an interface to the currently selected network via a MetaMask-compatible provider object
169 lines • 8.76 kB
text/typescript
import type { Json, JsonRpcParams, JsonRpcRequest, JsonRpcResponse } from "@metamask/utils";
import { IDisposable } from "cockatiel";
import { RpcService } from "./rpc-service.cjs";
import type { RpcServiceOptions } from "./rpc-service.cjs";
import type { CockatielEventToEventListenerWithData, ExcludeCockatielEventData, ExtractCockatielEventData, FetchOptions } from "./shared.cjs";
/**
* This class constructs and manages requests to a chain of RpcService objects
* which represent RPC endpoints with which to access a particular network. The
* first service in the chain is intended to be the primary way of hitting the
* network and the remaining services are used as failovers.
*/
export declare class RpcServiceChain {
#private;
/**
* Constructs a new RpcServiceChain object.
*
* @param rpcServiceConfigurations - The options for the RPC services
* that you want to construct. Each object in this array is the same as
* {@link RpcServiceOptions}.
*/
constructor(rpcServiceConfigurations: [RpcServiceOptions, ...RpcServiceOptions[]]);
/**
* Calls the provided callback when any of the RPC services is retried.
*
* This is mainly useful for tests.
*
* @param listener - The callback to be called.
* @returns An object with a `dispose` method which can be used to unregister
* the event listener.
*/
onServiceRetry(listener: CockatielEventToEventListenerWithData<RpcService['onRetry'], {
primaryEndpointUrl: string;
}>): {
dispose(): void;
};
/**
* Calls the provided callback only when the maximum number of failed
* consecutive attempts to receive a 2xx response has been reached for all
* RPC services in the chain, and all services' underlying circuits have
* broken.
*
* The callback will not be called if a service's circuit breaks but its
* failover does not. Use `onServiceBreak` if you'd like a lower level of
* granularity.
*
* @param listener - The callback to be called.
* @returns An object with a `dispose` method which can be used to unregister
* the callback.
*/
onBreak(listener: (data: ExcludeCockatielEventData<ExtractCockatielEventData<RpcService['onBreak']>, 'endpointUrl'>) => void): IDisposable;
/**
* Calls the provided callback each time when, for *any* of the RPC services
* in this chain, the maximum number of failed consecutive attempts to receive
* a 2xx response has been reached and the underlying circuit has broken. A
* more granular version of `onBreak`.
*
* @param listener - The callback to be called.
* @returns An object with a `dispose` method which can be used to unregister
* the callback.
*/
onServiceBreak(listener: CockatielEventToEventListenerWithData<RpcService['onBreak'], {
primaryEndpointUrl: string;
}>): IDisposable;
/**
* Calls the provided callback if no requests have been initiated yet or
* all requests to RPC services in this chain have responded successfully in a
* timely fashion, and then one of the two conditions apply:
*
* 1. When a retriable error is encountered making a request to an RPC
* service, and the request is retried until a set maximum is reached.
* 2. When a RPC service responds successfully, but the request takes longer
* than a set number of seconds to complete.
*
* Note that the callback will be called even if there are local connectivity
* issues which prevent requests from being initiated. This is intentional.
*
* Also note this callback will only be called if the RPC service chain as a
* whole is in a "degraded" state, and will then only be called once (e.g., it
* will not be called if a failover service falls into a degraded state, then
* the primary comes back online, but it is slow). Use `onServiceDegraded` if
* you'd like a lower level of granularity.
*
* @param listener - The callback to be called.
* @returns An object with a `dispose` method which can be used to unregister
* the callback.
*/
onDegraded(listener: (data: ExcludeCockatielEventData<ExtractCockatielEventData<RpcService['onDegraded']>, 'endpointUrl'>) => void): IDisposable;
/**
* Calls the provided callback each time one of the two conditions apply:
*
* 1. When a retriable error is encountered making a request to an RPC
* service, and the request is retried until a set maximum is reached.
* 2. When a RPC service responds successfully, but the request takes longer
* than a set number of seconds to complete.
*
* Note that the callback will be called even if there are local connectivity
* issues which prevent requests from being initiated. This is intentional.
*
* This is a more granular version of `onDegraded`. The callback will be
* called for each slow request to an RPC service. It may also be called again
* if a failover service falls into a degraded state, then the primary comes
* back online, but it is slow.
*
* @param listener - The callback to be called.
* @returns An object with a `dispose` method which can be used to unregister
* the callback.
*/
onServiceDegraded(listener: CockatielEventToEventListenerWithData<RpcService['onDegraded'], {
primaryEndpointUrl: string;
}>): IDisposable;
/**
* Calls the provided callback in one of the following two conditions:
*
* 1. The first time that a 2xx request is made to any of the RPC services in
* this chain.
* 2. When requests to any the failover RPC services in this chain were
* failing such that they were degraded or their underyling circuits broke,
* but the first request to the primary succeeds again.
*
* Note this callback will only be called if the RPC service chain as a whole
* is in an "available" state.
*
* @param listener - The callback to be called.
* @returns An object with a `dispose` method which can be used to unregister
* the callback.
*/
onAvailable(listener: (data: ExcludeCockatielEventData<ExtractCockatielEventData<RpcService['onAvailable']>, 'endpointUrl'>) => void): IDisposable;
/**
* Uses the RPC services in the chain to make a request, using each service
* after the first as a fallback to the previous one as necessary.
*
* This overload is specifically designed for `eth_getBlockByNumber`, which
* can return a `result` of `null` despite an expected `Result` being
* provided.
*
* @param jsonRpcRequest - The JSON-RPC request to send to the endpoint.
* @param fetchOptions - An options bag for {@link fetch} which further
* specifies the request.
* @returns The decoded JSON-RPC response from the endpoint.
* @throws A 401 error if the response status is 401.
* @throws A "rate limiting" error if the response HTTP status is 429.
* @throws A "resource unavailable" error if the response status is 402, 404, or any 5xx.
* @throws A generic HTTP client error (-32100) for any other 4xx status codes.
* @throws A "parse" error if the response is not valid JSON.
*/
request<Params extends JsonRpcParams, Result extends Json>(jsonRpcRequest: Readonly<JsonRpcRequest<Params>> & {
method: 'eth_getBlockByNumber';
}, fetchOptions?: FetchOptions): Promise<JsonRpcResponse<Result> | JsonRpcResponse<null>>;
/**
* Uses the RPC services in the chain to make a request, using each service
* after the first as a fallback to the previous one as necessary.
*
* This overload is designed for all RPC methods except for
* `eth_getBlockByNumber`, which are expected to return a `result` of the
* expected `Result`.
*
* @param jsonRpcRequest - The JSON-RPC request to send to the endpoint.
* @param fetchOptions - An options bag for {@link fetch} which further
* specifies the request.
* @returns The decoded JSON-RPC response from the endpoint.
* @throws A 401 error if the response status is 401.
* @throws A "rate limiting" error if the response HTTP status is 429.
* @throws A "resource unavailable" error if the response status is 402, 404, or any 5xx.
* @throws A generic HTTP client error (-32100) for any other 4xx status codes.
* @throws A "parse" error if the response is not valid JSON.
*/
request<Params extends JsonRpcParams, Result extends Json>(jsonRpcRequest: Readonly<JsonRpcRequest<Params>>, fetchOptions?: FetchOptions): Promise<JsonRpcResponse<Result>>;
}
//# sourceMappingURL=rpc-service-chain.d.cts.map