raptor 0.19.0 → 0.20.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6620d52a503c84e57e9aea223f0980e2215aeb58da7154e077c31c0d1858bf12
-  data.tar.gz: 36c546ae9bb960f6049a82e123af665375785872533b4657f0c336abd8ab7a9f
+  metadata.gz: e5a9aa19c5b29e7935a63f703d240ae6a132f4c7cc698481b02b9d66f1f65432
+  data.tar.gz: e443530d17e9c217982a425f5059c033ddd4eafa260f4ec60a1144bc99c0db4c
 SHA512:
-  metadata.gz: 729594070744ec522ec48852af6cce2c5aeef4df2050359473bdbf3f11aeaa167dbf7124e9a2fa21e622f77b6351d508fa3f4cf7438839e1b4e8a037784a7c89
-  data.tar.gz: 6812627b196892d9ffbc7608d34fc54c790d2d96ecdd4fa0823946389cc147a6e1640028cd057b958e91e9a2fc6307397e693bd5e6e7998b1c41b9fc9d13195b
+  metadata.gz: fcd061377838787f57e3555ba5997679ccf321ed2b8415a3eef7f9d15ccc2b221eb0335f16da285fe33054c430741b2b913663c26f6fad621ab3008e721257b1
+  data.tar.gz: 05b46a702067778709f0fb720ad908356650bbfc340cdde8809e49f536ed57dc7d2091bb96a07cda91af56a7a2daf634798e92af9a592d44002c1e84a18ad730

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [0.20.1] - 2026-09-26
+
+- Pass worker lifecycle settings through the Rackup handler
+
+## [0.20.0] - 2026-08-30
+
+- 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`
+- Make worker CPU affinity opt-in
+- Add request-local thread and Fiber cleanup options
+
 ## [0.19.0] - 2026-08-29
 
 - Skip HTTP/2 Ractor pools without SSL bindings

data/README.md

@@ -36,29 +36,29 @@ run proc { |_env| [200, { "content-type" => "text/plain" }, ["Hello, World!"]] }
 
 ```
 > bundle exec raptor -w 10 -t 3 hello_world.ru
-[Raptor 46475|Main|Main] Cluster initializing:
-[Raptor 46475|Main|Main] ├─ Version: 0.19.0
-[Raptor 46475|Main|Main] ├─ Ruby Version: ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +YJIT +PRISM [arm64-darwin23]
-[Raptor 46475|Main|Main] ├─ Environment: development
-[Raptor 46475|Main|Main] ├─ Master PID: 46475
-[Raptor 46475|Main|Main] │  └─ 10 worker processes
-[Raptor 46475|Main|Main] │     ├─ 1 server thread
-[Raptor 46475|Main|Main] │     ├─ 1 reactor thread
-[Raptor 46475|Main|Main] │     ├─ 1 HTTP/1.1 pipeline ractor
-[Raptor 46475|Main|Main] │     ├─ 1 pipeline collector thread
-[Raptor 46475|Main|Main] │     ├─ 3 worker threads (scaling, no limit)
-[Raptor 46475|Main|Main] │     └─ 1 stats thread
-[Raptor 46475|Main|Main] └─ Listening on 0.0.0.0:9292
-[Raptor 46480|Main|Main] Worker 0 booted
-[Raptor 46484|Main|Main] Worker 4 booted
-[Raptor 46482|Main|Main] Worker 2 booted
-[Raptor 46481|Main|Main] Worker 1 booted
-[Raptor 46483|Main|Main] Worker 3 booted
-[Raptor 46485|Main|Main] Worker 5 booted
-[Raptor 46486|Main|Main] Worker 6 booted
-[Raptor 46487|Main|Main] Worker 7 booted
-[Raptor 46488|Main|Main] Worker 8 booted
-[Raptor 46489|Main|Main] Worker 9 booted
+[Raptor 72876|Main|Main] Cluster initializing:
+[Raptor 72876|Main|Main] ├─ Version: 0.20.1
+[Raptor 72876|Main|Main] ├─ Ruby Version: ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +YJIT +PRISM [arm64-darwin23]
+[Raptor 72876|Main|Main] ├─ Environment: development
+[Raptor 72876|Main|Main] ├─ Master PID: 72876
+[Raptor 72876|Main|Main] │  └─ 10 worker processes
+[Raptor 72876|Main|Main] │     ├─ 1 server thread
+[Raptor 72876|Main|Main] │     ├─ 1 reactor thread
+[Raptor 72876|Main|Main] │     ├─ 1 HTTP/1.1 pipeline ractor
+[Raptor 72876|Main|Main] │     ├─ 1 pipeline collector thread
+[Raptor 72876|Main|Main] │     ├─ 3 worker threads (scaling, no limit)
+[Raptor 72876|Main|Main] │     └─ 1 stats thread
+[Raptor 72876|Main|Main] └─ Listening on 0.0.0.0:9292
+[Raptor 72884|Main|Main] Worker 0 booted
+[Raptor 72885|Main|Main] Worker 1 booted
+[Raptor 72886|Main|Main] Worker 2 booted
+[Raptor 72887|Main|Main] Worker 3 booted
+[Raptor 72891|Main|Main] Worker 7 booted
+[Raptor 72888|Main|Main] Worker 4 booted
+[Raptor 72890|Main|Main] Worker 6 booted
+[Raptor 72889|Main|Main] Worker 5 booted
+[Raptor 72892|Main|Main] Worker 8 booted
+[Raptor 72893|Main|Main] Worker 9 booted
 ```
 
 ```
