debugbundle 2.0.1 → 2.1.1

data/lib/debugbundle/relay/handler.rb

@@ -2,6 +2,7 @@
 
 require 'json'
 require 'uri'
+require 'debugbundle/relay/forwarder'
 
 module DebugBundle
   module Relay
@@ -12,6 +13,7 @@ module DebugBundle
       request_event
       probe_event
       analytics_event
+      diagnostic_context
     ].freeze
     BROWSER_SDK_NAME = '@debugbundle/sdk-browser'
     DEFAULT_MAX_BODY_BYTES = 262_144
@@ -20,6 +22,8 @@ module DebugBundle
     Response = Struct.new(:status, :body, :headers, keyword_init: true)
 
     class Handler
+      attr_reader :max_body_bytes
+
       def initialize(
         project_mode: :connected,
         project_token: nil,
@@ -33,7 +37,8 @@ module DebugBundle
         max_body_bytes: DEFAULT_MAX_BODY_BYTES,
         rate_limit_per_minute: DEFAULT_RATE_LIMIT_PER_MINUTE,
         rate_limit_store: nil,
-        forward_transport: nil
+        forward_transport: nil,
+        evidence_capabilities: nil
       )
         @project_mode = project_mode.to_sym
         @project_token = project_token
@@ -48,16 +53,24 @@ module DebugBundle
         @rate_limit_per_minute = rate_limit_per_minute
         @rate_limit_store = rate_limit_store
         @forward_transport = forward_transport || Transport::HttpTransport.new(@endpoint)
+        @evidence = EvidenceDelivery.new(evidence_capabilities)
+        @forwarder = Forwarder.new(@forward_transport, @project_token, @evidence)
         @rate_limit_state = Hash.new { |hash, key| hash[key] = [] }
       end
 
       def handle(request)
         method = request.fetch(:method, 'POST').to_s.upcase
         headers = normalize_headers(request[:headers] || {})
+        discover = requests_evidence?(request, headers)
         raw_body = request[:body].to_s
         return Response.new(status: 403, body: nil, headers: {}) unless origin_allowed?(headers)
 
-        response_headers = source_origin(headers) ? cors_headers(source_origin(headers)) : {}
+        response_headers = if source_origin(headers)
+                             cors_headers(source_origin(headers),
+                                          headers['access-control-request-headers'])
+                           else
+                             {}
+                           end
         early_response = request_validation_response(
           method: method,
           headers: headers,
@@ -66,11 +79,17 @@ module DebugBundle
         )
         return with_headers(early_response, response_headers) if early_response
 
-        accepted, errors = sanitize_batch(raw_body)
+        accepted, errors, indexed = sanitize_batch(raw_body)
 
-        deliver(accepted) unless accepted.empty?
+        deliver(accepted, discover: discover) unless accepted.empty?
 
-        with_headers(batch_response(accepted, errors), response_headers)
+        response = batch_response(accepted, errors)
+        if discover
+          response.status = 202
+          response.body['evidence_capabilities'] = @evidence.descriptor
+          response.body['evidence_errors'] = indexed unless indexed.empty?
+        end
+        with_headers(response, response_headers)
       rescue JSON::ParserError
         with_headers(invalid_json_response, response_headers || {})
       rescue KeyError
@@ -130,27 +149,44 @@ module DebugBundle
         )
       end
 
-      def cors_headers(origin)
+      def cors_headers(origin, requested = nil)
+        allow_evidence = requested.to_s.downcase.split(',').map(&:strip).include?('x-debugbundle-evidence')
         {
           'Access-Control-Allow-Origin' => origin,
           'Access-Control-Allow-Methods' => 'POST, OPTIONS',
-          'Access-Control-Allow-Headers' => 'content-type',
+          'Access-Control-Allow-Headers' => allow_evidence ? 'content-type, x-debugbundle-evidence' : 'content-type',
           'Access-Control-Max-Age' => '600',
-          'Vary' => 'Origin'
+          'Vary' => allow_evidence ? 'Origin, Access-Control-Request-Headers' : 'Origin'
         }
       end
 
-      def deliver(events)
+      def requests_evidence?(request, headers)
+        return true if headers['x-debugbundle-evidence'] == '1'
+
+        url = request[:url]
+        return false unless url.is_a?(String) && url.bytesize <= 4096
+
+        URI.decode_www_form(URI.parse(url).query || '').include?(%w[debugbundle_evidence 1])
+      rescue URI::InvalidURIError, ArgumentError
+        false
+      end
+
+      def deliver(events, discover:)
         service_name = @service || events.first.dig('service', 'name') || 'service'
 
         case @project_mode
         when :local_only
