hyperion-rb 2.12.0 → 2.14.0

data/lib/hyperion/metrics.rb

@@ -79,6 +79,30 @@ module Hyperion
       # Snapshot block hooks for gauges whose value is read on demand
       # (ThreadPool queue depth, etc.). `{ name => { labels_tuple => Proc } }`.
       @gauge_blocks    = {}
+
+      # 2.13-A — per-thread shards for the hot-path metrics that USED to
+      # take @hg_mutex on every observe / increment. The pre-2.13-A
+      # comment in `increment_labeled_counter` claimed those paths were
+      # "low-rate" — that turned out to be wrong: `tick_worker_request`
+      # fires once per Rack request, and `observe_histogram` fires once
+      # per request via the per-route duration histogram. Under -t 32
+      # the single mutex serialised every worker thread on the
+      # request-completion tail. Per-thread shards remove the
+      # contention; snapshots merge across threads under the mutex
+      # (snapshot is a low-rate operation — once per /-/metrics scrape).
+      #
+      # Thread-variable storage (NOT Thread.current[]) for the same
+      # reason as the unlabeled counter path: under an Async scheduler
+      # `Thread.current[:k]` is fiber-local, which would let snapshots
+      # miss observations made on a fiber that already exited.
+      @hg_thread_key   = :"__hyperion_metrics_hg_#{object_id}__"
+      @lc_thread_key   = :"__hyperion_metrics_lc_#{object_id}__"
+      # Holds direct references to every per-thread shard ever
+      # allocated through this Metrics instance (mirrors @thread_counters)
+      # so snapshots survive thread death.
+      @thread_histograms = []
+      @thread_labeled_counters = []
+      @hg_thread_mutex         = Mutex.new
     end
 
     # Hot path: one thread-variable lookup + one hash op. No mutex on the
@@ -162,6 +186,12 @@ module Hyperion
     end
 
     # Tests can call .reset! between examples to avoid cross-spec leakage.
+    #
+    # 2.13-A — also clear per-thread histogram and labeled-counter
+    # shards. Without this, an observation made on thread A in spec X
+    # would leak into spec Y's snapshot because the shard hashes are
+    # held alive by `@thread_histograms` / `@thread_labeled_counters`
+    # for the lifetime of the Metrics instance.
     def reset!
       @counters_mutex.synchronize do
         @thread_counters.each(&:clear)
@@ -171,6 +201,10 @@ module Hyperion
         @gauges.each_value(&:clear)
         @gauge_blocks.each_value(&:clear)
       end
+      @hg_thread_mutex.synchronize do
+        @thread_histograms.each(&:clear)
+        @thread_labeled_counters.each(&:clear)
+      end
     end
 
     # ---- 2.4-C histogram + gauge API ---------------------------------
@@ -197,27 +231,37 @@ module Hyperion
 
     # Observe `value` on a previously-registered histogram. `label_values`
     # MUST be supplied in the same order as `label_keys` at registration.
-    # The hot path: one Hash lookup, one accumulator update under a mutex.
-    # Allocation footprint per observe: zero on the cached-key path
-    # (same labels seen before); one frozen Array on first observation
-    # for a given label-set.
+    #
+    # 2.13-A — Hot-path lock-free shard. Each thread keeps its own
+    # `{ name => { labels => HistogramAccumulator } }` map; observations
+    # never block on `@hg_mutex`. Snapshots merge across threads under
+    # the mutex (low-rate). Allocation footprint per observe: zero on
+    # the cached-key path; one frozen Array + one HistogramAccumulator
+    # on first observation for a given (name, label-set, thread).
+    #
+    # Bench impact (generic Rack hello, -t 32 -c 100):
+    # contention on `@hg_mutex` was the dominant tail latency
+    # contributor — this fires once per request via the per-route
+    # request-duration histogram, multiplied by N worker threads.
     def observe_histogram(name, value, label_values = EMPTY_LABELS)
