raptor 0.20.2 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7d7d507ad52990de191f14ad645065b414e4d9b5f5d55f610626a0a1b3e6484
-  data.tar.gz: 7d06c53f9fc1e3531cc804dafccf28a715c1cb47924a69a19bd84e449164f935
+  metadata.gz: fc05eb1a4a916e5094c4496f18a3d3b179869a42efc1a7fd42ccda546b46e0bc
+  data.tar.gz: 1b975f682fcbaea183226775277cf441d4996899f4348237b96bf073586b1082
 SHA512:
-  metadata.gz: 4759064e2e344d4d3f4669e62d04056df8d78bbc6b7fe8ba85881e6a8babb136d1f5ca5855606014e06fa43ac18d3d2946121b59bb98be1e8499f8024b4bb3bf
-  data.tar.gz: 439b5f3fce057ce5f2fe8ae8f1d7d47931a688e4ab7ac2f9a59ab9917c4939fb3b5b42e3898d216bb734f0122d4de1e4c9b029f7c71339bffa16e036a4a61838
+  metadata.gz: c39ee7c2d2c4f68b8015a841c3fdadfb26b42f587041d6e85e69fc930abcb9fe65ce4841e3562c31b2ff6a0ac904787ba97ca1a26dafa25ba7a0f71b0069b2a1
+  data.tar.gz: 71604474925af588347c5e82f294eca27b5d51c3dc161ece9bb63508b9ea389196173cf890be8f8ebbd030dea284fc1e0d9f4aac26650f02c05303eb09707c7c

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 ## [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
+- Support HTTP/2 response trailers
+- Gracefully drain HTTP/2 connections
+- Support cleartext HTTP/2 bindings
+- Accept HTTP/2 request trailers
+- Propagate HTTP/2 stream cancellation to response bodies
+- Support Rack response lifecycle over HTTP/2
+- Support Rack streaming bodies over HTTP/2
+- Stream HTTP/2 response bodies incrementally
+- Suppress HTTP/2 response bodies when required
+
 ## [0.20.2] - 2026-09-26
 
 - Close idle connections before reforking workers

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.20.2
+[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,12 +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).
+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
@@ -116,6 +115,8 @@ The config file is a Ruby file that evaluates to a hash of options. By default R
   http2: {
     ractors: nil,
     max_concurrent_streams: 100,
+    keepalive_interval: 10,
+    keepalive_timeout: 5,
   },
   worker_boot_timeout: 60,
   worker_timeout: 60,
@@ -135,35 +136,20 @@ The config file is a Ruby file that evaluates to a hash of options. By default R
 }
 ```
 
-`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.
+`RAPTOR_WORKERS`, `RAPTOR_THREADS`, and `RAPTOR_MAX_THREADS` set the corresponding options without a config file.
 
-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.
+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
 
@@ -175,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
@@ -213,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
@@ -224,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.20.2 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
@@ -245,24 +222,24 @@ 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 ±12.4% for throughput and ±16.5% 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.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]
+| 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;
 > Falcon runs unbounded fibers per worker; 120 concurrent HTTP/1.1 client connections; 40 concurrent HTTP/2 client
 > connections × 3 streams each

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                                        |
@@ -238,7 +238,7 @@ Your Rack app still runs on ordinary threads under one worker GVL, so the app do
 
 **How the Ractor pools actually work.** Raptor uses the `ractor-pool` gem, which is another one of my libraries. Each 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.
 
-Raptor always runs an HTTP/1.1 pool because every binding supports HTTP/1.1. It only starts an HTTP/2 pool when an SSL binding is present, since HTTP/2 is negotiated over TLS. SSL bindings still need both pools because ALPN allows each client to choose HTTP/2 or HTTP/1.1. Both pool sizes scale with headroom via `round(cores / workers)`, clamped to `[1, 3]` for `http1.ractors` and `[1, 2]` for `http2.ractors`. Keeping the pools separate means h1 and h2 parsing never share ractor slots, so a burst of small HTTP/1.1 requests cannot delay HTTP/2 frame handling on the same connection, and vice versa.
+Raptor always runs an HTTP/1.1 pool because TCP, Unix, and SSL bindings support HTTP/1.1. It starts an HTTP/2 pool when an SSL or cleartext HTTP/2 binding is present. SSL bindings need both pools because ALPN allows each client to choose HTTP/2 or HTTP/1.1, while `h2c://` bindings accept only HTTP/2 clients using prior knowledge. Both pool sizes scale with headroom via `round(cores / workers)`, clamped to `[1, 3]` for `http1.ractors` and `[1, 2]` for `http2.ractors`. Keeping the pools separate means h1 and h2 parsing never share ractor slots, so a burst of small HTTP/1.1 requests cannot delay HTTP/2 frame handling on the same connection, and vice versa.
 
 **Why a custom thread pool.** The `AtomicThreadPool` in `atomic-ruby` (another one of my libraries) is backed by an `AtomicQueue`. The queue is a Michael-Scott multi-producer, multi-consumer FIFO: a singly linked list with a dummy sentinel and atomic head and tail pointers. Producers append nodes at the tail; consumers advance the head. Both operations are O(1) and make progress through compare-and-swap rather than a queue-wide mutex. Separate atoms track queue size and active app threads for backpressure.
 
