raptor 0.10.0 → 0.12.0

data/docs/raptor-vs-puma.md

@@ -1,6 +1,6 @@
 # Raptor vs Puma: A Design Comparison
 
-Raptor is a Ruby web server designed around Ruby 4's Ractors. On CPU-bound HTTP/1.1 workloads it holds a real edge over the latest Puma release on the same hardware; on IO-bound work where the request sleep dominates, both servers land close to parity. It also speaks HTTP/2 natively, which Puma does not. This document is a systems-design walkthrough of how it manages both.
+Raptor is a Ruby web server designed around Ruby 4's Ractors. On CPU-bound HTTP/1.1 with keep-alive it holds a real edge over the latest Puma release on the same hardware; on IO-heavy work fibers still win, and Falcon is the server to compare to there rather than Raptor or Puma. Raptor also speaks HTTP/2 natively, which Puma does not. This document is a systems-design walkthrough of how it manages both.
 
 ## Why this document exists
 
@@ -10,14 +10,26 @@ They did, but the more interesting result was structural. Once you commit to a R
 
 This document walks through both servers at systems-design depth. By the end you should be able to describe how Puma and Raptor each move a request from `accept()` to `app.call(env)` and back, why the two architectures make the design decisions they do, and where the performance delta actually comes from. No source code required.
 
+## A note on Falcon
+
+Falcon is the other next-generation Ruby web server worth naming. It takes a different bet than either Puma or Raptor: fiber-based concurrency via the `async` gem instead of threads, native HTTP/2, per-request lightweight tasks instead of a fixed thread pool. Its strengths show up on workloads with lots of concurrent long-lived connections (WebSockets, SSE, streaming), applications built end-to-end on the `async` ecosystem, and HTTP/2-heavy traffic. On a traditional Rails workload where most of the request budget is a synchronous DB round-trip through ActiveRecord, its advantages over Puma are less pronounced because the fiber scheduler only helps when the underlying I/O is fiber-aware. If your app fits that sweet spot, Falcon belongs in your evaluation.
+
+This document focuses on Puma because Puma is the incumbent that any new Ruby web server has to justify itself against; that is the comparison most readers actually need. Falcon appears in the benchmark table in the README as a third data point, but a full design comparison against Falcon would be its own document.
+
 ## The shape of the benchmark
 
