hyperion-rb 2.11.0 → 2.13.0

data/lib/hyperion/metrics.rb

@@ -79,6 +79,30 @@ module Hyperion
       # Snapshot block hooks for gauges whose value is read on demand
       # (ThreadPool queue depth, etc.). `{ name => { labels_tuple => Proc } }`.
       @gauge_blocks    = {}
+
+      # 2.13-A — per-thread shards for the hot-path metrics that USED to
+      # take @hg_mutex on every observe / increment. The pre-2.13-A
+      # comment in `increment_labeled_counter` claimed those paths were
+      # "low-rate" — that turned out to be wrong: `tick_worker_request`
+      # fires once per Rack request, and `observe_histogram` fires once
+      # per request via the per-route duration histogram. Under -t 32
+      # the single mutex serialised every worker thread on the
+      # request-completion tail. Per-thread shards remove the
+      # contention; snapshots merge across threads under the mutex
+      # (snapshot is a low-rate operation — once per /-/metrics scrape).
+      #
+      # Thread-variable storage (NOT Thread.current[]) for the same
+      # reason as the unlabeled counter path: under an Async scheduler
+      # `Thread.current[:k]` is fiber-local, which would let snapshots
+      # miss observations made on a fiber that already exited.
+      @hg_thread_key   = :"__hyperion_metrics_hg_#{object_id}__"
+      @lc_thread_key   = :"__hyperion_metrics_lc_#{object_id}__"
+      # Holds direct references to every per-thread shard ever
+      # allocated through this Metrics instance (mirrors @thread_counters)
+      # so snapshots survive thread death.
+      @thread_histograms = []
+      @thread_labeled_counters = []
+      @hg_thread_mutex         = Mutex.new
     end
 
     # Hot path: one thread-variable lookup + one hash op. No mutex on the
@@ -113,6 +137,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 }
@@ -124,6 +186,12 @@ module Hyperion
     end
 
     # Tests can call .reset! between examples to avoid cross-spec leakage.
+    #
+    # 2.13-A — also clear per-thread histogram and labeled-counter
+    # shards. Without this, an observation made on thread A in spec X
+    # would leak into spec Y's snapshot because the shard hashes are
+    # held alive by `@thread_histograms` / `@thread_labeled_counters`
+    # for the lifetime of the Metrics instance.
     def reset!
       @counters_mutex.synchronize do
         @thread_counters.each(&:clear)
@@ -133,6 +201,10 @@ module Hyperion
         @gauges.each_value(&:clear)
         @gauge_blocks.each_value(&:clear)
       end
+      @hg_thread_mutex.synchronize do
+        @thread_histograms.each(&:clear)
+        @thread_labeled_counters.each(&:clear)
+      end
     end
 
     # ---- 2.4-C histogram + gauge API ---------------------------------
@@ -159,27 +231,37 @@ module Hyperion
 
     # Observe `value` on a previously-registered histogram. `label_values`
     # MUST be supplied in the same order as `label_keys` at registration.
-    # The hot path: one Hash lookup, one accumulator update under a mutex.
-    # Allocation footprint per observe: zero on the cached-key path
-    # (same labels seen before); one frozen Array on first observation
-    # for a given label-set.
+    #
+    # 2.13-A — Hot-path lock-free shard. Each thread keeps its own
+    # `{ name => { labels => HistogramAccumulator } }` map; observations
+    # never block on `@hg_mutex`. Snapshots merge across threads under
+    # the mutex (low-rate). Allocation footprint per observe: zero on
+    # the cached-key path; one frozen Array + one HistogramAccumulator
+    # on first observation for a given (name, label-set, thread).
+    #
+    # Bench impact (generic Rack hello, -t 32 -c 100):
+    # contention on `@hg_mutex` was the dominant tail latency
+    # contributor — this fires once per request via the per-route
+    # request-duration histogram, multiplied by N worker threads.
     def observe_histogram(name, value, label_values = EMPTY_LABELS)
