raptor 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4a7acc08848f71017602d3abfb38b7d352a48d7bc7929e54f3a693dc3a0fe83
-  data.tar.gz: 1ee020abeb67db2a2eba6ff64f59054bf2e91447bd3996464f5a3279c3d3e748
+  metadata.gz: a9e7bfef1752060035a5e76f4d427097486aaa57c8bb184a47a3d8806d9749c8
+  data.tar.gz: e7c86ec6597a2315d0352c90c0ea89451e7301a00cfb4592d6c63760686ac7e6
 SHA512:
-  metadata.gz: b5b25843f29afe7e47a90c85f48ba5f9d06e7f5dc819d24595821940f8207fa46054208f38601a455271d026246bfd32144329782f1a842f44cd500bf3d10bbf
-  data.tar.gz: 5c1f9f18fbf946a8e4a648bed675f83ba7d71bdc9a85354b5df1ccc6ba39bd65b5740c31e1ffd11f4f88960b52aaee0ce2b46747fac52907bae6b6598f4e390e
+  metadata.gz: c5d04b6d4412b95b4131bcdcd6223a0b96ecc906a53a2522b1423195c4cd9b0746998d6d0588f6cf01a269eca4c67af091fd649512080ea98376de099d8eb291
+  data.tar.gz: 0e6b0fc536dccbe056c178bace6040550598aedf56ca05434714b299c09d7795092a85a41f6ffe7cb8e9a79ce6e88bd14ba231ce8a5afa6049ca4788ee6648fe

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 ## [Unreleased]
 
+## [0.8.0] - 2026-07-02
+
+- Add systemd `LISTEN_FDS` socket activation and `sd_notify` lifecycle messages
+- Add hot restart on `SIGUSR2`, inheriting listening sockets across the re-exec
+- Drop `SIGUSR1` stats logging and move phased restart from `SIGUSR2` to `SIGUSR1`
+- Add `chdir` and `environment` for Rack app loading, with fallback to `RAILS_ENV` and `RACK_ENV`
+- Add `access_log_file` for Common Log Format access logging, reopened on `SIGHUP`
+- Add `stdout_file` and `stderr_file` for redirecting stdout/stderr, reopened on `SIGHUP`
+- Add `drain_accept_queue` for dispatching every queued connection on shutdown
+- Add `worker_drain_timeout` for force-killing hung app threads during worker shutdown
+- Reject `Content-Length` values containing non-digit characters with 400
+- Populate `SERVER_SOFTWARE` and `HTTP_VERSION` in the Rack env
+- Honour `X-Forwarded-Proto`, `X-Forwarded-Scheme`, and `X-Forwarded-Ssl` from upstream proxies
+- Split newline-joined response header values into separate header lines
+- Reject excessive chunked framing overhead with 400 (slow-trickle attack guard)
+- Reject ambiguous request framing (`Transfer-Encoding` + `Content-Length`, or `chunked` not the final encoding) with 400
+- Send `100 Continue` when an HTTP/1.1 client sends `Expect: 100-continue`
+- Add new configuration options and split `client:` into protocol-scoped namespaces
+
 ## [0.7.0] - 2026-06-12
 
 - Eagerly consume back-to-back HTTP/2 frame batches in the pipeline collector

data/README.md

@@ -1,8 +1,14 @@
 # Raptor
 
-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.
+Raptor is a high-performance, preloading, pre-forking, multi-threaded Ruby 4+ web server implementing Rack 3.2+, using
+NIO for non-blocking I/O and Ractors for parallel HTTP/1.1 and HTTP/2 parsing via native C extensions, which also
+implement HPACK compression.
+
+> [!NOTE]
+> **Your application does not need to be Ractor-safe.** Ractors handle protocol-level work only; your Rack application
+> is invoked on a thread pool, so any thread-safe Rack app (including Rails) works as-is.
+
+Reference documentation is published at <https://joshuay03.github.io/raptor>.
 
 ## Installation
 
