solid_queue_guard 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 690433fe81ac90880ec7fdaa046b7638330eb879776e19343066732fd1f0f3e7
-  data.tar.gz: 6028bf63b80b0919158a10fb5771b8cdec74518be47b0882cfd39f893bbf10f7
+  metadata.gz: e4708571f815d3044a3aa1f952ffe250699e8b695972cf8449b38f53aa1ff4f3
+  data.tar.gz: ef314fa6328235a4e8d5174fe42db21a200ebb8ab067b2b6cda125b8a67b433a
 SHA512:
-  metadata.gz: 2d9bf3c79fbe0871ed9456eec1cefb22baf52f4949b128cc2a1f8d30dde4bb468bbece87752a33ea06a0e53d12ec25db65e1c1295205ac140643d9cf5dbfc769
-  data.tar.gz: 0d40a0805708376a56e243977772274a61f6e4a799ca3dfc64dfb362a46217e30258ba1758e1dda7bc3956f63e13895cde6814f446551b4bf271a07b24477e57
+  metadata.gz: 292e090e0c051b8f76d792070bfef73a33e4a21ba680f23319d85354b9de145fa1363dbd1b74efd19c3b23cf5833595b8bb45720ba19a9f41ae9a1497161fd19
+  data.tar.gz: 64b1b5b2a1d9e5535ba1170f1469cdf3ac693a9f358b4386fb22699c1ad03c37aabd49176b66ca2c51a0cd78c57d2f447c87581a6ee2450ebb1e317d80d6295d

data/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.1] - 2026-07-09
+
+### Changed
+
+- `QueueSchemaCheck` validates Solid Queue tables in `db/queue_schema.rb`, `db/schema.rb`, `db/structure.sql`, and the queue database instead of requiring `db/queue_schema.rb`
+- README documents operational usage: doctor, CI, HTTP health, and runtime process checks
+
 ## [1.0.0] - 2026-07-09
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    solid_queue_guard (1.0.0)
+    solid_queue_guard (1.0.1)
       actionpack (>= 7.1, < 9.0)
       activejob (>= 7.1, < 9.0)
       activerecord (>= 7.1, < 9.0)

data/README.md

@@ -49,7 +49,7 @@ 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
+✅ Solid Queue schema tables present
 ❌ Worker threads: 10, queue DB pool: 5
 ⚠️ No workers configured for "mailers" queue
 ⚠️ recurring.yml exists but scheduler may not run
