hyperion-rb 1.0.0.rc17

data/lib/hyperion/server.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'openssl'
+require 'async'
+require 'async/scheduler'
+
+module Hyperion
+  # Phase 2a server: bind a TCPServer, accept connections, schedule each on its
+  # own fiber via Async. Multiple in-flight requests run concurrently on a
+  # single OS thread. Keep-alive is still off — connection closes after one
+  # request (Phase 2b will add keep-alive).
+  #
+  # Phase 7 (scoped): when `tls:` is supplied, wrap the listener in an
+  # OpenSSL::SSL::SSLServer with ALPN advertising `h2` + `http/1.1`. After
+  # the handshake, dispatch on the negotiated protocol — http/1.1 goes
+  # through Connection (real path); h2 goes to Http2Handler (505 stub
+  # until Phase 8).
+  class Server
+    DEFAULT_READ_TIMEOUT_SECONDS = 30
+    DEFAULT_THREAD_COUNT         = 5
+
+    attr_reader :host, :port
+
+    def initialize(app:, host: '127.0.0.1', port: 9292, read_timeout: DEFAULT_READ_TIMEOUT_SECONDS,
+                   tls: nil, thread_count: DEFAULT_THREAD_COUNT)
+      @host         = host
+      @port         = port
+      @app          = app
+      @read_timeout = read_timeout
+      @tls          = tls
+      @thread_count = thread_count
+      @thread_pool  = nil
+      @stopped      = false
+    end
+
+    def listen
+      tcp = ::TCPServer.new(@host, @port)
+      @port = tcp.addr[1]
+
+      if @tls
+        @ssl_ctx = TLS.context(cert: @tls[:cert], key: @tls[:key])
+        ssl_server = ::OpenSSL::SSL::SSLServer.new(tcp, @ssl_ctx)
+        ssl_server.start_immediately = false
+        @server = ssl_server
+        @tcp_server = tcp
+      else
+        @server = tcp
+        @tcp_server = tcp
+      end
+      self
+    end
+
+    # Phase 3: workers pass in a pre-bound, SO_REUSEPORT-set socket built
+    # by Hyperion::Worker. Bypasses #listen but keeps the rest of the
+    # accept loop intact since Socket and TCPServer both quack #accept_nonblock.
+    #
+    # Phase 8: when `tls:` was supplied to the constructor, also build the
+    # SSL context here so the accept loop can wrap incoming connections.
+    # Each worker builds its own context — they don't share state.
+    def adopt_listener(sock)
+      @server = sock
+      @tcp_server = sock
+      @port = case sock
+              when ::TCPServer
+                sock.addr[1]
+              else
+                sock.local_address.ip_port
+              end
+      @ssl_ctx = TLS.context(cert: @tls[:cert], key: @tls[:key]) if @tls
+      self
+    end
+
+    def run_one
+      Async do
+        socket = blocking_accept
+        next unless socket
+
+        apply_timeout(socket)
+        dispatch(socket)
+      end.wait
+    end
+
+    def start
+      listen unless @server
+      @thread_pool = ThreadPool.new(size: @thread_count) if @thread_count.positive?
+
+      Async do |task|
+        until @stopped
+          socket = accept_or_nil
+          next unless socket
+
+          apply_timeout(socket)
+          # Plain HTTP/1.1 with a pool: submit straight to the worker — no
+          # fiber wrap needed (submit_connection returns immediately and the
+          # worker thread owns the connection for its lifetime).
+          # TLS still goes through a fiber: ALPN negotiation determines h2
+          # vs http/1.1, and h2 needs the fiber because each stream is its
+          # own fiber inside Http2Handler.
+          if @thread_pool && !@tls
+            @thread_pool.submit_connection(socket, @app)
+          else
+            task.async { dispatch(socket) }
+          end
+        end
+      end
+    ensure
+      @thread_pool&.shutdown
+    end
+
+    def stop
+      @stopped = true
+      @server&.close
+      @server = nil
+      @tcp_server = nil
+    end
+
+    private
+
+    def dispatch(socket)
+      if socket.is_a?(::OpenSSL::SSL::SSLSocket) && socket.alpn_protocol == 'h2'
+        # HTTP/2: each stream runs on a fiber inside Http2Handler. The
+        # handler still uses the pool's `#call` for app.call hops on each
+        # stream (one per stream, not one per connection).
+        Http2Handler.new(app: @app, thread_pool: @thread_pool).serve(socket)
+      elsif @thread_pool
+        # HTTP/1.1 (e.g. TLS-wrapped after ALPN picked http/1.1): hand the
+        # connection to a worker thread. The fiber that called dispatch
+        # returns immediately.
+        @thread_pool.submit_connection(socket, @app)
+      else
+        # No pool (thread_count: 0): inline on the calling fiber.
+        Connection.new.serve(socket, @app)
+      end
+    end
+
+    def listening_io
+      @tcp_server
+    end
+
+    def accept_or_nil
+      ready, = IO.select([listening_io], nil, nil, 0.1)
+      return nil unless ready
+
+      if @tls
+        raw, = listening_io.accept_nonblock
+        ssl = ::OpenSSL::SSL::SSLSocket.new(raw, @ssl_ctx)
+        ssl.sync_close = true
+        ssl.accept # blocks; under Async this yields cooperatively via the scheduler
+        ssl
+      else
+        socket, = listening_io.accept_nonblock
+        socket
+      end
+    rescue IO::WaitReadable, Errno::EINTR, Errno::ECONNABORTED
+      nil
+    rescue IOError, Errno::EBADF
+      @stopped = true
+      nil
+    rescue OpenSSL::SSL::SSLError => e
+      Hyperion.logger.warn { { message: 'tls handshake failed', error: e.message } }
+      nil
+    end
+
+    def blocking_accept
+      if @tls
+        raw, = listening_io.accept
+        ssl = ::OpenSSL::SSL::SSLSocket.new(raw, @ssl_ctx)
+        ssl.sync_close = true
+        ssl.accept
+        ssl
+      else
+        socket, = @server.accept
+        socket
+      end
+    rescue OpenSSL::SSL::SSLError => e
+      Hyperion.logger.warn { { message: 'tls handshake failed', error: e.message } }
+      nil
+    end
+
+    # Defensively set a per-connection read deadline so a stalled client
+    # cannot wedge the worker. Phase 2 (fiber scheduler) will replace this
+    # with cooperative timeouts driven by the scheduler.
+    def apply_timeout(socket)
+      target = socket.respond_to?(:io) ? socket.io : socket
+      if target.respond_to?(:timeout=)
+        target.timeout = @read_timeout
+      else
+        timeval = [@read_timeout, 0].pack('l_l_')
+        target.setsockopt(::Socket::SOL_SOCKET, ::Socket::SO_RCVTIMEO, timeval)
+      end
+    rescue StandardError => e
+      Hyperion.logger.warn do
+        { message: 'failed to set read timeout', error: e.message, error_class: e.class.name }
+      end
+    end
+  end
+end

