pgbus 0.21.4 → 0.23.0

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

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