chronos-ruby 0.1.0.pre.2 → 0.3.0.pre.1

data/docs/modules/serialization.md

@@ -0,0 +1,9 @@
+# Safe serialization module
+
+`Chronos::Core::SafeSerializer` converts sanitized values into JSON primitives without invoking `to_json` or `to_s` on arbitrary application objects. Unknown objects become a class-name placeholder.
+
+The serializer limits depth, visited nodes, hash keys, array items, key bytes, and string bytes. It detects circular hashes and arrays, repairs invalid UTF-8, and contains unreadable values. These structural budgets bound processing time and memory without using asynchronous interruption such as `Timeout` inside application code.
+
+`PayloadSerializer` owns the versioned event envelope and composes `Sanitizer` before `SafeSerializer`. If the resulting JSON exceeds `max_payload_size`, caller-controlled fields are compacted. An event that still cannot fit is rejected before queueing.
+
+The serializer is stateless across calls and safe for concurrent capture. Tests in `spec/unit/core/safe_serializer_spec.rb` and `spec/unit/core/payload_serializer_spec.rb` cover unsafe objects, cycles, invalid encoding, structural limits, and total payload limits.

data/docs/modules/transport.md

@@ -2,8 +2,10 @@
 
 `Chronos::Ports::Transport` defines delivery behavior. `Chronos::Adapters::NetHttpTransport` implements it with the Ruby standard library.
 
-Each event uses bounded open and read timeouts. TLS verification is enabled by default. Authentication and idempotency values are headers. Redirects are not followed. Statuses are classified as success, client error, rate limited, server error, network error, or closed.
+Each event uses bounded open and read timeouts. TLS verification is enabled by default. Authentication and idempotency values are headers. Redirects are not followed. Statuses are classified as success, request timeout, client error, rate limited, server error, network error, or closed. HTTP `408`, `429`, `5xx`, and network failures are retryable; other `4xx` responses are permanent.
 
-The adapter creates a connection per event in version 0.1. This is conservative for legacy applications and avoids shared socket lifecycle state. Batch optimization and retry may be added behind the same port.
+The adapter creates a connection per event in version 0.3. This is conservative for legacy applications and avoids shared socket lifecycle state. Retry remains in `DeliveryPipeline`, behind the transport port.
 
-Risks include proxy credential exposure, TLS incompatibility on old operating systems, and endpoint latency. Tests use a local fake HTTP server to verify headers, `2xx`, `429`, `500`, timeout, and invalid TLS behavior.
+A successful response may contain `X-Chronos-Remote-Configuration`. The adapter rejects the header when it exceeds `remote_config_max_bytes` or is not a JSON object. It never interprets policy or accepts remote endpoint and credential changes; that allowlist belongs to `RemoteConfiguration`.
+
+Risks include proxy credential exposure, TLS incompatibility on old operating systems, endpoint latency, and stale remote policy until another response arrives. Tests use a local fake HTTP server to verify headers, `2xx`, `408`, `429`, `500`, timeout, invalid TLS, and bounded remote policy parsing.

data/docs/performance.md

@@ -1,16 +1,53 @@
 # Performance
 
-Performance is a functional requirement, but version 0.1 makes no unverified speed claim.
+Performance is a functional requirement, but version 0.3 makes no unverified speed claim.
 
 Current controls:
 
 - backtraces are limited to 200 frames;
 - hashes and arrays are bounded during serialization;
 - strings and total payload size are bounded;
+- sanitizer traversal and serializer node count are bounded by the event structure;
 - the asynchronous queue has fixed capacity;
 - worker count is fixed and threads start lazily;
 - producers never wait for queue capacity;
 - HTTP open and read timeouts are explicit;
+- retry count, delay, jitter, and `Retry-After` are capped;
+- the circuit breaker suppresses requests during sustained failure;
+- retry backlog capacity is fixed and may be disabled;
 - shutdown and flush have caller-controlled timeouts.
 
