rails_nexus 2.0.0

data/lib/rails_nexus/configuration.rb

@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+
+module RailsNexus
+  class Configuration
+    # ─── General ───────────────────────────────────────────────
+
+    # Dashboard title shown in the header. Set to nil to use "RailsNexus".
+    attr_accessor :application_name
+
+    # Enable/disable the dashboard entirely (default: true).
+    attr_accessor :enabled
+
+    # Number of exceptions per page (default: 30).
+    attr_accessor :per_page
+
+    # ─── Authentication ────────────────────────────────────────
+
+    # Proc called with the controller instance before each request.
+    # Return false/nil to deny access; return true to allow.
+    # Example:
+    #   config.auth_block = ->(controller) { controller.current_user&.admin? }
+    attr_accessor :auth_block
+
+    # ─── Exception Data ────────────────────────────────────────
+
+    # Proc called with the controller to attach extra data to each exception record.
+    # Example:
+    #   config.exception_data = ->(controller) { { user_id: controller.current_user&.id } }
+    attr_accessor :exception_data
+
+    # ─── Notifications ─────────────────────────────────────────
+
+    # Proc called with the LoggedException record after creation.
+    # Use for Telegram, Slack, email, or custom notifications.
+    # Example:
+    #   config.after_create = ->(exception) { MyNotifier.alert(exception) }
+    attr_accessor :after_create
+
+    # Webhook URLs called on each new exception (POST with JSON body).
+    # Example:
+    #   config.webhooks = ["https://hooks.slack.com/services/xxx"]
+    attr_accessor :webhooks
+
+    # Webhook timeout in seconds (default: 5).
+    attr_accessor :webhook_timeout
+
+    # Custom headers sent with webhook requests.
+    # Example:
+    #   config.webhook_headers = { "Authorization" => "Bearer token123" }
+    attr_accessor :webhook_headers
+
+    # ─── Logging ───────────────────────────────────────────────
+
+    # Enable structured logging (default: true).
+    attr_accessor :logging_enabled
+
+    # Log level for rails_nexus logger (default: :info).
+    # Options: :debug, :info, :warn, :error, :fatal
+    attr_accessor :log_level
+
+    # Write logs to a JSON file (path or nil).
+    # Example:
+    #   config.log_file = "log/rails_nexus.log"
+    attr_accessor :log_file
+
+    # Include backtrace in logs (default: true).
+    attr_accessor :log_backtrace
+
+    # Include request params in logs (default: true).
+    attr_accessor :log_params
+
+    # Include user info in logs (default: true).
+    attr_accessor :log_user_info
+
+    # Maximum backtrace lines to include (default: 20).
+    attr_accessor :log_backtrace_limit
+
+    # Enable exception deduplication (default: false).
+    # When enabled, only logs unique exception class + controller combinations
+    # within a time window.
+    attr_accessor :deduplication_enabled
+
+    # Deduplication time window in seconds (default: 300 = 5 minutes).
+    attr_accessor :deduplication_window
+
+    # ─── Cleanup / Retention ───────────────────────────────────
+
+    # Automatically delete exceptions older than N days.
+    # Set to nil to disable (default: nil).
+    attr_accessor :retention_days
+
+    # ─── Appearance ────────────────────────────────────────────
+
+    # Dashboard theme: "light", "dark", or "auto" (default: "auto").
+    attr_accessor :theme
+
+    # Use the host app's layout instead of rails_nexus's built-in layout.
+    # Set to true to render inside the host app's sidebar/nav.
+    # Set to false (default) for a standalone dashboard.
+    attr_accessor :use_host_layout
+
+    # CSS class added to the dashboard body element.
+    attr_accessor :body_class
+
+    # ─── Sidebar Links ─────────────────────────────────────────
+
+    # Custom links shown in the dashboard sidebar.
+    # Example:
+    #   config.sidebar_links = [
+    #     { label: "GitHub", url: "https://github.com/myorg/myapp", icon: "code" },
+    #     { label: "Docs", url: "/docs", icon: "book" }
+    #   ]
+    attr_accessor :sidebar_links
+
+    # ─── Advanced UI ───────────────────────────────────────────
+
+    # Show stats overview cards on index page (default: true).
+    attr_accessor :show_stats
+
+    # Enable keyboard shortcuts in the dashboard (default: true).
+    attr_accessor :keyboard_shortcuts
+
+    # Enable exception grouping in the list (default: false).
+    # Groups exceptions by class + controller.
+    attr_accessor :group_exceptions
+
+    # Show metadata grid in detail view (default: true).
+    attr_accessor :show_metadata
+
+    # Show environment variables in detail view (default: false).
+    attr_accessor :show_environment
+
+    # Show request params in detail view (default: true).
+    attr_accessor :show_request
+
+    # Maximum number of backtrace frames to show before collapsing (default: 30).
+    attr_accessor :backtrace_limit
+
+    # Enable prev/next navigation in detail view (default: true).
+    attr_accessor :enable_navigation
+
+    # Columns to show in the exception table.
+    # Default: [:class, :controller, :action, :message, :time]
+    attr_accessor :table_columns
+
+    # Date format for display (default: nil = auto relative).
+    attr_accessor :date_format
+
+    # Rows per page options for the page size selector (default: [25, 50, 100]).
+    attr_accessor :page_size_options
+
+    # Server Statistics
+    attr_accessor :show_server_stats
+    attr_accessor :show_sidekiq_stats
+    attr_accessor :show_process_info
+    attr_accessor :stats_refresh_interval
+
+    # Cron Job Monitoring
+    attr_accessor :cron_job_tracking
+    attr_accessor :cron_job_retention_days
+
+    # Webhook Delivery Logging
+    attr_accessor :log_webhook_deliveries
+    attr_accessor :webhook_delivery_retention_days
+
+    # Breadcrumbs
+    attr_accessor :breadcrumbs_enabled
+
+    # Storm Protection
+    attr_accessor :storm_protection_enabled
+    attr_accessor :storm_threshold_per_second
+    attr_accessor :storm_cooldown_seconds
+
+    # User Impact
+    attr_accessor :user_impact_tracking
+
+    # Source Code Viewing
+    attr_accessor :source_code_viewing
+
+    # Backup Management
+    attr_accessor :backup_enabled
+    attr_accessor :backup_config_path
+    attr_accessor :backup_models_path
+    attr_accessor :backup_dump_path
+    attr_accessor :backup_notify_command
+    attr_accessor :backup_alert_threshold_hours
+
+    # ─── Database ───────────────────────────────────────────────
+    # Use a separate database for RailsNexus tables.
+    # Options:
+    #   config.database_url = "mysql2://user:pass@localhost/rails_nexus"
+    #   config.database_name = "rails_nexus"  # uses config/database.yml entry
+    #   config.database_yml  = "config/rails_nexus_database.yml"
+    #   config.table_prefix  = "rails_nexus_"
+    attr_accessor :database_url
+    attr_accessor :database_name
+    attr_accessor :database_yml
+    attr_accessor :table_prefix
+
+    def initialize
+      @application_name = nil
+      @auth_block = nil
+      @exception_data = nil
+      @after_create = nil
+      @per_page = 30
+      @enabled = true
+
+      # Notifications
+      @webhooks = []
+      @webhook_timeout = 5
+      @webhook_headers = {}
+
+      # Logging
+      @logging_enabled = true
+      @log_level = :info
+      @log_file = nil
+      @log_backtrace = true
+      @log_params = true
+      @log_user_info = true
+      @log_backtrace_limit = 20
+      @deduplication_enabled = false
+      @deduplication_window = 300
+
+      # Cleanup
+      @retention_days = nil
+
+      # Appearance
+      @theme = "auto"
+      @use_host_layout = false
+      @body_class = ""
+
+      # Sidebar
+      @sidebar_links = []
+
+      # Advanced UI
+      @show_stats = true
+      @keyboard_shortcuts = true
+      @group_exceptions = false
+      @show_metadata = true
+      @show_environment = false
+      @show_request = true
+      @backtrace_limit = 30
+      @enable_navigation = true
+      @table_columns = %i[class controller action message time].freeze
+      @date_format = nil
+      @page_size_options = [25, 50, 100].freeze
+
+      # Server Statistics
+      @show_server_stats = true
+      @show_sidekiq_stats = true
+      @show_process_info = true
+      @stats_refresh_interval = 30
+
+      # Cron Job Monitoring
+      @cron_job_tracking = true
+      @cron_job_retention_days = 30
+
+      # Webhook Delivery Logging
+      @log_webhook_deliveries = true
+      @webhook_delivery_retention_days = 30
+
+      # Breadcrumbs (activity trail) — needed for N+1 detection and breadcrumb tab
+      @breadcrumbs_enabled = true
+
+      # Storm Protection (circuit breaker)
+      @storm_protection_enabled = true
+      @storm_threshold_per_second = 50
+      @storm_cooldown_seconds = 60
+
+      # User Impact
+      @user_impact_tracking = true
+
+      # Source Code Viewing
+      @source_code_viewing = true
+
+      # Backup Management
+      @backup_enabled = false
+      @backup_config_path = default_backup_config_path
+      @backup_models_path = default_backup_models_path
+      @backup_dump_path = default_backup_dump_path
+      @backup_notify_command = nil
+      @backup_alert_threshold_hours = 24
+
+      # Database
+      @database_url = nil
+      @database_name = nil
+      @database_yml = nil
+      @table_prefix = "rails_nexus_"
+    end
+
+    private
+
+    def default_backup_config_path
+      if defined?(Rails) && Rails.respond_to?(:root)
+        path = Rails.root.join("config/backup/config.rb")
+        path.exist? ? path.to_s : nil
+      else
+        nil
+      end
+    end
+
+    def default_backup_models_path
+      if defined?(Rails) && Rails.respond_to?(:root)
+        path = Rails.root.join("config/backup/models")
+        path.exist? ? path.to_s : nil
+      else
+        nil
+      end
+    end
+
+    def default_backup_dump_path
+      if defined?(Rails) && Rails.respond_to?(:root)
+        Rails.root.join("storage/rails_nexus/backups").to_s
+      else
+        "storage/rails_nexus/backups"
+      end
+    end
+  end
+end

