debugbundle 0.1.0

data/lib/debugbundle/transport.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'securerandom'
+require 'uri'
+require 'fileutils'
+
+module DebugBundle
+  module Transport
+    RETRY_AFTER_CAP_SECONDS = 300
+
+    Result = Struct.new(:status_code, :retry_after_seconds, keyword_init: true)
+
+    def self.sdk_config_endpoint(events_endpoint)
+      uri = URI.parse(events_endpoint)
+      normalized_path = uri.path.to_s.sub(%r{/+$}, '')
+      uri.path = if normalized_path.end_with?('/sdk/config')
+                   normalized_path
+                 elsif normalized_path.end_with?('/events')
+                   normalized_path.sub(%r{/events\z}, '/sdk/config')
+                 else
+                   "#{normalized_path}/sdk/config"
+                 end
+      uri.query = nil
+      uri.fragment = nil
+      uri.to_s
+    rescue URI::InvalidURIError
+      events_endpoint.to_s.sub(%r{/events\z}, '/sdk/config')
+    end
+
+    def self.coerce_result(result)
+      return result if result.is_a?(Result)
+
+      raise TypeError, 'unsupported transport result' unless result.respond_to?(:status_code)
+
+      Result.new(
+        status_code: result.status_code.to_i,
+        retry_after_seconds: result.respond_to?(:retry_after_seconds) ? result.retry_after_seconds : nil
+      )
+    end
+
+    class HttpTransport
+      def initialize(endpoint)
+        @uri = URI.parse(endpoint)
+      end
+
+      def call(request)
+        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'
+          }
+        )
+
+        Result.new(
+          status_code: response.code.to_i,
+          retry_after_seconds: parse_retry_after(response['Retry-After'])
+        )
+      rescue StandardError
+        Result.new(status_code: 500)
+      end
+
+      private
+
+      def parse_retry_after(value)
+        return nil if value.nil? || value.strip.empty?
+
+        seconds = Integer(Float(value))
+        seconds.clamp(0, RETRY_AFTER_CAP_SECONDS)
+      rescue ArgumentError, TypeError
+        nil
+      end
+    end
+
+    class HttpConfigFetcher
+      def initialize(endpoint, project_token:, sdk_name:, sdk_version:)
+        @uri = URI.parse(Transport.sdk_config_endpoint(endpoint))
+        @project_token = project_token
+        @sdk_name = sdk_name
+        @sdk_version = sdk_version
+      end
+
+      def call(etag = nil)
+        http = Net::HTTP.new(@uri.host, @uri.port)
+        http.use_ssl = @uri.scheme == 'https'
+        http.open_timeout = 5
+        http.read_timeout = 5
+
+        request = Net::HTTP::Get.new(@uri.request_uri)
+        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
+
+        response = http.request(request)
+        body = response.body.to_s.empty? ? {} : JSON.parse(response.body)
+        { status_code: response.code.to_i, etag: response['ETag'], body: body }
+      rescue StandardError
+        { status_code: 500, body: {} }
+      end
+    end
+
+    class FileTransport
+      FILE_MODE = 0o600
+      DIRECTORY_MODE = 0o700
+
+      def initialize(directory)
+        @raw_directory = directory.to_s
+        @directory = File.expand_path(directory)
+      end
+
+      def call(request)
+        ensure_secure_directory!(@directory)
+
+        timestamp = Time.now.utc.strftime('%Y%m%dT%H%M%S')
+        service_fragment = request.fetch(:service_name, 'service').to_s.gsub(/[^a-zA-Z0-9_-]+/, '-')
+        token_fragment = SecureRandom.hex(12)
+        temp_path = File.join(@directory, "#{timestamp}-#{token_fragment}.tmp")
+        final_path = File.join(@directory, "#{timestamp}-#{token_fragment}-#{service_fragment}.events.json")
+
+        payload = JSON.generate(
+          request.fetch(:events)
+        )
+
+        write_secure_file(temp_path, payload)
+        reject_symlink!(final_path)
+        File.rename(temp_path, final_path)
+        File.chmod(FILE_MODE, final_path)
+
+        Result.new(status_code: 202)
+      rescue StandardError
+        Result.new(status_code: 500)
+      ensure
+        File.delete(temp_path) if defined?(temp_path) && temp_path && File.exist?(temp_path)
+      end
+
+      private
+
+      def ensure_secure_directory!(directory)
+        parent = File.dirname(directory)
+        raise ArgumentError, 'invalid directory' if @raw_directory.split(%r{[\\/]+}).include?('..')
+        raise ArgumentError, 'invalid directory' if directory.include?('..')
+
+        ensure_existing_path_is_not_symlink!(parent)
+        FileUtils.mkdir_p(directory, mode: DIRECTORY_MODE)
+        ensure_existing_path_is_not_symlink!(directory)
+        File.chmod(DIRECTORY_MODE, directory)
+      end
+
+      def ensure_existing_path_is_not_symlink!(path)
+        current = File.expand_path(path)
+
+        loop do
+          break unless File.exist?(current)
+
+          reject_symlink!(current)
+          parent = File.dirname(current)
+          break if parent == current
+
+          current = parent
+        end
+      end
+
+      def reject_symlink!(path)
+        return unless File.exist?(path)
+
+        raise IOError, 'symlink_path_rejected' if File.lstat(path).symlink?
+      end
+
+      def write_secure_file(path, payload)
+        flags = File::WRONLY | File::CREAT | File::EXCL
+        flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+        File.open(path, flags, FILE_MODE) do |handle|
+          handle.write(payload)
+          handle.flush
+          handle.fsync
+        end
+      end
+    end
+  end
+end