@@ -73,6 +73,9 @@ Also works with `rackup` and `rails server`:
 > bundle exec rails server -u raptor
 ```
 
+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.
+
 ## Configuration
 
 Raptor accepts configuration via command-line flags, a Ruby config file, or both (CLI flags override config file
@@ -93,6 +96,9 @@ The config file is a Ruby file that evaluates to a hash of options. By default R
   workers: 4, # `Etc.nprocessors`
   threads: 3,
   max_threads: Float::INFINITY, # set to `threads` for a fixed pool
+  cpu_affinity: false,
+  clean_thread_locals: true,
+  clean_fiber_locals: false,
   chdir: nil,
   environment: nil, # falls back to `RAILS_ENV`, then `RACK_ENV`, then `"development"`
   connection: {
@@ -105,7 +111,7 @@ The config file is a Ruby file that evaluates to a hash of options. By default R
   http1: {
     ractors: nil,
     persistent_data_timeout: 65,
-    max_keepalive_requests: 100,
+    max_keepalive_requests: 1000,
   },
   http2: {
     ractors: nil,
@@ -121,6 +127,7 @@ The config file is a Ruby file that evaluates to a hash of options. By default R
   before_worker_shutdown: [],
   before_refork: [],
   stats_file: "tmp/raptor.json",
+  control_url: nil,
   pid_file: nil,
   stdout_file: nil,
   stderr_file: nil,
@@ -133,6 +140,19 @@ without a fixed limit when queued work is held up by blocking operations. It doe
 GVL is the bottleneck, and temporary threads leave after the queue drains. Set `max_threads` to cap growth, or set it
 to the same value as `threads` for a fixed pool.
 
+Set `cpu_affinity` to `true` to pin each worker to a distinct CPU when the worker count fits within the process's
+allowed CPU set. It is off by default because container runtimes commonly expose CPUs that are shared with other
+containers.
+
+Raptor clears application thread locals after each request by default. Set `clean_thread_locals` to `false` to disable
+it. Set `clean_fiber_locals` to `true` to run each request in a fresh Fiber, isolating Fiber-local state as well.
+
+`RAPTOR_WORKERS`, `RAPTOR_THREADS`, and `RAPTOR_MAX_THREADS` can set the corresponding options without a config file.
+Config files override defaults, environment variables override config files, and command-line options override both.
+`RAPTOR_MAX_THREADS=unlimited` leaves adaptive growth uncapped.
+
+`before_worker_boot` and `before_worker_shutdown` hooks receive the worker index.
+
 ## Bindings
 
 Raptor accepts multiple `binds:` URIs across three schemes.
@@ -204,9 +224,14 @@ Worker 1 (phase 0): pid=91351, requests=1199, busy=1/3, backlog=0, booted, last_
 ...
 ```
 
+Set `control_url` to a Unix socket URL such as `unix:///tmp/raptor-control.sock` to expose cluster stats over `/stats`.
+For adaptive pools, `max_threads` in each worker's status is its current thread count, so
+`pool_capacity / max_threads` measures the capacity available at that moment rather than comparing against an
+unbounded configured limit. The control server is read-only and currently exposes only `/stats`.
+
 ## (Micro) Benchmarks
 
-Raptor 0.19.0 vs Puma 8.0.2 vs Falcon 0.57.0 across two workload profiles. **IO-bound** is a GET endpoint that
+Raptor 0.20.1 vs Puma 8.0.2 vs Falcon 0.57.0 across two workload profiles. **IO-bound** is a GET endpoint that
 interleaves 5-10 short sleeps (total 2.5-15ms) with small CPU work, simulating a read path that makes several DB or
 cache calls. **CPU-bound** is a POST endpoint that accepts a small JSON body, interleaves 3-5 chunks of JSON item
 building (total 450-1500 items) with sub-100µs sleeps, and returns the built array, simulating a write path that does
@@ -214,27 +239,28 @@ most of its work in Ruby with a few near-zero-cost cache hits.
 
 Raptor is run in two modes: **Fixed** keeps 3 application threads per worker, matching Puma, while **Scaling** starts
 with 3 and may add threads without a fixed limit when queued work is blocked outside the GVL. Both modes are compared
-with both Puma and Falcon in the table below.
+with both Puma and Falcon in the table below. Raptor request-local cleanup and Puma's Fiber-per-request mode are
+disabled, and both threaded servers allow 999 requests per HTTP/1.1 keep-alive connection.
 
 Each cell reports the median throughput and median p95 latency independently across 3 runs, so the two numbers in a row
 may come from different runs. Every run starts a fresh server process so the samples are independent of each other;
 state accumulated in a previous run cannot bias the next. Across the whole table, the widest spread
-((max - min) / 2 / median) between runs of a single cell was ±26.6% for throughput and ±45.2% for p95.
+((max - min) / 2 / median) between runs of a single cell was ±12.4% for throughput and ±16.5% for p95.
 
 | Protocol              | Workload | Raptor mode | Raptor req/s | Raptor p95 | Puma req/s  | Puma p95  | vs Puma req/s | vs Puma p95  | Falcon req/s | Falcon p95 | vs Falcon req/s | vs Falcon p95 |
 | --------------------- | -------- | ----------- | ------------ | ---------- | ----------- | --------- | ------------- | ------------ | ------------ | ---------- | --------------- | ------------- |
