feat: add transaction context propagation (spec 3.3) (#230)

Signed-off-by: Jose Colella <jose.colella@gusto.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: josecolella

lib/open_feature/sdk.rb

@@ -2,6 +2,8 @@
 
 require_relative "sdk/version"
 require_relative "sdk/api"
+require_relative "sdk/transaction_context_propagator"
+require_relative "sdk/thread_local_transaction_context_propagator"
 
 module OpenFeature
   # TODO: Add documentation

lib/open_feature/sdk/api.rb

@@ -70,6 +70,15 @@ def logger=(new_logger)
         configuration.logger = new_logger
       end
 
+      def set_transaction_context_propagator(propagator)
+        configuration.transaction_context_propagator = propagator
+      end
+
+      def set_transaction_context(evaluation_context)
+        propagator = configuration.transaction_context_propagator
+        propagator&.set_transaction_context(evaluation_context)
+      end
+
       def shutdown
         configuration.shutdown
       end

lib/open_feature/sdk/client.rb

@@ -49,11 +49,7 @@ def remove_handler(event_type, handler = nil, &block)
       def track(tracking_event_name, evaluation_context: nil, tracking_event_details: nil)
         return unless @provider.respond_to?(:track)
 
-        built_context = EvaluationContextBuilder.new.call(
-          api_context: OpenFeature::SDK.evaluation_context,
-          client_context: self.evaluation_context,
-          invocation_context: evaluation_context
-        )
+        built_context = build_evaluation_context(evaluation_context)
 
         @provider.track(tracking_event_name, evaluation_context: built_context, tracking_event_details: tracking_event_details)
       end
@@ -86,11 +82,7 @@ def fetch_details(type:, flag_key:, default_value:, evaluation_context: nil, inv
           end
         end
 
-        built_context = EvaluationContextBuilder.new.call(
-          api_context: OpenFeature::SDK.evaluation_context,
-          client_context: self.evaluation_context,
-          invocation_context: evaluation_context
-        )
+        built_context = build_evaluation_context(evaluation_context)
 
         # Assemble ordered hooks: API → Client → Invocation → Provider (spec 4.4.2)
         provider_hooks = @provider.respond_to?(:hooks) ? Array(@provider.hooks) : []
@@ -148,6 +140,18 @@ def short_circuit_error_code(state)
         end
       end
 
+      def build_evaluation_context(invocation_context)
+        propagator = OpenFeature::SDK.configuration.transaction_context_propagator
+        transaction_context = propagator&.get_transaction_context
+
+        EvaluationContextBuilder.new.call(
+          api_context: OpenFeature::SDK.evaluation_context,
+          transaction_context: transaction_context,
+          client_context: evaluation_context,
+          invocation_context: invocation_context
+        )
+      end
+
       def validate_default_value_type(type, default_value)
         expected_classes = TYPE_CLASS_MAP[type]
         unless expected_classes.any? { |klass| default_value.is_a?(klass) }

lib/open_feature/sdk/configuration.rb

@@ -17,7 +17,7 @@ module SDK
     class Configuration
       extend Forwardable
 
-      attr_accessor :evaluation_context, :hooks
+      attr_accessor :evaluation_context, :hooks, :transaction_context_propagator
       attr_reader :logger
 
       def initialize

lib/open_feature/sdk/evaluation_context_builder.rb

@@ -4,8 +4,8 @@ module OpenFeature
   module SDK
     # Used to combine evaluation contexts from different sources
     class EvaluationContextBuilder
-      def call(api_context:, client_context:, invocation_context:)
-        available_contexts = [api_context, client_context, invocation_context].compact
+      def call(api_context:, client_context:, invocation_context:, transaction_context: nil)
+        available_contexts = [api_context, transaction_context, client_context, invocation_context].compact
 
         return nil if available_contexts.empty?
 

lib/open_feature/sdk/thread_local_transaction_context_propagator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module OpenFeature
+  module SDK
+    class ThreadLocalTransactionContextPropagator
+      include TransactionContextPropagator
+
+      THREAD_KEY = :openfeature_transaction_context
+
+      def set_transaction_context(evaluation_context)
+        Thread.current[THREAD_KEY] = evaluation_context
+      end
+
+      def get_transaction_context
+        Thread.current[THREAD_KEY]
+      end
+    end
+  end
+end

lib/open_feature/sdk/transaction_context_propagator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module OpenFeature
+  module SDK
+    module TransactionContextPropagator
+      def set_transaction_context(evaluation_context)
+        raise NotImplementedError
+      end
+
+      def get_transaction_context
+        raise NotImplementedError
+      end
+    end
+  end
+end

spec/open_feature/sdk/transaction_context_propagator_spec.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe OpenFeature::SDK::ThreadLocalTransactionContextPropagator do
+  subject(:propagator) { described_class.new }
+
+  after do
+    Thread.current[described_class::THREAD_KEY] = nil
+  end
+
+  describe "#set_transaction_context / #get_transaction_context" do
+    it "round-trips an evaluation context" do
+      context = OpenFeature::SDK::EvaluationContext.new(targeting_key: "user-123")
+      propagator.set_transaction_context(context)
+
+      expect(propagator.get_transaction_context).to eq(context)
+    end
+
+    it "returns nil when no context has been set" do
+      expect(propagator.get_transaction_context).to be_nil
+    end
+
+    it "isolates context between threads" do
+      context = OpenFeature::SDK::EvaluationContext.new(targeting_key: "main-thread")
+      propagator.set_transaction_context(context)
+
+      other_thread_context = nil
+      Thread.new { other_thread_context = propagator.get_transaction_context }.join
+
+      expect(other_thread_context).to be_nil
+      expect(propagator.get_transaction_context).to eq(context)
+    end
+  end
+end
+
+RSpec.describe OpenFeature::SDK::TransactionContextPropagator do
+  describe "interface contract" do
+    let(:klass) do
+      Class.new do
+        include OpenFeature::SDK::TransactionContextPropagator
+      end
+    end
+
+    it "raises NotImplementedError for #set_transaction_context" do
+      expect { klass.new.set_transaction_context(nil) }.to raise_error(NotImplementedError)
+    end
+
+    it "raises NotImplementedError for #get_transaction_context" do
+      expect { klass.new.get_transaction_context }.to raise_error(NotImplementedError)
+    end
+  end
+end

spec/specification/evaluation_context_spec.rb

@@ -68,19 +68,93 @@
       end
     end
 
-    # TODO: We currently don't support transaction propogation and hooks
-    # We'll want to fully implement this requirement once those are supported
     specify "Requirement 3.2.3 - Evaluation context MUST be merged in the order: API (global; lowest precedence) -> transaction -> client -> invocation -> before hooks (highest precedence), with duplicate values being overwritten." do
       api_context = OpenFeature::SDK::EvaluationContext.new(targeting_key: "api")
+      transaction_context = OpenFeature::SDK::EvaluationContext.new("targeting_key" => "transaction", "transaction-related" => "field")
       client_context = OpenFeature::SDK::EvaluationContext.new("targeting_key" => "client", "client-related" => "field")
       invocation_context = OpenFeature::SDK::EvaluationContext.new("targeting_key" => "invocation", "invocation-related" => "field")
 
-      OpenFeature::SDK.configure { |c| c.evaluation_context = api_context }
+      propagator = OpenFeature::SDK::ThreadLocalTransactionContextPropagator.new
+      OpenFeature::SDK.configure do |c|
+        c.evaluation_context = api_context
+        c.transaction_context_propagator = propagator
+      end
+      propagator.set_transaction_context(transaction_context)
+
       client = OpenFeature::SDK.build_client(evaluation_context: client_context)
 
-      expect_any_instance_of(OpenFeature::SDK::EvaluationContextBuilder).to receive(:call).with(api_context:, client_context:, invocation_context:).and_call_original
+      expect_any_instance_of(OpenFeature::SDK::EvaluationContextBuilder).to receive(:call).with(
+        api_context: api_context,
+        transaction_context: transaction_context,
+        client_context: client_context,
+        invocation_context: invocation_context
+      ).and_call_original
 
       client.fetch_boolean_value(flag_key: "testing", default_value: true, evaluation_context: invocation_context)
+
+      propagator.set_transaction_context(nil)
+    end
+  end
+
+  context "3.3 Transaction Context Propagation" do
+    after do
+      OpenFeature::SDK.configure { |c| c.transaction_context_propagator = nil }
+    end
+
+    context "Requirement 3.3.1.1" do
+      specify "The API SHOULD have a method for setting a transaction context propagator." do
+        propagator = OpenFeature::SDK::ThreadLocalTransactionContextPropagator.new
+        OpenFeature::SDK.set_transaction_context_propagator(propagator)
+
+        expect(OpenFeature::SDK.configuration.transaction_context_propagator).to eq(propagator)
+      end
+    end
+
+    context "Condition 3.3.1.2 - A transaction context propagator is configured." do
+      let(:propagator) { OpenFeature::SDK::ThreadLocalTransactionContextPropagator.new }
+
+      before do
+        OpenFeature::SDK.set_transaction_context_propagator(propagator)
+      end
+
+      context "Conditional Requirement 3.3.1.2.1" do
+        specify "The API MUST have a method for setting the evaluation context of the transaction context propagator for the current transaction." do
+          context = OpenFeature::SDK::EvaluationContext.new(targeting_key: "txn-user")
+          OpenFeature::SDK.set_transaction_context(context)
+
+          expect(propagator.get_transaction_context).to eq(context)
+
+          propagator.set_transaction_context(nil)
+        end
+      end
+    end
+
+    context "Requirement 3.3.1.2.2" do
+      specify "A transaction context propagator MUST have a method for setting the evaluation context of the current transaction." do
+        propagator = OpenFeature::SDK::ThreadLocalTransactionContextPropagator.new
+        context = OpenFeature::SDK::EvaluationContext.new(targeting_key: "txn-user")
+
+        propagator.set_transaction_context(context)
+
+        expect(propagator.get_transaction_context).to eq(context)
+
+        propagator.set_transaction_context(nil)
+      end
+    end
+
+    context "Requirement 3.3.1.2.3" do
+      specify "A transaction context propagator MUST have a method for getting the evaluation context of the current transaction." do
+        propagator = OpenFeature::SDK::ThreadLocalTransactionContextPropagator.new
+
+        expect(propagator.get_transaction_context).to be_nil
+
+        context = OpenFeature::SDK::EvaluationContext.new(targeting_key: "txn-user")
+        propagator.set_transaction_context(context)
+
+        expect(propagator.get_transaction_context).to eq(context)
+
+        propagator.set_transaction_context(nil)
+      end
     end
   end
 end