-      @hg_mutex.synchronize do
-        meta = @histograms_meta[name]
-        return unless meta # silently skip unregistered observations
-
-        family = @histograms[name]
-        accum  = family[label_values]
-        unless accum
-          accum = HistogramAccumulator.new(meta[:buckets])
-          # Freeze the label tuple so future identical-content tuples
-          # hash to the same bucket — but we keep the original ref
-          # provided by the caller as the canonical key so subsequent
-          # observes with the same Array bypass the freeze step.
-          family[label_values.frozen? ? label_values : label_values.dup.freeze] = accum
-        end
-        accum.observe(value)
+      meta = @histograms_meta[name]
+      return unless meta # silently skip unregistered observations
+
+      thread = Thread.current
+      shard = thread.thread_variable_get(@hg_thread_key)
+      shard = register_thread_histograms(thread) if shard.nil?
+
+      family = (shard[name] ||= {})
+      accum  = family[label_values]
+      unless accum
+        accum = HistogramAccumulator.new(meta[:buckets])
+        # Freeze the label tuple so future identical-content tuples
+        # hash to the same bucket — but we keep the original ref
+        # provided by the caller as the canonical key so subsequent
+        # observes with the same Array bypass the freeze step.
+        family[label_values.frozen? ? label_values : label_values.dup.freeze] = accum
       end
+      accum.observe(value)
     end
 
     # Set a gauge value. `label_values` follows the same convention as
@@ -263,15 +307,40 @@ module Hyperion
 
     # Snapshot helpers — read-only views of the current histogram /
     # gauge state. The exporter uses these to render the scrape body.
+    #
+    # 2.13-A — Histograms merge across the per-thread shards on the
+    # snapshot path. The mutex is held only long enough to copy the
+    # shard list (every shard Hash is owned by one thread, so we can
+    # iterate its current contents safely while merging — torn reads
+    # of in-progress observations show as a slightly stale snapshot,
+    # never as a corrupted Accumulator).
     def histogram_snapshot
       out = {}
+
+      # Pre-seed names from registered families so a histogram with
+      # zero observations still appears in the scrape (matches the
+      # pre-2.13-A behaviour where `register_histogram` populated the
+      # `@histograms[name] = {}` slot eagerly).
       @hg_mutex.synchronize do
-        @histograms.each do |name, family|
-          per_labels = {}
-          family.each { |labels, accum| per_labels[labels] = accum.snapshot }
-          out[name] = { meta: @histograms_meta[name], series: per_labels }
+        @histograms_meta.each_key { |name| out[name] = { meta: @histograms_meta[name], series: {} } }
+      end
+
+      shards = @hg_thread_mutex.synchronize { @thread_histograms.dup }
+      shards.each do |shard|
+        shard.each do |name, family|
+          slot = (out[name] ||= { meta: @histograms_meta[name], series: {} })
+          series = slot[:series]
+          family.each do |labels, accum|
+            existing = series[labels]
+            if existing.nil?
+              series[labels] = accum.snapshot
+            else
+              merge_histogram_snapshot!(existing, accum)
+            end
+          end
         end
       end
+
       out
     end
 
@@ -309,19 +378,33 @@ module Hyperion
 
     # Labeled counter — separate from the legacy thread-local counter
     # surface (which is unlabeled and per-thread for hot-path
-    # contention-free increments). Labeled counters take a mutex per
-    # increment, but they're called from low-rate paths (per-conn
-    # rejection ~ kHz worst case, vs M+req/s on the unlabeled side)
-    # so the contention cost is invisible.
+    # contention-free increments).
+    #
+    # 2.13-A — moved to a per-thread shard for the same reason as
+    # `observe_histogram`: the previous "low-rate paths" claim was wrong
+    # (`tick_worker_request` is per-Rack-request), and at -t 32 the
+    # single mutex serialised every worker thread on the request-
+    # completion tail. Per-thread shards remove the contention;
+    # `labeled_counter_snapshot` merges shards under the mutex.
     def increment_labeled_counter(name, label_values = EMPTY_LABELS, by = 1)
-      @hg_mutex.synchronize do
-        @labeled_counters_meta ||= {}
-        @labeled_counters_meta[name] ||= { label_keys: [].freeze }
-        @labeled_counters ||= {}
-        family = (@labeled_counters[name] ||= {})
-        key    = label_values.frozen? ? label_values : label_values.dup.freeze
-        family[key] = (family[key] || 0) + by
+      thread = Thread.current
+      shard = thread.thread_variable_get(@lc_thread_key)
+      shard = register_thread_labeled_counters(thread) if shard.nil?
+
+      # Defensive: ensure the family meta exists so `register_labeled_counter`
+      # is not strictly required for hot-path increments. Pre-2.13-A the
+      # mutex'd path lazily registered an unlabeled meta; we mirror that
+      # under @hg_mutex so the shape stays consistent across threads.
+      unless @labeled_counters_meta && @labeled_counters_meta[name]
+        @hg_mutex.synchronize do
+          @labeled_counters_meta ||= {}
+          @labeled_counters_meta[name] ||= { label_keys: [].freeze }
+        end
       end
