pgbus 0.9.7 → 0.9.9

data/Rakefile

@@ -8,7 +8,16 @@ end
 
 require "rubocop/rake_task"
 
-RuboCop::RakeTask.new
+# Lint only the gem's own source — NOT the nested docs/ site. docs/ is a separate
+# consuming app with its own bundle and .rubocop.yml (it inherit_gems
+# rubocop-rails-omakase and requires docs_kit/rubocop, both absent from the gem's
+# bundle). RuboCop loads a directory's .rubocop.yml while scanning it — before
+# AllCops/Exclude applies — so a bare run discovers docs/.rubocop.yml and crashes
+# on the unresolvable gem inheritance. Passing explicit paths stops the
+# discovery. docs/ lints itself in the Docs site workflow. (Same fix as docs-kit.)
+RuboCop::RakeTask.new do |task|
+  task.patterns = %w[app benchmarks config lib spec Gemfile Rakefile pgbus.gemspec]
+end
 
 namespace :bench do
   bench_dir = "benchmarks"

data/app/helpers/pgbus/application_helper.rb

@@ -29,6 +29,43 @@ module Pgbus
       end
     end
 
+    # Order the rate keys are rendered in, and their i18n label suffixes.
+    WORKER_RATE_KEYS = %w[processed failed dequeued].freeze
+
+    # Metadata keys rendered specially elsewhere (throughput badge, health
+    # status) and therefore excluded from the generic key/value dump.
+    WORKER_INTERNAL_METADATA_KEYS = %w[rates jobs_processed jobs_failed in_flight loop_tick_at].freeze
+
+    # The subset of a process's metadata to render as generic key/value badges:
+    # everything except the throughput/health keys that have dedicated rendering.
+    def pgbus_display_metadata(metadata)
+      return {} unless metadata.is_a?(Hash)
+
+      metadata.reject { |k, _| WORKER_INTERNAL_METADATA_KEYS.include?(k.to_s) }
+    end
+
+    # Render a worker's per-second throughput rates (from heartbeat metadata)
+    # as a compact human-readable string, e.g. "12.4/s processed · 0.2/s failed".
+    # Zero rates are omitted; returns nil when there are no non-zero rates so
+    # callers can fall back to the raw metadata rendering.
+    def pgbus_worker_rates(metadata)
+      return nil unless metadata.is_a?(Hash)
+
+      rates = metadata["rates"]
+      return nil unless rates.is_a?(Hash)
+
+      parts = WORKER_RATE_KEYS.filter_map do |key|
+        value = rates[key].to_f
+        next if value.zero?
+
+        label = I18n.t("pgbus.processes.processes_table.rates.#{key}", default: key)
+        "#{value}/s #{label}"
+      end
+      return nil if parts.empty?
+
+      parts.join(" · ")
+    end
+
     def pgbus_status_badge(healthy_or_status)
       status = case healthy_or_status
                when true then :healthy

data/app/views/pgbus/processes/_processes_table.html.erb

@@ -21,7 +21,10 @@
             <td data-label="Last Heartbeat" class="px-4 py-3 text-sm text-gray-500"><%= pgbus_time_ago(p[:last_heartbeat_at]) %></td>
             <td data-label="Metadata" class="px-4 py-3 text-sm text-gray-500 font-mono text-xs max-w-xs truncate">
               <% if p[:metadata].is_a?(Hash) %>
-                <% p[:metadata].each do |k, v| %>
+                <% if (rates = pgbus_worker_rates(p[:metadata])) %>
+                  <span class="inline-flex items-center rounded bg-green-100 dark:bg-green-900/30 text-green-800 dark:text-green-300 px-1.5 py-0.5 text-xs mr-1 font-medium"><%= rates %></span>
+                <% end %>
+                <% pgbus_display_metadata(p[:metadata]).each do |k, v| %>
                   <span class="inline-flex items-center rounded bg-gray-100 px-1.5 py-0.5 text-xs mr-1"><%= k %>: <%= v %></span>
                 <% end %>
               <% end %>

data/config/locales/da.yml

@@ -458,6 +458,10 @@ da:
           metadata: Metadata
           pid: PID
           status: Status
+        rates:
+          dequeued: hentet
+          failed: mislykkedes
+          processed: behandlet
     queues:
       destroy:
         success: Køen %{name} slettet.

data/config/locales/de.yml

@@ -458,6 +458,10 @@ de:
           metadata: Metadaten
           pid: PID
           status: Status
+        rates:
+          dequeued: entnommen
+          failed: fehlgeschlagen
+          processed: verarbeitet
     queues:
       destroy:
         success: Warteschlange %{name} gelöscht.

data/config/locales/en.yml

@@ -458,6 +458,10 @@ en:
           metadata: Metadata
           pid: PID
           status: Status
