raptor 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9d82dc0869e270278088d312d03a6ed914e494da5fb6b7bf6e41c03257ddf41
-  data.tar.gz: c113ab336b5ad9e5e72095e79af4702b5adb0efb46117ba43b6879fe2e4a728c
+  metadata.gz: c20a98b3c581180e2b9ea2e9cdd23223f4f43438b94852b0b19b8e1b659c751d
+  data.tar.gz: bc98ee07befe42ad9c2e30b4645aeac4a1fb369cc598e360a336b591a56d74b1
 SHA512:
-  metadata.gz: 365e09dbfcc7cbb265b8ac6569a66e66a0629ecfb4fd176164cb4c55b6f0223ef05f3e17f3318f7ec6cd58be94396996885b232c496e46620f42049ca9a1fe84
-  data.tar.gz: d6d2b9b18cd0da790c2f13fce8994f799bac41e94270f9c69f4b57241f6931d98a8ef81573e8257d1766dfde0a63807d2f06cf57fa4a44ef8f754533b733aeff
+  metadata.gz: b065827d528422e5476827c2c01b792cd9b4a83ba38484283c33f05459a744a28a7ce88bfbe396c80fe07209893662350f205dd823a469503be208428f0cc784
+  data.tar.gz: '02583bea8f88760256318b3714b9f95cb7936b12ec0d9bb54a120108a734f965a9b85d4e556e6b8e73d7c731a43be6ddf96bd4871228f35d7bf2903df255cc84'

data/.mise.toml

@@ -0,0 +1,2 @@
+[tools]
+ruby = "latest"

data/Brewfile

@@ -0,0 +1,2 @@
+brew "hey"
+brew "nghttp2"

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+## [0.5.0] - 2026-05-31
+
+- Apply the default `stats_file` in the Rack handler
+- Add `phase` to per-worker stats
+- Force-kill workers that fail to exit within `--worker-shutdown-timeout` after shutdown is signalled
+- Kill workers that fail to check in within `--worker-timeout` or `--worker-boot-timeout`
+- Add `index`, `busy_threads`, and `thread_capacity` to per-worker stats
+
 ## [0.4.0] - 2026-05-29
 
 - Load `raptor.rb` or `config/raptor.rb` by default when no config path is supplied

data/README.md

@@ -29,23 +29,23 @@ run proc { |_env| [200, { "content-type" => "text/plain" }, ["Hello, World!"]] }
 ```
 
 ```
-> bundle exec raptor -t 3 -w 4 hello_world.ru
-Raptor Cluster initializing:
-├─ Version: 0.4.0
-├─ Ruby Version: ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +YJIT +PRISM [arm64-darwin23]
-├─ Master PID: 26456
-│  └─ 4 worker processes
-│     ├─ 1 server thread
-│     ├─ 1 reactor thread
-│     ├─ 1 pipeline ractor
-│     ├─ 1 pipeline collector thread
-│     ├─ 3 worker threads
-│     └─ 1 stats thread
-└─ Listening on 0.0.0.0:9292
-[26459] Worker 0 booted
-[26460] Worker 1 booted
-[26461] Worker 2 booted
-[26462] Worker 3 booted
+> bundle exec raptor -w 4 -t 3 hello_world.ru
+[Raptor 91348|main|main] Cluster initializing:
+[Raptor 91348|main|main] ├─ Version: 0.5.0
+[Raptor 91348|main|main] ├─ Ruby Version: ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +YJIT +PRISM [arm64-darwin23]
+[Raptor 91348|main|main] ├─ Master PID: 91348
+[Raptor 91348|main|main] │  └─ 4 worker processes
+[Raptor 91348|main|main] │     ├─ 1 server thread
+[Raptor 91348|main|main] │     ├─ 1 reactor thread
+[Raptor 91348|main|main] │     ├─ 1 pipeline ractor
+[Raptor 91348|main|main] │     ├─ 1 pipeline collector thread
+[Raptor 91348|main|main] │     ├─ 3 worker threads
+[Raptor 91348|main|main] │     └─ 1 stats thread
+[Raptor 91348|main|main] └─ Listening on 0.0.0.0:9292
+[Raptor 91350|main|main] Worker 0 booted
+[Raptor 91351|main|main] Worker 1 booted
+[Raptor 91352|main|main] Worker 2 booted
+[Raptor 91353|main|main] Worker 3 booted
 ```
 
 ```
