feat: Add FDv2 payload application via FlagManager.applyChanges (#299)

kinyoklion · web-flow · commit 66c255498f85 · 2026-06-11T14:00:47.000-07:00
## What this adds Two pieces the FDv2 data pipeline (a later PR) needs to apply payloads to the flag store correctly. Nothing produces FDv2 payloads for the flag manager yet, so behavior is unchanged. ### Envelope version is authoritative for flag-eval objects The flag-eval mapper now parses objects with the `put-object` envelope version substituted in, replacing any in-object value. The FDv2 wire format moved versioning onto the envelope; live service objects carry only `flagVersion`: ```json {"key":"greekTest","kind":"flag-eval","version":420, "object":{"flagVersion":7,"value":true,"variation":0,"trackEvents":false}} ``` The previous parse required an in-object `version`, which made every real payload fail with "FDv2 payload contained invalid data." The contract test harness includes an in-object version in its mock data, which is why the suites did not catch it; verified against the live service. This matches the JS implementation, which spreads the object over `version: update.version`. ### `FlagManager.applyChanges` Applies a changeset from an FDv2 payload, handling all three transfer types in one place — matching the JS implementation's `applyChanges(context, updates, type)` — plumbed through `FlagPersistence`/`FlagUpdater`: - **full** — replaces all stored flags. This delegates to the existing init path, so it keeps init's semantics: the context becomes the active context (as with an FDv1 put), changes are reported by diffing against the previous state (including deletions), and the cache is always written — replacing the stored flags with an empty set is a change. `environmentId` is applied on this path. - **partial** — applies the individual updates without per-item version comparison. FDv2 orders data at the payload level, so a lower envelope version must still apply — the existing `upsert` discards it as out-of-order, which is correct for FDv1 patches but wrong here (the harness's "ignores model version" test sends exactly this). Updates are context-checked like `upsert`, a single change event covers the affected keys, and an empty update set changes nothing and skips the cache write. - **none** — takes no action: no store mutation, no events, no cache write. The payload confirms the SDK is already up to date; freshness and status handling stay with the caller. Putting the type dispatch inside the flag manager (rather than having the data pipeline choose between `init` and a partial-only method) keeps the full/partial/none semantics in one self-documenting place and prevents a caller from applying a full payload through the merge path by mistake. ## Known pre-existing divergence, intentionally not addressed here Change detection (`FlagUpdater._hasChanged`) compares evaluation details by **value only** — `LDEvaluationDetail.==` ignores `variationIndex` and `reason` — so a variation- or reason-only change applies to the store without a `FlagsChangedEvent`, despite the event's documentation promising reason changes. This is shared behavior across `init`/`upsert`/`applyChanges` (the JS SDK compares the whole descriptor) and predates this PR; fixing it here would mix a behavior change into otherwise-inert plumbing, so it is left for a separate change. ## Testing Mapper tests pin the live wire shape (no in-object version parses; envelope version wins over a differing in-object value), alongside the existing put/delete/unknown-kind coverage. Flag updater tests cover partial transfers (no version comparison, a single change event for the changed keys, tombstones, rejection for an inactive context), full transfers (replacement with change events for the differences including deletions, making the context active, setting the environment ID), and a transfer of none leaving the store untouched and emitting nothing. Persistence-level tests assert a partial apply writes through to the cache, a rejected apply does not, an empty partial and a transfer of none skip the write, and a full transfer always writes — even an empty one. SDK-2186  --- > [!NOTE] > **Medium Risk** > Changes core flag-store update semantics for a new FDv2 path (no per-item version on partial applies, full replace behavior); production behavior is unchanged until callers wire it, but mistakes when integrating could cause stale or overwritten flags. > > **Overview** > Prepares the Dart common client for FDv2 by fixing **flag-eval** parsing and adding a single entry point to apply FDv2 changesets to the flag store (not wired from the data pipeline yet). > > **Flag-eval mapper:** When deserializing `flag-eval` objects, the put-object **envelope `version`** is merged into the JSON passed to `LDEvaluationResultSerialization.fromJson`, overriding any in-object `version`. That matches live FDv2 wire data where objects only carry `flagVersion`, which previously caused parse failures. > > **`FlagManager.applyChanges`:** New API plumbed through `FlagPersistence` and `FlagUpdater` for `PayloadType.full`, `partial`, and `none`. **Full** replaces all flags via the existing `init` path (active context, diff-based change events, optional `environmentId`, cache always written). **Partial** merges updates **without** per-item version checks (unlike `upsert`), rejects inactive contexts, batches change notifications, and skips cache when the update map is empty. **None** is a no-op (store, events, cache unchanged). > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 268c45b. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>
diff --git a/packages/common_client/lib/src/data_sources/fdv2/flag_eval_mapper.dart b/packages/common_client/lib/src/data_sources/fdv2/flag_eval_mapper.dart
@@ -22,15 +22,22 @@ Map<String, ItemDescriptor> mapUpdatesToItemDescriptors(List<Update> updates) {
       result[update.key] = ItemDescriptor(version: update.version);
     } else if (update.object case final object?) {
       try {
-        final evalResult = LDEvaluationResultSerialization.fromJson(object);
+        final evalResult = LDEvaluationResultSerialization.fromJson({
+          ...object,
+          // The envelope version is authoritative for FDv2 objects. The
+          // flag-eval object itself carries only flagVersion -- there is
+          // no in-object version on the wire -- so the envelope version
+          // becomes the result's version, replacing any present.
+          'version': update.version,
+        });
         result[update.key] = ItemDescriptor(
           version: update.version,
           flag: evalResult,
         );
       } catch (_) {
-        // Per spec 4.1.2.1: treat unparseable flag_eval as a data source
-        // error. Rethrow so the caller can discard the in-progress payload
-        // and reconnect.
+        // Treat an unparseable flag_eval as a data source error. Rethrow
+        // so the caller can discard the in-progress payload and
+        // reconnect.
         rethrow;
       }
     }
diff --git a/packages/common_client/lib/src/flag_manager/flag_manager.dart b/packages/common_client/lib/src/flag_manager/flag_manager.dart
@@ -1,5 +1,6 @@
 import 'package:launchdarkly_dart_common/launchdarkly_dart_common.dart';
 
+import '../data_sources/fdv2/payload.dart';
 import '../item_descriptor.dart';
 import 'flag_store.dart';
 import 'flag_persistence.dart';
@@ -55,6 +56,17 @@ final class FlagManager {
           LDContext context, String key, ItemDescriptor item) async =>
       _flagPersistence.upsert(context, key, item);
 
+  /// Applies a changeset from an FDv2 payload. A full transfer replaces all
+  /// stored flags, a partial transfer applies the individual updates without
+  /// per-item version comparison (FDv2 orders data at the payload level),
+  /// and a transfer of none takes no action. [environmentId] applies only
+  /// to full transfers.
+  Future<bool> applyChanges(LDContext context,
+          Map<String, ItemDescriptor> updates, PayloadType type,
+          {String? environmentId}) async =>
+      _flagPersistence.applyChanges(context, updates, type,
+          environmentId: environmentId);
+
   /// Asynchronously load cached values from persistence.
   Future<bool> loadCached(LDContext context) async {
     return _flagPersistence.loadCached(context);
diff --git a/packages/common_client/lib/src/flag_manager/flag_persistence.dart b/packages/common_client/lib/src/flag_manager/flag_persistence.dart
@@ -1,6 +1,7 @@
 import 'dart:convert';
 
 import 'package:launchdarkly_dart_common/launchdarkly_dart_common.dart';
+import '../data_sources/fdv2/payload.dart';
 import '../item_descriptor.dart';
 import '../persistence/persistence.dart';
 import 'context_index.dart';
@@ -63,6 +64,23 @@ final class FlagPersistence {
     return false;
   }
 
+  Future<bool> applyChanges(
+      LDContext context, Map<String, ItemDescriptor> updates, PayloadType type,
+      {String? environmentId}) async {
+    if (_updater.applyChanges(context, updates, type,
+        environmentId: environmentId)) {
+      // A transfer of none, or a partial transfer with no updates, changes
+      // nothing, so the cache write is skipped. A full transfer always
+      // writes; replacing the stored flags with an empty set is a change.
+      if (type == PayloadType.full ||
+          (type == PayloadType.partial && updates.isNotEmpty)) {
+        await _storeCache(context);
+      }
+      return true;
+    }
+    return false;
+  }
+
   Future<bool> loadCached(LDContext context) async {
     final json = await _persistence?.read(
         _environmentKey, encodePersistenceKey(context.canonicalKey));
diff --git a/packages/common_client/lib/src/flag_manager/flag_updater.dart b/packages/common_client/lib/src/flag_manager/flag_updater.dart
@@ -1,6 +1,7 @@
 import 'dart:async';
 
 import 'package:launchdarkly_dart_common/launchdarkly_dart_common.dart';
+import '../data_sources/fdv2/payload.dart';
 import '../item_descriptor.dart';
 import 'flag_store.dart';
 
@@ -101,6 +102,44 @@ final class FlagUpdater {
     return true;
   }
 
+  /// Applies a changeset from an FDv2 payload. A full transfer replaces all
+  /// stored flags, a partial transfer applies the individual updates, and a
+  /// transfer of none takes no action. FDv2 orders data at the payload
+  /// level, so unlike [upsert] there is no per-item version comparison.
+  ///
+  /// A full transfer makes [context] the active context; a partial transfer
+  /// is rejected when [context] is not the active context. [environmentId]
+  /// applies only to full transfers.
+  bool applyChanges(
+      LDContext context, Map<String, ItemDescriptor> updates, PayloadType type,
+      {String? environmentId}) {
+    switch (type) {
+      case PayloadType.full:
+        init(context, updates, environmentId: environmentId);
+        return true;
+      case PayloadType.partial:
+        if (_activeContextKey != context.canonicalKey) {
+          _logger.warn('Received an update for an inactive context.');
+          return false;
+        }
+
+        final changedKeys = <String>[];
+        for (final MapEntry(key: key, value: item) in updates.entries) {
+          if (_controller.hasListener &&
+              _hasChanged(key, _flagStore.get(key), item)) {
+            changedKeys.add(key);
+          }
+          _flagStore.insertOrUpdate(key, item);
+        }
+        if (changedKeys.isNotEmpty) {
+          _sendNotifications(changedKeys);
+        }
+        return true;
+      case PayloadType.none:
+        return true;
+    }
+  }
+
   void close() {
     _controller.close();
   }
diff --git a/packages/common_client/test/data_sources/fdv2/flag_eval_mapper_test.dart b/packages/common_client/test/data_sources/fdv2/flag_eval_mapper_test.dart
@@ -30,6 +30,53 @@ void main() {
           result['my-flag']!.flag!.detail.value, equals(LDValue.ofBool(true)));
     });
 
+    test(
+        'parses an object without an in-object version, using the envelope '
+        'version', () {
+      // The live service's flag-eval objects carry only flagVersion; the
+      // version lives on the put-object envelope.
+      final updates = [
+        Update(
+          kind: flagEvalKind,
+          key: 'my-flag',
+          version: 420,
+          object: {
+            'flagVersion': 7,
+            'value': true,
+            'variation': 0,
+            'trackEvents': false,
+          },
+        ),
+      ];
+
+      final result = mapUpdatesToItemDescriptors(updates);
+
+      expect(result['my-flag']!.version, equals(420));
+      expect(result['my-flag']!.flag!.version, equals(420));
+      expect(result['my-flag']!.flag!.flagVersion, equals(7));
+      expect(
+          result['my-flag']!.flag!.detail.value, equals(LDValue.ofBool(true)));
+    });
+
+    test('the envelope version replaces a differing in-object version', () {
+      final updates = [
+        Update(
+          kind: flagEvalKind,
+          key: 'my-flag',
+          version: 10,
+          object: {
+            'value': true,
+            'version': 3,
+            'variation': 0,
+          },
+        ),
+      ];
+
+      final result = mapUpdatesToItemDescriptors(updates);
+
+      expect(result['my-flag']!.flag!.version, equals(10));
+    });
+
     test('converts delete update to tombstone', () {
       final updates = [
         Update(
diff --git a/packages/common_client/test/flag_persistence_test.dart b/packages/common_client/test/flag_persistence_test.dart
@@ -1,6 +1,7 @@
 import 'dart:convert';
 
 import 'package:crypto/crypto.dart';
+import 'package:launchdarkly_common_client/src/data_sources/fdv2/payload.dart';
 import 'package:launchdarkly_common_client/src/flag_manager/flag_persistence.dart';
 import 'package:launchdarkly_common_client/src/flag_manager/flag_store.dart';
 import 'package:launchdarkly_common_client/src/flag_manager/flag_updater.dart';
@@ -31,6 +32,150 @@ void main() {
   };
 
   group('with persistence', () {
+    test('it stores cache on a partial applyChanges', () async {
+      final flagStore = FlagStore();
+      final mockPersistence = MockPersistence();
+      final flagPersistence = FlagPersistence(
+          persistence: mockPersistence,
+          updater: FlagUpdater(flagStore: flagStore, logger: logger),
+          store: flagStore,
+          sdkKey: sdkKey,
+          maxCachedContexts: 5,
+          logger: logger,
+          stamper: () => DateTime.fromMillisecondsSinceEpoch(0));
+
+      final context = LDContextBuilder().kind('user', 'user-key').build();
+      await flagPersistence.init(context, basicData);
+
+      final updated = LDEvaluationResult(
+          version: 3,
+          detail: LDEvaluationDetail(
+              LDValue.ofString('updated'), 0, LDEvaluationReason.off()));
+      expect(
+          await flagPersistence.applyChanges(
+              context,
+              {'flagA': ItemDescriptor(version: 3, flag: updated)},
+              PayloadType.partial),
+          true);
+
+      final contextPersistenceKey =
+          sha256.convert(utf8.encode(context.canonicalKey)).toString();
+      final cached =
+          mockPersistence.storage[sdkKeyPersistence]![contextPersistenceKey]!;
+      expect(cached, contains('updated'),
+          reason: 'a successful apply writes through to the cache');
+    });
+
+    test(
+        'it does not store cache for an inactive context on a partial '
+        'applyChanges', () async {
+      final flagStore = FlagStore();
+      final mockPersistence = MockPersistence();
+      final flagPersistence = FlagPersistence(
+          persistence: mockPersistence,
+          updater: FlagUpdater(flagStore: flagStore, logger: logger),
+          store: flagStore,
+          sdkKey: sdkKey,
+          maxCachedContexts: 5,
+          logger: logger,
+          stamper: () => DateTime.fromMillisecondsSinceEpoch(0));
+
+      final context = LDContextBuilder().kind('user', 'user-key').build();
+      final otherContext =
+          LDContextBuilder().kind('user', 'other-user-key').build();
+      await flagPersistence.init(context, basicData);
+
+      final updated = LDEvaluationResult(
+          version: 3,
+          detail: LDEvaluationDetail(
+              LDValue.ofString('updated'), 0, LDEvaluationReason.off()));
+      expect(
+          await flagPersistence.applyChanges(
+              otherContext,
+              {'flagA': ItemDescriptor(version: 3, flag: updated)},
+              PayloadType.partial),
+          false);
+
+      final otherPersistenceKey =
+          sha256.convert(utf8.encode(otherContext.canonicalKey)).toString();
+      expect(mockPersistence.storage[sdkKeyPersistence],
+          isNot(contains(otherPersistenceKey)),
+          reason: 'a rejected apply must not write the cache');
+    });
+
+    test('it skips the cache write for an empty partial applyChanges',
+        () async {
+      final flagStore = FlagStore();
+      final mockPersistence = MockPersistence();
+      final flagPersistence = FlagPersistence(
+          persistence: mockPersistence,
+          updater: FlagUpdater(flagStore: flagStore, logger: logger),
+          store: flagStore,
+          sdkKey: sdkKey,
+          maxCachedContexts: 5,
+          logger: logger,
+          stamper: () => DateTime.fromMillisecondsSinceEpoch(0));
+
+      final context = LDContextBuilder().kind('user', 'user-key').build();
+      await flagPersistence.init(context, basicData);
+      final writesAfterInit = mockPersistence.setCallCount;
+
+      expect(
+          await flagPersistence.applyChanges(context, {}, PayloadType.partial),
+          true);
+      expect(mockPersistence.setCallCount, writesAfterInit,
+          reason: 'an empty payload changes nothing');
+    });
+
+    test('it skips the cache write for an applyChanges of none', () async {
+      final flagStore = FlagStore();
+      final mockPersistence = MockPersistence();
+      final flagPersistence = FlagPersistence(
+          persistence: mockPersistence,
+          updater: FlagUpdater(flagStore: flagStore, logger: logger),
+          store: flagStore,
+          sdkKey: sdkKey,
+          maxCachedContexts: 5,
+          logger: logger,
+          stamper: () => DateTime.fromMillisecondsSinceEpoch(0));
+
+      final context = LDContextBuilder().kind('user', 'user-key').build();
+      await flagPersistence.init(context, basicData);
+      final writesAfterInit = mockPersistence.setCallCount;
+
+      expect(await flagPersistence.applyChanges(context, {}, PayloadType.none),
+          true);
+      expect(mockPersistence.setCallCount, writesAfterInit,
+          reason: 'a transfer of none changes nothing');
+    });
+
+    test('it stores cache for a full applyChanges, even an empty one',
+        () async {
+      final flagStore = FlagStore();
+      final mockPersistence = MockPersistence();
+      final flagPersistence = FlagPersistence(
+          persistence: mockPersistence,
+          updater: FlagUpdater(flagStore: flagStore, logger: logger),
+          store: flagStore,
+          sdkKey: sdkKey,
+          maxCachedContexts: 5,
+          logger: logger,
+          stamper: () => DateTime.fromMillisecondsSinceEpoch(0));
+
+      final context = LDContextBuilder().kind('user', 'user-key').build();
+      await flagPersistence.init(context, basicData);
+
+      expect(await flagPersistence.applyChanges(context, {}, PayloadType.full),
+          true);
+
+      final contextPersistenceKey =
+          sha256.convert(utf8.encode(context.canonicalKey)).toString();
+      final cached =
+          mockPersistence.storage[sdkKeyPersistence]![contextPersistenceKey]!;
+      expect(cached, '{}',
+          reason: 'replacing the stored flags with an empty set is a change '
+              'and must be persisted');
+    });
     test('it stores cache on init', () async {
       final flagStore = FlagStore();
       final mockPersistence = MockPersistence();
diff --git a/packages/common_client/test/flag_updater_test.dart b/packages/common_client/test/flag_updater_test.dart
diff --git a/packages/common_client/test/mock_persistence.dart b/packages/common_client/test/mock_persistence.dart
