feat: add override functionality to remote feature flags

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

@@ -7,6 +7,26 @@ 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
+  - `clearFlagOverride(flagName)` - Clear the local override for a specific feature flag
+  - `clearAllOverrides()` - 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 arrays that were processed from arrays to single value
+- Export additional controller action types ([#7271](https://github.com/MetaMask/core/pull/7271))
+  - `RemoteFeatureFlagControllerSetFlagOverrideAction`
+  - `RemoteFeatureFlagControllerClearFlagOverrideAction`
+  - `RemoteFeatureFlagControllerClearAllOverridesAction`
+
+### Changed
+
+- Enhanced feature flag processing to preserve raw A/B test arrays for visibility and override capabilities ([#7271](https://github.com/MetaMask/core/pull/7271))
+- Local overrides now take precedence over remote feature flags when both exist ([#7271](https://github.com/MetaMask/core/pull/7271))
+- 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,
+  RemoteFeatureFlagControllerClearFlagOverrideAction,
+  RemoteFeatureFlagControllerClearAllOverridesAction,
   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,154 @@ 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('clearFlagOverride', () => {
+      it('removes a specific override', () => {
+        const controller = createController();
+
+        controller.setFlagOverride('flag1', 'value1');
+        controller.setFlagOverride('flag2', 'value2');
+        controller.clearFlagOverride('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.clearFlagOverride('nonExistentFlag');
+
+        expect(controller.state.localOverrides).toStrictEqual({
+          flag1: 'value1',
+        });
+      });
+    });
+
+    describe('clearAllOverrides', () => {
+      it('removes all overrides', () => {
+        const controller = createController();
+
+        controller.setFlagOverride('flag1', 'value1');
+        controller.setFlagOverride('flag2', 'value2');
+        controller.clearAllOverrides();
+
+        expect(controller.state.localOverrides).toStrictEqual({});
+      });
+
+      it('does not affect state when no overrides exist', () => {
+        const controller = createController();
+
+        controller.clearAllOverrides();
+
+        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 override before fetching remote flags
+        controller.setFlagOverride('overrideFlag', 'overrideValue');
+
+        await controller.updateRemoteFeatureFlags();
+
+        // Mock different remote response for second fetch
+        jest
+          .spyOn(clientConfigApiService, 'fetchRemoteFeatureFlags')
+          .mockResolvedValueOnce({
+            remoteFeatureFlags: { remoteFlag: 'updatedRemoteValue' },
+            cacheTimestamp: Date.now(),
+          });
+
+        // Force cache expiration and update
+        jest
+          .spyOn(Date, 'now')
+          .mockReturnValue(Date.now() + DEFAULT_CACHE_DURATION + 1000);
+        await controller.updateRemoteFeatureFlags();
+
+        // Overrides should be preserved
+        expect(controller.state.localOverrides).toStrictEqual({
+          overrideFlag: 'overrideValue',
+        });
+
+        // Remote flags should be updated
+        expect(controller.state.remoteFeatureFlags).toStrictEqual({
+          remoteFlag: 'updatedRemoteValue',
+        });
+      });
+
+      it('overrides work with threshold-based feature flags', async () => {
+        const clientConfigApiService = buildClientConfigApiService({
+          remoteFeatureFlags: MOCK_FLAGS_WITH_THRESHOLD,
+        });
+        const controller = createController({
+          clientConfigApiService,
+          getMetaMetricsId: () => MOCK_METRICS_ID,
+        });
+
+        await controller.updateRemoteFeatureFlags();
+
+        // Override the threshold flag
+        controller.setFlagOverride('testFlagForThreshold', 'overriddenValue');
+
+        // Access flag value with override taking precedence
+        const flagValue =
+          controller.state.localOverrides.testFlagForThreshold ??
+          controller.state.remoteFeatureFlags.testFlagForThreshold;
+        expect(flagValue).toBe('overriddenValue');
+      });
+    });
+  });
+
   describe('metadata', () => {
     it('includes expected state in debug snapshots', () => {
       const controller = createController();
@@ -658,6 +806,8 @@ describe('RemoteFeatureFlagController', () => {
       ).toMatchInlineSnapshot(`
         Object {
           "cacheTimestamp": 0,
+          "localOverrides": Object {},
+          "rawRemoteFeatureFlags": Object {},
           "remoteFeatureFlags": Object {},
         }
       `);
@@ -675,6 +825,8 @@ describe('RemoteFeatureFlagController', () => {
       ).toMatchInlineSnapshot(`
         Object {
           "cacheTimestamp": 0,
+          "localOverrides": Object {},
+          "rawRemoteFeatureFlags": Object {},
           "remoteFeatureFlags": Object {},
         }
       `);
@@ -692,6 +844,8 @@ describe('RemoteFeatureFlagController', () => {
       ).toMatchInlineSnapshot(`
         Object {
           "cacheTimestamp": 0,
+          "localOverrides": Object {},
+          "rawRemoteFeatureFlags": Object {},
           "remoteFeatureFlags": Object {},
         }
       `);
@@ -708,6 +862,7 @@ describe('RemoteFeatureFlagController', () => {
         ),
       ).toMatchInlineSnapshot(`
         Object {
+          "localOverrides": Object {},
           "remoteFeatureFlags": Object {},
         }
       `);