feat: State change notification for flags client by typotter · Pull Request #3025 · DataDog/dd-sdk-android

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!}

…ethods

…ral core subscription class

typotter

Thanks Nikita. ptal

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

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


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

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


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

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


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

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


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

+    /**
+     * 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

    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

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


thanks. good catch

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

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


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

+    /**
+     * 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

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


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.

Implements state observation API for FlagsClient: - Add FlagsClientState sealed class (NotReady, Reconciling, Ready, Stale, Error) - Add FlagsStateListener interface for state change callbacks - Add StateObservable interface bundling getCurrentState, addListener, removeListener, and Flow - Implement FlagsStateManager with ExecutorService for ordered state notifications - Add synchronized blocks for defensive thread safety - Expose state via client.state property - Add StateFlow support for Kotlin coroutines - Ensure Java compatibility - Update NoOpFlagsClient with Ready state - Add comprehensive tests PR #3025

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

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

aleksandr-gringauz reviewed Nov 26, 2025

View reviewed changes

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

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 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

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

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

typotter merged commit bd9768e into develop Dec 1, 2025
26 of 29 checks passed

typotter deleted the typo/FFL-1442-android-sdk-of-wrapper-implement-observe-method branch December 1, 2025 23:15

typotter mentioned this pull request Dec 2, 2025

feat: Openfeature Provider implementation powered by DD Flags #2998

Merged

3 tasks

typotter mentioned this pull request Dec 8, 2025

feat: State change notification for flags client (for OpenFeature) #3042

Merged

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

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

Uh oh!

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!

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!

Uh oh!

typotter commented Dec 1, 2025

Uh oh!

dd-devflow-routing-codex Bot commented Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

typotter commented Dec 1, 2025

Uh oh!

typotter commented Dec 1, 2025

Uh oh!

dd-devflow-routing-codex Bot commented Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

typotter commented Dec 1, 2025

Uh oh!

dd-devflow-routing-codex Bot commented Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What to do next?

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

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