hyperion-rb 1.6.2 → 2.11.0

data/lib/hyperion/io_uring.rb

@@ -0,0 +1,317 @@
+# frozen_string_literal: true
+
+require 'etc'
+require 'fiddle'
+require 'fiddle/import'
+
+module Hyperion
+  # 2.3-A — io_uring accept on Linux 5.6+ (opt-in).
+  #
+  # The biggest unmovable bottleneck below the GVL on the plaintext h1
+  # path is the kernel accept loop: every accept costs accept_nonblock +
+  # IO.select on the EAGAIN edge (two syscalls per accepted connection
+  # under burst). io_uring lets us submit accept SQEs and reap CQEs in
+  # one syscall, with the kernel batching multiple accepts in a single
+  # CQE drain when connections arrive faster than the fiber can consume
+  # them.
+  #
+  # ## Surface
+  #
+  #   Hyperion::IOUring.supported?   # bool — Linux ≥ 5.6 + cdylib loaded
+  #                                  #        + runtime probe succeeds
+  #   Hyperion::IOUring::Ring.new(queue_depth: 256)
+  #                                  # per-fiber ring; #accept(fd) → fd
+  #                                  # or :wouldblock; #close releases
+  #                                  # the ring's SQ/CQ memory.
+  #
+  # ## Per-fiber, NEVER per-process or per-thread
+  #
+  # io_uring under fork+threads has known sharp edges:
+  #
+  #   * Submission queue is process-shared by default — under fork, the
+  #     parent's outstanding SQEs leak into the child's CQ.
+  #   * IORING_SETUP_SQPOLL kernel thread does not survive fork.
+  #   * Threads sharing a ring need IORING_SETUP_SINGLE_ISSUER + careful
+  #     submission discipline.
+  #
+  # Hyperion's safe pattern, matching the fiber-per-conn architecture:
+  #
+  #   * One ring per fiber that needs it (the accept fiber, optionally
+  #     per-connection read fibers in a future phase).
+  #   * Ring is opened lazily on first use:
+  #       Fiber.current[:hyperion_io_uring] ||=
+  #         Hyperion::IOUring::Ring.new(queue_depth: 256)
+  #   * Ring is closed when the fiber exits.
+  #   * Workers don't share rings across fork — each child opens its own.
+  #
+  # ## Default off in 2.3.0
+  #
+  # Mirrors the 2.2.0 fix-B HYPERION_H2_NATIVE_HPACK pattern: ship the
+  # plumbing in 2.3.0 with the default OFF, give operators an env-var to
+  # A/B (HYPERION_IO_URING={on,auto}), flip the default to :auto in
+  # 2.4 only after 6 months of soak. io_uring code in production has
+  # too many sharp edges to default-on without field validation.
+  module IOUring
+    EXPECTED_ABI = 1
+    # Linux 5.6 stabilized IORING_OP_ACCEPT (commit 17f2fe35d080,
+    # mainlined Mar 2020). 5.5 had a buggy precursor that the io-uring
+    # crate refuses to use. We gate on 5.6 to match the crate's stance.
+    MIN_LINUX_KERNEL = [5, 6].freeze
+
+    class Unsupported < StandardError; end
+
+    # Per-Ring instance. Wraps the opaque pointer returned by
+    # `hyperion_io_uring_ring_new` and exposes the accept / read
+    # primitives over Fiddle.
+    class Ring
+      DEFAULT_QUEUE_DEPTH = 256
+
+      def initialize(queue_depth: DEFAULT_QUEUE_DEPTH)
+        raise Unsupported, 'io_uring not supported on this platform' unless IOUring.supported?
+
+        @ptr = IOUring.ring_new(queue_depth.to_i)
+        raise Unsupported, 'io_uring_setup failed at ring allocation' if @ptr.nil? || @ptr.null?
+
+        # `errno` scratch — reused across calls. Fiddle::Pointer to a
+        # 4-byte buffer that the C side writes into on error. Saves
+        # one Pointer allocation per accept.
+        @errno_buf = Fiddle::Pointer.malloc(4, Fiddle::RUBY_FREE)
+        @closed = false
+      end
+
+      # Accept one connection on `listener_fd`. Returns the integer
+      # client fd, or `:wouldblock` on EAGAIN. Raises on hard errors.
+      #
+      # The ring's submit_and_wait drives io_uring_enter with
+      # min_complete=1, so this fiber parks here until the kernel
+      # delivers the matching CQE. Under Async, the Ruby side calls
+      # this from a Fiber — the fiber is logically blocked but the
+      # OS thread keeps running other fibers via the scheduler ONLY
+      # if `submit_and_wait` itself yields. It does not yield (it's
+      # a syscall under FFI), so the accept fiber must be the only
+      # fiber with work-pending on its OS thread. In Hyperion's
+      # default 1-accept-fiber-per-worker shape that's always true.
+      def accept(listener_fd)
+        raise IOError, 'ring closed' if @closed
+
+        rc = IOUring.ring_accept(@ptr, listener_fd.to_i, @errno_buf)
+        return rc if rc.positive? || rc.zero?
+        return :wouldblock if rc == -1
+
+        errno = @errno_buf.to_str(4).unpack1('l<')
+        # ECANCELED / EBADF / EINTR → caller treats as wouldblock and
+        # loops. Anything else is a hard error.
+        return :wouldblock if [4, 9, 103, 125].include?(errno) # EINTR / EBADF / ECONNABORTED / ECANCELED
+
+        raise SystemCallError.new('io_uring accept failed', errno)
+      end
+
+      # Read up to `max` bytes from `fd` into a fresh ASCII-8BIT
+      # String. 2.3-A ships this for the accept-only path's sibling
+      # use (per-connection short reads); the connection layer keeps
+      # using regular `read_nonblock` until a future 2.3-x round wires
+      # io_uring reads into the request-line + header parse.
+      def read(fd, max: 4096)
+        raise IOError, 'ring closed' if @closed
+
+        buf = Fiddle::Pointer.malloc(max, Fiddle::RUBY_FREE)
+        rc = IOUring.ring_read(@ptr, fd.to_i, buf, max.to_i, @errno_buf)
+        return buf.to_str(rc) if rc >= 0
+        return :wouldblock if rc == -1
+
+        errno = @errno_buf.to_str(4).unpack1('l<')
+        raise SystemCallError.new('io_uring read failed', errno)
+      end
+
+      # Close the ring + free its SQ/CQ memory. Idempotent — calling
+      # twice is a no-op (we null-out @ptr after the first free). Must
+      # be called from the same fiber that opened the ring.
+      def close
+        return if @closed
+
+        @closed = true
+        IOUring.ring_free(@ptr) if @ptr && !@ptr.null?
+        @ptr = nil
+      end
+
+      def closed?
+        @closed
+      end
+    end
+
+    class << self
+      # Cached three-state result: nil = not-yet-probed, true/false = result.
+      #
+      # The probe is intentionally process-local (not Fiber-local) — the
+      # answer is the same for every fiber in this process, and probing
+      # once at boot avoids per-request syscall overhead.
+      def supported?
+        return @supported unless @supported.nil?
+
+        @supported = compute_supported
+      end
+
+      # Test seam: clear cached probe so `supported?` re-runs. Used by
+      # specs that stub Etc.uname or RbConfig.
+      def reset!
+        @supported = nil
+        @lib = nil
+      end
+
+      # ---- Internal: feature gate ----
+
+      def compute_supported
+        # Gate 1: Linux only. macOS/BSD don't have io_uring.
+        return false unless linux?
+
+        # Gate 2: Kernel ≥ 5.6.
+        return false unless kernel_supports_io_uring?
+
+        # Gate 3: cdylib loaded.
+        load!
+        return false unless @lib
+
+        # Gate 4: runtime probe — try to set up a tiny ring. Catches
+        # sandboxed containers (seccomp blocking io_uring_setup,
+        # locked-down environments returning -EPERM, kernels with
+        # io_uring disabled via /proc/sys/kernel/io_uring_disabled).
+        rc = @probe_fn.call
+        rc.zero?
+      rescue StandardError
+        false
+      end
+
+      def linux?
+        Etc.uname[:sysname] == 'Linux'
+      rescue StandardError
+        false
+      end
+
+      def kernel_supports_io_uring?
+        return false unless linux?
+
+        release = parse_kernel_release
+        return false unless release
+
+        major, minor = release
+        min_major, min_minor = MIN_LINUX_KERNEL
+        major > min_major || (major == min_major && minor >= min_minor)
+      end
+
+      # `Etc.uname[:release]` is the canonical source. Falls back to
+      # `/proc/sys/kernel/osrelease` when uname isn't available (e.g.
+      # specs that stub Etc.uname[:sysname] but leave release alone).
+      def parse_kernel_release
+        release = Etc.uname[:release].to_s
+        if release.empty? && File.exist?('/proc/sys/kernel/osrelease')
+          release = File.read('/proc/sys/kernel/osrelease').strip
+        end
+        m = release.match(/\A(\d+)\.(\d+)/)
+        return nil unless m
+
+        [m[1].to_i, m[2].to_i]
+      rescue StandardError
+        nil
+      end
+
+      # ---- Internal: Fiddle loader ----
+
+      def load!
+        return @lib if defined?(@lib) && !@lib.nil?
+
+        path = candidate_paths.find { |p| File.exist?(p) }
+        unless path
+          @lib = nil
+          return nil
+        end
+
+        @lib = Fiddle.dlopen(path)
+        @abi_fn = Fiddle::Function.new(@lib['hyperion_io_uring_abi_version'],
+                                       [], Fiddle::TYPE_INT)
+        abi = @abi_fn.call
+        if abi != EXPECTED_ABI
+          warn "[hyperion] IOUring ABI mismatch (got #{abi}, expected #{EXPECTED_ABI}); falling back"
+          @lib = nil
+          return nil
+        end
+
+        @probe_fn = Fiddle::Function.new(@lib['hyperion_io_uring_probe'],
+                                         [], Fiddle::TYPE_INT)
+        @ring_new_fn = Fiddle::Function.new(@lib['hyperion_io_uring_ring_new'],
+                                            [Fiddle::TYPE_INT], Fiddle::TYPE_VOIDP)
+        @ring_free_fn = Fiddle::Function.new(@lib['hyperion_io_uring_ring_free'],
+                                             [Fiddle::TYPE_VOIDP], Fiddle::TYPE_VOID)
+        @accept_fn = Fiddle::Function.new(@lib['hyperion_io_uring_accept'],
+                                          [Fiddle::TYPE_VOIDP, Fiddle::TYPE_INT, Fiddle::TYPE_VOIDP],
+                                          Fiddle::TYPE_INT)
+        @read_fn = Fiddle::Function.new(@lib['hyperion_io_uring_read'],
+                                        [Fiddle::TYPE_VOIDP, Fiddle::TYPE_INT,
+                                         Fiddle::TYPE_VOIDP, Fiddle::TYPE_INT,
+                                         Fiddle::TYPE_VOIDP],
+                                        Fiddle::TYPE_INT)
+        @lib
+      rescue Fiddle::DLError, StandardError => e
+        warn "[hyperion] IOUring failed to load (#{e.class}: #{e.message}); falling back to epoll"
+        @lib = nil
+        nil
+      end
+
+      def candidate_paths
+        gem_lib = File.expand_path('../hyperion_io_uring', __dir__)
+        ext_target = File.expand_path('../../ext/hyperion_io_uring/target/release', __dir__)
+        %w[libhyperion_io_uring.dylib libhyperion_io_uring.so].flat_map do |name|
+          [File.join(gem_lib, name), File.join(ext_target, name)]
+        end
+      end
+
+      # ---- FFI wrappers ----
+
+      def ring_new(depth)
+        ptr = @ring_new_fn.call(depth)
+        ptr.null? ? nil : ptr
+      end
+
+      def ring_free(ptr)
+        @ring_free_fn.call(ptr)
+      end
+
+      def ring_accept(ptr, fd, errno_buf)
+        @accept_fn.call(ptr, fd, errno_buf)
+      end
+
+      def ring_read(ptr, fd, buf, max, errno_buf)
+        @read_fn.call(ptr, fd, buf, max, errno_buf)
+      end
+    end
+
+    # ---- Server-side helpers ----
+
+    # Resolve the operator's `io_uring` policy + the runtime gate
+    # into a boolean "use io_uring on this server". Called by Server
+    # at boot.
+    #
+    # Policy values:
+    #   :off  → never. Returns false. Used for the 2.3.0 default.
+    #   :auto → use it when supported; quietly fall back otherwise.
+    #   :on   → demand it. Raise UnsupportedError if not available
+    #           so the operator's misconfig surfaces at boot, not as
+    #           a slow-fallback mystery hours later.
+    def self.resolve_policy!(policy)
+      case policy
+      when :off, nil, false
+        false
+      when :auto
+        supported?
+      when :on, true
+        unless supported?
+          raise Unsupported,
+                'io_uring required (io_uring: :on) but not supported on this host ' \
+                "(linux=#{linux?}, kernel_ok=#{kernel_supports_io_uring?}, lib_loaded=#{!@lib.nil?})"
+        end
+        true
+      else
+        raise ArgumentError, "io_uring must be :off, :auto, or :on (got #{policy.inspect})"
+      end
+    end
+  end
+end

