raptor 0.22.3 → 0.23.0

data/sig/generated/raptor/reactor.rbs

@@ -5,11 +5,20 @@ module Raptor
   # ready bytes to the parser pipeline, and hands completed requests back
   # to the caller-provided handlers.
   class Reactor
+    CHUNK_SIZE: untyped
+
+    DETACHED_CONNECTION_BUFFER_SIZE: untyped
+
+    DETACHED_WRITE_BATCH: ::Integer
+
+    DETACHED_WORKER_BUFFER_SIZE: untyped
+
+    TIMEOUT_RESPONSE: ::String
+
     # 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: untyped
+      attr_accessor timeout_at: Float
 
       # Returns the client connection state.
       #
@@ -39,26 +48,19 @@ module Raptor
 
     # Tracks reactor-owned output state for a connection.
     class ConnectionIO
-      # @rbs attr_accessor offset: Integer
-      attr_accessor offset: untyped
+      attr_accessor offset: Integer
 
-      # @rbs attr_accessor wait: Symbol?
-      attr_accessor wait: untyped
+      attr_accessor wait: Symbol?
 
-      # @rbs attr_accessor reading: bool
-      attr_accessor reading: untyped
+      attr_accessor reading: bool
 
-      # @rbs attr_accessor closing: bool
-      attr_accessor closing: untyped
+      attr_accessor closing: bool
 
-      # @rbs attr_accessor monitor: NIO::Monitor?
-      attr_accessor monitor: untyped
+      attr_accessor monitor: NIO::Monitor?
 
-      # @rbs attr_accessor timeout: TimeoutClient?
-      attr_accessor timeout: untyped
+      attr_accessor timeout: TimeoutClient?
 
-      # @rbs attr_reader output: Array[String]
-      attr_reader output: untyped
+      attr_reader output: Array[String]
 
       # Creates empty connection I/O state for reactor-owned writes.
       #
@@ -77,25 +79,20 @@ module Raptor
 
     # Tracks reactor-owned I/O state for an HTTP/1.x detached response.
     class Http1IO < ConnectionIO
-      # @rbs attr_accessor body: DetachedBody?
-      attr_accessor body: untyped
+      attr_accessor body: DetachedBody?
 
-      # @rbs attr_accessor finishing: bool
-      attr_accessor finishing: untyped
+      attr_accessor finishing: bool
 
-      # @rbs attr_reader budget: DetachedBody::Budget
-      attr_reader budget: untyped
+      attr_reader budget: DetachedBody::Budget
 
-      # @rbs attr_reader input: String
-      attr_reader input: untyped
+      attr_reader input: String
 
-      # @rbs attr_reader state: Hash[Symbol, untyped]
-      attr_reader state: untyped
+      attr_reader state: Hash[Symbol, untyped]
 
       # Creates I/O state for an HTTP/1.x detached response.
       #
       # @param body [DetachedBody] the response body
-      # @param state [Hash] connection state restored after the response finishes
+      # @param state [Hash] connection state restored after the response finishes, including bytes the client pipelined after the request
       # @return [void]
       #
       # @rbs (DetachedBody body, Hash[Symbol, untyped] state) -> void
@@ -111,17 +108,13 @@ module Raptor
 
     # Tracks reactor-owned I/O state for an HTTP/2 connection.
     class Http2IO < ConnectionIO
-      # @rbs attr_reader detached: Hash[Integer, DetachedBody]
-      attr_reader detached: untyped
+      attr_reader detached: Hash[Integer, DetachedBody]
 
-      # @rbs attr_reader ready: Array[Integer]
-      attr_reader ready: untyped
+      attr_reader ready: Array[Integer]
 
-      # @rbs attr_reader ready_streams: Hash[Integer, bool]
-      attr_reader ready_streams: untyped
+      attr_reader ready_streams: Hash[Integer, bool]
 
-      # @rbs attr_reader budget: DetachedBody::Budget
-      attr_reader budget: untyped
+      attr_reader budget: DetachedBody::Budget
 
       # Creates empty I/O state for an HTTP/2 connection and its detached streams.
       #
@@ -138,18 +131,6 @@ module Raptor
       def empty?: () -> bool
     end
 
