raptor 0.4.0 → 0.5.0

data/lib/raptor/log.rb

@@ -0,0 +1,55 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Raptor
+  # Shared logging helpers. Every line is prefixed with
+  # `[Raptor <pid>|<ractor>|<thread>]` so output is identifiable
+  # and traceable to its source in a mixed log stream.
+  #
+  module Log
+    # Writes an informational message to stdout.
+    #
+    # @param message [String] the message to log
+    # @return [void]
+    #
+    # @rbs (String message) -> void
+    def self.info(message)
+      Kernel.puts "#{prefix} #{message}"
+    end
+
+    # Writes a warning to stderr.
+    #
+    # @param message [String] the message to log
+    # @return [void]
+    #
+    # @rbs (String message) -> void
+    def self.warn(message)
+      Kernel.warn "#{prefix} #{message}"
+    end
+
+    # Logs a rescued exception to stderr. The full message (class,
+    # message, backtrace) is written on subsequent unprefixed lines.
+    #
+    # @param error [Exception] the rescued exception
+    # @return [void]
+    #
+    # @rbs (Exception error) -> void
+    def self.rescued_error(error)
+      Kernel.warn "#{prefix} rescued:"
+      Kernel.warn error.full_message
+    end
+
+    # Builds the log line prefix from the current process, ractor,
+    # and thread. Unnamed ractors and threads are reported as `main`.
+    #
+    # @return [String] the prefix
+    #
+    # @rbs () -> String
+    def self.prefix
+      ractor = Ractor.current.name || "main"
+      thread = Thread.current.name || "main"
+      "[Raptor #{Process.pid}|#{ractor}|#{thread}]"
+    end
+    private_class_method :prefix
+  end
+end

data/lib/raptor/reactor.rb

@@ -9,12 +9,12 @@ module Raptor
   #
   # Reactor uses NIO selectors for efficient I/O multiplexing and implements
   # client timeouts using a red-black tree for O(log n) timeout management.
-  # It coordinates between thread pools for blocking operations and ractor
-  # pools for CPU-intensive HTTP parsing, and provides backlog metrics
-  # that the server uses for backpressure control to prevent overload.
+  # It coordinates between ractor pools for CPU-intensive HTTP parsing and
+  # thread pools for blocking operations, and provides backlog metrics that
+  # the server uses for backpressure control to prevent overload.
   #
   # @example
-  #   reactor = Reactor.new(thread_pool, ractor_pool, client_options: {
+  #   reactor = Reactor.new(ractor_pool, thread_pool, client_options: {
   #     first_data_timeout: 30,
   #     chunk_data_timeout: 10
   #   })
@@ -24,38 +24,38 @@ module Raptor
   #   reactor.shutdown
   #
   class Reactor
-    # Red-black tree node representing a client connection with timeout tracking.
-    #
-    # TimeoutClient extends RedBlackTree::Node to enable efficient timeout
-    # management using the tree's ordering properties.
+    # A client connection node ordered by absolute expiry time so the
+    # soonest-to-expire is always at the tree's minimum.
     #
     class TimeoutClient < RedBlackTree::Node
       # @rbs attr_accessor timeout_at: Float
       attr_accessor :timeout_at
 
-      # Returns the client data stored in this timeout node.
+      # Semantic alias for the inherited `data` slot.
       #
-      # @return [Hash] the client connection state data
+      # @return [Hash] the client connection state
       #
       # @rbs () -> Hash[Symbol, untyped]
       def client_data
         data
       end
 
-      # Calculates remaining timeout duration from the current time.
+      # Returns seconds until expiry, clamped to 0 so an already-expired
+      # client doesn't push the next selector wait into the future.
       #
       # @param now [Float] current monotonic timestamp
-      # @return [Float] remaining timeout in seconds, minimum 0
+      # @return [Float] seconds until expiry, never negative
       #
       # @rbs (Float now) -> Float
       def timeout(now)
         [timeout_at - now, 0].max
       end
 
-      # Compares timeout nodes by their timeout_at values for tree ordering.
+      # Orders nodes by `timeout_at` so the tree minimum is the next
+      # client to expire.
       #
       # @param other [TimeoutClient] another timeout client to compare
-      # @return [Integer] -1, 0, or 1 for ordering
+      # @return [Integer] -1, 0, or 1
       #
       # @rbs (TimeoutClient other) -> Integer
       def <=>(other)
