Skip to content

Commit

Permalink
docs: Documentation for public protocols/constructors (#111)
Browse files Browse the repository at this point in the history
* Remove unused timeout parameter

* docs: In-code docs for public protocols/constructors
  • Loading branch information
fabriziodemaria committed May 2, 2024
1 parent 0ca65ea commit 01dda08
Show file tree
Hide file tree
Showing 8 changed files with 103 additions and 60 deletions.
46 changes: 25 additions & 21 deletions Sources/Confidence/Confidence.swift
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@ import Combine

public class Confidence: ConfidenceEventSender {
public let clientSecret: String
public var timeout: TimeInterval
public var region: ConfidenceRegion
public var initializationStrategy: InitializationStrategy
private let parent: ConfidenceContextProvider?
Expand All @@ -12,9 +11,9 @@ public class Confidence: ConfidenceEventSender {
private var removedContextKeys: Set<String> = Set()
private let confidenceQueue = DispatchQueue(label: "com.confidence.queue")

/// Internal, the hosting app should use Confidence.Builder instead
required init(
clientSecret: String,
timeout: TimeInterval,
region: ConfidenceRegion,
eventSenderEngine: EventSenderEngine,
initializationStrategy: InitializationStrategy,
Expand All @@ -24,7 +23,6 @@ public class Confidence: ConfidenceEventSender {
) {
self.eventSenderEngine = eventSenderEngine
self.clientSecret = clientSecret
self.timeout = timeout
self.region = region
self.initializationStrategy = initializationStrategy
self.contextFlow.value = context
Expand All @@ -34,17 +32,18 @@ public class Confidence: ConfidenceEventSender {
}
}

public func track(eventName: String, message: ConfidenceStruct) {
eventSenderEngine.emit(eventName: eventName, message: message, context: getContext())
}

/// Allows to observe changes in the Context, not meant to be used directly by the hosting app
public func contextChanges() -> AnyPublisher<ConfidenceStruct, Never> {
return contextFlow
.dropFirst()
.removeDuplicates()
.eraseToAnyPublisher()
}

public func track(eventName: String, message: ConfidenceStruct) {
eventSenderEngine.emit(eventName: eventName, message: message, context: getContext())
}

private func withLock(callback: @escaping (Confidence) -> Void) {
confidenceQueue.sync { [weak self] in
guard let self = self else {
Expand Down Expand Up @@ -73,7 +72,7 @@ public class Confidence: ConfidenceEventSender {
}
}

public func putContext(context: ConfidenceStruct) {
private func putContext(context: ConfidenceStruct) {
withLock { confidence in
var map = confidence.contextFlow.value
for entry in context {
Expand All @@ -83,11 +82,12 @@ public class Confidence: ConfidenceEventSender {
}
}

public func putContext(context: ConfidenceStruct, removedKeys: [String] = []) {
public func putContext(context: ConfidenceStruct, removeKeys: [String] = []) {
withLock { confidence in
var map = confidence.contextFlow.value
for removedKey in removedKeys {
for removedKey in removeKeys {
map.removeValue(forKey: removedKey)
confidence.removedContextKeys.insert(removedKey)
}
for entry in context {
map.updateValue(entry.value, forKey: entry.key)
Expand All @@ -96,7 +96,7 @@ public class Confidence: ConfidenceEventSender {
}
}

public func removeContextEntry(key: String) {
public func removeKey(key: String) {
withLock { confidence in
var map = confidence.contextFlow.value
map.removeValue(forKey: key)
Expand All @@ -108,7 +108,6 @@ public class Confidence: ConfidenceEventSender {
public func withContext(_ context: ConfidenceStruct) -> Self {
return Self.init(
clientSecret: clientSecret,
timeout: timeout,
region: region,
eventSenderEngine: eventSenderEngine,
initializationStrategy: initializationStrategy,
Expand All @@ -117,15 +116,17 @@ public class Confidence: ConfidenceEventSender {
}
}

// MARK: Builder

extension Confidence {
public class Builder {
let clientSecret: String
var timeout: TimeInterval = 10.0
var region: ConfidenceRegion = .global
var initializationStrategy: InitializationStrategy = .fetchAndActivate
let eventStorage: EventStorage
var visitorId: String?

/// Initializes the builder with the given credentails.
public init(clientSecret: String) {
self.clientSecret = clientSecret
do {
Expand All @@ -135,22 +136,27 @@ extension Confidence {
}
}

public func withTimeout(timeout: TimeInterval) -> Builder {
self.timeout = timeout
return self
}


/**
Sets the region for the network request to the Confidence backend.
The default is `global` and the requests are automatically routed to the closest server.
*/
public func withRegion(region: ConfidenceRegion) -> Builder {
self.region = region
return self
}

/**
Flag resolve configuration related to how to refresh flags at startup
*/
public func withInitializationstrategy(initializationStrategy: InitializationStrategy) -> Builder {
self.initializationStrategy = initializationStrategy
return self
}

/**
The SDK attaches a unique identifier to the Context, which is persisted across
restarts of the App but re-generated on every new install
*/
public func withVisitorId() -> Builder {
self.visitorId = VisitorUtil().getId()
return self
Expand All @@ -160,7 +166,6 @@ extension Confidence {
let uploader = RemoteConfidenceClient(
options: ConfidenceClientOptions(
credentials: ConfidenceClientCredentials.clientSecret(secret: clientSecret),
timeout: timeout,
region: region),
metadata: ConfidenceMetadata(
name: "SDK_ID_SWIFT_CONFIDENCE",
Expand All @@ -173,7 +178,6 @@ extension Confidence {
flushPolicies: [SizeFlushPolicy(batchSize: 1)])
return Confidence(
clientSecret: clientSecret,
timeout: timeout,
region: region,
eventSenderEngine: eventSenderEngine,
initializationStrategy: initializationStrategy,
Expand Down
4 changes: 3 additions & 1 deletion Sources/Confidence/ConfidenceContextProvider.swift
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
import Foundation

/// A Contextual implementer returns the current context
/**
A Contextual implementer returns the current context
*/
public protocol ConfidenceContextProvider {
func getContext() -> ConfidenceStruct
}
8 changes: 7 additions & 1 deletion Sources/Confidence/ConfidenceEventSender.swift
Original file line number Diff line number Diff line change
@@ -1,6 +1,12 @@
import Foundation

/// Sends events to Confidence. Contextual data is appended to each event
/**
Sends events to Confidence. Contextual data is appended to each event
*/
public protocol ConfidenceEventSender: Contextual {
/**
Upon return, the event has been correctly stored and will be emitted to the backend
according to the configured flushing logic
*/
func track(eventName: String, message: ConfidenceStruct)
}
28 changes: 20 additions & 8 deletions Sources/Confidence/Contextual.swift
Original file line number Diff line number Diff line change
@@ -1,14 +1,26 @@
import Foundation

/// A Contextual implementer maintains local context data and can create child instances
/// that can still access their parent's data
/// Each ConfidenceContextProvider returns local data reconciled with parents' data. Local data has precedence
/**
A Contextual implementer maintains local context data and can create child instances
that can still access their parent's data
Each ConfidenceContextProvider returns local data reconciled with parents' data. Local data has precedence
*/
public protocol Contextual: ConfidenceContextProvider {
/// Adds/override entry to local data
/**
Adds/override entry to local data
*/
func putContext(key: String, value: ConfidenceValue)
/// Removes entry from local data
/// It hides entries with this key from parents' data (without modifying parents' data)
func removeContextEntry(key: String)
/// Creates a child Contextual instance that maintains access to its parent's data
/**
Removes entry from local data
It hides entries with this key from parents' data (without modifying parents' data)
*/
func removeKey(key: String)
/**
Perform `putContext` and multiple `removeKey` at once
*/
func putContext(context: ConfidenceStruct, removeKeys: [String])
/**
Creates a child Contextual instance that maintains access to its parent's data
*/
func withContext(_ context: ConfidenceStruct) -> Self
}
14 changes: 12 additions & 2 deletions Sources/Confidence/InitializationStrategy.swift
Original file line number Diff line number Diff line change
@@ -1,6 +1,16 @@
import Foundation

/// Flag resolve configuration related to how to refresh flags at startup
/**
Flag resolve configuration related to how to refresh flags at startup
*/
public enum InitializationStrategy {
case fetchAndActivate, activateAndFetchAsync
/**
Flags are resolved before the values are accessible by the application
*/
case fetchAndActivate
/**
Values in the cache are accessible right away, an asynchronous resolve
updates the cache for a future session
*/
case activateAndFetchAsync
}
18 changes: 7 additions & 11 deletions Sources/ConfidenceProvider/ConfidenceFeatureProvider.swift
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,6 @@ public class ConfidenceFeatureProvider: FeatureProvider {
let metadata = ConfidenceMetadata(version: "0.1.4") // x-release-please-version
let options = ConfidenceClientOptions(
credentials: ConfidenceClientCredentials.clientSecret(secret: confidence.clientSecret),
timeout: confidence.timeout,
region: confidence.region)
self.metadata = metadata
self.cache = InMemoryProviderCache.from(storage: DefaultStorage.resolverFlagsCache())
Expand All @@ -86,7 +85,7 @@ public class ConfidenceFeatureProvider: FeatureProvider {
return
}

self.updateConfidenceContext(context: initialContext)
confidence?.putContext(context: ConfidenceTypeMapper.from(ctx: initialContext))
if self.initializationStrategy == .activateAndFetchAsync {
eventHandler.send(.ready)
}
Expand Down Expand Up @@ -158,12 +157,13 @@ public class ConfidenceFeatureProvider: FeatureProvider {
return
}

var removedKeys: [String] = []
var removeKeys: [String] = []
if let oldContext = oldContext {
removedKeys = Array(oldContext.asMap().filter { key, _ in !newContext.asMap().keys.contains(key) }.keys)
removeKeys = Array(oldContext.asMap().filter { key, _ in !newContext.asMap().keys.contains(key) }.keys)
}

self.updateConfidenceContext(context: newContext, removedKeys: removedKeys)
confidence?.putContext(
context: ConfidenceTypeMapper.from(ctx: newContext),
removeKeys: removeKeys)
}

private func startListentingForContextChanges() {
Expand All @@ -185,10 +185,6 @@ public class ConfidenceFeatureProvider: FeatureProvider {
.store(in: &cancellables)
}

private func updateConfidenceContext(context: EvaluationContext, removedKeys: [String] = []) {
confidence?.putContext(context: ConfidenceTypeMapper.from(ctx: context), removedKeys: removedKeys)
}

public func getBooleanEvaluation(key: String, defaultValue: Bool, context: EvaluationContext?) throws
-> OpenFeature.ProviderEvaluation<Bool>
{
Expand Down Expand Up @@ -484,7 +480,7 @@ extension ConfidenceFeatureProvider {
var initializationStrategy: InitializationStrategy = .fetchAndActivate
var confidence: Confidence?

/// DEPRECATED
/// DEPRECATED: initialise with a `Confidence` object instead.
/// Initializes the builder with the given credentails.
///
/// OpenFeatureAPI.shared.setProvider(provider:
Expand Down
Loading

0 comments on commit 01dda08

Please sign in to comment.