solid_queue_guard 0.1.0

data/lib/solid_queue_guard/checks/config/scheduler_config_check.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Config
+      class SchedulerConfigCheck < Base
+        def call
+          recurring_tasks = solid_queue_configuration.send(:recurring_tasks)
+          scheduler_expected = solid_queue_configuration.send(:schedulers).any?
+
+          return pass('scheduler_config', 'No recurring tasks configured') if recurring_tasks.empty?
+
+          if scheduler_expected
+            pass('scheduler_config', "Recurring scheduler is configured (#{recurring_tasks.size} tasks)")
+          elsif solid_queue_configuration.send(:skip_recurring_tasks?)
+            warn(
+              'scheduler_config',
+              'Recurring tasks defined but recurring execution is skipped',
+              suggestion: 'Unset SOLID_QUEUE_SKIP_RECURRING and ensure scheduler process runs'
+            )
+          else
+            failure(
+              'scheduler_config',
+              'recurring.yml defines scheduled tasks but no scheduler is configured',
+              suggestion: 'Ensure config/recurring.yml tasks have a :schedule key and scheduler is enabled'
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/checks/config/thread_pool_check.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Config
+      class ThreadPoolCheck < Base
+        def call
+          required_threads = solid_queue_configuration.send(:estimated_number_of_threads)
+          pool_size = SolidQueue::Record.connection_pool&.size
+
+          return skip('thread_pool', 'Queue database connection pool is not available') if pool_size.nil?
+
+          max_worker_threads = solid_queue_configuration.send(:workers_options)
+                                                        .map do |options|
+            options.fetch(
+              :threads, 3
+            )
+          end.max || 1
+
+          if pool_size >= required_threads
+            pass(
+              'thread_pool',
+              "Worker threads: #{max_worker_threads}, queue DB pool: #{pool_size}",
+              metadata: { threads: max_worker_threads, pool: pool_size, required: required_threads }
+            )
+          else
+            failure(
+              'thread_pool',
+              "Worker threads: #{max_worker_threads}, queue DB pool: #{pool_size}",
+              suggestion: "Increase queue DB pool to at least #{required_threads} or reduce worker threads",
+              metadata: { threads: max_worker_threads, pool: pool_size, required: required_threads }
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/checks/config/worker_coverage_check.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Config
+      class WorkerCoverageCheck < Base
+        def call
+          worker_queues = worker_queue_names
+          required_queues = queues_requiring_workers
+
+          uncovered = QueueCoverage.uncovered_queues(required_queues, worker_queues)
+
+          if uncovered.empty?
+            pass('worker_coverage', 'All required queues have worker coverage')
+          else
+            failure(
+              'worker_coverage',
+              "No workers configured for: #{uncovered.join(', ')}",
+              suggestion: "Add a worker for #{uncovered.join(', ')} in config/queue.yml",
+              metadata: { uncovered_queues: uncovered, worker_queues: worker_queues }
+            )
+          end
+        end
+
+        private
+
+        def worker_queue_names
+          QueueCoverage.worker_queues_from_configuration(solid_queue_configuration)
+        end
+
+        def queues_requiring_workers
+          (recurring_queues + database_queues).uniq
+        end
+
+        def recurring_queues
+          solid_queue_configuration.recurring_tasks.filter_map(&:queue_name).uniq
+        rescue StandardError
+          []
+        end
+
+        def database_queues
+          return [] unless SolidQueue::Record.connection_pool&.connected?
+
+          SolidQueue::Job.distinct.pluck(:queue_name)
+        rescue StandardError
+          []
+        end
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/checks/registry.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    # @api private
+    class Registry
+      CONFIG_CHECKS = [
+        Config::AdapterCheck,
+        Config::QueueDatabaseCheck,
+        Config::ConnectsToCheck,
+        Config::QueueSchemaCheck,
+        Config::ThreadPoolCheck,
+        Config::WorkerCoverageCheck,
+        Config::SchedulerConfigCheck,
+        Config::EnvFlagsCheck,
+        Config::ProcessHeartbeatConfigCheck,
+        Config::PumaColocatedCheck
+      ].freeze
+
+      RUNTIME_CHECKS = [
+        Runtime::QueueLagCheck,
+        Runtime::StaleProcessCheck,
+        Runtime::ProcessTopologyCheck,
+        Runtime::DispatcherCheck,
+        Runtime::ScheduledBacklogCheck,
+        Runtime::BlockedJobsCheck,
+        Runtime::OrphanedClaimsCheck,
+        Runtime::FailedJobsCheck,
+        Runtime::RecurringStaleCheck,
+        Runtime::PausedQueueLagCheck,
+        Runtime::PidfileCheck,
+        Runtime::FinishedJobsGrowthCheck
+      ].freeze
+
+      class << self
+        def for(scope)
+          case scope.to_sym
+          when :config then CONFIG_CHECKS
+          when :runtime then RUNTIME_CHECKS
+          when :all then CONFIG_CHECKS + RUNTIME_CHECKS
+          else
+            raise ArgumentError, "Unknown scope: #{scope}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Runtime
+      class Base < Checks::Base
+        NOT_IMPLEMENTED_MESSAGE = 'Runtime check not implemented until v0.2'
+
+        def call
+          skip(check_id, NOT_IMPLEMENTED_MESSAGE)
+        end
+
+        private
+
+        def check_id
+          self.class.name.demodulize.underscore.delete_suffix('_check')
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Runtime
+      class BlockedJobsCheck < Base; end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Runtime
+      class DispatcherCheck < Base; end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Runtime
+      class FailedJobsCheck < Base; end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Runtime
+      class FinishedJobsGrowthCheck < Base; end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Runtime
+      class OrphanedClaimsCheck < Base; end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Runtime
+      class PausedQueueLagCheck < Base; end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Runtime
+      class PidfileCheck < Base; end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Runtime
+      class ProcessTopologyCheck < Base; end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Runtime
+      class QueueLagCheck < Base; end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Runtime
+      class RecurringStaleCheck < Base; end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Runtime
+      class ScheduledBacklogCheck < Base; end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Runtime
+      class StaleProcessCheck < Base; end
+    end
+  end
+end

data/lib/solid_queue_guard/cli.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module CLI
+    module_function
+
+    def options(argv: ARGV)
+      {
+        strict: strict_flag?(argv),
+        format: format_flag(argv),
+        scope: scope_flag(argv)
+      }
+    end
+
+    def run!(scope: nil, format: nil, strict: nil, argv: ARGV)
+      scope ||= scope_flag(argv)
+      format ||= format_flag(argv)
+      strict = strict_flag?(argv) if strict.nil?
+
+      report = Runner.new(scope: scope).run
+      output = formatter_for(format).new(report).render
+
+      Rails.logger.debug output unless output.empty?
+
+      exit report.exit_code(strict: strict)
+    end
+
+    def formatter_for(format)
+      case format.to_sym
+      when :json then Formatters::Json
+      else Formatters::Terminal
+      end
+    end
+
+    def strict_flag?(argv)
+      SolidQueueGuard.config.strict? || argv.include?('--strict')
+    end
+
+    def format_flag(argv)
+      if (format_argument = argv.find { |argument| argument.start_with?('--format=') })
+        format_argument.split('=', 2).last.to_sym
+      else
+        ENV.fetch('SOLID_QUEUE_GUARD_FORMAT', 'text').to_sym
+      end
+    end
+
+    def scope_flag(argv)
+      if (scope_argument = argv.find { |argument| argument.start_with?('--scope=') })
+        scope_argument.split('=', 2).last.to_sym
+      else
+        ENV.fetch('SOLID_QUEUE_GUARD_SCOPE', 'config').to_sym
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/configuration.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  class Configuration
+    attr_accessor :enabled,
+                  :queue_lag_thresholds,
+                  :failed_jobs_threshold,
+                  :stale_process_threshold,
+                  :health_token,
+                  :strict_mode,
+                  :health_cache_ttl,
+                  :scheduled_backlog_threshold,
+                  :integrate_rails_health,
+                  :notify_with
+
+    def initialize
+      @enabled = true
+      @queue_lag_thresholds = { default: 5.minutes }
+      @failed_jobs_threshold = 20
+      @stale_process_threshold = 5.minutes
+      @health_token = nil
+      @strict_mode = false
+      @health_cache_ttl = 15.seconds
+      @scheduled_backlog_threshold = 100
+      @integrate_rails_health = false
+      @notify_with = [:rails_logger]
+    end
+
+    def strict?
+      strict_mode || ActiveModel::Type::Boolean.new.cast(ENV.fetch('SOLID_QUEUE_GUARD_STRICT', nil))
+    end
+  end
+end

data/lib/solid_queue_guard/engine.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  class Engine < ::Rails::Engine
+    isolate_namespace SolidQueueGuard
+
+    rake_tasks do
+      load 'solid_queue_guard/tasks.rb'
+    end
+
+    config.solid_queue_guard = ActiveSupport::OrderedOptions.new
+
+    initializer 'solid_queue_guard.config' do
+      SolidQueueGuard.configure do |guard_config|
+        config.solid_queue_guard.each do |name, value|
+          guard_config.public_send("#{name}=", value)
+        end
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/formatters/json.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Formatters
+    # @api private
+    class Json
+      def initialize(report)
+        @report = report
+      end
+
+      def render
+        JSON.pretty_generate(report.to_h)
+      end
+
+      private
+
+      attr_reader :report
+    end
+  end
+end

data/lib/solid_queue_guard/formatters/terminal.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Formatters
+    # @api private
+    class Terminal
+      ICONS = { pass: '✅', warn: '⚠️', fail: '❌', skip: '⏭️' }.freeze
+
+      def initialize(report)
+        @report = report
+      end
+
+      def render
+        [
+          'SolidQueueGuard Report',
+          '',
+          "Status: #{report.status.to_s.upcase}",
+          '',
+          'Checks:',
+          *check_lines,
+          *suggestion_lines
+        ].join("\n")
+      end
+
+      private
+
+      attr_reader :report
+
+      def check_lines
+        report.results.map do |result|
+          icon = ICONS.fetch(result.status, '•')
+          "#{icon} #{result.message}"
+        end
+      end
+
+      def suggestion_lines
+        return [] unless report.suggestions.any?
+
+        ['', 'Suggested fixes:', *report.suggestions.map { |suggestion| "- #{suggestion}" }]
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/notifiers/base.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Notifiers
+    # @api private
+    class Base
+      def self.deliver(_report)
+        raise NotImplementedError, 'Notification adapters ship in v0.3'
+      end
+    end
+
+    class RailsLogger < Base; end
+    class Slack < Base; end
+    class Datadog < Base; end
+    class Webhook < Base; end
+  end
+end

data/lib/solid_queue_guard/queue_coverage.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module QueueCoverage
+    module_function
+
+    def worker_queues_from_configuration(configuration = SolidQueue::Configuration.new)
+      configuration.configured_processes
+                   .select { |process| process.kind == :worker }
+                   .flat_map { |process| parse_queues_option(process.attributes[:queues]) }
+                   .uniq
+    end
+
+    def covers_all?(worker_queues, required_queue)
+      return true if worker_queues.include?('*')
+
+      worker_queues.include?(required_queue)
+    end
+
+    def uncovered_queues(required_queues, worker_queues)
+      required_queues.reject { |queue_name| covers_all?(worker_queues, queue_name) }
+    end
+
+    def parse_queues_option(value)
+      case value
+      when '*', nil
+        ['*']
+      when String
+        value.split(',').map(&:strip).reject(&:empty?)
+      when Array
+        value.map(&:to_s)
+      else
+        []
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/report.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  class Report
+    STATUSES = %i[healthy degraded unhealthy].freeze
+
+    attr_reader :results
+
+    def initialize(results)
+      @results = results
+    end
+
+    def status
+      return :unhealthy if results.any?(&:fail?)
+      return :degraded if results.any?(&:warn?)
+
+      :healthy
+    end
+
+    def warnings
+      results.select(&:warn?).map(&:message)
+    end
+
+    def suggestions
+      results.filter_map(&:suggestion).uniq
+    end
+
+    def exit_code(strict: false)
+      return 1 if results.any?(&:fail?)
+      return 1 if strict && results.any?(&:warn?)
+
+      0
+    end
+
+    def to_h
+      {
+        status: status.to_s,
+        warnings: warnings,
+        suggestions: suggestions,
+        checks: results.map(&:to_h)
+      }
+    end
+  end
+end

data/lib/solid_queue_guard/runner.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  # @api private
+  class Runner
+    def initialize(scope: :config, enabled: SolidQueueGuard.enabled?)
+      @scope = scope
+      @enabled = enabled
+    end
+
+    def run
+      return Report.new([disabled_result]) unless enabled
+
+      results = checks.map do |check_class|
+        run_check(check_class)
+      end
+
+      Report.new(results)
+    end
+
+    private
+
+    attr_reader :scope, :enabled
+
+    def checks
+      Checks::Registry.for(scope)
+    end
+
+    def run_check(check_class)
+      check_class.call
+    rescue StandardError => e
+      Check::Result.new(
+        id: check_class.name.demodulize.underscore,
+        status: :fail,
+        message: "Check raised an error: #{e.class}: #{e.message}"
+      )
+    end
+
+    def disabled_result
+      Check::Result.new(
+        id: 'disabled',
+        status: :skip,
+        message: 'SolidQueueGuard is disabled'
+      )
+    end
+  end
+end

data/lib/solid_queue_guard/tasks.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+namespace :solid_queue_guard do
+  desc 'Install Solid Queue Guard'
+  task install: :environment do
+    Rails::Command.invoke :generate, ['solid_queue_guard:install']
+  end
+
+  desc 'Run configuration and runtime diagnostics. Usage: doctor[json] or SOLID_QUEUE_GUARD_FORMAT=json'
+  task :doctor, [:format] => :environment do |_task, args|
+    SolidQueueGuard::CLI.run!(
+      scope: :config,
+      format: cli_format(args[:format]),
+      strict: cli_strict
+    )
+  end
+
+  desc 'Print machine-readable health status'
+  task health: :environment do
+    SolidQueueGuard::CLI.run!(scope: :config, format: :json, strict: cli_strict)
+  end
+
+  desc 'Print full diagnostic report. Usage: report[json]'
+  task :report, [:format] => :environment do |_task, args|
+    SolidQueueGuard::CLI.run!(
+      scope: :all,
+      format: cli_format(args[:format]),
+      strict: cli_strict
+    )
+  end
+
+  def cli_format(argument)
+    (argument.presence || ENV.fetch('SOLID_QUEUE_GUARD_FORMAT', 'text')).to_sym
+  end
+
+  def cli_strict
+    SolidQueueGuard.config.strict?
+  end
+end