hyperion-rb 1.6.1 → 2.10.1

data/lib/hyperion/server.rb

@@ -5,6 +5,8 @@ require 'openssl'
 require 'async'
 require 'async/scheduler'
 
+require_relative 'server/route_table'
+
 module Hyperion
   # Phase 2a server: bind a TCPServer, accept connections, schedule each on its
   # own fiber via Async. Multiple in-flight requests run concurrently on a
@@ -38,11 +40,145 @@ module Hyperion
       (head + body).freeze
     }.call
 
-    attr_reader :host, :port
+    attr_reader :host, :port, :runtime
+
+    # 2.10-D — process-wide direct-dispatch route table.  Operators
+    # register routes via `Hyperion::Server.handle(:GET, '/hello',
+    # handler)` BEFORE forking workers; each forked worker inherits
+    # the populated table via copy-on-write.  Per-Server instances
+    # can override by passing `route_table:` to the constructor (a
+    # test seam — production code uses the class singleton).
+    #
+    # Lazily initialized so `require 'hyperion'` itself doesn't pay
+    # the allocation when the operator never registers a direct
+    # route (the common 1.x deployment).
+    def self.route_table
+      @route_table ||= RouteTable.new
+    end
+
+    # Test seam: replace the process-wide route table with a fresh
+    # (or stub) instance.  Used by `direct_route_spec.rb` so each
+    # example starts from an empty table without needing to call
+    # `clear` (which would interfere with parallel registration
+    # tests).
+    class << self
+      attr_writer :route_table
+    end
+
+    # 2.10-D — register a direct-dispatch handler.  Bypasses the Rack
+    # adapter on hit: when a request whose method + path matches
+    # this entry arrives, `Connection#serve` skips the env-hash
+    # build, the middleware chain, and the body-iteration loop —
+    # the handler is called directly with a `Hyperion::Request`
+    # value object.
+    #
+    # `method_sym` is one of `:GET`, `:POST`, `:PUT`, `:DELETE`,
+    # `:HEAD`, `:PATCH`, `:OPTIONS` (case-insensitive — `:get`
+    # works too).  `path` is an exact-match String (regex / glob
+    # routing is intentionally out of scope; future work).
+    # `handler` is any object responding to `#call(request)` that
+    # returns a `[status, headers, body]` Rack tuple.
+    #
+    # Lifecycle hooks (`Runtime#on_request_start` /
+    # `on_request_end`) still fire on direct routes so NewRelic /
+    # AppSignal / OpenTelemetry instrumentation works regardless
+    # of dispatch shape.
+    #
+    # On a non-match (any path / method not registered here) the
+    # request falls through to the regular Rack adapter dispatch
+    # — existing behaviour for un-handled routes is unchanged.
+    def self.handle(method_sym, path, handler)
+      route_table.register(method_sym, path, handler)
+    end
 
