hyperion-rb 2.16.4 → 2.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1052090a1cfa42b3ba8807ff239b88f1b5700b0efd2df58a84166b0f754d6496
-  data.tar.gz: '028fa894acb855151cd2901aa1964fb2fd4be68908060401ba64a80d43987bd1'
+  metadata.gz: 3cd6a998da3319e4fa653a2802c6d2114946cfca36dba3c6806f48ada9467e78
+  data.tar.gz: 317fb337740577fddd5c1203d2b41f8f8409d8e3998944c13595ea5db06bd1da
 SHA512:
-  metadata.gz: b080a73c39cbaa284594bda8b2a0dab21f2e737d8d4fd0b6316026bf9fb72b913f3d001117f4291166a6436fd1af0dae11766c47141aa54ca84c759d718c516d
-  data.tar.gz: 24fd2ff23e4ace9e29e9b43ef5c1becaaa1d732e4cff0ac6cafd1fa3fce317029afcf4cc26d3ee5cdad19ccfe7b7252f6da8b3d3a731824a1a10d74f043e4107
+  metadata.gz: ff99796e54e33fcbae1c8e61e30bbde780a8531db28601f86375a2babfe4c7c7edf546a1b7512523524e57ec49ec88487a7c350e6a1c890772474e2dd9b11e70
+  data.tar.gz: '08c49dbb4fe093a9ed4901e841f5504e374faef1fb4b3ff522f698e26afadbea58200f0546a273355113c6d62e3b4353660248f2fc8300d1959547d48460c715'

data/CHANGELOG.md

@@ -1,5 +1,85 @@
 # Changelog
 
+## 2.17.0 — 2026-05-08
+
+### Hot-path bucket: parser value intern + RFC-compliant handle_static prebuilt
+
+Two hot-path optimisations land together. Both are correctness-positive
+(no behavioural change for compliant clients; the second one moves
+`handle_static` from non-RFC-compliant headers to RFC-compliant ones).
+
+#### Parser header-value intern table
+
+`Hyperion::CParser` (`ext/hyperion_http/parser.c`) gains a 64-slot,
+33-seed open-addressed FNV-1a intern table for the highest-frequency
+HTTP/1.1 header *values* (Connection: keep-alive, Accept-Encoding combos,
+common User-Agent strings, localhost / 127.0.0.1, etc.). On every
+`stash_pending_header` call, the materialised value String is hashed and
+probed against the table; on hit, the freshly-allocated `rb_str_new`
+String becomes garbage and the env Hash holds the pre-frozen interned
+VALUE. Net effect: lower GC retention under burst, faster downstream
+identity-based string compares, reduced promote-to-old-gen pressure on
+long-running workers.
+
+- `bench/hello_handle_block.ru` (Row 3): **8727 → 9008 rps median** in
+  isolation (+3.2%), within noise but trending positive.
+- Static path (Row 1) is parser-bypass — intern doesn't apply.
+
+#### `Server.handle_static` — prebuilt wire bytes with Date splice
+
+`handle_static` previously emitted lowercase headers and **no Date
+header**, in violation of RFC 7231 §7.1.1.2 ("An origin server with a
+clock MUST generate a Date header field in all 2xx, 3xx, and 4xx
+responses"). 2.17.0 fixes that:
+
+- The full HTTP/1.1 wire response is built ONCE at registration
+  (status line + `Server: Hyperion` + `Content-Type` + `Content-Length`
+  + `Connection: keep-alive` + 29-byte `Date:` placeholder + body),
+  frozen, and stored on the `StaticEntry` struct alongside the legacy
+  `buffer` field (preserved for back-compat).
+- A new per-second-cached imf-fixdate cache lives in
+  `ext/hyperion_http/page_cache.c` (hand-rolled formatter — `strftime`
+  is locale-dependent and RFC 7231 mandates ASCII English month/day
+  names). Every snapshot site memcpy's the frozen response into a
+  per-write scratch buffer and splices the 29-byte cached date into
+  the placeholder slot AFTER releasing the page lock. The frozen
+  Ruby String is never mutated.
+- `PageCache.register_prebuilt` grows from arity 3 to arity -1 (3 or 4
+  args; the optional 4th is `date_offset`). Pre-2.17 callers (3 args
+  or 4-with-zero) fall through to the unchanged un-spliced fast path.
+- `Connection#serve_static_entry`'s Ruby fallback (used when the C ext
+  is absent — JRuby / TruffleRuby / build failure) mirrors the C path:
+  `prebuilt_keepalive_bytes.dup` + `[]= Time.now.httpdate`.
+
+Bench (3-trial median on `openclaw-vm`, Linux 6.8 / Ruby 3.3.3):
+
+| Row | Workload                                | 2.16.4 | 2.17.0 | Δ |
+|----:|-----------------------------------------|-------:|-------:|--:|
+| 1   | `handle_static` + io_uring (peak)       | 133211 | 127377 | -4.4% (Δ ≈ 80 extra RFC-mandated bytes per response; trial spread 122k–146k = ~19%) |
+| 3   | `Server.handle` block (dynamic)         |   8727 |   9458 | **+8.4%** |
+
+The Row 1 delta is the cost of writing the new mandatory Date / Server /
+Connection bytes. Trade is throughput-for-compliance — Hyperion's pre-2.17
+`handle_static` wasn't a valid HTTP/1.1 origin server.
+
+Captured artefacts:
+- `docs/BENCH_HOTPATH_2026_05_08_before.csv`
+- `docs/BENCH_HOTPATH_2026_05_08_after.csv`
+
+#### Tests
+
+- New: `spec/hyperion/parser_value_intern_spec.rb` (4 examples — intern
+  hits, miss fallback, encoding preservation, wrk User-Agent identity).
+- New: `spec/hyperion/handle_static_prebuilt_spec.rb` (7 examples —
+  wire shape, Date offset, custom content-type, back-compat with
+  legacy `buffer`, end-to-end real-socket request).
+- Modified: `spec/hyperion/direct_route_spec.rb` (two wire-output
+  assertions updated for the new capital-cased headers + Date).
+
+`bin/check` clean (mode=quick, 81 examples, 0 failures); full suite
+1266 examples, 0 failures, 16 pre-existing Linux-only / liburing
+pending on macOS.
+
 ## 2.16.4 — 2026-05-07
 
 ### io_uring hotpath accept fiber: row-19 BOOT-FAIL fix

