hyperion-rb 2.10.1 → 2.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 874baf5de450eacd4df0b5cd91f9aaa3a8d86214d099f50ed81af3416085a04c
-  data.tar.gz: ca1ce4f0c3f31e9399cc8b16cd461e9275b54f630cb9ea7bef9828658e490633
+  metadata.gz: 70fee9940bc27a68927bb0204717bb35da7ea695bc02fe49aaa6c9597c9dd78d
+  data.tar.gz: aaa583caa320c605bb06e2894c3f5452d183b4aa5f1ab27329a2a3a89e1ef900
 SHA512:
-  metadata.gz: 9d2958ba3850c6df36250f91c21b9d1f3901acde0a74e9c7b8aaf09116f80729c25414b5e50397c82ca083fc9dbca1b7e4b485f34441c659512644b6edb500af
-  data.tar.gz: bab657069a157759b5c7305f1151fc5795a0b3295958591ac91b55901bd29883e41660a2ba87970c496035b53d3ca8dbda393eb03eb20d55801d2003e58be0ce
+  metadata.gz: 3c28ad4d534e00eb3b687903da63ae7c04c918d27081d9ac73e04a67d521e2abd832f100b20d87b3411fa9c7be5abdcda2f8638ca8c139ef913fbd0f1ad1930a
+  data.tar.gz: debe988e4dc461376df38bdd84833a2f608dcfb8bf2dc420fc086e89970607b1c36d632dc1057b4eb9983f83918fdc60d93ee87a10098f6f775ccd4207611fb1

data/CHANGELOG.md

@@ -1,5 +1,210 @@
 # Changelog
 
