hyperion-rb 1.0.0.rc17

data/lib/hyperion/master.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require 'etc'
+require 'rbconfig'
+require 'socket'
+require 'openssl'
+
+module Hyperion
+  # Pre-fork master process. Owns the supervision loop. Each worker is a
+  # full fiber-scheduler `Hyperion::Server` running its own accept loop.
+  #
+  # rc15 — per-OS worker model. There are two ways to give N children a
+  # listening socket on the same port:
+  #
+  # 1. `:reuseport` (Linux): each worker binds its OWN socket with
+  #    SO_REUSEPORT. The kernel hashes incoming connections across the
+  #    sibling sockets — no thundering herd, no shared accept lock,
+  #    linear scaling with worker count. The master never binds.
+  #
+  # 2. `:share` (macOS / BSD / everything else): the master binds a
+  #    single TCPServer (or SSLServer) BEFORE fork. Children inherit the
+  #    fd via fork(2) and race on `accept(2)` — whichever child wins gets
+  #    the connection. This is Puma's model. We use it on Darwin because
+  #    Darwin's SO_REUSEPORT distributor hashes unevenly: at `-w 4`
+  #    against a real Rails app a single curl probe cannot get answered
+  #    inside 120s in the worst case, because the kernel keeps routing
+  #    to a worker whose accept queue is already full.
+  #
+  # Detection: `RbConfig::CONFIG['host_os']` matching `linux` picks
+  # `:reuseport`; everything else picks `:share`. Operators can pin the
+  # mode explicitly with `HYPERION_WORKER_MODEL=share|reuseport` (used by
+  # the test suite to exercise both paths on a single host).
+  class Master
+    DEFAULT_WORKER_COUNT     = nil # nil → Etc.nprocessors
+    GRACEFUL_TIMEOUT_SECONDS = 30
+
+    WORKER_MODELS = %i[reuseport share].freeze
+
+    def self.detect_worker_model
+      override = ENV['HYPERION_WORKER_MODEL']&.to_sym
+      return override if WORKER_MODELS.include?(override)
+
+      host_os = RbConfig::CONFIG['host_os'].to_s
+      case host_os
+      when /linux/ then :reuseport
+      else :share # macOS, BSD, anything else: shared-FD model (Puma-style)
+      end
+    end
+
+    def initialize(host:, port:, app:, workers: DEFAULT_WORKER_COUNT,
+                   read_timeout: Server::DEFAULT_READ_TIMEOUT_SECONDS, tls: nil,
+                   thread_count: Server::DEFAULT_THREAD_COUNT, config: nil)
+      @host         = host
+      @port         = port
+      @app          = app
+      @workers      = workers || Etc.nprocessors
+      @read_timeout = read_timeout
+      @tls          = tls
+      @thread_count = thread_count
+      @config       = config || Hyperion::Config.new
+      @graceful_timeout = @config.graceful_timeout || GRACEFUL_TIMEOUT_SECONDS
+      @children     = {} # pid => worker_index
+      @next_index   = 0
+      @stopping     = false
+      @worker_model = self.class.detect_worker_model
+      @listener     = nil # populated only in :share mode
+    end
+
+    def run
+      install_signal_handlers
+      bind_master_listener if @worker_model == :share
+      Hyperion.logger.info do
+        {
+          message: 'master starting',
+          pid: Process.pid,
+          workers: @workers,
+          host: @host,
+          port: @port,
+          worker_model: @worker_model
+        }
+      end
+
+      # `before_fork` runs ONCE in the master before any worker is forked.
+      # Operators use it to close shared resources (DB pools, Redis sockets)
+      # so each child gets fresh connections rather than inheriting the
+      # parent's open fds. Mirrors Puma's hook of the same name.
+      @config.before_fork.each(&:call)
+
+      @workers.times { spawn_worker }
+
+      supervise
+    ensure
+      # The master keeps the listener open across its lifetime so it can
+      # respawn workers (the new fork inherits the same fd). It only gets
+      # closed here once the master itself is exiting.
+      @listener&.close
+    end
+
+    private
+
+    def install_signal_handlers
+      shutdown_r, shutdown_w = IO.pipe
+      %w[INT TERM].each do |sig|
+        Signal.trap(sig) do
+          shutdown_w.write_nonblock('!')
+        rescue StandardError
+          nil
+        end
+      end
+      @shutdown_pipe = shutdown_r
+    end
+
+    # Bind the listening socket in the master so children inherit the fd
+    # via fork. Only used in :share mode (macOS / BSD).
+    def bind_master_listener
+      tcp = ::TCPServer.new(@host, @port)
+      # Honour port: 0 (let kernel pick) — propagate the chosen port so
+      # log lines and worker args reflect reality.
+      @port = tcp.addr[1]
+
+      if @tls
+        ctx = TLS.context(cert: @tls[:cert], key: @tls[:key])
+        ssl_server = ::OpenSSL::SSL::SSLServer.new(tcp, ctx)
+        ssl_server.start_immediately = false
+        @listener = ssl_server
+      else
+        @listener = tcp
+      end
+    end
+
+    def spawn_worker
+      worker_index = @next_index
+      @next_index += 1
+      pid = fork do
+        # Inside the child: clean signal traps; the worker installs its own.
+        Signal.trap('INT', 'DEFAULT')
+        Signal.trap('TERM', 'DEFAULT')
+        worker_args = {
+          host: @host, port: @port, app: @app,
+          read_timeout: @read_timeout, tls: @tls,
+          thread_count: @thread_count, config: @config,
+          worker_index: worker_index
+        }
+        # Hand the inherited socket to the worker in :share mode. In
+        # :reuseport mode the worker binds its own with SO_REUSEPORT.
+        worker_args[:listener] = @listener if @worker_model == :share
+        Worker.new(**worker_args).run
+      end
+      @children[pid] = worker_index
+    end
+
+    def supervise
+      until @stopping
+        # Block on the shutdown pipe + reap dead children.
+        ready, = IO.select([@shutdown_pipe], nil, nil, 1.0)
+
+        if ready
+          begin
+            @shutdown_pipe.read_nonblock(64)
+          rescue StandardError
+            nil
+          end
+          @stopping = true
+          break
+        end
+
+        reap_and_respawn
+      end
+
+      shutdown_children
+    end
+
+    def reap_and_respawn
+      while (result = Process.waitpid2(-1, Process::WNOHANG))
+        pid, _status = result
+        next unless @children.key?(pid)
+
+        Hyperion.logger.warn { { message: 'worker died, respawning', worker_pid: pid } }
+        @children.delete(pid)
+        spawn_worker unless @stopping
+      end
+    rescue Errno::ECHILD
+      # No children — happens during shutdown.
+    end
+
+    def shutdown_children
+      Hyperion.logger.info do
+        { message: 'master draining', graceful_timeout: @graceful_timeout }
+      end
+      @children.each_key do |pid|
+        Process.kill('TERM', pid)
+      rescue StandardError
+        nil
+      end
+
+      deadline = Time.now + @graceful_timeout
+      until @children.empty? || Time.now > deadline
+        begin
+          pid, _status = Process.waitpid2(-1, Process::WNOHANG)
+          if pid
+            @children.delete(pid)
+          else
+            sleep 0.1
+          end
+        rescue Errno::ECHILD
+          break
+        end
+      end
+
+      # Force-kill stragglers.
+      @children.each_key do |pid|
+        Process.kill('KILL', pid)
+      rescue StandardError
+        nil
+      end
+      @children.clear
+
+      Hyperion.logger.info { { message: 'master exiting' } }
+    end
+  end
+end

