raptor 0.11.0 → 0.13.0

data/sig/generated/raptor/binder.rbs

@@ -1,30 +1,9 @@
 # Generated from lib/raptor/binder.rb with RBS::Inline
 
 module Raptor
-  # Manages binding to network addresses and creating listening sockets.
-  #
-  # Binder handles parsing URI bind specifications, creating TCP, Unix, and SSL
-  # server sockets, and managing socket options for optimal performance. It
-  # supports binding to multiple addresses simultaneously.
-  #
-  # @example TCP binding
-  #   binder = Binder.new(["tcp://0.0.0.0:3000", "tcp://[::1]:3000"])
-  #   puts binder.addresses #=> ["0.0.0.0:3000", "[::1]:3000"]
-  #   binder.close
-  #
-  # @example Unix socket binding
-  #   binder = Binder.new(["unix:///tmp/raptor.sock"])
-  #   puts binder.addresses #=> ["/tmp/raptor.sock"]
-  #   binder.close
-  #
-  # @example SSL binding
-  #   binder = Binder.new(["ssl://0.0.0.0:443?cert=/path/to.crt&key=/path/to.key"])
-  #   puts binder.addresses #=> ["ssl://0.0.0.0:443"]
-  #   binder.close
-  #
-  # @example Localhost binding
-  #   binder = Binder.new(["tcp://localhost:8080"])
-  #   # Binds to both IPv4 and IPv6 loopback addresses
+  # Binds `tcp://`, `unix://`, and `ssl://` URIs to listening sockets and
+  # holds them for the server. Reconstructs listeners from inherited file
+  # descriptors when provided (systemd socket activation, hot restart).
   class Binder
     SOCKET_BACKLOG: ::Integer
 
@@ -33,11 +12,8 @@ module Raptor
       def initialize: (String scheme) -> void
     end
 
-    # Wraps a TCPServer with an SSL context for accepting SSL connections.
-    #
-    # Holds both the underlying TCP server and the SSL context together so
-    # the server thread can accept a TCP connection and then perform the SSL
-    # handshake in a single coordinated step.
+    # Pairs a TCPServer with the SSL context to use for accepted
+    # connections.
     class SslListener < Data
       attr_reader tcp_server(): untyped
 
@@ -61,28 +37,24 @@ module Raptor
 
     @bind_uris: Array[String]
 
-    # Array of bind URIs.
+    # Returns the array of bind URIs.
     #
-    # @return [Array<String>] the bind URIs
+    # @return [Array<String>]
     attr_reader bind_uris: untyped
 
-    # Kernel listen() queue depth for TCP/SSL listeners.
+    # Returns the kernel `listen()` queue depth for TCP/SSL listeners.
     #
-    # @return [Integer] the socket backlog
+    # @return [Integer]
     attr_reader socket_backlog: untyped
 
-    # Array of listening sockets.
+    # Returns the array of listening sockets.
     #
-    # @return [Array<TCPServer, UNIXServer, SslListener>] the server sockets
+    # @return [Array<TCPServer, UNIXServer, SslListener>]
     attr_reader listeners: untyped
 
-    # Creates a new Binder with the specified bind URIs.
-    #
-    # Parses the provided bind URIs and creates listening sockets for each one.
-    # Supports tcp://, unix://, and ssl:// schemes. Localhost is expanded to
-    # all available loopback addresses (both IPv4 and IPv6). When `inherited_fds`
-    # supplies file descriptors for a URI, the listener is reconstructed from
-    # those FDs instead of binding fresh.
+    # Creates a new Binder and binds each URI. `localhost` expands to both
+    # IPv4 and IPv6 loopback; when `inherited_fds` supplies file descriptors
+    # for a URI the listener is rebuilt from those instead of binding fresh.
     #
     # @param bind_uris [Array<String>] array of URI strings to bind to
     # @param socket_backlog [Integer] kernel listen() queue depth for TCP/SSL listeners
