chronos-ruby 0.2.0.pre.1 → 0.4.0.pre.1

data/lib/chronos/application/delivery_pipeline.rb

@@ -0,0 +1,248 @@
+module Chronos
+  module Application
+    # Coordinates bounded queueing, retry, backlog, circuit state, and delivery.
+    #
+    # @responsibility Move serialized events through explicit delivery states.
+    # @motivation Keep resilience policy out of transports, workers, and the public facade.
+    # @limits It stores only sanitized SerializedEvent objects and never writes to disk.
+    # @collaborators RetryPolicy, CircuitBreaker, RemoteConfiguration, WorkerPool, and Transport.
+    # @thread_safety Mutable state, backlog, queue, and circuit transitions are synchronized.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6; independent of frameworks.
+    # @example
+    #   pipeline.enqueue(serialized_event)
+    #   pipeline.flush(2.0)
+    # @errors Transport and policy failures are contained and diagnosed.
+    # @performance Queue, retry count, backlog, and state counters are strictly bounded.
+    class DeliveryPipeline
+      STATES = [:accepted, :queued, :serialized, :sent, :retried, :dropped, :rejected].freeze
+
+      attr_reader :remote_configuration
+
+      def initialize(config, transport, logger = nil, options = {})
+        @config = config
+        @transport = transport
+        @logger = logger || Internal::SafeLogger.new(config.logger)
+        initialize_resilience(options)
+        initialize_storage(options)
+      end
+
+      def enqueue(event)
+        record_pre_delivery(event)
+        if @worker_pool.enqueue(event)
+          transition(:queued)
+          true
+        else
+          transition(:dropped)
+          false
+        end
+      rescue StandardError => error
+        diagnose(error)
+        transition(:dropped)
+        false
+      end
+
+      def deliver_sync(event)
+        record_pre_delivery(event)
+        result = deliver_with_backlog(event)
+        result && result.success?
+      rescue StandardError => error
+        diagnose(error)
+        store_in_backlog(event)
+        false
+      end
+
+      # WorkerPool delivery entry point. Events were counted when accepted into the queue.
+      def send_event(event)
+        deliver_with_backlog(event)
+      rescue StandardError => error
+        diagnose(error)
+        store_in_backlog(event)
+        Ports::TransportResult.new(:network_error, :error => error.class.name)
+      end
+
+      def capture_allowed?(event_type, fingerprint = nil)
+        @remote_configuration.capture?(event_type, fingerprint)
+      rescue StandardError => error
+        diagnose(error)
+        false
+      end
+
+      def max_payload_size
+        @remote_configuration.max_payload_size
+      end
+
+      def flush(timeout)
+        @worker_pool.flush(timeout)
+      end
+
+      def close(timeout)
+        return true if closed?
+
+        @state_mutex.synchronize { @closed = true }
+        flushed = @worker_pool.close(timeout)
+        @transport.close
+        flushed
+      rescue StandardError => error
+        diagnose(error)
+        false
+      end
+
+      def diagnostics
+        {
+          :states => state_counts,
+          :queue => @queue.stats,
+          :backlog => @backlog.stats,
+          :circuit => @circuit_breaker.state,
+          :remote_configuration => @remote_configuration.to_h
+        }
+      end
+
+      private
+
+      def initialize_resilience(options)
+        @clock = options[:clock] || method(:monotonic_time)
+        @sleeper = options[:sleeper] || proc { |delay| sleep(delay) }
+        @remote_configuration = options[:remote_configuration] || RemoteConfiguration.new(@config)
+        @retry_policy = options[:retry_policy] || build_retry_policy(options[:random])
+        @circuit_breaker = options[:circuit_breaker] || CircuitBreaker.new(
+          @config.circuit_failure_threshold,
+          @config.circuit_reset_timeout,
+          @clock
+        )
+      end
+
+      def initialize_storage(options)
+        @backlog = options[:backlog] || Internal::MemoryBacklog.new(@config.backlog_size)
+        @queue = options[:queue] || Internal::BoundedQueue.new(@config.queue_size)
+        @state_mutex = Mutex.new
+        @states = STATES.each_with_object({}) { |state, counts| counts[state] = 0 }
+        @send_mutex = Mutex.new
+        @last_send_at = nil
+        @closed = false
+        @worker_pool = options[:worker_pool] || Internal::WorkerPool.new(@queue, self, @config.workers, @logger)
+      end
+
+      def build_retry_policy(random)
+        RetryPolicy.new(
+          :max_retries => @config.max_retries,
+          :base_interval => @config.retry_base_interval,
+          :max_interval => @config.retry_max_interval,
+          :jitter => @config.retry_jitter,
+          :random => random
+        )
+      end
+
+      def record_pre_delivery(event)
+        raise ArgumentError, "delivery requires a SerializedEvent" unless event.is_a?(Core::SerializedEvent)
+        raise Error, "delivery pipeline is closed" if closed?
+
+        transition(:accepted)
+        transition(:serialized)
+      end
+
+      def deliver_with_backlog(event)
+        drain_one_backlog unless @backlog.empty?
+        attempt_delivery(event)
+      end
+
+      def drain_one_backlog
+        event = @backlog.shift
+        attempt_delivery(event) if event
+      end
+
+      def attempt_delivery(event)
+        unless @circuit_breaker.allow_request?
+          transition(:retried)
+          store_in_backlog(event)
+          return Ports::TransportResult.new(:circuit_open)
+        end
+
+        retries = 0
+        loop do
+          wait_for_send_interval
+          result = @transport.send_event(event)
+          return finish_success(result) if result.success?
+          return finish_permanent_failure(result) unless result.retryable?
+
+          @circuit_breaker.record_failure
+          unless @retry_policy.retry?(result, retries) && @circuit_breaker.allow_request?
+            store_in_backlog(event)
+            return result
+          end
+
+          retries += 1
+          transition(:retried)
+          @sleeper.call(@retry_policy.delay(retries, result))
+        end
+      end
+
+      def finish_success(result)
+        @circuit_breaker.record_success
+        apply_remote_configuration(result)
+        transition(:sent)
+        result
+      end
+
+      def finish_permanent_failure(result)
+        @circuit_breaker.record_success
+        transition(result.status == :client_error ? :rejected : :dropped)
+        result
+      end
+
+      def store_in_backlog(event)
+        accepted = @backlog.push(event)
+        transition(:dropped) unless accepted
+        accepted
+      rescue StandardError => error
+        diagnose(error)
+        transition(:dropped)
+        false
+      end
+
+      def apply_remote_configuration(result)
+        values = result.remote_configuration
+        return unless values && @config.remote_configuration
+
+        @remote_configuration.apply(values)
+      end
+
+      def wait_for_send_interval
+        interval = @remote_configuration.send_interval
+        return if interval <= 0.0
+
+        @send_mutex.synchronize do
+          now = @clock.call
+          if @last_send_at
+            remaining = interval - (now - @last_send_at)
+            @sleeper.call(remaining) if remaining > 0.0
+          end
+          @last_send_at = @clock.call
+        end
+      end
+
+      def transition(state)
+        @state_mutex.synchronize { @states[state] += 1 }
+      end
+
+      def state_counts
+        @state_mutex.synchronize { @states.dup }
+      end
+
+      def closed?
+        @state_mutex.synchronize { @closed }
+      end
+
+      def diagnose(error)
+        @logger.warn("Chronos delivery failed: #{error.class}")
+      end
+
+      def monotonic_time
+        if Process.respond_to?(:clock_gettime) && defined?(Process::CLOCK_MONOTONIC)
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        else
+          Time.now.to_f
+        end
+      end
+    end
+  end
+end