-Run the scripts under `benchmarks/` and record Ruby version, operating system, CPU, warmup, iteration count, median, and dispersion before publishing results. Request overhead is not measured because automatic request integration is outside version 0.1.
+Run the scripts under `benchmarks/` and record Ruby version, operating system, CPU, warmup, iteration count, median, and dispersion before publishing results. `benchmarks/filtering.rb` measures privacy filtering, while `benchmarks/retry_backlog.rb` measures fixed-memory behavior with an unavailable in-memory transport. Request overhead is not measured because automatic request integration is outside version 0.3.
+
+## Version 0.2 development measurement
+
+A local diagnostic run on 2026-07-19 used macOS arm64 (`T8103`), legacy x86_64 Ruby builds, 100 warmup iterations, and 500 measured iterations per script:
+
+| Runtime | Asynchronous local capture | Full serialization | Privacy filtering fixture |
+|---|---:|---:|---:|
+| Ruby 2.2.10 | 1,857 µs/event | 4,047 µs/event | 798 µs/pass |
+| Ruby 2.6.3 | 1,904 µs/event | 4,705 µs/event | 1,037 µs/pass |
+
+The capture benchmark uses an in-memory transport and includes queue draining. The serialization fixture contains 20 backtrace frames; the filtering fixture contains nested fields and 20 repeated items. These are single aggregate development runs, not published performance claims: they do not provide median or dispersion and must be repeated on controlled hardware before comparison with another agent.
+
+## Version 0.3 resilience benchmark
+
+Run:
+
+```bash
+ITERATIONS=10000 bundle _1.17.3_ exec ruby benchmarks/retry_backlog.rb
+```
+
+The benchmark opens the circuit after one synthetic network failure, retains at most 100 serialized events, and measures bounded rejection into a full backlog. It performs no network I/O and is intended to detect accidental unbounded growth or excessive control-path overhead, not to claim production throughput.
+
+A local diagnostic run on 2026-07-20 used Ruby 2.2.10 on macOS arm64 with 1,000 capture, serialization, and filtering iterations plus 10,000 queue and outage iterations:
+
+| Measurement | Result |
+|---|---:|
+| Asynchronous local capture | 1,824 µs/event |
+| Full serialization | 3,961 µs/event |
+| Privacy filtering fixture | 777 µs/pass |
+| Bounded queue | 1,648,533 operations/second |
+| Open-circuit backlog handling | 88,922 operations/second |
+
+The outage run retained exactly 100 events and rejected 9,900 additional events without growing the backlog. These are single development runs without median or dispersion and are not comparative performance claims.

data/docs/privacy-lgpd.md

@@ -1,16 +1,86 @@
 # Privacy and LGPD
 
-Version 0.1 enforces structural limits but does not yet implement the recursive sensitive-data sanitizer planned for version 0.2.
+Version 0.3 sanitizes every exception event before JSON serialization, queueing, retry backlog, or transport. This reduces accidental exposure, but the host application remains responsible for lawful purpose, minimization, access control, retention, and responses to data-subject requests.
 
-Applications must not pass passwords, tokens, authorization headers, cookies, session secrets, private keys, card data, CPF, CNPJ, health data, or other unnecessary personal information.
+## Default policy
 
-Recommended practice:
+| Data | Default behavior |
+|---|---|
+| Keys such as `password`, `secret`, `token`, `authorization`, `cookie`, `session`, `card_number`, `cpf`, and `cnpj` | Replaced with `[FILTERED]` |
+| Bearer tokens and JWT-like strings | Replaced in free text |
+| E-mail addresses | Replaced with `[FILTERED_EMAIL]` |
+| CPF and CNPJ candidates with valid check digits | Replaced with `[FILTERED_DOCUMENT]` |
+| Payment-card candidates that pass the Luhn check | Replaced with `[FILTERED_CARD]` |
+| IPv4 addresses | Last octet replaced with `0` |
+| Unknown Ruby objects | Represented by class name without calling application serialization |
+| Request/response bodies, cookies, HTTP headers, SQL binds, environment variables | Never collected automatically in version 0.3 |
 
-1. pass opaque internal identifiers instead of names or e-mail addresses;
-2. allowlist context fields in application code;
-3. inspect payloads against a local fake server before production;
-4. keep TLS verification enabled;
-5. document the lawful purpose and retention policy in the SaaS;
-6. disable the agent in environments where collection is not authorized.
+The retry backlog exists only in process memory, accepts only `SerializedEvent`, has a fixed capacity, and disappears on process exit. Version 0.3 does not persist telemetry to disk.
 