-| HTTP/1.1              | IO       | Fixed       | 3.11k req/s  | 60.50 ms   | 1.51k req/s | 123.80 ms | 106.1% higher | 51.1% lower  | 12.20k req/s | 14.20 ms   | 74.5% lower     | 326.1% higher |
-| HTTP/1.1              | IO       | Scaling     | 8.63k req/s  | 21.60 ms   | 1.51k req/s | 123.80 ms | 471.4% higher | 82.6% lower  | 12.20k req/s | 14.20 ms   | 29.3% lower     | 52.1% higher  |
-| HTTP/1.1              | CPU      | Fixed       | 8.22k req/s  | 25.40 ms   | 8.65k req/s | 20.90 ms  | 5.0% lower    | 21.5% higher | 6.52k req/s  | 27.40 ms   | 26.0% higher    | 7.3% lower    |
-| HTTP/1.1              | CPU      | Scaling     | 8.22k req/s  | 25.10 ms   | 8.65k req/s | 20.90 ms  | 4.9% lower    | 20.1% higher | 6.52k req/s  | 27.40 ms   | 26.1% higher    | 8.4% lower    |
-| HTTP/1.1 (keep-alive) | IO       | Fixed       | 3.21k req/s  | 45.90 ms   | 1.46k req/s | 105.50 ms | 119.5% higher | 56.5% lower  | 6.23k req/s  | 28.20 ms   | 48.6% lower     | 62.8% higher  |
-| HTTP/1.1 (keep-alive) | IO       | Scaling     | 9.43k req/s  | 21.60 ms   | 1.46k req/s | 105.50 ms | 545.8% higher | 79.5% lower  | 6.23k req/s  | 28.20 ms   | 51.3% higher    | 23.4% lower   |
-| HTTP/1.1 (keep-alive) | CPU      | Fixed       | 8.49k req/s  | 21.80 ms   | 8.54k req/s | 22.20 ms  | 0.7% lower    | 1.8% lower   | 6.86k req/s  | 32.70 ms   | 23.8% higher    | 33.3% lower   |
-| HTTP/1.1 (keep-alive) | CPU      | Scaling     | 8.49k req/s  | 22.20 ms   | 8.54k req/s | 22.20 ms  | 0.6% lower    | 0.0% higher  | 6.86k req/s  | 32.70 ms   | 23.8% higher    | 32.1% lower   |
-| HTTP/2                | IO       | Fixed       | 1.14k req/s  | 150.03 ms  | N/A         | N/A       | -             | -            | 6.40k req/s  | 28.07 ms   | 82.1% lower     | 434.4% higher |
-| HTTP/2                | IO       | Scaling     | 4.46k req/s  | 39.65 ms   | N/A         | N/A       | -             | -            | 6.40k req/s  | 28.07 ms   | 30.3% lower     | 41.2% higher  |
-| HTTP/2                | CPU      | Fixed       | 5.35k req/s  | 35.99 ms   | N/A         | N/A       | -             | -            | 7.32k req/s  | 41.05 ms   | 26.9% lower     | 12.3% lower   |
-| HTTP/2                | CPU      | Scaling     | 6.28k req/s  | 32.32 ms   | N/A         | N/A       | -             | -            | 7.32k req/s  | 41.05 ms   | 14.2% lower     | 21.3% lower   |
+| HTTP/1.1              | IO       | Fixed       | 2.90k req/s  | 81.10 ms   | 1.41k req/s | 141.50 ms | 105.8% higher | 42.7% lower  | 12.26k req/s | 14.00 ms   | 76.4% lower     | 479.3% higher |
+| HTTP/1.1              | IO       | Scaling     | 6.24k req/s  | 36.20 ms   | 1.41k req/s | 141.50 ms | 343.2% higher | 74.4% lower  | 12.26k req/s | 14.00 ms   | 49.1% lower     | 158.6% higher |
+| HTTP/1.1              | CPU      | Fixed       | 7.21k req/s  | 37.90 ms   | 8.20k req/s | 23.20 ms  | 12.1% lower   | 63.4% higher | 5.28k req/s  | 35.00 ms   | 36.6% higher    | 8.3% higher   |
+| HTTP/1.1              | CPU      | Scaling     | 6.04k req/s  | 41.60 ms   | 8.20k req/s | 23.20 ms  | 26.4% lower   | 79.3% higher | 5.28k req/s  | 35.00 ms   | 14.4% higher    | 18.9% higher  |
+| HTTP/1.1 (keep-alive) | IO       | Fixed       | 2.35k req/s  | 73.50 ms   | 1.37k req/s | 124.50 ms | 71.2% higher  | 41.0% lower  | 6.35k req/s  | 27.50 ms   | 63.0% lower     | 167.3% higher |
+| HTTP/1.1 (keep-alive) | IO       | Scaling     | 7.83k req/s  | 23.20 ms   | 1.37k req/s | 124.50 ms | 470.1% higher | 81.4% lower  | 6.35k req/s  | 27.50 ms   | 23.2% higher    | 15.6% lower   |
+| HTTP/1.1 (keep-alive) | CPU      | Fixed       | 7.14k req/s  | 28.60 ms   | 7.85k req/s | 24.50 ms  | 9.1% lower    | 16.7% higher | 5.56k req/s  | 41.60 ms   | 28.4% higher    | 31.2% lower   |
+| HTTP/1.1 (keep-alive) | CPU      | Scaling     | 7.48k req/s  | 26.20 ms   | 7.85k req/s | 24.50 ms  | 4.8% lower    | 6.9% higher  | 5.56k req/s  | 41.60 ms   | 34.5% higher    | 37.0% lower   |
+| HTTP/2                | IO       | Fixed       | 1.13k req/s  | 174.70 ms  | N/A         | N/A       | -             | -            | 7.18k req/s  | 26.37 ms   | 84.3% lower     | 562.5% higher |
+| HTTP/2                | IO       | Scaling     | 6.48k req/s  | 29.15 ms   | N/A         | N/A       | -             | -            | 7.18k req/s  | 26.37 ms   | 9.7% lower      | 10.6% higher  |
+| HTTP/2                | CPU      | Fixed       | 6.31k req/s  | 31.74 ms   | N/A         | N/A       | -             | -            | 6.85k req/s  | 51.60 ms   | 7.9% lower      | 38.5% lower   |
+| HTTP/2                | CPU      | Scaling     | 6.70k req/s  | 31.91 ms   | N/A         | N/A       | -             | -            | 6.85k req/s  | 51.60 ms   | 2.2% lower      | 38.2% lower   |
 
 > ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +YJIT +PRISM [aarch64-linux]
 > 10 worker processes; fixed Raptor and Puma run 3 threads per worker; scaling Raptor starts at 3 with no fixed limit;

