pgbus 0.8.4 → 0.9.2

data/lib/pgbus/streams.rb

@@ -15,6 +15,12 @@ module Pgbus
     # this specifically can rescue Pgbus::Streams::StreamNameTooLong.
     class StreamNameTooLong < ArgumentError; end
 
+    # The default SSE `event:` name for a broadcast frame. Turbo's
+    # StreamObserver consumes frames the client re-dispatches as the
+    # `message` DOM event; the client maps this SSE event name to
+    # `message`. Broadcasts may override it with a typed name (issue #170).
+    DEFAULT_SSE_EVENT = "turbo-stream"
+
     # Process-wide registry of server-side audience filter predicates.
     # Register filters at boot time via:
     #   Pgbus::Streams.filters.register(:admin_only) { |user| user.admin? }
@@ -28,6 +34,25 @@ module Pgbus
       @filters = nil
     end
 
+    # Process-wide publish-side coalescer for high-frequency broadcasts
+    # (issue #171). Lazily built; the flush re-enters the normal broadcast
+    # path so a coalesced frame is just a deferred ordinary broadcast.
+    def self.coalescer
+      # `target:` is part of the flush signature but unused here — it's only
+      # a coalescing key; the target is already encoded in the payload's
+      # turbo-stream tag. Absorbed via ** so it isn't a broadcast argument.
+      @coalescer ||= Coalescer.new(
+        flush: lambda do |stream_name:, payload:, opts:, **|
+          Pgbus.stream(stream_name).broadcast(payload, **opts)
+        end
+      )
+    end
+
+    # Clears the coalescer. Used by tests; not intended for runtime.
+    def self.reset_coalescer!
+      @coalescer = 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).
@@ -76,9 +101,48 @@ module Pgbus
       # Per-broadcast `durable:` overrides the stream-level default for a
       # single broadcast. `nil` (the default) defers to the stream's own
       # `durable?` setting; `true`/`false` flip the mode for this call only.
-      def broadcast(payload, visible_to: nil, durable: nil)
+      #
+      # Actor-echo suppression: pass `exclude:` with the broadcaster's own
+      # SSE connection id (surfaced to the page as
+      # `<meta name="pgbus-connection-id">` / the element's `connection-id`
+      # attribute, sent back on the action request as the
+      # `X-Pgbus-Connection` header). The dispatcher skips delivery to that
+      # one connection, so the actor doesn't receive the echo of its own
+      # broadcast — it already applied the change via the action's HTTP
+      # response. Everyone else gets the broadcast. A nil/blank `exclude`
+      # is a no-op (the common path).
+      # Typed SSE event name: pass `event:` to set the SSE `event:` field
+      # on the delivered frame (e.g. `event: "presence"`, `event:
+      # "reactive"`) while keeping the payload a Turbo Stream. Clients that
+      # care can route on the typed event without sniffing the HTML;
+      # default consumers still receive the standard turbo-stream/`message`
+      # path. The default (`nil` or `"turbo-stream"`) is not carried on the
+      # wire — it's the implicit default the dispatcher applies.
+      # High-frequency coalescing: pass `coalesce:` (a window in milliseconds,
+      # or `true` for the default window) together with `target:` to batch
+      # rapid broadcasts to the same (stream, target) and publish only the
+      # latest within the window. Superseded frames never reach the bus.
+      # Last-write-wins, so this is only safe for idempotent replace/update
+      # of a stable target (the high-frequency case: cursors, typing,
+      # progress). Returns nil — the actual broadcast is deferred to the
+      # coalescer's flush. See issue #171 and Pgbus::Streams::Coalescer.
+      def broadcast(payload, visible_to: nil, durable: nil, exclude: nil, event: nil, coalesce: nil, target: nil)
+        if coalesce
+          return coalesce_broadcast(
+            payload,
+            coalesce: coalesce,
+            target: target,
+            visible_to: visible_to,
+            durable: durable,
+            exclude: exclude,
+            event: event
+          )
+        end
+
         wrapped = { "html" => payload.to_s }
         wrapped["visible_to"] = visible_to.to_s if visible_to
+        wrapped["exclude"] = exclude.to_s if exclude && !exclude.to_s.empty?
+        wrapped["event"] = event.to_s if event && event.to_s != DEFAULT_SSE_EVENT
 
         use_durable = durable.nil? ? @durable : durable
         return broadcast_ephemeral(wrapped) unless use_durable
@@ -101,6 +165,36 @@ module Pgbus
         end
       end
 
