pgbus 0.5.1 → 0.6.0

data/lib/pgbus/engine.rb

@@ -46,6 +46,7 @@ module Pgbus
 
     rake_tasks do
       load File.expand_path("../tasks/pgbus_pgmq.rake", __dir__)
+      load File.expand_path("../tasks/pgbus_streams.rake", __dir__)
     end
 
     initializer "pgbus.i18n" do
@@ -56,5 +57,35 @@ module Pgbus
       require "pgbus/web/authentication"
       require "pgbus/web/data_source"
     end
+
+    # Install the watermark cache middleware ahead of the app's own
+    # middleware so the thread-local cache is cleared between every
+    # Rack request. Without this, repeated page renders served by the
+    # same Puma thread would see stale current_msg_id values.
+    initializer "pgbus.streams.middleware" do |app|
+      app.middleware.use Pgbus::Streams::WatermarkCacheMiddleware if Pgbus.configuration.streams_enabled
+    end
+
+    # Install the Turbo::StreamsChannel patch after turbo-rails has been
+    # loaded. The patch redirects broadcast_stream_to through Pgbus.stream
+    # instead of ActionCable. When turbo-rails is not loaded, this is a
+    # no-op and pgbus_stream_from still works via the explicit
+    # Pgbus.stream(...).broadcast(...) API.
+    initializer "pgbus.streams.turbo_broadcastable", after: :load_config_initializers do
+      ActiveSupport.on_load(:after_initialize) do
+        if Pgbus.configuration.streams_enabled
+          # Touch the constant first so Zeitwerk autoloads
+          # lib/pgbus/streams/turbo_broadcastable.rb. The file defines
+          # `Pgbus::Streams::TurboBroadcastable` (the autoloaded const)
+          # AND `Pgbus::Streams.install_turbo_broadcastable_patch!`
+          # (a side-effect class method on the parent module). Without
+          # the constant reference, Zeitwerk doesn't load the file and
+          # the method call below raises NoMethodError. Assigning to
+          # `_` keeps RuboCop's Lint/Void from deleting the line.
+          _autoload_trigger = Pgbus::Streams::TurboBroadcastable
+          Pgbus::Streams.install_turbo_broadcastable_patch!
+        end
+      end
+    end
   end
 end

data/lib/pgbus/process/dispatcher.rb

@@ -33,6 +33,7 @@ module Pgbus
         @last_batch_cleanup_at = monotonic_now
         @last_recurring_cleanup_at = monotonic_now
         @last_archive_compaction_at = monotonic_now
+        @last_stream_archive_compaction_at = monotonic_now
         @last_outbox_cleanup_at = monotonic_now
         @last_job_lock_cleanup_at = monotonic_now
         @last_stats_cleanup_at = monotonic_now
@@ -79,6 +80,7 @@ module Pgbus
         run_if_due(now, :@last_batch_cleanup_at, BATCH_CLEANUP_INTERVAL) { cleanup_batches }
         run_if_due(now, :@last_recurring_cleanup_at, RECURRING_CLEANUP_INTERVAL) { cleanup_recurring_executions }
         run_if_due(now, :@last_archive_compaction_at, ARCHIVE_COMPACTION_INTERVAL) { compact_archives }
+        run_if_due(now, :@last_stream_archive_compaction_at, ARCHIVE_COMPACTION_INTERVAL) { prune_stream_archives }
         run_if_due(now, :@last_outbox_cleanup_at, OUTBOX_CLEANUP_INTERVAL) { cleanup_outbox }
         run_if_due(now, :@last_job_lock_cleanup_at, JOB_LOCK_CLEANUP_INTERVAL) { cleanup_job_locks }
         run_if_due(now, :@last_stats_cleanup_at, STATS_CLEANUP_INTERVAL) { cleanup_stats }
@@ -140,13 +142,20 @@ module Pgbus
       end
 
       def cleanup_stats
-        return unless config.stats_enabled
-
         retention = config.stats_retention
         return unless retention&.positive?
 
