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

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

@@ -31,12 +31,52 @@ 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
     ].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
+      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
+    end
+
+    private
+
+    def initialize_core_defaults
       @project_id = nil
       @project_key = nil
       @host = nil
@@ -57,6 +97,9 @@ module Chronos
       @user_agent = "chronos-ruby/#{Chronos::VERSION}"
       @max_payload_size = 1_048_576
       @gzip = false
+    end
+
+    def initialize_privacy_defaults
       @blocklist_keys = DEFAULT_BLOCKLIST_KEYS.dup
       @allowlist_keys = []
       @filters = []
@@ -64,34 +107,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|
@@ -170,6 +244,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.

data/lib/chronos/core/payload_serializer.rb

@@ -43,13 +43,15 @@ module Chronos
         @clock = clock || proc { Time.now }
         @sanitizer = options[:sanitizer] || Sanitizer.new(config)
         @safe_serializer = options[:safe_serializer] || SafeSerializer.new
+        @max_payload_size = options[:max_payload_size] || proc { @config.max_payload_size }
       end
 
       def call(notice)
         envelope = @safe_serializer.call(@sanitizer.call(build_envelope(notice)))
         body = JSON.generate(envelope)
-        body = JSON.generate(compact_envelope(envelope)) if body.bytesize > @config.max_payload_size
-        raise Error, "event exceeds max_payload_size" if body.bytesize > @config.max_payload_size
+        limit = @max_payload_size.call
+        body = JSON.generate(compact_envelope(envelope)) if body.bytesize > limit
+        raise Error, "event exceeds max_payload_size" if body.bytesize > limit
 
         SerializedEvent.new(notice.event_id, body)
       end

data/lib/chronos/internal/bounded_queue.rb

@@ -4,7 +4,7 @@ module Chronos
     #
     # @responsibility Accept events up to a limit and count accepted and dropped items.
     # @motivation Prevent telemetry bursts from growing application memory indefinitely.
-    # @limits Version 0.2 drops the newest item when full and does not persist to disk.
+    # @limits Version 0.3 drops the newest item when full and does not persist to disk.
     # @collaborators WorkerPool.
     # @thread_safety Mutex and condition variable protect all mutable state.
     # @compatibility Ruby 2.2.10 through Ruby 2.6 and fork-aware callers.

data/lib/chronos/internal/memory_backlog.rb

@@ -0,0 +1,65 @@
+module Chronos
+  module Internal
+    # Fixed-capacity retry storage for sanitized serialized events.
+    #
+    # @responsibility Retain failed deliveries in memory without unbounded growth.
+    # @motivation Allow later recovery while preserving the host application's memory limit.
+    # @limits It never writes to disk and accepts only SerializedEvent instances.
+    # @collaborators DeliveryPipeline and SerializedEvent.
+    # @thread_safety A mutex protects storage and counters.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   backlog.push(serialized_event)
+    # @errors Invalid event types raise before entering storage.
+    # @performance Push and shift are bounded by the configured capacity.
+    class MemoryBacklog
+      attr_reader :capacity
+
+      def initialize(capacity)
+        unless capacity.is_a?(Integer) && capacity >= 0
+          raise ArgumentError, "capacity must be a non-negative integer"
+        end
+
+        @capacity = capacity
+        @items = []
+        @accepted = 0
+        @dropped = 0
+        @mutex = Mutex.new
+      end
+
+      def push(event)
+        unless event.is_a?(Core::SerializedEvent)
+          raise ArgumentError, "backlog accepts only sanitized serialized events"
+        end
+
+        @mutex.synchronize do
+          if @items.length >= capacity
+            @dropped += 1
+            return false
+          end
+          @items << event
+          @accepted += 1
+          true
+        end
+      end
+
+      def shift
+        @mutex.synchronize { @items.shift }
+      end
+
+      def size
+        @mutex.synchronize { @items.size }
+      end
+
+      def empty?
+        size.zero?
+      end
+
+      def stats
+        @mutex.synchronize do
+          {:size => @items.size, :capacity => capacity, :accepted => @accepted, :dropped => @dropped}
+        end
+      end
+    end
+  end
+end

data/lib/chronos/internal/worker_pool.rb

@@ -4,8 +4,8 @@ module Chronos
     #
     # @responsibility Start workers on first use, deliver events, flush, and shut down predictably.
     # @motivation Keep serialization and network delivery outside the caller's critical path.
-    # @limits Version 0.2 does not retry failed deliveries or persist a backlog.
-    # @collaborators BoundedQueue, Transport, and SafeLogger.
+    # @limits Retry policy belongs to the delivery collaborator.
+    # @collaborators BoundedQueue, DeliveryPipeline, and SafeLogger.
     # @thread_safety Internal state is synchronized and active delivery is counted.
     # @compatibility Ruby 2.2.10 through Ruby 2.6; workers are recreated after fork.
     # @example
@@ -16,9 +16,9 @@ module Chronos
     class WorkerPool
       POLL_INTERVAL = 0.05
 
-      def initialize(queue, transport, worker_count, logger = nil)
+      def initialize(queue, delivery, worker_count, logger = nil)
         @queue = queue
