fix: RemoteFeatureFlagController client version change cache invalidation by Prithpal-Sooriya · Pull Request #7827 · MetaMask/core

Prithpal-Sooriya · 2026-02-03T22:18:39Z

Explanation

What is the current state of things and why does it need to change?
The RemoteFeatureFlagController did not invalidate its cache when the client application version changed. This could lead to users receiving stale feature flags after an application upgrade, as the controller would continue to use cached flags from the previous version. This is detailed in [Bug]: Explore feature is not available when upgrading from 7.62.2/7.63.0 to 7.64.0 metamask-mobile#25474.
What is the solution your changes offer and how does it work?
This PR introduces a previousClientVersion property to the controller's persisted state. On initialization, the controller compares the current clientVersion (passed in the constructor) with the stored previousClientVersion. If these versions differ (or if previousClientVersion is invalid/missing), the cache is invalidated, forcing a fresh fetch of feature flags. The previousClientVersion is then updated to the current clientVersion in the state.
Are there any changes whose purpose might not obvious to those unfamiliar with the domain?
No.

References

Fixes [Bug]: Explore feature is not available when upgrading from 7.62.2/7.63.0 to 7.64.0 metamask-mobile#25474

Checklist

I've updated the test suite for new or updated code as appropriate
I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
I've communicated my changes to consumers by updating changelogs for packages I've changed
I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

Note

Medium Risk
Changes cache-invalidation behavior in RemoteFeatureFlagController based on app version, which can increase fetches or alter which flags users receive immediately after upgrades. Risk is limited to this controller’s initialization path and is covered by new unit tests.

Overview
Remote feature flag caching now invalidates on app upgrades. RemoteFeatureFlagController accepts an optional prevClientVersion and resets cacheTimestamp to 0 when it differs from the current clientVersion, forcing a fresh fetch instead of using potentially stale cached flags.

Adds unit coverage for the version-change scenario and documents the fix in CHANGELOG.md.

^{Written by Cursor Bugbot for commit 6dfa4ae. This will update automatically on new commits. Configure here.}

Co-authored-by: prithpal.sooriya <[email protected]>

cursor · 2026-02-03T22:18:40Z

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

Co-authored-by: prithpal.sooriya <[email protected]>

sahar-fehri

LGTM

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

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

DDDDDanica · 2026-02-04T13:10:09Z

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

+       * @param opts - The options for the arrangeActAssertClientVersionChange test
+       * @param opts.clientVersion - The client version to use
+       * @param opts.controllerState - The controller state to use
+       * @param opts.expectedFeatureFlagState - The expected feature flag state\


Minor typo

Suggested change

* @param opts.expectedFeatureFlagState - The expected feature flag state\

* @param opts.expectedFeatureFlagState - The expected feature flag state

Thanks, resolved in daa2655

DDDDDanica · 2026-02-04T13:11:01Z

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

+        ).toStrictEqual({
+          enabled: expectedFeatureFlagState,
+        });
+


Nit: we could assert cachedTimestamp also here expect(controller.state.cacheTimestamp).toBe(0);

Good callout, added this additional assertion in daa2655

- clean up jsdoc comments - add additional assertion that cache is set.

Gudahtt · 2026-02-04T17:27:18Z

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

    localOverrides: {},
    rawRemoteFeatureFlags: {},
    cacheTimestamp: 0,
+    previousClientVersion: undefined,


This should be causing a type error 🤔 undefined is strictly disallowed in controller state, we only allow JSON.

Oh wow interesting! Thanks for tagging, will clean up!

Gudahtt · 2026-02-04T17:28:05Z

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

    includeInDebugSnapshot: false,
    usedInUi: false,
  },
+  previousClientVersion: {


I'm not sure that we need an extra copy of this, we already have it in the AppMetadataController. Maybe we could get it from there instead?

Hmm good callout!

Wondering if there is a controller race condition action issue?

making this.messenger.call() inside the constructor.

if the AppMetadataController version updates on initialisation before we can grab the previous version number

Will do some testing!

It wouldn't be a race condition, but it would mean we'd strictly need to construct the AppMetadataController before this one. We try to avoid using actions/events in the constructor for this exact reason, to avoid initialization order requirements.

Could we fetch the AppMetadataController state lazily instead, rather than in the constructor? That would avoid any init order issues.

Prithpal-Sooriya · 2026-02-04T18:57:16Z

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

    disabled = false,
    getMetaMetricsId,
    clientVersion,
+    prevClientVersion,


Now stateless. We can pass in the constructor parameter for the previous version.

Example on clients:

// the persisted current app ver is the new prevClientVersion we will pass into the `RemoteFeatureFlagController`. const prevClientVersion = persistedState.AppMetadataController?.currentAppVersion;

I'll spin up preview builds on mobile and extension to validate.

…ersion - Introduced optional prevClientVersion to manage feature flag cache invalidation. - Updated JSDoc comments for clarity on new parameter usage.

Invalidate feature flag cache on version change

4d10ee5

Co-authored-by: prithpal.sooriya <[email protected]>

cursoragent and others added 3 commits February 3, 2026 22:23

Add changelog for client version cache invalidation

312609f

Co-authored-by: prithpal.sooriya <[email protected]>

Fix SemVerVersion typing in cache invalidation test

9f93669

Co-authored-by: prithpal.sooriya <[email protected]>

refactor: clean up tests and resolve linting issues

016bbe9

Prithpal-Sooriya force-pushed the cursor/client-version-cache-invalidation-4c09 branch from c1f8201 to 016bbe9 Compare February 4, 2026 11:59

Prithpal-Sooriya marked this pull request as ready for review February 4, 2026 12:04

Prithpal-Sooriya requested review from a team as code owners February 4, 2026 12:04

Prithpal-Sooriya changed the title ~~Client version cache invalidation~~ fix: RemoteFeatureFlagController client version change cache invalidation Feb 4, 2026

sahar-fehri previously approved these changes Feb 4, 2026

View reviewed changes

cursor bot reviewed Feb 4, 2026

View reviewed changes

packages/remote-feature-flag-controller/src/remote-feature-flag-controller.ts Outdated Show resolved Hide resolved

DDDDDanica reviewed Feb 4, 2026

View reviewed changes

test: update tests from requested changes

daa2655

- clean up jsdoc comments - add additional assertion that cache is set.

Prithpal-Sooriya dismissed sahar-fehri’s stale review via daa2655 February 4, 2026 13:44

Gudahtt reviewed Feb 4, 2026

View reviewed changes

Prithpal-Sooriya commented Feb 4, 2026

View reviewed changes

refactor: update RemoteFeatureFlagController to pass in a prevClientV…

6dfa4ae

…ersion - Introduced optional prevClientVersion to manage feature flag cache invalidation. - Updated JSDoc comments for clarity on new parameter usage.

Prithpal-Sooriya force-pushed the cursor/client-version-cache-invalidation-4c09 branch from a4e549b to 6dfa4ae Compare February 4, 2026 19:00

	* @param opts.expectedFeatureFlagState - The expected feature flag state\
	* @param opts.expectedFeatureFlagState - The expected feature flag state

Uh oh!

Conversation

Prithpal-Sooriya commented Feb 3, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Explanation

References

Checklist

Uh oh!

cursor bot commented Feb 3, 2026

Uh oh!

sahar-fehri left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Prithpal-Sooriya commented Feb 3, 2026 •

edited by cursor bot

Loading