pgbus 0.6.3 → 0.6.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97572298add12c78b7d9f3ebb6a50af36a9803380d42202a66031ce7f1018d4c
-  data.tar.gz: b5498b051a4c1d134c2944d1b0c556124fef49a7276ee32cbe0172fac12f6c8d
+  metadata.gz: d43bc708b048e8b81cae4c4954686fcd0f227fd8bc2498c599ab231f262ef607
+  data.tar.gz: 465eba8207a366a8f639f110e8131d064b46267161ffbf969b86aa470de56bfa
 SHA512:
-  metadata.gz: ec8b0af9bac7c6156b12effa0ce3d3ecf9a29f06c091f5117c5567114c00f44c6dea26666306ff9b084c0b616aa3e47b5080d986c1159fcedf64e5fbfe1f909a
-  data.tar.gz: 0227ab4f57df35bd89c4dac8a022df20a16d8c30eaaff0cbc75c8a49e8debf9dba62e1fb54b1ac26c327aab6199398ac2fe1575db9b1ad1062fb0d6b21083ffc
+  metadata.gz: cbc395ea4f504b5295b7a90c50981aef8cce7b7a060a8488db2b8a3a73d9d08ae8a571a067626e1e269a501e87790f230231018d527096ebba89a6a743a390ac
+  data.tar.gz: 12ff4342c5fb3b1b30c328c7f373dcfcfd2db72d87d4a079e0538ba6857ca89b952078a6150ae495b560815bb637f396768397ccb250b98371096e146cb37b23

data/README.md

@@ -463,6 +463,36 @@ end
 
 When a limit is hit, the worker drains its thread pool, exits, and the supervisor forks a fresh process. RSS memory is sampled from `/proc/self/statm` (Linux) or `ps -o rss` (macOS).
 
+### Async execution mode (fibers)
+
+Workers can optionally execute jobs as fibers instead of threads. This is ideal for I/O-bound workloads (HTTP calls, email delivery, LLM API calls) where jobs spend most of their time waiting on network I/O.
+
+```ruby
+Pgbus.configure do |config|
+  # Global: all workers use async mode
+  config.execution_mode = :async
+
+  # Or per-worker: mix thread and async workers
+  config.workers = [
+    { queues: %w[webhooks emails], threads: 100, execution_mode: :async },
+    { queues: %w[default], threads: 5 }  # stays thread-based
+  ]
+end
+```
+
+**Prerequisites:**
+
+1. Add `gem "async"` to your Gemfile
+2. Set `config.active_support.isolation_level = :fiber` in your Rails app
+
+**Why it reduces connections:** In thread mode, each thread holds a database connection while waiting on I/O. With 50 threads, that's 50 connections. In async mode, 50 fibers share 3-5 connections because fibers yield during I/O and only one runs at a time.
+
+**CLI flag:** `pgbus start --execution-mode async`
+
+**Safety:** Messages stay in PGMQ with visibility timeout protection regardless of execution mode. If a fiber or worker crashes, the visibility timeout expires and messages become available for re-read. No data loss risk.
+
+**Not recommended for:** CPU-bound jobs (image processing, heavy computation). These block the single reactor thread and should use thread mode.
+
 ## Routing and ordering
 
 How messages flow between producers and the workers that handle them: priority sub-queues, consumer priority for active/standby workers, and single-active-consumer for strict ordering.
@@ -675,7 +705,7 @@ Without the plugin, Puma closes hijacked SSE sockets abruptly during graceful re
 
 ### Requirements
 
