hyperion-rb 2.15.0 → 2.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89ad0e591a8a44e23597ab8aa800ea65437c3e90d77903f7b3433c36368c87de
-  data.tar.gz: b8a17ba534c62e8aa9d1b91f23e7baebf5a49d3074617fbcf73a328363e76aa4
+  metadata.gz: d599cad6595983a3aef241b7e5895b613c6275e44e8f05925f29c82fba99072c
+  data.tar.gz: c733f8b8e0f2d7de93a5bed82d4cea1331bbafafde347334cf08bbb00f8c1474
 SHA512:
-  metadata.gz: 7e0059eba0f4d925bab72a1a7c4371e4e74c7336e62ac26135d3450480bfe6979ade740f0b7c236bfac67592eec40662ba0fca72c761cc2e208b8063dc6c04bb
-  data.tar.gz: 5e38e2d43c8c8dea1f1dfce54639c7ea11377905a7193b3e87199c78f7aacccbed30218ec49ba1e1f39317541f361501671ded4b0d0875503806cc3680a9a856
+  metadata.gz: 8311ce71399125875a3bab4499244801dfeac405512a6a3339762dc075e495a86e961f1135eb33ec8ac30c7d2e0bb46d0951a53ba144f42a1a40fce855889a74
+  data.tar.gz: c1eee7b3bdc928bdf328223abf54c80d5a1d9742a770968063659a98943a04e7c0f3b5530c4b5e5fef62847ccf29d6ddafb4cf8e7b4ee187968a82c27ad0f8b5

data/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## 2.16.0 — 2026-05-04
+
+### 2.16-A — `preload false`: macOS fork+resolver escape hatch
+
+**Why.** On macOS, Hyperion's "always preload" model deadlocks
+post-fork DNS resolution for any deployment whose master process
+ends up touching `Network.framework` — typically through native
+gems loaded transitively via `Bundler.require` (OpenSSL session
+caches, observability agents, Foundation-backed clients). The
+master's `Network.framework` path evaluator initializes against XPC
+peers in `mDNSResponder`; after `fork()` those XPC connections are
+invalid in the workers, and the next `getaddrinfo` call hangs
+forever inside `nw_path_evaluator_evaluate` →
+`nw_nat64_v4_address_requires_synthesis`. The symptom: workers
+spin at 99% CPU, requests TCP-connect but never get a response,
+no per-request log line ever fires.
+`OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES` does not help — that
+flag only covers Foundation / Obj-C runtime init, not
+`Network.framework`.
+
+The reason Puma users don't hit this: Puma without explicit
+`preload_app! true` runs in non-preload mode, so the master is a
+thin supervisor and each worker loads the Rack app post-fork
+against a clean process. Hyperion shipped no such option — preload
+was the only mode.
+
+**What 2.16-A ships.**
+
+1. **`preload` config field** (default `true` to preserve current
+   behaviour). When `preload false` is set in `config/hyperion.rb`
+   or `--no-preload` is passed on the CLI, the master never loads
+   `config.ru` and never calls `Hyperion.warmup!`. Each worker
+   parses the rackup itself post-fork via the same
+   `Hyperion::CLI.load_rack_app` path the master used to use; the
+   admin middleware wrap is preserved per-worker. `--preload` is
+   the inverse for argv overrides.
+
+2. **Single-worker mode is exempt.** With `workers <= 1` there is
+   no fork to protect against, so `run_single` always loads the
+   app in-process — deferring the parse buys nothing and would
+   surface lifecycle hooks against an unloaded app.
+
+3. **Master/Worker plumbing.** `Master.new` gains a `rackup_path:`
+   kwarg; `Worker.new` mirrors it and lazy-parses if `@app` is
+   `nil` and a path was provided. Both keep their existing
+   contract for the preload path (master receives `app:`, workers
+   inherit via fork).
+
+**Trade-off.** Non-preload loses copy-on-write — each worker pays
+the full Rails-boot RSS independently. Steady-state memory is N×
+higher and worker boot is slower. The escape hatch is meant for
+operators who hit the macOS deadlock; Linux users should leave it
+at the default (`preload true`).
+
+**Verification.**
+
+- `bin/check` green (81 examples, 0 failures).
+- Hand-reproduced against a Rails 8.1 application with a typical
+  native-gem stack (OpenSSL, observability agent, multi-A-record
+  DNS host for the database). Without `preload false`: deadlock
+  reproduces deterministically; CPU pegs at 99% per worker; curl
+  times out. With `preload false`: requests return promptly.
+
 ## 2.15.0 — 2026-05-02
 
 ### 2.15-A — Fresh bench, README split, CI flake fix

