pgbus 0.22.0 → 0.23.0

data/lib/pgbus/stat_buffer.rb

@@ -7,6 +7,8 @@ module Pgbus
   class StatBuffer
     DEFAULT_FLUSH_SIZE = 100
     DEFAULT_FLUSH_INTERVAL = 5 # seconds
+    BASE_COLUMNS = "job_class, queue_name, status, duration_ms"
+    ALL_COLUMNS = "#{BASE_COLUMNS}, enqueue_latency_ms, retry_count".freeze
 
     attr_reader :flush_size, :flush_interval
 
@@ -65,41 +67,80 @@ module Pgbus
 
     private
 
+    # One multi-row INSERT per flush, built here rather than by
+    # JobStat.insert_all: ActiveRecord's per-value attribute check and type
+    # cast and its RETURNING "id" cost ~1 ms of Ruby CPU per 100 rows, 12-15 %
+    # of a no-op job's on-CPU time (issue #622). The integer columns are
+    # written through Integer(); the strings (job_class comes from the
+    # message) go through the connection's quoting, once per distinct value.
+    #
+    # Always attempt all 6 columns. If the latency migration hasn't run, the
+    # statement fails, and we fall back to base columns. This avoids relying
+    # on the memoized latency_columns? flag which can be stuck at false if
+    # evaluated before the connection is ready.
     def write_to_database(entries)
       return unless JobStat.table_exists?
 
-      # Always attempt all 6 columns. If the latency migration hasn't
-      # run, the first flush will fail, and we fall back to base columns.
-      # This avoids relying on the memoized latency_columns? flag which
-      # can be stuck at false if evaluated before the connection is ready.
-      rows = entries.map do |e|
-        { job_class: e[:job_class], queue_name: e[:queue_name],
-          status: e[:status], duration_ms: e[:duration_ms],
-          enqueue_latency_ms: e[:enqueue_latency_ms], retry_count: e[:retry_count] }
-      end
+      JobStat.connection_pool.with_connection do |conn|
+        sql = insert_sql(conn, entries, latency: true)
+        conn.execute(sql, "Pgbus::JobStat Bulk Insert") if sql
+      rescue ActiveRecord::StatementInvalid => e
+        raise unless missing_latency_column?(e)
 
-      JobStat.insert_all(rows)
-    rescue ActiveRecord::StatementInvalid, ActiveModel::UnknownAttributeError => e
-      # Column doesn't exist — fall back to base columns only
-      if e.message.include?("enqueue_latency_ms") || e.message.include?("retry_count")
-        Pgbus.logger.warn { "[Pgbus] Latency columns missing — recording stats without latency data" } unless @degraded_warned
-        @degraded_warned = true
-        base_rows = entries.map do |entry|
-          { job_class: entry[:job_class], queue_name: entry[:queue_name],
-            status: entry[:status], duration_ms: entry[:duration_ms] }
-        end
-        begin
-          JobStat.insert_all(base_rows)
-        rescue StandardError => fallback_error
-          Pgbus.logger.warn { "[Pgbus] Stat buffer fallback flush failed: #{fallback_error.message}" }
-        end
-      else
-        Pgbus.logger.warn { "[Pgbus] Stat buffer flush failed: #{e.message}" }
+        write_base_columns(conn, entries)
       end
     rescue StandardError => e
       Pgbus.logger.warn { "[Pgbus] Stat buffer flush failed: #{e.message}" }
     end
 
