hyperion-rb 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85d66793d64b68cd4a7abcabddbe39f0bff7e2f2ba79b94ea1e3347badd0cee5
-  data.tar.gz: f1f42a47ce8849487f56c14b2e1ac1787f02617cc28972ecfd904233663b9acf
+  metadata.gz: 5670da7700c48436d0e3ded790cf5df090deeebd38bc0b7024b9b6e95c20b5c8
+  data.tar.gz: 10bedef6e02717511eb83bea0044e71978d7e13b9d93d0ac37310a89f6581e9a
 SHA512:
-  metadata.gz: 5d028d0c624bf56d64cc6b9859043deeec7c2c7c677a632d5a890cb6190468f97cc2632fccd9d90a6e1f5c4fcedd056c326e0873f012a3ac09a1546f931793ec
-  data.tar.gz: fbcb9b5fec440bf89fe54d3744bdab755582809aaeb4f7f098b7f4d7678e60f494cf5395f7ed6d05a8ebeb816c9e8c3bd7ced0da18d126b4812e22084883342d
+  metadata.gz: e791cdd9271cb954ddc11ee037ced8c182fffa4c8b27ded1d0c5672cada1d62fb4095d9e4c440136ce8eeed746eca6e4d99ebb3b1e42a2bc9bbd7bce5c1d9615
+  data.tar.gz: 4728b4bf159583fc6f46bd8c33dbcf916b74dddd49dd685159d39950112f5716cdc8108903d0ca312b31eef397d2237fab9d2f34d51e90822a7d3cab9c1b6691

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [1.1.0] - 2026-04-27
+
+First minor release after 1.0.0. Production hardening + perf wins, no breaking changes.
+
+### Added
+- **HTTP/2 §8.1.2 semantic validation** — Hyperion now rejects malformed `:method` / `:path` / `:scheme` pseudo-headers, connection-specific headers (`connection`, `te`, `transfer-encoding`, `keep-alive`, `upgrade`, `proxy-connection`), and inconsistent `content-length` framing with `RST_STREAM PROTOCOL_ERROR`. h2spec conformance pass rate is now 100% on the §8.1.2 suite (was 76.7% in 1.0.x).
+- **Worker recycling (`worker_max_rss_mb`)** — master polls each child's RSS via `/proc/<pid>/statm` (Linux) or `ps -o rss=` (macOS/BSD) every `worker_check_interval` seconds (default 30s). Workers exceeding the configured RSS ceiling are gracefully cycled (SIGTERM, drain, respawn). Disabled when `worker_max_rss_mb` is nil.
+- **Admin drain endpoint (`POST /-/quit`)** — token-protected Rack middleware that triggers the same SIGTERM-driven graceful shutdown as the signal path. Disabled by default; mount by setting `admin_token` in the Hyperion config DSL. Auth via `X-Hyperion-Admin-Token` header (constant-time comparison). Returns 202 + `{"status":"draining"}` on success, 401 on missing/wrong token.
+- **YJIT auto-enable** — Hyperion enables YJIT automatically in production/staging environments (`RAILS_ENV` / `RACK_ENV` / `HYPERION_ENV`). Override with the `yjit` config setting (true/false) or `--[no-]yjit` CLI flag. No-op on Rubies built without YJIT.
+- **C-extension access-log line builder** (`Hyperion::CParser.build_access_line`) — single-allocation line construction in C, ~10× faster than the Ruby interpolation path. Auto-selected on non-TTY destinations (production); colored TTY runs keep the Ruby fallback.
+- **Date-header cache** — per-thread, per-second cache of `Time.now.httpdate` in `ResponseWriter`. Eliminates ~3 String allocations per response.
+- **`bytes_read` / `bytes_written` metrics** — counters exposed via `Hyperion.stats` for connection-level bandwidth monitoring.
+- **`Hyperion.c_parser_available?`** module accessor + boot-time warn line if the llhttp C extension didn't load (so operators running production with the slower pure-Ruby fallback notice immediately).
+- **`MIGRATING_FROM_PUMA.md`** — operator guide covering config translation, lifecycle hook mapping, signal differences, and observability gaps.
+- **Concurrency-at-scale benchmarks** — README now documents 10 000-connection keep-alive throughput and h2 multiplexing numbers vs Puma/Falcon.
+
+### Changed
+- **Plain HTTP/1.1 accept loop bypasses Async** — when no TLS is configured, Hyperion uses a raw `IO.select` + `accept_nonblock` loop instead of wrapping the loop in an Async task. Worker-owns-connection semantics are unchanged. Removes ~2 µs of fiber-scheduler overhead from the hot accept path.
+
+### Fixed
+- **Lost shutdown log lines under SIGTERM** — `Master#shutdown_children` and `CLI.run_single` now call `Logger#flush_all`, which walks every per-thread access-log buffer registered through the Logger and `IO#flush`es both stdout and stderr before the process exits. Operators no longer have to chase missing `master draining` / `master exiting` lines after a graceful shutdown.
+- **Cross-instance Logger buffer leak** — per-thread access-log buffers are now namespaced per Logger instance (`:"__hyperion_access_buf_<oid>__"`). Previously a globally-shared key meant a buffer registered against an early Logger could be written to by a later Logger whose `flush_all` couldn't see it. The hot path remains a single `Thread.current` read.
+
+## [1.0.1] - 2026-04-26
+
+### Fixed
+- Bumped `required_ruby_version` floor from `>= 3.2.0` to `>= 3.3.0` to match actual transitive dependency reality (`protocol-http2 ~> 0.26` requires Ruby >= 3.3). Previously, installing on Ruby 3.2 produced an opaque dep-resolution error mentioning protocol-http2 instead of a clean Ruby-version mismatch.
+- CI matrix dropped `3.2.x` for the same reason.
+
 ## [1.0.0] - 2026-04-26
 
 First stable release. Same code as rc18; promoted from prerelease after smoke

