chronos-ruby 0.1.0.pre.2 → 0.3.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