data/docs/brisrails-talk.md

@@ -1098,6 +1098,8 @@ The distinction matters. More threads help when requests are asleep in database
 
 Growth has no fixed limit by default. Set `max_threads` to cap it, or set it to `threads` to keep the pool fixed. OS threads still are not as cheap as fibers.
 
+Raptor clears application thread locals when each request finishes. Running every request in a fresh Fiber is also available when an application needs Fiber-local isolation. Parser and response buffers are kept separately so the server can still reuse them without carrying application state into the next request.
+
 <br>
 <br>
 <br>
@@ -1318,7 +1320,7 @@ flowchart TB
     Col -->|"complete"| ATP
     Col -->|"incomplete"| Rct
     ATP -->|"response bytes"| Client
-    ATP -.->|"keep-alive: wait_readable(1ms), parse next inline"| ATP
+    ATP -.->|"keep-alive: parse ready bytes inline"| ATP
 ```
 
 <br>
@@ -1386,20 +1388,20 @@ After writing a response, if keep-alive is on:
 
 ```ruby
 loop do
-  unless socket.wait_readable(0.001) # 1 millisecond
+  unless socket.wait_readable(0)
     reactor.persist(socket, id, ...)
     return
   end
 
-  # Bytes arrived. Parse the next request inline on this thread.
+  # Bytes are ready. Parse the next request inline on this thread.
   # ...
 end
 ```
 
-- <big>Wait 1ms for the next request on the same connection</big>
-- <big>If bytes arrive in that window: parse and dispatch inline, on the same thread</big>
-- <big>Return to the reactor when no bytes arrive inside the 1ms window, or when a request is incomplete</big>
-- <big>The trade: occupy an app thread for up to 1ms to widen the no-reactor fast path</big>
+- <big>Check for the next request on the same connection without waiting</big>
+- <big>If bytes are ready: parse and dispatch inline, on the same thread</big>
+- <big>Return to the reactor immediately when no bytes are ready, or when a request is incomplete</big>
+- <big>Back-to-back requests avoid a reactor round-trip without holding an app thread open</big>
 
 <br>
 <br>
@@ -1707,6 +1709,7 @@ flowchart TB
 - <big>Each worker writes a 49-byte slot every second: pid, phase, requests, backlog, busy and available threads, boot time, checkin time, booted flag</big>
 - <big>Master reads the whole region directly. No JSON. No pipe drain. No signal.</big>
 - <big>`bundle exec raptor stats` prints the region as JSON, essentially instantly</big>
+- <big>An optional read-only Unix socket exposes the cluster snapshot at `GET /stats` for monitoring</big>
 
 Wrapped in a small C extension I wrote: **`mmap-ruby`**.
 

data/docs/raptor-vs-puma.md

@@ -44,7 +44,7 @@ The rest of this doc explains why the shape looks like that.
 | Cluster dispatch       | Workers race on inherited listeners with a load-proportional accept delay | Two-choice load-aware BPF dispatch for TCP on Linux; shared-listener fallback |
 | Work queue             | Ruby `Queue` coordinated under the pool mutex             | Lock-free Michael-Scott FIFO queue                                            |
 | HTTP/2                 | Not implemented                                         | Native C parser + HPACK, lock-free per-connection frame writer               |
-| Keep-alive fast path   | Same-thread inline dispatch when spare threads exist    | Same-thread inline plus a `wait_readable(1ms)` micro-poll on the app thread  |
+| Keep-alive fast path   | Same-thread inline dispatch when spare threads exist    | Same-thread inline dispatch for bytes that are already waiting               |
 | Native extensions      | 1 (Ragel HTTP/1 parser + MiniSSL)                       | 3, all Ractor-safe (Ragel HTTP/1 parser; HTTP/2 parser + HPACK; `writev`, `sched_setaffinity`, `prctl` wrappers) |
 | Shared state (worker↔master) | Pipes and signals                                 | Anonymous shared-memory `mmap` region                                        |
 | Restart primitives     | Phased (USR1), hot (USR2 re-exec, inherits FDs via env), refork (SIGURG) | Phased (USR1), hot (USR2 re-exec, inherits FDs via env), refork (SIGURG) |
@@ -181,8 +181,12 @@ Raptor takes a different position on nearly every axis. It is opinionated in a w
 
 There is no single mode. Raptor is always a cluster. A master forks N workers, monitors them, and restarts crashed workers. The Rack app is always loaded in the master before forking, so copy-on-write is preserved by default (no user-visible `preload_app` knob).
 
+The process and app-thread counts can be set with `RAPTOR_WORKERS`, `RAPTOR_THREADS`, and `RAPTOR_MAX_THREADS`, which lets a deployment tune them without generating a config file. Config files override the built-in defaults, environment variables override config files, and command-line options override both. `RAPTOR_MAX_THREADS=unlimited` leaves adaptive growth uncapped.
+
 The master is a supervisor. It never handles requests. It forks workers, watches them via a shared-memory region (more on that in a moment), traps signals, restarts crashed workers, and orchestrates restarts.
 
+Worker boot and shutdown hooks receive the worker's slot index, so setup and cleanup can identify the same slot across restarts. Hooks that do not take an argument continue to work.
+
 Two kinds of restart are supported:
 
 1. **Phased restart on SIGUSR1.** Same idea as Puma. Kill each worker in sequence, wait for its replacement to boot, move on. Existing workers drain their connections while their replacements come up. This is cheap and safe when the change does not require a fresh master.
@@ -193,7 +197,7 @@ Systemd socket activation is a native feature and slots straight into this model
 
 Routine worker monitoring does not use pipes. Every worker writes its stats (pid, request count, backlog, busy and available threads, last checkin timestamp, booted flag) into a fixed-size slot in an anonymous shared-memory region allocated with `mmap-ruby` before the fork. The master reads the region directly. There is no serialisation, pipe drain, or signal to trigger the read; it is 49 bytes per worker of native memory. `bundle exec raptor stats` prints a JSON snapshot. Refork coordination is separate and does use a pair of pipes between the master and seed.
 
-On Linux, each worker pins itself to a distinct CPU via `sched_setaffinity` when the worker count fits within the process's allowed CPU set, so it stays on one core and its L1/L2 caches stay warm. When workers outnumber available CPUs the pin is skipped and the kernel scheduler manages placement.
+On Linux, `cpu_affinity: true` pins each worker to a distinct CPU via `sched_setaffinity` when the worker count fits within the process's allowed CPU set, so it stays on one core and its L1/L2 caches stay warm. It is off by default because an allowed CPU in a container is not necessarily dedicated to that container. When workers outnumber available CPUs the pin is skipped and the kernel scheduler manages placement.
 
 ### Refork
 
@@ -242,6 +246,8 @@ The pool starts at `threads` and scales without a fixed limit by default. Set `m
 
 The pool still uses an `AtomicConditionVariable` under the hood to park idle threads (idle threads call `Thread.stop` and get woken with `Thread#wakeup`; there is no spinning), because idle spinning would waste CPU. The difference from Puma's pool is not "no locks anywhere" but rather "the hot path (enqueue and dequeue when the queue has items) is lock-free". Once every worker is busy the mechanics look similar; where things diverge is under contention when you have many threads all trying to push and pop.
 
