hyperion-rb 2.13.0 → 2.14.0

data/lib/hyperion/adapter/rack.rb

@@ -151,6 +151,291 @@ module Hyperion
           nil
         end
 
+        # 2.14-A — C-accept-loop dispatch helper.
+        #
+        # The C accept loop (`PageCache.run_static_accept_loop`) calls
+        # this helper, under the GVL, when a request matches a
+        # `RouteTable::DynamicBlockEntry`. The C side has already done
+        # accept + recv + parse without holding the GVL; this helper
+        # owns the `app.call(env)` slice and returns the fully-formed
+        # HTTP/1.1 response bytes for C to write (also without the GVL).
+        #
+        # Args (all positional, all Strings except `block` and
+        # `keep_alive` and `runtime`):
+        #   * `method_str`     — e.g. "GET"
+        #   * `path_str`       — request path, no query
+        #   * `query_str`      — query (no leading '?'), or "" if none
+        #   * `host_str`       — `Host:` header value, or ""
+        #   * `headers_blob`   — raw header section as bytes
+        #     (the slice between request-line CRLF and the closing
+        #     CRLFCRLF, terminated by a CRLF on the last header). The
+        #     helper parses this in Ruby — header parse is a few µs
+        #     even for the 30-header case, dwarfed by `app.call`.
+        #   * `remote_addr`    — peer IP as a String, or "" if unknown
+        #   * `block`          — the registered Proc / lambda
+        #   * `keep_alive`     — true to emit `connection: keep-alive`
+        #     in the response head, false for `connection: close`
+        #   * `runtime`        — the `Hyperion::Runtime` instance the
+        #     server was constructed with (for lifecycle hooks); the
+        #     C loop captures this once at boot via the registered
+        #     callback closure
+        #
+        # Returns a single binary String of HTTP/1.1 response bytes
+        # (status line + response headers + CRLF + body). The C loop
+        # writes this verbatim. On exception, returns a 500 envelope
+        # so the C loop can still respond to the peer (better UX than
+        # closing the fd silently).
+        def dispatch_for_c_loop(method_str, path_str, query_str,
+                                host_str, headers_blob, remote_addr,
+                                block, keep_alive, runtime)
+          env, input = build_c_loop_env(method_str, path_str, query_str,
+                                        host_str, headers_blob, remote_addr)
+          request = nil
+          response = nil
+          error = nil
+
+          rt = runtime || Hyperion::Runtime.default
+          if rt.has_request_hooks?
+            request = c_loop_request_for(env)
+            rt.fire_request_start(request, env)
+          end
+
+          begin
+            response = block.call(env)
+          rescue StandardError => e
+            error = e
+          end
+
+          if rt.has_request_hooks?
+            request ||= c_loop_request_for(env)
+            rt.fire_request_end(request, env, response, error)
+          end
+
+          if error
+            ::Hyperion.metrics.increment(:app_errors)
+            ::Hyperion.logger.error do
+              {
+                message: 'app raised (c-accept-loop dispatch)',
+                error: error.message,
+                error_class: error.class.name,
+                backtrace: (error.backtrace || []).first(20).join(' | ')
+              }
+            end
+            response = [500, { 'content-type' => 'text/plain' }, ['Internal Server Error']]
+          end
+
+          render_c_loop_response(response, keep_alive)
+        ensure
+          ENV_POOL.release(env) if env
+          INPUT_POOL.release(input) if input
+        end
+
+        # 2.14-A — assemble the Rack env for a C-accept-loop dispatch.
+        # Mirrors the constants `build_env` sets on the regular path
+        # but skips the `connection`/hijack branches: the C accept
+        # loop owns the fd; full-hijack semantics are out of scope
+        # for this dispatch shape (h1 keep-alive is handled in C).
+        # Returns `[env, input]` so the caller can release both back
+        # to their pools after the response is rendered.
+        def build_c_loop_env(method_str, path_str, query_str,
+                             host_str, headers_blob, remote_addr)
+          server_name, server_port = split_host(host_str || '')
+
+          env = ENV_POOL.acquire
+          input = INPUT_POOL.acquire
+          input.string = EMPTY_INPUT_BUFFER
+          input.rewind
+
+          env['REQUEST_METHOD']  = method_str
+          env['PATH_INFO']       = path_str
+          env['QUERY_STRING']    = query_str || ''
+          env['SERVER_PROTOCOL'] = 'HTTP/1.1'
+          env['HTTP_VERSION']    = 'HTTP/1.1'
+          env['SERVER_NAME']     = server_name
+          env['SERVER_PORT']     = server_port
+          env['SERVER_SOFTWARE'] = SERVER_SOFTWARE_VALUE
+          env['REMOTE_ADDR']     = remote_addr.nil? || remote_addr.empty? ? '127.0.0.1' : remote_addr
+          env['rack.url_scheme'] = 'http'
+          env['rack.errors']     = $stderr
+          env['rack.version']    = RACK_VERSION
+          env['rack.multithread'] = true
+          env['rack.multiprocess'] = false
+          env['rack.run_once']   = false
+          env['rack.hijack?']    = false
+          env['SCRIPT_NAME']     = ''
+          env['rack.input']      = input
+          # 2.14-A — guarded `is_a?(String) && !empty?` (rather than
+          # `present?`) so rubocop-rails's Style/Present autocorrect
+          # can't rewrite the branch to a Rails-only API. Same pattern
+          # `Server#dispatch_handed_off` uses for `partial`.
+          env['HTTP_HOST'] = host_str if host_str.is_a?(String) && !host_str.empty?
+
+          parse_c_loop_headers!(env, headers_blob) if headers_blob.is_a?(String) && !headers_blob.empty?
+
+          [env, input]
+        end
+
+        # 2.14-A — parse the raw header block the C accept loop hands
+        # us into the env hash. Each line is `name: value\r\n`; the
+        # final empty line is already trimmed by the caller (the C
+        # loop slices between request-line-end and the closing
+        # CRLFCRLF and passes the inner bytes verbatim).
+        #
+        # We honour the same HTTP_KEY_CACHE the regular adapter path
+        # uses, so `equal?` pointer-compares from upstream Rack code
+        # (Rack::Attack et al.) keep working.
+        def parse_c_loop_headers!(env, headers_blob)
+          return if headers_blob.empty?
+
+          c_upcase = c_upcase_available?
+          # The Ruby parser walks line-by-line; allocations are 1
+          # String per header (the value). Header names go through
+          # the cache hit (no alloc) or the C-ext upcase_underscore
+          # (single-call alloc).
+          start = 0
+          blen = headers_blob.bytesize
+          while start < blen
+            eol = headers_blob.index("\r\n", start) || blen
+            line = headers_blob.byteslice(start, eol - start)
+            start = eol + 2
+            next if line.empty?
+
+            colon = line.index(':')
+            next unless colon
+
+            name = line.byteslice(0, colon).downcase
+            # Skip the colon, then any leading whitespace.
+            v_start = colon + 1
+            v_start += 1 while v_start < line.bytesize && [32, 9].include?(line.getbyte(v_start))
+            v_end = line.bytesize
+            v_end -= 1 while v_end > v_start && [32, 9].include?(line.getbyte(v_end - 1))
+            value = line.byteslice(v_start, v_end - v_start)
+
+            key = HTTP_KEY_CACHE[name] ||
+                  (c_upcase ? ::Hyperion::CParser.upcase_underscore(name) : "HTTP_#{name.upcase.tr('-', '_')}")
+            env[key] = value
+          end
+
+          env['CONTENT_TYPE']   = env['HTTP_CONTENT_TYPE']   if env.key?('HTTP_CONTENT_TYPE')
+          env['CONTENT_LENGTH'] = env['HTTP_CONTENT_LENGTH'] if env.key?('HTTP_CONTENT_LENGTH')
+          nil
+        end
+
+        # 2.14-A — minimal `Hyperion::Request` value for lifecycle
+        # hook observers. Only built when hooks are active (the
+        # `has_request_hooks?` guard skips the alloc on the no-hook
+        # hot path).
+        def c_loop_request_for(env)
+          ::Hyperion::Request.new(
+            method: env['REQUEST_METHOD'],
+            path: env['PATH_INFO'],
+            query_string: env['QUERY_STRING'],
+            http_version: 'HTTP/1.1',
+            headers: {},
+            body: nil
+          )
+        end
+
+        # 2.14-A — render a Rack `[status, headers, body]` triple to
+        # the wire bytes for the C loop. Honours:
+        #   * `keep_alive` — emit `connection: keep-alive` vs
+        #     `connection: close`. The C loop honours the
+        #     `connection: close` request header by passing
+        #     `keep_alive=false`; ditto on Rack apps that opt in via
+        #     the response header.
+        #   * `content-length` — auto-computed from the body bytes
+        #     unless the app set it explicitly. Required for
+        #     keep-alive correctness.
+        #   * `body.each` — collected into a single binary blob; the
+        #     C loop writes head + body in one syscall.
+        #   * `body.close` — invoked after iteration per Rack spec.
+        #
+        # Streaming bodies (Rack 3 `body.call(stream)` shape) are NOT
+        # supported in the C-loop dispatch. Apps that need streaming
+        # must register via the legacy `Connection#serve` path
+        # (don't use the block form of `Server.handle`); the
+        # `eligible_route_table?` check refuses to engage the C loop
+        # for tables containing those handlers.
+        def render_c_loop_response(response, keep_alive)
+          unless response.is_a?(Array) && response.length == 3
+            response = [500, { 'content-type' => 'text/plain' }, ['Invalid Rack response']]
+          end
+          status, headers, body = response
+
+          body_bytes = collect_body_bytes(body)
+          headers_out = normalize_response_headers(headers, body_bytes.bytesize, keep_alive)
+          head = build_status_line(status) + headers_out + "\r\n"
+
+          buf = String.new(capacity: head.bytesize + body_bytes.bytesize, encoding: Encoding::ASCII_8BIT)
+          buf << head.b << body_bytes
+          buf
+        ensure
+          begin
+            body.close if body.respond_to?(:close)
+          rescue StandardError
+            nil
+          end
+        end
+
+        # 2.14-A — drain a Rack body into a single binary blob.
+        # Honours both Array bodies (the common case — `[body_str]`)
+        # and `each`-yielding bodies. Rack 3 streaming bodies (the
+        # `call(stream)` variant) raise here; the eligibility check
+        # is supposed to refuse them at registration time.
+        def collect_body_bytes(body)
+          return body[0].b if body.is_a?(Array) && body.length == 1 && body[0].is_a?(String)
+
+          buf = String.new(encoding: Encoding::ASCII_8BIT)
+          body.each { |chunk| buf << chunk.to_s.b } if body.respond_to?(:each)
+          buf
+        end
+
+        # 2.14-A — Build the response header lines including
+        # `content-length`, `connection`, and `server`. Skips any
+        # header named `connection`/`content-length`/`transfer-encoding`
+        # the app set (we own those in the C-loop path).
+        def normalize_response_headers(headers, body_len, keep_alive)
+          out = String.new(encoding: Encoding::ASCII_8BIT)
+          if headers.is_a?(Hash)
+            headers.each do |name, value|
+              ln = name.to_s.downcase
+              next if %w[connection content-length transfer-encoding].include?(ln)
+
+              # Multi-value headers (Rack 3: Array of values, or
+              # newline-joined String) — emit one line per value.
+              vals = value.is_a?(Array) ? value : value.to_s.split("\n")
+              vals.each do |v|
+                out << ln << ': ' << v.to_s << "\r\n"
+              end
+            end
+          end
+          out << 'content-length: ' << body_len.to_s << "\r\n"
+          out << (keep_alive ? "connection: keep-alive\r\n" : "connection: close\r\n")
+          out
+        end
+
+        # 2.14-A — minimal status line builder. Covers the canonical
+        # 200/201/204/301/302/304/400/401/403/404/500 by name; everything
+        # else falls back to a generic reason phrase since the Rack
+        # body still wins at the protocol level.
+        STATUS_LINES = {
+          200 => "HTTP/1.1 200 OK\r\n",
+          201 => "HTTP/1.1 201 Created\r\n",
+          204 => "HTTP/1.1 204 No Content\r\n",
+          301 => "HTTP/1.1 301 Moved Permanently\r\n",
+          302 => "HTTP/1.1 302 Found\r\n",
+          304 => "HTTP/1.1 304 Not Modified\r\n",
+          400 => "HTTP/1.1 400 Bad Request\r\n",
+          401 => "HTTP/1.1 401 Unauthorized\r\n",
+          403 => "HTTP/1.1 403 Forbidden\r\n",
+          404 => "HTTP/1.1 404 Not Found\r\n",
+          500 => "HTTP/1.1 500 Internal Server Error\r\n"
+        }.freeze
+
+        def build_status_line(status)
+          STATUS_LINES[status] || "HTTP/1.1 #{status} OK\r\n"
+        end
+
         # 2.1.0 (WS-1): `connection:` is the Hyperion::Connection that owns
         # the underlying socket for this request. When non-nil, the env hash
         # advertises Rack 3 full-hijack support — the app can call

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