@@ -62,15 +62,18 @@ Also works with `rackup` and `rails server`:
 
 ## (Micro) Benchmarks
 
-Raptor 0.4.0 vs Puma 8.0.1:
+Raptor 0.5.0 vs Puma 8.0.2:
 
-| Protocol              | Raptor       | Puma         |
-| --------------------- | ------------ | ------------ |
-| HTTP/1.1              | ~20k req/s   | ~21k req/s   |
-| HTTP/1.1 (keep-alive) | ~60k req/s   | ~45k req/s   |
-| HTTP/2                | ~23k req/s   | N/A          |
+| Protocol              | Raptor      | Puma        |
+| --------------------- | ----------- | ----------- |
+| HTTP/1.1              | 20.1k req/s | 20k req/s   |
+| HTTP/1.1 (keep-alive) | 61.4k req/s | 39.1k req/s |
+| HTTP/2                | 22.8k req/s | N/A         |
 
-> Ruby 4.0.5 +YJIT, macOS Apple Silicon. 4 workers, 3 threads, 12 concurrent connections.
+> ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +YJIT +PRISM [arm64-darwin23]
+> 4 workers, 3 threads, 12 concurrent connections
+
+See [bin/benchmark](bin/benchmark) for more details.
 
 ## Development
 

data/lib/rackup/handler/raptor.rb

@@ -42,9 +42,9 @@ module Rackup
         {
           "Host=HOST"   => "Hostname to listen on (default: #{DEFAULT_OPTIONS[:Host]})",
           "Port=PORT"   => "Port to listen on (default: #{DEFAULT_OPTIONS[:Port]})",
-          "Threads=NUM" => "Number of threads per worker (default: 3)",
-          "Ractors=NUM" => "Number of pipeline ractors per worker (default: 1)",
           "Workers=NUM" => "Number of worker processes (default: nprocessors)",
+          "Ractors=NUM" => "Number of pipeline ractors per worker (default: 1)",
+          "Threads=NUM" => "Number of threads per worker (default: 3)",
           "Config=PATH" => "Load additional configuration from PATH"
         }
       end
@@ -72,27 +72,25 @@ module Rackup
         config_path = options[:Config] || ::Raptor::CLI.default_config_path
         config = config_path ? ::Raptor::CLI.load_config_file(config_path) : {}
 
-        binds = if options[:Host] || options[:Port]
-          host = options[:Host] || defaults[:Host]
-          port = options[:Port] || defaults[:Port]
-          ["tcp://#{host}:#{port}"]
-        else
-          config[:binds] || ["tcp://#{defaults[:Host]}:#{defaults[:Port]}"]
-        end
-
         result = {
-          app: app,
-          binds: binds,
-          threads: (options[:Threads] || config[:threads] || cli_defaults[:threads]).to_i,
-          ractors: (options[:Ractors] || config[:ractors] || cli_defaults[:ractors]).to_i,
+          binds: if options[:Host] || options[:Port]
+            ["tcp://#{options[:Host] || defaults[:Host]}:#{options[:Port] || defaults[:Port]}"]
+          else
+            config[:binds] || ["tcp://#{defaults[:Host]}:#{defaults[:Port]}"]
+          end,
           workers: (options[:Workers] || config[:workers] || Etc.nprocessors).to_i,
-          client: cli_defaults[:client].merge(config[:client] || {})
+          ractors: (options[:Ractors] || config[:ractors] || cli_defaults[:ractors]).to_i,
+          threads: (options[:Threads] || config[:threads] || cli_defaults[:threads]).to_i,
+          app: app
         }
-
-        [:rackup, :on_error, :stats_file, :pid_file].each do |key|
-          result[key] = config[key] if config.key?(key)
-        end
-
+        result[:rackup] = config[:rackup] if config.key?(:rackup)
+        result[:client] = cli_defaults[:client].merge(config[:client] || {})
+        result[:worker_timeout] = (config[:worker_timeout] || cli_defaults[:worker_timeout]).to_i
+        result[:worker_boot_timeout] = (config[:worker_boot_timeout] || cli_defaults[:worker_boot_timeout]).to_i
+        result[:worker_shutdown_timeout] = (config[:worker_shutdown_timeout] || cli_defaults[:worker_shutdown_timeout]).to_i
+        result[:stats_file] = config.key?(:stats_file) ? config[:stats_file] : cli_defaults[:stats_file]
+        result[:pid_file] = config[:pid_file] if config.key?(:pid_file)
+        result[:on_error] = config[:on_error] if config.key?(:on_error)
         result
       end
       private_class_method :build_cluster_options

