raptor 0.3.0 → 0.5.0

data/sig/generated/raptor/http2.rbs

@@ -33,6 +33,85 @@ module Raptor
       def write_frames: (OpenSSL::SSL::SSLSocket socket, Array[String] frames) -> void
     end
 
+    # Per-connection outbound flow-control accounting.
+    #
+    # Tracks the peer's connection-level and per-stream receive windows so
+    # outbound DATA frames respect RFC 7540 §5.2. Threads dispatching stream
+    # responses call `acquire` to reserve send capacity; threads applying
+    # inbound WINDOW_UPDATE or SETTINGS frames call the mutating methods to
+    # replenish it. The connection window and per-stream windows live in
+    # separate `Atom`s so the common fast path skips per-stream tracking.
+    class FlowControl
+      ACQUIRE_POLL_INTERVAL: ::Float
+
+      @connection_window: Atom
+
+      @stream_windows: Atom
+
+      @initial_stream_window: Atom
+
+      # Creates a new FlowControl with the spec-default windows.
+      #
+      # @rbs () -> void
+      def initialize: () -> void
+
+      # Reserves outbound capacity on the given stream, polling until at
+      # least one byte is available on both the connection and stream
+      # windows. The returned size is capped at `MAX_FRAME_SIZE`.
+      #
+      # When `end_stream` is true, `max_bytes` fits within the peer's
+      # initial stream window, and no per-stream override has been
+      # recorded, only the connection window is consulted. The stream
+      # closes on this frame, so its remaining send window will not be
+      # consulted again and need not be tracked.
+      #
+      # @param stream_id [Integer] the HTTP/2 stream identifier
+      # @param max_bytes [Integer] the largest size the caller would like to send
+      # @param end_stream [Boolean] true when this is the final frame on the stream
+      # @return [Integer] the number of bytes the caller may now send
+      #
+      # @rbs (Integer stream_id, Integer max_bytes, ?end_stream: bool) -> Integer
+      def acquire: (Integer stream_id, Integer max_bytes, ?end_stream: bool) -> Integer
+
+      # Increments the connection-level send window. Called when the peer
+      # sends a WINDOW_UPDATE on stream 0.
+      #
+      # @param increment [Integer] the byte count to add
+      # @return [void]
+      #
+      # @rbs (Integer increment) -> void
+      def add_connection_window: (Integer increment) -> void
+
+      # Increments the per-stream send window. Called when the peer sends
+      # a WINDOW_UPDATE on a specific stream.
+      #
+      # @param stream_id [Integer] the HTTP/2 stream identifier
+      # @param increment [Integer] the byte count to add
+      # @return [void]
+      #
+      # @rbs (Integer stream_id, Integer increment) -> void
+      def add_stream_window: (Integer stream_id, Integer increment) -> void
+
+      # Updates the peer's `SETTINGS_INITIAL_WINDOW_SIZE`. Shifts every
+      # existing stream window by the delta as required by RFC 7540 §6.9.2.
+      #
+      # @param new_size [Integer] the peer's new initial window size
+      # @return [void]
+      #
+      # @rbs (Integer new_size) -> void
+      def set_initial_stream_window: (Integer new_size) -> void
+
+      # Discards any per-stream tracking for the given stream. Called
+      # after a stream closes so `@stream_windows` does not grow without
+      # bound across the lifetime of a connection.
+      #
+      # @param stream_id [Integer] the HTTP/2 stream identifier
+      # @return [void]
+      #
+      # @rbs (Integer stream_id) -> void
+      def discard_stream: (Integer stream_id) -> void
+    end
+
     FLAG_END_STREAM: ::Integer
 
     FLAG_END_HEADERS: ::Integer
@@ -41,6 +120,14 @@ module Raptor
 
     FLAG_PRIORITY: ::Integer
 
+    ERROR_NO_ERROR: ::Integer
+
+    ERROR_PROTOCOL_ERROR: ::Integer
+
+    DEFAULT_WINDOW_SIZE: ::Integer
+
+    MAX_FRAME_SIZE: ::Integer
+
     SERVER_PROTOCOL: ::String
 
     RACK_HEADER_PREFIX: ::String
@@ -82,6 +169,19 @@ module Raptor
     # @rbs (Hash[Symbol, untyped] data) -> Hash[Symbol, untyped]
     def self.process_frames: (Hash[Symbol, untyped] data) -> Hash[Symbol, untyped]
 