+
+      family = (shard[name] ||= {})
+      key    = label_values.frozen? ? label_values : label_values.dup.freeze
+      family[key] = (family[key] || 0) + by
     end
 
     def register_labeled_counter(name, label_keys: [])
@@ -333,14 +416,27 @@ module Hyperion
       end
     end
 
+    # 2.13-A — Snapshot merges per-thread shards. Pre-seeded with
+    # `@labeled_counters_meta` so registered-but-unticked families still
+    # show up in the scrape (matches pre-2.13-A behaviour where
+    # `register_labeled_counter` eagerly created the `[name] = {}` slot).
     def labeled_counter_snapshot
       out = {}
       @hg_mutex.synchronize do
-        (@labeled_counters || {}).each do |name, family|
-          per_labels = {}
-          family.each { |labels, count| per_labels[labels] = count }
+        (@labeled_counters_meta || {}).each do |name, meta|
+          out[name] = { meta: meta, series: {} }
+        end
+      end
+
+      shards = @hg_thread_mutex.synchronize { @thread_labeled_counters.dup }
+      shards.each do |shard|
+        shard.each do |name, family|
           meta = (@labeled_counters_meta || {})[name] || { label_keys: [].freeze }
-          out[name] = { meta: meta, series: per_labels }
+          slot = (out[name] ||= { meta: meta, series: {} })
+          series = slot[:series]
+          family.each do |labels, count|
+            series[labels] = (series[labels] || 0) + count
+          end
         end
       end
       out
@@ -392,6 +488,46 @@ module Hyperion
       @counters_mutex.synchronize { @thread_counters << counters }
       counters
     end
+
+    # 2.13-A — allocate this thread's histogram shard and register it
+    # in `@thread_histograms` so snapshots find it. Idempotent per
+    # thread: callers always check `thread_variable_get` first.
+    def register_thread_histograms(thread)
+      shard = {}
+      thread.thread_variable_set(@hg_thread_key, shard)
+      @hg_thread_mutex.synchronize { @thread_histograms << shard }
+      shard
+    end
+
+    # 2.13-A — same shape as register_thread_histograms but for labeled
+    # counters. Each thread gets its own `{ name => { labels => Integer } }`
+    # map; the snapshot path merges across shards.
+    def register_thread_labeled_counters(thread)
+      shard = {}
+      thread.thread_variable_set(@lc_thread_key, shard)
+      @hg_thread_mutex.synchronize { @thread_labeled_counters << shard }
+      shard
+    end
+
+    # 2.13-A — fold a per-thread HistogramAccumulator's contents into an
+    # already-snapshotted entry (`{buckets:, counts:, sum:, count:}`).
+    # Both arguments share the same `:buckets` so the bucket index axis
+    # is identical; we sum `counts` per bucket plus the scalars. Used
+    # when two threads observed the SAME (name, labels) pair — a
+    # legitimate steady state on a Rack route hit by concurrent
+    # workers.
+    def merge_histogram_snapshot!(existing, accum)
+      counts = existing[:counts]
+      acc_counts = accum.counts
+      i = 0
+      len = counts.length
+      while i < len
+        counts[i] += acc_counts[i]
+        i += 1
+      end
+      existing[:sum]   += accum.sum
+      existing[:count] += accum.count
+    end
   end
 end
 

data/lib/hyperion/server/connection_loop.rb

@@ -34,6 +34,92 @@ module Hyperion
     module ConnectionLoop
       module_function
 
