datadog 2.21.0 → 2.38.0

data/lib/datadog/core/transport/http.rb

@@ -4,6 +4,8 @@ require_relative 'http/builder'
 require_relative 'http/adapters/net'
 require_relative 'http/adapters/unix_socket'
 require_relative 'http/adapters/test'
+require_relative '../environment/container'
+require_relative '../environment/ext'
 
 module Datadog
   module Core
@@ -12,16 +14,16 @@ module Datadog
       module HTTP
         # Add adapters to registry
         Builder::REGISTRY.set(
-          Transport::HTTP::Adapters::Net,
+          Core::Transport::HTTP::Adapters::Net,
           Core::Configuration::Ext::Agent::HTTP::ADAPTER
         )
         Builder::REGISTRY.set(
-          Transport::HTTP::Adapters::Test,
-          Transport::Ext::Test::ADAPTER
+          Core::Transport::HTTP::Adapters::Test,
+          Core::Transport::Ext::Test::ADAPTER
         )
         Builder::REGISTRY.set(
-          Transport::HTTP::Adapters::UnixSocket,
-          Transport::Ext::UnixSocket::ADAPTER
+          Core::Transport::HTTP::Adapters::UnixSocket,
+          Core::Transport::Ext::UnixSocket::ADAPTER
         )
 
         module_function
@@ -29,8 +31,13 @@ module Datadog
         # Helper function that delegates to Builder.new
         # but is under HTTP namespace so that client code requires this file
         # to get the adapters configured, and not the builder directly.
-        def build(api_instance_class:, agent_settings:, logger: Datadog.logger, api_version: nil, headers: nil, &block)
-          Builder.new(api_instance_class: api_instance_class, logger: logger) do |transport|
+        def build(
+          agent_settings:,
+          logger: Datadog.logger,
+          headers: nil,
+          &block
+        )
+          Builder.new(logger: logger) do |transport|
             transport.adapter(agent_settings)
             transport.headers(default_headers)
 
@@ -38,34 +45,32 @@ module Datadog
             yield transport
 
             # Apply any settings given by options
-            transport.default_api = api_version if api_version
             transport.headers(headers) if headers
           end
         end
 
         def default_headers
           {
-            Datadog::Core::Transport::Ext::HTTP::HEADER_CLIENT_COMPUTED_TOP_LEVEL => '1',
-            Datadog::Core::Transport::Ext::HTTP::HEADER_META_LANG =>
+            Core::Transport::Ext::HTTP::HEADER_CLIENT_COMPUTED_TOP_LEVEL => '1',
+            Core::Transport::Ext::HTTP::HEADER_META_LANG =>
               Datadog::Core::Environment::Ext::LANG,
-            Datadog::Core::Transport::Ext::HTTP::HEADER_META_LANG_VERSION =>
+            Core::Transport::Ext::HTTP::HEADER_META_LANG_VERSION =>
               Datadog::Core::Environment::Ext::LANG_VERSION,
-            Datadog::Core::Transport::Ext::HTTP::HEADER_META_LANG_INTERPRETER =>
+            Core::Transport::Ext::HTTP::HEADER_META_LANG_INTERPRETER =>
               Datadog::Core::Environment::Ext::LANG_INTERPRETER,
-            Datadog::Core::Transport::Ext::HTTP::HEADER_META_LANG_INTERPRETER_VENDOR =>
+            Core::Transport::Ext::HTTP::HEADER_META_LANG_INTERPRETER_VENDOR =>
               Core::Environment::Ext::LANG_ENGINE,
-            Datadog::Core::Transport::Ext::HTTP::HEADER_META_TRACER_VERSION =>
+            Core::Transport::Ext::HTTP::HEADER_META_TRACER_VERSION =>
               Datadog::Core::Environment::Ext::GEM_DATADOG_VERSION
           }.tap do |headers|
-            # Add container ID, if present.
-            if (container_id = Datadog::Core::Environment::Container.container_id)
-              headers[Datadog::Core::Transport::Ext::HTTP::HEADER_CONTAINER_ID] = container_id
-            end
+            # Add application container info
+            headers.merge!(Core::Environment::Container.to_headers)
+
             # TODO: inject configuration rather than reading from global here
             unless Datadog.configuration.apm.tracing.enabled
               # Sending this header to the agent will disable metrics computation (and billing) on the agent side
               # by pretending it has already been done on the library side.