data/lib/hyperion/metrics.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Hyperion
+  # Lock-free per-thread counters. Each worker thread mutates its own Hash
+  # on the hot path — no mutex acquire/release on every increment, no
+  # contention across the thread pool. `snapshot` aggregates lazily across
+  # all threads that have ever incremented (one short mutex section, only
+  # taken when the operator asks for stats).
+  #
+  # Reset semantics: counters monotonically increase. Operators that want
+  # rate-of-change should snapshot, sleep, snapshot, diff.
+  #
+  # Public API:
+  #   Hyperion.stats -> Hash with all current values across all threads.
+  class Metrics
+    def initialize
+      @threads = Set.new
+      @threads_mutex = Mutex.new
+      # Each Metrics instance has its own thread-local key so spec runs that
+      # build fresh Metrics objects don't share state across examples.
+      @thread_key = :"__hyperion_metrics_#{object_id}__"
+    end
+
+    # Hot path: one TLS lookup + one hash op. No mutex.
+    def increment(key, by = 1)
+      counters = Thread.current[@thread_key] ||= register_thread_counters
+      counters[key] += by
+    end
+
+    def decrement(key, by = 1)
+      increment(key, -by)
+    end
+
+    def increment_status(code)
+      increment(:"responses_#{code}")
+    end
+
+    def snapshot
+      result = Hash.new(0)
+      @threads_mutex.synchronize do
+        @threads.delete_if { |t| !t.alive? }
+        @threads.each do |t|
+          counters = t[@thread_key]
+          next unless counters
+
+          counters.each { |k, v| result[k] += v }
+        end
+      end
+      result.default = nil
+      result
+    end
+
+    # Tests can call .reset! between examples to avoid cross-spec leakage.
+    def reset!
+      @threads_mutex.synchronize do
+        @threads.each { |t| t[@thread_key]&.clear }
+      end
+    end
+
+    private
+
+    def register_thread_counters
+      counters = Hash.new(0)
+      @threads_mutex.synchronize { @threads << Thread.current }
+      counters
+    end
+  end
+end