-- **Puma 6.1+ or Falcon.** Streams use `rack.hijack`. Puma 6.1+ supports it via partial hijack (thread-releasing, see [puma/puma#1009](https://github.com/puma/puma/issues/1009)). Falcon supports it via [protocol-rack](https://github.com/socketry/protocol-rack)'s adapter layer — same `env["rack.hijack?"]` + `env["rack.hijack"]` shape as Puma, so `Pgbus::Web::StreamApp` needs no server-specific code paths. Unicorn, Pitchfork, and Passenger return HTTP 501 from the streams endpoint.
+- **Puma 6.1+ or Falcon.** Streams use `rack.hijack` by default. Puma 6.1+ supports it via partial hijack (thread-releasing, see [puma/puma#1009](https://github.com/puma/puma/issues/1009)). Falcon supports both the hijack path (via [protocol-rack](https://github.com/socketry/protocol-rack)'s emulation) and a native streaming body path (`streams_falcon_streaming_body = true`) that integrates with Falcon's fiber scheduler for better backpressure and connection lifecycle management. Unicorn, Pitchfork, and Passenger return HTTP 501 from the streams endpoint.
 - **PostgreSQL LISTEN/NOTIFY.** `config.listen_notify = true` (the default). Stream queues override PGMQ's 250ms NOTIFY throttle to 0 so every broadcast fires individually.
 - **HTTP/2 or HTTP/3 in production.** SSE has a 6-connection-per-origin limit on HTTP/1.1; HTTP/2 lifts it. Falcon supports HTTP/2 natively without a reverse proxy.
 
@@ -695,9 +725,22 @@ Pgbus.configure do |c|
   c.streams_idle_timeout           = 3_600         # close idle connections after 1h
   c.streams_listen_health_check_ms = 250           # PG LISTEN keepalive + ensure_listening ack budget
   c.streams_write_deadline_ms      = 5_000         # write_nonblock deadline
+  c.streams_falcon_streaming_body  = false         # opt-in: Falcon-native streaming body
 end
 ```
 
+#### Falcon-native streaming body (opt-in)
+
+When running on Falcon, enable native streaming body support for better integration with Falcon's fiber scheduler:
+
+```ruby
+c.streams_falcon_streaming_body = true
+```
+
+With this flag, `StreamApp` returns `[200, headers, Writable]` instead of hijacking the socket. Falcon drives the response lifecycle with proper backpressure, connection cleanup, and fiber-scheduled IO. SSE writes go through `Protocol::HTTP::Body::Writable` which is fiber-safe and yields to other fibers when blocked.
+
+Without the flag (default), Falcon uses the same `rack.hijack` path as Puma via protocol-rack's emulation. Both paths are tested and work correctly — the streaming body path is an optimization for Falcon deployments that want tighter scheduler integration.
+
 ### How it works
 
 Stream broadcasts are stored in PGMQ queues prefixed `pgbus_stream_*`. Each broadcast is assigned a monotonic `msg_id` by PGMQ. The `pgbus_stream_from` helper captures the current `MAX(msg_id)` at render time and embeds it in the HTML as `since-id`. When the SSE client connects, it sends that cursor as `?since=` on the first request and as `Last-Event-ID` on reconnects. The streamer replays from `pgmq.q_*` (live) UNION `pgmq.a_*` (archive) for any `msg_id > cursor`, then switches to LISTEN/NOTIFY for the live path. There is no message identity gap between the render and the subscribe — the cursor model guarantees every broadcast is delivered exactly once, in order, even across reconnects.

data/app/helpers/pgbus/streams_helper.rb

@@ -75,22 +75,34 @@ module Pgbus
       end
     end
 
-    # Build the SSE endpoint URL by asking the engine where its
-    # `:streams` mount point lives, then appending the signed name.
-    # The base comes from Pgbus::Engine.routes.url_helpers.streams_path
-    # so the URL follows whatever mount point the host app chose for
-    # the engine ("/pgbus", "/admin/dashboard", etc.). A
-    # `NoMethodError` fallback covers the test-only context where
-    # the helper is included in a plain class outside a Rails
-    # request and the engine's url_helpers aren't wired in.
+    # Build the SSE endpoint URL for the given signed stream name.
+    #
+    # Resolution order:
+    #   1. `config.streams_path` — explicit override, useful when the
+    #      engine is mounted behind an auth constraint but the SSE
+    #      endpoint is mounted publicly at a separate path:
+    #
+    #        # config/routes.rb
+    #        authenticate :user, ->(u) { u.admin? } do
+    #          mount Pgbus::Engine => "/admin/jobs"
+    #        end
+    #        mount Pgbus::Web::StreamApp.new => "/pgbus/streams"
+    #
+    #        # config/initializers/pgbus.rb
+    #        Pgbus.configure { |c| c.streams_path = "/pgbus/streams" }
+    #
+    #   2. Engine route helper — derives the path from wherever the
+    #      host app mounted the engine.
+    #
+    #   3. Fallback `/pgbus/streams` — test-only context where the
+    #      engine's url_helpers aren't wired in.
     def pgbus_stream_src(signed_name)
+      base = Pgbus.configuration.streams_path
+      return "#{base.delete_suffix("/")}/#{signed_name}" if base
+
       base = Pgbus::Engine.routes.url_helpers.streams_path
       "#{base}/#{signed_name}"
     rescue NameError
-      # NameError covers both uninitialized-constant (Pgbus::Engine
-      # not loaded, e.g. plain-Ruby unit specs) and NoMethodError
-      # (a NameError subclass) when the routes helper chain isn't
-      # wired in.
       "/pgbus/streams/#{signed_name}"
     end
 

data/lib/pgbus/cli.rb

@@ -42,6 +42,7 @@ module Pgbus
       options = parse_start_options(args)
 
       Pgbus.configuration.workers = options[:queues] if options[:queues]
+      Pgbus.configuration.execution_mode = options[:execution_mode].to_sym if options[:execution_mode]
       apply_capsule_filter(options[:capsule]) if options[:capsule]
       apply_role_filter(options)
     end
@@ -70,6 +71,10 @@ module Pgbus
         opts.on("--dispatcher-only", "Run only the dispatcher (the maintenance pod pattern)") do
           options[:dispatcher_only] = true
         end
+
+        opts.on("--execution-mode MODE", "Execution mode: threads (default) or async") do |v|
+          options[:execution_mode] = v
+        end
       end.parse!(args.dup)
       options
     end
@@ -165,6 +170,8 @@ module Pgbus
                              pattern — exactly one of these per deployment)
           --dispatcher-only  Run only the dispatcher (the maintenance pod
                              pattern)
+          --execution-mode   Execution mode: threads (default) or async
+                             (fiber-based, lower connection usage)
       HELP
     end
   end

data/lib/pgbus/configuration.rb

@@ -11,7 +11,7 @@ module Pgbus
     attr_accessor :default_queue, :queue_prefix
 
     # Worker settings
-    attr_accessor :polling_interval, :prefetch_limit
+    attr_accessor :polling_interval, :prefetch_limit, :execution_mode
     attr_reader :workers, :visibility_timeout # rubocop:disable Style/AccessorGrouping
 
     # Supervisor role selection.
@@ -90,7 +90,7 @@ module Pgbus
                   :metrics_enabled
 
     # Streams (turbo-rails replacement, SSE-based)
-    attr_accessor :streams_enabled, :streams_queue_prefix, :streams_signed_name_secret,
+    attr_accessor :streams_enabled, :streams_path, :streams_queue_prefix, :streams_signed_name_secret,
                   :streams_default_retention, :streams_retention, :streams_heartbeat_interval,
                   :streams_max_connections, :streams_idle_timeout, :streams_listen_health_check_ms,
                   :streams_write_deadline_ms, :streams_falcon_streaming_body,
@@ -111,6 +111,7 @@ module Pgbus
       @visibility_timeout = 30
 
       @prefetch_limit = nil
+      @execution_mode = :threads
 
       @max_jobs_per_worker = nil
       @max_memory_mb = nil
@@ -168,6 +169,7 @@ module Pgbus
       @metrics_enabled = true
 
       @streams_enabled = true
+      @streams_path = nil
       @streams_queue_prefix = "pgbus_stream"
       @streams_signed_name_secret = nil
       @streams_default_retention = 5 * 60 # 5 minutes
@@ -215,6 +217,13 @@ module Pgbus
       (0...priority_levels).map { |p| priority_queue_name(name, p) }
     end
 
+    # Returns the execution mode for a specific worker config hash,
+    # falling back to the global execution_mode setting.
+    def execution_mode_for(worker_config)
+      mode = worker_config[:execution_mode] || worker_config["execution_mode"] || execution_mode
+      ExecutionPools.normalize_mode(mode)
+    end
+
     VALID_PGMQ_SCHEMA_MODES = %i[auto extension embedded].freeze
 
     def pgmq_schema_mode=(mode)
@@ -241,9 +250,16 @@ module Pgbus
         raise ArgumentError, "retry_backoff_jitter must be between 0 and 1"
       end
 
+      # Validate global execution_mode
+      ExecutionPools.normalize_mode(execution_mode)
+
       Array(workers).each do |w|
         threads = w[:threads] || w["threads"] || 5
         raise ArgumentError, "worker threads must be > 0" unless threads.is_a?(Integer) && threads.positive?
+
+        # Validate per-worker execution_mode override if present
+        mode = w[:execution_mode] || w["execution_mode"]
+        ExecutionPools.normalize_mode(mode) if mode
       end
 
       raise ArgumentError, "prefetch_limit must be > 0" if prefetch_limit && !(prefetch_limit.is_a?(Integer) && prefetch_limit.positive?)
@@ -469,6 +485,11 @@ module Pgbus
     # default formula provides.
     POOL_SIZE_WARN_THRESHOLD = 50
 
+    # Connections needed per async worker: one for the reactor's serial
+    # execution, one for polling, one for headroom. Fibers share connections
+    # because only one runs at a time per reactor thread.
+    ASYNC_POOL_CONNECTIONS = 3
+
     def resolved_pool_size
       return pool_size if pool_size
 
@@ -608,10 +629,19 @@ module Pgbus
           raise ArgumentError,
                 "#{group} threads must be a positive integer, got #{threads.inspect}"
         end
-        threads
+
+        if async_execution_mode?(entry)
+          ASYNC_POOL_CONNECTIONS
+        else
+          threads
+        end
       end
     end
 
+    def async_execution_mode?(entry)
+      execution_mode_for(entry) == :async
+    end
+
     def warn_if_oversized(size)
       return unless size > POOL_SIZE_WARN_THRESHOLD
 

data/lib/pgbus/execution_pools/async_pool.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module ExecutionPools
+    class AsyncPool
+      attr_reader :capacity
+
+      IDLE_WAIT_INTERVAL = 0.01
+
+      def initialize(capacity:, on_state_change: nil)
+        @capacity = capacity
+        @on_state_change = on_state_change
+        @available_capacity = capacity
+        @mutex = Mutex.new
+        @state_mutex = Mutex.new
+        @shutdown_flag = false
+        @fatal_error = nil
+        @boot_queue = Thread::Queue.new
+        @pending = Thread::Queue.new
+
+        validate_dependencies!
+        @reactor_thread = start_reactor
+        result = @boot_queue.pop
+        raise result if result.is_a?(Exception)
+      end
+
+      def post(&block)
+        raise_if_fatal!
+        raise "Execution pool is shutting down" if shutdown?
+
+        reserved = false
+        reserve_capacity!
+        reserved = true
+        @pending << block
+      rescue StandardError
+        restore_capacity if reserved
+        raise
+      end
+
+      def available_capacity
+        raise_if_fatal!
+        @mutex.synchronize { @available_capacity }
+      end
+
+      def idle?
+        available_capacity.positive?
+      end
+
+      def shutdown
+        @state_mutex.synchronize do
+          return false if @shutdown_flag
+
+          @shutdown_flag = true
+        end
+      end
+
+      def shutdown?
+        @state_mutex.synchronize { @shutdown_flag }
+      end
+
+      def wait_for_termination(timeout)
+        @reactor_thread&.join(timeout)
+      end
+
+      def kill
+        shutdown
+        @reactor_thread&.kill
+      end
+
+      def metadata
+        inflight = @mutex.synchronize { @available_capacity }
+        {
+          mode: :async,
+          capacity: @capacity,
+          busy: @capacity - inflight
+        }
+      end
+
+      private
+
+      def validate_dependencies!
+        require "async"
+        require "async/semaphore"
+      rescue LoadError => e
+        raise LoadError,
+              "Async execution mode requires the `async` gem. " \
+              "Add `gem \"async\"` to your Gemfile. Original error: #{e.message}"
+      end
+
+      # rubocop:disable Lint/RescueException
+      def start_reactor
+        Thread.new do
+          Thread.current.name = "pgbus-async-reactor-#{object_id}"
+          Async do |task|
+            semaphore = Async::Semaphore.new(@capacity, parent: task)
+            @boot_queue << :ready
+
+            wait_for_executions(semaphore)
+            wait_for_inflight
+          end
+        rescue Exception => e
+          register_fatal_error(e)
+          raise
+        end
+      end
+      # rubocop:enable Lint/RescueException
+
+      def wait_for_executions(semaphore)
+        loop do
+          schedule_pending(semaphore)
+          break if shutdown? && @pending.empty?
+
+          sleep(IDLE_WAIT_INTERVAL) if @pending.empty?
+        end
+      end
+
+      def schedule_pending(semaphore)
+        while (block = next_pending)
+          semaphore.async do
+            perform(block)
+          end
+        end
+      end
+
+      def next_pending
+        @pending.pop(true)
+      rescue ThreadError
+        nil
+      end
+
+      def perform(block)
+        block.call
+      rescue StandardError => e
+        Pgbus.logger.error { "[Pgbus] Async pool fiber error: #{e.class}: #{e.message}" }
+      ensure
+        restore_capacity
+      end
+
+      def reserve_capacity!
+        @mutex.synchronize do
+          raise "Execution pool is at capacity" if @available_capacity <= 0
+
+          @available_capacity -= 1
+        end
+      end
+
+      def restore_capacity
+        should_notify = @mutex.synchronize do
+          @available_capacity += 1
+          @available_capacity.positive?
+        end
+        @on_state_change&.call if should_notify
+      end
+
+      def register_fatal_error(error)
+        @state_mutex.synchronize { @fatal_error ||= error }
+        @boot_queue << error if @boot_queue.empty?
+        @on_state_change&.call
+      end
+
+      def raise_if_fatal!
+        error = @state_mutex.synchronize { @fatal_error }
+        raise error if error
+      end
+
+      def wait_for_inflight
+        sleep(IDLE_WAIT_INTERVAL) while inflight?
+      end
+
+      def inflight?
+        @mutex.synchronize { @available_capacity < @capacity }
+      end
+    end
+  end
+end

data/lib/pgbus/execution_pools/thread_pool.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Pgbus
+  module ExecutionPools
+    class ThreadPool
+      attr_reader :capacity
+
+      def initialize(capacity:, on_state_change: nil)
+        @capacity = capacity
+        @on_state_change = on_state_change
+        @available_capacity = Concurrent::AtomicFixnum.new(capacity)
+        @pool = Concurrent::FixedThreadPool.new(capacity)
+      end
+
+      def post(&block)
+        @available_capacity.decrement
+        begin
+          @pool.post do
+            block.call
+          ensure
+            @available_capacity.increment
+            @on_state_change&.call
+          end
+        rescue StandardError
+          @available_capacity.increment
+          raise
+        end
+      end
+
+      def available_capacity
+        @available_capacity.value
+      end
+
+      def idle?
+        available_capacity.positive?
+      end
+
+      def shutdown
+        @pool.shutdown
+      end
+
+      def wait_for_termination(timeout)
+        @pool.wait_for_termination(timeout)
+      end
+
+      def kill
+        @pool.kill
+      end
+
+      def metadata
+        {
+          mode: :threads,
+          capacity: @capacity,
+          busy: @capacity - available_capacity
+        }
+      end
+    end
+  end
+end

data/lib/pgbus/execution_pools.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module ExecutionPools
+    class << self
+      def build(mode:, capacity:, on_state_change: nil)
+        case normalize_mode(mode)
+        when :threads
+          ThreadPool.new(capacity: capacity, on_state_change: on_state_change)
+        when :async
+          AsyncPool.new(capacity: capacity, on_state_change: on_state_change)
+        end
+      end
+
+      def normalize_mode(mode)
+        case mode.to_s
+        when "", "threads"
+          :threads
+        when "async", "fiber"
+          :async
+        else
+          raise ArgumentError, "Unknown execution_mode: #{mode.inspect}. Expected one of: :threads, :async, :fiber"
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/process/consumer.rb

@@ -7,14 +7,15 @@ module Pgbus
     class Consumer
       include SignalHandler
 
-      attr_reader :topics, :threads, :config
+      attr_reader :topics, :threads, :config, :execution_mode
 
-      def initialize(topics:, threads: 3, config: Pgbus.configuration)
+      def initialize(topics:, threads: 3, config: Pgbus.configuration, execution_mode: :threads)
         @topics = Array(topics)
         @threads = threads
         @config = config
+        @execution_mode = ExecutionPools.normalize_mode(execution_mode)
         @shutting_down = false
-        @pool = Concurrent::FixedThreadPool.new(threads)
+        @pool = ExecutionPools.build(mode: @execution_mode, capacity: threads)
         @registry = EventBus::Registry.instance
       end
 
@@ -53,7 +54,7 @@ module Pgbus
       end
 
       def consume
-        idle = @pool.max_length - @pool.queue_length
+        idle = @pool.available_capacity
         return interruptible_sleep(config.polling_interval) if idle <= 0
 
         tagged_messages = if @queue_names.size == 1

data/lib/pgbus/process/supervisor.rb

@@ -60,6 +60,7 @@ module Pgbus
         threads = worker_config[:threads] || worker_config["threads"] || 5
         single_active = worker_config[:single_active_consumer] || worker_config["single_active_consumer"] || false
         priority = worker_config[:consumer_priority] || worker_config["consumer_priority"] || 0
+        exec_mode = config.execution_mode_for(worker_config)
 
         pid = fork do
           restore_signals
@@ -68,7 +69,8 @@ module Pgbus
           bootstrap_queues
           worker = Worker.new(
             queues: queues, threads: threads, config: config,
-            single_active_consumer: single_active, consumer_priority: priority
+            single_active_consumer: single_active, consumer_priority: priority,
+            execution_mode: exec_mode
           )
           worker.run
         end
@@ -79,7 +81,7 @@ module Pgbus
         end
 
         @forks[pid] = { type: :worker, config: worker_config }
-        Pgbus.logger.info { "[Pgbus] Forked worker pid=#{pid} queues=#{queues.join(",")}" }
+        Pgbus.logger.info { "[Pgbus] Forked worker pid=#{pid} queues=#{queues.join(",")} mode=#{exec_mode}" }
       rescue Errno::EAGAIN, Errno::ENOMEM => e
         Pgbus.logger.error { "[Pgbus] Fork failed for worker: #{e.message}" }
       end

data/lib/pgbus/process/worker.rb

@@ -7,14 +7,16 @@ module Pgbus
     class Worker
       include SignalHandler
 
-      attr_reader :queues, :threads, :config
+      attr_reader :queues, :threads, :config, :execution_mode
 
       def initialize(queues:, threads: 5, config: Pgbus.configuration,
-                     single_active_consumer: false, consumer_priority: 0)
+                     single_active_consumer: false, consumer_priority: 0,
+                     execution_mode: :threads)
         @queues = Array(queues)
         @wildcard = @queues.include?("*")
         @threads = threads
         @config = config
+        @execution_mode = ExecutionPools.normalize_mode(execution_mode)
         @single_active_consumer = single_active_consumer
         @consumer_priority = consumer_priority
         @lifecycle = Lifecycle.new
@@ -27,10 +29,14 @@ module Pgbus
         @started_at_monotonic = monotonic_now
         @stat_buffer = config.stats_enabled ? Pgbus::StatBuffer.new : nil
         @executor = Pgbus::ActiveJob::Executor.new(stat_buffer: @stat_buffer)
-        @pool = Concurrent::FixedThreadPool.new(threads)
+        @wake_signal = WakeSignal.new
+        @pool = ExecutionPools.build(
+          mode: @execution_mode,
+          capacity: threads,
+          on_state_change: -> { @wake_signal.notify! }
+        )
         @circuit_breaker = Pgbus::CircuitBreaker.new(config: config)
         @queue_lock = QueueLock.new if @single_active_consumer
-        @wake_signal = WakeSignal.new
       end
 
       def stats
@@ -39,12 +45,13 @@ module Pgbus
           jobs_failed: @jobs_failed.value,
           in_flight: @in_flight.value,
           state: @lifecycle.state,
+          execution_mode: @execution_mode,
           consumer_priority: @consumer_priority,
           single_active_consumer: @single_active_consumer,
           locked_queues: @queue_lock&.held_queues || [],
           rates: @rate_counter.rates,
           started_at: @started_at
-        }
+        }.merge(@pool.metadata)
       end
 
       def run
@@ -52,7 +59,10 @@ module Pgbus
         start_heartbeat
         resolve_wildcard_queues
         @lifecycle.transition_to!(:running)
-        Pgbus.logger.info { "[Pgbus] Worker started: queues=#{queues.join(",")} threads=#{threads} pid=#{::Process.pid}" }
+        Pgbus.logger.info do
+          "[Pgbus] Worker started: queues=#{queues.join(",")} threads=#{threads} " \
+            "mode=#{@execution_mode} pid=#{::Process.pid}"
+        end
 
         loop do
           process_signals
@@ -60,7 +70,7 @@ module Pgbus
           refresh_wildcard_queues
 
           break if @lifecycle.stopped?
-          break if @lifecycle.draining? && @pool.queue_length.zero?
+          break if @lifecycle.draining? && @pool.idle?
 
           claim_and_execute if @lifecycle.can_process?
           @stat_buffer&.flush_if_due
@@ -97,7 +107,7 @@ module Pgbus
       def claim_and_execute
         poll_interval = effective_polling_interval
 
-        idle = @pool.max_length - @pool.queue_length
+        idle = @pool.available_capacity
         return @wake_signal.wait(timeout: poll_interval) if idle <= 0
 
         if config.prefetch_limit
@@ -332,7 +342,7 @@ module Pgbus
           kind: "worker",
           metadata: {
             queues: queues, threads: threads, pid: ::Process.pid,
-            consumer_priority: @consumer_priority
+            execution_mode: @execution_mode, consumer_priority: @consumer_priority
           },
           on_beat: -> { @rate_counter.snapshot! }
         )

