feat(network-controller): force RPC failover via remote flag

packages/network-controller/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **BREAKING:** Drive RPC failover from the single `corePlatformRpcFailoverMode` remote feature flag ([#9175](https://github.com/MetaMask/core/pull/9175))
+  - The flag is a string with three values: `disabled` (failover off), `enabled` (divert to failover URLs when the primary endpoint is unavailable), and `forced` (Infura endpoints that have failover URLs route all traffic to those URLs, bypassing Infura entirely). Custom endpoints are unaffected, and the value defaults to `disabled` when the flag is absent or unrecognized.
+  - `NetworkController` no longer reads the `walletFrameworkRpcFailoverEnabled` flag; the `enabled` mode replaces it. Update your remote feature flag configuration to set `corePlatformRpcFailoverMode`.
+
+### Removed
+
+- **BREAKING:** Remove the `NetworkController.enableRpcFailover` and `NetworkController.disableRpcFailover` methods, their `NetworkController:enableRpcFailover` / `NetworkController:disableRpcFailover` messenger actions, and the `NetworkControllerEnableRpcFailoverAction` / `NetworkControllerDisableRpcFailoverAction` types ([#9175](https://github.com/MetaMask/core/pull/9175))
+  - RPC failover is now driven entirely by the `corePlatformRpcFailoverMode` remote feature flag, so there is no longer an imperative toggle.
+
 ## [33.0.0]
 
 ### Added

packages/network-controller/src/NetworkController-method-action-types.ts

@@ -16,26 +16,6 @@ export type NetworkControllerGetEthQueryAction = {
   handler: NetworkController['getEthQuery'];
 };
 
-/**
- * Enables the RPC failover functionality. That is, if any RPC endpoints are
- * configured with failover URLs, then traffic will automatically be diverted
- * to them if those RPC endpoints are unavailable.
- */
-export type NetworkControllerEnableRpcFailoverAction = {
-  type: `NetworkController:enableRpcFailover`;
-  handler: NetworkController['enableRpcFailover'];
-};
-
-/**
- * Disables the RPC failover functionality. That is, even if any RPC endpoints
- * are configured with failover URLs, then traffic will not automatically be
- * diverted to them if those RPC endpoints are unavailable.
- */
-export type NetworkControllerDisableRpcFailoverAction = {
-  type: `NetworkController:disableRpcFailover`;
-  handler: NetworkController['disableRpcFailover'];
-};
-
 /**
  * Accesses the provider and block tracker for the currently selected network.
  *
@@ -309,8 +289,6 @@ export type NetworkControllerFindNetworkClientIdByChainIdAction = {
  */
 export type NetworkControllerMethodActions =
   | NetworkControllerGetEthQueryAction
-  | NetworkControllerEnableRpcFailoverAction
-  | NetworkControllerDisableRpcFailoverAction
   | NetworkControllerGetProviderAndBlockTrackerAction
   | NetworkControllerGetSelectedNetworkClientAction
   | NetworkControllerGetSelectedChainIdAction

packages/network-controller/src/NetworkController.ts

@@ -56,7 +56,8 @@ import type { DegradedEventType, RetryReason } from './create-network-client';
 import { projectLogger, createModuleLogger } from './logger';
 import type { NetworkControllerMethodActions } from './NetworkController-method-action-types';
 import type { RpcServiceOptionsWithDefaults } from './rpc-service/rpc-service';
-import { getIsRpcFailoverEnabled } from './selectors';
+import { getRpcFailoverMode } from './selectors';
+import type { RpcFailoverMode } from './selectors';
 import { NetworkClientType } from './types';
 import type {
   BlockTracker,
@@ -668,8 +669,6 @@ type AllowedEvents = RemoteFeatureFlagControllerStateChangeEvent;
 
 const MESSENGER_EXPOSED_METHODS = [
   'addNetwork',
-  'disableRpcFailover',
-  'enableRpcFailover',
   'findNetworkClientIdByChainId',
   'get1559CompatibilityWithNetworkClientId',
   'getEIP1559Compatibility',
@@ -1273,7 +1272,7 @@ export class NetworkController extends BaseController<
     NetworkConfiguration
   >;
 
-  #isRpcFailoverEnabled = false;
+  #rpcFailoverMode: RpcFailoverMode = 'disabled';
 
   /**
    * Constructs a NetworkController.
@@ -1373,10 +1372,10 @@ export class NetworkController extends BaseController<
     this.messenger.subscribe(
       // eslint-disable-next-line no-restricted-syntax
       'RemoteFeatureFlagController:stateChange',
-      (isRpcFailoverEnabled) => {
-        this.#updateRpcFailoverEnabled(isRpcFailoverEnabled);
+      (rpcFailoverMode) => {
+        this.#updateRpcFailover(rpcFailoverMode);
       },
-      getIsRpcFailoverEnabled,
+      getRpcFailoverMode,
     );
   }
 
@@ -1391,38 +1390,19 @@ export class NetworkController extends BaseController<
   }
 
   /**
-   * Enables the RPC failover functionality. That is, if any RPC endpoints are
-   * configured with failover URLs, then traffic will automatically be diverted
-   * to them if those RPC endpoints are unavailable.
-   */
-  enableRpcFailover(): void {
-    this.#updateRpcFailoverEnabled(true);
-  }
-
-  /**
-   * Disables the RPC failover functionality. That is, even if any RPC endpoints
-   * are configured with failover URLs, then traffic will not automatically be
-   * diverted to them if those RPC endpoints are unavailable.
-   */
-  disableRpcFailover(): void {
-    this.#updateRpcFailoverEnabled(false);
-  }
-
-  /**
-   * Enables or disables the RPC failover functionality, depending on the
-   * boolean given. This is done by reconstructing all network clients that were
-   * originally configured with failover URLs so that those URLs are either
-   * honored or ignored. Network client IDs will be preserved so as not to
-   * invalidate state in other controllers.
+   * Invokes the given callback for each auto-managed network client that was
+   * configured with failover URLs. Used to reconstruct those clients when an
+   * RPC failover setting changes.
    *
-   * @param newIsRpcFailoverEnabled - Whether or not to enable or disable the
-   * RPC failover functionality.
-   */
-  #updateRpcFailoverEnabled(newIsRpcFailoverEnabled: boolean): void {
-    if (this.#isRpcFailoverEnabled === newIsRpcFailoverEnabled) {
-      return;
-    }
-
+   * @param callback - Called with each network client that has failover URLs.
+   */
+  #forEachNetworkClientWithFailover(
+    callback: (
+      networkClient:
+        | AutoManagedNetworkClient<InfuraNetworkClientConfiguration>
+        | AutoManagedNetworkClient<CustomNetworkClientConfiguration>,
+    ) => void,
+  ): void {
     const autoManagedNetworkClientRegistry =
       this.#ensureAutoManagedNetworkClientRegistryPopulated();
 
@@ -1439,14 +1419,44 @@ export class NetworkController extends BaseController<
           networkClient.configuration.failoverRpcUrls &&
           networkClient.configuration.failoverRpcUrls.length > 0
         ) {
-          newIsRpcFailoverEnabled
-            ? networkClient.enableRpcFailover()
-            : networkClient.disableRpcFailover();
+          callback(networkClient);
         }
       }
     }
+  }
+
+  /**
+   * Applies the given RPC failover mode by reconstructing all network clients
+   * that were configured with failover URLs so that the new mode takes effect.
+   * Network client IDs are preserved so as not to invalidate state in other
+   * controllers.
+   *
+   * @param newMode - The RPC failover mode to apply.
+   */
+  #updateRpcFailover(newMode: RpcFailoverMode): void {
+    if (this.#rpcFailoverMode === newMode) {
+      return;
+    }
+
+    const wasEnabled = this.#rpcFailoverMode === 'enabled';
+    const wasForced = this.#rpcFailoverMode === 'forced';
+    const isEnabled = newMode === 'enabled';
+    const isForced = newMode === 'forced';
+
+    this.#forEachNetworkClientWithFailover((networkClient) => {
+      if (isEnabled !== wasEnabled) {
+        isEnabled
+          ? networkClient.enableRpcFailover()
+          : networkClient.disableRpcFailover();
+      }
+      if (isForced !== wasForced) {
+        isForced
+          ? networkClient.enableForcedRpcFailover()
+          : networkClient.disableForcedRpcFailover();
+      }
+    });
 
