hyperion-rb 1.3.1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 154fbd1bc72c4eeb5e0c740354ced74c6fa8ee4295fab8e8551ae83f78313c53
-  data.tar.gz: 4eaea8250dc8315318152c4c54a16803cc8a7b81236ecaa5dad9adee1d1ab95b
+  metadata.gz: 94ad9628c5683d6b9c9d2d8359066e4bda37d29c7ec2e4fb4e48ae726f8ff939
+  data.tar.gz: 7ebf3c87d10a384e388cf7f2c28d276c0975044a49fe09e1174ffa331cab76b4
 SHA512:
-  metadata.gz: bed63c053e0f6d24876cde01346809ce830e3548382aab430798ee60b7056f926609190064a38d4f39a0c56b43945f4cc9b1b57fe0c938f24f3e95f1a2e499da
-  data.tar.gz: 79decaf41c5b5755e2af9e0ee5475fce3c74bade418dcd7032309a4fa9d9061388cf3757a8ca7191b373ada6c31d2b3eb2453827f569f86a9caeb7970ff27f48
+  metadata.gz: 9fb844690d5a06aa55335211bdaf3a5276b48f7cfd8a248bb714258ae02549a7e595bc1088987ae9c77d3f28aa1efec91fcd8cc401c26264620f48d78d85faf3
+  data.tar.gz: d050bffe3c8fed2ae1ce434fb7ccf8904a418e3fa18c6afd3e4314b841215ca0dec621edb7bc5f80350e4807e04503b1e785786fb57503b716e52afaf2e30a20

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [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

@@ -101,10 +101,17 @@ Ubuntu 24.04 / 16 vCPU / Ruby 3.3.3, Postgres 17 over WAN, `wrk -t4 -c200 -d20s`
 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:
@@ -264,7 +271,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/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.0'
 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.0
 platform: ruby
 authors:
 - Andrey Lobanov