raptor 0.2.0 → 0.4.0

data/lib/raptor/server.rb

@@ -14,8 +14,8 @@ module Raptor
   # 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.
+  # applied only to TCP sockets, and SSL handshakes are offloaded to the thread
+  # pool so a slow client cannot block the server thread.
   #
   # 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
@@ -27,7 +27,7 @@ module Raptor
   #   binder = Binder.new(["tcp://0.0.0.0:3000"])
   #   reactor = Reactor.new(thread_pool, ractor_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
@@ -41,6 +41,7 @@ module Raptor
     # @rbs @reactor: Reactor
     # @rbs @thread_pool: AtomicThreadPool
     # @rbs @request: Request
+    # @rbs @client_options: Hash[Symbol, untyped]
     # @rbs @running: AtomicBoolean
 
     # Creates a new Server instance.
@@ -49,14 +50,16 @@ 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, reactor, thread_pool, request)
+    # @rbs (Binder binder, Reactor reactor, AtomicThreadPool thread_pool, Request request, client_options: Hash[Symbol, untyped]) -> void
+    def initialize(binder, reactor, thread_pool, request, client_options:)
       @binder = binder
       @reactor = reactor
       @thread_pool = thread_pool
       @request = request
+      @client_options = client_options
       @running = AtomicBoolean.new(true)
     end
 
@@ -108,9 +111,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
@@ -131,46 +136,117 @@ module Raptor
         remote_addr = "127.0.0.1"
       end
 
-      url_scheme = HTTP_SCHEME
-      client = tcp_client
-
       if listener.is_a?(Binder::SslListener)
-        url_scheme = HTTPS_SCHEME
-        begin
-          ssl_socket = OpenSSL::SSL::SSLSocket.new(tcp_client, listener.ssl_context)
-          ssl_socket.sync_close = true
-          ssl_socket.accept
-          client = ssl_socket
-        rescue OpenSSL::SSL::SSLError => error
-          warn "SSL handshake failed: #{error.message}"
-          tcp_client.close rescue nil
-          return
+        @thread_pool << proc do
+          dispatch_ssl_connection(listener, tcp_client, remote_addr, reactor)
         end
+        return
+      end
 
-        if ssl_socket.alpn_protocol == H2_PROTOCOL
-          ssl_socket.write(Http2.build_server_settings_frame) rescue nil
+      @request.eager_accept(
+        tcp_client,
+        tcp_client.object_id,
+        reactor,
+        @thread_pool,
+        remote_addr,
+        HTTP_SCHEME
+      )
+    end
 
-          reactor.add(
-            id: ssl_socket.object_id,
-            socket: ssl_socket,
-            remote_addr: remote_addr,
-            url_scheme: HTTPS_SCHEME,
-            protocol: :http2,
-            writer: Http2::Writer.new
-          )
+    # 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(listener, tcp_client, remote_addr, reactor)
+      ssl_socket = OpenSSL::SSL::SSLSocket.new(tcp_client, listener.ssl_context)
+      ssl_socket.sync_close = true
+      return unless perform_ssl_handshake(ssl_socket)
+
+      if ssl_socket.alpn_protocol == H2_PROTOCOL
+        ssl_socket.write(Http2.build_server_settings_frame) rescue nil
+
+        reactor.add(
+          id: ssl_socket.object_id,
+          socket: ssl_socket,
+          remote_addr: remote_addr,
+          url_scheme: HTTPS_SCHEME,
+          protocol: :http2,
+          writer: Http2::Writer.new,
+          flow_control: Http2::FlowControl.new
+        )
 
-          return
-        end
+        return
       end
 
       @request.eager_accept(
-        client,
-        client.object_id,
+        ssl_socket,
+        ssl_socket.object_id,
         reactor,
         @thread_pool,
         remote_addr,
-        url_scheme
+        HTTPS_SCHEME
       )
     end
