pgbus 0.22.0 → 0.23.0

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

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Web
+    class DataSource
+      # The limits_concurrency half of a re-send (issue #636; Resend#resend_job
+      # is the whole). A re-sent copy signals its key's semaphore when it
+      # finishes, so it has to hold a slot first, taken the way
+      # Adapter#enqueue_with_concurrency takes one: the check and the park
+      # commit together under the semaphore row lock (rails/solid_queue#712),
+      # and the send follows the commit.
+      module ResendSlot
+        private
+
+        # Returns the block's msg_id once the copy is sent holding a slot,
+        # :parked when it waits behind a full limit (on_conflict: :block), and
+        # :refused when the limit is full under :discard or :raise. A payload
+        # with no concurrency key is sent as it is. +sending+ is :produce
+        # around the produce and :park around the park's commit, so the
+        # caller can tell an error that may hide a live copy from one that
+        # proves nothing went out.
+        def resend_holding_slot(payload, lock_queue, drop_source, sending, headers, &)
+          key = payload.is_a?(Hash) && Concurrency.extract_key(payload)
+          unless key
+            sending[0] = :produce
+            return yield
+          end
+
+          limits = resend_limits(payload)
+          case (taken = take_resend_slot(key, limits, lock_queue, park_payload(payload, headers), sending))
+          when :acquired then send_holding_resend_slot(key, sending, &)
+          when :full
+            Pgbus.logger.warn do
+              "[Pgbus::Web] Not re-sending #{payload["job_class"]}: concurrency limit for #{key} is full " \
+                "(on_conflict: :#{limits[:on_conflict]})"
+            end
+            :refused
+          else drop_parked_source(taken, key, drop_source)
+          end
+        end
+
+        # The limits live on the job class, not in the payload. A class that
+        # no longer declares them, or no longer resolves, is judged the way a
+        # promotion judges its parked job (Concurrency.config_for): against
+        # the limit the semaphore row records, parked when that is full.
+        def resend_limits(payload)
+          klass = Object.const_get(payload["job_class"].to_s)
+          config = klass.respond_to?(:pgbus_concurrency) && klass.pgbus_concurrency
+          config || { limit: nil, duration: Concurrency::DEFAULT_DURATION, on_conflict: :block }
+        rescue NameError
+          { limit: nil, duration: Concurrency::DEFAULT_DURATION, on_conflict: :block }
+        end
+
+        # :acquired, :full, or the id of the BlockedExecution the copy was
+        # parked as. The copy is sent right away, so its lease is the
+        # duration alone (Adapter#slot_lease with no delay). Parked on the
+        # logical queue at the job's own priority (the serialized "priority",
+        # else the default, as Adapter#handle_conflict parks it): promote_next
+        # sends it through Client#send_message, which prefixes the name and
+        # picks the _pN sub-queue by that priority. Once the park is inserted
+        # only its commit remains, and a COMMIT whose reply is lost may have
+        # landed: +sending+ says so until the transaction returns.
+        def take_resend_slot(key, limits, lock_queue, payload, sending)
+          taken = Pgbus::Semaphore.transaction(requires_new: true) do
+            lease = Concurrency.effective_duration(limits[:duration])
+            next :acquired if Concurrency::Semaphore.acquire(key, limits[:limit], lease) == :acquired
+            next :full unless limits[:on_conflict] == :block
+
+            Concurrency::BlockedExecution.insert(
+              concurrency_key: key, queue_name: lock_queue, payload: payload,
+              priority: payload["priority"] || Pgbus.configuration.default_priority, duration: limits[:duration]
+            ).rows.dig(0, 0).tap { sending[0] = :park }
+          end
+          sending[0] = nil
+          taken
+        end
+
+        # pgbus_blocked_executions has no headers column: the headers the
+        # copy would have been sent with (a DLQ retry's retries count) ride
+        # in the parked payload, and promote_next sends them as headers again
+        # (Concurrency::BlockedExecution::HEADERS_KEY).
+        def park_payload(payload, headers)
+          return payload if headers.nil? || headers.empty?
+
+          payload.merge(Concurrency::BlockedExecution::HEADERS_KEY => headers)
+        end
+
+        # Hand the slot back only when the failure proves nothing was
+        # produced (Adapter#send_holding_slot): on an ambiguous outcome the
+        # copy may be live, so the hold stands and the lease expiry plus the
+        # dispatcher's sweep reclaim it.
+        def send_holding_resend_slot(key, sending)
+          sending[0] = :produce
+          yield
+        rescue StandardError => e
+          if ambiguous_resend?(e)
+            Pgbus.logger.warn { "[Pgbus::Web] Re-send of #{key} may have been sent (#{e.class}); its concurrency slot stays held" }
+          else
+            begin
+              Concurrency::Semaphore.release(key)
+            rescue StandardError => release_error
+              Pgbus.logger.warn { "[Pgbus::Web] Giving back the concurrency slot of #{key} failed: #{release_error.message}" }
+            end
+          end
+          raise
+        end
+
+        # The park has committed; the source goes next (it lives on another
+        # connection, or after the commit, so the two cannot share a
+        # transaction). If that fails, the park is withdrawn while it still
+        # waits, and the error raised: nothing changed, the source stays. A
+        # removal whose outcome is unknown (a lost reply: its DELETE may have
+        # committed) keeps the park, since withdrawing it could leave neither
+        # copy; so does a park that cannot be withdrawn (already promoted: a
+        # live copy). Either way the source may stay, for the operator to
+        # discard: a duplicate is preferred over a lost job.
+        def drop_parked_source(park_id, key, drop_source)
+          drop_source.call
+          :parked
+        rescue StandardError => e
+          raise if !ambiguous_resend?(e) && withdraw_park(park_id)
+
+          Pgbus.logger.warn do
+            "[Pgbus::Web] Re-sent copy of #{key} is parked, but removing its source failed (#{e.class}: #{e.message}); " \
+              "the parked copy stands, and the source may stay to be discarded"
+          end
+          :parked
+        end
+
+        def withdraw_park(park_id)
+          Pgbus::BlockedExecution.where(id: park_id).delete_all.positive?
+        rescue StandardError => e
+          Pgbus.logger.warn { "[Pgbus::Web] Withdrawing the parked re-send #{park_id} failed: #{e.message}" }
+          false
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/web/data_source.rb

