hyperion-rb 2.11.0 → 2.12.0

data/ext/hyperion_http/page_cache_internal.h

@@ -0,0 +1,132 @@
+/* ----------------------------------------------------------------------
+ * page_cache_internal.h — internal C-ext sharing surface.
+ *
+ * 2.12-D — exposes the request-parsing + lookup + write helpers built by
+ * `page_cache.c`'s C accept loop so the io_uring sibling
+ * (`io_uring_loop.c`) can reuse them rather than copy-pasting. The
+ * helpers stay `static` inside `page_cache.c` and the symbols below are
+ * thin extern wrappers — one indirection per call, but the io_uring
+ * loop calls them at most once per request, so the cost is negligible
+ * (single-direct-call jump) compared to the syscall savings the loop
+ * delivers.
+ *
+ * NOT public surface. NOT installed in any include path. The header
+ * lives next to the .c files and is included only by the in-tree C
+ * sources.
+ * ---------------------------------------------------------------------- */
+#ifndef HYP_PAGE_CACHE_INTERNAL_H
+#define HYP_PAGE_CACHE_INTERNAL_H
+
+#include <stddef.h>
+#include <sys/types.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Method classification (mirrors `hyp_pc_method_t` in page_cache.c). The
+ * io_uring loop uses this via `pc_internal_classify_method` to decide
+ * how much of the cached response to write (HEAD = headers only, GET =
+ * full response). */
+typedef enum {
+    PC_INTERNAL_METHOD_GET   = 0,
+    PC_INTERNAL_METHOD_HEAD  = 1,
+    PC_INTERNAL_METHOD_OTHER = 2
+} pc_internal_method_t;
+
+/* End-of-headers scanner. Returns the byte offset PAST the trailing
+ * CRLFCRLF, or -1 if not found. */
+long pc_internal_find_eoh(const char *buf, size_t len);
+
+/* Request-line parser. On success fills *m_off, *m_len, *p_off, *p_len
+ * with offsets/lengths of METHOD and PATH inside `buf`, and returns the
+ * length of the request line including the trailing CRLF. Returns -1
+ * on malformed input or non-HTTP/1.1 versions (HTTP/1.0 differs in
+ * keep-alive defaults; the caller must hand it off to Ruby). */
+long pc_internal_parse_request_line(const char *buf, size_t len,
+                                    size_t *m_off, size_t *m_len,
+                                    size_t *p_off, size_t *p_len);
+
+/* Header-block scanner. `start` and `end` bracket the headers section
+ * (between request-line end and the closing CRLFCRLF). Reports:
+ *   *connection_close — Connection: close seen
+ *   *has_body         — non-zero Content-Length OR Transfer-Encoding
+ *   *upgrade_seen     — Upgrade or HTTP2-Settings seen
+ * Returns 0 on success, -1 on malformed framing. */
+int pc_internal_scan_headers(const char *buf, size_t start, size_t end,
+                             int *connection_close, int *has_body,
+                             int *upgrade_seen);
+
+/* Method classifier. Returns GET / HEAD / OTHER. */
+pc_internal_method_t pc_internal_classify_method(const char *m, size_t len);
+
+/* Snapshot the response bytes for `(path, kind)` into a freshly malloc'd
+ * buffer. On hit: returns the malloc'd buffer (caller must `free()` it)
+ * and writes the byte length into *out_len. On miss: returns NULL and
+ * sets *out_len = 0. The buffer is whatever the page cache's lookup
+ * picks given the recheck/staleness rules; the io_uring loop writes it
+ * verbatim. Takes the C-side cache lock briefly; releases it before
+ * returning. Returns NULL on OOM as well — the caller treats both as
+ * "couldn't serve from C, hand off to Ruby". */
+char *pc_internal_snapshot_response(const char *path, size_t path_len,
+                                    pc_internal_method_t kind,
+                                    size_t *out_len);
+
+/* Apply TCP_NODELAY to an accepted fd (best-effort; failures swallowed). */
+void pc_internal_apply_tcp_nodelay(int fd);
+
+/* Lifecycle hook fire wrapper. The io_uring loop calls this AFTER the
+ * write completion arrives so observers see a finished request. The
+ * C-side gate (`lifecycle_active`) is checked inside; the wrapper is
+ * a no-op when no callback is registered or the gate is off. Must be
+ * called under the GVL. */
+void pc_internal_fire_lifecycle(const char *method, size_t mlen,
+                                const char *path, size_t plen);
+
+/* Whether the lifecycle gate is currently on. The io_uring loop reads
+ * this BEFORE re-acquiring the GVL — when it's off, the loop skips
+ * the rb_thread_call_with_gvl round-trip entirely. */
+int pc_internal_lifecycle_active(void);
+
+/* Handoff wrapper — invokes the registered Ruby callback with
+ * (fd, partial_buffer_or_nil). Must be called under the GVL. Closes
+ * the fd locally if no callback is registered or if the callback
+ * raised. */
+void pc_internal_handoff(int client_fd, const char *partial, size_t partial_len);
+
+/* Read the stop flag flipped by `PageCache.stop_accept_loop`. Both the
+ * 2.12-C accept4 loop AND the 2.12-D io_uring loop honour it as a
+ * graceful-shutdown signal. */
+int pc_internal_stop_requested(void);
+
+/* Reset the stop flag to 0. Called by the loop entry points
+ * (`run_static_accept_loop`, `run_static_io_uring_loop`) so a previous
+ * invocation's `stop_accept_loop` doesn't immediately tear down a
+ * fresh loop. Specs hammer this path between examples — the 2.12-C
+ * loop resets inline; the io_uring sibling needs the same surface. */
+void pc_internal_reset_stop(void);
+
+/* 2.12-E — bump the per-process served-request counter (atomic; safe
+ * to call from any thread / fiber / accept-loop context). Both the
+ * 2.12-C accept4 loop and the 2.12-D io_uring loop call this after
+ * a successful response write so the SO_REUSEPORT distribution audit
+ * (`PageCache.c_loop_requests_total`) sees ticks regardless of which
+ * loop variant is active. */
+void pc_internal_tick_request(void);
+
+/* 2.12-E — reset the per-process served-request counter. Mirrors the
+ * stop-flag reset rationale: loop entry points call this so a prior
+ * invocation's count doesn't bleed into the new loop's snapshot. */
+void pc_internal_reset_requests_served(void);
+
+/* The 64 KiB header-cap shared with `page_cache.c`. Re-declared here
+ * so io_uring_loop.c doesn't need to mirror the magic number. */
+#ifndef PC_INTERNAL_MAX_HEADER_BYTES
+#define PC_INTERNAL_MAX_HEADER_BYTES 65536
+#endif
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* HYP_PAGE_CACHE_INTERNAL_H */

