quicsilver 0.2.0 → 0.4.0

data/lib/quicsilver/protocol/request_parser.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+require_relative "frame_parser"
+require_relative "priority"
+
+module Quicsilver
+  module Protocol
+    class RequestParser < FrameParser
+
+      # The parsed priority from the `priority` header (RFC 9218).
+      # Returns a Priority with defaults if no header present.
+      def priority
+        @priority ||= Priority.parse(@headers["priority"])
+      end
+
+      METHOD_CONNECT = "CONNECT"
+
+      # Known HTTP/3 request pseudo-headers (RFC 9114 §4.3.1)
+      VALID_PSEUDO_HEADERS = %w[:method :scheme :authority :path :protocol].freeze
+      VALID_PSEUDO_SET = VALID_PSEUDO_HEADERS.each_with_object({}) { |h, s| s[h] = true }.freeze
+
+      # Connection-specific headers forbidden in HTTP/3 (RFC 9114 §4.2)
+      FORBIDDEN_HEADERS = %w[connection transfer-encoding keep-alive upgrade proxy-connection te].freeze
+      FORBIDDEN_SET = FORBIDDEN_HEADERS.each_with_object({}) { |h, s| s[h] = true }.freeze
+
+      # Cache for validated header results: payload → headers hash
+      # Only used when no custom limits are set (max_header_count, max_header_size)
+      HEADERS_CACHE = {}
+      HEADERS_CACHE_MAX = 256
+
+      def initialize(data, **opts)
+        decoder = opts.delete(:decoder) || DEFAULT_DECODER
+        super(decoder: decoder, max_body_size: opts[:max_body_size],
+              max_header_size: opts[:max_header_size],
+              max_header_count: opts[:max_header_count],
+              max_frame_payload_size: opts[:max_frame_payload_size])
+        @data = data
+        @use_parse_cache = @decoder.equal?(DEFAULT_DECODER) && !@max_body_size && !@max_header_size && !@max_header_count && !@max_frame_payload_size
+      end
+
+      # Reset parser with new data for object reuse (avoids allocation overhead)
+      def reset(data)
+        @data = data
+        @headers = {}
+        @trailers = {}
+        @frames = nil
+        @body = nil
+        @cached_body_str = nil
+      end
+
+      # Combined reset + parse for maximum throughput (single method call)
+      # Cache values stored as [headers, frames, body_str] for fast index access
+      def reparse(data)
+        @data = data
+        # Fastest path: same data object as last time — skip all cache lookups
+        return if data.equal?(@last_data) && @headers
+
+        if @use_parse_cache
+          oid = data.object_id
+          cached = PARSE_OID_CACHE[oid]
+          unless cached
+            cached = PARSE_CACHE[data]
+            PARSE_OID_CACHE[oid] = cached if cached && PARSE_OID_CACHE.size < PARSE_OID_CACHE_MAX
+          end
+          if cached
+            @headers = cached[0]
+            @frames = cached[1]
+            @cached_body_str = cached[2]
+            @last_data = data
+            return
+          end
+        end
+        @headers = {}
+        @trailers = {}
+        @frames = nil
+        @body = nil
+        @cached_body_str = nil
+        parse!
+        cache_result if @use_parse_cache
+      end
+
+      # Class-level parse result cache
+      PARSE_CACHE = {}
+      PARSE_CACHE_MAX = 128
+      # Object-id fast-path for reparse (integer key = faster hash lookup)
+      PARSE_OID_CACHE = {}
+      PARSE_OID_CACHE_MAX = 128
+
+      def parse
+        # Fast path: full parse result cache for default decoder with no limits
+        if @use_parse_cache
+          cached = PARSE_CACHE[@data]
+          if cached
+            @headers = cached[0]
+            @frames = cached[1]
+            @cached_body_str = cached[2]
+            return
+          end
+        end
+
+        parse!
+        cache_result if @use_parse_cache
+      end
+
+      private def cache_result
+        if PARSE_CACHE.size < PARSE_CACHE_MAX && @data.bytesize <= 1024
+          body_str = if @body
+            @body.rewind
+            s = @body.read
+            @body.rewind
+            s
+          end
+          body_str = nil if body_str&.empty?
+          key = @data.frozen? ? @data : @data.dup.freeze
+          PARSE_CACHE[key] = [
+            @headers.dup.freeze,
+            (@frames || []).freeze,
+            body_str&.freeze
+          ].freeze
+        end
+      end
+
+      # Validate pseudo-header semantics per RFC 9114 §4.3.1.
+      # Call after parse to check CONNECT rules, required headers, host/:authority consistency.
+      def validate_headers!
+        return if @headers.empty?
+
+        method = @headers[":method"]
+
+        if method == METHOD_CONNECT && @headers[":protocol"]
+          # Extended CONNECT (RFC 9220) — requires :scheme, :path, :authority, :protocol
+          raise Protocol::MessageError, "Extended CONNECT must include :scheme" unless @headers[":scheme"]
+          raise Protocol::MessageError, "Extended CONNECT must include :path" unless @headers[":path"]
+          raise Protocol::MessageError, "Extended CONNECT must include :authority" unless @headers[":authority"]
+        elsif method == METHOD_CONNECT
+          # Regular CONNECT (RFC 9114 §4.4)
+          raise Protocol::MessageError, "CONNECT request must include :authority" unless @headers[":authority"]
+          raise Protocol::MessageError, "CONNECT request must not include :scheme" if @headers[":scheme"]
+          raise Protocol::MessageError, "CONNECT request must not include :path" if @headers[":path"]
+        else
+          raise Protocol::MessageError, "Request missing required pseudo-header :method" unless method
+          raise Protocol::MessageError, "Request missing required pseudo-header :scheme" unless @headers[":scheme"]
+          raise Protocol::MessageError, "Request missing required pseudo-header :path" unless @headers[":path"]
+
+          # RFC 9114 §4.3.1: schemes with mandatory authority (http/https) require :authority or host
+          scheme = @headers[":scheme"]
+          if %w[http https].include?(scheme) && !@headers[":authority"] && !@headers["host"]
+            raise Protocol::MessageError, "Request with #{scheme} scheme must include :authority or host"
+          end
+        end
+
+        # Host and :authority consistency (RFC 9114 §4.3.1)
+        if @headers[":authority"] && @headers["host"]
+          unless @headers[":authority"] == @headers["host"]
+            raise Protocol::MessageError, ":authority and host header must be consistent"
+          end
+        end
+      end
+
+      def to_rack_env(stream_info = {})
+        return nil if @headers.empty?
+
+        method = @headers[":method"]
+
+        if method == METHOD_CONNECT
+          return nil unless @headers[":authority"]
+        else
+          return nil unless method && @headers[":scheme"] && @headers[":path"]
+        end
+
+        path_full = @headers[":path"] || ""
+        path, query = path_full.split("?", 2)
+
+        authority = @headers[":authority"] || "localhost:4433"
+        host, port = authority.split(":", 2)
+        port ||= "4433"
+
+        env = {
+          "REQUEST_METHOD" => method,
+          "PATH_INFO" => path || "",
+          "QUERY_STRING" => query || "",
+          "SERVER_NAME" => host,
+          "SERVER_PORT" => port,
+          "SERVER_PROTOCOL" => "HTTP/3",
+          "rack.version" => [1, 3],
+          "rack.url_scheme" => @headers[":scheme"] || "https",
+          "rack.input" => body,
+          "rack.errors" => $stderr,
+          "rack.multithread" => true,
+          "rack.multiprocess" => false,
+          "rack.run_once" => false,
+          "rack.hijack?" => false,
+          "SCRIPT_NAME" => "",
+          "CONTENT_LENGTH" => body.size.to_s,
+        }
+
+        if @headers[":authority"]
+          env["HTTP_HOST"] = @headers[":authority"]
+        end
+
+        @headers.each do |name, value|
+          next if name.start_with?(":")
+          key = name.upcase.tr("-", "_")
+          if key == "CONTENT_TYPE"
+            env["CONTENT_TYPE"] = value
+          elsif key == "CONTENT_LENGTH"
+            env["CONTENT_LENGTH"] = value
+          else
+            env["HTTP_#{key}"] = value
+          end
+        end
+
+        env
+      end
+
+      private
+
+      # Decode QPACK header block and validate per RFC 9114 §4.2 and §4.3.1:
+      # - Header names MUST be lowercase
+      # - Pseudo-headers MUST appear before regular headers
+      # - Duplicate pseudo-headers are malformed
+      # - Unknown pseudo-headers are malformed
+      #
+      # QPACK decoding is delegated to @decoder (injectable).
+      def parse_headers(payload)
+        # Fast path: check validated headers cache (only when no custom limits and default decoder)
+        use_cache = !@max_header_count && @decoder.equal?(DEFAULT_DECODER)
+        if use_cache
+          cached = HEADERS_CACHE[payload]
+          if cached
+            @headers.merge!(cached)
+            return
+          end
+        end
+
+        pseudo_done = false
+
+        @decoder.decode(payload) do |name, value|
+          # RFC 9114 §4.2: Header field names MUST be lowercase
+          if name.match?(/[A-Z]/)
+            raise Protocol::MessageError, "Header name '#{name}' contains uppercase characters"
+          end
+
+          if name.getbyte(0) == 58 # ':'
+            raise Protocol::MessageError, "Pseudo-header '#{name}' after regular header" if pseudo_done
+
+            unless VALID_PSEUDO_SET.key?(name)
+              raise Protocol::MessageError, "Unknown pseudo-header '#{name}'"
+            end
+
+            if @headers.key?(name)
+              raise Protocol::MessageError, "Duplicate pseudo-header '#{name}'"
+            end
+          else
+            pseudo_done = true
+
+            # RFC 9114 §4.2: Connection-specific headers are malformed in HTTP/3
+            # Exception: "te: trailers" is permitted (RFC 9114 §4.2)
+            if FORBIDDEN_SET.key?(name)
+              raise Protocol::MessageError, "Connection-specific header '#{name}' forbidden in HTTP/3" unless name == "te" && value == "trailers"
+            end
+          end
+
+          store_header(name, value)
+        end
+
+        # Cache the validated result
+        if use_cache && HEADERS_CACHE.size < HEADERS_CACHE_MAX && payload.bytesize <= 512
+          key = payload.frozen? ? payload : payload.dup.freeze
+          HEADERS_CACHE[key] = @headers.dup.freeze
+        end
+      end
+    end
+  end
+end