-      @hg_mutex.synchronize do
-        meta = @histograms_meta[name]
-        return unless meta # silently skip unregistered observations
-
-        family = @histograms[name]
-        accum  = family[label_values]
-        unless accum
-          accum = HistogramAccumulator.new(meta[:buckets])
-          # Freeze the label tuple so future identical-content tuples
-          # hash to the same bucket — but we keep the original ref
-          # provided by the caller as the canonical key so subsequent
-          # observes with the same Array bypass the freeze step.
-          family[label_values.frozen? ? label_values : label_values.dup.freeze] = accum
-        end
-        accum.observe(value)
+      meta = @histograms_meta[name]
+      return unless meta # silently skip unregistered observations
+
+      thread = Thread.current
+      shard = thread.thread_variable_get(@hg_thread_key)
+      shard = register_thread_histograms(thread) if shard.nil?
+
+      family = (shard[name] ||= {})
+      accum  = family[label_values]
+      unless accum
+        accum = HistogramAccumulator.new(meta[:buckets])
+        # Freeze the label tuple so future identical-content tuples
+        # hash to the same bucket — but we keep the original ref
+        # provided by the caller as the canonical key so subsequent
+        # observes with the same Array bypass the freeze step.
+        family[label_values.frozen? ? label_values : label_values.dup.freeze] = accum
       end
+      accum.observe(value)
     end
 
     # Set a gauge value. `label_values` follows the same convention as
@@ -225,15 +307,40 @@ module Hyperion
 
     # Snapshot helpers — read-only views of the current histogram /
     # gauge state. The exporter uses these to render the scrape body.
+    #
+    # 2.13-A — Histograms merge across the per-thread shards on the
+    # snapshot path. The mutex is held only long enough to copy the
+    # shard list (every shard Hash is owned by one thread, so we can
+    # iterate its current contents safely while merging — torn reads
+    # of in-progress observations show as a slightly stale snapshot,
+    # never as a corrupted Accumulator).
     def histogram_snapshot
       out = {}
+
+      # Pre-seed names from registered families so a histogram with
+      # zero observations still appears in the scrape (matches the
+      # pre-2.13-A behaviour where `register_histogram` populated the
+      # `@histograms[name] = {}` slot eagerly).
       @hg_mutex.synchronize do
-        @histograms.each do |name, family|
-          per_labels = {}
-          family.each { |labels, accum| per_labels[labels] = accum.snapshot }
-          out[name] = { meta: @histograms_meta[name], series: per_labels }
+        @histograms_meta.each_key { |name| out[name] = { meta: @histograms_meta[name], series: {} } }
+      end
+
+      shards = @hg_thread_mutex.synchronize { @thread_histograms.dup }
+      shards.each do |shard|
+        shard.each do |name, family|
+          slot = (out[name] ||= { meta: @histograms_meta[name], series: {} })
+          series = slot[:series]
+          family.each do |labels, accum|
+            existing = series[labels]
+            if existing.nil?
+              series[labels] = accum.snapshot
+            else
+              merge_histogram_snapshot!(existing, accum)
+            end
+          end
         end
       end
+
       out
     end
 
@@ -271,19 +378,33 @@ module Hyperion
 
     # Labeled counter — separate from the legacy thread-local counter
     # surface (which is unlabeled and per-thread for hot-path
-    # contention-free increments). Labeled counters take a mutex per
-    # increment, but they're called from low-rate paths (per-conn
-    # rejection ~ kHz worst case, vs M+req/s on the unlabeled side)
-    # so the contention cost is invisible.
+    # contention-free increments).
+    #
+    # 2.13-A — moved to a per-thread shard for the same reason as
+    # `observe_histogram`: the previous "low-rate paths" claim was wrong
+    # (`tick_worker_request` is per-Rack-request), and at -t 32 the
+    # single mutex serialised every worker thread on the request-
+    # completion tail. Per-thread shards remove the contention;
+    # `labeled_counter_snapshot` merges shards under the mutex.
     def increment_labeled_counter(name, label_values = EMPTY_LABELS, by = 1)
