hyperion-rb 2.10.1 → 2.12.0

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

data/lib/hyperion/server.rb

@@ -6,6 +6,7 @@ require 'async'
 require 'async/scheduler'
 
 require_relative 'server/route_table'
+require_relative 'server/connection_loop'
 
 module Hyperion
   # Phase 2a server: bind a TCPServer, accept connections, schedule each on its
@@ -400,7 +401,16 @@ module Hyperion
     # a worker via the thread pool, or are served inline when no pool is
     # configured (thread_count: 0). Matches the dispatch contract used by
     # the TLS path; just skips the irrelevant h2/ALPN branch.
+    #
+    # 2.12-C — when the route table is composed entirely of `StaticEntry`
+    # registrations (and at least one is present), and the C ext is
+    # available, the entire accept-and-serve loop runs in C via
+    # `Hyperion::Http::PageCache.run_static_accept_loop`. Ruby is only
+    # re-entered for lifecycle hooks (gated by a C-side flag) and for
+    # the handoff path when a request doesn't match any StaticEntry.
     def start_raw_loop
+      return run_c_accept_loop if engage_c_accept_loop?
+
       until @stopped
         socket = accept_or_nil
         next unless socket
@@ -429,6 +439,179 @@ module Hyperion
       end
     end
 
+    # Whether all engagement conditions hold for the C accept loop.
+    def engage_c_accept_loop?
+      return false if @tls
+      return false unless ConnectionLoop.available?
+      return false unless ConnectionLoop.eligible_route_table?(@route_table)
+
+      true
+    end
+    private :engage_c_accept_loop?
+
+    # Hand control of the listening fd to the C loop. Wires up the
+    # lifecycle + handoff callbacks first; on return (clean stop or
+    # `:crashed` sentinel from C), bumps the dispatch metric and
+    # falls through to the regular Ruby accept loop on `:crashed`
+    # so an unrecoverable C-side accept error doesn't leave the
+    # listener idle.
+    def run_c_accept_loop
+      pc = ::Hyperion::Http::PageCache
+      pc.set_lifecycle_callback(ConnectionLoop.build_lifecycle_callback(@runtime))
+      pc.set_lifecycle_active(@runtime.has_request_hooks?)
+      pc.set_handoff_callback(ConnectionLoop.build_handoff_callback(self))
+      # 2.12-E — register the per-worker request counter family on the
+      # runtime's metrics sink BEFORE the C loop starts ticking. The
+      # PrometheusExporter's C-loop fold-in is gated on the family
+      # already existing in the snapshot (so spec-only sinks that
+      # never tick stay clean), and the C accept loop bypasses
+      # `Connection#serve` — without an explicit boot-time register,
+      # a 100% C-loop worker would scrape zero requests even with
+      # the atomic happily ticking.
+      runtime_metrics.ensure_worker_request_family_registered! \
+        if runtime_metrics.respond_to?(:ensure_worker_request_family_registered!)
+
+      # 2.12-D — io_uring path takes precedence over accept4 when the
+      # operator opted in AND the runtime probe at boot succeeds. The
+      # C-side `run_static_io_uring_loop` returns `:unavailable` if
+      # `io_uring_queue_init` fails; we treat that as "fall back to
+      # the 2.12-C accept4 path" without operator intervention. A
+      # `:crashed` from io_uring also falls back — the contract
+      # mirrors 2.12-C's `:crashed -> Ruby accept loop`.
+      use_io_uring = ConnectionLoop.io_uring_eligible?
+      mode_name = use_io_uring ? :c_accept_loop_io_uring_h1 : :c_accept_loop_h1
+      mode = DispatchMode.new(mode_name)
+      record_dispatch(mode)
+      runtime_logger.info do
+        { message: 'engaging C accept loop',
+          variant: use_io_uring ? :io_uring : :accept4,
+          static_routes: @route_table.size,
+          host: @host,
+          port: @port }
+      end
+      result = if use_io_uring
+                 io_uring_result = pc.run_static_io_uring_loop(@tcp_server.fileno)
+                 if io_uring_result == :unavailable
+                   runtime_logger.warn do
+                     { message: 'io_uring runtime probe failed; falling back to accept4 loop' }
+                   end
+                   pc.run_static_accept_loop(@tcp_server.fileno)
+                 else
+                   io_uring_result
+                 end
+               else
+                 pc.run_static_accept_loop(@tcp_server.fileno)
+               end
+      if result == :crashed
+        runtime_logger.warn do
+          { message: 'C accept loop crashed; falling back to Ruby accept loop' }
+        end
+        # Fall back to the Ruby loop so the listener doesn't go silent.
+        until @stopped
+          socket = accept_or_nil
+          next unless socket
+
+          apply_timeout(socket)
+          dispatch_one_h1(socket)
+        end
+      else
+        runtime_logger.info do
+          { message: 'C accept loop exited', requests_served: result.to_i,
+            variant: use_io_uring ? :io_uring : :accept4 }
+        end
+        runtime_metrics.increment(:c_accept_loop_requests, result.to_i)
+      end
+    ensure
+      # Best-effort: clear the lifecycle callback so a subsequent
+      # Server boot in the same process (test harnesses) doesn't see
+      # stale state.
+      pc&.set_lifecycle_active(false) if defined?(pc)
+      pc&.set_lifecycle_callback(nil) if defined?(pc)
+      pc&.set_handoff_callback(nil) if defined?(pc)
+    end
+    private :run_c_accept_loop
+
+    # Dispatch a connection that the C accept loop handed off to Ruby
+    # because it couldn't be served from the static cache (path miss,
+    # malformed request, body present, h2 upgrade requested, etc.).
+    # `partial` is the partial header buffer the C loop already read
+    # off the fd, or nil if the C loop hadn't started reading.
+    #
+    # The fd is owned by Ruby from this point on — the C loop will
+    # not touch it again. We wrap it in a `::Socket` (matches the
+    # `accept_nonblock` path's return type) and dispatch through the
+    # existing thread-pool / inline path.
+    def dispatch_handed_off(fd, partial)
+      require 'socket'
+      socket = ::Socket.for_fd(fd)
+      socket.autoclose = true
+      apply_timeout(socket)
+      # 2.12-E — `partial.present?` was a Rails-ism that crashed the
+      # handoff path with NoMethodError on plain Ruby. Hit by every
+      # request that lands on a static-only server (e.g. /-/metrics
+      # against `bench/hello_static.ru`) — the C loop hands off, the
+      # handoff dispatch raised, and the connection was force-closed
+      # with `:c_loop_handoff_failed`. Surfaced by the 2.12-E audit
+      # harness which scrapes /-/metrics on a handle_static-only
+      # cluster; pre-existing bug, fixed here so the metric is
+      # actually readable. The `is_a?(String)` guard is deliberate —
+      # it both narrows the contract (the C loop never hands off
+      # anything but a plain String or nil) and pins the shape so
+      # `rubocop-rails`'s Style/Present autocorrect can't rewrite
+      # this back to `partial.present?`.
+      carry = partial.is_a?(String) && !partial.empty? ? partial.dup.b : nil
+
+      if @thread_pool
+        mode = DispatchMode.new(:threadpool_h1)
+        # 2.12-E — thread the carry through to the worker so the
+        # `Connection#@inbuf` is preloaded with the partial header
+        # bytes the C accept loop already drained off the fd. Pre-2.12-E
+        # the threadpool handoff path silently dropped the buffer
+        # (only the inline-no-pool branch wired it), so every
+        # `-t N>0` server with the C accept loop engaged returned
+        # "Request Timeout" on every handed-off request — including
+        # the audit harness's own `/-/metrics` scrape.
+        if @thread_pool.submit_connection(socket, @app,
+                                          max_request_read_seconds: @max_request_read_seconds,
+                                          carry: carry)
+          record_dispatch(mode)
+        else
+          reject_connection(socket)
+        end
+      else
+        mode = DispatchMode.new(:inline_h1_no_pool)
+        record_dispatch(mode)
+        connection = Connection.new(runtime: @explicit_runtime ? @runtime : nil,
+                                    max_in_flight_per_conn: @max_in_flight_per_conn,
+                                    route_table: @route_table)
+        connection.instance_variable_set(:@inbuf, +carry.b) if carry
+        connection.serve(socket, @app,
+                         max_request_read_seconds: @max_request_read_seconds)
+      end
+    end
+    private :dispatch_handed_off
+
+    def dispatch_one_h1(socket)
+      if @thread_pool
+        mode = DispatchMode.new(:threadpool_h1)
+        if @thread_pool.submit_connection(socket, @app,
+                                          max_request_read_seconds: @max_request_read_seconds)
+          record_dispatch(mode)
+        else
+          reject_connection(socket)
+        end
+      else
+        mode = DispatchMode.new(:inline_h1_no_pool)
+        record_dispatch(mode)
+        Connection.new(runtime: @explicit_runtime ? @runtime : nil,
+                       max_in_flight_per_conn: @max_in_flight_per_conn,
+                       route_table: @route_table).serve(
+                         socket, @app, max_request_read_seconds: @max_request_read_seconds
+                       )
+      end
+    end
+    private :dispatch_one_h1
+
     # TLS / h2-capable accept loop. The Async wrapper is required because
     # h2 streams (inside Http2Handler) and the ALPN handshake yield
     # cooperatively via the scheduler.

