hyperion-rb 1.0.0.rc17

data/lib/hyperion/cli.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require 'etc'
+require 'openssl'
+require 'optparse'
+require 'rack'
+require_relative '../hyperion'
+
+module Hyperion
+  class CLI
+    DEFAULT_CONFIG_PATH = 'config/hyperion.rb'
+
+    def self.run(argv)
+      cli_opts    = {}
+      config_path = nil
+
+      parser = OptionParser.new do |o|
+        o.banner = 'Usage: hyperion [options] config.ru'
+        o.on('-C', '--config PATH', "Hyperion config file (default ./#{DEFAULT_CONFIG_PATH} if it exists)") do |p|
+          config_path = p
+        end
+        o.on('-b', '--bind HOST', 'host (default 127.0.0.1)') { |h| cli_opts[:host] = h }
+        o.on('-p', '--port PORT', Integer, 'port (default 9292)') { |p| cli_opts[:port] = p }
+        o.on('-w', '--workers N', Integer, 'worker processes (0 = nprocessors)') { |w| cli_opts[:workers] = w }
+        o.on('-t', '--threads N', Integer, 'Rack handler thread pool size (0 disables)') do |t|
+          cli_opts[:thread_count] = t
+        end
+        o.on('--tls-cert PATH', 'TLS certificate (PEM)') do |p|
+          cli_opts[:tls_cert] = OpenSSL::X509::Certificate.new(File.read(p))
+        end
+        o.on('--tls-key PATH', 'TLS private key (PEM)') do |p|
+          cli_opts[:tls_key] = OpenSSL::PKey.read(File.read(p))
+        end
+        o.on('--log-level LEVEL', %w[debug info warn error fatal], 'log level (default info)') do |l|
+          cli_opts[:log_level] = l.to_sym
+        end
+        o.on('--log-format FORMAT', %w[text json auto],
+             'log format: text | json | auto (default auto: json on RAILS_ENV/RACK_ENV=production, colored text on TTY, json otherwise)') do |f|
+          cli_opts[:log_format] = f.to_sym
+        end
+        o.on('--[no-]log-requests',
+             'Per-request access log line (default ON; pass --no-log-requests to disable).') do |v|
+          cli_opts[:log_requests] = v
+        end
+        o.on('--fiber-local-shim', 'Patch Thread.current[] to be fiber-local (Rails-compat for older gems)') do
+          cli_opts[:fiber_local_shim] = true
+        end
+        o.on('-h', '--help', 'show help') do
+          puts o
+          exit 0
+        end
+      end
+      parser.parse!(argv)
+
+      # Precedence: CLI > config file > built-in default. We auto-load
+      # config/hyperion.rb if present so operators can drop a file in their
+      # repo and have it take effect without having to remember -C.
+      config_path ||= DEFAULT_CONFIG_PATH if File.exist?(DEFAULT_CONFIG_PATH)
+      config = config_path ? Hyperion::Config.load(config_path) : Hyperion::Config.new
+      config.merge_cli!(cli_opts)
+
+      # 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)
+      end
+
+      # 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?
+
+      rackup = argv.first || 'config.ru'
+      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' } }
+      end
+
+      app = load_rack_app(rackup)
+      workers = config.workers.zero? ? Etc.nprocessors : config.workers
+
+      if workers <= 1
+        run_single(config, app)
+      else
+        run_cluster(config, app, workers)
+      end
+    end
+
+    def self.run_single(config, app)
+      tls = build_tls_from_config(config)
+      server = Server.new(host: config.host, port: config.port, app: app,
+                          tls: tls, thread_count: config.thread_count,
+                          read_timeout: config.read_timeout)
+      server.listen
+      scheme = tls ? 'https' : 'http'
+      Hyperion.logger.info { { message: 'listening', url: "#{scheme}://#{server.host}:#{server.port}" } }
+
+      # Single-worker mode reuses the lifecycle hooks: before_fork is a no-op
+      # 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.
+      config.on_worker_boot.each { |h| h.call(0) }
+
+      shutdown_r, shutdown_w = IO.pipe
+      %w[INT TERM].each do |sig|
+        Signal.trap(sig) do
+          shutdown_w.write_nonblock('!')
+        rescue StandardError
+          nil
+        end
+      end
+
+      shutdown_thread = Thread.new do
+        shutdown_r.read(1)
+        server.stop
+      end
+      shutdown_thread.report_on_exception = false
+
+      server.start
+      shutdown_thread.join
+      config.on_worker_shutdown.each { |h| h.call(0) }
+    end
+
+    def self.run_cluster(config, app, workers)
+      tls = build_tls_from_config(config)
+      Master.new(host: config.host, port: config.port, app: app,
+                 workers: workers, tls: tls, thread_count: config.thread_count,
+                 read_timeout: config.read_timeout, config: config).run
+    end
+
+    # Rack 3's parse_file returns a single app value; Rack 2 returned [app, options].
+    # Normalize so we get just the app either way.
+    def self.load_rack_app(path)
+      result = ::Rack::Builder.parse_file(path)
+      result.is_a?(Array) ? result.first : result
+    end
+    private_class_method :load_rack_app
+
+    def self.build_tls_from_config(config)
+      return nil unless config.tls_cert || config.tls_key
+
+      abort('[hyperion] tls_cert and tls_key must be supplied together') unless config.tls_cert && config.tls_key
+
+      { cert: config.tls_cert, key: config.tls_key }
+    end
+    private_class_method :build_tls_from_config
+  end
+end