+    # PostgreSQL's undefined_column (42703, PG::UndefinedColumn: the cause
+    # ActiveRecord keeps) naming a latency column in its first line. The
+    # class, not the wording, says a column is missing (the wording follows
+    # the server's lc_messages); only the first line names which, because the
+    # "LINE 1:" excerpt of the statement below it shows both latency columns
+    # whatever went wrong. pg is loaded once PostgreSQL has raised anything.
+    def missing_latency_column?(error)
+      return false unless defined?(::PG::UndefinedColumn) && error.cause.is_a?(::PG::UndefinedColumn)
+
+      primary = error.cause.message.lines.first.to_s
+      primary.include?("enqueue_latency_ms") || primary.include?("retry_count")
+    end
+
+    def write_base_columns(conn, entries)
+      Pgbus.logger.warn { "[Pgbus] Latency columns missing — recording stats without latency data" } unless @degraded_warned
+      @degraded_warned = true
+      sql = insert_sql(conn, entries, latency: false)
+      conn.execute(sql, "Pgbus::JobStat Bulk Insert") if sql
+    rescue StandardError => e
+      Pgbus.logger.warn { "[Pgbus] Stat buffer fallback flush failed: #{e.message}" }
+    end
+
+    def insert_sql(conn, entries, latency:)
+      quoted = Hash.new { |memo, value| memo[value] = conn.quote(value) }
+      columns = latency ? ALL_COLUMNS : BASE_COLUMNS
+      values = entries.filter_map { |entry| sql_row(entry, quoted, latency) }
+      return if values.empty?
+
+      "INSERT INTO #{JobStat.quoted_table_name} (#{columns}) VALUES #{values.join(", ")}"
+    end
+
+    # One entry's tuple, or nil when an integer column holds something
+    # Integer() refuses: that entry is dropped, the rest of the flush is still
+    # written. Logged on the six-column pass only: the base-column retry runs
+    # on the same entries, so anything it drops was dropped and logged already.
+    def sql_row(entry, quoted, latency)
+      row = "(#{quoted[entry[:job_class]]}, #{quoted[entry[:queue_name]]}, #{quoted[entry[:status]]}, #{sql_integer(entry[:duration_ms])}"
+      row << ", #{sql_integer(entry[:enqueue_latency_ms])}, #{sql_integer(entry[:retry_count])}" if latency
+      row << ")"
+    rescue ArgumentError, TypeError => e
+      Pgbus.logger.warn { "[Pgbus] Stat buffer dropped a #{entry[:job_class]} stat: #{e.message}" } if latency
+      nil
+    end
+
+    def sql_integer(value)
+      value.nil? ? "NULL" : Integer(value).to_s
+    end
+
     def monotonic_now
       ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
     end

data/lib/pgbus/streams/cursor.rb

@@ -12,6 +12,12 @@ module Pgbus
     #      because EventSource cannot send custom headers on the initial request)
     #
     # Returns 0 when no cursor is present (i.e. "deliver everything from now").
+    #
+    # A negative Last-Event-ID is not a cursor: ephemeral broadcasts carry a
+    # negative `id:` (they have no archive position), and a native EventSource
+    # that saw one last echoes it on reconnect. It is skipped, so the
+    # element's ?since= (its last durable id) decides (issue #621). A negative
+    # ?since= is still rejected: the element never sends one.
     module Cursor
       # PGMQ msg_id is BIGINT — strictly within signed 64-bit range.
       MAX_MSG_ID = (2**63) - 1
@@ -34,7 +40,7 @@ module Pgbus
       end
 
       def self.pick(last_event_id, query_since)
-        return last_event_id if present?(last_event_id)
+        return last_event_id if present?(last_event_id) && !ephemeral_id?(last_event_id)
         return query_since   if present?(query_since)
 
         nil
@@ -42,15 +48,20 @@ module Pgbus
 
       def self.present?(value)
         return false if value.nil?
-        # Any Integer is "present" so precedence is decided here, not by
-        # the sign of the value. validate! rejects negatives separately
-        # so a caller passing a literal -1 still crashes loud rather than
-        # silently falling through to query_since.
+        # Any Integer is "present"; pick skips a negative last_event_id (an
+        # ephemeral frame's id) and validate! rejects a negative ?since=.
         return true if value.is_a?(Integer)
 
         !value.to_s.strip.empty?
       end
 
+      # An ephemeral frame's id: a negative Integer, or its decimal text.
+      def self.ephemeral_id?(value)
+        return value.negative? if value.is_a?(Integer)
+
+        value.to_s.strip.match?(/\A-\d+\z/)
+      end
+
       def self.coerce(raw)
         return raw if raw.is_a?(Integer)
 