-      @hg_mutex.synchronize do
-        @labeled_counters_meta ||= {}
-        @labeled_counters_meta[name] ||= { label_keys: [].freeze }
-        @labeled_counters ||= {}
-        family = (@labeled_counters[name] ||= {})
-        key    = label_values.frozen? ? label_values : label_values.dup.freeze
-        family[key] = (family[key] || 0) + by
+      thread = Thread.current
+      shard = thread.thread_variable_get(@lc_thread_key)
+      shard = register_thread_labeled_counters(thread) if shard.nil?
+
+      # Defensive: ensure the family meta exists so `register_labeled_counter`
+      # is not strictly required for hot-path increments. Pre-2.13-A the
+      # mutex'd path lazily registered an unlabeled meta; we mirror that
+      # under @hg_mutex so the shape stays consistent across threads.
+      unless @labeled_counters_meta && @labeled_counters_meta[name]
+        @hg_mutex.synchronize do
+          @labeled_counters_meta ||= {}
+          @labeled_counters_meta[name] ||= { label_keys: [].freeze }
+        end
       end
+
+      family = (shard[name] ||= {})
+      key    = label_values.frozen? ? label_values : label_values.dup.freeze
+      family[key] = (family[key] || 0) + by
     end
 
     def register_labeled_counter(name, label_keys: [])
@@ -295,14 +416,27 @@ module Hyperion
       end
     end
 
+    # 2.13-A — Snapshot merges per-thread shards. Pre-seeded with
+    # `@labeled_counters_meta` so registered-but-unticked families still
+    # show up in the scrape (matches pre-2.13-A behaviour where
+    # `register_labeled_counter` eagerly created the `[name] = {}` slot).
     def labeled_counter_snapshot
       out = {}
       @hg_mutex.synchronize do
-        (@labeled_counters || {}).each do |name, family|
-          per_labels = {}
-          family.each { |labels, count| per_labels[labels] = count }
+        (@labeled_counters_meta || {}).each do |name, meta|
+          out[name] = { meta: meta, series: {} }
+        end
+      end
+
+      shards = @hg_thread_mutex.synchronize { @thread_labeled_counters.dup }
+      shards.each do |shard|
+        shard.each do |name, family|
           meta = (@labeled_counters_meta || {})[name] || { label_keys: [].freeze }
-          out[name] = { meta: meta, series: per_labels }
+          slot = (out[name] ||= { meta: meta, series: {} })
+          series = slot[:series]
+          family.each do |labels, count|
+            series[labels] = (series[labels] || 0) + count
+          end
         end
       end
       out
@@ -354,6 +488,46 @@ module Hyperion
       @counters_mutex.synchronize { @thread_counters << counters }
       counters
     end
+
+    # 2.13-A — allocate this thread's histogram shard and register it
+    # in `@thread_histograms` so snapshots find it. Idempotent per
+    # thread: callers always check `thread_variable_get` first.
+    def register_thread_histograms(thread)
+      shard = {}
+      thread.thread_variable_set(@hg_thread_key, shard)
+      @hg_thread_mutex.synchronize { @thread_histograms << shard }
+      shard
+    end
+
+    # 2.13-A — same shape as register_thread_histograms but for labeled
+    # counters. Each thread gets its own `{ name => { labels => Integer } }`
+    # map; the snapshot path merges across shards.
+    def register_thread_labeled_counters(thread)
+      shard = {}
+      thread.thread_variable_set(@lc_thread_key, shard)
+      @hg_thread_mutex.synchronize { @thread_labeled_counters << shard }
+      shard
+    end
+
+    # 2.13-A — fold a per-thread HistogramAccumulator's contents into an
+    # already-snapshotted entry (`{buckets:, counts:, sum:, count:}`).
+    # Both arguments share the same `:buckets` so the bucket index axis
+    # is identical; we sum `counts` per bucket plus the scalars. Used
+    # when two threads observed the SAME (name, labels) pair — a
+    # legitimate steady state on a Rack route hit by concurrent
+    # workers.
+    def merge_histogram_snapshot!(existing, accum)
+      counts = existing[:counts]
+      acc_counts = accum.counts
+      i = 0
+      len = counts.length
+      while i < len
+        counts[i] += acc_counts[i]
+        i += 1
+      end
+      existing[:sum]   += accum.sum
+      existing[:count] += accum.count
+    end
   end
 end
 

