pgbus 0.16.4 → 0.16.6

data/config/locales/pt.yml

@@ -86,6 +86,8 @@ pt:
         enqueued: Enfileirado
         failed_dlq: Falhou / DLQ
         failed_dlq_labels: Falhados / Dead Lettered
+        parked_jobs: Trabalhos estacionados
+        parked_jobs_oldest: mais antigo %{age}
         processes: Processos
         queues: Filas
         recurring: Recorrente
@@ -404,6 +406,43 @@ pt:
       toggle_dark_mode: Alternar modo escuro
       toggle_menu: Alternar menu
     locks:
+      concurrency:
+        cards:
+          keys_at_limit: Chaves no limite
+          keys_at_limit_hint: sem vaga livre
+          oldest_wait: Espera mais longa
+          oldest_wait_hint: o trabalho que espera há mais tempo
+          parked_jobs: Trabalhos estacionados
+          parked_jobs_hint: à espera de uma vaga
+          slots_held: Vagas ocupadas
+          slots_held_hint: em todas as chaves
+        description: Chaves declaradas com limits_concurrency, as vagas que ocupam e os trabalhos estacionados atrás delas
+        discard_parked: Descartar estacionados
+        discard_parked_confirm:
+          one: Descartar o trabalho estacionado atrás desta chave? Nunca será executado.
+          other: Descartar os %{count} trabalhos estacionados atrás desta chave? Nunca serão executados.
+        empty: Nenhuma chave de concorrência em uso
+        headers:
+          in_use: Em uso
+          key: Chave
+          lease: Concessão
+          oldest_wait: Espera mais longa
+          parked: Estacionados
+        key_released:
+          one: "%{key} libertada e 1 trabalho promovido."
+          other: "%{key} libertada e %{count} trabalhos promovidos."
+        lease:
+          expired: Expirada
+          live: Ativa
+          none: Sem detentor
+        no_key: Nenhuma chave de concorrência indicada.
+        parked_discarded:
+          one: 1 trabalho estacionado descartado.
+          other: "%{count} trabalhos estacionados descartados."
+        release: Libertar
+        release_confirm: Libertar %{key} e promover os seus trabalhos estacionados?
+        release_confirm_live: A concessão de %{key} ainda está válida, por isso é provável que um trabalho continue a correr. Libertar permite que outro arranque ao lado. Continuar?
+        title: Concorrência
       index:
         all_locks_discarded:
           one: 1 bloqueio descartado.
@@ -427,7 +466,9 @@ pt:
           one: 1 bloqueio descartado.
           other: "%{count} bloqueios descartados."
         none_selected: Nenhum bloqueio selecionado.
-        title: Chaves de unicidade
+        page_description: Chaves de unicidade e vagas de concorrência que estão a reter trabalhos
+        title: Bloqueios
+        uniqueness_title: Chaves de unicidade
     outbox:
       index:
         description: Entradas da caixa de saída transacional pendentes de publicação para PGMQ

data/config/locales/sv.yml

@@ -86,6 +86,8 @@ sv:
         enqueued: Inlagda
         failed_dlq: Misslyckade / DLQ
         failed_dlq_labels: Misslyckade / Dead Lettered
+        parked_jobs: Parkerade jobb
+        parked_jobs_oldest: äldst %{age}
         processes: Processer
         queues: Köer
         recurring: Återkommande
@@ -404,6 +406,43 @@ sv:
       toggle_dark_mode: Växla mörkt läge
       toggle_menu: Växla meny
     locks:
+      concurrency:
+        cards:
+          keys_at_limit: Nycklar vid gränsen
+          keys_at_limit_hint: ingen ledig plats
+          oldest_wait: Längsta väntan
+          oldest_wait_hint: längst ett jobb har väntat
+          parked_jobs: Parkerade jobb
+          parked_jobs_hint: väntar på en plats
+          slots_held: Hållna platser
+          slots_held_hint: över alla nycklar
+        description: Nycklar deklarerade med limits_concurrency, platserna de håller och jobben som parkerats bakom dem
+        discard_parked: Kasta parkerade
+        discard_parked_confirm:
+          one: Kasta det 1 jobb som parkerats bakom denna nyckel? Det kommer aldrig att köras.
+          other: Kasta de %{count} jobb som parkerats bakom denna nyckel? De kommer aldrig att köras.
+        empty: Inga samtidighetsnycklar används
+        headers:
+          in_use: Används
+          key: Nyckel
+          lease: Lås
+          oldest_wait: Längsta väntan
+          parked: Parkerade
+        key_released:
+          one: Frigjorde %{key} och befordrade 1 jobb.
+          other: Frigjorde %{key} och befordrade %{count} jobb.
+        lease:
+          expired: Utgånget
+          live: Aktivt
+          none: Ingen innehavare
+        no_key: Ingen samtidighetsnyckel angiven.
+        parked_discarded:
+          one: Kastade 1 parkerat jobb.
+          other: Kastade %{count} parkerade jobb.
+        release: Frigör
+        release_confirm: Frigör %{key} och befordra dess parkerade jobb?
+        release_confirm_live: Låset på %{key} är fortfarande färskt, så ett jobb körs troligen än. Att frigöra låter ett annat starta bredvid det. Fortsätta?
+        title: Samtidighet
       index:
         all_locks_discarded:
           one: Kasserade 1 lås.
@@ -427,7 +466,9 @@ sv:
           one: Kasserade 1 lås.
           other: Kasserade %{count} lås.
         none_selected: Inga lås valda.
-        title: Unikhetsnycklar
+        page_description: Unikhetsnycklar och samtidighetsplatser som håller tillbaka jobb
+        title: Lås
+        uniqueness_title: Unikhetsnycklar
     outbox:
       index:
         description: Transaktionella utboxposter som väntar på publicering till PGMQ

data/config/routes.rb

@@ -81,6 +81,11 @@ Pgbus::Engine.routes.draw do
     collection do
       post :discard_selected
       post :discard_all
+      # Collection routes, not member: a concurrency key is a free-form
+      # string that may contain ".", "/" or ":" and does not belong in a
+      # path segment. Both take the key as a form param.
+      post :release_key
+      post :discard_parked
     end
   end
   resource :insights, only: [:show], controller: "insights"

data/lib/pgbus/event_bus/handler.rb

@@ -158,12 +158,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 return false — 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/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

@@ -29,6 +29,9 @@ module Pgbus
   #   pgbus.serializer.deserialize — job/event deserialization
   #   pgbus.batch_finished         — batch flipped to finished
   #                                  payload: batch_id, total_jobs, completed_jobs, failed_jobs
+  #   pgbus.blocked_execution_discarded — a parked job was discarded from the
+  #                                  dashboard; it will never run
+  #                                  payload: concurrency_key, job_class, job_id
   #   pgbus.batch_sweep            — dispatcher stalled-batch sweep
   #                                  payload: stalled_for, stale_executions, orphan_rows,
   #                                  started_batches, finished_batches

data/lib/pgbus/integrations/appsignal/dashboard.json

@@ -355,6 +355,44 @@
             "tags": []
           }
         ]
+      },
+      {
+        "type": "timeseries",
+        "display": "LINE",
+        "title": "Concurrency",
+        "description": "Jobs parked behind a concurrency key, how long the oldest has waited, and slots held across all keys.",
+        "line_label": "%name%",
+        "format": "number",
+        "draw_null_as_zero": true,
+        "metrics": [
+          {
+            "name": "pgbus_concurrency_blocked_executions",
+            "fields": [
+              {
+                "field": "gauge"
+              }
+            ],
+            "tags": []
+          },
+          {
+            "name": "pgbus_concurrency_blocked_oldest_age_seconds",
+            "fields": [
+              {
+                "field": "gauge"
+              }
+            ],
+            "tags": []
+          },
+          {
+            "name": "pgbus_concurrency_slots_held",
+            "fields": [
+              {
+                "field": "gauge"
+              }
+            ],
+            "tags": []
+          }
+        ]
       }
     ]
   }

data/lib/pgbus/integrations/appsignal/probe.rb

@@ -60,6 +60,11 @@ module Pgbus
           def call
             return unless data_source
 
+            # One Runner lives for the life of the process, so its DataSource
+            # does too — without this, every memoized read (queue metrics, the
+            # concurrency aggregates) would report the first minute's numbers
+            # forever.
+            data_source.reset_cache! if data_source.respond_to?(:reset_cache!)
             track_queues
             track_processes
             track_summary