-Version 0.1 limits object depth, hash keys, array items, string bytes, backtrace frames, queue capacity, and total payload size. Unknown Ruby objects are represented by class name without calling their `to_json` implementation.
+Blocklist matching accepts `String`, `Symbol`, and `Regexp`. String and Symbol matching is case-insensitive after punctuation normalization and also protects namespaced keys such as `user_password`.
+
+## Configuration
+
+```ruby
+Chronos.configure do |config|
+  # required connection settings omitted
+  config.blocklist_keys += [:medical_record, /bank_account/i]
+  config.allowlist_keys += [:authorization_state]
+  config.hash_keys += [:customer_id]
+  config.anonymize_ip = true
+
+  config.filters << proc do |key, value|
+    key.to_s == "internal_reference" ? "[REMOVED]" : value
+  end
+end
+```
+
+An allowlisted key bypasses only key-name redaction. Content detection remains active, so an allowlisted field containing a Bearer token or e-mail address is still filtered. Identifier hashing uses SHA-256 scoped by the public project identifier. It is irreversible output, but low-entropy identifiers may still be guessable and should not be treated as anonymized data.
+
+Custom filters receive the key and already sanitized value. If a filter raises, that field becomes `[FILTERED]`; the error does not escape into the host application.
+
+## Health applications
+
+Do not send diagnoses, exam results, prescriptions, patient names, or free-form clinical notes. Use a scoped opaque identifier only when it is necessary and authorized:
+
+```ruby
+config.blocklist_keys += [:patient_name, :diagnosis, :clinical_notes]
+config.hash_keys += [:patient_id]
+
+Chronos.notify(error, :context => {
+  "operation" => "schedule_exam",
+  "patient_id" => "internal-opaque-id"
+})
+```
+
+## Financial applications
+
+Do not send cardholder names, full account identifiers, CVV, authentication tokens, or transaction payloads. Prefer categorical operational context:
+
+```ruby
+config.blocklist_keys += [:account_number, :pix_key, :bank_payload]
+config.hash_keys += [:customer_id]
+
+Chronos.notify(error, :context => {
+  "operation" => "authorize_payment",
+  "provider" => "example-gateway",
+  "customer_id" => "internal-opaque-id"
+})
+```
+
+## Payload audit procedure
+
+1. Point `host` to a local fake HTTP server controlled by the development team.
+2. Exercise representative exception paths with synthetic sensitive fixtures.
+3. Inspect the final JSON body, including exception messages and causes.
+4. Search for every fixture value in plaintext.
+5. Add missing application keys to `blocklist_keys` and repeat the audit.
+6. Keep the audit fixtures synthetic and run the privacy contract in CI.
+
+Run the included local example with:
+
+```bash
+bundle _1.17.3_ exec ruby examples/plain-ruby/privacy_audit.rb
+```
+
+The output must contain redaction placeholders and must not contain any fixture secret.

data/docs/troubleshooting.md

@@ -10,7 +10,7 @@ The agent may be unconfigured, disabled, ignored in the current environment, una
 
 ## `Chronos.notify_sync` returns false
 
-Check DNS, TLS certificates, credentials, HTTP status, proxy configuration, and timeout values. Version 0.1 does not retry.
+Check DNS, TLS certificates, credentials, HTTP status, proxy configuration, and timeout values. Version 0.3 retries only network errors, HTTP `408`, `429`, and `5xx` responses. Inspect `agent.diagnostics` when constructing an agent directly to see retry state, backlog usage, and the circuit state.
 
 ## Events disappear during shutdown
 
@@ -22,4 +22,4 @@ Workers are recreated after a process fork. Configure before or after forking, t
 
 ## Sensitive data
 
-Version 0.1 does not redact arbitrary context. Stop sending the affected field, rotate exposed credentials, and follow the incident process for the Chronos SaaS.
+Stop sending the affected field, rotate exposed credentials, and follow the incident process for the Chronos SaaS. Add the application-specific key to `blocklist_keys`, create a privacy contract fixture, and repeat the local payload audit. Pattern detection is defensive and cannot recognize every domain-specific identifier.

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.1.
+    # @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.1.
+    # @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.1 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 advanced sanitization, sampling, retry, or backlog.
-    # @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