data/lib/hyperion/parser.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Hyperion
+  # Pure-Ruby HTTP/1.1 parser.
+  # Phase 4 replaces this with a C extension wrapping llhttp; the interface
+  # (parse(buffer) -> [Request, end_offset] | raise ParseError | raise UnsupportedError)
+  # stays stable.
+  class Parser
+    REQUEST_LINE_RE = %r{\A([A-Z]+) ([^ ?]+)(?:\?([^ ]*))? (HTTP/\d\.\d)\r\n}
+    HEADER_RE       = /\G([!-9;-~]+):[ \t]*(.*?)[ \t]*\r\n/
+
+    # Returns [Request, end_offset] where end_offset is the byte index just AFTER
+    # the last byte consumed by parsing. The caller (Connection) uses end_offset
+    # to compute carry-over for pipelining.
+    def parse(buffer)
+      m = REQUEST_LINE_RE.match(buffer)
+      raise ParseError, 'invalid request line' unless m
+
+      method, path, query, version = m.captures
+      offset = m.end(0)
+
+      headers = {}
+      loop do
+        if buffer.byteslice(offset, 2) == "\r\n"
+          offset += 2
+          break
+        end
+        h = HEADER_RE.match(buffer, offset)
+        raise ParseError, 'invalid header line' unless h && h.begin(0) == offset
+
+        headers[h[1].downcase] = h[2]
+        offset = h.end(0)
+      end
+
+      headers_end = offset
+
+      has_content_length     = headers.key?('content-length')
+      has_transfer_encoding  = headers.key?('transfer-encoding')
+
+      # RFC 9112 §6.1: a sender MUST NOT send a message containing both
+      # Content-Length and Transfer-Encoding. Refuse rather than risk
+      # request smuggling.
+      if has_content_length && has_transfer_encoding
+        raise ParseError, 'both Content-Length and Transfer-Encoding present'
+      end
+
+      if has_transfer_encoding
+        encodings = headers['transfer-encoding'].split(',').map { |e| e.strip.downcase }
+        unless encodings.last == 'chunked'
+          raise UnsupportedError,
+                "Transfer-Encoding #{headers['transfer-encoding'].inspect} not supported"
+        end
+
+        result = dechunk(buffer, headers_end)
+        raise ParseError, 'truncated chunked body' if result.nil?
+
+        body, end_offset = result
+        request = Request.new(
+          method: method,
+          path: path,
+          query_string: query || '',
+          http_version: version,
+          headers: headers,
+          body: body
+        )
+        return [request, end_offset]
+      end
+
+      content_length = headers['content-length']&.to_i || 0
+      body = buffer.byteslice(headers_end, content_length) || ''
+      raise ParseError, "content-length mismatch (declared #{content_length}, got #{body.bytesize})" \
+        if body.bytesize != content_length
+
+      end_offset = headers_end + content_length
+      request = Request.new(
+        method: method,
+        path: path,
+        query_string: query || '',
+        http_version: version,
+        headers: headers,
+        body: body
+      )
+      [request, end_offset]
+    end
+
+    private
+
+    # Decode RFC 9112 §7.1 chunked body starting at `start` in `buffer`.
+    # Returns [body_bytes, end_offset] on success. Returns nil if buffer is
+    # truncated (caller treats as ParseError).
+    def dechunk(buffer, start)
+      body = +''
+      cursor = start
+
+      loop do
+        line_end = buffer.index("\r\n", cursor)
+        return nil unless line_end
+
+        size_line = buffer.byteslice(cursor, line_end - cursor)
+        size_token = size_line.split(';').first.to_s.strip
+        return nil if size_token.empty?
+
+        size = size_token.to_i(16)
+        cursor = line_end + 2
+
+        if size.zero?
+          # Skip optional trailer headers until blank line.
+          loop do
+            nl = buffer.index("\r\n", cursor)
+            return nil unless nl
+            return [body, cursor + 2] if nl == cursor
+
+            cursor = nl + 2
+          end
+        end
+
+        return nil if buffer.bytesize < cursor + size + 2
+
+        body << buffer.byteslice(cursor, size)
+        cursor += size
+
+        return nil unless buffer.byteslice(cursor, 2) == "\r\n"
+
+        cursor += 2
+      end
+    end
+  end
+end