@@ -289,7 +289,7 @@ Three timeout classes are tracked:
 - `chunk_data_timeout` (10s): applied once data has started arriving but the request is incomplete.
 - `persistent_data_timeout` (65s): applied to a keep-alive socket sitting idle between requests.
 
-On timeout, the reactor writes `HTTP/1.1 408 Request Timeout` and closes.
+An incomplete HTTP/1.1 request receives `408 Request Timeout` before the connection closes. Once an HTTP/2 connection has received its preface, its deadline instead sends a PING; an acknowledgement restores the idle deadline, while a missing acknowledgement closes the connection.
 
 ### HTTP/1.1 request lifecycle
 
@@ -326,32 +326,33 @@ 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. 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.
+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.
 
-Once ALPN selects h2, the pool worker that ran the TLS handshake calls `Http2#eager_accept`, which creates the per-connection `Writer` and `FlowControl`, attaches them to the reactor, writes the initial `SETTINGS` frame, and tries a non-blocking read on the socket. If bytes are already there, it parses the first frame batch inline via `Http2.process_frames` and dispatches completed streams to the thread pool without ever touching the ractor pool. If not, it hands the socket to the reactor to watch for the first bytes.
+Once ALPN selects h2 or an `h2c://` listener accepts a connection, the server calls `Http2#eager_accept`, which creates the per-connection `Writer` and `FlowControl`, attaches them to the reactor, writes the initial `SETTINGS` frame, and tries a non-blocking read on the socket. If bytes are already there, it parses the first frame batch inline via `Http2.process_frames` and dispatches completed streams to the thread pool without ever touching the ractor pool. If not, it hands the socket to the reactor to watch for the first bytes.
 
 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.
-
-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:
+4. Each stream's response frames are queued for the reactor, which owns every socket write after connection setup.
 
-- 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.
+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.
 
-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.
+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.
 
-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. For a typical response of a HEADERS frame plus several DATA frames, that is one SSL_write call rather than one per frame.
-
-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 sleeps 1ms and retries until a `WINDOW_UPDATE` makes progress possible.
+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 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
 
 ```mermaid
@@ -402,12 +403,13 @@ 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
         EAG -->|"no bytes, reactor.persist"| RCT
-        RCT -->|"timeout expired"| TO["write 408, close"]
+        RCT -->|"deadline expired"| TO["PING or close"]
 
         STA -.->|"writes slot"| SHM[("mmap shared memory")]
     end
@@ -489,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. 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
 
@@ -598,13 +600,13 @@ On the CPU-bound benchmark profile, each POST request accepts a small JSON body
 
 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.
 
-Where Raptor's HTTP/2 support does matter is the all-Ruby stack: no proxy in front, TLS terminated at the app, and browsers or API clients speaking h2 directly to it. In that setup, Puma negotiates HTTP/1.1 instead, so the app-server connection does not get HTTP/2 multiplexing or HPACK header compression.
+Where Raptor's HTTP/2 support does matter is the all-Ruby stack: clients can speak h2 directly over TLS, or a trusted proxy can use cleartext HTTP/2 to an `h2c://` listener. In that setup, Puma uses HTTP/1.1 instead, so the app-server connection does not get HTTP/2 multiplexing or HPACK header compression.
 
 Falcon also speaks HTTP/2 natively, so it's the interesting comparison there rather than Puma. On the CPU profile, scaling narrows Raptor's throughput gap from 26.9% to 14.2% and improves its p95 advantage from 12.3% to 21.3%. On IO, scaling raises Raptor from 1.14k to 4.46k req/s, but remains 30.3% behind Falcon. The h2 samples vary substantially more than the h1 samples, so these results establish broad shape rather than a precise ranking.
 
 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/ext/raptor_http2/raptor_http2.c

