hyperion-rb 1.6.2 → 2.11.0

data/lib/hyperion/deprecations.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Hyperion
+  # 1.8.0 deprecation-warn helper. RFC §3 requires a one-shot warn per
+  # deprecated API call site / key per process — emitted via the runtime
+  # logger when available, falling back to $stderr at very-early boot
+  # (before `Hyperion::Runtime.default.logger` is reachable).
+  #
+  # The deprecated APIs themselves keep working untouched in 1.8.0; the
+  # warn is purely informational. Removal lands in 2.0.0 per the RFC §3
+  # release plan.
+  #
+  # Tests that trip the deprecation paths intentionally can capture the
+  # output by swapping `Hyperion::Runtime.default.logger`; tests that
+  # want silence call `Deprecations.silence!` in a `before(:each)` and
+  # `Deprecations.reset!` in `after(:each)` to start with a clean slate.
+  module Deprecations
+    @warned = {}
+    @silenced = false
+    MUTEX = Mutex.new
+
+    module_function
+
+    # Emit a one-shot deprecation warn for `key`. Subsequent calls with
+    # the same key in the same process are no-ops. Thread-safe (the
+    # check-and-record runs under a Mutex) so two workers initializing
+    # at once don't double-emit on the same key.
+    def warn_once(key, message)
+      return if @silenced
+
+      MUTEX.synchronize do
+        return if @warned[key]
+
+        @warned[key] = true
+      end
+
+      emit("[hyperion] DEPRECATION: #{message}")
+    end
+
+    # Test seam: clear the dedup table so a spec can re-trigger a warn
+    # it just exercised. Combined with `silence!`/`unsilence!` tests can
+    # both assert the dedup behaviour and avoid noise on baseline runs.
+    def reset!
+      MUTEX.synchronize { @warned.clear }
+    end
+
+    # Test seam: suppress all warns until `unsilence!` is called. Used
+    # by the broad test suite which intentionally exercises the
+    # deprecated DSL surface and would otherwise flood output.
+    def silence!
+      @silenced = true
+    end
+
+    def unsilence!
+      @silenced = false
+    end
+
+    def silenced?
+      @silenced
+    end
+
+    # Visibility for assertion: did we already warn on `key`?
+    def warned?(key)
+      MUTEX.synchronize { @warned.key?(key) }
+    end
+
+    def emit(line)
+      logger = Hyperion::Runtime.default.logger if defined?(Hyperion::Runtime)
+      if logger.respond_to?(:warn)
+        logger.warn { { message: 'deprecation', detail: line } }
+      else
+        warn(line)
+      end
+    rescue StandardError
+      # Logger swap mid-emit / very-early boot — fall back to $stderr so
+      # the operator at least sees something on the console.
+      warn(line)
+    end
+    private_class_method :emit
+  end
+end

