raptor 0.22.2 → 0.23.0

data/lib/raptor/reuseport_bpf.rb

@@ -2,7 +2,6 @@
 # frozen_string_literal: true
 
 require "socket"
-require "uri"
 
 begin
   require "libbpf-ruby"
@@ -15,13 +14,28 @@ module Raptor
   #
   # Auto-enabled on Linux when the `libbpf-ruby` gem is installed and the
   # BPF object file has been compiled. Falls back silently to standard
-  # `SO_REUSEPORT` when either is missing. Raises when the kernel refuses
-  # the BPF program. Wraps `tcp://` bindings only; non-tcp bindings are
-  # left to the binder's shared listeners.
+  # `SO_REUSEPORT` when either is missing, or when there are more workers
+  # or listeners than the BPF maps have slots for. Raises when the kernel
+  # refuses the BPF program. Wraps `tcp://` bindings only; non-tcp bindings
+  # are left to the binder's shared listeners.
   #
   module ReuseportBPF
     LIBBPF_LOADED = !!defined?(LibBPFRuby)
     BPF_OBJECT_PATH = File.expand_path("../../ext/raptor_bpf/reuseport_select.bpf.o", __dir__)
+    TCP_INFO_UNACKED_OFFSET = 24
+    UNAVAILABLE_LOAD = 0xffffffff
+    MAX_WORKERS = 64
+    MAX_LISTENERS = 16
+
+    # @rbs self.@object: untyped
+    # @rbs self.@program_fd: Integer
+    # @rbs self.@socks_fd: Integer
+    # @rbs self.@loads_fd: Integer?
+    # @rbs self.@shared_listeners: Array[TCPServer]
+    # @rbs self.@worker_listeners: Array[TCPServer]
+    # @rbs self.@load_key: String
+    # @rbs self.@load_value: String
+    # @rbs self.@accepted_load_value: String
 
     # Returns true when the preconditions for BPF-directed reuseport are
     # met on this platform.
@@ -33,18 +47,22 @@ module Raptor
       LIBBPF_LOADED && File.exist?(BPF_OBJECT_PATH)
     end
 
-    # Prepares BPF-directed routing for `worker_count` workers.
+    # Prepares BPF-directed routing for `worker_count` workers across the
+    # addresses `shared_listeners` are bound to.
     #
     # Returns true when BPF-directed dispatch is active. Returns false
-    # when the platform is unsupported. Raises when the kernel refuses
-    # the program.
+    # when the platform is unsupported or the counts exceed the map slots.
+    # Raises when the kernel refuses the program.
     #
     # @param worker_count [Integer] number of worker processes that will bind sockets
+    # @param shared_listeners [Array<TCPServer>] the binder's tcp listeners
     # @return [Boolean]
     #
-    # @rbs (Integer worker_count) -> bool
-    def self.setup(worker_count)
-      return false unless supported?
+    # @rbs (Integer worker_count, Array[TCPServer] shared_listeners) -> bool
+    def self.setup(worker_count, shared_listeners)
+      return false unless supported? && worker_count <= MAX_WORKERS && shared_listeners.length <= MAX_LISTENERS
+
+      @shared_listeners = shared_listeners
 
       @object = LibBPFRuby::Object.new(BPF_OBJECT_PATH)
       @program_fd = @object.program_fd("select_less_loaded")
@@ -55,32 +73,27 @@ module Raptor
       true
     end
 
-    # Returns tcp listening sockets bound and registered for `worker_index`.
-    # Skips non-tcp bind URIs.
+    # Creates this worker's BPF-routed listeners at the shared listeners'
+    # bound addresses, including resolved `localhost` addresses and ports
+    # assigned by the kernel for port 0.
     #
-    # @param bind_uris [Array<String>] the configured bind URIs
     # @param worker_index [Integer] slot index for this worker in the socks map
     # @param socket_backlog [Integer] kernel listen() queue depth
     # @return [Array<TCPServer>] the tcp listening sockets created for this worker
     #
