pgbus 0.17.3 → 0.18.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54e3acb0aefac1a5a7e6a4dfabc972dc9fa830c8d738fbc029bfc667cf4635b2
-  data.tar.gz: 37b30a6e3f8625d938f499457c4cae88c6bc759d5017274bd425f1f9f59151e9
+  metadata.gz: e64af488e23381da4f7685e20a194addef033c1fb175fa64b1de7b169dc67996
+  data.tar.gz: b98a831339953b46a44e0a37468277d05b8718c3ac3fa7d7ee82d8857f78928f
 SHA512:
-  metadata.gz: 288d8ee976c4cf222f19fc3d3eab68523e1317bedbc94b49ddf1d6bde3fc22e05308e54fc0d4a0980ea9e7dc295452f224edf6088622b9acbc4d3f39dd595d45
-  data.tar.gz: 98b95204d3e73817c5b432ef85128ee1de8040aad5dacb1bba424e76fe88436028ed7259ae70f2636a9ddec6d18f2df615217497c9b887537dafde0a2ceebfc3
+  metadata.gz: f1a4d7d62a2c9a7a2767896246e20ec36ba3b5626ef0d45bb4b2cdc7efb50b14b99e57a848167db58a8d49e35ae5b7b8a367959a66044aa350b8eda7716afa05
+  data.tar.gz: f39f4dc967ea079dab0b1d7536bbc6effb9bd044f310a40e0fc1e4a988c03f1b104da4ab12f5c2eed515d67e805f6abc2e2d0944afdf8d77c4025436080b3a83

data/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ### Added
 
