http3 0.0.3

data/lib/http3/session.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module HTTP3
+  # HTTP/3 on one QUIC connection. The C part (ext/http3/session.c) runs
+  # nghttp3 inside the connection's packet I/O and calls the on_* methods
+  # below with the parts of each request. This part puts the requests
+  # together and keeps the bodies of the responses being sent.
+  #
+  # A Session belongs to the server's I/O loop: Server takes the finished
+  # requests, answers them, keeps the bodies flowing and lets go of what
+  # the streams no longer need.
+  class Session
+    # A request still coming in. reject is the status to answer with
+    # instead of calling the application (413, 431), or nil.
+    Incoming = Struct.new(:pseudo, :fields, :body, :reject)
+
+    # A response whose body is being sent.
+    Outgoing = Struct.new(:request, :body, :done)
+
+    # Take over quic_conn's streams. A request body over max_request_body
+    # bytes is answered with 413, a header section over
+    # max_field_section_size bytes (RFC 9114 section 4.2.2) with 431.
+    def self.attach(quic_conn, max_request_body:, max_field_section_size:)
+      session = _attach(quic_conn, max_field_section_size)
+      session.send(:setup, max_request_body)
+      session
+    end
+
+    # The requests received in full since the last call, each as
+    # [request, status]: status is nil for the application to answer the
+    # request, or the status to answer it with directly.
+    def take_requests
+      done = @done
+      @done = []
+      done
+    end
+
+    # Send response to request. Its body, if any, is kept until the stream
+    # closes, but the IO of a Body::File is closed at once: the C part reads
+    # the file through a descriptor of its own. When that descriptor cannot
+    # be had (EMFILE, say), the stream is aborted with H3_INTERNAL_ERROR and
+    # the block gets the exception.
+    def respond(request, response)
+      headers = [[":status", response.status.to_s], *response.headers]
+      body = response.body
+      submit_response(request.stream_id, headers, !body.nil?)
+      return if body.nil?
+
+      @outgoing[request.stream_id] = Outgoing.new(request, body, false)
+      return unless body.is_a?(Body::File)
+
+      begin
+        attach_file(request.stream_id, body.io, body.offset, body.length)
+      rescue SystemCallError => e
+        abort_stream(request.stream_id, Nghttp3::H3_INTERNAL_ERROR)
+        yield e if block_given?
+      ensure
+        body.io.close
+      end
+    end
+
+    # Queue more of each Body::Chunks body until limit bytes wait unsent on
+    # its stream. A body whose enum raises is the application failing after
+    # its headers went out: the stream is aborted with H3_INTERNAL_ERROR and
+    # the block gets (request, exception).
+    def fill_bodies(limit)
+      @outgoing.each_value do |out|
+        next if out.done || !out.body.is_a?(Body::Chunks)
+
+        fill_body(out, limit) { |error| yield out.request, error if block_given? }
+      end
+    end
+
+    # True when a Body::Chunks body could take more right now.
+    def wants_fill?(limit)
+      @outgoing.any? do |id, out|
+        !out.done && out.body.is_a?(Body::Chunks) && unsent_bytes(id) < limit
+      end
+    end
+
+    # True while a request stream is open: received in part, waiting for
+    # its answer, or with a response still being sent.
+    def busy?
+      !@open.empty?
+    end
+
+    # Let go of the streams nghttp3 closed: their requests are dropped and
+    # their bodies closed. The block gets (stream_id, exception) for a body
+    # whose close raised.
+    def release_closed(&block)
+      take_closed.each { |id| release(id, &block) }
+    end
+
+    # The connection is gone: close every body still held.
+    def release_all(&block)
+      (@open.keys | @outgoing.keys).each { |id| release(id, &block) }
+    end
+
+    # Called by the C part.
+
+    def on_begin_headers(id)
+      @open[id] = true
+      @incoming[id] = Incoming.new([], [], "".b, nil)
+    end
+
+    def on_header(id, name, value)
+      request = @incoming[id] or return
+      (name.start_with?(":") ? request.pseudo : request.fields) << [name, value]
+    end
+
+    def on_fields_too_large(id)
+      request = @incoming[id] or return
+      request.reject = 431
+    end
+
+    def on_end_headers(id)
+    end
+
+    def on_data(id, bytes)
+      request = @incoming[id] or return
+      return if request.reject
+
+      if request.body.bytesize + bytes.bytesize > @max_request_body
+        request.reject = 413
+        request.body = "".b
+      else
+        request.body << bytes
+      end
+    end
+
+    def on_end_stream(id)
+      request = @incoming.delete(id) or return
+      headers = request.pseudo + request.fields
+      @done << [Request.new(stream_id: id, headers: headers, body: request.body), request.reject]
+    end
+
+    private
+
+    def setup(max_request_body)
+      @max_request_body = max_request_body
+      @incoming = {}
+      @done = []
+      @outgoing = {}
+      @open = {}
+    end
+
+    def fill_body(out, limit)
+      id = out.request.stream_id
+      while unsent_bytes(id) < limit
+        begin
+          chunk = out.body.enum.next
+        rescue StopIteration
+          out.done = true
+          push_eof(id)
+          return
+        rescue => e
+          out.done = true
+          abort_stream(id, Nghttp3::H3_INTERNAL_ERROR)
+          yield e
+          return
+        end
+        unless chunk.is_a?(String)
+          out.done = true
+          abort_stream(id, Nghttp3::H3_INTERNAL_ERROR)
+          yield TypeError.new("body chunk must be a String (got #{chunk.class})")
+          return
+        end
+        push_chunk(id, chunk)
+      end
+    rescue Nghttp3::Error
+      # The stream went away under the body (the peer reset it); it is
+      # released when its close comes through.
+      out.done = true
+    end
+
+    def release(id)
+      @open.delete(id)
+      @incoming.delete(id)
+      @done.reject! { |request, _| request.stream_id == id }
+      out = @outgoing.delete(id) or return
+
+      close_body(out.body)
+    rescue => e
+      yield id, e if block_given?
+    end
+
+    def close_body(body)
+      body.io.close if body.is_a?(Body::File) && !body.io.closed?
+    ensure
+      body.rack_body.close if body.rack_body.respond_to?(:close)
+    end
+  end
+end