data/lib/chronos/application/remote_configuration.rb

@@ -0,0 +1,173 @@
+module Chronos
+  module Application
+    # Runtime policy restricted to server-authorized scalar options.
+    #
+    # @responsibility Validate and apply bounded remote delivery controls.
+    # @motivation Let operators reduce telemetry safely without redeploying an application.
+    # @limits It cannot change host, credentials, TLS, code, or regular expressions.
+    # @collaborators Configuration snapshot, CaptureException, and DeliveryPipeline.
+    # @thread_safety A mutex protects immutable state replacements.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   remote.apply("sampling_rate" => 0.5, "kill_switch" => false)
+    # @errors Invalid documents are ignored and return false.
+    # @performance Validation is bounded by configured document and list limits.
+    class RemoteConfiguration
+      SUPPORTED_EVENT_TYPES = ["exception"].freeze
+      MAX_IGNORED_FINGERPRINTS = 100
+      MAX_FINGERPRINT_BYTES = 256
+      MIN_PAYLOAD_SIZE = 256
+
+      attr_reader :ignored_fingerprints
+
+      def initialize(config, options = {})
+        @config = config
+        @random = options[:random] || proc { rand }
+        @mutex = Mutex.new
+        @local_event_types = allowed_event_types(config.enabled_event_types)
+        @values = {
+          "sampling_rate" => config.sampling_rate.to_f,
+          "enabled_event_types" => @local_event_types,
+          "max_payload_size" => config.max_payload_size,
+          "ignored_fingerprints" => [],
+          "send_interval" => 0.0,
+          "kill_switch" => false
+        }
+        @ignored_fingerprints = [].freeze
+      end
+
+      def apply(document)
+        normalized = normalize(document)
+        return false unless normalized
+
+        @mutex.synchronize do
+          @values = @values.merge(normalized)
+          @ignored_fingerprints = @values["ignored_fingerprints"].dup.freeze
+        end
+        true
+      rescue StandardError
+        false
+      end
+
+      def capture?(event_type, fingerprint = nil)
+        values = snapshot
+        return false if values["kill_switch"]
+        return false unless values["enabled_event_types"].include?(event_type.to_s)
+        return false if fingerprint && values["ignored_fingerprints"].include?(fingerprint.to_s)
+
+        rate = values["sampling_rate"]
+        rate >= 1.0 || (rate > 0.0 && @random.call.to_f < rate)
+      end
+
+      def enabled_event?(event_type)
+        snapshot["enabled_event_types"].include?(event_type.to_s)
+      end
+
+      def ignored_fingerprint?(fingerprint)
+        snapshot["ignored_fingerprints"].include?(fingerprint.to_s)
+      end
+
+      def sampling_rate
+        snapshot["sampling_rate"]
+      end
+
+      def max_payload_size
+        snapshot["max_payload_size"]
+      end
+
+      def send_interval
+        snapshot["send_interval"]
+      end
+
+      def kill_switch?
+        snapshot["kill_switch"]
+      end
+
+      def to_h
+        snapshot
+      end
+
+      private
+
+      def normalize(document)
+        return nil unless document.is_a?(Hash)
+
+        normalized = {}
+        document.each do |key, value|
+          name = key.to_s
+          next unless @values.key?(name)
+
+          normalized_value = normalize_value(name, value)
+          return nil if normalized_value.nil? && value != false
+          normalized[name] = normalized_value
+        end
+        normalized.empty? ? nil : normalized
+      end
+
+      def normalize_value(name, value)
+        case name
+        when "sampling_rate"
+          bounded_rate(value)
+        when "enabled_event_types"
+          normalize_event_types(value)
+        when "max_payload_size"
+          normalize_payload_size(value)
+        when "ignored_fingerprints"
+          normalize_fingerprints(value)
+        when "send_interval"
+          normalize_send_interval(value)
+        when "kill_switch"
+          value if [true, false].include?(value)
+        end
+      end
+
+      def bounded_rate(value)
+        return nil unless value.is_a?(Numeric) && value >= 0.0 && value <= @config.sampling_rate
+
+        value.to_f
+      end
+
+      def normalize_event_types(value)
+        return nil unless value.is_a?(Array) && value.all? { |item| item.is_a?(String) }
+
+        allowed_event_types(value)
+      end
+
+      def allowed_event_types(values)
+        supported = values.map(&:to_s).select { |value| SUPPORTED_EVENT_TYPES.include?(value) }
+        supported.select { |value| local_event_types.include?(value) }.uniq.freeze
+      end
+
+      def local_event_types
+        @local_event_types || SUPPORTED_EVENT_TYPES
+      end
+
+      def normalize_payload_size(value)
+        return nil unless value.is_a?(Integer) && value >= MIN_PAYLOAD_SIZE && value <= @config.max_payload_size
+
+        value
+      end
+
+      def normalize_fingerprints(value)
+        return nil unless value.is_a?(Array) && value.length <= MAX_IGNORED_FINGERPRINTS
+        return nil unless value.all? { |item| item.is_a?(String) && item.bytesize <= MAX_FINGERPRINT_BYTES }
+
+        value.map(&:dup).freeze
+      end
+
+      def normalize_send_interval(value)
+        return nil unless value.is_a?(Numeric) && value >= 0.0 && value <= @config.max_remote_send_interval
+
+        value.to_f
+      end
+
+      def snapshot
+        @mutex.synchronize do
+          @values.each_with_object({}) do |(key, value), copy|
+            copy[key] = value.is_a?(Array) ? value.dup : value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chronos/application/retry_policy.rb

