pgbus 0.17.1 → 0.17.2

data/lib/pgbus/web/data_source/dead_letter.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Web
+    class DataSource
+      # The dead-letter queue pages (issue #495): list, count, detail, and the
+      # retry/discard actions. Moved out of data_source.rb unchanged.
+      module DeadLetter
+        # The header path the error-class filter reads (DeadLetterHeader::KEY).
+        ERROR_CLASS_SQL = "headers #>> '{#{Pgbus::DeadLetterHeader::KEY},error_class}'".freeze
+
+        # DLQ queue names from queues_with_metrics are already fully qualified
+        # (e.g., "pgbus_default_dlq"), so we use them directly without re-prefixing.
+        # dlq: one DLQ by its full name (unknown names list nothing);
+        # error_class: only messages whose dead-letter block names that class.
+        def dlq_messages(page: 1, per_page: 25, dlq: nil, error_class: nil)
+          offset = (page - 1) * per_page
+          names = dlq_queue_names(dlq)
+          return [] if names.empty?
+          return paginated_queue_messages(names, per_page, offset) unless error_class
+
+          paginated_queue_messages(names, per_page, offset, where: "#{ERROR_CLASS_SQL} = $3", binds: [error_class])
+        rescue StandardError => e
+          Pgbus.logger.debug { "[Pgbus::Web] Error fetching DLQ messages: #{e.message}" }
+          []
+        end
+
+        def dlq_total_count(dlq: nil, error_class: nil)
+          names = dlq_queue_names(dlq)
+          return 0 if names.empty?
+          return dlq_counts_by_queue.values_at(*names).sum unless error_class
+
+          connection.select_value(
+            "SELECT COUNT(*) FROM (#{queue_message_fragments(names, "#{ERROR_CLASS_SQL} = $1")}) AS combined",
+            "Pgbus DLQ Count",
+            [error_class]
+          ).to_i
+        rescue StandardError => e
+          Pgbus.logger.debug { "[Pgbus::Web] Error fetching DLQ count: #{e.message}" }
+          0
+        end
+
+        # { "pgbus_default_dlq" => 12, ... } for the filter chips, from the
+        # cached metrics (no query of its own).
+        def dlq_counts_by_queue
+          queues_with_metrics
+            .select { |q| q[:name].end_with?(Pgbus::DEAD_LETTER_SUFFIX) }
+            .to_h { |q| [q[:name], q[:queue_length].to_i] }
+        rescue StandardError => e
+          Pgbus.logger.debug { "[Pgbus::Web] Error fetching DLQ counts: #{e.message}" }
+          {}
+        end
+
+        # msg_ids are unique per DLQ table only: queue_name: picks the table;
+        # without it the first DLQ holding the id wins.
+        def dlq_message_detail(msg_id, queue_name: nil)
+          dlq_queue_names(queue_name).each do |name|
+            row = connection.select_one(
+              "SELECT * FROM pgmq.q_#{sanitize_name(name)} WHERE msg_id = $1",
+              "Pgbus DLQ Detail",
+              [msg_id.to_i]
+            )
+            return format_message(row, name) if row
+          end
+          nil
+        rescue StandardError => e
+          Pgbus.logger.debug { "[Pgbus::Web] Error fetching DLQ message #{msg_id}: #{e.message}" }
+          nil
+        end
+
+        def retry_dlq_message(queue_name, msg_id)
+          # queue_name here is the full DLQ name (already prefixed)
+          dlq_suffix = Pgbus::DEAD_LETTER_SUFFIX
+          original_queue = queue_name.delete_suffix(dlq_suffix)
+
+          row = connection.select_one(
+            "SELECT * FROM pgmq.q_#{sanitize_name(queue_name)} WHERE msg_id = $1",
+            "Pgbus DLQ Read",
+            [msg_id.to_i]
+          )
+          return false unless row
+
+          @client.transaction do |txn|
+            # A live message must not claim to be dead: strip the block, count the trip.
+            txn.produce(original_queue, row["message"], headers: DeadLetterHeader.strip_for_retry(row["headers"]))
+            txn.delete(queue_name, msg_id.to_i)
+          end
+          true
+        rescue StandardError => e
+          Pgbus.logger.debug { "[Pgbus::Web] Error retrying DLQ message #{msg_id}: #{e.message}" }
+          false
+        end
+
+        def discard_dlq_message(queue_name, msg_id)
+          # queue_name here is the full DLQ name (already prefixed)
+          release_lock_for_message(queue_name, msg_id)
+          @client.delete_message(queue_name, msg_id.to_i, prefixed: false)
+          true
+        rescue StandardError => e
+          Pgbus.logger.debug { "[Pgbus::Web] Error discarding DLQ message #{msg_id}: #{e.message}" }
+          false
+        end
+
+        def retry_all_dlq
+          messages = dlq_messages(page: 1, per_page: 1000)
+          count = 0
+          messages.each do |m|
+            retry_dlq_message(m[:queue_name], m[:msg_id]) && count += 1
+          rescue StandardError => e
+            Pgbus.logger.debug { "[Pgbus::Web] Error retrying DLQ message #{m[:msg_id]}: #{e.message}" }
+            next
+          end
+          count
+        end
+
+        def discard_all_dlq
+          messages = dlq_messages(page: 1, per_page: 1000)
+          return 0 if messages.empty?
+
+          release_locks_for_messages(messages)
+
+          # Group by queue for batch delete — one call per DLQ instead of N calls
+          messages.group_by { |m| m[:queue_name] }.sum do |queue_name, msgs|
+            ids = msgs.map { |m| m[:msg_id].to_i }
+            @client.delete_batch(queue_name, ids, prefixed: false).size
+          rescue StandardError => e
+            Pgbus.logger.debug { "[Pgbus::Web] Error batch-discarding DLQ messages from #{queue_name}: #{e.message}" }
+            0
+          end
+        end
+
+        private
+
+        # Only names that are real DLQs ever reach sanitize_name and SQL.
+        def dlq_queue_names(dlq)
+          names = dlq_counts_by_queue.keys
+          dlq.nil? ? names : names & [dlq]
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/web/data_source/event_list.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Pgbus
+  module Web
+    class DataSource
+      # The Events page (issue #494): the unified job list scoped to the
+      # EventBus handler queues, the words EventState needs about consumers,
+      # and Replay of a processed event from its archived message.
+      #
+      # Handler names and patterns come from the subscriber registry, in Ruby:
+      # rows match on the physical queue (queue rows) or the logical one
+      # (orphaned failed rows, which carry the name the consumer recorded).
+      module EventList
+        # Lower bound on archived_at below the oldest claim on a page: the
+        # claim always precedes the archive, the margin absorbs clock skew.
+        ARCHIVE_PROBE_MARGIN = 60
+
+        # An archived envelope's routing key, where Publisher and the outbox
+        # put it. Without one the consumer would archive a replay unrouted.
+        ROUTING_KEY_SQL = "COALESCE(a.message->'headers'->>'routing_key', a.message->>'routing_key')"
+
+        def event_rows(state: nil, queue_name: nil, page: 1, per_page: 25)
+          queues = handler_queue_physical_names
+          return [] if queues.empty?
+
+          rows = job_rows(state: state, queue_name: queue_name, queues: queues, page: page, per_page: per_page)
+          by_queue = subscribers_by_queue_name
+          rows.map do |row|
+            sub = by_queue[row[:queue_name]]
+            row.merge(handler_class: sub&.dig(:handler_class), pattern: sub&.dig(:pattern))
+          end
+        end
+
+        def event_state_counts(queue_name: nil)
+          job_state_counts(queue_name: queue_name, queues: handler_queue_physical_names)
+        end
+
+        def events_ahead(rows) = jobs_ahead(rows)
+
+        def event_list_context(now: Time.now)
+          EventState::Context.new(jobs: job_list_context(now: now), covered_queues: covered_handler_queues,
+                                  claim_window: EventBus::Handler.claim_ownership_window)
+        end
+
+        # { processed_event id => :replayable | :not_archived | :no_handler }
+        # for one page of processed events: one bounded archive probe per
+        # handler queue, never one per row.
+        def event_replay_states(events)
+          subs = replay_subscribers
+          states = events.to_h { |e| [e["id"], subs[e["handler_class"]] ? :not_archived : :no_handler] }
+
+          events.select { |e| subs[e["handler_class"]] }.group_by { |e| subs[e["handler_class"]] }.each do |sub, rows|
+            keys = archived_routing_keys(sub[:physical_queue_name], rows)
+            rows.each { |e| states[e["id"]] = :replayable if replayable_key?(sub, keys[e["event_id"]]) }
+          end
+          states
+        end
+
+        # Re-deliver a processed event's archived envelope to its handler's
+        # queue, under a new event_id (so the idempotency claim is new) that
+        # links back through replayed_from. Only that handler runs again: a
+        # topic publish would re-run every subscriber of the routing key.
+        def replay_event(event)
+          sub = replay_subscribers[event["handler_class"]]
+          return false unless sub
+
+          archived = archived_event(sub[:physical_queue_name], event)
+          return false unless archived
+
+          message = JSON.parse(archived["message"])
+          return false unless replayable_key?(sub, event_routing_key(message))
+
+          replay = message.merge("event_id" => SecureRandom.uuid, "replayed_from" => event["event_id"])
+          @client.transaction do |txn|
+            txn.produce(sub[:physical_queue_name], JSON.generate(replay), headers: archived["headers"])
+          end
+          true
+        rescue StandardError => e
+          Pgbus.logger.error { "[Pgbus::Web] Error replaying event #{event["event_id"]}: #{e.class}: #{e.message}" }
+          false
+        end
+
+        private
+
+        def subscribers_by_queue_name
+          registered_subscribers.each_with_object({}) do |s, out|
+            out[s[:physical_queue_name]] ||= s
+            out[s[:queue_name]] ||= s
+          end
+        end
+
+        # Physical handler queues some healthy consumer reads: its topics
+        # overlap the subscriber's pattern (Registry#queue_names_for_topics'
+        # rule). nil when a healthy consumer does not report its topics.
+        def covered_handler_queues
+          consumers = processes.select { |p| p[:kind].to_s == "consumer" && p[:healthy] }
+          topics = consumers.map { |p| p[:metadata].is_a?(Hash) ? p[:metadata]["topics"] : nil }
+          return nil if topics.any?(&:nil?)
+
+          registry = EventBus::Registry.instance
+          topics = topics.flatten
+          registered_subscribers.select { |s| topics.any? { |t| registry.pattern_overlaps?(t, s[:pattern]) } }
+                                .to_set { |s| s[:physical_queue_name] }
+        end
+
+        # { event_id => routing key } for the page's events still in the archive.
+        def archived_routing_keys(queue, events)
+          ids = events.map { |e| text_array_element(e["event_id"]) }
+          rows = connection.select_all(<<~SQL, "Pgbus Archived Events", ["{#{ids.join(",")}}", archive_floor(events)])
+            SELECT a.message->>'event_id' AS event_id, #{ROUTING_KEY_SQL} AS routing_key
+            FROM pgmq.a_#{sanitize_name(queue)} a
+            WHERE a.archived_at >= $2::timestamptz AND a.message->>'event_id' = ANY($1::text[])
+              AND #{ROUTING_KEY_SQL} IS NOT NULL
+          SQL
+          rows.to_a.to_h { |r| [r["event_id"], r["routing_key"]] }
+        rescue StandardError => e
+          Pgbus.logger.error { "[Pgbus::Web] Error reading the archive of #{queue}: #{e.class}: #{e.message}" }
+          {}
+        end
+
+        # The registration Replay uses per handler class: the first, so the
+        # availability check and the action never disagree.
+        def replay_subscribers
+          registered_subscribers.each_with_object({}) { |s, out| out[s[:handler_class]] ||= s }
+        end
+
+        # A replay the consumer would archive unrouted is no replay: the key
+        # must still match the subscriber's pattern.
+        def replayable_key?(sub, routing_key)
+          !routing_key.nil? && EventBus::Registry.instance.pattern_matches?(sub[:pattern], routing_key)
+        end
+
+        # event_id is any string an envelope carried (Edit & Retry accepts any
+        # payload), so each element of the bound text[] literal is quoted.
+        def text_array_element(value)
+          %("#{value.to_s.gsub(/["\\]/) { |c| "\\#{c}" }}")
+        end
+
+        def archived_event(queue, event)
+          connection.select_one(<<~SQL, "Pgbus Archived Event", [event["event_id"].to_s, archive_floor([event])])
+            SELECT a.message::text AS message, a.headers::text AS headers FROM pgmq.a_#{sanitize_name(queue)} a
+            WHERE a.message->>'event_id' = $1 AND a.archived_at >= $2::timestamptz
+            ORDER BY a.archived_at DESC LIMIT 1
+          SQL
+        end
+
+        def archive_floor(events)
+          oldest = events.filter_map { |e| JobState.time(e["processed_at"]) }.min || Time.at(0)
+          (oldest - ARCHIVE_PROBE_MARGIN).utc.iso8601(6)
+        end
+
+        def event_routing_key(message)
+          headers = message["headers"]
+          (headers["routing_key"] if headers.is_a?(Hash)).presence || message["routing_key"].presence
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/web/data_source/job_list.rb

