raptor 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8391f9399db2e88dab106ad995a34060e6ae07f34c84825bfdcb066cd129dad4
-  data.tar.gz: 25cb3658e2aded284f302b84a1ee91d67344a5b5dd36c6c0e854381cfb4df048
+  metadata.gz: 7c247b4c221d0f19ff1383ca0a4092a54bc12cd2f945655fa24e1ab49745eb70
+  data.tar.gz: cb932a7a048d87eb0913f8c0dbe52750ea4e525e4c4dc32e5fcc531af0daaf41
 SHA512:
-  metadata.gz: e398237ccb391aff663c4d75e5470c0e4e0e6f6b273e26bface4cd6793691c3297053ab0a5d744deac8fd087c4f7dec0beb8426d8a762d3a089902d11dbe53e5
-  data.tar.gz: c4cfd5f7ffdcf7f970cc8c85868629bac6c6061312120c0dc2a3c64fa6431cf475bc8fbb877dce0bad3febc2bd87ccc5342e2bc9c8dad196c69306431ae91345
+  metadata.gz: d8e1543054862e8a87c7261884348456da13d4432c3424687b74f506b884283d2773068b6beb10cbe9e209e969b98a918720861b3d0e05bc04d930ba38ec1921
+  data.tar.gz: f215cc4a92af86542d49f2c4772f0a65af09988779bbb1c44512ab075d4fb5c0758cb51d9765a0ee9d08fe340d31b42cea1610b021c443818fe40fbdcea63b93

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-05-25
+
+- Load cluster options from a Ruby config file via `--config`
+- Replace workers one at a time on `SIGUSR2` (phased restart)
+- Invoke `:on_error` callback with `(env, exception)` when the Rack app raises
+- Spool request bodies larger than `--body-spool-threshold` to a tempfile
+- Reject HTTP/1.1 requests larger than `--max-body-size` with a 413 response
+- Write pidfile via `--pidfile`
+- Set `SO_REUSEPORT` on TCP listeners where supported
+
 ## [0.2.0] - 2026-05-25
 
 - Add Rack handler for booting via `rackup` or `rails server`

data/README.md

@@ -1,8 +1,8 @@
 # Raptor
 
-Raptor is a high-performance, multi-threaded, multi-process Ruby Rack 3 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.
 
 ## Installation
 
@@ -31,9 +31,9 @@ run proc { |_env| [200, { "content-type" => "text/plain" }, ["Hello, World!"]] }
 ```
 > bundle exec raptor -t 3 -w 4 hello_world.ru
 Raptor Cluster initializing:
-├─ Version: 0.1.0
+├─ Version: 0.3.0
 ├─ Ruby Version: ruby 4.0.4 (2026-05-12 revision b89eb1bcbf) +YJIT +PRISM [arm64-darwin23]
-├─ Master PID: 71052
+├─ Master PID: 31504
 │  └─ 4 worker processes
 │     ├─ 1 server thread
 │     ├─ 1 reactor thread
@@ -42,10 +42,10 @@ Raptor Cluster initializing:
 │     ├─ 3 worker threads
 │     └─ 1 stats thread
 └─ Listening on 0.0.0.0:9292
-[71054] Worker 0 booted
-[71055] Worker 1 booted
-[71056] Worker 2 booted
-[71057] Worker 3 booted
+[31506] Worker 0 booted
+[31507] Worker 1 booted
+[31508] Worker 2 booted
+[31509] Worker 3 booted
 ```
 
 ```
@@ -60,9 +60,9 @@ Also works with `rackup` and `rails server`:
 > bundle exec rails server -u raptor
 ```
 
-## Benchmarks
+## (Micro) Benchmarks
 
-Raptor 0.1.0 vs Puma 8.0.1:
+Raptor 0.3.0 vs Puma 8.0.1:
 
 | Protocol              | Raptor       | Puma         |
 | --------------------- | ------------ | ------------ |

data/lib/rackup/handler/raptor.rb

@@ -44,7 +44,8 @@ module Rackup
           "Port=PORT"   => "Port to listen on (default: #{DEFAULT_OPTIONS[:Port]})",
           "Threads=NUM" => "Number of threads per worker (default: 3)",
           "Ractors=NUM" => "Number of pipeline ractors per worker (default: 1)",
-          "Workers=NUM" => "Number of worker processes (default: nprocessors)"
+          "Workers=NUM" => "Number of worker processes (default: nprocessors)",
+          "Config=PATH" => "Load additional configuration from PATH"
         }
       end
 
@@ -67,20 +68,31 @@ module Rackup
           end
         end
 
-        host = options[:Host] || defaults[:Host]
-        port = options[:Port] || defaults[:Port]
-
         cli_defaults = ::Raptor::CLI::DEFAULT_OPTIONS