data/lib/raptor/cli.rb

@@ -12,7 +12,7 @@ module Raptor
   #
   # CLI parses command-line arguments and starts the server cluster with the
   # specified configuration options. It supports configuring the number of
-  # workers, threads, ractors, bind addresses, and various client timeout
+  # workers, ractors, threads, bind addresses, and various client timeout
   # settings.
   #
   # @example Basic usage
@@ -28,9 +28,9 @@ module Raptor
 
     DEFAULT_OPTIONS = {
       binds: ["tcp://0.0.0.0:9292"].freeze,
-      threads: 3,
-      ractors: 1,
       workers: DEFAULT_WORKER_COUNT,
+      ractors: 1,
+      threads: 3,
       rackup: "config.ru",
       client: {
         first_data_timeout: 30,
@@ -39,6 +39,9 @@ module Raptor
         max_body_size: nil,
         body_spool_threshold: 1024 * 1024,
       },
+      worker_timeout: 60,
+      worker_boot_timeout: 60,
+      worker_shutdown_timeout: 30,
       stats_file: "tmp/raptor.json",
       pid_file: nil,
     }.freeze
@@ -143,11 +146,12 @@ module Raptor
       data = JSON.parse(File.read(stats_file), symbolize_names: true)
 
       puts "Master PID: #{data[:master_pid]}"
-      data[:workers].each_with_index do |worker, index|
+      data[:workers].each do |worker|
         status = worker[:booted] ? "booted" : "starting"
         last_checkin = Time.at(worker[:last_checkin]).strftime("%H:%M:%S")
-        puts "Worker #{index}: pid=#{worker[:pid]}, requests=#{worker[:requests]}, " \
-             "backlog=#{worker[:backlog]}, #{status}, last_checkin=#{last_checkin}"
+        puts "Worker #{worker[:index]} (phase #{worker[:phase]}): pid=#{worker[:pid]}, requests=#{worker[:requests]}, " \
+             "busy=#{worker[:busy_threads]}/#{worker[:thread_capacity]}, backlog=#{worker[:backlog]}, " \
+             "#{status}, last_checkin=#{last_checkin}"
       end
     end
 
@@ -215,16 +219,16 @@ module Raptor
           end
         end
 
-        opts.on("-t", "--threads NUM", Integer, "Number of threads (default: 3)") do |num|
-          @options[:threads] = num
+        opts.on("-w", "--workers NUM", Integer, "Number of worker processes (default: #{DEFAULT_WORKER_COUNT})") do |num|
+          @options[:workers] = num
         end
 
         opts.on("-r", "--ractors NUM", Integer, "Number of ractors (default: 1)") do |num|
           @options[:ractors] = num
         end
 
-        opts.on("-w", "--workers NUM", Integer, "Number of worker processes (default: #{DEFAULT_WORKER_COUNT})") do |num|
-          @options[:workers] = num
+        opts.on("-t", "--threads NUM", Integer, "Number of threads (default: 3)") do |num|
+          @options[:threads] = num
         end
 
         opts.on("--first-data-timeout SECONDS", Integer, "First data timeout in seconds (default: 30)") do |timeout|
@@ -247,6 +251,18 @@ module Raptor
           @options[:client][:body_spool_threshold] = bytes
         end
 
+        opts.on("--worker-timeout SECONDS", Integer, "Worker check-in timeout in seconds (default: 60)") do |timeout|
+          @options[:worker_timeout] = timeout
+        end
+
+        opts.on("--worker-boot-timeout SECONDS", Integer, "Worker boot timeout in seconds (default: 60)") do |timeout|
+          @options[:worker_boot_timeout] = timeout
+        end
+
+        opts.on("--worker-shutdown-timeout SECONDS", Integer, "Worker shutdown timeout in seconds (default: 30)") do |timeout|
+          @options[:worker_shutdown_timeout] = timeout
+        end
+
         opts.on("--stats-file PATH", String, "Stats file path (default: tmp/raptor.json)") do |path|
           @options[:stats_file] = path
         end

