pgbus 0.9.10 → 0.10.0

data/lib/pgbus/process/dispatcher.rb

@@ -37,6 +37,16 @@ module Pgbus
       MAINTENANCE_BACKOFF_BASE = 30    # seconds; first backoff window
       MAINTENANCE_BACKOFF_MAX = 600    # seconds; window ceiling (10 minutes)
 
+      # A pooled backend the server terminated while the dispatcher sat idle
+      # between cycles surfaces with this exact PostgreSQL text on the next
+      # query. It is expected and self-healing — release_maintenance_connections
+      # returns the dead socket to the pool and the next cycle reconnects — so a
+      # task that hits it logs a calm INFO rather than an alarming WARN. Matched
+      # case-insensitively as a substring of the exception message. Common in
+      # local development (Postgres restart, `rails db:migrate` terminating idle
+      # backends, foreman/overmind restarting the DB), rare in production.
+      TERMINATED_CONNECTION_SIGNAL = "terminating connection due to administrator command"
+
       # The per-task monotonic timestamps run_maintenance consults via run_if_due.
       # Enumerated so set_maintenance_timestamp can validate its argument.
       MAINTENANCE_TIMESTAMPS = %i[
@@ -166,6 +176,51 @@ module Pgbus
 
         results = run_maintenance_tasks(now)
         update_maintenance_backoff(now, results)
+      ensure
+        release_maintenance_connections
+      end
+
+      # Return every AR connection this cycle leased back to the pool. The
+      # dispatcher is a long-lived loop that queries the pool on coarse
+      # intervals (concurrency cleanup every 300s, most tasks hourly). If it
+      # kept its pooled connection leased across the idle sleep, a backend the
+      # server terminates while it sits idle — routine in local development
+      # (a Postgres restart, `rails db:migrate` calling pg_terminate_backend,
+      # foreman/overmind restarting the DB) — would be reused dead on the next
+      # cycle, and every task would raise PG::ConnectionBad
+      # ("terminating connection due to administrator command"). Releasing here
+      # means the next cycle checks out afresh, and AR's verify!-on-checkout
+      # transparently discards a dead socket and reconnects. Best-effort: a
+      # failure to release must never crash the loop (mirrors the Streamer's
+      # release_ar_connections).
+      def release_maintenance_connections
+        return unless defined?(::ActiveRecord::Base)
+
+        Pgbus::BusRecord.connection_handler.clear_active_connections!
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus] Maintenance connection release failed: #{e.class}: #{e.message}" }
+      end
+
+      # True when the error is a pooled backend the server terminated while the
+      # dispatcher was idle between cycles. Self-healing (see
+      # TERMINATED_CONNECTION_SIGNAL / release_maintenance_connections), so
+      # callers downgrade the log from WARN to INFO.
+      def terminated_connection_error?(error)
+        error.message.to_s.downcase.include?(TERMINATED_CONNECTION_SIGNAL)
+      end
+
+      # Log a maintenance task failure at the right volume: a self-healing
+      # terminated-idle-connection is a calm INFO ("will reconnect next cycle"),
+      # anything else stays a WARN operators should look at.
+      def log_maintenance_failure(label, error)
+        if terminated_connection_error?(error)
+          Pgbus.logger.info do
+            "[Pgbus] #{label} skipped: database connection was terminated while idle; " \
+              "reconnecting on the next cycle (#{error.message.lines.first&.strip})"
+          end
+        else
+          Pgbus.logger.warn { "[Pgbus] #{label} failed: #{error.message}" }
+        end
       end
 
       # Runs every due maintenance task and returns their results. Each entry
@@ -284,7 +339,7 @@ module Pgbus
         deleted = ProcessedEvent.expired(Time.current - ttl).delete_all
         Pgbus.logger.debug { "[Pgbus] Cleaned up #{deleted} expired processed events" } if deleted.positive?
       rescue StandardError => e
