raptor 0.7.0 → 0.9.0

data/sig/generated/raptor/cluster.rbs

@@ -26,10 +26,12 @@ module Raptor
   #     workers: 4, ractors: 2, threads: 8,
   #     binds: ["tcp://0.0.0.0:3000"],
   #     rackup: "config.ru",
-  #     client: { first_data_timeout: 30, chunk_data_timeout: 10 }
+  #     connection: { first_data_timeout: 30, chunk_data_timeout: 10 }
   #   }
   #   Cluster.run(options)
   class Cluster
+    INHERITED_FDS_ENV: ::String
+
     # Convenience method to create and run a cluster with the given options.
     #
     # @param options [Hash] cluster configuration options
@@ -38,13 +40,13 @@ module Raptor
     # @rbs (Hash[Symbol, untyped] options) -> void
     def self.run: (Hash[Symbol, untyped] options) -> void
 
-    @thread_count: Integer
+    @http2_options: Hash[Symbol, untyped]
 
-    @client_options: Hash[Symbol, Integer]
+    @worker_boot_timeout: Integer
 
     @worker_timeout: Integer
 
-    @worker_boot_timeout: Integer
+    @worker_drain_timeout: Integer
 
     @worker_shutdown_timeout: Integer
 
@@ -52,6 +54,18 @@ module Raptor
 
     @pid_file: String?
 
+    @stdout_file: String?
+
+    @stderr_file: String?
+
+    @access_log_file: String?
+
+    @access_log_io: IO?
+
+    @launch_command: String?
+
+    @launch_argv: Array[String]?
+
     @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
 
     @binder: Binder
@@ -74,10 +88,24 @@ module Raptor
 
     @phased_restarting: bool
 
+    @hot_restart_requested: bool
+
+    @bpf_active: bool
+
+    @http1_options: Hash[Symbol, untyped]
+
+    @connection_options: Hash[Symbol, untyped]
+
+    @environment: String
+
+    @thread_count: Integer
+
     @ractor_count: Integer
 
     @worker_count: Integer
 
+    @drain_accept_queue: bool
+
     # Creates a new Cluster with the specified configuration.
     #
     # Initializes the cluster with worker, ractor, and thread counts,
@@ -86,18 +114,30 @@ module Raptor
     #
     # @param options [Hash] cluster configuration options
     # @option options [Array<String>] :binds array of bind URIs
+    # @option options [Integer] :socket_backlog kernel listen() queue depth for TCP/SSL listeners
+    # @option options [Boolean] :drain_accept_queue whether to drain the kernel accept queue on shutdown
     # @option options [Integer] :workers number of worker processes
     # @option options [Integer] :ractors number of ractors per worker process
     # @option options [Integer] :threads number of threads per worker process
     # @option options [#call] :app pre-built Rack application
     # @option options [String] :rackup path to Rack configuration file
-    # @option options [Hash] :client client configuration
-    # @option options [Integer] :worker_timeout seconds to wait for a booted worker to check in before killing it
+    # @option options [String, nil] :chdir directory to change to before loading the Rack application, or nil to leave the working directory unchanged
+    # @option options [String, nil] :environment Raptor's application environment label; falls back to `$RAILS_ENV`, then `$RACK_ENV`, then `"development"`
+    # @option options [Hash] :connection per-connection settings shared across protocols
+    # @option options [Hash] :http1 HTTP/1.1-specific settings
+    # @option options [Hash] :http2 HTTP/2-specific settings
     # @option options [Integer] :worker_boot_timeout seconds to wait for a worker to finish booting before killing it
+    # @option options [Integer] :worker_timeout seconds to wait for a booted worker to check in before killing it
+    # @option options [Integer] :worker_drain_timeout seconds a worker waits for in-flight requests during shutdown before force-killing app threads
     # @option options [Integer] :worker_shutdown_timeout seconds to wait for graceful worker exit before force-killing
     # @option options [String, nil] :stats_file path to write per-worker stats JSON, or nil to disable
     # @option options [String, nil] :pid_file path to write the master PID to, or nil to disable