-        deleted = JobStat.cleanup!(older_than: Time.current - retention)
-        Pgbus.logger.debug { "[Pgbus] Cleaned up #{deleted} old job stats" } if deleted.positive?
+        cutoff = Time.current - retention
+
+        if config.stats_enabled
+          deleted = JobStat.cleanup!(older_than: cutoff)
+          Pgbus.logger.debug { "[Pgbus] Cleaned up #{deleted} old job stats" } if deleted.positive?
+        end
+
+        return unless config.streams_stats_enabled
+
+        deleted = StreamStat.cleanup!(older_than: cutoff)
+        Pgbus.logger.debug { "[Pgbus] Cleaned up #{deleted} old stream stats" } if deleted.positive?
       end
 
       def cleanup_job_locks
@@ -241,6 +250,55 @@ module Pgbus
         Pgbus.logger.warn { "[Pgbus] Archive compaction failed: #{e.message}" }
       end
 
+      # Prunes per-stream archive tables. Unlike compact_archives (which
+      # uses the global archive_retention, typically 7 days), streams need
+      # per-stream retention because a chat-history stream and a
+      # presence-ping stream have wildly different storage requirements.
+      # Lookup order for a given queue: exact string match, then regex
+      # match, then streams_default_retention (5 minutes by default).
+      def prune_stream_archives
+        prefix = config.streams_queue_prefix
+        return if prefix.nil? || prefix.empty?
+
+        batch_size = config.archive_compaction_batch_size || 1000
+        conn = config.connects_to ? Pgbus::BusRecord.connection : ActiveRecord::Base.connection
+        queue_names = conn.select_values("SELECT queue_name FROM pgmq.meta ORDER BY queue_name")
+
+        queue_names.each do |full_name|
+          next unless full_name.start_with?("#{prefix}_")
+
+          retention = retention_for_stream_queue(full_name)
+          next unless retention.positive?
+
+          cutoff = Time.current - retention
+          stripped = full_name.delete_prefix("#{config.queue_prefix}_")
+          deleted = Pgbus.client.purge_archive(stripped, older_than: cutoff, batch_size: batch_size)
+          if deleted.positive?
+            Pgbus.logger.debug do
+              "[Pgbus] Compacted #{deleted} stream archive entries from #{full_name}"
+            end
+          end
+        rescue StandardError => e
+          Pgbus.logger.warn { "[Pgbus] Stream archive compaction failed for #{full_name}: #{e.message}" }
+        end
+      rescue StandardError => e
+        Pgbus.logger.warn { "[Pgbus] Stream archive compaction failed: #{e.message}" }
+      end
+
+      def retention_for_stream_queue(full_name)
+        retention_map = config.streams_retention || {}
+        # Exact-match first — cheapest and most common path
+        exact = retention_map[full_name]
+        return exact.to_f if exact
+
+        # Regex-match second for pattern-based overrides (e.g. /^chat_/)
+        retention_map.each do |key, value|
+          return value.to_f if key.is_a?(Regexp) && key.match?(full_name)
+        end
+
+        config.streams_default_retention.to_f
+      end
+
       def cleanup_recurring_executions
         retention = config.recurring_execution_retention
         return unless retention&.positive?

