Revamp NetworkController RPC endpoint events

packages/network-controller/CHANGELOG.md

@@ -7,8 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add `NetworkController:rpcEndpointChainAvailable` messenger event ([#7166](https://github.com/MetaMask/core/pull/7166))
+  - This is a counterpart to the (new) `NetworkController:rpcEndpointChainUnavailable` and `NetworkController:rpcEndpointChainDegraded` events, but is published when a successful request to an endpoint within a chain of endpoints is made either initially or following a previously established degraded or unavailable status.
+
 ### Changed
 
+- **BREAKING:** Split up and update payload data for `NetworkController:rpcEndpointDegraded` and `NetworkController:rpcEndpointUnavailable` ([#7166](https://github.com/MetaMask/core/pull/7166))
+  - `NetworkController:rpcEndpointDegraded` and `NetworkController:rpcEndpointUnavailable` still exist and retain the same behavior as before.
+  - New events are `NetworkController:rpcEndpointChainDegraded` and `NetworkController:rpcEndpointChainUnavailable`, and are designed to represent an entire chain of endpoints. They are also guaranteed to not be published multiple times in a row. In particular, `NetworkController:rpcEndpointChainUnavailable` is published only after trying all of the endpoints for a chain and when the underlying circuit for the last endpoint breaks, not as each primary's or failover's circuit breaks.
+  - The event payloads have been changed:
+    - For individual endpoint events (`NetworkController:rpcEndpointUnavailable`, `NetworkController:rpcEndpointDegraded`): `failoverEndpointUrl` has been removed, and `primaryEndpointUrl` has been added. In addition, `networkClientId` has been added to the payload.
+    - For chain-level events (`NetworkController:rpcEndpointChainUnavailable`, `NetworkController:rpcEndpointChainDegraded`, `NetworkController:rpcEndpointChainAvailable`): These include `chainId`, `networkClientId`, and event-specific fields (e.g., `error`, `endpointUrl`) but do not include `primaryEndpointUrl`. Consumers can derive endpoint information from the `networkClientId` using `NetworkController:getNetworkClientById` or `NetworkController:getNetworkConfigurationByNetworkClientId`.
+- **BREAKING:** Rename and update payload data for `NetworkController:rpcEndpointRequestRetried` ([#7166](https://github.com/MetaMask/core/pull/7166))
+  - This event is now called `NetworkController:rpcEndpointRetried`.
+  - The event payload has been changed as well: `failoverEndpointUrl` has been removed, and `primaryEndpointUrl` has been added. In addition, `networkClientId` and `attempt` have been added to the payload.
+- **BREAKING:** Update `AbstractRpcService`/`RpcServiceRequestable` to remove `{ isolated: true }` from the `onBreak` event data type ([#7166](https://github.com/MetaMask/core/pull/7166))
+  - This represented the error produced when `isolate` is called on a Cockatiel circuit breaker policy. This never happens for our service (we use `isolate` internally, but this error is suppressed and cannot trigger `onBreak`)
 - Move peer dependencies for controller and service packages to direct dependencies ([#7209](https://github.com/MetaMask/core/pull/7209))
   - The dependencies moved are:
     - `@metamask/error-reporting-service` (^3.0.0)

packages/network-controller/package.json

@@ -78,6 +78,7 @@
     "@types/jest-when": "^2.7.3",
     "@types/lodash": "^4.14.191",
     "@types/node-fetch": "^2.6.12",
+    "cockatiel": "^3.1.2",
     "deep-freeze-strict": "^1.1.1",
     "deepmerge": "^4.2.2",
     "jest": "^27.5.1",

packages/network-controller/src/NetworkController.ts

@@ -443,25 +443,112 @@ export type NetworkControllerNetworkRemovedEvent = {
 };
 
 /**
- * `rpcEndpointUnavailable` is published after an attempt to make a request to
- * an RPC endpoint fails too many times in a row (because of a connection error
- * or an unusable response).
+ * `NetworkController:rpcEndpointChainUnavailable` is published when, after
+ * trying all endpoints in an endpoint chain, the last failover reaches a
+ * maximum number of consecutive 5xx responses, breaking the underlying circuit.
+ *
+ * In other words, this event will not be published if a failover is available,
+ * even if the primary is not.
+ *
+ * @param payload - The event payload.
+ * @param payload.chainId - The target network's chain ID.
+ * @param payload.error - The last error produced by the last failover in the
+ * endpoint chain.
+ * @param payload.networkClientId - The target network's client ID.
+ */
+export type NetworkControllerRpcEndpointChainUnavailableEvent = {
+  type: 'NetworkController:rpcEndpointChainUnavailable';
+  payload: [
+    {
+      chainId: Hex;
+      error: unknown;
+      networkClientId: NetworkClientId;
+    },
+  ];
+};
+
+/**
+ * `NetworkController:rpcEndpointUnavailable` is published when any
+ * endpoint in an endpoint chain reaches a maximum number of consecutive 5xx
+ * responses, breaking the underlying circuit.
+ *
+ * In other words, this event will be published if a primary is not available,
+ * even if a failover is.
+ *
+ * @param payload - The event payload.
+ * @param payload.chainId - The target network's chain ID.
+ * @param payload.endpointUrl - The URL of the endpoint which reached the
+ * maximum number of consecutive 5xx responses. You can compare this to
+ * `primaryEndpointUrl` to know whether it was a failover or a primary.
+ * @param payload.error - The last error produced by the endpoint.
+ * @param payload.networkClientId - The target network's client ID.
+ * @param payload.primaryEndpointUrl - The endpoint chain's primary URL.
  */
 export type NetworkControllerRpcEndpointUnavailableEvent = {
   type: 'NetworkController:rpcEndpointUnavailable';
   payload: [
     {
       chainId: Hex;
       endpointUrl: string;
-      failoverEndpointUrl?: string;
       error: unknown;
+      networkClientId: NetworkClientId;
+      primaryEndpointUrl: string;
     },
   ];
 };
 
 /**
- * `rpcEndpointDegraded` is published after a request to an RPC endpoint
- * responds successfully but takes too long.
+ * `NetworkController:rpcEndpointChainDegraded` is published for any of the
+ * endpoints in an endpoint chain when one of the following two conditions hold
+ * (and the chain is not already in a degraded state):
+ *
+ * 1. A successful (2xx) request, even after being retried, cannot be made to
+ * the endpoint.
+ * 2. A successful (2xx) request can be made to the endpoint, but it takes
+ * longer than expected to complete.
+ *
+ * Note that this event will be published even if there are local connectivity
+ * issues which prevent requests from being initiated. This is intentional.
+ *
+ * @param payload - The event payload.
+ * @param payload.chainId - The target network's chain ID.
+ * @param payload.error - The last error produced by the endpoint (or
+ * `undefined` if the request was slow).
+ * @param payload.networkClientId - The target network's client ID.
+ */
+export type NetworkControllerRpcEndpointChainDegradedEvent = {
+  type: 'NetworkController:rpcEndpointChainDegraded';
+  payload: [
+    {
+      chainId: Hex;
+      error: unknown;
+      networkClientId: NetworkClientId;
+    },
+  ];
+};
+
+/**
+ *
+ * `NetworkController:rpcEndpointDegraded` is published for any of the endpoints
+ * in an endpoint chain when:
+ *
+ * 1. A successful (2xx) request, even after being retried, cannot be made to
+ * the endpoint.
+ * 2. A successful (2xx) request can be made to the endpoint, but it takes
+ * longer than expected to complete.
+ *
+ * Note that this event will be published even if there are local connectivity
+ * issues which prevent requests from being initiated. This is intentional.
+ *
+ * @param payload - The event payload.
+ * @param payload.chainId - The target network's chain ID.
+ * @param payload.endpointUrl - The URL of the endpoint for which requests
+ * failed or were slow to complete. You can compare this to `primaryEndpointUrl`
+ * to know whether it was a failover or a primary.
+ * @param payload.error - The last error produced by the endpoint (or
+ * `undefined` if the request was slow).
+ * @param payload.networkClientId - The target network's client ID.
+ * @param payload.primaryEndpointUrl - The endpoint chain's primary URL.
  */
 export type NetworkControllerRpcEndpointDegradedEvent = {
   type: 'NetworkController:rpcEndpointDegraded';
@@ -470,20 +557,59 @@ export type NetworkControllerRpcEndpointDegradedEvent = {
       chainId: Hex;
       endpointUrl: string;
       error: unknown;
+      networkClientId: NetworkClientId;
+      primaryEndpointUrl: string;
     },
   ];
 };
 
 /**
- * `rpcEndpointRequestRetried` is published after a request to an RPC endpoint
- * is retried following a connection error or an unusable response.
+ * `NetworkController:rpcEndpointChainAvailable` is published in one of two
+ * cases:
+ *
+ * 1. The first time that a 2xx request is made to any of the endpoints in an
+ * endpoint chain.
+ * 2. When requests to any of the endpoints previously failed (placing the
+ * endpoint in a degraded or unavailable status), but are now succeeding again.
+ *
+ * @param payload - The event payload.
+ * @param payload.chainId - The target network's chain ID.
+ * @param payload.networkClientId - The target network's client ID.
  */
-export type NetworkControllerRpcEndpointRequestRetriedEvent = {
-  type: 'NetworkController:rpcEndpointRequestRetried';
+export type NetworkControllerRpcEndpointChainAvailableEvent = {
+  type: 'NetworkController:rpcEndpointChainAvailable';
+  payload: [
+    {
+      chainId: Hex;
+      networkClientId: NetworkClientId;
+    },
+  ];
+};
+
+/**
+ * `NetworkController:rpcEndpointRetried` is published before a request to any
+ * endpoint in an endpoint chain is retried.
+ *
+ * This is mainly useful for tests.
+ *
+ * @param payload - The event payload.
+ * @param payload.attempt - The current attempt counter for the endpoint
+ * (starting from 0).
+ * @param payload.chainId - The target network's chain ID.
+ * @param payload.endpointUrl - The URL of the endpoint being retried.
+ * @param payload.networkClientId - The target network's client ID.
+ * @param payload.primaryEndpointUrl - The endpoint chain's primary URL.
+ * @see {@link RpcService} for the list of retriable errors.
+ */
+export type NetworkControllerRpcEndpointRetriedEvent = {
+  type: 'NetworkController:rpcEndpointRetried';
   payload: [
     {
-      endpointUrl: string;
       attempt: number;
+      chainId: Hex;
+      endpointUrl: string;
+      networkClientId: NetworkClientId;
+      primaryEndpointUrl: string;
     },
   ];
 };
@@ -496,9 +622,12 @@ export type NetworkControllerEvents =
   | NetworkControllerInfuraIsUnblockedEvent
   | NetworkControllerNetworkAddedEvent
   | NetworkControllerNetworkRemovedEvent
+  | NetworkControllerRpcEndpointChainUnavailableEvent
   | NetworkControllerRpcEndpointUnavailableEvent
+  | NetworkControllerRpcEndpointChainDegradedEvent
   | NetworkControllerRpcEndpointDegradedEvent
-  | NetworkControllerRpcEndpointRequestRetriedEvent;
+  | NetworkControllerRpcEndpointChainAvailableEvent
+  | NetworkControllerRpcEndpointRetriedEvent;
 
 /**
  * All events that {@link NetworkController} calls internally.
@@ -2800,6 +2929,7 @@ export class NetworkController extends BaseController<
         autoManagedNetworkClientRegistry[NetworkClientType.Infura][
           addedRpcEndpoint.networkClientId
         ] = createAutoManagedNetworkClient({
+          networkClientId: addedRpcEndpoint.networkClientId,
           networkClientConfiguration: {
             type: NetworkClientType.Infura,
             chainId: networkFields.chainId,
@@ -2818,6 +2948,7 @@ export class NetworkController extends BaseController<
         autoManagedNetworkClientRegistry[NetworkClientType.Custom][
           addedRpcEndpoint.networkClientId
         ] = createAutoManagedNetworkClient({
+          networkClientId: addedRpcEndpoint.networkClientId,
           networkClientConfiguration: {
             type: NetworkClientType.Custom,
             chainId: networkFields.chainId,
@@ -2980,6 +3111,7 @@ export class NetworkController extends BaseController<
           return [
             rpcEndpoint.networkClientId,
             createAutoManagedNetworkClient({
+              networkClientId: rpcEndpoint.networkClientId,
               networkClientConfiguration: {
                 type: NetworkClientType.Infura,
                 network: infuraNetworkName,
@@ -2999,6 +3131,7 @@ export class NetworkController extends BaseController<
         return [
           rpcEndpoint.networkClientId,
           createAutoManagedNetworkClient({
+            networkClientId: rpcEndpoint.networkClientId,
             networkClientConfiguration: {
               type: NetworkClientType.Custom,
               chainId: networkConfiguration.chainId,