@@ -0,0 +1,57 @@
+require "time"
+
+module Chronos
+  module Application
+    # Bounded retry timing policy with exponential backoff and jitter.
+    #
+    # @responsibility Decide whether and when a retry may occur.
+    # @motivation Centralize retry limits independently from HTTP and worker code.
+    # @limits It does not sleep, send events, or retain payloads.
+    # @collaborators TransportResult and DeliveryPipeline.
+    # @thread_safety Immutable after construction when the random callable is thread-safe.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   policy.delay(2, result)
+    # @errors Invalid configuration is rejected by Configuration.
+    # @performance Constant time per decision.
+    class RetryPolicy
+      def initialize(options)
+        @max_retries = options[:max_retries]
+        @base_interval = options[:base_interval]
+        @max_interval = options[:max_interval]
+        @jitter = options[:jitter]
+        @random = options[:random] || proc { rand }
+      end
+
+      def retry?(result, retries)
+        result.retryable? && retries < @max_retries
+      end
+
+      def delay(retry_number, result = nil)
+        retry_after = retry_after_seconds(result)
+        return [retry_after, @max_interval].min if retry_after
+
+        base = @base_interval * (2**(retry_number - 1))
+        jittered = base * (1.0 + (@random.call.to_f * @jitter))
+        [jittered, @max_interval].min
+      end
+
+      private
+
+      def retry_after_seconds(result)
+        return nil unless result && result.retry_after
+
+        value = result.retry_after.to_s
+        seconds = Float(value)
+        seconds >= 0 ? seconds : nil
+      rescue ArgumentError, TypeError
+        begin
+          seconds = Time.httpdate(value) - Time.now
+          seconds > 0 ? seconds : nil
+        rescue ArgumentError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/chronos/configuration.rb