@@ -90,31 +62,21 @@ module Raptor
     # @return [void]
     # @raise [UnknownBindSchemeError] if a URI has an unsupported scheme
     #
-    # @example
-    #   binder = Binder.new(["tcp://0.0.0.0:3000", "unix:///tmp/raptor.sock"])
-    #
     # @rbs (Array[String] bind_uris, ?socket_backlog: Integer, ?inherited_fds: Hash[String, Array[Integer]]) -> void
     def initialize: (Array[String] bind_uris, ?socket_backlog: Integer, ?inherited_fds: Hash[String, Array[Integer]]) -> void
 
-    # Returns the bound addresses as strings.
-    #
-    # TCP listeners are returned as "host:port", Unix listeners as the socket
-    # path, and SSL listeners as "ssl://host:port".
+    # Returns the bound addresses as strings: TCP as `host:port`, Unix as
+    # the socket path, SSL as `ssl://host:port`.
     #
-    # @return [Array<String>] address strings for each bound listener
-    #
-    # @example
-    #   binder.addresses #=> ["127.0.0.1:3000", "/tmp/raptor.sock", "ssl://0.0.0.0:443"]
+    # @return [Array<String>]
     #
     # @rbs () -> Array[String]
     def addresses: () -> Array[String]
 
-    # Returns the port number of the first TCP or SSL listener.
-    #
-    # Used to populate SERVER_PORT in the Rack environment. Returns 0
-    # if no TCP or SSL listener is configured (e.g., Unix socket only).
+    # Returns the port of the first TCP or SSL listener, or 0 when none
+    # is configured.
     #
-    # @return [Integer] the port number, or 0 if no TCP listener exists
+    # @return [Integer]
     #
     # @rbs () -> Integer
     def server_port: () -> Integer
@@ -126,9 +88,7 @@ module Raptor
     # @rbs () -> void
     def close: () -> void
 
-    # Returns the file descriptors of every listener, grouped by the bind URI
-    # they were created from. The result is the payload to hand to a successor
-    # process via the `inherited_fds:` constructor argument.
+    # Returns the file descriptors of every listener, grouped by bind URI.
     #
     # @return [Hash{String => Array<Integer>}]
     #
@@ -154,25 +114,25 @@ module Raptor
     # @rbs () -> void
     def parse: () -> void
 
-    # Creates fresh listeners for the given bind URI.
+    # Creates fresh listeners for the given URI.
     #
-    # @param bind_uri [String] the URI to bind
+    # @param uri [URI] the parsed bind URI
     # @return [Array<TCPServer, UNIXServer, SslListener>]
     # @raise [UnknownBindSchemeError] if the URI scheme is not supported
     #
-    # @rbs (String bind_uri) -> Array[TCPServer | UNIXServer | SslListener]
-    def create_listeners: (String bind_uri) -> Array[TCPServer | UNIXServer | SslListener]
+    # @rbs (URI::Generic uri) -> Array[TCPServer | UNIXServer | SslListener]
+    def create_listeners: (URI::Generic uri) -> Array[TCPServer | UNIXServer | SslListener]
 
-    # Reconstructs listeners for the given bind URI from inherited file
+    # Reconstructs listeners for the given URI from inherited file
     # descriptors.
     #
-    # @param bind_uri [String] the URI the FDs were bound to
+    # @param uri [URI] the parsed bind URI the FDs were bound to
     # @param filenos [Array<Integer>] file descriptors to wrap
     # @return [Array<TCPServer, UNIXServer, SslListener>]
     # @raise [UnknownBindSchemeError] if the URI scheme is not supported
     #
-    # @rbs (String bind_uri, Array[Integer] filenos) -> Array[TCPServer | UNIXServer | SslListener]
-    def restore_listeners: (String bind_uri, Array[Integer] filenos) -> Array[TCPServer | UNIXServer | SslListener]
+    # @rbs (URI::Generic uri, Array[Integer] filenos) -> Array[TCPServer | UNIXServer | SslListener]
+    def restore_listeners: (URI::Generic uri, Array[Integer] filenos) -> Array[TCPServer | UNIXServer | SslListener]
 
     # Creates TCP server sockets for the given host and port.
     #