data/lib/hyperion/prometheus_exporter.rb

@@ -74,9 +74,22 @@ module Hyperion
       hyperion_threadpool_queue_depth: {
         help: 'In-flight count in the worker ThreadPool inbox (snapshot at scrape time)',
         type: 'gauge'
+      },
+      # 2.12-E — per-worker request counter for the SO_REUSEPORT
+      # load-balancing audit. One series per worker (label_value =
+      # `Process.pid.to_s`); ticks on every dispatched request from
+      # every dispatch shape. Operators scrape /-/metrics N times in
+      # cluster mode to gather distribution across workers.
+      hyperion_requests_dispatch_total: {
+        help: 'Requests dispatched per worker (PID-labeled), across all dispatch modes',
+        type: 'counter'
       }
     }.freeze
 
+    # 2.12-E — name of the per-worker request counter family. Hoisted to
+    # a constant so the C-loop fold-in below stays declarative.
+    REQUESTS_DISPATCH_TOTAL = :hyperion_requests_dispatch_total
+
     def render(stats)
       buf = +''
       grouped_status = {}
@@ -129,10 +142,72 @@ module Hyperion
       buf << render(metrics_sink.snapshot)
       buf << render_histograms(metrics_sink.histogram_snapshot)
       buf << render_gauges(metrics_sink.gauge_snapshot)
-      buf << render_labeled_counters(metrics_sink.labeled_counter_snapshot)
+      labeled = merge_c_loop_into_dispatch_snapshot(metrics_sink.labeled_counter_snapshot)
+      buf << render_labeled_counters(labeled)
       buf
     end
 
+    # 2.12-E — merge `Hyperion::Http::PageCache.c_loop_requests_total`
+    # (process-global atomic ticked by the C accept4 + io_uring loops)
+    # into the `hyperion_requests_dispatch_total{worker_id=PID}` series
+    # for the current worker. Without this fold-in, a `-w 4` cluster
+    # serving from the C accept loop would scrape zeros from every
+    # worker even though the loop's atomic counter is ticking — the
+    # loop bypasses `Connection#serve`, so no Ruby-side
+    # `tick_worker_request` call ever lands.
+    #
+    # We only fold in when the labeled-counter family is ALREADY in
+    # the snapshot — i.e., something on the Ruby side has called
+    # `Metrics#tick_worker_request` at least once on this sink. The
+    # `Server#run_c_accept_loop` boot path performs a single
+    # registration tick on the runtime's metrics sink so this
+    # condition holds for any production cluster engaging the C loop.
+    #
+    # Why the gate matters: spec fixtures that `Hyperion::Metrics.new`
+    # to assert "empty body when no metrics have been recorded" would
+    # otherwise pull in a process-global atomic bumped by an earlier
+    # spec's C-loop run. Those fixtures never register the family, so
+    # the fold-in skips them cleanly.
+    #
+    # Idempotent on snapshots that already contain a series for the
+    # current PID. Pure on the input — we build a shallow copy of the
+    # snapshot so the live Hash behind `Metrics#labeled_counter_snapshot`
+    # isn't mutated.
+    #
+    # Defensive: when the C ext isn't loaded (JRuby / TruffleRuby) we
+    # silently skip — the snapshot stays Ruby-only.
+    def merge_c_loop_into_dispatch_snapshot(snap)
+      family = snap[REQUESTS_DISPATCH_TOTAL]
+      return snap if family.nil?
+
+      c_loop_count = c_loop_requests_total
+      return snap if c_loop_count <= 0
+
+      pid_label = Process.pid.to_s
+      merged_series = family[:series].dup
+      key = [pid_label].freeze
+      existing_key = merged_series.keys.find { |k| k.first == pid_label } || key
+      merged_series[existing_key] = (merged_series[existing_key] || 0) + c_loop_count
+
+      merged = snap.dup
+      merged[REQUESTS_DISPATCH_TOTAL] = {
+        meta: family[:meta] || { label_keys: %w[worker_id].freeze },
+        series: merged_series
+      }
+      merged
+    end
+
+    def c_loop_requests_total
+      return 0 unless defined?(::Hyperion::Http::PageCache)
+      return 0 unless ::Hyperion::Http::PageCache.respond_to?(:c_loop_requests_total)
+
+      ::Hyperion::Http::PageCache.c_loop_requests_total.to_i
+    rescue StandardError
+      # The scrape path must never raise — observability code degrades
+      # to "no fold-in" rather than failing the metrics endpoint.
+      0
+    end
+
     def render_histograms(snap)
       buf = +''
       snap.each do |name, payload|

