pgbus 0.11.1 → 0.11.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a52dc949281b6f2f1e9c847d38709fcc2723badd12370486faeb68b40ed55c42
-  data.tar.gz: 70a75a14bfe2225f63846314cbb60c0942e86b966c14b20e43eec74afc63adef
+  metadata.gz: 727dd6a7515414a2a426857ea19cc8cf33b8c5ca2311ecde116bf643114e8d85
+  data.tar.gz: c68f0e3c246b554059160e901e96d61f80c5a5a9aa1716d6e4787f84cfdbe655
 SHA512:
-  metadata.gz: dc59f389bf2b5e20b2e75a7a2c47301c242ea0b5857a240e5a59db3177effe34cbe694903d4396b07ef3ca67699f578a5d6b6d95f61d4318169ac477f237b526
-  data.tar.gz: a5a6a076c6cadb857c8690ef7d1363934c7f73bd76e8d91a87a936a91d05c4146c12bb67b5637204995d0ddef540833a8983ca4dd3d5ef1034a7b88473aa1e61
+  metadata.gz: f515f94c6e585a038ab468ca30dc49a284c9666ddb0116998532ce2afdf602ac8309972fbe79606ad055b73bd95da418210778cf80a9e3062288855d67a3b746
+  data.tar.gz: dd748949d2330236bfbc46b94c04ff907268e067830a2c4b91b3ff6b811324b2383d3c46bc950add9511c98355b39b39d9f3a58c03a3fed361838c866b24bf1c

data/CHANGELOG.md

@@ -10,6 +10,7 @@
 
 ### Added
 
