feat: Adds support for client-side prerequisite events (#172)

**Requirements**

- [x] I have added test coverage for new or changed functionality

- [x] I have followed the repository's [pull request submission
guidelines](../blob/main/CONTRIBUTING.md#submitting-pull-requests)

- [ ] I have validated my changes against all supported platform
versions
Exception: Changes are not related to platforms.

**Related issues**

SDK-691

Author: tanderson-ld

apps/flutter_client_contract_test_service/bin/contract_test_service.dart

@@ -24,7 +24,8 @@ class TestApiImpl extends SdkTestApi {
     'client-independence',
     'context-comparison',
     'inline-context',
-    'anonymous-redaction'
+    'anonymous-redaction',
+    'client-prereq-events',
   ];
 
   static const clientUrlPrefix = '/client/';

packages/common/lib/src/events/default_event_processor.dart

@@ -50,7 +50,7 @@ final class DefaultEventProcessor implements EventProcessor {
 
   DefaultEventProcessor(
       {required LDLogger logger,
-      bool indexEvents = false,
+      required bool indexEvents,
       required int eventCapacity,
       required Duration flushInterval,
       required HttpClient client,

packages/common/lib/src/ld_evaluation_result.dart

@@ -18,6 +18,9 @@ final class LDEvaluationResult {
   /// True if a client SDK should track reasons for this flag.
   final bool trackReason;
 
+  /// List of prerequisite flags that were evaluated as part of determining this [LDEvaluationResult]
+  final List<String>? prerequisites;
+
   /// A millisecond timestamp, which if the current time is before, a client SDK
   /// should send debug events for the flag.
   final int? debugEventsUntilDate;
@@ -31,6 +34,7 @@ final class LDEvaluationResult {
       required this.detail,
       this.trackEvents = false,
       this.trackReason = false,
+      this.prerequisites,
       this.debugEventsUntilDate});
 
   @override

packages/common/lib/src/serialization/ld_evaluation_result_serialization.dart

@@ -6,6 +6,9 @@ final class LDEvaluationResultSerialization {
     final flagVersion = json['flagVersion'] as num?;
     final trackEvents = (json['trackEvents'] ?? false) as bool;
     final trackReason = (json['trackReason'] ?? false) as bool;
+    final prerequisites = (json['prerequisites'] as List<dynamic>?)
+        ?.map((e) => e as String)
+        .toList();
     final debugEventsUntilDateRaw = json['debugEventsUntilDate'] as num?;
     final value = LDValueSerialization.fromJson(json['value']);
     final jsonReason = json['reason'];
@@ -24,6 +27,7 @@ final class LDEvaluationResultSerialization {
         detail: LDEvaluationDetail(value, variationIndex, reason),
         trackEvents: trackEvents,
         trackReason: trackReason,
+        prerequisites: prerequisites,
         debugEventsUntilDate: debugEventsUntilDateRaw?.toInt());
   }
 
@@ -37,6 +41,9 @@ final class LDEvaluationResultSerialization {
     if (evaluationResult.trackReason) {
       result['trackReason'] = evaluationResult.trackReason;
     }
+    if (evaluationResult.prerequisites?.isNotEmpty ?? false) {
+      result['prerequisites'] = evaluationResult.prerequisites;
+    }
     if (evaluationResult.debugEventsUntilDate != null) {
       result['debugEventsUntilDate'] = evaluationResult.debugEventsUntilDate;
     }

packages/common/test/events/event_processor_test.dart

@@ -23,6 +23,7 @@ import '../logging_test.dart';
   return (
     DefaultEventProcessor(
         logger: LDLogger(adapter: adapter),
+        indexEvents: false,
         eventCapacity: 100,
         flushInterval: Duration(milliseconds: 100),
         client: client,
@@ -47,6 +48,7 @@ import '../logging_test.dart';
   return (
     DefaultEventProcessor(
         logger: LDLogger(adapter: adapter),
+        indexEvents: false,
         eventCapacity: 100,
         flushInterval: Duration(milliseconds: 100),
         client: client,

packages/common_client/lib/src/ld_common_client.dart

@@ -77,6 +77,48 @@ Map<ConnectionMode, DataSourceFactory> _defaultFactories(
   };
 }
 
+typedef EventProcessorFactory = EventProcessor Function(
+    {required LDLogger logger,
+    required bool indexEvents,
+    required int eventCapacity,
+    required Duration flushInterval,
+    required HttpClient client,
+    required String analyticsEventsPath,
+    required String diagnosticEventsPath,
+    required ServiceEndpoints endpoints,
+    required Duration diagnosticRecordingInterval,
+    required bool allAttributesPrivate,
+    required Set<AttributeReference> globalPrivateAttributes,
+    DiagnosticsManager? diagnosticsManager});
+
+EventProcessor _defaultEventProcessorFactory(
+    {required LDLogger logger,
+    required bool indexEvents,
+    required int eventCapacity,
+    required Duration flushInterval,
+    required HttpClient client,
+    required String analyticsEventsPath,
+    required String diagnosticEventsPath,
+    required ServiceEndpoints endpoints,
+    required Duration diagnosticRecordingInterval,
+    required bool allAttributesPrivate,
+    required Set<AttributeReference> globalPrivateAttributes,
+    DiagnosticsManager? diagnosticsManager}) {
+  return DefaultEventProcessor(
+      logger: logger,
+      indexEvents: indexEvents,
+      eventCapacity: eventCapacity,
+      flushInterval: flushInterval,
+      client: client,
+      analyticsEventsPath: analyticsEventsPath,
+      diagnosticEventsPath: diagnosticEventsPath,
+      diagnosticsManager: diagnosticsManager,
+      endpoints: endpoints,
+      allAttributesPrivate: allAttributesPrivate,
+      globalPrivateAttributes: globalPrivateAttributes,
+      diagnosticRecordingInterval: diagnosticRecordingInterval);
+}
+
 final class LDCommonClient {
   final LDCommonConfig _config;
   final Persistence _persistence;
@@ -96,6 +138,8 @@ final class LDCommonClient {
   // If there are cross-dependent modifiers, then this must be considered.
   late final List<ContextModifier> _modifiers;
 
+  final EventProcessorFactory _eventProcessorFactory;
+
   /// The event processor is not constructed during LDCommonClient construction
   /// because it requires the HTTP properties which must be determined
   /// asynchronously.
@@ -127,7 +171,8 @@ final class LDCommonClient {
 
   LDCommonClient(LDCommonConfig commonConfig, CommonPlatform platform,
       LDContext context, DiagnosticSdkData sdkData,
-      {DataSourceFactoriesFn? dataSourceFactories})
+      {DataSourceFactoriesFn? dataSourceFactories,
+      EventProcessorFactory? eventProcessorFactory})
       : _config = commonConfig,
         _platform = platform,
         _persistence = ValidatingPersistence(
@@ -143,6 +188,8 @@ final class LDCommonClient {
         _initialUndecoratedContext = context,
         // Data source factories is primarily a mechanism for testing.
         _dataSourceFactories = dataSourceFactories ?? _defaultFactories,
+        _eventProcessorFactory =
+            eventProcessorFactory ?? _defaultEventProcessorFactory,
         _sdkData = sdkData {
     final dataSourceEventHandler = DataSourceEventHandler(
         flagManager: _flagManager,
@@ -273,8 +320,9 @@ final class LDCommonClient {
       final osInfo = _envReport.osInfo;
       DiagnosticsManager? diagnosticsManager = _makeDiagnosticsManager(osInfo);
 
-      _eventProcessor = DefaultEventProcessor(
+      _eventProcessor = _eventProcessorFactory(
           logger: _logger,
+          indexEvents: false,
           eventCapacity: _config.events.eventCapacity,
           flushInterval: _config.events.flushInterval,
           client: HttpClient(httpProperties: httpProperties),
@@ -528,6 +576,10 @@ final class LDCommonClient {
     LDEvaluationDetail<LDValue> detail;
 
     if (evalResult != null && evalResult.flag != null) {
+      evalResult.flag?.prerequisites?.forEach((prereq) {
+        _variationInternal(prereq, LDValue.ofNull(), isDetailed: isDetailed);
+      });
+
       if (type == null || type == evalResult.flag!.detail.value.type) {
         detail = evalResult.flag!.detail;
       } else {

packages/common_client/test/ld_dart_client_test.dart

@@ -6,6 +6,7 @@ import 'package:launchdarkly_common_client/launchdarkly_common_client.dart';
 import 'package:launchdarkly_common_client/src/data_sources/data_source.dart';
 import 'package:test/test.dart';
 
+import 'mock_eventprocessor.dart';
 import 'mock_persistence.dart';
 
 final class TestConfig extends LDCommonConfig {
@@ -284,4 +285,66 @@ void main() {
       expect(res, 'datasource');
     });
   });
+
+  group('given mock flag data with prerequisites', () {
+    late LDCommonClient client;
+    late MockPersistence mockPersistence;
+    late MockEventProcessor mockEventProcessor;
+    final sdkKey = 'the-sdk-key';
+    final sdkKeyPersistence =
+        'LaunchDarkly_${sha256.convert(utf8.encode(sdkKey))}';
+
+    setUp(() {
+      mockPersistence = MockPersistence();
+      mockEventProcessor = MockEventProcessor();
+      client = LDCommonClient(
+        TestConfig(sdkKey, AutoEnvAttributes.disabled),
+        CommonPlatform(persistence: mockPersistence),
+        LDContextBuilder().kind('user', 'bob').build(),
+        DiagnosticSdkData(name: '', version: ''),
+        dataSourceFactories: (LDCommonConfig config, LDLogger logger,
+            HttpProperties properties) {
+          return {
+            ConnectionMode.streaming: (LDContext context) {
+              return TestDataSource();
+            },
+            ConnectionMode.polling: (LDContext context) {
+              return TestDataSource();
+            },
+          };
+        },
+        eventProcessorFactory: (
+                {required allAttributesPrivate,
+                required analyticsEventsPath,
+                required client,
+                required diagnosticEventsPath,
+                required diagnosticRecordingInterval,
+                diagnosticsManager,
+                required endpoints,
+                required eventCapacity,
+                required flushInterval,
+                required globalPrivateAttributes,
+                required indexEvents,
+                required logger}) =>
+            mockEventProcessor,
+      );
+    });
+
+    test('it reports events for each prerequisite', () async {
+      final contextPersistenceKey =
+          sha256.convert(utf8.encode('bob')).toString();
+      mockPersistence.storage[sdkKeyPersistence] = {
+        contextPersistenceKey:
+            '{"flagA":{"version":1,"value":"storage","variation":0,"reason":{"kind":"OFF"},"prerequisites":["flagAB"]},"flagAB":{"version":1,"value":"storage","variation":0,"reason":{"kind":"OFF"}}}'
+      };
+
+      await client
+          .start(); // note no call to wait for network results here so we get the storage values
+      final res = client.stringVariation('flagA', 'default');
+      expect(res, 'storage');
+      expect(mockEventProcessor.evalEvents.length, 2);
+      expect(mockEventProcessor.evalEvents[0].flagKey, 'flagAB');
+      expect(mockEventProcessor.evalEvents[1].flagKey, 'flagA');
+    });
+  });
 }

packages/common_client/test/mock_eventprocessor.dart

@@ -0,0 +1,37 @@
+import 'package:launchdarkly_dart_common/launchdarkly_dart_common.dart';
+
+final class MockEventProcessor implements EventProcessor {
+  final customEvents = <CustomEvent>[];
+  final evalEvents = <EvalEvent>[];
+  final identifyEvents = <IdentifyEvent>[];
+
+  @override
+  Future<void> flush() async {
+    // no-op in this mock
+  }
+
+  @override
+  void processCustomEvent(CustomEvent event) {
+    customEvents.add(event);
+  }
+
+  @override
+  void processEvalEvent(EvalEvent event) {
+    evalEvents.add(event);
+  }
+
+  @override
+  void processIdentifyEvent(IdentifyEvent event) {
+    identifyEvents.add(event);
+  }
+
+  @override
+  void start() {
+    // no-op in this mock
+  }
+
+  @override
+  void stop() {
+    // no-op in this mock
+  }
+}