+Application thread locals are cleared when each request finishes. Running every request in a fresh Fiber is independently configurable, but opt-in. The pool keeps its own parser and response buffers in private thread variables so the server can reuse them without preserving application state between requests.
+
 The knock-on effect is that the server thread can read `pool.queue_size + pool.active_count` on every accept-loop iteration without acquiring the queue's mutation lock. Those are still synchronised atomic reads, but they do not serialise producers and consumers behind one mutex.
 
 ### I/O model
@@ -305,7 +311,7 @@ The eager keep-alive loop is one of Raptor's more deliberate latency/occupancy t
 
 ```ruby
 loop do
-  unless socket.wait_readable(KEEPALIVE_READ_TIMEOUT) # 0.001 s
+  unless socket.wait_readable(0)
     reactor.persist(socket, id, request_count, ...)
     return
   end
@@ -314,9 +320,9 @@ loop do
 end
 ```
 
-The thread waits up to 1 millisecond for the next request. If bytes arrive in that window, it parses them inline on the same thread and calls the Rack app again. If no bytes arrive, the connection returns to the reactor. Pipelined requests therefore avoid a reactor round-trip, while an idle keep-alive connection occupies an app thread for at most that short polling window.
+The thread checks for bytes without waiting. If they are already available, it parses them inline and calls the Rack app again. Otherwise the connection returns to the reactor immediately. Pipelined requests avoid a reactor round-trip without letting an idle keep-alive connection occupy an app thread.
 
