hyperion-rb 1.6.2 → 2.11.0

data/lib/hyperion/admin_listener.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'rack/utils'
+
+module Hyperion
+  # Sibling HTTP listener for admin endpoints (RFC A8). When the operator
+  # sets `admin.listener_port`, Hyperion spawns a small dedicated server
+  # on `127.0.0.1:<port>` that handles ONLY `/-/quit` and `/-/metrics`
+  # (Prometheus exposition). The application listener is unchanged —
+  # admin paths can stay mounted in-app simultaneously, depending on
+  # whether `AdminMiddleware` is wrapped.
+  #
+  # **Why a sibling listener, not just middleware?** Three failure modes
+  # AdminMiddleware can't escape on its own:
+  #
+  #   1. Misordered `Rack::Builder` middleware can disable admin (a
+  #      `use` of a custom 404 middleware in front of Hyperion's wrap).
+  #   2. Request-headers-logging middleware (`Rack::CommonLogger` derivs,
+  #      OpenTelemetry HTTP instrumentation, app-level header dumpers)
+  #      logs the `X-Hyperion-Admin-Token` value to access logs. The
+  #      sibling listener's path never goes through that pipeline.
+  #   3. Operators who don't want to manually 404 `/-/*` at the edge
+  #      proxy can simply not expose this port.
+  #
+  # **Defence-in-depth, not a replacement for network isolation.** The
+  # bearer token still gates every request. Operators MUST keep this
+  # port on a private interface (default `127.0.0.1`) or behind an
+  # authenticating reverse proxy. Same `secure_match?` logic as
+  # AdminMiddleware.
+  #
+  # **Implementation note.** Single accept thread, no Rack pipeline. We
+  # parse the request line + Authorization header by hand because:
+  #
+  #   * The two endpoints are trivial (drain via SIGTERM; render
+  #     pre-formatted Prometheus text).
+  #   * Pulling in a full Rack stack inside Hyperion to serve two
+  #     endpoints would re-introduce the misordering footgun (#1 above).
+  #   * The bytes per response are tiny — encryption / chunked encoding
+  #     / keep-alive aren't needed.
+  #
+  # Returns 202 + `{"status":"draining"}` on quit, 200 + Prometheus text
+  # on metrics, 401 on bearer mismatch, 404 on anything else.
+  class AdminListener
+    PATH_QUIT    = '/-/quit'
+    PATH_METRICS = '/-/metrics'
+
+    METRICS_CONTENT_TYPE = 'text/plain; version=0.0.4; charset=utf-8'
+    JSON_CONTENT_TYPE    = 'application/json'
+
+    UNAUTHORIZED_BODY = %({"error":"unauthorized"}\n)
+    NOT_FOUND_BODY    = %({"error":"not_found"}\n)
+    DRAINING_BODY     = %({"status":"draining"}\n)
+    SIGNAL_FAILED     = %({"error":"signal_failed"}\n)
+
+    attr_reader :host, :port
+
+    def initialize(host:, port:, token:, runtime: nil, signal_target: nil)
+      raise ArgumentError, 'admin listener token must be a non-empty String' if token.nil? || token.to_s.empty?
+
+      @host          = host
+      @port          = port
+      @token         = token.to_s
+      @runtime       = runtime || Hyperion::Runtime.default
+      @signal_target = signal_target
+      @stopped       = false
+    end
+
+    # Bind + spawn the accept thread. Returns self so callers can chain
+    # `.start.join` or just hold the reference for `#stop`.
+    def start
+      @server = ::TCPServer.new(@host, @port)
+      # Honour port: 0 (let kernel pick) — the test suite uses this so
+      # multiple AdminListeners can coexist without port conflicts.
+      @port = @server.addr[1]
+
+      @thread = Thread.new { accept_loop }
+      @thread.report_on_exception = false
+      @runtime.logger.info do
+        { message: 'admin listener started', host: @host, port: @port,
+          paths: [PATH_QUIT, PATH_METRICS] }
+      end
+      self
+    end
+
+    def stop
+      @stopped = true
+      @server&.close
+      @thread&.join(5)
+      nil
+    rescue StandardError
+      nil
+    end
+
+    private
+
+    def accept_loop
+      until @stopped
+        begin
+          client = @server.accept
+        rescue IOError, Errno::EBADF
+          break # listener closed
+        rescue StandardError => e
+          @runtime.logger.warn { { message: 'admin listener accept error', error: e.message } }
+          next
+        end
+
+        begin
+          handle(client)
+        rescue StandardError => e
+          @runtime.logger.warn { { message: 'admin listener handler error', error: e.message } }
+        ensure
+          begin
+            client.close unless client.closed?
+          rescue StandardError
+            nil
+          end
+        end
+      end
+    end
+
+    # Parse one request off the socket and dispatch. We deliberately don't
+    # implement keep-alive — `Connection: close` on every response is fine
+    # for an admin endpoint that handles ones-of operator probes.
+    def handle(socket)
+      request_line = socket.gets("\r\n", 1024)
+      return write_response(socket, 400, JSON_CONTENT_TYPE, NOT_FOUND_BODY) if request_line.nil?
+
+      method, path, _http = request_line.strip.split(' ', 3)
+      headers = read_headers(socket)
+      # Drain Content-Length body if present (POST /-/quit may carry one).
+      content_length = headers['content-length'].to_i
+      socket.read(content_length) if content_length.positive?
+
+      provided = (headers['x-hyperion-admin-token'] || '').to_s
+      return write_response(socket, 401, JSON_CONTENT_TYPE, UNAUTHORIZED_BODY) unless secure_match?(provided)
+
+      if path == PATH_QUIT && method == 'POST'
+        handle_quit(socket)
+      elsif path == PATH_METRICS && method == 'GET'
+        handle_metrics(socket)
+      else
+        write_response(socket, 404, JSON_CONTENT_TYPE, NOT_FOUND_BODY)
+      end
+    end
+
+    def read_headers(socket)
+      headers = {}
+      while (line = socket.gets("\r\n", 8192))
+        line = line.strip
+        break if line.empty?
+
+        name, value = line.split(':', 2)
+        next if name.nil? || value.nil?
+
+        headers[name.strip.downcase] = value.strip
+      end
+      headers
+    end
+
+    def handle_quit(socket)
+      target = @signal_target || Hyperion.master_pid
+      @runtime.logger.info { { message: 'admin drain requested', target_pid: target, via: 'sibling-listener' } }
+      begin
+        Process.kill('TERM', target)
+      rescue StandardError => e
+        @runtime.logger.warn { { message: 'admin drain signal failed', error: e.message } }
+        return write_response(socket, 500, JSON_CONTENT_TYPE, SIGNAL_FAILED)
+      end
+
+      write_response(socket, 202, JSON_CONTENT_TYPE, DRAINING_BODY)
+    end
+
+    def handle_metrics(socket)
+      body = Hyperion::PrometheusExporter.render(@runtime.metrics.snapshot)
+      write_response(socket, 200, METRICS_CONTENT_TYPE, body)
+    end
+
+    def secure_match?(provided)
+      return false if provided.empty?
+      return false unless provided.bytesize == @token.bytesize
+
+      Rack::Utils.secure_compare(provided, @token)
+    end
+
+    def write_response(socket, status, content_type, body)
+      reason = case status
+               when 200 then 'OK'
+               when 202 then 'Accepted'
+               when 400 then 'Bad Request'
+               when 401 then 'Unauthorized'
+               when 404 then 'Not Found'
+               when 500 then 'Internal Server Error'
+               else 'Unknown'
+               end
+      head = +"HTTP/1.1 #{status} #{reason}\r\n" \
+              "content-type: #{content_type}\r\n" \
+              "content-length: #{body.bytesize}\r\n" \
+              "connection: close\r\n\r\n"
+      socket.write(head)
+      socket.write(body)
+    rescue StandardError
+      # Peer hung up — nothing to do.
+      nil
+    end
+  end
+end

