pgbus 0.17.2 → 0.18.0

data/app/views/layouts/pgbus/application.html.erb

@@ -86,7 +86,6 @@
   <%# Importmap for ES modules — keys are internal symbols, values are app-controlled paths, no user input %>
   <% importmaps = Pgbus::FrontendsController.js_modules.keys.index_with { |mod| frontend_module_path(mod, format: :js, locale: nil) } %>
   <%= tag.script({ imports: importmaps }.to_json.html_safe, type: "importmap", nonce: content_security_policy_nonce) %> <%# herb:disable erb-no-unsafe-raw %>
-  <%= tag.script("", src: frontend_static_path(:apexcharts, format: :js, locale: nil), nonce: content_security_policy_nonce) %>
 
   <script type="module" nonce="<%= content_security_policy_nonce %>">
     import "application";

data/config/routes.rb

@@ -99,7 +99,7 @@ Pgbus::Engine.routes.draw do
   end
 
   scope :frontend, controller: :frontends, defaults: { version: Pgbus::VERSION.tr(".", "-") } do
-    get "modules/:version/:id", action: :module, as: :frontend_module, constraints: { format: "js" }
+    get "modules/:version/:id", action: :module, as: :frontend_module, constraints: { format: /js|map/ }
     get "static/:version/:id", action: :static, as: :frontend_static
   end
 end

data/lib/generators/pgbus/add_presence_generator.rb

@@ -33,7 +33,8 @@ module Pgbus
         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 "  3. Connection-driven presence (streams_presence_patterns) expires silent"
+        say "     seats on its own. Rows you join by member_id need a periodic sweeper:"
         say "       Pgbus.stream(@room).presence.sweep!(older_than: 60.seconds.ago)"
         say ""
       end

data/lib/generators/pgbus/add_presence_seats_generator.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+require_relative "migration_path"
+
+module Pgbus
+  module Generators
+    class AddPresenceSeatsGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+      include MigrationPath
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Add per-connection seats (connection_id, seat, state) to pgbus_presence_members"
+
+      class_option :database,
+                   type: :string,
+                   default: nil,
+                   desc: "Use a separate database for pgbus tables (e.g. --database=pgbus)"
+
+      def create_migration_file
+        migration_template "add_presence_seats.rb.erb",
+                           File.join(pgbus_migrate_path, "add_pgbus_presence_seats.rb")
+      end
+
+      def display_post_install
+        say ""
+        say "Pgbus presence seats installed!", :green
+        say ""
+        say "Next steps:"
+        say "  1. Run: rails db:migrate#{migrate_command_suffix}"
+        say "  2. Restart the app: connection-driven presence (streams_presence_patterns)"
+        say "     then keeps one row per SSE connection, expired after streams_presence_ttl"
+        say ""
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::Migration.current_version}]"
+      end
+    end
+  end
+end

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

@@ -4,23 +4,48 @@ class AddPgbusPresence < ActiveRecord::Migration<%= migration_version %>
       t.string :stream_name, null: false
       t.string :member_id, null: false
       t.jsonb :metadata, null: false, default: {}
+      # One row per SSE connection for connection-driven presence (seats).
+      # NULL for rows written by member-keyed join/leave calls.
+      t.string :connection_id
+      # The client's per-tab id (sent by <pgbus-stream-source presence> as ?seat=).
+      t.string :seat
+      # Ephemeral per-seat state, written by Presence#set_state.
+      t.jsonb :state, 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.
+    # A member-keyed row (no connection) appears once per stream. Upsert
+    # target of Pgbus::Streams::Presence#join(member_id:).
     add_index :pgbus_presence_members,
               %i[stream_name member_id],
               unique: true,
-              name: "idx_pgbus_presence_members_pk"
+              where: "connection_id IS NULL",
+              name: "idx_pgbus_presence_members_member_key"
 
-    # 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.
+    # A seat row appears once per connection. Upsert target of
+    # Pgbus::Streams::Presence#join(connection_id:).
+    add_index :pgbus_presence_members,
+              %i[stream_name connection_id],
+              unique: true,
+              where: "connection_id IS NOT NULL",
+              name: "idx_pgbus_presence_members_connection_key"
+
+    # All rows of one member (several tabs) on a stream.
+    add_index :pgbus_presence_members,
+              %i[stream_name member_id],
+              name: "idx_pgbus_presence_members_member"
+
+    # Sweeping by last_seen_at expires stale members:
+    # WHERE stream_name = ? AND last_seen_at < ?
     add_index :pgbus_presence_members,
               %i[stream_name last_seen_at],
               name: "idx_pgbus_presence_members_sweep"
+
+    # The streamer heartbeat expires silent seats across every stream.
+    add_index :pgbus_presence_members,
+              :last_seen_at,
+              where: "connection_id IS NOT NULL",
+              name: "idx_pgbus_presence_members_seat_expiry"
   end
 end

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