-    CHUNK_SIZE: untyped
-
-    DETACHED_CONNECTION_BUFFER_SIZE: untyped
-
-    DETACHED_WRITE_BATCH: ::Integer
-
-    DETACHED_WORKER_BUFFER_SIZE: untyped
-
-    TIMEOUT_RESPONSE: ::String
-
-    @timeouts: RedBlackTree[TimeoutClient]
-
     @io_applied: AtomicConditionVariable
 
     @io_queue: AtomicQueue
@@ -162,19 +143,23 @@ module Raptor
 
     @http2_keepalive_interval: Integer
 
-    @write_timeout: Integer
-
     @persistent_data_timeout: Integer
 
+    @write_timeout: Integer
+
     @chunk_data_timeout: Integer
 
     @first_data_timeout: Integer
 
-    @http2_ractor_pool: untyped
+    @thread_pool: AtomicThreadPool
 
-    @http1_ractor_pool: untyped
+    @http2_ractor_pool: RactorPool?
 
-    @thread_pool: untyped
+    @http1_ractor_pool: RactorPool
+
+    @http1: Http1
+
+    @timeouts: RedBlackTree[TimeoutClient]
 
     @id_to_socket: Hash[Integer, TCPSocket]
 
@@ -182,9 +167,9 @@ module Raptor
 
     @id_to_timeout: Hash[Integer, TimeoutClient]
 
-    @id_to_writer: Hash[Integer, untyped]
+    @id_to_writer: Hash[Integer, Http2::Writer]
 
-    @id_to_flow_control: Hash[Integer, untyped]
+    @id_to_flow_control: Hash[Integer, Http2::FlowControl]
 
     @id_to_http2_last_stream: Hash[Integer, Integer]
 
@@ -202,8 +187,9 @@ module Raptor
 
     @thread: Thread?
 
-    # Creates a new Reactor instance.
+    # Creates a new Reactor.
     #
+    # @param http1 [Http1] the HTTP/1.1 handler that resumes idle keep-alive connections
     # @param http1_ractor_pool [RactorPool] ractor pool for HTTP/1.x parsing
     # @param http2_ractor_pool [RactorPool, nil] ractor pool for HTTP/2 parsing, or nil when no listener supports HTTP/2
     # @param thread_pool [AtomicThreadPool] thread pool for application processing
@@ -218,8 +204,8 @@ module Raptor
     # @option http2_options [Integer] :keepalive_timeout time to await a PING acknowledgement
     # @return [void]
     #
-    # @rbs (untyped http1_ractor_pool, untyped http2_ractor_pool, untyped thread_pool, connection_options: Hash[Symbol, untyped], http1_options: Hash[Symbol, untyped], http2_options: Hash[Symbol, untyped]) -> void
-    def initialize: (untyped http1_ractor_pool, untyped http2_ractor_pool, untyped thread_pool, connection_options: Hash[Symbol, untyped], http1_options: Hash[Symbol, untyped], http2_options: Hash[Symbol, untyped]) -> void
+    # @rbs (Http1 http1, RactorPool http1_ractor_pool, RactorPool? http2_ractor_pool, AtomicThreadPool thread_pool, connection_options: Hash[Symbol, untyped], http1_options: Hash[Symbol, untyped], http2_options: Hash[Symbol, untyped]) -> void
+    def initialize: (Http1 http1, RactorPool http1_ractor_pool, RactorPool? http2_ractor_pool, AtomicThreadPool thread_pool, connection_options: Hash[Symbol, untyped], http1_options: Hash[Symbol, untyped], http2_options: Hash[Symbol, untyped]) -> void
 
     # Starts the reactor's main event loop in a new thread. Runs until
     # shutdown work and pending writes are drained.
@@ -233,7 +219,7 @@ module Raptor
     #
     # @param state [Hash] client connection state including socket and ID
     # @option state [TCPSocket] :socket the client socket
-    # @option state [Integer] :id unique identifier for the client
+    # @option state [Integer] :id unique connection identifier
     # @return [void]
     #
     # @rbs (Hash[Symbol, untyped] state) -> void
@@ -243,7 +229,7 @@ module Raptor
     # it for further I/O.
     #
     # @param state [Hash] updated client connection state