data/lib/hyperion/admin_middleware.rb

@@ -36,8 +36,9 @@ module Hyperion
 
       @app           = app
       @token         = token.to_s
-      # Override hook for tests. Defaults to ppid in worker context, pid
-      # for single-worker context (caller decides).
+      # Override hook for tests. When unset, resolve_signal_target consults
+      # Hyperion.master_pid (master writes itself there at boot, exports
+      # HYPERION_MASTER_PID into ENV so forked workers inherit it).
       @signal_target = signal_target
     end
 
@@ -85,7 +86,16 @@ module Hyperion
     end
 
     def handle_metrics
-      body = PrometheusExporter.render(Hyperion.stats)
+      # 2.4-C: render the full surface — legacy counters + histograms +
+      # gauges + labeled counters. The exporter falls back to the legacy
+      # `render(stats)` body when the sink doesn't expose the new
+      # snapshot helpers (defensive: third-party Metrics adapters that
+      # quack-implement the 1.x surface still emit a valid scrape body).
+      body = if Hyperion.metrics.respond_to?(:histogram_snapshot)
+               PrometheusExporter.render_full(Hyperion.metrics)
+             else
+               PrometheusExporter.render(Hyperion.stats)
+             end
       [200, { 'content-type' => METRICS_CONTENT_TYPE }, [body]]
     end
 
