raptor 0.25.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59fe5e87d01266b5c1c95e08e24339fc1bae9748c9ed814d4694903a2bbce8c5
-  data.tar.gz: 53cb18d26ad63f298a7a94496c536b561de3c7be29113df8ee77736d20c9019e
+  metadata.gz: 6f72ac9941a9da99f3fe49f3464ac925ff6304cf196836502a480220eb99d48f
+  data.tar.gz: 7a72e415e3663c54ac3c4f2fcfd13481356b3357693298c082f2b2eda3727182
 SHA512:
-  metadata.gz: e8a0997c88a5f7962cf9ae1d1a7e5ceb18830a321fc722cd88e87e848e998a68f0d2aa6bb091b5f6c0a7a074666a580150038d8ea52820f0518ff9f14e745ca7
-  data.tar.gz: 67178c0c92dca4d419f2127185c0df981f67e9e5e561b05d2f0c67fdb953db5db1d5866ae35d2b2a48b8a2bfe02439d7a41305da7fa691c04d3057edfbce73a0
+  metadata.gz: bf330c4d82552ee29b56b4bf0998355d3faad012147a5d34b9ade39d1f333ef4cc46b9d0e81c9b96516462fa920c3efe0c849fb716cdb158261cc3a6aff5014c
+  data.tar.gz: 9ff03e07f24109d0c1a0af66c309b6a49fa8f45c6db0aecd0a1c8507082d2e558a67bf72c01bf6c59f83c2aa379a41e8046f2b91f2d17deb8ecd59c5e44b162f

data/.buildkite/pipeline.yml

@@ -18,6 +18,17 @@ steps:
           - bundle install
           - bundle exec rake ci
 
+      - label: ":rails: Rails system tests"
+        image: "ruby:4.0"
+        env:
+          BROWSER_PATH: /usr/bin/chromium
+        commands:
+          - ruby -v
+          - apt-get update && apt-get install -y chromium
+          - bundle install
+          - bundle exec rails --version
+          - bundle exec rake test:rails
+
       - label: ":ruby: Ruby 4.0 +GC.stress"
         image: "ruby:4.0"
         env:
@@ -88,7 +99,7 @@ steps:
           queue: macos
         commands:
           - brew install --quiet ruby@4.0
-          - export PATH="$(brew --prefix ruby@4.0)/bin:$PATH"
+          - export PATH="$(brew --prefix ruby@4.0)/bin:$$PATH"
           - bundle config set --local path .bundle
           - ruby -v
           - bundle install
@@ -101,12 +112,27 @@ steps:
           RUBY_YJIT_ENABLE: "1"
         commands:
           - brew install --quiet ruby@4.0
-          - export PATH="$(brew --prefix ruby@4.0)/bin:$PATH"
+          - export PATH="$(brew --prefix ruby@4.0)/bin:$$PATH"
           - bundle config set --local path .bundle
           - ruby -v
           - bundle install
           - bundle exec rake ci
 
+      - label: ":rails: Rails system tests"
+        agents:
+          queue: macos
+        env:
+          BROWSER_PATH: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
+        commands:
+          - brew install --quiet ruby@4.0
+          - export PATH="$(brew --prefix ruby@4.0)/bin:$$PATH"
+          - test -x "$$BROWSER_PATH" || brew install --cask --quiet google-chrome
+          - bundle config set --local path .bundle
+          - ruby -v
+          - bundle install
+          - bundle exec rails --version
+          - bundle exec rake test:rails
+
       - label: ":ruby: Ruby 4.0 +GC.stress"
         agents:
           queue: macos
@@ -114,7 +140,7 @@ steps:
           RUBY_GC_STRESS: "1"
         commands:
           - brew install --quiet ruby@4.0
-          - export PATH="$(brew --prefix ruby@4.0)/bin:$PATH"
+          - export PATH="$(brew --prefix ruby@4.0)/bin:$$PATH"
           - bundle config set --local path .bundle
           - ruby -v
           - bundle install
@@ -128,7 +154,7 @@ steps:
           RUBY_GC_STRESS: "1"
         commands:
           - brew install --quiet ruby@4.0
-          - export PATH="$(brew --prefix ruby@4.0)/bin:$PATH"
+          - export PATH="$(brew --prefix ruby@4.0)/bin:$$PATH"
           - bundle config set --local path .bundle
           - ruby -v
           - bundle install
@@ -141,7 +167,7 @@ steps:
         commands:
           - brew unlink ruby
           - brew install --HEAD --quiet ruby
-          - export PATH="$(brew --prefix ruby)/bin:$PATH"
+          - export PATH="$(brew --prefix ruby)/bin:$$PATH"
           - bundle config set --local path .bundle
           - ruby -v
           - bundle install
@@ -156,7 +182,7 @@ steps:
         commands:
           - brew unlink ruby
           - brew install --HEAD --quiet ruby
-          - export PATH="$(brew --prefix ruby)/bin:$PATH"
+          - export PATH="$(brew --prefix ruby)/bin:$$PATH"
           - bundle config set --local path .bundle
           - ruby -v
           - bundle install
