pgbus 0.17.2 → 0.17.3

data/lib/pgbus/streams/presence.rb

@@ -35,26 +35,230 @@ module Pgbus
     # stream pipeline, which means it's transactional, replayable, and
     # filterable just like any other broadcast.
     #
-    # NOT included in this v1:
-    #   - Automatic connection-driven join/leave (the application must
-    #     call join/leave explicitly).
-    #   - Automatic stale-member sweeping (call Presence.sweep!(stream)
-    #     from a cron or after a heartbeat to expire idle members).
+    # Seats (issue #515). A table migrated with `pgbus:add_presence_seats`
+    # also keeps one row per SSE connection: `connection_id` (part of the
+    # key), `seat` (the client's per-tab id, sent as `?seat=`) and a
+    # `state` jsonb for ephemeral per-tab state. Connection-driven presence
+    # (`streams_presence_patterns`) writes those rows, so two tabs of one
+    # user are two rows and the user stays present until both are gone.
+    # Member-keyed calls (no `connection_id:`) keep working on their own
+    # row (connection_id IS NULL), exactly as before.
+    #
+    #   presence.join(member_id: "7", connection_id: conn_id, seat: seat)
+    #   presence.set_state(connection_id: conn_id, state: { selected: 3 })
+    #   presence.leave(connection_id: conn_id)
+    #
+    # Seat rows are expired by the streamer heartbeat after their stream's
+    # ttl (`Pgbus.configuration.presence_ttl_for`) and every join, leave
+    # and expiry is reported through `streams_presence_on_change`.
+    #
+    # Capability probe for a library building on seats:
+    #   Pgbus::Streams::Presence.instance_method(:join).parameters
+    #     .include?([:key, :connection_id])   # the gem has seats
+    #   Pgbus::Streams::Presence.seats_supported?  # the table is migrated
+    #
+    # NOT included:
     #   - Built-in DOM events on the <pgbus-stream-source> element
     #     (the application's broadcast block decides the HTML).
+    #   - Expiry of member-keyed rows (call #sweep! from a cron for those).
     class Presence
