datadog 2.4.0 → 2.44.0

data/lib/datadog/kit.rb

@@ -8,4 +8,4 @@ module Datadog
   end
 end
 
-require_relative 'kit/identity'
+require_relative "kit/identity"

data/lib/datadog/open_feature/agentless/configuration_source.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require_relative "../../core/workers/polling"
+require_relative "../evaluation_engine"
+require_relative "parser"
+require_relative "transport"
+
+module Datadog
+  module OpenFeature
+    module Agentless
+      # Polls the agentless endpoint and applies accepted configuration.
+      class ConfigurationSource
+        MAX_ATTEMPTS = 3
+        FIRST_RETRY_MIN_SECONDS = 2.0
+        FIRST_RETRY_MAX_SECONDS = 10.0
+        SECOND_RETRY_MIN_SECONDS = 5.0
+        SECOND_RETRY_MAX_SECONDS = 30.0
+        RETRY_JITTER = 0.2
+
+        include Core::Workers::Polling
+
+        attr_reader :etag
+
+        def self.build(settings, endpoint:, apply:, logger: Datadog.logger)
+          api_key = settings.api_key.to_s.strip
+          if endpoint.managed? && api_key.empty?
+            logger.warn("Feature Flags agentless delivery requires DD_API_KEY; agentless delivery is disabled")
+            return
+          end
+
+          new(
+            endpoint: endpoint,
+            api_key: api_key.empty? ? nil : api_key,
+            poll_interval_seconds: settings.feature_flags.agentless.poll_interval_seconds,
+            request_timeout_seconds: settings.feature_flags.agentless.request_timeout_seconds,
+            apply: apply,
+            logger: logger,
+          )
+        end
+
+        def initialize(
+          endpoint:,
+          api_key:,
+          poll_interval_seconds:,
+          request_timeout_seconds:,
+          apply:,
+          logger:,
+          transport: nil,
+          random: nil,
+          retry_wait: nil
+        )
+          @transport = transport || Transport.new(
+            endpoint: endpoint,
+            api_key: api_key,
+            timeout_seconds: request_timeout_seconds,
+          )
+          @apply = apply
+          @logger = logger
+          @poll_interval_seconds = poll_interval_seconds
+          @random = random || -> { Kernel.rand }
+          @retry_wait = retry_wait || ->(delay) { wait_for_retry(delay) }
+          @etag = nil
+          @warned = {}
+          @lifecycle_mutex = Mutex.new
+          @started = false
+          @stopped = false
+
+          self.enabled = true
+          self.fork_policy = Core::Workers::Async::Thread::FORK_POLICY_RESTART
+          self.loop_base_interval = poll_interval_seconds
+        end
+
+        def start
+          @lifecycle_mutex.synchronize do
+            return false if @stopped
+            return true if @started && !forked?
+
+            perform
+            @started = true
+          end
+
+          true
+        end
+
+        def stop(force_stop = true, timeout = Core::Workers::Polling::DEFAULT_SHUTDOWN_TIMEOUT)
+          @lifecycle_mutex.synchronize do
+            return false if @stopped
+
+            @stopped = true
+            self.enabled = false
+          end
+
+          super
+          true
+        end
+
+        def perform
+          poll
+        # An exception escaping here ends the unsupervised worker thread and freezes configuration.
+        rescue => error
+          warn_once(:unexpected) do
+            @logger.error("Feature Flags agentless poll failed with #{error.class}; polling continues")
+          end
+        end
+
+        def poll
+          attempt = 1
+
+          while attempt <= MAX_ATTEMPTS
+            return if stopped?
+
+            response = @transport.get(@etag)
+            unless retryable?(response)
+              apply_response(response)
+              return
+            end
+
+            if attempt == MAX_ATTEMPTS
+              warn_failure(response, attempt)
+              return
+            end
+
+            return if wait_before_retry(retry_delay(attempt))
+
+            attempt += 1
+          end
+        end
+
+        protected
+
+        def after_fork
+          # The child must report its own failures, while the inherited ETag still matches its configuration.
+          @warned = {}
+          nil
+        end
+
+        private
+
+        def stopped?
+          @lifecycle_mutex.synchronize { @stopped }
+        end
+
+        def retryable?(response)
+          status = response.status
+          return true unless status
+
+          retryable_status?(status)
+        end
+
+        def retryable_status?(status)
+          status == 408 || status == 429 || status.between?(500, 599)
+        end
+
+        def retry_delay(attempt)
+          base = if attempt == 1
+            clamp(@poll_interval_seconds / 6.0, FIRST_RETRY_MIN_SECONDS, FIRST_RETRY_MAX_SECONDS)
+          else
+            clamp(@poll_interval_seconds / 3.0, SECOND_RETRY_MIN_SECONDS, SECOND_RETRY_MAX_SECONDS)
+          end
+          random = @random.call
+          jitter = 1 - RETRY_JITTER + (random * RETRY_JITTER * 2)
+          [1.0, base * jitter].max
+        end
+
+        def clamp(value, minimum, maximum)
+          value.clamp(minimum, maximum)
+        end
+
+        def wait_before_retry(delay)
+          @retry_wait.call(delay)
+        end
+
+        def wait_for_retry(delay)
+          mutex.synchronize do
+            return true if stopped?
+
+            shutdown.wait(mutex, delay)
+          end
+
+          stopped? || !run_loop?
+        end
+
+        def apply_response(response)
+          case response.status
+          when 200
+            apply_configuration(response)
+          when 304
+            nil
+          when 401, 403
+            warn_once(:authentication) do
+              @logger.warn(
+                "Feature Flags agentless endpoint returned HTTP #{response.status}; verify endpoint authentication"
+              )
+            end
+          else
+            warn_failure(response, 1)
+          end
+        end
+
+        def apply_configuration(response)
+          configuration = response.body && Parser.parse(response.body)
+          unless configuration
+            warn_once(:malformed) do
+              @logger.error("Feature Flags agentless endpoint returned malformed UFC payload")
+            end
+            return
+          end
+
+          @apply.call(configuration)
+          etag = response.etag.to_s.strip
+          @etag = etag.empty? ? nil : etag
+        rescue EvaluationEngine::ReconfigurationError => error
+          warn_once(:application) do
+            @logger.warn("Feature Flags agentless UFC payload could not be applied: #{error.class}: #{error.message}")
+          end
+        end
+
+        def warn_failure(response, attempts)
+          status = response.status
+          category = if status.nil?
+            :request
+          elsif retryable_status?(status)
+            :http_retryable
+          else
+            :http_unexpected
+          end
+          warn_once(category) do
+            if status
+              @logger.warn("Feature Flags agentless endpoint returned HTTP #{status} after #{attempts} attempt(s)")
+            else
+              error_class = response.error ? response.error.class : StandardError
+              @logger.warn("Feature Flags agentless request failed after #{attempts} attempt(s): #{error_class}")
+            end
+          end
+        end
+
+        def warn_once(category)
+          return if @warned[category]
+
+          @warned[category] = true
+          yield
+        end
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/agentless/parser.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Datadog
+  module OpenFeature
+    module Agentless
+      # Parses the JSON:API envelope returned by agentless delivery.
+      module Parser
+        RESOURCE_TYPE = "universal-flag-configuration"
+
+        module_function
+
+        def parse(body)
+          payload = JSON.parse(body)
+          return unless payload.is_a?(Hash)
+
+          data = payload["data"]
+          return unless data.is_a?(Hash) && data["type"] == RESOURCE_TYPE
+
+          attributes = data["attributes"]
+          return unless valid_attributes?(attributes)
+
+          JSON.generate(attributes)
+        rescue JSON::ParserError, JSON::GeneratorError, TypeError
+          nil
+        end
+
+        def valid_attributes?(attributes)
+          return false unless attributes.is_a?(Hash)
+
+          environment = attributes["environment"]
+          attributes["format"].is_a?(String) &&
+            attributes["createdAt"].is_a?(String) &&
+            environment.is_a?(Hash) &&
+            environment["name"].is_a?(String) &&
+            attributes["flags"].is_a?(Hash)
+        end
+        private_class_method :valid_attributes?
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/agentless/response.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Datadog
+  module OpenFeature
+    module Agentless
+      # Result of one agentless configuration request.
+      class Response
+        attr_reader :status, :etag, :body, :error
+
+        def initialize(status: nil, etag: nil, body: nil, error: nil)
+          @status = status
+          @etag = etag
+          @body = body
+          @error = error
+        end
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/agentless/transport.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "stringio"
+require "timeout"
+require "uri"
+require "zlib"
+
+require_relative "../../core/environment/identity"
+require_relative "../../core/transport/ext"
+require_relative "response"
+
+module Datadog
+  module OpenFeature
+    module Agentless
+      # HTTP transport for agentless configuration delivery.
+      class Transport
+        def initialize(endpoint:, api_key:, timeout_seconds:)
+          @endpoint = endpoint
+          @api_key = endpoint.managed? ? api_key : nil
+          @timeout_seconds = timeout_seconds
+        end
+
+        def get(etag)
+          request = Net::HTTP::Get.new(@endpoint.uri.request_uri, headers(etag))
+          apply_custom_authentication(request)
+          response = request(request)
+          status = response.code.to_i
+
+          Response.new(
+            status: status,
+            etag: response["ETag"],
+            # Decoding another status can erase the status the poller needs to classify the response.
+            body: (status == 200) ? response_body(response) : nil,
+          )
+        # Net::HTTP uses several version-specific exception types. None may end
+        # the delivery worker; the poller classifies every transport failure.
+        rescue => error
+          Response.new(error: error)
+        end
+
+        private
+
+        def apply_custom_authentication(request)
+          return if @endpoint.managed?
+
+          uri = @endpoint.uri
+          username = uri.user
+          return unless username
+
+          request.basic_auth(
+            URI::RFC2396_PARSER.unescape(username),
+            URI::RFC2396_PARSER.unescape(uri.password.to_s),
+          )
+        end
+
+        def headers(etag)
+          headers = {
+            "Accept-Encoding" => "gzip",
+            "DD-Client-Library-Language" => Core::Environment::Identity.lang,
+            "DD-Client-Library-Version" => Core::Environment::Identity.gem_datadog_version_semver2,
+            Core::Transport::Ext::HTTP::HEADER_DD_INTERNAL_UNTRACED_REQUEST => "1",
+          }
+          api_key = @api_key
+          headers[Core::Transport::Ext::HTTP::HEADER_DD_API_KEY] = api_key if api_key
+          headers["If-None-Match"] = etag if etag
+          headers
+        end
+
+        def request(request)
+          uri = @endpoint.uri
+          hostname = uri.hostname
+          raise ArgumentError, "Feature Flags agentless endpoint must have a host" unless hostname
+
+          # Agentless delivery requires public egress, so use Ruby's standard proxy discovery.
+          http = Net::HTTP.new(hostname, uri.port)
+          http.max_retries = 0
+          http.use_ssl = uri.scheme == "https"
+          http.open_timeout = @timeout_seconds
+          http.read_timeout = @timeout_seconds
+          http.write_timeout = @timeout_seconds if http.respond_to?(:write_timeout=)
+
+          # Bounds total request time, including DNS resolution, which the per-phase timeouts do not cover.
+          Timeout.timeout(@timeout_seconds) do
+            http.start { |connection| connection.request(request) }
+          end
+        end
+
+        def response_body(response)
+          body = response.body.to_s
+          return body unless response["Content-Encoding"].to_s.strip.casecmp("gzip") == 0
+
+          reader = Zlib::GzipReader.new(StringIO.new(body))
+          begin
+            reader.read.to_s
+          ensure
+            reader.close
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/component.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require_relative "transport"
+require_relative "evaluation_engine"
+require_relative "../core/utils/time"
+require_relative "exposures/buffer"
+require_relative "exposures/worker"
+require_relative "exposures/deduplicator"
+require_relative "exposures/reporter"
+require_relative "metrics/flag_eval_metrics"
+require_relative "flag_evaluation/writer"
+require_relative "hooks/flag_eval_metrics_hook"
+require_relative "hooks/flag_eval_evp_hook"
+require_relative "hooks/span_enrichment_hook"
+
+module Datadog
+  module OpenFeature
+    # This class is the entry point for the OpenFeature component
+    class Component
+      CONFIGURATION_READY = :ready
+      CONFIGURATION_TIMEOUT = :timeout
+      CONFIGURATION_SHUTDOWN = :shutdown
+
+      attr_reader :engine, :flag_eval_metrics_hook, :flag_eval_evp_hook, :span_enrichment_hook
+
+      def self.build(settings, agent_settings, logger:, telemetry:)
+        return unless settings.respond_to?(:open_feature) && settings.open_feature.enabled
+
+        unless settings.respond_to?(:remote) && settings.remote.enabled
+          message = "OpenFeature could not be enabled as Remote Configuration is currently disabled. " \
+            "To enable Remote Configuration, see https://docs.datadoghq.com/remote_configuration/."
+
+          logger.warn(message)
+          return
+        end
+
+        unless ["ruby", "truffleruby"].include?(RUBY_ENGINE)
+          message = "OpenFeature could not be enabled as MRI is required, " \
+            "but running on #{RUBY_ENGINE.inspect}"
+
+          logger.warn(message)
+          return
+        end
+
+        if (libdatadog_api_failure = Core::LIBDATADOG_API_FAILURE)
+          message = "OpenFeature could not be enabled as `libdatadog` is not loaded: " \
+            "#{libdatadog_api_failure.inspect}. For help solving this issue, " \
+            "please contact Datadog support at https://docs.datadoghq.com/help/."
+
+          logger.warn(message)
+          return
+        end
+
+        new(settings, agent_settings, logger: logger, telemetry: telemetry)
+      end
+
+      def initialize(settings, agent_settings, logger:, telemetry:)
+        transport = Transport::HTTP.build(agent_settings: agent_settings, logger: logger)
+        @worker = Exposures::Worker.new(settings: settings, transport: transport, telemetry: telemetry, logger: logger)
+
+        reporter = Exposures::Reporter.new(@worker, telemetry: telemetry, logger: logger)
+        @engine = EvaluationEngine.new(reporter, telemetry: telemetry, logger: logger)
+
+        @telemetry = telemetry
+        @logger = logger
+        @settings = settings
+        @agent_settings = agent_settings
+        @flag_eval_metrics_hook = create_flag_eval_metrics_hook
+        @flag_eval_evp_hook = create_flag_eval_evp_hook
+        @span_enrichment_hook = create_span_enrichment_hook
+
+        @configuration_mutex = Mutex.new
+        @reconfiguration_mutex = Mutex.new
+        @configuration_condition = ConditionVariable.new
+        @configuration_received = false
+        @configuration_shutdown = false
+      end
+
+      def reconfigure!(configuration)
+        @reconfiguration_mutex.synchronize do
+          return if configuration_shutdown?
+
+          @engine.reconfigure!(configuration)
+
+          @configuration_mutex.synchronize do
+            return if @configuration_shutdown
+
+            @configuration_received = !configuration.nil?
+            @configuration_condition.broadcast
+          end
+        end
+      end
+
+      def wait_for_configuration
+        timeout_seconds = @settings.feature_flags.initialization_timeout_ms / 1000.0
+        deadline = Core::Utils::Time.get_time + timeout_seconds
+
+        @configuration_mutex.synchronize do
+          loop do
+            return CONFIGURATION_SHUTDOWN if @configuration_shutdown
+            return CONFIGURATION_READY if @configuration_received
+
+            remaining = deadline - Core::Utils::Time.get_time
+            return CONFIGURATION_TIMEOUT unless remaining.positive?
+
+            @configuration_condition.wait(@configuration_mutex, remaining)
+          end
+        end
+      end
+
+      def configuration_received?
+        @configuration_mutex.synchronize { @configuration_received }
+      end
+
+      def shutdown!
+        @configuration_mutex.synchronize do
+          @configuration_shutdown = true
+          @configuration_condition.broadcast
+        end
+
+        @worker.graceful_shutdown
+        @flag_eval_evp_writer&.stop
+        # Symmetric teardown: drop any accumulated span-enrichment state and
+        # subscriptions (Ruby CLAUDE.md mandates closing resources).
+        @span_enrichment_hook&.shutdown
+      end
+
+      private
+
+      def configuration_shutdown?
+        @configuration_mutex.synchronize { @configuration_shutdown }
+      end
+
+      def create_flag_eval_metrics_hook
+        return unless Hooks::FlagEvalMetricsHook.available?
+
+        metrics = Metrics::FlagEvalMetrics.new(telemetry: @telemetry, logger: @logger)
+        Hooks::FlagEvalMetricsHook.new(metrics)
+      end
+
+      # Killswitch: DD_FLAGGING_EVALUATION_COUNTS_ENABLED (default on) gates only the EVP path.
+      # Read through the datadog config registry, not raw ENV.
+      def create_flag_eval_evp_hook
+        return unless @settings.open_feature.evaluation_counts_enabled
+        return unless Hooks::FlagEvalEVPHook.available?
+
+        evp_transport = Transport::HTTP.build_flagevaluations(
+          agent_settings: @agent_settings,
+          logger: @logger,
+        )
+        @flag_eval_evp_writer = FlagEvaluation::Writer.new(transport: evp_transport, logger: @logger, telemetry: @telemetry)
+        Hooks::FlagEvalEVPHook.new(@flag_eval_evp_writer)
+      end
+
+      # Construct the span-enrichment hook only when the opt-in gate is on, so
+      # there is no idle per-span overhead when disabled.
+      def create_span_enrichment_hook
+        return unless @settings.open_feature.span_enrichment_enabled
+
+        store = Hooks::SpanEnrichmentHook::SpanEnrichmentStateStore.new
+        Hooks::SpanEnrichmentHook.new(store, logger: @logger)
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/configuration/agentless_endpoint.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Datadog
+  module OpenFeature
+    module Configuration
+      # Validated endpoint for agentless Feature Flags configuration delivery.
+      class AgentlessEndpoint
+        DEFAULT_SITE = "datadoghq.com"
+        AGENTLESS_SUBDOMAIN = "ufc-server.ff-cdn"
+        CONFIGURATION_PATH = "/api/v2/feature-flagging/config/rules-based/server"
+        INVALID_SITE_CHARACTERS = /[\s\/?#@:]/
+        INTERNAL_WHITESPACE = /\s/
+
+        class << self
+          def build(site:, environment:, base_url: nil, logger: Datadog.logger)
+            if base_url
+              build_custom(base_url, logger)
+            else
+              build_managed(site, environment, logger)
+            end
+          end
+
+          private
+
+          def build_custom(base_url, logger)
+            unless base_url.ascii_only?
+              logger.warn("Feature Flags agentless base URL is invalid; agentless delivery is disabled")
+              return
+            end
+
+            if base_url.match?(INTERNAL_WHITESPACE)
+              logger.warn("Feature Flags agentless base URL contains whitespace; agentless delivery is disabled")
+              return
+            end
+
+            uri = URI.parse(base_url)
+            unless uri.is_a?(URI::HTTP) && uri.absolute? && uri.host
+              logger.warn("Feature Flags agentless base URL must be an absolute HTTP or HTTPS URL; agentless delivery is disabled")
+              return
+            end
+
+            uri.path = CONFIGURATION_PATH if uri.path.to_s.empty? || uri.path == "/"
+            new(uri, managed: false)
+          rescue URI::InvalidURIError
+            logger.warn("Feature Flags agentless base URL is invalid; agentless delivery is disabled")
+            nil
+          end
+
+          def build_managed(site, environment, logger)
+            string_site = site.to_s
+            unless string_site.ascii_only?
+              logger.warn("Feature Flags site is invalid; agentless delivery is disabled")
+              return
+            end
+
+            normalized_site = string_site.strip.downcase
+            normalized_site = DEFAULT_SITE if normalized_site.empty?
+            if normalized_site.match?(INVALID_SITE_CHARACTERS)
+              logger.warn("Feature Flags site is invalid; agentless delivery is disabled")
+              return
+            end
+
+            uri = URI::HTTPS.build(
+              host: "#{AGENTLESS_SUBDOMAIN}.#{normalized_site}",
+              path: CONFIGURATION_PATH,
+              query: environment.nil? ? nil : URI.encode_www_form(dd_env: environment),
+            )
+            new(uri, managed: true)
+          rescue URI::InvalidComponentError
+            logger.warn("Feature Flags site is invalid; agentless delivery is disabled")
+            nil
+          end
+        end
+
+        attr_reader :uri
+
+        def initialize(uri, managed:)
+          @uri = uri
+          @managed = managed
+        end
+
+        def managed?
+          @managed
+        end
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/configuration/source/resolution.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Datadog
+  module OpenFeature
+    module Configuration
+      module Source
+        class Resolution
+          attr_reader :source
+
+          def initialize(source, enabled:)
+            @source = source
+            @enabled = enabled
+          end
+
+          def enabled?
+            @enabled
+          end
+        end
+      end
+    end
+  end
+end