@@ -171,7 +197,7 @@ steps:
         commands:
           - brew unlink ruby
           - brew install --HEAD --quiet ruby
-          - export PATH="$(brew --prefix ruby)/bin:$PATH"
+          - export PATH="$(brew --prefix ruby)/bin:$$PATH"
           - bundle config set --local path .bundle
           - ruby -v
           - bundle install
@@ -187,7 +213,7 @@ steps:
         commands:
           - brew unlink ruby
           - brew install --HEAD --quiet ruby
-          - export PATH="$(brew --prefix ruby)/bin:$PATH"
+          - export PATH="$(brew --prefix ruby)/bin:$$PATH"
           - bundle config set --local path .bundle
           - ruby -v
           - bundle install

data/AGENTS.md

@@ -0,0 +1,25 @@
+# Repository conventions
+
+## Code organisation
+
+- Follow local style so the repository reads as one cohesive codebase.
+- Group and order related declarations logically throughout the repository, not just in Ruby code. Use consistent names,
+  placement, and spacing to make relationships clear.
+- Use blank lines to separate logical steps and final return values, without fragmenting closely related code.
+- Separate standard-library, third-party, and project requires with blank lines, keeping `require_relative` separate.
+  Respect load-order dependencies and order semantically rather than alphabetically.
+- Prefer `atomic-ruby`'s CAS-based queues and synchronisation in server internals. Use mutex-backed alternatives only
+  when their semantics justify them, and avoid busy-spinning across blocking operations.
+
+## Documentation and commits
+
+- Keep comments focused on what and why. Explain implementation details only when the intent is otherwise unclear.
+- Normally match commit subjects to changelog entries. Preserve separate entries for distinct changes worth calling out.
+- Use inline code formatting for code references in commit subjects and changelog entries where applicable.
+
+## Tests
+
+- Load `test_helper` first in test files and group test-support requires together, respecting boot dependencies.
+- Rely on assertions' default failure messages rather than adding custom messages.
+- Follow suite conventions for descriptions, setup, and assertions. Use Minitest's `parallelize_me!` when tests can
+  safely run independently.

data/CHANGELOG.md

@@ -1,24 +1,34 @@
 ## [Unreleased]
 
+## [0.27.0] - 2026-11-10
+
+- Support master-owned Rack listeners across worker forks
+- Add `after_worker_exit` hooks
+- Add `after_worker_drain` hooks
+
+## [0.26.0] - 2026-11-10
+
+- Add in-process Rack serving
+
 ## [0.25.0] - 2026-11-08
 
-- Replace nio4r with io-event for reactor I/O readiness without changing application threading
+- Use `io-event` for reactor I/O readiness
 
 ## [0.24.0] - 2026-11-08
 
-- Honour `connection.max_body_size` for HTTP/2 request bodies without closing other streams
-- Wait for all current workers to boot before notifying systemd that Raptor is ready
-- Prefer each over call for HTTP/1 Rack response bodies that implement both
-- Reject empty HTTP/1 Content-Length values and unsupported transfer codings before reading request bodies
-- Preserve request Version headers instead of replacing them with the HTTP protocol
-- Trim leading tabs as optional HTTP/1 header whitespace
-- Honour HTTP/1 Connection token lists, with close taking precedence over keep-alive
-- Run worker boot hooks before starting application threads, parsers, and request handling
-- Close HTTP/2 response bodies when writing fails or a stream is cancelled
-- Bound HTTP/1 chunk size lines and trailers, including incomplete metadata
-- Reject invalid CRLF delimiters after HTTP/1 chunk payloads
-- Prefer hyphenated request headers over underscore aliases and reject HTTP/1 framing aliases
-- Add plugins with lifecycle hooks, cluster stats, and managed background threads
+- Enforce request body limits on HTTP/2 streams
+- Notify systemd only after every current worker boots
+- Prefer enumerable Rack bodies over callable streaming
+- Reject empty request lengths and unsupported transfer codings
+- Preserve `Version` request headers in the Rack environment
+- Trim optional leading tabs from HTTP/1 header values
+- Honour HTTP/1 `Connection` token lists
+- Complete worker boot hooks before starting request handling
+- Close HTTP/2 response bodies when writing fails
+- Bound HTTP/1 chunk size lines and trailers
+- Validate HTTP/1 chunk payload delimiters
+- Preserve request header identity during Rack normalization
+- Add plugins
 
 ## [0.23.0] - 2026-10-18
 
@@ -32,13 +42,13 @@
 - Apply HTTP/2 initial window changes to responses waiting for flow control
 - Default `SERVER_NAME` for HTTP/2 requests without a host name
 - Join repeated HTTP/2 request headers instead of keeping only the last
-- Ignore HTTP/2 DATA frames for streams that already closed
+- Ignore HTTP/2 `DATA` frames for streams that already closed
 - Credit each HTTP/2 stream window for the data that stream receives