+      RECORD_COLUMNS = "member_id, metadata, joined_at, last_seen_at"
+      SEAT_RECORD_COLUMNS = "member_id, metadata, joined_at, last_seen_at, connection_id, seat, state"
+
+      # How long a "no seats" answer is trusted before the schema is probed
+      # again, so a table migrated under a running process is picked up.
+      SCHEMA_RECHECK_SECONDS = 30
+
+      @schema_mutex = Mutex.new
+      @seats_supported = nil
+      @probed_at = nil
+
+      class << self
+        # True when pgbus_presence_members has the seat columns (the
+        # add_presence_seats migration ran). A true answer is kept for the
+        # life of the process; a false one for SCHEMA_RECHECK_SECONDS.
+        def seats_supported?
+          return @seats_supported if schema_answer_fresh?
+
+          @schema_mutex.synchronize do
+            next @seats_supported if schema_answer_fresh?
+
+            rows = connection.exec_params(<<~SQL, [])
+              SELECT 1 AS present FROM information_schema.columns
+              WHERE table_name = 'pgbus_presence_members' AND column_name = 'connection_id'
+                AND table_schema = ANY (current_schemas(false))
+            SQL
+            @probed_at = monotonic_now
+            @seats_supported = !rows.to_a.empty?
+          end
+        end
+
+        # seats_supported?, but a cached "no seats" is probed again first.
+        # For the destructive member-keyed statements: on a table migrated
+        # under this process their SQL without `connection_id IS NULL`
+        # succeeds silently and deletes seat rows.
+        def seats_supported_now?
+          return true if seats_supported?
+
+          reset_schema_cache!
+          seats_supported?
+        end
+
+        def reset_schema_cache!
+          @schema_mutex.synchronize do
+            @probed_at = nil
+            @seats_supported = nil
+          end
+        end
+
+        # Deletes every seat row (connection_id IS NOT NULL) that has not
+        # been touched within its stream's ttl and returns the deleted
+        # records, each with its "stream_name". Member-keyed rows are left
+        # alone. `ttl_for` maps a stream name to seconds; `min_ttl` is the
+        # smallest ttl configured, used to narrow the candidates in SQL.
+        # The DELETE re-checks the cutoff (a touch between the two
+        # statements keeps the row) and claims each row atomically, so
+        # concurrent sweepers in other processes never report a row twice.
+        def expire_seats!(ttl_for:, min_ttl:)
+          return [] unless seats_supported?
+
+          candidates = connection.exec_params(<<~SQL, [min_ttl])
+            SELECT stream_name, connection_id FROM pgbus_presence_members
+            WHERE connection_id IS NOT NULL AND last_seen_at < NOW() - make_interval(secs => $1)
+          SQL
+          candidates.to_a.group_by { |row| row["stream_name"] }.flat_map do |stream_name, rows|
+            expire_stream_seats(stream_name, rows.map { |row| row["connection_id"] }, ttl_for.call(stream_name))
+          end
+        end
+
+        def connection
+          # Respect multi-database setups (connects_to). When
+          # Pgbus.configuration.connects_to is set, the pgbus tables
+          # live in a separate database accessed via Pgbus::BusRecord;
+          # the default path uses ActiveRecord::Base. Matches the
+          # canonical pattern in Pgbus::Process::QueueLock#connection
+          # and Pgbus::Configuration's connection probe.
+          unless defined?(::ActiveRecord::Base)
+            raise Pgbus::ConfigurationError,
+                  "Pgbus::Streams::Presence requires ActiveRecord (no AR connection available)"
+          end
+
+          if Pgbus.configuration.connects_to
+            Pgbus::BusRecord.connection.raw_connection
+          else
+            ::ActiveRecord::Base.connection.raw_connection
+          end
+        end
+
+        # Reports a seat join/leave to streams_presence_on_change (issue #515).
+        def report_change(stream_name, type, record)
+          Pgbus.configuration.notify_presence_change(
+            stream_name,
+            { type: type, connection_id: record["connection_id"], seat: record["seat"], member_id: record["id"] }
+          )
+        end
+
+        # A Ruby Array of Strings as a Postgres text[] literal.
+        def text_array(values)
+          "{#{values.map { |v| %("#{v.to_s.gsub(/["\\]/) { |c| "\\#{c}" }}") }.join(",")}}"
+        end
+
+        def monotonic_now
+          ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+        end
+
+        private
+
+        # Reads each ivar once: a concurrent reset_schema_cache! may nil them.
+        def schema_answer_fresh?
+          supported = @seats_supported
+          probed_at = @probed_at
+          return false if supported.nil? || probed_at.nil?
+
+          supported || monotonic_now - probed_at < SCHEMA_RECHECK_SECONDS
+        end
+
+        def expire_stream_seats(stream_name, connection_ids, ttl)
+          rows = connection.exec_params(<<~SQL, [stream_name, text_array(connection_ids), ttl])
+            DELETE FROM pgbus_presence_members
+            WHERE stream_name = $1 AND connection_id = ANY($2::text[])
+              AND last_seen_at < NOW() - make_interval(secs => $3)
+            RETURNING #{SEAT_RECORD_COLUMNS}
+          SQL
+          rows.to_a.map do |row|
+            record = Record.build(row)
+            report_change(stream_name, :leave, record)
+            record.merge("stream_name" => stream_name)
+          end
+        end
+      end
+
+      # Turns a pgbus_presence_members row into the public record Hash.
+      # Seat columns appear only when the row has them.
+      module Record
+        def self.build(row)
+          record = {
+            "id" => row["member_id"],
+            "metadata" => parse_json(row["metadata"]),
+            "joined_at" => row["joined_at"],
+            "last_seen_at" => row["last_seen_at"]
+          }
+          return record unless row.key?("connection_id")
+
+          record.merge("connection_id" => row["connection_id"], "seat" => row["seat"],
+                       "state" => parse_json(row["state"]))
+        end
+
+        def self.parse_json(value)
+          return value if value.is_a?(Hash)
+          return {} if value.nil? || value.empty?
+
+          JSON.parse(value)
+        rescue JSON::ParserError => e
+          # Resilience fallback: return an empty hash rather than
+          # crashing the presence member list on one corrupt row. Debug
+          # log so operators can still find the corruption without
+          # impacting production throughput (debug is off by default).
+          # Truncate the value so a huge metadata payload doesn't bloat
+          # the log line.
+          truncated = value.to_s[0, 200]
+          Pgbus.logger&.debug do
+            "[Pgbus::Streams::Presence] parse_metadata failed (#{e.class}: #{e.message}); raw: #{truncated.inspect}"
+          end
+          {}
+        end
+      end
+
       def initialize(stream)
         @stream = stream
       end
 