-    # @option state [Integer] :id client identifier
+    # @option state [Integer] :id unique connection identifier
     # @return [void]
     #
     # @rbs (Hash[Symbol, untyped] state) -> void
@@ -253,7 +239,7 @@ module Raptor
     # 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
+    # @param id [Integer] unique connection identifier
     # @return [TCPSocket, nil] the socket associated with `id`, if any
     #
     # @rbs (Integer id) -> TCPSocket?
@@ -263,45 +249,45 @@ module Raptor
     # under the persistent-data timeout.
     #
     # @param socket [TCPSocket] the kept-alive client socket
-    # @param id [Integer] the unique client identifier
+    # @param id [Integer] unique connection identifier
     # @param request_count [Integer] number of requests handled on this connection
-    # @param remote_addr [String] the client's remote IP address
+    # @param remote_addr [String] the client IP address
     # @param url_scheme [String] "http" or "https"
     # @return [void]
     #
     # @rbs (TCPSocket socket, Integer id, Integer request_count, remote_addr: String, url_scheme: String) -> void
     def persist: (TCPSocket socket, Integer id, Integer request_count, remote_addr: String, url_scheme: String) -> void
 
-    # Returns the socket for a given client identifier without removing it.
+    # Returns the socket for a given connection identifier without removing it.
     #
-    # @param id [Integer] unique client identifier
+    # @param id [Integer] unique connection identifier
     # @return [TCPSocket, nil] the socket, if found
     #
     # @rbs (Integer id) -> TCPSocket?
     def socket_for: (Integer id) -> TCPSocket?
 
-    # Returns the writer object associated with a given connection, if one
-    # was supplied when the connection was added.
+    # Returns the HTTP/2 frame writer registered by {attach_http2} for a
+    # connection.
     #
-    # @param id [Integer] unique client identifier
-    # @return [Object, nil] the writer, if found
+    # @param id [Integer] unique connection identifier
+    # @return [Http2::Writer, nil] the writer, if found
     #
-    # @rbs (Integer id) -> untyped?
-    def writer_for: (Integer id) -> untyped?
+    # @rbs (Integer id) -> Http2::Writer?
+    def writer_for: (Integer id) -> Http2::Writer?
 
-    # Returns the flow controller associated with a given connection, if
-    # one was supplied when the connection was added.
+    # Returns the HTTP/2 flow controller registered by {attach_http2} for a
+    # connection.
     #
-    # @param id [Integer] unique client identifier
-    # @return [Object, nil] the flow controller, if found
+    # @param id [Integer] unique connection identifier
+    # @return [Http2::FlowControl, nil] the flow controller, if found
     #
-    # @rbs (Integer id) -> untyped?
-    def flow_control_for: (Integer id) -> untyped?
+    # @rbs (Integer id) -> Http2::FlowControl?
+    def flow_control_for: (Integer id) -> Http2::FlowControl?
 
     # Attaches a detached response body to an HTTP/1.x connection.
     #
     # @param socket [TCPSocket] the client socket
-    # @param id [Integer] unique client identifier
+    # @param id [Integer] unique connection identifier
     # @param body [DetachedBody] the response body
     # @param state [Hash] connection state restored once the response finishes
     # @param finished [Proc] called with the close reason
@@ -314,7 +300,7 @@ module Raptor
     # that arrived after graceful draining began.
     #
     # @param id [Integer] unique connection identifier
-    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @param stream_id [Integer] the HTTP/2 stream identifier
     # @return [Boolean] whether the stream may be dispatched
     #
     # @rbs (Integer id, Integer stream_id) -> bool
@@ -323,7 +309,8 @@ module Raptor
     # Sends GOAWAY on every HTTP/2 connection and fixes the last stream each
     # connection may dispatch while existing application work drains.
     #
-    # @yieldparam stream_id [Integer] last dispatched stream identifier
+    # @yield for each HTTP/2 connection
+    # @yieldparam stream_id [Integer] the last dispatched HTTP/2 stream identifier
     # @yieldreturn [String] serialized GOAWAY frame
     # @return [void]
     #
