Merge pull request #101 from unsignedapps/diagnostics

Added diagnostics for flag resolution and real-time updates

Author: bok-

.swiftlint.yml

@@ -6,6 +6,7 @@ disabled_rules:
   - type_name
   - vertical_whitespace
   - identifier_name
+  - let_var_whitespace
 
 opt_in_rules:
   - anyobject_protocol
@@ -67,6 +68,10 @@ line_length:
   ignores_function_declarations: true
   warning: 180
 
+file_length:
+  warning: 800
+  error: 1500
+
 identifier_name:
   excluded: [id, x, y, z, r, g, b, a, i, j, k, cx, cy, dx, dy, _rootGroup]
 

Sources/Vexil/Diagnostics.swift

@@ -0,0 +1,93 @@
+//
+//  Diagnostics.swift
+//  Vexil
+//
+//  Created by Rob Amos on 12/12/21.
+//
+
+import Foundation
+
+/// A diagnostic that is returned by `FlagPole.makeDiagnostics()`
+///
+public enum FlagPoleDiagnostic: Equatable {
+
+    // MARK: - Cases
+
+    case currentValue(key: String, value: BoxedFlagValue, resolvedBy: String?)
+    case changedValue(key: String, value: BoxedFlagValue, resolvedBy: String?, changedBy: String?)
+
+}
+
+
+// MARK: - Initialisation
+
+extension Array where Element == FlagPoleDiagnostic {
+
+    /// Creates diagnostic cases from an initial snapshot
+    init<Root> (current: Snapshot<Root>) where Root: FlagContainer {
+        self = current.values
+            .sorted(by: { $0.key < $1.key })
+            .compactMap { element -> FlagPoleDiagnostic? in
+                guard let value = element.value.boxed else {
+                    return nil
+                }
+                return .currentValue(key: element.key, value: value, resolvedBy: element.value.source)
+            }
+
+    }
+
+    /// Creates diagnostic cases from a changed snapshot
+    init<Root> (changed: Snapshot<Root>, sources: [String]?) where Root: FlagContainer {
+        let changedBy: String?
+        if let sources = sources {
+            changedBy = Set(sources).sorted().joined(separator: ", ")
+        } else {
+            changedBy = nil
+        }
+
+        self = changed.values
+            .sorted(by: { $0.key < $1.key })
+            .compactMap { element -> FlagPoleDiagnostic? in
+                guard let value = element.value.boxed else {
+                    return nil
+                }
+                return .changedValue(key: element.key, value: value, resolvedBy: element.value.source, changedBy: changedBy)
+            }
+
+    }
+
+}
+
+
+// MARK: - Debugging
+
+extension FlagPoleDiagnostic: CustomDebugStringConvertible {
+
+    public var debugDescription: String {
+        switch self {
+        case let .currentValue(key: key, value: value, resolvedBy: source):
+            return "Current value of flag '\(key)' is '\(String(describing: value))'. Resolved by: \(source ?? "Default value")"
+        case let .changedValue(key: key, value: value, resolvedBy: source, changedBy: trigger):
+            return "Value of flag '\(key)' was changed to '\(String(describing: value))' by '\(trigger ?? "an unknown source")'. Resolved by: \(source ?? "Default value")"
+        }
+    }
+
+}
+
+
+// MARK: - Errors
+
+public extension FlagPoleDiagnostic {
+
+    enum Error: LocalizedError {
+        case notEnabledForSnapshot
+
+        public var errorDescription: String? {
+            switch self {
+            case .notEnabledForSnapshot:
+                return "This snapshot was not taken with diagnostics enabled. Take it again using `FlagPole.snapshot(enableDiagnostics: true)`"
+            }
+        }
+    }
+
+}

Sources/Vexil/Flag.swift