data/lib/hyperion/pool.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Hyperion
+  # Single-thread object pool with a maximum size.
+  # Acquire returns an existing object (mutated for reuse) or constructs a new one.
+  # Release returns the object to the pool unless the pool is full.
+  #
+  # Not thread-safe. Each Hyperion worker process runs one fiber scheduler on
+  # one thread, so a per-process pool is contention-free.
+  class Pool
+    def initialize(max_size:, factory:, reset: nil)
+      @max_size = max_size
+      @factory  = factory
+      @reset    = reset
+      @free     = []
+    end
+
+    def acquire
+      obj = @free.pop || @factory.call
+      @reset&.call(obj)
+      obj
+    end
+
+    def release(obj)
+      return if @free.size >= @max_size
+
+      @free.push(obj)
+    end
+
+    def size # rubocop:disable Rails/Delegate
+      @free.size
+    end
+  end
+end

data/lib/hyperion/request.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Hyperion
+  # Immutable parsed-request value object.
+  # Phase 5 (object pooling) will redesign this with explicit reset semantics;
+  # for Phase 1 we freeze on construction to prevent accidental mutation.
+  class Request
+    attr_reader :method, :path, :query_string, :http_version, :headers, :body, :peer_address
+
+    def initialize(method:, path:, query_string:, http_version:, headers:, body:, peer_address: nil)
+      @method       = method
+      @path         = path
+      @query_string = query_string
+      @http_version = http_version
+      @headers      = headers.freeze
+      @body         = body
+      @peer_address = peer_address
+      freeze
+    end
+
+    def header(name)
+      @headers[name.downcase]
+    end
+  end
+end