data/lib/quicsilver/protocol/response_encoder.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Protocol
+    class ResponseEncoder
+      # Encode an informational (1xx) response as a single HEADERS frame.
+      # RFC 9114 §4.1: informational responses are encoded as HEADERS with no body.
+      def self.encode_informational(status, headers, encoder: Qpack::Encoder.new)
+        raise ArgumentError, "Informational status must be 1xx, got #{status}" unless (100..199).include?(status)
+
+        pairs = [[":status", status.to_s]]
+        headers.each { |name, value| pairs << [name.to_s.downcase, value.to_s] }
+        encoded = encoder.encode(pairs)
+
+        Protocol.encode_varint(FRAME_HEADERS) +
+          Protocol.encode_varint(encoded.bytesize) +
+          encoded
+      end
+
+      def initialize(status, headers, body, encoder: Qpack::Encoder.new, head_request: false, trailers: nil)
+        @status = status
+        @headers = headers
+        @body = body
+        @encoder = encoder
+        @head_request = head_request
+        @trailers = trailers
+      end
+
+      # Buffered encode - returns all frames at once
+      def encode
+        frames = "".b
+        frames << build_frame(FRAME_HEADERS, @encoder.encode(all_headers))
+        unless @head_request
+          @body.each do |chunk|
+            frames << build_frame(FRAME_DATA, chunk) unless chunk.empty?
+          end
+        end
+        frames << build_frame(FRAME_HEADERS, @encoder.encode(trailer_headers)) if @trailers&.any?
+        @body.close if @body.respond_to?(:close)
+        frames
+      end
+
+      # Streaming encode - yields frames as they're ready
+      def stream_encode
+        yield build_frame(FRAME_HEADERS, @encoder.encode(all_headers)), false
+
+        unless @head_request
+          last_chunk = nil
+          @body.each do |chunk|
+            yield build_frame(FRAME_DATA, last_chunk), false if last_chunk && !last_chunk.empty?
+            last_chunk = chunk
+          end
+
+          if @trailers&.any?
+            yield build_frame(FRAME_DATA, last_chunk), false if last_chunk && !last_chunk.empty?
+            yield build_frame(FRAME_HEADERS, @encoder.encode(trailer_headers)), true
+          elsif last_chunk && !last_chunk.empty?
+            yield build_frame(FRAME_DATA, last_chunk), true
+          else
+            yield "".b, true
+          end
+        else
+          yield "".b, true
+        end
+
+        @body.close if @body.respond_to?(:close)
+      end
+
+      private
+
+      # RFC 9114 §4.2: connection-specific header fields must not appear in HTTP/3
+      FORBIDDEN_HEADERS = %w[transfer-encoding connection keep-alive upgrade te proxy-connection].freeze
+
+      def all_headers
+        headers = [[":status", @status.to_s]]
+        @headers.each do |name, value|
+          downcased = name.to_s.downcase
+          next if downcased.start_with?("rack.")
+          next if FORBIDDEN_HEADERS.include?(downcased)
+          headers << [downcased, value.to_s]
+        end
+        headers
+      end
+
+      def trailer_headers
+        @trailers.map { |name, value| [name.to_s.downcase, value.to_s] }
+      end
+
+      def build_frame(type, payload)
+        payload = payload.to_s.b
+        Protocol.encode_varint(type) + Protocol.encode_varint(payload.bytesize) + payload
+      end
+
+
+    end
+  end
+end

