pgbus 0.16.5 → 0.16.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4382e9b750a7e3538c2ba640aa476bb914cd1c1deba00fda429510ea1dcdc851
-  data.tar.gz: bc8bff2b3b08ccc6de7d67c677a8797be4d0a1b9f65019a9728d0531ad5a830a
+  metadata.gz: 82a6db71dd099a9b4fa24cb0a278184a3aed8bbee7acfb3f3cc6ef6b55064038
+  data.tar.gz: ad7034ee934aee91afdb4a6278200f8178caf0da609d49e57bc6bbcf27d3b7b5
 SHA512:
-  metadata.gz: 9630731c5e8b4ef6bb9db80e1e950ad6abee7748e49868fb613645b0d16469f477a6b0fe819427135a6bdf85589fb518e6204f80a3a20810939ed1c2038238a7
-  data.tar.gz: b4c5b23b4e4513b5447985ab96b1578a3a1931fda6b3b4700338b71d7d822a989cda6498670a31e7ef30848f69f4075b23a2f018764072f51b6e91ae258d8445
+  metadata.gz: 86977d3f705b8e3732211956582334f6e49a60e426af1082fdf585a175c9a189c9dc9ec83d5ceeaac2f0be7dcee40c1414e55a99225fcc90ac955537d8b4f01c
+  data.tar.gz: 3af2ae55db88774c89f3082b70e5456201c9a85ffd994d43beb197fe0f52d282209fc5de57db66c44de10afe34b37d37fa5404522eabb97d4eb2e91cbfc80da7

data/CHANGELOG.md

@@ -2,12 +2,21 @@
 
 ### Added
 
+- **`coalesce:` now works on the `Turbo::StreamsChannel` broadcast path.** `Pgbus::Streams::Stream#broadcast` has accepted `coalesce:` since #171, but the Turbo patch forwarded only four options (`durable:`, `exclude:`, `visible_to:`, `event:`), so nothing that broadcasts through `Turbo::StreamsChannel.broadcast_*_to` — every `Turbo::Broadcastable` model, and phlex-reactive's `Streamable.broadcast_to` — could debounce. A background job settling a 177-row collection therefore pushed 177 idempotent replaces of the same count badge at every peer. Any targeted helper now takes `coalesce:` (`@order.broadcast_replace_to :account, coalesce: 100`), as does a direct channel call (`Turbo::StreamsChannel.broadcast_replace_to(@account, target: "order-count", coalesce: true)`), with the same semantics as the direct API: opt-in, per `(stream, target)`, last-write-wins, `true` = the 50ms default window, an integer = the window in ms. Two things the option's plumbing needed beyond a fifth thread-local: the coalescing key, which dedupes on `(stream, target)` while `broadcast_stream_to` only ever sees the rendered `content:` — it is now resolved from the frame's own `target:`/`targets:` through the same `ActionView::RecordIdentifier.dom_id` conversion Turbo applies, so a record target keys on `order_7` rather than on a per-instance `#to_s`; and extraction of the pgbus options at the channel itself, since a direct `Turbo::StreamsChannel` call never passes through `Turbo::Broadcastable` and so previously leaked `durable: true` (and now `coalesce:`) into Turbo's renderer. `broadcast_refresh_to` and `broadcast_render_to` carry no target and so cannot coalesce — they raise the existing actionable "requires target:" error rather than guessing a key — and the `_later_to` variants remain out of scope, as the thread-local cannot follow into a job. The wire is byte-identical when `coalesce:` is absent. Closes #465.
+
 - **Concurrency is now visible: a section on the Locks page, three gauges, a home stat card and an MCP tool.** `limits_concurrency … on_conflict: :block` became durable in #460 — a parked job is never dropped and a key never runs past `to:` — but nothing showed it, so an operator whose per-record pipeline looked "stuck" had no way to see that the key's slot was held, how many jobs were parked behind it, or how long the oldest had waited, short of SQL. `pgbus_semaphores` and `pgbus_blocked_executions` appeared on no page, in no gauge, in no tool. One new read, `Web::DataSource#concurrency_stats`, now feeds four surfaces: the Locks page's **Concurrency** section (parked jobs, oldest wait, slots held, keys at limit, then a row per key with value / limit, lease state, parked count and oldest wait, auto-refreshing like the other dashboard panels); a **Parked jobs** card on the dashboard home; three unlabelled gauges on both `/pgbus/api/metrics` and the AppSignal probe (`pgbus_concurrency_blocked_executions`, `pgbus_concurrency_blocked_oldest_age_seconds`, `pgbus_concurrency_slots_held` — keys are per-record, so a per-key label would be an unbounded series); and a read-only `pgbus_concurrency` MCP tool returning the same data. The key rows come from a FULL OUTER JOIN, not a LEFT one: a key can have parked jobs and no semaphore (its holder died and the sweep removed the row) or a semaphore and nothing parked, and both shapes matter to an operator. Each row carries two guarded escape hatches. **Release** drops the semaphore and promotes through `Concurrency::BlockedExecution.promote_next`, so it takes each slot through the same guarded upsert an enqueue uses and can never reintroduce the over-admission #460 closed; when the lease is still fresh the confirm says so, because a job is then probably still running and releasing lets another start beside it. **Discard parked** drops a single key's parked jobs, naming the exact count in the confirm, and resolves the bookkeeping those jobs will never resolve themselves — a parked batch child is marked failed so its batch stops waiting and `on_failure` fires (#413), and an `:until_executed` uniqueness lock is released rather than orphaned (#423); each discard logs a warning naming the job and emits `pgbus.blocked_execution_discarded`. There is deliberately no cross-key "discard all parked": not losing work is the whole point of `:block`. Nothing is added to the enqueue or execute path. Refs #461.
 
 - **The batches list and a batch's progress panel now refresh themselves.** Batches was the only dashboard list whose `turbo-frame` was missing `data-auto-refresh`, and the batch detail page had no frame at all, so watching a batch drain meant reloading by hand. Both now poll on the existing `web_refresh_interval` (5s, pauses while you interact) like every other list — the batch progress panel is served by `GET /batches/:id?frame=progress`. This reuses the dashboard's turbo-frame polling rather than the SSE stack in `lib/pgbus/web/stream_app.rb`: that is the host-app-facing stream feature, and pointing it at the dashboard would open a PG `LISTEN` connection per viewer to move four integers.
 
 ### Fixed
 