+- **`config.doctor_on_boot` (+ `pgbus start --doctor` / `--doctor-strict`) — run the doctor preflight inside the booting supervisor, one Rails boot instead of two (issue #347).** The recommended deploy preflight was `bin/pgbus doctor || true` in the container entrypoint before `bin/pgbus start` — but both commands `require config/environment`, so the job container boots the full Rails app **twice** on every deploy (cost scaling with app boot time), and running doctor pre-supervisor makes the `Process liveness` check false-fail (no workers exist yet), which is exactly why the entrypoint has to swallow the exit code with `|| true` — losing any chance to gate on a genuinely-fatal finding. Now `config.doctor_on_boot = :report` (or `pgbus start --doctor`) runs the checks in the already-booted supervisor, after the DB is verified reachable and queues are bootstrapped but **before any worker is forked**: one boot, and the worker-dependent `Process liveness` check is skipped (it has no workers to observe yet and would false-fail on stale prior-generation rows during a redeploy). `config.doctor_on_boot = :strict` (or `--doctor-strict`) additionally **refuses to boot** — raising before forking anything, so the `ensure shutdown` path tears down the heartbeat/health server and no child starts — but *only* on a genuinely-fatal, non-transient check: a `Configuration` failure (a real config bug) or an **absent** PGMQ schema. It deliberately does **not** abort on `Queues`/`Database` failures — those are the transients the lenient queue bootstrap is built to ride out (children crash-and-backoff until the DB recovers), and `verify_connection!` already gated a hard-down DB moments earlier; making them strict-fatal would take down a whole fleet's cold boot in lockstep on a momentarily-saturated primary. Default `nil`/`false` = off (byte-identical to today; the supervisor constructs no `Doctor` and does zero extra work). The standalone `pgbus doctor` command and its exit-code semantics are unchanged. Refs #347.
 - **`Pgbus::Streams::PhlexHelpers` — a Phlex-includable `pgbus_stream_from`, and `Pgbus.stream_name_budget` (issue #334).** Two small helpers that stop consuming apps reimplementing pgbus glue. (1) `pgbus_stream_from` is a Rails view helper, so a Phlex component couldn't call it without hand-registering an output-helper macro (phlex-rails ships no `Phlex::Rails::Helpers::PgbusStreamFrom`). `include Pgbus::Streams::PhlexHelpers` now bridges it exactly like phlex-rails' own `TurboStreamFrom`. phlex-rails stays an **optional** dependency — the module references its `HelperMacros` and is loaded on demand (`require "pgbus/streams/phlex_helpers"`), never eagerly. (2) `Pgbus.stream_name_budget` exposes the maximum stream-name length (the pgmq queue-name cap minus the queue prefix) so apps size/truncate stream identifiers up front instead of hand-computing `MAX_QUEUE_NAME_LENGTH - queue_prefix.length - 1` at every call site. Refs #334.
 - **`EventBus::Registry#setup_all!(safe: true)` — a boot/rake-safe way to eagerly set up event subscribers (issue #334).** Calling `setup_all!` opens a PGMQ connection per subscriber (to create its queue + bind its topic), which is wrong during a `db:`/schema rake task (a live connection blocks `DROP DATABASE`) and crashes boot if the database isn't up yet — so apps wrapped it in a hand-rolled multi-class rescue plus a rake-task skip. `setup_all!(safe: true)` bakes that in: it skips entirely in a schema/asset rake context and swallows a connection error with a warning instead of raising. The default `setup_all!` is unchanged (raises). Refs #334.
 - **Connection-pooler safety (`config.require_primary`, `config.connection_guc_mode`) — pgbus is now correct-and-loud behind a transaction/read-write-splitting pooler instead of silently stalling (issue #332).** Three linked fixes. (1) **Primary affinity:** a read/write-splitting pooler (pgdog/pgcat) can route pgmq's VOLATILE `read`/`archive`/`delete` to a read replica, where workers read nothing (`read_ct=0`) and jobs stop with a **healthy heartbeat** — the supervisor watchdog keys on loop advancement, not read progress, so nothing surfaced the stall. The job read path had zero primary-affinity defense (only the LISTEN/streamer paths validated the primary via `PrimaryValidator`). Setting `config.require_primary = true` (default **false** — a single-primary deployment is byte-identical) makes `verify_connection!` reject a connection that lands on a replica (`pg_is_in_recovery() => t`) at supervisor boot, raising a clear `ConfigurationError` instead of forking children that read nothing. (2) **GUC forwarding:** pgbus's AR-config extraction dropped database.yml's `variables:` block, so `client_min_messages` (and any GUC) never reached pgmq's dedicated raw connections (NOTICE flooding that three consuming apps hand-patched via `connection_params`). GUCs are now forwarded, on both the AR-extracted and explicit-`connection_params` paths, by `config.connection_guc_mode`: `:options` (default) bakes them into the libpq `options` STARTUP param (byte-compatible with today for the read-timeout `statement_timeout`, now also carrying `variables:`), while `:session` applies them via post-connect `SET` on a fresh connection instead — for a transaction-mode PgBouncer that **rejects** the `options` startup param with a FATAL. `pgbus doctor` gains a ninth check ("Primary affinity") that warns (never fails) when the job connection is currently on a replica, naming the direct-port remediation. DB-gated integration tests prove both GUC modes round-trip a forwarded GUC and that `require_primary` verifies on a real primary. Refs #332.

data/README.md

@@ -1872,6 +1872,25 @@ rake pgbus:doctor  # identical checks, for a Rake-based deploy pipeline
 
 The report ends with a resolved-config summary (queue prefix, pool size, roles, capsules) with any password redacted from `database_url` / `connection_params`. Warnings do not fail the exit code — only a `:fail` result does.
 
+##### Doctor preflight at boot (single Rails boot)
+
+Running `pgbus doctor || true` in a container entrypoint before `pgbus start` boots the full Rails app **twice** on every deploy, and the pre-supervisor `Process liveness` check false-fails (no workers exist yet) — which is why the `|| true` is needed, swallowing any genuinely-fatal finding too. Instead, run the preflight *inside* the booting supervisor:
+
+```bash
+pgbus start --doctor          # run the preflight, log the report, always boot
+pgbus start --doctor-strict   # refuse to boot on a fatal check (exit non-zero, fork nothing)
+```
+
+or set it in the initializer:
+
+```ruby
+Pgbus.configure do |c|
+  c.doctor_on_boot = :report   # or :strict; nil/false (default) is off
+end
+```
+
+The boot preflight runs after the DB is verified reachable and queues are bootstrapped, but **before any worker is forked** — one Rails boot, and the `Process liveness` check is skipped (nothing to observe yet, so it can't false-fail). `:strict` aborts the boot only on a genuinely-fatal, non-transient check — a `Configuration` failure or an **absent** PGMQ schema. A transient DB blip that the lenient queue bootstrap is designed to ride out (surfacing as a `Queues` or `Database` failure) is reported but never aborts, so a fleet-wide cold boot against a momentarily-saturated primary doesn't fail every pod in lockstep.
+
 #### pgbus dlq
 
 Dead-letter inspect/drain operations from a headless deployment or incident runbook, routed through `Web::DataSource` so retry/discard semantics are identical to the dashboard (origin-queue re-enqueue, transactional produce+delete, lock release on discard) with zero raw SQL and no direct PGMQ calls:

data/lib/pgbus/cli.rb

@@ -51,6 +51,16 @@ module Pgbus
       Pgbus.configuration.execution_mode = options[:execution_mode].to_sym if options[:execution_mode]
       apply_capsule_filter(options[:capsule]) if options[:capsule]
       apply_role_filter(options)
+      apply_doctor_flag(options)
+    end
+
+    # --doctor runs the boot preflight in report mode; --doctor-strict aborts
+    # the boot on a fatal finding. Both set config.doctor_on_boot, which the
+    # supervisor reads at boot (issue #347). Strict wins if both are passed — it
+    # is the stronger gate, so a user asking for both clearly wants strict.
+    def apply_doctor_flag(options)
+      Pgbus.configuration.doctor_on_boot = :report if options[:doctor]
+      Pgbus.configuration.doctor_on_boot = :strict if options[:doctor_strict]
     end
 
     def parse_start_options(args)
@@ -81,6 +91,14 @@ module Pgbus
         opts.on("--execution-mode MODE", "Execution mode: threads (default) or async") do |v|
           options[:execution_mode] = v
         end
+
+        opts.on("--doctor", "Run doctor preflight checks at boot and log the report (issue #347)") do
+          options[:doctor] = true
+        end
+
+        opts.on("--doctor-strict", "Run doctor preflight and refuse to boot on a fatal finding") do
+          options[:doctor_strict] = true
+        end
       end.parse!(args.dup)
       options
     end
@@ -199,6 +217,12 @@ module Pgbus
                              pattern)
           --execution-mode   Execution mode: threads (default) or async
                              (fiber-based, lower connection usage)
+          --doctor           Run doctor preflight checks in the booting
+                             supervisor and log the report (one Rails boot
+                             instead of `pgbus doctor` + `pgbus start`)
+          --doctor-strict    Like --doctor, but refuse to boot (exit non-zero,
+                             fork nothing) if a fatal check fails (bad config
+                             or an absent PGMQ schema)
 
         Environment for `mcp`:
           PGBUS_MCP_TOKEN          If set, PGBUS_MCP_AUTH_TOKEN must match for

data/lib/pgbus/configuration.rb

@@ -89,6 +89,19 @@ module Pgbus
     # PGMQ schema installation mode (:auto, :extension, :embedded)
     attr_reader :pgmq_schema_mode
 
+    # Run doctor preflight checks inside the supervisor at boot (issue #347),
+    # so an entrypoint need not boot Rails twice (once for `pgbus doctor`, once
+    # for `pgbus start`). nil/false (default) — off, byte-identical to today.
+    #   :report — run the preflight and log the report, always continue booting.
+    #   :strict — additionally REFUSE to boot (raise before forking any worker)
+    #             when a genuinely-fatal, non-transient check fails. The strict
+    #             set is deliberately narrow (Configuration, PGMQ schema) so a
+    #             transient boot-time DB blip — which the lenient queue bootstrap
+    #             is designed to ride out via child crash-and-backoff — never
+    #             aborts a whole fleet's cold boot in lockstep. Set via the
+    #             `--doctor` / `--doctor-strict` start flags too.
+    attr_reader :doctor_on_boot
+
     # Event consumers
     attr_reader :event_consumers
 
@@ -248,6 +261,7 @@ module Pgbus
       @worker_notify_database_url = nil
 
       @pgmq_schema_mode = :auto
+      @doctor_on_boot = nil
 
       @event_consumers = nil
 
@@ -566,6 +580,28 @@ module Pgbus
       @pgmq_schema_mode = mode
     end
 
+    VALID_DOCTOR_ON_BOOT_MODES = [nil, :report, :strict].freeze
+
+    # nil/false are both "off"; a String is coerced to a Symbol so the CLI flags
+    # and YAML-ish configs work. Validated at assignment time (like the other
+    # enum options), not in validate!.
+    def doctor_on_boot=(mode)
+      coerced = case mode
+                when nil, false then nil
+                when Symbol then mode
+                when String then mode.to_sym
+                else
+                  raise Pgbus::ConfigurationError,
+                        "Invalid doctor_on_boot type: #{mode.class}. Must be nil, false, String, or Symbol"
+                end
+      unless VALID_DOCTOR_ON_BOOT_MODES.include?(coerced)
+        raise Pgbus::ConfigurationError,
+              "Invalid doctor_on_boot: #{coerced.inspect}. Must be nil/false (off), :report, or :strict"
+      end
+
+      @doctor_on_boot = coerced
+    end
+
     def validate!
       if pool_size && !(pool_size.is_a?(Numeric) && pool_size.positive?)
         raise Pgbus::ConfigurationError, "pool_size must be a positive number or nil (auto-tune)"

data/lib/pgbus/doctor.rb

@@ -25,26 +25,47 @@ module Pgbus
 
     STATUS_ICON = { ok: "✓", warn: "!", fail: "✗" }.freeze
 
+    # The ordered check suite, name → method. The name strings are the public,
+    # stable identity of each check (used in the report and to select subsets).
+    CHECKS = {
+      "Configuration" => :check_configuration,
+      "Database" => :check_database,
+      "PGMQ schema" => :check_pgmq_schema,
+      "Queues" => :check_queues,
+      "LISTEN/NOTIFY" => :check_notify,
+      "Process liveness" => :check_processes,
+      "GlobalID allowlist" => :check_allowed_global_id_models,
+      "Broadcast queue" => :check_broadcast_queue,
+      "Primary affinity" => :check_primary
+    }.freeze
+
+    # Process liveness reads the pgbus_processes table (via HealthAnalyzer), so
+    # it is only meaningful once workers have registered. The supervisor boot
+    # preflight (issue #347) runs BEFORE forking any worker, so it excludes this
+    # check — otherwise stale prior-generation worker rows plus a visible backlog
+    # would produce a false STALLED verdict on a redeploy.
+    BOOT_SKIP = ["Process liveness"].freeze
+
+    # The subset of checks whose :fail is genuinely deploy-fatal AND not a
+    # transient the supervisor is designed to ride out. Only these abort a
+    # `:strict` boot. Configuration#validate! failing is a real config bug;
+    # an absent PGMQ schema means the migrations never ran. Deliberately NOT
+    # Queues/Database: the lenient queue bootstrap swallows a boot-time DB blip
+    # so children crash-and-backoff and recover, and verify_connection! already
+    # gated a hard-down DB before the preflight — making either strict-fatal
+    # would turn a tolerated transient into a fleet-wide lockstep boot abort.
+    STRICT_FATAL = ["Configuration", "PGMQ schema"].freeze
+
     def initialize(config: Pgbus.configuration, client: Pgbus.client, data_source: nil)
       @config = config
       @client = client
-      @data_source = data_source || Pgbus::Web::DataSource.new(client: client)
+      @data_source = data_source
     end
 
     # Run all checks and return an array of result hashes:
     #   { name:, status: :ok|:warn|:fail, detail: }
     def run
-      @run ||= [
-        check_configuration,
-        check_database,
-        check_pgmq_schema,
-        check_queues,
-        check_notify,
-        check_processes,
-        check_allowed_global_id_models,
-        check_broadcast_queue,
-        check_primary
-      ].map(&:to_h)
+      @run ||= run_checks(CHECKS.keys)
     end
 
     # True when no check failed. Warnings do not fail the run — they surface a
@@ -53,11 +74,34 @@ module Pgbus
       run.none? { |c| c[:status] == :fail }
     end
 
+    # --- Supervisor boot preflight (issue #347) ---
+
+    # The checks safe to run inside the booting supervisor before any worker is
+    # forked: everything except the worker-dependent process-liveness check.
+    # Runs a genuine SUBSET — check_processes is never invoked — so there is no
+    # pre-fork HealthAnalyzer/DataSource round-trip.
+    def boot_checks
+      @boot_checks ||= run_checks(CHECKS.keys - BOOT_SKIP)
+    end
+
+    # True unless a strict-fatal check (see STRICT_FATAL) failed. Warnings and
+    # transient-shaped failures (Queues, Database) never block a `:strict` boot.
+    def boot_ok?
+      boot_checks.none? { |c| c[:status] == :fail && STRICT_FATAL.include?(c[:name]) }
+    end
+
+    # Human-readable report for the boot preflight — the boot_checks subset.
+    def boot_report
+      report(boot_checks)
+    end
+
     # Human-readable report: one line per check, then a resolved-config summary
     # with passwords redacted. Suitable for stdout in the CLI and rake task.
-    def report
+    # Defaults to the full run; pass a filtered result array (e.g. boot_checks)
+    # to render a subset.
+    def report(checks = run)
       lines = ["Pgbus Doctor", "=" * 40]
-      run.each do |check|
+      checks.each do |check|
         icon = STATUS_ICON.fetch(check[:status], "?")
         lines << format("%<icon>s %<name>-22s %<detail>s", icon: icon, name: check[:name], detail: check[:detail])
       end
@@ -86,6 +130,21 @@ module Pgbus
 
     private
 
+    # Run the named checks in CHECKS order and return an array of result hashes.
+    # Only the requested checks are INVOKED — a check omitted from `names` does
+    # no work (e.g. boot_checks never calls check_processes, so no HealthAnalyzer
+    # round-trip pre-fork).
+    def run_checks(names)
+      CHECKS.filter_map { |name, method| send(method).to_h if names.include?(name) }
+    end
+
+    # The dashboard data source backing the process-liveness check. Built lazily
+    # so the boot preflight (which excludes that check) never constructs a
+    # DataSource or touches the dashboard layer at the fork boundary.
+    def data_source
+      @data_source ||= Pgbus::Web::DataSource.new(client: @client)
+    end
+
     # True in a Rails production environment. Guarded so the doctor still runs
     # outside Rails (plain Ruby, tests) without assuming Rails is loaded.
     def production?
@@ -181,7 +240,7 @@ module Pgbus
     # from the shared HealthAnalyzer. STALLED (the silent-worker-wedge) is a
     # failure; DEGRADED is a warning; OK passes.
     def check_processes
-      verdict = Pgbus::MCP::HealthAnalyzer.new(@data_source).verdict
+      verdict = Pgbus::MCP::HealthAnalyzer.new(data_source).verdict
       status = verdict[:status]
       detail = Array(verdict[:reasons]).first || status
 

data/lib/pgbus/process/supervisor.rb

@@ -76,6 +76,14 @@ module Pgbus
         # notify_trigger_current? makes those calls cheap no-ops.
         bootstrap_queues
 
+        # Optional in-process doctor preflight (issue #347): run the diagnostic
+        # checks here — after config is loaded, the DB is verified reachable, and
+        # queues are bootstrapped, but BEFORE any worker is forked — so an
+        # entrypoint gets a single Rails boot instead of `pgbus doctor` + `pgbus
+        # start`. :strict aborts the boot (raising, so nothing forks) on a
+        # genuinely-fatal finding; :report only logs. Off by default.
+        run_doctor_preflight unless config.doctor_on_boot.nil?
+
         boot_processes
         monitor_loop
       ensure
@@ -683,6 +691,33 @@ module Pgbus
         ErrorReporter.report(e, { action: "bootstrap_queues" })
       end
 
+      # In-process doctor preflight (issue #347). Runs the boot-safe subset of
+      # doctor checks (everything except the worker-dependent process-liveness
+      # check, which has no workers to observe yet) against the supervisor's own
+      # config and the already-verified shared client, and logs the report.
+      #
+      # In :strict mode, a genuinely-fatal check (Doctor::STRICT_FATAL —
+      # Configuration or an absent PGMQ schema) aborts the boot by raising
+      # Pgbus::ConfigurationError. Because this runs before boot_processes, no
+      # child is forked, and `run`'s `ensure shutdown` tears down the heartbeat
+      # and health server — the same fail-fast path verify_connection! uses.
+      # A transient-shaped failure (Queues, Database) is reported but never
+      # aborts: the lenient bootstrap above is built to let children ride out a
+      # boot-time DB blip, and a strict abort there would take down a whole
+      # fleet's cold boot in lockstep.
+      def run_doctor_preflight
+        doctor = Pgbus::Doctor.new(config: config, client: Pgbus.client)
+        report = doctor.boot_report
+        Pgbus.logger.info { "[Pgbus] doctor preflight (#{config.doctor_on_boot}):\n#{report}" }
+
+        return unless config.doctor_on_boot == :strict
+        return if doctor.boot_ok?
+
+        raise Pgbus::ConfigurationError,
+              "doctor preflight failed a fatal check (doctor_on_boot: :strict) — refusing to boot. " \
+              "See the report above."
+      end
+
       def load_rails_app
         return unless defined?(Rails) && Rails.respond_to?(:application) && Rails.application
 

data/lib/pgbus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pgbus
-  VERSION = "0.11.1"
+  VERSION = "0.11.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.11.1
+  version: 0.11.2
 platform: ruby
 authors:
 - Mikael Henriksson