@@ -116,6 +121,11 @@ module Pgbus
             gauge "total_dead_tuples", stats[:total_dead_tuples]
             gauge "tables_needing_vacuum", stats[:tables_needing_vacuum]
             gauge "oldest_transaction_age_seconds", stats[:oldest_transaction_age_sec]
+            # Unlabelled, same rationale as the /pgbus/api/metrics family:
+            # concurrency keys are per-record and would be unbounded as tags.
+            gauge "concurrency_blocked_executions", stats[:parked_total]
+            gauge "concurrency_blocked_oldest_age_seconds", stats[:oldest_parked_age_sec]
+            gauge "concurrency_slots_held", stats[:slots_held]
           rescue StandardError => e
             log_failure("summary metrics", e)
           end

data/lib/pgbus/mcp/base_tool.rb

@@ -36,8 +36,13 @@ module Pgbus
         # Pull the injected DataSource (or build a default one). Kept as a
         # class method because MCP tool entry points (`self.call`) are class
         # methods.
+        # The server injects ONE DataSource for the life of the process, so its
+        # per-request memos have to be dropped per tool call — otherwise every
+        # call after the first replays the first call's snapshot.
         def data_source_from(server_context)
-          (server_context && server_context[:data_source]) || Pgbus::Web::DataSource.new
+          data_source = (server_context && server_context[:data_source]) || Pgbus::Web::DataSource.new
+          data_source.reset_cache! if data_source.respond_to?(:reset_cache!)
+          data_source
         end
 
         # Whether payloads may be returned for this call. Honors a per-call

data/lib/pgbus/mcp/server.rb

@@ -23,6 +23,7 @@ module Pgbus
         Tools::DlqTool,
         Tools::DlqDetailTool,
         Tools::LocksTool,
+        Tools::ConcurrencyTool,
         Tools::ThroughputTool,
         Tools::StatsTool,
         Tools::RecurringTool
@@ -32,7 +33,7 @@ module Pgbus
         Read-only diagnostic tools for a pgbus (PostgreSQL/PGMQ) deployment.
         Start with pgbus_health for a one-call OK/DEGRADED/STALLED verdict,
         then drill in with pgbus_queues, pgbus_processes, pgbus_jobs,
-        pgbus_dlq, and pgbus_locks. No tool mutates state. Message payloads
+        pgbus_dlq, pgbus_locks, and pgbus_concurrency. No tool mutates state. Message payloads
         are redacted unless the server was started with payloads explicitly
         allowed.
       TEXT

data/lib/pgbus/mcp/tools/concurrency_tool.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    module Tools
+      # Reports concurrency-key pressure: how many jobs are parked behind a
+      # `limits_concurrency` key, how long the oldest has waited, how many slots
+      # are held, and the per-key detail behind those numbers. Maps to
+      # DataSource#concurrency_stats. Carries no job payloads — only key names,
+      # counts and lease state — so there is nothing to redact.
+      class ConcurrencyTool < BaseTool
+        tool_name "pgbus_concurrency"
+        title "Pgbus Concurrency"
+        description <<~DESC
+          Report concurrency keys and the jobs parked behind them: total parked
+          jobs, the oldest parked job's wait in seconds, slots held, and keys at
+          their limit — plus up to 100 key rows with value/limit, lease expiry,
+          whether the lease is still fresh, parked count and oldest wait. A key
+          with a stale lease and a parked backlog is a stuck pipeline: its holder
+          died before releasing the slot.
+        DESC
+
+        input_schema(properties: {}, required: [])
+
+        def self.call(server_context: nil)
+          data_source = data_source_from(server_context)
+          json_response(data_source.concurrency_stats)
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/mcp.rb

@@ -24,6 +24,7 @@ module Pgbus
       pgbus/mcp/tools/dlq_tool
       pgbus/mcp/tools/dlq_detail_tool
       pgbus/mcp/tools/locks_tool
+      pgbus/mcp/tools/concurrency_tool
       pgbus/mcp/tools/throughput_tool
       pgbus/mcp/tools/stats_tool
       pgbus/mcp/tools/recurring_tool

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/version.rb

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