@@ -183,11 +143,9 @@ module Raptor
     # @rbs (String? host, Integer? port) -> Array[TCPServer]
     def create_tcp_listeners: (String? host, Integer? port) -> Array[TCPServer]
 
-    # Creates a Unix domain server socket at the given path.
-    #
-    # Removes stale socket files left by crashed processes (when the socket
-    # is not currently in use). Registers an at_exit hook to clean up the
-    # socket file on normal process exit.
+    # Creates a Unix domain server socket at the given path. Removes stale
+    # socket files left by crashed processes, and cleans the file up on
+    # the master's clean exit.
     #
     # @param path [String] filesystem path for the Unix socket
     # @return [Array<UNIXServer>] array containing the created Unix server socket
@@ -206,15 +164,11 @@ module Raptor
     # @rbs (String path) -> void
     def register_unix_socket_cleanup: (String path) -> void
 
-    # Creates SSL server sockets for the given host, port, and SSL parameters.
-    #
-    # Wraps each TCP listener with an SSL context to produce SslListener objects.
-    # The ssl_params hash must include "cert" and "key" entries pointing to the
-    # certificate and private key files respectively.
+    # Creates SSL server sockets for the given host and port.
     #
     # @param host [String, nil] hostname or IP address to bind to
     # @param port [Integer, nil] port number to bind to
-    # @param ssl_params [Hash<String, String>] SSL options ("cert" and "key" paths)
+    # @param ssl_params [Hash<String, String>] SSL options (`cert` and `key` file paths)
     # @return [Array<SslListener>] array containing the created SSL listener(s)
     #
     # @rbs (String? host, Integer? port, Hash[String, String] ssl_params) -> Array[SslListener]

data/sig/generated/raptor/cli.rbs

@@ -24,11 +24,9 @@ module Raptor
 
     DEFAULT_CONFIG_PATHS: untyped
 
-    # Loads a configuration file and returns the hash it evaluates to.
-    #
-    # The file is evaluated at the top level so constants like `Raptor::*` resolve
-    # the same as in a regular Ruby script. The final expression must be a Hash
-    # of cluster options (the same keys accepted by {Raptor::Cluster#initialize}).
+    # Loads a Ruby config file and returns the options hash it evaluates
+    # to. Evaluated at the top level so `Raptor::*` constants resolve the
+    # same as in a regular script.
     #
     # @param path [String] path to a Ruby file that evaluates to a Hash
     # @return [Hash{Symbol => untyped}] cluster options
@@ -40,9 +38,6 @@ module Raptor
     # Returns the first existing path in {DEFAULT_CONFIG_PATHS} resolved
     # against `root`, or nil if none exist.
     #
-    # Used to pick up a project-local config file when no `-c`/`--config`
-    # flag was supplied.
-    #
     # @param root [String] directory to resolve the default paths against
     # @return [String, nil] the config path, or nil if no default file exists
     #
@@ -55,22 +50,14 @@ module Raptor
 
     @parser: OptionParser
 
-    # Creates a new CLI instance and parses command-line arguments.
-    #
-    # Parses the provided command-line arguments and configures the server
-    # options accordingly. A rackup file can be provided as the first
-    # positional argument (defaults to config.ru).
+    # Creates a new CLI instance from `argv`. A rackup file may be given
+    # as the first positional argument; every other value is parsed as a
+    # flag.
     #
     # @param argv [Array<String>] command-line arguments to parse
     # @return [void]
     # @raise [OptionParser::ParseError] if invalid options are provided
     #