data/lib/hyperion/config.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Hyperion
+  # Mutable configuration container — populated by the DSL evaluator
+  # (Hyperion::Config.load) and then read by CLI / Server / Master / Worker /
+  # Connection / Logger.
+  #
+  # All settings have safe defaults that match the per-class DEFAULT_* constants
+  # so that running Hyperion without a config file works identically to the
+  # pre-rc14 behaviour.
+  class Config
+    DEFAULTS = {
+      host: '127.0.0.1',
+      port: 9292,
+      workers: 1,
+      thread_count: 5,
+      tls_cert: nil,
+      tls_key: nil,
+      read_timeout: 30,
+      idle_keepalive: 5,
+      graceful_timeout: 30,
+      max_header_bytes: 64 * 1024,
+      max_body_bytes: 16 * 1024 * 1024,
+      log_level: nil, # nil → Logger picks from env / default
+      log_format: nil, # nil → Logger picks via auto rule
+      log_requests: nil, # nil → Hyperion.log_requests? (default true)
+      fiber_local_shim: false
+    }.freeze
+
+    HOOKS = %i[before_fork on_worker_boot on_worker_shutdown].freeze
+
+    attr_accessor(*DEFAULTS.keys)
+    attr_reader(*HOOKS)
+
+    def initialize
+      DEFAULTS.each { |k, v| public_send(:"#{k}=", v) }
+      HOOKS.each { |h| instance_variable_set(:"@#{h}", []) }
+    end
+
+    HOOKS.each do |hook|
+      define_method(:"add_#{hook}") do |&block|
+        instance_variable_get(:"@#{hook}") << block if block
+      end
+    end
+
+    # Load a Ruby DSL config file. Returns the populated Config.
+    # Path is the operator-supplied --config argument; we evaluate it in a
+    # DSL context that maps method calls to attribute setters.
+    def self.load(path)
+      cfg = new
+      contents = File.read(path)
+      DSL.new(cfg).instance_eval(contents, path)
+      cfg
+    end
+
+    # Apply CLI overrides on top of an existing config. Only non-nil values
+    # in `overrides` are applied — preserves the precedence ordering
+    # (CLI > env > config file > default).
+    def merge_cli!(overrides)
+      overrides.each do |key, value|
+        next if value.nil?
+
+        public_send(:"#{key}=", value) if respond_to?(:"#{key}=")
+      end
+      self
+    end
+
+    # DSL receiver. Each method call on the DSL maps to a Config setter or
+    # to a hook registration. Unknown methods raise NoMethodError so typos
+    # surface immediately at boot rather than as silent ignores.
+    class DSL
+      def initialize(config)
+        @config = config
+      end
+
+      # `bind` is the Puma-style alias for `host` — operators expect it.
+      def bind(value)
+        @config.host = value
+      end
+
+      Config::DEFAULTS.each_key do |key|
+        define_method(key) do |value|
+          @config.public_send(:"#{key}=", value)
+        end
+      end
+
+      Config::HOOKS.each do |hook|
+        define_method(hook) do |&block|
+          @config.public_send(:"add_#{hook}", &block)
+        end
+      end
+
+      # `tls_cert_path` / `tls_key_path` are convenience aliases that read
+      # the file off disk so the DSL stays terse. The parsed cert/key are
+      # stored on the config and Server consumes them directly.
+      def tls_cert_path(path)
+        require 'openssl'
+        @config.tls_cert = OpenSSL::X509::Certificate.new(File.read(path))
+      end
+
+      def tls_key_path(path)
+        require 'openssl'
+        @config.tls_key = OpenSSL::PKey.read(File.read(path))
+      end
+    end
+  end
+end