+      # True when the table carries seats (see .seats_supported?).
+      def seats?
+        self.class.seats_supported?
+      end
+
+      # True when the table carries seats, re-probing a cached "no".
+      def seats_now?
+        self.class.seats_supported_now?
+      end
+
       # Adds (or refreshes) a member on this stream. Idempotent: calling
       # join twice with the same member_id updates last_seen_at and
       # metadata without creating a duplicate row. Yields the member
       # hash to the optional block so the caller can render an
       # `<turbo-stream action="append">` to broadcast the join.
-      def join(member_id:, metadata: {})
+      #
+      # With `connection_id:` (seat tables only) the row is the
+      # connection's: one per SSE connection, carrying the client's `seat`.
+      def join(member_id:, metadata: {}, connection_id: nil, seat: nil)
         member_id = member_id.to_s
-        record = upsert_member(member_id, metadata)
+        record = if connection_id
+                   upsert_seat(member_id, metadata, connection_id.to_s, seat&.to_s)
+                 else
+                   upsert_member(member_id, metadata)
+                 end
+        self.class.report_change(@stream.name, :join, record) if connection_id
 
         if block_given?
           html = yield(record)
@@ -67,11 +271,19 @@ module Pgbus
       # Removes a member. Yields the (former) member hash to the
       # optional block so the caller can broadcast a `remove` action.
       # Returns the deleted record, or nil if the member wasn't present.
-      def leave(member_id:)
-        member_id = member_id.to_s
-        record = delete_member(member_id)
+      # Pass `connection_id:` instead to remove one connection's seat row.
+      def leave(member_id: nil, connection_id: nil)
+        record = if connection_id && member_id.nil?
+                   delete_seat(connection_id.to_s)
+                 elsif member_id && connection_id.nil?
+                   delete_member(member_id.to_s)
+                 else
+                   raise ArgumentError, "leave takes exactly one of member_id: or connection_id:"
+                 end
         return nil unless record
 
+        self.class.report_change(@stream.name, :leave, record) if connection_id
+
         if block_given?
           html = yield(record)
           @stream.broadcast(html) if html.is_a?(String) && !html.empty?
@@ -84,32 +296,53 @@ module Pgbus
       # Used as a heartbeat mechanism: clients ping touch periodically
       # to stay in the member list, and a sweeper expires anyone who
       # hasn't pinged in N seconds.
-      def touch(member_id:)
+      #
+      # With `connection_id:` (a String or an Array of them) it refreshes
+      # those connections' seat rows in one statement and returns the ids
+      # it found — a missing id means the row was expired while the
+      # connection was still alive, and the caller can re-join it.
+      def touch(member_id: nil, connection_id: nil)
+        raise ArgumentError, "touch takes exactly one of member_id: or connection_id:" unless member_id.nil? ^ connection_id.nil?
+
+        return touch_seats(Array(connection_id)) if connection_id
+
         member_id = member_id.to_s
         connection.exec_params(<<~SQL, [@stream.name, member_id])
           UPDATE pgbus_presence_members
           SET last_seen_at = NOW()
-          WHERE stream_name = $1 AND member_id = $2
+          WHERE stream_name = $1 AND member_id = $2#{" AND connection_id IS NULL" if seats_now?}
         SQL
       end
 
