findbug 0.2.0

data/lib/findbug/alerts/dispatcher.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Findbug
+  module Alerts
+    # Dispatcher routes alerts to configured channels.
+    #
+    # ALERT FLOW
+    # ==========
+    #
+    # 1. Error captured → PersistJob runs
+    # 2. PersistJob calls Dispatcher.notify(error_event)
+    # 3. Dispatcher checks throttling (avoid spam)
+    # 4. Dispatcher sends to enabled channels (async via AlertJob)
+    #
+    # THROTTLING
+    # ==========
+    #
+    # If your app throws 1000 errors in a minute, you don't want 1000 Slack
+    # messages. Throttling limits alerts to one per error fingerprint per
+    # throttle period (default 5 minutes).
+    #
+    # CHANNEL PRIORITY
+    # ================
+    #
+    # Different channels for different severities:
+    # - Critical errors → All channels (email, Slack, etc.)
+    # - Warnings → Maybe just Slack
+    # - Info → Maybe just logged, no alerts
+    #
+    class Dispatcher
+      class << self
+        # Send alert for an error event
+        #
+        # @param error_event [ErrorEvent] the error to alert about
+        # @param async [Boolean] whether to send asynchronously (default: true)
+        #
+        def notify(error_event, async: true)
+          return unless Findbug.enabled?
+          return unless Findbug.config.alerts.any_enabled?
+          return unless should_alert?(error_event)
+          return if throttled?(error_event)
+
+          if async
+            Jobs::AlertJob.perform_later(error_event.id)
+          else
+            send_alerts(error_event)
+          end
+
+          record_alert(error_event)
+        end
+
+        # Actually send alerts to all enabled channels
+        #
+        # @param error_event [ErrorEvent] the error to alert about
+        #
+        def send_alerts(error_event)
+          alert_config = Findbug.config.alerts
+
+          alert_config.enabled_channels.each do |channel_name, config|
+            send_to_channel(channel_name, error_event, config)
+          rescue StandardError => e
+            Findbug.logger.error(
+              "[Findbug] Failed to send alert to #{channel_name}: #{e.message}"
+            )
+          end
+        end
+
+        private
+
+        # Check if we should alert for this error
+        #
+        # You might not want to alert for:
+        # - Ignored errors
+        # - Info-level messages
+        # - Handled errors (depending on config)
+        #
+        def should_alert?(error_event)
+          # Don't alert for ignored errors
+          return false if error_event.status == ErrorEvent::STATUS_IGNORED
+
+          # Alert for errors and warnings, not info
+          %w[error warning].include?(error_event.severity)
+        end
+
+        # Check if this error is throttled
+        #
+        # We use Redis to track last alert time per fingerprint.
+        #
+        def throttled?(error_event)
+          Throttler.throttled?(error_event.fingerprint)
+        end
+
+        # Record that we sent an alert (for throttling)
+        def record_alert(error_event)
+          Throttler.record(error_event.fingerprint)
+        end
+
+        # Send to a specific channel
+        def send_to_channel(channel_name, error_event, config)
+          channel_class = channel_for(channel_name)
+          return unless channel_class
+
+          channel = channel_class.new(config)
+          channel.send_alert(error_event)
+        end
+
+        # Get the channel class for a channel name
+        def channel_for(channel_name)
+          case channel_name.to_sym
+          when :email
+            Channels::Email
+          when :slack
+            Channels::Slack
+          when :discord
+            Channels::Discord
+          when :webhook
+            Channels::Webhook
+          else
+            Findbug.logger.warn("[Findbug] Unknown alert channel: #{channel_name}")
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/findbug/alerts/throttler.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Findbug
+  module Alerts
+    # Throttler prevents alert spam by limiting how often we alert for the same error.
+    #
+    # THE PROBLEM
+    # ===========
+    #
+    # Without throttling:
+    # - 1000 users hit the same bug
+    # - 1000 Slack messages
+    # - Your team mutes the channel
+    # - You miss the NEXT important error
+    #
+    # With throttling:
+    # - First occurrence: Alert sent
+    # - Next 999 in 5 minutes: Throttled
+    # - 5 minutes later, if still happening: Another alert
+    #
+    # IMPLEMENTATION
+    # ==============
+    #
+    # We use Redis to store "last alerted at" timestamps:
+    #
+    #   Key: findbug:alert:throttle:{fingerprint}
+    #   Value: ISO8601 timestamp
+    #   TTL: throttle_period
+    #
+    # If the key exists and isn't expired, we're throttled.
+    # Simple and fast.
+    #
+    class Throttler
+      THROTTLE_KEY_PREFIX = "findbug:alert:throttle:"
+
+      class << self
+        # Check if an alert is currently throttled
+        #
+        # @param fingerprint [String] error fingerprint
+        # @return [Boolean] true if throttled
+        #
+        def throttled?(fingerprint)
+          key = throttle_key(fingerprint)
+
+          Storage::ConnectionPool.with do |redis|
+            redis.exists?(key)
+          end
+        rescue StandardError => e
+          Findbug.logger.debug("[Findbug] Throttle check failed: #{e.message}")
+          false # If we can't check, allow the alert
+        end
+
+        # Record that we sent an alert (starts throttle period)
+        #
+        # @param fingerprint [String] error fingerprint
+        #
+        def record(fingerprint)
+          key = throttle_key(fingerprint)
+          ttl = throttle_period
+
+          Storage::ConnectionPool.with do |redis|
+            redis.setex(key, ttl, Time.now.utc.iso8601)
+          end
+        rescue StandardError => e
+          Findbug.logger.debug("[Findbug] Throttle record failed: #{e.message}")
+        end
+
+        # Clear throttle for a specific error (e.g., when error is resolved)
+        #
+        # @param fingerprint [String] error fingerprint
+        #
+        def clear(fingerprint)
+          key = throttle_key(fingerprint)
+
+          Storage::ConnectionPool.with do |redis|
+            redis.del(key)
+          end
+        rescue StandardError
+          # Ignore errors during cleanup
+        end
+
+        # Get remaining throttle time
+        #
+        # @param fingerprint [String] error fingerprint
+        # @return [Integer, nil] seconds remaining, or nil if not throttled
+        #
+        def remaining_seconds(fingerprint)
+          key = throttle_key(fingerprint)
+
+          Storage::ConnectionPool.with do |redis|
+            ttl = redis.ttl(key)
+            ttl.positive? ? ttl : nil
+          end
+        rescue StandardError
+          nil
+        end
+
+        private
+
+        def throttle_key(fingerprint)
+          "#{THROTTLE_KEY_PREFIX}#{fingerprint}"
+        end
+
+        def throttle_period
+          Findbug.config.alerts.throttle_period
+        end
+      end
+    end
+  end
+end