+        config = options[:Config] ? ::Raptor::CLI.load_config_file(options[:Config]) : {}
 
-        {
+        binds = if options[:Host] || options[:Port]
+          host = options[:Host] || defaults[:Host]
+          port = options[:Port] || defaults[:Port]
+          ["tcp://#{host}:#{port}"]
+        else
+          config[:binds] || ["tcp://#{defaults[:Host]}:#{defaults[:Port]}"]
+        end
+
+        result = {
           app: app,
-          binds: ["tcp://#{host}:#{port}"],
-          threads: (options[:Threads] || cli_defaults[:threads]).to_i,
-          ractors: (options[:Ractors] || cli_defaults[:ractors]).to_i,
-          workers: (options[:Workers] || Etc.nprocessors).to_i,
-          client: cli_defaults[:client],
-          stats_file: nil
+          binds: binds,
+          threads: (options[:Threads] || config[:threads] || cli_defaults[:threads]).to_i,
+          ractors: (options[:Ractors] || config[:ractors] || cli_defaults[:ractors]).to_i,
+          workers: (options[:Workers] || config[:workers] || Etc.nprocessors).to_i,
+          client: cli_defaults[:client].merge(config[:client] || {})
         }
+
+        [:rackup, :on_error, :stats_file, :pidfile].each do |key|
+          result[key] = config[key] if config.key?(key)
+        end
+
+        result
       end
       private_class_method :build_cluster_options
     end

data/lib/raptor/binder.rb

@@ -173,6 +173,7 @@ module Raptor
 
       tcp_server = TCPServer.new(host, port)
       tcp_server.setsockopt(Socket::SOL_SOCKET, Socket::SO_REUSEADDR, true)
+      tcp_server.setsockopt(Socket::SOL_SOCKET, Socket::SO_REUSEPORT, true) if Socket.const_defined?(:SO_REUSEPORT)
       tcp_server.listen SOCKET_BACKLOG
 
       [tcp_server]

data/lib/raptor/cli.rb

@@ -32,14 +32,35 @@ module Raptor
       ractors: 1,
       workers: DEFAULT_WORKER_COUNT,
       rackup: "config.ru",
-      stats_file: "tmp/raptor.json",
       client: {
         first_data_timeout: 30,
         chunk_data_timeout: 10,
         persistent_data_timeout: 65,
+        max_body_size: nil,
+        body_spool_threshold: 1024 * 1024,
       },
+      stats_file: "tmp/raptor.json",
+      pidfile: nil,
     }.freeze
 
+    # 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(path)
+      config = eval(File.read(path), TOPLEVEL_BINDING, path, 1)
+      raise ArgumentError, "Config file at #{path.inspect} must return a Hash, got #{config.class}" unless config.is_a?(Hash)
+
+      config
+    end
+
     # @rbs @command: Symbol
     # @rbs @options: Hash[Symbol, untyped]
     # @rbs @parser: OptionParser
@@ -70,6 +91,9 @@ module Raptor
       end
       @options = DEFAULT_OPTIONS.dup
       @options[:client] = @options[:client].dup
+
+      apply_config_file(extract_config_path(argv))
+
       @parser = create_parser
       @parser.parse!(argv)
 
@@ -111,6 +135,49 @@ module Raptor
       end
     end
 
+    # 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(argv)
+      argv.each_with_index do |arg, i|
+        case arg
+        when "-c", "--config" then return argv[i + 1]
+        when /\A--config=(.*)\z/, /\A-c(.+)\z/ then return Regexp.last_match(1)
+        end
+      end
+      nil
+    end
+
+    # 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(path)
+      return unless path
+
+      config = self.class.load_config_file(path)
+      config.each do |key, value|
+        if key == :client && value.is_a?(Hash)
+          @options[:client] = @options[:client].merge(value)
+        else
+          @options[key] = value
+        end
+      end
+    end
+
     # Creates the OptionParser instance with all supported command-line options.
     #
     # @return [OptionParser] configured option parser
@@ -120,6 +187,10 @@ module Raptor
       OptionParser.new do |opts|
         opts.banner = "Usage: raptor [options] [rackup file]"
 
+        opts.on("-c", "--config PATH", String, "Load configuration from PATH") do
+          # Loaded in #initialize before parsing so CLI args can override config values
+        end
+
         opts.on("-b", "--bind URI", String, "Bind address (default: tcp://0.0.0.0:9292)") do |bind|
           if @options[:binds] == DEFAULT_OPTIONS[:binds]
             @options[:binds] = [bind]
@@ -152,10 +223,22 @@ module Raptor
           @options[:client][:persistent_data_timeout] = timeout
         end
 
