hyperion-rb 1.4.2 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd27fc15210a2436de9b88664413eeb7cd7cf129e0921f88d7d15edd87b76d11
-  data.tar.gz: 8dd98630e170ee1467197542d69d034b15aa1d1a1bc2441e780d3290c2c59f1d
+  metadata.gz: ab7691ac6671b0e0c9606c281c55659c76675b71f3d461d1fb5bf6a03680861b
+  data.tar.gz: b7ad35585d56e59d4a7b5c9fcb6d4e016e72b4c3f99496ba675ca7e871865718
 SHA512:
-  metadata.gz: a2ae7959ab5fe99207c2c53db22060385a6eeb3aad355d05b4b6f14b16c16d1057592eda2f63b2a72cbfeb62ec7ebae5ec5945f317e84a27c5bac9c6fdfbe614
-  data.tar.gz: 6fb3d77d7c631b98e366ef921859dcc9af1f5f2e3f6eb6e97bebfd9453f6403c6846d46c66628204785bd9c0253e01984696b59eab690c53a79f3238c6f1f15a
+  metadata.gz: 8911a91c7932b332a9d5f069099c7f6ded94d9b5978dffd259881ab482066d5328c508ca5983101c6d9d04b18c1353664766bf759ec66cb034d3bcdf84f01a89
+  data.tar.gz: 7c948c98eb9aea2cb31595e08deca0c4e98c2281105a18fc0419678da25a04ac9b04f9defe564ea660104cf935399582506eb87769f6f9fbbca74f568c8f904b

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [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

@@ -255,6 +255,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/lib/hyperion/adapter/rack.rb

@@ -138,7 +138,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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hyperion
-  VERSION = '1.4.2'
+  VERSION = '1.5.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.5.0
 platform: ruby
 authors:
 - Andrey Lobanov