rails_nexus 2.0.0

data/lib/rails_nexus/notifications.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module RailsNexus
+  module Notifications
+    class << self
+      # Called after a LoggedException is created.
+      # Triggers webhooks and the after_create callback.
+      def notify(exception_record)
+        config = RailsNexus.configuration
+
+        # Custom after_create callback
+        config.after_create&.call(exception_record)
+
+        # Webhooks
+        notify_webhooks(exception_record) if config.webhooks.any?
+      end
+
+      private
+
+      def notify_webhooks(exception_record)
+        config = RailsNexus.configuration
+        payload = build_webhook_payload(exception_record)
+
+        config.webhooks.each do |url|
+          deliver_webhook(url, payload, config)
+        rescue StandardError => e
+          Rails.logger.error("[RailsNexus] Webhook failed for #{url}: #{e.message}")
+          log_webhook_delivery(url: url, payload: payload, error: e.message, event_type: "exception.logged")
+        end
+      end
+
+      def deliver_webhook(url, payload, config)
+        uri = URI(url)
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = config.webhook_timeout
+        http.read_timeout = config.webhook_timeout
+
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
+        config.webhook_headers.each { |k, v| request[k] = v }
+        request.body = payload.to_json
+
+        response = http.request(request)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          Rails.logger.error("[RailsNexus] Webhook #{url} returned #{response.code}")
+        end
+      end
+
+      def log_webhook_delivery(url:, payload:, status_code: nil, response_body: nil, error: nil, event_type: nil)
+        return unless defined?(RailsNexus::WebhookDelivery) && RailsNexus.configuration.log_webhook_deliveries
+
+        if error.present?
+          RailsNexus::WebhookDelivery.log_failure!(
+            url: url,
+            request_body: payload.to_json,
+            error_message: error,
+            event_type: event_type
+          )
+        else
+          RailsNexus::WebhookDelivery.log_success!(
+            url: url,
+            request_body: payload.to_json,
+            response_code: status_code,
+            response_body: response_body,
+            duration: 0,
+            event_type: event_type
+          )
+        end
+      rescue StandardError => e
+        Rails.logger.error("[RailsNexus] Failed to log webhook delivery: #{e.message}")
+      end
+
+      def build_webhook_payload(exception_record)
+        {
+          event: "exception.logged",
+          timestamp: exception_record.created_at.iso8601,
+          exception: {
+            id: exception_record.id,
+            class: exception_record.exception_class,
+            message: exception_record.message&.truncate(500),
+            controller: exception_record.controller_name,
+            action: exception_record.action_name,
+            remote_ip: exception_record.remote_ip,
+            user_agent: exception_record.user_agent
+          },
+          dashboard_url: dashboard_url(exception_record)
+        }
+      end
+
+      def dashboard_url(exception_record)
+        host = Rails.application.routes.default_url_options[:host] ||
+               ENV.fetch("APP_HOST", "localhost:3000")
+        protocol = Rails.env.production? ? "https" : "http"
+        "#{protocol}://#{host}/rails_nexus/logged_exceptions/#{exception_record.id}"
+      end
+    end
+  end
+end

data/lib/rails_nexus/ransack_config.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Ransack configuration is now defined directly on RailsNexus::LoggedException
+# in app/models/rails_nexus/logged_exception.rb.

