kino 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19a396c4f03ec64ac1f598ca8563c69122a0db0a543372c629a56e3ed88d8d06
-  data.tar.gz: 57c185c402a0f89d0b177c0c017d377abc5fbe8effff999401ae3196426bd6c2
+  metadata.gz: 591ec1716d7d8f23c1483ba2db85f517c42da5de78343c938a27d3e00ca1a66a
+  data.tar.gz: 91a95efe00e8193be3792c4e2b8055f1b45e2b1a4dcb6acaa1a1a4525300f878
 SHA512:
-  metadata.gz: c208de3731186a58be3c4f0ca4f6795fae98405133f0d954ff105a3353892769842cc10bc11fe72dabcaa33c275218e2154eac839cef2fdf729d7959e886429f
-  data.tar.gz: 549bd8c04aa00b3e2c799d717a8d5bbeb702530a81ea688948b04535b848f1eb03c8e0f52fc1dca362189a00b01269c06ff1d5993e6f2de8e6d0f1e322132f4b
+  metadata.gz: ed8d00148990ce34bd73308b376f342b011de37ccf39a078a8676183b0689ad1762af4dc038d6baf2b0501cdb8556a5448e37e0f7ab0c8c755d4e719ceca62c6
+  data.tar.gz: 8305703e2c93bfbe4a00944a4773213f0414459bfdc2e85f963736767a382d85437889d9b216a845df2e314c4d339e0ddd40aebb5b6689b413c16cdf04e4cc87

data/CHANGELOG.md

@@ -1,3 +1,49 @@
+## [0.6.0] - 2026-09-01
+
+- HTTP/2 support. Kino now speaks HTTP/2 natively, on by default:
+  browsers negotiate it over TLS (ALPN), h2-preferring balancers and
+  tools get prior-knowledge h2c on plaintext, and everyone else keeps
+  getting HTTP/1.1 on the same port. `http2 false` restores an
+  HTTP/1-only server. What ships with it:
+  - A spec-complete Rack env on h2: `SERVER_PROTOCOL` is `"HTTP/2"`,
+    `HTTP_HOST`/`SERVER_NAME`/`SERVER_PORT` come from the `:authority`
+    pseudo-header, split cookie headers are rejoined, and uploads
+    stream with the same backpressure as HTTP/1.
+  - Uploads at full speed: body reads now drain every arrived chunk in
+    one native call, so h2's 16 KB data frames don't pay a GVL
+    round-trip each—h2 uploads run at HTTP/1 parity, and chunked
+    HTTP/1 uploads got faster too.
+  - `MAX_CONCURRENT_STREAMS` advertised from worker-slot capacity, so
+    an h2-aware balancer sees the server's real admission and a single
+    connection cannot multiply into hundreds of queued requests.
+  - Graceful connection drains: on shutdown, every connection finishes
+    its in-flight request and then closes (`Connection: close` on
+    HTTP/1, GOAWAY on h2) instead of being cut mid-stream at the
+    deadline.
+  - Interned header values: low-cardinality headers (user-agent,
+    accept-*, sec-ch-*) reuse one frozen string instead of allocating
+    per request—the env-side analogue of HPACK's wire dedup, worth a
+    few percent on header-heavy traffic and 6-8 fewer allocations per
+    request, on HTTP/1 too. Cookies and authorization are deliberately
+    never cached.
+
+  Measured on the reference box: native h2 is +79% over HTTP/1.1
+  cleartext and 2× over TLS on the same server, +50% over
+  nginx-terminated h2 in front of Kino, ~3× falcon on fast handlers.
+- Leaner request hot path: up to 2-4% more throughput on fast handlers
+  with `lanes` (measured on Linux), no change elsewhere.
+- All benchmarks re-measured from scratch on a fresh reference box
+  (c7a.2xlarge, Ruby 4.0.6, Puma 8.0.2): the 2026-06 numbers
+  reproduced within 1-3% at matched configurations, memory to the
+  megabyte. The published tables carry the new run, with two additions
+  and one honest downgrade: new studies for sharded I/O (+1-3% on 8
+  cores, best at `io_threads 8`) and HTTP/2 (above), and a narrower
+  ractor /cpu lead over the cluster (+25%, was +34%) because Puma
+  8.0.2 itself got faster. The bench harness gained the sharded-I/O
+  lanes and the Rails memory comparison, and the methodology notes now
+  record two measurement traps: memory is only comparable after the
+  full endpoint battery, and /io only at equal slot counts.
+
 ## [0.5.0] - 2026-08-29
 
 - Add opt-in `io_shards true`: accepted HTTP connections can run on