@@ -0,0 +1,38 @@
+class AddPgbusPresenceSeats < ActiveRecord::Migration<%= migration_version %>
+  def up
+    add_column :pgbus_presence_members, :connection_id, :string
+    add_column :pgbus_presence_members, :seat, :string
+    add_column :pgbus_presence_members, :state, :jsonb, null: false, default: {}
+
+    # Existing rows are member-keyed (connection_id IS NULL) and keep their
+    # one-row-per-member key; seat rows get one row per connection.
+    remove_index :pgbus_presence_members, name: "idx_pgbus_presence_members_pk"
+    add_index :pgbus_presence_members, %i[stream_name member_id],
+              unique: true, where: "connection_id IS NULL",
+              name: "idx_pgbus_presence_members_member_key"
+    add_index :pgbus_presence_members, %i[stream_name connection_id],
+              unique: true, where: "connection_id IS NOT NULL",
+              name: "idx_pgbus_presence_members_connection_key"
+    add_index :pgbus_presence_members, %i[stream_name member_id],
+              name: "idx_pgbus_presence_members_member"
+    add_index :pgbus_presence_members, :last_seen_at,
+              where: "connection_id IS NOT NULL",
+              name: "idx_pgbus_presence_members_seat_expiry"
+  end
+
+  def down
+    # Seat rows cannot satisfy the old one-row-per-member key.
+    execute "DELETE FROM pgbus_presence_members WHERE connection_id IS NOT NULL"
+
+    remove_index :pgbus_presence_members, name: "idx_pgbus_presence_members_seat_expiry"
+    remove_index :pgbus_presence_members, name: "idx_pgbus_presence_members_member"
+    remove_index :pgbus_presence_members, name: "idx_pgbus_presence_members_connection_key"
+    remove_index :pgbus_presence_members, name: "idx_pgbus_presence_members_member_key"
+    add_index :pgbus_presence_members, %i[stream_name member_id],
+              unique: true, name: "idx_pgbus_presence_members_pk"
+
+    remove_column :pgbus_presence_members, :state
+    remove_column :pgbus_presence_members, :seat
+    remove_column :pgbus_presence_members, :connection_id
+  end
+end

data/lib/pgbus/configuration/presence_settings.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Configuration
+    # Seat expiry and the change hook for connection-driven presence
+    # (issue #515). EXPERIMENTAL, like the other streams_presence_* settings.
+    #
+    #   config.streams_presence_ttl = 60                                   # every stream
+    #   config.streams_presence_ttl = { /^doc:/ => 5.minutes, default: 60 } # per pattern
+    #   config.streams_presence_on_change = ->(stream_name, change) { ... }
+    #
+    # `change` is { type: :join | :leave, connection_id:, seat:, member_id: }.
+    # An expired seat is reported as a :leave.
+    module PresenceSettings
+      DEFAULT_PRESENCE_TTL = 60
+
+      attr_accessor :streams_presence_on_change
+      attr_writer :streams_presence_ttl
+
+      def streams_presence_ttl
+        @streams_presence_ttl.nil? ? DEFAULT_PRESENCE_TTL : @streams_presence_ttl
+      end
+
+      # Seconds a seat may stay silent on `stream_name` before the heartbeat
+      # expires it. A pattern matches like streams_presence_patterns (exact
+      # String or Regexp); the first match wins.
+      def presence_ttl_for(stream_name)
+        ttl = streams_presence_ttl
+        return presence_seconds(ttl) unless ttl.is_a?(Hash)
+
+        match = ttl.find { |pattern, _| pattern_matches?(pattern, stream_name) }
+        presence_seconds(match ? match.last : ttl.fetch(:default, DEFAULT_PRESENCE_TTL))
+      end
+
+      # The smallest ttl configured: the expiry scan's candidate cutoff.
+      def presence_min_ttl
+        ttl = streams_presence_ttl
+        return presence_seconds(ttl) unless ttl.is_a?(Hash)
+
+        [*ttl.values, ttl.fetch(:default, DEFAULT_PRESENCE_TTL)].map { |v| presence_seconds(v) }.min
+      end
+
+      # Reports one join, leave or expiry to streams_presence_on_change.
+      # A raising hook is logged and swallowed, like the rest of the
+      # presence path: it must not break a connection or a sweep.
+      def notify_presence_change(stream_name, change)
+        hook = streams_presence_on_change
+        return unless hook
+
+        hook.call(stream_name, change)
+      rescue StandardError => e
+        Pgbus.logger.error do
+          "[Pgbus] streams_presence_on_change raised for #{stream_name}: #{e.class}: #{e.message}"
+        end
+      end
+
+      private
+
+      def validate_presence_settings!
+        if !streams_presence_on_change.nil? && !streams_presence_on_change.respond_to?(:call)
+          raise Pgbus::ConfigurationError,
+                "streams_presence_on_change must respond to #call (a Proc/lambda) or be nil"
+        end
+
+        ttl = streams_presence_ttl
+        values = ttl.is_a?(Hash) ? ttl.values : [ttl]
+        unless values.all? { |v| v.is_a?(Numeric) && v.to_f.positive? }
+          raise Pgbus::ConfigurationError,
+                "streams_presence_ttl must be a positive number of seconds or a Hash of pattern => seconds"
+        end
+
+        warn_presence_ttl_below_heartbeat
+      end
+
+      # A ttl at or below the heartbeat interval lets another process expire
+      # live seats between touches, so every tick reports a leave and a join.
+      def warn_presence_ttl_below_heartbeat
+        heartbeat = streams_heartbeat_interval
+        return unless heartbeat.is_a?(Numeric) && presence_min_ttl <= heartbeat
+
+        Pgbus.logger.warn do
+          "[Pgbus] streams_presence_ttl (#{presence_min_ttl}s) should exceed streams_heartbeat_interval " \
+            "(#{heartbeat}s), or live presence seats are expired and re-joined every tick"
+        end
+      end
+
+      # Seconds as an Integer when whole, a Float otherwise (a Duration
+      # becomes plain seconds), so fractional ttls are not truncated.
+      def presence_seconds(value)
+        seconds = value.to_f
+        seconds == seconds.floor ? seconds.to_i : seconds
+      end
+
+      def pattern_matches?(pattern, stream_name)
+        case pattern
+        when Regexp then pattern.match?(stream_name)
+        when :default then false
+        else pattern.to_s == stream_name
+        end
+      end
+    end
+  end
+end

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

