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

**Requirements**

- [x] I have added test coverage for new or changed functionality
- [x] I have followed the repository's [pull request submission
guidelines](../blob/v9/CONTRIBUTING.md#submitting-pull-requests)
- [x] I have validated my changes against all supported platform
versions

**Related issues**

SDK-684

**Describe the solution you've provided**

Added prerequisites to flag model
Variation calls now recurse on prerequisites
Updated iOS FlagRequestTracker to use "first default wins" instead of
"last default wins" to be more consistent with other SDK
implementations. Also updated it to not serialize a null default.

Author: tanderson-ld

ContractTests/Source/Controllers/SdkController.swift

@@ -31,7 +31,8 @@ final class SdkController: RouteCollection {
             "anonymous-redaction",
             "evaluation-hooks",
             "event-gzip",
-            "optional-event-gzip"
+            "optional-event-gzip",
+            "client-prereq-events"
         ]
 
         return StatusResponse(

LaunchDarkly/GeneratedCode/mocks.generated.swift

@@ -214,12 +214,12 @@ final class EventReportingMock: EventReporting {
     }
 
     var recordFlagEvaluationEventsCallCount = 0
-    var recordFlagEvaluationEventsCallback: (() throws -> Void)?
+    var recordFlagEvaluationEventsCallback: ((_ event: FeatureEvent) throws -> Void)?
     var recordFlagEvaluationEventsReceivedArguments: (flagKey: LDFlagKey, value: LDValue, defaultValue: LDValue, featureFlag: FeatureFlag?, context: LDContext, includeReason: Bool)?
     func recordFlagEvaluationEvents(flagKey: LDFlagKey, value: LDValue, defaultValue: LDValue, featureFlag: FeatureFlag?, context: LDContext, includeReason: Bool) {
         recordFlagEvaluationEventsCallCount += 1
         recordFlagEvaluationEventsReceivedArguments = (flagKey: flagKey, value: value, defaultValue: defaultValue, featureFlag: featureFlag, context: context, includeReason: includeReason)
-        try! recordFlagEvaluationEventsCallback?()
+        try! recordFlagEvaluationEventsCallback?(FeatureEvent(key: flagKey, context: context, value: value, defaultValue: defaultValue, featureFlag: featureFlag, includeReason: includeReason, isDebug: false))
     }
 
     var flushCallCount = 0

LaunchDarkly/LaunchDarkly/LDClientVariation.swift

@@ -173,6 +173,11 @@ extension LDClient {
             var result: LDEvaluationDetail<T>
             let featureFlag = flagStore.featureFlag(for: flagKey)
             if let featureFlag = featureFlag {
+                featureFlag.prerequisites?.forEach{ prereqFlagKey in
+                    // recurse on prerequisites to emulate prereq evaluations occurring with desirable side effects such as events for prereqs
+                    _ = variationDetailInternal(prereqFlagKey, LDValue.null, needsReason: needsReason, methodName: methodName)
+                }
+                
                 if featureFlag.value == .null {
                     result = LDEvaluationDetail(value: defaultValue, variationIndex: featureFlag.variation, reason: featureFlag.reason)
                 } else {
@@ -188,6 +193,7 @@ extension LDClient {
                 os_log("%s Unknown feature flag %s; returning default value", log: config.logger, type: .debug, typeName(and: #function), flagKey.description)
                 result = LDEvaluationDetail(value: defaultValue, variationIndex: nil, reason: ["kind": "ERROR", "errorKind": "FLAG_NOT_FOUND"])
             }
+            
             eventReporter.recordFlagEvaluationEvents(flagKey: flagKey,
                                                      value: result.value.toLDValue(),
                                                      defaultValue: defaultValue.toLDValue(),

LaunchDarkly/LaunchDarkly/Models/FeatureFlag/FeatureFlag.swift

@@ -3,7 +3,7 @@ import Foundation
 struct FeatureFlag: Codable {
 
     enum CodingKeys: String, CodingKey, CaseIterable {
-        case flagKey = "key", value, variation, version, flagVersion, trackEvents, debugEventsUntilDate, reason, trackReason
+        case flagKey = "key", value, variation, version, flagVersion, trackEvents, debugEventsUntilDate, reason, trackReason, prerequisites
     }
 
     let flagKey: LDFlagKey
@@ -17,6 +17,7 @@ struct FeatureFlag: Codable {
     let debugEventsUntilDate: Date?
     let reason: [String: LDValue]?
     let trackReason: Bool
+    let prerequisites: [String]?
 
     var versionForEvents: Int? { flagVersion ?? version }
 
@@ -28,7 +29,8 @@ struct FeatureFlag: Codable {
          trackEvents: Bool = false,
          debugEventsUntilDate: Date? = nil,
          reason: [String: LDValue]? = nil,
-         trackReason: Bool = false) {
+         trackReason: Bool = false,
+         prerequisites: [String]? = nil) {
         self.flagKey = flagKey
         self.value = value
         self.variation = variation
@@ -38,6 +40,7 @@ struct FeatureFlag: Codable {
         self.debugEventsUntilDate = debugEventsUntilDate
         self.reason = reason
         self.trackReason = trackReason
+        self.prerequisites = prerequisites
     }
 
     init(from decoder: Decoder) throws {
@@ -61,6 +64,7 @@ struct FeatureFlag: Codable {
         self.debugEventsUntilDate = Date(millisSince1970: try container.decodeIfPresent(Int64.self, forKey: .debugEventsUntilDate))
         self.reason = try container.decodeIfPresent([String: LDValue].self, forKey: .reason)
         self.trackReason = (try container.decodeIfPresent(Bool.self, forKey: .trackReason)) ?? false
+        self.prerequisites = (try container.decodeIfPresent([String].self, forKey: .prerequisites))
     }
 
     func encode(to encoder: Encoder) throws {
@@ -76,6 +80,9 @@ struct FeatureFlag: Codable {
         }
         if reason != nil { try container.encode(reason, forKey: .reason) }
         if trackReason { try container.encode(true, forKey: .trackReason) }
+        if let prerequisites = prerequisites, !prerequisites.isEmpty {
+            try container.encodeIfPresent(prerequisites, forKey: .prerequisites)
+        }
     }
 
     func shouldCreateDebugEvents(lastEventReportResponseTime: Date?) -> Bool {

LaunchDarkly/LaunchDarkly/Models/FeatureFlag/FlagRequestTracker.swift

@@ -12,11 +12,11 @@ struct FlagRequestTracker {
 
     mutating func trackRequest(flagKey: LDFlagKey, reportedValue: LDValue, featureFlag: FeatureFlag?, defaultValue: LDValue, context: LDContext) {
         if flagCounters[flagKey] == nil {
-            flagCounters[flagKey] = FlagCounter()
+            flagCounters[flagKey] = FlagCounter(defaultValue: defaultValue)
         }
         guard let flagCounter = flagCounters[flagKey]
         else { return }
-        flagCounter.trackRequest(reportedValue: reportedValue, featureFlag: featureFlag, defaultValue: defaultValue, context: context)
+        flagCounter.trackRequest(reportedValue: reportedValue, featureFlag: featureFlag, context: context)
 
         os_log("%s \n\tflagKey: %s\n\treportedValue: %s\n\tvariation: %s\n\tversion: %s\n\tdefaultValue: %s", log: logger, type: .debug,
             typeName(and: #function),
@@ -41,12 +41,16 @@ final class FlagCounter: Encodable {
         case value, variation, version, unknown, count
     }
 
-    private(set) var defaultValue: LDValue = .null
+    private(set) var defaultValue: LDValue
     private(set) var flagValueCounters: [CounterKey: CounterValue] = [:]
     private(set) var contextKinds: Set<String> = Set()
-
-    func trackRequest(reportedValue: LDValue, featureFlag: FeatureFlag?, defaultValue: LDValue, context: LDContext) {
+    
+    init(defaultValue: LDValue) {
+        // default value follows a "first one wins" approach where the first evaluation for a flag key sets the default value for the summary events
         self.defaultValue = defaultValue
+    }
+
+    func trackRequest(reportedValue: LDValue, featureFlag: FeatureFlag?, context: LDContext) {
         let key = CounterKey(variation: featureFlag?.variation, version: featureFlag?.versionForEvents)
         if let counter = flagValueCounters[key] {
             counter.increment()
@@ -61,7 +65,9 @@ final class FlagCounter: Encodable {
 
     func encode(to encoder: Encoder) throws {
         var container = encoder.container(keyedBy: CodingKeys.self)
-        try container.encode(defaultValue, forKey: .defaultValue)
+        if defaultValue != .null {
+            try container.encode(defaultValue, forKey: .defaultValue)
+        }
         try container.encode(contextKinds, forKey: .contextKinds)
         var countersContainer = container.nestedUnkeyedContainer(forKey: .counters)
         try flagValueCounters.forEach { (key, value) in

LaunchDarkly/LaunchDarklyTests/LDClientSpec.swift

@@ -714,6 +714,32 @@ final class LDClientSpec: QuickSpec {
                     }
                 }
             }
+            context("flag store contains flags with prerequisites") {
+                it("records evaluation events for the prerequisites that exist") {
+                    let flagA = FeatureFlag(flagKey: "flagA", value: LDValue.bool(true), trackEvents: false, trackReason: false)
+                    let flagAB = FeatureFlag(flagKey: "flagAB", value: LDValue.bool(true), trackEvents: false, trackReason: false, prerequisites: ["flagA"])
+                    let flagAC = FeatureFlag(flagKey: "flagAC", value: LDValue.bool(true), trackEvents: false, trackReason: false, prerequisites: ["flagA"])
+                    let flagABD = FeatureFlag(flagKey: "flagABD", value: LDValue.bool(true), trackEvents: false, trackReason: false, prerequisites: ["flagAB"])
+                    let flags: [LDFlagKey: FeatureFlag] = ["flagA": flagA, "flagAB": flagAB, "flagAC": flagAC, "flagABD": flagABD]
+                    var storedItems = StoredItems(items: flags)
+                    testContext.flagStoreMock.replaceStore(newStoredItems: storedItems)
+                    var events = [FeatureEvent]()
+                    testContext.eventReporterMock.recordFlagEvaluationEventsCallback = { events.append($0) }
+                    _ = testContext.subject.boolVariation(forKey: "flagA", defaultValue: DefaultFlagValues.bool)
+                    _ = testContext.subject.boolVariation(forKey: "flagAB", defaultValue: DefaultFlagValues.bool)
+                    _ = testContext.subject.boolVariation(forKey: "flagAC", defaultValue: DefaultFlagValues.bool)
+                    _ = testContext.subject.boolVariation(forKey: "flagABD", defaultValue: DefaultFlagValues.bool)
+                    expect(events.count) == 8
+                    expect(events[0].key) == "flagA"
+                    expect(events[1].key) == "flagA"
+                    expect(events[2].key) == "flagAB"
+                    expect(events[3].key) == "flagA"
+                    expect(events[4].key) == "flagAC"
+                    expect(events[5].key) == "flagA"
+                    expect(events[6].key) == "flagAB"
+                    expect(events[7].key) == "flagABD"
+                }
+            }
         }
     }
 

LaunchDarkly/LaunchDarklyTests/Models/EventSpec.swift

@@ -219,9 +219,9 @@ final class EventSpec: XCTestCase {
             XCTAssertEqual(dict["endDate"], .number(Double(event.endDate.millisSince1970)))
             valueIsObject(dict["features"]) { features in
                 XCTAssertEqual(features.count, 1)
-                let counter = FlagCounter()
-                counter.trackRequest(reportedValue: false, featureFlag: flag, defaultValue: true, context: LDContext.stub())
-                counter.trackRequest(reportedValue: false, featureFlag: flag, defaultValue: true, context: LDContext.stub())
+                let counter = FlagCounter(defaultValue: true)
+                counter.trackRequest(reportedValue: false, featureFlag: flag, context: LDContext.stub())
+                counter.trackRequest(reportedValue: false, featureFlag: flag, context: LDContext.stub())
                 XCTAssertEqual(features["bool-flag"], encodeToLDValue(counter))
             }
         }