hyperion-rb 1.4.2 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd27fc15210a2436de9b88664413eeb7cd7cf129e0921f88d7d15edd87b76d11
-  data.tar.gz: 8dd98630e170ee1467197542d69d034b15aa1d1a1bc2441e780d3290c2c59f1d
+  metadata.gz: eecb708980287e22968f1405778e91632ecd26eaae33845891ee00e94adf6839
+  data.tar.gz: e433cd1bff6039cd8c30bbc9fdce6cd4176ca1e03d33362f9e67ceddd7d89880
 SHA512:
-  metadata.gz: a2ae7959ab5fe99207c2c53db22060385a6eeb3aad355d05b4b6f14b16c16d1057592eda2f63b2a72cbfeb62ec7ebae5ec5945f317e84a27c5bac9c6fdfbe614
-  data.tar.gz: 6fb3d77d7c631b98e366ef921859dcc9af1f5f2e3f6eb6e97bebfd9453f6403c6846d46c66628204785bd9c0253e01984696b59eab690c53a79f3238c6f1f15a
+  metadata.gz: c02db1008beea0246601193a4ca18e8ac931f9a4952a2571a88ecc24028a838707a55e0ecf2159ba53f76b4a3c32c94c635afeb957304ae16ca2e0c2951ef7a3
+  data.tar.gz: 8c3bb4674315a4c41cd4bf38296ab2c991b113f3bcb0ced20ae3a143572f289c3d9a00ce258ba317045a5427b4b7a7986bf6de9f499c84d0ec61b505d8563518

data/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## [1.6.0] - 2026-04-27
+
+Two parallel improvements landing in 1.6.0:
+1. Three small C-extension additions on the request hot path (sibling commit — see "Performance" below).
+2. Architectural rewrite of the HTTP/2 outbound write path — per-stream send queue + dedicated writer fiber replace the global `@send_mutex` (see "HTTP/2 writer architecture" below).
+
+These are independent and can be reviewed / reverted separately. The CHANGELOG sub-sections will be merged before tag.
+
+### HTTP/2 writer architecture (Changed)
+- **`Hyperion::Http2Handler` now uses a per-connection writer fiber instead of a single send Mutex.** Pre-1.6.0 every framer write — HEADERS, DATA, RST_STREAM, GOAWAY — ran inside one `@send_mutex.synchronize { socket.write(...) }`. That capped per-connection h2 throughput at "one socket-write at a time" regardless of how many streams were concurrently in flight: a slow socket (kernel send buffer full, peer reading slowly) blocked every other stream's writes too. 1.6.0 splits the path:
+  - **Encode + frame format** (HPACK encoding, frame layout) is fast (microseconds, in-memory) and stays serialized on the calling fiber via `WriterContext#encode_mutex`. HPACK state is connection-scoped and stateful across HEADERS frames; per-stream wire order (HEADERS → DATA → END_STREAM) must also be preserved. Holding the encode mutex across a `stream.send_*` call satisfies both.
+  - **Bytes-to-socket** is owned by a dedicated `run_writer_loop` fiber spawned per connection. Encoder fibers hand bytes off via `WriterContext#enqueue` (non-blocking, signals an `Async::Notification`); the writer pops chunks from the queue and writes them. Only this fiber ever calls `socket.write`, satisfying SSLSocket's "no concurrent writes from different fibers" constraint.
+  - **Net effect**: a stream that has bytes ready can encode and enqueue while the writer is mid-flush of an earlier chunk — the slow-socket case no longer serializes encode work across streams. Mutex hold time drops from "until the kernel accepts the write" to "until the bytes are appended to the in-memory queue."
+- **Per-connection backpressure cap** (`MAX_PER_CONN_PENDING_BYTES = 16 MiB`). Pathological clients that read very slowly could otherwise let the queue grow without bound. `WriterContext#enqueue` parks the encoder on `@drained_notify` once `@pending_bytes` exceeds the cap; the writer signals `@drained_notify` after each drain pass.
+- **Coordinated shutdown**: when `Http2Handler#serve` exits (clean close, peer disconnect, or protocol error), the `ensure` block sets `WriterContext#shutdown!` and `writer_task.wait`s for the final drain BEFORE closing the socket. Order matters — closing the socket first would discard final RST_STREAM / GOAWAY / END_STREAM frames sitting in the queue.
+
+### HTTP/2 writer architecture (Added)
+- **`Hyperion::Http2Handler::SendQueueIO`** — IO-shaped wrapper passed to `Protocol::HTTP2::Framer` in place of the raw socket. `read` is a passthrough (single-reader on the connection fiber); `write` enqueues onto the connection-wide queue. Reports `closed?` from the underlying socket so framer EOF detection still works.
+- **`Hyperion::Http2Handler::WriterContext`** — holds the per-connection queue, the encode mutex, the send/drained notifications, and the byte-budget counters. One instance per connection; lives for the lifetime of `Http2Handler#serve`.
+- **9 new specs in `spec/hyperion/http2_writer_loop_spec.rb`**:
+  - `SendQueueIO#write` returns bytesize, enqueues without writing the socket, no-ops on empty/nil, reports the underlying socket's `closed?` state (4).
+  - Writer loop drains a single encoder's frames in enqueue order (1).
+  - Two encoder fibers pushing concurrently — bytes for both streams reach the wire and per-stream order (HEADERS → DATA → END) is preserved (1).
+  - Backpressure parks the encoder when `@pending_bytes` exceeds `max_pending_bytes`; encoder resumes after the writer drains (1).
+  - Shutdown drains all queued frames before the writer fiber exits; shutdown with an empty queue exits cleanly (2).
+- **`bench/h2_streams.sh`** — `h2load`-driven recipe (`-c 1 -m 100 -n 5000`) for measuring per-connection multi-stream rps. Skips with a clear message if `h2load` isn't on PATH; emits a one-line JSON summary so cross-version diffs are easy.
+
+### HTTP/2 writer architecture (Migration)
+- No public-API changes. Operators do not need to touch config or restart with new flags. The architectural change is internal to `Http2Handler`.
+
+### HTTP/2 writer architecture (Notes)
+- HPACK's dynamic-table state is shared across all streams on a connection (per RFC 7541 §2.3.2.1). That is why we still serialize encode work — two fibers calling `stream.send_headers` concurrently would corrupt the encoder's table state. The mutex is now microseconds-of-CPU rather than "however long the socket takes to drain N MB."
+- `Async::Notification#signal` is a no-op when there are no waiters (signals are not buffered). The writer loop accordingly re-checks `writer_done? && queue_empty?` before parking, so a `shutdown!` call that races a `wait_for_signal` doesn't deadlock.
+
+### Performance
+- **`Hyperion::CParser.upcase_underscore(name)` — C-level Rack header-name normalizer.** Replaces the per-uncached-header `"HTTP_#{name.upcase.tr('-', '_')}"` allocation in `Adapter::Rack#build_env`. Single allocation (5 prefix bytes + N source bytes), single byte loop, no Ruby intermediates. Microbench (5 typical X-* names per call): 460k i/s Ruby → 2.21M i/s C, **4.80×** faster (2.17 μs → 452 ns/iter). On a header-heavy hello-world rackup with 8 X-Custom-* request headers + 9 response headers, headline throughput went from ~16.6k r/s to ~18.0k r/s wrk-driven (~+8.5%, averaged across 3 trials). The 16-name `HTTP_KEY_CACHE` still short-circuits the common headers; this only fires on uncached customs.
+- **`Hyperion::CParser.chunked_body_complete?(buffer, body_start)` — chunked-transfer body completion check in C.** Replaces the pure-Ruby walker in `Connection#chunked_body_complete?` with a C-level loop that scans CRLF boundaries, decodes hex sizes, and advances the cursor without per-iteration `String#index` / `byteslice` / `split` allocations. Returns `[complete?, last_safe_offset]` so the caller can persist parse progress across read boundaries (handy for pipelined / streaming buffers, even though Connection currently only consults the boolean). Microbench (3 mixed buffers per iter): 283k i/s Ruby → 3.73M i/s C, **13.19×** faster (3.54 μs → 268 ns/iter). Profit is small in production because chunked uploads are rare, but the path now matches the rest of the parser in cost shape.
+- **`Hyperion::CParser.build_access_line_colored(...)` — TTY-coloured access-log builder in C.** Mirrors `build_access_line` with the green ANSI escape pair `\e[32mINFO \e[0m` baked into the level label. Ten extra bytes per line, single allocation. The pre-1.6.0 `Logger#access` path fell back to the slower Ruby builder whenever `@colorize` was on (i.e. local TTY / dev runs); now the C builder fires there too. Microbench: 1.78M i/s Ruby → 2.90M i/s C, **1.63×** faster (561 ns → 345 ns per line). Smaller win than the others — the Ruby builder was already a single interpolation — but closes the parity gap so dev-loop `tail -f` doesn't pay an avoidable Ruby tax.
+
+### Added
+- **9 new specs in `spec/hyperion/c_upcase_underscore_spec.rb`** plus a fallback-parity assertion that flips `Hyperion::Adapter::Rack.@c_upcase_available` to walk both the C and Ruby branches in one process. Covers lowercase / uppercase / multi-dash / empty / single-byte / non-ASCII byte-pass-through / digit-preservation / Ruby-equivalence on a panel of canonical custom names / encoding (US-ASCII).
+- **13 new specs in `spec/hyperion/c_chunked_body_complete_spec.rb`** including a fallback-parity assertion against the original Ruby walker. Covers single chunk, multi-chunk, trailers, partial CRLF, partial size token, partial chunk data, chunk extensions, body_start offset, last-safe-cursor reporting on partial buffers, ArgumentError on out-of-range body_start, and a panel of mixed inputs that must agree byte-for-byte with the Ruby walker.
+- **9 new specs in `spec/hyperion/c_access_line_colored_spec.rb`** plus a Logger#access integration test that constructs a TTY-faking IO and asserts the green INFO label appears in the emitted line. Covers text + json formats, query nil/empty/quote-trigger, remote_addr nil, ANSI absence in JSON, and byte-for-byte parity against a hand-rolled Ruby colored builder.
+
+## [1.5.0] - 2026-04-27
+
+Audit-driven CLI + adapter polish. No breaking changes; pure additions to the operator surface and a hardening of the host-header parser.
+
+### Added
+- **CLI flag coverage for 8 Config DSL settings.** Pre-1.5.0 these settings could only be reached by writing a `config/hyperion.rb` file; operators who don't keep one in their repo had no way to flip them without authoring one. They now flow through the same CLI > config-file > default precedence as the rest of the flags:
+  - `--max-body-bytes BYTES` (Integer, default 16 MiB)
+  - `--max-header-bytes BYTES` (Integer, default 64 KiB)
+  - `--max-pending COUNT` (Integer, default unbounded)
+  - `--max-request-read-seconds SECONDS` (Float, default 60)
+  - `--admin-token TOKEN` (String, default unset) — gates `POST /-/quit` and `GET /-/metrics`
+  - `--admin-token-file PATH` — sibling that reads the token from disk; refuses to load if the file is missing, unreadable, world-readable (perms must mask `0o007`), or empty. Production deployments should prefer this over `--admin-token` because argv is visible via `ps`.
+  - `--worker-max-rss-mb MB` (Integer, default unset) — RSS-based worker recycling
+  - `--idle-keepalive SECONDS` (Float, default 5)
+  - `--graceful-timeout SECONDS` (Integer, default 30)
+- **`Hyperion::CLI.parse_argv!` extracted as a public class method** so the flag-to-`cli_opts` mapping is unit-testable without booting a server. `CLI.run` is now a thin wrapper around it.
+- **README CLI flags table** extended with the 8 new flags plus `--[no-]yjit` / `--[no-]async-io` (already wired but previously undocumented in the table).
+- **17 new specs**:
+  - 14 in `spec/hyperion/cli_flags_spec.rb` cover per-flag parsing, the `merge_cli!` handoff for all 8 new flags, the CLI-wins precedence rule, and the four `--admin-token-file` abort paths (missing / unreadable / world-readable / empty).
+  - 3 in `spec/hyperion/adapter/rack_spec.rb` cover plain IPv4-with-port, bare hostname (no port), and the malformed-bracket regression below.
+
+### Fixed
+- **`Hyperion::Adapter::Rack#split_host` accepted malformed bracketed IPv6.** Pre-1.5.0 a `Host: [::1` header (no closing bracket) was returned as-is in `SERVER_NAME`, leaking attacker-controlled bytes into Rack env where downstream URL generators / SSRF allow-lists / audit logs would trust them. The adapter now fails closed to `localhost:80` and bumps a `:malformed_host_header` counter so operators can alert on attack-pattern volume. No raise — Rack apps don't expect a server adapter to throw on header-parse failures, so we degrade gracefully instead.
+
+### Security
+- `--admin-token` help text warns that argv is visible via `ps` and points operators at `--admin-token-file` for production. The token value is never echoed back in any log line.
+
 ## [1.4.2] - 2026-04-27
 
 Audit-driven cleanup. No behaviour changes; fiber-correctness + docs polish.

