raptor 0.1.0 → 0.3.0

data/lib/raptor/http2.rb

@@ -3,6 +3,7 @@
 
 require "stringio"
 
+require "atomic-ruby/atom"
 require "rack"
 
 require_relative "raptor_http2"
@@ -16,6 +17,63 @@ module Raptor
   # pipeline used by HTTP/1.1 connections.
   #
   class Http2
+    # Lock-free per-connection frame writer.
+    #
+    # Serializes concurrent socket writes from multiple stream workers
+    # without blocking any of them.
+    #
+    class Writer
+      IDLE = :idle
+
+      # @rbs @state: Atom
+
+      # Creates a new Writer.
+      #
+      # @rbs () -> void
+      def initialize
+        @state = Atom.new(IDLE)
+      end
+
+      # Writes frames to the socket, coordinating with concurrent writers
+      # so that exactly one thread is actively writing at any time.
+      #
+      # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
+      # @param frames [Array<String>] frame bytes to write in order
+      # @return [void]
+      #
+      # @rbs (OpenSSL::SSL::SSLSocket socket, Array[String] frames) -> void
+      def write_frames(socket, frames)
+        return if frames.nil? || frames.empty?
+
+        claimed = false
+        @state.swap do |current|
+          if current.equal?(IDLE)
+            claimed = true
+            frames
+          else
+            claimed = false
+            current + frames
+          end
+        end
+
+        return unless claimed
+
+        loop do
+          pending = nil
+          @state.swap do |current|
+            pending = current
+            current.empty? ? IDLE : []
+          end
+
+          break if pending.empty?
+
+          pending.each do |frame|
+            socket.write(frame) rescue nil
+          end
+        end
+      end
+    end
+
     FLAG_END_STREAM = 0x1
     FLAG_END_HEADERS = 0x4
     FLAG_ACK = 0x1
@@ -27,17 +85,20 @@ module Raptor
 
     # @rbs @app: ^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped]
     # @rbs @server_port: Integer
+    # @rbs @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
 
     # 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 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(app, server_port)
+    # @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(app, server_port, on_error: nil)
       @app = app
       @server_port = server_port
+      @on_error = on_error
     end
 
     # Builds the initial server SETTINGS frame to send on connection establishment.
@@ -215,13 +276,9 @@ module Raptor
       socket = reactor.socket_for(result[:id])
       return unless socket
 
-      mutex = reactor.mutex_for(result[:id])
+      writer = reactor.writer_for(result[:id])
 
-      if result[:outgoing_frames]&.any?
-        mutex.synchronize do
-          result[:outgoing_frames].each { |frame| socket.write(frame) rescue nil }
-        end
-      end
+      writer.write_frames(socket, result[:outgoing_frames])
 
       reactor.update_http2_state(result)
 
@@ -231,7 +288,7 @@ module Raptor
 
         thread_pool << proc do
           dispatch_stream_request(
-            socket, mutex, stream_id,
+            socket, writer, stream_id,
             request[:headers], request[:body],
             remote_addr: remote_addr
           )
@@ -245,22 +302,27 @@ module Raptor
     # the response back as HTTP/2 frames.
     #
     # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
-    # @param mutex [Mutex] mutex for serializing writes to the connection socket
+    # @param writer [Writer] lock-free frame writer for the connection
     # @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, Mutex mutex, Integer stream_id, Array[[String, String]] headers, String body, remote_addr: String) -> void
-    def dispatch_stream_request(socket, mutex, stream_id, headers, body, remote_addr:)
+    # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, Integer stream_id, Array[[String, String]] headers, String body, remote_addr: String) -> void
+    def dispatch_stream_request(socket, writer, stream_id, headers, body, remote_addr:)
       env = build_rack_env(headers, body, remote_addr: remote_addr)
       status, response_headers, response_body = @app.call(env)
 
-      write_http2_response(socket, mutex, stream_id, status, response_headers, response_body)
-    rescue
-      write_http2_error_response(socket, mutex, stream_id)
-      raise
+      write_http2_response(socket, writer, stream_id, status, response_headers, response_body)
+    rescue => error
+      write_http2_error_response(socket, writer, stream_id)
+
+      if @on_error
+        @on_error.call(env, error) rescue nil
+      else
+        raise
+      end
     ensure
       response_body.close if response_body.respond_to?(:close)
     end
@@ -268,15 +330,15 @@ module Raptor
     # Writes a Rack response as HTTP/2 frames to the socket.
     #
     # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
