feat: context propagation review

Signed-off-by: Sviatoslav Sharaev <sviatoslav.sharaev@gmail.com>

Author: ssharaev

README.md

@@ -273,6 +273,27 @@ This should only be called when your application is in the process of shutting d
 OpenFeatureAPI.getInstance().shutdown();
 ```
 
+### Transaction Context Propagation
+Transaction context is a container for transaction-specific evaluation context (e.g. user id, user agent, IP).
+Transaction context can be set where specific data is available (e.g. an auth service or request handler) and by using the transaction context propagator it will automatically be applied to all flag evaluations within a transaction (e.g. a request or thread).
+By default, the `NoOpTransactionContextPropagator` is used, which doesn't store anything.
+To register a `ThreadLocal` context propagator, you can use the `setTransactionContextPropagator` method as shown below:
+```java
+// registering the ThreadLocalTransactionContextPropagator
+OpenFeatureAPI.getInstance().setTransactionContextPropagator(new ThreadLocalTransactionContextPropagator());
+```
+Once you've registered a transaction context propagator, you can propagate the data into request scoped transaction context.
+
+```java
+// adding userId to transaction context
+OpenFeatureAPI api = OpenFeatureAPI.getInstance();
+Map<String, Value> transactionAttrs = new HashMap<>();
+transactionAttrs.put("userId", new Value("userId"));
+EvaluationContext transactionCtx = new ImmutableContext(transactionAttrs);
+api.setTransactionContext(apiCtx);
+```
+Additionally, you can develop a custom transaction context propagator by implementing the `TransactionContextPropagator` interface and registering it as shown above.
+
 ## Extending
 
 ### Develop a provider

src/main/java/dev/openfeature/sdk/NoOpTransactionContextPropagator.java

@@ -1,17 +1,17 @@
 package dev.openfeature.sdk;
 
 /**
- * A {@link TransactionContextPropagator} that simply returns null.
+ * A {@link TransactionContextPropagator} that simply returns empty context.
  */
 public class NoOpTransactionContextPropagator implements TransactionContextPropagator {
 
     /**
      * {@inheritDoc}
-     * @return null
+     * @return empty immutable context
      */
     @Override
     public EvaluationContext getTransactionContext() {
-        return null;
+        return new ImmutableContext();
     }
 
     /**

src/main/java/dev/openfeature/sdk/OpenFeatureAPI.java

@@ -127,14 +127,14 @@ public void setTransactionContextPropagator(TransactionContextPropagator transac
      *
      * @return {@link EvaluationContext} The current transaction context
      */
-    public EvaluationContext getTransactionContext() {
+    EvaluationContext getTransactionContext() {
         return this.transactionContextPropagator.getTransactionContext();
     }
 
     /**
      * Sets the transaction context using the registered transaction context propagator.
      */
-    void setTransactionContext(EvaluationContext evaluationContext) {
+    public void setTransactionContext(EvaluationContext evaluationContext) {
         this.transactionContextPropagator.setTransactionContext(evaluationContext);
     }
 

src/main/java/dev/openfeature/sdk/OpenFeatureClient.java

@@ -164,9 +164,7 @@ private EvaluationContext mergeEvaluationContext(
                 ? openfeatureApi.getTransactionContext()
                 : new ImmutableContext();
 
-        EvaluationContext mergedInvocationCtx = invocationContext.merge(hookContext);
-
-        return apiContext.merge(transactionContext.merge(clientContext.merge(mergedInvocationCtx)));
+        return apiContext.merge(transactionContext.merge(clientContext.merge(invocationContext.merge(hookContext))));
     }
 
     private <T> ProviderEvaluation<?> createProviderEvaluation(

src/test/java/dev/openfeature/sdk/NoOpTransactionContextPropagatorTest.java

@@ -2,6 +2,9 @@
 
 import org.junit.jupiter.api.Test;
 
+import java.util.HashMap;
+import java.util.Map;
+
 import static org.junit.jupiter.api.Assertions.*;
 
 class NoOpTransactionContextPropagatorTest {
@@ -11,13 +14,16 @@ class NoOpTransactionContextPropagatorTest {
     @Test
     public void emptyTransactionContext() {
         EvaluationContext result = contextPropagator.getTransactionContext();
-        assertNull(result);
+        assertTrue(result.asMap().isEmpty());
     }
 
     @Test
     public void setTransactionContext() {
-        EvaluationContext firstContext = new ImmutableContext();
-        contextPropagator.setTransactionContext(firstContext);
-        assertNull(contextPropagator.getTransactionContext());
+        Map<String, Value> transactionAttrs = new HashMap<>();
+        transactionAttrs.put("userId", new Value("userId"));
+        EvaluationContext transactionCtx = new ImmutableContext(transactionAttrs);
+        contextPropagator.setTransactionContext(transactionCtx);
+        EvaluationContext result = contextPropagator.getTransactionContext();
+        assertTrue(result.asMap().isEmpty());
     }
 }