debugbundle 2.0.0 → 2.1.0

data/lib/debugbundle/event_batch.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'debugbundle/evidence_wire'
+
+module DebugBundle
+  module EventBatch
+    MAX_BODY_BYTES = 256 * 1024
+    WRAPPER_BYTES = 13 # {"events":[]} plus a conservative comma allowance
+    MAX_EVENT_BYTES = MAX_BODY_BYTES - WRAPPER_BYTES
+
+    module_function
+
+    def bytes(event) = JSON.generate(event).bytesize
+    def fits?(event) = bytes(event) <= MAX_EVENT_BYTES
+
+    # Added metadata must not strand a primary that fits on the legacy wire.
+    # A historically open same-named custom context value remains untouched.
+    def fit(event)
+      return nil unless event
+      return event if fits?(event)
+
+      reduced = EvidenceWire.without_optional(event) || event
+      if EvidenceWire.reference(reduced.dig('context', 'evidence_reference'))
+        reduced = reduced.merge('context' => reduced['context'].except('evidence_reference'))
+      end
+      reduced if reduced != event && fits?(reduced)
+    end
+
+    def chunks(events)
+      result = [[]]
+      size = WRAPPER_BYTES
+      events.each do |event|
+        cost = bytes(event) + (result.last.empty? ? 0 : 1)
+        raise ArgumentError, 'event exceeds the ingestion request limit' unless fits?(event)
+
+        if size + cost > MAX_BODY_BYTES
+          result << []
+          size = WRAPPER_BYTES
+          cost -= 1
+        end
+        result.last << event
+        size += cost
+      end
+      result
+    end
+  end
+end

data/lib/debugbundle/evidence_delivery.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'debugbundle/evidence_wire'
+
+module DebugBundle
+  class EvidenceDelivery
+    attr_reader :features
+
+    def initialize(pin = nil)
+      @features = EvidenceWire.descriptor(EvidenceValue.options(pin))['features']
+    end
+
+    def supports?(feature) = @features.include?(feature)
+    def descriptor = { 'version' => 1, 'features' => @features.dup }
+    def restrict(features) = @features &= features
+
+    def observe(body, required: false, valid: true)
+      owned = EvidenceValue.copy(body)
+      supplied = owned.is_a?(Hash) && owned.key?('evidence_capabilities')
+      return false unless required || supplied
+
+      previous = @features
+      @features = EvidenceWire.descriptor(valid && supplied ? owned['evidence_capabilities'] : nil)['features']
+      (previous - @features).any?
+    end
+
+    def valid_config?(body)
+      owned = EvidenceValue.copy(body)
+      return false unless owned.is_a?(Hash)
+      return false unless %w[probes_enabled remote_probes_enabled].all? do |field|
+        !owned.key?(field) || [true, false].include?(owned[field])
+      end
+      return false if owned.key?('active_probes') && !owned['active_probes'].is_a?(Array)
+
+      policy = owned['capture_policy']
+      return true if policy.nil?
+      return false unless policy.is_a?(Hash)
+
+      diagnostic = policy['capture_diagnostic_context']
+      return false if policy.key?('capture_diagnostic_context') && ![true, false].include?(diagnostic)
+
+      { 'preset' => %w[minimal balanced investigative], 'capture_logs' => %w[off error warning info],
+        'capture_request_events' => %w[off failures_only filtered all],
+        'capture_breadcrumbs' => %w[local_only exception_only standalone],
+        'capture_probe_events' => %w[buffer_only standalone_when_activated] }.all? do |field, values|
+        !policy.key?(field) || values.include?(policy[field])
+      end
+    end
+  end
+end

