hyperion-rb 1.0.0.rc17

data/lib/hyperion/http2_handler.rb

@@ -0,0 +1,312 @@
+# frozen_string_literal: true
+
+require 'async'
+require 'async/notification'
+require 'protocol/http2/server'
+require 'protocol/http2/framer'
+require 'protocol/http2/stream'
+
+module Hyperion
+  # Real HTTP/2 dispatch driven by `protocol-http2`.
+  #
+  # Each TLS connection that negotiated `h2` via ALPN ends up here. We frame
+  # the socket, read the connection preface, and then drive a frame loop on
+  # the connection's fiber: it reads one frame at a time and lets
+  # `protocol-http2` update its connection/stream state machines. As soon as
+  # a client stream finishes its request half (state `:half_closed_remote`
+  # via `end_stream?`), we hand the stream off to a sibling fiber for
+  # dispatch — slow handlers no longer block other streams on the same
+  # connection.
+  #
+  # All framer writes (HEADERS, DATA, RST_STREAM) are serialized through a
+  # single connection-scoped Mutex (`@send_mutex`). The OpenSSL::SSL::SSLSocket
+  # underneath is not safe to drive from two fibers concurrently, and
+  # protocol-http2's HPACK encoder is also stateful across HEADERS frames,
+  # so all sends must be serialized.
+  #
+  # Flow control: `RequestStream#window_updated` overrides the protocol-http2
+  # default to fan a notification out to any fiber blocked in `send_body`
+  # waiting for the remote peer's flow-control window to grow. The body
+  # writer chunks the response payload by the per-stream available frame
+  # size and yields on the notification when the window is exhausted, so
+  # large bodies never trip a FlowControlError.
+  class Http2Handler
+    # Per-stream subclass that captures decoded request pseudo-headers,
+    # regular headers, and any DATA frame body bytes for later dispatch.
+    # Also exposes a `window_available` notification fan-out so the
+    # response-writer fiber can sleep until WINDOW_UPDATE arrives.
+    class RequestStream < ::Protocol::HTTP2::Stream
+      attr_reader :request_headers, :request_body, :request_complete
+
+      def initialize(*)
+        super
+        @request_headers = []
+        @request_body = +''
+        @request_complete = false
+        @window_available = ::Async::Notification.new
+      end
+
+      def process_headers(frame)
+        decoded = super
+        # decoded is an Array of [name, value] pairs (HPACK output).
+        decoded.each { |pair| @request_headers << pair }
+        @request_complete = true if frame.end_stream?
+        decoded
+      end
+
+      def process_data(frame)
+        data = super
+        # rubocop:disable Rails/Present
+        @request_body << data if data && !data.empty?
+        # rubocop:enable Rails/Present
+        @request_complete = true if frame.end_stream?
+        data
+      end
+
+      # Called by protocol-http2 whenever the remote peer's flow-control
+      # window opens up — either via a stream-level WINDOW_UPDATE or via the
+      # connection-level fan-out in `Connection#consume_window`. We poke the
+      # notification so any fiber waiting in `wait_for_window` resumes.
+      def window_updated(size)
+        @window_available.signal
+        super
+      end
+
+      # Block the calling fiber until the remote window grows. Cheap no-op
+      # signal each time `window_updated` fires; the caller re-checks
+      # available_frame_size in a loop.
+      def wait_for_window
+        @window_available.wait
+      end
+    end
+
+    def initialize(app:, thread_pool: nil)
+      @app         = app
+      @thread_pool = thread_pool
+      @metrics     = Hyperion.metrics
+      @logger      = Hyperion.logger
+    end
+
+    def serve(socket)
+      @metrics.increment(:connections_accepted)
+      @metrics.increment(:connections_active)
+      framer = ::Protocol::HTTP2::Framer.new(socket)
+      server = build_server(framer)
+      server.read_connection_preface
+
+      # Extract once — the same TCP peer drives every stream on this conn.
+      peer_addr = peer_address(socket)
+
+      # All framer writes (HEADERS / DATA / RST_STREAM / GOAWAY) must be
+      # serialized: the underlying SSLSocket is not safe across fibers, and
+      # the HPACK encoder is also stateful. The connection's own frame loop
+      # uses this mutex too — see `dispatch_stream` and `send_body`.
+      send_mutex = ::Mutex.new
+
+      task = ::Async::Task.current
+
+      # Track in-flight per-stream dispatch fibers so we can drain them on
+      # connection close.
+      stream_tasks = []
+
+      until server.closed?
+        ready_ids = []
+        server.read_frame do |frame|
+          ready_ids << frame.stream_id if frame.stream_id.positive?
+        end
+
+        ready_ids.uniq.each do |sid|
+          stream = server.streams[sid]
+          next unless stream.is_a?(RequestStream)
+          next unless stream.request_complete
+          next if stream.closed?
+          next if stream.instance_variable_get(:@hyperion_dispatched)
+
+          # Mark before spawning so we never dispatch the same stream twice
+          # if subsequent frames (e.g. RST_STREAM races) arrive.
+          stream.instance_variable_set(:@hyperion_dispatched, true)
+
+          stream_tasks << task.async do
+            dispatch_stream(stream, send_mutex, peer_addr)
+          end
+        end
+      end
+
+      # Drain in-flight stream dispatches before we close the socket.
+      stream_tasks.each do |t|
+        t.wait
+      rescue StandardError
+        nil
+      end
+    rescue EOFError, Errno::ECONNRESET, Errno::EPIPE, IOError, OpenSSL::SSL::SSLError
+      # Peer disconnect — nothing to do.
+    rescue ::Protocol::HTTP2::GoawayError, ::Protocol::HTTP2::ProtocolError, ::Protocol::HTTP2::HandshakeError
+      # Protocol-level error — protocol-http2 has already emitted GOAWAY.
+    rescue StandardError => e
+      @logger.error do
+        {
+          message: 'h2 connection error',
+          error: e.message,
+          error_class: e.class.name,
+          backtrace: (e.backtrace || []).first(10).join(' | ')
+        }
+      end
+    ensure
+      @metrics.decrement(:connections_active)
+      socket.close unless socket.closed?
+    end
+
+    private
+
+    def build_server(framer)
+      server = ::Protocol::HTTP2::Server.new(framer)
+      server.define_singleton_method(:accept_stream) do |stream_id, &block|
+        unless valid_remote_stream_id?(stream_id)
+          raise ::Protocol::HTTP2::ProtocolError, "Invalid stream id: #{stream_id}"
+        end
+
+        if block
+          create_stream(stream_id, &block)
+        else
+          create_stream(stream_id) { |conn, id| RequestStream.create(conn, id) }
+        end
+      end # quiet rubocop unused-warning placeholder; not actually returned
+      server
+    end
+
+    def dispatch_stream(stream, send_mutex, peer_addr = nil)
+      pseudo, regular = partition_pseudo(stream.request_headers)
+
+      method    = pseudo[':method'] || 'GET'
+      path_raw  = pseudo[':path']   || '/'
+      authority = pseudo[':authority']
+      path, query = path_raw.split('?', 2)
+
+      hyperion_headers = regular
+      hyperion_headers['host'] ||= authority if authority
+
+      request = Hyperion::Request.new(
+        method: method,
+        path: path,
+        query_string: query || '',
+        http_version: 'HTTP/2',
+        headers: hyperion_headers,
+        body: stream.request_body,
+        peer_address: peer_addr
+      )
+
+      @metrics.increment(:requests_total)
+      @metrics.increment(:requests_in_flight)
+      status, response_headers, body_chunks = begin
+        if @thread_pool
+          @thread_pool.call(@app, request)
+        else
+          Hyperion::Adapter::Rack.call(@app, request)
+        end
+      ensure
+        @metrics.decrement(:requests_in_flight)
+      end
+
+      out_headers = [[':status', status.to_s]]
+      response_headers.each do |k, v|
+        next if k.to_s.downcase == 'connection' # forbidden in h2
+
+        Array(v).each do |val|
+          val.to_s.split("\n").each do |line|
+            out_headers << [k.to_s.downcase, line]
+          end
+        end
+      end
+
+      payload = +''
+      body_chunks.each { |c| payload << c.to_s }
+      body_chunks.close if body_chunks.respond_to?(:close)
+
+      send_mutex.synchronize { stream.send_headers(out_headers) }
+      send_body(stream, payload, send_mutex)
+      @metrics.increment_status(status)
+    rescue StandardError => e
+      @metrics.increment(:app_errors)
+      @logger.error do
+        {
+          message: 'h2 stream dispatch failed',
+          error: e.message,
+          error_class: e.class.name,
+          backtrace: (e.backtrace || []).first(10).join(' | ')
+        }
+      end
+      begin
+        send_mutex.synchronize { stream.send_reset_stream(::Protocol::HTTP2::Error::INTERNAL_ERROR) }
+      rescue StandardError
+        nil
+      end
+    end
+
+    # Send the response body, respecting the peer's max frame size and
+    # per-stream flow-control window. When the window is exhausted, we
+    # block the dispatch fiber on the stream's `window_available`
+    # notification — protocol-http2 calls `window_updated` on every active
+    # stream when WINDOW_UPDATE frames arrive (either stream- or
+    # connection-scoped), which signals the notification.
+    def send_body(stream, payload, send_mutex)
+      if payload.empty?
+        send_mutex.synchronize { stream.send_data('', ::Protocol::HTTP2::END_STREAM) }
+        return
+      end
+
+      offset = 0
+      bytesize = payload.bytesize
+      while offset < bytesize
+        # `available_frame_size` is the min of the connection's max-frame
+        # setting and the smaller of the stream/connection remote windows.
+        available = stream.available_frame_size
+
+        if available <= 0
+          # Window exhausted. Wait for WINDOW_UPDATE and re-check.
+          stream.wait_for_window
+          next
+        end
+
+        chunk = payload.byteslice(offset, available)
+        offset += chunk.bytesize
+        flags = offset >= bytesize ? ::Protocol::HTTP2::END_STREAM : 0
+
+        send_mutex.synchronize { stream.send_data(chunk, flags) }
+      end
+    end
+
+    # Mirrors Connection#peer_address — see the comment there. SSLSocket
+    # wraps a TCPSocket; both expose #peeraddr after handshake.
+    def peer_address(socket)
+      raw = socket.respond_to?(:io) ? socket.io : socket
+      return nil unless raw.respond_to?(:peeraddr)
+
+      addr = raw.peeraddr
+      ip = addr[3] || addr[2]
+      return nil if ip.nil? || ip.to_s.empty?
+
+      ip
+    rescue StandardError
+      nil
+    end
+
+    def partition_pseudo(headers_array)
+      pseudo = {}
+      regular = {}
+      headers_array.each do |pair|
+        name, value = pair
+        if name.start_with?(':')
+          pseudo[name] = value
+        else
+          regular[name] ||= +''
+          regular[name] = if regular[name].empty?
+                            value.to_s
+                          else
+                            "#{regular[name]},#{value}"
+                          end
+        end
+      end
+      [pseudo, regular]
+    end
+  end
+end