-          Transport::FileTransport.new(@local_events_dir).call(service_name: service_name, events: events)
+          result = Transport::FileTransport.new(@local_events_dir).call(service_name: service_name, events: events)
+          raise 'relay_write_failed' unless result.status_code == 202
         when :connected
-          Transport::FileTransport.new(@spool_dir).call(service_name: service_name, events: events) if @durable_write
-
-          result = Transport.coerce_result(@forward_transport.call(project_token: @project_token, events: events))
-          raise 'relay_forward_failed' unless result.status_code.between?(200, 299)
+          if @durable_write
+            spool = Transport::FileTransport.new(@spool_dir)
+            written = spool.call(service_name: service_name, events: events)
+            raise 'relay_write_failed' unless written.status_code == 202
+          end
+          success, complete = @forwarder.send(events, discover: discover)
+          spool.mark_delivered(written.written_file_path) if complete && spool && written.written_file_path
+          raise 'relay_forward_failed' unless success || @durable_write
         else
           raise ArgumentError, 'unsupported relay project mode'
         end
@@ -161,12 +197,16 @@ module DebugBundle
         batch = decoded.fetch('batch')
         raise KeyError unless batch.is_a?(Array)
 
-        batch.each_with_index.with_object([[], []]) do |(candidate, index), (accepted, errors)|
+        batch.each_with_index.with_object([[], [], []]) do |(candidate, index), (accepted, errors, indexed)|
           sanitized = sanitize_event(candidate)
+          if sanitized && sanitized['event_type'] != 'analytics_event'
+            sanitized = EvidenceWire.supported(sanitized, @evidence.features)
+          end
           if sanitized
             accepted << sanitized
           else
             errors << "batch[#{index}]: Invalid browser relay event payload."
+            indexed << { 'index' => index, 'reason' => 'invalid_event' }
           end
         end
       end
@@ -194,19 +234,43 @@ module DebugBundle
             'environment' => @environment || service['environment'].to_s
           },
           'correlation' => sanitize_correlation(correlation, event_type),
-          'payload' => payload,
-          'project_token' => @project_token
+          'payload' => payload
         }
+        sanitized['project_token'] = @project_token if @project_token.is_a?(String) && !@project_token.empty?
+        sanitized['context'] = candidate['context'] if candidate['context'].is_a?(Hash)
+        return nil unless EvidenceWire.valid_optional?(sanitized)
+
+        new_contract = uses_evidence_contract?(sanitized)
+        return nil if new_contract && !BeforeSend.valid?(sanitized)
+
+        protect_relay_event(sanitized, new_contract)
+      rescue StandardError
+        nil
+      end
+
+      def protect_relay_event(sanitized, new_contract)
         return nil unless TelemetryPrivacy.safe_event_identity?(sanitized)
 
-        fields = TelemetryPrivacy.protect({ 'service' => sanitized['service'], 'payload' => sanitized['payload'] })
+        fields = TelemetryPrivacy.protect(sanitized.slice('service', 'payload', 'context'))
         return nil unless fields['service'].is_a?(Hash) && fields['payload'].is_a?(Hash)
 
-        sanitized.merge('service' => fields['service'], 'payload' => fields['payload'])
+        protected = sanitized.merge(fields)
+        if EvidenceWire.valid_optional?(protected) && (!new_contract || BeforeSend.valid?(protected))
+          return EventBatch.fit(protected)
+        end
+
+        reduced = EvidenceWire.without_optional(protected)
+        EventBatch.fit(reduced) if reduced && BeforeSend.valid?(reduced)
       rescue StandardError
         nil
       end
 
+      def uses_evidence_contract?(event)
+        event['event_type'] == 'diagnostic_context' ||
+          %w[exception_evidence resource_observations execution].any? { |field| event['payload'].key?(field) } ||
+          !EvidenceWire.reference(event.dig('context', 'evidence_reference')).nil?
+      end
+
       def sanitize_correlation(value, event_type)
         correlation = value.is_a?(Hash) ? value : {}
         keys = if event_type == 'analytics_event'

data/lib/debugbundle/remote_config.rb

@@ -10,6 +10,7 @@ module DebugBundle
       :capture_request_events,
       :capture_breadcrumbs,
       :capture_probe_events,
+      :capture_diagnostic_context,
       :immediate_client_error_statuses,
       :immediate_client_error_path_rules,
       keyword_init: true
@@ -72,6 +73,7 @@ module DebugBundle
         capture_request_events: 'failures_only',
         capture_breadcrumbs: 'local_only',
         capture_probe_events: 'buffer_only',