data/lib/rails_nexus/engine.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module RailsNexus
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsNexus
+
+    engine_name "rails_nexus"
+
+    # ─── Asset paths (Propshaft and Sprockets) ───
+
+    initializer "rails_nexus.assets", before: "propshaft.assets_middleware", group: :all do |app|
+      next unless app.config.respond_to?(:assets)
+
+      app.config.assets.paths << root.join("app/javascript")
+
+      # Sprockets 4 only compiles assets listed in a manifest or in the
+      # precompile list. Register these here so mounting applications do not
+      # need to modify their own asset manifest.
+      if app.config.assets.respond_to?(:precompile)
+        app.config.assets.precompile += %w[
+          rails_nexus/application.css
+          rails_nexus/application.js
+          controllers/rails_nexus_controller.js
+          controllers/rails_nexus_detail_controller.js
+          controllers/rails_nexus_sidebar_controller.js
+          controllers/rails_nexus_theme_controller.js
+        ]
+      end
+    end
+
+    # ─── Importmap support (for importmap-rails users) ────────────
+
+    initializer "rails_nexus.importmap", before: "importmap" do |app|
+      app.config.importmap.paths << root.join("config/importmap.rb")
+      app.config.importmap.cache_sweepers << root.join("app/javascript")
+    end
+
+    # ─── Database connection (separate DB support) ─────────────────
+
+    initializer "rails_nexus.database" do
+      ActiveSupport.on_load(:active_record) do
+        config = RailsNexus.configuration
+
+        if config.database_url.present?
+          uri = URI.parse(config.database_url)
+          RailsNexus::BaseRecord.establish_connection(
+            adapter: uri.scheme,
+            host: uri.host,
+            port: uri.port&.to_i,
+            username: URI.decode_www_form_component(uri.user || ""),
+            password: URI.decode_www_form_component(uri.password || ""),
+            database: uri.path&.gsub(%r{^/}, "")
+          )
+          Rails.logger.info("[RailsNexus] Connected to separate database: #{config.database_url.split("@").last}") if Rails.logger
+
+        elsif config.database_name.present?
+          yaml_path = Rails.root.join("config", "database.yml")
+          if yaml_path.exist?
+            yaml = YAML.safe_load(ERB.new(yaml_path.read).result, aliases: true) || {}
+            env_config = yaml[Rails.env.to_s] || yaml[Rails.env]
+            if env_config.is_a?(Hash)
+              db_config = env_config.symbolize_keys
+              db_config[:database] = config.database_name if config.database_name.is_a?(String)
+              RailsNexus::BaseRecord.establish_connection(**db_config)
+              Rails.logger.info("[RailsNexus] Connected to database: #{config.database_name}") if Rails.logger
+            end
+          end
+
+        elsif config.database_yml.present?
+          yaml_path = Rails.root.join(config.database_yml)
+          if yaml_path.exist?
+            yaml = YAML.safe_load(ERB.new(yaml_path.read).result, aliases: true) || {}
+            env_config = yaml[Rails.env.to_s] || yaml[Rails.env]
+            RailsNexus::BaseRecord.establish_connection(**env_config.symbolize_keys) if env_config.is_a?(Hash)
+            Rails.logger.info("[RailsNexus] Connected to database from #{config.database_yml}") if Rails.logger
+          end
+        end
+        # If none configured, BaseRecord inherits ApplicationRecord's connection (default)
+      end
+    end
+
+    # ─── Ransack configuration ───────────────────────────────────
+
+    initializer "rails_nexus.ransack" do
+      ActiveSupport.on_load(:active_record) do
+        require "rails_nexus/ransack_config" if defined?(Ransack)
+      end
+    end
+
+    # ─── Load support modules ─────────────────────────────────────
+
+    initializer "rails_nexus.support" do
+      require "rails_nexus/notifications"
+      require "rails_nexus/cleanup"
+      require "rails_nexus/storm_protection"
+    end
+
+    # ─── Rake tasks ──────────────────────────────────────────────
+
+    initializer "rails_nexus.rake_tasks" do
+      load "tasks/rails_nexus.rake" if Rake.respond_to?(:application)
+    end
+
+    # ─── Hook into after_create for notifications ─────────────────
+
+    initializer "rails_nexus.after_create" do
+      ActiveSupport.on_load(:active_record) do
+        RailsNexus::LoggedException.after_create do |exception|
+          RailsNexus::Notifications.notify(exception)
+        rescue StandardError => e
+          Rails.logger.error("[RailsNexus] Notification error: #{e.message}")
+        end
+      end
+    end
+
+    # ─── Storm protection ─────────────────────────────────────────
+
+    initializer "rails_nexus.storm_protection" do
+      ActiveSupport.on_load(:active_record) do
+        require "rails_nexus/storm_protection"
+      end
+    end
+
+    # ─── Breadcrumbs subscription ─────────────────────────────────
+
+    initializer "rails_nexus.breadcrumbs" do
+      ActiveSupport.on_load(:active_record) do
+        require "rails_nexus/breadcrumbs"
+        if RailsNexus.configuration.breadcrumbs_enabled
+          RailsNexus::Breadcrumbs.subscribe!
+        end
+      end
+    end
+  end
+end