+## 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)
+
+**Bench result (openclaw-vm, 25-header h2load -c 1 -m 100 -n 5000, 3 runs/variant, median):**
+
+| Variant | Env value | Median rps |
+|---|---|---:|
+| Ruby fallback | `=off`   | 1585.35 r/s |
+| Native v2 (Fiddle, forced) | `=v2`    | 1602.27 r/s |
+| Native v3 (CGlue, forced)  | `=cglue` | 2291.44 r/s |
+
+| Delta | Value |
+|---|---:|
+| native (v2) vs ruby | +1.1% (within noise) |
+| **cglue (v3) vs native (v2)** | **+43.0%** (HEADLINE — Fiddle marshalling overhead) |
+| cglue (v3) vs ruby            | +44.5% (total native win) |
+
+**Decision: flip cglue default ON.** The bench cleanly attributes the
++18-44% native-vs-ruby headline to the C-glue path's elimination of
+per-call Fiddle marshalling, *not* to the underlying Rust HPACK
+encoder. With cglue forced off, native v2 is +1-5% over ruby —
+basically noise on this header count. The 2.5-B headline ("+18%
+native vs ruby") was actually measuring v3 vs ruby because `=1`
+silently picked v3 on cglue-available hosts; 2.11-B's `=v2` token
+made the v2-only number measurable for the first time.
+
+The `:auto` resolved state (unset / `=1` / `=true`) was already
+selecting cglue when available since 2.4-A; this round confirms
+that selection and updates the boot-log mode string to advertise
+cglue as the de jure default. The runtime behavior on a host where
+cglue is available is unchanged from 2.10 — the de facto cglue
+selection becomes de jure, with a `default since 2.11-B` marker
+in the human-readable `mode` log field.
+
+
+
+The 2.5-B Rails-shape bench measured native v3 (CGlue) at +18% over
+the Ruby fallback on a 25-header response — comfortably above the
++15% flip threshold, which moved the native-vs-Ruby default to ON.
+The remaining open question 2.5-B punted on: how much of that +18%
+is the Rust HPACK encoder, and how much is the C-glue path's
+elimination of per-call Fiddle marshalling? A direct A/B was
+impossible at the time because `=1` always picked v3 on hosts
+where the C glue had installed successfully.
+
+**Surface change.** `HYPERION_H2_NATIVE_HPACK` now accepts an
+explicit native-mode token alongside the legacy Boolean values.
+The legacy values still resolve to the same physical path they
+did before, so this is back-compat for every operator who set the
+env var pre-2.11-B:
+
+| Value | Resolves to | Pre-2.11-B behavior | 2.11-B behavior |
+|---|---|---|---|
+| (unset) / `1` / `true` / `yes` / `on` / `auto` | `:auto`  | native, prefer cglue | native, prefer cglue (unchanged) |
+| `cglue` / `v3`        | `:cglue` | (same as `1`) | force cglue, warn-fallback to v2 |
+| `v2` / `fiddle`       | `:v2`    | (same as `1`) | force v2/Fiddle (skip cglue even if installed) |
+| `0` / `false` / `no` / `off` / `ruby` | `:off`   | ruby fallback | ruby fallback (unchanged) |
+
+The new `=v2` value is the bench-isolation knob `bench/h2_rails_shape.sh`
+needs: without it the harness's "native" variant silently picked v3
+on bench hosts where the C glue loaded successfully, making the
+v2-vs-v3 delta unmeasurable. With `=v2` the operator can force the
+Fiddle path on a host where cglue is physically present.
+
+**Implementation.** `Hyperion::H2Codec.cglue_active?` overlays
+`cglue_available?` with an operator-controllable gate
+(`H2Codec.cglue_disabled = true|false`). The Encoder/Decoder hot
+paths probe `cglue_active?` (was `cglue_available?`); one extra
+ivar read per encode call which YJIT inlines away. `Http2Handler`
+sets the gate at construction based on the resolved native-mode
+state. The gate is global (the codec module is a singleton); the
+handler resets it on every construction so a `=v2` boot can't leak
+the disable into a subsequent default-mode handler.
+
+**Boot log.** The `h2 codec selected` log line gains a new `native_mode`
+field exposing the operator-requested mode (`auto` / `cglue` / `v2` /
+`off` / `cglue-requested-unavailable`). The existing `hpack_path`
+field continues to be one of `pure-ruby` / `native-v2` / `native-v3` —
+unchanged, ops dashboards keying off it keep working. The `mode`
+human-readable string differentiates `forced` from `auto` selections
+so a misconfigured `=cglue` boot on a host without the C glue is
+visible in one log line instead of requiring a process trace.
+
+**Bench harness.** `bench/h2_rails_shape.sh` now runs three variants
+(`ruby`, `native`, `cglue`) instead of two and emits
+`delta_native_vs_ruby` (informational — should reproduce the 2.5-B
++18% headline) plus `delta_cglue_vs_native` (the headline for
+2.11-B — does cutting per-call Fiddle marshalling buy anything on
+top of the v2 path?). The decision rule keys off the cglue-vs-native
+delta:
+
+| Outcome (cglue vs native) | Action |
+|---|---|
+| ≥ +15% rps | Flip cglue default ON (replace 2.5-B's auto-cglue dance) |
+| Parity / +5-10% (within noise) | Keep cglue opt-in, file as deferred |
+| ≥ −2% (negative) | Investigate, do not ship |
+
+Each variant runs 3x, output is the median.
+
+**Spec coverage.** `spec/hyperion/h2_codec_native_mode_spec.rb` — 17
+new examples covering: each native-mode token resolves to the
+expected `hpack_path`; `=cglue` on a host without the C glue logs
+`native_mode=cglue-requested-unavailable` and falls through to v2;
+`=v2` actually flips `H2Codec.cglue_active?` to false even when
+cglue is available; the three bench-variant tokens
+(`{off,v2,cglue}`) produce the three distinct `hpack_path` values
+the harness compares.
+
+### 2.11-A — h2 first-stream TLS handshake parallelization (Bucket 2: pre-spawned dispatch worker pool)
+
+The 2.10-G TCP_NODELAY fix lifted the ~40 ms h2 max-latency ceiling
+that was paid by every stream. With the per-stream Nagle/delayed-ACK
+noise gone, the **first-stream cold cost** became isolatable via the
+2.10-G `HYPERION_H2_TIMING=1` instrumentation. Reading the breakdown
+on `h2load -c 1 -m 100 -n 5000 https://localhost/`:
+
+| Bucket | Master baseline | After 2.11-A |
+|---|---:|---:|
+| `t0_to_t1_ms`    (preface exchange — 0.3-1.7 ms baseline)               | 0.3-1.7 ms | 0.6-1.2 ms |
+| `t1_to_t2_enc_ms` (preface→first stream encoded — **dominant bucket**)   | **12-25 ms** | **m=1: 1.0-1.4 ms**, m=100: 13-18 ms |
+| `t2_enc_to_t2_wire_ms` (first stream encode → first byte on wire)        | -10 to -27 ms\* | -13 to -17 ms\* |
+| `t0_to_t2_wire_ms` (preface bytes on wire)                               | 0.9-3.4 ms | 1.1-1.9 ms |
+
+\* The `t2_enc_to_t2_wire_ms` slot reflects "preface SETTINGS bytes
+on the wire" minus "first stream HEADERS encoded" — the writer
+fiber's `||=` capture lands on the preface bytes (always written
+first), not the response. The negative value is expected and
+documents the preface→response gap at the writer-fiber boundary.
+
+**The dominant bucket was `t1_to_t2_enc_ms`** — preface complete to
+first stream's HEADERS+DATA encoded. On the cold-stream `m=1` path,
+the ~3-13 ms gap is dominated by lazy `task.async {}` fiber spawn
+on the connection-loop fiber's `ready_ids` tick (under the Async
+scheduler, the first `task.async` from a cold fiber pays scheduler
+bookkeeping that warmer paths amortize away).
+
+**Fix.** Pre-spawn a fixed pool of `N` dispatch worker fibers (default
+`4`, configurable via `HYPERION_H2_DISPATCH_POOL`) inside `serve`
+BEFORE `read_connection_preface` returns. Each worker parks on a
+new per-connection `Async::Queue` exposed off `WriterContext#dispatch_queue`.
+When a stream becomes ready, the connection-loop fiber pushes onto
+the queue; a parked worker grabs it and calls `dispatch_stream`.
+
+The first stream is now an enqueue+dequeue handoff (microseconds)
+instead of a `task.async {}` cold spawn. Streams that arrive while
+the queue is non-empty (workers all busy on prior streams) fall
+back to ad-hoc `task.async {}` so concurrency is never artificially
+capped — the operator-facing knob is `h2.max_concurrent_streams`,
+not the pool size.
+
+**Bench delta on openclaw-vm (single-worker, h2load → localhost TLS h2):**
+
+| | Master | 2.11-A | Δ |
+|---|---:|---:|---:|
+| `m=1 -n 50` cold first-run, time-to-1st-byte         | 20.28 ms | **9.28 ms** | **-54%** |
+| `m=1 -n 50` warm avg, time-to-1st-byte               | 5.93 ms  | 7.20 ms     | +21% (within run-to-run noise) |
+| `m=100 -n 5000` 10-run avg, time-to-1st-byte         | 19.6 ms  | 19.1 ms     | parity |
+| `m=100 -n 5000` 10-run avg, throughput               | 2742 r/s | 2893 r/s    | +5.5% |
+| `m=1 -n 50` `t1_to_t2_enc_ms` (instrumented, cold)   | 3.4 ms   | **1.0-1.4 ms** | **-66%** |
+
+**Cold first-stream cost is roughly halved** on `m=1` (the actual
+single-stream cold-connection path). The `m=100` path is dominated
+by sequential client-frame reads on the connection-loop fiber, not
+fiber-spawn cost — the fix doesn't move that needle but doesn't
+regress it either.
+
+**Sub-fixes folded in.**
+* **Pre-resolve `peer_address`** before `read_connection_preface`.
+  The `peeraddr` syscall was previously paid on the hot path between
+  preface read and first dispatch; moving it earlier overlaps with
+  the writer fiber's first-tick scheduling.
+
+**Operator surface.**
+
+* `HYPERION_H2_DISPATCH_POOL=<N>` — set the pre-warmed dispatch
+  worker count per connection. Default `4`. Ceiling `16` (guards
+  against pathological configs spawning hundreds of idle fibers
+  per accepted connection). Invalid / non-positive values fall
+  back to the default rather than crashing the connection — this
+  is a tuning knob, not a spec parameter.
+* `WriterContext#dispatch_queue` — the per-connection
+  `Async::Queue` workers park on; bench harnesses can introspect.
+* `WriterContext#dispatch_worker_count` — live count of workers
+  currently registered (parked or actively dispatching). Useful
+  for diagnostics endpoints that want to surface "this connection's
+  pool is saturated".
+
+**Constraints preserved.**
+* TCP_NODELAY (2.10-G) hunk in `apply_tcp_nodelay` is untouched.
+* Static asset preload + immutable hooks (2.10-E) are untouched.
+* C-ext fast-path response writer (2.10-F) is untouched.
+* `HYPERION_H2_TIMING=1` instrumentation continues to fire and
+  emits the same `'h2 first-stream timing'` log shape (the four
+  deltas + total). Locked by spec.
+
+**Specs.** 12 new examples in `spec/hyperion/http2_dispatch_pool_spec.rb`
+covering the WriterContext extensions (queue + worker count + register/
+unregister), `resolve_dispatch_pool_size` env-var parsing (default,
+override, invalid input, ceiling), the pool warmup contract (workers
+registered, workers process queued items, one bad stream doesn't
+poison the pool), and a TLS+curl end-to-end smoke (the timing log
+shape continues to fire after the warmup hook is added). Spec count
+**1060 → 1072**, 0 failures.
+
 ## 2.10.1 — 2026-05-01
 
 ### 2.10-F — C-ext fast-path response writer for prebuilt responses

