hyperion-rb 1.6.2 → 2.10.1

data/lib/hyperion.rb

@@ -3,22 +3,48 @@
 require_relative 'hyperion/version'
 require_relative 'hyperion/logger'
 require_relative 'hyperion/metrics'
+require_relative 'hyperion/runtime'
+require_relative 'hyperion/deprecations'
+require_relative 'hyperion/dispatch_mode'
 require_relative 'hyperion/config'
+require_relative 'hyperion/h2_admission'
 
 module Hyperion
   class Error < StandardError; end
   class ParseError < Error; end
   class UnsupportedError < Error; end
 
+  # Probe table for fiber-cooperative I/O libraries. 1.7.0 expanded
+  # the validation surface (RFC A9): `async_io: true` now requires at
+  # least one of these to be loaded, otherwise CLI bootstrap raises
+  # at `Hyperion.validate_async_io_loaded_libs!`. The CLI's pre-fork
+  # `warn_orphan_async_io` (1.6.1) still emits a soft warn for the
+  # nil-default case so existing operators see the same advisory log.
+  FIBER_IO_PROBES = {
+    'hyperion-async-pg' => -> { defined?(::Hyperion::AsyncPg) },
+    'async-redis' => -> { defined?(::Async::Redis) },
+    'async-http' => -> { defined?(::Async::HTTP) }
+  }.freeze
+
   class << self
+    # 2.0.0: legacy module-level `Hyperion.metrics =` / `Hyperion.logger =`
+    # SETTERS are removed. The getters stay as Runtime.default delegators —
+    # they're the canonical REPL convenience — and assignment now happens
+    # via the Runtime API:
+    #
+    #   Hyperion::Runtime.default.metrics = MyAdapter.new   # mutate default
+    #   server = Hyperion::Server.new(app:, runtime: Hyperion::Runtime.new(metrics: …))
+    #
+    # The 1.8.0 deprecation warns called this out for one full release;
+    # in-tree spec rewrites flipped to `Runtime.default.metrics =` already.
     def logger
-      @logger ||= Logger.new
+      Runtime.default.logger
     end
 
-    attr_writer :logger, :log_requests
+    attr_writer :log_requests
 
     def metrics
-      @metrics ||= Metrics.new
+      Runtime.default.metrics
     end
 
     def stats
@@ -75,6 +101,95 @@ module Hyperion
     # with a warn log: warmup is an optimization, not a correctness gate.
     # If, for instance, OpenSSL can't be required in some odd environment,
     # we'd rather start cold than refuse to boot.