data/README.md

@@ -201,6 +201,8 @@ The architectural difference shows up under **load**, not at idle: Puma can only
 
 Hyperion fans 100 in-flight streams across separate fibers within a single TCP connection. A serial server would take 5 s; the fiber-multiplexed result (1.04 s, ~96 req/s on one socket) is bounded by single-handler sleep time plus framing overhead. Puma has no native HTTP/2 path — production deployments terminate h2 at nginx and forward h1 to the worker pool, which serializes again.
 
+> **1.6.0 outbound write path** — `Http2Handler` no longer serializes every framer write through one `Mutex#synchronize { socket.write(...) }`. HPACK encoding (microseconds, in-memory) still serializes on a fast encode mutex, but the actual `socket.write` is owned by a dedicated per-connection writer fiber draining a queue. On per-connection multi-stream workloads where the kernel send buffer or peer reads are slow, encode work for ready streams overlaps the writer's flush of earlier chunks, instead of stacking up behind it. See `bench/h2_streams.sh` (`h2load -c 1 -m 100 -n 5000`) for a recipe to compare 1.5.0 vs 1.6.0 on a workload of your choice.
+
 ### Reproduce
 
 ```sh
@@ -255,6 +257,17 @@ Three layers, in precedence order: explicit CLI flag > environment variable > `c
 | `--log-format FORMAT` | `auto` | `text` / `json` / `auto`. Auto: JSON when `RAILS_ENV`/`RACK_ENV` is `production`/`staging`, colored text on TTY, JSON otherwise. |
 | `--[no-]log-requests` | ON | Per-request access log. |
 | `--fiber-local-shim` | off | Patches `Thread#thread_variable_*` to fiber storage for older Rails idioms. |
