@metamask-previews/network-controller 26.0.0-preview-81c9cf83 → 26.0.0-preview-d6fe4594

package/dist/rpc-service/rpc-service-chain.cjs

@@ -1,24 +1,36 @@
 "use strict";
-var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
 var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
     if (kind === "m") throw new TypeError("Private method is not writable");
     if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
     return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
 };
-var _RpcServiceChain_instances, _RpcServiceChain_services, _RpcServiceChain_buildRpcServiceChain;
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _RpcServiceChain_onAvailableEventEmitter, _RpcServiceChain_onBreakEventEmitter, _RpcServiceChain_onDegradedEventEmitter, _RpcServiceChain_primaryService, _RpcServiceChain_services, _RpcServiceChain_status;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RpcServiceChain = void 0;
+const controller_utils_1 = require("@metamask/controller-utils");
 const rpc_service_1 = require("./rpc-service.cjs");
+const logger_1 = require("../logger.cjs");
+const log = (0, logger_1.createModuleLogger)(logger_1.projectLogger, 'RpcServiceChain');
 /**
- * This class constructs a chain of RpcService objects which represent a
- * particular network. The first object in the chain is intended to be the
- * primary way of reaching the network and the remaining objects are used as
- * failovers.
+ * Statuses that the RPC service chain can be in.
+ */
+const STATUSES = {
+    Available: 'available',
+    Degraded: 'degraded',
+    Unknown: 'unknown',
+    Unavailable: 'unavailable',
+};
+/**
+ * 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.
  */
 class RpcServiceChain {
     /**
@@ -29,18 +41,73 @@ class RpcServiceChain {
      * {@link RpcServiceOptions}.
      */
     constructor(rpcServiceConfigurations) {
-        _RpcServiceChain_instances.add(this);
+        /**
+         * The event emitter for the `onAvailable` event.
+         */
+        _RpcServiceChain_onAvailableEventEmitter.set(this, void 0);
+        /**
+         * The event emitter for the `onBreak` event.
+         */
+        _RpcServiceChain_onBreakEventEmitter.set(this, void 0);
+        /**
+         * The event emitter for the `onDegraded` event.
+         */
+        _RpcServiceChain_onDegradedEventEmitter.set(this, void 0);
+        /**
+         * The first RPC service that requests will be sent to.
+         */
+        _RpcServiceChain_primaryService.set(this, void 0);
+        /**
+         * The RPC services in the chain.
+         */
         _RpcServiceChain_services.set(this, void 0);
-        __classPrivateFieldSet(this, _RpcServiceChain_services, __classPrivateFieldGet(this, _RpcServiceChain_instances, "m", _RpcServiceChain_buildRpcServiceChain).call(this, rpcServiceConfigurations), "f");
+        /**
+         * The status of the RPC service chain.
+         */
+        _RpcServiceChain_status.set(this, void 0);
+        __classPrivateFieldSet(this, _RpcServiceChain_services, rpcServiceConfigurations.map((rpcServiceConfiguration) => new rpc_service_1.RpcService(rpcServiceConfiguration)), "f");
+        __classPrivateFieldSet(this, _RpcServiceChain_primaryService, __classPrivateFieldGet(this, _RpcServiceChain_services, "f")[0], "f");
+        __classPrivateFieldSet(this, _RpcServiceChain_status, STATUSES.Unknown, "f");
+        __classPrivateFieldSet(this, _RpcServiceChain_onBreakEventEmitter, new controller_utils_1.CockatielEventEmitter(), "f");
+        __classPrivateFieldSet(this, _RpcServiceChain_onDegradedEventEmitter, new controller_utils_1.CockatielEventEmitter(), "f");
+        for (const service of __classPrivateFieldGet(this, _RpcServiceChain_services, "f")) {
+            service.onDegraded((data) => {
+                if (__classPrivateFieldGet(this, _RpcServiceChain_status, "f") !== STATUSES.Degraded) {
+                    log('Updating status to "degraded"', data);
+                    __classPrivateFieldSet(this, _RpcServiceChain_status, STATUSES.Degraded, "f");
+                    const { endpointUrl, ...rest } = data;
+                    __classPrivateFieldGet(this, _RpcServiceChain_onDegradedEventEmitter, "f").emit(rest);
+                }
+            });
+        }
+        __classPrivateFieldSet(this, _RpcServiceChain_onAvailableEventEmitter, new controller_utils_1.CockatielEventEmitter(), "f");
+        for (const service of __classPrivateFieldGet(this, _RpcServiceChain_services, "f")) {
+            service.onAvailable((data) => {
+                if (__classPrivateFieldGet(this, _RpcServiceChain_status, "f") !== STATUSES.Available) {
+                    log('Updating status to "available"', data);
+                    __classPrivateFieldSet(this, _RpcServiceChain_status, STATUSES.Available, "f");
+                    const { endpointUrl, ...rest } = data;
+                    __classPrivateFieldGet(this, _RpcServiceChain_onAvailableEventEmitter, "f").emit(rest);
+                }
+            });
+        }
     }
     /**
-     * Listens for when any of the RPC services retry a request.
+     * 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 when the retry occurs.
-     * @returns What {@link RpcService.onRetry} returns.
+     * @param listener - The callback to be called.
+     * @returns An object with a `dispose` method which can be used to unregister
+     * the event listener.
      */
-    onRetry(listener) {
-        const disposables = __classPrivateFieldGet(this, _RpcServiceChain_services, "f").map((service) => service.onRetry(listener));
+    onServiceRetry(listener) {
+        const disposables = __classPrivateFieldGet(this, _RpcServiceChain_services, "f").map((service) => service.onRetry((data) => {
+            listener({
+                ...data,
+                primaryEndpointUrl: __classPrivateFieldGet(this, _RpcServiceChain_primaryService, "f").endpointUrl.toString(),
+            });
+        }));
         return {
             dispose() {
                 disposables.forEach((disposable) => disposable.dispose());
@@ -48,14 +115,39 @@ class RpcServiceChain {
         };
     }
     /**
-     * Listens for when any of the RPC services retry the request too many times
-     * in a row.
+     * 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.
      *
-     * @param listener - The callback to be called when the retry occurs.
-     * @returns What {@link RpcService.onBreak} returns.
+     * 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) {
-        const disposables = __classPrivateFieldGet(this, _RpcServiceChain_services, "f").map((service) => service.onBreak(listener));
+        return __classPrivateFieldGet(this, _RpcServiceChain_onBreakEventEmitter, "f").addListener(listener);
+    }
+    /**
+     * 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) {
+        const disposables = __classPrivateFieldGet(this, _RpcServiceChain_services, "f").map((service) => service.onBreak((data) => {
+            listener({
+                ...data,
+                primaryEndpointUrl: __classPrivateFieldGet(this, _RpcServiceChain_primaryService, "f").endpointUrl.toString(),
+            });
+        }));
         return {
             dispose() {
                 disposables.forEach((disposable) => disposable.dispose());
@@ -63,34 +155,150 @@ class RpcServiceChain {
         };
     }
     /**
-     * Listens for when any of the RPC services send a slow request.
+     * 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.
      *
-     * @param listener - The callback to be called when the retry occurs.
-     * @returns What {@link RpcService.onRetry} returns.
+     * 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) {
-        const disposables = __classPrivateFieldGet(this, _RpcServiceChain_services, "f").map((service) => service.onDegraded(listener));
+        return __classPrivateFieldGet(this, _RpcServiceChain_onDegradedEventEmitter, "f").addListener(listener);
+    }
+    /**
+     * 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) {
+        const disposables = __classPrivateFieldGet(this, _RpcServiceChain_services, "f").map((service) => service.onDegraded((data) => {
+            listener({
+                ...data,
+                primaryEndpointUrl: __classPrivateFieldGet(this, _RpcServiceChain_primaryService, "f").endpointUrl.toString(),
+            });
+        }));
         return {
             dispose() {
                 disposables.forEach((disposable) => disposable.dispose());
             },
         };
     }
+    /**
+     * 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) {
+        return __classPrivateFieldGet(this, _RpcServiceChain_onAvailableEventEmitter, "f").addListener(listener);
+    }
     async request(jsonRpcRequest, fetchOptions = {}) {
-        return __classPrivateFieldGet(this, _RpcServiceChain_services, "f")[0].request(jsonRpcRequest, fetchOptions);
+        // Start with the primary (first) service and switch to failovers as the
+        // need arises. This is a bit confusing, so keep reading for more on how
+        // this works.
+        let availableServiceIndex;
+        let response;
+        for (const [i, service] of __classPrivateFieldGet(this, _RpcServiceChain_services, "f").entries()) {
+            log(`Trying service #${i + 1}...`);
+            const previousCircuitState = service.getCircuitState();
+            try {
+                // Try making the request through the service.
+                response = await service.request(jsonRpcRequest, fetchOptions);
+                log('Service successfully received request.');
+                availableServiceIndex = i;
+                break;
+            }
+            catch (error) {
+                // Oops, that didn't work.
+                // Capture this error so that we can handle it later.
+                const { lastError } = service;
+                const isCircuitOpen = service.getCircuitState() === controller_utils_1.CircuitState.Open;
+                log('Service failed! error =', error, 'lastError = ', lastError);
+                if (isCircuitOpen) {
+                    if (i < __classPrivateFieldGet(this, _RpcServiceChain_services, "f").length - 1) {
+                        log("This service's circuit is open. Proceeding to next service...");
+                        continue;
+                    }
+                    if (previousCircuitState !== controller_utils_1.CircuitState.Open &&
+                        __classPrivateFieldGet(this, _RpcServiceChain_status, "f") !== STATUSES.Unavailable &&
+                        lastError !== undefined) {
+                        // If the service's circuit just broke and it's the last one in the
+                        // chain, then trigger the onBreak event. (But if for some reason we
+                        // have already done this, then don't do it.)
+                        log('This service\'s circuit just opened and it is the last service. Updating status to "unavailable" and triggering onBreak.');
+                        __classPrivateFieldSet(this, _RpcServiceChain_status, STATUSES.Unavailable, "f");
+                        __classPrivateFieldGet(this, _RpcServiceChain_onBreakEventEmitter, "f").emit({
+                            error: lastError,
+                        });
+                    }
+                }
+                // The service failed, and we throw whatever the error is. The calling
+                // code can try again if it so desires.
+                log(`${isCircuitOpen ? '' : "This service's circuit is closed. "}Re-throwing error.`);
+                throw error;
+            }
+        }
+        if (response) {
+            // If one of the services is available, reset all of the circuits of the
+            // following services. If we didn't do this and the service became
+            // unavailable in the future, and any of the failovers' circuits were
+            // open (due to previous failures), we would receive a "circuit broken"
+            // error when we attempted to divert traffic to the failovers again.
+            //
+            if (availableServiceIndex !== undefined) {
+                for (const [i, service] of [...__classPrivateFieldGet(this, _RpcServiceChain_services, "f").entries()].slice(availableServiceIndex + 1)) {
+                    log(`Resetting policy for service #${i + 1}.`);
+                    service.resetPolicy();
+                }
+            }
+            return response;
+        }
+        // The only way we can end up here is if there are no services to loop over.
+        // That is not possible due to the types on the constructor, but TypeScript
+        // doesn't know this, so we have to appease it.
+        throw new Error('Nothing to return');
     }
 }
 exports.RpcServiceChain = RpcServiceChain;
-_RpcServiceChain_services = new WeakMap(), _RpcServiceChain_instances = new WeakSet(), _RpcServiceChain_buildRpcServiceChain = function _RpcServiceChain_buildRpcServiceChain(rpcServiceConfigurations) {
-    return [...rpcServiceConfigurations]
-        .reverse()
-        .reduce((workingServices, serviceConfiguration, index) => {
-        const failoverService = index > 0 ? workingServices[0] : undefined;
-        const service = new rpc_service_1.RpcService({
-            ...serviceConfiguration,
-            failoverService,
-        });
-        return [service, ...workingServices];
-    }, []);
-};
+_RpcServiceChain_onAvailableEventEmitter = new WeakMap(), _RpcServiceChain_onBreakEventEmitter = new WeakMap(), _RpcServiceChain_onDegradedEventEmitter = new WeakMap(), _RpcServiceChain_primaryService = new WeakMap(), _RpcServiceChain_services = new WeakMap(), _RpcServiceChain_status = new WeakMap();
 //# sourceMappingURL=rpc-service-chain.cjs.map

package/dist/rpc-service/rpc-service-chain.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"rpc-service-chain.cjs","sourceRoot":"","sources":["../../src/rpc-service/rpc-service-chain.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAOA,mDAA2C;AAK3C;;;;;GAKG;AACH,MAAa,eAAe;IAG1B;;;;;;OAMG;IACH,YACE,wBAAsE;;QAV/D,4CAAwB;QAY/B,uBAAA,IAAI,6BAAa,uBAAA,IAAI,yEAAsB,MAA1B,IAAI,EAAuB,wBAAwB,CAAC,MAAA,CAAC;IACxE,CAAC;IAED;;;;;OAKG;IACH,OAAO,CAAC,QAA8C;QACpD,MAAM,WAAW,GAAG,uBAAA,IAAI,iCAAU,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CACjD,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAC1B,CAAC;QAEF,OAAO;YACL,OAAO;gBACL,WAAW,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC;YAC5D,CAAC;SACF,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,QAA8C;QACpD,MAAM,WAAW,GAAG,uBAAA,IAAI,iCAAU,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CACjD,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAC1B,CAAC;QAEF,OAAO;YACL,OAAO;gBACL,WAAW,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC;YAC5D,CAAC;SACF,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,UAAU,CAAC,QAAiD;QAC1D,MAAM,WAAW,GAAG,uBAAA,IAAI,iCAAU,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CACjD,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAC7B,CAAC;QAEF,OAAO;YACL,OAAO;gBACL,WAAW,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC;YAC5D,CAAC;SACF,CAAC;IACJ,CAAC;IAkDD,KAAK,CAAC,OAAO,CACX,cAAgD,EAChD,eAA6B,EAAE;QAE/B,OAAO,uBAAA,IAAI,iCAAU,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,cAAc,EAAE,YAAY,CAAC,CAAC;IACjE,CAAC;CA0BF;AAtJD,0CAsJC;8KAbG,wBAAsE;IAEtE,OAAO,CAAC,GAAG,wBAAwB,CAAC;SACjC,OAAO,EAAE;SACT,MAAM,CAAC,CAAC,eAA6B,EAAE,oBAAoB,EAAE,KAAK,EAAE,EAAE;QACrE,MAAM,eAAe,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACnE,MAAM,OAAO,GAAG,IAAI,wBAAU,CAAC;YAC7B,GAAG,oBAAoB;YACvB,eAAe;SAChB,CAAC,CAAC;QACH,OAAO,CAAC,OAAO,EAAE,GAAG,eAAe,CAAC,CAAC;IACvC,CAAC,EAAE,EAAE,CAAC,CAAC;AACX,CAAC","sourcesContent":["import type {\n  Json,\n  JsonRpcParams,\n  JsonRpcRequest,\n  JsonRpcResponse,\n} from '@metamask/utils';\n\nimport { RpcService } from './rpc-service';\nimport type { RpcServiceOptions } from './rpc-service';\nimport type { RpcServiceRequestable } from './rpc-service-requestable';\nimport type { FetchOptions } from './shared';\n\n/**\n * This class constructs a chain of RpcService objects which represent a\n * particular network. The first object in the chain is intended to be the\n * primary way of reaching the network and the remaining objects are used as\n * failovers.\n */\nexport class RpcServiceChain implements RpcServiceRequestable {\n  readonly #services: RpcService[];\n\n  /**\n   * Constructs a new RpcServiceChain object.\n   *\n   * @param rpcServiceConfigurations - The options for the RPC services\n   * that you want to construct. Each object in this array is the same as\n   * {@link RpcServiceOptions}.\n   */\n  constructor(\n    rpcServiceConfigurations: Omit<RpcServiceOptions, 'failoverService'>[],\n  ) {\n    this.#services = this.#buildRpcServiceChain(rpcServiceConfigurations);\n  }\n\n  /**\n   * Listens for when any of the RPC services retry a request.\n   *\n   * @param listener - The callback to be called when the retry occurs.\n   * @returns What {@link RpcService.onRetry} returns.\n   */\n  onRetry(listener: Parameters<RpcService['onRetry']>[0]) {\n    const disposables = this.#services.map((service) =>\n      service.onRetry(listener),\n    );\n\n    return {\n      dispose() {\n        disposables.forEach((disposable) => disposable.dispose());\n      },\n    };\n  }\n\n  /**\n   * Listens for when any of the RPC services retry the request too many times\n   * in a row.\n   *\n   * @param listener - The callback to be called when the retry occurs.\n   * @returns What {@link RpcService.onBreak} returns.\n   */\n  onBreak(listener: Parameters<RpcService['onBreak']>[0]) {\n    const disposables = this.#services.map((service) =>\n      service.onBreak(listener),\n    );\n\n    return {\n      dispose() {\n        disposables.forEach((disposable) => disposable.dispose());\n      },\n    };\n  }\n\n  /**\n   * Listens for when any of the RPC services send a slow request.\n   *\n   * @param listener - The callback to be called when the retry occurs.\n   * @returns What {@link RpcService.onRetry} returns.\n   */\n  onDegraded(listener: Parameters<RpcService['onDegraded']>[0]) {\n    const disposables = this.#services.map((service) =>\n      service.onDegraded(listener),\n    );\n\n    return {\n      dispose() {\n        disposables.forEach((disposable) => disposable.dispose());\n      },\n    };\n  }\n\n  /**\n   * Makes a request to the first RPC service in the chain. If this service is\n   * down, then the request is forwarded to the next service in the chain, etc.\n   *\n   * This overload is specifically designed for `eth_getBlockByNumber`, which\n   * can return a `result` of `null` despite an expected `Result` being\n   * provided.\n   *\n   * @param jsonRpcRequest - The JSON-RPC request to send to the endpoint.\n   * @param fetchOptions - An options bag for {@link fetch} which further\n   * specifies the request.\n   * @returns The decoded JSON-RPC response from the endpoint.\n   * @throws A 401 error if the response status is 401.\n   * @throws A \"rate limiting\" error if the response HTTP status is 429.\n   * @throws A \"resource unavailable\" error if the response status is 402, 404, or any 5xx.\n   * @throws A generic HTTP client error (-32100) for any other 4xx status codes.\n   * @throws A \"parse\" error if the response is not valid JSON.\n   */\n  async request<Params extends JsonRpcParams, Result extends Json>(\n    jsonRpcRequest: Readonly<JsonRpcRequest<Params>> & {\n      method: 'eth_getBlockByNumber';\n    },\n    fetchOptions?: FetchOptions,\n  ): Promise<JsonRpcResponse<Result> | JsonRpcResponse<null>>;\n\n  /**\n   * Makes a request to the first RPC service in the chain. If this service is\n   * down, then the request is forwarded to the next service in the chain, etc.\n   *\n   * This overload is designed for all RPC methods except for\n   * `eth_getBlockByNumber`, which are expected to return a `result` of the\n   * expected `Result`.\n   *\n   * @param jsonRpcRequest - The JSON-RPC request to send to the endpoint.\n   * @param fetchOptions - An options bag for {@link fetch} which further\n   * specifies the request.\n   * @returns The decoded JSON-RPC response from the endpoint.\n   * @throws A 401 error if the response status is 401.\n   * @throws A \"rate limiting\" error if the response HTTP status is 429.\n   * @throws A \"resource unavailable\" error if the response status is 402, 404, or any 5xx.\n   * @throws A generic HTTP client error (-32100) for any other 4xx status codes.\n   * @throws A \"parse\" error if the response is not valid JSON.\n   */\n  async request<Params extends JsonRpcParams, Result extends Json>(\n    jsonRpcRequest: Readonly<JsonRpcRequest<Params>>,\n    fetchOptions?: FetchOptions,\n  ): Promise<JsonRpcResponse<Result>>;\n\n  async request<Params extends JsonRpcParams, Result extends Json>(\n    jsonRpcRequest: Readonly<JsonRpcRequest<Params>>,\n    fetchOptions: FetchOptions = {},\n  ): Promise<JsonRpcResponse<Result | null>> {\n    return this.#services[0].request(jsonRpcRequest, fetchOptions);\n  }\n\n  /**\n   * Constructs the chain of RPC services. The second RPC service is\n   * configured as the failover for the first, the third service is\n   * configured as the failover for the second, etc.\n   *\n   * @param rpcServiceConfigurations - The options for the RPC services that\n   * you want to construct. Each object in this array is the same as\n   * {@link RpcServiceOptions}.\n   * @returns The constructed chain of RPC services.\n   */\n  #buildRpcServiceChain(\n    rpcServiceConfigurations: Omit<RpcServiceOptions, 'failoverService'>[],\n  ): RpcService[] {\n    return [...rpcServiceConfigurations]\n      .reverse()\n      .reduce((workingServices: RpcService[], serviceConfiguration, index) => {\n        const failoverService = index > 0 ? workingServices[0] : undefined;\n        const service = new RpcService({\n          ...serviceConfiguration,\n          failoverService,\n        });\n        return [service, ...workingServices];\n      }, []);\n  }\n}\n"]}
+{"version":3,"file":"rpc-service-chain.cjs","sourceRoot":"","sources":["../../src/rpc-service/rpc-service-chain.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  CircuitState,\n  CockatielEventEmitter,\n} from '@metamask/controller-utils';\nimport type {\n  Json,\n  JsonRpcParams,\n  JsonRpcRequest,\n  JsonRpcResponse,\n} from '@metamask/utils';\n\nimport { RpcService } from './rpc-service';\nimport type { RpcServiceOptions } from './rpc-service';\nimport type {\n  CockatielEventToEventListenerWithData,\n  ExcludeCockatielEventData,\n  ExtractCockatielEventData,\n  FetchOptions,\n} from './shared';\nimport { projectLogger, createModuleLogger } from '../logger';\n\nconst log = createModuleLogger(projectLogger, 'RpcServiceChain');\n\n/**\n * Statuses that the RPC service chain can be in.\n */\nconst STATUSES = {\n  Available: 'available',\n  Degraded: 'degraded',\n  Unknown: 'unknown',\n  Unavailable: 'unavailable',\n} as const;\n\n/**\n * Statuses that the RPC service chain can be in.\n */\ntype Status = (typeof STATUSES)[keyof typeof STATUSES];\n\n/**\n * This class constructs and manages requests to a chain of RpcService objects\n * which represent RPC endpoints with which to access a particular network. The\n * first service in the chain is intended to be the primary way of hitting the\n * network and the remaining services are used as failovers.\n */\nexport class RpcServiceChain {\n  /**\n   * The event emitter for the `onAvailable` event.\n   */\n  readonly #onAvailableEventEmitter: CockatielEventEmitter<\n    ExcludeCockatielEventData<\n      ExtractCockatielEventData<RpcService['onAvailable']>,\n      'endpointUrl'\n    >\n  >;\n\n  /**\n   * The event emitter for the `onBreak` event.\n   */\n  readonly #onBreakEventEmitter: CockatielEventEmitter<\n    ExcludeCockatielEventData<\n      ExtractCockatielEventData<RpcService['onBreak']>,\n      'endpointUrl'\n    >\n  >;\n\n  /**\n   * The event emitter for the `onDegraded` event.\n   */\n  readonly #onDegradedEventEmitter: CockatielEventEmitter<\n    ExcludeCockatielEventData<\n      ExtractCockatielEventData<RpcService['onDegraded']>,\n      'endpointUrl'\n    >\n  >;\n\n  /**\n   * The first RPC service that requests will be sent to.\n   */\n  readonly #primaryService: RpcService;\n\n  /**\n   * The RPC services in the chain.\n   */\n  readonly #services: RpcService[];\n\n  /**\n   * The status of the RPC service chain.\n   */\n  #status: Status;\n\n  /**\n   * Constructs a new RpcServiceChain object.\n   *\n   * @param rpcServiceConfigurations - The options for the RPC services\n   * that you want to construct. Each object in this array is the same as\n   * {@link RpcServiceOptions}.\n   */\n  constructor(\n    rpcServiceConfigurations: [RpcServiceOptions, ...RpcServiceOptions[]],\n  ) {\n    this.#services = rpcServiceConfigurations.map(\n      (rpcServiceConfiguration) => new RpcService(rpcServiceConfiguration),\n    );\n    this.#primaryService = this.#services[0];\n\n    this.#status = STATUSES.Unknown;\n    this.#onBreakEventEmitter = new CockatielEventEmitter<\n      ExcludeCockatielEventData<\n        ExtractCockatielEventData<RpcService['onBreak']>,\n        'endpointUrl'\n      >\n    >();\n\n    this.#onDegradedEventEmitter = new CockatielEventEmitter<\n      ExcludeCockatielEventData<\n        ExtractCockatielEventData<RpcService['onDegraded']>,\n        'endpointUrl'\n      >\n    >();\n    for (const service of this.#services) {\n      service.onDegraded((data) => {\n        if (this.#status !== STATUSES.Degraded) {\n          log('Updating status to \"degraded\"', data);\n          this.#status = STATUSES.Degraded;\n          const { endpointUrl, ...rest } = data;\n          this.#onDegradedEventEmitter.emit(rest);\n        }\n      });\n    }\n\n    this.#onAvailableEventEmitter = new CockatielEventEmitter<\n      ExcludeCockatielEventData<\n        ExtractCockatielEventData<RpcService['onAvailable']>,\n        'endpointUrl'\n      >\n    >();\n    for (const service of this.#services) {\n      service.onAvailable((data) => {\n        if (this.#status !== STATUSES.Available) {\n          log('Updating status to \"available\"', data);\n          this.#status = STATUSES.Available;\n          const { endpointUrl, ...rest } = data;\n          this.#onAvailableEventEmitter.emit(rest);\n        }\n      });\n    }\n  }\n\n  /**\n   * Calls the provided callback when any of the RPC services is retried.\n   *\n   * This is mainly useful for tests.\n   *\n   * @param listener - The callback to be called.\n   * @returns An object with a `dispose` method which can be used to unregister\n   * the event listener.\n   */\n  onServiceRetry(\n    listener: CockatielEventToEventListenerWithData<\n      RpcService['onRetry'],\n      { primaryEndpointUrl: string }\n    >,\n  ) {\n    const disposables = this.#services.map((service) =>\n      service.onRetry((data) => {\n        listener({\n          ...data,\n          primaryEndpointUrl: this.#primaryService.endpointUrl.toString(),\n        });\n      }),\n    );\n\n    return {\n      dispose() {\n        disposables.forEach((disposable) => disposable.dispose());\n      },\n    };\n  }\n\n  /**\n   * Calls the provided callback only when the maximum number of failed\n   * consecutive attempts to receive a 2xx response has been reached for all\n   * RPC services in the chain, and all services' underlying circuits have\n   * broken.\n   *\n   * The callback will not be called if a service's circuit breaks but its\n   * failover does not. Use `onServiceBreak` if you'd like a lower level of\n   * granularity.\n   *\n   * @param listener - The callback to be called.\n   * @returns An object with a `dispose` method which can be used to unregister\n   * the callback.\n   */\n  onBreak(\n    listener: (\n      data: ExcludeCockatielEventData<\n        ExtractCockatielEventData<RpcService['onBreak']>,\n        'endpointUrl'\n      >,\n    ) => void,\n  ) {\n    return this.#onBreakEventEmitter.addListener(listener);\n  }\n\n  /**\n   * Calls the provided callback each time when, for *any* of the RPC services\n   * in this chain, the maximum number of failed consecutive attempts to receive\n   * a 2xx response has been reached and the underlying circuit has broken. A\n   * more granular version of `onBreak`.\n   *\n   * @param listener - The callback to be called.\n   * @returns An object with a `dispose` method which can be used to unregister\n   * the callback.\n   */\n  onServiceBreak(\n    listener: CockatielEventToEventListenerWithData<\n      RpcService['onBreak'],\n      { primaryEndpointUrl: string }\n    >,\n  ) {\n    const disposables = this.#services.map((service) =>\n      service.onBreak((data) => {\n        listener({\n          ...data,\n          primaryEndpointUrl: this.#primaryService.endpointUrl.toString(),\n        });\n      }),\n    );\n\n    return {\n      dispose() {\n        disposables.forEach((disposable) => disposable.dispose());\n      },\n    };\n  }\n\n  /**\n   * Calls the provided callback if no requests have been initiated yet or\n   * all requests to RPC services in this chain have responded successfully in a\n   * timely fashion, and then one of the two conditions apply:\n   *\n   * 1. When a retriable error is encountered making a request to an RPC\n   * service, and the request is retried until a set maximum is reached.\n   * 2. When a RPC service responds successfully, but the request takes longer\n   * than a set number of seconds to complete.\n   *\n   * Note that the callback will be called even if there are local connectivity\n   * issues which prevent requests from being initiated. This is intentional.\n   *\n   * Also note this callback will only be called if the RPC service chain as a\n   * whole is in a \"degraded\" state, and will then only be called once (e.g., it\n   * will not be called if a failover service falls into a degraded state, then\n   * the primary comes back online, but it is slow). Use `onServiceDegraded` if\n   * you'd like a lower level of granularity.\n   *\n   * @param listener - The callback to be called.\n   * @returns An object with a `dispose` method which can be used to unregister\n   * the callback.\n   */\n  onDegraded(\n    listener: (\n      data: ExcludeCockatielEventData<\n        ExtractCockatielEventData<RpcService['onDegraded']>,\n        'endpointUrl'\n      >,\n    ) => void,\n  ) {\n    return this.#onDegradedEventEmitter.addListener(listener);\n  }\n\n  /**\n   * Calls the provided callback each time one of the two conditions apply:\n   *\n   * 1. When a retriable error is encountered making a request to an RPC\n   * service, and the request is retried until a set maximum is reached.\n   * 2. When a RPC service responds successfully, but the request takes longer\n   * than a set number of seconds to complete.\n   *\n   * Note that the callback will be called even if there are local connectivity\n   * issues which prevent requests from being initiated. This is intentional.\n   *\n   * This is a more granular version of `onDegraded`. The callback will be\n   * called for each slow request to an RPC service. It may also be called again\n   * if a failover service falls into a degraded state, then the primary comes\n   * back online, but it is slow.\n   *\n   * @param listener - The callback to be called.\n   * @returns An object with a `dispose` method which can be used to unregister\n   * the callback.\n   */\n  onServiceDegraded(\n    listener: CockatielEventToEventListenerWithData<\n      RpcService['onDegraded'],\n      { primaryEndpointUrl: string }\n    >,\n  ) {\n    const disposables = this.#services.map((service) =>\n      service.onDegraded((data) => {\n        listener({\n          ...data,\n          primaryEndpointUrl: this.#primaryService.endpointUrl.toString(),\n        });\n      }),\n    );\n\n    return {\n      dispose() {\n        disposables.forEach((disposable) => disposable.dispose());\n      },\n    };\n  }\n\n  /**\n   * Calls the provided callback in one of the following two conditions:\n   *\n   * 1. The first time that a 2xx request is made to any of the RPC services in\n   * this chain.\n   * 2. When requests to any the failover RPC services in this chain were\n   * failing such that they were degraded or their underyling circuits broke,\n   * but the first request to the primary succeeds again.\n   *\n   * Note this callback will only be called if the RPC service chain as a whole\n   * is in an \"available\" state.\n   *\n   * @param listener - The callback to be called.\n   * @returns An object with a `dispose` method which can be used to unregister\n   * the callback.\n   */\n  onAvailable(\n    listener: (\n      data: ExcludeCockatielEventData<\n        ExtractCockatielEventData<RpcService['onAvailable']>,\n        'endpointUrl'\n      >,\n    ) => void,\n  ) {\n    return this.#onAvailableEventEmitter.addListener(listener);\n  }\n\n  /**\n   * Uses the RPC services in the chain to make a request, using each service\n   * after the first as a fallback to the previous one as necessary.\n   *\n   * This overload is specifically designed for `eth_getBlockByNumber`, which\n   * can return a `result` of `null` despite an expected `Result` being\n   * provided.\n   *\n   * @param jsonRpcRequest - The JSON-RPC request to send to the endpoint.\n   * @param fetchOptions - An options bag for {@link fetch} which further\n   * specifies the request.\n   * @returns The decoded JSON-RPC response from the endpoint.\n   * @throws A 401 error if the response status is 401.\n   * @throws A \"rate limiting\" error if the response HTTP status is 429.\n   * @throws A \"resource unavailable\" error if the response status is 402, 404, or any 5xx.\n   * @throws A generic HTTP client error (-32100) for any other 4xx status codes.\n   * @throws A \"parse\" error if the response is not valid JSON.\n   */\n  async request<Params extends JsonRpcParams, Result extends Json>(\n    jsonRpcRequest: Readonly<JsonRpcRequest<Params>> & {\n      method: 'eth_getBlockByNumber';\n    },\n    fetchOptions?: FetchOptions,\n  ): Promise<JsonRpcResponse<Result> | JsonRpcResponse<null>>;\n\n  /**\n   * Uses the RPC services in the chain to make a request, using each service\n   * after the first as a fallback to the previous one as necessary.\n   *\n   * This overload is designed for all RPC methods except for\n   * `eth_getBlockByNumber`, which are expected to return a `result` of the\n   * expected `Result`.\n   *\n   * @param jsonRpcRequest - The JSON-RPC request to send to the endpoint.\n   * @param fetchOptions - An options bag for {@link fetch} which further\n   * specifies the request.\n   * @returns The decoded JSON-RPC response from the endpoint.\n   * @throws A 401 error if the response status is 401.\n   * @throws A \"rate limiting\" error if the response HTTP status is 429.\n   * @throws A \"resource unavailable\" error if the response status is 402, 404, or any 5xx.\n   * @throws A generic HTTP client error (-32100) for any other 4xx status codes.\n   * @throws A \"parse\" error if the response is not valid JSON.\n   */\n  async request<Params extends JsonRpcParams, Result extends Json>(\n    jsonRpcRequest: Readonly<JsonRpcRequest<Params>>,\n    fetchOptions?: FetchOptions,\n  ): Promise<JsonRpcResponse<Result>>;\n\n  async request<Params extends JsonRpcParams, Result extends Json>(\n    jsonRpcRequest: Readonly<JsonRpcRequest<Params>>,\n    fetchOptions: FetchOptions = {},\n  ): Promise<JsonRpcResponse<Result | null>> {\n    // Start with the primary (first) service and switch to failovers as the\n    // need arises. This is a bit confusing, so keep reading for more on how\n    // this works.\n\n    let availableServiceIndex: number | undefined;\n    let response: JsonRpcResponse<Result> | undefined;\n\n    for (const [i, service] of this.#services.entries()) {\n      log(`Trying service #${i + 1}...`);\n      const previousCircuitState = service.getCircuitState();\n\n      try {\n        // Try making the request through the service.\n        response = await service.request<Params, Result>(\n          jsonRpcRequest,\n          fetchOptions,\n        );\n        log('Service successfully received request.');\n        availableServiceIndex = i;\n        break;\n      } catch (error) {\n        // Oops, that didn't work.\n        // Capture this error so that we can handle it later.\n\n        const { lastError } = service;\n        const isCircuitOpen = service.getCircuitState() === CircuitState.Open;\n\n        log('Service failed! error =', error, 'lastError = ', lastError);\n\n        if (isCircuitOpen) {\n          if (i < this.#services.length - 1) {\n            log(\n              \"This service's circuit is open. Proceeding to next service...\",\n            );\n            continue;\n          }\n\n          if (\n            previousCircuitState !== CircuitState.Open &&\n            this.#status !== STATUSES.Unavailable &&\n            lastError !== undefined\n          ) {\n            // If the service's circuit just broke and it's the last one in the\n            // chain, then trigger the onBreak event. (But if for some reason we\n            // have already done this, then don't do it.)\n            log(\n              'This service\\'s circuit just opened and it is the last service. Updating status to \"unavailable\" and triggering onBreak.',\n            );\n            this.#status = STATUSES.Unavailable;\n            this.#onBreakEventEmitter.emit({\n              error: lastError,\n            });\n          }\n        }\n\n        // The service failed, and we throw whatever the error is. The calling\n        // code can try again if it so desires.\n        log(\n          `${isCircuitOpen ? '' : \"This service's circuit is closed. \"}Re-throwing error.`,\n        );\n        throw error;\n      }\n    }\n\n    if (response) {\n      // If one of the services is available, reset all of the circuits of the\n      // following services. If we didn't do this and the service became\n      // unavailable in the future, and any of the failovers' circuits were\n      // open (due to previous failures), we would receive a \"circuit broken\"\n      // error when we attempted to divert traffic to the failovers again.\n      //\n      if (availableServiceIndex !== undefined) {\n        for (const [i, service] of [...this.#services.entries()].slice(\n          availableServiceIndex + 1,\n        )) {\n          log(`Resetting policy for service #${i + 1}.`);\n          service.resetPolicy();\n        }\n      }\n\n      return response;\n    }\n\n    // The only way we can end up here is if there are no services to loop over.\n    // That is not possible due to the types on the constructor, but TypeScript\n    // doesn't know this, so we have to appease it.\n    throw new Error('Nothing to return');\n  }\n}\n"]}

package/dist/rpc-service/rpc-service-chain.d.cts

@@ -1,15 +1,14 @@
 import type { Json, JsonRpcParams, JsonRpcRequest, JsonRpcResponse } from "@metamask/utils";
 import { RpcService } from "./rpc-service.cjs";
 import type { RpcServiceOptions } from "./rpc-service.cjs";
-import type { RpcServiceRequestable } from "./rpc-service-requestable.cjs";
-import type { FetchOptions } from "./shared.cjs";
+import type { CockatielEventToEventListenerWithData, ExcludeCockatielEventData, ExtractCockatielEventData, FetchOptions } from "./shared.cjs";
 /**
- * This class constructs a chain of RpcService objects which represent a
- * particular network. The first object in the chain is intended to be the
- * primary way of reaching the network and the remaining objects are used as
- * failovers.
+ * 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 implements RpcServiceRequestable {
+export declare class RpcServiceChain {
     #private;
     /**
      * Constructs a new RpcServiceChain object.
@@ -18,38 +17,120 @@ export declare class RpcServiceChain implements RpcServiceRequestable {
      * that you want to construct. Each object in this array is the same as
      * {@link RpcServiceOptions}.
      */
-    constructor(rpcServiceConfigurations: Omit<RpcServiceOptions, 'failoverService'>[]);
+    constructor(rpcServiceConfigurations: [RpcServiceOptions, ...RpcServiceOptions[]]);
     /**
-     * Listens for when any of the RPC services retry a request.
+     * Calls the provided callback when any of the RPC services is retried.
      *
-     * @param listener - The callback to be called when the retry occurs.
-     * @returns What {@link RpcService.onRetry} returns.
+     * 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.
      */
-    onRetry(listener: Parameters<RpcService['onRetry']>[0]): {
+    onServiceRetry(listener: CockatielEventToEventListenerWithData<RpcService['onRetry'], {
+        primaryEndpointUrl: string;
+    }>): {
         dispose(): void;
     };
     /**
-     * Listens for when any of the RPC services retry the request too many times
-     * in a row.
+     * 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): import("cockatiel").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 when the retry occurs.
-     * @returns What {@link RpcService.onBreak} returns.
+     * @param listener - The callback to be called.
+     * @returns An object with a `dispose` method which can be used to unregister
+     * the callback.
      */
-    onBreak(listener: Parameters<RpcService['onBreak']>[0]): {
+    onServiceBreak(listener: CockatielEventToEventListenerWithData<RpcService['onBreak'], {
+        primaryEndpointUrl: string;
+    }>): {
         dispose(): void;
     };
     /**
-     * Listens for when any of the RPC services send a slow request.
+     * 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:
      *
-     * @param listener - The callback to be called when the retry occurs.
-     * @returns What {@link RpcService.onRetry} returns.
+     * 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: Parameters<RpcService['onDegraded']>[0]): {
+    onDegraded(listener: (data: ExcludeCockatielEventData<ExtractCockatielEventData<RpcService['onDegraded']>, 'endpointUrl'>) => void): import("cockatiel").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;
+    }>): {
         dispose(): void;
     };
     /**
-     * Makes a request to the first RPC service in the chain. If this service is
-     * down, then the request is forwarded to the next service in the chain, etc.
+     * 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): import("cockatiel").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
@@ -69,8 +150,8 @@ export declare class RpcServiceChain implements RpcServiceRequestable {
         method: 'eth_getBlockByNumber';
     }, fetchOptions?: FetchOptions): Promise<JsonRpcResponse<Result> | JsonRpcResponse<null>>;
     /**
-     * Makes a request to the first RPC service in the chain. If this service is
-     * down, then the request is forwarded to the next service in the chain, etc.
+     * 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

package/dist/rpc-service/rpc-service-chain.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"rpc-service-chain.d.cts","sourceRoot":"","sources":["../../src/rpc-service/rpc-service-chain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,IAAI,EACJ,aAAa,EACb,cAAc,EACd,eAAe,EAChB,wBAAwB;AAEzB,OAAO,EAAE,UAAU,EAAE,0BAAsB;AAC3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,0BAAsB;AACvD,OAAO,KAAK,EAAE,qBAAqB,EAAE,sCAAkC;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,qBAAiB;AAE7C;;;;;GAKG;AACH,qBAAa,eAAgB,YAAW,qBAAqB;;IAG3D;;;;;;OAMG;gBAED,wBAAwB,EAAE,IAAI,CAAC,iBAAiB,EAAE,iBAAiB,CAAC,EAAE;IAKxE;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;;;IAYtD;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;;;IAYtD;;;;;OAKG;IACH,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;;;IAY5D;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,CAAC,MAAM,SAAS,aAAa,EAAE,MAAM,SAAS,IAAI,EAC7D,cAAc,EAAE,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,GAAG;QACjD,MAAM,EAAE,sBAAsB,CAAC;KAChC,EACD,YAAY,CAAC,EAAE,YAAY,GAC1B,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IAE3D;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,CAAC,MAAM,SAAS,aAAa,EAAE,MAAM,SAAS,IAAI,EAC7D,cAAc,EAAE,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,EAChD,YAAY,CAAC,EAAE,YAAY,GAC1B,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;CAiCpC"}
+{"version":3,"file":"rpc-service-chain.d.cts","sourceRoot":"","sources":["../../src/rpc-service/rpc-service-chain.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,IAAI,EACJ,aAAa,EACb,cAAc,EACd,eAAe,EAChB,wBAAwB;AAEzB,OAAO,EAAE,UAAU,EAAE,0BAAsB;AAC3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,0BAAsB;AACvD,OAAO,KAAK,EACV,qCAAqC,EACrC,yBAAyB,EACzB,yBAAyB,EACzB,YAAY,EACb,qBAAiB;AAoBlB;;;;;GAKG;AACH,qBAAa,eAAe;;IA8C1B;;;;;;OAMG;gBAED,wBAAwB,EAAE,CAAC,iBAAiB,EAAE,GAAG,iBAAiB,EAAE,CAAC;IAkDvE;;;;;;;;OAQG;IACH,cAAc,CACZ,QAAQ,EAAE,qCAAqC,CAC7C,UAAU,CAAC,SAAS,CAAC,EACrB;QAAE,kBAAkB,EAAE,MAAM,CAAA;KAAE,CAC/B;;;IAkBH;;;;;;;;;;;;;OAaG;IACH,OAAO,CACL,QAAQ,EAAE,CACR,IAAI,EAAE,yBAAyB,CAC7B,yBAAyB,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,EAChD,aAAa,CACd,KACE,IAAI;IAKX;;;;;;;;;OASG;IACH,cAAc,CACZ,QAAQ,EAAE,qCAAqC,CAC7C,UAAU,CAAC,SAAS,CAAC,EACrB;QAAE,kBAAkB,EAAE,MAAM,CAAA;KAAE,CAC/B;;;IAkBH;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,UAAU,CACR,QAAQ,EAAE,CACR,IAAI,EAAE,yBAAyB,CAC7B,yBAAyB,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,EACnD,aAAa,CACd,KACE,IAAI;IAKX;;;;;;;;;;;;;;;;;;;OAmBG;IACH,iBAAiB,CACf,QAAQ,EAAE,qCAAqC,CAC7C,UAAU,CAAC,YAAY,CAAC,EACxB;QAAE,kBAAkB,EAAE,MAAM,CAAA;KAAE,CAC/B;;;IAkBH;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CACT,QAAQ,EAAE,CACR,IAAI,EAAE,yBAAyB,CAC7B,yBAAyB,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,EACpD,aAAa,CACd,KACE,IAAI;IAKX;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,CAAC,MAAM,SAAS,aAAa,EAAE,MAAM,SAAS,IAAI,EAC7D,cAAc,EAAE,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,GAAG;QACjD,MAAM,EAAE,sBAAsB,CAAC;KAChC,EACD,YAAY,CAAC,EAAE,YAAY,GAC1B,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IAE3D;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,CAAC,MAAM,SAAS,aAAa,EAAE,MAAM,SAAS,IAAI,EAC7D,cAAc,EAAE,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,EAChD,YAAY,CAAC,EAAE,YAAY,GAC1B,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;CA8FpC"}