data/lib/hyperion/thread_pool.rb

@@ -85,10 +85,20 @@ module Hyperion
     # not strict. Off-by-one over the configured cap during a thundering
     # accept burst is acceptable; the cost of stricter sync would be a
     # mutex on every enqueue, which we won't pay on the hot path.
-    def submit_connection(socket, app, max_request_read_seconds: 60)
+    def submit_connection(socket, app, max_request_read_seconds: 60, carry: nil)
       return false if @max_pending && @inbox.size >= @max_pending
 
-      @inbox << [:connection, socket, app, max_request_read_seconds]
+      # 2.12-E — `carry:` carries any partial header bytes the C accept
+      # loop already read off the fd before deciding to hand the
+      # connection off to Ruby. The worker thread pre-loads them into
+      # `Connection#@inbuf` so the parser sees the full request, not a
+      # short read that times out. Pre-2.12-E the threadpool handoff
+      # path silently dropped the partial buffer (the inline-no-pool
+      # path was the only one wired) — a server with `-t N>0` and the
+      # C accept loop engaged returned "Request Timeout" on every
+      # handed-off request, including the audit harness's own
+      # `/-/metrics` scrape.
+      @inbox << [:connection, socket, app, max_request_read_seconds, carry]
       true
     end
 
@@ -139,17 +149,23 @@ module Hyperion
 
           case job[0]
           when :connection
