raptor 0.21.0 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fa644eb1b4bc0f253823d74dcd806125176ef6940410f6ed332a7ae446be2e6
-  data.tar.gz: a100f4830e44b1ed3cce30e2549ddfe95c4bc648d4d0e1b0f4ffa9aee9906269
+  metadata.gz: fc05eb1a4a916e5094c4496f18a3d3b179869a42efc1a7fd42ccda546b46e0bc
+  data.tar.gz: 1b975f682fcbaea183226775277cf441d4996899f4348237b96bf073586b1082
 SHA512:
-  metadata.gz: 79ac90d569223b7826731aae20441dcec3362cd92b8e03eca3ee243492c0f41d20edab8dc5ddb06a3099b642bb6774b1bd013397d3c33798be9057c57c4f53e4
-  data.tar.gz: e007cf30032b2a0053c8f7b15fca20a376a7dcd85c5cb3ec57591dd48d84daa69f51d4e294a60cfa6ac8c9df1f15b39d1f30a33ffa6709071efa72dfde4a6a33
+  metadata.gz: c39ee7c2d2c4f68b8015a841c3fdadfb26b42f587041d6e85e69fc930abcb9fe65ce4841e3562c31b2ff6a0ac904787ba97ca1a26dafa25ba7a0f71b0069b2a1
+  data.tar.gz: 71604474925af588347c5e82f294eca27b5d51c3dc161ece9bb63508b9ea389196173cf890be8f8ebbd030dea284fc1e0d9f4aac26650f02c05303eb09707c7c

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [0.22.0] - 2026-10-03
+
+- Add detached HTTP/1.1 response bodies
+- Add detached HTTP/2 response bodies
+- Move HTTP/2 writes to the reactor
+
 ## [0.21.0] - 2026-09-27
 
 - Add HTTP/2 keepalive

data/README.md

@@ -37,7 +37,7 @@ run proc { |_env| [200, { "content-type" => "text/plain" }, ["Hello, World!"]] }
 ```
 > bundle exec raptor -w 10 -t 3 hello_world.ru
 [Raptor 72876|Main|Main] Cluster initializing:
-[Raptor 72876|Main|Main] ├─ Version: 0.21.0
+[Raptor 72876|Main|Main] ├─ Version: 0.22.0
 [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
@@ -78,21 +78,11 @@ 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
-values). Run `bundle exec raptor --help` for the full flag list.
+Raptor reads options from a Ruby config file, environment variables, and command line flags, in increasing order of
+precedence. Run `bundle exec raptor --help` for the full flag list.
 
-The config file is a Ruby file that evaluates to a hash of options. By default Raptor loads `raptor.rb` then
-`config/raptor.rb` from the working directory; pass `-c PATH` to point at a specific file. Settings are nested under
-`connection:` (shared across protocols), `http1:` (HTTP/1.1-specific), and `http2:` (HTTP/2-specific).
-
-Use an `ssl://` bind for HTTP/2 negotiated with ALPN, or an `h2c://` bind for cleartext HTTP/2 clients using prior
-knowledge. Each `h2c://` listener accepts HTTP/2 only.
-
-HTTP/2 applications can populate `env["raptor.response_trailers"]` with trailing response headers. Values may be
-strings or arrays of strings.
-
-Idle HTTP/2 connections receive a PING after `keepalive_interval` seconds and close when its acknowledgement does not
-arrive within `keepalive_timeout`. Set `keepalive_interval` to `0` to disable these probes.
+The config file evaluates to a hash of options. By default Raptor loads `raptor.rb` then `config/raptor.rb` from the
+working directory. Pass `-c PATH` to point at a specific file.
 
 ```ruby
 # raptor.rb
@@ -146,35 +136,20 @@ arrive within `keepalive_timeout`. Set `keepalive_interval` to `0` to disable th
 }
 ```
 
