fix: bring back provider eventing (#124)

Signed-off-by: Nicklas Lundin <[email protected]>

Author: nicklasl

README.md

@@ -75,7 +75,7 @@ coroutineScope.launch(Dispatchers.IO) {
 | ✅      | [Tracking](#tracking)           | Associate user actions with feature flag evaluations.                                                                              |
 | ❌      | [Logging](#logging)             | Integrate with popular logging packages.                                                                                           |
 | ❌      | [Named clients](#named-clients) | Utilize multiple providers in a single application.                                                                                |
-| ❌      | [Eventing](#eventing)           | React to state changes in the provider or flag management system.                                                                  |
+| ✅      | [Eventing](#eventing)           | React to state changes in the provider or flag management system.                                                                  |
 | ✅      | [Shutdown](#shutdown)           | Gracefully clean up a provider during application shutdown.                                                                        |
 | ⚠️     | [Extending](#extending)         | Extend OpenFeature with custom providers and hooks.                                                                                |
 
@@ -171,13 +171,37 @@ Tracking is optionally implemented by Providers.
 
 Logging customization is not yet available in the Kotlin SDK.
 
+It is possible to write and inject logging `Hook`s to log events at different stages of the flag evaluation life-cycle.
+
 ### Named clients
 
 Support for named clients is not yet available in the Kotlin SDK.
 
 ### Eventing
 
-Support for eventing is not yet available in the Kotlin SDK.
+Events from the Provider allow the SDK to react to state changes in the provider or underlying flag management system, such as flag definition changes, provider readiness, or error conditions.
+Events are optional which mean that not all Providers will emit them and it is not a must have. Some providers support additional events, such as `PROVIDER_CONFIGURATION_CHANGED`.
+
+Please refer to the documentation of the provider you're using to see what events are supported.
+
+Example usage:
+```kotlin
+viewModelScope.launch {
+  OpenFeatureAPI.observe().collect {
+    println(">> Provider event received")
+  }
+}
+
+viewModelScope.launch {
+  OpenFeatureAPI.setProviderAndWait(
+    MyFeatureProvider(),
+    Dispatchers.IO,
+    myEvaluationContext
+  )
+}
+```
+
+<!-- (It's only possible to observe events from the global `OpenFeatureAPI`, until multiple providers are supported) -->
 
 ### Shutdown
 
@@ -244,6 +268,18 @@ class NewProvider(override val hooks: List<Hook<*>>, override val metadata: Meta
     override suspend fun onContextSet(oldContext: EvaluationContext?, newContext: EvaluationContext) {
         // add necessary changes on context change
     }
+  
+    override fun track(
+      trackingEventName: String,
+      context: EvaluationContext?,
+      details: TrackingEventDetails?
+    ) {
+      // Optionally track an event
+    }
+  
+    override fun observe(): Flow<OpenFeatureProviderEvents> {
+        // Optionally return a `Flow` of OpenFeatureProviderEvents
+    }
 }
 ```
 

android/api/android.api

@@ -63,12 +63,14 @@ public abstract interface class dev/openfeature/sdk/FeatureProvider {
 	public abstract fun getObjectEvaluation (Ljava/lang/String;Ldev/openfeature/sdk/Value;Ldev/openfeature/sdk/EvaluationContext;)Ldev/openfeature/sdk/ProviderEvaluation;
 	public abstract fun getStringEvaluation (Ljava/lang/String;Ljava/lang/String;Ldev/openfeature/sdk/EvaluationContext;)Ldev/openfeature/sdk/ProviderEvaluation;
 	public abstract fun initialize (Ldev/openfeature/sdk/EvaluationContext;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public abstract fun observe ()Lkotlinx/coroutines/flow/Flow;
 	public abstract fun onContextSet (Ldev/openfeature/sdk/EvaluationContext;Ldev/openfeature/sdk/EvaluationContext;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public abstract fun shutdown ()V
 	public abstract fun track (Ljava/lang/String;Ldev/openfeature/sdk/EvaluationContext;Ldev/openfeature/sdk/TrackingEventDetails;)V
 }
 
 public final class dev/openfeature/sdk/FeatureProvider$DefaultImpls {
+	public static fun observe (Ldev/openfeature/sdk/FeatureProvider;)Lkotlinx/coroutines/flow/Flow;
 	public static fun track (Ldev/openfeature/sdk/FeatureProvider;Ljava/lang/String;Ldev/openfeature/sdk/EvaluationContext;Ldev/openfeature/sdk/TrackingEventDetails;)V
 }
 
@@ -237,6 +239,7 @@ public class dev/openfeature/sdk/NoOpProvider : dev/openfeature/sdk/FeatureProvi
 	public fun getObjectEvaluation (Ljava/lang/String;Ldev/openfeature/sdk/Value;Ldev/openfeature/sdk/EvaluationContext;)Ldev/openfeature/sdk/ProviderEvaluation;
 	public fun getStringEvaluation (Ljava/lang/String;Ljava/lang/String;Ldev/openfeature/sdk/EvaluationContext;)Ldev/openfeature/sdk/ProviderEvaluation;
 	public fun initialize (Ldev/openfeature/sdk/EvaluationContext;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public fun observe ()Lkotlinx/coroutines/flow/Flow;
 	public fun onContextSet (Ldev/openfeature/sdk/EvaluationContext;Ldev/openfeature/sdk/EvaluationContext;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public fun shutdown ()V
 	public fun track (Ljava/lang/String;Ldev/openfeature/sdk/EvaluationContext;Ldev/openfeature/sdk/TrackingEventDetails;)V
@@ -257,23 +260,24 @@ public final class dev/openfeature/sdk/OpenFeatureAPI {
 	public static final field INSTANCE Ldev/openfeature/sdk/OpenFeatureAPI;
 	public final fun addHooks (Ljava/util/List;)V
 	public final fun clearHooks ()V
-	public final fun clearProvider ()V
+	public final fun clearProvider (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public final fun getClient (Ljava/lang/String;Ljava/lang/String;)Ldev/openfeature/sdk/Client;
 	public static synthetic fun getClient$default (Ldev/openfeature/sdk/OpenFeatureAPI;Ljava/lang/String;Ljava/lang/String;ILjava/lang/Object;)Ldev/openfeature/sdk/Client;
 	public final fun getEvaluationContext ()Ldev/openfeature/sdk/EvaluationContext;
 	public final fun getHooks ()Ljava/util/List;
 	public final fun getProvider ()Ldev/openfeature/sdk/FeatureProvider;
 	public final fun getProviderMetadata ()Ldev/openfeature/sdk/ProviderMetadata;
+	public final fun getProvidersFlow ()Lkotlinx/coroutines/flow/MutableStateFlow;
 	public final fun getStatus ()Ldev/openfeature/sdk/OpenFeatureStatus;
 	public final fun getStatusFlow ()Lkotlinx/coroutines/flow/Flow;
 	public final fun setEvaluationContext (Ldev/openfeature/sdk/EvaluationContext;Lkotlinx/coroutines/CoroutineDispatcher;)V
 	public static synthetic fun setEvaluationContext$default (Ldev/openfeature/sdk/OpenFeatureAPI;Ldev/openfeature/sdk/EvaluationContext;Lkotlinx/coroutines/CoroutineDispatcher;ILjava/lang/Object;)V
 	public final fun setEvaluationContextAndWait (Ldev/openfeature/sdk/EvaluationContext;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public final fun setProvider (Ldev/openfeature/sdk/FeatureProvider;Lkotlinx/coroutines/CoroutineDispatcher;Ldev/openfeature/sdk/EvaluationContext;)V
 	public static synthetic fun setProvider$default (Ldev/openfeature/sdk/OpenFeatureAPI;Ldev/openfeature/sdk/FeatureProvider;Lkotlinx/coroutines/CoroutineDispatcher;Ldev/openfeature/sdk/EvaluationContext;ILjava/lang/Object;)V
-	public final fun setProviderAndWait (Ldev/openfeature/sdk/FeatureProvider;Ldev/openfeature/sdk/EvaluationContext;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
-	public static synthetic fun setProviderAndWait$default (Ldev/openfeature/sdk/OpenFeatureAPI;Ldev/openfeature/sdk/FeatureProvider;Ldev/openfeature/sdk/EvaluationContext;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
-	public final fun shutdown ()V
+	public final fun setProviderAndWait (Ldev/openfeature/sdk/FeatureProvider;Ldev/openfeature/sdk/EvaluationContext;Lkotlinx/coroutines/CoroutineDispatcher;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public static synthetic fun setProviderAndWait$default (Ldev/openfeature/sdk/OpenFeatureAPI;Ldev/openfeature/sdk/FeatureProvider;Ldev/openfeature/sdk/EvaluationContext;Lkotlinx/coroutines/CoroutineDispatcher;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
+	public final fun shutdown (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 }
 
 public final class dev/openfeature/sdk/OpenFeatureClient : dev/openfeature/sdk/Client {
@@ -325,7 +329,8 @@ public final class dev/openfeature/sdk/OpenFeatureStatus$Error : dev/openfeature
 }
 
 public final class dev/openfeature/sdk/OpenFeatureStatus$Fatal : dev/openfeature/sdk/OpenFeatureStatus {
-	public static final field INSTANCE Ldev/openfeature/sdk/OpenFeatureStatus$Fatal;
+	public fun <init> (Ldev/openfeature/sdk/exceptions/OpenFeatureError;)V
+	public final fun getError ()Ldev/openfeature/sdk/exceptions/OpenFeatureError;
 }
 
 public final class dev/openfeature/sdk/OpenFeatureStatus$NotReady : dev/openfeature/sdk/OpenFeatureStatus {
@@ -589,6 +594,36 @@ public final class dev/openfeature/sdk/Value$Structure : dev/openfeature/sdk/Val
 	public fun toString ()Ljava/lang/String;
 }
 
+public abstract interface class dev/openfeature/sdk/events/OpenFeatureProviderEvents {
+}
+
+public final class dev/openfeature/sdk/events/OpenFeatureProviderEvents$ProviderConfigurationChanged : dev/openfeature/sdk/events/OpenFeatureProviderEvents {
+	public static final field INSTANCE Ldev/openfeature/sdk/events/OpenFeatureProviderEvents$ProviderConfigurationChanged;
+}
+
+public final class dev/openfeature/sdk/events/OpenFeatureProviderEvents$ProviderError : dev/openfeature/sdk/events/OpenFeatureProviderEvents {
+	public fun <init> (Ldev/openfeature/sdk/exceptions/OpenFeatureError;)V
+	public final fun component1 ()Ldev/openfeature/sdk/exceptions/OpenFeatureError;
+	public final fun copy (Ldev/openfeature/sdk/exceptions/OpenFeatureError;)Ldev/openfeature/sdk/events/OpenFeatureProviderEvents$ProviderError;
+	public static synthetic fun copy$default (Ldev/openfeature/sdk/events/OpenFeatureProviderEvents$ProviderError;Ldev/openfeature/sdk/exceptions/OpenFeatureError;ILjava/lang/Object;)Ldev/openfeature/sdk/events/OpenFeatureProviderEvents$ProviderError;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getError ()Ldev/openfeature/sdk/exceptions/OpenFeatureError;
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class dev/openfeature/sdk/events/OpenFeatureProviderEvents$ProviderNotReady : dev/openfeature/sdk/events/OpenFeatureProviderEvents {
+	public static final field INSTANCE Ldev/openfeature/sdk/events/OpenFeatureProviderEvents$ProviderNotReady;
+}
+
+public final class dev/openfeature/sdk/events/OpenFeatureProviderEvents$ProviderReady : dev/openfeature/sdk/events/OpenFeatureProviderEvents {
+	public static final field INSTANCE Ldev/openfeature/sdk/events/OpenFeatureProviderEvents$ProviderReady;
+}
+
+public final class dev/openfeature/sdk/events/OpenFeatureProviderEvents$ProviderStale : dev/openfeature/sdk/events/OpenFeatureProviderEvents {
+	public static final field INSTANCE Ldev/openfeature/sdk/events/OpenFeatureProviderEvents$ProviderStale;
+}
+
 public final class dev/openfeature/sdk/exceptions/ErrorCode : java/lang/Enum {
 	public static final field FLAG_NOT_FOUND Ldev/openfeature/sdk/exceptions/ErrorCode;
 	public static final field GENERAL Ldev/openfeature/sdk/exceptions/ErrorCode;

android/build.gradle.kts

@@ -101,6 +101,7 @@ dependencies {
     testImplementation("junit:junit:4.13.2")
     testImplementation("org.mockito.kotlin:mockito-kotlin:5.4.0")
     testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.7.3")
+    testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-debug:1.7.3")
 }
 
 signing {

android/src/main/java/dev/openfeature/sdk/FeatureProvider.kt

@@ -1,6 +1,9 @@
 package dev.openfeature.sdk
 
+import dev.openfeature.sdk.events.OpenFeatureProviderEvents
 import dev.openfeature.sdk.exceptions.OpenFeatureError
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.emptyFlow
 import kotlin.jvm.Throws
 
 interface FeatureProvider {
@@ -53,4 +56,12 @@ interface FeatureProvider {
     fun track(trackingEventName: String, context: EvaluationContext?, details: TrackingEventDetails?) {
         // an empty default implementation to make implementing this functionality optional
     }
+
+    /**
+     * Used by providers to expose internal events to the SDK or the application.
+     * This can be optionally implemented by the provider to expose a flow of internal events.
+     */
+    fun observe(): Flow<OpenFeatureProviderEvents> {
+        return emptyFlow()
+    }
 }

android/src/main/java/dev/openfeature/sdk/OpenFeatureAPI.kt

@@ -1,23 +1,36 @@
 package dev.openfeature.sdk
 
+import dev.openfeature.sdk.events.OpenFeatureProviderEvents
 import dev.openfeature.sdk.exceptions.OpenFeatureError
 import kotlinx.coroutines.CoroutineDispatcher
 import kotlinx.coroutines.CoroutineScope
-import kotlinx.coroutines.Deferred
 import kotlinx.coroutines.Dispatchers
-import kotlinx.coroutines.async
+import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.cancelChildren
 import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.FlowCollector
 import kotlinx.coroutines.flow.MutableSharedFlow
+import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.distinctUntilChanged
+import kotlinx.coroutines.flow.filterIsInstance
+import kotlinx.coroutines.flow.flatMapLatest
+import kotlinx.coroutines.launch
 import java.util.concurrent.CancellationException
 
 @Suppress("TooManyFunctions")
 object OpenFeatureAPI {
-    private var setProviderJob: Deferred<Unit>? = null
-    private var setEvaluationContextJob: Deferred<Unit>? = null
+    private var setProviderJob: Job? = null
+    private var setEvaluationContextJob: Job? = null
+    private var observeProviderEventsJob: Job? = null
+    private var providerEventObservationScope: CoroutineScope? = null
+
     private val NOOP_PROVIDER = NoOpProvider()
     private var provider: FeatureProvider = NOOP_PROVIDER
     private var context: EvaluationContext? = null
+    val providersFlow: MutableStateFlow<FeatureProvider> = MutableStateFlow(NOOP_PROVIDER)
 
     private val _statusFlow: MutableSharedFlow<OpenFeatureStatus> =
         MutableSharedFlow<OpenFeatureStatus>(replay = 1, extraBufferCapacity = 5)
@@ -29,6 +42,7 @@ object OpenFeatureAPI {
      * A flow of [OpenFeatureStatus] that emits the current status of the SDK.
      */
     val statusFlow: Flow<OpenFeatureStatus> get() = _statusFlow.distinctUntilChanged()
+    private var providerJob: Job? = null
 
     var hooks: List<Hook<*>> = listOf()
         private set
@@ -51,8 +65,8 @@ object OpenFeatureAPI {
         initialContext: EvaluationContext? = null
     ) {
         setProviderJob?.cancel()
-        this.setProviderJob = CoroutineScope(dispatcher).async {
-            setProviderInternal(provider, initialContext)
+        this.setProviderJob = CoroutineScope(SupervisorJob() + dispatcher).launch {
+            setProviderInternal(provider, dispatcher, initialContext)
         }
     }
 
@@ -64,19 +78,35 @@ object OpenFeatureAPI {
      */
     suspend fun setProviderAndWait(
         provider: FeatureProvider,
-        initialContext: EvaluationContext? = null
+        initialContext: EvaluationContext? = null,
+        dispatcher: CoroutineDispatcher = Dispatchers.IO
     ) {
-        setProviderInternal(provider, initialContext)
+        setProviderInternal(provider, dispatcher, initialContext)
+    }
+
+    private fun listenToProviderEvents(provider: FeatureProvider, dispatcher: CoroutineDispatcher) {
+        providerJob?.cancel()
+        this.providerJob = CoroutineScope(SupervisorJob() + dispatcher).launch {
+            provider.observe().collect(handleProviderEvents)
+        }
     }
 
+    @OptIn(ExperimentalCoroutinesApi::class)
     private suspend fun setProviderInternal(
         provider: FeatureProvider,
+        dispatcher: CoroutineDispatcher,
         initialContext: EvaluationContext? = null
     ) {
-        this@OpenFeatureAPI.provider = provider
-        _statusFlow.emit(OpenFeatureStatus.NotReady)
+        // TODO should we send shutdown to previous provider:
+        // getProvider().shutdown()
+
+        this@OpenFeatureAPI.provider = provider.also {
+            _statusFlow.emit(OpenFeatureStatus.NotReady)
+        }
+        providersFlow.value = provider
         if (initialContext != null) context = initialContext
         try {
+            listenToProviderEvents(provider, dispatcher)
             getProvider().initialize(context)
             _statusFlow.emit(OpenFeatureStatus.Ready)
         } catch (e: OpenFeatureError) {
@@ -102,9 +132,11 @@ object OpenFeatureAPI {
     /**
      * Clear the current [FeatureProvider] for the SDK and set it to a no-op provider.
      */
-    fun clearProvider() {
+    suspend fun clearProvider() {
+        getProvider().shutdown()
         provider = NOOP_PROVIDER
-        _statusFlow.tryEmit(OpenFeatureStatus.NotReady)
+        providersFlow.value = NOOP_PROVIDER
+        _statusFlow.emit(OpenFeatureStatus.NotReady)
     }
 
     /**
@@ -140,7 +172,7 @@ object OpenFeatureAPI {
         dispatcher: CoroutineDispatcher = Dispatchers.IO
     ) {
         setEvaluationContextJob?.cancel()
-        this.setEvaluationContextJob = CoroutineScope(dispatcher).async {
+        this.setEvaluationContextJob = CoroutineScope(SupervisorJob() + dispatcher).launch {
             setEvaluationContextInternal(evaluationContext)
         }
     }
@@ -208,17 +240,54 @@ object OpenFeatureAPI {
      * This will cancel the provider set job and call the provider's shutdown method.
      * The SDK status will be set to [OpenFeatureStatus.NotReady].
      */
-    fun shutdown() {
+    suspend fun shutdown() {
+        clearHooks()
         setEvaluationContextJob?.cancel(CancellationException("Set context job was cancelled"))
         setProviderJob?.cancel(CancellationException("Provider set job was cancelled"))
-        provider = NOOP_PROVIDER
-        _statusFlow.tryEmit(OpenFeatureStatus.NotReady)
-        getProvider().shutdown()
-        clearHooks()
+        observeProviderEventsJob?.cancel(CancellationException("Provider event observe job was cancelled"))
+        providerEventObservationScope?.coroutineContext?.cancelChildren()
+        providerEventObservationScope?.coroutineContext?.cancel()
+        clearProvider()
     }
 
     /**
      * Get the current [OpenFeatureStatus] of the SDK.
      */
     fun getStatus(): OpenFeatureStatus = _statusFlow.replayCache.first()
+
+    /**
+     * Observe events from currently configured Provider.
+     */
+    @OptIn(ExperimentalCoroutinesApi::class)
+    inline fun <reified T : OpenFeatureProviderEvents> observe(): Flow<T> = providersFlow
+        .flatMapLatest { it.observe() }.filterIsInstance()
+
+    private val handleProviderEvents: FlowCollector<OpenFeatureProviderEvents> = FlowCollector {
+        when (it) {
+            OpenFeatureProviderEvents.ProviderReady -> {
+                _statusFlow.emit(OpenFeatureStatus.Ready)
+            }
+
+            is OpenFeatureProviderEvents.ProviderError -> {
+                val status = if (it.error is OpenFeatureError.ProviderFatalError) {
+                    OpenFeatureStatus.Fatal(it.error)
+                } else {
+                    OpenFeatureStatus.Error(it.error)
+                }
+                _statusFlow.emit(status)
+            }
+
+            OpenFeatureProviderEvents.ProviderNotReady -> {
+                _statusFlow.emit(OpenFeatureStatus.NotReady)
+            }
+
+            OpenFeatureProviderEvents.ProviderStale -> {
+                _statusFlow.emit(OpenFeatureStatus.Stale)
+            }
+
+            OpenFeatureProviderEvents.ProviderConfigurationChanged -> {
+                _statusFlow.emit(OpenFeatureStatus.Ready)
+            }
+        }
+    }
 }