+
+    # 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(ssl_socket)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @client_options[:first_data_timeout]
+
+      begin
+        ssl_socket.accept_nonblock
+        true
+      rescue IO::WaitReadable
+        return false unless wait_for_handshake(ssl_socket, deadline, :read)
+
+        retry
+      rescue IO::WaitWritable
+        return false unless wait_for_handshake(ssl_socket, deadline, :write)
+
+        retry
+      rescue OpenSSL::SSL::SSLError => error
+        warn "SSL handshake failed: #{error.message}"
+        ssl_socket.close rescue nil
+        false
+      end
+    end
+
+    # 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(ssl_socket, deadline, direction)
+      remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      ready = if remaining <= 0
+        false
+      elsif direction == :read
+        ssl_socket.wait_readable(remaining)
+      else
+        ssl_socket.wait_writable(remaining)
+      end
+      return true if ready
+
+      warn "SSL handshake timed out"
+      ssl_socket.close rescue nil
+      false
+    end
   end
 end

data/lib/raptor/version.rb

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

data/lib/raptor.rb

@@ -5,9 +5,9 @@ require_relative "raptor/version"
 
 # Main module for the Raptor web server.
 #
-# Raptor is a high-performance, multi-threaded, multi-process Ruby web server that
-# leverages Ractors for parallel HTTP/1.1 and HTTP/2 request processing, native C
-# extensions for HTTP parsing and HPACK compression, and NIO for non-blocking I/O.
+# Raptor is a high-performance, preloading, multi-process, multi-threaded Ruby 4+ web server
+# implementing Rack 3+, leveraging Ractors for parallel HTTP/1.1 and HTTP/2 request processing,
+# native C extensions for HTTP parsing and HPACK compression, and NIO for non-blocking I/O.
 #
 module Raptor
 end

data/sig/generated/raptor/cli.rbs

@@ -20,6 +20,33 @@ module Raptor
 
     DEFAULT_OPTIONS: untyped
 
+    DEFAULT_CONFIG_PATHS: untyped
+
+    # Loads a configuration file and returns the hash it evaluates to.
+    #
+    # The file is evaluated at the top level so constants like `Raptor::*` resolve
+    # the same as in a regular Ruby script. The final expression must be a Hash
+    # of cluster options (the same keys accepted by {Raptor::Cluster#initialize}).
+    #
+    # @param path [String] path to a Ruby file that evaluates to a Hash
+    # @return [Hash{Symbol => untyped}] cluster options
+    # @raise [ArgumentError] if the file does not evaluate to a Hash
+    #
+    # @rbs (String path) -> Hash[Symbol, untyped]
+    def self.load_config_file: (String path) -> Hash[Symbol, untyped]
+
+    # Returns the first existing path in {DEFAULT_CONFIG_PATHS} resolved
+    # against `root`, or nil if none exist.
+    #
+    # Used to pick up a project-local config file when no `-c`/`--config`
+    # flag was supplied.
+    #
+    # @param root [String] directory to resolve the default paths against
+    # @return [String, nil] the config path, or nil if no default file exists
+    #
+    # @rbs (?String root) -> String?
+    def self.default_config_path: (?String root) -> String?
+
     @command: Symbol
 
     @options: Hash[Symbol, untyped]
@@ -61,6 +88,30 @@ module Raptor
     # @rbs () -> void
     def run_stats: () -> void
 
+    # Scans argv for a `-c`/`--config` flag and returns the configured path.
+    #
+    # The pre-scan runs before the main OptionParser pass so the config file
+    # can be applied as a base layer that CLI args then override. All four
+    # OptionParser-accepted forms (`-c PATH`, `-cPATH`, `--config PATH`,
+    # `--config=PATH`) are recognized.
+    #
+    # @param argv [Array<String>] command-line arguments to scan
+    # @return [String, nil] the config path, or nil if no flag was supplied
+    #
+    # @rbs (Array[String] argv) -> String?
+    def extract_config_path: (Array[String] argv) -> String?
+
+    # Loads a config file and merges it into `@options` over the defaults.
+    #
+    # Top-level keys replace defaults; the nested `:client` hash is merged
+    # key-by-key so a config file does not need to restate every client option.
+    #
+    # @param path [String, nil] path to the config file, or nil to no-op
+    # @return [void]
+    #
+    # @rbs (String? path) -> void
+    def apply_config_file: (String? path) -> void
+
     # Creates the OptionParser instance with all supported command-line options.
     #
     # @return [OptionParser] configured option parser

