pgbus 0.17.1 → 0.17.3

data/config/routes.rb

@@ -99,7 +99,7 @@ Pgbus::Engine.routes.draw do
   end
 
   scope :frontend, controller: :frontends, defaults: { version: Pgbus::VERSION.tr(".", "-") } do
-    get "modules/:version/:id", action: :module, as: :frontend_module, constraints: { format: "js" }
+    get "modules/:version/:id", action: :module, as: :frontend_module, constraints: { format: /js|map/ }
     get "static/:version/:id", action: :static, as: :frontend_static
   end
 end

data/lib/generators/pgbus/add_presence_generator.rb

@@ -33,7 +33,8 @@ module Pgbus
         say "  2. Use in your code:"
         say "       Pgbus.stream(@room).presence.join(member_id: current_user.id.to_s)"
         say "       Pgbus.stream(@room).presence.members"
-        say "  3. Run a periodic sweeper to expire idle members:"
+        say "  3. Connection-driven presence (streams_presence_patterns) expires silent"
+        say "     seats on its own. Rows you join by member_id need a periodic sweeper:"
         say "       Pgbus.stream(@room).presence.sweep!(older_than: 60.seconds.ago)"
         say ""
       end

data/lib/generators/pgbus/add_presence_seats_generator.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+require_relative "migration_path"
+
+module Pgbus
+  module Generators
+    class AddPresenceSeatsGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+      include MigrationPath
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Add per-connection seats (connection_id, seat, state) to pgbus_presence_members"
+
+      class_option :database,
+                   type: :string,
+                   default: nil,
+                   desc: "Use a separate database for pgbus tables (e.g. --database=pgbus)"
+
+      def create_migration_file
+        migration_template "add_presence_seats.rb.erb",
+                           File.join(pgbus_migrate_path, "add_pgbus_presence_seats.rb")
+      end
+
+      def display_post_install
+        say ""
+        say "Pgbus presence seats installed!", :green
+        say ""
+        say "Next steps:"
+        say "  1. Run: rails db:migrate#{migrate_command_suffix}"
+        say "  2. Restart the app: connection-driven presence (streams_presence_patterns)"
+        say "     then keeps one row per SSE connection, expired after streams_presence_ttl"
+        say ""
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::Migration.current_version}]"
+      end
+    end
+  end
+end

data/lib/generators/pgbus/templates/add_presence.rb.erb

@@ -4,23 +4,48 @@ class AddPgbusPresence < ActiveRecord::Migration<%= migration_version %>
       t.string :stream_name, null: false
       t.string :member_id, null: false
       t.jsonb :metadata, null: false, default: {}
+      # One row per SSE connection for connection-driven presence (seats).
+      # NULL for rows written by member-keyed join/leave calls.
+      t.string :connection_id
+      # The client's per-tab id (sent by <pgbus-stream-source presence> as ?seat=).
+      t.string :seat
+      # Ephemeral per-seat state, written by Presence#set_state.
+      t.jsonb :state, null: false, default: {}
       t.datetime :joined_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
       t.datetime :last_seen_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
     end
 
-    # Composite primary key (stream_name, member_id) — a member can only
-    # appear once per stream. Used by the upsert path in
-    # Pgbus::Streams::Presence#join.
+    # A member-keyed row (no connection) appears once per stream. Upsert
+    # target of Pgbus::Streams::Presence#join(member_id:).
     add_index :pgbus_presence_members,
               %i[stream_name member_id],
               unique: true,
-              name: "idx_pgbus_presence_members_pk"
+              where: "connection_id IS NULL",
+              name: "idx_pgbus_presence_members_member_key"
 
-    # Sweeping by last_seen_at expires stale members. The Dispatcher's
-    # periodic sweeper queries WHERE stream_name = ? AND last_seen_at < ?,
-    # so this composite index makes that fast.
+    # A seat row appears once per connection. Upsert target of
+    # Pgbus::Streams::Presence#join(connection_id:).
+    add_index :pgbus_presence_members,
+              %i[stream_name connection_id],
+              unique: true,
+              where: "connection_id IS NOT NULL",
+              name: "idx_pgbus_presence_members_connection_key"
+
+    # All rows of one member (several tabs) on a stream.
+    add_index :pgbus_presence_members,
+              %i[stream_name member_id],
+              name: "idx_pgbus_presence_members_member"
+
+    # Sweeping by last_seen_at expires stale members:
+    # WHERE stream_name = ? AND last_seen_at < ?
     add_index :pgbus_presence_members,
               %i[stream_name last_seen_at],
               name: "idx_pgbus_presence_members_sweep"