+| `--[no-]yjit` | auto | Force YJIT on/off. Default: auto-on under `RAILS_ENV`/`RACK_ENV` = `production`/`staging`. |
+| `--[no-]async-io` | off | Run plain HTTP/1.1 connections under `Async::Scheduler`. Required for `hyperion-async-pg` on plain HTTP. TLS h1 / HTTP/2 always run under the scheduler regardless. |
+| `--max-body-bytes BYTES` | `16777216` (16 MiB) | Maximum request body size. |
+| `--max-header-bytes BYTES` | `65536` (64 KiB) | Maximum total request-header size. |
+| `--max-pending COUNT` | unbounded | Per-worker accept-queue cap before new connections are rejected with HTTP 503 + `Retry-After: 1`. |
+| `--max-request-read-seconds SECONDS` | `60` | Total wallclock budget for reading request line + headers + body for ONE request. Slowloris defence. |
+| `--admin-token TOKEN` | unset | Bearer token for `POST /-/quit` and `GET /-/metrics`. **Production: prefer `--admin-token-file` — argv is visible via `ps`.** |
+| `--admin-token-file PATH` | unset | Read the admin token from a file. Refuses to load if the file is missing or world-readable (mode must mask `0o007`). |
+| `--worker-max-rss-mb MB` | unset | Master gracefully recycles a worker once its RSS exceeds this many megabytes. nil = disabled. |
+| `--idle-keepalive SECONDS` | `5` | Keep-alive idle timeout. Connection closes after this many seconds of inactivity. |
+| `--graceful-timeout SECONDS` | `30` | Shutdown deadline before SIGKILL is delivered to a worker that hasn't drained. |
 
 ### Environment variables
 

data/ext/hyperion_http/parser.c

@@ -543,6 +543,322 @@ static VALUE cbuild_access_line(VALUE self,
 }
 #undef CAT_LIT
 