-The Raptor README carries the [current head-to-head numbers](../README.md#micro-benchmarks) against the latest Puma release, run on the same hardware with the same Rack app, 4 workers, 3 threads, 24 concurrent connections, on a recent Ruby with YJIT enabled. Two workload profiles are measured: **IO-bound** (each request sleeps for a random 5-50ms then returns a small JSON response) and **CPU-bound** (each request serialises a JSON array of 20-200 items). Rather than pin specific numbers into this document (they drift with Ruby versions and hardware), the shape of the result is what matters.
+Raptor is a research project. It hasn't run production traffic. The numbers in the README come from a repeatable microbenchmark, not from a real deployment. The benchmark measures only the **server** work: accepting connections, parsing, dispatching, and writing responses. It does not measure your application. In a typical Rails app where most of a request's time goes to ActiveRecord and downstream services, the server accounts for maybe 5 to 15 percent of the total, so a +N% number in this table will show up as a much smaller improvement in production. The gap is real, but it isn't what a Rails app against a real database will report.
+
+The Raptor README carries the [current head-to-head numbers](../README.md#micro-benchmarks) against the latest Puma and Falcon releases, run on the same hardware with the same Rack app on a recent Ruby with YJIT enabled. All three servers run four worker processes; Raptor and Puma use three threads per worker, and Falcon uses unbounded fibers per worker. Load generators use 48 concurrent HTTP/1.1 client connections, and 16 h2 connections × 3 streams each for the h2 rows.
+
+Two workload profiles are measured. **IO-bound** is a GET endpoint that does 5 to 10 short sleeps interleaved with small CPU work per request, simulating a read path that makes several DB or cache calls throughout its lifetime. **CPU-bound** is a POST endpoint with a small JSON body that builds a JSON response in 3 to 5 chunks interleaved with sub-100µs sleeps, simulating a write path that does most of its work in Ruby with a few near-zero-cost cache hits. The workloads are interleaved rather than a single bulk sleep or single bulk serialise so a fiber-per-connection server like Falcon doesn't look artificially good from one-shot IO, and the CPU-bound workload is heavily CPU-dominated by design (roughly 95% CPU / 5% IO by wall time) so it actually measures CPU work rather than smuggling in enough IO for fibers to multiplex.
 
-- On IO-bound work, both servers land near parity across all protocols; throughput is bounded by the per-request sleep and the benchmark client's concurrency, not by anything the server does.
-- On CPU-bound HTTP/1.1 without keep-alive, Raptor holds a meaningful lead; per-request parsing and response-writing overhead is a real fraction of the work.
-- On CPU-bound HTTP/1.1 with keep-alive, Raptor still leads but by a smaller margin; the app thread's JSON-building work dominates.
-- On HTTP/2 there is no comparison, since Puma does not implement it.
+Each cell in the table reports the median throughput and median p95 latency independently across 5 runs, and every run boots a fresh server process so state cannot accumulate across measurements. Rather than pin specific numbers into this document (they drift with Ruby versions and hardware), the shape of the result is what matters.
+
+- On IO-bound work, Falcon is roughly 3-4x ahead of both thread-based servers; the fiber-per-connection model can keep every one of the 48 client connections in flight at once, while Raptor and Puma cap out at their 12 threads. Between the two thread-based servers, Raptor holds a clear lead over Puma on both throughput and p95.
+- On CPU-bound HTTP/1.1 without keep-alive, the three servers land close together on throughput. Raptor's p95 is meaningfully worse than Puma's and Falcon's here; the extra hop through the pipeline shows up as tail latency when connection setup and teardown are also on the critical path.
+- On CPU-bound HTTP/1.1 with keep-alive, Raptor pulls ahead of both on throughput and p95. Connection setup is amortised, the eager keep-alive loop keeps requests on the same app thread, and the Ractor-parallel parser earns its cost when many small requests are in flight.
+- On HTTP/2, Raptor and Falcon both implement it; Puma doesn't. On CPU-bound h2 Raptor holds a small edge on throughput and a meaningful one on p95; on IO-bound h2 Falcon dominates for the same reason it dominates h1 IO. This matters if you're terminating h2 at the app server, less so if nginx or another proxy in front is already handling it.
 
 The rest of this doc explains why the shape looks like that.
 
@@ -73,7 +85,7 @@ The server thread is straightforward. It calls `IO.select` on all listener socke
 
 What happens next depends on `queue_requests`. `queue_requests` defaults to true and is the mode almost everyone runs in. When it is true, a thread-pool worker picks up the client and calls `client.eagerly_finish`, which does one non-blocking read attempt and one attempt at parsing. If the request is complete after that single read, the worker proceeds to invoke the Rack app inline. If it is not complete, the worker hands the client to the reactor and returns to the pool. When `queue_requests` is false, the worker skips the eagerly_finish attempt and does a blocking `client.finish(first_data_timeout)`. The `queue_requests: false` path is fine for fast trusted clients but does not scale; a slow client will hold a thread indefinitely.
 
-The reactor is a separate thread running `Puma::Reactor`, which wraps an `NIO::Selector` from nio4r. Its job is to babysit two kinds of sockets:
+The reactor is a separate thread running `Puma::Reactor`, which wraps an `NIO::Selector` from `nio4r`. Its job is to babysit two kinds of sockets:
 
 1. **Sockets in the middle of a request.** A client sent some headers, was not yet complete, and needs more data before the app can be called.
 2. **Keep-alive sockets between requests.** The previous request finished, the connection is still alive, and we are waiting for the next request to start.
@@ -84,7 +96,7 @@ Puma stores its reactor timeouts in a Ruby array of `Client` objects. New client
 
 Cross-thread waking is done through a pipe. When work needs to enter the reactor from another thread (a Client being registered), a byte is written to a pipe that the selector is also watching; the selector wakes, drains the input queue, and gets on with it.
 
-### Request lifecycle (HTTP/1.1)
+### HTTP/1.1 request lifecycle
 
 Putting the pieces together, a request through Puma looks like this:
 
@@ -104,16 +116,17 @@ Response writing is done from the app thread. Puma sets `TCP_CORK` on Linux, wri
 ```mermaid
 flowchart TB
     subgraph Master["Master process, cluster mode"]
-        M["Master loop"]
-        M -->|fork| W1["Worker 0"]
-        M -->|fork| W2["Worker 1"]
-        M -->|fork| W3["Worker N"]
+        MM["Master loop<br/>Reads worker pipes for<br/>per-worker vitals<br/>Handles signals"]
+        MM -->|"fork"| W1["Worker 0"]
+        MM -->|"fork"| W2["Worker 1"]
+        MM -->|"fork"| W3["Worker N"]
+        MM -.->|"SIGUSR2<br/>exec with argv"| MM
     end
 
-    subgraph Worker["Puma worker process"]
-        A["Server thread<br/>IO.select on listeners<br/>accept_nonblock"]
+    subgraph Worker["Puma worker process, one of N"]
+        SRV["Server thread<br/>IO.select on listeners<br/>accept_nonblock"]
 
-        R["Reactor thread<br/>NIO::Selector<br/>sorted timeout array"]
+        RCT["Reactor thread<br/>NIO::Selector<br/>sorted timeout array"]
 
         subgraph TP["Thread pool, Mutex + CondVar"]
             T1["Thread 1"]
@@ -121,37 +134,45 @@ flowchart TB
             T3["Thread N"]
         end
 
+        STA["Stat thread<br/>writes to worker pipe<br/>on worker_check_interval"]
+
         C1{"Complete<br/>request<br/>on accept?"}
         C2{"Complete<br/>request<br/>after read?"}
         KA{"Keep-alive?"}
         BB{"Back-to-back<br/>data in buffer?"}
 
-        A -->|"push new socket"| TP
+        SRV -->|"push new socket"| TP
         TP -->|"eagerly_finish"| C1
         C1 -->|"complete, app.call"| APP["Rack app"]
-        C1 -->|"incomplete, register"| R
-        R -->|"socket readable"| C2
+        C1 -->|"incomplete, register"| RCT
+        RCT -->|"socket readable"| C2
         C2 -->|"complete, push"| TP
-        C2 -->|"incomplete, keep waiting"| R
-        R -->|"timeout"| CLOSE1["write 408, close"]
+        C2 -->|"incomplete, keep waiting"| RCT
+        RCT -->|"timeout"| TO["write 408, close"]
         APP -->|"write response"| KA
-        KA -->|"no"| CLOSE2["close socket"]
+        KA -->|"no"| CLS["close socket"]
         KA -->|"yes"| BB
         BB -->|"yes, reprocess"| TP
-        BB -->|"no, back to reactor"| R
+        BB -->|"no, back to reactor"| RCT
+
+        STA -.->|"writes ping"| PIPE[("worker→master pipe")]
     end
 
+    MM -.->|"reads ping"| PIPE
+
     classDef accept fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
     classDef reactor fill:#fecdd3,stroke:#e11d48,color:#881337
     classDef pool fill:#fef3c7,stroke:#d97706,color:#78350f
     classDef app fill:#d1fae5,stroke:#059669,color:#064e3b
-    class A accept
-    class R reactor
+    classDef storage fill:#e5e7eb,stroke:#6b7280,color:#374151
+    class SRV accept
+    class RCT reactor
     class TP pool
     class APP app
+    class PIPE storage
 ```
 
-The key thing to notice: the parser runs inside an app thread. Puma's concurrency model is "many app threads, each doing one full request (parse plus app plus write) at a time". Under MRI's GVL this is genuine concurrency but not parallelism; at any given moment at most one of those threads is executing Ruby, and the others are either blocked on I/O (which releases the GVL and lets another thread proceed) or waiting their turn. Puma leans on the fact that most Rack apps spend most of their time blocked on the database or an external API, where threads do effectively overlap.
+Notably, the parser runs inside an app thread. Puma's concurrency model is "many app threads, each doing one full request (parse plus app plus write) at a time". Under MRI's GVL this is genuine concurrency but not parallelism; at any given moment at most one of those threads is executing Ruby, and the others are either blocked on I/O (which releases the GVL and lets another thread proceed) or waiting their turn. Puma leans on the fact that most Rack apps spend most of their time blocked on the database or an external API, where threads do effectively overlap.
 
 ## Part II: Raptor
 
@@ -175,7 +196,21 @@ Master-to-worker communication does not use pipes. Every worker writes its stats
 
 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.
 
-### Per-worker threading model
+### Refork
+
+Long-lived workers accumulate mutations. Every allocation, every YJIT-compiled block, every gem that lazy-loads on first use, every cache that populates over the first few thousand requests, all of it dirties pages that were shared copy-on-write with the master. After a few hours of traffic the CoW savings are mostly gone and each worker's RSS climbs toward its steady-state size. Reforking off a warmed source is the standard answer.
+
+Raptor's version is driven by `refork_after`, an `Integer`, `Array<Integer>`, or `nil`. When any worker's request count crosses the next threshold, the master picks the most-experienced booted worker in the current phase and sends it `SIGURG`. That worker breaks out of its main loop, runs any `before_refork` hooks (typically to close database connections and any other file descriptors the fresh workers should not inherit), drains in-flight requests, and then transitions into a seed loop instead of exiting. From that point on the seed's only job is to fork replacement workers on the master's request; it never accepts another connection. The master then rolls the remaining workers through a phased restart, forking each replacement from the seed.
+
+Successive thresholds promote fresh seeds. When the next threshold trips, the master picks a new candidate from the currently-serving generation, terminates the previous seed, and starts the same drain-and-promote cycle on the new candidate. Each generation's fork source is therefore a worker that has served enough traffic to warm its VM, its YJIT caches, and its lazy-loaded gems, and the previous generation's seed is retired the moment it is no longer needed. Passing an array to `refork_after` (e.g. `[1000, 5000, 20_000]`) sets successive thresholds; the last one repeats.
+
+Master and seed communicate over two pipes opened before the initial fork. The fork pipe (`@fork_r`, `@fork_w`) carries an 8-byte packed `[slot_index, phase]` from master to seed for each replacement to fork. The response pipe (`@resp_r`, `@resp_w`) carries a 4-byte packed pid back the other way, plus a one-shot 4-byte zero the seed writes when it enters its loop so the master knows drain is complete. The master polls the ready marker non-blockingly on the supervision loop; the phased restart that fills the vacated slot and cycles the remaining workers only starts once the marker arrives (or the drain deadline expires, in which case the master clears the seed reference and falls back to direct forks).
+
+Workers forked by the seed are not the master's direct children. Before spawning anything the master calls `PR_SET_CHILD_SUBREAPER` (via a small `Raptor::Subreaper` C extension wrapping `prctl`), so seed-forked children reparent to the master immediately and `Process.wait2` sees them like any other child. When a seed is retired on the next promotion its still-running descendants stay attached to the master through the same subreaper bit. Refork depends on this: on platforms without `PR_SET_CHILD_SUBREAPER` — everything except Linux — `refork_after` defaults to `nil` and is ignored with a warning if the user sets it anyway.
+
+The design is Pitchfork's, adapted for Raptor's process model. [Pitchfork](https://github.com/Shopify/pitchfork) was the first Ruby server built around `PR_SET_CHILD_SUBREAPER` and multi-generation mould promotion; Puma's shipping `fork_worker` keeps worker 0 serving traffic alongside its fork-server duties, and Instacart's [`mold_worker` PR #3643](https://github.com/puma/puma/pull/3643) is Puma catching up to the same shape Pitchfork established. Raptor's seed matches the Pitchfork shape: pure fork source, promoted from a warm worker, retired when the next generation takes over.
+
+### Threading model
 
 This is where Raptor diverges dramatically. Inside a worker there are five kinds of concurrent activity:
 
@@ -188,11 +223,13 @@ This is where Raptor diverges dramatically. Inside a worker there are five kinds
 
 That is a lot of moving parts. Let us go through why.
 
-**Why Ractors for parsing.** Ractors are Ruby's answer to true parallelism. Multiple Ractors can execute Ruby code simultaneously on different OS threads, each with its own GVL. But Ractors are heavily restricted: they can only share frozen data, they cannot access most global mutable state, and code inside a Ractor cannot use most existing gems (which universally assume shared-state semantics).
+**Why Ractors for parsing.** Ractors are Ruby's answer to true parallelism. Multiple Ractors can execute Ruby code simultaneously on different OS threads, each with its own GVL. But Ractors are heavily restricted. They can only share frozen data, they cannot access most global mutable state, and code inside a Ractor cannot use most existing gems (which universally assume shared-state semantics).
 
 For a web server, this restriction turns out to be almost exactly right for HTTP parsing. Parsing a request is CPU-bound (tokenising bytes, uppercasing header names, decoding chunked bodies), it does not need to touch any global state, and it produces a result (a hash) that can be safely frozen and handed off. The native HTTP/1 parser (`raptor_http.c`) is declared `rb_ext_ractor_safe(true)`: it holds no per-parser Ruby state in the extension itself, and it writes only into the caller-supplied env hash. Same for the HTTP/2 parser plus HPACK.
 
-The upshot: while your Rack app runs on regular threads under the GVL (so your app does not need to be Ractor-safe), the protocol-level work runs in parallel across Ractors. Under heavy load with lots of small requests, the GVL contention that would otherwise dominate parsing simply is not there.
+The HTTP/1 parser also pre-interns the ~40 most common header keys (`HTTP_HOST`, `HTTP_USER_AGENT`, the `HTTP_ACCEPT_*` family, `CONTENT_LENGTH`, `HTTP_X_FORWARDED_*`, the `HTTP_SEC_FETCH_*` client hints, and so on) once at load time. During parsing, a `memcmp` lookup against that table returns the shared frozen `VALUE` for known keys and falls back to `rb_enc_interned_str` for the rest. Every request's env hash therefore reuses the same String object for its header names, which both skips per-request allocation and lets Ruby's hash lookup use the interned key's cached hash code.
+
+The upshot is that while your Rack app runs on regular threads under the GVL (so your app does not need to be Ractor-safe), the protocol-level work runs in parallel across Ractors. Under heavy load with lots of small requests, the GVL contention that would otherwise dominate parsing simply is not there.
 
 **How the Ractor pool actually works.** Raptor uses the `ractor-pool` gem, which is another one of my libraries. The pool has one coordinator Ractor and M pipeline Ractors. When a pipeline Ractor is idle, it sends itself back to the coordinator via `coordinator.send(Ractor.current, move: true)`. When work arrives at the coordinator, it either forwards it to a waiting Ractor (if any) or queues it. This coordinator-dispatch pattern guarantees that no Ractor sits idle while there is work. Results flow back through a shared `Ractor::Port` (a many-to-one channel added in recent Ruby versions and stable in 4.0) to a Ruby-side collector thread. If `M == 1` the coordinator is skipped and work goes straight to the single pipeline Ractor; this is the default because a single Ractor already parses in parallel with the app threads and adds enough headroom for typical workloads.
 
@@ -216,9 +253,11 @@ next if @reactor.backlog >= backpressure_threshold
 
 where `@reactor.backlog` is `thread_pool.queue_size + thread_pool.active_count`. If the total load on the thread pool is at 120% of the pool size, this worker stops accepting until it drains. `MIN_BACKPRESSURE_THRESHOLD` is 8, so small pools (say, 3 threads) trip backpressure at 8 concurrent items rather than at 120% of a very small number; the floor keeps saturated workers signaling early so the load-aware dispatcher (below) has time to route around them.
 
-Because Raptor is always in cluster mode and every worker listens in the same `SO_REUSEPORT` group, load balancing across workers happens at the kernel level. On Linux, Raptor attaches a small BPF program to the reuseport group. Each worker binds its own listener registered in a sockmap, and a dedicated reporter thread publishes the worker's current reactor backlog into a loads map at 100 Hz. The BPF program consults the map on every incoming connection and routes it to the least-loaded worker, with a random tie-break when loads are equal. If the `libbpf-ruby` gem is not installed or the BPF object has not been compiled, Raptor falls back silently to the default four-tuple-hash routing; if the kernel refuses the program, startup raises. Either way, if a worker is saturated and stops calling `accept`, other workers pick up the slack.
+Because Raptor is always in cluster mode and every worker listens in the same `SO_REUSEPORT` group, load balancing across workers happens at the kernel level. On Linux, Raptor attaches a small BPF program to the reuseport group. Each worker binds its own listener registered in a sockmap, and a dedicated reporter thread publishes the worker's current reactor backlog into a loads map at 100 Hz. The BPF program consults the map on every incoming connection and routes it to the least-loaded worker; when all workers report equal load (typical of a fresh accept burst), the program falls back to the connection's 4-tuple hash, which spreads accepts more evenly than a random draw across a small worker count. If the `libbpf-ruby` gem is not installed or the BPF object has not been compiled, Raptor falls back silently to the default four-tuple-hash routing; if the kernel refuses the program, startup raises. Either way, if a worker is saturated and stops calling `accept`, other workers pick up the slack.
 
-The reactor is again an NIO::Selector loop. Two things make it different from Puma's:
+The BPF-based approach was inspired by [a comment](https://github.com/puma/puma/issues/3934#issuecomment-4356462590) by John Hawthorn ([@jhawthorn](https://github.com/jhawthorn)) on a Puma issue about `EPOLLEXCLUSIVE`, where he floated `SO_ATTACH_REUSEPORT_EBPF` as a way to route each connection to the least-busy worker.
+
+The reactor is again an `NIO::Selector` loop. Two things make it different from Puma's:
 
 1. **Read strategy.** When a socket is readable, the reactor does one `read_nonblock(64KB)` right there in the reactor thread, updates the buffered state for that connection, and only then decides what to do. If the request is not yet complete, the state stays in the reactor and awaits more data. If it is complete (headers parsed, body received), the state is pushed to the Ractor pool for parsing (or, for HTTP/2, straight to the parser). The reactor does not try to parse; it does the I/O and hands off the raw buffer.
 
@@ -279,10 +318,10 @@ From there the shape is similar to HTTP/1.1:
 
 1. Reactor reads frames.
 2. The HTTP/2 parser (native C, with an HPACK decoder using a static Huffman table) parses the frames in the Ractor pool.
-3. Completed requests (once HEADERS+DATA is complete for a stream) go to the thread pool as separate work items. **A single connection can be servicing many streams in parallel across the thread pool.**
+3. Completed requests (once `HEADERS` and `DATA` are complete for a stream) go to the thread pool as separate work items. **A single connection can be servicing many streams in parallel across the thread pool.**
 4. Each stream's response is written back through the connection's `Writer`, which serialises frame writes across threads without a mutex.
 
-The Writer is worth a paragraph. Naive per-connection writing would use a mutex: acquire, write, release. Contention grows with concurrent streams. Raptor's Writer stores the "pending frames" queue in an `Atom` whose value is either `:idle` (nobody is writing) or an array of frames waiting to go out. A thread that wants to write does a CAS:
+The `Writer` is worth a paragraph. Naive per-connection writing would use a mutex: acquire, write, release. Contention grows with concurrent streams. Raptor's `Writer` stores the "pending frames" queue in an `Atom` whose value is either `:idle` (nobody is writing) or an array of frames waiting to go out. A thread that wants to write does a CAS:
 
 - If current value is `:idle`, the thread claims the writer by CAS-ing to its own array of frames, then loops draining any additional frames other threads have appended.
 - If current value is an array (someone is already writing), the thread CAS-appends its frames and returns immediately; the current writer will pick them up and flush them.
@@ -341,7 +380,7 @@ flowchart TB
         ATP -->|"app.call + write"| KA
         KA -->|"no, close"| CLS["close socket"]
         KA -->|"yes"| EAG
-        EAG -->|"bytes within 1ms"| ATP
+        EAG -.->|"bytes within 1ms, parse+dispatch on same thread"| ATP
         EAG -->|"no bytes, reactor.persist"| RCT
         RCT -->|"timeout expired"| TO["write 408, close"]
 
@@ -364,7 +403,7 @@ flowchart TB
     class SHM storage
 ```
 
-The critical structural difference from Puma: parsing is not on the app thread. It is on the Ractor pool. The app thread only does the Rack call and the response write. This decouples the two costs and lets Ruby actually use more than one CPU for the protocol work.
+The critical structural difference from Puma is that parsing is not on the app thread. It is on the Ractor pool. The app thread only does the Rack call and the response write. This decouples the two costs and lets Ruby actually use more than one CPU for the protocol work.
 
 ## Part III: Head to head
 
@@ -388,7 +427,7 @@ At a moderate 100 concurrent connections this is a rounding error. At 1000+ (whi
 
 **Puma.** Standard `Mutex` + `ConditionVariable` + Array-as-queue. Every enqueue takes the mutex, wakes a waiter. Every dequeue takes the mutex to check the queue. Under contention, the mutex is a serialisation point.
 
-**Raptor.** CAS on an Atom holding a frozen `{in:, out:, count:}` hash (Banker's queue). Enqueue is a single CAS to prepend to the in-stack. Dequeue is a single CAS to pop from the out-stack (or, if empty, atomically flip in/out). Metrics (queue length, active count) are lock-free reads.
+**Raptor.** CAS on an `Atom` holding a frozen `{in:, out:, count:}` hash (Banker's queue). Enqueue is a single CAS to prepend to the in-stack. Dequeue is a single CAS to pop from the out-stack (or, if empty, atomically flip in/out). Metrics (queue length, active count) are lock-free reads.
 
 The condvar is still there for parking idle threads (spinning would burn CPU), but the hot path when the queue has items is lock-free.
 
@@ -398,11 +437,11 @@ Under moderate load these look equivalent. Under high concurrency (many threads
 
 **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` (a single non-blocking read attempt) 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, parse and dispatch the next request inline on the same thread. Otherwise `reactor.persist` and return.
+**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.
 
-The difference is subtle but the numbers show it up. Real-world clients pipelining requests often send the next request 100-500 microseconds after the previous response completes. Puma's `eagerly_finish` catches the case where bytes are already in the socket buffer; Raptor's `wait_readable(1ms)` catches both the "already buffered" case and the "arriving very shortly" case. And Raptor never has to hand the socket back to a different thread; the response-writing thread parses the next request itself.
+The difference is subtle but the numbers show it up. Real-world clients pipelining requests often send the next request 100-500 microseconds after the previous response completes. Puma's `eagerly_finish` catches the case where bytes are already in the socket buffer; Raptor's `wait_readable(1ms)` catches both the "already buffered" case and the "arriving very shortly" case. And Raptor always parses the next request on the response-writing thread, so the parse itself never crosses a thread boundary.
 
-This is where most of Raptor's keep-alive edge comes from. Under the benchmark load, with a small number of concurrent connections all doing keep-alive, every connection is issuing back-to-back requests, and Raptor's app threads are essentially processing a single connection each in a tight loop until the connection stops. Puma's app threads do the same when they can, but the coordination overhead between thread pool and reactor for the transitions costs meaningfully more.
+This is where most of Raptor's keep-alive edge comes from. Subsequent requests are always parsed and dispatched 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 for another thread to pick up (when it is not). Puma's app threads do the same when they can, but the coordination overhead between thread pool and reactor for the transitions costs meaningfully more.
 
 ### Backpressure
 
@@ -420,10 +459,12 @@ The performance difference here is negligible. Stats writing is one syscall per
 
 ### HTTP/2
 
-**Puma.** Not implemented. `alpn_protocols` is not advertised, so h2 clients fall back to h1.
+**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.
 
 **Raptor.** Native C parser plus HPACK, per-stream flow control, lock-free frame writer, stream multiplexing over a single connection. Same request path as HTTP/1.1 once a request is complete: it enters the same thread pool. Under HTTP/2, a single client connection can be issuing many concurrent requests, and Raptor services all of them in parallel on the same thread pool.
 
+Whether that matters depends on your setup. If you terminate TLS at an edge proxy that already speaks HTTP/2, both servers see HTTP/1.1 and it doesn't matter which of them you pick on this axis. If you're building an all-Ruby stack with no proxy in front, running gRPC or similar all the way through, or measuring the app server itself, HTTP/2 support is where Raptor and Puma stop being comparable.
+
 At the throughput numbers the benchmark shows, with only a handful of concurrent connections each multiplexing many streams, Raptor is exercising the HTTP/2 multiplexing hard: many in-flight streams sharing one socket, all writing responses through the same connection. The writer's CAS-based coordination avoids the mutex contention that would otherwise cap throughput.
 
 ### Response writing
@@ -434,6 +475,10 @@ On the HTTP/1.1 path, Raptor has a small `writev(2)` C extension (`Raptor::Vecto
 
 HTTP/1.1 responses also reuse a per-thread String buffer for the status line and headers rather than allocating one per response. The buffer grows once to fit the largest response the thread has served and stays that size afterwards, so subsequent responses on that thread skip the allocation entirely.
 
+Chunked responses with an array or file body accumulate chunk-framed writes into the response buffer up to 512KB before flushing to the socket, collapsing what would be N `write` syscalls for an N-chunk body into a handful. Enumerable bodies (SSE, long-polling, per-line log tailing) still flush every chunk, so streaming semantics are preserved.
+
+Around the response boundary, HTTP/1.1 also amortises the common per-request allocations. A frozen Rack env template with the static keys (`rack.version`, `rack.hijack?`, `SCRIPT_NAME`, `QUERY_STRING`, `SERVER_SOFTWARE`) is duped per request, so the app-thread env build only writes the dynamic keys. Response header serialisation appends directly onto the response buffer instead of allocating intermediate `Array` wraps and `flat_map` products for each header value.
+
 ### Keep-alive request by request
 
 Because the keep-alive fast path is where Raptor's throughput edge shows up, here is each server processing three back-to-back requests on the same connection. Drawn separately so the participant columns stay wide enough to read. Compare the number of boundaries each request has to cross.
@@ -476,16 +521,12 @@ sequenceDiagram
     autonumber
     participant Client
     participant RS as Server thread
-    participant RR as Reactor thread
-    participant RC as Pipeline Ractor
     participant RP as App thread
 
     Note over Client,RP: Request 1, initial
     Client->>RS: SYN, request bytes
-    RS->>RR: reactor.add
-    RR->>RC: shareable state
-    RC->>RC: parse on own Ractor GVL
-    RC->>RP: dispatch complete request
+    RS->>RS: eager_accept, read + parse inline
+    RS->>RP: push proc to thread pool
     RP->>Client: response 1
 
     Note over Client,RP: Request 2, pipelined a few hundred us later
@@ -506,27 +547,33 @@ Puma has to bounce Request 3 through the reactor and back through the mutex-prot
 
 ## Part IV: What Raptor's design buys you
 
-### IO-bound work, close to parity
+### IO-bound work, where Falcon wins and Raptor clearly beats Puma
+
+On the IO-bound benchmark profile, each request does 5 to 10 short sleeps interleaved with small CPU work, simulating a request that makes several DB or cache calls throughout its lifetime. The bottleneck is how many requests a worker can keep in flight while they wait on IO. Raptor and Puma cap out at their 12 total threads (4 workers × 3), so with 48 client connections the extra 36 sit in the pool queue at any given moment. Falcon spawns a fiber per connection and cooperatively yields on every sleep, so all 48 requests can be in flight simultaneously. That gap shows up as roughly 3-4x throughput and much lower p95 for Falcon.
+
+Between the thread-based servers, Raptor holds a clear lead over Puma on both throughput and p95. The eager accept path, writev-batched responses, and lock-free work queue all shave a bit of per-request time, and those savings stack.
+
+Real applications that spend most of their time waiting on a database or an upstream service look like this. If your app is IO-heavy and you're free to adopt the `async` ecosystem, Falcon is the interesting comparison there, not Raptor or Puma.
 
-On the IO-bound benchmark profile, each request sleeps for a random 5-50ms then returns a small JSON payload. Throughput is bounded by the per-request sleep and the benchmark client's 24-connection concurrency; both servers push those requests through their pipelines faster than the sleep completes, so what shows up in the numbers is the workload cost itself, not the server cost. Raptor and Puma land within a few percent of each other in both keep-alive modes because there is nothing to differentiate.
+### CPU-bound HTTP/1.1, where the pool model earns its keep
 
-Real applications that spend most of their time waiting on a database or an upstream service look like this. The choice between Raptor and Puma there is not throughput-driven.
+On the CPU-bound benchmark profile, each POST request accepts a small JSON body and builds a JSON response in 3 to 5 chunks totalling 450 to 1500 items, with sub-100µs sleeps between chunks. It's roughly 95% CPU by wall time, so fibers can't multiplex their way to an advantage. The CPU work happens under a single Ruby VM regardless of concurrency model.
 
-### CPU-bound HTTP/1.1, where the edge shows up
+**Without keep-alive**, every request opens a fresh TCP connection, gets parsed, dispatched, served, and closes. All three servers land within a few percent of each other on throughput. Raptor's p95 is meaningfully worse than Puma's and Falcon's here; the extra hop through the Ractor pipeline shows up as tail latency when connection setup and teardown are also on the critical path.
 
-On the CPU-bound benchmark profile, each request serialises a JSON array of 20-200 items. Per-request cost is real Ruby work, and the coordination overhead of pushing a request through the server matters.
+**With keep-alive**, Raptor pulls ahead of both Puma and Falcon on throughput and p95. Connection setup is amortised, the eager keep-alive loop keeps subsequent requests on the same app thread, and the Ractor-parallel parser earns its cost when many small requests are in flight. This is the shape of workload Raptor's design was optimised for.
 
-**Without keep-alive**, every request opens a fresh TCP connection, gets parsed, dispatched, served, and closes. Raptor lands materially ahead of Puma. The wins that individually add a few percent (writev-batched response writes, CAS-based work queue, per-worker CPU affinity) stack more prominently here because per-request coordination is a larger fraction of total time than under keep-alive.
+### HTTP/2, when it matters
 
-**With keep-alive**, Raptor still leads but by a smaller margin. Every connection amortises accept and TCP-setup costs to zero, and the app thread's JSON-building work dominates the per-request budget. The eager keep-alive loop keeps both servers close to their pool ceiling, and Raptor's coordination-overhead advantages become a smaller relative slice.
+Puma doesn't implement HTTP/2, and most Rails production terminates HTTP/2 at nginx or a similar edge proxy before it reaches the app server. If that describes your stack, Raptor's HTTP/2 support isn't going to help you. Both servers see HTTP/1.1 from the proxy and the throughput numbers above are what actually matter. Puma's [position](https://github.com/puma/puma/issues/2697) is that this is where h2 belongs, and it's a reasonable one.
 
-Raptor's eager keep-alive loop is still doing real work here; it keeps the socket on the same app thread for the entire burst, avoiding the reactor round-trip Puma has to make between requests. But when the work per request is large enough, that round-trip is a smaller share of the total.
+Where Raptor's HTTP/2 support does matter is the all-Ruby stack. No proxy in front, TLS terminated at the app, clients speaking h2 all the way through (`curl --http2`, gRPC-Ruby transports, HTTP/2-only SDKs, direct browser connections). In that setup, Puma silently falls back to HTTP/1.1 and you lose multiplexing, header compression, and prioritisation.
 
-### HTTP/2, a category to itself
+Falcon also speaks HTTP/2 natively, so it's the interesting comparison there rather than Puma. The shape of the h2 result follows the h1 shape. On CPU-bound h2 Raptor holds a small edge on throughput and a meaningful one on p95, for the same reasons it wins CPU-bound h1 keep-alive. Parsing runs in parallel with the app, the lock-free writer serialises frames without a mutex, and per-stream flow-control atoms don't contend. On IO-bound h2 Falcon wins by a wide margin, again because fibers can keep every stream in flight simultaneously while Raptor's thread pool caps concurrency.
 
-Puma does not implement HTTP/2. Raptor does, natively, with a Ractor-safe parser, HPACK, per-stream flow control, and a lock-free frame writer. If your clients default to h2 (most browsers, `curl --http2`, gRPC-flavoured stacks, most modern SDKs), or if you terminate TLS at your app rather than upstream, this alone is decisive: on Puma you silently fall back to HTTP/1.1 and lose multiplexing, header compression, and prioritisation.
+Raptor's h2 IO numbers still show some run-to-run variance where h1 doesn't. With only 16 physical connections spread across four workers, even the BPF program's hash-based tie-break can leave one worker over-subscribed, and the concentrated worker becomes the bottleneck for that whole run. h2 CPU stays tight because once workers report distinguishable load the load-aware routing has enough signal to place new connections cleanly regardless of tie-break behaviour.
 
-Beyond parity, Raptor's HTTP/2 CPU-bound throughput in the benchmark is on the same order as its HTTP/1.1 keep-alive throughput on the same profile, despite each connection multiplexing dozens of concurrent streams into a single socket. That only happens if the per-stream coordination is essentially free. The lock-free `Writer` and flow-control atoms are doing real work here. If they used mutexes, throughput would be capped by lock contention rather than by CPU.
+Beyond that, Raptor's HTTP/2 CPU-bound throughput in the benchmark is on the same order as its HTTP/1.1 keep-alive throughput on the same profile, despite each connection multiplexing dozens of concurrent streams into a single socket. That only happens if the per-stream coordination is essentially free. The lock-free `Writer` and flow-control atoms are doing real work here. If they used mutexes, throughput would be capped by lock contention rather than by CPU.
 
 ## Part V: What Raptor gives up
 
@@ -536,22 +583,4 @@ No design comes free. Two disclosures matter most.
 
 **Ruby version.** Raptor requires Ruby 4.0 because it depends on `Ractor::Port` and on Ractor internals having stabilised. Puma works on 3.0 and up. If you need to support older Ruby, Puma wins by default.
 
-A handful of smaller trade-offs are worth naming briefly. Raptor pays some minimum-latency overhead per request because of the Ractor crossing, so at extremely low concurrency Puma's simpler flow can edge ahead; the eager-parse path on the server thread hides most of this in practice. Raptor's core dependencies (`ractor-pool`, `atomic-ruby`, `red-black-tree`, `mmap-ruby`, `libbpf-ruby`) are libraries I wrote specifically to make it work, which is either "purpose-built" or "narrower testing surface" depending on how you look at it. Debugging is harder because control flow crosses Ractor and thread boundaries, so tracing a request end-to-end means stitching several stack traces together. Raptor has no single-process mode; on a single-CPU container it wastes a small amount of coordination overhead. And Puma's `fork_worker: true` refork mode is a genuinely clever answer to CoW decay over time that Raptor has no equivalent for.
-
-## Part VI: The design in one line each
-
-If you had to compress this whole document into a handful of one-line framings, these are the ones that carry the most:
-
-- **"Puma is a thread pool with a reactor bolted on. Raptor is a pipeline with each stage on its own scheduling primitive."** Puma's core abstraction is the thread pool; the reactor exists to feed it. Raptor's core abstraction is the pipeline; the thread pool is one stage in it.
-
-- **"The GVL is not the enemy. Serialising parsing behind the GVL is the enemy."** Ruby threads are fine for I/O-bound work; the app thread spends most of its time waiting on the database. What you cannot afford is spending CPU cycles under the GVL doing work that does not need the GVL, like tokenising HTTP headers.
-
-- **"Ractors are impractical for user code but perfect for protocol code."** The very things that make Ractors annoying for application code (frozen data only, no shared mutable state) are exactly what you want in a parser: a pure function from bytes to headers with no side effects.
-
-- **"Lock-free is not always faster, but it is always less variable."** A CAS-based queue does not out-perform a mutex in every scenario, but its worst-case latency is much better. Under contention, mutex-based code can suffer thundering herd wakeups and cache-line bouncing that a CAS design avoids.
-
-- **"The keep-alive edge is not one big win, it is many small wins that stack."** Eager keep-alive, RBT timeouts, CAS work queue, Ractor parsing, lock-free backpressure. Each adds a few percent and stacked they produce a measurable lead.
-
-- **"HTTP/2 is not a nice-to-have; it changes the arithmetic."** With HTTP/2, one client connection can be doing dozens of requests concurrently. Suddenly every serialisation point in the server becomes a bottleneck. The lock-free primitives Raptor uses for HTTP/1.1 are not optional for HTTP/2; they are structural.
-
-- **"This is what Ruby 4 lets you do."** `Ractor::Port`, `Ractor.shareable_proc`, `rb_ext_ractor_safe`, native-extension Ractor safety. These are all recent additions. Raptor is essentially a demo of what becomes practical when you have them.
+A handful of smaller trade-offs are worth naming briefly. Raptor pays some minimum-latency overhead per request because of the Ractor crossing, so at extremely low concurrency Puma's simpler flow can edge ahead; the eager-parse path on the server thread hides most of this in practice. Raptor's core dependencies (`ractor-pool`, `atomic-ruby`, `red-black-tree`, `mmap-ruby`, `libbpf-ruby`) are libraries I wrote specifically to make it work, which is either "purpose-built" or "narrower testing surface" depending on how you look at it. Debugging is harder because control flow crosses Ractor and thread boundaries, so tracing a request end-to-end means stitching several stack traces together. Raptor has no single-process mode; on a single-CPU container it wastes a small amount of coordination overhead.

data/ext/raptor_bpf/reuseport_select.bpf.c

@@ -20,7 +20,8 @@ struct {
 } loads SEC(".maps");
 
 // Routes each incoming connection to the worker with the lowest backlog,
-// with a random tie-break when loads are equal.
+// falling back to the connection's 4-tuple hash when loads are equal so
+// bursts of accepts spread across workers instead of clustering by chance.
 SEC("sk_reuseport")
 int select_least_loaded(struct sk_reuseport_md *ctx) {
   __u32 count_key = 0;
@@ -55,7 +56,7 @@ int select_least_loaded(struct sk_reuseport_md *ctx) {
     }
   }
 
-  __u32 chosen_idx = (min_load == max_load) ? (bpf_get_prandom_u32() % num_workers) : min_idx;
+  __u32 chosen_idx = (min_load == max_load) ? (ctx->hash % num_workers) : min_idx;
   bpf_sk_select_reuseport(ctx, &socks, &chosen_idx, 0);
   return SK_PASS;
 }

data/ext/raptor_http/raptor_http.c

@@ -121,6 +121,21 @@ static inline void upcase_header_char(char *c) {
     *c = '_';
 }
 
+static int contains_chunked(const char *value, long len) {
+  static const char chunked[] = "chunked";
+  static const long chunked_len = sizeof(chunked) - 1;
+
+  if (len < chunked_len) return 0;
+  for (long start = 0; start + chunked_len <= len; start++) {
+    long i;
+    for (i = 0; i < chunked_len; i++) {
+      if ((char)tolower((unsigned char)value[start + i]) != chunked[i]) break;
+    }
+    if (i == chunked_len) return 1;
+  }
+  return 0;
+}
+
 static const int raptor_parser_start = 1;
 static const int raptor_parser_first_final = 46;
 static const int raptor_parser_error = 0;
@@ -392,7 +407,7 @@ tr26:
         parser->flags |= FLAG_HAS_BODY;
     } else if (needs_http_prefix && parser->field_len == 17 &&
                memcmp(field_ptr, "TRANSFER_ENCODING", 17) == 0) {
-      if (strstr(RSTRING_PTR(value), "chunked")) {
+      if (contains_chunked(value_ptr, value_real_len)) {
         parser->flags |= FLAG_CHUNKED | FLAG_HAS_BODY;
         parser->content_len = 0;
       }
@@ -452,7 +467,7 @@ tr29:
         parser->flags |= FLAG_HAS_BODY;
     } else if (needs_http_prefix && parser->field_len == 17 &&
                memcmp(field_ptr, "TRANSFER_ENCODING", 17) == 0) {
-      if (strstr(RSTRING_PTR(value), "chunked")) {
+      if (contains_chunked(value_ptr, value_real_len)) {
         parser->flags |= FLAG_CHUNKED | FLAG_HAS_BODY;
         parser->content_len = 0;
       }
@@ -1160,7 +1175,10 @@ case 45:
 
 done:
   parser->cs = cs;
-  parser->nread = p - buffer;
+  parser->nread = (parser->flags & FLAG_FINISHED) ? parser->body_start : (size_t)(p - buffer);
+
+  if (parser->nread > MAX_HEADER_LENGTH)
+    rb_raise(eHttpParserError, "request header too long");
 
   assert(p <= pe && "buffer overflow after parsing execute");
   assert(parser->nread <= len && "nread longer than length");
@@ -1267,6 +1285,12 @@ static VALUE parser_has_body_p(VALUE self) {
   return raptor_parser_has_body(parser) ? Qtrue : Qfalse;
 }
 
+static VALUE parser_chunked_p(VALUE self) {
+  raptor_parser *parser;
+  TypedData_Get_Struct(self, raptor_parser, &parser_type, parser);
+  return raptor_parser_is_chunked(parser) ? Qtrue : Qfalse;
+}
+
 static VALUE parser_content_length(VALUE self) {
   raptor_parser *parser;
   TypedData_Get_Struct(self, raptor_parser, &parser_type, parser);
@@ -1322,6 +1346,7 @@ RUBY_FUNC_EXPORTED void Init_raptor_http(void) {
   rb_define_method(cHttpParser, "execute", parser_execute, 3);
   rb_define_method(cHttpParser, "finished?", parser_finished_p, 0);
   rb_define_method(cHttpParser, "has_body?", parser_has_body_p, 0);
+  rb_define_method(cHttpParser, "chunked?", parser_chunked_p, 0);
   rb_define_method(cHttpParser, "content_length", parser_content_length, 0);
   rb_define_method(cHttpParser, "nread", parser_nread, 0);
   rb_define_method(cHttpParser, "reset", parser_reset, 0);

data/ext/raptor_native/raptor_native.c

@@ -10,6 +10,7 @@
 
 #ifdef __linux__
 #include <sched.h>
+#include <sys/prctl.h>
 #include <unistd.h>
 #endif
 
@@ -82,18 +83,31 @@ static VALUE raptor_native_cpu_count(VALUE self) {
 #endif
 }
 
+static VALUE raptor_native_enable_subreaper(VALUE self) {
+  (void)self;
+#if defined(__linux__) && defined(PR_SET_CHILD_SUBREAPER)
+  if (prctl(PR_SET_CHILD_SUBREAPER, 1, 0, 0, 0) < 0) rb_sys_fail("prctl");
+  return Qtrue;
+#else
+  return Qfalse;
+#endif
+}
+
 RUBY_FUNC_EXPORTED void Init_raptor_native(void) {
   rb_ext_ractor_safe(true);
 
   VALUE mRaptor = rb_define_module("Raptor");
-  VALUE mVectorIO = rb_define_module_under(mRaptor, "VectorIO");
-  VALUE mCPU = rb_define_module_under(mRaptor, "CPU");
 
+  VALUE mVectorIO = rb_define_module_under(mRaptor, "VectorIO");
   rb_define_singleton_method(mVectorIO, "writev_nonblock", raptor_native_writev_nonblock, 2);
 
+  VALUE mCPU = rb_define_module_under(mRaptor, "CPU");
   rb_define_singleton_method(mCPU, "pin", raptor_native_pin_to_cpu, 1);
   rb_define_singleton_method(mCPU, "count", raptor_native_cpu_count, 0);
 
+  VALUE mSubreaper = rb_define_module_under(mRaptor, "Subreaper");
+  rb_define_singleton_method(mSubreaper, "enable", raptor_native_enable_subreaper, 0);
+
   eEAGAINWaitWritable = rb_const_get(rb_cIO, rb_intern("EAGAINWaitWritable"));
   rb_global_variable(&eEAGAINWaitWritable);
 }

data/lib/raptor/cli.rb

@@ -56,6 +56,11 @@ module Raptor
       worker_timeout: 60,
       worker_drain_timeout: 25,
       worker_shutdown_timeout: 30,
+      refork_after: (RUBY_PLATFORM.include?("linux") ? 1000 : nil),
+      before_fork: [].freeze,
+      before_worker_boot: [].freeze,
+      before_worker_shutdown: [].freeze,
+      before_refork: [].freeze,
       stats_file: "tmp/raptor.json",
       pid_file: nil,
       stdout_file: nil,
@@ -187,9 +192,9 @@ module Raptor
     #
     # @rbs (Array[String] argv) -> String?
     def extract_config_path(argv)
-      argv.each_with_index do |arg, i|
+      argv.each_with_index do |arg, index|
         case arg
-        when "-c", "--config" then return argv[i + 1]
+        when "-c", "--config" then return argv[index + 1]
         when /\A--config=(.*)\z/, /\A-c(.+)\z/ then return Regexp.last_match(1)
         end
       end
@@ -312,6 +317,10 @@ module Raptor
           @options[:worker_shutdown_timeout] = timeout
         end
 
+        opts.on("--refork-after NUM", Integer, "Refork workers from a warmed source after any worker crosses NUM requests; 0 disables (default: 1000)") do |num|
+          @options[:refork_after] = num
+        end
+
         opts.on("--stats-file PATH", String, "Stats file path (default: tmp/raptor.json)") do |path|
           @options[:stats_file] = path
         end