+
+    # The streamer heartbeat expires silent seats across every stream.
+    add_index :pgbus_presence_members,
+              :last_seen_at,
+              where: "connection_id IS NOT NULL",
+              name: "idx_pgbus_presence_members_seat_expiry"
   end
 end

data/lib/generators/pgbus/templates/add_presence_seats.rb.erb

@@ -0,0 +1,38 @@
+class AddPgbusPresenceSeats < ActiveRecord::Migration<%= migration_version %>
+  def up
+    add_column :pgbus_presence_members, :connection_id, :string
+    add_column :pgbus_presence_members, :seat, :string
+    add_column :pgbus_presence_members, :state, :jsonb, null: false, default: {}
+
+    # Existing rows are member-keyed (connection_id IS NULL) and keep their
+    # one-row-per-member key; seat rows get one row per connection.
+    remove_index :pgbus_presence_members, name: "idx_pgbus_presence_members_pk"
+    add_index :pgbus_presence_members, %i[stream_name member_id],
+              unique: true, where: "connection_id IS NULL",
+              name: "idx_pgbus_presence_members_member_key"
+    add_index :pgbus_presence_members, %i[stream_name connection_id],
+              unique: true, where: "connection_id IS NOT NULL",
+              name: "idx_pgbus_presence_members_connection_key"
+    add_index :pgbus_presence_members, %i[stream_name member_id],
+              name: "idx_pgbus_presence_members_member"
+    add_index :pgbus_presence_members, :last_seen_at,
+              where: "connection_id IS NOT NULL",
+              name: "idx_pgbus_presence_members_seat_expiry"
+  end
+
+  def down
+    # Seat rows cannot satisfy the old one-row-per-member key.
+    execute "DELETE FROM pgbus_presence_members WHERE connection_id IS NOT NULL"
+
+    remove_index :pgbus_presence_members, name: "idx_pgbus_presence_members_seat_expiry"
+    remove_index :pgbus_presence_members, name: "idx_pgbus_presence_members_member"
+    remove_index :pgbus_presence_members, name: "idx_pgbus_presence_members_connection_key"
+    remove_index :pgbus_presence_members, name: "idx_pgbus_presence_members_member_key"
+    add_index :pgbus_presence_members, %i[stream_name member_id],
+              unique: true, name: "idx_pgbus_presence_members_pk"
+
+    remove_column :pgbus_presence_members, :state
+    remove_column :pgbus_presence_members, :seat
+    remove_column :pgbus_presence_members, :connection_id
+  end
+end

data/lib/generators/pgbus/templates/initializer.rb.erb

@@ -36,6 +36,10 @@ Pgbus.configure do |c|
   c.workers = []
   c.capsule :default,  queues: %w[critical default], threads: 5
   c.capsule :low,      queues: %w[low],              threads: 2
+  # CPU-bound jobs (rendering, reports, PDFs): threads share one GVL, so use
+  # processes instead. Capsule-level recycle limits override the global ones.
+  # c.capsule :render,   queues: %w[render], threads: 1, processes: 4,
+  #                      max_memory_mb: 1_536
 
   # --- Worker recycling (prevents memory bloat) --------------------------
   c.max_jobs_per_worker = 10_000

data/lib/pgbus/active_job/executor.rb

@@ -26,7 +26,10 @@ module Pgbus
         read_count = message.read_ct.to_i
 
         if read_count > config.max_retries
-          handle_dead_letter(message, queue_name, payload, source_queue: source_queue)
+          # Read the last error before clear! deletes the only row that has
+          # it: the DLQ copy carries it in its headers (issue #495).
+          last_error = FailedEventRecorder.last_error(queue_name: queue_name, msg_id: message.msg_id.to_i)
+          handle_dead_letter(message, queue_name, payload, source_queue: source_queue, last_error: last_error)
           FailedEventRecorder.clear!(queue_name: queue_name, msg_id: message.msg_id.to_i)
           signal_concurrency(payload)
           signal_batch_discarded(payload)