-        Pgbus.logger.warn { "[Pgbus] Idempotency cleanup failed: #{e.message}" }
+        log_maintenance_failure("Idempotency cleanup", e)
         e
       end
 
@@ -293,7 +348,7 @@ module Pgbus
         deleted = ProcessEntry.stale(Time.current - threshold).delete_all
         Pgbus.logger.info { "[Pgbus] Reaped #{deleted} stale processes" } if deleted.positive?
       rescue StandardError => e
-        Pgbus.logger.warn { "[Pgbus] Stale process reaping failed: #{e.message}" }
+        log_maintenance_failure("Stale process reaping", e)
         e
       end
 
@@ -306,7 +361,7 @@ module Pgbus
         orphaned = Concurrency::BlockedExecution.expire_stale
         Pgbus.logger.debug { "[Pgbus] Expired #{orphaned} orphaned blocked executions" } if orphaned.positive?
       rescue StandardError => e
-        Pgbus.logger.warn { "[Pgbus] Concurrency cleanup failed: #{e.message}" }
+        log_maintenance_failure("Concurrency cleanup", e)
         e
       end
 
@@ -314,14 +369,14 @@ module Pgbus
         promoted = Concurrency::BlockedExecution.promote_next(key, client: Pgbus.client)
         Pgbus.logger.debug { "[Pgbus] Released blocked execution for key: #{key}" } if promoted
       rescue StandardError => e
-        Pgbus.logger.warn { "[Pgbus] Failed to release blocked execution for #{key}: #{e.message}" }
+        log_maintenance_failure("Releasing blocked execution for #{key}", e)
       end
 
       def cleanup_batches
         deleted = Batch.cleanup(older_than: Time.current - (7 * 24 * 3600)) # 7 days
         Pgbus.logger.debug { "[Pgbus] Cleaned up #{deleted} finished batches" } if deleted.positive?
       rescue StandardError => e
-        Pgbus.logger.warn { "[Pgbus] Batch cleanup failed: #{e.message}" }
+        log_maintenance_failure("Batch cleanup", e)
         e
       end
 
@@ -353,7 +408,7 @@ module Pgbus
         )
         Pgbus.logger.info { "[Pgbus] Table maintenance completed: #{maintained} table(s) vacuumed" } if maintained.positive?
       rescue StandardError => e
-        Pgbus.logger.warn { "[Pgbus] Table maintenance failed: #{e.message}" }
+        log_maintenance_failure("Table maintenance", e)
         e
       end
 
@@ -378,7 +433,7 @@ module Pgbus
         reaped = reap_orphaned_uniqueness_keys
         Pgbus.logger.info { "[Pgbus] Reaped #{reaped} orphaned uniqueness keys" } if reaped.positive?
       rescue StandardError => e
-        Pgbus.logger.warn { "[Pgbus] Job lock cleanup failed: #{e.message}" }
+        log_maintenance_failure("Job lock cleanup", e)
         e
       end
 
@@ -434,7 +489,7 @@ module Pgbus
         deleted = OutboxEntry.published_before(Time.current - retention).delete_all
         Pgbus.logger.debug { "[Pgbus] Cleaned up #{deleted} published outbox entries" } if deleted.positive?
       rescue StandardError => e
-        Pgbus.logger.warn { "[Pgbus] Outbox cleanup failed: #{e.message}" }
+        log_maintenance_failure("Outbox cleanup", e)
         e
       end
 
@@ -445,6 +500,10 @@ module Pgbus
         cutoff = Time.current - retention
         batch_size = ARCHIVE_COMPACTION_BATCH_SIZE
         prefix = config.queue_prefix
+        # Stream queues share the job prefix but are pruned separately by
+        # prune_stream_archives (per-stream retention). Skip them here so a
+        # stream archive is compacted by exactly one path, not both.
+        stream_names = current_stream_queue_names
 
         conn = config.connects_to ? Pgbus::BusRecord.connection : ActiveRecord::Base.connection
         queue_names = conn.select_values("SELECT queue_name FROM pgmq.meta ORDER BY queue_name")