+    # 2.10-D — register a direct-dispatch route whose response is
+    # FULLY known at registration time.  The full HTTP/1.1 response
+    # buffer (status line + Content-Type + Content-Length + body)
+    # is built ONCE here and stashed in a `RouteTable::StaticEntry`;
+    # on hit, `Connection#serve` issues a single `socket.write` of
+    # the pre-built bytes — no header build, no body iteration,
+    # zero per-request allocation past the Connection ivars.
+    #
+    # Mirrors agoo's optimal hello-world path.  `body_bytes` is
+    # the response body (frozen automatically); `content_type`
+    # defaults to `text/plain`.  Returns the registered
+    # `StaticEntry` for inspection.
+    def self.handle_static(method_sym, path, body_bytes, content_type: 'text/plain')
+      raise ArgumentError, 'body_bytes must be a String' unless body_bytes.is_a?(String)
+      raise ArgumentError, 'content_type must be a String' unless content_type.is_a?(String)
+
+      body = body_bytes.dup.b.freeze
+      head = +"HTTP/1.1 200 OK\r\n" \
+              "content-type: #{content_type}\r\n" \
+              "content-length: #{body.bytesize}\r\n" \
+              "\r\n"
+      head.force_encoding(Encoding::ASCII_8BIT)
+      buffer = (head + body).freeze
+
+      method_key = method_sym.to_s.upcase.to_sym
+      # 2.10-F — record the headers prefix length on the StaticEntry
+      # struct so HEAD-method writes can serve a headers-only prefix.
+      entry = RouteTable::StaticEntry.new(method_key, path.dup.freeze, buffer, head.bytesize).freeze
+      # 2.10-F — register the entry DIRECTLY (StaticEntry responds to
+      # `#call`) instead of wrapping it in a closure, so the dispatch
+      # path can branch on `is_a?(StaticEntry)` BEFORE invoking the
+      # handler — that's what unlocks the C-ext fast path.
+      route_table.register(method_sym, path, entry)
+      # 2.10-F — also register HEAD for any GET registration.  HTTP
+      # mandates HEAD-on-a-GET-resource, and the C fast path strips
+      # the body bytes for HEAD requests inside `serve_request`.
+      # Idiomatic for static-asset routes (every CDN-shaped GET URL
+      # MUST also answer HEAD with the same headers).  No-op on a
+      # POST/PUT/etc. registration — those don't get a HEAD twin.
+      route_table.register(:HEAD, path, entry) if method_key == :GET
+      # 2.10-F — fold the prebuilt response into the C-side PageCache so
+      # `PageCache.serve_request` can write it without ever crossing
+      # back into Ruby.  Best-effort: if the C ext isn't available
+      # (JRuby / TruffleRuby), the dispatcher silently falls back to
+      # the Ruby `socket.write` path that's been there since 2.10-D.
+      if defined?(::Hyperion::Http::PageCache) && ::Hyperion::Http::PageCache.respond_to?(:register_prebuilt)
+        ::Hyperion::Http::PageCache.register_prebuilt(path, buffer, body.bytesize)
+      end
+      entry
+    end
+
+    # 1.7.0 added kwargs (all default to current behaviour):
+    #   * `runtime:`             — `Hyperion::Runtime` instance (default
+    #                               `Runtime.default`). Threaded through to
+    #                               every per-connection / per-stream code
+    #                               path so per-server metrics/logger
+    #                               isolation works.
+    #   * `accept_fibers_per_worker:` — Integer, default 1. When > 1 and the
+    #                               accept loop is async-wrapped, spawn N
+    #                               accept fibers that race on the same
+    #                               listening fd. Linear scaling on
+    #                               `:reuseport` (Linux); Darwin honours the
+    #                               knob silently with no scaling benefit
+    #                               (RFC §5 Q5).
+    #   * `h2_max_total_streams:` — Integer or nil (default nil). Process-
+    #                               wide cap on simultaneously-open h2
+    #                               streams across all connections. nil
+    #                               disables (current behaviour); set to
+    #                               opt into RFC A7 admission control.
+    #   * `admin_listener_port:`  — Integer or nil (default nil). When set,
+    #                               spawn a sibling HTTP listener on
+    #                               `127.0.0.1:<port>` that serves only
+    #                               `/-/quit` and `/-/metrics`. nil keeps
+    #                               admin mounted in-app (current shape).
     def initialize(app:, host: '127.0.0.1', port: 9292, read_timeout: DEFAULT_READ_TIMEOUT_SECONDS,
                    tls: nil, thread_count: DEFAULT_THREAD_COUNT, max_pending: nil,
-                   max_request_read_seconds: 60, h2_settings: nil, async_io: nil)
+                   max_request_read_seconds: 60, h2_settings: nil, async_io: nil,
+                   runtime: nil, accept_fibers_per_worker: 1,
+                   h2_max_total_streams: nil, admin_listener_port: nil,
+                   admin_listener_host: '127.0.0.1', admin_token: nil,
+                   tls_session_cache_size: TLS::DEFAULT_SESSION_CACHE_SIZE,
+                   tls_ktls: :auto,
+                   io_uring: :off,
+                   max_in_flight_per_conn: nil,
+                   tls_handshake_rate_limit: :unlimited,
+                   route_table: nil,
+                   preload_static_dirs: nil)
+      validate_async_io!(async_io)
       @host                     = host
       @port                     = port
       @app                      = app
@@ -53,16 +189,97 @@ module Hyperion
       @max_request_read_seconds = max_request_read_seconds
       @h2_settings              = h2_settings
       @async_io                 = async_io
