hyperion-rb 1.6.1 → 2.10.1

data/lib/hyperion/http2/native_hpack_adapter.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative '../h2_codec'
+
+module Hyperion
+  module Http2
+    # Phase 10 (RFC §3 Phase 6c, 2.2.0) — adapter shim that exposes the
+    # Rust HPACK encoder/decoder behind the same call surface
+    # `protocol-http2`'s connection uses today (`#encode_headers(headers)`
+    # → bytes, `#decode_headers(bytes)` → array of [name, value]).
+    #
+    # The adapter is constructed once per HTTP/2 connection, holds an
+    # `Hyperion::H2Codec::Encoder` and `Decoder` (each owns its own RFC 7541
+    # dynamic table), and is consulted only from the encode/decode
+    # serialization point inside `protocol-http2::Connection`. The framer,
+    # stream state machine, flow control, and HEADERS/CONTINUATION
+    # framing all stay in `protocol-http2` — Phase 10's scope is the
+    # HPACK byte-pump only. Replacing the framer in Rust is left for a
+    # future Phase 6d.
+    #
+    # When `Hyperion::H2Codec.available?` is false (no Rust toolchain at
+    # gem install, ABI mismatch, JRuby, etc.) callers MUST NOT
+    # construct `NativeHpackAdapter` — the substitution layer in
+    # `Http2Handler#build_server` skips installation in that case and
+    # the connection keeps using `protocol-http2`'s pure-Ruby
+    # Compressor/Decompressor.
+    #
+    # Headers are passed in/returned as `[[name_string, value_string], …]`
+    # — the same shape `protocol-http2` already uses internally, so the
+    # substitution is byte-for-byte transparent at the protocol-http2
+    # boundary.
+    class NativeHpackAdapter
+      # @raise [RuntimeError] if the native codec isn't loaded.
+      def initialize
+        unless Hyperion::H2Codec.available?
+          raise 'NativeHpackAdapter requires Hyperion::H2Codec.available? — guard at the call site'
+        end
+
+        @encoder = Hyperion::H2Codec::Encoder.new
+        @decoder = Hyperion::H2Codec::Decoder.new
+      end
+
+      # Encode a header block via the native HPACK encoder. The
+      # encoder's dynamic table persists across calls (HPACK is
+      # stateful per direction per connection), so two HEADERS frames
+      # encoded back-to-back on the same adapter share table state
+      # exactly as RFC 7541 requires.
+      #
+      # @param headers [Array<Array(String, String)>]
+      # @param buffer [String] optional output buffer; bytes are
+      #   appended so the Rust encoder's output appends to whatever
+      #   the caller already accumulated. Returned for chaining.
+      # @return [String] the buffer (with newly-encoded bytes appended).
+      def encode_headers(headers, buffer = String.new.b)
+        bytes = @encoder.encode(headers)
+        buffer << bytes
+        buffer
+      end
+
+      # Decode a HEADERS/CONTINUATION block via the native HPACK
+      # decoder. Updates the decoder's dynamic table.
+      #
+      # @param data [String] the wire bytes for one header block.
+      # @return [Array<Array(String, String)>]
+      def decode_headers(data)
+        @decoder.decode(data)
+      end
+    end
+  end
+end

data/lib/hyperion/http2_handler.rb

@@ -6,6 +6,8 @@ require 'protocol/http2/server'
 require 'protocol/http2/framer'
 require 'protocol/http2/stream'
 
+require_relative 'http2/native_hpack_adapter'
+
 module Hyperion
   # Real HTTP/2 dispatch driven by `protocol-http2`.
   #
@@ -132,6 +134,11 @@ module Hyperion
     # Single instance per connection, lives for the lifetime of `serve`.
     class WriterContext
       attr_reader :encode_mutex
+      # 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
+      # once per connection. nil = unset, set on first observation.
+      attr_accessor :t0_serve_entry, :t1_preface_done, :t2_first_encode, :t2_first_wire
 
       def initialize(max_pending_bytes: MAX_PER_CONN_PENDING_BYTES)
         @queue              = ::Thread::Queue.new