data/lib/hyperion/lint_wrapper_pool.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'rack/lint'
+
+module Hyperion
+  # Phase 2a (1.7.1) — per-worker `Rack::Lint::Wrapper` pool.
+  #
+  # In dev mode (`RACK_ENV != 'production'`), Rack guidance is to wrap the
+  # response body with a `Rack::Lint::Wrapper` so spec violations surface
+  # immediately. The naive shape is one wrapper allocation per request. On a
+  # high-rps dev/staging fleet that's a measurable allocation tax — every
+  # wrapper carries 8 ivars and a non-trivial init.
+  #
+  # The pool keeps up to `MAX_POOL_SIZE` reusable wrappers per worker fiber
+  # scheduler. On request entry, callers `acquire(app, env)` to get a
+  # ready-to-go wrapper. On response close, callers `release(wrapper)` to put
+  # it back in the free list. The wrapper's per-request state (`@app`, `@env`,
+  # `@response`, status/headers/body, content-length tracking) is reset before
+  # reuse so each request gets clean state.
+  #
+  # Safety:
+  #   * Production short-circuit: `acquire` always allocates fresh in
+  #     `RACK_ENV=production` so production never carries pool overhead and
+  #     never reuses a wrapper that's mid-iteration on another fiber.
+  #   * Pool cap: `MAX_POOL_SIZE` bounds steady-state memory. Excess wrappers
+  #     fall out of scope and the GC reaps them.
+  #   * Single-thread safety: each Hyperion worker runs one fiber scheduler on
+  #     one thread, so the underlying `Pool` is contention-free. We don't add
+  #     a Mutex — that would be measurable overhead for zero correctness gain
+  #     in the supported deployment shape. If a host embeds Hyperion in a
+  #     multi-thread context the pool simply won't be reused (each thread
+  #     allocates fresh; no corruption).
+  #
+  # Lint semantics are unchanged: every reused wrapper still validates the
+  # body each request via `check_environment`/`check_headers`/etc. inside
+  # `Rack::Lint::Wrapper#response`. The only thing reuse skips is the
+  # allocation itself — not the validation work.
+  module LintWrapperPool
+    MAX_POOL_SIZE = 32
+
+    # Reset hook — clear all per-request ivars on a wrapper before it goes
+    # back into the free list. Mirrors `Rack::Lint::Wrapper#initialize` so
+    # that the wrapper looks freshly-constructed on the next acquire.
+    RESET = lambda do |wrapper|
+      wrapper.instance_variable_set(:@app, nil)
+      wrapper.instance_variable_set(:@env, nil)
+      wrapper.instance_variable_set(:@response, nil)
+      wrapper.instance_variable_set(:@head_request, false)
+      wrapper.instance_variable_set(:@status, nil)
+      wrapper.instance_variable_set(:@headers, nil)
+      wrapper.instance_variable_set(:@body, nil)
+      wrapper.instance_variable_set(:@consumed, nil)
+      wrapper.instance_variable_set(:@content_length, nil)
+      wrapper.instance_variable_set(:@closed, false)
+      wrapper.instance_variable_set(:@size, 0)
+      wrapper
+    end
+
+    class << self
+      # Whether this process should pool Lint wrappers. False in production
+      # (Lint is a dev tool; production never inserts it) and false when
+      # explicitly disabled via `RACK_LINT_DISABLE=1` for operators who want
+      # to side-step the pool entirely.
+      def enabled?
+        return false if production?
+        return false if ENV['RACK_LINT_DISABLE'] == '1'
+
+        true
+      end
+
+      def production?
+        ENV['RACK_ENV'] == 'production'
+      end
+
+      # Acquire a wrapper for `(app, env)`. In production we always allocate
+      # fresh (skipping the pool entirely). Outside production we pop a
+      # reusable wrapper, rebind it to (app, env) via the reset hook + ivar
+      # writes, and return it ready for `#response`.
+      #
+      # The returned wrapper behaves identically to `Rack::Lint::Wrapper.new(app, env)`.
+      def acquire(app, env)
+        if enabled?
+          wrapper = pool.acquire
+          wrapper.instance_variable_set(:@app, app)
+          wrapper.instance_variable_set(:@env, env)
+          wrapper
+        else
+          ::Rack::Lint::Wrapper.new(app, env)
+        end
+      end
+
+      # Release a wrapper back to the pool. No-op in production (where
+      # `acquire` returned a fresh allocation that the GC will reap). The
+      # underlying `Hyperion::Pool` enforces MAX_POOL_SIZE; releases past
+      # the cap drop the wrapper on the floor.
+      def release(wrapper)
+        return unless enabled?
+        return unless wrapper.is_a?(::Rack::Lint::Wrapper)
+
+        pool.release(wrapper)
+      end
+
+      # Test seam: clear the free list so spec runs that toggle RACK_ENV
+      # don't see warm wrappers from a previous example.
+      def reset!
+        @pool = nil
+      end
+
+      # Read-only accessor for the underlying pool — used by specs to assert
+      # reuse without relying on `.equal?` identity through `acquire`.
+      def pool_size
+        @pool ? @pool.size : 0
+      end
+
+      private
+
+      def pool
+        @pool ||= Hyperion::Pool.new(
+          max_size: MAX_POOL_SIZE,
+          factory: -> { ::Rack::Lint::Wrapper.allocate },
+          reset: RESET
+        )
+      end
+    end
+  end
+end