-            _, socket, app, max_request_read_seconds = job
+            _, socket, app, max_request_read_seconds, carry = job
             # Worker thread owns the connection for its full lifetime. Pass
             # thread_pool: nil so Connection#call_app inlines Adapter::Rack.call
             # — the worker IS the pool, no further hop required. 2.3-B
             # threads `max_in_flight_per_conn` so the per-conn fairness
             # cap (if configured) takes effect on this worker's serve loop.
             begin
-              Hyperion::Connection
-                .new(max_in_flight_per_conn: @max_in_flight_per_conn,
-                     route_table: @route_table)
-                .serve(socket, app, max_request_read_seconds: max_request_read_seconds)
+              connection = Hyperion::Connection
+                           .new(max_in_flight_per_conn: @max_in_flight_per_conn,
+                                route_table: @route_table)
+              # 2.12-E — preload `@inbuf` with the partial buffer the C
+              # accept loop already drained off the fd, mirroring the
+              # inline-no-pool branch in `Server#dispatch_handed_off`.
+              # `carry` is nil on the regular accept path; only the C
+              # loop's handoff path supplies it.
+              connection.instance_variable_set(:@inbuf, +carry.b) if carry.is_a?(String) && !carry.empty?
+              connection.serve(socket, app, max_request_read_seconds: max_request_read_seconds)
             rescue StandardError => e
               Hyperion.logger.error do
                 {

data/lib/hyperion/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hyperion
-  VERSION = '2.10.1'
+  VERSION = '2.12.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperion-rb
 version: !ruby/object:Gem::Version
-  version: 2.10.1
+  version: 2.12.0
 platform: ruby
 authors:
 - Andrey Lobanov
@@ -164,11 +164,13 @@ files:
 - ext/hyperion_h2_codec/src/lib.rs
 - ext/hyperion_http/extconf.rb
 - ext/hyperion_http/h2_codec_glue.c
+- ext/hyperion_http/io_uring_loop.c
 - ext/hyperion_http/llhttp/api.c
 - ext/hyperion_http/llhttp/http.c
 - ext/hyperion_http/llhttp/llhttp.c
 - ext/hyperion_http/llhttp/llhttp.h
 - ext/hyperion_http/page_cache.c
+- ext/hyperion_http/page_cache_internal.h
 - ext/hyperion_http/parser.c
 - ext/hyperion_http/sendfile.c
 - ext/hyperion_http/websocket.c
@@ -207,6 +209,7 @@ files:
 - lib/hyperion/response_writer.rb
 - lib/hyperion/runtime.rb
 - lib/hyperion/server.rb
+- lib/hyperion/server/connection_loop.rb
 - lib/hyperion/server/route_table.rb
 - lib/hyperion/static_preload.rb
 - lib/hyperion/thread_pool.rb