@@ -80,18 +80,18 @@ module Raptor
 
     # Creates a new Reactor instance.
     #
-    # @param thread_pool [AtomicThreadPool] thread pool for application processing
     # @param ractor_pool [RactorPool] ractor pool for HTTP parsing
+    # @param thread_pool [AtomicThreadPool] thread pool for application processing
     # @param client_options [Hash] timeout configuration options
     # @option client_options [Integer] :first_data_timeout timeout for initial data
     # @option client_options [Integer] :chunk_data_timeout timeout for subsequent chunks
     # @option client_options [Integer] :persistent_data_timeout timeout for keep-alive connections
     # @return [void]
     #
-    # @rbs (untyped thread_pool, untyped ractor_pool, client_options: Hash[Symbol, Integer]) -> void
-    def initialize(thread_pool, ractor_pool, client_options:)
-      @thread_pool = thread_pool
+    # @rbs (untyped ractor_pool, untyped thread_pool, client_options: Hash[Symbol, Integer]) -> void
+    def initialize(ractor_pool, thread_pool, client_options:)
       @ractor_pool = ractor_pool
+      @thread_pool = thread_pool
       @client_options = client_options
 
       @selector = NIO::Selector.new
@@ -149,8 +149,7 @@ module Raptor
               register(@queue.pop)
             end
           rescue => error
-            warn "#{Thread.current.name} rescued:"
-            warn error.full_message
+            Log.rescued_error(error)
           end
         end
 
@@ -200,13 +199,12 @@ module Raptor
       socket.close
     end
 
-    # Removes a client connection from the reactor.
-    #
-    # Called when an HTTP request is complete and ready for application
-    # processing. Triggers server accept re-enabling if system capacity allows.
+    # Drops the reactor's references to a client whose parsed request
+    # has been handed off to the thread pool. The socket itself is kept
+    # open so the worker can write the response.
     #
     # @param id [Integer] unique client identifier
-    # @return [TCPSocket, nil] the removed socket, if found
+    # @return [TCPSocket, nil] the socket associated with `id`, if any
     #
     # @rbs (Integer id) -> TCPSocket?
     def remove(id)
@@ -321,10 +319,8 @@ module Raptor
       socket.close rescue nil
     end
 
-    # Initiates reactor shutdown.
-    #
-    # Closes the registration queue and wakes up the selector to begin
-    # graceful shutdown process.
+    # Closes the registration queue and wakes the selector so the
+    # event loop drains pending work and exits.
     #
     # @return [void]
     #

data/lib/raptor/request.rb

@@ -11,13 +11,10 @@ require "rack"
 require_relative "raptor_http"
 
 module Raptor
-  # Handles HTTP request processing and Rack application integration.
-  #
-  # Request manages the HTTP parsing pipeline using Ractors and coordinates
-  # with the reactor for connection state management. It bridges between the
-  # low-level HTTP parsing and high-level Rack application interface, handling
-  # both incomplete requests (that need more data) and complete requests
-  # (ready for application processing).
+  # Parses HTTP/1.x requests and dispatches them to the Rack
+  # application. Coordinates with the Ractor pool for parsing and
+  # with the reactor for requests that need more data before they
+  # can be handled.
   #
   class Request
     BODY_BUFFER_THRESHOLD = 256 * 1024
@@ -27,7 +24,6 @@ module Raptor
     KEEPALIVE_READ_TIMEOUT = 0.001
     MAX_KEEPALIVE_REQUESTS = 100
 
-    HTTP_SCHEME = "http"
     HTTP_10 = "HTTP/1.0"
     HTTP_11 = "HTTP/1.1"
     STATUS_LINE_CACHE_10 = Hash.new do |h, status|
@@ -94,10 +90,8 @@ module Raptor
       [decoded, :incomplete]
     end
 
-    # Writes a string to the socket, retrying on partial writes and flow control blocks.
-    #
-    # Uses write_nonblock with `WRITE_TIMEOUT` to avoid blocking the thread
-    # indefinitely on slow clients.
+    # Writes `string` in full, retrying on partial writes. Bounded by
+    # `WRITE_TIMEOUT` so a slow client can't pin the writing thread.
     #
     # @param socket [TCPSocket] the socket to write to
     # @param string [String] the data to write