@@ -76,7 +76,7 @@ Runs locally, in CI, or pre-deploy. **No extra infrastructure.**
 | **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` |
+| **Queue schema** | Missing Solid Queue tables in schema files or queue database |
 | **Thread pool** | `threads` > available queue DB connections |
 | **Worker coverage** | Queues with no worker assigned |
 | **Scheduler** | `recurring.yml` tasks without a scheduler |
@@ -178,6 +178,153 @@ Works with **Kamal**, **Heroku**, **Fly.io**, **ECS/Fargate**, **Kubernetes**, *
 
 ---
 
+## How to use it
+
+Solid Queue does not show up in Rails `/up`. **solid_queue_guard** gives you three operational surfaces:
+
+| Surface | Command / URL | Best for |
+| ------- | ------------- | -------- |
+| **Doctor** | `bin/rails solid_queue_guard:doctor` | Local pre-deploy, config review |
+| **CI gate** | `SOLID_QUEUE_GUARD_STRICT=1 bin/rails solid_queue_guard:doctor` | Block merges with broken queue config |
+| **HTTP health** | `GET /solid_queue_guard/health` | Production uptime monitors (Kamal, ECS, UptimeRobot) |
+
+**Mission Control** shows what is happening. **solid_queue_guard** warns what is dangerous. Use both.
+
+### Local and pre-deploy
+
+Run before changing `queue.yml`, `database.yml`, or recurring tasks:
+
+```bash
+bin/rails solid_queue_guard:doctor      # config checks (default scope)
+bin/rails solid_queue_guard:report      # config + runtime when the queue DB is available
+```
+
+By default the install generator sets `config.enabled = Rails.env.production?`, so in **development** checks are skipped unless you enable them:
+
+```ruby
+SolidQueueGuard.configure { |c| c.enabled = true }
+```
+
+Or run with production config locally when validating deploy readiness.
+
+### CI pipelines
+
+Validate **configuration** before deploy. Process/runtime checks usually **skip** in CI because there is no `bin/jobs` supervisor on the runner.
+
+```yaml
+- name: Solid Queue production readiness
+  run: SOLID_QUEUE_GUARD_STRICT=1 bin/rails solid_queue_guard:doctor
+```
+
+`STRICT=1` turns warnings into exit code `1`, so the pipeline fails on misconfigured pools, missing worker coverage, or missing schema tables — not only hard failures.
+
+Generate a starter workflow:
+
+```bash
+bin/rails generate solid_queue_guard:install:ci
+```
+
+### Production monitoring
+
+Mount the engine and point your load balancer or Kamal health check at `/solid_queue_guard/health`:
+
+```ruby
+# config/routes.rb
+mount SolidQueueGuard::Engine, at: "/solid_queue_guard"
+```
+
+Runtime checks matter here: queue lag, stale heartbeats, dispatcher health, and process topology reflect **live** Solid Queue state.
+
+Optional hardening:
+
+```ruby
+config.health_token = ENV["SOLID_QUEUE_GUARD_TOKEN"]
+config.health_cache_ttl = 15.seconds
+config.degraded_http_status = 207   # or :ok (200), 503, etc.
+config.notify_with = [:rails_logger, :slack]
+```
+
+### Typical flow
+
+```text
+Developer          CI                    Production
+    │               │                         │
+    │ doctor        │ doctor --strict           │ GET /health (every 30–60s)
+    ▼               ▼                         ▼
+ "pool wrong?"   block bad deploy          alert: worker dead
+ "schema ok?"    before merge              alert: queue lag
+```
+
+---
+
+## Runtime process checks
+
+Runtime checks query the **queue database** (via `SolidQueue::Record`). If `connects_to` is missing or the DB is unreachable, they **skip** — they do not pass silently as healthy.
+
+### `process_topology` — are the expected roles present?
+
+Reads distinct `kind` values from `solid_queue_processes`:
+
+| Kind | Role |
+| ---- | ---- |
+| `Supervisor` | Parent process (`bin/jobs`) |
+| `Worker` | Consumes ready jobs |
+| `Dispatcher` | Moves scheduled jobs to ready |
+| `Scheduler` | Runs recurring tasks |
+
+| Result | Meaning |
+| ------ | ------- |
+| ⚠️ No processes | Nothing registered — supervisor not running |
+| ⚠️ No Worker | Jobs will not be processed |
+| ⚠️ No Dispatcher | Scheduled work may stall (when recurring/scheduled jobs exist) |
+| ✅ Pass | Expected kinds are present |
+
+This check looks at **presence of records**, not heartbeat freshness.
+
+### `stale_process` — are heartbeats fresh?
+
+Finds processes where `last_heartbeat_at` is older than `stale_process_threshold` (default **5 minutes**):
+
+| Result | Meaning |
+| ------ | ------- |
+| ✅ Pass | All processes reported recently |
+| ❌ Fail | One or more workers/dispatchers look dead or stuck |
+
+Use this in production health to catch workers that died after deploy.
+
+### `pidfile` — optional supervisor liveness
+
+When `tmp/pids/solid_queue.pid` (or `SOLID_QUEUE_PIDFILE`) exists, verifies the PID is alive. Often **warns in development** where `bin/jobs` is not running. Disable if you do not use pidfiles:
+
+```ruby
+config.disabled_checks = [:pidfile]
+```
+
+### `puma_plugin_runtime` — Solid Queue inside Puma
+
+When `plugin :solid_queue` is in `config/puma.rb`, verifies active processes with recent heartbeats exist. **Skips** when the Puma plugin is not enabled.
+
+### Queue schema detection
+
+`QueueSchemaCheck` does **not** require `db/queue_schema.rb`. It validates that all tables for your installed **solid_queue** version exist in any of:
+
+- `db/queue_schema.rb`
+- `db/schema.rb`
+- `db/structure.sql`
+- the connected queue database
+
+Apps that keep Solid Queue tables only in `structure.sql` (common in Revelo-style repos) pass correctly.
+
+### Where each check type applies
+
+| Context | Config checks | Process / runtime checks |
+| ------- | ------------- | ------------------------ |
+| Local `doctor` | ✅ Primary value | ⚠️ Partial without `bin/jobs` |
+| CI `--strict` | ✅ Primary value | ⏭️ Usually skip |
+| Production `/health` | ✅ When DB up | ✅ Primary value |
+
+---
+
 ## Configuration
 
 ```ruby

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