+      # `@explicit_runtime` toggles between 1.7.0 isolation (an
+      # explicitly-passed Runtime) and 1.6.x compat (legacy module-level
+      # accessors honoured for stub seams). All record_dispatch /
+      # reject_connection / log lines route through `runtime_metrics` /
+      # `runtime_logger` helpers below.
+      @runtime                  = runtime || Hyperion::Runtime.default
+      @explicit_runtime         = !runtime.nil?
+      @accept_fibers_per_worker = [accept_fibers_per_worker.to_i, 1].max
+      # 2.0: `h2_max_total_streams` is normally a positive integer (the
+      # default-flipped cap from `Config#finalize!`) or nil (operator
+      # opted out via `h2.max_total_streams :unbounded`). Defensive
+      # branch: treat the `:auto` / `:unbounded` sentinels as "no cap"
+      # if a caller bypasses Config and constructs Server directly.
+      @h2_admission             = if h2_max_total_streams.is_a?(Integer) && h2_max_total_streams.positive?
+                                    Hyperion::H2Admission.new(max_total_streams: h2_max_total_streams)
+                                  end
+      @admin_listener_port      = admin_listener_port
+      @admin_listener_host      = admin_listener_host
+      @admin_token              = admin_token
+      @admin_listener           = nil
       @thread_pool              = nil
       @stopped                  = false
+      @tls_session_cache_size   = tls_session_cache_size
+      @tls_ktls                 = tls_ktls
+      @ktls_logged              = false
+      # 2.3-A: resolve the io_uring accept policy. `:off` (the 2.3.0
+      # default) skips the resolve step entirely so hosts without the
+      # cdylib don't trigger any Fiddle.dlopen probe at boot.
+      # Workers don't share rings across fork — each child opens its
+      # own ring lazily on first use inside `run_accept_fiber`.
+      @io_uring_policy          = io_uring
+      @io_uring_active          = io_uring != :off && Hyperion::IOUring.resolve_policy!(io_uring)
+      log_io_uring_state_once
+      # 2.3-B: per-conn fairness cap (validated/finalized upstream by
+      # `Config#finalize!`; constructor accepts the resolved value, not
+      # a sentinel). nil = no cap (default). The cap propagates to
+      # every Connection the ThreadPool's `:connection` worker builds.
+      @max_in_flight_per_conn   = max_in_flight_per_conn
+      # 2.3-B: TLS handshake CPU throttle. One limiter per worker
+      # (per-Server). `:unlimited` short-circuits every `acquire_token!`
+      # to true so the hot path stays branchless. Built eagerly so
+      # bench harnesses can introspect via `server.tls_handshake_limiter`.
+      @tls_handshake_limiter    = Hyperion::TLS::HandshakeRateLimiter.new(tls_handshake_rate_limit)
+      # 2.10-D: per-instance route table (defaults to the class-level
+      # singleton).  Tests can inject a fresh table to isolate
+      # registrations from other examples.
+      @route_table              = route_table || Hyperion::Server.route_table
+      # 2.10-E: list of `{path:, immutable:}` entries the worker warms
+      # into `Hyperion::Http::PageCache` at boot. Resolved by
+      # `Config#resolved_preload_static_dirs` and threaded through
+      # Master → Worker → Server. nil/[] = no preload (1.x cold-cache
+      # behaviour).
+      @preload_static_dirs      = preload_static_dirs
+      @preloaded                = false
+    end
+
+    # Read-only handle for tests + bench harness introspection.
+    attr_reader :tls_handshake_limiter
+
+    # 2.10-D — read-only handle to the per-instance route table.
+    # Connection#serve consults this after parse to decide whether
+    # to engage the direct-dispatch fast path.  Defaults to the
+    # process-wide `Hyperion::Server.route_table` singleton.
+    attr_reader :route_table
+
+    # Read-only handle to the per-worker SSL context (nil when the
+    # listener is plain TCP). Exposed so the worker can call
+    # `Hyperion::TLS.rotate!(server.ssl_context)` from its SIGUSR2
+    # handler without reaching into Server internals.
+    attr_reader :ssl_ctx
+
+    # Strict validation of the tri-state `async_io` flag (RFC A9). Pre-1.7
+    # the Server constructor accepted any object; `1`, `:yes`, `'true'`
+    # silently landed in the wrong matrix cell. Now: raise immediately so
+    # the operator's typo surfaces at boot, not as a "why is my fiber-pg
+    # config not behaving" report three hours later.
+    def validate_async_io!(value)
+      return if value.nil? || value == true || value == false
+
+      raise ArgumentError, "async_io must be nil, true, or false (got #{value.inspect})"
     end