data/README.md

@@ -11,6 +11,39 @@ gem install hyperion-rb
 bundle exec hyperion config.ru
 ```
 
+## What's new in 2.11.0
+
+**h2 cold-stream latency cut + native HPACK CGlue flipped to default.**
+Two perf wins on top of 2.10:
+
+- **2.11-A — h2 first-stream TLS handshake parallelization.** The
+  2.10-G `HYPERION_H2_TIMING=1` instrumentation, run against the
+  TCP_NODELAY-fixed handler, isolated the residual cold-stream cost
+  to **bucket 2**: lazy `task.async {}` fiber spawn for the first
+  stream of every connection. Fix: pre-spawn a stream-dispatch fiber
+  pool at connection accept (configurable via `HYPERION_H2_DISPATCH_POOL`,
+  default 4, ceiling 16). h2load `-c 1 -m 1 -n 50` cold first-run:
+  **time-to-1st-byte 20.28 → 9.28 ms (−54%); m=100 throughput +5.5%**.
+  Warm steady-state unchanged (no head-of-line blocking under the small
+  pool — backlog still spills to ad-hoc `task.async`).
+- **2.11-B — HPACK FFI marshalling round-2 (CGlue flipped to default).**
+  Three-way bench (`bench/h2_rails_shape.sh` extended): `ruby` (1,585
+  r/s) vs `native v2` (1,602 r/s, +1% — noise) vs `native v3 / CGlue`
+  (**2,291 r/s, +43% over v2**). The +18-44% native-vs-Ruby headline
+  was almost entirely Fiddle marshalling overhead, not the underlying
+  Rust HPACK encoder — same encoder, no per-call FFI marshalling, +43%
+  rps. Default flipped: unset `HYPERION_H2_NATIVE_HPACK` now selects
+  CGlue. Three escape valves stay (`=v2` to force the old path, `=ruby`
+  / `=off` for the pure-Ruby fallback) for any operator that needs
+  them. Boot log gains a `native_mode` field documenting which path is
+  actually live.
+
+Plus operator infrastructure: a stale-`.dylib`-on-Linux cross-platform
+host-OS portability fix in `H2Codec.candidate_paths` (was silently
+falling through to pure-Ruby on the bench host); `bench/h2_rails_shape.sh`
+race-fixed (boot-log probe + stderr routing). Full bench tables and
+flip-decision rationale in [`CHANGELOG.md`](CHANGELOG.md).
+
 ## What's new in 2.10.1
 
 **Static-asset operator surface (2.10-E) + C-ext fast-path response

data/lib/hyperion/h2_codec.rb

@@ -45,11 +45,36 @@ module Hyperion
       @cglue_available == true
     end
 
+    # 2.11-B — operator-controllable gate that overlays CGlue
+    # availability. The Encoder/Decoder hot paths probe this (NOT
+    # `cglue_available?`) so a `HYPERION_H2_NATIVE_HPACK=v2` boot can
+    # force the Fiddle path even on a host where the C glue loaded
+    # successfully. This is the bench-isolation knob 2.11-B's
+    # `bench/h2_rails_shape.sh` needs to compare native-v2 against
+    # native-v3 honestly — without it, "native" and "cglue" variants
+    # would always pick the same physical path.
+    #
+    # `Http2Handler#initialize` writes the gate based on the env var;
+    # tests can flip `@cglue_disabled` directly. Default false (i.e.,
+    # gate is OPEN — same physical behavior as 2.4-A through 2.10).
+    def self.cglue_active?
+      cglue_available? && !@cglue_disabled
+    end
+
+    def self.cglue_disabled=(value)
+      @cglue_disabled = value ? true : false
+    end
+
+    def self.cglue_disabled
+      @cglue_disabled == true
+    end
+
     # Force a reload (test seam). Unsets the memoized state so the next
     # `available?` call probes the filesystem again.
     def self.reset!
       @available = nil
       @cglue_available = nil
