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

data/lib/chronos/core/breadcrumb.rb

@@ -0,0 +1,126 @@
+require "json"
+require "time"
+
+module Chronos
+  module Core
+    # Immutable, bounded diagnostic marker attached to an execution.
+    #
+    # @responsibility Normalize one breadcrumb without retaining raw application objects.
+    # @motivation Preserve useful events leading to an exception with predictable memory use.
+    # @limits It does not capture logs, SQL, bodies, or HTTP calls automatically.
+    # @collaborators SafeSerializer and BreadcrumbBuffer.
+    # @thread_safety Immutable after construction.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   breadcrumb.to_h #=> {"category"=>"custom", ...}
+    # @errors Unserializable metadata is replaced by SafeSerializer placeholders.
+    # @performance Metadata traversal has strict depth, node, item, and byte limits.
+    class Breadcrumb
+      CATEGORIES = %w(custom log request query external_http cache job).freeze
+
+      def initialize(attributes, clock = nil, max_bytes = 2048)
+        attributes = {} unless attributes.is_a?(Hash)
+        clock ||= proc { Time.now }
+        serializer = SafeSerializer.new(
+          :max_depth => 5, :max_keys => 20, :max_items => 20,
+          :max_string_bytes => 512, :max_nodes => 100
+        )
+        @data = serializer.call(build_data(attributes, clock))
+        @data = compact_data(@data, max_bytes) if JSON.generate(@data).bytesize > max_bytes
+        deep_freeze(@data)
+        freeze
+      end
+
+      def to_h
+        @data
+      end
+
+      private
+
+      def build_data(attributes, clock)
+        category = value(attributes, :category).to_s
+        category = "custom" unless CATEGORIES.include?(category)
+        {
+          "category" => category,
+          "message" => value(attributes, :message).to_s,
+          "metadata" => value(attributes, :metadata) || {},
+          "timestamp" => clock.call.utc.iso8601(6)
+        }
+      end
+
+      def compact_data(data, max_bytes)
+        message_limit = [max_bytes / 4, 32].max
+        compacted = {
+          "category" => data["category"],
+          "message" => SafeSerializer.new.call(data["message"], :max_string_bytes => message_limit),
+          "metadata" => {"_truncated" => true},
+          "timestamp" => data["timestamp"]
+        }
+        trim_compacted_message(compacted, max_bytes)
+      end
+
+      def trim_compacted_message(compacted, max_bytes)
+        while JSON.generate(compacted).bytesize > max_bytes && !compacted["message"].empty?
+          length = [compacted["message"].bytesize - 16, 0].max
+          compacted["message"] = SafeSerializer.new.call(
+            compacted["message"].byteslice(0, length).to_s,
+            :max_string_bytes => length
+          )
+        end
+        compacted
+      end
+
+      def value(attributes, key)
+        attributes.key?(key) ? attributes[key] : attributes[key.to_s]
+      end
+
+      def deep_freeze(value)
+        if value.is_a?(Hash)
+          value.each do |key, child|
+            deep_freeze(key)
+            deep_freeze(child)
+          end
+        elsif value.is_a?(Array)
+          value.each { |child| deep_freeze(child) }
+        end
+        value.freeze
+      end
+    end
+
+    # Fixed-size circular collection of execution breadcrumbs.
+    #
+    # @responsibility Retain only the newest bounded breadcrumbs for one execution.
+    # @motivation Prevent long requests or noisy instrumentation from growing memory indefinitely.
+    # @limits It is process memory only and does not collect events by itself.
+    # @collaborators Breadcrumb and Agent.
+    # @thread_safety Intended for one execution thread; snapshots are immutable values.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   buffer.add(:category => "custom", :message => "started")
+    # @errors Invalid attributes are normalized into a safe breadcrumb.
+    # @performance Add is constant time and storage never exceeds capacity.
+    class BreadcrumbBuffer
+      def initialize(capacity, max_bytes = 2048)
+        raise ArgumentError, "capacity must be a positive integer" unless capacity.is_a?(Integer) && capacity > 0
+
+        @capacity = capacity
+        @max_bytes = max_bytes
+        @items = []
+      end
+
+      def add(attributes)
+        @items.shift if @items.length >= @capacity
+        @items << Breadcrumb.new(attributes, nil, @max_bytes)
+        true
+      end
+
+      def to_a
+        @items.map(&:to_h)
+      end
+
+      def size
+        @items.size
+      end
+    end
+  end
+end

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/integrations/rack/middleware.rb