data/lib/pgbus/version.rb

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

data/lib/pgbus/web/stream_app.rb

@@ -62,11 +62,15 @@ module Pgbus
         cursor = parse_cursor(env, request)
         return bad_request("invalid cursor: #{cursor}") if cursor.is_a?(String)
 
-        return unsupported_server unless env["rack.hijack?"]
-
         return over_capacity if streamer.registry.size >= config.streams_max_connections
 
-        hijack_and_register(env, stream_name: stream_name, since_id: cursor, context: context)
+        if config.streams_falcon_streaming_body
+          streaming_body_response(stream_name: stream_name, since_id: cursor, context: context)
+        elsif env["rack.hijack?"]
+          hijack_and_register(env, stream_name: stream_name, since_id: cursor, context: context)
+        else
+          unsupported_server
+        end
       rescue StandardError => e
         logger.error { "[Pgbus::StreamApp] #{e.class}: #{e.message}" }
         server_error
@@ -127,6 +131,38 @@ module Pgbus
         [-1, {}, []]
       end
 
+      def streaming_body_response(stream_name:, since_id:, context: nil)
+        require "protocol/http/body/writable" unless defined?(::Protocol::HTTP::Body::Writable)
+        require_relative "streamer/falcon_connection" unless defined?(Pgbus::Web::Streamer::FalconConnection)
+
+        body = ::Protocol::HTTP::Body::Writable.new
+
+        body.write(Pgbus::Streams::Envelope.retry_directive(2_000))
+        body.write(Pgbus::Streams::Envelope.comment(
+                     "pgbus stream open since_id=#{since_id} stream=#{stream_name}"
+                   ))
+
+        connection = Pgbus::Web::Streamer::FalconConnection.new(
+          id: SecureRandom.hex(8),
+          stream_name: stream_name,
+          body: body,
+          since_id: since_id,
+          write_deadline_ms: config.streams_write_deadline_ms,
+          context: context
+        )
+        streamer.register(connection)
+
+        [200, sse_headers, body]
+      end
+
+      def sse_headers
+        {
+          "content-type" => "text/event-stream",
+          "cache-control" => "no-cache, no-transform",
+          "x-accel-buffering" => "no"
+        }
+      end
+
       def write_headers(io, stream_name:, since_id:)
         io.write(Pgbus::Streams::Envelope.http_response_headers)
         io.write(Pgbus::Streams::Envelope.retry_directive(2_000))

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