data/lib/debugbundle/trigger_token.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+require 'openssl'
+
+module DebugBundle
+  module TriggerToken
+    HEADER_NAME = 'x-debugbundle-probe-trigger'
+    QUERY_PARAMETER_NAME = '_debug_probe'
+    TOKEN_PREFIX = 'dbundle_probe_'
+
+    def self.resolve_request_directives(request:, trigger_token_key:)
+      return [] if request.nil? || trigger_token_key.to_s.empty?
+
+      token = extract_token(request)
+      return [] unless token&.start_with?(TOKEN_PREFIX)
+
+      payload_segment, signature_segment = split_token(token.delete_prefix(TOKEN_PREFIX))
+      return [] unless payload_segment && signature_segment
+      return [] unless valid_signature?(payload_segment, signature_segment, trigger_token_key)
+
+      payload = decode_payload(payload_segment)
+      return [] unless payload
+      return [] if payload[:expires_at] <= Time.now.utc
+
+      [
+        RemoteConfig::Directive.new(
+          id: payload[:activation_id],
+          label_pattern: payload[:label_pattern],
+          service: payload[:service],
+          environment: payload[:environment],
+          expires_at: payload[:expires_at]
+        )
+      ]
+    end
+
+    def self.extract_token(request)
+      headers = request[:headers] || request['headers'] || {}
+      header_token = extract_map_value(headers, HEADER_NAME, case_insensitive: true)
+      return header_token if header_token
+
+      query = request[:query] || request['query'] || {}
+      extract_map_value(query, QUERY_PARAMETER_NAME, case_insensitive: false)
+    end
+
+    def self.split_token(token)
+      separator_index = token.index('.')
+      return [nil, nil] unless separator_index&.positive? && separator_index < (token.length - 1)
+
+      [token[0...separator_index], token[(separator_index + 1)..]]
+    end
+
+    def self.decode_payload(payload_segment)
+      decoded = base64url_decode(payload_segment)
+      return nil unless decoded
+
+      parsed = JSON.parse(decoded)
+      return nil unless parsed.is_a?(Hash)
+
+      activation_id = parsed['activation_id']
+      label_pattern = parsed['label_pattern']
+      service = parsed['service']
+      environment = parsed['environment']
+      expires_at = Time.iso8601(parsed['trigger_expires_at'])
+
+      return nil if [activation_id, label_pattern, service, environment].any? { |value| value.to_s.empty? }
+
+      {
+        activation_id: activation_id,
+        label_pattern: label_pattern,
+        service: service,
+        environment: environment,
+        expires_at: expires_at
+      }
+    rescue JSON::ParserError, ArgumentError, TypeError
+      nil
+    end
+
+    def self.valid_signature?(payload_segment, signature_segment, trigger_token_key)
+      expected = OpenSSL::HMAC.digest('sha256', trigger_token_key, payload_segment)
+      actual = base64url_decode_bytes(signature_segment)
+      return false unless actual && actual.bytesize == expected.bytesize
+
+      secure_compare(expected, actual)
+    end
+
+    def self.secure_compare(left, right)
+      result = 0
+      left.bytes.zip(right.bytes) do |left_byte, right_byte|
+        result |= left_byte ^ right_byte
+      end
+      result.zero?
+    end
+
+    def self.extract_map_value(mapping, target_key, case_insensitive:)
+      mapping.each do |key, value|
+        matches = case_insensitive ? key.to_s.downcase == target_key.downcase : key.to_s == target_key
+        next unless matches
+
+        return value if value.is_a?(String) && !value.empty?
+        return value.first if value.is_a?(Array) && value.first.is_a?(String) && !value.first.empty?
+      end
+
+      nil
+    end
+
+    def self.base64url_decode(value)
+      decoded = base64url_decode_bytes(value)
+      decoded&.force_encoding('UTF-8')
+    end
+
+    def self.base64url_decode_bytes(value)
+      padded = value.dup
+      remainder = padded.length % 4
+      padded += '=' * (4 - remainder) if remainder.positive?
+      Base64.urlsafe_decode64(padded)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/debugbundle/version.rb

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

