hyperion-rb 2.16.3 → 2.16.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b52ac123c5a40e73e75a2384abf032393a9b90e8aad6b2701903373e518d6bd2
-  data.tar.gz: 529138f8068a67192a9e45ebd6599510f8a14d0ef405b1e0c57e8ee043d4f713
+  metadata.gz: 1052090a1cfa42b3ba8807ff239b88f1b5700b0efd2df58a84166b0f754d6496
+  data.tar.gz: '028fa894acb855151cd2901aa1964fb2fd4be68908060401ba64a80d43987bd1'
 SHA512:
-  metadata.gz: 8cd08a9d462cce2158d6c508038b7b05d8f6e6e50f7372b36c2c28827b440038963f62e29663a76204c4b2387dd8b4d648c1bc5bd2db9b81394375f1cbb18054
-  data.tar.gz: 4113cfca038452c873d2bd48ac9a890480a6d1d65c52374a7e85693504f094de04e6d7f112a08a7c27b33e3f8464c558c2307782e63d84dffbb5acfcdcecb08b
+  metadata.gz: b080a73c39cbaa284594bda8b2a0dab21f2e737d8d4fd0b6316026bf9fb72b913f3d001117f4291166a6436fd1af0dae11766c47141aa54ca84c759d718c516d
+  data.tar.gz: 24fd2ff23e4ace9e29e9b43ef5c1becaaa1d732e4cff0ac6cafd1fa3fce317029afcf4cc26d3ee5cdad19ccfe7b7252f6da8b3d3a731824a1a10d74f043e4107

data/CHANGELOG.md

@@ -1,5 +1,80 @@
 # Changelog
 
+## 2.16.4 — 2026-05-07
+
+### io_uring hotpath accept fiber: row-19 BOOT-FAIL fix
+
+Bug fix only; no public API change. Restores the
+`--async-io + io_uring_hotpath=on + 1w` boot path on Linux 5.19+.
+
+- **`Hyperion::Server#run_accept_fiber_io_uring_hotpath`** used
+  `@metrics.increment(:connections_accepted)` /
+  `@metrics.increment(:connections_active)` on every accept
+  completion, but `Server` has no `@metrics` ivar — sibling write
+  paths route through `runtime_metrics` (which resolves to
+  `@runtime.metrics` or `Hyperion.metrics`). Reading the unset
+  ivar yielded `nil`, so the first `OP_ACCEPT` completion raised
+  `NoMethodError: undefined method 'increment' for nil`. The
+  `rescue StandardError` block caught it, logged
+  `"io_uring hotpath accept fiber error; falling back to epoll"`,
+  and bailed to the epoll path. The fault only manifested on the
+  `--async-io` boot shape because `start_async_loop` is the only
+  call path that drives the hotpath fiber — `start_raw_loop`
+  short-circuits to the C accept loop and bypasses the bug
+  entirely (which is why the hotpath-on synthetic rows kept
+  passing while the AR-CRUD `--async-io` row took down `wait_for_bind`
+  and registered as `BOOT-FAIL`). Replaced with `runtime_metrics`.
+
+- **`Hyperion::Connection#feed_read_bytes`** and
+  **`#close_for_eof`** were defined under `private` (line 536) but
+  called externally from the accept fiber per their own doc
+  comments. Each `OP_RECV` completion would have re-tripped the
+  fallback with `NoMethodError: private method 'feed_read_bytes'
+  called …`. Moved both to `public`.
+
+- **`Hyperion::Server#run_accept_fiber_io_uring_hotpath` rescue
+  ordering**: the `rescue` blocks called `run_accept_fiber_epoll(task)`
+  *before* the `ensure` closed the hotpath ring. While the fallback
+  ran, the multishot-accept SQE stayed armed against the listener
+  fd and competed with the fallback's `accept_or_nil` for incoming
+  connections — defeating the recovery. Extracted
+  `close_hotpath_ring_for_fallback` and call it before the fallback
+  invocation in every rescue path.
+
+- **`spec/hyperion/connection_io_uring_hotpath_spec.rb`** had a
+  `rescue StandardError => e ; pending "in-process boot is fragile"`
+  block that masked the `NoMethodError` above as a flake for the
+  bench gate to chase. Removed the `pending` rescue and added
+  `async_io: true` to `boot_server_thread` (without it the spec
+  exercised `start_raw_loop`, not the hotpath fiber it claimed to
+  test — which is exactly how the bug slipped past CI).
+
+- **`spec/hyperion/server_metrics_ivar_regression_spec.rb`** new —
+  cross-platform structural guard so a future re-introduction of
+  an `@metrics` ivar reference in `Server` trips on macOS / Linux
+  CI before reaching the bench gate.
+
+Bench evidence on the project's Linux 6.8 + io_uring 5.19+ host
+against PG 17 (canonical `--async-io` + `hyperion-async-pg`):
+
+| Trial | Requests/sec | p99 latency |
+|---:|---:|---:|
+| 1 | 468.46 | 237.95 ms |
+| 2 | 474.61 | 220.60 ms |
+| 3 | 492.93 | 234.79 ms |
+| **Median** | **474.61** | **234.79 ms** |
+
+Boot succeeded in 5 s (vs `BOOT-FAIL` after 45 s on 2026-05-07).
+Zero `io_uring hotpath accept fiber error` warn lines and zero
+`io_uring hotpath ring unhealthy` lines across the 60 s wrk window:
+the hotpath served every request end-to-end with no fallback
+engagement. p99 is ~2× better than the 2026-05-05 first pass
+(234 ms vs 497 ms) — the 2026-05-05 run used the epoll-style
+accept loop; this run exercises multishot-accept + multishot-recv
++ send-SQE on the unified ring as designed (shallower queues,
+trades some throughput for tail latency). CSV in
+`docs/BENCH_ROW19_HOTPATH_FIX_2026_05_07.csv`.
+
 ## 2.16.3 — 2026-05-05
 
 ### 2.16.3-A — Hot-path Ruby cost reduction (metrics + split_host cache)