@@ -101,10 +111,29 @@ module Hyperion
     def resolve_signal_target
       return @signal_target if @signal_target
 
-      # In a forked worker, ppid IS the master; in single-worker mode,
-      # the master + worker are the same process — signal self.
-      ppid = Process.ppid
-      ppid > 1 ? ppid : Process.pid
+      # Always prefer the explicitly-recorded master PID. In a worker the
+      # master wrote `HYPERION_MASTER_PID` into ENV before forking, so
+      # `Hyperion.master_pid` returns the master from inside the worker
+      # via inherited ENV. In single-mode the master IS the running
+      # process and `master_pid!` set the ivar in #run_single.
+      #
+      # Why not Process.ppid? Two failure modes:
+      #
+      #   1. Master runs as PID 1 inside containerd / Docker (default
+      #      shape: `CMD ["hyperion", "config.ru"]`). A worker's
+      #      `Process.ppid` is 1 — and the previous fallback
+      #      `ppid > 1 ? ppid : Process.pid` then mistargeted the
+      #      *worker itself* on a graceful drain, so SIGTERM killed the
+      #      worker but left the master + the rest of the workers intact.
+      #      Operators saw the admin endpoint return 202 "draining" and
+      #      nothing happen at the fleet level.
+      #
+      #   2. Single-worker mode has no parent Hyperion process; ppid is
+      #      whatever launched us (shell, systemd, a supervisor). Killing
+      #      that is at best confusing, at worst destructive.
+      #
+      # Hyperion.master_pid handles both correctly without any ppid math.
+      Hyperion.master_pid
     end
   end
 end

data/lib/hyperion/cli.rb

@@ -20,10 +20,45 @@ module Hyperion
       config = config_path ? Hyperion::Config.load(config_path) : Hyperion::Config.new
       config.merge_cli!(cli_opts)
 
