rails_error_dashboard 0.3.1 → 0.4.0

data/lib/rails_error_dashboard/services/crash_capture.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require "json"
+require "tmpdir"
+require "timeout"
+
+module RailsErrorDashboard
+  module Services
+    # Last-resort crash capture via Ruby's `at_exit` hook.
+    #
+    # When the Rails process dies from an unhandled exception, the error never
+    # reaches the error subscriber or middleware. This service registers an
+    # `at_exit` hook that captures `$!` (the fatal exception) and writes it to
+    # disk as JSON. On the next boot, `import!` reads crash files and creates
+    # ErrorLog records with severity "fatal".
+    #
+    # Safety contract:
+    # - Default OFF (opt-in via config.enable_crash_capture)
+    # - Writes to tmpfile, NOT the database (connection pool may be closed)
+    # - Timeout: 1 second max for file write, then give up
+    # - Skips clean exits (SystemExit.success?, SignalException)
+    # - Every operation wrapped in rescue (crash capture must never itself crash)
+    # - Zero runtime overhead — hook only fires during process shutdown
+    class CrashCapture
+      FILE_PREFIX = "red_crash_"
+
+      class << self
+        # Enable crash capture. Registers the `at_exit` hook and records boot time.
+        # @return [true]
+        def enable!
+          return true if enabled?
+
+          @boot_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          @enabled = true
+
+          at_exit { capture!($!) }
+
+          true
+        end
+
+        # Disable crash capture. The `at_exit` hook remains registered but will
+        # no-op because `@enabled` is false.
+        def disable!
+          @enabled = false
+        end
+
+        # @return [Boolean] whether crash capture is enabled
+        def enabled?
+          @enabled == true
+        end
+
+        # Capture a fatal exception to disk. Called from the `at_exit` hook.
+        # @param exception [Exception, nil] the fatal exception ($!)
+        def capture!(exception)
+          return unless @enabled
+          return unless exception
+          return if exception.is_a?(SystemExit) && exception.success?
+          return if exception.is_a?(SignalException)
+
+          crash_data = build_crash_data(exception)
+          path = crash_file_path
+
+          Timeout.timeout(1) do
+            FileUtils.mkdir_p(File.dirname(path))
+            File.write(path, JSON.generate(crash_data))
+          end
+        rescue => e
+          # Crash capture must NEVER itself crash the exit.
+          # Best-effort stderr warning (may not be visible).
+          $stderr.puts "[RailsErrorDashboard] CrashCapture.capture! failed: #{e.class} - #{e.message}" rescue nil
+        end
+
+        # Import crash files from disk into the database. Called during boot
+        # (config.after_initialize) BEFORE enable! so old crashes are processed first.
+        def import!
+          dir = crash_capture_dir
+          return unless Dir.exist?(dir)
+
+          pattern = File.join(dir, "#{FILE_PREFIX}*.json")
+          Dir.glob(pattern).each do |file|
+            import_crash_file(file)
+          end
+        rescue => e
+          RailsErrorDashboard::Logger.debug(
+            "[RailsErrorDashboard] CrashCapture.import! failed: #{e.class} - #{e.message}"
+          )
+        end
+
+        # Reset internal state (for testing)
+        def reset!
+          @enabled = false
+          @boot_time = nil
+        end
+
+        private
+
+        def build_crash_data(exception)
+          data = {
+            exception_class: exception.class.name,
+            message: exception.message.to_s[0, 10_000],
+            backtrace: exception.backtrace&.first(50),
+            timestamp: Time.now.utc.iso8601,
+            pid: Process.pid,
+            ruby_version: RUBY_VERSION,
+            thread_count: Thread.list.count
+          }
+
+          # Rails version (may not be available during crash)
+          data[:rails_version] = Rails.version if defined?(Rails) && Rails.respond_to?(:version)
+
+          # Uptime
+          if @boot_time
+            data[:uptime_seconds] = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - @boot_time).round(1)
+          end
+
+          # GC stats (safe, read-only, <1ms)
+          data[:gc] = GC.stat rescue nil
+
+          # Cause chain (up to 5 causes)
+          data[:cause_chain] = extract_cause_chain(exception)
+
+          data
+        end
+
+        def extract_cause_chain(exception)
+          causes = []
+          current = exception.cause
+          5.times do
+            break unless current
+            causes << {
+              exception_class: current.class.name,
+              message: current.message.to_s[0, 2_000]
+            }
+            current = current.cause
+          end
+          causes
+        end
+
+        def crash_file_path
+          File.join(crash_capture_dir, "#{FILE_PREFIX}#{Process.pid}.json")
+        end
+
+        def crash_capture_dir
+          RailsErrorDashboard.configuration.crash_capture_path || Dir.tmpdir
+        end
+
+        def import_crash_file(file)
+          raw = File.read(file)
+          data = JSON.parse(raw)
+
+          # Build attributes for ErrorLog
+          backtrace = data["backtrace"]
+          backtrace_text = backtrace.is_a?(Array) ? backtrace.join("\n") : backtrace.to_s
+
+          cause_chain = data["cause_chain"]
+          cause_json = cause_chain.is_a?(Array) && cause_chain.any? ? cause_chain.to_json : nil
+
+          # Build environment_info from crash metadata
+          env_info = {
+            ruby_version: data["ruby_version"],
+            rails_version: data["rails_version"],
+            pid: data["pid"],
+            thread_count: data["thread_count"],
+            uptime_seconds: data["uptime_seconds"],
+            gc: data["gc"],
+            crash_captured_at: data["timestamp"],
+            source: "crash_capture"
+          }.compact
+
+          # Resolve application (same as LogError does)
+          app_name = RailsErrorDashboard.configuration.application_name ||
+                     (defined?(Rails) && Rails.application ? Rails.application.class.module_parent_name : "Unknown")
+          application = Commands::FindOrCreateApplication.call(app_name)
+
+          occurred_at = parse_timestamp(data["timestamp"])
+
+          attributes = {
+            application_id: application.id,
+            error_type: data["exception_class"] || "UnknownCrash",
+            message: data["message"] || "Process crash captured via at_exit hook",
+            backtrace: backtrace_text,
+            occurred_at: occurred_at,
+            platform: "crash_capture",
+            resolved: false
+          }
+
+          # Add optional columns if they exist on the model
+          if ErrorLog.column_names.include?("environment_info")
+            attributes[:environment_info] = env_info.to_json
+          end
+
+          if ErrorLog.column_names.include?("exception_cause") && cause_json
+            attributes[:exception_cause] = cause_json
+          end
+
+          if ErrorLog.column_names.include?("error_hash")
+            attributes[:error_hash] = Services::ErrorHashGenerator.from_attributes(
+              error_type: attributes[:error_type],
+              message: attributes[:message],
+              backtrace: backtrace_text,
+              application_id: application.id
+            )
+          end
+
+          if ErrorLog.column_names.include?("first_seen_at")
+            attributes[:first_seen_at] = occurred_at
+          end
+
+          if ErrorLog.column_names.include?("last_seen_at")
+            attributes[:last_seen_at] = occurred_at
+          end
+
+          ErrorLog.create!(attributes)
+
+          # Delete file after successful import
+          File.delete(file)
+        rescue => e
+          RailsErrorDashboard::Logger.debug(
+            "[RailsErrorDashboard] CrashCapture.import_crash_file failed for #{file}: #{e.class} - #{e.message}"
+          )
+          # Rename to .failed to prevent infinite reimport while preserving data for debugging
+          File.rename(file, "#{file}.failed") rescue nil
+        end
+
+        def parse_timestamp(ts)
+          return Time.current unless ts
+          Time.parse(ts).utc
+        rescue
+          Time.current
+        end
+      end
+    end
+  end
+end