+- **A still-running event handler is no longer re-run as if it had crashed, and a slow one is no longer redelivered mid-run.** Two halves of one hole, follow-up to #469. First: `Process::Consumer` had no equivalent of `ActiveJob::Executor#with_visibility_heartbeat`, so an event message's visibility timeout was never re-armed — a handler slower than `visibility_timeout` (30s by default) was redelivered *while it was still running*, `read_ct` climbed on every redelivery, and after `max_retries` the event was dead-lettered without the handler ever raising. Workers have been protected from this since the heartbeat landed; event consumers never were. The consumer now tracks each message through `VisibilityHeartbeat` for exactly as long as its handlers run, releasing the entry before the archive so a beat can never re-arm a message that is already gone. Second: `Handler#claim_idempotency?` read a `pgbus_processed_events` row with `completed_at IS NULL` as proof that the previous holder had been killed mid-handler, and re-ran. That state equally describes a handler that is simply still running — on another thread, another fork or another host — so a second delivery (a genuine redelivery, or a duplicate envelope, whose independent visibility timeouts no heartbeat can serialize) executed the handler *concurrently with* the live one, which is precisely the double-execution `idempotent!` exists to prevent. The claim now carries liveness rather than only a claim instant: `EventBus::ClaimBeat` refreshes every in-flight claim's `processed_at` from the same beat that re-arms the message's visibility timeout, so message visibility and claim liveness go quiet together when a process dies. A pending claim silent for longer than twice the heartbeat interval is abandoned and re-runs, exactly as before; a fresher one is owned and the delivery skips, deferring to the holder — which either completes (nothing is lost) or fails, leaving its own message for visibility-timeout redelivery to recover. A skip is also no longer silent: `pgbus.event_skipped` carries the reason (`:completed`, `:cached` or `:owned`), the claim's age in seconds and the delivery's `read_ct`, and the metrics subscriber counts it as `pgbus_event_count` with `status: "skipped"` and the reason as a tag. No migration, no new column, and no change on a table that has not run `pgbus:add_processed_event_completion` — a single-phase claim has no pending state and therefore no ownership question. Closes #470.
+
+- **An event is no longer handed to every handler whose pattern matches it, so a wildcard handler ran once per subscriber on the topic.** Each subscriber gets its own queue (`Subscriber#setup!` creates and binds one), so a topic with N matching subscribers puts N copies of every event on the bus — but `Consumer#handle_message` resolved handlers with `Registry#handlers_for(routing_key)`, a pattern match that ignored which queue the message had just been read from, and ran every match. Each of the N copies therefore fanned out to all N handlers: **every handler ran N times per event**, with four `"#"` subscribers meaning four invocations of each handler for every event on the bus. `idempotent!` was the only thing hiding it, and it hides it imperfectly by design: the two-phase claim (#385) deliberately *re-runs* when the existing claim is still pending, on the theory that the prior holder crashed — but a pending claim is also exactly what a handler still running on another host looks like. So one event could have host A win the claim and start a 700ms handler while host B, reading a different subscriber's copy of the same event a few hundred milliseconds later, dispatched to that same handler, lost the claim insert, read `completed_at IS NULL` as "crashed, re-run", and executed it concurrently. In one host app that meant a "task completed" record written twice and the user emailed twice, with a single row in `pgbus_processed_events`, `read_ct = 1` on every archived copy, and the second execution's side effects timestamped inside the first's window — dispatch, not redelivery. A non-idempotent handler simply ran N times with no guard at all. `handlers_for` now takes a required `queue_name:` and selects on ownership *and* pattern, so a message read from queue Q goes to Q's owner(s) alone and each handler runs exactly once per event; duplicate execution again requires a real redelivery, which is the at-least-once contract the docs describe. The keyword is required rather than defaulted precisely so a keyword-less call cannot silently restore the fan-out — the two callers that genuinely want the pattern view (the `Testing.inline!` publish path and `Testing::EventStore#drain!`, neither of which has a queue, since the event never reaches PGMQ) moved to an explicitly named `Registry#subscribers_matching`, where per-subscriber delivery counts already match what owner-only dispatch now produces in production. Two handlers registered against the same explicit `queue_name:` still both run on that queue's delivery. The pattern check is kept alongside the ownership check because a routing key the owner's pattern does not match means a stale `pgmq.topic_bindings` row, and a stale binding must not run the handler. A message on a queue no subscriber in this process owns is still archived rather than looped through visibility-timeout redelivery into the DLQ — that was already the behavior when `handlers_for` returned `[]` — but it is no longer silent: it logs a warning naming the queue and routing key, rate-limited to once per queue per process so a permanently stale binding cannot flood the log, and emits `pgbus.event_unrouted` on every occurrence so the real rate stays visible in metrics. The pending-claim re-run in `Handler#claim_idempotency?` is deliberately untouched here; it is a separate question now that dispatch no longer manufactures the concurrency it was misreading. Closes #469.
+
+- **A dropped ActiveRecord socket no longer pages the host app for an event that was handled successfully.** EventBus consumers are long-lived threads holding a leased AR connection, and a pooler restart, an admin disconnect or a brief failover can kill that socket at any point. Rails reconnects most statements transparently, but `Relation#update_all` is marked `allow_retry: false` — and that is exactly the phase-2 claim stamp in `Handler#complete_claim!`, the one AR write that happens *after* `handle` has already returned. A drop there surfaced as `ActiveRecord::ConnectionFailed` ("PQconsumeInput() SSL error: unexpected eof while reading") on a message whose work was done, so the host app's exception tracker paged for a false failure and PGMQ redelivered the event for a re-run. `EventBus::StaleConnectionRetry` now reconnects this thread's lease (via `ConnectionPool#active_connection?`, the accessor that exists across the supported Rails range) and repeats the stamp once; a second drop still raises, leaving the message to VT redelivery. Only the leased connections are reconnected — `clear_all_connections!` would yank sockets out from under sibling consumers in the same process, turning one recoverable drop into many. The retryable patterns are deliberately *broader* than `Client::STALE_CONNECTION_PATTERNS` and for the opposite reason: that list excludes mid-flight drops because a half-committed enqueue would duplicate a message, whereas this only ever repeats an idempotent `SET completed_at = <now>`. Phase 1 (`claim_idempotency?`) is deliberately not wrapped — its INSERT may have committed before the socket died, and on a legacy schema the retry's empty `result.rows` would read as "another consumer owns this claim", turning a recoverable drop into a silently skipped event.
+
+
 - **The AppSignal probe's gauges and every MCP tool response were frozen at their first read.** `Web::DataSource` memoizes `queues_with_metrics` for the life of the instance — correct for the dashboard, which builds one instance per request, but the AppSignal `Probe::Runner` holds a single DataSource for the life of the process and `MCP::Server.build` injects one into the server context, so both replayed the first read forever: queue depth in AppSignal never moved after the first minute, and `pgbus_queues` returned the same snapshot for every call in a session. `DataSource#reset_cache!` drops the memos, and both long-lived consumers call it — the probe once per iteration, `MCP::BaseTool.data_source_from` once per tool call. Found while reviewing the concurrency aggregates added in the same release, which memoize the same way.
 
 - **`limits_concurrency … on_conflict: :block` now constrains a job without ever losing it, and never runs more than `to:` at once.** The same bug class solid_queue closed in rails/solid_queue#712 and #761, checked against pgbus's implementation. Four defects, each with a regression spec:

data/README.md

@@ -221,6 +221,14 @@ Pgbus::EventBus::Registry.instance.subscribe(
 )
 ```
 
+Each subscriber gets its own queue, and a queue is consumed only by the
+handler(s) registered against it: one published event matching N subscribers
+becomes N deliveries, one per handler, so every handler runs exactly once per
+event. (Two handlers sharing an explicit `queue_name:` both run on that queue's
+delivery.) A message on a queue no subscriber in this process owns — a stale
+topic binding left by a renamed or removed handler — is archived, logged once
+per queue, and reported as `pgbus.event_unrouted`.
+
 `idempotent!` uses a **two-phase claim**: a *pending* row in
 `pgbus_processed_events` is inserted before `handle` runs, and only stamped
 `completed_at` after `handle` returns. Deduplication applies to **completed**

data/lib/pgbus/event_bus/claim_beat.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module EventBus
+    # Liveness for the idempotency claims in flight for one PGMQ message.
+    #
+    # A two-phase claim (issue #385) is a `pgbus_processed_events` row with
+    # `completed_at IS NULL`. That state says "claimed, not finished" — it does
+    # NOT say whether the claimer is dead or simply still running (issue #470).
+    # Handler resolves the ambiguity by age: a claim whose `processed_at` has
+    # gone quiet for longer than the ownership window is abandoned, anything
+    # fresher is owned. For that age to mean "silence" rather than
+    # "time since the claim was taken", something has to keep stamping it while
+    # the handler runs. This is that something.
+    #
+    # One beat per message, created by Process::Consumer and handed to every
+    # handler dispatched for it. A handler registers its claim for exactly the
+    # duration of `handle` and the consumer's VisibilityHeartbeat `on_beat` hook
+    # drives #touch! on the same cadence that re-arms the message's visibility
+    # timeout — so the claim and the message go quiet together when the process
+    # dies, and both stay fresh while it lives.
+    #
+    # #touch! runs on the heartbeat ticker thread while #register / #release run
+    # on a pool thread, hence the mutex.
+    class ClaimBeat
+      def initialize
+        @mutex = Mutex.new
+        @claims = []
+      end
+
+      def register(event_id, handler_class)
+        claim = [event_id, handler_class]
+        @mutex.synchronize { @claims << claim unless @claims.include?(claim) }
+        self
+      end
+
+      def release(event_id, handler_class)
+        @mutex.synchronize { @claims.delete([event_id, handler_class]) }
+        self
+      end
+
+      def size
+        @mutex.synchronize { @claims.size }
+      end
+
+      def empty?
+        size.zero?
+      end
+
+      # Refresh every registered claim's liveness stamp. Returns the number of
+      # claims touched. No-op on a legacy schema: without `completed_at` there
+      # are no pending claims to keep alive, and Handler's single-phase
+      # fallback never consults the age.
+      #
+      # A claim that fails to update is logged and skipped rather than raised:
+      # this runs inside the visibility heartbeat's beat, and one unwritable
+      # row must not cost every other in-flight message its VT extension.
+      def touch!
+        return 0 unless ProcessedEvent.completion_column?
+
+        now = Time.now.utc
+        @mutex.synchronize { @claims.dup }.count { |event_id, handler_class| touch(event_id, handler_class, now) }
+      end
+
+      private
+
+      def touch(event_id, handler_class, now)
+        ProcessedEvent
+          .where(event_id: event_id, handler_class: handler_class, completed_at: nil)
+          .update_all(processed_at: now)
+        true
+      rescue StandardError => e
+        Pgbus.logger.warn do
+          "[Pgbus] Could not refresh idempotency claim #{handler_class}/#{event_id}: #{e.class}: #{e.message}"
+        end
+        false
+      end
+    end
+  end
+end

data/lib/pgbus/event_bus/handler.rb

@@ -17,8 +17,20 @@ module Pgbus
         end
       end
 
-      def process(message)
-        with_rails_executor { process!(message) }
+      # Outcome of the two-phase claim. `age` is how long the losing delivery
+      # found the existing claim to have been silent, in seconds (nil unless
+      # the claim was pending).
+      ClaimResult = Data.define(:status, :age) do
+        def granted?
+          status == :claimed
+        end
+      end
+
+      # @param claim_beat [ClaimBeat, nil] the message's claim-liveness beat,
+      #   supplied by Process::Consumer. Absent for a hand-rolled caller: the
+      #   handler still runs, its claim simply ages from the claim instant.
+      def process(message, claim_beat: nil)
+        with_rails_executor { process!(message, claim_beat) }
       end
 
       def handle(event)
@@ -27,12 +39,18 @@ module Pgbus
 
       private
 
-      def process!(message)
+      def process!(message, claim_beat = nil)
         raw = JSON.parse(message.message)
         event = build_event(raw)
         routing_key = raw.dig("headers", "routing_key") || raw["routing_key"]
 
-        return :skipped if self.class.idempotent? && !claim_idempotency?(event.event_id)
+        if self.class.idempotent?
+          claim = claim_idempotency(event.event_id)
+          unless claim.granted?
+            instrument_skip(claim, event, message, routing_key)
+            return :skipped
+          end
+        end
 
         instrument_payload = {
           event_id: event.event_id,
@@ -42,11 +60,13 @@ module Pgbus
           read_ct: message.read_ct.to_i,
           msg_id: message.msg_id.to_i
         }
-        Instrumentation.instrument("pgbus.event_processed", instrument_payload) do
-          # Publisher's Current attributes (issue #431) are set for the handler
-          # and reverted after (CurrentAttributes#set semantics); the Rails
-          # executor wrap above additionally resets at completion.
-          Pgbus::CurrentAttributes.restore(event.context) { handle(event) }
+        with_claim_beat(claim_beat, event.event_id) do
+          Instrumentation.instrument("pgbus.event_processed", instrument_payload) do
+            # Publisher's Current attributes (issue #431) are set for the handler
+            # and reverted after (CurrentAttributes#set semantics); the Rails
+            # executor wrap above additionally resets at completion.
+            Pgbus::CurrentAttributes.restore(event.context) { handle(event) }
+          end
         end
         complete_claim!(event.event_id) if self.class.idempotent?
         :handled
@@ -64,7 +84,7 @@ module Pgbus
 
       # Mirrors Pgbus::ActiveJob::Executor#execute_job: wrap the handler
       # invocation in Rails.application.executor (or the reloader in dev)
-      # so AR connections leased by `claim_idempotency?` and `handle` are
+      # so AR connections leased by `claim_idempotency` and `handle` are
       # released back to the pool when this method returns. Without the
       # wrap, every consumed event leaks one AR connection on the consumer
       # thread — in dev that wedges `clear_reloadable_connections!`,
@@ -113,24 +133,32 @@ module Pgbus
 
       # Two-phase idempotency claim (issue #385). Phase 1: atomically claim
       # via INSERT ... ON CONFLICT DO NOTHING with completed_at NULL — a
-      # *pending* claim. Returns true when this delivery should run handle:
+      # *pending* claim. Returns a ClaimResult whose status is one of:
       #
-      #   - insert won → fresh claim
-      #   - insert lost, completed_at NULL → a prior attempt claimed but was
-      #     killed before finishing (SIGKILL mid-handler); re-run so the crash
-      #     doesn't silently drop the execution. Safe: PGMQ's VT means the
-      #     prior holder is dead or wedged past its timeout — the same
-      #     at-least-once window every non-idempotent handler has.
+      #   :claimed   — insert won (fresh claim), or the row was purged between
+      #                the losing insert and the read, or an existing pending
+      #                claim has gone silent for longer than the ownership
+      #                window: the holder is dead by the heartbeat's own
+      #                definition, so re-run rather than silently drop the
+      #                execution a SIGKILL interrupted.
+      #   :completed — the execution already finished. Skip.
+      #   :owned     — pending, and its liveness stamp is fresh: the holder is
+      #                still running (issue #470). Skip — running `handle`
+      #                concurrently with the holder is exactly the
+      #                double-execution `idempotent!` promises not to do. The
+      #                holder either completes (nothing lost) or fails, leaving
+      #                its own message for VT redelivery to recover.
+      #   :cached    — a completed execution already in this process's memory.
       #
-      # Returns false (skip) only for a *completed* execution. Phase 2 is
-      # complete_claim! after handle returns; only completed executions enter
-      # the in-memory dedup cache.
+      # Phase 2 is complete_claim! after handle returns; only completed
+      # executions enter the in-memory dedup cache.
       #
       # Legacy fallback: without the completed_at column (upgraded gem,
-      # not-yet-migrated table) this degrades to the old single-phase claim.
-      def claim_idempotency?(event_id)
+      # not-yet-migrated table) this degrades to the old single-phase claim,
+      # which has no pending state and therefore no ownership question.
+      def claim_idempotency(event_id)
         cache_key = dedup_key(event_id)
-        return false if self.class.dedup_cache.seen?(cache_key)
+        return ClaimResult.new(status: :cached, age: nil) if self.class.dedup_cache.seen?(cache_key)
 
         result = ProcessedEvent.insert(
           { event_id: event_id, handler_class: self.class.name, processed_at: Time.now.utc },
@@ -139,18 +167,79 @@ module Pgbus
 
         unless ProcessedEvent.completion_column?
           self.class.dedup_cache.mark!(cache_key)
-          return result.rows.any?
+          return ClaimResult.new(status: result.rows.any? ? :claimed : :completed, age: nil)
         end
 
-        return true if result.rows.any?
+        return ClaimResult.new(status: :claimed, age: nil) if result.rows.any?
 
-        completed_at = ProcessedEvent
-                       .where(event_id: event_id, handler_class: self.class.name)
-                       .pick(:completed_at)
-        return true if completed_at.nil? # pending claim (or purged row) → re-run
+        inspect_existing_claim(event_id, cache_key)
+      end
+
+      # The insert lost, so a row exists (or existed). `pick` returns nil for
+      # the whole row when it has since been purged — not a pending claim,
+      # nothing is running, so claim it.
+      def inspect_existing_claim(event_id, cache_key)
+        completed_at, processed_at = ProcessedEvent
+                                     .where(event_id: event_id, handler_class: self.class.name)
+                                     .pick(:completed_at, :processed_at)
 
-        self.class.dedup_cache.mark!(cache_key)
-        false
+        if completed_at
+          self.class.dedup_cache.mark!(cache_key)
+          return ClaimResult.new(status: :completed, age: nil)
+        end
+
+        return ClaimResult.new(status: :claimed, age: nil) if processed_at.nil?
+
+        age = Time.now.utc - processed_at.to_time.utc
+        return ClaimResult.new(status: :owned, age: age) if age < claim_ownership_window
+
+        ClaimResult.new(status: :claimed, age: age)
+      end
+
+      # How long a pending claim may stay silent before its holder counts as
+      # dead. ClaimBeat refreshes a live claim from the visibility heartbeat,
+      # which lands every extension inside [interval, 1.5 * interval] of the
+      # previous one — two intervals leaves margin for a late beat without
+      # stretching the window past the visibility timeout it rides on.
+      #
+      # With the heartbeat disabled a claim is never refreshed, so the window
+      # degrades to "roughly the first two thirds of one visibility timeout
+      # after the claim" — a redelivery, which cannot arrive before the VT has
+      # lapsed, still re-runs exactly as it did before issue #470.
+      def claim_ownership_window
+        Pgbus.configuration.effective_visibility_heartbeat_interval * 2
+      end
+
+      # Register this claim with the message's beat for exactly the duration of
+      # handle: before it, there is nothing to keep alive; after it,
+      # complete_claim! owns the row and a beat touching processed_at would
+      # race the completion stamp.
+      def with_claim_beat(claim_beat, event_id)
+        return yield unless claim_beat && self.class.idempotent? && ProcessedEvent.completion_column?
+
+        claim_beat.register(event_id, self.class.name)
+        begin
+          yield
+        ensure
+          claim_beat.release(event_id, self.class.name)
+        end
+      end
+
+      # A skip used to be silent, which made an over-eager re-run (issue #470)
+      # invisible in production: nothing distinguished "deduplicated" from
+      # "deferred to a live holder". The claim age and read_ct are what tell
+      # an operator which one happened.
+      def instrument_skip(claim, event, message, routing_key)
+        Instrumentation.instrument(
+          "pgbus.event_skipped",
+          event_id: event.event_id,
+          handler: self.class.name,
+          routing_key: routing_key,
+          reason: claim.status,
+          claim_age: claim.age,
+          read_ct: message.read_ct.to_i,
+          msg_id: message.msg_id.to_i
+        )
       end
 
       # Phase 2: stamp the claim completed and only then admit it to the
@@ -158,12 +247,26 @@ module Pgbus
       # already cached at claim time). If this write fails, process!'s rescue
       # re-raises, the consumer leaves the message for VT redelivery, and the
       # still-pending claim re-runs — at-least-once, never a silent drop.
+      #
+      # Wrapped in StaleConnectionRetry because this is the one AR write that
+      # happens AFTER handle() has already succeeded: a socket dropped here
+      # costs the host app a paging exception for work that was in fact done.
+      # The stamp is an idempotent `SET completed_at = <now>`, so repeating a
+      # statement that may already have committed is safe.
+      #
+      # Phase 1 (claim_idempotency) is deliberately NOT wrapped. Its INSERT
+      # may have committed before the socket died, and on a legacy schema the
+      # retry's empty `result.rows` would read as "someone else owns this
+      # claim" and report :completed — turning a recoverable drop into a
+      # silently skipped event. VT redelivery is the correct recovery there.
       def complete_claim!(event_id)
         return unless ProcessedEvent.completion_column?
 
-        ProcessedEvent
-          .where(event_id: event_id, handler_class: self.class.name)
-          .update_all(completed_at: Time.now.utc)
+        StaleConnectionRetry.call(context: self.class.name) do
+          ProcessedEvent
+            .where(event_id: event_id, handler_class: self.class.name)
+            .update_all(completed_at: Time.now.utc)
+        end
         self.class.dedup_cache.mark!(dedup_key(event_id))
       end
 

data/lib/pgbus/event_bus/publisher.rb

@@ -25,7 +25,7 @@ module Pgbus
           Pgbus::Testing.store.push_event(event)
 
           if Pgbus::Testing.inline? && delay.to_i <= 0
-            Pgbus::EventBus::Registry.instance.handlers_for(routing_key).each do |subscriber|
+            Pgbus::EventBus::Registry.instance.subscribers_matching(routing_key).each do |subscriber|
               Pgbus::CurrentAttributes.restore(event.context) { subscriber.handler_class.new.handle(event) }
             end
           end

data/lib/pgbus/event_bus/registry.rb

@@ -62,7 +62,30 @@ module Pgbus
         end
       end
 
-      def handlers_for(routing_key)
+      # Subscribers a message read from +queue_name+ must be dispatched to
+      # (issue #469). Every subscriber gets its own queue, so a topic with N
+      # matching subscribers produces N queue copies of each event; selecting by
+      # pattern alone fanned every copy out to every match, running each handler
+      # N times per event — and, across hosts, concurrently. Ownership is the
+      # primary filter; the pattern check still applies because a routing key
+      # the owner's pattern does not match means a stale pgmq.topic_bindings
+      # row, and a stale binding must not run the handler.
+      #
+      # +queue_name+ is required on purpose: a keyword-less call would silently
+      # restore the fan-out this closed. Callers that genuinely want the
+      # pattern view (the Testing inline/drain paths, which never touch a
+      # queue) use #subscribers_matching.
+      def handlers_for(routing_key, queue_name:)
+        @subscribers.select do |s|
+          s.queue_name == queue_name && matches?(s.pattern, routing_key)
+        end
+      end
+
+      # Pattern-only selection, with no queue in play. Used by the Testing
+      # inline/drain paths, where the event never reaches PGMQ and each matching
+      # subscriber is invoked exactly once — the same per-subscriber delivery
+      # count owner-only dispatch produces in production.
+      def subscribers_matching(routing_key)
         @subscribers.select { |s| matches?(s.pattern, routing_key) }
       end
 

data/lib/pgbus/event_bus/stale_connection_retry.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module EventBus
+    # Reconnect + one retry for an ActiveRecord socket that died underneath a
+    # long-lived consumer thread.
+    #
+    # A consumer holds its leased connection for the life of the message, and a
+    # pooler restart (PgBouncer `server_idle_timeout`), an admin disconnect or a
+    # brief failover can kill that socket at any point. Rails reconnects most
+    # statements transparently, but `Relation#update_all` is marked
+    # `allow_retry: false`, so the drop propagates — and the only call that
+    # matters here, the phase-2 claim stamp, is exactly an `update_all`. The
+    # host app saw a paging exception on a message whose handler had in fact
+    # succeeded.
+    #
+    # Deliberately narrower than `Client::STALE_CONNECTION_PATTERNS`, and for
+    # the opposite reason. That list excludes mid-flight drops because a
+    # half-committed *enqueue* would duplicate a message on retry. This one
+    # only ever wraps an idempotent `UPDATE ... SET completed_at = <now>`, so a
+    # statement that may already have committed is safe to repeat — which is
+    # what makes the mid-flight shapes retryable here and not there.
+    module StaleConnectionRetry
+      # The socket dying under a statement, not a server refusing us. A refused
+      # or timed-out connection is an outage: retrying it in-process buys
+      # nothing and hides the outage behind a doubled statement timeout.
+      #
+      # "ssl syscall error" is libpq's wording when the peer vanished without a
+      # TLS close_notify — the same drop as "unexpected eof while reading",
+      # reported from the syscall layer instead. It is in
+      # Client::STALE_CONNECTION_PATTERNS for the same reason.
+      TRANSIENT_DROP = /
+        PQconsumeInput|
+        server\ closed\ the\ connection\ unexpectedly|
+        unexpected\ eof\ while\ reading|
+        ssl\ syscall\ error
+      /ix
+
+      module_function
+
+      # Runs the block, and on a transient drop reconnects this thread's lease
+      # and runs it exactly once more. A second drop raises: the socket is not
+      # coming back inside this attempt, and PGMQ's visibility timeout is the
+      # right recovery — it redelivers to a healthy consumer.
+      #
+      # context — an identifier for the log line (the handler class name).
+      def call(context: nil, &block)
+        block.call
+      rescue ActiveRecord::ConnectionFailed => e
+        raise unless transient_drop?(e)
+
+        reconnect_leased!
+        Pgbus.logger.warn do
+          "[Pgbus::EventBus] Retrying after stale ActiveRecord connection drop" \
+            "#{" (#{context})" if context}: #{e.message}"
+        end
+        block.call
+      end
+
+      def transient_drop?(error)
+        return false unless error.is_a?(ActiveRecord::ConnectionFailed)
+
+        [error.message, error.cause&.message].compact.any? { |message| TRANSIENT_DROP.match?(message) }
+      end
+
+      # Only the connections this thread has actually leased.
+      # `clear_all_connections!` would yank sockets out from under sibling
+      # consumers sharing the process, turning one recoverable drop into many.
+      # `active_connection?` returns the lease or nil, and is the accessor this
+      # gem uses everywhere (Streams#current_open_transaction documents why we
+      # never reach for `ActiveRecord::Base.connection`). Its `active_connection`
+      # alias is `:nodoc:` and does not exist at all before Rails 7.2 — below
+      # our floor, so calling it would raise NoMethodError on the one path that
+      # exists to recover from an error.
+      def reconnect_leased!
+        ActiveRecord::Base.connection_handler.each_connection_pool(:all) do |pool|
+          connection = pool.active_connection?
+          next unless connection
+
+          connection.reconnect!
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/instrumentation.rb

@@ -20,6 +20,10 @@ module Pgbus
   #                                  payload: queue, job_class, msg_id, vt, extensions
   #   pgbus.event_processed        — event handler succeeded
   #   pgbus.event_failed           — event handler raised; carries :exception_object
+  #   pgbus.event_unrouted         — a consumer read an event from a queue no
+  #                                  subscriber in this process owns (stale topic
+  #                                  binding); the message is archived
+  #                                  payload: queue_name, routing_key
   #   pgbus.stream.broadcast       — stream broadcast (sync or deferred)
   #   pgbus.outbox.publish         — outbox row created
   #   pgbus.recurring.enqueue      — scheduler enqueued a due recurring task

data/lib/pgbus/metrics/subscriber.rb

@@ -33,6 +33,7 @@ module Pgbus
             subscribe("pgbus.job_visibility_extended") { |event| on_job_visibility_extended(event) },
             subscribe("pgbus.event_processed") { |event| on_event_processed(event) },
             subscribe("pgbus.event_failed") { |event| on_event_failed(event) },
+            subscribe("pgbus.event_skipped") { |event| on_event_skipped(event) },
             subscribe("pgbus.client.send_message") { |event| on_send_message(event) },
             subscribe("pgbus.client.send_batch") { |event| on_send_batch(event) },
             subscribe("pgbus.client.read_batch") { |event| on_read_batch(event) },
@@ -139,6 +140,19 @@ module Pgbus
           )
         end
 
+        # An idempotent handler that did not run this delivery. `reason` is what
+        # makes the skip readable: :completed/:cached is deduplication working,
+        # :owned means a second delivery arrived while the holder was still
+        # running and was deferred to it (issue #470).
+        def on_event_skipped(event)
+          payload = event.payload
+          backend.increment(
+            "#{METRIC_PREFIX}event_count", 1,
+            compact(handler: payload[:handler], routing_key: payload[:routing_key],
+                    status: "skipped", reason: payload[:reason])
+          )
+        end
+
         # ── Client (PGMQ wrapper) ─────────────────────────────────────────
 
         def on_send_message(event)

data/lib/pgbus/process/consumer.rb

@@ -78,6 +78,11 @@ module Pgbus
         )
         @registry = EventBus::Registry.instance
         @circuit_breaker = Pgbus::CircuitBreaker.new(config: config)
