feat: State change notification for flags client

detekt_custom_safe_calls.yml

@@ -449,6 +449,7 @@ datadog:
       - "java.util.concurrent.atomic.AtomicReference.constructor(com.datadog.android.api.SdkCore?)"
       - "java.util.concurrent.atomic.AtomicReference.constructor(com.datadog.android.api.feature.FeatureEventReceiver?)"
       - "java.util.concurrent.atomic.AtomicReference.constructor(com.datadog.android.flags.internal.repository.DefaultFlagsRepository.FlagsState?)"
+      - "java.util.concurrent.atomic.AtomicReference.constructor(com.datadog.android.flags.model.FlagsClientState?)"
       - "java.util.concurrent.atomic.AtomicReference.constructor(com.datadog.android.flags.model.ProviderContext?)"
       - "java.util.concurrent.atomic.AtomicReference.constructor(com.datadog.android.rum.internal.domain.RumContext?)"
       - "java.util.concurrent.atomic.AtomicReference.constructor(kotlin.collections.Map?)"
@@ -1064,6 +1065,7 @@ datadog:
       - "kotlin.IllegalArgumentException(kotlin.String?)"
       - "kotlin.IllegalStateException(kotlin.String?)"
       - "kotlin.Throwable.constructor()"
+      - "kotlin.Throwable.constructor(kotlin.String?)"
       - "kotlin.Throwable.fillInStackTrace()"
       - "kotlin.Throwable.stackTraceToString()"
       - "kotlin.UnsupportedOperationException()"

features/dd-sdk-android-flags/api/apiSurface

@@ -8,6 +8,7 @@ interface com.datadog.android.flags.FlagsClient
   fun resolveIntValue(String, Int): Int
   fun resolveStructureValue(String, org.json.JSONObject): org.json.JSONObject
   fun <T: Any> resolve(String, T): com.datadog.android.flags.model.ResolutionDetails<T>
+  val state: StateObservable
   class Builder
     constructor(String = DEFAULT_CLIENT_NAME, com.datadog.android.api.SdkCore = Datadog.getInstance())
     fun build(): FlagsClient
@@ -22,13 +23,26 @@ data class com.datadog.android.flags.FlagsConfiguration
     fun gracefulModeEnabled(Boolean): Builder
     fun build(): FlagsConfiguration
   companion object 
+interface com.datadog.android.flags.FlagsStateListener
+  fun onStateChanged(com.datadog.android.flags.model.FlagsClientState)
+interface com.datadog.android.flags.StateObservable
+  fun getCurrentState(): com.datadog.android.flags.model.FlagsClientState
+  fun addListener(FlagsStateListener)
+  fun removeListener(FlagsStateListener)
 enum com.datadog.android.flags.model.ErrorCode
   - PROVIDER_NOT_READY
   - FLAG_NOT_FOUND
   - PARSE_ERROR
   - TYPE_MISMATCH
 data class com.datadog.android.flags.model.EvaluationContext
   constructor(String, Map<String, String> = emptyMap())
+sealed class com.datadog.android.flags.model.FlagsClientState
+  object NotReady : FlagsClientState
+  object Ready : FlagsClientState
+  object Reconciling : FlagsClientState
+  object Stale : FlagsClientState
+  data class Error : FlagsClientState
+    constructor(Throwable? = null)
 data class com.datadog.android.flags.model.ResolutionDetails<T: Any>
   constructor(T, String? = null, ResolutionReason? = null, ErrorCode? = null, String? = null, Map<String, Any> = emptyMap())
 enum com.datadog.android.flags.model.ResolutionReason

features/dd-sdk-android-flags/api/dd-sdk-android-flags.api