+        opts.on("--max-body-size BYTES", Integer, "Maximum request body size in bytes (default: unlimited)") do |bytes|
+          @options[:client][:max_body_size] = bytes
+        end
+
+        opts.on("--body-spool-threshold BYTES", Integer, "Spool request bodies larger than this to a tempfile (default: #{1024 * 1024})") do |bytes|
+          @options[:client][:body_spool_threshold] = bytes
+        end
+
         opts.on("--stats-file PATH", String, "Stats file path (default: tmp/raptor.json)") do |path|
           @options[:stats_file] = path
         end
 
+        opts.on("--pidfile PATH", String, "Pidfile path (default: none)") do |path|
+          @options[:pidfile] = path
+        end
+
         opts.on("--help", "Show this help") do
           puts opts
           exit

data/lib/raptor/cluster.rb

@@ -58,13 +58,17 @@ module Raptor
     # @rbs @ractor_count: Integer
     # @rbs @worker_count: Integer
     # @rbs @client_options: Hash[Symbol, Integer]
+    # @rbs @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
+    # @rbs @stats_file: String?
+    # @rbs @pidfile: String?
     # @rbs @binder: Binder
     # @rbs @server_port: Integer
     # @rbs @app: untyped
     # @rbs @shutdown: bool
     # @rbs @workers: Hash[Integer, Integer]
     # @rbs @stats: Stats
-    # @rbs @stats_file: String?
+    # @rbs @phased_restart_requested: bool
+    # @rbs @phased_restarting: bool
 
     # Creates a new Cluster with the specified configuration.
     #
@@ -79,7 +83,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] :pidfile path to write the master PID to, or nil to disable
     # @return [void]
     #
     # @rbs (Hash[Symbol, untyped] options) -> void
@@ -88,6 +95,9 @@ module Raptor
       @ractor_count = options[:ractors]
       @worker_count = options[:workers]
       @client_options = options[:client]
+      @on_error = options[:on_error]
+      @stats_file = options[:stats_file]
+      @pidfile = options[:pidfile]
 
       @binder = Binder.new(options[:binds])
       @server_port = @binder.server_port
@@ -97,14 +107,16 @@ module Raptor
       @shutdown = false
       @workers = {}
       @stats = Stats.new(@worker_count)
-      @stats_file = options[:stats_file]
+      @phased_restart_requested = false
+      @phased_restarting = false
     end
 
     # Starts the multi-process cluster and manages worker processes.
     #
     # 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)
@@ -121,6 +133,9 @@ module Raptor
       trap("INT") { shutdown }
       trap("TERM") { shutdown }
       trap("USR1") { log_stats }
+      trap("USR2") { @phased_restart_requested = true }
+
+      File.open(@pidfile, File::CREAT | File::EXCL | File::WRONLY) { |file| file.write(Process.pid.to_s) } if @pidfile
 
       @worker_count.times { |index| spawn_worker(index) }
 
@@ -133,29 +148,18 @@ module Raptor
       end
 
       until @shutdown
-        begin
-          pid, status = Process.wait2(-1, Process::WNOHANG)
-        rescue Errno::ECHILD
-          break
-        end
+        break if reap_workers == :no_children
 
-        if pid
-          index = @workers.key(pid)
-          @workers.delete(index)
+        perform_phased_restart if @phased_restart_requested && !@phased_restarting
 
-          unless @shutdown
-            warn "[#{Process.pid}] Restarting worker #{index} (#{pid}), #{exit_description(status)}"
-            spawn_worker(index)
-          end
-        else
-          sleep 0.1
-        end
+        sleep 0.1
       end
 
       @workers.values.each { |pid| Process.kill("TERM", pid) rescue nil }
       @workers.values.each { |pid| Process.wait(pid) rescue nil }
       stats_file_thread&.join
       File.delete(@stats_file) rescue nil if @stats_file
+      File.delete(@pidfile) rescue nil if @pidfile
       @stats.unmap
     end
 
@@ -182,6 +186,66 @@ module Raptor
       @workers[index] = pid
     end
 