-    # @rbs (Array[String] bind_uris, Integer worker_index, Integer socket_backlog) -> Array[TCPServer]
-    def self.create_worker_listeners(bind_uris, worker_index, socket_backlog)
-      bind_uris.filter_map do |bind_uri|
-        uri = URI(bind_uri)
-        next unless uri.scheme == "tcp"
-
-        host = uri.host
-        host = host[1..-2] if host&.start_with?("[")
-
-        addrinfo = Addrinfo.tcp(host, uri.port)
+    # @rbs (Integer worker_index, Integer socket_backlog) -> Array[TCPServer]
+    def self.create_worker_listeners(worker_index, socket_backlog)
+      @worker_listeners = @shared_listeners.each_with_index.map do |shared_listener, listener_index|
+        addrinfo = shared_listener.local_address
         socket = Socket.new(addrinfo.afamily, Socket::SOCK_STREAM, 0)
         socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_REUSEADDR, true)
         socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_REUSEPORT, true)
         socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
+        socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_DEFER_ACCEPT, 1)
         socket.bind(addrinfo)
         socket.listen(socket_backlog)
 
-        LibBPFRuby.sockmap_update(@socks_fd, [worker_index].pack("L"), socket)
+        LibBPFRuby.sockmap_update(@socks_fd, [listener_index * MAX_WORKERS + worker_index].pack("L"), socket)
         LibBPFRuby.attach_reuseport(socket, @program_fd)
 
         tcp_server = TCPServer.for_fd(socket.fileno)
@@ -102,21 +115,22 @@ module Raptor
       @accepted_load_value = String.new("\x00\x00\x00\x00", encoding: Encoding::ASCII_8BIT)
     end
 
-    # Publishes this worker's current backlog to the BPF map.
+    # Publishes this worker's load to the BPF map.
     #
     # @param backlog [Integer] the worker's current reactor backlog
     # @return [void]
     #
     # @rbs (Integer backlog) -> void
     def self.update_load(backlog)
-      @load_value.setbyte(0, backlog & 0xff)
-      @load_value.setbyte(1, (backlog >> 8) & 0xff)
-      @load_value.setbyte(2, (backlog >> 16) & 0xff)
-      @load_value.setbyte(3, (backlog >> 24) & 0xff)
+      load = backlog + accept_queue_length
+      @load_value.setbyte(0, load & 0xff)
+      @load_value.setbyte(1, (load >> 8) & 0xff)
+      @load_value.setbyte(2, (load >> 16) & 0xff)
+      @load_value.setbyte(3, (load >> 24) & 0xff)
       LibBPFRuby.map_update(@loads_fd, @load_key, @load_value)
     end
 
-    # Publishes an accept-side backlog estimate. This uses a separate value
+    # Publishes an accept-side load estimate. This uses a separate value
     # buffer because the server and load reporter call into the map from
     # different threads.
     #
@@ -125,24 +139,34 @@ module Raptor
     #
     # @rbs (Integer backlog) -> void
     def self.update_accepted_load(backlog)
