hyperion-rb 2.11.0 → 2.12.0

data/README.md

@@ -11,6 +11,65 @@ gem install hyperion-rb
 bundle exec hyperion config.ru
 ```
 
+## What's new in 2.12.0
+
+**The hot path moves into C — and gRPC ships.** The headline win:
+`Server.handle_static` routes now serve from a C accept→read→route→write
+loop with optional **io_uring** (Linux 5.x+) backing it. The `wrk -t4
+-c100 -d20s` hello bench moved from **5,502 r/s** (2.11.0
+`Server.handle_static` via Ruby accept loop) to **15,685 r/s** (2.12-C
+C accept4 loop) to **134,084 r/s** (2.12-D io_uring loop) — that's
+**24× over 2.11.0's `handle_static` and 7× over Agoo 2.15.14's
+19,024 r/s** on the same workload. p99 stays sub-millisecond
+throughout. Plus durable foundation work and one big new feature:
+
+- **2.12-B — Fresh 4-way re-bench.** New
+  [`docs/BENCH_HYPERION_2_11.md`](docs/BENCH_HYPERION_2_11.md) re-runs
+  Hyperion / Puma / Falcon / Agoo on the 6 workloads with all 2.10/2.11
+  wins enabled. Headline shifts: static 1 KB Hyperion `handle_static`
+  flipped from 1.89× behind Agoo to **+127% ahead**; CPU JSON gap
+  widened (the one row 2.10/2.11 didn't touch — flagged for follow-up).
+- **2.12-C — Connection lifecycle in C.** New
+  `Hyperion::Http::PageCache.run_static_accept_loop` does
+  `accept4` + `recv` + path lookup + `write` entirely in a C tight
+  loop, returning to Ruby only on a route miss / TLS / h2 / WebSocket
+  upgrade. GVL released across syscalls. Auto-engages when the listener
+  is plain TCP and the route table contains only `StaticEntry`
+  registrations. **5,502 → 15,685 r/s (+185%, 2.85×) on `handle_static`
+  hello; p99 1.59 ms → 107 µs (15× tighter).** Falls through to the
+  existing Ruby accept loop on miss with no regression.
+- **2.12-D — io_uring accept loop (Linux 5.x+).** A multishot accept +
+  per-conn RECV/WRITE/CLOSE state machine on top of liburing. One
+  `io_uring_enter` per N requests instead of N×3 syscalls. Opt-in via
+  `HYPERION_IO_URING_ACCEPT=1` (default off until 2.13 production
+  soak). **15,685 → 134,084 r/s (+755%, 8.6×) on the same bench.**
+  Compiles out cleanly without liburing — the `accept4` path stays
+  the fallback. macOS keeps using `accept4` (no liburing).
+- **2.12-E — SO_REUSEPORT cluster-mode audit.** New per-worker request
+  metric (`requests_dispatch_total{worker_id="N"}`) ticks under every
+  dispatch mode (Rack, `handle_static`, h2, the C accept loops). New
+  audit harness `bench/cluster_distribution.sh` and a 4-worker, 30s
+  sustained-load bench: under steady state the SO_REUSEPORT hash
+  distributes within **1.004-1.011 max/min ratio** — production-grade,
+  measured. The cold-start swing (1.16× during the first second of
+  fresh boot) is documented as expected `SO_REUSEPORT + keep-alive`
+  behavior and matches what production L4 LBs already exhibit.
+- **2.12-F — gRPC support on h2.** Trailers (the `grpc-status` /
+  `grpc-message` final HEADERS frame), `TE: trailers` handling, h2
+  request half-close semantics. Rack 3 contract: a Rack body that
+  defines `#trailers` triggers the trailers wire shape automatically;
+  bodies that don't are byte-identical to 2.11.x h2. Smoke test against
+  the real `grpc` Ruby gem ships gated by `RUN_GRPC_SMOKE=1`; the
+  durable coverage is 11 unit specs driving real `protocol-http2`
+  framer + HPACK encode/decode + TLS.
+
+The 2.10-G TCP_NODELAY hunk, 2.10-E preload hooks, 2.10-F C-ext
+`rb_pc_serve_request`, 2.11-A dispatch pool warmup, and 2.11-B cglue
+HPACK default all preserved and verified by the 1143-spec suite.
+
+Full per-stream details, bench tables, and follow-up items in
+[`CHANGELOG.md`](CHANGELOG.md).
+
 ## What's new in 2.11.0
 
 **h2 cold-stream latency cut + native HPACK CGlue flipped to default.**
@@ -156,6 +215,38 @@ container required. HTTP/1.1 only this release; WS-over-HTTP/2 (RFC 8441
 Extended CONNECT) and permessage-deflate (RFC 7692) defer to 2.2.x.
 See [`docs/WEBSOCKETS.md`](docs/WEBSOCKETS.md).
 
+## gRPC on Hyperion (2.12-F+)
+
+Hyperion's HTTP/2 path supports gRPC unary calls via the Rack 3 trailers
+contract: any response body that exposes `:trailers` gets a final
+HEADERS frame (with END_STREAM=1) carrying the trailer map after the
+DATA frames. That's the wire shape gRPC clients expect for the
+`grpc-status` / `grpc-message` map.
+
+A minimal Rack-shaped gRPC handler:
+
+```ruby
+class GrpcBody
+  def initialize(reply); @reply = reply; end
+  def each; yield @reply; end
+  def trailers; { 'grpc-status' => '0', 'grpc-message' => 'OK' }; end
+  def close; end
+end
+
+run ->(env) {
+  request = env['rack.input'].read # gRPC-framed protobuf bytes
+  reply   = handle(request)        # your service implementation
+  [200, { 'content-type' => 'application/grpc' }, GrpcBody.new(reply)]
+}
+```
+
+What Hyperion handles for you: ALPN negotiation, HTTP/2 framing, HPACK,
+per-stream flow control, the trailer-frame emit, binary-clean
+`env['rack.input']` (gRPC bodies are non-UTF-8), and `te: trailers`
+preserved into `env['HTTP_TE']`. What you handle: protobuf
+marshalling and the `grpc-status` semantics. Streaming RPCs (server /
+client / bidi) are 2.13 candidates — pin to unary for now.
+
 ## Highlights
 
 - **HTTP/1.1 + HTTP/2 + TLS** out of the box (HTTP/2 with per-stream fiber multiplexing, WINDOW_UPDATE-aware flow control, ALPN auto-negotiation).