data/lib/hyperion/connection.rb

@@ -135,6 +135,12 @@ module Hyperion
       # keep the existing pattern of caching boot-time refs as ivars so
       # the per-request observe stays a single Hash lookup.
       @path_templater = path_templater || Hyperion::Metrics.default_path_templater
+      # 2.12-E — per-worker request counter label. Cached once per
+      # Connection (Process.pid is process-constant — re-reading it per
+      # request would allocate the to_s String every time the operator
+      # asked Ruby for the symbol/label). Each Connection lives in
+      # exactly one process, so the cache is tight and never stale.
+      @worker_id = Process.pid.to_s
       # 2.10-D — direct-dispatch route table.  The hot-path lookup
       # is `@route_table&.lookup(method, path)` so the nil-default
       # case (no operator-registered direct routes — the
@@ -307,6 +313,14 @@ module Hyperion
         @metrics.increment(:bytes_read, body_end)
         @metrics.increment(:requests_total)
         @metrics.increment(:requests_in_flight)
+        # 2.12-E — per-worker request counter for the SO_REUSEPORT
+        # load-balancing audit. Worker_id is the OS pid (matches the
+        # 2.4-C `hyperion_io_uring_workers_active` convention). Single
+        # location for every Ruby-side dispatch shape: regular Rack
+        # via `dispatch_request`, direct dispatch via `dispatch_direct!`,
+        # and the StaticEntry fast path via `dispatch_direct_static!`
+        # all flow through this point in `serve`.
+        @metrics.tick_worker_request(@worker_id)
         # 2.4-C: capture start time for the per-route duration histogram.
         # Same Process.clock_gettime that the access-log path was already
         # paying — at default-ON log_requests the second call here is

data/lib/hyperion/dispatch_mode.rb

@@ -46,8 +46,26 @@ module Hyperion
     #                          escape hatch via `env['hyperion.dispatch_mode']
     #                          = :inline_blocking` for routes the auto-
     #                          detect doesn't catch.
+    # 2.12-C — `:c_accept_loop_h1` is a connection-wide mode (NOT a
+    # per-response override): the entire accept-and-serve loop runs in
+    # C via `Hyperion::Http::PageCache.run_static_accept_loop`. Engaged
+    # only when the operator's route table is composed entirely of
+    # `Server.handle_static`-registered routes AND the listener is
+    # plain TCP. Counted under `:requests_dispatch_c_accept_loop_h1`
+    # at engage time (one bump per worker boot) so operators can see
+    # the path is on without scraping the per-request `:c_accept_loop_requests`
+    # counter.
+    # 2.12-D — `:c_accept_loop_io_uring_h1` is a sibling of
+    # `:c_accept_loop_h1`. Engaged when the operator opts into
+    # `HYPERION_IO_URING_ACCEPT=1` AND the C ext was compiled with
+    # liburing AND the runtime probe succeeded. Same eligibility gates
+    # as `:c_accept_loop_h1` (handle_static-only routes, plain TCP),
+    # different syscall shape (single `io_uring_enter` per N requests
+    # vs. N×3 syscalls). Counted under
+    # `:requests_dispatch_c_accept_loop_io_uring_h1` so operators can
+    # confirm the path is on without scraping logs.
     MODES = %i[tls_h2 tls_h1_inline async_io_h1_inline threadpool_h1 inline_h1_no_pool
-               inline_blocking].freeze
+               inline_blocking c_accept_loop_h1 c_accept_loop_io_uring_h1].freeze
 
     INLINE_MODES = %i[tls_h1_inline async_io_h1_inline inline_h1_no_pool inline_blocking].freeze
 

data/lib/hyperion/http2_handler.rb

@@ -275,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
@@ -506,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
@@ -1121,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,
@@ -1155,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)
@@ -1165,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)
@@ -1229,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
 
@@ -1250,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 }

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