+        # Queues already warned about for an unroutable message (issue #469).
+        # handle_message runs on the execution pool, so this is touched from
+        # several threads — Concurrent::Set makes add? the atomic
+        # test-and-set the once-per-queue guarantee needs.
+        @unrouted_queues = Concurrent::Set.new
         # stat_buffer: :default means "build one iff config.stats_enabled";
         # passing an explicit value (including nil) overrides that for tests.
         @stat_buffer =
@@ -222,10 +227,12 @@ module Pgbus
         raw = JSON.parse(message.message)
         routing_key = raw.dig("headers", "routing_key") || raw["routing_key"]
 
-        handlers = @registry.handlers_for(routing_key || "")
-        handlers.each do |subscriber|
-          handler = subscriber.handler_class.new
-          handler.process(message)
+        handlers = @registry.handlers_for(routing_key || "", queue_name: queue_name)
+
+        if handlers.empty?
+          report_unrouted(queue_name, routing_key)
+        else
+          dispatch(handlers, message, queue_name)
         end
 
         Pgbus.client.archive_message(queue_name, message.msg_id.to_i)
@@ -247,6 +254,65 @@ module Pgbus
         @jobs_processed.increment
       end
 
+      # Run every handler that owns this message, with the message's visibility
+      # timeout held open for as long as they take (issue #470).
+      #
+      # Without this the consumer had no equivalent of
+      # ActiveJob::Executor#with_visibility_heartbeat: an event handler slower
+      # than config.visibility_timeout (30s by default) was redelivered *while
+      # still running*, a second consumer read the same envelope, and the
+      # holder's pending idempotency claim was indistinguishable from a claim
+      # left by a crash — so the handler ran twice, concurrently.
+      #
+      # The beat also refreshes the claims the handlers register, which is what
+      # lets Handler tell "holder still running" from "holder died": message
+      # visibility and claim liveness go quiet together when this process does.
+      #
+      # Tracking ends before the caller archives — a beat must never re-arm the
+      # VT of a message that is already gone (same rule as the executor's).
+      def dispatch(handlers, message, queue_name)
+        claim_beat = EventBus::ClaimBeat.new
+
+        VisibilityHeartbeat.track(
+          client: Pgbus.client,
+          queue_name: queue_name,
+          msg_id: message.msg_id.to_i,
+          job_class: "EventConsumer",
+          config: config,
+          on_beat: -> { claim_beat.touch! }
+        ) do
+          handlers.each { |subscriber| subscriber.handler_class.new.process(message, claim_beat: claim_beat) }
+        end
+      end
+
+      # No subscriber in this process owns +queue_name+ (a stale
+      # pgmq.topic_bindings row left by a renamed or removed handler, another
+      # app bound to the same bus), or the owner's pattern no longer matches the
+      # routing key. The message is archived by the caller either way — looping
+      # it through VT redelivery would only walk it into the DLQ — but that used
+      # to happen in total silence. The warning is rate-limited to once per
+      # queue per process so a permanently stale binding cannot flood the log;
+      # the instrumentation fires on every message, so the real rate stays
+      # visible in metrics (issue #469).
+      def report_unrouted(queue_name, routing_key)
+        first_for_queue = @unrouted_queues.add?(queue_name)
+
+        if first_for_queue
+          Pgbus.logger.warn do
+            "[Pgbus] Consumer read an unroutable event from queue #{queue_name} " \
+              "(routing_key=#{routing_key.inspect}): no subscriber in this process owns that queue. " \
+              "Archiving. This usually means a stale topic binding — a handler was renamed or removed " \
+              "without unbinding its queue. Further unrouted messages on this queue are not logged."
+          end
+        end
+
+        Pgbus::Instrumentation.instrument(
+          "pgbus.event_unrouted",
+          queue_name: queue_name,
+          routing_key: routing_key
+        )
+      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.
@@ -521,6 +587,7 @@ module Pgbus
         # wait IS its drain window — bound it by the same knob workers use
         # instead of a hardcoded 30s (issue #386).
         @pool.wait_for_termination(config.drain_timeout)