-Puma has a similar shape but does not wait. It checks buffered back-to-back requests, then eagerly drains bytes already available on the socket. If a complete request is ready and the pool has a waiting thread, the current thread loops inline; otherwise Puma queues the client or returns it to the reactor. Raptor's 1ms poll deliberately widens the window in which the next request can stay on the current app thread.
+Puma has a similar shape. It checks buffered back-to-back requests, then eagerly drains bytes already available on the socket. If a complete request is ready and the pool has a waiting thread, the current thread loops inline; otherwise Puma queues the client or returns it to the reactor.
 
 The `reactor.persist` call re-registers the socket with the reactor using `persistent_data_timeout` (65s) as the new deadline. When the next bytes arrive, the reactor treats the socket like any other partially-read connection.
 
@@ -384,7 +390,7 @@ flowchart TB
 
         CHK{"Request<br/>complete?"}
         KA{"Keep-alive?"}
-        EAG{"wait_readable<br/>1ms"}
+        EAG{"wait_readable(0)<br/>bytes ready?"}
 
         SRV -->|"HTTP/1.1 eager_accept, parse inline, push proc"| ATP
         SRV -->|"HTTP/2 eager_accept, parse inline, push proc"| ATP
@@ -399,7 +405,7 @@ flowchart TB
         ATP -->|"app.call + write"| KA
         KA -->|"no, close"| CLS["close socket"]
         KA -->|"yes"| EAG
-        EAG -.->|"bytes within 1ms, parse+dispatch on same thread"| ATP
+        EAG -.->|"bytes ready, parse+dispatch on same thread"| ATP
         EAG -->|"no bytes, reactor.persist"| RCT
         RCT -->|"timeout expired"| TO["write 408, close"]
 
@@ -431,7 +437,7 @@ The critical structural difference from Puma is that Raptor has a separate proto
 
 **Puma.** Parsing happens on an app thread. The C parser callbacks build the env hash. A fresh client first enters the thread pool, where eager reads may complete it immediately; partial and idle keep-alive connections wait in the reactor before returning to the pool. Parsing shares the worker's GVL with the app.
 
-**Raptor.** Fresh and immediate keep-alive requests parse inline on the server or app thread. A connection that needs more bytes takes the longer path: reactor (I/O) → protocol Ractor pool (parse) → collector → app thread pool (Rack + write). Between keep-alive requests, the app thread does a 1ms micro-poll before returning an idle connection to the reactor. Parsing in the Ractor pipeline has its own GVL; parsing on an eager path does not.
+**Raptor.** Fresh and immediate keep-alive requests parse inline on the server or app thread. A connection that needs more bytes takes the longer path: reactor (I/O) → protocol Ractor pool (parse) → collector → app thread pool (Rack + write). Between keep-alive requests, the app thread checks for bytes without waiting before returning an idle connection to the reactor. Parsing in the Ractor pipeline has its own GVL; parsing on an eager path does not.
 
 In practice, Puma has one process-wide GVL per worker. Every Ruby thread inside that worker takes turns holding it. Raptor has the same main-Ractor GVL plus one GVL per protocol Ractor, so a pipeline Ractor can parse one connection while an app thread executes Rack for another. That parallelism is real, but so are the costs of making state shareable and crossing the Ractor and collector boundaries. Which side wins depends on how much work the request gives the protocol pipeline; the current CPU benchmark leaves Raptor and Puma close rather than proving a universal parsing advantage.
 
@@ -457,11 +463,11 @@ Under moderate load, queue mechanics are unlikely to dominate either server. Und
 
 **Puma.** After a response, if the connection is keep-alive and there are already buffered bytes for the next request (`has_back_to_back_requests?`) and there is a spare app thread, loop inline. Otherwise, if `eagerly_finish` (non-blocking reads while data is already buffered) returns true, either loop inline (if spare threads) or hand back to the thread pool (`@thread_pool << client`). Otherwise, back to the reactor with `@persistent_timeout`.
 
-**Raptor.** After a response, the app thread does `socket.wait_readable(0.001)`, waiting up to 1ms for bytes. If bytes arrive, it parses the next request inline. If the thread pool queue is at least as deep as the pool, the parsed request is handed back to the pool so other threads share the load; otherwise the same thread dispatches it inline. If no bytes arrive, `reactor.persist` and return.
+**Raptor.** After a response, the app thread checks `socket.wait_readable(0)`. If bytes are already available, it parses the next request inline. If other work is waiting, the parsed request goes to the back of the pool queue; otherwise the same thread dispatches it inline. If no bytes are ready, `reactor.persist` and return.
 
-The difference is subtle. Puma's `eagerly_finish` catches bytes already available on the socket; Raptor's `wait_readable(1ms)` catches those plus bytes arriving during the next millisecond. A request caught there parses on the response-writing thread and avoids a reactor round-trip. The cost is that an app thread can spend up to 1ms waiting on an otherwise idle connection.
+Both servers therefore keep a back-to-back request on an app thread when its bytes are already waiting, and return an idle connection to the reactor without deliberately holding an app thread open. The details of their parsing and pool handoff still differ, but neither widens the inline window by waiting for the client.
 
-This fast path is one plausible contributor to Raptor's keep-alive result. Requests arriving inside the polling window are parsed without a reactor round-trip: the response-writing thread either continues serving that connection inline (when the pool queue is shallower than the pool) or hands the parsed request back to the pool (when it is not). Puma's app threads also continue inline when data is already available and capacity permits. The material difference is Raptor's short wait for data that has not arrived yet.
+Raptor closes an HTTP/1.1 connection after 1,000 requests by default. The finite limit bounds connection-lifetime state without forcing frequent TCP teardown and reconnection under sustained keep-alive traffic.
 
 ### Backpressure
 