@@ -330,8 +324,8 @@ module Raptor
       else
         socket = reactor.remove(parsed_request[:id])
         request_count = (parsed_request[:request_count] || 0) + 1
-        remote_addr = parsed_request[:remote_addr] || "127.0.0.1"
-        url_scheme = parsed_request[:url_scheme] || HTTP_SCHEME
+        remote_addr = parsed_request[:remote_addr] || Server::DEFAULT_REMOTE_ADDR
+        url_scheme = parsed_request[:url_scheme] || Server::HTTP_SCHEME
 
         thread_pool << proc do
           process_client(
@@ -607,7 +601,7 @@ module Raptor
     # @return [Hash] fully populated Rack environment hash
     #
     # @rbs (Hash[String, untyped] env, Hash[Symbol, untyped] parse_data, String? body, TCPSocket socket, ?remote_addr: String, ?url_scheme: String) -> Hash[String, untyped]
-    def build_rack_env(env, parse_data, body, socket, remote_addr: "127.0.0.1", url_scheme: HTTP_SCHEME)
+    def build_rack_env(env, parse_data, body, socket, remote_addr: Server::DEFAULT_REMOTE_ADDR, url_scheme: Server::HTTP_SCHEME)
       env[Rack::RACK_VERSION] = Rack::VERSION
       env[Rack::RACK_URL_SCHEME] = url_scheme
       env[Rack::RACK_INPUT] = build_rack_input(body)
@@ -647,7 +641,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
 

data/lib/raptor/server.rb

@@ -6,26 +6,20 @@ require "socket"
 require "atomic-ruby/atomic_boolean"
 
 module Raptor
-  # High-performance HTTP server that accepts connections and dispatches them.
+  # Accepts client connections and dispatches them into the request
+  # pipeline. Skips acceptance when the reactor backlog is high so an
+  # overloaded process leaves connections for peers that can absorb
+  # them (via shared `SO_REUSEPORT` listeners).
   #
-  # Server manages the main accept loop, handling incoming client connections from
-  # bound sockets. It uses IO.select for efficient polling and implements automatic
-  # load balancing by checking reactor backlog before accepting connections,
-  # providing natural backpressure based on system capacity.
-  #
-  # Supports TCP, Unix domain, and SSL listeners transparently. TCP_NODELAY is
-  # applied only to TCP sockets, and SSL handshakes are offloaded to the thread
-  # pool so a slow client cannot block the server thread.
-  #
-  # For HTTP/1.1 connections the first request is parsed inline on the server
-  # thread and dispatched directly to the thread pool, falling back to the
-  # reactor only when more data is needed. For HTTP/2 connections (negotiated
-  # via ALPN) the server sends initial SETTINGS and registers the connection
-  # with the reactor for frame processing through the ractor pool.
+  # Supports TCP, Unix, and SSL listeners. SSL handshakes are offloaded
+  # to the thread pool so a slow client can't pin the server thread.
+  # For HTTP/1.1 the first request is parsed inline and dispatched
+  # straight to the thread pool; HTTP/2 (negotiated via ALPN) is
+  # registered with the reactor for frame processing.
   #
   # @example
   #   binder = Binder.new(["tcp://0.0.0.0:3000"])
-  #   reactor = Reactor.new(thread_pool, ractor_pool, client_options: {})
+  #   reactor = Reactor.new(ractor_pool, thread_pool, client_options: {})
   #   request = Request.new(app, 3000)
   #   server = Server.new(binder, reactor, thread_pool, request, client_options: { first_data_timeout: 30 })
   #   server.run
@@ -35,8 +29,12 @@ module Raptor
   class Server
     HTTP_SCHEME = "http"
     HTTPS_SCHEME = "https"
+
     H2_PROTOCOL = "h2"
 
+    DEFAULT_REMOTE_ADDR = "127.0.0.1"
+    DEFAULT_SERVER_NAME = "localhost"
+
     # @rbs @binder: Binder
     # @rbs @reactor: Reactor
     # @rbs @thread_pool: AtomicThreadPool
@@ -133,7 +131,7 @@ module Raptor
         tcp_client.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
         remote_addr = tcp_client.remote_address.ip_address
       else
-        remote_addr = "127.0.0.1"
+        remote_addr = DEFAULT_REMOTE_ADDR
       end
 
       if listener.is_a?(Binder::SslListener)
@@ -218,7 +216,7 @@ module Raptor
 
         retry
       rescue OpenSSL::SSL::SSLError => error
-        warn "SSL handshake failed: #{error.message}"
+        Log.rescued_error(error)
         ssl_socket.close rescue nil
         false
       end
@@ -244,7 +242,7 @@ module Raptor
       end
       return true if ready
 
-      warn "SSL handshake timed out"
+      Log.warn "SSL handshake timed out"
       ssl_socket.close rescue nil
       false
     end

data/lib/raptor/stats.rb

@@ -12,26 +12,27 @@ module Raptor
   # assigned a fixed-size slot in the shared region.
   #
   # Binary layout per slot (native byte order):
-  #   pid           uint32    4 bytes
-  #   requests      uint64    8 bytes
-  #   backlog       uint32    4 bytes
-  #   started_at    float64   8 bytes
-  #   last_checkin  float64   8 bytes
-  #   booted        uint8     1 byte
-  #                          33 bytes total
+  #   pid               uint32    4 bytes
+  #   index             uint32    4 bytes
+  #   phase             uint32    4 bytes
+  #   requests          uint64    8 bytes
+  #   backlog           uint32    4 bytes
+  #   busy_threads      uint32    4 bytes
+  #   thread_capacity   uint32    4 bytes
+  #   started_at        float64   8 bytes
+  #   last_checkin      float64   8 bytes
+  #   booted            uint8     1 byte
+  #                              49 bytes total
   #
   class Stats
-    SLOT_FORMAT = "LQLddC"
-    SLOT_SIZE = [0, 0, 0, 0.0, 0.0, 0].pack(SLOT_FORMAT).bytesize
+    SLOT_FORMAT = "LLLQLLLddC"
+    SLOT_SIZE = [0, 0, 0, 0, 0, 0, 0, 0.0, 0.0, 0].pack(SLOT_FORMAT).bytesize
 
     # @rbs @num_workers: Integer
     # @rbs @mmap: untyped
 
-    # Creates a new Stats instance backed by anonymous shared memory.
-    #
-    # Allocates a MAP_ANON | MAP_SHARED mmap region large enough for
-    # num_workers slots. Must be called before forking so that all
-    # worker processes share the same backing memory.
+    # Allocates the shared mmap region. Must be called before forking
+    # workers so the mapping is inherited by every child process.
     #
     # @param num_workers [Integer] number of worker slots to allocate
     # @return [void]
@@ -44,24 +45,27 @@ module Raptor
 
     # Writes stats for a worker slot into shared memory.
     #
-    # @param index [Integer] slot index to write into
+    # @param index [Integer] slot index to write into; also written into the slot itself
     # @param pid [Integer] worker process ID
+    # @param phase [Integer] cluster phase this worker was forked at
     # @param requests [Integer] total requests handled by this worker
     # @param backlog [Integer] current queue depth
+    # @param busy_threads [Integer] worker threads currently processing requests
+    # @param thread_capacity [Integer] worker threads configured for this worker
     # @param started_at [Float] process start time as a Unix timestamp
     # @param last_checkin [Float] time of last stats write as a Unix timestamp
     # @param booted [Boolean] whether the worker has finished starting
     # @return [void]
     #
-    # @rbs (Integer index, pid: Integer, requests: Integer, backlog: Integer, started_at: Float, last_checkin: Float, booted: bool) -> void
-    def write(index, pid:, requests:, backlog:, started_at:, last_checkin:, booted:)
-      data = [pid, requests, backlog, started_at, last_checkin, booted ? 1 : 0].pack(SLOT_FORMAT)
+    # @rbs (Integer index, pid: Integer, phase: Integer, requests: Integer, backlog: Integer, busy_threads: Integer, thread_capacity: Integer, started_at: Float, last_checkin: Float, booted: bool) -> void
+    def write(index, pid:, phase:, requests:, backlog:, busy_threads:, thread_capacity:, started_at:, last_checkin:, booted:)
+      data = [pid, index, phase, requests, backlog, busy_threads, thread_capacity, started_at, last_checkin, booted ? 1 : 0].pack(SLOT_FORMAT)
       @mmap.semlock { @mmap[index * SLOT_SIZE, SLOT_SIZE] = data }
     end
 
     # Returns stats for all worker slots.
     #
-    # @return [Array<Hash>] per-worker stat hashes with :pid, :requests, :backlog, :started_at, :last_checkin, and :booted
+    # @return [Array<Hash>] per-worker stat hashes with :pid, :index, :phase, :requests, :backlog, :busy_threads, :thread_capacity, :started_at, :last_checkin, and :booted
     #
     # @rbs () -> Array[Hash[Symbol, untyped]]
     def all
@@ -81,14 +85,14 @@ module Raptor
 
     # Reads stats for a worker slot from shared memory.
     #
-    # @param index [Integer] slot index to read from
-    # @return [Hash] stat hash with :pid, :requests, :backlog, :started_at, :last_checkin, and :booted
+    # @param slot [Integer] slot offset to read from
+    # @return [Hash] stat hash with :pid, :index, :phase, :requests, :backlog, :busy_threads, :thread_capacity, :started_at, :last_checkin, and :booted
     #
-    # @rbs (Integer index) -> Hash[Symbol, untyped]
-    def read(index)
-      data = @mmap[index * SLOT_SIZE, SLOT_SIZE]
-      pid, requests, backlog, started_at, last_checkin, booted = data.unpack(SLOT_FORMAT)
-      { pid:, requests:, backlog:, started_at:, last_checkin:, booted: booted == 1 }
+    # @rbs (Integer slot) -> Hash[Symbol, untyped]
+    def read(slot)
+      data = @mmap[slot * SLOT_SIZE, SLOT_SIZE]
+      pid, index, phase, requests, backlog, busy_threads, thread_capacity, started_at, last_checkin, booted = data.unpack(SLOT_FORMAT)
+      { pid:, index:, phase:, requests:, backlog:, busy_threads:, thread_capacity:, started_at:, last_checkin:, booted: booted == 1 }
     end
   end
 end

data/lib/raptor/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Raptor
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/sig/generated/raptor/cli.rbs

@@ -5,7 +5,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

data/sig/generated/raptor/cluster.rbs

@@ -4,14 +4,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
@@ -22,7 +23,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 }
@@ -37,53 +38,66 @@ module Raptor
     # @rbs (Hash[Symbol, untyped] options) -> void
     def self.run: (Hash[Symbol, untyped] options) -> void
 
