debugbundle 0.1.0

data/lib/debugbundle/config.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module DebugBundle
+  class Config
+    DEFAULT_ENDPOINT = 'https://api.debugbundle.com/v1/events'
+    DEFAULT_PROJECT_MODE = :connected
+    DEFAULT_BATCH_SIZE = 25
+    DEFAULT_FLUSH_INTERVAL = 5
+    DEFAULT_SAMPLE_RATE = 1.0
+    DEFAULT_LOG_LEVEL = :warning
+    DEFAULT_LOCAL_EVENTS_DIR = '.debugbundle/local/events'
+    DEFAULT_SPOOL_DIR = '.debugbundle/local/browser-relay-spool'
+    DEFAULT_RELAY_RATE_LIMIT_PER_MINUTE = 60
+    DEFAULT_MAX_PROBE_LABELS = 50
+    DEFAULT_MAX_PROBE_ENTRIES_PER_LABEL = 10
+    DEFAULT_PROBE_FLUSH_ON_ERROR = true
+    DEFAULT_PROBES_POLL_INTERVAL = 60
+    DEFAULT_REDACT_FIELDS = [].freeze
+
+    VALID_PROJECT_MODES = %i[connected local_only].freeze
+    VALID_STATUSES = %i[healthy degraded disconnected].freeze
+
+    attr_reader :project_token,
+                :enabled,
+                :environment,
+                :service,
+                :endpoint,
+                :project_mode,
+                :local_events_dir,
+                :spool_dir,
+                :batch_size,
+                :flush_interval,
+                :sample_rate,
+                :log_level,
+                :relay_enabled,
+                :relay_rate_limit_per_minute,
+                :relay_durable_write,
+                :redact_fields,
+                :max_probe_labels,
+                :max_probe_entries_per_label,
+                :probe_flush_on_error,
+                :probes_poll_interval
+
+    def initialize(
+      project_token: nil,
+      enabled: true,
+      environment: nil,
+      service: nil,
+      endpoint: DEFAULT_ENDPOINT,
+      project_mode: DEFAULT_PROJECT_MODE,
+      local_events_dir: DEFAULT_LOCAL_EVENTS_DIR,
+      spool_dir: DEFAULT_SPOOL_DIR,
+      batch_size: DEFAULT_BATCH_SIZE,
+      flush_interval: DEFAULT_FLUSH_INTERVAL,
+      sample_rate: DEFAULT_SAMPLE_RATE,
+      log_level: DEFAULT_LOG_LEVEL,
+      relay_enabled: true,
+      relay_rate_limit_per_minute: DEFAULT_RELAY_RATE_LIMIT_PER_MINUTE,
+      relay_durable_write: true,
+      redact_fields: DEFAULT_REDACT_FIELDS,
+      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
+    )
+      @project_token = project_token
+      @enabled = enabled
+      @environment = environment
+      @service = service
+      @endpoint = endpoint
+      @project_mode = normalize_project_mode(project_mode)
+      @local_events_dir = local_events_dir
+      @spool_dir = spool_dir
+      @batch_size = normalize_positive_integer(batch_size, DEFAULT_BATCH_SIZE)
+      @flush_interval = normalize_positive_number(flush_interval, DEFAULT_FLUSH_INTERVAL)
+      @sample_rate = normalize_sample_rate(sample_rate)
+      @log_level = log_level
+      @relay_enabled = relay_enabled
+      @relay_rate_limit_per_minute = normalize_positive_integer(
+        relay_rate_limit_per_minute,
+        DEFAULT_RELAY_RATE_LIMIT_PER_MINUTE
+      )
+      @relay_durable_write = relay_durable_write
+      @redact_fields = normalize_redact_fields(redact_fields)
+      @max_probe_labels = normalize_positive_integer(max_probe_labels, DEFAULT_MAX_PROBE_LABELS)
+      @max_probe_entries_per_label = normalize_positive_integer(
+        max_probe_entries_per_label,
+        DEFAULT_MAX_PROBE_ENTRIES_PER_LABEL
+      )
+      @probe_flush_on_error = probe_flush_on_error
+      @probes_poll_interval = normalize_positive_number(probes_poll_interval, DEFAULT_PROBES_POLL_INTERVAL)
+      freeze
+    end
+
+    def enabled?
+      enabled
+    end
+
+    def configured?
+      !project_token.to_s.empty?
+    end
+
+    private
+
+    def normalize_project_mode(value)
+      normalized = value.to_s.strip.downcase.tr('-', '_').to_sym
+      return normalized if VALID_PROJECT_MODES.include?(normalized)
+
+      DEFAULT_PROJECT_MODE
+    end
+
+    def normalize_positive_integer(value, fallback)
+      integer = Integer(value)
+      integer.positive? ? integer : fallback
+    rescue ArgumentError, TypeError
+      fallback
+    end
+
+    def normalize_positive_number(value, fallback)
+      number = Float(value)
+      number.positive? ? number : fallback
+    rescue ArgumentError, TypeError
+      fallback
+    end
+
+    def normalize_sample_rate(value)
+      number = Float(value)
+      number.clamp(0.0, 1.0)
+    rescue ArgumentError, TypeError
+      DEFAULT_SAMPLE_RATE
+    end
+
+    def normalize_redact_fields(value)
+      Array(value).filter_map do |entry|
+        case entry
+        when String, Symbol
+          entry.to_s
+        when Regexp
+          entry.source
+        end
+      end.freeze
+    end
+  end
+end