@@ -65,7 +76,7 @@ module Pgbus
         raise InvalidCursor, "cursor #{value} is out of BIGINT range" if value > MAX_MSG_ID
       end
 
-      private_class_method :pick, :present?, :coerce, :validate!
+      private_class_method :pick, :present?, :ephemeral_id?, :coerce, :validate!
     end
   end
 end

data/lib/pgbus/streams/envelope.rb

@@ -70,6 +70,16 @@ module Pgbus
         "retry: #{milliseconds}\n\n"
       end
 
+      # The SSE event name for a frame: the envelope's typed event when
+      # present, else the default turbo-stream. Plain ReadAfter::Envelopes
+      # (no event field) and StreamEnvelopes with a nil event both fall back
+      # to the default (issue #170). Shared by the connections and the
+      # dispatcher, which frames each envelope once per wake (issue #621).
+      def self.sse_event_for(envelope)
+        event = envelope.respond_to?(:event) ? envelope.event : nil
+        event && !event.to_s.empty? ? event.to_s : Pgbus::Streams::DEFAULT_SSE_EVENT
+      end
+
       def self.http_response_headers
         RESPONSE_HEADERS
       end
@@ -82,6 +92,12 @@ module Pgbus
       # empty strings, so a payload ending in \n round-trips as an empty
       # final `data:` line (the client's rejoin restores the newline).
       def self.data_lines(str)
+        # Most payloads are one line (a rendered turbo-stream): no split, map
+        # or join, one String (issue #621). Two memchr scans beat the regex
+        # match? (232 vs 388 ns on a 170-byte line, YJIT) and cost a multi-line
+        # payload ~3 % before its split.
+        return "data: #{str}\n" unless str.include?("\n") || str.include?("\r")
+
         lines = str.split(DATA_LINE_BREAK, -1)
         lines = [""] if lines.empty? # "".split → [] — an empty payload still gets its data: line
         lines.map { |line| "data: #{line}\n" }.join

data/lib/pgbus/streams/key.rb

@@ -9,7 +9,7 @@ module Pgbus
     # PGMQ queue names are bounded by two ceilings: PostgreSQL's
     # NAMEDATALEN (63 chars for `pgmq.q_<name>`) and pgmq-ruby's own
     # stricter runtime check (`length >= 48` in
-    # `PGMQ::Client#validate_queue_name!`). The effective budget is the
+    # `PGMQ::QueueName.validate!`). The effective budget is the
     # lower of the two, exposed as `QueueNameValidator::MAX_QUEUE_NAME_LENGTH`
     # (currently 47). Any stream name composed from UUID primary keys
     # and turbo-rails-style dom ids blows past that budget almost

data/lib/pgbus/table_maintenance.rb

@@ -37,7 +37,7 @@ module Pgbus
             q RECORD;
           BEGIN
             FOR q IN SELECT queue_name FROM pgmq.meta LOOP
-              EXECUTE format('ALTER TABLE pgmq.q_%I SET (fillfactor = #{FILLFACTOR})', q.queue_name);
+              EXECUTE format('ALTER TABLE pgmq.%I SET (fillfactor = #{FILLFACTOR})', 'q_' || lower(q.queue_name));
             END LOOP;
           END $$;
         SQL

data/lib/pgbus/uniqueness.rb

@@ -13,13 +13,15 @@ module Pgbus
   #   1. Enqueue: INSERT INTO pgbus_uniqueness_keys ON CONFLICT DO NOTHING
   #      (logical queue, msg_id=0). After send_message, bind! writes the
   #      real msg_id. The lock row lives as long as the job is in the queue
-  #      or executing.
+  #      or executing (:until_executing: only while it is queued — the
+  #      executor releases it before perform).
   #   2. Execution: PGMQ's visibility timeout is the execution lock —
   #      no separate claim_for_execution step needed.