@@ -142,6 +149,12 @@ module Hyperion
         @pending_bytes_lock = ::Mutex.new
         @max_pending_bytes  = max_pending_bytes
         @writer_done        = false
+        # 2.10-G timing slots, all initially nil so capture is a single
+        # `||=` write under the encode mutex / writer fiber.
+        @t0_serve_entry  = nil
+        @t1_preface_done = nil
+        @t2_first_encode = nil
+        @t2_first_wire   = nil
       end
 
       # Called by SendQueueIO#write on the calling (encoder) fiber. Enforces
@@ -412,12 +425,171 @@ module Hyperion
     # MAXIMUM_ALLOWED_WINDOW_SIZE).
     H2_MAX_WINDOW_SIZE = 0x7FFFFFFF
 
-    def initialize(app:, thread_pool: nil, h2_settings: nil)
-      @app         = app
-      @thread_pool = thread_pool
-      @h2_settings = h2_settings
-      @metrics     = Hyperion.metrics
-      @logger      = Hyperion.logger
+    # 1.7.0 added kwargs:
+    #   * `runtime:`      — `Hyperion::Runtime` for metrics/logger
+    #                       isolation (default `Runtime.default`).
+    #   * `h2_admission:` — Optional `Hyperion::H2Admission` for the
+    #                       per-process stream cap (RFC A7). nil keeps
+    #                       the 1.6.x unbounded behaviour.
+    #
+    # 2.0.0 (Phase 6b) probed `Hyperion::H2Codec.available?` at
+    # construction so the handler knew whether the native HPACK path
+    # was operational, but the connection state machine still drove
+    # encode/decode through `protocol-http2`'s pure-Ruby Compressor /
+    # Decompressor.
+    #
+    # 2.2.0 (Phase 10 / RFC §3 Phase 6c) ships the wiring infrastructure:
+    # {Hyperion::Http2::NativeHpackAdapter} + {#install_native_hpack}
+    # replace the per-connection HPACK encode/decode boundary with
+    # the Rust crate when AND ONLY WHEN both:
+    #   1. `Hyperion::H2Codec.available?` is true (cdylib loaded), AND
+    #   2. `ENV['HYPERION_H2_NATIVE_HPACK']` is one of `1`/`true`/`yes`/`on`.
+    #
+    # The default is OFF because local h2load benchmarking on macOS
+    # showed the Fiddle FFI per-call marshalling overhead dominates
+    # for typical 3–8-header HEADERS frames — the standalone microbench's
+    # 3.26× encode win does not translate to wire wins until the FFI
+    # marshalling layer is rewritten to amortize allocation. Keeping the
+    # default OFF preserves 2.0.0/2.1.0 behavior; flipping the env var
+    # gives operators the swap they want to A/B test in their own env.
+    # The framer + stream state machine + flow control + HEADERS /
+    # CONTINUATION framing all stay in `protocol-http2`; only the
+    # HPACK byte-pump is replaced when the swap is enabled. Frame ser/de
+    # in Rust (Phase 6d) is a separate, larger lift.
+    def initialize(app:, thread_pool: nil, h2_settings: nil, runtime: nil, h2_admission: nil)
+      @app          = app
+      @thread_pool  = thread_pool
+      @h2_settings  = h2_settings
+      if runtime
+        @runtime = runtime
+        @metrics = runtime.metrics
+        @logger  = runtime.logger
+      else
+        # 1.6.x compat path — see Connection#initialize for rationale.
+        @runtime = Hyperion::Runtime.default
+        @metrics = Hyperion.metrics
+        @logger  = Hyperion.logger
+      end
+      @h2_admission       = h2_admission
+      @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
+      # bench (`bench/h2_rails_shape.ru`, 25 response headers) measured
+      # native v3 at 1,418 r/s vs Ruby fallback 1,201 r/s — **+18.0%**
+      # on a header-heavy workload, comfortably above the +15% flip
+      # threshold. 2.4-A's hello-shape bench saw parity because HPACK
+      # is <1% of per-stream CPU on a 2-header response.
+      #
+      # 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.
+      #
+      # 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_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:
+      #
+      #   t0 — entry to `serve` (post-TLS, post-ALPN — the socket is already
+      #        the negotiated h2 SSLSocket by the time the handler sees it)
+      #   t1 — `read_connection_preface` returned (server-side SETTINGS
+      #        encoded + handed to the framer; client preface fully read)
+      #   t2_encode — first stream's HEADERS frame finished encoding (bytes
+      #               sit in the writer queue)
+      #   t2_wire   — writer fiber finished its first `socket.write` (bytes
+      #               on the wire)
+      #
+      # When the connection's first response completes, the handler emits
+      # a single `'h2 first-stream timing'` info line with t0→t1, t1→t2_encode,
+      # t2_encode→t2_wire deltas in milliseconds. Off by default (zero hot-path
+      # 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')
+      record_codec_boot_state
+    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)
+      v = ENV[name]
+      return false if v.nil? || v.empty?
+
+      %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
+      v = ENV['HYPERION_H2_NATIVE_HPACK']
+      return true if v.nil? || v.empty?
+
+      lc = v.downcase
+      return false if %w[0 false no off].include?(lc)
+
+      true
+    end
+
+    # 2.0.0 Phase 6b: emit a single-shot boot log line per process
+    # describing the codec selection. Operators reading the boot log
+    # see whether the native HPACK path is in play. Idempotent across
+    # multiple Http2Handler constructions in the same process.
+    def record_codec_boot_state
+      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
+      @logger.info do
+        {
+          message: 'h2 codec selected',
+          mode: mode,
+          native_available: @h2_codec_available,
+          native_enabled: @h2_native_hpack_enabled,
+          cglue_active: cglue_active,
+          hpack_path: if @h2_native_hpack_enabled
+                        cglue_active ? 'native-v3' : 'native-v2'
+                      else
+                        'pure-ruby'
+                      end
+        }
+      end
+      @metrics.increment(:h2_codec_native_selected) if @h2_native_hpack_enabled
+      @metrics.increment(:h2_codec_fallback_selected) unless @h2_native_hpack_enabled
+    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
+    # wire the native adapter onto every new connection's
+    # `encode_headers` / `decode_headers` boundary. The 2.2.0 default
+    # is false (opt-in) — see `#initialize` for the rationale and the
+    # bench numbers in CHANGELOG/docs that pinned the default off.
+    def codec_native?
+      @h2_native_hpack_enabled
+    end
+
+    # True when the Rust crate loaded successfully, regardless of
+    # whether the operator opted in to wiring it into the wire path.
+    # Useful for diagnostics/health endpoints that want to surface
+    # "native is available but currently disabled".
+    def codec_available?
+      @h2_codec_available
     end
 
     def serve(socket)
