debugbundle 0.1.0

data/spec/file_transport_spec.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'json'
+require 'tmpdir'
+
+RSpec.describe DebugBundle::Transport::FileTransport do
+  it 'derives the remote SDK config endpoint from the events endpoint' do
+    expect(DebugBundle::Transport.sdk_config_endpoint('https://api.debugbundle.com/v1/events')).to eq(
+      'https://api.debugbundle.com/v1/sdk/config'
+    )
+    expect(DebugBundle::Transport.sdk_config_endpoint('https://api.debugbundle.com/events')).to eq(
+      'https://api.debugbundle.com/sdk/config'
+    )
+    expect(DebugBundle::Transport.sdk_config_endpoint('https://api.debugbundle.com/v1/sdk/config')).to eq(
+      'https://api.debugbundle.com/v1/sdk/config'
+    )
+  end
+
+  it 'writes local event batches with secure permissions' do
+    Dir.mktmpdir do |directory|
+      transport = described_class.new(directory)
+      result = transport.call(
+        project_token: 'dbundle_proj_test',
+        service_name: 'checkout-api',
+        events: [{ 'event_type' => 'log_event', 'payload' => { 'message' => 'ok' } }]
+      )
+
+      expect(result.status_code).to eq(202)
+
+      file_path = Dir.children(directory).find { |name| name.end_with?('.events.json') }
+      expect(file_path).not_to be_nil
+
+      full_path = File.join(directory, file_path)
+      parsed = JSON.parse(File.read(full_path))
+      expect(parsed.length).to eq(1)
+      expect(parsed.fetch(0)).to include('event_type' => 'log_event')
+      expect(File.stat(full_path).mode & 0o777).to eq(0o600)
+      expect(File.stat(directory).mode & 0o777).to eq(0o700)
+    end
+  end
+
+  it 'rejects traversal-style local event directories without raising into the caller' do
+    transport = described_class.new('../debugbundle-events')
+
+    result = transport.call(
+      project_token: 'dbundle_proj_test',
+      service_name: 'checkout-api',
+      events: [{ 'event_type' => 'log_event', 'payload' => { 'message' => 'ok' } }]
+    )
+
+    expect(result.status_code).to eq(500)
+  end
+end