data/lib/findbug/background_persister.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Findbug
+  # BackgroundPersister runs a background thread that periodically moves
+  # events from the Redis buffer to the database.
+  #
+  # WHY A BACKGROUND THREAD?
+  # ========================
+  #
+  # We want Findbug to work "out of the box" without requiring users to:
+  # 1. Set up Sidekiq/ActiveJob
+  # 2. Configure recurring jobs
+  # 3. Run separate worker processes
+  #
+  # A background thread achieves this by running inside the Rails process.
+  #
+  # THREAD SAFETY
+  # =============
+  #
+  # - Uses Mutex for start/stop synchronization
+  # - Only one persister thread runs at a time
+  # - Safe to call start! multiple times (idempotent)
+  #
+  # GRACEFUL SHUTDOWN
+  # =================
+  #
+  # The thread checks a @running flag and exits cleanly when stopped.
+  # We also register an at_exit hook to ensure cleanup.
+  #
+  # LIMITATIONS
+  # ===========
+  #
+  # - Only persists in the process where it's started
+  # - In multi-process setups (Puma cluster), each process has its own thread
+  # - For high-volume apps, users should use the ActiveJob approach instead
+  #
+  class BackgroundPersister
+    DEFAULT_INTERVAL = 30 # seconds
+
+    class << self
+      def start!(interval: nil)
+        return if @running
+
+        @mutex ||= Mutex.new
+        @mutex.synchronize do
+          return if @running
+
+          @interval = interval || Findbug.config.persist_interval || DEFAULT_INTERVAL
+          @running = true
+          @thread = Thread.new { run_loop }
+          @thread.name = "findbug-persister"
+          @thread.abort_on_exception = false
+
+          Findbug.logger.info("[Findbug] Background persister started (interval: #{@interval}s)")
+        end
+      end
+
+      def stop!
+        return unless @running
+
+        @mutex.synchronize do
+          @running = false
+          @thread&.wakeup rescue nil # Wake from sleep
+          @thread&.join(5) # Wait up to 5 seconds
+          @thread = nil
+          Findbug.logger.info("[Findbug] Background persister stopped")
+        end
+      end
+
+      def running?
+        @running == true && @thread&.alive?
+      end
+
+      # Force an immediate persist (useful for testing)
+      def persist_now!
+        perform_persist
+      end
+
+      private
+
+      def run_loop
+        while @running
+          sleep(@interval)
+          next unless @running
+
+          perform_persist
+        end
+      rescue StandardError => e
+        Findbug.logger.error("[Findbug] Background persister crashed: #{e.message}")
+        @running = false
+      end
+
+      def perform_persist
+        return unless Findbug.enabled?
+
+        # Persist errors
+        persist_errors
+
+        # Persist performance events
+        persist_performance
+      rescue StandardError => e
+        Findbug.logger.error("[Findbug] Persist failed: #{e.message}")
+      end
+
+      def persist_errors
+        events = Findbug::Storage::RedisBuffer.pop_errors(batch_size)
+        return if events.empty?
+
+        persisted = 0
+        events.each do |event_data|
+          scrubbed = Findbug::Processing::DataScrubber.scrub(event_data)
+          Findbug::ErrorEvent.upsert_from_event(scrubbed)
+          persisted += 1
+        rescue StandardError => e
+          Findbug.logger.error("[Findbug] Failed to persist error: #{e.message}")
+        end
+
+        Findbug.logger.info("[Findbug] Persisted #{persisted}/#{events.size} errors") if persisted > 0
+      end
+
+      def persist_performance
+        events = Findbug::Storage::RedisBuffer.pop_performance(batch_size)
+        return if events.empty?
+
+        persisted = 0
+        events.each do |event_data|
+          scrubbed = Findbug::Processing::DataScrubber.scrub(event_data)
+          Findbug::PerformanceEvent.create_from_event(scrubbed)
+          persisted += 1
+        rescue StandardError => e
+          Findbug.logger.error("[Findbug] Failed to persist performance event: #{e.message}")
+        end
+
+        Findbug.logger.info("[Findbug] Persisted #{persisted}/#{events.size} performance events") if persisted > 0
+      end
+
+      def batch_size
+        Findbug.config.persist_batch_size || 100
+      end
+    end
+  end
+end