-              headers[Datadog::Core::Transport::Ext::HTTP::HEADER_CLIENT_COMPUTED_STATS] = 'yes'
+              headers[Core::Transport::Ext::HTTP::HEADER_CLIENT_COMPUTED_STATS] = 'yes'
             end
           end
         end

data/lib/datadog/core/transport/parcel.rb

@@ -3,19 +3,71 @@
 module Datadog
   module Core
     module Transport
-      # Data transfer object for generic data
-      # @abstract
-      module Parcel
-        attr_reader \
-          :data
-
-        def initialize(data)
+      # Data transfer object for transporting already-encoded data.
+      #
+      # A Parcel is a container that holds pre-encoded data along with metadata
+      # about its encoding. The key design principle is that encoding happens
+      # BEFORE the Parcel is created, not inside it.
+      #
+      # @example Creating a Parcel with JSON data
+      #   encoder = Core::Encoding::JSONEncoder
+      #   parcel = Parcel.new(
+      #     encoder.encode(payload),
+      #     content_type: encoder.content_type,
+      #   )
+      #
+      # @example Creating a Parcel with compressed MessagePack data
+      #   msgpack_data = MessagePack.pack(payload)
+      #   compressed_data = Zlib.gzip(msgpack_data)
+      #   parcel = Parcel.new(
+      #     compressed_data,
+      #     content_type: 'application/msgpack',
+      #     content_encoding: 'gzip',
+      #   )
+      #
+      # @example Accessing Parcel data in HTTP transport
+      #   # In HTTP adapters, Parcel metadata maps to HTTP headers:
+      #   env.headers['Content-Type'] = request.parcel.content_type
+      #   env.headers['Content-Encoding'] = request.parcel.content_encoding
+      #   env.body = request.parcel.data
+      #
+      # The content_type and content_encoding fields are optional but recommended:
+      # - Set them when creating the Parcel for automatic header management
+      # - Leave them nil for IO transports or when headers are managed elsewhere
+      # - HTTP transports use these to set appropriate request headers
+      #
+      # @see Core::Encoding::JSONEncoder for JSON encoding utilities
+      # @see Core::Transport::Request which wraps Parcels for transmission
+      class Parcel
+        # Creates a new Parcel with pre-encoded data.
+        #
+        # @param data [String] The already-encoded data (e.g., JSON string, MessagePack bytes)
+        # @param content_type [String, nil] MIME type of the data (e.g., 'application/json')
+        # @param content_encoding [String, nil] Encoding applied to data (e.g., 'gzip')
+        def initialize(data, content_type: nil, content_encoding: nil)
           @data = data
+          @content_type = content_type
+          @content_encoding = content_encoding
         end
 
-        def encode_with(encoder)
-          raise NotImplementedError
+        # @!attribute [r] data
+        #   @return [String] The encoded data payload
+        attr_reader :data
+
+        # Returns the length of the encoded data.
+        #
+        # @return [Integer] Number of bytes in the data
+        def length
+          data.length
         end
+
+        # @!attribute [r] content_type
+        #   @return [String, nil] MIME type of the data (e.g., 'application/json')
+        attr_reader :content_type
+
+        # @!attribute [r] content_encoding
+        #   @return [String, nil] Encoding applied to data (e.g., 'gzip')
+        attr_reader :content_encoding
       end
     end
   end

data/lib/datadog/core/transport/response.rb

@@ -34,7 +34,21 @@ module Datadog
         end
 
         def inspect
-          "#{self.class} ok?:#{ok?} unsupported?:#{unsupported?}, " \
+          maybe_code = if respond_to?(:code)
+            # Steep: `code` method may be defined by classes extending this module.
+            # There seem to be no annotation for this.
+            " code:#{code}," # steep:ignore NoMethod
+          end
+          payload = self.payload
+          # Truncation thresholds are arbitrary but we need to truncate the
+          # payload here because outputting multi-MB request body to the
+          # log is not useful.
+          #
+          # Note that payload can be nil here.
+          if payload && payload.length > 2000 # steep:ignore
+            payload = Utils::Truncation.truncate_in_middle(payload, 1500, 500) # steep:ignore
+          end
+          "#{self.class} ok?:#{ok?},#{maybe_code} unsupported?:#{unsupported?}, " \
             "not_found?:#{not_found?}, client_error?:#{client_error?}, " \
             "server_error?:#{server_error?}, internal_error?:#{internal_error?}, " \
             "payload:#{payload}"