data/bin/check

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# Hyperion health-check. Run this BEFORE claiming a change is "all green".
+#
+# Usage:
+#   bin/check                       # default: compile + syntax + smoke specs (~10s)
+#   bin/check --quick               # same as default
+#   bin/check --full                # compile + syntax + full rspec (perf excluded)
+#   bin/check --syntax-only         # compile + ruby -wc on lib/
+#   bin/check spec/path/foo_spec.rb [more...]   # compile + targeted specs
+#
+# Exits non-zero on the first failing stage. Hooks-friendly: stdout is
+# stage-tagged so .claude/bin/run-bounded.sh shows the right slice on tail.
+#
+# Smoke set covers the request hot path: parser, request, response writer,
+# connection lifecycle, server loop, runtime. Each spec runs in <1s on a
+# warm bundler cache; the full set lands in ~5–10s total.
+
+set -uo pipefail
+
+cd "$(dirname "$0")/.."
+
+mode="quick"
+specs=()
+if [ $# -gt 0 ]; then
+  case "$1" in
+    --quick) mode="quick"; shift ;;
+    --full) mode="full"; shift ;;
+    --syntax-only) mode="syntax" ;;
+    -h|--help)
+      sed -n '2,15p' "$0"
+      exit 0 ;;
+    *) mode="targeted"; specs=("$@") ;;
+  esac
+fi
+
+stage() { printf '\n=== %s ===\n' "$1"; }
+fail()  { printf '\n!!! FAIL: %s\n' "$1"; exit 1; }
+
+# --- 1. Compile (always; cheap if already built) -----------------------------
+stage "compile (rake compile)"
+bundle exec rake compile || fail "rake compile"
+
+# --- 2. Syntax check on lib/ (fast, catches typos before specs load) --------
+stage "ruby -wc on lib/hyperion/**/*.rb"
+syntax_errors=0
+while IFS= read -r -d '' f; do
+  if ! ruby -wc "$f" >/dev/null 2>/tmp/hyperion-check-syntax.err; then
+    printf '  syntax: %s\n' "$f"
+    cat /tmp/hyperion-check-syntax.err
+    syntax_errors=$((syntax_errors + 1))
+  fi
+done < <(find lib -name '*.rb' -type f -print0)
+[ "$syntax_errors" -eq 0 ] || fail "$syntax_errors file(s) failed ruby -wc"
+
+if [ "$mode" = "syntax" ]; then
+  printf '\nOK (compile + syntax only)\n'
+  exit 0
+fi
+
+# --- 3. Specs ---------------------------------------------------------------
+case "$mode" in
+  quick)
+    stage "rspec smoke set"
+    bundle exec rspec --fail-fast \
+      spec/hyperion/c_parser_spec.rb \
+      spec/hyperion/parser_spec.rb \
+      spec/hyperion/request_spec.rb \
+      spec/hyperion/response_writer_spec.rb \
+      spec/hyperion/connection_spec.rb \
+      spec/hyperion/runtime_spec.rb \
+      spec/hyperion/server_spec.rb \
+      spec/hyperion/config_spec.rb \
+      || fail "smoke specs"
+    ;;
+  full)
+    stage "rspec (full; :perf excluded by spec_helper)"
+    bundle exec rspec --fail-fast || fail "full rspec"
+    ;;
+  targeted)
+    stage "rspec ${specs[*]}"
+    bundle exec rspec --fail-fast "${specs[@]}" || fail "targeted specs"
+    ;;
+esac
+
+printf '\nOK (mode=%s)\n' "$mode"

data/lib/hyperion/cli.rb