+    # PID of the Hyperion master process. Writable so the master records its
+    # own PID at boot; readable everywhere so AdminMiddleware (and other
+    # would-be signallers) can target the master regardless of context.
+    #
+    # Why not `Process.ppid`? Two reasons:
+    #
+    #   1. In single-worker mode, the "master" and "worker" are the same
+    #      process; `Process.ppid` points to the shell / init that launched
+    #      hyperion, NOT to ourselves.
+    #   2. When the master runs as PID 1 inside containerd / Docker (the
+    #      default for `hyperion` as a container CMD), `Process.ppid` from a
+    #      worker is `1` — but the worker IS a child of PID 1, so `kill`ing
+    #      ppid signals the master correctly only by accident, and the
+    #      pre-1.6.3 fallback `ppid > 1 ? ppid : Process.pid` would
+    #      MIS-target the worker itself. (Repro: `docker run -e
+    #      HYPERION_ADMIN_TOKEN=… hyperion` then `curl -X POST /-/quit` —
+    #      response says draining, nothing happens.)
+    #
+    # The master sets this at boot (cluster: Master#run, single: CLI.run_single)
+    # AND exports `HYPERION_MASTER_PID` into ENV so forked workers read the
+    # correct value via copy-on-write. The reader prefers the in-process
+    # ivar (faster) and falls back to ENV (cross-fork) and finally to
+    # `Process.pid` (last-resort: someone constructed AdminMiddleware before
+    # the master booted, or in a non-Hyperion test context).
+    def master_pid
+      return @master_pid if @master_pid
+
+      env = ENV['HYPERION_MASTER_PID']
+      env_pid = env && env =~ /\A\d+\z/ ? env.to_i : nil
+      env_pid&.positive? ? env_pid : Process.pid
+    end
+
+    # Record the master PID and export it for forked workers. Called once
+    # by the master at boot. Workers inherit ENV via fork; the worker's own
+    # `master_pid` ivar stays nil and its reader falls back to ENV.
+    def master_pid!(pid = Process.pid)
+      @master_pid = pid
+      ENV['HYPERION_MASTER_PID'] = pid.to_s
+      pid
+    end
+
+    # Returns the list of currently-loaded fiber-cooperative I/O
+    # libraries. Reads `Hyperion::FIBER_IO_PROBES` via `const_get` so
+    # `stub_const('Hyperion::FIBER_IO_PROBES', ...)` works for the
+    # strict-validation specs without needing a method-injection seam.
+    def fiber_io_libs_loaded
+      probes = Hyperion.const_get(:FIBER_IO_PROBES)
+      probes.select { |_name, probe| probe.call }.keys
+    end
+
+    # Strict tri-state validation of `async_io` at warmup time (RFC A9).
+    # Run after `Hyperion.warmup!`'s eager-load section so any library
+    # that monkey-patches in fiber-cooperative I/O during boot has had
+    # the chance to install itself.
+    #
+    # - `true`  → MUST have at least one fiber-IO library loaded; raise
+    #            ArgumentError otherwise. The error message lists the
+    #            checked libraries so operators can pick one.
+    # - `false` → No fiber-IO library should be loaded; if one is, emit
+    #            a warn (the operator may still want this for some
+    #            edge case, so we don't raise).
+    # - `nil`   → Default. The CLI's existing soft-warn path covers
+    #            this; warmup is a no-op.
+    def validate_async_io_loaded_libs!(setting)
+      probes = Hyperion.const_get(:FIBER_IO_PROBES)
+      case setting
+      when true
+        loaded = fiber_io_libs_loaded
+        if loaded.empty?
+          raise ArgumentError,
+                'async_io: true requires a fiber-cooperative I/O library to be loaded ' \
+                "(checked: #{probes.keys.join(', ')}); none detected. " \
+                'See https://github.com/andrew-woblavobla/hyperion#operator-guidance'
+        end
+      when false
+        loaded = fiber_io_libs_loaded
+        unless loaded.empty?
+          Hyperion.logger.warn do
+            {
+              message: 'async_io: false but fiber-cooperative I/O library is loaded',
+              loaded: loaded,
+              impact: 'the library will not yield to a scheduler under async_io: false; verify this is intentional'
+            }
+          end
+        end
+      end
+      nil
+    end
+
     def warmup!
       return if @warmed
 
@@ -97,10 +212,22 @@ module Hyperion
       # Subsequent calls hit the per-thread `cached_date` slot in response_writer.
       Time.now.httpdate
       nil
+    rescue ArgumentError
+      # Strict-validation error from `validate_async_io_loaded_libs!` —
+      # propagate so operators see the boot-time abort, not a warn-and-
+      # continue.
+      raise
     rescue StandardError => e
       Hyperion.logger.warn { { message: 'warmup failed (non-fatal)', error: e.message } }
       nil
     end
+
+    # Test seam: clear the warmup flag so a fresh `warmup!` call can
+    # re-run. Used by the async_io strict-validation specs that need to
+    # exercise the raise/warn paths multiple times in one process.
+    def reset_warmup!
+      @warmed = false
+    end
   end
 end
 
@@ -126,9 +253,16 @@ require_relative 'hyperion/fiber_local'
 require_relative 'hyperion/request'
 require_relative 'hyperion/parser'
 require_relative 'hyperion/c_parser'
+require_relative 'hyperion/http/sendfile'
+require_relative 'hyperion/http/page_cache'
+require_relative 'hyperion/static_preload'
 require_relative 'hyperion/adapter/rack'