@@ -431,6 +603,11 @@ module Hyperion
       framer       = ::Protocol::HTTP2::Framer.new(send_io)
       server       = build_server(framer)
 
+      # 2.10-G — connection entry timestamp. Captured before any framing
+      # work so the t0→t1 delta isolates "preface exchange + initial
+      # SETTINGS round-trip" from any pre-handler scheduling delay.
+      writer_ctx.t0_serve_entry = monotonic_now if @h2_timing_enabled
+
       task = ::Async::Task.current
 
       # Spawn the dedicated writer fiber BEFORE the preface exchange.
@@ -442,6 +619,7 @@ module Hyperion
       writer_task = task.async { run_writer_loop(socket, writer_ctx) }
 
       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)
@@ -504,6 +682,12 @@ module Hyperion
         rescue StandardError
           nil
         end
+        # 2.10-G — emit one info-level timing line per connection when the
+        # opt-in instrumentation is enabled and we collected a full set of
+        # samples (a connection that died before serving any stream lacks
+        # t2_first_encode / t2_first_wire and gets skipped — there's no
+        # first-stream signal to report).
+        log_h2_first_stream_timing(writer_ctx) if @h2_timing_enabled
       end
       @metrics.decrement(:connections_active)
       socket.close unless socket.closed?
@@ -576,6 +760,7 @@ module Hyperion
 
     def build_server(framer)
       server = ::Protocol::HTTP2::Server.new(framer)
