pgbus 0.9.8 → 0.9.9

data/lib/pgbus/pgmq_schema.rb

@@ -11,7 +11,7 @@ module Pgbus
   # Vendored SQL files live in lib/pgbus/pgmq_schema/pgmq_v{VERSION}.sql
   # and are exact copies of the upstream pgmq-extension/sql/pgmq.sql at each release.
   module PgmqSchema
-    class VersionNotFoundError < StandardError; end
+    class VersionNotFoundError < Pgbus::Error; end
 
     SCHEMA_DIR = File.expand_path("pgmq_schema", __dir__).freeze
 
@@ -112,7 +112,11 @@ module Pgbus
               EXECUTE 'DROP FUNCTION IF EXISTS ' || r.func_sig || ' CASCADE';
             END LOOP;
 
-            -- Drop custom types in pgmq schema
+            -- Drop custom composite types in pgmq schema (e.g. message_record,
+            -- queue_record, metrics_result). Standalone `CREATE TYPE ... AS (...)`
+            -- types get a pg_class shell with relkind = 'c'; only skip row-types
+            -- backed by an actual relation (table/view/etc.), which must be
+            -- dropped via DROP TABLE rather than DROP TYPE.
             FOR r IN
               SELECT n.nspname || '.' || t.typname AS type_name
               FROM pg_catalog.pg_type t
@@ -122,6 +126,7 @@ module Pgbus
                 AND NOT EXISTS (
                   SELECT 1 FROM pg_catalog.pg_class c
                   WHERE c.reltype = t.oid
+                    AND c.relkind <> 'c'
                 )
             LOOP
               EXECUTE 'DROP TYPE IF EXISTS ' || r.type_name || ' CASCADE';

data/lib/pgbus/process/consumer.rb

@@ -8,12 +8,16 @@ module Pgbus
       include SignalHandler
 
       attr_reader :topics, :threads, :config, :execution_mode,
-                  :queue_names, :wake_signal, :notify_retry_backoff
+                  :queue_names, :wake_signal, :notify_retry_backoff, :circuit_breaker
       # notify_listener is writable so tests can simulate a start_notify_listener
       # success from inside a stub (production sets it in start_notify_listener).
       # notify_retry_at is writable so a test can re-arm the backoff window
       # between successive ensure_notify_listener calls.
       attr_accessor :notify_listener, :notify_retry_at
+      # stat_buffer is writable so a test can swap in a buffer double after
+      # construction and assert graceful_shutdown / check_recycle / shutdown flush
+      # it (mirrors Worker#stat_buffer).
+      attr_accessor :stat_buffer
 
       def shutting_down?
         @shutting_down
@@ -50,7 +54,8 @@ module Pgbus
       # ivars. All default to the values production initializes to; `queue_names`
       # defaults to nil, meaning "derive from the registry in setup_subscriptions".
       def initialize(topics:, threads: 3, config: Pgbus.configuration, execution_mode: :threads,
-                     queue_names: nil, notify_listener: nil, notify_retry_at: 0.0,
+                     queue_names: nil, liveness_pipe: nil, stat_buffer: :default,
+                     notify_listener: nil, notify_retry_at: 0.0,
                      notify_retry_backoff: NOTIFY_RETRY_BASE_SECONDS,
                      started_at_monotonic: nil)
         @topics = Array(topics)
@@ -60,6 +65,7 @@ module Pgbus
         @shutting_down = false
         @recycling = false
         @jobs_processed = Concurrent::AtomicFixnum.new(0)
+        @loop_tick_at = Concurrent::AtomicReference.new(nil)
         @started_at_monotonic = started_at_monotonic || monotonic_now
         @wake_signal = WakeSignal.new
         @pool = ExecutionPools.build(
@@ -68,10 +74,36 @@ module Pgbus
           on_state_change: -> { @wake_signal.notify! }
         )
         @registry = EventBus::Registry.instance