-    @phased_restarting: bool
+    @thread_count: Integer
 
-    @phased_restart_requested: bool
+    @client_options: Hash[Symbol, Integer]
 
-    @stats: Stats
+    @worker_timeout: Integer
 
-    @workers: Hash[Integer, Integer]
+    @worker_boot_timeout: Integer
 
-    @shutdown: bool
+    @worker_shutdown_timeout: Integer
 
-    @app: untyped
+    @stats_file: String?
 
-    @server_port: Integer
+    @pid_file: String?
+
+    @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
 
     @binder: Binder
 
-    @pid_file: String?
+    @server_port: Integer
 
-    @stats_file: String?
+    @app: untyped
 
-    @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
+    @shutdown: bool
 
-    @client_options: Hash[Symbol, Integer]
+    @workers: Hash[Integer, Integer]
 
-    @worker_count: Integer
+    @timed_out: Set[Integer]
+
+    @stats: Stats
+
+    @phase: Integer
+
+    @phased_restart_requested: bool
+
+    @phased_restarting: bool
 
     @ractor_count: Integer
 
-    @thread_count: Integer
+    @worker_count: Integer
 
     # 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
@@ -92,15 +106,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)
     #
@@ -120,6 +134,7 @@ 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]
@@ -135,6 +150,25 @@ module Raptor
     # @rbs () -> Symbol
     def reap_workers: () -> Symbol
 
+    # Stops every worker, escalating from TERM to KILL if any fail to
+    # exit within `worker_shutdown_timeout`.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def stop_workers: () -> void
+
+    # 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: () -> void
+
     # Replaces each worker process one at a time, waiting for the new
     # worker to boot before moving on to the next. Triggered by SIGUSR2.
     #
@@ -150,10 +184,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: (Integer index) -> void
+    # @rbs (Integer index, Integer phase) -> void
+    def run_worker: (Integer index, Integer phase) -> void
 
     # Returns a human-readable description of how a process exited.
     #
@@ -170,11 +205,8 @@ module Raptor
     # @rbs () -> void
     def shutdown: () -> void
 
-    # 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]
     #

data/sig/generated/raptor/http2.rbs

@@ -39,7 +39,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: ::Float