pgbus 0.5.1 → 0.6.0

data/app/models/pgbus/stream_stat.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Pgbus
+  # Records one row per stream event (broadcast / connect / disconnect)
+  # when `config.streams_stats_enabled` is true. Mirrors JobStat in
+  # shape and aggregation API so the Insights controller can query
+  # both with the same patterns.
+  #
+  # Writes are fire-and-forget: any error is swallowed so a stat
+  # recording failure cannot affect the dispatcher's hot path.
+  class StreamStat < BusRecord
+    self.table_name = "pgbus_stream_stats"
+
+    EVENT_TYPES = %w[broadcast connect disconnect].freeze
+
+    scope :since, ->(time) { where("created_at >= ?", time) }
+    scope :broadcasts, -> { where(event_type: "broadcast") }
+    scope :connects, -> { where(event_type: "connect") }
+    scope :disconnects, -> { where(event_type: "disconnect") }
+
+    # Records a stream event. Called from the Dispatcher when the
+    # `streams_stats_enabled` flag is set. Errors are swallowed so a
+    # missing table or a connection blip cannot kill the dispatcher.
+    def self.record!(stream_name:, event_type:, duration_ms: 0, fanout: nil)
+      return unless table_exists?
+
+      create!(
+        stream_name: stream_name,
+        event_type: event_type,
+        duration_ms: duration_ms.to_i,
+        fanout: fanout
+      )
+    rescue StandardError => e
+      Pgbus.logger.debug { "[Pgbus] Failed to record stream stat: #{e.message}" }
+    end
+
+    # Memoized — intentionally never invalidated at runtime. If the
+    # pgbus_stream_stats migration runs while the app is already
+    # running, a restart is required for stat recording to begin.
+    #
+    # We only memoize a *successful* probe. A transient error (PG
+    # hiccup during boot, connection refused during a failover) is
+    # treated as "don't know yet" — the next call retries. Caching
+    # false on the first hiccup would permanently disable stream
+    # stats for the process lifetime, which is a worse failure mode
+    # than a few retries.
+    def self.table_exists?
+      return @table_exists if defined?(@table_exists)
+
+      @table_exists = connection.table_exists?(table_name)
+    rescue StandardError => e
+      Pgbus.logger.debug { "[Pgbus] Failed to check stream stat table: #{e.message}" }
+      false
+    end
+
+    # Single-query aggregate summary over the given window.
+    # Returns totals by event type, average fanout for broadcasts,
+    # and an "active" estimate (connects − disconnects in window).
+    def self.summary(minutes: 60)
+      row = since(minutes.minutes.ago).pick(
+        Arel.sql("COUNT(*) FILTER (WHERE event_type = 'broadcast')"),
+        Arel.sql("COUNT(*) FILTER (WHERE event_type = 'connect')"),
+        Arel.sql("COUNT(*) FILTER (WHERE event_type = 'disconnect')"),
+        Arel.sql("ROUND(AVG(fanout) FILTER (WHERE event_type = 'broadcast')::numeric, 1)"),
+        Arel.sql("ROUND(AVG(duration_ms) FILTER (WHERE event_type = 'broadcast')::numeric, 1)"),
+        Arel.sql("ROUND(AVG(duration_ms) FILTER (WHERE event_type = 'connect')::numeric, 1)")
+      )
+
+      {
+        broadcasts: row[0].to_i,
+        connects: row[1].to_i,
+        disconnects: row[2].to_i,
+        active_estimate: [row[1].to_i - row[2].to_i, 0].max,
+        avg_fanout: row[3]&.to_f || 0,
+        avg_broadcast_ms: row[4]&.to_f || 0,
+        avg_connect_ms: row[5]&.to_f || 0
+      }
+    end
+
+    # Top N streams by broadcast count in the window, with avg fanout.
+    def self.top_streams(limit: 10, minutes: 60)
+      broadcasts
+        .since(minutes.minutes.ago)
+        .group(:stream_name)
+        .order(Arel.sql("COUNT(*) DESC"))
+        .limit(limit)
+        .pluck(
+          :stream_name,
+          Arel.sql("COUNT(*)"),
+          Arel.sql("ROUND(AVG(fanout)::numeric, 1)"),
+          Arel.sql("ROUND(AVG(duration_ms)::numeric, 1)")
+        )
+        .map do |name, count, avg_fanout, avg_ms|
+          {
+            stream_name: name,
+            count: count.to_i,
+            avg_fanout: avg_fanout&.to_f || 0,
+            avg_ms: avg_ms&.to_f || 0
+          }
+        end
+    end
+
+    # Throughput: broadcast events per minute bucketed by minute.
+    def self.throughput(minutes: 60)
+      broadcasts
+        .since(minutes.minutes.ago)
+        .group("date_trunc('minute', created_at)")
+        .order(Arel.sql("date_trunc('minute', created_at)"))
+        .count
+    end
+
+    # Cleanup old stats. Called from Pgbus::Process::Dispatcher on the
+    # same cadence as JobStat.cleanup! using the shared stats_retention.
+    def self.cleanup!(older_than:)
+      where("created_at < ?", older_than).delete_all
+    end
+  end
+end