-  #   3. Retry: a retry_job / retry_on re-enqueue passes through the key the
-  #      running attempt holds, and the row is handed to the retry: unbound
-  #      and re-stamped before the retry is sent or parked (unbind!), bound
-  #      to it once sent (bind!).
+  #   3. Retry (:until_executed): a retry_job / retry_on re-enqueue passes
+  #      through the key the running attempt holds, and the row is handed to
+  #      the retry: unbound and re-stamped before the retry is sent or parked
+  #      (unbind!), bound to it once sent (bind!). An :until_executing
+  #      attempt released its row at start, so its retry goes out with none.
   #   4. Completion/DLQ: the finishing message deletes the row only while it
   #      holds it (release_held_by!), so a row handed to a retry, or a
   #      successor's, stays. The dashboard's discards do the same.
@@ -31,9 +33,20 @@ module Pgbus
   #   :until_executed  — Lock acquired at enqueue, held through execution, released on
   #                      completion or DLQ. Prevents duplicate enqueue AND duplicate execution.
   #
+  #   :until_executing — Lock acquired at enqueue, released when execution starts
+  #                      (a debounce). Further enqueues are dropped while a copy is
+  #                      queued; one that arrives while a copy runs is accepted, so a
+  #                      run starting after it observes the state written before that
+  #                      enqueue. At most one copy is queued at a time.
+  #                      Two runs can overlap; compose with limits_concurrency to: 1,
+  #                      on_conflict: :block for "debounce and no overlap".
+  #
   #   :while_executing — Lock acquired at execution start, released on completion.
   #                      Allows duplicate enqueue (multiple copies in queue) but only one
-  #                      executes at a time.
+  #                      executes at a time. A copy read while another message holds
+  #                      the key follows on_conflict (issue #629): :discard completes
+  #                      it without running; :reject and :log leave it for a
+  #                      backed-off redelivery (:log warns).
   #
   # Usage:
   #   class ImportOrderJob < ApplicationJob
@@ -50,12 +63,17 @@ module Pgbus
 
     METADATA_KEY = "pgbus_uniqueness_key"
     STRATEGY_KEY = "pgbus_uniqueness_strategy"
+    # The on_conflict policy of a :while_executing job, read by the executor
+    # when the lock is held by another message (issue #629).
+    ON_CONFLICT_KEY = "pgbus_uniqueness_on_conflict"
     # Synthetic queue stored before produce when the caller does not know the
     # real queue yet. Never a live PGMQ queue — the reaper must not probe
     # pgmq.q_<prefix>_pending for these rows (issue #418).
     PLACEHOLDER_QUEUE = "pending"
 
-    VALID_STRATEGIES = %i[until_executed while_executing].freeze
+    VALID_STRATEGIES = %i[until_executed until_executing while_executing].freeze
+    # The strategies that take the lock at enqueue, before the message exists.
+    ENQUEUE_LOCK_STRATEGIES = %i[until_executed until_executing].freeze
     VALID_CONFLICTS = %i[reject discard log].freeze
 
     # Class-body macro: it runs while the job class loads (at boot, or under the
@@ -129,7 +147,8 @@ module Pgbus
       end
 
       # Guards the class-name default key against the per-record collapse
-      # footgun (#333). When an :until_executed job was declared with NO explicit
+      # footgun (#333). When an enqueue-locked job (:until_executed, or
+      # :until_executing, issue #628) was declared with NO explicit
       # key (so the key is the class name) AND is enqueued WITH arguments, every
       # distinct argument set would resolve to the same class-name key and
       # collapse into one per-class singleton — almost never what the caller
@@ -139,11 +158,11 @@ module Pgbus
       # per-invocation at execution start, not by class-name identity at enqueue).
       def guard_class_name_default!(active_job, config, args)
         return if config[:explicit_key]
-        return unless config[:strategy] == :until_executed
+        return unless ENQUEUE_LOCK_STRATEGIES.include?(config[:strategy])
         return if args.nil? || args.empty?
 
         raise ArgumentError,
-              "#{active_job.class.name} uses ensures_uniqueness strategy: :until_executed with no key: " \
+              "#{active_job.class.name} uses ensures_uniqueness strategy: #{config[:strategy].inspect} with no key: " \
               "but is enqueued with arguments — the default key is the class name, which would collapse " \
               "every distinct argument set into one per-class singleton. Pass an explicit " \
               "key: ->(*args) { ... } that includes the arguments. See https://pgbus.dev/docs/upgrading-pgbus"