+/* Hyperion::CParser.build_access_line_colored(format, ts, method, path, query,
+ *                                              status, duration_ms, remote_addr,
+ *                                              http_version) -> String
+ *
+ * TTY-coloured variant of build_access_line. The text path wraps the level
+ * label with ANSI escape "\e[32mINFO \e[0m" so a developer running Hyperion
+ * in a terminal sees a green INFO tag. The :json branch is identical to the
+ * non-coloured builder — JSON access lines are machine-readable and never
+ * carry ANSI escapes.
+ *
+ * Lifted from cbuild_access_line above; the only divergence is the level
+ * label injection in the text branch. We deliberately duplicate the text
+ * format rather than templating, because the text body is short and a
+ * single function with a colour flag would compile to the same code with an
+ * extra branch in the hot loop.
+ */
+static VALUE cbuild_access_line_colored(VALUE self,
+                                        VALUE format_sym, VALUE rb_ts,
+                                        VALUE rb_method, VALUE rb_path,
+                                        VALUE rb_query, VALUE rb_status,
+                                        VALUE rb_duration, VALUE rb_remote,
+                                        VALUE rb_http_version) {
+    (void)self;
+    Check_Type(rb_ts, T_STRING);
+    Check_Type(rb_method, T_STRING);
+    Check_Type(rb_path, T_STRING);
+    Check_Type(rb_http_version, T_STRING);
+
+    int is_json = (TYPE(format_sym) == T_SYMBOL) &&
+                  (SYM2ID(format_sym) == rb_intern("json"));
+
+    int status     = NUM2INT(rb_status);
+    double dur_ms  = NUM2DBL(rb_duration);
+
+    int has_query  = !NIL_P(rb_query) && RSTRING_LEN(rb_query) > 0;
+    int has_remote = !NIL_P(rb_remote) && RSTRING_LEN(rb_remote) > 0;
+
+#define CAT_LIT(b, s) rb_str_cat((b), (s), (long)(sizeof(s) - 1))
+
+    VALUE buf = rb_str_buf_new(512);
+
+    if (is_json) {
+        /* JSON output is identical to the non-coloured path — ANSI escapes
+         * have no place in a structured log record. */
+        CAT_LIT(buf, "{\"ts\":\"");
+        rb_str_cat(buf, RSTRING_PTR(rb_ts), RSTRING_LEN(rb_ts));
+        CAT_LIT(buf, "\",\"level\":\"info\",\"source\":\"hyperion\",\"message\":\"request\",");
+        CAT_LIT(buf, "\"method\":\"");
+        rb_str_cat(buf, RSTRING_PTR(rb_method), RSTRING_LEN(rb_method));
+        CAT_LIT(buf, "\",\"path\":\"");
+        rb_str_cat(buf, RSTRING_PTR(rb_path), RSTRING_LEN(rb_path));
+        CAT_LIT(buf, "\"");
+
+        if (has_query) {
+            CAT_LIT(buf, ",\"query\":\"");
+            rb_str_cat(buf, RSTRING_PTR(rb_query), RSTRING_LEN(rb_query));
+            CAT_LIT(buf, "\"");
+        }
+
+        char num[64];
+        int n = snprintf(num, sizeof(num), ",\"status\":%d,\"duration_ms\":%g,",
+                         status, dur_ms);
+        rb_str_cat(buf, num, n);
+
+        if (has_remote) {
+            CAT_LIT(buf, "\"remote_addr\":\"");
+            rb_str_cat(buf, RSTRING_PTR(rb_remote), RSTRING_LEN(rb_remote));
+            CAT_LIT(buf, "\",");
+        } else {
+            CAT_LIT(buf, "\"remote_addr\":null,");
+        }
+
+        CAT_LIT(buf, "\"http_version\":\"");
+        rb_str_cat(buf, RSTRING_PTR(rb_http_version), RSTRING_LEN(rb_http_version));
+        CAT_LIT(buf, "\"}\n");
+    } else {
+        /* text: "<ts> \e[32mINFO \e[0m [hyperion] message=request method=..." */
+        rb_str_cat(buf, RSTRING_PTR(rb_ts), RSTRING_LEN(rb_ts));
+        CAT_LIT(buf, " \x1b[32mINFO \x1b[0m [hyperion] message=request method=");
+        rb_str_cat(buf, RSTRING_PTR(rb_method), RSTRING_LEN(rb_method));
+        CAT_LIT(buf, " path=");
+        rb_str_cat(buf, RSTRING_PTR(rb_path), RSTRING_LEN(rb_path));
+
+        if (has_query) {
+            const char *q_ptr = RSTRING_PTR(rb_query);
+            long q_len = RSTRING_LEN(rb_query);
+            int need_quote = 0;
+            for (long j = 0; j < q_len; j++) {
+                char c = q_ptr[j];
+                if (c == ' ' || c == '\t' || c == '\n' || c == '\r' ||
+                    c == '"' || c == '=') {
+                    need_quote = 1;
+                    break;
+                }
+            }
+            if (need_quote) {
+                VALUE quoted = rb_funcall(rb_query, rb_intern("inspect"), 0);
+                CAT_LIT(buf, " query=");
+                rb_str_cat(buf, RSTRING_PTR(quoted), RSTRING_LEN(quoted));
+            } else {
+                CAT_LIT(buf, " query=");
+                rb_str_cat(buf, q_ptr, q_len);
+            }
+        }
+
+        char num[80];
+        int n = snprintf(num, sizeof(num), " status=%d duration_ms=%g remote_addr=",
+                         status, dur_ms);
+        rb_str_cat(buf, num, n);
+
+        if (has_remote) {
+            rb_str_cat(buf, RSTRING_PTR(rb_remote), RSTRING_LEN(rb_remote));
+        } else {
+            CAT_LIT(buf, "nil");
+        }
+
+        CAT_LIT(buf, " http_version=");
+        rb_str_cat(buf, RSTRING_PTR(rb_http_version), RSTRING_LEN(rb_http_version));
+        CAT_LIT(buf, "\n");
+    }
+
+    return buf;
+}
+#undef CAT_LIT
+
+/* Hyperion::CParser.upcase_underscore(name) -> "HTTP_<UPCASED_UNDERSCORED>"
+ *
+ * Single-allocation replacement for `"HTTP_#{name.upcase.tr('-', '_')}"`.
+ * Hot path on the Rack adapter: every uncached request header (any
+ * `X-*` custom header) hits this on every request, and the Ruby version
+ * spawns three String allocations (the upcase result, the tr result, and the
+ * "HTTP_..." interpolation) plus a per-byte loop in tr.
+ *
+ * We allocate one Ruby String of length 5 + name.bytesize, fill it in a
+ * single byte loop, return it. ASCII letters get OR'd with 0x20 inverted
+ * (i.e. cleared bit 5 to upcase 'a'..'z'); '-' becomes '_'; everything else
+ * passes through (header names are ASCII per RFC 9110, but multi-byte UTF-8
+ * bytes pass through bytewise unmolested rather than crashing).
+ *
+ * Encoding is set to US-ASCII because Ruby's String#upcase on an ASCII-only
+ * input returns a US-ASCII string, and the env-key lookup downstream is
+ * encoding-agnostic anyway.
+ */
+static VALUE cupcase_underscore(VALUE self, VALUE rb_name) {
+    (void)self;
+    Check_Type(rb_name, T_STRING);
+
+    const char *src = RSTRING_PTR(rb_name);
+    long src_len    = RSTRING_LEN(rb_name);
+
+    /* Single allocation: 5 prefix bytes + N source bytes. */
+    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());
+    /* Keep rb_name live across the loop above. RSTRING_PTR returns an
+     * interior pointer that becomes invalid if the GC moves the source
+     * String — unlikely on this tight path, but cheap insurance. */
+    RB_GC_GUARD(rb_name);
+    return out;
+}
+
+/* Hyperion::CParser.chunked_body_complete?(buffer, body_start)
+ *   -> [complete?, end_offset]
+ *
+ * Walks chunked-transfer framing in `buffer` starting at byte offset
+ * `body_start`. Returns a 2-element array:
+ *   [true,  end_offset] — chunked body fully buffered; end_offset is the
+ *                         byte just after the trailer CRLF (where pipelined
+ *                         bytes from a follow-on request would begin).
+ *   [false, last_safe]  — body is not yet complete; last_safe is the
+ *                         furthest cursor we successfully advanced to,
+ *                         useful as a hint for incremental parsing.
+ *
+ * Mirrors Connection#chunked_body_complete? in pure Ruby — see lib/hyperion/
+ * connection.rb. Trailing whitespace after the size token (e.g. "5 ; ext\r\n")
+ * is permitted as a permissive parse to match the upstream Ruby `.strip`.
+ */
+static VALUE cchunked_body_complete(VALUE self, VALUE rb_buffer, VALUE rb_body_start) {
+    (void)self;
+    Check_Type(rb_buffer, T_STRING);
+
+    const char *data = RSTRING_PTR(rb_buffer);
+    long len         = RSTRING_LEN(rb_buffer);
+    long cursor      = NUM2LONG(rb_body_start);
+
+    if (cursor < 0 || cursor > len) {
+        rb_raise(rb_eArgError, "body_start out of range");
+    }
+
+    long last_safe = cursor;
+    VALUE result   = rb_ary_new_capa(2);
+
+    while (1) {
+        /* Find the next CRLF starting at cursor. */
+        long line_end = -1;
+        for (long i = cursor; i + 1 < len; i++) {
+            if (data[i] == '\r' && data[i + 1] == '\n') {
+                line_end = i;
+                break;
+            }
+        }
+        if (line_end < 0) {
+            rb_ary_push(result, Qfalse);
+            rb_ary_push(result, LONG2NUM(last_safe));
+            RB_GC_GUARD(rb_buffer);
+            return result;
+        }
+
+        /* Parse the size token: hex digits up to ';' or whitespace, optional
+         * chunk extension after ';' which we ignore wholesale. */
+        long tok_start = cursor;
+        long tok_end   = line_end;
+        for (long i = cursor; i < line_end; i++) {
+            if (data[i] == ';') { tok_end = i; break; }
+        }
+        /* Trim leading/trailing ASCII whitespace from the token. */
+        while (tok_start < tok_end &&
+               (data[tok_start] == ' ' || data[tok_start] == '\t')) {
+            tok_start++;
+        }
+        while (tok_end > tok_start &&
+               (data[tok_end - 1] == ' ' || data[tok_end - 1] == '\t')) {
+            tok_end--;
+        }
+        if (tok_end <= tok_start) {
+            /* Empty size token — incomplete frame. */
+            rb_ary_push(result, Qfalse);
+            rb_ary_push(result, LONG2NUM(last_safe));
+            RB_GC_GUARD(rb_buffer);
+            return result;
+        }
+
+        /* Validate + decode hex. */
+        unsigned long size = 0;
+        for (long i = tok_start; i < tok_end; i++) {
+            unsigned char c = (unsigned char)data[i];
+            unsigned int digit;
+            if (c >= '0' && c <= '9') {
+                digit = c - '0';
+            } else if (c >= 'a' && c <= 'f') {
+                digit = 10 + (c - 'a');
+            } else if (c >= 'A' && c <= 'F') {
+                digit = 10 + (c - 'A');
+            } else {
+                /* Non-hex byte: incomplete/malformed. Match the Ruby
+                 * regex `/\A\h+\z/` semantics — return false, advance no
+                 * further. The caller will read more bytes and retry. */
+                rb_ary_push(result, Qfalse);
+                rb_ary_push(result, LONG2NUM(last_safe));
+                RB_GC_GUARD(rb_buffer);
+                return result;
+            }
+            size = (size << 4) | digit;
+        }
+
+        cursor = line_end + 2;
+
+        if (size == 0) {
+            /* Final chunk — walk trailer headers until we hit "\r\n\r\n"
+             * (i.e. an empty trailer line directly after the size line). */
+            while (1) {
+                long nl = -1;
+                for (long i = cursor; i + 1 < len; i++) {
+                    if (data[i] == '\r' && data[i + 1] == '\n') {
+                        nl = i;
+                        break;
+                    }
+                }
+                if (nl < 0) {
+                    rb_ary_push(result, Qfalse);
+                    rb_ary_push(result, LONG2NUM(last_safe));
+                    RB_GC_GUARD(rb_buffer);
+                    return result;
+                }
+                if (nl == cursor) {
+                    /* Empty line — body complete. */
+                    rb_ary_push(result, Qtrue);
+                    rb_ary_push(result, LONG2NUM(nl + 2));
+                    RB_GC_GUARD(rb_buffer);
+                    return result;
+                }
+                cursor = nl + 2;
+            }
+        }
+
+        /* Need cursor + size + 2 bytes (chunk data + trailing CRLF). */
+        if ((unsigned long)(len - cursor) < size + 2) {
+            rb_ary_push(result, Qfalse);
+            rb_ary_push(result, LONG2NUM(last_safe));
+            RB_GC_GUARD(rb_buffer);
+            return result;
+        }
+
+        cursor += (long)size + 2;
+        last_safe = cursor;
+    }
+}
+
 void Init_hyperion_http(void) {
     install_settings();
 
@@ -557,6 +873,12 @@ void Init_hyperion_http(void) {
                                cbuild_response_head, 6);
     rb_define_singleton_method(rb_cCParser, "build_access_line",
                                cbuild_access_line, 9);
+    rb_define_singleton_method(rb_cCParser, "build_access_line_colored",
+                               cbuild_access_line_colored, 9);
+    rb_define_singleton_method(rb_cCParser, "upcase_underscore",
+                               cupcase_underscore, 1);
+    rb_define_singleton_method(rb_cCParser, "chunked_body_complete?",
+                               cchunked_body_complete, 2);
 
     id_new             = rb_intern("new");
     id_downcase        = rb_intern("downcase");

data/lib/hyperion/adapter/rack.rb

@@ -48,6 +48,17 @@ module Hyperion
         }
       )
 