data/lib/raptor/cluster.rb

@@ -7,6 +7,7 @@ require "atomic-ruby/atomic_thread_pool"
 require "rack/builder"
 require "ractor-pool"
 
+require_relative "log"
 require_relative "binder"
 require_relative "server"
 require_relative "reactor"
@@ -18,14 +19,15 @@ module Raptor
   # Multi-process web server cluster with advanced concurrency architecture.
   #
   # Cluster manages multiple worker processes, each running a complete server
-  # stack including a reactor thread, server thread, ractor pool for HTTP
-  # parsing, and thread pool for application processing. It handles process
-  # forking, signal management, graceful shutdown, and automatic worker
-  # restart when a worker process unexpectedly exits.
+  # stack including a ractor pool for HTTP parsing, a thread pool for
+  # application processing, plus dedicated reactor and server threads. It
+  # handles process forking, signal management, graceful shutdown, and
+  # automatic worker restart when a worker process unexpectedly exits.
   #
   # The architecture provides horizontal scaling through processes while
-  # maintaining efficient I/O and CPU utilization within each process through
-  # the combination of NIO reactors, ractor-based parsing, and thread pools.
+  # maintaining efficient I/O and CPU utilization within each process
+  # through the combination of ractor-based parsing and thread pools on
+  # top of NIO reactors.
   #
   # Flow per worker process:
   # 1. Server continuously accepts connections but skips acceptance when backlog is high
@@ -36,7 +38,7 @@ module Raptor
   #
   # @example Basic usage
   #   options = {
-  #     threads: 8, ractors: 2, workers: 4,
+  #     workers: 4, ractors: 2, threads: 8,
   #     binds: ["tcp://0.0.0.0:3000"],
   #     rackup: "config.ru",
   #     client: { first_data_timeout: 30, chunk_data_timeout: 10 }
@@ -54,50 +56,61 @@ module Raptor
       new(options).run
     end
 
-    # @rbs @thread_count: Integer
-    # @rbs @ractor_count: Integer
     # @rbs @worker_count: Integer
+    # @rbs @ractor_count: Integer
+    # @rbs @thread_count: Integer
     # @rbs @client_options: Hash[Symbol, Integer]
-    # @rbs @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
+    # @rbs @worker_timeout: Integer
+    # @rbs @worker_boot_timeout: Integer
+    # @rbs @worker_shutdown_timeout: Integer
     # @rbs @stats_file: String?
     # @rbs @pid_file: String?
+    # @rbs @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
     # @rbs @binder: Binder
     # @rbs @server_port: Integer
     # @rbs @app: untyped
     # @rbs @shutdown: bool
     # @rbs @workers: Hash[Integer, Integer]
+    # @rbs @timed_out: Set[Integer]
     # @rbs @stats: Stats
+    # @rbs @phase: Integer
     # @rbs @phased_restart_requested: bool
     # @rbs @phased_restarting: bool
 
     # Creates a new Cluster with the specified configuration.
     #
-    # Initializes the cluster with thread, ractor, and worker counts,
+    # Initializes the cluster with worker, ractor, and thread counts,
     # sets up network binding, loads the Rack application, and prepares
     # for multi-process operation.
     #
     # @param options [Hash] cluster configuration options
-    # @option options [Integer] :threads number of threads per worker process
-    # @option options [Integer] :ractors number of ractors per worker process
-    # @option options [Integer] :workers number of worker processes
     # @option options [Array<String>] :binds array of bind URIs
+    # @option options [Integer] :workers number of worker processes
+    # @option options [Integer] :ractors number of ractors per worker process
+    # @option options [Integer] :threads number of threads per worker process
     # @option options [#call] :app pre-built Rack application
     # @option options [String] :rackup path to Rack configuration file
     # @option options [Hash] :client client configuration
-    # @option options [#call] :on_error callback invoked with (env, exception) when the Rack app raises
+    # @option options [Integer] :worker_timeout seconds to wait for a booted worker to check in before killing it
+    # @option options [Integer] :worker_boot_timeout seconds to wait for a worker to finish booting before killing it
+    # @option options [Integer] :worker_shutdown_timeout seconds to wait for graceful worker exit before force-killing
     # @option options [String, nil] :stats_file path to write per-worker stats JSON, or nil to disable
     # @option options [String, nil] :pid_file path to write the master PID to, or nil to disable