data/lib/hyperion/thread_pool.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Hyperion
+  # Thread pool for Rack dispatch. Has two modes:
+  #
+  # 1. `#submit_connection(socket, app)` — HTTP/1.1 path. The whole socket is
+  #    handed to a worker thread, which runs `Connection#serve(socket, app)`
+  #    directly with `thread_pool: nil` (the worker IS the pool). Zero
+  #    per-request hop, one OS thread per in-flight connection — Puma's model.
+  #
+  # 2. `#call(app, request)` — old hop-based API. Used by Http2Handler, where
+  #    each h2 stream runs on a fiber inside the connection fiber and DOES
+  #    need the cross-thread hop for `app.call(env)`.
+  #
+  # Why we need this: synchronous Rack handlers (Rails dev-mode reloader,
+  # ActiveRecord, many gems) hold global mutexes that serialize work across
+  # fibers on a single thread. Fibers give us cheap connection counts but
+  # cannot deliver true parallelism for blocking handlers. The thread pool
+  # gives us Puma-style OS-thread concurrency for `app.call(env)` while the
+  # accept loop stays on fibers.
+  #
+  # Cross-thread fiber wakeup (for the legacy `#call` path): on Ruby 3.2+ with
+  # the Async fiber scheduler, `Queue#pop` is fiber-aware — the fiber yields
+  # cooperatively while waiting on the queue. Verified experimentally on Ruby
+  # 3.3.3.
+  class ThreadPool
+    SHUTDOWN = :__hyperion_thread_pool_shutdown__
+
+    attr_reader :size
+
+    def initialize(size:)
+      @size       = size
+      @inbox      = Queue.new # multiplexes both kinds of jobs
+      # Pre-allocate one reply queue per in-flight slot for the legacy `#call`
+      # path. Bounded by `size`: if all workers are busy, all reply queues are
+      # checked out, and the next caller blocks on `@reply_pool.pop` until a
+      # worker frees one. That's the correct backpressure shape.
+      @reply_pool = Queue.new
+      size.times { @reply_pool << Queue.new }
+      @workers = Array.new(size) { spawn_worker }
+    end
+
+    # HTTP/1.1 path: hand the whole socket to a worker thread. The worker
+    # runs `Connection#serve(socket, app)` directly. No per-request hop.
+    # Returns immediately — caller does not wait.
+    def submit_connection(socket, app)
+      @inbox << [:connection, socket, app]
+    end
+
+    # HTTP/2 + sub-call path: hop one `app.call` from the calling fiber to a
+    # worker thread. The fiber yields until the worker pushes the result back.
+    #
+    # Reply-queue lifecycle invariant: `@reply_pool` always contains queues
+    # that are empty. We check one out, hand it to the worker, the worker
+    # pushes exactly one result, we pop it, then return the queue to the
+    # pool. If `app.call` raises, the worker still pushes a 500 result — see
+    # `spawn_worker`.
+    def call(app, request)
+      reply = @reply_pool.pop
+      @inbox << [:call, app, request, reply]
+      result = reply.pop
+      @reply_pool << reply
+      result
+    end
+
+    def shutdown
+      @size.times { @inbox << SHUTDOWN }
+      @workers.each { |t| t.join(5) }
+    end
+
+    private
+
+    def spawn_worker
+      Thread.new do
+        loop do
+          job = @inbox.pop
+          break if job.equal?(SHUTDOWN)
+
+          case job[0]
+          when :connection
+            _, socket, app = job
+            # Worker thread owns the connection for its full lifetime. Pass
+            # thread_pool: nil so Connection#call_app inlines Adapter::Rack.call
+            # — the worker IS the pool, no further hop required.
+            begin
+              Hyperion::Connection.new.serve(socket, app)
+            rescue StandardError => e
+              Hyperion.logger.error do
+                {
+                  message: 'thread pool worker connection raised',
+                  error: e.message,
+                  error_class: e.class.name
+                }
+              end
+            end
+          when :call
+            _, app, request, reply = job
+            reply <<
+              begin
+                Hyperion::Adapter::Rack.call(app, request)
+              rescue StandardError => e
+                Hyperion.logger.error do
+                  { message: 'thread pool worker raised', error: e.message, error_class: e.class.name }
+                end
+                [500, { 'content-type' => 'text/plain' }, ['Internal Server Error']]
+              end
+          end
+        end
+      rescue StandardError => e
+        Hyperion.logger.error do
+          { message: 'thread pool worker died', error: e.message, error_class: e.class.name }
+        end
+      end
+    end
+  end
+end