data/lib/rails_nexus/storm_protection.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module RailsNexus
+  # Storm Protection: Circuit breaker + adaptive sampling
+  # Prevents error floods from crashing the app with DB writes
+  module StormProtection
+    # Default thresholds
+    DEFAULT_PER_PROCESS_THRESHOLD = 50  # errors per second per process
+    DEFAULT_GLOBAL_THRESHOLD = 200       # errors per second globally
+    DEFAULT_COOLDOWN_SECONDS = 60        # circuit breaker cooldown
+    DEFAULT_SAMPLE_RATE_CALM = 1.0       # 100% capture when calm
+    DEFAULT_SAMPLE_RATE_STORM = 0.1      # 10% capture during storm
+
+    class << self
+      attr_reader :circuit_open, :error_counts, :last_reset
+
+      def enabled?
+        RailsNexus.configuration.storm_protection_enabled
+      end
+
+      def threshold
+        RailsNexus.configuration.storm_threshold_per_second || DEFAULT_PER_PROCESS_THRESHOLD
+      end
+
+      def cooldown
+        RailsNexus.configuration.storm_cooldown_seconds || DEFAULT_COOLDOWN_SECONDS
+      end
+
+      # Check if we should capture this error
+      # Returns true if allowed, false if shed
+      def allow_capture?
+        return true unless enabled?
+
+        reset_counts_if_needed
+
+        # If circuit is open (storm detected), use sampling
+        if circuit_open?
+          return should_sample?
+        end
+
+        # Increment count and check threshold
+        @error_counts[:total] += 1
+        @error_counts[:current_second] += 1
+
+        if @error_counts[:current_second] >= threshold
+          open_circuit!
+          return should_sample?
+        end
+
+        true
+      end
+
+      # Record that an error was captured
+      def record_captured
+        @error_counts[:captured] += 1
+      end
+
+      # Record that an error was shed
+      def record_shed
+        @error_counts[:shed] += 1
+      end
+
+      # Get current stats
+      def stats
+        reset_counts_if_needed
+        {
+          enabled: enabled?,
+          circuit_open: circuit_open?,
+          errors_this_second: @error_counts[:current_second] || 0,
+          threshold: threshold,
+          total_errors: @error_counts[:total] || 0,
+          total_captured: @error_counts[:captured] || 0,
+          total_shed: @error_counts[:shed] || 0,
+          last_reset: @last_reset,
+          sample_rate: circuit_open? ? DEFAULT_SAMPLE_RATE_STORM : DEFAULT_SAMPLE_RATE_CALM
+        }
+      end
+
+      # Reset circuit (manual or after cooldown)
+      def reset!
+        @circuit_open = false
+        @error_counts = { total: 0, current_second: 0, captured: 0, shed: 0 }
+        @last_reset = Time.now
+        @second_window = Time.now.to_i
+      end
+
+      private
+
+      def circuit_open?
+        return false unless @circuit_open
+
+        # Auto-reset after cooldown
+        if Time.now - @circuit_open_at > cooldown
+          reset!
+          return false
+        end
+
+        true
+      end
+
+      def open_circuit!
+        @circuit_open = true
+        @circuit_open_at = Time.now
+        Rails.logger.warn("[RailsNexus] Storm protection: circuit opened at #{@error_counts[:current_second]} errors/sec")
+      end
+
+      def reset_counts_if_needed
+        current_second = Time.now.to_i
+        if current_second != @second_window
+          @error_counts[:current_second] = 0
+          @second_window = current_second
+        end
+      end
+
+      def should_sample?
+        # Keep 10% of errors during storm
+        rand < DEFAULT_SAMPLE_RATE_STORM
+      end
+    end
+
+    # Initialize on load
+    reset!
+  end
+end

data/lib/rails_nexus/version.rb

@@ -0,0 +1,3 @@
+module RailsNexus
+  VERSION = "2.0.0"
+end

data/lib/rails_nexus.rb

