hyperion-rb 1.6.0 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eecb708980287e22968f1405778e91632ecd26eaae33845891ee00e94adf6839
-  data.tar.gz: e433cd1bff6039cd8c30bbc9fdce6cd4176ca1e03d33362f9e67ceddd7d89880
+  metadata.gz: 388377a54507d370411ae4b229ff575e191742ba6e3dc044c9c8990552bff5ff
+  data.tar.gz: 8cc9cd083c9450948ba3a710cb5514f16bc31b8a421ebd405c4064129b0b031c
 SHA512:
-  metadata.gz: c02db1008beea0246601193a4ca18e8ac931f9a4952a2571a88ecc24028a838707a55e0ecf2159ba53f76b4a3c32c94c635afeb957304ae16ca2e0c2951ef7a3
-  data.tar.gz: 8c3bb4674315a4c41cd4bf38296ab2c991b113f3bcb0ced20ae3a143572f289c3d9a00ce258ba317045a5427b4b7a7986bf6de9f499c84d0ec61b505d8563518
+  metadata.gz: 389098362215d01ce8fa08add90d29871390e0c9c5e38d384caa50ee2605210005c252ecbaea191f379d59580e2c4d4573b94ef8c9308259e1959abee81e4397
+  data.tar.gz: f3d2664e553a2b3c24f8518ed9b65e73a49bbefd0dee03f0c602d7867fdd37ed0a8bf7030abcee68b9020c54ee80fe3cc039c93e4e004fbd372cea02313592bd

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [1.6.1] - 2026-04-27
+
+Audit follow-up from the [BENCH_2026_04_27.md](docs/BENCH_2026_04_27.md) sweep. No code-path changes; doc surface and operator-UX polish.
+
+### Added
+- **`## Operator guidance` README section** — concrete "when do I pick which config?" tables. Translates the bench numbers into decisions: `-w 1 + larger pool` vs `-w N + smaller pool` for I/O-bound (multi-worker is 2.6× memory for 0.77× rps if you pick wrong on PG-wait); the `--async-io` decision tree (default OFF unless you're paired with a fiber-cooperative library); how to read p50 vs p99 (tail wins are 5-200× larger than the rps story suggests — size capacity by p99).
+- **Boot-time advisory warn for orphan `--async-io`** — if `async_io: true` is set but no fiber-cooperative library is loaded (`hyperion-async-pg`, `async-redis`, `async-http`), Hyperion logs a single advisory warn at boot pointing at the operator-guidance docs. The setting is still honoured; the warn just helps operators who flipped the flag expecting a free perf bump (bench showed `--async-io` on hello-world = 47% rps regression + 3.65 s p99 spike).
+- **4 new specs in `spec/hyperion/cli_async_io_warn_spec.rb`** covering all four warn-fire cases (true + no library, false, nil, true + library detected via stub_const).
+
 ## [1.6.0] - 2026-04-27
 
 Two parallel improvements landing in 1.6.0:

data/README.md

@@ -25,7 +25,9 @@ bundle exec hyperion config.ru
 
 ## Benchmarks
 
-All numbers are real wrk runs against published Hyperion configs. Hyperion ships **with default-ON structured access logs**; Puma comparisons use Puma defaults (no per-request log emission). Each section is stamped with the Hyperion version it was measured against — newer versions (1.3.0+ `--async-io`, 1.4.0+ TLS h1 inline, 1.4.1+ Metrics fiber-key fix) preserve or improve these numbers; we re-run the headline configs each release and have not seen regressions on these workloads.
+All numbers are real wrk runs against published Hyperion configs. Hyperion ships **with default-ON structured access logs**; Puma comparisons use Puma defaults (no per-request log emission). Each section is stamped with the Hyperion version it was measured against — newer versions (1.3.0+ `--async-io`, 1.4.0+ TLS h1 inline, 1.4.1+ Metrics fiber-key fix, 1.6.0+ HTTP/2 writer fiber + 3 C-ext additions) preserve or improve these numbers; we re-run the headline configs each release and have not seen regressions on these workloads.
+
+> **Comprehensive matrix for 1.6.0 + hyperion-async-pg 0.5.0 (16-vCPU Linux, 9 workloads × 25+ configs)**: see [`docs/BENCH_2026_04_27.md`](docs/BENCH_2026_04_27.md). Headline: 98,818 r/s on hello `-w 16`, 21,215 r/s `-w 4` at p99 < 2 ms, 2,180 r/s on a 50 ms-waiting PG workload (4.1× the best Puma), 1,667 req/s HTTP/2 multiplexed at 0 errors, 155 MB RSS for 10k idle keep-alive connections.
 
 ### Hello-world Rack app
 
@@ -320,6 +322,62 @@ Strict DSL: unknown methods raise `NoMethodError` at boot — typos surface imme
 
 A documented sample lives at [`config/hyperion.example.rb`](config/hyperion.example.rb).
 
+## Operator guidance
+
+Concrete tradeoffs distilled from [`docs/BENCH_2026_04_27.md`](docs/BENCH_2026_04_27.md). If the bench numbers cited below feel surprising, check that doc for the full matrix + caveats.
+
+### When to use `-w N`
+
+| Workload shape | Recommended | Why |
+|---|---|---|
+| **Pure I/O-bound** (PG / Redis / external HTTP, no significant CPU) | `-w 1` + larger pool | Bench: `-w 1 pool=200` = 87 MB / 2,180 r/s vs `-w 4 pool=64` = 224 MB / 1,680 r/s. **2.6× more memory, 0.77× rps** if you pick multi-worker on a wait-bound workload. |
+| **Pure CPU-bound** (heavy JSON / template render / image processing) | `-w N` matching CPU count | Each worker's accept loop is single-threaded under `--async-io`; multi-worker gives CPU-parallelism. Bench: `-w 16 -t 5` hits 98,818 r/s on a 16-vCPU box, 4.7× a `-w 1` ceiling on the same hardware. |
+| **Mixed** (Rails-shaped: ~5 ms CPU + 50 ms PG wait per request) | `-w N/2` (half cores) + medium pool | Lets CPU work parallelise while keeping per-worker memory tractable. Bench `pg_mixed.ru` at `-w 4 -t 5 pool=128` = 1,740 r/s with no cold-start spike (ForkSafe `prefill_in_child: true`). |
+
+Multi-worker on PG-wait workloads is the **wrong** default for most apps — the headline rps doesn't justify the memory and PG-connection cost. Verify your shape with the bench before scaling out.
+
+### When to use `--async-io`
+
+```
+                 Are you using a fiber-cooperative I/O library?
+                 (hyperion-async-pg, async-redis, async-http)
+                              │
+                ┌─────────────┴─────────────┐
+                yes                          no
+                │                            │
+        Pair with a fiber-aware       Leave --async-io OFF.
+        connection pool               Default thread-pool dispatch
+        (FiberPool, async-pool —      is faster for synchronous
+        NOT connection_pool gem,      Rails apps. Bench: --async-io
+        which uses non-fiber Mutex).  on hello-world = 47% rps
+                │                     regression + p99 spike to
+        Set --async-io.               3.65 s under no-yield workloads.
+        Pool size is the real         No reason to flip the flag.
+        concurrency knob; -t is
+        decorative for wait-bound.
+```
+
+Hyperion warns at boot if you set `--async-io` without any fiber-cooperative library loaded. The setting is still honoured; the warn just nudges operators who flipped it expecting a free perf bump.
+
+### Tuning `-t` and pool sizes
+
+- **Without `--async-io`** (sync server, default): `-t` is the concurrency knob. Each in-flight request holds an OS thread; pool size should match `-t`. Bench shows Puma-style behaviour — at 200 wrk conns hitting a 5-thread server, queue depth dominates p99 (Hyperion `-t 5 -w 1` p50 = 0.95 ms vs Puma's same shape at 59.5 ms — Hyperion's queueing is cheaper but the model still serializes at `-t`).
+- **With `--async-io` + a fiber-aware pool**: pool size is the concurrency knob. `-t` is decorative for wait-bound workloads; one accept-loop fiber serves all in-flight queries via the pool. Linear scaling: pool=64 → ~780 r/s, pool=128 → ~1,344 r/s, pool=200 → ~2,180 r/s on 50 ms PG queries.
+- **Pool over WAN**: if `PG.connect` round-trip is >50 ms, expect pool fill at startup to take `pool_size / parallel_fill_threads × RTT`. `hyperion-async-pg 0.5.1+` auto-scales `parallel_fill_threads` so pool=200 fills in ~1-2 s.
+
+### How to read p50 vs p99
+
+Tail latency tells the queueing story; rps tells the throughput story. Hyperion's tail wins are **always** bigger than its rps wins — sometimes the rps numbers look close to a competitor while p99 is 5-200× lower:
+
+| Workload | Hyperion rps / p99 | Closest competitor | rps ratio | p99 ratio |
+|---|---|---|---:|---:|
+| Hello `-w 4` | 21,215 r/s / 1.87 ms | Falcon 24,061 / 9.78 ms | 0.88× | **5.2× lower** |
+| CPU JSON `-w 4` | 15,582 r/s / 2.47 ms | Falcon 18,643 / 13.51 ms | 0.84× | **5.5× lower** |
+| Static 1 MiB | 1,919 r/s / 4.22 ms | Puma 2,074 / 55 ms | 0.93× | **13× lower** |
+| PG-wait `-w 1` pool=200 | 2,180 r/s / 668 ms | Puma 530 r/s + 200 timeouts | **4.1×** | qualitative crush |
+
+**Size capacity by p99, not by mean.** Throughput peaks are easy to fake under controlled bench conditions; tail latency reflects what your slowest user actually experiences when the load balancer fans them onto a busy worker.
+
 ## Logging
 
 Default behaviour (rc16+):

data/lib/hyperion/cli.rb

@@ -26,6 +26,14 @@ module Hyperion
         Hyperion.logger = Hyperion::Logger.new(level: config.log_level, format: config.log_format)
       end
 
+      # Advisory: operators frequently flip --async-io expecting "fast mode"
+      # without installing a fiber-cooperative I/O library. On hello-world this
+      # costs ~5% rps; on no-I/O workloads more. The flag only pays off when
+      # paired with `hyperion-async-pg` / `async-redis` / `async-http`. We log
+      # once at boot pointing at the operator-guidance docs; the operator's
+      # setting is still honoured.
+      warn_orphan_async_io(config)
+
       # Propagate log_requests so every Connection picks it up via
       # `Hyperion.log_requests?` without needing to thread it through
       # Server/ThreadPool/Master plumbing. Default is ON; nil means "don't
@@ -261,6 +269,35 @@ WARNING: argv is visible via `ps`; prefer --admin-token-file PATH for production
     end
     private_class_method :maybe_enable_yjit
 
+    # Probe table for fiber-cooperative I/O libraries. If `async_io: true` is
+    # set but none of these are loaded, the operator has likely flipped the
+    # flag without reading the bench numbers — `--async-io` adds Async-loop
+    # overhead and only pays off when paired with a library whose I/O calls
+    # yield to the scheduler. Hello-world bench (BENCH_2026_04_27.md) showed
+    # a 47% rps regression + 3.65 s p99 spike on this shape.
+    ASYNC_IO_PROBE_LIBS = {
+      'hyperion-async-pg' => -> { defined?(::Hyperion::AsyncPg) },
+      'async-redis' => -> { defined?(::Async::Redis) },
+      'async-http' => -> { defined?(::Async::HTTP) }
+    }.freeze
+
+    def self.warn_orphan_async_io(config)
+      return unless config.async_io == true # nil and false are both no-ops here
+
+      detected = ASYNC_IO_PROBE_LIBS.select { |_name, probe| probe.call }.keys
+      return unless detected.empty?
+
+      Hyperion.logger.warn do
+        {
+          message: 'async_io enabled but no fiber-cooperative I/O library detected',
+          libraries_checked: ASYNC_IO_PROBE_LIBS.keys,
+          impact: 'async_io adds Async-loop overhead (~5-47% rps depending on workload) and only pays off when paired with a library that yields to the Async scheduler on socket waits.',
+          docs: 'https://github.com/andrew-woblavobla/hyperion#operator-guidance'
+        }
+      end
+    end
+    private_class_method :warn_orphan_async_io
+
     # When admin_token is configured, wrap the app in AdminMiddleware so
     # POST /-/quit and GET /-/metrics become token-protected admin endpoints.
     # Skipped when the token is unset — those paths fall through to the app,

data/lib/hyperion/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperion-rb
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 1.6.1
 platform: ruby
 authors:
 - Andrey Lobanov