+        @circuit_breaker = Pgbus::CircuitBreaker.new(config: config)
+        # stat_buffer: :default means "build one iff config.stats_enabled";
+        # passing an explicit value (including nil) overrides that for tests.
+        @stat_buffer =
+          if stat_buffer == :default
+            if config.stats_enabled
+              Pgbus::StatBuffer.new(
+                flush_size: config.stats_flush_size,
+                flush_interval: config.stats_flush_interval
+              )
+            end
+          else
+            stat_buffer
+          end
         @queue_names = queue_names
         @notify_listener = notify_listener
         @notify_retry_at = notify_retry_at
         @notify_retry_backoff = notify_retry_backoff
+        # OS-level liveness channel to the supervisor watchdog. nil unless the
+        # supervisor forked us with one. Written from stamp_loop_tick so the
+        # watchdog can detect a wedged consumer even when the database is down.
+        @liveness_pipe = liveness_pipe
+      end
+
+      # The last wall-clock loop-tick stamp (Time.now.to_f) fed to the
+      # heartbeat's loop_tick_supplier. Wall-clock so it stays comparable across
+      # the process boundary the supervisor watchdog reads it over. nil until the
+      # first stamp_loop_tick.
+      def last_loop_tick
+        @loop_tick_at.get
       end
 
       def run
@@ -85,6 +117,7 @@ module Pgbus
         end
 
         loop do
+          stamp_loop_tick
           process_signals
           check_recycle
           ensure_notify_listener
@@ -92,6 +125,7 @@ module Pgbus
           break if @shutting_down
 
           consume
+          @stat_buffer&.flush_if_due
         end
 
         shutdown
@@ -99,6 +133,11 @@ module Pgbus
 
       def graceful_shutdown
         @shutting_down = true
+        # Flush buffered stats at drain entry so the window since the last flush
+        # isn't lost if the supervisor watchdog SIGKILLs a stalled consumer
+        # before shutdown runs. Same-thread (signals dispatched via
+        # process_signals, not trap context), so the DB write is safe.
+        @stat_buffer&.flush
         @wake_signal.notify!
       end
 
@@ -121,12 +160,7 @@ module Pgbus
         idle = @pool.available_capacity
         return @wake_signal.wait(timeout: wake_timeout) if idle <= 0
 
-        tagged_messages = if @queue_names.size == 1
-                            queue = @queue_names.first
-                            (Pgbus.client.read_batch(queue, qty: idle) || []).map { |m| [queue, m] }
-                          else
-                            fetch_multi_consumer(idle)
-                          end
+        tagged_messages = fetch_messages(idle)
 
         if tagged_messages.empty?
           @wake_signal.wait(timeout: wake_timeout)
@@ -138,10 +172,38 @@ module Pgbus
         end
       end
 
+      # Returns an array of [queue_name, message] pairs. Queues whose circuit
+      # breaker has tripped are skipped so a poison queue is left to cool down
+      # instead of being hammered every tick (mirrors Worker#fetch_messages).
+      def fetch_messages(qty)
+        active_queues = @queue_names.reject { |q| @circuit_breaker.paused?(q) }
+        return [] if active_queues.empty?
+
+        if active_queues.size == 1
+          queue = active_queues.first
+          (Pgbus.client.read_batch(queue, qty: qty) || []).map { |m| [queue, m] }
+        else
+          fetch_multi_consumer(active_queues, qty)
+        end
+      rescue Pgbus::ConnectionCircuitOpenError
+        # The client-level connection breaker is open: the database has failed
+        # enough consecutive connection attempts that reads fail fast. Idle this
+        # poll without an ErrorReporter call so the whole consumer pool doesn't
+        # flood the error tracker for the duration of a database outage. The
+        # open/close transitions are logged once by the client, not per poll.
+        []
+      rescue StandardError => e
+        ErrorReporter.report(e, { action: "fetch_messages", queues: active_queues })
+        []
+      end
+
       def handle_message(message, queue_name)