-    this.#isRpcFailoverEnabled = newIsRpcFailoverEnabled;
+    this.#rpcFailoverMode = newMode;
   }
 
   /**
@@ -1610,12 +1620,13 @@ export class NetworkController extends BaseController<
   }
 
   /**
-   * Initialize the NetworkController, updating the RPC failover feature flag
-   * and applying the network selection.
+   * Initialize the NetworkController, updating the RPC failover feature flags
+   * (`isRpcFailoverEnabled` and `isRpcFailoverForced`) and applying the network
+   * selection.
    */
   init(): void {
     const state = this.messenger.call('RemoteFeatureFlagController:getState');
-    this.#updateRpcFailoverEnabled(getIsRpcFailoverEnabled(state));
+    this.#updateRpcFailover(getRpcFailoverMode(state));
 
     this.#applyNetworkSelection(this.state.selectedNetworkClientId);
   }
@@ -2859,7 +2870,8 @@ export class NetworkController extends BaseController<
           getRpcServiceOptions: this.#getRpcServiceOptions,
           getBlockTrackerOptions: this.#getBlockTrackerOptions,
           messenger: this.messenger,
-          isRpcFailoverEnabled: this.#isRpcFailoverEnabled,
+          isRpcFailoverEnabled: this.#rpcFailoverMode === 'enabled',
+          isRpcFailoverForced: this.#rpcFailoverMode === 'forced',
           logger: this.#log,
         });
       } else {
@@ -2878,7 +2890,8 @@ export class NetworkController extends BaseController<
           getRpcServiceOptions: this.#getRpcServiceOptions,
           getBlockTrackerOptions: this.#getBlockTrackerOptions,
           messenger: this.messenger,
-          isRpcFailoverEnabled: this.#isRpcFailoverEnabled,
+          isRpcFailoverEnabled: this.#rpcFailoverMode === 'enabled',
+          isRpcFailoverForced: this.#rpcFailoverMode === 'forced',
           logger: this.#log,
         });
       }
@@ -3044,7 +3057,8 @@ export class NetworkController extends BaseController<
               getRpcServiceOptions: this.#getRpcServiceOptions,
               getBlockTrackerOptions: this.#getBlockTrackerOptions,
               messenger: this.messenger,
-              isRpcFailoverEnabled: this.#isRpcFailoverEnabled,
+              isRpcFailoverEnabled: this.#rpcFailoverMode === 'enabled',
+              isRpcFailoverForced: this.#rpcFailoverMode === 'forced',
               logger: this.#log,
             }),
           ] as const;
@@ -3063,7 +3077,8 @@ export class NetworkController extends BaseController<
             getRpcServiceOptions: this.#getRpcServiceOptions,
             getBlockTrackerOptions: this.#getBlockTrackerOptions,
             messenger: this.messenger,
-            isRpcFailoverEnabled: this.#isRpcFailoverEnabled,
+            isRpcFailoverEnabled: this.#rpcFailoverMode === 'enabled',
+            isRpcFailoverForced: this.#rpcFailoverMode === 'forced',
             logger: this.#log,
           }),
         ] as const;