data/lib/debugbundle/evidence_graph.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module DebugBundle
+  module EvidenceGraph
+    module_function
+
+    def valid?(value)
+      wire = EvidenceWire
+      return false unless wire.closed(value, %w[version runtime root_id nodes truncated unavailable_reason])
+      return false unless wire.integer(value['version'], 1, 1) && wire.integer(value['root_id'], 0, 7)
+      return false unless %w[node browser python php jvm go ruby dotnet android swift react_native
+                             unknown].include?(value['runtime'])
+      return false unless [true, false].include?(value['truncated']) &&
+                          [nil, 'unknown', 'unsupported', 'unsafe',
+                           'budget_exceeded'].include?(value['unavailable_reason'])
+
+      nodes = value['nodes']
+      return false unless nodes.is_a?(Array) && nodes.length.between?(1, 8)
+
+      adjacency = {}
+      nodes.each do |node|
+        return false unless valid_node?(node) && !adjacency.key?(node['id'])
+
+        adjacency[node['id']] = node['relationships'].map { |edge| edge['target_id'] }
+      end
+      visited = {}
+      visit(value['root_id'], adjacency, [], visited) && visited.length == nodes.length &&
+        EvidenceJson.bytes(value) <= 32_768
+    end
+
+    def valid_node?(node)
+      wire = EvidenceWire
+      return false unless wire.closed(node, %w[id name message stack trace_origin parsing_status frames relationships])
+      return false unless wire.integer(node['id'], 0,
+                                       7) && wire.text(node['name'], 256) && wire.text(node['message'], 2048)
+      return false unless node['stack'].nil? || wire.text(node['stack'], 16_384)
+      return false unless %w[throw native_fatal capture runtime_reported unavailable
+                             unknown].include?(node['trace_origin'])
+      return false unless %w[parsed partial unparsed unavailable truncated].include?(node['parsing_status'])
+
+      frames = node['frames']
+      frames.is_a?(Array) && frames.length <= 32 && frames.all? { |frame| valid_frame?(frame) } &&
+        valid_edges?(node['relationships'])
+    end
+
+    def valid_frame?(frame)
+      wire = EvidenceWire
+      wire.closed(frame, %w[function file line column classification]) &&
+        (frame['function'].nil? || wire.text(frame['function'], 256)) &&
+        (frame['file'].nil? || wire.text(frame['file'], 2048)) &&
+        (frame['line'].nil? || wire.integer(frame['line'], 1)) &&
+        (frame['column'].nil? || wire.integer(frame['column'], 0)) &&
+        %w[application framework sdk unknown].include?(frame['classification'])
+    end
+
+    def valid_edges?(edges)
+      return false unless edges.is_a?(Array) && edges.length <= 5 && edges.uniq.length == edges.length
+      return false if edges.count { |edge| edge.is_a?(Hash) && %w[cause context].include?(edge['kind']) } > 1
+
+      edges.all? do |edge|
+        EvidenceWire.closed(edge, %w[kind target_id]) &&
+          %w[cause context aggregate suppressed].include?(edge['kind']) && EvidenceWire.integer(edge['target_id'], 0, 7)
+      end
+    end
+
+    def visit(id, adjacency, path, visited)
+      return false if path.length > 4 || path.include?(id) || !adjacency.key?(id)
+
+      visited[id] = true
+      adjacency[id].all? { |target| visit(target, adjacency, path + [id], visited) }
+    end
+  end
+end

data/lib/debugbundle/evidence_json.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'debugbundle/evidence_value'
+
+module DebugBundle
+  module EvidenceJson
+    module_function
+
+    def bytes(value)
+      owned = EvidenceValue.copy(value)
+      owned.equal?(EvidenceValue::INVALID) ? 32_769 : count(owned)
+    rescue StandardError
+      32_769
+    end
+
+    def count(value)
+      case value
+      when Hash
+        2 + [0, value.length - 1].max + value.sum { |key, item| count(key) + 1 + count(item) }
+      when Array
+        2 + [0, value.length - 1].max + value.sum { |item| count(item) }
+      when Integer, Float then number_bytes(value)
+      else JSON.generate(value).bytesize
+      end
+    end
+
+    def number_bytes(value)
+      return value.to_s.length if value.is_a?(Integer) && value.abs <= 9_007_199_254_740_991
+
+      number = value.to_f
+      return 32_769 unless number.finite?
+      return 1 if number.zero?
+
+      mantissa, exponent = number.abs.to_s.downcase.split('e', 2)
+      raw = mantissa.delete('.')
+      leading = raw.length - raw.sub(/\A0+/, '').length
+      digits = raw.sub(/\A0+/, '').sub(/0+\z/, '')
+      position = mantissa.split('.', 2).first.length + (exponent || '0').to_i - leading
+      power = position - 1
+      length = if power.between?(-6, 20)
+                 decimal_bytes(position, digits.length)
+               else
+                 digits.length + (digits.length > 1 ? 1 : 0) + 2 + power.abs.to_s.length
+               end
+      length + (number.negative? ? 1 : 0)
+    end
+
+    def decimal_bytes(position, digits)
+      return 2 - position + digits if position <= 0
+
+      [position, digits].max + (position < digits ? 1 : 0)
+    end
+  end
+end