@@ -343,7 +330,7 @@ module Raptor
     # Attaches a detached response body to an HTTP/2 stream.
     #
     # @param id [Integer] unique connection identifier
-    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @param stream_id [Integer] the HTTP/2 stream identifier
     # @param body [DetachedBody] the response body
     # @param finished [Proc] called with the close reason
     # @return [Boolean] whether the body was attached
@@ -362,7 +349,7 @@ module Raptor
     # Cancels a detached response stream.
     #
     # @param id [Integer] unique connection identifier
-    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @param stream_id [Integer] the HTTP/2 stream identifier
     # @return [void]
     #
     # @rbs (Integer id, Integer stream_id) -> void
@@ -380,17 +367,17 @@ module Raptor
     # Stores an HTTP/2 connection's socket, state, writer, and flow
     # controller in the reactor's per-connection maps.
     #
-    # @param id [Integer] unique client identifier
+    # @param id [Integer] unique connection identifier
     # @param socket [TCPSocket] the connection socket
     # @param state [Hash] initial connection state
-    # @param writer [Http2::Writer] per-connection frame writer
+    # @param writer [Http2::Writer] frame writer for the connection
     # @param flow_control [Http2::FlowControl] per-connection outbound flow controller
     # @param ping_frame [String] serialized PING frame for keepalive probes
     # @param ping_payload [String] payload expected in the corresponding acknowledgement
     # @return [void]
     #
-    # @rbs (id: Integer, socket: TCPSocket, state: Hash[Symbol, untyped], writer: untyped, flow_control: untyped, ping_frame: String, ping_payload: String) -> void
-    def attach_http2: (id: Integer, socket: TCPSocket, state: Hash[Symbol, untyped], writer: untyped, flow_control: untyped, ping_frame: String, ping_payload: String) -> void
+    # @rbs (id: Integer, socket: TCPSocket, state: Hash[Symbol, untyped], writer: Http2::Writer, flow_control: Http2::FlowControl, ping_frame: String, ping_payload: String) -> void
+    def attach_http2: (id: Integer, socket: TCPSocket, state: Hash[Symbol, untyped], writer: Http2::Writer, flow_control: Http2::FlowControl, ping_frame: String, ping_payload: String) -> void
 
     # Records acknowledgements for server keepalive probes.
     #
@@ -403,24 +390,15 @@ module Raptor
 
     # Registers an attached socket for future reactor-driven reads.
     #
-    # @param id [Integer] unique client identifier
+    # @param id [Integer] unique connection identifier
     # @return [void]
     #
     # @rbs (Integer id) -> void
     def watch: (Integer id) -> void
 
-    # Updates connection state for an HTTP/2 connection and re-registers
-    # the socket for further reads.
-    #
-    # @param state [Hash] updated connection state from the ractor pool
-    # @return [void]
-    #
-    # @rbs (Hash[Symbol, untyped] state) -> void
-    def update_http2_state: (Hash[Symbol, untyped] state) -> void
-
     # Closes a connection after writing any frames already queued for it.
     #
-    # @param id [Integer] unique client identifier
+    # @param id [Integer] unique connection identifier
     # @return [void]
     #
     # @rbs (Integer id) -> void
@@ -469,7 +447,7 @@ module Raptor
     # Adds a detached body to an HTTP/1.x connection.
     #
     # @param socket [TCPSocket] the client socket
-    # @param id [Integer] unique client identifier
+    # @param id [Integer] unique connection identifier
     # @param body [DetachedBody] the response body
     # @param state [Hash] connection state restored once the response finishes
     # @param finished [Proc] called with the close reason
@@ -480,7 +458,7 @@ module Raptor
 
     # Writes buffered HTTP/1.x body chunks without blocking.
     #
-    # @param id [Integer] unique client identifier
+    # @param id [Integer] unique connection identifier
     # @return [void]
     #
     # @rbs (Integer id) -> void
@@ -488,7 +466,7 @@ module Raptor
 
     # Finishes an HTTP/1.x detached response and either reuses or closes its connection.
     #
-    # @param id [Integer] unique client identifier
+    # @param id [Integer] unique connection identifier
     # @param io [Http1IO] connection I/O state
     # @return [void]
     #
