pgbus 0.7.2 → 0.7.4

data/lib/pgbus/testing.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "pgbus"
+
+module Pgbus
+  # Test helpers for Pgbus EventBus. Opt-in via explicit require — never
+  # autoloaded by Zeitwerk so this code never leaks into production.
+  #
+  #   require "pgbus/testing"          # core only
+  #   require "pgbus/testing/rspec"    # RSpec matchers + auto-config
+  #   require "pgbus/testing/minitest" # Minitest assertions
+  #
+  # Three modes:
+  #   :fake     — capture published events in an in-memory store (default for tests)
+  #   :inline   — capture AND immediately dispatch to matching handlers
+  #   :disabled — pass through to the real publisher (production behavior)
+  module Testing
+    MODES = %i[fake inline disabled].freeze
+    MODE_KEY = :__pgbus_test_mode
+
+    # Thread-safe in-memory store for events captured in fake/inline mode.
+    class EventStore
+      def initialize
+        @mutex = Mutex.new
+        @events = []
+      end
+
+      def push_event(event)
+        @mutex.synchronize { @events << event }
+      end
+
+      def events(routing_key: nil)
+        @mutex.synchronize do
+          result = @events.dup
+          result = result.select { |e| e.routing_key == routing_key } if routing_key
+          result
+        end
+      end
+
+      def size
+        @mutex.synchronize { @events.size }
+      end
+
+      def clear!
+        @mutex.synchronize { @events.clear }
+      end
+
+      # Dispatch all stored events to their matching handlers, then clear.
+      # Events are removed one at a time after successful dispatch so that
+      # a handler exception leaves unprocessed events in the store.
+      def drain!
+        loop do
+          event = @mutex.synchronize { @events.first }
+          break unless event
+
+          Pgbus::EventBus::Registry.instance.handlers_for(event.routing_key).each do |subscriber|
+            subscriber.handler_class.new.handle(event)
+          end
+
+          @mutex.synchronize { @events.shift }
+        end
+      end
+    end
+
+    # Eagerly initialize the store so concurrent access never races on creation.
+    @store = EventStore.new
+
+    class << self
+      def mode!(mode, &block)
+        raise ArgumentError, "Unknown mode: #{mode}. Valid modes: #{MODES.join(", ")}" unless MODES.include?(mode)
+
+        sync_streams_test_mode!(mode)
+
+        unless block
+          Thread.main[MODE_KEY] = mode
+          return
+        end
+
+        old = Thread.current[MODE_KEY]
+        Thread.current[MODE_KEY] = mode
+        yield
+      ensure
+        if block
+          Thread.current[MODE_KEY] = old
+          sync_streams_test_mode!(old || :disabled)
+        end
+      end
+
+      def mode
+        Thread.current[MODE_KEY] || Thread.main[MODE_KEY] || :disabled
+      end
+
+      def fake!(&) = mode!(:fake, &)
+      def inline!(&) = mode!(:inline, &)
+      def disabled!(&) = mode!(:disabled, &)
+
+      def fake?     = mode == :fake
+      def inline?   = mode == :inline
+      def disabled? = mode == :disabled
+
+      attr_reader :store
+
+      private
+
+      # When entering fake/inline mode, enable streams_test_mode to prevent
+      # rack.hijack from spawning background threads that acquire DB
+      # connections outside the test transaction (see issue #133). When
+      # returning to :disabled mode, restore the previous setting.
+      def sync_streams_test_mode!(mode)
+        return unless defined?(Pgbus.configuration)
+
+        if mode == :disabled
+          Pgbus.configuration.streams_test_mode = false
+          Pgbus::Web::Streamer.reset! if defined?(Pgbus::Web::Streamer)
+        else
+          Pgbus.configuration.streams_test_mode = true
+        end
+      end
+    end
+  end
+end
+
+require_relative "testing/assertions"

data/lib/pgbus/version.rb

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

data/lib/pgbus/web/data_source.rb

@@ -707,10 +707,155 @@ module Pgbus
         []
       end
 
