pgbus 0.9.9 → 0.9.11

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

@@ -13,17 +13,29 @@ module Pgbus
       # cursor only for envelopes that actually wrote successfully. This is
       # the client-side leg of the replay-race fix (§6.5 of the design doc).
       class Connection
-        attr_reader :id, :stream_name, :io, :mutex, :last_msg_id_sent, :context
+        attr_reader :id, :stream_name, :io, :mutex, :context
         # The presence member id this connection auto-joined as, or nil for
         # non-presence streams / anonymous connections. Set by the
         # Dispatcher on connect; read on disconnect and heartbeat touch.
         attr_accessor :presence_member
 
+        # last_msg_id_sent is the ONE field whose writer can cross threads: with
+        # streams_writer_threads > 0 (issue #321) the OutboundPump worker thread
+        # advances it inside #enqueue, while the dispatcher thread reads it via
+        # cursor_for / handle_connect. A Concurrent::AtomicReference gives a real
+        # happens-before on every Ruby engine (not just MRI's GVL) at ~ns cost —
+        # one worker only ever writes a given connection's field (stable
+        # partition), so there's no writer-writer contention. Inline mode
+        # (default) reads/writes it single-threaded, semantically identical.
+        def last_msg_id_sent
+          @last_msg_id_sent.get
+        end
+
         def initialize(id:, stream_name:, io:, since_id:, writer:, write_deadline_ms:, context: nil)
           @id = id
           @stream_name = stream_name
           @io = io
-          @last_msg_id_sent = since_id.to_i
+          @last_msg_id_sent = Concurrent::AtomicReference.new(since_id.to_i)
           @writer = writer
           @write_deadline_ms = write_deadline_ms
           @mutex = Mutex.new
@@ -40,11 +52,15 @@ module Pgbus
           @context = context
         end
 
-        def enqueue(envelopes)
+        # deadline_ms defaults to the connection's own write deadline so every
+        # 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)
           written = []
           envelopes.each do |envelope|
             ephemeral = envelope.msg_id.negative?
-            next if !ephemeral && envelope.msg_id <= @last_msg_id_sent
+            next if !ephemeral && envelope.msg_id <= @last_msg_id_sent.get
 
             bytes = Pgbus::Streams::Envelope.message(
               id: envelope.msg_id,
@@ -52,9 +68,9 @@ module Pgbus
               data: envelope.payload
             )
 
-            result = @writer.write(self, bytes, deadline_ms: @write_deadline_ms)
+            result = @writer.write(self, bytes, deadline_ms: deadline_ms)
             if result == :ok
-              @last_msg_id_sent = envelope.msg_id unless ephemeral
+              @last_msg_id_sent.set(envelope.msg_id) unless ephemeral
               @last_write_at = monotonic
               written << envelope
             else

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

@@ -12,15 +12,23 @@ module Pgbus
       # directly to body.write which is backed by Thread::Queue and
       # is fiber-safe under Falcon's scheduler.
       class FalconConnection
-        attr_reader :id, :stream_name, :io, :mutex, :last_msg_id_sent, :context
+        attr_reader :id, :stream_name, :io, :mutex, :context
         attr_accessor :presence_member
 
+        # last_msg_id_sent mirrors Connection's cross-thread cursor (issue #321):
+        # a Concurrent::AtomicReference so the OutboundPump worker's advance and
+        # the dispatcher's read have a happens-before on every Ruby engine. See
+        # the note on Connection#last_msg_id_sent.
+        def last_msg_id_sent
+          @last_msg_id_sent.get
+        end
+
         def initialize(id:, stream_name:, body:, since_id:, write_deadline_ms:, context: nil)
           @id = id
           @stream_name = stream_name
           @body = body
           @io = body
-          @last_msg_id_sent = since_id.to_i
+          @last_msg_id_sent = Concurrent::AtomicReference.new(since_id.to_i)
           @write_deadline_ms = write_deadline_ms
           @mutex = Mutex.new
           @dead = false
@@ -31,10 +39,14 @@ module Pgbus
           @context = context
         end
 
-        def enqueue(envelopes)
+        # deadline_ms is accepted for duck-type parity with Connection#enqueue
+        # (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
           written = []
           envelopes.each do |envelope|
