Class: Hyperion::Http2Handler

Inherits:
Object
  • Object
show all
Defined in:
lib/hyperion/http2_handler.rb

Overview

Real HTTP/2 dispatch driven by ‘protocol-http2`.

Each TLS connection that negotiated ‘h2` via ALPN ends up here. We frame the socket, read the connection preface, and then drive a frame loop on the connection’s fiber: it reads one frame at a time and lets ‘protocol-http2` update its connection/stream state machines. As soon as a client stream finishes its request half (state `:half_closed_remote` via `end_stream?`), we hand the stream off to a sibling fiber for dispatch — slow handlers no longer block other streams on the same connection.

## Outbound write architecture (1.6.0+)

Pre-1.6.0 every framer write (HEADERS / DATA / RST_STREAM / GOAWAY) ran under one connection-scoped ‘Mutex#synchronize { socket.write(…) }`. That capped per-connection h2 throughput to “one socket-write at a time” regardless of stream count: a slow socket (kernel send buffer full, remote peer reading slowly) blocked every other stream’s writes too.

1.6.0 splits the path:

* The HPACK encode + frame format step is fast (microseconds, in-memory)
  and remains serialized on the calling fiber via `@encode_mutex`. HPACK
  state is stateful across HEADERS frames per connection, and frames for
  a single stream must be wire-ordered (HEADERS → DATA → END_STREAM).
  Holding the encode mutex across a `send_*` call accomplishes both.
* The framer writes through a `SendQueueIO` wrapper (wraps the real
  socket). `SendQueueIO#write(bytes)` enqueues onto a connection-wide
  `@send_queue` and signals `@send_notify`; it never touches the real
  socket.
* A dedicated **writer fiber** owns the real socket. It pops byte chunks
  off the queue, writes them, and parks on `@send_notify` when empty.
  Only this fiber ever calls `socket.write` — the SSLSocket cross-fiber
  unsafety constraint is satisfied.

Net effect: the slow-socket case no longer serializes encode work across streams. A stream that has bytes ready to encode can encode and enqueue while the writer is mid-flush of an earlier chunk. The mutex hold time drops from “until the kernel accepts the write” to “until the bytes are appended to the in-memory queue.”

Backpressure: pathological clients (slow-read h2) could otherwise let the queue grow without bound. We track ‘@pending_bytes`; once it exceeds `MAX_PER_CONN_PENDING_BYTES`, encoding fibers wait on `@drained_notify` before enqueueing more. The writer signals `@drained_notify` after each drain pass.

Flow control: ‘RequestStream#window_updated` overrides the protocol-http2 default to fan a notification out to any fiber blocked in `send_body` waiting for the remote peer’s flow-control window to grow. The body writer chunks the response payload by the per-stream available frame size and yields on the notification when the window is exhausted, so large bodies never trip a FlowControlError.

Defined Under Namespace

Classes: RequestStream, SendQueueIO, WriterContext

Constant Summary collapse

MAX_PER_CONN_PENDING_BYTES =

Cap on bytes that may sit in a connection’s send queue waiting for the writer fiber to drain. Slow-read h2 clients can otherwise let an encoder fiber pile arbitrary bytes into RAM. 16 MiB matches the upper bound a well-behaved peer will buffer — anything beyond that is the writer being starved, and the right answer is to backpressure the encoder rather than allocate more.

16 * 1024 * 1024
SETTINGS_KEY_MAP =

Maps Hyperion-friendly setting names to the integer SETTINGS_* identifiers protocol-http2 uses on the wire. See RFC 7540 §6.5.2 — these are the only four parameters Hyperion exposes; the rest of the SETTINGS frame (HEADER_TABLE_SIZE, ENABLE_PUSH, etc.) keeps protocol-http2’s default.

{
  max_concurrent_streams: ::Protocol::HTTP2::Settings::MAXIMUM_CONCURRENT_STREAMS,
  initial_window_size: ::Protocol::HTTP2::Settings::INITIAL_WINDOW_SIZE,
  max_frame_size: ::Protocol::HTTP2::Settings::MAXIMUM_FRAME_SIZE,
  max_header_list_size: ::Protocol::HTTP2::Settings::MAXIMUM_HEADER_LIST_SIZE
}.freeze
H2_MIN_FRAME_SIZE =

RFC 7540 §6.5.2 floor for SETTINGS_MAX_FRAME_SIZE. protocol-http2 raises ProtocolError on values below this; we clamp + warn instead so a misconfigured operator gets a working server, not a boot-time crash.

0x4000
H2_MAX_FRAME_SIZE =

RFC 7540 §6.5.2 ceiling for SETTINGS_MAX_FRAME_SIZE.

0xFFFFFF
H2_MAX_WINDOW_SIZE =

RFC 7540 §6.9.2 — INITIAL_WINDOW_SIZE has the same 31-bit max as the WINDOW_UPDATE frame’s Window Size Increment (see protocol-http2’s MAXIMUM_ALLOWED_WINDOW_SIZE).

