debugbundle 0.1.0

data/lib/debugbundle/relay/handler.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'uri'
+
+module DebugBundle
+  module Relay
+    ACCEPTED_EVENT_TYPES = %w[
+      frontend_exception
+      error_suppressed
+      frontend_breadcrumb
+      request_event
+      probe_event
+    ].freeze
+    BROWSER_SDK_NAME = '@debugbundle/sdk-browser'
+    DEFAULT_MAX_BODY_BYTES = 262_144
+    DEFAULT_RATE_LIMIT_PER_MINUTE = 60
+
+    Response = Struct.new(:status, :body, keyword_init: true)
+
+    class Handler
+      def initialize(
+        project_mode: :connected,
+        project_token: nil,
+        endpoint: DebugBundle::Config::DEFAULT_ENDPOINT,
+        local_events_dir: DebugBundle::Config::DEFAULT_LOCAL_EVENTS_DIR,
+        spool_dir: DebugBundle::Config::DEFAULT_SPOOL_DIR,
+        durable_write: true,
+        service: nil,
+        environment: nil,
+        allowed_origins: nil,
+        max_body_bytes: DEFAULT_MAX_BODY_BYTES,
+        rate_limit_per_minute: DEFAULT_RATE_LIMIT_PER_MINUTE,
+        rate_limit_store: nil,
+        forward_transport: nil
+      )
+        @project_mode = project_mode.to_sym
+        @project_token = project_token
+        @endpoint = endpoint
+        @local_events_dir = local_events_dir
+        @spool_dir = spool_dir
+        @durable_write = durable_write
+        @service = service
+        @environment = environment
+        @allowed_origins = Array(allowed_origins).compact.map { |origin| normalize_origin(origin) }
+        @max_body_bytes = max_body_bytes
+        @rate_limit_per_minute = rate_limit_per_minute
+        @rate_limit_store = rate_limit_store
+        @forward_transport = forward_transport || Transport::HttpTransport.new(@endpoint)
+        @rate_limit_state = Hash.new { |hash, key| hash[key] = [] }
+      end
+
+      def handle(request)
+        return Response.new(status: 405, body: nil) unless request.fetch(:method, 'POST').to_s.upcase == 'POST'
+
+        headers = normalize_headers(request[:headers] || {})
+        return Response.new(status: 403, body: nil) unless origin_allowed?(headers)
+        unless json_content_type?(headers['content-type'])
+          return Response.new(status: 400,
+                              body: invalid_body('Relay requests must use Content-Type: application/json.'))
+        end
+
+        raw_body = request[:body].to_s
+        return Response.new(status: 413, body: nil) if raw_body.bytesize > @max_body_bytes
+        return Response.new(status: 429, body: nil) if rate_limited?(request[:ip_address] || request[:ip])
+
+        decoded = JSON.parse(raw_body)
+        batch = decoded.fetch('batch')
+        unless batch.is_a?(Array)
+          return Response.new(status: 400,
+                              body: invalid_body('Relay request body must include a batch array.'))
+        end
+
+        accepted = []
+        errors = []
+
+        batch.each_with_index do |candidate, index|
+          sanitized = sanitize_event(candidate)
+          if sanitized
+            accepted << sanitized
+          else
+            errors << "batch[#{index}]: Invalid browser relay event payload."
+          end
+        end
+
+        deliver(accepted) unless accepted.empty?
+
+        unless errors.empty?
+          return Response.new(status: 400,
+                              body: { 'accepted' => accepted.length,
+                                      'rejected' => errors.length, 'errors' => errors })
+        end
+
+        Response.new(status: 202, body: { 'accepted' => accepted.length, 'rejected' => 0, 'errors' => [] })
+      rescue JSON::ParserError
+        Response.new(status: 400, body: invalid_body('Relay request body must be valid JSON.'))
+      rescue KeyError
+        Response.new(status: 400, body: invalid_body('Relay request body must include a batch array.'))
+      rescue StandardError
+        Response.new(status: 500, body: nil)
+      end
+
+      private
+
+      def deliver(events)
+        service_name = @service || events.first.dig('service', 'name') || 'service'
+
+        case @project_mode
+        when :local_only
+          Transport::FileTransport.new(@local_events_dir).call(service_name: service_name, events: events)
+        when :connected
+          Transport::FileTransport.new(@spool_dir).call(service_name: service_name, events: events) if @durable_write
+
+          result = Transport.coerce_result(@forward_transport.call(project_token: @project_token, events: events))
+          raise 'relay_forward_failed' unless result.status_code.between?(200, 299)
+        else
+          raise ArgumentError, 'unsupported relay project mode'
+        end
+      end
+
+      def sanitize_event(candidate)
+        return nil unless candidate.is_a?(Hash)
+
+        event_type = candidate['event_type']
+        return nil unless ACCEPTED_EVENT_TYPES.include?(event_type)
+
+        service = candidate['service']
+        correlation = candidate['correlation']
+        payload = candidate['payload']
+        return nil unless service.is_a?(Hash) && payload.is_a?(Hash)
+
+        {
+          'schema_version' => candidate['schema_version'].to_s,
+          'event_id' => candidate['event_id'].to_s,
+          'event_type' => event_type,
+          'sdk_name' => BROWSER_SDK_NAME,
+          'sdk_version' => candidate['sdk_version'].to_s,
+          'occurred_at' => candidate['occurred_at'].to_s,
+          'service' => {
+            'name' => @service || service['name'].to_s,
+            'environment' => @environment || service['environment'].to_s
+          },
+          'correlation' => sanitize_correlation(correlation),
+          'payload' => payload,
+          'project_token' => @project_token
+        }
+      end
+
+      def sanitize_correlation(value)
+        correlation = value.is_a?(Hash) ? value : {}
+        {
+          'request_id' => string_or_nil(correlation['request_id']),
+          'trace_id' => string_or_nil(correlation['trace_id']),
+          'session_id' => string_or_nil(correlation['session_id']),
+          'user_id_hash' => string_or_nil(correlation['user_id_hash'])
+        }
+      end
+
+      def string_or_nil(value)
+        value.is_a?(String) ? value : nil
+      end
+
+      def invalid_body(message)
+        { 'accepted' => 0, 'rejected' => 0, 'errors' => [message] }
+      end
+
+      def normalize_headers(headers)
+        headers.each_with_object({}) do |(key, value), result|
+          result[key.to_s.downcase] = value.to_s
+        end
+      end
+
+      def json_content_type?(value)
+        value.to_s.downcase.include?('application/json')
+      end
+
+      def origin_allowed?(headers)
+        origin = headers['origin'] || origin_from_referer(headers['referer'])
+        return false if origin.nil? || origin.empty?
+
+        return @allowed_origins.include?(normalize_origin(origin)) if @allowed_origins.any?
+
+        host = headers['host'].to_s.split(':').first
+        return false if host.empty?
+
+        URI.parse(origin).host == host
+      rescue URI::InvalidURIError
+        false
+      end
+
+      def origin_from_referer(referer)
+        return nil if referer.to_s.empty?
+
+        parsed = URI.parse(referer)
+        return nil unless parsed.scheme && parsed.host
+
+        "#{parsed.scheme}://#{parsed.host}"
+      rescue URI::InvalidURIError
+        nil
+      end
+
+      def normalize_origin(origin)
+        origin.to_s.downcase.sub(%r{/$}, '')
+      end
+
+      def rate_limited?(ip)
+        key = ip.to_s.empty? ? 'unknown' : ip.to_s
+        return shared_rate_limited?(key) if @rate_limit_store
+
+        cutoff = Time.now.to_i - 60
+        @rate_limit_state[key] = @rate_limit_state[key].select { |entry| entry > cutoff }
+        return true if @rate_limit_state[key].length >= @rate_limit_per_minute
+
+        @rate_limit_state[key] << Time.now.to_i
+        false
+      end
+
+      def shared_rate_limited?(key)
+        cache_key = "debugbundle:relay-rate:#{key}:#{Time.now.to_i / 60}"
+        count = @rate_limit_store.increment(cache_key, 1, expires_in: 60)
+        if count.nil? && @rate_limit_store.respond_to?(:write)
+          @rate_limit_store.write(cache_key, 1, expires_in: 60)
+          count = 1
+        end
+        count.to_i > @rate_limit_per_minute
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/debugbundle/relay.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'relay/handler'
+require_relative 'rack/relay_middleware'

