feat: add provider status to client (#205)

Signed-off-by: Marcin Stepien <marcin.stepien@fluxon.com>

Author: mstepien

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

@@ -19,6 +19,7 @@ public abstract interface class dev/openfeature/kotlin/sdk/Client : dev/openfeat
 	public abstract fun addHooks (Ljava/util/List;)V
 	public abstract fun getHooks ()Ljava/util/List;
 	public abstract fun getMetadata ()Ldev/openfeature/kotlin/sdk/ClientMetadata;
+	public abstract fun getProviderStatus ()Ldev/openfeature/kotlin/sdk/OpenFeatureStatus;
 	public abstract fun getStatusFlow ()Lkotlinx/coroutines/flow/Flow;
 }
 
@@ -313,6 +314,7 @@ public final class dev/openfeature/kotlin/sdk/OpenFeatureClient : dev/openfeatur
 	public fun getObjectDetails (Ljava/lang/String;Ldev/openfeature/kotlin/sdk/Value;Ldev/openfeature/kotlin/sdk/FlagEvaluationOptions;)Ldev/openfeature/kotlin/sdk/FlagEvaluationDetails;
 	public fun getObjectValue (Ljava/lang/String;Ldev/openfeature/kotlin/sdk/Value;)Ldev/openfeature/kotlin/sdk/Value;
 	public fun getObjectValue (Ljava/lang/String;Ldev/openfeature/kotlin/sdk/Value;Ldev/openfeature/kotlin/sdk/FlagEvaluationOptions;)Ldev/openfeature/kotlin/sdk/Value;
+	public fun getProviderStatus ()Ldev/openfeature/kotlin/sdk/OpenFeatureStatus;
 	public fun getStatusFlow ()Lkotlinx/coroutines/flow/Flow;
 	public fun getStringDetails (Ljava/lang/String;Ljava/lang/String;)Ldev/openfeature/kotlin/sdk/FlagEvaluationDetails;
 	public fun getStringDetails (Ljava/lang/String;Ljava/lang/String;Ldev/openfeature/kotlin/sdk/FlagEvaluationOptions;)Ldev/openfeature/kotlin/sdk/FlagEvaluationDetails;

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

@@ -19,6 +19,7 @@ public abstract interface class dev/openfeature/kotlin/sdk/Client : dev/openfeat
 	public abstract fun addHooks (Ljava/util/List;)V
 	public abstract fun getHooks ()Ljava/util/List;
 	public abstract fun getMetadata ()Ldev/openfeature/kotlin/sdk/ClientMetadata;
+	public abstract fun getProviderStatus ()Ldev/openfeature/kotlin/sdk/OpenFeatureStatus;
 	public abstract fun getStatusFlow ()Lkotlinx/coroutines/flow/Flow;
 }
 
@@ -313,6 +314,7 @@ public final class dev/openfeature/kotlin/sdk/OpenFeatureClient : dev/openfeatur
 	public fun getObjectDetails (Ljava/lang/String;Ldev/openfeature/kotlin/sdk/Value;Ldev/openfeature/kotlin/sdk/FlagEvaluationOptions;)Ldev/openfeature/kotlin/sdk/FlagEvaluationDetails;
 	public fun getObjectValue (Ljava/lang/String;Ldev/openfeature/kotlin/sdk/Value;)Ldev/openfeature/kotlin/sdk/Value;
 	public fun getObjectValue (Ljava/lang/String;Ldev/openfeature/kotlin/sdk/Value;Ldev/openfeature/kotlin/sdk/FlagEvaluationOptions;)Ldev/openfeature/kotlin/sdk/Value;
+	public fun getProviderStatus ()Ldev/openfeature/kotlin/sdk/OpenFeatureStatus;
 	public fun getStatusFlow ()Lkotlinx/coroutines/flow/Flow;
 	public fun getStringDetails (Ljava/lang/String;Ljava/lang/String;)Ldev/openfeature/kotlin/sdk/FlagEvaluationDetails;
 	public fun getStringDetails (Ljava/lang/String;Ljava/lang/String;Ldev/openfeature/kotlin/sdk/FlagEvaluationOptions;)Ldev/openfeature/kotlin/sdk/FlagEvaluationDetails;

kotlin-sdk/src/commonMain/kotlin/dev/openfeature/kotlin/sdk/Client.kt

@@ -8,4 +8,9 @@ interface Client : Features, Tracking {
     val statusFlow: Flow<OpenFeatureStatus>
 
     fun addHooks(hooks: List<Hook<*>>)
+
+    /**
+     * Get the current [OpenFeatureStatus] of the Provider handling this client's evaluations.
+     */
+    fun getProviderStatus(): OpenFeatureStatus
 }