data/spec/logger_integration_spec.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'stringio'
+
+RSpec.describe 'stdlib logger integration' do
+  it 'captures log events without changing logger output' do
+    transport_events = []
+    transport = Class.new do
+      define_method(:initialize) do |transport_events|
+        @transport_events = transport_events
+      end
+
+      define_method(:call) do |request|
+        @transport_events << request
+        DebugBundle::Transport::Result.new(status_code: 202)
+      end
+    end.new(transport_events)
+
+    output = StringIO.new
+    logger = Logger.new(output)
+    logger.progname = 'checkout'
+
+    client = DebugBundle::Client.new(project_token: 'dbundle_proj_test', transport: transport)
+    client.capture_logger(logger)
+    client.capture_logger(logger)
+
+    logger.warn('payment retry failed')
+    client.flush
+
+    event = transport_events.fetch(0).fetch(:events).fetch(0)
+
+    expect(output.string).to include('payment retry failed')
+    expect(event.fetch('event_type')).to eq('log_event')
+    expect(event.fetch('payload')).to include('message' => 'payment retry failed', 'level' => 'warning')
+    expect(event.fetch('payload').fetch('attributes')).to include('logger_name' => 'checkout')
+  end
+
+  it 'registers a semantic logger appender when SemanticLogger is available' do
+    transport_events = []
+    transport = Class.new do
+      define_method(:initialize) do |transport_events|
+        @transport_events = transport_events
+      end
+
+      define_method(:call) do |request|
+        @transport_events << request
+        DebugBundle::Transport::Result.new(status_code: 202)
+      end
+    end.new(transport_events)
+
+    semantic_logger = Module.new do
+      class << self
+        attr_reader :appenders
+
+        def add_appender(appender:)
+          @appenders ||= []
+          @appenders << appender
+        end
+      end
+    end
+
+    stub_const('SemanticLogger', semantic_logger)
+
+    log_entry = Struct.new(:message, :level, :name, :payload, :tags).new(
+      'semantic failure',
+      :error,
+      'semantic-checkout',
+      { order_id: 123 },
+      %w[payments critical]
+    )
+
+    client = DebugBundle::Client.new(project_token: 'dbundle_proj_test', transport: transport)
+    appender = client.capture_semantic_logger
+    appender.log(log_entry)
+    client.flush
+
+    event = transport_events.fetch(0).fetch(:events).fetch(0)
+
+    expect(SemanticLogger.appenders).to include(appender)
+    expect(event.fetch('payload')).to include('message' => 'semantic failure', 'level' => 'error')
+    expect(event.fetch('payload').fetch('attributes')).to include(
+      'logger_name' => 'semantic-checkout',
+      'payload' => { 'order_id' => 123 },
+      'tags' => %w[payments critical]
+    )
+  end
+
+  it 'guards semantic logger capture against recursive SDK logging' do
+    capture_count = 0
+    appender = nil
+    log_entry = Struct.new(:message, :level, :name, :payload, :tags).new(
+      'semantic recursion check',
+      :error,
+      'semantic-checkout',
+      {},
+      []
+    )
+    recursive_client = Class.new do
+      define_method(:initialize) do |on_capture|
+        @on_capture = on_capture
+      end
+
+      define_method(:capture_log) do |_message, level:, context:|
+        @on_capture.call(level, context)
+      end
+    end.new(lambda do |_level, _context|
+      capture_count += 1
+      appender.log(log_entry)
+    end)
+
+    appender = DebugBundle::Logging::SemanticLoggerAppender.new(client: recursive_client)
+
+    appender.log(log_entry)
+
+    expect(capture_count).to eq(1)
+  end
+end

data/spec/rack_integration_spec.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'rack'
+require 'rack/mock'
+
+RSpec.describe 'Rack integration' do
+  let(:transport_events) { [] }
+  let(:transport) do
+    Class.new do
+      define_method(:initialize) do |transport_events|
+        @transport_events = transport_events
+      end
+
+      define_method(:call) do |request|
+        @transport_events << request
+        DebugBundle::Transport::Result.new(status_code: 202)
+      end
+    end.new(transport_events)
+  end
+
+  it 'captures request context in a real Rack builder stack' do
+    client = DebugBundle::Client.new(project_token: 'dbundle_proj_test', service: 'rack-checkout', transport: transport)
+    app = Rack::Builder.new do
+      use DebugBundle::Rack::Middleware, client: client
+      run ->(_env) { [422, { 'Content-Type' => 'text/plain' }, ['ok']] }
+    end.to_app
+
+    response = Rack::MockRequest.new(app).get(
+      '/checkout?cart_id=123',
+      'HTTP_X_REQUEST_ID' => 'req-rack',
+      'HTTP_X_DEBUGBUNDLE_TRACE_ID' => 'trace-rack'
+    )
+
+    client.flush
+    event = transport_events.fetch(0).fetch(:events).fetch(0)
+
+    expect(response.status).to eq(422)
+    expect(response.body).to eq('ok')
+    expect(event.fetch('event_type')).to eq('request_event')
+    expect(event.fetch('correlation')).to include('request_id' => 'req-rack', 'trace_id' => 'trace-rack')
+    expect(event.fetch('payload')).to include('path' => '/checkout', 'method' => 'GET', 'response_status' => 422)
+  end
+end