data/lib/hyperion/response_writer.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Hyperion
+  # Serializes a Rack [status, headers, body] tuple to an HTTP/1.1 wire stream.
+  # Phase 5 replaces this with an io_buffer-batched writer; Phase 7 adds a
+  # sibling Http2ResponseWriter. Public surface (#write) stays stable.
+  class ResponseWriter
+    REASONS = {
+      200 => 'OK',
+      201 => 'Created',
+      204 => 'No Content',
+      301 => 'Moved Permanently',
+      302 => 'Found',
+      304 => 'Not Modified',
+      400 => 'Bad Request',
+      401 => 'Unauthorized',
+      403 => 'Forbidden',
+      404 => 'Not Found',
+      405 => 'Method Not Allowed',
+      408 => 'Request Timeout',
+      409 => 'Conflict',
+      410 => 'Gone',
+      413 => 'Payload Too Large',
+      414 => 'URI Too Long',
+      422 => 'Unprocessable Entity',
+      429 => 'Too Many Requests',
+      500 => 'Internal Server Error',
+      501 => 'Not Implemented',
+      502 => 'Bad Gateway',
+      503 => 'Service Unavailable',
+      504 => 'Gateway Timeout'
+    }.freeze
+
+    CRLF_HEADER_VALUE = /[\r\n]/
+
+    def write(io, status, headers, body, keep_alive: false)
+      # Phase 1 buffers the full body so Content-Length is exact.
+      # Phase 2 introduces chunked transfer-encoding for streaming bodies;
+      # Phase 5 batches via IO::Buffer to avoid this intermediate String.
+      buffered = +''
+      body.each { |chunk| buffered << chunk }
+
+      reason = REASONS[status] || 'Unknown'
+      date_str = Time.now.httpdate
+
+      head = build_head(status, reason, headers, buffered.bytesize, keep_alive, date_str)
+
+      # Phase 8 perf fix: coalesce status line + all headers + body into a
+      # SINGLE io.write call. Each syscall round-trip is ~1 usec on macOS
+      # kqueue; before this change we issued (1 status) + (N headers) + (1 blank)
+      # + (1 body) = 8+ syscalls per response. Now: 1 syscall.
+      if buffered.empty?
+        io.write(head)
+      else
+        # Concatenate into the head buffer (which is already a fresh +'' from
+        # the C builder or the Ruby fallback) so we still emit a single write.
+        head << buffered
+        io.write(head)
+      end
+    ensure
+      body.close if body.respond_to?(:close)
+    end
+
+    private
+
+    # rc17: prefer the C extension when available — eliminates the per-response
+    # status-line interpolation, normalized hash, and per-header String#<<
+    # allocations. Pure-Ruby fallback covers JRuby/TruffleRuby/build failures.
+    def build_head(status, reason, headers, body_size, keep_alive, date_str)
+      if defined?(::Hyperion::CParser) && ::Hyperion::CParser.respond_to?(:build_response_head)
+        ::Hyperion::CParser.build_response_head(status, reason, headers, body_size, keep_alive, date_str)
+      else
+        build_head_ruby(status, reason, headers, body_size, keep_alive, date_str)
+      end
+    end
+
+    def build_head_ruby(status, reason, headers, body_size, keep_alive, date_str)
+      normalized = {}
+      headers.each { |k, v| normalized[k.to_s.downcase] = v }
+      normalized['content-length'] = body_size.to_s
+      # Keep-alive negotiated by Connection layer; ResponseWriter just emits it.
+      normalized['connection']     = keep_alive ? 'keep-alive' : 'close'
+      normalized['date']         ||= date_str
+
+      buf = +"HTTP/1.1 #{status} #{reason}\r\n"
+      normalized.each do |k, v|
+        value = v.to_s
+        raise ArgumentError, "header #{k.inspect} contains CR/LF" if value.match?(CRLF_HEADER_VALUE)
+
+        buf << k << ': ' << value << "\r\n"
+      end
+      buf << "\r\n"
+      buf
+    end
+  end
+end