debugbundle 2.0.0 → 2.1.0

data/lib/debugbundle/client.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 require 'digest'
+require 'English'
 require 'json'
 require 'set'
 require 'time'
 
 require 'debugbundle/client_event_support'
+require 'debugbundle/client_exception_support'
+require 'debugbundle/client_evidence_support'
 require 'debugbundle/client_process_support'
 require 'debugbundle/client_queue_support'
 require 'debugbundle/config_worker'
@@ -91,6 +94,9 @@ module DebugBundle
     def initialize(transport: nil, time_provider: nil, random_provider: nil, config_fetcher: nil, **options)
       @owner_pid = Process.pid
       @config = Config.new(**options)
+      @closed = false
+      @retired = false
+      initialize_evidence
       @time_provider = time_provider || -> { Time.now.utc }
       @random_provider = random_provider || -> { rand }
       @redactor = Redaction::Redactor.new(
@@ -99,17 +105,7 @@ module DebugBundle
       @transport = transport || build_default_transport
       @config_fetcher = config_fetcher || build_default_config_fetcher(custom_transport: !transport.nil?)
       @context = {}
-      @buffer = []
-      @buffer_bytes = 0
-      @buffer_priority_counts = [0, 0, 0, 0]
-      @inflight_event_ids = Set.new
-      @inflight_priority_counts = [0, 0, 0, 0]
-      @event_sizes = {}
-      @pressure_drops = {}
-      @hook_bypass = Set.new
-      @finalized_events = {}
-      @buffer_mutex = Mutex.new
-      @flush_mutex = Mutex.new
+      initialize_buffer_ownership
       @probe_buffers = {}
       @suppression = Suppression::Tracker.new
       @last_event_at = nil
@@ -145,46 +141,6 @@ module DebugBundle
       capture_exception_internal(error, context: context, handled: handled, run_before_send: true)
     end
 
-    def capture_exception_internal(error, context:, handled:, run_before_send:)
-      return unless capture_enabled?
-      return unless preflight_capacity?(3, 'exception')
-
-      request_remote_config_poll_if_due
-
-      merged_context = merge_context(context)
-      payload = {
-        'name' => safe_exception_name(error),
-        'message' => safe_exception_message(error),
-        'stack' => safe_exception_stack(error),
-        'handled' => handled,
-        'request' => request_payload(merged_context['request']),
-        'response' => response_payload(merged_context['response']),
-        'runtime' => runtime_payload
-      }
-
-      causes = exception_causes(error)
-
-      probe_data = probe_snapshot
-      payload['probe_data'] = probe_data unless probe_data.empty?
-
-      extra_context = merged_context.except('request', 'response', 'correlation')
-      extra_context['causes'] = causes unless causes.empty?
-
-      event = base_event('backend_exception', payload, extra_context)
-
-      event_payload = event.fetch('payload')
-      suppression_key = [
-        event['event_type'],
-        event_payload['name'],
-        event_payload['message'],
-        event_payload['stack']
-      ].join(':')
-      return unless @suppression.should_capture(suppression_key, now: monotonic_now)
-
-      enqueue_event(event, skip_before_send: !run_before_send)
-    end
-    private :capture_exception_internal
-
     def capture_error(error, context: nil, handled: true) = capture_exception(error, context: context, handled: handled)
 
     def capture_log(message, level: :warning, context: nil)
@@ -363,6 +319,8 @@ module DebugBundle
       return false unless @config_fetcher
 
       response = @config_fetcher.call(@remote_config_etag)
+      return false if @closed
+
       status_code = response.fetch(:status_code, 500)
       if status_code == 304
         schedule_next_remote_config_poll
@@ -373,7 +331,9 @@ module DebugBundle
         return false
       end
 
-      snapshot = RemoteConfig.parse(response.fetch(:body, {}), config.probes_poll_interval)
+      body = response.fetch(:body, {})
+      snapshot = RemoteConfig.parse(body, config.probes_poll_interval)
+      @evidence.observe(body, required: true, valid: !snapshot.nil? && @evidence.valid_config?(body))
       unless snapshot
         schedule_next_remote_config_poll
         return false
@@ -403,8 +363,17 @@ module DebugBundle
 
     def close
       ensure_current_process!
+      @closed = true
+      @operations.clear
+      @evidence = EvidenceDelivery.new
       @delivery_worker&.close
       @config_worker&.close
+      @buffer_mutex.synchronize { discard_closed_buffer_locked }
+    end
+
+    def dispose
+      @retired = true
+      close
     end
 
     def flush_now
@@ -417,20 +386,12 @@ module DebugBundle
         return false if @transport.nil?
         return false if rate_limited?
 
-        # Replace consumed snapshot slots so dropped events do not remain owned
-        # by this batch while later callbacks run or transport waits.
-        prepared = candidates.map! do |event|
-          finalized = finalized_event_for(event)
-          if finalized.nil?
-            remove_buffered_events([event])
-            next
-          end
-          [event, finalized]
-        end.compact
+        prepared = prepare_wire_batch(candidates)
         return true if prepared.empty?
 
         batch = prepared.map(&:first)
         wire_events = prepared.map(&:last)
+        return true if @closed
 
         result = Transport.coerce_result(
           @transport.call(
@@ -442,11 +403,13 @@ module DebugBundle
 
         case result.status_code
         when 200..299
-          handle_successful_result(result, batch)
-        when 429
+          accepted = handle_successful_result(result, batch)
+          @delivery_worker&.wake if @retry_at.nil? && buffered_event_count.positive?
+          accepted
+        when 429, 500..599
           @consecutive_failures += 1
-          retry_after_seconds = (result.retry_after_seconds || 1).clamp(1, RETRY_AFTER_CAP_SECONDS)
-          @retry_at = now + retry_after_seconds
+          retry_after_seconds = bounded_retry_hint(result.retry_after_seconds)
+          @retry_at = now + retry_after_seconds if result.status_code == 429 || !result.retry_after_seconds.nil?
           false
         when 400..499
           remove_buffered_events(batch)
@@ -468,22 +431,30 @@ module DebugBundle
     private :flush_now
 
     def finalized_event_for(event)
+      return nil if @closed
+
       event_id = event['event_id']
       cached, bypass = @buffer_mutex.synchronize do
         [@finalized_events[event_id], @hook_bypass.include?(event_id)]
       end
-      return cached if cached
+      finalized = cached || (bypass || !config.before_send ? event : apply_before_send(event))
+      return nil if finalized.nil? || @closed
 
-      finalized = bypass || !config.before_send ? event : apply_before_send(event)
-      return nil if finalized.nil?
+      finalized = filter_evidence(finalized)
+      return nil unless finalized
       return nil unless post_hook_event_allowed?(finalized)
+      return nil unless reconcile_diagnostic(cached || event, finalized)
 
-      cache_finalized_event(event, finalized)
+      retained = cache_finalized_event(event, finalized)
+      @buffer_mutex.synchronize { release_diagnostics_locked(event, finalized) } unless retained
+      retained
     end
     private :finalized_event_for
 
     def post_hook_event_allowed?(event)
       case event['event_type']
+      when 'diagnostic_context'
+        recovery_allowed? && event.dig('payload', 'kind') == 'recovery'
       when 'log_event'
         return false if @capture_policy.capture_logs == 'off'
 
@@ -515,9 +486,17 @@ module DebugBundle
 
     private
 
+    def bounded_retry_hint(value)
+      return 1 unless value.is_a?(Numeric) && value.real? && value.finite?
+
+      value.clamp(1, RETRY_AFTER_CAP_SECONDS)
+    end
+
     def handle_successful_result(result, batch)
-      decision = Acknowledgement.decide(result.body, batch.length)
-      return handle_protocol_failure if decision[:kind] == :protocol_failure
+      decision = Acknowledgement.decide(result.body, batch.length, required: @transport.is_a?(Transport::HttpTransport))
+      lost_evidence = !@closed && @evidence.observe(result.body, required: @transport.is_a?(Transport::HttpTransport),
+                                                                 valid: decision[:kind] == :acknowledged)
+      return handle_protocol_failure(result.retry_after_seconds) if decision[:kind] == :protocol_failure
 
       if decision[:kind] == :legacy
         remove_buffered_events(batch)
@@ -527,12 +506,13 @@ module DebugBundle
 
       retryable_indices = decision.fetch(:retryable_indices)
       retryable_events = retryable_indices.map { |index| batch.fetch(index) }
+      retryable_events |= downgrade_evidence_errors(batch, decision, lost_evidence)
       remove_buffered_events(batch - retryable_events)
       @last_event_at = now if decision.fetch(:accepted).positive?
 
       if retryable_events.any?
         @consecutive_failures += 1
-        @retry_at = now + 1
+        @retry_at = now + bounded_retry_hint(result.retry_after_seconds)
         @acknowledgement_state = :degraded
         false
       else
@@ -543,9 +523,9 @@ module DebugBundle
       end
     end
 
-    def handle_protocol_failure
+    def handle_protocol_failure(retry_hint)
       @consecutive_failures += 1
-      @retry_at = now + 1
+      @retry_at = now + bounded_retry_hint(retry_hint)
       @acknowledgement_state = :degraded
       false
     end

data/lib/debugbundle/client_event_support.rb

@@ -9,11 +9,12 @@ module DebugBundle
 
       def capture_enabled?
         ensure_current_process!
-        config.enabled? && config.configured?
+        !@closed && config.enabled? && config.configured?
       end
 
       def merge_context(context)
-        merged = @context.merge(stringify_hash(context || {}))
+        scoped = @operations.current&.fetch(:correlation) || {}
+        merged = @context.merge(scoped).merge(stringify_hash(context || {}))
         @redactor.redact_value(merged)
       end
 
@@ -46,7 +47,13 @@ module DebugBundle
         }
       end
 
-      def runtime_payload = Runtime.payload
+      def runtime_payload
+        snapshot = Runtime.payload
+        # Engine metadata belongs in the existing extensible runtime block;
+        # unknown top-level runtime keys are rejected by installed acceptors.
+        extras = snapshot.slice('engine', 'engine_version')
+        snapshot.except('engine', 'engine_version').merge('framework_extras' => extras)
+      end
 
       def exception_causes(error)
         causes = []
@@ -144,15 +151,7 @@ module DebugBundle
         { 'value' => '[REDACTED]' }
       end
 
-      def apply_before_send(event)
-        protected = protect_event(event)
-        return nil unless protected
-
-        prepared = BeforeSend.apply(protected, config.before_send)
-        prepared && protect_event(prepared)
-      end
-
-      def protect_event(event)
+      def protect_event_fields(event)
         return nil unless TelemetryPrivacy.safe_event_identity?(event, additional_fields: config.redact_fields)
 
         fields = TelemetryPrivacy.protect(

data/lib/debugbundle/client_evidence_support.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require 'debugbundle/diagnostic_budget'
+require 'debugbundle/evidence_delivery'
+require 'debugbundle/exception_evidence'
+require 'debugbundle/operation_context'
+require 'debugbundle/event_batch'
+
+module DebugBundle
+  class Client
+    module EvidenceSupport
+      def with_operation_context(kind:, name: nil, limit_ms: nil, correlation: nil)
+        ensure_current_process!
+        unless @closed
+          lease = @operations.begin_scope(kind: kind, name: name, limit_ms: limit_ms, correlation: correlation)
+        end
+        yield
+      ensure
+        @operations.end_scope(lease)
+      end
+
+      def capture_recovery(observation = nil, context: nil, **options)
+        return unless capture_enabled? && recovery_allowed?
+
+        return if observation && !options.empty?
+
+        input = EvidenceValue.options(observation || options)
+        payload = EvidenceWire.recovery(input, @operations.scope)
+        return unless payload
+
+        event = base_event('diagnostic_context', payload, merge_context(context))
+        return unless EvidenceWire.valid_optional?(event)
+
+        enqueue_event(event)
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def apply_before_send(event)
+        protected = protect_event(event)
+        return nil unless protected
+
+        prepared = BeforeSend.apply(protected, config.before_send)
+        return nil unless prepared
+
+        result = protect_event(prepared)
+        return result if prepared.equal?(protected)
+
+        result if result && BeforeSend.valid?(result)
+      end
+
+      def protect_event(event)
+        protected = protect_event_fields(event)
+        return fit_protected_event(protected) if protected && EvidenceWire.valid_optional?(protected)
+
+        legacy = EvidenceWire.without_optional(event)
+        fit_protected_event(legacy && protect_event_fields(legacy))
+      rescue StandardError
+        legacy = EvidenceWire.without_optional(event)
+        fit_protected_event(legacy && protect_event_fields(legacy))
+      end
+
+      def fit_protected_event(event)
+        return event if @transport.is_a?(Transport::FileTransport)
+
+        EventBatch.fit(event)
+      end
+
+      def initialize_evidence
+        @evidence = EvidenceDelivery.new(config.evidence_capabilities)
+        @operations = OperationContext.new
+        @diagnostics = DiagnosticBudget.new
+      end
+
+      def recovery_allowed?
+        config.capture_recovery_observations && @evidence.supports?('recovery_v1') &&
+          @capture_policy.preset != 'minimal' && @capture_policy.capture_diagnostic_context != false
+      end
+
+      def evidence_context(context)
+        return context unless @evidence.supports?('recovery_v1') || @evidence.supports?('resource_observations_v1')
+
+        reference = EvidenceWire.capture_reference(context, @operations.scope)
+        reference ? context.except('failure_ref', 'evidence_scope').merge('evidence_reference' => reference) : context
+      end
+
+      def enrich_exception(event, retained, causes, fatal:)
+        return event unless config.capture_exception_evidence && @evidence.supports?('exception_evidence_v1')
+
+        metadata = {}
+        execution = @operations.snapshot
+        metadata['execution'] = execution if execution
+        reference = EvidenceWire.reference(event.dig('context', 'evidence_reference'))
+        metadata['evidence_reference'] = reference if reference
+        maximum = (fatal ? 4096 : 32_768) - EvidenceJson.bytes(metadata) - 32
+        graph = ExceptionEvidence.from_retained(root: retained, causes: causes, fatal: fatal, budget_bytes: maximum)
+        event['payload']['exception_evidence'] = graph if graph
+        event['payload']['execution'] = execution if execution
+        event
+      rescue StandardError
+        event
+      end
+
+      def filter_evidence(event)
+        features = @evidence.features
+        features -= ['exception_evidence_v1'] unless config.capture_exception_evidence
+        EvidenceWire.supported(event, features)
+      end
+
+      def reserve_diagnostic_locked(event, bytes)
+        event['event_type'] != 'diagnostic_context' ||
+          (recovery_allowed? && event.dig('payload', 'kind') == 'recovery' &&
+            @diagnostics.reserve(event['event_id'], event['payload'], bytes, now.to_f))
+      end
+
+      def reconcile_diagnostic(original, replacement)
+        @buffer_mutex.synchronize do
+          original_id = original['event_type'] == 'diagnostic_context' ? original['event_id'] : nil
+          if replacement['event_type'] == 'diagnostic_context'
+            return false unless recovery_allowed? && replacement.dig('payload', 'kind') == 'recovery'
+
+            payload = replacement['payload']
+            size = JSON.generate(replacement).bytesize
+            return original_id ? @diagnostics.replace(original_id, replacement['event_id'], payload, size,
+                                                      now.to_f) : @diagnostics.reserve(replacement['event_id'],
+                                                                                       payload, size, now.to_f)
+          end
+          @diagnostics.release([original_id]) if original_id
+          if %w[backend_exception frontend_exception].include?(replacement['event_type'])
+            reference = EvidenceWire.reference(replacement.dig('context', 'evidence_reference'))
+            if reference
+              @diagnostics.register_failure(reference, replacement['event_id'],
+                                            Time.iso8601(replacement['occurred_at']).to_f)
+            end
+          end
+          true
+        end
+      end
+
+      def release_diagnostics_locked(event, finalized = nil)
+        ids = []
+        ids << event['event_id'] if event['event_type'] == 'diagnostic_context'
+        ids << finalized['event_id'] if finalized && finalized['event_type'] == 'diagnostic_context'
+        @diagnostics.release(ids)
+      end
+
+      def downgrade_evidence_errors(batch, decision, lost)
+        return [] unless lost
+
+        decision.fetch(:terminal_errors).filter_map do |index, reason|
+          next unless reason == 'invalid_event'
+
+          original = batch.fetch(index)
+          finalized = @buffer_mutex.synchronize { @finalized_events[original['event_id']] || original }
+          next unless %w[backend_exception frontend_exception].include?(finalized['event_type'])
+
+          reduced = filter_evidence(finalized)
+          next if reduced == finalized
+
+          original if cache_finalized_event(original, reduced)
+        end
+      end
+    end
+
+    include EvidenceSupport
+  end
+end

data/lib/debugbundle/client_exception_support.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module DebugBundle
+  class Client
+    module ExceptionSupport
+      private
+
+      def capture_exception_internal(error, context:, handled:, run_before_send:)
+        return unless capture_enabled?
+        return unless preflight_capacity?(3, 'exception')
+
+        request_remote_config_poll_if_due
+
+        merged_context = evidence_context(merge_context(context))
+        payload = {
+          'name' => safe_exception_name(error),
+          'message' => safe_exception_message(error),
+          'stack' => safe_exception_stack(error),
+          'handled' => handled,
+          'request' => request_payload(merged_context['request']),
+          'response' => response_payload(merged_context['response']),
+          'runtime' => runtime_payload
+        }
+
+        causes = exception_causes(error)
+        retained = payload.slice('name', 'message', 'stack')
+        payload['message'] = payload['name'] if payload['message'].strip.empty?
+        payload['stack'] = "#{payload['name']}: #{payload['message']}" if payload['stack'].empty?
+
+        probe_data = probe_snapshot
+        payload['probe_data'] = probe_data unless probe_data.empty?
+
+        extra_context = merged_context.dup
+        extra_context['causes'] = causes unless causes.empty?
+
+        event = base_event('backend_exception', payload, extra_context)
+
+        event_payload = event.fetch('payload')
+        suppression_key = [
+          event['event_type'],
+          event_payload['name'],
+          event_payload['message'],
+          event_payload['stack']
+        ].join(':')
+        return unless @suppression.should_capture(suppression_key, now: monotonic_now)
+
+        event = enrich_exception(event, retained, causes, fatal: !run_before_send)
+        enqueue_event(event, skip_before_send: !run_before_send)
+      end
+    end
+
+    include ExceptionSupport
+  end
+end

data/lib/debugbundle/client_process_support.rb

@@ -13,19 +13,11 @@ module DebugBundle
         inherited_probes_enabled = @remote_config.probes_enabled
         # A fork inherits buffers, locks, and an unusable sender thread. Reset them
         # before touching any inherited synchronization object or captured event.
-        @buffer = []
-        @buffer_bytes = 0
-        @buffer_priority_counts = [0, 0, 0, 0]
-        @inflight_event_ids = Set.new
-        @inflight_priority_counts = [0, 0, 0, 0]
-        @event_sizes = {}
-        @pressure_drops = {}
-        @hook_bypass = Set.new
-        @finalized_events = {}
-        @buffer_mutex = Mutex.new
-        @flush_mutex = Mutex.new
+        initialize_buffer_ownership
         @probe_buffers = {}
         @context = {}
+        @operations&.clear
+        initialize_evidence
         @suppression = Suppression::Tracker.new
         @last_event_at = nil
         @retry_at = nil
@@ -41,7 +33,8 @@ module DebugBundle
         @delivery_worker = nil
         @config_worker = nil
         @owner_pid = current_pid
-        return unless config.enabled? && config.configured?
+        @closed = @retired
+        return unless !@closed && config.enabled? && config.configured?
 
         @delivery_worker = DeliveryWorker.new(
           interval: config.flush_interval,

data/lib/debugbundle/client_queue_support.rb

@@ -5,6 +5,20 @@ module DebugBundle
     module QueueSupport
       private
 
+      def initialize_buffer_ownership
+        @buffer = []
+        @buffer_bytes = 0
+        @buffer_priority_counts = [0, 0, 0, 0]
+        @inflight_event_ids = Set.new
+        @inflight_priority_counts = [0, 0, 0, 0]
+        @event_sizes = {}
+        @pressure_drops = {}
+        @hook_bypass = Set.new
+        @finalized_events = {}
+        @buffer_mutex = Mutex.new
+        @flush_mutex = Mutex.new
+      end
+
       def preflight_capacity?(priority, kind)
         @buffer_mutex.synchronize do
           full = @buffer.length >= MAX_BUFFER_SIZE || @buffer_bytes >= MAX_BUFFER_BYTES
@@ -23,7 +37,10 @@ module DebugBundle
 
         event_size = JSON.generate(event).bytesize
         admitted, buffered = @buffer_mutex.synchronize do
+          next [false, @buffer.length] unless reserve_diagnostic_locked(event, event_size)
+
           unless admit_event_locked?(event, event_size)
+            release_diagnostics_locked(event)
             record_pressure_drop_locked(event) if record_pressure
             next [false, @buffer.length]
           end
@@ -118,7 +135,8 @@ module DebugBundle
         @buffer_priority_counts[event_priority(event)] -= 1
         @inflight_priority_counts[event_priority(event)] -= 1 if @inflight_event_ids.delete?(event_id)
         @hook_bypass.delete(event_id)
-        @finalized_events.delete(event_id)
+        finalized = @finalized_events.delete(event_id)
+        release_diagnostics_locked(event, finalized)
       end
 
       def evictable_event_index(priority)
@@ -130,9 +148,13 @@ module DebugBundle
       def cache_finalized_event(event, finalized)
         # The original stays available for acknowledgement identity and retries, so
         # a distinct hook replacement owns additional bytes until removal.
+        finalized = event if finalized == event
         extra_bytes = finalized.equal?(event) ? 0 : JSON.generate(finalized).bytesize
         @buffer_mutex.synchronize do
-          while @buffer_bytes + extra_bytes > MAX_BUFFER_BYTES
+          previous = @finalized_events[event['event_id']]
+          old_extra = previous && !previous.equal?(event) ? JSON.generate(previous).bytesize : 0
+          delta = extra_bytes - old_extra
+          while @buffer_bytes + delta > MAX_BUFFER_BYTES
             index = evictable_event_index(event_priority(event))
             unless index
               record_pressure_drop_locked(event)
@@ -142,8 +164,8 @@ module DebugBundle
             remove_event_ownership_locked(removed)
             record_pressure_drop_locked(removed)
           end
-          @buffer_bytes += extra_bytes
-          @event_sizes[event['event_id']] += extra_bytes
+          @buffer_bytes += delta
+          @event_sizes[event['event_id']] += delta
           @finalized_events[event['event_id']] = finalized
         end
       end
@@ -156,11 +178,44 @@ module DebugBundle
         end
       end
 
+      def prepare_wire_batch(candidates)
+        prepared = []
+        size = EventBatch::WRAPPER_BYTES
+        limit = @transport.is_a?(Transport::FileTransport) ? nil : EventBatch::MAX_BODY_BYTES
+        candidates.each do |event|
+          finalized = finalized_event_for(event)
+          unless finalized
+            remove_buffered_events([event])
+            next
+          end
+
+          cost = EventBatch.bytes(finalized) + (prepared.empty? ? 0 : 1)
+          break if limit && size + cost > limit
+
+          prepared << [event, finalized]
+          size += cost
+        end
+        prepared
+      end
+
       def release_buffered_batch
         @buffer_mutex.synchronize do
           @inflight_event_ids.clear
           @inflight_priority_counts = [0, 0, 0, 0]
+          discard_closed_buffer_locked if @closed
+        end
+      end
+
+      def discard_closed_buffer_locked
+        # A stopped sender discards queued work. An active send keeps ownership
+        # charged until its ensure block releases the last snapshot.
+        @buffer.reject! do |event|
+          next false if @inflight_event_ids.include?(event['event_id'])
+
+          remove_event_ownership_locked(event)
+          true
         end
+        @diagnostics = DiagnosticBudget.new if @buffer.empty?
       end
 
       def buffered_batch