@@ -30,22 +36,23 @@ run proc { |_env| [200, { "content-type" => "text/plain" }, ["Hello, World!"]] }
 
 ```
 > bundle exec raptor -w 4 -t 3 hello_world.ru
-[Raptor 91348|main|main] Cluster initializing:
-[Raptor 91348|main|main] ├─ Version: 0.6.0
-[Raptor 91348|main|main] ├─ Ruby Version: ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +YJIT +PRISM [arm64-darwin23]
-[Raptor 91348|main|main] ├─ Master PID: 91348
-[Raptor 91348|main|main] │  └─ 4 worker processes
-[Raptor 91348|main|main] │     ├─ 1 server thread
-[Raptor 91348|main|main] │     ├─ 1 reactor thread
-[Raptor 91348|main|main] │     ├─ 1 pipeline ractor
-[Raptor 91348|main|main] │     ├─ 1 pipeline collector thread
-[Raptor 91348|main|main] │     ├─ 3 worker threads
-[Raptor 91348|main|main] │     └─ 1 stats thread
-[Raptor 91348|main|main] └─ Listening on 0.0.0.0:9292
-[Raptor 91350|main|main] Worker 0 booted
-[Raptor 91351|main|main] Worker 1 booted
-[Raptor 91352|main|main] Worker 2 booted
-[Raptor 91353|main|main] Worker 3 booted
+[Raptor 76577|Main|Main] Cluster initializing:
+[Raptor 76577|Main|Main] ├─ Version: 0.8.0
+[Raptor 76577|Main|Main] ├─ Ruby Version: ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +YJIT +PRISM [arm64-darwin23]
+[Raptor 76577|Main|Main] ├─ Environment: development
+[Raptor 76577|Main|Main] ├─ Master PID: 76577
+[Raptor 76577|Main|Main] │  └─ 4 worker processes
+[Raptor 76577|Main|Main] │     ├─ 1 server thread
+[Raptor 76577|Main|Main] │     ├─ 1 reactor thread
+[Raptor 76577|Main|Main] │     ├─ 1 pipeline ractor
+[Raptor 76577|Main|Main] │     ├─ 1 pipeline collector thread
+[Raptor 76577|Main|Main] │     ├─ 3 worker threads
+[Raptor 76577|Main|Main] │     └─ 1 stats thread
+[Raptor 76577|Main|Main] └─ Listening on 0.0.0.0:9292
+[Raptor 76579|Main|Main] Worker 0 booted
+[Raptor 76580|Main|Main] Worker 1 booted
+[Raptor 76581|Main|Main] Worker 2 booted
+[Raptor 76582|Main|Main] Worker 3 booted
 ```
 
 ```
@@ -60,15 +67,133 @@ Also works with `rackup` and `rails server`:
 > bundle exec rails server -u raptor
 ```
 