-      # Subscriber registry
+      # Pending events — messages sitting in handler queues that haven't been processed.
+      # Identifies handler queues via the subscriber registry and queries them
+      # for unprocessed messages. Subscriber queue names are logical
+      # (e.g. "task_completion_handler"), while `pgmq.meta.queue_name` stores
+      # physical names (e.g. "pgbus_task_completion_handler"), so we normalize
+      # through `config.queue_name` before intersecting.
+      def pending_events(page: 1, per_page: 25)
+        handler_queues = handler_queue_physical_names
+        return [] if handler_queues.empty?
+
+        existing = connection.select_values(
+          "SELECT queue_name FROM pgmq.meta ORDER BY queue_name", "Pgbus Queue Names"
+        )
+        target_queues = handler_queues & existing
+        return [] if target_queues.empty?
+
+        offset = (page - 1) * per_page
+        paginated_queue_messages(target_queues, per_page, offset)
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error fetching pending events: #{e.message}" }
+        []
+      end
+
+      # Physical queue names for all registered subscribers. Used for both
+      # pending_events lookup and server-side validation of target queues
+      # in reroute_event.
+      def handler_queue_physical_names
+        registered_subscribers.map { |s| s[:physical_queue_name] }.uniq
+      end
+
+      # Find the handler class registered for a given physical queue name.
+      # Returns nil if no subscriber matches — used to reject forged handler
+      # values in mark_event_handled / reroute_event.
+      def handler_class_for_queue(physical_queue_name)
+        sub = registered_subscribers.find { |s| s[:physical_queue_name] == physical_queue_name }
+        sub && sub[:handler_class]
+      end
+
+      # Discard (archive) an event message from a handler queue.
+      def discard_event(queue_name, msg_id)
+        release_lock_for_message(queue_name, msg_id)
+        @client.archive_message(queue_name, msg_id.to_i, prefixed: false)
+        true
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error discarding event #{msg_id}: #{e.message}" }
+        false
+      end
+
+      # Mark an event as handled: archive the queue message and insert a
+      # ProcessedEvent record so it won't be reprocessed on replay.
+      #
+      # The insert is performed BEFORE archive. If the archive step fails
+      # afterwards the operator can retry — replay protection is already in
+      # place and the idempotency dedup will cause the handler to skip the
+      # event even if it is eventually re-read from the queue. Doing it the
+      # other way around would risk losing the message without recording the
+      # marker.
+      def mark_event_handled(queue_name, msg_id, handler_class)
+        detail = job_detail(queue_name, msg_id)
+        return false unless detail
+
+        raw = JSON.parse(detail[:message])
+        event_id = raw["event_id"]
+        return false unless event_id
+
+        ProcessedEvent.insert(
+          { event_id: event_id, handler_class: handler_class, processed_at: Time.now.utc },
+          unique_by: %i[event_id handler_class]
+        )
+        # Release the uniqueness lock while we still hold the payload in
+        # memory — otherwise the message is archived but the lock row stays
+        # behind, blocking later publishes with the same key. Mirrors
+        # discard_event.
+        release_lock_for_payload(detail[:message])
+        @client.archive_message(queue_name, msg_id.to_i, prefixed: false)
+        true
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error marking event #{msg_id} handled: #{e.message}" }
+        false
+      end
+
+      # Edit the payload of a stuck event: delete old message and re-enqueue
+      # with the corrected payload in the same queue. The produce + delete
+      # are wrapped in a PGMQ transaction so the message can't be lost if
+      # either half fails (same pattern as retry_dlq_message).
+      def edit_event_payload(queue_name, msg_id, new_payload_json)
+        begin
+          parsed = JSON.parse(new_payload_json)
+        rescue JSON::ParserError
+          return false
+        end
+
+        detail = job_detail(queue_name, msg_id)
+        return false unless detail
+
+        @client.transaction do |txn|
+          txn.produce(queue_name, parsed.to_json, headers: detail[:headers])
+          txn.delete(queue_name, msg_id.to_i)
+        end
+        true
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error editing event #{msg_id}: #{e.message}" }
+        false
+      end
+
+      # Reroute an event from one handler queue to another. Wrapped in a
+      # PGMQ transaction so produce on the target and delete on the source
+      # are atomic.
+      def reroute_event(source_queue, msg_id, target_queue)
+        detail = job_detail(source_queue, msg_id)
+        return false unless detail
+
+        @client.transaction do |txn|
+          txn.produce(target_queue, detail[:message], headers: detail[:headers])
+          txn.delete(source_queue, msg_id.to_i)
+        end
+        true
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error rerouting event #{msg_id}: #{e.message}" }
+        false
+      end
+
+      # Bulk discard selected events from handler queues.
+      def discard_selected_events(selections)
+        return 0 if selections.empty?
+
+        count = 0
+        selections.each do |sel|
+          discard_event(sel[:queue_name], sel[:msg_id]) && count += 1
+        rescue StandardError => e
+          Pgbus.logger.debug { "[Pgbus::Web] Error in bulk discard for #{sel[:msg_id]}: #{e.message}" }
+          next
+        end
+        count
+      end
+
+      # Subscriber registry. `queue_name` is the logical name the subscriber
+      # registered with; `physical_queue_name` is what the queue is actually
+      # called in `pgmq.meta` (e.g. logical "task_completion_handler" ->
+      # physical "pgbus_task_completion_handler"). The dashboard needs the
+      # physical name to match against pending messages / target queues.
       def registered_subscribers
         EventBus::Registry.instance.subscribers.map do |s|