data/lib/findbug/capture/context.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+module Findbug
+  module Capture
+    # Context stores request-scoped data that gets attached to errors.
+    #
+    # THREAD-LOCAL STORAGE
+    # ====================
+    #
+    # In a multi-threaded server like Puma, multiple requests run concurrently.
+    # Each request needs its OWN context - we can't share a global variable
+    # or Request A's user would appear on Request B's errors!
+    #
+    # Solution: Thread.current[:key] - a hash specific to each thread.
+    #
+    #   Thread 1 (Request A):
+    #     Context.set_user(id: 1)
+    #     # Thread.current[:findbug_context] = { user: { id: 1 } }
+    #
+    #   Thread 2 (Request B):
+    #     Context.set_user(id: 2)
+    #     # Thread.current[:findbug_context] = { user: { id: 2 } }
+    #
+    #   Thread 1: Context.current[:user] → { id: 1 }  ✓ Correct!
+    #   Thread 2: Context.current[:user] → { id: 2 }  ✓ Correct!
+    #
+    # WHAT GETS STORED?
+    # =================
+    #
+    # 1. User - who was affected
+    # 2. Tags - short key-value pairs for filtering
+    # 3. Extra - arbitrary data about the request
+    # 4. Breadcrumbs - trail of events before the error
+    # 5. Request - HTTP request details (auto-captured)
+    #
+    class Context
+      THREAD_KEY = :findbug_context
+      MAX_BREADCRUMBS = 50
+
+      class << self
+        # Get the current context hash
+        #
+        # @return [Hash] the current thread's context
+        #
+        def current
+          Thread.current[THREAD_KEY] ||= default_context
+        end
+
+        # Clear the context (call between requests)
+        #
+        # This MUST be called after each request to prevent context leaking.
+        # The Railtie sets this up via after_action.
+        #
+        def clear!
+          Thread.current[THREAD_KEY] = nil
+        end
+
+        # Set user information
+        #
+        # @param user_data [Hash] user attributes (id, email, username, etc.)
+        #
+        # @example
+        #   Context.set_user(id: 123, email: "user@example.com")
+        #
+        def set_user(user_data)
+          current[:user] = scrub_user_data(user_data)
+        end
+
+        # Get current user
+        #
+        # @return [Hash, nil] the current user data
+        #
+        def user
+          current[:user]
+        end
+
+        # Add a tag
+        #
+        # Tags are short key-value pairs optimized for filtering.
+        # Unlike extra data, tags are indexed and searchable.
+        #
+        # @param key [String, Symbol] tag name
+        # @param value [String, Numeric, Boolean] tag value
+        #
+        # @example
+        #   Context.add_tag(:environment, "production")
+        #   Context.add_tag(:plan, "enterprise")
+        #
+        def add_tag(key, value)
+          current[:tags][key.to_sym] = value
+        end
+
+        # Get all tags
+        #
+        # @return [Hash] current tags
+        #
+        def tags
+          current[:tags]
+        end
+
+        # Merge extra data into context
+        #
+        # Extra data is arbitrary key-value pairs that provide more detail.
+        # Use this for non-indexed, detailed information.
+        #
+        # @param data [Hash] data to merge
+        #
+        # @example
+        #   Context.merge(order_id: 456, cart_size: 3)
+        #
+        def merge(data)
+          current[:extra].merge!(data)
+        end
+
+        # Get extra data
+        #
+        # @return [Hash] current extra data
+        #
+        def extra
+          current[:extra]
+        end
+
+        # Add a breadcrumb
+        #
+        # Breadcrumbs are a chronological trail of events leading to an error.
+        # Think of them like a log, but attached to the error.
+        #
+        # @param breadcrumb [Hash] breadcrumb data
+        # @option breadcrumb [String] :message what happened
+        # @option breadcrumb [String] :category grouping category
+        # @option breadcrumb [Hash] :data additional data
+        # @option breadcrumb [String] :timestamp when it happened
+        #
+        # @example
+        #   Context.add_breadcrumb(
+        #     message: "User clicked checkout",
+        #     category: "ui",
+        #     data: { button: "checkout_btn" }
+        #   )
+        #
+        def add_breadcrumb(breadcrumb)
+          crumbs = current[:breadcrumbs]
+
+          # Add timestamp if not provided
+          breadcrumb[:timestamp] ||= Time.now.utc.iso8601(3)
+
+          crumbs << breadcrumb
+
+          # Keep only the most recent breadcrumbs
+          # This prevents memory issues from long-running requests
+          crumbs.shift while crumbs.size > MAX_BREADCRUMBS
+        end
+
+        # Get all breadcrumbs
+        #
+        # @return [Array<Hash>] breadcrumbs in chronological order
+        #
+        def breadcrumbs
+          current[:breadcrumbs]
+        end
+
+        # Set request data (auto-populated by middleware)
+        #
+        # @param request_data [Hash] HTTP request information
+        #
+        def set_request(request_data)
+          current[:request] = request_data
+        end
+
+        # Get request data
+        #
+        # @return [Hash] HTTP request information
+        #
+        def request
+          current[:request]
+        end
+
+        # Get the complete context for capturing
+        #
+        # This returns all context data in a format ready for storage.
+        #
+        # @return [Hash] complete context
+        #
+        def to_h
+          ctx = current.dup
+          ctx.compact! # Remove nil values
+
+          # Convert breadcrumbs to array (it's already an array, but be explicit)
+          ctx[:breadcrumbs] = ctx[:breadcrumbs].dup if ctx[:breadcrumbs]
+
+          ctx
+        end
+
+        # Create context from a Rack request
+        #
+        # This extracts useful information from the HTTP request.
+        # Called automatically by the middleware.
+        #
+        # @param rack_request [Rack::Request] the Rack request object
+        # @return [Hash] extracted request data
+        #
+        def from_rack_request(rack_request)
+          {
+            method: rack_request.request_method,
+            url: rack_request.url,
+            path: rack_request.path,
+            query_string: scrub_query_string(rack_request.query_string),
+            headers: scrub_headers(extract_headers(rack_request)),
+            ip: rack_request.ip,
+            user_agent: rack_request.user_agent,
+            content_type: rack_request.content_type,
+            content_length: rack_request.content_length,
+            request_id: rack_request.env["action_dispatch.request_id"]
+          }
+        end
+
+        private
+
+        def default_context
+          {
+            user: nil,
+            tags: {},
+            extra: {},
+            breadcrumbs: [],
+            request: nil
+          }
+        end
+
+        # Scrub sensitive data from user info
+        def scrub_user_data(user_data)
+          return nil unless user_data
+
+          scrubbed = user_data.dup
+
+          # Never store password-related fields
+          Findbug.config.scrub_fields.each do |field|
+            scrubbed.delete(field.to_sym)
+            scrubbed.delete(field.to_s)
+          end
+
+          scrubbed
+        end
+
+        # Extract headers from Rack request
+        def extract_headers(rack_request)
+          headers = {}
+
+          rack_request.each_header do |key, value|
+            # HTTP headers in Rack are prefixed with HTTP_
+            next unless key.start_with?("HTTP_")
+
+            # Convert HTTP_X_FORWARDED_FOR to X-Forwarded-For
+            header_name = key.sub(/^HTTP_/, "").split("_").map(&:capitalize).join("-")
+            headers[header_name] = value
+          end
+
+          # Add Content-Type and Content-Length (not prefixed with HTTP_)
+          headers["Content-Type"] = rack_request.content_type if rack_request.content_type
+          headers["Content-Length"] = rack_request.content_length.to_s if rack_request.content_length
+
+          headers
+        end
+
+        # Scrub sensitive headers
+        def scrub_headers(headers)
+          return {} unless Findbug.config.scrub_headers
+
+          sensitive_headers = %w[
+            Authorization
+            Cookie
+            X-Api-Key
+            X-Auth-Token
+            X-Access-Token
+          ] + Findbug.config.scrub_header_names
+
+          headers.transform_values.with_index do |value, _|
+            key = headers.keys[headers.values.index(value)]
+            if sensitive_headers.any? { |h| key.casecmp?(h) }
+              "[FILTERED]"
+            else
+              value
+            end
+          end
+        end
+
+        # Scrub sensitive query parameters
+        def scrub_query_string(query_string)
+          return nil if query_string.nil? || query_string.empty?
+
+          params = Rack::Utils.parse_query(query_string)
+
+          Findbug.config.scrub_fields.each do |field|
+            params[field] = "[FILTERED]" if params.key?(field)
+          end
+
+          Rack::Utils.build_query(params)
+        end
+      end
+    end
+  end
+end