@@ -56,7 +70,7 @@ module Datadog
         end
 
         def to_s
-          "#{super}, error_type:#{error.class} error:#{error}"
+          "#{self.class}, error_type:#{error.class} error:#{error}"
         end
 
         def inspect

data/lib/datadog/core/transport/transport.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative 'http/client'
+
+module Datadog
+  module Core
+    module Transport
+      # Raised when configured with an unknown API version
+      class UnknownApiVersionError < StandardError
+        attr_reader :version
+
+        def initialize(version)
+          super
+
+          @version = version
+        end
+
+        def message
+          "No matching transport API for version #{version}!"
+        end
+      end
+
+      # Raised when the API verson to downgrade to does not map to a
+      # defined API.
+      class NoDowngradeAvailableError < StandardError
+        attr_reader :version
+
+        def initialize(version)
+          super
+
+          @version = version
+        end
+
+        def message
+          "No downgrade from transport API version #{version} is available!"
+        end
+      end
+
+      # Base class for transports.
+      class Transport
+        attr_reader :client, :apis, :default_api, :current_api_id, :logger
+
+        class << self
+          # The HTTP client class to use for requests, derived from
+          # Core::Transport::HTTP::Client.
+          #
+          # Important: this attribute is NOT inherited by derived classes -
+          # it must be set by every Transport class that wants to have a
+          # non-default HTTP::Client instance.
+          attr_accessor :http_client_class
+        end
+
+        def initialize(apis, default_api, logger:)
+          @apis = apis
+          @default_api = default_api
+          @logger = logger
+
+          set_api!(default_api)
+        end
+
+        def current_api
+          apis[current_api_id]
+        end
+
+        private
+
+        def set_api!(api_id)
+          raise UnknownApiVersionError, api_id unless apis.key?(api_id)
+
+          @current_api_id = api_id
+          client_class = self.class.http_client_class || Core::Transport::HTTP::Client
+          @client = client_class.new(current_api, logger: logger) # steep:ignore
+        end
+
+        def downgrade?(response)
+          return false unless apis.fallbacks.key?(current_api_id)
+
+          response.not_found? || response.unsupported?
+        end
+
+        def downgrade!
+          downgrade_api_id = apis.fallbacks[current_api_id]
+          raise NoDowngradeAvailableError, current_api_id if downgrade_api_id.nil?
+
+          set_api!(downgrade_api_id)
+        end
+      end
+    end
+  end
+end

data/lib/datadog/core/utils/at_fork_monkey_patch.rb

@@ -6,7 +6,7 @@ module Datadog
       # Monkey patches `Kernel#fork` and similar functions, adding an `at_fork` callback mechanism which
       # is used to restart observability after the VM forks (e.g. in multiprocess Ruby apps).
       module AtForkMonkeyPatch
-        AT_FORK_CHILD_BLOCKS = [] # rubocop:disable Style/MutableConstant Used to store blocks to run, mutable by design.
+        AT_FORK_CHILD_BLOCKS = [] # rubocop:disable Style/MutableConstant -- Used to store blocks to run, mutable by design.
         private_constant :AT_FORK_CHILD_BLOCKS
 
         def self.supported?
@@ -16,7 +16,7 @@ module Datadog
         def self.apply!
           return false unless supported?
 
