pgbus 0.9.7 → 0.9.9

data/lib/pgbus/web/data_source.rb

@@ -1234,18 +1234,50 @@ module Pgbus
 
       def derive_process_status(stale, metadata, kind)
         return :stale if stale
-        return :healthy unless kind == "worker" && metadata.is_a?(Hash)
+        return :healthy unless metadata.is_a?(Hash)
+
+        threshold = stall_threshold_for(kind)
+        return :healthy unless threshold
 
         loop_tick = metadata["loop_tick_at"]
         return :healthy unless loop_tick
 
-        threshold = Pgbus.configuration.stall_threshold
-        return :healthy unless threshold&.positive?
-
         age = Time.now.to_f - loop_tick.to_f
         age > threshold ? :stalled : :healthy
       end
 
+      # Kind-aware stall threshold. Workers run a tight loop, so the base
+      # stall_threshold applies directly. The dispatcher and scheduler sleep
+      # between iterations, so their beacon is naturally up to one sleep
+      # interval stale even when healthy — widen the window by that interval to
+      # avoid false stalls. Consumers idle on an empty-read wait that can reach
+      # NOTIFY_FALLBACK_POLL_SECONDS (15s) when a live listener drives wake-up,
+      # so widen by that max wait when notify is on, or by the poll interval
+      # otherwise. Kinds with no loop beacon (nil) are never stalled.
+      def stall_threshold_for(kind)
+        config = Pgbus.configuration
+        base = config.stall_threshold
+        return nil unless base&.positive?
+
+        case kind
+        when "worker" then base
+        when "dispatcher" then base + config.dispatch_interval
+        when "scheduler" then base + config.recurring_schedule_interval
+        when "consumer" then base + consumer_stall_slack(config)
+        end
+      end
+
+      # Widen the consumer's stall window by its maximum empty-read wait. With
+      # notify wake-up live, that wait rises to NOTIFY_FALLBACK_POLL_SECONDS as a
+      # safety net; without it, the consumer polls at polling_interval.
+      def consumer_stall_slack(config)
+        if config.worker_notify_wakeup?
+          [config.polling_interval, Pgbus::Process::Consumer::NOTIFY_FALLBACK_POLL_SECONDS].max
+        else
+          config.polling_interval
+        end
+      end
+
       def format_batch(record)
         total = record.total_jobs
         done = record.completed_jobs + record.discarded_jobs