@@ -156,10 +175,9 @@ module Pgbus
         key = resolve_key(active_job)
         return payload_hash unless key
 
-        payload_hash.merge(
-          METADATA_KEY => key,
-          STRATEGY_KEY => config[:strategy].to_s
-        )
+        metadata = { METADATA_KEY => key, STRATEGY_KEY => config[:strategy].to_s }
+        metadata[ON_CONFLICT_KEY] = config[:on_conflict].to_s if config[:strategy] == :while_executing
+        payload_hash.merge(metadata)
       end
 
       def extract_key(payload)
@@ -170,19 +188,28 @@ module Pgbus
         payload&.dig(STRATEGY_KEY)&.to_sym
       end
 
+      # The :while_executing policy at the skip point. :reject when the payload
+      # carries none (enqueued before the key existed) or one this version does not know:
+      # that keeps the redelivery such a message had.
+      def extract_on_conflict(payload)
+        policy = payload&.dig(ON_CONFLICT_KEY)&.to_sym
+        VALID_CONFLICTS.include?(policy) ? policy : :reject
+      end
+
       def uniqueness_config(active_job)
         return nil unless active_job.class.respond_to?(:pgbus_uniqueness)
 
         active_job.class.pgbus_uniqueness
       end
 
-      # Acquire the uniqueness lock at enqueue time (:until_executed only).
+      # Acquire the uniqueness lock at enqueue time (:until_executed and
+      # :until_executing).
       # Uses pg_advisory_xact_lock to serialize concurrent attempts.
       # Returns :acquired, :locked, or :no_lock.
       def acquire_enqueue_lock(key, active_job, queue_name: nil, msg_id: nil)
         config = uniqueness_config(active_job)
         return :no_lock unless config
-        return :no_lock unless config[:strategy] == :until_executed
+        return :no_lock unless ENQUEUE_LOCK_STRATEGIES.include?(config[:strategy])
 
         acquired = if msg_id && queue_name
                      UniquenessKey.acquire!(key, queue_name: lock_queue_name(queue_name), msg_id: msg_id)

data/lib/pgbus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pgbus
-  VERSION = "0.22.0"
+  VERSION = "0.23.0"
 end

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

@@ -80,12 +80,21 @@ module Pgbus
           )
           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)
+          payload = row["message"].is_a?(String) ? JSON.parse(row["message"]) : row["message"]
+          # The row Discard would release is the one the copy takes over.
+          holder = lock_holder(queue_name, row["msg_id"], row["headers"], row["enqueued_at"])
+          # A live message must not claim to be dead: strip the block, count the trip.
+          headers = DeadLetterHeader.strip_for_retry(row["headers"])
+          drop_source = -> { @client.delete_message(queue_name, msg_id.to_i, prefixed: false) }
+          outcome = resend_job(payload, lock_queue: lock_queue_for_table(original_queue), holder: holder,
+                                        drop_source: drop_source, headers: JSON.parse(headers)) do
+            @client.transaction do |txn|
+              sent = txn.produce(original_queue, row["message"], headers: headers)
+              txn.delete(queue_name, msg_id.to_i)
+              sent
+            end
           end