-    # @option options [#call] :on_error callback invoked with (env, exception) when the Rack app raises
+    # @option options [String, nil] :stdout_file path to redirect stdout to, reopened on SIGHUP, or nil to disable
+    # @option options [String, nil] :stderr_file path to redirect stderr to, reopened on SIGHUP, or nil to disable
+    # @option options [String, nil] :access_log_file path to write Common Log Format access logs to, reopened on SIGHUP, or nil to disable
+    # @option options [String, nil] :launch_command path of the program to re-exec on hot restart, or nil to disable
+    # @option options [Array<String>, nil] :launch_argv command-line arguments for the hot-restart exec, or nil to disable
+    # @option options [#call, nil] :on_error callback invoked with (env, exception) when the Rack app raises
     # @return [void]
     #
     # @rbs (Hash[Symbol, untyped] options) -> void
@@ -107,8 +147,8 @@ module Raptor
     #
     # Forks the configured number of worker processes and monitors them,
     # restarting any that exit unexpectedly or stop checking in. Handles
-    # graceful shutdown via INT or TERM signals, stats logging via USR1,
-    # and phased restart via USR2.
+    # graceful shutdown via INT or TERM signals, phased restart via USR1,
+    # and hot restart via USR2.
     #
     # Each worker process includes:
     # - 1 server thread (continuously accepts connections with backpressure control)
@@ -133,6 +173,18 @@ module Raptor
 
     private
 
+    # Returns the inherited-FDs hash for a systemd socket-activation handoff,
+    # pairing each bind URI with the FD systemd passed at the same index.
+    # The activation is skipped (with a warning) when the FD count doesn't
+    # match the number of bind URIs.
+    #
+    # @param bind_uris [Array<String>] the configured bind URIs
+    # @param filenos [Array<Integer>] file descriptors passed by systemd
+    # @return [Hash{String => Array<Integer>}]
+    #
+    # @rbs (Array[String] bind_uris, Array[Integer] filenos) -> Hash[String, Array[Integer]]
+    def pair_systemd_fds: (Array[String] bind_uris, Array[Integer] filenos) -> Hash[String, Array[Integer]]
+
     # Forks a new worker process and registers it at the given index.
     # The worker inherits the cluster's current phase.
     #
@@ -170,13 +222,22 @@ module Raptor
     def timeout_hung_workers: () -> void
 
     # Replaces each worker process one at a time, waiting for the new
-    # worker to boot before moving on to the next. Triggered by SIGUSR2.
+    # worker to boot before moving on to the next.
     #
     # @return [void]
     #
     # @rbs () -> void
     def perform_phased_restart: () -> void
 
+    # Re-execs the master process with a fresh boot of the same Raptor
+    # invocation, handing the new master its listening sockets so accepted
+    # connections continue to be served across the swap.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def perform_hot_restart: () -> void
+
     # Runs the full server stack inside a worker process.
     #
     # Sets up and coordinates the reactor, server, ractor pool, thread pool,
@@ -190,6 +251,16 @@ module Raptor
     # @rbs (Integer index, Integer phase) -> void
     def run_worker: (Integer index, Integer phase) -> void
 
+    # Shuts down the worker's application thread pool, force-killing the
+    # underlying threads if in-flight requests have not finished within
+    # `worker_drain_timeout` seconds.
+    #
+    # @param thread_pool [AtomicThreadPool] the worker's thread pool
+    # @return [void]
+    #
+    # @rbs (AtomicThreadPool thread_pool) -> void
+    def drain_thread_pool: (AtomicThreadPool thread_pool) -> void
+
     # Returns a human-readable description of how a process exited.
     #
     # @param status [Process::Status] the exit status of the process
@@ -213,14 +284,21 @@ module Raptor
     # @rbs () -> void
     def log_initialization: () -> void
 
-    # Logs current stats for all workers to stdout.
+    # Redirects `$stdout`, `$stderr`, and the access log to their configured
+    # paths. No-op for any stream whose target path is nil.
     #
-    # Triggered by SIGUSR1 in the master process.
+    # @return [void]
+    #
+    # @rbs () -> void
+    def reopen_logs: () -> void
+
+    # Reopens the master's log files and forwards SIGHUP to each worker so
+    # they reopen their own inherited file descriptors.
     #
     # @return [void]
     #
     # @rbs () -> void
-    def log_stats: () -> void
+    def reopen_logs_and_signal_workers: () -> void
 
     # Writes the stats file on a 1-second interval until shutdown.
     #