@@ -7,6 +7,8 @@ module Pgbus
     class DataSource
       include JobList
       include DeadLetter
+      include Resend
+      include ResendSlot
       include ListCounts
       include QueueSummary
       include EventList
@@ -175,9 +177,17 @@ module Pgbus
         @client.purge_queue(name, prefixed: false)
       end
 
+      # The messages' uniqueness locks are released only once the table is
+      # gone: their holders are read just before the drop (the client runs
+      # the block only when it drops the table, not for a mixed-case
+      # duplicate from before issue #633, whose table and messages stay with
+      # the lower-case queue) and released after it succeeds, so a failed
+      # drop leaves both messages and locks.
       def drop_queue(name)
-        release_uniqueness_keys_for_queue(name)
-        @client.drop_queue(name, prefixed: false)
+        holders = nil
+        result = @client.drop_queue(name, prefixed: false) { holders = queue_lock_holders(name) }
+        release_lock_holders(holders) if holders
+        result
       end
 
       def pause_queue(name, reason: nil)
@@ -299,20 +309,7 @@ module Pgbus
         # duplicate (the original is still in the queue waiting for retry).
         # Falls back to enqueueing a fresh copy only if the original is gone
         # (e.g., already moved to DLQ).
-        physical = failed_message_queue(event)
-        if physical
-          @client.set_visibility_timeout(physical, event["msg_id"].to_i, vt: 0, prefixed: false)
-        else
-          payload = JSON.parse(event["payload"])
-          headers = event["headers"]
-          headers = JSON.parse(headers) if headers.is_a?(String)
-          @client.send_message(event["queue_name"], payload, headers: headers)
-        end
-
-        connection.exec_delete(
-          "DELETE FROM pgbus_failed_events WHERE id = $1", "Pgbus Delete Failed Event", [id.to_i]
-        )
-        true
+        retry_failed_job(event)
       rescue StandardError => e
         Pgbus.logger.debug { "[Pgbus::Web] Error retrying failed event #{id}: #{e.message}" }
         false
@@ -336,27 +333,24 @@ module Pgbus
 
       # Failed jobs only, like discard_all_failed: an event's message is still
       # in its handler queue, so a re-sent copy would run the handler twice.
