feat: Openfeature Provider implementation powered by DD Flags by typotter · Pull Request #2998 · DataDog/dd-sdk-android

typotter · 2025-11-10T18:20:01Z

What does this PR do?

This PR adds a new OpenFeature provider module (dd-sdk-android-flags-openfeature) that integrates the Datadog Feature Flags SDK with the
OpenFeature API, enabling developers to use standardized feature flag management while leveraging Datadog's observability platform.

Key components:

DatadogFlagsProvider: OpenFeature FeatureProvider implementation that adapts the OpenFeature API to Datadog's FlagsClient
Blocking Lifecycle: Implements spec-compliant blocking for initialize() and onContextSet() methods
State Observation: observe() method emitting provider state change events via Kotlin Flow
Extension Function: FlagsClient.asOpenFeatureProvider() for convenient wrapping of existing clients
Static-Context Paradigm: Implements OpenFeature's static-context model with global context management

Motivation

Why OpenFeature Integration?

Standardization: OpenFeature provides a vendor-neutral, community-driven specification for feature flagging
Ecosystem: Enables integration with OpenFeature-compatible tools and libraries
Migration Path: Allows customers to adopt OpenFeature API while using Datadog as the backend
Multi-Vendor: Customers can switch between feature flag providers without code changes

Additional Notes

** Provider Lifecycle & Blocking Behavior (OpenFeature Spec 1.7)**

Per the OpenFeature specification, provider lifecycle methods must block until ready:

initialize(initialContext)

Blocks until provider reaches Ready or Error state
Uses suspendCoroutine + StateObservable.addListener() to wait for terminal state
Throws exception if initialization fails (Error state)
Implementation: DatadogFlagsProvider.kt:99-124

onContextSet(oldContext, newContext)

Blocks during context reconciliation until Ready, Stale, or Error state
Enables OpenFeature SDK to emit PROVIDER_RECONCILING events while method executes
Returns normally for Ready/Stale, throws for Error
Implementation: DatadogFlagsProvider.kt:143-169

This blocking design ensures:

SDK knows when reconciliation is happening → emits PROVIDER_RECONCILING automatically
SDK emits PROVIDER_CONTEXT_CHANGED when onContextSet() completes
Proper state visibility for OpenFeature clients

Event Emission via observe() (OpenFeature Spec Section 5)

Per the OpenFeature Events specification, providers emit only certain events while the SDK handles others:

Provider emits (via observe() Flow):

PROVIDER_READY: When FlagsClient reaches Ready state
PROVIDER_STALE: When flags are stale but cached data available
PROVIDER_ERROR: When FlagsClient reaches Error state (unrecoverable)

SDK emits (not from provider):

PROVIDER_RECONCILING: SDK emits while onContextSet() is executing
PROVIDER_CONTEXT_CHANGED: SDK emits when onContextSet() completes

Filtered (not emitted by provider):

FlagsClientState.NotReady: Pre-initialization state, handled via blocking initialize()
FlagsClientState.Reconciling: Context reconciliation, SDK handles via blocking onContextSet()

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)

codecov-commenter · 2025-11-10T18:40:54Z

Codecov Report

❌ Patch coverage is 88.46154% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 70.86%. Comparing base (3099ab5) to head (d8e9f68).
⚠️ Report is 13 commits behind head on feature/flags-ofeat.

Files with missing lines	Patch %	Lines
.../android/flags/openfeature/DatadogFlagsProvider.kt	88.64%	0 Missing and 5 partials ⚠️
...droid/flags/openfeature/internal/FlagsClientExt.kt	85.71%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@                   Coverage Diff                   @@
##           feature/flags-ofeat    #2998      +/-   ##
=======================================================
+ Coverage                70.70%   70.86%   +0.16%     
=======================================================
  Files                      895      899       +4     
  Lines                    33030    33137     +107     
  Branches                  5562     5592      +30     
=======================================================
+ Hits                     23352    23481     +129     
+ Misses                    8111     8100      -11     
+ Partials                  1567     1556      -11

