@metamask/network-controller
Version:
Provides an interface to the currently selected network via a MetaMask-compatible provider object
241 lines • 10.3 kB
text/typescript
import type { CreateServicePolicyOptions, ServicePolicy } from "@metamask/controller-utils";
import type { Json, JsonRpcParams, JsonRpcRequest, JsonRpcResponse } from "@metamask/utils";
import { CircuitState } from "cockatiel";
import type { Logger } from "loglevel";
import type { CockatielEventToEventListenerWithData, ExcludeCockatielEventData, ExtendCockatielEventData, ExtractCockatielEventData, FetchOptions } from "./shared.mjs";
/**
* Options for the RpcService constructor.
*/
export type RpcServiceOptions = {
/**
* A function that can be used to convert a binary string into a
* base64-encoded ASCII string. Used to encode authorization credentials.
*/
btoa: typeof btoa;
/**
* The URL of the RPC endpoint to hit.
*/
endpointUrl: URL | string;
/**
* A function that can be used to make an HTTP request. If your JavaScript
* environment supports `fetch` natively, you'll probably want to pass that;
* otherwise you can pass an equivalent (such as `fetch` via `node-fetch`).
*/
fetch: typeof fetch;
/**
* A common set of options that will be used to make every request. Can be
* overridden on the request level (e.g. to add headers).
*/
fetchOptions?: FetchOptions;
/**
* A `loglevel` logger.
*/
logger?: Pick<Logger, 'warn'>;
/**
* Options to pass to `createServicePolicy`. Note that `retryFilterPolicy` is
* not accepted, as it is overwritten. See {@link createServicePolicy}.
*/
policyOptions?: Omit<CreateServicePolicyOptions, 'retryFilterPolicy'>;
/**
* A function that checks if the user is currently offline. If it returns true,
* connection errors will not be retried, preventing degraded and break
* callbacks from being triggered.
*/
isOffline: () => boolean;
};
/**
* The maximum number of times that a failing service should be re-run before
* giving up.
*/
export declare const DEFAULT_MAX_RETRIES = 4;
/**
* The maximum number of times that the service is allowed to fail before
* pausing further retries. This is set to a value such that if given a
* service that continually fails, the policy needs to be executed 3 times
* before further retries are paused.
*/
export declare const DEFAULT_MAX_CONSECUTIVE_FAILURES: number;
/**
* The list of error messages that represent a failure to connect to the network.
*
* This list was derived from Sindre Sorhus's `is-network-error` package:
* <https://github.com/sindresorhus/is-network-error/blob/7bbfa8be9482ce1427a21fbff60e3ee1650dd091/index.js>
*/
export declare const CONNECTION_ERRORS: {
constructorName: string;
pattern: RegExp;
}[];
/**
* Custom JSON-RPC error codes for specific cases.
*
* These should be moved to `@metamask/rpc-errors` eventually.
*/
export declare const CUSTOM_RPC_ERRORS: {
readonly unauthorized: -32006;
readonly httpClientError: -32080;
};
/**
* Determines whether the given error represents a failure to reach the network
* after request parameters have been validated.
*
* This is somewhat difficult to verify because JavaScript engines (and in
* some cases libraries) produce slightly different error messages for this
* particular scenario, and we need to account for this.
*
* @param error - The error.
* @returns True if the error indicates that the network cannot be connected to,
* and false otherwise.
*/
export declare function isConnectionError(error: unknown): boolean;
/**
* Determine whether the given error message indicates a failure to parse JSON.
*
* This is different in tests vs. implementation code because it may manifest as
* a FetchError or a SyntaxError.
*
* @param error - The error object to test.
* @returns True if the error indicates a JSON parse error, false otherwise.
*/
export declare function isJsonParseError(error: unknown): boolean;
/**
* Determines whether the given error represents a HTTP server error
* (502, 503, or 504) that should be retried.
*
* @param error - The error object to test.
* @returns True if the error has an httpStatus of 502, 503, or 504.
*/
export declare function isHttpServerError(error: Error): boolean;
/**
* Determines whether the given error has a `code` property of `ETIMEDOUT`.
*
* @param error - The error object to test.
* @returns True if the error code is `ETIMEDOUT`.
*/
export declare function isTimeoutError(error: Error): boolean;
/**
* Determines whether the given error has a `code` property of `ECONNRESET`.
*
* @param error - The error object to test.
* @returns True if the error code is `ECONNRESET`.
*/
export declare function isConnectionResetError(error: Error): boolean;
/**
* This class is responsible for making a request to an endpoint that implements
* the JSON-RPC protocol. It is designed to gracefully handle network and server
* failures, retrying requests using exponential backoff. It also offers a hook
* which can used to respond to slow requests.
*/
export declare class RpcService {
#private;
/**
* The URL of the RPC endpoint.
*/
readonly endpointUrl: URL;
/**
* The last error that the retry policy captured (or `undefined` if the last
* execution of the service was successful).
*/
lastError: Error | undefined;
/**
* Constructs a new RpcService object.
*
* @param options - The options. See {@link RpcServiceOptions}.
*/
constructor(options: RpcServiceOptions);
/**
* Resets the underlying composite Cockatiel policy.
*
* This is useful in a collection of RpcServices where some act as failovers
* for others where you effectively want to invalidate the failovers when the
* primary recovers.
*/
resetPolicy(): void;
/**
* @returns The state of the underlying circuit.
*/
getCircuitState(): CircuitState;
/**
* Listens for when the RPC service retries the request.
*
* @param listener - The callback to be called when the retry occurs.
* @returns What {@link ServicePolicy.onRetry} returns.
* @see {@link createServicePolicy}
*/
onRetry(listener: CockatielEventToEventListenerWithData<ServicePolicy['onRetry'], {
endpointUrl: string;
}>): ReturnType<ServicePolicy['onRetry']>;
/**
* Listens for when the RPC service retries the request too many times in a
* row, causing the underlying circuit to break.
*
* @param listener - The callback to be called when the circuit is broken.
* @returns What {@link ServicePolicy.onBreak} returns.
* @see {@link createServicePolicy}
*/
onBreak(listener: (data: ExcludeCockatielEventData<ExtendCockatielEventData<ExtractCockatielEventData<ServicePolicy['onBreak']>, {
endpointUrl: string;
}>, 'isolated'>) => void): ReturnType<ServicePolicy['onBreak']>;
/**
* Listens for when the policy underlying this RPC service detects a slow
* request.
*
* @param listener - The callback to be called when the request is slow.
* @returns What {@link ServicePolicy.onDegraded} returns.
* @see {@link createServicePolicy}
*/
onDegraded(listener: CockatielEventToEventListenerWithData<ServicePolicy['onDegraded'], {
duration?: number;
endpointUrl: string;
rpcMethodName: string;
traceId?: string;
}>): ReturnType<ServicePolicy['onDegraded']>;
/**
* Listens for when the policy underlying this RPC service is available.
*
* @param listener - The callback to be called when the request is available.
* @returns What {@link ServicePolicy.onAvailable} returns.
* @see {@link createServicePolicy}
*/
onAvailable(listener: CockatielEventToEventListenerWithData<ServicePolicy['onAvailable'], {
endpointUrl: string;
}>): ReturnType<ServicePolicy['onAvailable']>;
/**
* Makes a request to the RPC endpoint.
*
* 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 An "authorized" JSON-RPC error (code -32006) if the response HTTP status is 401.
* @throws A "rate limiting" JSON-RPC error (code -32005) if the response HTTP status is 429.
* @throws A "resource unavailable" JSON-RPC error (code -32002) if the response HTTP status is 402, 404, or any 5xx.
* @throws A generic HTTP client JSON-RPC error (code -32050) for any other 4xx HTTP status codes.
* @throws A "parse" JSON-RPC error (code -32700) if the response is not valid JSON.
*/
request<Params extends JsonRpcParams, Result extends Json>(jsonRpcRequest: JsonRpcRequest<Params> & {
method: 'eth_getBlockByNumber';
}, fetchOptions?: FetchOptions): Promise<JsonRpcResponse<Result> | JsonRpcResponse<null>>;
/**
* Makes a request to the RPC endpoint.
*
* 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 An "authorized" JSON-RPC error (code -32006) if the response HTTP status is 401.
* @throws A "rate limiting" JSON-RPC error (code -32005) if the response HTTP status is 429.
* @throws A "resource unavailable" JSON-RPC error (code -32002) if the response HTTP status is 402, 404, or any 5xx.
* @throws A generic HTTP client JSON-RPC error (code -32050) for any other 4xx HTTP status codes.
* @throws A "parse" JSON-RPC error (code -32700) if the response is not valid JSON.
*/
request<Params extends JsonRpcParams, Result extends Json>(jsonRpcRequest: JsonRpcRequest<Params>, fetchOptions?: FetchOptions): Promise<JsonRpcResponse<Result>>;
}
//# sourceMappingURL=rpc-service.d.mts.map