data/lib/debugbundle/logging.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module DebugBundle
+  module Logging
+    RECURSION_GUARD_KEY = :__debugbundle_logger_capture_active__
+    LOGGER_LEVEL_NAMES = {
+      ::Logger::DEBUG => :debug,
+      ::Logger::INFO => :info,
+      ::Logger::WARN => :warning,
+      ::Logger::ERROR => :error,
+      ::Logger::FATAL => :fatal,
+      ::Logger::UNKNOWN => :critical
+    }.freeze
+
+    def self.install_stdlib_logger(logger, client:)
+      interceptor = Module.new do
+        define_method(:add) do |severity, message = nil, progname = nil, &block|
+          was_capturing = Thread.current[RECURSION_GUARD_KEY]
+          unless was_capturing
+            Thread.current[RECURSION_GUARD_KEY] = true
+            resolved_message = message
+            resolved_message = block.call if resolved_message.nil? && block
+            resolved_message = progname if resolved_message.nil?
+
+            client.capture_log(
+              resolved_message.to_s,
+              level: LOGGER_LEVEL_NAMES.fetch(severity || ::Logger::UNKNOWN, :warning),
+              context: { logger_name: logger.progname }
+            )
+          end
+
+          super(severity, message, progname, &block)
+        ensure
+          Thread.current[RECURSION_GUARD_KEY] = was_capturing
+        end
+      end
+
+      logger.singleton_class.prepend(interceptor)
+      interceptor
+    end
+
+    def self.install_semantic_logger(client:)
+      return nil unless defined?(::SemanticLogger)
+      return nil unless ::SemanticLogger.respond_to?(:add_appender)
+
+      appender = SemanticLoggerAppender.new(client: client)
+      ::SemanticLogger.add_appender(appender: appender)
+      appender
+    end
+
+    class SemanticLoggerAppender
+      def initialize(client: DebugBundle.client)
+        @client = client
+      end
+
+      def log(log)
+        was_capturing = Thread.current[RECURSION_GUARD_KEY]
+        return if was_capturing
+
+        Thread.current[RECURSION_GUARD_KEY] = true
+        @client.capture_log(
+          log.message,
+          level: log.level || :info,
+          context: {
+            logger_name: log.name,
+            payload: log.payload,
+            tags: log.tags
+          }
+        )
+      ensure
+        Thread.current[RECURSION_GUARD_KEY] = was_capturing
+      end
+    end
+  end
+end

