refactor into FlagsStateManager

Author: typotter

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

@@ -12,16 +12,14 @@ 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 (e.g., from NOT_READY to READY, or
- * from READY to RECONCILING when the evaluation context changes).
+ * 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.
-     * @param error Optional error that caused the state change. This is typically provided
-     *              when transitioning to the [FlagsClientState.ERROR] state.
+     * @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, error: Throwable? = null)
+    fun onStateChanged(newState: FlagsClientState)
 }

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

@@ -0,0 +1,63 @@
+/*
+ * 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.internal
+
+import com.datadog.android.flags.FlagsStateListener
+import com.datadog.android.flags.model.FlagsClientState
+import com.datadog.android.internal.utils.DDCoreSubscription
+import java.util.concurrent.ExecutorService
+
+/**
+ * Manages state transitions and notifications for a [com.datadog.android.flags.FlagsClient].
+ *
+ * This class handles state change notifications to registered listeners. All notification
+ * methods are thread-safe and guarantee ordered delivery to listeners by using a
+ * single-threaded executor service.
+ *
+ * State updates trigger listener notifications asynchronously on the executor service.
+ *
+ * @param subscription the underlying subscription for managing listeners
+ * @param executorService single-threaded executor for ordered state notification delivery
+ */
+internal class FlagsStateManager(
+    private val subscription: DDCoreSubscription<FlagsStateListener>,
+    private val executorService: ExecutorService
+) {
+    /**
+     * Updates the state and notifies all listeners.
+     *
+     * This method asynchronously notifies all registered listeners on the executor service,
+     * ensuring ordered delivery.
+     *
+     * @param newState The new state to transition to.
+     */
+    internal fun updateState(newState: FlagsClientState) {
+        executorService.execute {
+            subscription.notifyListeners {
+                onStateChanged(newState)
+            }
+        }
+    }
+
+    /**
+     * Registers a listener to receive state change notifications.
+     *
+     * @param listener The listener to add.
+     */
+    fun addListener(listener: FlagsStateListener) {
+        subscription.addListener(listener)
+    }
+
+    /**
+     * Unregisters a previously registered listener.
+     *
+     * @param listener The listener to remove.
+     */
+    fun removeListener(listener: FlagsStateListener) {
+        subscription.removeListener(listener)
+    }
+}

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

@@ -8,32 +8,37 @@ package com.datadog.android.flags.model
 
 /**
  * Represents the current state of a [com.datadog.android.flags.FlagsClient].
- *
- * Note: A STALE state is not currently defined as there is no mechanism to determine
- * whether configuration is stale. This may be added in a future release.
  */
-enum class FlagsClientState {
+sealed class FlagsClientState {
     /**
      * The client has been created but no evaluation context has been set.
      * No flags are available for evaluation in this state.
      */
-    NOT_READY,
+    object NotReady : FlagsClientState()
 
     /**
      * The client has successfully loaded flags and they are available for evaluation.
      * This is the normal operational state.
      */
-    READY,
+    object Ready : FlagsClientState()
 
     /**
      * The client is currently fetching new flags for a context change.
      * Cached flags may still be available for evaluation during this state.
      */
-    RECONCILING,
+    object Reconciling : FlagsClientState()
+
+    /**
+     * The client is currently stale.
+     * Cached flags may still be available for evaluation during this state.
+     */
+    object Stale : FlagsClientState()
 
     /**
      * An unrecoverable error has occurred.
      * The client cannot provide flag evaluations in this state.
+     *
+     * @param error The error that caused the transition to this state, or null if unknown.
      */
-    ERROR
+    data class Error(val error: Throwable? = null) : FlagsClientState()
 }