Files with missing lines	Coverage Δ
...atadog/android/flags/openfeature/FlagsClientExt.kt	`100.00% <100.00%> (ø)`
...droid/flags/openfeature/internal/FlagsClientExt.kt	`85.71% <85.71%> (ø)`
.../android/flags/openfeature/DatadogFlagsProvider.kt	`88.64% <88.64%> (-11.36%)`	⬇️

... and 37 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

datadog-datadog-prod-us1 · 2025-11-10T20:22:17Z

🎯 Code Coverage
• Patch Coverage: 100.00%
• Overall Coverage: 65.96% (+1.32%)

View detailed report

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

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

0xnm · 2025-12-09T09:49:44Z

+                is FlagsClientState.Ready -> {
+                    flagsClient.state.removeListener(listener)
+                    continuation.resume(Unit)
+                }
+                is FlagsClientState.Error -> {
+                    flagsClient.state.removeListener(listener)
+                    continuation.resumeWithException(
+                        currentState.error ?: Exception("Initialization failed")
+                    )
+                }
+                else -> {} // Wait for state change notification


minor: it seems that this block is exactly the same as above, maybe it is worth extracting it?

typotter

Thanks. Still need to sort out some more changes. Will ping when ready for review

typotter · 2025-12-16T05:01:41Z