@@ -0,0 +1,133 @@
+require "rails"
+require "importmap-rails"
+require "turbo-rails"
+require "stimulus-rails"
+require "pagy"
+require "ipaddr"
+require "socket"
+require "rails_nexus/version"
+require "rails_nexus/configuration"
+require "rails_nexus/logger"
+require "rails_nexus/engine"
+
+module RailsNexus
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    # Backward-compatible accessor for application_name
+    def application_name
+      configuration.application_name
+    end
+
+    def application_name=(value)
+      configuration.application_name = value
+    end
+
+    # Convenience logger accessor
+    def logger
+      RailsNexus::Logger
+    end
+  end
+
+  # Copyright (c) 2005 Jamis Buck
+  #
+  # Permission is hereby granted, free of charge, to any person obtaining
+  # a copy of this software and associated documentation files (the
+  # "Software"), to deal in the Software without restriction, including
+  # without limitation the rights to use, copy, modify, merge, publish,
+  # distribute, sublicense, and/or sell copies of the Software, and to
+  # permit persons to whom the Software is furnished to do so, subject to
+  # the following conditions:
+  #
+  # The above copyright notice and this permission notice shall be
+  # included in all copies or substantial portions of the Software.
+  #
+  # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+  # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+  # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+  # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+  # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+  # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+  module ExceptionLoggable
+    def self.included(target)
+      target.extend(ClassMethods)
+      target.class_attribute :local_addresses, :exception_data
+
+      target.local_addresses = [IPAddr.new("127.0.0.1")]
+    end
+
+    module ClassMethods
+      def consider_local(*args)
+        local_addresses.concat(args.flatten.map { |a| IPAddr.new(a) })
+      end
+    end
+
+    def local_request?
+      remote = IPAddr.new(request.remote_ip)
+      !self.class.local_addresses.detect { |addr| addr.include?(remote) }.nil?
+    end
+
+    # we log the exception and raise it again, for the normal handling.
+    def log_exception_handler(exception)
+      log_exception(exception)
+      raise exception
+    end
+
+    def rescue_action(exception)
+      status = response_code_for_rescue(exception)
+      log_exception(exception) if status != :not_found
+      super
+    end
+
+    def filter_sub_parameters(params, rails_filter_parameters)
+      params.each do |key, value|
+        if(value.class != Hash and value.class != ActiveSupport::HashWithIndifferentAccess)
+          params[key] = '[FILTERED]' if rails_filter_parameters.include?(key.to_sym)
+        else
+          params[key] = filter_sub_parameters(value, rails_filter_parameters)
+        end
+      end
+      params
+    end
+
+    def log_exception(exception)
+      # Support both the legacy class_attribute and the new configuration DSL
+      deliverer = if self.class.exception_data
+                    self.class.exception_data
+                  elsif RailsNexus.configuration.exception_data
+                    RailsNexus.configuration.exception_data
+                  end
+
+      data = case deliverer
+             when nil    then {}
+             when Symbol then send(deliverer)
+             when Proc   then deliverer.call(self)
+             end
+
+      rails_filter_parameters = defined?(::Rails) ? ::Rails.application.config.filter_parameters : []
+
+      self.request.parameters.each do |key, value|
+        if(value.class != Hash and value.class != ActiveSupport::HashWithIndifferentAccess)
+          self.request.parameters[key] = '[FILTERED]' if rails_filter_parameters.include?(key.to_sym)
+        else
+          self.request.parameters[key] = filter_sub_parameters(value, rails_filter_parameters)
+        end
+      end if rails_filter_parameters.any?
+
+      # Log with structured logger
+      RailsNexus::Logger.error(exception, controller: self, extra: data)
+
+      # Create the record
+      LoggedException.create_from_exception(self, exception, data)
+    end
+  end
+end