@@ -39,7 +42,8 @@ module Pgbus
             job_id: payload["job_id"],
             provider_job_id: payload["provider_job_id"],
             read_ct: read_count,
-            msg_id: message.msg_id.to_i
+            msg_id: message.msg_id.to_i,
+            error: last_error&.dig(:error_class)
           )
           Pgbus.logger.debug { "[Pgbus::Executor] dead_lettered #{log_tag(message, queue_name)} job_class=#{job_class}" }
           return :dead_lettered
@@ -428,20 +432,26 @@ module Pgbus
         defined?(PGMQ::Errors::ConnectionError) && error.is_a?(PGMQ::Errors::ConnectionError)
       end
 
-      def handle_dead_letter(message, queue_name, payload, source_queue: nil)
+      def handle_dead_letter(message, queue_name, payload, source_queue: nil, last_error: nil)
         Pgbus.logger.warn do
           job_class = payload["job_class"] || "unknown"
-          "[Pgbus] Moving job #{job_class} to dead letter queue after #{message.read_ct} attempts"
+          error = last_error ? " (last error: #{last_error[:error_class]})" : ""
+          "[Pgbus] Moving job #{job_class} to dead letter queue after #{message.read_ct} attempts#{error}"
         end
+        headers = DeadLetterHeader.build(
+          existing: message.headers, reason: DeadLetterHeader::REASON_MAX_RETRIES, source: "worker",
+          source_queue: source_queue || config.queue_name(queue_name), attempts: message.read_ct.to_i,
+          max_retries: config.max_retries, error: last_error
+        )
         if source_queue
           client.ensure_dead_letter_queue(queue_name)
           dlq_name = config.dead_letter_queue_name(queue_name)
           client.transaction do |txn|
-            txn.produce(dlq_name, message.message, headers: message.headers)
+            txn.produce(dlq_name, message.message, headers: headers)
             txn.delete(source_queue, message.msg_id.to_i)
           end
         else
-          client.move_to_dead_letter(queue_name, message)
+          client.move_to_dead_letter(queue_name, message, headers: headers)
         end
       end
     end

data/lib/pgbus/cli/dlq.rb

@@ -12,7 +12,8 @@ module Pgbus
     module DLQ
       module_function
 
-      ROW_FORMAT = "%-10s %-32s %-28s %-8s %s"
+      ROW_FORMAT = "%-10s %-32s %-28s %-8s %-26s %s"
+      REASON_WIDTH = 40
 
       def start(args, data_source: Pgbus::Web::DataSource.new)
         subcommand = args.first
@@ -41,7 +42,7 @@ module Pgbus
         end
 
         print_list_table(messages)
-        puts "-" * 96
+        puts "-" * 140
         puts "Total dead-letter messages: #{data_source.dlq_total_count} " \
              "(page #{options[:page]}, #{options[:per_page]} per page)"
       end
@@ -56,6 +57,7 @@ module Pgbus
         puts "origin:      #{origin_queue(detail[:queue_name])}"
         puts "read_ct:     #{detail[:read_ct]}"
         puts "enqueued_at: #{detail[:enqueued_at]}"
+        print_dead_letter(Pgbus::Web::DeadLetterReason.present(detail))
         puts "payload:"
         puts Pgbus::Web::PayloadFilter.filter_json(detail[:message])
       end
@@ -120,14 +122,39 @@ module Pgbus
       end
 
       def print_list_table(messages)
-        puts format(ROW_FORMAT, "MSG_ID", "DLQ QUEUE", "ORIGIN QUEUE", "READ_CT", "ENQUEUED_AT")
-        puts "-" * 96
+        puts format(ROW_FORMAT, "MSG_ID", "DLQ QUEUE", "ORIGIN QUEUE", "READ_CT", "ENQUEUED_AT", "REASON")
+        puts "-" * 140
         messages.each do |m|