data/lib/pgbus/streams/cursor.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Streams
+    # Parses an SSE replay cursor from a Rack request. The cursor is the highest
+    # PGMQ msg_id the client has already seen; the streamer replays everything
+    # strictly greater on (re)connect.
+    #
+    # Two sources, by precedence:
+    #   1. Last-Event-ID header (sent automatically by EventSource on reconnect)
+    #   2. ?since= query param (sent by the custom element on first connect,
+    #      because EventSource cannot send custom headers on the initial request)
+    #
+    # Returns 0 when no cursor is present (i.e. "deliver everything from now").
+    module Cursor
+      # PGMQ msg_id is BIGINT — strictly within signed 64-bit range.
+      MAX_MSG_ID = (2**63) - 1
+
+      class InvalidCursor < ArgumentError
+      end
+
+      # Strict integer pattern: optional leading minus, then digits. No plus prefix,
+      # no decimal, no whitespace. Negatives are caught by validate! with a clearer
+      # error message than "must be numeric".
+      INTEGER_PATTERN = /\A-?\d+\z/
+
+      def self.parse(query_since:, last_event_id:)
+        raw = pick(last_event_id, query_since)
+        return 0 if raw.nil?
+
+        value = coerce(raw)
+        validate!(value)
+        value
+      end
+
+      def self.pick(last_event_id, query_since)
+        return last_event_id if present?(last_event_id)
+        return query_since   if present?(query_since)
+
+        nil
+      end
+
+      def self.present?(value)
+        return false if value.nil?
+        # Any Integer is "present" so precedence is decided here, not by
+        # the sign of the value. validate! rejects negatives separately
+        # so a caller passing a literal -1 still crashes loud rather than
+        # silently falling through to query_since.
+        return true if value.is_a?(Integer)
+
+        !value.to_s.strip.empty?
+      end
+
+      def self.coerce(raw)
+        return raw if raw.is_a?(Integer)
+
+        str = raw.to_s
+        raise InvalidCursor, "cursor must be numeric (got #{raw.inspect})" unless str.match?(INTEGER_PATTERN)
+
+        Integer(str, 10)
+      end
+
+      def self.validate!(value)
+        raise InvalidCursor, "cursor must not be negative (got #{value})" if value.negative?
+        raise InvalidCursor, "cursor #{value} is out of BIGINT range" if value > MAX_MSG_ID
+      end
+
+      private_class_method :pick, :present?, :coerce, :validate!
+    end
+  end
+end

data/lib/pgbus/streams/envelope.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Streams
+    # Encodes Server-Sent Events frames per https://html.spec.whatwg.org/multipage/server-sent-events.html.
+    #
+    # Pgbus uses three frame types:
+    #   - `message(id:, event:, data:)` — a real broadcast (carries an `id:` so the client
+    #     can resume via `Last-Event-ID` on reconnect)
+    #   - `comment(text)` — a heartbeat or sentinel that the SSE parser ignores
+    #   - `retry_directive(ms)` — tells `EventSource` how long to wait before reconnecting
+    #
+    # All frames end with `\n\n` (the SSE event terminator). `data:` lines must not
+    # contain newlines — the SSE spec uses `\n` as the field terminator, so a multi-line
+    # payload would arrive as multiple events. We strip `\r` and `\n` from data and
+    # comment text rather than splitting into multiple `data:` lines, because Turbo
+    # Stream HTML is already flat and the simpler encoding is easier to debug.
+    module Envelope
+      NEWLINES = /[\r\n]+/
+
+      RESPONSE_HEADERS = "HTTP/1.1 200 OK\r\n" \
+                         "content-type: text/event-stream\r\n" \
+                         "cache-control: no-cache, no-transform\r\n" \
+                         "x-accel-buffering: no\r\n" \
+                         "connection: keep-alive\r\n" \
+                         "\r\n"
+
+      def self.message(id:, event:, data:)
+        raise ArgumentError, "id is required" if id.nil?
+        raise ArgumentError, "event is required" if event.nil? || event.to_s.empty?
+
+        "id: #{id}\nevent: #{event}\ndata: #{strip_newlines(data.to_s)}\n\n"
+      end
+
+      def self.comment(text)
+        ": #{strip_newlines(text.to_s)}\n\n"
+      end
+
+      def self.retry_directive(milliseconds)
+        unless milliseconds.is_a?(Integer) && !milliseconds.negative?
+          raise ArgumentError, "retry must be a non-negative integer (got #{milliseconds.inspect})"
+        end
+
+        "retry: #{milliseconds}\n\n"
+      end
+
+      def self.http_response_headers
+        RESPONSE_HEADERS
+      end
+
+      def self.strip_newlines(str)
+        str.gsub(NEWLINES, "")
+      end
+
+      private_class_method :strip_newlines
+    end
+  end
+end