data/sig/generated/raptor/http.rbs

@@ -0,0 +1,65 @@
+# Generated from lib/raptor/http.rb with RBS::Inline
+
+module Raptor
+  # Shared HTTP utilities used by both the HTTP/1.x and HTTP/2 handlers:
+  # Rack env keys that aren't provided by Rack itself, low-level socket
+  # writing, and Common Log Format access-log formatting.
+  module Http
+    WRITE_TIMEOUT: ::Integer
+
+    CONTENT_LENGTH: ::String
+
+    CONTENT_TYPE: ::String
+
+    HTTP_VERSION: ::String
+
+    REMOTE_ADDR: ::String
+
+    SERVER_SOFTWARE: ::String
+
+    SERVER_SOFTWARE_VALUE: untyped
+
+    class WriteError < StandardError
+      # @rbs () -> String
+      def message: () -> String
+    end
+
+    # Writes `string` in full, retrying on partial writes. Bounded by
+    # `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
+    # @param timeout [Integer] seconds to wait for the socket to become writable on each partial write
+    # @return [void]
+    # @raise [WriteError] if the socket is not writable within the timeout or raises IOError
+    #
+    # @rbs (TCPSocket socket, String string, ?timeout: Integer) -> void
+    def self.socket_write: (TCPSocket socket, String string, ?timeout: Integer) -> void
+
+    # Writes `strings` in full via a single `writev(2)` syscall when possible,
+    # falling back to per-string writes on partial results. Bounded by
+    # `timeout` so a slow client can't pin the writing thread.
+    #
+    # @param socket [TCPSocket] the socket to write to
+    # @param strings [Array<String>] the buffers to write in order
+    # @param timeout [Integer] seconds to wait for the socket to become writable on each retry
+    # @return [void]
+    # @raise [WriteError] if the socket is not writable within the timeout or raises IOError
+    #
+    # @rbs (TCPSocket socket, Array[String] strings, ?timeout: Integer) -> void
+    def self.socket_writev: (TCPSocket socket, Array[String] strings, ?timeout: Integer) -> void
+
+    # Writes a Common Log Format entry to `io`. Write failures are silently
+    # ignored.
+    #
+    # @param io [IO] the destination IO
+    # @param env [Hash] the Rack environment
+    # @param status [Integer] the response status code
+    # @param size [String] the response body size in bytes, or `-` if unknown
+    # @param remote_addr [String] the client IP address
+    # @return [void]
+    #
+    # @rbs (IO io, Hash[String, untyped] env, Integer status, String size, String remote_addr) -> void
+    def self.write_access_log: (IO io, Hash[String, untyped] env, Integer status, String size, String remote_addr) -> void
+  end
+end

data/sig/generated/raptor/{request.rbs → http1.rbs}

@@ -1,18 +1,20 @@
-# Generated from lib/raptor/request.rb with RBS::Inline
+# Generated from lib/raptor/http1.rb with RBS::Inline
 
 module Raptor
   # 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
+  class Http1
     BODY_BUFFER_THRESHOLD: untyped
 
     FILE_CHUNK_SIZE: untyped
 
+    MAX_CHUNK_OVERHEAD: untyped
+
     READ_BUFFER_SIZE: untyped
 
-    WRITE_TIMEOUT: ::Integer
+    RESPONSE_BUFFER_CAPACITY: untyped
 
     KEEPALIVE_READ_TIMEOUT: ::Float
 
@@ -28,20 +30,26 @@ module Raptor
 
     STATUS_WITH_NO_ENTITY_BODY: untyped
 
-    BAD_REQUEST_RESPONSE: ::String
+    CONTINUE_RESPONSE: ::String
 
-    INTERNAL_SERVER_ERROR_RESPONSE: ::String
+    BAD_REQUEST_RESPONSE: ::String
 
     CONTENT_TOO_LARGE_RESPONSE: ::String
 
+    INTERNAL_SERVER_ERROR_RESPONSE: ::String
+
     CONNECTION_CLOSE: ::String
 
     CONNECTION_KEEPALIVE: ::String
 
+    EXPECT_100_CONTINUE: ::String
+
     TRANSFER_ENCODING_CHUNKED: ::String
 
     HTTP_CONNECTION: ::String
 