+    # Merges a decoded header block into the stream's accumulated state,
+    # promoting the stream to `completed_requests` when END_STREAM is set.
+    #
+    # @param streams [Hash] current open-stream map
+    # @param completed_requests [Array<Hash>] accumulator of completed stream requests
+    # @param stream_id [Integer] the stream identifier
+    # @param decoded_headers [Array<Array(String, String)>] decoded header pairs
+    # @param end_stream [Boolean] whether the source frame had END_STREAM set
+    # @return [Array(Hash, Array<Hash>)] updated streams and completed_requests
+    #
+    # @rbs (Hash[Integer, Hash[Symbol, untyped]] streams, Array[Hash[Symbol, untyped]] completed_requests, Integer stream_id, Array[[String, String]] decoded_headers, bool end_stream) -> [Hash[Integer, Hash[Symbol, untyped]], Array[Hash[Symbol, untyped]]]
+    def self.finalize_headers: (Hash[Integer, Hash[Symbol, untyped]] streams, Array[Hash[Symbol, untyped]] completed_requests, Integer stream_id, Array[[ String, String ]] decoded_headers, bool end_stream) -> [ Hash[Integer, Hash[Symbol, untyped]], Array[Hash[Symbol, untyped]] ]
+
     # Builds a frozen result hash from the current processing state.
     #
     # @param data [Hash] original connection state
@@ -90,12 +190,17 @@ module Raptor
     # @param streams [Hash] updated stream states
     # @param outgoing_frames [Array<String>] frames to write to the socket
     # @param completed_requests [Array<Hash>] fully received stream requests
+    # @param window_updates [Array<Array(Integer, Integer)>] inbound WINDOW_UPDATE pairs as [stream_id, increment]
+    # @param peer_initial_window_size [Integer, nil] new SETTINGS_INITIAL_WINDOW_SIZE announced by the peer
     # @param connection_window [Integer] current connection flow control window
     # @param preface_received [Boolean] whether the connection preface has been received
+    # @param last_client_stream_id [Integer] highest client-initiated stream ID seen
+    # @param pending_headers [Hash, nil] in-progress HEADERS+CONTINUATION assembly
+    # @param close_connection [Boolean] whether the connection should be closed after writing outgoing frames
     # @return [Hash] frozen result hash
     #
-    # @rbs (Hash[Symbol, untyped] data, String buffer, Array[untyped] hpack_table, Hash[Integer, Hash[Symbol, untyped]] streams, Array[String] outgoing_frames, Array[Hash[Symbol, untyped]] completed_requests, Integer connection_window, bool preface_received) -> Hash[Symbol, untyped]
-    def self.build_result: (Hash[Symbol, untyped] data, String buffer, Array[untyped] hpack_table, Hash[Integer, Hash[Symbol, untyped]] streams, Array[String] outgoing_frames, Array[Hash[Symbol, untyped]] completed_requests, Integer connection_window, bool preface_received) -> Hash[Symbol, untyped]
+    # @rbs (Hash[Symbol, untyped] data, String buffer, Array[untyped] hpack_table, Hash[Integer, Hash[Symbol, untyped]] streams, Array[String] outgoing_frames, Array[Hash[Symbol, untyped]] completed_requests, Array[[Integer, Integer]] window_updates, Integer? peer_initial_window_size, Integer connection_window, bool preface_received, Integer last_client_stream_id, Hash[Symbol, untyped]? pending_headers, bool close_connection) -> Hash[Symbol, untyped]
+    def self.build_result: (Hash[Symbol, untyped] data, String buffer, Array[untyped] hpack_table, Hash[Integer, Hash[Symbol, untyped]] streams, Array[String] outgoing_frames, Array[Hash[Symbol, untyped]] completed_requests, Array[[ Integer, Integer ]] window_updates, Integer? peer_initial_window_size, Integer connection_window, bool preface_received, Integer last_client_stream_id, Hash[Symbol, untyped]? pending_headers, bool close_connection) -> Hash[Symbol, untyped]
 
     # Handles a parsed HTTP/2 request from the ractor pool.
     #
@@ -112,32 +217,47 @@ module Raptor
 
     private
 