data/lib/pgbus/streams/filters.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Streams
+    # Process-wide registry of server-side audience filter predicates.
+    # Used by `Pgbus.stream(name).broadcast(html, visible_to: :label)`
+    # to restrict delivery to connections whose authorize-hook context
+    # matches the predicate.
+    #
+    # Typical setup at boot time:
+    #
+    #   Pgbus::Streams.filters.register(:admin_only) { |user| user.admin? }
+    #   Pgbus::Streams.filters.register(:workspace_member) do |user, stream|
+    #     user.workspaces.pluck(:id).include?(stream.split(":").last.to_i)
+    #   end
+    #
+    # Broadcasts reference filters by label:
+    #
+    #   Pgbus.stream("workspace:42").broadcast(html, visible_to: :admin_only)
+    #
+    # The Dispatcher looks up the filter in the registry, evaluates it
+    # against each connection's context (populated from the StreamApp's
+    # authorize hook return value), and only delivers to connections
+    # where the predicate returns true.
+    #
+    # Why a registry of labels instead of passing a Proc directly to
+    # broadcast: predicates can't be serialized to JSON, so they can't
+    # travel through PGMQ. The label is serialized; the predicate lives
+    # in-process on the subscriber side. This also means the predicate
+    # is evaluated on the same process that holds the SSE connection,
+    # so the user context (typically an ActiveRecord model or a session
+    # hash) is always available.
+    class Filters
+      def initialize(logger: nil)
+        @mutex = Mutex.new
+        @filters = {}
+        @logger = logger
+      end
+
+      def register(label, callable = nil, &block)
+        raise ArgumentError, "filter label must be a Symbol (got #{label.class})" unless label.is_a?(Symbol)
+
+        predicate = callable || block
+        raise ArgumentError, "filter must be given a block or callable" if predicate.nil?
+
+        @mutex.synchronize { @filters[label] = predicate }
+      end
+
+      def lookup(label)
+        @mutex.synchronize { @filters[label] }
+      end
+
+      # Evaluates the named filter against a context. The context is
+      # whatever the StreamApp's authorize hook returned when the
+      # connection was established — typically a user model.
+      #
+      # Policy decisions:
+      #   - label=nil → visible (no filter attached to the broadcast)
+      #   - unknown label → NOT visible + warning log. Fail-closed so
+      #     a typo or renamed filter doesn't turn a restricted
+      #     broadcast into a public one. The whole point of audience
+      #     filtering is data isolation; failing open on a typo
+      #     defeats the feature. The warning log is loud enough that
+      #     typos still get noticed in dev (check the log or wonder
+      #     why no subscriber sees your broadcast).
+      #   - predicate raises → NOT visible (fail-closed on runtime
+      #     error to avoid leaking data on an exception path).
+      def visible?(label, context)
+        return true if label.nil?
+
+        predicate = lookup(label)
+        if predicate.nil?
+          log_warn("unknown filter label #{label.inspect} — broadcast dropped (fail-closed)")
+          return false
+        end
+
+        begin
+          !!predicate.call(context)
+        rescue StandardError => e
+          log_error("filter #{label.inspect} raised #{e.class}: #{e.message} — dropping broadcast (fail-closed)")
+          false
+        end
+      end
+
+      private
+
+      def log_warn(message)
+        logger = @logger || (Pgbus.logger if defined?(Pgbus) && Pgbus.respond_to?(:logger))
+        logger&.warn { "[Pgbus::Streams::Filters] #{message}" }
+      end
+
+      def log_error(message)
+        logger = @logger || (Pgbus.logger if defined?(Pgbus) && Pgbus.respond_to?(:logger))
+        logger&.error { "[Pgbus::Streams::Filters] #{message}" }
+      end
+    end
+  end
+end

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