data/lib/hyperion/server/connection_loop.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Hyperion
+  class Server
+    # 2.12-C — Connection lifecycle in C.
+    #
+    # Engaged by `Server#start_raw_loop` when ALL of the following hold:
+    #
+    #   * The listener is plain TCP (no TLS, no h2 ALPN dance).
+    #   * The route table has at least one `RouteTable::StaticEntry`
+    #     registration (i.e. `Server.handle_static` was called).
+    #   * The route table has NO non-StaticEntry registrations
+    #     (any `Server.handle(:GET, '/api', dynamic_handler)` disables
+    #     the C path; the C loop only knows how to write prebuilt
+    #     responses).
+    #   * The `HYPERION_C_ACCEPT_LOOP` env knob is not set to `"0"` /
+    #     `"off"` (operator escape hatch for debug).
+    #
+    # On engage, the Ruby accept loop is *not* run for this listener;
+    # `Hyperion::Http::PageCache.run_static_accept_loop` drives the
+    # accept-and-serve loop entirely in C and only re-enters Ruby for:
+    #
+    #   1. Per-request lifecycle hooks
+    #      (`Runtime#fire_request_start` / `fire_request_end`), gated
+    #      by a single C-side integer flag so the no-hook hot path
+    #      stays one syscall.
+    #   2. Connection handoff: requests that don't match a `StaticEntry`
+    #      (or are malformed, h2/upgrade, or carry a body) are passed
+    #      back as `(fd, partial_buffer)` — Ruby resumes ownership of
+    #      the fd and dispatches via the regular `Connection` path.
+    #
+    # The wiring lives in this module so the conditional logic stays
+    # out of the Server hot-path entry methods.
+    module ConnectionLoop
+      module_function
+
+      # Whether the C accept loop is available and the env didn't
+      # disable it.
+      def available?
+        return false unless defined?(::Hyperion::Http::PageCache)
+        return false unless ::Hyperion::Http::PageCache.respond_to?(:run_static_accept_loop)
+
+        env = ENV['HYPERION_C_ACCEPT_LOOP']
+        env.nil? || !%w[0 off false no].include?(env.downcase)
+      end
+
+      # 2.12-D — whether to engage the io_uring accept loop variant
+      # over the 2.12-C `accept4` loop. All four conditions must hold:
+      #
+      #   1. Operator opted in via `HYPERION_IO_URING_ACCEPT=1`. This
+      #      is OFF by default for 2.12.0 — flipping the default to ON
+      #      is a 2.13 decision after production-soak.
+      #   2. The C ext was compiled with `HAVE_LIBURING` (probed at
+      #      gem-install time via `extconf.rb` — needs `liburing-dev`
+      #      headers). Builds without it ship the stub method that
+      #      returns `:unavailable` regardless of the env var.
+      #   3. `Hyperion::Http::PageCache.run_static_io_uring_loop` is
+      #      defined (paranoia: the symbol always exists on builds
+      #      that loaded the C ext, but the check keeps us from
+      #      NameError'ing on partial installs).
+      #   4. A liburing runtime probe — opening a tiny ring with
+      #      `io_uring_queue_init`. The probe lives inside the C
+      #      method itself (`run_static_io_uring_loop` returns
+      #      `:unavailable` if `io_uring_queue_init` fails); we
+      #      don't pre-probe here because that would require holding
+      #      a ring open across the eligibility check, and the
+      #      penalty for "engaged but probe-fail at run time" is
+      #      one cheap fall-through to the `accept4` path.
+      def io_uring_eligible?
+        return false unless available?
+        return false unless ::Hyperion::Http::PageCache.respond_to?(:run_static_io_uring_loop)
+        return false unless ::Hyperion::Http::PageCache.respond_to?(:io_uring_loop_compiled?) &&
+                            ::Hyperion::Http::PageCache.io_uring_loop_compiled?
+
+        env = ENV['HYPERION_IO_URING_ACCEPT']
+        return false unless env
+
+        %w[1 on true yes].include?(env.downcase)
+      end
+
+      # Whether the route table is C-loop eligible: only `StaticEntry`
+      # handlers, at least one of them, no dynamic handlers anywhere.
+      def eligible_route_table?(route_table)
+        return false unless route_table
+
+        any_static = false
+        route_table.instance_variable_get(:@routes).each_value do |path_table|
+          path_table.each_value do |handler|
+            return false unless handler.is_a?(::Hyperion::Server::RouteTable::StaticEntry)
+
+            any_static = true
+          end
+        end
+        any_static
+      end
+
+      # Build a lifecycle callback that, when invoked from the C loop
+      # with `(method_str, path_str)`, fires the runtime's
+      # `fire_request_start` / `fire_request_end` hooks against a
+      # minimal `Hyperion::Request` value object. `env=nil` and the
+      # response slot carries the `:c_static` symbol (just a marker —
+      # the wire write already happened in C and we have no
+      # `[status, headers, body]` tuple to hand back).
+      #
+      # The proc captures `runtime` so multi-tenant deployments with
+      # per-Server runtimes route hooks to the right observer
+      # registry. Allocation cost: one Request per request when
+      # hooks are active. The C loop only invokes this callback when
+      # `lifecycle_active?` is true; the no-hook path pays nothing.
+      def build_lifecycle_callback(runtime)
+        lambda do |method_str, path_str|
+          request = ::Hyperion::Request.new(
+            method: method_str,
+            path: path_str,
+            query_string: nil,
+            http_version: 'HTTP/1.1',
+            headers: {},
+            body: nil
+          )
+          if runtime.has_request_hooks?
+            runtime.fire_request_start(request, nil)
+            runtime.fire_request_end(request, nil, :c_static, nil)
+          end
+          nil
+        rescue StandardError
+          # Hook errors are already swallowed inside `Runtime#fire_*`;
+          # this rescue catches Request allocation oddities so a
+          # misbehaving observer can't take down the C loop.
+          nil
+        end
+      end
+
+      # Build the handoff callback the C loop invokes when a
+      # connection's first request can't be served from the static
+      # cache. Receives `(fd, partial_buffer_or_nil)` — Ruby owns
+      # the fd from that point on. We wrap the fd in a `Socket`
+      # (so `apply_timeout` and the rest of the Connection path see
+      # the same surface they always see) and dispatch through the
+      # server's existing `dispatch_handed_off` helper.
+      def build_handoff_callback(server)
+        lambda do |fd, partial|
+          server.send(:dispatch_handed_off, fd, partial)
+        rescue StandardError => e
+          server.send(:runtime_logger).warn do
+            { message: 'C loop handoff dispatch failed',
+              error: e.message, error_class: e.class.name }
+          end
+          # Always close the fd if dispatch raised — Ruby owns it.
+          begin
+            require 'socket'
+            ::Socket.for_fd(fd).close
+          rescue StandardError
+            nil
+          end
+        end
+      end
+    end
+  end
+end