data/app/views/pgbus/insights/show.html.erb

@@ -159,6 +159,65 @@
   </table>
 </div>
 
+<% if @stream_stats_available %>
+<!-- Stream stats -->
+<div class="mt-8">
+  <h2 class="text-lg font-semibold text-gray-900 dark:text-white mb-4"><%= t("pgbus.insights.show.streams.title") %></h2>
+
+  <div class="grid grid-cols-2 gap-4 sm:grid-cols-3 lg:grid-cols-5 mb-6">
+    <div class="rounded-lg bg-white dark:bg-gray-800 p-4 shadow ring-1 ring-gray-200 dark:ring-gray-700">
+      <dt class="text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.insights.show.streams.summary.broadcasts") %></dt>
+      <dd class="mt-1 text-2xl font-semibold text-gray-900 dark:text-white"><%= pgbus_number(@stream_summary[:broadcasts]) %></dd>
+    </div>
+    <div class="rounded-lg bg-white dark:bg-gray-800 p-4 shadow ring-1 ring-gray-200 dark:ring-gray-700">
+      <dt class="text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.insights.show.streams.summary.connects") %></dt>
+      <dd class="mt-1 text-2xl font-semibold text-green-600 dark:text-green-400"><%= pgbus_number(@stream_summary[:connects]) %></dd>
+    </div>
+    <div class="rounded-lg bg-white dark:bg-gray-800 p-4 shadow ring-1 ring-gray-200 dark:ring-gray-700">
+      <dt class="text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.insights.show.streams.summary.disconnects") %></dt>
+      <dd class="mt-1 text-2xl font-semibold text-orange-600 dark:text-orange-400"><%= pgbus_number(@stream_summary[:disconnects]) %></dd>
+    </div>
+    <div class="rounded-lg bg-white dark:bg-gray-800 p-4 shadow ring-1 ring-gray-200 dark:ring-gray-700">
+      <dt class="text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.insights.show.streams.summary.active") %></dt>
+      <dd class="mt-1 text-2xl font-semibold text-gray-900 dark:text-white"><%= pgbus_number(@stream_summary[:active_estimate]) %></dd>
+    </div>
+    <div class="rounded-lg bg-white dark:bg-gray-800 p-4 shadow ring-1 ring-gray-200 dark:ring-gray-700">
+      <dt class="text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.insights.show.streams.summary.avg_fanout") %></dt>
+      <dd class="mt-1 text-2xl font-semibold text-gray-900 dark:text-white"><%= @stream_summary[:avg_fanout]&.round(1) || 0 %></dd>
+    </div>
+  </div>
+
+  <div class="rounded-lg bg-white dark:bg-gray-800 shadow ring-1 ring-gray-200 dark:ring-gray-700">
+    <div class="px-5 py-4 border-b border-gray-200 dark:border-gray-700">
+      <h3 class="text-sm font-medium text-gray-700 dark:text-gray-300"><%= t("pgbus.insights.show.streams.top.title") %></h3>
+    </div>
+    <table class="pgbus-table min-w-full divide-y divide-gray-200 dark:divide-gray-700">
+      <thead class="bg-gray-50 dark:bg-gray-900">
+        <tr>
+          <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.insights.show.streams.top.headers.stream") %></th>
+          <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.insights.show.streams.top.headers.broadcasts") %></th>
+          <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.insights.show.streams.top.headers.avg_fanout") %></th>
+          <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.insights.show.streams.top.headers.avg_ms") %></th>
+        </tr>
+      </thead>
+      <tbody class="divide-y divide-gray-100 dark:divide-gray-700">
+        <% @top_streams.each do |row| %>
+          <tr class="hover:bg-gray-50 dark:hover:bg-gray-700/50">
+            <td data-label="Stream" class="px-4 py-3 text-sm font-medium text-gray-700 dark:text-gray-300"><%= row[:stream_name] %></td>
+            <td data-label="Broadcasts" class="px-4 py-3 text-sm text-right font-mono text-gray-700 dark:text-gray-300"><%= pgbus_number(row[:count]) %></td>
+            <td data-label="Avg Fanout" class="px-4 py-3 text-sm text-right font-mono text-gray-700 dark:text-gray-300"><%= row[:avg_fanout]&.round(1) || 0 %></td>
+            <td data-label="Avg Duration" class="px-4 py-3 text-sm text-right font-mono text-gray-700 dark:text-gray-300"><%= pgbus_ms_duration(row[:avg_ms]) %></td>
+          </tr>
+        <% end %>
+        <% if @top_streams.empty? %>
+          <tr><td colspan="4" class="px-4 py-8 text-center text-sm text-gray-400 dark:text-gray-500"><%= t("pgbus.insights.show.streams.top.empty") %></td></tr>
+        <% end %>
+      </tbody>
+    </table>
+  </div>
+</div>
+<% end %>
+
 <script type="module" nonce="<%= content_security_policy_nonce %>">
   import { renderCharts, observeThemeChanges } from "charts";
 