-          if RUBY_VERSION < '3.1'
+          if RubyVersion.is?('< 3.1')
             [
               ::Process.singleton_class, # Process.fork
               ::Kernel.singleton_class,  # Kernel.fork

data/lib/datadog/core/utils/{base64.rb → base64_codec.rb}

@@ -3,8 +3,9 @@
 module Datadog
   module Core
     module Utils
-      # Helper methods for encoding and decoding base64
-      module Base64
+      # Base64 encoding/decoding without using the `base64` gem,
+      # which is no longer a default gem since Ruby 3.4.
+      module Base64Codec
         def self.encode64(bin)
           [bin].pack('m')
         end
@@ -14,7 +15,7 @@ module Datadog
         end
 
         def self.strict_decode64(str)
-          str.unpack1('m0')
+          str.unpack1('m0') #: String # 'm0' format always returns a String
         end
       end
     end

data/lib/datadog/core/utils/enumerable_compat.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Datadog
+  module Core
+    module Utils
+      # Bring newer Enumerable methods to older Ruby versions.
+      module EnumerableCompat
+        def self.filter_map(array, &block)
+          if array.respond_to?(:filter_map)
+            # DEV Supported since Ruby 2.7, saves an intermediate object creation
+            array.filter_map(&block)
+          elsif array.is_a?(Enumerator::Lazy)
+            # You would think that .compact would work here, but it does not:
+            # the result of .map could be an Enumerator::Lazy instance which
+            # does not implement #compact on Ruby 2.5/2.6.
+            array.map(&block).reject do |item|
+              item.nil?
+            end
+          else
+            array.each_with_object([]) do |item, memo|
+              new_item = block.call(item)
+              memo.push(new_item) unless new_item.nil?
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/core/utils/fnv.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Datadog
+  module Core
+    module Utils
+      module FNV
+        # FNV-1a 64-bit non-cryptographic hash function.
+        # @see https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function#FNV-1a_hash Algorithm
+        # @see https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function#FNV_hash_parameters Prime and Offset Basis
+
+        FNV_OFFSET_BASIS = 14695981039346656037
+        FNV_PRIME = 1099511628211
+        FNV_64_BIT_MASK = 0xFFFFFFFFFFFFFFFF
+
+        def self.fnv1_64(data)
+          hash_value = FNV_OFFSET_BASIS
+          data.each_byte do |byte|
+            hash_value ^= byte
+            hash_value = (hash_value * FNV_PRIME) & FNV_64_BIT_MASK
+          end
+          hash_value
+        end
+      end
+    end
+  end
+end

data/lib/datadog/core/utils/forking.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../../ruby_version'
+
 module Datadog
   module Core
     module Utils
@@ -45,7 +47,7 @@ module Datadog
           # object will cause forking to not be detected in the fork when it should have.
           #
           # This wrapper prevents this by initializing the fork PID when the object is created.
-          if RUBY_VERSION >= '3'
+          if RubyVersion.is?('>= 3')
             def initialize(*args, **kwargs, &block)
               super
               update_fork_pid!

data/lib/datadog/core/utils/hash.rb

@@ -3,30 +3,7 @@
 module Datadog
   module Core
     module Utils
-      # Refinements for {Hash}.
       module Hash
-        # This refinement ensures modern rubies are allowed to use newer,
-        # simpler, and more performant APIs.
-        module Refinement
-          # Introduced in Ruby 2.4
-          unless ::Hash.method_defined?(:compact)
-            refine ::Hash do
-              def compact
-                reject { |_k, v| v.nil? }
-              end
-            end
-          end
-
-          # Introduced in Ruby 2.4
-          unless ::Hash.method_defined?(:compact!)
-            refine ::Hash do
-              def compact!
-                reject! { |_k, v| v.nil? }
-              end
-            end
-          end
-        end
-
         # A minimal {Hash} wrapper that provides case-insensitive access
         # to hash keys, without the overhead of copying the original hash.
         #

data/lib/datadog/{appsec/api_security → core/utils}/lru_cache.rb

@@ -3,13 +3,13 @@
 require 'forwardable'
 
 module Datadog
-  module AppSec
-    module APISecurity
+  module Core
+    module Utils
       # An LRU (Least Recently Used) cache implementation that relies on the
       # Ruby 1.9+ `Hash` implementation that guarantees insertion order.
       #
       # WARNING: This implementation is NOT thread-safe and should be used
-      #          in a single-threaded context.
+      #          in a single-threaded context or guarded by Mutex.
       class LRUCache
         extend Forwardable
 
@@ -30,25 +30,14 @@ module Datadog
           end
         end
 
-        def store(key, value)
-          return @store[key] = value if @store.delete(key)
-
-          # NOTE: evict the oldest entry if store reached the maximum allowed size
-          @store.shift if @store.size >= @max_size
-          @store[key] = value
-        end
-
-        # NOTE: If the key exists, it's moved to the end of the list and
-        #       if does not, the given block will be executed and the result
-        #       will be stored (which will add it to the end of the list).
-        def fetch_or_store(key)
-          if (entry = @store.delete(key))
-            return @store[key] = entry
+        def []=(key, value)
+          if @store.delete(key)
+            @store[key] = value
+          else
+            # NOTE: evict the oldest entry if store reached the maximum allowed size
+            @store.shift if @store.size >= @max_size
+            @store[key] = value
           end
-
-          # NOTE: evict the oldest entry if store reached the maximum allowed size
-          @store.shift if @store.size >= @max_size
-          @store[key] = yield
         end
       end
     end

data/lib/datadog/core/utils/network.rb

@@ -13,6 +13,7 @@ module Datadog
           true-client-ip
           x-client-ip
           x-forwarded
+          forwarded
           forwarded-for
           x-cluster-client-ip
           fastly-client-ip
@@ -20,6 +21,8 @@ module Datadog
           cf-connecting-ipv6
         ].freeze
 
