hyperion-rb 2.10.1 → 2.12.0

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)
@@ -240,7 +275,16 @@ module Hyperion
       def initialize(*)
         super
         @request_headers = []
-        @request_body = +''
+        # 2.12-F — gRPC carries opaque protobuf bytes
+        # ([1-byte compressed flag][4-byte length-prefix][message bytes]) in the
+        # request body. The default UTF-8 encoding on a `+''` literal would
+        # break valid_encoding? on byte sequences that don't form UTF-8
+        # codepoints, leading to a Rack app reading `body.string` and getting
+        # a String that misreports its bytesize / corrupts when string-
+        # interpolated. ASCII_8BIT (binary) preserves bytes verbatim and is
+        # the encoding gRPC Ruby clients expect. Same change is applied to
+        # the HTTP/1.1 path as a separate concern; see Connection.
+        @request_body = String.new(encoding: Encoding::ASCII_8BIT)
         @request_body_bytes = 0
         @request_complete = false
         @window_available = ::Async::Notification.new
@@ -471,6 +515,10 @@ module Hyperion
         @logger  = Hyperion.logger
       end
       @h2_admission       = h2_admission
+      # 2.12-E — per-worker request counter label. Identical caching
+      # rationale to Connection#initialize: process-constant ID, looked
+      # up once and held in the ivar.
+      @worker_id          = Process.pid.to_s
       @h2_codec_available = Hyperion::H2Codec.available?
       # 2.5-B [breaking-default-change]: native HPACK now defaults to ON
       # when the Rust crate is available. The 2026-04-30 Rails-shape
@@ -480,14 +528,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 +560,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 +608,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)
 
-      true
+      :auto
+    end
+
+    # 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 +654,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 +692,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 +757,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 +773,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 +808,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 +860,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 +891,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
@@ -881,6 +1134,11 @@ module Hyperion
 
       @metrics.increment(:requests_total)
       @metrics.increment(:requests_in_flight)
+      # 2.12-E — per-worker request counter, ticked once per h2 stream.
+      # Same family as Connection#serve so the audit metric reflects
+      # cluster distribution across BOTH transports without operators
+      # needing to alert on two separate counters.
+      @metrics.tick_worker_request(@worker_id)
       # 2.1.0 (WS-1): HTTP/2 hijack is intentionally NOT plumbed here.
       # Rack 3 hijack over HTTP/2 requires Extended CONNECT (RFC 8441 +
       # RFC 9220) — a separate feature with its own SETTINGS handshake,
@@ -915,8 +1173,17 @@ module Hyperion
         end
       end
 
-      payload = +''
+      # 2.12-F — gRPC support: bodies that respond to `:trailers` carry a
+      # final HEADERS frame (with END_STREAM=1) right after the DATA frames.
+      # The Rack 3 contract is "iterate body first, then call body.trailers"
+      # — so we materialise the payload, then *before* `body.close`
+      # (`Rack::BodyProxy` clears state on close) snapshot the trailers Hash.
+      # `nil` / empty Hash → no trailing frame. Non-Hash values are coerced
+      # to a Hash defensively; a misbehaving app must not be able to crash
+      # the connection.
+      payload = String.new(encoding: Encoding::ASCII_8BIT)
       body_chunks.each { |c| payload << c.to_s }
+      response_trailers = collect_response_trailers(body_chunks)
       body_chunks.close if body_chunks.respond_to?(:close)
 
       # Hotfix C2: empty-body responses (RFC 7230 §3.3.3 — 204/304 + HEAD)
@@ -925,10 +1192,21 @@ module Hyperion
       # one writer-fiber wakeup instead of two. Any body the app returned
       # for HEAD is discarded here per spec (the bytes were already
       # built — that's a Rack-app smell, not our problem to fix).