data/lib/rails_error_dashboard/services/diagnostic_dump_generator.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module RailsErrorDashboard
+  module Services
+    # Pure algorithm: Capture on-demand diagnostic snapshot of current system state
+    #
+    # Aggregates data from existing services (zero duplication):
+    # - SystemHealthSnapshot: GC, memory, threads, connection pool, Puma, job queue
+    # - EnvironmentSnapshot: Ruby/Rails versions, gems, server, DB adapter
+    # - BreadcrumbCollector: Current thread's breadcrumb buffer (non-destructive)
+    #
+    # Additional data unique to diagnostic dumps:
+    # - Per-thread info (name, status, alive)
+    # - Full GC.stat (SystemHealthSnapshot only captures a subset)
+    # - ObjectSpace.count_objects (O(1) type counts — NOT each_object)
+    # - Process uptime
+    #
+    # SAFETY RULES (HOST_APP_SAFETY.md):
+    # - Every section individually wrapped in rescue => nil
+    # - Never raises — returns partial dump on error
+    # - No ObjectSpace.each_object (banned rule #8)
+    # - No Thread.list.map(&:backtrace) (GVL hold)
+    # - No Signal.trap (banned rule #9)
+    class DiagnosticDumpGenerator
+      def self.call
+        new.call
+      end
+
+      def call
+        {
+          captured_at: Time.current.iso8601,
+          pid: Process.pid,
+          uptime_seconds: process_uptime,
+          environment: environment_info,
+          system_health: system_health,
+          breadcrumbs: breadcrumbs,
+          threads: thread_info,
+          gc: gc_info,
+          object_counts: object_counts
+        }
+      rescue => e
+        { captured_at: Time.current.iso8601, error: e.message }
+      end
+
+      private
+
+      def process_uptime
+        Process.clock_gettime(Process::CLOCK_MONOTONIC) - PROCESS_START_TIME
+      rescue => e
+        nil
+      end
+
+      def environment_info
+        EnvironmentSnapshot.snapshot.dup
+      rescue => e
+        nil
+      end
+
+      def system_health
+        SystemHealthSnapshot.capture
+      rescue => e
+        nil
+      end
+
+      def breadcrumbs
+        return [] unless RailsErrorDashboard.configuration.enable_breadcrumbs
+        BreadcrumbCollector.current_breadcrumbs
+      rescue => e
+        []
+      end
+
+      def thread_info
+        Thread.list.map do |t|
+          { name: t.name, status: t.status, alive: t.alive? }
+        rescue => e
+          { name: nil, status: "unknown", alive: false }
+        end
+      rescue => e
+        nil
+      end
+
+      def gc_info
+        GC.stat
+      rescue => e
+        nil
+      end
+
+      def object_counts
+        ObjectSpace.count_objects
+      rescue => e
+        nil
+      end
+
+      PROCESS_START_TIME = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      private_constant :PROCESS_START_TIME
+    end
+  end
+end