data/lib/http3/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HTTP3
+  VERSION = "0.0.3"
+end

data/lib/http3.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "http3/version"
+require_relative "http3/http3"
+
+require_relative "http3/request"
+require_relative "http3/response"
+require_relative "http3/session"
+require_relative "http3/rack_adapter"
+require_relative "http3/server"
+
+module HTTP3
+  module Nghttp3
+    class Error < StandardError; end
+  end
+end

data/sig/http3/nghttp3/callbacks.rbs

@@ -0,0 +1,32 @@
+module HTTP3
+  module Nghttp3
+    class Callbacks
+      def initialize: () -> void
+
+      # Stream data callbacks
+      def on_acked_stream_data: () { (Integer stream_id, Integer datalen) -> void } -> self
+      def on_stream_close: () { (Integer stream_id, Integer app_error_code) -> void } -> self
+      def on_recv_data: () { (Integer stream_id, String data) -> void } -> self
+      def on_deferred_consume: () { (Integer stream_id, Integer consumed) -> void } -> self
+
+      # Header callbacks
+      def on_begin_headers: () { (Integer stream_id) -> void } -> self
+      def on_recv_header: () { (Integer stream_id, String name, String value, Integer flags) -> void } -> self
+      def on_end_headers: () { (Integer stream_id, bool fin) -> void } -> self
+
+      # Trailer callbacks
+      def on_begin_trailers: () { (Integer stream_id) -> void } -> self
+      def on_recv_trailer: () { (Integer stream_id, String name, String value, Integer flags) -> void } -> self
+      def on_end_trailers: () { (Integer stream_id, bool fin) -> void } -> self
+
+      # Stream control callbacks
+      def on_stop_sending: () { (Integer stream_id, Integer app_error_code) -> void } -> self
+      def on_end_stream: () { (Integer stream_id) -> void } -> self
+      def on_reset_stream: () { (Integer stream_id, Integer app_error_code) -> void } -> self
+
+      # Connection callbacks
+      def on_shutdown: () { (Integer id) -> void } -> self
+      def on_recv_settings: () { (Hash[Symbol, untyped] settings) -> void } -> self
+    end
+  end
+end

data/sig/http3/nghttp3/connection.rbs