+          reason = Pgbus::Web::DeadLetterReason.present(m)
           puts format(ROW_FORMAT, m[:msg_id], m[:queue_name], origin_queue(m[:queue_name]),
-                      m[:read_ct], m[:enqueued_at])
+                      m[:read_ct], m[:enqueued_at], (reason.error_class || reason.reason_key).to_s[0, REASON_WIDTH])
         end
       end
 
+      # Why the message died, from its pgbus_dead_letter header (issue #495).
+      def print_dead_letter(result)
+        if result.legacy?
+          puts "reason:      not recorded (dead-lettered before pgbus #{Pgbus::DeadLetterHeader::SINCE})"
+          return
+        end
+
+        puts "died:        #{result.died_at}"
+        puts "attempts:    #{result.attempts}/#{result.max_retries}"
+        puts "source:      #{result.source_queue}"
+        puts "reason:      #{result.reason}"
+        puts "error:       #{dead_letter_error(result)}"
+        puts "retried:     #{result.retried_before} time(s) from the DLQ before" if result.retried_before
+      end
+
+      def dead_letter_error(result)
+        return "none recorded" unless result.error_class
+
+        error = "#{result.error_class}: #{result.error_message} (attempt #{result.error_attempt})"
+        # A stored message is untrusted: newlines would break the layout and
+        # ANSI sequences could rewrite the operator's terminal.
+        error.gsub(/[\x00-\x1f\x7f]/) { |char| format("\\x%02X", char.ord) }
+      end
+
       def origin_queue(dlq_queue_name)
         dlq_queue_name.delete_suffix(Pgbus::DEAD_LETTER_SUFFIX)
       end

data/lib/pgbus/client.rb

@@ -592,7 +592,9 @@ module Pgbus
       end
     end
 
-    def move_to_dead_letter(queue_name, message)
+    # headers: what the DLQ copy carries. Movers pass the message's headers
+    # merged with a DeadLetterHeader block; the default copies them verbatim.
+    def move_to_dead_letter(queue_name, message, headers: message.headers)
       dlq_name = config.dead_letter_queue_name(queue_name)
       full_queue = config.queue_name(queue_name)
 
@@ -600,7 +602,7 @@ module Pgbus
         ensure_dead_letter_queue(queue_name)
         synchronized do
           @pgmq.transaction do |txn|
-            txn.produce(dlq_name, message.message, headers: message.headers)
+            txn.produce(dlq_name, message.message, headers: headers)
             txn.delete(full_queue, message.msg_id.to_i)
           end
         end