@@ -477,6 +483,8 @@ This fast path is one plausible contributor to Raptor's keep-alive result. Reque
 
 The performance difference here is negligible because the update happens once per worker per second, outside request processing. The design mainly gives the master a fixed-size snapshot it can inspect without draining per-worker messages.
 
+For external monitoring, `control_url` can expose a read-only `GET /stats` endpoint over a Unix socket. Its per-worker status includes backlog, busy threads, free capacity, request count, and the thread count currently available. Adaptive pools report their current size as `max_threads`, rather than their configured limit, so `pool_capacity / max_threads` remains a useful measure while the pool grows and shrinks.
+
 ### HTTP/2
 
 **Puma.** Not implemented. Puma's [position](https://github.com/puma/puma/issues/2697) is that HTTP/2 belongs at the edge (nginx, Caddy, ALB), which terminates it and speaks HTTP/1.1 to the app server. That's a reasonable call for the deployments Puma is aimed at, and it's where most Rails production actually sits.
@@ -489,7 +497,7 @@ At the throughput numbers the benchmark shows, a small set of concurrent connect
 
 ### Response writing
 
-Both servers support the same fundamental response shapes: file bodies through `IO.copy_stream`, non-blocking writes with `wait_writable(timeout)` on EAGAIN, and chunked transfer encoding for enumerable bodies without a known length. Puma uses `TCP_CORK` on Linux around HTTP/1.1 responses. Raptor corks responses that will close the connection, but skips the cork/uncork socket options on keep-alive responses where its write batching already supplies the important grouping.
+Both servers support the same fundamental response shapes: file bodies through `IO.copy_stream`, non-blocking writes with `wait_writable(timeout)` on EAGAIN, and chunked transfer encoding for enumerable bodies without a known length. Puma uses `TCP_CORK` on Linux around HTTP/1.1 responses. Raptor only corks a response that will close the connection when its body cannot already be emitted with the headers in one `writev` call.
 
 On the HTTP/1.1 path, Raptor has a small `writev(2)` wrapper (`Raptor::VectorIO`) that can scatter-write the status line, headers, and body in one call for non-chunked responses. Puma sends the same content over multiple `write` calls batched by `TCP_CORK` at the kernel; Raptor groups the buffers in userspace and lets `writev` handle partial writes when necessary.
 
@@ -501,7 +509,7 @@ Around the response boundary, HTTP/1.1 also amortises the common per-request all
 
 ### Keep-alive request by request
 
-To make the keep-alive distinction concrete, here is one possible timing for three requests on the same connection. The third request arrives after Puma's non-blocking eager read but inside Raptor's 1ms polling window. Drawn separately so the participant columns stay wide enough to read.
+To make the keep-alive paths concrete, here is one possible timing for three requests on the same connection. The second request is already buffered when the first response completes; the third arrives after the non-blocking check. Drawn separately so the participant columns stay wide enough to read.
 
 **Puma, three keep-alive requests:**
 
@@ -541,6 +549,7 @@ sequenceDiagram
     autonumber
     participant Client
     participant RS as Server thread
+    participant RR as Reactor thread
     participant RP as App thread
 
     Note over Client,RP: Request 1, initial
@@ -549,21 +558,21 @@ sequenceDiagram
     RS->>RP: push proc to thread pool
     RP->>Client: response 1
 
-    Note over Client,RP: Request 2, pipelined a few hundred us later
-    RP-->>RP: wait_readable 1ms
-    Client->>RP: request bytes
+    Note over Client,RP: Request 2, already buffered
+    Client->>RP: request bytes already waiting
+    RP->>RP: wait_readable(0) returns true
     RP->>RP: parse inline on app thread
     RP->>Client: response 2
 