data/spec/rack_middleware_spec.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'base64'
+require 'json'
+require 'openssl'
+
+RSpec.describe DebugBundle::Rack::Middleware do
+  let(:transport_events) { [] }
+  let(:client) do
+    transport = Class.new do
+      define_method(:initialize) do |transport_events|
+        @transport_events = transport_events
+      end
+
+      define_method(:call) do |request|
+        @transport_events << request
+        DebugBundle::Transport::Result.new(status_code: 202)
+      end
+    end.new(transport_events)
+
+    config_fetcher = lambda do |_etag|
+      {
+        status_code: 200,
+        etag: 'rack-etag',
+        body: {
+          capture_policy: {
+            preset: 'balanced',
+            capture_logs: 'warning',
+            capture_request_events: 'all',
+            capture_breadcrumbs: 'exception_only',
+            capture_probe_events: 'buffer_only',
+            immediate_client_error_statuses: []
+          }
+        }
+      }
+    end
+
+    DebugBundle::Client.new(
+      project_token: 'dbundle_proj_test',
+      service: 'checkout-api',
+      transport: transport,
+      config_fetcher: config_fetcher
+    )
+  end
+
+  it 'captures request metadata and preserves the response' do
+    app = lambda do |_env|
+      [201, { 'Content-Type' => 'application/json', 'Set-Cookie' => 'secret' }, ['ok']]
+    end
+
+    middleware = described_class.new(app, client: client)
+    status, headers, body = middleware.call(
+      'REQUEST_METHOD' => 'POST',
+      'PATH_INFO' => '/checkout',
+      'QUERY_STRING' => 'cart_id=123',
+      'HTTP_X_REQUEST_ID' => 'req-1',
+      'HTTP_X_DEBUGBUNDLE_TRACE_ID' => 'trace-1',
+      'HTTP_AUTHORIZATION' => 'Bearer secret',
+      'HTTP_USER_AGENT' => 'RSpec'
+    )
+
+    client.flush
+    event = transport_events.fetch(0).fetch(:events).fetch(0)
+
+    expect(status).to eq(201)
+    expect(headers).to include('Content-Type' => 'application/json')
+    expect(body).to eq(['ok'])
+    expect(event.fetch('event_type')).to eq('request_event')
+    expect(event.fetch('correlation')).to include('request_id' => 'req-1', 'trace_id' => 'trace-1')
+    expect(event.fetch('payload').fetch('headers')).to include('user-agent' => 'RSpec')
+    expect(event.fetch('payload').fetch('headers')).not_to have_key('authorization')
+    expect(event.fetch('payload').fetch('response_headers')).to include('content-type' => 'application/json')
+    expect(event.fetch('payload').fetch('response_headers')).not_to have_key('set-cookie')
+  end
+
+  it 'captures exceptions and re-raises them' do
+    app = lambda do |_env|
+      raise 'checkout failure'
+    end
+
+    middleware = described_class.new(app, client: client)
+
+    expect do
+      middleware.call(
+        'REQUEST_METHOD' => 'GET',
+        'PATH_INFO' => '/checkout',
+        'QUERY_STRING' => '',
+        'HTTP_X_REQUEST_ID' => 'req-2'
+      )
+    end.to raise_error(RuntimeError, 'checkout failure')
+
+    client.flush
+    event = transport_events.fetch(0).fetch(:events).fetch(0)
+
+    expect(event.fetch('event_type')).to eq('backend_exception')
+    expect(event.fetch('payload')).to include('handled' => false)
+    expect(event.fetch('correlation')).to include('request_id' => 'req-2')
+  end
+
+  it 'activates trigger-token probe shipping for a single request' do
+    trigger_key = 'trigger-secret'
+    expires_at = (Time.now.utc + 60).iso8601
+    payload_json = JSON.generate(
+      activation_id: 'probe-1',
+      label_pattern: 'checkout.*',
+      service: '*',
+      environment: '*',
+      trigger_expires_at: expires_at
+    )
+    payload_segment = Base64.urlsafe_encode64(payload_json, padding: false)
+    signature = OpenSSL::HMAC.digest('sha256', trigger_key, payload_segment)
+    token = "dbundle_probe_#{payload_segment}.#{Base64.urlsafe_encode64(signature, padding: false)}"
+
+    transport = Class.new do
+      define_method(:initialize) do |transport_events|
+        @transport_events = transport_events
+      end
+
+      define_method(:call) do |request|
+        @transport_events << request
+        DebugBundle::Transport::Result.new(status_code: 202)
+      end
+    end.new(transport_events)
+
+    config_fetcher = lambda do |_etag|
+      {
+        status_code: 200,
+        etag: 'rack-trigger-etag',
+        body: {
+          probes_enabled: true,
+          remote_probes_enabled: true,
+          trigger_token_key: trigger_key,
+          capture_policy: {
+            preset: 'balanced',
+            capture_logs: 'warning',
+            capture_request_events: 'all',
+            capture_breadcrumbs: 'exception_only',
+            capture_probe_events: 'buffer_only',
+            immediate_client_error_statuses: []
+          }
+        }
+      }
+    end
+
+    trigger_client = DebugBundle::Client.new(
+      project_token: 'dbundle_proj_test',
+      service: 'checkout-api',
+      transport: transport,
+      config_fetcher: config_fetcher
+    )
+
+    app = lambda do |_env|
+      trigger_client.probe('checkout.tax', { region: 'us-east-1' })
+      [200, { 'Content-Type' => 'application/json' }, ['ok']]
+    end
+
+    middleware = described_class.new(app, client: trigger_client)
+    middleware.call(
+      'REQUEST_METHOD' => 'GET',
+      'PATH_INFO' => '/checkout',
+      'QUERY_STRING' => '',
+      'HTTP_X_DEBUGBUNDLE_PROBE_TRIGGER' => token,
+      'HTTP_X_REQUEST_ID' => 'req-trigger'
+    )
+
+    trigger_client.flush
+    events = transport_events.fetch(0).fetch(:events)
+    probe_event = events.find { |entry| entry.fetch('event_type') == 'probe_event' }
+
+    expect(probe_event).not_to be_nil
+    expect(probe_event.fetch('payload')).to include(
+      'label' => 'checkout.tax',
+      'activation_id' => 'probe-1',
+      'probe_label_pattern' => 'checkout.*'
+    )
+  end
+
+  it 'captures Rails route, controller, and action metadata when present' do
+    app = lambda do |_env|
+      [422, { 'Content-Type' => 'application/json' }, ['invalid']]
+    end
+
+    middleware = described_class.new(app, client: client)
+    middleware.call(
+      'REQUEST_METHOD' => 'POST',
+      'PATH_INFO' => '/patients/123/checkouts',
+      'QUERY_STRING' => '',
+      'action_dispatch.request_id' => 'req-rails',
+      'action_dispatch.route_uri_pattern' => '/patients/:patient_id/checkouts',
+      'action_dispatch.request.parameters' => {
+        'controller' => 'checkouts',
+        'action' => 'create'
+      }
+    )
+
+    client.flush
+    payload = transport_events.fetch(0).fetch(:events).fetch(0).fetch('payload')
+
+    expect(payload).to include(
+      'route_template' => '/patients/:patient_id/checkouts',
+      'controller' => 'checkouts',
+      'action' => 'create'
+    )
+  end
+end