-`threads` sets the number of application threads each worker keeps running. By default, Raptor adds temporary threads
-without a fixed limit when queued work is held up by blocking operations. It does not add threads when waiting for the
-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_WORKERS`, `RAPTOR_THREADS`, and `RAPTOR_MAX_THREADS` set the corresponding options without a config file.
 
-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.
+By default each worker adds threads beyond `threads` only while queued requests are waiting on blocking work such as
+database or network calls. It stops adding them once Ruby execution becomes the bottleneck, and the extra threads
+retire when the queue is idle. Set `max_threads` to cap this growth, or set it to `threads` for a fixed pool.
 
 ## Bindings
 
-Raptor accepts multiple `binds:` URIs across three schemes.
+`binds` accepts any combination of these URIs.
 
-- `tcp://host:port` for TCP. Host can be a specific IP, `0.0.0.0` / `[::]`, or `localhost` (expanded to both IPv4 and
-  IPv6 loopback addresses).
-- `unix:///path/to/socket` for a Unix domain socket. Stale sockets left by crashed processes are cleaned up
-  automatically.
-- `ssl://host:port?cert=/path/to.crt&key=/path/to.key` for TLS. HTTP/1.1 and HTTP/2 are negotiated via ALPN.
-
-Multiple binds can be combined freely.
+- `tcp://host:port` for TCP. `localhost` binds both IPv4 and IPv6 loopback addresses.
+- `unix:///path/to/socket` for a Unix domain socket.
+- `ssl://host:port?cert=/path/to.crt&key=/path/to.key` for TLS, negotiating HTTP/1.1 or HTTP/2 via ALPN.
+- `h2c://host:port` for cleartext HTTP/2.
 
 ## Signals
 
@@ -186,22 +161,16 @@ Send to the master process.
 | `TERM` | Graceful shutdown                                           |
 | `HUP`  | Reopen `stdout_file`, `stderr_file`, and `access_log_file`  |
 | `USR1` | Phased restart (rolling worker replacement)                 |
-| `USR2` | Hot restart (re-exec master, inheriting listening sockets)  |
-
-## Restarts
+| `USR2` | Hot restart (restart master, keeping listening sockets)     |
 
-- **Phased restart** (`USR1`) replaces workers one at a time, waiting for each new worker to boot before retiring the
-  previous one. The master process keeps running, so existing workers continue serving until they are individually
-  replaced. Use to pick up code changes that don't affect the master's boot path.
-- **Hot restart** (`USR2`) re-execs the master process with its original command line, inheriting the listening sockets
-  so accepted connections continue to be served across the swap. The successor master re-runs initialization from
-  scratch. Use to pick up changes that affect master-level state (config layout, dependency upgrades, Raptor itself).
+A phased restart replaces workers one at a time while the master keeps running, picking up application code changes.
+A hot restart starts a new master with the original command line and the same listening sockets, picking up changes
+to configuration, dependencies, or Raptor itself.
 
 ## systemd
 
-Raptor implements socket activation (`LISTEN_FDS`) and `sd_notify`, so it integrates cleanly with `Type=notify` units.
-When the socket unit is active, systemd hands the pre-bound listening file descriptors to Raptor, which serves them in
-place of `binds:`. `READY=1`, `STOPPING=1`, and `RELOADING=1` lifecycle messages are emitted automatically.
+Raptor supports socket activation and `sd_notify`, so it works with `Type=notify` units. When the socket unit is
+active, Raptor serves the listening sockets systemd passes in place of `binds`.
 
 ```ini
 # /etc/systemd/system/myapp.socket
@@ -224,8 +193,7 @@ KillMode=mixed
 
 ## Stats
 
-Each worker writes per-worker stats (request count, busy and available threads, backlog, last check-in) to shared
-memory and to a JSON file (default `tmp/raptor.json`; set via `stats_file`).
+Workers publish their stats to `stats_file`, which defaults to `tmp/raptor.json`.
 
 ```
 > bundle exec raptor stats