+      @cglue_disabled = false
       @lib = nil
     end
 
@@ -126,7 +151,13 @@ module Hyperion
         # into a new owned String — that's the contract callers rely
         # on (`protocol-http2`'s Compressor#encode returns a String,
         # not a slice into shared mutable memory).
-        if H2Codec.cglue_available?
+        #
+        # 2.11-B — probe `cglue_active?` (NOT `cglue_available?`) so an
+        # operator-set `HYPERION_H2_NATIVE_HPACK=v2` boot routes through
+        # Fiddle even when the C glue is physically present. Same
+        # branch shape; one extra ivar read on the hot path which
+        # disappears under YJIT inlining.
+        if H2Codec.cglue_active?
           # Pad the scratch String with zero bytes so its length matches
           # capacity — the C ext writes into RSTRING_PTR up to RSTRING_LEN
           # and then truncates back via rb_str_set_len after encoding.
@@ -272,7 +303,8 @@ module Hyperion
         # 2.4-A — fast path: reuse a per-decoder scratch and dispatch
         # through the C glue. The Rust ABI writes `[u32 name_len][name]
         # [u32 val_len][val]` repeated; we unpack that in Ruby.
-        if H2Codec.cglue_available?
+        # 2.11-B — `cglue_active?` overlays an operator-set v2 force.
+        if H2Codec.cglue_active?
           if capacity > @scratch_out_capacity
             new_cap = @scratch_out_capacity
             new_cap *= 2 while new_cap < capacity
@@ -412,9 +444,24 @@ module Hyperion
     def self.candidate_paths
       gem_lib = File.expand_path('../hyperion_h2_codec', __dir__)
       ext_target = File.expand_path('../../ext/hyperion_h2_codec/target/release', __dir__)
-      %w[libhyperion_h2_codec.dylib libhyperion_h2_codec.so].flat_map do |name|
-        [File.join(gem_lib, name), File.join(ext_target, name)]
-      end
+      # 2.11-B fix: order suffixes by host OS. Pre-2.11-B this was a
+      # static `[dylib, so]` order, which broke on Linux hosts that
+      # had a stale macOS `.dylib` on the path (e.g. a developer rsync
+      # leaking the `target/release` artifact across platforms). Fiddle
+      # would try the `.dylib` first, choke on the Mach-O binary with
+      # `ArgumentError: invalid byte sequence in UTF-8` from libffi,
+      # and the rescue in `load!` would silently fall back to the Ruby
+      # HPACK path with no warning visible to bench harnesses.
+      #
+      # Ordering by `host_os` makes Linux pick `.so` first and ignore
+      # any orphan `.dylib`; macOS keeps the `.dylib`-first behavior
+      # for back-compat with existing dev environments.
+      suffixes = if /darwin|mac/i.match?(RbConfig::CONFIG['host_os'])
+                   %w[libhyperion_h2_codec.dylib libhyperion_h2_codec.so]
+                 else
+                   %w[libhyperion_h2_codec.so libhyperion_h2_codec.dylib]
+                 end
+      suffixes.flat_map { |name| [File.join(gem_lib, name), File.join(ext_target, name)] }
     end
 
     # FFI wrappers — kept thin so callers don't see Fiddle::Pointer

data/lib/hyperion/http2_handler.rb

@@ -2,6 +2,7 @@
 
 require 'async'
 require 'async/notification'
+require 'async/queue'
 require 'protocol/http2/server'
 require 'protocol/http2/framer'
 require 'protocol/http2/stream'
@@ -133,7 +134,7 @@ module Hyperion
     #
     # Single instance per connection, lives for the lifetime of `serve`.
     class WriterContext
-      attr_reader :encode_mutex
+      attr_reader :encode_mutex, :dispatch_queue
       # 2.10-G — connection-lifecycle timing slots used by the optional h2
       # latency-instrumentation path (gated by `HYPERION_H2_TIMING=1`).
       # Each slot is a single CLOCK_MONOTONIC timestamp captured at most