data/lib/debugbundle/rack/middleware.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'cgi'
+
+module DebugBundle
+  module Rack
+    class Middleware
+      def initialize(app, client: DebugBundle.client)
+        @app = app
+        @client = client
+      end
+
+      def call(env)
+        request_context = build_request_context(env)
+        started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @client.with_request_trigger(request_context.fetch(:request)) do
+          status, headers, body = @app.call(env)
+          duration_ms = elapsed_ms(started_at)
+
+          @client.capture_request(
+            request_context.fetch(:request),
+            { status_code: status, headers: headers.to_h },
+            context: request_context.merge(duration_ms: duration_ms, route_template: route_template(env))
+          )
+
+          [status, headers, body]
+        end
+      rescue StandardError => e
+        duration_ms = elapsed_ms(started_at)
+        @client.capture_exception(
+          e,
+          context: request_context.merge(
+            response: { status_code: 500, headers: {} },
+            duration_ms: duration_ms,
+            route_template: route_template(env)
+          ),
+          handled: false
+        )
+        raise
+      end
+
+      private
+
+      def build_request_context(env)
+        {
+          request: {
+            method: env['REQUEST_METHOD'],
+            path: env['PATH_INFO'],
+            query: parse_query(env['QUERY_STRING']),
+            headers: request_headers(env),
+            body: {}
+          },
+          request_id: env['action_dispatch.request_id'] || env['HTTP_X_REQUEST_ID'],
+          trace_id: env['HTTP_X_DEBUGBUNDLE_TRACE_ID']
+        }.merge(rails_metadata(env))
+      end
+
+      def request_headers(env)
+        env.each_with_object({}) do |(key, value), headers|
+          next unless key.start_with?('HTTP_') || %w[CONTENT_TYPE ACCEPT].include?(key)
+
+          normalized_key = key.sub(/^HTTP_/, '').downcase.tr('_', '-')
+          headers[normalized_key] = value
+        end
+      end
+
+      def parse_query(query_string)
+        CGI.parse(query_string.to_s).transform_values do |values|
+          values.length == 1 ? values.first : values
+        end
+      end
+
+      def route_template(env)
+        env['debugbundle.route_template'] || env['action_dispatch.route_uri_pattern']
+      end
+
+      def rails_metadata(env)
+        parameters = env['action_dispatch.request.parameters'] || {}
+        metadata = {}
+        if env.key?('action_dispatch.request_id') || env.key?('action_dispatch.route_uri_pattern')
+          metadata[:framework] = 'rails'
+        end
+        metadata[:route_template] = route_template(env) if route_template(env)
+        metadata[:controller] = parameters['controller'] if parameters['controller']
+        metadata[:action] = parameters['action'] if parameters['action']
+        metadata
+      end
+
+      def elapsed_ms(started_at)
+        ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round
+      end
+    end
+  end
+end

data/lib/debugbundle/rack/relay_middleware.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module DebugBundle
+  module Rack
+    class RelayMiddleware
+      def initialize(app = nil, handler: DebugBundle::Relay::Handler.new)
+        @app = app
+        @handler = handler
+      end
+
+      def call(env)
+        response = @handler.handle(
+          method: env['REQUEST_METHOD'],
+          headers: relay_headers(env),
+          body: env.fetch('rack.input', StringIO.new).read,
+          ip_address: env['REMOTE_ADDR']
+        )
+
+        body = response.body ? JSON.generate(response.body) : ''
+        [response.status, { 'Content-Type' => 'application/json' }, [body]]
+      end
+
+      private
+
+      def relay_headers(env)
+        env.each_with_object({}) do |(key, value), headers|
+          next unless key.start_with?('HTTP_') || %w[CONTENT_TYPE HOST REFERER].include?(key)
+
+          normalized_key = key.sub(/^HTTP_/, '').downcase.tr('_', '-')
+          headers[normalized_key] = value
+        end
+      end
+    end
+  end
+end

data/lib/debugbundle/rails/railtie.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+if defined?(Rails::Railtie)
+  module DebugBundle
+    module Rails
+      class Railtie < ::Rails::Railtie
+        config.debugbundle = ActiveSupport::OrderedOptions.new
+
+        initializer 'debugbundle.configure' do |app|
+          options = app.config.debugbundle
+          next if options.respond_to?(:enabled) && options.enabled == false
+
+          client = DebugBundle.init(
+            project_token: options.project_token || ENV.fetch('DEBUGBUNDLE_TOKEN', nil),
+            service: options.service || app.class.module_parent_name.underscore.tr('_', '-'),
+            environment: options.environment || ::Rails.env,
+            project_mode: options.project_mode || :connected,
+            local_events_dir: options.local_events_dir || DebugBundle::Config::DEFAULT_LOCAL_EVENTS_DIR,
+            endpoint: options.endpoint || DebugBundle::Config::DEFAULT_ENDPOINT,
+            redact_fields: Array(options.redact_fields) + Array(app.config.filter_parameters)
+          )
+
+          app.middleware.use(DebugBundle::Rack::Middleware, client: client)
+          if DebugBundle::Rails.relay_route_enabled?(app)
+            app.routes.append do
+              post DebugBundle::Rails.relay_path(app), to: DebugBundle::Rails::RelayEndpoint.new(app: app)
+            end
+          end
+          DebugBundle.capture_logger(::Rails.logger) if ::Rails.logger
+          DebugBundle.capture_semantic_logger if defined?(::SemanticLogger)
+        end
+      end
+    end
+  end
+end