data/ext/hyperion_http/extconf.rb

@@ -15,6 +15,7 @@ require 'mkmf'
 # is available (the C source raises NotImplementedError at call time).
 $srcs = %w[
   parser.c
+  response_writer.c
   sendfile.c
   page_cache.c
   io_uring_loop.c
@@ -37,6 +38,14 @@ have_header('sys/sendfile.h') # Linux: sendfile64
 have_header('sys/uio.h')      # BSD/Darwin sendfile + Linux iovec plumbing
 have_header('sys/socket.h')
 
+# Plan #1 (perf roadmap) — direct-syscall response writer probes.
+# All POSIX-shaped; on macOS MSG_NOSIGNAL doesn't exist so the C
+# source falls back to writev with #ifdef MSG_NOSIGNAL guards.
+have_func('writev', 'sys/uio.h')
+have_func('sendmsg', 'sys/socket.h')
+have_macro('MSG_NOSIGNAL', 'sys/socket.h')
+have_macro('TCP_CORK', 'netinet/tcp.h')
+
 # 2.4-A: h2_codec_glue.c calls dlopen/dlsym to wire the Rust HPACK
 # cdylib without going through Fiddle on the per-call hot path. macOS
 # ships dlopen in libSystem (no extra link flag needed); Linux glibc

data/ext/hyperion_http/parser.c

@@ -3,6 +3,7 @@
 #include <ruby/st.h>
 #include <string.h>
 #include "llhttp.h"
+#include "response_writer.h"
 
 /* ----------------------------------------------------------------------
  * Hyperion::CParser — C extension wrapping llhttp.
@@ -568,9 +569,10 @@ typedef struct {
     /* Two-word key: input key VALUE bits + value VALUE bits. */
     VALUE key_v;
     VALUE val_v;
-    VALUE line;     /* "<lc-key>: <value>\r\n" buffer */
+    VALUE line;        /* "<lc-key>: <value>\r\n" buffer */
     long  line_len;
-    int   is_date;  /* 1 if lc-key == "date" — caller skips the date tail */
+    int   is_date;     /* 1 if lc-key == "date" — caller skips the date tail */
+    int   is_framing;  /* 1 if lc-key == "transfer-encoding" — skip in chunked mode */
 } header_line_cache_entry_t;
 
 static st_table *g_header_line_cache = NULL;