-    # @param mutex [Mutex] mutex for serializing writes to the connection socket
+    # @param writer [Writer] lock-free frame writer for the connection
     # @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, Mutex mutex, Integer stream_id, Integer status, Hash[String, String | Array[String]] headers, untyped body) -> void
-    def write_http2_response(socket, mutex, stream_id, status, headers, body)
+    # @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(socket, writer, stream_id, status, headers, body)
       parser = Http2Parser.new
 
       header_pairs = [[":status", status.to_s]]
@@ -296,40 +358,38 @@ module Raptor
       body_chunks = []
       body.each { |chunk| body_chunks << chunk unless chunk.empty? }
 
-      mutex.synchronize do
-        if body_chunks.empty?
-          socket.write(parser.build_frame(:headers, FLAG_END_STREAM | FLAG_END_HEADERS, stream_id, encoded_headers))
-        else
-          socket.write(parser.build_frame(:headers, FLAG_END_HEADERS, stream_id, encoded_headers))
+      frames = []
+      if body_chunks.empty?
+        frames << parser.build_frame(:headers, FLAG_END_STREAM | FLAG_END_HEADERS, stream_id, encoded_headers)
+      else
+        frames << parser.build_frame(:headers, FLAG_END_HEADERS, stream_id, encoded_headers)
 
-          body_chunks.each_with_index do |chunk, index|
-            last = index == body_chunks.size - 1
-            flags = last ? FLAG_END_STREAM : 0
-            socket.write(parser.build_frame(:data, flags, stream_id, chunk))
-          end
+        last_index = body_chunks.size - 1
+        body_chunks.each_with_index do |chunk, index|
+          flags = index == last_index ? FLAG_END_STREAM : 0
+          frames << parser.build_frame(:data, flags, stream_id, chunk)
         end
       end
-    rescue IOError, Errno::EPIPE
-      # Connection closed
+
+      writer.write_frames(socket, frames)
     end
 
     # Writes a 500 error response as HTTP/2 frames.
     #
     # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
-    # @param mutex [Mutex] mutex for serializing writes to the connection socket
+    # @param writer [Writer] lock-free frame writer for the connection
     # @param stream_id [Integer] the HTTP/2 stream identifier
     # @return [void]
     #
-    # @rbs (OpenSSL::SSL::SSLSocket socket, Mutex mutex, Integer stream_id) -> void
-    def write_http2_error_response(socket, mutex, stream_id)
+    # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, Integer stream_id) -> void
+    def write_http2_error_response(socket, writer, stream_id)
       parser = Http2Parser.new
       encoded = parser.encode_headers([[":status", "500"]])
 
-      mutex.synchronize do
-        socket.write(parser.build_frame(:headers, FLAG_END_STREAM | FLAG_END_HEADERS, stream_id, encoded))
-      end
-    rescue IOError, Errno::EPIPE
-      # Connection closed
+      writer.write_frames(
+        socket,
+        [parser.build_frame(:headers, FLAG_END_STREAM | FLAG_END_HEADERS, stream_id, encoded)]
+      )
     end
 
     # Builds a Rack environment hash from HTTP/2 headers and body.

data/lib/raptor/reactor.rb

@@ -75,7 +75,7 @@ module Raptor
     # @rbs @id_to_socket: Hash[Integer, TCPSocket]
     # @rbs @socket_to_state: Hash[TCPSocket, Hash[Symbol, untyped]]
     # @rbs @id_to_timeout: Hash[Integer, TimeoutClient]
-    # @rbs @id_to_mutex: Hash[Integer, Mutex]
+    # @rbs @id_to_writer: Hash[Integer, untyped]
 
     # Creates a new Reactor instance.
     #
@@ -100,7 +100,7 @@ module Raptor
       @id_to_socket = {}
       @socket_to_state = {}
       @id_to_timeout = {}
-      @id_to_mutex = {}
+      @id_to_writer = {}
     end
 
     # Starts the reactor's main event loop in a new thread.
@@ -162,12 +162,10 @@ module Raptor
     def add(state)
       socket = state[:socket]
       state.delete(:socket)
+      writer = state.delete(:writer)
       @id_to_socket[state[:id]] = socket
       @socket_to_state[socket] = state
-
-      if state[:protocol] == :http2
-        @id_to_mutex[state[:id]] = Mutex.new
-      end
+      @id_to_writer[state[:id]] = writer if writer
 
       read_and_queue_for_parse(socket, state)
     end
