pgbus 0.7.3 → 0.7.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d07ecda9d90b73fa2ab8d9a34bf775b305bba9349dd5d49c99b587ea5b614bc
-  data.tar.gz: af072bf9e30ead0928db95896380384c49d8a49a59994864693aea80dd249bda
+  metadata.gz: 3c1610b9a423eb2d8cc6797176ec23ce9ddadab1b313f8c1ee985327a6af0c42
+  data.tar.gz: b7369612f3ac54bc3bef2e9fbec4afcc8c31a632edd667ab91d03d750f1c3e4c
 SHA512:
-  metadata.gz: 49eccf16ff1d0dcdec75f111bda474b343f3cf154b14569d19138f1b666457d71482037e390f4faa7136e21ead14b32a8a9408d18256843992e83476424a333c
-  data.tar.gz: 0d78309574c68a90b59b276b7648ac17cd8c74f3dbedebbd3d6cabe70a062a4d879cac19da8b2ab6ac78584f671ec7eda1db37fa459ecd761b81f0cd5c81ded0
+  metadata.gz: 906567f5015468dad875c7d4948979fb78b095e1433838cbb3761eff02d54b3186a251a44e8d52508a3fd6b8cb540648d79eded23301561346f4d97878c63b11
+  data.tar.gz: 24cdb2845692e0172681fa899f5b8dac743ef00d214b0e09f4f9a0836f042026f0cceda1fab76851a52028b8b50101df9158907d487752dd301f4b28aed9466c

data/README.md

