pgbus 0.9.0 → 0.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93b9de67b282c7c707b2dcd4222ddde62d758447cc4769f72046dcf5b017dd92
-  data.tar.gz: 1a30a5e46ec20f02fa1cca3d56435c4e2c7f426a3933c523351503f0b69bff64
+  metadata.gz: 5027c420c26dac65291e11e07ca0291da540b7d2aef9d963e9fdebc2217e7943
+  data.tar.gz: 9e66b85229c55528b3b5b2093883935c1333733018508bb6d9f7f7836666363d
 SHA512:
-  metadata.gz: 8912988721d6dfcf064693b9a84a6d1925a3535535b4b584abbdb2d311f80a5c1d7f6503c72da2825cbdfaf8daedb9c9e04b53353d3cc81279945b616a47a204
-  data.tar.gz: '0668b1229a24e47bcdc7fbb3d5f5fcfe95417329be2cdf14eb039cd9e258c22cefcaa4dbb3f2d17a84d5f0aa2c8a6def94971f9a51913ae028f395ac7758168c'
+  metadata.gz: 9c476c7de9c0db40e0d2183a11f7d502704a468e68f49b28934619cfab07f1130f3988d6f0fbfa6e77a57d6450aa183746b301367e0d4af7dcd2779319f96ff7
+  data.tar.gz: ed62152e6c2c361c5b8f38c61e31ea4e3af5d031cf68f71d0ea95177ab04f538bfbb4fefc84f5d08a2acd8efb23b0024d6433d4a6db2272e7c05521a59e83a3b

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+### Added
+
+- **Streams: optional publish-side coalescing for high-frequency broadcasts.** A chatty reactive component (live cursor, typing indicator, progress bar) can fan out many small broadcasts per second. Pass `coalesce:` (a window in milliseconds, or `true` for the 50ms default) with `target:` to `broadcast`/`broadcast_render` to batch per `(stream, target)` and publish only the *latest* frame within the window — superseded frames never hit the bus (no PGMQ insert, no NOTIFY, no fan-out). Last-write-wins, so it is opt-in and only safe for idempotent `replace`/`update` of a stable target (exactly the high-frequency case). The new `Pgbus::Streams::Coalescer` is a process-wide, thread-safe, trailing-edge-with-max-wait debounce: the first submit per window schedules the flush (bounding latency to one window) and later submits only overwrite the buffered payload; the flush re-enters the normal broadcast path, so a coalesced frame is just a deferred ordinary broadcast that still composes with `visible_to`/`exclude`/`event`/`durable`. Refs #171.
+
+- **Streams: typed SSE event names on broadcasts.** A broadcast can set the SSE `event:` field — `Pgbus.stream(name).broadcast(html, event: "presence")` (and `broadcast_render(..., event:)`) — while keeping the payload a Turbo Stream, so clients route on the typed name instead of sniffing the HTML. The default (`nil` or `"turbo-stream"`) is omitted from the JSONB payload to avoid redundancy, but is still set on the SSE frame's `event:` line (the connection adapter falls back to `turbo-stream`), so default consumers still get the standard `message`/turbo-stream path. The event flows through the JSONB payload → `StreamEnvelope.event` → the SSE frame's `event:` line (both the Puma and Falcon connection adapters). On the client, `<pgbus-stream-source>` dispatches a typed broadcast as a generic `pgbus:event` (`{ event, data, msgId }`) and a named `pgbus:<event>` (`{ data, msgId }`) for `addEventListener` ergonomics; declare typed event names via the element's `listen-events` attribute so they survive the EventSource reconnect path. Refs #170.
+
+- **Streams: optional connection-driven presence.** Streams matching `config.streams_presence_patterns` (exact string or Regexp, mirroring `streams_durable_patterns`) now auto-join a member on SSE connect, auto-leave on disconnect, and refresh `last_seen_at` on the keepalive heartbeat — no explicit `join`/`leave`/sweeper wiring. Identity comes from the connection's authorize-hook context: the built-in extractor handles a Hash with `:member_id`/`:id` (plus optional `:metadata`) or any object responding to `#id`, and `config.streams_presence_member` accepts a custom `->(context) { { id:, metadata: } }`. Membership work runs on the dispatcher thread (which already releases AR connections each pass); the heartbeat posts a batched `PresenceTouchMessage` per tick. Presence failures are logged and swallowed so a presence-DB hiccup can't knock a live SSE connection out of the registry. Anonymous connections (no derivable member) are simply skipped. Refs #169.
+
+- **Streams: msg_id (revision) exposed to the client for optimistic-UI reconciliation.** Each delivered turbo-stream frame already carries its monotonic `msg_id` as the SSE `id:`; `<pgbus-stream-source>` now surfaces it two ways: the standard `message` MessageEvent sets `lastEventId` to the msg_id (Turbo ignores it; a reactive runtime listening for `message` reads the revision with no pgbus-specific API), and a new `pgbus:message` CustomEvent carries `{ msgId, data }` (msgId is a Number when numeric; a negative value marks an ephemeral frame). Documents the reconciliation pattern: track the highest applied msgId per target and skip the morph if a newer revision was already applied, so a late echo can't clobber a newer optimistic edit. Complements #165 (exclude handles the actor; the revision handles out-of-order delivery for everyone else). Refs #168.
+
+- **Streams: `Stream#broadcast_render` — render a renderable and broadcast it in one call.** `Pgbus.stream(name).broadcast_render(renderable:, target:, action: :replace, exclude:, visible_to:, durable:)` renders a Phlex component, a ViewComponent, or a pre-rendered HTML string into a complete `<turbo-stream action target><template>…</template></turbo-stream>` tag and broadcasts it atomically — removing the off-request render + tag-building boilerplate (and the easy-to-get-wrong view context) from every call site. `action` defaults to `:replace`; content-less actions (`remove`) emit no `<template>`. `exclude:`/`visible_to:`/`durable:` forward to `#broadcast`, so actor-echo suppression and audience filtering compose. Self-contained (no turbo-rails/ActionView/Phlex dependency); the renderable is resolved via `String` → `#call` (Phlex) → `#render_in` (ViewComponent) → `#to_s`. Refs #166.
+
+- **Streams: actor-echo suppression via `exclude:` on broadcasts.** A broadcast can now name a connection id to skip: `Pgbus.stream(name).broadcast(html, exclude: connection_id)` (and `visible_to:` composes with it). The dispatcher skips delivery to that one SSE connection, so an actor who triggered a change does not receive the echo of its own broadcast — it already applied the change via its action's HTTP response, and re-applying the SSE echo would double-apply (re-run animations, clobber optimistic edits). Every server-minted SSE connection now exposes its id to the page: the server sends a `pgbus:connected` frame right after the open handshake, and `<pgbus-stream-source>` captures it onto the element's `connection-id` attribute and re-dispatches it as a `pgbus:connected` event (also surfaced in `pgbus:open`'s detail). A page reads its connection id and sends it back as the `X-Pgbus-Connection` header on action requests; the broadcaster passes `exclude: request.headers["X-Pgbus-Connection"]`. Reuses the existing per-connection delivery (Filters) path. Refs #165.
+
+- **Streams: `Pgbus.stream_key` is idempotent for an already-built key, plus `Pgbus.stream_key!`.** A single `String` argument is now treated as a pre-built pgbus stream key and returned unchanged (after the queue-name budget check) instead of tripping the colon-separator guard. This lets a consumer hold one `stream_key` value and pass it to both `turbo_stream_from` and the broadcaster without `stream_key("chat:lobby")` raising `ArgumentError`. The guard still fires for the genuinely ambiguous multi-fragment join (`stream_key("a:b", :c)`), and `Symbol`/record fragments with colons are still rejected (a colon there never came from `stream_key`). `Pgbus.stream_key!(key)` accepts a pre-built key explicitly (String required, budget enforced). Refs #167.
+
 ### Breaking Changes
 
 - **Queue names must be alphanumeric and underscores only.** Queue names containing dashes (e.g., `my-app-queue`) will now raise `ArgumentError`. Rename to underscored form (e.g., `my_app_queue`) before upgrading. This restriction prevents SQL injection via PGMQ queue identifiers, which are interpolated into table names and cannot be parameterized.

data/app/assets/javascripts/pgbus/stream_source_element.js

@@ -17,12 +17,32 @@
 //   channel             — compatibility shim; ignored
 //
 // Events (dispatched on the element):
-//   pgbus:open         { lastEventId }
+//   message            (MessageEvent) data = turbo-stream HTML;
+//                      lastEventId = the frame's msg_id (revision)
+//   pgbus:message      { msgId, data } — same frame, for optimistic-UI
+//                      reconciliation (skip morph if a newer rev for the
+//                      target was already applied). See #168.
+//   pgbus:event        { event, data, msgId } — a typed broadcast (any SSE
+//                      event name other than turbo-stream). See #170.
+//   pgbus:<event>      { data, msgId } — the same typed broadcast, named
+//                      for ergonomic addEventListener("pgbus:presence").
+//   pgbus:open         { lastEventId, connectionId }
+//   pgbus:connected    { connectionId }
 //   pgbus:replay-start { fromId, toId }
 //   pgbus:replay-end   {}
 //   pgbus:gap-detected { lastSeenId, archiveOldestId }
 //   pgbus:close        { code, reason }
 //
+// Connection id (issue #165 — actor-echo suppression): the server sends a
+// `pgbus:connected` frame right after the open handshake carrying the
+// server-minted connection id. This element captures it, reflects it onto
+// the `connection-id` attribute, and re-dispatches it as `pgbus:connected`.
+// A page reads it (from the element or a `<meta name="pgbus-connection-id">`
+// the app mirrors it to) and sends it back as the `X-Pgbus-Connection`
+// header on action requests. The broadcaster then passes
+// `exclude: request.headers["X-Pgbus-Connection"]` so the actor does not
+// receive the echo of its own broadcast.
+//
 // The element integrates with Turbo via connectStreamSource /
 // disconnectStreamSource + dispatching MessageEvent("message") so Turbo
 // Stream HTML is automatically consumed by the existing StreamObserver.
@@ -48,9 +68,17 @@ class PgbusStreamSourceElement extends HTMLElement {
     this.abortController = null
     this.eventSource = null
     this.lastEventId = null
+    this.connectionId = null
     this.closed = false
   }
 
+  // The server-minted connection id for this SSE connection, or null
+  // until the `pgbus:connected` frame arrives. Public read accessor so
+  // a reactive runtime can grab it without poking at attributes.
+  get pgbusConnectionId() {
+    return this.connectionId
+  }
+
   connectedCallback() {
     this.closed = false
     connectStreamSource(this)
@@ -80,6 +108,12 @@ class PgbusStreamSourceElement extends HTMLElement {
   // the URL. Parses the SSE event stream by hand because EventSource
   // doesn't expose custom query strings uniformly across browsers.
   async openFetchStream() {
+    // Each transport open is a fresh connection: the server mints a new id
+    // and sends a new pgbus:connected frame. Clear the previous id so
+    // pgbus:open (which fires before that frame arrives) can't surface a
+    // stale connection id — a stale id would produce a wrong X-Pgbus-Connection
+    // exclude header during reconnect windows.
+    this.resetConnectionId()
     const url = this.buildUrl({ includeSince: true })
     this.abortController = new AbortController()
 
@@ -99,7 +133,7 @@ class PgbusStreamSourceElement extends HTMLElement {
 
       this.setAttribute("connected", "")
       this.dispatchEvent(new CustomEvent("pgbus:open", {
-        detail: { lastEventId: this.lastEventId }
+        detail: { lastEventId: this.lastEventId, connectionId: this.connectionId }
       }))
 
       const reader = response.body.getReader()
@@ -137,13 +171,17 @@ class PgbusStreamSourceElement extends HTMLElement {
   switchToEventSource() {
     if (this.closed) return
 
+    // Fresh connection on reconnect — drop the previous connection id so
+    // pgbus:open can't emit a stale one before the new pgbus:connected
+    // frame lands. See openFetchStream.
+    this.resetConnectionId()
     const url = this.buildUrl({ includeSince: true })
     this.eventSource = new EventSource(url, { withCredentials: true })
 
     this.eventSource.addEventListener("open", () => {
       this.setAttribute("connected", "")
       this.dispatchEvent(new CustomEvent("pgbus:open", {
-        detail: { lastEventId: this.lastEventId }
+        detail: { lastEventId: this.lastEventId, connectionId: this.connectionId }
       }))
     })
 
@@ -153,7 +191,11 @@ class PgbusStreamSourceElement extends HTMLElement {
 
     this.eventSource.addEventListener("turbo-stream", (event) => {
       this.lastEventId = event.lastEventId
-      this.dispatchEvent(new MessageEvent("message", { data: event.data }))
+      this.emitTurboStream(event.data, event.lastEventId)
+    })
+
+    this.eventSource.addEventListener("pgbus:connected", (event) => {
+      this.handleConnected(event.data)
     })
 
     this.eventSource.addEventListener("pgbus:gap-detected", (event) => {
@@ -166,6 +208,15 @@ class PgbusStreamSourceElement extends HTMLElement {
         detail: { code: "shutdown", reason: "worker restart" }
       }))
     })
+
+    // Typed broadcasts (issue #170): EventSource only fires listeners
+    // registered by name, so we register one per declared typed event.
+    for (const name of this.declaredTypedEvents()) {
+      this.eventSource.addEventListener(name, (event) => {
+        if (event.lastEventId) this.lastEventId = event.lastEventId
+        this.emitTypedEvent(name, event.data, event.lastEventId)
+      })
+    }
   }
 
   // Parses a single SSE event block (: comment | id: ... | event: ... | data: ...)
@@ -185,7 +236,9 @@ class PgbusStreamSourceElement extends HTMLElement {
     if (id !== null) this.lastEventId = id
 
     if (event === "turbo-stream") {
-      this.dispatchEvent(new MessageEvent("message", { data }))
+      this.emitTurboStream(data, id)
+    } else if (event === "pgbus:connected") {
+      this.handleConnected(data)
     } else if (event === "pgbus:gap-detected") {
       this.dispatchEvent(new CustomEvent("pgbus:gap-detected", {
         detail: this.safeJsonParse(data)
@@ -194,9 +247,101 @@ class PgbusStreamSourceElement extends HTMLElement {
       this.dispatchEvent(new CustomEvent("pgbus:close", {
         detail: { code: "shutdown", reason: "worker restart" }
       }))
+    } else {
+      // A typed broadcast (issue #170): event: presence | reactive | ...
+      this.emitTypedEvent(event, data, id)
     }
   }
 
+  // Captures the server-minted connection id from a `pgbus:connected`
+  // frame: stores it, reflects it onto the `connection-id` attribute (so
+  // it's visible in the DOM / to MutationObservers), and re-dispatches it
+  // as a `pgbus:connected` CustomEvent. Idempotent across reconnects — the
+  // server mints a fresh id per connection, so a reconnect updates it.
+  handleConnected(data) {
+    const detail = this.safeJsonParse(data)
+    const connectionId = detail && detail.connectionId
+    if (!connectionId) return
+
+    this.connectionId = connectionId
+    this.setAttribute("connection-id", connectionId)
+    this.dispatchEvent(new CustomEvent("pgbus:connected", {
+      detail: { connectionId }
+    }))
+  }
+
+  // Clears the cached connection id and its reflected attribute. Called at
+  // the start of every transport open so a reconnect doesn't carry the
+  // previous connection's id into pgbus:open before the new pgbus:connected
+  // frame arrives.
+  resetConnectionId() {
+    this.connectionId = null
+    this.removeAttribute("connection-id")
+  }
+
+  // Delivers a turbo-stream frame to two audiences (issue #168):
+  //
+  //   1. Turbo's StreamObserver, via a `message` MessageEvent whose `data`
+  //      is the turbo-stream HTML. The MessageEvent's standard
+  //      `lastEventId` field carries the frame's msg_id, so a reactive
+  //      runtime that listens for `message` can read the revision without
+  //      any pgbus-specific API. (Turbo ignores lastEventId.)
+  //
+  //   2. A reactive runtime doing optimistic-UI reconciliation, via a
+  //      `pgbus:message` CustomEvent carrying { msgId, data }. msgId is the
+  //      monotonic per-stream revision (a negative value marks an ephemeral
+  //      frame that was never persisted). Pattern: track the highest msgId
+  //      you have applied per target; when a frame arrives, skip the morph
+  //      if you have already applied a newer revision for that target —
+  //      this stops a late echo from clobbering a newer optimistic edit.
+  //      Complements #165: exclude handles the actor; this handles
+  //      out-of-order delivery for everyone else.
+  //
+  // msgId is parsed to a Number when numeric so consumers can compare
+  // revisions with `>` directly; left as-is otherwise.
+  emitTurboStream(data, id) {
+    const msgId = id === null || id === undefined || id === "" ? null
+      : (Number.isNaN(Number(id)) ? id : Number(id))
+
+    const message = new MessageEvent("message", { data, lastEventId: id == null ? "" : String(id) })
+    this.dispatchEvent(message)
+
+    this.dispatchEvent(new CustomEvent("pgbus:message", {
+      detail: { msgId, data }
+    }))
+  }
+
+  // Delivers a typed broadcast (issue #170) — a frame whose SSE event name
+  // is something other than turbo-stream (e.g. "presence", "reactive").
+  // The payload is still whatever the broadcaster sent (usually a Turbo
+  // Stream); the typed name lets a client route without sniffing the HTML.
+  // Dispatched two ways for ergonomics:
+  //   - a generic `pgbus:event` { event, data, msgId } (one listener for all)
+  //   - a named `pgbus:<event>`  { data, msgId }      (addEventListener by name)
+  emitTypedEvent(event, data, id) {
+    const msgId = id === null || id === undefined || id === "" ? null
+      : (Number.isNaN(Number(id)) ? id : Number(id))
+
+    this.dispatchEvent(new CustomEvent("pgbus:event", {
+      detail: { event, data, msgId }
+    }))
+    this.dispatchEvent(new CustomEvent(`pgbus:${event}`, {
+      detail: { data, msgId }
+    }))
+  }
+
+  // Typed event names the EventSource (reconnect) path should listen for,
+  // declared by the app via the `listen-events` attribute (comma- or
+  // space-separated). EventSource only invokes listeners registered by
+  // name, so unlike the fetch path it cannot route unknown typed events
+  // generically; declaring them here keeps typed delivery working across
+  // reconnects. The fetch (initial) path always routes typed events.
+  declaredTypedEvents() {
+    const raw = this.getAttribute("listen-events")
+    if (!raw) return []
+    return raw.split(/[\s,]+/).filter((name) => name && name !== "turbo-stream")
+  }
+
   buildUrl({ includeSince }) {
     const src = this.getAttribute("src")
     if (!includeSince || !this.lastEventId) return src

data/app/views/pgbus/batches/_batches_table.html.erb

@@ -16,7 +16,8 @@
           <tr class="hover:bg-gray-50 dark:hover:bg-gray-700/50">
             <td data-label="Batch ID" class="px-4 py-3 text-sm">
               <%= link_to batch[:batch_id][0..7], pgbus.batch_path(batch[:batch_id]),
-                    class: "font-mono text-indigo-600 dark:text-indigo-400 hover:underline" %>
+                    class: "font-mono text-indigo-600 dark:text-indigo-400 hover:underline",
+                    data: { turbo_frame: "_top" } %>
             </td>
             <td data-label="Description" class="px-4 py-3 text-sm text-gray-700 dark:text-gray-300 max-w-xs truncate">
               <%= batch[:description] || "—" %>

data/lib/pgbus/configuration.rb

@@ -113,6 +113,7 @@ module Pgbus
                   :streams_stats_enabled, :streams_test_mode,
                   :streams_orphan_sweep_interval, :streams_orphan_threshold,
                   :streams_durable_patterns,
+                  :streams_presence_patterns, :streams_presence_member,
                   :streams_host, :streams_port, :streams_database_url
     attr_reader :streams_default_broadcast_mode # rubocop:disable Style/AccessorGrouping
 
@@ -247,6 +248,15 @@ module Pgbus
       @streams_orphan_sweep_interval = 3600    # 1 hour
       @streams_orphan_threshold = 86_400       # 24 hours
       @streams_durable_patterns = []
+      # Streams matching these patterns get connection-driven presence:
+      # auto-join on SSE connect, auto-leave on disconnect, touch on the
+      # keepalive heartbeat (issue #169). Empty by default (opt-in).
+      @streams_presence_patterns = []
+      # Extracts a presence member { id:, metadata: } from a connection's
+      # authorize-hook context. Defaults to nil, which uses the built-in
+      # extractor (see #presence_member_for): a Hash with :member_id/:id,
+      # or an object responding to #id.
+      @streams_presence_member = nil
 
       # AppSignal: auto-on when the appsignal gem is loaded; probe runs in
       # the same process, so the operator can disable it independently.
@@ -411,6 +421,12 @@ module Pgbus
 
       raise ArgumentError, "streams_durable_patterns must be an Array of strings/regex" unless streams_durable_patterns.is_a?(Array)
 
+      raise ArgumentError, "streams_presence_patterns must be an Array of strings/regex" unless streams_presence_patterns.is_a?(Array)
+
+      if !streams_presence_member.nil? && !streams_presence_member.respond_to?(:call)
+        raise ArgumentError, "streams_presence_member must respond to #call (a Proc/lambda) or be nil"
+      end
+
       return if streams_orphan_threshold.nil?
       return if streams_orphan_threshold.is_a?(Numeric) && streams_orphan_threshold.positive?
 
@@ -427,6 +443,35 @@ module Pgbus
       streams_default_broadcast_mode == :durable
     end
 
+    # Returns true if the given stream name should have connection-driven
+    # presence based on `streams_presence_patterns` (exact string or
+    # Regexp match). Presence is opt-in, so the default (no patterns) is
+    # false. See issue #169.
+    def stream_presence?(name)
+      patterns = streams_presence_patterns || []
+      patterns.any? { |p| p.is_a?(Regexp) ? p.match?(name) : p == name }
+    end
+
+    # Derives a presence member { id:, metadata: } from a connection's
+    # authorize-hook context, or nil when no member can be derived (an
+    # anonymous connection — presence is simply skipped). Uses
+    # `streams_presence_member` when configured; otherwise the built-in
+    # extractor handles the common shapes:
+    #   - Hash with :member_id (or :id) and optional :metadata
+    #   - an object responding to #id (e.g. a User model)
+    # The id is always coerced to a String and metadata defaults to {}.
+    def presence_member_for(context)
+      return nil if context.nil?
+
+      raw = streams_presence_member ? streams_presence_member.call(context) : default_presence_member(context)
+      return nil unless raw.is_a?(Hash)
+
+      id = raw[:id]
+      return nil if id.nil? || id.to_s.empty?
+
+      { id: id.to_s, metadata: raw[:metadata] || {} }
+    end
+
     # Set the worker capsule list. Accepts:
     #
     #   String — parsed via Pgbus::Configuration::CapsuleDSL into capsules
@@ -689,6 +734,20 @@ module Pgbus
 
     private
 
+    # Built-in presence-member extractor used when no custom
+    # `streams_presence_member` is configured. Returns a { id:, metadata: }
+    # Hash or nil; #presence_member_for normalizes the id/metadata.
+    def default_presence_member(context)
+      if context.is_a?(Hash)
+        id = context[:member_id] || context[:id]
+        return nil if id.nil?
+
+        { id: id, metadata: context[:metadata] || {} }
+      elsif context.respond_to?(:id)
+        { id: context.id, metadata: {} }
+      end
+    end
+
     # Coerce a duration setting value to a positive Numeric.
     #
     # Accepts an ActiveSupport::Duration (coerced to Integer seconds via .to_i)

data/lib/pgbus/execution_pools/async_pool.rb

@@ -5,8 +5,6 @@ module Pgbus
     class AsyncPool
       attr_reader :capacity
 
-      IDLE_WAIT_INTERVAL = 0.01
-
       def initialize(capacity:, on_state_change: nil)
         @capacity = capacity
         @on_state_change = on_state_change
@@ -17,6 +15,7 @@ module Pgbus
         @fatal_error = nil
         @boot_queue = Thread::Queue.new
         @pending = Thread::Queue.new
+        @wake_rd, @wake_wr = IO.pipe
 
         validate_dependencies!
         @reactor_thread = start_reactor
@@ -32,6 +31,7 @@ module Pgbus
         reserve_capacity!
         reserved = true
         @pending << block
+        wake_reactor
       rescue StandardError
         restore_capacity if reserved
         raise
@@ -52,6 +52,7 @@ module Pgbus
 
           @shutdown_flag = true
         end
+        wake_reactor
       end
 
       def shutdown?
@@ -96,7 +97,18 @@ module Pgbus
             @boot_queue << :ready
 
             wait_for_executions(semaphore)
-            wait_for_inflight
+            wait_for_inflight(task)
+          ensure
+            begin
+              @wake_rd.close
+            rescue IOError
+              nil
+            end
+            begin
+              @wake_wr.close
+            rescue IOError
+              nil
+            end
           end
         rescue Exception => e
           register_fatal_error(e)
@@ -110,10 +122,35 @@ module Pgbus
           schedule_pending(semaphore)
           break if shutdown? && @pending.empty?
 
-          sleep(IDLE_WAIT_INTERVAL) if @pending.empty?
+          wait_for_wake if @pending.empty?
         end
       end
 
+      # Fiber-aware wait: yields the reactor fiber until the main thread
+      # writes a wake byte via wake_reactor. IO#wait_readable integrates
+      # with the Async scheduler so other fibers continue running.
+      def wait_for_wake
+        return if @wake_rd.closed?
+
+        @wake_rd.wait_readable
+        drain_wake_pipe
+      rescue IOError, Errno::EBADF
+        nil
+      end
+
+      def drain_wake_pipe
+        @wake_rd.read_nonblock(256)
+      rescue IOError, SystemCallError
+        nil
+      end
+
+      # Thread-safe: called from the main thread to wake the reactor fiber.
+      def wake_reactor
+        @wake_wr.write_nonblock(".")
+      rescue IO::WaitWritable, IOError, Errno::EBADF, Errno::EPIPE
+        nil
+      end
+
       def schedule_pending(semaphore)
         while (block = next_pending)
           semaphore.async do
@@ -160,6 +197,7 @@ module Pgbus
           @available_capacity += 1
           @available_capacity.positive?
         end
+        wake_reactor
         @on_state_change&.call if should_notify
       end
 
@@ -174,8 +212,8 @@ module Pgbus
         raise error if error
       end
 
-      def wait_for_inflight
-        sleep(IDLE_WAIT_INTERVAL) while inflight?
+      def wait_for_inflight(task)
+        task.sleep(0.01) while inflight?
       end
 
       def inflight?

data/lib/pgbus/streams/coalescer.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Pgbus
+  module Streams
+    # Publish-side coalescing for high-frequency broadcasts (issue #171).
+    #
+    # A chatty reactive component — a live cursor, a typing indicator, a
+    # progress bar — can fan out many small broadcasts per second. For
+    # per-keystroke / per-frame updates that's wasteful: every frame
+    # becomes a PGMQ insert (or a NOTIFY) and a fan-out to every connection.
+    #
+    # The Coalescer batches per (stream, target) within a short window and
+    # flushes only the *latest* payload, so superseded frames never hit the
+    # bus at all. This is last-write-wins and is only safe for idempotent
+    # actions (replace / update of a stable target) — which is exactly the
+    # high-frequency case. It is strictly opt-in (`coalesce:` on broadcast).
+    #
+    # Debounce semantics: the FIRST submit for a (stream, target) schedules
+    # a flush `window_ms` later; subsequent submits within that window only
+    # overwrite the buffered payload. So latency is bounded to one window
+    # and a continuous stream of updates can't starve the flush (it is a
+    # trailing-edge-with-max-wait debounce, not a resettable one).
+    #
+    # Thread-safe: many request threads may submit concurrently. The buffer
+    # and the per-key pending-flush set are guarded by a single mutex; the
+    # flush itself runs off the mutex on the scheduler's thread.
+    class Coalescer
+      # Default coalescing window when `coalesce: true` is passed without an
+      # explicit millisecond value.
+      DEFAULT_WINDOW_MS = 50
+
+      Entry = Struct.new(:payload, :opts)
+
+      # scheduler: responds to `schedule(delay_seconds) { ... }`. Defaults
+      #   to a Concurrent::ScheduledTask-backed scheduler.
+      # flush: ->(stream_name:, target:, payload:, opts:) called once per
+      #   window per key with the latest buffered frame.
+      def initialize(flush:, scheduler: nil)
+        @flush = flush
+        @scheduler = scheduler || ScheduledTaskScheduler.new
+        @mutex = Mutex.new
+        @buffer = {}  # key => Entry (latest)
+        @pending = {} # key => true while a flush is scheduled
+      end
+
+      # Buffers a frame for (stream_name, target). Overwrites any frame
+      # already buffered for the same key within the current window. The
+      # first submit per window schedules the flush.
+      def submit(stream_name:, target:, payload:, opts:, window_ms: DEFAULT_WINDOW_MS)
+        key = [stream_name, target]
+        schedule = false
+
+        @mutex.synchronize do
+          @buffer[key] = Entry.new(payload, opts)
+          unless @pending[key]
+            @pending[key] = true
+            schedule = true
+          end
+        end
+
+        @scheduler.schedule(window_ms / 1000.0) { flush_key(key, stream_name, target) } if schedule
+      end
+
+      private
+
+      def flush_key(key, stream_name, target)
+        entry = @mutex.synchronize do
+          @pending.delete(key)
+          @buffer.delete(key)
+        end
+        return unless entry
+
+        @flush.call(stream_name: stream_name, target: target, payload: entry.payload, opts: entry.opts)
+      end
+
+      # Default scheduler backed by Concurrent::ScheduledTask. Kept as a
+      # tiny adapter so the Coalescer can be unit-tested with a synchronous
+      # fake scheduler (no real timers, no sleeps).
+      class ScheduledTaskScheduler
+        def schedule(delay_seconds, &)
+          Concurrent::ScheduledTask.execute(delay_seconds, &)
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/streams/envelope.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 module Pgbus
   module Streams
     # Encodes Server-Sent Events frames per https://html.spec.whatwg.org/multipage/server-sent-events.html.
@@ -29,13 +31,30 @@ module Pgbus
         raise ArgumentError, "id is required" if id.nil?
         raise ArgumentError, "event is required" if event.nil? || event.to_s.empty?
 
-        "id: #{id}\nevent: #{event}\ndata: #{strip_newlines(data.to_s)}\n\n"
+        # Strip newlines from BOTH event and data, not just data: each is
+        # interpolated into its own SSE field line, so an unescaped \r/\n in
+        # either would terminate the field early and let a crafted value
+        # inject extra SSE fields (a forged id:/data:) into the frame.
+        "id: #{id}\nevent: #{strip_newlines(event.to_s)}\ndata: #{strip_newlines(data.to_s)}\n\n"
       end
 
       def self.comment(text)
         ": #{strip_newlines(text.to_s)}\n\n"
       end
 
+      # Emits a `pgbus:connected` frame carrying the server-minted
+      # connection id as JSON. Sent once, right after the open handshake,
+      # so the page can read its own connection id and send it back as
+      # `X-Pgbus-Connection` on action requests (actor-echo suppression,
+      # issue #165). Deliberately omits an `id:` line: this is connection
+      # metadata, not a broadcast, and giving it a cursor id would corrupt
+      # the client's Last-Event-ID replay position on reconnect.
+      def self.connected(id:)
+        raise ArgumentError, "id is required" if id.nil? || id.to_s.empty?
+
+        "event: pgbus:connected\ndata: #{JSON.generate({ connectionId: id.to_s })}\n\n"
+      end
+
       def self.retry_directive(milliseconds)
         unless milliseconds.is_a?(Integer) && !milliseconds.negative?
           raise ArgumentError, "retry must be a non-negative integer (got #{milliseconds.inspect})"

data/lib/pgbus/streams/key.rb

@@ -63,9 +63,42 @@ module Pgbus
       # `to_stream_key`/`to_gid_param` implementation that forgot to
       # sanitize) raise an ArgumentError at the call site.
       def stream_key(*parts, digest_bits: DEFAULT_DIGEST_BITS)
-        fragments = Array(parts).flatten.map { |part| normalize(part, digest_bits: digest_bits) }
+        flattened = Array(parts).flatten
+
+        # Idempotency for an already-built key: a single String argument
+        # is treated as a pre-built pgbus stream key and returned
+        # unchanged (after the budget check). This lets a consumer hold
+        # one `stream_key` value and pass it to both `turbo_stream_from`
+        # and the broadcaster without the colon separator guard raising
+        # on the second call. The guard only protects against ambiguous
+        # *joins* (`stream_key('a:b', :c)` vs `stream_key('a', 'b:c')`),
+        # and there is no second fragment here to collapse against, so the
+        # hazard cannot arise. Symbols and records are NOT keys — a colon
+        # in those never came from `stream_key` and stays a mistake.
+        return stream_key!(flattened.first) if flattened.length == 1 && flattened.first.is_a?(String)
+
+        fragments = flattened.map { |part| normalize(part, digest_bits: digest_bits) }
         fragments.each { |fragment| reject_colons!(fragment) }
-        key = fragments.join(":")
+        validate_budget!(fragments.join(":"))
+      end
+
+      # Accepts an already-built stream key verbatim, skipping the
+      # per-fragment colon guard (a pre-built key legitimately contains
+      # ':' separators). Still enforces the queue-name budget so an
+      # oversized key fails at the call site rather than deep inside
+      # Client#ensure_stream_queue. Use this when you hold a key string
+      # and want to be explicit that no re-keying should happen — e.g.
+      # passing the same value to `turbo_stream_from` and a broadcaster.
+      def stream_key!(key)
+        raise ArgumentError, "stream_key! key must be a String, got #{key.class}" unless key.is_a?(String)
+
+        validate_budget!(key)
+      end
+
+      # Returns the key when it fits the pgbus queue-name budget; raises
+      # ArgumentError with an actionable message otherwise. Shared by
+      # `stream_key` and `stream_key!` so both paths fail identically.
+      def validate_budget!(key)
         budget = queue_name_budget
         return key if key.length <= budget