+    # Applies inbound flow-control updates from a parsed result to the
+    # connection's `FlowControl`.
+    #
+    # @param flow_control [FlowControl] the per-connection flow controller
+    # @param result [Hash] the parsed result from `process_frames`
+    # @return [void]
+    #
+    # @rbs (FlowControl flow_control, Hash[Symbol, untyped] result) -> void
+    def apply_flow_control_updates: (FlowControl flow_control, Hash[Symbol, untyped] result) -> void
+
     # Dispatches a completed stream request to the Rack app and writes
     # the response back as HTTP/2 frames.
     #
     # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
     # @param writer [Writer] lock-free frame writer for the connection
+    # @param flow_control [FlowControl] per-connection outbound flow controller
     # @param stream_id [Integer] the HTTP/2 stream identifier
     # @param headers [Array<Array(String, String)>] request headers
     # @param body [String] request body
     # @param remote_addr [String] the client IP address
     # @return [void]
     #
-    # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, Integer stream_id, Array[[String, String]] headers, String body, remote_addr: String) -> void
-    def dispatch_stream_request: (OpenSSL::SSL::SSLSocket socket, Writer writer, Integer stream_id, Array[[ String, String ]] headers, String body, remote_addr: String) -> void
+    # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Array[[String, String]] headers, String body, remote_addr: String) -> void
+    def dispatch_stream_request: (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Array[[ String, String ]] headers, String body, remote_addr: String) -> void
 
     # Writes a Rack response as HTTP/2 frames to the socket.
     #
+    # DATA frames are partitioned through `flow_control` so each write fits
+    # within the peer's per-stream and connection windows.
+    #
     # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
     # @param writer [Writer] lock-free frame writer for the connection
+    # @param flow_control [FlowControl] per-connection outbound flow controller
     # @param stream_id [Integer] the HTTP/2 stream identifier
     # @param status [Integer] HTTP status code
     # @param headers [Hash] response headers from the Rack application
     # @param body [Object] response body responding to each
     # @return [void]
     #
-    # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, Integer stream_id, Integer status, Hash[String, String | Array[String]] headers, untyped body) -> void
-    def write_http2_response: (OpenSSL::SSL::SSLSocket socket, Writer writer, Integer stream_id, Integer status, Hash[String, String | Array[String]] headers, untyped body) -> void
+    # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Integer status, Hash[String, String | Array[String]] headers, untyped body) -> void
+    def write_http2_response: (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Integer status, Hash[String, String | Array[String]] headers, untyped body) -> void
 
     # Writes a 500 error response as HTTP/2 frames.
     #

data/sig/generated/raptor/log.rbs

@@ -0,0 +1,41 @@
+# Generated from lib/raptor/log.rb with RBS::Inline
+
+module Raptor
+  # Shared logging helpers. Every line is prefixed with
+  # `[Raptor <pid>|<ractor>|<thread>]` so output is identifiable
+  # and traceable to its source in a mixed log stream.
+  module Log
+    # Writes an informational message to stdout.
+    #
+    # @param message [String] the message to log
+    # @return [void]
+    #
+    # @rbs (String message) -> void
+    def self.info: (String message) -> void
+
+    # Writes a warning to stderr.
+    #
+    # @param message [String] the message to log
+    # @return [void]
+    #
+    # @rbs (String message) -> void
+    def self.warn: (String message) -> void
+
+    # Logs a rescued exception to stderr. The full message (class,
+    # message, backtrace) is written on subsequent unprefixed lines.
+    #
+    # @param error [Exception] the rescued exception
+    # @return [void]
+    #
+    # @rbs (Exception error) -> void
+    def self.rescued_error: (Exception error) -> void
+
+    # Builds the log line prefix from the current process, ractor,
+    # and thread. Unnamed ractors and threads are reported as `main`.
+    #
+    # @return [String] the prefix
+    #
+    # @rbs () -> String
+    def self.prefix: () -> String
+  end
+end

data/sig/generated/raptor/reactor.rbs

@@ -5,12 +5,12 @@ module Raptor
   #
   # Reactor uses NIO selectors for efficient I/O multiplexing and implements
   # client timeouts using a red-black tree for O(log n) timeout management.
-  # It coordinates between thread pools for blocking operations and ractor
-  # pools for CPU-intensive HTTP parsing, and provides backlog metrics
-  # that the server uses for backpressure control to prevent overload.
+  # It coordinates between ractor pools for CPU-intensive HTTP parsing and
+  # thread pools for blocking operations, and provides backlog metrics that
+  # the server uses for backpressure control to prevent overload.
   #
   # @example