+        execution_start = monotonic_now
+
         if message.read_ct.to_i > config.max_retries
           Pgbus.logger.warn { "[Pgbus] Consumer moving message #{message.msg_id} to DLQ after #{message.read_ct} reads" }
           Pgbus.client.move_to_dead_letter(queue_name, message)
+          record_stat(message, queue_name, "dead_lettered", execution_start)
           return
         end
 
@@ -155,11 +217,15 @@ module Pgbus
         end
 
         Pgbus.client.archive_message(queue_name, message.msg_id.to_i)
+        @circuit_breaker.record_success(queue_name)
+        record_stat(message, queue_name, "success", execution_start)
       rescue StandardError => e
         Pgbus.logger.error { "[Pgbus] Consumer error: #{e.class}: #{e.message}" }
         # Message stays in queue; VT will expire and it becomes available again.
         # read_ct tracks delivery attempts — when it exceeds max_retries,
         # the next read will route to DLQ above.
+        @circuit_breaker.record_failure(queue_name)
+        record_stat(message, queue_name, "failed", execution_start)
       ensure
         # Count every message the consumer handles — success, DLQ-routed, AND
         # rescued failure — mirroring Worker#process_message, which increments
@@ -169,16 +235,40 @@ module Pgbus
         @jobs_processed.increment
       end
 
+      # Record a job stat for the handled message, mirroring the shape the
+      # executor pushes (Executor#record_stat) so consumer and worker throughput
+      # land in the same pgbus_job_stats table. No-op unless stats are enabled.
+      def record_stat(message, queue_name, status, start_time)
+        return unless config.stats_enabled
+
+        attrs = {
+          job_class: "EventConsumer",
+          queue_name: queue_name,
+          status: status,
+          duration_ms: ((monotonic_now - start_time) * 1000).round,
+          enqueue_latency_ms: nil,
+          retry_count: [message.read_ct.to_i - 1, 0].max
+        }
+
+        if @stat_buffer
+          @stat_buffer.push(attrs)
+        else
+          JobStat.record!(**attrs)
+        end
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus] Consumer stat recording failed: #{e.message}" }
+      end
+
       # `qty` is the total pool capacity. pgmq-ruby treats `qty:` as per-queue,
       # so we also pass `limit: qty` to cap the total across all queues —
       # otherwise we get `queue_count * qty` messages and overflow the
       # execution pool, crashing the consumer fork (issue #123).
-      def fetch_multi_consumer(qty)
-        messages = Pgbus.client.read_multi(@queue_names, qty: qty, limit: qty) || []
+      def fetch_multi_consumer(active_queues, qty)
+        messages = Pgbus.client.read_multi(active_queues, qty: qty, limit: qty) || []
         prefix = "#{config.queue_prefix}_"
 
         messages.map do |m|
-          logical = m.queue_name&.delete_prefix(prefix) || @queue_names.first
+          logical = m.queue_name&.delete_prefix(prefix) || active_queues.first
           [logical, m]
         end
       end
@@ -203,6 +293,9 @@ module Pgbus
 
         @recycling = true
         @shutting_down = true