data/spec/rails_railtie_spec.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'json'
+require 'logger'
+require 'rack/test'
+require 'rails'
+require 'debugbundle/rails'
+
+RSpec.describe 'Rails Railtie integration' do
+  include Rack::Test::Methods
+
+  def app
+    @app ||= build_rails_app
+  end
+
+  after do
+    @app = nil
+    DebugBundle.client = nil
+    Rails.instance_variable_set(:@application, nil)
+  end
+
+  it 'mounts the configured relay route and forwards browser events' do
+    post '/relay/browser',
+         JSON.generate('batch' => [browser_event]),
+         {
+           'CONTENT_TYPE' => 'application/json',
+           'HTTP_HOST' => 'app.example.com',
+           'HTTP_ORIGIN' => 'https://app.example.com'
+         }
+
+    expect(last_response.status).to eq(202)
+    expect(last_response.headers.fetch('Content-Type')).to include('application/json')
+    expect(JSON.parse(last_response.body)).to include('accepted' => 1, 'rejected' => 0)
+    expect(@transport_events.fetch(0).fetch(:events).fetch(0).fetch('service')).to include(
+      'name' => 'rails-checkout',
+      'environment' => 'production'
+    )
+
+    post '/debugbundle/browser',
+         JSON.generate('batch' => [browser_event]),
+         {
+           'CONTENT_TYPE' => 'application/json',
+           'HTTP_HOST' => 'app.example.com',
+           'HTTP_ORIGIN' => 'https://app.example.com'
+         }
+
+    expect(last_response.status).to eq(404)
+  end
+
+  def build_rails_app
+    @transport_events = []
+    forward_transport = Class.new do
+      define_method(:initialize) do |transport_events|
+        @transport_events = transport_events
+      end
+
+      define_method(:call) do |request|
+        @transport_events << request
+        DebugBundle::Transport::Result.new(status_code: 202)
+      end
+    end.new(@transport_events)
+
+    app_class = Class.new(Rails::Application) do
+      config.root = File.expand_path('..', __dir__)
+      config.eager_load = false
+      config.secret_key_base = 'test-secret'
+      config.logger = Logger.new(nil)
+    end
+
+    app_class.config.hosts << 'app.example.com' if app_class.config.respond_to?(:hosts)
+    app_class.config.debugbundle.project_token = 'dbundle_proj_test'
+    app_class.config.debugbundle.service = 'rails-checkout'
+    app_class.config.debugbundle.environment = 'production'
+    app_class.config.debugbundle.relay_durable_write = false
+    app_class.config.debugbundle.relay_allowed_origins = ['https://app.example.com']
+    app_class.config.debugbundle.relay_forward_transport = forward_transport
+    app_class.config.debugbundle.relay_path = '/relay/browser'
+    app_class.initialize!
+    app_class
+  end
+
+  def browser_event
+    {
+      'schema_version' => '2026-03-01',
+      'event_id' => 'evt-1',
+      'event_type' => 'frontend_exception',
+      'sdk_name' => '@debugbundle/sdk-browser',
+      'sdk_version' => '0.1.0',
+      'occurred_at' => Time.now.utc.iso8601,
+      'service' => { 'name' => 'browser-app', 'environment' => 'production' },
+      'correlation' => { 'trace_id' => 'trace-1' },
+      'payload' => { 'message' => 'boom' }
+    }
+  end
+end