+## Configuration
+
+Raptor accepts configuration via command-line flags, a Ruby config file, or both (CLI flags override config file
+values). Run `bundle exec raptor --help` for the full flag list.
+
+The config file is a Ruby file that evaluates to a hash of options. By default Raptor loads `raptor.rb` then
+`config/raptor.rb` from the working directory; pass `-c PATH` to point at a specific file. Settings are nested under
+`connection:` (shared across protocols), `http1:` (HTTP/1.1-specific), and `http2:` (HTTP/2-specific).
+
+```ruby
+# raptor.rb
+
+{
+  binds: ["tcp://0.0.0.0:9292"],
+  socket_backlog: 1024,
+  drain_accept_queue: false,
+  workers: 4,
+  ractors: 1,
+  threads: 3,
+  chdir: nil,
+  environment: nil,
+  connection: {
+    first_data_timeout: 30,
+    chunk_data_timeout: 10,
+    write_timeout: 5,
+    max_body_size: nil,
+    body_spool_threshold: 1024 * 1024,
+  },
+  http1: {
+    persistent_data_timeout: 65,
+    max_keepalive_requests: 100,
+  },
+  http2: {
+    max_concurrent_streams: 100,
+  },
+  worker_boot_timeout: 60,
+  worker_timeout: 60,
+  worker_drain_timeout: 25,
+  worker_shutdown_timeout: 30,
+  stats_file: "tmp/raptor.json",
+  pid_file: nil,
+  stdout_file: nil,
+  stderr_file: nil,
+  access_log_file: nil,
+}
+```
+
+## Bindings
+
+Raptor accepts multiple `binds:` URIs across three schemes.
+
+- `tcp://host:port` for TCP. Host can be a specific IP, `0.0.0.0` / `[::]`, or `localhost` (expanded to both IPv4 and
+  IPv6 loopback addresses).
+- `unix:///path/to/socket` for a Unix domain socket. Stale sockets left by crashed processes are cleaned up
+  automatically.
+- `ssl://host:port?cert=/path/to.crt&key=/path/to.key` for TLS. HTTP/1.1 and HTTP/2 are negotiated via ALPN.
+
+Multiple binds can be combined freely.
+
+## Signals
+
+Send to the master process.
+
+| Signal | Effect                                                      |
+| ------ | ----------------------------------------------------------- |
+| `INT`  | Graceful shutdown                                           |
+| `TERM` | Graceful shutdown                                           |
+| `HUP`  | Reopen `stdout_file`, `stderr_file`, and `access_log_file`  |
+| `USR1` | Phased restart (rolling worker replacement)                 |
+| `USR2` | Hot restart (re-exec master, inheriting listening sockets)  |
+
+## Restarts
+
+- **Phased restart** (`USR1`) replaces workers one at a time, waiting for each new worker to boot before retiring the
+  previous one. The master process keeps running, so existing workers continue serving until they are individually
+  replaced. Use to pick up code changes that don't affect the master's boot path.
+- **Hot restart** (`USR2`) re-execs the master process with its original command line, inheriting the listening sockets
+  so accepted connections continue to be served across the swap. The successor master re-runs initialization from
+  scratch. Use to pick up changes that affect master-level state (config layout, dependency upgrades, Raptor itself).
+
+## systemd
+
+Raptor implements socket activation (`LISTEN_FDS`) and `sd_notify`, so it integrates cleanly with `Type=notify` units.
+When the socket unit is active, systemd hands the pre-bound listening file descriptors to Raptor, which serves them in
+place of `binds:`. `READY=1`, `STOPPING=1`, and `RELOADING=1` lifecycle messages are emitted automatically.
+
+```ini
+# /etc/systemd/system/myapp.socket
+[Socket]
+ListenStream=0.0.0.0:9292
+
+[Install]
+WantedBy=sockets.target
+```
+
+```ini
+# /etc/systemd/system/myapp.service
+[Service]
+Type=notify
+WorkingDirectory=/srv/myapp
+ExecStart=/usr/bin/bundle exec raptor
+ExecReload=/bin/kill -USR2 $MAINPID
+KillMode=mixed
+```
+
+## Stats
+
+Each worker writes per-worker stats (request count, busy threads, backlog, last check-in) to shared memory and to a
+JSON file (default `tmp/raptor.json`; set via `stats_file`).
+
+```
+> bundle exec raptor stats
+Master PID: 91348
+Worker 0 (phase 0): pid=91350, requests=1234, busy=2/3, backlog=0, booted, last_checkin=10:42:01
+Worker 1 (phase 0): pid=91351, requests=1199, busy=1/3, backlog=0, booted, last_checkin=10:42:01
+...
+```
+
 ## (Micro) Benchmarks
 
-Raptor 0.6.0 vs Puma 8.0.2:
+Raptor 0.8.0 vs Puma 8.0.2:
 
 | Protocol              | Raptor      | Puma        |
 | --------------------- | ----------- | ----------- |
-| HTTP/1.1              | 17.9k req/s | 16.8k req/s |
-| HTTP/1.1 (keep-alive) | 60k req/s   | 29.6k req/s |
-| HTTP/2                | 57.2k req/s | N/A         |
+| HTTP/1.1              | 18.1k req/s | 15.8k req/s |
+| HTTP/1.1 (keep-alive) | 58.2k req/s | 29.5k req/s |
+| HTTP/2                | 57k req/s   | N/A         |
 
 > ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +YJIT +PRISM [arm64-darwin23]
 > 4 workers, 3 threads, 12 concurrent connections