data/lib/debugbundle/evidence_resources.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module DebugBundle
+  module EvidenceResources
+    module_function
+
+    def valid?(value)
+      wire = EvidenceWire
+      wire.closed(value, %w[version items]) && wire.integer(value['version'], 1, 1) &&
+        value['items'].is_a?(Array) && value['items'].length.between?(1, 5) &&
+        value['items'].all? { |item| valid_item?(item) } && EvidenceJson.bytes(value) <= 32_768
+    end
+
+    def valid_item?(item)
+      wire = EvidenceWire
+      return false unless item.is_a?(Hash) && wire.timestamp(item['observed_at']) && item.key?('source_url')
+      return false unless item['source_url'].nil? || url?(item['source_url'])
+
+      case item['kind']
+      when 'timing' then valid_timing?(item)
+      when 'csp' then valid_csp?(item)
+      else false
+      end
+    end
+
+    def valid_timing?(item)
+      wire = EvidenceWire
+      wire.closed(item,
+                  %w[kind observed_at source_url availability response_status duration_ms transfer_size_bytes]) &&
+        %w[observed unsupported no_match withheld ambiguous unknown].include?(item['availability']) &&
+        (item['response_status'].nil? || wire.integer(item['response_status'], 100, 599)) &&
+        (item['duration_ms'].nil? || wire.number(item['duration_ms'])) &&
+        (item['transfer_size_bytes'].nil? || wire.integer(item['transfer_size_bytes'], 0))
+    end
+
+    def valid_csp?(item)
+      wire = EvidenceWire
+      wire.closed(item, %w[kind observed_at source_url effective_directive disposition document_status_code]) &&
+        wire.text(item['effective_directive'], 64) && /\A[a-z-]{1,64}\z/.match?(item['effective_directive']) &&
+        %w[enforce report].include?(item['disposition']) &&
+        (item['document_status_code'].nil? || wire.integer(item['document_status_code'], 100, 599))
+    end
+
+    def url?(value)
+      return false unless EvidenceWire.text(value, 2048) && !value.empty?
+      return false if value.start_with?('//') || value.match?(/[\x00-\x20\x7f\\?#]/)
+      return false unless value.start_with?('/') || value.match?(%r{\Ahttps?://}i)
+      return true if value.start_with?('/')
+
+      # URI validates an ASCII representation; retain the original resource identity.
+      ascii = value.gsub(/[^\x00-\x7f]/) { |char| char.bytes.map { |byte| format('%%%02X', byte) }.join }
+      uri = URI.parse(ascii)
+      return false if !value.start_with?('/') && (uri.host.nil? || uri.host.empty?)
+
+      [nil, ''].include?(uri.user) && [nil, ''].include?(uri.password) && uri.query.nil? && uri.fragment.nil?
+    rescue URI::InvalidURIError
+      false
+    end
+  end
+end

data/lib/debugbundle/evidence_value.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module DebugBundle
+  # Copy only bounded native JSON values. No custom iterators, serializers,
+  # default procs or coercions may run at the optional evidence boundary.
+  module EvidenceValue
+    INVALID = Object.new.freeze
+    EXHAUSTED = Object.new.freeze
+    NATIVE_CLASS = Object.instance_method(:class)
+    NATIVE_EQUAL = Object.instance_method(:equal?)
+
+    module_function
+
+    def type?(value, type) = NATIVE_EQUAL.bind_call(NATIVE_CLASS.bind_call(value), type)
+
+    def copy(value, symbol_keys: false)
+      result = copy_with_budget(value, symbol_keys: symbol_keys)
+      result.equal?(EXHAUSTED) ? INVALID : result
+    end
+
+    # Hooks must distinguish an invalid value from validation that stopped at
+    # its resource limit; the latter must not restore pre-hook content.
+    def copy_with_budget(value, symbol_keys: false, max_bytes: 262_144, max_string_bytes: 32_768)
+      budget = { nodes: 4096, bytes: max_bytes, string_bytes: max_string_bytes, symbol_keys: symbol_keys }
+      result = visit(value, 0, budget)
+      budget[:exhausted] ? EXHAUSTED : result
+    rescue StandardError
+      INVALID
+    end
+
+    def options(value)
+      visit(value, 0, { nodes: 4096, bytes: 262_144, symbols: true })
+    rescue StandardError
+      INVALID
+    end
+
+    def visit(value, depth, budget)
+      budget[:nodes] -= 1
+      return exhausted(budget) if depth > 16 || budget[:nodes].negative? || budget[:bytes].negative?
+      return value if type?(value, NilClass) || type?(value, TrueClass) || type?(value, FalseClass)
+      return copy_string(value, budget) if type?(value, String)
+
+      if budget[:symbols] && type?(value, Symbol)
+        return exhausted(budget) if Symbol.instance_method(:length).bind_call(value) > 32_768
+
+        return copy_string(Symbol.instance_method(:to_s).bind_call(value), budget)
+      end
+      return value if type?(value, Integer) && value.bit_length <= 1024
+      return value if type?(value, Float) && value.finite?
+      return copy_array(value, depth, budget) if type?(value, Array)
+      return copy_hash(value, depth, budget) if type?(value, Hash)
+
+      INVALID
+    end
+
+    def exhausted(budget)
+      budget[:exhausted] = true
+      INVALID
+    end
+
+    def copy_string(value, budget)
+      maximum = budget.fetch(:string_bytes, 32_768)
+      return exhausted(budget) if String.instance_method(:bytesize).bind_call(value) > [maximum, budget[:bytes]].min
+
+      text = String.new(value).encode(Encoding::UTF_8)
+      budget[:bytes] -= text.bytesize
+      return exhausted(budget) if text.bytesize > maximum || budget[:bytes].negative?
+
+      text.valid_encoding? ? text : INVALID
+    end
+
+    def copy_array(value, depth, budget)
+      return exhausted(budget) if Array.instance_method(:length).bind_call(value) > 256
+
+      result = []
+      Array.instance_method(:each).bind_call(value) do |item|
+        child = visit(item, depth + 1, budget)
+        return INVALID if child.equal?(INVALID)
+
+        result << child
+      end
+      result
+    end
+
+    def copy_hash(value, depth, budget)
+      return exhausted(budget) if Hash.instance_method(:size).bind_call(value) > 256
+
+      result = {}
+      Hash.instance_method(:each_pair).bind_call(value) do |key, item|
+        if (budget[:symbols] || budget[:symbol_keys]) && type?(key, Symbol)
+          return exhausted(budget) if Symbol.instance_method(:length).bind_call(key) > 32_768
+
+          key = Symbol.instance_method(:to_s).bind_call(key)
+        end
+        return INVALID unless type?(key, String)
+
+        name = copy_string(key, budget)
+        child = visit(item, depth + 1, budget)
+        return INVALID if name.equal?(INVALID) || child.equal?(INVALID)
+        return INVALID if result.key?(name)
+
+        result[name] = child
+      end
+      result
+    end
+  end
+end

data/lib/debugbundle/evidence_wire.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'date'
+require 'uri'
+require 'debugbundle/evidence_value'
+require 'debugbundle/evidence_json'
+require 'debugbundle/evidence_graph'
+require 'debugbundle/evidence_resources'
+
+module DebugBundle
+  # Only additive evidence is closed here. Historical arbitrary context remains
+  # open, including an application-defined invalid same-named reference field.
+  module EvidenceWire
+    FEATURES = %w[exception_evidence_v1 resource_observations_v1 recovery_v1 evidence_provenance_v1].freeze
+    UUID = /\A[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}\z/i
+    FRESH_UUID = /\A[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}\z/i
+    UTC_TIME = /\A\d{4}-\d{2}-\d{2}T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?Z\z/
+
+    module_function
+
+    def closed(value, required, optional = [])
+      value.is_a?(Hash) && (required - value.keys).empty? && (value.keys - required - optional).empty?
+    end
+
+    def number(value)
+      (value.is_a?(Integer) || value.is_a?(Float)) && value >= 0 && value.to_f.finite?
+    end
+
+    def integer(value, minimum, maximum = nil)
+      number(value) && value == value.floor && value >= minimum && (!maximum || value <= maximum)
+    end
+
+    def text(value, maximum) = value.is_a?(String) && value.valid_encoding? && value.bytesize <= maximum
+    def uuid(value, fresh: false) = text(value, 36) && (fresh ? FRESH_UUID : UUID).match?(value)
+
+    def timestamp(value)
+      text(value, 32_768) && UTC_TIME.match?(value) && !!Date.iso8601(value[0, 10])
+    rescue ArgumentError
+      false
+    end
+
+    def descriptor(value)
+      owned = EvidenceValue.copy(value)
+      empty = { 'version' => 1, 'features' => [] }
+      return empty unless closed(owned, %w[version features]) && integer(owned['version'], 1, 1)
+
+      features = owned['features']
+      return empty unless features.is_a?(Array) && features.length <= 4 && (features - FEATURES).empty?
+      return empty unless features.uniq.length == features.length
+
+      { 'version' => 1, 'features' => FEATURES & features }
+    end
+
+    def scope(value)
+      return false unless value.is_a?(Hash)
+
+      field = { 'page' => 'page_id', 'operation' => 'operation_id' }[value['kind']]
+      field && closed(value, ['kind', field]) && uuid(value[field], fresh: true)
+    end
+
+    def reference(value)
+      owned = EvidenceValue.copy(value)
+      return nil unless closed(owned, %w[version failure_ref scope]) && integer(owned['version'], 1, 1)
+      return nil unless uuid(owned['failure_ref'], fresh: true) && scope(owned['scope'])
+
+      owned
+    end
+
+    def capture_reference(value, default_scope = nil)
+      owned = EvidenceValue.copy(value)
+      return nil unless owned.is_a?(Hash)
+
+      reference('version' => 1, 'failure_ref' => owned['failure_ref'],
+                'scope' => owned['evidence_scope'] || default_scope)
+    end
+
+    def recovery(value, default_scope = nil)
+      owned = EvidenceValue.copy(value)
+      selected = capture_reference(owned, default_scope)
+      return nil unless selected
+
+      payload = selected.merge('kind' => 'recovery', 'attempt_id' => owned['attempt_id'], 'state' => owned['state'])
+      %w[operation status_code duration_ms].each { |field| payload[field] = owned[field] if owned.key?(field) }
+      diagnostic(payload) ? payload : nil
+    end
+
+    def diagnostic(value)
+      return false unless value.is_a?(Hash) && reference(value.slice('version', 'failure_ref', 'scope'))
+
+      if value['kind'] == 'recovery'
+        closed(value, %w[version kind failure_ref scope attempt_id state], %w[operation status_code duration_ms]) &&
+          uuid(value['attempt_id'], fresh: true) &&
+          %w[attempt_started attempt_completed attempt_failed recovery_observed
+             failure_persisted].include?(value['state']) &&
+          (!value.key?('operation') || text(value['operation'], 64)) &&
+          (!value.key?('status_code') || integer(value['status_code'], 100, 599)) &&
+          (!value.key?('duration_ms') || number(value['duration_ms']))
+      else
+        value['kind'] == 'resource_observation' &&
+          closed(value, %w[version kind failure_ref scope source_event_id observations]) &&
+          uuid(value['source_event_id']) && EvidenceResources.valid?(value['observations'])
+      end
+    end
+
+    def execution(value)
+      closed(value, %w[version kind name elapsed_ms limit_ms]) && integer(value['version'], 1, 1) &&
+        %w[request command job unknown].include?(value['kind']) &&
+        (value['name'].nil? || text(value['name'], 128)) &&
+        (value['elapsed_ms'].nil? || number(value['elapsed_ms'])) &&
+        (value['limit_ms'].nil? || number(value['limit_ms']))
+    end
+
+    def valid_optional?(event)
+      return false unless EvidenceValue.type?(event, Hash)
+
+      payload = Hash.instance_method(:fetch).bind_call(event, 'payload', nil)
+      return false unless EvidenceValue.type?(payload, Hash)
+
+      type = EvidenceValue.copy(Hash.instance_method(:fetch).bind_call(event, 'event_type', nil))
+      return valid_context?(event, EvidenceValue.copy(payload)) if type == 'diagnostic_context'
+
+      additions = {}
+      { 'exception_evidence' => EvidenceGraph, 'execution' => self,
+        'resource_observations' => EvidenceResources }.each do |field, validator|
+        next unless Hash.instance_method(:key?).bind_call(payload, field)
+        return false unless allowed_field?(type, field)
+
+        owned = EvidenceValue.copy(Hash.instance_method(:fetch).bind_call(payload, field))
+        return false unless field == 'execution' ? execution(owned) : validator.valid?(owned)
+
+        additions[field] = owned
+      end
+      return true if additions.empty?
+
+      context = Hash.instance_method(:fetch).bind_call(event, 'context', nil)
+      if EvidenceValue.type?(
+        context, Hash
+      )
+        selected = reference(Hash.instance_method(:fetch).bind_call(context, 'evidence_reference',
+                                                                    nil))
+      end
+      additions['evidence_reference'] = selected if selected
+      EvidenceJson.bytes(additions) <= 32_768
+    rescue StandardError
+      false
+    end
+
+    def allowed_field?(type, field)
+      (type == 'backend_exception' && field != 'resource_observations') ||
+        (type == 'frontend_exception' && field != 'execution')
+    end
+
+    def valid_context?(event, payload)
+      return false unless diagnostic(payload)
+      return true unless payload['scope']['kind'] == 'page'
+
+      correlation = Hash.instance_method(:fetch).bind_call(event, 'correlation', nil)
+      return false unless EvidenceValue.type?(correlation, Hash)
+
+      session = Hash.instance_method(:fetch).bind_call(correlation, 'session_id', nil)
+      EvidenceValue.type?(session, String) && !String.new(session).strip.empty?
+    end
+
+    def supported(event, features)
+      payload = event['payload']
+      if event['event_type'] == 'diagnostic_context'
+        feature = payload['kind'] == 'recovery' ? 'recovery_v1' : 'resource_observations_v1'
+        return features.include?(feature) ? event : nil
+      end
+      filtered = payload.dup
+      filtered = filtered.except('exception_evidence', 'execution') unless features.include?('exception_evidence_v1')
+      filtered.delete('resource_observations') unless features.include?('resource_observations_v1')
+      result = filtered == payload ? event : event.merge('payload' => filtered)
+      context = event['context']
+      reference_disabled = !features.intersect?(%w[recovery_v1 resource_observations_v1])
+      if reference_disabled && context.is_a?(Hash) && reference(context['evidence_reference'])
+        result = result.merge('context' => context.except('evidence_reference'))
+      end
+      result
+    end
+
+    def without_optional(event)
+      return nil unless event.is_a?(Hash) && %w[backend_exception frontend_exception].include?(event['event_type'])
+
+      payload = event['payload']
+      return nil unless payload.is_a?(Hash)
+
+      stripped = payload.except('exception_evidence', 'execution', 'resource_observations')
+      stripped == payload ? nil : event.merge('payload' => stripped)
+    end
+  end
+end