hyperion-rb 2.11.0 → 2.12.0

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.11.0'
+  VERSION = '2.12.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperion-rb
 version: !ruby/object:Gem::Version
-  version: 2.11.0
+  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