+        rates:
+          dequeued: dequeued
+          failed: failed
+          processed: processed
     queues:
       destroy:
         success: Queue %{name} deleted.

data/config/locales/es.yml

@@ -458,6 +458,10 @@ es:
           metadata: Metadatos
           pid: PID
           status: Estado
+        rates:
+          dequeued: extraídos
+          failed: fallidos
+          processed: procesados
     queues:
       destroy:
         success: Cola %{name} eliminada.

data/config/locales/fi.yml

@@ -458,6 +458,10 @@ fi:
           metadata: Metatiedot
           pid: PID
           status: Tila
+        rates:
+          dequeued: haettu
+          failed: epäonnistui
+          processed: käsitelty
     queues:
       destroy:
         success: Jono %{name} poistettu.

data/config/locales/fr.yml

@@ -458,6 +458,10 @@ fr:
           metadata: Métadonnées
           pid: PID
           status: Statut
+        rates:
+          dequeued: retirés
+          failed: échoués
+          processed: traités
     queues:
       destroy:
         success: File d'attente %{name} supprimée.

data/config/locales/it.yml

@@ -458,6 +458,10 @@ it:
           metadata: Metadati
           pid: PID
           status: Stato
+        rates:
+          dequeued: prelevati
+          failed: falliti
+          processed: elaborati
     queues:
       destroy:
         success: Coda %{name} eliminata.

data/config/locales/ja.yml

@@ -458,6 +458,10 @@ ja:
           metadata: メタデータ
           pid: PID
           status: ステータス
+        rates:
+          dequeued: 取得
+          failed: 失敗
+          processed: 処理
     queues:
       destroy:
         success: キュー %{name} を削除しました。

data/config/locales/nb.yml

@@ -458,6 +458,10 @@ nb:
           metadata: Metadata
           pid: PID
           status: Status
+        rates:
+          dequeued: hentet
+          failed: mislyktes
+          processed: behandlet
     queues:
       destroy:
         success: Køen %{name} slettet.

data/config/locales/nl.yml

@@ -458,6 +458,10 @@ nl:
           metadata: Metadata
           pid: PID
           status: Status
+        rates:
+          dequeued: opgehaald
+          failed: mislukt
+          processed: verwerkt
     queues:
       destroy:
         success: Wachtrij %{name} verwijderd.

data/config/locales/pt.yml

@@ -458,6 +458,10 @@ pt:
           metadata: Metadados
           pid: PID
           status: Status
+        rates:
+          dequeued: retirados
+          failed: falharam
+          processed: processados
     queues:
       destroy:
         success: Fila %{name} excluída.

data/config/locales/sv.yml

@@ -458,6 +458,10 @@ sv:
           metadata: Metadata
           pid: PID
           status: Status
+        rates:
+          dequeued: hämtade
+          failed: misslyckade
+          processed: bearbetade
     queues:
       destroy:
         success: Kön %{name} borttagen.

data/lib/generators/pgbus/{add_job_locks_generator.rb → add_uniqueness_keys_generator.rb}

@@ -6,13 +6,13 @@ require_relative "migration_path"
 
 module Pgbus
   module Generators
-    class AddJobLocksGenerator < Rails::Generators::Base
+    class AddUniquenessKeysGenerator < Rails::Generators::Base
       include ActiveRecord::Generators::Migration
       include MigrationPath
 
       source_root File.expand_path("templates", __dir__)
 
-      desc "Add job locks table for uniqueness guarantees"
+      desc "Add uniqueness keys table for ensures_uniqueness support"
 
       class_option :database,
                    type: :string,
@@ -20,13 +20,13 @@ module Pgbus
                    desc: "Use a separate database for pgbus tables (e.g. --database=pgbus)"
 
       def create_migration_file
-        migration_template "add_job_locks.rb.erb",
-                           File.join(pgbus_migrate_path, "add_pgbus_job_locks.rb")
+        migration_template "add_uniqueness_keys.rb.erb",
+                           File.join(pgbus_migrate_path, "add_pgbus_uniqueness_keys.rb")
       end
 
       def display_post_install
         say ""
-        say "Pgbus job locks table installed!", :green
+        say "Pgbus uniqueness keys table installed!", :green
         say ""
         say "Next steps:"
         say "  1. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"

data/lib/pgbus/active_job/adapter.rb

@@ -151,7 +151,7 @@ module Pgbus
         msg_ids = Pgbus.client.send_batch(queue, payloads)
 
         unless msg_ids.is_a?(Array) && msg_ids.size == jobs.size
-          raise "Pgbus batch enqueue failed: expected #{jobs.size} ids, got #{msg_ids&.size || 0}"
+          raise Pgbus::EnqueueError, "Pgbus batch enqueue failed: expected #{jobs.size} ids, got #{msg_ids&.size || 0}"
         end
 
         jobs.zip(msg_ids).each { |job, id| job.provider_job_id = id }

