Merge pull request #3056 from DataDog/typo/FFL-1579-sdk-android-expose-callback-for-set-evaluation-context-method-call

[FFL-1579] Add callback support to setEvaluationContext method

Co-authored-by: typotter <[email protected]>

Author: dd-mergequeue[bot]

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

@@ -1,7 +1,10 @@
+interface com.datadog.android.flags.EvaluationContextCallback
+  fun onSuccess()
+  fun onFailure(Throwable)
 object com.datadog.android.flags.Flags
   fun enable(FlagsConfiguration = FlagsConfiguration.default, com.datadog.android.api.SdkCore = Datadog.getInstance())
 interface com.datadog.android.flags.FlagsClient
-  fun setEvaluationContext(com.datadog.android.flags.model.EvaluationContext)
+  fun setEvaluationContext(com.datadog.android.flags.model.EvaluationContext, EvaluationContextCallback? = null)
   fun resolveBooleanValue(String, Boolean): Boolean
   fun resolveStringValue(String, String): String
   fun resolveDoubleValue(String, Double): Double

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

@@ -1,3 +1,8 @@
+public abstract interface class com/datadog/android/flags/EvaluationContextCallback {
+	public abstract fun onFailure (Ljava/lang/Throwable;)V
+	public abstract fun onSuccess ()V
+}
+
 public final class com/datadog/android/flags/Flags {
 	public static final field INSTANCE Lcom/datadog/android/flags/Flags;
 	public static final fun enable ()V
@@ -18,7 +23,7 @@ public abstract interface class com/datadog/android/flags/FlagsClient {
 	public abstract fun resolveIntValue (Ljava/lang/String;I)I
 	public abstract fun resolveStringValue (Ljava/lang/String;Ljava/lang/String;)Ljava/lang/String;
 	public abstract fun resolveStructureValue (Ljava/lang/String;Lorg/json/JSONObject;)Lorg/json/JSONObject;
-	public abstract fun setEvaluationContext (Lcom/datadog/android/flags/model/EvaluationContext;)V
+	public abstract fun setEvaluationContext (Lcom/datadog/android/flags/model/EvaluationContext;Lcom/datadog/android/flags/EvaluationContextCallback;)V
 }
 
 public final class com/datadog/android/flags/FlagsClient$Builder {
@@ -34,6 +39,10 @@ public final class com/datadog/android/flags/FlagsClient$Companion {
 	public static synthetic fun get$default (Lcom/datadog/android/flags/FlagsClient$Companion;Ljava/lang/String;Lcom/datadog/android/api/SdkCore;ILjava/lang/Object;)Lcom/datadog/android/flags/FlagsClient;
 }
 
+public final class com/datadog/android/flags/FlagsClient$DefaultImpls {
+	public static synthetic fun setEvaluationContext$default (Lcom/datadog/android/flags/FlagsClient;Lcom/datadog/android/flags/model/EvaluationContext;Lcom/datadog/android/flags/EvaluationContextCallback;ILjava/lang/Object;)V
+}
+
 public final class com/datadog/android/flags/FlagsConfiguration {
 	public static final field Companion Lcom/datadog/android/flags/FlagsConfiguration$Companion;
 	public final fun copy (ZLjava/lang/String;Ljava/lang/String;ZZ)Lcom/datadog/android/flags/FlagsConfiguration;

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

@@ -0,0 +1,37 @@
+/*
+ * 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
+
+/**
+ * Callback interface for asynchronous evaluation context update operations.
+ *
+ * This callback is invoked on a background thread after the [FlagsClient.setEvaluationContext]
+ * operation completes. The callback is guaranteed to be invoked after the corresponding
+ * [FlagsClientState] transition.
+ */
+interface EvaluationContextCallback {
+    /**
+     * Invoked when the evaluation context update completes successfully.
+     *
+     * This method is called on a background executor thread after the state transitions
+     * to [FlagsClientState.Ready]. The new flag evaluations are now available for
+     * subsequent flag resolution calls.
+     */
+    fun onSuccess()
+
+    /**
+     * Invoked when the evaluation context update fails.
+     *
+     * This method is called on a background executor thread after the state transitions
+     * to either [FlagsClientState.Stale] (network failed but cached flags available) or
+     * [FlagsClientState.Error] (network failed with no cached flags).
+     *
+     * @param error A [Throwable] containing details about the failure, typically including
+     * a message explaining the network request failure.
+     */
+    fun onFailure(error: Throwable)
+}

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

@@ -67,9 +67,13 @@ interface FlagsClient {
      * The context is used to determine which flag values to return based on user targeting
      * rules. This method triggers a background fetch of updated flag evaluations.
      *
+     * This method returns immediately without blocking. The actual context update and flag
+     * fetching happen asynchronously on a background thread.
+     *
      * @param context The [EvaluationContext] containing targeting key and attributes.
+     * @param callback Optional callback to notify when the operation completes or fails.
      */
-    fun setEvaluationContext(context: EvaluationContext)
+    fun setEvaluationContext(context: EvaluationContext, callback: EvaluationContextCallback? = null)
 
     /**
      * Resolves a boolean flag value.

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

@@ -8,6 +8,7 @@ package com.datadog.android.flags.internal
 
 import com.datadog.android.api.InternalLogger
 import com.datadog.android.api.feature.FeatureSdkCore
+import com.datadog.android.flags.EvaluationContextCallback
 import com.datadog.android.flags.FlagsClient
 import com.datadog.android.flags.FlagsConfiguration
 import com.datadog.android.flags.StateObservable
@@ -66,9 +67,11 @@ internal class DatadogFlagsClient(
      *
      * @param context The evaluation context containing targeting key and attributes.
      * Must contain a valid targeting key; invalid contexts are logged and ignored.
+     * @param callback Optional callback to notify when the operation completes or fails.
+     * Invoked on a background executor thread after the state transition.
      */
-    override fun setEvaluationContext(context: EvaluationContext) {
-        evaluationsManager.updateEvaluationsForContext(context)
+    override fun setEvaluationContext(context: EvaluationContext, callback: EvaluationContextCallback?) {
+        evaluationsManager.updateEvaluationsForContext(context, callback)
     }
 
     /**

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

@@ -7,6 +7,7 @@
 package com.datadog.android.flags.internal
 
 import com.datadog.android.api.InternalLogger
+import com.datadog.android.flags.EvaluationContextCallback
 import com.datadog.android.flags.FlagsClient
 import com.datadog.android.flags.FlagsStateListener
 import com.datadog.android.flags.StateObservable
@@ -43,10 +44,17 @@ internal class NoOpFlagsClient(
 
     /**
      * No-op implementation that ignores context updates and logs a warning.
+     *
+     * Consistent with the graceful degradation pattern, this method succeeds silently
+     * (invoking the success callback) while logging the no-op behavior. The actual error
+     * state is communicated via [state.getCurrentState] which returns [FlagsClientState.Error].
+     *
      * @param context Ignored evaluation context.
+     * @param callback Optional callback invoked immediately with success.
      */
-    override fun setEvaluationContext(context: EvaluationContext) {
+    override fun setEvaluationContext(context: EvaluationContext, callback: EvaluationContextCallback?) {
         logOperation("setEvaluationContext", InternalLogger.Level.WARN)
+        callback?.onSuccess()
     }
 
     /**

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

@@ -8,7 +8,9 @@ package com.datadog.android.flags.internal.evaluation
 
 import com.datadog.android.api.InternalLogger
 import com.datadog.android.core.internal.utils.executeSafe
+import com.datadog.android.flags.EvaluationContextCallback
 import com.datadog.android.flags.internal.FlagsStateManager
+import com.datadog.android.flags.internal.net.NetworkRequestFailedException
 import com.datadog.android.flags.internal.net.PrecomputedAssignmentsReader
 import com.datadog.android.flags.internal.repository.FlagsRepository
 import com.datadog.android.flags.internal.repository.net.PrecomputeMapper
@@ -50,8 +52,9 @@ internal class EvaluationsManager(
      *
      * @param context The evaluation context to process. Must be non-null and contain
      * a valid targeting key.
+     * @param callback Optional callback invoked when the context is set and the flags have been fetched successfully or not.
      */
-    fun updateEvaluationsForContext(context: EvaluationContext) {
+    fun updateEvaluationsForContext(context: EvaluationContext, callback: EvaluationContextCallback? = null) {
         flagStateManager.updateState(FlagsClientState.Reconciling)
 
         executorService.executeSafe(
@@ -76,18 +79,21 @@ internal class EvaluationsManager(
                 )
 
                 flagStateManager.updateState(FlagsClientState.Ready)
+                callback?.onSuccess()
             } else {
                 internalLogger.log(
                     InternalLogger.Level.WARN,
                     InternalLogger.Target.USER,
                     { NETWORK_REQUEST_FAILED_MESSAGE }
                 )
 
+                val throwable = NetworkRequestFailedException(NETWORK_REQUEST_FAILED_MESSAGE)
                 if (hadFlags) {
                     flagStateManager.updateState(FlagsClientState.Stale)
                 } else {
-                    flagStateManager.updateState(FlagsClientState.Error(Throwable(NETWORK_REQUEST_FAILED_MESSAGE)))
+                    flagStateManager.updateState(FlagsClientState.Error(throwable))
                 }
+                callback?.onFailure(throwable)
             }
         }
     }

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

@@ -0,0 +1,18 @@
+/*
+ * 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.net
+
+/**
+ * Exception thrown when a network request for flag evaluations fails.
+ *
+ * This exception is used internally to communicate network failures when updating evaluation
+ * contexts. It provides a clear signal that the failure was due to network connectivity issues
+ * rather than application logic errors.
+ *
+ * @param message A descriptive message about the network failure
+ */
+internal class NetworkRequestFailedException(message: String) : RuntimeException(message)

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

@@ -95,6 +95,20 @@ internal class NoOpFlagsClientTest {
         )
     }
 
+    @Test
+    fun `M invoke onSuccess W setEvaluationContext() { with callback }`(forge: Forge) {
+        // Given
+        val fakeContext = EvaluationContext(forge.anAlphabeticalString(), emptyMap())
+        val mockCallback = mock<EvaluationContextCallback>()
+
+        // When
+        testedClient.setEvaluationContext(fakeContext, callback = mockCallback)
+
+        // Then
+        // NoOp client follows graceful degradation pattern - succeeds silently
+        verify(mockCallback).onSuccess()
+    }
+
     // endregion
 
     // region resolveBooleanValue()

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

@@ -9,6 +9,7 @@ package com.datadog.android.flags.internal
 import com.datadog.android.api.InternalLogger
 import com.datadog.android.api.feature.Feature.Companion.RUM_FEATURE_NAME
 import com.datadog.android.api.feature.FeatureSdkCore
+import com.datadog.android.flags.EvaluationContextCallback
 import com.datadog.android.flags.FlagsConfiguration
 import com.datadog.android.flags.FlagsStateListener
 import com.datadog.android.flags.internal.evaluation.EvaluationsManager
@@ -34,6 +35,7 @@ import org.mockito.Mockito.mock
 import org.mockito.junit.jupiter.MockitoExtension
 import org.mockito.junit.jupiter.MockitoSettings
 import org.mockito.kotlin.any
+import org.mockito.kotlin.anyOrNull
 import org.mockito.kotlin.argumentCaptor
 import org.mockito.kotlin.doReturn
 import org.mockito.kotlin.eq
@@ -871,7 +873,10 @@ internal class DatadogFlagsClientTest {
 
         // Then
         val contextCaptor = argumentCaptor<EvaluationContext>()
-        verify(mockEvaluationsManager).updateEvaluationsForContext(contextCaptor.capture())
+        verify(mockEvaluationsManager).updateEvaluationsForContext(
+            contextCaptor.capture(),
+            anyOrNull()
+        )
 
         val capturedContext = contextCaptor.firstValue
         assertThat(capturedContext.targetingKey).isEqualTo(fakeTargetingKey)
@@ -894,7 +899,10 @@ internal class DatadogFlagsClientTest {
         // Then
         // Verify that blank targeting keys are allowed and processed
         val contextCaptor = argumentCaptor<EvaluationContext>()
-        verify(mockEvaluationsManager).updateEvaluationsForContext(contextCaptor.capture())
+        verify(mockEvaluationsManager).updateEvaluationsForContext(
+            contextCaptor.capture(),
+            anyOrNull()
+        )
 
         val capturedContext = contextCaptor.firstValue
         assertThat(capturedContext.targetingKey).isEmpty()
@@ -919,6 +927,37 @@ internal class DatadogFlagsClientTest {
         verify(mockEvaluationsManager).updateEvaluationsForContext(fakeContext)
     }
 
+    @Test
+    fun `M delegate callback W setEvaluationContext() { with callback }`(forge: Forge) {
+        // Given
+        val fakeContext = EvaluationContext(forge.anAlphabeticalString(), emptyMap())
+        val mockCallback = mock<EvaluationContextCallback>()
+
+        // When
+        testedClient.setEvaluationContext(fakeContext, mockCallback)
+
+        // Then
+        verify(mockEvaluationsManager).updateEvaluationsForContext(
+            fakeContext,
+            mockCallback
+        )
+    }
+
+    @Test
+    fun `M delegate with null callback W setEvaluationContext() { without callback }`(forge: Forge) {
+        // Given
+        val fakeContext = EvaluationContext(forge.anAlphabeticalString(), emptyMap())
+
+        // When
+        testedClient.setEvaluationContext(fakeContext)
+
+        // Then
+        verify(mockEvaluationsManager).updateEvaluationsForContext(
+            fakeContext,
+            null
+        )
+    }
+
     // endregion
 
     // region exposure event logging configuration