hyperion-rb 1.2.0 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4174d7143559b6bd05bdc78acf4377add8aca32f885e933786c50f31c956e9ba
-  data.tar.gz: f163a7f5bd2b363f37205e1f1ba845fb0324c329cc15b4c1144e6d519a1bc60a
+  metadata.gz: 154fbd1bc72c4eeb5e0c740354ced74c6fa8ee4295fab8e8551ae83f78313c53
+  data.tar.gz: 4eaea8250dc8315318152c4c54a16803cc8a7b81236ecaa5dad9adee1d1ab95b
 SHA512:
-  metadata.gz: ea61b5e3298ae50b9b6530d51e1f9a5299b0ccfea3b99248230a601a96ebaf764b5d7978215e09a7d73ed7e85ee3f8b5f7d13d40a830ca5c4482a9d192b2919a
-  data.tar.gz: ed8e125b2ff0c9aab53f3178d0f31d1b0db028f8ebf3a40d09ba11e86c3a62756a3c15c7eb3b288faf8dee6f1062159d372cb0c08997a76fedcb97d485d87283
+  metadata.gz: bed63c053e0f6d24876cde01346809ce830e3548382aab430798ee60b7056f926609190064a38d4f39a0c56b43945f4cc9b1b57fe0c938f24f3e95f1a2e499da
+  data.tar.gz: 79decaf41c5b5755e2af9e0ee5475fce3c74bade418dcd7032309a4fa9d9061388cf3757a8ca7191b373ada6c31d2b3eb2453827f569f86a9caeb7970ff27f48