+    private :validate_async_io!
 
     def listen
       tcp = ::TCPServer.new(@host, @port)
       @port = tcp.addr[1]
 
       if @tls
-        @ssl_ctx = TLS.context(cert: @tls[:cert], key: @tls[:key], chain: @tls[:chain])
+        @ssl_ctx = TLS.context(cert: @tls[:cert], key: @tls[:key], chain: @tls[:chain],
+                               session_cache_size: @tls_session_cache_size,
+                               ktls: @tls_ktls)
         ssl_server = ::OpenSSL::SSL::SSLServer.new(tcp, @ssl_ctx)
         ssl_server.start_immediately = false
         @server = ssl_server
@@ -90,7 +307,11 @@ module Hyperion
               else
                 sock.local_address.ip_port
               end
-      @ssl_ctx = TLS.context(cert: @tls[:cert], key: @tls[:key], chain: @tls[:chain]) if @tls
+      if @tls
+        @ssl_ctx = TLS.context(cert: @tls[:cert], key: @tls[:key], chain: @tls[:chain],
+                               session_cache_size: @tls_session_cache_size,
+                               ktls: @tls_ktls)
+      end
       self
     end
 
@@ -106,7 +327,19 @@ module Hyperion
 
     def start
       listen unless @server
-      @thread_pool = ThreadPool.new(size: @thread_count, max_pending: @max_pending) if @thread_count.positive?
+      # 2.10-E: warm the page cache before any request can land. Idempotent
+      # via `@preloaded`, so repeated `start` calls (test harnesses,
+      # Worker#run respawn) don't re-walk the tree. Runs after `listen`
+      # (so `@server` exists for the operator's introspection hooks if any
+      # future runtime fires off boot-side instrumentation) but before the
+      # accept loop fires up — first request hits warm cache.
+      preload_static!
+      if @thread_count.positive?
+        @thread_pool = ThreadPool.new(size: @thread_count, max_pending: @max_pending,
+                                      max_in_flight_per_conn: @max_in_flight_per_conn,
+                                      route_table: @route_table)
+      end
+      maybe_start_admin_listener
 
       if @tls || @async_io
         # TLS path: ALPN may pick `h2`, and h2 spawns one fiber per stream
@@ -133,6 +366,7 @@ module Hyperion
       end
     ensure
       @thread_pool&.shutdown
+      @admin_listener&.stop
     end
 
     def stop
@@ -142,6 +376,24 @@ module Hyperion
       @tcp_server = nil
     end
 
+    # 2.10-E — Walk every configured preload directory, populate
+    # `Hyperion::Http::PageCache`, and mark every entry immutable when
+    # asked.  Called from `start` once per worker.  Idempotent — second
+    # call is a no-op so test harnesses + Worker respawn paths don't
+    # re-walk the tree.
+    #
+    # `logger` is exposed as a kwarg purely for the spec suite; production
+    # callers omit it and the runtime logger is used.
+    def preload_static!(logger: runtime_logger)
+      return 0 if @preloaded
+
+      @preloaded = true
+      entries = @preload_static_dirs
+      return 0 if entries.nil? || entries.empty?
+
+      Hyperion::StaticPreload.run(entries, logger: logger)
+    end
+
     private
 
     # Plain HTTP/1.1 accept loop — no fiber wrap. Connections go straight to
@@ -155,15 +407,24 @@ module Hyperion
 
         apply_timeout(socket)
         if @thread_pool
+          mode = DispatchMode.new(:threadpool_h1)
           if @thread_pool.submit_connection(socket, @app,
                                             max_request_read_seconds: @max_request_read_seconds)
-            Hyperion.metrics.increment(:requests_threadpool_dispatched)
+            record_dispatch(mode)
           else
             reject_connection(socket)
           end
         else
