solid_queue_guard 0.5.0 → 1.0.1

data/lib/solid_queue_guard/checks/runtime/puma_plugin_runtime_check.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Runtime
+      class PumaPluginRuntimeCheck < Base
+        def call
+          return skip(check_id, 'Solid Queue Puma plugin is not enabled') unless PumaPluginSupport.puma_plugin_enabled?
+
+          with_queue_database do
+            threshold = config.check_setting(:puma_plugin_runtime, :threshold, config.stale_process_threshold)
+            active = SolidQueue::Process.where(last_heartbeat_at: threshold.ago..)
+
+            if active.any?
+              pass(
+                check_id,
+                "Solid Queue processes are active via Puma plugin (#{active.count} process(es))",
+                metadata: { active_processes: active.count, supervisor_mode: supervisor_mode_label }
+              )
+            else
+              failure(
+                check_id,
+                'Solid Queue Puma plugin is enabled but no active processes were found',
+                suggestion: 'Verify the Puma plugin booted Solid Queue and workers are processing jobs',
+                metadata: { supervisor_mode: supervisor_mode_label }
+              )
+            end
+          end
+        end
+
+        private
+
+        def supervisor_mode_label
+          PumaPluginSupport.async_supervisor_mode? ? 'async' : 'fork'
+        end
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/checks/runtime/recurring_stale_check.rb

@@ -29,7 +29,7 @@ module SolidQueueGuard
         private
 
         def expected_staleness
-          config.stale_process_threshold * 2
+          config.check_setting(:recurring_stale, :threshold, config.stale_process_threshold * 2)
         end
       end
     end

data/lib/solid_queue_guard/checks/runtime/scheduled_backlog_check.rb

@@ -7,7 +7,7 @@ module SolidQueueGuard
         def call
           with_queue_database do
             due_count = SolidQueue::ScheduledExecution.due.count
