raptor 0.2.0 → 0.4.0

data/sig/generated/raptor/request.rbs

@@ -33,7 +33,11 @@ module Raptor
 
     STATUS_WITH_NO_ENTITY_BODY: untyped
 
-    ERROR_RESPONSE_500: ::String
+    BAD_REQUEST_RESPONSE: ::String
+
+    INTERNAL_SERVER_ERROR_RESPONSE: ::String
+
+    CONTENT_TOO_LARGE_RESPONSE: ::String
 
     CONNECTION_CLOSE: ::String
 
@@ -65,15 +69,37 @@ module Raptor
 
     # Decodes a chunked transfer-encoded body buffer.
     #
-    # Returns the decoded bytes and a flag indicating whether the terminating
-    # zero-length chunk was found. The decoder stops at the first unparseable
-    # boundary (incomplete CRLF) or zero-length chunk.
+    # 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.
     #
     # @param buffer [String] the raw body buffer to decode
-    # @return [Array(String, Boolean)] decoded body and completion flag
+    # @param max_size [Integer, nil] maximum decoded body size, or nil for unlimited
+    # @return [Array(String, Symbol)] decoded body and completion state
+    #
+    # @rbs (String buffer, ?Integer? max_size) -> [String, Symbol]
+    def self.decode_chunked: (String buffer, ?Integer? max_size) -> [ String, Symbol ]
+
+    # Writes a string to the socket, retrying on partial writes and flow control blocks.
+    #
+    # Uses write_nonblock with `WRITE_TIMEOUT` to avoid blocking the thread
+    # indefinitely on slow clients.
     #
-    # @rbs (String buffer) -> [String, bool]
-    def self.decode_chunked: (String buffer) -> [ String, bool ]
+    # @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?
+
+    @max_body_size: Integer?
 
     @server_port: Integer
 
@@ -83,10 +109,22 @@ module Raptor
     #
     # @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 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, ?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
@@ -203,6 +241,24 @@ module Raptor
     # @rbs (TCPSocket socket, Integer id, String buffer, Hash[String, untyped] env, Hash[Symbol, untyped] parse_data, Reactor reactor, Integer request_count, String remote_addr, String url_scheme, persisted: bool) -> void
     def fallback_to_reactor: (TCPSocket socket, Integer id, String buffer, Hash[String, untyped] env, Hash[Symbol, untyped] parse_data, Reactor reactor, Integer request_count, String remote_addr, String url_scheme, persisted: bool) -> void
 
+    # Writes a 413 response and closes the socket. Used when a request body
+    # exceeds the configured maximum size.
+    #
+    # @param socket [TCPSocket] the client socket
+    # @return [void]
+    #
+    # @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,
@@ -219,6 +275,16 @@ module Raptor
     # @rbs (Hash[String, untyped] env, Hash[Symbol, untyped] parse_data, String? body, TCPSocket socket, ?remote_addr: String, ?url_scheme: String) -> Hash[String, untyped]
     def build_rack_env: (Hash[String, untyped] env, Hash[Symbol, untyped] parse_data, String? body, TCPSocket socket, ?remote_addr: String, ?url_scheme: String) -> Hash[String, untyped]
 
+    # Builds the `rack.input` IO object for the request body. Returns an
+    # in-memory StringIO for bodies up to the spool threshold, or a Tempfile
+    # for larger bodies to bound per-worker memory.
+    #
+    # @param body [String, nil] decoded request body
+    # @return [IO] an IO-like object positioned at the start of the body
+    #
+    # @rbs (String? body) -> IO
+    def build_rack_input: (String? body) -> IO
+
     # 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
@@ -467,19 +533,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

@@ -9,8 +9,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
@@ -22,7 +22,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
@@ -33,15 +33,17 @@ module Raptor
 
     H2_PROTOCOL: ::String
 
-    @binder: Binder
+    @running: AtomicBoolean
 
-    @reactor: Reactor
+    @client_options: Hash[Symbol, untyped]
+
+    @request: Request
 
     @thread_pool: AtomicThreadPool
 
-    @request: Request
+    @reactor: Reactor
 
-    @running: AtomicBoolean
+    @binder: Binder
 
     # Creates a new Server instance.
     #
@@ -49,10 +51,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 +83,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 +95,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

data/sig/generated/raptor.rbs

@@ -2,8 +2,8 @@
 
 # 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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raptor
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Joshua Young