data/config/locales/en.yml

@@ -161,6 +161,22 @@ en:
             job_class: Job Class
             max: Max
           title: Slowest Job Classes (avg duration)
+        streams:
+          summary:
+            active: Active
+            avg_fanout: Avg Fanout
+            broadcasts: Broadcasts
+            connects: Connects
+            disconnects: Disconnects
+          title: Real-time Streams
+          top:
+            empty: No stream activity recorded in the selected window
+            headers:
+              avg_fanout: Avg Fanout
+              avg_ms: Avg Dispatch
+              broadcasts: Broadcasts
+              stream: Stream
+            title: Top Streams by Broadcast Volume
         summary:
           avg_duration: Avg Duration
           avg_latency: Avg Latency

data/config/routes.rb

@@ -1,6 +1,17 @@
 # frozen_string_literal: true
 
 Pgbus::Engine.routes.draw do
+  # SSE streaming endpoint for the pgbus_stream_from turbo-rails replacement.
+  # Mounted as a bare Rack app so it bypasses the entire Rails middleware
+  # stack — see lib/pgbus/web/stream_app.rb for the rationale. Named with
+  # `as: :streams` so `Pgbus::Engine.routes.url_helpers.streams_path`
+  # resolves to whatever mount point the host app chose for the engine,
+  # not a hardcoded `/pgbus/streams`. The helper under
+  # app/helpers/pgbus/streams_helper.rb appends `/:signed_name` to that
+  # base so the full URL works whether the engine is at /pgbus, /admin,
+  # or anywhere else.
+  mount Pgbus::Web::StreamApp.new => "/streams", as: :streams if Pgbus.configuration.streams_enabled
+
   root to: "dashboard#show"
 
   resources :queues, only: %i[index show destroy], param: :name do