@@ -235,14 +203,12 @@ 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`.
+Set `control_url` to a Unix socket URL such as `unix:///tmp/raptor-control.sock` to serve the same stats over
+`GET /stats`.
 
 ## (Micro) Benchmarks
 
-Raptor 0.21.0 vs Puma 8.0.2 vs Falcon 0.57.0 across two workload profiles. **IO-bound** is a GET endpoint that
+Raptor 0.22.0 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
@@ -256,22 +222,22 @@ disabled, and both threaded servers allow 999 requests per HTTP/1.1 keep-alive c
 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 ±22.1% for throughput and ±26.6% for p95.
+((max - min) / 2 / median) between runs of a single cell was ±13.2% for throughput and ±25.6% 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       | 2.83k req/s  | 84.00 ms   | 1.51k req/s | 126.00 ms | 87.5% higher  | 33.3% lower  | 12.19k req/s | 14.10 ms   | 76.8% lower     | 495.7% higher |
-| HTTP/1.1              | IO       | Scaling     | 7.12k req/s  | 31.00 ms   | 1.51k req/s | 126.00 ms | 371.2% higher | 75.4% lower  | 12.19k req/s | 14.10 ms   | 41.6% lower     | 119.9% higher |
-| HTTP/1.1              | CPU      | Fixed       | 7.42k req/s  | 37.30 ms   | 8.63k req/s | 21.30 ms  | 14.0% lower   | 75.1% higher | 6.55k req/s  | 28.10 ms   | 13.2% higher    | 32.7% higher  |
-| HTTP/1.1              | CPU      | Scaling     | 6.66k req/s  | 37.70 ms   | 8.63k req/s | 21.30 ms  | 22.8% lower   | 77.0% higher | 6.55k req/s  | 28.10 ms   | 1.6% higher     | 34.2% higher  |
-| HTTP/1.1 (keep-alive) | IO       | Fixed       | 2.43k req/s  | 65.40 ms   | 1.47k req/s | 106.30 ms | 65.2% higher  | 38.5% lower  | 6.22k req/s  | 28.10 ms   | 61.0% lower     | 132.7% higher |
-| HTTP/1.1 (keep-alive) | IO       | Scaling     | 7.77k req/s  | 23.40 ms   | 1.47k req/s | 106.30 ms | 428.4% higher | 78.0% lower  | 6.22k req/s  | 28.10 ms   | 24.9% higher    | 16.7% lower   |
-| HTTP/1.1 (keep-alive) | CPU      | Fixed       | 7.46k req/s  | 26.60 ms   | 8.46k req/s | 22.80 ms  | 11.8% lower   | 16.7% higher | 6.92k req/s  | 33.80 ms   | 7.9% higher     | 21.3% lower   |
-| HTTP/1.1 (keep-alive) | CPU      | Scaling     | 7.53k req/s  | 26.50 ms   | 8.46k req/s | 22.80 ms  | 11.0% lower   | 16.2% higher | 6.92k req/s  | 33.80 ms   | 8.9% higher     | 21.6% lower   |
-| HTTP/2                | IO       | Fixed       | 1.25k req/s  | 138.74 ms  | N/A         | N/A       | -             | -            | 6.17k req/s  | 28.61 ms   | 79.7% lower     | 384.9% higher |
-| HTTP/2                | IO       | Scaling     | 6.20k req/s  | 30.00 ms   | N/A         | N/A       | -             | -            | 6.17k req/s  | 28.61 ms   | 0.5% higher     | 4.9% higher   |
-| HTTP/2                | CPU      | Fixed       | 6.84k req/s  | 32.02 ms   | N/A         | N/A       | -             | -            | 7.90k req/s  | 56.51 ms   | 13.4% lower     | 43.3% lower   |
-| HTTP/2                | CPU      | Scaling     | 7.12k req/s  | 31.07 ms   | N/A         | N/A       | -             | -            | 7.90k req/s  | 56.51 ms   | 9.9% lower      | 45.0% lower   |
+| HTTP/1.1              | IO       | Fixed       | 2.91k req/s  | 82.40 ms   | 1.51k req/s | 125.20 ms | 92.2% higher  | 34.2% lower  | 12.08k req/s | 14.40 ms   | 75.9% lower     | 472.2% higher |
+| HTTP/1.1              | IO       | Scaling     | 7.01k req/s  | 31.70 ms   | 1.51k req/s | 125.20 ms | 362.9% higher | 74.7% lower  | 12.08k req/s | 14.40 ms   | 42.0% lower     | 120.1% higher |
+| HTTP/1.1              | CPU      | Fixed       | 7.24k req/s  | 37.90 ms   | 8.50k req/s | 23.10 ms  | 14.9% lower   | 64.1% higher | 6.44k req/s  | 28.90 ms   | 12.4% higher    | 31.1% higher  |
+| HTTP/1.1              | CPU      | Scaling     | 6.48k req/s  | 39.50 ms   | 8.50k req/s | 23.10 ms  | 23.8% lower   | 71.0% higher | 6.44k req/s  | 28.90 ms   | 0.6% higher     | 36.7% higher  |
+| HTTP/1.1 (keep-alive) | IO       | Fixed       | 2.26k req/s  | 67.20 ms   | 1.47k req/s | 105.60 ms | 53.7% higher  | 36.4% lower  | 6.22k req/s  | 28.20 ms   | 63.7% lower     | 138.3% higher |
+| HTTP/1.1 (keep-alive) | IO       | Scaling     | 8.20k req/s  | 21.80 ms   | 1.47k req/s | 105.60 ms | 458.3% higher | 79.4% lower  | 6.22k req/s  | 28.20 ms   | 32.0% higher    | 22.7% lower   |
+| HTTP/1.1 (keep-alive) | CPU      | Fixed       | 7.21k req/s  | 27.10 ms   | 8.38k req/s | 23.60 ms  | 14.0% lower   | 14.8% higher | 6.87k req/s  | 34.20 ms   | 5.0% higher     | 20.8% lower   |
+| HTTP/1.1 (keep-alive) | CPU      | Scaling     | 7.56k req/s  | 28.10 ms   | 8.38k req/s | 23.60 ms  | 9.8% lower    | 19.1% higher | 6.87k req/s  | 34.20 ms   | 10.1% higher    | 17.8% lower   |
+| HTTP/2                | IO       | Fixed       | 1.64k req/s  | 112.08 ms  | N/A         | N/A       | -             | -            | 6.34k req/s  | 28.16 ms   | 74.2% lower     | 298.1% higher |
+| HTTP/2                | IO       | Scaling     | 6.90k req/s  | 27.33 ms   | N/A         | N/A       | -             | -            | 6.34k req/s  | 28.16 ms   | 8.8% higher     | 2.9% lower    |
+| HTTP/2                | CPU      | Fixed       | 6.90k req/s  | 29.30 ms   | N/A         | N/A       | -             | -            | 6.69k req/s  | 65.77 ms   | 3.2% higher     | 55.4% lower   |
+| HTTP/2                | CPU      | Scaling     | 7.51k req/s  | 26.86 ms   | N/A         | N/A       | -             | -            | 6.69k req/s  | 65.77 ms   | 12.2% higher    | 59.2% lower   |
 
 > ruby 4.0.7 (2026-09-15 revision 229531a6cf) +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/raptor-vs-puma.md

