Add SMP + Legacy Provider adaptor

Signed-off-by: Max Pinheiro <max.pinheiro@fluxon.com>

Author: maxnrp

README.md

@@ -139,9 +139,11 @@ coroutineScope.launch(Dispatchers.Default) {
 }
 ```
 
+After `initialize()` returns, `setProviderAndWait` waits for the provider’s `status` to move off `NotReady` and `Reconciling`. That is the provider’s contract to fulfill; the SDK does not time out. If a provider never updates `status` correctly, the call never completes. If you need a maximum wait time, wrap the call in your own `withTimeout` from `kotlinx.coroutines` (or similar) at the application level.
+
 Asynchronous API that doesn't wait is also available. It's useful when you want to set a provider and continue with other tasks.
 
-However, flag evaluations are only possible after the provider is Ready.
+However, flag evaluations are only possible after the provider is `OpenFeatureStatus.Ready`. The built-in `NoOpProvider` reports `Ready` after initialization and returns default values for flags (a lightweight placeholder until you register a real provider).
 
 ```kotlin
 OpenFeatureAPI.setProvider(MyProvider()) // can pass a dispatcher here
@@ -412,11 +414,17 @@ in an Android app.
 
 ### Develop a provider
 
-To develop a provider, you need to create a new project and include the OpenFeature SDK as a dependency.
-You’ll then need to write the provider by implementing the `FeatureProvider` interface exported by the OpenFeature SDK.
+Providers are developed in dedicated projects that declare the OpenFeature SDK as a dependency. Each provider must implement the `StateManagingProvider` interface exported by the OpenFeature SDK.
+
+The provider must keep `status` and `observe()` consistent: each time the provider transitions between `OpenFeatureStatus.NotReady`, `OpenFeatureStatus.Reconciling`, and `OpenFeatureStatus.Ready`, it must update `_status` and emit the corresponding `OpenFeatureProviderEvents` (for example, `OpenFeatureStatus.Reconciling` paired with `ProviderReconciling()`). The SDK derives `statusFlow` from `status`, and application-level handlers registered via `OpenFeatureAPI.observe()` receive the emitted events — inconsistency between the two will produce contradictory state to callers.
 
 ```kotlin
-class NewProvider(override val hooks: List<Hook<*>>, override val metadata: ProviderMetadata) : FeatureProvider {
+class NewProvider(override val hooks: List<Hook<*>>, override val metadata: ProviderMetadata) : StateManagingProvider {
+    private val _status = MutableStateFlow(OpenFeatureStatus.NotReady)
+    override val status: StateFlow<OpenFeatureStatus> = _status.asStateFlow()
+
+    private val events = MutableSharedFlow<OpenFeatureProviderEvents>(replay = 1, extraBufferCapacity = 5)
+
     override fun getBooleanEvaluation(
         key: String,
         defaultValue: Boolean,
@@ -459,26 +467,43 @@ class NewProvider(override val hooks: List<Hook<*>>, override val metadata: Prov
 
     override suspend fun initialize(initialContext: EvaluationContext?) {
         // add context-aware provider initialization
+
+        _status.value = OpenFeatureStatus.Ready
+        events.emit(OpenFeatureProviderEvents.ProviderReady())
     }
 
     override suspend fun onContextSet(oldContext: EvaluationContext?, newContext: EvaluationContext) {
+        _status.value = OpenFeatureStatus.Reconciling
+        events.emit(OpenFeatureProviderEvents.ProviderReconciling())
+
         // add necessary changes on context change
+
+        _status.value = OpenFeatureStatus.Ready
+        events.emit(OpenFeatureProviderEvents.ProviderReady())
+    }
+
+    override fun shutdown() {
+        _status.value = OpenFeatureStatus.NotReady
+        events.tryEmit(OpenFeatureProviderEvents.ProviderNotReady)
+        // add necessary closure on shutdown
     }
 
     override fun track(
-      trackingEventName: String,
-      context: EvaluationContext?,
-      details: TrackingEventDetails?
+        trackingEventName: String,
+        context: EvaluationContext?,
+        details: TrackingEventDetails?
     ) {
-      // Optionally track an event
-    }
-  
-    override fun observe(): Flow<OpenFeatureProviderEvents> {
-        // Optionally return a `Flow` of OpenFeatureProviderEvents
+        // Optionally track an event
     }
+
+    override fun observe(): Flow<OpenFeatureProviderEvents> = events
 }
 ```
 