0x7FFFFFFF
DISPATCH_POOL_DEFAULT =

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.

4
DISPATCH_POOL_MAX = 
16

Instance Method Summary collapse

Constructor Details

#initialize(app:, thread_pool: nil, h2_settings: nil, runtime: nil, h2_admission: nil) ⇒ Http2Handler

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.



503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
 
# File 'lib/hyperion/http2_handler.rb', line 503

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
  # 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
  # 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.
  #
  # 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 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_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:
  #
  #   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')
  # 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

Instance Method Details

#apply_h2_cglue_gate(state) ⇒ Object

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.



645
646
647
 
# File 'lib/hyperion/http2_handler.rb', line 645

def apply_h2_cglue_gate(state)
  Hyperion::H2Codec.cglue_disabled = (state == :v2)
end

#codec_available? ⇒ Boolean

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”.

Returns:

  • (Boolean) 


738
739
740
 
# File 'lib/hyperion/http2_handler.rb', line 738

def codec_available?
  @h2_codec_available
end

#codec_native? ⇒ Boolean

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.

Returns:

  • (Boolean) 


730
731
732
 
# File 'lib/hyperion/http2_handler.rb', line 730

def codec_native?
  @h2_native_hpack_enabled
end

#describe_codec_mode(cglue_active:, cglue_requested_unavailable:) ⇒ Object

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).



698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
 
# File 'lib/hyperion/http2_handler.rb', line 698

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

#env_flag_enabled?(name) ⇒ Boolean

Read an env-var flag with the usual truthiness rules (any of 1/true/yes/on, case-insensitive). Anything else → false.

Returns:

  • (Boolean) 


604
605
606
607
608
609
 
# File 'lib/hyperion/http2_handler.rb', line 604

def env_flag_enabled?(name)
  v = ENV[name]
  return false if v.nil? || v.empty?

  %w[1 true yes on].include?(v.downcase)
end

#record_codec_boot_state ⇒ Object

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.



653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
 
# File 'lib/hyperion/http2_handler.rb', line 653

def record_codec_boot_state
  return if Hyperion::Http2Handler.instance_variable_get(:@codec_state_logged)

  Hyperion::Http2Handler.instance_variable_set(:@codec_state_logged, true)
  # 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'
                  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

#resolve_dispatch_pool_size ⇒ Object 



590
591
592
593
594
595
596
597
598
599
600
 
# File 'lib/hyperion/http2_handler.rb', line 590

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

#resolve_h2_native_hpack_state ⇒ Object

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`.



628
629
630
631
632
633
634
635
636
637
638
 
# File 'lib/hyperion/http2_handler.rb', line 628

def resolve_h2_native_hpack_state
  v = ENV['HYPERION_H2_NATIVE_HPACK']
  return :auto if v.nil? || v.empty?

  lc = v.downcase
  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

#serve(socket) ⇒ Object 



742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
 
# File 'lib/hyperion/http2_handler.rb', line 742

def serve(socket)
  @metrics.increment(:connections_accepted)
  @metrics.increment(:connections_active)

  # Per-connection outbound coordination. Encoder fibers enqueue bytes;
  # the writer fiber owns the real socket and drains. See class docstring.
  writer_ctx   = WriterContext.new
  send_io      = SendQueueIO.new(socket, writer_ctx)
  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

  # 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
  # queue. Spawning first guarantees they flush as soon as the scheduler
  # ticks, avoiding any pathological deadlock where a client implementation
  # 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

  # 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 = []
    server.read_frame do |frame|
      ready_ids << frame.stream_id if frame.stream_id.positive?
    end

    ready_ids.uniq.each do |sid|
      stream = server.streams[sid]
      next unless stream.is_a?(RequestStream)
      next unless stream.request_complete
      next if stream.closed?
      next if stream.instance_variable_get(:@hyperion_dispatched)

      # Mark before spawning so we never dispatch the same stream twice
      # if subsequent frames (e.g. RST_STREAM races) arrive.
      stream.instance_variable_set(:@hyperion_dispatched, true)

      # 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.
  overflow_tasks.each do |t|
    t.wait
  rescue StandardError
    nil
  end
rescue EOFError, Errno::ECONNRESET, Errno::EPIPE, IOError, OpenSSL::SSL::SSLError
  # Peer disconnect — nothing to do.
rescue ::Protocol::HTTP2::GoawayError, ::Protocol::HTTP2::ProtocolError, ::Protocol::HTTP2::HandshakeError
  # Protocol-level error — protocol-http2 has already emitted GOAWAY.
rescue StandardError => e
  @logger.error do
    {
      message: 'h2 connection error',
      error: e.message,
      error_class: e.class.name,
      backtrace: (e.backtrace || []).first(10).join(' | ')
    }
  end
ensure
  # Coordinated shutdown: flag the writer, signal it, wait for the final
  # drain, then close the real socket. Order matters — closing the
  # 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
    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?
end