hyperion-rb 2.11.0 → 2.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70fee9940bc27a68927bb0204717bb35da7ea695bc02fe49aaa6c9597c9dd78d
-  data.tar.gz: aaa583caa320c605bb06e2894c3f5452d183b4aa5f1ab27329a2a3a89e1ef900
+  metadata.gz: ae613d6efdf92072a2076a95a3656687e6bc0b5a9302700c56d75bcc0a900b56
+  data.tar.gz: f4f3f26cff7f4ebd08d35757726219ee53e65418bacdd0061d05626d7b354dba
 SHA512:
-  metadata.gz: 3c28ad4d534e00eb3b687903da63ae7c04c918d27081d9ac73e04a67d521e2abd832f100b20d87b3411fa9c7be5abdcda2f8638ca8c139ef913fbd0f1ad1930a
-  data.tar.gz: debe988e4dc461376df38bdd84833a2f608dcfb8bf2dc420fc086e89970607b1c36d632dc1057b4eb9983f83918fdc60d93ee87a10098f6f775ccd4207611fb1
+  metadata.gz: 5e0cbc3aa81bbe246dbf670642cae5fd2e1f0275f36030729bb68fe23b00dd54bbc51fb5f2e62c0a306fd825f73ab35e86cc49dd3bb6a27f38269885067de62c
+  data.tar.gz: f749e0b6e05c52695bc4698d847b92e88c10a17dc21a2d6d93deb9c9a013c5c712f778dfa13aa6dab6f5dd0ebf398c69a5eb56255031aaf9539ca561a38bca6d

data/CHANGELOG.md

@@ -1,5 +1,571 @@
 # Changelog
 
