hyperion-rb 1.3.1 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 154fbd1bc72c4eeb5e0c740354ced74c6fa8ee4295fab8e8551ae83f78313c53
-  data.tar.gz: 4eaea8250dc8315318152c4c54a16803cc8a7b81236ecaa5dad9adee1d1ab95b
+  metadata.gz: 64221d424c994e0757262dca6984cd2b65bf9ec3da6c85094daa717c716da906
+  data.tar.gz: 236188ff1777b49178bb4b2bfe75fbea9309ec6f5d56ec01329943dfa1afbb36
 SHA512:
-  metadata.gz: bed63c053e0f6d24876cde01346809ce830e3548382aab430798ee60b7056f926609190064a38d4f39a0c56b43945f4cc9b1b57fe0c938f24f3e95f1a2e499da
-  data.tar.gz: 79decaf41c5b5755e2af9e0ee5475fce3c74bade418dcd7032309a4fa9d9061388cf3757a8ca7191b373ada6c31d2b3eb2453827f569f86a9caeb7970ff27f48
+  metadata.gz: 9b196f8d046c828546f8f5fbac91e0300e8704a70f11b47096a9b0fb05caf2ec34f63e2f33768ab53b41413aaa4e957ac499aa4779ecd54b6a987deef7fd464e
+  data.tar.gz: cb3d64f757736bcbc2632492e24b0794a67c98bfdcae7a1e53d89f583cf2eecc404e060fd3ec10e441ddfdcd11273c41e0d46fa9b80be904b29a7718fe0258ba

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [1.4.1] - 2026-04-27
+
+### Fixed
+- **`Hyperion::Metrics` fiber-key bug** — pre-1.4.1 the metrics module stored counters via `Thread.current[:key]`, which is FIBER-local in Ruby 1.9+. Under an `Async::Scheduler` (TLS / h2 / `--async-io` plain HTTP/1.1) every handler fiber got its own private counters Hash that `Hyperion.stats` could never see — increments were stranded, the dispatch counters and `:bytes_written` etc. read as zero from any non-handler-fiber observer (including the Prometheus `/-/metrics` exporter when scraped from a different fiber). Switched to `Thread#thread_variable_*` (truly thread-local across fibers) plus direct counter-Hash list storage so snapshots also survive thread death. Verified via 4 new specs: cross-fiber on same thread, cross-thread, cross-fiber-on-different-thread, many-fibers-on-same-thread (210 increments aggregated correctly). Surfaced by hyperion-async-pg 0.4.0's bench round, which couldn't read `:requests_async_dispatched` from spec assertions even though the increments were firing.
+
+## [1.4.0] - 2026-04-27
+
+Default-behaviour change for TLS users: HTTP/1.1-over-TLS now dispatches inline on the calling fiber instead of hopping through the worker thread pool. Fiber-cooperative libraries (`hyperion-async-pg`, `async-redis`) work on the TLS h1 path without `--async-io`. No code-path changes for plain HTTP/1.1 default behaviour.
+
+### Changed
+- **TLS h1 inline dispatch by default** — `Hyperion::Server#dispatch` now serves HTTP/1.1-over-TLS inline on the accept-loop fiber under `Async::Scheduler`. Rationale: the TLS path already wraps the accept loop in `Async {}` for ALPN handshake + h2 streams; handing the post-handshake socket to a worker thread strips that scheduler context for no perf benefit (the Async-loop cost is already paid) and defeats fiber-cooperative I/O on TLS. Operators no longer need to pair `--tls-cert/--tls-key` with `--async-io` to get `hyperion-async-pg` working on TLS — it just works.
+- **`async_io` config is now three-way** — was Boolean (`true` / `false`, default `false`). Now `nil` (default, "auto" — pool on plain HTTP/1.1, inline on TLS h1), `true` (force inline-on-fiber everywhere — required for `hyperion-async-pg` on plain HTTP/1.1), `false` (force pool hop everywhere — explicit opt-out for the rare operator who wants TLS+threadpool, e.g. CPU-bound synchronous handlers competing for OS threads).
+- **Server / Worker constructor defaults** — `Hyperion::Server#initialize` and `Hyperion::Worker#initialize` now default `async_io: nil`. `Hyperion::Config::DEFAULTS[:async_io]` is `nil`.
+
+### Migration
+- **Most users want the new default and should do nothing.** Wait-bound TLS workloads paired with fiber-cooperative I/O libraries (async-pg, async-redis) are now strictly faster on TLS — no flag flip required.
+- **CPU-bound TLS handlers that want true OS-thread parallelism** (synchronous Rack handlers holding a global mutex, no Async-aware libraries in the stack) should set `async_io false` in their `config/hyperion.rb` (or pass `async_io: false` to `Server.new`). This restores the 1.3.x pool-hop behaviour for TLS h1.
+- The plain HTTP/1.1 default path is unchanged: still pool dispatch, still the raw-loop perf-bypass; `--async-io` / `async_io: true` semantics for plain HTTP/1.1 are unchanged.
+
+### Added
+- **`spec/hyperion/server_tls_dispatch_spec.rb`** — three new examples covering the matrix (nil + TLS → inline; false + TLS → pool; true + TLS → inline). Behavioural assertions verify `Fiber.scheduler` presence and which OS thread ran the handler (accept-loop vs pool worker).
+- **README** — TLS + async-pg note rewritten for 1.4.0; config-DSL example block now documents the three-way `async_io` setting.
+
+### Fixed
+- N/A — pure default-behaviour change with explicit opt-out.
+
 ## [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.