data/lib/hyperion/dispatch_mode.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Hyperion
+  # Internal value object replacing the 4-flag / 5-output if/elsif state
+  # machine that lived in `Server#dispatch` and `Server#inline_h1_dispatch?`.
+  # Pre-1.7 the matrix (`@tls`, `@async_io ∈ {nil, true, false}`,
+  # `@thread_count`, ALPN) was prose-only — no enum, no boot validation,
+  # operators verified the shape by reading the 1.4.0 changelog.
+  #
+  # 1.7 ships the value object internally + plumbs it at the dispatch call
+  # sites. Operators don't see it — they read modes via per-mode counters
+  # (`Hyperion.stats[:requests_dispatch_<mode>]`). Two reasons it is NOT
+  # public surface:
+  #
+  #   1. The `name` set is small but expected to grow as we add transports
+  #      (HTTP/3, h2c upgrade); locking it now would force a major-bump
+  #      churn for every new mode.
+  #   2. Operators using stats keys instead of reflection are insulated
+  #      from rename refactors — `:requests_dispatch_threadpool` keeps
+  #      working even if the internal symbol changes.
+  #
+  # Frozen after construction so a caller can't mutate the mode out from
+  # under a hot-path branch. Equality + hash are by `name` so it slots
+  # cleanly into per-mode metric keys without surprising identity checks.
+  class DispatchMode
+    # The 6 dispatch shapes Hyperion currently honours. Names mirror the
+    # RFC's wording so readers can map between the two without translation:
+    #   :tls_h2              — TLS connection that ALPN-picked HTTP/2
+    #   :tls_h1_inline       — TLS HTTP/1.1, served inline on accept fiber
+    #                          (1.4.0+ default; preserves Async scheduler
+    #                          for hyperion-async-pg / async-redis)
+    #   :async_io_h1_inline  — Plain HTTP/1.1 with `async_io: true`,
+    #                          served inline on the calling fiber
+    #   :threadpool_h1       — Plain or TLS HTTP/1.1 dispatched to the
+    #                          worker thread pool (`-t N`, default)
+    #   :inline_h1_no_pool   — Plain HTTP/1.1, no pool (`-t 0`); served
+    #                          inline on the accept thread/fiber
+    #   :inline_blocking     — 2.6-C: Puma-style serial-per-thread response
+    #                          write for static-file routes.  Connection's
+    #                          connection-wide mode (typically threadpool)
+    #                          stays unchanged; `:inline_blocking` is opt-
+    #                          in PER RESPONSE for bodies that respond to
+    #                          `:to_path`.  No fiber yield, no per-chunk
+    #                          EAGAIN dance — the OS thread parks on the
+    #                          kernel write under the GVL.  Operator-level
+    #                          escape hatch via `env['hyperion.dispatch_mode']
+    #                          = :inline_blocking` for routes the auto-
+    #                          detect doesn't catch.
+    MODES = %i[tls_h2 tls_h1_inline async_io_h1_inline threadpool_h1 inline_h1_no_pool
+               inline_blocking].freeze
+
+    INLINE_MODES = %i[tls_h1_inline async_io_h1_inline inline_h1_no_pool inline_blocking].freeze
+
+    attr_reader :name
+
+    # Resolve the mode for a single dispatch from the four signals that
+    # drive the matrix. ALPN is only relevant when TLS is in play; the
+    # caller passes nil for plain HTTP. `thread_count` is a positive
+    # integer (pool present) or 0 (no pool, dispatch inline).
+    #
+    # Semantics intentionally mirror the pre-1.7 if/elsif chain in
+    # `Server#dispatch` so the refactor is behaviour-preserving.
+    def self.resolve(tls:, async_io:, thread_count:, alpn: nil)
+      return new(:tls_h2) if tls && alpn == 'h2'
+      return new(:tls_h1_inline) if tls && async_io != false
+      return new(:async_io_h1_inline) if !tls && async_io == true
+      return new(:threadpool_h1) if thread_count.to_i.positive?
+
+      new(:inline_h1_no_pool)
+    end
+
+    def initialize(name)
+      raise ArgumentError, "unknown DispatchMode #{name.inspect}" unless MODES.include?(name)
+
+      @name = name
+      freeze
+    end
+
+    # Inline-on-fiber dispatch (no thread-pool hop). Three shapes qualify:
+    # tls_h1_inline (default for TLS h1), async_io_h1_inline (operator
+    # opted into fiber I/O on plain h1), inline_h1_no_pool (`-t 0`).
+    def inline?
+      INLINE_MODES.include?(@name)
+    end
+
+    def threadpool?
+      @name == :threadpool_h1
+    end
+
+    def h2?
+      @name == :tls_h2
+    end
+
+    # 2.6-C — Puma-style serial-per-thread response write for static-
+    # file routes.  Per-response opt-in (NOT a connection-wide mode);
+    # the underlying connection still dispatches via its configured
+    # mode (`:async_io_h1_inline`, `:threadpool_h1`, `:tls_h1_inline`,
+    # `:inline_h1_no_pool`).  When this mode engages, the response-
+    # write path uses `Sendfile.copy_to_socket_blocking` instead of
+    # the fiber-yielding `copy_to_socket` — the OS thread parks on
+    # the kernel write under the GVL, no per-chunk EAGAIN-yield
+    # round-trip.
+    def inline_blocking?
+      @name == :inline_blocking
+    end
+
+    # 2.6-C — whether the response is dispatched on a fiber that may
+    # yield cooperatively to the scheduler.  False for `:inline_blocking`
+    # (the whole point — block the OS thread on write rather than yield
+    # the fiber) and for `:threadpool_h1` / `:inline_h1_no_pool` (no
+    # scheduler in scope).  True for the three async-scheduler shapes
+    # (`:tls_h1_inline`, `:async_io_h1_inline`, `:tls_h2`).
+    def fiber_dispatched?
+      @name == :tls_h2 || @name == :tls_h1_inline || @name == :async_io_h1_inline
+    end
+
+    # Whether dispatch yields cooperatively (Async scheduler current on
+    # the calling fiber). True for TLS h1 inline (TLS already wraps the
+    # accept loop in Async), async_io_h1_inline (operator opted in), and
+    # h2 (per-stream fibers). False for threadpool dispatch (worker
+    # thread, no scheduler), `-t 0` plain HTTP, and `:inline_blocking`
+    # (per-response opt-in that explicitly disables fiber yield on the
+    # response-write path).
+    def async?
+      @name == :tls_h2 || @name == :tls_h1_inline || @name == :async_io_h1_inline
+    end
+
+    # Whether the dispatch goes through `ThreadPool#submit_connection`
+    # (or `ThreadPool#call` on the h2 per-stream path).
+    def pooled?
+      @name == :threadpool_h1
+    end
+
+    # Per-mode metric key. Stable across releases — operators alert on
+    # `:requests_dispatch_threadpool` etc. directly. The full set is
+    # documented in the README's Metrics section.
+    def metric_key
+      :"requests_dispatch_#{@name}"
+    end
+
+    def ==(other)
+      other.is_a?(DispatchMode) && other.name == @name
+    end
+    alias eql? ==
+
+    # Symbol#hash — DispatchMode is a value object keyed on `name`, so
+    # rehashing under the underlying symbol gives correct Hash bucket
+    # placement without allocating.
+    def hash
+      n = @name
+      n.hash
+    end
+
+    # -- this gem has no ActiveSupport on
+    # its dependency graph; `delegate` is unavailable. Plain method.
+    def to_s
+      n = @name
+      n.to_s
+    end
+
+    def inspect
+      "#<Hyperion::DispatchMode #{@name}>"
+    end
+  end
+end

