debugbundle 2.0.1 → 2.1.1

data/lib/debugbundle/exception_evidence.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'uri'
+require 'debugbundle/telemetry_privacy'
+require 'debugbundle/evidence_value'
+
+module DebugBundle
+  # Consume the existing protected native snapshots, never an Exception or its
+  # formatter. Even MRI's bound Exception#to_s converts a non-string message;
+  # new inspection must not introduce another such application callback.
+  module ExceptionEvidence
+    module_function
+
+    def native_type?(value, type)
+      EvidenceValue.type?(value, type)
+    end
+
+    def owned_text(value, limit, scrub: true, state: nil)
+      return nil unless Object.instance_method(:is_a?).bind_call(value, String)
+
+      copy = String.new(value)
+      state[:truncated] = true if state && (copy.bytesize > limit || !copy.valid_encoding?)
+      copy = copy.byteslice(0, limit).force_encoding(Encoding::UTF_8).scrub
+      # A split UTF-8 sequence can expand to a replacement character.
+      copy = copy.byteslice(0, limit).force_encoding(Encoding::UTF_8).scrub('')
+      copy = TelemetryPrivacy.protect(copy) if scrub
+      state[:truncated] = true if state && copy.bytesize > limit
+      copy.byteslice(0, limit).force_encoding(Encoding::UTF_8).scrub('')
+    end
+
+    def retained_snapshot(value, state)
+      return nil unless native_type?(value, Hash)
+      return nil if Hash.instance_method(:size).bind_call(value) > 32
+
+      keys = Hash.instance_method(:keys).bind_call(value)
+      return nil unless keys.all? { |key| native_type?(key, String) }
+
+      result = {}
+      { 'name' => 256, 'message' => 2048, 'stack' => 16_384 }.each do |key, limit|
+        source = Hash.instance_method(:fetch).bind_call(value, key, nil)
+        # Parse coordinates before a URL scrub can discard a fragment containing
+        # the native line suffix. Only scrubbed fields/text enter the graph.
+        result[key] = owned_text(source, limit, scrub: key != 'stack', state: state)
+        return nil if result[key].nil?
+      end
+      result['name'] = 'Exception' if result['name'].empty?
+      result['message'] = '[message unavailable]' if result['message'].empty?
+      result
+    end
+
+    def from_retained(root:, causes:, fatal: false, budget_bytes: 32_768)
+      maximum = [fatal ? 4096 : 32_768, budget_bytes].min
+      return nil if maximum < 512
+
+      state = { truncated: false }
+      outer = retained_snapshot(root, state)
+      return nil unless outer && native_type?(causes, Array)
+
+      limit = fatal ? 2 : 5 # A linear cause path has at most four edges.
+      count = Array.instance_method(:length).bind_call(causes)
+      snapshots = [outer]
+      [count, limit - 1].min.times do |index|
+        cause = retained_snapshot(Array.instance_method(:[]).bind_call(causes, index), state)
+        break unless cause
+
+        snapshots << cause
+      end
+      graph = build_graph(snapshots, count > snapshots.length - 1 || state[:truncated])
+      shrink_metadata(graph, maximum)
+      return nil if JSON.generate(graph).bytesize > maximum
+
+      append_traces(graph, snapshots, maximum, fatal ? 8 : 32)
+      graph
+    rescue StandardError
+      nil
+    end
+
+    def build_graph(snapshots, truncated)
+      nodes = snapshots.each_with_index.map do |snapshot, index|
+        {
+          'id' => index, 'name' => snapshot['name'], 'message' => snapshot['message'], 'stack' => nil,
+          'trace_origin' => snapshot['stack'].empty? ? 'unavailable' : 'runtime_reported',
+          'parsing_status' => snapshot['stack'].empty? ? 'unavailable' : 'unparsed', 'frames' => [],
+          'relationships' => index + 1 < snapshots.length ? [{ 'kind' => 'cause', 'target_id' => index + 1 }] : []
+        }
+      end
+      { 'version' => 1, 'runtime' => 'ruby', 'root_id' => 0, 'nodes' => nodes,
+        'truncated' => truncated, 'unavailable_reason' => nil }
+    end
+
+    def shrink_metadata(graph, maximum)
+      return if JSON.generate(graph).bytesize <= maximum - 32
+
+      mark_budget(graph)
+      graph['nodes'].each do |node|
+        node['name'] = owned_text(node['name'], 64)
+        node['message'] = owned_text(node['message'], 128)
+      end
+      while graph['nodes'].length > 1 && JSON.generate(graph).bytesize > maximum - 32
+        graph['nodes'].pop
+        graph['nodes'].last['relationships'] = []
+      end
+    end
+
+    def append_traces(graph, snapshots, maximum, frame_limit)
+      # Charge exact JSON fragments incrementally. Re-encoding the whole graph
+      # for every rejected frame would amplify work on adversarial long stacks.
+      used = JSON.generate(graph).bytesize + 32
+      # A bounded graph often repeats one file/function across many frames.
+      # Reuse protected text only within this projection; returned strings remain
+      # independently owned so a hook cannot mutate another frame through aliases.
+      text_cache = {}
+      graph['nodes'].each_with_index do |node, index|
+        stack = snapshots[index]['stack']
+        stack.each_line do |line|
+          frame = parse_frame(line, text_cache)
+          next unless frame
+
+          cost = JSON.generate(frame).bytesize + (node['frames'].empty? ? 0 : 1)
+          if node['frames'].length >= frame_limit || used + cost > maximum
+            node['parsing_status'] = 'truncated'
+            mark_budget(graph)
+            break
+          end
+          node['frames'] << frame
+          node['parsing_status'] = 'parsed'
+          used += cost
+        end
+        next unless node['parsing_status'] == 'unparsed'
+
+        retained = owned_text(stack, 16_384).gsub(%r{\bhttps?://[^\s<>"']+}i) { |url| frame_file(url) }
+        cost = JSON.generate(retained).bytesize - 4 # Replaces JSON null.
+        if used + cost <= maximum
+          node['stack'] = retained
+          used += cost
+        else
+          mark_budget(graph)
+        end
+      end
+    end
+
+    def parse_frame(line, text_cache = nil)
+      match = /\A(.+):([1-9]\d*)(?::in [`']([^`'\r\n]*)[`'])?\z/.match(line.strip)
+      return nil unless match
+
+      { 'function' => match[3] && frame_text(match[3], 256, text_cache),
+        'file' => frame_text(match[1], 2048, text_cache),
+        'line' => match[2].to_i, 'column' => nil, 'classification' => 'unknown' }
+    end
+
+    def frame_text(value, limit, cache)
+      return limit == 2048 ? frame_file(value) : owned_text(value, limit) unless cache
+
+      key = [limit, value]
+      cache[key] ||= (limit == 2048 ? frame_file(value) : owned_text(value, limit)).freeze
+      cache[key].dup
+    end
+
+    def frame_file(value)
+      result = owned_text(value, 2048)
+      return result unless result.match?(%r{\Ahttps?://}i)
+
+      uri = URI.parse(result)
+      uri.password = nil
+      uri.user = nil
+      uri.query = nil
+      uri.fragment = nil
+      uri.to_s
+    rescue URI::InvalidURIError
+      '[withheld]'
+    end
+
+    def mark_budget(graph)
+      graph['truncated'] = true
+      graph['unavailable_reason'] = 'budget_exceeded'
+    end
+  end
+end

data/lib/debugbundle/exception_identity.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'weakref'
+
+module DebugBundle
+  class ExceptionIdentity
+    NATIVE_EQUAL = BasicObject.instance_method(:equal?)
+
+    def initialize
+      @entries = []
+      @lock = Mutex.new
+    end
+
+    def admit?(error, scope, automatic, accepted: false)
+      return true if scope.nil?
+      return true unless @lock.try_lock
+
+      begin
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @entries.reject! { |entry| !entry[0].weakref_alive? || now - entry[3] >= 30 }
+        @entries.each do |entry|
+          next unless NATIVE_EQUAL.bind_call(entry[0].__getobj__, error) && entry[1] == scope
+
+          if !accepted && automatic != entry[2]
+            @entries.delete(entry)
+            return false
+          end
+          @entries.delete(entry) if accepted
+        end
+        if accepted
+          @entries.shift if @entries.length >= 128
+          @entries << [WeakRef.new(error), scope, automatic, now]
+        end
+        true
+      rescue WeakRef::RefError
+        true
+      ensure
+        @lock.unlock
+      end
+    end
+  end
+end

data/lib/debugbundle/framework_operation.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module DebugBundle
+  module FrameworkOperation
+    def self.run(client, ...)
+      # Custom clients implementing the older injection surface keep their
+      # established application behavior without claiming scoped evidence.
+      return yield unless client.respond_to?(:with_operation_context)
+
+      client.with_operation_context(...)
+    end
+  end
+end

data/lib/debugbundle/logging.rb

@@ -44,7 +44,7 @@ module DebugBundle
       was_capturing = Thread.current[RECURSION_GUARD_KEY]
       Thread.current[RECURSION_GUARD_KEY] = true
       client.capture_log(
-        message.to_s,
+        message.is_a?(Exception) ? message : message.to_s,
         level: LOGGER_LEVEL_NAMES.fetch(severity, :warning),
         context: { logger_name: progname }
       )
@@ -79,6 +79,7 @@ module DebugBundle
           level: log.level || :info,
           context: {
             logger_name: log.name,
+            exception: log.respond_to?(:exception) ? log.exception : nil,
             payload: log.payload,
             tags: log.tags
           }

data/lib/debugbundle/operation_context.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'debugbundle/evidence_wire'
+require 'debugbundle/telemetry_privacy'
+
+module DebugBundle
+  # Thread#[] is Fiber-local on the supported Ruby floor. New Fibers and threads
+  # do not inherit request ownership; completed/closed generations are revoked.
+  class OperationContext
+    def initialize
+      @key = :"__debugbundle_operation_#{object_id}"
+      @generation = 0
+    end
+
+    def current
+      lease = Thread.current[@key]
+      return nil unless lease && lease[:generation] == @generation && lease[:active]
+      return nil unless lease[:parents].all? { |parent| parent[:active] }
+
+      lease
+    end
+
+    def begin_scope(kind:, name: nil, limit_ms: nil, correlation: nil)
+      previous = current
+      parents = previous ? previous[:parents] + [previous] : []
+      return nil if parents.length > 15
+
+      owned_kind = EvidenceValue.options(kind)
+      owned_name = EvidenceValue.copy(name)
+      owned_limit = EvidenceValue.copy(limit_ms)
+      owned_kind = 'unknown' unless %w[request command job unknown].include?(owned_kind)
+      unless EvidenceWire.text(owned_name,
+                               128) && !owned_name.empty? && TelemetryPrivacy.protect(owned_name) == owned_name
+        owned_name = nil
+      end
+      owned_limit = nil unless EvidenceWire.number(owned_limit)
+      lease = { generation: @generation, active: true, parents: parents, previous: previous,
+                scope: { 'kind' => 'operation', 'operation_id' => SecureRandom.uuid },
+                kind: owned_kind, name: owned_name, limit: owned_limit,
+                correlation: scoped_correlation(previous, correlation),
+                started: Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      Thread.current[@key] = lease
+      lease
+    rescue StandardError
+      nil
+    end
+
+    def end_scope(lease)
+      return unless lease
+
+      lease[:active] = false
+      return unless Thread.current[@key].equal?(lease)
+
+      Thread.current[@key] = lease[:generation] == @generation ? lease[:previous] : nil
+    rescue StandardError
+      nil
+    end
+
+    def snapshot
+      lease = current
+      return nil unless lease
+
+      { 'version' => 1, 'kind' => lease[:kind], 'name' => lease[:name], 'limit_ms' => lease[:limit],
+        'elapsed_ms' => [(Process.clock_gettime(Process::CLOCK_MONOTONIC) - lease[:started]) * 1000, 0].max }
+    end
+
+    def scope = current&.fetch(:scope)&.dup
+
+    def scoped_correlation(previous, input)
+      owned = EvidenceValue.options(input)
+      selected = {}
+      if owned.is_a?(Hash)
+        %w[request_id trace_id session_id user_id_hash].each do |field|
+          value = owned[field]
+          next unless EvidenceWire.text(value, 256) && !value.strip.empty?
+          next unless TelemetryPrivacy.protect(value) == value
+
+          selected[field] = value
+        end
+      end
+      (previous ? previous[:correlation] : {}).merge(selected)
+    end
+
+    def clear
+      @generation += 1
+      Thread.current[@key] = nil
+    end
+  end
+end

data/lib/debugbundle/rack/middleware.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'uri'
+require 'debugbundle/framework_operation'
 
 module DebugBundle
   module Rack
@@ -13,30 +14,32 @@ module DebugBundle
       def call(env)
         request_context = build_request_context(env)
         started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        @client.with_request_trigger(request_context.fetch(:request)) do
-          status, headers, body = @app.call(env)
-          duration_ms = elapsed_ms(started_at)
+        FrameworkOperation.run(@client, kind: 'request', correlation: request_context.slice(:request_id, :trace_id)) do
+          @client.with_request_trigger(request_context.fetch(:request)) do
+            status, headers, body = @app.call(env)
+            duration_ms = elapsed_ms(started_at)
 
-          @client.capture_request(
-            request_context.fetch(:request),
-            { status_code: status, headers: headers.to_h },
-            context: request_context.merge(duration_ms: duration_ms, route_template: route_template(env))
-          )
+            @client.capture_request(
+              request_context.fetch(:request),
+              { status_code: status, headers: headers.to_h },
+              context: request_context.merge(duration_ms: duration_ms, route_template: route_template(env))
+            )
 
-          [status, headers, body]
+            [status, headers, body]
+          end
+        rescue StandardError => e
+          duration_ms = elapsed_ms(started_at)
+          @client.capture_exception(
+            e,
+            context: request_context.merge(
+              response: { status_code: 500, headers: {} },
+              duration_ms: duration_ms,
+              route_template: route_template(env)
+            ),
+            handled: false
+          )
+          raise
         end
-      rescue StandardError => e
-        duration_ms = elapsed_ms(started_at)
-        @client.capture_exception(
-          e,
-          context: request_context.merge(
-            response: { status_code: 500, headers: {} },
-            duration_ms: duration_ms,
-            route_template: route_template(env)
-          ),
-          handled: false
-        )
-        raise
       end
 
       private

data/lib/debugbundle/rack/relay_middleware.rb

@@ -11,10 +11,13 @@ module DebugBundle
       end
 
       def call(env)
+        limit = @handler.respond_to?(:max_body_bytes) ? @handler.max_body_bytes : Relay::DEFAULT_MAX_BODY_BYTES
+        limit = Relay::DEFAULT_MAX_BODY_BYTES unless limit.is_a?(Integer) && limit.positive?
         response = @handler.handle(
           method: env['REQUEST_METHOD'],
+          url: "#{env['PATH_INFO']}?#{env['QUERY_STRING']}",
           headers: relay_headers(env),
-          body: env.fetch('rack.input', StringIO.new).read,
+          body: env.fetch('rack.input', StringIO.new).read(limit + 1),
           ip_address: env['REMOTE_ADDR']
         )
 

data/lib/debugbundle/rails/railtie.rb

@@ -17,7 +17,10 @@ if defined?(Rails::Railtie)
             project_mode: options.project_mode || :connected,
             local_events_dir: options.local_events_dir || DebugBundle::Config::DEFAULT_LOCAL_EVENTS_DIR,
             endpoint: options.endpoint || DebugBundle::Config::DEFAULT_ENDPOINT,
-            redact_fields: Array(options.redact_fields) + Array(app.config.filter_parameters)
+            redact_fields: Array(options.redact_fields) + Array(app.config.filter_parameters),
+            capture_exception_evidence: options.capture_exception_evidence != false,
+            capture_recovery_observations: options.capture_recovery_observations == true,
+            evidence_capabilities: options.evidence_capabilities
           )
 
           app.middleware.use(DebugBundle::Rack::Middleware, client: client)

data/lib/debugbundle/rails/relay_endpoint.rb

@@ -36,7 +36,8 @@ module DebugBundle
         max_body_bytes: relay_option(options, :relay_max_body_bytes, Relay::DEFAULT_MAX_BODY_BYTES),
         rate_limit_per_minute: relay_rate_limit(options),
         rate_limit_store: relay_option(options, :relay_rate_limit_store, nil),
-        forward_transport: relay_option(options, :relay_forward_transport, nil)
+        forward_transport: relay_option(options, :relay_forward_transport, nil),
+        evidence_capabilities: relay_option(options, :relay_evidence_capabilities, nil)
       )
     end
 

data/lib/debugbundle/relay/forwarder.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'debugbundle/evidence_delivery'
+require 'debugbundle/event_batch'
+
+module DebugBundle
+  module Relay
+    class Forwarder
+      def initialize(transport, token, evidence)
+        @transport = transport
+        @token = token
+        @evidence = evidence
+      end
+
+      # The second result permits marking a spool delivered only after complete
+      # canonical acceptance. Legacy custom-transport acceptance stays compatible.
+      def send(events, discover:)
+        return [false, false] unless @token.is_a?(String) && !@token.empty?
+
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 5
+        complete = true
+        features = EvidenceWire::FEATURES.dup
+        owned = events.map { |event| event.merge('project_token' => @token) }
+        EventBatch.chunks(owned).each do |chunk|
+          chunk = chunk.map { |event| EvidenceWire.supported(event, @evidence.features) }
+          return [false, false] if chunk.any?(&:nil?)
+
+          return [false, false] if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+          success, canonical = send_chunk(chunk, discover: discover, deadline: deadline)
+          features &= @evidence.features
+          @evidence.restrict(features)
+          return [false, false] unless success && Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+
+          complete &&= canonical
+        end
+        [true, complete]
+      rescue StandardError
+        [false, false]
+      end
+
+      def send_chunk(events, discover:, deadline:)
+        required = discover || @transport.is_a?(Transport::HttpTransport)
+        response, ack, lost = forward(events, required, deadline)
+        return [false, false] unless response && ack
+        return [true, false] if ack[:kind] == :legacy
+        return [false, false] unless ack[:kind] == :acknowledged
+        return [true, true] if ack[:accepted] == events.length
+        return [false, false] unless lost
+
+        retry_events = ack.fetch(:terminal_errors).filter_map do |index, reason|
+          original = events.fetch(index)
+          next unless reason == 'invalid_event' && original['event_type'] == 'frontend_exception'
+
+          reduced = EvidenceWire.supported(original, @evidence.features)
+          reduced if reduced != original
+        end
+        return [false, false] if retry_events.empty?
+
+        _reply, retry_ack, = forward(retry_events, true, deadline)
+        complete = retry_ack && retry_ack[:kind] == :acknowledged &&
+                   ack[:accepted] + retry_ack[:accepted] == events.length
+        [!!complete, !!complete]
+      rescue StandardError
+        [false, false]
+      end
+
+      def forward(events, required, deadline)
+        return [nil, nil, false] if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+        owned = events.map { |event| event.merge('project_token' => @token) }
+        request = { project_token: @token, events: owned }
+        request[:deadline] = deadline if @transport.is_a?(Transport::HttpTransport)
+        response = Transport.coerce_result(@transport.call(request))
+        return [nil, nil, false] unless response.status_code.between?(200, 299)
+
+        ack = Acknowledgement.decide(response.body, events.length, required: required)
+        lost = @evidence.observe(response.body, required: required, valid: ack[:kind] == :acknowledged)
+        [response, ack, lost]
+      end
+    end
+  end
+end