@@ -24,6 +24,7 @@ module Chronos
       token access_token refresh_token private_key client_secret cookie set-cookie
       session credit_card card_number cvv cpf cnpj
     ).freeze
+    CONTEXT_STORE_METHODS = [:get, :set, :clear, :with_context].freeze
 
     ATTRIBUTES = [
       :project_id, :project_key, :host, :environment, :app_version,
@@ -31,12 +32,54 @@ module Chronos
       :queue_size, :workers, :enabled, :error_notifications,
       :ignored_environments, :proxy, :ssl_verify, :user_agent,
       :max_payload_size, :gzip, :blocklist_keys, :allowlist_keys,
-      :filters, :hash_keys, :anonymize_ip
+      :filters, :hash_keys, :anonymize_ip, :max_retries,
+      :retry_base_interval, :retry_max_interval, :retry_jitter,
+      :backlog_size, :circuit_failure_threshold, :circuit_reset_timeout,
+      :remote_configuration, :remote_config_max_bytes, :sampling_rate,
+      :enabled_event_types, :max_remote_send_interval, :context_store,
+      :breadcrumb_capacity, :breadcrumb_max_bytes
     ].freeze
 
     attr_accessor(*ATTRIBUTES)
 
     def initialize
+      initialize_core_defaults
+      initialize_privacy_defaults
+      initialize_resilience_defaults
+    end
+
+    def snapshot
+      errors = validation_errors
+      raise ConfigurationError, errors.join(", ") unless errors.empty?
+
+      Snapshot.new(to_hash)
+    end
+
+    def valid?
+      validation_errors.empty?
+    end
+
+    def validation_errors # rubocop:disable Metrics/AbcSize
+      errors = []
+      if enabled
+        errors << "project_id is required" if blank?(project_id)
+        errors << "project_key is required" if blank?(project_key)
+        errors.concat(host_errors)
+      end
+      errors << "timeout must be greater than zero" unless positive_number?(timeout)
+      errors << "open_timeout must be greater than zero" unless positive_number?(open_timeout)
+      errors << "queue_size must be a positive integer" unless positive_integer?(queue_size)
+      errors << "workers must be a positive integer" unless positive_integer?(workers)
+      errors << "max_payload_size must be a positive integer" unless positive_integer?(max_payload_size)
+      errors.concat(resilience_errors)
+      errors.concat(privacy_errors)
+      errors.concat(context_errors)
+      errors
+    end
+
+    private
+
+    def initialize_core_defaults
       @project_id = nil
       @project_key = nil
       @host = nil