+        VisibilityHeartbeat.stop
         @stat_buffer&.stop
         @heartbeat&.stop
         restore_signals

data/lib/pgbus/streams/broadcast_opts.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Streams
+    # The thread-local channel that carries pgbus-specific broadcast options
+    # from a `Turbo::Broadcastable` / `Turbo::StreamsChannel` call site down to
+    # `TurboBroadcastable#broadcast_stream_to`, which is the only place with a
+    # `Pgbus::Streams::Stream` to hand them to.
+    #
+    # turbo-rails' broadcast helpers funnel everything through
+    # `broadcast_stream_to(*streamables, content:)` — a signature with nowhere
+    # to put `durable:`, `exclude:`, `visible_to:`, `event:` or `coalesce:`.
+    # Rather than fork turbo's whole helper surface, the patches pull those
+    # kwargs out before calling `super` and stash them here for the duration of
+    # the broadcast.
+    #
+    # Both patches (`BroadcastableOverride` on the model concern and
+    # `TurboBroadcastable` on the channel) share this module so there is one
+    # definition of which keys exist and how they are saved/restored.
+    module BroadcastOpts
+      # Options a caller may pass to any Turbo broadcast helper. They are
+      # deleted from the kwargs so they never reach turbo-rails' renderer.
+      KEYS = %i[durable exclude visible_to event coalesce].freeze
+
+      # `coalesce_target` is not a caller-facing kwarg — it is derived from the
+      # broadcast's own `target:`/`targets:` by the channel patch, because
+      # coalescing keys on `(stream, target)` and `broadcast_stream_to` never
+      # sees the target otherwise.
+      THREAD_LOCALS = {
+        durable: :pgbus_broadcast_durable,
+        exclude: :pgbus_broadcast_exclude,
+        visible_to: :pgbus_broadcast_visible_to,
+        event: :pgbus_broadcast_event,
+        coalesce: :pgbus_broadcast_coalesce,
+        coalesce_target: :pgbus_broadcast_coalesce_target
+      }.freeze
+
+      # Removes the pgbus options from `kwargs` (mutating it) and returns them.
+      # Keys the caller did not pass are absent from the result, so an outer
+      # `BroadcastOpts.with` block's values survive an inner broadcast that
+      # doesn't set them.
+      def self.extract!(kwargs)
+        KEYS.each_with_object({}) do |key, opts|
+          opts[key] = kwargs.delete(key) if kwargs.key?(key)
+        end
+      end
+
+      # Sets the thread-locals for the given options for the duration of the
+      # block, restoring the previous values afterwards (nesting-safe), even on
+      # error. Only the keys passed are touched.
+      def self.with(**opts)
+        previous = {}
+
+        opts.each do |key, value|
+          tl_key = THREAD_LOCALS.fetch(key)
+          previous[tl_key] = Thread.current[tl_key]
+          Thread.current[tl_key] = value
+        end
+
+        yield
+      ensure
+        previous.each { |tl_key, value| Thread.current[tl_key] = value }
+      end
+
+      def self.[](key)
+        Thread.current[THREAD_LOCALS.fetch(key)]
+      end
+    end
+  end
+end