+    # 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
+      loop do
+        pid, status = Process.wait2(-1, Process::WNOHANG)
+        return :reaped unless pid
+
+        index = @workers.key(pid)
+        @workers.delete(index)
+
+        unless @shutdown
+          warn "[#{Process.pid}] Restarting worker #{index} (#{pid}), #{exit_description(status)}"
+          spawn_worker(index)
+        end
+      end
+    rescue Errno::ECHILD
+      :no_children
+    end
+
+    # 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
+      @phased_restart_requested = false
+      @phased_restarting = true
+      puts "[#{Process.pid}] Phased restart starting"
+
+      begin
+        @workers.keys.sort.each do |index|
+          return if @shutdown
+
+          target_pid = @workers[index]
+          next unless target_pid
+
+          Process.kill("TERM", target_pid) rescue nil
+
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 60
+          until @shutdown
+            reap_workers
+            current = @workers[index]
+            break if current && current != target_pid && @stats.all[index][:booted]
+            break if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+
+            sleep 0.1
+          end
+        end
+
+        puts "[#{Process.pid}] Phased restart complete"
+      ensure
+        @phased_restarting = false
+      end
+    end
+
     # Runs the full server stack inside a worker process.
     #
     # Sets up and coordinates the reactor, server, ractor pool, thread pool,
@@ -217,8 +281,8 @@ module Raptor
         @app.call(env)
       }
       thread_pool = AtomicThreadPool.new(name: "Raptor Workers", size: @thread_count)
-      request = Request.new(counting_app, @server_port)
-      http2 = Http2.new(counting_app, @server_port)
+      request = Request.new(counting_app, @server_port, client_options: @client_options, on_error: @on_error)
+      http2 = Http2.new(counting_app, @server_port, on_error: @on_error)
       ractor_pool = RactorPool.new(
         name: "Raptor Pipeline Workers",
         size: @ractor_count,

data/lib/raptor/http2.rb

@@ -85,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.
@@ -312,9 +315,14 @@ module Raptor
       status, response_headers, response_body = @app.call(env)
 
       write_http2_response(socket, writer, stream_id, status, response_headers, response_body)
-    rescue
+    rescue => error
       write_http2_error_response(socket, writer, stream_id)
-      raise
+
+      if @on_error
+        @on_error.call(env, error) rescue nil
+      else
+        raise
+      end
     ensure
       response_body.close if response_body.respond_to?(:close)
     end

data/lib/raptor/request.rb

@@ -3,6 +3,7 @@
 
 require "socket"
 require "stringio"
+require "tempfile"
 
 require "rack"
 
@@ -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"
@@ -61,46 +63,58 @@ 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) -> [String, bool]
-    def self.decode_chunked(buffer)
+    # @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, false] unless crlf
+        return [decoded, :incomplete] unless crlf
 
         chunk_size = buffer.byteslice(offset, crlf - offset).to_i(16)
-        return [decoded, true] if chunk_size == 0
+        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, false]
+      [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
@@ -149,12 +163,21 @@ module Raptor
         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_complete = Request.decode_chunked(body)
-          if chunked_complete
+          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
@@ -180,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
 
@@ -197,12 +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, chunked_complete = Raptor::Request.decode_chunked(body_buffer)
+            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)
 
-              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
@@ -233,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
@@ -322,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
@@ -459,6 +503,18 @@ module Raptor
       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.
     #
     # Populates all required Rack env keys including rack.* keys, REMOTE_ADDR,
@@ -476,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] = []
 
@@ -520,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

data/lib/raptor/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Raptor
-  VERSION = "0.2.0"
+  VERSION = "0.3.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,19 @@ module Raptor
 
     DEFAULT_OPTIONS: 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]
+
     @command: Symbol
 
     @options: Hash[Symbol, untyped]
@@ -61,6 +74,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
 
+    @pidfile: 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] :pidfile 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

@@ -47,6 +47,8 @@ module Raptor
 
     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 +57,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.
     #

data/sig/generated/raptor/request.rbs

@@ -33,7 +33,9 @@ module Raptor
 
     STATUS_WITH_NO_ENTITY_BODY: untyped
 
-    ERROR_RESPONSE_500: ::String
+    INTERNAL_SERVER_ERROR_RESPONSE: ::String
+
+    CONTENT_TOO_LARGE_RESPONSE: ::String
 
     CONNECTION_CLOSE: ::String
 
@@ -65,15 +67,22 @@ 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) -> [String, bool]
-    def self.decode_chunked: (String buffer) -> [ String, bool ]
+    # @rbs (String buffer, ?Integer? max_size) -> [String, Symbol]
+    def self.decode_chunked: (String buffer, ?Integer? max_size) -> [ String, Symbol ]
+
+    @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
+
+    @body_spool_threshold: Integer?
+
+    @max_body_size: Integer?
 
     @server_port: Integer
 
@@ -83,10 +92,14 @@ 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
 
     # Eagerly reads and parses the first request on a freshly accepted
     # connection on the server thread, dispatching directly to the thread pool
@@ -203,6 +216,15 @@ 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
+
     # Builds a Rack environment hash from parsed HTTP request data.
     #
     # Populates all required Rack env keys including rack.* keys, REMOTE_ADDR,
@@ -219,6 +241,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

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.3.0
 platform: ruby
 authors:
 - Joshua Young