+      # Each job goes back the way Retry sends it (#retry_failed_job): a
+      # message still queued gets its vt reset, one that is gone is re-sent.
+      # A row it cannot retry (the re-send's key is held, its concurrency
+      # limit refuses it, or a call fails) stays, and the walk goes on past it
+      # by id.
       def retry_all_failed
         count = 0
+        last_id = 0
         loop do
           batch = connection.select_all(
-            "SELECT * FROM pgbus_failed_events WHERE #{NOT_HANDLER_QUEUE} ORDER BY id LIMIT 100", "Pgbus Retry Batch",
-            [handler_queue_names_literal]
+            "SELECT * FROM pgbus_failed_events WHERE #{NOT_HANDLER_QUEUE} AND id > $2 ORDER BY id LIMIT 100",
+            "Pgbus Retry Batch", [handler_queue_names_literal, last_id]
           ).to_a
           break if batch.empty?
 
           batch.each do |event|
-            payload = JSON.parse(event["payload"])
-            headers = event["headers"]
-            headers = JSON.parse(headers) if headers.is_a?(String)
-
-            connection.transaction do
-              @client.send_message(event["queue_name"], payload, headers: headers)
-              connection.exec_delete(
-                "DELETE FROM pgbus_failed_events WHERE id = $1", "Pgbus Delete Failed Event", [event["id"].to_i]
-              )
-            end
-            count += 1
+            last_id = event["id"].to_i
+            count += 1 if retry_failed_job(event)
           rescue StandardError => e
             Pgbus.logger.error { "[Pgbus::Web] Failed to retry event #{event["id"]}: #{e.message}" }
           end
@@ -634,9 +628,10 @@ module Pgbus
       # Drop every job parked behind a key. The jobs never run, so the
       # bookkeeping they would have resolved has to be resolved here: a parked
       # batch child is marked failed (otherwise its batch waits forever and
-      # on_failure never fires — issue #413) and an :until_executed uniqueness
-      # lock is released (otherwise it is orphaned, since no executor will ever
-      # release it — issue #423). Returns the number of jobs discarded.
+      # on_failure never fires — issue #413) and an :until_executed or
+      # :until_executing uniqueness lock is released (otherwise it is
+      # orphaned, since no executor will ever release it — issue #423).
+      # Returns the number of jobs discarded.
       def discard_parked_jobs(key)
         return 0 if key.to_s.strip.empty?
 
@@ -1162,11 +1157,17 @@ module Pgbus
       # one acquired after this row was parked.
       def release_parked_uniqueness_lock(payload, parked_at)
         key = payload[Uniqueness::METADATA_KEY]
-        return unless key && payload[Uniqueness::STRATEGY_KEY].to_s == "until_executed"
+        return unless key && enqueue_locked_strategy?(payload[Uniqueness::STRATEGY_KEY])
 
         UniquenessKey.release_if_unbound!(key, acquired_before: parked_at)
       end
 
+      # The strategies whose row is taken at enqueue and so is held by a parked
+      # job: :until_executed, and :until_executing (issue #628).
+      def enqueue_locked_strategy?(strategy)
+        Uniqueness::ENQUEUE_LOCK_STRATEGIES.any? { |s| s.to_s == strategy.to_s }
+      end
+
       # A row parked before the double-encoding fix stores a jsonb *string*
       # holding the document — the same two-pass unwrap BlockedExecution
       # .release_next! does.
@@ -1613,10 +1614,19 @@ module Pgbus
       # Release the locks a collection of formatted messages hold, in a single
       # query.
       def release_locks_for_messages(messages)
-        holders = messages.filter_map do |m|
+        release_lock_holders(lock_holders_for(messages))
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error releasing locks for messages: #{e.message}" }
+      end
+
+      def lock_holders_for(messages)
+        messages.filter_map do |m|
           key = extract_uniqueness_key_from_payload_str(m[:message])
           [key, *lock_holder(m[:queue_name], m[:msg_id], m[:headers], m[:enqueued_at])] if key
         end
+      end
+
+      def release_lock_holders(holders)
         UniquenessKey.release_all_held_by!(holders) if holders.any?
       rescue StandardError => e
         Pgbus.logger.debug { "[Pgbus::Web] Error releasing locks for messages: #{e.message}" }
