pgbus 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb5b86968b21bebedf9b33d6d69338b86f7dfb5304b5efa714b270bc8128fa10
-  data.tar.gz: f5d6118149ebcd7c7f773ab399fbdc97079883dd895339c5918c156fc416bbfe
+  metadata.gz: 9428608c5f9419017f78a37cfe59c70ec03ff276654e516444ec25b8d9ee4fed
+  data.tar.gz: 8ad2651f7b6f25203442c819649c81d90c55c057a2d77219c10f6f74d2db18e9
 SHA512:
-  metadata.gz: 7649ee8dfd9d9ff155e510c014a28fb070d79357d34ed4e8a8c0369c502c90b806d01775a0b01f480709fa9399d7ecc3edddb7d4e092813d42014d412833d9ce
-  data.tar.gz: 756c31dd3fd970dca11c78cbb17af8b74e798cd42e3782b9993e4081982cc340a1224b6c0b829c259ea6d13abcec035510c2b4e0e6b8c39f73a34b1b9cd2bc48
+  metadata.gz: d63781a6eac94d51d295ce57f47729f7e6d6fffcc7c9a1883db110dd5833f35bfdf14559e832431e0c1759dfb8fd060c6f09701da47f65355b966c35f5aaa2c0
+  data.tar.gz: 4acb342915df5bb5761ab534edcfbd051592735640d3fa9551b2c16b0e785ec8ffe82e45fec1e7dbc81c92d2e5408f23457c80c088dc7c2c49a1aa03584a80c8

data/README.md