@@ -453,6 +512,7 @@ module Pgbus
         queue_names.each_with_index do |full_name, index|
           break if interrupted?("Archive compaction", index, queue_names.size)
           next unless full_name.start_with?("#{prefix}_")
+          next if stream_names.include?(full_name)
 
           stripped = full_name.delete_prefix("#{prefix}_")
           deleted = Pgbus.client.purge_archive(stripped, older_than: cutoff, batch_size: batch_size)
@@ -464,7 +524,7 @@ module Pgbus
         end
         outcome.result
       rescue StandardError => e
-        Pgbus.logger.warn { "[Pgbus] Archive compaction failed: #{e.message}" }
+        log_maintenance_failure("Archive compaction", e)
         e
       end
 
@@ -475,8 +535,8 @@ module Pgbus
       # Lookup order for a given queue: exact string match, then regex
       # match, then streams_default_retention (5 minutes by default).
       def prune_stream_archives
-        prefix = config.streams_queue_prefix
-        return if prefix.nil? || prefix.empty?
+        stream_names = current_stream_queue_names
+        return if stream_names.empty?
 
         batch_size = ARCHIVE_COMPACTION_BATCH_SIZE
         conn = config.connects_to ? Pgbus::BusRecord.connection : ActiveRecord::Base.connection
@@ -485,7 +545,7 @@ module Pgbus
         outcome = LoopOutcome.new
         queue_names.each_with_index do |full_name, index|
           break if interrupted?("Stream archive compaction", index, queue_names.size)
-          next unless full_name.start_with?("#{prefix}_")
+          next unless stream_names.include?(full_name)
 
           retention = retention_for_stream_queue(full_name)
           next unless retention.positive?
@@ -505,7 +565,7 @@ module Pgbus
         end
         outcome.result
       rescue StandardError => e
-        Pgbus.logger.warn { "[Pgbus] Stream archive compaction failed: #{e.message}" }
+        log_maintenance_failure("Stream archive compaction", e)
         e
       end
 
@@ -524,12 +584,12 @@ module Pgbus
       end
 
       def sweep_orphan_streams
-        prefix = config.streams_queue_prefix
-        return if prefix.nil? || prefix.empty?
-
         threshold = config.streams_orphan_threshold
         return unless threshold
 
+        stream_names = current_stream_queue_names
+        return if stream_names.empty?
+
         conn = config.connects_to ? Pgbus::BusRecord.connection : ActiveRecord::Base.connection
         queue_names = conn.select_values("SELECT queue_name FROM pgmq.meta ORDER BY queue_name")
 
@@ -537,7 +597,7 @@ module Pgbus
         outcome = LoopOutcome.new
         queue_names.each_with_index do |full_name, index|
           break if interrupted?("Orphan stream sweep", index, queue_names.size)
-          next unless full_name.start_with?("#{prefix}_")
+          next unless stream_names.include?(full_name)
 
           safe_name = QueueNameValidator.sanitize!(full_name)
           row = conn.select_one(<<~SQL, "Pgbus Orphan Check")
@@ -571,10 +631,20 @@ module Pgbus
         Pgbus.logger.debug { "[Pgbus] Orphan stream sweep complete: dropped #{dropped} queue(s)" } if dropped.positive?
         outcome.result
       rescue StandardError => e
-        Pgbus.logger.warn { "[Pgbus] Orphan stream sweep failed: #{e.message}" }
+        log_maintenance_failure("Orphan stream sweep", e)
         e
       end
 
