http3 0.0.3

data/lib/http3/rack_adapter.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module HTTP3
+  # Calls a Rack 3 application for an HTTP3::Request and turns what it
+  # returns into an HTTP3::Response.
+  class RackAdapter
+    # The application's response breaks the Rack 3 specification; the
+    # server answers 500 instead.
+    class InvalidResponse < StandardError; end
+
+    # Connection-specific fields, which HTTP/3 forbids (RFC 9114 section
+    # 4.2).
+    CONNECTION_FIELDS = %w[connection keep-alive transfer-encoding upgrade proxy-connection].freeze
+
+    # A response field name: a token (RFC 9110 section 5.6.2), lowercase.
+    FIELD_NAME = /\A[!#$%&'*+\-.^_`|~0-9a-z]+\z/
+
+    # What a field value must not hold (RFC 9114 section 4.2, and the Rack 3
+    # specification).
+    FORBIDDEN_IN_VALUE = /[\0\r\n]/
+
+    def initialize(app)
+      @app = app
+    end
+
+    # remote is the client's address, an Addrinfo. Raises whatever the
+    # application raises, and InvalidResponse for a response that cannot be
+    # sent; the Rack body is closed in both cases.
+    def call(request, remote:)
+      status, headers, body = @app.call(env_for(request, remote))
+      response_for(request, status, headers, body)
+    end
+
+    private
+
+    def env_for(request, remote)
+      pseudo = {}
+      fields = {}
+      request.headers.each do |name, value|
+        if name.start_with?(":")
+          pseudo[name] ||= value
+        else
+          (fields[name] ||= []) << value
+        end
+      end
+
+      path, query = pseudo.fetch(":path", "/").split("?", 2)
+      scheme = pseudo.fetch(":scheme", "https")
+      authority = pseudo[":authority"] || fields["host"]&.first || "localhost"
+      server_name, server_port = split_authority(authority, scheme)
+
+      env = {
+        "REQUEST_METHOD" => pseudo.fetch(":method", "GET"),
+        "SCRIPT_NAME" => "",
+        "PATH_INFO" => path,
+        "QUERY_STRING" => query || "",
+        "SERVER_NAME" => server_name,
+        "SERVER_PORT" => server_port,
+        "SERVER_PROTOCOL" => "HTTP/3",
+        "REMOTE_ADDR" => remote.ip_address,
+        "HTTP_HOST" => authority,
+        "rack.url_scheme" => scheme,
+        "rack.input" => StringIO.new(request.body.b),
+        "rack.errors" => $stderr
+      }
+      fields.each do |name, values|
+        next if name == "host"
+        # "x_forwarded_for" would become HTTP_X_FORWARDED_FOR just like
+        # "x-forwarded-for", letting a client slip a value past a proxy that
+        # only removes or overwrites the latter. Such names are dropped, as
+        # nginx and Puma do.
+        next if name.include?("_")
+
+        # Cookies are split into one field each in HTTP/3 and joined with
+        # "; " again (RFC 9114 section 4.2.1).
+        env[env_key(name)] = values.join((name == "cookie") ? "; " : ", ")
+      end
+      env
+    end
+
+    def env_key(name)
+      case name
+      when "content-type" then "CONTENT_TYPE"
+      when "content-length" then "CONTENT_LENGTH"
+      else "HTTP_#{name.upcase.tr("-", "_")}"
+      end
+    end
+
+    # "host", "host:port", "[v6]" or "[v6]:port"; the port defaults to the
+    # scheme's.
+    def split_authority(authority, scheme)
+      default_port = (scheme == "http") ? "80" : "443"
+      if (match = authority.match(/\A(\[[^\]]*\])(?::(\d+))?\z/))
+        [match[1], match[2] || default_port]
+      else
+        host, port = authority.split(":", 2)
+        [host, port || default_port]
+      end
+    end
+
+    # The Rack body is closed here unless it goes on in the Response.
+    def response_for(request, status, headers, body)
+      response = nil
+      status = Integer(status)
+      headers = header_pairs(headers)
+
+      method = request.headers.assoc(":method")&.last
+      response = if method == "HEAD" || status < 200 || status == 204 || status == 304
+        close_rack_body(body)
+        Response.new(status: status, headers: headers, body: nil)
+      else
+        Response.new(status: status, headers: headers, body: body_for(body))
+      end
+    ensure
+      close_rack_body(body) if response.nil?
+    end
+
+    # Rack 3 headers: lowercase names, each value a String or an Array of
+    # them, one field per element. nghttp3 sends names and values as they
+    # are, so a name that is not a token (":status", say) or a value with
+    # NUL, CR or LF would reach the client, or a proxy that turns the
+    # response into HTTP/1.1, as fields the application never meant. The
+    # message leaves the value out, since it goes to the log.
+    def header_pairs(headers)
+      pairs = []
+      headers.each do |name, value|
+        name = name.to_s
+        raise InvalidResponse, "header name #{name.inspect} has uppercase letters" if name.match?(/[A-Z]/)
+        raise InvalidResponse, "header name #{name.inspect} is not a token" unless name.match?(FIELD_NAME)
+        next if CONNECTION_FIELDS.include?(name)
+
+        Array(value).each do |v|
+          v = v.to_s
+          raise InvalidResponse, "header #{name} has NUL, CR or LF in its value" if v.match?(FORBIDDEN_IN_VALUE)
+
+          pairs << [name, v]
+        end
+      end
+      pairs
+    end
+
+    def body_for(body)
+      if body.respond_to?(:to_path)
+        io = ::File.open(body.to_path, "rb")
+        Body::File.new(io: io, offset: 0, length: io.size, rack_body: body)
+      elsif body.respond_to?(:to_ary)
+        # Rack 3 has to_ary close the body itself.
+        Body::Chunks.new(enum: body.to_ary.each, rack_body: nil)
+      elsif body.respond_to?(:each)
+        Body::Chunks.new(enum: body.to_enum(:each), rack_body: body)
+      else
+        raise InvalidResponse, "streaming bodies (#{body.class}) are not supported"
+      end
+    end
+
+    def close_rack_body(body)
+      body.close if body.respond_to?(:close)
+    end
+  end
+end