@@ -5,18 +5,91 @@ module SolidQueueGuard
     module Config
       class QueueSchemaCheck < Base
         def call
-          schema_path = rails_root.join('db/queue_schema.rb')
+          evaluation = evaluate_schema
 
-          if schema_path.exist?
-            pass('queue_schema', 'db/queue_schema.rb exists')
-          else
+          case evaluation[:status]
+          when :pass
+            pass(check_id, evaluation[:message], metadata: evaluation[:metadata])
+          when :warn
             warn(
-              'queue_schema',
-              'db/queue_schema.rb not found',
-              suggestion: 'Run bin/rails solid_queue:install to generate the queue schema'
+              check_id,
+              evaluation[:message],
+              suggestion: evaluation[:suggestion],
+              metadata: evaluation[:metadata]
+            )
+          else
+            failure(
+              check_id,
+              evaluation[:message],
+              suggestion: evaluation[:suggestion],
+              metadata: evaluation[:metadata]
             )
           end
         end
+
+        private
+
+        def evaluate_schema
+          required = Schema::SolidQueueTables.required_tables
+          detection = Schema::SolidQueueTables.detected_tables(rails_root: rails_root)
+          missing = required - detection[:tables]
+          metadata = schema_metadata(detection, missing: missing)
+
+          return pass_evaluation(detection, required.size, metadata) if missing.empty?
+          return partial_evaluation(missing, metadata) if detection[:tables].any?
+
+          empty_evaluation(metadata)
+        end
+
+        def pass_evaluation(detection, table_count, metadata)
+          {
+            status: :pass,
+            message: success_message(detection, table_count),
+            metadata: metadata
+          }
+        end
+
+        def partial_evaluation(missing, metadata)
+          {
+            status: :warn,
+            message: "Missing Solid Queue tables: #{missing.join(', ')}",
+            suggestion: 'Run bin/rails solid_queue:install or migrate the queue database',
+            metadata: metadata
+          }
+        end
+
+        def empty_evaluation(metadata)
+          {
+            status: :fail,
+            message: [
+              'No Solid Queue schema tables found in',
+              'db/queue_schema.rb, db/schema.rb, db/structure.sql, or the queue database'
+            ].join(' '),
+            suggestion: 'Run bin/rails solid_queue:install and migrate the queue database',
+            metadata: metadata
+          }
+        end
+
+        def success_message(detection, table_count)
+          sources = source_descriptions(detection)
+          "Solid Queue schema complete (#{table_count}/#{table_count} tables) in #{sources.join(', ')}"
+        end
+
+        def source_descriptions(detection)
+          sources = detection[:file_tables].keys
+          sources << 'queue database' if detection[:database_tables].any?
+          sources.presence || ['schema files']
+        end
+
+        def schema_metadata(detection, missing:)
+          {
+            required_tables: Schema::SolidQueueTables.required_tables,
+            detected_tables: detection[:tables],
+            missing_tables: missing,
+            schema_sources: detection[:file_tables],
+            database_tables: detection[:database_tables]
+          }
+        end
       end
     end
   end

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 = '1.0.0'
+  VERSION = '1.0.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solid_queue_guard
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Rafael Pissardo
@@ -337,6 +337,7 @@ files:
 - 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