+      install_native_hpack(server) if @h2_native_hpack_enabled
       server.define_singleton_method(:accept_stream) do |stream_id, &block|
         unless valid_remote_stream_id?(stream_id)
           raise ::Protocol::HTTP2::ProtocolError, "Invalid stream id: #{stream_id}"
@@ -590,6 +775,53 @@ module Hyperion
       server
     end
 
+    # Phase 10 (Phase 6c): swap the per-connection HPACK encode/decode
+    # entry points to route through the Rust crate. We replace
+    # `encode_headers` / `decode_headers` on the `Protocol::HTTP2::Server`
+    # instance via singleton methods — protocol-http2's framer + stream
+    # state machine call `connection.encode_headers(headers, buffer)` and
+    # `connection.decode_headers(data)` whenever HEADERS / CONTINUATION
+    # frames cross the wire, so this is exactly the boundary where the
+    # native codec slots in. The adapter holds one Encoder + one Decoder
+    # for this connection; their dynamic tables persist across all
+    # HEADERS frames in their respective directions, matching RFC 7541's
+    # per-direction HPACK context model.
+    #
+    # The Ruby `@encoder` / `@decoder` Context ivars on the
+    # `Protocol::HTTP2::Connection` superclass remain in place but are
+    # never consulted — the singleton-method overrides shortcut past
+    # them. That's safe: protocol-http2 only touches those Contexts
+    # through `encode_headers` / `decode_headers`, which we now own.
+    #
+    # If the substitution surface ever shifts in protocol-http2 (e.g.
+    # a future version inlines the call), this method becomes a no-op
+    # safely — `define_singleton_method` doesn't fail when the parent
+    # method is absent, but downstream calls would. The codec-boot log
+    # makes the substitution observable, so a regression would surface
+    # quickly via the integration spec.
+    def install_native_hpack(server)
+      adapter = Hyperion::Http2::NativeHpackAdapter.new
+      server.define_singleton_method(:encode_headers) do |headers, buffer = String.new.b|
+        adapter.encode_headers(headers, buffer)
+      end
+      server.define_singleton_method(:decode_headers) do |data|
+        adapter.decode_headers(data)
+      end
+      # Stash the adapter so introspection (and the encode-mutex synchronisation
+      # boundary, since adapter state is mutated under it) can reach it.
+      server.instance_variable_set(:@hyperion_native_hpack, adapter)
+      adapter
+    rescue StandardError => e
+      # Defence in depth: if the adapter ctor fails for any reason, log and
+      # fall back to protocol-http2's Ruby Compressor/Decompressor. Better
+      # than crashing the connection on first HEADERS frame.
+      @logger.warn do
+        { message: 'h2 native hpack install failed; falling back to Ruby HPACK',
+          error: e.class.name, detail: e.message }
+      end
+      nil
+    end
+
     def dispatch_stream(stream, writer_ctx, peer_addr = nil)
       # RFC 7540 §8.1.2 — header validation flagged this stream as malformed.
       # Send RST_STREAM PROTOCOL_ERROR instead of invoking the app.
@@ -608,6 +840,25 @@ module Hyperion
         return
       end
 