data/lib/hyperion/fiber_local.rb

@@ -25,11 +25,38 @@ module Hyperion
   # 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).
+  # `Hyperion::FiberLocal.install!(async_io:)` — opt-in monkey-patch that
+  # routes `thread_variable_get`/`thread_variable_set` to fiber storage. Use
+  # only if your app uses `thread_variable_set` for request scope under
+  # fiber-per-request concurrency.
+  #
+  # ## 1.4.x compat — the regression this gates against
+  #
+  # 1.4.x fixed a bug where Hyperion's own Logger access buffer + Metrics
+  # counters were stranded under `Async::Scheduler` because they were stored
+  # on `Thread.current[:k]` (which is fiber-local in Ruby 3.2+). The fix
+  # switched those to `Thread#thread_variable_*`, which is the only TRUE
+  # thread-local storage in CRuby (commits f987462 + e8db450). A blanket
+  # FiberLocal monkey-patch would re-route those calls to fiber storage and
+  # restage the exact bug 1.4.x fixed. To stay compatible:
+  #
+  # 1. When `async_io` is OFF (the default — single-thread or thread-pool
+  #    mode, no scheduler in play), `install!` is a no-op. The shim has no
+  #    purpose without fibers, and patching only risks re-introducing the
+  #    1.4.x stranded-counter bug if a thread pool ever runs job N and
+  #    job N+1 in distinct fibers on the same OS thread.
+  # 2. When `async_io` is ON, the patched `thread_variable_*` reserves the
+  #    `__hyperion_*` symbol keys for true thread-local storage so Hyperion's
+  #    Logger/Metrics keep aggregating correctly. Everything else routes to
+  #    `Fiber.current.storage` for fiber-per-request isolation.
   module FiberLocal
+    # Symbol keys with this prefix bypass the fiber-storage routing and use
+    # the original `thread_variable_*` semantics. Hyperion's internal
+    # Logger access buffer + ts-cache and Metrics counters all live behind
+    # this prefix and rely on TRUE thread-local storage to survive fiber
+    # scheduling on the same OS thread (1.4.x guarantee).
+    HYPERION_KEY_PREFIX = '__hyperion_'
+
     @installed = false
 
     class << self
@@ -59,27 +86,62 @@ module Hyperion
       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!
+      #
+      # `async_io:` MUST be true to install the shim. With async_io off there
+      # are no fibers in flight and patching only risks the 1.4.x regression
+      # (stranded Logger/Metrics counters when a thread pool runs successive
+      # jobs in different fibers). When async_io is off we log a warning and
+      # leave thread_variable_* on its original (truly thread-local) path.
+      #
+      # Even with the shim installed, `__hyperion_*` symbol keys still route
+      # to the original thread_variable_* — Hyperion's own Logger and Metrics
+      # depend on true thread-local storage and must not be redirected to
+      # fiber storage. See the module docstring for the full rationale.
+      def install!(async_io: false)
         return if @installed
 
+        unless async_io
+          # 1.4.x compat: with no fibers in play the shim has no purpose,
+          # and patching `thread_variable_*` to fiber storage would
+          # re-introduce the bug 1.4.x fixed (Logger/Metrics counters
+          # stranded across thread-pool jobs that happen to run in distinct
+          # fibers on the same OS thread). Make this a no-op and tell the
+          # operator we ignored their flag.
+          Hyperion.logger.warn do
+            { message: 'FiberLocal.install! ignored — async_io is off',
+              hint: 'The shim only matters under fiber-per-request concurrency. ' \
+                    'Enable async_io: true (or pass --async-io) to opt in.' }
+          end
+          return
+        end
+
+        prefix = HYPERION_KEY_PREFIX
+
         ::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-internal keys always use TRUE thread-local storage