-      @accepted_load_value.setbyte(0, backlog & 0xff)
-      @accepted_load_value.setbyte(1, (backlog >> 8) & 0xff)
-      @accepted_load_value.setbyte(2, (backlog >> 16) & 0xff)
-      @accepted_load_value.setbyte(3, (backlog >> 24) & 0xff)
+      load = backlog + accept_queue_length
+      @accepted_load_value.setbyte(0, load & 0xff)
+      @accepted_load_value.setbyte(1, (load >> 8) & 0xff)
+      @accepted_load_value.setbyte(2, (load >> 16) & 0xff)
+      @accepted_load_value.setbyte(3, (load >> 24) & 0xff)
       LibBPFRuby.map_update(@loads_fd, @load_key, @accepted_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.
+    # Parks a worker's load at the maximum so BPF favors other workers.
+    # Stop publishing its load first to avoid overwriting the sentinel.
     #
     # @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"), [UNAVAILABLE_LOAD].pack("L"))
+    end
 
-      LibBPFRuby.map_update(@loads_fd, [worker_index + 1].pack("L"), [0xffffffff].pack("L"))
+    # Returns the number of connections waiting in this worker's accept
+    # queues, which the reactor backlog cannot see.
+    #
+    # @return [Integer]
+    #
+    # @rbs () -> Integer
+    def self.accept_queue_length
+      @worker_listeners.sum { |listener| listener.getsockopt(Socket::IPPROTO_TCP, Socket::TCP_INFO).data.unpack1("L", offset: TCP_INFO_UNACKED_OFFSET) }
     end
+    private_class_method :accept_queue_length
   end
 end

data/lib/raptor/server.rb

@@ -1,17 +1,19 @@
 # rbs_inline: enabled
 # frozen_string_literal: true
 
+require "openssl"
 require "socket"
 
 require "atomic-ruby/atomic_boolean"
 
+require_relative "binder"
+require_relative "log"
+require_relative "raptor_native"
 require_relative "reuseport_bpf"
 
 module Raptor
-  # Accepts client connections on TCP, Unix, and SSL listeners and
-  # dispatches them into the request pipeline. Yields between accepts
-  # when the thread pool queue exceeds the pool size so overloaded
-  # workers stay responsive to in-flight requests.
+  # Accepts client connections on TCP, Unix, SSL, and cleartext HTTP/2
+  # listeners and dispatches them into the request pipeline.
   #
   class Server
     HTTP_SCHEME = "http"
@@ -25,42 +27,44 @@ module Raptor
     BACKPRESSURE_THRESHOLD_MULTIPLIER = 1.2
     MIN_BACKPRESSURE_THRESHOLD = 8
 
-    # @rbs @binder: Binder
-    # @rbs @listeners: Array[TCPServer | UNIXServer | Binder::SslListener]
     # @rbs @reactor: Reactor
     # @rbs @thread_pool: AtomicThreadPool
     # @rbs @http1: Http1
     # @rbs @http2: Http2
     # @rbs @first_data_timeout: Integer
+    # @rbs @listeners: Array[TCPServer | UNIXServer | Binder::SslListener | Binder::H2cListener]
     # @rbs @drain_accept_queue: bool
-    # @rbs @bpf_active: bool
+    # @rbs @worker_index: Integer?
     # @rbs @running: AtomicBoolean
+    # @rbs @thread: Thread?
+    # @rbs @load_reporter: Thread?
 
-    # Creates a new Server instance.
+    # Creates a new Server.
     #
-    # @param binder [Binder] the binder managing listening sockets
     # @param reactor [Reactor] the reactor for handling client connections
     # @param thread_pool [AtomicThreadPool] thread pool for application processing
     # @param http1 [Http1] the HTTP/1.1 handler
-    # @param http2 [Http2] the HTTP/2 handler (provides the initial SETTINGS frame)
+    # @param http2 [Http2] the HTTP/2 handler
     # @param connection_options [Hash] per-connection timeout configuration, used to bound TLS handshakes
-    # @param listeners [Array] the per-worker listeners this server accepts on
+    # @option connection_options [Integer] :first_data_timeout timeout for completing the TLS handshake
+    # @param listeners [Array<TCPServer, UNIXServer, Binder::SslListener, Binder::H2cListener>] the per-worker listeners this server accepts on
     # @param drain_accept_queue [Boolean] whether to drain the kernel accept queue on shutdown
-    # @param worker_index [Integer, nil] the slot index for BPF load reporting
+    # @param worker_index [Integer, nil] this worker's BPF slot index, or nil when BPF dispatch is inactive
     # @return [void]
     #
-    # @rbs (Binder binder, Reactor reactor, AtomicThreadPool thread_pool, Http1 http1, Http2 http2, connection_options: Hash[Symbol, untyped], listeners: Array[untyped], ?drain_accept_queue: bool, ?worker_index: Integer?) -> void
-    def initialize(binder, reactor, thread_pool, http1, http2, connection_options:, listeners:, drain_accept_queue: false, worker_index: nil)
-      @binder = binder
-      @listeners = listeners
+    # @rbs (Reactor reactor, AtomicThreadPool thread_pool, Http1 http1, Http2 http2, connection_options: Hash[Symbol, untyped], listeners: Array[TCPServer | UNIXServer | Binder::SslListener | Binder::H2cListener], ?drain_accept_queue: bool, ?worker_index: Integer?) -> void
+    def initialize(reactor, thread_pool, http1, http2, connection_options:, listeners:, drain_accept_queue: false, worker_index: nil)
       @reactor = reactor
       @thread_pool = thread_pool
       @http1 = http1
       @http2 = http2
       @first_data_timeout = connection_options[:first_data_timeout]
+      @listeners = listeners
       @drain_accept_queue = drain_accept_queue
-      @bpf_active = !!worker_index
+      @worker_index = worker_index
       @running = AtomicBoolean.new(true)
+      @thread = nil
+      @load_reporter = nil
     end
 
     # Starts the server's main accept loop in a new thread.
@@ -69,30 +73,36 @@ module Raptor
     #
     # @rbs () -> Thread
     def run
-      spawn_load_reporter if @bpf_active
+      @load_reporter = spawn_load_reporter if @worker_index
 
-      Thread.new do
+      @thread = Thread.new do
         Thread.current.name = "Server"
 
-        backpressure_threshold = [(@thread_pool.size * BACKPRESSURE_THRESHOLD_MULTIPLIER).ceil, MIN_BACKPRESSURE_THRESHOLD].max
-
         while @running.true?
           begin
-            ready_servers, _, _ = IO.select(@listeners, nil, nil, 1)
+            ready_servers, = IO.select(@listeners, nil, nil, 1)
           rescue IOError, Errno::EBADF
             break
           end
 
           next unless ready_servers
-          next if @reactor.backlog >= backpressure_threshold
 
-          if @thread_pool.queue_size > @thread_pool.size
-            Thread.pass
+          backpressure_threshold = [(@thread_pool.size * BACKPRESSURE_THRESHOLD_MULTIPLIER).ceil, MIN_BACKPRESSURE_THRESHOLD].max
+          if @reactor.backlog >= backpressure_threshold || @thread_pool.queue_size > @thread_pool.size
+            CPU.yield
             next
           end
 
+          break if @running.false?
+
           ready_servers.each { |listener| accept_connection(listener) }
         end
+
+        if @worker_index
+          # Stop load updates before parking the slot so the sentinel survives.
+          @load_reporter.join
+          ReuseportBPF.mark_unavailable(@worker_index)
+        end
       end
     end
 
@@ -105,6 +115,7 @@ module Raptor
     # @rbs () -> void
     def stop_accepting
       @running.make_false
+      @thread&.wakeup rescue nil
       drain_accept_queue if @drain_accept_queue
     end
 
@@ -121,12 +132,12 @@ module Raptor
 
     private
 
-    # Starts a background thread that publishes this worker's reactor
-    # backlog to the BPF map for load-aware dispatch.
+    # Starts a background thread that publishes this worker's load to the
+    # BPF map for load-aware dispatch.
     #
-    # @return [void]
+    # @return [Thread] the load reporter
     #
-    # @rbs () -> void
+    # @rbs () -> Thread
     def spawn_load_reporter
       Thread.new do
         Thread.current.name = "Load Reporter"
@@ -154,12 +165,12 @@ module Raptor
 
     # Accepts a connection from the given listener, immediately publishes
     # the pending work to the BPF map, and dispatches the socket into the
-    # HTTP/1.1 or SSL/HTTP-2 pipeline.
+    # SSL, cleartext HTTP/2, or HTTP/1.1 pipeline.
     #
-    # @param listener [TCPServer, UNIXServer, Binder::SslListener] the ready listener
+    # @param listener [TCPServer, UNIXServer, Binder::SslListener, Binder::H2cListener] the ready listener
     # @return [Boolean] true if a connection was accepted, false if the listener had nothing to dispatch
     #
-    # @rbs (TCPServer | UNIXServer | Binder::SslListener listener) -> bool
+    # @rbs (TCPServer | UNIXServer | Binder::SslListener | Binder::H2cListener listener) -> bool
     def accept_connection(listener)
       tcp_client = begin
         listener.is_a?(Binder::SslListener) ? listener.tcp_server.accept_nonblock : listener.accept_nonblock
@@ -167,13 +178,14 @@ module Raptor
         return false
       end
 
-      if tcp_client.is_a?(TCPSocket)
-        remote_addr = tcp_client.remote_address.ip_address
-      else
-        remote_addr = DEFAULT_REMOTE_ADDR
+      remote_addr = begin
+        tcp_client.is_a?(TCPSocket) ? tcp_client.remote_address.ip_address : DEFAULT_REMOTE_ADDR
+      rescue SystemCallError
+        tcp_client.close
+        return true
       end
 
-      ReuseportBPF.update_accepted_load(@reactor.backlog + 1) if @bpf_active
+      ReuseportBPF.update_accepted_load(@reactor.backlog + 1) if @worker_index && @running.true?
 
       if listener.is_a?(Binder::SslListener)
         @thread_pool << proc do
@@ -211,7 +223,7 @@ module Raptor
     #
     # @param listener [Binder::SslListener] the SSL listener that accepted the connection
     # @param tcp_client [TCPSocket] the accepted TCP socket
-    # @param remote_addr [String] the client's IP address
+    # @param remote_addr [String] the client IP address
     # @return [void]
     #
     # @rbs (Binder::SslListener listener, TCPSocket tcp_client, String remote_addr) -> void
@@ -268,6 +280,9 @@ module Raptor
         Log.rescued_error(error)
         ssl_socket.close rescue nil
         false
+      rescue SystemCallError
+        ssl_socket.close rescue nil
+        false
       end
     end
 

data/lib/raptor/stats.rb

@@ -27,7 +27,8 @@ module Raptor
     # @rbs @num_workers: Integer
     # @rbs @mmap: untyped
 
-    # Allocates the shared mmap region for `num_workers` slots.
+    # Creates a new Stats and allocates the shared mmap region for
+    # `num_workers` slots.
     #
     # @param num_workers [Integer] number of worker slots to allocate
     # @return [void]
@@ -80,14 +81,25 @@ module Raptor
 
     # Reads stats for a worker slot from shared memory.
     #
-    # @param slot [Integer] slot offset to read from
+    # @param slot [Integer] slot index 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 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 }
+      {
+        pid: pid,
+        index: index,
+        phase: phase,
+        requests: requests,
+        backlog: backlog,
+        busy_threads: busy_threads,
+        thread_capacity: thread_capacity,
+        started_at: started_at,
+        last_checkin: last_checkin,
+        booted: booted == 1
+      }
     end
   end
 end

data/lib/raptor/thread_locals.rb

@@ -15,7 +15,8 @@ module Raptor
     # Returns a reusable value stored on the current thread.
     #
     # @param key [Symbol] thread-variable key used to cache the value
-    # @yieldreturn [Object] value to store when the key is unset
+    # @yield when the key is unset
+    # @yieldreturn [Object] the value to store
     # @return [Object] the existing or newly stored value
     #
     # @rbs (Symbol key) { () -> untyped } -> untyped
@@ -24,8 +25,8 @@ module Raptor
       thread.thread_variable_get(key) || thread.thread_variable_set(key, yield)
     end
 
-    # Clears application-owned true thread locals while retaining Raptor's
-    # reusable per-thread values.
+    # Clears application thread locals while retaining Raptor's reusable
+    # per-thread values.
     #
     # @return [void]
     #

data/lib/raptor/version.rb

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

data/sig/generated/rackup/handler/raptor.rbs

@@ -11,7 +11,8 @@ module Rackup
       #
       # @param app [#call] the Rack application to serve
       # @param options [Hash] handler options provided by Rackup or the host
-      # @yield [cluster] the cluster instance, before it starts running
+      # @yield before the cluster starts running
+      # @yieldparam cluster [::Raptor::Cluster] the cluster instance
       # @return [void]
       #
       # @rbs (^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped] app, **untyped options) { (::Raptor::Cluster) -> void } -> void

data/sig/generated/raptor/binder.rbs

@@ -52,17 +52,17 @@ module Raptor
     # Returns the array of bind URIs.
     #
     # @return [Array<String>]
-    attr_reader bind_uris: untyped
+    attr_reader bind_uris: Array[String]
 
     # Returns the kernel `listen()` queue depth for TCP/SSL listeners.
     #
     # @return [Integer]
-    attr_reader socket_backlog: untyped
+    attr_reader socket_backlog: Integer
 
     # Returns the array of listening sockets.
     #
     # @return [Array<TCPServer, UNIXServer, SslListener, H2cListener>]
-    attr_reader listeners: untyped
+    attr_reader listeners: Array[TCPServer | UNIXServer | SslListener | H2cListener]
 
     # Creates a new Binder and binds each URI. `localhost` expands to both
     # IPv4 and IPv6 loopback; when `inherited_fds` supplies file descriptors
@@ -86,8 +86,8 @@ module Raptor
     # @rbs () -> Array[String]
     def addresses: () -> Array[String]
 
-    # Returns the port of the first TCP or SSL listener, or 0 when none
-    # is configured.
+    # Returns the port of the first TCP, SSL, or cleartext HTTP/2 listener,
+    # or 0 when none is configured.
     #
     # @return [Integer]
     #
@@ -136,7 +136,7 @@ module Raptor
 
     # Creates fresh listeners for the given URI.
     #
-    # @param uri [URI] the parsed bind URI
+    # @param uri [URI::Generic] the parsed bind URI
     # @return [Array<TCPServer, UNIXServer, SslListener, H2cListener>]
     # @raise [UnknownBindSchemeError] if the URI scheme is not supported
     #
@@ -146,7 +146,7 @@ module Raptor
     # Reconstructs listeners for the given URI from inherited file
     # descriptors.
     #
-    # @param uri [URI] the parsed bind URI the FDs were bound to
+    # @param uri [URI::Generic] the parsed bind URI the FDs were bound to
     # @param filenos [Array<Integer>] file descriptors to wrap
     # @return [Array<TCPServer, UNIXServer, SslListener, H2cListener>]
     # @raise [UnknownBindSchemeError] if the URI scheme is not supported
@@ -188,7 +188,7 @@ module Raptor
     #
     # @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` file 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]
@@ -197,7 +197,7 @@ module Raptor
     # Builds a frozen `OpenSSL::SSL::SSLContext` configured for HTTP/2 and
     # HTTP/1.1 ALPN negotiation.
     #
-    # @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 [OpenSSL::SSL::SSLContext]
     #
     # @rbs (Hash[String, String] ssl_params) -> OpenSSL::SSL::SSLContext

data/sig/generated/raptor/cli.rbs

@@ -57,17 +57,17 @@ module Raptor
 
     @parser: OptionParser
 
-    @options: Hash[Symbol, untyped]
-
     @command: Symbol
 
-    # 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.
+    @options: Hash[Symbol, untyped]
+
+    # Creates a new CLI 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
+    # @raise [ArgumentError] if the config file or max threads value is invalid
     #
     # @rbs (Array[String] argv) -> void
     def initialize: (Array[String] argv) -> void
@@ -88,7 +88,7 @@ module Raptor
     # @rbs () -> void
     def run_stats: () -> void
 
-    # Returns the path from a `-c`/`--config` flag in `argv`, recognising
+    # Returns the path from a `-c`/`--config` flag in `argv`, recognizing
     # all four OptionParser-accepted forms (`-c PATH`, `-cPATH`,
     # `--config PATH`, `--config=PATH`).
     #

data/sig/generated/raptor/cluster.rbs

@@ -62,7 +62,7 @@ module Raptor
 
     @launch_argv: Array[String]?
 
-    @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
+    @on_error: (^(Hash[String, untyped]?, Exception) -> void)?
 
     @binder: Binder
 
@@ -104,7 +104,7 @@ module Raptor
 
     @seed_pid: Integer?
 
-    @refork_threshold_idx: Integer
+    @refork_threshold_index: Integer
 
     @refork_requested: bool
 
@@ -210,19 +210,19 @@ module Raptor
     # @rbs () -> Array[Hash[Symbol, untyped]]
     def stats: () -> Array[Hash[Symbol, untyped]]
 
-    # Returns cluster statistics for the control server.
-    # For an adaptive pool, `max_threads` is the number of threads currently
-    # running so utilization reflects the capacity available at that moment.
+    private
+
+    # Returns cluster statistics for the control server. For an adaptive
+    # pool, `max_threads` is the number of threads currently running so
+    # utilization reflects the capacity available at that moment.
     #
     # @return [Hash] cluster statistics
     #
     # @rbs () -> Hash[Symbol, untyped]
     def stats_hash: () -> Hash[Symbol, untyped]
 
-    private
-
-    # @rbs (Float timestamp) -> String
-    def timestamp: (Float timestamp) -> String
+    # @rbs (Numeric time) -> String
+    def timestamp: (Numeric time) -> String
 
     # Returns the inherited-FDs hash for a systemd socket-activation handoff,
     # pairing each bind URI with the FD systemd passed at the same index.

data/sig/generated/raptor/control_server.rbs

@@ -15,9 +15,10 @@ module Raptor
 
     @thread: Thread?
 
-    # Creates a control server for `url` without binding it.
+    # Creates a new ControlServer for `url` without binding it.
     #
     # @param url [String] `unix://` URL to listen on
+    # @yield for each stats request
     # @yieldreturn [Hash] cluster statistics
     # @return [void]
     # @raise [ArgumentError] if the URL is not a Unix socket

data/sig/generated/raptor/detached_body.rbs

@@ -57,6 +57,7 @@ module Raptor
     #
     # @param max_buffer_size [Integer] maximum body bytes waiting to be written
     # @return [void]
+    # @raise [ArgumentError] if `max_buffer_size` is not positive
     #
     # @rbs (?max_buffer_size: Integer) -> void
     def initialize: (?max_buffer_size: Integer) -> void
@@ -64,6 +65,7 @@ module Raptor
     # Registers a callback that runs on the request thread once the server
     # accepts the response stream.
     #
+    # @yield once the response stream opens
     # @yieldparam stream [DetachedBody] the opened response stream
     # @return [DetachedBody]
     #
@@ -72,6 +74,7 @@ module Raptor
 
     # Registers a callback for when the response stream closes.
     #
+    # @yield once the response stream closes
     # @yieldparam reason [Symbol] why the stream closed
     # @return [DetachedBody]
     #
@@ -82,11 +85,12 @@ module Raptor
     #
     # @param chunk [String] response body bytes
     # @return [Symbol] `:accepted`, `:full`, or `:closed`
+    # @raise [TypeError] if the chunk is not a String
     #
     # @rbs (String chunk) -> Symbol
     def try_write: (String chunk) -> Symbol
 
-    # Finishes the body after all accepted bytes have been written.
+    # Marks the body complete; the stream finishes once buffered bytes are written.
     #
     # @param trailers [Hash] trailing response headers
     # @return [void]