+      # 2.2.x fix-C: env-var override for the kTLS knob so operators can
+      # A/B kernel-TLS vs userspace SSL_write without rewriting their
+      # config file. Useful for the large-payload TLS bench harness
+      # (`bench/tls_static_1m.ru`, `bench/tls_json_50k.ru`).
+      apply_ktls_env_override!(config)
+
+      # 2.2.x fix-D: env-var override for the `h2.max_total_streams`
+      # admission cap. Mirrors `HYPERION_TLS_KTLS` from fix-C — operators
+      # running h2load or long-fan-out workloads can lift the 2.0.0
+      # default (`max_concurrent_streams × workers × 4`) without
+      # rewriting a config file. `HYPERION_H2_MAX_TOTAL_STREAMS=unbounded`
+      # restores pre-2.0 behaviour. Applied AFTER `merge_cli!` so it
+      # takes precedence over the CLI flag too — the env var is the
+      # outermost knob (CI/bench harness), the flag is the inner knob
+      # (per-invocation), and the config file is innermost.
+      apply_h2_max_total_streams_env_override!(config)
+
+      # 2.3-A: env-var override for the io_uring accept policy. Same
+      # grammar as `HYPERION_TLS_KTLS` (off/on/auto). Operators flip
+      # on for an A/B run without rewriting their config file.
+      # 2.3.0 default is :off because io_uring under fork+threads has
+      # known sharp edges (SQ inheritance, SQPOLL non-survival across
+      # fork). The env var is the sanctioned way to opt in.
+      apply_io_uring_env_override!(config)
+
+      # 2.3-B: env-var overrides for the per-conn fairness cap and the
+      # TLS handshake CPU throttle. Same precedence rule as the other
+      # 2.x env-var bridges — outermost knob (env > CLI > config file).
+      apply_max_in_flight_per_conn_env_override!(config)
+      apply_tls_handshake_rate_limit_env_override!(config)
+
       # Install logger early so every subsequent log call honours the operator's
       # chosen format/level (config file or CLI) before anything else logs.
-      if config.log_level || config.log_format
-        Hyperion.logger = Hyperion::Logger.new(level: config.log_level, format: config.log_format)
+      # 1.8.0: write directly to the default Runtime — `Hyperion.logger=` now
+      # emits a deprecation warn aimed at out-of-tree callers, and CLI bootstrap
+      # is the canonical in-tree caller, so we sidestep the warn here.
+      if config.logging.level || config.logging.format
+        Hyperion::Runtime.default.logger =
+          Hyperion::Logger.new(level: config.logging.level, format: config.logging.format)
       end
 
       # Advisory: operators frequently flip --async-io expecting "fast mode"
@@ -33,12 +68,16 @@ module Hyperion
       # once at boot pointing at the operator-guidance docs; the operator's
       # setting is still honoured.
       warn_orphan_async_io(config)
+      # 1.7.0 (RFC A9): hard validation of `async_io: true` (and a soft
+      # warn for `false` with a fiber lib loaded). The nil-default keeps
+      # the 1.6.1 advisory shape — see Hyperion.validate_async_io_loaded_libs!.
+      Hyperion.validate_async_io_loaded_libs!(config.async_io)
 
       # Propagate log_requests so every Connection picks it up via
       # `Hyperion.log_requests?` without needing to thread it through
       # Server/ThreadPool/Master plumbing. Default is ON; nil means "don't
       # touch — fall through to the env/default chain in Hyperion.log_requests?".
-      Hyperion.log_requests = config.log_requests unless config.log_requests.nil?
+      Hyperion.log_requests = config.logging.requests unless config.logging.requests.nil?
 
       # Enable YJIT before workers fork / connections start. Auto-on in
       # production/staging gives operators the perf bump for free; explicit
@@ -49,14 +88,25 @@ module Hyperion
       abort("[hyperion] no such rackup file: #{rackup}") unless File.exist?(rackup)
 
       if config.fiber_local_shim
-        Hyperion::FiberLocal.install!
-        Hyperion.logger.info { { message: 'FiberLocal shim installed' } }
+        # Gate on async_io: with no fibers in play the shim has no purpose
+        # and patching `thread_variable_*` would re-stage the 1.4.x bug
+        # (stranded Logger/Metrics counters across thread-pool jobs running
+        # in distinct fibers). FiberLocal.install! itself enforces this and
+        # warns when ignored — we mirror the gate here for the success log.
+        Hyperion::FiberLocal.install!(async_io: config.async_io == true)
+        Hyperion.logger.info { { message: 'FiberLocal shim installed' } } if Hyperion::FiberLocal.installed?
       end
 
       app = load_rack_app(rackup)
       app = wrap_admin_middleware(app, config)
       workers = config.workers.zero? ? Etc.nprocessors : config.workers
 