data/lib/pgbus/web/health_app.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Pgbus
+  module Web
+    # Plain Rack app exposing HTTP liveness and readiness probes for
+    # orchestrators (Kubernetes kubelet, load balancers). Mount it in the host
+    # Rails app — no auth, no DB access on the liveness path:
+    #
+    #   # config/routes.rb
+    #   mount Pgbus::Web::HealthApp.new => "/pgbus/health"
+    #
+    #   # kubelet
+    #   livenessProbe:  { httpGet: { path: /pgbus/health/livez, port: 3000 } }
+    #   readinessProbe: { httpGet: { path: /pgbus/health/readyz, port: 3000 } }
+    #
+    # The supervisor process can also serve these two paths standalone via
+    # {Pgbus::Web::HealthServer} when `config.health_port` is set — that path
+    # synthesizes a minimal Rack env and calls this same #call, so the routing
+    # and verdict logic live in exactly one place.
+    #
+    # Routing (env-only, no Rack::Request so it works under the bare-socket
+    # HealthServer too):
+    #   GET  /livez  → 200 text/plain "ok", unconditionally, NO database access
+    #                  (the serving process is up — that is all liveness means).
+    #   GET  /readyz → build a DataSource, run MCP::HealthAnalyzer#verdict:
+    #                    OK / DEGRADED → 200, STALLED → 503, body = verdict JSON.
+    #                  Any StandardError (DB unreachable) → 503 {"status":"ERROR"},
+    #                  logged via Pgbus.logger (never swallowed).
+    #   unknown path → 404; non-GET on a known path → 405.
+    class HealthApp
+      LIVEZ = "/livez"
+      READYZ = "/readyz"
+      KNOWN_PATHS = [LIVEZ, READYZ].freeze
+      private_constant :KNOWN_PATHS
+
+      TEXT = { "Content-Type" => "text/plain" }.freeze
+      JSON_HEADERS = { "Content-Type" => "application/json" }.freeze
+      private_constant :TEXT, :JSON_HEADERS
+
+      # DEGRADED is deliberately "ready": the serving process can still answer,
+      # and flapping a pod out of rotation on a transient DEGRADED (a stale
+      # sibling, a paused queue) would remove capacity for no gain. Only STALLED
+      # — the silent-wedge signal — fails readiness.
+      READY_STATUSES = %w[OK DEGRADED].freeze
+      private_constant :READY_STATUSES
+
+      # @param data_source [Pgbus::Web::DataSource, nil] read layer for /readyz.
+      #   nil (the default) builds a fresh DataSource per readiness check, which
+      #   avoids serving stale metrics from a long-lived app's memoized instance.
+      def initialize(data_source: nil)
+        @data_source = data_source
+      end
+
+      def call(env)
+        path = env["PATH_INFO"].to_s
+        return not_found unless KNOWN_PATHS.include?(path)
+        return method_not_allowed unless env["REQUEST_METHOD"] == "GET"
+
+        path == LIVEZ ? livez : readyz
+      end
+
+      private
+
+      # Liveness: the process is running. No DB, no analyzer, no config lookups.
+      def livez
+        [200, TEXT.dup, ["ok"]]
+      end
+
+      def readyz
+        # HealthAnalyzer lives in the MCP namespace, which is excluded from
+        # Zeitwerk (its *tools* subclass the optional `mcp` gem). The analyzer
+        # itself has no gem dependency, so require just that one file — the
+        # standalone health server must work without the `mcp` gem installed.
+        require "pgbus/mcp/health_analyzer" unless defined?(Pgbus::MCP::HealthAnalyzer)
+
+        verdict = Pgbus::MCP::HealthAnalyzer.new(data_source_for_check).verdict
+        status = READY_STATUSES.include?(verdict[:status].to_s) ? 200 : 503
+        [status, JSON_HEADERS.dup, [verdict.to_json]]
+      rescue StandardError => e
+        Pgbus.logger.error { "[Pgbus::Web::HealthApp] readiness check failed: #{e.class}: #{e.message}" }
+        [503, JSON_HEADERS.dup, [{ status: "ERROR", error: e.message }.to_json]]
+      end
+
+      # Reuse an injected DataSource (tests, an app that wants one shared
+      # instance); otherwise build a fresh one each check so per-instance
+      # memoization can never serve stale queue/process metrics.
+      def data_source_for_check
+        @data_source || DataSource.new
+      end
+
+      def not_found
+        [404, TEXT.dup, ["pgbus: not found"]]
+      end
+
+      def method_not_allowed
+        [405, TEXT.merge("Allow" => "GET"), ["pgbus: method not allowed"]]
+      end
+    end
+  end
+end