data/lib/debugbundle/rails/relay_endpoint.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module DebugBundle
+  module Rails
+    class RelayEndpoint
+      def initialize(app:, handler: nil)
+        @app = app
+        @handler = handler
+      end
+
+      def call(env)
+        middleware.call(env)
+      end
+
+      private
+
+      def middleware
+        @middleware ||= DebugBundle::Rack::RelayMiddleware.new(nil, handler: @handler || DebugBundle::Rails.build_relay_handler(@app))
+      end
+    end
+
+    def self.build_relay_handler(app)
+      options = relay_options(app)
+      return options.relay_handler if relay_option_present?(options, :relay_handler)
+
+      Relay::Handler.new(
+        project_mode: relay_option(options, :project_mode, :connected),
+        project_token: relay_option(options, :project_token, ENV.fetch('DEBUGBUNDLE_TOKEN', nil)),
+        endpoint: relay_option(options, :endpoint, DebugBundle::Config::DEFAULT_ENDPOINT),
+        local_events_dir: relay_option(options, :local_events_dir, DebugBundle::Config::DEFAULT_LOCAL_EVENTS_DIR),
+        spool_dir: relay_option(options, :spool_dir, DebugBundle::Config::DEFAULT_SPOOL_DIR),
+        durable_write: relay_durable_write(options),
+        service: relay_service_name(app, options),
+        environment: relay_environment_name(options),
+        allowed_origins: relay_option(options, :relay_allowed_origins, nil),
+        max_body_bytes: relay_option(options, :relay_max_body_bytes, Relay::DEFAULT_MAX_BODY_BYTES),
+        rate_limit_per_minute: relay_rate_limit(options),
+        rate_limit_store: relay_option(options, :relay_rate_limit_store, nil),
+        forward_transport: relay_option(options, :relay_forward_transport, nil)
+      )
+    end
+
+    def self.relay_route_enabled?(app)
+      options = relay_options(app)
+      relay_option(options, :relay_enabled, true) != false
+    end
+
+    def self.relay_path(app)
+      options = relay_options(app)
+      path = relay_option(options, :relay_path, '').to_s
+      path.empty? ? '/debugbundle/browser' : path
+    end
+
+    def self.relay_options(app)
+      return nil unless app.respond_to?(:config)
+      return nil unless app.config.respond_to?(:debugbundle)
+
+      app.config.debugbundle
+    end
+
+    def self.relay_durable_write(options)
+      relay_option(options, :relay_durable_write, true) != false
+    end
+
+    def self.relay_rate_limit(options)
+      relay_option(options, :relay_rate_limit_per_minute, Relay::DEFAULT_RATE_LIMIT_PER_MINUTE)
+    end
+
+    def self.relay_service_name(app, options)
+      service_name = relay_option(options, :service, nil)
+      return service_name if service_name && !service_name.to_s.empty?
+
+      if app.class.respond_to?(:module_parent_name)
+        app_name = app.class.module_parent_name.to_s
+        return app_name.underscore.tr('_', '-') unless app_name.empty?
+      end
+
+      Client::DEFAULT_SERVICE_NAME
+    end
+
+    def self.relay_environment_name(options)
+      environment_name = relay_option(options, :environment, nil)
+      return environment_name if environment_name && !environment_name.to_s.empty?
+      return ::Rails.env if defined?(::Rails)
+
+      Client::DEFAULT_ENVIRONMENT
+    end
+
+    def self.relay_option(options, name, default)
+      return default if options.nil? || !options.respond_to?(name)
+
+      value = options.public_send(name)
+      value.nil? ? default : value
+    end
+
+    def self.relay_option_present?(options, name)
+      !options.nil? && options.respond_to?(name) && !options.public_send(name).nil?
+    end
+  end
+end

data/lib/debugbundle/rails.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+begin
+  require 'rails/railtie'
+rescue LoadError
+  nil
+end
+
+require_relative 'rails/relay_endpoint'
+require_relative 'rails/railtie' if defined?(Rails::Railtie)

