feat: State change notification for flags client #3025

typotter · 2025-11-25T05:46:42Z

What does this PR do?

Implements state management for FlagsClient in the dd-sdk-android-flags module, enabling applications and OpenFeature providers to observe client lifecycle states.

Key Changes:

Adds FlagsClientState enum with states: NOT_READY, READY, RECONCILING, ERROR
Adds FlagsStateListener interface for receiving state change notifications
Extends FlagsClient interface with state management methods: getCurrentState(), addStateListener(), removeStateListener()
Implements FlagsStateChannel wrapper over DDCoreSubscription with semantic notification methods
Wires state transitions through EvaluationsManager to DatadogFlagsClient
Provides comprehensive unit test coverage for all state management components

Motivation

This change is a prerequisite for implementing the OpenFeature provider's observe() method. The OpenFeature specification requires providers to emit events (PROVIDER_READY, PROVIDER_RECONCILING, PROVIDER_ERROR) when their state changes.

Without state tracking in the underlying FlagsClient, the OpenFeature provider has no mechanism to know when flags are loaded, when context changes begin/complete, or when errors occur.

Benefits:

Enables OpenFeature provider compliance with the observe() specification
Provides visibility into flag loading lifecycle for debugging and monitoring
Allows applications to react to flag availability changes
Fully backwards compatible - existing clients continue to work unchanged

Additional Notes

Design Decisions:

Left out STALE state: The OpenFeature spec includes a STALE state for "cached flags may be outdated", but we removed it because there's no current mechanism to determine staleness. Added a note in FlagsClientState docs that this may be added in a future release.
DDCoreSubscription with synchronization: Used the existing DDCoreSubscription utility for listener management, wrapped with synchronized blocks to guarantee ordered delivery of state changes (critical for NOT_READY → RECONCILING → READY flows).
FlagsStateChannel abstraction: Created a wrapper class with semantic methods (notifyReady(), notifyReconciling(), etc.) to abstract DDCoreSubscription internals and improve code readability.

State Transition Flow:

setEvaluationContext()
    ↓
EvaluationsManager.notifyReconciling()
    ↓
[Background fetch...]
    ↓
Success: EvaluationsManager.notifyReady()
Failure: EvaluationsManager.notifyError()
    ↓
FlagsStateChannel → All registered listeners notified

Thread Safety:

getCurrentState(): Lock-free atomic read
addStateListener()/removeStateListener(): Thread-safe via DDCoreSubscription
State notifications: Synchronized to guarantee ordered delivery

Review checklist (to be filled by reviewers)

Feature or bugfix MUST have appropriate tests (unit, integration, e2e)
Make sure you discussed the feature or bugfix with the maintaining team in an Issue
Make sure each commit and the PR mention the Issue number (cf the CONTRIBUTING doc)

Review checklist (to be filled by reviewers)

Feature or bugfix MUST have appropriate tests (unit, integration, e2e)
Make sure you discussed the feature or bugfix with the maintaining team in an Issue
Make sure each commit and the PR mention the Issue number (cf the CONTRIBUTING doc)

datadog-datadog-prod-us1 · 2025-11-25T07:10:13Z

🎯 Code Coverage
• Patch Coverage: 100.00%
• Total Coverage: 71.37% (+0.05%)

View detailed report

_{This comment will be updated automatically if new data arrives.

🔗 Commit SHA: c8b1143 | Docs | Datadog PR Page | Was this helpful? Give us feedback!}

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

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

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

...k-android-flags/src/test/kotlin/com/datadog/android/flags/internal/DatadogFlagsClientTest.kt

...dk-android-flags/src/test/kotlin/com/datadog/android/flags/internal/FlagsStateChannelTest.kt

...lags/src/test/kotlin/com/datadog/android/flags/internal/evaluation/EvaluationsManagerTest.kt

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

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

…ethods

…ral core subscription class

typotter

Thanks. I've removed coroutines and updated deps, etc. ptal

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

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

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

0xnm · 2025-12-01T09:25:18Z

detekt_custom_safe_calls.yml