@@ -43,7 +43,7 @@ The rest of this doc explains why the shape looks like that.
 | I/O multiplexing       | `nio4r` reactor for keep-alive idle and slow reads      | `nio4r` reactor for the same, plus a red-black tree for O(log n) timeouts    |
 | 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               |
+| HTTP/2                 | Not implemented                                         | Native C parser + HPACK, reactor-owned frame scheduler                        |
 | 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                                        |
@@ -326,6 +326,8 @@ Puma has a similar shape. It checks buffered back-to-back requests, then eagerly
 
 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.
 
+A `Raptor::DetachedBody` returns the application thread while keeping the response open, chunked on HTTP/1.1 and ended by closing the connection on HTTP/1.0. The reactor owns the response until it closes, buffers later writes within fixed limits, and pauses the connection's next request without occupying an application thread.
+
 ### HTTP/2 request lifecycle
 
 Raptor speaks HTTP/2 on TLS connections where the client negotiates it via ALPN and on `h2c://` listeners for cleartext clients using prior knowledge. The binder sets `alpn_protocols = ["h2", "http/1.1"]` on the SSL context and the ALPN callback picks h2 whenever the client offers it. Puma does not do this. Puma's SSL context does not advertise `h2` in ALPN, so clients transparently fall back to HTTP/1.1.