-          Hyperion.metrics.increment(:requests_threadpool_dispatched)
-          Connection.new.serve(socket, @app, max_request_read_seconds: @max_request_read_seconds)
+          # `-t 0` plain HTTP/1.1 — no pool, serve inline on the accept
+          # thread. RFC §5 Q3: `--async-io -t 0` keeps working — see
+          # start_async_loop's `inline_h1_no_pool` branch.
+          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
     end
@@ -171,27 +432,129 @@ module Hyperion
     # TLS / h2-capable accept loop. The Async wrapper is required because
     # h2 streams (inside Http2Handler) and the ALPN handshake yield
     # cooperatively via the scheduler.
+    #
+    # 1.7.0 (RFC A6): `accept_fibers_per_worker > 1` spawns N accept
+    # fibers that each `IO.select` on the same listening fd. On `:reuseport`
+    # workers (Linux) the kernel hashes connections fairly across siblings;
+    # on `:share` (Darwin) the knob is silently honoured but shows no
+    # scaling benefit — operators already know Darwin is special.
     def start_async_loop
       Async do |task|
-        until @stopped
-          socket = accept_or_nil
-          next unless socket
-
-          apply_timeout(socket)
-          task.async { dispatch(socket) }
+        n = @accept_fibers_per_worker
+        n.times { task.async { run_accept_fiber(task) } }
+        # `task.children.each(&:wait)` would deadlock if no children — n is
+        # always >= 1, so we're safe; but use rescue-wait pattern in case
+        # one accept fiber raises.
+        task.children.each do |child|
+          child.wait
+        rescue StandardError
+          nil
         end
       end
     end
 
+    # Single accept fiber's run loop. Called N times (default 1) from
+    # `start_async_loop`. All accept fibers share `@server` / `@tcp_server`
+    # via closure; the kernel arbitrates which fiber wins each
+    # IO.select / accept_nonblock race.
+    #
+    # 2.3-A: when `io_uring: :auto/:on` resolves to active, each accept
+    # fiber lazily opens its OWN ring (per-fiber lifecycle — see
+    # `Hyperion::IOUring` docs for the fork+threads sharp edges this
+    # avoids). The ring is closed at fiber exit. The TLS path keeps the
+    # epoll branch — io_uring accept is wired only for the plain TCP
+    # listener; the SSL handshake still wants the userspace
+    # `accept` + `SSL_accept` dance.
+    def run_accept_fiber(task)
+      if @io_uring_active && !@tls
+        run_accept_fiber_io_uring(task)
+      else
+        run_accept_fiber_epoll(task)
+      end
+    end
+
+    def run_accept_fiber_epoll(task)
+      until @stopped
+        socket = accept_or_nil
+        next unless socket
+
+        apply_timeout(socket)
+        task.async { dispatch(socket) }
+      end
+    end
+
+    # 2.3-A: io_uring accept loop. Opens a per-fiber ring on first
+    # use, drains accept CQEs, and hands the resulting fd to the
+    # existing `dispatch` path via a Ruby `Socket.for_fd` wrapper so
+    # the rest of the server (Connection, ResponseWriter, …) keeps
+    # working off a `::Socket` object identical to what
+    # `accept_nonblock` would have returned.
+    def run_accept_fiber_io_uring(task)
+      ring = Fiber.current[:hyperion_io_uring] ||= Hyperion::IOUring::Ring.new(queue_depth: 256)
+      listener_fd = listening_io.fileno
+      until @stopped
+        client_fd = ring.accept(listener_fd)
+        next if client_fd == :wouldblock
+
+        socket = ::Socket.for_fd(client_fd)
+        socket.autoclose = true
+        apply_timeout(socket)
+        task.async { dispatch(socket) }
+      end
+    rescue IOError, Errno::EBADF
+      @stopped = true
+    rescue StandardError => e
+      runtime_logger.warn do
+        { message: 'io_uring accept fiber error; falling back to epoll for this fiber',
+          error: e.message, error_class: e.class.name }
+      end
+      run_accept_fiber_epoll(task)
+    ensure
+      ring = Fiber.current[:hyperion_io_uring]
+      if ring && !ring.closed?
+        ring.close
+        Fiber.current[:hyperion_io_uring] = nil
+      end
+    end
+
+    # Boot-time log line per worker capturing the resolved io_uring
+    # state. Mirrors the `log_ktls_state_once` pattern from 2.2.0.
+    # Single-shot via the class-level ivar so multi-worker boots
+    # don't fan into N identical lines.
+    def log_io_uring_state_once
+      return if Hyperion::Server.instance_variable_get(:@io_uring_state_logged)
+      return if @io_uring_policy == :off
+
+      Hyperion::Server.instance_variable_set(:@io_uring_state_logged, true)
+      runtime_logger.info do
+        {
+          message: 'io_uring accept policy resolved',
+          policy: @io_uring_policy,
+          active: @io_uring_active,
+          supported: Hyperion::IOUring.supported?
+        }
+      end
+    rescue StandardError
+      nil
+    end
+
     def dispatch(socket)