+      # Fresh set of physical stream-queue names for this maintenance pass.
+      # Reset first so a stream created since the last hourly pass is picked
+      # up without a process restart. Empty on unmigrated installs (registry
+      # table absent) — callers then treat every queue as a job queue, which
+      # is the pre-registry behavior.
+      def current_stream_queue_names
+        Pgbus::StreamQueue.reset_cache!
+        Pgbus::StreamQueue.all_names
+      end
+
       def cleanup_recurring_executions
         retention = config.recurring_execution_retention
         return unless retention&.positive?
@@ -582,7 +652,7 @@ module Pgbus
         deleted = RecurringExecution.older_than(Time.current - retention).delete_all
         Pgbus.logger.debug { "[Pgbus] Cleaned up #{deleted} old recurring executions" } if deleted.positive?
       rescue StandardError => e
-        Pgbus.logger.warn { "[Pgbus] Recurring execution cleanup failed: #{e.message}" }
+        log_maintenance_failure("Recurring execution cleanup", e)
         e
       end
 

data/lib/pgbus/process/notify_listener.rb

@@ -49,12 +49,25 @@ module Pgbus
         @running = false
         @thread = nil
         @conn = nil
+        # Optimistic until the start-time self-probe runs: assume NOTIFY delivery
+        # works so a not-yet-probed listener isn't mistaken for a pooler-deaf one.
+        @delivering = true
       end
 
       def listening_to
         @state_mutex.synchronize { @listening_to.dup }
       end
 
+      # Whether the start-time self-probe confirmed this connection can actually
+      # receive a NOTIFY. False when a transaction-mode pooler or replica
+      # silently drops LISTEN: the thread is still alive (running? == true) but
+      # will never wake the loop. The Worker/Consumer consult this so a
+      # live-but-deaf listener is treated as absent for wake-timeout purposes —
+      # fast polling, not the 15s NOTIFY ceiling (issue #332).
+      def delivering?
+        @state_mutex.synchronize { @delivering }
+      end
+
       def start
         @state_mutex.synchronize do
           return self if @running
@@ -116,8 +129,11 @@ module Pgbus
         # One-shot delivery self-probe on the initial connection only. A pooler
         # or replica that silently breaks LISTEN/NOTIFY is surfaced here with an
         # actionable error; the listener still runs and degrades to polling.
-        # Reconnects skip the probe to stay cheap.
-        NotifyProbe.probe_notify_delivery!(conn, logger: @logger)
+        # Reconnects skip the probe to stay cheap. Record the result so the
+        # owning worker can drop back to fast polling instead of the 15s NOTIFY
+        # ceiling when this connection can't actually deliver (issue #332).
+        delivering = NotifyProbe.probe_notify_delivery!(conn, logger: @logger)
+        @state_mutex.synchronize { @delivering = delivering }
         @state_mutex.synchronize { @conn = conn }
         drain_commands
 

data/lib/pgbus/process/worker.rb

@@ -407,10 +407,19 @@ module Pgbus
         dlq_suffix = Pgbus::DEAD_LETTER_SUFFIX
         prefix = "#{config.queue_prefix}_"
 
+        # Stream queues share the job namespace (pgbus_<name>) but must never
+        # be adopted by a wildcard worker: a worker would claim durable
+        # broadcasts, fail to deserialize them, and DLQ-move them out of the
+        # stream's replay history. The registry is what tells them apart.
+        # Reset first so a stream created since the last resolve is excluded.
+        Pgbus::StreamQueue.reset_cache!
+        stream_names = Pgbus::StreamQueue.all_names
+
         conn = Pgbus.configuration.connects_to ? Pgbus::BusRecord.connection : ActiveRecord::Base.connection
         all_queues = conn.select_values("SELECT queue_name FROM pgmq.meta ORDER BY queue_name")
         resolved = all_queues
                    .reject { |q| q.end_with?(dlq_suffix) }
+                   .reject { |q| stream_names.include?(q) }
                    .map { |q| q.delete_prefix(prefix) }
 
         if resolved.empty?
@@ -596,13 +605,20 @@ module Pgbus
       def wake_timeout
         # A dead listener (running? false) will never wake the loop, so treat
         # it as absent and keep polling at the short interval until