data/lib/debugbundle.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative 'debugbundle/redaction'
+require_relative 'debugbundle/rack/middleware'
+require_relative 'debugbundle/logging'
+require_relative 'debugbundle/remote_config'
+require_relative 'debugbundle/relay'
+require_relative 'debugbundle/rails/relay_endpoint'
+require_relative 'debugbundle/sidekiq/server_middleware'
+require_relative 'debugbundle/suppression'
+require_relative 'debugbundle/transport'
+require_relative 'debugbundle/trigger_token'
+require_relative 'debugbundle/client'
+require_relative 'debugbundle/config'
+require_relative 'debugbundle/version'
+
+require_relative 'debugbundle/rails' if defined?(Rails::Railtie)
+
+module DebugBundle
+  class << self
+    def init(**options)
+      self.client = Client.new(**options)
+      client.capture_exceptions
+      client
+    end
+
+    def client
+      @client ||= Client.new
+    end
+
+    attr_writer :client
+
+    def capture_exception(error, context: nil)
+      client.capture_exception(error, context: context)
+    end
+
+    def capture_error(error, context: nil)
+      client.capture_error(error, context: context)
+    end
+
+    def capture_log(message, level: :warning, context: nil)
+      client.capture_log(message, level: level, context: context)
+    end
+
+    def capture_request(request, response, context: nil)
+      client.capture_request(request, response, context: context)
+    end
+
+    def capture_message(message, level: nil, context: nil)
+      client.capture_message(message, level: level, context: context)
+    end
+
+    def set_context(key, value)
+      client.set_context(key, value)
+    end
+
+    def probe(label, data = nil, heavy: false, &block)
+      client.probe(label, data, heavy: heavy, &block)
+    end
+
+    def capture_exceptions
+      client.capture_exceptions
+    end
+
+    def capture_at_exit
+      client.capture_at_exit
+    end
+
+    def with_exception_capture(context: nil, &block)
+      client.with_exception_capture(context: context, &block)
+    end
+
+    def capture_logger(logger = ::Logger.new($stdout))
+      client.capture_logger(logger)
+    end
+
+    def capture_semantic_logger
+      client.capture_semantic_logger
+    end
+
+    def flush
+      client.flush
+    end
+
+    def status
+      client.status
+    end
+
+    def last_event_at
+      client.last_event_at
+    end
+  end
+end