data/lib/hyperion/tls.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module Hyperion
+  # TLS context builder with ALPN configured for HTTP/2 + HTTP/1.1.
+  #
+  # Phase 7: TLS is opt-in via Server's `tls:` kwarg. ALPN lets the client
+  # negotiate `h2` (HTTP/2) or `http/1.1` during the handshake; the server
+  # then dispatches to either Http2Handler or Connection accordingly.
+  module TLS
+    SUPPORTED_PROTOCOLS = %w[h2 http/1.1].freeze
+
+    module_function
+
+    def context(cert:, key:)
+      ctx = OpenSSL::SSL::SSLContext.new
+      ctx.cert = cert
+      ctx.key = key
+      ctx.min_version = OpenSSL::SSL::TLS1_2_VERSION
+      ctx.alpn_protocols = SUPPORTED_PROTOCOLS
+      ctx.alpn_select_cb = lambda do |client_protocols|
+        # Prefer h2 if the client offered it; else fall back to http/1.1.
+        SUPPORTED_PROTOCOLS.find { |p| client_protocols.include?(p) }
+      end
+      ctx
+    end
+  end
+end

data/lib/hyperion/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Hyperion
+  VERSION = '1.0.0.rc17'
+end

data/lib/hyperion/worker.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'openssl'
+
+module Hyperion
+  # Worker process. Receives a listening socket and runs a
+  # `Hyperion::Server` (fiber accept loop) until SIGTERM.
+  #
+  # Two listener sources, picked by the master per-OS:
+  #
+  # - `:share` mode (macOS / BSD): the master forwards a pre-bound
+  #   `TCPServer` / `OpenSSL::SSL::SSLServer` via the `listener:` kwarg.
+  #   The worker uses it as-is — the fd was inherited across fork.
+  # - `:reuseport` mode (Linux): no listener is passed. The worker binds
+  #   its own `Socket` with `SO_REUSEPORT` set so the kernel can hash
+  #   incoming connections across the sibling sockets.
+  class Worker
+    def initialize(host:, port:, app:, read_timeout:, tls: nil,
+                   thread_count: Server::DEFAULT_THREAD_COUNT,
+                   config: nil, worker_index: 0, listener: nil)
+      @host         = host
+      @port         = port
+      @app          = app
+      @read_timeout = read_timeout
+      @tls          = tls
+      @thread_count = thread_count
+      @config       = config || Hyperion::Config.new
+      @worker_index = worker_index
+      @listener     = listener
+    end
+
+    def run
+      scheme = @tls ? 'https' : 'http'
+      Hyperion.logger.info do
+        {
+          message: 'worker listening',
+          pid: Process.pid,
+          worker_index: @worker_index,
+          url: "#{scheme}://#{@host}:#{@port}"
+        }
+      end
+
+      server = Server.new(host: @host, port: @port, app: @app,
+                          read_timeout: @read_timeout, tls: @tls,
+                          thread_count: @thread_count)
+      tcp_server = @listener || build_reuseport_listener
+      server.adopt_listener(tcp_server)
+
+      Signal.trap('TERM') { server.stop }
+      Signal.trap('INT')  { server.stop }
+
+      # `on_worker_boot` runs in the child after fork, after the listener is
+      # ready, and before we start accepting. App code reconnects DB/Redis
+      # pools here so each worker has its own. Index identifies the slot
+      # (0..workers-1) so apps can shard background work if they want.
+      @config.on_worker_boot.each { |h| h.call(@worker_index) }
+
+      begin
+        server.start
+      ensure
+        # `on_worker_shutdown` fires when the accept loop exits — either
+        # due to graceful SIGTERM or a hard error. Use it to flush metrics,
+        # close DB connections cleanly, etc.
+        @config.on_worker_shutdown.each { |h| h.call(@worker_index) }
+      end
+    end
+
+    private
+
+    def build_reuseport_listener
+      addr = ::Socket.getaddrinfo(@host, @port, nil, :STREAM).first
+      sock = ::Socket.new(addr[4], ::Socket::SOCK_STREAM, 0)
+      sock.setsockopt(::Socket::SOL_SOCKET, ::Socket::SO_REUSEADDR, 1)
+      sock.setsockopt(::Socket::SOL_SOCKET, ::Socket::SO_REUSEPORT, 1)
+      sock.bind(::Socket.pack_sockaddr_in(@port, addr[3]))
+      sock.listen(::Socket::SOMAXCONN)
+
+      if @tls
+        ctx = Hyperion::TLS.context(cert: @tls[:cert], key: @tls[:key])
+        ssl = ::OpenSSL::SSL::SSLServer.new(sock, ctx)
+        ssl.start_immediately = false
+        ssl
+      else
+        # Hyperion::Server#adopt_listener accepts any object responding to
+        # #accept_nonblock, #accept, #close — which Socket does.
+        sock
+      end
+    end
+  end
+end