-  #   reactor = Reactor.new(thread_pool, ractor_pool, client_options: {
+  #   reactor = Reactor.new(ractor_pool, thread_pool, client_options: {
   #     first_data_timeout: 30,
   #     chunk_data_timeout: 10
   #   })
@@ -19,33 +19,33 @@ module Raptor
   #   # ... later
   #   reactor.shutdown
   class Reactor
-    # Red-black tree node representing a client connection with timeout tracking.
-    #
-    # TimeoutClient extends RedBlackTree::Node to enable efficient timeout
-    # management using the tree's ordering properties.
+    # A client connection node ordered by absolute expiry time so the
+    # soonest-to-expire is always at the tree's minimum.
     class TimeoutClient < RedBlackTree::Node
       # @rbs attr_accessor timeout_at: Float
       attr_accessor timeout_at: untyped
 
-      # Returns the client data stored in this timeout node.
+      # Semantic alias for the inherited `data` slot.
       #
-      # @return [Hash] the client connection state data
+      # @return [Hash] the client connection state
       #
       # @rbs () -> Hash[Symbol, untyped]
       def client_data: () -> Hash[Symbol, untyped]
 
-      # Calculates remaining timeout duration from the current time.
+      # Returns seconds until expiry, clamped to 0 so an already-expired
+      # client doesn't push the next selector wait into the future.
       #
       # @param now [Float] current monotonic timestamp
-      # @return [Float] remaining timeout in seconds, minimum 0
+      # @return [Float] seconds until expiry, never negative
       #
       # @rbs (Float now) -> Float
       def timeout: (Float now) -> Float
 
-      # Compares timeout nodes by their timeout_at values for tree ordering.
+      # Orders nodes by `timeout_at` so the tree minimum is the next
+      # client to expire.
       #
       # @param other [TimeoutClient] another timeout client to compare
-      # @return [Integer] -1, 0, or 1 for ordering
+      # @return [Integer] -1, 0, or 1
       #
       # @rbs (TimeoutClient other) -> Integer
       def <=>: (TimeoutClient other) -> Integer
@@ -55,6 +55,8 @@ module Raptor
 
     TIMEOUT_RESPONSE: ::String
 
+    @id_to_flow_control: Hash[Integer, untyped]
+
     @id_to_writer: Hash[Integer, untyped]
 
     @id_to_timeout: Hash[Integer, TimeoutClient]
@@ -77,16 +79,16 @@ module Raptor
 
     # Creates a new Reactor instance.
     #
-    # @param thread_pool [AtomicThreadPool] thread pool for application processing
     # @param ractor_pool [RactorPool] ractor pool for HTTP parsing
+    # @param thread_pool [AtomicThreadPool] thread pool for application processing
     # @param client_options [Hash] timeout configuration options
     # @option client_options [Integer] :first_data_timeout timeout for initial data
     # @option client_options [Integer] :chunk_data_timeout timeout for subsequent chunks
     # @option client_options [Integer] :persistent_data_timeout timeout for keep-alive connections
     # @return [void]
     #
-    # @rbs (untyped thread_pool, untyped ractor_pool, client_options: Hash[Symbol, Integer]) -> void
-    def initialize: (untyped thread_pool, untyped ractor_pool, client_options: Hash[Symbol, Integer]) -> void
+    # @rbs (untyped ractor_pool, untyped thread_pool, client_options: Hash[Symbol, Integer]) -> void
+    def initialize: (untyped ractor_pool, untyped thread_pool, client_options: Hash[Symbol, Integer]) -> void
 
     # Starts the reactor's main event loop in a new thread.
     #
@@ -121,13 +123,12 @@ module Raptor
     # @rbs (Hash[Symbol, untyped] state) -> void
     def update_state: (Hash[Symbol, untyped] state) -> void
 
-    # Removes a client connection from the reactor.
-    #
-    # Called when an HTTP request is complete and ready for application
-    # processing. Triggers server accept re-enabling if system capacity allows.
+    # Drops the reactor's references to a client whose parsed request
+    # has been handed off to the thread pool. The socket itself is kept
+    # open so the worker can write the response.
     #
     # @param id [Integer] unique client identifier
-    # @return [TCPSocket, nil] the removed socket, if found
+    # @return [TCPSocket, nil] the socket associated with `id`, if any
     #
     # @rbs (Integer id) -> TCPSocket?
     def remove: (Integer id) -> TCPSocket?