+      #
+      # Trailers on body-suppressed responses (HEAD/204/304) are dropped:
+      # the response is end-of-stream after HEADERS, with no place to put
+      # a trailing HEADERS frame. This matches what curl --http2 / grpc
+      # clients do (HEAD + gRPC isn't a meaningful combination).
       if body_suppressed?(method, status)
         writer_ctx.encode_mutex.synchronize do
           stream.send_headers(out_headers, ::Protocol::HTTP2::END_STREAM)
         end
+      elsif have_trailers?(response_trailers)
+        # gRPC / Rack-3-trailers path: HEADERS (no END_STREAM), DATA frames
+        # (no END_STREAM on last DATA), final HEADERS with END_STREAM=1.
+        writer_ctx.encode_mutex.synchronize { stream.send_headers(out_headers) }
+        send_body(stream, payload, writer_ctx, end_stream: false)
+        send_trailers(stream, response_trailers, writer_ctx)
       else
         writer_ctx.encode_mutex.synchronize { stream.send_headers(out_headers) }
         send_body(stream, payload, writer_ctx)
@@ -989,9 +1267,24 @@ module Hyperion
     #
     # The encode_mutex protects HPACK state and per-stream frame ordering;
     # the actual socket write happens off-fiber via the writer task.
-    def send_body(stream, payload, writer_ctx)
+    #
+    # 2.12-F — `end_stream:` controls whether the LAST DATA frame carries
+    # the END_STREAM flag. The default `true` preserves pre-2.12-F semantics
+    # (final DATA frame closes the stream). Callers that intend to send a
+    # trailing HEADERS frame after the body pass `end_stream: false` so the
+    # final DATA frame leaves the stream half-open from the server side
+    # and the trailer HEADERS frame can carry END_STREAM=1.
+    def send_body(stream, payload, writer_ctx, end_stream: true)
       if payload.empty?
-        writer_ctx.encode_mutex.synchronize { stream.send_data('', ::Protocol::HTTP2::END_STREAM) }
+        if end_stream
+          writer_ctx.encode_mutex.synchronize do
+            stream.send_data('', ::Protocol::HTTP2::END_STREAM)
+          end
+        end
+        # When end_stream is false AND payload is empty, we deliberately
+        # send NO DATA frame at all — gRPC trailers-only responses (the
+        # error-without-payload shape) are HEADERS → trailer-HEADERS, no
+        # DATA in between. send_trailers handles the closing END_STREAM.
         return
       end
 
@@ -1010,12 +1303,77 @@ module Hyperion
 
         chunk = payload.byteslice(offset, available)
         offset += chunk.bytesize
-        flags = offset >= bytesize ? ::Protocol::HTTP2::END_STREAM : 0
+        last_chunk = offset >= bytesize
+        flags = last_chunk && end_stream ? ::Protocol::HTTP2::END_STREAM : 0
 
         writer_ctx.encode_mutex.synchronize { stream.send_data(chunk, flags) }
       end
     end
 