+        # Flush buffered stats on recycle-triggered drain for the same reason as
+        # graceful_shutdown: shrink the SIGKILL loss window. Same-thread, safe.
+        @stat_buffer&.flush
         Pgbus::Instrumentation.instrument(
           "pgbus.consumer.recycle",
           reason: reason,
@@ -324,15 +417,36 @@ module Pgbus
       def start_heartbeat
         @heartbeat = Heartbeat.new(
           kind: "consumer",
-          metadata: { topics: topics, threads: threads, pid: ::Process.pid }
+          metadata: { topics: topics, threads: threads, pid: ::Process.pid },
+          on_beat: -> { on_heartbeat },
+          loop_tick_supplier: -> { @loop_tick_at.get }
         )
         @heartbeat.start
       end
 
+      # Runs once per heartbeat interval (not per message), so it's the right
+      # place to emit connection-pool observability without touching any per-job
+      # hot path. Reading the pool must never crash the beat — pool_stats already
+      # rescues to {}, and this whole method is guarded so an unexpected error
+      # can't take down the heartbeat thread (mirrors Worker#on_heartbeat).
+      def on_heartbeat
+        emit_pool_stats
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus] Consumer heartbeat hook error: #{e.class}: #{e.message}" }
+      end
+
+      def emit_pool_stats
+        stats = Pgbus.client.pool_stats
+        return if stats.empty?
+
+        Pgbus::Instrumentation.instrument("pgbus.client.pool", stats)
+      end
+
       def shutdown
         @notify_listener&.stop
         @pool.shutdown
         @pool.wait_for_termination(30)
+        @stat_buffer&.stop
         @heartbeat&.stop
         restore_signals
         Pgbus.logger.info { "[Pgbus] Consumer stopped. Processed: #{@jobs_processed.value}" }
@@ -341,6 +455,21 @@ module Pgbus
       def monotonic_now
         ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
       end
+
+      # Stamp the loop-progress beacon with a wall-clock timestamp (required
+      # because the supervisor watchdog reads it cross-fork and the dashboard
+      # reads it cross-host). Also pokes the OS-level liveness pipe when the
+      # supervisor forked us with one, giving the watchdog a database-independent
+      # signal. The write is non-blocking and never raises in the hot path
+      # (mirrors Worker#stamp_loop_tick).
+      def stamp_loop_tick
+        @loop_tick_at.set(Time.now.to_f)
+        return unless @liveness_pipe
+
+        @liveness_pipe.write_nonblock("\0", exception: false)
+      rescue Errno::EPIPE, IOError, Errno::EBADF
+        nil
+      end
     end
   end
 end

data/lib/pgbus/process/supervisor.rb

@@ -308,7 +308,7 @@ module Pgbus
       end
 
       def boot_scheduler
-        return if config.skip_recurring
+        return unless config.recurring_enabled
         return unless recurring_tasks_configured?
 
         fork_scheduler
@@ -381,22 +381,43 @@ module Pgbus
         topics = consumer_config[:topics]
         threads = consumer_config[:threads] || 3
 
+        # OS-level liveness channel: the consumer writes a byte each loop
+        # iteration, the parent drains the reader in monitor_loop. This lets the
+        # watchdog detect a wedged consumer without the database (issue #274),
+        # exactly as fork_worker does for workers.
+        liveness_reader, liveness_writer = IO.pipe
+
         pid = fork do
+          # Child owns the writer end. Close every earlier sibling's inherited
+          # liveness reader and this fork's own reader copy before becoming a
+          # Consumer (see fork_worker for the full rationale).
+          close_inherited_liveness_readers
+          liveness_reader.close
           restore_signals
           setup_child_process
           load_rails_app
-          consumer = Consumer.new(topics: topics, threads: threads, config: config)
+          consumer = Consumer.new(topics: topics, threads: threads, config: config, liveness_pipe: liveness_writer)
           consumer.run
         end
 
         unless pid
+          close_pipe(liveness_reader)
+          close_pipe(liveness_writer)
           Pgbus.logger.error { "[Pgbus] Failed to fork consumer for topics=#{topics.join(",")}" }
           return
         end
 
-        @forks[pid] = { type: :consumer, config: consumer_config, slot: slot, spawned_at: monotonic_now }
+        # Parent keeps the reader, discards its writer copy so the pipe reaches
+        # EOF once the (sole remaining) child writer closes.
+        close_pipe(liveness_writer)
+        @forks[pid] = {
+          type: :consumer, config: consumer_config, slot: slot, spawned_at: monotonic_now,
+          liveness_reader: liveness_reader, last_pipe_tick_at: monotonic_now, pipe_seen: false
+        }
         Pgbus.logger.info { "[Pgbus] Forked consumer pid=#{pid} topics=#{topics.join(",")}" }
       rescue Errno::EAGAIN, Errno::ENOMEM => e