+      # Whether Hyperion::CParser.upcase_underscore is available. Probed lazily
+      # at first use (CParser is required after this file, so an eager check
+      # at load time would always be false). Memoised in a class-level ivar to
+      # keep the hot path branchless.
+      def self.c_upcase_available?
+        return @c_upcase_available unless @c_upcase_available.nil?
+
+        @c_upcase_available = defined?(::Hyperion::CParser) &&
+                              ::Hyperion::CParser.respond_to?(:upcase_underscore)
+      end
+
       class << self
         # Pre-allocate `n` env-hash and rack-input objects in master before
         # fork. Children inherit the populated free-list via copy-on-write —
@@ -122,8 +133,14 @@ module Hyperion
           env['rack.run_once']     = false
           env['SCRIPT_NAME']       = ''
 
+          # Header-name → Rack env-key conversion. Cache covers the 16 most
+          # common names; uncached headers (X-* customs, vendor-specific) flow
+          # through CParser.upcase_underscore (single C-level allocation) when
+          # the extension is built, else the pure-Ruby triple-allocation path.
+          c_upcase = Rack.c_upcase_available?
           request.headers.each do |name, value|
-            key = HTTP_KEY_CACHE[name] || "HTTP_#{name.upcase.tr('-', '_')}"
+            key = HTTP_KEY_CACHE[name] ||
+                  (c_upcase ? ::Hyperion::CParser.upcase_underscore(name) : "HTTP_#{name.upcase.tr('-', '_')}")
             env[key] = value
           end
 
@@ -138,7 +155,17 @@ module Hyperion
 
           if host_header.start_with?('[')
             close = host_header.index(']')
-            return [host_header, '80'] unless close
+            # Malformed bracketed IPv6 (no closing bracket): we used to return
+            # the raw garbage as SERVER_NAME, which then leaked into Rack env
+            # where downstream URL generators / loggers / SSRF allow-lists
+            # would trust attacker-controlled bytes. Fail closed to a safe
+            # default and bump a counter so operators can alert on volume.
+            # No raise — Rack apps don't expect Hyperion's adapter to throw
+            # on header-parse failures, so we degrade gracefully instead.
+            unless close
+              Hyperion.metrics.increment(:malformed_host_header)
+              return %w[localhost 80]
+            end
 
             name = host_header[0..close]
             rest = host_header[(close + 1)..]

data/lib/hyperion/cli.rb

@@ -11,6 +11,55 @@ module Hyperion
     DEFAULT_CONFIG_PATH = 'config/hyperion.rb'
 
     def self.run(argv)
+      cli_opts, config_path = parse_argv!(argv)
+
+      # Precedence: CLI > config file > built-in default. We auto-load
+      # config/hyperion.rb if present so operators can drop a file in their
+      # repo and have it take effect without having to remember -C.
+      config_path ||= DEFAULT_CONFIG_PATH if File.exist?(DEFAULT_CONFIG_PATH)
+      config = config_path ? Hyperion::Config.load(config_path) : Hyperion::Config.new
+      config.merge_cli!(cli_opts)
+
+      # Install logger early so every subsequent log call honours the operator's
+      # chosen format/level (config file or CLI) before anything else logs.
+      if config.log_level || config.log_format
+        Hyperion.logger = Hyperion::Logger.new(level: config.log_level, format: config.log_format)
+      end
+
+      # Propagate log_requests so every Connection picks it up via
+      # `Hyperion.log_requests?` without needing to thread it through
+      # Server/ThreadPool/Master plumbing. Default is ON; nil means "don't
+      # touch — fall through to the env/default chain in Hyperion.log_requests?".
+      Hyperion.log_requests = config.log_requests unless config.log_requests.nil?
+
+      # Enable YJIT before workers fork / connections start. Auto-on in
+      # production/staging gives operators the perf bump for free; explicit
+      # config.yjit (true/false) overrides the env-based default.
+      maybe_enable_yjit(config)
+
+      rackup = argv.first || 'config.ru'
+      abort("[hyperion] no such rackup file: #{rackup}") unless File.exist?(rackup)
+
+      if config.fiber_local_shim
+        Hyperion::FiberLocal.install!
+        Hyperion.logger.info { { message: 'FiberLocal shim installed' } }
+      end
+
+      app = load_rack_app(rackup)
+      app = wrap_admin_middleware(app, config)
+      workers = config.workers.zero? ? Etc.nprocessors : config.workers
+
+      if workers <= 1
+        run_single(config, app)
+      else
+        run_cluster(config, app, workers)
+      end
+    end
+
+    # Extracted from #run so the flag-to-cli_opts mapping can be unit-tested
+    # without booting a server. Returns [cli_opts, config_path]. Mutates argv
+    # in place (consumes flags, leaves the rackup path for the caller).
+    def self.parse_argv!(argv)
       cli_opts    = {}
       config_path = nil
 
@@ -61,6 +110,46 @@ module Hyperion
              'Run plain HTTP/1.1 connections under Async::Scheduler (required for hyperion-async-pg and other fiber-cooperative I/O; default off)') do |v|
           cli_opts[:async_io] = v
         end
+        o.on('--max-body-bytes BYTES', Integer,
+             'Maximum request body size in bytes (default 16777216 = 16 MiB)') do |n|
+          cli_opts[:max_body_bytes] = n
+        end
+        o.on('--max-header-bytes BYTES', Integer,
+             'Maximum total request-header size in bytes (default 65536 = 64 KiB)') do |n|
+          cli_opts[:max_header_bytes] = n
+        end
+        o.on('--max-pending COUNT', Integer,
+             'Maximum queued connections per worker before new accepts are rejected with 503 (default unbounded)') do |n|
+          cli_opts[:max_pending] = n
+        end
+        o.on('--max-request-read-seconds SECONDS', Float,
+             'Total wallclock budget for reading request line + headers + body (default 60.0; 0 disables)') do |n|
+          cli_opts[:max_request_read_seconds] = n
+        end
+        # Security-sensitive: read the token verbatim and never echo it back
+        # in any subsequent log/help line. argv is visible via `ps` on most
+        # systems; production deployments should prefer --admin-token-file.
+        o.on('--admin-token TOKEN',
+             "Bearer token for the /-/quit and /-/metrics admin endpoints. \
+WARNING: argv is visible via `ps`; prefer --admin-token-file PATH for production.") do |t|
+          cli_opts[:admin_token] = t
+        end
+        o.on('--admin-token-file PATH',
+             'Read the admin token from a file. File must NOT be world-readable (perms must mask 0o007).') do |p|
+          cli_opts[:admin_token] = read_admin_token_file(p)
+        end
+        o.on('--worker-max-rss-mb MB', Integer,
+             'Recycle a worker when its RSS exceeds MB megabytes (default unset; nil disables)') do |n|
+          cli_opts[:worker_max_rss_mb] = n
+        end
+        o.on('--idle-keepalive SECONDS', Float,
+             'Idle keep-alive timeout in seconds (default 5.0)') do |n|
+          cli_opts[:idle_keepalive] = n
+        end
+        o.on('--graceful-timeout SECONDS', Integer,
+             'Graceful shutdown deadline in seconds before SIGKILL (default 30)') do |n|
+          cli_opts[:graceful_timeout] = n
+        end
         o.on('-h', '--help', 'show help') do
           puts o
           exit 0
@@ -68,47 +157,7 @@ module Hyperion
       end
       parser.parse!(argv)
 