data/lib/generators/pgbus/add_presence_generator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Pgbus
+  module Generators
+    class AddPresenceGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Add presence_members table for Pgbus::Streams presence tracking"
+
+      class_option :database,
+                   type: :string,
+                   default: nil,
+                   desc: "Use a separate database for pgbus tables (e.g. --database=pgbus)"
+
+      def create_migration_file
+        if separate_database?
+          migration_template "add_presence.rb.erb",
+                             "db/pgbus_migrate/add_pgbus_presence.rb"
+        else
+          migration_template "add_presence.rb.erb",
+                             "db/migrate/add_pgbus_presence.rb"
+        end
+      end
+
+      def display_post_install
+        say ""
+        say "Pgbus presence installed!", :green
+        say ""
+        say "Next steps:"
+        say "  1. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"
+        say "  2. Use in your code:"
+        say "       Pgbus.stream(@room).presence.join(member_id: current_user.id.to_s)"
+        say "       Pgbus.stream(@room).presence.members"
+        say "  3. Run a periodic sweeper to expire idle members:"
+        say "       Pgbus.stream(@room).presence.sweep!(older_than: 60.seconds.ago)"
+        say ""
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::Migration.current_version}]"
+      end
+
+      def separate_database?
+        options[:database].present?
+      end
+    end
+  end
+end

data/lib/generators/pgbus/add_stream_stats_generator.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Pgbus
+  module Generators
+    class AddStreamStatsGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Add stream stats table for Insights dashboard (opt-in, disabled by default)"
+
+      class_option :database,
+                   type: :string,
+                   default: nil,
+                   desc: "Use a separate database for pgbus tables (e.g. --database=pgbus)"
+
+      def create_migration_file
+        if separate_database?
+          migration_template "add_stream_stats.rb.erb",
+                             "db/pgbus_migrate/add_pgbus_stream_stats.rb"
+        else
+          migration_template "add_stream_stats.rb.erb",
+                             "db/migrate/add_pgbus_stream_stats.rb"
+        end
+      end
+
+      def display_post_install
+        say ""
+        say "Pgbus stream stats table installed!", :green
+        say ""
+        say "Next steps:"
+        say "  1. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"
+        say "  2. Opt in by setting `config.streams_stats_enabled = true` in your"
+        say "     pgbus initializer (disabled by default — stream event volume can"
+        say "     be high, so stats recording is off unless you ask for it)."
+        say "  3. View stream insights at /pgbus/insights"
+        say ""
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::Migration.current_version}]"
+      end
+
+      def separate_database?
+        options[:database].present?
+      end
+    end
+  end
+end

data/lib/generators/pgbus/templates/add_presence.rb.erb

@@ -0,0 +1,26 @@
+class AddPgbusPresence < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :pgbus_presence_members, id: false do |t|
+      t.string :stream_name, null: false
+      t.string :member_id, null: false
+      t.jsonb :metadata, null: false, default: {}
+      t.datetime :joined_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
+      t.datetime :last_seen_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
+    end
+
+    # Composite primary key (stream_name, member_id) — a member can only
+    # appear once per stream. Used by the upsert path in
+    # Pgbus::Streams::Presence#join.
+    add_index :pgbus_presence_members,
+              %i[stream_name member_id],
+              unique: true,
+              name: "idx_pgbus_presence_members_pk"
+
+    # Sweeping by last_seen_at expires stale members. The Dispatcher's
+    # periodic sweeper queries WHERE stream_name = ? AND last_seen_at < ?,
+    # so this composite index makes that fast.
+    add_index :pgbus_presence_members,
+              %i[stream_name last_seen_at],
+              name: "idx_pgbus_presence_members_sweep"
+  end
+end