@@ -11,6 +11,7 @@ public abstract interface class com/datadog/android/flags/FlagsClient {
 	public static fun get ()Lcom/datadog/android/flags/FlagsClient;
 	public static fun get (Ljava/lang/String;)Lcom/datadog/android/flags/FlagsClient;
 	public static fun get (Ljava/lang/String;Lcom/datadog/android/api/SdkCore;)Lcom/datadog/android/flags/FlagsClient;
+	public abstract fun getState ()Lcom/datadog/android/flags/StateObservable;
 	public abstract fun resolve (Ljava/lang/String;Ljava/lang/Object;)Lcom/datadog/android/flags/model/ResolutionDetails;
 	public abstract fun resolveBooleanValue (Ljava/lang/String;Z)Z
 	public abstract fun resolveDoubleValue (Ljava/lang/String;D)D
@@ -55,6 +56,16 @@ public final class com/datadog/android/flags/FlagsConfiguration$Builder {
 public final class com/datadog/android/flags/FlagsConfiguration$Companion {
 }
 
+public abstract interface class com/datadog/android/flags/FlagsStateListener {
+	public abstract fun onStateChanged (Lcom/datadog/android/flags/model/FlagsClientState;)V
+}
+
+public abstract interface class com/datadog/android/flags/StateObservable {
+	public abstract fun addListener (Lcom/datadog/android/flags/FlagsStateListener;)V
+	public abstract fun getCurrentState ()Lcom/datadog/android/flags/model/FlagsClientState;
+	public abstract fun removeListener (Lcom/datadog/android/flags/FlagsStateListener;)V
+}
+
 public final class com/datadog/android/flags/model/ErrorCode : java/lang/Enum {
 	public static final field FLAG_NOT_FOUND Lcom/datadog/android/flags/model/ErrorCode;
 	public static final field PARSE_ERROR Lcom/datadog/android/flags/model/ErrorCode;
@@ -170,6 +181,38 @@ public final class com/datadog/android/flags/model/ExposureEvent$Subject$Compani
 	public final fun fromJsonObject (Lcom/google/gson/JsonObject;)Lcom/datadog/android/flags/model/ExposureEvent$Subject;
 }
 
+public abstract class com/datadog/android/flags/model/FlagsClientState {
+}
+
+public final class com/datadog/android/flags/model/FlagsClientState$Error : com/datadog/android/flags/model/FlagsClientState {
+	public fun <init> ()V
+	public fun <init> (Ljava/lang/Throwable;)V
+	public synthetic fun <init> (Ljava/lang/Throwable;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public final fun component1 ()Ljava/lang/Throwable;
+	public final fun copy (Ljava/lang/Throwable;)Lcom/datadog/android/flags/model/FlagsClientState$Error;
+	public static synthetic fun copy$default (Lcom/datadog/android/flags/model/FlagsClientState$Error;Ljava/lang/Throwable;ILjava/lang/Object;)Lcom/datadog/android/flags/model/FlagsClientState$Error;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getError ()Ljava/lang/Throwable;
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class com/datadog/android/flags/model/FlagsClientState$NotReady : com/datadog/android/flags/model/FlagsClientState {
+	public static final field INSTANCE Lcom/datadog/android/flags/model/FlagsClientState$NotReady;
+}
+
+public final class com/datadog/android/flags/model/FlagsClientState$Ready : com/datadog/android/flags/model/FlagsClientState {
+	public static final field INSTANCE Lcom/datadog/android/flags/model/FlagsClientState$Ready;
+}
+
+public final class com/datadog/android/flags/model/FlagsClientState$Reconciling : com/datadog/android/flags/model/FlagsClientState {
+	public static final field INSTANCE Lcom/datadog/android/flags/model/FlagsClientState$Reconciling;
+}
+
+public final class com/datadog/android/flags/model/FlagsClientState$Stale : com/datadog/android/flags/model/FlagsClientState {
+	public static final field INSTANCE Lcom/datadog/android/flags/model/FlagsClientState$Stale;
+}
+
 public final class com/datadog/android/flags/model/ResolutionDetails {
 	public fun <init> (Ljava/lang/Object;Ljava/lang/String;Lcom/datadog/android/flags/model/ResolutionReason;Lcom/datadog/android/flags/model/ErrorCode;Ljava/lang/String;Ljava/util/Map;)V
 	public synthetic fun <init> (Ljava/lang/Object;Ljava/lang/String;Lcom/datadog/android/flags/model/ResolutionReason;Lcom/datadog/android/flags/model/ErrorCode;Ljava/lang/String;Ljava/util/Map;ILkotlin/jvm/internal/DefaultConstructorMarker;)V

features/dd-sdk-android-flags/src/main/kotlin/com/datadog/android/flags/FlagsClient.kt

@@ -16,6 +16,7 @@ import com.datadog.android.core.InternalSdkCore
 import com.datadog.android.flags.internal.DatadogFlagsClient
 import com.datadog.android.flags.internal.DefaultRumEvaluationLogger
 import com.datadog.android.flags.internal.FlagsFeature
+import com.datadog.android.flags.internal.FlagsStateManager
 import com.datadog.android.flags.internal.LogWithPolicy
 import com.datadog.android.flags.internal.NoOpFlagsClient
 import com.datadog.android.flags.internal.NoOpRumEvaluationLogger
@@ -28,6 +29,7 @@ import com.datadog.android.flags.internal.repository.NoOpFlagsRepository
 import com.datadog.android.flags.internal.repository.net.PrecomputeMapper
 import com.datadog.android.flags.model.EvaluationContext
 import com.datadog.android.flags.model.ResolutionDetails
+import com.datadog.android.internal.utils.DDCoreSubscription
 import org.json.JSONObject
 
 /**
@@ -148,6 +150,24 @@ interface FlagsClient {
      */
     fun <T : Any> resolve(flagKey: String, defaultValue: T): ResolutionDetails<T>
 
+    /**
+     * Observable interface for tracking client state changes.
+     *
+     * Provides three ways to observe state:
+     * - Synchronous: [StateObservable.getCurrentState] for immediate queries (Java-friendly)
+     * - Callback: [StateObservable.addListener] for traditional observers (Java-friendly)
+     *
+     * Example:
+     * ```kotlin
+     * // Synchronous
+     * val current = client.state.getCurrentState()
+     *
+     * // Callback
+     * client.state.addListener(listener)
+     * ```
+     */
+    val state: StateObservable
+
     /**
      * Builder for creating [FlagsClient] instances with custom configuration.
      *
@@ -338,7 +358,8 @@ interface FlagsClient {
 
         // region Internal
 
-        internal const val FLAGS_CLIENT_EXECUTOR_NAME = "flags-client-executor"
+        internal const val FLAGS_NETWORK_EXECUTOR_NAME = "flags-network"
+        internal const val FLAGS_STATE_NOTIFICATION_EXECUTOR_NAME = "flags-state-notifications"
 
         @Suppress("LongMethod")
         internal fun createInternal(
@@ -347,8 +368,11 @@ interface FlagsClient {
             flagsFeature: FlagsFeature,
             name: String
         ): FlagsClient {
-            val executorService = featureSdkCore.createSingleThreadExecutorService(
-                executorContext = FLAGS_CLIENT_EXECUTOR_NAME
+            val networkExecutorService = featureSdkCore.createSingleThreadExecutorService(
+                executorContext = FLAGS_NETWORK_EXECUTOR_NAME
+            )
+            val stateNotificationExecutorService = featureSdkCore.createSingleThreadExecutorService(
+                executorContext = FLAGS_STATE_NOTIFICATION_EXECUTOR_NAME
             )
 
             val datadogContext = (featureSdkCore as InternalSdkCore).getDatadogContext()
@@ -400,12 +424,19 @@ interface FlagsClient {
 
                 val precomputeMapper = PrecomputeMapper(featureSdkCore.internalLogger)
 
+                val flagStateManager = FlagsStateManager(
+                    DDCoreSubscription.create(),
+                    stateNotificationExecutorService,
+                    featureSdkCore.internalLogger
+                )
+
                 val evaluationsManager = EvaluationsManager(
-                    executorService = executorService,
+                    executorService = networkExecutorService,
                     internalLogger = featureSdkCore.internalLogger,
                     flagsRepository = flagsRepository,
                     assignmentsReader = assignmentsDownloader,
-                    precomputeMapper = precomputeMapper
+                    precomputeMapper = precomputeMapper,
+                    flagStateManager = flagStateManager
                 )
 
                 val rumEvaluationLogger = createRumEvaluationLogger(featureSdkCore)
@@ -416,7 +447,8 @@ interface FlagsClient {
                     flagsRepository = flagsRepository,
                     flagsConfiguration = configuration,
                     rumEvaluationLogger = rumEvaluationLogger,
-                    processor = flagsFeature.processor
+                    processor = flagsFeature.processor,
+                    flagStateManager = flagStateManager
                 )
             }
         }

features/dd-sdk-android-flags/src/main/kotlin/com/datadog/android/flags/FlagsStateListener.kt

@@ -0,0 +1,25 @@
+/*
+ * Unless explicitly stated otherwise all files in this repository are licensed under the Apache License Version 2.0.
+ * This product includes software developed at Datadog (https://www.datadoghq.com/).
+ * Copyright 2016-Present Datadog, Inc.
+ */
+
+package com.datadog.android.flags
+
+import com.datadog.android.flags.model.FlagsClientState
+
+/**
+ * Listener interface for receiving state change notifications from a [FlagsClient].
+ *
+ * Implementations of this interface can be registered with a [FlagsClient] to receive
+ * callbacks whenever the client's state changes.
+ */
+interface FlagsStateListener {
+    /**
+     * Called when the state of the [FlagsClient] changes.
+     *
+     * @param newState The new state of the client. If the state is [FlagsClientState.Error],
+     *                 the error details are contained within the state object itself.
+     */
+    fun onStateChanged(newState: FlagsClientState)
+}

features/dd-sdk-android-flags/src/main/kotlin/com/datadog/android/flags/StateObservable.kt

@@ -0,0 +1,61 @@
+/*
+ * Unless explicitly stated otherwise all files in this repository are licensed under the Apache License Version 2.0.
+ * This product includes software developed at Datadog (https://www.datadoghq.com/).
+ * Copyright 2016-Present Datadog, Inc.
+ */
+
+package com.datadog.android.flags
+
+import com.datadog.android.flags.model.FlagsClientState
+
+/**
+ * Observable interface for tracking [FlagsClient] state changes.
+ *
+ * This interface provides two ways to observe state:
+ * 1. **Synchronous getter**: [getCurrentState] for immediate state queries
+ * 2. **Callback pattern**: [addListener]/[removeListener] for reactive observers
+ *
+ * ## Usage Examples
+ *
+ * ```kotlin
+ * // Synchronous getter
+ * val current = client.state.getCurrentState()
+ * if (current is FlagsClientState.Ready) {
+ *     // Proceed
+ * }
+ *
+ * // Callback pattern
+ * client.state.addListener(object : FlagsStateListener {
+ *     override fun onStateChanged(newState: FlagsClientState) {
+ *         // Handle state change
+ *     }
+ * })
+ * ```
+ */
+interface StateObservable {
+    /**
+     * Returns the current state synchronously.
+     *
+     * This method is safe to call from any thread.
+     *
+     * @return The current [FlagsClientState].
+     */
+    fun getCurrentState(): FlagsClientState
+
+    /**
+     * Registers a listener to receive state change notifications.
+     *
+     * The listener will immediately receive the current state upon registration,
+     * then be notified of all future state changes.
+     *
+     * @param listener The [FlagsStateListener] to register.
+     */
+    fun addListener(listener: FlagsStateListener)
+
+    /**
+     * Unregisters a previously registered state listener.
+     *
+     * @param listener The [FlagsStateListener] to unregister.
+     */
+    fun removeListener(listener: FlagsStateListener)
+}

features/dd-sdk-android-flags/src/main/kotlin/com/datadog/android/flags/internal/DatadogFlagsClient.kt

@@ -10,6 +10,7 @@ import com.datadog.android.api.InternalLogger
 import com.datadog.android.api.feature.FeatureSdkCore
 import com.datadog.android.flags.FlagsClient
 import com.datadog.android.flags.FlagsConfiguration
+import com.datadog.android.flags.StateObservable
 import com.datadog.android.flags.internal.evaluation.EvaluationsManager
 import com.datadog.android.flags.internal.model.PrecomputedFlag
 import com.datadog.android.flags.internal.repository.FlagsRepository
@@ -35,6 +36,7 @@ import org.json.JSONObject
  * @param flagsConfiguration configuration for the flags feature
  * @param rumEvaluationLogger responsible for sending flag evaluations to RUM.
  * @param processor responsible for writing exposure batches to be sent to flags backend.
+ * @param flagStateManager channel for managing state change listeners
  */
 @Suppress("TooManyFunctions") // All functions are necessary for flag evaluation lifecycle
 internal class DatadogFlagsClient(
@@ -43,9 +45,12 @@ internal class DatadogFlagsClient(
     private val flagsRepository: FlagsRepository,
     private val flagsConfiguration: FlagsConfiguration,
     private val rumEvaluationLogger: RumEvaluationLogger,
-    private val processor: EventsProcessor
+    private val processor: EventsProcessor,
+    private val flagStateManager: FlagsStateManager
 ) : FlagsClient {
 
+    override val state: StateObservable = flagStateManager
+
     // region FlagsClient
 
     /**