hyperion-rb 1.6.2 → 2.11.0

data/lib/hyperion/runtime.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module Hyperion
+  # Runtime services container — holds per-process or per-server services
+  # (metrics sink, logger, clock) that used to live as module-level
+  # singletons on `Hyperion`.
+  #
+  # Pre-1.7 every Connection / Http2Handler / ResponseWriter reached for
+  # `Hyperion.metrics` / `Hyperion.logger` directly. That made:
+  #
+  #   1. Long-lived keep-alive connections impossible to swap services on
+  #      mid-flight — `Connection#initialize` cached the singletons in ivars
+  #      and never re-read them.
+  #   2. Multi-tenant apps unable to give each `Hyperion::Server` its own
+  #      metrics sink — the module-level singleton is process-global.
+  #   3. Tests messy: stubbing `Hyperion.metrics` is global state mutation
+  #      that bleeds across examples unless every spec resets explicitly.
+  #
+  # 1.7.0 introduces this Runtime and adds a `runtime:` kwarg to `Server`
+  # and `Connection`. The default is `Runtime.default`, a process-wide
+  # singleton — back-compat with the 1.6.x behaviour. Tests and library
+  # users construct their own `Runtime.new(metrics: …, logger: …)` and
+  # pass it explicitly; that runtime is then used exclusively by the
+  # connection/server it was given to.
+  #
+  # `Runtime.default` is intentionally NOT frozen after first read.
+  # RFC §5 Q4: tests need to swap metrics/logger on the default runtime,
+  # and freezing for no real safety benefit just adds ceremony.
+  #
+  # Module-level `Hyperion.metrics` / `Hyperion.logger` (and their
+  # writers) keep working — they delegate to `Runtime.default`. They're
+  # marked for deprecation in 1.8.0 and removal in 2.0.
+  class Runtime
+    attr_reader :clock
+    attr_writer :metrics, :logger
+
+    # The default Runtime's metrics / logger readers honour module-level
+    # ivar overrides on `Hyperion` itself. This preserves a back-compat
+    # seam for 1.6.x specs that swap by reaching into private internals
+    # via `Hyperion.instance_variable_set(:@metrics, …)` — the new
+    # Runtime-routed code paths (Server / Connection / Http2Handler) all
+    # read `runtime.metrics`, so without this the override would only
+    # affect the legacy `Hyperion.metrics` reader and the new code path
+    # would still write to the original Runtime-owned object.
+    #
+    # Custom Runtimes (`Hyperion::Runtime.new(...)`) ignore the override
+    # entirely — they're per-Server isolated by design.
+    def metrics
+      override = Hyperion.instance_variable_get(:@metrics) if default?
+      override || @metrics
+    end
+
+    def logger
+      override = Hyperion.instance_variable_get(:@logger) if default?
+      override || @logger
+    end
+
+    # True when this runtime is `Runtime.default`. The default runtime
+    # is the one consulted by legacy module-level accessors — see the
+    # `metrics` / `logger` readers above.
+    def default?
+      Runtime.instance_variable_get(:@default).equal?(self)
+    end
+
+    # Process-wide default Runtime. Lazily initialized on first read.
+    # Module-level `Hyperion.metrics` / `Hyperion.logger` accessors and
+    # writers all delegate to this instance, so legacy callers in 1.6.x
+    # shape (`Hyperion.metrics = MyAdapter.new`) keep working without
+    # any source change.
+    #
+    # Tests can mutate `Runtime.default.metrics = …` directly or replace
+    # the whole default with `Runtime.default = Runtime.new(...)` (writer
+    # below). Resetting between examples is on the test author — there's
+    # no auto-reset because the singleton is part of the public surface.
+    def self.default
+      @default ||= new
+    end
+
+    # Test seam: replace the process-wide default. Used in specs that
+    # need to inject a known-state Runtime without reaching into
+    # `@default` directly.
+    def self.default=(runtime)
+      raise ArgumentError, 'expected a Hyperion::Runtime' unless runtime.is_a?(Runtime)
+
+      @default = runtime
+    end
+
+    # Test seam: clear the memoized default so the next `default` call
+    # builds a fresh one. Equivalent to `default = Runtime.new` but
+    # without forcing the caller to allocate.
+    def self.reset_default!
+      @default = nil
+    end
+
+    def initialize(metrics: nil, logger: nil, clock: Process)
+      @metrics = metrics || Hyperion::Metrics.new
+      @logger  = logger  || Hyperion::Logger.new
+      @clock   = clock
+      # 2.5-C: per-request lifecycle hooks. Pre-allocated empty Arrays so
+      # `has_request_hooks?` can be a single `any?` check on each side
+      # — no nil-guard, no lazy-init branch on the hot path. Hooks are
+      # appended in registration order; FIFO dispatch.
+      @before_request_hooks = []
+      @after_request_hooks  = []
+    end
+
+    # 2.5-C — register a Proc to fire AFTER env is built but BEFORE
+    # `app.call`. Receives `(request, env)` where `request` is the
+    # parsed `Hyperion::Request` and `env` is the mutable Rack env Hash
+    # — callbacks may stash trace context (NewRelic transactions,
+    # OpenTelemetry spans, AppSignal/DataDog handles) into the env so
+    # the corresponding after-hook can finish them.
+    #
+    # Hook errors are caught and logged; they DO NOT abort dispatch.
+    # Multiple hooks fire in registration order (FIFO).
+    def on_request_start(&block)
+      raise ArgumentError, 'block required' unless block
+
+      @before_request_hooks << block
+      block
+    end
+
+    # 2.5-C — register a Proc to fire AFTER `app.call` returns or
+    # raises. Receives `(request, env, response, error)`:
+    #
+    #   * `response` is the `[status, headers, body]` tuple when the
+    #     app returned normally, or `nil` when the app raised.
+    #   * `error` is the `StandardError` the app raised, or `nil` on
+    #     success.
+    #
+    # Use this to finish trace spans, attach response codes to the
+    # active transaction, increment per-route counters, etc. Hook
+    # errors are caught and logged — they never break dispatch.
+    def on_request_end(&block)
+      raise ArgumentError, 'block required' unless block
+
+      @after_request_hooks << block
+      block
+    end
+
+    # 2.5-C — zero-cost guard used by Adapter::Rack#call. When both
+    # arrays are empty (the default — no hooks registered), the
+    # adapter skips the dispatch entirely: no Array iteration, no
+    # Proc invocation, no allocation. The audit harness
+    # (`yjit_alloc_audit_spec`) verifies the per-request alloc count
+    # is unchanged from 2.5-B.
+    def has_request_hooks?
+      !@before_request_hooks.empty? || !@after_request_hooks.empty?
+    end
+
+    # 2.5-C — invoked by Adapter::Rack#call after env is built. Wraps
+    # each hook in a rescue so a misbehaving observer can't break the
+    # dispatch chain — failures are logged with the block's source
+    # location so operators can identify which hook went wrong.
+    def fire_request_start(request, env)
+      @before_request_hooks.each do |hook|
+        hook.call(request, env)
+      rescue StandardError => e
+        log_hook_failure(:before_request, hook, e)
+      end
+      nil
+    end
+
+    # 2.5-C — invoked by Adapter::Rack#call after `app.call` returns
+    # (or raises). `response` is the [status, headers, body] tuple on
+    # success, `nil` on error; `error` is the raised exception or nil.
+    # Same rescue contract as `fire_request_start`: each hook runs
+    # independently; one failure does not prevent later hooks from
+    # firing or the response from being written.
+    def fire_request_end(request, env, response, error)
+      @after_request_hooks.each do |hook|
+        hook.call(request, env, response, error)
+      rescue StandardError => e
+        log_hook_failure(:after_request, hook, e)
+      end
+      nil
+    end
+
+    private
+
+    def log_hook_failure(phase, hook, error)
+      file, line = hook.source_location
+      logger.error do
+        {
+          message: 'request lifecycle hook raised',
+          phase: phase,
+          hook_source: file ? "#{file}:#{line}" : 'unknown',
+          error: error.message,
+          error_class: error.class.name,
+          backtrace: (error.backtrace || []).first(5).join(' | ')
+        }
+      end
+    end
+  end
+end

