pgbus 0.17.1 → 0.17.3

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

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Web
+    class DataSource
+      # Row totals for the dashboard's paged lists (issue #496). list_count
+      # stops at COUNT_CAP + 1 rows, so a table with millions of rows costs no
+      # more than one with ten thousand; past the cap the pager shows "10,000+".
+      # The same bound JobList uses for its state tabs. batches_count and
+      # recurring_tasks_count are exact (summary_stats' badge reads the latter);
+      # they predate the pagers and live here to keep data_source.rb small.
+      module ListCounts
+        COUNT_CAP = 10_000
+
+        Count = Data.define(:total, :capped) do
+          def capped? = capped
+        end
+
+        EMPTY_COUNT = Count.new(total: 0, capped: false)
+
+        # Semaphores and parked jobs, FULL OUTER JOINed: a key can have parked
+        # rows and no semaphore (its holder died and the sweep removed the row)
+        # or a semaphore and nothing parked. Shared with concurrency_keys.
+        CONCURRENCY_KEYS_FROM = <<~SQL
+          FROM pgbus_semaphores s
+          FULL OUTER JOIN (
+            SELECT concurrency_key, COUNT(*) AS parked_count, MIN(created_at) AS oldest_parked_at
+            FROM pgbus_blocked_executions
+            GROUP BY concurrency_key
+          ) b ON s.key = b.concurrency_key
+        SQL
+
+        LIST_MODELS = {
+          batches: -> { BatchEntry },
+          job_locks: -> { UniquenessKey },
+          outbox: -> { OutboxEntry },
+          processed_events: -> { ProcessedEvent },
+          recurring_tasks: -> { RecurringTask }
+        }.freeze
+
+        # list – :batches, :job_locks, :concurrency_keys, :outbox, :processed_events or :recurring_tasks.
+        def list_count(list)
+          raise ArgumentError, "unknown list: #{list.inspect}" unless list == :concurrency_keys || LIST_MODELS.key?(list)
+
+          bounded_count(list)
+        end
+
+        def batches_count
+          BatchEntry.count
+        rescue StandardError => e
+          Pgbus.logger.debug { "[Pgbus::Web] Error counting batches: #{e.message}" }
+          0
+        end
+
+        def recurring_tasks_count
+          RecurringTask.count
+        rescue StandardError => e
+          Pgbus.logger.debug { "[Pgbus::Web] Error counting recurring tasks: #{e.message}" }
+          0
+        end
+
+        private
+
+        def bounded_count(list)
+          rows = list == :concurrency_keys ? concurrency_keys_probe : LIST_MODELS.fetch(list).call.limit(COUNT_CAP + 1).count
+          Count.new(total: [rows.to_i, COUNT_CAP].min, capped: rows.to_i > COUNT_CAP)
+        rescue StandardError => e
+          Pgbus.logger.debug { "[Pgbus::Web] Error counting #{list}: #{e.message}" }
+          EMPTY_COUNT
+        end
+
+        def concurrency_keys_probe
+          connection.select_value(<<~SQL, "Pgbus Concurrency Keys Count")
+            SELECT COUNT(*) FROM (SELECT 1 #{CONCURRENCY_KEYS_FROM} LIMIT #{COUNT_CAP + 1}) c
+          SQL
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Web
+    class DataSource
+      # The Processes page's rows and the context ProcessState needs to put
+      # them in words (issue #493). Every status in one result set is derived
+      # against one ProcessState::Thresholds, so one now.
+      module ProcessList
+        # thresholds: pass the ones the caller puts the rows in words with, so
+        # badge and sentence share one now.
+        def processes(thresholds: process_thresholds)
+          process_rows.map { |r| format_process(r, thresholds) }
+        rescue StandardError => e
+          Pgbus.logger.debug { "[Pgbus::Web] Error fetching processes: #{e.message}" }
+          []
+        end
+
+        # The dashboard host's config: the stall limits the page states are
+        # this host's stall_threshold, as the badge always was.
+        def process_thresholds(now: Time.now)
+          config = Pgbus.configuration
+          ProcessState::Thresholds.new(
+            now: now, alive_threshold: Process::Heartbeat::ALIVE_THRESHOLD, stall_threshold: config.stall_threshold,
+            dispatch_interval: config.dispatch_interval, recurring_schedule_interval: config.recurring_schedule_interval,
+            polling_interval: config.polling_interval, notify_fallback_poll: Process::Consumer::NOTIFY_FALLBACK_POLL_SECONDS,
+            notify_wakeup: config.worker_notify_wakeup?, reap_interval: Process::Dispatcher::REAP_INTERVAL
+          )
+        end
+
+        def process_context(rows:, thresholds: process_thresholds)
+          ProcessState.context_for(rows, thresholds)
+        end
+
+        private
+
+        # The raw rows, memoized per instance like queues_with_metrics (cleared
+        # by reset_cache!): the home page reads them for the stats, the signals,
+        # the health verdict, the queue lines and the panel (issue #492). Only
+        # the rows: each caller derives statuses against its own thresholds.
+        def process_rows
+          @process_rows ||= connection.select_all("SELECT * FROM pgbus_processes ORDER BY kind, created_at").to_a
+        end
+
+        def format_process(row, thresholds)
+          heartbeat = JobState.time(row["last_heartbeat_at"])
+          metadata = row["metadata"].is_a?(String) ? JSON.parse(row["metadata"]) : row["metadata"]
+          status = ProcessState.derive(kind: row["kind"], metadata: metadata, heartbeat_at: heartbeat,
+                                       thresholds: thresholds)
+          started_at = metadata.is_a?(Hash) && metadata["started_at"]
+
+          {
+            id: row["id"].to_i,
+            kind: row["kind"],
+            hostname: row["hostname"],
+            pid: row["pid"].to_i,
+            metadata: metadata,
+            last_heartbeat_at: heartbeat,
+            healthy: status == :healthy,
+            status: status,
+            created_at: row["created_at"],
+            supervisor_pid: metadata.is_a?(Hash) ? metadata["supervisor_pid"] : nil,
+            started_at: started_at ? Time.at(started_at.to_f) : nil
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Web
+    class DataSource
+      # The facts behind a queue page's summary in words (issue #491), turned
+      # into sentences by Pgbus::Web::QueueSummary. Both methods take the
+      # physical queue name the page is for.
+      module QueueSummary
+        RUNNING = { paused: false, reason: nil, paused_at: nil, resumes_at: nil, trip_count: 0 }.freeze
+
+        # Pause state is kept per logical queue, so every priority level and
+        # the bare table share it.
+        def queue_pause_state(name)
+          pause_state_of(QueueState.find_by(queue_name: logical_queue_name(name)))
+        rescue StandardError => e
+          Pgbus.logger.error { "[Pgbus::Web] Error reading pause state for #{name}: #{e.class}: #{e.message}" }
+          RUNNING
+        end
+
+        # { physical name => pause state } for many queues in one query (the
+        # home page's queues table, issue #492). Raises: the caller degrades.
+        def queue_pause_states(names)
+          states = QueueState.where(queue_name: names.map { |n| logical_queue_name(n) }.uniq).index_by(&:queue_name)
+          names.to_h { |name| [name, pause_state_of(states[logical_queue_name(name)])] }
+        end
+
+        # healthy: and streams: let a caller describing many queues load the
+        # process rows and the stream registry once (issue #492).
+        def queue_drainers(name, healthy: processes.select { |p| p[:healthy] }, streams: stream_queue_names)
+          table = name.to_s.delete_suffix(Pgbus::DEAD_LETTER_SUFFIX)
+          level = priority_level_of(table)
+          logical = level ? logical_queue_name(table) : table.delete_prefix("#{Pgbus.configuration.queue_prefix}_")
+          capsules, wildcard = draining_capsules(name)
+          {
+            logical: logical, capsules: capsules, wildcard: wildcard,
+            handler: handler_queue_physical_names.include?(name), stream: streams.include?(name),
+            live_workers: healthy.count { |p| p[:kind].to_s == "worker" && worker_drains?(p, logical) },
+            live_consumers: healthy.count { |p| p[:kind].to_s == "consumer" && consumer_drains?(p, name) },
+            siblings: level ? priority_siblings(name, logical) : [], priority_level: level
+          }
+        end
+
+        private
+
+        def pause_state_of(state)
+          return RUNNING unless state&.paused
+
+          { paused: true, reason: state.paused_reason, paused_at: state.paused_at,
+            resumes_at: state.circuit_breaker_resume_at, trip_count: state.circuit_breaker_trip_count.to_i }
+        end
+
+        # The level of a priority sub-table, or nil. `_pN` is legal in an
+        # ordinary queue name, so only a table the queue strategy creates for
+        # the stripped logical name counts.
+        def priority_level_of(table)
+          level = table[Pgbus::Web::QueueSummary::PRIORITY_LEVEL, 1]
+          return unless level && @client.physical_queue_names(logical_queue_name(table)).include?(table)
+
+          level.to_i
+        rescue StandardError => e
+          Pgbus.logger.debug { "[Pgbus::Web] Error resolving priority level of #{table}: #{e.class}: #{e.message}" }
+          nil
+        end
+
+        # [names of the capsules whose queues expand to this table, wildcard?].
+        # An anonymous capsule goes by its first queue. Fails open to a
+        # wildcard, like drained_queue_names: never a false "nothing drains it".
+        def draining_capsules(name)
+          capsules = Array(Pgbus.configuration.workers)
+          wildcard = capsules.any? { |c| capsule_queue_list(c).include?("*") }
+          names = capsules.filter_map do |c|
+            queues = capsule_queue_list(c) - ["*"]
+            next unless queues.any? { |q| @client.physical_queue_names(q).include?(name) }
+
+            (c[:name] || c["name"] || queues.first).to_s
+          end
+          [names, wildcard]
+        rescue StandardError => e
+          Pgbus.logger.error { "[Pgbus::Web] Error resolving capsules for #{name}: #{e.class}: #{e.message}" }
+          [[], true]
+        end
+
+        def capsule_queue_list(capsule)
+          Array(capsule[:queues] || capsule["queues"]).map(&:to_s)
+        end
+
+        # A heartbeat lists queue names as configured (Array or comma-separated
+        # String); tables are named after their normalized form ("bulk-imports"
+        # → pgbus_bulk_imports), so compare that.
+        def worker_drains?(process, logical)
+          queues = Array((process[:metadata] || {})["queues"]).flat_map { |q| q.to_s.split(",") }.map(&:strip)
+          queues.include?("*") || queues.any? { |q| normalized_queue(q) == logical }
+        end
+
+        # A consumer drains a handler queue when one of its topic filters
+        # overlaps a subscription routed to it (the rule the consumer itself
+        # uses to pick queues). A heartbeat without topics counts.
+        def consumer_drains?(process, name)
+          topics = Array((process[:metadata] || {})["topics"])
+          return true if topics.empty?
+
+          patterns = registered_subscribers.select { |s| s[:physical_queue_name] == name }.map { |s| s[:pattern] }
+          registry = EventBus::Registry.instance
+          topics.any? { |t| patterns.any? { |pattern| registry.pattern_overlaps?(t.to_s, pattern) } }
+        end
+
+        def normalized_queue(queue)
+          Pgbus.configuration.queue_name(queue).delete_prefix("#{Pgbus.configuration.queue_prefix}_")
+        rescue ArgumentError
+          queue
+        end
+
+        def priority_siblings(name, logical)
+          queues_with_metrics.map { |q| q[:name] }.select do |n|
+            n != name && n.match?(Pgbus::Web::QueueSummary::PRIORITY_LEVEL) && logical_queue_name(n) == logical
+          end
+        end
+      end
+    end
+  end
+end