data/lib/hyperion/master.rb

@@ -53,11 +53,16 @@ module Hyperion
     # place") doesn't accidentally send a SETTINGS entry with a nil value.
     # Empty hash → no override → Http2Handler skips the SETTINGS push.
     def self.build_h2_settings(config)
+      # 1.7.0 (RFC A4): read from the nested `H2Settings` subconfig.
+      # The flat-name forwarders on `Config` still work for callers
+      # holding a 1.6.x reference, but Master is in-tree so we point
+      # at the nested object directly to avoid the extra hop.
+      h2 = config.h2
       {
-        max_concurrent_streams: config.h2_max_concurrent_streams,
-        initial_window_size: config.h2_initial_window_size,
-        max_frame_size: config.h2_max_frame_size,
-        max_header_list_size: config.h2_max_header_list_size
+        max_concurrent_streams: h2.max_concurrent_streams,
+        initial_window_size: h2.initial_window_size,
+        max_frame_size: h2.max_frame_size,
+        max_header_list_size: h2.max_header_list_size
       }.compact
     end
 
@@ -72,21 +77,32 @@ module Hyperion
       @tls          = tls
       @thread_count = thread_count
       @config       = config || Hyperion::Config.new
+      # 2.0 default flip (RFC A7): if the operator hasn't already
+      # finalized the config (e.g. via the CLI bootstrap path), do it
+      # now so the worker count for the auto-cap formula is the one
+      # Master actually uses. `finalize!` is idempotent — a config the
+      # CLI already finalized passes through unchanged.
+      @config.finalize!(workers: @workers || 1)
       @graceful_timeout = @config.graceful_timeout || GRACEFUL_TIMEOUT_SECONDS
       @children     = {} # pid => worker_index
       @next_index   = 0
       @stopping     = false
       @worker_model = self.class.detect_worker_model
       @listener     = nil # populated only in :share mode