kotlin-sdk/src/commonMain/kotlin/dev/openfeature/kotlin/sdk/OpenFeatureClient.kt

@@ -26,6 +26,10 @@ class OpenFeatureClient(
 
     override val statusFlow = openFeatureAPI.statusFlow
 
+    override fun getProviderStatus(): OpenFeatureStatus {
+        return openFeatureAPI.getStatus()
+    }
+
     override fun getBooleanValue(key: String, defaultValue: Boolean): Boolean {
         return getBooleanDetails(key, defaultValue).value
     }
@@ -219,7 +223,7 @@ class OpenFeatureClient(
     }
 
     private fun shortCircuitIfNotReady() {
-        val providerStatus = openFeatureAPI.getStatus()
+        val providerStatus = getProviderStatus()
         if (providerStatus == OpenFeatureStatus.NotReady) {
             throw OpenFeatureError.ProviderNotReadyError()
         } else if (providerStatus is OpenFeatureStatus.Fatal) {

kotlin-sdk/src/commonTest/kotlin/dev/openfeature/kotlin/sdk/OpenFeatureClientTests.kt

@@ -1,10 +1,17 @@
 package dev.openfeature.kotlin.sdk
 
+import dev.openfeature.kotlin.sdk.helpers.BrokenInitProvider
 import dev.openfeature.kotlin.sdk.helpers.GenericSpyHookMock
+import dev.openfeature.kotlin.sdk.helpers.SlowProvider
+import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.test.StandardTestDispatcher
+import kotlinx.coroutines.test.advanceTimeBy
+import kotlinx.coroutines.test.runCurrent
 import kotlinx.coroutines.test.runTest
 import kotlin.test.AfterTest
 import kotlin.test.Test
 import kotlin.test.assertEquals
+import kotlin.test.assertTrue
 
 class OpenFeatureClientTests {
 
@@ -20,4 +27,52 @@ class OpenFeatureClientTests {
         val stringValue = OpenFeatureAPI.getClient().getStringValue("test", "defaultTest")
         assertEquals(stringValue, "defaultTest")
     }
+
+    /**
+     * Spec 1.7.1: The client MUST define a provider status accessor.
+     */
+    @Test
+    fun testClientGetProviderStatusShouldReturnReadyWhenProviderIsInitialized() = runTest {
+        OpenFeatureAPI.setProviderAndWait(NoOpProvider())
+        val client = OpenFeatureAPI.getClient()
+        assertEquals(OpenFeatureStatus.Ready, client.getProviderStatus())
+    }
+
+    /**
+     * Spec 1.7.1: The client MUST define a provider status accessor.
+     */
+    @Test
+    fun testClientGetProviderStatusShouldReturnErrorWhenProviderFailsToInitialize() = runTest {
+        OpenFeatureAPI.setProviderAndWait(BrokenInitProvider())
+        val client = OpenFeatureAPI.getClient()
+        assertTrue(client.getProviderStatus() is OpenFeatureStatus.Error)
+    }
+
+    /**
+     * Spec 1.7.2.1: Provider status accessor must support RECONCILING state (static-context paradigm).
+     */
+    @OptIn(ExperimentalCoroutinesApi::class)
+    @Test
+    fun testClientGetProviderStatusShouldReturnReconcilingWhileContextIsBeingUpdated() = runTest {
+        val dispatcher = StandardTestDispatcher(testScheduler)
+        val slowProvider = SlowProvider(dispatcher = dispatcher)
+        OpenFeatureAPI.setProvider(slowProvider, dispatcher = dispatcher)
+
+        // Wait for SlowProvider initialized (2000ms delay)
+        advanceTimeBy(2001)
+
+        val client = OpenFeatureAPI.getClient()
+        assertEquals(OpenFeatureStatus.Ready, client.getProviderStatus())
+
+        // Trigger a context update (takes 2000ms natively)
+        OpenFeatureAPI.setEvaluationContext(ImmutableContext(targetingKey = "user-123"), dispatcher)
+
+        // Run execution queue deterministically to ensure coroutine reaches emit(Reconciling)
+        runCurrent()
+        assertEquals(OpenFeatureStatus.Reconciling, client.getProviderStatus())
+
+        // Wait out the remaining 2000ms for slow context update finish
+        advanceTimeBy(2001)
+        assertEquals(OpenFeatureStatus.Ready, client.getProviderStatus())
+    }
 }