data/lib/quicsilver/protocol/response_parser.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative "frame_parser"
+
+module Quicsilver
+  module Protocol
+    class ResponseParser < FrameParser
+      attr_reader :status
+
+      def initialize(data, **opts)
+        decoder = opts.delete(:decoder) || DEFAULT_DECODER
+        super(decoder: decoder, max_body_size: opts[:max_body_size],
+              max_header_size: opts[:max_header_size])
+        @data = data
+        @use_parse_cache = @decoder.equal?(DEFAULT_DECODER) && !@max_body_size && !@max_header_size
+      end
+
+      # Reset parser with new data for object reuse (avoids allocation overhead)
+      def reset(data)
+        @data = data
+        @status = nil
+        @headers = {}
+        @trailers = {}
+        @frames = nil
+        @body = nil
+        @cached_body_str = nil
+      end
+
+      # Combined reset + parse for maximum throughput (single method call)
+      def reparse(data)
+        @data = data
+        # Fastest path: same data object as last time — skip all cache lookups
+        return if data.equal?(@last_data) && @headers
+
+        if @use_parse_cache
+          oid = data.object_id
+          cached = PARSE_OID_CACHE[oid]
+          unless cached
+            cached = PARSE_CACHE[data]
+            PARSE_OID_CACHE[oid] = cached if cached && PARSE_OID_CACHE.size < PARSE_OID_CACHE_MAX
+          end
+          if cached
+            @status = cached[0]
+            @headers = cached[1]
+            @frames = cached[2]
+            @cached_body_str = cached[3]
+            @trailers = cached[4] || {}
+            @last_data = data
+            return
+          end
+        end
+        @status = nil
+        @headers = {}
+        @trailers = {}
+        @frames = nil
+        @body = nil
+        @cached_body_str = nil
+        parse!
+        cache_result if @use_parse_cache
+      end
+
+      # Class-level parse result cache: data → [status, headers, frames, body_str, trailers]
+      PARSE_CACHE = {}
+      PARSE_CACHE_MAX = 128
+      PARSE_OID_CACHE = {}
+      PARSE_OID_CACHE_MAX = 128
+
+      def parse
+        # Fast path: full parse result cache for default decoder with no limits
+        if @use_parse_cache
+          cached = PARSE_CACHE[@data]
+          if cached
+            @status = cached[0]
+            @headers = cached[1]
+            @frames = cached[2]
+            @cached_body_str = cached[3]
+            @trailers = cached[4] || {}
+            return
+          end
+        end
+
+        parse!
+        cache_result if @use_parse_cache
+      end
+
+      private def cache_result
+        if PARSE_CACHE.size < PARSE_CACHE_MAX && @data.bytesize <= 1024
+          body_str = if @body
+            @body.rewind
+            s = @body.read
+            @body.rewind
+            s
+          end
+          key = @data.frozen? ? @data : @data.dup.freeze
+          PARSE_CACHE[key] = [
+            @status,
+            @headers.dup.freeze,
+            (@frames || []).freeze,
+            body_str&.freeze,
+            (@trailers.empty? ? nil : @trailers.dup.freeze)
+          ].freeze
+        end
+      end
+
+      private
+
+      # Cache for validated response header results
+      HEADERS_CACHE = {}
+      HEADERS_CACHE_MAX = 256
+
+      # Decode QPACK header block via injectable @decoder.
+      # Extracts :status pseudo-header into @status.
+      def parse_headers(payload)
+        use_cache = @decoder.equal?(DEFAULT_DECODER)
+
+        if use_cache
+          cached = HEADERS_CACHE[payload]
+          if cached
+            @status = cached[:status]
+            @headers.merge!(cached[:headers])
+            return
+          end
+        end
+
+        @decoder.decode(payload) do |name, value|
+          if name == ":status"
+            @status = value.to_i
+          else
+            store_header(name, value)
+          end
+        end
+
+        # Cache the result
+        if use_cache && HEADERS_CACHE.size < HEADERS_CACHE_MAX && payload.bytesize <= 512
+          key = payload.frozen? ? payload : payload.dup.freeze
+          HEADERS_CACHE[key] = { status: @status, headers: @headers.dup.freeze }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/quicsilver/protocol/stream_input.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "protocol/http/body/writable"
+
+module Quicsilver
+  module Protocol
+    # A streaming request body backed by Protocol::HTTP::Body::Writable.
+    #
+    # QUIC RECEIVE events push chunks via {write}, while the application
+    # reads them via {read}. This enables concurrent streaming — the app
+    # can start processing before the full body arrives.
+    #
+    # Follows the protocol-http Body::Writable contract:
+    # - write(chunk) — called by the QUIC transport on RECEIVE events
+    # - close_write  — called on RECEIVE_FIN to signal end of body
+    # - read         — called by the application (blocks until data available)
+    # - close        — called to abort (e.g., stream reset)
+    #
+    # Optional features:
+    # - Back-pressure via Thread::SizedQueue (bounded buffer)
+    # - Read timeout for slow client protection
+    #
+    class StreamInput < ::Protocol::HTTP::Body::Writable
+      class ReadTimeout < StandardError; end
+
+      # @param length [Integer, nil] The content-length if known from headers.
+      # @param queue_size [Integer, nil] Maximum buffered chunks for back-pressure.
+      #   nil (default) = unbounded. When bounded, write blocks if queue is full,
+      #   which naturally maps to QUIC flow control.
+      # @param read_timeout [Numeric, nil] Seconds to wait for data before raising
+      #   ReadTimeout. nil (default) = wait forever.
+      def initialize(length = nil, queue_size: nil, read_timeout: nil)
+        queue = if queue_size
+          Thread::SizedQueue.new(queue_size)
+        else
+          Thread::Queue.new
+        end
+
+        super(length, queue: queue)
+        @read_timeout = read_timeout
+        @bytes_written = 0
+      end
+
+      # @attribute [Numeric, nil] Read timeout in seconds.
+      attr_reader :read_timeout
+
+      # Track bytes written for content-length validation.
+      def write(chunk)
+        @bytes_written += chunk.bytesize
+        super
+      end
+
+      # Signal that no more data will be written.
+      # Validates content-length if declared (RFC 9114 §4.1.2) — raises
+      # MessageError if total bytes written don't match.
+      def close_write(error = nil)
+        if @length && @bytes_written != @length
+          raise Protocol::MessageError, "Content-length mismatch: header=#{@length}, body=#{@bytes_written}"
+        end
+        super
+      end
+
+      # Read the next available chunk, with optional timeout.
+      #
+      # @returns [String | Nil] The next chunk, or nil if the body is finished.
+      # @raises [ReadTimeout] If no data arrives within the timeout.
+      # @raises [Exception] If the body was closed due to an error.
+      def read
+        if @read_timeout
+          read_with_timeout
+        else
+          super
+        end
+      end
+
+      private
+
+      def read_with_timeout
+        raise @error if @error
+
+        # Thread::Queue#pop(timeout:) blocks efficiently (no busy-wait).
+        # Returns nil on timeout OR on closed empty queue — disambiguate below.
+        chunk = @queue.pop(timeout: @read_timeout)
+
+        raise @error if @error
+
+        # nil means either timeout or body finished (queue closed + empty).
+        # If queue is closed, the body is done — return nil (EOF).
+        # If queue is still open, we timed out waiting for data.
+        if chunk.nil? && !@queue.closed?
+          raise ReadTimeout, "No data received within #{@read_timeout}s"
+        end
+
+        chunk
+      end
+    end
+  end
+end