data/lib/pgbus/web/health_server.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Pgbus
+  module Web
+    # Standalone HTTP health server for the supervisor process. When
+    # `config.health_port` is set, Supervisor#run starts one of these so a
+    # Kubernetes kubelet can probe the supervisor directly — the process that
+    # forks and watches workers — without the supervisor having to boot Rails,
+    # Puma, or the dashboard.
+    #
+    # It is intentionally tiny: one accept-loop thread over a TCPServer that
+    # reads only the HTTP request line (`GET /readyz HTTP/1.1`), synthesizes a
+    # minimal Rack env, and hands it to {HealthApp#call}. All routing and the
+    # OK/DEGRADED/STALLED → status mapping live in HealthApp, so the mounted-in-
+    # Rails path and this standalone path share exactly one implementation.
+    #
+    # This is a health probe surface, not a general HTTP server: it speaks just
+    # enough HTTP/1.0 to answer a kubelet. It only parses the request line
+    # (method + path), ignores headers and body, and closes the connection
+    # after each response (no keep-alive).
+    class HealthServer
+      # Cap the request line so a client can't stream unbounded data at the
+      # probe port. A real probe request line is well under 100 bytes.
+      MAX_REQUEST_LINE = 8_192
+      private_constant :MAX_REQUEST_LINE
+
+      STATUS_TEXT = {
+        200 => "OK", 404 => "Not Found", 405 => "Method Not Allowed", 503 => "Service Unavailable"
+      }.freeze
+      private_constant :STATUS_TEXT
+
+      # @return [Integer, nil] the bound port. Equals the configured port, or
+      #   the OS-assigned port when the configured port was 0 (used in tests).
+      #   nil before #start.
+      attr_reader :port
+
+      def initialize(port:, bind: "127.0.0.1", app: nil, logger: nil)
+        @configured_port = port
+        @bind = bind
+        @app = app || HealthApp.new
+        @logger = logger
+        @server = nil
+        @thread = nil
+        @port = nil
+      end
+
+      # Bind the port and start the accept loop. Idempotent: a second call
+      # while running is a no-op (so a supervisor restart path can't double-bind).
+      def start
+        return if @server
+
+        @server = TCPServer.new(@bind, @configured_port)
+        @port = @server.addr[1]
+        @thread = Thread.new { accept_loop }
+        logger.info { "[Pgbus::Web::HealthServer] listening on #{@bind}:#{@port} (/livez, /readyz)" }
+      end
+
+      # Close the listening socket (unblocking the accept loop, which then
+      # exits) and join the thread. Safe to call when never started or twice.
+      def stop
+        server = @server
+        @server = nil
+        close_socket(server)
+        @thread&.join(2)
+        @thread = nil
+        @port = nil
+      end
+
+      private
+
+      # accept blocks until stop closes the socket, which raises here and ends
+      # the loop. Any per-connection error is logged and swallowed so one bad
+      # client can never take the probe surface down.
+      def accept_loop
+        loop do
+          server = @server
+          break unless server
+
+          client =
+            begin
+              server.accept
+            rescue IOError, Errno::EBADF, Errno::EINVAL
+              break # socket closed by #stop
+            end
+
+          handle_client(client)
+        end
+      end
+
+      def handle_client(client)
+        method, path = read_request_line(client)
+        return unless method
+
+        status, headers, body = @app.call(rack_env(method, path))
+        write_response(client, status, headers, body)
+      rescue StandardError => e
+        logger.warn { "[Pgbus::Web::HealthServer] connection error: #{e.class}: #{e.message}" }
+      ensure
+        close_socket(client)
+      end
+
+      # Read and parse only the first line: "METHOD PATH HTTP/x.y". Returns
+      # [method, path] or [nil, nil] when the line is missing/garbage so the
+      # caller drops the connection without dispatching.
+      def read_request_line(client)
+        line = client.gets("\r\n", MAX_REQUEST_LINE)
+        return [nil, nil] if line.nil?
+
+        method, path, = line.strip.split(" ", 3)
+        return [nil, nil] if method.nil? || path.nil?
+
+        [method, path]
+      end
+
+      # Minimal Rack env — HealthApp reads only REQUEST_METHOD and PATH_INFO.
+      # Strip any query string from the path so PATH_INFO stays a bare path.
+      def rack_env(method, path)
+        { "REQUEST_METHOD" => method, "PATH_INFO" => path.split("?", 2).first }
+      end
+
+      def write_response(client, status, headers, body)
+        reason = STATUS_TEXT.fetch(status, "OK")
+        payload = Array(body).join
+        lines = ["HTTP/1.0 #{status} #{reason}"]
+        headers.each { |k, v| lines << "#{k}: #{v}" }
+        lines << "Content-Length: #{payload.bytesize}"
+        lines << "Connection: close"
+        client.write("#{lines.join("\r\n")}\r\n\r\n#{payload}")
+      end
+
+      def close_socket(socket)
+        socket&.close
+      rescue IOError, Errno::EBADF
+        nil
+      end
+
+      def logger
+        @logger || Pgbus.logger
+      end
+    end
+  end
+end

data/lib/pgbus/web/payload_filter.rb

@@ -16,7 +16,7 @@ module Pgbus
       FILTERED = "[FILTERED]"
 
       def filter(value)