+    # @option options [#call] :on_error callback invoked with (env, exception) when the Rack app raises
     # @return [void]
     #
     # @rbs (Hash[Symbol, untyped] options) -> void
     def initialize(options)
-      @thread_count = options[:threads]
-      @ractor_count = options[:ractors]
       @worker_count = options[:workers]
+      @ractor_count = options[:ractors]
+      @thread_count = options[:threads]
       @client_options = options[:client]
-      @on_error = options[:on_error]
+      @worker_timeout = options[:worker_timeout]
+      @worker_boot_timeout = options[:worker_boot_timeout]
+      @worker_shutdown_timeout = options[:worker_shutdown_timeout]
       @stats_file = options[:stats_file]
       @pid_file = options[:pid_file]
+      @on_error = options[:on_error]
 
       @binder = Binder.new(options[:binds])
       @server_port = @binder.server_port
@@ -106,7 +119,9 @@ module Raptor
 
       @shutdown = false
       @workers = {}
+      @timed_out = Set.new
       @stats = Stats.new(@worker_count)
+      @phase = 0
       @phased_restart_requested = false
       @phased_restarting = false
     end
@@ -114,15 +129,15 @@ module Raptor
     # Starts the multi-process cluster and manages worker processes.
     #
     # Forks the configured number of worker processes and monitors them,
-    # automatically restarting any that exit unexpectedly. Handles graceful
-    # shutdown via INT or TERM signals, stats logging via USR1, and phased
-    # restart via USR2.
+    # restarting any that exit unexpectedly or stop checking in. Handles
+    # graceful shutdown via INT or TERM signals, stats logging via USR1,
+    # and phased restart via USR2.
     #
     # Each worker process includes:
     # - 1 server thread (continuously accepts connections with backpressure control)
     # - 1 reactor thread (I/O multiplexing, timeout handling, backlog monitoring)
-    # - N ractor workers (parallel HTTP parsing)
-    # - 1 ractor collector thread (coordinates parsing results)
+    # - N pipeline ractors (parallel HTTP parsing)
+    # - 1 pipeline collector thread (coordinates parsing results)
     # - M worker threads (Rack application processing and response writing)
     # - 1 stats thread (writes per-worker metrics to shared memory every second)
     #
@@ -151,12 +166,12 @@ module Raptor
         break if reap_workers == :no_children
 
         perform_phased_restart if @phased_restart_requested && !@phased_restarting
+        timeout_hung_workers
 
         sleep 0.1
       end
 
-      @workers.values.each { |pid| Process.kill("TERM", pid) rescue nil }
-      @workers.values.each { |pid| Process.wait(pid) rescue nil }
+      stop_workers
       stats_file_thread&.join
       File.delete(@stats_file) rescue nil if @stats_file
       File.delete(@pid_file) rescue nil if @pid_file
@@ -176,13 +191,14 @@ module Raptor
     private
 
     # Forks a new worker process and registers it at the given index.
+    # The worker inherits the cluster's current phase.
     #
     # @param index [Integer] slot index for this worker in the stats region
     # @return [void]
     #
     # @rbs (Integer index) -> void
     def spawn_worker(index)
-      pid = fork { run_worker(index) }
+      pid = fork { run_worker(index, @phase) }
       @workers[index] = pid
     end
 
@@ -199,9 +215,10 @@ module Raptor
 
         index = @workers.key(pid)
         @workers.delete(index)
+        @timed_out.delete(pid)
 
         unless @shutdown
-          warn "[#{Process.pid}] Restarting worker #{index} (#{pid}), #{exit_description(status)}"
+          Log.warn "Restarting worker #{index} (#{pid}), #{exit_description(status)}"
           spawn_worker(index)
         end
       end
@@ -209,6 +226,57 @@ module Raptor
       :no_children
     end
 