-      # Precedence: CLI > config file > built-in default. We auto-load
-      # config/hyperion.rb if present so operators can drop a file in their
-      # repo and have it take effect without having to remember -C.
-      config_path ||= DEFAULT_CONFIG_PATH if File.exist?(DEFAULT_CONFIG_PATH)
-      config = config_path ? Hyperion::Config.load(config_path) : Hyperion::Config.new
-      config.merge_cli!(cli_opts)
-
-      # Install logger early so every subsequent log call honours the operator's
-      # chosen format/level (config file or CLI) before anything else logs.
-      if config.log_level || config.log_format
-        Hyperion.logger = Hyperion::Logger.new(level: config.log_level, format: config.log_format)
-      end
-
-      # Propagate log_requests so every Connection picks it up via
-      # `Hyperion.log_requests?` without needing to thread it through
-      # Server/ThreadPool/Master plumbing. Default is ON; nil means "don't
-      # touch — fall through to the env/default chain in Hyperion.log_requests?".
-      Hyperion.log_requests = config.log_requests unless config.log_requests.nil?
-
-      # Enable YJIT before workers fork / connections start. Auto-on in
-      # production/staging gives operators the perf bump for free; explicit
-      # config.yjit (true/false) overrides the env-based default.
-      maybe_enable_yjit(config)
-
-      rackup = argv.first || 'config.ru'
-      abort("[hyperion] no such rackup file: #{rackup}") unless File.exist?(rackup)
-
-      if config.fiber_local_shim
-        Hyperion::FiberLocal.install!
-        Hyperion.logger.info { { message: 'FiberLocal shim installed' } }
-      end
-
-      app = load_rack_app(rackup)
-      app = wrap_admin_middleware(app, config)
-      workers = config.workers.zero? ? Etc.nprocessors : config.workers
-
-      if workers <= 1
-        run_single(config, app)
-      else
-        run_cluster(config, app, workers)
-      end
+      [cli_opts, config_path]
     end
 
     def self.run_single(config, app)
@@ -227,6 +276,28 @@ module Hyperion
     end
     private_class_method :wrap_admin_middleware
 
+    # Read the admin token from a file on disk. Refuses to load if the file
+    # is missing, unreadable, or world-readable — the whole point of using a
+    # file instead of `--admin-token` is to keep the token off argv (which
+    # `ps` exposes) and off other-user-readable storage. Trailing whitespace
+    # is stripped so operators can use `echo "$TOKEN" > /etc/hyperion-token`
+    # without inadvertently embedding a newline. Empty files abort.
+    def self.read_admin_token_file(path)
+      abort("[hyperion] admin token file not found: #{path}") unless File.file?(path)
+      abort("[hyperion] admin token file not readable: #{path}") unless File.readable?(path)
+
+      mode = File.stat(path).mode & 0o777
+      if (mode & 0o007).positive?
+        abort("[hyperion] admin token file #{path} is world-readable (mode #{format('%04o', mode)}); chmod 600")
+      end
+
+      token = File.read(path).strip
+      abort("[hyperion] admin token file is empty: #{path}") if token.empty?
+
+      token
+    end
+    private_class_method :read_admin_token_file
+
     # Warn loudly at boot if the C parser didn't load — operators running
     # production with the pure-Ruby fallback are paying ~2× CPU on parse-heavy
     # workloads and probably don't know it.

data/lib/hyperion/connection.rb

@@ -287,9 +287,29 @@ module Hyperion
 
     # Walks chunked framing in `buffer` starting at `body_start` and
     # returns true once the final 0-sized chunk (and trailer terminator)
-    # is fully buffered. Mirrors the parser's dechunk walk; Phase 4's C
-    # parser folds these together via incremental parsing.
+    # is fully buffered. The C extension folds the size-line scan + hex
+    # decode + chunk advance into a single tight loop with no per-iteration
+    # Ruby allocation; the pure-Ruby fallback below preserves the original
+    # semantics for environments where the C extension didn't build.
     def chunked_body_complete?(buffer, body_start)
+      if self.class.c_chunked_available?
+        ::Hyperion::CParser.chunked_body_complete?(buffer, body_start).first
+      else
+        chunked_body_complete_ruby?(buffer, body_start)
+      end
+    end
+
+    # Whether Hyperion::CParser.chunked_body_complete? is available. Probed
+    # lazily at first use; memoised in a class-level ivar to keep the
+    # per-request hot path branchless.
+    def self.c_chunked_available?
+      return @c_chunked_available unless @c_chunked_available.nil?
+
+      @c_chunked_available = defined?(::Hyperion::CParser) &&
+                             ::Hyperion::CParser.respond_to?(:chunked_body_complete?)
+    end
+
+    def chunked_body_complete_ruby?(buffer, body_start)
       cursor = body_start
       loop do
         line_end = buffer.index("\r\n", cursor)

data/lib/hyperion/http2_handler.rb

@@ -18,11 +18,40 @@ module Hyperion
   # dispatch — slow handlers no longer block other streams on the same
   # connection.
   #
-  # All framer writes (HEADERS, DATA, RST_STREAM) are serialized through a
-  # single connection-scoped Mutex (`@send_mutex`). The OpenSSL::SSL::SSLSocket
-  # underneath is not safe to drive from two fibers concurrently, and
-  # protocol-http2's HPACK encoder is also stateful across HEADERS frames,
-  # so all sends must be serialized.
+  # ## Outbound write architecture (1.6.0+)
+  #
+  # Pre-1.6.0 every framer write (HEADERS / DATA / RST_STREAM / GOAWAY) ran
+  # under one connection-scoped `Mutex#synchronize { socket.write(...) }`.
+  # That capped per-connection h2 throughput to "one socket-write at a time"
+  # regardless of stream count: a slow socket (kernel send buffer full,
+  # remote peer reading slowly) blocked every other stream's writes too.
+  #
+  # 1.6.0 splits the path:
+  #   * The HPACK encode + frame format step is fast (microseconds, in-memory)
+  #     and remains serialized on the calling fiber via `@encode_mutex`. HPACK
+  #     state is stateful across HEADERS frames per connection, and frames for
+  #     a single stream must be wire-ordered (HEADERS → DATA → END_STREAM).
+  #     Holding the encode mutex across a `send_*` call accomplishes both.
+  #   * The framer writes through a `SendQueueIO` wrapper (wraps the real
+  #     socket). `SendQueueIO#write(bytes)` enqueues onto a connection-wide
+  #     `@send_queue` and signals `@send_notify`; it never touches the real
+  #     socket.
+  #   * A dedicated **writer fiber** owns the real socket. It pops byte chunks
+  #     off the queue, writes them, and parks on `@send_notify` when empty.
+  #     Only this fiber ever calls `socket.write` — the SSLSocket cross-fiber
+  #     unsafety constraint is satisfied.
+  #
+  # Net effect: the slow-socket case no longer serializes encode work across
+  # streams. A stream that has bytes ready to encode can encode and enqueue
+  # while the writer is mid-flush of an earlier chunk. The mutex hold time
+  # drops from "until the kernel accepts the write" to "until the bytes are
+  # appended to the in-memory queue."
+  #
+  # Backpressure: pathological clients (slow-read h2) could otherwise let the
+  # queue grow without bound. We track `@pending_bytes`; once it exceeds
+  # `MAX_PER_CONN_PENDING_BYTES`, encoding fibers wait on `@drained_notify`
+  # before enqueueing more. The writer signals `@drained_notify` after each
+  # drain pass.
   #
   # Flow control: `RequestStream#window_updated` overrides the protocol-http2
   # default to fan a notification out to any fiber blocked in `send_body`
@@ -31,6 +60,153 @@ module Hyperion
   # size and yields on the notification when the window is exhausted, so
   # large bodies never trip a FlowControlError.
   class Http2Handler