+        capture_diagnostic_context: false,
         immediate_client_error_statuses: [],
         immediate_client_error_path_rules: []
       )
@@ -84,6 +86,7 @@ module DebugBundle
         capture_request_events: 'failures_only',
         capture_breadcrumbs: 'exception_only',
         capture_probe_events: 'buffer_only',
+        capture_diagnostic_context: true,
         immediate_client_error_statuses: [],
         immediate_client_error_path_rules: []
       )
@@ -125,6 +128,8 @@ module DebugBundle
           payload['capture_request_events'] || payload[:capture_request_events] || 'failures_only',
         capture_breadcrumbs: payload['capture_breadcrumbs'] || payload[:capture_breadcrumbs] || 'exception_only',
         capture_probe_events: payload['capture_probe_events'] || payload[:capture_probe_events] || 'buffer_only',
+        capture_diagnostic_context: (payload['preset'] || payload[:preset]) != 'minimal' &&
+          payload['capture_diagnostic_context'] != false && payload[:capture_diagnostic_context] != false,
         immediate_client_error_statuses: Array(
           payload['immediate_client_error_statuses'] || payload[:immediate_client_error_statuses]
         ).grep(Integer),

data/lib/debugbundle/sidekiq/server_middleware.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'debugbundle/framework_operation'
+
 module DebugBundle
   module Sidekiq
     class ServerMiddleware
@@ -9,25 +11,27 @@ module DebugBundle
       end
 
       def call(_worker, job, queue)