-          true
+          outcome != false
         rescue StandardError => e
           Pgbus.logger.debug { "[Pgbus::Web] Error retrying DLQ message #{msg_id}: #{e.message}" }
           false

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

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Web
+    class DataSource
+      # Re-sending a job payload as a new message — DLQ Retry, and failed-job
+      # Retry when the original message is gone (issues #631, #636). The
+      # payload names its uniqueness key and strategy, and its
+      # limits_concurrency key. The copy releases the uniqueness row it holds
+      # when it starts (:until_executing) or finishes (:until_executed), and
+      # signals the semaphore when it finishes. Re-sent without a row or a
+      # slot of its own, that release could free a newer parked copy's key,
+      # and that signal gave back a slot another copy held and promoted a
+      # parked job beside it. So the copy goes out the way Adapter#enqueue
+      # sends a job: the uniqueness key taken unbound before the send and
+      # bound to the new message after it; a slot taken before the send, or
+      # the copy parked behind a full limit (on_conflict: :block), or the
+      # retry refused (:discard, :raise) with the source left in place.
+      module Resend
+        private
+
+        # Yields to send the payload; the block returns the new msg_id.
+        # Returns :sent, :parked (a BlockedExecution the limit's next signal
+        # promotes; nothing is sent and the block does not run), or false
+        # when another copy holds the uniqueness key or the limit is full
+        # under :discard / :raise (nothing is sent, so the source — the DLQ
+        # message or the failed row — stays for a later retry).
+        # +lock_queue+ is the queue as the executor spells the lock
+        # (Uniqueness.lock_queue_name), which is also the logical queue a
+        # parked copy is promoted onto; +holder+ is the [lock queue, msg_id,
+        # enqueued_at] of the message the payload was read from, as the
+        # dashboard's discards name it (#lock_holder). +drop_source+ removes
+        # the source once the copy is parked (a sent copy's source is the
+        # block's to remove). +headers+ (a Hash) are the ones the block
+        # sends; a parked copy carries them to its promotion.
+        def resend_job(payload, lock_queue:, holder:, drop_source:, headers: nil, &)
+          key = resend_lock_key(payload)
+          stamp = key && take_resend_lock(key, lock_queue, holder)
+          if key && !stamp
+            Pgbus.logger.warn { "[Pgbus::Web] Not re-sending #{payload["job_class"]}: uniqueness key #{key} is held by another copy" }
+            return false
+          end
+
+          # Only an error raised by the produce (:produce), or by the park's
+          # commit (:park: the COMMIT may have landed with its reply lost),
+          # can hide a live copy: one from the slot upsert, the park's insert
+          # or the source's removal proves nothing went out, however
+          # database-shaped it is.
+          sending = [nil]
+          begin
+            outcome = resend_holding_slot(payload, lock_queue, drop_source, sending, headers, &)
+          rescue StandardError => e
+            give_back_resend_lock(key, stamp, e, sending: sending.first) if key
+            raise
+          end
+
+          case outcome
+          when :refused
+            give_back_resend_lock(key, stamp) if key
+            false
+          when :parked
+            # Unbound, as a parked enqueue's row is: the promoted copy's
+            # release takes it (UniquenessKey.release_held_by!).
+            :parked
+          else
+            bind_resent_lock(key, lock_queue, outcome, stamp) if key
+            :sent
+          end
+        ensure
+          UniquenessKey.clear_bind_stamp!(key) if key
+        end
+
+        # A failed job's message back to work: its vt reset to 0 while it is
+        # still queued (a second copy would run beside it; a failed attempt
+        # keeps its concurrency slot, so it needs no other), else its payload
+        # re-sent or parked. The failed row goes either way; false (row kept)
+        # while the re-send's key is held or its limit refuses it.
+        def retry_failed_job(event)
+          physical = failed_message_queue(event)
+          return resend_failed_event(event) unless physical
+
+          @client.set_visibility_timeout(physical, event["msg_id"].to_i, vt: 0, prefixed: false)
+          delete_failed_row(event)
+          true
+        end
+
+        # A failed job's payload as a new message on its queue, its failed row
+        # deleted once it is sent or parked. Its message is gone, so it can
+        # hold only a row still bound to it (nil send time: no unbound row is
+        # its own). The delete comes after the key is bound: PGMQ sends on its
+        # own connection, so a failed delete cannot undo the send, and must
+        # not give back the key of a live copy.
+        def resend_failed_event(event) # rubocop:disable Naming/PredicateMethod
+          payload = JSON.parse(event["payload"])
+          headers = event["headers"]
+          headers = JSON.parse(headers) if headers.is_a?(String)
+          lock_queue = Uniqueness.lock_queue_name(event["queue_name"])
+
+          outcome = resend_job(payload, lock_queue: lock_queue, holder: [lock_queue, event["msg_id"].to_i, nil],
+                                        drop_source: -> { delete_failed_row(event) }, headers: headers) do
+            @client.send_message(event["queue_name"], payload, headers: headers)
+          end
+          delete_failed_row(event) if outcome == :sent
+          outcome != false
+        end
+
+        def delete_failed_row(event)
+          connection.exec_delete(
+            "DELETE FROM pgbus_failed_events WHERE id = $1", "Pgbus Delete Failed Event", [event["id"].to_i]
+          )
+        end
+
+        # The key for the copy: the row the source message still holds is
+        # taken over (it went without releasing it — a release that failed,
+        # or a failed job whose message is gone), as a retry takes its
+        # attempt's (Adapter#hand_lock_to_retry); else a free key is
+        # acquired. Returns the row's created_at stamp (bind! and the
+        # give-back match the row by it), nil when another copy holds the
+        # key. A newer copy parked after the source released its row was
+        # acquired after the source was sent, so the takeover never matches it.
+        def take_resend_lock(key, lock_queue, holder)
+          from_queue, from_msg_id, from_enqueued_at = holder
+          stamp = UniquenessKey.unbind!(key, from_queue_name: from_queue, from_msg_id: from_msg_id,
+                                             from_enqueued_at: from_enqueued_at, queue_name: lock_queue)
+          return stamp if stamp
+          return unless UniquenessKey.acquire!(key, queue_name: lock_queue, msg_id: 0)
+
+          Thread.current[:pgbus_uniqueness_created_at]&.[](key)
+        end
+
+        # The copy did not go out (the limit refused it), or the send raised.
+        # Proven unsent, the row taken for it goes (matched by its stamp, so
+        # never a successor's). An error from the produce that may hide a
+        # committed send (a lost connection or reply, as
+        # Adapter#ambiguous_delivery? counts it), or any error from the park's
+        # commit, keeps the row: the copy may be live, and the reaper takes
+        # the row if it is not. A failed give-back is logged, so the send's
+        # error is the one that surfaces.
+        def give_back_resend_lock(key, stamp, error = nil, sending: nil)
+          if sending == :park || (sending == :produce && ambiguous_resend?(error))
+            Pgbus.logger.warn { "[Pgbus::Web] Re-send of #{key} may have been sent (#{error.class}); its key stays held" }
+            return
+          end
+
+          UniquenessKey.release_if_unbound!(key, acquired_before: stamp)
+        rescue StandardError => e
+          Pgbus.logger.warn { "[Pgbus::Web] Giving back the uniqueness key #{key} failed: #{e.message}" }
+        end
+
+        # ActiveRecord wraps a PG error (StatementInvalid, ConnectionFailed),
+        # so the cause is asked too.
+        def ambiguous_resend?(error)
+          [error, error&.cause].compact.any? do |err|
+            (defined?(PGMQ::Errors::ConnectionError) && err.is_a?(PGMQ::Errors::ConnectionError)) ||
+              (defined?(PG::Error) && err.is_a?(PG::Error))
+          end
+        end
+
+        # The key a re-sent copy has to hold: only an enqueue-locked one. An
+        # :until_executing payload with executions > 0 is a retry_on
+        # re-enqueue, which went out with no row and whose copy releases none
+        # (Executor#holds_uniqueness_row?): a row taken for it would never go.
+        def resend_lock_key(payload)
+          return unless payload.is_a?(Hash)
+
+          key = Uniqueness.extract_key(payload)
+          strategy = Uniqueness.extract_strategy(payload)
+          return unless key && Uniqueness::ENQUEUE_LOCK_STRATEGIES.include?(strategy)
+          return if strategy == :until_executing && payload["executions"].to_i.positive?
+
+          key.to_s
+        end
+
+        # The copy is live: a failed bind is logged, not raised. The row stays
+        # unbound and stamped before the send, so the copy's own release
+        # still takes it.
+        def bind_resent_lock(key, lock_queue, msg_id, stamp)
+          UniquenessKey.bind!(key, queue_name: lock_queue, msg_id: msg_id.to_i, acquired_at: stamp)
+        rescue StandardError => e
+          Pgbus.logger.warn { "[Pgbus::Web] Uniqueness bind of re-sent #{key} failed: #{e.message}" }
+        end
+      end
+    end
+  end
+end