@@ -337,26 +339,19 @@ 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 HTTP/2 Ractor 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.
+4. Each stream's response frames are queued for the reactor, which owns every socket write after connection setup.
 
 Responses to `HEAD` requests and statuses that prohibit a message body end with the response `HEADERS` frame.
 Early hints and response-finished callbacks follow the same Rack lifecycle as HTTP/1.1.
 Trailing request `HEADERS` complete an open request. Rack has no standard request-trailer key, so Raptor validates them without adding them to the environment.
 
-The `Writer` is worth a paragraph. Naive per-connection writing would need a mutex around every socket write. 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.
-
-So under contention, only one thread does socket I/O at a time (because a socket can only be written to serially anyway), but no thread ever blocks on a lock. The "loser" of the CAS hands its frames off to the "winner" and returns immediately to whatever it was doing next, whether that is starting another stream, waiting for the next work item, or servicing a different connection.
-
-Once the writer thread has claimed a batch of pending frames, it concatenates them into a single buffer and issues one socket write for the whole batch. Frames handed off concurrently can share that write, while sequential body chunks reach the socket as the Rack body yields or writes them.
+The `Writer` hands serialized frames to the reactor, which writes as the socket becomes ready and closes clients that stop reading. Application threads never wait for socket writability, and the connection has a single I/O owner without a per-connection mutex.
 
-Flow control uses similar CAS-protected atoms. The connection-level window and the per-stream windows live in separate `Atom` cells. `acquire` atomically reserves connection capacity and, where per-stream tracking is needed, deducts the same grant from that stream's window. If either window is exhausted, the caller parks on an `AtomicConditionVariable`; a `WINDOW_UPDATE`, stream reset, or connection shutdown wakes it.
+Flow control uses similar CAS-protected atoms. Ordinary Rack bodies wait for connection and stream capacity as they yield. A `Raptor::DetachedBody` instead returns its application thread immediately; the reactor schedules its bounded buffer as capacity becomes available and closes it when the client cancels. This keeps long-lived streams from consuming one application thread each.
 
 Frame processing also has an eager loop. After processing one batch of frames, the h2 handler tries to `read_nonblock` one more time to see if the next batch is already available. Up to eight rounds are consumed inline before handing back to the reactor, and the loop bails out early once the app thread pool has more queued work than worker slots so one busy connection cannot starve the collector. This is the same principle as the HTTP/1.1 eager keep-alive: amortise the reactor round-trip when the client is actively sending, but back off under saturation.
 
-During worker shutdown, Raptor stops accepting connections and sends GOAWAY with the last stream handed to the Rack application. Later streams are refused while the application pool drains. The reactor remains active during that period so in-flight responses can receive flow-control updates and finish before their connections close.
+During worker shutdown, Raptor stops accepting connections and sends GOAWAY with the last stream handed to the Rack application. Later streams are refused while application work and detached bodies drain. The reactor remains active so in-flight responses can receive flow-control updates; detached bodies still open when the drain period expires are cancelled before their connections close.
 
 ### Raptor request flow diagram
 