data/lib/rackup/handler/raptor.rb

@@ -78,18 +78,28 @@ module Rackup
           else
             config[:binds] || ["tcp://#{defaults[:Host]}:#{defaults[:Port]}"]
           end,
+          socket_backlog: (config[:socket_backlog] || cli_defaults[:socket_backlog]).to_i,
+          drain_accept_queue: config.key?(:drain_accept_queue) ? config[:drain_accept_queue] : cli_defaults[:drain_accept_queue],
           workers: (options[:Workers] || config[:workers] || Etc.nprocessors).to_i,
           ractors: (options[:Ractors] || config[:ractors] || cli_defaults[:ractors]).to_i,
           threads: (options[:Threads] || config[:threads] || cli_defaults[:threads]).to_i,
           app: app
         }
         result[:rackup] = config[:rackup] if config.key?(:rackup)
-        result[:client] = cli_defaults[:client].merge(config[:client] || {})
-        result[:worker_timeout] = (config[:worker_timeout] || cli_defaults[:worker_timeout]).to_i
+        result[:chdir] = config[:chdir] if config.key?(:chdir)
+        result[:environment] = config[:environment] if config.key?(:environment)
+        ::Raptor::CLI::NESTED_OPTION_KEYS.each do |key|
+          result[key] = cli_defaults[key].merge(config[key] || {})
+        end
         result[:worker_boot_timeout] = (config[:worker_boot_timeout] || cli_defaults[:worker_boot_timeout]).to_i
+        result[:worker_timeout] = (config[:worker_timeout] || cli_defaults[:worker_timeout]).to_i
+        result[:worker_drain_timeout] = (config[:worker_drain_timeout] || cli_defaults[:worker_drain_timeout]).to_i
         result[:worker_shutdown_timeout] = (config[:worker_shutdown_timeout] || cli_defaults[:worker_shutdown_timeout]).to_i
         result[:stats_file] = config.key?(:stats_file) ? config[:stats_file] : cli_defaults[:stats_file]
         result[:pid_file] = config[:pid_file] if config.key?(:pid_file)
+        result[:stdout_file] = config[:stdout_file] if config.key?(:stdout_file)
+        result[:stderr_file] = config[:stderr_file] if config.key?(:stderr_file)
+        result[:access_log_file] = config[:access_log_file] if config.key?(:access_log_file)
         result[:on_error] = config[:on_error] if config.key?(:on_error)
         result
       end

data/lib/raptor/binder.rb

@@ -56,7 +56,10 @@ module Raptor
     end
 
     # @rbs @bind_uris: Array[String]
+    # @rbs @socket_backlog: Integer
+    # @rbs @inherited_fds: Hash[String, Array[Integer]]
     # @rbs @listeners: Array[TCPServer | UNIXServer | SslListener]
+    # @rbs @uri_listeners: Hash[String, Array[TCPServer | UNIXServer | SslListener]]
 
     # Array of listening sockets.
     #
@@ -67,19 +70,26 @@ module Raptor
     #
     # Parses the provided bind URIs and creates listening sockets for each one.
     # Supports tcp://, unix://, and ssl:// schemes. Localhost is expanded to
-    # all available loopback addresses (both IPv4 and IPv6).
+    # all available loopback addresses (both IPv4 and IPv6). When `inherited_fds`
+    # supplies file descriptors for a URI, the listener is reconstructed from
+    # those FDs instead of binding fresh.
     #
     # @param bind_uris [Array<String>] array of URI strings to bind to
+    # @param socket_backlog [Integer] kernel listen() queue depth for TCP/SSL listeners
+    # @param inherited_fds [Hash{String => Array<Integer>}] inherited listener FDs keyed by bind URI
     # @return [void]
     # @raise [UnknownBindSchemeError] if a URI has an unsupported scheme
     #
     # @example
     #   binder = Binder.new(["tcp://0.0.0.0:3000", "unix:///tmp/raptor.sock"])
     #