+    HTTP_EXPECT: ::String
+
     HTTP_TRANSFER_ENCODING: ::String
 
     RACK_HEADER_PREFIX: ::String
@@ -54,19 +62,24 @@ module Raptor
 
     ILLEGAL_HEADER_VALUE_REGEX: ::Regexp
 
-    class Error < StandardError
-    end
-
-    class WriteError < Error
-      # @rbs () -> String
-      def message: () -> String
-    end
+    # Returns true when the message framing shows a request-smuggling vector
+    # per RFC 9112 section 6.3: a `Transfer-Encoding` where `chunked` is
+    # missing, not the final encoding, or duplicated; a `Transfer-Encoding`
+    # paired with a `Content-Length`; or a `Content-Length` containing any
+    # non-digit character.
+    #
+    # @param env [Hash] the Rack environment after header parsing
+    # @return [Boolean]
+    #
+    # @rbs (Hash[String, untyped] env) -> bool
+    def self.request_smuggling?: (Hash[String, untyped] env) -> bool
 
     # Decodes a chunked transfer-encoded body buffer.
     #
     # Returns the decoded bytes and a state symbol: `:complete` when the
     # terminating zero-length chunk was found, `:too_large` when the decoded
-    # size would exceed `max_size`, or `:incomplete` otherwise.
+    # size would exceed `max_size`, `:malformed` when chunk framing overhead
+    # exceeds `MAX_CHUNK_OVERHEAD`, or `:incomplete` otherwise.
     #
     # @param buffer [String] the raw body buffer to decode
     # @param max_size [Integer, nil] maximum decoded body size, or nil for unlimited
@@ -75,41 +88,62 @@ 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
 
+    @access_log_io: IO?
+
+    @max_keepalive_requests: Integer
+
     @body_spool_threshold: Integer?
 
     @max_body_size: Integer?
 
+    @write_timeout: Integer
+
     @server_port: Integer
 
     @app: ^(Hash[String, untyped]) -> [ Integer, Hash[String, String | Array[String]], untyped ]
 
-    # Creates a new Request handler.
+    # Creates a new Http1 handler.
     #
     # @param app [#call] the Rack application to dispatch complete requests to
     # @param server_port [Integer] port number used to populate SERVER_PORT in the Rack env
-    # @param client_options [Hash] client limits configuration
-    # @option client_options [Integer, nil] :max_body_size maximum request body size in bytes
-    # @option client_options [Integer, nil] :body_spool_threshold spool bodies larger than this to a tempfile
+    # @param connection_options [Hash] per-connection settings shared across protocols
+    # @option connection_options [Integer] :write_timeout per-write socket timeout in seconds
+    # @option connection_options [Integer, nil] :max_body_size maximum request body size in bytes
+    # @option connection_options [Integer, nil] :body_spool_threshold spool bodies larger than this to a tempfile
+    # @param http1_options [Hash] HTTP/1.1-specific settings
+    # @option http1_options [Integer] :max_keepalive_requests maximum requests per HTTP/1.1 keep-alive connection
+    # @param access_log_io [IO, nil] IO to write Common Log Format access entries to, or nil to disable
     # @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, ?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
+    # @rbs (^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped] app, Integer server_port, ?connection_options: Hash[Symbol, untyped], ?http1_options: Hash[Symbol, untyped], ?access_log_io: IO?, ?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, ?connection_options: Hash[Symbol, untyped], ?http1_options: Hash[Symbol, untyped], ?access_log_io: IO?, ?on_error: ^(Hash[String, untyped]?, Exception) -> void | nil) -> void
+
+    # Instance-level wrapper around {Http.socket_write} that applies the
+    # configured `write_timeout`.
+    #
+    # @param socket [TCPSocket] the socket to write to
+    # @param string [String] the data to write
+    # @return [void]
+    # @raise [Http::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
+
+    # Instance-level wrapper around {Http.socket_writev} that applies the
+    # configured `write_timeout`.
+    #
+    # @param socket [TCPSocket] the socket to write to
+    # @param strings [Array<String>] the buffers to write in order
+    # @return [void]
+    # @raise [Http::WriteError] if the socket is not writable within the timeout or raises IOError
+    #
+    # @rbs (TCPSocket socket, Array[String] strings) -> void
+    def socket_writev: (TCPSocket socket, Array[String] strings) -> void
 
     # Signals eager keep-alive loops to stop processing further requests on
     # their connections. In-flight requests complete normally.