data/lib/rails_nexus/logger.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module RailsNexus
+  class Logger
+    # Log levels
+    LEVELS = %i[debug info warn error fatal].freeze
+
+    # Default context that's attached to every log entry
+    DEFAULT_CONTEXT = {
+      gem: "rails_nexus",
+      version: RailsNexus::VERSION
+    }.freeze
+
+    class << self
+      # Log an exception with full context
+      #
+      #   RailsNexus::Logger.error(exception, controller: self, extra: { key: "value" })
+      #
+      def error(exception, controller: nil, extra: {}, **kwargs)
+        log(:error, exception, controller: controller, extra: extra, **kwargs)
+      end
+
+      def warn(exception, controller: nil, extra: {}, **kwargs)
+        log(:warn, exception, controller: controller, extra: extra, **kwargs)
+      end
+
+      def info(message, controller: nil, extra: {}, **kwargs)
+        log(:info, message, controller: controller, extra: extra, **kwargs)
+      end
+
+      def debug(message, controller: nil, extra: {}, **kwargs)
+        log(:debug, message, controller: controller, extra: extra, **kwargs)
+      end
+
+      # Log a custom event (not an exception)
+      #
+      #   RailsNexus::Logger.event("user.login", user_id: 123, method: "POST")
+      #
+      def event(name, data = {})
+        entry = build_entry(:info, name, nil, extra: data)
+        write_to_output(entry)
+        write_to_file(entry) if RailsNexus.configuration.log_file.present?
+        entry
+      end
+
+      # Query logs with filters
+      #
+      #   RailsNexus::Logger.query(level: :error, since: 1.hour.ago, limit: 50)
+      #
+      def query(level: nil, since: nil, controller_name: nil, limit: 100)
+        scope = RailsNexus::LoggedException.order(created_at: :desc)
+        scope = scope.where("created_at >= ?", since) if since.present?
+        scope = scope.where(exception_class: level.to_s.camelize) if level.present?
+        scope = scope.where(controller_name: controller_name) if controller_name.present?
+        scope.limit(limit)
+      end
+
+      # Get aggregated stats
+      #
+      #   RailsNexus::Logger.stats(since: 24.hours.ago)
+      #
+      def stats(since: nil)
+        scope = RailsNexus::LoggedException.all
+        scope = scope.where("created_at >= ?", since) if since.present?
+
+        {
+          total: scope.count,
+          by_class: scope.group(:exception_class).count,
+          by_controller: scope.group(:controller_name).count,
+          by_hour: scope.group_by { |e| e.created_at.hour }.transform_values(&:count),
+          top_exceptions: scope.group(:exception_class).count.sort_by { |_, v| -v }.first(10)
+        }
+      end
+
+      private
+
+      def log(level, exception_or_message, controller: nil, extra: {}, **kwargs)
+        message = exception_or_message.is_a?(Exception) ? exception_or_message.message : exception_or_message.to_s
+        exception_class = exception_or_message.is_a?(Exception) ? exception_or_message.class.name : nil
+
+        entry = build_entry(level, message, exception_class,
+          controller: controller,
+          extra: extra.merge(kwargs),
+          backtrace: exception_or_message.is_a?(Exception) ? exception_or_message.backtrace&.first(20)&.join("\n") : nil
+        )
+
+        write_to_output(entry)
+        write_to_file(entry) if RailsNexus.configuration.log_file.present?
+        entry
+      end
+
+      def build_entry(level, message, exception_class, controller: nil, extra: {}, backtrace: nil)
+        entry = DEFAULT_CONTEXT.merge(
+          level: level,
+          message: message,
+          timestamp: Time.current.iso8601
+        )
+
+        entry[:exception_class] = exception_class if exception_class.present?
+
+        # Add controller context
+        if controller.present?
+          entry[:controller] = {
+            class: controller.class.name,
+            action: controller.action_name,
+            path: controller.request&.path,
+            method: controller.request&.request_method,
+            remote_ip: controller.request&.remote_ip,
+            user_agent: controller.request&.user_agent
+          }
+
+          # Add user context
+          if controller.respond_to?(:current_user, true) && controller.current_user.present?
+            entry[:user] = {
+              id: controller.current_user.id,
+              email: controller.current_user.email
+            }
+          end
+
+          # Add request params (filtered)
+          if controller.request.present?
+            entry[:params] = filter_params(controller.request.filtered_parameters)
+          end
+        end
+
+        # Add extra metadata
+        entry[:extra] = extra if extra.present?
+        entry[:backtrace] = backtrace if backtrace.present?
+
+        entry
+      end
+
+      def write_to_output(entry)
+        level = entry[:level]
+        color = case level
+                when :debug then "\e[37m"  # white
+                when :info  then "\e[36m"  # cyan
+                when :warn  then "\e[33m"  # yellow
+                when :error then "\e[31m"  # red
+                when :fatal then "\e[35m"  # magenta
+                else "\e[0m"
+                end
+
+        reset = "\e[0m"
+        ts = entry[:timestamp].sub(/T/, " ").sub(/\+.*/, "")
+        msg = entry[:message]
+        cls = entry[:exception_class]
+
+        line = "#{color}[RailsNexus]#{reset} #{ts} #{level.to_s.upcase.ljust(5)}"
+        line += " #{cls}:" if cls.present?
+        line += " #{msg}"
+
+        if entry[:controller]
+          ctrl = entry[:controller]
+          line += " [#{ctrl[:class]}##{ctrl[:action]}]"
+        end
+
+        Rails.logger.send(level, line)
+      end
+
+      def write_to_file(entry)
+        file = RailsNexus.configuration.log_file
+        return unless file.present?
+
+        File.open(file, "a") do |f|
+          f.puts(entry.to_json)
+        end
+      rescue StandardError => e
+        Rails.logger.error("[RailsNexus] Failed to write to log file: #{e.message}")
+      end
+
+      def filter_params(params)
+        return {} unless params.is_a?(Hash)
+
+        rails_filters = Rails.application.config.filter_parameters
+        params.each_with_object({}) do |(key, value), result|
+          if rails_filters.any? { |f| key.to_s.include?(f.to_s) }
+            result[key] = "[FILTERED]"
+          elsif value.is_a?(Hash)
+            result[key] = filter_params(value)
+          else
+            result[key] = value
+          end
+        end
+      end
+    end
+  end
+end