-            threshold = config.scheduled_backlog_threshold
+            threshold = config.check_setting(:scheduled_backlog, :threshold, config.scheduled_backlog_threshold)
 
             if due_count > threshold
               warn(

data/lib/solid_queue_guard/checks/runtime/stale_process_check.rb

@@ -6,7 +6,7 @@ module SolidQueueGuard
       class StaleProcessCheck < Base
         def call
           with_queue_database do
-            threshold = config.stale_process_threshold
+            threshold = config.check_setting(:stale_process, :threshold, config.stale_process_threshold)
             stale = SolidQueue::Process.where(last_heartbeat_at: ...threshold.ago)
 
             if stale.none?

data/lib/solid_queue_guard/configuration.rb

@@ -12,7 +12,11 @@ module SolidQueueGuard
                   :scheduled_backlog_threshold,
                   :integrate_rails_health,
                   :notify_with,
-                  :metrics_backends
+                  :metrics_backends,
+                  :disabled_checks,
+                  :checks,
+                  :degraded_http_status,
+                  :unhealthy_http_status
 
     def initialize
       @enabled = true
@@ -26,10 +30,39 @@ module SolidQueueGuard
       @integrate_rails_health = false
       @notify_with = [:rails_logger]
       @metrics_backends = []
+      @disabled_checks = []
+      @checks = ActiveSupport::OrderedOptions.new
+      @degraded_http_status = :ok
+      @unhealthy_http_status = :service_unavailable
     end
 
     def strict?
       strict_mode || ActiveModel::Type::Boolean.new.cast(ENV.fetch('SOLID_QUEUE_GUARD_STRICT', nil))
     end
+
+    def check_enabled?(check_id)
+      id = check_id.to_sym
+      return false if disabled_checks.map(&:to_sym).include?(id)
+
+      settings = check_settings_for(id)
+      return true if settings.nil?
+
+      enabled_value = settings[:enabled]
+      enabled_value = settings['enabled'] if enabled_value.nil?
+      enabled_value != false
+    end
+
+    def check_settings_for(check_id)
+      checks[check_id.to_sym] || checks[check_id.to_s]
+    end
+
+    def check_setting(check_id, key, default = nil)
+      settings = check_settings_for(check_id)
+      return default unless settings
+
+      value = settings[key]
+      value = settings[key.to_sym] if value.nil?
+      value.nil? ? default : value
+    end
   end
 end

data/lib/solid_queue_guard/http_status_policy.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  # @api private
+  module HttpStatusPolicy
+    module_function
+
+    STATUS_MAP = {
+      ok: :ok,
+      success: :ok,
+      200 => :ok,
+      multi_status: :multi_status,
+      207 => :multi_status,
+      service_unavailable: :service_unavailable,
+      unavailable: :service_unavailable,
+      503 => :service_unavailable
+    }.freeze
+
+    def resolve(status)
+      key = status.is_a?(Integer) ? status : status.to_sym
+      STATUS_MAP.fetch(key, :ok)
+    end
+
+    def for_report_status(report_status, config: SolidQueueGuard.config)
+      case report_status.to_s
+      when 'unhealthy'
+        resolve(config.unhealthy_http_status)
+      when 'degraded'
+        resolve(config.degraded_http_status)
+      else
+        :ok
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/puma_plugin_support.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  # @api private
+  module PumaPluginSupport
+    module_function
+
+    PUMA_PLUGIN_PATTERN = /plugin\s+:?solid_queue/
+    ASYNC_MODE_PATTERN = /solid_queue_mode\s+:?async/
+
+    def puma_config_path
+      Rails.root.join('config/puma.rb')
+    end
+
+    def puma_config_content
+      return unless puma_config_path.exist?
+
+      puma_config_path.read
+    end
+
+    def puma_plugin_enabled?
+      content = puma_config_content
+      content.present? && content.match?(PUMA_PLUGIN_PATTERN)
+    end
+
+    def puma_async_mode?
+      content = puma_config_content
+      content.present? && content.match?(ASYNC_MODE_PATTERN)
+    end
+
+    def async_supervisor_mode?
+      ENV.fetch('SOLID_QUEUE_SUPERVISOR_MODE', 'fork').casecmp('async').zero? || puma_async_mode?
+    end
+  end
+end

data/lib/solid_queue_guard/recommendations/topology.rb

@@ -31,6 +31,8 @@ module SolidQueueGuard
       end
 
       def pool_recommendations
+        return async_pool_recommendation if PumaPluginSupport.async_supervisor_mode?
+
         required_threads = configuration.estimated_number_of_threads
         pool_size = SolidQueue::Record.connection_pool&.size
         return [] if pool_size.nil? || required_threads <= pool_size
@@ -58,6 +60,17 @@ module SolidQueueGuard
       rescue StandardError
         false
       end
+
+      def async_pool_recommendation
+        required_threads = configuration.estimated_number_of_threads
+        pool_size = SolidQueue::Record.connection_pool&.size
+        return [] if pool_size.nil? || required_threads <= pool_size
+
+        ["Increase queue DB pool to at least #{required_threads + 2} " \
+         "for async supervisor mode (currently #{pool_size})"]
+      rescue StandardError
+        []
+      end
     end
   end
 end

data/lib/solid_queue_guard/runner.rb

@@ -27,10 +27,19 @@ module SolidQueueGuard
     end
 
     def run_check(check_class)
+      check_id = Checks::Registry.check_id_for(check_class)
+      unless SolidQueueGuard.config.check_enabled?(check_id)
+        return Check::Result.new(
+          id: check_id,
+          status: :skip,
+          message: 'Check disabled via configuration'
+        )
+      end
+
       check_class.call
     rescue StandardError => e
       Check::Result.new(
-        id: check_class.name.demodulize.underscore,
+        id: check_id,
         status: :fail,
         message: "Check raised an error: #{e.class}: #{e.message}"
       )

data/lib/solid_queue_guard/schema/solid_queue_tables.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Schema
+    # @api private
+    class SolidQueueTables
+      SCHEMA_FILES = %w[
+        db/queue_schema.rb
+        db/schema.rb
+        db/structure.sql
+      ].freeze
+
+      RUBY_CREATE_TABLE_PATTERN = /
+        create_table
+        \s+
+        (?:
+          ["'](?<quoted>solid_queue_[a-z_]+)["']
+          |
+          :(?<symbol>solid_queue_[a-z_]+)
+        )
+      /ix
+
+      SQL_CREATE_TABLE_PATTERN = /
+        CREATE \ TABLE
+        (?: \ IF \ NOT \ EXISTS )?
+        \s+
+        (?:[\w.]+\.)?
+        (?:
+          "(?<quoted>solid_queue_[a-z_]+)"
+          |
+          (?<unquoted>solid_queue_[a-z_]+)
+        )
+      /ix
+
+      class << self
+        def required_tables
+          @required_tables ||= tables_from_gem_template || default_required_tables
+        end
+
+        def detected_tables(rails_root: Rails.root)
+          file_tables = {}
+          tables = Set.new
+
+          SCHEMA_FILES.each do |relative_path|
+            path = rails_root.join(relative_path)
+            next unless path.exist?
+
+            tables_in_file = parse_file(path)
+            next if tables_in_file.empty?
+
+            file_tables[relative_path] = tables_in_file.sort
+            tables.merge(tables_in_file)
+          end
+
+          database_tables = tables_in_queue_database
+          tables.merge(database_tables)
+
+          {
+            tables: tables.sort,
+            file_tables: file_tables,
+            database_tables: database_tables.sort
+          }
+        end
+
+        def missing_tables(rails_root: Rails.root)
+          required_tables - detected_tables(rails_root: rails_root)[:tables]
+        end
+
+        def tables_from_gem_template
+          spec = Gem.loaded_specs['solid_queue']
+          return nil unless spec
+
+          template = File.join(
+            spec.full_gem_path,
+            'lib/generators/solid_queue/install/templates/db/queue_schema.rb'
+          )
+          return nil unless File.exist?(template)
+
+          parse_ruby_schema(File.read(template))
+        end
+
+        def default_required_tables
+          %w[
+            solid_queue_blocked_executions
+            solid_queue_claimed_executions
+            solid_queue_failed_executions
+            solid_queue_jobs
+            solid_queue_pauses
+            solid_queue_processes
+            solid_queue_ready_executions
+            solid_queue_recurring_executions
+            solid_queue_recurring_tasks
+            solid_queue_scheduled_executions
+            solid_queue_semaphores
+          ].freeze
+        end
+
+        private
+
+        def parse_file(path)
+          content = path.read
+          path.extname == '.sql' ? parse_sql_schema(content) : parse_ruby_schema(content)
+        end
+
+        def parse_ruby_schema(content)
+          content.scan(RUBY_CREATE_TABLE_PATTERN).flatten.compact.uniq
+        end
+
+        def parse_sql_schema(content)
+          content.scan(SQL_CREATE_TABLE_PATTERN).flatten.compact.uniq
+        end
+
+        def tables_in_queue_database
+          return [] unless defined?(SolidQueue::Record)
+
+          pool = SolidQueue::Record.connection_pool
+          return [] unless pool&.with_connection(&:active?)
+
+          SolidQueue::Record.connection.tables.grep(/\Asolid_queue_/)
+        rescue StandardError
+          []
+        end
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SolidQueueGuard
-  VERSION = '0.5.0'
+  VERSION = '1.0.1'
 end

data/lib/solid_queue_guard.rb

@@ -18,7 +18,7 @@ module SolidQueueGuard
     attr_accessor :configuration
 
     def deprecator
-      @deprecator ||= ActiveSupport::Deprecation.new('0.2', 'SolidQueueGuard')
+      @deprecator ||= ActiveSupport::Deprecation.new('2.0', 'SolidQueueGuard')
     end
 
     def configure

data/solid_queue_guard.gemspec

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative 'lib/solid_queue_guard/version'
+
+Gem::Specification.new do |spec|
+  spec.name        = 'solid_queue_guard'
+  spec.version     = SolidQueueGuard::VERSION
+  spec.authors     = ['Rafael Pissardo']
+  spec.email       = ['rpissardo@users.noreply.github.com']
+  spec.homepage    = 'https://github.com/rafael-pissardo/solid_queue_guard'
+  spec.summary     = 'Production readiness checks and runtime guards for Rails Solid Queue.'
+  spec.description = [
+    'Detect queue lag, dead workers, unsafe thread/pool configuration,',
+    'and broken recurring jobs before they become incidents.'
+  ].join(' ')
+  spec.license = 'MIT'
+
+  spec.metadata = {
+    'homepage_uri' => spec.homepage,
+    'source_code_uri' => 'https://github.com/rafael-pissardo/solid_queue_guard',
+    'changelog_uri' => 'https://github.com/rafael-pissardo/solid_queue_guard/blob/main/CHANGELOG.md',
+    'bug_tracker_uri' => 'https://github.com/rafael-pissardo/solid_queue_guard/issues',
+    'documentation_uri' => 'https://github.com/rafael-pissardo/solid_queue_guard#readme',
+    'rubygems_mfa_required' => 'true'
+  }
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |file|
+      file.start_with?('test/', '.github/', 'docs/', 'script/', 'gemfiles/', 'Appraisals')
+    end
+  end
+
+  spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 3.1'
+
+  rails_version = '>= 7.1', '< 9.0'
+
+  spec.add_dependency 'actionpack', rails_version
+  spec.add_dependency 'activejob', rails_version
+  spec.add_dependency 'activerecord', rails_version
+  spec.add_dependency 'activesupport', rails_version
+  spec.add_dependency 'railties', rails_version
+  spec.add_dependency 'solid_queue', '>= 1.0', '< 2.0'
+
+  spec.add_development_dependency 'appraisal', '~> 2.5'
+  spec.add_development_dependency 'debug'
+  spec.add_development_dependency 'minitest', '~> 5.0'
+  spec.add_development_dependency 'mocha', '>= 2.1'
+  spec.add_development_dependency 'puma', '>= 6.0'
+  spec.add_development_dependency 'rails', rails_version
+  spec.add_development_dependency 'rubocop', '~> 1.75'
+  spec.add_development_dependency 'rubocop-rails', '~> 2.30'
+  spec.add_development_dependency 'sqlite3', '~> 2.1'
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solid_queue_guard
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Rafael Pissardo
@@ -269,6 +269,12 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".gitignore"
+- ".rubocop.yml"
+- ".ruby-version"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
 - MIT-LICENSE
 - README.md
 - Rakefile
@@ -276,12 +282,16 @@ files:
 - app/controllers/solid_queue_guard/health_controller.rb
 - config/routes.rb
 - lib/generators/solid_queue_guard/install/USAGE
+- lib/generators/solid_queue_guard/install/USAGE.ci
+- lib/generators/solid_queue_guard/install/ci_generator.rb
 - lib/generators/solid_queue_guard/install/install_generator.rb
 - lib/generators/solid_queue_guard/install/templates/solid_queue_guard.rb
+- lib/generators/solid_queue_guard/install/templates/solid_queue_guard.yml
 - lib/solid_queue_guard.rb
 - lib/solid_queue_guard/check/result.rb
 - lib/solid_queue_guard/checks/base.rb
 - lib/solid_queue_guard/checks/config/adapter_check.rb
+- lib/solid_queue_guard/checks/config/async_supervisor_config_check.rb
 - lib/solid_queue_guard/checks/config/connects_to_check.rb
 - lib/solid_queue_guard/checks/config/env_flags_check.rb
 - lib/solid_queue_guard/checks/config/process_heartbeat_config_check.rb
@@ -303,6 +313,7 @@ files:
 - lib/solid_queue_guard/checks/runtime/paused_queue_lag_check.rb
 - lib/solid_queue_guard/checks/runtime/pidfile_check.rb
 - lib/solid_queue_guard/checks/runtime/process_topology_check.rb
+- lib/solid_queue_guard/checks/runtime/puma_plugin_runtime_check.rb
 - lib/solid_queue_guard/checks/runtime/queue_lag_check.rb
 - lib/solid_queue_guard/checks/runtime/recurring_stale_check.rb
 - lib/solid_queue_guard/checks/runtime/scheduled_backlog_check.rb
@@ -314,18 +325,22 @@ files:
 - lib/solid_queue_guard/formatters/terminal.rb
 - lib/solid_queue_guard/health/cache.rb
 - lib/solid_queue_guard/health/payload.rb
+- lib/solid_queue_guard/http_status_policy.rb
 - lib/solid_queue_guard/metrics/exporter.rb
 - lib/solid_queue_guard/metrics/open_telemetry.rb
 - lib/solid_queue_guard/metrics/prometheus.rb
 - lib/solid_queue_guard/metrics/statsd.rb
 - lib/solid_queue_guard/notifier.rb
 - lib/solid_queue_guard/notifiers/base.rb
+- lib/solid_queue_guard/puma_plugin_support.rb
 - lib/solid_queue_guard/queue_coverage.rb
 - lib/solid_queue_guard/recommendations/topology.rb
 - lib/solid_queue_guard/report.rb
 - lib/solid_queue_guard/runner.rb
+- lib/solid_queue_guard/schema/solid_queue_tables.rb
 - lib/solid_queue_guard/tasks.rb
 - lib/solid_queue_guard/version.rb
+- solid_queue_guard.gemspec
 homepage: https://github.com/rafael-pissardo/solid_queue_guard
 licenses:
 - MIT