+    # Stops every worker, escalating from TERM to KILL if any fail to
+    # exit within `worker_shutdown_timeout`.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def stop_workers
+      @workers.values.each { |pid| Process.kill("TERM", pid) rescue nil }
+
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @worker_shutdown_timeout
+      until @workers.empty? || Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+        reap_workers
+        sleep 0.05
+      end
+      return if @workers.empty?
+
+      Log.warn "Force-killing #{@workers.size} worker(s) after #{@worker_shutdown_timeout}s"
+      @workers.values.each { |pid| Process.kill("KILL", pid) rescue nil }
+      @workers.values.each { |pid| Process.wait(pid) rescue nil }
+    end
+
+    # Kills workers that have stopped checking in. A booted worker that
+    # fails to update its stats slot within `worker_timeout` seconds is
+    # assumed to be hung (deadlocked app, runaway loop, blocked syscall);
+    # a worker still in startup is held to `worker_boot_timeout`. Killed
+    # workers are then restarted by `reap_workers`.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def timeout_hung_workers
+      now = Process.clock_gettime(Process::CLOCK_REALTIME)
+      stats = @stats.all
+
+      @workers.each do |index, pid|
+        next if @timed_out.include?(pid)
+
+        stat = stats[index]
+        next unless stat[:pid] == pid
+
+        timeout = stat[:booted] ? @worker_timeout : @worker_boot_timeout
+        elapsed = now - stat[:last_checkin]
+        next if elapsed <= timeout
+
+        action = stat[:booted] ? "check in" : "boot"
+        Log.warn "Killing worker #{index} (#{pid}), failed to #{action} within #{timeout}s"
+        Process.kill("KILL", pid) rescue nil
+        @timed_out << pid
+      end
+    end
+
     # Replaces each worker process one at a time, waiting for the new
     # worker to boot before moving on to the next. Triggered by SIGUSR2.
     #
@@ -218,7 +286,8 @@ module Raptor
     def perform_phased_restart
       @phased_restart_requested = false
       @phased_restarting = true
-      puts "[#{Process.pid}] Phased restart starting"
+      @phase += 1
+      Log.info "Phased restart starting"
 
       begin
         @workers.keys.sort.each do |index|
@@ -240,7 +309,7 @@ module Raptor
           end
         end
 
-        puts "[#{Process.pid}] Phased restart complete"
+        Log.info "Phased restart complete"
       ensure
         @phased_restarting = false
       end
@@ -253,10 +322,11 @@ module Raptor
     # critical component fails.
     #
     # @param index [Integer] slot index for this worker in the stats region
+    # @param phase [Integer] the cluster phase this worker was forked at
     # @return [void]
     #
-    # @rbs (Integer index) -> void
-    def run_worker(index)
+    # @rbs (Integer index, Integer phase) -> void
+    def run_worker(index, phase)
       shutdown_requested = false
       trap("INT") { shutdown_requested = true }
       trap("TERM") { shutdown_requested = true }
