findbug 0.2.0

data/lib/findbug/processing/data_scrubber.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Findbug
+  module Processing
+    # DataScrubber removes sensitive data from captured events.
+    #
+    # WHY SCRUBBING IS CRITICAL
+    # =========================
+    #
+    # Error data often contains sensitive information:
+    # - User passwords (in form params)
+    # - API keys (in headers)
+    # - Credit card numbers (in payment flows)
+    # - Personal data (in user context)
+    #
+    # Even though Findbug is self-hosted, you don't want this data:
+    # 1. Stored in your database
+    # 2. Visible in the dashboard
+    # 3. In logs or backups
+    # 4. Accessible to developers who shouldn't see it
+    #
+    # SCRUBBING STRATEGY
+    # ==================
+    #
+    # We replace sensitive values with "[FILTERED]" rather than removing them.
+    # This way you can see that the field existed (helpful for debugging)
+    # without exposing the actual value.
+    #
+    # WHAT WE SCRUB
+    # =============
+    #
+    # 1. Known field names (password, api_key, etc.)
+    # 2. Credit card patterns (16 digits)
+    # 3. SSN patterns (XXX-XX-XXXX)
+    # 4. Sensitive headers (Authorization, Cookie)
+    # 5. Custom fields from configuration
+    #
+    class DataScrubber
+      FILTERED = "[FILTERED]"
+
+      # Credit card patterns (Visa, MasterCard, Amex, etc.)
+      CREDIT_CARD_PATTERN = /\b(?:\d{4}[-\s]?){3}\d{4}\b/
+
+      # SSN pattern
+      SSN_PATTERN = /\b\d{3}[-\s]?\d{2}[-\s]?\d{4}\b/
+
+      # Bearer token in text
+      BEARER_TOKEN_PATTERN = /Bearer\s+[A-Za-z0-9\-_.~+\/]+=*/i
+
+      # API key-like patterns (long alphanumeric strings)
+      API_KEY_PATTERN = /\b[A-Za-z0-9]{32,}\b/
+
+      class << self
+        # Scrub an entire event hash
+        #
+        # @param event [Hash] the event data to scrub
+        # @return [Hash] scrubbed event data
+        #
+        def scrub(event)
+          deep_scrub(event)
+        end
+
+        # Scrub a string value for patterns
+        #
+        # @param value [String] the string to scrub
+        # @return [String] scrubbed string
+        #
+        def scrub_string(value)
+          return value unless value.is_a?(String)
+
+          value = value.dup
+
+          # Scrub credit card numbers
+          value.gsub!(CREDIT_CARD_PATTERN, FILTERED)
+
+          # Scrub SSN
+          value.gsub!(SSN_PATTERN, FILTERED)
+
+          # Scrub Bearer tokens
+          value.gsub!(BEARER_TOKEN_PATTERN, "Bearer #{FILTERED}")
+
+          # Scrub potential API keys (but not in backtraces)
+          # Only scrub in certain contexts to avoid false positives
+          # value.gsub!(API_KEY_PATTERN, FILTERED)
+
+          value
+        end
+
+        private
+
+        def deep_scrub(obj, path = [])
+          case obj
+          when Hash
+            # Preserve original key type (symbol or string)
+            obj.each_with_object({}) do |(key, value), result|
+              result[key] = if sensitive_key?(key)
+                              FILTERED
+                            else
+                              deep_scrub(value, path + [key])
+                            end
+            end
+          when Array
+            obj.map.with_index { |item, i| deep_scrub(item, path + [i]) }
+          when String
+            scrub_string(obj)
+          else
+            obj
+          end
+        end
+
+        def sensitive_key?(key)
+          key_s = key.to_s.downcase
+
+          # Check against configured scrub fields
+          scrub_fields.any? do |field|
+            key_s.include?(field.downcase)
+          end
+        end
+
+        def scrub_fields
+          @scrub_fields ||= build_scrub_fields
+        end
+
+        def build_scrub_fields
+          default_fields = %w[
+            password
+            passwd
+            secret
+            token
+            api_key
+            apikey
+            access_key
+            accesskey
+            private_key
+            privatekey
+            credit_card
+            creditcard
+            card_number
+            cardnumber
+            cvv
+            cvc
+            ssn
+            social_security
+            authorization
+            auth
+            bearer
+            cookie
+            session
+            csrf
+          ]
+
+          # Merge with user-configured fields
+          (default_fields + Findbug.config.scrub_fields.map(&:to_s)).uniq
+        end
+
+        # Reset cached fields (for testing or config changes)
+        def reset!
+          @scrub_fields = nil
+        end
+      end
+    end
+  end
+end

