debugbundle 1.2.0 → 1.3.0

data/lib/debugbundle/client_event_support.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+module DebugBundle
+  class Client
+    module EventSupport
+      private
+
+      def capture_enabled? = config.enabled? && config.configured?
+
+      def merge_context(context)
+        merged = @context.merge(stringify_hash(context || {}))
+        @redactor.redact_value(merged)
+      end
+
+      def stringify_hash(value)
+        return {} unless value.is_a?(Hash)
+
+        value.each_with_object({}) do |(key, nested_value), result|
+          result[key.to_s] = nested_value
+        end
+      end
+
+      def request_payload(request)
+        source = object_to_hash(request)
+        {
+          'method' => source['method'] || 'UNKNOWN',
+          'path' => source['path'] || '/',
+          'query' => @redactor.redact_value(source['query'] || {}),
+          'headers' => sanitized_headers(source['headers'] || {}),
+          'body' => @redactor.redact_value(source['body'] || {})
+        }
+      end
+
+      def response_payload(response)
+        source = object_to_hash(response)
+        {
+          'status_code' => source['status_code'] || source['status'] || 0,
+          'headers' => sanitized_headers(source['headers'] || {}),
+          'body' => @redactor.redact_value(source['body'] || {})
+        }
+      end
+
+      def runtime_payload = Runtime.payload
+
+      def exception_causes(error)
+        causes = []
+        current = error.cause
+
+        while current
+          causes << {
+            'name' => current.class.name,
+            'message' => current.message.to_s,
+            'stack' => Array(current.backtrace).join("\n")
+          }
+          current = current.cause
+        end
+
+        causes
+      end
+
+      def probe_snapshot
+        items = @probe_buffers.values.flatten.map do |entry|
+          entry.merge('activation_id' => nil)
+        end
+        return {} if items.empty?
+
+        { 'version' => 1, 'items' => items }
+      end
+
+      def resolve_probe_value(data, block)
+        [true, block ? block.call : data]
+      rescue StandardError
+        [false, nil]
+      end
+
+      def normalize_probe_data(value)
+        redacted = @redactor.redact_value(value)
+        redacted.is_a?(Hash) ? redacted : { 'value' => redacted }
+      end
+
+      def apply_before_send(event)
+        BeforeSend.apply(event, config.before_send)
+      end
+
+      def enqueue_event(event)
+        return unless sampled_in?
+
+        @buffer_mutex.synchronize do
+          @buffer << event
+          @buffer.shift while @buffer.length > MAX_BUFFER_SIZE
+        end
+      end
+
+      def buffered_batch
+        @buffer_mutex.synchronize { @buffer.dup }
+      end
+
+      def remove_buffered_events(events)
+        event_ids = events.map { |event| event['event_id'] }
+        @buffer_mutex.synchronize do
+          @buffer.reject! { |event| event_ids.include?(event['event_id']) }
+        end
+      end
+
+      def sampled_in?
+        return false if config.sample_rate <= 0.0
+        return true if config.sample_rate >= 1.0
+
+        @random_provider.call.to_f < config.sample_rate
+      rescue StandardError
+        true
+      end
+
+      def append_suppression_aggregates
+        @suppression.drain_aggregates(now: monotonic_now).each do |aggregate|
+          event = apply_before_send(base_event('error_suppressed', aggregate, {}))
+          enqueue_event(event) if event
+        end
+      end
+
+      def base_event(event_type, payload, context)
+        redacted_payload = @redactor.redact_value(payload)
+        preserve_redacted_probe_data!(event_type, payload, redacted_payload)
+        event = {
+          'schema_version' => SCHEMA_VERSION,
+          'event_id' => SecureRandom.uuid,
+          'event_type' => event_type,
+          'project_token' => config.project_token,
+          'sdk_name' => SDK_NAME,
+          'sdk_version' => DebugBundle::VERSION,
+          'service' => {
+            'name' => service_name,
+            'runtime' => 'ruby',
+            'framework' => context['framework'],
+            'environment' => environment_name
+          },
+          'occurred_at' => now.iso8601,
+          'correlation' => correlation_payload(context),
+          'payload' => redacted_payload
+        }
+        envelope_context = event_context(context)
+        event['context'] = envelope_context unless envelope_context.empty?
+        event
+      end
+
+      # Probe values are redacted before entering the in-memory probe buffer. Re-running
+      # the depth limiter after nesting them inside an event would replace valid scalar
+      # and list values with truncation markers.
+      def preserve_redacted_probe_data!(event_type, payload, redacted_payload)
+        if event_type == 'backend_exception' && payload.key?('probe_data')
+          preserve_probe_snapshot_values!(payload, redacted_payload)
+        elsif event_type == 'probe_event' && payload.key?('data')
+          redacted_payload['data'] = payload['data']
+        end
+      end
+
+      def preserve_probe_snapshot_values!(payload, redacted_payload)
+        original_items = payload.dig('probe_data', 'items')
+        redacted_items = redacted_payload.dig('probe_data', 'items')
+        return unless original_items.is_a?(Array) && redacted_items.is_a?(Array)
+
+        original_items.zip(redacted_items).each do |original, redacted|
+          redacted['data'] = original['data'] if original.is_a?(Hash) && redacted.is_a?(Hash)
+        end
+      end
+
+      def service_name = config.service || DEFAULT_SERVICE_NAME
+
+      def environment_name = config.environment || DEFAULT_ENVIRONMENT
+
+      def correlation_payload(context)
+        request = object_to_hash(context['request'])
+        correlation = object_to_hash(context['correlation'])
+        {
+          'request_id' => correlation['request_id'] || request['request_id'] || context['request_id'],
+          'trace_id' => correlation['trace_id'] || request['trace_id'] || context['trace_id'],
+          'session_id' => correlation['session_id'] || context['session_id'],
+          'user_id_hash' => correlation['user_id_hash'] || context['user_id_hash']
+        }
+      end
+
+      def event_context(context)
+        object_to_hash(context).except(
+          'request',
+          'response',
+          'correlation',
+          'request_id',
+          'trace_id',
+          'session_id',
+          'user_id_hash'
+        )
+      end
+
+      def object_to_hash(value)
+        case value
+        when Hash
+          stringify_hash(value)
+        else
+          return stringify_hash(value.to_h) if value.respond_to?(:to_h)
+          return stringify_hash(value.to_hash) if value.respond_to?(:to_hash)
+
+          {}
+        end
+      rescue StandardError
+        {}
+      end
+
+      def sanitized_headers(headers)
+        stringify_hash(headers).each_with_object({}) do |(key, value), result|
+          normalized_key = key.to_s.downcase
+          next unless DEFAULT_HEADER_ALLOWLIST.include?(normalized_key)
+
+          result[normalized_key] = @redactor.redact_value(value)
+        end
+      end
+
+      def normalize_level(level)
+        candidate = level.to_s.strip.downcase.to_sym
+        return candidate if LOG_LEVEL_RANKS.key?(candidate)
+
+        :warning
+      end
+
+      def level_enabled?(level)
+        threshold = [normalize_level(config.log_level), policy_log_level].max_by do |entry|
+          LOG_LEVEL_RANKS.fetch(entry)
+        end
+        LOG_LEVEL_RANKS.fetch(level) >= LOG_LEVEL_RANKS.fetch(threshold)
+      end
+
+      def policy_log_level
+        case @capture_policy.capture_logs
+        when 'off'
+          :fatal
+        when 'error'
+          :error
+        when 'info'
+          :info
+        else
+          :warning
+        end
+      end
+    end
+
+    include EventSupport
+  end
+end