-    # @example With rackup file
-    #   cli = CLI.new(["my_app.ru", "-w", "4"])
-    #
-    # @example With options only
-    #   cli = CLI.new(["-t", "8", "-r", "2"])
-    #
     # @rbs (Array[String] argv) -> void
     def initialize: (Array[String] argv) -> void
 
@@ -90,12 +77,9 @@ module Raptor
     # @rbs () -> void
     def run_stats: () -> void
 
-    # Scans argv for a `-c`/`--config` flag and returns the configured path.
-    #
-    # The pre-scan runs before the main OptionParser pass so the config file
-    # can be applied as a base layer that CLI args then override. All four
-    # OptionParser-accepted forms (`-c PATH`, `-cPATH`, `--config PATH`,
-    # `--config=PATH`) are recognized.
+    # Returns the path from a `-c`/`--config` flag in `argv`, recognising
+    # all four OptionParser-accepted forms (`-c PATH`, `-cPATH`,
+    # `--config PATH`, `--config=PATH`).
     #
     # @param argv [Array<String>] command-line arguments to scan
     # @return [String, nil] the config path, or nil if no flag was supplied

data/sig/generated/raptor/cluster.rbs

@@ -1,38 +1,14 @@
 # Generated from lib/raptor/cluster.rb with RBS::Inline
 
 module Raptor
-  # Multi-process web server cluster with advanced concurrency architecture.
-  #
-  # Cluster manages multiple worker processes, each running a complete server
-  # 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 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
-  # 2. Reactor manages I/O multiplexing and provides backlog metrics for load control
-  # 3. Ractor pool handles CPU-intensive HTTP parsing in parallel
-  # 4. Thread pool processes Rack applications and handles response writing
-  # 5. Natural load balancing occurs through backpressure-based acceptance control
-  #
-  # @example Basic usage
-  #   options = {
-  #     workers: 4, ractors: 2, threads: 8,
-  #     binds: ["tcp://0.0.0.0:3000"],
-  #     rackup: "config.ru",
-  #     connection: { first_data_timeout: 30, chunk_data_timeout: 10 }
-  #   }
-  #   Cluster.run(options)
+  # Forks and supervises worker processes. Handles graceful shutdown on
+  # `INT` and `TERM`, phased restart on `USR1`, hot restart on `USR2`,
+  # and (on Linux) refork on `URG`. Restarts workers that exit
+  # unexpectedly or stop checking in.
   class Cluster
     INHERITED_FDS_ENV: ::String
 
-    # Convenience method to create and run a cluster with the given options.
+    # Creates and runs a cluster with the given options.
     #
     # @param options [Hash] cluster configuration options
     # @return [void]
@@ -40,57 +16,85 @@ module Raptor
     # @rbs (Hash[Symbol, untyped] options) -> void
     def self.run: (Hash[Symbol, untyped] options) -> void
 
-    @http2_options: Hash[Symbol, untyped]
+    @bpf_active: bool
 
-    @worker_boot_timeout: Integer
+    @server_port: Integer
 
-    @worker_timeout: Integer
+    @binder: Binder
 
-    @worker_drain_timeout: Integer
+    @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
 
-    @worker_shutdown_timeout: Integer
+    @launch_argv: Array[String]?
 
-    @stats_file: String?
+    @launch_command: String?
 
-    @pid_file: String?
+    @access_log_io: IO?
 
-    @stdout_file: String?
+    @access_log_file: String?
 
     @stderr_file: String?
 
-    @access_log_file: String?
+    @stdout_file: String?
 
-    @access_log_io: IO?
+    @pid_file: String?
 
-    @launch_command: String?
+    @stats_file: String?
 
-    @launch_argv: Array[String]?
+    @before_refork: Array[Proc]
 
-    @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
+    @before_worker_shutdown: Array[Proc]
 
-    @binder: Binder
+    @before_worker_boot: Array[Proc]
 
-    @server_port: Integer
+    @before_fork: Array[Proc]
 
-    @app: untyped
+    @worker_shutdown_timeout: Integer
 
