feat: add override functionality to remote feature flags

packages/remote-feature-flag-controller/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add override functionality to remote feature flags ([#7271](https://github.com/MetaMask/core/pull/7271))
+  - `setFlagOverride(flagName, value)` - Set a local override for a specific feature flag
+  - `removeFlagOverride(flagName)` - Clear the local override for a specific feature flag
+  - `clearAllFlagOverrides()` - Clear all local feature flag overrides
+- Add new controller state properties ([#7271](https://github.com/MetaMask/core/pull/7271))
+  - `localOverrides` - Local overrides for feature flags that take precedence over remote flags
+  - `rawRemoteFeatureFlags` - Raw flag value for all feature flags
+- Export additional controller action types ([#7271](https://github.com/MetaMask/core/pull/7271))
+  - `RemoteFeatureFlagControllerSetFlagOverrideAction`
+  - `RemoteFeatureFlagControllerremoveFlagOverrideAction`
+  - `RemoteFeatureFlagControllerclearAllFlagOverridesAction`
+
+### Changed
+
+- Controller state now includes metadata for new properties with appropriate persistence and logging settings ([#7271](https://github.com/MetaMask/core/pull/7271))
+
 ## [3.0.0]
 
 ### Added

packages/remote-feature-flag-controller/src/index.ts

@@ -5,6 +5,9 @@ export type {
   RemoteFeatureFlagControllerActions,
   RemoteFeatureFlagControllerGetStateAction,
   RemoteFeatureFlagControllerUpdateRemoteFeatureFlagsAction,
+  RemoteFeatureFlagControllerSetFlagOverrideAction,
+  RemoteFeatureFlagControllerRemoveFlagOverrideAction,
+  RemoteFeatureFlagControllerClearAllFlagOverridesAction,
   RemoteFeatureFlagControllerEvents,
   RemoteFeatureFlagControllerStateChangeEvent,
 } from './remote-feature-flag-controller';

packages/remote-feature-flag-controller/src/remote-feature-flag-controller-types.ts

@@ -51,3 +51,25 @@ export type ServiceResponse = {
   remoteFeatureFlags: FeatureFlags;
   cacheTimestamp: number | null;
 };
+
+/**
+ * Describes the shape of the state object for the {@link RemoteFeatureFlagController}.
+ */
+export type RemoteFeatureFlagControllerState = {
+  /**
+   * The collection of feature flags and their respective values, which can be objects.
+   */
+  remoteFeatureFlags: FeatureFlags;
+  /**
+   * Local overrides for feature flags that take precedence over remote flags.
+   */
+  localOverrides: FeatureFlags;
+  /**
+   * Raw A/B test flag arrays for flags that were processed from arrays to single values.
+   */
+  rawRemoteFeatureFlags: FeatureFlags;
+  /**
+   * The timestamp of the last successful feature flag cache.
+   */
+  cacheTimestamp: number;
+};

packages/remote-feature-flag-controller/src/remote-feature-flag-controller.test.ts

@@ -9,6 +9,7 @@ import type {
 import type { AbstractClientConfigApiService } from './client-config-api-service/abstract-client-config-api-service';
 import {
   RemoteFeatureFlagController,
+  controllerName,
   DEFAULT_CACHE_DURATION,
   getDefaultRemoteFeatureFlagControllerState,
 } from './remote-feature-flag-controller';
@@ -18,8 +19,6 @@ import type {
 } from './remote-feature-flag-controller';
 import type { FeatureFlags } from './remote-feature-flag-controller-types';
 
-const controllerName = 'RemoteFeatureFlagController';
-
 const MOCK_FLAGS: FeatureFlags = {
   feature1: true,
   feature2: { chrome: '<109' },
@@ -88,6 +87,8 @@ describe('RemoteFeatureFlagController', () => {
 
       expect(controller.state).toStrictEqual({
         remoteFeatureFlags: {},
+        localOverrides: {},
+        rawRemoteFeatureFlags: {},
         cacheTimestamp: 0,
       });
     });
@@ -97,6 +98,8 @@ describe('RemoteFeatureFlagController', () => {
 
       expect(controller.state).toStrictEqual({
         remoteFeatureFlags: {},
+        localOverrides: {},
+        rawRemoteFeatureFlags: {},
         cacheTimestamp: 0,
       });
     });
@@ -105,6 +108,8 @@ describe('RemoteFeatureFlagController', () => {
       const customState = {
         remoteFeatureFlags: MOCK_FLAGS_TWO,
         cacheTimestamp: 123456789,
+        rawRemoteFeatureFlags: {},
+        localOverrides: {},
       };
 
       const controller = createController({ state: customState });
@@ -640,11 +645,116 @@ describe('RemoteFeatureFlagController', () => {
     it('should return default state', () => {
       expect(getDefaultRemoteFeatureFlagControllerState()).toStrictEqual({
         remoteFeatureFlags: {},
+        localOverrides: {},
+        rawRemoteFeatureFlags: {},
         cacheTimestamp: 0,
       });
     });
   });
 
+  describe('override functionality', () => {
+    describe('setFlagOverride', () => {
+      it('sets a local override for a feature flag', () => {
+        const controller = createController();
+
+        controller.setFlagOverride('testFlag', true);
+
+        expect(controller.state.localOverrides).toStrictEqual({
+          testFlag: true,
+        });
+      });
+
+      it('overwrites existing override for the same flag', () => {
+        const controller = createController();
+
+        controller.setFlagOverride('testFlag', true);
+        controller.setFlagOverride('testFlag', false);
+
+        expect(controller.state.localOverrides).toStrictEqual({
+          testFlag: false,
+        });
+      });
+
+      it('preserves other overrides when setting a new one', () => {
+        const controller = createController();
+
+        controller.setFlagOverride('flag1', 'value1');
+        controller.setFlagOverride('flag2', 'value2');
+
+        expect(controller.state.localOverrides).toStrictEqual({
+          flag1: 'value1',
+          flag2: 'value2',
+        });
+      });
+    });
+
+    describe('removeFlagOverride', () => {
+      it('removes a specific override', () => {
+        const controller = createController();
+
+        controller.setFlagOverride('flag1', 'value1');
+        controller.setFlagOverride('flag2', 'value2');
+        controller.removeFlagOverride('flag1');
+
+        expect(controller.state.localOverrides).toStrictEqual({
+          flag2: 'value2',
+        });
+      });
+
+      it('does not affect state when clearing non-existent override', () => {
+        const controller = createController();
+
+        controller.setFlagOverride('flag1', 'value1');
+        controller.removeFlagOverride('nonExistentFlag');
+
+        expect(controller.state.localOverrides).toStrictEqual({
+          flag1: 'value1',
+        });
+      });
+    });
+
+    describe('clearAllFlagOverrides', () => {
+      it('removes all overrides', () => {
+        const controller = createController();
+
+        controller.setFlagOverride('flag1', 'value1');
+        controller.setFlagOverride('flag2', 'value2');
+        controller.clearAllFlagOverrides();
+
+        expect(controller.state.localOverrides).toStrictEqual({});
+      });
+
+      it('does not affect state when no overrides exist', () => {
+        const controller = createController();
+
+        controller.clearAllFlagOverrides();
+
+        expect(controller.state.localOverrides).toStrictEqual({});
+      });
+    });
+
+    describe('integration with remote flags', () => {
+      it('preserves overrides when remote flags are updated', async () => {
+        const clientConfigApiService = buildClientConfigApiService({
+          remoteFeatureFlags: { remoteFlag: 'initialRemoteValue' },
+        });
+        const controller = createController({ clientConfigApiService });
+
+        // Set overrides before fetching remote flags
+        controller.setFlagOverride('overrideFlag', 'overrideValue');
+        controller.setFlagOverride('remoteFlag', 'updatedRemoteValue');
+
+        await controller.updateRemoteFeatureFlags();
+
+        // Overrides should be preserved when remote flags are updated.
+        expect(controller.state.localOverrides).toStrictEqual({
+          overrideFlag: 'overrideValue',
+          remoteFlag: 'updatedRemoteValue',
+        });
+      });
+    });
+  });
+
   describe('metadata', () => {
     it('includes expected state in debug snapshots', () => {
       const controller = createController();
@@ -658,6 +768,8 @@ describe('RemoteFeatureFlagController', () => {
       ).toMatchInlineSnapshot(`
         Object {
           "cacheTimestamp": 0,
+          "localOverrides": Object {},
+          "rawRemoteFeatureFlags": Object {},
           "remoteFeatureFlags": Object {},
         }
       `);
@@ -675,6 +787,8 @@ describe('RemoteFeatureFlagController', () => {
       ).toMatchInlineSnapshot(`
         Object {
           "cacheTimestamp": 0,
+          "localOverrides": Object {},
+          "rawRemoteFeatureFlags": Object {},
           "remoteFeatureFlags": Object {},
         }
       `);
@@ -692,6 +806,8 @@ describe('RemoteFeatureFlagController', () => {
       ).toMatchInlineSnapshot(`
         Object {
           "cacheTimestamp": 0,
+          "localOverrides": Object {},
+          "rawRemoteFeatureFlags": Object {},
           "remoteFeatureFlags": Object {},
         }
       `);
@@ -708,6 +824,7 @@ describe('RemoteFeatureFlagController', () => {
         ),
       ).toMatchInlineSnapshot(`
         Object {
+          "localOverrides": Object {},
           "remoteFeatureFlags": Object {},
         }
       `);

packages/remote-feature-flag-controller/src/remote-feature-flag-controller.ts

@@ -21,13 +21,15 @@ import { isVersionFeatureFlag, getVersionData } from './utils/version';
 
 // === GENERAL ===
 
-const controllerName = 'RemoteFeatureFlagController';
+export const controllerName = 'RemoteFeatureFlagController';
 export const DEFAULT_CACHE_DURATION = 24 * 60 * 60 * 1000; // 1 day
 
 // === STATE ===
 
 export type RemoteFeatureFlagControllerState = {
   remoteFeatureFlags: FeatureFlags;
+  localOverrides: FeatureFlags;
+  rawRemoteFeatureFlags: FeatureFlags;
   cacheTimestamp: number;
 };
 
@@ -38,6 +40,18 @@ const remoteFeatureFlagControllerMetadata = {
     includeInDebugSnapshot: true,
     usedInUi: true,
   },
+  localOverrides: {
+    includeInStateLogs: true,
+    persist: true,
+    includeInDebugSnapshot: true,
+    usedInUi: true,
+  },
+  rawRemoteFeatureFlags: {
+    includeInStateLogs: true,
+    persist: true,
+    includeInDebugSnapshot: true,
+    usedInUi: false,
+  },
   cacheTimestamp: {
     includeInStateLogs: true,
     persist: true,
@@ -62,9 +76,27 @@ export type RemoteFeatureFlagControllerUpdateRemoteFeatureFlagsAction = {
   handler: RemoteFeatureFlagController['updateRemoteFeatureFlags'];
 };
 
+export type RemoteFeatureFlagControllerSetFlagOverrideAction = {
+  type: `${typeof controllerName}:setFlagOverride`;
+  handler: RemoteFeatureFlagController['setFlagOverride'];
+};
+
+export type RemoteFeatureFlagControllerRemoveFlagOverrideAction = {
+  type: `${typeof controllerName}:removeFlagOverride`;
+  handler: RemoteFeatureFlagController['removeFlagOverride'];
+};
+
+export type RemoteFeatureFlagControllerClearAllFlagOverridesAction = {
+  type: `${typeof controllerName}:clearAllFlagOverrides`;
+  handler: RemoteFeatureFlagController['clearAllFlagOverrides'];
+};
+
 export type RemoteFeatureFlagControllerActions =
   | RemoteFeatureFlagControllerGetStateAction
-  | RemoteFeatureFlagControllerUpdateRemoteFeatureFlagsAction;
+  | RemoteFeatureFlagControllerUpdateRemoteFeatureFlagsAction
+  | RemoteFeatureFlagControllerSetFlagOverrideAction
+  | RemoteFeatureFlagControllerRemoveFlagOverrideAction
+  | RemoteFeatureFlagControllerClearAllFlagOverridesAction;
 
 export type RemoteFeatureFlagControllerStateChangeEvent =
   ControllerStateChangeEvent<
@@ -89,6 +121,8 @@ export type RemoteFeatureFlagControllerMessenger = Messenger<
 export function getDefaultRemoteFeatureFlagControllerState(): RemoteFeatureFlagControllerState {
   return {
     remoteFeatureFlags: {},
+    localOverrides: {},
+    rawRemoteFeatureFlags: {},
     cacheTimestamp: 0,
   };
 }
@@ -218,6 +252,8 @@ export class RemoteFeatureFlagController extends BaseController<
     this.update(() => {
       return {
         remoteFeatureFlags: processedRemoteFeatureFlags,
+        localOverrides: this.state.localOverrides,
+        rawRemoteFeatureFlags: remoteFeatureFlags,
         cacheTimestamp: Date.now(),
       };
     });
@@ -291,4 +327,50 @@ export class RemoteFeatureFlagController extends BaseController<
   disable(): void {
     this.#disabled = true;
   }
+
+  /**
+   * Sets a local override for a specific feature flag.
+   *
+   * @param flagName - The name of the feature flag to override.
+   * @param value - The override value for the feature flag.
+   */
+  setFlagOverride(flagName: string, value: Json): void {
+    this.update(() => {
+      return {
+        ...this.state,
+        localOverrides: {
+          ...this.state.localOverrides,
+          [flagName]: value,
+        },
+      };
+    });
+  }
+
+  /**
+   * Clears the local override for a specific feature flag.
+   *
+   * @param flagName - The name of the feature flag to clear.
+   */
+  removeFlagOverride(flagName: string): void {
+    const newLocalOverrides = { ...this.state.localOverrides };
+    delete newLocalOverrides[flagName];
+    this.update(() => {
+      return {
+        ...this.state,
+        localOverrides: newLocalOverrides,
+      };
+    });
+  }
+
+  /**
+   * Clears all local feature flag overrides.
+   */
+  clearAllFlagOverrides(): void {
+    this.update(() => {
+      return {
+        ...this.state,
+        localOverrides: {},
+      };
+    });
+  }
 }