data/lib/debugbundle/config.rb

@@ -39,7 +39,8 @@ module DebugBundle
                 :max_probe_labels,
                 :max_probe_entries_per_label,
                 :probe_flush_on_error,
-                :probes_poll_interval
+                :probes_poll_interval,
+                :before_send
 
     def initialize(
       project_token: nil,
@@ -61,7 +62,8 @@ module DebugBundle
       max_probe_labels: DEFAULT_MAX_PROBE_LABELS,
       max_probe_entries_per_label: DEFAULT_MAX_PROBE_ENTRIES_PER_LABEL,
       probe_flush_on_error: DEFAULT_PROBE_FLUSH_ON_ERROR,
-      probes_poll_interval: DEFAULT_PROBES_POLL_INTERVAL
+      probes_poll_interval: DEFAULT_PROBES_POLL_INTERVAL,
+      before_send: nil
     )
       @project_token = project_token
       @enabled = enabled
@@ -89,6 +91,7 @@ module DebugBundle
       )
       @probe_flush_on_error = probe_flush_on_error
       @probes_poll_interval = normalize_positive_number(probes_poll_interval, DEFAULT_PROBES_POLL_INTERVAL)
+      @before_send = before_send.respond_to?(:call) ? before_send : nil
       freeze
     end
 

data/lib/debugbundle/rails.rb