@@ -0,0 +1,323 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Web
+    class DataSource
+      # The Jobs page's unified list (issue #489): every job the dashboard can
+      # see, one row each, whatever table it lives in, with its state derived
+      # in SQL so tabs, counts and paging all cut on the same value.
+      #
+      # Sources, one UNION ALL fragment each:
+      # - every non-DLQ queue table, LEFT JOINed to its pgbus_failed_events row
+      #   (failed_events.queue_name is the LOGICAL name; the physical one is
+      #   matched too for rows older code wrote)
+      # - failed rows whose message is no longer in its queue ("orphans")
+      # - pgbus_blocked_executions (jobs parked by limits_concurrency)
+      #
+      # Queue names reach SQL only through sanitize_name; the state filter and
+      # paging are bound parameters. Each fragment carries its own ORDER BY +
+      # LIMIT so it stays index-backed and bounded; msg_ids from different
+      # queues are not comparable, so the outer sort is by time.
+      #
+      # queues: cuts the list to those physical queues (the Events page passes
+      # the EventBus handler queues); exclude: leaves physical queues out (the
+      # Jobs page leaves the handler queues to the Events page). Both are
+      # optional, and without them the SQL is unchanged (issue #494).
+      module JobList
+        # A failure recorded after the read that ran the attempt means the job
+        # is backing off; a later read (last_read_at past failed_at) means the
+        # retry attempt is running now.
+        STATE_CASE = <<~SQL.gsub(/\s+/, " ").strip.freeze
+          CASE
+            WHEN m.read_ct = 0 AND m.vt > now() THEN 'scheduled'
+            WHEN m.read_ct = 0 THEN 'ready'
+            WHEN f.failed_at IS NOT NULL AND f.failed_at >= m.last_read_at THEN 'retrying'
+            WHEN m.vt > now() THEN 'running'
+            ELSE 'ready'
+          END
+        SQL
+
+        # Per-fragment ceiling for the tab counts, so a million-row queue never
+        # forces a full scan on every auto-refresh. A fragment that reaches it
+        # makes its states' counts lower bounds.
+        COUNT_CAP = 10_000
+
+        QUEUE_STATES = %w[ready scheduled running retrying].freeze
+
+        # A predicate on m that each state branch of STATE_CASE already implies.
+        # Without it a filtered tab walks the whole pkey and probes the LATERAL for
+        # every row before LIMIT bites (300k-row queue, no matches: ~350 ms); with it
+        # only candidates reach the CASE. The exact `q.state = $1` still applies.
+        STATE_PREFILTER = {
+          "scheduled" => "m.read_ct = 0 AND m.vt > now()",
+          "ready" => "m.vt <= now()",
+          "running" => "m.read_ct > 0 AND m.vt > now()",
+          "retrying" => "m.read_ct > 0"
+        }.freeze
+
+        INTEGER_COLUMNS = %i[id msg_id read_ct failed_event_id slots_held slots_max].freeze
+
+        StateCounts = Data.define(:counts, :capped) do
+          def [](state) = counts.fetch(state.to_s, 0)
+          def capped?(state) = capped.include?(state.to_s)
+        end
+
+        def job_rows(state: nil, queue_name: nil, queues: nil, exclude: nil, page: 1, per_page: 25)
+          scope = job_list_scope(queue_name, queues: queues, exclude: exclude)
+          return [] unless scope
+
+          binds = []
+          state_param = nil
+          if state && state != "blocked" && scope[:queues].any?
+            binds << state
+            state_param = "$1"
+          end
+
+          fetch = (page * per_page).to_i
+          fragments = job_row_fragments(scope, state, state_param, fetch)
+          return [] if fragments.empty?
+
+          sql = <<~SQL
+            SELECT * FROM (#{fragments.join("\nUNION ALL\n")}) AS jobs
+            ORDER BY sort_at DESC NULLS LAST, id DESC
+            LIMIT $#{binds.size + 1} OFFSET $#{binds.size + 2}
+          SQL
+          binds.push(per_page, (page - 1) * per_page)
+
+          connection.select_all(sql, "Pgbus Job List", binds).to_a.map { |row| format_job_row(row) }
+        rescue StandardError => e
+          Pgbus.logger.error { "[Pgbus::Web] Error reading the job list: #{e.class}: #{e.message}" }
+          []
+        end
+
+        def job_state_counts(queue_name: nil, queues: nil, exclude: nil)
+          scope = job_list_scope(queue_name, queues: queues, exclude: exclude)
+          return empty_state_counts unless scope
+
+          kinds = []
+          fragments = []
+          count_fragments(scope).each do |kind, sql|
+            fragments << "(SELECT #{kinds.size} AS frag, state FROM (#{sql}) c LIMIT #{COUNT_CAP + 1})"
+            kinds << kind
+          end
+
+          rows = connection.select_all(<<~SQL, "Pgbus Job State Counts").to_a
+            SELECT frag, state, COUNT(*) AS n FROM (#{fragments.join("\nUNION ALL\n")}) AS counted
+            GROUP BY frag, state
+          SQL
+          tally_state_counts(rows, kinds)
+        rescue StandardError => e
+          Pgbus.logger.error { "[Pgbus::Web] Error counting job states: #{e.class}: #{e.message}" }
+          empty_state_counts
+        end
+
+        # { [physical_queue, msg_id] => jobs_ahead } for the ready queue rows
+        # on one page: one bounded COUNT per distinct queue, never per row.
+        def jobs_ahead(rows)
+          ready = rows.select { |r| r[:source] == "queue" && r[:state] == "ready" }
+          ready.group_by { |r| r[:queue_name] }.each_with_object({}) do |(queue, queue_rows), out|
+            out.merge!(jobs_ahead_in(queue, queue_rows.map { |r| r[:msg_id].to_i }.sort))
+          end
+        end
+
+        def job_list_context(now: Time.now)
+          alive = ->(kind) { processes.any? { |p| p[:kind].to_s == kind && p[:healthy] } }
+          JobState::Context.new(now: now, max_retries: Pgbus.configuration.max_retries,
+                                paused: paused_queue_names.to_set, drained: drained_queue_names,
+                                workers_alive: alive.call("worker"), handler_queues: handler_queue_physical_names.to_set,
+                                consumers_alive: alive.call("consumer"))
+        end
+
+        private
+
+        # The physical non-DLQ queues in view, grouped under their logical
+        # name, or nil when the requested queue (or every listed one) does not
+        # exist. Excluded queues stay known, so their failed rows never show up
+        # as orphans of an unknown queue.
+        def job_list_scope(queue_name, queues: nil, exclude: nil)
+          names = queues_with_metrics.map { |q| q[:name] }.reject { |n| n.end_with?(Pgbus::DEAD_LETTER_SUFFIX) }
+          names &= queues if queues
+          return nil if queues && names.empty?
+
+          excluded = exclude ? names & exclude : []
+          names -= excluded
+          if queue_name
+            return nil unless names.include?(queue_name)
+
+            names = [queue_name]
+          end
+
+          pairs = ->(list) { list.map { |n| [sanitize_name(n), logical_queue_name(n)] } }
+          scoped = pairs.call(names)
+          { queues: scoped, by_logical: scoped.group_by(&:last), excluded: pairs.call(excluded),
+            filtered: !queue_name.nil? || !queues.nil? }
+        end
+
+        def job_row_fragments(scope, state, state_param, fetch)
+          fragments = []
+          unless state == "blocked"
+            fragments.concat(scope[:queues].map { |(qtable, logical)| queue_row_fragment(qtable, logical, state, state_param, fetch) })
+          end
+          fragments.concat(orphan_fragments(scope, fetch)) if state.nil? || state == "retrying"
+          fragments << blocked_fragment(scope, fetch) if state.nil? || state == "blocked"
+          fragments
+        end
+
+        def queue_row_fragment(qtable, logical, state, state_param, fetch)
+          where = state_param ? "WHERE q.state = #{state_param}" : ""
+          prefilter = state_param && STATE_PREFILTER[state] ? "WHERE #{STATE_PREFILTER[state]}" : ""
+          <<~SQL.strip
+            (SELECT * FROM (
+              SELECT 'queue'::text AS source, m.msg_id AS id, '#{qtable}'::text AS queue_name,
+                     '#{logical}'::text AS logical_queue, m.msg_id, m.message->>'job_class' AS job_class,
+                     m.read_ct, m.enqueued_at, m.last_read_at, m.vt, #{STATE_CASE} AS state,
+                     f.error_class, f.error_message, f.id AS failed_event_id,
+                     NULL::text AS concurrency_key, NULL::integer AS slots_held, NULL::integer AS slots_max,
+                     m.message::text AS payload, m.headers::text AS headers, m.enqueued_at AS sort_at
+              FROM pgmq.q_#{qtable} m
+              #{failed_join(qtable, logical)}
+              #{prefilter}
+            ) q #{where} ORDER BY q.msg_id DESC LIMIT #{fetch})
+          SQL
+        end
+
+        def failed_join(qtable, logical)
+          <<~SQL.strip
+            LEFT JOIN LATERAL (
+              SELECT f.id, f.error_class::text AS error_class, f.error_message,
+                     f.failed_at::timestamptz AS failed_at
+              FROM pgbus_failed_events f
+              WHERE f.queue_name IN ('#{logical}', '#{qtable}') AND f.msg_id = m.msg_id
+              ORDER BY f.failed_at DESC LIMIT 1
+            ) f ON true
+          SQL
+        end
+
+        # Failed rows whose message left its queue: one fragment per logical
+        # queue, plus (unfiltered) one for rows whose queue no longer exists.
+        def orphan_fragments(scope, fetch)
+          fragments = scope[:by_logical].map do |logical, tables|
+            missing = tables.map { |(qtable, _)| "NOT EXISTS (SELECT 1 FROM pgmq.q_#{qtable} m WHERE m.msg_id = f.msg_id)" }
+            names = quoted_list([logical, *tables.map(&:first)])
+            orphan_fragment("'#{logical}'::text", "f.queue_name IN (#{names}) AND #{missing.join(" AND ")}", fetch)
+          end
+          return fragments if scope[:filtered]
+
+          known = scope[:by_logical].flat_map { |logical, tables| [logical, *tables.map(&:first)] }
+          known += scope[:excluded].flat_map { |(qtable, logical)| [logical, qtable] }
+          where = known.empty? ? "true" : "NOT (f.queue_name = ANY(ARRAY[#{quoted_list(known)}]))"
+          fragments << orphan_fragment("f.queue_name::text", where, fetch)
+        end
+
+        def orphan_fragment(logical_sql, where, fetch)
+          <<~SQL.strip
+            (SELECT 'failed'::text AS source, f.id, f.queue_name::text AS queue_name, #{logical_sql} AS logical_queue,
+                    f.msg_id, f.payload->>'job_class' AS job_class, (f.retry_count + 1) AS read_ct,
+                    NULL::timestamptz AS enqueued_at, NULL::timestamptz AS last_read_at, NULL::timestamptz AS vt,
+                    'retrying'::text AS state, f.error_class::text AS error_class, f.error_message,
+                    f.id AS failed_event_id, NULL::text AS concurrency_key, NULL::integer AS slots_held,
+                    NULL::integer AS slots_max, f.payload::text AS payload, f.headers::text AS headers,
+                    f.failed_at::timestamptz AS sort_at
+             FROM pgbus_failed_events f WHERE #{where} ORDER BY f.id DESC LIMIT #{fetch})
+          SQL
+        end
+
+        def blocked_fragment(scope, fetch)
+          <<~SQL.strip
+            (SELECT 'blocked'::text AS source, b.id, b.queue_name::text AS queue_name,
+                    b.queue_name::text AS logical_queue, NULL::bigint AS msg_id, b.payload->>'job_class' AS job_class,
+                    NULL::integer AS read_ct, b.created_at::timestamptz AS enqueued_at,
+                    NULL::timestamptz AS last_read_at, NULL::timestamptz AS vt, 'blocked'::text AS state,
+                    NULL::text AS error_class, NULL::text AS error_message, NULL::bigint AS failed_event_id,
+                    b.concurrency_key::text AS concurrency_key, s.value AS slots_held, s.max_value AS slots_max,
+                    b.payload::text AS payload, NULL::text AS headers, b.created_at::timestamptz AS sort_at
+             FROM pgbus_blocked_executions b
+             LEFT JOIN pgbus_semaphores s ON s.key = b.concurrency_key
+             #{blocked_where(scope)} ORDER BY b.created_at DESC LIMIT #{fetch})
+          SQL
+        end
+
+        def blocked_where(scope)
+          if scope[:filtered]
+            return "WHERE false" if scope[:queues].empty?
+
+            "WHERE b.queue_name IN (#{quoted_list(scope[:queues].flat_map { |(qtable, logical)| [logical, qtable] })})"
+          elsif scope[:excluded].any?
+            "WHERE b.queue_name NOT IN (#{quoted_list(scope[:excluded].flat_map { |(qtable, logical)| [logical, qtable] })})"
+          else
+            ""
+          end
+        end
+
+        # [kind, sql selecting a `state` column] per fragment, uncapped.
+        def count_fragments(scope)
+          queue = scope[:queues].map do |(qtable, logical)|
+            [:queue, "SELECT #{STATE_CASE} AS state FROM pgmq.q_#{qtable} m #{failed_join(qtable, logical)}"]
+          end
+          orphans = orphan_fragments(scope, COUNT_CAP + 1).map { |sql| [:orphan, "SELECT state FROM #{sql} o"] }
+          queue + orphans + [[:blocked, "SELECT state FROM #{blocked_fragment(scope, COUNT_CAP + 1)} b2"]]
+        end
+
+        def tally_state_counts(rows, kinds)
+          counts = Hash.new(0)
+          per_fragment = Hash.new(0)
+          rows.each do |row|
+            n = row["n"].to_i
+            counts[row["state"]] += n
+            per_fragment[row["frag"].to_i] += n
+          end
+
+          capped = Set.new
+          per_fragment.each do |frag, total|
+            next if total <= COUNT_CAP
+
+            capped.merge(capped_states_for(kinds[frag]))
+          end
+          counts["all"] = counts.values.sum
+          StateCounts.new(counts: counts.to_h, capped: capped)
+        end
+
+        def capped_states_for(kind)
+          states = { queue: QUEUE_STATES, orphan: %w[retrying], blocked: %w[blocked] }.fetch(kind)
+          [*states, "all"]
+        end
+
+        def empty_state_counts
+          StateCounts.new(counts: {}, capped: Set.new)
+        end
+
+        def jobs_ahead_in(queue, msg_ids)
+          @jobs_ahead_memo ||= {}
+          @jobs_ahead_memo[[queue, msg_ids]] ||= begin
+            rows = connection.select_all(<<~SQL, "Pgbus Jobs Ahead", ["{#{msg_ids.join(",")}}"])
+              SELECT x.msg_id, (
+                SELECT COUNT(*) FROM (
+                  SELECT 1 FROM pgmq.q_#{sanitize_name(queue)} m
+                  WHERE m.vt <= now() AND m.msg_id < x.msg_id LIMIT #{JobState::AHEAD_CAP}
+                ) s
+              ) AS ahead
+              FROM unnest($1::bigint[]) AS x(msg_id)
+            SQL
+            rows.to_a.to_h { |r| [[queue, r["msg_id"].to_i], r["ahead"].to_i] }
+          end
+        rescue StandardError => e
+          Pgbus.logger.error { "[Pgbus::Web] Error counting jobs ahead in #{queue}: #{e.class}: #{e.message}" }
+          {}
+        end
+
+        # Values are sanitized queue names (word characters only), so quoting
+        # them as literals is safe.
+        def quoted_list(names)
+          names.uniq.map { |n| "'#{sanitize_name(n)}'" }.join(", ")
+        end
+
+        def format_job_row(row)
+          row.to_h.each_with_object({}) do |(key, value), out|
+            sym = key.to_sym
+            out[sym] = INTEGER_COLUMNS.include?(sym) && !value.nil? ? value.to_i : value
+          end
+        end
+      end
+    end
+  end
+end