@@ -160,6 +194,28 @@ module Raptor
 
     private
 
+    # Returns true if the request expects a 100 Continue response per
+    # RFC 7231 section 5.1.1.
+    #
+    # @param env [Hash] the parsed Rack environment (possibly incomplete)
+    # @return [Boolean]
+    #
+    # @rbs (Hash[String, untyped] env) -> bool
+    def expects_100_continue?: (Hash[String, untyped] env) -> bool
+
+    # Sends an HTTP 100 Continue response when an HTTP/1.1 client requested
+    # `Expect: 100-continue` and the request body has not yet been received.
+    #
+    # Returns the state hash with `:continued` set when the response has been
+    # written. A write failure is silently ignored.
+    #
+    # @param state [Hash] the partially-parsed connection state
+    # @param reactor [Reactor] the reactor holding the connection's socket
+    # @return [Hash] the state, with `:continued` set if 100 was written
+    #
+    # @rbs (Hash[Symbol, untyped] state, Reactor reactor) -> Hash[Symbol, untyped]
+    def send_continue_if_expected: (Hash[Symbol, untyped] state, Reactor reactor) -> Hash[Symbol, untyped]
+
     # Processes a client connection by handling the current request and,
     # if keep-alive, eagerly reading subsequent requests inline.
     #
@@ -278,6 +334,16 @@ module Raptor
     # @rbs (String? body) -> IO
     def build_rack_input: (String? body) -> IO
 
+    # Returns true when an upstream proxy signals that it terminated TLS for
+    # this request via `X-Forwarded-Proto`, `X-Forwarded-Scheme`, or
+    # `X-Forwarded-Ssl`. Only the first comma-separated value is consulted.
+    #
+    # @param env [Hash] the Rack environment
+    # @return [Boolean]
+    #
+    # @rbs (Hash[String, untyped] env) -> bool
+    def forwarded_https?: (Hash[String, untyped] env) -> bool
+
     # Determines whether the connection should be kept alive after the response.
     #
     # Returns false if the request limit has been reached. For HTTP/1.1, keep-alive
@@ -353,7 +419,8 @@ module Raptor
     # @rbs (Hash[String, String | Array[String]] headers, Integer status) -> void
     def validate_headers: (Hash[String, String | Array[String]] headers, Integer status) -> void
 
-    # Builds the HTTP status line string.
+    # Returns the HTTP status line for `status`. Callers must not retain the
+    # returned string across further calls on the same thread.
     #
     # @param http_version [String] "HTTP/1.1" or "HTTP/1.0"
     # @param status [Integer] HTTP status code
@@ -446,10 +513,7 @@ module Raptor
     # @rbs (TCPSocket socket, String response, Array[String] body_array, bool use_chunked) -> void
     def write_array_body: (TCPSocket socket, String response, Array[String] body_array, bool use_chunked) -> void
 
-    # Writes a single-element array body, optionally buffering it with the headers.
-    #
-    # Small bodies are concatenated with the headers into one write to reduce
-    # system call overhead.
+    # Writes a single-element array body to the socket.
     #
     # @param socket [TCPSocket] the client socket
     # @param response [String] headers already serialized, to be written before the body
@@ -526,6 +590,29 @@ 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
 
+    # Instance-level wrapper around {Http.write_access_log} that routes to
+    # the configured `@access_log_io`.
+    #
+    # @param env [Hash] the Rack environment
+    # @param status [Integer] the response status code
+    # @param size [String] the response body size in bytes, or `-` if unknown
+    # @param remote_addr [String] the client IP address
+    # @return [void]
+    #
+    # @rbs (Hash[String, untyped] env, Integer status, String size, String remote_addr) -> void
+    def write_access_log: (Hash[String, untyped] env, Integer status, String size, String remote_addr) -> void
+
+    # Returns the response body size as a String for the access log, taken
+    # from the `content-length` header when set, computed from the body
+    # otherwise, or `-` when the size cannot be determined upfront.
+    #
+    # @param headers [Hash] the response headers
+    # @param body [Object] the response body
+    # @return [String]
+    #
+    # @rbs (Hash[String, String | Array[String]] headers, untyped body) -> String
+    def response_size: (Hash[String, String | Array[String]] headers, untyped body) -> String
+
     # 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/http2.rbs