data/lib/debugbundle/remote_config.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module DebugBundle
+  module RemoteConfig
+    CapturePolicy = Struct.new(
+      :preset,
+      :capture_logs,
+      :capture_request_events,
+      :capture_breadcrumbs,
+      :capture_probe_events,
+      :immediate_client_error_statuses,
+      keyword_init: true
+    )
+
+    Directive = Struct.new(:id, :label_pattern, :service, :environment, :expires_at, keyword_init: true) do
+      def active?(label:, service:, environment:, now:)
+        return false if expires_at <= now
+        return false unless match_scope?(self.service, service)
+        return false unless match_scope?(self.environment, environment)
+
+        match_label?(label_pattern, label)
+      end
+
+      private
+
+      def match_scope?(pattern, value)
+        pattern == '*' || pattern == value
+      end
+
+      def match_label?(pattern, label)
+        return true if pattern == '*'
+
+        if pattern.end_with?('.*')
+          prefix = pattern.delete_suffix('.*')
+          return label == prefix || label.start_with?("#{prefix}.")
+        end
+
+        pattern == label
+      end
+    end
+
+    Snapshot = Struct.new(
+      :probes_enabled,
+      :remote_probes_enabled,
+      :directives,
+      :poll_interval_seconds,
+      :capture_policy,
+      :trigger_token_key,
+      keyword_init: true
+    ) do
+      def self.default
+        new(
+          probes_enabled: true,
+          remote_probes_enabled: false,
+          directives: [],
+          poll_interval_seconds: 60,
+          capture_policy: RemoteConfig.balanced_capture_policy,
+          trigger_token_key: nil
+        )
+      end
+    end
+
+    def self.minimal_capture_policy
+      CapturePolicy.new(
+        preset: 'minimal',
+        capture_logs: 'error',
+        capture_request_events: 'failures_only',
+        capture_breadcrumbs: 'local_only',
+        capture_probe_events: 'buffer_only',
+        immediate_client_error_statuses: []
+      )
+    end
+
+    def self.balanced_capture_policy
+      CapturePolicy.new(
+        preset: 'balanced',
+        capture_logs: 'warning',
+        capture_request_events: 'failures_only',
+        capture_breadcrumbs: 'exception_only',
+        capture_probe_events: 'buffer_only',
+        immediate_client_error_statuses: []
+      )
+    end
+
+    def self.parse(payload, fallback_poll_interval_seconds)
+      return nil unless payload.is_a?(Hash)
+
+      capture_policy =
+        parse_capture_policy(payload['capture_policy'] || payload[:capture_policy]) || balanced_capture_policy
+      directives = Array(payload['active_probes'] || payload[:active_probes]).filter_map do |entry|
+        parse_directive(entry)
+      end
+
+      poll_interval_ms = payload['poll_interval_ms'] || payload[:poll_interval_ms]
+      poll_interval_seconds = if poll_interval_ms.to_i.positive?
+                                [(poll_interval_ms.to_i / 1000), 1].max
+                              else
+                                fallback_poll_interval_seconds
+                              end
+
+      Snapshot.new(
+        probes_enabled: payload['probes_enabled'] != false && payload[:probes_enabled] != false,
+        remote_probes_enabled: payload['remote_probes_enabled'] == true || payload[:remote_probes_enabled] == true,
+        directives: directives,
+        poll_interval_seconds: poll_interval_seconds,
+        capture_policy: capture_policy,
+        trigger_token_key: payload['trigger_token_key'] || payload[:trigger_token_key]
+      )
+    end
+
+    def self.parse_capture_policy(payload)
+      return nil unless payload.is_a?(Hash)
+
+      CapturePolicy.new(
+        preset: payload['preset'] || payload[:preset] || 'balanced',
+        capture_logs: payload['capture_logs'] || payload[:capture_logs] || 'warning',
+        capture_request_events:
+          payload['capture_request_events'] || payload[:capture_request_events] || 'failures_only',
+        capture_breadcrumbs: payload['capture_breadcrumbs'] || payload[:capture_breadcrumbs] || 'exception_only',
+        capture_probe_events: payload['capture_probe_events'] || payload[:capture_probe_events] || 'buffer_only',
+        immediate_client_error_statuses: Array(
+          payload['immediate_client_error_statuses'] || payload[:immediate_client_error_statuses]
+        ).grep(Integer)
+      )
+    end
+
+    def self.parse_directive(payload)
+      return nil unless payload.is_a?(Hash)
+
+      expires_at_value = payload['expires_at'] || payload[:expires_at]
+      expires_at = parse_time(expires_at_value)
+      return nil unless expires_at
+
+      Directive.new(
+        id: payload['id'] || payload[:id],
+        label_pattern: payload['label_pattern'] || payload[:label_pattern],
+        service: payload['service'] || payload[:service] || '*',
+        environment: payload['environment'] || payload[:environment] || '*',
+        expires_at: expires_at
+      )
+    end
+
+    def self.parse_time(value)
+      return nil unless value.is_a?(String) && !value.empty?
+
+      Time.iso8601(value)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/debugbundle/runtime.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'socket'
+
+module DebugBundle
+  module Runtime
+    def self.payload
+      {
+        'version' => RUBY_VERSION,
+        'platform' => RUBY_PLATFORM,
+        'pid' => Process.pid,
+        'cwd' => Dir.pwd,
+        'hostname' => Socket.gethostname,
+        'thread_id' => Thread.current.object_id,
+        'engine' => defined?(RUBY_ENGINE) ? RUBY_ENGINE : 'ruby',
+        'engine_version' => defined?(RUBY_ENGINE_VERSION) ? RUBY_ENGINE_VERSION : RUBY_VERSION
+      }
+    rescue StandardError
+      { 'version' => RUBY_VERSION }
+    end
+  end
+end