+      # 2.14-B — bound applied to the wake-connect dial inside
+      # `Server#stop`. The listener is local — a successful connect
+      # is sub-millisecond — so the cap exists purely as a sanity
+      # bound for the pathological case where the listener was
+      # already torn down (Errno::ECONNREFUSED is fast) or the
+      # kernel netstack is somehow stuck (e.g. CI under heavy load).
+      WAKE_CONNECT_TIMEOUT_SECONDS = 1.0
+
+      # 2.14-B — number of wake-connect dials issued per `Server#stop`.
+      # In single-server / `:share` cluster mode (Darwin/BSD), one dial
+      # is enough — the listener is shared and any wake races to a
+      # parked accept call. In `:reuseport` cluster mode (Linux), the
+      # kernel hashes incoming SYNs across each worker's per-process
+      # listener fd; one dial may hash to a sibling whose stop hasn't
+      # progressed, leaving THIS worker's accept thread parked. K=8
+      # drops the miss probability to <1% for realistic worker counts
+      # (≤32 workers per host) and adds at most ~8ms to a stop call —
+      # well below the master-side `graceful_timeout` (30s default).
+      WAKE_CONNECT_BURST = 8
+
+      # 2.14-B — Wake any thread parked in `accept(2)` on the listener
+      # bound at `host:port` by dialing one (or `count`) throwaway TCP
+      # connections.
+      #
+      # Background. On Linux ≥ 6.x, calling `close()` on a listening
+      # socket from one thread does NOT interrupt another thread that
+      # is currently blocked in `accept(2)` on that same fd — the
+      # kernel silently dropped the close-wake guarantee that
+      # `Server#stop` (and 2.13-C's spec teardown) had relied on.
+      # Without this helper, the C accept loop stays parked until a
+      # real connection arrives, which during a SIGTERM-driven graceful
+      # shutdown means "until SIGKILL".
+      #
+      # The fix is structural: dial a throwaway TCP connection at the
+      # listener's bound address. The accept call returns with the new
+      # fd, the C loop services it (a 0-byte read drops it), then
+      # re-checks `hyp_cl_stop` between accepts and exits cleanly. The
+      # 2.13-C connection_loop_spec helper does the same thing in spec
+      # land — this is the production-side mirror.
+      #
+      # Burst semantics. With SO_REUSEPORT (Linux cluster mode), the
+      # kernel hashes each SYN to one of the N still-open per-worker
+      # listeners. A single dial from worker A may hash to worker B —
+      # leaving A's parked accept un-woken. Dialing K times (default
+      # `WAKE_CONNECT_BURST`) drives the miss probability down to
+      # negligible for typical worker counts.
+      #
+      # Failure-tolerant by construction:
+      # * `Errno::ECONNREFUSED` — listener already closed (the close
+      #   raced ahead of us). Nothing to wake; bail out of the burst
+      #   so we don't spend the timeout budget on doomed dials.
+      # * `Errno::EADDRNOTAVAIL` — interface gone. Same.
+      # * Connect timeout — kernel netstack is stuck; we tried, the
+      #   caller's `thread.join(timeout)` will surface the symptom.
+      # * Any other socket error — log nothing (we may be running
+      #   inside a signal handler thread); just swallow.
+      def wake_listener(host, port, connect_timeout: WAKE_CONNECT_TIMEOUT_SECONDS,
+                        count: 1)
+        return unless host && port
+        return if count <= 0
+
+        count.times do
+          break unless dial_wake_once(host, port, connect_timeout)
+        end
+        nil
+      end
+
+      # 2.14-B — single dial. Returns true on success (continue
+      # bursting), false on a "listener gone" outcome (abort the burst
+      # so we don't waste the timeout budget on N×ECONNREFUSED).
+      def dial_wake_once(host, port, connect_timeout)
+        ::Socket.tcp(host, port, connect_timeout: connect_timeout, &:close)
+        true
+      rescue Errno::ECONNREFUSED, Errno::EADDRNOTAVAIL, Errno::EHOSTUNREACH,
+             Errno::ENETUNREACH
+        # Listener gone — no point retrying, the kernel will refuse
+        # every dial in this burst the same way.
+        false
+      rescue Errno::ETIMEDOUT, Errno::ECONNRESET, Errno::EPIPE,
+             Errno::EBADF, IOError, SocketError
+        # Transient — keep bursting in case a later dial races into a
+        # still-open sibling listener (REUSEPORT cluster mode).
+        true
+      end
+      private_class_method :dial_wake_once
+
       # Whether the C accept loop is available and the env didn't
       # disable it.
       def available?
@@ -78,20 +164,32 @@ module Hyperion
         %w[1 on true yes].include?(env.downcase)
       end
 
-      # Whether the route table is C-loop eligible: only `StaticEntry`
-      # handlers, at least one of them, no dynamic handlers anywhere.
+      # Whether the route table is C-loop eligible: every registered
+      # entry is either a `StaticEntry` (2.12-C path) or a
+      # `DynamicBlockEntry` (2.14-A path), and the table has at least
+      # one of either. Legacy `Server.handle(method, path, handler)`
+      # registrations (where `handler` takes a `Hyperion::Request`)
+      # disable the C path — those still flow through `Connection#serve`.
       def eligible_route_table?(route_table)
         return false unless route_table
 
