raptor 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8391f9399db2e88dab106ad995a34060e6ae07f34c84825bfdcb066cd129dad4
-  data.tar.gz: 25cb3658e2aded284f302b84a1ee91d67344a5b5dd36c6c0e854381cfb4df048
+  metadata.gz: a9d82dc0869e270278088d312d03a6ed914e494da5fb6b7bf6e41c03257ddf41
+  data.tar.gz: c113ab336b5ad9e5e72095e79af4702b5adb0efb46117ba43b6879fe2e4a728c
 SHA512:
-  metadata.gz: e398237ccb391aff663c4d75e5470c0e4e0e6f6b273e26bface4cd6793691c3297053ab0a5d744deac8fd087c4f7dec0beb8426d8a762d3a089902d11dbe53e5
-  data.tar.gz: c4cfd5f7ffdcf7f970cc8c85868629bac6c6061312120c0dc2a3c64fa6431cf475bc8fbb877dce0bad3febc2bd87ccc5342e2bc9c8dad196c69306431ae91345
+  metadata.gz: 365e09dbfcc7cbb265b8ac6569a66e66a0629ecfb4fd176164cb4c55b6f0223ef05f3e17f3318f7ec6cd58be94396996885b232c496e46620f42049ca9a1fe84
+  data.tar.gz: d6d2b9b18cd0da790c2f13fce8994f799bac41e94270f9c69f4b57241f6931d98a8ef81573e8257d1766dfde0a63807d2f06cf57fa4a44ef8f754533b733aeff

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 ## [Unreleased]
 
+## [0.4.0] - 2026-05-29
+
+- Load `raptor.rb` or `config/raptor.rb` by default when no config path is supplied
+- Honour the peer's HTTP/2 flow-control windows when sending `DATA` frames
+- Assemble HEADERS across `CONTINUATION` frames
+- Validate HTTP/2 stream IDs and emit `GOAWAY` on protocol errors
+- Offload TLS handshakes to the thread pool to keep the server thread responsive
+- Exit eager keep-alive loops on cluster shutdown
+- Apply the write timeout to HTTP/2 frame writes
+- Reject HPACK dynamic table size updates larger than 4096 bytes
+- Reject malformed HTTP/1.1 requests with a 400 response
+- Rescue unexpected errors in the reactor and pipeline collector
+
+## [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.2+,
+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
-├─ Ruby Version: ruby 4.0.4 (2026-05-12 revision b89eb1bcbf) +YJIT +PRISM [arm64-darwin23]
-├─ Master PID: 71052
+├─ Version: 0.4.0
+├─ Ruby Version: ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +YJIT +PRISM [arm64-darwin23]
+├─ Master PID: 26456
 │  └─ 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
+[26459] Worker 0 booted
+[26460] Worker 1 booted
+[26461] Worker 2 booted
+[26462] Worker 3 booted
 ```
 
 ```
@@ -60,17 +60,17 @@ 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.4.0 vs Puma 8.0.1:
 
 | Protocol              | Raptor       | Puma         |
 | --------------------- | ------------ | ------------ |
-| HTTP/1.1              | 20.3k req/s  | 20.8k req/s  |
-| HTTP/1.1 (keep-alive) | 60.9k req/s  | 45.4k req/s  |
-| HTTP/2                | 22.9k req/s  | N/A          |
+| HTTP/1.1              | ~20k req/s   | ~21k req/s   |
+| HTTP/1.1 (keep-alive) | ~60k req/s   | ~45k req/s   |
+| HTTP/2                | ~23k req/s   | N/A          |
 
-> Ruby 4.0.4 +YJIT, macOS Apple Silicon. 4 workers, 3 threads, 12 concurrent connections.
+> Ruby 4.0.5 +YJIT, macOS Apple Silicon. 4 workers, 3 threads, 12 concurrent connections.
 
 ## Development
 

data/ext/raptor_http2/raptor_http2.c