+    # Cap on bytes that may sit in a connection's send queue waiting for the
+    # writer fiber to drain. Slow-read h2 clients can otherwise let an
+    # encoder fiber pile arbitrary bytes into RAM. 16 MiB matches the upper
+    # bound a well-behaved peer will buffer — anything beyond that is the
+    # writer being starved, and the right answer is to backpressure the
+    # encoder rather than allocate more.
+    MAX_PER_CONN_PENDING_BYTES = 16 * 1024 * 1024
+
+    # IO-shaped wrapper passed to `Protocol::HTTP2::Framer` in place of the
+    # real socket. Reads are direct passthroughs (the read loop runs on the
+    # connection fiber and there's only one reader). Writes are enqueued
+    # onto the connection-wide `WriterContext#queue`; the writer fiber owns
+    # the real socket and drains the queue.
+    #
+    # We deliberately do NOT delegate `flush` to the real socket: writes
+    # don't reach it from this object — the writer fiber does that. `flush`
+    # here is a no-op (the writer flushes after each batch).
+    #
+    # `closed?` reports the real socket's state so protocol-http2's read
+    # loop sees EOF the same way it always has.
+    class SendQueueIO
+      attr_reader :real_socket
+
+      def initialize(real_socket, writer_ctx)
+        @real_socket = real_socket
+        @writer_ctx  = writer_ctx
+      end
+
+      # Framer's read path — direct delegation. Single-reader (the conn
+      # fiber), so no contention here.
+      def read(*args)
+        @real_socket.read(*args)
+      end
+
+      # Framer's write path — non-blocking handoff into the send queue.
+      # Backpressure is applied here: if pending bytes exceed the cap, the
+      # calling fiber parks on the drained notification until the writer
+      # has flushed enough to bring us below the threshold.
+      def write(bytes)
+        return 0 if bytes.nil? || bytes.empty?
+
+        @writer_ctx.enqueue(bytes)
+        bytes.bytesize
+      end
+
+      def flush
+        # No-op: bytes don't live in this object, they live in the queue.
+        # The writer fiber flushes the real socket as it drains.
+        nil
+      end
+
+      def close
+        @real_socket.close unless @real_socket.closed?
+      end
+
+      # Multi-line on purpose: a single-line `def closed?; @real_socket.closed?; end`
+      # gets autocorrected to `delegate :closed?, to: :@real_socket` by Rails-aware
+      # ruby-lsp formatters, which is wrong here (this is a plain gem, no
+      # ActiveSupport on the dependency graph).
+      def closed?
+        socket = @real_socket
+        socket.closed?
+      end
+    end
+
+    # Holds the per-connection outbound coordination state (queue,
+    # notifications, byte counters, shutdown flag) plus the encode mutex
+    # that protects HPACK state and per-stream frame ordering.
+    #
+    # Single instance per connection, lives for the lifetime of `serve`.
+    class WriterContext
+      attr_reader :encode_mutex
+
+      def initialize(max_pending_bytes: MAX_PER_CONN_PENDING_BYTES)
+        @queue              = ::Thread::Queue.new
+        @send_notify        = ::Async::Notification.new
+        @drained_notify     = ::Async::Notification.new
+        @encode_mutex       = ::Mutex.new
+        @pending_bytes      = 0
+        @pending_bytes_lock = ::Mutex.new
+        @max_pending_bytes  = max_pending_bytes
+        @writer_done        = false
+      end
+
+      # Called by SendQueueIO#write on the calling (encoder) fiber. Enforces
+      # the per-connection backpressure cap before enqueuing.
+      def enqueue(bytes)
+        wait_for_drain_if_full(bytes.bytesize)
+        @pending_bytes_lock.synchronize { @pending_bytes += bytes.bytesize }
+        @queue << bytes
+        @send_notify.signal
+      end
+
+      # Pops a single chunk; returns nil if the queue is empty (non-blocking).
+      def try_pop
+        @queue.pop(true)
+      rescue ::ThreadError
+        nil
+      end
+
+      # Called by the writer fiber after each successful drain to release
+      # any encoders blocked on the cap.
+      def note_drained(bytesize)
+        @pending_bytes_lock.synchronize do
+          @pending_bytes -= bytesize
+          @pending_bytes = 0 if @pending_bytes.negative? # paranoia
+        end
+        @drained_notify.signal
+      end
+
+      def wait_for_signal
+        @send_notify.wait
+      end
+
+      def shutdown!
+        @writer_done = true
+        # Wake the writer if it's parked, and any encoder waiting on drain.
+        @send_notify.signal
+        @drained_notify.signal
+      end
+
+      def writer_done?
+        @writer_done
+      end
+
+      def queue_empty?
+        @queue.empty?
+      end
+
+      def pending_bytes
+        @pending_bytes_lock.synchronize { @pending_bytes }
+      end
+
+      private
+
+      def wait_for_drain_if_full(incoming_bytes)
+        # If we're already at/above the cap, park until the writer has
+        # drained. We re-check after every signal because multiple encoders
+        # can wake on a single drain notification.
+        while !@writer_done &&
+              @pending_bytes_lock.synchronize { @pending_bytes + incoming_bytes > @max_pending_bytes } &&
+              !@queue.empty?
+          @drained_notify.wait
+        end
+      end
+    end
+
     # Per-stream subclass that captures decoded request pseudo-headers,
     # regular headers, and any DATA frame body bytes for later dispatch.
     # Also exposes a `window_available` notification fan-out so the
@@ -247,21 +423,29 @@ module Hyperion
     def serve(socket)
       @metrics.increment(:connections_accepted)
       @metrics.increment(:connections_active)
-      framer = ::Protocol::HTTP2::Framer.new(socket)
-      server = build_server(framer)
+
+      # Per-connection outbound coordination. Encoder fibers enqueue bytes;
+      # the writer fiber owns the real socket and drains. See class docstring.
+      writer_ctx   = WriterContext.new
+      send_io      = SendQueueIO.new(socket, writer_ctx)
+      framer       = ::Protocol::HTTP2::Framer.new(send_io)
+      server       = build_server(framer)
+
+      task = ::Async::Task.current
+
+      # Spawn the dedicated writer fiber BEFORE the preface exchange.
+      # `Server#read_connection_preface` writes the server's SETTINGS frame
+      # via the framer; if the writer isn't running, those bytes sit in the
+      # queue. Spawning first guarantees they flush as soon as the scheduler
+      # ticks, avoiding any pathological deadlock where a client implementation
+      # waits for our SETTINGS before sending more frames.
+      writer_task = task.async { run_writer_loop(socket, writer_ctx) }
+
       server.read_connection_preface(initial_settings_payload)
 
       # Extract once — the same TCP peer drives every stream on this conn.
       peer_addr = peer_address(socket)
 
-      # All framer writes (HEADERS / DATA / RST_STREAM / GOAWAY) must be
-      # serialized: the underlying SSLSocket is not safe across fibers, and
-      # the HPACK encoder is also stateful. The connection's own frame loop
-      # uses this mutex too — see `dispatch_stream` and `send_body`.
-      send_mutex = ::Mutex.new
-
-      task = ::Async::Task.current
-
       # Track in-flight per-stream dispatch fibers so we can drain them on
       # connection close.
       stream_tasks = []
@@ -284,7 +468,7 @@ module Hyperion
           stream.instance_variable_set(:@hyperion_dispatched, true)
 
           stream_tasks << task.async do
-            dispatch_stream(stream, send_mutex, peer_addr)
+            dispatch_stream(stream, writer_ctx, peer_addr)
           end
         end
       end
@@ -309,6 +493,18 @@ module Hyperion
         }
       end
     ensure
+      # Coordinated shutdown: flag the writer, signal it, wait for the final
+      # drain, then close the real socket. Order matters — closing the
+      # socket before the writer drains would discard final RST_STREAM /
+      # GOAWAY / END_STREAM frames in the queue.
+      if writer_ctx
+        writer_ctx.shutdown!
+        begin
+          writer_task&.wait
+        rescue StandardError
+          nil
+        end
+      end
       @metrics.decrement(:connections_active)
       socket.close unless socket.closed?
     end