data/lib/hyperion.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative 'hyperion/version'
+require_relative 'hyperion/logger'
+require_relative 'hyperion/metrics'
+require_relative 'hyperion/config'
+
+module Hyperion
+  class Error < StandardError; end
+  class ParseError < Error; end
+  class UnsupportedError < Error; end
+
+  class << self
+    def logger
+      @logger ||= Logger.new
+    end
+
+    attr_writer :logger, :log_requests
+
+    def metrics
+      @metrics ||= Metrics.new
+    end
+
+    def stats
+      metrics.snapshot
+    end
+
+    # Per-request access logging is ON by default — matches Puma/Rails operator
+    # expectations (Rails::Rack::Logger emits one line per request out of the
+    # box). Operators can disable it via `--no-log-requests`,
+    # `HYPERION_LOG_REQUESTS=0|false|no|off`, or programmatically via
+    # `Hyperion.log_requests = false`. When false, Connection skips ALL
+    # access-log work — no Process.clock_gettime, no hash build, nothing.
+    #
+    # The hot path uses Logger#access (single-interpolation line build,
+    # per-thread cached timestamp, lock-free emit) so default-ON throughput
+    # stays well above Puma's default-OFF baseline.
+    def log_requests?
+      return @log_requests unless @log_requests.nil?
+
+      env = ENV['HYPERION_LOG_REQUESTS']&.downcase
+      @log_requests =
+        case env
+        when '0', 'false', 'no', 'off' then false
+        when '1', 'true', 'yes', 'on'  then true
+        else true # default ON
+        end
+    end
+  end
+end
+
+# Runtime guard: warn early if the host app pulled openssl 4.x in despite the
+# gemspec pin. Some Rails apps mutate `OpenSSL::SSL::SSLContext::DEFAULT_PARAMS`
+# (e.g. the AWS SDK pattern that injects ciphers); 4.0 froze that hash, so the
+# mutation now raises FrozenError on boot. We don't fix the host app — we just
+# point at the source so the operator doesn't think it's a Hyperion bug.
+if defined?(::OpenSSL::VERSION) &&
+   ::Gem::Version.new(::OpenSSL::VERSION) >= ::Gem::Version.new('4.0.0') &&
+   ::OpenSSL::SSL::SSLContext::DEFAULT_PARAMS.frozen?
+  Hyperion.logger.warn do
+    {
+      message: 'openssl froze SSLContext::DEFAULT_PARAMS — apps mutating that hash crash on boot',
+      openssl_version: ::OpenSSL::VERSION,
+      remediation: 'pin openssl < 4.0 in your Gemfile until the upstream initializer is updated'
+    }
+  end
+end
+
+require_relative 'hyperion/pool'
+require_relative 'hyperion/fiber_local'
+require_relative 'hyperion/request'
+require_relative 'hyperion/parser'
+require_relative 'hyperion/c_parser'
+require_relative 'hyperion/adapter/rack'
+require_relative 'hyperion/response_writer'
+require_relative 'hyperion/thread_pool'
+require_relative 'hyperion/connection'
+require_relative 'hyperion/tls'
+require_relative 'hyperion/http2_handler'
+require_relative 'hyperion/server'
+require_relative 'hyperion/worker'
+require_relative 'hyperion/master'