data/lib/http3/request.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module HTTP3
+  # A request as a Session put it together. headers is an Array of
+  # [name, value] binary Strings with lowercase names, the pseudo-headers
+  # (:method, :scheme, :authority, :path) first; a repeated name keeps one
+  # pair per field. body is the request body, a binary String.
+  Request = Data.define(:stream_id, :headers, :body)
+end

data/lib/http3/response.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module HTTP3
+  # A response for a Session to send. status is an Integer, headers an Array
+  # of [name, value] Strings without pseudo-headers, and body nil (no
+  # content) or one of the HTTP3::Body types.
+  Response = Data.define(:status, :headers, :body)
+
+  module Body
+    # length bytes of io from offset, read by the C part of the Session as
+    # the connection can take them, through a descriptor of its own. The
+    # Session closes io once the C part has that descriptor, and rack_body,
+    # unless it is nil, when the stream ends.
+    File = Data.define(:io, :offset, :length, :rack_body)
+
+    # Chunks pulled with enum.next as the send buffer drains; StopIteration
+    # ends the body. The Session closes rack_body, unless it is nil, when
+    # the stream ends.
+    Chunks = Data.define(:enum, :rack_body)
+  end
+end

data/lib/http3/server.rb

@@ -0,0 +1,357 @@
+# frozen_string_literal: true
+
+require "logger"
+require "socket"
+
+module HTTP3
+  # An HTTP/3 server for a Rack 3 application, on one UDP address:
+  #
+  #   HTTP3::Server.new(
+  #     app: app, bind: "192.0.2.1:443",
+  #     certificate_path: "fullchain.pem", private_key_path: "privkey.pem"
+  #   ).run
+  #
+  # #run serves until SIGTERM or SIGINT. It then sends GOAWAY to every
+  # client, refuses new connections, and waits up to shutdown_timeout
+  # seconds for the requests under way before closing every connection; a
+  # second signal stops the wait. SIGHUP reads the certificate and key
+  # again for new connections, and keeps the old ones if that fails.
+  #
+  # Only failures are logged, one line each: the event, then key=value
+  # pairs. Requests are not logged; use Rack::CommonLogger for that. Query
+  # strings and header values never appear in the log.
+  class Server
+    ALPN = ["h3"].freeze
+
+    # What the signal handlers write to the self-pipe.
+    SIGNALS = {"TERM" => "T", "INT" => "I", "HUP" => "H"}.freeze
+
+    # The largest UDP payload read at once.
+    RECV_SIZE = 65_535
+
+    # Datagrams read per turn of the loop at most, so that a flood cannot
+    # keep it from sending and running timers.
+    RECV_BATCH = 1024
+
+    # The address #run bound, an Addrinfo; nil until then. With port 0 in
+    # bind, this tells the port.
+    attr_reader :local_address
+
+    # bind is "host:port" or "[v6]:port", one address; 0.0.0.0 and [::] are
+    # refused, since the local address of each path has to be known.
+    # certificate_path is a PEM chain, leaf first; private_key_path a PEM key
+    # without passphrase. qlog_dir writes one qlog file per connection.
+    # max_request_body and max_field_section_size (bytes) bound a request's
+    # body (413 beyond) and header section (431 beyond); send_buffer_size
+    # bounds the bytes of a response body queued but unsent per stream.
+    def initialize(app:, bind:, certificate_path:, private_key_path:, transport_params: nil, settings: nil,
+      qlog_dir: nil, max_connections: 1024, max_request_body: 1_048_576, max_field_section_size: 65_536,
+      send_buffer_size: 65_536, shutdown_timeout: 30, logger: Logger.new($stderr))
+      @adapter = RackAdapter.new(app)
+      @bind_address = parse_bind(bind)
+      @certificate_path = certificate_path
+      @private_key_path = private_key_path
+      @tls_context = new_tls_context
+      @transport_params = transport_params || QUIC::TransportParams.default
+      settings ||= QUIC::Settings.default
+      settings = settings.with(qlog_dir: qlog_dir) if qlog_dir
+      settings.check_qlog_dir
+      @settings = settings
+      @max_connections = max_connections
+      @max_request_body = max_request_body
+      @max_field_section_size = max_field_section_size
+      @send_buffer_size = send_buffer_size
+      @shutdown_timeout = shutdown_timeout
+      @logger = logger
+    end
+
+    # Serve until told to stop (see the class comment). Returns nil.
+    def run
+      sig_r, sig_w = IO.pipe
+      @sock = UDPSocket.new(@bind_address.afamily)
+      @sock.bind(@bind_address.ip_address, @bind_address.ip_port)
+      @local_address = @sock.local_address
+      @endpoint = QUIC::Endpoint.new(
+        local_address: @local_address, tls_context: @tls_context, transport_params: @transport_params,
+        settings: @settings, max_connections: @max_connections
+      )
+      @sessions = {}
+      @remotes = {}
+      @blocked_send = nil
+      @phase = :serving
+      @drain_deadline = nil
+      old_traps = install_traps(sig_w)
+
+      turn(sig_r) until finished?
+      close_connections
+      nil
+    ensure
+      restore_traps(old_traps) if old_traps
+      @sessions&.each_value { |session| release_session(session) }
+      [@sock, sig_r, sig_w].each { |io| io.close if io && !io.closed? }
+    end
+
+    private
+
+    # One turn of the loop.
+    def turn(sig_r)
+      writers = @blocked_send ? [@sock] : nil
+      readable, writable, = IO.select([@sock, sig_r], writers, nil, select_timeout)
+      handle_signals(sig_r) if readable&.include?(sig_r)
+      flush if writable&.include?(@sock)
+      receive if readable&.include?(@sock)
+      serve_requests
+      fill_bodies
+      @endpoint.handle_expiry if due?(@endpoint.expiry)
+      flush
+      reap
+    end
+
+    def finished?
+      case @phase
+      when :serving then false
+      when :draining then now >= @drain_deadline || @sessions.each_value.none?(&:busy?)
+      else true
+      end
+    end
+
+    # Until the next timer or the end of the drain, but no wait at all while
+    # a body could take more.
+    def select_timeout
+      return 0 if @sessions.each_value.any? { |session| session.wants_fill?(@send_buffer_size) }
+
+      timeouts = []
+      expiry = @endpoint.expiry
+      timeouts << [(expiry - now_ns) / 1e9, 0.0].max if expiry
+      timeouts << [@drain_deadline - now, 0.0].max if @drain_deadline
+      timeouts.min
+    end
+
+    # Read into one buffer reused for every datagram: a buffer of RECV_SIZE
+    # per datagram would be garbage at once, and under a download the client
+    # sends thousands of ACKs, enough to grow the process by tens of MiB
+    # between GCs. read_pkt keeps nothing of the buffer.
+    def receive
+      @recv_buffer ||= String.new(capacity: RECV_SIZE, encoding: Encoding::BINARY)
+      RECV_BATCH.times do
+        result = @sock.recvfrom_nonblock(RECV_SIZE, 0, @recv_buffer, exception: false)
+        break if result == :wait_readable
+
+        data, sender_addr = result
+        sender = Addrinfo.new(sender_addr, nil, :DGRAM)
+        conn = @endpoint.read_pkt(data, remote: sender.to_sockaddr)
+        next if conn.nil? || @sessions.key?(conn)
+
+        @sessions[conn] = Session.attach(
+          conn, max_request_body: @max_request_body, max_field_section_size: @max_field_section_size
+        )
+        @remotes[conn] = sender
+      end
+    end
+
+    def serve_requests
+      @sessions.each do |conn, session|
+        session.take_requests.each do |request, status|
+          response = status ? Response.new(status: status, headers: [], body: nil) : call_app(conn, request)
+          begin
+            session.respond(request, response) { |error| log_body_error(conn, request, error) }
+          rescue Nghttp3::Error
+            # The stream went away while the application ran.
+            discard_body(response.body)
+          end
+        end
+      end
+    end
+
+    def call_app(conn, request)
+      @adapter.call(request, remote: @remotes[conn])
+    rescue => e
+      log_app_error(conn, request, e)
+      Response.new(status: 500, headers: [], body: nil)
+    end
+
+    def fill_bodies
+      @sessions.each do |conn, session|
+        session.fill_bodies(@send_buffer_size) { |request, error| log_app_error(conn, request, error) }
+      end
+    end
+
+    # Send what the Endpoint has, until the socket would block.
+    def flush
+      loop do
+        pkt, to = @blocked_send || @endpoint.write_pkt
+        break if pkt.nil?
+
+        result = begin
+          @sock.sendmsg_nonblock(pkt, 0, to, exception: false)
+        rescue SystemCallError
+          # Unreachable, too large, ...: the datagram is lost, as on the
+          # wire.
+          nil
+        end
+        if result == :wait_writable
+          @blocked_send = [pkt, to]
+          break
+        end
+        @blocked_send = nil
+      end
+    end
+
+    # Take out what has ended: streams within each Session, and whole
+    # connections.
+    def reap
+      @sessions.each do |conn, session|
+        if (error = session.take_error)
+          log(:error, "session_error", remote: remote_of(conn), **error_fields(error))
+        end
+        session.release_closed { |stream_id, e| log_body_close_error(stream_id, e) }
+      end
+      @endpoint.take_closed.each do |conn|
+        if conn.error
+          log(:warn, "connection_error", remote: remote_of(conn), error: conn.error.class, message: conn.error.message)
+        end
+        session = @sessions.delete(conn)
+        release_session(session) if session
+        @remotes.delete(conn)
+      end
+    end
+
+    def release_session(session)
+      session.release_all { |stream_id, e| log_body_close_error(stream_id, e) }
+    end
+
+    def handle_signals(sig_r)
+      bytes = sig_r.read_nonblock(64, exception: false)
+      return unless bytes.is_a?(String)
+
+      bytes.each_char { |byte| (byte == SIGNALS["HUP"]) ? reload_tls : begin_shutdown }
+    end
+
+    # First signal: GOAWAY and drain. Second: stop draining.
+    def begin_shutdown
+      if @phase == :serving
+        @phase = :draining
+        @drain_deadline = now + @shutdown_timeout
+        @sessions.each_value(&:shutdown_notice)
+        @endpoint.stop_accepting
+      else
+        @phase = :closing
+      end
+    end
+
+    def reload_tls
+      @endpoint.tls_context = new_tls_context
+    rescue => e
+      log(:error, "tls_reload_failed", certificate_path: @certificate_path, private_key_path: @private_key_path,
+        error: e.class, message: e.message)
+    end
+
+    # Close every connection and send the CONNECTION_CLOSEs, without
+    # waiting out the closing period.
+    def close_connections
+      @endpoint.connections.each do |conn|
+        conn.close(error_code: Nghttp3::H3_NO_ERROR)
+      rescue QUIC::Error
+        nil
+      end
+      deadline = now + 1
+      loop do
+        flush
+        break if @blocked_send.nil? || now >= deadline
+
+        IO.select(nil, [@sock], nil, [deadline - now, 0].max)
+      end
+    end
+
+    def new_tls_context
+      QUIC::TLSContext.server(certificate_path: @certificate_path, private_key_path: @private_key_path, alpn: ALPN)
+    end
+
+    def install_traps(sig_w)
+      SIGNALS.to_h do |name, byte|
+        previous = Signal.trap(name) do
+          sig_w.write_nonblock(byte, exception: false)
+        rescue IOError
+          nil
+        end
+        [name, previous]
+      end
+    end
+
+    def restore_traps(previous)
+      previous.each { |name, handler| Signal.trap(name, handler || "DEFAULT") }
+    end
+
+    def parse_bind(bind)
+      match = bind.match(/\A\[(?<host>[^\]]+)\]:(?<port>\d+)\z/) || bind.match(/\A(?<host>[^:\[\]]+):(?<port>\d+)\z/)
+      raise ArgumentError, "bind must be \"host:port\" or \"[ipv6]:port\" (got #{bind.inspect})" unless match
+
+      address = Addrinfo.udp(match[:host], Integer(match[:port], 10))
+      if address.ip_address == "0.0.0.0" || address.ip_address == "::"
+        raise ArgumentError, "bind must name the address to serve, not #{address.ip_address}"
+      end
+      address
+    end
+
+    def discard_body(body)
+      return if body.nil?
+
+      body.io.close if body.is_a?(Body::File) && !body.io.closed?
+      body.rack_body.close if body.rack_body.respond_to?(:close)
+    rescue => e
+      log(:error, "body_close_error", **error_fields(e))
+    end
+
+    def log_app_error(conn, request, error)
+      pseudo = request.headers.select { |name, _| name.start_with?(":") }.to_h
+      path = pseudo.fetch(":path", "")[/\A[^?]*/]
+      log(:error, "app_error", remote: remote_of(conn), stream: request.stream_id, method: pseudo[":method"],
+        path: path, **error_fields(error))
+    end
+
+    def log_body_error(conn, request, error)
+      log(:error, "body_error", remote: remote_of(conn), stream: request.stream_id, error: error.class,
+        message: error.message)
+    end
+
+    def log_body_close_error(stream_id, error)
+      log(:error, "body_close_error", stream: stream_id, error: error.class, message: error.message)
+    end
+
+    def error_fields(error)
+      fields = {error: error.class, message: error.message}
+      if (location = error.backtrace_locations&.first)
+        fields[:at] = "#{location.path}:#{location.lineno}"
+      end
+      fields
+    end
+
+    # The event, then key=value; a value with a space, '"' or '=' is
+    # written with String#inspect.
+    def log(level, event, **fields)
+      pairs = fields.map do |key, value|
+        text = value.to_s
+        "#{key}=#{text.match?(/[\s"=]/) ? text.inspect : text}"
+      end
+      @logger.public_send(level, [event, *pairs].join(" "))
+    end
+
+    def remote_of(conn)
+      address = @remotes[conn] or return "-"
+      host = address.ipv6? ? "[#{address.ip_address}]" : address.ip_address
+      "#{host}:#{address.ip_port}"
+    end
+
+    def due?(expiry)
+      expiry && expiry <= now_ns
+    end
+
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def now_ns
+      Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
+    end
+  end
+end