data/lib/hyperion/server/route_table.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Hyperion
+  class Server
+    # 2.10-D — direct-dispatch route registry.  Mirrors agoo's
+    # `Agoo::Server.handle(:GET, "/hello", handler)` design: a lookup
+    # table indexed by HTTP method then exact-match path.  When a
+    # match hits inside `Connection#serve` (after parse, before the
+    # Rack adapter), the dispatcher skips the env-hash build, the
+    # middleware chain, and the body-iteration overhead — the
+    # handler is called directly with a `Hyperion::Request` value
+    # object and returns either a `[status, headers, body]` Rack
+    # tuple or a sentinel that points at a pre-built static
+    # response buffer (the `handle_static` path, where the response
+    # bytes are baked at registration time so the hot path is one
+    # `socket.write` syscall and zero Ruby allocation past the
+    # Connection ivars).
+    #
+    # The table is per-process: forked workers each inherit a copy
+    # of the parent's table at fork time (no IPC, no shared memory)
+    # so registrations made before `Server.start` propagate to every
+    # worker via copy-on-write.  Registrations made AFTER fork (e.g.
+    # from `on_worker_boot`) only affect the calling worker — by
+    # design, this is the operator's escape hatch for per-worker
+    # routing.  The hot-path lookup is a two-Hash-key access (O(1));
+    # write paths are guarded by a Mutex so a registration racing
+    # with an in-flight request lookup is safe.
+    #
+    # Mutability invariant: registrations replace any prior entry
+    # for the same `(method, path)` tuple — last writer wins.  No
+    # delete API for now (operator restarts to clear), keeps the
+    # public surface minimal.
+    class RouteTable
+      # The seven HTTP methods agoo's `Server.handle` accepts.  We
+      # match agoo's surface verbatim so apps porting their
+      # registrations across servers don't have to relearn the
+      # matrix.  `OPTIONS` is included for CORS preflight handlers
+      # (commonly registered as direct routes since they have no
+      # business model).
+      KNOWN_METHODS = %i[GET POST PUT DELETE HEAD PATCH OPTIONS].freeze
+
+      # 2.10-D — sentinel result returned by `Server.handle_static`'s
+      # internal handler.  When `Connection#serve` sees it, the writer
+      # short-circuits to a single `socket.write(buf)` of the
+      # pre-built response buffer — no header build, no body
+      # iteration.  Wrapping the buffer in a small struct (rather
+      # than returning the raw String from `handle`) keeps the
+      # `[status, headers, body]` shape contract visible while
+      # giving the dispatcher a single `is_a?` branch to engage the
+      # one-syscall fast path.
+      # 2.10-F adds `headers_len` so the C fast path
+      # (`PageCache.serve_request`) can write the headers-only prefix
+      # for HEAD requests without reparsing the buffer.  Defaults to
+      # `buffer.bytesize` for back-compat with callers that
+      # constructed StaticEntry the 2.10-D way (3 args, no body
+      # split) — those entries fall back to writing the whole buffer
+      # on HEAD too, which is RFC-correct (HEAD MAY include the body
+      # so long as Content-Length matches; the spec only forbids the
+      # SERVER from sending body bytes the client didn't ask for).
+      StaticEntry = Struct.new(:method, :path, :buffer, :headers_len) do
+        # Returns the pre-built response bytes ready for one
+        # `socket.write` call.  Always frozen.
+        def response_bytes
+          buffer
+        end
+
+        # 2.10-F — StaticEntry responds to `#call` so it can be
+        # registered directly in the route table (instead of via a
+        # closure wrapping it).  Returning `self` keeps the
+        # `[status, headers, body]` contract: `dispatch_direct!`'s
+        # is_a?(StaticEntry) branch handles the wire write.  Pre-
+        # 2.10-F callers that registered via
+        # `Server.handle_static` still work — that registration
+        # path now stores the entry directly and the route table's
+        # `respond_to?(:call)` invariant is preserved.
+        def call(_request)
+          self
+        end
+
+        # 2.10-F — bytes-count of the headers-only prefix.  Used by
+        # callers that reach the StaticEntry directly (specs, custom
+        # writers); the C fast path reads the C-side `headers_len`
+        # mirror that `PageCache.register_prebuilt` records.
+        def headers_bytesize
+          headers_len || buffer.bytesize
+        end
+      end
+
+      def initialize
+        # Per-method Hash so the lookup is `@routes[:GET][path]`
+        # — two integer-keyed-Hash hits.  Pre-allocate the seven
+        # slots so the request hot path never lazily creates an
+        # entry under a misspelled method (we just miss).
+        @routes = KNOWN_METHODS.each_with_object({}) { |m, h| h[m] = {} }
+        @mutex  = Mutex.new
+      end
+
+      # Register a direct-dispatch handler for the given method +
+      # path.  `handler` must respond to `#call(request)` and return
+      # either:
+      #
+      #   * a `[status, headers, body]` Rack tuple — the dispatcher
+      #     writes it via the standard ResponseWriter (no env hash,
+      #     no middleware), or
+      #   * a `StaticEntry` (built only via `Server.handle_static`)
+      #     — the dispatcher emits the pre-built bytes in one
+      #     write syscall.
+      #
+      # `method_sym` is upper-cased before lookup so callers may pass
+      # `:get` or `'get'` interchangeably with `:GET`.
+      def register(method_sym, path, handler)
+        method_key = normalize_method(method_sym)
+        raise ArgumentError, "unknown method #{method_sym.inspect}" unless KNOWN_METHODS.include?(method_key)
+        raise ArgumentError, 'path must be a String' unless path.is_a?(String)
+        raise ArgumentError, 'handler must respond to #call' unless handler.respond_to?(:call)
+
+        @mutex.synchronize { @routes[method_key][path.dup.freeze] = handler }
+        handler
+      end
+
+      # Hot-path lookup.  `method_str` is the request method as the
+      # parser produced it (a String like `'GET'`); `path` is the
+      # request path String.  Returns the registered handler or nil.
+      #
+      # No mutex on the read side — Ruby Hash reads under MRI are
+      # safe against a concurrent write that's mutex-guarded
+      # (the GVL pins the writer during the bucket update), and
+      # the cost of a Mutex acquire on every request would defeat
+      # the whole point of the fast path.
+      def lookup(method_str, path)
+        method_key = METHOD_LOOKUP[method_str] || normalize_method(method_str)
+        table = @routes[method_key]
+        return nil unless table
+
+        table[path]
+      end
+
+      # Inspection helper — returns the count of registered routes
+      # across all methods.  Used by specs and the bench harness
+      # to assert registrations took effect.
+      def size
+        @routes.values.sum(&:size)
+      end
+
+      # Clear all registrations.  Test / spec seam — production
+      # code restarts the process to drop routes.
+      def clear
+        @mutex.synchronize { @routes.each_value(&:clear) }
+        nil
+      end
+
+      private
+
+      # Pre-built lookup for the seven canonical method strings the
+      # parser emits.  Skips the Symbol allocation + upcase that
+      # `normalize_method` does for unrecognised inputs.  Frozen so
+      # the table itself is shared across all RouteTable instances
+      # (one allocation, process-wide).
+      METHOD_LOOKUP = {
+        'GET' => :GET,
+        'POST' => :POST,
+        'PUT' => :PUT,
+        'DELETE' => :DELETE,
+        'HEAD' => :HEAD,
+        'PATCH' => :PATCH,
+        'OPTIONS' => :OPTIONS
+      }.freeze
+
+      def normalize_method(value)
+        case value
+        when Symbol
+          KNOWN_METHODS.include?(value) ? value : value.to_s.upcase.to_sym
+        else
+          value.to_s.upcase.to_sym
+        end
+      end
+    end
+  end
+end