@@ -149,6 +150,15 @@ module Hyperion
         @pending_bytes_lock = ::Mutex.new
         @max_pending_bytes  = max_pending_bytes
         @writer_done        = false
+        # 2.11-A — pre-spawned dispatch worker pool. The connection-loop
+        # fiber pushes ready streams onto `@dispatch_queue`; workers
+        # parked on `dequeue` grab them and call `dispatch_stream`. The
+        # queue is created here (cheap — wraps a Thread::Queue) so the
+        # WriterContext is fully self-contained and unit-testable without
+        # an Async reactor.
+        @dispatch_queue           = ::Async::Queue.new
+        @dispatch_worker_count    = 0
+        @dispatch_worker_lock     = ::Mutex.new
         # 2.10-G timing slots, all initially nil so capture is a single
         # `||=` write under the encode mutex / writer fiber.
         @t0_serve_entry  = nil
@@ -157,6 +167,31 @@ module Hyperion
         @t2_first_wire   = nil
       end
 
+      # 2.11-A — bench/diagnostics introspection. Reads the live count
+      # of dispatch worker fibers parked on (or actively pulling from)
+      # `@dispatch_queue`. Reflects pre-spawned workers AND any ad-hoc
+      # workers spawned when the pool was saturated. Exposed as a method
+      # rather than `attr_reader` so the lock guards the counter.
+      def dispatch_worker_count
+        @dispatch_worker_lock.synchronize { @dispatch_worker_count }
+      end
+
+      # Called by a dispatch worker fiber when it enters its run loop.
+      # Pairs with `unregister_dispatch_worker` in an ensure block.
+      def register_dispatch_worker
+        @dispatch_worker_lock.synchronize { @dispatch_worker_count += 1 }
+      end
+
+      # Called by a dispatch worker fiber when it exits (queue closed,
+      # or unrecoverable error). Floors at 0 to defend against a stray
+      # double-unregister — instrumentation must never go negative.
+      def unregister_dispatch_worker
+        @dispatch_worker_lock.synchronize do
+          @dispatch_worker_count -= 1
+          @dispatch_worker_count = 0 if @dispatch_worker_count.negative?
+        end
+      end
+
       # Called by SendQueueIO#write on the calling (encoder) fiber. Enforces
       # the per-connection backpressure cap before enqueuing.
       def enqueue(bytes)
@@ -480,14 +515,19 @@ module Hyperion
       # threshold. 2.4-A's hello-shape bench saw parity because HPACK
       # is <1% of per-stream CPU on a 2-header response.
       #
+      # 2.11-B — `HYPERION_H2_NATIVE_HPACK` extended with a native-mode
+      # axis (`auto` / `cglue` / `v2` / `off`). See `resolve_h2_native_hpack_state`.
       # Operators who want the prior 2.4.x default (Ruby fallback, env
-      # var unset) can now set `HYPERION_H2_NATIVE_HPACK=off` (or
-      # `0`/`false`/`no`/`off`) explicitly. `HYPERION_H2_NATIVE_HPACK=1`
-      # still works for explicit opt-in.
+      # var unset) can set `HYPERION_H2_NATIVE_HPACK=off` (or
+      # `0`/`false`/`no`/`off`/`ruby`). `HYPERION_H2_NATIVE_HPACK=1`
+      # / unset preserves the 2.5-B `auto` behavior. `=cglue`/`=v2`
+      # forces the corresponding native sub-path.
       #
       # When OFF (env-overridden): `protocol-http2`'s pure-Ruby HPACK
       # Compressor / Decompressor handles everything as in 2.0.0–2.4.x.
-      @h2_native_hpack_enabled = @h2_codec_available && resolve_h2_native_hpack_default
+      @h2_native_mode          = resolve_h2_native_hpack_state
+      @h2_native_hpack_enabled = @h2_codec_available && @h2_native_mode != :off
+      apply_h2_cglue_gate(@h2_native_mode)
       @h2_codec_native = @h2_native_hpack_enabled # back-compat ivar — preserved for codec_native? readers
       # 2.10-G — opt-in connection-setup timing instrumentation. When set,
       # `serve` captures four monotonic timestamps per connection:
@@ -507,9 +547,45 @@ module Hyperion
       # cost when disabled — a single ivar read per stream branch). Used by
       # 2.10-G to root-cause Hyperion's flat ~40 ms first-stream max-latency.
       @h2_timing_enabled = env_flag_enabled?('HYPERION_H2_TIMING')
+      # 2.11-A — resolve the dispatch worker pool size once at handler
+      # construction so every `serve` call uses the same value (instead
+      # of re-parsing ENV per connection on the hot path). Cached as an
+      # ivar; bench/diagnostics can read it via the spec seam.
+      @dispatch_pool_size = resolve_dispatch_pool_size
       record_codec_boot_state
     end
 