@@ -1802,10 +1812,18 @@ module Pgbus
       # Release all uniqueness keys associated with a queue before purge/drop.
       # Scans queue messages for uniqueness metadata and deletes matching rows.
       def release_uniqueness_keys_for_queue(queue_name)
-        messages = query_queue_messages_raw(queue_name, 10_000, 0)
-        release_locks_for_messages(messages)
+        holders = queue_lock_holders(queue_name)
+        release_lock_holders(holders) if holders
+      end
+
+      # The uniqueness-lock holders of a queue's messages, or nil when they
+      # cannot be read (the purge or drop goes ahead; the reaper frees what
+      # is left).
+      def queue_lock_holders(queue_name)
+        lock_holders_for(query_queue_messages_raw(queue_name, 10_000, 0))
       rescue StandardError => e
-        Pgbus.logger.debug { "[Pgbus::Web] Error releasing uniqueness keys for queue #{queue_name}: #{e.message}" }
+        Pgbus.logger.debug { "[Pgbus::Web] Error reading uniqueness keys for queue #{queue_name}: #{e.message}" }
+        nil
       end
     end
   end

data/lib/pgbus/web/dead_letter_reason.rb

@@ -45,6 +45,12 @@ module Pgbus
 
       def reason_for(block, attempts, max)
         error_class = block["error_class"]
+        # A :while_executing copy skipped on every read (issue #629): no
+        # attempt ran, so "crashed before it could report" would mislead.
+        if block["reason"] == DeadLetterHeader::REASON_UNIQUENESS_CONFLICT && !error_class
+          return ["uniqueness_conflict", { attempts: attempts, max: max }]
+        end
+
         unless error_class
           key = block["source"] == "consumer" ? "event_no_error" : "no_error_recorded"
           return [key, { attempts: attempts, max: max }]

data/lib/pgbus/web/streamer/connection.rb

@@ -62,21 +62,24 @@ module Pgbus
         # existing caller is unchanged. The Dispatcher overrides it with the
         # short streams_fanout_write_deadline_ms for hot-loop fanout writes,
         # bounding head-of-line blocking on a slow client (issue #315 item 3).
-        def enqueue(envelopes, deadline_ms: @write_deadline_ms)
+        #
+        # frames: msg_id → the frozen SSE frame, built once per wake by the
+        # Dispatcher for every connection on the stream (issue #621). An
+        # envelope the Hash does not hold (or no Hash: the connect replay, an
+        # in-flight buffer flush) is framed here, so the bytes are the same
+        # either way.
+        def enqueue(envelopes, deadline_ms: @write_deadline_ms, frames: nil)
           written = []
           envelopes.each do |envelope|
-            ephemeral = envelope.msg_id.negative?
-            next if !ephemeral && envelope.msg_id <= @last_msg_id_sent.get
+            msg_id = envelope.msg_id
+            ephemeral = msg_id.negative?
+            next if !ephemeral && msg_id <= @last_msg_id_sent.get
 
-            bytes = Pgbus::Streams::Envelope.message(
-              id: envelope.msg_id,
-              event: sse_event_for(envelope),
-              data: envelope.payload
-            )
+            bytes = frames&.[](msg_id) || frame_for(envelope)
 
             result = @writer.write(self, bytes, deadline_ms: deadline_ms)
             if result == :ok
-              @last_msg_id_sent.set(envelope.msg_id) unless ephemeral
+              @last_msg_id_sent.set(msg_id) unless ephemeral
               @last_write_at = monotonic
               written << envelope
             else
@@ -88,11 +91,26 @@ module Pgbus
         end
 
         def write_comment(text)
-          write_frame(Pgbus::Streams::Envelope.comment(text))
+          write_raw(Pgbus::Streams::Envelope.comment(text))
+        end
+
+        # The one raw writer: bytes that are already a whole SSE frame (the
+        # heartbeat's shared comment, the shutdown sentinel). A successful
+        # write counts as activity for the idle reaper; a failed one marks the
+        # connection dead. The Heartbeat passes the short fan-out deadline
+        # (issue #621); everything else keeps the connection's own.
+        def write_raw(bytes, deadline_ms: @write_deadline_ms)
+          result = @writer.write(self, bytes, deadline_ms: deadline_ms)
+          if result == :ok
+            @last_write_at = monotonic
+          else
+            mark_dead!
+          end
+          result
         end
 
         def write_sentinel(bytes)