-    # @rbs (Array[String] bind_uris) -> void
-    def initialize(bind_uris)
+    # @rbs (Array[String] bind_uris, ?socket_backlog: Integer, ?inherited_fds: Hash[String, Array[Integer]]) -> void
+    def initialize(bind_uris, socket_backlog: SOCKET_BACKLOG, inherited_fds: {})
       @bind_uris = bind_uris
+      @socket_backlog = socket_backlog
+      @inherited_fds = inherited_fds
       @listeners = nil
+      @uri_listeners = nil
       parse
     end
 
@@ -133,28 +143,91 @@ module Raptor
       @listeners.each(&:close)
     end
 
+    # Returns the file descriptors of every listener, grouped by the bind URI
+    # they were created from. The result is the payload to hand to a successor
+    # process via the `inherited_fds:` constructor argument.
+    #
+    # @return [Hash{String => Array<Integer>}]
+    #
+    # @rbs () -> Hash[String, Array[Integer]]
+    def inheritable_fds
+      @uri_listeners.transform_values { |listeners| listeners.map { |listener| listener.to_io.fileno } }
+    end
+
+    # Clears the close-on-exec flag on every listener so the file descriptors
+    # survive `Kernel.exec`.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def clear_close_on_exec
+      @listeners.each { |listener| listener.to_io.close_on_exec = false }
+    end
+
     private
 
-    # Parses bind URIs and creates listening sockets.
+    # Parses bind URIs and creates listening sockets, reusing inherited file
+    # descriptors for URIs supplied in `@inherited_fds`.
     #
     # @return [void]
     # @raise [UnknownBindSchemeError] if a URI scheme is not supported
     #
     # @rbs () -> void
     def parse
-      @listeners = @bind_uris.map do |bind_uri|
-        uri = URI.parse(bind_uri)
-        case uri.scheme
-        when "tcp"
-          create_tcp_listeners(uri.host, uri.port)
-        when "unix"
-          create_unix_listeners(uri.path)
-        when "ssl"
-          create_ssl_listeners(uri.host, uri.port, URI.decode_www_form(uri.query || "").to_h)
+      @uri_listeners = @bind_uris.to_h do |bind_uri|
+        if filenos = @inherited_fds[bind_uri]
+          [bind_uri, restore_listeners(bind_uri, filenos)]
         else
-          raise UnknownBindSchemeError.new(uri.scheme)
+          [bind_uri, create_listeners(bind_uri)]
         end
-      end.tap(&:flatten!)
+      end
+      @listeners = @uri_listeners.values.flatten
+    end
+
+    # Creates fresh listeners for the given bind URI.
+    #
+    # @param bind_uri [String] the URI to bind
+    # @return [Array<TCPServer, UNIXServer, SslListener>]
+    # @raise [UnknownBindSchemeError] if the URI scheme is not supported
+    #
+    # @rbs (String bind_uri) -> Array[TCPServer | UNIXServer | SslListener]
+    def create_listeners(bind_uri)
+      uri = URI.parse(bind_uri)
+      case uri.scheme
+      when "tcp"
+        create_tcp_listeners(uri.host, uri.port)
+      when "unix"
+        create_unix_listeners(uri.path)
+      when "ssl"
+        create_ssl_listeners(uri.host, uri.port, URI.decode_www_form(uri.query || "").to_h)
+      else
+        raise UnknownBindSchemeError.new(uri.scheme)
+      end
+    end
+
+    # Reconstructs listeners for the given bind URI from inherited file
+    # descriptors.
+    #
+    # @param bind_uri [String] the URI the FDs were bound to
+    # @param filenos [Array<Integer>] file descriptors to wrap
+    # @return [Array<TCPServer, UNIXServer, SslListener>]
+    # @raise [UnknownBindSchemeError] if the URI scheme is not supported
+    #
+    # @rbs (String bind_uri, Array[Integer] filenos) -> Array[TCPServer | UNIXServer | SslListener]
+    def restore_listeners(bind_uri, filenos)
+      uri = URI.parse(bind_uri)
+      case uri.scheme
+      when "tcp"
+        filenos.map { |fileno| TCPServer.for_fd(fileno) }
+      when "unix"
+        register_unix_socket_cleanup(uri.path)
+        filenos.map { |fileno| UNIXServer.for_fd(fileno) }
+      when "ssl"
+        ssl_context = build_ssl_context(URI.decode_www_form(uri.query || "").to_h)
+        filenos.map { |fileno| SslListener.new(tcp_server: TCPServer.for_fd(fileno), ssl_context: ssl_context) }
+      else
+        raise UnknownBindSchemeError.new(uri.scheme)
+      end
     end
 
     # Creates TCP server sockets for the given host and port.