-    Note over Client,RP: Request 3, arrives sub-millisecond later
-    RP-->>RP: wait_readable 1ms
-    Note right of RP: still within the 1ms window
-    Client->>RP: request bytes
-    RP->>RP: parse inline
+    Note over Client,RP: Request 3, not yet available
+    RP->>RP: wait_readable(0) returns false
+    RP->>RR: reactor.persist
+    Client->>RR: request bytes
+    RR->>RP: dispatch back to thread pool
     RP->>Client: response 3
 ```
 
-In this timing, Puma returns Request 3 to the reactor while Raptor catches it on the current thread. If the bytes were already available, both could stay inline; if they arrived after 1ms, both would use the reactor. The optimisation trades up to 1ms of app-thread occupancy for a wider inline window.
+In this timing, both servers keep Request 2 inline and return Request 3 to the reactor. Their implementations differ, but the occupancy rule is the same: use the current app thread for bytes that are ready, not to wait for future bytes.
 
 ## Part IV: What Raptor's design buys you
 

data/lib/rackup/handler/raptor.rb

@@ -71,8 +71,8 @@ module Rackup
         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) : {}
-        threads = (options[:Threads] || config[:threads] || cli_defaults[:threads]).to_i
-        max_threads = options[:MaxThreads] || config.fetch(:max_threads, cli_defaults[:max_threads])
+        threads = (options[:Threads] || ENV["RAPTOR_THREADS"] || config[:threads] || cli_defaults[:threads]).to_i
+        max_threads = options[:MaxThreads] || ENV["RAPTOR_MAX_THREADS"] || config.fetch(:max_threads, cli_defaults[:max_threads])
 
         result = {
           binds: if options[:Host] || options[:Port]
@@ -82,9 +82,12 @@ module Rackup
           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] || Concurrent.available_processor_count).to_i,
+          workers: (options[:Workers] || ENV["RAPTOR_WORKERS"] || config[:workers] || Concurrent.available_processor_count).to_i,
           threads: threads,
           max_threads: ::Raptor::CLI.parse_max_threads(max_threads, threads: threads),
+          cpu_affinity: config.key?(:cpu_affinity) ? config[:cpu_affinity] : cli_defaults[:cpu_affinity],
+          clean_thread_locals: config.key?(:clean_thread_locals) ? config[:clean_thread_locals] : cli_defaults[:clean_thread_locals],
+          clean_fiber_locals: config.key?(:clean_fiber_locals) ? config[:clean_fiber_locals] : cli_defaults[:clean_fiber_locals],
           app: app
         }
         result[:rackup] = config[:rackup] if config.key?(:rackup)
@@ -97,7 +100,13 @@ module Rackup
         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[:refork_after] = config.fetch(:refork_after, cli_defaults[:refork_after])
+        result[:before_fork] = config.fetch(:before_fork, cli_defaults[:before_fork])
+        result[:before_worker_boot] = config.fetch(:before_worker_boot, cli_defaults[:before_worker_boot])
+        result[:before_worker_shutdown] = config.fetch(:before_worker_shutdown, cli_defaults[:before_worker_shutdown])
+        result[:before_refork] = config.fetch(:before_refork, cli_defaults[:before_refork])
         result[:stats_file] = config.key?(:stats_file) ? config[:stats_file] : cli_defaults[:stats_file]
+        result[:control_url] = config[:control_url] if config.key?(:control_url)
         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)

data/lib/raptor/cli.rb

@@ -35,6 +35,9 @@ module Raptor
       workers: DEFAULT_WORKER_COUNT,
       threads: 3,
       max_threads: Float::INFINITY,
+      cpu_affinity: false,
+      clean_thread_locals: true,
+      clean_fiber_locals: false,
       rackup: "config.ru",
       chdir: nil,
       environment: nil,
@@ -48,7 +51,7 @@ module Raptor
       http1: {
         ractors: nil,
         persistent_data_timeout: 65,
-        max_keepalive_requests: 100,
+        max_keepalive_requests: 1000,
       },
       http2: {
         ractors: nil,
@@ -64,6 +67,7 @@ module Raptor
       before_worker_shutdown: [].freeze,
       before_refork: [].freeze,
       stats_file: "tmp/raptor.json",
+      control_url: nil,
       pid_file: nil,
       stdout_file: nil,
       stderr_file: nil,
@@ -151,6 +155,7 @@ module Raptor
       end
 
       apply_config_file(extract_config_path(argv) || self.class.default_config_path)
+      apply_environment
 
       @parser = create_parser
       @parser.parse!(argv)
@@ -232,6 +237,18 @@ module Raptor
       end
     end
 
+    # Applies worker and thread settings from the environment. Explicit CLI
+    # options are parsed afterwards and take precedence.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def apply_environment
+      @options[:workers] = Integer(ENV["RAPTOR_WORKERS"], 10) if ENV["RAPTOR_WORKERS"]
+      @options[:threads] = Integer(ENV["RAPTOR_THREADS"], 10) if ENV["RAPTOR_THREADS"]
+      @options[:max_threads] = ENV["RAPTOR_MAX_THREADS"] if ENV["RAPTOR_MAX_THREADS"]
+    end
+
     # Creates the OptionParser instance with all supported command-line options.
     #
     # @return [OptionParser] configured option parser
@@ -273,6 +290,18 @@ module Raptor
           @options[:max_threads] = num
         end
 
+        opts.on("--[no-]cpu-affinity", "Pin each worker process to a CPU (default: off)") do |bool|
+          @options[:cpu_affinity] = bool
+        end
+
+        opts.on("--[no-]clean-thread-locals", "Clear application thread locals after each request (default: on)") do |bool|
+          @options[:clean_thread_locals] = bool
+        end
+
+        opts.on("--[no-]clean-fiber-locals", "Process each request in a fresh Fiber (default: off)") do |bool|
+          @options[:clean_fiber_locals] = bool
+        end
+
         opts.on("-C", "--chdir PATH", String, "Change to PATH before loading the Rack application (default: none)") do |path|
           @options[:chdir] = path
         end
@@ -309,7 +338,7 @@ module Raptor
           @options[:http1][:persistent_data_timeout] = timeout
         end
 
-        opts.on("--http1-max-keepalive-requests NUM", Integer, "Maximum HTTP/1.1 requests per keep-alive connection (default: 100)") do |num|
+        opts.on("--http1-max-keepalive-requests NUM", Integer, "Maximum HTTP/1.1 requests per keep-alive connection (default: 1000)") do |num|
           @options[:http1][:max_keepalive_requests] = num
         end
 
@@ -345,6 +374,10 @@ module Raptor
           @options[:stats_file] = path
         end
 
+        opts.on("--control-url URI", String, "Serve cluster stats on a unix:// URI (default: off)") do |uri|
+          @options[:control_url] = uri
+        end
+
         opts.on("--pid-file PATH", String, "PID file path (default: none)") do |path|
           @options[:pid_file] = path
         end