hyperion-rb 1.4.1 → 1.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64221d424c994e0757262dca6984cd2b65bf9ec3da6c85094daa717c716da906
-  data.tar.gz: 236188ff1777b49178bb4b2bfe75fbea9309ec6f5d56ec01329943dfa1afbb36
+  metadata.gz: fd27fc15210a2436de9b88664413eeb7cd7cf129e0921f88d7d15edd87b76d11
+  data.tar.gz: 8dd98630e170ee1467197542d69d034b15aa1d1a1bc2441e780d3290c2c59f1d
 SHA512:
-  metadata.gz: 9b196f8d046c828546f8f5fbac91e0300e8704a70f11b47096a9b0fb05caf2ec34f63e2f33768ab53b41413aaa4e957ac499aa4779ecd54b6a987deef7fd464e
-  data.tar.gz: cb3d64f757736bcbc2632492e24b0794a67c98bfdcae7a1e53d89f583cf2eecc404e060fd3ec10e441ddfdcd11273c41e0d46fa9b80be904b29a7718fe0258ba
+  metadata.gz: a2ae7959ab5fe99207c2c53db22060385a6eeb3aad355d05b4b6f14b16c16d1057592eda2f63b2a72cbfeb62ec7ebae5ec5945f317e84a27c5bac9c6fdfbe614
+  data.tar.gz: 6fb3d77d7c631b98e366ef921859dcc9af1f5f2e3f6eb6e97bebfd9453f6403c6846d46c66628204785bd9c0253e01984696b59eab690c53a79f3238c6f1f15a

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [1.4.2] - 2026-04-27
+
+Audit-driven cleanup. No behaviour changes; fiber-correctness + docs polish.
+
+### Fixed
+- **`Hyperion::Logger` access buffer was fiber-local, not thread-local** — pre-1.4.2 the access-log write buffer was stored via `Thread.current[@buffer_key]`. Under an `Async::Scheduler` (TLS / h2 / `--async-io` plain HTTP/1.1) every handler fiber got its own private buffer, so the 4 KiB `ACCESS_FLUSH_BYTES` batching never fired — each fiber's buffer accumulated 1-3 lines before its connection closed and `flush_access_buffer` wrote them. At 24k r/s this meant ~12-24k `write(2)` syscalls/sec instead of the designed ~750/sec. Switched to `Thread#thread_variable_*` so all fibers on the same OS thread share one buffer and the batching actually fires. Same root cause as the 1.4.1 Metrics fix; surfaced by a code-audit grep for residual `Thread.current[:key]` patterns.
+- **`Logger#cached_timestamp` and `ResponseWriter#cached_date`** — same fix. Pre-1.4.2 the per-second / per-millisecond Time-formatting caches were per-fiber, so under Async every fiber rebuilt the iso8601 / httpdate String on its first call after a tick. Now per-OS-thread, shared across fibers; one allocation per second per thread total.
+
+### Added
+- **Prometheus exporter example output** in the README's Metrics section — shows what `curl -H 'X-Hyperion-Admin-Token: ...' /-/metrics` actually returns (HELP/TYPE lines, status-code labels, auto-export of unknown counters), plus the Prometheus scraper config sketch.
+- **Regression spec** for the access-buffer cross-fiber bug — two fibers on the same OS thread write through one logger; verifies a single buffer is registered (not one per fiber) and both lines land via `flush_all`.
+- **4 new Metrics specs** (already shipped in 1.4.1; called out here for coverage tracking) — cross-fiber on same thread, cross-thread, cross-fiber-on-different-thread, many-fibers-on-same-thread.
+
+### Changed
+- **README benchmark section** version-stamped: clarifies that the headline numbers were measured against the noted Hyperion version (most are 1.2.0 hello-world / 1.3.0 PG-bound) and that 1.3.0+ `--async-io` + 1.4.0+ TLS-inline + 1.4.1+ Metrics fix preserve or improve these numbers. We re-run the headline configs each release.
+
 ## [1.4.1] - 2026-04-27
 
 ### Fixed

data/README.md

@@ -25,7 +25,7 @@ bundle exec hyperion config.ru
 
 ## Benchmarks
 
-All numbers are real wrk runs against published Hyperion configs. Hyperion ships **with default-ON structured access logs**; Puma comparisons use Puma defaults (no per-request log emission).
+All numbers are real wrk runs against published Hyperion configs. Hyperion ships **with default-ON structured access logs**; Puma comparisons use Puma defaults (no per-request log emission). Each section is stamped with the Hyperion version it was measured against — newer versions (1.3.0+ `--async-io`, 1.4.0+ TLS h1 inline, 1.4.1+ Metrics fiber-key fix) preserve or improve these numbers; we re-run the headline configs each release and have not seen regressions on these workloads.
 
 ### Hello-world Rack app
 