@@ -57,6 +100,12 @@ module Chronos
       @user_agent = "chronos-ruby/#{Chronos::VERSION}"
       @max_payload_size = 1_048_576
       @gzip = false
+      @context_store = :thread_local
+      @breadcrumb_capacity = 20
+      @breadcrumb_max_bytes = 2048
+    end
+
+    def initialize_privacy_defaults
       @blocklist_keys = DEFAULT_BLOCKLIST_KEYS.dup
       @allowlist_keys = []
       @filters = []
@@ -64,34 +113,65 @@ module Chronos
       @anonymize_ip = true
     end
 
-    def snapshot
-      errors = validation_errors
-      raise ConfigurationError, errors.join(", ") unless errors.empty?
+    def initialize_resilience_defaults
+      @max_retries = 3
+      @retry_base_interval = 0.5
+      @retry_max_interval = 30.0
+      @retry_jitter = 0.25
+      @backlog_size = 100
+      @circuit_failure_threshold = 5
+      @circuit_reset_timeout = 30.0
+      @remote_configuration = true
+      @remote_config_max_bytes = 4096
+      @sampling_rate = 1.0
+      @enabled_event_types = ["exception"]
+      @max_remote_send_interval = 60.0
+    end
 
-      Snapshot.new(to_hash)
+    def resilience_errors
+      errors = []
+      errors.concat(retry_errors)
+      errors.concat(backlog_and_circuit_errors)
+      errors.concat(remote_policy_errors)
+      errors
     end
 
-    def valid?
-      validation_errors.empty?
+    def retry_errors
+      errors = []
+      errors << "max_retries must be a non-negative integer" unless non_negative_integer?(max_retries)
+      errors << "retry_base_interval must be greater than zero" unless positive_number?(retry_base_interval)
+      errors << "retry_max_interval must be greater than zero" unless positive_number?(retry_max_interval)
+      if positive_number?(retry_base_interval) && positive_number?(retry_max_interval) &&
+         retry_max_interval < retry_base_interval
+        errors << "retry_max_interval must be greater than or equal to retry_base_interval"
+      end
+      errors << "retry_jitter must be between zero and one" unless rate?(retry_jitter)
+      errors
     end
 