+      # RFC A7: process-wide stream admission control. nil admission =
+      # unbounded (current behaviour). When the cap is hit we send
+      # REFUSED_STREAM (RFC 7540 §11 / RFC 9113 §5.4.1) — the spec-
+      # defined response for "this stream cannot be processed; client
+      # may retry on a different stream id". Bumps a counter so
+      # operators can alert on sustained refusal volume.
+      if @h2_admission && !@h2_admission.admit
+        @metrics.increment(:h2_streams_refused)
+        begin
+          writer_ctx.encode_mutex.synchronize do
+            stream.send_reset_stream(::Protocol::HTTP2::Error::REFUSED_STREAM) unless stream.closed?
+          end
+        rescue StandardError
+          nil
+        end
+        return
+      end
+      @h2_admission.nil?
+
       pseudo, regular = partition_pseudo(stream.request_headers)
 
       method    = pseudo[':method'] || 'GET'
@@ -630,11 +881,24 @@ module Hyperion
 
       @metrics.increment(:requests_total)
       @metrics.increment(:requests_in_flight)
+      # 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,
+      # :protocol pseudo-header, and stream lifetime semantics. The
+      # 2.1.0 scope is HTTP/1.1 hijack only (env['rack.hijack?'] returns
+      # false on h2 streams because we don't pass `connection:` here).
+      # If a Rack app keys on rack.hijack? to choose a transport, the h2
+      # branch will fall through to its non-hijack path. See WS-2..WS-5
+      # for the full WebSocket roadmap.
       status, response_headers, body_chunks = begin
         if @thread_pool
           @thread_pool.call(@app, request)
         else
-          Hyperion::Adapter::Rack.call(@app, request)
+          # 2.5-C — pass the handler's Runtime so per-request hooks
+          # fire on h2 streams too. Multi-tenant deployments rely on
+          # this to keep tracing context per-server even on the h2
+          # path that doesn't go through Connection#call_app.
+          Hyperion::Adapter::Rack.call(@app, request, runtime: @runtime)
         end
       ensure
         @metrics.decrement(:requests_in_flight)
@@ -655,8 +919,27 @@ module Hyperion
       body_chunks.each { |c| payload << c.to_s }
       body_chunks.close if body_chunks.respond_to?(:close)
 
-      writer_ctx.encode_mutex.synchronize { stream.send_headers(out_headers) }
-      send_body(stream, payload, writer_ctx)
+      # Hotfix C2: empty-body responses (RFC 7230 §3.3.3 — 204/304 + HEAD)
+      # MUST NOT carry a DATA frame. Folding END_STREAM onto the HEADERS
+      # frame collapses the response to one encoder-mutex acquisition and
+      # 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).
+      if body_suppressed?(method, status)
+        writer_ctx.encode_mutex.synchronize do
+          stream.send_headers(out_headers, ::Protocol::HTTP2::END_STREAM)
+        end
+      else
+        writer_ctx.encode_mutex.synchronize { stream.send_headers(out_headers) }
+        send_body(stream, payload, writer_ctx)
+      end
+      # 2.10-G — first stream's HEADERS+DATA encoded. Capture exactly once
+      # per connection (use ||= under the encode mutex's freshly-released
+      # write so concurrent stream fibers race lose-race once). For h2load
+      # `-c 1 -m 100 -n 5000` the first stream is stream id 1, the only
+      # one that pays the connection-setup cost; later streams skip this
+      # branch via the `||=`.
+      writer_ctx.t2_first_encode = monotonic_now if @h2_timing_enabled && writer_ctx.t2_first_encode.nil?
       @metrics.increment_status(status)
     rescue StandardError => e
       @metrics.increment(:app_errors)
@@ -675,6 +958,26 @@ module Hyperion
       rescue StandardError
         nil
       end