+      # Renders a renderable (a Phlex component, a ViewComponent, or a
+      # pre-rendered HTML string) into a complete `<turbo-stream>` action
+      # tag and broadcasts it atomically — the render and the broadcast in
+      # one call. This removes the #1 footgun in server-driven UI: building
+      # the off-request render context and the turbo-stream wrapper by hand
+      # at every call site.
+      #
+      #   Pgbus.stream("chat", room).broadcast_render(
+      #     renderable: Chat::Message.new(chat_message: msg),
+      #     action: :append, target: "chat-messages-#{room}",
+      #     exclude: connection_id   # composes with #165
+      #   )
+      #
+      # `action` defaults to :replace. `target` is required. `exclude:`,
+      # `visible_to:`, and `durable:` are forwarded to #broadcast unchanged,
+      # so actor-echo suppression and audience filtering compose. Returns
+      # whatever #broadcast returns (msg_id, or nil when deferred to
+      # after_commit inside a transaction).
+      #
+      # See Pgbus::Streams::Renderer for the renderable-resolution order.
+      # Components that need URL helpers or a full view context should be
+      # rendered by the app (which has the request context) and the
+      # resulting string passed as `renderable:`.
+      def broadcast_render(target:, action: :replace, renderable: nil, visible_to: nil, durable: nil, exclude: nil,
+                           event: nil, coalesce: nil)
+        html = Renderer.turbo_stream_tag(action: action, target: target, renderable: renderable)
+        broadcast(html, visible_to: visible_to, durable: durable, exclude: exclude, event: event,
+                        coalesce: coalesce, target: target)
+      end
+
       def current_msg_id
         @client.stream_current_msg_id(@name)
       end
@@ -172,6 +266,61 @@ module Pgbus
         nil
       end
 
+      # Submits a frame to the process-wide coalescer instead of
+      # broadcasting now. Requires a target (the dedupe key — there's no
+      # way to last-write-win without one). The window is `coalesce` in ms
+      # when numeric, else the coalescer's default. Returns nil; the
+      # coalescer flushes the latest frame as an ordinary broadcast.
+      def coalesce_broadcast(payload, coalesce:, target:, visible_to:, durable:, exclude:, event:)
+        if target.nil? || target.to_s.empty?
+          raise ArgumentError,
+                "broadcast(coalesce:) requires target: — coalescing keys on (stream, target), " \
+                "so the latest frame per target can win. Use broadcast_render(coalesce:) which " \
+                "already has a target, or pass target: explicitly."
+        end
+
+        window_ms = coalesce_window_ms(coalesce)
+        # Resolve durability against THIS stream instance now, not nil. The
+        # coalescer's flush re-enters Pgbus.stream(@name), whose durability
+        # could resolve differently (config patterns) than this instance —
+        # passing the resolved value keeps the coalesced frame's mode stable.
+        resolved_durable = durable.nil? ? @durable : durable
+
+        submit = lambda do
+          Streams.coalescer.submit(
+            stream_name: @name,
+            target: target.to_s,
+            payload: payload.to_s,
+            window_ms: window_ms,
+            opts: { visible_to: visible_to, durable: resolved_durable, exclude: exclude, event: event }
+          )
+        end
+
+        # Transaction gating: a coalesced DURABLE broadcast made inside an
+        # open transaction must not flush if the transaction rolls back, so
+        # defer the submission to after_commit (mirrors the non-coalesced
+        # path). Ephemeral coalescing is fire-and-forget, so it submits now.
+        transaction = resolved_durable ? current_open_transaction : nil
+        if transaction
+          transaction.after_commit { submit.call }
+        else
+          submit.call
+        end
+        nil
+      end
+
+      # Resolves the coalescing window in ms. `true` → the default window;
+      # a positive Numeric is used as-is. Anything else is a misuse and is
+      # rejected at the API boundary with an actionable error rather than a
+      # cryptic NoMethodError deep inside the coalescer's timer math.
+      def coalesce_window_ms(coalesce)
+        return Coalescer::DEFAULT_WINDOW_MS if coalesce == true
+        return coalesce if coalesce.is_a?(Numeric) && coalesce.positive?
+
+        raise ArgumentError,
+              "coalesce: must be true or a positive Numeric window in milliseconds, got #{coalesce.inspect}"
+      end
+
       def ensure_queue!
         return if @ensured
 

data/lib/pgbus/version.rb

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

data/lib/pgbus/web/data_source.rb

@@ -590,6 +590,43 @@ module Pgbus
         []
       end
 