@@ -457,6 +457,7 @@ static int hpack_decode_header_block(const uint8_t *buf, size_t len,
       /* dynamic table size update (RFC 7541 6.3) */
       uint64_t new_size;
       if (hpack_decode_int(buf, len, &pos, 5, &new_size) < 0) return -1;
+      if (new_size > HTTP2_DEFAULT_HEADER_TABLE_SIZE) return -1;
       *max_table_size = (long)new_size;
       *dyn_table = dynamic_table_evict(*dyn_table, *max_table_size);
 

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,32 @@ module Rackup
           end
         end
 
-        host = options[:Host] || defaults[:Host]
-        port = options[:Port] || defaults[:Port]
-
         cli_defaults = ::Raptor::CLI::DEFAULT_OPTIONS
+        config_path = options[:Config] || ::Raptor::CLI.default_config_path
+        config = config_path ? ::Raptor::CLI.load_config_file(config_path) : {}
 
-        {
+        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, :pid_file].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,51 @@ 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",
+      pid_file: nil,
     }.freeze
 
+    DEFAULT_CONFIG_PATHS = ["raptor.rb", "config/raptor.rb"].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
+
+    # Returns the first existing path in {DEFAULT_CONFIG_PATHS} resolved
+    # against `root`, or nil if none exist.
+    #
+    # Used to pick up a project-local config file when no `-c`/`--config`
+    # flag was supplied.
+    #
+    # @param root [String] directory to resolve the default paths against
+    # @return [String, nil] the config path, or nil if no default file exists
+    #
+    # @rbs (?String root) -> String?
+    def self.default_config_path(root = Dir.pwd)
+      DEFAULT_CONFIG_PATHS.find { |path| File.exist?(File.join(root, path)) }
+    end
+
     # @rbs @command: Symbol
     # @rbs @options: Hash[Symbol, untyped]
     # @rbs @parser: OptionParser
@@ -70,6 +107,9 @@ module Raptor
       end
       @options = DEFAULT_OPTIONS.dup
       @options[:client] = @options[:client].dup
+
+      apply_config_file(extract_config_path(argv) || self.class.default_config_path)
+
       @parser = create_parser
       @parser.parse!(argv)
 
@@ -111,6 +151,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 +203,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 +239,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("--pid-file PATH", String, "PID file path (default: none)") do |path|
+          @options[:pid_file] = 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 @pid_file: 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] :pid_file 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]
+      @pid_file = options[:pid_file]
 
       @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(@pid_file, File::CREAT | File::EXCL | File::WRONLY) { |file| file.write(Process.pid.to_s) } if @pid_file
 
       @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(@pid_file) rescue nil if @pid_file
       @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,24 +281,29 @@ 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,
         worker: request.http_parser_worker
       ) do |parsed_result|
-        if parsed_result[:protocol] == :http2
-          http2.handle_parsed_request(parsed_result, reactor, thread_pool)
-        else
-          request.handle_parsed_request(parsed_result, reactor, thread_pool)
+        begin
+          if parsed_result[:protocol] == :http2
+            http2.handle_parsed_request(parsed_result, reactor, thread_pool)
+          else
+            request.handle_parsed_request(parsed_result, reactor, thread_pool)
+          end
+        rescue => error
+          warn "#{Thread.current.name} rescued:"
+          warn error.full_message
         end
       end
 
       reactor = Reactor.new(thread_pool, ractor_pool, client_options: @client_options)
       reactor_thread = reactor.run
 
-      server = Server.new(@binder, reactor, thread_pool, request)
+      server = Server.new(@binder, reactor, thread_pool, request, client_options: @client_options)
       server_thread = server.run
 
       puts "[#{Process.pid}] Worker #{index} booted"
@@ -269,6 +338,7 @@ module Raptor
       reactor.shutdown
       reactor_thread.join
       ractor_pool.shutdown
+      request.shutdown
       thread_pool.shutdown
       stats_thread.join
     end