data/README.md

@@ -95,16 +95,23 @@ Ubuntu 24.04 / 16 vCPU / Ruby 3.3.3, Postgres 17 over WAN, `wrk -t4 -c200 -d20s`
 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.
+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 architectural win is **handler concurrency under load**, not idle memory: Hyperion's fiber path runs thousands of in-flight handler invocations per OS thread, so wait-bound handlers don't queue at `max_threads`. See [Concurrency at scale](#concurrency-at-scale-architectural-advantages) for both the throughput-under-load row and a measured 10k-idle-keepalive RSS sweep against Puma and Falcon.
 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).
+3. **Fiber-aware connection pool.** The popular `connection_pool` gem is NOT — its Mutex blocks the OS thread. Use `Hyperion::AsyncPg::FiberPool` (ships with hyperion-async-pg 0.3.0+), [`async-pool`](https://github.com/socketry/async-pool), or `Async::Semaphore`.
 
 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).
 
+> **TLS + async-pg note (1.4.0+).** TLS / HTTPS already runs each connection on a fiber under `Async::Scheduler` (the TLS path always uses `start_async_loop` for the ALPN handshake). **As of 1.4.0, the post-handshake `app.call` for HTTP/1.1-over-TLS dispatches inline on the calling fiber by default** — so fiber-cooperative libraries (`hyperion-async-pg`, `async-redis`) work on the TLS h1 path without needing `--async-io`. The Async-loop cost is already paid for the handshake; running the handler under the existing scheduler just preserves that context instead of stripping it on a thread-pool hop. h2 streams are always fiber-dispatched and benefit from async-pg without the flag.
+>
+> Operators who specifically want **TLS + threadpool dispatch** (e.g. CPU-heavy handlers competing for OS threads, where you'd rather not pay fiber yields and want true OS-thread parallelism on a synchronous handler) can pass `async_io: false` in the config to force the pool branch back on. The three-way `async_io` setting:
+> - `nil` (default): plain HTTP/1.1 → pool, TLS h1 → inline.
+> - `true`: plain HTTP/1.1 → inline, TLS h1 → inline (force fiber dispatch everywhere; needed for `hyperion-async-pg` on plain HTTP).
+> - `false`: plain HTTP/1.1 → pool, TLS h1 → pool (explicit opt-out for TLS+threadpool).
+
 ### 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:
@@ -169,7 +176,21 @@ These workloads demonstrate structural differences between Hyperion's fiber-per-
 | Hyperion `-w 1 -t 10` | 93,090 | 6,910 | 3,446 | 27.01 s |
 | Puma `-w 1 -t 10:10`  | 77,340 | 22,660 | 706 | 109.59 s |
 
-Hyperion holds each connection in a ~1 KB fiber stack; Puma needs an OS thread (~1–8 MB each, capped at `max_threads`). At 10k concurrent connections Hyperion serves **~5× the throughput** of Puma with **~20% fewer dropped requests**, while the per-connection bookkeeping cost is bounded by fiber size, not by `max_threads`.
+At 10k concurrent connections under load Hyperion serves **~5× the throughput** of Puma with **~20% fewer dropped requests**. The per-connection bookkeeping cost is bounded by fiber size, not by `max_threads` — workers don't get pinned to long-lived sockets, so a slow handler doesn't starve other connections.
+
+**Memory at idle keep-alive scale — 10,000 idle HTTP/1.1 keep-alive connections:**
+
+Each client opens a TCP connection, sends one keep-alive GET, drains the response, then holds the socket open without sending a follow-up request. RSS is sampled once a second across a 30s idle hold. Same hello-world rackup, single worker, no TLS. Hyperion runs with `async_io true` (fiber-per-connection on the plain HTTP/1.1 path).
+
+| | held | dropped | peak RSS | RSS after drain |
+|---|---:|---:|---:|---:|
+| Hyperion `-w 1 -t 5 --async-io` | 10,000 / 10,000 | 0 | 173 MB | 155 MB |
+| Puma `-w 0 -t 100`               | 10,000 / 10,000 | 0 | 101 MB | 104 MB |
+| Falcon `--count 1`               | 10,000 / 10,000 | 0 | 429 MB | 440 MB |
+
+All three hold 10k idle conns without OOMing or dropping — the "MB-per-thread" intuition that thread-based servers can't reach this scale doesn't survive contact with Linux's demand-paged thread stacks plus Puma's reactor-based keep-alive handling. Per-conn RSS lands at ~14 KB (Hyperion fiber + parser state), ~7 KB (Puma reactor entry + tiny thread share), ~36 KB (Falcon Async::Task + protocol-http stack). Bounded, not unbounded — for all three.
+
+The architectural difference shows up under **load**, not at idle: Puma can only run `max_threads` handler invocations concurrently, so wait-bound handlers (DB, HTTP, Redis) starve at higher request concurrency than `max_threads`. Hyperion's fiber-per-connection model + `--async-io` gives one OS thread thousands of in-flight handler executions, paired with [hyperion-async-pg](https://github.com/exodusgaming-io/hyperion-async-pg) for non-blocking DB. The 10k-conn throughput row above (5× Puma) is the consequence — same idle RSS shape, very different behaviour once the handlers actually do work.
 
 **HTTP/2 multiplexing — 1 connection × 100 concurrent streams (handler sleeps 50 ms):**
 
@@ -187,6 +208,9 @@ Hyperion fans 100 in-flight streams across separate fibers within a single TCP c
 bundle exec ruby bench/compare.rb
 HYPERION_WORKERS=4 PUMA_WORKERS=4 FALCON_COUNT=4 bundle exec ruby bench/compare.rb
 
+# Idle keep-alive RSS sweep (1k / 5k / 10k conns, 30s hold per server)
+./bench/keepalive_memory.sh
+
 # Real Rails / Grape: see bench/db.ru for the schema
 ```
 
@@ -264,7 +288,7 @@ 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.
+async_io nil    # Three-way (1.4.0+): nil (default, auto: inline-on-fiber for TLS h1, pool hop for plain HTTP/1.1), true (force inline-on-fiber everywhere — required for hyperion-async-pg on plain HTTP/1.1), false (force pool hop everywhere — explicit opt-out for TLS+threadpool with CPU-heavy handlers). ~5% throughput hit on hello-world when inline; in exchange one OS thread serves N concurrent in-flight DB queries on wait-bound workloads. TLS / HTTP/2 accept loops always run under Async::Scheduler regardless of this flag.
 
 before_fork do
   ActiveRecord::Base.connection_handler.clear_all_connections! if defined?(ActiveRecord)

data/lib/hyperion/config.rb

@@ -31,7 +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.
+      async_io: nil, # Three-way: nil (default, auto: inline on TLS h1 / pool on plain HTTP/1.1), true (force inline-on-fiber for plain HTTP/1.1 too — required for fiber-cooperative I/O like hyperion-async-pg on plain HTTP), false (force pool hop everywhere — explicit opt-out for operators who specifically want TLS+threadpool with CPU-bound handlers). Costs ~5% throughput on hello-world when inline; in exchange one OS thread can serve N concurrent in-flight DB queries on wait-bound workloads. TLS / HTTP/2 paths always run the Async accept loop regardless of 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/metrics.rb

@@ -7,6 +7,22 @@ module Hyperion
   # all threads that have ever incremented (one short mutex section, only
   # taken when the operator asks for stats).
   #
+  # Storage: counters live behind `Thread#thread_variable_*`, which is the
+  # only TRUE thread-local in Ruby 1.9+ — `Thread.current[:key]` is in fact
+  # FIBER-local, so under an `Async::Scheduler` (TLS path, h2 streams, the
+  # 1.3.0+ `--async-io` plain HTTP/1.1 path) every handler fiber would get
+  # its own private counters Hash that `snapshot` could never find.
+  # Verified with hyperion-async-pg 0.4.0's bench round; before the fix
+  # the dispatch counters dropped requests entirely under `--async-io` and
+  # an external scrape (Prometheus exporter on a different fiber than the
+  # handler) saw the dispatch buckets at zero.
+  #
+  # Cross-fiber races on the same OS thread: the `+=` is technically read-
+  # modify-write, but Ruby's fiber scheduler only preempts at IO boundaries
+  # (Fiber.scheduler-aware system calls), and `Hash#[]=` is purely Ruby —
+  # no preemption mid-increment, no torn writes. Two fibers cannot
+  # interleave a single `+=` on the same OS thread.
+  #
   # Reset semantics: counters monotonically increase. Operators that want
   # rate-of-change should snapshot, sleep, snapshot, diff.
   #
@@ -14,16 +30,40 @@ module Hyperion
   #   Hyperion.stats -> Hash with all current values across all threads.
   class Metrics
     def initialize
-      @threads = Set.new
-      @threads_mutex = Mutex.new
-      # Each Metrics instance has its own thread-local key so spec runs that
-      # build fresh Metrics objects don't share state across examples.
+      # Direct list of every per-thread counters Hash ever allocated through
+      # this Metrics instance. We hold the Hash refs ourselves (instead of
+      # holding Thread refs and looking the Hash up via thread-local
+      # storage) so snapshot survives thread death — counters from a
+      # short-lived worker that already exited still aggregate. Tiny per-
+      # thread footprint (one Hash + one slot in this Array).
+      @thread_counters = []
+      @counters_mutex = Mutex.new
+      # Per-instance thread-local key so spec runs that build fresh Metrics
+      # objects don't share state across examples.
       @thread_key = :"__hyperion_metrics_#{object_id}__"
     end
 
-    # Hot path: one TLS lookup + one hash op. No mutex.
+    # Hot path: one thread-variable lookup + one hash op. No mutex on the
+    # increment fast path; the mutex is taken only on first allocation per
+    # OS thread (very rare) and on snapshot.
+    #
+    # Storage uses Thread#thread_variable_*, which is the only TRUE thread-
+    # local in Ruby 1.9+ — Thread.current[:key] is in fact FIBER-local, so
+    # under an Async::Scheduler (TLS path, h2 streams, the 1.3.0+ --async-io
+    # plain HTTP/1.1 path) every handler fiber would get its own private
+    # counters Hash that snapshot could never aggregate. Verified with
+    # hyperion-async-pg 0.4.0's bench round; before the fix the dispatch
+    # counters dropped requests under --async-io.
+    #
+    # Cross-fiber races on the same OS thread: the `+=` is read-modify-write,
+    # but Ruby's fiber scheduler only preempts at IO boundaries (Fiber-
+    # scheduler-aware system calls). Hash#[]= is purely Ruby — no
+    # preemption mid-increment, no torn writes. Two fibers cannot
+    # interleave a single `+=` on the same OS thread.
     def increment(key, by = 1)
-      counters = Thread.current[@thread_key] ||= register_thread_counters
+      thread = Thread.current
+      counters = thread.thread_variable_get(@thread_key)
+      counters = register_thread_counters(thread) if counters.nil?
       counters[key] += by
     end
 
@@ -37,14 +77,9 @@ module Hyperion
 
     def snapshot
       result = Hash.new(0)
-      @threads_mutex.synchronize do
-        @threads.delete_if { |t| !t.alive? }
-        @threads.each do |t|
-          counters = t[@thread_key]
-          next unless counters
-
-          counters.each { |k, v| result[k] += v }
-        end
+      counters_snapshot = @counters_mutex.synchronize { @thread_counters.dup }
+      counters_snapshot.each do |counters|
+        counters.each { |k, v| result[k] += v }
       end
       result.default = nil
       result
@@ -52,16 +87,17 @@ module Hyperion
 
     # Tests can call .reset! between examples to avoid cross-spec leakage.
     def reset!
-      @threads_mutex.synchronize do
-        @threads.each { |t| t[@thread_key]&.clear }
+      @counters_mutex.synchronize do
+        @thread_counters.each(&:clear)
       end
     end
 
     private
 
-    def register_thread_counters
+    def register_thread_counters(thread)
       counters = Hash.new(0)
-      @threads_mutex.synchronize { @threads << Thread.current }
+      thread.thread_variable_set(@thread_key, counters)
+      @counters_mutex.synchronize { @thread_counters << counters }
       counters
     end
   end

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, async_io: false)
+                   max_request_read_seconds: 60, h2_settings: nil, async_io: nil)
       @host                     = host
       @port                     = port
       @app                      = app