+## 2.12.0 — 2026-05-01
+
+### 2.12-F — gRPC support on h2
+
+**Background.** Hyperion has shipped a working HTTP/2 stack since 1.6
+(per-stream fiber multiplexing, WINDOW_UPDATE-aware flow control, ALPN
+auto-negotiation, native HPACK via the Rust v3/CGlue codec since 2.5-B).
+What was missing for gRPC over Hyperion was three small things:
+
+  1. **Trailing headers.** gRPC carries its protocol-level status
+     (`grpc-status: 0` / `grpc-message: OK`) as **trailers** — a
+     final HEADERS frame sent AFTER the body's DATA frames, with
+     END_STREAM=1. Hyperion's pre-2.12-F dispatch path always
+     folded END_STREAM onto the LAST DATA frame, so there was no
+     hook for emitting trailers.
+  2. **Binary-clean request body.** The h2 RequestStream initialised
+     `@request_body = +''` (UTF-8). Valid gRPC request bodies
+     (`[1-byte compressed flag][4-byte length-prefix][protobuf bytes]`)
+     contain non-UTF-8 byte sequences, which broke `.bytesize` /
+     `valid_encoding?` checks and corrupted bodies that downstream
+     code interpolated into a UTF-8 String.
+  3. **TE: trailers preservation.** Hyperion's RFC 7540 §8.1.2.2
+     validator already accepted `te: trailers` (any other TE value
+     is rejected as a protocol error per the spec). What was needed
+     was a non-regression spec confirming the header makes it to
+     `env['HTTP_TE']` for the Rack app.
+
+**What's new.** The h2 dispatch path (`Http2Handler#dispatch_stream`)
+now checks if the Rack response body responds to `:trailers` AFTER
+iterating the body. When it does, the wire shape becomes:
+
+```
+HEADERS (no END_STREAM)
+DATA (no END_STREAM on last DATA)
+HEADERS (END_STREAM=1)  ← trailers, e.g. grpc-status: 0
+```
+
+The trailer Hash is filtered defensively before encoding: pseudo-headers
+(`:status` / `:method` / etc.) and connection-specific names
+(`connection`, `transfer-encoding`, …) are stripped — same allow-list
+the regular response-header path uses. A misbehaving app that returns
+non-Hash trailers (or whose `body.trailers` raises) gets a warn log and
+falls back to the no-trailers path; the connection never crashes.
+
+`Http2Handler::RequestStream#@request_body` is now an
+`Encoding::ASCII_8BIT` String, so binary bytes survive verbatim through
+`<<` accumulation and `env['rack.input'].read`.
+
+**What's NOT changed.** The existing wire shape for non-gRPC h2 traffic
+is identical to 2.11.x. A Rack body that doesn't define `:trailers` (or
+where `body.trailers` is `nil` / empty) takes the pre-2.12-F path:
+HEADERS → DATA-with-END_STREAM-on-last. Verified by three non-regression
+specs in `spec/hyperion/grpc_trailers_spec.rb`.
+
+The HTTP/1.1 dispatch path is untouched. gRPC is HTTP/2-only by spec
+(the `Trailer:` mechanism on h1 has interop gaps with Go / Java clients;
+gRPC mandates h2 since v1.0). Hyperion follows suit.
+
+**What's NOT in scope for this stream.** gRPC server streaming /
+client streaming / bidi streaming require Rack 3 streaming bodies AND
+a way for the Rack app to read incoming DATA frames after sending
+response HEADERS. That's a separate stream-control problem (`rack.hijack`
+on h2 needs RFC 8441 Extended CONNECT, same blocker as WebSocket-over-h2).
+2.12-F lands the **unary** (request-response) and **server-side trailers**
+half — which covers ~80% of production gRPC traffic shapes by message
+volume per the public Google / Netflix talks. Streaming is a 2.13
+candidate.
+
+**Opt-in via Rack 3 `body.trailers`.** Apps don't need to know about
+Hyperion. Any Rack 3 body — hand-rolled, `grpc-server-rack`, a future
+`Rack::Trailers` middleware — that exposes `body.trailers` returning
+a Hash gets the trailing HEADERS frame on the wire. Bodies that don't
+expose it (the overwhelming majority of HTTP/2 traffic — Rails,
+Sinatra, asset servers, JSON APIs) take the legacy path with no
+behaviour change.
+
+**Spec coverage.** `spec/hyperion/grpc_trailers_spec.rb` — 11 specs
+covering:
+
+  - End-to-end TLS+h2 client driving a real Hyperion server through
+    `Protocol::HTTP2::Client`, asserting the trailing HEADERS frame
+    decodes to the expected `grpc-status` / `grpc-message` map.
+  - `te: trailers` request header reaches `env['HTTP_TE']`.
+  - Binary request body bytes (`\xFF\x00\x01\x02\xC3\x28\x80`)
+    round-trip verbatim through `env['rack.input'].read`.
+  - Non-regression: bodies without `:trailers` keep the
+    DATA-with-END_STREAM-on-last shape (no extra HEADERS frame).
+  - Defensive: `body.trailers = nil` and `body.trailers = {}` both
+    take the no-trailers path.
+  - Unit tests for `collect_response_trailers` covering nil /
+    raises / Hash-coercible / non-responding bodies.
+
+`spec/hyperion/grpc_smoke_spec.rb` — opt-in (`RUN_GRPC_SMOKE=1`)
+end-to-end smoke against the real `grpc` Ruby gem. Skipped by default
+because the gem pulls protobuf C bindings (~50 MB build); the unit
+specs above are the durable coverage.
+
+**Performance.** Zero hot-path cost when no app uses trailers — the
+`body.respond_to?(:trailers)` probe is one method dispatch, the
+trailers-Hash branch only runs when the probe returns truthy. The
+trailers-emitting path costs one extra encoder-mutex acquisition + one
+extra HEADERS frame per response — negligible against the existing
+HEADERS+DATA sequence. No bench numbers here because gRPC throughput
+on Hyperion is dominated by the application's protobuf marshalling,
+not the framing layer; a meaningful gRPC bench is a 2.13 follow-up
+once we have a streaming story to compare against Falcon's
+`async-grpc`.
+
+### 2.12-E — SO_REUSEPORT load balancing audit
+
+**Background.** Hyperion's cluster mode (`-w N`) uses two listener-FD
+models depending on platform:
+
+  - **Linux:** `SO_REUSEPORT`. Every worker calls `bind()` on the same
+    port; the kernel does in-kernel load balancing across connected
+    workers based on a 4-tuple hash. Documented as the
+    production-recommended setup since rc15.
+  - **Darwin / BSD:** master-bind + worker-fd-share. The master process
+    binds the listener and passes the fd to workers via `fork()`;
+    workers race to `accept()`. Darwin's `SO_REUSEPORT` doesn't
+    load-balance — it just lets multiple sockets bind without
+    `EADDRINUSE` — so we deliberately do NOT use it on Darwin.
+
+The Linux path was built on the assumption that the kernel hash
+distributes uniformly across workers under sustained load. We had no
+**measurement** of that — only theory. 2.12-E fixes the gap.
+
+**New per-worker request counter.** `Hyperion::Metrics#tick_worker_request`
+ticks the labeled counter family
+`hyperion_requests_dispatch_total{worker_id="<pid>"}` once per
+dispatched request, regardless of which dispatch shape served it:
+
+  - Rack-via-`Connection#serve` (the threadpool / inline / async-io
+    paths).
+  - HTTP/2 stream dispatch in `Http2Handler`.
+  - The 2.12-C `accept4` C accept loop.
+  - The 2.12-D io_uring accept loop.
+
+The C-loop variants tick a process-global atomic counter
+(`Hyperion::Http::PageCache.c_loop_requests_total`) that the
+`PrometheusExporter.render_full` pass folds into the
+per-worker series at scrape time — so operators see one consistent
+per-PID count even on the C-only fast path that bypasses
+`Connection#serve`. Hot-path cost on the C loops is one
+`__atomic_add_fetch` (relaxed) — negligible against the 134k r/s
+2.12-D bench peak.
+
+The label value is `Process.pid.to_s` — matches the 2.4-C
+`hyperion_io_uring_workers_active` and
+`hyperion_per_conn_rejections_total` labeling convention; lets
+operators correlate cluster-mode rows with `ps`/`/proc` data without
+a separate worker_id ↔ pid mapping table.
+
+**New bench harness.** `bench/cluster_distribution.sh` boots
+Hyperion `-w 4 -t 1 -p 9292 bench/hello_static.ru` (4 workers,
+sharp imbalance signal), runs `wrk -t8 -c200 -d30s` against `/`,
+then scrapes `/-/metrics` repeatedly until all 4 workers have
+responded. Reports the per-worker request distribution
+(pid + count + share-%), mean / stddev / max-vs-min ratio, and a
+verdict:
+
+  - `balanced` (max/min ≤ 1.10): kernel hash is doing its job.
+  - `mild` (1.10 < max/min ≤ 1.50): note here, no fix.
+  - `severe` (max/min > 1.50): file follow-up; do not ship as-is.
+
+Three runs back-to-back so noise is visible; aggregate verdict is
+the worst per-run verdict (one severe run is enough to fail the
+audit).
+
+**Bench result.** See `docs/BENCH_HYPERION_2_11.md`'s "Cluster
+distribution audit" section. Headline number lands in the
+`[bench][2.12.0] 2.12-E — bench result: …` follow-up commit.
+
+**Darwin caveat.** The Darwin master-bind/worker-fd-share path is
+documented as known-imbalanced and is NOT covered by this audit
+(no kernel SO_REUSEPORT distributor to measure). The metric
+infrastructure is platform-independent; any operator running on
+Darwin can read their own per-worker imbalance via `/-/metrics` and
+the same `hyperion_requests_dispatch_total{worker_id}` series.
+
+**Spec coverage.** `spec/hyperion/metrics_per_worker_request_count_spec.rb`
+asserts:
+
+  - `Metrics#tick_worker_request` registers the labeled family with
+    `worker_id` label and increments the right series.
+  - `Connection#serve` ticks the counter once per request from any
+    dispatch shape (regular Rack, direct dispatch, StaticEntry fast
+    path).
+  - `PrometheusExporter.render_full` emits the merged
+    `hyperion_requests_dispatch_total{worker_id="<pid>"}` line.
+  - The C accept4 loop's atomic counter ticks per request and is
+    reset on `run_static_accept_loop` entry. (Gated on the C ext
+    being available; same gating pattern 2.12-D specs use.)
+
+### 2.12-D — io_uring accept loop (Linux 5.x)
+
+The 2.12-C `accept4` loop closed most of the gap to Agoo on the
+`handle_static` hello row (5,502 → 15,685 r/s, 1.21× from parity).
+Looking at the remaining cost on Linux: the worker thread does
+**three** syscalls per request — `accept4` + `recv` + `write`. On a
+host that delivers ~150 ns of syscall entry/exit overhead each, that's
+~450 ns of pure kernel-mode bookkeeping per request, before any I/O
+actually happens.
+
+io_uring lets us collapse the train. We submit ACCEPT/RECV/WRITE/CLOSE
+SQEs to a per-worker ring; the worker thread does **one**
+`io_uring_enter` per cycle and reaps N completions in a single
+syscall round-trip. Steady-state cost goes from N×3 syscalls to
+~N÷K × 1 syscall (where K is the burst-batch size the kernel
+naturally delivers).
+
+**New C exports** on `Hyperion::Http::PageCache`:
+
+  - `run_static_io_uring_loop(listen_fd) -> Integer | :crashed | :unavailable`
+    drives the io_uring accept-and-serve loop. Same wire contract as
+    `run_static_accept_loop`: only `handle_static` routes, plain TCP,
+    GET/HEAD without a body, HTTP/1.1 only. Returns `:unavailable` if
+    the C ext was built without `liburing` OR the runtime
+    `io_uring_queue_init` probe failed (seccomp / locked-down
+    container / kernel < 5.5). The Ruby caller treats `:unavailable`
+    as "fall through to the 2.12-C `accept4` path" — operator gets a
+    one-line warn-level log, no surprise downtime.
+  - `io_uring_loop_compiled?` — boolean, true when the C ext was
+    built with `HAVE_LIBURING`. Cheap eligibility check that lets
+    `ConnectionLoop#io_uring_eligible?` skip the env-var read on
+    builds where the path can't engage anyway.
+
+**Build.** `extconf.rb` probes for `liburing` in two passes:
+
+  1. `pkg-config --exists liburing` — picks up Debian/Ubuntu's
+     pkg-config metadata and adds the right `-L`/`-l` flags.
+  2. `have_header('liburing.h')` + `have_library('uring', ...)` —
+     covers the no-pkg-config path.
+
+On success, `-DHAVE_LIBURING` lands and the io_uring loop compiles.
+On failure, the same `io_uring_loop.c` translation unit compiles to
+a thin stub that returns `:unavailable`. Soft-optional dependency:
+hosts without liburing-dev still build cleanly and ship the 2.12-C
+behaviour.
+
+**Wiring.** `Hyperion::Server::ConnectionLoop.io_uring_eligible?`
+returns true when ALL hold:
+
+  1. The C accept-loop path is available
+     (`ConnectionLoop.available?`).
+  2. The C ext was compiled with `HAVE_LIBURING`.
+  3. `HYPERION_IO_URING_ACCEPT=1` is set (default OFF in 2.12 — the
+     soak window before flipping the default to ON is 2.13 or later).
+
+When eligible, `Server#run_c_accept_loop` calls
+`run_static_io_uring_loop` first; on `:unavailable` (runtime probe
+fail) it falls through to `run_static_accept_loop`. A new
+`:c_accept_loop_io_uring_h1` `DispatchMode` symbol counts engagements
+under `requests_dispatch_c_accept_loop_io_uring_h1`.
+
+**Lifecycle hooks.** Same contract as 2.12-C: per-request
+`Runtime#fire_request_start` / `#fire_request_end` fire on every
+request the io_uring loop served. `env=nil`, minimal `Hyperion::Request`
+passed. The C-side `lifecycle_active?` flag gates the GVL re-acquisition
+(`rb_thread_call_with_gvl`); the no-hook hot path stays GVL-free for
+the whole `submit_and_wait` cycle.
+
+**Handoff.** Same set of "send to Ruby" triggers as 2.12-C: HTTP/1.0,
+`Content-Length` / `Transfer-Encoding`, `Upgrade`, `HTTP2-Settings`,
+`Connection: upgrade`, malformed framing, header section >64 KiB,
+unknown method, path miss. Ruby resumes ownership via the same
+`dispatch_handed_off` path the 2.12-C loop already uses.
+
+**TCP_NODELAY.** Applied per-accept via the shared
+`pc_internal_apply_tcp_nodelay` wrapper — preserves the 2.10-G hunk.
+
+**Tests.** `spec/hyperion/io_uring_loop_spec.rb` covers the Ruby
+surface (always exposed), the stub `:unavailable` return on
+non-Linux / no-liburing builds, eligibility-gate semantics
+(`HYPERION_IO_URING_ACCEPT` env var honoured, compile-time flag
+honoured), and — gated on `HAVE_LIBURING` — a smoke test (5 GETs,
+assert served count grows), lifecycle-hook firing parity with the
+2.12-C contract, and Server-level engagement (the
+`:c_accept_loop_io_uring_h1` dispatch mode is recorded).
+
+Total: 1065 specs / 0 failures / 15 pending on macOS — +10 specs and
++4 pending over the 2.12-C macOS baseline (1055 / 0 / 11). Linux:
+1065 / 1 / 14 (the one failure is a pre-existing flake on the 2.12-C
+smoke spec — reproduces on unmodified master at e526ef3 on the bench
+host, NOT a 2.12-D regression).
+
+**Bench (3 trials, median, openclaw-vm 16 vCPU Ubuntu 24.04 Linux 6.8.0,
+liburing 2.5, wrk -t4 -c100 -d20s, `bench/hello_static.ru`):**
+
+| Variant | r/s (median) | p99 |
+|---|---:|---:|
+| 2.12-C `handle_static` Hyperion (C accept loop, accept4) | 15,532 | 101 µs |
+| **2.12-D `handle_static` Hyperion (C accept loop, io_uring)** | **134,084** | **0.99 ms** |
+| Agoo 2.15.14 (reference, prior bench) | 19,024 | 10.47 ms |
+
+`handle_static` hello: **8.6× over the 2.12-C accept4 baseline**
+(15,532 → 134,084 r/s) and **7.0× over Agoo** (134,084 vs. 19,024).
+The accept4 path is unchanged and within bench noise of the prior
+2.12-C 15,685 r/s baseline (15,532 r/s today is -1%, well inside the
+±5% target).
+
+The p99 climb (101 µs accept4 → 0.99 ms io_uring) is the cost of
+batching: with one `io_uring_enter` reaping K completions, the
+last-enqueued request waits for the kernel to produce all K CQEs
+before our worker drains. At 134k r/s the per-request median is
+~7.4 µs; the p99 of ~990 µs is roughly the steady-state batch-tail
+(~130 requests' worth of completions). For the smoke-class workload
+this is a clear win — sub-millisecond p99 is below most real-world
+network jitter floors and well below Agoo's 10.47 ms p99.
+
+The Rack-style fallback (`bench/hello.ru`, no `handle_static`) is
+unaffected: io_uring engagement requires `Server.handle_static`
+registration, the regular dynamic-Rack path is unchanged.
+
+**Production rollout.** Default OFF for 2.12.0. Operators opt in
+with `HYPERION_IO_URING_ACCEPT=1` per worker. Soak window for
+flipping the default to ON is 2.13 — kernel io_uring has known
+sharp edges around fork-shared rings and `seccomp` policies that
+this default-off posture lets us discover under operator A/B
+before forcing the path on every install.
+
+### 2.12-C — Connection lifecycle in C
+
+The 2.12-B re-bench made it clear that Hyperion's `handle_static`
+hot path was already doing the **response side** in C
+(`PageCache.serve_request`, 2.10-F), but the **connection
+lifecycle around it** — accept loop, route lookup, per-`Connection`
+ivar init — was still in Ruby. The 2.10-D / 2.10-F bench analysis
+flagged that as the next dominant cost: `accept4` + `clone3`
+(worker thread wakeup) + `futex` (GVL handoff) + Ruby ivar init
+on every connection.
+
+This stream pushes the entire accept→read→route-lookup→write
+loop into C for `handle_static`-routed paths.
+
+**New C exports** on `Hyperion::Http::PageCache`:
+
+  - `run_static_accept_loop(listen_fd) -> Integer | :crashed`
+    drives the accept-and-serve loop. Releases the GVL during
+    `accept(2)`, `recv(2)`, and `write(2)`; re-acquires only for
+    the registered lifecycle / handoff Ruby callbacks. Returns
+    the count of requests served when the listener closes
+    cleanly, or `:crashed` if an unrecoverable accept error
+    happened (Ruby falls back to its own accept loop on this
+    sentinel).
+  - `set_lifecycle_callback(callable)` and
+    `set_lifecycle_active(bool)` — register / gate the per-request
+    lifecycle hook. Decoupled so flipping the gate at runtime
+    doesn't re-allocate the callback. The hot path checks a
+    single `int` flag; the no-hook path stays one syscall (recv
+    or write) per request.
+  - `set_handoff_callback(callable)` — register the callback the
+    C loop invokes when a connection's first request can't be
+    served from the static cache (path miss, malformed request,
+    body present, h2 upgrade requested, HTTP/1.0). Receives
+    `(fd_int, partial_buffer_or_nil)`; Ruby owns the fd from
+    that point on and resumes ownership via the regular
+    `Connection` path.
+  - `stop_accept_loop` and `lifecycle_active?` — operator /
+    spec helpers.
+  - `handoff_to_ruby(client_fd, partial_buffer, partial_len)` —
+    echo helper exposing the 2.12-C contract for spec-time
+    introspection (the actual handoff happens inside
+    `run_static_accept_loop` via the registered callback).
+
+**Wiring.** `Hyperion::Server::ConnectionLoop` (new module) holds
+the engagement check + callback factories. `Server#start_raw_loop`
+engages the C loop when:
+
+  1. The listener is plain TCP (no TLS, no h2 ALPN dance).
+  2. The route table has at least one
+     `RouteTable::StaticEntry` registration.
+  3. The route table has NO non-StaticEntry registrations
+     (any dynamic handler disables the C path; the C loop
+     only knows how to write prebuilt responses).
+  4. The C ext is available (the `Hyperion::Http::PageCache`
+     module responds to `:run_static_accept_loop`) and the
+     `HYPERION_C_ACCEPT_LOOP=0` escape hatch is not set.
+
+A new `:c_accept_loop_h1` `DispatchMode` symbol ships under
+`requests_dispatch_c_accept_loop_h1` (one bump per worker boot
+that engages the path) plus `c_accept_loop_requests` (count of
+requests the C loop served on this worker, bumped at loop exit).
+
+**Lifecycle hooks.** The 2.10-D contract holds: per-request
+`Runtime#fire_request_start` / `#fire_request_end` fire on every
+request the C loop served. `env=nil`, `path=` the matched path
+string — same surface as the Ruby direct-dispatch path. The
+Ruby-side bridge in `ConnectionLoop.build_lifecycle_callback`
+builds a minimal `Hyperion::Request` for the hooks to consume.
+The C-side `lifecycle_active?` flag gates the `rb_funcall`;
+when no hooks are registered, the no-hook hot path is one
+syscall (recv) + one syscall (write) per request, with **zero
+Ruby method invocations**.
+
+**Handoff.** When the C loop sees a request it can't serve from
+the static cache (POST, path miss, malformed framing,
+`Content-Length`, `Transfer-Encoding`, `Upgrade`,
+`HTTP2-Settings`, `Connection: upgrade`, HTTP/1.0), it invokes
+the handoff callback with `(fd_int, partial_buffer_str)` and
+continues to the next accept. Ruby resumes ownership of the fd
+via `dispatch_handed_off`, which wraps the fd in `Socket.for_fd`,
+applies the read timeout (matches the regular Ruby accept
+path), pre-loads the partial buffer onto the Connection's
+`@inbuf` ivar so the parser sees the bytes the C loop already
+consumed, and dispatches through the existing thread-pool /
+inline path.
+
+**Tests.** `spec/hyperion/connection_loop_spec.rb` covers
+smoke (registered route → C loop served-count grows), mixed
+registered + unregistered (C loop hands off to the Ruby callback
+spy with the partial buffer + fd), body-present requests
+(`POST /hello` hands off), lifecycle hooks
+(`set_lifecycle_active(true)` fires the registered callback
+once per served request; `false` is silent — no callback
+invocation, even with one set), GVL release (a slow C-loop
+parked on `accept(2)` doesn't block another Ruby thread doing
+arithmetic), keep-alive on a single connection (two pipelined
+requests on the same socket → two responses), Server-level
+engagement (only-static-routes engages the C loop;
+mixed-with-dynamic-handlers refuses to engage and falls back
+to the regular Ruby loop).
+
+Total: 1112 specs / 0 failures / 11 pending — +10 specs over
+the 2.12-B baseline (1102 / 0 / 11).
+
+**Bench (3 trials, median, openclaw-vm 16 vCPU Ubuntu 24.04 Linux 6.8.0,
+wrk -t4 -c100 -d20s, `bench/hello_static.ru`):**
+
+| Variant | r/s (median) | p99 |
+|---|---:|---:|
+| 2.12-B `handle_static` Hyperion (Ruby accept loop + C `serve_request`) | 5,502 | 1.59 ms |
+| **2.12-C `handle_static` Hyperion (C accept loop)** | **15,685** | **107 µs** |
+| Agoo 2.15.14 (reference) | 19,024 | 10.47 ms |
+
+`handle_static` hello: **2.85× over the 2.12-B baseline** (5,502 → 15,685).
+Gap to Agoo's 19,024 r/s closed from **3.46×** to **1.21×** — the
+2.12-C path is now within striking distance of Agoo on this row.
+Tail latency (p99) is now **107 µs**, an **15× improvement** over
+the 2.12-B 1.59 ms p99 and **97× better** than Agoo's 10.47 ms p99.
+
+The Rack-style fallback (`bench/hello.ru`, no `handle_static`) was
+re-checked: 4,648 r/s median (vs 4,477 r/s 2.12-B baseline — within
+bench noise, no regression). The C-loop path is only engaged when
+the operator opts in via `Server.handle_static` registration on
+every route; the regular dynamic-Rack path is unchanged.
+
+### 2.12-B — Fresh 4-way re-bench (post-2.10/2.11 wins)
+
+The 4-way head-to-head in `docs/BENCH_HYPERION_2_0.md`
+§ "4-way head-to-head (2.10-B baseline, 2026-05-01)" was
+captured before the 2.10-C / 2.10-D / 2.10-E / 2.10-F /
+2.10-G / 2.11-A / 2.11-B wins landed. Every Hyperion column
+in that doc was therefore stale; the Puma / Falcon / Agoo
+columns were unchanged (no version bumps on the bench host).
+This stream re-runs the entire 6-row matrix on the 2.11.0
+codebase — same host (`openclaw-vm`, 16 vCPU, Ubuntu 24.04,
+Linux 6.8.0), same tools (`wrk` + `perfer`), 3 trials per
+row, median reported — and writes the results to a new
+`docs/BENCH_HYPERION_2_11.md` (pointed at from the README's
+Benchmarks section; the 2.0 doc is now marked "historical
+baseline (pre-2.10/2.11 wins)").
+
+The harness at `bench/4way_compare.sh` gains a sixth server
+label, `hyperion_handle_static`, which boots Hyperion against
+an alternate rackup whose hot path is the
+`Hyperion::Server.handle_static` direct route + 2.10-F C-ext
+fast-path response writer + 2.10-C PageCache fold. This
+exposes two Hyperion columns on the rows where it applies
+(hello + small static): "Rack-style" (the legacy generic-Rack
+path most apps run unchanged) and "`handle_static`" (the peak
+path operators can opt into by registering one pre-built
+route at boot). New rackup `bench/static_handle_static.ru`
+preloads the 1 KB static asset bytes at boot and serves them
+through the same direct-route fast path; the existing
+`bench/hello_static.ru` (added in 2.10-F) plays the same role
+for the hello row.
+
+**Headline shifts (medians, vs the 2.10-B baseline at the
+same workload):**
+
+| # | Workload | 2.10-B Hyperion | 2.11.0 Rack-style | 2.11.0 `handle_static` | Gap-vs-leader shift |
+|---:|---|---:|---:|---:|---|
+| 1 | hello | 4,587 | 4,477 (-2.4%, noise) | **5,502** (+19.9%) | gap to Agoo: 4.22× → **3.46×** with `handle_static` |
+| 2 | static 1 KB | 1,380 | 1,687 (**+22.2%**, PageCache 2.10-C auto-engage) | **5,935** (+330%) | gap to Agoo: 1.89× behind → **flipped, Hyperion +127%** |
+| 3 | static 1 MiB | 1,378 | 1,513 (+9.8%) | n/a (handle_static buffers in memory; defeats sendfile) | Hyperion lead vs Agoo: 9.07× → 9.74× (held) |
+| 4 | CPU JSON 50-key | 3,450 | 3,659 (+6.0%) | n/a (per-request `JSON.generate`) | gap to Agoo: 1.85× → **2.05× (widened)**; Agoo +17.5% in same window |
+| 5 | PG-bound async (`pg_sleep 50ms`) | 1,564 | 1,565 (+0.1%) | n/a | Hyperion-only; identical |
+| 6 | SSE 1000 events × 50 B | 500 | 472 (-5.6%, noise) | n/a (single fixed response) | Hyperion lead vs Puma: 3.65× → 3.58× (flat) |
+
+**Reading the deltas.**
+
+- **The 2.10-D + 2.10-F + 2.10-C win-stack lands cleanly on
+  static 1 KB.** Hyperion's `handle_static` row at 5,935 r/s
+  wins the column outright by +127% (2.27×) over Agoo, +208%
+  over Falcon, +282% over Puma. The Rack-style row also moved
+  up +22.2% from the PageCache auto-engage even without
+  explicit `handle_static` registration. Operators who can
+  register one pre-built route via `handle_static` pick up a
+  3.5× lift over the generic Rack-style path on this exact
+  shape.
+- **Hello narrowed but did not close.** The gap to Agoo went
+  from 4.22× to 3.46× with `handle_static`; the Rack-style
+  row stayed flat (within bench noise) — meaning the 2.10-D
+  direct-route win **only manifests when the rackup actually
+  opts in via `handle_static`**.
+- **CPU JSON widened.** Agoo +17.5% in the same window
+  Hyperion +6.0% took the gap from 1.85× to 2.05×. This is
+  the one row the 2.10/2.11 streams didn't move; closing it
+  is the obvious 2.12 follow-on.
+- **Large static, PG-bound async, SSE — Hyperion's existing
+  wins held.** Sendfile (9.7× over Agoo on 1 MiB), fiber-
+  cooperative I/O (Hyperion-only on PG-bound, identical to
+  2.10-B), ChunkedCoalescer (3.58× over Puma, 16.7× over
+  Falcon on SSE) all stayed clean. Agoo's SSE behavior
+  regressed to a hard segfault at boot on `bench/sse_generic.ru`
+  (different shape from 2.10-B's "buffers entire response,
+  takes ~5 s to flush"; same conclusion either way — Agoo is
+  not a viable SSE server on this rackup at any throughput).
+- **Tail latency is still Hyperion's clean win** across every
+  row with a non-trivial p99: hello 1.73 ms vs Agoo 10.47 ms
+  / Puma 29 ms / Falcon 408 ms; 1 KB 1.69 ms vs 57–86 ms;
+  1 MiB 4.63 ms vs 82–720 ms; CPU JSON 2.60 ms vs 17–411 ms;
+  SSE 2.85 ms vs 11–42 ms.
+
+**Harness changes** (`bench/4way_compare.sh`):
+
+- New server label `hyperion_handle_static` — boots Hyperion
+  against an alternate rackup specified by the new
+  `HYPERION_STATIC_RACKUP` env var (falls back to the same
+  `RACKUP` as the legacy `hyperion` label if unset, which
+  becomes a harmless no-op duplicate). The four legacy
+  labels (`hyperion`, `puma`, `falcon`, `agoo`) keep their
+  byte-identical 2.10-B shape so the older doc stays
+  reproducible.
+
+**New rackup**: `bench/static_handle_static.ru` — preloads
+the 1 KB static asset (`/tmp/hyperion_bench_1k.bin`) at boot,
+registers it via `Hyperion::Server.handle_static`, and falls
+through to a 404 lambda for any other path. Mirrors the role
+`bench/hello_static.ru` plays for the hello row.
+
+**Spec coverage** (`spec/hyperion/bench_handle_static_rackups_spec.rb`,
+9 examples):
+
+- `bench/hello_static.ru` parses cleanly and registers a `/`
+  StaticEntry with the expected response bytes.
+- `bench/static_handle_static.ru` preloads the asset and
+  registers a route at boot; fails fast if the asset is
+  missing rather than booting empty (prevents a silently-
+  bound 404 from masking a misconfigured bench run).
+- `bench/4way_compare.sh` knows how to boot all five variant
+  labels (hyperion, hyperion_handle_static, puma, falcon,
+  agoo) — a typo in the harness's case statement or the
+  new env var name fails this spec at unit-level instead
+  of waiting for a 41-minute bench sweep to surface the
+  regression.
+
+Spec count: 1093 → 1102 (+9). 0 failures, 11 pending —
+invariant preserved.
+
+**Reproducing.** See
+`docs/BENCH_HYPERION_2_11.md` § "Reproducing 4-way" for the
+six per-row commands. Bench host: `openclaw-vm`, sweep dir
+`/home/ubuntu/bench-2.12-B/`. Total wall time ~41 min.
+
 ## 2.11.0 — 2026-05-01
 
 ### 2.11-B — HPACK FFI marshalling round-2 (cglue confirmed as firm default; +43% v3 vs v2 on Rails-shape h2)