+        close_pipe(liveness_reader)
+        close_pipe(liveness_writer)
         ErrorReporter.report(e, { action: "fork_consumer", topics: topics })
       end
 
@@ -525,12 +546,14 @@ module Pgbus
         threshold = config.stall_threshold
         return unless threshold&.positive?
 
-        worker_pids = @forks.select { |_, info| info[:type] == :worker }.keys
-        return if worker_pids.empty?
+        # Workers AND consumers both stamp a loop beacon and carry a liveness
+        # pipe (issue #274), so both are watched for a wedged claim/consume loop.
+        watched_pids = @forks.select { |_, info| %i[worker consumer].include?(info[:type]) }.keys
+        return if watched_pids.empty?
 
-        db_ages = db_loop_tick_ages(worker_pids)
+        db_ages = db_loop_tick_ages(watched_pids)
 
-        worker_pids.each do |pid|
+        watched_pids.each do |pid|
           info = @forks[pid]
           next unless info
 
@@ -540,13 +563,13 @@ module Pgbus
         Pgbus.logger.warn { "[Pgbus] Supervisor watchdog check failed: #{e.message}" }
       end
 
-      # Read each worker's loop_tick_at from the process table and return a
-      # {pid => wall-clock age in seconds} map. Isolated in its own rescue so a
+      # Read each watched fork's loop_tick_at from the process table and return
+      # a {pid => wall-clock age in seconds} map. Isolated in its own rescue so a
       # database outage degrades to the OS-pipe fallback instead of skipping
       # the whole watchdog — the exact failure this pipe channel exists to fix.
       def db_loop_tick_ages(worker_pids)
         ages = {}
-        ProcessEntry.where(kind: "worker", pid: worker_pids).to_a.each do |entry|
+        ProcessEntry.where(kind: %w[worker consumer], pid: worker_pids).to_a.each do |entry|
           meta = entry.metadata
           next unless meta.is_a?(Hash)
 

data/lib/pgbus/process/worker.rb

@@ -141,21 +141,11 @@ module Pgbus
       # restarting, failover, DNS blip) or its thread can die mid-run. Rather
       # than downgrade to blind polling until process restart, the loop retries
       # from ensure_notify_listener on an exponential backoff: NOTIFY_RETRY_BASE
-      # doubling up to NOTIFY_RETRY_MAX. Constant-tuned, matching DRAIN_TIMEOUT
-      # and CircuitBreaker/Dispatcher precedent.
+      # doubling up to NOTIFY_RETRY_MAX. Constant-tuned, matching the
+      # CircuitBreaker/Dispatcher precedent.
       NOTIFY_RETRY_BASE_SECONDS = 5
       NOTIFY_RETRY_MAX_SECONDS = 300
 
-      # Upper bound on the drain phase. Waiting for quiesced? must be
-      # bounded: a permanently-stuck job would otherwise hold the loop open
-      # forever — recycling never completes, TERM shutdown hangs the whole
-      # process tree, and the loop keeps stamping loop_tick so the
-      # supervisor watchdog never intervenes. After this many seconds the
-      # loop falls through to shutdown, whose wait_for_termination(30)
-      # bounds the remaining in-flight work. Tuned via constant rather than
-      # configuration, matching CircuitBreaker/Dispatcher precedent.
-      DRAIN_TIMEOUT = 30
-
       def run
         setup_signals
         start_heartbeat
@@ -178,7 +168,7 @@ module Pgbus
           # quiesced? (all slots free), not idle? (any slot free) — exiting
           # with work still in flight abandons those jobs to the 30s
           # wait_for_termination timeout in shutdown. Bounded by