data/lib/findbug/rails/controller_methods.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Findbug
+  module RailsExt
+    # ControllerMethods provides helper methods for Rails controllers.
+    #
+    # These methods are automatically included in all controllers via the Railtie.
+    # They let you add custom context to errors and performance data.
+    #
+    # WHY CONTROLLER HELPERS?
+    # =======================
+    #
+    # When an error occurs, you often want to know:
+    # - Which user was affected?
+    # - What were the request params?
+    # - What was the user's plan/tier?
+    # - What A/B experiment variant were they in?
+    #
+    # These helpers let you attach this context easily:
+    #
+    #   class ApplicationController < ActionController::Base
+    #     before_action :set_findbug_context
+    #
+    #     def set_findbug_context
+    #       findbug_set_user(current_user)
+    #       findbug_set_context(
+    #         plan: current_user&.plan,
+    #         experiment: session[:ab_variant]
+    #       )
+    #     end
+    #   end
+    #
+    # Then when an error occurs, all this context is captured automatically.
+    #
+    module ControllerMethods
+      extend ActiveSupport::Concern
+
+      included do
+        # Store context in a thread-local variable
+        # Thread-local means each request has its own context
+        # This is important for thread-safe operation in Puma
+        before_action :findbug_clear_context
+        after_action :findbug_clear_context
+      end
+
+      # Set the current user for error context
+      #
+      # @param user [Object] the user object (any object with id, email, etc.)
+      #
+      # @example
+      #   findbug_set_user(current_user)
+      #
+      # WHY A SEPARATE USER METHOD?
+      # ---------------------------
+      # Users are special - they're the most common context and have
+      # special handling (we extract id, email, username automatically).
+      #
+      def findbug_set_user(user)
+        return unless user
+
+        Findbug::Capture::Context.set_user(
+          id: user.try(:id),
+          email: user.try(:email),
+          username: user.try(:username) || user.try(:name)
+        )
+      end
+
+      # Set custom context data
+      #
+      # @param data [Hash] key-value pairs to attach to errors
+      #
+      # @example
+      #   findbug_set_context(
+      #     organization_id: current_org.id,
+      #     feature_flags: current_flags
+      #   )
+      #
+      def findbug_set_context(data = {})
+        Findbug::Capture::Context.merge(data)
+      end
+
+      # Add a tag (short key-value pair for filtering)
+      #
+      # @param key [String, Symbol] the tag key
+      # @param value [String] the tag value
+      #
+      # @example
+      #   findbug_tag(:environment, "production")
+      #   findbug_tag(:region, "us-east-1")
+      #
+      # Tags are optimized for filtering/grouping in the dashboard.
+      # Use context for detailed data, tags for filterable attributes.
+      #
+      def findbug_tag(key, value)
+        Findbug::Capture::Context.add_tag(key, value)
+      end
+
+      # Add a breadcrumb (for debugging what happened before the error)
+      #
+      # @param message [String] what happened
+      # @param category [String] category for grouping
+      # @param data [Hash] additional data
+      #
+      # @example
+      #   findbug_breadcrumb("User logged in", category: "auth")
+      #   findbug_breadcrumb("Loaded products", category: "query", data: { count: 50 })
+      #
+      # Breadcrumbs help you understand the sequence of events leading to an error.
+      # Think of them like a trail of breadcrumbs Hansel & Gretel left.
+      #
+      def findbug_breadcrumb(message, category: "default", data: {})
+        Findbug::Capture::Context.add_breadcrumb(
+          message: message,
+          category: category,
+          data: data,
+          timestamp: Time.now.utc.iso8601(3)
+        )
+      end
+
+      # Capture an exception manually with current context
+      #
+      # @param exception [Exception] the exception to capture
+      # @param extra [Hash] additional context for this specific error
+      #
+      # @example
+      #   begin
+      #     external_api.call
+      #   rescue ExternalAPIError => e
+      #     findbug_capture(e, api: "payment_gateway")
+      #     # handle gracefully
+      #   end
+      #
+      def findbug_capture(exception, extra = {})
+        Findbug.capture_exception(exception, extra)
+      end
+
+      private
+
+      # Clear context between requests
+      #
+      # WHY CLEAR CONTEXT?
+      # ------------------
+      # Without clearing, context from one request could leak into another.
+      # This is especially important in threaded servers like Puma where
+      # threads are reused across requests.
+      #
+      def findbug_clear_context
+        Findbug::Capture::Context.clear!
+      end
+    end
+  end
+end