+      # Merges `state` into one connection's seat row (keys not given keep
+      # their value). Returns the updated record, or nil when the
+      # connection has no row on this stream. Does not broadcast: the
+      # caller renders whatever its viewers should see.
+      def set_state(connection_id:, state:)
+        raise ArgumentError, "set_state takes a Hash (got #{state.class})" unless state.is_a?(Hash)
+
+        rows = connection.exec_params(<<~SQL, [@stream.name, connection_id.to_s, JSON.generate(state)])
+          UPDATE pgbus_presence_members
+          SET state = state || $3::jsonb, last_seen_at = NOW()
+          WHERE stream_name = $1 AND connection_id = $2
+          RETURNING #{SEAT_RECORD_COLUMNS}
+        SQL
+        row = rows.first
+        row && Record.build(row)
+      end
+
       # Returns the current list of members on this stream as an
-      # array of hashes (id, metadata, joined_at, last_seen_at).
+      # array of hashes (id, metadata, joined_at, last_seen_at). On a seat
+      # table each row is one seat and also carries connection_id, seat
+      # and state; group by "id" for one entry per member.
       def members
         rows = connection.exec_params(<<~SQL, [@stream.name])
-          SELECT member_id, metadata, joined_at, last_seen_at
+          SELECT #{seats? ? SEAT_RECORD_COLUMNS : RECORD_COLUMNS}
           FROM pgbus_presence_members
           WHERE stream_name = $1
           ORDER BY joined_at
         SQL
-        rows.to_a.map do |row|
-          {
-            "id" => row["member_id"],
-            "metadata" => parse_metadata(row["metadata"]),
-            "joined_at" => row["joined_at"],
-            "last_seen_at" => row["last_seen_at"]
-          }
-        end
+        rows.to_a.map { |row| Record.build(row) }
       end
 
       # Returns the count of current members. Faster than members.size
@@ -128,88 +361,91 @@ module Pgbus
       #
       # Atomically claims the deletion via DELETE RETURNING so multiple
       # workers running the sweep concurrently won't double-emit leave
-      # events.
+      # events. Yields each expired record when a block is given.
       def sweep!(older_than:)
         rows = connection.exec_params(<<~SQL, [@stream.name, older_than])
           DELETE FROM pgbus_presence_members
-          WHERE stream_name = $1 AND last_seen_at < $2
-          RETURNING member_id, metadata, joined_at, last_seen_at
+          WHERE stream_name = $1 AND last_seen_at < $2#{" AND connection_id IS NULL" if seats_now?}
+          RETURNING #{RECORD_COLUMNS}
         SQL
-        rows.to_a.size
+        rows = rows.to_a
+        rows.each { |row| yield Record.build(row) } if block_given?
+        rows.size
       end
 
       private
 
-      def upsert_member(member_id, metadata)
+      # A process that last probed the pre-seat schema sends the old conflict
+      # target, which Postgres rejects once add_presence_seats has replaced
+      # the unique index with a partial one. Re-probe and retry once.
+      def upsert_member(member_id, metadata, retried: false)
+        upsert_member_once(member_id, metadata)
+      rescue PG::InvalidColumnReference
+        raise if retried
+
+        self.class.reset_schema_cache!
+        upsert_member(member_id, metadata, retried: true)
+      end
+
+      def upsert_member_once(member_id, metadata)
+        conflict = seats? ? "(stream_name, member_id) WHERE connection_id IS NULL" : "(stream_name, member_id)"
         rows = connection.exec_params(<<~SQL, [@stream.name, member_id, JSON.generate(metadata)])
           INSERT INTO pgbus_presence_members (stream_name, member_id, metadata, joined_at, last_seen_at)
           VALUES ($1, $2, $3::jsonb, NOW(), NOW())
-          ON CONFLICT (stream_name, member_id)
+          ON CONFLICT #{conflict}
           DO UPDATE SET metadata = EXCLUDED.metadata, last_seen_at = NOW()
-          RETURNING member_id, metadata, joined_at, last_seen_at
+          RETURNING #{RECORD_COLUMNS}
         SQL