data/lib/pgbus/configuration/presence_settings.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Configuration
+    # Seat expiry and the change hook for connection-driven presence
+    # (issue #515). EXPERIMENTAL, like the other streams_presence_* settings.
+    #
+    #   config.streams_presence_ttl = 60                                   # every stream
+    #   config.streams_presence_ttl = { /^doc:/ => 5.minutes, default: 60 } # per pattern
+    #   config.streams_presence_on_change = ->(stream_name, change) { ... }
+    #
+    # `change` is { type: :join | :leave, connection_id:, seat:, member_id: }.
+    # An expired seat is reported as a :leave.
+    module PresenceSettings
+      DEFAULT_PRESENCE_TTL = 60
+
+      attr_accessor :streams_presence_on_change
+      attr_writer :streams_presence_ttl
+
+      def streams_presence_ttl
+        @streams_presence_ttl.nil? ? DEFAULT_PRESENCE_TTL : @streams_presence_ttl
+      end
+
+      # Seconds a seat may stay silent on `stream_name` before the heartbeat
+      # expires it. A pattern matches like streams_presence_patterns (exact
+      # String or Regexp); the first match wins.
+      def presence_ttl_for(stream_name)
+        ttl = streams_presence_ttl
+        return presence_seconds(ttl) unless ttl.is_a?(Hash)
+
+        match = ttl.find { |pattern, _| pattern_matches?(pattern, stream_name) }
+        presence_seconds(match ? match.last : ttl.fetch(:default, DEFAULT_PRESENCE_TTL))
+      end
+
+      # The smallest ttl configured: the expiry scan's candidate cutoff.
+      def presence_min_ttl
+        ttl = streams_presence_ttl
+        return presence_seconds(ttl) unless ttl.is_a?(Hash)
+
+        [*ttl.values, ttl.fetch(:default, DEFAULT_PRESENCE_TTL)].map { |v| presence_seconds(v) }.min
+      end
+
+      # Reports one join, leave or expiry to streams_presence_on_change.
+      # A raising hook is logged and swallowed, like the rest of the
+      # presence path: it must not break a connection or a sweep.
+      def notify_presence_change(stream_name, change)
+        hook = streams_presence_on_change
+        return unless hook
+
+        hook.call(stream_name, change)
+      rescue StandardError => e
+        Pgbus.logger.error do
+          "[Pgbus] streams_presence_on_change raised for #{stream_name}: #{e.class}: #{e.message}"
+        end
+      end
+
+      private
+
+      def validate_presence_settings!
+        if !streams_presence_on_change.nil? && !streams_presence_on_change.respond_to?(:call)
+          raise Pgbus::ConfigurationError,
+                "streams_presence_on_change must respond to #call (a Proc/lambda) or be nil"
+        end
+
+        ttl = streams_presence_ttl
+        values = ttl.is_a?(Hash) ? ttl.values : [ttl]
+        unless values.all? { |v| v.is_a?(Numeric) && v.to_f.positive? }
+          raise Pgbus::ConfigurationError,
+                "streams_presence_ttl must be a positive number of seconds or a Hash of pattern => seconds"
+        end
+
+        warn_presence_ttl_below_heartbeat
+      end
+
+      # A ttl at or below the heartbeat interval lets another process expire
+      # live seats between touches, so every tick reports a leave and a join.
+      def warn_presence_ttl_below_heartbeat
+        heartbeat = streams_heartbeat_interval
+        return unless heartbeat.is_a?(Numeric) && presence_min_ttl <= heartbeat
+
+        Pgbus.logger.warn do
+          "[Pgbus] streams_presence_ttl (#{presence_min_ttl}s) should exceed streams_heartbeat_interval " \
+            "(#{heartbeat}s), or live presence seats are expired and re-joined every tick"
+        end
+      end
+
+      # Seconds as an Integer when whole, a Float otherwise (a Duration
+      # becomes plain seconds), so fractional ttls are not truncated.
+      def presence_seconds(value)
+        seconds = value.to_f
+        seconds == seconds.floor ? seconds.to_i : seconds
+      end
+
+      def pattern_matches?(pattern, stream_name)
+        case pattern
+        when Regexp then pattern.match?(stream_name)
+        when :default then false
+        else pattern.to_s == stream_name
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/configuration.rb

@@ -4,6 +4,8 @@ require "logger"
 
 module Pgbus
   class Configuration
+    include PresenceSettings
+
     # Connection settings
     attr_accessor :database_url, :connection_params, :pool_size, :pool_timeout
 
@@ -590,6 +592,21 @@ module Pgbus
       entry.fetch(:read_ahead, nil) || read_ahead
     end
 
+    # Recycle limits a capsule may set for its own workers (issue #503).
+    RECYCLE_LIMIT_KEYS = %i[max_jobs_per_worker max_memory_mb max_worker_lifetime].freeze
+
+    # How many identical worker processes the supervisor forks for one
+    # capsule (issue #503). Default 1.
+    def processes_for(entry)
+      entry.fetch(:processes, nil) || 1
+    end
+
+    # One recycle limit for a capsule, falling back to the global value
+    # (mirrors read_ahead_for). nil means the limit is off.
+    def recycle_limit_for(entry, key)
+      entry.fetch(key, nil) || public_send(key)
+    end
+
     # Returns the execution mode for a specific worker config hash,
     # falling back to the global execution_mode setting.
     def execution_mode_for(worker_config)
@@ -846,6 +863,7 @@ module Pgbus
       end
 
       validate_read_ahead!
+      validate_capsule_processes!
 
       if priority_levels && !(priority_levels.is_a?(Integer) && priority_levels >= 1 && priority_levels <= 10)
         raise Pgbus::ConfigurationError, "priority_levels must be an integer between 1 and 10"