@@ -0,0 +1,101 @@
+module HTTP3
+  module Nghttp3
+    class Connection
+      # Creates a new client connection
+      def self.client_new: (?Settings? settings, ?Callbacks? callbacks) -> Connection
+
+      # Creates a new server connection
+      def self.server_new: (?Settings? settings, ?Callbacks? callbacks) -> Connection
+
+      # Binds the control stream
+      def bind_control_stream: (Integer stream_id) -> self
+
+      # Binds QPACK encoder and decoder streams
+      def bind_qpack_streams: (Integer encoder_stream_id, Integer decoder_stream_id) -> self
+
+      # Closes the connection
+      def close: () -> nil
+
+      # Returns true if the connection is closed
+      def closed?: () -> bool
+
+      # Returns true if this is a server connection
+      def server?: () -> bool
+
+      # Returns true if this is a client connection
+      def client?: () -> bool
+
+      # Stream operations
+
+      # Reads data on a stream from the QUIC layer. ts is the time in
+      # nanoseconds on a monotonic clock (CLOCK_MONOTONIC by default). An
+      # exception raised by a callback comes out of here.
+      def read_stream: (Integer stream_id, String data, ?fin: bool, ?ts: Integer?) -> Integer
+
+      # Gets stream data to send to the QUIC layer. An exception raised by a
+      # body block comes out of here.
+      def writev_stream: () -> { stream_id: Integer, fin: bool, data: String }?
+
+      # Tells the connection that n bytes have been accepted by the QUIC layer
+      def add_write_offset: (Integer stream_id, Integer n) -> self
+
+      # Tells the connection that n bytes have been acknowledged by the remote peer
+      def add_ack_offset: (Integer stream_id, Integer n) -> self
+
+      # Marks a stream as blocked due to QUIC flow control
+      def block_stream: (Integer stream_id) -> self
+
+      # Marks a stream as unblocked
+      def unblock_stream: (Integer stream_id) -> self
+
+      # Returns true if the stream is writable
+      def stream_writable?: (Integer stream_id) -> bool
+
+      # Closes the stream with the given error code
+      def close_stream: (Integer stream_id, Integer app_error_code) -> self
+
+      # Prevents any further write operations on the stream
+      def shutdown_stream_write: (Integer stream_id) -> self
+
+      # Resumes a stream that was blocked for input data
+      def resume_stream: (Integer stream_id) -> self
+
+      # Tells the connection that no more data will be read on the stream
+      def shutdown_stream_read: (Integer stream_id) -> self
+
+      # Tells a server connection how many bidirectional streams the client
+      # may open in total
+      def set_max_client_streams_bidi: (Integer max_streams) -> self
+
+      # The body Strings handed to nghttp3 that the peer has not acknowledged
+      # in full yet, oldest first (a copy)
+      def pending_data: (Integer stream_id) -> Array[String]
+
+      # HTTP operations
+
+      # Submits an HTTP request (client only)
+      def submit_request: (Integer stream_id, Array[NV] headers, ?body: String?) ?{ (Integer stream_id) -> (String | Symbol | nil) } -> self
+
+      # Submits an HTTP response (server only)
+      def submit_response: (Integer stream_id, Array[NV] headers, ?body: String?) ?{ (Integer stream_id) -> (String | Symbol | nil) } -> self
+
+      # Submits a 1xx informational response
+      def submit_info: (Integer stream_id, Array[NV] headers) -> self
+
+      # Submits trailer headers (implicitly ends the stream)
+      def submit_trailers: (Integer stream_id, Array[NV] trailers) -> self
+
+      # Signals the intention to shut down the connection gracefully
+      def submit_shutdown_notice: () -> self
+
+      # Initiates graceful shutdown
+      def shutdown: () -> self
+
+      # Associates arbitrary data with a stream
+      def set_stream_user_data: (Integer stream_id, untyped data) -> self
+
+      # Returns data associated with a stream
+      def get_stream_user_data: (Integer stream_id) -> untyped
+    end
+  end
+end

data/sig/http3/nghttp3/error.rbs

@@ -0,0 +1,48 @@
+module HTTP3
+  module Nghttp3
+    class Error < StandardError
+    end
+
+    class InvalidArgumentError < Error
+    end
+
+    class InvalidStateError < Error
+    end
+
+    class WouldBlockError < Error
+    end
+
+    class StreamInUseError < Error
+    end
+
+    class MalformedHTTPHeaderError < Error
+    end
+
+    class MalformedHTTPMessagingError < Error
+    end
+
+    class QPACKFatalError < Error
+    end
+
+    class QPACKHeaderTooLargeError < Error
+    end
+
+    class StreamNotFoundError < Error
+    end
+
+    class ConnClosingError < Error
+    end
+
+    class StreamDataOverflowError < Error
+    end
+
+    class FatalError < Error
+    end
+
+    class NoMemError < Error
+    end
+
+    class CallbackFailureError < Error
+    end
+  end
+end

data/sig/http3/nghttp3/info.rbs

@@ -0,0 +1,9 @@
+module HTTP3
+  module Nghttp3
+    class Info
+      def age: () -> Integer
+      def version_num: () -> Integer
+      def version_str: () -> String
+    end
+  end
+end

data/sig/http3/nghttp3/nv.rbs