data/Cargo.lock

@@ -184,6 +184,12 @@ dependencies = [
  "spin",
 ]
 
+[[package]]
+name = "fnv"
+version = "1.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"
+
 [[package]]
 name = "foldhash"
 version = "0.2.0"
@@ -253,6 +259,25 @@ version = "0.3.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b"
 
+[[package]]
+name = "h2"
+version = "0.4.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ef8e5e5a340588f4452631496976cf8636d4a7ecf600239fdc27615d2530bc16"
+dependencies = [
+ "atomic-waker",
+ "bytes",
+ "fnv",
+ "futures-core",
+ "futures-sink",
+ "http",
+ "indexmap",
+ "slab",
+ "tokio",
+ "tokio-util",
+ "tracing",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.17.1"
@@ -319,6 +344,7 @@ dependencies = [
  "bytes",
  "futures-channel",
  "futures-core",
+ "h2",
  "http",
  "http-body",
  "httparse",
@@ -327,6 +353,7 @@ dependencies = [
  "pin-project-lite",
  "smallvec",
  "tokio",
+ "want",
 ]
 
 [[package]]
@@ -343,6 +370,16 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "indexmap"
+version = "2.14.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "07aa2048142242915a31d35844fb311e0e53fcca590c3a0a40dcf1b841fa09eb"
+dependencies = [
+ "equivalent",
+ "hashbrown",
+]
+
 [[package]]
 name = "itertools"
 version = "0.13.0"
@@ -407,7 +444,7 @@ dependencies = [
 
 [[package]]
 name = "kino"
-version = "0.5.0"
+version = "0.6.0"
 dependencies = [
  "ahash",
  "bytes",
@@ -817,6 +854,12 @@ version = "2.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
 
+[[package]]
+name = "slab"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
+
 [[package]]
 name = "smallvec"
 version = "1.15.2"
@@ -926,6 +969,45 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "tokio-util"
+version = "0.7.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "494815d09bf52b5548659851081238f0ca39ff638363907596da739561c62c52"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "futures-sink",
+ "libc",
+ "pin-project-lite",
+ "tokio",
+]
+
+[[package]]
+name = "tracing"
+version = "0.1.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
+dependencies = [
+ "pin-project-lite",
+ "tracing-core",
+]
+
+[[package]]
+name = "tracing-core"
+version = "0.1.36"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
+dependencies = [
+ "once_cell",
+]
+
+[[package]]
+name = "try-lock"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
+
 [[package]]
 name = "unicode-ident"
 version = "1.0.24"
@@ -944,6 +1026,15 @@ version = "0.9.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
 
+[[package]]
+name = "want"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bfa7760aed19e106de2c7c0b581b509f2f25d3dacaf737cb82ac61bc6d760b0e"
+dependencies = [
+ "try-lock",
+]
+
 [[package]]
 name = "wasi"
 version = "0.11.1+wasi-snapshot-preview1"

data/README.md

@@ -11,11 +11,14 @@ on every core in **one small process**. A **Rust** (tokio + hyper)
 front-end owns the network, parallel **Ractors** run your Rack 3 app,
 and a threaded fallback mode runs everything else, Rails included.
 
-* **Fast.** On a real 8-core server, every Kino mode is **1.5-2×**
-  ahead of a Puma fork cluster on I/O-light endpoints. Ractor mode also
-  wins on pure CPU, **30%+**. [Benchmarks](#benchmarks) below.
-* **A fraction of the memory.** About **~7×** on the simplistic bench 
-  Ractor app, and about **4× less memory** than a Puma cluster serving Rails in fallback threaded mode.
+* **Fast.** On a real 8-core server, every Kino mode is **1.5-1.7×**
+  ahead of a Puma fork cluster on I/O-light endpoints—with native
+  **HTTP/2** adding another **+79%** over HTTP/1.1 on the same server.
+  Ractor mode also wins on pure CPU, **+25%**.
+  [Benchmarks](#benchmarks) below.
+* **A fraction of the memory.** About **~8×** on the simplistic bench
+  Ractor app, and about **4× less memory** than a Puma cluster serving
+  Rails in fallback threaded mode.
 * **Parallel without forking.** Ractor mode runs CPU work **more than
   5× faster** than Kino's own GVL-bound threaded mode, in the same
   small process.
@@ -73,32 +76,32 @@ rather than an app. It is Ractor-shareable, so Kino runs it in `:ractor`
 mode (and `:threaded` for comparison). **A real Rails app is a different
 story:** it is *not* Ractor-shareable, so it runs only in Kino's
 `:threaded` fallback, with its own numbers—see [Rails](#rails) below.
-Ruby 4.0.5 with YJIT, every server at its defaults: Puma forks 8 workers ×
-3 threads, Kino stays in one process (8 workers; 1 thread each in ractor
-modes, 3 in threaded). Numbers are req/s by wrk (8-second windows, 64
-connections, same host). Methodology:
-[doc/benchmarks.md](doc/benchmarks.md).
+Ruby 4.0.6 with YJIT (re-measured 2026-09), every server at its
+defaults: Puma forks 8 workers × 3 threads, Kino stays in one process
+(8 workers; 1 thread each in ractor modes, 3 in threaded). Numbers are
+req/s by wrk (8-second windows, 64 connections, same host).
+Methodology: [doc/benchmarks.md](doc/benchmarks.md).
 
 | endpoint    | Kino :ractor | + lanes | :ractor, `workers 32`² | Kino :threaded | Puma (cluster) |
 |-------------|-------------:|--------:|-----------------------:|---------------:|---------------:|
-| /plaintext  |      229,534 | **250,222** |         182,997 |        216,994 |        118,176 |
-| /10k        |      178,083 | **189,862** |         151,034 |        160,400 |        106,768 |
-| /cpu (fib)  |   **77,999**¹|  70,885 |          66,100 |         13,429 |         58,006 |
-| /io (5 ms)  |        1,552 |   1,551 |       **5,888** |          4,709 |          4,693 |
-| /io_native  |        1,570 |   1,571 |       **6,274** |          4,695 |          4,691 |
+| /plaintext  |      222,980 | **244,652** |         115,553 |        213,104 |        142,094 |
+| /10k        |      175,182 | **188,365** |         103,147 |        132,009 |        125,116 |
+| /cpu (fib)  |   **76,695**¹|  71,830 |          54,062 |         13,463 |         61,329 |
+| /io (5 ms)  |        1,548 |   1,556 |       **5,388** |          4,722 |          4,699 |
+| /io_native  |        1,570 |   1,573 |       **6,207** |          4,695 |          4,693 |
 
 Memory tells two different stories depending on the app, both by **PSS**
 (proportional set size; see note) after sustained load.
 
 **The tiny benchmark app** (Ractor-shareable, so Kino runs it in `:ractor`
-or `:threaded`). Kino is **~7× lighter in :ractor mode, ~10× in :threaded**
-than the Puma cluster — the gap stays large because a trivial app is almost
+or `:threaded`). Kino is **~8× lighter in :ractor mode, ~10× in :threaded**
+than the Puma cluster—the gap stays large because a trivial app is almost
 all private per-worker heap, which copy-on-write can't share:
 
 | tiny app, Kino  | Kino (one process) | Puma cluster (8 workers) | ratio |
 |-----------------|-------------------:|-------------------------:|------:|
-| :ractor (8×1)   |         **148 MB** |                 1,068 MB |  ~7×  |
-| :threaded (8×3) |         **107 MB**³|                 1,068 MB | ~10×  |
+| :ractor (8×1)   |         **135 MB** |                 1,072 MB |  ~8×  |
+| :threaded (8×3) |         **107 MB**³|                 1,072 MB | ~10×  |
 
 **A real Rails app** (not Ractor-shareable—Kino's `:threaded` fallback
 only, [below](#rails)). The gap is **~4×**, smaller because Rails' large
@@ -106,24 +109,25 @@ framework *is* shared copy-on-write across Puma's forks:
 
 | Rails hello-world | Kino :threaded | Puma cluster (8 workers) | ratio |
 |-------------------|---------------:|-------------------------:|------:|
-| **PSS**           |      **92 MB** |               **389 MB** |  ~4×  |
+| **PSS**           |      **95 MB** |               **405 MB** |  ~4×  |
 
 "+ lanes" is the experimental per-worker-queue dispatcher (`lanes true`).
 It posts the fastest plaintext/10k of any configuration here. Details:
 [doc/benchmarks.md](doc/benchmarks.md#lane-dispatch-experimental-lanes-true).
 
 ¹ Stock settings, no tuning. Ractor mode beats the fork cluster on pure
-CPU by +34% (+22% with lanes). Threaded mode shows the GVL ceiling that
-every single-process Ruby server hits. The old CPU-tuning recipe is
-retired: its `threads 1` half **is** the default now, and its
-`tokio_threads 1` half costs −12% on real hardware; see
+CPU by +25% (+17% with lanes; Puma 8.0.2 narrowed this from the +34%
+measured against 7.x). Threaded mode shows the GVL ceiling that every
+single-process Ruby server hits. The old CPU-tuning recipe stays
+retired: its `threads 1` half **is** the default, and its
+`tokio_threads 1` half still costs on real hardware; see
 [doc/benchmarks.md](doc/benchmarks.md#cpu-bound-tuning).
 
 ² Wait-bound throughput is slots ÷ wait, and the default columns bring
 8 single-thread workers against the cluster's 24 threads. Kino slots
 are threads, not processes—when your app waits a lot, raise `workers`.
-The `workers 32` column is that tuning: **+25% over the cluster on /io
-(+34% via `Kino.sleep`)** while still ahead of it on pure CPU, all in
+The `workers 32` column is that tuning: **+15% over the cluster on /io
+(+32% via `Kino.sleep`)** while still ahead of it on pure CPU, all in
 one small process. The cost is the CPU-light rows (32 ractors
 oversubscribe 8 cores); pick the topology your app's wait profile
 needs. See
@@ -131,7 +135,7 @@ needs. See
 
 ³ With `MALLOC_ARENA_MAX=2` (the standard Ruby deployment setting;
 Heroku's default). Without it, 24 threads churning 10 KB responses
-through one glibc heap balloon to ~670 MB—an arena-fragmentation
+through one glibc heap balloon to ~647 MB—an arena-fragmentation
 footgun, not a leak, and ractor mode sidesteps it. See
 [doc/benchmarks.md](doc/benchmarks.md#memory-under-load-and-the-glibc-arena-footgun).
 
@@ -141,36 +145,64 @@ doc):
 
 | endpoint   | Kino :ractor (8×3) | Puma + ractor wrapper | Falcon + ractor wrapper |
 |------------|-------------------:|----------------------:|------------------------:|
-| /plaintext |        **193,826** |                19,480 |                  99,776 |
-| /cpu (fib) |         **68,061** |                17,755 |                  48,721 |
-| /io (5 ms) |          **4,530** |                 1,454 |                   1,549 |
+| /plaintext |        **190,206** |                22,055 |                 107,203 |
+| /cpu (fib) |         **68,230** |                16,528 |                  50,101 |
+| /io (5 ms) |          **4,477** |                 1,482 |                   1,545 |
+
+(The Kino column here runs 8×3—the same 24 slots the wrappers get—so
+the /io row is comparable; the main table's ractor column runs the 8×1
+default.)
+
+### HTTP/2 head-to-head
+
+Kino speaks HTTP/2 natively, so it skips the usual nginx-termination
+hop. Same box as the tables above; all over TLS, h2load, 64 in-flight,
+same app:
+
+| /plaintext                    |       req/s | /upload (64 KB) |
+|-------------------------------|------------:|----------------:|
+| Kino native h2                | **164,044** |      **19,226** |
+| Kino HTTP/1.1 (same boot)     |      80,789 |          17,210 |
+| nginx h2 → Kino HTTP/1.1      |     109,219 |          1,217¹ |
+| Falcon (native h2)            |      55,637 |          18,838 |
+
+Native h2 **doubles** HTTP/1.1 throughput on the same TLS server
+(+79% on cleartext h2c; fewer, larger socket operations, and HPACK
+spares re-sending cookies) and is **+50% over fronting the same Kino
+with nginx**—the proxy hop is pure cost. Uploads, h2's classic weak
+spot, run at HTTP/1 parity. Full matrix, cleartext h2c lanes, and
+methodology: [doc/benchmarks.md](doc/benchmarks.md#http2); reproduce
+with `bench/h2.sh`.
+
+¹ nginx default-config h2 request-body flow control; see the doc.
 
 ### Rails
 
 Rails is not Ractor-shareable today, so Kino serves it in `:threaded`
-fallback — one GVL-bound process. On the same box (`examples/rails-hello`,
+fallback—one GVL-bound process. On the same box (`examples/rails-hello`,
 edge Rails, production, 8×5):
 
 | Rails hello-world            |  req/s | memory (PSS) |
 |------------------------------|-------:|-------------:|
-| Kino :threaded (one process) |  2,637 |    **92 MB** |
-| Puma cluster (8 workers)     | 12,138 |       389 MB |
+| Kino :threaded (one process) |  2,731 |    **95 MB** |
+| Puma cluster (8 workers)     | 15,422 |       405 MB |
 
 The honest trade-off: Puma's fork cluster uses all 8 cores, so it serves
-~4.6× the throughput — at ~4× the memory. Ractor-mode Rails would close
+~5.6× the throughput—at ~4× the memory. Ractor-mode Rails would close
 the throughput gap at one-process memory cost; the upstream blockers are
 tracked in [doc/rails-on-ractors.md](doc/rails-on-ractors.md).
 
-In short: on the tiny synthetic app, ractor mode beats fork-level CPU parallelism (**5.8×** Kino's
-own GVL-bound threaded mode, +34% over the cluster) in one process, at
-about 1/7th of the cluster's memory by PSS (~4× on a real Rails app).
-Every Kino mode is 1.5-2.1× ahead of the cluster on I/O-light endpoints. The macOS numbers
+In short: on the tiny synthetic app, ractor mode beats fork-level CPU parallelism (**5.7×** Kino's
+own GVL-bound threaded mode, +25% over the cluster) in one process, at
+about 1/8th of the cluster's memory by PSS (~4× on a real Rails app).
+Every Kino mode is 1.5-1.7× ahead of the cluster on I/O-light endpoints,
+and native HTTP/2 adds +79% over HTTP/1.1 on top. The macOS numbers
 (secondary; everything there hits the loopback ceiling) and the
 YJIT × Ractors gotcha are in [doc/benchmarks.md](doc/benchmarks.md).
 
 Reproduce: `bench/run.sh [seconds] [concurrency]` for the main table,
 `bench/studies.sh` for the follow-ups (CPU recipe, topology, scaling,
-logging, memory).
+sharded I/O, logging, memory), `bench/h2.sh` for the HTTP/2 matrix.
 
 ## Install
 
@@ -239,6 +271,7 @@ server = Kino::Server.new(app,
   control_bind: "127.0.0.1:9293",   # monitoring: /stats /metrics /ready /live; port 0 reads back via server.control_port
   control_token: ENV["KINO_CONTROL_TOKEN"],  # optional Bearer auth for /stats + /metrics
   tls: { cert: "cert.pem", key: "key.pem" },  # file paths or inline PEM
+  http2: true,                # ALPN h2 on TLS + plaintext h2c; false = HTTP/1 only
 )
 server.start
 server.shutdown               # graceful: drain → deadline → abort stragglers
@@ -265,15 +298,39 @@ server.shutdown               # graceful: drain → deadline → abort straggler
 multi-thread runtime onto current-thread shards: one thread accepts and
 hands each connection to the least-loaded shard, which then owns it for
 its lifetime—no work-stealing, no cross-thread wakeups on the hot path.
-Fast handlers gain double-digit throughput; Ruby-bound endpoints are
-unchanged. Orthogonal to `mode`: it reshapes the Rust side only.
+On the 8-core reference box fast handlers gain +1-3% (best with
+`io_threads 8`); the win grows with scheduler contention, so measure on
+your own core count. Ruby-bound endpoints are unchanged. Orthogonal to
+`mode`: it reshapes the Rust side only.
 
 ```ruby
 # kino.rb
 io_shards true
-io_threads 4  # optional; default: half the available CPUs
+io_threads 8  # optional; default: half the available CPUs
 ```
 
+### HTTP/2
+
+On by default, on both transports, with nothing to configure:
+
+- **TLS binds** advertise `h2` via ALPN, so browsers and h2-capable
+  clients negotiate HTTP/2 and everything else stays on HTTP/1.1.
+- **Plaintext binds** serve prior-knowledge h2c: a client that opens
+  with the HTTP/2 preface (an h2-preferring load balancer, a gRPC-style
+  backend hop, `curl --http2-prior-knowledge`) gets HTTP/2; ordinary
+  clients are HTTP/1.1 exactly as before. Browsers never do h2 on
+  plaintext, so a certificate-less kino behaves identically for them.
+
+The Rack side is spec-complete on h2: `SERVER_PROTOCOL` is `"HTTP/2"`,
+`HTTP_HOST`/`SERVER_NAME`/`SERVER_PORT` come from the `:authority`
+pseudo-header (h2 requests carry no Host header), split cookie headers
+are rejoined with `"; "`, and streamed uploads flow through the same
+backpressured body channel as HTTP/1. Streams multiplex into the same
+worker slots as keep-alive requests—`workers × threads` bounds
+concurrency either way. (`rack.hijack` stays out on h2 as it is on h1;
+the protocol has no 101 upgrade to hijack anyway.) `http2 false` pins
+the server to HTTP/1 and drops `h2` from ALPN.
+
 ## Config file and CLI
 
 Settings can live in a Puma-style Ruby DSL file: `kino.rb` in the
@@ -439,8 +496,8 @@ not `queue_time`.
 
 ## Logging
 
-With one log line per request, `Kino::Logger` sustained **2.4× the
-throughput of a shared `::Logger`** (149k vs 63k req/s on the benchmark
+With one log line per request, `Kino::Logger` sustained **1.7× the
+throughput of a shared `::Logger`** (155k vs 90k req/s on the benchmark
 box). There are two native pieces. Both write through a lock-free
 channel to a Rust flusher thread, so request threads never take a log
 mutex and never make a write syscall:

data/doc/architecture.md

@@ -109,13 +109,63 @@ plain decrement after an `.await` would never run).
 
 ## Graceful shutdown
 
-`stop_accepting` → drain until queue + in-flight reach zero or the
-deadline passes → `close_queue` (idle workers see Disconnected and exit) →
+`stop_accepting` → every live connection switches to graceful shutdown
+(finish the in-flight request, answer with `Connection: close` on
+HTTP/1 or GOAWAY on h2, take nothing new—so drains converge instead
+of chasing chatty keep-alive clients) → drain until queue + in-flight
+reach zero or the deadline passes → `close_queue` (idle workers see
+Disconnected and exit) →
 join workers → past deadline: abort remaining clients (a 500, or a
 connection abort mid-stream), interrupt blocked workers, reap
 stragglers → tear down the tokio runtime. Idempotent;
 a second INT/TERM force-exits.
 
+## HTTP/2
+
+One connection builder serves every protocol: hyper-util's auto builder
+picks h2 by ALPN on TLS connections, by the 24-byte preface sniff on
+plaintext (prior-knowledge h2c), and HTTP/1.x otherwise; `http2 false`
+pins the HTTP/1 codec and skips the sniff entirely. Streams multiplex
+into the same bounded queue as keep-alive requests, so h2 concurrency
+is bounded by workers × threads exactly as h1's is, and the bounded
+body channels give per-stream backpressure for free: while the
+forwarder blocks, hyper withholds WINDOW_UPDATE and the client stalls.
+
+The env bridge fills SERVER_NAME/SERVER_PORT/HTTP_HOST from the request
+URI's `:authority` (h2 requests carry no Host header), through the same
+host LRU the Host-header path uses, keyed by the authority bytes;
+SERVER_PROTOCOL is the interned "HTTP/2". h2 trailer frames are dropped
+(Rack has no trailer surface), and the h2 codec itself rejects
+connection-ish headers before they can reach the env.
+
+The upload path needed one h2-shaped fix: `read_body` drains every
+already-queued chunk in a single native call (one GVL round-trip and
+one Ruby string per 64 KB read), because a body arriving as 16 KB DATA
+frames otherwise paid one crossing per frame—that alone took h2
+uploads from half of h1's throughput to parity. A knob sweep over
+hyper's h2 codec (frame size, adaptive windows, window sizes) moved
+nothing after that, so hyper's defaults stay.
+
+SETTINGS_MAX_CONCURRENT_STREAMS is derived from slot capacity
+(workers × threads, clamped to [8, 1024]) rather than hyper's flat 200:
+a smart balancer sees the server's true admission, and a hostile client
+cannot multiply one connection into hundreds of queued requests—the
+h2 analogue of h1's one-request-per-connection shape. The codec's own
+abuse bounds ship as hyper/h2 defaults and were reviewed: 16 KB header
+lists, 20 pending remote resets then GOAWAY (rapid reset), per-second
+reset-churn and empty-frame budgets.
+
+Low-cardinality header values (UA, accept-*, sec-ch-*, sec-fetch-*)
+are interned in an LRU of frozen strings—the env-side analogue of
+HPACK's wire dedup, and the practical form of it: hyper does not expose
+HPACK table indices, so the cache keys on value bytes and works for
+HTTP/1 too. Cookie and authorization are deliberately excluded
+(per-user cardinality, secret lifetime).
+
+Deferred until benchmarks justify it: slot-aware flow-control window
+grants (a memory/abuse lever, not a throughput one—the knob sweep
+showed windows don't gate upload throughput).
+
 ## Timer waits: `Kino.sleep`
 
 MRI's `sleep` parks the thread on the VM timer, whose wakeups inside
@@ -128,7 +178,8 @@ at the interrupt tick so `Thread#kill` and shutdown stay responsive.
 
 - **tokio + hyper**: the bottleneck is the Ruby dispatch boundary, not raw
   I/O throughput; what matters is HTTP correctness, keep-alive, TLS, and
-  h2-later—hyper's territory. Cross-platform out of the box.
+  h2 (since shipped, via hyper-util's protocol-auto builder)—hyper's
+  territory. Cross-platform out of the box.
 - **monoio**: thread-per-core io_uring looks great in echo-server
   benchmarks, but hyper only works through its poll-io compat layer
   (forfeiting io_uring on the hot path), and the share-nothing advantage