+      - "kotlinx.coroutines.flow.MutableStateFlow(com.datadog.android.flags.model.FlagsClientState)"
+      - "kotlinx.coroutines.flow.MutableStateFlow.asStateFlow()"


since coroutines are now removed from this module, this is not relevant

0xnm · 2025-12-01T11:01:01Z

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

+    /**
+     * Observable interface for tracking client state changes.
+     *
+     * Provides three ways to observe state:
+     * - Synchronous: [StateObservable.getCurrentState] for immediate queries (Java-friendly)
+     * - Reactive: [StateObservable.flow] for coroutine-based updates (Kotlin)
+     * - Callback: [StateObservable.addListener] for traditional observers (Java-friendly)
+     *
+     * Example:
+     * ```kotlin
+     * // Synchronous
+     * val current = client.state.getCurrentState()
+     *
+     * // Reactive Flow
+     * client.state.flow.collect { state -> /* ... */ }


this comment is outdated, there is no Flow option

0xnm · 2025-12-01T11:08:46Z

...s/dd-sdk-android-flags/src/main/kotlin/com/datadog/android/flags/internal/NoOpFlagsClient.kt

+        override fun addListener(listener: FlagsStateListener) { /* no-op */ }
+        override fun removeListener(listener: FlagsStateListener) { /* no-op */ }


Suggested change

override fun addListener(listener: FlagsStateListener) { /* no-op */ }

override fun removeListener(listener: FlagsStateListener) { /* no-op */ }

override fun addListener(listener: FlagsStateListener) = Unit

override fun removeListener(listener: FlagsStateListener) = Unit

0xnm · 2025-12-01T11:09:51Z

.../src/test/kotlin/com/datadog/android/flags/internal/repository/DefaultFlagsRepositoryTest.kt