data/lib/hyperion/logger.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'json'
+require 'time'
+
+module Hyperion
+  # Structured logger.
+  #
+  # Usage:
+  #   logger = Hyperion::Logger.new
+  #   logger.info  { { message: 'listening', host: '127.0.0.1', port: 9292 } }
+  #   logger.warn  { { message: 'parse error', error: e.message, error_class: e.class.name } }
+  #   logger.error 'plain string also works for legacy callers'
+  #
+  # Level is set from:
+  #   1. The `level:` constructor kwarg (highest precedence).
+  #   2. ENV['HYPERION_LOG_LEVEL'] if set.
+  #   3. Defaults to :info.
+  #
+  # Format is :text (key=value), :json (JSONL), or :auto (default — picks the
+  # right one based on the runtime environment, see #pick_format below).
+  #
+  # Each log line is prefixed with timestamp + level + a 'hyperion' tag so
+  # operators can grep multi-process worker output. When the resolved format
+  # is :text and the underlying IO is a TTY, level names are ANSI-coloured
+  # for readability.
+  class Logger
+    LEVELS = { debug: 0, info: 1, warn: 2, error: 3, fatal: 4 }.freeze
+
+    LEVEL_COLORS = {
+      debug: "\e[90m", # bright black / grey
+      info: "\e[32m",  # green
+      warn: "\e[33m",  # yellow
+      error: "\e[31m",  # red
+      fatal: "\e[35m"   # magenta
+    }.freeze
+    COLOR_RESET = "\e[0m"
+
+    PRODUCTION_ENVS = %w[production staging].freeze
+
+    attr_reader :level, :format
+
+    # Levels at WARN or higher are routed to the error stream (stderr by
+    # default). info / debug go to the regular stream (stdout by default).
+    # 12-factor: app logs to stdout, errors to stderr.
+    ERROR_LEVELS = %i[warn error fatal].freeze
+
+    def initialize(out: $stdout, err: $stderr, io: nil, level: nil, format: nil)
+      # `io:` is a back-compat alias for tests / single-IO use cases — it
+      # routes both streams to the same target (e.g. a StringIO in specs).
+      @out = io || out
+      @err = io || err
+      @level = parse_level(level || ENV.fetch('HYPERION_LOG_LEVEL', 'info'))
+      requested = format || ENV['HYPERION_LOG_FORMAT']
+      @format = pick_format(requested)
+      # Colorize when format is text AND the destination is a TTY. We only
+      # check the regular stream here — colored text is for humans.
+      @colorize = @format == :text && tty?(@out)
+    end
+
+    LEVELS.each_key do |lvl|
+      define_method(lvl) do |payload = nil, &block|
+        next unless emit?(lvl)
+
+        actual = block ? block.call : payload
+        write(lvl, actual)
+      end
+    end
+
+    # Pick the destination IO for a given level.
+    # warn / error / fatal → @err (stderr default).
+    # debug / info        → @out (stdout default).
+    def io_for(lvl)
+      ERROR_LEVELS.include?(lvl) ? @err : @out
+    end
+
+    def level=(lvl)
+      @level = parse_level(lvl)
+    end
+
+    # Per-thread access-log buffer flush threshold. ~32 average-size lines
+    # per write(2) call, well under PIPE_BUF (4096) so writes stay atomic.
+    # Larger = fewer syscalls but higher latency-to-disk (up to ~32 reqs of
+    # delay before the line shows up in the log file). 4 KiB is a good
+    # balance: a 16-thread fleet at 24k r/s flushes ~750 buffers/sec total
+    # vs ~24 000 syscalls/sec without buffering.
+    ACCESS_FLUSH_BYTES = 4096
+
+    # Hot-path access-log emitter — bypasses the generic format_text /
+    # format_json kvs.join + hash#map allocations. The whole line is built
+    # via a single interpolation, the timestamp is cached per-thread per
+    # millisecond, and we batch lines into a per-thread buffer that flushes
+    # when full (lock-free emit; POSIX write(2) is atomic for writes
+    # <= PIPE_BUF / 4096 bytes).
+    #
+    # Returns silently on any IO error — logging must never crash the server.
+    def access(method, path, query, status, duration_ms, remote_addr, http_version)
+      return unless emit?(:info)
+
+      ts = cached_timestamp
+      line = if @format == :json
+               build_access_json(ts, method, path, query, status, duration_ms, remote_addr, http_version)
+             else
+               build_access_text(ts, method, path, query, status, duration_ms, remote_addr, http_version)
+             end
+
+      buf = (Thread.current[:__hyperion_access_buf__] ||= +'')
+      buf << line
+      return if buf.bytesize < ACCESS_FLUSH_BYTES
+
+      @out.write(buf)
+      buf.clear
+    rescue StandardError
+      # Swallow logger failures — never let logging crash the server.
+    end
+
+    # Flush this thread's buffered access-log lines. Called by the connection
+    # loop when a connection closes (so log lines from a closing keep-alive
+    # session don't get stuck behind the buffer until the next connection).
+    def flush_access_buffer
+      buf = Thread.current[:__hyperion_access_buf__]
+      return if buf.nil? || buf.empty?
+
+      @out.write(buf)
+      buf.clear
+    rescue StandardError
+      # Swallow logger failures — never let logging crash the server.
+    end
+
+    private
+
+    # Cached UTC iso8601(3) timestamp, refreshed at most once per millisecond
+    # per thread. At 24k r/s with 16 threads we render ~1500 r/s/thread; only
+    # ~1000 of those allocate a new String. The other 500 reuse the cached one.
+    def cached_timestamp
+      now_ms = Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
+      cache = (Thread.current[:__hyperion_ts_cache__] ||= [-1, ''])
+      return cache[1] if cache[0] == now_ms
+
+      cache[0] = now_ms
+      cache[1] = Time.now.utc.iso8601(3)
+      cache[1]
+    end
+
+    # Resolve the effective format.
+    # 1. If the operator passed an explicit value (kwarg or env), honour it.
+    # 2. Else, if the app is running in a production-ish env (RAILS_ENV /
+    #    RACK_ENV / HYPERION_ENV), default to JSON — log aggregators love it.
+    # 3. Else, if stderr is a TTY, default to colored text — humans prefer it.
+    # 4. Else (piped/redirected output, no env hint), default to JSON so
+    #    captured logs are parseable by tooling.
+    def pick_format(requested)
+      if requested && !requested.to_s.empty? && requested.to_s != 'auto'
+        sym = requested.to_s.to_sym
+        return sym if %i[text json].include?(sym)
+      end
+
+      env_name = ENV['HYPERION_ENV'] || ENV['RAILS_ENV'] || ENV['RACK_ENV']
+      return :json if env_name && PRODUCTION_ENVS.include?(env_name)
+      return :text if tty?(@out)
+
+      :json
+    end
+
+    def tty?(io)
+      io.respond_to?(:tty?) && io.tty?
+    rescue StandardError
+      false
+    end
+
+    def emit?(lvl)
+      LEVELS.fetch(lvl) >= LEVELS.fetch(@level)
+    end
+
+    def write(lvl, payload)
+      hash = case payload
+             when Hash then payload
+             when nil  then { message: '' }
+             else { message: payload.to_s }
+             end
+
+      line = case @format
+             when :json then format_json(lvl, hash)
+             else format_text(lvl, hash)
+             end
+
+      # No mutex: POSIX write(2) is atomic for writes <= PIPE_BUF (4096 bytes)
+      # on regular FDs, pipes, and sockets. A single log line is ~200 bytes.
+      # Ruby's IO#write is a thin wrapper; concurrent threads writing short
+      # lines don't interleave bytes within a line. Skipping flush, too:
+      # stdout/stderr are line-buffered or unbuffered respectively when
+      # attached to a terminal, and removing the syscall saves ~30% of the
+      # logger overhead.
+      io_for(lvl).write(line)
+    rescue StandardError
+      # Swallow logger failures — never let logging crash the server.
+    end
+
+    def format_text(lvl, hash)
+      ts = cached_timestamp
+      level_label = lvl.to_s.upcase.ljust(5)
+      level_label = "#{LEVEL_COLORS[lvl]}#{level_label}#{COLOR_RESET}" if @colorize
+      kvs = hash.map { |k, v| "#{k}=#{format_value(v)}" }.join(' ')
+      "#{ts} #{level_label} [hyperion] #{kvs}\n"
+    end
+
+    def format_json(lvl, hash)
+      hash = { ts: cached_timestamp, level: lvl.to_s, source: 'hyperion' }.merge(hash)
+      "#{JSON.generate(hash)}\n"
+    end
+
+    # Hand-rolled text access-log line — single interpolation, no Hash#map,
+    # no Array#join. Matches the structured-hash format users got in rc9
+    # (key=value pairs starting with `message=request`) so existing log
+    # parsers keep working.
+    def build_access_text(ts, method, path, query, status, duration_ms, remote_addr, http_version)
+      level_label = @colorize ? "#{LEVEL_COLORS[:info]}INFO #{COLOR_RESET}" : 'INFO '
+      addr = remote_addr || 'nil'
+      query_part = query.nil? || query.empty? ? '' : " query=#{quote_if_needed(query)}"
+      "#{ts} #{level_label} [hyperion] message=request method=#{method} path=#{path}#{query_part} " \
+        "status=#{status} duration_ms=#{duration_ms} remote_addr=#{addr} http_version=#{http_version}\n"
+    end
+
+    # Hand-rolled JSON access-log line — single interpolation, skips
+    # JSON.generate's Hash walk. The values we write are all server-controlled
+    # (method/path/status/etc) and well-formed; we only need to escape path
+    # and query. Status/duration_ms are numeric, not quoted.
+    def build_access_json(ts, method, path, query, status, duration_ms, remote_addr, http_version)
+      query_field = query.nil? || query.empty? ? '' : %(,"query":#{json_str(query)})
+      addr_field = remote_addr.nil? ? 'null' : json_str(remote_addr)
+      %({"ts":"#{ts}","level":"info","source":"hyperion","message":"request",) +
+        %("method":"#{method}","path":#{json_str(path)}#{query_field},) +
+        %("status":#{status},"duration_ms":#{duration_ms},"remote_addr":#{addr_field},) +
+        %("http_version":"#{http_version}"}\n)
+    end
+
+    # Cheap JSON string serializer — defers to JSON.generate for any value
+    # that needs escaping (control chars, quotes, backslashes). Hot path
+    # (paths like /, /api/v1/games) skips JSON.generate entirely.
+    def json_str(value)
+      s = value.to_s
+      return %("#{s}") if s.match?(%r{\A[A-Za-z0-9._\-/?=&%:+,@!~*';()\[\] ]*\z})
+
+      JSON.generate(s)
+    end
+
+    # Mirror format_value's quoting rule for access-log query strings.
+    def quote_if_needed(value)
+      s = value.to_s
+      s.match?(/[\s"=]/) ? s.inspect : s
+    end
+
+    def format_value(v)
+      case v
+      when nil then 'nil'
+      when String
+        v.match?(/[\s"=]/) ? v.inspect : v
+      else
+        v.to_s
+      end
+    end
+
+    def parse_level(lvl)
+      sym = lvl.to_s.downcase.to_sym
+      LEVELS.key?(sym) ? sym : :info
+    end
+  end
+end