@@ -497,7 +475,7 @@ module Raptor
 
     # Cancels an HTTP/1.x detached response and closes its connection.
     #
-    # @param id [Integer] unique client identifier
+    # @param id [Integer] unique connection identifier
     # @param reason [Symbol] why the response closed
     # @return [void]
     #
@@ -507,7 +485,7 @@ module Raptor
     # Adds a detached body to an HTTP/2 stream.
     #
     # @param id [Integer] unique connection identifier
-    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @param stream_id [Integer] the HTTP/2 stream identifier
     # @param body [DetachedBody] the response body
     # @param finished [Proc] called with the close reason
     # @return [void]
@@ -518,7 +496,7 @@ module Raptor
     # Marks an HTTP/2 detached stream eligible for fair scheduling.
     #
     # @param id [Integer] unique connection identifier
-    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @param stream_id [Integer] the HTTP/2 stream identifier
     # @return [void]
     #
     # @rbs (Integer id, Integer stream_id) -> void
@@ -543,7 +521,7 @@ module Raptor
     # Finishes an HTTP/2 detached stream with DATA or trailing HEADERS.
     #
     # @param id [Integer] unique connection identifier
-    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @param stream_id [Integer] the HTTP/2 stream identifier
     # @param body [DetachedBody] the response body
     # @return [void]
     #
@@ -553,7 +531,7 @@ module Raptor
     # Removes an HTTP/2 detached stream and schedules its close callback.
     #
     # @param id [Integer] unique connection identifier
-    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @param stream_id [Integer] the HTTP/2 stream identifier
     # @param reason [Symbol] why the stream closed
     # @return [void]
     #
@@ -576,7 +554,7 @@ module Raptor
 
     # Closes a connection once its queued frames are written.
     #
-    # @param id [Integer] unique client identifier
+    # @param id [Integer] unique connection identifier
     # @return [void]
     #
     # @rbs (Integer id) -> void
@@ -584,15 +562,15 @@ module Raptor
 
     # Immediately closes a connection and drops its reactor state.
     #
-    # @param id [Integer] unique client identifier
+    # @param id [Integer] unique connection identifier
     # @return [void]
     #
     # @rbs (Integer id) -> void
     def remove_connection: (Integer id) -> void
 
-    # Adds bytes to one connection and writes as much as the socket accepts.
+    # Appends bytes to one connection's pending output.
     #
-    # @param io [ConnectionIO] connection I/O state
+    # @param io [ConnectionIO, nil] connection I/O state
     # @param data [String] serialized response bytes
     # @return [void]
     #
@@ -602,7 +580,7 @@ module Raptor
     # Drains one connection's queued response bytes without blocking.
     #
     # @param id [Integer] unique connection identifier
-    # @param io [ConnectionIO] connection I/O state
+    # @param io [ConnectionIO, nil] connection I/O state
     # @return [void]
     #
     # @rbs (Integer id, ConnectionIO? io) -> void
@@ -692,13 +670,14 @@ module Raptor
     # Handles readiness for an HTTP/1.x detached response.
     #
     # @param monitor [NIO::Monitor] ready selector monitor
-    # @param id [Integer] unique client identifier
+    # @param id [Integer] unique connection identifier
     # @return [void]
     #
     # @rbs (NIO::Monitor monitor, Integer id) -> void
     def handle_http1_detached_monitor: (NIO::Monitor monitor, Integer id) -> void
 
-    # Handles socket wakeup by deregistering and queuing for processing.
+    # Deregisters a readable socket and resumes its idle keep-alive
+    # connection or queues its bytes for parsing.
     #
     # @param socket [TCPSocket] the socket that became ready
     # @return [void]
@@ -706,15 +685,25 @@ module Raptor
     # @rbs (TCPSocket socket) -> void
     def wakeup!: (TCPSocket socket) -> void
 
+    # Resumes a readable keep-alive connection on an application thread,
+    # avoiding a Ractor round trip for complete requests.
+    #
+    # @param socket [TCPSocket] the readable client socket
+    # @param state [Hash] current connection state
+    # @return [void]
+    #
+    # @rbs (TCPSocket socket, Hash[Symbol, untyped] state) -> void
+    def resume_keepalive: (TCPSocket socket, Hash[Symbol, untyped] state) -> void
+
     # Reads data from a socket and either queues it for parsing or
     # returns it to the selector.
     #
     # @param socket [TCPSocket] the socket to read from and queue
     # @param state [Hash] current connection state