+      # 2.0 default flip (RFC A7): resolve the `h2.max_total_streams`
+      # auto-sentinel now that worker count is known. After finalize!
+      # the field always carries either a positive integer (cap) or nil
+      # (operator-requested unbounded).
+      config.finalize!(workers: workers)
+
       if workers <= 1
         run_single(config, app)
       else
@@ -158,6 +208,56 @@ WARNING: argv is visible via `ps`; prefer --admin-token-file PATH for production
              'Graceful shutdown deadline in seconds before SIGKILL (default 30)') do |n|
           cli_opts[:graceful_timeout] = n
         end
+        # 2.2.x fix-D: expose the existing `h2.max_total_streams` admission
+        # cap (1.7.0+ DSL knob) at the CLI surface. The 2.0.0 default flip
+        # to `max_concurrent_streams × workers × 4` (= 512 streams per
+        # process at -w 1) is sized for normal browser traffic but cuts
+        # off h2load benches and gRPC/long-fan-out workloads mid-test —
+        # this flag lets operators raise or disable the cap without
+        # writing a config file. `unbounded` (or `:unbounded`) writes
+        # `nil` to Config, which restores the pre-2.0 unbounded behaviour.
+        o.on('--h2-max-total-streams VALUE',
+             'HTTP/2 per-connection total stream cap. Use `unbounded` to disable. ' \
+             'Default: max_concurrent_streams × workers × 4 (2.0.0 flip).') do |v|
+          cli_opts[:h2_max_total_streams] = parse_h2_max_total_streams!(v)
+        end
+        # 2.3-B: per-connection fairness cap. Defends against a greedy
+        # upstream connection (nginx pipelining many client requests
+        # through one keep-alive conn) hogging the worker thread pool.
+        # Recommended setting: thread_count / 4 (e.g., `4` for `-t 16`).
+        # `auto` resolves at finalize! to thread_count/4 (floor 1).
+        # Default unset (no cap) — opt-in operator hardening.
+        o.on('--max-in-flight-per-conn VALUE',
+             'Per-connection in-flight request cap. Integer >= 1, or `auto` ' \
+             '(thread_count/4, floor 1). Default: unset (no cap).') do |v|
+          cli_opts[:max_in_flight_per_conn] = parse_max_in_flight_per_conn!(v)
+        end
+        # 2.3-B: TLS handshake CPU throttle. Token-bucket budget for
+        # SSL_accept calls per second per worker. Defends direct-exposure
+        # operators against handshake storms; for nginx-fronted topologies
+        # this is mostly defensive (nginx keeps long-lived upstream conns).
+        # `unlimited` (default) preserves 2.2.0 behaviour.
+        o.on('--tls-handshake-rate-limit VALUE',
+             'TLS handshake CPU throttle: handshakes/sec/worker. Integer >= 1 ' \
+             'or `unlimited` (default).') do |v|
+          cli_opts[:tls_handshake_rate_limit] = parse_tls_handshake_rate_limit!(v)
+        end
+        # 2.10-E: repeatable preload-at-boot flag. Each occurrence appends
+        # to the cli_opts Array; merge_cli! turns each into a
+        # `{path:, immutable: true}` entry on `Config#preload_static_dirs`.
+        # `--no-preload-static` is the sibling sentinel that disables the
+        # Rails-aware auto-detect path; the operator's explicit dirs (if
+        # any) still take effect.
+        o.on('--preload-static DIR',
+             'Preload static assets from DIR at boot (repeatable). Marks every ' \
+             'cached entry immutable so subsequent serves never re-stat.') do |dir|
+          (cli_opts[:preload_static] ||= []) << dir
+        end
+        o.on('--no-preload-static',
+             'Disable the Rails-aware static-asset auto-detect at boot. ' \
+             'Explicit `--preload-static` dirs still take effect.') do
+          cli_opts[:auto_preload_static_disabled] = true
+        end
         o.on('-h', '--help', 'show help') do
           puts o
           exit 0
@@ -169,6 +269,15 @@ WARNING: argv is visible via `ps`; prefer --admin-token-file PATH for production
     end
 
     def self.run_single(config, app)
