RubyGems - hyperion-rb - Versions diffs - 2.14.0 → 2.16.0 - Mend

hyperion-rb 2.14.0 → 2.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 787ac0a93ce35270be1e12de302c80a696fcfd6a59eb6b02c376c11935a36e90
-  data.tar.gz: 41d30b0add0c321af76ee0b009a3b2a1925c9fa083bb188dd36a57aef8d7e329
+  metadata.gz: d599cad6595983a3aef241b7e5895b613c6275e44e8f05925f29c82fba99072c
+  data.tar.gz: c733f8b8e0f2d7de93a5bed82d4cea1331bbafafde347334cf08bbb00f8c1474
 SHA512:
-  metadata.gz: 9229473b20a042b2e91ed8e62c6193f8f9c1f7371117ba8fc3ed357489f63b1f90b48005d5fd16b47e5f0801507dfedbd514c4357e2f5f52db3496d658aff36c
-  data.tar.gz: 43079b86d3432d72c5ffbf1afe4dcc3c7c9a59916b78f6f9e81aec0ed1de1274ba00d8c20f7024ea28cfc890b9641fd87d2410ff063bbdacde491572e4e7cc6a
+  metadata.gz: 8311ce71399125875a3bab4499244801dfeac405512a6a3339762dc075e495a86e961f1135eb33ec8ac30c7d2e0bb46d0951a53ba144f42a1a40fce855889a74
+  data.tar.gz: c1eee7b3bdc928bdf328223abf54c80d5a1d9742a770968063659a98943a04e7c0f3b5530c4b5e5fef62847ccf29d6ddafb4cf8e7b4ee187968a82c27ad0f8b5

data/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,139 @@
 # 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
+**Why.** Three coordinated changes for one consolidated milestone.
+First, the README's headline numbers were a stitched collection
+across sprints 2.10–2.14 — the 134k claim from 2.12-D, the 4-hour
+soak from 2.14-C, the gRPC numbers from 2.14-D — captured on
+different days under different host conditions. Operators wanted
+one coherent snapshot they could trust. Second, the README sat at
+445 lines after the 2.14-E rework; with feature-deep-dive material
+inline it was still longer than a 30-second reader will tolerate.
+Third, GitHub Actions flaked on the `2.14-E` commit (1700426) with
+`Errno::EBADF: select_internal_with_gvl:epoll_wait` raised from
+inside `Async::Scheduler#close` on Ruby 3.4 + async 2.39 — the
+existing `child.wait rescue StandardError` only protected the
+inner block.
+**What 2.15-A ships.**
+1. **CI flake fix.** `lib/hyperion/server.rb#start_async_loop`
+   gains an outer `rescue Errno::EBADF, IOError` around the entire
+   `Async do ... end` block. Two regression specs added — one
+   deterministic (stubs `run_accept_fiber` to raise EBADF
+   synchronously), one integration-shape (10-cycle rapid boot/stop
+   on `thread_count: 0 + async_io: true`). 10/10 clean local runs.
+2. **Fresh bench.** Single coherent run on the bench host on a
+   single day captures all 9 headline rows. New driver script
+   `bench/run_all.sh` boots one server per row, runs `wrk` (or
+   `ghz` for gRPC), kills it, moves on — designed to be
+   re-runnable: any future maintainer can `./bench/run_all.sh` and
+   reproduce the published numbers within bench-host drift.
+   Numbers preserved in `docs/BENCH_HYPERION_2_14.md` (table +
+   reproduction commands) and `docs/BENCH_HYPERION_2_14_results.csv`
+   (raw CSV for archaeology).
+3. **README split.** `README.md` shrunk 445 → 163 lines. Feature
+   deep-dives moved to `docs/HTTP2_AND_TLS.md`,
+   `docs/HANDLE_STATIC_AND_HANDLE_BLOCK.md`,
+   `docs/CLUSTER_AND_SO_REUSEPORT.md`, `docs/ASYNC_IO.md`,
+   `docs/CONFIGURATION.md`, `docs/OPERATOR_GUIDANCE.md`,
+   `docs/LOGGING.md`, `docs/GRPC.md` (`docs/WEBSOCKETS.md` and
+   `docs/OBSERVABILITY.md` already existed). README structure now:
+   title + tagline → 30-second pitch → quick start → headline
+   bench table (one tight row per workload, fresh numbers) →
+   features (8 bullets, each linking into `docs/<feature>.md`) →
+   compatibility → documentation index → reproducing benchmarks →
+   release history → contributing → credits + license.
+**Headline bench numbers (median of 3 trials, captured 2026-05-02).**
+| # | Workload | r/s | p99 |
+|--:|---|---:|---:|
+| 1 | Hyperion `handle_static` + io_uring | **122,778** (peak 134,573) | 1.11 ms |
+| 2 | Hyperion `handle_static` + accept4 | 16,725 | 90 µs |
+| 3 | Hyperion `Server.handle` block | 8,956 | 190 µs |
+| 4 | Hyperion generic Rack hello | 4,231 | 2.33 ms |
+| 5 | Hyperion CPU JSON block | 5,456 | 327 µs |
+| 6 | Hyperion gRPC unary (h2/TLS) | 1,732 | 29.87 ms |
+| 7 | Reference Agoo hello | 18,326 | 10.54 ms |
+| 8 | Reference Falcon hello | 6,394 | 408.83 ms |
+| 9 | Reference Puma hello | 6,240 | 408.77 ms |
+The peak trial on row 1 (134,573 r/s) is consistent with the
+2.14-D 134,084 headline; median 122,778 is the conservative honest
+number, both cited in README.
+**Spec count.** 1145 → 1147 / 0 / 16 (+2 regression specs from
+the flake fix). All on macOS arm64 + Ruby 3.3.3.
 ## 2.14.0 — 2026-05-02
 ### 2.14-E — Complete README rework