data/lib/findbug/railtie.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Findbug
+  # Railtie hooks Findbug into the Rails boot process.
+  #
+  # WHAT IS A RAILTIE?
+  # ==================
+  #
+  # When Rails boots, it looks for classes that inherit from Rails::Railtie
+  # and calls their initializers in order. This is how gems integrate with Rails.
+  #
+  # Common things Railties do:
+  # - Insert middleware into the stack
+  # - Subscribe to ActiveSupport::Notifications
+  # - Add rake tasks
+  # - Configure the Rails app
+  #
+  # WHY USE A RAILTIE?
+  # ==================
+  #
+  # Instead of making users add Findbug to 5 different places:
+  #
+  #   # application.rb
+  #   config.middleware.use Findbug::Capture::Middleware
+  #
+  #   # initializer
+  #   ActiveSupport::Notifications.subscribe(...)
+  #
+  #   # routes
+  #   mount Findbug::Web::Engine => "/findbug"
+  #
+  # We do it all automatically in the Railtie. User just adds the gem
+  # and creates a config file. Zero setup!
+  #
+  # THE INITIALIZATION ORDER
+  # ========================
+  #
+  # Rails runs initializers in stages:
+  #
+  # 1. before_configuration - Before config is read
+  # 2. before_initialize - Before Rails.initialize!
+  # 3. to_prepare - Before each request (dev) or once (prod)
+  # 4. after_initialize - After Rails is fully loaded
+  #
+  # We use after_initialize because we need:
+  # - Rails.env to be set
+  # - Database connections to exist
+  # - All models to be loaded
+  #
+  class Railtie < Rails::Railtie
+    # Register our middleware to catch exceptions
+    #
+    # MIDDLEWARE ORDER MATTERS!
+    # -------------------------
+    #
+    # We insert AFTER ActionDispatch::ShowExceptions because:
+    # 1. ShowExceptions converts exceptions to HTTP responses
+    # 2. We want to capture the raw exception BEFORE that happens
+    # 3. We also want to capture exceptions that ShowExceptions misses
+    #
+    # Stack (simplified):
+    #   Rails::Rack::Logger
+    #   ActionDispatch::RequestId
+    #   ActionDispatch::ShowExceptions  ← Converts exceptions to 500 pages
+    #   Findbug::Capture::Middleware    ← WE GO HERE (sees raw exceptions)
+    #   ActionDispatch::Routing
+    #   YourController#action
+    #
+    initializer "findbug.middleware" do
+      require_relative "capture/middleware"
+
+      Rails.application.config.middleware.use(Findbug::Capture::Middleware)
+    end
+
+    # Set up Rails error reporting integration (Rails 7+)
+    #
+    # Rails 7 introduced ErrorReporter for centralized error handling.
+    # We subscribe to it so we capture ALL errors, even those handled
+    # gracefully by the app.
+    #
+    initializer "findbug.error_reporter" do |app|
+      require_relative "capture/exception_subscriber"
+
+      app.config.after_initialize do
+        if defined?(Rails.error) && Rails.error.respond_to?(:subscribe)
+          Rails.error.subscribe(Findbug::Capture::ExceptionSubscriber.new)
+        end
+      end
+    end
+
+    # Set up performance instrumentation
+    #
+    # Rails uses ActiveSupport::Notifications for internal events:
+    # - sql.active_record (database queries)
+    # - process_action.action_controller (requests)
+    # - render_template.action_view (view rendering)
+    #
+    # We subscribe to these to capture performance data.
+    #
+    initializer "findbug.instrumentation" do |app|
+      app.config.after_initialize do
+        next unless Findbug.config.performance_enabled
+
+        require_relative "performance/instrumentation"
+        Findbug::Performance::Instrumentation.setup!
+      end
+    end
+
+    # Mount the web dashboard engine
+    #
+    # This adds routes for the /findbug dashboard.
+    # We only mount if authentication is configured (security!).
+    #
+    initializer "findbug.routes" do |app|
+      app.config.after_initialize do
+        next unless Findbug.config.web_enabled?
+
+        require_relative "engine"
+
+        # Add routes programmatically
+        # This is equivalent to `mount Findbug::Engine => "/findbug"` in routes.rb
+        # but automatic!
+        app.routes.append do
+          mount Findbug::Engine => Findbug.config.web_path
+        end
+      end
+    end
+
+    # Set up default configuration values that depend on Rails
+    #
+    initializer "findbug.defaults" do |app|
+      app.config.after_initialize do
+        config = Findbug.config
+
+        # Use Rails.env if environment not explicitly set
+        config.environment ||= Rails.env
+
+        # Disable in test environment by default
+        if Rails.env.test? && config.enabled
+          Findbug.logger.debug(
+            "[Findbug] Running in test environment. Set `config.enabled = true` to enable."
+          )
+          # Note: We don't force disable here. User might want it enabled for integration tests.
+        end
+
+        # Try to auto-detect release from common sources
+        config.release ||= detect_release
+      end
+    end
+
+    # Add Findbug helpers to ActionController
+    #
+    # This adds methods like `findbug_context` that controllers can use
+    # to add custom context to errors.
+    #
+    initializer "findbug.controller_methods" do
+      ActiveSupport.on_load(:action_controller) do
+        require_relative "rails/controller_methods"
+        include Findbug::RailsExt::ControllerMethods
+      end
+    end
+
+    # Start background persister
+    #
+    # This runs a thread that periodically moves events from Redis to the database.
+    # Users don't need to set up Sidekiq or any job system - it works out of the box.
+    #
+    initializer "findbug.background_persister" do |app|
+      app.config.after_initialize do
+        next unless Findbug.enabled?
+        next unless Findbug.config.auto_persist
+
+        require_relative "background_persister"
+        Findbug::BackgroundPersister.start!(
+          interval: Findbug.config.persist_interval
+        )
+      end
+    end
+
+    # Register cleanup for application shutdown
+    #
+    # When the app shuts down (e.g., during deploys), we want to:
+    # 1. Stop the background persister thread
+    # 2. Flush any pending events
+    # 3. Close Redis connections cleanly
+    #
+    initializer "findbug.shutdown" do |app|
+      at_exit do
+        Findbug::BackgroundPersister.stop! if defined?(Findbug::BackgroundPersister)
+        Findbug::Storage::ConnectionPool.shutdown! if defined?(Findbug::Storage::ConnectionPool)
+      end
+    end
+
+    # Add rake tasks
+    rake_tasks do
+      load File.expand_path("tasks/findbug.rake", __dir__)
+    end
+
+    private
+
+    # Try to detect the release/version from environment
+    def detect_release
+      # Common environment variables for release tracking
+      ENV["FINDBUG_RELEASE"] ||
+        ENV["HEROKU_SLUG_COMMIT"] ||
+        ENV["RENDER_GIT_COMMIT"] ||
+        ENV["GIT_COMMIT"] ||
+        ENV["SOURCE_VERSION"] ||
+        git_sha
+    end
+
+    # Get current git SHA (if in a git repo)
+    def git_sha
+      sha = `git rev-parse --short HEAD 2>/dev/null`.strip
+      sha.empty? ? nil : sha
+    rescue StandardError
+      nil
+    end
+  end
+end