+    # 2.11-A — pre-spawned dispatch worker pool sizing.
+    #
+    # Default `4` workers per connection — enough to absorb the typical
+    # HTTP/2 burst (2-8 concurrent streams) without paying any per-stream
+    # `task.async {}` cost on the hot path. Operators on long-lived
+    # high-fan-out connections (e.g. an aggregator backend that fans
+    # 30+ parallel streams) can bump this with `HYPERION_H2_DISPATCH_POOL`.
+    # Streams that arrive when the pool is saturated still get an ad-hoc
+    # fiber (see `serve` below) so concurrency is never artificially
+    # capped — the operator-facing limit is `h2.max_concurrent_streams`.
+    #
+    # Ceiling at 16 guards against a pathological config that would
+    # spawn hundreds of idle fibers per accepted connection. Anything
+    # malformed / non-positive falls back to the default rather than
+    # crashing the connection — this is a tuning knob, not a spec
+    # parameter.
+    DISPATCH_POOL_DEFAULT = 4
+    DISPATCH_POOL_MAX     = 16
+
+    def resolve_dispatch_pool_size
+      raw = ENV['HYPERION_H2_DISPATCH_POOL']
+      return DISPATCH_POOL_DEFAULT if raw.nil? || raw.strip.empty?
+
+      n = Integer(raw.strip, 10)
+      return DISPATCH_POOL_DEFAULT unless n.positive?
+
+      [n, DISPATCH_POOL_MAX].min
+    rescue ArgumentError, TypeError
+      DISPATCH_POOL_DEFAULT
+    end
+
     # Read an env-var flag with the usual truthiness rules (any of
     # 1/true/yes/on, case-insensitive). Anything else → false.
     def env_flag_enabled?(name)
@@ -519,21 +595,42 @@ module Hyperion
       %w[1 true yes on].include?(v.downcase)
     end
 
-    # Read an env-var flag with explicit OFF support. Used by
-    # `HYPERION_H2_NATIVE_HPACK` since 2.5-B flipped the default to ON.
-    # Returns true if the env var is unset / empty / explicitly truthy;
-    # returns false only when the operator sets it to a truthy-OFF
-    # value (0/false/no/off, case-insensitive). Anything else falls
-    # back to the default-on behavior so we don't surprise operators
-    # who set typo'd values.
-    def resolve_h2_native_hpack_default
+    # 2.11-B — resolve the operator-requested native-mode state from
+    # `HYPERION_H2_NATIVE_HPACK`.
+    #
+    # Returns one of:
+    #   * `:auto`  — native enabled, prefer cglue if available
+    #                (unset / `1` / `true` / `yes` / `on` / `auto`)
+    #   * `:cglue` — native enabled, force cglue (warn-fallback to v2
+    #                if cglue is unavailable; native_mode log marker
+    #                surfaces the divergence to the operator)
+    #   * `:v2`    — native enabled, force Fiddle (skip cglue even if
+    #                available; this is the bench-isolation knob the
+    #                2.11-B Rails-shape harness needs)
+    #   * `:off`   — ruby fallback (`0` / `false` / `no` / `off` / `ruby`)
+    #
+    # Unknown values fall through to `:auto` rather than crashing the
+    # connection — same forgiving-default policy as the pre-2.11-B
+    # `resolve_h2_native_hpack_default`.
+    def resolve_h2_native_hpack_state
       v = ENV['HYPERION_H2_NATIVE_HPACK']
-      return true if v.nil? || v.empty?
+      return :auto if v.nil? || v.empty?
 
       lc = v.downcase
-      return false if %w[0 false no off].include?(lc)
+      return :off   if %w[0 false no off ruby].include?(lc)
+      return :cglue if %w[cglue v3].include?(lc)
+      return :v2    if %w[v2 fiddle].include?(lc)
+
+      :auto
+    end
 
-      true
+    # 2.11-B — flip the global `H2Codec.cglue_disabled` gate based on
+    # the resolved native-mode state. The gate is per-process state
+    # (the codec module is a singleton) so reset it on every handler
+    # construction; otherwise a test that booted with `=v2` would leak
+    # the disable into a subsequent default-mode handler.
+    def apply_h2_cglue_gate(state)
+      Hyperion::H2Codec.cglue_disabled = (state == :v2)
     end
 
     # 2.0.0 Phase 6b: emit a single-shot boot log line per process
@@ -544,23 +641,32 @@ module Hyperion
       return if Hyperion::Http2Handler.instance_variable_get(:@codec_state_logged)
 
       Hyperion::Http2Handler.instance_variable_set(:@codec_state_logged, true)