+        CGNAT_IP_RANGE = IPAddr.new('100.64.0.0/10')
+
         class << self
           # Returns a client IP associated with the request if it was
           #   retrieved successfully.
@@ -73,6 +76,8 @@ module Datadog
               next unless value
 
               ips = value.split(',')
+              ips = process_forwarded_header_values(ips) if name == 'forwarded'
+
               ips.each do |ip|
                 parsed_ip = ip_to_ipaddr(ip.strip)
 
@@ -83,6 +88,22 @@ module Datadog
             nil
           end
 
+          def process_forwarded_header_values(values)
+            values.each_with_object([]) do |value, acc|
+              value.downcase!
+
+              value.split(';').each do |tuple_str|
+                tuple_str.strip!
+                next unless tuple_str.start_with?('for=')
+
+                tuple_str.delete_prefix!('for=')
+                tuple_str.delete!('"')
+
+                acc << tuple_str
+              end
+            end
+          end
+
           # Returns whether the given value is more likely to be an IPv4 than an IPv6 address.
           #
           # This is done by checking if a dot (`'.'`) character appears before a colon (`':'`) in the value.
@@ -112,7 +133,7 @@ module Datadog
           end
 
           def global_ip?(parsed_ip)
-            parsed_ip && !parsed_ip.private? && !parsed_ip.loopback? && !parsed_ip.link_local?
+            parsed_ip && !parsed_ip.private? && !parsed_ip.loopback? && !parsed_ip.link_local? && !CGNAT_IP_RANGE.include?(parsed_ip)
           end
         end
       end

data/lib/datadog/core/utils/only_once.rb

@@ -3,7 +3,7 @@
 module Datadog
   module Core
     module Utils
-      # Helper class to execute something only once such as not repeating warning logs, and instrumenting classes
+      # Helper class to execute something only once, such as not repeating warning logs and instrumenting classes
       # only once.
       #
       # Thread-safe when used correctly (e.g. be careful of races when lazily initializing instances of this class).

data/lib/datadog/core/utils/only_once_successful.rb

@@ -29,7 +29,11 @@ module Datadog
       # In https://github.com/DataDog/dd-trace-rb/pull/1398#issuecomment-797378810 we have a discussion of alternatives,
       # including an alternative implementation that is Ractor-safe once spent.
       class OnlyOnceSuccessful < OnlyOnce
-        def initialize(limit = 0)
+        def initialize(limit = nil)
+          if limit && limit <= 0
+            raise ArgumentError, "Limit must be a positive integer if provided: #{limit}"
+          end
+
           super()
 
           @limit = limit
@@ -63,7 +67,9 @@ module Datadog
 
         private
 
+        # Use this method only after checking that limit is not nil.
         def check_limit!
+          # @type ivar @limit: Integer
           if @retries >= @limit
             @failed = true
             @ran_once = true
@@ -71,7 +77,7 @@ module Datadog
         end
 
         def limited?
-          !@limit.nil? && @limit.positive?
+          !@limit.nil?
         end
 
         def reset_ran_once_state_for_tests

data/lib/datadog/core/utils/safe_dup.rb

@@ -5,8 +5,8 @@ module Datadog
     module Utils
       # Helper methods for safer dup
       module SafeDup
-        # String#+@ was introduced in Ruby 2.3
-        def self.frozen_or_dup(v)
+        # Steep: https://github.com/soutaro/steep/issues/2001
+        def self.frozen_or_dup(v) # steep:ignore MethodBodyTypeMismatch
           # For the case of a String we use the methods +@ and -@.
           # Those methods are only for String objects
           # they are faster and chepaer on the memory side.

data/lib/datadog/core/utils/sequence.rb

@@ -12,6 +12,8 @@ module Datadog
         end
 
         def next
+          # Steep: https://github.com/soutaro/steep/issues/477
+          # @type ivar @next_item: ^(::Integer) -> Integer
           next_item = @next_item ? @next_item.call(@current) : @current
           @current += 1
           next_item