+      # Single-mode: there's no fork, but AdminMiddleware still resolves the
+      # signal target via Hyperion.master_pid. Set it to ourselves so
+      # POST /-/quit signals the lone process — same contract as cluster
+      # mode (SIGTERM the master). See Hyperion.master_pid for why we don't
+      # rely on Process.pid alone (the AdminMiddleware reader's fallback
+      # would do that anyway, but making it explicit + writing
+      # HYPERION_MASTER_PID into ENV keeps single/cluster behaviour
+      # symmetric for any external tooling that introspects the var).
+      Hyperion.master_pid!(Process.pid)
       tls = build_tls_from_config(config)
       server = Server.new(host: config.host, port: config.port, app: app,
                           tls: tls, thread_count: config.thread_count,
@@ -176,10 +285,18 @@ WARNING: argv is visible via `ps`; prefer --admin-token-file PATH for production
                           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)
-      server.listen
-      scheme = tls ? 'https' : 'http'
-      Hyperion.logger.info { { message: 'listening', url: "#{scheme}://#{server.host}:#{server.port}" } }
+                          async_io: config.async_io,
+                          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,
+                          tls_session_cache_size: config.tls.session_cache_size,
+                          tls_ktls: config.tls.ktls,
+                          io_uring: config.io_uring,
+                          max_in_flight_per_conn: config.max_in_flight_per_conn,
+                          tls_handshake_rate_limit: config.tls.handshake_rate_limit,
+                          preload_static_dirs: config.resolved_preload_static_dirs)
       warn_c_parser_unavailable
 
       # Pre-allocate Rack env-pool entries and eager-touch lazy constants.
@@ -192,8 +309,17 @@ WARNING: argv is visible via `ps`; prefer --admin-token-file PATH for production
       # here (no fork happens), and on_worker_boot/on_worker_shutdown fire
       # for the lone in-process "worker" so app code that opens DB pools etc.
       # gets the same lifecycle whether you run 1 or N workers.
+      #
+      # `on_worker_boot` fires BEFORE the listener is bound — same contract
+      # as the cluster path (Worker#run): the operator's boot hook runs
+      # against a process with no inbound socket yet, so DB/Redis warmup
+      # finishes before the kernel can queue any connections.
       config.on_worker_boot.each { |h| h.call(0) }
 
+      server.listen
+      scheme = tls ? 'https' : 'http'
+      Hyperion.logger.info { { message: 'listening', url: "#{scheme}://#{server.host}:#{server.port}" } }
+
       shutdown_r, shutdown_w = IO.pipe
       %w[INT TERM].each do |sig|
         Signal.trap(sig) do
@@ -269,6 +395,179 @@ WARNING: argv is visible via `ps`; prefer --admin-token-file PATH for production
     end
     private_class_method :maybe_enable_yjit
 