data/spec/client_spec.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'json'
+require 'tmpdir'
+
+RSpec.describe DebugBundle::Client 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 'buffers and flushes canonical events' do
+    client = described_class.new(
+      project_token: 'dbundle_proj_test',
+      service: 'checkout-api',
+      environment: 'production',
+      transport: transport
+    )
+
+    client.set_context(:account_id, 'acct_123')
+    client.capture_log('payment retry failed', level: :error, context: { trace_id: 'trace-1' })
+
+    expect(client.buffered_event_count).to eq(1)
+    expect(client.flush).to be(true)
+    expect(client.last_event_at).not_to be_nil
+
+    payload = transport_events.fetch(0)
+    event = payload.fetch(:events).fetch(0)
+
+    expect(event.fetch('event_type')).to eq('log_event')
+    expect(event.fetch('schema_version')).to eq('2026-03-01')
+    expect(event.fetch('sdk_name')).to eq('@debugbundle/sdk-ruby')
+    expect(event.fetch('service')).to include('name' => 'checkout-api', 'environment' => 'production')
+    expect(event.fetch('correlation')).to include('trace_id' => 'trace-1')
+    expect(event.fetch('payload')).to include('level' => 'error', 'message' => 'payment retry failed')
+  end
+
+  it 'captures explicit exception blocks and re-raises' do
+    client = described_class.new(project_token: 'dbundle_proj_test', transport: transport)
+
+    expect do
+      client.with_exception_capture(context: { request_id: 'req-1' }) do
+        raise ArgumentError, 'invalid checkout'
+      end
+    end.to raise_error(ArgumentError, 'invalid checkout')
+
+    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-1')
+  end
+
+  it 'registers at-exit capture once and flushes shutdown exceptions' do
+    client = described_class.new(project_token: 'dbundle_proj_test', transport: transport)
+    registered_callback = nil
+
+    allow(client).to receive(:at_exit) do |&block|
+      registered_callback = block
+    end
+
+    expect(client.capture_exceptions).to be(true)
+    expect(client.capture_at_exit).to be(false)
+    expect(registered_callback).not_to be_nil
+
+    begin
+      raise 'shutdown boom'
+    rescue RuntimeError
+      registered_callback.call
+    end
+
+    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, 'message' => 'shutdown boom')
+  end
+
+  it 'captures unhandled thread exceptions after hooks are armed' do
+    client = described_class.new(project_token: 'dbundle_proj_test', transport: transport)
+
+    allow(client).to receive(:at_exit)
+
+    expect(client.capture_exceptions).to be(true)
+
+    thread = Thread.new do
+      raise 'thread boom'
+    end
+
+    expect { thread.value }.to raise_error(RuntimeError, 'thread boom')
+
+    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, 'message' => 'thread boom')
+  end
+
+  it 'suppresses duplicate exceptions and emits an aggregate' do
+    client = described_class.new(project_token: 'dbundle_proj_test', transport: transport)
+    error = RuntimeError.new('boom')
+    error.set_backtrace(['app/models/checkout.rb:10'])
+
+    5.times { client.capture_exception(error) }
+
+    expect(client.buffered_event_count).to eq(3)
+    client.flush
+
+    flushed_events = transport_events.fetch(0).fetch(:events)
+    expect(flushed_events.count { |event| event.fetch('event_type') == 'backend_exception' }).to eq(3)
+    expect(flushed_events.count { |event| event.fetch('event_type') == 'error_suppressed' }).to eq(1)
+  end
+
+  it 'backs off after 429 responses without dropping buffered events' do
+    retry_transport = Class.new do
+      def initialize
+        @calls = 0
+      end
+
+      def call(_request)
+        @calls += 1
+        return DebugBundle::Transport::Result.new(status_code: 429, retry_after_seconds: 1) if @calls == 1
+
+        DebugBundle::Transport::Result.new(status_code: 202)
+      end
+    end.new
+
+    current_time = Time.utc(2026, 5, 23, 12, 0, 0)
+    time_provider = -> { current_time }
+
+    client = described_class.new(project_token: 'dbundle_proj_test', transport: retry_transport,
+                                 time_provider: time_provider)
+    client.capture_log('worker started', level: :warning)
+
+    expect(client.flush).to be(false)
+    expect(client.buffered_event_count).to eq(1)
+    expect(client.status).to eq(:degraded)
+
+    current_time += 2
+    expect(client.flush).to be(true)
+    expect(client.buffered_event_count).to eq(0)
+  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)
+
+      client.capture_log('local event', level: :error)
+      expect(client.flush).to be(true)
+
+      file_name = Dir.children(directory).find { |entry| entry.end_with?('.events.json') }
+      event = JSON.parse(File.read(File.join(directory, file_name))).fetch(0)
+
+      expect(event.fetch('event_type')).to eq('log_event')
+      expect(event.fetch('payload')).to include('message' => 'local event')
+    end
+  end
+
+  it 'does not raise for invalid project mode configuration' do
+    expect do
+      described_class.new(project_token: 'dbundle_proj_test', project_mode: :surprising, transport: transport)
+    end.not_to raise_error
+  end
+
+  it 'applies sample rate before buffering events' do
+    client = described_class.new(
+      project_token: 'dbundle_proj_test',
+      transport: transport,
+      sample_rate: 0.25,
+      random_provider: -> { 0.9 }
+    )
+
+    client.capture_log('sampled out', level: :error)
+
+    expect(client.buffered_event_count).to eq(0)
+  end
+
+  it 'does not include local OS account names in runtime facts' do
+    client = described_class.new(project_token: 'dbundle_proj_test', transport: transport)
+
+    client.capture_exception(RuntimeError.new('privacy check'))
+    client.flush
+
+    runtime = transport_events.fetch(0).fetch(:events).fetch(0).fetch('payload').fetch('runtime')
+    expect(runtime).not_to have_key('user')
+  end
+
+  it 'builds a default remote config fetcher for connected remote environments' do
+    fetcher_instances = []
+    fetcher_class = Class.new do
+      define_method(:initialize) do |endpoint, project_token:, sdk_name:, sdk_version:|
+        fetcher_instances << {
+          endpoint: endpoint,
+          project_token: project_token,
+          sdk_name: sdk_name,
+          sdk_version: sdk_version
+        }
+      end
+
+      define_method(:call) do |_etag|
+        {
+          status_code: 200,
+          etag: 'cfg-default',
+          body: {
+            capture_policy: {
+              preset: 'minimal',
+              capture_logs: 'error',
+              capture_request_events: 'failures_only',
+              capture_breadcrumbs: 'local_only',
+              capture_probe_events: 'buffer_only',
+              immediate_client_error_statuses: []
+            }
+          }
+        }
+      end
+    end
+
+    stub_const('DebugBundle::Transport::HttpConfigFetcher', fetcher_class)
+
+    client = described_class.new(project_token: 'dbundle_proj_test', environment: 'production')
+    client.capture_log('warning dropped by default fetched policy', level: :warning)
+
+    expect(fetcher_instances.fetch(0)).to include(
+      endpoint: DebugBundle::Config::DEFAULT_ENDPOINT,
+      project_token: 'dbundle_proj_test',
+      sdk_name: '@debugbundle/sdk-ruby'
+    )
+    expect(client.buffered_event_count).to eq(0)
+  end
+end