-        any_static = false
+        any_eligible = false
         route_table.instance_variable_get(:@routes).each_value do |path_table|
           path_table.each_value do |handler|
-            return false unless handler.is_a?(::Hyperion::Server::RouteTable::StaticEntry)
+            return false unless eligible_entry?(handler)
 
-            any_static = true
+            any_eligible = true
           end
         end
-        any_static
+        any_eligible
+      end
+
+      # 2.14-A — predicate split out so specs and the engagement check
+      # can introspect single entries. Lives here (rather than on the
+      # entry classes) so the eligibility surface stays in one place.
+      def eligible_entry?(handler)
+        handler.is_a?(::Hyperion::Server::RouteTable::StaticEntry) ||
+          handler.is_a?(::Hyperion::Server::RouteTable::DynamicBlockEntry)
       end
 
       # Build a lifecycle callback that, when invoked from the C loop

data/lib/hyperion/server/route_table.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'stringio'
+
 module Hyperion
   class Server
     # 2.10-D — direct-dispatch route registry.  Mirrors agoo's
@@ -86,6 +88,68 @@ module Hyperion
         end
       end
 
+      # 2.14-A — wrapper for a Rack-style block registered via
+      # `Server.handle(:GET, '/path') { |env| [...] }`.  Differs from
+      # `StaticEntry` in that the response is computed per-request
+      # rather than baked at registration time — but the route table
+      # entry shape is uniform, so the C accept loop can branch on
+      # `is_a?(DynamicBlockEntry)` AFTER the StaticEntry check and
+      # invoke the block via the registered C-loop dispatch helper.
+      #
+      # The struct holds:
+      #   * `method` — request-method symbol (`:GET`, `:POST`, ...)
+      #   * `path`   — exact-match path String (frozen)
+      #   * `block`  — the registered Proc / lambda; receives a Rack
+      #     env hash and must return a `[status, headers, body]`
+      #     triple per the Rack spec.  The C accept loop hands it a
+      #     populated env via the `Adapter::Rack.dispatch_for_c_loop`
+      #     helper; the block sees the same env shape Rack apps
+      #     normally see (HTTP_*, REQUEST_METHOD, PATH_INFO, etc.).
+      #
+      # Calling the entry directly (the legacy fall-through path used
+      # when the C accept loop is NOT engaged — TLS listeners, mixed
+      # tables, operator escape hatch via `HYPERION_C_ACCEPT_LOOP=0`)
+      # delegates straight to the block with a freshly-built env via
+      # the existing `Adapter::Rack#call` machinery.  The Connection
+      # path's direct-route dispatcher already handles
+      # `respond_to?(:call)` entries by invoking them with a
+      # `Hyperion::Request` value object — we route through that
+      # surface so the legacy fallback stays bit-identical to a
+      # 2.13-shape `Server.handle` registration.
+      DynamicBlockEntry = Struct.new(:method, :path, :block) do
+        # Legacy direct-route surface: `RouteTable#lookup` → handler →
+        # `handler.call(request)` returning a `[status, headers, body]`
+        # triple. Used by the Connection path when the C accept loop is
+        # disengaged (TLS, mixed tables). We hand the block a minimal
+        # env hash so it sees the same Rack-style API regardless of
+        # which dispatch shape served the request.
+        def call(request)
+          env = build_legacy_env(request)
+          block.call(env)
+        end
+
+        private
+
+        def build_legacy_env(request)
+          headers = request.respond_to?(:headers) ? (request.headers || {}) : {}
+          env = {
+            'REQUEST_METHOD' => request.method,
+            'PATH_INFO' => request.path,
+            'QUERY_STRING' => request.query_string.to_s,
+            'SERVER_NAME' => 'localhost',
+            'SERVER_PORT' => '80',
+            'rack.input' => StringIO.new(request.body.to_s),
+            'rack.errors' => $stderr,
+            'rack.url_scheme' => 'http'
+          }
+          headers.each do |name, value|
+            key = "HTTP_#{name.to_s.upcase.tr('-', '_')}"
+            env[key] = value
+          end
+          env
+        end
+      end
+
       def initialize
         # Per-method Hash so the lookup is `@routes[:GET][path]`
         # — two integer-keyed-Hash hits.  Pre-allocate the seven