solid_queue_guard 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bd60b98c25c507b3069f98b6b69282f627a398e96bd43d7a5d0713f0499c8610
+  data.tar.gz: c60a8995c311f4935456f58ca950e1d4cdb4b7e601dc1e6290f62f9d06931cb0
+SHA512:
+  metadata.gz: ac5fbbb57df0cb133466076f0c4c1b698a13004b3f44e22bc64139e04e8c4bb51973a22e534ff0617329709a154a92a7a93ac9e083ea0087d86dadc73c6e89cf
+  data.tar.gz: b16bc3883213b26928b0cfa2c4d0b355ce43bd956a4c3df27e4cad4f8f71534748a15e5f9c892190a018741df8c9f1fbe4aaaa577e960f4e39a2a28c00a823ed

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rafael Pissardo
+
+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.

data/README.md

@@ -0,0 +1,258 @@
+# solid_queue_guard
+
+**Production readiness checks and runtime guards for Rails Solid Queue.**
+
+[![Gem Version](https://img.shields.io/gem/v/solid_queue_guard)](https://rubygems.org/gems/solid_queue_guard)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](MIT-LICENSE)
+
+Rails 8 ships with [Solid Queue](https://github.com/rails/solid_queue). Redis is optional. Production config is not.
+
+Your web tier can be **green** while your jobs are **dead**. Your queue can look **empty** while scheduled work is **stuck**. Your `queue.yml` can declare **10 threads** against a database pool of **5**.
+
+**solid_queue_guard** catches that *before* it becomes a 3am incident.
+
+> **Mission Control** shows what is happening.  
+> **solid_queue_guard** warns what is dangerous.
+
+---
+
+## Why this exists
+
+Solid Queue is excellent. Operating it blindly is not.
+
+| Symptom | What actually happened |
+| ------- | ---------------------- |
+| "Site is up, emails stopped" | Workers dead, heartbeats stale |
+| "Only 3 jobs in the queue, why the panic?" | Oldest job waiting 40 minutes — **lag**, not depth |
+| "Recurring billing just… stopped" | Scheduler not running, nobody noticed for a week |
+| "Jobs hang after deploy" | Thread count > DB pool — connection starvation |
+| "Health check passes, jobs don't" | `/up` doesn't know Solid Queue exists |
+
+You don't need another dashboard. You need a **doctor**.
+
+---
+
+## See it in action
+
+```bash
+bundle add solid_queue_guard
+bin/rails solid_queue_guard:install
+bin/rails solid_queue_guard:doctor
+```
+
+```text
+SolidQueueGuard Report
+
+Status: DEGRADED
+
+Checks:
+✅ Active Job adapter is :solid_queue
+✅ Queue database configured in database.yml
+✅ Solid Queue connects_to queue database (pool: 10)
+✅ db/queue_schema.rb exists
+❌ Worker threads: 10, queue DB pool: 5
+⚠️ No workers configured for "mailers" queue
+⚠️ recurring.yml exists but scheduler may not run
+✅ Solid Queue is not co-located with Puma
+
+Suggested fixes:
+- Increase queue DB pool to at least 12 or reduce worker threads
+- Add a worker for the mailers queue
+- Verify scheduler process is running in production
+```
+
+One command. Actionable output. No Datadog required to get started.
+
+---
+
+## What it checks
+
+### v0.1 — Configuration doctor (available now)
+
+Runs locally, in CI, or pre-deploy. **No extra infrastructure.**
+
+| Check | Catches |
+| ----- | ------- |
+| **Adapter** | Active Job not set to `:solid_queue` |
+| **Queue database** | Missing `queue` entry in `database.yml` |
+| **connects_to** | Solid Queue pointing at the wrong DB / pool |
+| **Queue schema** | Missing `db/queue_schema.rb` |
+| **Thread pool** | `threads` > available queue DB connections |
+| **Worker coverage** | Queues with no worker assigned |
+| **Scheduler** | `recurring.yml` tasks without a scheduler |
+| **Env flags** | `SOLID_QUEUE_SKIP_RECURRING=true` in production |
+| **Heartbeats** | Default thresholds that may not fit your deploy |
+| **Puma plugin** | Solid Queue co-located with web in production |
+
+### v0.2+ — Runtime guards (roadmap)
+
+| Check | Catches |
+| ----- | ------- |
+| **Queue lag** | Oldest ready job waiting too long |
+| **Stale processes** | Dead workers, dispatchers, schedulers |
+| **Dispatcher health** | Scheduled jobs never becoming ready |
+| **Blocked jobs** | Concurrency control silently holding jobs |
+| **Recurring staleness** | Cron tasks that stopped firing |
+| **HTTP `/health`** | Kamal, ECS, K8s, UptimeRobot integration |
+
+---
+
+## Quick start
+
+### Install
+
+```bash
+bundle add solid_queue_guard
+bin/rails solid_queue_guard:install
+```
+
+### Run the doctor
+
+```bash
+# Human-readable report
+bin/rails solid_queue_guard:doctor
+
+# JSON for scripts / CI
+bin/rails "solid_queue_guard:doctor[json]"
+SOLID_QUEUE_GUARD_FORMAT=json bin/rails solid_queue_guard:doctor
+
+# Fail CI on warnings too
+SOLID_QUEUE_GUARD_STRICT=1 bin/rails solid_queue_guard:doctor
+
+# Full report (config + runtime when available)
+bin/rails solid_queue_guard:report
+```
+
+### Exit codes
+
+| Code | Meaning |
+| ---- | ------- |
+| `0` | Healthy or degraded |
+| `1` | Unhealthy (or degraded in `--strict` / `SOLID_QUEUE_GUARD_STRICT=1`) |
+
+Perfect for deploy pipelines:
+
+```yaml
+# GitHub Actions
+- name: Solid Queue production readiness
+  run: SOLID_QUEUE_GUARD_STRICT=1 bin/rails solid_queue_guard:doctor
+```
+
+### HTTP health (v0.2)
+
+```ruby
+# config/routes.rb
+mount SolidQueueGuard::Engine, at: "/solid_queue_guard"
+```
+
+```bash
+curl localhost:3000/solid_queue_guard/health
+# => { "status": "degraded", "queue_lag_seconds": 245, "warnings": [...] }
+```
+
+Works with **Kamal**, **Heroku**, **Fly.io**, **ECS/Fargate**, **Kubernetes**, **Better Stack**, **UptimeRobot**.
+
+---
+
+## Configuration
+
+```ruby
+# config/initializers/solid_queue_guard.rb
+SolidQueueGuard.configure do |config|
+  config.enabled = Rails.env.production?
+
+  config.queue_lag_thresholds = {
+    critical: 30.seconds,
+    default:  5.minutes,
+    mailers:  15.minutes
+  }
+
+  config.failed_jobs_threshold = 20
+  config.stale_process_threshold = 5.minutes
+
+  # config.health_token = ENV["SOLID_QUEUE_GUARD_TOKEN"]  # v0.2
+  # config.notify_with = [:rails_logger, :slack]          # v0.3
+end
+```
+
+---
+
+## solid_queue_guard vs Mission Control
+
+| | [Mission Control — Jobs](https://github.com/rails/mission_control-jobs) | solid_queue_guard |
+| --- | --- | --- |
+| **Purpose** | Inspect & manage jobs | Detect production risk |
+| **UI** | Dashboard | CLI + JSON + health endpoint |
+| **Retry / discard** | Yes | No (use Mission Control) |
+| **Config doctor** | No | Yes |
+| **Queue lag alerts** | No | Yes (v0.2) |
+| **Pre-deploy checks** | No | Yes |
+| **Recurring job guard** | Manual inspection | Automatic (v0.2) |
+
+**Use both.** They solve different problems.
+
+---
+
+## Roadmap
+
+| Version | Ships |
+| ------- | ----- |
+| **v0.1** | `doctor` — config checks, CI integration, install generator |
+| **v0.2** | Runtime health, queue lag, dispatcher/blocked jobs, HTTP endpoint |
+| **v0.3** | Slack, Datadog, webhook notifications |
+| **v0.4** | StatsD, Prometheus, OpenTelemetry metrics |
+| **v0.5** | Auto-recommendations for `queue.yml` topology |
+
+---
+
+## Compatibility
+
+| Gem version | Ruby | Rails |
+| ----------- | ---- | ----- |
+| 0.1.x       | 3.1+ | 7.1, 7.2, 8.0 |
+
+## Requirements
+
+- Ruby >= 3.1
+- Rails >= 7.1, < 9.0
+- [solid_queue](https://github.com/rails/solid_queue) >= 1.0, < 2.0
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/rafael-pissardo/solid_queue_guard.git
+cd solid_queue_guard
+bundle install
+cd test/dummy && bin/setup
+cd ../.. && bundle exec rake test
+bundle exec rubocop
+bundle exec appraisal install
+bundle exec appraisal rake test
+```
+
+---
+
+## Contributing
+
+Issues and PRs welcome. Keep it focused: **production safety**, not another job dashboard.
+
+1. Fork it
+2. Create your branch (`git checkout -b my-new-check`)
+3. Write a test first
+4. Make the check pass
+5. Open a PR
+
+---
+
+## License
+
+MIT — see [MIT-LICENSE](MIT-LICENSE).
+
+---
+
+<p align="center">
+  <strong>Run the doctor before you run the deploy.</strong><br>
+  <sub>Built for Rails teams who chose Solid Queue and still sleep at night.</sub>
+</p>

data/Rakefile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+APP_RAKEFILE = File.expand_path('test/dummy/Rakefile', __dir__)
+load 'rails/tasks/engine.rake'
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |task|
+  task.libs << 'test'
+  task.pattern = 'test/**/*_test.rb'
+end
+
+task default: :test

data/app/controllers/solid_queue_guard/application_controller.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/solid_queue_guard/health_controller.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  class HealthController < ApplicationController
+    def show
+      render json: { status: 'not_implemented', message: 'HTTP health checks ship in v0.2' }, status: :not_implemented
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+SolidQueueGuard::Engine.routes.draw do
+  get 'health', to: 'health#show'
+end

data/lib/generators/solid_queue_guard/install/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Installs Solid Queue Guard initializer with thresholds and feature flags.
+
+Usage:
+    bin/rails generate solid_queue_guard:install
+
+    This will create:
+        config/initializers/solid_queue_guard.rb

data/lib/generators/solid_queue_guard/install/install_generator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'rails/generators/base'
+
+module SolidQueueGuard
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates Solid Queue Guard initializer'
+
+      def copy_initializer
+        template 'solid_queue_guard.rb', 'config/initializers/solid_queue_guard.rb'
+      end
+    end
+  end
+end

data/lib/generators/solid_queue_guard/install/templates/solid_queue_guard.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+SolidQueueGuard.configure do |config|
+  config.enabled = Rails.env.production?
+
+  config.queue_lag_thresholds = {
+    critical: 30.seconds,
+    default: 5.minutes,
+    mailers: 15.minutes
+  }
+
+  config.failed_jobs_threshold = 20
+  config.stale_process_threshold = 5.minutes
+
+  # config.health_token = ENV["SOLID_QUEUE_GUARD_TOKEN"]
+  # config.notify_with = [ :rails_logger ]
+end

data/lib/solid_queue_guard/check/result.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Check
+    Result = Data.define(:id, :status, :message, :suggestion, :metadata) do
+      def initialize(id:, status:, message:, suggestion: nil, metadata: {})
+        super
+      end
+
+      def pass?
+        status == :pass
+      end
+
+      def warn?
+        status == :warn
+      end
+
+      def fail?
+        status == :fail
+      end
+
+      def skip?
+        status == :skip
+      end
+
+      def to_h
+        {
+          id: id,
+          status: status.to_s,
+          message: message,
+          suggestion: suggestion,
+          metadata: metadata
+        }.compact
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/checks/base.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    # @api private
+    class Base
+      def self.call(**options)
+        new(**options).call
+      end
+
+      def initialize(**options)
+        @options = options
+      end
+
+      def call
+        raise NotImplementedError
+      end
+
+      private
+
+      attr_reader :options
+
+      def pass(id, message, **kwargs)
+        build_result(id, :pass, message, **kwargs)
+      end
+
+      def warn(id, message, **kwargs)
+        build_result(id, :warn, message, **kwargs)
+      end
+
+      def failure(id, message, **kwargs)
+        build_result(id, :fail, message, **kwargs)
+      end
+
+      def skip(id, message, **kwargs)
+        build_result(id, :skip, message, **kwargs)
+      end
+
+      def build_result(id, status, message, suggestion: nil, metadata: {})
+        Check::Result.new(id: id, status: status, message: message, suggestion: suggestion, metadata: metadata)
+      end
+
+      def rails_root
+        Rails.root
+      end
+
+      def solid_queue_configuration
+        @solid_queue_configuration ||= SolidQueue::Configuration.new
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Config
+      class AdapterCheck < Base
+        def call
+          adapter = Rails.application.config.active_job.queue_adapter
+
+          if adapter.to_sym == :solid_queue
+            pass('adapter', 'Active Job adapter is :solid_queue')
+          else
+            failure(
+              'adapter',
+              "Active Job adapter is #{adapter.inspect}, expected :solid_queue",
+              suggestion: 'Set config.active_job.queue_adapter = :solid_queue'
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Config
+      class ConnectsToCheck < Base
+        def call
+          connects_to = Rails.application.config.solid_queue.connects_to
+
+          if connects_to.blank?
+            return failure(
+              'connects_to',
+              'config.solid_queue.connects_to is not configured',
+              suggestion: 'Set config.solid_queue.connects_to = { database: { writing: :queue } }'
+            )
+          end
+
+          writing = connects_to.dig(:database, :writing) || connects_to.dig('database', 'writing')
+
+          if writing.to_s != 'queue'
+            failure(
+              'connects_to',
+              "Solid Queue connects_to writing target is #{writing.inspect}, expected :queue",
+              suggestion: 'Point config.solid_queue.connects_to to the queue database'
+            )
+          elsif SolidQueue::Record.connection_pool.nil?
+            failure('connects_to', 'Solid Queue queue database connection pool is not available')
+          else
+            pass(
+              'connects_to',
+              "Solid Queue connects_to queue database (pool: #{SolidQueue::Record.connection_pool.size})"
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Config
+      class EnvFlagsCheck < Base
+        def call
+          if Rails.env.production? && ActiveModel::Type::Boolean.new.cast(ENV.fetch('SOLID_QUEUE_SKIP_RECURRING', nil))
+            warn(
+              'env_flags',
+              'SOLID_QUEUE_SKIP_RECURRING=true in production',
+              suggestion: 'Remove SOLID_QUEUE_SKIP_RECURRING unless recurring jobs are intentionally disabled'
+            )
+          else
+            pass('env_flags', 'No dangerous Solid Queue environment flags detected')
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Config
+      class ProcessHeartbeatConfigCheck < Base
+        DEFAULT_HEARTBEAT_INTERVAL = 60.seconds
+        DEFAULT_ALIVE_THRESHOLD = 5.minutes
+
+        def call
+          heartbeat_interval = SolidQueue.process_heartbeat_interval
+          alive_threshold = SolidQueue.process_alive_threshold
+
+          if heartbeat_interval == DEFAULT_HEARTBEAT_INTERVAL && alive_threshold == DEFAULT_ALIVE_THRESHOLD
+            warn(
+              'process_heartbeat_config',
+              'Process heartbeat thresholds use defaults (interval: 60s, alive: 5m)',
+              suggestion: 'Consider customizing process_alive_threshold for your deployment latency requirements'
+            )
+          else
+            pass(
+              'process_heartbeat_config',
+              "Process heartbeat interval: #{heartbeat_interval.inspect}, alive threshold: #{alive_threshold.inspect}"
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Config
+      class PumaColocatedCheck < Base
+        PUMA_PLUGIN_PATTERN = /plugin\s+:?solid_queue/
+
+        def call
+          puma_config = rails_root.join('config/puma.rb')
+
+          return pass('puma_colocated', 'No config/puma.rb found') unless puma_config.exist?
+
+          content = puma_config.read
+
+          if content.match?(PUMA_PLUGIN_PATTERN)
+            if Rails.env.production?
+              warn(
+                'puma_colocated',
+                'Solid Queue Puma plugin is enabled in production',
+                suggestion: 'Run Solid Queue in a dedicated job process for better isolation and memory management'
+              )
+            else
+              pass('puma_colocated', 'Solid Queue Puma plugin detected (non-production environment)')
+            end
+          else
+            pass('puma_colocated', 'Solid Queue is not co-located with Puma')
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Config
+      class QueueDatabaseCheck < Base
+        def call
+          config = Rails.application.config.database_configuration
+          env_config = config[Rails.env]
+
+          if env_config.is_a?(Hash) && env_config.key?('queue')
+            pass('queue_database', 'Queue database configured in database.yml')
+          else
+            failure(
+              'queue_database',
+              "No queue database entry in database.yml for #{Rails.env}",
+              suggestion: 'Add a queue database configuration for Solid Queue'
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Config
+      class QueueSchemaCheck < Base
+        def call
+          schema_path = rails_root.join('db/queue_schema.rb')
+
+          if schema_path.exist?
+            pass('queue_schema', 'db/queue_schema.rb exists')
+          else
+            warn(
+              'queue_schema',
+              'db/queue_schema.rb not found',
+              suggestion: 'Run bin/rails solid_queue:install to generate the queue schema'
+            )
+          end
+        end
+      end
+    end
+  end
+end