+    # 2.12-F — pull a trailers Hash off the response body if Rack 3
+    # `body.trailers` is implemented. Called AFTER the body has been
+    # fully iterated (Rack 3 contract: trailers are computed by the body
+    # while it streams; reading them before iteration is undefined).
+    # Returns nil when the body doesn't expose trailers, when the call
+    # raises, or when the result isn't a Hash-coercible map. Defensive
+    # by design: a misbehaving app must not crash the dispatch loop.
+    def collect_response_trailers(body)
+      return nil unless body.respond_to?(:trailers)
+
+      raw = body.trailers
+      return nil if raw.nil?
+      return raw if raw.is_a?(Hash)
+      return raw.to_h if raw.respond_to?(:to_h)
+
+      nil
+    rescue StandardError => e
+      @logger.warn do
+        { message: 'h2 body.trailers raised; ignoring',
+          error: e.message, error_class: e.class.name }
+      end
+      nil
+    end
+
+    # 2.12-F — predicate for "we have trailers worth sending". Defined as
+    # a method (rather than the more idiomatic `!h.nil? && !h.empty?` /
+    # `h&.any?`) because rubocop-rails on the hot path autocorrects both
+    # of those forms to `h.present?`, which raises NoMethodError on a
+    # plain Hash outside ActiveSupport. Hyperion is a stand-alone gem;
+    # we don't depend on ActiveSupport, so we route through this helper
+    # to keep the rubocop-rails formatter quiet without adding a Cop
+    # disable comment everywhere a nil-or-empty Hash check appears.
+    def have_trailers?(trailers)
+      return false if trailers.nil?
+      return false if trailers.respond_to?(:empty?) && trailers.empty?
+
+      true
+    end
+
+    # 2.12-F — emit the final HEADERS frame carrying response trailers.
+    # The wire shape is one HEADERS frame with END_STREAM=1; HPACK
+    # encodes the trailer block exactly like a regular HEADERS frame.
+    # Trailer keys MUST be lowercased (RFC 7540 §8.1.2) — same rule as
+    # regular HTTP/2 headers. We strip CR/LF from values defensively
+    # (a header-injection guard) and split multi-line values on \n the
+    # same way the regular response-header path does.
+    def send_trailers(stream, trailers, writer_ctx)
+      pairs = []
+      trailers.each do |k, v|
+        name = k.to_s.downcase
+        # Pseudo-headers and forbidden names cannot appear in trailers.
+        next if name.empty?
+        next if name.start_with?(':')
+        next if RequestStream::FORBIDDEN_HEADERS.include?(name)
+
+        Array(v).each do |val|
+          val.to_s.split("\n").each { |line| pairs << [name, line] }
+        end
+      end
+      writer_ctx.encode_mutex.synchronize do
+        stream.send_headers(pairs, ::Protocol::HTTP2::END_STREAM)
+      end
+    end
+
     # Drain bytes off the per-connection send queue onto the real socket.
     # This fiber is the SOLE writer to `socket` for the connection's
     # lifetime, which satisfies SSLSocket's "no concurrent writes from

data/lib/hyperion/metrics.rb

@@ -113,6 +113,44 @@ module Hyperion
       increment(:"responses_#{code}")
     end
 
+    # 2.12-E — labeled counter family that observes which worker
+    # process a given request landed on. Ticks once per dispatched
+    # request from every dispatch shape (Connection#serve, h2 streams,
+    # the C accept4 + io_uring loops; see PrometheusExporter for the
+    # C-loop fold-in at scrape time).
+    #
+    # `worker_id` is conventionally `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 distribution rows with `ps`/`/proc` data
+    # without a separate worker_id <-> pid mapping table.
+    #
+    # Hot-path cost: one `@hg_mutex` acquisition per tick. That's
+    # acceptable for the audit metric: contention shows up only on
+    # the `tick + render` overlap, never inside the C accept loop
+    # (which uses its own atomic counter folded in at scrape time).
+    # Worth the simplicity over an extra lock-free per-thread cache.
+    REQUESTS_DISPATCH_TOTAL = :hyperion_requests_dispatch_total
+    WORKER_ID_LABEL_KEYS = %w[worker_id].freeze
+
+    def tick_worker_request(worker_id)
+      label = worker_id.nil? || worker_id.to_s.empty? ? '0' : worker_id.to_s
+      ensure_worker_request_family_registered!
+      increment_labeled_counter(REQUESTS_DISPATCH_TOTAL, [label])
+    end
+
+    # 2.12-E — Idempotently register the labeled-counter family. Public
+    # so `Server#run_c_accept_loop` can register at boot — the
+    # PrometheusExporter's C-loop fold-in is gated on the family being
+    # in the snapshot, and a 100% C-loop worker never goes through
+    # `tick_worker_request` to register lazily.
+    def ensure_worker_request_family_registered!
+      return if @worker_request_family_registered
+
+      register_labeled_counter(REQUESTS_DISPATCH_TOTAL, label_keys: WORKER_ID_LABEL_KEYS)
+      @worker_request_family_registered = true
+    end
+
     def snapshot
       result = Hash.new(0)
       counters_snapshot = @counters_mutex.synchronize { @thread_counters.dup }