@@ -169,6 +170,16 @@ module Raptor
     # @rbs (Integer id) -> untyped?
     def writer_for: (Integer id) -> untyped?
 
+    # Returns the flow controller associated with a given connection, if one
+    # was supplied when the connection was added. Used by HTTP/2 stream
+    # dispatchers to honour the peer's flow-control windows.
+    #
+    # @param id [Integer] unique client identifier
+    # @return [Object, nil] the flow controller, if found
+    #
+    # @rbs (Integer id) -> untyped?
+    def flow_control_for: (Integer id) -> untyped?
+
     # Updates connection state for an HTTP/2 connection after frame processing.
     #
     # Re-registers the socket with the selector for further reads and stores
@@ -180,10 +191,18 @@ module Raptor
     # @rbs (Hash[Symbol, untyped] state) -> void
     def update_http2_state: (Hash[Symbol, untyped] state) -> void
 
-    # Initiates reactor shutdown.
+    # Closes the socket for the given connection and drops all reactor state
+    # associated with it. Used to terminate HTTP/2 connections after sending
+    # a GOAWAY frame.
     #
-    # Closes the registration queue and wakes up the selector to begin
-    # graceful shutdown process.
+    # @param id [Integer] unique client identifier
+    # @return [void]
+    #
+    # @rbs (Integer id) -> void
+    def close_connection: (Integer id) -> void
+
+    # Closes the registration queue and wakes the selector so the
+    # event loop drains pending work and exits.
     #
     # @return [void]
     #

data/sig/generated/raptor/request.rbs

@@ -1,13 +1,10 @@
 # Generated from lib/raptor/request.rb with RBS::Inline
 
 module Raptor
-  # Handles HTTP request processing and Rack application integration.
-  #
-  # Request manages the HTTP parsing pipeline using Ractors and coordinates
-  # with the reactor for connection state management. It bridges between the
-  # low-level HTTP parsing and high-level Rack application interface, handling
-  # both incomplete requests (that need more data) and complete requests
-  # (ready for application processing).
+  # Parses HTTP/1.x requests and dispatches them to the Rack
+  # application. Coordinates with the Ractor pool for parsing and
+  # with the reactor for requests that need more data before they
+  # can be handled.
   class Request
     BODY_BUFFER_THRESHOLD: untyped
 
@@ -21,8 +18,6 @@ module Raptor
 
     MAX_KEEPALIVE_REQUESTS: ::Integer
 
-    HTTP_SCHEME: ::String
-
     HTTP_10: ::String
 
     HTTP_11: ::String
@@ -33,6 +28,8 @@ module Raptor
 
     STATUS_WITH_NO_ENTITY_BODY: untyped
 
+    BAD_REQUEST_RESPONSE: ::String
+
     INTERNAL_SERVER_ERROR_RESPONSE: ::String
 
     CONTENT_TOO_LARGE_RESPONSE: ::String
@@ -78,6 +75,19 @@ module Raptor
     # @rbs (String buffer, ?Integer? max_size) -> [String, Symbol]
     def self.decode_chunked: (String buffer, ?Integer? max_size) -> [ String, Symbol ]
 
+    # Writes `string` in full, retrying on partial writes. Bounded by
+    # `WRITE_TIMEOUT` so a slow client can't pin the writing thread.
+    #
+    # @param socket [TCPSocket] the socket to write to
+    # @param string [String] the data to write
+    # @return [void]
+    # @raise [WriteError] if the socket is not writable within the timeout or raises IOError
+    #
+    # @rbs (TCPSocket socket, String string) -> void
+    def self.socket_write: (TCPSocket socket, String string) -> void
+
+    @running: AtomicBoolean
+
     @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
 
     @body_spool_threshold: Integer?
@@ -101,6 +111,14 @@ module Raptor
     # @rbs (^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped] app, Integer server_port, ?client_options: Hash[Symbol, untyped], ?on_error: ^(Hash[String, untyped]?, Exception) -> void | nil) -> void
     def initialize: (^(Hash[String, untyped]) -> [ Integer, Hash[String, String | Array[String]], untyped ] app, Integer server_port, ?client_options: Hash[Symbol, untyped], ?on_error: ^(Hash[String, untyped]?, Exception) -> void | nil) -> void
 