-        yield
-      rescue StandardError => e
-        @client.capture_exception(
-          e,
-          context: {
-            queue: queue,
-            job: {
-              class: job['class'],
-              queue: job['queue'] || queue,
-              jid: job['jid'],
-              retry_count: job['retry_count'] || job['retry'],
-              args_summary: Array(job['args']).first(5).map { |value| value.class.name }
+        FrameworkOperation.run(@client, kind: 'job', correlation: { trace_id: job['trace_id'] }) do
+          yield
+        rescue StandardError => e
+          @client.capture_exception(
+            e,
+            context: {
+              queue: queue,
+              job: {
+                class: job['class'],
+                queue: job['queue'] || queue,
+                jid: job['jid'],
+                retry_count: job['retry_count'] || job['retry'],
+                args_summary: Array(job['args']).first(5).map { |value| value.class.name }
+              },
+              job_id: job['jid'],
+              trace_id: job['trace_id']
             },
-            job_id: job['jid'],
-            trace_id: job['trace_id']
-          },
-          handled: false
-        )
-        raise
+            handled: false
+          )
+          raise
+        end
       end
     end
   end

data/lib/debugbundle/telemetry_privacy.rb

@@ -28,8 +28,12 @@ module DebugBundle
         raise ArgumentError, 'unsafe_input'
       end
 
-      work = { nodes: 0, bytes: 0, seen: {}.compare_by_identity,
-               fields: (FIELDS + additional_fields).map { |field| canonical(field) },
+      work = { nodes: 0, bytes: 0, seen: {}.compare_by_identity, key_policy: {}, safe_text: {},
+               fields: if additional_fields.empty?
+                         CANONICAL_FIELDS
+                       else
+                         CANONICAL_FIELDS + additional_fields.map { |field| canonical(field) }
+                       end,
                extra: additional_fields,
                assignment_pattern: assignment_pattern(additional_fields) }
       result = visit(value, work, 0, true)
@@ -54,6 +58,10 @@ module DebugBundle
       value.downcase.gsub(/[^a-z0-9]/, '')
     end
 
+    # Mandatory terms are immutable policy. Reuse their normalised form while
+    # each projection still owns its counters, seen set and configured keys.
+    CANONICAL_FIELDS = FIELDS.map { |field| canonical(field).freeze }.freeze
+
     def assignment_pattern(additional_fields)
       return DEFAULT_ASSIGNMENT_PATTERN if additional_fields.empty?
 
@@ -72,6 +80,23 @@ module DebugBundle
       end
     end
 
+    def key_policy(name, work)
+      cached = work[:key_policy][name]
+      return cached if cached
+
+      policy = if scrub_text(name, work) != name
+                 :omit
+               elsif sensitive_key?(name, work[:fields])
+                 :redact
+               else
+                 :retain
+               end
+      # Stack frames repeat the same keys. Cache decisions only in this bounded
+      # projection; values, byte accounting and later policies remain independent.
+      work[:key_policy][name] = policy if work[:key_policy].size < 256
+      policy
+    end
+
     def visit(value, work, depth, structured)
       work[:nodes] += 1
       raise ArgumentError, 'budget_exceeded' if work[:nodes] > 4096
@@ -107,9 +132,10 @@ module DebugBundle
           next if name.bytesize > 128
 
           count_bytes(work, name)
-          next if scrub_text(name, work) != name
+          policy = key_policy(name, work)
+          next if policy == :omit
 
-          result[name] = sensitive_key?(name, work[:fields]) ? REDACTED : visit(nested, work, depth + 1, structured)
+          result[name] = policy == :redact ? REDACTED : visit(nested, work, depth + 1, structured)
         end
       end
     ensure
@@ -134,13 +160,25 @@ module DebugBundle
           # Malformed structured content with a credential label is withheld below.
         end
       end
-      result = scrub_text(value, work)
+      result = scrub_value_text(value, work)
       return REDACTED if result == value && value.start_with?('{', '[') &&
                          /(?:password|token|secret|authorization|cookie)["']?\s*[:=]/i.match?(value)
 
       result
     end
 
+    def scrub_value_text(value, work)
+      # Only short, unchanged scalar text is reusable. Structured containers and
+      # redacted values always take the full path; every return owns its string.
+      cacheable = value.bytesize <= 128 && !value.start_with?('{', '[')
+      cached = work[:safe_text][value] if cacheable
+      return cached.dup if cached
+
+      result = scrub_text(value, work)
+      work[:safe_text][value] = result.dup.freeze if cacheable && result == value && work[:safe_text].size < 256
+      result
+    end
+
     def valid_card?(candidate)
       digits = candidate.delete(' -')
       return false unless digits.length.between?(13, 19) && digits.chars.uniq.length > 1

data/lib/debugbundle/transport.rb

@@ -6,12 +6,13 @@ require 'securerandom'
 require 'uri'
 require 'time'
 require 'fileutils'
+require 'debugbundle/bounded_http_response'
 
 module DebugBundle
   module Transport
     RETRY_AFTER_CAP_SECONDS = 300
 
-    Result = Struct.new(:status_code, :retry_after_seconds, :body, keyword_init: true)
+    Result = Struct.new(:status_code, :retry_after_seconds, :body, :written_file_path, keyword_init: true)
 
     def self.sdk_config_endpoint(events_endpoint)
       uri = URI.parse(events_endpoint)
@@ -48,24 +49,35 @@ module DebugBundle
       end
 
       def call(request)
+        deadline = request.fetch(:deadline) { Process.clock_gettime(Process::CLOCK_MONOTONIC) + 5 }
+        remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        return Result.new(status_code: 500) unless remaining.positive?
+
+        body = JSON.generate(events: request.fetch(:events))
+        return Result.new(status_code: 413) if body.bytesize > 262_144
+
         http = Net::HTTP.new(@uri.host, @uri.port)
         http.use_ssl = @uri.scheme == 'https'
-        http.open_timeout = 5
-        http.read_timeout = 5
-
-        response = http.post(
-          @uri.request_uri,
-          JSON.generate(events: request.fetch(:events)),
-          {
-            'Authorization' => "Bearer #{request.fetch(:project_token)}",
-            'Content-Type' => 'application/json'
-          }
-        )
+        http.open_timeout = remaining
+        http.read_timeout = remaining
+
+        response, raw = BoundedHttpResponse.read(deadline: deadline) do |consume|
+          http.post(
+            @uri.request_uri,
+            body,
+            {
+              'Authorization' => "Bearer #{request.fetch(:project_token)}",
+              'Content-Type' => 'application/json',
+              'Accept-Encoding' => 'identity',
+              'X-DebugBundle-Evidence' => '1'
+            }, &consume
+          )
+        end
 
         Result.new(
           status_code: response.code.to_i,
           retry_after_seconds: parse_retry_after(response['Retry-After']),
-          body: parse_body(response.body)
+          body: parse_body(raw)
         )
       rescue StandardError
         Result.new(status_code: 500)
@@ -108,15 +120,18 @@ module DebugBundle
         http.open_timeout = 5
         http.read_timeout = 5
 
-        request = Net::HTTP::Get.new(@uri.request_uri)
+        request = Net::HTTP::Get.new(@uri.request_uri, 'Accept-Encoding' => 'identity')
         request['Authorization'] = "Bearer #{@project_token}"
         request['Accept'] = 'application/json'
         request['X-DebugBundle-SDK'] = @sdk_name
         request['X-DebugBundle-SDK-Version'] = @sdk_version
         request['If-None-Match'] = etag if etag
+        request['X-DebugBundle-Evidence'] = '1'
 
-        response = http.request(request)
-        body = response.body.to_s.empty? ? {} : JSON.parse(response.body)
+        response, raw = BoundedHttpResponse.read do |consume|
+          http.request(request) { |reply| reply.read_body(&consume) }
+        end
+        body = raw.empty? ? {} : JSON.parse(raw)
         { status_code: response.code.to_i, etag: response['ETag'], body: body }
       rescue StandardError
         { status_code: 500, body: {} }
@@ -150,13 +165,24 @@ module DebugBundle
         File.rename(temp_path, final_path)
         File.chmod(FILE_MODE, final_path)
 
-        Result.new(status_code: 202)
+        Result.new(status_code: 202, written_file_path: final_path)
       rescue StandardError
         Result.new(status_code: 500)
       ensure
         File.delete(temp_path) if defined?(temp_path) && temp_path && File.exist?(temp_path)
       end
 
+      def mark_delivered(path)
+        ensure_secure_directory!(@directory)
+        return false unless File.dirname(File.expand_path(path)) == @directory && path.end_with?('.events.json')
+        return false unless File.file?(path) && !File.symlink?(path)
+
+        write_secure_file("#{path}.delivered", '')
+        true
+      rescue StandardError
+        false
+      end
+
       private
 
       def ensure_secure_directory!(directory)

data/lib/debugbundle/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DebugBundle
-  VERSION = '2.0.1'
+  VERSION = '2.1.1'
 end

data/lib/debugbundle.rb

@@ -22,7 +22,9 @@ require_relative 'debugbundle/rails' if defined?(Rails::Railtie)
 module DebugBundle
   class << self
     def init(**options)
-      self.client = Client.new(**options)
+      replacement = Client.new(**options)
+      @client.dispose if @client.is_a?(Client)
+      self.client = replacement
       client.capture_exceptions
       client
     end
@@ -41,6 +43,14 @@ module DebugBundle
       client.capture_error(error, context: context)
     end
 
+    def capture_recovery(observation = nil, context: nil, **options)
+      client.capture_recovery(observation, context: context, **options)
+    end
+
+    def with_operation_context(...)
+      client.with_operation_context(...)
+    end
+
     def capture_log(message, level: :warning, context: nil)
       client.capture_log(message, level: level, context: context)
     end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: debugbundle
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.1
 platform: ruby
 authors:
 - DebugBundle
 bindir: exe
 cert_chain: []
-date: 2026-09-26 00:00:00.000000000 Z
+date: 2026-11-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -49,14 +49,31 @@ files:
 - lib/debugbundle.rb
 - lib/debugbundle/acknowledgement.rb
 - lib/debugbundle/before_send.rb
+- lib/debugbundle/bounded_http_response.rb
+- lib/debugbundle/canonical_event_schema.rb
 - lib/debugbundle/client.rb
 - lib/debugbundle/client_event_support.rb
+- lib/debugbundle/client_evidence_support.rb
+- lib/debugbundle/client_exception_support.rb
 - lib/debugbundle/client_process_support.rb
 - lib/debugbundle/client_queue_support.rb
 - lib/debugbundle/config.rb
 - lib/debugbundle/config_worker.rb
 - lib/debugbundle/delivery_worker.rb
+- lib/debugbundle/diagnostic_budget.rb
+- lib/debugbundle/event-envelope.schema.json
+- lib/debugbundle/event_batch.rb
+- lib/debugbundle/evidence_delivery.rb
+- lib/debugbundle/evidence_graph.rb
+- lib/debugbundle/evidence_json.rb
+- lib/debugbundle/evidence_resources.rb
+- lib/debugbundle/evidence_value.rb
+- lib/debugbundle/evidence_wire.rb
+- lib/debugbundle/exception_evidence.rb
+- lib/debugbundle/exception_identity.rb
+- lib/debugbundle/framework_operation.rb
 - lib/debugbundle/logging.rb
+- lib/debugbundle/operation_context.rb
 - lib/debugbundle/rack/middleware.rb
 - lib/debugbundle/rack/relay_middleware.rb
 - lib/debugbundle/rails.rb
@@ -64,6 +81,7 @@ files:
 - lib/debugbundle/rails/relay_endpoint.rb
 - lib/debugbundle/redaction.rb
 - lib/debugbundle/relay.rb
+- lib/debugbundle/relay/forwarder.rb
 - lib/debugbundle/relay/handler.rb
 - lib/debugbundle/remote_config.rb
 - lib/debugbundle/runtime.rb