data/lib/rails_error_dashboard/services/local_variable_capturer.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module RailsErrorDashboard
+  module Services
+    # TracePoint lifecycle manager for capturing local variables and instance
+    # variables at raise time.
+    #
+    # Uses TracePoint(:raise) which only fires when exceptions are raised (rare
+    # in normal request flow). Sentry ships this in production (proven safe).
+    #
+    # Safety contract:
+    # - Default OFF (opt-in via config.enable_local_variables / enable_instance_variables)
+    # - Never stores Binding objects or object references — extracts vars immediately in callback
+    # - Every callback wrapped in rescue => e (never raises)
+    # - Per-variable rescue in extraction
+    # - Skips SystemExit, SignalException, Interrupt
+    # - Skips non-app-code paths (gems, vendor, stdlib, this gem)
+    # - Re-raise guard: skips if exception already has @_red_locals / @_red_instance_vars
+    class LocalVariableCapturer
+      # Instance variable names used to attach captured data to the exception
+      LOCALS_IVAR = :@_red_locals
+      INSTANCE_VARS_IVAR = :@_red_instance_vars
+
+      class << self
+        # Enable the TracePoint(:raise) hook globally
+        def enable!
+          return if enabled?
+
+          @tracepoint = TracePoint.new(:raise) do |tp|
+            on_raise(tp)
+          rescue => e
+            # CRITICAL: never let the callback crash the app
+            RailsErrorDashboard::Logger.debug(
+              "[RailsErrorDashboard] LocalVariableCapturer callback error: #{e.class} - #{e.message}"
+            )
+          end
+
+          @tracepoint.enable
+        end
+
+        # Disable the TracePoint hook
+        def disable!
+          @tracepoint&.disable
+          @tracepoint = nil
+        end
+
+        # Check if currently enabled
+        def enabled?
+          @tracepoint&.enabled? == true
+        end
+
+        # Extract captured locals from an exception (if any)
+        # @param exception [Exception] The exception to check
+        # @return [Hash, nil] Raw locals hash or nil
+        def extract(exception)
+          return nil unless exception.is_a?(Exception)
+          return nil unless exception.instance_variable_defined?(LOCALS_IVAR)
+
+          exception.instance_variable_get(LOCALS_IVAR)
+        rescue => e
+          RailsErrorDashboard::Logger.debug(
+            "[RailsErrorDashboard] LocalVariableCapturer.extract failed: #{e.message}"
+          )
+          nil
+        end
+
+        # Extract captured instance variables from an exception (if any)
+        # @param exception [Exception] The exception to check
+        # @return [Hash, nil] Raw instance vars hash or nil
+        def extract_instance_vars(exception)
+          return nil unless exception.is_a?(Exception)
+          return nil unless exception.instance_variable_defined?(INSTANCE_VARS_IVAR)
+
+          exception.instance_variable_get(INSTANCE_VARS_IVAR)
+        rescue => e
+          RailsErrorDashboard::Logger.debug(
+            "[RailsErrorDashboard] LocalVariableCapturer.extract_instance_vars failed: #{e.message}"
+          )
+          nil
+        end
+
+        private
+
+        # TracePoint callback — runs on every :raise event
+        # Filter chain ordered cheapest-first for minimal overhead
+        def on_raise(tp)
+          exception = tp.raised_exception
+          config = RailsErrorDashboard.configuration
+
+          # 1. Re-raise guard: skip if already captured both
+          locals_captured = exception.instance_variable_defined?(LOCALS_IVAR)
+          ivars_captured = exception.instance_variable_defined?(INSTANCE_VARS_IVAR)
+          return if locals_captured && ivars_captured
+
+          # 2. Skip system/signal exceptions
+          return if exception.is_a?(SystemExit) || exception.is_a?(SignalException) || exception.is_a?(Interrupt)
+
+          # 3. Skip common flow-control exceptions (avoid expensive tp.binding call)
+          return if defined?(ActionController::RoutingError) && exception.is_a?(ActionController::RoutingError)
+          return if defined?(ActiveRecord::RecordNotFound) && exception.is_a?(ActiveRecord::RecordNotFound)
+          return if defined?(ActionController::UnknownFormat) && exception.is_a?(ActionController::UnknownFormat)
+
+          # 4. Skip non-app-code paths
+          path = tp.path.to_s
+          return if skip_path?(path)
+
+          # 5. Extract local variables from the binding (if enabled and not already captured)
+          if config.enable_local_variables && !locals_captured
+            locals = extract_locals(tp.binding)
+            exception.instance_variable_set(LOCALS_IVAR, locals) if locals && locals.any?
+          end
+
+          # 6. Extract instance variables from tp.self (if enabled and not already captured)
+          if config.enable_instance_variables && !ivars_captured
+            ivars = capture_instance_vars(tp.self)
+            exception.instance_variable_set(INSTANCE_VARS_IVAR, ivars) if ivars && ivars.any?
+          end
+        end
+
+        # Check if the path should be skipped (gem code, vendor, stdlib, this gem)
+        def skip_path?(path)
+          path.include?("/gems/") ||
+            path.include?("/vendor/") ||
+            path.include?("/ruby/") ||
+            path.include?("rails_error_dashboard") ||
+            path.start_with?("<") ||   # Ruby 3.3+: <eval>, <irb>, etc.
+            path.start_with?("(")      # Ruby 3.2: (eval), (irb), etc.
+        end
+
+        # Extract local variables from a binding (per-variable rescue)
+        # @param binding_obj [Binding] The binding at raise time
+        # @return [Hash] { variable_name_symbol => raw_value }
+        def extract_locals(binding_obj)
+          return nil unless binding_obj
+
+          var_names = binding_obj.local_variables
+          return nil if var_names.empty?
+
+          # Respect max count limit at extraction time (reduces memory on exception object)
+          max_count = RailsErrorDashboard.configuration.local_variable_max_count || 15
+          var_names = var_names.first(max_count)
+
+          locals = {}
+          var_names.each do |name|
+            locals[name] = binding_obj.local_variable_get(name)
+          rescue => e
+            locals[name] = "(extraction error: #{e.class.name})"
+          end
+
+          locals
+        rescue => e
+          RailsErrorDashboard::Logger.debug(
+            "[RailsErrorDashboard] extract_locals failed: #{e.message}"
+          )
+          nil
+        end
+
+        # Extract instance variables from the receiver object (tp.self)
+        # Never stores the object reference — extracts values immediately.
+        # @param obj [Object] The receiver where the exception was raised
+        # @return [Hash, nil] { :_self_class => class_name, :@ivar_name => raw_value }
+        def capture_instance_vars(obj)
+          return nil if obj.nil?
+
+          config = RailsErrorDashboard.configuration
+          max_count = config.instance_variable_max_count || 20
+
+          # Get instance variable names (safe — instance_variables is always available)
+          ivar_names = obj.instance_variables
+          return nil if ivar_names.empty?
+
+          # Filter out internal ivars:
+          # - @_red_* — our own gem ivars (e.g. @_red_locals, @_red_instance_vars)
+          # - @_* — Rails framework internals (e.g. @_request, @_response, @_action_name)
+          ivar_names = ivar_names.reject { |name| name.to_s.start_with?("@_") }
+          return nil if ivar_names.empty?
+
+          # Respect max count limit
+          ivar_names = ivar_names.first(max_count)
+
+          result = {}
+
+          # Add metadata: class name of the receiver
+          result[:_self_class] = begin
+            obj.class.name || obj.class.to_s
+          rescue
+            "Unknown"
+          end
+
+          # Extract each instance variable (per-variable rescue)
+          ivar_names.each do |name|
+            result[name] = obj.instance_variable_get(name)
+          rescue => e
+            result[name] = "(extraction error: #{e.class.name})"
+          end
+
+          result
+        rescue => e
+          RailsErrorDashboard::Logger.debug(
+            "[RailsErrorDashboard] capture_instance_vars failed: #{e.message}"
+          )
+          nil
+        end
+      end
+    end
+  end
+end