feat!: replace getter and setter callables and remove rack specific propagators (#589)

* feat: introduce Getter class with keys; remove default getter callable

* refactor: remove propagation.http/text; use getter instead

* feat: add TextMapSetter; replace setter callable

* refactor: remove rack extractors

* refactor: use TextMapSetter in Propagator and CompositePropagator

* docs: cleanup pass through documentation

* Update api/test/opentelemetry/context/propagation/rack_env_getter_test.rb

Co-authored-by: Francis Bogsanyi <[email protected]>

* refactor: use kwargs for Propagator#inject / extract

Co-authored-by: Francis Bogsanyi <[email protected]>

Author: mwear

api/lib/opentelemetry.rb

@@ -22,7 +22,8 @@
 module OpenTelemetry
   extend self
 
-  attr_writer :tracer_provider, :meter_provider, :baggage, :logger, :error_handler
+  attr_writer :tracer_provider, :meter_provider, :propagation, :baggage,
+              :logger, :error_handler
 
   # @return [Object, Logger] configured Logger or a default STDOUT Logger.
   def logger
@@ -68,8 +69,11 @@ def baggage
     @baggage ||= Baggage::Manager.new
   end
 
-  # @return [Context::Propagation::Propagation] an instance of the propagation API
+  # @return [Context::Propagation::Propagator] a propagator instance
   def propagation
-    @propagation ||= Context::Propagation::Propagation.new
+    @propagation ||= Context::Propagation::Propagator.new(
+      Context::Propagation::NoopInjector.new,
+      Context::Propagation::NoopExtractor.new
+    )
   end
 end

api/lib/opentelemetry/baggage/propagation.rb

@@ -15,17 +15,11 @@ module Baggage
     module Propagation
       extend self
 
+      BAGGAGE_KEY = 'baggage'
       TEXT_MAP_EXTRACTOR = TextMapExtractor.new
       TEXT_MAP_INJECTOR = TextMapInjector.new
-      RACK_EXTRACTOR = TextMapExtractor.new(
-        baggage_key: 'HTTP_BAGGAGE'
-      )
-      RACK_INJECTOR = TextMapInjector.new(
-        baggage_key: 'HTTP_BAGGAGE'
-      )
 
-      private_constant :TEXT_MAP_INJECTOR, :TEXT_MAP_EXTRACTOR, :RACK_INJECTOR,
-                       :RACK_EXTRACTOR
+      private_constant :BAGGAGE_KEY, :TEXT_MAP_INJECTOR, :TEXT_MAP_EXTRACTOR
 
       # Returns an extractor that extracts context using the W3C Baggage
       # format
@@ -38,20 +32,6 @@ def text_map_injector
       def text_map_extractor
         TEXT_MAP_EXTRACTOR
       end
-
-      # Returns an extractor that extracts context using the W3C Baggage
-      # format with Rack normalized keys (upcased and prefixed with
-      # HTTP_)
-      def rack_injector
-        RACK_INJECTOR
-      end
-
-      # Returns an injector that injects context using the W3C Baggage
-      # format with Rack normalized keys (upcased and prefixed with
-      # HTTP_)
-      def rack_extractor
-        RACK_EXTRACTOR
-      end
     end
   end
 end

api/lib/opentelemetry/baggage/propagation/text_map_extractor.rb

@@ -11,33 +11,30 @@ module Baggage
     module Propagation
       # Extracts baggage from carriers in the W3C Baggage format
       class TextMapExtractor
-        include Context::Propagation::DefaultGetter
-
         # Returns a new TextMapExtractor that extracts context using the specified
-        # header key
+        # getter
         #
-        # @param [String] baggage_key The baggage header
-        #   key used in the carrier
+        # @param [optional Getter] default_getter The default getter used to read
+        #   headers from a carrier during extract. Defaults to a
+        #   {OpenTelemetry::Context::Propagation::TextMapGetter} instance.
         # @return [TextMapExtractor]
-        def initialize(baggage_key: 'baggage')
-          @baggage_key = baggage_key
+        def initialize(default_getter = Context::Propagation.text_map_getter)
+          @default_getter = default_getter
         end
 
         # Extract remote baggage from the supplied carrier.
         # If extraction fails, the original context will be returned
         #
         # @param [Carrier] carrier The carrier to get the header from
         # @param [Context] context The context to be updated with extracted baggage
-        # @param [optional Callable] getter An optional callable that takes a carrier and a key and
-        #   returns the value associated with the key. If omitted the default getter will be used
-        #   which expects the carrier to respond to [] and []=.
-        # @yield [Carrier, String] if an optional getter is provided, extract will yield the carrier
-        #   and the header key to the getter.
+        # @param [optional Getter] getter If the optional getter is provided, it
+        #   will be used to read the header from the carrier, otherwise the default
+        #   getter will be used.
         # @return [Context] context updated with extracted baggage, or the original context
         #   if extraction fails
-        def extract(carrier, context, &getter)
-          getter ||= default_getter
-          header = getter.call(carrier, @baggage_key)
+        def extract(carrier, context, getter = nil)
+          getter ||= @default_getter
+          header = getter.get(carrier, BAGGAGE_KEY)
 
           entries = header.gsub(/\s/, '').split(',')
 

api/lib/opentelemetry/baggage/propagation/text_map_injector.rb

@@ -11,33 +11,30 @@ module Baggage
     module Propagation
       # Injects baggage using the W3C Baggage format
       class TextMapInjector
-        include Context::Propagation::DefaultSetter
-
         # Returns a new TextMapInjector that injects context using the specified
-        # header key
+        # setter
         #
-        # @param [String] baggage_key The baggage header
-        #   key used in the carrier
+        # @param [optional Setter] default_setter The default setter used to
+        #   write context into a carrier during inject. Defaults to a
+        #   {OpenTelemetry::Context::Propagation::TextMapSetter} instance.
         # @return [TextMapInjector]
-        def initialize(baggage_key: 'baggage')
-          @baggage_key = baggage_key
+        def initialize(default_setter = Context::Propagation.text_map_setter)
+          @default_setter = default_setter
         end
 
         # Inject in-process baggage into the supplied carrier.
         #
         # @param [Carrier] carrier The carrier to inject baggage into
         # @param [Context] context The context to read baggage from
-        # @param [optional Callable] getter An optional callable that takes a carrier and a key and
-        #   returns the value associated with the key. If omitted the default getter will be used
-        #   which expects the carrier to respond to [] and []=.
-        # @yield [Carrier, String] if an optional getter is provided, inject will yield the carrier
-        #   and the header key to the getter.
+        # @param [optional Setter] setter If the optional setter is provided, it
+        #   will be used to write context into the carrier, otherwise the default
+        #   setter will be used.
         # @return [Object] carrier with injected baggage
-        def inject(carrier, context, &setter)
+        def inject(carrier, context, setter = nil)
           return carrier unless (baggage = context[ContextKeys.baggage_key]) && !baggage.empty?
 
-          setter ||= default_setter
-          setter.call(carrier, @baggage_key, encode(baggage))
+          setter ||= @default_setter
+          setter.set(carrier, BAGGAGE_KEY, encode(baggage))
 
           carrier
         end

api/lib/opentelemetry/context/propagation.rb

@@ -5,18 +5,43 @@
 # SPDX-License-Identifier: Apache-2.0
 
 require 'opentelemetry/context/propagation/composite_propagator'
-require 'opentelemetry/context/propagation/default_getter'
-require 'opentelemetry/context/propagation/default_setter'
 require 'opentelemetry/context/propagation/noop_extractor'
 require 'opentelemetry/context/propagation/noop_injector'
-require 'opentelemetry/context/propagation/propagation'
 require 'opentelemetry/context/propagation/propagator'
+require 'opentelemetry/context/propagation/text_map_getter'
+require 'opentelemetry/context/propagation/text_map_setter'
+require 'opentelemetry/context/propagation/rack_env_getter'
 
 module OpenTelemetry
   class Context
     # The propagation module contains APIs and utilities to interact with context
     # and propagate across process boundaries.
     module Propagation
+      extend self
+
+      TEXT_MAP_GETTER = TextMapGetter.new
+      TEXT_MAP_SETTER = TextMapSetter.new
+      RACK_ENV_GETTER = RackEnvGetter.new
+
+      private_constant :TEXT_MAP_GETTER, :TEXT_MAP_SETTER, :RACK_ENV_GETTER
+
+      # Returns a {TextMapGetter} instance suitable for reading values from a
+      # hash-like carrier
+      def text_map_getter
+        TEXT_MAP_GETTER
+      end
+
+      # Returns a {TextMapSetter} instance suitable for writing values into a
+      # hash-like carrier
+      def text_map_setter
+        TEXT_MAP_SETTER
+      end
+
+      # Returns a {RackEnvGetter} instance suitable for reading values from a
+      # Rack environment.
+      def rack_env_getter
+        RACK_ENV_GETTER
+      end
     end
   end
 end

api/lib/opentelemetry/context/propagation/composite_propagator.rb

@@ -30,15 +30,14 @@ def initialize(injectors, extractors)
         #   context into
         # @param [optional Context] context Context to be injected into carrier.
         #   Defaults to +Context.current+
-        # @param [optional Callable] setter An optional callable that takes a
-        #   carrier, a key and a value and assigns the key-value pair in the
-        #   carrier. If omitted the default setter will be used which expects
-        #   the carrier to respond to [] and []=.
+        # @param [optional Setter] setter If the optional setter is provided, it
+        #   will be used to write context into the carrier, otherwise the default
+        #   setter will be used.
         #
         # @return [Object] carrier
-        def inject(carrier, context = Context.current, &setter)
+        def inject(carrier, context: Context.current, setter: Context::Propagation.text_map_setter)
           @injectors.inject(carrier) do |memo, injector|
-            injector.inject(memo, context, &setter)
+            injector.inject(memo, context, setter)
           rescue => e # rubocop:disable Style/RescueStandardError
             OpenTelemetry.logger.warn "Error in CompositePropagator#inject #{e.message}"
             carrier
@@ -53,15 +52,15 @@ def inject(carrier, context = Context.current, &setter)
         # @param [Object] carrier The carrier to extract context from
         # @param [optional Context] context Context to be updated with the state
         #   extracted from the carrier. Defaults to +Context.current+
-        # @param [optional Callable] getter An optional callable that takes a carrier and a key and
-        #   returns the value associated with the key. If omitted the default getter will be used
-        #   which expects the carrier to respond to [] and []=.
+        # @param [optional Getter] getter If the optional getter is provided, it
+        #   will be used to read the header from the carrier, otherwise the default
+        #   getter will be used.
         #
         # @return [Context] a new context updated with state extracted from the
         #   carrier
-        def extract(carrier, context = Context.current, &getter)
+        def extract(carrier, context: Context.current, getter: Context::Propagation.text_map_getter)
           @extractors.inject(context) do |ctx, extractor|
-            extractor.extract(carrier, ctx, &getter)
+            extractor.extract(carrier, ctx, getter)
           rescue => e # rubocop:disable Style/RescueStandardError
             OpenTelemetry.logger.warn "Error in CompositePropagator#extract #{e.message}"
             ctx

api/lib/opentelemetry/context/propagation/default_getter.rb

@@ -17,7 +17,7 @@ class NoopExtractor
         # @param [optional Callable] getter An optional callable that takes a carrier and a key and
         #   and returns the value associated with the key
         # @return [Context]
-        def extract(carrier, context, &getter)
+        def extract(carrier, context, getter = nil)
           context
         end
       end