datadog 2.28.0 → 2.41.0

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

@@ -70,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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative 'http/client'
+require_relative "http/client"
 
 module Datadog
   module Core
@@ -69,7 +69,7 @@ module Datadog
 
           @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
+          @client = client_class.new(current_api, logger: logger)
         end
 
         def downgrade?(response)

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

@@ -6,8 +6,30 @@ 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.
-        private_constant :AT_FORK_CHILD_BLOCKS
+        class Callback
+          attr_reader :block, :group
+
+          def initialize(block, group = nil)
+            @block = block
+            @group = group
+            freeze
+          end
+        end
+        private_constant :Callback
+
+        EMPTY_AT_FORK_BLOCKS = {
+          before: [].freeze,
+          parent: [].freeze,
+          child: [].freeze,
+        }.freeze
+        private_constant :EMPTY_AT_FORK_BLOCKS
+
+        @at_fork_blocks = EMPTY_AT_FORK_BLOCKS
+
+        # Serializes copy-on-write registry updates. Fork dispatch only reads the
+        # latest immutable registry reference and never acquires this mutex.
+        AT_FORK_REGISTRY_MUTEX = Mutex.new
+        private_constant :AT_FORK_REGISTRY_MUTEX
 
         def self.supported?
           Process.respond_to?(:fork)
@@ -16,7 +38,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
@@ -31,43 +53,147 @@ module Datadog
           true
         end
 
-        def self.run_at_fork_blocks(stage)
-          raise(ArgumentError, "Unsupported stage #{stage}") unless stage == :child
+        # Runs the callbacks copied for one fork lifecycle. Before callbacks
+        # stop at the first failure; parent and child callbacks all run before
+        # the first failure is re-raised.
+        def self.run_at_fork_blocks(stage, snapshot:, started: nil)
+          callbacks = blocks_for(snapshot, stage)
+          if stage == :before
+            return callbacks.each do |callback|
+              started[callback.group] = true if started && callback.group
+              callback.block.call
+            end
+          end
+
+          error = nil
+          callbacks.each do |callback|
+            next if started && callback.group && !started.key?(callback.group)
 
-          AT_FORK_CHILD_BLOCKS.each(&:call)
+            callback.block.call
+          rescue Exception => e # rubocop:disable Lint/RescueException -- finish cleanup, then re-raise the first failure
+            error ||= e
+          end
+          raise error if error
         end
 
+        def self.run_parent_cleanup(snapshot, started, fork_error)
+          run_at_fork_blocks(:parent, snapshot: snapshot, started: started)
+        rescue Exception => cleanup_error # rubocop:disable Lint/RescueException -- preserve the original fork failure
+          Datadog.logger.warn do
+            "Parent at-fork cleanup failed while handling #{fork_error.class}: " \
+              "#{cleanup_error.class}: #{cleanup_error.message}"
+          end
+        end
+        private_class_method :run_parent_cleanup
+
+        # Registers a block to run at the given fork +stage+ (+:before+,
+        # +:parent+, or +:child+).
+        #
+        # Returns the registered block so callers can keep a handle to it and
+        # later deregister it via {.remove_at_fork}.
         def self.at_fork(stage, &block)
-          raise(ArgumentError, "Unsupported stage #{stage}") unless stage == :child
-          raise(ArgumentError, 'Missing block argument') unless block
+          raise(ArgumentError, "Missing block argument") unless block
 
-          AT_FORK_CHILD_BLOCKS << block
+          AT_FORK_REGISTRY_MUTEX.synchronize do
+            current = @at_fork_blocks
+            @at_fork_blocks = current.merge(
+              stage => (blocks_for(current, stage) + [Callback.new(block)]).freeze
+            ).freeze
+          end
 
-          true
+          block
+        end
+
+        # Registers one before/parent/child callback triplet atomically relative
+        # to the snapshots taken by fork dispatch.
+        def self.at_fork_blocks(before:, parent:, child:)
+          blocks = {before: before, parent: parent, child: child}
+          group = Object.new.freeze
+          AT_FORK_REGISTRY_MUTEX.synchronize do
+            current = @at_fork_blocks
+            @at_fork_blocks = {
+              before: (current.fetch(:before) + [Callback.new(before, group)]).freeze,
+              parent: (current.fetch(:parent) + [Callback.new(parent, group)]).freeze,
+              child: (current.fetch(:child) + [Callback.new(child, group)]).freeze,
+            }.freeze
+          end
+          blocks
         end
 