@@ -252,14 +250,16 @@ module Raptor
       @id_to_socket[id]
     end
 
-    # Returns the mutex for a given HTTP/2 connection.
+    # Returns the writer object associated with a given connection, if one
+    # was supplied when the connection was added. Used by protocol handlers
+    # that need to coordinate concurrent socket writes.
     #
     # @param id [Integer] unique client identifier
-    # @return [Mutex, nil] the mutex, if found
+    # @return [Object, nil] the writer, if found
     #
-    # @rbs (Integer id) -> Mutex?
-    def mutex_for(id)
-      @id_to_mutex[id]
+    # @rbs (Integer id) -> untyped?
+    def writer_for(id)
+      @id_to_writer[id]
     end
 
     # Updates connection state for an HTTP/2 connection after frame processing.
@@ -384,7 +384,7 @@ module Raptor
     def cleanup(socket)
       state = @socket_to_state.delete(socket)
       @id_to_socket.delete(state[:id])
-      @id_to_mutex.delete(state[:id])
+      @id_to_writer.delete(state[:id])
       socket.close
     end
 

data/lib/raptor/request.rb

@@ -3,6 +3,7 @@
 
 require "socket"
 require "stringio"
+require "tempfile"
 
 require "rack"
 
@@ -20,7 +21,7 @@ module Raptor
   class Request
     BODY_BUFFER_THRESHOLD = 256 * 1024
     FILE_CHUNK_SIZE = 64 * 1024
-    KEEPALIVE_BUFFER_SIZE = 64 * 1024
+    READ_BUFFER_SIZE = 64 * 1024
     WRITE_TIMEOUT = 5
     KEEPALIVE_READ_TIMEOUT = 0.001
     MAX_KEEPALIVE_REQUESTS = 100
@@ -38,7 +39,8 @@ module Raptor
     end
 
     STATUS_WITH_NO_ENTITY_BODY = Set.new([204, 304, *100..199]).freeze
-    ERROR_RESPONSE_500 = "HTTP/1.1 500 Internal Server Error\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
+    INTERNAL_SERVER_ERROR_RESPONSE = "HTTP/1.1 500 Internal Server Error\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
+    CONTENT_TOO_LARGE_RESPONSE = "HTTP/1.1 413 Content Too Large\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
 
     CONNECTION_CLOSE = "close"
     CONNECTION_KEEPALIVE = "keep-alive"
@@ -59,19 +61,136 @@ module Raptor
       def message = "could not write response"
     end
 
+    # 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.
+    #
+    # @param buffer [String] the raw body buffer to decode
+    # @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(buffer, max_size = nil)
+      decoded = String.new
+      offset = 0
+
+      while offset < buffer.bytesize
+        crlf = buffer.index("\r\n", offset)
+        return [decoded, :incomplete] unless crlf
+
+        chunk_size = buffer.byteslice(offset, crlf - offset).to_i(16)
+        return [decoded, :complete] if chunk_size == 0
+        return [decoded, :too_large] if max_size && decoded.bytesize + chunk_size > max_size
+
+        offset = crlf + 2
+        decoded << buffer.byteslice(offset, chunk_size)
+        offset += chunk_size + 2
+      end
+
+      [decoded, :incomplete]
+    end
+
     # @rbs @app: ^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped]
     # @rbs @server_port: Integer
+    # @rbs @max_body_size: Integer?
+    # @rbs @body_spool_threshold: Integer?
+    # @rbs @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
 
     # Creates a new Request 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 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(app, server_port)
+    # @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(app, server_port, client_options: {}, on_error: nil)
       @app = app
       @server_port = server_port