-          # DRAIN_TIMEOUT so a stuck job can't wedge the loop forever.
+          # config.drain_timeout so a stuck job can't wedge the loop forever.
           break if @lifecycle.draining? && (@pool.quiesced? || drain_deadline_exceeded?)
 
           claim_and_execute if @lifecycle.can_process?
@@ -223,7 +213,7 @@ module Pgbus
       # deleted), the first restore waits RESTORE_COOLDOWN_BASE seconds; each
       # consecutive failed restore doubles the wait up to RESTORE_COOLDOWN_MAX.
       # A successful fetch resets the streak so a recreated queue restores
-      # promptly. Constant-tuned, matching NOTIFY_RETRY/DRAIN_TIMEOUT precedent.
+      # promptly. Constant-tuned, matching the NOTIFY_RETRY precedent.
       RESTORE_COOLDOWN_BASE = 30
       RESTORE_COOLDOWN_MAX = 300
 
@@ -531,10 +521,10 @@ module Pgbus
       # state (graceful_shutdown, recycling) without hooking each one.
       def drain_deadline_exceeded?
         @drain_started_at ||= monotonic_now
-        return false unless monotonic_now - @drain_started_at > DRAIN_TIMEOUT
+        return false unless monotonic_now - @drain_started_at > config.drain_timeout
 
         Pgbus.logger.warn do
-          "[Pgbus] Worker drain deadline (#{DRAIN_TIMEOUT}s) reached with #{@in_flight.value} job(s) " \
+          "[Pgbus] Worker drain deadline (#{config.drain_timeout}s) reached with #{@in_flight.value} job(s) " \
             "still in flight — proceeding to shutdown"
         end
         true

data/lib/pgbus/recurring/schedule.rb

@@ -202,8 +202,7 @@ module Pgbus
 
         payload.merge(
           Pgbus::Uniqueness::METADATA_KEY => key,
-          Pgbus::Uniqueness::STRATEGY_KEY => config[:strategy].to_s,
-          Pgbus::Uniqueness::TTL_KEY => config[:lock_ttl]
+          Pgbus::Uniqueness::STRATEGY_KEY => config[:strategy].to_s
         )
       end
     end

data/lib/pgbus/serializer.rb

@@ -55,21 +55,21 @@ module Pgbus
     # can be resolved — prevents loading arbitrary objects from crafted payloads.
     def locate_global_id(gid_string)
       gid = GlobalID.parse(gid_string)
-      raise ArgumentError, "Invalid GlobalID: #{gid_string.inspect}" unless gid
+      raise Pgbus::SerializationError, "Invalid GlobalID: #{gid_string.inspect}" unless gid
 
       allowed = Pgbus.configuration.allowed_global_id_models
       if allowed && allowed.empty?
-        raise ArgumentError,
+        raise Pgbus::SerializationError,
               "GlobalID deserialization is disabled (allowed_global_id_models is empty). " \
               "Set to nil to allow all models, or add permitted classes."
       end
       if allowed&.any? { |entry| !entry.is_a?(Class) && !entry.is_a?(Module) }
-        raise ArgumentError,
+        raise Pgbus::SerializationError,
               "allowed_global_id_models must contain Class/Module objects, " \
               "got: #{allowed.map(&:class).uniq.join(", ")}"
       end
       if allowed&.none? { |klass| gid.model_class <= klass }
-        raise ArgumentError,
+        raise Pgbus::SerializationError,
               "GlobalID model #{gid.model_class} is not in allowed_global_id_models. " \
               "Add it to Pgbus.configuration.allowed_global_id_models to permit deserialization."
       end

data/lib/pgbus/streams/broadcastable_override.rb

@@ -155,14 +155,6 @@ module Pgbus
       ensure
         previous.each { |tl_key, value| Thread.current[tl_key] = value }
       end
-
-      # Kept for backward compatibility — the class-level durable callbacks
-      # (broadcasts_to with durable:) and any external callers may still use it.
-      def with_pgbus_durable(value, &)
-        return yield if value.nil?
-
-        with_pgbus_broadcast_opts(durable: value, &)
-      end
     end
   end
 end