-    def validation_errors
+    def backlog_and_circuit_errors
       errors = []
-      if enabled
-        errors << "project_id is required" if blank?(project_id)
-        errors << "project_key is required" if blank?(project_key)
-        errors.concat(host_errors)
+      errors << "backlog_size must be a non-negative integer" unless non_negative_integer?(backlog_size)
+      unless positive_integer?(circuit_failure_threshold)
+        errors << "circuit_failure_threshold must be a positive integer"
       end
-      errors << "timeout must be greater than zero" unless positive_number?(timeout)
-      errors << "open_timeout must be greater than zero" unless positive_number?(open_timeout)
-      errors << "queue_size must be a positive integer" unless positive_integer?(queue_size)
-      errors << "workers must be a positive integer" unless positive_integer?(workers)
-      errors << "max_payload_size must be a positive integer" unless positive_integer?(max_payload_size)
-      errors.concat(privacy_errors)
+      errors << "circuit_reset_timeout must be greater than zero" unless positive_number?(circuit_reset_timeout)
       errors
     end
 
-    private
+    def remote_policy_errors
+      errors = []
+      unless [true, false].include?(remote_configuration)
+        errors << "remote_configuration must be true or false"
+      end
+      errors << "remote_config_max_bytes must be a positive integer" unless positive_integer?(remote_config_max_bytes)
+      errors << "sampling_rate must be between zero and one" unless rate?(sampling_rate)
+      unless enabled_event_types.is_a?(Array) && enabled_event_types.all? { |value| value.is_a?(String) }
+        errors << "enabled_event_types must contain only String values"
+      end
+      errors << "max_remote_send_interval must be greater than zero" unless positive_number?(max_remote_send_interval)
+      errors
+    end
 
     def to_hash
       ATTRIBUTES.each_with_object({}) do |attribute, values|
@@ -113,6 +193,20 @@ module Chronos
       errors
     end
 
+    def context_errors
+      errors = []
+      unless context_store == :thread_local || CONTEXT_STORE_METHODS.all? do |method_name|
+        context_store.respond_to?(method_name)
+      end
+        errors << "context_store must be :thread_local or implement get, set, clear, and with_context"
+      end
+      errors << "breadcrumb_capacity must be a positive integer" unless positive_integer?(breadcrumb_capacity)
+      unless breadcrumb_max_bytes.is_a?(Integer) && breadcrumb_max_bytes >= 128
+        errors << "breadcrumb_max_bytes must be an integer greater than or equal to 128"
+      end
+      errors
+    end
+
     def filter_errors
       return ["filters must be an array"] unless filters.is_a?(Array)
       return [] if filters.all? { |filter| filter.respond_to?(:call) }
@@ -170,6 +264,14 @@ module Chronos
       value.is_a?(Integer) && value > 0
     end
 
+    def non_negative_integer?(value)
+      value.is_a?(Integer) && value >= 0
+    end
+
+    def rate?(value)
+      value.is_a?(Numeric) && value >= 0.0 && value <= 1.0
+    end
+
     # Immutable configuration shared by all runtime components.
     #
     # @responsibility Expose validated settings without mutable containers.
@@ -196,7 +298,7 @@ module Chronos
       private
 
       def deep_freeze(value)
-        return value if value.respond_to?(:call)
+        return value if value.respond_to?(:call) || context_store?(value)
 
         case value
         when Hash
@@ -209,6 +311,12 @@ module Chronos
         end
         value.freeze
       end
+
+      def context_store?(value)
+        CONTEXT_STORE_METHODS.all? { |method_name| value.respond_to?(method_name) }
+      rescue StandardError
+        false
+      end
     end
   end
 end