data/lib/tasks/rails_nexus.rake

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+namespace :rails_nexus do
+  desc "Delete exceptions older than the configured retention period"
+  task cleanup: :environment do
+    require "rails_nexus/cleanup"
+    count = RailsNexus::Cleanup.run
+    if count
+      puts "✓ Cleaned up #{count} old exceptions."
+    else
+      puts "⚠ No retention_days configured. Set config.retention_days in your initializer."
+    end
+  end
+
+  desc "Show rails_nexus statistics"
+  task stats: :environment do
+    require "rails_nexus/logger"
+
+    stats = RailsNexus::Logger.stats
+
+    puts ""
+    puts "  ⚡ RailsNexus v#{RailsNexus::VERSION}"
+    puts "  ─────────────────────────────────────"
+    puts "  Total exceptions:  #{stats[:total]}"
+    puts ""
+
+    if stats[:top_exceptions].any?
+      puts "  Top exceptions:"
+      stats[:top_exceptions].each do |klass, count|
+        puts "    #{klass.ljust(40)} #{count}"
+      end
+      puts ""
+    end
+
+    if stats[:by_controller].any?
+      puts "  By controller:"
+      stats[:by_controller].sort_by { |_, v| -v }.first(10).each do |ctrl, count|
+        puts "    #{ctrl.to_s.ljust(40)} #{count}"
+      end
+      puts ""
+    end
+  end
+
+  desc "Tail rails_nexus logs in real-time"
+  task tail: :environment do
+    log_file = RailsNexus.configuration.log_file
+    if log_file.blank?
+      puts "⚠ No log_file configured. Set config.log_file in your initializer."
+      puts "  Example: config.log_file = 'log/rails_nexus.log'"
+      next
+    end
+
+    puts "Tailing #{log_file}... (Ctrl+C to stop)"
+    puts ""
+
+    IO.popen(["tail", "-f", log_file]) do |io|
+      while (line = io.gets)
+        begin
+          entry = JSON.parse(line)
+          level = entry["level"].to_s.upcase.ljust(5)
+          ts = entry["timestamp"].to_s.sub(/T/, " ").sub(/\+.*/, "")
+          msg = entry["message"]
+          cls = entry["exception_class"]
+          ctrl = entry["controller"]
+
+          line_out = "[#{level}] #{ts}"
+          line_out += " #{cls}:" if cls.present?
+          line_out += " #{msg}"
+          line_out += " [#{ctrl["class"]}##{ctrl["action"]}]" if ctrl.present?
+
+          puts line_out
+        rescue JSON::ParserError
+          puts line
+        end
+      end
+    end
+  end
+
+  desc "Export exceptions to JSON"
+  task export: :environment do
+    require "json"
+
+    output_file = ENV.fetch("OUTPUT", "rails_nexus_export.json")
+    since = ENV["SINCE"] ? Time.parse(ENV["SINCE"]) : nil
+
+    scope = RailsNexus::LoggedException.order(created_at: :desc)
+    scope = scope.where("created_at >= ?", since) if since.present?
+
+    data = scope.map do |e|
+      {
+        id: e.id,
+        exception_class: e.exception_class,
+        controller_name: e.controller_name,
+        action_name: e.action_name,
+        message: e.message,
+        backtrace: e.backtrace,
+        environment: e.environment,
+        request: e.request,
+        user_info: e.user_info,
+        remote_ip: e.remote_ip,
+        user_agent: e.user_agent,
+        created_at: e.created_at.iso8601,
+        updated_at: e.updated_at.iso8601
+      }
+    end
+
+    File.write(output_file, JSON.pretty_generate(data))
+    puts "✓ Exported #{data.size} exceptions to #{output_file}"
+  end
+
+  desc "Test webhook configuration"
+  task test_webhook: :environment do
+    require "rails_nexus/notifications"
+
+    config = RailsNexus.configuration
+    if config.webhooks.empty?
+      puts "⚠ No webhooks configured. Set config.webhooks in your initializer."
+      next
+    end
+
+    puts "Testing webhooks..."
+    config.webhooks.each do |url|
+      print "  #{url}... "
+      begin
+        uri = URI(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = 5
+        http.read_timeout = 5
+
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
+        config.webhook_headers.each { |k, v| request[k] = v }
+        request.body = { event: "test", message: "RailsNexus webhook test", timestamp: Time.current.iso8601 }.to_json
+
+        response = http.request(request)
+        if response.is_a?(Net::HTTPSuccess)
+          puts "✓ (#{response.code})"
+        else
+          puts "✗ (#{response.code} #{response.message})"
+        end
+      rescue StandardError => e
+        puts "✗ (#{e.message})"
+      end
+    end
+  end
+end
+
+namespace :rails_nexus do
+  desc "Run a task with cron job tracking"
+  task :cron, [:task_name] => :environment do |_t, args|
+    task_name = args[:task_name] || "unnamed_task"
+    job = nil
+
+    begin
+      job = RailsNexus::CronJob.start!(task_name)
+      puts "⚡ Starting cron job: #{task_name} (ID: #{job.id})"
+
+      job.succeed!(output: "Completed successfully")
+      puts "✓ Cron job completed: #{task_name} (#{job.duration.round(2)}s)"
+    rescue StandardError => e
+      job&.fail!(error: e.message)
+      puts "✗ Cron job failed: #{task_name} — #{e.message}"
+      raise e
+    end
+  end
+
+  desc "Wrap a rake task with RailsNexus cron tracking"
+  task :wrap_cron, [:task_name] => :environment do |_t, args|
+    task_name = args[:task_name]
+    if task_name.blank?
+      puts "Usage: rake rails_nexus:wrap_cron[rake:task:name]"
+      next
+    end
+
+    job = nil
+    begin
+      job = RailsNexus::CronJob.start!(task_name)
+      puts "⚡ Starting tracked task: #{task_name}"
+
+      Rake::Task[task_name].invoke
+
+      job.succeed!(output: "Completed successfully")
+      puts "✓ Task completed: #{task_name} (#{job.duration.round(2)}s)"
+    rescue StandardError => e
+      job&.fail!(error: e.message)
+      puts "✗ Task failed: #{task_name} — #{e.message}"
+      raise e
+    end
+  end
+
+  desc "Show cron job statistics"
+  task cron_stats: :environment do
+    stats = RailsNexus::CronJob.summary
+
+    puts ""
+    puts "  ⏰ Cron Job Statistics"
+    puts "  ─────────────────────────────────────"
+    puts "  Total runs:      #{stats[:total]}"
+    puts "  Successful:      #{stats[:successful]}"
+    puts "  Failed:          #{stats[:failed]}"
+    puts "  Running:         #{stats[:running]}"
+    puts "  Failure rate:    #{stats[:failure_rate]}%"
+    puts ""
+
+    if stats[:last_run]
+      last = stats[:last_run]
+      puts "  Last run:"
+      puts "    Name:     #{last.name}"
+      puts "    Status:   #{last.status}"
+      puts "    Time:     #{last.created_at}"
+      puts "    Duration: #{last.duration&.round(2)}s"
+      puts ""
+    end
+  end
+
+  desc "Clean up old cron job records (default: 30 days)"
+  task :cron_cleanup, [:days] => :environment do |_t, args|
+    days = (args[:days] || 30).to_i
+    count = RailsNexus::CronJob.where("created_at < ?", days.days.ago).delete_all
+    puts "✓ Deleted #{count} cron job records older than #{days} days"
+  end
+
+  desc "Clean up old webhook delivery records (default: 30 days)"
+  task :webhook_cleanup, [:days] => :environment do |_t, args|
+    days = (args[:days] || 30).to_i
+    count = RailsNexus::WebhookDelivery.where("created_at < ?", days.days.ago).delete_all
+    puts "✓ Deleted #{count} webhook delivery records older than #{days} days"
+  end
+end

data/lib/tasks/rails_nexus_tasks.rake

@@ -0,0 +1,37 @@
+namespace :rails_nexus do
+  namespace :tailwind do
+    desc "Generate Tailwind v4 @source entries for RailsNexus views/helpers (OUT=app/assets/stylesheets/_rails_nexus_sources.css ENTRY=app/assets/stylesheets/application.tailwind.css)"
+    task sources: :environment do
+      root = RailsNexus::Engine.root
+      out = ENV["OUT"] || "app/assets/stylesheets/_rails_nexus_sources.css"
+
+      content = <<~CSS
+        /* Generated by bin/rails rails_nexus:tailwind:sources - do not edit. Re-run after gem updates or on new machines/containers. */
+        @source "#{root}/app/views/**/*.erb";
+        @source "#{root}/app/helpers/**/*.rb";
+      CSS
+
+      FileUtils.mkdir_p(File.dirname(out))
+      File.write(out, content)
+      puts "Wrote #{out}"
+
+      entry = ENV["ENTRY"]
+      entry ||= "app/assets/stylesheets/application.tailwind.css" if File.exist?("app/assets/stylesheets/application.tailwind.css")
+
+      if entry && File.file?(entry)
+        import_line = "@import \"./#{File.basename(out)}\";"
+        body = File.read(entry)
+
+        if body.include?(File.basename(out))
+          puts "#{entry} already imports #{File.basename(out)}"
+        else
+          File.write(entry, body.sub(/\A/, "#{import_line}\n"))
+          puts "Added #{import_line} to #{entry}"
+        end
+      elsif !entry
+        puts "Add this to your Tailwind entry stylesheet:"
+        puts "  @import \"./#{File.basename(out)}\";"
+      end
+    end
+  end
+end

data/rails_nexus.gemspec

@@ -0,0 +1,36 @@
+require_relative "lib/rails_nexus/version"
+
+Gem::Specification.new do |spec|
+  spec.name        = "rails_nexus"
+  spec.version     = RailsNexus::VERSION
+  spec.authors     = ["Tamiru Hailu"]
+  spec.email       = ["tamiruhailu@gmail.com"]
+  spec.homepage    = "https://github.com/tamiru/rails_nexus"
+  spec.summary     = "The extensible control plane for Rails applications"
+  spec.description = "RailsNexus is an extensible operations and administration console for Rails applications. It provides error monitoring, backup management, cron job tracking, server statistics, database health, real-time analytics, workflow management, source code viewing, N+1 query detection, and storm protection. Built with Hotwire, Stimulus, and Tailwind-compatible CSS."
+  spec.metadata["rubygems_mfa_required"] = "true"
+  spec.license     = "MIT"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/tamiru/rails_nexus/tree/main"
+  spec.metadata["changelog_uri"] = "https://github.com/tamiru/rails_nexus/blob/main/CHANGELOG.md"
+  spec.metadata["funding_uri"] = "https://github.com/sponsors/tamiru"
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir["{app,config,db,lib}/**/*", "MIT-LICENSE", "Rakefile", "README.md", "rails_nexus.gemspec"]
+  end
+
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.add_dependency "rails", "~> 8.0", ">= 8.0.0"
+  spec.add_dependency "stimulus-rails", "~> 1.3"
+  spec.add_dependency "turbo-rails", "~> 2.0"
+  spec.add_dependency "importmap-rails", "~> 2.0"
+  spec.add_dependency "pagy", "~> 6.5"
+
+  spec.add_dependency "ransack", "~> 4.0"
+
+  # Note: Backup management requires 'backup' (~> 4.4) and 'whenever' (~> 1.1)
+  # gems to be added to your host application's Gemfile.
+end