data/lib/pgbus/streams/signed_name.rb

@@ -14,10 +14,10 @@ module Pgbus
     # `"gid://app/Order/42:messages"`). Verification returns that string;
     # tampered or unsigned input raises `InvalidSignedName`.
     module SignedName
-      class InvalidSignedName < StandardError
+      class InvalidSignedName < Pgbus::Error
       end
 
-      class MissingSecret < StandardError
+      class MissingSecret < Pgbus::Error
       end
 
       def self.verify!(token)

data/lib/pgbus/uniqueness.rb

@@ -43,28 +43,28 @@ module Pgbus
 
     METADATA_KEY = "pgbus_uniqueness_key"
     STRATEGY_KEY = "pgbus_uniqueness_strategy"
-    TTL_KEY = "pgbus_uniqueness_lock_ttl"
-
-    # TTL is kept for metadata compatibility but no longer drives lock expiry.
-    # The lock exists until the job completes or is dead-lettered.
-    DEFAULT_LOCK_TTL = 24 * 60 * 60
 
     VALID_STRATEGIES = %i[until_executed while_executing].freeze
     VALID_CONFLICTS = %i[reject discard log].freeze
 
     class_methods do
-      def ensures_uniqueness(strategy: :until_executed, key: nil, lock_ttl: DEFAULT_LOCK_TTL, on_conflict: :reject)
+      def ensures_uniqueness(strategy: :until_executed, key: nil, on_conflict: :reject, **opts)
+        # lock_ttl was validated and stored in message metadata but never read
+        # by the lock lifecycle (the lock lives until the job completes or is
+        # dead-lettered, not until a TTL expires). Removed in 1.0.0.
+        if opts.key?(:lock_ttl)
+          raise ArgumentError,
+                "lock_ttl: was removed in pgbus 1.0.0 — it was validated but never read by anything. " \
+                "Remove it from ensures_uniqueness. See https://pgbus.dev/docs/upgrading-pgbus"
+        end
+        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)
-
-        valid_ttl = lock_ttl.is_a?(Numeric) || (defined?(ActiveSupport::Duration) && lock_ttl.is_a?(ActiveSupport::Duration))
-        raise ArgumentError, "lock_ttl must be a positive number or Duration" unless valid_ttl && lock_ttl.positive?
         raise ArgumentError, "key must be callable (Proc or lambda)" if key && !key.respond_to?(:call)
 
         @pgbus_uniqueness = {
           strategy: strategy,
           key: key || ->(*) { name },
-          lock_ttl: lock_ttl,
           on_conflict: on_conflict
         }.freeze
       end
@@ -102,8 +102,7 @@ module Pgbus
 
         payload_hash.merge(
           METADATA_KEY => key,
-          STRATEGY_KEY => config[:strategy].to_s,
-          TTL_KEY => config[:lock_ttl]
+          STRATEGY_KEY => config[:strategy].to_s
         )
       end
 

data/lib/pgbus/version.rb

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

data/lib/pgbus/web/data_source.rb

@@ -1250,15 +1250,31 @@ module Pgbus
       # 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. Kinds with no loop beacon (nil) are never stalled.
+      # 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)
-        base = Pgbus.configuration.stall_threshold
+        config = Pgbus.configuration
+        base = config.stall_threshold
         return nil unless base&.positive?
 
         case kind
         when "worker" then base
-        when "dispatcher" then base + Pgbus.configuration.dispatch_interval
-        when "scheduler" then base + Pgbus.configuration.recurring_schedule_interval
+        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
 

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
@@ -46,9 +47,10 @@ module Pgbus
             # 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. Skipped for an injected pg_connection: (unit tests) — a
-            # nil factory falls back to conn.reset.
-            connection_factory: pg_connection ? nil : -> { build_raw_pg_connection }
+            # 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,