@@ -601,7 +603,7 @@ static const struct st_hash_type header_line_cache_type = {
  * and st_insert. */
 static const header_line_cache_entry_t *header_line_cache_lookup(VALUE key, VALUE val) {
     if (g_header_line_cache == NULL) return NULL;
-    header_line_cache_entry_t probe = { key, val, Qnil, 0, 0 };
+    header_line_cache_entry_t probe = { key, val, Qnil, 0, 0, 0 };
     st_data_t found_data;
     if (st_lookup(g_header_line_cache, (st_data_t)&probe, &found_data)) {
         return (const header_line_cache_entry_t *)found_data;
@@ -664,6 +666,8 @@ static const header_key_cache_entry_t *header_key_cache_lookup(VALUE key_v) {
 typedef struct {
     VALUE buf;
     int has_date;
+    int is_chunked;  /* 1 → skip content-length + transfer-encoding from user headers;
+                      *     emit transfer-encoding: chunked instead (set by sentinel -1). */
 } build_head_state_t;
 
 static int build_head_each(VALUE k, VALUE v, VALUE arg) {
@@ -671,11 +675,16 @@ static int build_head_each(VALUE k, VALUE v, VALUE arg) {
 
     /* Full-line cache fast path: BOTH key AND value are frozen-literal
      * Strings AND the (key, value) pair is already cached. ONE rb_str_cat
-     * consumes the entire prebuilt "<lc-key>: <value>\r\n" line. */
+     * consumes the entire prebuilt "<lc-key>: <value>\r\n" line.
+     * In chunked mode, skip any framing headers (transfer-encoding) that
+     * may have been cached from a previous non-chunked call on the same
+     * connection. content-length is never in the cache because the slow
+     * path drops it before the cache-populate step. */
     if (TYPE(k) == T_STRING && TYPE(v) == T_STRING &&
         OBJ_FROZEN_RAW(k) && OBJ_FROZEN_RAW(v)) {
         const header_line_cache_entry_t *line_e = header_line_cache_lookup(k, v);
         if (line_e != NULL) {
+            if (st->is_chunked && line_e->is_framing) return ST_CONTINUE;
             rb_str_cat(st->buf, RSTRING_PTR(line_e->line), line_e->line_len);
             if (line_e->is_date) st->has_date = 1;
             return ST_CONTINUE;
@@ -717,9 +726,14 @@ static int build_head_each(VALUE k, VALUE v, VALUE arg) {
     }
 
     /* Drop user-supplied content-length / connection — we always set
-     * these unconditionally below. */
+     * these unconditionally below.
+     * In chunked mode also drop transfer-encoding — we emit our own
+     * "transfer-encoding: chunked\r\n" (RFC 7230 §3.3.3: content-length
+     * and transfer-encoding are mutually exclusive). */
     if (lc_len == 14 && memcmp(lc_ptr, "content-length", 14) == 0) return ST_CONTINUE;
     if (lc_len == 10 && memcmp(lc_ptr, "connection", 10) == 0)     return ST_CONTINUE;
+    if (st->is_chunked &&
+        lc_len == 17 && memcmp(lc_ptr, "transfer-encoding", 17) == 0) return ST_CONTINUE;
 
     if (lc_len == 4 && memcmp(lc_ptr, "date", 4) == 0) st->has_date = 1;
 
@@ -733,7 +747,8 @@ static int build_head_each(VALUE k, VALUE v, VALUE arg) {
     rb_str_cat(st->buf, "\r\n", 2);
 
     /* Populate the line cache for next time when both sides are frozen
-     * literals and we have room. */
+     * literals and we have room. Mark transfer-encoding entries as
+     * is_framing so the full-line fast path can skip them in chunked mode. */
     if (g_header_line_cache != NULL &&
         TYPE(k) == T_STRING && TYPE(v) == T_STRING &&
         OBJ_FROZEN_RAW(k) && OBJ_FROZEN_RAW(v) &&
@@ -747,11 +762,12 @@ static int build_head_each(VALUE k, VALUE v, VALUE arg) {
         rb_obj_freeze(line);
 
         header_line_cache_entry_t *ne = ALLOC(header_line_cache_entry_t);
-        ne->key_v    = k;
-        ne->val_v    = v;
-        ne->line     = line;
-        ne->line_len = line_len;
-        ne->is_date  = (lc_len == 4 && memcmp(lc_ptr, "date", 4) == 0) ? 1 : 0;
+        ne->key_v      = k;
+        ne->val_v      = v;
+        ne->line       = line;
+        ne->line_len   = line_len;
+        ne->is_date    = (lc_len == 4  && memcmp(lc_ptr, "date", 4) == 0) ? 1 : 0;
+        ne->is_framing = (lc_len == 17 && memcmp(lc_ptr, "transfer-encoding", 17) == 0) ? 1 : 0;
 
         rb_ary_push(rb_aHeaderLineAnchor, k);
         rb_ary_push(rb_aHeaderLineAnchor, v);
@@ -811,6 +827,23 @@ static VALUE cbuild_response_head(VALUE self, VALUE rb_status, VALUE rb_reason,
     long body_size = NUM2LONG(rb_body_size);
     int keep_alive = RTEST(rb_keep_alive);
 
+    /* body_size == -1 is the chunked-encoding sentinel; any other
+     * negative value is a programming error (likely an integer
+     * underflow in a caller). Reject early with a clear message
+     * rather than silently treating -2 / -42 as chunked. */
+    if (body_size < -1) {
+        rb_raise(rb_eArgError,
+                 "body_size must be >= 0 (or -1 for chunked sentinel), got %ld",
+                 body_size);
+    }
+
+    /* body_size == -1 is the chunked-encoding sentinel (from
+     * hyperion_build_response_head_chunked).  In this mode we emit
+     * "transfer-encoding: chunked\r\n" instead of "content-length: N\r\n"
+     * and suppress any user-supplied content-length / transfer-encoding
+     * headers (RFC 7230 §3.3.3 — they are mutually exclusive). */
+    int is_chunked = (body_size == -1);
+
     /* Most heads fit in 1 KiB; rb_str_cat grows on demand. */
     VALUE buf = rb_str_buf_new(1024);
 
@@ -831,18 +864,25 @@ static VALUE cbuild_response_head(VALUE self, VALUE rb_status, VALUE rb_reason,
 
     /* Iterate user headers — lowercase key, validate value, skip framing.
      * Threaded through rb_hash_foreach so we can reuse the per-key
-     * downcase cache and skip the per-call `keys` Array allocation. */
-    build_head_state_t state = { buf, 0 };
+     * downcase cache and skip the per-call `keys` Array allocation.
+     * is_chunked is threaded through state so build_head_each can drop
+     * user-supplied transfer-encoding and content-length in chunked mode. */
+    build_head_state_t state = { buf, 0, is_chunked };
     rb_hash_foreach(rb_headers, build_head_each, (VALUE)&state);
 
-    /* Framing headers — always emitted. content-length uses a hand-rolled
-     * itoa rather than snprintf (vfprintf was 1 % of CPU on the
-     * CPU-JSON profile). */
-    char itoa_scratch[24];
-    int cl_off = itoa_positive_decimal(body_size, itoa_scratch, (int)sizeof(itoa_scratch));
-    rb_str_cat(buf, "content-length: ", 16);
-    rb_str_cat(buf, itoa_scratch + cl_off, sizeof(itoa_scratch) - cl_off);
-    rb_str_cat(buf, "\r\n", 2);
+    /* Framing headers — always emitted.
+     * Non-chunked: content-length uses a hand-rolled itoa rather than
+     *   snprintf (vfprintf was 1 % of CPU on the CPU-JSON profile).
+     * Chunked: transfer-encoding: chunked (no content-length — RFC 7230 §3.3.3). */
+    if (is_chunked) {
+        rb_str_cat(buf, "transfer-encoding: chunked\r\n", 28);
+    } else {
+        char itoa_scratch[24];
+        int cl_off = itoa_positive_decimal(body_size, itoa_scratch, (int)sizeof(itoa_scratch));
+        rb_str_cat(buf, "content-length: ", 16);
+        rb_str_cat(buf, itoa_scratch + cl_off, sizeof(itoa_scratch) - cl_off);
+        rb_str_cat(buf, "\r\n", 2);
+    }
 
     if (keep_alive) {
         rb_str_cat(buf, "connection: keep-alive\r\n", 24);
@@ -862,6 +902,34 @@ static VALUE cbuild_response_head(VALUE self, VALUE rb_status, VALUE rb_reason,
     return buf;
 }
 
+/* response_writer.h surface — called from response_writer.c to reuse the
+ * head-build logic without going through Ruby method dispatch on the hot path.
+ * Both wrappers delegate directly to cbuild_response_head; they are NOT static
+ * so the linker can resolve them from response_writer.c in the same .bundle. */
+
+/* hyperion_build_response_head — non-chunked path.
+ * Calling convention matches the Ruby-side method:
+ *   status / reason / headers / body_size / keep_alive / date_str. */
+VALUE hyperion_build_response_head(VALUE status, VALUE reason, VALUE headers,
+                                   VALUE body_size, VALUE keep_alive,
+                                   VALUE date_str) {
+    return cbuild_response_head(Qnil, status, reason, headers,
+                                body_size, keep_alive, date_str);
+}
+
+/* hyperion_build_response_head_chunked — chunked-encoding path.
+ * Same byte shape as ResponseWriter#build_head_chunked in response_writer.rb
+ * but native, allocating one Ruby String.  Drops any caller-supplied
+ * content-length and transfer-encoding headers (mutually exclusive per
+ * RFC 7230 §3.3.3) and always emits "transfer-encoding: chunked\r\n".
+ * Implemented as cbuild_response_head with the body_size = -1 sentinel. */
+VALUE hyperion_build_response_head_chunked(VALUE status, VALUE reason,
+                                           VALUE headers, VALUE keep_alive,
+                                           VALUE date_str) {
+    return cbuild_response_head(Qnil, status, reason, headers,
+                                LL2NUM(-1), keep_alive, date_str);
+}
+
 /* Hyperion::CParser.build_access_line(format, ts, method, path, query,
  *                                     status, duration_ms, remote_addr,
  *                                     http_version) -> String
@@ -1654,4 +1722,8 @@ void Init_hyperion_http(void) {
      * fail-fast crash here would break parser.c entirely. */
     extern void Init_hyperion_h2_codec_glue(void);
     Init_hyperion_h2_codec_glue();
+
+    /* Plan #1 (perf roadmap) — Hyperion::Http::ResponseWriter. */
+    extern void Init_hyperion_response_writer(void);
+    Init_hyperion_response_writer();
 }