@@ -70,6 +70,10 @@ module Pgbus
           result
         end
 
+        def write_sentinel(bytes)
+          @writer.write(self, bytes, deadline_ms: @write_deadline_ms)
+        end
+
         def idle_for
           monotonic - @last_write_at
         end

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Web
+    module Streamer
+      # Connection adapter for Falcon's native streaming body path.
+      # Wraps a Protocol::HTTP::Body::Writable instead of a raw IO socket.
+      #
+      # Satisfies the same duck-type interface as Connection so the
+      # Dispatcher, Heartbeat, and Instance can use either type
+      # interchangeably. Key difference: no IoWriter — writes go
+      # 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
+
+        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
+          @write_deadline_ms = write_deadline_ms
+          @mutex = Mutex.new
+          @dead = false
+          @closed = false
+          @created_at = monotonic
+          @last_write_at = @created_at
+          @context = context
+        end
+
+        def enqueue(envelopes)
+          written = []
+          envelopes.each do |envelope|
+            next if envelope.msg_id <= @last_msg_id_sent
+
+            bytes = Pgbus::Streams::Envelope.message(
+              id: envelope.msg_id,
+              event: "turbo-stream",
+              data: envelope.payload
+            )
+
+            result = write_to_body(bytes)
+            if result == :ok
+              @last_msg_id_sent = envelope.msg_id
+              @last_write_at = monotonic
+              written << envelope
+            else
+              mark_dead!
+              break
+            end
+          end
+          written
+        end
+
+        def write_comment(text)
+          bytes = Pgbus::Streams::Envelope.comment(text)
+          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)
+        end
+
+        def close
+          @mutex.synchronize do
+            return if @closed
+
+            @closed = true
+            mark_dead!
+            @body.close_write
+          end
+        rescue StandardError => e
+          Pgbus.logger&.debug { "[Pgbus::Streamer::FalconConnection] close failed: #{e.class}: #{e.message}" }
+        end
+
+        def idle_for
+          monotonic - @last_write_at
+        end
+
+        def dead?
+          @dead || @body.closed?
+        end
+
+        def mark_dead!
+          @dead = true
+        end
+
+        private
+
+        def write_to_body(bytes)
+          @mutex.synchronize do
+            return :closed if @dead || @body.closed?
+
+            @body.write(bytes)
+            :ok
+          end
+        rescue Protocol::HTTP::Body::Writable::Closed
+          :closed
+        end
+
+        def monotonic
+          ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+        end
+      end
+    end
+  end
+end

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