data/ext/hyperion_http/page_cache.c

@@ -160,6 +160,15 @@ typedef struct hyp_page_s {
                              * (no on-disk file backing — never re-stat,
                              * never invalidate on missing file). */
     char    *content_type;  /* heap-owned, picked at insert time */
+    /* 2.17-A (Hot Path Task 2) — byte offset within `response_buf`
+     * of the first byte of a 29-byte HTTP `Date:` placeholder ('X' run).
+     * Zero means "no placeholder; do not splice". When non-zero, every
+     * snapshot site overwrites the 29 bytes at this offset in the
+     * stack/heap snapshot copy with the per-second-cached imf-fixdate
+     * string before the kernel write fires. The `response_buf` itself
+     * is never mutated (it is shared across concurrent reads under the
+     * page-cache rwlock). */
+    size_t   date_offset;
 } hyp_page_t;
 
 typedef struct hyp_page_slot_s {
@@ -254,6 +263,117 @@ static double hyp_pc_now(void) {
     return (double)tv.tv_sec + (double)tv.tv_usec / 1.0e6;
 }
 
+/* ============================================================
+ * 2.17-A (Hot Path Task 2) — per-second-cached HTTP `Date:` header.
+ *
+ * The wire format is RFC 7231 imf-fixdate:
+ *   "Sun, 06 Nov 1994 08:49:37 GMT"
+ * Always exactly 29 bytes, ASCII, no trailing NUL written into the
+ * splice slot — the slot lives in the middle of a frozen response
+ * buffer and the surrounding bytes (CRLF + remaining headers + body)
+ * are already correct.
+ *
+ * Refresh strategy: lazy, tied to wall-clock seconds.  Every call to
+ * `hyp_pc_cached_date` checks whether the cached `time_t` matches
+ * `time(NULL)`; on miss, the cache is rebuilt from `gmtime_r` under a
+ * dedicated mutex (NOT `hyp_pc_lock` — splice happens AFTER the page
+ * lock has been released, so we mustn't reacquire the page lock for
+ * the date refresh).  Concurrent rebuilds race to write the same 29
+ * bytes; the result is bit-identical so the race is benign — readers
+ * either see the previous second's value (already-stale-by-one-second
+ * is RFC-acceptable) or the new one.
+ *
+ * The cached buffer is sized 32 to leave room for an aligned read on
+ * older toolchains that might over-read past `[28]`; we hand out only
+ * the first 29 bytes via `hyp_pc_cached_date_copy`. */
+#define HYP_PC_DATE_LEN 29
+
+static char            hyp_pc_cached_date[32];
+static time_t          hyp_pc_cached_date_sec = 0;
+static pthread_mutex_t hyp_pc_date_lock       = PTHREAD_MUTEX_INITIALIZER;
+
+/* Day-of-week and month tables match RFC 7231 §7.1.1.1 imf-fixdate. */
+static const char *const hyp_pc_dow[7] = {
+    "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"
+};
+static const char *const hyp_pc_mon[12] = {
+    "Jan", "Feb", "Mar", "Apr", "May", "Jun",
+    "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
+};
+
+/* Format `t` as RFC 7231 imf-fixdate into `dst` (29 bytes, no NUL).
+ * Hand-rolled to avoid `strftime`'s locale-dependent output (locale-
+ * aware libcs would spell the month / day in non-ASCII for some
+ * locales — RFC 7231 mandates English).  Branch-free except for the
+ * gmtime_r itself. */
+static void hyp_pc_format_imf_fixdate(time_t t, char *dst) {
+    struct tm tm;
+    if (gmtime_r(&t, &tm) == NULL) {
+        /* Fall back to a known-good zero date; should never happen
+         * for a sane wall clock. */
+        memcpy(dst, "Thu, 01 Jan 1970 00:00:00 GMT", HYP_PC_DATE_LEN);
+        return;
+    }
+    int year = tm.tm_year + 1900;
+    int dow  = tm.tm_wday  & 7;       /* defensive: mask to [0,7) */
+    int mon  = tm.tm_mon   % 12;      /* defensive */
+    if (dow >= 7) dow = 0;
+    if (mon < 0) mon = 0;
+
+    /* "Sun, 06 Nov 1994 08:49:37 GMT" */
+    memcpy(dst,      hyp_pc_dow[dow], 3);
+    dst[3]  = ',';
+    dst[4]  = ' ';
+    dst[5]  = (char)('0' + (tm.tm_mday / 10));
+    dst[6]  = (char)('0' + (tm.tm_mday % 10));
+    dst[7]  = ' ';
+    memcpy(dst + 8,  hyp_pc_mon[mon], 3);
+    dst[11] = ' ';
+    dst[12] = (char)('0' + ((year / 1000) % 10));
+    dst[13] = (char)('0' + ((year / 100)  % 10));
+    dst[14] = (char)('0' + ((year / 10)   % 10));
+    dst[15] = (char)('0' + (year          % 10));
+    dst[16] = ' ';
+    dst[17] = (char)('0' + (tm.tm_hour / 10));
+    dst[18] = (char)('0' + (tm.tm_hour % 10));
+    dst[19] = ':';
+    dst[20] = (char)('0' + (tm.tm_min  / 10));
+    dst[21] = (char)('0' + (tm.tm_min  % 10));
+    dst[22] = ':';
+    dst[23] = (char)('0' + (tm.tm_sec  / 10));
+    dst[24] = (char)('0' + (tm.tm_sec  % 10));
+    dst[25] = ' ';
+    dst[26] = 'G';
+    dst[27] = 'M';
+    dst[28] = 'T';
+}
+
+/* Copy the per-second-cached imf-fixdate into `dst` (29 bytes).
+ * Refreshes the cache iff the wall-clock second has advanced since the
+ * last refresh.  Safe to call without `hyp_pc_lock`. */
+static void hyp_pc_cached_date_copy(char *dst) {
+    time_t now = time(NULL);
+    pthread_mutex_lock(&hyp_pc_date_lock);
+    if (now != hyp_pc_cached_date_sec) {
+        hyp_pc_format_imf_fixdate(now, hyp_pc_cached_date);
+        hyp_pc_cached_date_sec = now;
+    }
+    memcpy(dst, hyp_pc_cached_date, HYP_PC_DATE_LEN);
+    pthread_mutex_unlock(&hyp_pc_date_lock);
+}
+
+/* Splice the per-second-cached imf-fixdate into `snapshot` at
+ * `date_offset`.  No-op when `date_offset == 0` (entry has no
+ * placeholder — pre-2.17 register_prebuilt callers).  Bounds-checks
+ * against `snap_len` so a corrupted header layout never overruns the
+ * snapshot buffer. */
+static inline void hyp_pc_splice_date(char *snapshot, size_t snap_len,
+                                      size_t date_offset) {
+    if (date_offset == 0) return;
+    if (date_offset + HYP_PC_DATE_LEN > snap_len) return;
+    hyp_pc_cached_date_copy(snapshot + date_offset);
+}
+
 /* FNV-1a 64-bit. Stable, cheap, branchless on the hot path; not a
  * cryptographic hash but the cache only stores trusted operator paths. */
 static uint64_t hyp_pc_hash(const char *key, size_t len) {
@@ -694,6 +814,7 @@ static VALUE rb_pc_write_to(VALUE self, VALUE socket_io, VALUE rb_path) {
         return sym_missing_pc;
     }
     size_t resp_len = slot->page->response_len;
+    size_t date_off = slot->page->date_offset;
     char  *snapshot = (char *)malloc(resp_len);
     if (snapshot == NULL) {
         pthread_mutex_unlock(&hyp_pc_lock);
@@ -702,6 +823,11 @@ static VALUE rb_pc_write_to(VALUE self, VALUE socket_io, VALUE rb_path) {
     }
     memcpy(snapshot, slot->page->response_buf, resp_len);
     pthread_mutex_unlock(&hyp_pc_lock);
+    /* 2.17-A — overwrite the 29-byte Date placeholder in the snapshot
+     * (NEVER the page's frozen response_buf) with the per-second-cached
+     * imf-fixdate string. No-op when the entry was registered without
+     * a placeholder (date_off == 0). */
+    hyp_pc_splice_date(snapshot, resp_len, date_off);
 
     hyp_pc_write_args_t args;
     args.fd    = fd;
@@ -721,7 +847,7 @@ static VALUE rb_pc_write_to(VALUE self, VALUE socket_io, VALUE rb_path) {
     return SSIZET2NUM(args.total);
 }
 
-/* PageCache.register_prebuilt(path, response_bytes, body_len) -> Integer
+/* PageCache.register_prebuilt(path, response_bytes, body_len, date_offset = 0) -> Integer
  *
  * 2.10-F — register a fully prebuilt HTTP response under a route path
  * (e.g. `/health`).  Unlike `cache_file`, the entry has NO on-disk
@@ -730,16 +856,37 @@ static VALUE rb_pc_write_to(VALUE self, VALUE socket_io, VALUE rb_path) {
  * starts inside `response_bytes` so HEAD requests can write the
  * headers-only prefix.
  *
- * `response_bytes.bytesize` MUST be >= `body_len`.  Returns the
- * stored response byte count on success.
+ * 2.17-A (Hot Path Task 2) — `date_offset` is an OPTIONAL fourth
+ * argument: when non-zero, it is the byte offset within
+ * `response_bytes` of a 29-byte `XXX...` placeholder reserved for
+ * the HTTP `Date:` header.  The C splice helper overwrites those 29
+ * bytes in a per-write SCRATCH copy with the per-second-cached
+ * imf-fixdate string before each kernel write — the registered
+ * `response_bytes` is never mutated.  Pre-2.17 callers that pass
+ * three arguments (or pass 0 for the fourth) get the un-spliced
+ * behaviour they had before.
+ *
+ * `response_bytes.bytesize` MUST be >= `body_len`.  When
+ * `date_offset != 0` it must satisfy
+ * `date_offset + 29 <= response_bytes.bytesize` so the splice never
+ * runs off the end of the buffer.  Returns the stored response
+ * byte count on success.
  *
  * Used by `Hyperion::Server.handle_static` to fold the prebuilt
  * static-route response into the C fast path so the request hot
  * path is one hash lookup + one `write()` syscall, fully outside
  * Ruby method dispatch. */
-static VALUE rb_pc_register_prebuilt(VALUE self, VALUE rb_path,
-                                     VALUE rb_response, VALUE rb_body_len) {
+static VALUE rb_pc_register_prebuilt(int argc, VALUE *argv, VALUE self) {
     (void)self;
+    if (argc < 3 || argc > 4) {
+        rb_raise(rb_eArgError,
+                 "wrong number of arguments (given %d, expected 3..4)", argc);
+    }
+    VALUE rb_path     = argv[0];
+    VALUE rb_response = argv[1];
+    VALUE rb_body_len = argv[2];
+    VALUE rb_date_off = (argc == 4) ? argv[3] : INT2FIX(0);
+
     Check_Type(rb_path, T_STRING);
     Check_Type(rb_response, T_STRING);
 
@@ -761,6 +908,16 @@ static VALUE rb_pc_register_prebuilt(VALUE self, VALUE rb_path,
                  "body_len (%zu) must be <= response_bytes.bytesize (%zu)",
                  body_len, resp_len);
     }
+    long date_off_signed = NUM2LONG(rb_date_off);
+    if (date_off_signed < 0) {
+        rb_raise(rb_eArgError, "date_offset must be >= 0");
+    }
+    size_t date_off = (size_t)date_off_signed;
+    if (date_off != 0 && date_off + HYP_PC_DATE_LEN > resp_len) {
+        rb_raise(rb_eArgError,
+                 "date_offset (%zu) + 29 must be <= response_bytes.bytesize (%zu)",
+                 date_off, resp_len);
+    }
 
     hyp_page_t *page = (hyp_page_t *)calloc(1, sizeof(*page));
     if (page == NULL) {
@@ -802,6 +959,7 @@ static VALUE rb_pc_register_prebuilt(VALUE self, VALUE rb_path,
     page->last_check   = hyp_pc_now();
     page->immutable    = 1;
     page->prebuilt     = 1;
+    page->date_offset  = date_off;
 
     uint64_t h = hyp_pc_hash(path, path_len);
     pthread_mutex_lock(&hyp_pc_lock);
@@ -887,6 +1045,7 @@ static VALUE rb_pc_serve_request(VALUE self, VALUE socket_io,
     size_t write_len = (kind == HYP_PC_METHOD_HEAD)
                            ? slot->page->headers_len
                            : slot->page->response_len;
+    size_t date_off  = slot->page->date_offset;
     char  *snapshot  = (char *)malloc(write_len);
     if (snapshot == NULL) {
         pthread_mutex_unlock(&hyp_pc_lock);
@@ -895,6 +1054,11 @@ static VALUE rb_pc_serve_request(VALUE self, VALUE socket_io,
     }
     memcpy(snapshot, slot->page->response_buf, write_len);
     pthread_mutex_unlock(&hyp_pc_lock);
+    /* 2.17-A — splice the per-second-cached imf-fixdate into the
+     * snapshot's Date placeholder (when the entry has one).  HEAD
+     * write_len equals headers_len, so a Date placeholder placed
+     * inside the headers span is still in range. */
+    hyp_pc_splice_date(snapshot, write_len, date_off);
 
     hyp_pc_write_args_t args;
     args.fd    = fd;
@@ -1920,6 +2084,7 @@ static long hyp_cl_serve_connection(int client_fd, int *handed_off) {
             size_t write_len = (kind == HYP_PC_METHOD_HEAD)
                                    ? slot->page->headers_len
                                    : slot->page->response_len;
+            size_t date_off  = slot->page->date_offset;
             char *snapshot = (char *)malloc(write_len);
             if (snapshot == NULL) {
                 pthread_mutex_unlock(&hyp_pc_lock);
@@ -1930,6 +2095,10 @@ static long hyp_cl_serve_connection(int client_fd, int *handed_off) {
             }
             memcpy(snapshot, slot->page->response_buf, write_len);
             pthread_mutex_unlock(&hyp_pc_lock);
+            /* 2.17-A — splice the per-second-cached imf-fixdate into
+             * the snapshot's Date placeholder before the kernel write.
+             * No-op for entries registered without a placeholder. */
+            hyp_pc_splice_date(snapshot, write_len, date_off);
 
             hyp_pc_write_args_t wargs;
             wargs.fd    = client_fd;
@@ -2484,6 +2653,7 @@ char *pc_internal_snapshot_response(const char *path, size_t path_len,
     size_t write_len = (kind == PC_INTERNAL_METHOD_HEAD)
                            ? slot->page->headers_len
                            : slot->page->response_len;
+    size_t date_off  = slot->page->date_offset;
     char *snapshot = (char *)malloc(write_len);
     if (snapshot == NULL) {
         pthread_mutex_unlock(&hyp_pc_lock);
@@ -2491,6 +2661,11 @@ char *pc_internal_snapshot_response(const char *path, size_t path_len,
     }
     memcpy(snapshot, slot->page->response_buf, write_len);
     pthread_mutex_unlock(&hyp_pc_lock);
+    /* 2.17-A — splice the per-second-cached imf-fixdate into the
+     * Date placeholder before handing the snapshot to io_uring (the
+     * kernel reads the bytes asynchronously, so the splice MUST land
+     * before the SQE is submitted). */
+    hyp_pc_splice_date(snapshot, write_len, date_off);
     *out_len = write_len;
     return snapshot;
 }
@@ -2576,8 +2751,10 @@ void Init_hyperion_page_cache(void) {
                                rb_pc_auto_threshold, 0);
     rb_define_singleton_method(rb_mHyperionHttpPageCache, "max_key_len",
                                rb_pc_max_key_len, 0);
+    /* 2.17-A — variable arity: 3-arg legacy form, 4-arg form adds
+     * `date_offset` for the imf-fixdate splice slot. */
     rb_define_singleton_method(rb_mHyperionHttpPageCache, "register_prebuilt",
-                               rb_pc_register_prebuilt, 3);
+                               rb_pc_register_prebuilt, -1);
     rb_define_singleton_method(rb_mHyperionHttpPageCache, "serve_request",
                                rb_pc_serve_request, 3);
     /* 2.12-C — connection lifecycle in C. */

data/ext/hyperion_http/parser.c

@@ -153,6 +153,117 @@ typedef struct {
 static VALUE rb_kEMPTY_STR;          /* frozen empty ASCII-8BIT String */
 static VALUE rb_kHTTP_1_1;           /* frozen "HTTP/1.1" String */
 
+/* Phase HotPath-1 (2.17.0) — intern table for the highest-frequency HTTP/1.1
+ * *value* tokens (not header names — those are interned via the
+ * PREINTERNED_HEADERS table above). On a typical wrk-shaped benchmark, the
+ * VALUE side of every header (Host, User-Agent, Accept, Connection,
+ * Accept-Encoding, etc.) is identical across every request on a keep-alive
+ * connection. Without interning, each request rb_str_new's a fresh String
+ * for every value — 6–10 allocations per request, all destined for the
+ * young GC. With interning, stash_pending_header's hash check returns the
+ * pre-frozen VALUE for known values; the freshly-allocated String becomes
+ * unreferenced garbage (collected at next minor GC) and the env Hash holds
+ * a single shared identity across all requests. Net wins: lower GC retention
+ * under burst, faster string compares downstream (identity), reduced
+ * promote-to-old-gen pressure on long-running workers.
+ *
+ * Layout: open-addressed table sized to 64 slots (power of 2; load factor
+ * <0.5 with 33 seeds). Probing capped at 8 to keep cache-friendly.
+ * Lookup is FNV-1a on the byte range; on hit we return the frozen VALUE,
+ * on miss we return Qundef and the caller falls through to the original
+ * (unmodified) String. The table is seeded once at extension init from a
+ * static literal list — no growth, no eviction, no thread synchronisation.
+ */
+#define HYP_VALUE_INTERN_TABLE_SIZE 64u  /* power of 2 */
+#define HYP_VALUE_INTERN_PROBE_MAX  8
+#define HYP_VALUE_INTERN_MAX_LEN    96u  /* skip lookup for values > this */
+
+typedef struct {
+    uint64_t fnv1a;
+    uint32_t len;
+    VALUE    str;
+} hyp_value_intern_entry_t;
+
+static hyp_value_intern_entry_t hyp_value_intern_tbl[HYP_VALUE_INTERN_TABLE_SIZE];
+
+static const char *const hyp_value_intern_seed[] = {
+    /* Connection */
+    "keep-alive", "close", "Keep-Alive", "Upgrade", "upgrade",
+    /* Accept-Encoding */
+    "gzip, deflate", "gzip, deflate, br", "gzip, deflate, br, zstd",
+    "identity", "gzip", "deflate", "br", "*",
+    /* Accept */
+    "*/*", "text/html", "application/json", "text/plain",
+    "application/x-www-form-urlencoded", "text/event-stream",
+    /* Accept-Language */
+    "en-US,en;q=0.9", "en-US", "en",
+    /* User-Agent — synthetic / bench clients */
+    "Mozilla/5.0 (compatible; wrk/4.2.0)",
+    "wrk/4.2.0",
+    "curl/8.4.0", "curl/8.5.0", "curl/8.6.0",
+    /* Host — local bench */
+    "localhost", "127.0.0.1", "0.0.0.0",
+    /* Cache-Control */
+    "no-cache", "no-store", "max-age=0",
+    /* Misc */
+    "trailers", "websocket", "h2c",
+};
+#define HYP_VALUE_INTERN_SEED_N \
+    (sizeof(hyp_value_intern_seed) / sizeof(hyp_value_intern_seed[0]))
+
+static inline uint64_t hyp_fnv1a(const char *bytes, uint32_t len) {
+    uint64_t h = 0xcbf29ce484222325ULL;
+    for (uint32_t i = 0; i < len; i++) {
+        h ^= (uint8_t)bytes[i];
+        h *= 0x100000001b3ULL;
+    }
+    return h;
+}
+
+static inline VALUE hyp_intern_lookup(const char *bytes, uint32_t len) {
+    if (len == 0 || len > HYP_VALUE_INTERN_MAX_LEN) return Qundef;
+    uint64_t h = hyp_fnv1a(bytes, len);
+    uint32_t mask = HYP_VALUE_INTERN_TABLE_SIZE - 1u;
+    uint32_t idx  = (uint32_t)h & mask;
+    for (int probe = 0; probe < HYP_VALUE_INTERN_PROBE_MAX; probe++) {
+        hyp_value_intern_entry_t *e =
+            &hyp_value_intern_tbl[(idx + (uint32_t)probe) & mask];
+        if (e->str == 0) return Qundef;
+        if (e->fnv1a == h && e->len == len &&
+            memcmp(RSTRING_PTR(e->str), bytes, len) == 0) {
+            return e->str;
+        }
+    }
+    return Qundef;
+}
+
+static void hyp_value_intern_seed_all(void) {
+    memset(hyp_value_intern_tbl, 0, sizeof(hyp_value_intern_tbl));
+    uint32_t mask = HYP_VALUE_INTERN_TABLE_SIZE - 1u;
+    for (size_t i = 0; i < HYP_VALUE_INTERN_SEED_N; i++) {
+        const char *s = hyp_value_intern_seed[i];
+        uint32_t len  = (uint32_t)strlen(s);
+        if (len == 0 || len > HYP_VALUE_INTERN_MAX_LEN) continue;
+        uint64_t h    = hyp_fnv1a(s, len);
+        uint32_t idx  = (uint32_t)h & mask;
+        for (int probe = 0; probe < HYP_VALUE_INTERN_PROBE_MAX; probe++) {
+            hyp_value_intern_entry_t *e =
+                &hyp_value_intern_tbl[(idx + (uint32_t)probe) & mask];
+            if (e->str == 0) {
+                /* Match the encoding of values produced by rb_str_new
+                 * (ASCII-8BIT) so identity comparisons downstream don't
+                 * fail on encoding mismatch. */
+                VALUE v = rb_obj_freeze(rb_str_new(s, (long)len));
+                rb_global_variable(&e->str);  /* GC root */
+                e->str   = v;
+                e->fnv1a = h;
+                e->len   = len;
+                break;
+            }
+        }
+    }
+}
+
 static void state_init(parser_state_t *s) {
     s->method                    = Qnil;
     s->path                      = Qnil;  /* allocated in on_url first call */
@@ -216,6 +327,15 @@ static void stash_pending_header(parser_state_t *s) {
             key = rb_funcall(s->current_header_name, id_downcase, 0);
         }
         VALUE val = NIL_P(s->current_header_value) ? rb_kEMPTY_STR : s->current_header_value;
+        /* Phase HotPath-1 (2.17.0): intern common header values so identical
+         * values across keep-alive requests share one frozen VALUE. The
+         * freshly-allocated `s->current_header_value` becomes garbage on
+         * intern hit. */
+        if (val != rb_kEMPTY_STR) {
+            long val_len = RSTRING_LEN(val);
+            VALUE interned = hyp_intern_lookup(RSTRING_PTR(val), (uint32_t)val_len);
+            if (interned != Qundef) val = interned;
+        }
         rb_hash_aset(s->headers, key, val);
         s->current_header_name  = Qnil;
         s->current_header_value = Qnil;
@@ -1670,6 +1790,13 @@ void Init_hyperion_http(void) {
     rb_obj_freeze(rb_aHeaderTable);
     rb_define_const(rb_cCParser, "PREINTERNED_HEADERS", rb_aHeaderTable);
 
+    /* Phase HotPath-1 (2.17.0): seed the header-value intern table. See
+     * the long comment at the table declaration. Must run after the
+     * encoding registry is up (Init_hyperion_parser is called by
+     * Init_hyperion_http after rb_define_module) so rb_str_new finds
+     * ASCII-8BIT. */
+    hyp_value_intern_seed_all();
+
     /* 2.13-B — status-line, header-key, header-line caches used by
      * cbuild_response_head. The status-line table is fixed-size (no GC
      * concerns; bytes are .rodata). The two header caches are

data/lib/hyperion/connection.rb

@@ -670,20 +670,46 @@ module Hyperion
 
     # 2.10-F — call into the C ext when available, else fall back to
     # the 2.10-D Ruby `socket.write` path.  Returns bytes written.
+    #
+    # 2.17-A — when the C ext is unavailable (JRuby / TruffleRuby /
+    # build failure) AND the entry carries the new keep-alive prebuilt
+    # bytes, splice the per-second-cached httpdate into a per-write
+    # scratch String and write THAT — so the wire output shape is
+    # identical to the C-loop path even on the slow Ruby fallback.
+    # The frozen `prebuilt_keepalive_bytes` itself is never mutated;
+    # `String#dup` copies it onto the heap so `[]=` is safe.
     def serve_static_entry(socket, request, entry)
       if defined?(::Hyperion::Http::PageCache) &&
          ::Hyperion::Http::PageCache.respond_to?(:serve_request)
         result = ::Hyperion::Http::PageCache.serve_request(socket, request.method, entry.path)
         return result.last if result.is_a?(Array) && result.first == :ok
       end
-      # Fallback: Ruby write of the full buffer (or headers-only on HEAD).
-      bytes = if request.method == 'HEAD' && entry.headers_bytesize < entry.buffer.bytesize
-                entry.buffer.byteslice(0, entry.headers_bytesize)
-              else
-                entry.buffer
-              end
-      socket.write(bytes)
+      socket.write(static_entry_fallback_bytes(request, entry))
+    end
+
+    # 2.17-A — build the wire bytes for the Ruby fallback path. When
+    # the entry carries `prebuilt_keepalive_bytes` + `prebuilt_date_offset`
+    # (registered post-2.17), use those bytes with the date spliced in.
+    # Otherwise fall through to the legacy `entry.buffer` (lowercase
+    # headers, no Date) — this path keeps pre-2.17 callers that
+    # constructed StaticEntry directly working unchanged.
+    def static_entry_fallback_bytes(request, entry)
+      if entry.prebuilt_keepalive_bytes && entry.prebuilt_date_offset.to_i.positive?
+        bytes = entry.prebuilt_keepalive_bytes.dup
+        bytes[entry.prebuilt_date_offset, 29] = Time.now.httpdate
+        return bytes if request.method != 'HEAD'
+
+        head_end = bytes.index("\r\n\r\n")
+        return head_end ? bytes.byteslice(0, head_end + 4) : bytes
+      end
+
+      if request.method == 'HEAD' && entry.headers_bytesize < entry.buffer.bytesize
+        entry.buffer.byteslice(0, entry.headers_bytesize)
+      else
+        entry.buffer
+      end
     end
+    private :static_entry_fallback_bytes
 
     # 2.10-D — write a direct-route response.  Returns the status
     # code that was written (so `dispatch_direct!` can bump the

data/lib/hyperion/server/route_table.rb

@@ -59,7 +59,28 @@ module Hyperion
       # on HEAD too, which is RFC-correct (HEAD MAY include the body
       # so long as Content-Length matches; the spec only forbids the
       # SERVER from sending body bytes the client didn't ask for).
-      StaticEntry = Struct.new(:method, :path, :buffer, :headers_len) do
+      #
+      # 2.17-A (Hot Path Task 2) adds two more fields so the C-loop
+      # writer can mem-splice a per-second-cached HTTP `Date:` header
+      # into a pre-built keep-alive response without rebuilding it
+      # from scratch:
+      #   * `prebuilt_keepalive_bytes` — frozen ASCII-8BIT String of
+      #     the full HTTP/1.1 wire response (status line + Server +
+      #     Content-Type + Content-Length + Connection: keep-alive +
+      #     Date placeholder + body) with a 29-byte 'X' run reserved
+      #     at `prebuilt_date_offset`.  The placeholder is overwritten
+      #     in a per-write scratch buffer (NEVER in this frozen
+      #     String) by the C splice helper before the syscall fires.
+      #   * `prebuilt_date_offset` — Integer byte offset of the first
+      #     placeholder byte within `prebuilt_keepalive_bytes`.  Zero
+      #     means "no Date placeholder; do not splice".  29 bytes is
+      #     the canonical RFC 7231 imf-fixdate length.
+      # Existing callers that construct StaticEntry with 3 or 4 args
+      # see nil for these new fields and the C side falls through to
+      # the un-spliced fast path it has used since 2.10-F.
+      StaticEntry = Struct.new(:method, :path, :buffer, :headers_len,
+                                :prebuilt_keepalive_bytes,
+                                :prebuilt_date_offset) do
         # Returns the pre-built response bytes ready for one
         # `socket.write` call.  Always frozen.
         def response_bytes

data/lib/hyperion/server.rb

@@ -136,10 +136,23 @@ module Hyperion
       head.force_encoding(Encoding::ASCII_8BIT)
       buffer = (head + body).freeze
 
+      # 2.17-A (Hot Path Task 2) — pre-build the keep-alive wire bytes
+      # with a 29-byte Date placeholder so the C-loop writer can splice
+      # the per-second-cached httpdate string in without rebuilding the
+      # head from scratch every request.  Returned as `[bytes, offset]`
+      # — `offset` is the byte index of the first placeholder byte.
+      prebuilt_ka_bytes, date_offset =
+        build_static_wire_bytes(body, content_type: content_type, server_string: 'Hyperion')
+
       method_key = method_sym.to_s.upcase.to_sym
       # 2.10-F — record the headers prefix length on the StaticEntry
       # struct so HEAD-method writes can serve a headers-only prefix.
-      entry = RouteTable::StaticEntry.new(method_key, path.dup.freeze, buffer, head.bytesize).freeze
+      # 2.17-A — also stash the keep-alive prebuilt bytes + Date offset
+      # so the C splice helper (or the Ruby fallback in
+      # Connection#serve_static_entry) can stamp the cached date in
+      # before each write.
+      entry = RouteTable::StaticEntry.new(method_key, path.dup.freeze, buffer, head.bytesize,
+                                           prebuilt_ka_bytes, date_offset).freeze
       # 2.10-F — register the entry DIRECTLY (StaticEntry responds to
       # `#call`) instead of wrapping it in a closure, so the dispatch
       # path can branch on `is_a?(StaticEntry)` BEFORE invoking the
@@ -152,17 +165,58 @@ module Hyperion
       # MUST also answer HEAD with the same headers).  No-op on a
       # POST/PUT/etc. registration — those don't get a HEAD twin.
       route_table.register(:HEAD, path, entry) if method_key == :GET
-      # 2.10-F — fold the prebuilt response into the C-side PageCache so
-      # `PageCache.serve_request` can write it without ever crossing
-      # back into Ruby.  Best-effort: if the C ext isn't available
-      # (JRuby / TruffleRuby), the dispatcher silently falls back to
-      # the Ruby `socket.write` path that's been there since 2.10-D.
+      # 2.17-A — fold the keep-alive prebuilt bytes (with Date placeholder)
+      # into the C-side PageCache so `PageCache.serve_request` and the
+      # C accept loop both serve the new shape.  The 4-arg
+      # `register_prebuilt` form (introduced in 2.17-A) records the
+      # Date offset on the C-side `hyp_page_t` so every snapshot
+      # site splices the cached date before writing.  Best-effort:
+      # the C ext may be absent on JRuby / TruffleRuby — the
+      # dispatcher silently falls back to the Ruby `socket.write`
+      # path that's been there since 2.10-D.
       if defined?(::Hyperion::Http::PageCache) && ::Hyperion::Http::PageCache.respond_to?(:register_prebuilt)
-        ::Hyperion::Http::PageCache.register_prebuilt(path, buffer, body.bytesize)
+        ::Hyperion::Http::PageCache.register_prebuilt(path, prebuilt_ka_bytes, body.bytesize, date_offset)
       end
       entry
     end
 
+    # 2.17-A (Hot Path Task 2) — assemble the prebuilt keep-alive
+    # wire bytes for a static route registered via `handle_static`.
+    # Returns `[frozen_bytes, date_offset]`:
+    #   * `frozen_bytes` — ASCII-8BIT, frozen String of the full
+    #     HTTP/1.1 response (status line + Server + Content-Type +
+    #     Content-Length + Connection: keep-alive + Date placeholder
+    #     + CRLFCRLF + body).  The Date placeholder is a 29-byte 'X'
+    #     run that the C splice helper overwrites in a per-write
+    #     scratch buffer (the frozen String itself is NEVER mutated).
+    #   * `date_offset` — Integer index of the first placeholder
+    #     byte within `frozen_bytes`.  29 bytes is the canonical RFC
+    #     7231 imf-fixdate length (`Sun, 06 Nov 1994 08:49:37 GMT`).
+    #
+    # Header order is fixed on purpose — the C splice helper relies
+    # on the offset being stable across requests; placing Date last
+    # keeps the offset arithmetic trivial regardless of body length
+    # variations between routes.  Headers are capitalized in the
+    # canonical RFC 7230 §3.2 form (case-insensitive but
+    # conventionally capitalized) so the wire output matches what
+    # CDN / proxy logs expect.
+    def self.build_static_wire_bytes(body, content_type:, server_string:)
+      placeholder = 'X' * 29
+      head_prefix = +"HTTP/1.1 200 OK\r\n" \
+                     "Server: #{server_string}\r\n" \
+                     "Content-Type: #{content_type}\r\n" \
+                     "Content-Length: #{body.bytesize}\r\n" \
+                     "Connection: keep-alive\r\n" \
+                     "Date: "
+      head_prefix.force_encoding(Encoding::ASCII_8BIT)
+      date_offset = head_prefix.bytesize
+      head = head_prefix + placeholder + "\r\n\r\n"
+      head.force_encoding(Encoding::ASCII_8BIT)
+      bytes = (head + body).b.freeze
+      [bytes, date_offset]
+    end
+    private_class_method :build_static_wire_bytes
+
     # 1.7.0 added kwargs (all default to current behaviour):
     #   * `runtime:`             — `Hyperion::Runtime` instance (default
     #                               `Runtime.default`). Threaded through to

data/lib/hyperion/version.rb

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

metadata

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