data/lib/pgbus/streams/broadcastable_override.rb

@@ -40,7 +40,7 @@ module Pgbus
       # don't understand. We pull them out of kwargs (so they never reach
       # turbo-rails' renderer) and thread them to broadcast_stream_to via
       # thread-locals, mirroring the original durable: shim.
-      PGBUS_BROADCAST_OPTS = %i[durable exclude visible_to event].freeze
+      PGBUS_BROADCAST_OPTS = BroadcastOpts::KEYS
 
       BROADCAST_METHODS.each do |method_name|
         define_method(method_name) do |*streamables, **kwargs|
@@ -128,32 +128,19 @@ module Pgbus
       private
 
       def extract_pgbus_broadcast_opts(kwargs)
-        PGBUS_BROADCAST_OPTS.each_with_object({}) do |key, opts|
-          opts[key] = kwargs.delete(key) if kwargs.key?(key)
-        end
+        BroadcastOpts.extract!(kwargs)
       end
 
       # Set the pgbus broadcast thread-locals for the duration of the block,
       # restoring previous values afterwards (nested/concurrent-safe). Only
       # keys actually passed are touched, so unrelated outer broadcasts keep
       # their values.
-      def with_pgbus_broadcast_opts(durable: :__unset__, exclude: :__unset__, visible_to: :__unset__, event: :__unset__)
-        previous = {}
-        set = lambda do |tl_key, value|
-          next if value == :__unset__
-
-          previous[tl_key] = Thread.current[tl_key]
-          Thread.current[tl_key] = value
-        end
-
-        set.call(:pgbus_broadcast_durable, durable)
-        set.call(:pgbus_broadcast_exclude, exclude)
-        set.call(:pgbus_broadcast_visible_to, visible_to)
-        set.call(:pgbus_broadcast_event, event)
+      def with_pgbus_broadcast_opts(durable: :__unset__, exclude: :__unset__, visible_to: :__unset__,
+                                    event: :__unset__, coalesce: :__unset__, &)
+        opts = { durable: durable, exclude: exclude, visible_to: visible_to, event: event, coalesce: coalesce }
+        opts.reject! { |_key, value| value == :__unset__ }
 