@@ -111,7 +111,10 @@ module Hyperion
       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.
+        # available for those fibers and for handshake yields. Plain
+        # HTTP/1.1-over-TLS dispatch is also handled inline on the calling
+        # fiber by default in 1.4.0+ (see #dispatch) — fiber-cooperative
+        # libraries (async-pg, async-redis) work without --async-io.
         #
         # 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.
@@ -120,9 +123,10 @@ module Hyperion
         # OS thread can serve N concurrent in-flight DB queries instead of 1.
         start_async_loop
       else
-        # 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
+        # Plain HTTP/1.1, async_io: nil (default with no TLS) or
+        # async_io: false (explicit opt-out): 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
@@ -187,19 +191,26 @@ module Hyperion
         # 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.
+      elsif inline_h1_dispatch?
+        # Inline-on-fiber HTTP/1.1 dispatch. Two ways to land here:
+        #   1. async_io: true — operator explicitly opted into fiber I/O on
+        #      the plain HTTP/1.1 path.
+        #   2. async_io: nil (default) AND TLS configured — TLS already
+        #      runs the Async accept loop for ALPN handshake + h2 streams,
+        #      so the scheduler is current on this fiber. Handing the
+        #      socket to a worker thread would strip the scheduler context
+        #      for no perf benefit (we paid the Async-loop cost already)
+        #      and would defeat hyperion-async-pg / async-redis on the
+        #      TLS h1 path.
+        # Operators who specifically want TLS+threadpool (e.g. CPU-heavy
+        # handlers competing for OS threads) can pass async_io: false to
+        # force the pool branch below.
         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