@@ -31,6 +31,7 @@ PostgreSQL-native job processing and event bus for Rails, built on [PGMQ](https:
   - [Batches](#batches)
   - [Transactional outbox](#transactional-outbox)
   - [Archive compaction](#archive-compaction)
+- [Real-time broadcasts](#real-time-broadcasts-turbo-streams-replacement)
 - [Operations](#operations)
   - [CLI](#cli)
   - [Dashboard](#dashboard)
@@ -45,6 +46,7 @@ PostgreSQL-native job processing and event bus for Rails, built on [PGMQ](https:
 ## Features
 
 - **ActiveJob adapter** -- drop-in replacement, zero config migration from other backends
+- **Turbo Streams replacement** -- `pgbus_stream_from` drops into turbo-rails apps with no ActionCable, no Redis, no lost messages on reconnect. Includes transactional broadcasts (deferred until commit), backlog replay on connect, server-side audience filtering, and presence tracking. Fixes rails/rails#52420, hotwired/turbo#1261, and hotwired/turbo-rails#674.
 - **Event bus** -- publish/subscribe with AMQP-style topic routing (`orders.#`, `payments.*`)
 - **Dead letter queues** -- automatic DLQ routing after configurable retries
 - **Worker recycling** -- memory, job count, and lifetime limits prevent runaway processes
@@ -625,6 +627,234 @@ as configuration. The dispatcher runs archive compaction as part of its
 maintenance loop, deleting archived messages older than `archive_retention`
 in batches to avoid long-running transactions.
 
+## Real-time broadcasts (turbo-streams replacement)
+
+Pgbus ships a drop-in replacement for turbo-rails' `turbo_stream_from` helper that fixes several well-known ActionCable correctness bugs by using PGMQ message IDs as a replay cursor. Same API as turbo-rails. No Redis. No ActionCable. No lost messages on reconnect.
+
+**Bugs fixed:**
+
+- [**rails/rails#52420**](https://github.com/rails/rails/issues/52420) -- "page born stale": a broadcast that fires between controller render and WebSocket subscribe is silently lost with ActionCable. Pgbus captures a PGMQ `msg_id` watermark at render time and replays any messages published in the gap via the SSE `Last-Event-ID` mechanism.
+- [**hotwired/turbo#1261**](https://github.com/hotwired/turbo/issues/1261) -- missed messages on reconnect. Pgbus persists the cursor on the client (EventSource's built-in `Last-Event-ID`) and replays from the PGMQ archive on every reconnect.
+- [**hotwired/turbo-rails#674**](https://github.com/hotwired/turbo-rails/issues/674) -- no way to detect disconnect. Pgbus dispatches `pgbus:open`, `pgbus:gap-detected`, and `pgbus:close` DOM events on the stream element.
+
+### Usage
+
+Swap `turbo_stream_from` for `pgbus_stream_from` in your view:
+
+```erb
+<%# Before %>
+<%= turbo_stream_from @order %>
+
+<%# After %>
+<%= pgbus_stream_from @order %>
+```
+
+Everything else stays the same. The model concern keeps working unchanged:
+
+```ruby
+class Order < ApplicationRecord
+  broadcasts_to ->(order) { [order.account, :orders] }
+end
+```
+
+`broadcasts_to`, `broadcast_replace_to`, `broadcasts_refreshes`, `broadcast_append_later_to`, and every other `Turbo::Broadcastable` helper funnels through a single `Turbo::StreamsChannel.broadcast_stream_to` method that pgbus monkey-patches at engine boot. The signed-stream-name verification reuses `Turbo.signed_stream_verifier_key` so existing signed tokens Just Work.
+
+Add the Puma plugin to `config/puma.rb` so SSE connections drain cleanly on deploy:
+
+```ruby
+# config/puma.rb
+plugin :pgbus_streams
+```
+
+Without the plugin, Puma closes hijacked SSE sockets abruptly during graceful restart, which looks to browsers like a network error and triggers an immediate reconnect. With the plugin, the streamer writes a `pgbus:shutdown` sentinel before the socket closes; browsers reconnect to the new worker and replay missed messages via `Last-Event-ID`.
+
+### Requirements
+
+- **Puma 6.1+ or Falcon.** Streams use `rack.hijack`. Puma 6.1+ supports it via partial hijack (thread-releasing, see [puma/puma#1009](https://github.com/puma/puma/issues/1009)). Falcon supports it via [protocol-rack](https://github.com/socketry/protocol-rack)'s adapter layer — same `env["rack.hijack?"]` + `env["rack.hijack"]` shape as Puma, so `Pgbus::Web::StreamApp` needs no server-specific code paths. Unicorn, Pitchfork, and Passenger return HTTP 501 from the streams endpoint.
+- **PostgreSQL LISTEN/NOTIFY.** `config.listen_notify = true` (the default). Stream queues override PGMQ's 250ms NOTIFY throttle to 0 so every broadcast fires individually.
+- **HTTP/2 or HTTP/3 in production.** SSE has a 6-connection-per-origin limit on HTTP/1.1; HTTP/2 lifts it. Falcon supports HTTP/2 natively without a reverse proxy.
+
+### Configuration
+
+```ruby
+Pgbus.configure do |c|
+  c.streams_enabled                = true          # default
+  c.streams_queue_prefix           = "pgbus_stream"
+  c.streams_default_retention      = 5 * 60        # 5 minutes
+  c.streams_retention              = {             # per-stream overrides
+    /^chat_/        => 7 * 24 * 3600,              # 7 days for chat history
+    "presence_room" => 30                          # 30 seconds for presence
+  }
+  c.streams_heartbeat_interval     = 15            # seconds
+  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
+  c.streams_write_deadline_ms      = 5_000         # write_nonblock deadline
+end
+```
+
+### How it works
+
+Stream broadcasts are stored in PGMQ queues prefixed `pgbus_stream_*`. Each broadcast is assigned a monotonic `msg_id` by PGMQ. The `pgbus_stream_from` helper captures the current `MAX(msg_id)` at render time and embeds it in the HTML as `since-id`. When the SSE client connects, it sends that cursor as `?since=` on the first request and as `Last-Event-ID` on reconnects. The streamer replays from `pgmq.q_*` (live) UNION `pgmq.a_*` (archive) for any `msg_id > cursor`, then switches to LISTEN/NOTIFY for the live path. There is no message identity gap between the render and the subscribe — the cursor model guarantees every broadcast is delivered exactly once, in order, even across reconnects.
+
+One Puma worker (or Falcon reactor) hosts one `Pgbus::Web::Streamer::Instance` singleton with three threads (Listener / Dispatcher / Heartbeat) and one dedicated PG connection for LISTEN. Hijacked SSE sockets are held outside the web server's thread pool on Puma (confirmed by an integration test that fires 20 concurrent hijacked connections and observes them complete in parallel on an 8-thread Puma server, [puma/puma#1009](https://github.com/puma/puma/issues/1009)) and inside a fiber on Falcon (one fiber per hijacked connection, scheduler-backed non-blocking IO).
+
+> **Don't use `ActionController::Live` for pgbus streams.** It's the conventional Rails answer for SSE and it's the wrong one. `Live` blocks inside `@app.call(env)` for the lifetime of the connection, which ties up a Puma thread *per subscriber* — the exact problem the `rack.hijack`-based architecture above exists to avoid. Pgbus's streams endpoint is a mounted Rack app (not a Rails controller) so the temptation isn't even available, and a `rake pgbus:streams:lint_no_live` task fails CI if any pgbus controller `include`s it. If you're tempted to wire SSE through a Rails controller, use `pgbus_stream_from` in your view instead — the helper handles the cursor, replay, reconnect, and Puma-thread-release concerns for you.
+
+Per-stream retention is handled by the main pgbus dispatcher process on the same interval as the dispatcher's `ARCHIVE_COMPACTION_INTERVAL` constant. Streams default to a 5-minute retention because SSE clients reconnect within seconds; chat-style applications override the retention to days via `streams_retention`.
+
+### Transactional broadcasts
+
+**This is the feature no other Rails real-time stack can offer.** A broadcast issued inside an open ActiveRecord transaction is deferred until the transaction commits. If it rolls back, the broadcast silently drops — clients never see the change that the database never persisted.
+
+```ruby
+ActiveRecord::Base.transaction do
+  @order.update!(status: "shipped")
+  @order.broadcast_replace_to :account           # ← deferred until commit
+  RelatedService.update_counters!(@order)        # ← might raise, rolling back the update
+end
+# If RelatedService raised, the database state is unchanged AND no SSE client
+# ever saw a "shipped" broadcast. The broadcast and the data mutation are
+# atomic with respect to each other.
+```
+
+ActionCable can't do this because its broadcast path goes through Redis pub/sub, which has no concept of your application's transaction boundary. Pgbus detects the open AR transaction via `ActiveRecord::Base.connection.current_transaction.after_commit`, which is a first-class Rails API — no outbox table, no background worker, no extra storage.
+
+Outside an open transaction, broadcasts are synchronous and return the assigned `msg_id` as before. Inside a transaction, they return `nil` (the id isn't known until commit time).
+
+### Replaying history on connect (`replay:`)
+
+By default `pgbus_stream_from @room` captures `MAX(msg_id)` at render time and replays only broadcasts published after that — the page-born-stale fix. For chat-history-style applications where the page should show backlog on load, pass `replay:`:
+
+```erb
+<%# Show the last 50 messages on load, then stream live %>
+<%= pgbus_stream_from @room, replay: 50 %>
+
+<%# Show everything in PGMQ retention on load %>
+<%= pgbus_stream_from @room, replay: :all %>
+
+<%# Default behavior (post-render only) — same as omitting the option %>
+<%= pgbus_stream_from @room, replay: :watermark %>
+```
+
+The replay cap is applied server-side: the helper computes `since_id = max(0, current_msg_id - N)` for integer `N` and writes that into the HTML attribute. The client just reads the attribute and sends it as `?since=` on connect. Nothing else changes about the transport.
+
+How much history is actually available depends on the stream's retention setting (`streams_retention` or `streams_default_retention`, both in seconds). A chat stream configured with `streams_retention = { /^chat_/ => 7.days }` will replay up to seven days of history with `replay: :all`; a notification stream with the 5-minute default will only go back five minutes.
+
+### Server-side audience filtering
+
+Some broadcasts shouldn't reach every subscriber on a stream. Pgbus supports per-connection filtering via a registry of named predicates evaluated against each connection's authorize-hook context:
+
+```ruby
+# config/initializers/pgbus_streams.rb
+Pgbus::Streams.filters.register(:admin_only) { |user| user&.admin? }
+Pgbus::Streams.filters.register(:workspace_member) do |user, stream_name|
+  user&.workspace_ids&.include?(stream_name.split(":").last.to_i)
+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:
+
+```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
+})
+```
+
+Then label broadcasts with the filter you want to apply:
+
+```ruby
+@order.broadcast_replace_to :account                                # delivered to everyone
+Pgbus.stream("ops").broadcast(html, visible_to: :admin_only)        # admins only
+```
+
+Failure semantics:
+
+- **Unknown filter label** → fail-CLOSED with a warning log. Audience filtering is a data-isolation feature; failing open on a typo would turn a restricted broadcast into a public one. The warning log is loud enough that typos still get noticed in dev ("why are no subscribers receiving my broadcast?" → check the log).
+- **Filter predicate raises** → fail-CLOSED. A buggy predicate that crashes is treated as "deny" so private data doesn't leak on an exception path.
+- **No `visible_to` on the broadcast** → no filter applied; everyone sees it.
+
+The filter registry is process-local. Each Puma worker (or Falcon reactor) has its own copy populated at boot. Filter predicates run **on the subscriber side** — the predicate itself can't be serialized through PGMQ, so the broadcast carries only the label name.
+
+### Presence
+
+Pgbus tracks who is currently subscribed to a stream via a `pgbus_presence_members` table. This is the standard "X people are in this room" feature that chat apps and collaboration tools need:
+
+```ruby
+rails generate pgbus:add_presence
+rails db:migrate
+```
+
+```ruby
+class RoomsController < ApplicationController
+  def show
+    @room = Room.find(params[:id])
+    Pgbus.stream(@room).presence.join(
+      member_id: current_user.id.to_s,
+      metadata: { name: current_user.name, avatar: current_user.avatar_url }
+    ) do |member|
+      render_to_string(partial: "presence/joined", locals: { member: member })
+    end
+  end
+
+  def destroy
+    Pgbus.stream(@room).presence.leave(member_id: current_user.id.to_s) do |member|
+      "<turbo-stream action=\"remove\" target=\"presence-#{member['id']}\"></turbo-stream>"
+    end
+  end
+end
+```
+
+The block passed to `join`/`leave` is rendered into HTML and broadcast through the regular pgbus stream pipeline — so it shows up in every connected client's DOM in real time, alongside the normal `broadcasts_to` output. Reading the current member list:
+
+```ruby
+Pgbus.stream(@room).presence.members
+# => [{ "id" => "7", "metadata" => {...}, "joined_at" => "...", "last_seen_at" => "..." }]
+
+Pgbus.stream(@room).presence.count
+# => 5
+```
+
+**Heartbeat and expiry.** Members that don't ping `presence.touch(member_id: ...)` periodically can be expired by a sweeper:
+
+```ruby
+# Run from a cron, ActiveJob, or after each subscriber heartbeat
+Pgbus.stream(@room).presence.sweep!(older_than: 60.seconds.ago)
+```
+
+The sweep uses `DELETE ... RETURNING` so multiple workers running it concurrently won't double-emit leave events.
+
+**Deliberately left to the application**:
+
+- Join/leave is explicit, not connection-driven. The controller decides who is "present" — a connected SSE client is not always a present user (think tab-in-background, multi-tab dedup).
+- The stale-member sweep is manual. Run it from a cron, an ActiveJob, or your existing heartbeat — pgbus does not assume one over the others.
+- The DOM markup for join/leave is whatever your `join`/`leave` block returns. Pgbus does not impose a fixed presence schema on `<pgbus-stream-source>`.
+
+### Stream stats (opt-in)
+
+Pgbus can record one row in `pgbus_stream_stats` per broadcast, connect, and disconnect so the `/pgbus/insights` dashboard shows stream throughput alongside job throughput. This is **disabled by default** because stream event volume can dwarf job volume in chat-style apps — enable it deliberately when you want the observability.
+
+```ruby
+# config/initializers/pgbus.rb
+Pgbus.configure do |c|
+  c.streams_stats_enabled = true
+end
+```
+
+Then run the migration generator once:
+
+```bash
+rails generate pgbus:add_stream_stats                  # Add the migration
+rails generate pgbus:add_stream_stats --database=pgbus # For separate database
+rails db:migrate
+```
+
+The Insights tab gains a "Real-time Streams" section with counts of broadcasts / connects / disconnects, an "active" estimate (connects − disconnects in the selected window), average fanout per broadcast, and a "Top Streams by Broadcast Volume" table. The existing `stats_retention` config covers cleanup, so there is no separate retention knob.
+
+Overhead on a real Puma + PGMQ setup (`bundle exec rake bench:streams`): the most visible cost is an INSERT per connect/disconnect pair, which shows up under thundering-herd connect scenarios (K=50 concurrent connects: ~+20% per-connect latency). Steady-state broadcast and fanout numbers stay in the run-to-run noise band. Enable it if Insights is useful; leave it off if the write traffic worries you.
+
 ## Operations
 
 Day-to-day running of Pgbus: starting and stopping processes, observing what is happening on the dashboard, the database tables Pgbus relies on, and how to migrate from an existing job backend.
@@ -820,6 +1050,14 @@ bunx --bun playwright install chromium
 bundle exec rspec spec/system/
 ```
 
+End-to-end streams benchmarks (real Puma + real PGMQ + real SSE clients):
+
+```bash
+PGBUS_DATABASE_URL=postgres://user@host/db bundle exec rake bench:streams
+```
+
+The harness measures single-broadcast roundtrip latency, burst throughput, fanout to many clients, and concurrent connect under thundering herd. See `benchmarks/streams_bench.rb`.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -36,6 +36,11 @@ namespace :bench do
     ruby "benchmarks/integration_bench.rb"
   end
 
+  desc "Run streams benchmarks (requires PGBUS_DATABASE_URL; boots real Puma + SSE)"
+  task :streams do
+    ruby "benchmarks/streams_bench.rb"
+  end
+
   desc "Run all benchmarks (unit-level, no DB required)"
   task all: %i[serialization client executor]
 end
@@ -191,4 +196,6 @@ namespace :dummy do
   end
 end
 
-task default: %i[spec rubocop]
+load File.expand_path("lib/tasks/pgbus_streams.rake", __dir__)
+
+task default: %i[spec rubocop pgbus:streams:lint_no_live]

data/app/controllers/pgbus/insights_controller.rb

@@ -8,6 +8,12 @@ module Pgbus
       @slowest = data_source.slowest_job_classes(minutes: @minutes)
       @latency_by_queue = data_source.latency_by_queue(minutes: @minutes)
       @latency_available = Pgbus::JobStat.latency_columns?
+
+      @stream_stats_available = data_source.stream_stats_available?
+      return unless @stream_stats_available
+
+      @stream_summary = data_source.stream_stats_summary(minutes: @minutes)
+      @top_streams = data_source.top_streams(minutes: @minutes)
     end
   end
 end

data/app/helpers/pgbus/streams_helper.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Pgbus
+  # View helper for subscribing a page to one or more pgbus streams. This
+  # is the drop-in replacement for `turbo_stream_from` — same API, same
+  # streamable resolution (GlobalID objects, symbols, arrays), same
+  # signed-name verification path — but the rendered element speaks to
+  # `Pgbus::Web::StreamApp` via SSE instead of ActionCable.
+  #
+  # The critical difference from `turbo_stream_from` is the `since-id`
+  # attribute: it carries the current PGMQ `msg_id` watermark at render
+  # time so the streamer can replay anything published in the gap between
+  # the controller render and the client connecting. This is the fix for
+  # rails/rails#52420.
+  module StreamsHelper
+    # Renders a <pgbus-stream-source> custom element. The element's JS
+    # (shipped separately under app/javascript/pgbus/stream_source_element.js)
+    # opens an SSE connection to /pgbus/streams/<signed-name>?since=<cursor>,
+    # listens for messages, and forwards each turbo-stream HTML payload
+    # into Turbo via `connectStreamSource`.
+    #
+    # The `replay:` option controls which messages get delivered on the
+    # initial connect:
+    #   - :watermark (default) — only broadcasts published after this
+    #     render's moment (the page-born-stale fix). since_id = current_msg_id.
+    #   - :all — deliver every message still in PGMQ retention. since_id = 0.
+    #     Useful for chat rooms where the page should show backlog on load.
+    #   - N (Integer) — deliver the last N messages. since_id = max(0, current_msg_id - N).
+    #     Useful when the backlog is large and you want a capped history.
+    def pgbus_stream_from(*streamables, replay: :watermark, **html_attributes)
+      stream_name = Pgbus::Streams::Stream.name_from(streamables.length == 1 ? streamables.first : streamables)
+      signed_name = Pgbus::Streams::SignedName.sign(stream_name)
+
+      since_id = compute_since_id(stream_name, replay)
+
+      attributes = {
+        "src" => pgbus_stream_src(signed_name),
+        "signed-stream-name" => signed_name,
+        "since-id" => since_id.to_s,
+        # Compatibility shim: turbo-rails' cable_stream_source_element reads
+        # `channel` to decide which ActionCable channel to subscribe to.
+        # We emit the same attribute so a page that mistakenly uses the
+        # turbo-rails element still renders (with ActionCable semantics).
+        "channel" => "Turbo::StreamsChannel"
+      }.merge(html_attributes.transform_keys(&:to_s))
+
+      render_tag("pgbus-stream-source", attributes)
+    end
+
+    private
+
+    def compute_since_id(stream_name, replay)
+      case replay
+      when :watermark
+        # The page-born-stale fix: capture MAX(msg_id) at render time.
+        fetch_watermark(stream_name)
+      when :all
+        # Replay everything still in retention. The streamer's read_after
+        # handles both live and archive tables, so this pulls the full
+        # backlog bounded by `streams_retention`.
+        0
+      when Integer
+        raise ArgumentError, "replay: must be non-negative (got #{replay})" if replay.negative?
+
+        # Clamp to 0 so a fresh queue with replay: 1000 doesn't return
+        # a negative cursor. fetch_watermark goes through the per-request
+        # thread-local cache, so mixing :watermark and :N in the same
+        # render only queries once.
+        watermark = fetch_watermark(stream_name)
+        [watermark - replay, 0].max
+      else
+        raise ArgumentError, "replay: must be :watermark, :all, or a non-negative Integer (got #{replay.inspect})"
+      end
+    end
+
+    # Build the SSE endpoint URL by asking the engine where its
+    # `:streams` mount point lives, then appending the signed name.
+    # The base comes from Pgbus::Engine.routes.url_helpers.streams_path
+    # so the URL follows whatever mount point the host app chose for
+    # the engine ("/pgbus", "/admin/dashboard", etc.). A
+    # `NoMethodError` fallback covers the test-only context where
+    # the helper is included in a plain class outside a Rails
+    # request and the engine's url_helpers aren't wired in.
+    def pgbus_stream_src(signed_name)
+      base = Pgbus::Engine.routes.url_helpers.streams_path
+      "#{base}/#{signed_name}"
+    rescue NameError
+      # NameError covers both uninitialized-constant (Pgbus::Engine
+      # not loaded, e.g. plain-Ruby unit specs) and NoMethodError
+      # (a NameError subclass) when the routes helper chain isn't
+      # wired in.
+      "/pgbus/streams/#{signed_name}"
+    end
+
+    def fetch_watermark(stream_name)
+      # Avoid hitting Postgres multiple times within a single render when
+      # the page uses several pgbus_stream_from helpers. We cache per
+      # thread-local for the duration of the current request — Rails'
+      # RequestStore gem is the idiomatic fit but we don't want to add
+      # a runtime dep, so a plain Thread.current hash is used. The engine
+      # initializer clears this hash between requests via a Rack middleware
+      # (Phase 4.5).
+      cache = Thread.current[:pgbus_streams_watermark_cache] ||= {}
+      cache[stream_name] ||= Pgbus.stream(stream_name).current_msg_id
+    end
+
+    def render_tag(name, attributes)
+      attr_string = attributes.map { |k, v| %(#{k}="#{CGI.escape_html(v.to_s)}") }.join(" ")
+      html = "<#{name} #{attr_string}></#{name}>"
+      html.respond_to?(:html_safe) ? html.html_safe : html
+    end
+  end
+end

data/app/javascript/pgbus/stream_source_element.js

@@ -0,0 +1,212 @@
+// <pgbus-stream-source> — the browser-side counterpart to
+// Pgbus::StreamsHelper#pgbus_stream_from. Drop-in replacement for
+// turbo-rails' <turbo-cable-stream-source> that speaks SSE + pgbus
+// instead of WebSocket + ActionCable.
+//
+// Attributes (set by the view helper):
+//   src                 — absolute path to the SSE endpoint, including
+//                         the URL-safe signed stream name
+//   since-id            — PGMQ msg_id watermark at render time; the
+//                         client sends this as ?since= on the FIRST
+//                         connect so the server can replay any
+//                         broadcasts from the render-to-connect gap
+//                         (rails/rails#52420 fix)
+//   signed-stream-name  — present for parity with turbo-rails; unused
+//                         by this element because the signed name is
+//                         already in the URL path
+//   channel             — compatibility shim; ignored
+//
+// Events (dispatched on the element):
+//   pgbus:open         { lastEventId }
+//   pgbus:replay-start { fromId, toId }
+//   pgbus:replay-end   {}
+//   pgbus:gap-detected { lastSeenId, archiveOldestId }
+//   pgbus:close        { code, reason }
+//
+// The element integrates with Turbo via connectStreamSource /
+// disconnectStreamSource + dispatching MessageEvent("message") so Turbo
+// Stream HTML is automatically consumed by the existing StreamObserver.
+//
+// Transport strategy:
+//   - FIRST connect: use fetch() + ReadableStream to include ?since=
+//     in the URL. Native EventSource cannot send Last-Event-ID on the
+//     initial request, so we need fetch to carry the watermark.
+//   - RECONNECT: switch to native EventSource, which sends Last-Event-ID
+//     automatically based on the last id: we observed. The native
+//     client is more battle-tested for reconnection backoff.
+
+import { connectStreamSource, disconnectStreamSource } from "@hotwired/turbo"
+
+class PgbusStreamSourceElement extends HTMLElement {
+  static get observedAttributes() {
+    return ["src", "since-id"]
+  }
+
+  constructor() {
+    super()
+    this.abortController = null
+    this.eventSource = null
+    this.lastEventId = null
+    this.closed = false
+  }
+
+  connectedCallback() {
+    connectStreamSource(this)
+    const sinceId = this.getAttribute("since-id")
+    this.lastEventId = sinceId && sinceId !== "" ? sinceId : null
+    this.openFetchStream()
+  }
+
+  disconnectedCallback() {
+    this.closed = true
+    disconnectStreamSource(this)
+    this.teardown()
+  }
+
+  teardown() {
+    if (this.abortController) {
+      this.abortController.abort()
+      this.abortController = null
+    }
+    if (this.eventSource) {
+      this.eventSource.close()
+      this.eventSource = null
+    }
+  }
+
+  // First connect: use fetch() so we can include ?since=<watermark> on
+  // the URL. Parses the SSE event stream by hand because EventSource
+  // doesn't expose custom query strings uniformly across browsers.
+  async openFetchStream() {
+    const url = this.buildUrl({ includeSince: true })
+    this.abortController = new AbortController()
+
+    try {
+      const response = await fetch(url, {
+        headers: { Accept: "text/event-stream" },
+        credentials: "same-origin",
+        signal: this.abortController.signal
+      })
+
+      if (!response.ok) {
+        this.dispatchEvent(new CustomEvent("pgbus:close", {
+          detail: { code: response.status, reason: response.statusText }
+        }))
+        return
+      }
+
+      this.setAttribute("connected", "")
+      this.dispatchEvent(new CustomEvent("pgbus:open", {
+        detail: { lastEventId: this.lastEventId }
+      }))
+
+      const reader = response.body.getReader()
+      const decoder = new TextDecoder("utf-8")
+      let buffer = ""
+
+      while (!this.closed) {
+        const { value, done } = await reader.read()
+        if (done) break
+
+        buffer += decoder.decode(value, { stream: true })
+        const events = buffer.split("\n\n")
+        buffer = events.pop() // last chunk may be incomplete
+
+        for (const block of events) {
+          this.handleBlock(block)
+        }
+      }
+    } catch (err) {
+      if (err.name !== "AbortError") {
+        this.removeAttribute("connected")
+        // Fall through to reconnect via native EventSource, which
+        // will carry Last-Event-ID from this.lastEventId forward.
+        this.switchToEventSource()
+      }
+    }
+  }
+
+  // Reconnect path: native EventSource with Last-Event-ID baked into
+  // the initial handshake by the browser.
+  switchToEventSource() {
+    if (this.closed) return
+
+    const url = this.buildUrl({ includeSince: false })
+    this.eventSource = new EventSource(url, { withCredentials: true })
+
+    this.eventSource.addEventListener("open", () => {
+      this.setAttribute("connected", "")
+      this.dispatchEvent(new CustomEvent("pgbus:open", {
+        detail: { lastEventId: this.lastEventId }
+      }))
+    })
+
+    this.eventSource.addEventListener("error", () => {
+      this.removeAttribute("connected")
+    })
+
+    this.eventSource.addEventListener("turbo-stream", (event) => {
+      this.lastEventId = event.lastEventId
+      this.dispatchEvent(new MessageEvent("message", { data: event.data }))
+    })
+
+    this.eventSource.addEventListener("pgbus:gap-detected", (event) => {
+      const detail = this.safeJsonParse(event.data)
+      this.dispatchEvent(new CustomEvent("pgbus:gap-detected", { detail }))
+    })
+
+    this.eventSource.addEventListener("pgbus:shutdown", () => {
+      this.dispatchEvent(new CustomEvent("pgbus:close", {
+        detail: { code: "shutdown", reason: "worker restart" }
+      }))
+    })
+  }
+
+  // Parses a single SSE event block (: comment | id: ... | event: ... | data: ...)
+  handleBlock(block) {
+    if (!block || block.startsWith(":")) return // comment
+
+    let id = null
+    let event = "message"
+    let data = ""
+
+    for (const line of block.split("\n")) {
+      if (line.startsWith("id:")) id = line.slice(3).trim()
+      else if (line.startsWith("event:")) event = line.slice(6).trim()
+      else if (line.startsWith("data:")) data += line.slice(5).trim()
+    }
+
+    if (id !== null) this.lastEventId = id
+
+    if (event === "turbo-stream") {
+      this.dispatchEvent(new MessageEvent("message", { data }))
+    } else if (event === "pgbus:gap-detected") {
+      this.dispatchEvent(new CustomEvent("pgbus:gap-detected", {
+        detail: this.safeJsonParse(data)
+      }))
+    } else if (event === "pgbus:shutdown") {
+      this.dispatchEvent(new CustomEvent("pgbus:close", {
+        detail: { code: "shutdown", reason: "worker restart" }
+      }))
+    }
+  }
+
+  buildUrl({ includeSince }) {
+    const src = this.getAttribute("src")
+    if (!includeSince || !this.lastEventId) return src
+
+    const url = new URL(src, window.location.origin)
+    url.searchParams.set("since", this.lastEventId)
+    return url.toString()
+  }
+
+  safeJsonParse(str) {
+    try { return JSON.parse(str) } catch { return null }
+  }
+}
+
+if (!customElements.get("pgbus-stream-source")) {
+  customElements.define("pgbus-stream-source", PgbusStreamSourceElement)
+}
+
+export { PgbusStreamSourceElement }