solid_queue_guard 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd60b98c25c507b3069f98b6b69282f627a398e96bd43d7a5d0713f0499c8610
-  data.tar.gz: c60a8995c311f4935456f58ca950e1d4cdb4b7e601dc1e6290f62f9d06931cb0
+  metadata.gz: 690433fe81ac90880ec7fdaa046b7638330eb879776e19343066732fd1f0f3e7
+  data.tar.gz: 6028bf63b80b0919158a10fb5771b8cdec74518be47b0882cfd39f893bbf10f7
 SHA512:
-  metadata.gz: ac5fbbb57df0cb133466076f0c4c1b698a13004b3f44e22bc64139e04e8c4bb51973a22e534ff0617329709a154a92a7a93ac9e083ea0087d86dadc73c6e89cf
-  data.tar.gz: b16bc3883213b26928b0cfa2c4d0b355ce43bd956a4c3df27e4cad4f8f71534748a15e5f9c892190a018741df8c9f1fbe4aaaa577e960f4e39a2a28c00a823ed
+  metadata.gz: 2d9bf3c79fbe0871ed9456eec1cefb22baf52f4949b128cc2a1f8d30dde4bb468bbece87752a33ea06a0e53d12ec25db65e1c1295205ac140643d9cf5dbfc769
+  data.tar.gz: 0d40a0805708376a56e243977772274a61f6e4a799ca3dfc64dfb362a46217e30258ba1758e1dda7bc3956f63e13895cde6814f446551b4bf271a07b24477e57

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/Gemfile.lock.bak
+/pkg/
+/tmp/
+/*.gem
+/solid_queue_guard-*/
+
+/test/dummy/db/*.sqlite3
+/test/dummy/log/*
+!/test/dummy/log/.keep
+/test/dummy/tmp/*
+!/test/dummy/tmp/.keep

data/.rubocop.yml

@@ -0,0 +1,44 @@
+plugins:
+  - rubocop-rails
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.1
+  SuggestExtensions: false
+  Exclude:
+    - "gemfiles/**/*"
+    - "test/dummy/**/*"
+    - "vendor/**/*"
+    - "tmp/**/*"
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - "Rakefile"
+    - "*.gemspec"
+    - "lib/solid_queue_guard/tasks.rb"
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/AbcSize:
+  Max: 25
+  Exclude:
+    - lib/solid_queue_guard/checks/runtime/**/*
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+Rails/Exit:
+  Exclude:
+    - "lib/solid_queue_guard/cli.rb"
+
+Naming/PredicateMethod:
+  Exclude:
+    - "lib/solid_queue_guard/tasks.rb"
+
+Style/MultilineBlockChain:
+  Exclude:
+    - "lib/solid_queue_guard/checks/runtime/**/*"

data/.ruby-version

@@ -0,0 +1 @@
+3.4.9

data/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+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.0] - 2026-07-09
+
+### Added
+
+- Stable public API guarantee documented in README
+- Gemspec packaging via `git ls-files` for reproducible releases
+
+### Changed
+
+- Deprecations now target removal in `2.0` per semver policy
+
+## [0.8.0] - 2026-07-09
+
+### Added
+
+- Configurable HTTP status policy via `degraded_http_status` and `unhealthy_http_status`
+- `solid_queue_guard:install:ci` generator for GitHub Actions doctor workflow
+
+## [0.7.0] - 2026-07-09
+
+### Added
+
+- `AsyncSupervisorConfigCheck` for async supervisor mode
+- `PumaPluginRuntimeCheck` for co-located Puma plugin health
+- Async-aware topology pool recommendations
+
+## [0.6.0] - 2026-07-09
+
+### Added
+
+- Per-check configuration via `disabled_checks` and `config.checks`
+- Per-check threshold overrides for queue lag, failed jobs, stale processes, and scheduled backlog
+
+## [0.5.0] - 2026-07-09
+
+### Added
+
+- `TopologyRecommendationCheck` for automatic `queue.yml` and pool recommendations
+- `SolidQueueGuard::Recommendations::Topology` analyzer
+
+## [0.4.0] - 2026-07-09
+
+### Added
+
+- Metrics export via `config.metrics_backends` (`:statsd`, `:prometheus`, `:opentelemetry`)
+- `SolidQueueGuard::Metrics::Exporter` and per-backend exporters
+
+## [0.3.0] - 2026-07-09
+
+### Added
+
+- Notification adapters: `:rails_logger`, `:slack`, `:datadog`, `:webhook`
+- Automatic notification delivery on degraded/unhealthy CLI reports via `config.notify_with`
+
+## [0.2.0] - 2026-07-09
+
+### Added
+
+- Runtime checks: queue lag, stale processes, dispatcher health, scheduled backlog, blocked jobs, orphaned claims, failed jobs, recurring staleness, paused queue lag, pidfile, finished jobs growth
+- HTTP `/solid_queue_guard/health` endpoint with optional token auth and response caching
+- `health` rake task now runs full runtime scope
+- Terminal report hides skipped runtime checks
+- Optional Rails `/up` integration via `integrate_rails_health`
+
+## [0.1.0] - 2026-07-09
+
+### Added
+
+- `solid_queue_guard:doctor` rake task for configuration readiness checks
+- `solid_queue_guard:report` rake task for full diagnostic output
+- `solid_queue_guard:install` generator for the initializer
+- JSON output via `SOLID_QUEUE_GUARD_FORMAT=json` or `doctor[json]`
+- Strict CI mode via `SOLID_QUEUE_GUARD_STRICT=1` or `--strict`
+- Configuration checks: adapter, queue database, `connects_to`, queue schema, thread pool, worker coverage, scheduler, environment flags, process heartbeat thresholds, and Puma co-location