-            next if envelope.msg_id <= @last_msg_id_sent
+            next if envelope.msg_id <= @last_msg_id_sent.get
 
             bytes = Pgbus::Streams::Envelope.message(
               id: envelope.msg_id,
@@ -44,7 +56,7 @@ module Pgbus
 
             result = write_to_body(bytes)
             if result == :ok
-              @last_msg_id_sent = envelope.msg_id
+              @last_msg_id_sent.set(envelope.msg_id)
               @last_write_at = monotonic
               written << envelope
             else

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

@@ -20,7 +20,8 @@ module Pgbus
       # production the module-level Streamer.current(...) builds all of the
       # defaults from the configuration.
       class Instance
-        attr_reader :registry, :listener, :dispatcher, :heartbeat, :dispatch_queue, :stream_counter
+        attr_reader :registry, :listener, :dispatcher, :heartbeat, :dispatch_queue, :stream_counter, :pump,
+                    :autoscaler
 
         def initialize(
           client: Pgbus.client,
@@ -39,10 +40,26 @@ module Pgbus
 
           @stream_counter = StreamCounter.new
           @pg_connection = pg_connection || build_pg_connection
+          # Self-tuning streams-pool autoscaler (issue #323). Opt-in; nil unless
+          # enabled AND on the dedicated connection path (the shared-AR streams
+          # pool aliases the non-thread-safe job pool and resize is a no-op there).
+          # It's a pure decision object — no thread, no connection. It runs as a
+          # throttled maintenance task on the Listener's idle LISTEN connection
+          # (zero extra connections), querying live headroom there.
+          @autoscaler =
+            if @config.streams_pool_autoscale && !@client.shared_connection?
+              Pgbus::Streams::PoolAutoscaler.new(client: @client, config: @config, logger: @logger)
+            end
           @listener = Listener.new(
             pg_connection: @pg_connection,
             dispatch_queue: @dispatch_queue,
             health_check_ms: @config.streams_listen_health_check_ms,
+            # Opt-in dispatch-queue backpressure (issue #315 item 3). 0 =
+            # unbounded (default). The queue itself stays an unbounded
+            # Queue.new so the request-thread Connect push and the dispatcher's
+            # own prune_dead self-post never block.
+            dispatch_queue_limit: @config.streams_dispatch_queue_limit,
+            maintenance: build_autoscale_maintenance,
             logger: @logger,
             # On reconnect the Listener rebuilds its OWN connection via this
             # factory (fresh connect re-resolves DNS, converges on the promoted
@@ -52,6 +69,14 @@ module Pgbus
             # can inject its own factory to avoid touching real configuration.
             connection_factory: connection_factory || -> { build_raw_pg_connection }
           )
+          # Off-thread durable fanout writer (issue #321). Built only when
+          # streams_writer_threads > 0; nil means fanout writes stay inline on
+          # the dispatcher thread (the default, pre-#321 behavior). The pump
+          # reports write acks on @ack_queue (drained by the dispatcher) and
+          # posts a DisconnectMessage via on_dead when a write fails, so the
+          # dispatcher owns all cursor + registry cleanup on its own thread.
+          @ack_queue = Queue.new
+          @pump = build_pump
           @dispatcher = StreamEventDispatcher.new(
             client: @client,
             registry: @registry,
@@ -59,7 +84,9 @@ module Pgbus
             dispatch_queue: @dispatch_queue,
             logger: @logger,
             config: @config,
-            stream_counter: @stream_counter
+            stream_counter: @stream_counter,
+            pump: @pump,
+            ack_queue: @ack_queue
           )
           @heartbeat = Heartbeat.new(
             registry: @registry,
@@ -76,6 +103,9 @@ module Pgbus
           return if @started
 
           @started = true
+          # Pump first: it must be ready to accept writes before the dispatcher
+          # can post any (issue #321). No-op when offload is off (@pump nil).
+          @pump&.start
           @listener.start
           @dispatcher.start
           @heartbeat.start
@@ -112,9 +142,15 @@ module Pgbus
         #   2. Listener next (stop accepting new NOTIFYs)
         #   3. Dispatcher next (drain the queue; it's now finite because
         #      nothing else writes into it)
-        #   4. Send pgbus:shutdown sentinel to every connection and close
-        #      their sockets. We do this AFTER stopping the dispatcher so
-        #      no one else is writing to these IOs concurrently.
+        #   4. Writer pump next (issue #321): once the dispatcher — the pump's
+        #      only producer — is stopped, each partition is finite, so the
+        #      pump drains every accepted-but-unflushed durable frame and joins
+        #      its workers before we touch the sockets. No-op when offload is
+        #      off. Must come BEFORE close_all_connections so buffered frames
+        #      flush before their sockets close.
+        #   5. Send pgbus:shutdown sentinel to every connection and close
+        #      their sockets. We do this AFTER stopping the dispatcher AND the
+        #      pump so nothing else is writing to these IOs concurrently.
         #
         # Bounded by the configured write deadline per connection; a dead
         # client drops instantly, a slow one stalls for at most write_deadline_ms.
@@ -126,6 +162,7 @@ module Pgbus
             safely { @heartbeat.stop }
             safely { @listener.stop }
             safely { @dispatcher.stop }
+            safely { @pump&.stop }
             close_all_connections
           end
         end
@@ -138,6 +175,39 @@ module Pgbus
           @logger.warn { "[Pgbus::Streamer::Instance] component stop raised: #{e.class}: #{e.message}" }
         end
 
+        # Off-thread durable fanout writer (issue #321). nil (the default) keeps
+        # fanout writes inline on the dispatcher thread. When on_dead fires
+        # (a write failed), the pump posts a DisconnectMessage onto the shared
+        # dispatch queue — the SAME explicit protocol prune_dead and the
+        # heartbeat use — so the dispatcher thread owns the lockless cursor +
+        # registry cleanup and the pump never touches dispatcher state.
+        # Wrap the autoscaler as a throttled Listener maintenance task (issue
+        # #323), so headroom is read on the Listener's existing idle LISTEN
+        # connection every streams_pool_autoscale_interval seconds. nil (no
+        # autoscaler) means the Listener runs no maintenance.
+        def build_autoscale_maintenance
+          return nil unless @autoscaler
+
+          Pgbus::Streams::PoolAutoscaler::Maintenance.new(
+            autoscaler: @autoscaler,
+            interval: @config.streams_pool_autoscale_interval,
+            application_name_prefix: @config.streams_application_name
+          )
+        end
+
+        def build_pump
+          threads = @config.streams_writer_threads
+          return nil unless threads.positive?
+
+          OutboundPump.new(
+            threads: threads,
+            ack_queue: @ack_queue,
+            on_dead: ->(conn) { @dispatch_queue << StreamEventDispatcher::DisconnectMessage.new(connection: conn) },
+            buffer_limit: @config.streams_writer_buffer_limit,
+            logger: @logger
+          )
+        end
+
         def close_all_connections
           sentinel_bytes = Pgbus::Streams::Envelope.message(
             id: 0,

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

@@ -11,11 +11,17 @@ module Pgbus
       # pattern.
       #
       # The write loop uses write_nonblock + IO.select so a slow client at most
-      # stalls *its own* mutex-protected write for `deadline_ms`, never the
-      # dispatcher or heartbeat thread. When the deadline expires with bytes
-      # still pending, we return :blocked; the caller (Connection#enqueue or
-      # Connection#write_comment) translates that into mark_dead!, and the
-      # heartbeat sweep eventually unregisters the connection.
+      # stalls the CALLING thread's mutex-protected write for `deadline_ms`.
+      # During fanout the dispatcher IS that caller, writing to each connection
+      # serially, so K slow-but-not-yet-dead clients stack the deadline
+      # (~K * deadline_ms) before each is marked dead — the head-of-line block.
+      # Fanout writes therefore pass the SHORT streams_fanout_write_deadline_ms
+      # (not streams_write_deadline_ms) to bound that stall (issue #315 item 3).
+      # When the deadline expires with bytes still pending, we return :blocked;
+      # the caller (Connection#enqueue or Connection#write_comment) translates
+      # that into mark_dead!, and the heartbeat sweep unregisters the
+      # connection — the client then reconnects and replays the gap from the
+      # durable archive.
       #
       # Returns:
       #   :ok       — all bytes written

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

@@ -48,8 +48,20 @@ module Pgbus
         #   Required — the reconnect loop always rebuilds rather than resetting a
         #   possibly-dead socket, so every caller (production and tests) must pass
         #   one.
+        # dispatch_queue_limit (issue #315 item 3): 0 = unbounded (default). A
+        # positive value makes handle_notify DROP a durable wake when the
+        # dispatch queue is at/over the cap — safe because the next durable
+        # wake for that stream re-reads from the min cursor. Ephemeral wakes
+        # and Connect/Disconnect messages are never dropped.
+        # `maintenance:` is an optional periodic callback (issue #323 pool
+        # autoscaler). On the listener's idle health-check window — the only place
+        # the non-thread-safe LISTEN connection is safely idle — it is invoked at
+        # most once per `maintenance.interval` seconds with THIS connection, so a
+        # maintenance query (e.g. pg_stat_activity headroom) reuses the existing
+        # idle connection instead of opening its own. nil disables it.
         def initialize(pg_connection:, dispatch_queue:, health_check_ms:,
-                       connection_factory:, logger: Pgbus.logger)
+                       connection_factory:, dispatch_queue_limit: 0, maintenance: nil,
+                       logger: Pgbus.logger, clock: nil)
           raise ArgumentError, "connection_factory is required" unless connection_factory.respond_to?(:call)
 
           @conn = pg_connection
@@ -57,12 +69,22 @@ module Pgbus
           @health_check_ms = health_check_ms
           @logger = logger
           @connection_factory = connection_factory
+          @dispatch_queue_limit = dispatch_queue_limit
+          @maintenance = maintenance
+          @clock = clock || -> { ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) }
+          @maintenance_last = nil
+          @dropped_wakes = 0
           @listening_to = Set.new
           @commands = Queue.new
           @running = false
           @thread = nil
         end
 
+        # Count of durable wakes dropped due to the dispatch-queue cap. Read by
+        # tests and available for operator introspection. Only mutated on the
+        # Listener thread (in handle_notify), so no synchronization needed.
+        attr_reader :dropped_wakes
+
         def start
           return if @running
 
@@ -202,11 +224,49 @@ module Pgbus
           queue_name = queue_name_from(channel)
           return unless queue_name
 
+          # Backpressure applies ONLY to durable wakes (payload nil): they
+          # self-heal because the next durable wake for the stream re-reads
+          # from the min cursor. Ephemeral wakes (payload present) carry the
+          # only copy of their HTML with no archive to replay, so they are
+          # never dropped (issue #315 item 3). @dispatch_queue.size on a stdlib
+          # Queue is internally synchronized; this runs only on the Listener
+          # thread and touches no dispatcher-owned state.
+          if payload.nil? && @dispatch_queue_limit.positive? &&
+             @dispatch_queue.size >= @dispatch_queue_limit
+            @dropped_wakes += 1
+            if (@dropped_wakes % 100) == 1
+              @logger.warn do
+                "[Pgbus::Streamer::Listener] dispatch queue at limit " \
+                  "(#{@dispatch_queue_limit}); dropped durable wake for " \
+                  "#{queue_name} (total dropped: #{@dropped_wakes})"
+              end
+            end
+            return
+          end
+
           @dispatch_queue << WakeMessage.new(queue_name: queue_name, payload: payload)
         end
 
         def run_health_check
           @conn.exec("SELECT 1")
+          run_maintenance
+        end
+
+        # Periodic maintenance on the idle LISTEN connection, throttled to
+        # @maintenance.interval (issue #323). Runs on the listener thread, so it
+        # is the only place the non-thread-safe @conn may be queried outside
+        # wait_for_notify. Fail-soft: a raising maintenance callback is logged and
+        # never disturbs the listen loop.
+        def run_maintenance
+          return unless @maintenance
+
+          now = @clock.call
+          return if @maintenance_last && (now - @maintenance_last) < @maintenance.interval
+
+          @maintenance_last = now
+          @maintenance.run(@conn)
+        rescue StandardError => e
+          @logger.debug { "[Pgbus::Streamer::Listener] maintenance raised: #{e.class}: #{e.message}" }
         end
 
         # Retry reconnect until we succeed (fresh conn + every channel

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

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Web
+    module Streamer
+      # Off-thread durable-stream fanout writer (issue #321).
+      #
+      # The dispatcher must never block on a slow client's socket write. When
+      # streams_writer_threads > 0, StreamEventDispatcher#handle_durable_wake
+      # hands each (connection, filtered envelopes, batch_max) to this pump
+      # instead of writing inline. The pump owns N worker threads; each
+      # connection is pinned to ONE worker by `id.hash % N`, so a connection's
+      # frames stay strictly ordered and its per-io mutex is never contended
+      # across workers.
+      #
+      # The pump calls the UNCHANGED Connection#enqueue on a worker thread (the
+      # blocking write, last_msg_id_sent advance, and mark_dead! all move off
+      # the dispatcher), then reports back:
+      #   - success  → a WriteAckMessage(connection, accepted_max) onto ack_queue.
+      #                accepted_max is the highest msg_id actually written (or
+      #                the batch_max for a fully-filtered empty batch, so the
+      #                dispatcher's scan cursor still advances past the hidden
+      #                window). The dispatcher — the SOLE owner of @scanned_cursor
+      #                — applies it on its own thread. This keeps the lockless
+      #                single-owner invariant intact: the writer only reports a
+      #                value, it never mutates dispatcher state.
+      #   - failure  → the injected on_dead callback (which posts a
+      #                DisconnectMessage), NOT an ack. A failed write must never
+      #                advance the cursor past a frame that never reached the
+      #                socket (issue #321 B2). The dispatcher then scrubs the
+      #                connection's state deterministically (B4), even on an
+      #                otherwise-quiet stream.
+      #
+      # EPHEMERAL frames are NEVER routed here — they have no archive to replay,
+      # so an async drop would be unrecoverable (issue #321 B1). #post raises
+      # ArgumentError on a negative msg_id as a defense-in-depth guard against a
+      # future refactor accidentally offloading one.
+      class OutboundPump
+        WriteJob = Data.define(:connection, :envelopes, :batch_max, :deadline_ms)
+        private_constant :WriteJob
+
+        DRAIN = :__drain__
+
+        def initialize(threads:, ack_queue:, on_dead:, buffer_limit: 0, logger: Pgbus.logger)
+          raise ArgumentError, "threads must be positive" unless threads.positive?
+
+          @ack_queue = ack_queue
+          @on_dead = on_dead
+          @buffer_limit = buffer_limit
+          @logger = logger
+          # One partition per worker. Each is a Partition wrapping a bounded
+          # per-connection buffer so the drop-oldest policy is per connection,
+          # not per partition (a fast connection can't be starved by a slow one
+          # sharing its worker beyond ordering).
+          @partitions = Array.new(threads) { Partition.new(buffer_limit, @logger) }
+          @threads = []
+          @started = false
+        end
+
+        def start
+          return self if @started
+
+          @started = true
+          @partitions.each do |partition|
+            @threads << Thread.new { run_worker(partition) }
+          end
+          self
+        end
+
+        # True while any writer thread is still alive. Lets callers assert the
+        # pump's OWN threads stopped after #stop without inspecting the global
+        # Thread.list (which is noisy and can't distinguish a pump leak from
+        # unrelated thread churn).
+        def alive?
+          @threads.any?(&:alive?)
+        end
+
+        # Snapshot of the pump's live writer threads — for test introspection.
+        def worker_threads
+          @threads.dup
+        end
+
+        # Hand a durable fanout write to the pump. Returns immediately — the
+        # dispatcher does not block. Raises on a negative (ephemeral) msg_id.
+        def post(connection, envelopes, batch_max, deadline_ms:)
+          if envelopes.any? { |e| e.msg_id.negative? }
+            raise ArgumentError,
+                  "OutboundPump received an ephemeral (negative msg_id) envelope; " \
+                  "ephemeral fanout must stay inline on the dispatcher thread (issue #321 B1)"
+          end
+
+          partition_for(connection).push(
+            WriteJob.new(connection: connection, envelopes: envelopes,
+                         batch_max: batch_max, deadline_ms: deadline_ms)
+          )
+        end
+
+        # Graceful drain: signal every partition to flush what it holds, then
+        # join each worker bounded by the write deadline. Never Thread#kill — a
+        # kill mid write_nonblock corrupts IO state (mirrors
+        # StreamEventDispatcher#stop). Idempotent.
+        def stop
+          return self unless @started
+
+          @started = false
+          @partitions.each { |p| p.push(DRAIN) }
+          @threads.each do |t|
+            next if t.join(join_timeout_seconds)
+
+            @logger.warn { "[Pgbus::Streamer::OutboundPump] writer thread did not drain within #{join_timeout_seconds}s" }
+          end
+          @threads.clear
+          self
+        end
+
+        private
+
+        def partition_for(connection)
+          @partitions[connection.id.hash % @partitions.size]
+        end
+
+        def join_timeout_seconds
+          5
+        end
+
+        def run_worker(partition)
+          loop do
+            job = partition.pop
+            break if job == DRAIN
+
+            process(job)
+          end
+        rescue StandardError => e
+          @logger.error { "[Pgbus::Streamer::OutboundPump] worker crashed: #{e.class}: #{e.message}" }
+          raise
+        end
+
+        def process(job)
+          conn = job.connection
+          return if conn.dead?
+
+          written = conn.enqueue(job.envelopes, deadline_ms: job.deadline_ms)
+
+          if conn.dead?
+            @on_dead.call(conn)
+          else
+            @ack_queue << StreamEventDispatcher::WriteAckMessage.new(
+              connection: conn,
+              accepted_max: accepted_max_for(job, written)
+            )
+          end
+        rescue StandardError => e
+          @logger.error { "[Pgbus::Streamer::OutboundPump] write failed for #{job.connection.id}: #{e.class}: #{e.message}" }
+          safe_mark_dead(job.connection)
+        end
+
+        # The scan cursor may advance to:
+        #   - the highest msg_id actually written, or
+        #   - the batch_max when the filtered batch was empty (advance past the
+        #     audience-hidden window so read_after moves forward), or
+        #   - the connection's current cursor when every frame was a dedup
+        #     no-op (a max-guarded no-op on the dispatcher side).
+        def accepted_max_for(job, written)
+          return job.batch_max if job.envelopes.empty?
+
+          written.map(&:msg_id).max || job.connection.last_msg_id_sent
+        end
+
+        def safe_mark_dead(connection)
+          connection.mark_dead!
+          @on_dead.call(connection)
+        rescue StandardError => e
+          @logger.debug { "[Pgbus::Streamer::OutboundPump] on_dead failed: #{e.class}: #{e.message}" }
+        end
+
+        # A worker's inbox: a control channel (for the DRAIN sentinel, always
+        # delivered) plus a bounded per-connection buffer. When buffer_limit is
+        # positive and a connection's pending frames exceed it, the OLDEST
+        # durable frame for that connection is dropped — safe because durable
+        # frames are archive-recoverable on reconnect (issue #321). A drop is
+        # logged (throttled) so it isn't silent.
+        class Partition
+          # Total durable frames this partition has dropped under buffer_limit.
+          # Monotonic; read by tests and folded into a throttled operator log.
+          attr_reader :dropped
+
+          def initialize(buffer_limit, logger)
+            @buffer_limit = buffer_limit
+            @logger = logger
+            @jobs = []                 # FIFO of WriteJob (and the DRAIN sentinel)
+            @pending = Hash.new(0)     # connection.id → buffered frame count
+            @mutex = Mutex.new
+            @cond = ConditionVariable.new
+            @dropped = 0
+          end
+
+          def push(job)
+            @mutex.synchronize do
+              if job == DRAIN
+                @jobs << job
+              else
+                enforce_limit(job)
+                @jobs << job
+                @pending[job.connection.id] += job.envelopes.size
+              end
+              @cond.signal
+            end
+          end
+
+          def pop
+            @mutex.synchronize do
+              @cond.wait(@mutex) while @jobs.empty?
+              job = @jobs.shift
+              @pending[job.connection.id] -= job.envelopes.size unless job == DRAIN
+              job
+            end
+          end
+
+          private
+
+          # Caller holds @mutex. Drop the oldest still-buffered frames for this
+          # connection until adding `job`'s frames keeps it at/under the cap.
+          def enforce_limit(job)
+            return unless @buffer_limit.positive?
+
+            cid = job.connection.id
+            while @pending[cid] + job.envelopes.size > @buffer_limit
+              dropped = drop_oldest_for(cid)
+              break unless dropped # nothing left to drop → let it through
+            end
+          end
+
+          # Caller holds @mutex. Remove the oldest queued WriteJob for cid,
+          # decrementing the pending count. Returns the dropped job or nil.
+          # A drop is logged (throttled to powers of two so a sustained
+          # overflow can't flood the log) so lost frames aren't silent.
+          def drop_oldest_for(cid)
+            idx = @jobs.index { |j| j != DRAIN && j.connection.id == cid }
+            return nil unless idx
+
+            dropped = @jobs.delete_at(idx)
+            @pending[cid] -= dropped.envelopes.size
+            @dropped += 1
+            log_drop(cid) if @dropped.nobits?(@dropped - 1) # power-of-two throttle
+            dropped
+          end
+
+          def log_drop(cid)
+            @logger.warn do
+              "[Pgbus::Streamer::OutboundPump] dropped #{@dropped} durable frame(s) " \
+                "under buffer_limit=#{@buffer_limit} (connection #{cid}) — the client " \
+                "replays them from the archive on reconnect"
+            end
+          end
+        end
+        private_constant :Partition
+      end
+    end
+  end
+end