pgbus 0.5.0 → 0.6.0

data/lib/pgbus/streams/presence.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Streams
+    # Presence tracking for SSE streams. A "presence member" is an
+    # arbitrary identifier (typically a user id) marked as currently
+    # subscribed to a given stream. Members live in pgbus_presence_members
+    # with a (stream_name, member_id) primary key and a `last_seen_at`
+    # timestamp; the table is the source of truth across all Puma workers
+    # and Falcon reactors.
+    #
+    # Typical usage in a controller:
+    #
+    #   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 }
+    #     )
+    #   end
+    #
+    # And when the user leaves:
+    #
+    #   Pgbus.stream(@room).presence.leave(member_id: current_user.id.to_s)
+    #
+    # Reading the current member list:
+    #
+    #   Pgbus.stream(@room).presence.members
+    #     # => [{ "id" => "7", "metadata" => {"name" => ..., "avatar" => ...},
+    #     #      "joined_at" => "...", "last_seen_at" => "..." }]
+    #
+    # The join/leave operations also fire a stream broadcast (via the
+    # caller-provided block) so connected clients see the change in real
+    # time. The library emits the broadcast through the regular 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).
+    #   - Built-in DOM events on the <pgbus-stream-source> element
+    #     (the application's broadcast block decides the HTML).
+    class Presence
+      def initialize(stream)
+        @stream = stream
+      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: {})
+        member_id = member_id.to_s
+        record = upsert_member(member_id, metadata)
+
+        if block_given?
+          html = yield(record)
+          @stream.broadcast(html) if html.is_a?(String) && !html.empty?
+        end
+
+        record
+      end
+
+      # 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)
+        return nil unless record
+
+        if block_given?
+          html = yield(record)
+          @stream.broadcast(html) if html.is_a?(String) && !html.empty?
+        end
+
+        record
+      end
+
+      # Refreshes the last_seen_at timestamp without re-broadcasting.
+      # 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:)
+        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
+        SQL
+      end
+
+      # Returns the current list of members on this stream as an
+      # array of hashes (id, metadata, joined_at, last_seen_at).
+      def members
+        rows = connection.exec_params(<<~SQL, [@stream.name])
+          SELECT member_id, metadata, joined_at, last_seen_at
+          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
+      end
+
+      # Returns the count of current members. Faster than members.size
+      # because it doesn't deserialize metadata.
+      def count
+        rows = connection.exec_params(<<~SQL, [@stream.name])
+          SELECT COUNT(*) AS n FROM pgbus_presence_members WHERE stream_name = $1
+        SQL
+        rows.first["n"].to_i
+      end
+
+      # Removes members whose last_seen_at is older than the given cutoff.
+      # Returns the number of expired rows. Use as a sweeper:
+      #
+      #   Pgbus.stream("room:42").presence.sweep!(older_than: 60.seconds.ago)
+      #
+      # Atomically claims the deletion via DELETE RETURNING so multiple
+      # workers running the sweep concurrently won't double-emit leave
+      # events.
+      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
+        SQL
+        rows.to_a.size
+      end
+
+      private
+
+      def upsert_member(member_id, metadata)
+        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)
+          DO UPDATE SET metadata = EXCLUDED.metadata, last_seen_at = NOW()
+          RETURNING member_id, metadata, joined_at, last_seen_at
+        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"]
+        }
+      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
+        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
+        {}
+      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
+    end
+  end
+end