data/lib/generators/pgbus/templates/add_stream_stats.rb.erb

@@ -0,0 +1,18 @@
+class AddPgbusStreamStats < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :pgbus_stream_stats do |t|
+      t.string :stream_name, null: false
+      t.string :event_type, null: false # 'broadcast' | 'connect' | 'disconnect'
+      t.integer :duration_ms, null: false, default: 0
+      t.integer :fanout # nil for connect/disconnect
+      t.datetime :created_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
+    end
+
+    add_index :pgbus_stream_stats, :created_at,
+              name: "idx_pgbus_stream_stats_time"
+    add_index :pgbus_stream_stats, %i[stream_name created_at],
+              name: "idx_pgbus_stream_stats_stream_time"
+    add_index :pgbus_stream_stats, %i[event_type created_at],
+              name: "idx_pgbus_stream_stats_type_time"
+  end
+end

data/lib/pgbus/client/ensure_stream_queue.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Client
+    # Idempotent stream-queue setup. Creates the PGMQ queue (delegating to
+    # `ensure_queue` which already handles schema bootstrap and dedup),
+    # overrides the NOTIFY throttle to 0 so every broadcast fires its
+    # own NOTIFY, and adds an `msg_id` index on the archive table that
+    # PGMQ does not ship with.
+    #
+    # PGMQ's archive tables (`pgmq.a_<name>`) only carry an `archived_at`
+    # index by default. `Client#read_after`'s replay query filters by
+    # `WHERE msg_id > $1`, which becomes a sequential scan once the archive
+    # grows past a few thousand rows. We add the index here, scoped to
+    # stream queues only, so users with chat-history-style retention don't
+    # hit a performance cliff.
+    #
+    # Called from `Pgbus.stream(name).broadcast(...)` on first publish per
+    # stream and from the streamer on first subscription per stream.
+    module EnsureStreamQueue
+      def ensure_stream_queue(stream_name)
+        ensure_queue(stream_name)
+        full_name = config.queue_name(stream_name)
+
+        # PGMQ's default NOTIFY throttle is 250ms — meant to coalesce
+        # high-frequency worker queue inserts. Streams are latency-
+        # sensitive and need every broadcast to fire a NOTIFY, even
+        # when several are batched within a single millisecond.
+        # Override the throttle to 0 specifically for stream queues.
+        synchronized { @pgmq.enable_notify_insert(full_name, throttle_interval_ms: 0) } if config.listen_notify
+
+        # CREATE INDEX IF NOT EXISTS is idempotent in Postgres but still
+        # requires a roundtrip and a brief ACCESS SHARE lock on the archive
+        # table. Broadcast-per-after_commit loops can hit this 1000x/sec on
+        # the same stream, so memoize per-process after the first success.
+        return if @stream_indexes_created[stream_name]
+
+        sanitized = QueueNameValidator.sanitize!(full_name)
+        sql = <<~SQL
+          CREATE INDEX IF NOT EXISTS a_#{sanitized}_msg_id_idx
+          ON pgmq.a_#{sanitized} (msg_id)
+        SQL
+
+        synchronized do
+          with_raw_connection do |conn|
+            conn.exec(sql)
+          end
+        end
+
+        @stream_indexes_created[stream_name] = true
+      end
+    end
+  end
+end

