hyperion-rb 2.11.0 → 2.13.0

data/README.md

@@ -11,6 +11,114 @@ gem install hyperion-rb
 bundle exec hyperion config.ru
 ```
 
+## What's new in 2.13.0
+
+**Hardening sprint: profile-driven CPU work, durable infrastructure,
+and gRPC streaming.** 2.13 follows up the 2.12 perf jump with the
+work that wasn't structural enough to need its own major release —
+each stream is small but adds up:
+
+- **2.13-A — Generic Rack hot-path wins.** Per-thread shards for
+  hot-path metrics (no more cross-worker mutex on `observe_histogram`),
+  cached `worker_id` label tuple, and a Rack-3 keepalive fast-path.
+  Generic Rack hello bench: **+3.6% on `-c100` no-log**. Honest
+  finding: env-pool + body-coalesce already shipped; the deeper
+  generic-Rack gap to Agoo is single-thread Ruby ceiling that closing
+  needs moving `app.call` into the C accept loop — a 2.14 lift.
+- **2.13-B — Response head builder rewritten in C.** Pre-baked
+  status-line table, `rb_hash_foreach` replacing `rb_funcall(:keys)`,
+  per-key downcase + per-(key, value) full-line caches, custom `itoa`
+  replacing `snprintf`. **+7.7% single-thread synthetic; multi-thread
+  neutral (GVL-bound).** Profile confirms Hyperion's own C-ext code is
+  **<1%** of wall-clock; the rest is libruby + JSON gem.
+- **2.13-C — Spec flake hunt.** Two long-standing flakes fixed:
+  `tls_ktls_spec` macOS skip leak (unconditional `RUBY_PLATFORM`
+  guard), and `connection_loop_spec:79` Linux port-bind flake (root
+  cause: Linux `close()` doesn't wake a parked `accept(2)` — fixed
+  with a `stop_loop_and_wake` helper). 5/5 → 0/10 failure rate;
+  spec-suite runtime 46 s → 1.3 s.
+- **2.13-D — gRPC streaming RPCs.** Server-streaming, client-streaming,
+  and bidirectional RPCs on top of 2.12-F's unary trailers foundation.
+  New `bench/grpc_stream.{proto,ru}` + `grpc_stream_bench.sh` ghz
+  harness for operator-side comparison vs Falcon's `async-grpc`.
+- **2.13-E — io_uring soak harness + CI smoke.** New
+  `bench/io_uring_soak.sh` runs a 24h soak against the 2.12-D
+  io_uring loop with `/proc/$PID` + `/-/metrics` sampling, emits a
+  CSV + verdict (PASS / SOAK FAIL / borderline). New
+  `spec/hyperion/io_uring_soak_smoke_spec.rb` runs a 1000-request
+  mini-soak in CI to catch leak regressions before any 24h run.
+  **`HYPERION_IO_URING_ACCEPT` stays opt-in for 2.13** — operators
+  with their own staging environments can now collect signal; the
+  default-flip decision moves to 2.14.
+
+Plus all previous wins are preserved and verified by the 1183-spec
+suite (2.10-G TCP_NODELAY at accept, 2.10-E preload hooks, 2.10-F
+C-ext fast-path response writer, 2.11-A dispatch pool warmup, 2.11-B
+cglue HPACK default, 2.12-C accept4 connection loop, 2.12-D io_uring
+loop, 2.12-E per-worker request counter, 2.12-F gRPC unary trailers).
+
+Full per-stream details, bench tables, and follow-up items in
+[`CHANGELOG.md`](CHANGELOG.md).
+
+## 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 +264,107 @@ 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 (2.13-D+)
+
+All four gRPC call shapes work on Hyperion since 2.13-D — unary,
+server-streaming, client-streaming, and bidirectional. The detection
+trigger is the gRPC content-type plus `te: trailers`; any HTTP/2
+request that carries both is dispatched to the Rack app on HEADERS
+arrival (rather than after END_STREAM), and `env['rack.input']`
+becomes a streaming IO that blocks reads until the next DATA frame
+lands. Plain HTTP/2 traffic (without those headers) keeps the unary
+buffered semantics — no behaviour change for non-gRPC clients.
+
+**Server-streaming.** Yield one gRPC-framed message per `each`
+iteration; Hyperion writes each yield as its own DATA frame:
+
+```ruby
+class StreamReply
+  def initialize(messages); @messages = messages; end
+  def each; @messages.each { |m| yield m }; end       # one DATA frame each
+  def trailers; { 'grpc-status' => '0' }; end
+  def close; end
+end
+
+run ->(env) {
+  env['rack.input'].read # the unary request message
+  [200, { 'content-type' => 'application/grpc' }, StreamReply.new(messages)]
+}
+```
+
+**Client-streaming.** Read messages off `env['rack.input']` as the peer
+sends them. Reads block until a DATA frame arrives:
+
+```ruby
+run ->(env) {
+  io = env['rack.input']
+  count = 0
+  while (prefix = io.read(5)) && prefix.bytesize == 5
+    length = prefix.byteslice(1, 4).unpack1('N')
+    msg = io.read(length)
+    count += 1
+  end
+  [200, { 'content-type' => 'application/grpc' }, GrpcBody.new(reply_for(count))]
+}
+```
+
+**Bidirectional.** Interleave reads and writes. The response body is
+iterated lazily, so you can read one request message, yield one reply,
+read the next, yield the next:
+
+```ruby
+class BidiReplies
+  def initialize(io); @io = io; end
+  def each
+    while (prefix = @io.read(5)) && prefix.bytesize == 5
+      len = prefix.byteslice(1, 4).unpack1('N')
+      msg = @io.read(len)
+      yield grpc_frame(handle(msg))                   # sent immediately
+    end
+  end
+  def trailers; { 'grpc-status' => '0' }; end
+  def close; end
+end
+
+run ->(env) {
+  [200, { 'content-type' => 'application/grpc' }, BidiReplies.new(env['rack.input'])]
+}
+```
+
+The streaming-input path runs each stream on its own fiber, so
+concurrent read+write on the same stream is safe.
+
 ## 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 +383,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')