data/lib/pgbus/streams/signed_name.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "active_support/message_verifier"
+
+module Pgbus
+  module Streams
+    # Verifies tamper-proof stream identifiers carried in URLs (the
+    # `signed-stream-name` attribute set by `pgbus_stream_from`). Reuses
+    # `Turbo.signed_stream_verifier_key` when turbo-rails is loaded so that
+    # existing `broadcasts_to :room` calls Just Work; falls back to
+    # `Pgbus.configuration.streams_signed_name_secret` otherwise.
+    #
+    # The signed payload is the logical stream name as a string (e.g.
+    # `"gid://app/Order/42:messages"`). Verification returns that string;
+    # tampered or unsigned input raises `InvalidSignedName`.
+    module SignedName
+      class InvalidSignedName < StandardError
+      end
+
+      class MissingSecret < StandardError
+      end
+
+      def self.verify!(token)
+        raise InvalidSignedName, "signed stream name is blank" if token.nil? || token.to_s.strip.empty?
+
+        verifier.verified(token) || raise(InvalidSignedName, "signed stream name failed verification")
+      rescue ActiveSupport::MessageVerifier::InvalidSignature => e
+        raise InvalidSignedName, "signed stream name failed verification: #{e.message}"
+      end
+
+      def self.sign(stream_name)
+        verifier.generate(stream_name)
+      end
+
+      # Returns an ActiveSupport::MessageVerifier configured with whichever
+      # secret is appropriate for this process. Memoization is intentionally
+      # NOT used because tests rotate keys and the cost of constructing a
+      # verifier is negligible compared to the SHA256 work it does.
+      def self.verifier
+        ActiveSupport::MessageVerifier.new(secret, digest: "SHA256", serializer: JSON)
+      end
+
+      def self.secret
+        turbo_secret || configuration_secret || raise_missing_secret!
+      end
+
+      def self.turbo_secret
+        return nil unless defined?(::Turbo)
+
+        ::Turbo.signed_stream_verifier_key
+      rescue ArgumentError
+        # Real turbo-rails raises ArgumentError when the key is unset.
+        nil
+      end
+
+      def self.configuration_secret
+        Pgbus.configuration.streams_signed_name_secret
+      end
+
+      def self.raise_missing_secret!
+        raise MissingSecret,
+              "no signing secret available — set Pgbus.configuration.streams_signed_name_secret " \
+              "or Turbo.signed_stream_verifier_key"
+      end
+
+      private_class_method :verifier, :secret, :turbo_secret, :configuration_secret, :raise_missing_secret!
+    end
+  end
+end

data/lib/pgbus/streams/turbo_broadcastable.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Streams
+    # Runtime patch that redirects `Turbo::StreamsChannel.broadcast_stream_to`
+    # through pgbus instead of `ActionCable.server.broadcast`. Applied at
+    # Rails engine boot time when `defined?(::Turbo::StreamsChannel)` —
+    # see `Pgbus::Engine`'s initializer. When turbo-rails isn't loaded,
+    # this patch is a no-op and pgbus streams continue to work via the
+    # explicit `Pgbus.stream(...).broadcast(...)` API.
+    #
+    # After the patch:
+    #
+    #   class Order < ApplicationRecord
+    #     broadcasts_to :account   # existing turbo-rails API, unchanged
+    #   end
+    #
+    #   # In a controller:
+    #   @order.update!(status: "shipped")
+    #   # → Turbo::Broadcastable runs its after_update_commit callback
+    #   # → calls Turbo::StreamsChannel.broadcast_replace_to
+    #   # → which calls Turbo::StreamsChannel.broadcast_stream_to
+    #   # → which is patched to call Pgbus.stream(name).broadcast(content)
+    #   # → which inserts into PGMQ and fires NOTIFY
+    #
+    # Zero changes to user code. The entire Turbo::Broadcastable API
+    # (broadcasts_to, broadcasts_refreshes, broadcast_replace_to,
+    # broadcast_append_later_to, broadcasts_refreshes_to, etc) reuses
+    # this code path because they all funnel through broadcast_stream_to.
+    #
+    # Signed stream name reuse: we don't touch `Turbo.signed_stream_verifier`,
+    # so any existing `broadcasts_to :room` call continues to generate
+    # tokens that our `Pgbus::Streams::SignedName.verify!` accepts (as
+    # long as `Turbo.signed_stream_verifier_key` is set, which the Rails
+    # app is already responsible for).
+    module TurboBroadcastable
+      def broadcast_stream_to(*streamables, content:)
+        name = stream_name_from(streamables)
+        Pgbus.stream(name).broadcast(content)
+      end
+    end
+
+    # Apply the patch to Turbo::StreamsChannel's singleton class. Idempotent:
+    # prepending the same module twice is a no-op. Called from
+    # Pgbus::Engine's initializer when Turbo is detected.
+    def self.install_turbo_broadcastable_patch!
+      return unless defined?(::Turbo::StreamsChannel)
+      return if ::Turbo::StreamsChannel.singleton_class.include?(TurboBroadcastable)
+
+      ::Turbo::StreamsChannel.singleton_class.prepend(TurboBroadcastable)
+    end
+  end
+end

