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

data/lib/chronos/adapters/net_http_transport.rb

@@ -1,5 +1,6 @@
 require "net/http"
 require "openssl"
+require "json"
 require "stringio"
 require "uri"
 require "zlib"
@@ -10,16 +11,17 @@ module Chronos
     #
     # @responsibility Send serialized events over bounded HTTPS requests.
     # @motivation Use the Ruby standard library to preserve legacy compatibility.
-    # @limits It classifies failures but does not retry or persist events in version 0.2.
+    # @limits It classifies failures but leaves retry and backlog policy to the application layer.
     # @collaborators Configuration::Snapshot, SerializedEvent, and TransportResult.
     # @thread_safety Creates a new Net::HTTP connection per call and synchronizes health state.
     # @compatibility Ruby 2.2.10 through Ruby 2.6; no Rails dependency.
     # @example
     #   result = transport.send_event(serialized_event)
     # @errors Network, TLS, and HTTP errors are returned, never raised to callers.
-    # @performance One bounded network request per event in version 0.2.
+    # @performance One bounded network request per delivery attempt in version 0.3.
     class NetHttpTransport
       EVENT_PATH = "/api/v1/events".freeze
+      REMOTE_CONFIGURATION_HEADER = "X-Chronos-Remote-Configuration".freeze
 
       def initialize(config, logger = nil)
         @config = config
@@ -100,7 +102,11 @@ module Chronos
       def classify(response)
         code = response.code.to_i
         options = {:status_code => code}
-        return Ports::TransportResult.new(:success, options) if code >= 200 && code < 300
+        if code >= 200 && code < 300
+          options[:remote_configuration] = parse_remote_configuration(response)
+          return Ports::TransportResult.new(:success, options)
+        end
+        return Ports::TransportResult.new(:request_timeout, options) if code == 408
         if code == 429
           options[:retry_after] = response["Retry-After"]
           return Ports::TransportResult.new(:rate_limited, options)
@@ -110,6 +116,18 @@ module Chronos
         Ports::TransportResult.new(:client_error, options)
       end
 
+      def parse_remote_configuration(response)
+        return nil unless @config.remote_configuration
+
+        value = response[REMOTE_CONFIGURATION_HEADER]
+        return nil if value.nil? || value.bytesize > @config.remote_config_max_bytes
+
+        parsed = JSON.parse(value)
+        parsed.is_a?(Hash) ? parsed : nil
+      rescue JSON::ParserError, EncodingError
+        nil
+      end
+
       def request_body(body)
         return body unless @config.gzip
 

data/lib/chronos/agent.rb

@@ -1,10 +1,10 @@
 module Chronos
   # Runtime composition root for the framework-independent Chronos agent.
   #
-  # @responsibility Own transport, queue, workers, and the capture use case.
+  # @responsibility Own transport, resilient delivery pipeline, and the capture use case.
   # @motivation Keep construction details outside the public module facade.
   # @limits It does not integrate with Rails, Rack, or job systems.
-  # @collaborators Configuration snapshot, CaptureException, BoundedQueue, and NetHttpTransport.
+  # @collaborators Configuration snapshot, CaptureException, DeliveryPipeline, and NetHttpTransport.
   # @thread_safety Runtime collaborators synchronize mutable state.
   # @compatibility Ruby 2.2.10 through Ruby 2.6.
   # @example
@@ -23,9 +23,16 @@ module Chronos
       unless Ports::Transport.compatible?(@transport)
         raise ArgumentError, "transport does not implement the Chronos transport port"
       end
-      @queue = options[:queue] || Internal::BoundedQueue.new(config.queue_size)
-      @worker_pool = options[:worker_pool] || Internal::WorkerPool.new(@queue, @transport, config.workers, @logger)
-      @capture = options[:capture] || Application::CaptureException.new(config, @worker_pool, @transport, @logger)
+      pipeline_options = {}
+      pipeline_options[:queue] = options[:queue] if options[:queue]
+      pipeline_options[:worker_pool] = options[:worker_pool] if options[:worker_pool]
+      @delivery_pipeline = options[:delivery_pipeline] || Application::DeliveryPipeline.new(
+        config,
+        @transport,
+        @logger,
+        pipeline_options
+      )
+      @capture = options[:capture] || Application::CaptureException.new(config, @delivery_pipeline, @logger)
     end
 
     def notify(exception, context = {})
@@ -37,21 +44,22 @@ module Chronos
     end
 
     def flush(timeout = DEFAULT_FLUSH_TIMEOUT)
-      @worker_pool.flush(timeout)
+      @delivery_pipeline.flush(timeout)
     rescue StandardError => error
       @logger.warn("Chronos flush failed: #{error.class}")
       false
     end
 
     def close(timeout = DEFAULT_FLUSH_TIMEOUT)
-      @worker_pool.close(timeout)
+      @delivery_pipeline.close(timeout)
     rescue StandardError => error
       @logger.warn("Chronos close failed: #{error.class}")
       false
     end
 
     def diagnostics
-      @queue.stats
+      details = @delivery_pipeline.diagnostics
+      details[:queue].merge(details)
     end
   end
 end