@@ -630,6 +630,7 @@ static int response_headers_iter(VALUE key, VALUE value, VALUE data) {
   const char *lname = RSTRING_PTR(lowered);
   long lname_len = RSTRING_LEN(lowered);
 
+  if (lname_len > 0 && lname[0] == ':') return ST_CONTINUE;
   if (lname_len >= 5 && memcmp(lname, "rack.", 5) == 0) return ST_CONTINUE;
   if (is_hop_by_hop(lname, lname_len)) return ST_CONTINUE;
 
@@ -658,6 +659,16 @@ static VALUE h2_encode_response_headers(VALUE self, VALUE status, VALUE headers)
   return hpack_encode_header_block(pairs);
 }
 
+static VALUE h2_encode_response_trailers(VALUE self, VALUE trailers) {
+  (void)self;
+  Check_Type(trailers, T_HASH);
+
+  VALUE pairs = rb_ary_new();
+  rb_hash_foreach(trailers, response_headers_iter, pairs);
+
+  return hpack_encode_header_block(pairs);
+}
+
 static VALUE h2_parse_frame(VALUE self, VALUE buffer) {
   (void)self;
   Check_Type(buffer, T_STRING);
@@ -825,6 +836,7 @@ RUBY_FUNC_EXPORTED void Init_raptor_http2(void) {
   rb_define_method(cHttp2Parser, "parse_headers", h2_parse_headers, 2);
   rb_define_method(cHttp2Parser, "encode_headers", h2_encode_headers, 1);
   rb_define_method(cHttp2Parser, "encode_response_headers", h2_encode_response_headers, 2);
+  rb_define_method(cHttp2Parser, "encode_response_trailers", h2_encode_response_trailers, 1);
   rb_define_method(cHttp2Parser, "parse_settings", h2_parse_settings, 1);
   rb_define_method(cHttp2Parser, "build_settings", h2_build_settings, 1);
   rb_define_method(cHttp2Parser, "build_frame", h2_build_frame, 4);

data/lib/raptor/binder.rb

@@ -5,9 +5,9 @@ require "socket"
 require "uri"
 
 module Raptor
-  # Binds `tcp://`, `unix://`, and `ssl://` URIs to listening sockets and
-  # holds them for the server. Reconstructs listeners from inherited file
-  # descriptors when provided (systemd socket activation, hot restart).
+  # Binds TCP, Unix, SSL, and cleartext HTTP/2 URIs to listening sockets
+  # and holds them for the server. Reconstructs listeners from inherited
+  # file descriptors when provided (systemd socket activation, hot restart).
   #
   class Binder
     SOCKET_BACKLOG = 1024
@@ -31,11 +31,27 @@ module Raptor
       def close = tcp_server.close
     end
 
+    # Marks a TCPServer as accepting cleartext HTTP/2 connections.
+    #
+    H2cListener = Data.define(:tcp_server) do
+      # @rbs (*untyped) -> TCPSocket
+      def accept_nonblock(...) = tcp_server.accept_nonblock(...)
+
+      # @rbs () -> TCPServer
+      def to_io = tcp_server
+
+      # @rbs () -> Addrinfo
+      def local_address = tcp_server.local_address
+
+      # @rbs () -> void
+      def close = tcp_server.close
+    end
+
     # @rbs @bind_uris: Array[String]
     # @rbs @socket_backlog: Integer
     # @rbs @inherited_fds: Hash[String, Array[Integer]]
-    # @rbs @listeners: Array[TCPServer | UNIXServer | SslListener]
-    # @rbs @uri_listeners: Hash[String, Array[TCPServer | UNIXServer | SslListener]]
+    # @rbs @listeners: Array[TCPServer | UNIXServer | SslListener | H2cListener]
+    # @rbs @uri_listeners: Hash[String, Array[TCPServer | UNIXServer | SslListener | H2cListener]]
 
     # Returns the array of bind URIs.
     #
@@ -49,7 +65,7 @@ module Raptor
 
     # Returns the array of listening sockets.
     #
-    # @return [Array<TCPServer, UNIXServer, SslListener>]
+    # @return [Array<TCPServer, UNIXServer, SslListener, H2cListener>]
     attr_reader :listeners
 
     # Creates a new Binder and binds each URI. `localhost` expands to both
@@ -73,7 +89,8 @@ module Raptor
     end
 
     # Returns the bound addresses as strings: TCP as `host:port`, Unix as
-    # the socket path, SSL as `ssl://host:port`.
+    # the socket path, SSL as `ssl://host:port`, and cleartext HTTP/2 as
+    # `h2c://host:port`.
     #
     # @return [Array<String>]
     #
@@ -86,6 +103,9 @@ module Raptor
         when SslListener
           address = listener.local_address
           "ssl://#{address.ip_address}:#{address.ip_port}"
+        when H2cListener
+          address = listener.local_address
+          "h2c://#{address.ip_address}:#{address.ip_port}"
         else
           address = listener.local_address
           "#{address.ip_address}:#{address.ip_port}"
@@ -100,7 +120,9 @@ module Raptor
     #
     # @rbs () -> Integer
     def server_port
-      tcp_listener = @listeners.find { |listener| listener.is_a?(TCPServer) || listener.is_a?(SslListener) }
+      tcp_listener = @listeners.find do |listener|
+        listener.is_a?(TCPServer) || listener.is_a?(SslListener) || listener.is_a?(H2cListener)
+      end
       return 0 unless tcp_listener
 
       tcp_listener.local_address.ip_port
@@ -112,7 +134,7 @@ module Raptor
     #
     # @rbs () -> bool
     def http2?
-      @listeners.any? { |listener| listener.is_a?(SslListener) }
+      @listeners.any? { |listener| listener.is_a?(SslListener) || listener.is_a?(H2cListener) }
     end
 
     # Closes all listening sockets.
@@ -164,14 +186,16 @@ module Raptor
     # Creates fresh listeners for the given URI.
     #
     # @param uri [URI] the parsed bind URI
-    # @return [Array<TCPServer, UNIXServer, SslListener>]
+    # @return [Array<TCPServer, UNIXServer, SslListener, H2cListener>]
     # @raise [UnknownBindSchemeError] if the URI scheme is not supported
     #
-    # @rbs (URI::Generic uri) -> Array[TCPServer | UNIXServer | SslListener]
+    # @rbs (URI::Generic uri) -> Array[TCPServer | UNIXServer | SslListener | H2cListener]
     def create_listeners(uri)
       case uri.scheme
       when "tcp"
         create_tcp_listeners(uri.host, uri.port)
+      when "h2c"
+        create_tcp_listeners(uri.host, uri.port).map { |listener| H2cListener.new(tcp_server: listener) }
       when "unix"
         create_unix_listeners(uri.path)
       when "ssl"
@@ -186,14 +210,16 @@ module Raptor
     #
     # @param uri [URI] the parsed bind URI the FDs were bound to
     # @param filenos [Array<Integer>] file descriptors to wrap
-    # @return [Array<TCPServer, UNIXServer, SslListener>]
+    # @return [Array<TCPServer, UNIXServer, SslListener, H2cListener>]
     # @raise [UnknownBindSchemeError] if the URI scheme is not supported
     #
-    # @rbs (URI::Generic uri, Array[Integer] filenos) -> Array[TCPServer | UNIXServer | SslListener]
+    # @rbs (URI::Generic uri, Array[Integer] filenos) -> Array[TCPServer | UNIXServer | SslListener | H2cListener]
     def restore_listeners(uri, filenos)
       case uri.scheme
       when "tcp"
         filenos.map { |fileno| TCPServer.for_fd(fileno) }
+      when "h2c"
+        filenos.map { |fileno| H2cListener.new(tcp_server: TCPServer.for_fd(fileno)) }
       when "unix"
         register_unix_socket_cleanup(uri.path)
         filenos.map { |fileno| UNIXServer.for_fd(fileno) }

data/lib/raptor/cli.rb

@@ -56,6 +56,8 @@ module Raptor
       http2: {
         ractors: nil,
         max_concurrent_streams: 100,
+        keepalive_interval: 10,
+        keepalive_timeout: 5,
       },
       worker_boot_timeout: 60,
       worker_timeout: 60,
@@ -350,6 +352,14 @@ module Raptor
           @options[:http2][:max_concurrent_streams] = num
         end
 
+        opts.on("--http2-keepalive-interval SECONDS", Integer, "HTTP/2 idle time before sending a PING, or 0 to disable (default: 10)") do |seconds|
+          @options[:http2][:keepalive_interval] = seconds
+        end
+
+        opts.on("--http2-keepalive-timeout SECONDS", Integer, "HTTP/2 PING acknowledgement timeout in seconds (default: 5)") do |seconds|
+          @options[:http2][:keepalive_timeout] = seconds
+        end
+
         opts.on("--worker-boot-timeout SECONDS", Integer, "Worker boot timeout in seconds (default: 60)") do |timeout|
           @options[:worker_boot_timeout] = timeout
         end

data/lib/raptor/cluster.rb

@@ -876,7 +876,8 @@ module Raptor
         http2_ractor_pool,
         thread_pool,
         connection_options: @connection_options,
-        http1_options: @http1_options
+        http1_options: @http1_options,
+        http2_options: @http2_options
       )
       reactor_thread = reactor.run
 
@@ -943,12 +944,14 @@ module Raptor
       end
 
       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
       http1_ractor_pool.shutdown
       http2_ractor_pool&.shutdown
-      http1.shutdown
-      drain_thread_pool(thread_pool)
       stats_thread.join
 
       run_seed_loop(index) if promote_to_seed