-      if socket.is_a?(::OpenSSL::SSL::SSLSocket) && socket.alpn_protocol == 'h2'
-        # HTTP/2: each stream runs on a fiber inside Http2Handler. The
-        # handler still uses the pool's `#call` for app.call hops on each
-        # stream (one per stream, not one per connection). Per-stream
-        # counters live inside Http2Handler; we don't bump either of the
-        # H1 dispatch buckets here — neither fits the h2 model cleanly.
-        Http2Handler.new(app: @app, thread_pool: @thread_pool, h2_settings: @h2_settings).serve(socket)
-      elsif inline_h1_dispatch?
+      alpn = socket.is_a?(::OpenSSL::SSL::SSLSocket) ? socket.alpn_protocol : nil
+      mode = DispatchMode.resolve(tls: !@tls.nil?, async_io: @async_io,
+                                  thread_count: @thread_count, alpn: alpn)
+      case mode.name
+      when :tls_h2
+        # HTTP/2: each stream runs on a fiber inside Http2Handler. Per-
+        # stream counters live there. We bump the per-mode counter
+        # (`:requests_dispatch_tls_h2`) at connection-accept time so
+        # operators see the connection's chosen transport even when the
+        # h2 streams happen on later fibers.
+        record_dispatch(mode)
+        Http2Handler.new(app: @app, thread_pool: @thread_pool,
+                         h2_settings: @h2_settings,
+                         runtime: @explicit_runtime ? @runtime : nil,
+                         h2_admission: @h2_admission).serve(socket)
+      when :tls_h1_inline, :async_io_h1_inline
         # Inline-on-fiber HTTP/1.1 dispatch. Two ways to land here:
         #   1. async_io: true — operator explicitly opted into fiber I/O on
         #      the plain HTTP/1.1 path.
@@ -202,44 +565,85 @@ module Hyperion
         #      for no perf benefit (we paid the Async-loop cost already)
         #      and would defeat hyperion-async-pg / async-redis on the
         #      TLS h1 path.
-        # Operators who specifically want TLS+threadpool (e.g. CPU-heavy
-        # handlers competing for OS threads) can pass async_io: false to
-        # force the pool branch below.
-        Hyperion.metrics.increment(:requests_async_dispatched)
-        Connection.new.serve(socket, @app, max_request_read_seconds: @max_request_read_seconds)
-      elsif @thread_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
+                       )
+      when :threadpool_h1
         # HTTP/1.1 default plain-HTTP path, OR explicit async_io: false on
         # TLS (operator opted out of inline-on-fiber dispatch). Hand the
         # connection to a worker thread; the fiber that called dispatch
         # returns immediately. On overflow, reject with 503 + close.
-        if @thread_pool.submit_connection(socket, @app,
-                                          max_request_read_seconds: @max_request_read_seconds)
-          Hyperion.metrics.increment(:requests_threadpool_dispatched)
+        if @thread_pool
+          if @thread_pool.submit_connection(socket, @app,
+                                            max_request_read_seconds: @max_request_read_seconds)
+            record_dispatch(mode)
+          else
+            reject_connection(socket)
+          end
         else