data/lib/pgbus/active_job/executor.rb

@@ -296,14 +296,35 @@ module Pgbus
         Pgbus.logger.warn { "[Pgbus] Batch discard signal failed: #{e.message}" }
       end
 
+      # Archiving is idempotent — archiving an already-archived message is a
+      # no-op — so a connection error here is safe to retry once, unlike sends
+      # where a retry could duplicate the message. Without the retry, a job
+      # that succeeded but failed to archive redelivers after VT expiry and
+      # runs twice. If the retry also fails, fall through to the normal
+      # failure path (recorded failure + VT-based redelivery).
       def archive_from(queue_name, msg_id, source_queue: nil)
-        if source_queue
-          client.archive_message(source_queue, msg_id, prefixed: false)
-        else
-          client.archive_message(queue_name, msg_id)
+        attempts = 0
+        begin
+          if source_queue
+            client.archive_message(source_queue, msg_id, prefixed: false)
+          else
+            client.archive_message(queue_name, msg_id)
+          end
+        rescue StandardError => e
+          attempts += 1
+          raise unless attempts == 1 && connection_error?(e)
+
+          Pgbus.logger.warn do
+            "[Pgbus::Executor] Archive failed on connection error, retrying once: #{e.message}"
+          end
+          retry
         end
       end
 
+      def connection_error?(error)
+        defined?(PGMQ::Errors::ConnectionError) && error.is_a?(PGMQ::Errors::ConnectionError)
+      end
+
       def handle_dead_letter(message, queue_name, payload, source_queue: nil)
         Pgbus.logger.warn do
           job_class = payload["job_class"] || "unknown"

data/lib/pgbus/cli/dlq.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Pgbus
+  module CLI
+    # Dead-letter queue management for headless deployments and incident
+    # runbooks. Every operation routes through +Web::DataSource+ so the CLI
+    # shares the dashboard's exact semantics — origin-queue re-enqueue,
+    # transactional retry, lock release on discard, sensitive-payload
+    # filtering — with zero raw SQL or direct PGMQ calls.
+    module DLQ
+      module_function
+
+      ROW_FORMAT = "%-10s %-32s %-28s %-8s %s"
+
+      def start(args, data_source: Pgbus::Web::DataSource.new)
+        subcommand = args.first
+        rest = args[1..] || []
+
+        case subcommand
+        when "list"       then list(rest, data_source)
+        when "show"       then show(rest, data_source)
+        when "retry"      then retry_one(rest, data_source)
+        when "retry-all"  then retry_all(data_source)
+        when "purge"      then purge(rest, data_source)
+        else
+          warn "Unknown dlq subcommand: #{subcommand.inspect}" if subcommand
+          print_help
+          exit 1
+        end
+      end
+
+      def list(args, data_source)
+        options = parse_list_options(args)
+        messages = data_source.dlq_messages(page: options[:page], per_page: options[:per_page])
+
+        if messages.empty?
+          puts "No dead-letter messages."
+          return
+        end
+
+        print_list_table(messages)
+        puts "-" * 96
+        puts "Total dead-letter messages: #{data_source.dlq_total_count} " \
+             "(page #{options[:page]}, #{options[:per_page]} per page)"
+      end
+
+      def show(args, data_source)
+        msg_id = require_msg_id(args)
+        detail = data_source.dlq_message_detail(msg_id)
+        abort_missing(msg_id) unless detail
+
+        puts "msg_id:      #{detail[:msg_id]}"
+        puts "dlq queue:   #{detail[:queue_name]}"
+        puts "origin:      #{origin_queue(detail[:queue_name])}"
+        puts "read_ct:     #{detail[:read_ct]}"
+        puts "enqueued_at: #{detail[:enqueued_at]}"
+        puts "payload:"
+        puts Pgbus::Web::PayloadFilter.filter_json(detail[:message])
+      end
+
+      def retry_one(args, data_source)
+        msg_id = require_msg_id(args)
+        detail = data_source.dlq_message_detail(msg_id)
+        abort_missing(msg_id) unless detail
+
+        if data_source.retry_dlq_message(detail[:queue_name], detail[:msg_id])
+          puts "Re-enqueued msg_id #{detail[:msg_id]} to #{origin_queue(detail[:queue_name])}."
+        else
+          warn "Failed to retry msg_id #{detail[:msg_id]}."
+          exit 1
+        end
+      end
+
+      def retry_all(data_source)
+        count = data_source.retry_all_dlq
+        puts "Re-enqueued #{count} dead-letter message#{"s" unless count == 1}."
+      end
+
+      def purge(args, data_source)
+        if args.include?("--all")
+          purge_all(args, data_source)
+        else
+          purge_one(args, data_source)
+        end
+      end
+
+      def purge_one(args, data_source)
+        msg_id = require_msg_id(args)
+        detail = data_source.dlq_message_detail(msg_id)
+        abort_missing(msg_id) unless detail
+
+        if data_source.discard_dlq_message(detail[:queue_name], detail[:msg_id])
+          puts "Purged msg_id #{detail[:msg_id]} from #{detail[:queue_name]}."
+        else
+          warn "Failed to purge msg_id #{detail[:msg_id]}."
+          exit 1
+        end
+      end
+
+      def purge_all(args, data_source)
+        unless args.include?("--yes")
+          warn "Refusing to purge all dead-letter messages without --yes."
+          exit 1
+        end
+
+        count = data_source.discard_all_dlq
+        puts "Purged #{count} dead-letter message#{"s" unless count == 1}."
+      end
+
+      def parse_list_options(args)
+        options = { page: 1, per_page: 25 }
+        OptionParser.new do |opts|
+          opts.banner = "Usage: pgbus dlq list [options]"
+          opts.on("--page N", Integer, "Page number (default: 1)") { |v| options[:page] = v }
+          opts.on("--per-page N", Integer, "Messages per page (default: 25)") { |v| options[:per_page] = v }
+        end.parse!(args.dup)
+        options
+      end
+
+      def print_list_table(messages)
+        puts format(ROW_FORMAT, "MSG_ID", "DLQ QUEUE", "ORIGIN QUEUE", "READ_CT", "ENQUEUED_AT")
+        puts "-" * 96
+        messages.each do |m|
+          puts format(ROW_FORMAT, m[:msg_id], m[:queue_name], origin_queue(m[:queue_name]),
+                      m[:read_ct], m[:enqueued_at])
+        end
+      end
+
+      def origin_queue(dlq_queue_name)
+        dlq_queue_name.delete_suffix(Pgbus::DEAD_LETTER_SUFFIX)
+      end
+
+      def require_msg_id(args)
+        msg_id = args.find { |a| a !~ /\A--/ }
+        unless msg_id
+          warn "A msg_id is required."
+          exit 1
+        end
+        msg_id
+      end
+
+      def abort_missing(msg_id)
+        warn "No dead-letter message found with msg_id #{msg_id}."
+        exit 1
+      end
+
+      def print_help
+        puts <<~HELP
+          Usage: pgbus dlq <subcommand> [options]
+
+          Subcommands:
+            list [--page N] [--per-page N]  List dead-letter messages
+            show MSG_ID                     Show one message (payload filtered)
+            retry MSG_ID                    Re-enqueue a message to its origin queue
+            retry-all                       Re-enqueue every dead-letter message
+            purge MSG_ID                    Discard a single message
+            purge --all --yes               Discard every dead-letter message
+        HELP
+      end
+    end
+  end
+end