@@ -408,7 +403,8 @@ flowchart TB
         COL --> CHK
         CHK -->|"no, more bytes needed"| RCT
         CHK -->|"yes, push proc"| ATP
-        ATP -->|"app.call + write"| KA
+        ATP -->|"HTTP/2 response frames"| RCT
+        ATP -->|"HTTP/1.1 response write"| KA
         KA -->|"no, close"| CLS["close socket"]
         KA -->|"yes"| EAG
         EAG -.->|"bytes ready, parse+dispatch on same thread"| ATP
@@ -495,11 +491,11 @@ For external monitoring, `control_url` can expose a read-only `GET /stats` endpo
 
 **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, configurable PING keepalive, and response trailers exposed through `env["raptor.response_trailers"]`. Once a request is complete it takes the same path as HTTP/1.1 and 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.
+**Raptor.** Native C parser plus HPACK, per-stream flow control, reactor-owned response writes, detached long-lived responses, stream multiplexing over a single connection, configurable PING keepalive, and response trailers exposed through `env["raptor.response_trailers"]`. Once a request is complete it takes the same path as HTTP/1.1 and 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, serving direct HTTP/2 clients, or measuring the app server itself, HTTP/2 support is where Raptor and Puma stop being comparable.
 
-At the throughput numbers the benchmark shows, a small set of concurrent connections multiplex many streams, so responses from several app threads share each socket. The writer's CAS-based handoff keeps one active socket writer without parking the other app threads behind a per-connection mutex.
+At the throughput numbers the benchmark shows, a small set of concurrent connections multiplex many streams, so responses from several app threads share each socket. Those threads queue frames while the reactor owns non-blocking writes for the connection.
 
 ### Response writing
 
@@ -610,7 +606,7 @@ Falcon also speaks HTTP/2 natively, so it's the interesting comparison there rat
 
 The benchmark's h2 listener uses TLS, while Raptor's BPF reuseport path only wraps plain TCP listeners. BPF dispatch therefore cannot explain the h2 variance. With 40 physical connections spread across 10 workers, each carrying three streams, placement and per-connection scheduling have coarse granularity; more instrumentation is needed before assigning the variance to a specific mechanism.
 
-Raptor's HTTP/2 CPU-bound throughput remains in the same broad range as its HTTP/1.1 result while multiplexing streams onto shared sockets. The lock-free `Writer` and flow-control atoms are part of how it coordinates that work, but this benchmark does not provide a mutex-based Raptor control case from which to quantify their individual effect.
+Raptor's HTTP/2 CPU-bound throughput remains in the same broad range as its HTTP/1.1 result while multiplexing streams onto shared sockets. The reactor-owned frame scheduler and flow-control atoms are part of how it coordinates that work, but this benchmark does not provide an alternative Raptor control case from which to quantify their individual effect.
 
 ## Part V: What Raptor gives up
 

data/lib/raptor/cluster.rb

@@ -946,6 +946,7 @@ module Raptor
       server_thread.join
       http1.shutdown
       http2.shutdown(reactor)
+      reactor.drain_detached_bodies(@worker_drain_timeout)
       drain_thread_pool(thread_pool)
       reactor.shutdown
       reactor_thread.join

data/lib/raptor/detached_body.rb