+      @max_body_size = client_options[:max_body_size]
+      @body_spool_threshold = client_options[:body_spool_threshold]
+      @on_error = on_error
+    end
+
+    # 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.
+    #
+    # @param socket [TCPSocket] the freshly accepted client socket
+    # @param id [Integer] unique client identifier
+    # @param reactor [Reactor] the reactor for fallback registration
+    # @param thread_pool [AtomicThreadPool] thread pool for application processing
+    # @param remote_addr [String] client IP address
+    # @param url_scheme [String] "http" or "https"
+    # @return [void]
+    #
+    # @rbs (TCPSocket socket, Integer id, Reactor reactor, AtomicThreadPool thread_pool, String remote_addr, String url_scheme) -> void
+    def eager_accept(socket, id, reactor, thread_pool, remote_addr, url_scheme)
+      data = begin
+        socket.read_nonblock(READ_BUFFER_SIZE)
+      rescue IO::WaitReadable
+        reactor.add(
+          id: id,
+          socket: socket,
+          remote_addr: remote_addr,
+          url_scheme: url_scheme
+        )
+        return
+      rescue EOFError, IOError
+        socket.close rescue nil
+        return
+      end
+
+      buffer = String.new
+      buffer << data
+
+      while socket.respond_to?(:pending) && socket.pending > 0
+        buffer << socket.read_nonblock(socket.pending)
+      end
+
+      parser = HttpParser.new
+      env = {}
+      nread = parser.execute(env, buffer, 0)
+      parse_data = { parse_count: 1, content_length: parser.content_length }
+
+      body = nil
+      if !parser.finished?
+        fallback_to_reactor(socket, id, buffer, env, parse_data, reactor, 0, remote_addr, url_scheme, persisted: false)
+        return
+      elsif parser.has_body?
+        if @max_body_size && parser.content_length > @max_body_size
+          reject_oversized(socket)
+          return
+        end
+
+        body = buffer.byteslice(nread..-1) || ""
+
+        if env[HTTP_TRANSFER_ENCODING]&.include?(TRANSFER_ENCODING_CHUNKED)
+          body, chunked_state = Request.decode_chunked(body, @max_body_size)
+          case chunked_state
+          when :complete
+            env.delete(HTTP_TRANSFER_ENCODING)
+          when :too_large
+            reject_oversized(socket)
+            return
+          else
+            fallback_to_reactor(socket, id, buffer, env, parse_data, reactor, 0, remote_addr, url_scheme, persisted: false)
+            return
+          end
+        elsif parser.content_length > body.bytesize
+          fallback_to_reactor(socket, id, buffer, env, parse_data, reactor, 0, remote_addr, url_scheme, persisted: false)
+          return
+        end
+      end
+
+      thread_pool << proc do
+        process_client(socket, id, env, parse_data, body, reactor, thread_pool, 1, remote_addr, url_scheme)
+      end
     end
 
     # Returns a Proc for HTTP parsing work in Ractor context.
@@ -84,6 +203,8 @@ module Raptor
     #
     # @rbs () -> ^(Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
     def http_parser_worker
+      max_body_size = @max_body_size
+
       proc do |data|
         next Raptor::Http2.process_frames(data) if data[:protocol] == :http2
 
@@ -101,30 +222,17 @@ module Raptor
           if parser.has_body?
             body_buffer = data[:buffer].byteslice(nread..-1) || ""
 
-            if env[HTTP_TRANSFER_ENCODING]&.include?(TRANSFER_ENCODING_CHUNKED)
-              decoded_body = String.new
-              offset = 0
-              chunked_complete = false
+            if max_body_size && parser.content_length > max_body_size
+              data.merge(env: env, body: nil, parse_data: parse_data, complete: true, too_large: true)
+            elsif env[HTTP_TRANSFER_ENCODING]&.include?(TRANSFER_ENCODING_CHUNKED)
+              decoded_body, chunked_state = Raptor::Request.decode_chunked(body_buffer, max_body_size)
 
-              while offset < body_buffer.bytesize
-                crlf = body_buffer.index("\r\n", offset)
-                break unless crlf
-
-                chunk_size = body_buffer.byteslice(offset, crlf - offset).to_i(16)
-
-                if chunk_size == 0
-                  chunked_complete = true
-                  break
-                end
-
-                offset = crlf + 2
-                decoded_body << body_buffer.byteslice(offset, chunk_size)
-                offset += chunk_size + 2
-              end
-
-              if chunked_complete
+              case chunked_state
+              when :complete
                 env.delete(HTTP_TRANSFER_ENCODING)
                 data.merge(env: env, body: decoded_body, parse_data: parse_data, complete: true)
+              when :too_large
+                data.merge(env: env, body: nil, parse_data: parse_data, complete: true, too_large: true)
               else
                 data.merge(env: env, parse_data: parse_data)
               end
@@ -155,6 +263,12 @@ module Raptor
     #
     # @rbs (Hash[Symbol, untyped] parsed_request, Reactor reactor, AtomicThreadPool thread_pool) -> void
     def handle_parsed_request(parsed_request, reactor, thread_pool)