@@ -394,7 +590,7 @@ module Hyperion
       server
     end
 
-    def dispatch_stream(stream, send_mutex, peer_addr = nil)
+    def dispatch_stream(stream, writer_ctx, peer_addr = nil)
       # RFC 7540 §8.1.2 — header validation flagged this stream as malformed.
       # Send RST_STREAM PROTOCOL_ERROR instead of invoking the app.
       if stream.protocol_error?
@@ -403,7 +599,7 @@ module Hyperion
         end
         @metrics.increment(:requests_rejected)
         begin
-          send_mutex.synchronize do
+          writer_ctx.encode_mutex.synchronize do
             stream.send_reset_stream(::Protocol::HTTP2::Error::PROTOCOL_ERROR) unless stream.closed?
           end
         rescue StandardError
@@ -459,8 +655,8 @@ module Hyperion
       body_chunks.each { |c| payload << c.to_s }
       body_chunks.close if body_chunks.respond_to?(:close)
 
-      send_mutex.synchronize { stream.send_headers(out_headers) }
-      send_body(stream, payload, send_mutex)
+      writer_ctx.encode_mutex.synchronize { stream.send_headers(out_headers) }
+      send_body(stream, payload, writer_ctx)
       @metrics.increment_status(status)
     rescue StandardError => e
       @metrics.increment(:app_errors)
@@ -473,7 +669,9 @@ module Hyperion
         }
       end
       begin
-        send_mutex.synchronize { stream.send_reset_stream(::Protocol::HTTP2::Error::INTERNAL_ERROR) }
+        writer_ctx.encode_mutex.synchronize do
+          stream.send_reset_stream(::Protocol::HTTP2::Error::INTERNAL_ERROR)
+        end
       rescue StandardError
         nil
       end
@@ -485,9 +683,12 @@ module Hyperion
     # notification — protocol-http2 calls `window_updated` on every active
     # stream when WINDOW_UPDATE frames arrive (either stream- or
     # connection-scoped), which signals the notification.
-    def send_body(stream, payload, send_mutex)
+    #
+    # The encode_mutex protects HPACK state and per-stream frame ordering;
+    # the actual socket write happens off-fiber via the writer task.
+    def send_body(stream, payload, writer_ctx)
       if payload.empty?
-        send_mutex.synchronize { stream.send_data('', ::Protocol::HTTP2::END_STREAM) }
+        writer_ctx.encode_mutex.synchronize { stream.send_data('', ::Protocol::HTTP2::END_STREAM) }
         return
       end
 
@@ -508,7 +709,69 @@ module Hyperion
         offset += chunk.bytesize
         flags = offset >= bytesize ? ::Protocol::HTTP2::END_STREAM : 0
 
-        send_mutex.synchronize { stream.send_data(chunk, flags) }
+        writer_ctx.encode_mutex.synchronize { stream.send_data(chunk, flags) }
+      end
+    end
+
+    # Drain bytes off the per-connection send queue onto the real socket.
+    # This fiber is the SOLE writer to `socket` for the connection's
+    # lifetime, which satisfies SSLSocket's "no concurrent writes from
+    # different fibers" constraint.
+    #
+    # The loop:
+    #   1. Drain everything currently enqueued (non-blocking pops).
+    #   2. If we drained anything, signal `@drained_notify` so backpressured
+    #      encoders can resume, then loop again — more bytes may have been
+    #      enqueued while we were writing.
+    #   3. If shutdown was requested AND the queue is empty, exit.
+    #   4. Otherwise park on the send notification until an encoder pokes us.
+    def run_writer_loop(socket, writer_ctx)
+      loop do
+        drained_bytes = 0
+        while (chunk = writer_ctx.try_pop)
+          begin
+            socket.write(chunk)
+          rescue EOFError, Errno::ECONNRESET, Errno::EPIPE, IOError, OpenSSL::SSL::SSLError
+            # Peer hung up. Release THIS chunk's byte budget, then drain the
+            # rest of the queue (without writing) so backpressured encoders
+            # don't stall waiting on a writer that's about to exit. Any
+            # remaining queued bytes are dropped — the connection is dead.
+            writer_ctx.note_drained(chunk.bytesize)
+            drain_and_discard_queue(writer_ctx)
+            return
+          end
+          drained_bytes += chunk.bytesize
+          writer_ctx.note_drained(chunk.bytesize)
+        end
+
+        # Some sockets (SSLSocket on a TCPSocket whose Nagle is off) need an
+        # explicit flush to push small final frames (END_STREAM data, GOAWAY)
+        # without waiting for the next write. Cheap when there's nothing
+        # buffered.
+        socket.flush if drained_bytes.positive? && socket.respond_to?(:flush) && !socket.closed?
+
+        return if writer_ctx.writer_done? && writer_ctx.queue_empty?
+
+        writer_ctx.wait_for_signal
+      end
+    rescue StandardError => e
+      @logger.error do
+        {
+          message: 'h2 writer loop error',
+          error: e.message,
+          error_class: e.class.name,
+          backtrace: (e.backtrace || []).first(10).join(' | ')
+        }
+      end
+    end
+
+    # On peer-disconnect we discard any queued bytes (we can't write them),
+    # but we MUST still decrement the byte counter for each one or
+    # backpressured encoder fibers will park forever on the drain
+    # notification.
+    def drain_and_discard_queue(writer_ctx)
+      while (chunk = writer_ctx.try_pop)
+        writer_ctx.note_drained(chunk.bytesize)
       end
     end
 

data/lib/hyperion/logger.rb

@@ -65,6 +65,7 @@ module Hyperion
       # check the regular stream here — colored text is for humans.
       @colorize = @format == :text && tty?(@out)
       @c_access_available = nil # lazy-computed on first access — see below.
+      @c_access_colored_available = nil # ditto for the coloured TTY variant.
       # Registry of every per-thread access buffer ever allocated through
       # this Logger instance. Walked by #flush_all on shutdown so SIGTERM
       # doesn't strand buffered lines in dying threads. The Mutex guards
@@ -94,6 +95,16 @@ module Hyperion
                             ::Hyperion::CParser.respond_to?(:build_access_line)
     end
 
+    # Whether Hyperion::CParser.build_access_line_colored is available. Same
+    # lazy-probe pattern as #c_access_available?; lets a colored-TTY run pick
+    # up the C path instead of the Ruby fallback.
+    def c_access_colored_available?
+      return @c_access_colored_available unless @c_access_colored_available.nil?
+
+      @c_access_colored_available = defined?(::Hyperion::CParser) &&
+                                    ::Hyperion::CParser.respond_to?(:build_access_line_colored)
+    end
+
     LEVELS.each_key do |lvl|
       define_method(lvl) do |payload = nil, &block|
         next unless emit?(lvl)
@@ -140,7 +151,12 @@ module Hyperion
       # which the C builder doesn't emit. Production deploys (non-TTY,
       # log-aggregator destinations) take the C path; local TTY runs keep the
       # colored Ruby fallback.
-      line = if !@colorize && c_access_available?
+      line = if @colorize && c_access_colored_available?
+               # Colored TTY path: green INFO label baked into the C builder.
+               ::Hyperion::CParser.build_access_line_colored(@format, ts, method, path,
+                                                             query, status, duration_ms,
+                                                             remote_addr, http_version)
+             elsif !@colorize && c_access_available?
                ::Hyperion::CParser.build_access_line(@format, ts, method, path,
                                                      query, status, duration_ms,
                                                      remote_addr, http_version)

data/lib/hyperion/version.rb

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

metadata

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