-          reject_connection(socket)
+          # `run_one` / spec entry points dispatch without having
+          # started the pool — serve inline and count under
+          # threadpool_h1 (the connection's logical mode).
+          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
-      else
-        # No pool (thread_count: 0) on the TLS / async-wrap path with
-        # async_io: false. Rare config — neither dispatch bucket fits
-        # cleanly. Leave un-counted rather than misclassify; the request
-        # still shows up in :requests_total via Connection.
-        Connection.new.serve(socket, @app, max_request_read_seconds: @max_request_read_seconds)
+      when :inline_h1_no_pool
+        # `-t 0` on the TLS / async-wrap path. Rare config — debug /
+        # spec aid (RFC §5 Q3 keeps `--async-io -t 0` valid). Counted
+        # under its own bucket now (pre-1.7 it was un-counted).
+        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
 
-    # Decide whether to serve HTTP/1.1 inline on the calling fiber instead
-    # of hopping through the worker thread pool. The matrix:
-    #   async_io == true       → inline always (plain h1 + TLS h1).
-    #   async_io == nil + TLS  → inline (TLS already runs Async loop, so
-    #                            the scheduler is current; preserve it).
-    #   async_io == nil + plain → pool (pure HTTP/1.1 fast path; no scheduler).
-    #   async_io == false       → pool always (explicit opt-out).
-    def inline_h1_dispatch?
-      return true if @async_io == true
-      return false if @async_io == false
-
-      # @async_io.nil? — auto: inline on TLS, pool on plain.
-      !@tls.nil?
+    # Resolve the metrics sink for write-side ops. When the operator
+    # passed an explicit `runtime:` we honour it; otherwise we read
+    # the module-level singleton (`Hyperion.metrics`) so 1.6.x test
+    # stubs (`allow(Hyperion).to receive(:metrics)`) keep working.
+    def runtime_metrics
+      @explicit_runtime ? @runtime.metrics : Hyperion.metrics
+    end
+
+    def runtime_logger
+      @explicit_runtime ? @runtime.logger : Hyperion.logger
+    end
+
+    # Bump the per-mode dispatch counter. 1.7→1.8 dual-emitted under the
+    # legacy `:requests_async_dispatched` / `:requests_threadpool_dispatched`
+    # keys for one full release cycle so operators could migrate Grafana
+    # boards. 2.0 retires the legacy keys: only `:requests_dispatch_<mode>`
+    # is emitted (one of `:requests_dispatch_threadpool_h1`,
+    # `:requests_dispatch_inline_h1_no_pool`, `:requests_dispatch_tls_h1_inline`,
+    # `:requests_dispatch_async_io_h1_inline`, `:requests_dispatch_tls_h2`).
+    def record_dispatch(mode)
+      runtime_metrics.increment(mode.metric_key)
+    end
+
+    # Spawn the optional sibling admin listener (RFC A8). When
+    # `admin.listener_port` is unset (default), admin endpoints stay
+    # mounted in-app via `AdminMiddleware` — no behaviour change.
+    def maybe_start_admin_listener
+      return unless @admin_listener_port
+      return if @admin_token.nil? || @admin_token.empty?
+
+      @admin_listener = Hyperion::AdminListener.new(
+        host: @admin_listener_host,
+        port: @admin_listener_port,
+        token: @admin_token,
+        runtime: @runtime
+      )
+      @admin_listener.start
     end
 
     # Backpressure rejection. Emits a pre-built 503 + closes the socket.
@@ -249,7 +653,7 @@ module Hyperion
     # can alert on sustained overload.
     def reject_connection(socket)
       socket.write(REJECT_503)
-      Hyperion.metrics.increment(:rejected_connections)
+      runtime_metrics.increment(:rejected_connections)
     rescue StandardError
       # Client may have hung up between accept and our 503 write — that's
       # the failure mode we're protecting them from anyway, so swallow.
@@ -275,6 +679,11 @@ module Hyperion
         ssl = ::OpenSSL::SSL::SSLSocket.new(raw, @ssl_ctx)
         ssl.sync_close = true
         ssl.accept # blocks; under Async this yields cooperatively via the scheduler
+        log_ktls_state_once(ssl)
+        # 2.4-C: bump the per-worker active-kTLS-connections gauge if
+        # the kernel module accepted this connection. Connection#serve
+        # decrements on close.
+        Hyperion::TLS.track_ktls_handshake!(ssl)
         ssl
       else
         socket, = listening_io.accept_nonblock