data/lib/chronos/application/capture_exception.rb

@@ -2,10 +2,10 @@ module Chronos
   module Application
     # Orchestrates exception normalization, serialization, queueing, and delivery.
     #
-    # @responsibility Execute the version 0.2 exception capture pipeline.
+    # @responsibility Execute the version 0.3 exception capture pipeline.
     # @motivation Keep the public facade and transport adapters free of use-case logic.
-    # @limits It does not implement sampling, retry, backlog, or framework hooks.
-    # @collaborators NoticeBuilder, PayloadSerializer, WorkerPool, and Transport.
+    # @limits It does not implement framework hooks or automatic capture.
+    # @collaborators NoticeBuilder, PayloadSerializer, and DeliveryPipeline.
     # @thread_safety Collaborators are immutable or synchronized; calls may run concurrently.
     # @compatibility Ruby 2.2.10 through Ruby 2.6; independent of Rails.
     # @example
@@ -13,20 +13,25 @@ module Chronos
     # @errors All internal StandardError failures are contained and logged.
     # @performance Local work is bounded before asynchronous queue insertion.
     class CaptureException
-      def initialize(config, worker_pool, transport, logger = nil, options = {})
+      def initialize(config, delivery_pipeline, logger = nil, options = {})
         @config = config
-        @worker_pool = worker_pool
-        @transport = transport
+        @delivery_pipeline = delivery_pipeline
         @logger = logger || Internal::SafeLogger.new(config.logger)
         @notice_builder = options[:notice_builder] || Core::NoticeBuilder.new(config)
-        @serializer = options[:serializer] || Core::PayloadSerializer.new(config)
+        @serializer = options[:serializer] || Core::PayloadSerializer.new(
+          config,
+          nil,
+          :max_payload_size => proc { @delivery_pipeline.max_payload_size }
+        )
       end
 
       def call(exception, context = {})
         return false unless capture_enabled?
 
-        event = build_event(exception, context)
-        @worker_pool.enqueue(event)
+        notice = build_notice(exception, context)
+        return false unless @delivery_pipeline.capture_allowed?("exception", notice.fingerprint)
+
+        @delivery_pipeline.enqueue(@serializer.call(notice))
       rescue StandardError => error
         diagnose(error)
         false
@@ -35,8 +40,10 @@ module Chronos
       def call_sync(exception, context = {})
         return false unless capture_enabled?
 
-        event = build_event(exception, context)
-        @transport.send_event(event).success?
+        notice = build_notice(exception, context)
+        return false unless @delivery_pipeline.capture_allowed?("exception", notice.fingerprint)
+
+        @delivery_pipeline.deliver_sync(@serializer.call(notice))
       rescue StandardError => error
         diagnose(error)
         false
@@ -48,9 +55,8 @@ module Chronos
         @config.enabled_for_environment? && @config.error_notifications
       end
 
-      def build_event(exception, context)
-        notice = @notice_builder.call(exception, context)
-        @serializer.call(notice)
+      def build_notice(exception, context)
+        @notice_builder.call(exception, context)
       end
 
       def diagnose(error)

data/lib/chronos/application/circuit_breaker.rb

@@ -0,0 +1,70 @@
+module Chronos
+  module Application
+    # Small circuit breaker for retryable transport failures.
+    #
+    # @responsibility Stop delivery attempts temporarily after repeated failures.
+    # @motivation Prevent retry storms while the Chronos endpoint is unavailable.
+    # @limits It keeps no payload and permits only one half-open probe.
+    # @collaborators DeliveryPipeline and a monotonic clock.
+    # @thread_safety All transitions are protected by a mutex.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   transport.send_event(event) if breaker.allow_request?
+    # @errors Clock failures are contained by DeliveryPipeline.
+    # @performance Constant time with fixed memory.
+    class CircuitBreaker
+      def initialize(failure_threshold, reset_timeout, clock)
+        @failure_threshold = failure_threshold
+        @reset_timeout = reset_timeout
+        @clock = clock
+        @state = :closed
+        @failures = 0
+        @opened_at = nil
+        @probe_in_flight = false
+        @mutex = Mutex.new
+      end
+
+      def allow_request?
+        @mutex.synchronize do
+          return true if @state == :closed
+          return false if @state == :half_open && @probe_in_flight
+          return false unless reset_elapsed?
+
+          @state = :half_open
+          @probe_in_flight = true
+          true
+        end
+      end
+
+      def record_success
+        @mutex.synchronize do
+          @state = :closed
+          @failures = 0
+          @opened_at = nil
+          @probe_in_flight = false
+        end
+      end
+
+      def record_failure
+        @mutex.synchronize do
+          @failures += 1
+          if @state == :half_open || @failures >= @failure_threshold
+            @state = :open
+            @opened_at = @clock.call
+          end
+          @probe_in_flight = false
+        end
+      end
+
+      def state
+        @mutex.synchronize { @state }
+      end
+
+      private
+
+      def reset_elapsed?
+        @opened_at && (@clock.call - @opened_at >= @reset_timeout)
+      end
+    end
+  end
+end

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