-        row = rows.first
-        {
-          "id" => row["member_id"],
-          "metadata" => parse_metadata(row["metadata"]),
-          "joined_at" => row["joined_at"],
-          "last_seen_at" => row["last_seen_at"]
-        }
+        Record.build(rows.first)
+      end
+
+      def upsert_seat(member_id, metadata, connection_id, seat)
+        rows = connection.exec_params(<<~SQL, [@stream.name, member_id, JSON.generate(metadata), connection_id, seat])
+          INSERT INTO pgbus_presence_members
+            (stream_name, member_id, metadata, connection_id, seat, joined_at, last_seen_at)
+          VALUES ($1, $2, $3::jsonb, $4, $5, NOW(), NOW())
+          ON CONFLICT (stream_name, connection_id) WHERE connection_id IS NOT NULL
+          DO UPDATE SET member_id = EXCLUDED.member_id, metadata = EXCLUDED.metadata,
+                        seat = EXCLUDED.seat, last_seen_at = NOW()
+          RETURNING #{SEAT_RECORD_COLUMNS}
+        SQL
+        Record.build(rows.first)
       end
 
       def delete_member(member_id)
         rows = connection.exec_params(<<~SQL, [@stream.name, member_id])
           DELETE FROM pgbus_presence_members
-          WHERE stream_name = $1 AND member_id = $2
-          RETURNING member_id, metadata, joined_at, last_seen_at
+          WHERE stream_name = $1 AND member_id = $2#{" AND connection_id IS NULL" if seats_now?}
+          RETURNING #{RECORD_COLUMNS}
         SQL
         row = rows.first
-        return nil unless row
-
-        {
-          "id" => row["member_id"],
-          "metadata" => parse_metadata(row["metadata"]),
-          "joined_at" => row["joined_at"],
-          "last_seen_at" => row["last_seen_at"]
-        }
-      end
-
-      def parse_metadata(value)
-        return value if value.is_a?(Hash)
-        return {} if value.nil? || value.empty?
-
-        JSON.parse(value)
-      rescue JSON::ParserError => e
-        # Resilience fallback: return an empty hash rather than
-        # crashing the presence member list on one corrupt row. Debug
-        # log so operators can still find the corruption without
-        # impacting production throughput (debug is off by default).
-        # Truncate the value so a huge metadata payload doesn't bloat
-        # the log line.
-        truncated = value.to_s[0, 200]
-        Pgbus.logger&.debug do
-          "[Pgbus::Streams::Presence] parse_metadata failed (#{e.class}: #{e.message}); raw: #{truncated.inspect}"
-        end
-        {}
+        row && Record.build(row)
       end
 
-      def connection
-        # Respect multi-database setups (connects_to). When
-        # Pgbus.configuration.connects_to is set, the pgbus tables
-        # live in a separate database accessed via Pgbus::BusRecord;
-        # the default path uses ActiveRecord::Base. Matches the
-        # canonical pattern in Pgbus::Process::QueueLock#connection
-        # and Pgbus::Configuration's connection probe.
-        unless defined?(::ActiveRecord::Base)
-          raise Pgbus::ConfigurationError,
-                "Pgbus::Streams::Presence requires ActiveRecord (no AR connection available)"
-        end
+      def delete_seat(connection_id)
+        rows = connection.exec_params(<<~SQL, [@stream.name, connection_id])
+          DELETE FROM pgbus_presence_members
+          WHERE stream_name = $1 AND connection_id = $2
+          RETURNING #{SEAT_RECORD_COLUMNS}
+        SQL
+        row = rows.first
+        row && Record.build(row)
+      end
 
-        if Pgbus.configuration.connects_to
-          Pgbus::BusRecord.connection.raw_connection
-        else
-          ::ActiveRecord::Base.connection.raw_connection
-        end
+      def touch_seats(connection_ids)
+        return [] if connection_ids.empty?
+
+        rows = connection.exec_params(<<~SQL, [@stream.name, self.class.text_array(connection_ids)])
+          UPDATE pgbus_presence_members
+          SET last_seen_at = NOW()
+          WHERE stream_name = $1 AND connection_id = ANY($2::text[])
+          RETURNING connection_id
+        SQL
+        rows.to_a.map { |row| row["connection_id"] }
+      end
+
+      def connection
+        self.class.connection
       end
     end
   end