data/lib/pgbus/cli.rb

@@ -16,8 +16,12 @@ module Pgbus
         show_status
       when "queues"
         list_queues
+      when "dlq"
+        DLQ.start(args[1..] || [])
       when "mcp"
         start_mcp_server
+      when "doctor"
+        run_doctor
       when "version"
         puts "pgbus #{Pgbus::VERSION}"
       when "help", "--help", "-h"
@@ -107,7 +111,7 @@ module Pgbus
     def apply_capsule_filter(name)
       capsule = Pgbus.configuration.capsule_named(name)
       unless capsule
-        available = (Pgbus.configuration.workers || []).filter_map { |c| c[:name] || c["name"] }
+        available = (Pgbus.configuration.workers || []).filter_map { |c| c[:name] }
         raise ArgumentError,
               "no capsule named #{name.inspect} (available: #{available.join(", ")})"
       end
@@ -141,6 +145,15 @@ module Pgbus
       Pgbus::MCP::Runner.run
     end
 
+    # Runs the deployment preflight diagnostics and prints the report. Exits 1
+    # on any failed check so it can gate a deploy or CI run; exits 0 when all
+    # checks pass (warnings do not fail). Doctor itself never raises.
+    def run_doctor
+      doctor = Pgbus::Doctor.new
+      puts doctor.report
+      exit 1 unless doctor.success?
+    end
+
     def list_queues
       Pgbus.client.list_queues
       metrics = Pgbus.client.metrics
@@ -163,7 +176,11 @@ module Pgbus
           start    Start the Pgbus supervisor (workers + dispatcher)
           status   Show running Pgbus processes
           queues   List queues with metrics
+          dlq      Inspect and drain dead-letter queues
+                   (list/show/retry/retry-all/purge)
           mcp      Start the read-only MCP diagnostic server over stdio
+          doctor   Run environment diagnostics (config, DB, PGMQ, queues,
+                   LISTEN/NOTIFY, process liveness); exits 1 on any failure
           version  Show version
           help     Show this help