@@ -17,10 +17,15 @@ module Raptor
 
       @state: Atom
 
+      @write_timeout: Integer
+
       # Creates a new Writer.
       #
-      # @rbs () -> void
-      def initialize: () -> void
+      # @param write_timeout [Integer] per-write socket timeout passed through to {Http.socket_write}
+      # @return [void]
+      #
+      # @rbs (write_timeout: Integer) -> void
+      def initialize: (write_timeout: Integer) -> void
 
       # Writes frames to the socket, coordinating with concurrent writers
       # so that exactly one thread is actively writing at any time.
@@ -36,7 +41,7 @@ module Raptor
     # 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
+    # outbound DATA frames respect RFC 7540 section 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
@@ -93,7 +98,7 @@ module Raptor
       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.
+      # existing stream window by the delta as required by RFC 7540 section 6.9.2.
       #
       # @param new_size [Integer] the peer's new initial window size
       # @return [void]
@@ -140,28 +145,44 @@ module Raptor
 
     HOP_BY_HOP_HEADERS: untyped
 
+    @initial_settings_frame: String
+
     @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
 
+    @access_log_io: IO?
+
+    @write_timeout: Integer
+
     @server_port: Integer
 
     @app: ^(Hash[String, untyped]) -> [ Integer, Hash[String, String | Array[String]], untyped ]
 
+    # The initial server SETTINGS frame sent on every new HTTP/2 connection.
+    #
+    # @return [String] the encoded SETTINGS frame
+    attr_reader initial_settings_frame: untyped
+
     # Creates a new Http2 handler.
     #
     # @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 connection_options [Hash] per-connection settings shared across protocols
+    # @option connection_options [Integer] :write_timeout per-write socket timeout in seconds
+    # @param http2_options [Hash] HTTP/2-specific settings
+    # @option http2_options [Integer] :max_concurrent_streams maximum HTTP/2 concurrent streams per connection
+    # @param access_log_io [IO, nil] IO to write Common Log Format access entries to, or nil to disable
     # @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, ?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
+    # @rbs (^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped] app, Integer server_port, ?connection_options: Hash[Symbol, untyped], ?http2_options: Hash[Symbol, untyped], ?access_log_io: IO?, ?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, ?connection_options: Hash[Symbol, untyped], ?http2_options: Hash[Symbol, untyped], ?access_log_io: IO?, ?on_error: ^(Hash[String, untyped]?, Exception) -> void | nil) -> void
 
-    # Builds the initial server SETTINGS frame to send on connection establishment.
+    # Creates a per-connection {Writer} configured with the handler's write timeout.
     #
-    # @return [String] the encoded SETTINGS frame
+    # @return [Writer] a new per-connection frame writer
     #
-    # @rbs () -> String
-    def self.build_server_settings_frame: () -> String
+    # @rbs () -> Writer
+    def create_writer: () -> Writer
 
     # Processes HTTP/2 frames from the connection buffer.
     #
@@ -271,10 +292,10 @@ module Raptor
     # @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]
+    # @return [String] the response body size in bytes
     #
-    # @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
+    # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Integer status, Hash[String, String | Array[String]] headers, untyped body) -> String
+    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) -> String
 
     # Writes a 500 error response as HTTP/2 frames.
     #
@@ -286,6 +307,18 @@ module Raptor
     # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, Integer stream_id) -> void
     def write_http2_error_response: (OpenSSL::SSL::SSLSocket socket, Writer writer, Integer stream_id) -> void
 
+    # Instance-level wrapper around {Http.write_access_log} that routes to
+    # the configured `@access_log_io`.
+    #
+    # @param env [Hash] the Rack environment
+    # @param status [Integer] the response status code
+    # @param size [String] the response body size in bytes, or `-` if unknown
+    # @param remote_addr [String] the client IP address
+    # @return [void]
+    #
+    # @rbs (Hash[String, untyped] env, Integer status, String size, String remote_addr) -> void
+    def write_access_log: (Hash[String, untyped] env, Integer status, String size, String remote_addr) -> void
+
     # Builds a Rack environment hash from HTTP/2 headers and body.
     #
     # Translates HTTP/2 pseudo-headers into Rack-compatible environment keys