@@ -0,0 +1,293 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "atomic-ruby/atom"
+
+module Raptor
+  # A bounded response body that may be written after its application thread
+  # has returned.
+  #
+  class DetachedBody
+    DEFAULT_MAX_BUFFER_SIZE = 64 * 1024
+
+    # Tracks buffered bytes shared by a group of detached bodies.
+    #
+    class Budget
+      # @rbs @max_size: Integer
+      # @rbs @size: Atom
+
+      # @rbs (Integer max_size) -> void
+      def initialize(max_size)
+        @max_size = max_size
+        @size = Atom.new(0)
+      end
+
+      # @rbs (Integer bytes) -> bool
+      def reserve(bytes)
+        reserved = false
+        @size.swap do |size|
+          reserved = size + bytes <= @max_size
+          reserved ? size + bytes : size
+        end
+        reserved
+      end
+
+      # @rbs (Integer bytes) -> void
+      def release(bytes)
+        @size.swap { |size| size - bytes }
+      end
+    end
+
+    # @rbs @max_buffer_size: Integer
+    # @rbs @state: Atom
+    # @rbs @budgets: Array[Budget]
+    # @rbs @wake: ^() -> void
+    # @rbs @dispatch: ^(Proc) -> void
+    # @rbs @finished: ^(Symbol) -> void
+    # @rbs @on_open: (^(DetachedBody) -> void)?
+    # @rbs @on_close: (^(Symbol) -> void)?
+
+    # Creates a detached body with a bounded byte buffer.
+    #
+    # @param max_buffer_size [Integer] maximum body bytes waiting to be written
+    # @return [void]
+    #
+    # @rbs (?max_buffer_size: Integer) -> void
+    def initialize(max_buffer_size: DEFAULT_MAX_BUFFER_SIZE)
+      raise ArgumentError, "max_buffer_size must be positive" unless max_buffer_size.positive?
+
+      @max_buffer_size = max_buffer_size
+      @state = Atom.new({chunks: [], size: 0, closing: false, closed: false, notified: false, trailers: {}})
+      @budgets = []
+      @wake = proc {}
+      @dispatch = proc { |callback| callback.call }
+      @finished = proc {}
+      @on_open = nil
+      @on_close = nil
+    end
+
+    # Registers a callback for when the server accepts the response stream.
+    #
+    # @yieldparam stream [DetachedBody] the opened response stream
+    # @return [DetachedBody]
+    #
+    # @rbs () { (DetachedBody stream) -> void } -> DetachedBody
+    def on_open(&block)
+      @on_open = block
+      self
+    end
+
+    # Registers a callback for when the response stream closes.
+    #
+    # @yieldparam reason [Symbol] why the stream closed
+    # @return [DetachedBody]
+    #
+    # @rbs () { (Symbol reason) -> void } -> DetachedBody
+    def on_close(&block)
+      @on_close = block
+      self
+    end
+
+    # Adds body bytes without waiting for socket or flow-control capacity.
+    #
+    # @param chunk [String] response body bytes
+    # @return [Symbol] `:accepted`, `:full`, or `:closed`
+    #
+    # @rbs (String chunk) -> Symbol
+    def try_write(chunk)
+      raise TypeError, "body must yield String values" unless chunk.is_a?(String)
+
+      chunk = chunk.dup.freeze
+      if chunk.empty?
+        state = @state.value
+        return state[:closed] || state[:closing] ? :closed : :accepted
+      end
+      return :full unless reserve(chunk.bytesize)
+
+      result = :closed
+      wake = false
+      @state.swap do |state|
+        if state[:closed] || state[:closing]
+          result = :closed
+          wake = false
+          state
+        elsif state[:size] + chunk.bytesize > @max_buffer_size
+          result = :full
+          wake = false
+          state
+        else
+          result = :accepted
+          wake = !state[:notified]
+          state.merge(
+            chunks: state[:chunks] + [chunk],
+            size: state[:size] + chunk.bytesize,
+            notified: true
+          )
+        end
+      end
+
+      if result == :accepted
+        @wake.call if wake
+      else
+        release(chunk.bytesize)
+      end
+      result
+    end
+
+    # Finishes the body after all accepted bytes have been written.
+    #
+    # @param trailers [Hash] trailing response headers
+    # @return [void]
+    #
+    # @rbs (?trailers: Hash[String, String | Array[String]]) -> void
+    def close(trailers: {})
+      trailers = trailers.to_h do |name, value|
+        value = value.is_a?(Array) ? value.map { _1.dup.freeze }.freeze : value.dup.freeze
+        [name.dup.freeze, value]
+      end.freeze
+      wake = false
+      @state.swap do |state|
+        if state[:closed] || state[:closing]
+          wake = false
+          next state
+        end
+
+        wake = !state[:notified]
+        state.merge(closing: true, notified: true, trailers: trailers)
+      end
+      @wake.call if wake
+    end
+
+    # Returns whether the stream has closed.
+    #
+    # @return [Boolean]
+    #
+    # @rbs () -> bool
+    def closed?
+      @state.value[:closed]
+    end
+
+    # Connects the body to its reactor-owned response stream.
+    #
+    # @rbs (Array[Budget] budgets, ^() -> void wake, ^(Proc) -> void dispatch, ^(Symbol) -> void finished) -> bool
+    def attach(budgets, wake, dispatch, finished)
+      @wake = wake
+      @dispatch = dispatch
+      @finished = finished
+      size = @state.value[:size]
+      reserved = []
+      budgets.each do |budget|
+        unless budget.reserve(size)
+          reserved.each { |held| held.release(size) }
+          finish(:full)
+          return false
+        end
+        reserved << budget
+      end
+
+      @budgets = budgets
+      true
+    end
+
+    # Notifies the application that its response stream is ready.
+    #
+    # @rbs () -> void
+    def open
+      callback = @on_open
+      @dispatch.call(proc { callback.call(self) }) if callback
+      @wake.call if @state.value[:notified]
+    end
+
+    # Returns the size of the next buffered chunk, 0 when closing, or nil
+    # while waiting for more data.
+    #
+    # @rbs () -> Integer?
+    def next_size
+      state = @state.value
+      state[:chunks].first&.bytesize || (0 if state[:closing])
+    end
+
+    # Removes up to `max_bytes` from the next buffered chunk.
+    #
+    # @rbs (Integer max_bytes) -> String?
+    def shift(max_bytes)
+      chunk = nil
+      @state.swap do |state|
+        chunk = nil
+        first = state[:chunks].first
+        next state unless first
+
+        size = max_bytes < first.bytesize ? max_bytes : first.bytesize
+        chunk = first.byteslice(0, size)
+        chunks = if size == first.bytesize
+          state[:chunks].drop(1)
+        else
+          [first.byteslice(size..-1).freeze] + state[:chunks].drop(1)
+        end
+        state.merge(
+          chunks: chunks,
+          size: state[:size] - size,
+          notified: !chunks.empty? || state[:closing]
+        )
+      end
+      release(chunk.bytesize) if chunk
+      chunk
+    end
+
+    # Returns the response trailers supplied when the body closed.
+    #
+    # @rbs () -> Hash[String, String | Array[String]]
+    def trailers
+      @state.value[:trailers]
+    end
+
+    # Closes the stream and invokes its callback exactly once.
+    #
+    # @rbs (Symbol reason) -> void
+    def finish(reason)
+      callback = false
+      remaining = 0
+      @state.swap do |state|
+        if state[:closed]
+          callback = false
+          remaining = 0
+          state
+        else
+          callback = true
+          remaining = state[:size]
+          state.merge(chunks: [], size: 0, closed: true, notified: false)
+        end
+      end
+      return unless callback
+
+      release(remaining)
+      @dispatch.call(proc do
+        begin
+          @on_close&.call(reason)
+        ensure
+          @finished.call(reason)
+        end
+      end)
+    end
+
+    private
+
+    # @rbs (Integer bytes) -> bool
+    def reserve(bytes)
+      reserved = []
+      @budgets.each do |budget|
+        unless budget.reserve(bytes)
+          reserved.each { |held| held.release(bytes) }
+          return false
+        end
+        reserved << budget
+      end
+      true
+    end
+
+    # @rbs (Integer bytes) -> void
+    def release(bytes)
+      @budgets.each { |budget| budget.release(bytes) }
+    end
+  end
+end