data/lib/pgbus/streams/watermark_cache_middleware.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Streams
+    # Rack middleware that clears the per-request thread-local watermark
+    # cache used by `Pgbus::StreamsHelper#pgbus_stream_from`. Without this
+    # middleware, a subsequent request served by the same thread would
+    # see stale `current_msg_id` values from the previous render — the
+    # pgbus_stream_from helper caches watermark lookups within a single
+    # request to avoid N+1 queries when a page uses multiple streams,
+    # and the cache would leak without a per-request boundary.
+    #
+    # Installed automatically by `Pgbus::Engine` at boot.
+    class WatermarkCacheMiddleware
+      CACHE_KEY = :pgbus_streams_watermark_cache
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        @app.call(env)
+      ensure
+        Thread.current[CACHE_KEY] = nil
+      end
+    end
+  end
+end

data/lib/pgbus/streams.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Pgbus
+  # Pgbus::Streams is the SSE-based pub/sub subsystem that replaces
+  # `turbo_stream_from`. The user-facing entrypoint is `Pgbus.stream(name)`,
+  # which returns a `Pgbus::Streams::Stream` providing `#broadcast`,
+  # `#current_msg_id`, and `#read_after`.
+  module Streams
+    # Process-wide registry of server-side audience filter predicates.
+    # Register filters at boot time via:
+    #   Pgbus::Streams.filters.register(:admin_only) { |user| user.admin? }
+    # See lib/pgbus/streams/filters.rb for the full API.
+    def self.filters
+      @filters ||= Filters.new
+    end
+
+    # Clears the filters registry. Used by tests; not intended for runtime.
+    def self.reset_filters!
+      @filters = nil
+    end
+
+    # A handle on a single logical stream. The name can be any string, an
+    # object responding to `to_gid_param`, or an array of streamables (which
+    # are joined with colons — turbo-rails-compatible).
+    #
+    # Stream is *not* a singleton — callers create instances ad hoc, but the
+    # underlying queue is created lazily and only once per process per name.
+    class Stream
+      attr_reader :name
+
+      def initialize(streamables, client: Pgbus.client)
+        @name = self.class.name_from(streamables)
+        @client = client
+        @ensured = false
+        @ensure_mutex = Mutex.new
+      end
+
+      # Broadcasts a Turbo Stream HTML payload through the pgbus streamer.
+      # PGMQ's `message` column is JSONB, so raw HTML strings can't be passed
+      # directly. We wrap as `{"html": "..."}` on the way in and unwrap in
+      # Pgbus::Web::Streamer::Dispatcher before delivering to the SSE client.
+      # Callers pass a plain HTML string; the wrapping is an implementation
+      # detail.
+      #
+      # Transactional semantics: if this call is made inside an open
+      # ActiveRecord transaction, the PGMQ insert is deferred to an
+      # after_commit callback. If the transaction rolls back, the broadcast
+      # silently drops — clients never see the change that the database
+      # never persisted. This is the feature no other Rails real-time stack
+      # (including turbo-rails over ActionCable) can offer: the broadcast
+      # and the data mutation are atomic with respect to each other.
+      # Returns the assigned msg_id when sent synchronously, nil when
+      # deferred (the id isn't known until the after_commit callback runs).
+      #
+      # Audience filtering: pass `visible_to:` with a filter label (a
+      # Symbol previously registered via Pgbus::Streams.filters.register)
+      # to restrict delivery to connections whose authorize-hook context
+      # satisfies the predicate. The label travels with the broadcast
+      # through PGMQ; the predicate itself lives in-process on the
+      # subscriber side and is evaluated per-connection by the Dispatcher.
+      def broadcast(payload, visible_to: nil)
+        ensure_queue!
+        wrapped = { "html" => payload.to_s }
+        wrapped["visible_to"] = visible_to.to_s if visible_to
+        transaction = current_open_transaction
+        if transaction
+          transaction.after_commit { @client.send_message(@name, wrapped) }
+          nil
+        else
+          @client.send_message(@name, wrapped)
+        end
+      end
+
+      def current_msg_id
+        @client.stream_current_msg_id(@name)
+      end
+
+      def read_after(after_id:, limit: 500)
+        @client.read_after(@name, after_id: after_id, limit: limit)
+      end
+
+      def ensure!
+        ensure_queue!
+        self
+      end
+
+      # Returns a Pgbus::Streams::Presence handle for this stream.
+      # The Presence object exposes join/leave/touch/members/sweep!
+      # for tracking who is currently subscribed. See
+      # lib/pgbus/streams/presence.rb for the API.
+      def presence
+        @presence ||= Presence.new(self)
+      end
+
+      # Mirrors `Turbo::Streams::StreamName#stream_name_from`. Strings pass
+      # through; objects with `to_gid_param` or `to_param` are coerced; arrays
+      # are joined with `:`. The result is suitable both as a logical stream
+      # identifier and as the input to QueueNameValidator (after sanitisation).
+      def self.name_from(streamables)
+        if streamables.is_a?(Array)
+          streamables.map { |s| name_from(s) }.join(":")
+        elsif streamables.respond_to?(:to_gid_param)
+          streamables.to_gid_param
+        elsif streamables.respond_to?(:to_param) && !streamables.is_a?(Symbol)
+          streamables.to_param
+        else
+          streamables.to_s
+        end
+      end
+
+      private
+
+      def ensure_queue!
+        return if @ensured
+
+        @ensure_mutex.synchronize do
+          return if @ensured
+
+          @client.ensure_stream_queue(@name)
+          @ensured = true
+        end
+      end
+
+      # Returns the current AR transaction if one is open, nil otherwise.
+      # Guarded by defined? so the streams subsystem stays usable in
+      # non-Rails contexts. AR's NullTransaction yields immediately from
+      # after_commit, so we have to check #open? explicitly — otherwise
+      # every call path would hit the "deferred" branch and we'd lose the
+      # msg_id return value.
+      def current_open_transaction
+        return nil unless defined?(::ActiveRecord::Base)
+
+        connection = ::ActiveRecord::Base.connection
+        transaction = connection.current_transaction
+        transaction if transaction.open?
+      rescue StandardError => e
+        # Defensive: if AR is loaded but not yet connected (e.g. a
+        # Rake task invoked before Rails boot), don't let the transaction
+        # probe break the broadcast. Debug-logged so a misconfigured
+        # app can diagnose "why aren't my transactional broadcasts
+        # deferring?" without impacting production performance
+        # (debug is off by default).
+        Pgbus.logger.debug do
+          "[Pgbus::Streams::Stream] transaction probe failed (#{e.class}: #{e.message}); " \
+            "falling back to synchronous broadcast"
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/pgbus/version.rb

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

data/lib/pgbus/web/data_source.rb

@@ -630,6 +630,35 @@ module Pgbus
         []
       end
 
+      # Stream stats — only populated when streams_stats_enabled is
+      # true AND the migration has been run. Controllers should gate
+      # rendering on `stream_stats_available?` to avoid showing empty
+      # sections.
+      def stream_stats_available?
+        Pgbus.configuration.streams_stats_enabled && StreamStat.table_exists?
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error checking stream stats availability: #{e.message}" }
+        false
+      end
+
+      def stream_stats_summary(minutes: 60)
+        StreamStat.summary(minutes: minutes)
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error fetching stream stats summary: #{e.message}" }
+        {
+          broadcasts: 0, connects: 0, disconnects: 0,
+          active_estimate: 0, avg_fanout: 0,
+          avg_broadcast_ms: 0, avg_connect_ms: 0
+        }
+      end
+
+      def top_streams(limit: 10, minutes: 60)
+        StreamStat.top_streams(limit: limit, minutes: minutes)
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error fetching top streams: #{e.message}" }
+        []
+      end
+
       # Subscriber registry
       def registered_subscribers
         EventBus::Registry.instance.subscribers.map do |s|