@@ -174,7 +247,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.listen @socket_backlog
 
       [tcp_server]
     end
@@ -200,11 +273,22 @@ module Raptor
         end
       end
 
-      server = UNIXServer.new(path)
+      register_unix_socket_cleanup(path)
+
+      [UNIXServer.new(path)]
+    end
+
+    # Registers an `at_exit` hook that removes the Unix socket file on the
+    # owning master's clean exit. Each call records the current process so
+    # forked workers won't delete a socket their master still owns.
+    #
+    # @param path [String] filesystem path of the Unix socket
+    # @return [void]
+    #
+    # @rbs (String path) -> void
+    def register_unix_socket_cleanup(path)
       master_pid = Process.pid
       at_exit { File.delete(path) rescue nil if Process.pid == master_pid }
-
-      [server]
     end
 
     # Creates SSL server sockets for the given host, port, and SSL parameters.
@@ -220,18 +304,28 @@ module Raptor
     #
     # @rbs (String? host, Integer? port, Hash[String, String] ssl_params) -> Array[SslListener]
     def create_ssl_listeners(host, port, ssl_params)
-      require "openssl"
-
       tcp_servers = create_tcp_listeners(host, port)
+      ssl_context = build_ssl_context(ssl_params)
+      tcp_servers.map { |tcp_server| SslListener.new(tcp_server: tcp_server, ssl_context: ssl_context) }
+    end
 
-      ssl_context = OpenSSL::SSL::SSLContext.new
-      ssl_context.cert = OpenSSL::X509::Certificate.new(File.read(ssl_params["cert"]))
-      ssl_context.key = OpenSSL::PKey.read(File.read(ssl_params["key"]))
-      ssl_context.alpn_protocols = ["h2", "http/1.1"]
-      ssl_context.alpn_select_cb = ->(protocols) { protocols.include?("h2") ? "h2" : "http/1.1" }
-      ssl_context.freeze
+    # Builds a frozen `OpenSSL::SSL::SSLContext` configured for HTTP/2 and
+    # HTTP/1.1 ALPN negotiation.
+    #
+    # @param ssl_params [Hash<String, String>] SSL options ("cert" and "key" paths)
+    # @return [OpenSSL::SSL::SSLContext]
+    #
+    # @rbs (Hash[String, String] ssl_params) -> OpenSSL::SSL::SSLContext
+    def build_ssl_context(ssl_params)
+      require "openssl"
 
-      tcp_servers.map { |tcp_server| SslListener.new(tcp_server: tcp_server, ssl_context: ssl_context) }
+      OpenSSL::SSL::SSLContext.new.tap do |ssl_context|
+        ssl_context.cert = OpenSSL::X509::Certificate.new(File.read(ssl_params["cert"]))
+        ssl_context.key = OpenSSL::PKey.read(File.read(ssl_params["key"]))
+        ssl_context.alpn_protocols = ["h2", "http/1.1"]
+        ssl_context.alpn_select_cb = ->(protocols) { protocols.include?("h2") ? "h2" : "http/1.1" }
+        ssl_context.freeze
+      end
     end
 
     # Returns all available loopback IP addresses.