-- Strip padding from HTTP/2 DATA and HEADERS frames
+- Strip padding from HTTP/2 `DATA` and `HEADERS` frames
 - Encode and decode long HTTP/2 header strings without overflowing the stack
 - Limit HTTP/2 request header lists to 112 KiB
 - Reject HTTP/2 frames larger than the maximum frame size
-- Send GOAWAY when an HTTP/2 frame fails to decode
+- Send `GOAWAY` when an HTTP/2 frame fails to decode
 - Keep pipelined HTTP/1.1 requests out of the previous request's body
 - Process chunked requests on kept-alive HTTP/1.1 connections without waiting for more data
 - Validate request framing on kept-alive HTTP/1.1 connections
@@ -97,12 +107,12 @@
 - Close connected control socket clients during shutdown
 - Skip TCP corking when `writev(2)` emits a response in one call
 - Return idle HTTP/1.1 keep-alive connections to the reactor without waiting
-- Increase the HTTP/1.1 keep-alive request limit to 1,000 and requeue the connection when other work is waiting
-- Add a read-only `/stats` control socket
-- Pass the worker index to worker boot and shutdown hooks
-- Add `RAPTOR_WORKERS`, `RAPTOR_THREADS`, and `RAPTOR_MAX_THREADS`
+- Increase HTTP/1.1 keep-alive request limit
+- Expose cluster stats over a control socket
+- Pass worker indexes to lifecycle hooks
+- Add worker and thread environment variables
 - Make worker CPU affinity opt-in
-- Add request-local thread and Fiber cleanup options
+- Clean request-local state between requests
 
 ## [0.19.0] - 2026-08-29
 
@@ -173,7 +183,7 @@
 ## [0.10.0] - 2026-07-07
 
 - Memoize the server port string for the Rack env
-- Parse the Host header without regex
+- Parse the `Host` header without regex
 - Apply `TCP_NODELAY` on the listener rather than each accepted socket
 - Buffer chunked body writes up to 512KB before flushing
 - Add `QUERY_STRING` to the Rack env template
@@ -188,7 +198,7 @@
 - Batch response header and body writes into a single `writev(2)` syscall
 - Close the binder as the last step of graceful shutdown
 - Lower the backpressure floor for tighter load balancing on small pools
-- Add load-aware `SO_REUSEPORT` routing on Linux via an attached BPF program
+- Add load-aware `SO_REUSEPORT` routing via an attached BPF program
 - Reuse per-thread read buffers across HTTP/1.1 requests
 - Preserve the first `--bind` when it equals the default
 
@@ -235,7 +245,7 @@
 
 - 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
+- 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

data/README.md

@@ -37,7 +37,7 @@ run proc { |_env| [200, { "content-type" => "text/plain" }, ["Hello, World!"]] }
 ```
 > bundle exec raptor -w 10 -t 3 hello_world.ru
 [Raptor 39704|Main|Main] Cluster initializing:
-[Raptor 39704|Main|Main] ├─ Version: 0.23.0
+[Raptor 39704|Main|Main] ├─ Version: 0.27.0
 [Raptor 39704|Main|Main] ├─ Ruby Version: ruby 4.0.9 (2026-10-23 revision 3e93b23afc) +YJIT +PRISM [arm64-darwin25]
 [Raptor 39704|Main|Main] ├─ Environment: development
 [Raptor 39704|Main|Main] ├─ Master PID: 39704
@@ -76,6 +76,30 @@ Also works with `rackup` and `rails server`:
 Rails apps using `SOLID_QUEUE_IN_PUMA` run jobs through `config/puma.rb`, which Raptor does not load. Run `bin/jobs` as
 a separately supervised process or container instead.
 
+### Rails system tests
+
+Use Raptor as Capybara's server without forking, so Rails can share transactional test data with browser requests.
+Add this to your system test setup, alongside your browser driver configuration:
+
+```ruby
+require "rackup"
+require "rackup/handler/raptor"
+
+Capybara.register_server :raptor do |app, port, host|
+  Rackup::Handler::Raptor.run(app, Host: host, Port: port, Workers: 0) do |server|
+    at_exit { server.shutdown }
+  end
+end
+Capybara.server = :raptor
+```
+
+The exit hook shuts the server down before Ruby tears down its background threads.
+
+For other in-process uses, `require "raptor/embedded"` and call `Raptor::Embedded.new(app, host: "127.0.0.1", port: 0)`.
+`start` returns when serving is ready, `port` reports the bound port, `shutdown` drains requests and releases resources,
+and `join` waits for termination. Call `shutdown` before process exit. The embedded server leaves signal handlers and
+process-wide configuration to its caller. Cluster plugins and process lifecycle hooks do not run in this mode.
+
 ## Configuration
 
 Raptor reads options from a Ruby config file, environment variables, and command line flags, in increasing order of
@@ -124,8 +148,11 @@ working directory. Pass `-c PATH` to point at a specific file.
   worker_shutdown_timeout: 30,
   refork_after: 1000, # `nil` on non-Linux
   before_fork: [],
+  after_fork: [],
   before_worker_boot: [],
   before_worker_shutdown: [],
+  after_worker_drain: [],
+  after_worker_exit: [],
   before_refork: [],
   plugins: [],
   stats_file: "tmp/raptor.json",
@@ -167,21 +194,9 @@ Raptor::Plugin.create(:stats_logger) do
 end
 ```
 