@@ -134,14 +134,9 @@ module Pgbus
             event: "pgbus:shutdown",
             data: '{"reason":"worker_restart"}'
           )
-          deadline_ms = @config.streams_write_deadline_ms
 
           @registry.each_connection do |connection|
-            # IoWriter holds the connection's mutex, so this write is
-            # serialised against any write the dispatcher/heartbeat
-            # might still be performing if their stop hadn't fully
-            # returned yet.
-            safely { IoWriter.write(connection, sentinel_bytes, deadline_ms: deadline_ms) }
+            safely { connection.write_sentinel(sentinel_bytes) }
             safely { connection.close }
           end
         end

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

@@ -113,6 +113,14 @@ module Pgbus
               @conn.wait_for_notify(timeout_s) do |channel, _pid, _payload|
                 handle_notify(channel)
               end || run_health_check
+            rescue IOError => e
+              # #stop closes the PG connection to interrupt
+              # wait_for_notify, which raises IOError ("stream closed
+              # in another thread"). This is expected — exit cleanly.
+              break unless @running
+
+              @logger.warn { "[Pgbus::Streamer::Listener] IO error (#{e.class}: #{e.message}) — reconnecting" }
+              reconnect!
             rescue PG::Error => e
               break unless @running
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.6.3
+  version: 0.6.5
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -256,6 +256,9 @@ files:
 - lib/pgbus/event_bus/publisher.rb
 - lib/pgbus/event_bus/registry.rb
 - lib/pgbus/event_bus/subscriber.rb
+- lib/pgbus/execution_pools.rb
+- lib/pgbus/execution_pools/async_pool.rb
+- lib/pgbus/execution_pools/thread_pool.rb
 - lib/pgbus/failed_event_recorder.rb
 - lib/pgbus/generators/config_converter.rb
 - lib/pgbus/generators/database_target_detector.rb
@@ -303,6 +306,7 @@ files:
 - lib/pgbus/web/stream_app.rb
 - lib/pgbus/web/streamer.rb
 - lib/pgbus/web/streamer/connection.rb
+- lib/pgbus/web/streamer/falcon_connection.rb
 - lib/pgbus/web/streamer/heartbeat.rb
 - lib/pgbus/web/streamer/instance.rb
 - lib/pgbus/web/streamer/io_writer.rb