-          @writer.write(self, bytes, deadline_ms: @write_deadline_ms)
+          write_raw(bytes)
         end
 
         # The pgbus:connected frame carrying this connection's id. Written by
@@ -100,7 +118,7 @@ module Pgbus
         # seat joined (issue #521), so a client that acts on the id right
         # after the event finds its row.
         def write_connected
-          write_frame(Pgbus::Streams::Envelope.connected(id: @id))
+          write_raw(Pgbus::Streams::Envelope.connected(id: @id))
         end
 
         def idle_for
@@ -143,23 +161,12 @@ module Pgbus
 
         private
 
-        def write_frame(bytes)
-          result = @writer.write(self, bytes, deadline_ms: @write_deadline_ms)
-          if result == :ok
-            @last_write_at = monotonic
-          else
-            mark_dead!
-          end
-          result
-        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)
-        def 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
+        def frame_for(envelope)
+          Pgbus::Streams::Envelope.message(
+            id: envelope.msg_id,
+            event: Pgbus::Streams::Envelope.sse_event_for(envelope),
+            data: envelope.payload
+          )
         end
 
         def monotonic

data/lib/pgbus/web/streamer/falcon_connection.rb

@@ -49,20 +49,20 @@ module Pgbus
         # (so the Dispatcher's safe_enqueue can call either class) but ignored:
         # write_to_body is non-blocking under Falcon's fiber reactor, so there
         # is no head-of-line blocking to bound here (issue #315 item 3).
-        def enqueue(envelopes, deadline_ms: @write_deadline_ms) # rubocop:disable Lint/UnusedMethodArgument
+        # frames: as Connection#enqueue (issue #621). Ephemeral envelopes
+        # (negative msg_id) bypass the cursor and never advance it, as there.
+        def enqueue(envelopes, deadline_ms: @write_deadline_ms, frames: nil) # rubocop:disable Lint/UnusedMethodArgument
           written = []
           envelopes.each do |envelope|
-            next if envelope.msg_id <= @last_msg_id_sent.get
+            msg_id = envelope.msg_id
+            ephemeral = msg_id.negative?
+            next if !ephemeral && msg_id <= @last_msg_id_sent.get
 
-            bytes = Pgbus::Streams::Envelope.message(
-              id: envelope.msg_id,
-              event: sse_event_for(envelope),
-              data: envelope.payload
-            )
+            bytes = frames&.[](msg_id) || frame_for(envelope)
 
             result = write_to_body(bytes)
             if result == :ok
-              @last_msg_id_sent.set(envelope.msg_id)
+              @last_msg_id_sent.set(msg_id) unless ephemeral
               @last_write_at = monotonic
               written << envelope
             else
@@ -74,16 +74,28 @@ module Pgbus
         end
 
         def write_comment(text)
-          write_frame(Pgbus::Streams::Envelope.comment(text))
+          write_raw(Pgbus::Streams::Envelope.comment(text))
         end
 
         # See Connection#write_connected (issue #521).
         def write_connected
-          write_frame(Pgbus::Streams::Envelope.connected(id: @id))
+          write_raw(Pgbus::Streams::Envelope.connected(id: @id))
+        end
+
+        # See Connection#write_raw (issue #621). deadline_ms is ignored, as in
+        # #enqueue: the body write does not block.
+        def write_raw(bytes, deadline_ms: @write_deadline_ms) # rubocop:disable Lint/UnusedMethodArgument
+          result = write_to_body(bytes)
+          if result == :ok
+            @last_write_at = monotonic
+          else
+            mark_dead!
+          end
+          result
         end
 
         def write_sentinel(bytes)
-          write_to_body(bytes)
+          write_raw(bytes)
         end
 
         def close
@@ -112,20 +124,12 @@ module Pgbus
 
         private
 
-        # See Connection#sse_event_for. (issue #170)
-        def 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 write_frame(bytes)
-          result = write_to_body(bytes)
-          if result == :ok
-            @last_write_at = monotonic
-          else
-            mark_dead!
-          end
-          result
+        def frame_for(envelope)
+          Pgbus::Streams::Envelope.message(
+            id: envelope.msg_id,
+            event: Pgbus::Streams::Envelope.sse_event_for(envelope),
+            data: envelope.payload
+          )
         end
 
         def write_to_body(bytes)