+      # Batches
+      def batches(limit: 100)
+        BatchEntry.order(created_at: :desc).limit(limit).map { |r| format_batch(r) }
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error fetching batches: #{e.message}" }
+        []
+      end
+
+      def batch_detail(batch_id)
+        record = BatchEntry.find_by(batch_id: batch_id)
+        return nil unless record
+
+        format_batch(record).merge(
+          properties: record.properties,
+          on_finish_class: record.on_finish_class,
+          on_success_class: record.on_success_class,
+          on_discard_class: record.on_discard_class
+        )
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error fetching batch #{batch_id}: #{e.message}" }
+        nil
+      end
+
+      def batches_count
+        BatchEntry.count
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error counting batches: #{e.message}" }
+        0
+      end
+
+      def active_batches_count
+        BatchEntry.where.not(status: "finished").count
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error counting active batches: #{e.message}" }
+        0
+      end
+
       # Job stats
       def job_stats_summary(minutes: 60)
         JobStat.summary(minutes: minutes)
@@ -874,6 +911,33 @@ module Pgbus
         []
       end
 
+      # NOTIFY throttle status for all queues with notifications enabled.
+      # Returns an array of hashes: { queue_name:, throttle_interval_ms:, last_notified_at: }
+      def notify_throttles
+        @client.list_notify_insert_throttles.map do |throttle|
+          {
+            queue_name: throttle.queue_name,
+            throttle_interval_ms: throttle.throttle_interval_ms,
+            last_notified_at: throttle.last_notified_at
+          }
+        end
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error fetching notify throttles: #{e.message}" }
+        []
+      end
+
+      # FIFO group head sampling for a specific queue.
+      # Returns the oldest visible message from each distinct group (up to qty).
+      # Useful for detecting head-of-line stalls in multi-tenant queues.
+      def queue_group_heads(queue_name, qty: 20)
+        logical = logical_queue_name(queue_name)
+        messages = @client.read_grouped_head(logical, qty: qty) || []
+        messages.map { |m| format_pgmq_message(m, queue_name) }
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error fetching group heads for #{queue_name}: #{e.message}" }
+        []
+      end
+
       private
 
       def connection
@@ -1114,6 +1178,19 @@ module Pgbus
         }
       end
 
+      def format_pgmq_message(msg, queue_name)
+        {
+          msg_id: msg.msg_id.to_i,
+          read_ct: msg.read_ct.to_i,
+          enqueued_at: msg.enqueued_at,
+          last_read_at: msg.respond_to?(:last_read_at) ? msg.last_read_at : nil,
+          vt: msg.respond_to?(:vt) ? msg.vt : nil,
+          message: msg.message,
+          headers: msg.headers,
+          queue_name: queue_name
+        }
+      end
+
       def format_process(row)
         heartbeat = row["last_heartbeat_at"]
         heartbeat_time = heartbeat.is_a?(String) ? Time.parse(heartbeat) : heartbeat
@@ -1131,6 +1208,25 @@ module Pgbus
         }
       end
 
+      def format_batch(record)
+        total = record.total_jobs
+        done = record.completed_jobs + record.discarded_jobs
+        pct = total.positive? ? ((done * 100) / total) : 100
+
+        {
+          batch_id: record.batch_id,
+          description: record.description,
+          status: record.status,
+          total_jobs: total,
+          completed_jobs: record.completed_jobs,
+          discarded_jobs: record.discarded_jobs,
+          failed_jobs: record.failed_jobs,
+          progress_pct: pct,
+          created_at: record.created_at,
+          finished_at: record.finished_at
+        }
+      end
+
       def sanitize_name(name)
         QueueNameValidator.sanitize!(name)
       end

data/lib/pgbus/web/stream_app.rb

@@ -117,10 +117,11 @@ module Pgbus
         hijack_result = env["rack.hijack"].call
         io = hijack_result || env["rack.hijack_io"]
 