data/README.md CHANGED Viewed

@@ -6,438 +6,156 @@ High-performance Ruby HTTP server. Rack 3 + HTTP/2 + WebSockets + gRPC on a sing
 [![Gem Version](https://img.shields.io/gem/v/hyperion-rb.svg)](https://rubygems.org/gems/hyperion-rb)
 [![License: MIT](https://img.shields.io/github/license/andrew-woblavobla/hyperion.svg)](https://github.com/andrew-woblavobla/hyperion/blob/master/LICENSE)
-Hyperion serves a hello-world Rack response at **134,084 r/s with a 1.14 ms p99**
-on a single worker (Linux 6.x, io_uring accept loop, `Server.handle_static`),
-**7×** Agoo's 19,024 r/s on the same hardware. Beyond the C-side fast path
-it's a complete Rack 3 server: HTTP/1.1 + HTTP/2 with ALPN, WebSockets
-(RFC 6455), gRPC unary + streaming on the Rack 3 trailers contract, native
-fiber concurrency for PG-bound apps, and pre-fork cluster mode with
-SO_REUSEPORT-balanced workers.
-```sh
-gem install hyperion-rb
-bundle exec hyperion config.ru                 # http://127.0.0.1:9292
-```
-## Headline benchmarks
-Linux 6.8 / 16-vCPU Ubuntu 24.04 / Ruby 3.3.3, single worker, `wrk -t4 -c100 -d20s`
-unless noted. Reproduction commands and the full 6-row 4-way matrix
-(Hyperion / Puma / Falcon / Agoo) live in
-[docs/BENCH_HYPERION_2_11.md](docs/BENCH_HYPERION_2_11.md).
-| Workload                                              | Hyperion r/s | Hyperion p99 | Reference            |
-|-------------------------------------------------------|-------------:|-------------:|----------------------|
-| Static hello, `handle_static` + io_uring (2.12-D)     | **134,084**  | 1.14 ms      | Agoo 2.15.14: 19,024 |
-| Static hello, `handle_static` + accept4 fallback      |       15,685 | 107 µs       | Agoo 2.15.14: 19,024 |
-| Dynamic block, `Server.handle { \|env\| ... }` (2.14-A) |        9,422 | 166 µs       | Agoo 2.15.14: 19,024 |
-| CPU JSON via block (`bench/work.ru`, 2.14-A)          |        5,897 | 256 µs       | Falcon: 4,226        |
-| Generic Rack hello (no `Server.handle`)               |        4,752 | 2.02 ms      | Agoo 2.15.14: 19,024 |
-| gRPC unary, h2/TLS, ghz `-c50` (2.14-D)               |        1,618 | 33.3 ms      | Falcon `async-grpc`: 1,512 (+7%) |
-The 134,084 r/s row is sustained over a 4-hour soak at **120,684 r/s**
-with RSS variance 2.71% and `wrk-truth` p99 1.14 ms (2.14-C). The
-io_uring loop is opt-in via `HYPERION_IO_URING_ACCEPT=1` until 2.15;
-the `accept4` row is the default on Linux.
+Hyperion serves a hello-world Rack response at **122,778 r/s with a 1.14 ms p99**
+(median of 3 trials, peak 134,573) on a single worker — Linux 6.x, io_uring
+accept loop, `Server.handle_static`, **6.7×** Agoo's 18,326 r/s on the same
+hardware. Beyond the C-side fast path it's a complete Rack 3 server: HTTP/1.1
++ HTTP/2 with ALPN, WebSockets (RFC 6455), gRPC unary + streaming on the Rack
+3 trailers contract, native fiber concurrency for PG-bound apps, and pre-fork
+cluster mode with SO_REUSEPORT-balanced workers.
 ## Quick start
 ```sh
-bundle exec hyperion config.ru                          # single process
+gem install hyperion-rb
+bundle exec hyperion config.ru                          # http://127.0.0.1:9292
 bundle exec hyperion -w 4 -t 10 config.ru               # 4 workers × 10 threads
-bundle exec hyperion -w 0 config.ru                     # one worker per CPU
 bundle exec hyperion --tls-cert cert.pem --tls-key key.pem -p 9443 config.ru
 ```
-`bundle exec rake spec` (and the default task) auto-invoke `compile`, so a
-fresh checkout just needs `bundle install && bundle exec rake` for a green run.
 Migrating from Puma? `hyperion -t N -w M` matching your current Puma
 `-t N:N -w M` is the recommended drop-in. See
 [docs/MIGRATING_FROM_PUMA.md](docs/MIGRATING_FROM_PUMA.md).
-## Features
-### HTTP/1.1 + HTTP/2 + TLS
-ALPN auto-negotiates `h2` or `http/1.1` per connection. HTTP/2 multiplexes
-streams onto fibers within a single connection — slow handlers don't
-head-of-line-block other streams. Cluster-mode TLS works (`-w N` +
-`--tls-cert` / `--tls-key`).
-Smuggling defenses for HTTP/1.1: `Content-Length` + `Transfer-Encoding`
-together → 400; non-chunked `Transfer-Encoding` → 501; CRLF in response
-header values → `ArgumentError` (response-splitting guard).
-### WebSockets (2.1.0+)
-RFC 6455 over Rack 3 full hijack, native frame codec, per-connection
-wrapper with auto-pong, close handshake, UTF-8 validation, and per-message
-size cap. **ActionCable + faye-websocket on a single binary** — one
-`hyperion -w 4 -t 10 config.ru` serves HTTP, HTTP/2, TLS, and `/cable`
-from the same listener. Conformance: 463/463 autobahn-testsuite cases
-pass. See [docs/WEBSOCKETS.md](docs/WEBSOCKETS.md).
-### gRPC (2.12-F+)
-Hyperion's HTTP/2 path supports gRPC unary, server-streaming,
-client-streaming, and bidirectional RPCs via the Rack 3 trailers contract:
-any response body that defines `#trailers` gets a final HEADERS frame
-(with `END_STREAM=1`) carrying the trailer map after the DATA frames.
-Plain HTTP/2 traffic without the gRPC content-type keeps the unary
-buffered semantics — no behaviour change for non-gRPC clients.
-A minimal unary handler:
-```ruby
-class GrpcBody
-  def initialize(reply); @reply = reply; end
-  def each; yield @reply; end
-  def trailers; { 'grpc-status' => '0', 'grpc-message' => 'OK' }; end
-  def close; end
-end
-run ->(env) {
-  request = env['rack.input'].read
-  reply   = handle(request)
-  [200, { 'content-type' => 'application/grpc' }, GrpcBody.new(reply)]
-}
-```
-Server-streaming yields one DATA frame per `each`; client-streaming
-reads incoming frames off `env['rack.input']` (a streaming IO that
-blocks until the next DATA frame lands); bidirectional interleaves
-both. Reproducible bench at `bench/grpc_stream.{proto,ru}` +
-`bench/grpc_stream_bench.sh` (ghz). Numbers in
-[docs/BENCH_HYPERION_2_11.md](docs/BENCH_HYPERION_2_11.md#grpc-ghz-bench--hyperion-vs-falcon-async-grpc-214-d).
-### `Server.handle` direct routes
-Bypass the Rack adapter for hot paths:
-```ruby
-Hyperion::Server.handle_static '/health', body: 'ok'
-Hyperion::Server.handle(:GET, '/v1/ping') { |env| [200, {}, ['pong']] }
-```
-`handle_static` bakes the response at boot and serves from the C accept
-loop (134k r/s with io_uring, 16k r/s on accept4). The dynamic block
-form (2.14-A) runs `app.call(env)` on the C accept loop too — accept +
-recv + parse + write release the GVL while the block holds it, so
-multi-threaded workers actually parallelise.
-### Pre-fork cluster
-Per-OS worker model: `SO_REUSEPORT` on Linux (kernel-balanced accept,
-1.004–1.011 max/min ratio across workers under steady load — 2.12-E
-audit), master-bind + worker-fd-share on macOS/BSD where Darwin's
-`SO_REUSEPORT` doesn't load-balance. Lifecycle hooks (`before_fork`,
-`on_worker_boot`, `on_worker_shutdown`) for AR / Redis / pool init.
-### Async I/O (PG-bound apps)
-`--async-io` runs plain HTTP/1.1 connections under `Async::Scheduler`,
-turning one OS thread into thousands of in-flight handler invocations.
-Paired with [hyperion-async-pg](https://github.com/andrew-woblavobla/hyperion-async-pg)
-on a `pg_sleep(50ms)` workload, single-worker `pool=200` hits **2,381 r/s**
-vs Puma `-t 5` at 56 r/s (architectural ceiling: pool size, not thread
-count). Three things must all be true: `--async-io`, `hyperion-async-pg`
-loaded, and a fiber-aware pool (`Hyperion::AsyncPg::FiberPool`,
-`async-pool`, or `Async::Semaphore` — **not** the `connection_pool` gem,
-whose `Mutex` blocks the OS thread). Skip any one and you get parity
-with Puma.
-### Observability
-`/-/metrics` Prometheus endpoint (admin-token guarded), per-route
-latency histograms, per-conn fairness rejections, WebSocket
-permessage-deflate ratio, kTLS active connections, ThreadPool queue
-depth, dispatch-mode counters (Rack / `handle_static` / dynamic block /
-h2 / async-io). Pre-built Grafana dashboard at
-[docs/grafana/hyperion-2.4-dashboard.json](docs/grafana/hyperion-2.4-dashboard.json).
-Full reference: [docs/OBSERVABILITY.md](docs/OBSERVABILITY.md).
-Default-ON structured access logs (one JSON or text line per request)
-with hot-path optimisations: per-thread cached iso8601 timestamp,
-hand-rolled line builder, lock-free per-thread 4 KiB write buffer.
-12-factor logger split: `info`/`debug` → stdout, `warn`/`error`/`fatal`
-→ stderr.
-### Optional io_uring accept loop
-Linux 5.x+, opt-in via `HYPERION_IO_URING_ACCEPT=1`. Multishot accept
-+ per-conn RECV/WRITE/CLOSE state machine on top of liburing. One
-`io_uring_enter` per N requests instead of N×3 syscalls. Compiles out
-cleanly without liburing — the `accept4` path stays the fallback.
-macOS keeps using `accept4`. Default-flip moves to 2.15 with a fresh
-24h soak.
-## Configuration
-Three layers, in precedence order: explicit CLI flag > environment
-variable > `config/hyperion.rb` > built-in default.
-### Most-used CLI flags
-| Flag | Default | Notes |
-|---|---|---|
-| `-b, --bind HOST` | `127.0.0.1` | |
-| `-p, --port PORT` | `9292` | |
-| `-w, --workers N` | `1` | `0` → `Etc.nprocessors` |
-| `-t, --threads N` | `5` | OS-thread Rack handler pool per worker. `0` → run inline (debugging). |
-| `-C, --config PATH` | `config/hyperion.rb` if present | Ruby DSL file. |
-| `--tls-cert PATH` / `--tls-key PATH` | nil | PEM cert + key for HTTPS. |
-| `--[no-]async-io` | off | Run plain HTTP/1.1 under `Async::Scheduler`. Required for `hyperion-async-pg` on plain HTTP. |
-| `--preload-static DIR` | nil | Preload static assets from DIR at boot (repeatable, immutable). Rails apps auto-detect from `Rails.configuration.assets.paths`. |
-| `--admin-token-file PATH` | unset | Auth file for `/-/quit` and `/-/metrics`. Refuses world-readable files. |
-| `--worker-max-rss-mb MB` | unset | Master gracefully recycles a worker exceeding MB RSS. |
-| `--max-pending COUNT` | unbounded | Per-worker accept-queue cap before HTTP 503 + `Retry-After: 1`. |
-| `--idle-keepalive SECONDS` | `5` | Keep-alive idle timeout. |
-| `--graceful-timeout SECONDS` | `30` | Shutdown deadline before SIGKILL. |
-`bin/hyperion --help` prints the full set, including `--max-body-bytes`,
-`--max-header-bytes`, `--max-request-read-seconds` (slowloris defence),
-`--h2-max-total-streams`, `--max-in-flight-per-conn`,
-`--tls-handshake-rate-limit`, and the `--[no-]yjit` /
-`--[no-]log-requests` toggles.
-### Environment variables
-`HYPERION_LOG_LEVEL`, `HYPERION_LOG_FORMAT`, `HYPERION_LOG_REQUESTS`
-(`0|1|true|false|yes|no|on|off`), `HYPERION_ENV`,
-`HYPERION_WORKER_MODEL` (`share|reuseport`), `HYPERION_IO_URING_ACCEPT`
-(`0|1`), `HYPERION_H2_DISPATCH_POOL`, `HYPERION_H2_NATIVE_HPACK`
-(`v2|ruby|off`), `HYPERION_H2_TIMING`.
-### Config file
-`config/hyperion.rb` — same shape as Puma's `puma.rb`. Auto-loaded if
-present. Strict DSL: unknown methods raise `NoMethodError` at boot.
-```ruby
-# config/hyperion.rb
-bind '0.0.0.0'
-port 9292
-workers      4
-thread_count 10
-# tls_cert_path 'config/cert.pem'
-# tls_key_path  'config/key.pem'
-read_timeout      30
-idle_keepalive     5
-graceful_timeout  30
-log_level    :info
-log_format   :auto
-log_requests true
-async_io nil    # nil = auto (1.4.0+), true = inline-on-fiber everywhere, false = pool everywhere
-before_fork do
-  ActiveRecord::Base.connection_handler.clear_all_connections! if defined?(ActiveRecord)
-end
-on_worker_boot do |worker_index|
-  ActiveRecord::Base.establish_connection if defined?(ActiveRecord)
-end
-```
-A documented sample lives at
-[`config/hyperion.example.rb`](config/hyperion.example.rb).
-## Operator guidance
-Distilled from [docs/BENCH_2026_04_27.md](docs/BENCH_2026_04_27.md)
-(Rails 8.1 real-app sweep). Headline finding: **the simplest drop-in
-is the right answer.**
-### Migrating from Puma
-`hyperion -t N -w M` matching your current Puma `-t N:N -w M`. No other
-flags. Versus Puma at the same `-t/-w` shape on real Rails endpoints:
-**+9% rps on lightweight endpoints, 28× lower p99 on health-style
-endpoints, 3.8× lower p99 on PG-touching endpoints.** Same RSS, same
-operator surface — keep all your existing config, monitoring, deploy
-scripts.
-### Knobs that help on synthetic benches but **not** on real Rails
-| Knob | Synthetic | Real Rails | Recommendation |
-|---|---|---|---|
-| `-t 30` | +5–10% on hello-world | **Hurts** p99 vs `-t 10` (3.51 s vs 148 ms on `/up`) — GVL + middleware Mutex contention | Stay at `-t 10`. |
-| `--yjit` | +5–10% on CPU-bound | Wash on dev-mode Rails | Skip until you bench production-mode. |
-| `RAILS_POOL > 25` | n/a | No improvement at 50 or 100 | Keep your existing AR pool. |
-| `--async-io` | 33–42× rps on PG-bound | **Worse** than drop-in (4.14 s p99 on `/up`) until your full I/O stack is fiber-cooperative | Don't enable until `redis-rb` → `async-redis`. |
-### When `-w N` helps
-| Workload | Recommended | Why |
-|---|---|---|
-| Pure I/O-bound (PG / Redis / external HTTP) | `-w 1` + larger pool | `-w 1 pool=200` = 87 MB / 2,180 r/s vs `-w 4 pool=64` = 224 MB / 1,680 r/s. **2.6× memory, 0.77× rps** if you pick multi-worker on wait-bound. |
-| Pure CPU-bound | `-w N` matching CPU count | Bench: `-w 16 -t 5` hits 98,818 r/s on a 16-vCPU box. |
-| Mixed (Rails-shaped, ~5 ms CPU + 50 ms wait) | `-w N/2` (half cores) + medium pool | `-w 4 -t 5 pool=128` = 1,740 r/s on `pg_mixed.ru`, no cold-start spike. |
-### Read p99 not mean
-| Workload | Hyperion rps / p99 | Closest competitor | rps ratio | p99 ratio |
-|---|---|---|---:|---:|
-| Hello `-w 4` | 21,215 / 1.87 ms | Falcon 24,061 / 9.78 ms | 0.88× | **5.2× lower** |
-| CPU JSON `-w 4` | 15,582 / 2.47 ms | Falcon 18,643 / 13.51 ms | 0.84× | **5.5× lower** |
-| Static 1 MiB | 1,919 / 4.22 ms | Puma 2,074 / 55 ms | 0.93× | **13× lower** |
-| PG-wait `-w 1` pool=200 | 2,180 / 668 ms | Puma 530 + 200 timeouts | **4.1×** | qualitative crush |
-Throughput peaks are easy to fake under controlled conditions; tail
-latency reflects what your slowest user actually experiences when the
-load balancer fans them onto a busy worker.
-## Logging
-Default behaviour:
-- `info`/`debug` → stdout, `warn`/`error`/`fatal` → stderr (12-factor).
-- One structured access-log line per response, `info` level. Disable
-  with `--no-log-requests` or `HYPERION_LOG_REQUESTS=0`.
-- Format auto-selects: `RAILS_ENV=production`/`staging` → JSON; TTY →
-  coloured text; piped output without env hint → JSON.
-Sample text (TTY default):
-```
-2026-04-26T18:40:04.112Z INFO  [hyperion] message=request method=GET path=/api/v1/health status=200 duration_ms=46.63 remote_addr=127.0.0.1 http_version=HTTP/1.1
-```
-Sample JSON (production / piped):
-```json
-{"ts":"2026-04-26T18:38:49.405Z","level":"info","source":"hyperion","message":"request","method":"GET","path":"/api/v1/health","status":200,"duration_ms":46.63,"remote_addr":"127.0.0.1","http_version":"HTTP/1.1"}
-```
-## Metrics
+## Headline benchmarks
-`Hyperion.stats` returns a snapshot Hash with lock-free per-thread
-counters (`connections_accepted`, `connections_active`, `requests_total`,
-`requests_in_flight`, `responses_<code>`, `parse_errors`, `app_errors`,
-`read_timeouts`, `requests_threadpool_dispatched`,
-`requests_async_dispatched`, `c_loop_requests_total`).
+Linux 6.8 / 16-vCPU Ubuntu 24.04 / Ruby 3.3.3, single worker, `wrk -t4 -c100 -d20s`
+unless noted. Three trials per row, median reported. Captured 2026-05-02 on
+the 2.14.0 release commit. Full reproduction in
+[docs/BENCH_HYPERION_2_14.md](docs/BENCH_HYPERION_2_14.md); single-command
+re-bench via [`bench/run_all.sh`](bench/run_all.sh).
-When `admin_token` is set, `/-/metrics` emits Prometheus text-format
-v0.0.4. Auth is via the `X-Hyperion-Admin-Token` header (same token
-guards `POST /-/quit`):
+| Workload                                              | Hyperion r/s | Hyperion p99 | Reference            |
+|-------------------------------------------------------|-------------:|-------------:|----------------------|
+| Static hello, `handle_static` + io_uring              | **122,778**  | 1.11 ms      | Agoo: 18,326         |
+| Static hello, `handle_static` + accept4 fallback      |       16,725 | 90 µs        | Agoo: 18,326         |
+| Dynamic block, `Server.handle { \|env\| ... }`        |        8,956 | 190 µs       | Agoo: 18,326         |
+| CPU JSON via block (`bench/work.ru`)                  |        5,456 | 327 µs       | Falcon: 6,394        |
+| Generic Rack hello (no `Server.handle`)               |        4,231 | 2.33 ms      | Agoo: 18,326         |
+| gRPC unary, h2/TLS, `ghz -c50`                        |        1,732 | 29.87 ms     | (Falcon `async-grpc` historical: 1,512) |
+Peak trial on row 1: 134,573 r/s. The io_uring loop is opt-in via
+`HYPERION_IO_URING_ACCEPT=1` until 2.15; the `accept4` row is the default on
+Linux. Falcon and Puma both tail-latency at **>400 ms p99** on the generic
+Rack hello row Hyperion serves at 2.33 ms; the closest-competitor's mean is
+Hyperion's p99 — read the tail, not the throughput peak.
-```sh
-$ curl -s -H 'X-Hyperion-Admin-Token: secret' http://127.0.0.1:9292/-/metrics
-# HELP hyperion_requests_total Total HTTP requests handled
-# TYPE hyperion_requests_total counter
-hyperion_requests_total 8910
-hyperion_responses_status_total{status="200"} 8521
-hyperion_responses_status_total{status="404"} 12
-```
+## Features
-Any counter not in the known set (added via
-`Hyperion.metrics.increment(:custom_thing)`) is auto-exported as
-`hyperion_custom_thing` with a generic HELP line. Network-isolate the
-admin endpoints if the listener is internet-facing — see
-[docs/REVERSE_PROXY.md](docs/REVERSE_PROXY.md) for the nginx
-`location /-/ { return 404; }` recipe.
+- **HTTP/1.1 + HTTP/2 + TLS** with ALPN auto-negotiation. Multiplexed h2
+  streams on fibers; smuggling defences inline. See
+  [docs/HTTP2_AND_TLS.md](docs/HTTP2_AND_TLS.md).
+- **WebSockets** (RFC 6455) over Rack 3 full hijack. ActionCable +
+  faye-websocket on the same listener. 463/463 autobahn cases pass. See
+  [docs/WEBSOCKETS.md](docs/WEBSOCKETS.md).
+- **gRPC** unary, server-stream, client-stream, bidirectional via
+  Rack 3 trailers. See [docs/GRPC.md](docs/GRPC.md).
+- **`Server.handle_static`** + **`Server.handle { |env| … }`** —
+  C-loop direct routes that bypass the Rack adapter for hot paths.
+  See [docs/HANDLE_STATIC_AND_HANDLE_BLOCK.md](docs/HANDLE_STATIC_AND_HANDLE_BLOCK.md).
+- **Pre-fork cluster mode** — `SO_REUSEPORT` on Linux, master-bind on
+  macOS / BSD. 1.004–1.011 max/min worker fairness ratio under steady
+  load. See [docs/CLUSTER_AND_SO_REUSEPORT.md](docs/CLUSTER_AND_SO_REUSEPORT.md).
+- **Async I/O** for PG-bound apps via `--async-io` +
+  [hyperion-async-pg](https://github.com/andrew-woblavobla/hyperion-async-pg).
+  Single worker `pool=200` hits 2,381 r/s on `pg_sleep(50ms)` vs Puma's 56
+  r/s. See [docs/ASYNC_IO.md](docs/ASYNC_IO.md).
+- **Observability** — `/-/metrics` Prometheus endpoint, per-route
+  histograms, dispatch-mode counters, kTLS gauge. Pre-built Grafana
+  dashboard. See [docs/OBSERVABILITY.md](docs/OBSERVABILITY.md).
+- **Default-on structured access logs** — JSON in production, coloured
+  text on TTY. Per-thread cached timestamps; ≈ 0.1 µs per logged
+  request. See [docs/LOGGING.md](docs/LOGGING.md).
+- **io_uring accept loop** (Linux 5.x+, opt-in) — multishot accept +
+  per-conn state machine. Compiles out cleanly without liburing.
+  Default-flip moves to 2.15 with a fresh 24h soak.
 ## Compatibility
 | Component | Version |
 |---|---|
-| Ruby | 3.3+ (transitive `protocol-http2 ~> 0.26` floor) |
+| Ruby | 3.3+ |
 | Rack | 3.x |
 | Rails | verified up to 8.1 |
 | Linux kernel | 5.x+ for io_uring opt-in; 4.x+ otherwise |
-| macOS | works (TLS, h2, WebSockets, `accept4` fallback path) |
+| macOS | works (TLS, h2, WebSockets, `accept4` fallback) |
-Per-Rack-3-spec: auto-sets `SERVER_SOFTWARE`, `rack.version`,
-`REMOTE_ADDR`, IPv6-safe `Host` parsing, CRLF guard. The
-`Hyperion::FiberLocal.install!` opt-in shim handles the residual
-`Thread.current.thread_variable_*` footgun in older Rails idioms;
-modern Rails 7.1+ already uses Fiber storage natively.
+## Documentation
-## Reproducing benchmarks
+- [BENCH_HYPERION_2_14.md](docs/BENCH_HYPERION_2_14.md) — fresh 2.14.0
+  bench (this README's headline numbers, with reproduction commands).
+- [BENCH_HYPERION_2_11.md](docs/BENCH_HYPERION_2_11.md) — 4-way
+  matrix (Hyperion / Puma / Falcon / Agoo).
+- [BENCH_2026_04_27.md](docs/BENCH_2026_04_27.md) — real Rails 8.1
+  app sweep (Exodus platform).
+- [CONFIGURATION.md](docs/CONFIGURATION.md) — CLI flags, env vars,
+  `config/hyperion.rb` DSL.
+- [OPERATOR_GUIDANCE.md](docs/OPERATOR_GUIDANCE.md) — what `-w N` /
+  `-t N` / `--async-io` actually do on Rails-shaped traffic.
+- [HTTP2_AND_TLS.md](docs/HTTP2_AND_TLS.md) — h2 + TLS surface.
+- [WEBSOCKETS.md](docs/WEBSOCKETS.md) — RFC 6455 surface.
+- [GRPC.md](docs/GRPC.md) — Rack 3 trailers + streaming RPCs.
+- [HANDLE_STATIC_AND_HANDLE_BLOCK.md](docs/HANDLE_STATIC_AND_HANDLE_BLOCK.md)
+  — direct-route forms.
+- [CLUSTER_AND_SO_REUSEPORT.md](docs/CLUSTER_AND_SO_REUSEPORT.md) —
+  cluster mode and per-OS worker model.
+- [ASYNC_IO.md](docs/ASYNC_IO.md) — `--async-io` for PG-bound apps.
+- [OBSERVABILITY.md](docs/OBSERVABILITY.md) — metrics + Grafana.
+- [LOGGING.md](docs/LOGGING.md) — access log surface.
+- [MIGRATING_FROM_PUMA.md](docs/MIGRATING_FROM_PUMA.md) — drop-in guide.
+- [REVERSE_PROXY.md](docs/REVERSE_PROXY.md) — nginx fronting.
-Every number in this README is reproducible. Per-row commands:
+## Reproducing benchmarks
 ```sh
-# Setup (once)
-bundle install
-bundle exec rake compile
-# Hello via Server.handle_static + io_uring (134k r/s row)
-HYPERION_IO_URING_ACCEPT=1 bundle exec bin/hyperion -w 1 -t 5 -p 9292 bench/hello_static.ru &
-wrk -t4 -c100 -d20s --latency http://127.0.0.1:9292/
-# Dynamic block via Server.handle (9.4k r/s row)
-bundle exec bin/hyperion -w 1 -t 5 -p 9292 bench/hello_handle_block.ru &
-wrk -t4 -c100 -d20s --latency http://127.0.0.1:9292/
-# Generic Rack hello (4.7k r/s row)
-bundle exec bin/hyperion -w 1 -t 5 -p 9292 bench/hello.ru &
-wrk -t4 -c100 -d20s --latency http://127.0.0.1:9292/
-# CPU JSON via block form (5.9k r/s row)
-bundle exec bin/hyperion -w 1 -t 5 -p 9292 bench/work.ru &
-wrk -t4 -c200 -d15s --latency http://127.0.0.1:9292/
-# 4-way comparator (Hyperion vs Puma vs Falcon vs Agoo)
-bash bench/4way_compare.sh
-# gRPC unary + streaming (Hyperion side)
-GHZ=/tmp/ghz TRIALS=3 DURATION=15s WARMUP_DURATION=3s bash bench/grpc_stream_bench.sh
-# Idle keep-alive RSS sweep (10k conns × 30s hold)
-bash bench/keepalive_memory.sh
+bundle install && bundle exec rake compile
+./bench/run_all.sh                  # full table
+./bench/run_all.sh --row 1          # single row
+./bench/run_all.sh --skip-grpc      # rows 1-5 + 7-9
 ```
-PG benches (`pg_concurrent.ru`, `pg_mixed.ru`) live in the
-[hyperion-async-pg](https://github.com/andrew-woblavobla/hyperion-async-pg)
-companion repo — they require a running Postgres and the companion
-gem.
+The `bench/run_all.sh` driver boots one server per row, runs `wrk` (or
+`ghz` for gRPC), kills it, moves on — no concurrent runs (cross-talk
+inflates noise on shared hosts). Output: CSV + markdown table at
+`$OUT_CSV` / `$OUT_MD` (default `/tmp/hyperion-2.15-bench.{csv,md}`).
-When numbers from your host don't match the published numbers, the
-most likely explanations (in order): (1) bench-host noise — single-VM
-benches drift 10–30% over days; (2) Puma version mismatch (sweep used
-Puma 8.0.1; the in-repo Gemfile pins `~> 6.4`); (3) different kernel
-or Ruby; (4) different `-t` / `-c` (apples-to-apples requires
-identical worker count, thread count, wrk concurrency, payload, and
-TLS cipher).
+Per-row commands and the host snapshot live in
+[docs/BENCH_HYPERION_2_14.md](docs/BENCH_HYPERION_2_14.md). When
+your numbers don't match: bench-host noise drifts ±10–30% over days,
+Puma version mismatch (sweep used 8.0.x; in-repo Gemfile pins
+`~> 6.4`), and different `-t` / `-c` are the usual culprits.
 ## Release history
-See [CHANGELOG.md](CHANGELOG.md). Recent: 2.14.0 (gRPC streaming ghz
-numbers; dynamic-block C dispatch — `Server.handle { |env| ... }` lifts
-hello to 9,422 r/s and CPU JSON to 5,897 r/s; `Server#stop` accept-wake
-on Linux; io_uring 4h soak), 2.13.0 (response head builder C-rewrite;
-gRPC streaming RPCs; soak harness), 2.12.0 (C connection lifecycle;
-io_uring loop hits 134k r/s; gRPC unary trailers; SO_REUSEPORT
-audit), 2.11.0 (HPACK CGlue default; h2 dispatch-pool warmup), 2.10.x
-(`PageCache`, `Server.handle` direct routes, TCP_NODELAY at accept).
+See [CHANGELOG.md](CHANGELOG.md). Recent: 2.14.0 (gRPC streaming
+ghz; dynamic-block C dispatch; `Server#stop` accept-wake on Linux;
+io_uring 4h soak), 2.13.0 (response head builder C-rewrite; gRPC
+streaming RPCs), 2.12.0 (C connection lifecycle; io_uring loop;
+gRPC unary trailers), 2.11.0 (HPACK CGlue default; h2 dispatch-pool
+warmup), 2.10.x (PageCache, `Server.handle` direct routes,
+TCP_NODELAY at accept).
-## Links
+## Contributing
-- [CHANGELOG.md](CHANGELOG.md) — per-stream releases.
-- [docs/BENCH_HYPERION_2_11.md](docs/BENCH_HYPERION_2_11.md) — current
-  4-way matrix + 2.14-D gRPC numbers.
-- [docs/BENCH_HYPERION_2_0.md](docs/BENCH_HYPERION_2_0.md) — historical
-  2.10-B baseline (preserved for archaeology).
-- [docs/BENCH_2026_04_27.md](docs/BENCH_2026_04_27.md) — real Rails 8.1
-  app sweep (Exodus platform).
-- [docs/OBSERVABILITY.md](docs/OBSERVABILITY.md) — metrics + Grafana.
-- [docs/WEBSOCKETS.md](docs/WEBSOCKETS.md) — RFC 6455 surface.
-- [docs/MIGRATING_FROM_PUMA.md](docs/MIGRATING_FROM_PUMA.md) — drop-in
-  guide.
-- [docs/REVERSE_PROXY.md](docs/REVERSE_PROXY.md) — nginx fronting.
+See [CONTRIBUTING.md](CONTRIBUTING.md). `bundle install && bundle exec rake`
+gives you a green test suite (1147 examples / 0 failures / 16 pending
+on macOS arm64 + Ruby 3.3.3 as of 2.15-A).
 ## Credits
 - Vendored [llhttp](https://github.com/nodejs/llhttp) (Node.js's HTTP
   parser, MIT) under `ext/hyperion_http/llhttp/`.
-- HTTP/2 framing and HPACK via
-  [`protocol-http2`](https://github.com/socketry/protocol-http2).
+- HTTP/2 framing and HPACK via [`protocol-http2`](https://github.com/socketry/protocol-http2).
 - Fiber scheduler via [`async`](https://github.com/socketry/async).
 ## License

data/bin/check ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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/server.rb CHANGED Viewed

@@ -821,6 +821,33 @@ module Hyperion
     # workers (Linux) the kernel hashes connections fairly across siblings;
     # on `:share` (Darwin) the knob is silently honoured but shows no
     # scaling benefit — operators already know Darwin is special.
+    # 2.15-A — outer rescue for `Errno::EBADF` / `IOError`.
+    #
+    # Background: prior to 2.15-A this was just the inner
+    # `task.children.each { child.wait rescue StandardError; nil }`
+    # pattern. That handles raises from the accept fiber bodies, but
+    # NOT from `Async::Scheduler#close`, which runs implicitly when the
+    # `Async do ... end` block exits and which itself parks in
+    # `epoll_wait` / `kevent`. If `stop` closed the listener fd while
+    # the scheduler still had it registered, the scheduler-close
+    # surfaces `Errno::EBADF: Bad file descriptor —
+    # select_internal_with_gvl:epoll_wait` and re-raises it past the
+    # inner rescue (the inner rescue is only on `child.wait`).
+    #
+    # Symptom in CI: `async_io: true` boot/stop integration specs flake
+    # on Ruby 3.4 + async 2.39 with EBADF bubbling out of the worker
+    # thread. The race window is widest with `thread_count: 0` because
+    # the entire dispatch path runs on the same fiber as the accept
+    # loop, so there's no thread-pool synchronization barrier between
+    # `stop` and scheduler close.
+    #
+    # Fix: catch `Errno::EBADF`/`IOError` at the outer `Async do` scope.
+    # These are exclusively shutdown signals (the listener fd only goes
+    # bad when `close_listeners` has run); swallowing them here is
+    # equivalent to the C-loop path, which already swallows them inside
+    # `accept_or_nil`. The change is intentionally narrow — other
+    # `StandardError` from inside the loop bodies still propagates out
+    # so genuine accept-loop bugs are not masked.
     def start_async_loop
       Async do |task|
         n = @accept_fibers_per_worker
@@ -834,6 +861,11 @@ module Hyperion
           nil
         end
       end
+    rescue Errno::EBADF, IOError
+      # Listener fd already closed by `stop` — scheduler close-time
+      # epoll_wait / kevent saw the bad fd. Benign at this point;
+      # the server is shutting down by design.
+      nil
     end
     # Single accept fiber's run loop. Called N times (default 1) from

data/lib/hyperion/version.rb CHANGED Viewed

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

data/lib/hyperion/worker.rb CHANGED Viewed

@@ -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 CHANGED Viewed

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