-      @worker_max_rss_mb     = @config.worker_max_rss_mb
-      @worker_check_interval = @config.worker_check_interval || 30
+      @worker_max_rss_mb     = @config.worker_health.max_rss_mb
+      @worker_check_interval = @config.worker_health.check_interval || 30
       @last_health_check     = 0  # monotonic seconds
       @cycling               = {} # pid => true while we wait for it to exit
     end
 
     def run
       install_signal_handlers
-      bind_master_listener if @worker_model == :share
+      # Record master PID + export to ENV BEFORE the first fork. Workers
+      # inherit the env var via copy-on-write so AdminMiddleware can target
+      # the master regardless of whether `Process.ppid` is meaningful in
+      # the deployment (containerd / Docker run hyperion as PID 1, where
+      # ppid would point at the host's init or 0). See Hyperion.master_pid.
+      Hyperion.master_pid!(Process.pid)
       Hyperion.logger.info do
         {
           message: 'master starting',
@@ -108,8 +124,20 @@ module Hyperion
       # Operators use it to close shared resources (DB pools, Redis sockets)
       # so each child gets fresh connections rather than inheriting the
       # parent's open fds. Mirrors Puma's hook of the same name.
+      #
+      # IMPORTANT: must fire BEFORE the master binds its listening socket on
+      # `:share` mode. In `:reuseport` mode the master never binds — workers
+      # bind their own SO_REUSEPORT sockets after fork — so `before_fork`
+      # there trivially runs "before any listener exists." Pre-1.6.3 we
+      # bound the master listener first on `:share` and ran `before_fork`
+      # afterwards, which made the two worker models hand off the lifecycle
+      # asymmetrically: an operator using `before_fork` to mutate listening
+      # behaviour saw a different world depending on host OS. Binding here
+      # restores symmetry — in both modes `before_fork` precedes any socket.
       @config.before_fork.each(&:call)
 
+      bind_master_listener if @worker_model == :share
+
       @workers.times { spawn_worker }
 
       supervise
@@ -132,6 +160,41 @@ module Hyperion
         end
       end
       @shutdown_pipe = shutdown_r
+      install_tls_rotation_handler
+    end
+
+    # Wire the master-side handler for the configured TLS ticket-key
+    # rotation signal (default SIGUSR2). When the operator (or an
+    # automated rotation cron) sends SIGUSR2 to the master, we re-emit
+    # it to every live child so each worker flushes its session cache
+    # and OpenSSL rolls a fresh ticket-encryption key.
+    #
+    # The master deliberately does NOT mutate its own listener context
+    # in `:share` mode — the listening fd is shared across children, so
+    # the children's per-context flushes already cover the resumption
+    # pool. This keeps the master accept-loop free.
+    def install_tls_rotation_handler
+      return unless @tls
+
+      sig = @config.tls.ticket_key_rotation_signal
+      return if sig.nil? || sig == :NONE
+
+      Signal.trap(sig.to_s) do
+        @children.each_key do |pid|
+          Process.kill(sig.to_s, pid)
+        rescue StandardError
+          # Worker already exiting / reaped — the next reap_and_respawn
+          # cycle will replace it; rotation does not block on liveness.
+          nil
+        end
+      end
+    rescue ArgumentError
+      Hyperion.logger.warn do
+        {
+          message: 'invalid tls.ticket_key_rotation_signal on master; rotation disabled',
+          signal: @config.tls.ticket_key_rotation_signal
+        }
+      end
     end
 
     # Bind the listening socket in the master so children inherit the fd
@@ -143,7 +206,9 @@ module Hyperion
       @port = tcp.addr[1]
 
       if @tls
-        ctx = TLS.context(cert: @tls[:cert], key: @tls[:key])
+        ctx = TLS.context(cert: @tls[:cert], key: @tls[:key],
+                          session_cache_size: @config.tls.session_cache_size,
+                          ktls: @config.tls.ktls)
         ssl_server = ::OpenSSL::SSL::SSLServer.new(tcp, ctx)
         ssl_server.start_immediately = false
         @listener = ssl_server
@@ -167,7 +232,29 @@ module Hyperion
           max_pending: @config.max_pending,
           max_request_read_seconds: @config.max_request_read_seconds,
           h2_settings: Master.build_h2_settings(@config),
-          async_io: @config.async_io
+          async_io: @config.async_io,
+          # 1.7.0 RFC additive plumbing — all default to current
+          # behaviour when the operator hasn't opted in.
+          accept_fibers_per_worker: @config.accept_fibers_per_worker,
+          h2_max_total_streams: @config.h2.max_total_streams,
+          admin_listener_port: @config.admin.listener_port,
+          admin_listener_host: @config.admin.listener_host,
+          admin_token: @config.admin.token,
+          # 1.8.0 Phase 4 — TLS session resumption knobs.
+          tls_session_cache_size: @config.tls.session_cache_size,
+          tls_ticket_key_rotation_signal: @config.tls.ticket_key_rotation_signal,
+          # 2.2.0 Phase 9 — kernel TLS_TX policy.
+          tls_ktls: @config.tls.ktls,
+          # 2.3-A — io_uring accept policy.
+          io_uring: @config.io_uring,
+          # 2.3-B — per-conn fairness cap + TLS handshake CPU throttle.
+          max_in_flight_per_conn: @config.max_in_flight_per_conn,
+          tls_handshake_rate_limit: @config.tls.handshake_rate_limit,
+          # 2.10-E — boot-time static asset preload list (resolved from
+          # operator config + Rails auto-detect at master boot, not in
+          # each child, so the spec/log line for auto-detect appears once
+          # per cluster rather than once per worker).
+          preload_static_dirs: @config.resolved_preload_static_dirs
         }
         # Hand the inherited socket to the worker in :share mode. In
         # :reuseport mode the worker binds its own with SO_REUSEPORT.