+    # Signals eager keep-alive loops to stop processing further requests on
+    # their connections. In-flight requests complete normally.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def shutdown: () -> void
+
     # Eagerly reads and parses the first request on a freshly accepted
     # connection on the server thread, dispatching directly to the thread pool
     # when complete. Falls back to the reactor when more data is needed.
@@ -225,6 +243,15 @@ module Raptor
     # @rbs (TCPSocket socket) -> void
     def reject_oversized: (TCPSocket socket) -> void
 
+    # Writes a 400 response and closes the socket. Used when the HTTP parser
+    # rejects the request line or headers.
+    #
+    # @param socket [TCPSocket] the client socket
+    # @return [void]
+    #
+    # @rbs (TCPSocket socket) -> void
+    def reject_malformed: (TCPSocket socket) -> void
+
     # Builds a Rack environment hash from parsed HTTP request data.
     #
     # Populates all required Rack env keys including rack.* keys, REMOTE_ADDR,
@@ -499,19 +526,6 @@ module Raptor
     # @rbs (Hash[String, untyped] env, Integer? status, Hash[String, String | Array[String]]? headers, Exception? error) -> void
     def call_response_finished: (Hash[String, untyped] env, Integer? status, Hash[String, String | Array[String]]? headers, Exception? error) -> void
 
-    # Writes a string to the socket, retrying on partial writes and flow control blocks.
-    #
-    # Uses write_nonblock with a 5-second writable timeout to avoid blocking the
-    # thread indefinitely on slow clients.
-    #
-    # @param socket [TCPSocket] the socket to write to
-    # @param string [String] the data to write
-    # @return [void]
-    # @raise [WriteError] if the socket is not writable within the timeout or raises IOError
-    #
-    # @rbs (TCPSocket socket, String string) -> void
-    def socket_write: (TCPSocket socket, String string) -> void
-
     # Enables TCP_CORK on the socket to batch outgoing packets into fewer segments.
     #
     # Only applies to TCP sockets. No-op on non-TCP sockets.

data/sig/generated/raptor/server.rbs

@@ -1,28 +1,22 @@
 # Generated from lib/raptor/server.rb with RBS::Inline
 
 module Raptor
-  # High-performance HTTP server that accepts connections and dispatches them.
+  # Accepts client connections and dispatches them into the request
+  # pipeline. Skips acceptance when the reactor backlog is high so an
+  # overloaded process leaves connections for peers that can absorb
+  # them (via shared `SO_REUSEPORT` listeners).
   #
-  # Server manages the main accept loop, handling incoming client connections from
-  # bound sockets. It uses IO.select for efficient polling and implements automatic
-  # load balancing by checking reactor backlog before accepting connections,
-  # providing natural backpressure based on system capacity.
-  #
-  # Supports TCP, Unix domain, and SSL listeners transparently. TCP_NODELAY is
-  # applied only to TCP sockets, and SSL handshakes are performed synchronously
-  # before the connection is dispatched.
-  #
-  # For HTTP/1.1 connections the first request is parsed inline on the server
-  # thread and dispatched directly to the thread pool, falling back to the
-  # reactor only when more data is needed. For HTTP/2 connections (negotiated
-  # via ALPN) the server sends initial SETTINGS and registers the connection
-  # with the reactor for frame processing through the ractor pool.
+  # Supports TCP, Unix, and SSL listeners. SSL handshakes are offloaded
+  # to the thread pool so a slow client can't pin the server thread.
+  # For HTTP/1.1 the first request is parsed inline and dispatched
+  # straight to the thread pool; HTTP/2 (negotiated via ALPN) is
+  # registered with the reactor for frame processing.
   #
   # @example
   #   binder = Binder.new(["tcp://0.0.0.0:3000"])
-  #   reactor = Reactor.new(thread_pool, ractor_pool, client_options: {})
+  #   reactor = Reactor.new(ractor_pool, thread_pool, client_options: {})
   #   request = Request.new(app, 3000)
-  #   server = Server.new(binder, reactor, thread_pool, request)
+  #   server = Server.new(binder, reactor, thread_pool, request, client_options: { first_data_timeout: 30 })
   #   server.run
   #   # ... later
   #   server.shutdown
@@ -33,15 +27,21 @@ module Raptor
 
     H2_PROTOCOL: ::String
 
-    @binder: Binder
+    DEFAULT_REMOTE_ADDR: ::String
 