-    # @return [Hash, nil] updated state, if successful
+    # @return [void]
     #
-    # @rbs (TCPSocket socket, Hash[Symbol, untyped] state) -> Hash[Symbol, untyped]?
-    def read_and_queue_for_parse: (TCPSocket socket, Hash[Symbol, untyped] state) -> Hash[Symbol, untyped]?
+    # @rbs (TCPSocket socket, Hash[Symbol, untyped] state) -> void
+    def read_and_queue_for_parse: (TCPSocket socket, Hash[Symbol, untyped] state) -> void
 
     # Cleans up a client connection by removing it from tracking and closing the socket.
     #
@@ -724,18 +713,18 @@ module Raptor
     # @rbs (TCPSocket socket) -> void
     def cleanup: (TCPSocket socket) -> void
 
-    # Returns true when the request has been fully parsed.
+    # Returns whether the request has been fully parsed.
     #
     # @param state [Hash] connection state
-    # @return [Boolean] true if the request is complete
+    # @return [Boolean]
     #
     # @rbs (Hash[Symbol, untyped] state) -> bool
     def complete?: (Hash[Symbol, untyped] state) -> bool
 
-    # Checks if any data has been received for this connection.
+    # Returns whether any data has been received for this connection.
     #
     # @param state [Hash] connection state
-    # @return [Boolean] true if first data has been received
+    # @return [Boolean]
     #
     # @rbs (Hash[Symbol, untyped] state) -> bool
     def first_data_received?: (Hash[Symbol, untyped] state) -> bool

data/sig/generated/raptor/reuseport_bpf.rbs

@@ -6,14 +6,41 @@ 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: untyped
 
     BPF_OBJECT_PATH: untyped
 
+    TCP_INFO_UNACKED_OFFSET: ::Integer
+
+    UNAVAILABLE_LOAD: ::Integer
+
+    MAX_WORKERS: ::Integer
+
+    MAX_LISTENERS: ::Integer
+
+    self.@accepted_load_value: String
+
+    self.@load_value: String
+
+    self.@load_key: String
+
+    self.@worker_listeners: Array[TCPServer]
+
+    self.@shared_listeners: Array[TCPServer]
+
+    self.@loads_fd: Integer?
+
+    self.@socks_fd: Integer
+
+    self.@program_fd: Integer
+
+    self.@object: untyped
+
     # Returns true when the preconditions for BPF-directed reuseport are
     # met on this platform.
     #
@@ -22,28 +49,30 @@ module Raptor
     # @rbs () -> bool
     def self.supported?: () -> bool
 
-    # 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: (Integer worker_count) -> bool
+    # @rbs (Integer worker_count, Array[TCPServer] shared_listeners) -> bool
+    def self.setup: (Integer worker_count, Array[TCPServer] shared_listeners) -> bool
 
-    # 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: (Array[String] bind_uris, Integer worker_index, Integer socket_backlog) -> Array[TCPServer]
+    # @rbs (Integer worker_index, Integer socket_backlog) -> Array[TCPServer]
+    def self.create_worker_listeners: (Integer worker_index, Integer socket_backlog) -> Array[TCPServer]
 
     # Prepares this worker's load-reporting slot so subsequent
     # {update_load} calls can publish its backlog.
@@ -54,7 +83,7 @@ module Raptor
     # @rbs (Integer worker_index) -> void
     def self.enable_load_reporting: (Integer worker_index) -> void
 
-    # 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]
@@ -62,7 +91,7 @@ module Raptor
     # @rbs (Integer backlog) -> void
     def self.update_load: (Integer backlog) -> void
 
-    # 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.
     #
@@ -72,13 +101,21 @@ module Raptor
     # @rbs (Integer backlog) -> void
     def self.update_accepted_load: (Integer backlog) -> void
 
-    # 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: (Integer worker_index) -> void
+
+    # 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: () -> Integer
   end
 end