-For an existing class, inherit from `Raptor::Plugin` and register it with
-`Raptor::Plugin.register(:stats_logger, MyStatsLogger)` instead.
-
-`start(cluster)` runs once before the initial workers fork. `cluster.options` exposes configuration, including
-plugin-specific keys. Append callbacks to its `before_fork`, `before_worker_boot`, `before_worker_shutdown`, and
-`before_refork` arrays during startup. If your plugin opens a listener, close the worker's inherited copy with
-`cluster.options[:before_worker_boot] << proc { @listener.close }` so only the master serves it.
-
-`cluster.stats` returns per-worker snapshots. `cluster.stats_hash` returns the same aggregate structure as `GET /stats`,
-including boot status, busy threads, capacity, backlog, and request counts. Both remain available while workers drain.
-
-Override `stop` to close listeners and flush exporters. Raptor calls it after workers exit, in reverse plugin order,
-then stops and joins threads created with `in_background`. These callbacks also run before hot restart and when startup
-fails, so `stop` must handle partially initialized resources. Worker replacement and phased restart keep the same
-master plugin instances running.
+`cluster.options` exposes configuration and lifecycle hooks. `cluster.stats` and `cluster.stats_hash` provide worker
+and aggregate statistics. Override `stop` to release plugin resources after workers exit, including during hot restart.
+See the [API documentation](https://joshuay03.github.io/raptor/Raptor/Plugin.html) for lifecycle details.
 
 ## Bindings
 
@@ -250,7 +265,7 @@ Set `control_url` to a Unix socket URL such as `unix:///tmp/raptor-control.sock`
 
 ## (Micro) Benchmarks
 
-Raptor 0.25.0 vs Puma 8.0.2 vs Falcon 0.57.0. Each case has 3 fresh-process samples, interleaved in seeded shuffled
+Raptor 0.27.0 vs Puma 8.0.2 vs Falcon 0.57.0. Each case has 3 fresh-process samples, interleaved in seeded shuffled
 rounds. Each sample warms up for 3s and measures for 15s. Metrics are independent medians. ± is (max − min) / 2 /
 median, not a confidence interval. Failure counts below each table sum all samples, so a failed run cannot disappear in
 a median. Throughput counts successful ordinary requests only.
@@ -278,92 +293,92 @@ accounting for shared pages instead of counting them fully in every worker.
 
 | Server | Mode           | Raptor baseline | req/s        | vs Raptor req/s | p95 ms | vs Raptor p95 | CPU ms/req | PSS MiB |
 | ------ | -------------- | --------------- | ------------ | --------------- | ------ | ------------- | ---------- | ------- |
-| Raptor | Fixed (3)      | -               | 3.41k ±0.9%  | -               | 44.85  | -             | 2.438      | 363.9   |
-| Raptor | Scaling (3–16) | -               | 8.12k ±0.8%  | -               | 22.30  | -             | 0.495      | 332.2   |
-| Puma   | Fixed (3)      | Fixed (3)       | 1.53k ±1.3%  | 55.0% lower     | 118.30 | 163.8% higher | 0.950      | 289.8   |
-| Puma   | Scaling (3–16) | Scaling (3–16)  | 8.22k ±0.3%  | 1.3% higher     | 22.02  | 1.3% lower    | 0.484      | 337.6   |
-| Falcon | Fibers         | Fixed (3)       | 10.87k ±0.4% | 218.7% higher   | 15.63  | 65.1% lower   | 0.468      | 437.3   |
-| Falcon | Fibers         | Scaling (3–16)  | 10.87k ±0.4% | 34.0% higher    | 15.63  | 29.9% lower   | 0.468      | 437.3   |
+| Raptor | Fixed (3)      | -               | 3.35k ±1.2%  | -               | 49.00  | -             | 2.421      | 337.8   |
+| Raptor | Scaling (3–16) | -               | 8.21k ±0.6%  | -               | 22.09  | -             | 0.468      | 323.6   |
+| Puma   | Fixed (3)      | Fixed (3)       | 1.53k ±0.7%  | 54.4% lower     | 120.94 | 146.8% higher | 0.969      | 272.0   |
+| Puma   | Scaling (3–16) | Scaling (3–16)  | 8.15k ±0.5%  | 0.7% lower      | 22.23  | 0.6% higher   | 0.467      | 319.5   |
+| Falcon | Fibers         | Fixed (3)       | 11.07k ±0.5% | 230.3% higher   | 15.44  | 68.5% lower   | 0.439      | 446.6   |
+| Falcon | Fibers         | Scaling (3–16)  | 11.07k ±0.5% | 34.8% higher    | 15.44  | 30.1% lower   | 0.439      | 446.6   |
 
 ### IO over HTTP/1.1 keep-alive
 
 | Server | Mode           | Raptor baseline | req/s       | vs Raptor req/s | p95 ms | vs Raptor p95 | CPU ms/req | PSS MiB |
 | ------ | -------------- | --------------- | ----------- | --------------- | ------ | ------------- | ---------- | ------- |
-| Raptor | Fixed (3)      | -               | 3.40k ±3.1% | -               | 38.77  | -             | 2.440      | 369.9   |
-| Raptor | Scaling (3–16) | -               | 7.44k ±0.4% | -               | 24.43  | -             | 0.494      | 356.2   |
-| Raptor | Fixed (16)     | -               | 7.55k ±2.0% | -               | 24.11  | -             | 0.475      | 358.0   |
-| Puma   | Fixed (3)      | Fixed (3)       | 1.50k ±0.8% | 56.0% lower     | 104.07 | 168.5% higher | 1.038      | 299.3   |
-| Puma   | Scaling (3–16) | Scaling (3–16)  | 7.44k ±0.3% | 0.1% higher     | 24.44  | 0.1% higher   | 0.441      | 341.3   |
-| Puma   | Fixed (16)     | Fixed (16)      | 7.59k ±1.2% | 0.5% higher     | 23.94  | 0.7% lower    | 0.442      | 345.2   |
-| Falcon | Fibers         | Fixed (3)       | 7.58k ±4.3% | 123.1% higher   | 23.89  | 38.4% lower   | 0.408      | 365.3   |
-| Falcon | Fibers         | Scaling (3–16)  | 7.58k ±4.3% | 1.9% higher     | 23.89  | 2.2% lower    | 0.408      | 365.3   |
-| Falcon | Fibers         | Fixed (16)      | 7.58k ±4.3% | 0.4% higher     | 23.89  | 0.9% lower    | 0.408      | 365.3   |
+| Raptor | Fixed (3)      | -               | 3.09k ±6.5% | -               | 51.42  | -             | 2.346      | 348.9   |
+| Raptor | Scaling (3–16) | -               | 7.39k ±0.6% | -               | 24.67  | -             | 0.465      | 344.2   |
+| Raptor | Fixed (16)     | -               | 7.48k ±0.5% | -               | 24.30  | -             | 0.453      | 344.1   |
+| Puma   | Fixed (3)      | Fixed (3)       | 1.49k ±0.4% | 51.7% lower     | 100.59 | 95.6% higher  | 1.009      | 282.5   |
+| Puma   | Scaling (3–16) | Scaling (3–16)  | 7.39k ±0.4% | 0.0% higher     | 24.58  | 0.4% lower    | 0.434      | 310.0   |
+| Puma   | Fixed (16)     | Fixed (16)      | 7.52k ±0.4% | 0.5% higher     | 24.16  | 0.6% lower    | 0.428      | 316.3   |
+| Falcon | Fibers         | Fixed (3)       | 7.34k ±2.1% | 137.4% higher   | 24.78  | 51.8% lower   | 0.382      | 329.6   |
+| Falcon | Fibers         | Scaling (3–16)  | 7.34k ±2.1% | 0.7% lower      | 24.78  | 0.4% higher   | 0.382      | 329.6   |
+| Falcon | Fibers         | Fixed (16)      | 7.34k ±2.1% | 1.9% lower      | 24.78  | 2.0% higher   | 0.382      | 329.6   |
 
 ### IO over HTTP/2
 
-| Server | Mode           | Raptor baseline | req/s        | vs Raptor req/s | p95 ms | vs Raptor p95 | CPU ms/req | PSS MiB |
-| ------ | -------------- | --------------- | ------------ | --------------- | ------ | ------------- | ---------- | ------- |
-| Raptor | Fixed (3)      | -               | 1.60k ±0.3%  | -               | 130.95 | -             | 0.937      | 474.6   |
-| Raptor | Scaling (3–16) | -               | 8.03k ±5.7%  | -               | 23.92  | -             | 0.573      | 905.4   |
-| Falcon | Fibers         | Fixed (3)       | 7.55k ±10.7% | 370.7% higher   | 25.90  | 80.2% lower   | 0.462      | 497.3   |
-| Falcon | Fibers         | Scaling (3–16)  | 7.55k ±10.7% | 5.9% lower      | 25.90  | 8.3% higher   | 0.462      | 497.3   |
+| Server | Mode           | Raptor baseline | req/s       | vs Raptor req/s | p95 ms | vs Raptor p95 | CPU ms/req | PSS MiB |
+| ------ | -------------- | --------------- | ----------- | --------------- | ------ | ------------- | ---------- | ------- |
+| Raptor | Fixed (3)      | -               | 1.61k ±0.3% | -               | 131.78 | -             | 0.901      | 410.2   |
+| Raptor | Scaling (3–16) | -               | 7.24k ±8.6% | -               | 30.21  | -             | 0.563      | 940.4   |
+| Falcon | Fibers         | Fixed (3)       | 7.82k ±1.7% | 386.4% higher   | 25.75  | 80.5% lower   | 0.426      | 526.6   |
+| Falcon | Fibers         | Scaling (3–16)  | 7.82k ±1.7% | 8.0% higher     | 25.75  | 14.7% lower   | 0.426      | 526.6   |
 
 ### CPU over HTTP/1.1
 
 | Server | Mode           | Raptor baseline | req/s       | vs Raptor req/s | p95 ms | vs Raptor p95 | CPU ms/req | PSS MiB |
 | ------ | -------------- | --------------- | ----------- | --------------- | ------ | ------------- | ---------- | ------- |
-| Raptor | Fixed (3)      | -               | 3.38k ±1.4% | -               | 68.70  | -             | 2.546      | 506.9   |
-| Raptor | Scaling (3–16) | -               | 3.37k ±2.4% | -               | 63.69  | -             | 2.482      | 532.6   |
-| Puma   | Fixed (3)      | Fixed (3)       | 3.17k ±1.2% | 6.2% lower      | 56.91  | 17.2% lower   | 2.521      | 451.2   |
-| Puma   | Scaling (3–16) | Scaling (3–16)  | 3.20k ±3.9% | 5.1% lower      | 50.38  | 20.9% lower   | 2.236      | 460.7   |
-| Falcon | Fibers         | Fixed (3)       | 3.40k ±1.0% | 0.7% higher     | 47.88  | 30.3% lower   | 2.533      | 428.3   |
-| Falcon | Fibers         | Scaling (3–16)  | 3.40k ±1.0% | 0.9% higher     | 47.88  | 24.8% lower   | 2.533      | 428.3   |
+| Raptor | Fixed (3)      | -               | 3.40k ±1.5% | -               | 66.74  | -             | 2.519      | 511.8   |
+| Raptor | Scaling (3–16) | -               | 3.45k ±3.9% | -               | 62.67  | -             | 2.389      | 504.6   |
+| Puma   | Fixed (3)      | Fixed (3)       | 3.24k ±0.9% | 4.7% lower      | 57.00  | 14.6% lower   | 2.457      | 444.5   |
+| Puma   | Scaling (3–16) | Scaling (3–16)  | 3.09k ±2.7% | 10.4% lower     | 49.54  | 21.0% lower   | 2.182      | 437.4   |
+| Falcon | Fibers         | Fixed (3)       | 3.53k ±0.8% | 3.8% higher     | 47.04  | 29.5% lower   | 2.430      | 432.3   |
+| Falcon | Fibers         | Scaling (3–16)  | 3.53k ±0.8% | 2.2% higher     | 47.04  | 24.9% lower   | 2.430      | 432.3   |
 
 ### CPU over HTTP/1.1 keep-alive
 
 | Server | Mode           | Raptor baseline | req/s       | vs Raptor req/s | p95 ms | vs Raptor p95 | CPU ms/req | PSS MiB |
 | ------ | -------------- | --------------- | ----------- | --------------- | ------ | ------------- | ---------- | ------- |
-| Raptor | Fixed (3)      | -               | 3.09k ±3.7% | -               | 59.42  | -             | 2.732      | 503.7   |
-| Raptor | Scaling (3–16) | -               | 2.93k ±2.0% | -               | 50.46  | -             | 2.645      | 518.6   |
-| Puma   | Fixed (3)      | Fixed (3)       | 3.41k ±6.7% | 10.7% higher    | 57.91  | 2.5% lower    | 2.423      | 406.4   |
-| Puma   | Scaling (3–16) | Scaling (3–16)  | 2.79k ±1.6% | 4.9% lower      | 66.33  | 31.5% higher  | 2.291      | 497.1   |
-| Falcon | Fibers         | Fixed (3)       | 3.01k ±6.2% | 2.5% lower      | 73.18  | 23.1% higher  | 2.920      | 563.1   |
-| Falcon | Fibers         | Scaling (3–16)  | 3.01k ±6.2% | 2.6% higher     | 73.18  | 45.0% higher  | 2.920      | 563.1   |
+| Raptor | Fixed (3)      | -               | 3.12k ±0.3% | -               | 50.35  | -             | 2.534      | 483.3   |
+| Raptor | Scaling (3–16) | -               | 2.99k ±2.1% | -               | 50.79  | -             | 2.532      | 502.5   |
+| Puma   | Fixed (3)      | Fixed (3)       | 3.49k ±6.5% | 11.7% higher    | 51.75  | 2.8% higher   | 2.319      | 383.4   |
+| Puma   | Scaling (3–16) | Scaling (3–16)  | 3.00k ±3.8% | 0.5% higher     | 64.39  | 26.8% higher  | 2.224      | 470.8   |
+| Falcon | Fibers         | Fixed (3)       | 3.17k ±0.2% | 1.7% higher     | 67.10  | 33.3% higher  | 2.763      | 529.6   |
+| Falcon | Fibers         | Scaling (3–16)  | 3.17k ±0.2% | 6.1% higher     | 67.10  | 32.1% higher  | 2.763      | 529.6   |
 
 ### CPU over HTTP/2
 
 | Server | Mode           | Raptor baseline | req/s        | vs Raptor req/s | p95 ms | vs Raptor p95 | CPU ms/req | PSS MiB |
 | ------ | -------------- | --------------- | ------------ | --------------- | ------ | ------------- | ---------- | ------- |
-| Raptor | Fixed (3)      | -               | 3.20k ±2.9%  | -               | 72.40  | -             | 2.401      | 621.4   |
-| Raptor | Scaling (3–16) | -               | 3.11k ±1.4%  | -               | 75.04  | -             | 2.403      | 597.8   |
-| Falcon | Fibers         | Fixed (3)       | 2.45k ±20.8% | 23.4% lower     | 147.43 | 103.6% higher | 2.616      | 567.1   |
-| Falcon | Fibers         | Scaling (3–16)  | 2.45k ±20.8% | 21.2% lower     | 147.43 | 96.5% higher  | 2.616      | 567.1   |
+| Raptor | Fixed (3)      | -               | 3.32k ±3.7%  | -               | 70.25  | -             | 2.374      | 583.2   |
+| Raptor | Scaling (3–16) | -               | 3.31k ±0.9%  | -               | 60.05  | -             | 2.347      | 562.3   |
+| Falcon | Fibers         | Fixed (3)       | 2.36k ±18.9% | 29.0% lower     | 127.17 | 81.0% higher  | 2.399      | 561.8   |
+| Falcon | Fibers         | Scaling (3–16)  | 2.36k ±18.9% | 28.8% lower     | 127.17 | 111.8% higher | 2.399      | 561.8   |
 
 ### 64 KiB body over HTTP/1.1 keep-alive
 
 | Server | Mode           | Raptor baseline | req/s         | vs Raptor req/s | p95 ms | vs Raptor p95 | CPU ms/req | PSS MiB |
 | ------ | -------------- | --------------- | ------------- | --------------- | ------ | ------------- | ---------- | ------- |
-| Raptor | Scaling (3–16) | -               | 96.95k ±0.5%  | -               | 3.59   | -             | 0.051      | 554.2   |
-| Puma   | Scaling (3–16) | Scaling (3–16)  | 90.31k ±0.5%  | 6.8% lower      | 3.56   | 0.9% lower    | 0.052      | 1447.0  |
-| Falcon | Fibers         | Scaling (3–16)  | 106.79k ±0.8% | 10.2% higher    | 3.70   | 3.0% higher   | 0.050      | 642.1   |
+| Raptor | Scaling (3–16) | -               | 94.57k ±1.5%  | -               | 3.70   | -             | 0.051      | 592.0   |
+| Puma   | Scaling (3–16) | Scaling (3–16)  | 88.51k ±0.7%  | 6.4% lower      | 3.67   | 0.6% lower    | 0.054      | 1201.7  |
+| Falcon | Fibers         | Scaling (3–16)  | 103.00k ±5.1% | 8.9% higher     | 3.84   | 3.9% higher   | 0.051      | 341.1   |
 
 ### IO + SSE (native) over HTTP/1.1 keep-alive
 
 | Server        | Mode           | Raptor baseline | req/s       | vs Raptor req/s | p95 ms | vs Raptor p95 | CPU ms/req | PSS MiB |
 | ------------- | -------------- | --------------- | ----------- | --------------- | ------ | ------------- | ---------- | ------- |
-| Raptor        | Fixed (3)      | -               | 3.43k ±8.5% | -               | 35.14  | -             | 2.448      | 378.5   |
-| Raptor        | Scaling (3–16) | -               | 7.58k ±1.5% | -               | 23.79  | -             | 0.485      | 373.3   |
-| Puma          | Fixed (3)      | Fixed (3)       | 0.34k ±6.3% | 90.0% lower     | 327.51 | 832.1% higher | 1.744      | 281.0   |
-| Puma          | Scaling (3–16) | Scaling (3–16)  | 7.38k ±1.4% | 2.6% lower      | 24.55  | 3.2% higher   | 0.443      | 339.9   |
-| Falcon        | Fibers         | Fixed (3)       | 7.51k ±4.0% | 118.8% higher   | 24.31  | 30.8% lower   | 0.413      | 371.0   |
-| Falcon        | Fibers         | Scaling (3–16)  | 7.51k ±4.0% | 1.0% lower      | 24.31  | 2.2% higher   | 0.413      | 371.0   |
-| Raptor (enum) | Fixed (3)      | -               | 0.89k ±3.3% | -               | 58.38  | -             | 8.363      | 356.0   |
+| Raptor        | Fixed (3)      | -               | 2.74k ±6.2% | -               | 59.25  | -             | 2.298      | 341.5   |
+| Raptor        | Scaling (3–16) | -               | 7.41k ±1.2% | -               | 24.53  | -             | 0.471      | 345.4   |
+| Puma          | Fixed (3)      | Fixed (3)       | 0.34k ±5.4% | 87.5% lower     | 361.94 | 510.8% higher | 1.715      | 263.9   |
+| Puma          | Scaling (3–16) | Scaling (3–16)  | 7.34k ±1.0% | 1.0% lower      | 24.70  | 0.7% higher   | 0.430      | 310.9   |
+| Falcon        | Fibers         | Fixed (3)       | 7.30k ±1.0% | 165.9% higher   | 24.88  | 58.0% lower   | 0.379      | 356.6   |
+| Falcon        | Fibers         | Scaling (3–16)  | 7.30k ±1.0% | 1.6% lower      | 24.88  | 1.5% higher   | 0.379      | 356.6   |
+| Raptor (enum) | Fixed (3)      | -               | 0.88k ±0.3% | -               | 66.74  | -             | 8.142      | 382.6   |
 
-Puma, Fixed (3) had 34 timeouts, 1 stalled stream across all samples.
+Puma, Fixed (3) had 37 timeouts, 1 stalled stream across all samples.
 
-Raptor (enum), Fixed (3) had 24 timeouts across all samples.
+Raptor (enum), Fixed (3) had 16 timeouts across all samples.
 
-> ruby 4.1.0dev (2026-11-07T16:07:23Z HEAD e67e4a6960) +YJIT +PRISM [aarch64-linux]
+> ruby 4.1.0dev (2026-11-10T00:02:04Z HEAD 7a07e456e4) +YJIT +PRISM [aarch64-linux]
 > 10 workers, 120 HTTP/1.1 client connections, 40 HTTP/2 connections × 3 streams.
 
 Run [bin/benchmark](bin/benchmark) to reproduce.

data/Rakefile

@@ -20,6 +20,13 @@ Rake::ExtensionTask.new("raptor_native", GEMSPEC) do |ext|
   ext.lib_dir = "lib/raptor"
 end
 
+namespace :test do
+  desc "Run Rails system tests"
+  task rails: :compile do
+    ruby "-Itest", "test/system/rails.rb"
+  end
+end
+
 namespace :bpf do
   task :compile do
     if RUBY_PLATFORM.include?("linux")
@@ -41,6 +48,6 @@ namespace :rbs do
   end
 end
 
-task default: %i[clobber compile bpf:compile rbs:generate test]
-task build: %i[clobber compile rbs:generate]
-task ci: %i[clobber compile test]
+task default: [:clobber, :compile, :"bpf:compile", :"rbs:generate", :test]
+task build: [:clobber, :compile, :"rbs:generate"]
+task ci: [:clobber, :compile, :test]

data/lib/rackup/handler/raptor.rb

@@ -12,24 +12,31 @@ module Rackup
         Port: 9292
       }.freeze
 