data/lib/pgbus/version.rb

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

data/lib/pgbus/web/stream_app.rb

@@ -31,6 +31,9 @@ module Pgbus
     # full request lifecycle.
     class StreamApp
       PATH_PREFIX = "/pgbus/streams"
+      # The client's per-tab presence seat (?seat=, issue #515): an opaque id
+      # minted by <pgbus-stream-source presence>. Anything else is dropped.
+      SEAT_FORMAT = /\A[A-Za-z0-9_-]{1,64}\z/
       # EventSource reconnect delay handed to the streams_test_mode stub (24h).
       TEST_MODE_RETRY_MS = 86_400_000
       private_constant :PATH_PREFIX
@@ -64,14 +67,16 @@ module Pgbus
         cursor = parse_cursor(env, request)
         return bad_request("invalid cursor: #{cursor}") if cursor.is_a?(String)
 
+        seat = parse_seat(request)
+
         return test_mode_stub if config.streams_test_mode
 
         return over_capacity if streamer.registry.size >= config.streams_max_connections
 
         if config.streams_falcon_streaming_body
-          streaming_body_response(stream_name: stream_name, since_id: cursor, context: context)
+          streaming_body_response(stream_name: stream_name, since_id: cursor, context: context, seat: seat)
         elsif env["rack.hijack?"]
-          hijack_and_register(env, stream_name: stream_name, since_id: cursor, context: context)
+          hijack_and_register(env, stream_name: stream_name, since_id: cursor, context: context, seat: seat)
         else
           unsupported_server
         end
@@ -114,7 +119,12 @@ module Pgbus
         e.message
       end
 
-      def hijack_and_register(env, stream_name:, since_id:, context: nil)
+      def parse_seat(request)
+        seat = request.params["seat"]
+        seat if seat.is_a?(String) && seat.ascii_only? && SEAT_FORMAT.match?(seat)
+      end
+
+      def hijack_and_register(env, stream_name:, since_id:, context: nil, seat: nil)
         # Rack hijack is a one-time transition per the Rack spec. Call
         # once, use the return value, and fall back to the side-effect
         # `rack.hijack_io` variable only if the return was nil (some
@@ -133,14 +143,15 @@ module Pgbus
           since_id: since_id,
           writer: Pgbus::Web::Streamer::IoWriter,
           write_deadline_ms: config.streams_write_deadline_ms,
-          context: context
+          context: context,
+          seat: seat
         )
         streamer.register(connection)
 
         [-1, {}, []]
       end
 
-      def streaming_body_response(stream_name:, since_id:, context: nil)
+      def streaming_body_response(stream_name:, since_id:, context: nil, seat: nil)
         require "protocol/http/body/writable" unless defined?(::Protocol::HTTP::Body::Writable)
         require_relative "streamer/falcon_connection" unless defined?(Pgbus::Web::Streamer::FalconConnection)
 
@@ -159,7 +170,8 @@ module Pgbus
           body: body,
           since_id: since_id,
           write_deadline_ms: config.streams_write_deadline_ms,
-          context: context
+          context: context,
+          seat: seat
         )
         streamer.register(connection)
 

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

@@ -14,10 +14,15 @@ module Pgbus
       # the client-side leg of the replay-race fix (§6.5 of the design doc).
       class Connection
         attr_reader :id, :stream_name, :io, :mutex, :context
+        # The client's per-tab presence seat (?seat=), or nil (issue #515).
+        attr_reader :seat
         # The presence member id this connection auto-joined as, or nil for
         # non-presence streams / anonymous connections. Set by the
         # Dispatcher on connect; read on disconnect and heartbeat touch.
         attr_accessor :presence_member
+        # True when presence_member joined as a seat row, false when as a
+        # member-keyed row (table not yet migrated). Leave follows the join.
+        attr_accessor :presence_seat
 
         # last_msg_id_sent is the ONE field whose writer can cross threads: with
         # streams_writer_threads > 0 (issue #321) the OutboundPump worker thread