@@ -286,7 +695,7 @@ module Hyperion
       @stopped = true
       nil
     rescue OpenSSL::SSL::SSLError => e
-      Hyperion.logger.warn { { message: 'tls handshake failed', error: e.message } }
+      runtime_logger.warn { { message: 'tls handshake failed', error: e.message } }
       nil
     end
 
@@ -296,13 +705,43 @@ module Hyperion
         ssl = ::OpenSSL::SSL::SSLSocket.new(raw, @ssl_ctx)
         ssl.sync_close = true
         ssl.accept
+        log_ktls_state_once(ssl)
+        Hyperion::TLS.track_ktls_handshake!(ssl)
         ssl
       else
         socket, = @server.accept
         socket
       end
     rescue OpenSSL::SSL::SSLError => e
-      Hyperion.logger.warn { { message: 'tls handshake failed', error: e.message } }
+      runtime_logger.warn { { message: 'tls handshake failed', error: e.message } }
+      nil
+    end
+
+    # 2.2.0 (Phase 9): emit a single info-level log line per worker boot
+    # capturing whether kTLS_TX engaged for this listener and which cipher
+    # the first connection landed on. The cipher is per-connection (not
+    # per-context), so we wait for the first successful handshake — at
+    # that point either the kernel module is in use or the listener fell
+    # back to userspace SSL_write. Subsequent connections skip the log
+    # via `@ktls_logged`.
+    def log_ktls_state_once(ssl)
+      return if @ktls_logged
+
+      @ktls_logged = true
+      cipher_name = ssl.cipher && ssl.cipher.first rescue nil # rubocop:disable Style/RescueModifier
+      ktls_active = Hyperion::TLS.ktls_active?(ssl)
+      runtime_logger.info do
+        {
+          message: 'tls listener ready',
+          ktls_policy: @tls_ktls,
+          ktls_supported: Hyperion::TLS.ktls_supported?,
+          ktls_active: ktls_active,
+          cipher: cipher_name
+        }
+      end
+    rescue StandardError
+      # Logging is best-effort — never let a log line take down the
+      # accept loop.
       nil
     end
 
@@ -317,10 +756,35 @@ module Hyperion
         timeval = [@read_timeout, 0].pack('l_l_')
         target.setsockopt(::Socket::SOL_SOCKET, ::Socket::SO_RCVTIMEO, timeval)
       end
+      apply_tcp_nodelay(target)
     rescue StandardError => e
-      Hyperion.logger.warn do
+      runtime_logger.warn do
         { message: 'failed to set read timeout', error: e.message, error_class: e.class.name }
       end
     end
+
+    # 2.10-G — disable Nagle so HTTP/2 stream responses (and any small-payload
+    # write that doesn't already coalesce head+body via the 2.0.1 Phase 8 path)
+    # don't stall ~40 ms on the client's delayed-ACK timer.
+    #
+    # Symptom that surfaced this: 2.9-B Falcon comparison flagged Hyperion's
+    # h2 max-latency stuck at ~40 ms across all rows; the 2.10-G bench showed
+    # the **min** latency was 40.6 ms (every stream, not just the first).
+    # That's the canonical Linux delayed-ACK + Nagle interaction —
+    # protocol-http2 emits HEADERS and DATA as separate framer writes, the
+    # first arrives at the peer alone, the peer waits 40 ms for an ACK so it
+    # can piggyback, Hyperion's writer fiber waits because Nagle is buffering
+    # the DATA frame until the HEADERS ACK lands. TCP_NODELAY breaks the
+    # cycle — every framer write goes out immediately.
+    #
+    # Cost: a few extra TCP packets for chatty streams. Worth it; Falcon and
+    # Agoo both set TCP_NODELAY.
+    def apply_tcp_nodelay(target)
+      target.setsockopt(::Socket::IPPROTO_TCP, ::Socket::TCP_NODELAY, 1)
+    rescue StandardError
+      # SSLSocket-without-#io, UDPSocket, or platform without TCP_NODELAY
+      # (Windows-on-WSL2 occasionally). Silently skip — the socket still
+      # works; only delayed-ACK behavior is affected.
+    end
   end
 end