data/lib/hyperion/metrics/path_templater.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Hyperion
+  class Metrics
+    # 2.4-C — turn raw request paths into low-cardinality templates so the
+    # per-route histogram doesn't blow up to one label-set per `/users/<id>`.
+    #
+    # The default rules collapse `/users/123` → `/users/:id` and
+    # `/orders/3fa85f64-5717-4562-b3fc-2c963f66afa6` → `/orders/:uuid`. They
+    # cover the bulk of real-world REST paths; operators with Rails-style
+    # routes (`/articles/cool-slug-2024`) plug in their own rules via
+    # `Hyperion::Config#metrics.path_templater = MyTemplater.new`.
+    #
+    # An LRU cache keyed on the raw path side-steps repeating the regex walk
+    # on every keep-alive request to the same handler. 1000 entries is sized
+    # for typical Rails-shape apps (sub-1000 unique route templates); apps
+    # with more should pass `lru_size:` explicitly.
+    class PathTemplater
+      DEFAULT_RULES = [
+        [/\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/i, ':uuid'],
+        [/\b\d+\b/, ':id']
+      ].freeze
+
+      DEFAULT_LRU_SIZE = 1000
+
+      attr_reader :lru_size
+
+      def initialize(rules: DEFAULT_RULES, lru_size: DEFAULT_LRU_SIZE)
+        @rules    = rules
+        @lru_size = lru_size
+        @cache    = {} # Insertion-ordered Hash doubles as an LRU.
+        @mutex    = Mutex.new
+      end
+
+      # Translate a raw request path into its template form. The result
+      # is memoized in the LRU; a cache hit is a single Hash#[] +
+      # re-insert (touch). On miss we run the regex chain and trim the
+      # oldest entry if we exceed `lru_size`.
+      def template(path)
+        return path if path.nil? || path.empty?
+
+        @mutex.synchronize do
+          if (cached = @cache.delete(path))
+            # Re-insert to mark "recently used" (Ruby Hashes preserve
+            # insertion order, oldest = first key).
+            @cache[path] = cached
+            return cached
+          end
+
+          templated = compute(path)
+          @cache[path] = templated
+          @cache.shift if @cache.size > @lru_size
+          templated
+        end
+      end
+
+      def cache_size
+        @mutex.synchronize { @cache.size }
+      end
+
+      private
+
+      def compute(path)
+        @rules.reduce(path) { |p, (regex, replacement)| p.gsub(regex, replacement) }
+      end
+    end
+  end
+end