@@ -0,0 +1,11 @@
+module HTTP3
+  module Nghttp3
+    class NV
+      def initialize: (String name, String value, ?flags: Integer) -> void
+
+      def name: () -> String
+      def value: () -> String
+      def flags: () -> Integer
+    end
+  end
+end

data/sig/http3/nghttp3/qpack.rbs

@@ -0,0 +1,48 @@
+module HTTP3
+  module Nghttp3
+    module QPACK
+      class Encoder
+        # Creates a new QPACK encoder
+        def initialize: (Integer max_dtable_capacity) -> void
+
+        # Encodes headers for a given stream
+        def encode: (Integer stream_id, Array[NV] headers) -> { prefix: String, data: String, encoder_stream: String }
+
+        # Reads decoder stream data
+        def read_decoder: (String data) -> Integer
+
+        # Sets the maximum dynamic table capacity
+        def max_dtable_capacity=: (Integer capacity) -> Integer
+
+        # Sets the maximum number of blocked streams
+        def max_blocked_streams=: (Integer num) -> Integer
+
+        # Returns the number of currently blocked streams
+        def num_blocked_streams: () -> Integer
+      end
+
+      class Decoder
+        # Creates a new QPACK decoder
+        def initialize: (Integer max_dtable_capacity, Integer max_blocked_streams) -> void
+
+        # Decodes headers from a stream
+        def decode: (Integer stream_id, String data, ?fin: bool) -> { headers: Array[{ name: String, value: String, token: Integer }]?, blocked: bool, consumed: Integer }
+
+        # Reads encoder stream data
+        def read_encoder: (String data) -> Integer
+
+        # Returns data to be sent on the decoder stream
+        def decoder_stream_data: () -> String
+
+        # Cancels decoding for the given stream
+        def cancel_stream: (Integer stream_id) -> void
+
+        # Sets the maximum dynamic table capacity
+        def max_dtable_capacity=: (Integer capacity) -> Integer
+
+        # Returns the current insert count
+        def insert_count: () -> Integer
+      end
+    end
+  end
+end

data/sig/http3/nghttp3/settings.rbs

@@ -0,0 +1,27 @@
+module HTTP3
+  module Nghttp3
+    class Settings
+      def self.default: () -> Settings
+
+      def initialize: () -> void
+
+      def max_field_section_size: () -> Integer
+      def max_field_section_size=: (Integer value) -> Integer
+
+      def qpack_max_dtable_capacity: () -> Integer
+      def qpack_max_dtable_capacity=: (Integer value) -> Integer
+
+      def qpack_encoder_max_dtable_capacity: () -> Integer
+      def qpack_encoder_max_dtable_capacity=: (Integer value) -> Integer
+
+      def qpack_blocked_streams: () -> Integer
+      def qpack_blocked_streams=: (Integer value) -> Integer
+
+      def enable_connect_protocol: () -> bool
+      def enable_connect_protocol=: (boolish value) -> boolish
+
+      def h3_datagram: () -> bool
+      def h3_datagram=: (boolish value) -> boolish
+    end
+  end
+end

data/sig/http3/rack_adapter.rbs

@@ -0,0 +1,18 @@
+module HTTP3
+  # Calls a Rack 3 application for a Request and turns its answer into a
+  # Response.
+  class RackAdapter
+    class InvalidResponse < StandardError
+    end
+
+    CONNECTION_FIELDS: Array[String]
+    FIELD_NAME: Regexp
+    FORBIDDEN_IN_VALUE: Regexp
+
+    def initialize: (untyped app) -> void
+
+    # Raises what the application raises, and InvalidResponse for an
+    # answer that cannot be sent; the Rack body is closed either way.
+    def call: (Request request, remote: Addrinfo) -> Response
+  end
+end

data/sig/http3/request.rbs

@@ -0,0 +1,11 @@
+module HTTP3
+  # A request as a Session put it together. headers holds [name, value]
+  # pairs with lowercase names, the pseudo-headers first.
+  class Request < Data
+    attr_reader stream_id: Integer
+    attr_reader headers: Array[[String, String]]
+    attr_reader body: String
+
+    def self.new: (stream_id: Integer, headers: Array[[String, String]], body: String) -> Request
+  end
+end

data/sig/http3/response.rbs