data/lib/quicsilver/protocol/stream_output.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+
+module Quicsilver
+  module Protocol
+    # Reads from a Protocol::HTTP::Body::Readable response body and writes
+    # HTTP/3 DATA frames to the transport.
+    #
+    # Transport-agnostic: takes a writer block/callable that handles the actual
+    # sending. Works with msquic, kernel QUIC sockets, or any transport that
+    # can send bytes with a FIN flag.
+    #
+    class StreamOutput
+      # @param body [Protocol::HTTP::Body::Readable] The response body to stream.
+      # @param writer [#call] A callable that accepts (data, fin) — sends bytes
+      #   to the transport. `fin: true` signals end of stream.
+      def initialize(body, &writer)
+        @body = body
+        @writer = writer
+      end
+
+      # Stream all chunks from the response body as HTTP/3 DATA frames.
+      #
+      # Each chunk is wrapped in an HTTP/3 DATA frame (type 0x00) and sent
+      # via the writer. The final chunk is sent with fin=true.
+      #
+      # @param send_fin [Boolean] Whether to send FIN after the last chunk.
+      #   Set to false when trailers will follow.
+      # @return [void]
+      def stream(send_fin: true)
+        last_chunk = nil
+
+        while (chunk = @body.read)
+          if last_chunk
+            @writer.call(build_data_frame(last_chunk), false)
+          end
+          last_chunk = chunk
+        end
+
+        if last_chunk
+          @writer.call(build_data_frame(last_chunk), send_fin)
+        elsif send_fin
+          @writer.call("".b, true)
+        end
+      ensure
+        @body.close if @body.respond_to?(:close)
+      end
+
+      private
+
+      def build_data_frame(payload)
+        payload = payload.b
+        Quicsilver::Protocol.encode_varint(Quicsilver::Protocol::FRAME_DATA) +
+          Quicsilver::Protocol.encode_varint(payload.bytesize) +
+          payload
+      end
+    end
+  end
+end

data/lib/quicsilver/server/listener_data.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  class Server
+    class ListenerData
+      attr_reader :listener_handle, :context_handle
+
+      def initialize(listener_handle, context_handle)
+        @listener_handle = listener_handle  # The MSQUIC listener handle
+        @context_handle = context_handle    # The C context pointer
+      end
+    end
+  end
+end