data/Gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+# RuboCop 1.75+ can pull parallel 2.x, which requires Ruby >= 3.3.
+gem 'parallel', '~> 1.26'

data/Gemfile.lock

@@ -0,0 +1,308 @@
+PATH
+  remote: .
+  specs:
+    solid_queue_guard (1.0.0)
+      actionpack (>= 7.1, < 9.0)
+      activejob (>= 7.1, < 9.0)
+      activerecord (>= 7.1, < 9.0)
+      activesupport (>= 7.1, < 9.0)
+      railties (>= 7.1, < 9.0)
+      solid_queue (>= 1.0, < 2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    action_text-trix (2.1.19)
+      railties
+    actioncable (8.1.3)
+      actionpack (= 8.1.3)
+      activesupport (= 8.1.3)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+      zeitwerk (~> 2.6)
+    actionmailbox (8.1.3)
+      actionpack (= 8.1.3)
+      activejob (= 8.1.3)
+      activerecord (= 8.1.3)
+      activestorage (= 8.1.3)
+      activesupport (= 8.1.3)
+      mail (>= 2.8.0)
+    actionmailer (8.1.3)
+      actionpack (= 8.1.3)
+      actionview (= 8.1.3)
+      activejob (= 8.1.3)
+      activesupport (= 8.1.3)
+      mail (>= 2.8.0)
+      rails-dom-testing (~> 2.2)
+    actionpack (8.1.3)
+      actionview (= 8.1.3)
+      activesupport (= 8.1.3)
+      nokogiri (>= 1.8.5)
+      rack (>= 2.2.4)
+      rack-session (>= 1.0.1)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+      useragent (~> 0.16)
+    actiontext (8.1.3)
+      action_text-trix (~> 2.1.15)
+      actionpack (= 8.1.3)
+      activerecord (= 8.1.3)
+      activestorage (= 8.1.3)
+      activesupport (= 8.1.3)
+      globalid (>= 0.6.0)
+      nokogiri (>= 1.8.5)
+    actionview (8.1.3)
+      activesupport (= 8.1.3)
+      builder (~> 3.1)
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activejob (8.1.3)
+      activesupport (= 8.1.3)
+      globalid (>= 0.3.6)
+    activemodel (8.1.3)
+      activesupport (= 8.1.3)
+    activerecord (8.1.3)
+      activemodel (= 8.1.3)
+      activesupport (= 8.1.3)
+      timeout (>= 0.4.0)
+    activestorage (8.1.3)
+      actionpack (= 8.1.3)
+      activejob (= 8.1.3)
+      activerecord (= 8.1.3)
+      activesupport (= 8.1.3)
+      marcel (~> 1.0)
+    activesupport (8.1.3)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    appraisal (2.5.0)
+      bundler
+      rake
+      thor (>= 0.14.0)
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (4.1.2)
+    builder (3.3.0)
+    concurrent-ruby (1.3.7)
+    connection_pool (3.0.2)
+    crass (1.0.7)
+    date (3.5.1)
+    debug (1.11.1)
+      irb (~> 1.10)
+      reline (>= 0.3.8)
+    drb (2.2.3)
+    erb (6.0.4)
+    erubi (1.13.1)
+    et-orbi (1.4.0)
+      tzinfo
+    fugit (1.12.3)
+      et-orbi (~> 1.4)
+      raabro (~> 1.4)
+    globalid (1.4.0)
+      activesupport (>= 6.1)
+    i18n (1.15.2)
+      concurrent-ruby (~> 1.0)
+    io-console (0.8.2)
+    irb (1.18.0)
+      pp (>= 0.6.0)
+      prism (>= 1.3.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.20.0)
+    language_server-protocol (3.17.0.6)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    loofah (2.25.1)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
+    mail (2.9.1)
+      logger
+      mini_mime (>= 0.1.1)
+      net-imap
+      net-pop
+      net-smtp
+    marcel (1.2.1)
+    mini_mime (1.1.5)
+    minitest (5.27.0)
+    mocha (3.1.0)
+      ruby2_keywords (>= 0.0.5)
+    net-imap (0.6.4.1)
+      date
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.2.2)
+      timeout
+    net-smtp (0.5.1)
+      net-protocol
+    nio4r (2.7.5)
+    nokogiri (1.19.4-aarch64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.4-aarch64-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.19.4-arm-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.4-arm-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.19.4-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.4-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.4-x86_64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.4-x86_64-linux-musl)
+      racc (~> 1.4)
+    parallel (1.28.0)
+    parser (3.3.11.1)
+      ast (~> 2.4.1)
+      racc
+    pp (0.6.4)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
+    puma (8.0.2)
+      nio4r (~> 2.0)
+    raabro (1.4.0)
+    racc (1.8.1)
+    rack (3.2.6)
+    rack-session (2.1.2)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0)
+    rack-test (2.2.0)
+      rack (>= 1.3)
+    rackup (2.3.1)
+      rack (>= 3)
+    rails (8.1.3)
+      actioncable (= 8.1.3)
+      actionmailbox (= 8.1.3)
+      actionmailer (= 8.1.3)
+      actionpack (= 8.1.3)
+      actiontext (= 8.1.3)
+      actionview (= 8.1.3)
+      activejob (= 8.1.3)
+      activemodel (= 8.1.3)
+      activerecord (= 8.1.3)
+      activestorage (= 8.1.3)
+      activesupport (= 8.1.3)
+      bundler (>= 1.15.0)
+      railties (= 8.1.3)
+    rails-dom-testing (2.3.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.7.0)
+      loofah (~> 2.25)
+      nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
+    railties (8.1.3)
+      actionpack (= 8.1.3)
+      activesupport (= 8.1.3)
+      irb (~> 1.13)
+      rackup (>= 1.0.0)
+      rake (>= 12.2)
+      thor (~> 1.0, >= 1.2.2)
+      tsort (>= 0.2)
+      zeitwerk (~> 2.6)
+    rainbow (3.1.1)
+    rake (13.4.2)
+    rbs (4.0.3)
+      logger
+      prism (>= 1.6.0)
+      tsort
+    rdoc (8.0.0)
+      erb
+      prism (>= 1.6.0)
+      rbs (>= 4.0.0)
+      tsort
+    regexp_parser (2.12.0)
+    reline (0.6.3)
+      io-console (~> 0.5)
+    rubocop (1.88.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-rails (2.35.5)
+      activesupport (>= 4.2.0)
+      lint_roller (~> 1.1)
+      rack (>= 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.44.0, < 2.0)
+    ruby-progressbar (1.13.0)
+    ruby2_keywords (0.0.5)
+    securerandom (0.4.1)
+    solid_queue (1.4.0)
+      activejob (>= 7.1)
+      activerecord (>= 7.1)
+      concurrent-ruby (>= 1.3.1)
+      fugit (~> 1.11)
+      railties (>= 7.1)
+      thor (>= 1.3.1)
+    sqlite3 (2.9.5-aarch64-linux-gnu)
+    sqlite3 (2.9.5-aarch64-linux-musl)
+    sqlite3 (2.9.5-arm-linux-gnu)
+    sqlite3 (2.9.5-arm-linux-musl)
+    sqlite3 (2.9.5-arm64-darwin)
+    sqlite3 (2.9.5-x86_64-darwin)
+    sqlite3 (2.9.5-x86_64-linux-gnu)
+    sqlite3 (2.9.5-x86_64-linux-musl)
+    thor (1.5.0)
+    timeout (0.6.1)
+    tsort (0.2.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    uri (1.1.1)
+    useragent (0.16.11)
+    websocket-driver (0.8.2)
+      base64
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    zeitwerk (2.8.2)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  appraisal (~> 2.5)
+  debug
+  minitest (~> 5.0)
+  mocha (>= 2.1)
+  parallel (~> 1.26)
+  puma (>= 6.0)
+  rails (>= 7.1, < 9.0)
+  rubocop (~> 1.75)
+  rubocop-rails (~> 2.30)
+  solid_queue_guard!
+  sqlite3 (~> 2.1)
+
+BUNDLED WITH
+   2.7.2

data/README.md

@@ -67,7 +67,7 @@ One command. Actionable output. No Datadog required to get started.
 
 ## What it checks
 
-### v0.1 — Configuration doctor (available now)
+### Configuration doctor
 
 Runs locally, in CI, or pre-deploy. **No extra infrastructure.**
 
@@ -83,8 +83,10 @@ Runs locally, in CI, or pre-deploy. **No extra infrastructure.**
 | **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 |
+| **Async supervisor** | `async` mode with thread/pool sizing risks |
+| **Topology** | `queue.yml` worker and pool recommendations |
 
-### v0.2+ — Runtime guards (roadmap)
+### Runtime guards
 
 | Check | Catches |
 | ----- | ------- |
@@ -93,6 +95,7 @@ Runs locally, in CI, or pre-deploy. **No extra infrastructure.**
 | **Dispatcher health** | Scheduled jobs never becoming ready |
 | **Blocked jobs** | Concurrency control silently holding jobs |
 | **Recurring staleness** | Cron tasks that stopped firing |
+| **Puma plugin runtime** | Plugin enabled but no active Solid Queue processes |
 | **HTTP `/health`** | Kamal, ECS, K8s, UptimeRobot integration |
 
 ---
@@ -104,6 +107,7 @@ Runs locally, in CI, or pre-deploy. **No extra infrastructure.**
 ```bash
 bundle add solid_queue_guard
 bin/rails solid_queue_guard:install
+bin/rails generate solid_queue_guard:install:ci   # optional GitHub Actions workflow
 ```
 
 ### Run the doctor
@@ -138,7 +142,13 @@ Perfect for deploy pipelines:
   run: SOLID_QUEUE_GUARD_STRICT=1 bin/rails solid_queue_guard:doctor
 ```
 
-### HTTP health (v0.2)
+Or generate a workflow:
+
+```bash
+bin/rails generate solid_queue_guard:install:ci
+```
+
+### HTTP health
 
 ```ruby
 # config/routes.rb
@@ -150,6 +160,20 @@ curl localhost:3000/solid_queue_guard/health
 # => { "status": "degraded", "queue_lag_seconds": 245, "warnings": [...] }
 ```
 
+Optional token protection:
+
+```ruby
+config.health_token = ENV["SOLID_QUEUE_GUARD_TOKEN"]
+# curl -H "X-Solid-Queue-Guard-Token: $TOKEN" ...
+```
+
+HTTP status policy (for Kamal, ECS, load balancers):
+
+```ruby
+config.degraded_http_status = 207   # or :ok (200), 503, etc.
+config.unhealthy_http_status = 503  # default
+```
+
 Works with **Kamal**, **Heroku**, **Fly.io**, **ECS/Fargate**, **Kubernetes**, **Better Stack**, **UptimeRobot**.
 
 ---
@@ -170,13 +194,46 @@ SolidQueueGuard.configure do |config|
   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
+  # Per-check overrides (v0.6+)
+  config.disabled_checks = [:pidfile]
+  config.checks.queue_lag = { threshold: 10.minutes }
+  config.checks.failed_jobs = { threshold: 5, enabled: true }
+
+  # HTTP status policy (v0.8+)
+  # config.degraded_http_status = 207
+  # config.unhealthy_http_status = 503
+
+  # config.health_token = ENV["SOLID_QUEUE_GUARD_TOKEN"]
+  # config.integrate_rails_health = true
+  # config.notify_with = [:rails_logger, :slack, :datadog, :webhook]
+  # config.metrics_backends = [:statsd, :prometheus, :opentelemetry]
 end
 ```
 
 ---
 
+## Public API (v1.0+)
+
+The following surface is **stable** until `2.0` and follows [semantic versioning](https://semver.org/):
+
+| API | Description |
+| --- | ----------- |
+| `SolidQueueGuard.configure` | Block-style configuration |
+| `SolidQueueGuard.config` | Current configuration object |
+| `SolidQueueGuard.enabled?` | Whether checks run |
+| `solid_queue_guard:doctor` | Config readiness report |
+| `solid_queue_guard:health` | Runtime health report |
+| `solid_queue_guard:report` | Full diagnostic report |
+| `solid_queue_guard:install` | Initializer generator |
+| `solid_queue_guard:install:ci` | GitHub Actions workflow generator |
+| `mount SolidQueueGuard::Engine` | HTTP health endpoint |
+
+Configuration attributes, rake tasks, and health JSON shape are public. Internal check classes and registry are `@api private`.
+
+Breaking changes ship only in major versions (`2.0+`). Deprecations warn one minor version ahead.
+
+---
+
 ## solid_queue_guard vs Mission Control
 
 | | [Mission Control — Jobs](https://github.com/rails/mission_control-jobs) | solid_queue_guard |
@@ -185,9 +242,9 @@ end
 | **UI** | Dashboard | CLI + JSON + health endpoint |
 | **Retry / discard** | Yes | No (use Mission Control) |
 | **Config doctor** | No | Yes |
-| **Queue lag alerts** | No | Yes (v0.2) |
+| **Queue lag alerts** | No | Yes |
 | **Pre-deploy checks** | No | Yes |
-| **Recurring job guard** | Manual inspection | Automatic (v0.2) |
+| **Recurring job guard** | Manual inspection | Automatic |
 
 **Use both.** They solve different problems.
 
@@ -195,13 +252,17 @@ end
 
 ## 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 |
+| Version | Ships | Status |
+| ------- | ----- | ------ |
+| **v0.1** | `doctor` — config checks, CI integration, install generator | ✅ Released |
+| **v0.2** | Runtime health, queue lag, dispatcher/blocked jobs, HTTP endpoint | ✅ Released |
+| **v0.3** | Slack, Datadog, webhook notifications | ✅ Released |
+| **v0.4** | StatsD, Prometheus, OpenTelemetry metrics | ✅ Released |
+| **v0.5** | Auto-recommendations for `queue.yml` topology | ✅ Released |
+| **v0.6** | Per-check configuration (`disabled_checks`, `config.checks`) | ✅ Released |
+| **v0.7** | Puma plugin runtime check, async supervisor awareness | ✅ Released |
+| **v0.8** | HTTP status policy, `install:ci` generator | ✅ Released |
+| **v1.0** | Stable public API, strict semver | ✅ Released |
 
 ---
 
@@ -209,6 +270,8 @@ end
 
 | Gem version | Ruby | Rails |
 | ----------- | ---- | ----- |
+| 1.0.x       | 3.1+ | 7.1, 7.2, 8.0 |
+| 0.5.x       | 3.1+ | 7.1, 7.2, 8.0 |
 | 0.1.x       | 3.1+ | 7.1, 7.2, 8.0 |
 
 ## Requirements
@@ -232,6 +295,8 @@ bundle exec appraisal install
 bundle exec appraisal rake test
 ```
 
+Release a new version by pushing a `v*` tag after CI passes (Trusted Publishing on RubyGems).
+
 ---
 
 ## Contributing

data/app/controllers/solid_queue_guard/application_controller.rb

@@ -2,5 +2,6 @@
 
 module SolidQueueGuard
   class ApplicationController < ActionController::Base
+    protect_from_forgery with: :null_session
   end
 end

data/app/controllers/solid_queue_guard/health_controller.rb

@@ -2,8 +2,29 @@
 
 module SolidQueueGuard
   class HealthController < ApplicationController
+    before_action :authenticate_token!
+
     def show
-      render json: { status: 'not_implemented', message: 'HTTP health checks ship in v0.2' }, status: :not_implemented
+      payload = Health::Cache.fetch
+      status_code = http_status_for(payload[:status])
+
+      render json: payload, status: status_code
+    end
+
+    private
+
+    def authenticate_token!
+      token = SolidQueueGuard.config.health_token
+      return if token.blank?
+
+      provided = request.headers['X-Solid-Queue-Guard-Token'].presence || params[:token]
+      return if ActiveSupport::SecurityUtils.secure_compare(provided.to_s, token.to_s)
+
+      render json: { status: 'unauthorized' }, status: :unauthorized
+    end
+
+    def http_status_for(status)
+      HttpStatusPolicy.for_report_status(status)
     end
   end
 end

data/lib/generators/solid_queue_guard/install/USAGE.ci

@@ -0,0 +1,9 @@
+Description:
+    Adds a GitHub Actions workflow that runs `solid_queue_guard:doctor` with strict mode.
+
+Example:
+    bin/rails generate solid_queue_guard:install:ci
+
+    This will create:
+
+        .github/workflows/solid_queue_guard.yml