@@ -0,0 +1,152 @@
+require "securerandom"
+
+module Chronos
+  module Integrations
+    module Rack
+      # Captures unhandled Rack exceptions while preserving Rack semantics.
+      #
+      # @responsibility Build bounded request context, notify Chronos, and re-raise the original exception.
+      # @motivation Provide automatic error capture without coupling the core to Rack.
+      # @limits It never reads rack.input, enumerates response bodies, or infers Rails routes.
+      # @collaborators Rack application and the Chronos facade or Agent.
+      # @thread_safety Shared instances keep no per-request mutable state.
+      # @compatibility Rack 1.x/2.x protocol; Ruby 2.2.10 through Ruby 2.6.
+      # @example
+      #   use Chronos::Integrations::Rack::Middleware
+      # @errors Notification failures are contained; the application exception is always re-raised.
+      # @performance Adds bounded hash construction and monotonic-clock reads per request.
+      class Middleware
+        def initialize(app, options = {})
+          @app = app
+          @notifier = options[:notifier] || Chronos
+          @include_user_agent = options[:include_user_agent] || false
+          @clock = options[:clock] || proc { monotonic_time }
+        end
+
+        def call(env)
+          started_at = @clock.call
+          base = request_capture_context(env)
+          @notifier.with_context(base) do
+            add_request_breadcrumb("request started", base)
+            call_application(env, base, started_at)
+          end
+        end
+
+        private
+
+        def call_application(env, base, started_at)
+          response = @app.call(env)
+          status = response[0]
+          headers = response[1]
+          add_request_breadcrumb("request completed", dynamic_request_context(base, status, headers, started_at))
+          response
+        rescue Exception => error # rubocop:disable Lint/RescueException
+          context = dynamic_request_context(base, 500, nil, started_at)
+          notify_safely(error, context)
+          raise
+        end
+
+        def notify_safely(error, context)
+          @notifier.notify(error, context)
+        rescue StandardError
+          false
+        end
+
+        def request_capture_context(env)
+          request = request_values(env)
+          {
+            :context => {"request" => request, "trace_id" => trace_id(env)},
+            :parameters => parameters(env),
+            :user => hash_value(env["chronos.user"])
+          }
+        end
+
+        def request_values(env)
+          values = {
+            "method" => env["REQUEST_METHOD"].to_s,
+            "route" => normalized_route(env),
+            "request_id" => request_id(env),
+            "host" => (env["HTTP_HOST"] || env["SERVER_NAME"]).to_s,
+            "path" => env["PATH_INFO"].to_s,
+            "controller" => controller_action(env, "controller"),
+            "action" => controller_action(env, "action")
+          }
+          values["user_agent"] = env["HTTP_USER_AGENT"].to_s if @include_user_agent
+          values
+        end
+
+        def dynamic_request_context(base, status, headers, started_at)
+          request = base[:context]["request"].merge(
+            "status" => status.to_i,
+            "duration_ms" => ((@clock.call - started_at) * 1000.0).round(3),
+            "response_size" => response_size(headers)
+          )
+          {:context => base[:context].merge("request" => request)}
+        end
+
+        def parameters(env)
+          result = {}
+          [env["rack.request.query_hash"], env["action_dispatch.request.query_parameters"],
+           env["action_dispatch.request.path_parameters"], env["chronos.parameters"]].each do |candidate|
+            result.merge!(candidate) if candidate.is_a?(Hash)
+          end
+          result
+        rescue StandardError
+          {}
+        end
+
+        def normalized_route(env)
+          explicit = env["chronos.route"] || env["action_dispatch.route_uri_pattern"]
+          return explicit.to_s unless explicit.to_s.empty?
+
+          env["PATH_INFO"].to_s.split("/").map { |part| dynamic_segment?(part) ? ":id" : part }.join("/")
+        end
+
+        def dynamic_segment?(segment)
+          segment =~ /\A\d+\z/ || segment =~ /\A[0-9a-f]{8}-[0-9a-f-]{27,}\z/i
+        end
+
+        def controller_action(env, key)
+          explicit = env["chronos.#{key}"]
+          paths = env["action_dispatch.request.path_parameters"]
+          explicit || (paths[key] if paths.is_a?(Hash)) || (paths[key.to_sym] if paths.is_a?(Hash))
+        end
+
+        def request_id(env)
+          env["chronos.request_id"] || env["action_dispatch.request_id"] || env["HTTP_X_REQUEST_ID"]
+        end
+
+        def trace_id(env)
+          env["chronos.trace_id"] || SecureRandom.uuid
+        end
+
+        def response_size(headers)
+          return nil unless headers.respond_to?(:each)
+
+          pair = headers.find { |key, _value| key.to_s.casecmp("content-length").zero? }
+          pair ? pair[1].to_i : nil
+        rescue StandardError
+          nil
+        end
+
+        def add_request_breadcrumb(message, context)
+          request = context[:context]["request"]
+          @notifier.add_breadcrumb(
+            :category => "request", :message => message,
+            :metadata => {"method" => request["method"], "route" => request["route"], "status" => request["status"]}
+          )
+        end
+
+        def hash_value(value)
+          value.is_a?(Hash) ? value : {}
+        end
+
+        def monotonic_time
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        rescue StandardError
+          Time.now.to_f
+        end
+      end
+    end
+  end
+end

data/lib/chronos/integrations/rack.rb