data/spec/rails_relay_spec.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'json'
+require 'stringio'
+
+RSpec.describe DebugBundle::Rails::RelayEndpoint do
+  let(:relay_options_class) do
+    Struct.new(
+      :project_mode,
+      :project_token,
+      :service,
+      :environment,
+      :relay_durable_write,
+      :relay_allowed_origins,
+      :relay_forward_transport,
+      :relay_rate_limit_per_minute,
+      :relay_handler,
+      keyword_init: true
+    )
+  end
+  let(:app_config_class) { Struct.new(:debugbundle, keyword_init: true) }
+  let(:fake_app_class) { Struct.new(:config, keyword_init: true) }
+
+  it 'builds a relay handler from Rails config and forwards browser events' do
+    transport_events = []
+    forward_transport = Class.new do
+      define_method(:initialize) do |transport_events|
+        @transport_events = transport_events
+      end
+
+      define_method(:call) do |request|
+        @transport_events << request
+        DebugBundle::Transport::Result.new(status_code: 202)
+      end
+    end.new(transport_events)
+
+    app = fake_app_class.new(
+      config: app_config_class.new(
+        debugbundle: relay_options_class.new(
+          project_mode: :connected,
+          project_token: 'dbundle_proj_test',
+          service: 'rails-checkout',
+          environment: 'production',
+          relay_durable_write: false,
+          relay_allowed_origins: ['https://app.example.com'],
+          relay_forward_transport: forward_transport,
+          relay_rate_limit_per_minute: 10
+        )
+      )
+    )
+
+    endpoint = described_class.new(app: app)
+    status, headers, body = endpoint.call(
+      'REQUEST_METHOD' => 'POST',
+      'CONTENT_TYPE' => 'application/json',
+      'HOST' => 'app.example.com',
+      'HTTP_ORIGIN' => 'https://app.example.com',
+      'rack.input' => StringIO.new(
+        JSON.generate(
+          'batch' => [
+            {
+              'schema_version' => '2026-03-01',
+              'event_id' => 'evt-1',
+              'event_type' => 'frontend_exception',
+              'sdk_name' => '@debugbundle/sdk-browser',
+              'sdk_version' => '0.1.0',
+              'occurred_at' => Time.now.utc.iso8601,
+              'service' => { 'name' => 'browser-app', 'environment' => 'production' },
+              'correlation' => { 'trace_id' => 'trace-1' },
+              'payload' => { 'message' => 'boom' }
+            }
+          ]
+        )
+      )
+    )
+
+    expect(status).to eq(202)
+    expect(headers).to include('Content-Type' => 'application/json')
+    expect(JSON.parse(body.join)).to include('accepted' => 1, 'rejected' => 0)
+    expect(transport_events.fetch(0).fetch(:events).fetch(0).fetch('service')).to include(
+      'name' => 'rails-checkout',
+      'environment' => 'production'
+    )
+  end
+
+  it 'uses an explicit relay handler override when provided' do
+    custom_handler = Class.new do
+      attr_reader :requests
+
+      def initialize
+        @requests = []
+      end
+
+      def handle(request)
+        @requests << request
+        DebugBundle::Relay::Response.new(status: 202, body: { 'accepted' => 0, 'rejected' => 0, 'errors' => [] })
+      end
+    end.new
+
+    app = fake_app_class.new(
+      config: app_config_class.new(
+        debugbundle: relay_options_class.new(
+          relay_handler: custom_handler
+        )
+      )
+    )
+
+    endpoint = described_class.new(app: app)
+    status, = endpoint.call(
+      'REQUEST_METHOD' => 'POST',
+      'CONTENT_TYPE' => 'application/json',
+      'HOST' => 'example.com',
+      'HTTP_ORIGIN' => 'https://example.com',
+      'rack.input' => StringIO.new('{"batch":[]}')
+    )
+
+    expect(status).to eq(202)
+    expect(custom_handler.requests.fetch(0)).to include(method: 'POST')
+  end
+end