@@ -363,6 +363,31 @@ Hyperion.stats
 # => {connections_accepted: 1234, connections_active: 7, requests_total: 8910, …}
 ```
 
+### Prometheus exporter
+
+When `admin_token` is set in your config, Hyperion mounts a `/-/metrics` endpoint that emits Prometheus text-format v0.0.4. Same token guards both `/-/metrics` (GET) and `/-/quit` (POST); auth is via the `X-Hyperion-Admin-Token` header.
+
+```sh
+$ curl -s -H 'X-Hyperion-Admin-Token: secret' http://127.0.0.1:9292/-/metrics
+# HELP hyperion_requests_total Total HTTP requests handled
+# TYPE hyperion_requests_total counter
+hyperion_requests_total 8910
+# HELP hyperion_bytes_written_total Total bytes written to response sockets
+# TYPE hyperion_bytes_written_total counter
+hyperion_bytes_written_total 2351023
+# HELP hyperion_responses_status_total Responses by HTTP status code
+# TYPE hyperion_responses_status_total counter
+hyperion_responses_status_total{status="200"} 8521
+hyperion_responses_status_total{status="404"} 12
+hyperion_responses_status_total{status="500"} 3
+# … and so on for sendfile_responses_total, rejected_connections_total,
+# slow_request_aborts_total, requests_async_dispatched_total, etc.
+```
+
+Any counter not in the known set (added by app middleware via `Hyperion.metrics.increment(:custom_thing)`) is auto-exported as `hyperion_custom_thing` with a generic HELP line — no Hyperion config change required.
+
+Point your scraper at it: in Prometheus' `scrape_configs`, set `metrics_path: /-/metrics` and `bearer_token` (or use a custom header relabel — Prometheus 2.42+ supports `authorization.credentials_file` paired with a custom `header` block). Network-isolate the admin endpoints if the listener is internet-facing — see [docs/REVERSE_PROXY.md](docs/REVERSE_PROXY.md) for the nginx `location /-/ { return 404; }` recipe.
+
 ## TLS + HTTP/2
 
 Provide a PEM cert + key:

data/lib/hyperion/logger.rb

@@ -150,7 +150,7 @@ module Hyperion
                build_access_text(ts, method, path, query, status, duration_ms, remote_addr, http_version)
              end
 
-      buf = Thread.current[@buffer_key] || allocate_access_buffer
+      buf = Thread.current.thread_variable_get(@buffer_key) || allocate_access_buffer
       buf << line
       return if buf.bytesize < ACCESS_FLUSH_BYTES
 
@@ -164,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[@buffer_key]
+      buf = Thread.current.thread_variable_get(@buffer_key)
       return if buf.nil? || buf.empty?
 
       @out.write(buf)
@@ -215,7 +215,7 @@ module Hyperion
     # Mutex is taken once per thread (not per request).
     def allocate_access_buffer
       buf = +''
-      Thread.current[@buffer_key] = buf
+      Thread.current.thread_variable_set(@buffer_key, buf)
       @access_buffers_mutex.synchronize { @access_buffers << buf }
       buf
     end
@@ -229,11 +229,21 @@ module Hyperion
     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.
+    # per OS 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. Stored as a thread variable (truly thread-local across
+    # fibers) so under Async every fiber on this thread shares the same
+    # cache and the per-second amortisation actually fires; with the prior
+    # `Thread.current[:k]` storage each fiber would re-build the iso8601
+    # String on its first call after a millisecond tick.
     def cached_timestamp
       now_ms = Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
-      cache = (Thread.current[:__hyperion_ts_cache__] ||= [-1, ''])
+      thread = Thread.current
+      cache = thread.thread_variable_get(:__hyperion_ts_cache__)
+      if cache.nil?
+        cache = [-1, '']
+        thread.thread_variable_set(:__hyperion_ts_cache__, cache)
+      end
       return cache[1] if cache[0] == now_ms
 
       cache[0] = now_ms

data/lib/hyperion/response_writer.rb

@@ -142,10 +142,19 @@ module Hyperion
 
     # 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.
+    # second per OS thread instead of allocating per response. Stored as a
+    # thread variable (truly thread-local across fibers) so under Async
+    # every fiber on this thread shares the same cache — otherwise each
+    # fiber would rebuild the httpdate String on its first response after
+    # a second tick.
     def cached_date
       now_s = Process.clock_gettime(Process::CLOCK_REALTIME, :second)
-      cache = (Thread.current[:__hyperion_date_cache__] ||= [-1, ''])
+      thread = Thread.current
+      cache = thread.thread_variable_get(:__hyperion_date_cache__)
+      if cache.nil?
+        cache = [-1, '']
+        thread.thread_variable_set(:__hyperion_date_cache__, cache)
+      end
       return cache[1] if cache[0] == now_s
 
       cache[0] = now_s

data/lib/hyperion/version.rb

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

metadata

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