@@ -879,6 +897,27 @@ module Pgbus
       warn_read_ahead_without_heartbeat(settings)
     end
 
+    # Per-capsule processes (a positive Integer) and recycle limits (a positive
+    # number; unset falls back to the global value). The Array form of
+    # +workers=+ bypasses +capsule+, so both are checked here (issue #503).
+    def validate_capsule_processes!
+      Array(workers).each do |w|
+        validate_processes!(w[:processes]) unless w[:processes].nil?
+        RECYCLE_LIMIT_KEYS.each do |key|
+          value = w[key]
+          next if value.nil? || (value.is_a?(Numeric) && value.positive?)
+
+          raise Pgbus::ConfigurationError, "capsule #{key} must be a positive number (got #{value.inspect})"
+        end
+      end
+    end
+
+    def validate_processes!(value)
+      return if value.is_a?(Integer) && value.positive?
+
+      raise Pgbus::ConfigurationError, "capsule processes must be a positive Integer (got #{value.inspect})"
+    end
+
     # Buffered claims are kept invisible only by the visibility heartbeat.
     # Without it a message buffered longer than visibility_timeout can be
     # claimed by another worker while it still waits here. Legal, but warned.
@@ -1056,6 +1095,8 @@ module Pgbus
         raise Pgbus::ConfigurationError, "streams_presence_member must respond to #call (a Proc/lambda) or be nil"
       end
 
+      validate_presence_settings!
+
       return if streams_orphan_threshold.nil?
       return if streams_orphan_threshold.is_a?(Numeric) && streams_orphan_threshold.positive?
 
@@ -1209,15 +1250,23 @@ module Pgbus
     #
     #   c.capsule :critical, queues: %w[critical], threads: 5
     #   c.capsule :gated, queues: %w[gated], threads: 1, single_active_consumer: true
+    #   c.capsule :render, queues: %w[render], threads: 1, processes: 4,
+    #             max_memory_mb: 1_536, max_worker_lifetime: 6.hours
+    #
+    # processes: N forks N identical workers for the capsule (CPU-bound jobs:
+    # threads share one GVL, processes do not). The capsule-level recycle
+    # limits override the global ones for this capsule's workers only.
     #
     # Names must be unique. Queues must not overlap with capsules already
     # defined (would cause double-processing). Composes with the string DSL —
     # +c.workers "..."+ followed by +c.capsule :name, ...+ appends the
     # named capsule to the list parsed from the string.
-    def capsule(name, queues:, threads:, **)
+    def capsule(name, queues:, threads:, **options)
       raise Pgbus::ConfigurationError, "capsule queues must be a non-empty Array" unless queues.is_a?(Array) && queues.any?
       raise Pgbus::ConfigurationError, "capsule threads must be a positive Integer" unless threads.is_a?(Integer) && threads.positive?
 
+      validate_processes!(options[:processes]) unless options[:processes].nil?
+
       normalized_name = name.to_s
       @workers ||= []
 
@@ -1227,7 +1276,7 @@ module Pgbus
 
       validate_no_queue_overlap!(queues)
 
-      @workers << { name: normalized_name, queues: queues, threads: threads, ** }
+      @workers << { name: normalized_name, queues: queues, threads: threads, **options }
     end
 
     # Look up a capsule by its name. Accepts symbol or string. Returns the