@@ -97,8 +97,6 @@ module Hyperion
         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`
@@ -107,10 +105,30 @@ module Hyperion
       # (operator-requested unbounded).
       config.finalize!(workers: workers)
 
+      # 2.16 — preload toggle. In preload mode (default) the master
+      # parses config.ru once and workers inherit the loaded app via
+      # copy-on-write. In non-preload mode the master never touches
+      # the app; each worker parses post-fork. The non-preload path
+      # is the documented escape hatch for macOS getaddrinfo+fork
+      # deadlocks; it costs CoW (each worker pays the full boot RSS).
+      preload = config.preload != false
+      if preload
+        app = wrap_admin_middleware(load_rack_app(rackup), config)
+      else
+        app = nil
+        Hyperion.logger.info do
+          { message: 'preload disabled; each worker will parse rackup after fork',
+            rackup: File.expand_path(rackup) }
+        end
+      end
+
       if workers <= 1
+        # Single-mode always preloads — there's no fork to protect from
+        # global state poisoning, so deferring the parse buys nothing.
+        app ||= wrap_admin_middleware(load_rack_app(rackup), config)
         run_single(config, app)
       else
-        run_cluster(config, app, workers)
+        run_cluster(config, app, workers, rackup_path: preload ? nil : File.expand_path(rackup))
       end
     end
 
@@ -258,6 +276,15 @@ WARNING: argv is visible via `ps`; prefer --admin-token-file PATH for production
              'Explicit `--preload-static` dirs still take effect.') do
           cli_opts[:auto_preload_static_disabled] = true
         end
+        # 2.16 — app preload toggle.
+        o.on('--[no-]preload',
+             'Preload the Rack app in the master before fork (default ON). ' \
+             '--no-preload makes each worker parse config.ru post-fork; ' \
+             'needed on macOS when native gems loaded in the master ' \
+             '(anything that touches Network.framework via XPC) ' \
+             'deadlock getaddrinfo in workers post-fork.') do |v|
+          cli_opts[:preload] = v
+        end
         o.on('-h', '--help', 'show help') do
           puts o
           exit 0
@@ -345,20 +372,22 @@ WARNING: argv is visible via `ps`; prefer --admin-token-file PATH for production
       Hyperion.logger.flush_all
     end
 
-    def self.run_cluster(config, app, workers)
+    def self.run_cluster(config, app, workers, rackup_path: nil)
       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
+                 read_timeout: config.read_timeout, config: config,
+                 rackup_path: rackup_path).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.
+    # Normalize so we get just the app either way. Used by both the preload
+    # path (master parses once, before fork) and the non-preload path
+    # (each worker parses post-fork) — see Worker#run.
     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
@@ -610,7 +639,6 @@ WARNING: argv is visible via `ps`; prefer --admin-token-file PATH for production
       end
       AdminMiddleware.new(app, token: config.admin.token)
     end
-    private_class_method :wrap_admin_middleware
 
     # Read the admin token from a file on disk. Refuses to load if the file
     # is missing, unreadable, or world-readable — the whole point of using a

data/lib/hyperion/config.rb

@@ -71,7 +71,25 @@ module Hyperion
       # the `--no-preload-static` CLI flag; lets operators turn off
       # auto-warming on a Rails app while still keeping the option to
       # configure explicit dirs via `preload_static`.
-      auto_preload_static_disabled: false
+      auto_preload_static_disabled: false,
+      # 2.16: app preload toggle. When true (default) the master loads
+      # `config.ru` once before forking — workers inherit the loaded app
+      # via copy-on-write, the canonical Hyperion model. When false, the
+      # master stays a thin supervisor and each worker parses `config.ru`
+      # itself post-fork. Mirrors Puma's `preload_app! false` mode.
+      #
+      # The non-preload mode is the documented escape hatch for macOS
+      # workloads where loading native gems in the master (anything that
+      # initializes Network.framework / CoreFoundation via XPC) leaves
+      # the post-fork resolver in a deadlocked state — `getaddrinfo`
+      # hangs forever in `nw_path_evaluator_evaluate`. Setting `preload
+      # false` keeps the master's address space free of those globals so
+      # workers fork from a clean slate.
+      #
+      # Trade-off: each worker pays the boot cost (CPU + RSS) on its own,
+      # so steady-state RSS is N× higher and worker boot is slower. Linux
+      # users should leave this true.
+      preload: true
     }.freeze
 
     HOOKS = %i[before_fork on_worker_boot on_worker_shutdown].freeze