@@ -2,9 +2,13 @@
 
 begin
   require 'rails/railtie'
+# The gem is intentionally usable without Rails; this branch is exercised by
+# the clean non-Rails gem smoke rather than the Rails-enabled coverage process.
+# :nocov:
 rescue LoadError
   nil
 end
+# :nocov:
 
 require_relative 'rails/relay_endpoint'
 require_relative 'rails/railtie' if defined?(Rails::Railtie)

data/lib/debugbundle/transport.rb

@@ -10,7 +10,7 @@ module DebugBundle
   module Transport
     RETRY_AFTER_CAP_SECONDS = 300
 
-    Result = Struct.new(:status_code, :retry_after_seconds, keyword_init: true)
+    Result = Struct.new(:status_code, :retry_after_seconds, :body, keyword_init: true)
 
     def self.sdk_config_endpoint(events_endpoint)
       uri = URI.parse(events_endpoint)
@@ -36,7 +36,8 @@ module DebugBundle
 
       Result.new(
         status_code: result.status_code.to_i,
-        retry_after_seconds: result.respond_to?(:retry_after_seconds) ? result.retry_after_seconds : nil
+        retry_after_seconds: result.respond_to?(:retry_after_seconds) ? result.retry_after_seconds : nil,
+        body: result.respond_to?(:body) ? result.body : nil
       )
     end
 
@@ -62,7 +63,8 @@ module DebugBundle
 
         Result.new(
           status_code: response.code.to_i,
-          retry_after_seconds: parse_retry_after(response['Retry-After'])
+          retry_after_seconds: parse_retry_after(response['Retry-After']),
+          body: parse_body(response.body)
         )
       rescue StandardError
         Result.new(status_code: 500)
@@ -70,6 +72,14 @@ module DebugBundle
 
       private
 
+      def parse_body(body)
+        return nil if body.to_s.empty?
+
+        JSON.parse(body)
+      rescue JSON::ParserError
+        body
+      end
+
       def parse_retry_after(value)
         return nil if value.nil? || value.strip.empty?
 

data/lib/debugbundle/version.rb

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

data/lib/debugbundle.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative 'debugbundle/redaction'
+require_relative 'debugbundle/acknowledgement'
+require_relative 'debugbundle/before_send'
 require_relative 'debugbundle/rack/middleware'
 require_relative 'debugbundle/logging'
 require_relative 'debugbundle/remote_config'

data/spec/before_send_spec.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe DebugBundle::BeforeSend do
+  let(:base_event) do
+    {
+      'schema_version' => '2026-03-01',
+      'event_id' => '11111111-1111-4111-8111-111111111111',
+      'event_type' => 'log_event',
+      'occurred_at' => '2026-07-27T08:00:00Z',
+      'sdk_name' => '@debugbundle/sdk-ruby',
+      'sdk_version' => '1.3.0',
+      'service' => { 'name' => 'ruby-test', 'environment' => 'test' },
+      'payload' => { 'level' => 'error', 'message' => 'failure', 'attributes' => {} }
+    }
+  end
+
+  it 'validates every closed canonical payload variant' do
+    payloads = {
+      'backend_exception' => {
+        'name' => 'RuntimeError', 'message' => 'failure', 'stack' => 'stack', 'handled' => true,
+        'request' => {}, 'response' => {}, 'runtime' => {}, 'probe_data' => {}
+      },
+      'request_event' => {
+        'method' => 'GET', 'path' => '/', 'query' => {}, 'headers' => {},
+        'response_status' => 503, 'duration_ms' => 10, 'response_headers' => {}
+      },
+      'frontend_breadcrumb' => { 'breadcrumb_type' => 'navigation', 'data' => {} },
+      'frontend_exception' => {
+        'name' => 'Error', 'message' => 'failure', 'stack' => 'stack',
+        'breadcrumbs' => [], 'probe_data' => {}
+      },
+      'deploy_metadata' => {
+        'commit_sha' => 'abc', 'version' => '1', 'branch' => 'main',
+        'environment' => 'test', 'deployed_at' => '2026-07-27T08:00:00Z'
+      },
+      'error_suppressed' => {
+        'fingerprint' => 'fp', 'suppressed_count' => 2, 'window_seconds' => 60,
+        'first_seen' => '2026-07-27T08:00:00Z', 'last_seen' => '2026-07-27T08:01:00Z'
+      },
+      'probe_event' => {
+        'label' => 'cart.total', 'data' => { 'value' => 2 },
+        'activation_id' => nil, 'probe_label_pattern' => 'cart.*'
+      }
+    }
+
+    payloads.each do |event_type, payload|
+      event = base_event.merge('event_type' => event_type, 'payload' => payload)
+      expect(described_class.valid?(event)).to be_truthy, event_type
+    end
+  end
+
+  it 'rejects malformed roots, timestamps, payload fields, and typed values' do
+    expect(described_class.valid?([])).to be(false)
+    expect(described_class.valid?(base_event.merge('unexpected' => true))).to be(false)
+    expect(described_class.valid?(base_event.merge('event_id' => 'not-a-uuid'))).to be(false)
+    expect(described_class.valid?(base_event.merge('occurred_at' => 'not-a-time'))).to be(false)
+    expect(
+      described_class.valid?(
+        base_event.merge('payload' => base_event['payload'].merge('unexpected' => true))
+      )
+    ).to be(false)
+    expect(described_class.valid?(base_event.merge('event_type' => 'unknown'))).to be_falsey
+  end
+
+  it 'covers strict scalar helpers used by request, suppression, and probe validation' do
+    expect(described_class.non_negative_number?(Float::INFINITY)).to be(false)
+    expect(described_class.non_negative_integer?(-1)).to be(false)
+    expect(described_class.positive_integer?(0)).to be(false)
+    expect(described_class.timestamp?('invalid')).to be(false)
+    expect(described_class.nullable_uuid?('invalid')).to be(false)
+  end
+end