@@ -0,0 +1,12 @@
+module Chronos
+  module Integrations
+    # Rack protocol integrations that do not require Rack at gem load time.
+    #
+    # @responsibility Namespace Rack-compatible middleware.
+    # @motivation Permit optional use without adding a runtime Rack dependency.
+    # @limits It does not provide Rails-specific route discovery.
+    # @thread_safety Middleware instances may be shared by concurrent Rack threads.
+    # @compatibility Rack 1.x and 2.x protocol shapes on Ruby 2.2.10 through Ruby 2.6.
+    module Rack; end
+  end
+end

data/lib/chronos/integrations.rb

@@ -0,0 +1,10 @@
+module Chronos
+  # Optional framework entry points kept outside the framework-independent core.
+  #
+  # @responsibility Namespace integration adapters such as Rack middleware.
+  # @motivation Keep framework loading optional for plain Ruby applications.
+  # @limits Integrations may depend only on documented public agent behavior.
+  # @thread_safety Each integration documents its own guarantees.
+  # @compatibility Version 0.4 supports Rack protocol behavior on Ruby 2.2.10 through 2.6.
+  module Integrations; end
+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/context_store.rb

@@ -0,0 +1,22 @@
+module Chronos
+  module Ports
+    # Conceptual storage port for execution-scoped context.
+    #
+    # @responsibility Define get, set, clear, and scoped context behavior.
+    # @motivation Let integrations isolate request state without depending on a thread implementation.
+    # @limits The port does not prescribe thread, fiber, or distributed propagation semantics.
+    # @collaborators Agent and context-store adapters.
+    # @thread_safety Implementations must isolate concurrent executions.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   Chronos::Ports::ContextStore.compatible?(store) #=> true
+    # @errors Compatibility checks never invoke application methods.
+    module ContextStore
+      REQUIRED_METHODS = [:get, :set, :clear, :with_context].freeze
+
+      def self.compatible?(object)
+        REQUIRED_METHODS.all? { |method_name| object.respond_to?(method_name) }
+      end
+    end
+  end
+end

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.4.0.pre.1".freeze
 end

data/lib/chronos.rb

@@ -16,18 +16,29 @@ require "chronos/core/sanitizer"
 require "chronos/core/safe_serializer"
 require "chronos/core/payload_serializer"
 require "chronos/ports/transport"
+require "chronos/ports/context_store"
 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/adapters/thread_local_context_store"
+require "chronos/core/breadcrumb"
+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"
+require "chronos/integrations"
+require "chronos/integrations/rack"
+require "chronos/integrations/rack/middleware"
 
 # Framework-independent public facade for the Chronos Ruby 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.4 captures Rack failures but does not install middleware automatically.
 # @collaborators Configuration and Agent.
 # @thread_safety Agent replacement and lookup are protected by a mutex.
 # @compatibility Ruby 2.2.10 through Ruby 2.6.
@@ -70,6 +81,20 @@ module Chronos
       false
     end
 
+    def with_context(context = {})
+      agent = current_agent
+      return yield unless agent
+
+      agent.with_context(context) { yield }
+    end
+
+    def add_breadcrumb(attributes = {})
+      agent = current_agent
+      agent ? agent.add_breadcrumb(attributes) : false
+    rescue StandardError
+      false
+    end
+
     def configured?
       !current_agent.nil?
     end

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.4.0.pre.1
 platform: ruby
 authors:
 - Antonio Jefferson
@@ -87,12 +87,15 @@ files:
 - README.md
 - SECURITY.md
 - contracts/event-v1.schema.json
+- contracts/rack-context-v1.schema.json
 - docs/adr/ADR-001-core-and-integrations.md
 - docs/adr/ADR-002-version-lines.md
 - docs/adr/ADR-003-net-http-legacy-transport.md
 - 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/adr/ADR-012-rack-context-isolation.md
 - docs/architecture.md
 - docs/compatibility.md
 - docs/configuration.md
@@ -101,6 +104,9 @@ files:
 - docs/modules/async-queue.md
 - docs/modules/configuration.md
 - docs/modules/notice-pipeline.md
+- docs/modules/rack-context.md
+- docs/modules/remote-configuration.md
+- docs/modules/retry-backlog.md
 - docs/modules/sanitization.md
 - docs/modules/serialization.md
 - docs/modules/transport.md
@@ -110,12 +116,18 @@ files:
 - lib/chronos.rb
 - lib/chronos/adapters.rb
 - lib/chronos/adapters/net_http_transport.rb
+- lib/chronos/adapters/thread_local_context_store.rb
 - 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
+- lib/chronos/core/breadcrumb.rb
 - lib/chronos/core/exception_cause_collector.rb
 - lib/chronos/core/notice.rb
 - lib/chronos/core/notice_builder.rb
@@ -125,11 +137,16 @@ files:
 - lib/chronos/core/sanitizer.rb
 - lib/chronos/core/sensitive_value_filter.rb
 - lib/chronos/errors.rb
+- lib/chronos/integrations.rb
+- lib/chronos/integrations/rack.rb
+- lib/chronos/integrations/rack/middleware.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
+- lib/chronos/ports/context_store.rb
 - lib/chronos/ports/transport.rb
 - lib/chronos/ruby.rb
 - lib/chronos/ruby/version.rb