-    @reactor: Reactor
+    DEFAULT_SERVER_NAME: ::String
 
-    @thread_pool: AtomicThreadPool
+    @running: AtomicBoolean
+
+    @client_options: Hash[Symbol, untyped]
 
     @request: Request
 
-    @running: AtomicBoolean
+    @thread_pool: AtomicThreadPool
+
+    @reactor: Reactor
+
+    @binder: Binder
 
     # Creates a new Server instance.
     #
@@ -49,10 +49,11 @@ module Raptor
     # @param reactor [Reactor] the reactor for handling client connections
     # @param thread_pool [AtomicThreadPool] thread pool for application processing
     # @param request [Request] the HTTP/1.1 request handler
+    # @param client_options [Hash] client timeout configuration, used to bound TLS handshakes
     # @return [void]
     #
-    # @rbs (Binder binder, Reactor reactor, AtomicThreadPool thread_pool, Request request) -> void
-    def initialize: (Binder binder, Reactor reactor, AtomicThreadPool thread_pool, Request request) -> void
+    # @rbs (Binder binder, Reactor reactor, AtomicThreadPool thread_pool, Request request, client_options: Hash[Symbol, untyped]) -> void
+    def initialize: (Binder binder, Reactor reactor, AtomicThreadPool thread_pool, Request request, client_options: Hash[Symbol, untyped]) -> void
 
     # Starts the server's main accept loop in a new thread.
     #
@@ -80,9 +81,11 @@ module Raptor
 
     # Accepts a connection from the given listener and dispatches it.
     #
-    # For SSL connections with h2 negotiated via ALPN, the server sends
-    # initial SETTINGS and adds the connection to the reactor as an HTTP/2
-    # connection. All other connections follow the HTTP/1.1 path.
+    # For SSL listeners the TLS handshake is offloaded to the thread pool so
+    # a slow client cannot block the server thread. For SSL connections with
+    # h2 negotiated via ALPN, the server sends initial SETTINGS and adds the
+    # connection to the reactor as an HTTP/2 connection. All other connections
+    # follow the HTTP/1.1 path.
     #
     # @param listener [TCPServer, UNIXServer, Binder::SslListener] the ready listener
     # @param reactor [Reactor] the reactor to dispatch connections to
@@ -90,5 +93,39 @@ module Raptor
     #
     # @rbs (TCPServer | UNIXServer | Binder::SslListener listener, Reactor reactor) -> void
     def accept_connection: (TCPServer | UNIXServer | Binder::SslListener listener, Reactor reactor) -> void
+
+    # Performs the TLS handshake for an accepted SSL connection and dispatches
+    # it through the HTTP/2 or HTTP/1.1 path. The handshake is bounded by
+    # `:first_data_timeout` so a slow client cannot pin a worker thread.
+    #
+    # @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 reactor [Reactor] the reactor to dispatch the connection to
+    # @return [void]
+    #
+    # @rbs (Binder::SslListener listener, TCPSocket tcp_client, String remote_addr, Reactor reactor) -> void
+    def dispatch_ssl_connection: (Binder::SslListener listener, TCPSocket tcp_client, String remote_addr, Reactor reactor) -> void
+
+    # Drives a non-blocking SSL handshake to completion, bounded by the
+    # configured first-data timeout. Returns true on success, false on
+    # timeout or SSL error.
+    #
+    # @param ssl_socket [OpenSSL::SSL::SSLSocket] the SSL socket to hand-shake
+    # @return [Boolean] true if the handshake completed
+    #
+    # @rbs (OpenSSL::SSL::SSLSocket ssl_socket) -> bool
+    def perform_ssl_handshake: (OpenSSL::SSL::SSLSocket ssl_socket) -> bool
+
+    # Waits up to `deadline` for the socket to become ready for the next step
+    # of the SSL handshake. Closes the socket and returns false on timeout.
+    #
+    # @param ssl_socket [OpenSSL::SSL::SSLSocket] the SSL socket
+    # @param deadline [Float] absolute monotonic deadline
+    # @param direction [Symbol] either `:read` or `:write`
+    # @return [Boolean] true if the socket became ready before the deadline
+    #
+    # @rbs (OpenSSL::SSL::SSLSocket ssl_socket, Float deadline, Symbol direction) -> bool
+    def wait_for_handshake: (OpenSSL::SSL::SSLSocket ssl_socket, Float deadline, Symbol direction) -> bool
   end
 end