@@ -267,8 +337,11 @@ module Raptor
       @stats.write(
         index,
         pid: Process.pid,
+        phase: phase,
         requests: 0,
         backlog: 0,
+        busy_threads: 0,
+        thread_capacity: @thread_count,
         started_at:,
         last_checkin: started_at,
         booted: false
@@ -295,18 +368,17 @@ module Raptor
             request.handle_parsed_request(parsed_result, reactor, thread_pool)
           end
         rescue => error
-          warn "#{Thread.current.name} rescued:"
-          warn error.full_message
+          Log.rescued_error(error)
         end
       end
 
-      reactor = Reactor.new(thread_pool, ractor_pool, client_options: @client_options)
+      reactor = Reactor.new(ractor_pool, thread_pool, client_options: @client_options)
       reactor_thread = reactor.run
 
       server = Server.new(@binder, reactor, thread_pool, request, client_options: @client_options)
       server_thread = server.run
 
-      puts "[#{Process.pid}] Worker #{index} booted"
+      Log.info "Worker #{index} booted"
 
       stats_thread = Thread.new do
         Thread.current.name = "Raptor Stats"
@@ -315,8 +387,11 @@ module Raptor
           @stats.write(
             index,
             pid: Process.pid,
+            phase: phase,
             requests: request_count,
             backlog: reactor.backlog,
+            busy_threads: thread_pool.active_count,
+            thread_capacity: @thread_count,
             started_at:,
             last_checkin: Process.clock_gettime(Process::CLOCK_REALTIME),
             booted: true
@@ -370,28 +445,25 @@ module Raptor
       @shutdown = true
     end
 
-    # Logs cluster initialization details including architecture and bind addresses.
-    #
-    # Outputs a hierarchical view of the cluster configuration showing
-    # the master process, worker processes, and per-process thread/ractor
-    # allocation along with listening addresses.
+    # Prints the cluster's startup banner showing process structure
+    # and bind addresses.
     #
     # @return [void]
     #
     # @rbs () -> void
     def log_initialization
-      puts "Raptor Cluster initializing:"
-      puts "├─ Version: #{VERSION}"
-      puts "├─ Ruby Version: #{RUBY_DESCRIPTION}"
-      puts "├─ Master PID: #{Process.pid}"
-      puts "│  └─ #{@worker_count} worker process#{"es" if @worker_count > 1}"
-      puts "│     ├─ 1 server thread"
-      puts "│     ├─ 1 reactor thread"
-      puts "│     ├─ #{@ractor_count} pipeline ractor#{"s" if @ractor_count > 1}"
-      puts "│     ├─ 1 pipeline collector thread"
-      puts "│     ├─ #{@thread_count} worker thread#{"s" if @thread_count > 1}"
-      puts "│     └─ 1 stats thread"
-      puts "└─ Listening on #{@binder.addresses.join(", ")}"
+      Log.info "Cluster initializing:"
+      Log.info "├─ Version: #{VERSION}"
+      Log.info "├─ Ruby Version: #{RUBY_DESCRIPTION}"
+      Log.info "├─ Master PID: #{Process.pid}"
+      Log.info "│  └─ #{@worker_count} worker process#{"es" if @worker_count > 1}"
+      Log.info "│     ├─ 1 server thread"
+      Log.info "│     ├─ 1 reactor thread"
+      Log.info "│     ├─ #{@ractor_count} pipeline ractor#{"s" if @ractor_count > 1}"
+      Log.info "│     ├─ 1 pipeline collector thread"
+      Log.info "│     ├─ #{@thread_count} worker thread#{"s" if @thread_count > 1}"
+      Log.info "│     └─ 1 stats thread"
+      Log.info "└─ Listening on #{@binder.addresses.join(", ")}"
     end
 
     # Logs current stats for all workers to stdout.
@@ -402,11 +474,11 @@ module Raptor
     #
     # @rbs () -> void
     def log_stats
-      @stats.all.each_with_index do |stat, index|
+      @stats.all.each do |stat|
         status = stat[:booted] ? "booted" : "starting"
-        puts "Worker #{index}: pid=#{stat[:pid]}, requests=#{stat[:requests]}, " \
-             "backlog=#{stat[:backlog]}, #{status}, " \
-             "last_checkin=#{Time.at(stat[:last_checkin]).strftime("%H:%M:%S")}"
+        Log.info "Worker #{stat[:index]} (phase #{stat[:phase]}): pid=#{stat[:pid]}, requests=#{stat[:requests]}, " \
+                 "busy=#{stat[:busy_threads]}/#{stat[:thread_capacity]}, backlog=#{stat[:backlog]}, " \
+                 "#{status}, last_checkin=#{Time.at(stat[:last_checkin]).strftime("%H:%M:%S")}"
       end
     end
 

data/lib/raptor/http2.rb

@@ -81,7 +81,8 @@ module Raptor
     # outbound DATA frames respect RFC 7540 §5.2. Threads dispatching stream
     # responses call `acquire` to reserve send capacity; threads applying
     # inbound WINDOW_UPDATE or SETTINGS frames call the mutating methods to
-    # replenish it. State is held in a single `Atom` so updates use CAS.
+    # replenish it. The connection window and per-stream windows live in
+    # separate `Atom`s so the common fast path skips per-stream tracking.
     #
     class FlowControl
       ACQUIRE_POLL_INTERVAL = 0.001
@@ -529,7 +530,7 @@ module Raptor
 
       result[:completed_requests]&.each do |request|
         stream_id = request[:stream_id]
-        remote_addr = result[:remote_addr] || "127.0.0.1"
+        remote_addr = result[:remote_addr] || Server::DEFAULT_REMOTE_ADDR
 
         thread_pool << proc do
           dispatch_stream_request(
@@ -749,7 +750,7 @@ module Raptor
         env[Rack::SERVER_NAME] ||= host
         env[Rack::SERVER_PORT] ||= port || @server_port.to_s
       else
-        env[Rack::SERVER_NAME] ||= "localhost"
+        env[Rack::SERVER_NAME] ||= Server::DEFAULT_SERVER_NAME
         env[Rack::SERVER_PORT] ||= @server_port.to_s
       end
     end