data/lib/pgbus/dead_letter_header.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Pgbus
+  # The `pgbus_dead_letter` block a mover writes into a message's PGMQ
+  # headers when it moves the message to a dead-letter queue (issue #495):
+  # why it was moved, from where, after how many attempts, and the last
+  # recorded error. Pure — no I/O — so the executor, the consumer, the
+  # dashboard, MCP and the CLI all read and write the same shape.
+  #
+  # PGMQ headers travel as raw JSON strings, so every entry point accepts a
+  # String (or a Hash, or nil) and build/strip_for_retry return a String.
+  module DeadLetterHeader
+    KEY = "pgbus_dead_letter"
+    # Top-level counter on a live message retried out of a DLQ. Folded into
+    # the block as `retries_from_dlq` when the message dies again.
+    RETRIES_KEY = "pgbus_dlq_retries"
+    ORIGINAL_KEY = "pgbus_original_headers"
+    VERSION = 1
+    REASON_MAX_RETRIES = "max_retries_exceeded"
+    # The release that started writing the block: rows without it predate it.
+    SINCE = "0.18.0"
+    MESSAGE_LIMIT = 1_000
+    BACKTRACE_LINES = 10
+    BACKTRACE_LIMIT = 2_000
+
+    module_function
+
+    # error: FailedEventRecorder.last_error's Hash, or nil when no failure
+    # was recorded. Returns the merged headers as a JSON string.
+    def build(existing:, reason:, source:, source_queue:, attempts:, max_retries:, error: nil, now: Time.now.utc)
+      headers = decode(existing, warn: true)
+      retries = count(headers.delete(RETRIES_KEY))
+      block = {
+        "version" => VERSION,
+        "reason" => reason,
+        "source" => source,
+        "source_queue" => source_queue,
+        "attempts" => attempts,
+        "max_retries" => max_retries,
+        "dead_lettered_at" => iso(now)
+      }
+      block["retries_from_dlq"] = retries if retries.positive?
+      block.merge!(error_fields(error)) if error
+      JSON.generate(headers.merge(KEY => block))
+    end
+
+    # The block as a string-keyed Hash, or nil. Never raises.
+    def parse(headers)
+      block = decode(headers, warn: false)[KEY]
+      block.is_a?(Hash) ? block : nil
+    end
+
+    # A live message must not claim to be dead: drop the block, and carry
+    # how many times it has come back out of a DLQ. A DLQ message has no
+    # top-level counter (build folded it into the block), so the block is
+    # the only place to read the previous count from.
+    def strip_for_retry(headers)
+      retries = count(parse(headers)&.dig("retries_from_dlq")) + 1
+      stripped = decode(headers, warn: false)
+      stripped.delete(KEY)
+      stripped[RETRIES_KEY] = retries
+      JSON.generate(stripped)
+    end
+
+    # A counter read from headers anyone could have written: an Integer or a
+    # numeric String counts, anything else is 0. Never raises, so a bad value
+    # can't stop a dead-letter.
+    def count(value)
+      case value
+      when Integer then value
+      when String then Integer(value, 10, exception: false) || 0
+      else 0
+      end
+    end
+
+    def error_fields(error)
+      {
+        "error_class" => error[:error_class],
+        "error_message" => error[:error_message]&.to_s&.slice(0, MESSAGE_LIMIT),
+        "backtrace" => backtrace_head(error[:backtrace]),
+        "error_attempt" => error[:retry_count].to_i + 1,
+        "error_recorded_at" => error[:failed_at] && iso(error[:failed_at])
+      }.compact
+    end
+
+    def backtrace_head(backtrace)
+      return if backtrace.nil? || backtrace.empty?
+
+      lines = backtrace.is_a?(Array) ? backtrace : backtrace.to_s.split("\n")
+      lines.first(BACKTRACE_LINES).join("\n").slice(0, BACKTRACE_LIMIT)
+    end
+
+    def iso(value)
+      case value
+      when Time then value.getutc.iso8601(6)
+      when String then value
+      else value.respond_to?(:to_time) ? value.to_time.utc.iso8601(6) : value.to_s
+      end
+    end
+
+    # Always a Hash. Headers that are not a JSON object are kept, not
+    # dropped, under ORIGINAL_KEY.
+    def decode(headers, warn:)
+      case headers
+      when nil, "" then {}
+      when Hash then headers.transform_keys(&:to_s)
+      else wrap(JSON.parse(headers.to_s), headers, warn)
+      end
+    rescue JSON::ParserError
+      log_kept(headers) if warn
+      { ORIGINAL_KEY => headers }
+    end
+
+    def wrap(parsed, raw, warn)
+      return parsed if parsed.is_a?(Hash)
+
+      log_kept(raw) if warn
+      { ORIGINAL_KEY => parsed }
+    end
+
+    # The raw value is not logged: headers can carry caller secrets.
+    def log_kept(_raw)
+      Pgbus.logger.warn { "[Pgbus] Dead-letter headers were not a JSON object; kept under #{ORIGINAL_KEY}" }
+    end
+  end
+end