@@ -42,7 +42,7 @@ public struct Flag<Value>: Decorated, Identifiable where Value: FlagValue {
 
     /// The `Flag` value. This is a calculated property based on the `FlagPole`s sources.
     public var wrappedValue: Value {
-        return value(in: nil) ?? self.defaultValue
+        return value(in: nil)?.value ?? self.defaultValue
     }
 
     /// The string-based Key for this `Flag`, as calculated during `init`. This key is
@@ -149,17 +149,19 @@ public struct Flag<Value>: Decorated, Identifiable where Value: FlagValue {
 
     // MARK: - Lookup Support
 
-    func value (in source: FlagValueSource?) -> Value? {
-        guard let lookup = self.decorator.lookup, let key = self.decorator.key else { return self.defaultValue }
-        let value: Value? = lookup.lookup(key: key, in: source)
+    func value (in source: FlagValueSource?) -> LookupResult<Value>? {
+        guard let lookup = self.decorator.lookup, let key = self.decorator.key else {
+            return LookupResult(source: nil, value: self.defaultValue)
+        }
+        let value: LookupResult<Value>? = lookup.lookup(key: key, in: source)
 
         // if we're looking up against a specific source we return only what we get from it
         if source != nil {
             return value
         }
 
         // otherwise we're looking up on the FlagPole - which must always return a value so go back to our default
-        return value ?? self.defaultValue
+        return value ?? LookupResult(source: nil, value: self.defaultValue)
     }
 
 }

Sources/Vexil/Lookup.swift

@@ -18,13 +18,19 @@ import Foundation
 /// Only `FlagPole` and `Snapshot`s conform to this.
 ///
 internal protocol Lookup: AnyObject {
-    func lookup<Value> (key: String, in source: FlagValueSource?) -> Value? where Value: FlagValue
+    func lookup<Value> (key: String, in source: FlagValueSource?) -> LookupResult<Value>? where Value: FlagValue
 
     #if !os(Linux)
     func publisher<Value> (key: String) -> AnyPublisher<Value, Never> where Value: FlagValue
     #endif
 }
 
+/// A lightweight internal type used to support diagnostics by tagging the values with the source that resolved it
+struct LookupResult<Value> where Value: FlagValue {
+    let source: String?
+    let value: Value
+}
+
 extension FlagPole: Lookup {
 
     /// This is the primary lookup function in a `FlagPole`. When you access the `Flag.wrappedValue`
@@ -33,14 +39,15 @@ extension FlagPole: Lookup {
     /// It iterates through our `FlagValueSource`s and asks each if they have a `FlagValue` for
     /// that key, returning the first non-nil value it finds.
     ///
-    func lookup<Value> (key: String, in source: FlagValueSource?) -> Value? where Value: FlagValue {
+    func lookup<Value> (key: String, in source: FlagValueSource?) -> LookupResult<Value>? where Value: FlagValue {
         if let source = source {
             return source.flagValue(key: key)
+                .map { LookupResult(source: source.name, value: $0) }
         }
 
         for source in self._sources {
             if let value: Value = source.flagValue(key: key) {
-                return value
+                return LookupResult(source: source.name, value: value)
             }
         }
         return nil

Sources/Vexil/Pole.swift

@@ -59,7 +59,14 @@ public class FlagPole<RootGroup> where RootGroup: FlagContainer {
             #if !os(Linux)
 
             if #available(OSX 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *) {
-                self.setupSnapshotPublishing(keys: self.allFlagKeys, sendImmediately: true)
+                let oldSourceNames = oldValue.map(\.name)
+                let newSourceNames = _sources.map(\.name)
+
+                self.setupSnapshotPublishing(
+                    keys: self.allFlagKeys,
+                    sendImmediately: true,
+                    changedSources: oldSourceNames.difference(from: newSourceNames).map(\.element)
+                )
             }
 
             #endif
@@ -159,7 +166,7 @@ public class FlagPole<RootGroup> where RootGroup: FlagContainer {
 
     // MARK: - Real Time Changes
 
-    #if !os(Linux)
+#if !os(Linux)
 
     /// An internal state variable used so we don't setup the `Publisher` infrastructure
     /// until someone has accessed `self.publisher`
@@ -179,44 +186,106 @@ public class FlagPole<RootGroup> where RootGroup: FlagContainer {
         let snapshot = self.latestSnapshot
         if self.shouldSetupSnapshotPublishing == false {
             self.shouldSetupSnapshotPublishing = true
-            self.setupSnapshotPublishing(keys: self.allFlagKeys, sendImmediately: true)
+            self.setupSnapshotPublishing(keys: self.allFlagKeys, sendImmediately: false)
         }
         return snapshot.eraseToAnyPublisher()
     }
 
     private lazy var cancellables = Set<AnyCancellable>()
 
-    private func setupSnapshotPublishing (keys: Set<String>, sendImmediately: Bool) {
+    private func setupSnapshotPublishing (keys: Set<String>, sendImmediately: Bool, changedSources: [String]? = nil) {
         guard self.shouldSetupSnapshotPublishing else { return }
 
         // cancel our existing one
         self.cancellables.forEach { $0.cancel() }
         self.cancellables.removeAll()
 
         let upstream = self._sources
-            .compactMap { source in
-                source.valuesDidChange(keys: keys)
+            .compactMap { source -> AnyPublisher<(String, Set<String>), Never>? in
+                let maybePublisher = source.valuesDidChange(keys: keys)
                     ?? source.valuesDidChange?.map({ _ in [] }).eraseToAnyPublisher()   // backwards compatibility
+
+                guard let publisher = maybePublisher else {
+                    return nil
+                }
+
+                let name = source.name
+                return publisher
+                    .map { (name, $0) }
+                    .eraseToAnyPublisher()
             }
 
         Publishers.MergeMany(upstream)
-            .sink { [weak self] keys in
+            .sink { [weak self] source, keys in
                 guard let self = self else { return }
 
                 let snapshot = Snapshot(flagPole: self, snapshot: self.latestSnapshot.value)
-                let changed = Snapshot(flagPole: self, copyingFlagValuesFrom: .pole, keys: keys.isEmpty == true ? nil : keys)
+                let changed = Snapshot(flagPole: self, copyingFlagValuesFrom: .pole, keys: keys.isEmpty == true ? nil : keys, diagnosticsEnabled: self._diagnosticsEnabled)
                 snapshot.merge(changed)
-
                 self.latestSnapshot.send(snapshot)
+
+                if self._diagnosticsEnabled == true {
+                    self.diagnosticSubject.send(.init(changed: changed, sources: [source]))
+                }
             }
             .store(in: &self.cancellables)
 
         if sendImmediately {
-            self.latestSnapshot.send(self.snapshot())
+            let snapshot = self.snapshot()
+            self.latestSnapshot.send(snapshot)
+            if self._diagnosticsEnabled == true {
+                self.diagnosticSubject.send(.init(changed: snapshot, sources: changedSources))
+            }
+        }
+    }
+
+#endif // !os(Linux)
+
+    // MARK: - Diagnostics
+
+    var _diagnosticsEnabled = false
+
+    /// Returns the current diagnostic state of all flags managed by this FlagPole.
+    ///
+    /// This method is intended to be called from the debugger
+    ///
+    public func makeDiagnostics () -> [FlagPoleDiagnostic] {
+        return .init(current: self.snapshot(enableDiagnostics: true))
+    }
+
+#if !os(Linux)
+
+    private lazy var diagnosticSubject = PassthroughSubject<[FlagPoleDiagnostic], Never>()
+
+    /// A `Publisher` that can be used to monitor diagnostic outputs
+    ///
+    /// An array of `Diagnostic` messages is emitted every time a flag value changes. It can be one of two types:
+    ///
+    ///  - The value of every flag on the `FlagPole` at the time of subscribing, and which `FlagValueSource` it was resolved by
+    ///  - An array of the flag values that were changed, which `FlagValueSource` they were changed by, and their resolved value/source
+    ///
+    public func makeDiagnosticsPublisher () -> AnyPublisher<[FlagPoleDiagnostic], Never> {
+        let wasAlreadyEnabled = _diagnosticsEnabled
+        _diagnosticsEnabled = true
+
+        let snapshot = self.latestSnapshot.value
+
+        // if publishing hasn't been started yet (ie they've accessed `_diagnosticsPublisher` before `publisher`)
+        if self.shouldSetupSnapshotPublishing == false {
+            self.shouldSetupSnapshotPublishing = true
+            self.setupSnapshotPublishing(keys: self.allFlagKeys, sendImmediately: false)
+
+        // if publishing has already been started, but diagnostics were not previously enabled, we setup again to make sure they are available
+        } else if wasAlreadyEnabled == false {
+            self.setupSnapshotPublishing(keys: self.allFlagKeys, sendImmediately: true)
         }
+
+        return diagnosticSubject
+            .prepend(.init(current: snapshot))
+            .eraseToAnyPublisher()
     }
 
-    #endif
+#endif // !os(Linux)
 
 
     // MARK: - Snapshots
@@ -229,10 +298,11 @@ public class FlagPole<RootGroup> where RootGroup: FlagContainer {
     ///                     or nil then the values of each `Flag` within the `FlagPole` is copied
     ///                     into the snapshot instead.
     ///
-    public func snapshot (of source: FlagValueSource? = nil) -> Snapshot<RootGroup> {
+    public func snapshot (of source: FlagValueSource? = nil, enableDiagnostics: Bool = false) -> Snapshot<RootGroup> {
         return Snapshot (
             flagPole: self,
-            copyingFlagValuesFrom: source.flatMap(Snapshot.Source.source) ?? .pole
+            copyingFlagValuesFrom: source.flatMap(Snapshot.Source.source) ?? .pole,
+            diagnosticsEnabled: enableDiagnostics || self._diagnosticsEnabled
         )
     }
 

Sources/Vexil/Snapshots/AnyFlag.swift

@@ -8,17 +8,16 @@
 protocol AnyFlag {
     var key: String { get }
 
-    func getFlagValue (in source: FlagValueSource?) -> Any?
+    func getFlagValue (in source: FlagValueSource?, diagnosticsEnabled: Bool) -> LocatedFlagValue?
     func save (to source: FlagValueSource) throws
 }
 
-protocol AnyFlagGroup {
-    func allFlags () -> [AnyFlag]
-}
-
 extension Flag: AnyFlag {
-    func getFlagValue(in source: FlagValueSource?) -> Any? {
-        return value(in: source)
+    func getFlagValue (in source: FlagValueSource?, diagnosticsEnabled: Bool) -> LocatedFlagValue? {
+        guard let result = value(in: source) else {
+            return nil
+        }
+        return LocatedFlagValue(lookupResult: result, diagnosticsEnabled: diagnosticsEnabled)
     }
 
     func save(to source: FlagValueSource) throws {
@@ -27,6 +26,12 @@ extension Flag: AnyFlag {
 }
 
 
+// MARK: - Flag Groups
+
+protocol AnyFlagGroup {
+    func allFlags () -> [AnyFlag]
+}
+
 extension FlagGroup: AnyFlagGroup {
     func allFlags () -> [AnyFlag] {
         return Mirror(reflecting: self.wrappedValue)