+        # Deregisters a block previously registered with {.at_fork} for the given
+        # +stage+. It is a no-op (does not raise) when +block+ was never
+        # registered (or was already removed). Raises +ArgumentError+ for an
+        # unknown stage, matching the {.at_fork} contract.
+        def self.remove_at_fork(stage, block)
+          AT_FORK_REGISTRY_MUTEX.synchronize do
+            current = @at_fork_blocks
+            callbacks = blocks_for(current, stage)
+            @at_fork_blocks = current.merge(
+              stage => callbacks.reject { |callback| callback.block.equal?(block) }.freeze
+            ).freeze
+          end
+
+          nil
+        end
+
+        # Returns the immutable callback registry for one fork lifecycle.
+        # Copy-on-write updates publish a new reference, so registrations made
+        # afterwards apply only to the next lifecycle without locking this read.
+        def self.snapshot_at_fork_blocks
+          @at_fork_blocks
+        end
+
+        def self.replace_at_fork_blocks(snapshot)
+          AT_FORK_REGISTRY_MUTEX.synchronize { @at_fork_blocks = snapshot }
+        end
+        private_class_method :replace_at_fork_blocks
+
+        def self.blocks_for(snapshot, stage)
+          case stage
+          when :before, :parent, :child then snapshot.fetch(stage)
+          else raise(ArgumentError, "Unsupported stage #{stage}")
+          end
+        end
+        private_class_method :blocks_for
+
         # Adds `at_fork` behavior; see parent module for details.
         module KernelMonkeyPatch
           def fork
+            snapshot = AtForkMonkeyPatch.snapshot_at_fork_blocks
+            started = {}
+
             # If a block is provided, it must be wrapped to trigger callbacks.
             child_block = if block_given?
               proc do
-                AtForkMonkeyPatch.run_at_fork_blocks(:child)
+                AtForkMonkeyPatch.run_at_fork_blocks(:child, snapshot: snapshot)
 
                 # Invoke original block
                 yield
               end
             end
 
-            # Start fork
-            # If a block is provided, use the wrapped version.
-            result = child_block.nil? ? super : super(&child_block)
+            begin
+              # Run pre-fork callbacks in the parent, just before forking.
+              AtForkMonkeyPatch.run_at_fork_blocks(:before, snapshot: snapshot, started: started)
+
+              # Start fork. If a block is provided, use the wrapped version.
+              result = child_block.nil? ? super : super(&child_block)
+            rescue Exception => e # rubocop:disable Lint/RescueException -- re-raised unchanged; we only need to run parent cleanup first
+              # The fork or a before-fork callback failed and we are still in
+              # the parent. Restore any state set up by earlier callbacks.
+              AtForkMonkeyPatch.send(:run_parent_cleanup, snapshot, started, e)
+              raise
+            end
 
             # When fork gets called without a block, it returns twice:
             # If we're in the fork, result = nil: trigger child callbacks.
-            # If we're in the parent, result = pid: we do nothing.
+            # If we're in the parent, result = pid: trigger parent callbacks.
             # (If it gets called with a block, it only returns on the parent)
-            AtForkMonkeyPatch.run_at_fork_blocks(:child) if result.nil?
+            if result.nil?
+              AtForkMonkeyPatch.run_at_fork_blocks(:child, snapshot: snapshot)
+            else
+              AtForkMonkeyPatch.run_at_fork_blocks(:parent, snapshot: snapshot)
+            end
 
             result
           end
@@ -78,9 +204,23 @@ module Datadog
           # Hook provided by Ruby 3.1+ for observability libraries that want to know about fork, see
           # https://github.com/ruby/ruby/pull/5017 and https://bugs.ruby-lang.org/issues/17795
           def _fork
-            pid = super
+            snapshot = AtForkMonkeyPatch.snapshot_at_fork_blocks
+            started = {}
+            begin
+              AtForkMonkeyPatch.run_at_fork_blocks(:before, snapshot: snapshot, started: started)
+              pid = super
+            rescue Exception => e # rubocop:disable Lint/RescueException -- re-raised unchanged; we only need to run parent cleanup first
+              # The fork or a before-fork callback failed, so no child was
+              # created. Restore state set up by any earlier callbacks.
+              AtForkMonkeyPatch.send(:run_parent_cleanup, snapshot, started, e)
+              raise
+            end
 
-            AtForkMonkeyPatch.run_at_fork_blocks(:child) if pid == 0
+            if pid == 0
+              AtForkMonkeyPatch.run_at_fork_blocks(:child, snapshot: snapshot)
+            else
+              AtForkMonkeyPatch.run_at_fork_blocks(:parent, snapshot: snapshot)
+            end
 
             pid
           end
@@ -89,9 +229,21 @@ module Datadog
           # keeps executing code in the child process, killing off the parent, thus effectively replacing it.
           # This is not covered by `_fork` and thus we have some extra code for it.
           def daemon(*args)
-            result = super
+            snapshot = AtForkMonkeyPatch.snapshot_at_fork_blocks
+            started = {}
+            begin
+              AtForkMonkeyPatch.run_at_fork_blocks(:before, snapshot: snapshot, started: started)
+              result = super
+            rescue Exception => e # rubocop:disable Lint/RescueException -- re-raised unchanged; we only need to run parent cleanup first
+              # `daemon` or a before-fork callback failed, so the original
+              # process survives. Restore state set up by earlier callbacks.
+              AtForkMonkeyPatch.send(:run_parent_cleanup, snapshot, started, e)
+              raise
+            end
 
