hyperion-rb 2.15.0 → 2.16.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89ad0e591a8a44e23597ab8aa800ea65437c3e90d77903f7b3433c36368c87de
-  data.tar.gz: b8a17ba534c62e8aa9d1b91f23e7baebf5a49d3074617fbcf73a328363e76aa4
+  metadata.gz: 8ee8566aa14b81d85a43cb2bdfad406f4f026836d230efcee7d4c386f98a1af8
+  data.tar.gz: 0c982adc33ba39f5e3b50179edaea24e9c82de40e6b11220f024a9d663e2e434
 SHA512:
-  metadata.gz: 7e0059eba0f4d925bab72a1a7c4371e4e74c7336e62ac26135d3450480bfe6979ade740f0b7c236bfac67592eec40662ba0fca72c761cc2e208b8063dc6c04bb
-  data.tar.gz: 5e38e2d43c8c8dea1f1dfce54639c7ea11377905a7193b3e87199c78f7aacccbed30218ec49ba1e1f39317541f361501671ded4b0d0875503806cc3680a9a856
+  metadata.gz: 772d23dde2abe5b97ec1e943f46e7744fd932d57e8e8488a9374fdcf42dec6c2479d315cdd7dc6b389d5f68c83fe8973acad0940108092009c81d8c7e8dbbd4f
+  data.tar.gz: abed58d154aea89829e1b9ef74c31027fa15d451ea51ed13c6736ae452e1fd06bf030dcfc5bc9bfa83dcb413b87e365e6c600bf62ac875f3fec488b54b58e39a

data/CHANGELOG.md

@@ -1,5 +1,113 @@
 # Changelog
 
+## 2.16.1 — 2026-05-04
+
+### 2.16.1-A — macOS Obj-C fork-safety guard
+
+**Why.** Operators landing on 2.16.0's `preload false` mode on macOS
+were still hitting a second fork+macOS crash, distinct from the
+Network.framework deadlock that 2.16.0 addressed. The Obj-C runtime's
+post-fork sanity check trips when a worker touches a Foundation
+class that was mid-initialization in the master at fork time:
+
+```
+objc[…]: +[NSCharacterSet initialize] may have been in progress in
+another thread when fork() was called. We cannot safely call it or
+ignore it in the fork() child process. Crashing instead.
+```
+
+`NSCharacterSet` (and friends) load transitively through OpenSSL,
+the system resolver, and several other native gems. The result with
+many workers (`WEB_CONCURRENCY=0` on a multi-core box): every fresh
+worker crashes on first Foundation touch, master respawns, ad
+infinitum until graceful_timeout fires.
+
+The escape hatch on macOS is the documented env var
+`OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES`, but it MUST be in the
+process environment before any Foundation class loads — setting it
+from `config/hyperion.rb` (parsed after gems load) is too late.
+
+**What 2.16.1-A ships.** `bin/hyperion` and `lib/hyperion.rb` set
+`ENV['OBJC_DISABLE_INITIALIZE_FORK_SAFETY'] ||= 'YES'` on `darwin`
+unconditionally — before any `require` brings in Foundation-touching
+code. `||=` honours operators who've set the var explicitly. No-op
+on Linux/BSD; affects only macOS.
+
+This is a defense-in-depth change, complementary to `preload false`:
+`preload false` keeps Network.framework's resolver state out of the
+master; this guard keeps Obj-C runtime fork-checks from crashing
+the workers when something else (OpenSSL etc.) still touches
+Foundation. Together they make the macOS dev experience match Linux.
+
+**Verification.**
+
+- `bin/check` green.
+- Hand-reproduced the `NSCharacterSet` worker-crash loop on macOS;
+  no longer reproduces in 2.16.1.
+
+## 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/bin/hyperion

@@ -1,6 +1,15 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+# 2.16.1 — macOS fork-safety. The Obj-C runtime's post-fork sanity check
+# crashes any worker that touches a Foundation class which was mid-init
+# in the master at fork time (e.g. NSCharacterSet, common as a side-effect
+# of OpenSSL / system-resolver loads). The escape hatch is the env var
+# below; it must be set before Foundation classes load. Set on darwin
+# unconditionally — no-op elsewhere. `||=` so an operator who has set
+# it explicitly (e.g. to `NO`) is honoured.
+ENV['OBJC_DISABLE_INITIALIZE_FORK_SAFETY'] ||= 'YES' if RUBY_PLATFORM.include?('darwin')
+
 $LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
 require 'hyperion/cli'
 Hyperion::CLI.run(ARGV)

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.1'
 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,

data/lib/hyperion.rb

@@ -1,5 +1,15 @@
 # frozen_string_literal: true
 
+# 2.16.1 — macOS fork-safety. Mirrors the guard at the top of
+# `bin/hyperion` so programmatic `require 'hyperion'` (specs,
+# embedded uses) gets the same workaround. The Obj-C runtime's
+# post-fork check crashes workers that touch a Foundation class
+# which was mid-init in the master at fork time (NSCharacterSet
+# is a frequent victim — it loads transitively via OpenSSL / system
+# resolver paths). `||=` so an operator who has set the var
+# explicitly is honoured. No-op on non-darwin platforms.
+ENV['OBJC_DISABLE_INITIALIZE_FORK_SAFETY'] ||= 'YES' if RUBY_PLATFORM.include?('darwin')
+
 require_relative 'hyperion/version'
 require_relative 'hyperion/logger'
 require_relative 'hyperion/metrics'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperion-rb
 version: !ruby/object:Gem::Version
-  version: 2.15.0
+  version: 2.16.1
 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