@@ -31,7 +36,7 @@ module Pgbus
           @last_msg_id_sent.get
         end
 
-        def initialize(id:, stream_name:, io:, since_id:, writer:, write_deadline_ms:, context: nil)
+        def initialize(id:, stream_name:, io:, since_id:, writer:, write_deadline_ms:, context: nil, seat: nil)
           @id = id
           @stream_name = stream_name
           @io = io
@@ -50,6 +55,7 @@ module Pgbus
           # registry when evaluating visible_to predicates. Defaults to
           # nil for tests that don't need audience filtering.
           @context = context
+          @seat = seat
         end
 
         # deadline_ms defaults to the connection's own write deadline so every

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

@@ -13,7 +13,12 @@ module Pgbus
       # is fiber-safe under Falcon's scheduler.
       class FalconConnection
         attr_reader :id, :stream_name, :io, :mutex, :context
+        # The client's per-tab presence seat (?seat=), or nil (issue #515).
+        attr_reader :seat
         attr_accessor :presence_member
+        # True when presence_member joined as a seat row, false when as a
+        # member-keyed row (table not yet migrated). Leave follows the join.
+        attr_accessor :presence_seat
 
         # last_msg_id_sent mirrors Connection's cross-thread cursor (issue #321):
         # a Concurrent::AtomicReference so the OutboundPump worker's advance and
@@ -23,7 +28,7 @@ module Pgbus
           @last_msg_id_sent.get
         end
 
-        def initialize(id:, stream_name:, body:, since_id:, write_deadline_ms:, context: nil)
+        def initialize(id:, stream_name:, body:, since_id:, write_deadline_ms:, context: nil, seat: nil)
           @id = id
           @stream_name = stream_name
           @body = body
@@ -37,6 +42,7 @@ module Pgbus
           @created_at = monotonic
           @last_write_at = @created_at
           @context = context
+          @seat = seat
         end
 
         # deadline_ms is accepted for duck-type parity with Connection#enqueue

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

@@ -26,13 +26,18 @@ module Pgbus
       # the Connection's own mutex, so concurrent dispatcher + heartbeat
       # writes are safe.
       class Heartbeat
-        def initialize(registry:, dispatch_queue:, interval:, idle_timeout:, logger: Pgbus.logger, clock: nil)
+        # presence_expiry: true (streams_presence_patterns is set) posts the
+        # presence touch every tick, even with no presence connection here,
+        # so the dispatcher can expire seats left by other processes.
+        def initialize(registry:, dispatch_queue:, interval:, idle_timeout:, logger: Pgbus.logger, clock: nil,
+                       presence_expiry: false)
           @registry = registry
           @queue = dispatch_queue
           @interval = interval
           @idle_timeout = idle_timeout
           @logger = logger
           @clock = clock || -> { ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) }
+          @presence_expiry = presence_expiry
           @running = false
           @thread = nil
           @wake = ConditionVariable.new
@@ -122,9 +127,10 @@ module Pgbus
         # Posts one batched touch per tick so the dispatcher (which owns AR
         # connection release) refreshes last_seen_at for live presence
         # members, keeping them out of the sweeper. No message when no
-        # connection has presence — avoids waking the dispatcher for nothing.
+        # connection has presence and seat expiry is off — avoids waking the
+        # dispatcher for nothing.
         def enqueue_presence_touch(connections)
-          return if connections.empty?
+          return if connections.empty? && !@presence_expiry
 
           @queue << StreamEventDispatcher::PresenceTouchMessage.new(connections: connections)
         end

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

@@ -74,7 +74,8 @@ module Pgbus
             dispatch_queue: @dispatch_queue,
             interval: @config.streams_heartbeat_interval,
             idle_timeout: @config.streams_idle_timeout,
-            logger: @logger
+            logger: @logger,
+            presence_expiry: Array(@config.streams_presence_patterns).any?
           )
           @started = false
           @shutdown_mutex = Mutex.new