data/lib/pgbus/web/streamer/heartbeat.rb

@@ -10,7 +10,15 @@ module Pgbus
       #      connection. This keeps proxies and load balancers from timing
       #      out idle HTTP responses; most reverse proxies close HTTP
       #      responses that sit idle for 30-60s, which would silently drop
-      #      SSE clients.
+      #      SSE clients. The frame is built once per tick and shared by
+      #      every connection, and each write runs under the short fan-out
+      #      deadline (streams_fanout_write_deadline_ms, issue #621): the
+      #      writes are serial on this one thread, and each socket write is
+      #      bounded by 250 ms once it holds the connection's mutex, not by
+      #      streams_write_deadline_ms (a concurrent fan-out or replay write
+      #      on the same connection can still delay its turn). A client that
+      #      cannot take the heartbeat comment in that window is marked dead
+      #      and reconnects (durable streams replay from Last-Event-ID).
       #
       #   2. Mark connections that have been idle longer than the
       #      configured idle_timeout as dead. The StreamEventDispatcher's next pass
@@ -30,8 +38,10 @@ module Pgbus
         # presence touch every tick, even with no presence connection here,
         # so the dispatcher can expire seats left by other processes.
         def initialize(registry:, dispatch_queue:, interval:, idle_timeout:, logger: Pgbus.logger, clock: nil,
-                       presence_expiry: false)
+                       presence_expiry: false,
+                       fanout_write_deadline_ms: Pgbus.configuration.streams_fanout_write_deadline_ms)
           @registry = registry
+          @fanout_write_deadline_ms = fanout_write_deadline_ms
           @queue = dispatch_queue
           @interval = interval
           @idle_timeout = idle_timeout
@@ -76,6 +86,7 @@ module Pgbus
         # code goes through the background thread.
         def tick
           now = @clock.call
+          frame = Pgbus::Streams::Envelope.comment("heartbeat #{now.to_i}").freeze
           presence_conns = []
           @registry.each_connection do |connection|
             if connection.dead?
@@ -91,7 +102,7 @@ module Pgbus
               next
             end
 
-            result = connection.write_comment("heartbeat #{now.to_i}")
+            result = connection.write_raw(frame, deadline_ms: @fanout_write_deadline_ms)
             if connection.dead? || result != :ok
               enqueue_disconnect(connection)
               next

data/lib/pgbus/web/streamer/instance.rb

@@ -76,7 +76,8 @@ module Pgbus
             interval: @config.streams_heartbeat_interval,
             idle_timeout: @config.streams_idle_timeout,
             logger: @logger,
-            presence_expiry: Array(@config.streams_presence_patterns).any?
+            presence_expiry: Array(@config.streams_presence_patterns).any?,
+            fanout_write_deadline_ms: @config.streams_fanout_write_deadline_ms
           )
           @peer_close_watcher = build_peer_close_watcher
           @started = false
@@ -243,8 +244,10 @@ module Pgbus
           @logger.warn { "[Pgbus::Streamer::Instance] component stop raised: #{e.class}: #{e.message}" }
         end
 
-        # Captured BEFORE the stops: every component nils its thread
-        # reference in #stop whether or not the join succeeded.
+        # Captured BEFORE the stops: the other components nil their thread
+        # reference in #stop whether or not the join succeeded (the Listener
+        # keeps a thread that outlived its budget, so it cannot be restarted
+        # beside it).
         def component_threads
           {
             "heartbeat" => @heartbeat.threads,
@@ -340,8 +343,8 @@ module Pgbus
           when Proc
             # The Proc branch in connection_options typically returns
             # ActiveRecord::Base.connection.raw_connection — a pooled
-            # AR connection. That's fatal for the streamer: LISTEN and
-            # wait_for_notify bind the session to the connection object,
+            # AR connection. That's fatal for the streamer: LISTEN and the
+            # listener's wait on its socket bind the session to the connection object,
             # so if AR's pool hands the same raw_connection to another
             # thread mid-wait, we get concurrent libpq calls → segfault
             # or result corruption. Bail out with a clear error instead