data/lib/hyperion/master.rb

@@ -68,10 +68,15 @@ module Hyperion
 
     def initialize(host:, port:, app:, workers: DEFAULT_WORKER_COUNT,
                    read_timeout: Server::DEFAULT_READ_TIMEOUT_SECONDS, tls: nil,
-                   thread_count: Server::DEFAULT_THREAD_COUNT, config: nil)
+                   thread_count: Server::DEFAULT_THREAD_COUNT, config: nil,
+                   rackup_path: nil)
       @host         = host
       @port         = port
       @app          = app
+      # 2.16 — non-preload mode: master holds a path; each worker parses
+      # post-fork. Mutually exclusive with @app (asserted by CLI flow:
+      # exactly one of the two is non-nil).
+      @rackup_path  = rackup_path
       @workers      = workers || Etc.nprocessors
       @read_timeout = read_timeout
       @tls          = tls
@@ -118,7 +123,13 @@ module Hyperion
       # BEFORE we fork. Children inherit the warm memory via copy-on-write
       # so the first batch of requests on each fresh worker doesn't pay
       # the allocation/autoload tax.
-      Hyperion.warmup!
+      #
+      # 2.16: skipped in non-preload mode. The whole point of `preload:
+      # false` is to keep the master's address space free of native-gem
+      # globals (OpenSSL session caches, Network.framework XPC state,
+      # etc.) so workers fork from a clean slate. Warming up here would
+      # re-introduce exactly the state we're trying to avoid.
+      Hyperion.warmup! if @app
 
       # `before_fork` runs ONCE in the master before any worker is forked.
       # Operators use it to close shared resources (DB pools, Redis sockets)
@@ -226,6 +237,10 @@ module Hyperion
         Signal.trap('TERM', 'DEFAULT')
         worker_args = {
           host: @host, port: @port, app: @app,
+          # 2.16 — propagate the deferred rackup path. Worker#run loads
+          # via Hyperion::CLI.load_rack_app + wraps admin middleware
+          # post-fork when @app is nil.
+          rackup_path: @rackup_path,
           read_timeout: @read_timeout, tls: @tls,
           thread_count: @thread_count, config: @config,
           worker_index: worker_index,

data/lib/hyperion/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hyperion
-  VERSION = '2.15.0'
+  VERSION = '2.16.0'
 end

data/lib/hyperion/worker.rb

@@ -30,7 +30,8 @@ module Hyperion
                    io_uring: :off,
                    max_in_flight_per_conn: nil,
                    tls_handshake_rate_limit: :unlimited,
-                   preload_static_dirs: nil)
+                   preload_static_dirs: nil,
+                   rackup_path: nil)
       @host                     = host
       @port                     = port
       @app                      = app
@@ -57,6 +58,7 @@ module Hyperion
       @max_in_flight_per_conn            = max_in_flight_per_conn
       @tls_handshake_rate_limit          = tls_handshake_rate_limit
       @preload_static_dirs               = preload_static_dirs
+      @rackup_path                       = rackup_path
     end
 
     def run
@@ -70,6 +72,19 @@ module Hyperion
         }
       end
 
+      # 2.16 — non-preload mode: master never loaded the Rack app, so we
+      # parse it here, post-fork. Native gems load against THIS process's
+      # address space, not the master's, which avoids the macOS
+      # Network.framework + fork getaddrinfo deadlock (where post-fork
+      # XPC peers are wedged forever in `nw_path_evaluator_evaluate`).
+      if @app.nil? && @rackup_path
+        require_relative 'cli'
+        @app = ::Hyperion::CLI.wrap_admin_middleware(
+          ::Hyperion::CLI.load_rack_app(@rackup_path),
+          @config
+        )
+      end
+
       server = Server.new(host: @host, port: @port, app: @app,
                           read_timeout: @read_timeout, tls: @tls,
                           thread_count: @thread_count,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperion-rb
 version: !ruby/object:Gem::Version
-  version: 2.15.0
+  version: 2.16.0
 platform: ruby
 authors:
 - Andrey Lobanov
@@ -154,6 +154,7 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- bin/check
 - bin/hyperion
 - ext/hyperion_h2_codec/Cargo.lock
 - ext/hyperion_h2_codec/Cargo.toml