data/spec/client_spec.rb

@@ -117,6 +117,104 @@ RSpec.describe DebugBundle::Client do
     expect(flushed_events.count { |event| event.fetch('event_type') == 'error_suppressed' }).to eq(1)
   end
 
+  it 'wraps list, scalar, and nil probe data before exception attachment' do
+    client = described_class.new(project_token: 'dbundle_proj_test', transport: transport)
+    client.probe('list', %w[first second])
+    client.probe('scalar', 42)
+    client.probe('nil', nil)
+    client.capture_exception(RuntimeError.new('boom'))
+
+    client.flush
+
+    exception = transport_events.fetch(0).fetch(:events).find do |event|
+      event.fetch('event_type') == 'backend_exception'
+    end
+    items = exception.fetch('payload').fetch('probe_data').fetch('items')
+    expect(items.map { |item| item.fetch('data') }).to eq(
+      [
+        { 'value' => %w[first second] },
+        { 'value' => 42 },
+        { 'value' => nil }
+      ]
+    )
+  end
+
+  it 'swallows probe callback failures' do
+    client = described_class.new(project_token: 'dbundle_proj_test', transport: transport)
+
+    expect { client.probe('unsafe') { raise 'callback failed' } }.not_to raise_error
+  end
+
+  it 'runs before_send after redaction and mutates before queueing' do
+    observed_passwords = []
+    client = described_class.new(
+      project_token: 'dbundle_proj_test',
+      transport: transport,
+      before_send: lambda do |event|
+        observed_passwords << event.fetch('context').fetch('password')
+        event.fetch('payload')['message'] = 'mutated'
+        event
+      end
+    )
+    client.capture_message('original', level: :error, context: { password: 'secret' })
+
+    client.flush
+
+    expect(observed_passwords).to eq(['[REDACTED]'])
+    expect(transport_events.fetch(0).fetch(:events).fetch(0).dig('payload', 'message')).to eq('mutated')
+  end
+
+  it 'handles before_send drop, invalid return, failure, and sampling safely' do
+    calls = 0
+    dropping_client = described_class.new(
+      project_token: 'dbundle_proj_test',
+      transport: transport,
+      before_send: lambda do |_event|
+        calls += 1
+        nil
+      end
+    )
+    dropping_client.capture_message('drop', level: :error)
+    dropping_client.flush
+    expect(calls).to eq(1)
+    expect(transport_events).to be_empty
+
+    invalid_client = described_class.new(
+      project_token: 'dbundle_proj_test',
+      transport: transport,
+      before_send: ->(_event) { { 'invalid' => true } }
+    )
+    invalid_client.capture_message('preserve invalid', level: :error)
+    invalid_client.flush
+
+    failing_client = described_class.new(
+      project_token: 'dbundle_proj_test',
+      transport: transport,
+      before_send: ->(_event) { raise 'hook failed' }
+    )
+    failing_client.capture_message('preserve failure', level: :error)
+    failing_client.flush
+
+    expect(transport_events.map { |request| request.fetch(:events).fetch(0).dig('payload', 'message') }).to eq(
+      ['preserve invalid', 'preserve failure']
+    )
+
+    sampled_calls = 0
+    sampled_client = described_class.new(
+      project_token: 'dbundle_proj_test',
+      transport: transport,
+      sample_rate: 0,
+      before_send: lambda do |event|
+        sampled_calls += 1
+        event
+      end
+    )
+    sampled_client.capture_message('sampled out', level: :error)
+    sampled_client.flush
+    expect(sampled_calls).to eq(1)
+    expect(transport_events.length).to eq(2)
+  end
+
   it 'backs off after 429 responses without dropping buffered events' do
     retry_transport = Class.new do
       def initialize