+- **`config.streams_authorize`: the engine's stream endpoint can supply a connection context.** The engine mounts `Pgbus::Web::StreamApp.new` with no `authorize:` hook, so every connection was authorized with no context. Connection-driven presence (`streams_presence_patterns`) then joined nobody, and `visible_to:` predicates that need a context (they receive `nil`, so `user&.admin?` is falsy) hid every broadcast, unless the app mounted its own `StreamApp`. `config.streams_authorize = ->(env, stream_name) { … }` takes the same contract as `StreamApp.new(authorize:)`: a falsy return answers 403, `true` authorizes with no context, any other value (the current user, say) becomes the connection context. It is read per request, so the order of initializers and route loading doesn't matter. An explicit `StreamApp.new(authorize:)` wins; any `StreamApp` without one, the engine's included, uses the configured hook, and nil (the default) keeps today's behaviour. `validate!` rejects a non-callable. Closes #522.
+
 - **Streams presence keeps one row per tab, with per-tab state, a change hook and automatic expiry (experimental).** Connection-driven presence (`streams_presence_patterns`) kept one row per member, so a user with two tabs open vanished from the room when either tab closed. On a migrated table it now keeps one row per SSE connection: `pgbus_presence_members` gains `connection_id`, `seat` (the client's per-tab id) and `state jsonb`. `<pgbus-stream-source presence>` (`pgbus_stream_from @room, presence: true`) mints one seat per document and sends it as `?seat=`; the stream app stores it on the connection and the dispatcher joins with `connection_id:` and `seat:`. New API: `Presence#join(member_id:, connection_id:, seat:, metadata:)`, `#leave(connection_id:)`, `#touch(connection_id:)` (one statement per stream, returning the ids it found), `#set_state(connection_id:, state:)` (merges into that row) and `.seats_supported?`; `#members` rows carry `connection_id`, `seat` and `state`. Member-keyed calls keep working on their own row. New settings: `streams_presence_on_change = ->(stream_name, change) { }`, called after each seat join, leave and expiry with `{ type:, connection_id:, seat:, member_id: }` (errors logged and swallowed), and `streams_presence_ttl` (seconds, or a pattern => seconds Hash with `:default`; 60 by default). The heartbeat touches live seats each tick, re-joins a live connection whose row was expired, and at most every ttl / 2 expires silent seats across all streams, including rows of crashed processes, reporting each as a `:leave`. On a seat table `sweep!` only expires member-keyed rows, and pgbus warns at boot when a ttl does not exceed `streams_heartbeat_interval`. **Upgrade:** `rails generate pgbus:add_presence_seats` (queued by `pgbus:update`; fresh `pgbus:add_presence` tables already have the columns). It replaces the `(stream_name, member_id)` unique index with partial unique indexes on `(stream_name, member_id) WHERE connection_id IS NULL` and `(stream_name, connection_id) WHERE connection_id IS NOT NULL`, and is reversible. Until it runs, presence behaves as before; a running process notices the migrated table within 30 seconds (at once on a member-keyed `join` outside a transaction). Closes #515.
 
 - **The home page and Insights explain themselves.** The home page (`/pgbus`) showed numbers without words ("Failed / DLQ 5 / 3", a Throughput card that was always `0.0` on the web, Queue Health percentages coloured against thresholds it never stated). It now opens with a health verdict strip — the OK / DEGRADED / STALLED verdict and reasons `/readyz` and the MCP compute (`HealthAnalyzer`), with links to the page that explains them. Eight cards each say what their number means and link to the page that explains it: Queues (paused, dead-letter, holding jobs nothing drains), Enqueued (claimable now vs scheduled, running or retrying), Processes (healthy · stalled · stale), Recurring, Retrying (the Jobs page's Retrying count, when the next attempt runs, how many are due now, the newest error), Dead-lettered (the newest message's reason, read as the DLQ page reads it), Throughput (jobs/min over the last 5 minutes from job stats, or "needs job stats") and Parked. The queues table gains a Status column in words (the queue page's summary line: paused and why, nothing drains it, what is waiting). Queue Health states each threshold ("12% on pgmq.q_pgbus_events — vacuum due (warns above 10%, critical above 20%)"; the MVCC card names both its own 30 s / 60 s warnings and the verdict's 300 s) and its table always renders, with an empty state. Recent failures show the job and attempt and link to the failure. New `Web::DataSource#dashboard_signals` and `#queue_status_lines` (in `DataSource::DashboardSignals`) and the pure presenters `Web::HealthVerdict` and `Web::InsightsCharts`; `summary_stats`, `/pgbus/api/stats`, `/pgbus/api/metrics` and the AppSignal probe are unchanged. On Insights each chart has a caption sentence (also the chart's accessible name) and a `<details>` data table rendered on the server (at most 60 rows: long ranges roll minutes up), empty series show an empty state, and the page draws from series it embeds instead of fetching `/pgbus/api/insights` a second time (that endpoint is unchanged). Closes #492.
@@ -54,6 +56,12 @@
 
 ### Fixed
 
+- **A draining worker no longer strands its read-ahead claims.** The worker loop checked `can_process?` once to decide whether to return buffered claims, then read the lifecycle again to decide whether to exit. A drain (`graceful_shutdown`) or stop (`immediate_shutdown`) from another thread that landed between the two reads let the loop exit with the buffer still full (a pause does not exit the loop, so its claims go back on the next step), so those messages stayed invisible until their visibility timeout instead of going straight back to the queue (`vt: 0`). The worker now returns whatever is still buffered after the loop, however it exits. This was the intermittent `worker_read_ahead_spec.rb:217` failure (about 1 run in 20). Refs #486.
+
+- **`pgbus:connected` now fires only once the connection is registered and its presence join has run.** `StreamApp` wrote the frame at hijack time, before the streamer's dispatcher had handled the connect, so a page that acted on its connection id as soon as it heard the event — `Pgbus.stream(x).presence.set_state(connection_id:)` from an action, for instance — found no row (`set_state` returned nil) and had to retry. The dispatcher now writes the frame at the end of the connect, after the archive replay, `registry.register` and the presence join attempt (a stream without presence, or a member resolver that returns nil, has no seat to join; a join that raises is logged and the frame still follows), through the connection's mutex-serialised writer (`Connection#write_connected` / `FalconConnection#write_connected`). The event name, its `connectionId` payload and the element's `connection-id` attribute are unchanged; listeners hear it after any replayed frames instead of before them, and a connection that dies during the replay never gets one. A repeated disconnect for an already-unregistered connection no longer records a second `disconnect` stream stat. Closes #521.
+
+- **A closed tab leaves its presence seat at once, not on the next heartbeat.** The server never reads a hijacked SSE socket after the request, so a client that went away was noticed only when a heartbeat write failed: up to `streams_heartbeat_interval` later (15 s by default), and often a beat later still, because the first write after the client's FIN succeeds. Every viewer of a presence roster kept the closed tab for that long. A new `PeerCloseWatcher` thread per streamer waits on every live hijacked socket with `IO.select` and probes a readable one with a non-blocking read: EOF or a reset marks the connection dead, closes it and posts the same `DisconnectMessage` the heartbeat posts, so the seat leaves (and `streams_presence_on_change` fires once) within milliseconds on Puma and on Falcon's default hijack path; a connection closed within its first `streams_peer_close_interval` after opening is noticed within that interval. A TLS client that vanishes without close_notify (OpenSSL's or Puma MiniSSL's SSL error on read) counts as closed, the probe skips a socket while a write holds its mutex, and `#stop` wakes the select through a self-pipe so shutdown does not wait out the interval. The client sends nothing after its request, so a readable socket means a close; stray bytes are read and discarded. Falcon's experimental streaming-body path has no socket and keeps the heartbeat. New setting `streams_peer_close_interval` (1.0 s by default): how long a newly opened connection waits to join the watched set; `nil` turns the watcher off. Closes #519.
+
 - **Insights charts are readable in dark mode.** The charts were themed only through `foreColor`: in dark mode the donut kept white slice separators, axis borders and the crosshair label stayed light, and the "No data" fallback was `text-gray-400 dark:text-gray-500` (below WCAG AA, and invisible to the contrast guard because it lived in JS). `charts.js` now themes every chart from one `palette(isDark)` (theme mode, axis and grid colours, donut separators in the card colour, legend and tooltip, animations off under `prefers-reduced-motion`) and redraws on the dark-mode toggle without a reload. The latency headers and chart titles no longer carry "(ms)" / "(jobs/min)"; the P95 latency card's yellow is now AA. The static contrast guard scans the dashboard's JS modules too. Refs #492.
 
 - **The dashboard home page reads the process rows and the stream registry once per render.** `DataSource` memoizes the raw process rows, `stream_queue_names` and `queue_health_stats` per instance (cleared by `reset_cache!`, as `queues_with_metrics` already was), so the stats, the verdict and the panels share one query each. `HealthApp` now calls `reset_cache!` on an injected DataSource before every `/readyz` check, so a long-lived one never answers with the first check's facts (it already did that for queues). Refs #492.

data/README.md

@@ -1443,6 +1443,7 @@ Pgbus.configure do |c|
     "presence_room" => 30                          # 30 seconds for presence
   }
   c.streams_heartbeat_interval     = 15            # seconds
+  c.streams_peer_close_interval    = 1.0           # notice a closed client at once; nil = heartbeat only
   c.streams_max_connections        = 2_000         # per web-server process (Puma worker or Falcon process)
   c.streams_idle_timeout           = 3_600         # close idle connections after 1h
   c.streams_listen_health_check_ms = 250           # PG LISTEN keepalive + ensure_listening ack budget
@@ -1617,16 +1618,26 @@ Pgbus::Streams.filters.register(:workspace_member) do |user, stream_name|
 end
 ```
 
-The authorize hook on `Pgbus::Web::StreamApp` doubles as a context provider — return any non-boolean value (typically a `User` model) and pgbus will pass it to the filter predicate when evaluating broadcasts:
+The authorize hook doubles as a context provider — return any non-boolean value (typically a `User` model) and pgbus will pass it to the filter predicate when evaluating broadcasts. The engine's stream endpoint reads it from `config.streams_authorize`, so no custom mount is needed:
 
 ```ruby
-Pgbus::Web::StreamApp.new(authorize: ->(env, _stream_name) {
-  user = User.find_by(id: env["rack.session"][:user_id])
-  return false unless user
-  user  # ← context attached to the connection
-})
+Pgbus.configure do |c|
+  c.streams_authorize = ->(env, stream_name) {
+    user = User.find_by(id: env["rack.session"]&.dig("user_id"))
+    next unless user
+
+    # Check THIS user against THIS stream: here "room:42" names a room.
+    room_id = stream_name.delete_prefix("room:") if stream_name.start_with?("room:")
+    room = Room.find_by(id: room_id) if room_id
+    user if room&.member?(user)  # nil → 403; the user becomes the context
+  }
+end
 ```
 
+Authorize per stream here. The signed stream name proves pgbus minted it, not that this user may read it: a user removed from a room keeps a working signed name until the signing key rotates (`Turbo.signed_stream_verifier_key` when turbo-rails is loaded, `streams_signed_name_secret` otherwise), so a hook that only checks "logged in" lets them keep listening. Rotating the key only refuses new connections: an SSE connection already open stays open until it closes or its worker restarts.
+
+The hook gets the Rack env, not a controller (the stream endpoint is a bare Rack app), so read the session (`env["rack.session"]`) or a signed cookie from it. A falsy return answers 403, `true` authorizes with no context. An explicit `Pgbus::Web::StreamApp.new(authorize: …)` wins; every `StreamApp` built without one, the engine's mount included, uses `streams_authorize`. `validate!` rejects a non-callable value at boot; with `eager_validation = false` it is not checked there, and every stream request then fails closed with a 500.
+
 Then label broadcasts with the filter you want to apply:
 
 ```ruby
@@ -1650,7 +1661,7 @@ An actor who just triggered a change already applied it via the HTTP response of
 Pgbus.stream(room).broadcast(html, exclude: connection_id)
 ```
 
-Every server-minted SSE connection exposes its id to the page: right after the open handshake, pgbus sends a `pgbus:connected` frame carrying the connection id, and `<pgbus-stream-source>` captures it onto its `connection-id` attribute and re-dispatches it as a `pgbus:connected` event (also present in `pgbus:open`'s detail). The page reads that id and sends it back as the `X-Pgbus-Connection` header on the action request that triggers the broadcast:
+Every server-minted SSE connection exposes its id to the page: once the streamer has registered the connection (after the connect replay, and after its presence seat has joined on a presence stream), pgbus sends a `pgbus:connected` frame carrying the connection id, and `<pgbus-stream-source>` captures it onto its `connection-id` attribute and re-dispatches it as a `pgbus:connected` event. A write keyed by the connection id right after the event, such as `presence.set_state(connection_id:)`, finds the connection's row. The page reads that id and sends it back as the `X-Pgbus-Connection` header on the action request that triggers the broadcast:
 
 ```js
 document.addEventListener("pgbus:connected", (event) => {
@@ -1795,7 +1806,7 @@ Pgbus.configure do |c|
 end
 ```
 
-Identity comes from the connection's authorize-hook context (the value your `StreamApp` `authorize:` callable returns). The built-in extractor handles the common shapes without any configuration: a `Hash` with `:member_id` (or `:id`) and optional `:metadata`, or any object responding to `#id` (e.g. a `User` model). For anything else, provide a custom extractor — a `->(context) { { id:, metadata: } }` callable returning `nil` for a context with no derivable identity (anonymous connections are simply skipped, not an error):
+Identity comes from the connection's authorize-hook context (the value `config.streams_authorize`, or your own `StreamApp` `authorize:` callable, returns). Without a hook every connection is anonymous and nobody joins. The built-in extractor handles the common shapes without any configuration: a `Hash` with `:member_id` (or `:id`) and optional `:metadata`, or any object responding to `#id` (e.g. a `User` model). For anything else, provide a custom extractor — a `->(context) { { id:, metadata: } }` callable returning `nil` for a context with no derivable identity (anonymous connections are simply skipped, not an error):
 
 ```ruby
 Pgbus.configure do |c|
@@ -1806,7 +1817,7 @@ Pgbus.configure do |c|
 end
 ```
 
-Membership work runs on the dispatcher thread (which already releases AR connections each pass); the heartbeat posts a batched touch per tick. Presence failures are logged and swallowed so a presence-table hiccup can't knock a live SSE connection out of the registry.
+Membership work runs on the dispatcher thread (which already releases AR connections each pass); the heartbeat posts a batched touch per tick. A closed tab leaves at once (within `streams_peer_close_interval` for a connection that just opened): a watcher thread notices the client's close on the socket (Puma and Falcon's hijack path) instead of waiting for the next heartbeat write to fail. Falcon's experimental streaming-body path still leaves on the heartbeat. Presence failures are logged and swallowed so a presence-table hiccup can't knock a live SSE connection out of the registry.
 
 #### Seats: one row per tab (experimental)
 

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

@@ -37,8 +37,9 @@
 //   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
+// `pgbus:connected` frame carrying the server-minted connection id once the
+// streamer has registered the connection and joined its presence seat
+// (issue #521), after the connect replay. 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`

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

@@ -1 +1 @@
-{"version":3,"sources":["src/stream_source_element.js"],"sourcesContent":["// <pgbus-stream-source> — the browser-side counterpart to\n// Pgbus::StreamsHelper#pgbus_stream_from. Drop-in replacement for\n// turbo-rails' <turbo-cable-stream-source> that speaks SSE + pgbus\n// instead of WebSocket + ActionCable.\n//\n// Attributes (set by the view helper):\n//   src                 — absolute path to the SSE endpoint, including\n//                         the URL-safe signed stream name\n//   since-id            — PGMQ msg_id watermark at render time; the\n//                         client sends this as ?since= on the FIRST\n//                         connect so the server can replay any\n//                         broadcasts from the render-to-connect gap\n//                         (rails/rails#52420 fix)\n//   signed-stream-name  — present for parity with turbo-rails; unused\n//                         by this element because the signed name is\n//                         already in the URL path\n//   channel             — compatibility shim; ignored\n//   presence            — boolean; when present the element sends this\n//                         document's presence seat as ?seat= on every\n//                         connect (issue #515)\n//\n// Events (dispatched on the element):\n//   message            (MessageEvent) data = turbo-stream HTML;\n//                      lastEventId = the frame's msg_id (revision)\n//   pgbus:message      { msgId, data } — same frame, for optimistic-UI\n//                      reconciliation (skip morph if a newer rev for the\n//                      target was already applied). See #168.\n//   pgbus:event        { event, data, msgId } — a typed broadcast (any SSE\n//                      event name other than turbo-stream). See #170.\n//   pgbus:<event>      { data, msgId } — the same typed broadcast, named\n//                      for ergonomic addEventListener(\"pgbus:presence\").\n//   pgbus:open         { lastEventId, connectionId }\n//   pgbus:connected    { connectionId }\n//   pgbus:replay-start { fromId, toId }\n//   pgbus:replay-end   {}\n//   pgbus:gap-detected { lastSeenId, archiveOldestId }\n//   pgbus:close        { code, reason }\n//\n// Connection id (issue #165 — actor-echo suppression): the server sends a\n// `pgbus:connected` frame right after the open handshake carrying the\n// server-minted connection id. This element captures it, reflects it onto\n// the `connection-id` attribute, and re-dispatches it as `pgbus:connected`.\n// A page reads it (from the element or a `<meta name=\"pgbus-connection-id\">`\n// the app mirrors it to) and sends it back as the `X-Pgbus-Connection`\n// header on action requests. The broadcaster then passes\n// `exclude: request.headers[\"X-Pgbus-Connection\"]` so the actor does not\n// receive the echo of its own broadcast.\n//\n// The element integrates with Turbo via connectStreamSource /\n// disconnectStreamSource + dispatching MessageEvent(\"message\") so Turbo\n// Stream HTML is automatically consumed by the existing StreamObserver.\n//\n// Presence seat (issue #515): with the `presence` attribute, the element\n// appends `?seat=<id>` to the SSE request. The seat is minted once per\n// document (shared by every presence element on the page and kept across\n// Turbo Drive visits, so it names the browser tab) and stays the same across\n// reconnects. The server stores it on the connection's presence row, which\n// lets a page tell its own tab apart from the member's other tabs. Read it\n// from `element.pgbusSeat`.\n//\n// Transport strategy:\n//   - FIRST connect: use fetch() + ReadableStream to include ?since=\n//     in the URL. Native EventSource cannot send Last-Event-ID on the\n//     initial request, so we need fetch to carry the watermark.\n//   - RECONNECT: switch to native EventSource, which sends Last-Event-ID\n//     automatically based on the last id: we observed. The native\n//     client is more battle-tested for reconnection backoff.\n\nimport { Turbo } from \"@hotwired/turbo-rails\"\nconst { connectStreamSource, disconnectStreamSource } = Turbo\n\nlet documentSeat = null\n\n// One seat per document, minted on first use (see \"Presence seat\" above).\nfunction seatForDocument() {\n  if (!documentSeat) {\n    documentSeat = globalThis.crypto && crypto.randomUUID\n      ? crypto.randomUUID()\n      : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`\n  }\n  return documentSeat\n}\n\nclass PgbusStreamSourceElement extends HTMLElement {\n  static get observedAttributes() {\n    return [\"src\", \"since-id\"]\n  }\n\n  constructor() {\n    super()\n    this.abortController = null\n    this.eventSource = null\n    this.lastEventId = null\n    this.connectionId = null\n    this.closed = false\n  }\n\n  // The server-minted connection id for this SSE connection, or null\n  // until the `pgbus:connected` frame arrives. Public read accessor so\n  // a reactive runtime can grab it without poking at attributes.\n  get pgbusConnectionId() {\n    return this.connectionId\n  }\n\n  // This document's presence seat when the element has the `presence`\n  // attribute, otherwise null.\n  get pgbusSeat() {\n    return this.hasAttribute(\"presence\") ? seatForDocument() : null\n  }\n\n  connectedCallback() {\n    this.closed = false\n    connectStreamSource(this)\n    const sinceId = this.getAttribute(\"since-id\")\n    this.lastEventId = sinceId && sinceId !== \"\" ? sinceId : null\n    this.openFetchStream()\n  }\n\n  disconnectedCallback() {\n    this.closed = true\n    disconnectStreamSource(this)\n    this.teardown()\n  }\n\n  teardown() {\n    if (this.abortController) {\n      this.abortController.abort()\n      this.abortController = null\n    }\n    if (this.eventSource) {\n      this.eventSource.close()\n      this.eventSource = null\n    }\n  }\n\n  // First connect: use fetch() so we can include ?since=<watermark> on\n  // the URL. Parses the SSE event stream by hand because EventSource\n  // doesn't expose custom query strings uniformly across browsers.\n  async openFetchStream() {\n    // Each transport open is a fresh connection: the server mints a new id\n    // and sends a new pgbus:connected frame. Clear the previous id so\n    // pgbus:open (which fires before that frame arrives) can't surface a\n    // stale connection id — a stale id would produce a wrong X-Pgbus-Connection\n    // exclude header during reconnect windows.\n    this.resetConnectionId()\n    const url = this.buildUrl({ includeSince: true })\n    this.abortController = new AbortController()\n\n    try {\n      const response = await fetch(url, {\n        headers: { Accept: \"text/event-stream\" },\n        credentials: \"same-origin\",\n        signal: this.abortController.signal\n      })\n\n      if (!response.ok) {\n        this.dispatchEvent(new CustomEvent(\"pgbus:close\", {\n          detail: { code: response.status, reason: response.statusText }\n        }))\n        return\n      }\n\n      this.setAttribute(\"connected\", \"\")\n      this.dispatchEvent(new CustomEvent(\"pgbus:open\", {\n        detail: { lastEventId: this.lastEventId, connectionId: this.connectionId }\n      }))\n\n      const reader = response.body.getReader()\n      const decoder = new TextDecoder(\"utf-8\")\n      let buffer = \"\"\n\n      while (!this.closed) {\n        const { value, done } = await reader.read()\n        if (done) {\n          this.removeAttribute(\"connected\")\n          this.switchToEventSource()\n          return\n        }\n\n        buffer += decoder.decode(value, { stream: true })\n        const events = buffer.split(\"\\n\\n\")\n        buffer = events.pop() // last chunk may be incomplete\n\n        for (const block of events) {\n          this.handleBlock(block)\n        }\n      }\n    } catch (err) {\n      if (err.name !== \"AbortError\") {\n        this.removeAttribute(\"connected\")\n        // Fall through to reconnect via native EventSource, which\n        // will carry Last-Event-ID from this.lastEventId forward.\n        this.switchToEventSource()\n      }\n    }\n  }\n\n  // Reconnect path: native EventSource with Last-Event-ID baked into\n  // the initial handshake by the browser.\n  switchToEventSource() {\n    if (this.closed) return\n\n    // Fresh connection on reconnect — drop the previous connection id so\n    // pgbus:open can't emit a stale one before the new pgbus:connected\n    // frame lands. See openFetchStream.\n    this.resetConnectionId()\n    const url = this.buildUrl({ includeSince: true })\n    this.eventSource = new EventSource(url, { withCredentials: true })\n\n    this.eventSource.addEventListener(\"open\", () => {\n      this.setAttribute(\"connected\", \"\")\n      this.dispatchEvent(new CustomEvent(\"pgbus:open\", {\n        detail: { lastEventId: this.lastEventId, connectionId: this.connectionId }\n      }))\n    })\n\n    this.eventSource.addEventListener(\"error\", () => {\n      this.removeAttribute(\"connected\")\n    })\n\n    this.eventSource.addEventListener(\"turbo-stream\", (event) => {\n      this.lastEventId = event.lastEventId\n      this.emitTurboStream(event.data, event.lastEventId)\n    })\n\n    this.eventSource.addEventListener(\"pgbus:connected\", (event) => {\n      this.handleConnected(event.data)\n    })\n\n    this.eventSource.addEventListener(\"pgbus:gap-detected\", (event) => {\n      const detail = this.safeJsonParse(event.data)\n      this.dispatchEvent(new CustomEvent(\"pgbus:gap-detected\", { detail }))\n    })\n\n    this.eventSource.addEventListener(\"pgbus:shutdown\", () => {\n      this.dispatchEvent(new CustomEvent(\"pgbus:close\", {\n        detail: { code: \"shutdown\", reason: \"worker restart\" }\n      }))\n    })\n\n    // Typed broadcasts (issue #170): EventSource only fires listeners\n    // registered by name, so we register one per declared typed event.\n    for (const name of this.declaredTypedEvents()) {\n      this.eventSource.addEventListener(name, (event) => {\n        if (event.lastEventId) this.lastEventId = event.lastEventId\n        this.emitTypedEvent(name, event.data, event.lastEventId)\n      })\n    }\n  }\n\n  // Parses a single SSE event block (: comment | id: ... | event: ... | data: ...)\n  handleBlock(block) {\n    if (!block || block.startsWith(\":\")) return // comment\n\n    let id = null\n    let event = \"message\"\n    const dataLines = []\n\n    for (const line of block.split(\"\\n\")) {\n      if (line.startsWith(\"id:\")) id = line.slice(3).trim()\n      else if (line.startsWith(\"event:\")) event = line.slice(6).trim()\n      // Per the SSE spec: strip only a single leading space after the colon\n      // (never trim — payload whitespace is significant, issue #392) and\n      // rejoin consecutive data: lines with \\n, matching native EventSource.\n      else if (line.startsWith(\"data:\")) dataLines.push(line.slice(5).replace(/^ /, \"\"))\n    }\n    const data = dataLines.join(\"\\n\")\n\n    if (id !== null) this.lastEventId = id\n\n    if (event === \"turbo-stream\") {\n      this.emitTurboStream(data, id)\n    } else if (event === \"pgbus:connected\") {\n      this.handleConnected(data)\n    } else if (event === \"pgbus:gap-detected\") {\n      this.dispatchEvent(new CustomEvent(\"pgbus:gap-detected\", {\n        detail: this.safeJsonParse(data)\n      }))\n    } else if (event === \"pgbus:shutdown\") {\n      this.dispatchEvent(new CustomEvent(\"pgbus:close\", {\n        detail: { code: \"shutdown\", reason: \"worker restart\" }\n      }))\n    } else {\n      // A typed broadcast (issue #170): event: presence | reactive | ...\n      this.emitTypedEvent(event, data, id)\n    }\n  }\n\n  // Captures the server-minted connection id from a `pgbus:connected`\n  // frame: stores it, reflects it onto the `connection-id` attribute (so\n  // it's visible in the DOM / to MutationObservers), and re-dispatches it\n  // as a `pgbus:connected` CustomEvent. Idempotent across reconnects — the\n  // server mints a fresh id per connection, so a reconnect updates it.\n  handleConnected(data) {\n    const detail = this.safeJsonParse(data)\n    const connectionId = detail && detail.connectionId\n    if (!connectionId) return\n\n    this.connectionId = connectionId\n    this.setAttribute(\"connection-id\", connectionId)\n    this.dispatchEvent(new CustomEvent(\"pgbus:connected\", {\n      detail: { connectionId }\n    }))\n  }\n\n  // Clears the cached connection id and its reflected attribute. Called at\n  // the start of every transport open so a reconnect doesn't carry the\n  // previous connection's id into pgbus:open before the new pgbus:connected\n  // frame arrives.\n  resetConnectionId() {\n    this.connectionId = null\n    this.removeAttribute(\"connection-id\")\n  }\n\n  // Delivers a turbo-stream frame to two audiences (issue #168):\n  //\n  //   1. Turbo's StreamObserver, via a `message` MessageEvent whose `data`\n  //      is the turbo-stream HTML. The MessageEvent's standard\n  //      `lastEventId` field carries the frame's msg_id, so a reactive\n  //      runtime that listens for `message` can read the revision without\n  //      any pgbus-specific API. (Turbo ignores lastEventId.)\n  //\n  //   2. A reactive runtime doing optimistic-UI reconciliation, via a\n  //      `pgbus:message` CustomEvent carrying { msgId, data }. msgId is the\n  //      monotonic per-stream revision (a negative value marks an ephemeral\n  //      frame that was never persisted). Pattern: track the highest msgId\n  //      you have applied per target; when a frame arrives, skip the morph\n  //      if you have already applied a newer revision for that target —\n  //      this stops a late echo from clobbering a newer optimistic edit.\n  //      Complements #165: exclude handles the actor; this handles\n  //      out-of-order delivery for everyone else.\n  //\n  // msgId is parsed to a Number when numeric so consumers can compare\n  // revisions with `>` directly; left as-is otherwise.\n  emitTurboStream(data, id) {\n    const msgId = id === null || id === undefined || id === \"\" ? null\n      : (Number.isNaN(Number(id)) ? id : Number(id))\n\n    const message = new MessageEvent(\"message\", { data, lastEventId: id == null ? \"\" : String(id) })\n    this.dispatchEvent(message)\n\n    this.dispatchEvent(new CustomEvent(\"pgbus:message\", {\n      detail: { msgId, data }\n    }))\n  }\n\n  // Delivers a typed broadcast (issue #170) — a frame whose SSE event name\n  // is something other than turbo-stream (e.g. \"presence\", \"reactive\").\n  // The payload is still whatever the broadcaster sent (usually a Turbo\n  // Stream); the typed name lets a client route without sniffing the HTML.\n  // Dispatched two ways for ergonomics:\n  //   - a generic `pgbus:event` { event, data, msgId } (one listener for all)\n  //   - a named `pgbus:<event>`  { data, msgId }      (addEventListener by name)\n  emitTypedEvent(event, data, id) {\n    const msgId = id === null || id === undefined || id === \"\" ? null\n      : (Number.isNaN(Number(id)) ? id : Number(id))\n\n    this.dispatchEvent(new CustomEvent(\"pgbus:event\", {\n      detail: { event, data, msgId }\n    }))\n    this.dispatchEvent(new CustomEvent(`pgbus:${event}`, {\n      detail: { data, msgId }\n    }))\n  }\n\n  // Typed event names the EventSource (reconnect) path should listen for,\n  // declared by the app via the `listen-events` attribute (comma- or\n  // space-separated). EventSource only invokes listeners registered by\n  // name, so unlike the fetch path it cannot route unknown typed events\n  // generically; declaring them here keeps typed delivery working across\n  // reconnects. The fetch (initial) path always routes typed events.\n  declaredTypedEvents() {\n    const raw = this.getAttribute(\"listen-events\")\n    if (!raw) return []\n    return raw.split(/[\\s,]+/).filter((name) => name && name !== \"turbo-stream\")\n  }\n\n  buildUrl({ includeSince }) {\n    const src = this.getAttribute(\"src\")\n    const since = includeSince && this.lastEventId ? this.lastEventId : null\n    const seat = this.pgbusSeat\n    if (!since && !seat) return src\n\n    const url = new URL(src, window.location.origin)\n    if (since) url.searchParams.set(\"since\", since)\n    if (seat) url.searchParams.set(\"seat\", seat)\n    return url.toString()\n  }\n\n  safeJsonParse(str) {\n    try { return JSON.parse(str) } catch { return null }\n  }\n}\n\nif (!customElements.get(\"pgbus-stream-source\")) {\n  customElements.define(\"pgbus-stream-source\", PgbusStreamSourceElement)\n}\n\nexport { PgbusStreamSourceElement }\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["src/stream_source_element.js"],"sourcesContent":["// <pgbus-stream-source> — the browser-side counterpart to\n// Pgbus::StreamsHelper#pgbus_stream_from. Drop-in replacement for\n// turbo-rails' <turbo-cable-stream-source> that speaks SSE + pgbus\n// instead of WebSocket + ActionCable.\n//\n// Attributes (set by the view helper):\n//   src                 — absolute path to the SSE endpoint, including\n//                         the URL-safe signed stream name\n//   since-id            — PGMQ msg_id watermark at render time; the\n//                         client sends this as ?since= on the FIRST\n//                         connect so the server can replay any\n//                         broadcasts from the render-to-connect gap\n//                         (rails/rails#52420 fix)\n//   signed-stream-name  — present for parity with turbo-rails; unused\n//                         by this element because the signed name is\n//                         already in the URL path\n//   channel             — compatibility shim; ignored\n//   presence            — boolean; when present the element sends this\n//                         document's presence seat as ?seat= on every\n//                         connect (issue #515)\n//\n// Events (dispatched on the element):\n//   message            (MessageEvent) data = turbo-stream HTML;\n//                      lastEventId = the frame's msg_id (revision)\n//   pgbus:message      { msgId, data } — same frame, for optimistic-UI\n//                      reconciliation (skip morph if a newer rev for the\n//                      target was already applied). See #168.\n//   pgbus:event        { event, data, msgId } — a typed broadcast (any SSE\n//                      event name other than turbo-stream). See #170.\n//   pgbus:<event>      { data, msgId } — the same typed broadcast, named\n//                      for ergonomic addEventListener(\"pgbus:presence\").\n//   pgbus:open         { lastEventId, connectionId }\n//   pgbus:connected    { connectionId }\n//   pgbus:replay-start { fromId, toId }\n//   pgbus:replay-end   {}\n//   pgbus:gap-detected { lastSeenId, archiveOldestId }\n//   pgbus:close        { code, reason }\n//\n// Connection id (issue #165 — actor-echo suppression): the server sends a\n// `pgbus:connected` frame carrying the server-minted connection id once the\n// streamer has registered the connection and joined its presence seat\n// (issue #521), after the connect replay. This element captures it, reflects it onto\n// the `connection-id` attribute, and re-dispatches it as `pgbus:connected`.\n// A page reads it (from the element or a `<meta name=\"pgbus-connection-id\">`\n// the app mirrors it to) and sends it back as the `X-Pgbus-Connection`\n// header on action requests. The broadcaster then passes\n// `exclude: request.headers[\"X-Pgbus-Connection\"]` so the actor does not\n// receive the echo of its own broadcast.\n//\n// The element integrates with Turbo via connectStreamSource /\n// disconnectStreamSource + dispatching MessageEvent(\"message\") so Turbo\n// Stream HTML is automatically consumed by the existing StreamObserver.\n//\n// Presence seat (issue #515): with the `presence` attribute, the element\n// appends `?seat=<id>` to the SSE request. The seat is minted once per\n// document (shared by every presence element on the page and kept across\n// Turbo Drive visits, so it names the browser tab) and stays the same across\n// reconnects. The server stores it on the connection's presence row, which\n// lets a page tell its own tab apart from the member's other tabs. Read it\n// from `element.pgbusSeat`.\n//\n// Transport strategy:\n//   - FIRST connect: use fetch() + ReadableStream to include ?since=\n//     in the URL. Native EventSource cannot send Last-Event-ID on the\n//     initial request, so we need fetch to carry the watermark.\n//   - RECONNECT: switch to native EventSource, which sends Last-Event-ID\n//     automatically based on the last id: we observed. The native\n//     client is more battle-tested for reconnection backoff.\n\nimport { Turbo } from \"@hotwired/turbo-rails\"\nconst { connectStreamSource, disconnectStreamSource } = Turbo\n\nlet documentSeat = null\n\n// One seat per document, minted on first use (see \"Presence seat\" above).\nfunction seatForDocument() {\n  if (!documentSeat) {\n    documentSeat = globalThis.crypto && crypto.randomUUID\n      ? crypto.randomUUID()\n      : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`\n  }\n  return documentSeat\n}\n\nclass PgbusStreamSourceElement extends HTMLElement {\n  static get observedAttributes() {\n    return [\"src\", \"since-id\"]\n  }\n\n  constructor() {\n    super()\n    this.abortController = null\n    this.eventSource = null\n    this.lastEventId = null\n    this.connectionId = null\n    this.closed = false\n  }\n\n  // The server-minted connection id for this SSE connection, or null\n  // until the `pgbus:connected` frame arrives. Public read accessor so\n  // a reactive runtime can grab it without poking at attributes.\n  get pgbusConnectionId() {\n    return this.connectionId\n  }\n\n  // This document's presence seat when the element has the `presence`\n  // attribute, otherwise null.\n  get pgbusSeat() {\n    return this.hasAttribute(\"presence\") ? seatForDocument() : null\n  }\n\n  connectedCallback() {\n    this.closed = false\n    connectStreamSource(this)\n    const sinceId = this.getAttribute(\"since-id\")\n    this.lastEventId = sinceId && sinceId !== \"\" ? sinceId : null\n    this.openFetchStream()\n  }\n\n  disconnectedCallback() {\n    this.closed = true\n    disconnectStreamSource(this)\n    this.teardown()\n  }\n\n  teardown() {\n    if (this.abortController) {\n      this.abortController.abort()\n      this.abortController = null\n    }\n    if (this.eventSource) {\n      this.eventSource.close()\n      this.eventSource = null\n    }\n  }\n\n  // First connect: use fetch() so we can include ?since=<watermark> on\n  // the URL. Parses the SSE event stream by hand because EventSource\n  // doesn't expose custom query strings uniformly across browsers.\n  async openFetchStream() {\n    // Each transport open is a fresh connection: the server mints a new id\n    // and sends a new pgbus:connected frame. Clear the previous id so\n    // pgbus:open (which fires before that frame arrives) can't surface a\n    // stale connection id — a stale id would produce a wrong X-Pgbus-Connection\n    // exclude header during reconnect windows.\n    this.resetConnectionId()\n    const url = this.buildUrl({ includeSince: true })\n    this.abortController = new AbortController()\n\n    try {\n      const response = await fetch(url, {\n        headers: { Accept: \"text/event-stream\" },\n        credentials: \"same-origin\",\n        signal: this.abortController.signal\n      })\n\n      if (!response.ok) {\n        this.dispatchEvent(new CustomEvent(\"pgbus:close\", {\n          detail: { code: response.status, reason: response.statusText }\n        }))\n        return\n      }\n\n      this.setAttribute(\"connected\", \"\")\n      this.dispatchEvent(new CustomEvent(\"pgbus:open\", {\n        detail: { lastEventId: this.lastEventId, connectionId: this.connectionId }\n      }))\n\n      const reader = response.body.getReader()\n      const decoder = new TextDecoder(\"utf-8\")\n      let buffer = \"\"\n\n      while (!this.closed) {\n        const { value, done } = await reader.read()\n        if (done) {\n          this.removeAttribute(\"connected\")\n          this.switchToEventSource()\n          return\n        }\n\n        buffer += decoder.decode(value, { stream: true })\n        const events = buffer.split(\"\\n\\n\")\n        buffer = events.pop() // last chunk may be incomplete\n\n        for (const block of events) {\n          this.handleBlock(block)\n        }\n      }\n    } catch (err) {\n      if (err.name !== \"AbortError\") {\n        this.removeAttribute(\"connected\")\n        // Fall through to reconnect via native EventSource, which\n        // will carry Last-Event-ID from this.lastEventId forward.\n        this.switchToEventSource()\n      }\n    }\n  }\n\n  // Reconnect path: native EventSource with Last-Event-ID baked into\n  // the initial handshake by the browser.\n  switchToEventSource() {\n    if (this.closed) return\n\n    // Fresh connection on reconnect — drop the previous connection id so\n    // pgbus:open can't emit a stale one before the new pgbus:connected\n    // frame lands. See openFetchStream.\n    this.resetConnectionId()\n    const url = this.buildUrl({ includeSince: true })\n    this.eventSource = new EventSource(url, { withCredentials: true })\n\n    this.eventSource.addEventListener(\"open\", () => {\n      this.setAttribute(\"connected\", \"\")\n      this.dispatchEvent(new CustomEvent(\"pgbus:open\", {\n        detail: { lastEventId: this.lastEventId, connectionId: this.connectionId }\n      }))\n    })\n\n    this.eventSource.addEventListener(\"error\", () => {\n      this.removeAttribute(\"connected\")\n    })\n\n    this.eventSource.addEventListener(\"turbo-stream\", (event) => {\n      this.lastEventId = event.lastEventId\n      this.emitTurboStream(event.data, event.lastEventId)\n    })\n\n    this.eventSource.addEventListener(\"pgbus:connected\", (event) => {\n      this.handleConnected(event.data)\n    })\n\n    this.eventSource.addEventListener(\"pgbus:gap-detected\", (event) => {\n      const detail = this.safeJsonParse(event.data)\n      this.dispatchEvent(new CustomEvent(\"pgbus:gap-detected\", { detail }))\n    })\n\n    this.eventSource.addEventListener(\"pgbus:shutdown\", () => {\n      this.dispatchEvent(new CustomEvent(\"pgbus:close\", {\n        detail: { code: \"shutdown\", reason: \"worker restart\" }\n      }))\n    })\n\n    // Typed broadcasts (issue #170): EventSource only fires listeners\n    // registered by name, so we register one per declared typed event.\n    for (const name of this.declaredTypedEvents()) {\n      this.eventSource.addEventListener(name, (event) => {\n        if (event.lastEventId) this.lastEventId = event.lastEventId\n        this.emitTypedEvent(name, event.data, event.lastEventId)\n      })\n    }\n  }\n\n  // Parses a single SSE event block (: comment | id: ... | event: ... | data: ...)\n  handleBlock(block) {\n    if (!block || block.startsWith(\":\")) return // comment\n\n    let id = null\n    let event = \"message\"\n    const dataLines = []\n\n    for (const line of block.split(\"\\n\")) {\n      if (line.startsWith(\"id:\")) id = line.slice(3).trim()\n      else if (line.startsWith(\"event:\")) event = line.slice(6).trim()\n      // Per the SSE spec: strip only a single leading space after the colon\n      // (never trim — payload whitespace is significant, issue #392) and\n      // rejoin consecutive data: lines with \\n, matching native EventSource.\n      else if (line.startsWith(\"data:\")) dataLines.push(line.slice(5).replace(/^ /, \"\"))\n    }\n    const data = dataLines.join(\"\\n\")\n\n    if (id !== null) this.lastEventId = id\n\n    if (event === \"turbo-stream\") {\n      this.emitTurboStream(data, id)\n    } else if (event === \"pgbus:connected\") {\n      this.handleConnected(data)\n    } else if (event === \"pgbus:gap-detected\") {\n      this.dispatchEvent(new CustomEvent(\"pgbus:gap-detected\", {\n        detail: this.safeJsonParse(data)\n      }))\n    } else if (event === \"pgbus:shutdown\") {\n      this.dispatchEvent(new CustomEvent(\"pgbus:close\", {\n        detail: { code: \"shutdown\", reason: \"worker restart\" }\n      }))\n    } else {\n      // A typed broadcast (issue #170): event: presence | reactive | ...\n      this.emitTypedEvent(event, data, id)\n    }\n  }\n\n  // Captures the server-minted connection id from a `pgbus:connected`\n  // frame: stores it, reflects it onto the `connection-id` attribute (so\n  // it's visible in the DOM / to MutationObservers), and re-dispatches it\n  // as a `pgbus:connected` CustomEvent. Idempotent across reconnects — the\n  // server mints a fresh id per connection, so a reconnect updates it.\n  handleConnected(data) {\n    const detail = this.safeJsonParse(data)\n    const connectionId = detail && detail.connectionId\n    if (!connectionId) return\n\n    this.connectionId = connectionId\n    this.setAttribute(\"connection-id\", connectionId)\n    this.dispatchEvent(new CustomEvent(\"pgbus:connected\", {\n      detail: { connectionId }\n    }))\n  }\n\n  // Clears the cached connection id and its reflected attribute. Called at\n  // the start of every transport open so a reconnect doesn't carry the\n  // previous connection's id into pgbus:open before the new pgbus:connected\n  // frame arrives.\n  resetConnectionId() {\n    this.connectionId = null\n    this.removeAttribute(\"connection-id\")\n  }\n\n  // Delivers a turbo-stream frame to two audiences (issue #168):\n  //\n  //   1. Turbo's StreamObserver, via a `message` MessageEvent whose `data`\n  //      is the turbo-stream HTML. The MessageEvent's standard\n  //      `lastEventId` field carries the frame's msg_id, so a reactive\n  //      runtime that listens for `message` can read the revision without\n  //      any pgbus-specific API. (Turbo ignores lastEventId.)\n  //\n  //   2. A reactive runtime doing optimistic-UI reconciliation, via a\n  //      `pgbus:message` CustomEvent carrying { msgId, data }. msgId is the\n  //      monotonic per-stream revision (a negative value marks an ephemeral\n  //      frame that was never persisted). Pattern: track the highest msgId\n  //      you have applied per target; when a frame arrives, skip the morph\n  //      if you have already applied a newer revision for that target —\n  //      this stops a late echo from clobbering a newer optimistic edit.\n  //      Complements #165: exclude handles the actor; this handles\n  //      out-of-order delivery for everyone else.\n  //\n  // msgId is parsed to a Number when numeric so consumers can compare\n  // revisions with `>` directly; left as-is otherwise.\n  emitTurboStream(data, id) {\n    const msgId = id === null || id === undefined || id === \"\" ? null\n      : (Number.isNaN(Number(id)) ? id : Number(id))\n\n    const message = new MessageEvent(\"message\", { data, lastEventId: id == null ? \"\" : String(id) })\n    this.dispatchEvent(message)\n\n    this.dispatchEvent(new CustomEvent(\"pgbus:message\", {\n      detail: { msgId, data }\n    }))\n  }\n\n  // Delivers a typed broadcast (issue #170) — a frame whose SSE event name\n  // is something other than turbo-stream (e.g. \"presence\", \"reactive\").\n  // The payload is still whatever the broadcaster sent (usually a Turbo\n  // Stream); the typed name lets a client route without sniffing the HTML.\n  // Dispatched two ways for ergonomics:\n  //   - a generic `pgbus:event` { event, data, msgId } (one listener for all)\n  //   - a named `pgbus:<event>`  { data, msgId }      (addEventListener by name)\n  emitTypedEvent(event, data, id) {\n    const msgId = id === null || id === undefined || id === \"\" ? null\n      : (Number.isNaN(Number(id)) ? id : Number(id))\n\n    this.dispatchEvent(new CustomEvent(\"pgbus:event\", {\n      detail: { event, data, msgId }\n    }))\n    this.dispatchEvent(new CustomEvent(`pgbus:${event}`, {\n      detail: { data, msgId }\n    }))\n  }\n\n  // Typed event names the EventSource (reconnect) path should listen for,\n  // declared by the app via the `listen-events` attribute (comma- or\n  // space-separated). EventSource only invokes listeners registered by\n  // name, so unlike the fetch path it cannot route unknown typed events\n  // generically; declaring them here keeps typed delivery working across\n  // reconnects. The fetch (initial) path always routes typed events.\n  declaredTypedEvents() {\n    const raw = this.getAttribute(\"listen-events\")\n    if (!raw) return []\n    return raw.split(/[\\s,]+/).filter((name) => name && name !== \"turbo-stream\")\n  }\n\n  buildUrl({ includeSince }) {\n    const src = this.getAttribute(\"src\")\n    const since = includeSince && this.lastEventId ? this.lastEventId : null\n    const seat = this.pgbusSeat\n    if (!since && !seat) return src\n\n    const url = new URL(src, window.location.origin)\n    if (since) url.searchParams.set(\"since\", since)\n    if (seat) url.searchParams.set(\"seat\", seat)\n    return url.toString()\n  }\n\n  safeJsonParse(str) {\n    try { return JSON.parse(str) } catch { return null }\n  }\n}\n\nif (!customElements.get(\"pgbus-stream-source\")) {\n  customElements.define(\"pgbus-stream-source\", PgbusStreamSourceElement)\n}\n\nexport { PgbusStreamSourceElement }\n"],"mappings":"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","names":[]}

data/lib/pgbus/configuration/stream_authorization.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Configuration
+    # The authorize hook the engine-mounted StreamApp uses (issue #522). Same
+    # contract as StreamApp.new(authorize:):
+    #
+    #   config.streams_authorize = ->(env, stream_name) {
+    #     user = current_user_from(env)
+    #     user if user && may_read?(user, stream_name)
+    #   }
+    #
+    # A falsy return answers 403, `true` authorizes with no context, any other
+    # value becomes the connection context (what visible_to: filters and
+    # connection-driven presence read). nil (the default) authorizes every
+    # connection with no context. An app that mounts its own
+    # StreamApp.new(authorize:) keeps its hook; this one is not consulted.
+    #
+    # Authorize per stream: the signed name proves pgbus minted it, not that
+    # this user may read it (a removed member keeps a working name until the
+    # secret rotates). A non-callable value fails validate!; with
+    # eager_validation = false every stream request fails closed with a 500.
+    module StreamAuthorization
+      attr_accessor :streams_authorize
+
+      private
+
+      def validate_stream_authorization!
+        return if streams_authorize.nil? || streams_authorize.respond_to?(:call)
+
+        raise Pgbus::ConfigurationError,
+              "streams_authorize must respond to #call (a ->(env, stream_name) { } lambda) or be nil"
+      end
+    end
+  end
+end

data/lib/pgbus/configuration.rb

@@ -5,6 +5,7 @@ require "logger"
 module Pgbus
   class Configuration
     include PresenceSettings
+    include StreamAuthorization
 
     # Connection settings
     attr_accessor :database_url, :connection_params, :pool_size, :pool_timeout
@@ -217,7 +218,7 @@ module Pgbus
 
     # Streams (turbo-rails replacement, SSE-based)
     attr_accessor :streams_enabled, :streams_path, :streams_signed_name_secret,
-                  :streams_default_retention, :streams_retention, :streams_heartbeat_interval,
+                  :streams_default_retention, :streams_retention, :streams_heartbeat_interval, :streams_peer_close_interval,
                   :streams_max_connections, :streams_idle_timeout, :streams_listen_health_check_ms,
                   :streams_write_deadline_ms, :streams_falcon_streaming_body,
                   :streams_stats_enabled, :streams_test_mode,
@@ -461,6 +462,10 @@ module Pgbus
       @streams_default_retention = 5 * 60 # 5 minutes
       @streams_retention = {}
       @streams_heartbeat_interval = 15
+      # Seconds a new SSE connection waits to join the peer-close watch; a
+      # client that closes a watched socket is noticed at once (issue #519).
+      # nil turns the watcher off and leaves disconnects to the heartbeat.
+      @streams_peer_close_interval = 1.0
       @streams_max_connections = 2_000
       @streams_idle_timeout = 3_600 # 1 hour
       # 250ms — this value plays two roles: (1) the TCP keepalive
@@ -1028,6 +1033,11 @@ module Pgbus
         raise Pgbus::ConfigurationError, "streams_heartbeat_interval must be a positive number"
       end
 
+      unless streams_peer_close_interval.nil? ||
+             (streams_peer_close_interval.is_a?(Numeric) && streams_peer_close_interval.positive?)
+        raise Pgbus::ConfigurationError, "streams_peer_close_interval must be nil or a positive number"
+      end
+
       unless streams_idle_timeout.is_a?(Numeric) && streams_idle_timeout.positive?
         raise Pgbus::ConfigurationError, "streams_idle_timeout must be a positive number"
       end
@@ -1096,6 +1106,7 @@ module Pgbus
       end
 
       validate_presence_settings!
+      validate_stream_authorization!
 
       return if streams_orphan_threshold.nil?
       return if streams_orphan_threshold.is_a?(Numeric) && streams_orphan_threshold.positive?

data/lib/pgbus/process/worker.rb

@@ -210,6 +210,11 @@ module Pgbus
           @wake_signal.wait(timeout: config.polling_interval) if @lifecycle.draining? || @lifecycle.paused?
         end
 
+        # The lifecycle can change on another thread between the
+        # return_claims check and the breaks above, so a loop that exits with
+        # the state it never returned claims for would strand them until their
+        # visibility timeout. Nothing buffered outlives the loop.
+        return_claims
         shutdown
       end
 

data/lib/pgbus/streams/envelope.rb

@@ -49,8 +49,9 @@ module Pgbus
       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
+      # connection id as JSON. Sent once by the streamer's Dispatcher, after
+      # the connection is registered and its presence seat joined (issue
+      # #521), 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

data/lib/pgbus/version.rb

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

data/lib/pgbus/web/stream_app.rb

@@ -16,13 +16,16 @@ module Pgbus
     # Call flow (happy path, Puma 6.1+ hijack):
     #   1. Parse the signed name from PATH_INFO
     #   2. Verify it via Pgbus::Streams::SignedName (raises → 404)
-    #   3. Run the authorize hook (raises → 403)
+    #   3. Run the authorize hook: authorize:, else config.streams_authorize
+    #      (falsy → 403)
     #   4. Parse the cursor from ?since= or Last-Event-ID
     #   5. Check streams_max_connections per worker (over → 503)
     #   6. Check rack.hijack? (missing → 501)
     #   7. Hijack, write the HTTP response line + SSE headers + opening
     #      comment directly to the socket
-    #   8. Build a Connection, hand to Streamer.current.register(...)
+    #   8. Build a Connection, hand to Streamer.current.register(...). The
+    #      Dispatcher writes the pgbus:connected frame once the connection
+    #      is registered and its presence seat joined (issue #521)
     #   9. Return [-1, {}, []] (Puma's async protocol)
     #
     # On errors, returns a normal [status, headers, body] response so
@@ -38,11 +41,15 @@ module Pgbus
       TEST_MODE_RETRY_MS = 86_400_000
       private_constant :PATH_PREFIX
 
+      # Used when neither authorize: nor config.streams_authorize is set.
+      ALLOW_ALL = ->(_env, _stream_name) { true }
+      private_constant :ALLOW_ALL
+
       def initialize(streamer: nil, config: nil, logger: nil, authorize: nil)
         @streamer_override = streamer
         @config_override   = config
         @logger_override   = logger
-        @authorize         = authorize || ->(_env, _stream_name) { true }
+        @authorize         = authorize
       end
 
       def call(env)
@@ -55,7 +62,7 @@ module Pgbus
         stream_name = verify!(signed_name)
         return not_found("invalid signed stream name") if stream_name.nil?
 
-        authorize_result = @authorize.call(env, stream_name)
+        authorize_result = authorize_hook.call(env, stream_name)
         return forbidden unless authorize_result
 
         # If authorize returned a non-boolean value (e.g. a User model),
@@ -134,7 +141,7 @@ module Pgbus
         io = hijack_result || env["rack.hijack_io"]
 
         connection_id = SecureRandom.hex(8)
-        write_headers(io, stream_name: stream_name, since_id: since_id, connection_id: connection_id)
+        write_headers(io, stream_name: stream_name, since_id: since_id)
 
         connection = Pgbus::Web::Streamer::Connection.new(
           id: connection_id,
@@ -162,7 +169,6 @@ module Pgbus
         body.write(Pgbus::Streams::Envelope.comment(
                      "pgbus stream open since_id=#{since_id} stream=#{stream_name}"
                    ))
-        body.write(Pgbus::Streams::Envelope.connected(id: connection_id))
 
         connection = Pgbus::Web::Streamer::FalconConnection.new(
           id: connection_id,
@@ -186,11 +192,22 @@ module Pgbus
         }
       end
 
-      def write_headers(io, stream_name:, since_id:, connection_id:)
+      def write_headers(io, stream_name:, since_id:)
         io.write(Pgbus::Streams::Envelope.http_response_headers)
         io.write(Pgbus::Streams::Envelope.retry_directive(2_000))
         io.write(Pgbus::Streams::Envelope.comment("pgbus stream open since_id=#{since_id} stream=#{stream_name}"))
-        io.write(Pgbus::Streams::Envelope.connected(id: connection_id))
+      end
+
+      # An explicit authorize: wins; otherwise config.streams_authorize, read
+      # per request so the engine's mount (built when routes load) sees a hook
+      # set in an initializer that runs later (issue #522). Only nil means
+      # "unset": any other non-callable (false included) must reach #call and
+      # fail closed with a 500, never fall through to ALLOW_ALL.
+      def authorize_hook
+        return @authorize unless @authorize.nil?
+
+        hook = config.streams_authorize
+        hook.nil? ? ALLOW_ALL : hook
       end
 
       def streamer

data/lib/pgbus/web/streamer/connection.rb

@@ -88,20 +88,21 @@ module Pgbus
         end
 
         def write_comment(text)
-          bytes = Pgbus::Streams::Envelope.comment(text)
-          result = @writer.write(self, bytes, deadline_ms: @write_deadline_ms)
-          if result == :ok
-            @last_write_at = monotonic
-          else
-            mark_dead!
-          end
-          result
+          write_frame(Pgbus::Streams::Envelope.comment(text))
         end
 
         def write_sentinel(bytes)
           @writer.write(self, bytes, deadline_ms: @write_deadline_ms)
         end
 
+        # The pgbus:connected frame carrying this connection's id. Written by
+        # the Dispatcher once the connection is registered and its presence
+        # seat joined (issue #521), so a client that acts on the id right
+        # after the event finds its row.
+        def write_connected
+          write_frame(Pgbus::Streams::Envelope.connected(id: @id))
+        end
+
         def idle_for
           monotonic - @last_write_at
         end
@@ -142,6 +143,16 @@ module Pgbus
 
         private
 
+        def write_frame(bytes)
+          result = @writer.write(self, bytes, deadline_ms: @write_deadline_ms)
+          if result == :ok
+            @last_write_at = monotonic
+          else
+            mark_dead!
+          end
+          result
+        end
+
         # The SSE event name for a frame: the envelope's typed event when
         # present, else the default turbo-stream. Plain ReadAfter::Envelopes
         # (no event field) and StreamEnvelopes with a nil event both fall

data/lib/pgbus/web/streamer/falcon_connection.rb

@@ -74,14 +74,12 @@ module Pgbus
         end
 
         def write_comment(text)
-          bytes = Pgbus::Streams::Envelope.comment(text)
-          result = write_to_body(bytes)
-          if result == :ok
-            @last_write_at = monotonic
-          else
-            mark_dead!
-          end
-          result
+          write_frame(Pgbus::Streams::Envelope.comment(text))
+        end
+
+        # See Connection#write_connected (issue #521).
+        def write_connected
+          write_frame(Pgbus::Streams::Envelope.connected(id: @id))
         end
 
         def write_sentinel(bytes)
@@ -120,6 +118,16 @@ module Pgbus
           event && !event.to_s.empty? ? event.to_s : Pgbus::Streams::DEFAULT_SSE_EVENT
         end
 
+        def write_frame(bytes)
+          result = write_to_body(bytes)
+          if result == :ok
+            @last_write_at = monotonic
+          else
+            mark_dead!
+          end
+          result
+        end
+
         def write_to_body(bytes)
           @mutex.synchronize do
             return :closed if @dead || @body.closed?

data/lib/pgbus/web/streamer/instance.rb

@@ -3,14 +3,15 @@
 module Pgbus
   module Web
     module Streamer
-      # Composes the Streamer's three background threads (Listener, Dispatcher,
-      # Heartbeat) with the shared Registry and dispatch_queue. One Instance
-      # per Puma worker. Owns the lifecycle of all three threads and the
-      # dedicated PG::Connection for LISTEN.
+      # Composes the Streamer's background threads (Listener, Dispatcher,
+      # Heartbeat, and the PeerCloseWatcher unless streams_peer_close_interval
+      # is nil) with the shared Registry and dispatch_queue. One Instance per
+      # Puma worker. Owns the lifecycle of those threads and the dedicated
+      # PG::Connection for LISTEN.
       #
       # Lifecycle:
       #   Instance.new(...)  — allocates wiring, does NOT start threads
-      #   #start             — spawns listener/dispatcher/heartbeat in order
+      #   #start             — spawns listener/dispatcher/heartbeat/watcher in order
       #   #register(conn)    — enqueues a ConnectMessage into the dispatch queue
       #   #shutdown!         — sends shutdown sentinel to every connection and
       #                        stops all threads in reverse order
@@ -21,7 +22,7 @@ module Pgbus
       # defaults from the configuration.
       class Instance
         attr_reader :registry, :listener, :dispatcher, :heartbeat, :dispatch_queue, :stream_counter, :pump,
-                    :autoscaler
+                    :autoscaler, :peer_close_watcher
 
         def initialize(
           client: Pgbus.client,
@@ -77,6 +78,7 @@ module Pgbus
             logger: @logger,
             presence_expiry: Array(@config.streams_presence_patterns).any?
           )
+          @peer_close_watcher = build_peer_close_watcher
           @started = false
           @shutdown_mutex = Mutex.new
         end
@@ -91,6 +93,7 @@ module Pgbus
           @listener.start
           @dispatcher.start
           @heartbeat.start
+          @peer_close_watcher&.start
           self
         end
 
@@ -119,7 +122,9 @@ module Pgbus
         end
 
         # Graceful shutdown for Puma worker restart. Order matters:
-        #   1. Heartbeat first (stop writing comments to connections we're
+        #   0. Peer-close watcher first (issue #519): stop reaping sockets
+        #      we're about to close ourselves; #stop wakes its select at once
+        #   1. Heartbeat next (stop writing comments to connections we're
         #      about to close)
         #   2. Listener next (stop accepting new NOTIFYs)
         #   3. Dispatcher next (drain the queue; it's now finite because
@@ -150,6 +155,7 @@ module Pgbus
 
             @started = false
             threads = component_threads
+            safely { @peer_close_watcher&.stop }
             safely { @heartbeat.stop }
             safely { @listener.stop }
             safely { @dispatcher.stop }
@@ -242,6 +248,7 @@ module Pgbus
         def component_threads
           {
             "heartbeat" => @heartbeat.threads,
+            "peer_close_watcher" => @peer_close_watcher ? @peer_close_watcher.threads : [],
             "listener" => @listener.threads,
             "dispatcher" => @dispatcher.threads,
             "pump" => @pump ? @pump.threads : []
@@ -276,6 +283,15 @@ module Pgbus
           )
         end
 
+        # Notices a closed SSE client at once instead of on the next
+        # heartbeat write (issue #519). nil interval: heartbeat only.
+        def build_peer_close_watcher
+          interval = @config.streams_peer_close_interval
+          return nil unless interval
+
+          PeerCloseWatcher.new(registry: @registry, dispatch_queue: @dispatch_queue, interval: interval, logger: @logger)
+        end
+
         def build_pump
           threads = @config.streams_writer_threads
           return nil unless threads.positive?

data/lib/pgbus/web/streamer/peer_close_watcher.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Web
+    module Streamer
+      # Notices an SSE client that went away the moment its socket says so,
+      # instead of on the next heartbeat write (issue #519).
+      #
+      # The server never reads a hijacked SSE socket after the request, so a
+      # closed tab used to stay registered (and present) until a heartbeat
+      # write failed, up to streams_heartbeat_interval later. Often longer:
+      # the first write after the client's FIN still succeeds. The client
+      # sends nothing after its request, so the socket only turns readable
+      # when the peer closes or resets it. This thread waits on every live
+      # socket with IO.select and probes the readable ones with a
+      # non-blocking read. EOF or a reset means the client is gone: the
+      # connection is marked dead, closed, and handed to the dispatcher's
+      # disconnect path, the same DisconnectMessage the heartbeat posts. That
+      # path is idempotent, so a heartbeat racing the watcher still leaves
+      # the seat once.
+      #
+      # Only connections with a real socket are watched: Puma's and Falcon's
+      # rack.hijack paths. Falcon's experimental streaming-body path
+      # (FalconConnection) exposes no socket and keeps the heartbeat.
+      #
+      # Half-close: a client that shuts down only its write side (SHUT_WR)
+      # reads as EOF and is reaped. EventSource, fetch streams and reverse
+      # proxies never half-close an SSE request, so EOF means the client left.
+      #
+      # The probe takes the connection's write mutex with try_lock: a TLS
+      # wrapper (Puma's MiniSSL) is not safe to read while IoWriter writes
+      # through it. A socket mid-write is skipped and probed on a later pass.
+      #
+      # `interval` bounds how long a new connection waits to join the
+      # watched set; a close on a watched socket wakes the select at once,
+      # and #stop wakes it through a self-pipe.
+      class PeerCloseWatcher
+        # Stray bytes from a client are read and discarded in chunks of this.
+        DRAIN_BYTES = 4096
+
+        # How long #stop waits for the thread. It is woken at once, so this
+        # only bounds a reap stuck closing a socket (see Heartbeat#stop).
+        STOP_JOIN_SECONDS = 5
+
+        def initialize(registry:, dispatch_queue:, interval: 1.0, logger: Pgbus.logger)
+          @registry = registry
+          @queue = dispatch_queue
+          @interval = interval
+          @logger = logger
+          @running = false
+          @thread = nil
+          @wake_reader, @wake_writer = IO.pipe
+        end
+
+        def start
+          return if @running
+
+          @wake_reader, @wake_writer = IO.pipe if @wake_reader.closed?
+          @running = true
+          @thread = Thread.new { run_loop }
+          self
+        end
+
+        # See Heartbeat#threads (issue #443).
+        def threads
+          [@thread].compact
+        end
+
+        def stop
+          return unless @running
+
+          @running = false
+          wake
+          @thread&.join(STOP_JOIN_SECONDS)
+          @thread = nil
+          @wake_reader.close
+          @wake_writer.close
+          self
+        end
+
+        # One wait-and-probe pass, at most `interval` long. Public for tests.
+        def tick
+          by_socket = watched_sockets
+          ready, = IO.select([@wake_reader, *by_socket.keys], nil, nil, @interval)
+          Array(ready).each do |socket|
+            socket.equal?(@wake_reader) ? drain_wake : probe(by_socket[socket])
+          end
+        rescue IOError, Errno::EBADF => e
+          # A socket was closed under the select (shutdown, a dispatcher
+          # write that failed). The next pass rebuilds the set without it.
+          @logger.debug { "[Pgbus::Streamer::PeerCloseWatcher] select interrupted: #{e.class}: #{e.message}" }
+        end
+
+        private
+
+        def wake
+          @wake_writer.write_nonblock(".", exception: false)
+        rescue IOError
+          nil
+        end
+
+        def drain_wake
+          @wake_reader.read_nonblock(64, exception: false)
+        end
+
+        # One socket's probe never ends the pass for the others.
+        def probe(connection)
+          return unless connection.mutex.try_lock
+
+          closed = begin
+            peer_closed?(connection)
+          ensure
+            connection.mutex.unlock
+          end
+          reap(connection) if closed
+        rescue StandardError => e
+          @logger.error { "[Pgbus::Streamer::PeerCloseWatcher] probe of #{connection.id} raised: #{e.class}: #{e.message}" }
+        end
+
+        def run_loop
+          while @running
+            begin
+              tick
+            rescue StandardError => e
+              @logger.error { "[Pgbus::Streamer::PeerCloseWatcher] tick raised: #{e.class}: #{e.message}" }
+              sleep @interval
+            end
+          end
+        end
+
+        # select needs a real IO: Puma's TLS socket and Falcon's hijacked
+        # stream answer #to_io with the underlying socket.
+        def watched_sockets
+          sockets = {}
+          @registry.each_connection do |connection|
+            next if connection.dead?
+
+            socket = socket_of(connection)
+            sockets[socket] = connection if socket
+          end
+          sockets
+        end
+
+        def socket_of(connection)
+          io = connection.io
+          return nil unless io.respond_to?(:to_io) && io.respond_to?(:read_nonblock)
+
+          socket = io.to_io
+          socket if socket.is_a?(::BasicSocket) && !socket.closed?
+        end
+
+        def peer_closed?(connection)
+          # A nil read is EOF; :wait_readable (TLS, a spurious wake) and stray
+          # bytes leave the connection alone.
+          connection.io.read_nonblock(DRAIN_BYTES, exception: false).nil?
+        rescue IO::WaitReadable
+          # A socket wrapper that raises instead of honouring exception:
+          # false (EAGAIN is a SystemCallError, so this rescue comes first).
+          false
+        rescue IOError, SystemCallError, *tls_errors
+          true
+        end
+
+        # A TLS socket whose client vanished without close_notify raises its
+        # library's SSL error ("unexpected eof while reading") on read.
+        def tls_errors
+          errors = []
+          errors << ::OpenSSL::SSL::SSLError if defined?(::OpenSSL::SSL::SSLError)
+          errors << ::Puma::MiniSSL::SSLError if defined?(::Puma::MiniSSL::SSLError)
+          errors
+        end
+
+        def reap(connection)
+          return if connection.dead?
+
+          connection.mark_dead!
+          connection.close
+          @queue << StreamEventDispatcher::DisconnectMessage.new(connection: connection)
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/web/streamer/stream_event_dispatcher.rb

@@ -401,6 +401,16 @@ module Pgbus
             @stream_counter.increment_connections(stream)
             @registry.register(connection)
             presence_join(connection, stream)
+            # Step 6: announce the connection id only now (issue #521). A
+            # client that writes keyed by it right after pgbus:connected
+            # (Presence#set_state) must find the registered connection and
+            # its presence row. If that write finds the socket gone, run the
+            # disconnect now rather than leave the connection registered,
+            # and its seat on the roster, until the next heartbeat. A later
+            # DisconnectMessage for it (heartbeat, peer-close watcher) is a
+            # no-op: unregister reports false and the seat has already left.
+            connection.write_connected
+            handle_disconnect(DisconnectMessage.new(connection: connection)) if connection.dead?
           end
 
           record_stat(
@@ -409,10 +419,12 @@ module Pgbus
             started_at: started_at
           )
         rescue StandardError => e
-          # Same leak path for exceptions in steps 1-4. Mark dead and
+          # Same leak path for exceptions in steps 1-6. Mark dead and
           # scrub state so a transient failure on a single connect
           # doesn't permanently bloat @full_to_logical or leave a
-          # dangling LISTEN on the PG connection.
+          # dangling LISTEN on the PG connection. A connection already
+          # registered in step 5 is dead now, so the heartbeat sweep
+          # unregisters it (and leaves its seat) like any dead connection.
           remove_in_flight(stream, connection)
           @scanned_cursor.delete(connection)
           cleanup_stream_if_unused(stream)
@@ -429,6 +441,10 @@ module Pgbus
           @stream_counter.decrement_connections(stream) if removed
           presence_leave(connection, stream)
           cleanup_stream_if_unused(stream)
+          # A second DisconnectMessage for the same connection (heartbeat,
+          # peer-close watcher, a failed pgbus:connected write) is a no-op
+          # and must not count as another disconnect.
+          return unless removed
 
           record_stat(
             stream_name: stream,

data/lib/pgbus.rb

@@ -289,8 +289,10 @@ module Pgbus
     # Do NOT call close — the parent's @pgmq_mutex is in undefined
     # state post-fork and attempting to acquire it can deadlock.
     # The next call to Pgbus.client will lazily create a fresh one.
+    # Cached streams hold the client they were built with, so they go too.
     def reset_client!
       @client = nil
+      @stream_cache = nil
     end
 
     def logger

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.17.3
+  version: 0.18.1
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -316,6 +316,7 @@ files:
 - lib/pgbus/configuration.rb
 - lib/pgbus/configuration/capsule_dsl.rb
 - lib/pgbus/configuration/presence_settings.rb
+- lib/pgbus/configuration/stream_authorization.rb
 - lib/pgbus/current_attributes.rb
 - lib/pgbus/database_tasks_guard.rb
 - lib/pgbus/dead_letter_header.rb
@@ -477,6 +478,7 @@ files:
 - lib/pgbus/web/streamer/master_hub.rb
 - lib/pgbus/web/streamer/master_hub_boot.rb
 - lib/pgbus/web/streamer/outbound_pump.rb
+- lib/pgbus/web/streamer/peer_close_watcher.rb
 - lib/pgbus/web/streamer/presence_tracker.rb
 - lib/pgbus/web/streamer/registry.rb
 - lib/pgbus/web/streamer/stream_counter.rb