+        # HTTP/1.1 default plain-HTTP path, OR explicit async_io: false on
+        # TLS (operator opted out of inline-on-fiber dispatch). Hand the
+        # connection to a worker thread; the fiber that called dispatch
         # returns immediately. On overflow, reject with 503 + close.
         if @thread_pool.submit_connection(socket, @app,
                                           max_request_read_seconds: @max_request_read_seconds)
@@ -208,14 +219,29 @@ module Hyperion
           reject_connection(socket)
         end
       else
-        # 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.
+        # No pool (thread_count: 0) on the TLS / async-wrap path with
+        # async_io: false. 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
 
+    # Decide whether to serve HTTP/1.1 inline on the calling fiber instead
+    # of hopping through the worker thread pool. The matrix:
+    #   async_io == true       → inline always (plain h1 + TLS h1).
+    #   async_io == nil + TLS  → inline (TLS already runs Async loop, so
+    #                            the scheduler is current; preserve it).
+    #   async_io == nil + plain → pool (pure HTTP/1.1 fast path; no scheduler).
+    #   async_io == false       → pool always (explicit opt-out).
+    def inline_h1_dispatch?
+      return true if @async_io == true
+      return false if @async_io == false
+
+      # @async_io.nil? — auto: inline on TLS, pool on plain.
+      !@tls.nil?
+    end
+
     # Backpressure rejection. Emits a pre-built 503 + closes the socket.
     # No Rack env, no app dispatch, no access-log line — the overload
     # path must stay cheap so we don't pile rejection cost on top of the

data/lib/hyperion/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hyperion
-  VERSION = '1.3.1'
+  VERSION = '1.4.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, async_io: false)
+                   h2_settings: nil, async_io: nil)
       @host                     = host
       @port                     = port
       @app                      = app

metadata

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