-        # ensure_notify_listener restarts it. Only a live listener earns the
-        # long NOTIFY-mode ceiling.
-        return effective_polling_interval unless notify_wakeup? && @notify_listener&.running?
+        # ensure_notify_listener restarts it. A live-but-deaf listener
+        # (delivering? false — a transaction-mode pooler or replica that drops
+        # LISTEN) is the same story: it will never wake us, so don't raise the
+        # poll floor to the 15s ceiling behind it (issue #332). Only a live,
+        # delivering listener earns the long NOTIFY-mode ceiling.
+        return effective_polling_interval unless notify_wakeup? && listener_delivering?
 
         [effective_polling_interval, config.polling_interval, NOTIFY_FALLBACK_POLL_SECONDS].max
       end
 
+      def listener_delivering?
+        @notify_listener&.running? && @notify_listener.delivering?
+      end
+
       def effective_polling_interval
         return config.polling_interval if @consumer_priority.zero?
 

data/lib/pgbus/streams/pool_autoscaler.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Streams
+    # Self-tuning decision logic for the dedicated streams DB pool (issue #323).
+    #
+    # A PURE DECISION OBJECT — it owns no thread and no connection. Two callers
+    # drive it, both feeding it a live-headroom reading:
+    #   * the streamer's Listener, as a periodic maintenance check on its idle
+    #     LISTEN connection (see Maintenance below); and
+    #   * a publisher (Client#send_stream_message), throttled, on the job pool.
+    # #evaluate reads the streams pool's busy ratio, decides, and resizes via the
+    # #325 hot-swap primitive.
+    #
+    # Cadence is slow (streams_pool_autoscale_interval, default 5 min), so the
+    # interval itself is the debounce: it acts on each check with no multi-sample
+    # hysteresis and no cooldown. A sustained burst converges over a few checks
+    # (one grow step each); a swap's transient (a freshly-swapped connection_pool
+    # is lazy → reads busy ≈ 0) simply means "no shrink this check" and is gone by
+    # the next check minutes later.
+    #
+    # Decision priority per check:
+    #   1. EMERGENCY SHRINK — DB free connections critically low → resize to
+    #      baseline now (protect the DB; overrides the busy signal).
+    #   2. GROW — pool saturated AND a fair share of real headroom exists.
+    #   3. SHRINK — pool idle → step toward baseline.
+    #   4. HOLD.
+    #
+    # SAFETY (proven in the #323 design; independent of cadence):
+    #   * No multi-process exhaustion: four stacked grow guards (GROW_RESERVE
+    #     gate, SAFETY peer inflation, STEP_MAX, per-process floor(free/2)).
+    #   * No grow↔emergency limit cycle: GROW_RESERVE (0.20·maxc) ≥ 4×
+    #     EMERGENCY_MARGIN (0.05·maxc) → a ~15% dead-zone.
+    class PoolAutoscaler
+      GROW_THRESHOLD   = 0.85 # busy_ratio to grow
+      SHRINK_THRESHOLD = 0.30 # busy_ratio to shrink
+      FAIR_FRACTION    = 0.25 # claim only ¼ of the computed fair share per grow
+      SAFETY           = 1.5  # inflate peer count → deflate fair share (undercount guard)
+      STEP_MAX         = 4    # hard cap on connections added per single grow
+
+      # SQL a caller runs on a connection to gather headroom. Public so the
+      # Listener/publisher can issue it; $1 is the application_name LIKE pattern.
+      HEADROOM_SQL = <<~SQL
+        SELECT current_setting('max_connections')::int AS maxc,
+               count(*) AS used,
+               count(DISTINCT application_name)
+                 FILTER (WHERE application_name LIKE $1) AS peers
+        FROM pg_stat_activity
+      SQL
+
+      def initialize(client:, config:, logger: Pgbus.logger)
+        @client = client
+        @config = config
+        @logger = logger
+        @baseline = config.streams_pool_size
+      end
+
+      # One maintenance decision. `headroom` is {maxc:, used:, peers:} from a
+      # caller's query, or nil if it failed (→ HOLD). Returns the action taken
+      # (:emergency_shrink / :grow / :shrink / :hold) — handy for tests + logging.
+      #
+      # `allow_shrink:` gates the NORMAL idle shrink (priority 3). The streamer
+      # passes true (it sees the sustained idle picture across replay reads). A
+      # publisher passes false: it only ever reacts to its OWN publish pressure
+      # (grow), and leaves idle-shrink to the streamer/consumer. Emergency shrink
+      # is NEVER gated — a DB running out of connections must always be relieved,
+      # whoever notices first.
+      def evaluate(headroom, allow_shrink: true)
+        return :hold if headroom.nil?
+
+        free = headroom[:maxc] - headroom[:used]
+
+        # PRIORITY 1 — EMERGENCY SHRINK (keys off DB `free`, an external fact).
+        return emergency_shrink(free, headroom[:maxc]) if free < emergency_margin(headroom[:maxc])
+
+        size, busy_ratio = pool_busy
+        return :hold if size.nil?
+
+        if busy_ratio >= GROW_THRESHOLD
+          maybe_grow(size, free, headroom)
+        elsif allow_shrink && busy_ratio < SHRINK_THRESHOLD
+          maybe_shrink(size)
+        else
+          :hold
+        end
+      end
+
+      private
+
+      # PRIORITY 2 — GROW into a bounded fair share of live headroom.
+      def maybe_grow(size, free, headroom)
+        return :hold if free <= grow_reserve(headroom[:maxc]) # not enough headroom
+        return :hold if size <= 1 # a telemetry checkout would starve publishing
+
+        delta = grow_delta(free, headroom[:peers])
+        return :hold if delta < 1
+
+        target = size + delta
+        cap = @config.streams_pool_max
+        target = [target, cap].min if cap
+        return :hold if target <= size
+
+        act(size, target, :grow)
+      end
+
+      # PRIORITY 3 — SHRINK one step toward the baseline.
+      def maybe_shrink(size)
+        return :hold if size <= @baseline
+
+        act(size, [@baseline, size - STEP_MAX].max, :shrink)
+      end
+
+      def emergency_shrink(free, maxc)
+        return :hold if pool_current_size <= @baseline
+
+        if swapped?(@client.resize_streams_pool(@baseline))
+          @logger.warn do
+            "[Pgbus::Streams::PoolAutoscaler] EMERGENCY streams-pool shrink to " \
+              "#{@baseline} (free=#{free}/#{maxc})"
+          end
+          :emergency_shrink
+        else
+          # The DB is critically low on connections but the shrink was a no-op
+          # (unchanged / shared-AR). This is the one case where a failed resize
+          # matters most — leave a trace instead of silently reporting success.
+          @logger.warn do
+            "[Pgbus::Streams::PoolAutoscaler] EMERGENCY streams-pool shrink to " \
+              "#{@baseline} did NOT apply (free=#{free}/#{maxc}) — resize was a no-op"
+          end
+          :hold
+        end
+      end
+
+      # fair_share = free / (peers · SAFETY); claim FAIR_FRACTION, never more than
+      # STEP_MAX or half the remaining headroom (leave ≥half for unknown peers →
+      # geometric contraction → N processes can't collectively exhaust the DB).
+      def grow_delta(free, peers)
+        peer_count = [peers.to_i, 1].max
+        fair_share = free.to_f / (peer_count * SAFETY)
+        [(FAIR_FRACTION * fair_share).floor, STEP_MAX, (free / 2)].min
+      end
+
+      def act(from_size, target_size, kind)
+        if swapped?(@client.resize_streams_pool(target_size))
+          @logger.info { "[Pgbus::Streams::PoolAutoscaler] streams pool #{from_size}->#{target_size} (#{kind})" }
+          kind
+        else
+          :hold # unchanged / shared-AR no-op
+        end
+      end
+
+      # Margins self-derive from live max_connections; the 4× gap forbids a
+      # grow↔emergency limit cycle.
+      def emergency_margin(maxc) = [5, (0.05 * maxc).ceil].max
+      def grow_reserve(maxc)     = [20, (0.20 * maxc).ceil].max
+
+      def pool_busy
+        stats = @client.streams_pool_stats
+        return [nil, nil] if stats.nil? || stats.empty?
+
+        size = stats[:size]
+        available = stats[:available]
+        return [nil, nil] if size.nil? || available.nil? || size <= 0
+
+        [size, (size - available).to_f / size]
+      end
+
+      def pool_current_size
+        stats = @client.streams_pool_stats
+        stats.is_a?(Hash) ? stats[:size].to_i : 0
+      end
+
+      def swapped?(result) = result.is_a?(Pgbus::Client::ResizablePool::SwapStats)
+
+      # Wraps an autoscaler as a Listener maintenance task: on each throttled idle
+      # window the Listener calls #run(conn); this queries live headroom on THAT
+      # connection (the streamer's existing LISTEN connection — no extra
+      # connection) and hands it to the autoscaler. `interval` is the throttle
+      # (seconds) the Listener honors between runs.
+      class Maintenance
+        attr_reader :interval
+
+        def initialize(autoscaler:, interval:, application_name_prefix:)
+          @autoscaler = autoscaler
+          @interval = interval
+          @like = "#{application_name_prefix}_%"
+        end
+
+        def run(conn)
+          row = conn.exec_params(HEADROOM_SQL, [@like]).first
+          # Explicit positional hash (braces) — evaluate now takes an optional
+          # allow_shrink: keyword, so a bare hash would be parsed as keywords.
+          # The streamer allows shrink (it sees the sustained idle picture).
+          @autoscaler.evaluate(
+            { maxc: row["maxc"].to_i, used: row["used"].to_i, peers: row["peers"].to_i },
+            allow_shrink: true
+          )
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/streams/pool_trigger.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Pgbus
+  module Streams
+    # Publisher-side throttled autoscale trigger (issue #323 follow-up).
+    #
+    # The streamer autoscales via a periodic check on its idle LISTEN connection,
+    # but a pure-*publisher* process (a worker that fans out broadcasts via
+    # Client#send_stream_message but serves no SSE) has no streamer — so its
+    # streams pool would never autoscale. This closes that gap: each publish
+    # opportunistically triggers a headroom check, throttled to at most once per
+    # `interval` seconds across all publisher threads.
+    #
+    # OFF THE HOT PATH: the publishing thread only does a lock-free
+    # compare-and-set to claim the throttle window and, if it wins, posts the
+    # actual work to a background single-thread executor and returns immediately.
+    # It never runs the query or the resize inline. A quiet (non-publishing)
+    # process does zero work — this object is only ever built by the first publish
+    # (Client#streams_pool_trigger), and only when autoscale is on and the pool is
+    # dedicated, so a process that never publishes a stream never spawns the
+    # executor thread. There is no always-on timer.
+    #
+    # AT MOST ONE CHECK AT A TIME is enforced primarily by the single-thread
+    # executor (it serializes run_check calls end-to-end) plus the throttle CAS
+    # (one post per interval). The @running flag is a belt-and-suspenders
+    # invariant that becomes load-bearing only if a MULTI-threaded executor is
+    # injected (the executor: seam) — then it is the sole guard against two
+    # overlapping check bodies. It is cheap (one AtomicBoolean per check), so it
+    # stays.
+    #
+    # The query runs through the JOB pool, NOT the streams pool: pg_stat_activity
+    # is global, so any connection to the same database reads the same headroom,
+    # and using the job pool means the check can never starve on a saturated
+    # streams pool (the very pool it's trying to grow). The decision reuses
+    # PoolAutoscaler#evaluate with allow_shrink: false — a publisher only ever
+    # reacts to its own publish pressure (grow) and to DB exhaustion (emergency
+    # shrink); the streamer/consumer handles normal idle shrink.
+    class PoolTrigger
+      def initialize(autoscaler:, job_pool:, interval:, application_name_prefix:, clock: nil,
+                     executor: nil, logger: Pgbus.logger)
+        @autoscaler = autoscaler
+        @job_pool = job_pool
+        @interval = interval
+        @like = "#{application_name_prefix}_%"
+        @clock = clock || -> { ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) }
+        @logger = logger
+        # A single background worker with a GENUINELY bounded 1-slot queue that
+        # DISCARDS overflow. NOTE: Concurrent::SingleThreadExecutor silently drops
+        # max_queue: (it hardcodes an unbounded queue), so build the base
+        # ThreadPoolExecutor directly to actually honor the bound. Built eagerly
+        # (assigned once, safely published with the object) — the quiet-process
+        # "no thread" guarantee is owned by Client#streams_pool_trigger (this
+        # object only exists after a real publish with autoscale on), so there's
+        # no reason to lazy-build inside. Injectable for tests.
+        @executor = executor || Concurrent::ThreadPoolExecutor.new(
+          min_threads: 1, max_threads: 1, max_queue: 1, fallback_policy: :discard
+        )
+        # nil = never checked. AtomicReference gives a lock-free compare-and-set
+        # so exactly one concurrent publisher claims each throttle window.
+        @last_check = Concurrent::AtomicReference.new(nil)
+        # At-most-one-check guard — load-bearing only under an injected
+        # multi-threaded executor (see class comment).
+        @running = Concurrent::AtomicBoolean.new(false)
+      end
+
+      # Called from the publish path. Claims the throttle window with a single CAS
+      # and, if it wins, defers the actual check to the background executor. Does
+      # NOT run the query or resize on the calling thread. Never raises.
+      def maybe_check
+        return unless claim_window
+
+        @executor.post { run_check }
+      rescue StandardError => e
+        # A post after shutdown raises RejectedExecutionError; swallow it so a
+        # publish never fails. The check body itself is guarded inside run_check.
+        @logger.debug { "[Pgbus::Streams::PoolTrigger] dispatch failed: #{e.class}: #{e.message}" }
+      end
+
+      # Stop the background executor (idempotent). For a clean Client#close.
+      def shutdown
+        @executor.shutdown
+        @executor.wait_for_termination(5)
+      end
+
+      private
+
+      # True for exactly one caller per `interval` window; false for the rest.
+      # A losing CAS (another thread advanced @last_check first) also returns
+      # false, so only one thread posts the check per window.
+      def claim_window
+        now = @clock.call
+        last = @last_check.get
+        return false if last && (now - last) < @interval
+
+        @last_check.compare_and_set(last, now)
+      end
+
+      # Runs on the executor thread. Skips if a prior check is still in flight so
+      # a slow query can't queue up work. Fully guarded — a failure here never
+      # escapes the executor.
+      def run_check
+        return unless @running.make_true # false if already running
+
+        begin
+          headroom = read_headroom
+          @autoscaler.evaluate(headroom, allow_shrink: false) if headroom
+        ensure
+          @running.make_false
+        end
+      rescue StandardError => e
+        @logger.debug { "[Pgbus::Streams::PoolTrigger] check failed: #{e.class}: #{e.message}" }
+      end
+
+      def read_headroom
+        @job_pool.with_connection do |conn|
+          row = conn.exec_params(PoolAutoscaler::HEADROOM_SQL, [@like]).first
+          { maxc: row["maxc"].to_i, used: row["used"].to_i, peers: row["peers"].to_i }
+        end
+      end
+    end
+  end
+end