-        yield
-      ensure
-        previous.each { |tl_key, value| Thread.current[tl_key] = value }
+        BroadcastOpts.with(**opts, &)
       end
     end
   end

data/lib/pgbus/streams/turbo_broadcastable.rb

@@ -34,9 +34,57 @@ module Pgbus
     # long as `Turbo.signed_stream_verifier_key` is set, which the Rails
     # app is already responsible for).
     module TurboBroadcastable
+      # Every targeted broadcast helper (`broadcast_replace_to`,
+      # `broadcast_append_to`, `broadcast_remove_to`, …) funnels through
+      # `broadcast_action_to`, so this is the one place that sees both the
+      # caller's kwargs and the `target:`/`targets:` the frame will carry.
+      #
+      # It does two things the model-level `BroadcastableOverride` can't:
+      #
+      # 1. Extracts the pgbus options from a *direct* channel call —
+      #    `Turbo::StreamsChannel.broadcast_replace_to(..., coalesce: true)` —
+      #    which never passes through `Turbo::Broadcastable` at all (this is
+      #    the path phlex-reactive's `Streamable.broadcast_to` takes).
+      # 2. Records the coalescing key. `coalesce:` dedupes on
+      #    `(stream, target)`, but `broadcast_stream_to` only receives the
+      #    rendered `content:` — the target is gone by then. We resolve it the
+      #    same way turbo will (`convert_to_turbo_stream_dom_id`), so a record
+      #    target keys on its stable dom_id rather than its object id.
+      #
+      # Resolving the key is skipped entirely unless coalescing was actually
+      # requested, so the uncoalesced path stays byte-identical and free.
+      def broadcast_action_to(*streamables, action:, target: nil, targets: nil, **rendering)
+        opts = BroadcastOpts.extract!(rendering)
+
+        coalesce = opts.key?(:coalesce) ? opts[:coalesce] : BroadcastOpts[:coalesce]
+        opts[:coalesce_target] = pgbus_coalesce_target(target, targets) if coalesce
+
+        BroadcastOpts.with(**opts) do
+          super(*streamables, action: action, target: target, targets: targets, **rendering)
+        end
+      end
+
+      # The two helpers that don't pass through `broadcast_action_to`. They
+      # carry no target, so they can't coalesce (`Stream#broadcast` raises an
+      # actionable error, same as `Pgbus.stream(x).broadcast(coalesce:)`
+      # without one) — but they still need their pgbus options pulled out of
+      # the kwargs, or a direct channel call leaks `durable: true` into
+      # turbo's renderer and it ends up as an HTML attribute.
+      def broadcast_refresh_to(*streamables, **attributes)
+        BroadcastOpts.with(**BroadcastOpts.extract!(attributes)) do
+          super(*streamables, **attributes)
+        end
+      end
+
+      def broadcast_render_to(*streamables, **rendering)
+        BroadcastOpts.with(**BroadcastOpts.extract!(rendering)) do
+          super(*streamables, **rendering)
+        end
+      end
+
       def broadcast_stream_to(*streamables, content:)
         name = stream_name_from(streamables)