data/sig/generated/raptor/cluster.rbs

@@ -37,7 +37,9 @@ module Raptor
     # @rbs (Hash[Symbol, untyped] options) -> void
     def self.run: (Hash[Symbol, untyped] options) -> void
 
-    @stats_file: String?
+    @phased_restarting: bool
+
+    @phased_restart_requested: bool
 
     @stats: Stats
 
@@ -51,6 +53,12 @@ module Raptor
 
     @binder: Binder
 
+    @pid_file: String?
+
+    @stats_file: String?
+
+    @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
+
     @client_options: Hash[Symbol, Integer]
 
     @worker_count: Integer
@@ -72,7 +80,10 @@ module Raptor
     # @option options [Array<String>] :binds array of bind URIs
     # @option options [#call] :app pre-built Rack application
     # @option options [String] :rackup path to Rack configuration file
-    # @option options [Hash] :client client timeout configuration
+    # @option options [Hash] :client client configuration
+    # @option options [#call] :on_error callback invoked with (env, exception) when the Rack app raises
+    # @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
     # @return [void]
     #
     # @rbs (Hash[Symbol, untyped] options) -> void
@@ -82,7 +93,8 @@ module Raptor
     #
     # Forks the configured number of worker processes and monitors them,
     # automatically restarting any that exit unexpectedly. Handles graceful
-    # shutdown via INT or TERM signals, and stats logging via USR1.
+    # shutdown via INT or TERM signals, stats logging via USR1, and phased
+    # restart via USR2.
     #
     # Each worker process includes:
     # - 1 server thread (continuously accepts connections with backpressure control)
@@ -115,6 +127,22 @@ module Raptor
     # @rbs (Integer index) -> void
     def spawn_worker: (Integer index) -> void
 
+    # 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
+    #
+    # @rbs () -> Symbol
+    def reap_workers: () -> Symbol
+
+    # Replaces each worker process one at a time, waiting for the new
+    # worker to boot before moving on to the next. Triggered by SIGUSR2.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def perform_phased_restart: () -> void
+
     # Runs the full server stack inside a worker process.
     #
     # Sets up and coordinates the reactor, server, ractor pool, thread pool,

data/sig/generated/raptor/http2.rbs

@@ -33,6 +33,84 @@ 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. State is held in a single `Atom` so updates use CAS.
+    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,12 +119,22 @@ 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
 
     HOP_BY_HOP_HEADERS: untyped
 
+    @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
+
     @server_port: Integer
 
     @app: ^(Hash[String, untyped]) -> [ Integer, Hash[String, String | Array[String]], untyped ]
@@ -55,10 +143,11 @@ module Raptor
     #
     # @param app [#call] the Rack application to dispatch requests to
     # @param server_port [Integer] port number used to populate SERVER_PORT in the Rack env
+    # @param on_error [#call, nil] callback invoked with (env, exception) when the Rack app raises
     # @return [void]
     #
-    # @rbs (^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped] app, Integer server_port) -> void
-    def initialize: (^(Hash[String, untyped]) -> [ Integer, Hash[String, String | Array[String]], untyped ] app, Integer server_port) -> void
+    # @rbs (^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped] app, Integer server_port, ?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, ?on_error: ^(Hash[String, untyped]?, Exception) -> void | nil) -> void
 
     # Builds the initial server SETTINGS frame to send on connection establishment.
     #
@@ -79,6 +168,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
@@ -87,12 +189,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.
     #
@@ -109,32 +216,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/reactor.rbs

@@ -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]
@@ -169,6 +171,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,6 +192,16 @@ module Raptor
     # @rbs (Hash[Symbol, untyped] state) -> void
     def update_http2_state: (Hash[Symbol, untyped] state) -> void
 
+    # 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.
+    #
+    # @param id [Integer] unique client identifier
+    # @return [void]
+    #
+    # @rbs (Integer id) -> void
+    def close_connection: (Integer id) -> void
+
     # Initiates reactor shutdown.
     #
     # Closes the registration queue and wakes up the selector to begin