data/lib/hyperion/connection.rb

@@ -0,0 +1,338 @@
+# frozen_string_literal: true
+
+module Hyperion
+  # Drives one TCP connection through its lifecycle:
+  # read until headers complete + body, parse, dispatch via Rack adapter, write, close.
+  # Phase 2 adds fiber scheduling and keep-alive; the public surface (#serve)
+  # is stable.
+  #
+  # Phase 1 assumes blocking I/O: socket.read(N) blocks until N bytes or EOF, so
+  # `break if chunk.nil? || chunk.empty?` correctly detects EOF in read_request.
+  # Phase 2 (fiber scheduler) introduces non-blocking semantics where short reads
+  # and EAGAIN must be distinguished from EOF — read_request will need to handle
+  # IO::WaitReadable explicitly at that point.
+  class Connection
+    READ_CHUNK                      = 16 * 1024
+    MAX_HEADER_BYTES                = 64 * 1024
+    MAX_BODY_BYTES                  = 16 * 1024 * 1024 # 16 MB cap. Phase 5 introduces streaming bodies.
+    HEADER_TERM                     = "\r\n\r\n"
+    TIMEOUT_SENTINEL                = :__hyperion_read_timeout__
+    IDLE_KEEPALIVE_TIMEOUT_SECONDS  = 5
+
+    # Default parser is the C-extension `CParser` when the extension built;
+    # otherwise we fall back to the pure-Ruby `Parser`. Evaluated each call
+    # because Ruby evaluates default kwargs at call time.
+    def self.default_parser
+      defined?(::Hyperion::CParser) ? ::Hyperion::CParser.new : ::Hyperion::Parser.new
+    end
+
+    def initialize(parser: self.class.default_parser, writer: ResponseWriter.new, thread_pool: nil,
+                   log_requests: nil)
+      @parser      = parser
+      @writer      = writer
+      @thread_pool = thread_pool
+      # Cache module-level singletons once per Connection instance so the hot
+      # path doesn't re-dispatch through Hyperion.metrics / Hyperion.logger
+      # (each was a method call + ivar nil-check on every request).
+      @metrics     = Hyperion.metrics
+      @logger      = Hyperion.logger
+      # Per-request access logging is ON by default (matches Puma+Rails
+      # operator expectation). The hot path is optimised end-to-end: one
+      # Process.clock_gettime per request, per-thread cached timestamp,
+      # hand-rolled line builder, lock-free emit. Operator disables via
+      # `--no-log-requests` or `HYPERION_LOG_REQUESTS=0`.
+      @log_requests = log_requests.nil? ? Hyperion.log_requests? : log_requests
+    end
+
+    def serve(socket, app)
+      request_count = 0
+      carry = +'' # bytes already pulled off the socket but past the prev request boundary
+      peer_addr = peer_address(socket)
+      @metrics.increment(:connections_accepted)
+      @metrics.increment(:connections_active)
+      loop do
+        buffer = read_request(socket, carry)
+        return unless buffer
+
+        if buffer == TIMEOUT_SENTINEL
+          # Idle timeout between keep-alive requests: close silently — the peer
+          # never started a new request, so there's nothing to 408 about.
+          @metrics.increment(:read_timeouts)
+          return if request_count.positive?
+
+          safe_write_error(socket, 408, 'Request Timeout')
+          @metrics.increment_status(408)
+          return
+        end
+
+        request, body_end = @parser.parse(buffer)
+        carry = +(buffer.byteslice(body_end, buffer.bytesize - body_end) || '')
+        request = enrich_with_peer(request, peer_addr) if peer_addr && request.peer_address.nil?
+
+        @metrics.increment(:requests_total)
+        @metrics.increment(:requests_in_flight)
+        request_started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) if @log_requests
+        begin
+          status, headers, body = call_app(app, request)
+        ensure
+          @metrics.decrement(:requests_in_flight)
+        end
+
+        keep_alive = should_keep_alive?(request, status, headers)
+        @writer.write(socket, status, headers, body, keep_alive: keep_alive)
+        @metrics.increment_status(status)
+        log_request(request, status, request_started_at) if @log_requests
+        request_count += 1
+
+        return unless keep_alive
+
+        # Idle wait between requests: don't hold a fiber forever on a quiet conn.
+        set_idle_timeout(socket)
+      end
+    rescue ParseError => e
+      @metrics.increment(:parse_errors)
+      @logger.warn { { message: 'parse error', error: e.message, error_class: e.class.name } }
+      safe_write_error(socket, 400, 'Bad Request')
+      @metrics.increment_status(400)
+    rescue UnsupportedError => e
+      @logger.warn { { message: 'unsupported request', error: e.message, error_class: e.class.name } }
+      safe_write_error(socket, 501, 'Not Implemented')
+      @metrics.increment_status(501)
+    rescue StandardError => e
+      @metrics.increment(:app_errors)
+      @logger.error do
+        { message: 'unhandled in connection', error: e.message, error_class: e.class.name }
+      end
+    ensure
+      @metrics.decrement(:connections_active)
+      # Flush any buffered access-log lines for this thread before letting
+      # the connection go idle. Otherwise a low-traffic worker would hold
+      # logs in its per-thread buffer indefinitely.
+      @logger.flush_access_buffer if @log_requests && @logger.respond_to?(:flush_access_buffer)
+      begin
+        socket.close unless socket.closed?
+      rescue StandardError
+        # Already failing; swallow close errors so we don't mask the real cause.
+      end
+    end
+
+    private
+
+    # Route Rack dispatch through the thread pool when one was injected,
+    # otherwise run inline on the current fiber. Inline keeps the test path
+    # simple (no extra threads spun up for unit specs) and provides a
+    # debugging escape hatch via `Server#thread_count: 0`.
+    def call_app(app, request)
+      if @thread_pool
+        @thread_pool.call(app, request)
+      else
+        Adapter::Rack.call(app, request)
+      end
+    end
+
+    # Extract the peer IP from the underlying socket, if available.
+    # Works for TCPSocket and OpenSSL::SSL::SSLSocket (via #io). UNIX sockets
+    # return AF_UNIX with an empty path — we return nil there so the adapter
+    # falls back to its localhost default.
+    def peer_address(socket)
+      raw = socket.respond_to?(:io) ? socket.io : socket
+      return nil unless raw.respond_to?(:peeraddr)
+
+      addr = raw.peeraddr
+      ip = addr[3] || addr[2]
+      return nil if ip.nil? || ip.to_s.empty?
+
+      ip
+    rescue StandardError
+      nil
+    end
+
+    # Request is frozen — to enrich it we build a new value object with the
+    # peer address copied in. Cheap on the fast path because we only do this
+    # once per connection (peer_addr is captured before the request loop).
+    def enrich_with_peer(request, peer_addr)
+      Hyperion::Request.new(
+        method: request.method,
+        path: request.path,
+        query_string: request.query_string,
+        http_version: request.http_version,
+        headers: request.headers,
+        body: request.body,
+        peer_address: peer_addr
+      )
+    end
+
+    def should_keep_alive?(request, _status, headers)
+      # App-emitted Connection: close wins.
+      conn_response = headers.find { |k, _| k.to_s.downcase == 'connection' }
+      return false if conn_response && conn_response.last.to_s.downcase == 'close'
+
+      # Request-side Connection header.
+      conn_request = request.header('connection')&.downcase
+
+      case request.http_version
+      when 'HTTP/1.1'
+        conn_request != 'close'
+      when 'HTTP/1.0'
+        conn_request == 'keep-alive'
+      else
+        false
+      end
+    end
+
+    def set_idle_timeout(socket)
+      socket.timeout = IDLE_KEEPALIVE_TIMEOUT_SECONDS if socket.respond_to?(:timeout=)
+    rescue StandardError
+      # Best-effort; if the socket type doesn't support it, read_chunk's
+      # IO.select fallback still gives us a deadline via read_timeout_for.
+    end
+
+    # Reads one complete request off the socket. `carry` is bytes already
+    # buffered from the previous request's trailing read (keep-alive
+    # pipelining). Returns the full buffer (with any trailing pipelined
+    # bytes intact); the parser's returned end_offset tells the caller
+    # where this request ends. On EOF returns nil; on read timeout returns
+    # TIMEOUT_SENTINEL.
+    def read_request(socket, carry = +'')
+      buffer = carry
+      until buffer.include?(HEADER_TERM)
+        chunk = read_chunk(socket)
+        return chunk if chunk.nil? || chunk == TIMEOUT_SENTINEL
+        return nil if chunk.empty?
+
+        buffer << chunk
+        raise ParseError, 'header section too large' if buffer.bytesize > MAX_HEADER_BYTES
+      end
+
+      header_end = buffer.index(HEADER_TERM) + HEADER_TERM.bytesize
+      headers_part = buffer.byteslice(0, header_end)
+
+      if chunked?(headers_part)
+        until chunked_body_complete?(buffer, header_end)
+          raise ParseError, 'chunked body exceeds limit' if buffer.bytesize - header_end > MAX_BODY_BYTES
+
+          chunk = read_chunk(socket)
+          break if chunk.nil? || chunk.empty? || chunk == TIMEOUT_SENTINEL
+
+          buffer << chunk
+        end
+      else
+        content_length = headers_part[/^content-length:\s*(\d+)/i, 1].to_i
+        while buffer.bytesize < header_end + content_length
+          chunk = read_chunk(socket)
+          break if chunk.nil? || chunk.empty? || chunk == TIMEOUT_SENTINEL
+
+          buffer << chunk
+        end
+      end
+
+      buffer
+    end
+
+    def chunked?(headers_part)
+      headers_part.match?(/^transfer-encoding:[ \t]*[^\r\n]*chunked\b/i)
+    end
+
+    # Walks chunked framing in `buffer` starting at `body_start` and
+    # returns true once the final 0-sized chunk (and trailer terminator)
+    # is fully buffered. Mirrors the parser's dechunk walk; Phase 4's C
+    # parser folds these together via incremental parsing.
+    def chunked_body_complete?(buffer, body_start)
+      cursor = body_start
+      loop do
+        line_end = buffer.index("\r\n", cursor)
+        return false unless line_end
+
+        size_line = buffer.byteslice(cursor, line_end - cursor)
+        size_token = size_line.split(';').first.to_s.strip
+        return false if size_token.empty?
+
+        size = size_token.to_i(16)
+        cursor = line_end + 2
+
+        if size.zero?
+          loop do
+            nl = buffer.index("\r\n", cursor)
+            return false unless nl
+            return true if nl == cursor
+
+            cursor = nl + 2
+          end
+        end
+
+        return false if buffer.bytesize < cursor + size + 2
+
+        cursor += size + 2
+      end
+    end
+
+    # Read up to READ_CHUNK bytes, returning whatever's available. Unlike
+    # IO#read(N) — which blocks until N bytes or EOF — read_nonblock returns
+    # as soon as any data arrives, which is what we need for live HTTP
+    # clients that send a small request and then wait for a response on
+    # the same socket without closing the write half.
+    #
+    # Phase 8 perf fix: try read_nonblock FIRST, only fall through to IO.select
+    # if no data is buffered. wrk and other benchmarkers pre-buffer the entire
+    # request so the first readpartial succeeds and we skip the select syscall
+    # entirely. The IO.select fallback still gives us a deterministic deadline
+    # against stalled peers (SO_RCVTIMEO and IO#timeout= don't reliably trip
+    # readpartial on Ruby 3.3).
+    def read_chunk(socket)
+      result = socket.read_nonblock(READ_CHUNK, exception: false)
+      return result if result.is_a?(String) # hot path: data was buffered, return immediately
+      return nil if result.nil?             # EOF
+
+      # :wait_readable — fall back to IO.select with a deadline.
+      timeout = read_timeout_for(socket)
+      ready, = IO.select([socket], nil, nil, timeout)
+      return TIMEOUT_SENTINEL if ready.nil?
+
+      retry_read_nonblock(socket)
+    rescue EOFError
+      nil
+    rescue Errno::EAGAIN, Errno::EWOULDBLOCK, IO::TimeoutError
+      TIMEOUT_SENTINEL
+    end
+
+    def retry_read_nonblock(socket)
+      socket.read_nonblock(READ_CHUNK)
+    rescue IO::WaitReadable
+      TIMEOUT_SENTINEL
+    rescue EOFError
+      nil
+    end
+
+    def read_timeout_for(socket)
+      socket.respond_to?(:timeout) && socket.timeout || 30
+    rescue StandardError
+      30
+    end
+
+    def safe_write_error(socket, status, body_text)
+      @writer.write(socket, status, { 'content-type' => 'text/plain' }, [body_text])
+    rescue StandardError => e
+      @logger.error do
+        { message: 'failed to write error response', error: e.message, error_class: e.class.name }
+      end
+    end
+
+    # Emit one structured access-log line per response. Default ON; operator
+    # disables via `--no-log-requests`. Routes through Logger#access which
+    # uses a hand-rolled single-interpolation builder + per-thread cached
+    # timestamp + lock-free emit (no mutex, no flush) — at 16 threads the
+    # default-ON path runs within a few percent of the disabled path.
+    def log_request(request, status, started_at)
+      duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round(2)
+      @logger.access(
+        request.method,
+        request.path,
+        request.query_string,
+        status,
+        duration_ms,
+        request.peer_address,
+        request.http_version
+      )
+    end
+  end
+end