@@ -147,6 +245,104 @@ RSpec.describe DebugBundle::Client do
     expect(client.buffered_event_count).to eq(0)
   end
 
+  it 'retries only the indexed retryable rejection from an acknowledgement' do
+    requests = []
+    responses = [
+      DebugBundle::Transport::Result.new(
+        status_code: 202,
+        body: {
+          'accepted' => 1,
+          'rejected' => 1,
+          'errors' => [{ 'index' => 1, 'reason' => 'rate_limited' }]
+        }
+      ),
+      DebugBundle::Transport::Result.new(
+        status_code: 202,
+        body: { 'accepted' => 1, 'rejected' => 0, 'errors' => [] }
+      )
+    ]
+    acknowledgement_transport = lambda do |request|
+      requests << request
+      responses.shift
+    end
+    current_time = Time.utc(2026, 5, 23, 12, 0, 0)
+    client = described_class.new(
+      project_token: 'dbundle_proj_test',
+      transport: acknowledgement_transport,
+      time_provider: -> { current_time }
+    )
+    client.capture_log('accepted', level: :warning)
+    client.capture_log('retry', level: :warning)
+
+    expect(client.flush).to be(false)
+    expect(client.buffered_event_count).to eq(1)
+    expect(client.last_event_at).not_to be_nil
+    expect(client.status).to eq(:degraded)
+
+    current_time += 2
+    expect(client.flush).to be(true)
+    expect(requests.fetch(1).fetch(:events).map { |event| event.dig('payload', 'message') }).to eq(['retry'])
+  end
+
+  it 'removes terminal rejections without reporting delivery success' do
+    calls = 0
+    acknowledgement_transport = lambda do |_request|
+      calls += 1
+      DebugBundle::Transport::Result.new(
+        status_code: 202,
+        body: {
+          'accepted' => 0,
+          'rejected' => 1,
+          'errors' => [{ 'index' => 0, 'reason' => 'capture_policy_rejected' }]
+        }
+      )
+    end
+    client = described_class.new(project_token: 'dbundle_proj_test', transport: acknowledgement_transport)
+    client.capture_log('terminal', level: :warning)
+
+    expect(client.flush).to be(false)
+    expect(client.buffered_event_count).to eq(0)
+    expect(client.last_event_at).to be_nil
+    expect(client.status).to eq(:disconnected)
+    expect(client.flush).to be(true)
+    expect(calls).to eq(1)
+  end
+
+  it 'retains the full batch after an inconsistent acknowledgement' do
+    requests = []
+    responses = [
+      DebugBundle::Transport::Result.new(
+        status_code: 202,
+        body: { 'accepted' => 1, 'rejected' => 0, 'errors' => [] }
+      ),
+      DebugBundle::Transport::Result.new(
+        status_code: 202,
+        body: { 'accepted' => 2, 'rejected' => 0, 'errors' => [] }
+      )
+    ]
+    acknowledgement_transport = lambda do |request|
+      requests << request
+      responses.shift
+    end
+    current_time = Time.utc(2026, 5, 23, 12, 0, 0)
+    client = described_class.new(
+      project_token: 'dbundle_proj_test',
+      transport: acknowledgement_transport,
+      time_provider: -> { current_time }
+    )
+    client.capture_log('first', level: :warning)
+    client.capture_log('second', level: :warning)
+
+    expect(client.flush).to be(false)
+    expect(client.buffered_event_count).to eq(2)
+    expect(client.last_event_at).to be_nil
+    expect(client.status).to eq(:degraded)
+
+    current_time += 2
+    expect(client.flush).to be(true)
+    expect(requests.fetch(1).fetch(:events).length).to eq(2)
+  end
+
   it 'defaults development captures to secure local event files' do
     Dir.mktmpdir do |directory|
       client = described_class.new(project_token: 'dbundle_proj_test', local_events_dir: directory)