+      if parsed_request[:too_large]
+        socket = reactor.remove(parsed_request[:id])
+        reject_oversized(socket) if socket
+        return
+      end
+
       unless parsed_request[:complete]
         reactor.update_state(parsed_request)
       else
@@ -244,10 +358,18 @@ module Raptor
         keep_alive && !hijacked
       rescue => error
         call_response_finished(rack_env, status, headers, error) if rack_env
-        socket.write(ERROR_RESPONSE_500) rescue nil unless response_started || hijacked
+        socket.write(INTERNAL_SERVER_ERROR_RESPONSE) rescue nil unless response_started || hijacked
         keep_alive = false
-        raise
+
+        if @on_error
+          @on_error.call(rack_env, error) rescue nil
+        else
+          raise
+        end
       ensure
+        rack_input = rack_env && rack_env[Rack::RACK_INPUT]
+        rack_input.close! rescue nil if rack_input.respond_to?(:close!)
+
         unless hijacked || keep_alive
           socket.close rescue nil
         end
@@ -278,7 +400,7 @@ module Raptor
         end
 
         data = begin
-          socket.read_nonblock(KEEPALIVE_BUFFER_SIZE)
+          socket.read_nonblock(READ_BUFFER_SIZE)
         rescue IO::WaitReadable
           reactor.persist(socket, id, request_count, remote_addr: remote_addr, url_scheme: url_scheme)
           return
@@ -346,8 +468,12 @@ module Raptor
       end
     end
 
-    # Re-registers a socket with the reactor for further processing
-    # when an incomplete request is received during eager keep-alive.
+    # Re-registers a socket with the reactor for further processing when
+    # an incomplete request is received during eager accept or eager keep-alive.
+    #
+    # The persisted flag selects between persistent_data_timeout (for
+    # kept-alive connections awaiting the next request) and chunk_data_timeout
+    # (for fresh connections awaiting the rest of the first request).
     #
     # @param socket [TCPSocket] the client socket
     # @param id [Integer] unique client identifier
@@ -358,21 +484,35 @@ module Raptor
     # @param request_count [Integer] number of requests handled on this connection
     # @param remote_addr [String] client IP address
     # @param url_scheme [String] "http" or "https"
+    # @param persisted [Boolean] whether the connection has already completed at least one request
     # @return [void]
     #
-    # @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) -> void
-    def fallback_to_reactor(socket, id, buffer, env, parse_data, reactor, request_count, remote_addr, url_scheme)
+    # @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(socket, id, buffer, env, parse_data, reactor, request_count, remote_addr, url_scheme, persisted: true)
       reactor.persist(socket, id, request_count, remote_addr: remote_addr, url_scheme: url_scheme)
-      reactor.update_state(Ractor.make_shareable({
+      state = {
         id: id,
         buffer: buffer,
         env: env,
         request_count: request_count,
         parse_data: parse_data,
         remote_addr: remote_addr,
-        url_scheme: url_scheme,
-        persisted: true
-      }))
+        url_scheme: url_scheme
+      }
+      state[:persisted] = true if persisted
+      reactor.update_state(Ractor.make_shareable(state))
+    end
+
+    # 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(socket)
+      socket.write(CONTENT_TOO_LARGE_RESPONSE) rescue nil
+      socket.close rescue nil
     end
 
     # Builds a Rack environment hash from parsed HTTP request data.
@@ -392,7 +532,7 @@ module Raptor
     def build_rack_env(env, parse_data, body, socket, remote_addr: "127.0.0.1", url_scheme: HTTP_SCHEME)
       env[Rack::RACK_VERSION] = Rack::VERSION
       env[Rack::RACK_URL_SCHEME] = url_scheme
-      env[Rack::RACK_INPUT] = (body ? StringIO.new(body) : StringIO.new).set_encoding(Encoding::ASCII_8BIT)
+      env[Rack::RACK_INPUT] = build_rack_input(body)
       env[Rack::RACK_ERRORS] = $stderr
       env[Rack::RACK_RESPONSE_FINISHED] = []
 
@@ -436,6 +576,26 @@ module Raptor
       env
     end
 
+    # 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(body)
+      if body && @body_spool_threshold && body.bytesize > @body_spool_threshold
+        tempfile = Tempfile.new("raptor-body")
+        tempfile.binmode
+        tempfile.write(body)
+        tempfile.rewind
+        tempfile
+      else
+        (body ? StringIO.new(body) : StringIO.new).set_encoding(Encoding::ASCII_8BIT)
+      end
+    end
+
     # 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