@@ -4,6 +4,9 @@ require "logger"
 
 module Pgbus
   class Configuration
+    include PresenceSettings
+    include StreamAuthorization
+
     # Connection settings
     attr_accessor :database_url, :connection_params, :pool_size, :pool_timeout
 
@@ -215,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,
@@ -459,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
@@ -1026,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
@@ -1093,6 +1105,9 @@ module Pgbus
         raise Pgbus::ConfigurationError, "streams_presence_member must respond to #call (a Proc/lambda) or be nil"
       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/engine.rb

@@ -139,14 +139,20 @@ module Pgbus
       app.middleware.use Pgbus::Streams::WatermarkCacheMiddleware if Pgbus.configuration.streams_enabled
     end
 
-    # Make stream_source_element.js available to the host app's asset
-    # pipeline (Propshaft or Sprockets) so it can be included via
-    # `javascript_include_tag "pgbus/stream_source_element"` or pinned
-    # in importmap. When importmap-rails is loaded, auto-pin it so
-    # host apps get it without manual configuration.
+    # Make the <pgbus-stream-source> element available to the host app's
+    # asset pipeline (Propshaft or Sprockets). The importmap pin points at
+    # the minified build (rake frontend:js). Propshaft rewrites its
+    # sourceMappingURL to the digested .min.js.map; Sprockets serves the
+    # comment as written. The readable ES module source stays precompiled for
+    # apps that pin or bundle it themselves. When importmap-rails is loaded,
+    # auto-pin it so host apps get it without manual configuration.
     initializer "pgbus.streams.assets" do |app|
       if Pgbus.configuration.streams_enabled && app.config.respond_to?(:assets)
-        app.config.assets.precompile += %w[pgbus/stream_source_element.js]
+        app.config.assets.precompile += %w[
+          pgbus/stream_source_element.min.js
+          pgbus/stream_source_element.min.js.map
+          pgbus/stream_source_element.js
+        ]
       end
     end
 
@@ -156,7 +162,7 @@ module Pgbus
           next unless Rails.application.respond_to?(:importmap)
 
           Rails.application.importmap.pin(
-            "pgbus/stream_source_element", to: "pgbus/stream_source_element.js"
+            "pgbus/stream_source_element", to: "pgbus/stream_source_element.min.js"
           )
         end
       end

data/lib/pgbus/generators/migration_detector.rb

@@ -73,6 +73,7 @@ module Pgbus
         add_stream_stats: "pgbus:add_stream_stats",
         add_stream_queues: "pgbus:add_stream_queues",
         add_presence: "pgbus:add_presence",
+        add_presence_seats: "pgbus:add_presence_seats",
         add_queue_states: "pgbus:add_queue_states",
         add_outbox: "pgbus:add_outbox",
         add_recurring: "pgbus:add_recurring",
@@ -94,6 +95,7 @@ module Pgbus
         add_stream_stats: "stream stats table (opt-in real-time Insights)",
         add_stream_queues: "stream queue registry (per-stream retention, orphan sweep, wildcard-worker safety)",
         add_presence: "presence members table (Turbo Streams presence)",
+        add_presence_seats: "presence seats (one row per SSE connection, per-seat state)",
         add_queue_states: "queue states table (pause/resume)",
         add_outbox: "outbox entries table (transactional outbox)",
         add_recurring: "recurring tasks + executions tables",
@@ -182,8 +184,14 @@ module Pgbus
         table_exists?("pgbus_stream_queues") ? [] : [:add_stream_queues]
       end
 
+      # The add_presence template already carries the seat columns, so a
+      # missing table needs only that; an existing table without
+      # connection_id predates seats (issue #515).
       def presence_migrations
-        table_exists?("pgbus_presence_members") ? [] : [:add_presence]
+        return [:add_presence] unless table_exists?("pgbus_presence_members")
+        return [] if column_names("pgbus_presence_members").include?("connection_id")
+
+        [:add_presence_seats]
       end
 
       def queue_states_migrations

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