data/spec/redaction_spec.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe DebugBundle::Redaction::Redactor do
+  it 'redacts segment-aware sensitive keys' do
+    redacted = described_class.new.redact_value(
+      {
+        'user_password' => 'super-secret',
+        'apiKey' => 'abc123',
+        'sessionId' => 'sess-1',
+        'safe' => { 'message' => 'ok' }
+      }
+    )
+
+    expect(redacted).to include(
+      'user_password' => '[REDACTED]',
+      'apiKey' => '[REDACTED]',
+      'sessionId' => '[REDACTED]'
+    )
+    expect(redacted.fetch('safe')).to eq({ 'message' => 'ok' })
+  end
+
+  it 'protects against circular references' do
+    value = {}
+    value['self'] = value
+
+    redacted = described_class.new.redact_value(value)
+
+    expect(redacted.fetch('self')).to eq('[Circular]')
+  end
+
+  it 'supports additional sensitive fields from framework configuration' do
+    redactor = described_class.new(
+      sensitive_fields: DebugBundle::Redaction::DEFAULT_SENSITIVE_FIELDS + %w[patient_notes]
+    )
+
+    redacted = redactor.redact_value('patient_notes' => 'diagnosis details', 'safe' => 'ok')
+
+    expect(redacted).to include('patient_notes' => '[REDACTED]', 'safe' => 'ok')
+  end
+end