pgbus 0.9.0 → 0.9.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93b9de67b282c7c707b2dcd4222ddde62d758447cc4769f72046dcf5b017dd92
-  data.tar.gz: 1a30a5e46ec20f02fa1cca3d56435c4e2c7f426a3933c523351503f0b69bff64
+  metadata.gz: 562d32e977685559437bdb1d3817fd02feb4fd9485b9101241a64d25d37162b1
+  data.tar.gz: eeacf0de199bfdc49c5b68523c5bbae7b1eff7970637742f3ec3e4391e4a3b06
 SHA512:
-  metadata.gz: 8912988721d6dfcf064693b9a84a6d1925a3535535b4b584abbdb2d311f80a5c1d7f6503c72da2825cbdfaf8daedb9c9e04b53353d3cc81279945b616a47a204
-  data.tar.gz: '0668b1229a24e47bcdc7fbb3d5f5fcfe95417329be2cdf14eb039cd9e258c22cefcaa4dbb3f2d17a84d5f0aa2c8a6def94971f9a51913ae028f395ac7758168c'
+  metadata.gz: a06cdb8eeecef32d6fa024f1fadac4f8c22758a11c91b1e9f5b00266869ea92b068c58a239a543c9409375d7155a59a5ec05f17cad59d7a23a49c90ecf74d7cd
+  data.tar.gz: e2a941feb09d3462bb9a83cda9b48821cf93649b53e9e7305af4a3b43b95bccca7690f40ebcb42857c4b9118ebeb592bcfacc317302e3a71b39be1c4f78493aa

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,9 +113,18 @@ 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
 
+    # NOTIFY-gated worker wakeups. When true, each Worker fork owns a
+    # dedicated NotifyListener PG connection that LISTENs on its queues'
+    # INSERT channels and wakes the loop on a real insert. Defaults to the
+    # value of listen_notify. The worker_notify_* overrides mirror
+    # streams_* so the LISTEN connection can bypass PgBouncer.
+    attr_accessor :worker_notify_wakeup,
+                  :worker_notify_host, :worker_notify_port, :worker_notify_database_url
+
     # AppSignal integration (auto-loaded when ::Appsignal is defined and this is true).
     # Set to false to opt out without uninstalling the appsignal gem.
     attr_accessor :appsignal_enabled, :appsignal_probe_enabled
@@ -170,6 +179,11 @@ module Pgbus
 
       @listen_notify = true
 
+      @worker_notify_wakeup = nil
+      @worker_notify_host = nil
+      @worker_notify_port = nil
+      @worker_notify_database_url = nil
+
       @pgmq_schema_mode = :auto
 
       @event_consumers = nil
@@ -247,6 +261,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 +434,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 +456,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
@@ -687,8 +745,57 @@ module Pgbus
       end
     end
 
+    # Connection options for the Worker's dedicated NotifyListener connection.
+    # Mirrors streams_connection_options: defaults to the base connection_options,
+    # overridable via worker_notify_database_url / worker_notify_host /
+    # worker_notify_port so the LISTEN connection can bypass PgBouncer.
+    def worker_notify_connection_options
+      return worker_notify_database_url if worker_notify_database_url
+
+      base = connection_options
+      return base unless worker_notify_host || worker_notify_port
+
+      case base
+      when Hash
+        result = base.dup
+        result[:host] = worker_notify_host if worker_notify_host
+        result[:port] = worker_notify_port if worker_notify_port
+        result
+      when String
+        parts = [base]
+        parts << "host=#{worker_notify_host}" if worker_notify_host
+        parts << "port=#{worker_notify_port}" if worker_notify_port
+        parts.join(" ")
+      else
+        base
+      end
+    end
+
+    # Resolved notify wakeup flag: defaults to listen_notify when nil.
+    def worker_notify_wakeup?
+      if @worker_notify_wakeup.nil?
+        listen_notify
+      else
+        @worker_notify_wakeup
+      end
+    end
+
     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?