data/spec/debugbundle_spec.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe DebugBundle do
+  before do
+    described_class.client = DebugBundle::Client.new
+  end
+
+  it 'exposes the universal singleton interface' do
+    client = described_class.init(project_token: 'dbundle_proj_test', service: 'checkout-api')
+
+    expect(client).to be_a(DebugBundle::Client)
+    expect(described_class).to respond_to(:init)
+    expect(described_class).to respond_to(:capture_exception)
+    expect(described_class).to respond_to(:capture_error)
+    expect(described_class).to respond_to(:capture_log)
+    expect(described_class).to respond_to(:capture_request)
+    expect(described_class).to respond_to(:capture_message)
+    expect(described_class).to respond_to(:set_context)
+    expect(described_class).to respond_to(:probe)
+    expect(described_class).to respond_to(:flush)
+    expect(described_class).to respond_to(:status)
+    expect(described_class).to respond_to(:last_event_at)
+  end
+
+  it 'arms exception capture when initialized' do
+    client = instance_double(DebugBundle::Client)
+    allow(DebugBundle::Client).to receive(:new).and_return(client)
+    allow(client).to receive(:capture_exceptions).and_return(true)
+
+    expect(client).to receive(:capture_exceptions)
+    expect(described_class.init(project_token: 'dbundle_proj_test')).to be(client)
+  end
+
+  it 'reports a degraded status without a configured project token' do
+    described_class.client = DebugBundle::Client.new
+
+    expect(described_class.status).to eq(:degraded)
+  end
+
+  it 'records the last event timestamp on flush' do
+    transport = Class.new do
+      def call(_request)
+        DebugBundle::Transport::Result.new(status_code: 202)
+      end
+    end.new
+
+    described_class.client = DebugBundle::Client.new(project_token: 'dbundle_proj_test', transport: transport)
+    described_class.capture_log('worker started', level: :warning)
+
+    expect { described_class.flush }.to change(described_class, :last_event_at).from(nil)
+  end
+end