raptor 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d7a708bc4146a30fa1b03dbca5404dff1173c0b39348de9e3ae3a0330907063
-  data.tar.gz: 5db6986d6c9ca964873ec42f408d13087755b59c2517e7f942b8d2421ab88133
+  metadata.gz: 7c247b4c221d0f19ff1383ca0a4092a54bc12cd2f945655fa24e1ab49745eb70
+  data.tar.gz: cb932a7a048d87eb0913f8c0dbe52750ea4e525e4c4dc32e5fcc531af0daaf41
 SHA512:
-  metadata.gz: 8e163192ea38a0fa01852fe9c8ea31b82ef90b7fdd8f1b2b65b04e73f49e10792ba01225644d23104b42a7c1d3f07f47c273123a36ff4e77ef6259e695f967b8
-  data.tar.gz: 90b1789fff941091795ebac8092deb97d6cdc51f915e38399bc782c05d6a101866f651d42a6183c948b99c25ab70532357c70d1090a68609cda0f6f3be46de8b
+  metadata.gz: d8e1543054862e8a87c7261884348456da13d4432c3424687b74f506b884283d2773068b6beb10cbe9e209e969b98a918720861b3d0e05bc04d930ba38ec1921
+  data.tar.gz: f215cc4a92af86542d49f2c4772f0a65af09988779bbb1c44512ab075d4fb5c0758cb51d9765a0ee9d08fe340d31b42cea1610b021c443818fe40fbdcea63b93

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [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`
+- Replace the HTTP/2 per-connection write mutex with a lock-free writer
+- Parse the first HTTP/1.1 request inline on the server thread
+
 ## [0.1.0] - 2026-05-22
 
 - Initial release

data/README.md

@@ -1,7 +1,8 @@
 # Raptor
 
-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.
 
 ## Installation
 
@@ -30,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
@@ -41,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
 ```
 
 ```
@@ -52,15 +53,22 @@ Raptor Cluster initializing:
 Hello, World!%   
 ```
 
-## Benchmarks
+Also works with `rackup` and `rails server`:
 
-Raptor 0.1.0 vs Puma 8.0.1:
+```
+> bundle exec rackup -s raptor hello_world.ru
+> bundle exec rails server -u raptor
+```
+
+## (Micro) Benchmarks
+
+Raptor 0.3.0 vs Puma 8.0.1:
 
 | Protocol              | Raptor       | Puma         |
 | --------------------- | ------------ | ------------ |
-| HTTP/1.1              | 17.5k req/s  | 20.8k req/s  |
-| HTTP/1.1 (keep-alive) | 61.2k req/s  | 45.4k req/s  |
-| HTTP/2                | 23.4k req/s  | N/A          |
+| 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          |
 
 > Ruby 4.0.4 +YJIT, macOS Apple Silicon. 4 workers, 3 threads, 12 concurrent connections.
 

data/lib/rackup/handler/raptor.rb

@@ -0,0 +1,102 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "etc"
+
+module Rackup
+  module Handler
+    # Rack handler for booting Raptor through Rackup, `rails server`, or any
+    # other host that follows the Rack handler protocol.
+    #
+    module Raptor
+      DEFAULT_OPTIONS = {
+        Host: "0.0.0.0",
+        Port: 9292
+      }.freeze
+
+      # Boots a Raptor cluster serving the given Rack application.
+      #
+      # @param app [#call] the Rack application to serve
+      # @param options [Hash] handler options provided by Rackup or the host
+      # @yield [cluster] the cluster instance, before it starts running
+      # @return [void]
+      #
+      # @rbs (^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped] app, **untyped options) { (::Raptor::Cluster) -> void } -> void
+      def self.run(app, **options)
+        require_relative "../../raptor/cli"
+        require_relative "../../raptor/cluster"
+
+        cluster = ::Raptor::Cluster.new(build_cluster_options(app, options))
+
+        yield cluster if block_given?
+
+        cluster.run
+      end
+
+      # Returns the handler-specific options surfaced by `rackup --help`.
+      #
+      # @return [Hash{String => String}] option spec to description mapping
+      #
+      # @rbs () -> Hash[String, String]
+      def self.valid_options
+        {
+          "Host=HOST"   => "Hostname to listen on (default: #{DEFAULT_OPTIONS[:Host]})",
+          "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)",
+          "Config=PATH" => "Load additional configuration from PATH"
+        }
+      end
+
+      # Builds a Raptor cluster options hash from Rack handler options.
+      #
+      # Options not explicitly supplied by the user (per the `:user_supplied_options`
+      # key) are treated as host-provided defaults.
+      #
+      # @param app [#call] the Rack application to serve
+      # @param options [Hash] handler options provided by Rackup or the host
+      # @return [Hash{Symbol => untyped}] cluster configuration
+      #
+      # @rbs (^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped] app, Hash[Symbol, untyped] options) -> Hash[Symbol, untyped]
+      def self.build_cluster_options(app, options)
+        defaults = DEFAULT_OPTIONS.dup
+
+        if user_supplied_options = options.delete(:user_supplied_options)
+          (options.keys - user_supplied_options).each do |key|
+            defaults[key] = options.delete(key)
+          end
+        end
+
+        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: 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
+
+    register :raptor, Raptor
+  end
+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.
     #
@@ -77,8 +81,12 @@ module Raptor
     # @option options [Integer] :ractors number of ractors per worker process
     # @option options [Integer] :workers number of worker processes
     # @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
@@ -87,23 +95,28 @@ 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
-      @app = Rack::Builder.parse_file(options[:rackup])
+      @app = options[:app] || Rack::Builder.parse_file(options[:rackup])
       log_initialization
 
       @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)
@@ -120,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) }
 
@@ -132,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
 
@@ -181,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,
@@ -216,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,
@@ -233,7 +298,7 @@ module Raptor
       reactor = Reactor.new(thread_pool, ractor_pool, client_options: @client_options)
       reactor_thread = reactor.run
 
-      server = Server.new(@binder, reactor, thread_pool)
+      server = Server.new(@binder, reactor, thread_pool, request)
       server_thread = server.run
 
       puts "[#{Process.pid}] Worker #{index} booted"