-        return value unless Pgbus.configuration.dashboard_filter_sensitive
+        return value unless Pgbus.configuration.web_filter_sensitive
 
         case value
         when Hash
@@ -29,7 +29,7 @@ module Pgbus
       end
 
       def filter_json(value)
-        return value unless Pgbus.configuration.dashboard_filter_sensitive
+        return value unless Pgbus.configuration.web_filter_sensitive
 
         case value
         when nil then nil
@@ -46,7 +46,7 @@ module Pgbus
       end
 
       def parameter_filter
-        patterns = Pgbus.configuration.dashboard_filter_parameters ||
+        patterns = Pgbus.configuration.web_filter_parameters ||
                    rails_filter_parameters ||
                    DEFAULT_FILTER_PATTERNS
         ActiveSupport::ParameterFilter.new(patterns)

data/lib/pgbus/web/streamer/instance.rb

@@ -28,7 +28,8 @@ module Pgbus
           pg_connection: nil,
           logger: Pgbus.logger,
           registry: nil,
-          dispatch_queue: nil
+          dispatch_queue: nil,
+          connection_factory: nil
         )
           @client = client
           @config = config
@@ -42,7 +43,14 @@ module Pgbus
             pg_connection: @pg_connection,
             dispatch_queue: @dispatch_queue,
             health_check_ms: @config.streams_listen_health_check_ms,