+require_relative 'hyperion/lint_wrapper_pool'
 require_relative 'hyperion/prometheus_exporter'
 require_relative 'hyperion/admin_middleware'
+require_relative 'hyperion/admin_listener'
+require_relative 'hyperion/h2_codec'
+require_relative 'hyperion/io_uring'
 require_relative 'hyperion/response_writer'
 require_relative 'hyperion/thread_pool'
 require_relative 'hyperion/connection'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperion-rb
 version: !ruby/object:Gem::Version
-  version: 1.6.2
+  version: 2.10.1
 platform: ruby
 authors:
 - Andrey Lobanov
@@ -83,6 +83,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -132,41 +146,76 @@ email:
 executables:
 - hyperion
 extensions:
+- ext/hyperion_h2_codec/extconf.rb
 - ext/hyperion_http/extconf.rb
+- ext/hyperion_io_uring/extconf.rb
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE
 - README.md
 - bin/hyperion
+- ext/hyperion_h2_codec/Cargo.lock
+- ext/hyperion_h2_codec/Cargo.toml
+- ext/hyperion_h2_codec/extconf.rb
+- ext/hyperion_h2_codec/src/frames.rs
+- ext/hyperion_h2_codec/src/hpack.rs
+- ext/hyperion_h2_codec/src/hpack/huffman.rs
+- ext/hyperion_h2_codec/src/lib.rs
 - ext/hyperion_http/extconf.rb
+- ext/hyperion_http/h2_codec_glue.c
 - ext/hyperion_http/llhttp/api.c
 - ext/hyperion_http/llhttp/http.c
 - ext/hyperion_http/llhttp/llhttp.c
 - ext/hyperion_http/llhttp/llhttp.h
+- ext/hyperion_http/page_cache.c
 - ext/hyperion_http/parser.c
+- ext/hyperion_http/sendfile.c
+- ext/hyperion_http/websocket.c
+- ext/hyperion_io_uring/Cargo.lock
+- ext/hyperion_io_uring/Cargo.toml
+- ext/hyperion_io_uring/extconf.rb
+- ext/hyperion_io_uring/src/lib.rs
 - lib/hyperion-rb.rb
 - lib/hyperion.rb
 - lib/hyperion/adapter/rack.rb
+- lib/hyperion/admin_listener.rb
 - lib/hyperion/admin_middleware.rb
 - lib/hyperion/c_parser.rb
 - lib/hyperion/cli.rb
 - lib/hyperion/config.rb
 - lib/hyperion/connection.rb
+- lib/hyperion/deprecations.rb
+- lib/hyperion/dispatch_mode.rb
 - lib/hyperion/fiber_local.rb
+- lib/hyperion/h2_admission.rb
+- lib/hyperion/h2_codec.rb
+- lib/hyperion/http/page_cache.rb
+- lib/hyperion/http/sendfile.rb
+- lib/hyperion/http2/native_hpack_adapter.rb
 - lib/hyperion/http2_handler.rb
+- lib/hyperion/io_uring.rb
+- lib/hyperion/lint_wrapper_pool.rb
 - lib/hyperion/logger.rb
 - lib/hyperion/master.rb
 - lib/hyperion/metrics.rb
+- lib/hyperion/metrics/path_templater.rb
 - lib/hyperion/parser.rb
 - lib/hyperion/pool.rb
 - lib/hyperion/prometheus_exporter.rb
 - lib/hyperion/request.rb
 - lib/hyperion/response_writer.rb
+- lib/hyperion/runtime.rb
 - lib/hyperion/server.rb
+- lib/hyperion/server/route_table.rb
+- lib/hyperion/static_preload.rb
 - lib/hyperion/thread_pool.rb
 - lib/hyperion/tls.rb
 - lib/hyperion/version.rb
+- lib/hyperion/websocket/close_codes.rb
+- lib/hyperion/websocket/connection.rb
+- lib/hyperion/websocket/frame.rb
+- lib/hyperion/websocket/handshake.rb
 - lib/hyperion/worker.rb
 - lib/hyperion/worker_health.rb
 homepage: https://github.com/andrew-woblavobla/hyperion