+ * @return Value.List containing the converted elements
+ */
+@Suppress("UnsafeThirdPartyFunctionCall")
+internal fun convertArrayToValue(jsonArray: JSONArray, internalLogger: InternalLogger? = null): Value {


made not optional.

typotter · 2025-12-16T05:02:54Z

+        Mockito.lenient().`when`(mockFlagsClient.state).thenReturn(mockStateObservable)
+        Mockito.lenient().`when`(mockStateObservable.addListener(any())).thenAnswer {
+            capturedStateListener = it.getArgument(0)
+            Unit
+        }
+        Mockito.lenient().`when`(mockStateObservable.getCurrentState()).thenReturn(FlagsClientState.NotReady)


typotter · 2025-12-16T05:10:01Z

+    @Test
+    fun `M call setEvaluationContext W initialize() {valid context}`() = runTest {
+        // Given
+        val context = dev.openfeature.kotlin.sdk.ImmutableContext(targetingKey = "user-123")


typotter · 2025-12-16T05:10:06Z

-        val result = provider.helloWorld()
+    fun `M return immediately W initialize() {already ready state}`() = runTest {
+        // Given
+        val context = dev.openfeature.kotlin.sdk.ImmutableContext(targetingKey = "user-123")


aleksandr-gringauz · 2025-12-15T16:02:37Z

+                        }
+                        is FlagsClientState.Error -> {
+                            flagsClient.state.removeListener(this)
+                            continuation.resumeWithException(


This will make initialize function throw an exception that isn't specified in its signature here https://github.com/open-feature/kotlin-sdk/blob/da47e54909bc1cfc77e2295b3d0ceb217d4193b9/kotlin-sdk/src/commonMain/kotlin/dev/openfeature/kotlin/sdk/FeatureProvider.kt#L18. Should we create OpenFeatureError here?

aleksandr-gringauz · 2025-12-15T16:07:31Z

+            when (val currentState = flagsClient.state.getCurrentState()) {
+                is FlagsClientState.Ready -> {
+                    flagsClient.state.removeListener(listener)
+                    continuation.resume(Unit)


We should be extra careful here. You can't call resume methods of Continuation multiple times https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.coroutines/suspend-coroutine.html. It is theoretically possible that it will be called in addListener right away. I suggest that we add the listener only if we aren't resuming here. Or skip this "fast path" entirely.

understood. With the setContext callback now, I think we should be OK here, as we're either calling resume from the callback, or from the other branch of the if; not both. Not listening to state change either

aleksandr-gringauz · 2025-12-16T09:23:31Z

+        setContext(newContext)
+
+        // Then wait for Ready, Stale, or Error state
+        suspendCoroutine<Unit> { continuation ->


I think you can create a helper function like this

private suspend fun StateObservable.waitFor(predicate: (FlagsClientState) -> Boolean): FlagsClientState { val currentState = getCurrentState() if (predicate(currentState)) { return currentState } return suspendCancellableCoroutine { cont -> val listener = object : FlagsStateListener { override fun onStateChanged(newState: FlagsClientState) { if (predicate(newState)) { removeListener(this) cont.resume(newState) } } } addListener(listener) cont.invokeOnCancellation { removeListener(listener) } } }

and use it here and in initialize function.

Also it is better to use suspendCancellableCoroutine.

Thanks for the details. We have a callback now, so much cleaner.

Implements OpenFeature Provider for Datadog Feature Flags SDK, enabling standardized feature flag management with vendor-neutral API. Key components: - DatadogFlagsProvider: Spec-compliant provider with blocking lifecycle - FlagsClient.asOpenFeatureProvider(): Extension function for wrapping clients - Type converters: Bidirectional JSON ↔ OpenFeature Value conversion - Event observation: Filtered state change events via Kotlin Flow OpenFeature spec compliance: - Blocking initialize() and onContextSet() (spec 1.7) - Proper event filtering (NotReady/Reconciling handled by SDK) - Static-context paradigm implementation - Error code mapping NotReady state clarifications: - Enhanced FlagsClientState.NotReady documentation - NoOpFlagsClient returns NotReady (not Error) as appropriate state - Aligns with OpenFeature NOT_READY semantics Dependencies: - dev.openfeature:kotlin-sdk-android:0.6.2 (118 Kb) - kotlinx-coroutines-core-jvm:1.7.3 (1514 Kb) - kotlinx-coroutines-test:1.7.3 (test only) - Total transitive dependencies: 3 Mb Test coverage: - 147 unit tests covering all provider methods - Type conversion edge cases - Blocking behavior verification - Event emission and filtering

…ng the listener

- Add resolveStructureValue(Map) overload that returns pure Kotlin collections - Implement JsonExtensions with bidirectional Map<->JSONObject conversion - Add comprehensive test coverage for Map API - Update FlagValueConverter to support all Map implementations - Add detekt safe calls configuration for JSON methods The Map API provides better Kotlin integration by returning nested Maps and Lists instead of JSONObject/JSONArray types. Both APIs coexist for compatibility.

… of supertype

0xnm · 2026-01-12T08:08:20Z

+        } catch (e: OpenFeatureError.ProviderFatalError) {
+            throw e


this can be removed

yes, we can actually skip the error promoting altogether.

0xnm · 2026-01-12T08:20:14Z

+     * @param initialContext The initial evaluation context to set (optional)
+     * @throws OpenFeatureError.ProviderFatalError if initialization fails
+     */
+    @Suppress("SwallowedException") // Message is propagated but detekt still considers it a swallowed exception.


This is still a valid concern from Detekt, because stacktrace is lost.

Maybe it is worth to avoid catching OpenFeatureError? Is there any added value in re-packaging it?

If we consider setting the initial context to not be a fatal error mode (this would come from not being able to pull a flag configuration wen setEvaluationContextSuspend is called), then we can avoid repackaging and catch/throwing below.
I suppose that, even though there might not have been a configuration successfully loaded, the SDK is still able to function returning the coded default at the least.

Actually, looking further into it, the OpenFeature SDK itself will shortcircuit the the Provider if it is in either the fatal or error states after initialize so it doesn't actually matter what which OpenFeatureError we throw here.

0xnm · 2026-01-12T08:21:40Z

+                // Safe: trySend returns ChannelResult, never throws exceptions
+                @Suppress("UnsafeThirdPartyFunctionCall")


trySend is already declared as a safe call, is this annotation necessary?

0xnm · 2026-01-12T08:22:33Z

+        /**
+         * Sentinel default value used to avoid unnecessary Value-to-Map conversion.
+         *
+         * When resolving structured flags, we pass this sentinel to the FlagsClient instead of
+         * converting the user's OpenFeature Value. If the FlagsClient returns this sentinel
+         * (via reference equality), we know no flag was found and can return the user's original
+         * default without any conversion overhead.
+         */


Suggested change

/**

* Sentinel default value used to avoid unnecessary Value-to-Map conversion.

*

* When resolving structured flags, we pass this sentinel to the FlagsClient instead of

* converting the user's OpenFeature Value. If the FlagsClient returns this sentinel

* (via reference equality), we know no flag was found and can return the user's original

* default without any conversion overhead.

*/

/**

* Sentinel default value used to avoid unnecessary Value-to-Map conversion.

*

* When resolving structured flags, we pass this sentinel to the [FlagsClient] instead of

* converting the user's OpenFeature [Value]. If the [FlagsClient] returns this sentinel

* (via reference equality), we know no flag was found and can return the user's original

* default without any conversion overhead.

*/

0xnm · 2026-01-12T08:24:52Z

There is another FlagsClientExt file with the same function inside.

removed from the public package. This extension is only needed internally

0xnm · 2026-01-12T08:35:12Z

    @Test
-    fun `M return greeting W helloWorld()`() {
-        val result = provider.helloWorld()
+    fun `M return immediately W initialize() {already ready state}`() = runTest {


the body of this test is exactly the same as above

0xnm · 2026-01-12T08:35:58Z


-        assertThat(result).isEqualTo("Hello from DatadogFlagsProvider!")
+        // Then - triggers context setting via suspend function
+        verify(mockFlagsClient).setEvaluationContext(any(), any())


worth to assert first argument instead of using any()

0xnm · 2026-01-12T08:39:08Z

+        delay(100) // Let flow set up
+        capturedStateListener?.onStateChanged(FlagsClientState.Ready)
+        delay(100) // Let event propagate


minor: Using delay with some value makes tests flaky. In fact for such tests we can just block execution until capturedStateListener is captured. Or use some other deterministic marker.

Thanks. I used testScheduler.runCurrent to run out any current coroutines instead of the delay. I think I have used it properly, though liberally

0xnm · 2026-01-12T08:41:01Z

+        // When/Then - should complete without throwing
+        mockFlagsClient.setEvaluationContextSuspend(context)
+
+        // Verify the correct context was passed


contrary to this comment, there is no context verification

0xnm · 2026-01-13T07:58:44Z

+        // Then - verify the correct context was passed
+        verify(mockFlagsClient).setEvaluationContext(contextCaptor.capture(), any())
+        assertThat(contextCaptor.firstValue).isEqualTo(context)
+        assertThat(contextCaptor.firstValue.targetingKey).isEqualTo(targetingKey)


the line above already covers it

0xnm · 2026-01-13T07:59:45Z

+        assertThat(contextCaptor.firstValue.targetingKey).isEqualTo(targetingKey)
+        assertThat(contextCaptor.firstValue.attributes).isEqualTo(attributes)


line above covers it as well

…datadog/android/flags/openfeature/internal/FlagsClientExt.kt Co-authored-by: Nikita Ogorodnikov <4046447+0xnm@users.noreply.github.com>

typotter · 2026-01-13T16:06:22Z

Thanks @0xnm PTAL for the last small changes

typotter · 2026-01-13T16:19:30Z

/merge

gh-worker-devflow-routing-ef8351 · 2026-01-13T16:19:38Z

View all feedbacks in Devflow UI.

2026-01-13 16:19:38 UTC ℹ️ Start processing command /merge

2026-01-13 16:20:10 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. View in MergeQueue UI.
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.

2026-01-13 17:10:49 UTC ℹ️ MergeQueue: merge request added to the queue

The expected merge time in feature/flags-ofeat is approximately 1h (p90).

2026-01-13 18:16:11 UTC ℹ️ MergeQueue: This merge request was merged

typotter changed the base branch from develop to feature/flags-ofeat November 10, 2025 18:22

typotter marked this pull request as ready for review November 24, 2025 16:51

typotter requested review from a team as code owners November 24, 2025 16:51

0xnm requested changes Nov 25, 2025

View reviewed changes

aleksandr-gringauz reviewed Nov 26, 2025

View reviewed changes

Comment thread ...eature/src/main/kotlin/com/datadog/android/flags/openfeature/internal/adapters/Converters.kt Outdated

Comment thread ...gs-openfeature/src/main/kotlin/com/datadog/android/flags/openfeature/DatadogFlagsProvider.kt

typotter force-pushed the typo/openfeature-module-impl branch from 16c7902 to 7692d7f Compare December 2, 2025 04:41

typotter mentioned this pull request Dec 8, 2025

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

Merged

typotter changed the base branch from feature/flags-ofeat to typo/openfeature-flags-client-state December 8, 2025 16:44

typotter force-pushed the typo/openfeature-module-impl branch from ef411d2 to 688b08c Compare December 8, 2025 17:02

typotter mentioned this pull request Dec 8, 2025

docs: Clarify NotReady state semantics for OpenFeature #3043

Closed

typotter changed the base branch from typo/openfeature-flags-client-state to typo/flags-not-ready-clarifications December 8, 2025 17:36

typotter force-pushed the typo/openfeature-module-impl branch from 688b08c to 2f3ed72 Compare December 8, 2025 17:36

typotter changed the base branch from typo/flags-not-ready-clarifications to typo/openfeature-flags-client-state December 8, 2025 17:45

typotter force-pushed the typo/openfeature-module-impl branch 4 times, most recently from 778e82a to 3e80743 Compare December 8, 2025 20:39

typotter commented Dec 8, 2025

View reviewed changes

0xnm requested changes Dec 9, 2025

View reviewed changes

Base automatically changed from typo/openfeature-flags-client-state to feature/flags-ofeat December 9, 2025 15:16

typotter commented Dec 16, 2025

View reviewed changes

aleksandr-gringauz reviewed Dec 16, 2025

View reviewed changes

typotter added 5 commits December 17, 2025 21:22

fix: rely on the StateObservable emitting the current state upon addi…

e92e064

…ng the listener

use resolve map

63b1963

tidy tests

5673b4f

use suppression instead of idiomatic _ because context is named param…

bbb4628

… of supertype

typotter requested review from 0xnm and aleksandr-gringauz January 8, 2026 22:23

typotter added 4 commits January 8, 2026 15:49

fix test

44cf8de

missing error use classname

f7e3deb

don't log initialization exception

c273748

don't log init error

0d1b622

0xnm requested changes Jan 12, 2026

View reviewed changes

typotter added 3 commits January 12, 2026 21:39

don't promote OF provider errors

a5f8bbb

fix comments and internall extension

f02a791

fix tests

9710149

typotter requested a review from 0xnm January 13, 2026 05:24

0xnm previously approved these changes Jan 13, 2026

View reviewed changes

Update features/dd-sdk-android-flags-openfeature/src/main/kotlin/com/…

16f7397

…datadog/android/flags/openfeature/internal/FlagsClientExt.kt Co-authored-by: Nikita Ogorodnikov <4046447+0xnm@users.noreply.github.com>

typotter dismissed 0xnm’s stale review via 16f7397 January 13, 2026 16:04

remove redundant checks

d8e9f68

typotter requested a review from 0xnm January 13, 2026 16:06

0xnm approved these changes Jan 13, 2026

View reviewed changes

dd-devflow Bot added mergequeue-status: waiting mergequeue-status: queued mergequeue-status: in_progress and removed mergequeue-status: waiting mergequeue-status: queued labels Jan 13, 2026

dd-mergequeue Bot merged commit a45cc1a into feature/flags-ofeat Jan 13, 2026
26 of 27 checks passed

dd-mergequeue Bot deleted the typo/openfeature-module-impl branch January 13, 2026 18:16

dd-devflow Bot added mergequeue-status: done and removed mergequeue-status: in_progress labels Jan 13, 2026

		// Safe: trySend returns ChannelResult, never throws exceptions
		@Suppress("UnsafeThirdPartyFunctionCall")

		assertThat(contextCaptor.firstValue.targetingKey).isEqualTo(targetingKey)
		assertThat(contextCaptor.firstValue.attributes).isEqualTo(attributes)

Conversation

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

Uh oh!

Review checklist (to be filled by reviewers)

Uh oh!

codecov-commenter commented Nov 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

datadog-datadog-prod-us1 Bot commented Nov 10, 2025 • edited 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!

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!

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!

Uh oh!

typotter left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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

typotter commented Nov 10, 2025 •

edited

Loading

codecov-commenter commented Nov 10, 2025 •

edited

Loading

datadog-datadog-prod-us1 Bot commented Nov 10, 2025 •

edited

Loading

typotter left a comment •

edited

Loading