-    @shutdown: bool
+    @worker_drain_timeout: Integer
 
-    @workers: Hash[Integer, Integer]
+    @worker_timeout: Integer
 
-    @timed_out: Set[Integer]
+    @worker_boot_timeout: Integer
 
-    @stats: Stats
+    @resp_w: IO?
 
-    @phase: Integer
+    @resp_r: IO?
 
-    @phased_restart_requested: bool
+    @fork_w: IO?
 
-    @phased_restarting: bool
+    @fork_r: IO?
+
+    @seed_vacated_index: Integer?
+
+    @seed_ready: bool
+
+    @seed_pid: Integer?
+
+    @refork_threshold_idx: Integer
+
+    @refork_requested: bool
+
+    @refork_thresholds: Array[Integer]
 
     @hot_restart_requested: bool
 
-    @bpf_active: bool
+    @phased_restarting: bool
+
+    @phased_restart_requested: bool
+
+    @phase: Integer
+
+    @stats: Stats
+
+    @timed_out: Set[Integer]
+
+    @workers: Hash[Integer, Integer]
+
+    @shutdown: bool
+
+    @app: untyped
+
+    @http2_options: Hash[Symbol, untyped]
 
     @http1_options: Hash[Symbol, untyped]
 
@@ -106,11 +110,7 @@ module Raptor
 
     @drain_accept_queue: bool
 
-    # Creates a new Cluster with the specified configuration.
-    #
-    # Initializes the cluster with worker, ractor, and thread counts,
-    # sets up network binding, loads the Rack application, and prepares
-    # for multi-process operation.
+    # Creates a new Cluster with the given options.
     #
     # @param options [Hash] cluster configuration options
     # @option options [Array<String>] :binds array of bind URIs
@@ -130,6 +130,11 @@ module Raptor
     # @option options [Integer] :worker_timeout seconds to wait for a booted worker to check in before killing it
     # @option options [Integer] :worker_drain_timeout seconds a worker waits for in-flight requests during shutdown before force-killing app threads
     # @option options [Integer] :worker_shutdown_timeout seconds to wait for graceful worker exit before force-killing
+    # @option options [Integer, Array<Integer>, nil] :refork_after request-count threshold(s) at which a warm worker is promoted to a fork source for phased refork; nil or 0 disables. Requires `PR_SET_CHILD_SUBREAPER` (Linux)
+    # @option options [Array<Proc>] :before_fork procs called in the master before every worker fork
+    # @option options [Array<Proc>] :before_worker_boot procs called in each worker before it begins serving
+    # @option options [Array<Proc>] :before_worker_shutdown procs called in each worker before its graceful shutdown
+    # @option options [Array<Proc>] :before_refork procs called in a worker before it transitions to a seed
     # @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 [String, nil] :stdout_file path to redirect stdout to, reopened on SIGHUP, or nil to disable
@@ -143,20 +148,7 @@ module Raptor
     # @rbs (Hash[Symbol, untyped] options) -> void
     def initialize: (Hash[Symbol, untyped] options) -> void
 
-    # Starts the multi-process cluster and manages worker processes.
-    #
-    # Forks the configured number of worker processes and monitors them,
-    # restarting any that exit unexpectedly or stop checking in. Handles
-    # graceful shutdown via INT or TERM signals, phased restart via USR1,
-    # and hot 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 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)
+    # Runs the cluster until a graceful shutdown is signalled.
     #
     # @return [void]
     #
@@ -166,7 +158,8 @@ module Raptor
     # Returns stats for all worker processes.
     #
     # @return [Array<Hash>] array of per-worker stat hashes, each containing
-    #   :pid, :requests, :backlog, :started_at, :last_checkin, and :booted
+    #   :pid, :index, :phase, :requests, :backlog, :busy_threads,
+    #   :thread_capacity, :started_at, :last_checkin, and :booted
     #
     # @rbs () -> Array[Hash[Symbol, untyped]]
     def stats: () -> Array[Hash[Symbol, untyped]]
