raptor 0.10.0 → 0.12.0

data/lib/raptor/http1.rb

@@ -58,6 +58,22 @@ module Raptor
 
     ILLEGAL_HEADER_KEY_REGEX = /[\x00-\x20\(\)<>@,;:\\"\/\[\]\?=\{\}\x7F]/
     ILLEGAL_HEADER_VALUE_REGEX = /[\x00-\x08\x0A-\x1F]/
+    CHUNK_SIZE_REGEX = /\A[0-9A-Fa-f]+\z/
+
+    # Returns true when an HTTP/1.1 request lacks a valid `Host` header per
+    # RFC 9112 section 3.2, where a valid value is a non-empty single-value
+    # line.
+    #
+    # @param env [Hash] the Rack environment after header parsing
+    # @return [Boolean]
+    #
+    # @rbs (Hash[String, untyped] env) -> bool
+    def self.invalid_host?(env)
+      return false unless env[Rack::SERVER_PROTOCOL] == HTTP_11
+
+      http_host = env[Rack::HTTP_HOST]
+      !http_host || http_host.empty? || http_host.include?(",")
+    end
 
     # Returns true when the message framing shows a request-smuggling vector
     # per RFC 9112 section 6.3: a `Transfer-Encoding` where `chunked` is
@@ -89,9 +105,10 @@ module Raptor
     # Decodes a chunked transfer-encoded body buffer.
     #
     # Returns the decoded bytes and a state symbol: `:complete` when the
-    # terminating zero-length chunk was found, `:too_large` when the decoded
-    # size would exceed `max_size`, `:malformed` when chunk framing overhead
-    # exceeds `MAX_CHUNK_OVERHEAD`, or `:incomplete` otherwise.
+    # terminating zero-length chunk and trailer section were fully consumed,
+    # `:too_large` when the decoded size would exceed `max_size`, `:malformed`
+    # when a chunk-size line is not valid hex or chunk framing overhead exceeds
+    # `MAX_CHUNK_OVERHEAD`, or `:incomplete` otherwise.
     #
     # @param buffer [String] the raw body buffer to decode
     # @param max_size [Integer, nil] maximum decoded body size, or nil for unlimited
@@ -107,8 +124,24 @@ module Raptor
         crlf = buffer.index("\r\n", offset)
         return [decoded, :incomplete] unless crlf
 
-        chunk_size = buffer.byteslice(offset, crlf - offset).to_i(16)
-        return [decoded, :complete] if chunk_size == 0
+        size_line = buffer.byteslice(offset, crlf - offset)
+        semicolon = size_line.index(";")
+        size_part = semicolon ? size_line.byteslice(0, semicolon) : size_line
+        return [decoded, :malformed] unless size_part.match?(CHUNK_SIZE_REGEX)
+
+        chunk_size = size_part.to_i(16)
+
+        if chunk_size == 0
+          trailer_offset = crlf + 2
+          loop do
+            trailer_crlf = buffer.index("\r\n", trailer_offset)
+            return [decoded, :incomplete] unless trailer_crlf
+            return [decoded, :complete] if trailer_crlf == trailer_offset
+
+            trailer_offset = trailer_crlf + 2
+          end
+        end
+
         return [decoded, :too_large] if max_size && (decoded.bytesize + chunk_size) > max_size
 
         overhead += (crlf - offset) + 4
@@ -240,7 +273,8 @@ module Raptor
         buffer << socket.read_nonblock(socket.pending)
       end
 
-      parser = HttpParser.new
+      parser = (Thread.current[:raptor_http_parser] ||= HttpParser.new)
+      parser.reset
       env = @env_template.dup
       nread = begin
         parser.execute(env, buffer, 0)
@@ -254,7 +288,7 @@ module Raptor
       if !parser.finished?
         fallback_to_reactor(socket, id, buffer, env, parse_data, reactor, 0, remote_addr, url_scheme, persisted: false)
         return
-      elsif Http1.request_smuggling?(env)
+      elsif Http1.invalid_host?(env) || Http1.request_smuggling?(env)
         reject_malformed(socket)
         return
       elsif parser.has_body?
@@ -265,7 +299,7 @@ module Raptor
 
         body = buffer.byteslice(nread..-1) || ""
 
-        if env[HTTP_TRANSFER_ENCODING]&.include?(TRANSFER_ENCODING_CHUNKED)
+        if parser.chunked?
           body, chunked_state = Http1.decode_chunked(body, @max_body_size)
           case chunked_state
           when :complete
@@ -322,14 +356,14 @@ module Raptor
         parse_data[:parse_count] += 1
 
         message = if parser.finished?
-          if Raptor::Http1.request_smuggling?(env)
+          if Raptor::Http1.invalid_host?(env) || Raptor::Http1.request_smuggling?(env)
             data.merge(env: env, body: nil, parse_data: parse_data, complete: true, malformed: true)
           elsif parser.has_body?
             body_buffer = data[:buffer].byteslice(nread..-1) || ""
 
             if max_body_size && parser.content_length > max_body_size
               data.merge(env: env, body: nil, parse_data: parse_data, complete: true, too_large: true)
-            elsif env[HTTP_TRANSFER_ENCODING]&.include?(TRANSFER_ENCODING_CHUNKED)
+            elsif parser.chunked?
               decoded_body, chunked_state = Raptor::Http1.decode_chunked(body_buffer, max_body_size)
 
               case chunked_state
@@ -571,7 +605,8 @@ module Raptor
           buffer << socket.read_nonblock(socket.pending)
         end
 
-        parser = HttpParser.new
+        parser = (Thread.current[:raptor_http_parser] ||= HttpParser.new)
+        parser.reset
         env = @env_template.dup
         nread = begin
           parser.execute(env, buffer, 0)
@@ -588,8 +623,7 @@ module Raptor
         elsif parser.has_body?
           body = buffer.byteslice(nread..-1) || ""
 
-          chunked = env[HTTP_TRANSFER_ENCODING]&.include?(TRANSFER_ENCODING_CHUNKED)
-          if chunked || parser.content_length > body.bytesize
+          if parser.chunked? || parser.content_length > body.bytesize
             fallback_to_reactor(socket, id, buffer, env, parse_data, reactor, request_count, remote_addr, url_scheme)
             return
           end
@@ -597,7 +631,7 @@ module Raptor
 
         request_count += 1
 
-        if thread_pool.queue_size > 0
+        if thread_pool.queue_size >= thread_pool.size
           thread_pool << proc do
             process_client(
               socket,
@@ -718,8 +752,23 @@ module Raptor
         send_early_hints(socket, hints) rescue nil
       end
 
-      env[Rack::PATH_INFO] = env.delete(Rack::REQUEST_PATH) if env.key?(Rack::REQUEST_PATH)
-      env[Rack::PATH_INFO] = "" unless env.key?(Rack::PATH_INFO)
+      unless env.key?(Rack::PATH_INFO)
+        request_uri = env[Http::REQUEST_URI]
+        scheme_end = request_uri&.index("://")
+        if scheme_end
+          authority_end = request_uri.index("/", scheme_end + 3) || request_uri.bytesize
+          path_and_query = request_uri.byteslice(authority_end..-1) || ""
+          if query_delim = path_and_query.index("?")
+            env[Rack::PATH_INFO] = query_delim.zero? ? "/" : path_and_query.byteslice(0, query_delim)
+            env[Rack::QUERY_STRING] = path_and_query.byteslice(query_delim + 1..-1)
+          else
+            env[Rack::PATH_INFO] = path_and_query.empty? ? "/" : path_and_query
+          end
+        else
+          env[Rack::PATH_INFO] = ""
+        end
+      end
+
       if (content_length = parse_data[:content_length]).positive?
         env[Http::CONTENT_LENGTH] = content_length.to_s
       end
@@ -976,7 +1025,7 @@ module Raptor
     #
     # @rbs (TCPSocket socket, String response, Hash[String, String | Array[String]] headers, ^(TCPSocket) -> void response_hijack) -> void
     def write_hijacked_response(socket, response, headers, response_hijack)
-      response << format_headers(headers)
+      format_headers(response, headers)
       response << "\r\n"
       socket_write(socket, response)
       uncork_socket(socket)
@@ -1001,7 +1050,7 @@ module Raptor
         headers[Rack::CONTENT_LENGTH] = "0" unless headers.key?(Rack::CONTENT_LENGTH) || headers.key?(Rack::TRANSFER_ENCODING)
       end
 
-      response << format_headers(headers)
+      format_headers(response, headers)
       response << "\r\n"
       socket_write(socket, response)
     end
@@ -1023,7 +1072,7 @@ module Raptor
     # @rbs (TCPSocket socket, String response, Hash[String, String | Array[String]] headers, untyped body, String http_version) -> void
     def write_full_response(socket, response, headers, body, http_version)
       if body.respond_to?(:call)
-        response << format_headers(headers)
+        format_headers(response, headers)
         response << "\r\n"
         socket_write(socket, response)
         uncork_socket(socket)
@@ -1049,7 +1098,7 @@ module Raptor
         headers[Rack::TRANSFER_ENCODING] = TRANSFER_ENCODING_CHUNKED
       end
 
-      response << format_headers(headers)
+      format_headers(response, headers)
       response << "\r\n"
 
       if body.respond_to?(:to_path) && (path = body.to_path) && File.readable?(path)
@@ -1253,9 +1302,8 @@ module Raptor
     # @param headers [Hash] normalized response headers
     # @return [String] formatted header lines, each ending with CRLF
     #
-    # @rbs (Hash[String, String | Array[String]] headers) -> String
-    def format_headers(headers)
-      result = +""
+    # @rbs (String result, Hash[String, String | Array[String]] headers) -> void
+    def format_headers(result, headers)
       headers.each do |name, value|
         next if illegal_header_key?(name)
 
@@ -1265,7 +1313,6 @@ module Raptor
           append_header_value(result, name, value)
         end
       end
-      result
     end
 
     # Appends one or more `name: value` header lines to `result`. Newline-

data/lib/raptor/http2.rb

@@ -247,6 +247,39 @@ module Raptor
     RACK_HEADER_PREFIX = "rack."
     HOP_BY_HOP_HEADERS = ["connection", "transfer-encoding", "keep-alive", "upgrade", "proxy-connection"].freeze
 
+    REQUEST_PSEUDO_HEADERS = [":method", ":scheme", ":path", ":authority"].freeze
+    REQUIRED_REQUEST_PSEUDO_HEADERS = [":method", ":scheme", ":path"].freeze
+
+    # Returns true when a decoded header block violates the HTTP/2 pseudo-header
+    # rules from RFC 9113 section 8.3: an unknown pseudo-header, a duplicate
+    # pseudo-header, a pseudo-header appearing after any regular header, or a
+    # required pseudo-header (`:method`, `:scheme`, `:path`) missing on
+    # non-`CONNECT` requests.
+    #
+    # @param headers [Array<Array(String, String)>] decoded header pairs
+    # @return [Boolean]
+    #
+    # @rbs (Array[[String, String]] headers) -> bool
+    def self.invalid_pseudo_headers?(headers)
+      seen_pseudo = {}
+      seen_regular = false
+
+      headers.each do |name, _value|
+        if name.start_with?(":")
+          return true if seen_regular
+          return true unless REQUEST_PSEUDO_HEADERS.include?(name)
+          return true if seen_pseudo[name]
+          seen_pseudo[name] = true
+        else
+          seen_regular = true
+        end
+      end
+
+      return false if seen_pseudo[":method"] && headers.assoc(":method")&.last == "CONNECT"
+
+      REQUIRED_REQUEST_PSEUDO_HEADERS.any? { |name| !seen_pseudo[name] }
+    end
+
     # @rbs @app: ^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped]
     # @rbs @server_port: Integer
     # @rbs @write_timeout: Integer
@@ -370,7 +403,12 @@ module Raptor
 
           if (frame[:flags] & FLAG_END_HEADERS) != 0
             decoded_headers, hpack_table = parser.parse_headers(header_payload, hpack_table)
-            streams, completed_requests = finalize_headers(streams, completed_requests, stream_id, decoded_headers, end_stream)
+            if invalid_pseudo_headers?(decoded_headers)
+              streams.delete(stream_id)
+              outgoing_frames << parser.build_frame(:rst_stream, 0, stream_id, [ERROR_PROTOCOL_ERROR].pack("N"))
+            else
+              streams, completed_requests = finalize_headers(streams, completed_requests, stream_id, decoded_headers, end_stream)
+            end
           else
             pending_headers = { stream_id: stream_id, buffer: header_payload, end_stream: end_stream }
           end
@@ -386,7 +424,12 @@ module Raptor
           if (frame[:flags] & FLAG_END_HEADERS) != 0
             stream_id = pending_headers[:stream_id]
             decoded_headers, hpack_table = parser.parse_headers(pending_headers[:buffer], hpack_table)
-            streams, completed_requests = finalize_headers(streams, completed_requests, stream_id, decoded_headers, pending_headers[:end_stream])
+            if invalid_pseudo_headers?(decoded_headers)
+              streams.delete(stream_id)
+              outgoing_frames << parser.build_frame(:rst_stream, 0, stream_id, [ERROR_PROTOCOL_ERROR].pack("N"))
+            else
+              streams, completed_requests = finalize_headers(streams, completed_requests, stream_id, decoded_headers, pending_headers[:end_stream])
+            end
             pending_headers = nil
           end
 
@@ -688,7 +731,7 @@ module Raptor
         next if HOP_BY_HOP_HEADERS.include?(lowered)
 
         if value.is_a?(Array)
-          value.each { |val| header_pairs << [lowered, val.to_s] }
+          value.each { |entry| header_pairs << [lowered, entry.to_s] }
         else
           header_pairs << [lowered, value.to_s]
         end

data/lib/raptor/reuseport_bpf.rb

@@ -105,5 +105,18 @@ module Raptor
       @load_value.setbyte(3, (backlog >> 24) & 0xff)
       LibBPFRuby.map_update(@loads_fd, @load_key, @load_value)
     end
+
+    # Marks a worker's slot as unavailable by parking its load at the
+    # sentinel maximum so the BPF program's least-loaded pick skips it.
+    #
+    # @param worker_index [Integer] slot index for the worker to mark
+    # @return [void]
+    #
+    # @rbs (Integer worker_index) -> void
+    def self.mark_unavailable(worker_index)
+      return unless @loads_fd
+
+      LibBPFRuby.map_update(@loads_fd, [worker_index + 1].pack("L"), [0xffffffff].pack("L"))
+    end
   end
 end

data/lib/raptor/server.rb

@@ -111,18 +111,26 @@ module Raptor
       end
     end
 
-    # Gracefully shuts down the server.
-    #
-    # Stops accepting new connections and closes all listening sockets. When
-    # `drain_accept_queue` is enabled, dispatches every connection already in
-    # the kernel accept queue before closing the listeners.
+    # Stops the accept loop and, when `drain_accept_queue` is enabled,
+    # dispatches every connection already in the kernel accept queue. Leaves
+    # the listening sockets open so they can be handed to replacement workers.
     #
     # @return [void]
     #
     # @rbs () -> void
-    def shutdown
+    def stop_accepting
       @running.make_false
       drain_accept_queue if @drain_accept_queue
+    end
+
+    # Gracefully shuts down the server, stopping the accept loop and closing
+    # all listening sockets.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def shutdown
+      stop_accepting
       @listeners.each(&:close)
     end
 

data/lib/raptor/version.rb

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

data/sig/generated/raptor/cluster.rbs

@@ -40,57 +40,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]
 
@@ -130,6 +158,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
@@ -185,8 +218,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 +237,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 +343,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 +369,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 +381,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

@@ -15,6 +15,8 @@ module Raptor
 
     REMOTE_ADDR: ::String
 
+    REQUEST_URI: ::String
+
     SERVER_SOFTWARE: ::String
 
     SERVER_SOFTWARE_VALUE: untyped