+            # to preserve the 1.4.x guarantee for Logger/Metrics.
+            return __hyperion_orig_tvar_get(sym) if sym.to_s.start_with?(prefix)
 
-            __hyperion_orig_tvar_get(key)
+            # Fiber#storage returns a COPY, so the canonical fiber-local
+            # access path is `Fiber[]` — it reads through to the underlying
+            # storage and falls back to inherited storage on parent fibers.
+            ::Fiber[sym]
           end
 
           define_method(:thread_variable_set) do |key, value|
-            ::Fiber.current.storage ||= {}
-            ::Fiber.current.storage[key.to_sym] = value
+            sym = key.to_sym
+            # Hyperion-internal keys always use TRUE thread-local storage
+            # to preserve the 1.4.x guarantee for Logger/Metrics.
+            return __hyperion_orig_tvar_set(sym, value) if sym.to_s.start_with?(prefix)
+
+            # Use `Fiber[]=` (not `Fiber.current.storage[k] = v`) — the
+            # latter mutates a copy and does not persist across reads.
+            ::Fiber[sym] = value
           end
         end
 

data/lib/hyperion/h2_admission.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Hyperion
+  # Process-wide HTTP/2 stream admission control (RFC A7).
+  #
+  # **Problem.** `h2_max_concurrent_streams` (default 128) caps streams
+  # *per connection*. An abuser can open 5,000 connections × 128 streams
+  # = 640k fibers → OOM → master respawns → abuser reconnects. The 1.6.0
+  # backpressure cap on bytes-in-queue is 16 MiB *per connection*, so it
+  # doesn't bound aggregate fiber count either. Real DoS vector,
+  # currently no built-in defence.
+  #
+  # **Shape.** A single per-process atomic counter shared across all
+  # `Http2Handler` instances within a worker. Each new stream calls
+  # `#admit` before invoking the app; the call returns true when the
+  # slot was reserved and false when the cap is hit. False → caller
+  # sends `RST_STREAM REFUSED_STREAM` (RFC 7540 §11 / RFC 9113 §5.4.1).
+  # Slot is freed by `#release` from the dispatch ensure block.
+  #
+  # **Default.** `max_total_streams: nil` — admission disabled, every
+  # `#admit` returns true. `Server` only constructs an `H2Admission`
+  # when the operator passes a positive cap. The 1.7.0 default is `nil`;
+  # 2.0 flips to `h2_max_concurrent_streams × workers × 4` (RFC §3
+  # 1.x-vs-2.0 split).
+  #
+  # **Concurrency.** Mutex hold time is "increment + compare", in the
+  # tens of nanoseconds. The mutex is contention-bounded by the actual
+  # rate of new stream admits, which is much lower than dispatch rate
+  # (one mutex acquire per stream, not per frame). On the abuser's
+  # path this is also where they hit the wall — by design.
+  class H2Admission
+    attr_reader :max
+
+    def initialize(max_total_streams:)
+      @max     = max_total_streams
+      @count   = 0
+      @rejected = 0
+      @mutex = Mutex.new
+    end
+
+    # Try to acquire one stream slot. Returns true when admitted, false
+    # when the cap is hit. nil cap (admission disabled) returns true
+    # without taking the mutex — keeps the hot path branchless when
+    # admission is off.
+    def admit
+      return true if @max.nil?
+
+      @mutex.synchronize do
+        if @count >= @max
+          @rejected += 1
+          false
+        else
+          @count += 1
+          true
+        end
+      end
+    end
+
+    # Release a previously-admitted slot. Idempotent: if the count is
+    # already zero (paranoia: double-release on a programming bug) this
+    # is a no-op. nil cap is a no-op (admission disabled).
+    def release
+      return if @max.nil?
+
+      @mutex.synchronize { @count -= 1 if @count.positive? }
+    end
+
+    # Snapshot the admission state. `in_flight` = streams currently
+    # holding a slot, `rejected` = cumulative count of REFUSED_STREAM
+    # events served by this gate, `max` = configured cap. Used by
+    # operator dashboards via `Hyperion.stats[:h2_admission_*]` keys
+    # (the stats publisher pulls these out and surfaces them).
+    def stats
+      @mutex.synchronize { { in_flight: @count, rejected: @rejected, max: @max } }
+    end
+  end
+end