-        override = Thread.current[:pgbus_broadcast_durable]
+        override = BroadcastOpts[:durable]
         # When no explicit thread-local override is present, let the config
         # resolver decide: it checks `streams_durable_patterns` first (exact
         # string or regex match), then falls back to
@@ -46,11 +94,24 @@ module Pgbus
         durable = override.nil? ? Pgbus.configuration.stream_durable?(name) : override
         Pgbus.stream(name, durable: durable).broadcast(
           content,
-          exclude: Thread.current[:pgbus_broadcast_exclude],
-          visible_to: Thread.current[:pgbus_broadcast_visible_to],
-          event: Thread.current[:pgbus_broadcast_event]
+          exclude: BroadcastOpts[:exclude],
+          visible_to: BroadcastOpts[:visible_to],
+          event: BroadcastOpts[:event],
+          coalesce: BroadcastOpts[:coalesce],
+          target: BroadcastOpts[:coalesce_target]
         )
       end
+
+      private
+
+      # The coalescing key, resolved exactly as turbo resolves the rendered
+      # `target=`/`targets=` attribute. `targets:` (a CSS selector) is the
+      # fallback turbo itself uses when `target:` is absent; we drop the `#`
+      # selector prefix because the key is never rendered — it only has to be
+      # stable and distinct.
+      def pgbus_coalesce_target(target, targets)
+        convert_to_turbo_stream_dom_id(target) || convert_to_turbo_stream_dom_id(targets)
+      end
     end
 
     # Apply the patch to Turbo::StreamsChannel's singleton class. Idempotent:

data/lib/pgbus/testing.rb

@@ -58,7 +58,7 @@ module Pgbus
           event = @mutex.synchronize { @events.first }
           break unless event
 
-          Pgbus::EventBus::Registry.instance.handlers_for(event.routing_key).each do |subscriber|
+          Pgbus::EventBus::Registry.instance.subscribers_matching(event.routing_key).each do |subscriber|
             # Restore the publisher's Current (issue #431) like the consumer does.
             Pgbus::CurrentAttributes.restore(event.context) { subscriber.handler_class.new.handle(event) }
           end

data/lib/pgbus/version.rb

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

data/lib/pgbus/visibility_heartbeat.rb

@@ -25,9 +25,15 @@ module Pgbus
   # out with `pgbus_visibility_heartbeat false`.
   module VisibilityHeartbeat
     # `concurrency` is `[key, duration]` for a concurrency-limited job, else
-    # nil — one member, so the struct stays inside an 80-byte slot.
+    # nil. `on_beat` is an optional callable run on every extension — the event
+    # consumer uses it to refresh its handlers' idempotency claims (issue #470).
+    #
+    # The ninth member takes the struct out of the 80-byte slot it used to fit
+    # (measured: 80 → 160). That is paid at most once per in-flight message, so
+    # the whole table is bounded by the execution pool's capacity — a handful of
+    # entries per process, not one per enqueued job.
     Entry = Struct.new(:client, :queue_name, :prefixed, :msg_id, :job_class, :extended_at, :extensions,
-                       :concurrency, keyword_init: true)
+                       :concurrency, :on_beat, keyword_init: true)
 
     # Per-job opt-out, included on ActiveJob::Base by the engine:
     #
@@ -59,13 +65,14 @@ module Pgbus
       # @param config [Pgbus::Configuration]
       # @param concurrency [Array(String, Numeric), nil] semaphore key to keep alive alongside
       #   the message and how far to push its expiry on each beat
+      # @param on_beat [#call, nil] run after each extension; its failures are contained
       def track(client:, queue_name:, msg_id:, prefixed: true, job_class: nil, config: Pgbus.configuration,
-                concurrency: nil)
+                concurrency: nil, on_beat: nil)
         return yield unless config.visibility_heartbeat
 
         entry = Entry.new(client: client, queue_name: queue_name, prefixed: prefixed, msg_id: msg_id.to_i,
                           job_class: job_class, extended_at: monotonic_now, extensions: 0,
-                          concurrency: concurrency)
+                          concurrency: concurrency, on_beat: on_beat)
         register(entry, config)
         begin
           yield
@@ -130,6 +137,7 @@ module Pgbus
         entry.extended_at = now
         entry.extensions += 1
         touch_semaphore(entry)
+        run_on_beat(entry)
         Instrumentation.instrument(
           "pgbus.job_visibility_extended",
           queue: entry.queue_name, job_class: entry.job_class, msg_id: entry.msg_id, vt: vt,
@@ -186,6 +194,17 @@ module Pgbus
         end
       end
 
+      # Same containment as touch_semaphore: a lease the beat keeps alive
+      # alongside the message must never cost the message its extension.
+      def run_on_beat(entry)
+        entry.on_beat&.call
+      rescue StandardError => e
+        Pgbus.logger.warn do
+          "[Pgbus::VisibilityHeartbeat] on_beat hook failed for msg_id=#{entry.msg_id} " \
+            "queue=#{entry.queue_name}: #{e.class}: #{e.message}"
+        end
+      end
+
       def forget_parent_entries!
         return if @pid == ::Process.pid
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.16.5
+  version: 0.16.7
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -291,9 +291,11 @@ files:
 - lib/pgbus/engine.rb
 - lib/pgbus/error_reporter.rb
 - lib/pgbus/event.rb
+- lib/pgbus/event_bus/claim_beat.rb
 - lib/pgbus/event_bus/handler.rb
 - lib/pgbus/event_bus/publisher.rb
 - lib/pgbus/event_bus/registry.rb
+- lib/pgbus/event_bus/stale_connection_retry.rb
 - lib/pgbus/event_bus/subscriber.rb
 - lib/pgbus/execution_pools.rb
 - lib/pgbus/execution_pools/async_pool.rb
@@ -375,6 +377,7 @@ files:
 - lib/pgbus/serializer.rb
 - lib/pgbus/stat_buffer.rb
 - lib/pgbus/streams.rb
+- lib/pgbus/streams/broadcast_opts.rb
 - lib/pgbus/streams/broadcastable_override.rb
 - lib/pgbus/streams/coalescer.rb
 - lib/pgbus/streams/cursor.rb