+    ensure
+      # Release the admission slot once the stream's served (success or
+      # error). h2_admitted is local-set above the slot acquisition, so
+      # the protocol-error / pre-admission early-returns above don't
+      # double-release.
+      @h2_admission.release if defined?(h2_admitted) && h2_admitted
+    end
+
+    # RFC 7230 §3.3.3: status codes that prohibit a response body, plus
+    # the HEAD method which always suppresses the body regardless of what
+    # the application returned. The h2 dispatch path uses this to fold
+    # END_STREAM onto the HEADERS frame and skip the DATA-frame write
+    # entirely (see Hotfix C2).
+    BODY_SUPPRESSED_STATUSES = [204, 304].freeze
+
+    def body_suppressed?(method, status)
+      return true if BODY_SUPPRESSED_STATUSES.include?(status)
+      return true if method == 'HEAD'
+
+      false
     end
 
     # Send the response body, respecting the peer's max frame size and
@@ -731,6 +1034,13 @@ module Hyperion
         while (chunk = writer_ctx.try_pop)
           begin
             socket.write(chunk)
+            # 2.10-G — first byte on the wire. Capture exactly once per
+            # connection (the first chunk drained is the server's
+            # connection-preface SETTINGS frame; we want the t1→t2_wire
+            # delta to bracket "preface bytes encoded → preface bytes on
+            # the socket". The expensive HEADERS+DATA enqueue happens
+            # later under t2_first_encode.)
+            writer_ctx.t2_first_wire = monotonic_now if @h2_timing_enabled && writer_ctx.t2_first_wire.nil?
           rescue EOFError, Errno::ECONNRESET, Errno::EPIPE, IOError, OpenSSL::SSL::SSLError
             # Peer hung up. Release THIS chunk's byte budget, then drain the
             # rest of the queue (without writing) so backpressured encoders
@@ -775,6 +1085,55 @@ module Hyperion
       end
     end
 
+    # 2.10-G — small helper so the four timing call sites in `serve`,
+    # `dispatch_stream`, and `run_writer_loop` agree on the clock source.
+    # CLOCK_MONOTONIC is unaffected by NTP jumps and is what the rest of
+    # the gem uses for elapsed-time math (see Connection#serve).
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # 2.10-G — assemble + emit the per-connection timing breakdown that
+    # the bench harness greps for. Three deltas are reported in
+    # milliseconds:
+    #
+    #   t0_to_t1_ms     — preface exchange (read client preface + write
+    #                     server SETTINGS into the framer queue)
+    #   t1_to_t2_enc_ms — gap between preface complete and first stream's
+    #                     HEADERS+DATA encoded. If this is the dominant
+    #                     bucket, the framer-fiber priming / first-stream
+    #                     scheduling is the suspect.
+    #   t2_enc_to_t2_wire_ms — encode-complete to writer drained first
+    #                          chunk on the wire. Should be near-zero on
+    #                          a healthy connection (writer fiber is
+    #                          already running, parked on @send_notify).
+    #                          A large value here = writer-fiber
+    #                          starvation under the Async scheduler.
+    #
+    # Skipped when any timestamp is missing (connection died before
+    # serving a stream / instrumentation was disabled mid-flight).
+    def log_h2_first_stream_timing(writer_ctx)
+      t0 = writer_ctx.t0_serve_entry
+      t1 = writer_ctx.t1_preface_done
+      t2_enc  = writer_ctx.t2_first_encode
+      t2_wire = writer_ctx.t2_first_wire
+      return if t0.nil? || t1.nil? || t2_enc.nil? || t2_wire.nil?
+
+      @logger.info do
+        {
+          message: 'h2 first-stream timing',
+          t0_to_t1_ms: ((t1 - t0) * 1000).round(3),
+          t1_to_t2_enc_ms: ((t2_enc - t1) * 1000).round(3),
+          t2_enc_to_t2_wire_ms: ((t2_wire - t2_enc) * 1000).round(3),
+          t0_to_t2_wire_ms: ((t2_wire - t0) * 1000).round(3)
+        }
+      end
+    rescue StandardError
+      # Logging the timing breakdown must never crash the connection
+      # teardown path — instrumentation is best-effort.
+      nil
+    end
+
     # Mirrors Connection#peer_address — see the comment there. SSLSocket
     # wraps a TCPSocket; both expose #peeraddr after handshake.
     def peer_address(socket)