@@ -0,0 +1,30 @@
+module HTTP3
+  # A response for a Session to send; headers exclude pseudo-headers.
+  class Response < Data
+    attr_reader status: Integer
+    attr_reader headers: Array[[String, String]]
+    attr_reader body: Body::File | Body::Chunks | nil
+
+    def self.new: (status: Integer, headers: Array[[String, String]], body: Body::File | Body::Chunks | nil) -> Response
+  end
+
+  module Body
+    # length bytes of io from offset, read by the C part of the Session.
+    class File < Data
+      attr_reader io: ::File
+      attr_reader offset: Integer
+      attr_reader length: Integer
+      attr_reader rack_body: untyped
+
+      def self.new: (io: ::File, offset: Integer, length: Integer, rack_body: untyped) -> File
+    end
+
+    # Chunks pulled with enum.next as the send buffer drains.
+    class Chunks < Data
+      attr_reader enum: Enumerator[String, untyped]
+      attr_reader rack_body: untyped
+
+      def self.new: (enum: Enumerator[String, untyped], rack_body: untyped) -> Chunks
+    end
+  end
+end

data/sig/http3/server.rbs

@@ -0,0 +1,32 @@
+module HTTP3
+  # An HTTP/3 server for a Rack 3 application on one UDP address. #run
+  # serves until SIGTERM or SIGINT, then drains; SIGHUP reloads the
+  # certificate and key.
+  class Server
+    ALPN: Array[String]
+    SIGNALS: Hash[String, String]
+    RECV_SIZE: Integer
+    RECV_BATCH: Integer
+
+    # The address #run bound; nil until then.
+    attr_reader local_address: Addrinfo?
+
+    def initialize: (
+      app: untyped,
+      bind: String,
+      certificate_path: String | _ToPath,
+      private_key_path: String | _ToPath,
+      ?transport_params: QUIC::TransportParams?,
+      ?settings: QUIC::Settings?,
+      ?qlog_dir: (String | _ToPath)?,
+      ?max_connections: Integer,
+      ?max_request_body: Integer,
+      ?max_field_section_size: Integer,
+      ?send_buffer_size: Integer,
+      ?shutdown_timeout: Numeric,
+      ?logger: Logger
+    ) -> void
+
+    def run: () -> nil
+  end
+end

data/sig/http3/session.rbs

@@ -0,0 +1,52 @@
+module HTTP3
+  # HTTP/3 on one QUIC connection, driven by HTTP3::Server's I/O loop. The
+  # on_* methods are called by the C part with the parts of each request.
+  class Session
+    # Take over quic_conn's streams. Requests over max_request_body bytes of
+    # body get 413, over max_field_section_size bytes of headers 431.
+    def self.attach: (QUIC::Connection::Server quic_conn, max_request_body: Integer, max_field_section_size: Integer) -> Session
+
+    def self._attach: (QUIC::Connection::Server quic_conn, Integer max_field_section_size) -> Session
+
+    # Finished requests, each with the status to answer it with directly
+    # (413, 431) or nil for the application to answer it.
+    def take_requests: () -> Array[[Request, Integer?]]
+
+    # Send response. Yields the exception of a file body whose descriptor
+    # could not be duplicated; its stream is aborted.
+    def respond: (Request request, Response response) ?{ (SystemCallError error) -> void } -> void
+
+    # Queue more of each Body::Chunks body, up to limit unsent bytes per
+    # stream. Yields the request and exception of a body that raised.
+    def fill_bodies: (Integer limit) ?{ (Request request, Exception error) -> void } -> void
+
+    def wants_fill?: (Integer limit) -> bool
+
+    # True while a request stream is open.
+    def busy?: () -> bool
+
+    # Let go of closed streams; yields a body close that raised.
+    def release_closed: () ?{ (Integer stream_id, Exception error) -> void } -> void
+
+    # Close every body still held.
+    def release_all: () ?{ (Integer stream_id, Exception error) -> void } -> void
+
+    def on_begin_headers: (Integer id) -> void
+    def on_header: (Integer id, String name, String value) -> void
+    def on_fields_too_large: (Integer id) -> void
+    def on_end_headers: (Integer id) -> void
+    def on_data: (Integer id, String bytes) -> void
+    def on_end_stream: (Integer id) -> void
+
+    # The C part.
+    def submit_response: (Integer stream_id, Array[[String, String]] headers, bool has_body) -> self
+    def push_chunk: (Integer stream_id, String str) -> self
+    def push_eof: (Integer stream_id) -> self
+    def attach_file: (Integer stream_id, IO io, Integer offset, Integer length) -> self
+    def unsent_bytes: (Integer stream_id) -> Integer
+    def take_closed: () -> Array[Integer]
+    def take_error: () -> Exception?
+    def shutdown_notice: () -> self
+    def abort_stream: (Integer stream_id, Integer app_error_code) -> self
+  end
+end