+    # 2.2.x fix-C: env-var bridge for `tls.ktls`. Operators running the
+    # large-payload TLS bench harness (`bench/tls_static_1m.ru` /
+    # `bench/tls_json_50k.ru`) need to A/B kernel-TLS vs userspace
+    # SSL_write without editing their config file — the bench script
+    # flips `HYPERION_TLS_KTLS=off` for the userspace baseline and
+    # leaves it unset (`:auto`) for the kTLS run. Unknown values are
+    # ignored (with a warn) rather than aborting boot — the env var is
+    # a convenience knob, not a security boundary, and a typo
+    # shouldn't crash the process.
+    def self.apply_ktls_env_override!(config)
+      raw = ENV['HYPERION_TLS_KTLS']
+      return if raw.nil? || raw.empty?
+
+      case raw
+      when 'off'  then config.tls.ktls = :off
+      when 'on'   then config.tls.ktls = :on
+      when 'auto' then config.tls.ktls = :auto
+      else
+        Hyperion.logger.warn do
+          { message: 'HYPERION_TLS_KTLS ignored (must be off|on|auto)', value: raw }
+        end
+      end
+    end
+    private_class_method :apply_ktls_env_override!
+
+    # 2.2.x fix-D: shared parser for `--h2-max-total-streams VALUE` and
+    # `HYPERION_H2_MAX_TOTAL_STREAMS=VALUE`. Returns either a positive
+    # Integer (explicit cap) or the `H2Settings::UNBOUNDED` sentinel,
+    # which `Config#finalize!` later resolves to `nil` (no cap).
+    # Anything else raises `OptionParser::InvalidArgument` — same shape
+    # as the built-in `OptionParser` integer-parse failures, so the CLI
+    # branch's caller treats it identically.
+    def self.parse_h2_max_total_streams!(raw)
+      case raw
+      when 'unbounded', ':unbounded'
+        Hyperion::Config::H2Settings::UNBOUNDED
+      when /\A\d+\z/
+        n = raw.to_i
+        unless n.positive?
+          raise OptionParser::InvalidArgument,
+                "--h2-max-total-streams: expected a positive integer or 'unbounded', got #{raw.inspect}"
+        end
+        n
+      else
+        raise OptionParser::InvalidArgument,
+              "--h2-max-total-streams: expected a positive integer or 'unbounded', got #{raw.inspect}"
+      end
+    end
+    private_class_method :parse_h2_max_total_streams!
+
+    # 2.2.x fix-D: env-var bridge for the h2 admission cap. Same value
+    # grammar as the CLI flag (`unbounded` or a positive integer).
+    # Unknown values warn and leave the config untouched — the env var
+    # is a convenience knob for benches and operator overrides, not a
+    # security boundary, and a typo shouldn't crash boot.
+    def self.apply_h2_max_total_streams_env_override!(config)
+      raw = ENV['HYPERION_H2_MAX_TOTAL_STREAMS']
+      return if raw.nil? || raw.empty?
+
+      begin
+        config.h2.max_total_streams = parse_h2_max_total_streams!(raw)
+      rescue OptionParser::InvalidArgument
+        Hyperion.logger.warn do
+          { message: 'HYPERION_H2_MAX_TOTAL_STREAMS ignored (must be a positive integer or `unbounded`)',
+            value: raw }
+        end
+      end
+    end
+    private_class_method :apply_h2_max_total_streams_env_override!
+
+    # 2.3-A: env-var bridge for the io_uring accept policy. Mirrors
+    # `apply_ktls_env_override!`. Unknown values warn and leave the
+    # config untouched — env vars are convenience knobs for benches /
+    # operator overrides, not security boundaries, so a typo
+    # shouldn't crash boot.
+    def self.apply_io_uring_env_override!(config)
+      raw = ENV['HYPERION_IO_URING']
+      return if raw.nil? || raw.empty?
+
+      case raw
+      when 'off'  then config.io_uring = :off
+      when 'on'   then config.io_uring = :on
+      when 'auto' then config.io_uring = :auto
+      else
+        Hyperion.logger.warn do
+          { message: 'HYPERION_IO_URING ignored (must be off|on|auto)', value: raw }
+        end
+      end
+    end
+    private_class_method :apply_io_uring_env_override!
+
+    # 2.3-B: shared parser for `--max-in-flight-per-conn VALUE` and
+    # `HYPERION_MAX_IN_FLIGHT_PER_CONN=VALUE`. Returns either a positive
+    # Integer (explicit cap) or the `:auto` sentinel which `Config#finalize!`
+    # later resolves to `thread_count / 4`. Anything else raises
+    # `OptionParser::InvalidArgument` so CLI typos surface at boot.
+    def self.parse_max_in_flight_per_conn!(raw)
+      case raw
+      when 'auto', ':auto'
+        Hyperion::Config::MAX_IN_FLIGHT_PER_CONN_AUTO
+      when /\A\d+\z/
+        n = raw.to_i
+        unless n.positive?
+          raise OptionParser::InvalidArgument,
+                "--max-in-flight-per-conn: expected a positive integer or 'auto', got #{raw.inspect}"
+        end
+        n
+      else
+        raise OptionParser::InvalidArgument,
+              "--max-in-flight-per-conn: expected a positive integer or 'auto', got #{raw.inspect}"
+      end
+    end
+    private_class_method :parse_max_in_flight_per_conn!
+
+    # 2.3-B: env-var bridge for the per-conn fairness cap. Same value
+    # grammar as the CLI flag (`auto` or a positive integer). Unknown
+    # values warn and leave the config untouched — the env var is a
+    # convenience knob, not a security boundary.
+    def self.apply_max_in_flight_per_conn_env_override!(config)
+      raw = ENV['HYPERION_MAX_IN_FLIGHT_PER_CONN']
+      return if raw.nil? || raw.empty?
+
+      begin
+        config.max_in_flight_per_conn = parse_max_in_flight_per_conn!(raw)
+      rescue OptionParser::InvalidArgument
+        Hyperion.logger.warn do
+          { message: 'HYPERION_MAX_IN_FLIGHT_PER_CONN ignored (must be a positive integer or `auto`)',
+            value: raw }
+        end
+      end
+    end
+    private_class_method :apply_max_in_flight_per_conn_env_override!
+
+    # 2.3-B: shared parser for `--tls-handshake-rate-limit VALUE` and
+    # `HYPERION_TLS_HANDSHAKE_RATE_LIMIT=VALUE`. Returns either a
+    # positive Integer (handshakes/sec/worker) or the `:unlimited`
+    # sentinel which keeps the 2.2.0 (no-throttle) behaviour. Anything
+    # else raises `OptionParser::InvalidArgument`.
+    def self.parse_tls_handshake_rate_limit!(raw)
+      case raw
+      when 'unlimited', ':unlimited'
+        :unlimited
+      when /\A\d+\z/
+        n = raw.to_i
+        unless n.positive?
+          raise OptionParser::InvalidArgument,
+                "--tls-handshake-rate-limit: expected a positive integer or 'unlimited', got #{raw.inspect}"
+        end
+        n
+      else
+        raise OptionParser::InvalidArgument,
+              "--tls-handshake-rate-limit: expected a positive integer or 'unlimited', got #{raw.inspect}"
+      end
+    end
+    private_class_method :parse_tls_handshake_rate_limit!
+
+    # 2.3-B: env-var bridge for the TLS handshake throttle. Same value
+    # grammar as the CLI flag.
+    def self.apply_tls_handshake_rate_limit_env_override!(config)
+      raw = ENV['HYPERION_TLS_HANDSHAKE_RATE_LIMIT']
+      return if raw.nil? || raw.empty?
+
+      begin
+        config.tls.handshake_rate_limit = parse_tls_handshake_rate_limit!(raw)
+      rescue OptionParser::InvalidArgument
+        Hyperion.logger.warn do
+          { message: 'HYPERION_TLS_HANDSHAKE_RATE_LIMIT ignored (must be a positive integer or `unlimited`)',
+            value: raw }
+        end
+      end
+    end
+    private_class_method :apply_tls_handshake_rate_limit_env_override!
+
     # Probe table for fiber-cooperative I/O libraries. If `async_io: true` is
     # set but none of these are loaded, the operator has likely flipped the
     # flag without reading the bench numbers — `--async-io` adds Async-loop
@@ -303,13 +602,13 @@ WARNING: argv is visible via `ps`; prefer --admin-token-file PATH for production
     # Skipped when the token is unset — those paths fall through to the app,
     # so apps may still own /-/anything if Hyperion's admin is off.
     def self.wrap_admin_middleware(app, config)
-      return app if config.admin_token.nil? || config.admin_token.to_s.empty?
+      return app if config.admin.token.nil? || config.admin.token.to_s.empty?
 
       Hyperion.logger.info do
         { message: 'admin endpoint enabled',
           paths: [AdminMiddleware::PATH_QUIT, AdminMiddleware::PATH_METRICS] }
       end
-      AdminMiddleware.new(app, token: config.admin_token)
+      AdminMiddleware.new(app, token: config.admin.token)
     end
     private_class_method :wrap_admin_middleware