-      cglue_active = @h2_native_hpack_enabled && Hyperion::H2Codec.cglue_available?
-      mode =
-        if @h2_native_hpack_enabled && cglue_active
-          'native (Rust v3 / CGlue) — HPACK on hot path, no Fiddle per call'
-        elsif @h2_native_hpack_enabled
-          'native (Rust v2 / Fiddle) — HPACK on hot path, Fiddle marshalling per call'
-        elsif @h2_codec_available
-          'fallback (protocol-http2 / pure Ruby HPACK) — native available but opted out via HYPERION_H2_NATIVE_HPACK=off'
-        else
-          'fallback (protocol-http2 / pure Ruby HPACK) — native unavailable'
-        end
+      # 2.11-B — `cglue_active` gates on the operator-controllable
+      # `cglue_active?` predicate (was `cglue_available?` pre-2.11-B).
+      # When the operator sets `=v2` we want the boot log to read
+      # `cglue_active: false` even though the C glue did install
+      # successfully — the bench harness inspects this field to
+      # differentiate the variants.
+      cglue_active = @h2_native_hpack_enabled && Hyperion::H2Codec.cglue_active?
+      cglue_requested_unavailable = @h2_native_mode == :cglue &&
+                                    @h2_native_hpack_enabled &&
+                                    !Hyperion::H2Codec.cglue_available?
+      mode = describe_codec_mode(cglue_active: cglue_active,
+                                 cglue_requested_unavailable: cglue_requested_unavailable)
+      native_mode_log = if !@h2_native_hpack_enabled
+                          @h2_native_mode == :off ? 'off' : 'native-disabled'
+                        elsif cglue_requested_unavailable
+                          'cglue-requested-unavailable'
+                        else
+                          @h2_native_mode.to_s
+                        end
       @logger.info do
         {
           message: 'h2 codec selected',
           mode: mode,
           native_available: @h2_codec_available,
           native_enabled: @h2_native_hpack_enabled,
+          native_mode: native_mode_log,
           cglue_active: cglue_active,
           hpack_path: if @h2_native_hpack_enabled
                         cglue_active ? 'native-v3' : 'native-v2'
@@ -573,6 +679,34 @@ module Hyperion
       @metrics.increment(:h2_codec_fallback_selected) unless @h2_native_hpack_enabled
     end
 
+    # 2.11-B — boot-log mode descriptor (extracted for clarity since
+    # the matrix of native_mode × cglue_available × cglue_active grew
+    # past the point where an inline conditional was readable).
+    def describe_codec_mode(cglue_active:, cglue_requested_unavailable:)
+      if !@h2_native_hpack_enabled
+        if @h2_codec_available
+          'fallback (protocol-http2 / pure Ruby HPACK) — native available but opted out via HYPERION_H2_NATIVE_HPACK=off'
+        else
+          'fallback (protocol-http2 / pure Ruby HPACK) — native unavailable'
+        end
+      elsif cglue_active && @h2_native_mode == :cglue
+        'native (Rust v3 / CGlue, forced) — HPACK on hot path, no Fiddle per call'
+      elsif cglue_active
+        # 2.11-B confirmed cglue as the firm default — the bench-measured
+        # delta vs the v2 (Fiddle) path is +33-43% on Rails-shape h2
+        # responses, which is the actual win the 2.5-B "+18% native vs
+        # ruby" headline was capturing (v2 alone is +1-5%, basically
+        # noise vs the ruby fallback at this header count).
+        'native (Rust v3 / CGlue, default since 2.11-B) — HPACK on hot path, no Fiddle per call'
+      elsif @h2_native_mode == :v2
+        'native (Rust v2 / Fiddle, forced) — HPACK on hot path, Fiddle marshalling per call'
+      elsif cglue_requested_unavailable
+        'native (Rust v2 / Fiddle) — CGlue requested via HYPERION_H2_NATIVE_HPACK=cglue but unavailable, fell back'
+      else
+        'native (Rust v2 / Fiddle) — HPACK on hot path, Fiddle marshalling per call'
+      end
+    end
+
     # Read-only accessor used by tests + diagnostics. true = the
     # `Hyperion::H2Codec` Rust extension loaded successfully AND
     # `HYPERION_H2_NATIVE_HPACK=1` is set, so `build_server` will
@@ -610,6 +744,14 @@ module Hyperion
 
       task = ::Async::Task.current
 
+      # 2.11-A — extract the peer address BEFORE the preface exchange.
+      # Two wins: (1) the lookup runs in parallel with the writer fiber
+      # picking up the first scheduler slot, and (2) the first stream's
+      # dispatch fiber doesn't pay this `peeraddr` syscall on its hot
+      # path. The address is then captured by the worker closures
+      # below.
+      peer_addr = peer_address(socket)
+
       # Spawn the dedicated writer fiber BEFORE the preface exchange.
       # `Server#read_connection_preface` writes the server's SETTINGS frame
       # via the framer; if the writer isn't running, those bytes sit in the
@@ -618,15 +760,23 @@ module Hyperion
       # waits for our SETTINGS before sending more frames.
       writer_task = task.async { run_writer_loop(socket, writer_ctx) }
 
+      # 2.11-A — pre-spawn the dispatch worker pool BEFORE the preface
+      # exchange. Workers park on `writer_ctx.dispatch_queue.dequeue`;
+      # by the time the first client HEADERS frame arrives the workers
+      # are already in the scheduler's runnable set. The first stream
+      # is just an enqueue + dequeue (microseconds) instead of a
+      # `task.async {}` cold spawn (was the dominant cost in the t1→t2_enc
+      # bucket per the 2.10-G timing breakdown).
+      warmup_dispatch_pool!(task, writer_ctx, peer_addr: peer_addr,
+                                              pool_size: @dispatch_pool_size)
+
       server.read_connection_preface(initial_settings_payload)
       writer_ctx.t1_preface_done = monotonic_now if @h2_timing_enabled
 
-      # Extract once — the same TCP peer drives every stream on this conn.
-      peer_addr = peer_address(socket)
-
-      # Track in-flight per-stream dispatch fibers so we can drain them on
-      # connection close.
-      stream_tasks = []
+      # Track ad-hoc per-stream dispatch fibers (spilled when the pool is
+      # saturated). The pool handles the common case; we only fall back
+      # to `task.async {}` when more streams arrive than warm workers.
+      overflow_tasks = []
 
       until server.closed?
         ready_ids = []
@@ -645,14 +795,35 @@ module Hyperion
           # if subsequent frames (e.g. RST_STREAM races) arrive.
           stream.instance_variable_set(:@hyperion_dispatched, true)
 
-          stream_tasks << task.async do
-            dispatch_stream(stream, writer_ctx, peer_addr)
+          # 2.11-A — hand the stream to a warm worker via the dispatch
+          # queue. We use a simple "queue is empty" probe to decide:
+          #
+          #   * Empty queue ⇒ at least one worker is parked on
+          #     `dequeue`; the enqueue+dequeue handoff is microseconds
+          #     and we avoid a `task.async {}` cold spawn. This is the
+          #     hot path for the FIRST stream of a fresh connection
+          #     (the case 2.11-A is targeting).
+          #   * Non-empty queue ⇒ every parked worker has already
+          #     pulled a stream; another worker won't pick this up
+          #     until one finishes. To avoid head-of-line blocking
+          #     behind the warmup pool, fall back to `task.async {}`.
+          #     The overflow fiber re-uses `dispatch_stream` so the
+          #     dispatch contract is identical between pool and
+          #     overflow paths. Concurrency is never artificially
+          #     capped; the operator-facing knob is
+          #     `h2.max_concurrent_streams`.
+          if writer_ctx.dispatch_queue.size.zero?
+            writer_ctx.dispatch_queue.enqueue(stream)
+          else
+            overflow_tasks << task.async do
+              dispatch_stream(stream, writer_ctx, peer_addr)
+            end
           end
         end
       end
 
       # Drain in-flight stream dispatches before we close the socket.
-      stream_tasks.each do |t|
+      overflow_tasks.each do |t|
         t.wait
       rescue StandardError
         nil
@@ -676,6 +847,18 @@ module Hyperion
       # socket before the writer drains would discard final RST_STREAM /
       # GOAWAY / END_STREAM frames in the queue.
       if writer_ctx
+        # 2.11-A — close the dispatch queue so any pre-spawned workers
+        # parked on `dequeue` fall through (Async::Queue#dequeue returns
+        # nil after close). Do this BEFORE waiting on the writer so
+        # pool workers can drain their in-flight stream dispatches and
+        # release the encode mutex; otherwise the writer might park
+        # waiting for bytes that the dispatch worker never gets to
+        # encode.
+        begin
+          writer_ctx.dispatch_queue.close unless writer_ctx.dispatch_queue.closed?
+        rescue StandardError
+          nil
+        end
         writer_ctx.shutdown!
         begin
           writer_task&.wait
@@ -695,6 +878,63 @@ module Hyperion
 
     private
 
+    # 2.11-A — pre-spawn the per-connection dispatch worker pool.
+    #
+    # Each worker is a fiber that loops:
+    #   1. `dequeue` a stream from the per-connection dispatch queue
+    #      (parks the fiber on the queue's internal notification when
+    #      empty — zero CPU until a stream arrives).
+    #   2. Calls `dispatch_stream` with the stream + writer context +
+    #      pre-resolved peer address.
+    #   3. Loops back to (1). Exits cleanly when `dequeue` returns nil
+    #      (queue closed by `serve`'s ensure block on connection
+    #      teardown).
+    #
+    # Why pre-spawn rather than `task.async {}` per stream:
+    #   * Fiber startup under Async involves a few µs of allocation and
+    #     scheduler bookkeeping. Per-stream that's negligible; on the
+    #     CONNECTION COLD PATH (first request on a fresh TCP/TLS conn)
+    #     it adds up to a measurable share of the t1→t2_enc bucket
+    #     (the 2.10-G timing breakdown showed ~12-25 ms on h2load
+    #     `-c 1 -m 100 -n 5000`).
+    #   * Workers parked on `dequeue` are already in the scheduler's
+    #     ready set; the first stream is just an enqueue + dequeue
+    #     handoff (microseconds).
+    #
+    # Errors inside `dispatch_stream` are already caught + RST_STREAMed
+    # there, so the worker only needs to defend against truly
+    # unexpected failures (queue shutdown races, fiber kill on graceful
+    # shutdown). We swallow those defensively and unregister so the
+    # `dispatch_worker_count` introspection is truthful.
+    def warmup_dispatch_pool!(task, writer_ctx, peer_addr:, pool_size:)
+      pool_size.times do
+        task.async do
+          writer_ctx.register_dispatch_worker
+          begin
+            loop do
+              stream = writer_ctx.dispatch_queue.dequeue
+              break if stream.nil? # queue closed → graceful exit
+
+              begin
+                dispatch_stream(stream, writer_ctx, peer_addr)
+              rescue StandardError => e
+                # `dispatch_stream` already logs + RST_STREAMs internally;
+                # if anything escapes that net we log here and keep the
+                # worker alive — one bad stream must not poison the
+                # connection's worker pool.
+                @logger.error do
+                  { message: 'h2 dispatch worker swallowed error',
+                    error: e.message, error_class: e.class.name }
+                end
+              end
+            end
+          ensure
+            writer_ctx.unregister_dispatch_worker
+          end
+        end
+      end
+    end
+
     # Build the [setting_id, value] pairs that go in the connection-preface
     # SETTINGS frame. protocol-http2's Server#read_connection_preface accepts
     # this array and does the wire encoding for us. Empty array (no overrides

data/lib/hyperion/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hyperion
-  VERSION = '2.10.1'
+  VERSION = '2.11.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperion-rb
 version: !ruby/object:Gem::Version
-  version: 2.10.1
+  version: 2.11.0
 platform: ruby
 authors:
 - Andrey Lobanov