data/lib/hyperion/fiber_local.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Hyperion
+  # FiberLocal — tooling for fiber-local request scope under the Async scheduler.
+  #
+  # ## Background
+  #
+  # Under fiber-per-request concurrency (Hyperion Phase 2+, Falcon), all
+  # in-flight requests share the same OS thread. Code that stores per-request
+  # state on `Thread.current` would leak between requests.
+  #
+  # **Ruby 3.2+ already solves the most common case:** `Thread.current[:k] = v`
+  # writes to FIBER-local storage, not thread-local storage. Each fiber's
+  # `Thread.current[:k]` is independent. This is what Hyperion relies on.
+  #
+  # The remaining footgun is `Thread.current.thread_variable_set`, which IS
+  # genuinely thread-shared and will leak across fiber-scheduled requests.
+  # Old Rails code (< 7.0) sometimes used this. Modern Rails uses
+  # `ActiveSupport::IsolatedExecutionState` (which routes to Fiber storage),
+  # so well-maintained apps are not affected.
+  #
+  # ## What this module provides
+  #
+  # `Hyperion::FiberLocal.verify_environment!` — sanity check that the
+  # current Ruby actually isolates `Thread.current[:k]` per-fiber. Raises if
+  # not (which would only happen on Ruby < 3.2).
+  #
+  # `Hyperion::FiberLocal.install!` — opt-in monkey-patch that ALSO routes
+  # `thread_variable_get`/`thread_variable_set` to fiber storage. Use only
+  # if you know your app stores request scope via thread variables and you
+  # accept the trade-offs (genuine thread-pool patterns will break).
+  module FiberLocal
+    @installed = false
+
+    class << self
+      def installed?
+        @installed
+      end
+
+      # Confirm that the current Ruby treats Thread.current[:k] as fiber-local.
+      # Raises NotImplementedError on older Ruby where the leak still exists.
+      def verify_environment!
+        marker = :__hyperion_fiber_isolation_check__
+        ::Thread.current[marker] = :outer
+
+        observed = nil
+        ::Fiber.new { observed = ::Thread.current[marker] }.resume
+
+        unless observed.nil?
+          raise NotImplementedError,
+                'Thread.current[:k] is NOT fiber-local on this Ruby. ' \
+                'Hyperion requires Ruby 3.2+ for safe fiber-per-request scope. ' \
+                "Got Ruby #{RUBY_VERSION}."
+        end
+
+        true
+      ensure
+        ::Thread.current[marker] = nil
+      end
+
+      # Opt-in patch that routes thread_variable_get/set to fiber storage.
+      # Most apps DO NOT need this — Ruby 3.2+ symbol-keyed Thread.current[]
+      # is already fiber-local. Only install! if your app uses
+      # thread_variable_set for request scope.
+      def install!
+        return if @installed
+
+        ::Thread.class_eval do
+          alias_method :__hyperion_orig_tvar_get, :thread_variable_get
+          alias_method :__hyperion_orig_tvar_set, :thread_variable_set
+
+          define_method(:thread_variable_get) do |key|
+            sym = key.to_sym
+            storage = ::Fiber.current.storage
+            return storage[sym] if storage&.key?(sym)
+
+            __hyperion_orig_tvar_get(key)
+          end
+
+          define_method(:thread_variable_set) do |key, value|
+            ::Fiber.current.storage ||= {}
+            ::Fiber.current.storage[key.to_sym] = value
+          end
+        end
+
+        @installed = true
+      end
+
+      # Test-only undo. Not promised for production.
+      def uninstall!
+        return unless @installed
+
+        ::Thread.class_eval do
+          alias_method :thread_variable_get, :__hyperion_orig_tvar_get
+          alias_method :thread_variable_set, :__hyperion_orig_tvar_set
+          remove_method :__hyperion_orig_tvar_get
+          remove_method :__hyperion_orig_tvar_set
+        end
+
+        @installed = false
+      end
+    end
+  end
+end