+    @Test
+    fun `M return expected value W hasFlags() { for various states }`(forge: Forge) {
+        data class TestCase(val given: () -> Unit, val then: Boolean)
+
+        val testCases = listOf(
+            TestCase(
+                given = { /* no state set */ },
+                then = false
+            ),
+            TestCase(


it is better to split this into different standalone tests

0xnm · 2025-12-01T11:12:23Z

.../src/test/kotlin/com/datadog/android/flags/internal/repository/DefaultFlagsRepositoryTest.kt

+    @Test
+    fun `M not block W hasFlags() { persistence still loading }`() {
+        // Given
+        val startTime = System.currentTimeMillis()


probably it is not a right place to start counting time, it is better to move it right before slowRepository.hasFlags() call

thanks. good catch

0xnm · 2025-12-01T11:13:49Z

features/dd-sdk-android-flags/src/test/kotlin/com/datadog/android/flags/FlagsTest.kt

    fun `set up`() {
        whenever(mockSdkCore.internalLogger) doReturn mockInternalLogger
-        whenever(mockSdkCore.createSingleThreadExecutorService(FLAGS_CLIENT_EXECUTOR_NAME)) doReturn
+        whenever(mockSdkCore.createSingleThreadExecutorService(org.mockito.kotlin.any())) doReturn


Suggested change

whenever(mockSdkCore.createSingleThreadExecutorService(org.mockito.kotlin.any())) doReturn

whenever(mockSdkCore.createSingleThreadExecutorService(any())) doReturn

0xnm · 2025-12-01T11:22:08Z

...k-android-flags/src/test/kotlin/com/datadog/android/flags/internal/DatadogFlagsClientTest.kt

+    @Test
+    fun `M delegate to state manager W state_addListener()`() {
+        // Given
+        val mockListener = mock(FlagsStateListener::class.java)


Suggested change

val mockListener = mock(FlagsStateListener::class.java)

val mockListener = mock<FlagsStateListener>()

0xnm · 2025-12-01T11:22:30Z

...k-android-flags/src/test/kotlin/com/datadog/android/flags/internal/DatadogFlagsClientTest.kt

+    @Test
+    fun `M delegate to state manager W state_removeListener()`() {
+        // Given
+        val mockListener = mock(FlagsStateListener::class.java)


Suggested change

val mockListener = mock(FlagsStateListener::class.java)

val mockListener = mock<FlagsStateListener>()

0xnm · 2025-12-01T11:27:19Z

...dk-android-flags/src/test/kotlin/com/datadog/android/flags/internal/FlagsStateManagerTest.kt

+    // region addListener / removeListener
+
+    @Test
+    fun `M notify listener W addListener() and notify`() {


this test is already included by the parametrized test above

0xnm · 2025-12-01T11:28:08Z

...dk-android-flags/src/test/kotlin/com/datadog/android/flags/internal/FlagsStateManagerTest.kt

+        testedManager.updateState(FlagsClientState.Ready)
+
+        // Then - no further notifications after removal
+        org.mockito.kotlin.verifyNoMoreInteractions(mockListener)


Suggested change

org.mockito.kotlin.verifyNoMoreInteractions(mockListener)

verifyNoMoreInteractions(mockListener)

typotter

Thanks Nikita. ptal

typotter · 2025-12-01T16:13:18Z

...dk-android-flags/src/test/kotlin/com/datadog/android/flags/internal/FlagsStateManagerTest.kt

+        testedManager.updateState(FlagsClientState.Ready)
+
+        // Then - no further notifications after removal
+        org.mockito.kotlin.verifyNoMoreInteractions(mockListener)


typotter · 2025-12-01T16:13:28Z

...k-android-flags/src/test/kotlin/com/datadog/android/flags/internal/DatadogFlagsClientTest.kt

+    @Test
+    fun `M delegate to state manager W state_removeListener()`() {
+        // Given
+        val mockListener = mock(FlagsStateListener::class.java)


typotter · 2025-12-01T16:13:31Z

...k-android-flags/src/test/kotlin/com/datadog/android/flags/internal/DatadogFlagsClientTest.kt

+    @Test
+    fun `M delegate to state manager W state_addListener()`() {
+        // Given
+        val mockListener = mock(FlagsStateListener::class.java)


typotter · 2025-12-01T16:13:36Z

...s/dd-sdk-android-flags/src/main/kotlin/com/datadog/android/flags/internal/NoOpFlagsClient.kt

+        override fun addListener(listener: FlagsStateListener) { /* no-op */ }
+        override fun removeListener(listener: FlagsStateListener) { /* no-op */ }


typotter · 2025-12-01T16:13:59Z

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

+    /**
+     * Observable interface for tracking client state changes.
+     *
+     * Provides three ways to observe state:
+     * - Synchronous: [StateObservable.getCurrentState] for immediate queries (Java-friendly)
+     * - Reactive: [StateObservable.flow] for coroutine-based updates (Kotlin)
+     * - Callback: [StateObservable.addListener] for traditional observers (Java-friendly)
+     *
+     * Example:
+     * ```kotlin
+     * // Synchronous
+     * val current = client.state.getCurrentState()
+     *
+     * // Reactive Flow
+     * client.state.flow.collect { state -> /* ... */ }


typotter · 2025-12-01T16:14:07Z

features/dd-sdk-android-flags/src/test/kotlin/com/datadog/android/flags/FlagsTest.kt

    fun `set up`() {
        whenever(mockSdkCore.internalLogger) doReturn mockInternalLogger
-        whenever(mockSdkCore.createSingleThreadExecutorService(FLAGS_CLIENT_EXECUTOR_NAME)) doReturn
+        whenever(mockSdkCore.createSingleThreadExecutorService(org.mockito.kotlin.any())) doReturn


typotter · 2025-12-01T16:14:34Z

.../src/test/kotlin/com/datadog/android/flags/internal/repository/DefaultFlagsRepositoryTest.kt

+    @Test
+    fun `M not block W hasFlags() { persistence still loading }`() {
+        // Given
+        val startTime = System.currentTimeMillis()


thanks. good catch

typotter · 2025-12-01T16:14:57Z

detekt_custom_safe_calls.yml

+      - "kotlinx.coroutines.flow.MutableStateFlow(com.datadog.android.flags.model.FlagsClientState)"
+      - "kotlinx.coroutines.flow.MutableStateFlow.asStateFlow()"


typotter · 2025-12-01T16:15:08Z

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

+    /**
+     * Observable interface for tracking client state changes.
+     *
+     * Provides three ways to observe state:
+     * - Synchronous: [StateObservable.getCurrentState] for immediate queries (Java-friendly)
+     * - Reactive: [StateObservable.flow] for coroutine-based updates (Kotlin)
+     * - Callback: [StateObservable.addListener] for traditional observers (Java-friendly)
+     *
+     * Example:
+     * ```kotlin
+     * // Synchronous
+     * val current = client.state.getCurrentState()
+     *
+     * // Reactive Flow
+     * client.state.flow.collect { state -> /* ... */ }


typotter · 2025-12-01T16:22:25Z

...dk-android-flags/src/test/kotlin/com/datadog/android/flags/internal/FlagsStateManagerTest.kt

+    // region addListener / removeListener
+
+    @Test
+    fun `M notify listener W addListener() and notify`() {


features/dd-sdk-android-flags/src/test/kotlin/com/datadog/android/flags/FlagsTest.kt

typotter · 2025-12-01T16:47:40Z

/merge

dd-devflow-routing-codex · 2025-12-01T16:47:44Z

View all feedbacks in Devflow UI.

2025-12-01 16:47:44 UTC ℹ️ Start processing command /merge

2025-12-01 16:47:50 UTC ℹ️ MergeQueue: waiting for PR to be ready

This pull request is not mergeable according to GitHub. Common reasons include pending required checks, missing approvals, or merge conflicts — but it could also be blocked by other repository rules or settings.
It will be added to the queue as soon as checks pass and/or get approvals.
Note: if you pushed new commits since the last approval, you may need additional approval.
You can remove it from the waiting list with /remove command.

2025-12-01 18:07:30 UTC ⚠️ MergeQueue: This merge request was unqueued

tyler.potter@datadoghq.com unqueued this merge request

typotter · 2025-12-01T16:48:09Z

Thanks. Just need one more stamp for the final change

typotter · 2025-12-01T18:07:23Z

/remove

dd-devflow-routing-codex · 2025-12-01T18:07:25Z

View all feedbacks in Devflow UI.

2025-12-01 18:07:25 UTC ℹ️ Start processing command /remove

2025-12-01 18:07:28 UTC ℹ️ Devflow: /remove

Requested changes have been applied; reviewer is on PTO.

typotter · 2025-12-01T20:12:41Z

/merge

dd-devflow-routing-codex · 2025-12-01T20:12:44Z

View all feedbacks in Devflow UI.

2025-12-01 20:12:44 UTC ℹ️ Start processing command /merge

2025-12-01 20:12:48 UTC ℹ️ MergeQueue: pull request added to the queue

The expected merge time in develop is approximately 1h (p90).

2025-12-01 20:29:08 UTC ❌ MergeQueue: The checks failed on this merge request

Tests failed on this commit 1909853:

Analyze (java)

What to do next?

Investigate the failures and when ready, re-add your pull request to the queue!
If your PR checks are green, try to rebase/merge. It might be because the CI run is a bit old.
Any question, go check the FAQ.

typotter changed the title ~~Typo/ffl 1442 android sdk of wrapper implement observe method~~ feat: State change notification for flags client Nov 25, 2025

typotter marked this pull request as ready for review November 25, 2025 06:50

typotter requested review from a team as code owners November 25, 2025 06:50

0xnm requested changes Nov 25, 2025

View reviewed changes

jonathanmos reviewed Nov 26, 2025

View reviewed changes

...d-sdk-android-flags/src/main/kotlin/com/datadog/android/flags/internal/DatadogFlagsClient.kt Outdated Show resolved Hide resolved

aleksandr-gringauz reviewed Nov 26, 2025

View reviewed changes

...dd-sdk-android-flags/src/main/kotlin/com/datadog/android/flags/internal/FlagsStateChannel.kt Outdated Show resolved Hide resolved

typotter added 16 commits November 27, 2025 10:43

Flags Client State enum

af48d48

Add flags-openfeature module to local-ci

a0cc0cc

Client State observer and reg/unreg

1d10ded

use DD core subscription, listeners, and implement new subscription m…

fe1b172

…ethods

Flags State channel w/named state methods, listener paradigm and leve…

8035650

…ral core subscription class

tests

4d1923c

api surface

856631b

trim comments

c9f9cbc

detekt safe

a44a582

api

2ffdd58

refactor into FlagsStateManager

d6d6538

tidy listener api on FlagsClient

4478372

hasFlags and tests

a913a5c

state listeners

4a54161

emit current state

949a693

fix race

be53823

typotter force-pushed the typo/FFL-1442-android-sdk-of-wrapper-implement-observe-method branch from 8cfaa65 to be53823 Compare November 27, 2025 18:01

typotter added 5 commits November 27, 2025 13:24

separate executors, abstract state interaction out of FlagsClient

d2b729d

lint imports

6d79a8b

safe calls and sync on state

f341b57

lint

1cb6beb

not using atomic reference for flags client state

9332ebf

typotter added 2 commits November 28, 2025 10:10

remove coroutines and Flow

7fdd225

no need to sync

740d7e7

typotter commented Nov 28, 2025

View reviewed changes

typotter requested a review from aleksandr-gringauz November 28, 2025 17:15

0xnm requested changes Dec 1, 2025

View reviewed changes

Fix comments, tests, safe calls

952b5b8

typotter commented Dec 1, 2025

View reviewed changes

typotter requested a review from 0xnm December 1, 2025 16:23

0xnm previously approved these changes Dec 1, 2025

View reviewed changes

features/dd-sdk-android-flags/src/test/kotlin/com/datadog/android/flags/FlagsTest.kt Outdated Show resolved Hide resolved

apply suggestion

c8b1143

typotter dismissed 0xnm’s stale review via c8b1143 December 1, 2025 16:47

typotter requested a review from 0xnm December 1, 2025 16:47

dd-devflow bot added the mergequeue-status: waiting label Dec 1, 2025

0xnm approved these changes Dec 1, 2025

View reviewed changes

dd-devflow bot added mergequeue-status: removed and removed mergequeue-status: waiting labels Dec 1, 2025

dd-devflow bot added mergequeue-status: queued mergequeue-status: in_progress mergequeue-status: rejected and removed mergequeue-status: removed mergequeue-status: queued mergequeue-status: in_progress labels Dec 1, 2025

		- "kotlinx.coroutines.flow.MutableStateFlow(com.datadog.android.flags.model.FlagsClientState)"
		- "kotlinx.coroutines.flow.MutableStateFlow.asStateFlow()"

		override fun addListener(listener: FlagsStateListener) { /* no-op */ }
		override fun removeListener(listener: FlagsStateListener) { /* no-op */ }

	whenever(mockSdkCore.createSingleThreadExecutorService(org.mockito.kotlin.any())) doReturn
	whenever(mockSdkCore.createSingleThreadExecutorService(any())) doReturn

	val mockListener = mock(FlagsStateListener::class.java)
	val mockListener = mock<FlagsStateListener>()

	org.mockito.kotlin.verifyNoMoreInteractions(mockListener)
	verifyNoMoreInteractions(mockListener)

feat: State change notification for flags client #3025

Are you sure you want to change the base?

feat: State change notification for flags client #3025

Conversation

typotter commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Motivation

Additional Notes

Review checklist (to be filled by reviewers)

Review checklist (to be filled by reviewers)

Uh oh!

datadog-datadog-prod-us1 bot commented Nov 25, 2025 • edited by datadog-official bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

typotter left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

typotter left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

typotter commented Nov 25, 2025 •

edited

Loading

datadog-datadog-prod-us1 bot commented Nov 25, 2025 •

edited by datadog-official bot

Loading

dd-devflow-routing-codex bot commented Dec 1, 2025 •

edited

Loading

dd-devflow-routing-codex bot commented Dec 1, 2025 •

edited

Loading

dd-devflow-routing-codex bot commented Dec 1, 2025 •

edited

Loading