data/README.md

@@ -7,7 +7,7 @@ High-performance Ruby HTTP server. Falcon-class fiber concurrency, Puma-class co
 [![License: MIT](https://img.shields.io/github/license/andrew-woblavobla/hyperion.svg)](https://github.com/andrew-woblavobla/hyperion/blob/master/LICENSE)
 
 ```sh
-gem install hyperion-rb --pre
+gem install hyperion-rb
 bundle exec hyperion config.ru
 ```
 
@@ -77,6 +77,35 @@ Health endpoint that traverses the full middleware chain (rack-attack, locale re
 
 On Grape and Rails-controller workloads Puma hits wrk's 2 s timeout cap on ~⅔ of requests — its real p99 is censored above 2 s. Hyperion serves all of its requests under 1.2 s with 0 to 16 timeouts. **1.14–1.48× Puma throughput** depending on endpoint.
 
+### Concurrency at scale (architectural advantages)
+
+These workloads demonstrate structural differences between Hyperion's fiber-per-connection / fiber-per-stream model and Puma's thread-pool model. Numbers are illustrative; the architecture is what matters. Run on Ubuntu 24.04 / Ruby 3.3.3, single worker, h2load `-c <conns> -n 100000 --rps 1000 --h1`.
+
+**5,000 concurrent keep-alive connections (50,000 requests):**
+
+| | succeeded | r/s | wall | master RSS |
+|---|---:|---:|---:|---:|
+| Hyperion `-w 1 -t 10` | 50,000 / 50,000 | 3,460 | 14.45 s | 53.5 MB |
+| Puma `-w 1 -t 10:10`  | 50,000 / 50,000 | 1,762 | 28.37 s | 36.9 MB |
+
+**10,000 concurrent keep-alive connections (100,000 requests):**
+
+| | succeeded | failed | r/s | wall |
+|---|---:|---:|---:|---:|
+| Hyperion `-w 1 -t 10` | 93,090 | 6,910 | 3,446 | 27.01 s |
+| Puma `-w 1 -t 10:10`  | 77,340 | 22,660 | 706 | 109.59 s |
+
+Hyperion holds each connection in a ~1 KB fiber stack; Puma needs an OS thread (~1–8 MB each, capped at `max_threads`). At 10k concurrent connections Hyperion serves **~5× the throughput** of Puma with **~20% fewer dropped requests**, while the per-connection bookkeeping cost is bounded by fiber size, not by `max_threads`.
+
+**HTTP/2 multiplexing — 1 connection × 100 concurrent streams (handler sleeps 50 ms):**
+
+| | wall time |
+|---|---:|
+| Hyperion (per-stream fiber dispatch) | **1.04 s** |
+| Serial baseline (100 × 50 ms) | 5.00 s |
+
+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.
+
 ### Reproduce
 
 ```sh
@@ -107,6 +136,8 @@ curl --http2 -k https://127.0.0.1:9443/
 
 `bundle exec rake spec` (and the `default` task) auto-invoke `compile`, so a fresh checkout just needs `bundle install && bundle exec rake` to get a green run.
 
+**Migrating from Puma?** See [docs/MIGRATING_FROM_PUMA.md](docs/MIGRATING_FROM_PUMA.md).
+
 ## Configuration
 
 Three layers, in precedence order: explicit CLI flag > environment variable > `config/hyperion.rb` > built-in default.
@@ -244,7 +275,7 @@ Smuggling defenses for HTTP/1.1: `Content-Length` + `Transfer-Encoding` together
 
 ## Compatibility
 
-- **Ruby 3.2+** required.
+- **Ruby 3.3+** required (the `protocol-http2 ~> 0.26` transitive dep imposes this floor; older Ruby installs error at `bundle install`).
 - **Rack 3** (auto-sets `SERVER_SOFTWARE`, `rack.version`, `REMOTE_ADDR`, IPv6-safe `Host` parsing, CRLF guard).
 - **`Hyperion::FiberLocal.install!`** opt-in shim for older Rails apps that store request-scoped data via `Thread.current.thread_variable_*` (modern Rails 7.1+ already uses Fiber storage natively; the shim handles the residual footgun).
 - **`Hyperion::FiberLocal.verify_environment!`** runtime check that `Thread.current[:k]` is fiber-local on the current Ruby (it is on 3.2+).

data/ext/hyperion_http/parser.c

@@ -404,6 +404,145 @@ static VALUE cbuild_response_head(VALUE self, VALUE rb_status, VALUE rb_reason,
     return buf;
 }
 
+/* Hyperion::CParser.build_access_line(format, ts, method, path, query,
+ *                                     status, duration_ms, remote_addr,
+ *                                     http_version) -> String
+ *
+ * Hand-rolled access-log line builder used by Hyperion::Logger#access on the
+ * hot path. The Ruby version allocates 1-2 throwaway Strings per line; this
+ * builds the line into a stack scratch buffer (with rb_str_buf overflow for
+ * extreme cases) and returns a single Ruby String. ~10× faster on the
+ * common case, which closes the perf gap between log_requests on/off.
+ *
+ * `format` is :text or :json (Symbol). The format strings here mirror
+ * Logger#build_access_text / #build_access_json byte-for-byte (no colour —
+ * the C builder is only used when @colorize is false, i.e. non-TTY production
+ * deployments where access logs are the highest-volume log line).
+ *
+ * String inputs are passed through verbatim. Access logs are best-effort
+ * structured output, not a security boundary; CRLF in path/remote_addr would
+ * be a log-injection nuisance but cannot escalate. Status (int) and
+ * duration_ms (double/Numeric) go through snprintf, which is type-safe.
+ */
+static VALUE cbuild_access_line(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;
+
+    /* 1 KiB initial buffer covers the vast majority of access-log lines
+     * (timestamp + level + path + status + addr ~= 200 bytes). rb_str_cat
+     * grows on overflow.
+     *
+     * We use a CAT_LIT macro for literal-string appends so the compiler
+     * computes length via sizeof — manual byte counts on hand-rolled
+     * literal lengths are an off-by-one waiting to happen. */
+#define CAT_LIT(b, s) rb_str_cat((b), (s), (long)(sizeof(s) - 1))
+
+    VALUE buf = rb_str_buf_new(512);
+
+    if (is_json) {
+        /* Prefix: {"ts":"...","level":"info","source":"hyperion","message":"request", */
+        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> INFO  [hyperion] message=request method=... path=... [query=...] status=... duration_ms=... remote_addr=... http_version=...\n" */
+        rb_str_cat(buf, RSTRING_PTR(rb_ts), RSTRING_LEN(rb_ts));
+        CAT_LIT(buf, " INFO  [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) {
+            /* Mirror Logger#quote_if_needed: quote if value contains
+             * whitespace, '"', or '='. Hot path skips quoting. */
+            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) {
+                /* Defer to Ruby's String#inspect for correct quoting. */
+                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];
+        /* Use %g to match the existing Ruby format which interpolates
+         * Float#to_s (no fixed precision). Status is an int. */
+        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
+
 void Init_hyperion_http(void) {
     install_settings();
 
@@ -416,6 +555,8 @@ void Init_hyperion_http(void) {
     rb_define_method(rb_cCParser, "parse", cparser_parse, 1);
     rb_define_singleton_method(rb_cCParser, "build_response_head",
                                cbuild_response_head, 6);
+    rb_define_singleton_method(rb_cCParser, "build_access_line",
+                               cbuild_access_line, 9);
 
     id_new             = rb_intern("new");
     id_downcase        = rb_intern("downcase");

data/lib/hyperion/admin_middleware.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'rack/utils'
+
+module Hyperion
+  # Rack middleware that exposes administrative endpoints on the same
+  # listener as the application. Disabled by default — only mounted when
+  # `admin_token` is configured. Currently provides:
+  #
+  #   POST /-/quit  →  triggers graceful master drain (SIGTERM to ppid)
+  #
+  # Auth: the request must include `X-Hyperion-Admin-Token: <token>`.
+  # Mismatch → 401. Path/method mismatch → falls through to the app
+  # (so the app can still own /-/anything if Hyperion's admin is off).
+  # When the token is unset, the constructor refuses to wrap — callers
+  # must skip mounting this middleware at all.
+  #
+  # SECURITY: the bearer token is defense-in-depth, not a substitute for
+  # network isolation. Operators MUST keep the listener on a private
+  # network or behind TLS + an authenticating reverse proxy. Anyone who
+  # can reach the listener AND knows the token can drain the server.
+  class AdminMiddleware
+    PATH = '/-/quit'
+
+    def initialize(app, token:, signal_target: nil)
+      raise ArgumentError, 'admin_token must be a non-empty String' if token.nil? || token.to_s.empty?
+
+      @app           = app
+      @token         = token.to_s
+      # Override hook for tests. Defaults to ppid in worker context, pid
+      # for single-worker context (caller decides).
+      @signal_target = signal_target
+    end
+
+    def call(env)
+      return @app.call(env) unless admin_request?(env)
+
+      provided = env['HTTP_X_HYPERION_ADMIN_TOKEN'].to_s
+      # Constant-time comparison. Rack::Utils.secure_compare requires same
+      # length, so prefix-pad first to avoid a length-leak side channel.
+      unless secure_match?(provided)
+        return [401, { 'content-type' => 'application/json' },
+                [%({"error":"unauthorized"}\n)]]
+      end
+
+      target = resolve_signal_target
+      Hyperion.logger.info { { message: 'admin drain requested', remote_addr: env['REMOTE_ADDR'], target_pid: target } }
+      begin
+        Process.kill('TERM', target)
+      rescue StandardError => e
+        Hyperion.logger.warn { { message: 'admin drain signal failed', error: e.message } }
+        return [500, { 'content-type' => 'application/json' }, [%({"error":"signal_failed"}\n)]]
+      end
+
+      [202, { 'content-type' => 'application/json' }, [%({"status":"draining"}\n)]]
+    end
+
+    private
+
+    def admin_request?(env)
+      env['PATH_INFO'] == PATH && env['REQUEST_METHOD'] == 'POST'
+    end
+
+    def secure_match?(provided)
+      return false if provided.empty?
+      return false unless provided.bytesize == @token.bytesize
+
+      Rack::Utils.secure_compare(provided, @token)
+    end
+
+    def resolve_signal_target
+      return @signal_target if @signal_target
+
+      # In a forked worker, ppid IS the master; in single-worker mode,
+      # the master + worker are the same process — signal self.
+      ppid = Process.ppid
+      ppid > 1 ? ppid : Process.pid
+    end
+  end
+end

data/lib/hyperion/cli.rb

@@ -53,6 +53,10 @@ module Hyperion
         o.on('--fiber-local-shim', 'Patch Thread.current[] to be fiber-local (Rails-compat for older gems)') do
           cli_opts[:fiber_local_shim] = true
         end
+        o.on('--[no-]yjit',
+             'Enable Ruby YJIT (default: auto on RAILS_ENV/RACK_ENV=production/staging)') do |v|
+          cli_opts[:yjit] = v
+        end
         o.on('-h', '--help', 'show help') do
           puts o
           exit 0
@@ -79,6 +83,11 @@ module Hyperion
       # 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)
 
@@ -88,6 +97,7 @@ module Hyperion
       end
 
       app = load_rack_app(rackup)
+      app = wrap_admin_middleware(app, config)
       workers = config.workers.zero? ? Etc.nprocessors : config.workers
 
       if workers <= 1
@@ -105,6 +115,7 @@ module Hyperion
       server.listen
       scheme = tls ? 'https' : 'http'
       Hyperion.logger.info { { message: 'listening', url: "#{scheme}://#{server.host}:#{server.port}" } }
+      warn_c_parser_unavailable
 
       # Single-worker mode reuses the lifecycle hooks: before_fork is a no-op
       # here (no fork happens), and on_worker_boot/on_worker_shutdown fire
@@ -130,6 +141,11 @@ module Hyperion
       server.start
       shutdown_thread.join
       config.on_worker_shutdown.each { |h| h.call(0) }
+      # Drain per-thread access buffers + sync stdio. Single-worker mode
+      # doesn't go through Master#shutdown_children, so without this call
+      # buffered access lines + final shutdown messages can be lost on
+      # SIGTERM. See Hyperion::Logger#flush_all.
+      Hyperion.logger.flush_all
     end
 
     def self.run_cluster(config, app, workers)
@@ -155,5 +171,58 @@ module Hyperion
       { cert: config.tls_cert, key: config.tls_key }
     end
     private_class_method :build_tls_from_config
+
+    # Decide whether to enable YJIT and flip the switch once at boot.
+    # Precedence:
+    #   1. config.yjit explicitly true/false  → honour exactly.
+    #   2. config.yjit nil (default)          → auto: on for production/staging.
+    # No-op on Rubies without YJIT (e.g. JRuby/TruffleRuby) and idempotent if
+    # the operator already passed `ruby --yjit` upstream.
+    def self.maybe_enable_yjit(config)
+      return unless defined?(::RubyVM::YJIT)
+      return if ::RubyVM::YJIT.enabled?
+
+      enable = if config.yjit.nil?
+                 env_name = ENV['HYPERION_ENV'] || ENV['RAILS_ENV'] || ENV['RACK_ENV']
+                 %w[production staging].include?(env_name)
+               else
+                 config.yjit
+               end
+
+      return unless enable
+
+      ::RubyVM::YJIT.enable
+      Hyperion.logger.info do
+        { message: 'YJIT enabled', mode: config.yjit.nil? ? 'auto' : 'explicit' }
+      end
+    end
+    private_class_method :maybe_enable_yjit
+
+    # When admin_token is configured, wrap the app in AdminMiddleware so
+    # POST /-/quit becomes a token-protected drain endpoint. Skipped when
+    # the token is unset — the path falls through to the app, so apps may
+    # still own /-/anything if Hyperion's admin is off.
+    def self.wrap_admin_middleware(app, config)
+      return app if config.admin_token.nil? || config.admin_token.to_s.empty?
+
+      Hyperion.logger.info { { message: 'admin endpoint enabled', path: AdminMiddleware::PATH } }
+      AdminMiddleware.new(app, token: config.admin_token)
+    end
+    private_class_method :wrap_admin_middleware
+
+    # 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.
+    def self.warn_c_parser_unavailable
+      return if Hyperion.c_parser_available?
+
+      Hyperion.logger.warn do
+        {
+          message: 'llhttp C parser not loaded — using pure-Ruby fallback (slower)',
+          remediation: 'rebuild the gem with `bundle exec rake compile` or check your OpenSSL/build-essential install'
+        }
+      end
+    end
+    private_class_method :warn_c_parser_unavailable
   end
 end

data/lib/hyperion/config.rb

@@ -24,7 +24,11 @@ module Hyperion
       log_level: nil, # nil → Logger picks from env / default
       log_format: nil, # nil → Logger picks via auto rule
       log_requests: nil, # nil → Hyperion.log_requests? (default true)
-      fiber_local_shim: false
+      fiber_local_shim: false,
+      yjit: nil, # nil → auto: enable on production/staging; true/false to force.
+      worker_max_rss_mb: nil, # Integer, e.g. 1024. When a worker exceeds this RSS in MB, master gracefully cycles it. nil disables.
+      worker_check_interval: 30, # Seconds between RSS polls. Tradeoff: tighter = faster recycle, more ps calls. 30s matches Puma WorkerKiller.
+      admin_token: nil # String. When set, POST /-/quit triggers graceful drain. nil disables endpoint entirely (returns 404).
     }.freeze
 
     HOOKS = %i[before_fork on_worker_boot on_worker_shutdown].freeze

data/lib/hyperion/connection.rb

@@ -69,6 +69,7 @@ module Hyperion
         carry = +(buffer.byteslice(body_end, buffer.bytesize - body_end) || '')
         request = enrich_with_peer(request, peer_addr) if peer_addr && request.peer_address.nil?
 
+        @metrics.increment(:bytes_read, body_end)
         @metrics.increment(:requests_total)
         @metrics.increment(:requests_in_flight)
         request_started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) if @log_requests

data/lib/hyperion/http2_handler.rb

@@ -36,33 +36,143 @@ module Hyperion
     # Also exposes a `window_available` notification fan-out so the
     # response-writer fiber can sleep until WINDOW_UPDATE arrives.
     class RequestStream < ::Protocol::HTTP2::Stream
-      attr_reader :request_headers, :request_body, :request_complete
+      # RFC 7540 §8.1.2.1 — the only pseudo-headers a server MUST accept on a
+      # request. Anything else (notably `:status`, which is response-only, or
+      # an unknown `:foo`) is a malformed request that we reject with
+      # PROTOCOL_ERROR.
+      VALID_REQUEST_PSEUDO_HEADERS = %w[:method :path :scheme :authority].freeze
+
+      # RFC 7540 §8.1.2.2 — these connection-specific headers MUST NOT appear
+      # in HTTP/2 requests; their semantics are folded into HTTP/2 framing.
+      FORBIDDEN_HEADERS = %w[connection transfer-encoding keep-alive upgrade proxy-connection].freeze
+
+      attr_reader :request_headers, :request_body, :request_complete, :protocol_error_reason
 
       def initialize(*)
         super
         @request_headers = []
         @request_body = +''
+        @request_body_bytes = 0
         @request_complete = false
         @window_available = ::Async::Notification.new
+        @protocol_error_reason = nil
+        @declared_content_length = nil
+      end
+
+      # Used by the dispatch loop to decide whether to invoke the app or
+      # send RST_STREAM PROTOCOL_ERROR. Set by `validate_request_headers!`
+      # and `validate_body_length!`.
+      def protocol_error?
+        !@protocol_error_reason.nil?
       end
 
       def process_headers(frame)
         decoded = super
+        # First HEADERS frame on a stream carries the request header block;
+        # any later HEADERS frame is trailers (§8.1) and we deliberately do
+        # not re-validate (re-running the validator would see the original
+        # request pseudo-headers plus the new trailer block and falsely flag
+        # them as misordered).
+        first_block = @request_headers.empty?
         # decoded is an Array of [name, value] pairs (HPACK output).
         decoded.each { |pair| @request_headers << pair }
-        @request_complete = true if frame.end_stream?
+        # Run RFC 7540 §8.1.2 validation as soon as we have a complete header
+        # block. We do it here (not at end_stream) so the dispatcher sees the
+        # error flag before it spawns a fiber for the request.
+        validate_request_headers! if first_block && !protocol_error?
+        if frame.end_stream?
+          validate_body_length! unless protocol_error?
+          @request_complete = true
+        end
         decoded
       end
 
       def process_data(frame)
         data = super
         # rubocop:disable Rails/Present
-        @request_body << data if data && !data.empty?
+        if data && !data.empty?
+          @request_body << data
+          @request_body_bytes += data.bytesize
+        end
         # rubocop:enable Rails/Present
-        @request_complete = true if frame.end_stream?
+        if frame.end_stream?
+          validate_body_length! unless protocol_error?
+          @request_complete = true
+        end
         data
       end
 
+      # RFC 7540 §8.1.2 — request header validation. Sets
+      # `@protocol_error_reason` on the first violation we hit; the dispatch
+      # loop turns that into RST_STREAM PROTOCOL_ERROR.
+      def validate_request_headers!
+        seen_regular = false
+        pseudo_counts = Hash.new(0)
+        @request_headers.each do |pair|
+          name, value = pair
+          name = name.to_s
+          if name.start_with?(':')
+            # §8.1.2.1: pseudo-headers MUST precede regular headers.
+            return fail_validation!('pseudo-header after regular header') if seen_regular
+            # §8.1.2.1: only the four request pseudo-headers are valid; in
+            # particular, `:status` is response-only.
+            unless VALID_REQUEST_PSEUDO_HEADERS.include?(name)
+              return fail_validation!("invalid request pseudo-header: #{name}")
+            end
+
+            pseudo_counts[name] += 1
+          else
+            seen_regular = true
+            # §8.1.2: header names must be lowercase in HTTP/2.
+            return fail_validation!('uppercase header name') if /[A-Z]/.match?(name)
+            # §8.1.2.2: connection-specific headers are forbidden.
+            return fail_validation!("forbidden connection-specific header: #{name}") if FORBIDDEN_HEADERS.include?(name)
+            # §8.1.2.2: TE may only carry the value `trailers`.
+            if name == 'te' && value.to_s.downcase.strip != 'trailers'
+              return fail_validation!('TE header with non-trailers value')
+            end
+
+            # Track declared content-length for later body-byte cross-check.
+            @declared_content_length = value.to_s.to_i if name == 'content-length'
+          end
+        end
+
+        # §8.1.2.3: every pseudo-header may appear at most once.
+        pseudo_counts.each do |name, count|
+          return fail_validation!("duplicated pseudo-header: #{name}") if count > 1
+        end
+
+        method = pseudo_value(':method')
+        # CONNECT (§8.3) has its own rules; everything else MUST carry
+        # :method, :scheme and a non-empty :path.
+        if method == 'CONNECT'
+          return fail_validation!('CONNECT with :scheme') if pseudo_value(':scheme')
+          return fail_validation!('CONNECT with :path') if pseudo_value(':path')
+          return fail_validation!('CONNECT without :authority') unless pseudo_value(':authority')
+        else
+          return fail_validation!('missing :method') if method.nil? || method.empty?
+
+          scheme = pseudo_value(':scheme')
+          return fail_validation!('missing :scheme') if scheme.nil? || scheme.empty?
+
+          path = pseudo_value(':path')
+          return fail_validation!('missing or empty :path') if path.nil? || path.empty?
+        end
+
+        nil
+      end
+
+      # RFC 7540 §8.1.2.6 — if `content-length` was advertised, the actual
+      # number of DATA bytes received (across all DATA frames) MUST match.
+      def validate_body_length!
+        return if @declared_content_length.nil?
+        return if @declared_content_length == @request_body_bytes
+
+        fail_validation!(
+          "content-length mismatch: declared #{@declared_content_length}, received #{@request_body_bytes}"
+        )
+      end
+
       # Called by protocol-http2 whenever the remote peer's flow-control
       # window opens up — either via a stream-level WINDOW_UPDATE or via the
       # connection-level fan-out in `Connection#consume_window`. We poke the
@@ -78,6 +188,28 @@ module Hyperion
       def wait_for_window
         @window_available.wait
       end
+
+      private
+
+      # Look up a pseudo-header by name (e.g. `:method`) by scanning the raw
+      # collected pairs. Returns nil if absent. We don't pre-build a hash
+      # because the validator needs to detect duplicates first.
+      def pseudo_value(name)
+        @request_headers.each do |pair|
+          return pair[1].to_s if pair[0].to_s == name
+        end
+        nil
+      end
+
+      # Record the first protocol-error reason and short-circuit further
+      # validation. Returns nil so callers can `return fail_validation!(...)`.
+      def fail_validation!(reason)
+        @protocol_error_reason ||= reason
+        # As soon as a header-block violation is detected we treat the request
+        # as "complete" so the dispatch loop wakes up and emits RST_STREAM.
+        @request_complete = true
+        nil
+      end
     end
 
     def initialize(app:, thread_pool: nil)
@@ -175,6 +307,23 @@ module Hyperion
     end
 
     def dispatch_stream(stream, send_mutex, 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?
+        @logger.debug do
+          { message: 'h2 request rejected', reason: stream.protocol_error_reason, stream_id: stream.id }
+        end
+        @metrics.increment(:requests_rejected)
+        begin
+          send_mutex.synchronize do
+            stream.send_reset_stream(::Protocol::HTTP2::Error::PROTOCOL_ERROR) unless stream.closed?
+          end
+        rescue StandardError
+          nil
+        end
+        return
+      end
+
       pseudo, regular = partition_pseudo(stream.request_headers)
 
       method    = pseudo[':method'] || 'GET'

data/lib/hyperion/logger.rb

@@ -64,6 +64,34 @@ module Hyperion
       # Colorize when format is text AND the destination is a TTY. We only
       # 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.
+      # 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
+      # registration on first allocation per thread (rare) and the shutdown
+      # walk; the hot #access path stays lock-free.
+      @access_buffers = []
+      @access_buffers_mutex = Mutex.new
+      # Per-instance thread-local key. A globally-shared key (e.g. a frozen
+      # Symbol constant) lets a buffer created by an earlier Logger in this
+      # thread be picked up by a later Logger — but the buffer is registered
+      # against the *earlier* Logger's @access_buffers, so the new Logger's
+      # #flush_all can't see it. Namespacing the key per-instance fixes that:
+      # each Logger gets its own per-thread buffer, and the registry it
+      # walks at shutdown matches the one #access wrote to. The Symbol is
+      # allocated once at construction; the hot path just reads it.
+      @buffer_key = :"__hyperion_access_buf_#{object_id}__"
+    end
+
+    # Whether Hyperion::CParser.build_access_line is available. Probed lazily
+    # on first call (the C parser is required after Logger is required, so we
+    # can't cache this at constant-define time — it would always be false).
+    # Memoised per-instance to keep the hot path branchless.
+    def c_access_available?
+      return @c_access_available unless @c_access_available.nil?
+
+      @c_access_available = defined?(::Hyperion::CParser) &&
+                            ::Hyperion::CParser.respond_to?(:build_access_line)
     end
 
     LEVELS.each_key do |lvl|
@@ -106,13 +134,23 @@ module Hyperion
       return unless emit?(:info)
 
       ts = cached_timestamp
-      line = if @format == :json
+      # The C extension builds the line in a stack scratch buffer (~10× faster
+      # than the Ruby interpolation path). It only fires when colorization is
+      # off — a colored TTY line needs ANSI escapes around the level label,
+      # 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?
+               ::Hyperion::CParser.build_access_line(@format, ts, method, path,
+                                                     query, status, duration_ms,
+                                                     remote_addr, http_version)
+             elsif @format == :json
                build_access_json(ts, method, path, query, status, duration_ms, remote_addr, http_version)
              else
                build_access_text(ts, method, path, query, status, duration_ms, remote_addr, http_version)
              end
 
-      buf = (Thread.current[:__hyperion_access_buf__] ||= +'')
+      buf = Thread.current[@buffer_key] || allocate_access_buffer
       buf << line
       return if buf.bytesize < ACCESS_FLUSH_BYTES
 
@@ -126,7 +164,7 @@ module Hyperion
     # loop when a connection closes (so log lines from a closing keep-alive
     # session don't get stuck behind the buffer until the next connection).
     def flush_access_buffer
-      buf = Thread.current[:__hyperion_access_buf__]
+      buf = Thread.current[@buffer_key]
       return if buf.nil? || buf.empty?
 
       @out.write(buf)
@@ -135,8 +173,61 @@ module Hyperion
       # Swallow logger failures — never let logging crash the server.
     end
 
+    # Flush every per-thread access-log buffer ever allocated through this
+    # Logger, then sync the underlying IOs.
+    #
+    # Why this exists: under SIGTERM, Master#shutdown_children logs the
+    # 'master draining' / 'master exiting' lines and then exits. The 'info'
+    # path doesn't go through the access buffer, but it does rely on glibc
+    # stdio buffering being flushed before the process dies — and per-thread
+    # access buffers (Thread.current[:__hyperion_access_buf__]) are *only*
+    # flushed when the buffer reaches ACCESS_FLUSH_BYTES or when the owning
+    # thread closes a connection. On a clean SIGTERM both can be missed and
+    # the operator sees nothing in the captured log. This method walks every
+    # registered per-thread buffer, writes any pending bytes, then calls
+    # IO#flush on @out / @err so the kernel sees them before exec_exit.
+    #
+    # Safe to call from any thread. Idempotent. Never raises.
+    def flush_all
+      buffers = @access_buffers_mutex.synchronize { @access_buffers.dup }
+      buffers.each do |buf|
+        next if buf.empty?
+
+        begin
+          @out.write(buf)
+          buf.clear
+        rescue StandardError
+          # Continue — one bad buffer must not block the rest.
+        end
+      end
+
+      flush_io(@out)
+      flush_io(@err) unless @err.equal?(@out)
+    rescue StandardError
+      # Swallow logger failures — never let logging crash the server.
+    end
+
     private
 
+    # First-touch path for a thread's access buffer. Allocates the String,
+    # stores it in the thread-local for lock-free access on subsequent calls,
+    # and registers it in @access_buffers so #flush_all can find it later.
+    # Mutex is taken once per thread (not per request).
+    def allocate_access_buffer
+      buf = +''
+      Thread.current[@buffer_key] = buf
+      @access_buffers_mutex.synchronize { @access_buffers << buf }
+      buf
+    end
+
+    def flush_io(io)
+      io.flush if io.respond_to?(:flush)
+    rescue StandardError
+      # Some IO destinations raise on flush (closed pipes during SIGPIPE,
+      # custom IO-likes that don't implement it cleanly). Logging must
+      # never crash the server, especially during shutdown.
+    end
+
     # Cached UTC iso8601(3) timestamp, refreshed at most once per millisecond
     # per thread. At 24k r/s with 16 threads we render ~1500 r/s/thread; only
     # ~1000 of those allocate a new String. The other 500 reuse the cached one.

data/lib/hyperion/master.rb

@@ -64,6 +64,10 @@ module Hyperion
       @stopping     = false
       @worker_model = self.class.detect_worker_model
       @listener     = nil # populated only in :share mode
+      @worker_max_rss_mb     = @config.worker_max_rss_mb
+      @worker_check_interval = @config.worker_check_interval || 30
+      @last_health_check     = 0  # monotonic seconds
+      @cycling               = {} # pid => true while we wait for it to exit
     end
 
     def run
@@ -165,6 +169,7 @@ module Hyperion
         end
 
         reap_and_respawn
+        maybe_cycle_workers
       end
 
       shutdown_children
@@ -177,12 +182,47 @@ module Hyperion
 
         Hyperion.logger.warn { { message: 'worker died, respawning', worker_pid: pid } }
         @children.delete(pid)
+        @cycling.delete(pid)
         spawn_worker unless @stopping
       end
     rescue Errno::ECHILD
       # No children — happens during shutdown.
     end
 
+    # Periodically poll worker RSS and SIGTERM any that exceed the configured
+    # cap. The dying worker is reaped by `reap_and_respawn` on the next tick,
+    # which also clears the @cycling guard so the slot can be replaced.
+    # Skips entirely when no cap is configured — zero overhead by default.
+    def maybe_cycle_workers
+      return unless @worker_max_rss_mb
+
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      return if now - @last_health_check < @worker_check_interval
+
+      @last_health_check = now
+      @children.each_key do |pid|
+        next if @cycling.key?(pid)
+
+        rss = WorkerHealth.rss_mb(pid)
+        next unless rss && rss > @worker_max_rss_mb
+
+        Hyperion.logger.warn do
+          {
+            message: 'cycling worker for memory',
+            worker_pid: pid,
+            rss_mb: rss,
+            limit_mb: @worker_max_rss_mb
+          }
+        end
+        @cycling[pid] = true
+        begin
+          Process.kill('TERM', pid)
+        rescue StandardError
+          # process already gone — reap_and_respawn will handle it
+        end
+      end
+    end
+
     def shutdown_children
       Hyperion.logger.info do
         { message: 'master draining', graceful_timeout: @graceful_timeout }
@@ -216,6 +256,11 @@ module Hyperion
       @children.clear
 
       Hyperion.logger.info { { message: 'master exiting' } }
+      # Drain per-thread access buffers + sync stdio so the 'master draining'
+      # / 'master exiting' lines (and any in-flight access-log lines from
+      # threads that never reached the 4-KiB flush threshold) actually reach
+      # the operator's log file before the process exits on SIGTERM.
+      Hyperion.logger.flush_all
     end
   end
 end

data/lib/hyperion/response_writer.rb

@@ -51,14 +51,18 @@ module Hyperion
       # SINGLE io.write call. Each syscall round-trip is ~1 usec on macOS
       # kqueue; before this change we issued (1 status) + (N headers) + (1 blank)
       # + (1 body) = 8+ syscalls per response. Now: 1 syscall.
-      if buffered.empty?
-        io.write(head)
-      else
-        # Concatenate into the head buffer (which is already a fresh +'' from
-        # the C builder or the Ruby fallback) so we still emit a single write.
-        head << buffered
-        io.write(head)
-      end
+      bytes_out = if buffered.empty?
+                    io.write(head)
+                    head.bytesize
+                  else
+                    # Concatenate into the head buffer (which is already a fresh +''
+                    # from the C builder or the Ruby fallback) so we still emit a
+                    # single write.
+                    head << buffered
+                    io.write(head)
+                    head.bytesize
+                  end
+      Hyperion.metrics.increment(:bytes_written, bytes_out)
     ensure
       body.close if body.respond_to?(:close)
     end
@@ -76,6 +80,19 @@ module Hyperion
       end
     end
 
+    # Cached HTTP `Date:` header at second resolution. `Time.now.httpdate`
+    # allocates several strings; at high r/s the cache reuses one String per
+    # second per thread instead of allocating per response.
+    def cached_date
+      now_s = Process.clock_gettime(Process::CLOCK_REALTIME, :second)
+      cache = (Thread.current[:__hyperion_date_cache__] ||= [-1, ''])
+      return cache[1] if cache[0] == now_s
+
+      cache[0] = now_s
+      cache[1] = Time.now.httpdate
+      cache[1]
+    end
+
     def build_head_ruby(status, reason, headers, body_size, keep_alive, date_str)
       normalized = {}
       headers.each { |k, v| normalized[k.to_s.downcase] = v }

data/lib/hyperion/server.rb

@@ -85,24 +85,17 @@ module Hyperion
       listen unless @server
       @thread_pool = ThreadPool.new(size: @thread_count) if @thread_count.positive?
 
-      Async do |task|
-        until @stopped
-          socket = accept_or_nil
-          next unless socket
-
-          apply_timeout(socket)
-          # Plain HTTP/1.1 with a pool: submit straight to the worker — no
-          # fiber wrap needed (submit_connection returns immediately and the
-          # worker thread owns the connection for its lifetime).
-          # TLS still goes through a fiber: ALPN negotiation determines h2
-          # vs http/1.1, and h2 needs the fiber because each stream is its
-          # own fiber inside Http2Handler.
-          if @thread_pool && !@tls
-            @thread_pool.submit_connection(socket, @app)
-          else
-            task.async { dispatch(socket) }
-          end
-        end
+      if @tls
+        # TLS path: ALPN may pick `h2`, and h2 spawns one fiber per stream
+        # inside Http2Handler. Keep the Async wrapper so the scheduler is
+        # available for those fibers and for handshake yields.
+        start_async_loop
+      else
+        # Plain HTTP/1.1: the worker thread owns each connection for its
+        # lifetime, so the Async wrapper adds zero value (no fibers ever
+        # run on this loop's task). Skip it — pure IO.select + accept_nonblock
+        # shaves measurable overhead off the accept hot path.
+        start_raw_loop
       end
     ensure
       @thread_pool&.shutdown
@@ -117,6 +110,39 @@ module Hyperion
 
     private
 
+    # Plain HTTP/1.1 accept loop — no fiber wrap. Connections go straight to
+    # a worker via the thread pool, or are served inline when no pool is
+    # configured (thread_count: 0). Matches the dispatch contract used by
+    # the TLS path; just skips the irrelevant h2/ALPN branch.
+    def start_raw_loop
+      until @stopped
+        socket = accept_or_nil
+        next unless socket
+
+        apply_timeout(socket)
+        if @thread_pool
+          @thread_pool.submit_connection(socket, @app)
+        else
+          Connection.new.serve(socket, @app)
+        end
+      end
+    end
+
+    # TLS / h2-capable accept loop. The Async wrapper is required because
+    # h2 streams (inside Http2Handler) and the ALPN handshake yield
+    # cooperatively via the scheduler.
+    def start_async_loop
+      Async do |task|
+        until @stopped
+          socket = accept_or_nil
+          next unless socket
+
+          apply_timeout(socket)
+          task.async { dispatch(socket) }
+        end
+      end
+    end
+
     def dispatch(socket)
       if socket.is_a?(::OpenSSL::SSL::SSLSocket) && socket.alpn_protocol == 'h2'
         # HTTP/2: each stream runs on a fiber inside Http2Handler. The

data/lib/hyperion/version.rb

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

data/lib/hyperion/worker_health.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Hyperion
+  # Measures a worker process's resident set size (RSS) in MiB.
+  # Cross-platform: uses /proc/<pid>/statm on Linux (zero subprocess) and
+  # `ps -o rss= -p <pid>` everywhere else (macOS, BSD).
+  module WorkerHealth
+    module_function
+
+    # Returns the worker's RSS in MiB, or nil if it can't be read (process
+    # gone, ps not available, /proc not mounted). Callers must handle nil
+    # gracefully — health checks must never crash the supervisor.
+    def rss_mb(pid)
+      if File.readable?("/proc/#{pid}/statm")
+        # statm fields are in pages; column index 1 is "resident".
+        # PAGE_SIZE = 4096 on x86_64 / aarch64 Linux.
+        contents = File.read("/proc/#{pid}/statm")
+        pages = contents.split.fetch(1).to_i
+        bytes = pages * 4096
+        bytes / 1024 / 1024
+      else
+        # Fallback: ps emits RSS in KiB.
+        out = `ps -o rss= -p #{pid} 2>/dev/null`
+        kib = out.strip.to_i
+        return nil if kib.zero?
+
+        kib / 1024
+      end
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/hyperion.rb

@@ -25,6 +25,23 @@ module Hyperion
       metrics.snapshot
     end
 
+    # Whether YJIT is currently enabled in this Ruby process. False on Rubies
+    # that don't ship YJIT (JRuby, TruffleRuby) and on CRuby builds compiled
+    # without YJIT support. Cheap (no allocations) — safe to call from hot
+    # paths if needed for diagnostics.
+    def yjit_enabled?
+      defined?(::RubyVM::YJIT) && ::RubyVM::YJIT.enabled?
+    end
+
+    # Whether the llhttp C extension loaded. False on JRuby/TruffleRuby and
+    # any environment where extconf.rb / make failed at install time. The
+    # pure-Ruby parser handles those cases correctly but is ~2× slower on
+    # parse-heavy workloads. Operators running production should confirm this
+    # returns true; CLI emits a startup banner if it doesn't.
+    def c_parser_available?
+      defined?(::Hyperion::CParser) && ::Hyperion::CParser.respond_to?(:build_response_head)
+    end
+
     # Per-request access logging is ON by default — matches Puma/Rails operator
     # expectations (Rails::Rack::Logger emits one line per request out of the
     # box). Operators can disable it via `--no-log-requests`,
@@ -72,6 +89,7 @@ require_relative 'hyperion/request'
 require_relative 'hyperion/parser'
 require_relative 'hyperion/c_parser'
 require_relative 'hyperion/adapter/rack'
+require_relative 'hyperion/admin_middleware'
 require_relative 'hyperion/response_writer'
 require_relative 'hyperion/thread_pool'
 require_relative 'hyperion/connection'
@@ -79,4 +97,5 @@ require_relative 'hyperion/tls'
 require_relative 'hyperion/http2_handler'
 require_relative 'hyperion/server'
 require_relative 'hyperion/worker'
+require_relative 'hyperion/worker_health'
 require_relative 'hyperion/master'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperion-rb
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Andrey Lobanov
@@ -148,6 +148,7 @@ files:
 - lib/hyperion-rb.rb
 - lib/hyperion.rb
 - lib/hyperion/adapter/rack.rb
+- lib/hyperion/admin_middleware.rb
 - lib/hyperion/c_parser.rb
 - lib/hyperion/cli.rb
 - lib/hyperion/config.rb
@@ -166,6 +167,7 @@ files:
 - lib/hyperion/tls.rb
 - lib/hyperion/version.rb
 - lib/hyperion/worker.rb
+- lib/hyperion/worker_health.rb
 homepage: https://github.com/andrew-woblavobla/hyperion
 licenses:
 - MIT
@@ -181,7 +183,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="