-        @transport = transport
+        @delivery = delivery
         @worker_count = worker_count
         @logger = logger || SafeLogger.new(nil)
         @mutex = Mutex.new
@@ -59,7 +59,6 @@ module Chronos
         flushed = flush_without_reopening(timeout)
         @queue.close
         join_workers(timeout)
-        @transport.close
         flushed
       rescue StandardError => error
         @logger.warn("Chronos worker shutdown failed: #{error.class}")
@@ -87,7 +86,7 @@ module Chronos
 
           increment_active
           begin
-            @transport.send_event(event)
+            @delivery.send_event(event)
           rescue StandardError => error
             @logger.warn("Chronos worker contained #{error.class}")
           ensure

data/lib/chronos/ports/transport.rb

@@ -4,17 +4,18 @@ module Chronos
     #
     # @responsibility Describe delivery outcome and retry classification.
     # @motivation Keep HTTP implementation details outside the application layer.
-    # @limits It does not schedule retries; retry is outside version 0.2.
+    # @limits It classifies outcomes but does not schedule retries.
     # @thread_safety Immutable after construction.
     # @compatibility Ruby 2.2.10 through Ruby 2.6.
     class TransportResult
-      attr_reader :status, :status_code, :retry_after, :error
+      attr_reader :status, :status_code, :retry_after, :error, :remote_configuration
 
       def initialize(status, options = {})
         @status = status
         @status_code = options[:status_code]
         @retry_after = options[:retry_after]
         @error = options[:error]
+        @remote_configuration = options[:remote_configuration]
         freeze
       end
 
@@ -23,7 +24,7 @@ module Chronos
       end
 
       def retryable?
-        [:rate_limited, :server_error, :network_error].include?(status)
+        [:request_timeout, :rate_limited, :server_error, :network_error].include?(status)
       end
     end
 

data/lib/chronos/version.rb

@@ -1,4 +1,4 @@
 module Chronos
   # Current version of the legacy Chronos Ruby agent.
-  VERSION = "0.2.0.pre.1".freeze
+  VERSION = "0.3.0.pre.1".freeze
 end

data/lib/chronos.rb

@@ -18,8 +18,13 @@ require "chronos/core/payload_serializer"
 require "chronos/ports/transport"
 require "chronos/internal/safe_logger"
 require "chronos/internal/bounded_queue"
+require "chronos/internal/memory_backlog"
 require "chronos/internal/worker_pool"
 require "chronos/adapters/net_http_transport"
+require "chronos/application/retry_policy"
+require "chronos/application/circuit_breaker"
+require "chronos/application/remote_configuration"
+require "chronos/application/delivery_pipeline"
 require "chronos/application/capture_exception"
 require "chronos/agent"
 
@@ -27,7 +32,7 @@ require "chronos/agent"
 #
 # @responsibility Configure the agent and expose its small lifecycle API.
 # @motivation Give applications a stable entry point while internals evolve.
-# @limits Version 0.2 captures Ruby exceptions manually; integrations arrive later.
+# @limits Version 0.3 captures Ruby exceptions manually; integrations arrive later.
 # @collaborators Configuration and Agent.
 # @thread_safety Agent replacement and lookup are protected by a mutex.
 # @compatibility Ruby 2.2.10 through Ruby 2.6.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: chronos-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.0.pre.1
+  version: 0.3.0.pre.1
 platform: ruby
 authors:
 - Antonio Jefferson
@@ -93,6 +93,7 @@ files:
 - docs/adr/ADR-004-bounded-queue.md
 - docs/adr/ADR-005-sanitize-before-backlog.md
 - docs/adr/ADR-006-versioned-event-contract.md
+- docs/adr/ADR-011-bounded-resilience-and-remote-control.md
 - docs/architecture.md
 - docs/compatibility.md
 - docs/configuration.md
@@ -101,6 +102,8 @@ files:
 - docs/modules/async-queue.md
 - docs/modules/configuration.md
 - docs/modules/notice-pipeline.md
+- docs/modules/remote-configuration.md
+- docs/modules/retry-backlog.md
 - docs/modules/sanitization.md
 - docs/modules/serialization.md
 - docs/modules/transport.md
@@ -113,6 +116,10 @@ files:
 - lib/chronos/agent.rb
 - lib/chronos/application.rb
 - lib/chronos/application/capture_exception.rb
+- lib/chronos/application/circuit_breaker.rb
+- lib/chronos/application/delivery_pipeline.rb
+- lib/chronos/application/remote_configuration.rb
+- lib/chronos/application/retry_policy.rb
 - lib/chronos/configuration.rb
 - lib/chronos/core.rb
 - lib/chronos/core/backtrace_parser.rb
@@ -127,6 +134,7 @@ files:
 - lib/chronos/errors.rb
 - lib/chronos/internal.rb
 - lib/chronos/internal/bounded_queue.rb
+- lib/chronos/internal/memory_backlog.rb
 - lib/chronos/internal/safe_logger.rb
 - lib/chronos/internal/worker_pool.rb
 - lib/chronos/ports.rb