-        write_headers(io, stream_name: stream_name, since_id: since_id)
+        connection_id = SecureRandom.hex(8)
+        write_headers(io, stream_name: stream_name, since_id: since_id, connection_id: connection_id)
 
         connection = Pgbus::Web::Streamer::Connection.new(
-          id: SecureRandom.hex(8),
+          id: connection_id,
           stream_name: stream_name,
           io: io,
           since_id: since_id,
@@ -138,14 +139,16 @@ module Pgbus
         require_relative "streamer/falcon_connection" unless defined?(Pgbus::Web::Streamer::FalconConnection)
 
         body = ::Protocol::HTTP::Body::Writable.new
+        connection_id = SecureRandom.hex(8)
 
         body.write(Pgbus::Streams::Envelope.retry_directive(2_000))
         body.write(Pgbus::Streams::Envelope.comment(
                      "pgbus stream open since_id=#{since_id} stream=#{stream_name}"
                    ))
+        body.write(Pgbus::Streams::Envelope.connected(id: connection_id))
 
         connection = Pgbus::Web::Streamer::FalconConnection.new(
-          id: SecureRandom.hex(8),
+          id: connection_id,
           stream_name: stream_name,
           body: body,
           since_id: since_id,
@@ -165,10 +168,11 @@ module Pgbus
         }
       end
 
-      def write_headers(io, stream_name:, since_id:)
+      def write_headers(io, stream_name:, since_id:, connection_id:)
         io.write(Pgbus::Streams::Envelope.http_response_headers)
         io.write(Pgbus::Streams::Envelope.retry_directive(2_000))
         io.write(Pgbus::Streams::Envelope.comment("pgbus stream open since_id=#{since_id} stream=#{stream_name}"))
+        io.write(Pgbus::Streams::Envelope.connected(id: connection_id))
       end
 
       def streamer

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

@@ -14,6 +14,10 @@ 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, :last_msg_id_sent, :context
+        # 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
 
         def initialize(id:, stream_name:, io:, since_id:, writer:, write_deadline_ms:, context: nil)
           @id = id
@@ -25,6 +29,7 @@ module Pgbus
           @mutex = Mutex.new
           @dead = false
           @closed = false
+          @presence_member = nil
           @created_at = monotonic
           @last_write_at = @created_at
           # Context is whatever the StreamApp's authorize hook returned
@@ -43,7 +48,7 @@ module Pgbus
 
             bytes = Pgbus::Streams::Envelope.message(
               id: envelope.msg_id,
-              event: "turbo-stream",
+              event: sse_event_for(envelope),
               data: envelope.payload
             )
 
@@ -115,6 +120,15 @@ module Pgbus
 
         private
 
+        # The SSE event name for a frame: the envelope's typed event when
+        # present, else the default turbo-stream. Plain ReadAfter::Envelopes
+        # (no event field) and StreamEnvelopes with a nil event both fall
+        # back to the default. (issue #170)
+        def sse_event_for(envelope)
+          event = envelope.respond_to?(:event) ? envelope.event : nil
+          event && !event.to_s.empty? ? event.to_s : Pgbus::Streams::DEFAULT_SSE_EVENT
+        end
+
         def monotonic
           # Qualify ::Process because Pgbus::Process already exists as a
           # namespace for worker/supervisor/consumer and would otherwise

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

@@ -13,6 +13,7 @@ module Pgbus
       # is fiber-safe under Falcon's scheduler.
       class FalconConnection
         attr_reader :id, :stream_name, :io, :mutex, :last_msg_id_sent, :context
+        attr_accessor :presence_member
 
         def initialize(id:, stream_name:, body:, since_id:, write_deadline_ms:, context: nil)
           @id = id
@@ -24,6 +25,7 @@ module Pgbus
           @mutex = Mutex.new
           @dead = false
           @closed = false
+          @presence_member = nil
           @created_at = monotonic
           @last_write_at = @created_at
           @context = context
@@ -36,7 +38,7 @@ module Pgbus
 
             bytes = Pgbus::Streams::Envelope.message(
               id: envelope.msg_id,
-              event: "turbo-stream",
+              event: sse_event_for(envelope),
               data: envelope.payload
             )
 
@@ -94,6 +96,12 @@ module Pgbus
 
         private
 
+        # See Connection#sse_event_for. (issue #170)
+        def sse_event_for(envelope)
+          event = envelope.respond_to?(:event) ? envelope.event : nil
+          event && !event.to_s.empty? ? event.to_s : Pgbus::Streams::DEFAULT_SSE_EVENT
+        end
+
         def write_to_body(bytes)
           @mutex.synchronize do
             return :closed if @dead || @body.closed?

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

@@ -61,6 +61,7 @@ module Pgbus
         # code goes through the background thread.
         def tick
           now = @clock.call
+          presence_conns = []
           @registry.each_connection do |connection|
             if connection.dead?
               # Already dead (e.g. IoWriter returned :closed on a previous
@@ -76,8 +77,15 @@ module Pgbus
             end
 
             result = connection.write_comment("heartbeat #{now.to_i}")
-            enqueue_disconnect(connection) if connection.dead? || result != :ok
+            if connection.dead? || result != :ok
+              enqueue_disconnect(connection)
+              next
+            end
+
+            presence_conns << connection if presence_member?(connection)
           end
+
+          enqueue_presence_touch(presence_conns)
         end
 
         private
@@ -99,6 +107,20 @@ module Pgbus
         def enqueue_disconnect(connection)
           @queue << StreamEventDispatcher::DisconnectMessage.new(connection: connection)
         end
+
+        def presence_member?(connection)
+          connection.respond_to?(:presence_member) && !connection.presence_member.nil?
+        end
+
+        # 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.
+        def enqueue_presence_touch(connections)
+          return if connections.empty?
+
+          @queue << StreamEventDispatcher::PresenceTouchMessage.new(connections: connections)
+        end
       end
     end
   end