@@ -37,6 +37,13 @@ PostgreSQL-native job processing and event bus for Rails, built on [PGMQ](https:
   - [Structured logging](#structured-logging)
   - [Queue health monitoring](#queue-health-monitoring)
 - [Real-time broadcasts](#real-time-broadcasts-turbo-streams-replacement)
+- [Testing](#testing)
+  - [RSpec setup](#rspec-setup)
+  - [Minitest / TestUnit setup](#minitest--testunit-setup)
+  - [Event bus assertions](#event-bus-assertions)
+  - [RSpec matchers](#rspec-matchers)
+  - [Testing modes](#testing-modes)
+  - [SSE streams in tests](#sse-streams-in-tests)
 - [Operations](#operations)
   - [CLI](#cli)
   - [Dashboard](#dashboard)
@@ -1058,6 +1065,234 @@ The Insights tab gains a "Real-time Streams" section with counts of broadcasts /
 
 Overhead on a real Puma + PGMQ setup (`bundle exec rake bench:streams`): the most visible cost is an INSERT per connect/disconnect pair, which shows up under thundering-herd connect scenarios (K=50 concurrent connects: ~+20% per-connect latency). Steady-state broadcast and fanout numbers stay in the run-to-run noise band. Enable it if Insights is useful; leave it off if the write traffic worries you.
 
+## Testing
+
+Pgbus ships opt-in test helpers for both RSpec and Minitest. The testing module is **never autoloaded** by Zeitwerk -- you must `require` it explicitly, so it cannot leak into production.
+
+### RSpec setup
+
+Add one line to your `spec/rails_helper.rb` (or `spec/spec_helper.rb`):
+
+```ruby
+# spec/rails_helper.rb
+require "pgbus/testing/rspec"
+```
+
+This does three things:
+
+1. Loads `Pgbus::Testing` with the in-memory `EventStore` and mode management
+2. Registers the `have_published_event` matcher
+3. Includes `Pgbus::Testing::Assertions` into all example groups
+
+You still need to activate a testing mode and clear the store per test. Add a `before`/`after` block:
+
+```ruby
+# spec/rails_helper.rb
+require "pgbus/testing/rspec"
+
+RSpec.configure do |config|
+  config.before { Pgbus::Testing.fake! }
+  config.after do
+    Pgbus::Testing.disabled!
+    Pgbus::Testing.store.clear!
+  end
+end
+```
+
+Or scope it to specific groups:
+
+```ruby
+RSpec.configure do |config|
+  config.before(:each, :pgbus) { Pgbus::Testing.fake! }
+  config.after(:each, :pgbus) do
+    Pgbus::Testing.disabled!
+    Pgbus::Testing.store.clear!
+  end
+end
+
+# Usage:
+RSpec.describe OrderService, :pgbus do
+  it "publishes an event" do
+    expect { described_class.create!(attrs) }
+      .to have_published_event("orders.created")
+  end
+end
+```
+
+### Minitest / TestUnit setup
+
+Add the require and include to your `test/test_helper.rb`:
+
+```ruby
+# test/test_helper.rb
+require "pgbus/testing/minitest"
+
+class ActiveSupport::TestCase
+  include Pgbus::Testing::MinitestHelpers
+end
+```
+
+`MinitestHelpers` hooks into Minitest's lifecycle automatically:
+
+- **`before_setup`** -- activates `:fake` mode and clears the event store before each test
+- Includes all assertion helpers (`assert_pgbus_published`, `assert_no_pgbus_published`, `pgbus_published_events`, `perform_published_events`)
+
+No additional `setup`/`teardown` blocks are needed -- the module handles it.
+
+### Event bus assertions
+
+Both RSpec and Minitest share the same assertion helpers via `Pgbus::Testing::Assertions`:
+
+```ruby
+# Assert that a block publishes exactly N events
+assert_pgbus_published(count: 1, routing_key: "orders.created") do
+  OrderService.create!(attrs)
+end
+
+# Assert that a block publishes zero events
+assert_no_pgbus_published(routing_key: "orders.created") do
+  OrderService.preview(attrs)
+end
+
+# Inspect captured events directly
+events = pgbus_published_events(routing_key: "orders.created")
+assert_equal 1, events.size
+assert_equal({ "id" => 42 }, events.first.payload)
+
+# Capture events, then dispatch them to registered handlers
+perform_published_events do
+  OrderService.create!(attrs)
+end
+# After the block, all captured events have been dispatched to their
+# matching handlers synchronously -- useful for testing side effects
+```
+
+### RSpec matchers
+
+The `have_published_event` matcher supports chainable constraints:
+
+```ruby
+# Basic: assert any event was published with the given routing key
+expect { publish_order(order) }
+  .to have_published_event("orders.created")
+
+# With payload matching (uses RSpec's values_match?, so hash_including works)
+expect { publish_order(order) }
+  .to have_published_event("orders.created")
+  .with_payload(hash_including("id" => order.id))
+
+# With header matching
+expect { publish_order(order) }
+  .to have_published_event("orders.created")
+  .with_headers(hash_including("x-tenant" => "acme"))
+
+# Exact count
+expect { publish_order(order) }
+  .to have_published_event("orders.created")
+  .exactly(1)
+
+# Combine all constraints
+expect { publish_order(order) }
+  .to have_published_event("orders.created")
+  .with_payload(hash_including("id" => order.id))
+  .with_headers(hash_including("x-tenant" => "acme"))
+  .exactly(1)
+
+# Negated
+expect { publish_order(order) }
+  .not_to have_published_event("orders.cancelled")
+```
+
+### Testing modes
+
+Three modes control how `Pgbus::EventBus::Publisher.publish` behaves:
+
+| Mode | Behavior | Use case |
+|------|----------|----------|
+| `:fake` | Captures events in-memory, no PGMQ calls, no handler dispatch | Most unit/integration tests |
+| `:inline` | Captures events AND immediately dispatches to matching handlers | Testing side effects (handler logic) |
+| `:disabled` | Pass-through to real publisher (production behavior) | Default; integration tests with real PGMQ |
+
+Switch modes globally or scoped to a block:
+
+```ruby
+# Global (persists until changed)
+Pgbus::Testing.fake!
+Pgbus::Testing.inline!
+Pgbus::Testing.disabled!
+
+# Scoped (restores previous mode after block)
+Pgbus::Testing.inline! do
+  OrderService.create!(attrs)  # handlers fire synchronously
+end
+# mode is restored to whatever it was before
+
+# Query current mode
+Pgbus::Testing.fake?     # => true/false
+Pgbus::Testing.inline?   # => true/false
+Pgbus::Testing.disabled? # => true/false
+```
+
+The `:inline` mode skips delayed publishes (`delay: > 0`) -- those are captured in the store but not dispatched. Use `Pgbus::Testing.store.drain!` to manually dispatch all captured events including delayed ones.
+
+### SSE streams in tests
+
+When using `use_transactional_fixtures = true` (the default in Rails), pgbus SSE streams are incompatible with transactional test isolation. The `rack.hijack` mechanism spawns background threads that acquire their own database connections outside the test transaction, which causes:
+
+- Connection pool exhaustion after enough system tests
+- CI hangs (tests freeze waiting for a connection)
+- `Errno::EPIPE` errors when the browser navigates away
+
+**Automatic fix with `Pgbus::Testing`:** When you activate `:fake` or `:inline` mode (as shown above), pgbus automatically enables `streams_test_mode`. The SSE endpoint returns a stub response (valid SSE headers + a comment + immediate close) without hijacking, without spawning background threads, and without acquiring any database connections. The `<pgbus-stream-source>` custom element still renders and connects, but no PGMQ polling occurs.
+
+If you're using the RSpec or Minitest setup shown above, **you don't need to do anything extra** -- streams are safe automatically.
+
+**Manual configuration** (if you don't use `Pgbus::Testing`):
+
+```ruby
+# config/initializers/pgbus.rb
+Pgbus.configure do |c|
+  c.streams_test_mode = true if Rails.env.test?
+end
+```
+
+Or toggle it per test:
+
+```ruby
+# RSpec
+before { Pgbus.configuration.streams_test_mode = true }
+after  { Pgbus.configuration.streams_test_mode = false }
+
+# Minitest
+setup    { Pgbus.configuration.streams_test_mode = true }
+teardown { Pgbus.configuration.streams_test_mode = false }
+```
+
+**What `streams_test_mode` does:** The `StreamApp` short-circuits after signature verification and authorization checks but before any hijack, streaming body, or capacity logic. It returns:
+
+```
+HTTP/1.1 200 OK
+Content-Type: text/event-stream
+Cache-Control: no-cache, no-transform
+
+: pgbus test mode — connection accepted, no polling
+```
+
+This is a valid SSE response that the browser's EventSource will accept. No `Streamer` singleton is created, no PG LISTEN connection is opened, and no dispatcher/heartbeat/listener threads are spawned.
+
+**Testing actual stream delivery:** If you need to verify end-to-end SSE message delivery in integration tests, disable `streams_test_mode` and use the `PumaTestHarness` from the pgbus test support:
+
+```ruby
+require "pgbus/testing"
+
+Pgbus::Testing.disabled! do
+  # streams_test_mode is automatically disabled
+  # Use real Puma + real PGMQ for end-to-end stream tests
+end
+```
+
+See `spec/integration/streams/` in the pgbus source for examples of integration tests that exercise the full SSE pipeline with a real Puma server.
+
 ## Operations
 
 Day-to-day running of Pgbus: starting and stopping processes, observing what is happening on the dashboard, the database tables Pgbus relies on, and how to migrate from an existing job backend.
@@ -1240,6 +1475,7 @@ PostgreSQL + PGMQ
 | `web_live_updates` | `true` | Enable Turbo Frames auto-refresh on dashboard |
 | `stats_enabled` | `true` | Record job execution stats for insights dashboard |
 | `stats_retention` | `30.days` | How long to keep job stats. Accepts seconds, Duration, or `nil` to disable cleanup |
+| `streams_test_mode` | `false` | Return a stub SSE response without hijack or background threads. Auto-enabled by `Pgbus::Testing.fake!`/`.inline!`. See [SSE streams in tests](#sse-streams-in-tests). |
 | `streams_stats_enabled` | `false` | Record stream broadcast/connect/disconnect stats (opt-in, can be high volume) |
 | `streams_path` | `nil` | Custom URL path for the SSE endpoint (nil = auto-detected from engine mount) |
 | `execution_mode` | `:threads` | Global execution mode (`:threads` or `:async`). Per-worker override via capsule config. |

data/app/controllers/pgbus/events_controller.rb

@@ -5,6 +5,7 @@ module Pgbus
     def index
       @events = data_source.processed_events(page: page_param, per_page: per_page)
       @subscribers = data_source.registered_subscribers
+      @pending = data_source.pending_events(page: page_param, per_page: per_page)
     end
 
     def show
@@ -14,10 +15,105 @@ module Pgbus
     def replay
       event = data_source.processed_event(params[:id])
       if event && data_source.replay_event(event)
-        redirect_to events_path, notice: "Event replayed."
+        redirect_to events_path, notice: t("pgbus.events.flash.replayed")
       else
-        redirect_to events_path, alert: "Event not found or could not be replayed."
+        redirect_to events_path, alert: t("pgbus.events.flash.replay_failed")
       end
     end
+
+    def discard
+      queue_name = params[:queue_name].to_s
+      return reject_unknown_queue(:discard_failed) unless registered_queue?(queue_name)
+
+      if data_source.discard_event(queue_name, params[:id])
+        redirect_to events_path, notice: t("pgbus.events.flash.discarded")
+      else
+        redirect_to events_path, alert: t("pgbus.events.flash.discard_failed")
+      end
+    end
+
+    def mark_handled
+      queue_name = params[:queue_name].to_s
+      return reject_unknown_queue(:mark_handled_failed) unless registered_queue?(queue_name)
+
+      # Resolve the handler class server-side from the subscriber registry
+      # instead of trusting params[:handler_class] — otherwise a crafted POST
+      # could create ProcessedEvent markers for arbitrary class names and
+      # corrupt replay/idempotency state.
+      handler_class = data_source.handler_class_for_queue(queue_name)
+      if handler_class && data_source.mark_event_handled(queue_name, params[:id], handler_class)
+        redirect_to events_path, notice: t("pgbus.events.flash.marked_handled")
+      else
+        redirect_to events_path, alert: t("pgbus.events.flash.mark_handled_failed")
+      end
+    end
+
+    def edit_payload
+      queue_name = params[:queue_name].to_s
+      return reject_unknown_queue(:payload_update_failed) unless registered_queue?(queue_name)
+
+      new_payload = params[:payload].to_s
+      if data_source.edit_event_payload(queue_name, params[:id], new_payload)
+        redirect_to events_path, notice: t("pgbus.events.flash.payload_updated")
+      else
+        redirect_to events_path, alert: t("pgbus.events.flash.payload_update_failed")
+      end
+    end
+
+    def reroute
+      source_queue = params[:queue_name].to_s
+      target_queue = params[:target_queue].to_s
+      # Reject rerouting to/from any queue that isn't a registered handler —
+      # the UI dropdown is not a real server-side constraint, so a crafted
+      # POST could otherwise touch arbitrary queues.
+      allowed = registered_queue?(source_queue) && registered_queue?(target_queue)
+      return reject_unknown_queue(:reroute_failed) unless allowed
+
+      if data_source.reroute_event(source_queue, params[:id], target_queue)
+        redirect_to events_path, notice: t("pgbus.events.flash.rerouted")
+      else
+        redirect_to events_path, alert: t("pgbus.events.flash.reroute_failed")
+      end
+    end
+
+    def discard_selected
+      # Guard against non-hash entries in params[:messages] — a crafted POST
+      # can otherwise raise NoMethodError on [:queue_name]. Mirrors the
+      # hardening already used in jobs_controller#discard_selected_enqueued.
+      # Also whitelist queue_name per selection so operators can't archive
+      # arbitrary non-handler queues through this endpoint.
+      allowed = registered_queues
+      selections = Array(params[:messages]).filter_map do |s|
+        next unless s.respond_to?(:[])
+
+        queue_name = s[:queue_name]
+        msg_id = s[:msg_id]
+        next if queue_name.blank? || msg_id.blank?
+        next unless allowed.include?(queue_name.to_s)
+
+        { queue_name: queue_name.to_s, msg_id: msg_id }
+      end
+      if selections.empty?
+        redirect_to events_path, alert: t("pgbus.events.flash.none_selected")
+        return
+      end
+
+      count = data_source.discard_selected_events(selections)
+      redirect_to events_path, notice: t("pgbus.events.flash.discarded_selected", count: count)
+    end
+
+    private
+
+    def registered_queues
+      @registered_queues ||= data_source.handler_queue_physical_names
+    end
+
+    def registered_queue?(name)
+      registered_queues.include?(name)
+    end
+
+    def reject_unknown_queue(flash_key)
+      redirect_to events_path, alert: t("pgbus.events.flash.#{flash_key}")
+    end
   end
 end

data/app/views/pgbus/events/_pending_table.html.erb

@@ -0,0 +1,148 @@
+<turbo-frame id="pending-events">
+  <%# Bulk form outside table to avoid nested form issues %>
+  <form id="bulk-discard-events-form" action="<%= pgbus.discard_selected_events_path %>" method="post" data-turbo-frame="_top" class="hidden">
+    <%= hidden_field_tag :authenticity_token, form_authenticity_token %>
+  </form>
+  <div class="overflow-hidden rounded-lg bg-white dark:bg-gray-800 shadow ring-1 ring-gray-200 dark:ring-gray-700" data-bulk-scope="events">
+    <table class="pgbus-table min-w-full divide-y divide-gray-200 dark:divide-gray-700">
+      <thead class="bg-gray-50 dark:bg-gray-900">
+        <tr>
+          <% if @pending.any? %>
+            <th class="w-10 px-4 py-3">
+              <input type="checkbox" data-bulk-select-all
+                     aria-label="<%= t("pgbus.helpers.bulk_select_all") %>"
+                     class="h-4 w-4 rounded border-gray-300 text-indigo-600 focus:ring-indigo-600">
+            </th>
+          <% end %>
+          <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500"><%= t("pgbus.events.index.pending_headers.id") %></th>
+          <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500"><%= t("pgbus.events.index.pending_headers.routing_key") %></th>
+          <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500"><%= t("pgbus.events.index.pending_headers.handler_queue") %></th>
+          <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500"><%= t("pgbus.events.index.pending_headers.enqueued") %></th>
+          <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500"><%= t("pgbus.events.index.pending_headers.reads") %></th>
+        </tr>
+      </thead>
+      <tbody class="divide-y divide-gray-100 dark:divide-gray-700">
+        <% @pending.each do |m| %>
+          <%# Preserve the raw message so corrupt payloads stay visible in the
+              edit textarea and full-JSON panel. pgbus_parse_message swallows
+              JSON::ParserError and returns {}, which would otherwise hide
+              exactly the data the operator is trying to inspect/repair.
+              Also coerce scalar JSON values (numbers, booleans, nil, arrays)
+              to {} for hash-style access below — otherwise payload["foo"]
+              raises NoMethodError. %>
+          <% payload_raw = pgbus_parse_message(m[:message]) %>
+          <% payload = payload_raw.is_a?(Hash) ? payload_raw : {} %>
+          <% parse_ok = m[:message].blank? || payload_raw != {} || m[:message].to_s.strip == "{}" %>
+          <tr>
+            <td class="w-10 px-4 py-3 align-top">
+              <input type="checkbox" data-bulk-item data-pgbus-action="bulk-row-toggle"
+                     aria-label="<%= t("pgbus.helpers.bulk_select_row", id: m[:msg_id]) %>"
+                     data-queue-name="<%= m[:queue_name] %>" data-msg-id="<%= m[:msg_id] %>"
+                     class="h-4 w-4 rounded border-gray-300 text-indigo-600 focus:ring-indigo-600 mt-1">
+              <input type="hidden" name="messages[][queue_name]" value="<%= m[:queue_name] %>" form="bulk-discard-events-form" disabled>
+              <input type="hidden" name="messages[][msg_id]" value="<%= m[:msg_id] %>" form="bulk-discard-events-form" disabled>
+            </td>
+            <td colspan="5" class="p-0">
+              <details class="group">
+                <summary class="flex cursor-pointer hover:bg-gray-50 dark:hover:bg-gray-700/50 dark:bg-gray-900 list-none">
+                  <span class="w-16 shrink-0 px-4 py-3 text-sm font-mono text-gray-900 dark:text-white"><%= m[:msg_id] %></span>
+                  <span class="flex-1 px-4 py-3 text-sm font-mono text-indigo-600 truncate"><%= payload["routing_key"] || payload["event_id"] || "—" %></span>
+                  <span class="w-40 shrink-0 px-4 py-3 text-sm text-gray-700"><%= m[:queue_name] %></span>
+                  <span class="w-28 shrink-0 px-4 py-3 text-sm text-gray-500"><%= pgbus_time_ago(m[:enqueued_at]) %></span>
+                  <span class="w-16 shrink-0 px-4 py-3 text-sm text-gray-500"><%= m[:read_ct] %></span>
+                </summary>
+                <div class="px-4 pb-4 bg-gray-50 dark:bg-gray-900 border-t border-gray-100">
+                  <div class="flex items-center justify-between mt-3 mb-3">
+                    <span class="text-xs font-mono text-gray-400"><%= t("pgbus.events.pending_table.event_id") %> <%= payload["event_id"] %></span>
+                    <div class="flex space-x-2">
+                      <%# Mark Handled — handler_class is resolved server-side
+                          from the subscriber registry, so we only send queue_name. %>
+                      <%= button_to t("pgbus.events.pending_table.mark_handled"),
+                            pgbus.mark_handled_event_path(m[:msg_id], queue_name: m[:queue_name]),
+                            method: :post,
+                            class: "rounded-md bg-green-600 px-3 py-1.5 text-xs font-medium text-white hover:bg-green-500",
+                            data: { turbo_confirm: t("pgbus.events.pending_table.mark_handled_confirm"), turbo_frame: "_top" } %>
+                      <%# Reroute — dropdown with available handlers %>
+                      <details class="relative inline-block">
+                        <summary class="rounded-md bg-yellow-600 px-3 py-1.5 text-xs font-medium text-white hover:bg-yellow-500 cursor-pointer list-none">
+                          <%= t("pgbus.events.pending_table.reroute") %>
+                        </summary>
+                        <div class="absolute right-0 z-10 mt-1 w-64 rounded-md bg-white dark:bg-gray-800 shadow-lg ring-1 ring-gray-200 dark:ring-gray-700 p-2">
+                          <p class="text-xs text-gray-500 mb-2"><%= t("pgbus.events.pending_table.reroute_label") %></p>
+                          <% @subscribers.each do |s| %>
+                            <% next if s[:physical_queue_name] == m[:queue_name] %>
+                            <%= button_to s[:handler_class],
+                                  pgbus.reroute_event_path(m[:msg_id], queue_name: m[:queue_name], target_queue: s[:physical_queue_name]),
+                                  method: :post,
+                                  class: "block w-full text-left rounded px-2 py-1 text-xs text-gray-700 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-700",
+                                  data: { turbo_confirm: t("pgbus.events.pending_table.reroute_confirm"), turbo_frame: "_top" } %>
+                          <% end %>
+                        </div>
+                      </details>
+                      <%# Discard %>
+                      <%= button_to t("pgbus.events.pending_table.discard"),
+                            pgbus.discard_event_path(m[:msg_id], queue_name: m[:queue_name]),
+                            method: :post,
+                            class: "rounded-md bg-red-600 px-3 py-1.5 text-xs font-medium text-white hover:bg-red-500",
+                            data: { turbo_confirm: t("pgbus.events.pending_table.discard_confirm"), turbo_frame: "_top" } %>
+                    </div>
+                  </div>
+                  <%# Payload display %>
+                  <div class="grid grid-cols-2 gap-4 mb-3">
+                    <div>
+                      <span class="text-xs font-medium text-gray-500"><%= t("pgbus.events.pending_table.arguments") %></span>
+                      <pre class="text-xs text-gray-700 bg-white dark:bg-gray-800 rounded p-2 mt-1 overflow-x-auto max-h-40"><%= parse_ok ? (JSON.pretty_generate(payload["payload"] || payload_raw) rescue "—") : m[:message] %></pre>
+                    </div>
+                    <div>
+                      <span class="text-xs font-medium text-gray-500"><%= t("pgbus.events.pending_table.metadata") %></span>
+                      <div class="text-xs text-gray-600 bg-white dark:bg-gray-800 rounded p-2 mt-1 space-y-1">
+                        <% if m[:read_ct] %><p><strong><%= t("pgbus.events.pending_table.metadata_labels.read_count") %></strong> <%= m[:read_ct] %></p><% end %>
+                        <% if m[:vt] %><p><strong><%= t("pgbus.events.pending_table.metadata_labels.visible_at") %></strong> <%= m[:vt] %></p><% end %>
+                        <% if m[:last_read_at] %><p><strong><%= t("pgbus.events.pending_table.metadata_labels.last_read") %></strong> <%= m[:last_read_at] %></p><% end %>
+                      </div>
+                    </div>
+                  </div>
+                  <%# Edit Payload form %>
+                  <details class="mt-2">
+                    <summary class="text-xs font-medium text-indigo-600 cursor-pointer hover:text-indigo-500"><%= t("pgbus.events.pending_table.edit_payload") %></summary>
+                    <div class="mt-2 p-3 bg-white dark:bg-gray-800 rounded ring-1 ring-gray-200 dark:ring-gray-700">
+                      <%= form_with url: pgbus.edit_payload_event_path(m[:msg_id]), method: :post, local: true, data: { turbo_frame: "_top" } do |f| %>
+                        <%= hidden_field_tag :queue_name, m[:queue_name] %>
+                        <label class="text-xs font-medium text-gray-500"><%= t("pgbus.events.pending_table.edit_payload_label") %></label>
+                        <textarea name="payload" rows="6"
+                                  class="mt-1 block w-full rounded-md border-gray-300 dark:border-gray-600 dark:bg-gray-900 dark:text-white text-xs font-mono shadow-sm focus:border-indigo-500 focus:ring-indigo-500"><%= parse_ok ? (JSON.pretty_generate(payload_raw) rescue m[:message]) : m[:message] %></textarea>
+                        <div class="mt-2 flex justify-end">
+                          <button type="submit"
+                                  class="rounded-md bg-indigo-600 px-3 py-1.5 text-xs font-medium text-white hover:bg-indigo-500"
+                                  data-turbo-confirm="<%= t("pgbus.events.pending_table.edit_payload_confirm") %>">
+                            <%= t("pgbus.events.pending_table.edit_payload") %>
+                          </button>
+                        </div>
+                      <% end %>
+                    </div>
+                  </details>
+                  <%# Full JSON %>
+                  <details class="mt-2">
+                    <summary class="text-xs font-medium text-gray-500 cursor-pointer hover:text-gray-700"><%= t("pgbus.events.pending_table.full_json_payload") %></summary>
+                    <pre class="text-xs text-gray-600 bg-white dark:bg-gray-800 rounded p-2 mt-1 overflow-x-auto max-h-96"><%= parse_ok ? (JSON.pretty_generate(payload_raw) rescue m[:message]) : m[:message] %></pre>
+                  </details>
+                  <% if m[:headers] %>
+                    <details class="mt-2">
+                      <summary class="text-xs font-medium text-gray-500 cursor-pointer hover:text-gray-700"><%= t("pgbus.events.pending_table.headers_section") %></summary>
+                      <pre class="text-xs text-gray-600 bg-white dark:bg-gray-800 rounded p-2 mt-1 overflow-x-auto"><%= JSON.pretty_generate(JSON.parse(m[:headers])) rescue m[:headers] %></pre>
+                    </details>
+                  <% end %>
+                </div>
+              </details>
+            </td>
+          </tr>
+        <% end %>
+        <% if @pending.empty? %>
+          <%# Header only renders the bulk-select column when rows are present,
+              so the empty-state colspan must match (5 without, 6 with). %>
+          <tr><td colspan="5" class="px-4 py-8 text-center text-sm text-gray-400"><%= t("pgbus.events.index.pending_empty") %></td></tr>
+        <% end %>
+      </tbody>
+    </table>
+  </div>
+</turbo-frame>

data/app/views/pgbus/events/index.html.erb

@@ -1,4 +1,18 @@
-<h1 class="text-2xl font-bold text-gray-900 dark:text-white mb-6"><%= t("pgbus.events.index.title") %></h1>
+<div class="flex items-center justify-between mb-6">
+  <h1 class="text-2xl font-bold text-gray-900 dark:text-white"><%= t("pgbus.events.index.title") %></h1>
+  <% if @pending.any? %>
+    <div class="flex items-center space-x-2">
+      <div data-bulk-actions class="hidden flex items-center space-x-2">
+        <span class="text-sm text-gray-500 dark:text-gray-400"><span data-bulk-count>0</span> <%= t("pgbus.helpers.bulk_selected") %></span>
+        <button type="submit" form="bulk-discard-events-form"
+                class="rounded-md bg-red-600 px-3 py-2 text-sm font-medium text-white hover:bg-red-500"
+                data-turbo-confirm="<%= t("pgbus.events.index.discard_selected_confirm") %>">
+          <%= t("pgbus.events.index.discard_selected") %>
+        </button>
+      </div>
+    </div>
+  <% end %>
+</div>
 
 <!-- Registered Subscribers -->
 <div class="mb-8">
@@ -28,6 +42,12 @@
   </div>
 </div>
 
+<!-- Pending Events (Unprocessed messages in handler queues) -->
+<div class="mb-8">
+  <h2 class="text-lg font-semibold text-gray-900 dark:text-white mb-3"><%= t("pgbus.events.index.pending_title") %></h2>
+  <%= render "pgbus/events/pending_table" %>
+</div>
+
 <!-- Processed Events (Audit Trail) -->
 <div>
   <h2 class="text-lg font-semibold text-gray-900 dark:text-white mb-3"><%= t("pgbus.events.index.processed_title") %></h2>