@@ -175,8 +168,7 @@ module Raptor
 
     # Returns the inherited-FDs hash for a systemd socket-activation handoff,
     # pairing each bind URI with the FD systemd passed at the same index.
-    # The activation is skipped (with a warning) when the FD count doesn't
-    # match the number of bind URIs.
+    # Returns an empty hash when the FD count doesn't match the bind count.
     #
     # @param bind_uris [Array<String>] the configured bind URIs
     # @param filenos [Array<Integer>] file descriptors passed by systemd
@@ -185,8 +177,18 @@ module Raptor
     # @rbs (Array[String] bind_uris, Array[Integer] filenos) -> Hash[String, Array[Integer]]
     def pair_systemd_fds: (Array[String] bind_uris, Array[Integer] filenos) -> Hash[String, Array[Integer]]
 
-    # Forks a new worker process and registers it at the given index.
-    # The worker inherits the cluster's current phase.
+    # Normalises the `refork_after` option into a sorted array of positive
+    # thresholds. Accepts nil, 0, an Integer, or an Array<Integer>; anything
+    # else falls back to an empty array (feature disabled).
+    #
+    # @param value [Integer, Array<Integer>, nil] the raw option value
+    # @return [Array<Integer>]
+    #
+    # @rbs (untyped value) -> Array[Integer]
+    def normalize_refork_thresholds: (untyped value) -> Array[Integer]
+
+    # Forks a new worker process and registers it at the given index,
+    # forking from the seed when one is active and off the master otherwise.
     #
     # @param index [Integer] slot index for this worker in the stats region
     # @return [void]
@@ -194,16 +196,87 @@ module Raptor
     # @rbs (Integer index) -> void
     def spawn_worker: (Integer index) -> void
 
+    # Asks the seed to fork a new worker at the given index, returning the
+    # child pid, or nil when the seed doesn't respond in time.
+    #
+    # @param index [Integer] slot index for the new worker
+    # @return [Integer, nil] the forked worker's pid, or nil on failure
+    #
+    # @rbs (Integer index) -> Integer?
+    def spawn_worker_via_seed: (Integer index) -> Integer?
+
+    # Checks whether a process with the given pid is currently alive.
+    #
+    # @param pid [Integer] the pid to probe
+    # @return [Boolean] true if the process exists
+    #
+    # @rbs (Integer pid) -> bool
+    def pid_alive?: (Integer pid) -> bool
+
     # Reaps any worker processes that have exited, respawning each one
     # unless the cluster is shutting down.
     #
-    # @return [Symbol] :no_children when there are no remaining children, otherwise :reaped
+    # @return [Symbol] :no_children when nothing is left to supervise, otherwise :reaped
     #
     # @rbs () -> Symbol
     def reap_workers: () -> Symbol
 
-    # Stops every worker, escalating from TERM to KILL if any fail to
-    # exit within `worker_shutdown_timeout`.
+    # Records a reaped pid, respawning its worker slot unless the cluster
+    # is shutting down. Clears the seed reference when the seed exits.
+    #
+    # @param pid [Integer] the reaped pid
+    # @param status [Process::Status] the exit status
+    # @return [void]
+    #
+    # @rbs (Integer pid, Process::Status status) -> void
+    def reap_pid: (Integer pid, Process::Status status) -> void
+
+    # Promotes the most-experienced worker to a seed and starts a phased
+    # refork when the next `refork_after` threshold is crossed or a manual
+    # refork was requested via `SIGURG`.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def check_refork_trigger: () -> void
+
+    # Picks the most-experienced booted worker in the current phase,
+    # returning its slot index and its request count. Returns nil when
+    # no worker qualifies.
+    #
+    # @return [Array<Integer>, nil]
+    #
+    # @rbs () -> Array[Integer]?
+    def pick_refork_candidate: () -> Array[Integer]?
+
+    # Retires the current seed and promotes the given worker into its place,
+    # queueing a phased refork for the remaining workers.
+    #
+    # @param index [Integer] slot index of the worker to promote
+    # @return [void]
+    #
+    # @rbs (Integer index) -> void
+    def promote_worker_to_seed: (Integer index) -> void
+
+    # Terminates the currently-active seed process, if any, and waits for
+    # it to exit. Its seed-forked workers stay attached to the master and
+    # keep serving.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def retire_current_seed: () -> void
+
+    # Records the seed's readiness when its ready marker has arrived.
+    # Non-blocking.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def poll_seed_ready: () -> void
+
+    # Stops every worker (and the seed if one is active), escalating
+    # from TERM to KILL if any fail to exit within `worker_shutdown_timeout`.
     #
     # @return [void]
     #