-      # Boots a Raptor cluster serving the given Rack application.
+      # Serves the given Rack application using the handler options.
       #
       # @param app [#call] the Rack application to serve
       # @param options [Hash] handler options provided by Rackup or the host
-      # @yield before the cluster starts running
-      # @yieldparam cluster [::Raptor::Cluster] the cluster instance
+      # @yield before the server starts running
+      # @yieldparam server [::Raptor::Cluster, ::Raptor::Embedded] the server instance
       # @return [void]
       #
-      # @rbs (^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped] app, **untyped options) { (::Raptor::Cluster) -> void } -> void
+      # @rbs (^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped] app, **untyped options) { (::Raptor::Cluster | ::Raptor::Embedded) -> void } -> void
       def self.run(app, **options)
         require_relative "../../raptor/cli"
         require_relative "../../raptor/cluster"
+        require_relative "../../raptor/embedded"
 
-        cluster = ::Raptor::Cluster.new(build_cluster_options(app, options))
+        configuration = build_options(app, options)
+        server = if configuration[:workers].zero?
+          configuration.delete(:app)
+          ::Raptor::Embedded.new(app, **configuration)
+        else
+          ::Raptor::Cluster.new(configuration)
+        end
 
-        yield cluster if block_given?
+        yield server if block_given?
 
