feat: Implement transaction context (#312)

<!-- Please use this template for your pull request. -->
<!-- Please use the sections that you need and delete other sections -->

## Transaction Context
<!-- add the description of the PR here -->

This pull request introduces transaction context propagation to the
OpenFeature library. The changes include adding a new interface for
transaction context propagation, implementing a no-op and an
AsyncLocal-based propagator, and updating the API to support these
propagators.

### Related Issues
<!-- add here the GitHub issue that this PR resolves if applicable -->

Fixes #243 

### Notes
<!-- any additional notes for this PR -->
#### Transaction Context Propagation:

*
[`src/OpenFeature/Api.cs`](diffhunk://#diff-dc150fbd3b7be797470374ee7e38c7ab8a31eb9b6b7a52345e05114c2d32a15eR25-R26):
Added a private field `_transactionContextPropagator` and a lock for
thread safety. Introduced methods to get and set the transaction context
propagator, and to manage the transaction context using the propagator.
[[1]](diffhunk://#diff-dc150fbd3b7be797470374ee7e38c7ab8a31eb9b6b7a52345e05114c2d32a15eR25-R26)
[[2]](diffhunk://#diff-dc150fbd3b7be797470374ee7e38c7ab8a31eb9b6b7a52345e05114c2d32a15eR222-R274)
*
[`src/OpenFeature/AsyncLocalTransactionContextPropagator.cs`](diffhunk://#diff-d9ca58e32d696079f875c51837dfc6ded087b06eb3aef3513f5ea15ebc22c700R1-R25):
Implemented the `AsyncLocalTransactionContextPropagator` class that uses
`AsyncLocal<T>` to store the transaction context.
*
[`src/OpenFeature/NoOpTransactionContextPropagator.cs`](diffhunk://#diff-09ab422ed267155042b791de4d1c88f1bd82cb68d5f541a92c6af4318ceacd6aR1-R15):
Implemented a no-op version of the `ITransactionContextPropagator`
interface.
*
[`src/OpenFeature/Model/ITransactionContextPropagator.cs`](diffhunk://#diff-614f5b3e42871f4057f04d5fd27bf56157315e1c822ff0c83403255a8bf163ecR1-R26):
Defined the `ITransactionContextPropagator` interface responsible for
persisting transaction contexts.

#### API Enhancements:

*
[`src/OpenFeature/Api.cs`](diffhunk://#diff-dc150fbd3b7be797470374ee7e38c7ab8a31eb9b6b7a52345e05114c2d32a15eR291):
Updated the `ShutdownAsync` method to reset the transaction context
propagator.
*
[`src/OpenFeature/OpenFeatureClient.cs`](diffhunk://#diff-c23c8a3ea4538fbdcf6b1cf93ea3de456906e4d267fc4b2ba3f8b1cb186a7907R224):
Modified the `EvaluateFlagAsync` method to merge the transaction context
with the evaluation context.

---------

Signed-off-by: André Silva <[email protected]>
Signed-off-by: Todd Baert <[email protected]>
Co-authored-by: Todd Baert <[email protected]>

Author: askpt

README.md

@@ -68,18 +68,19 @@ public async Task Example()
 
 ## 🌟 Features
 
-| Status | Features                | Description                                                                                                                        |
-| ------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| ✅      | [Providers](#providers) | Integrate with a commercial, open source, or in-house feature management tool.                                                     |
-| ✅      | [Targeting](#targeting) | Contextually-aware flag evaluation using [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context). |
-| ✅      | [Hooks](#hooks)         | Add functionality to various stages of the flag evaluation life-cycle.                                                             |
-| ✅      | [Tracking](#tracking)   | Associate user actions with feature flag evaluations.                                                                              |
-| ✅      | [Logging](#logging)     | Integrate with popular logging packages.                                                                                           |
-| ✅      | [Domains](#domains)     | Logically bind clients with providers.                                                                                             |
-| ✅      | [Eventing](#eventing)   | React to state changes in the provider or flag management system.                                                                  |
-| ✅      | [Shutdown](#shutdown)   | Gracefully clean up a provider during application shutdown.                                                                        |
-| ✅      | [Extending](#extending) | Extend OpenFeature with custom providers and hooks.                                                                                |
-| 🔬      | [DependencyInjection](#DependencyInjection) | Integrate OpenFeature with .NET's dependency injection for streamlined provider setup.                         |
+| Status | Features                                                            | Description                                                                                                                                                   |
+| ------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ✅      | [Providers](#providers)                                             | Integrate with a commercial, open source, or in-house feature management tool.                                                                                |
+| ✅      | [Targeting](#targeting)                                             | Contextually-aware flag evaluation using [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context).                            |
+| ✅      | [Hooks](#hooks)                                                     | Add functionality to various stages of the flag evaluation life-cycle.                                                                                        |
+| ✅      | [Tracking](#tracking)                                               | Associate user actions with feature flag evaluations.                                                                                                         |
+| ✅      | [Logging](#logging)                                                 | Integrate with popular logging packages.                                                                                                                      |
+| ✅      | [Domains](#domains)                                                 | Logically bind clients with providers.                                                                                                                        |
+| ✅      | [Eventing](#eventing)                                               | React to state changes in the provider or flag management system.                                                                                             |
+| ✅      | [Shutdown](#shutdown)                                               | Gracefully clean up a provider during application shutdown.                                                                                                   |
+| ✅      | [Transaction Context Propagation](#transaction-context-propagation) | Set a specific [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context) for a transaction (e.g. an HTTP request or a thread). |
+| ✅      | [Extending](#extending)                                             | Extend OpenFeature with custom providers and hooks.                                                                                                           |
+| 🔬      | [DependencyInjection](#DependencyInjection)                         | Integrate OpenFeature with .NET's dependency injection for streamlined provider setup.                                                                        |
 
 > Implemented: ✅ | In-progress: ⚠️ | Not implemented yet: ❌ | Experimental: 🔬
 
@@ -234,6 +235,28 @@ The OpenFeature API provides a close function to perform a cleanup of all regist
 await Api.Instance.ShutdownAsync();
 ```
 
+### 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 [AsyncLocal](https://learn.microsoft.com/en-us/dotnet/api/system.threading.asynclocal-1) context propagator, you can use the `SetTransactionContextPropagator` method as shown below.
+
+```csharp
+// registering the AsyncLocalTransactionContextPropagator
+Api.Instance.SetTransactionContextPropagator(new AsyncLocalTransactionContextPropagator());
+```
+Once you've registered a transaction context propagator, you can propagate the data into request-scoped transaction context.
+
+```csharp
+// adding userId to transaction context
+EvaluationContext transactionContext = EvaluationContext.Builder()
+    .Set("userId", userId)
+    .Build();
+Api.Instance.SetTransactionContext(transactionContext);
+```
+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/OpenFeature/Api.cs

@@ -22,6 +22,8 @@ public sealed class Api : IEventBus
         private EventExecutor _eventExecutor = new EventExecutor();
         private ProviderRepository _repository = new ProviderRepository();
         private readonly ConcurrentStack<Hook> _hooks = new ConcurrentStack<Hook>();
+        private ITransactionContextPropagator _transactionContextPropagator = new NoOpTransactionContextPropagator();
+        private readonly object _transactionContextPropagatorLock = new();
 
         /// The reader/writer locks are not disposed because the singleton instance should never be disposed.
         private readonly ReaderWriterLockSlim _evaluationContextLock = new ReaderWriterLockSlim();
@@ -47,6 +49,7 @@ public async Task SetProviderAsync(FeatureProvider featureProvider)
         {
             this._eventExecutor.RegisterDefaultFeatureProvider(featureProvider);
             await this._repository.SetProviderAsync(featureProvider, this.GetContext(), this.AfterInitialization, this.AfterError).ConfigureAwait(false);
+
         }
 
         /// <summary>
@@ -85,7 +88,6 @@ public FeatureProvider GetProvider()
         /// Gets the feature provider with given domain
         /// </summary>
         /// <param name="domain">An identifier which logically binds clients with providers</param>
-
         /// <returns>A provider associated with the given domain, if domain is empty or doesn't
         /// have a corresponding provider the default provider will be returned</returns>
         public FeatureProvider GetProvider(string domain)
@@ -109,7 +111,6 @@ public FeatureProvider GetProvider(string domain)
         /// assigned to it the default provider will be returned
         /// </summary>
         /// <param name="domain">An identifier which logically binds clients with providers</param>
-
         /// <returns>Metadata assigned to provider</returns>
         public Metadata? GetProviderMetadata(string domain) => this.GetProvider(domain).GetMetadata();
 
@@ -218,6 +219,59 @@ public EvaluationContext GetContext()
             }
         }
 
+        /// <summary>
+        /// Return the transaction context propagator.
+        /// </summary>
+        /// <returns><see cref="ITransactionContextPropagator"/>the registered transaction context propagator</returns>
+        internal ITransactionContextPropagator GetTransactionContextPropagator()
+        {
+            return this._transactionContextPropagator;
+        }
+
+        /// <summary>
+        /// Sets the transaction context propagator.
+        /// </summary>
+        /// <param name="transactionContextPropagator">the transaction context propagator to be registered</param>
+        /// <exception cref="ArgumentNullException">Transaction context propagator cannot be null</exception>
+        public void SetTransactionContextPropagator(ITransactionContextPropagator transactionContextPropagator)
+        {
+            if (transactionContextPropagator == null)
+            {
+                throw new ArgumentNullException(nameof(transactionContextPropagator),
+                    "Transaction context propagator cannot be null");
+            }
+
+            lock (this._transactionContextPropagatorLock)
+            {
+                this._transactionContextPropagator = transactionContextPropagator;
+            }
+        }
+
+        /// <summary>
+        /// Returns the currently defined transaction context using the registered transaction context propagator.
+        /// </summary>
+        /// <returns><see cref="EvaluationContext"/>The current transaction context</returns>
+        public EvaluationContext GetTransactionContext()
+        {
+            return this._transactionContextPropagator.GetTransactionContext();
+        }
+
+        /// <summary>
+        /// Sets the transaction context using the registered transaction context propagator.
+        /// </summary>
+        /// <param name="evaluationContext">The <see cref="EvaluationContext"/> to set</param>
+        /// <exception cref="InvalidOperationException">Transaction context propagator is not set.</exception>
+        /// <exception cref="ArgumentNullException">Evaluation context cannot be null</exception>
+        public void SetTransactionContext(EvaluationContext evaluationContext)
+        {
+            if (evaluationContext == null)
+            {
+                throw new ArgumentNullException(nameof(evaluationContext), "Evaluation context cannot be null");
+            }
+
+            this._transactionContextPropagator.SetTransactionContext(evaluationContext);
+        }
+
         /// <summary>
         /// <para>
         /// Shut down and reset the current status of OpenFeature API.
@@ -234,6 +288,7 @@ public async Task ShutdownAsync()
             {
                 this._evaluationContext = EvaluationContext.Empty;
                 this._hooks.Clear();
+                this._transactionContextPropagator = new NoOpTransactionContextPropagator();
 
                 // TODO: make these lazy to avoid extra allocations on the common cleanup path?
                 this._eventExecutor = new EventExecutor();

src/OpenFeature/AsyncLocalTransactionContextPropagator.cs

@@ -0,0 +1,25 @@
+using System.Threading;
+using OpenFeature.Model;
+
+namespace OpenFeature;
+
+/// <summary>
+///  This is a task transaction context implementation of <see cref="ITransactionContextPropagator"/>
+///  It uses the <see cref="AsyncLocal{T}"/> to store the transaction context.
+/// </summary>
+public sealed class AsyncLocalTransactionContextPropagator : ITransactionContextPropagator
+{
+    private readonly AsyncLocal<EvaluationContext> _transactionContext = new();
+
+    /// <inheritdoc />
+    public EvaluationContext GetTransactionContext()
+    {
+        return this._transactionContext.Value ?? EvaluationContext.Empty;
+    }
+
+    /// <inheritdoc />
+    public void SetTransactionContext(EvaluationContext evaluationContext)
+    {
+        this._transactionContext.Value = evaluationContext;
+    }
+}

src/OpenFeature/Model/ITransactionContextPropagator.cs

@@ -0,0 +1,26 @@
+namespace OpenFeature.Model;
+
+/// <summary>
+/// <see cref="ITransactionContextPropagator"/> is responsible for persisting a transactional context
+/// for the duration of a single transaction.
+/// Examples of potential transaction specific context include: a user id, user agent, IP.
+/// Transaction context is merged with evaluation context prior to flag evaluation.
+/// </summary>
+/// <remarks>
+/// The precedence of merging context can be seen in
+/// <a href="https://openfeature.dev/specification/sections/evaluation-context#requirement-323">the specification</a>.
+/// </remarks>
+public interface ITransactionContextPropagator
+{
+    /// <summary>
+    ///  Returns the currently defined transaction context using the registered transaction context propagator.
+    /// </summary>
+    /// <returns><see cref="EvaluationContext"/>The current transaction context</returns>
+    EvaluationContext GetTransactionContext();
+
+    /// <summary>
+    /// Sets the transaction context.
+    /// </summary>
+    /// <param name="evaluationContext">The transaction context to be set</param>
+    void SetTransactionContext(EvaluationContext evaluationContext);
+}

src/OpenFeature/NoOpTransactionContextPropagator.cs

@@ -0,0 +1,15 @@
+using OpenFeature.Model;
+
+namespace OpenFeature;
+
+internal class NoOpTransactionContextPropagator : ITransactionContextPropagator
+{
+    public EvaluationContext GetTransactionContext()
+    {
+        return EvaluationContext.Empty;
+    }
+
+    public void SetTransactionContext(EvaluationContext evaluationContext)
+    {
+    }
+}

src/OpenFeature/OpenFeatureClient.cs

@@ -215,12 +215,12 @@ private async Task<FlagEvaluationDetails<T>> EvaluateFlagAsync<T>(
             // New up an evaluation context if one was not provided.
             context ??= EvaluationContext.Empty;
 
-            // merge api, client, and invocation context.
-            var evaluationContext = Api.Instance.GetContext();
+            // merge api, client, transaction and invocation context
             var evaluationContextBuilder = EvaluationContext.Builder();
-            evaluationContextBuilder.Merge(evaluationContext);
-            evaluationContextBuilder.Merge(this.GetContext());
-            evaluationContextBuilder.Merge(context);
+            evaluationContextBuilder.Merge(Api.Instance.GetContext()); // API context
+            evaluationContextBuilder.Merge(this.GetContext()); // Client context
+            evaluationContextBuilder.Merge(Api.Instance.GetTransactionContext()); // Transaction context
+            evaluationContextBuilder.Merge(context); // Invocation context
 
             var allHooks = new List<Hook>()
                 .Concat(Api.Instance.GetHooks())

test/OpenFeature.Tests/AsyncLocalTransactionContextPropagatorTests.cs

@@ -0,0 +1,58 @@
+using OpenFeature.Model;
+using Xunit;
+
+namespace OpenFeature.Tests;
+
+public class AsyncLocalTransactionContextPropagatorTests
+{
+    [Fact]
+    public void GetTransactionContext_ReturnsEmpty_WhenNoContextIsSet()
+    {
+        // Arrange
+        var propagator = new AsyncLocalTransactionContextPropagator();
+
+        // Act
+        var context = propagator.GetTransactionContext();
+
+        // Assert
+        Assert.Equal(EvaluationContext.Empty, context);
+    }
+
+    [Fact]
+    public void SetTransactionContext_SetsAndGetsContextCorrectly()
+    {
+        // Arrange
+        var propagator = new AsyncLocalTransactionContextPropagator();
+        var evaluationContext = EvaluationContext.Builder()
+            .Set("initial", "yes")
+            .Build();
+
+        // Act
+        propagator.SetTransactionContext(evaluationContext);
+        var context = propagator.GetTransactionContext();
+
+        // Assert
+        Assert.Equal(evaluationContext, context);
+        Assert.Equal(evaluationContext.GetValue("initial"), context.GetValue("initial"));
+    }
+
+    [Fact]
+    public void SetTransactionContext_OverridesPreviousContext()
+    {
+        // Arrange
+        var propagator = new AsyncLocalTransactionContextPropagator();
+
+        var initialContext = EvaluationContext.Builder()
+            .Set("initial", "yes")
+            .Build();
+        var newContext = EvaluationContext.Empty;
+
+        // Act
+        propagator.SetTransactionContext(initialContext);
+        propagator.SetTransactionContext(newContext);
+        var context = propagator.GetTransactionContext();
+
+        // Assert
+        Assert.Equal(newContext, context);
+    }
+}

test/OpenFeature.Tests/OpenFeatureHookTests.cs

@@ -166,6 +166,9 @@ public async Task Evaluation_Context_Must_Be_Merged_In_Correct_Order()
             var propInvocation = "4.3.4invocation";
             var propInvocationToOverwrite = "4.3.4invocationToOverwrite";
 
+            var propTransaction = "4.3.4transaction";
+            var propTransactionToOverwrite = "4.3.4transactionToOverwrite";
+
             var propHook = "4.3.4hook";
 
             // setup a cascade of overwriting properties
@@ -180,17 +183,29 @@ public async Task Evaluation_Context_Must_Be_Merged_In_Correct_Order()
                 .Set(propClientToOverwrite, false)
                 .Build();
 
+            var transactionContext = new EvaluationContextBuilder()
+                .Set(propTransaction, true)
+                .Set(propInvocationToOverwrite, true)
+                .Set(propTransactionToOverwrite, false)
+                .Build();
+
             var invocationContext = new EvaluationContextBuilder()
                 .Set(propInvocation, true)
                 .Set(propClientToOverwrite, true)
+                .Set(propTransactionToOverwrite, true)
                 .Set(propInvocationToOverwrite, false)
                 .Build();
 
+
             var hookContext = new EvaluationContextBuilder()
                 .Set(propHook, true)
                 .Set(propInvocationToOverwrite, true)
                 .Build();
 
+            var transactionContextPropagator = new AsyncLocalTransactionContextPropagator();
+            transactionContextPropagator.SetTransactionContext(transactionContext);
+            Api.Instance.SetTransactionContextPropagator(transactionContextPropagator);
+
             var provider = Substitute.For<FeatureProvider>();
 
             provider.GetMetadata().Returns(new Metadata(null));
@@ -212,7 +227,9 @@ public async Task Evaluation_Context_Must_Be_Merged_In_Correct_Order()
             _ = provider.Received(1).ResolveBooleanValueAsync(Arg.Any<string>(), Arg.Any<bool>(), Arg.Is<EvaluationContext>(y =>
                 (y.GetValue(propGlobal).AsBoolean ?? false)
                 && (y.GetValue(propClient).AsBoolean ?? false)
+                && (y.GetValue(propTransaction).AsBoolean ?? false)
                 && (y.GetValue(propGlobalToOverwrite).AsBoolean ?? false)
+                && (y.GetValue(propTransactionToOverwrite).AsBoolean ?? false)
                 && (y.GetValue(propInvocation).AsBoolean ?? false)
                 && (y.GetValue(propClientToOverwrite).AsBoolean ?? false)
                 && (y.GetValue(propHook).AsBoolean ?? false)