pgbus 0.12.0 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2e4a0eacc67a1d3edf2fa7aae4ffd835cf03ae275f016aa92c2f490923897cd
-  data.tar.gz: defeb677222dc6ac50c755225e3da9b57752667e03569af747f1f8a26974b95d
+  metadata.gz: a966ed340b2cd097f82b926f90647a0d481df35da76bb4ef06f4e3c13e3d5692
+  data.tar.gz: 779124d08216918b02a162f2a1263c4115cd7a7fb9404dc0055dc940da28793f
 SHA512:
-  metadata.gz: 2a9b8e1d6efa1106a5f56325d48bae1bcc650916154e54ccffa675fa9a5fde887f412536ca6d40d56e907ec804de66b3b1ca2000c5c66142889d9f8ff07dce3d
-  data.tar.gz: 0f5da2baedef6ad70d304e1d91339a6f7613687c642d40bb7b52fd508d198fde5840a22b2f42f2a0bbf3429aea7b9f8f1c71d20d63e35dbaa29b787b43fb4601
+  metadata.gz: b25519a1d9ea9e1e2700b959a5ebcf03adf8efbcb130001f1e962067e0def2546b1644e199d24d2b849b29ba67f15bc83eef5f41506ffde3d6ea5d79da752af7
+  data.tar.gz: f0ec03ccc2b075b90f6b87cc5eb1315d5d3834b2cdd7c9c19fc851f350196f6860b941ec0566aac0315f531bf29356f9a1f94b68e852aa497eb642833ddc3800

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+### Fixed
+
+- **`streams_pool_database_url` / `streams_pool_host` / `streams_pool_port` — route the streams PGMQ pool independently of the streamer's LISTEN connection (issue #358).** 0.12.0 started building the dedicated streams pool from `streams_connection_options` (correct for a separate streams database), but that method is also how pooler-bypass installs pin the LISTEN connection to the **direct** Postgres port (`streams_port = 5432`, the documented "workers go through PgBouncer, streamer goes direct" pattern) — so upgrading silently moved up to `streams_pool_size` connections **per process** onto the direct port, whose `max_connections` ceiling on managed Postgres is typically low. A modest fleet exhausts it (`FATAL: remaining connection slots are reserved for roles with the SUPERUSER attribute`): `StreamApp` then 500s every SSE connect and durable broadcasts fail at publish, intermittently, because the pools are lazy. Only LISTEN actually needs the direct port (it dies at transaction-pool COMMIT boundaries); the pool's broadcast INSERTs and replay reads are plain pooler-safe SQL. The new `streams_pool_*` triple routes the POOL independently — applied to the base options exactly like the `streams_*` and `worker_notify_*` groups: set `streams_pool_port` back to the pooled port and only the LISTEN pins remain direct. Default `nil` = follows `streams_connection_options`, byte-identical to 0.12.0, so separate-streams-DB installs are unchanged. Refs #358.
+- **The health verdict no longer reads durable stream queues as a wedged fleet (issue #359).** The Process-liveness signal (`pgbus doctor`, `pgbus_health`, the MCP health tool) treats *visible messages with `read_ct=0` while workers are alive* as the silent-worker-wedge signature — but durable stream delivery is a non-consuming peek, so **every** stream queue matches it permanently by design. On a streams-heavy install the verdict screamed STALLED listing hundreds of healthy stream queues, burying real wedges in noise. `HealthAnalyzer` now excludes queues registered in the `pgbus_stream_queues` registry from the operational set (exactly like DLQs) — out of the STALLED/DEGRADED reasons and the backlog totals — via a new `Web::DataSource#stream_queue_names` (loaded fresh per verdict; degrades to an empty set on pre-registry installs). Same bug class as #308/#309, same registry cure. Refs #359.
+- **The `upgrade_pgmq` migration no longer silently kills NOTIFY-gated wakeups fleet-wide (issue #360).** The generated migration drops every pgmq function **with CASCADE** — which also drops the `trigger_notify_queue_insert_listeners` trigger from every existing queue table (it depends on the dropped `pgmq.notify_queue_listeners()`), and `install_sql` re-created the functions but never the per-queue triggers. Result: after every PGMQ schema upgrade, NOTIFY wakeups (#174) silently died and workers fell back to `polling_interval` polling — nothing errored; latency degraded and DB poll load rose. Trigger re-install only happened in `ensure_single_queue` (per-process memoized), so on the common deploy ordering where the job supervisor boots *before* migrations run, the supervisor installed triggers at boot and the migration wiped them minutes later — with nothing left to re-install them until a full process restart. New `PgmqSchema.reinstall_notify_triggers_sql` replays `pgmq.enable_notify_insert` for every row in `pgmq.notify_insert_throttle` (a table, preserved by the upgrade, recording exactly which queues had notify and at what throttle; the function is idempotent), and the migration template runs it after `install_sql` — restoring every trigger at its original interval. No-op on vendored versions without the notify feature. **Already ran an upgrade migration?** Run `Pgbus::PgmqSchema.reinstall_notify_triggers_sql` once (e.g. from a console: `ActiveRecord::Base.connection.execute(...)`) or restart the fleet; `pgbus doctor`'s LISTEN/NOTIFY check confirms the repair. Refs #360.
+
 ### Breaking Changes
 
 - **`config.validate!` now rejects malformed values for 12 core config keys at boot instead of failing deep in a worker or silently misbehaving (issue #335).** Before the 1.0 surface freeze, these headline job-path keys had **zero** validation while streams keys had 14 checks — so a bad value surfaced as a crash inside a worker/dispatcher/poller/scheduler thread, per-enqueue, or by silently corrupting every derived queue name / leaving the dashboard open. `Pgbus.configure` (eager-validating by default) now raises `Pgbus::ConfigurationError` naming the key for: the worker-recycling trio `max_jobs_per_worker`/`max_memory_mb`/`max_worker_lifetime` (positive number or `nil` to disable); the intervals `dispatch_interval`/`outbox_poll_interval`/`recurring_schedule_interval` (positive number); `outbox_batch_size` (positive integer); `default_priority` (non-negative integer — `0` is a valid level); `queue_prefix`/`default_queue` (non-empty String — an empty prefix silently produced malformed queue names); `web_auth` (a callable or `nil` — a non-callable silently left the dashboard open); `error_reporters` (an Array); and `connects_to` (a Hash or `nil` — previously a malformed value raised a raw `TypeError` deep in engine boot). This only rejects configuration that was already broken; if a `Pgbus.configure` block set one of these to an invalid value it will now fail loudly at boot (the intended pre-freeze tightening). Set `config.eager_validation = false` to defer. Refs #335, #282.
@@ -38,6 +44,7 @@
 
 ### Fixed
 
+- **`ensures_uniqueness` / `limits_concurrency` declared on a base class now reach every subclass — previously the declaration was silently inert for them (issue #357).** Both macros stored their config in a class-level ivar (`@pgbus_uniqueness` / `@pgbus_concurrency`) and every lookup read `active_job.class.pgbus_uniqueness` without walking ancestors — class-level ivars are not inherited in Ruby, so `class RecurringBase < ApplicationJob; ensures_uniqueness strategy: :until_executed; end` gave subclasses NO uniqueness key, no scheduler overlap protection, and no #333 guard, with no warning that the natural reading of the code was false. The readers now fall back to the nearest ancestor's declaration (a class's own declaration still beats an inherited one). Coupled fix, required to make inheritance safe rather than harmful: no default key proc is stored anymore — the old `key || ->(*) { name }` captured the DECLARING class, so an inheritance fix alone would have collapsed every subclass into ONE shared key (the base class's name), and with `on_conflict: :discard` sibling jobs would silently discard each other's enqueues — strictly worse than inert. The class-name default is now resolved from the ENQUEUED job's class at all three call sites (`Uniqueness.resolve_key`, `Concurrency.resolve_key`, and the recurring scheduler's `resolve_uniqueness_key`), and `config[:key]` is `nil` when no explicit `key:` was given. Consumer note: concrete-class declarations resolve to exactly the same keys as before, but a base-class declaration that was silently inert now ACTIVATES per-subclass uniqueness/concurrency on upgrade — audit any base-class declarations (the macro finally does what it says). In the scheduler path the no-key default is additionally qualified with the recurring task's `args:` (`SyncJob:["site_a"]`) so two tasks pointing at the same job class with different arguments don't share one lock — the scheduler's analogue of the #333 raise-at-enqueue guard, which a scheduler loop can't use — and a failure to resolve ANY uniqueness key — default or user-supplied key proc — now fails closed (skips the tick, logs, and reaches `error_reporters`) instead of degrading to nil and enqueuing WITHOUT a lock, which silently disabled the very protection the proc configured. Both macros also now reject a non-nil, non-callable `key:` (e.g. `key: false`) at definition time with the documented ArgumentError — previously `false` slipped the truthiness guard and surfaced as a `NoMethodError` at enqueue (uniqueness) or silently acted as the class-name default (concurrency). Measured (benchmark-ips, enqueue-path budget per docs/performance.md): the shared `Support.call_key_proc` dispatch is ~17% faster than the old inline dispatch (136ns vs 160ns/op), the class-name default is 3.7× faster than the old stored-proc call (23ns vs 86ns/op), and the inherited-config ancestor walk adds ~15ns/op. Refs #357, #333.
 - **The Ruby-Timeout read fallback no longer leaves a wedged `CONNECTION_OK` connection in the pgmq pool to re-hang the next read (issue #354).** On the one path where libpq can't bound a hung socket (dedicated connection on non-Linux hosts or libpq < 12), the last-resort `Timeout.timeout` interrupts the read via `Thread#raise` — and libpq may leave the pooled `PG::Connection` reporting `CONNECTION_OK` while it will in fact re-hang on reuse, invisible to pgmq-ruby's checkout health check (it isn't `CONNECTION_BAD`). This was a documented KNOWN LIMITATION waiting on a public pool-reload upstream (cf. mensfeld/pgmq-ruby#94); pgmq-ruby 0.7.1 shipped it, so the fallback now raises an internal `ReadTimeoutError` subclass and reloads the job pool before re-raising — the poisoned connection (already checked back in by `connection_pool`'s ensure) is dropped and the pool rebuilds lazily. A clean server-side `statement_timeout` cancel still never triggers a reload (the connection is healthy), and a reload failure is logged without masking the timeout. Requires pgmq-ruby >= 0.7.1 (dependency bumped to `~> 0.7.1`). Refs #354.
 - **`connection_guc_mode = :session` no longer kills every SSE stream and NOTIFY wakeup with `PG::Error: invalid connection option "variables"` (issue #352).** In `:session` mode, `forward_connection_variables` deliberately leaves the database.yml `variables:` hash on the connection options for the *caller* to strip and apply via post-connect `SET` (a transaction-mode pooler rejects the libpq `options` startup param — the reason `:session` mode exists). `Pgbus::Client#wrap_session_gucs` honors that contract on both pgmq pools, but the two dedicated raw-connect paths — the streamer's `build_raw_pg_connection` and the worker `NotifyListener` — passed the hash straight to `PG.connect`, which rejects the non-libpq `:variables` key. Result: the first stream request per process raised, `StreamApp` rescued it into a 500 (so **every** `/pgbus/streams/…` request failed from then on), and NOTIFY-gated wakeups died with workers silently falling back to polling. Both paths now connect through the new `Pgbus::DedicatedConnection.connect`, which strips `:variables` and applies each GUC via post-connect `SET` — dedicated connections *keep* the operator's GUCs (`statement_timeout`, `timezone`, …), matching the pooled paths, and the mechanism works on both a direct port and a session-mode pooler. A guard spec confines raw `PG.connect` call sites to `Client` and `DedicatedConnection`, so the next dedicated-connection path can't silently reintroduce the bypass. Refs #352.
 - **AppSignal main dashboard: job and event lines now split by `job_class` and `routing_key`.** Applied the upstream review suggestions committed on appsignal/public_config#80 to the vendored `dashboard.json`: the "Job status per queue" panel gains a `job_class` wildcard tag filter and label (`%job_class% - %queue% - %status%`), and "Event handler status" gains `routing_key` (`%handler% - %status% - %routing_key%`). Without the wildcard tag entry a `%placeholder%` in the line label never resolves, so lines from different job classes / routing keys were collapsed together. The subscriber already emitted both tags; only the dashboard definition lagged.

data/lib/generators/pgbus/templates/upgrade_pgmq.rb.erb

@@ -8,6 +8,13 @@ class UpgradePgmqToV<%= target_version_slug.camelize %> < ActiveRecord::Migratio
     # This uses the vendored SQL which doesn't require the pgmq extension.
     execute Pgbus::PgmqSchema.install_sql("<%= target_version %>")
 
+    # Re-install the per-queue NOTIFY insert triggers the function drop
+    # cascaded away (pgmq.notify_insert_throttle records which queues had
+    # them and at what throttle; enable_notify_insert is idempotent).
+    # Without this, NOTIFY-gated wakeups silently die and workers fall back
+    # to polling until each queue is re-ensured by a process restart.
+    execute Pgbus::PgmqSchema.reinstall_notify_triggers_sql
+
     # Record the upgrade
     execute <<~SQL
       CREATE TABLE IF NOT EXISTS pgbus_pgmq_schema_versions (

data/lib/pgbus/client.rb

@@ -89,15 +89,17 @@ module Pgbus
         # persistent connection instead of a fresh PG.connect per call. Its own
         # PGMQ::Client → its own connection_pool, sized independently of worker
         # thread counts.
-        # Build the streams pool from streams_connection_options (which defaults
-        # to connection_options but honors streams_database_url/host/port for a
-        # separate/direct streams DB — issue #315), bounds-applied, and tagged
-        # with a per-process application_name so the autoscaler can count peer
-        # processes from pg_stat_activity (issue #323 P1/P2). Snapshot it so a
-        # hot-swap rebuilds a byte-identical pool at a new size.
+        # Build the streams pool from streams_pool_connection_options (defaults
+        # to streams_connection_options so a separate streams DB carries the
+        # pool with it — issue #315 — but overridable via streams_pool_* so a
+        # pooler-bypass install keeps the pool off the direct port — issue
+        # #358), bounds-applied, and tagged with a per-process application_name
+        # so the autoscaler can count peer processes from pg_stat_activity
+        # (issue #323 P1/P2). Snapshot it so a hot-swap rebuilds a
+        # byte-identical pool at a new size.
         @streams_conn_opts = wrap_session_gucs(
           tag_application_name(
-            apply_connection_bounds(config.streams_connection_options)
+            apply_connection_bounds(config.streams_pool_connection_options)
           )
         )
         @streams_pgmq = PGMQ::Client.new(@streams_conn_opts, pool_size: config.streams_pool_size,

data/lib/pgbus/concurrency.rb

@@ -16,25 +16,30 @@ module Pgbus
       #
       # Options:
       #   to:          Maximum concurrent jobs for the same key (required)
-      #   key:         Proc receiving job arguments, returns a string key. Default: job class name.
+      #   key:         Proc receiving job arguments, returns a string key.
+      #                Default: the ENQUEUED job's class name (resolved at
+      #                resolve time, so an inherited declaration keys each
+      #                subclass separately — issue #357).
       #   duration:    Safety expiry for semaphore (default: 15 minutes)
       #   on_conflict: What to do when limit is reached — :block, :discard, or :raise (default: :block)
       def limits_concurrency(to:, key: nil, duration: 15 * 60, on_conflict: :block) # rubocop:disable Naming/MethodParameterName
         raise ArgumentError, "to: must be a positive integer" unless to.is_a?(Integer) && to.positive?
         raise ArgumentError, "on_conflict must be :block, :discard, or :raise" unless %i[block discard raise].include?(on_conflict)
         raise ArgumentError, "duration must be a positive number" unless duration.is_a?(Numeric) && duration.positive?
-        raise ArgumentError, "key must be callable (Proc or lambda)" if key && !key.respond_to?(:call)
+        raise ArgumentError, "key must be callable (Proc or lambda)" if !key.nil? && !key.respond_to?(:call)
 
         @pgbus_concurrency = {
           limit: to,
-          key: key || ->(*) { name },
+          key: key,
           duration: duration,
           on_conflict: on_conflict
         }.freeze
       end
 
+      # The nearest declaration in the ancestor chain wins — same inheritance
+      # contract as Uniqueness#pgbus_uniqueness (issue #357).
       def pgbus_concurrency
-        @pgbus_concurrency
+        @pgbus_concurrency || (superclass.pgbus_concurrency if superclass.respond_to?(:pgbus_concurrency))
       end
     end
 
@@ -47,13 +52,11 @@ module Pgbus
         config = active_job.class.pgbus_concurrency
         return nil unless config
 
-        args = active_job.arguments
-        last = args.last
-        if last.is_a?(Hash) && last.each_key.all?(Symbol)
-          config[:key].call(*args[...-1], **last)
-        else
-          config[:key].call(*args)
-        end
+        # Class-name default, resolved from the ENQUEUED job's class so an
+        # inherited declaration keys each subclass separately (#357).
+        return active_job.class.name unless config[:key]
+
+        Support.call_key_proc(config[:key], active_job.arguments)
       end
 
       # Inject the resolved concurrency key into the job's serialized payload.

data/lib/pgbus/configuration.rb

@@ -167,6 +167,7 @@ module Pgbus
                   :streams_durable_patterns, :streams_broadcast_queue,
                   :streams_presence_patterns, :streams_presence_member,
                   :streams_host, :streams_port, :streams_database_url,
+                  :streams_pool_host, :streams_pool_port, :streams_pool_database_url,
                   :streams_pool_size, :streams_pool_timeout,
                   :streams_fanout_write_deadline_ms, :streams_dispatch_queue_limit,
                   :streams_writer_threads, :streams_writer_buffer_limit,
@@ -338,6 +339,22 @@ module Pgbus
       # thread-safe and streams keep using the single serialized connection.
       @streams_pool_size = 5
       @streams_pool_timeout = 5
+      # Streams-POOL-only connection overrides (issue #358). The pool above
+      # defaults to wherever the streamer connects (streams_host/port/
+      # database_url), which is right for a separate streams database — but
+      # wrong for the pooler-bypass pattern, where streams_port pins the
+      # LISTEN connection to the direct Postgres port purely because LISTEN
+      # dies in transaction pooling. The pool's traffic (broadcast INSERTs,
+      # replay reads) is plain pooler-safe SQL, and on a direct port with a
+      # low max_connections ceiling every process's streams_pool_size
+      # connections eat scarce direct slots. Set any of these to route the
+      # POOL independently of the LISTEN connection:
+      #
+      #   c.streams_port = 5432        # LISTEN bypasses the pooler
+      #   c.streams_pool_port = 6432   # the pool stays on the pooler
+      @streams_pool_host = nil
+      @streams_pool_port = nil
+      @streams_pool_database_url = nil
       # Self-tuning streams-pool autoscaling (issue #323). Opt-in, default off.
       # When true, a per-web-process control loop grows the dedicated streams
       # pool into a FAIR SHARE of live Postgres connection headroom under
@@ -1214,6 +1231,33 @@ module Pgbus
       override_connection_options(url: streams_database_url, host: streams_host, port: streams_port)
     end
 
+    # Connection options for the dedicated streams PGMQ pool — durable-broadcast
+    # publish INSERTs and the dispatcher's replay reads (issue #315). Defaults
+    # to `streams_connection_options`, so a genuinely separate streams database
+    # carries the pool with it. When any of `streams_pool_database_url` /
+    # `streams_pool_host` / `streams_pool_port` is set, the pool is routed
+    # independently — applied to the BASE options, exactly like the other two
+    # override groups.
+    #
+    # Why this exists (issue #358): only the streamer's LISTEN connection needs
+    # to bypass a transaction-mode pooler (LISTEN dies at COMMIT boundaries);
+    # the pool's INSERT/SELECT traffic is pooler-safe. Without this split, a
+    # `streams_port` direct-port pin drags streams_pool_size connections per
+    # process onto the direct port's low max_connections ceiling:
+    #
+    #   c.streams_port = 5432        # LISTEN bypasses the pooler
+    #   c.streams_pool_port = 6432   # the pool stays on the pooler
+    #
+    # Precedence: streams_pool_database_url > streams_pool_host/port over the
+    # base > streams_connection_options.
+    def streams_pool_connection_options
+      return streams_connection_options unless streams_pool_database_url || streams_pool_host || streams_pool_port
+
+      override_connection_options(
+        url: streams_pool_database_url, host: streams_pool_host, port: streams_pool_port
+      )
+    end
+
     # Connection options for the Worker's dedicated NotifyListener connection.
     # Mirrors streams_connection_options: defaults to the base connection_options,
     # overridable via worker_notify_database_url / worker_notify_host /

data/lib/pgbus/mcp/health_analyzer.rb

@@ -32,13 +32,19 @@ module Pgbus
       def verdict
         queues          = @data_source.queues_with_metrics
         processes       = @data_source.processes
+        stream_names    = @data_source.stream_queue_names
         health, health_error = safe_queue_health
 
-        # Partition queues once: non-DLQ (the operational set) and the subset
-        # of those with visible, claimable backlog. Paused queues are removed
-        # from the STALLED backlog (an intentional pause is not the wedge —
-        # it's reported under DEGRADED), but kept in `non_dlq` for the summary.
-        non_dlq = queues.reject { |q| dlq?(q) }
+        # Partition queues once: the operational set excludes DLQs and
+        # registered stream queues, and the backlog is the subset with
+        # visible, claimable messages. Stream queues are excluded like DLQs
+        # (issue #359): stream delivery is a non-consuming peek, so their
+        # messages are permanently visible with read_ct=0 — exactly the wedge
+        # signature — and counting them makes the verdict scream STALLED on
+        # every streams-heavy install. Paused queues are removed from the
+        # STALLED backlog (an intentional pause is not the wedge — it's
+        # reported under DEGRADED), but kept in `non_dlq` for the summary.
+        non_dlq = queues.reject { |q| dlq?(q) || stream_names.include?(q[:name].to_s) }
         backlog = non_dlq.select { |q| q[:queue_visible_length].to_i.positive? }
         active_backlog = backlog.reject { |q| q[:paused] }
 

data/lib/pgbus/pgmq_schema.rb

@@ -135,6 +135,46 @@ module Pgbus
         SQL
       end
 
+      # SQL to re-install the per-queue NOTIFY insert triggers that
+      # drop_pgmq_functions_sql cascades away (issue #360). Dropping
+      # pgmq.notify_queue_listeners() with CASCADE also drops the
+      # trigger_notify_queue_insert_listeners trigger from every queue table;
+      # install_sql re-creates the function but nothing re-creates the
+      # triggers, so NOTIFY-gated wakeups silently die fleet-wide until each
+      # queue happens to be re-ensured by a process restart.
+      #
+      # The dropped state is fully recoverable: pgmq.notify_insert_throttle is
+      # a TABLE (preserved by the upgrade — its rows record exactly which
+      # queues had notify enabled and at what throttle, FK-bound to pgmq.meta
+      # so it can't reference a dropped queue), and pgmq.enable_notify_insert
+      # is idempotent. Replaying it per recorded row restores every trigger at
+      # its original interval. No-ops when the throttle table or the enable
+      # function is absent (a vendored version without the notify feature).
+      def reinstall_notify_triggers_sql
+        <<~SQL
+          DO $$
+          DECLARE
+            r RECORD;
+          BEGIN
+            IF to_regclass('pgmq.notify_insert_throttle') IS NULL THEN
+              RETURN;
+            END IF;
+            IF to_regprocedure('pgmq.enable_notify_insert(text, integer)') IS NULL THEN
+              RETURN;
+            END IF;
+
+            -- The FOR loop iterates a snapshot, so enable_notify_insert's
+            -- internal DELETE + re-INSERT of the same throttle row is safe.
+            FOR r IN
+              SELECT queue_name, throttle_interval_ms
+              FROM pgmq.notify_insert_throttle
+            LOOP
+              PERFORM pgmq.enable_notify_insert(r.queue_name, r.throttle_interval_ms);
+            END LOOP;
+          END $$;
+        SQL
+      end
+
       private
 
       # Strips extension-specific blocks (pg_extension_config_dump, pg_depend checks)

data/lib/pgbus/recurring/schedule.rb

@@ -139,7 +139,7 @@ module Pgbus
         return nil unless config
         return nil unless config[:strategy] == :until_executed
 
-        key = resolve_uniqueness_key(config, task)
+        key = resolve_uniqueness_key(job_class, config, task)
         return nil unless key
 
         acquired = UniquenessKey.acquire!(key, queue_name: resolve_queue(task), msg_id: 0)
@@ -155,6 +155,7 @@ module Pgbus
           "[Pgbus] Uniqueness lock check failed for #{task.key}: #{e.class}: #{e.message} — " \
             "skipping enqueue to prevent duplicates"
         end
+        ErrorReporter.report(e, { action: "recurring_uniqueness_lock", task: task.key })
         :already_locked # Fail closed — skip enqueue when lock check errors
       end
 
@@ -168,19 +169,39 @@ module Pgbus
       end
 
       # Resolve the uniqueness key for a recurring task.
-      # For no-argument recurring jobs, the key defaults to the class name.
-      def resolve_uniqueness_key(config, task)
+      # With no explicit key: the key is the SCHEDULED job class's name —
+      # resolved here, not via a stored proc, so a declaration inherited from
+      # a base class keys each subclass separately (issue #357) — qualified
+      # with the task's arguments so two recurring tasks pointing at the same
+      # job class with different args: don't share one lock (the scheduler
+      # can't use #333's raise-at-enqueue guard, so it disambiguates instead).
+      #
+      # Every failure here — default path or user-supplied key proc — must
+      # propagate to acquire_uniqueness_lock's fail-closed rescue (skip this
+      # tick, log, report). Returning nil instead would mean "no key
+      # configured", and the task would be enqueued WITHOUT a lock: a broken
+      # key proc silently disabling the very protection it configures. The
+      # warn adds the failing-proc context before re-raising.
+      def resolve_uniqueness_key(job_class, config, task)
         key_proc = config[:key]
         args = task.arguments || []
+        return default_uniqueness_key(job_class, args) unless key_proc
 
-        if args.empty?
-          key_proc.call
-        else
-          key_proc.call(*args)
+        begin
+          args.empty? ? key_proc.call : key_proc.call(*args)
+        rescue StandardError => e
+          Pgbus.logger.warn { "[Pgbus] Could not resolve uniqueness key for #{task.key}: #{e.message}" }
+          raise
         end
-      rescue StandardError => e
-        Pgbus.logger.warn { "[Pgbus] Could not resolve uniqueness key for #{task.key}: #{e.message}" }
-        nil
+      end
+
+      # Class-name default for the scheduler path, args-qualified so distinct
+      # argument sets get distinct locks. JSON keeps the key deterministic
+      # and readable in the dashboard/locks table.
+      def default_uniqueness_key(job_class, args)
+        return job_class.name if args.empty?
+
+        "#{job_class.name}:#{JSON.generate(args)}"
       end
 
       # Inject uniqueness metadata into the payload so the executor releases
@@ -197,7 +218,7 @@ module Pgbus
         return payload unless config
         return payload unless config[:strategy] == :until_executed
 
-        key = resolve_uniqueness_key(config, task)
+        key = resolve_uniqueness_key(job_class, config, task)
         return payload unless key
 
         payload.merge(

data/lib/pgbus/support.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Pgbus
+  # Shared internal helpers.
+  module Support
+    module_function
+
+    # Call a user-supplied key proc with a job's arguments, preserving
+    # ActiveJob's keyword-argument convention: a trailing Hash whose keys are
+    # all Symbols is splatted as keywords; everything else is positional.
+    # Single implementation for Uniqueness.resolve_key and
+    # Concurrency.resolve_key so the dispatch semantics cannot drift apart.
+    def call_key_proc(key_proc, args)
+      last = args.last
+      if last.is_a?(Hash) && last.each_key.all?(Symbol)
+        key_proc.call(*args[...-1], **last)
+      else
+        key_proc.call(*args)
+      end
+    end
+  end
+end

data/lib/pgbus/uniqueness.rb

@@ -60,7 +60,7 @@ module Pgbus
         raise ArgumentError, "unknown keyword: #{opts.keys.first.inspect}" if opts.any?
         raise ArgumentError, "strategy must be one of: #{VALID_STRATEGIES.join(", ")}" unless VALID_STRATEGIES.include?(strategy)
         raise ArgumentError, "on_conflict must be one of: #{VALID_CONFLICTS.join(", ")}" unless VALID_CONFLICTS.include?(on_conflict)
-        raise ArgumentError, "key must be callable (Proc or lambda)" if key && !key.respond_to?(:call)
+        raise ArgumentError, "key must be callable (Proc or lambda)" if !key.nil? && !key.respond_to?(:call)
 
         # Record whether an explicit key was given. With NO explicit key the key
         # defaults to the class name; that is safe for a no-argument job (one
@@ -70,16 +70,26 @@ module Pgbus
         # order into ONE per-class singleton. resolve_key raises at resolve time
         # when the class-name default meets non-empty arguments (see #333); the
         # no-arg case keeps working. explicit_key marks which is which.
+        #
+        # No proc is stored for the default — resolve_key derives it from the
+        # ENQUEUED job's class. A stored `->(*) { name }` would capture the
+        # DECLARING class, so a base-class declaration would collapse every
+        # subclass into one shared key once configs became inheritable (#357).
         @pgbus_uniqueness = {
           strategy: strategy,
-          key: key || ->(*) { name },
+          key: key,
           explicit_key: !key.nil?,
           on_conflict: on_conflict
         }.freeze
       end
 
+      # The nearest declaration in the ancestor chain wins: a class's own
+      # `ensures_uniqueness` beats an inherited one, and a base-class
+      # declaration reaches every subclass (issue #357 — class-level ivars
+      # don't inherit, so without the superclass walk a base declaration was
+      # silently inert for subclasses).
       def pgbus_uniqueness
-        @pgbus_uniqueness
+        @pgbus_uniqueness || (superclass.pgbus_uniqueness if superclass.respond_to?(:pgbus_uniqueness))
       end
     end
 
@@ -90,11 +100,12 @@ module Pgbus
 
         args = active_job.arguments
         guard_class_name_default!(active_job, config, args)
-        last = args.last
-        key = if last.is_a?(Hash) && last.each_key.all?(Symbol)
-                config[:key].call(*args[...-1], **last)
+        key = if config[:explicit_key]
+                Support.call_key_proc(config[:key], args)
               else
-                config[:key].call(*args)
+                # Class-name default, resolved from the ENQUEUED job's class so
+                # an inherited declaration keys each subclass separately (#357).
+                active_job.class.name
               end
 
         # Automatically serialize GlobalID-compatible objects (e.g. ActiveRecord models)

data/lib/pgbus/version.rb

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

data/lib/pgbus/web/data_source.rb

@@ -65,6 +65,19 @@ module Pgbus
       end
       private :fetch_queues_with_metrics
 
+      # Physical queue names registered as stream queues (the
+      # pgbus_stream_queues registry). Stream delivery is a non-consuming
+      # peek, so stream messages sit visible with read_ct=0 forever — health
+      # verdicts must not read that as a wedge (issue #359). Loaded fresh per
+      # call (reset + one query): verdicts run on coarse intervals and a
+      # long-lived process must see streams registered since the last check.
+      # Degrades to an empty Set when the registry table is absent
+      # (pre-migration installs) or unreadable — StreamQueue swallows both.
+      def stream_queue_names
+        StreamQueue.reset_cache!
+        StreamQueue.all_names
+      end
+
       # name is the full PGMQ queue name (e.g. "pgbus_default") as returned
       # by queues_with_metrics. No prefix is added.
       def queue_detail(name)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.12.1
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -365,6 +365,7 @@ files:
 - lib/pgbus/streams/turbo_broadcastable.rb
 - lib/pgbus/streams/turbo_stream_override.rb
 - lib/pgbus/streams/watermark_cache_middleware.rb
+- lib/pgbus/support.rb
 - lib/pgbus/table_maintenance.rb
 - lib/pgbus/testing.rb
 - lib/pgbus/testing/assertions.rb