data/lib/pgbus/client/read_after.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Client
+    # Non-consuming peek across PGMQ live (`q_`) and archive (`a_`) tables. Used
+    # exclusively by `Pgbus::Web::Streamer` for SSE replay — workers continue to
+    # use `read_batch` (claim semantics). The two read paths are disjoint.
+    #
+    # The cursor is the highest msg_id the client has already seen. Replay returns
+    # everything strictly greater, ordered by msg_id ASC, capped by `limit`.
+    module ReadAfter
+      Envelope = Data.define(:msg_id, :enqueued_at, :payload, :source)
+
+      DEFAULT_LIMIT = 500
+
+      def read_after(stream_name, after_id:, limit: DEFAULT_LIMIT)
+        sanitized = sanitized_queue(stream_name)
+        sql = build_read_after_sql(sanitized)
+
+        rows = synchronized do
+          with_raw_connection do |conn|
+            conn.exec_params(sql, [after_id.to_i, limit.to_i]).to_a
+          end
+        end
+
+        rows.map { |row| build_envelope(row) }
+      end
+
+      def stream_current_msg_id(stream_name)
+        sanitized = sanitized_queue(stream_name)
+        sql = "SELECT COALESCE(MAX(msg_id), 0) AS max FROM pgmq.q_#{sanitized}"
+        synchronized do
+          with_raw_connection do |conn|
+            conn.exec(sql).first.fetch("max").to_i
+          end
+        end
+      end
+
+      def stream_oldest_msg_id(stream_name)
+        sanitized = sanitized_queue(stream_name)
+        sql = <<~SQL
+          SELECT LEAST(
+            (SELECT MIN(msg_id) FROM pgmq.q_#{sanitized}),
+            (SELECT MIN(msg_id) FROM pgmq.a_#{sanitized})
+          ) AS least
+        SQL
+        synchronized do
+          with_raw_connection do |conn|
+            value = conn.exec(sql).first.fetch("least")
+            value&.to_i
+          end
+        end
+      end
+
+      private
+
+      # Builds the union of live and archive tables. The outer ORDER BY + LIMIT
+      # ensures we never return more than `limit` rows total even if both
+      # subqueries hit it. The 'live'/'archive' constants are how the streamer
+      # tells whether a row was peeked from the queue or replayed from history;
+      # the streamer doesn't currently distinguish them, but we keep the column
+      # so debugging is straightforward when archive replay misbehaves.
+      def build_read_after_sql(sanitized)
+        <<~SQL
+          (
+            SELECT msg_id, enqueued_at, message, 'live'::text AS source
+            FROM pgmq.q_#{sanitized}
+            WHERE msg_id > $1
+            ORDER BY msg_id ASC
+            LIMIT $2
+          )
+          UNION ALL
+          (
+            SELECT msg_id, enqueued_at, message, 'archive'::text AS source
+            FROM pgmq.a_#{sanitized}
+            WHERE msg_id > $1
+            ORDER BY msg_id ASC
+            LIMIT $2
+          )
+          ORDER BY msg_id ASC
+          LIMIT $2
+        SQL
+      end
+
+      def sanitized_queue(stream_name)
+        full = config.queue_name(stream_name)
+        QueueNameValidator.sanitize!(full)
+      end
+
+      def build_envelope(row)
+        Envelope.new(
+          msg_id: row.fetch("msg_id").to_i,
+          enqueued_at: row.fetch("enqueued_at"),
+          payload: row.fetch("message"),
+          source: row.fetch("source")
+        )
+      end
+    end
+  end
+end

data/lib/pgbus/client.rb

@@ -1,9 +1,14 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "client/read_after"
+require_relative "client/ensure_stream_queue"
 
 module Pgbus
   class Client
+    include ReadAfter
+    include EnsureStreamQueue
+
     attr_reader :pgmq, :config
 
     PGMQ_REQUIRE_MUTEX = Mutex.new
@@ -49,6 +54,7 @@ module Pgbus
       end
 
       @queues_created = Concurrent::Map.new
+      @stream_indexes_created = Concurrent::Map.new
       @queue_strategy = QueueFactory.for(config)
       @schema_ensured = false
     end

data/lib/pgbus/configuration.rb

@@ -84,6 +84,13 @@ module Pgbus
     attr_accessor :web_auth, :web_refresh_interval, :web_per_page, :web_live_updates, :web_data_source,
                   :insights_default_minutes, :base_controller_class, :return_to_app_url
 
+    # Streams (turbo-rails replacement, SSE-based)
+    attr_accessor :streams_enabled, :streams_queue_prefix, :streams_signed_name_secret,
+                  :streams_default_retention, :streams_retention, :streams_heartbeat_interval,
+                  :streams_max_connections, :streams_idle_timeout, :streams_listen_health_check_ms,
+                  :streams_write_deadline_ms, :streams_falcon_streaming_body,
+                  :streams_stats_enabled
+
     def initialize
       @database_url = nil
       @connection_params = nil
@@ -150,6 +157,34 @@ module Pgbus
       @insights_default_minutes = 30 * 24 * 60 # 30 days
       @base_controller_class = "::ActionController::Base"
       @return_to_app_url = nil
+
+      @streams_enabled = true
+      @streams_queue_prefix = "pgbus_stream"
+      @streams_signed_name_secret = nil
+      @streams_default_retention = 5 * 60 # 5 minutes
+      @streams_retention = {}
+      @streams_heartbeat_interval = 15
+      @streams_max_connections = 2_000
+      @streams_idle_timeout = 3_600 # 1 hour
+      # 250ms — this value plays two roles: (1) the TCP keepalive
+      # interval for the streamer's PG LISTEN connection, and (2) the
+      # upper bound on how long Dispatcher#handle_connect waits for
+      # the Listener to acknowledge a synchronous ensure_listening
+      # call. 5s was unbounded enough to drop messages on a
+      # realistic subscribe burst; 250ms keeps the connect-path race
+      # window tight while still leaving headroom over a typical
+      # PG keepalive interval.
+      @streams_listen_health_check_ms = 250
+      @streams_write_deadline_ms = 5_000
+      @streams_falcon_streaming_body = false
+      # Opt-in: when true, the Dispatcher writes one row to
+      # pgbus_stream_stats per broadcast/connect/disconnect. Default
+      # off because stream event volume can be much higher than job
+      # volume and the Insights surface is only useful if operators
+      # actually look at it. Separate from #stats_enabled (which
+      # gates pgbus_job_stats recording) on purpose — operators
+      # usually want job stats on and stream stats off, or vice versa.
+      @streams_stats_enabled = false
     end
 
     def queue_name(name)
@@ -208,9 +243,39 @@ module Pgbus
         raise ArgumentError, "insights_default_minutes must be a positive integer"
       end
 
+      validate_streams!
+
       self
     end
 
+    def validate_streams!
+      unless streams_default_retention.is_a?(Numeric) && streams_default_retention >= 0
+        raise ArgumentError, "streams_default_retention must be a non-negative number"
+      end
+
+      unless streams_max_connections.is_a?(Integer) && streams_max_connections.positive?
+        raise ArgumentError, "streams_max_connections must be a positive integer"
+      end
+
+      unless streams_heartbeat_interval.is_a?(Numeric) && streams_heartbeat_interval.positive?
+        raise ArgumentError, "streams_heartbeat_interval must be a positive number"
+      end
+
+      unless streams_idle_timeout.is_a?(Numeric) && streams_idle_timeout.positive?
+        raise ArgumentError, "streams_idle_timeout must be a positive number"
+      end
+
+      unless streams_listen_health_check_ms.is_a?(Integer) && streams_listen_health_check_ms.positive?
+        raise ArgumentError, "streams_listen_health_check_ms must be a positive integer"
+      end
+
+      unless streams_write_deadline_ms.is_a?(Integer) && streams_write_deadline_ms.positive?
+        raise ArgumentError, "streams_write_deadline_ms must be a positive integer"
+      end
+
+      raise ArgumentError, "streams_retention must be a Hash" unless streams_retention.is_a?(Hash)
+    end
+
     # Set the worker capsule list. Accepts:
     #
     #   String — parsed via Pgbus::Configuration::CapsuleDSL into capsules