-            AtForkMonkeyPatch.run_at_fork_blocks(:child)
+            # `daemon` kills the parent, so there is no surviving parent to run
+            # `:parent` callbacks in; only the child continues executing.
+            AtForkMonkeyPatch.run_at_fork_blocks(:child, snapshot: snapshot)
 
             result
           end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Datadog
+  module Core
+    module Utils
+      # 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
+
+        def self.strict_encode64(bin)
+          [bin].pack("m0")
+        end
+
+        def self.strict_decode64(str)
+          str.unpack1("m0") #: String # 'm0' format always returns a String
+        end
+      end
+    end
+  end
+end

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

@@ -6,7 +6,7 @@ module Datadog
       # Helper methods for parsing string values into Numeric
       module Duration
         def self.call(value, base: :s)
-          cast = if value.include?('.')
+          cast = if value.include?(".")
             method(:Float)
           else
             method(:Integer)

data/lib/datadog/core/utils/{array.rb → enumerable_compat.rb}

@@ -3,8 +3,8 @@
 module Datadog
   module Core
     module Utils
-      # Common array-related utility functions.
-      module Array
+      # 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

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/core/utils/lru_cache.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'forwardable'
+require "forwardable"
 
 module Datadog
   module Core
@@ -16,8 +16,8 @@ module Datadog
         def_delegators :@store, :clear, :empty?
 
         def initialize(max_size)
-          raise ArgumentError, 'max_size must be an Integer' unless max_size.is_a?(Integer)
-          raise ArgumentError, 'max_size must be greater than 0' if max_size <= 0
+          raise ArgumentError, "max_size must be an Integer" unless max_size.is_a?(Integer)
+          raise ArgumentError, "max_size must be greater than 0" if max_size <= 0
 
           @max_size = max_size
           @store = {}

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'ipaddr'
+require "ipaddr"
 
 module Datadog
   module Core
@@ -21,7 +21,7 @@ module Datadog
           cf-connecting-ipv6
         ].freeze
 
-        CGNAT_IP_RANGE = IPAddr.new('100.64.0.0/10')
+        CGNAT_IP_RANGE = IPAddr.new("100.64.0.0/10")
 
         class << self
           # Returns a client IP associated with the request if it was
@@ -75,8 +75,8 @@ module Datadog
 
               next unless value
 
-              ips = value.split(',')
-              ips = process_forwarded_header_values(ips) if name == 'forwarded'
+              ips = value.split(",")
+              ips = process_forwarded_header_values(ips) if name == "forwarded"
 
               ips.each do |ip|
                 parsed_ip = ip_to_ipaddr(ip.strip)
@@ -92,11 +92,11 @@ module Datadog
             values.each_with_object([]) do |value, acc|
               value.downcase!
 
-              value.split(';').each do |tuple_str|
+              value.split(";").each do |tuple_str|
                 tuple_str.strip!
-                next unless tuple_str.start_with?('for=')
+                next unless tuple_str.start_with?("for=")
 
-                tuple_str.delete_prefix!('for=')
+                tuple_str.delete_prefix!("for=")
                 tuple_str.delete!('"')
 
                 acc << tuple_str
@@ -110,14 +110,14 @@ module Datadog
           # The rationale is that in valid IPv6 addresses, colons will always preced dots,
           #   and in valid IPv4 addresses dots will always preced colons.
           def likely_ipv4?(value)
-            dot_index = value.index('.') || value.size
-            colon_index = value.index(':') || value.size
+            dot_index = value.index(".") || value.size
+            colon_index = value.index(":") || value.size
 
             dot_index < colon_index
           end
 
           def strip_zone_specifier(ipv6)
-            ipv6.gsub(/%.*/, '')
+            ipv6.gsub(/%.*/, "")
           end
 
           def strip_ipv6_port(ip)
@@ -129,7 +129,7 @@ module Datadog
           end
 
           def strip_ipv4_port(ip)
-            ip.gsub(/:\d+\z/, '')
+            ip.gsub(/:\d+\z/, "")
           end
 
           def global_ip?(parsed_ip)

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative 'only_once'
+require_relative "only_once"
 
 module Datadog
   module Core

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

@@ -22,7 +22,8 @@ module Datadog
           end
         end
 
-        def self.frozen_dup(v)
+        # Steep: https://github.com/soutaro/steep/issues/2001
+        def self.frozen_dup(v) # steep:ignore MethodBodyTypeMismatch
           # For the case of a String we use the methods -@
           # That method are only for String objects
           # they are faster and chepaer on the memory side.

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

@@ -5,18 +5,15 @@ module Datadog
     module Utils
       # Generates values from a consistent sequence
       class Sequence
-        def initialize(seed = 0, &block)
+        def initialize(seed = 0)
           @seed = seed
           @current = seed
-          @next_item = block
         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 = @current
           @current += 1
-          next_item
+          current
         end
 
         def reset!