-            logger: @logger
+            logger: @logger,
+            # On reconnect the Listener rebuilds its OWN connection via this
+            # factory (fresh connect re-resolves DNS, converges on the promoted
+            # primary after a failover) instead of resetting a possibly-dead
+            # socket. Always provided — even when an initial pg_connection: is
+            # injected, the reconnect path builds a fresh raw connection. A test
+            # can inject its own factory to avoid touching real configuration.
+            connection_factory: connection_factory || -> { build_raw_pg_connection }
           )
           @dispatcher = StreamEventDispatcher.new(
             client: @client,
@@ -143,7 +151,20 @@ module Pgbus
           end
         end
 
+        # Build the INITIAL LISTEN connection: raw connect, reject a replica
+        # fatally (a misconfiguration at boot), then run the one-shot delivery
+        # self-probe. The reconnect path uses build_raw_pg_connection directly
+        # (validation retries there, probe is skipped) — see the factory wired
+        # into Listener.new above.
         def build_pg_connection
+          probe(validate_primary(build_raw_pg_connection))
+        end
+
+        # Raw PG.connect with no validation or probe. This is what the Listener's
+        # connection_factory calls on every reconnect attempt: the reconnect loop
+        # runs its own PrimaryValidator (retrying on a replica) and skips the
+        # probe to stay cheap, mirroring Pgbus::Process::NotifyListener.
+        def build_raw_pg_connection
           require "pg" unless defined?(::PG::Connection)
           opts = @config.streams_connection_options
           case opts
@@ -167,6 +188,41 @@ module Pgbus
                   "Cannot build streamer PG connection from #{opts.class}"
           end
         end
+
+        # Reject a connection that landed on a read-only replica before the
+        # streamer wires it into a Listener. After a failover, stale DNS can
+        # point this fresh PG.connect at the demoted master; NOTIFY fires only
+        # on the primary, so the streamer would sit deaf. Unlike the reconnect
+        # loop (which retries), this runs once at Instance construction (Puma
+        # worker boot), so a replica here is a fatal misconfiguration: re-raise
+        # as a ConfigurationError naming the direct-connection overrides.
+        def validate_primary(pg_connection)
+          Pgbus::Process::PrimaryValidator.validate_primary!(pg_connection)
+        rescue Pgbus::Process::ReplicaConnectionError => e
+          close_quietly(pg_connection)
+          raise Pgbus::ConfigurationError,
+                "Streamer LISTEN connection landed on a read-only replica " \
+                "(#{e.message}). NOTIFY fires only on the primary, so the " \
+                "streamer would never wake. Point the streamer at a DIRECT " \
+                "primary via streams_database_url (or streams_host / " \
+                "streams_port)."
+        end
+
+        def close_quietly(pg_connection)
+          pg_connection.close if pg_connection.respond_to?(:close)
+        rescue StandardError
+          nil
+        end
+
+        # One-shot LISTEN/NOTIFY delivery self-probe on the freshly built
+        # connection. A transaction-mode pooler or replica that silently breaks
+        # NOTIFY is surfaced with an actionable error (naming the streams_*
+        # overrides); the streamer still starts and degrades to slow SSE
+        # updates rather than crashing. Returns the connection unchanged.
+        def probe(pg_connection)
+          Pgbus::Process::NotifyProbe.probe_notify_delivery!(pg_connection, logger: @logger)
+          pg_connection
+        end
       end
     end
   end

data/lib/pgbus/web/streamer/listener.rb

@@ -19,10 +19,11 @@ module Pgbus
       #
       # Health check: `wait_for_notify(timeout)` returns nil on timeout. When
       # it does, the listener runs `SELECT 1` as a TCP keepalive. If that
-      # raises, the connection is reset (`conn.reset`) and every channel in
-      # `@listening_to` is re-LISTENed. This is the fix for design doc §11 #1
-      # (silently dropped LISTEN connections from NAT / PG restart / network
-      # blips).
+      # raises, the listener rebuilds a FRESH connection via connection_factory
+      # and re-LISTENs every channel in `@listening_to`. This is the fix for
+      # design doc §11 #1 (silently dropped LISTEN connections from NAT / PG
+      # restart / network blips) — a fresh connect also re-resolves DNS and
+      # converges on the promoted primary after a failover.
       #
       # NOTIFY channel naming (from pgmq_v1.11.0.sql:1634):
       #   PG_NOTIFY('pgmq.' || TG_TABLE_NAME || '.' || TG_OP, NULL)
@@ -38,13 +39,24 @@ module Pgbus
         CHANNEL_PREFIX = "pgmq.q_"
         CHANNEL_SUFFIX = ".INSERT"
 
+        RECONNECT_BACKOFF_SECONDS = 0.5
+
         attr_reader :listening_to
 
-        def initialize(pg_connection:, dispatch_queue:, health_check_ms:, logger: Pgbus.logger)
+        # @param connection_factory [#call] builds a FRESH PG connection on each
+        #   reconnect attempt (the Instance passes -> { build_raw_pg_connection }).
+        #   Required — the reconnect loop always rebuilds rather than resetting a
+        #   possibly-dead socket, so every caller (production and tests) must pass
+        #   one.
+        def initialize(pg_connection:, dispatch_queue:, health_check_ms:,
+                       connection_factory:, logger: Pgbus.logger)
+          raise ArgumentError, "connection_factory is required" unless connection_factory.respond_to?(:call)
+
           @conn = pg_connection
           @dispatch_queue = dispatch_queue
           @health_check_ms = health_check_ms
           @logger = logger
+          @connection_factory = connection_factory
           @listening_to = Set.new
           @commands = Queue.new
           @running = false
@@ -197,28 +209,64 @@ module Pgbus
           @conn.exec("SELECT 1")
         end
 
+        # Retry reconnect until we succeed (fresh conn + every channel
+        # re-LISTENed) or #stop flips @running to false. Mirrors
+        # NotifyListener#reconnect!: a single failed attempt never returns with
+        # a dead connection while running, so ensure_listening acks can't
+        # succeed vacuously against a broken LISTEN socket and strand SSE
+        # clients.
         def reconnect!
-          @conn.reset
-          # Don't clear @listening_to until the new set is built. If a
-          # mid-loop LISTEN raises, we keep the original set so the
-          # next reconnect cycle still knows which channels need to
-          # come back. The previous version cleared first and lost
-          # any channels not yet retried on a transient error.
-          to_relisten = @listening_to.to_a
-          new_listening = Set.new
-          to_relisten.each do |channel|
-            @conn.exec(%(LISTEN "#{channel}"))
-            new_listening.add(channel)
+          # Snapshot the canonical subscription set BEFORE tearing down the old
+          # connection. We rebuild @listening_to from this and only publish it
+          # once every channel has been re-LISTENed on the new conn, so a
+          # mid-loop LISTEN failure never loses channels.
+          channels = @listening_to.to_a
+          loop do
+            return unless @running
+
+            close_quietly(@conn)
+            @conn = nil
+            new_conn = nil
+            begin
+              new_conn = @connection_factory.call
+              # Reject a replica before re-LISTENing. A fresh connect re-resolves
+              # DNS, so backing off and retrying converges on the promoted primary
+              # once DNS catches up after a failover. NOTIFY fires only on the
+              # primary; re-LISTENing on a replica registers channels that never wake.
+              Pgbus::Process::PrimaryValidator.validate_primary!(new_conn)
+              channels.each { |channel| new_conn.exec(%(LISTEN "#{channel}")) }
+            rescue PG::Error, Pgbus::Process::ReplicaConnectionError, Pgbus::ConfigurationError => e
+              # The factory may raise a ConfigurationError (a bad
+              # streams_connection_options, e.g. a pooled AR connection) or return
+              # a live conn before a later LISTEN raised (or validate_primary!
+              # rejected a replica). Close any partial conn so repeated failures
+              # don't leak PG connections, then back off and retry rather than
+              # letting the exception kill the listener thread silently.
+              close_quietly(new_conn)
+              @logger.error { "[Pgbus::Streamer::Listener] reconnect failed: #{e.class}: #{e.message}" }
+              sleep RECONNECT_BACKOFF_SECONDS
+              next
+            end
+
+            @conn = new_conn
+            @listening_to = Set.new(channels)
+            return
           end
-          @listening_to = new_listening
-        rescue PG::Error => e
-          @logger.error { "[Pgbus::Streamer::Listener] reconnect failed: #{e.class}: #{e.message}" }
-          sleep 0.5
+        end
+
+        # Close a PG connection we're discarding (the old conn at the top of a
+        # reconnect cycle, or a half-built one whose LISTEN raised). Best-effort.
+        def close_quietly(conn)
+          conn&.close if conn.respond_to?(:close)
+        rescue StandardError
+          nil
         end
 
         def safe_unlisten_all
           @listening_to.each do |channel|
-            @conn.exec(%(UNLISTEN "#{channel}"))
+            # @conn may be nil if #stop interrupted the reconnect loop between
+            # closing the old connection and publishing a new one.
+            @conn&.exec(%(UNLISTEN "#{channel}"))
           rescue PG::Error
             # connection may be dead; nothing we can do
           end

data/lib/pgbus.rb

@@ -10,6 +10,24 @@ module Pgbus
   # this to be configurable.
   DEAD_LETTER_SUFFIX = "_dlq"
 
+  # Error-hierarchy policy (the 1.0 contract, issue #282):
+  #
+  #   * OPERATIONAL errors — a pgbus subsystem failed to do its job at runtime
+  #     (bad configuration, a pool that's shutting down, a batch enqueue that
+  #     came back short, a rejected GlobalID, a missing PGMQ version) — descend
+  #     from Pgbus::Error. `rescue Pgbus::Error` is meant to catch every one of
+  #     them; that is the whole point of the hierarchy.
+  #
+  #   * ARGUMENT-SHAPE errors — the caller handed a method a malformed argument
+  #     (a stream name too long for the queue-name budget, an unparseable
+  #     cursor, a capsule DSL line that doesn't parse) — stay ArgumentError
+  #     subclasses. That's what ArgumentError means, and rescuing it is the
+  #     caller's responsibility, not an operational concern. These live in
+  #     their own files: Streams::StreamNameTooLong, Streams::Cursor::InvalidCursor,
+  #     Configuration::CapsuleDSL::ParseError.
+  #
+  # When adding a new error class, decide which half it belongs to and parent
+  # it accordingly — do not default to StandardError.
   class Error < StandardError; end
   class ConfigurationError < Error; end
   class SerializationError < Error; end
@@ -20,6 +38,41 @@ module Pgbus
   class SchemaNotReady < Error; end
   class ReadTimeoutError < Error; end
 
+  # Raised by the ActiveJob adapter when a batch enqueue (perform_all_later)
+  # comes back with a msg_id count that doesn't match the number of jobs sent —
+  # a data-integrity signal that some jobs may not have been persisted.
+  class EnqueueError < Error; end
+
+  # Raised by the execution pools when work can't be accepted: the pool is
+  # shutting down, or it's momentarily at capacity. Consumer-reachable during
+  # job submission, so it descends from Pgbus::Error rather than RuntimeError.
+  class ExecutionPoolError < Error; end
+
+  # Raised by Client read paths when the in-memory connection-health circuit
+  # breaker (Client::ConnectionHealth) is open: the database has failed enough
+  # consecutive connection attempts that reads now fail fast without a pool
+  # checkout, sparing a dead database from the whole fleet re-polling and the
+  # error tracker from per-poll noise. Workers rescue this and idle until the
+  # breaker's backoff window admits a probe. See issue #197.
+  class ConnectionCircuitOpenError < Error; end
+
+  module Process
+    # A LISTEN connection landed on a read-only replica (pg_is_in_recovery() =>
+    # t). After a failover, stale DNS can point a fresh connection at the
+    # demoted master; NOTIFY fires only on the primary, so such a connection
+    # connects "successfully" but never wakes. Raised by
+    # Process::PrimaryValidator so the listener rejects it and retries with
+    # backoff (re-resolving DNS each attempt).
+    #
+    # Defined here rather than in process/primary_validator.rb because Zeitwerk
+    # requires each managed file to define exactly the constant matching its
+    # path — a second class in that file would break eager_load. lib/pgbus.rb
+    # is the (require-loaded) gem entry point, so it can define the error and
+    # explicitly namespace Process without conflicting with Zeitwerk's
+    # management of the lib/pgbus/process/ directory.
+    class ReplicaConnectionError < Error; end
+  end
+
   class << self
     # Process-global flag set by Worker#graceful_shutdown so the adapter
     # can report stopping? to ActiveJob::Continuation (Rails 8.1+).
@@ -35,6 +88,7 @@ module Pgbus
         loader.inflector.inflect(
           "pgbus" => "Pgbus",
           "cli" => "CLI",
+          "dlq" => "DLQ",
           "dsl" => "DSL",
           "capsule_dsl" => "CapsuleDSL",
           "mcp" => "MCP"
@@ -92,6 +146,11 @@ module Pgbus
 
     def configure
       yield configuration
+      # Fail loud at boot on an invalid value rather than leaving it dormant
+      # until a worker path consumes it. Checking the flag after the yield
+      # lets a block opt out for itself via `c.eager_validation = false`.
+      configuration.validate! if configuration.eager_validation
+      configuration
     end
 
     def client
@@ -150,6 +209,24 @@ module Pgbus
       Streams::Key.stream_key!(key)
     end
 
+    # Publish an event to the bus — the top-level shortcut for
+    # `Pgbus::EventBus::Publisher.publish`, symmetric with `Pgbus.stream`.
+    #
+    #   Pgbus.publish("orders.created", { order_id: 42 })
+    #   Pgbus.publish("orders.created", order, headers: { "x-trace" => id }, delay: 30)
+    def publish(routing_key, payload, headers: nil, delay: 0)
+      EventBus::Publisher.publish(routing_key, payload, headers: headers, delay: delay)
+    end
+
+    # Publish an event with a delay. Mirrors
+    # `Pgbus::EventBus::Publisher.publish_later`; `delay:` is required (a
+    # publish_later with no delay is just publish).
+    #
+    #   Pgbus.publish_later("orders.reminder", { order_id: 42 }, delay: 1.hour)
+    def publish_later(routing_key, payload, delay:, headers: nil)
+      EventBus::Publisher.publish_later(routing_key, payload, delay: delay, headers: headers)
+    end
+
     def reset!
       @client&.close
       @client = nil

data/lib/tasks/pgbus_doctor.rake

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+namespace :pgbus do
+  desc "Run environment diagnostics (config, DB, PGMQ, queues, LISTEN/NOTIFY, process liveness)"
+  task doctor: :environment do
+    require "pgbus/doctor"
+
+    doctor = Pgbus::Doctor.new
+    puts doctor.report
+    exit 1 unless doctor.success?
+  end
+end