@@ -229,6 +302,23 @@ module Raptor
     # @rbs () -> void
     def perform_phased_restart: () -> void
 
+    # Blocks until the freshly-promoted seed has signalled readiness,
+    # or times out and clears the seed reference. No-op when no seed is
+    # being promoted.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def wait_for_seed_ready: () -> void
+
+    # Spawns a replacement worker for the slot the seed vacated when
+    # it was promoted, returning the slot index it filled.
+    #
+    # @return [Integer, nil] the filled slot index, or nil if none was vacated
+    #
+    # @rbs () -> Integer?
+    def fill_vacated_seed_slot: () -> Integer?
+
     # Re-execs the master process with a fresh boot of the same Raptor
     # invocation, handing the new master its listening sockets so accepted
     # connections continue to be served across the swap.
@@ -238,11 +328,10 @@ module Raptor
     # @rbs () -> void
     def perform_hot_restart: () -> void
 
-    # Runs the full server stack inside a worker process.
-    #
-    # Sets up and coordinates the reactor, server, ractor pool, thread pool,
-    # and stats thread, running until a shutdown signal is received or a
-    # critical component fails.
+    # Runs a worker process's full server stack until a shutdown signal is
+    # received or a critical component fails. On `SIGURG` the worker drains
+    # and transitions into a seed loop that forks replacement workers on
+    # master's request.
     #
     # @param index [Integer] slot index for this worker in the stats region
     # @param phase [Integer] the cluster phase this worker was forked at
@@ -251,6 +340,15 @@ module Raptor
     # @rbs (Integer index, Integer phase) -> void
     def run_worker: (Integer index, Integer phase) -> void
 
+    # Runs the seed's fork loop, forking a replacement worker for each
+    # slot index the master asks for.
+    #
+    # @param index [Integer] the seed's original slot index
+    # @return [void]
+    #
+    # @rbs (Integer index) -> void
+    def run_seed_loop: (Integer index) -> void
+
     # Shuts down the worker's application thread pool, force-killing the
     # underlying threads if in-flight requests have not finished within
     # `worker_drain_timeout` seconds.

data/sig/generated/raptor/http.rbs

@@ -51,6 +51,16 @@ module Raptor
     # @rbs (TCPSocket socket, Array[String] strings, ?timeout: Integer) -> void
     def self.socket_writev: (TCPSocket socket, Array[String] strings, ?timeout: Integer) -> void
 
+    # Returns a Ractor-safe proc that routes each pipeline task to the
+    # HTTP/1.x or HTTP/2 handler based on the state hash's `:protocol` key.
+    #
+    # @param env_template [Hash] the Rack env template to seed each HTTP/1.x request with
+    # @param max_body_size [Integer, nil] byte limit for HTTP/1.x request bodies, or nil for no limit
+    # @return [Proc]
+    #
+    # @rbs (Hash[String, untyped] env_template, Integer? max_body_size) -> ^(Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+    def self.parser_worker: (Hash[String, untyped] env_template, Integer? max_body_size) -> ^(Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+
     # Writes a Common Log Format entry to `io`. Write failures are silently
     # ignored.
     #