hyperion-rb 1.6.2 → 2.10.1

data/ext/hyperion_http/parser.c

@@ -1,5 +1,6 @@
 #include <ruby.h>
 #include <ruby/encoding.h>
+#include <ruby/st.h>
 #include <string.h>
 #include "llhttp.h"
 
@@ -35,6 +36,90 @@ static ID id_http_version_kw;
 static ID id_headers_kw;
 static ID id_body_kw;
 
+/* Phase 3a (1.7.1) — pre-built frozen Strings for the fixed Rack env keys
+ * we set on every request (REQUEST_METHOD, PATH_INFO, QUERY_STRING,
+ * HTTP_VERSION, SERVER_PROTOCOL) plus the two non-HTTP_ promotions
+ * (CONTENT_TYPE, CONTENT_LENGTH). Allocated once at extension load and
+ * reused as hash keys forever — saves an alloc per key per request. */
+static VALUE rb_kREQUEST_METHOD;
+static VALUE rb_kPATH_INFO;
+static VALUE rb_kQUERY_STRING;
+static VALUE rb_kHTTP_VERSION;
+static VALUE rb_kSERVER_PROTOCOL;
+static VALUE rb_kCONTENT_TYPE;
+static VALUE rb_kCONTENT_LENGTH;
+
+/* 2.4-B (S2): pre-interned frozen Strings used by on_headers_complete
+ * for the smuggling-defense lookups. Pre-2.4-B these were freshly
+ * allocated via rb_str_new_cstr on every parse(); promoting them to
+ * static globals removes 2 String allocations per parse. */
+static VALUE rb_kHCONTENT_LENGTH_LC;
+static VALUE rb_kHTRANSFER_ENCODING_LC;
+
+/* Request ivar IDs, looked up once at extension load. Request is a frozen
+ * struct-like value so reading via rb_ivar_get is safe — no dispatch cost,
+ * no method-cache invalidation. */
+static ID id_iv_method;
+static ID id_iv_path;
+static ID id_iv_query_string;
+static ID id_iv_http_version;
+static ID id_iv_headers;
+
+/* Phase 2c (1.7.1) — pre-interned frozen lowercase keys for the 30 most
+ * common production HTTP request headers. When llhttp finishes a header
+ * the parser's `stash_pending_header` does a case-insensitive O(N=30)
+ * scan against this table; on hit, it stores the pre-frozen lowercase
+ * VALUE as the hash key instead of allocating a fresh `name.downcase`
+ * String per request. The table doubles as an exposure point for the
+ * Ruby-side adapter so HTTP_KEY_CACHE can widen to the same 30 names.
+ *
+ * Memory layout: a flat array of strings, even indices are lowercase
+ * names, odd indices are the corresponding "HTTP_<UPCASED_UNDERSCORED>"
+ * Rack env keys. Both halves are deeply frozen at extension load.
+ */
+#define HEADER_TABLE_PAIRS 30
+static VALUE rb_aHeaderTable;          /* Array(2*30) — name+http key pairs */
+static const char *header_table_lc[HEADER_TABLE_PAIRS] = {
+    "host",             "user-agent",       "accept",         "accept-encoding",
+    "accept-language",  "cache-control",    "connection",     "cookie",
+    "content-length",   "content-type",     "authorization",  "referer",
+    "origin",           "upgrade",          "x-forwarded-for","x-forwarded-proto",
+    "x-forwarded-host", "x-real-ip",        "x-request-id",   "if-none-match",
+    "if-modified-since","if-match",         "etag",           "range",
+    "pragma",           "dnt",              "sec-ch-ua",      "sec-fetch-dest",
+    "sec-fetch-mode",   "sec-fetch-site"
+};
+static const char *header_table_http[HEADER_TABLE_PAIRS] = {
+    "HTTP_HOST",            "HTTP_USER_AGENT",     "HTTP_ACCEPT",         "HTTP_ACCEPT_ENCODING",
+    "HTTP_ACCEPT_LANGUAGE", "HTTP_CACHE_CONTROL",  "HTTP_CONNECTION",     "HTTP_COOKIE",
+    "HTTP_CONTENT_LENGTH",  "HTTP_CONTENT_TYPE",   "HTTP_AUTHORIZATION",  "HTTP_REFERER",
+    "HTTP_ORIGIN",          "HTTP_UPGRADE",        "HTTP_X_FORWARDED_FOR","HTTP_X_FORWARDED_PROTO",
+    "HTTP_X_FORWARDED_HOST","HTTP_X_REAL_IP",      "HTTP_X_REQUEST_ID",   "HTTP_IF_NONE_MATCH",
+    "HTTP_IF_MODIFIED_SINCE","HTTP_IF_MATCH",      "HTTP_ETAG",           "HTTP_RANGE",
+    "HTTP_PRAGMA",          "HTTP_DNT",            "HTTP_SEC_CH_UA",      "HTTP_SEC_FETCH_DEST",
+    "HTTP_SEC_FETCH_MODE",  "HTTP_SEC_FETCH_SITE"
+};
+static VALUE header_table_lc_v[HEADER_TABLE_PAIRS];   /* parallel cached frozen Strings */
+static long  header_table_lc_len[HEADER_TABLE_PAIRS]; /* cached strlen for fast compare */
+
+/* Case-insensitive lookup against the pre-interned header table. Returns
+ * the table index on hit, -1 on miss. Bounded O(30) — vastly faster than
+ * spawning a `String#downcase` allocation per header. */
+static int header_table_lookup(const char *name, long len) {
+    for (int i = 0; i < HEADER_TABLE_PAIRS; i++) {
+        if (header_table_lc_len[i] != len) continue;
+        const char *cand = header_table_lc[i];
+        int match = 1;
+        for (long j = 0; j < len; j++) {
+            unsigned char c = (unsigned char)name[j];
+            if (c >= 'A' && c <= 'Z') c |= 0x20;
+            if (c != (unsigned char)cand[j]) { match = 0; break; }
+        }
+        if (match) return i;
+    }
+    return -1;
+}
+
 typedef struct {
     /* Request line + headers */
     VALUE method;
@@ -57,15 +142,25 @@ typedef struct {
     const char *error_message;
 } parser_state_t;
 
+/* 2.4-B (S1): defer per-field String allocations until the relevant
+ * llhttp callback actually fires. A typical GET request never sends a
+ * body and may have no query_string; allocating empty placeholder
+ * Strings up-front cost 6 allocations per parse() before this change.
+ * After: allocate Qnil sentinels; the on_* callbacks lazy-allocate
+ * via the LAZY_ALLOC helper below; the Request build at the bottom
+ * coerces any remaining Qnil to the global empty-Strings table. */
+static VALUE rb_kEMPTY_STR;          /* frozen empty ASCII-8BIT String */
+static VALUE rb_kHTTP_1_1;           /* frozen "HTTP/1.1" String */
+
 static void state_init(parser_state_t *s) {
     s->method                    = Qnil;
-    s->path                      = rb_str_new_cstr("");
-    s->query_string              = rb_str_new_cstr("");
-    s->http_version              = rb_str_new_cstr("HTTP/1.1");
+    s->path                      = Qnil;  /* allocated in on_url first call */
+    s->query_string              = Qnil;  /* allocated in on_url_complete only if '?' present */
+    s->http_version              = Qnil;  /* allocated in on_version */
     s->headers                   = rb_hash_new();
-    s->body                      = rb_str_new_cstr("");
-    s->current_header_name       = rb_str_new_cstr("");
-    s->current_header_value      = rb_str_new_cstr("");
+    s->body                      = Qnil;  /* allocated in on_body first call */
+    s->current_header_name       = Qnil;  /* allocated in on_header_field */
+    s->current_header_value      = Qnil;  /* allocated in on_header_value */
     s->message_complete          = 0;
     s->has_content_length        = 0;
     s->has_transfer_encoding     = 0;
@@ -78,21 +173,51 @@ static void state_init(parser_state_t *s) {
 #define MAX_FIELD_BYTES (64 * 1024)
 #define MAX_BODY_BYTES  (16 * 1024 * 1024)
 
+/* 2.4-B (S1): lazy field allocation. The slot may still be Qnil on
+ * first append (state_init left it nil to skip the empty-String
+ * allocation). Materialise on first append, cap-check on subsequent. */
 #define APPEND_OR_FAIL(dst, at, length, cap, who) do {     \
-    if (RSTRING_LEN(dst) + (long)(length) > (long)(cap)) { \
-        s->parse_error = 1;                                \
-        s->error_message = (who " too large");             \
-        return -1;                                         \
+    if (NIL_P(dst)) {                                      \
+        if ((long)(length) > (long)(cap)) {                \
+            s->parse_error = 1;                            \
+            s->error_message = (who " too large");         \
+            return -1;                                     \
+        }                                                  \
+        (dst) = rb_str_new(at, length);                    \
+    } else {                                               \
+        if (RSTRING_LEN(dst) + (long)(length) > (long)(cap)) { \
+            s->parse_error = 1;                            \
+            s->error_message = (who " too large");         \
+            return -1;                                     \
+        }                                                  \
+        rb_str_cat(dst, at, length);                       \
     }                                                      \
-    rb_str_cat(dst, at, length);                           \
 } while (0)
 
 static void stash_pending_header(parser_state_t *s) {
-    if (RSTRING_LEN(s->current_header_name) > 0) {
-        VALUE downcased = rb_funcall(s->current_header_name, id_downcase, 0);
-        rb_hash_aset(s->headers, downcased, s->current_header_value);
-        s->current_header_name  = rb_str_new_cstr("");
-        s->current_header_value = rb_str_new_cstr("");
+    /* 2.4-B (S1): the name/value slots are Qnil between headers; only
+     * an actually-populated header pair triggers the stash. Reset to
+     * Qnil after stash (not a fresh empty String) — the next
+     * on_header_field allocates lazily via APPEND_OR_FAIL. */
+    if (!NIL_P(s->current_header_name) && RSTRING_LEN(s->current_header_name) > 0) {
+        /* Phase 2c (1.7.1): try the pre-interned table first. On a hit
+         * we reuse the frozen lowercase VALUE — saves a String allocation
+         * per common header. On a miss, fall back to the original
+         * `String#downcase` path so unusual / vendor-specific headers
+         * still flow through unmolested. */
+        const char *name_ptr = RSTRING_PTR(s->current_header_name);
+        long        name_len = RSTRING_LEN(s->current_header_name);
+        int         idx      = header_table_lookup(name_ptr, name_len);
+        VALUE key;
+        if (idx >= 0) {
+            key = header_table_lc_v[idx];
+        } else {
+            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;
+        rb_hash_aset(s->headers, key, val);
+        s->current_header_name  = Qnil;
+        s->current_header_value = Qnil;
     }
 }
 
@@ -104,6 +229,11 @@ static int on_url(llhttp_t *p, const char *at, size_t length) {
 
 static int on_url_complete(llhttp_t *p) {
     parser_state_t *s = (parser_state_t *)p->data;
+    /* 2.4-B (S1): path is Qnil for the (rare) zero-length-URL pathological
+     * case; nothing to split. */
+    if (NIL_P(s->path)) {
+        return 0;
+    }
     /* Split path?query. */
     char *full = RSTRING_PTR(s->path);
     long full_len = RSTRING_LEN(s->path);
@@ -131,6 +261,13 @@ static int on_method(llhttp_t *p, const char *at, size_t length) {
 static int on_version(llhttp_t *p, const char *at, size_t length) {
     /* llhttp gives us "1.1"; we prepend "HTTP/" ourselves. */
     parser_state_t *s = (parser_state_t *)p->data;
+    /* 2.4-B (S1): fast path the common "1.1" case to the frozen
+     * "HTTP/1.1" constant; saves an allocation on the overwhelming
+     * majority of HTTP/1.1 requests. */
+    if (length == 3 && at[0] == '1' && at[1] == '.' && at[2] == '1') {
+        s->http_version = rb_kHTTP_1_1;
+        return 0;
+    }
     s->http_version = rb_str_new_cstr("HTTP/");
     rb_str_cat(s->http_version, at, length);
     return 0;
@@ -138,25 +275,18 @@ static int on_version(llhttp_t *p, const char *at, size_t length) {
 
 static int on_header_field(llhttp_t *p, const char *at, size_t length) {
     parser_state_t *s = (parser_state_t *)p->data;
-    /* If current_header_value is non-empty, we just finished a header. */
-    if (RSTRING_LEN(s->current_header_value) > 0) {
+    /* 2.4-B (S1): name/value are Qnil between headers. A pending value
+     * is the signal that we just finished one and need to stash. */
+    if (!NIL_P(s->current_header_value) && RSTRING_LEN(s->current_header_value) > 0) {
         stash_pending_header(s);
     }
-    if (RSTRING_LEN(s->current_header_name) == 0) {
-        s->current_header_name = rb_str_new(at, length);
-    } else {
-        APPEND_OR_FAIL(s->current_header_name, at, length, MAX_FIELD_BYTES, "header name");
-    }
+    APPEND_OR_FAIL(s->current_header_name, at, length, MAX_FIELD_BYTES, "header name");
     return 0;
 }
 
 static int on_header_value(llhttp_t *p, const char *at, size_t length) {
     parser_state_t *s = (parser_state_t *)p->data;
-    if (RSTRING_LEN(s->current_header_value) == 0) {
-        s->current_header_value = rb_str_new(at, length);
-    } else {
-        APPEND_OR_FAIL(s->current_header_value, at, length, MAX_FIELD_BYTES, "header value");
-    }
+    APPEND_OR_FAIL(s->current_header_value, at, length, MAX_FIELD_BYTES, "header value");
     return 0;
 }
 
@@ -164,11 +294,14 @@ static int on_headers_complete(llhttp_t *p) {
     parser_state_t *s = (parser_state_t *)p->data;
     stash_pending_header(s);
 
-    /* Smuggling defense: both Content-Length and Transfer-Encoding present. */
-    VALUE cl_key = rb_str_new_cstr("content-length");
-    VALUE te_key = rb_str_new_cstr("transfer-encoding");
-    VALUE cl = rb_hash_aref(s->headers, cl_key);
-    VALUE te = rb_hash_aref(s->headers, te_key);
+    /* 2.4-B (S2): the lookup keys are pre-interned frozen Strings
+     * registered as globals in Init_hyperion_http. Pre-2.4-B these were
+     * freshly allocated via rb_str_new_cstr on every parse(); the new
+     * statics save 2 String allocations per parse() and (more
+     * importantly) make the Hash#[] lookup hit the internal frozen-key
+     * fast path because identity matches the keys we stored under. */
+    VALUE cl = rb_hash_aref(s->headers, rb_kHCONTENT_LENGTH_LC);
+    VALUE te = rb_hash_aref(s->headers, rb_kHTRANSFER_ENCODING_LC);
     s->has_content_length    = !NIL_P(cl);
     s->has_transfer_encoding = !NIL_P(te);
     if (s->has_content_length && s->has_transfer_encoding) {
@@ -284,14 +417,24 @@ static VALUE cparser_parse(VALUE self, VALUE buffer) {
         consumed = len;
     }
 
+    /* 2.4-B (S1): Qnil-to-empty-String coercion for fields that the
+     * llhttp callbacks never touched (e.g. zero-length URL, GET with
+     * no body, HTTP/1.0 with no version detail). The frozen empty
+     * String is shared across every nil-coerced field — no allocation. */
+    VALUE method        = NIL_P(s.method)        ? rb_kEMPTY_STR : s.method;
+    VALUE path          = NIL_P(s.path)          ? rb_kEMPTY_STR : s.path;
+    VALUE query_string  = NIL_P(s.query_string)  ? rb_kEMPTY_STR : s.query_string;
+    VALUE http_version  = NIL_P(s.http_version)  ? rb_kHTTP_1_1  : s.http_version;
+    VALUE body          = NIL_P(s.body)          ? rb_kEMPTY_STR : s.body;
+
     /* Build the Request. */
     VALUE kwargs = rb_hash_new();
-    rb_hash_aset(kwargs, ID2SYM(id_method_kw),       s.method);
-    rb_hash_aset(kwargs, ID2SYM(id_path_kw),         s.path);
-    rb_hash_aset(kwargs, ID2SYM(id_query_string_kw), s.query_string);
-    rb_hash_aset(kwargs, ID2SYM(id_http_version_kw), s.http_version);
+    rb_hash_aset(kwargs, ID2SYM(id_method_kw),       method);
+    rb_hash_aset(kwargs, ID2SYM(id_path_kw),         path);
+    rb_hash_aset(kwargs, ID2SYM(id_query_string_kw), query_string);
+    rb_hash_aset(kwargs, ID2SYM(id_http_version_kw), http_version);
     rb_hash_aset(kwargs, ID2SYM(id_headers_kw),      s.headers);
-    rb_hash_aset(kwargs, ID2SYM(id_body_kw),         s.body);
+    rb_hash_aset(kwargs, ID2SYM(id_body_kw),         body);
 
     VALUE args[1] = { kwargs };
     VALUE request = rb_funcallv_kw(rb_cRequest, id_new, 1, args, RB_PASS_KEYWORDS);
@@ -859,6 +1002,197 @@ static VALUE cchunked_body_complete(VALUE self, VALUE rb_buffer, VALUE rb_body_s
     }
 }
 
+/* Look up the pre-interned "HTTP_<UPCASED_UNDERSCORED>" Rack key for a
+ * lowercase header name, or build a fresh one bytewise if it's not on the
+ * 30-entry table. The fresh-build path mirrors cupcase_underscore exactly
+ * — a single Ruby String allocation, US-ASCII encoded.
+ *
+ * Returns the (frozen, table-owned) VALUE on a hit; the freshly-built
+ * (mutable, US-ASCII) VALUE on a miss. Both are safe as Hash keys: Ruby
+ * Hash dups+freezes mutable String keys on insertion. */
+static VALUE http_key_for(VALUE name_str) {
+    const char *src = RSTRING_PTR(name_str);
+    long src_len    = RSTRING_LEN(name_str);
+
+    /* The lowercase keys come straight from the parser's own
+     * stash_pending_header — for the 30 pre-interned entries those
+     * Strings are literally the same VALUE as header_table_lc_v[i],
+     * so we can short-circuit with a pointer compare before falling
+     * back to the byte-equality scan. */
+    for (int i = 0; i < HEADER_TABLE_PAIRS; i++) {
+        if (header_table_lc_v[i] == name_str) {
+            return rb_ary_entry(rb_aHeaderTable, (i * 2) + 1);
+        }
+    }
+    /* Fallback for headers that came in via a non-parser path (e.g.
+     * adapter receives an artificially constructed Request in specs)
+     * — case-insensitive scan against the same table. */
+    int idx = header_table_lookup(src, src_len);
+    if (idx >= 0) {
+        return rb_ary_entry(rb_aHeaderTable, (idx * 2) + 1);
+    }
+
+    /* Not on the table — build "HTTP_<UPCASED_UNDERSCORED>" in one alloc. */
+    VALUE out = rb_str_new(NULL, 5 + src_len);
+    char *dst = RSTRING_PTR(out);
+    dst[0] = 'H'; dst[1] = 'T'; dst[2] = 'T'; dst[3] = 'P'; dst[4] = '_';
+    for (long i = 0; i < src_len; i++) {
+        unsigned char c = (unsigned char)src[i];
+        if (c >= 'a' && c <= 'z') {
+            dst[5 + i] = (char)(c - 32);
+        } else if (c == '-') {
+            dst[5 + i] = '_';
+        } else {
+            dst[5 + i] = (char)c;
+        }
+    }
+    rb_enc_associate(out, rb_usascii_encoding());
+    RB_GC_GUARD(name_str);
+    return out;
+}
+
+/* Iteration callback for the headers Hash in cbuild_env. `arg` is the env
+ * Hash; we map the lowercase header name to its HTTP_* Rack key (via the
+ * pre-interned table or a one-allocation upcase) and store the value. */
+static int build_env_iter(VALUE name, VALUE value, VALUE arg) {
+    VALUE env = arg;
+    if (TYPE(name) != T_STRING) return ST_CONTINUE;
+
+    VALUE http_key = http_key_for(name);
+    rb_hash_aset(env, http_key, value);
+
+    /* Promote the two RFC-mandated non-HTTP_ env keys. We compare against
+     * the pre-interned VALUEs first (pointer compare, common case) and
+     * fall back to byte compare for off-table-but-still-named matches. */
+    if (name == header_table_lc_v[8] /* "content-length" */ ||
+        (RSTRING_LEN(name) == 14 &&
+         memcmp(RSTRING_PTR(name), "content-length", 14) == 0)) {
+        rb_hash_aset(env, rb_kCONTENT_LENGTH, value);
+    } else if (name == header_table_lc_v[9] /* "content-type" */ ||
+               (RSTRING_LEN(name) == 12 &&
+                memcmp(RSTRING_PTR(name), "content-type", 12) == 0)) {
+        rb_hash_aset(env, rb_kCONTENT_TYPE, value);
+    }
+    return ST_CONTINUE;
+}
+
+/* Hyperion::CParser.build_env(env, request) -> env
+ *
+ * Phase 3a (1.7.1) — populate the Rack env hash with REQUEST_METHOD,
+ * PATH_INFO, QUERY_STRING, HTTP_VERSION, SERVER_PROTOCOL, CONTENT_TYPE,
+ * CONTENT_LENGTH, and HTTP_<UPCASED_UNDERSCORED> for every parsed header.
+ *
+ * The Ruby caller (Hyperion::Adapter::Rack#build_env) sets the rest of the
+ * Rack-required keys (rack.input, REMOTE_ADDR, SERVER_NAME/PORT, …) since
+ * those need a StringIO from a pool and a peer-address split. The header
+ * loop is the bytewise-bound piece and the only thing worth pulling into
+ * C — moving the full env build would mean threading the pool, host
+ * splitter, and version constant through the FFI boundary for ~no extra
+ * win.
+ *
+ * Returns the same env Hash (callers can either chain or ignore).
+ */
+static VALUE cbuild_env(VALUE self, VALUE env, VALUE request) {
+    (void)self;
+    Check_Type(env, T_HASH);
+
+    /* Read Request ivars directly — Request is a frozen value object set
+     * up in initialize; no risk of stale reads, no method-dispatch cost. */
+    VALUE method       = rb_ivar_get(request, id_iv_method);
+    VALUE path         = rb_ivar_get(request, id_iv_path);
+    VALUE query_string = rb_ivar_get(request, id_iv_query_string);
+    VALUE http_version = rb_ivar_get(request, id_iv_http_version);
+    VALUE headers      = rb_ivar_get(request, id_iv_headers);
+
+    rb_hash_aset(env, rb_kREQUEST_METHOD,  method);
+    rb_hash_aset(env, rb_kPATH_INFO,       path);
+    rb_hash_aset(env, rb_kQUERY_STRING,    query_string);
+    rb_hash_aset(env, rb_kSERVER_PROTOCOL, http_version);
+    rb_hash_aset(env, rb_kHTTP_VERSION,    http_version);
+
+    if (TYPE(headers) == T_HASH) {
+        rb_hash_foreach(headers, build_env_iter, env);
+    }
+
+    return env;
+}
+
+/* Hyperion::CParser.parse_cookie_header(cookie_str) -> Hash
+ *
+ * Phase 3b (1.7.1) — split a single Cookie header value into its
+ * { "name" => "value" } pairs.
+ *
+ * Standard format: "name1=val1; name2=val2; name3=val3".
+ * Leading/trailing ASCII whitespace is trimmed around each pair and
+ * around each key. Empty values are valid. Pairs without `=` are skipped
+ * (RFC 6265 calls them ignorable). Repeated names are last-wins —
+ * middlewares that need RFC-strict merge can override.
+ *
+ * Cookies are NOT URL-decoded by spec; values are opaque octets. We
+ * leave them verbatim. The returned Hash is mutable so the caller can
+ * extend it (e.g. for session-cookie hot-swaps).
+ */
+static VALUE cparse_cookie_header(VALUE self, VALUE rb_cookie) {
+    (void)self;
+    Check_Type(rb_cookie, T_STRING);
+
+    VALUE result = rb_hash_new();
+
+    const char *src = RSTRING_PTR(rb_cookie);
+    long src_len    = RSTRING_LEN(rb_cookie);
+    long i = 0;
+
+    while (i < src_len) {
+        /* Skip leading whitespace and stray semicolons. */
+        while (i < src_len && (src[i] == ' ' || src[i] == '\t' ||
+                               src[i] == ';')) {
+            i++;
+        }
+        if (i >= src_len) break;
+
+        /* Pair runs to next ';' (or end of string). */
+        long pair_start = i;
+        while (i < src_len && src[i] != ';') i++;
+        long pair_end = i;
+
+        /* Trim trailing whitespace inside the pair. */
+        while (pair_end > pair_start &&
+               (src[pair_end - 1] == ' ' || src[pair_end - 1] == '\t')) {
+            pair_end--;
+        }
+        if (pair_end == pair_start) continue;
+
+        /* Find '=' inside [pair_start, pair_end). */
+        long eq = -1;
+        for (long j = pair_start; j < pair_end; j++) {
+            if (src[j] == '=') { eq = j; break; }
+        }
+        if (eq < 0) continue; /* malformed — no '=' — skip per RFC 6265. */
+
+        /* Trim trailing ws on key (between pair_start and eq). */
+        long key_end = eq;
+        while (key_end > pair_start &&
+               (src[key_end - 1] == ' ' || src[key_end - 1] == '\t')) {
+            key_end--;
+        }
+        if (key_end == pair_start) continue; /* empty name — skip. */
+
+        /* Skip leading ws on value (between eq+1 and pair_end). */
+        long val_start = eq + 1;
+        while (val_start < pair_end &&
+               (src[val_start] == ' ' || src[val_start] == '\t')) {
+            val_start++;
+        }
+
+        VALUE key = rb_str_new(src + pair_start, key_end - pair_start);
+        VALUE val = rb_str_new(src + val_start,  pair_end - val_start);
+        rb_hash_aset(result, key, val);
+    }
+
+    RB_GC_GUARD(rb_cookie);
+    return result;
+}
+
 void Init_hyperion_http(void) {
     install_settings();
 
@@ -879,6 +1213,10 @@ void Init_hyperion_http(void) {
                                cupcase_underscore, 1);
     rb_define_singleton_method(rb_cCParser, "chunked_body_complete?",
                                cchunked_body_complete, 2);
+    rb_define_singleton_method(rb_cCParser, "build_env",
+                               cbuild_env, 2);
+    rb_define_singleton_method(rb_cCParser, "parse_cookie_header",
+                               cparse_cookie_header, 1);
 
     id_new             = rb_intern("new");
     id_downcase        = rb_intern("downcase");
@@ -888,4 +1226,101 @@ void Init_hyperion_http(void) {
     id_http_version_kw = rb_intern("http_version");
     id_headers_kw      = rb_intern("headers");
     id_body_kw         = rb_intern("body");
+
+    /* Phase 3a (1.7.1) — Request ivars + fixed env-key Strings. The
+     * env-key Strings are deeply frozen and registered via rb_global_variable
+     * so the GC doesn't reclaim them; reusing a single VALUE per fixed key
+     * eliminates a per-request String allocation on the hot path. */
+    id_iv_method       = rb_intern("@method");
+    id_iv_path         = rb_intern("@path");
+    id_iv_query_string = rb_intern("@query_string");
+    id_iv_http_version = rb_intern("@http_version");
+    id_iv_headers      = rb_intern("@headers");
+
+    rb_kREQUEST_METHOD  = rb_obj_freeze(rb_str_new_cstr("REQUEST_METHOD"));
+    rb_kPATH_INFO       = rb_obj_freeze(rb_str_new_cstr("PATH_INFO"));
+    rb_kQUERY_STRING    = rb_obj_freeze(rb_str_new_cstr("QUERY_STRING"));
+    rb_kHTTP_VERSION    = rb_obj_freeze(rb_str_new_cstr("HTTP_VERSION"));
+    rb_kSERVER_PROTOCOL = rb_obj_freeze(rb_str_new_cstr("SERVER_PROTOCOL"));
+    rb_kCONTENT_TYPE    = rb_obj_freeze(rb_str_new_cstr("CONTENT_TYPE"));
+    rb_kCONTENT_LENGTH  = rb_obj_freeze(rb_str_new_cstr("CONTENT_LENGTH"));
+    rb_global_variable(&rb_kREQUEST_METHOD);
+    rb_global_variable(&rb_kPATH_INFO);
+    rb_global_variable(&rb_kQUERY_STRING);
+    rb_global_variable(&rb_kHTTP_VERSION);
+    rb_global_variable(&rb_kSERVER_PROTOCOL);
+    rb_global_variable(&rb_kCONTENT_TYPE);
+    rb_global_variable(&rb_kCONTENT_LENGTH);
+
+    /* 2.4-B (S1, S2): the Qnil-coercion sentinel + the smuggling-defense
+     * lookup keys, all interned + frozen once at module init. They show
+     * up in every parse() call. */
+    rb_kEMPTY_STR             = rb_obj_freeze(rb_str_new("", 0));
+    rb_kHTTP_1_1              = rb_obj_freeze(rb_str_new_cstr("HTTP/1.1"));
+    rb_kHCONTENT_LENGTH_LC    = rb_obj_freeze(rb_str_new_cstr("content-length"));
+    rb_kHTRANSFER_ENCODING_LC = rb_obj_freeze(rb_str_new_cstr("transfer-encoding"));
+    rb_global_variable(&rb_kEMPTY_STR);
+    rb_global_variable(&rb_kHTTP_1_1);
+    rb_global_variable(&rb_kHCONTENT_LENGTH_LC);
+    rb_global_variable(&rb_kHTRANSFER_ENCODING_LC);
+
+    /* Phase 2c (1.7.1): build the 30-entry pre-interned header table.
+     * Each entry caches the frozen lowercase header name (used as the
+     * env-hash key by stash_pending_header) and the corresponding frozen
+     * "HTTP_<UPCASED_UNDERSCORED>" Rack key (consumed by the Ruby-side
+     * Hyperion::Adapter::Rack via a class-level constant lookup, so all
+     * three layers — parser, adapter, env hash — share string identity).
+     * `rb_aHeaderTable` is registered as a global so the GC doesn't
+     * reclaim its members. */
+    rb_aHeaderTable = rb_ary_new_capa(HEADER_TABLE_PAIRS * 2);
+    rb_global_variable(&rb_aHeaderTable);
+    for (int i = 0; i < HEADER_TABLE_PAIRS; i++) {
+        VALUE lc   = rb_str_new_cstr(header_table_lc[i]);
+        VALUE http = rb_str_new_cstr(header_table_http[i]);
+        rb_obj_freeze(lc);
+        rb_obj_freeze(http);
+        header_table_lc_v[i]   = lc;
+        header_table_lc_len[i] = (long)strlen(header_table_lc[i]);
+        rb_ary_push(rb_aHeaderTable, lc);
+        rb_ary_push(rb_aHeaderTable, http);
+    }
+    rb_obj_freeze(rb_aHeaderTable);
+    rb_define_const(rb_cCParser, "PREINTERNED_HEADERS", rb_aHeaderTable);
+
+    /* Phase 1 (1.7.0) — sibling C unit owns Hyperion::Http::Sendfile.
+     * Defined in sendfile.c; both objects link into the same .bundle/.so
+     * so a single `require 'hyperion_http/hyperion_http'` brings up the
+     * full surface. */
+    extern void Init_hyperion_sendfile(void);
+    Init_hyperion_sendfile();
+
+    /* 2.10-C — sibling C unit owns Hyperion::Http::PageCache.
+     * Pre-built static-response cache mirrored on agoo's agooPage:
+     * each cached asset's full HTTP/1.1 response (status line +
+     * Content-Type + Content-Length + body) lives in ONE contiguous
+     * heap buffer.  The hot path issues a single write() syscall
+     * with zero Ruby-side allocation.  See ext/hyperion_http/page_cache.c
+     * for design notes; the Ruby façade lives in
+     * lib/hyperion/http/page_cache.rb. */
+    extern void Init_hyperion_page_cache(void);
+    Init_hyperion_page_cache();
+
+    /* WS-3 (2.1.0) — sibling C unit owns Hyperion::WebSocket::CFrame.
+     * RFC 6455 frame parse/build + GVL-releasing unmask. Same single-.so
+     * link arrangement as sendfile. */
+    extern void Init_hyperion_websocket(void);
+    Init_hyperion_websocket();
+
+    /* 2.4-A (2.4.0) — sibling C unit owns Hyperion::H2Codec::CGlue.
+     * Direct C → Rust HPACK encode/decode bridge that bypasses the
+     * Fiddle layer on the per-call hot path. Defines the v3 ABI;
+     * Ruby's H2Codec::Encoder/Decoder dispatch through CGlue when
+     * `available?` returns true and fall back to the v2 (Fiddle) path
+     * transparently otherwise. The `dlopen` of the Rust cdylib is
+     * deferred to `H2Codec.load!`'s call to `CGlue.install(path)` —
+     * we don't want to probe the filesystem from Init time because
+     * the Rust crate may not have built (no cargo on host) and a
+     * fail-fast crash here would break parser.c entirely. */
+    extern void Init_hyperion_h2_codec_glue(void);
+    Init_hyperion_h2_codec_glue();
 }