data/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## [1.3.1] - 2026-04-27
+
+Documentation + observability follow-ups for the 1.3.0 `--async-io` feature. No behaviour changes to existing code paths.
+
+### Added
+- **Dispatch-path metrics** — `Hyperion::Server` now bumps two new counters so operators can verify which path served their requests:
+  - `:requests_threadpool_dispatched` — HTTP/1.1 connection handed to the worker pool (or served inline in `start_raw_loop` when `thread_count: 0`).
+  - `:requests_async_dispatched` — HTTP/1.1 connection served inline on the accept-loop fiber under `--async-io`.
+  HTTP/2 streams are not bucketed (per-stream counters cover them); the rare TLS+`thread_count: 0` config is also un-counted to avoid misclassification.
+- **`docs/MIGRATING_FROM_PUMA.md`** — new "Fiber-cooperative I/O for PG-bound apps" section near the top, with the Linux 50 ms `pg_sleep` bench summary and the three-prerequisite checklist (`async_io: true` + `hyperion-async-pg` + fiber-aware pool).
+- **README** — `async_io` documented in the config-DSL example block; the new dispatch-path counters listed in the Metrics table.
+- **Specs** — two new examples in `spec/hyperion/server_async_io_spec.rb`:
+  - `async_io: true` + `thread_count: 0` boots cleanly and serves a request under a scheduler.
+  - Thread-decoupling proof: 5 concurrent requests against a 200 ms fiber-yielding handler complete in <600 ms wall (vs. ~1.0 s if serialized), locking in the architectural promise from the README.
+
+### Changed
+- N/A — no behavioural changes; metrics are additive, docs are additive.
+
+### Fixed
+- N/A.
+
+## [1.3.0] - 2026-04-27
+
+Adds the structural moat for fiber-cooperative I/O. No breaking changes.
+
+### Added
+- **`async_io: true` config flag** (also `--async-io` CLI flag) — when enabled, the plain HTTP/1.1 accept loop runs each connection on a fiber under `Async::Scheduler` instead of handing it to a worker thread. This is what makes [hyperion-async-pg](https://github.com/andrew-woblavobla/hyperion-async-pg) (and other Async-aware libraries) actually cooperate: each fiber yields the OS thread on socket waits, so one thread can serve N concurrent in-flight DB queries instead of 1. **Default off** to keep the 1.2.0 raw-loop perf for fiber-unaware apps. Trade-off: ~5% throughput hit on hello-world; 5–10× throughput on PG-bound workloads when paired with hyperion-async-pg + a fiber-aware connection pool.
+- **Bench validation (macOS, 50ms PG round-trip, 200 concurrent wrk conns):**
+
+  | | r/s | p99 |
+  |---|---:|---:|
+  | Puma 7.2 `-t 5` + plain pg (pool=5) | 88.9 | 2.31 s |
+  | **Hyperion 1.3.0 `--async-io -t 5` + hyperion-async-pg (FiberPool=64)** | **1,103.7** | **237 ms** |
+
+  **12.4× throughput, 9.7× lower p99.** Theoretical ceiling at pool=64 + 50ms query is ~1280 r/s; achieved 86% of it. Linux numbers will land in a follow-up bench section.
+
+### Changed
+- TLS / HTTP/2 paths still always use the Async accept loop (unchanged); they ignore the `async_io` flag because they need the scheduler for ALPN handshake yields and per-stream fiber dispatch anyway.
+- When `async_io: true`, plain HTTP/1.1 dispatch bypasses the thread pool and serves the connection inline on the calling fiber. The pool stays in use for the TLS path's `app.call` hops on each h2 stream.
+
 ## [1.2.0] - 2026-04-27
 
 Production hardening + perf round 2. No breaking changes.

data/README.md

@@ -29,26 +29,27 @@ All numbers are real wrk runs against published Hyperion configs. Hyperion ships
 
 ### Hello-world Rack app
 
-`bench/hello.ru`, single worker, parity threads (`-t 16` vs Puma `-t 16:16`), 4 wrk threads / 50 connections / 10s, macOS arm64 / Ruby 3.3.3:
+`bench/hello.ru`, single worker, parity threads (`-t 5` vs Puma `-t 5:5`), 4 wrk threads / 100 connections / 15s, macOS arm64 / Ruby 3.3.3, Hyperion 1.2.0:
 
-| | r/s | p99 |
-|---|---:|---:|
-| **Hyperion default (logs ON)** | **23,885** | **1.05 ms** |
-| Hyperion `--no-log-requests` | 24,222 | 1.00 ms |
-| Puma `-t 16:16` | 18,794 | 30.89 ms |
+| | r/s | p99 | tail vs Hyperion |
+|---|---:|---:|---:|
+| **Hyperion 1.2.0** (default, logs ON) | **22,496** | **502 µs** | **1×** |
+| Falcon 0.55.3 `--count 1` | 22,199 | 5.36 ms | 11× worse |
+| Puma 7.1.0 `-t 5:5` | 20,400 | 422.85 ms | 845× worse |
 
-**1.27× Puma throughput, ~30× lower p99 — while emitting structured JSON access logs Puma doesn't.**
+**Hyperion: 1.10× Puma throughput, parity with Falcon on throughput, ~10× lower p99 than Falcon and ~845× lower than Puma — while emitting structured JSON access logs the others don't.**
 
 ### Production cluster config (`-w 4`)
 
-Same bench app, `-w 4` cluster, parity threads. macOS arm64:
+Same bench app, `-w 4` cluster, parity threads (`-t 5` everywhere), 4 wrk threads / 200 connections / 15s, macOS arm64:
 
-| | r/s | p99 |
-|---|---:|---:|
-| **Hyperion `-w 4 -t 10`** | **44,221** | **1.15 ms** |
-| Puma `-w 4 -t 10:10` | 37,929 | 17.06 ms |
+| | r/s | p99 | tail vs Hyperion |
+|---|---:|---:|---:|
+| Falcon `--count 4` | 48,197 | 4.84 ms | 5.9× worse |
+| **Hyperion `-w 4 -t 5`** | **40,137** | **825 µs** | **1×** |
+| Puma `-w 4 -t 5:5` | 34,793 | 177.76 ms | 215× worse (1 timeout) |
 
-**1.17× Puma throughput, ~15× lower p99.**
+Falcon edges Hyperion ~20% on raw rps at `-w 4` on macOS hello-world. **Hyperion still leads on tail latency by 5.9× over Falcon and 215× over Puma**, and beats Puma on throughput by 1.15×. On Linux production-config and DB-backed workloads (below) Hyperion takes the rps lead too — the macOS hello-world advantage to Falcon disappears once the workload includes any actual work or the kernel is Linux.
 
 ### Linux production-config (DB-backed Rack)
 
@@ -60,7 +61,61 @@ Same bench app, `-w 4` cluster, parity threads. macOS arm64:
 | Hyperion `--no-log-requests` | 6,364 | 1.114× |
 | Puma `-w 4 -t 10:10` (no per-req logs) | 5,715 | 1.000× |
 
-Bench is network-bound (~3-4 ms median is the PG + Redis round-trip). Hyperion's lead comes from cheaper per-request CPU: lock-free per-thread metrics, per-thread cached iso8601 timestamps in the access log, hand-rolled single-interpolation log line builder, no logger mutex (POSIX `write(2)` atomicity), C-extension response-head builder.
+Bench is **wait-bound** — ~3-4 ms median is the PG + Redis round-trip, dwarfing the per-request CPU work where Hyperion's optimisations live. With a synchronous `pg` driver, fibers don't help: every in-flight DB call still parks an OS thread, and both servers max out at `workers × threads` concurrent queries. To widen this gap requires either an async PG driver — see [hyperion-async-pg](https://github.com/andrew-woblavobla/hyperion-async-pg) (companion gem; pair with `--async-io` and a fiber-aware pool, see "Async I/O — fiber concurrency on PG-bound apps" below) — or a CPU-bound workload, where Hyperion's lead becomes visible (next section).
+
+### Async I/O — fiber concurrency on PG-bound apps
+
+Ubuntu 24.04 / 16 vCPU / Ruby 3.3.3, Postgres 17 over WAN, `wrk -t4 -c200 -d20s`. Single worker (`-w 1`) unless noted. All configs returned 0 non-2xx and 0 timeouts. RSS sampled mid-run via `ps -o rss`.
+
+**Wait-bound workload** (`bench/pg_concurrent.ru`: `SELECT pg_sleep(0.05)` + tiny JSON):
+
+| | r/s | p99 | RSS | vs Puma `-t 5` |
+|---|---:|---:|---:|---:|
+| Puma 8.0 `-t 5` pool=5 | 56.5 | 3.88 s | 87 MB | 1.0× |
+| Puma 8.0 `-t 30` pool=30 | 402.1 | 880 ms | 99 MB | 7.1× |
+| Puma 8.0 `-t 100` pool=100 | 1067.4 | 557 ms | 121 MB | 18.9× |
+| **Hyperion `--async-io -t 5`** pool=32 | 400.4 | 878 ms | 123 MB | 7.1× |
+| **Hyperion `--async-io -t 5`** pool=64 | 778.9 | 638 ms | 133 MB | 13.8× |
+| **Hyperion `--async-io -t 5`** pool=128 | 1344.2 | 536 ms | 148 MB | 23.8× |
+| **Hyperion `--async-io -t 5` pool=200** | **2381.4** | **471 ms** | **164 MB** | **42.2×** |
+| Hyperion `--async-io -w 4 -t 5` pool=64 | 1937.5 | 4.84 s | 416 MB | 34.3× (cold-start p99 — see note) |
+| Falcon 0.55.3 `--count 1` pool=128 | 1665.7 | 516 ms | 141 MB | 29.5× |
+
+**Mixed CPU+wait** (`bench/pg_mixed.ru`: same query + 50-key JSON serialization, ~5 ms CPU):
+
+| | r/s | p99 | RSS | vs Puma `-t 30` |
+|---|---:|---:|---:|---:|
+| Puma 8.0 `-t 30` pool=30 | 351.7 | 963 ms | 127 MB | 1.0× |
+| Hyperion `--async-io -t 5` pool=32 | 371.2 | 919 ms | 151 MB | 1.05× |
+| Hyperion `--async-io -t 5` pool=64 | 741.5 | 681 ms | 161 MB | 2.1× |
+| **Hyperion `--async-io -t 5` pool=128** | **1739.9** | **512 ms** | **201 MB** | **4.9×** |
+| Falcon `--count 1` pool=128 | 1642.1 | 531 ms | 213 MB | 4.7× |
+
+**Takeaways:**
+1. **Linear scaling with pool size** under `--async-io` — `r/s ≈ pool × 12` on this WAN bench. Single-worker pool=200 hits 2381 r/s, **42× Puma `-t 5`** and **5.9× Puma's best** (`-t 30`).
+2. **Mixed workload doesn't kill the win** — Hyperion `--async-io` pool=128 actually goes *up* on mixed (1740 vs 1344 r/s) because CPU work overlaps other fibers' PG-wait windows. This is the honest "what happens to a real Rails handler" answer.
+3. **Hyperion ≈ Falcon within 3-7%** across pool sizes; both fiber-native architectures extract similar value from `hyperion-async-pg`.
+4. **RSS at single-worker scale isn't the architectural moat** — Linux thread stacks are demand-paged; PG connection buffers dominate RSS at pool sizes ≤ 200. The MB-vs-GB story shows up at **idle keep-alive connection scale** (10k+ conns), not in this PG-bound throughput bench. See [Concurrency at scale](#concurrency-at-scale-architectural-advantages) for the connection-count win.
+5. **`-w 4` cold-start caveat** — multi-worker p99 inflates because the bench rackup uses lazy per-process pool init (each worker pays full pool fill on its first request). Production apps avoid this with `on_worker_boot { Hyperion::AsyncPg::FiberPool.new(...).fill }`.
+
+Three things must all be true to get this win:
+1. **`async_io: true`** in your Hyperion config (or `--async-io` CLI flag). Default is off to keep 1.2.0's raw-loop perf for fiber-unaware apps.
+2. **`hyperion-async-pg`** installed: `gem 'hyperion-async-pg', require: 'hyperion/async_pg'` + `Hyperion::AsyncPg.install!` at boot.
+3. **Fiber-aware connection pool.** The popular `connection_pool` gem is NOT — its Mutex blocks the OS thread. Use [`async-pool`](https://github.com/socketry/async-pool), `Async::Semaphore`, or hand-roll one (see `bench/pg_concurrent.ru` for a ~30-line FiberPool example).
+
+Skip any of these and you get parity with Puma at the same `-t`. Run the bench yourself: `MODE=async DATABASE_URL=... PG_POOL_SIZE=200 bundle exec hyperion --async-io -t 5 bench/pg_concurrent.ru` (in the [hyperion-async-pg](https://github.com/andrew-woblavobla/hyperion-async-pg) repo).
+
+### CPU-bound JSON workload
+
+`bench/work.ru` — handler builds a 50-key fixture, JSON-encodes a fresh response per request (~8 KB body), processes a 6-cookie header chain. wrk `-t4 -c200 -d15s`, macOS arm64 / Ruby 3.3.3, 1.2.0:
+
+| | r/s | p99 | tail vs Hyperion |
+|---|---:|---:|---:|
+| Falcon `--count 4` | 46,166 | 20.17 ms | 24× worse |
+| **Hyperion `-w 4 -t 5`** | **43,924** | **824 µs** | **1×** |
+| Puma `-w 4 -t 5:5` | 36,383 | 166.30 ms (47 socket errors) | 200× worse |
+
+**1.21× Puma throughput, 200× lower p99.** This is the gap that hides behind PG-round-trip noise on the DB bench. Hyperion's per-request CPU savings (lock-free per-thread metrics, frozen header keys in the Rack adapter, C-ext response head builder, cached iso8601 timestamps, cached HTTP Date header) land on the wire when the workload is CPU-bound. Falcon edges us 5% on raw r/s but with 24× worse tail — a different tradeoff curve. Reproduce: `bundle exec bin/hyperion -w 4 -t 5 -p 9292 bench/work.ru`.
 
 ### Real Rails 8.1 app (single worker, parity threads `-t 16`)
 
@@ -77,6 +132,25 @@ Health endpoint that traverses the full middleware chain (rack-attack, locale re
 
 On Grape and Rails-controller workloads Puma hits wrk's 2 s timeout cap on ~⅔ of requests — its real p99 is censored above 2 s. Hyperion serves all of its requests under 1.2 s with 0 to 16 timeouts. **1.14–1.48× Puma throughput** depending on endpoint.
 
+### Static-asset serving (sendfile zero-copy path, 1.2.0+)
+
+`bench/static.ru` (`Rack::Files` over a 1 MiB asset), `-w 1`, `wrk -t4 -c100 -d15s`, macOS arm64 / Ruby 3.3.3:
+
+| | r/s | p99 | transferred | tail vs winner |
+|---|---:|---:|---:|---:|
+| **Hyperion (sendfile path)** | **2,069** | **3.10 ms** | 30.4 GB | **1×** |
+| Puma `-w 1 -t 5:5` | 2,109 | 566.16 ms | 31.0 GB | 183× worse |
+| Falcon `--count 1` | 1,269 | 801.01 ms | 18.7 GB | 258× worse (28 timeouts) |
+
+Throughput is bandwidth-bound on localhost (≈2 GB/s = the loopback memory ceiling), so the throughput column looks like parity. The actual win is in the **tail latency** column: Hyperion's `IO.copy_stream` → `sendfile(2)` path skips userspace entirely, while Puma allocates a String per response and Falcon serializes more aggressively. On real network paths sendfile widens the gap further (kernel-to-NIC zero-copy).
+
+Reproduce:
+```sh
+ruby -e 'File.binwrite("/tmp/hyperion_bench_asset_1m.bin", "x" * (1024*1024))'
+bundle exec bin/hyperion -p 9292 bench/static.ru
+wrk --latency -t4 -c100 -d15s http://127.0.0.1:9292/hyperion_bench_asset_1m.bin
+```
+
 ### Concurrency at scale (architectural advantages)
 
 These workloads demonstrate structural differences between Hyperion's fiber-per-connection / fiber-per-stream model and Puma's thread-pool model. Numbers are illustrative; the architecture is what matters. Run on Ubuntu 24.04 / Ruby 3.3.3, single worker, h2load `-c <conns> -n 100000 --rps 1000 --h1`.
@@ -190,6 +264,8 @@ log_requests true
 
 fiber_local_shim false
 
+async_io false  # When true, the plain HTTP/1.1 accept loop runs each connection on a fiber under Async::Scheduler instead of handing it to a worker thread. Required for fiber-cooperative I/O (e.g. hyperion-async-pg). ~5% throughput hit on hello-world; in exchange one OS thread serves N concurrent in-flight DB queries on wait-bound workloads. TLS / HTTP/2 paths always use the async loop and ignore this flag.
+
 before_fork do
   ActiveRecord::Base.connection_handler.clear_all_connections! if defined?(ActiveRecord)
 end
@@ -254,6 +330,8 @@ The default-ON access log path is engineered to stay near-zero cost:
 | `parse_errors` | HTTP parse failures → 400. |
 | `app_errors` | Rack app raised → 500. |
 | `read_timeouts` | Per-connection read deadline hit. |
+| `requests_threadpool_dispatched` | HTTP/1.1 connection handed to the worker pool (or served inline in `start_raw_loop` when `thread_count: 0`). The default dispatch path. |
+| `requests_async_dispatched` | HTTP/1.1 connection served inline on the accept-loop fiber under `--async-io`. Operators can use the ratio against `requests_threadpool_dispatched` to verify fiber-cooperative I/O is actually engaged. |
 
 ```ruby
 require 'hyperion'

data/lib/hyperion/cli.rb

@@ -57,6 +57,10 @@ module Hyperion
              'Enable Ruby YJIT (default: auto on RAILS_ENV/RACK_ENV=production/staging)') do |v|
           cli_opts[:yjit] = v
         end
+        o.on('--[no-]async-io',
+             'Run plain HTTP/1.1 connections under Async::Scheduler (required for hyperion-async-pg and other fiber-cooperative I/O; default off)') do |v|
+          cli_opts[:async_io] = v
+        end
         o.on('-h', '--help', 'show help') do
           puts o
           exit 0
@@ -114,7 +118,8 @@ module Hyperion
                           read_timeout: config.read_timeout,
                           max_pending: config.max_pending,
                           max_request_read_seconds: config.max_request_read_seconds,
-                          h2_settings: Master.build_h2_settings(config))
+                          h2_settings: Master.build_h2_settings(config),
+                          async_io: config.async_io)
       server.listen
       scheme = tls ? 'https' : 'http'
       Hyperion.logger.info { { message: 'listening', url: "#{scheme}://#{server.host}:#{server.port}" } }

data/lib/hyperion/config.rb

@@ -31,6 +31,7 @@ module Hyperion
       admin_token: nil, # String. When set, exposes admin endpoints (POST /-/quit triggers graceful drain; GET /-/metrics returns Prometheus-format Hyperion.stats). Same token guards both. nil disables admin entirely (paths fall through to the app).
       max_pending: nil, # Integer, e.g. 256. When the per-worker accept inbox has this many queued connections, additional accepts are rejected with HTTP 503 + Retry-After:1 instead of being queued. nil disables (current behaviour: unbounded queue).
       max_request_read_seconds: 60, # Numeric. Total wallclock budget (seconds) for reading the request line + headers + body for ONE request. Defends against slowloris-style drips that satisfy the per-recv read_timeout but never finish the request. Resets between requests on a keep-alive connection. nil disables.
+      async_io: false, # When true, the plain HTTP/1.1 accept loop runs each connection on a fiber under Async::Scheduler instead of handing it to a worker thread. Required for fiber-cooperative I/O (e.g. hyperion-async-pg). Costs ~5% throughput on hello-world; in exchange one OS thread can serve N concurrent in-flight DB queries on wait-bound workloads. TLS / HTTP/2 paths always use the async loop and ignore this flag.
       h2_max_concurrent_streams: 128, # HTTP/2 SETTINGS_MAX_CONCURRENT_STREAMS — cap on simultaneously-open streams per connection. Falcon: 64. nil leaves protocol-http2 default (0xFFFFFFFF).
       h2_initial_window_size: 1_048_576, # HTTP/2 SETTINGS_INITIAL_WINDOW_SIZE (octets) — flow-control window per stream at open. Bigger = fewer WINDOW_UPDATE round-trips on large bodies. Spec default is 65535. nil → leave protocol default.
       h2_max_frame_size: 1_048_576, # HTTP/2 SETTINGS_MAX_FRAME_SIZE (octets) — biggest DATA/HEADERS frame we'll accept. Spec floor 16384, ceiling 16777215. We pick 1 MiB to match common CDNs without unbounded buffer growth. nil → leave protocol default (16384).

data/lib/hyperion/master.rb

@@ -166,7 +166,8 @@ module Hyperion
           worker_index: worker_index,
           max_pending: @config.max_pending,
           max_request_read_seconds: @config.max_request_read_seconds,
-          h2_settings: Master.build_h2_settings(@config)
+          h2_settings: Master.build_h2_settings(@config),
+          async_io: @config.async_io
         }
         # Hand the inherited socket to the worker in :share mode. In
         # :reuseport mode the worker binds its own with SO_REUSEPORT.

data/lib/hyperion/server.rb

@@ -42,7 +42,7 @@ module Hyperion
 
     def initialize(app:, host: '127.0.0.1', port: 9292, read_timeout: DEFAULT_READ_TIMEOUT_SECONDS,
                    tls: nil, thread_count: DEFAULT_THREAD_COUNT, max_pending: nil,
-                   max_request_read_seconds: 60, h2_settings: nil)
+                   max_request_read_seconds: 60, h2_settings: nil, async_io: false)
       @host                     = host
       @port                     = port
       @app                      = app
@@ -52,6 +52,7 @@ module Hyperion
       @max_pending              = max_pending
       @max_request_read_seconds = max_request_read_seconds
       @h2_settings              = h2_settings
+      @async_io                 = async_io
       @thread_pool              = nil
       @stopped                  = false
     end
@@ -107,16 +108,23 @@ module Hyperion
       listen unless @server
       @thread_pool = ThreadPool.new(size: @thread_count, max_pending: @max_pending) if @thread_count.positive?
 
-      if @tls
+      if @tls || @async_io
         # TLS path: ALPN may pick `h2`, and h2 spawns one fiber per stream
         # inside Http2Handler. Keep the Async wrapper so the scheduler is
         # available for those fibers and for handshake yields.
+        #
+        # async_io: true: operator opt-in for plain HTTP/1.1. The Async wrap
+        # is required when callers want fiber cooperative I/O — e.g.
+        # `hyperion-async-pg` yielding while a Postgres query is in flight.
+        # Pays ~5% throughput vs the raw-loop fast path; in exchange one
+        # OS thread can serve N concurrent in-flight DB queries instead of 1.
         start_async_loop
       else
-        # Plain HTTP/1.1: the worker thread owns each connection for its
-        # lifetime, so the Async wrapper adds zero value (no fibers ever
-        # run on this loop's task). Skip it — pure IO.select + accept_nonblock
-        # shaves measurable overhead off the accept hot path.
+        # Plain HTTP/1.1, async_io: false (default): the worker thread owns
+        # each connection for its lifetime, so the Async wrapper adds zero
+        # value (no fibers ever run on this loop's task). Skip it — pure
+        # IO.select + accept_nonblock shaves measurable overhead off the
+        # accept hot path.
         start_raw_loop
       end
     ensure
@@ -143,11 +151,14 @@ module Hyperion
 
         apply_timeout(socket)
         if @thread_pool
-          unless @thread_pool.submit_connection(socket, @app,
-                                                max_request_read_seconds: @max_request_read_seconds)
+          if @thread_pool.submit_connection(socket, @app,
+                                            max_request_read_seconds: @max_request_read_seconds)
+            Hyperion.metrics.increment(:requests_threadpool_dispatched)
+          else
             reject_connection(socket)
           end
         else
+          Hyperion.metrics.increment(:requests_threadpool_dispatched)
           Connection.new.serve(socket, @app, max_request_read_seconds: @max_request_read_seconds)
         end
       end
@@ -172,18 +183,35 @@ module Hyperion
       if socket.is_a?(::OpenSSL::SSL::SSLSocket) && socket.alpn_protocol == 'h2'
         # HTTP/2: each stream runs on a fiber inside Http2Handler. The
         # handler still uses the pool's `#call` for app.call hops on each
-        # stream (one per stream, not one per connection).
+        # stream (one per stream, not one per connection). Per-stream
+        # counters live inside Http2Handler; we don't bump either of the
+        # H1 dispatch buckets here — neither fits the h2 model cleanly.
         Http2Handler.new(app: @app, thread_pool: @thread_pool, h2_settings: @h2_settings).serve(socket)
+      elsif @async_io
+        # async_io plain HTTP/1.1: serve inline on the calling fiber so the
+        # request runs *under* Async::Scheduler. This is what makes
+        # hyperion-async-pg (and other Async-aware libraries) actually
+        # cooperate — each fiber yields the OS thread on socket waits, so
+        # one thread can serve N concurrent in-flight DB queries. The
+        # thread pool is intentionally bypassed here: handing the socket
+        # to a worker thread strips the scheduler context.
+        Hyperion.metrics.increment(:requests_async_dispatched)
+        Connection.new.serve(socket, @app, max_request_read_seconds: @max_request_read_seconds)
       elsif @thread_pool
         # HTTP/1.1 (e.g. TLS-wrapped after ALPN picked http/1.1): hand the
         # connection to a worker thread. The fiber that called dispatch
         # returns immediately. On overflow, reject with 503 + close.
-        unless @thread_pool.submit_connection(socket, @app,
-                                              max_request_read_seconds: @max_request_read_seconds)
+        if @thread_pool.submit_connection(socket, @app,
+                                          max_request_read_seconds: @max_request_read_seconds)
+          Hyperion.metrics.increment(:requests_threadpool_dispatched)
+        else
           reject_connection(socket)
         end
       else
-        # No pool (thread_count: 0): inline on the calling fiber.
+        # No pool (thread_count: 0) on the TLS / async-wrap path. Rare
+        # config — neither dispatch bucket fits cleanly. Leave un-counted
+        # rather than misclassify; the request still shows up in
+        # :requests_total via Connection.
         Connection.new.serve(socket, @app, max_request_read_seconds: @max_request_read_seconds)
       end
     end

data/lib/hyperion/version.rb

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

data/lib/hyperion/worker.rb

@@ -20,7 +20,7 @@ module Hyperion
                    thread_count: Server::DEFAULT_THREAD_COUNT,
                    config: nil, worker_index: 0, listener: nil,
                    max_pending: nil, max_request_read_seconds: 60,
-                   h2_settings: nil)
+                   h2_settings: nil, async_io: false)
       @host                     = host
       @port                     = port
       @app                      = app
@@ -33,6 +33,7 @@ module Hyperion
       @max_pending              = max_pending
       @max_request_read_seconds = max_request_read_seconds
       @h2_settings              = h2_settings
+      @async_io                 = async_io
     end
 
     def run
@@ -51,7 +52,8 @@ module Hyperion
                           thread_count: @thread_count,
                           max_pending: @max_pending,
                           max_request_read_seconds: @max_request_read_seconds,
-                          h2_settings: @h2_settings)
+                          h2_settings: @h2_settings,
+                          async_io: @async_io)
       tcp_server = @listener || build_reuseport_listener
       server.adopt_listener(tcp_server)
 

metadata

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