data/lib/debugbundle/redaction.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module DebugBundle
+  module Redaction
+    REDACTED_VALUE = '[REDACTED]'
+    CIRCULAR_VALUE = '[Circular]'
+    TRUNCATED_DEPTH_VALUE = '[Truncated:depth]'
+    TRUNCATED_COLLECTION_VALUE = '[Truncated:collection]'
+    DEFAULT_MAX_DEPTH = 5
+    DEFAULT_MAX_STRING_LENGTH = 1_024
+    DEFAULT_MAX_ARRAY_LENGTH = 50
+    DEFAULT_MAX_HASH_KEYS = 50
+    DEFAULT_SENSITIVE_FIELDS = %w[
+      password
+      secret
+      token
+      api_key
+      apikey
+      access_token
+      refresh_token
+      private_key
+      passwd
+      card_number
+      credit_card
+      cvv
+      cvc
+      pin
+      expiry
+      phone
+      bearer
+      session_id
+      otp
+      verification_code
+      authorization
+      cookie
+      ssn
+    ].freeze
+
+    class Redactor
+      def initialize(
+        sensitive_fields: DEFAULT_SENSITIVE_FIELDS,
+        max_depth: DEFAULT_MAX_DEPTH,
+        max_string_length: DEFAULT_MAX_STRING_LENGTH,
+        max_array_length: DEFAULT_MAX_ARRAY_LENGTH,
+        max_hash_keys: DEFAULT_MAX_HASH_KEYS
+      )
+        @sensitive_terms = sensitive_fields.map { |field| compile_sensitive_term(field) }
+        @max_depth = max_depth
+        @max_string_length = max_string_length
+        @max_array_length = max_array_length
+        @max_hash_keys = max_hash_keys
+      end
+
+      def redact_value(value)
+        sanitize(value, depth: 0, seen: {}.compare_by_identity)
+      end
+
+      private
+
+      def sanitize(value, depth:, seen:)
+        return TRUNCATED_DEPTH_VALUE if depth >= @max_depth
+
+        case value
+        when NilClass, TrueClass, FalseClass, Numeric
+          value
+        when String
+          truncate_string(value)
+        when Symbol
+          truncate_string(value.to_s)
+        when Time, DateTime
+          value.iso8601
+        when Array
+          return CIRCULAR_VALUE if circular?(value, seen)
+
+          mark_seen(value, seen)
+          value.first(@max_array_length).map { |item| sanitize(item, depth: depth + 1, seen: seen) }.tap do |items|
+            items << TRUNCATED_COLLECTION_VALUE if value.length > @max_array_length
+          end
+        when Hash
+          return CIRCULAR_VALUE if circular?(value, seen)
+
+          mark_seen(value, seen)
+          sanitize_hash(value, depth: depth + 1, seen: seen)
+        else
+          if value.respond_to?(:to_h)
+            sanitize(value.to_h, depth: depth + 1, seen: seen)
+          elsif value.respond_to?(:to_hash)
+            sanitize(value.to_hash, depth: depth + 1, seen: seen)
+          else
+            truncate_string(value.to_s)
+          end
+        end
+      end
+
+      def sanitize_hash(value, depth:, seen:)
+        value.each_with_index.with_object({}) do |((key, nested_value), index), result|
+          break result if index >= @max_hash_keys
+
+          key_string = key.to_s
+          result[key_string] =
+            sensitive_key?(key_string) ? REDACTED_VALUE : sanitize(nested_value, depth: depth, seen: seen)
+        end.tap do |result|
+          result['__truncated__'] = TRUNCATED_COLLECTION_VALUE if value.size > @max_hash_keys
+        end
+      end
+
+      def truncate_string(value)
+        return value if value.length <= @max_string_length
+
+        value[0, @max_string_length] + TRUNCATED_COLLECTION_VALUE
+      end
+
+      def sensitive_key?(key)
+        segments, joined = normalize_key(key)
+
+        @sensitive_terms.any? do |term|
+          joined == term[:joined] || contains_contiguous_segments?(segments, term[:segments])
+        end
+      end
+
+      def contains_contiguous_segments?(segments, target_segments)
+        return false if target_segments.empty? || segments.empty? || target_segments.length > segments.length
+
+        segments.each_index.any? do |index|
+          segments[index, target_segments.length] == target_segments
+        end
+      end
+
+      def normalize_key(key)
+        underscored = key.to_s.gsub(/([a-z\d])([A-Z])/, '\\1_\\2').downcase
+        segments = underscored.split(/[^a-z0-9]+/).reject(&:empty?)
+        [segments, segments.join]
+      end
+
+      def compile_sensitive_term(term)
+        segments, joined = normalize_key(term)
+        { segments: segments, joined: joined }
+      end
+
+      def circular?(value, seen)
+        seen.key?(value)
+      end
+
+      def mark_seen(value, seen)
+        seen[value] = true
+      end
+    end
+  end
+end