-        cluster.run
+        server.run
       end
 
       # Returns the handler-specific options surfaced by `rackup --help`.
@@ -41,24 +48,24 @@ module Rackup
         {
           "Host=HOST"      => "Hostname to listen on (default: #{DEFAULT_OPTIONS[:Host]})",
           "Port=PORT"      => "Port to listen on (default: #{DEFAULT_OPTIONS[:Port]})",
-          "Workers=NUM"    => "Number of worker processes (default: available processor count)",
+          "Workers=NUM"    => "Number of worker processes, or 0 for in-process serving (default: available processor count)",
           "Threads=NUM"    => "Number of threads per worker (default: 3)",
           "MaxThreads=NUM" => "Maximum threads per worker (`unlimited` for no limit; default: unlimited)",
           "Config=PATH"    => "Load additional configuration from PATH"
         }
       end
 
-      # Builds a Raptor cluster options hash from Rack handler options.
+      # Builds Raptor server configuration 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
+      # @return [Hash{Symbol => untyped}] server 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)
+      def self.build_options(app, options)
         defaults = DEFAULT_OPTIONS.dup
 
         if (user_supplied_options = options.delete(:user_supplied_options))
@@ -116,7 +123,7 @@ module Rackup
         result[:on_error] = config[:on_error] if config.key?(:on_error)
         config.merge(result)
       end
-      private_class_method :build_cluster_options
+      private_class_method :build_options
     end
 
     register :raptor, Raptor