@@ -174,11 +265,17 @@ See [`docs/WEBSOCKETS.md`](docs/WEBSOCKETS.md).
 All numbers are real wrk runs against published Hyperion configs. Hyperion ships **with default-ON structured access logs**; Puma comparisons use Puma defaults (no per-request log emission). Each section is stamped with the Hyperion version + bench host it was measured against — bench-host drift over time is real (see "Bench-host drift" note below).
 
 **Headline doc**: the most recent comprehensive sweep is
-[`docs/BENCH_HYPERION_2_0.md`](docs/BENCH_HYPERION_2_0.md) (Hyperion
-2.0.0 vs Puma 8.0.1, 16-vCPU Ubuntu 24.04, 12 workloads). The 1.6.0
-matrix at [`docs/BENCH_2026_04_27.md`](docs/BENCH_2026_04_27.md) covers
-9 workloads × 25+ configs against hyperion-async-pg 0.5.0; both docs
-include caveats and per-row reproduction commands.
+[`docs/BENCH_HYPERION_2_11.md`](docs/BENCH_HYPERION_2_11.md) — the
+2.12-B 4-way re-bench (Hyperion 2.11.0 vs Puma 8.0.1 / Falcon 0.55.3 /
+Agoo 2.15.14, 16-vCPU Ubuntu 24.04, 6 workloads). It's the post-
+2.10/2.11-wins re-baseline of the four-server matrix that originally
+shipped in [`docs/BENCH_HYPERION_2_0.md`](docs/BENCH_HYPERION_2_0.md)
+§ "4-way head-to-head (2.10-B baseline)" — the older doc is the
+**historical baseline (pre-2.10/2.11 wins)** and is preserved
+unchanged for archaeology. The 1.6.0 matrix at
+[`docs/BENCH_2026_04_27.md`](docs/BENCH_2026_04_27.md) covers 9
+workloads × 25+ configs against hyperion-async-pg 0.5.0; all three
+docs include caveats and per-row reproduction commands.
 
 > **Bench-host drift note (2026-05-01).** A spot-check rerun on
 > `openclaw-vm` 5 days after the 2.0.0 sweep showed Puma 8.0.1 and

data/ext/hyperion_http/extconf.rb

@@ -17,6 +17,7 @@ $srcs = %w[
   parser.c
   sendfile.c
   page_cache.c
+  io_uring_loop.c
   websocket.c
   h2_codec_glue.c
   llhttp.c
@@ -44,4 +45,44 @@ have_header('sys/socket.h')
 have_header('dlfcn.h')
 have_library('dl', 'dlopen')
 
+# 2.12-D — io_uring accept loop (Linux 5.x).
+#
+# Soft-optional dependency: if `liburing` is installed at compile time
+# (Ubuntu/Debian: `apt install liburing-dev`; Fedora: `dnf install
+# liburing-devel`; Arch: `pacman -S liburing`), we build the io_uring
+# accept-loop variant. If it's not, the C ext compiles cleanly without
+# it and the Ruby caller falls through to the 2.12-C `accept4` loop.
+#
+# We probe in two passes:
+#   1. `pkg-config --exists liburing` lets us pick up Debian/Ubuntu's
+#      pkg-config metadata and add the right -L/-l flags. Quiet failure
+#      is fine — the second pass catches header-only setups (vendored
+#      installs, distros without pkg-config metadata).
+#   2. `have_header('liburing.h')` + `have_library('uring', ...)` covers
+#      the no-pkg-config path.
+#
+# On success: `-DHAVE_LIBURING` lands in $defs (mkmf-managed) and
+# `io_uring_loop.c` compiles its real loop. On failure: the file
+# compiles to a thin stub that returns `:unavailable`.
+#
+# Linux-only — the loop is `#ifdef __linux__` guarded too, so a
+# liburing-on-FreeBSD setup (technically possible) still picks the
+# stub. Worth-it cost: portability + zero surprise on the bench host.
+RbConfig::CONFIG['target_os'] =~ /linux/ && begin
+  pkg_ok = system('pkg-config --exists liburing 2>/dev/null')
+  if pkg_ok
+    $CFLAGS << ' ' + `pkg-config --cflags liburing`.strip
+    $LDFLAGS << ' ' + `pkg-config --libs liburing`.strip
+    have_header('liburing.h')
+    $defs << '-DHAVE_LIBURING'
+    puts '[hyperion] liburing detected via pkg-config — building 2.12-D io_uring accept loop'
+  elsif have_header('liburing.h') && have_library('uring', 'io_uring_queue_init')
+    $defs << '-DHAVE_LIBURING'
+    puts '[hyperion] liburing detected via header probe — building 2.12-D io_uring accept loop'
+  else
+    puts '[hyperion] liburing not found — 2.12-D io_uring accept loop will return :unavailable; ' \
+         'install `liburing-dev` (Debian/Ubuntu) / `liburing-devel` (Fedora) for the io_uring path'
+  end
+end
+
 create_makefile('hyperion_http/hyperion_http')