-          { pattern: s.pattern, handler_class: s.handler_class.name, queue_name: s.queue_name }
+          {
+            pattern: s.pattern,
+            handler_class: s.handler_class.name,
+            queue_name: s.queue_name,
+            physical_queue_name: @client.config.queue_name(s.queue_name)
+          }
         end
       rescue StandardError => e
         Pgbus.logger.debug { "[Pgbus::Web] Error fetching subscribers: #{e.message}" }

data/lib/pgbus/web/stream_app.rb

@@ -62,6 +62,8 @@ module Pgbus
         cursor = parse_cursor(env, request)
         return bad_request("invalid cursor: #{cursor}") if cursor.is_a?(String)
 
+        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
@@ -210,6 +212,11 @@ module Pgbus
       def server_error
         [500, { "content-type" => "text/plain" }, ["pgbus: internal error"]]
       end
+
+      def test_mode_stub
+        body = ": pgbus test mode — connection accepted, no polling\n\n"
+        [200, sse_headers, [body]]
+      end
     end
   end
 end

data/lib/pgbus.rb

@@ -39,6 +39,7 @@ module Pgbus
         )
         loader.ignore("#{__dir__}/generators")
         loader.ignore("#{__dir__}/active_job")
+        loader.ignore("#{__dir__}/pgbus/testing")
         # lib/puma/plugin/pgbus_streams.rb is a Puma plugin — it's required
         # explicitly by the user from config/puma.rb via `plugin :pgbus_streams`.
         # Without this ignore, Zeitwerk scans lib/puma/ under the pgbus loader

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.7.4
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -170,6 +170,7 @@ files:
 - app/views/pgbus/dead_letter/_messages_table.html.erb
 - app/views/pgbus/dead_letter/index.html.erb
 - app/views/pgbus/dead_letter/show.html.erb
+- app/views/pgbus/events/_pending_table.html.erb
 - app/views/pgbus/events/index.html.erb
 - app/views/pgbus/events/show.html.erb
 - app/views/pgbus/insights/show.html.erb
@@ -308,6 +309,10 @@ files:
 - lib/pgbus/streams/turbo_broadcastable.rb
 - lib/pgbus/streams/turbo_stream_override.rb
 - lib/pgbus/streams/watermark_cache_middleware.rb
+- lib/pgbus/testing.rb
+- lib/pgbus/testing/assertions.rb
+- lib/pgbus/testing/minitest.rb
+- lib/pgbus/testing/rspec.rb
 - lib/pgbus/uniqueness.rb
 - lib/pgbus/version.rb
 - lib/pgbus/web/authentication.rb