data/lib/debugbundle/sidekiq/server_middleware.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module DebugBundle
+  module Sidekiq
+    class ServerMiddleware
+      def initialize(options = nil, client: nil)
+        resolved_options = options.is_a?(Hash) ? options : {}
+        @client = client || resolved_options[:client] || resolved_options['client'] || DebugBundle.client
+      end
+
+      def call(_worker, job, queue)
+        yield
+      rescue StandardError => e
+        @client.capture_exception(
+          e,
+          context: {
+            queue: queue,
+            job: {
+              class: job['class'],
+              queue: job['queue'] || queue,
+              jid: job['jid'],
+              retry_count: job['retry_count'] || job['retry'],
+              args_summary: Array(job['args']).first(5).map { |value| value.class.name }
+            },
+            job_id: job['jid'],
+            trace_id: job['trace_id']
+          },
+          handled: false
+        )
+        raise
+      end
+    end
+  end
+end

data/lib/debugbundle/suppression.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'time'
+
+module DebugBundle
+  module Suppression
+    DUPLICATE_WINDOW_SECONDS = 30.0
+    LOOP_WINDOW_SECONDS = 2.0
+    LOOP_THRESHOLD = 10
+    LOOP_RESET_AFTER_SECONDS = 60.0
+    LOOP_CHECKPOINT_SECONDS = 30.0
+    MAX_NORMAL_EVENTS_PER_WINDOW = 3
+
+    State = Struct.new(
+      :window_started_at,
+      :emitted_count,
+      :pending_suppressed_count,
+      :pending_first_seen_at,
+      :pending_last_seen_at,
+      :last_aggregate_emitted_at,
+      :loop_window_started_at,
+      :loop_hit_count,
+      :suppression_mode,
+      :last_seen_at,
+      keyword_init: true
+    )
+
+    class Tracker
+      def initialize
+        @states = {}
+      end
+
+      def should_capture(key, now:)
+        state = (@states[key] ||= new_state(now))
+
+        if state.suppression_mode && (now - state.last_seen_at) >= LOOP_RESET_AFTER_SECONDS
+          @states[key] = new_state(now)
+          state = @states[key]
+        end
+
+        if (now - state.window_started_at) >= DUPLICATE_WINDOW_SECONDS
+          state.window_started_at = now
+          state.emitted_count = 0
+        end
+
+        if (now - state.loop_window_started_at) >= LOOP_WINDOW_SECONDS
+          state.loop_window_started_at = now
+          state.loop_hit_count = 0
+        end
+
+        state.loop_hit_count += 1
+        state.last_seen_at = now
+        state.suppression_mode = true if state.loop_hit_count > LOOP_THRESHOLD
+
+        if state.suppression_mode
+          mark_suppressed(state, now)
+          return false
+        end
+
+        if state.emitted_count < MAX_NORMAL_EVENTS_PER_WINDOW
+          state.emitted_count += 1
+          return true
+        end
+
+        mark_suppressed(state, now)
+        false
+      end
+
+      def drain_aggregates(now:)
+        @states.each_with_object([]) do |(key, state), aggregates|
+          next if state.pending_suppressed_count.zero?
+          next if state.pending_first_seen_at.nil? || state.pending_last_seen_at.nil?
+          next if checkpoint_not_due?(state, now)
+
+          aggregates << {
+            'fingerprint' => Digest::SHA256.hexdigest(key),
+            'suppressed_count' => state.pending_suppressed_count,
+            'first_seen' => Time.at(state.pending_first_seen_at).utc.iso8601,
+            'last_seen' => Time.at(state.pending_last_seen_at).utc.iso8601,
+            'window_seconds' => DUPLICATE_WINDOW_SECONDS.to_i
+          }
+
+          state.pending_suppressed_count = 0
+          state.pending_first_seen_at = nil
+          state.pending_last_seen_at = nil
+          state.last_aggregate_emitted_at = now
+        end
+      end
+
+      private
+
+      def new_state(now)
+        State.new(
+          window_started_at: now,
+          emitted_count: 0,
+          pending_suppressed_count: 0,
+          pending_first_seen_at: nil,
+          pending_last_seen_at: nil,
+          last_aggregate_emitted_at: nil,
+          loop_window_started_at: now,
+          loop_hit_count: 0,
+          suppression_mode: false,
+          last_seen_at: now
+        )
+      end
+
+      def mark_suppressed(state, now)
+        state.pending_first_seen_at ||= state.window_started_at
+        state.pending_suppressed_count += 1
+        state.pending_last_seen_at = now
+      end
+
+      def checkpoint_not_due?(state, now)
+        state.suppression_mode &&
+          state.last_aggregate_emitted_at &&
+          (now - state.last_aggregate_emitted_at) < LOOP_CHECKPOINT_SECONDS
+      end
+    end
+  end
+end