+#### `FeatureProvider` DEPRECATION
+
+`FeatureProvider` is still supported although `StateManagingProvider` is preferred for new providers. It should be noted that `FeatureProvider` is a legacy behavior and will be removed in the next major version, due to its possible race condition in the presence of multi-threading.
+
 > Built a new provider? [Let us know](https://github.com/open-feature/openfeature.dev/issues/new?assignees=&labels=provider&projects=&template=document-provider.yaml&title=%5BProvider%5D%3A+) so we can add it to the docs!
 
 ### Develop a hook

kotlin-sdk/api/android/kotlin-sdk.api

@@ -232,7 +232,7 @@ public final class dev/openfeature/kotlin/sdk/ImmutableStructure : dev/openfeatu
 	public fun keySet ()Ljava/util/Set;
 }
 
-public class dev/openfeature/kotlin/sdk/NoOpProvider : dev/openfeature/kotlin/sdk/FeatureProvider {
+public class dev/openfeature/kotlin/sdk/NoOpProvider : dev/openfeature/kotlin/sdk/StateManagingProvider {
 	public fun <init> ()V
 	public fun <init> (Ljava/util/List;)V
 	public synthetic fun <init> (Ljava/util/List;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
@@ -242,6 +242,7 @@ public class dev/openfeature/kotlin/sdk/NoOpProvider : dev/openfeature/kotlin/sd
 	public fun getIntegerEvaluation (Ljava/lang/String;ILdev/openfeature/kotlin/sdk/EvaluationContext;)Ldev/openfeature/kotlin/sdk/ProviderEvaluation;
 	public fun getMetadata ()Ldev/openfeature/kotlin/sdk/ProviderMetadata;
 	public fun getObjectEvaluation (Ljava/lang/String;Ldev/openfeature/kotlin/sdk/Value;Ldev/openfeature/kotlin/sdk/EvaluationContext;)Ldev/openfeature/kotlin/sdk/ProviderEvaluation;
+	public fun getStatus ()Lkotlinx/coroutines/flow/StateFlow;
 	public fun getStringEvaluation (Ljava/lang/String;Ljava/lang/String;Ldev/openfeature/kotlin/sdk/EvaluationContext;)Ldev/openfeature/kotlin/sdk/ProviderEvaluation;
 	public fun initialize (Ldev/openfeature/kotlin/sdk/EvaluationContext;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public fun observe ()Lkotlinx/coroutines/flow/Flow;
@@ -273,7 +274,7 @@ public final class dev/openfeature/kotlin/sdk/OpenFeatureAPI {
 	public final fun getHooks ()Ljava/util/List;
 	public final fun getProvider ()Ldev/openfeature/kotlin/sdk/FeatureProvider;
 	public final fun getProviderMetadata ()Ldev/openfeature/kotlin/sdk/ProviderMetadata;
-	public final fun getProvidersFlow ()Lkotlinx/coroutines/flow/MutableStateFlow;
+	public final fun getProvidersFlow ()Lkotlinx/coroutines/flow/StateFlow;
 	public final fun getStatus ()Ldev/openfeature/kotlin/sdk/OpenFeatureStatus;
 	public final fun getStatusFlow ()Lkotlinx/coroutines/flow/Flow;
 	public final fun setEvaluationContext (Ldev/openfeature/kotlin/sdk/EvaluationContext;Lkotlinx/coroutines/CoroutineDispatcher;)V
@@ -402,6 +403,18 @@ public final class dev/openfeature/kotlin/sdk/Reason : java/lang/Enum {
 	public static fun values ()[Ldev/openfeature/kotlin/sdk/Reason;
 }
 
+public abstract interface class dev/openfeature/kotlin/sdk/StateManagingProvider : dev/openfeature/kotlin/sdk/FeatureProvider {
+	public abstract fun getStatus ()Lkotlinx/coroutines/flow/StateFlow;
+	public abstract fun initialize (Ldev/openfeature/kotlin/sdk/EvaluationContext;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public abstract fun observe ()Lkotlinx/coroutines/flow/Flow;
+	public abstract fun onContextSet (Ldev/openfeature/kotlin/sdk/EvaluationContext;Ldev/openfeature/kotlin/sdk/EvaluationContext;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public abstract fun shutdown ()V
+}
+
+public final class dev/openfeature/kotlin/sdk/StateManagingProvider$DefaultImpls {
+	public static fun track (Ldev/openfeature/kotlin/sdk/StateManagingProvider;Ljava/lang/String;Ldev/openfeature/kotlin/sdk/EvaluationContext;Ldev/openfeature/kotlin/sdk/TrackingEventDetails;)V
+}
+
 public abstract interface class dev/openfeature/kotlin/sdk/Structure {
 	public abstract fun asMap ()Ljava/util/Map;
 	public abstract fun asObjectMap ()Ljava/util/Map;
@@ -709,6 +722,19 @@ public final class dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$P
 	public fun toString ()Ljava/lang/String;
 }
 
+public final class dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderReconciling : dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents {
+	public fun <init> ()V
+	public fun <init> (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;)V
+	public synthetic fun <init> (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public final fun component1 ()Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;
+	public final fun copy (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;)Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderReconciling;
+	public static synthetic fun copy$default (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderReconciling;Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;ILjava/lang/Object;)Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderReconciling;
+	public fun equals (Ljava/lang/Object;)Z
+	public fun getEventDetails ()Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
 public final class dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderStale : dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents {
 	public fun <init> ()V
 	public fun <init> (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;)V
@@ -872,7 +898,7 @@ public final class dev/openfeature/kotlin/sdk/multiprovider/FirstSuccessfulStrat
 	public fun evaluate (Ljava/util/List;Ljava/lang/String;Ljava/lang/Object;Ldev/openfeature/kotlin/sdk/EvaluationContext;Lkotlin/jvm/functions/Function4;)Ldev/openfeature/kotlin/sdk/ProviderEvaluation;
 }
 
-public final class dev/openfeature/kotlin/sdk/multiprovider/MultiProvider : dev/openfeature/kotlin/sdk/FeatureProvider {
+public final class dev/openfeature/kotlin/sdk/multiprovider/MultiProvider : dev/openfeature/kotlin/sdk/StateManagingProvider {
 	public static final field Companion Ldev/openfeature/kotlin/sdk/multiprovider/MultiProvider$Companion;
 	public fun <init> (Ljava/util/List;Ldev/openfeature/kotlin/sdk/multiprovider/MultiProvider$Strategy;)V
 	public synthetic fun <init> (Ljava/util/List;Ldev/openfeature/kotlin/sdk/multiprovider/MultiProvider$Strategy;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
@@ -882,6 +908,7 @@ public final class dev/openfeature/kotlin/sdk/multiprovider/MultiProvider : dev/
 	public fun getIntegerEvaluation (Ljava/lang/String;ILdev/openfeature/kotlin/sdk/EvaluationContext;)Ldev/openfeature/kotlin/sdk/ProviderEvaluation;
 	public fun getMetadata ()Ldev/openfeature/kotlin/sdk/ProviderMetadata;
 	public fun getObjectEvaluation (Ljava/lang/String;Ldev/openfeature/kotlin/sdk/Value;Ldev/openfeature/kotlin/sdk/EvaluationContext;)Ldev/openfeature/kotlin/sdk/ProviderEvaluation;
+	public fun getStatus ()Lkotlinx/coroutines/flow/StateFlow;
 	public final fun getStatusFlow ()Lkotlinx/coroutines/flow/StateFlow;
 	public fun getStringEvaluation (Ljava/lang/String;Ljava/lang/String;Ldev/openfeature/kotlin/sdk/EvaluationContext;)Ldev/openfeature/kotlin/sdk/ProviderEvaluation;
 	public fun initialize (Ldev/openfeature/kotlin/sdk/EvaluationContext;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;

kotlin-sdk/api/jvm/kotlin-sdk.api

@@ -232,7 +232,7 @@ public final class dev/openfeature/kotlin/sdk/ImmutableStructure : dev/openfeatu
 	public fun keySet ()Ljava/util/Set;
 }
 
-public class dev/openfeature/kotlin/sdk/NoOpProvider : dev/openfeature/kotlin/sdk/FeatureProvider {
+public class dev/openfeature/kotlin/sdk/NoOpProvider : dev/openfeature/kotlin/sdk/StateManagingProvider {
 	public fun <init> ()V
 	public fun <init> (Ljava/util/List;)V
 	public synthetic fun <init> (Ljava/util/List;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
@@ -242,6 +242,7 @@ public class dev/openfeature/kotlin/sdk/NoOpProvider : dev/openfeature/kotlin/sd
 	public fun getIntegerEvaluation (Ljava/lang/String;ILdev/openfeature/kotlin/sdk/EvaluationContext;)Ldev/openfeature/kotlin/sdk/ProviderEvaluation;
 	public fun getMetadata ()Ldev/openfeature/kotlin/sdk/ProviderMetadata;
 	public fun getObjectEvaluation (Ljava/lang/String;Ldev/openfeature/kotlin/sdk/Value;Ldev/openfeature/kotlin/sdk/EvaluationContext;)Ldev/openfeature/kotlin/sdk/ProviderEvaluation;
+	public fun getStatus ()Lkotlinx/coroutines/flow/StateFlow;
 	public fun getStringEvaluation (Ljava/lang/String;Ljava/lang/String;Ldev/openfeature/kotlin/sdk/EvaluationContext;)Ldev/openfeature/kotlin/sdk/ProviderEvaluation;
 	public fun initialize (Ldev/openfeature/kotlin/sdk/EvaluationContext;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public fun observe ()Lkotlinx/coroutines/flow/Flow;
@@ -273,7 +274,7 @@ public final class dev/openfeature/kotlin/sdk/OpenFeatureAPI {
 	public final fun getHooks ()Ljava/util/List;
 	public final fun getProvider ()Ldev/openfeature/kotlin/sdk/FeatureProvider;
 	public final fun getProviderMetadata ()Ldev/openfeature/kotlin/sdk/ProviderMetadata;
-	public final fun getProvidersFlow ()Lkotlinx/coroutines/flow/MutableStateFlow;
+	public final fun getProvidersFlow ()Lkotlinx/coroutines/flow/StateFlow;
 	public final fun getStatus ()Ldev/openfeature/kotlin/sdk/OpenFeatureStatus;
 	public final fun getStatusFlow ()Lkotlinx/coroutines/flow/Flow;
 	public final fun setEvaluationContext (Ldev/openfeature/kotlin/sdk/EvaluationContext;Lkotlinx/coroutines/CoroutineDispatcher;)V
@@ -402,6 +403,18 @@ public final class dev/openfeature/kotlin/sdk/Reason : java/lang/Enum {
 	public static fun values ()[Ldev/openfeature/kotlin/sdk/Reason;
 }
 
+public abstract interface class dev/openfeature/kotlin/sdk/StateManagingProvider : dev/openfeature/kotlin/sdk/FeatureProvider {
+	public abstract fun getStatus ()Lkotlinx/coroutines/flow/StateFlow;
+	public abstract fun initialize (Ldev/openfeature/kotlin/sdk/EvaluationContext;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public abstract fun observe ()Lkotlinx/coroutines/flow/Flow;
+	public abstract fun onContextSet (Ldev/openfeature/kotlin/sdk/EvaluationContext;Ldev/openfeature/kotlin/sdk/EvaluationContext;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public abstract fun shutdown ()V
+}
+
+public final class dev/openfeature/kotlin/sdk/StateManagingProvider$DefaultImpls {
+	public static fun track (Ldev/openfeature/kotlin/sdk/StateManagingProvider;Ljava/lang/String;Ldev/openfeature/kotlin/sdk/EvaluationContext;Ldev/openfeature/kotlin/sdk/TrackingEventDetails;)V
+}
+
 public abstract interface class dev/openfeature/kotlin/sdk/Structure {
 	public abstract fun asMap ()Ljava/util/Map;
 	public abstract fun asObjectMap ()Ljava/util/Map;
@@ -709,6 +722,19 @@ public final class dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$P
 	public fun toString ()Ljava/lang/String;
 }
 
+public final class dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderReconciling : dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents {
+	public fun <init> ()V
+	public fun <init> (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;)V
+	public synthetic fun <init> (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public final fun component1 ()Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;
+	public final fun copy (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;)Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderReconciling;
+	public static synthetic fun copy$default (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderReconciling;Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;ILjava/lang/Object;)Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderReconciling;
+	public fun equals (Ljava/lang/Object;)Z
+	public fun getEventDetails ()Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
 public final class dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderStale : dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents {
 	public fun <init> ()V
 	public fun <init> (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;)V
@@ -872,7 +898,7 @@ public final class dev/openfeature/kotlin/sdk/multiprovider/FirstSuccessfulStrat
 	public fun evaluate (Ljava/util/List;Ljava/lang/String;Ljava/lang/Object;Ldev/openfeature/kotlin/sdk/EvaluationContext;Lkotlin/jvm/functions/Function4;)Ldev/openfeature/kotlin/sdk/ProviderEvaluation;
 }
 
-public final class dev/openfeature/kotlin/sdk/multiprovider/MultiProvider : dev/openfeature/kotlin/sdk/FeatureProvider {
+public final class dev/openfeature/kotlin/sdk/multiprovider/MultiProvider : dev/openfeature/kotlin/sdk/StateManagingProvider {
 	public static final field Companion Ldev/openfeature/kotlin/sdk/multiprovider/MultiProvider$Companion;
 	public fun <init> (Ljava/util/List;Ldev/openfeature/kotlin/sdk/multiprovider/MultiProvider$Strategy;)V
 	public synthetic fun <init> (Ljava/util/List;Ldev/openfeature/kotlin/sdk/multiprovider/MultiProvider$Strategy;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
@@ -882,6 +908,7 @@ public final class dev/openfeature/kotlin/sdk/multiprovider/MultiProvider : dev/
 	public fun getIntegerEvaluation (Ljava/lang/String;ILdev/openfeature/kotlin/sdk/EvaluationContext;)Ldev/openfeature/kotlin/sdk/ProviderEvaluation;
 	public fun getMetadata ()Ldev/openfeature/kotlin/sdk/ProviderMetadata;
 	public fun getObjectEvaluation (Ljava/lang/String;Ldev/openfeature/kotlin/sdk/Value;Ldev/openfeature/kotlin/sdk/EvaluationContext;)Ldev/openfeature/kotlin/sdk/ProviderEvaluation;
+	public fun getStatus ()Lkotlinx/coroutines/flow/StateFlow;
 	public final fun getStatusFlow ()Lkotlinx/coroutines/flow/StateFlow;
 	public fun getStringEvaluation (Ljava/lang/String;Ljava/lang/String;Ldev/openfeature/kotlin/sdk/EvaluationContext;)Ldev/openfeature/kotlin/sdk/ProviderEvaluation;
 	public fun initialize (Ldev/openfeature/kotlin/sdk/EvaluationContext;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;