quicsilver 0.2.0 → 0.4.0

data/lib/quicsilver/protocol/adapter.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "protocol/http/request"
+require "protocol/http/response"
+require "protocol/http/headers"
+require_relative "stream_input"
+require_relative "stream_output"
+
+module Quicsilver
+  module Protocol
+    # Converts between QUIC/HTTP/3 frames and protocol-http Request/Response
+    # objects. This enables integration with Falcon and any other server
+    # built on protocol-http.
+    #
+    # Usage:
+    #   adapter = Protocol::Adapter.new(app)
+    #   request, body = adapter.build_request(parsed_headers)
+    #   body.write(chunk)               # feed body data
+    #   body.close_write                # signal end of body
+    #   response = adapter.call(request)
+    #   adapter.send_response(response, writer)
+    #
+    class Adapter
+      VERSION = "HTTP/3"
+
+      def initialize(app)
+        @app = app
+        @qpack_encoder = Quicsilver::Protocol::Qpack::Encoder.new
+      end
+
+      # Build a Protocol::HTTP::Request from parsed HTTP/3 headers.
+      #
+      # Returns [request, body] where body is a Protocol::StreamInput that
+      # the transport feeds RECEIVE chunks into.
+      #
+      # @param headers [Hash] Parsed headers from RequestParser (includes pseudo-headers).
+      # @return [Array(Protocol::HTTP::Request, Protocol::StreamInput)] request and body.
+      #   Body is nil for bodyless methods (GET, HEAD, TRACE).
+      #   Caller feeds RECEIVE data into body via write(), then close_write on FIN.
+      def build_request(headers)
+        method = headers[":method"]
+        scheme = headers[":scheme"] || "https"
+        authority = headers[":authority"]
+        path = headers[":path"]
+        protocol = headers[":protocol"]
+        content_length = headers["content-length"]&.to_i
+
+        protocol_headers = ::Protocol::HTTP::Headers.new
+        headers.each do |name, value|
+          next if name.start_with?(":")
+          protocol_headers.add(name, value)
+        end
+
+        body = unless bodyless_request?(method)
+          Protocol::StreamInput.new(content_length)
+        end
+
+        request = ::Protocol::HTTP::Request.new(
+          scheme, authority, method, path, VERSION,
+          protocol_headers, body, protocol
+        )
+
+        [request, body]
+      end
+
+      # Send a Protocol::HTTP::Response via a transport writer.
+      #
+      # Encodes the response headers as an HTTP/3 HEADERS frame, then streams
+      # the response body as DATA frames via Protocol::StreamOutput.
+      #
+      # @param response [Protocol::HTTP::Response] The response to send.
+      # @param writer [#call] Transport writer — accepts (data, fin) for sending bytes.
+      # @param head_request [Boolean] Whether this was a HEAD request.
+      # @return [void]
+      def send_response(response, writer, head_request: false)
+        status = response.status
+        headers = response.headers
+        trailers = extract_trailers(headers)
+        headers_hash = response_headers_hash(headers)
+        body = response.body
+
+        if body.nil? || head_request
+          send_headers_only(status, headers_hash, writer, trailers: trailers)
+        elsif body.respond_to?(:read)
+          stream_response(status, headers_hash, body, writer, trailers: trailers)
+        else
+          buffer_response(status, headers_hash, body, writer, trailers: trailers)
+        end
+      end
+
+      # Call the protocol-http application with the request.
+      #
+      # @param request [Protocol::HTTP::Request]
+      # @return [Protocol::HTTP::Response]
+      def call(request)
+        @app.call(request)
+      end
+
+      private
+
+      # Methods where a body has no defined semantics (RFC 9110 §9.3.1, §9.3.2, §9.3.8).
+      # GET and HEAD SHOULD NOT have a body. TRACE MUST NOT.
+      # DELETE, OPTIONS, CONNECT can all have meaningful bodies.
+      BODYLESS_METHODS = %w[GET HEAD TRACE].freeze
+
+      def bodyless_request?(method)
+        BODYLESS_METHODS.include?(method)
+      end
+
+      # No body — send HEADERS with FIN
+      def send_headers_only(status, headers, writer, trailers: nil)
+        encoder = Quicsilver::Protocol::ResponseEncoder.new(status, headers, [], trailers: trailers)
+        writer.call(encoder.encode, true)
+      end
+
+      # Streaming body (protocol-http Body::Readable) — send HEADERS, then
+      # stream DATA frames as chunks arrive. Used by Falcon mode.
+      def stream_response(status, headers, body, writer, trailers: nil)
+        has_trailers = trailers&.any?
+        writer.call(build_headers_frame(status, headers), false)
+        Protocol::StreamOutput.new(body, &writer).stream(send_fin: !has_trailers)
+        writer.call(build_trailer_frame(trailers), true) if has_trailers
+      end
+
+      # Buffered body (Rack array or enumerable) — encode everything and send.
+      def buffer_response(status, headers, body, writer, trailers: nil)
+        parts = body.respond_to?(:each) ? body : [body.to_s]
+        encoder = Quicsilver::Protocol::ResponseEncoder.new(status, headers, parts, trailers: trailers)
+        writer.call(encoder.encode, true)
+      ensure
+        body.close if body.respond_to?(:close)
+      end
+
+      # Extract trailers from Protocol::HTTP::Headers if present.
+      # Returns a Hash or nil.
+      def extract_trailers(headers)
+        return nil unless headers.respond_to?(:trailer?) && headers.trailer?
+
+        result = {}
+        headers.trailer.each do |name, value|
+          result[name] = value
+        end
+        result
+      end
+
+      # Convert Protocol::HTTP::Headers to a plain Hash for ResponseEncoder.
+      # Only includes headers, not trailers.
+      def response_headers_hash(headers)
+        return {} unless headers
+
+        headers.header.to_h
+      end
+
+      # Build an HTTP/3 HEADERS frame from key-value pairs
+      def build_qpack_frame(pairs)
+        encoded = @qpack_encoder.encode(pairs)
+        Quicsilver::Protocol.encode_varint(Quicsilver::Protocol::FRAME_HEADERS) +
+          Quicsilver::Protocol.encode_varint(encoded.bytesize) +
+          encoded
+      end
+
+      # Build a response HEADERS frame (with :status pseudo-header)
+      def build_headers_frame(status, headers)
+        pairs = [[":status", status.to_s]]
+        headers.each { |name, value| pairs << [name.to_s.downcase, value.to_s] }
+        build_qpack_frame(pairs)
+      end
+
+      # Build a trailer HEADERS frame
+      def build_trailer_frame(trailers)
+        pairs = trailers.map { |name, value| [name.to_s.downcase, value.to_s] }
+        build_qpack_frame(pairs)
+      end
+    end
+  end
+end

data/lib/quicsilver/protocol/control_stream_parser.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Protocol
+    # Shared control stream parsing for both server Connection and Client.
+    #
+    # RFC 9114 §7.2.4: Both endpoints MUST send and process SETTINGS.
+    # RFC 9114 §7.2.6: Both endpoints MUST validate incoming GOAWAY.
+    #
+    # Includer must provide:
+    #   @settings_received — boolean, initially false
+    #   @peer_goaway_id   — nil initially
+    #
+    # Includer may override:
+    #   on_settings_received(settings_hash) — called after SETTINGS parsed
+    #   on_goaway_received(stream_id)       — called after GOAWAY parsed
+    #   handle_control_frame(type, payload) — called for non-SETTINGS/GOAWAY frames
+    module ControlStreamParser
+      # RFC 9114 §7.2.4.1 / §11.2.2: HTTP/2 setting identifiers forbidden in HTTP/3
+      # 0x00 = SETTINGS_HEADER_TABLE_SIZE (reserved), 0x02-0x05 = various HTTP/2 settings
+      # Note: 0x08 (SETTINGS_ENABLE_CONNECT_PROTOCOL) is valid in HTTP/3 per RFC 9220
+      HTTP2_SETTINGS = [0x00, 0x02, 0x03, 0x04, 0x05].freeze
+
+      def parse_control_frames(data)
+        first_frame = !@settings_received
+
+        Protocol::FrameReader.each(data) do |type, payload|
+          if first_frame && type != Protocol::FRAME_SETTINGS
+            raise Protocol::FrameError.new("First frame on control stream must be SETTINGS",
+              error_code: Protocol::H3_MISSING_SETTINGS)
+          end
+          first_frame = false
+
+          case type
+          when Protocol::FRAME_SETTINGS
+            raise Protocol::FrameError, "Duplicate SETTINGS frame on control stream" if @settings_received
+            parse_peer_settings(payload)
+            @settings_received = true
+          when Protocol::FRAME_GOAWAY
+            parse_peer_goaway(payload)
+          else
+            handle_control_frame(type, payload)
+          end
+        end
+      end
+
+      def parse_peer_settings(payload)
+        offset = 0
+        seen = Set.new
+        settings = {}
+
+        while offset < payload.bytesize
+          id, id_len = Protocol.decode_varint(payload.bytes, offset)
+          value, value_len = Protocol.decode_varint(payload.bytes, offset + id_len)
+          break if id_len == 0 || value_len == 0
+
+          if HTTP2_SETTINGS.include?(id)
+            raise Protocol::FrameError.new("HTTP/2 setting identifier 0x#{id.to_s(16)} not allowed in HTTP/3",
+              error_code: Protocol::H3_SETTINGS_ERROR)
+          end
+
+          raise Protocol::FrameError, "Duplicate setting identifier 0x#{id.to_s(16)}" if seen.include?(id)
+          seen.add(id)
+
+          settings[id] = value
+          offset += id_len + value_len
+        end
+
+        on_settings_received(settings)
+      end
+
+      # RFC 9114 §7.2.6: Validate incoming GOAWAY frame.
+      # Stream ID must be a client-initiated bidirectional stream ID (divisible by 4)
+      # and must not increase from a previous GOAWAY.
+      def parse_peer_goaway(payload)
+        stream_id, _ = Protocol.decode_varint(payload.bytes, 0)
+
+        unless stream_id % 4 == 0
+          raise Protocol::FrameError.new(
+            "GOAWAY stream ID #{stream_id} is not a client-initiated bidirectional stream ID",
+            error_code: Protocol::H3_ID_ERROR)
+        end
+
+        if @peer_goaway_id && stream_id > @peer_goaway_id
+          raise Protocol::FrameError.new(
+            "GOAWAY stream ID #{stream_id} exceeds previous #{@peer_goaway_id}",
+            error_code: Protocol::H3_ID_ERROR)
+        end
+
+        @peer_goaway_id = stream_id
+      end
+
+      private
+
+      # Override in includer to store settings. Default: no-op.
+      def on_settings_received(settings)
+      end
+
+      # Override in includer to handle additional frame types on the control stream.
+      # Server handles FORBIDDEN_ON_CONTROL and PRIORITY_UPDATE here.
+      # Client ignores unknown frames.
+      def handle_control_frame(type, payload)
+      end
+    end
+  end
+end

data/lib/quicsilver/protocol/frame_parser.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "stringio"
+require_relative "frame_reader"
+require_relative "qpack/header_block_decoder"
+
+module Quicsilver
+  module Protocol
+    # Base class for HTTP/3 request and response frame parsing.
+    #
+    # Handles the shared frame walking loop, HEADERS→DATA→HEADERS ordering,
+    # trailer parsing, body accumulation, and size limit enforcement.
+    #
+    # Subclasses implement:
+    #   - parse_headers(payload) — decode the first HEADERS frame
+    class FrameParser
+      # Frame types forbidden on request streams — use hash for O(1) lookup
+      # Static-only QPACK decoder (no dynamic table). Used by default.
+      # Inject a custom decoder via decoder: kwarg for dynamic QPACK support.
+      DEFAULT_DECODER = Qpack::HeaderBlockDecoder.default
+
+      CONTROL_ONLY_SET = Protocol::CONTROL_ONLY_FRAMES.each_with_object({}) { |f, h| h[f] = true }.freeze
+
+      EMPTY_BODY = StringIO.new("".b).tap { |io| io.set_encoding(Encoding::ASCII_8BIT) }
+
+      attr_reader :headers, :trailers, :bytes_consumed
+
+      def frames
+        @frames || []
+      end
+
+      def initialize(decoder:, max_body_size: nil, max_header_size: nil, max_header_count: nil, max_frame_payload_size: nil)
+        @decoder = decoder
+        @max_body_size = max_body_size
+        @max_header_size = max_header_size
+        @max_header_count = max_header_count
+        @max_frame_payload_size = max_frame_payload_size
+        @headers = {}
+        @trailers = {}
+      end
+
+      def body
+        if @body
+          @body.rewind
+          @body
+        elsif @cached_body_str
+          @body = StringIO.new(@cached_body_str)
+          @body.set_encoding(Encoding::ASCII_8BIT)
+          @body
+        else
+          EMPTY_BODY
+        end
+      end
+
+      private
+
+      def parse!
+        walk_frames(@data)
+      end
+
+      def walk_frames(buffer)
+        @headers = {}
+        @trailers = {}
+        @body = nil
+        @frames = nil
+        @bytes_consumed = 0
+        headers_received = false
+        trailers_received = false
+
+        @bytes_consumed = FrameReader.each(buffer) do |type, payload|
+          if @max_frame_payload_size && payload.bytesize > @max_frame_payload_size
+            raise Protocol::FrameError, "Frame payload #{payload.bytesize} exceeds limit #{@max_frame_payload_size}"
+          end
+
+          (@frames ||= []) << { type: type, length: payload.bytesize, payload: payload }
+
+          if CONTROL_ONLY_SET.key?(type)
+            raise Protocol::FrameError, "Frame type 0x#{type.to_s(16)} not allowed on request streams"
+          end
+
+          case type
+          when 0x01 # HEADERS
+            if @max_header_size && payload.bytesize > @max_header_size
+              raise Protocol::MessageError, "Header block #{payload.bytesize} exceeds limit #{@max_header_size}"
+            end
+            if trailers_received
+              raise Protocol::FrameError, "HEADERS frame after trailers"
+            elsif headers_received
+              parse_trailers(payload)
+              trailers_received = true
+            else
+              parse_headers(payload)
+              headers_received = true
+            end
+          when 0x00 # DATA
+            raise Protocol::FrameError, "DATA frame before HEADERS" unless headers_received
+            raise Protocol::FrameError, "DATA frame after trailers" if trailers_received
+            unless @body
+              @body = StringIO.new
+              @body.set_encoding(Encoding::ASCII_8BIT)
+            end
+            @body.write(payload)
+            if @max_body_size && @body.size > @max_body_size
+              raise Protocol::MessageError, "Body size #{@body.size} exceeds limit #{@max_body_size}"
+            end
+          end
+        end
+
+        @body&.rewind
+      end
+
+      # RFC 9110 §5.3: Combine duplicate header values.
+      # - set-cookie: join with "\n" (Rack convention, MUST NOT combine with comma)
+      # - cookie: join with "; " (RFC 9114 §4.2.1)
+      # - all others: join with ", "
+      def store_header(name, value)
+        if @headers.key?(name)
+          separator = case name
+            when "set-cookie" then "\n"
+            when "cookie" then "; "
+            else ", "
+          end
+          @headers[name] = "#{@headers[name]}#{separator}#{value}"
+        else
+          if @max_header_count && @headers.size >= @max_header_count
+            raise Protocol::MessageError, "Header count exceeds limit #{@max_header_count}"
+          end
+          @headers[name] = value
+        end
+      end
+
+      def parse_trailers(payload)
+        @decoder.decode(payload) do |name, value|
+          if name.start_with?(":")
+            raise Protocol::MessageError, "Pseudo-header '#{name}' in trailers"
+          end
+          @trailers[name] = value
+        end
+      end
+    end
+  end
+end

data/lib/quicsilver/protocol/frame_reader.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Protocol
+    # Extracts HTTP/3 frames from a byte buffer.
+    # Yields [type, payload] pairs. No protocol semantics — just byte-level extraction.
+    #
+    # Usage:
+    #   FrameReader.each(buffer) do |type, payload|
+    #     case type
+    #     when FRAME_HEADERS then ...
+    #     when FRAME_DATA then ...
+    #     end
+    #   end
+    module FrameReader
+      def self.each(buffer)
+        offset = 0
+        buf_size = buffer.bytesize
+
+        while offset < buf_size
+          break if buf_size - offset < 2
+
+          # Inline single-byte varint fast path (covers frame types 0x00-0x3F)
+          type_byte = buffer.getbyte(offset)
+          if type_byte < 0x40
+            type = type_byte
+            type_len = 1
+          else
+            type, type_len = Protocol.decode_varint_str(buffer, offset)
+            break if type_len == 0
+          end
+
+          len_byte = buffer.getbyte(offset + type_len)
+          if len_byte < 0x40
+            length = len_byte
+            length_len = 1
+          else
+            length, length_len = Protocol.decode_varint_str(buffer, offset + type_len)
+            break if length_len == 0
+          end
+
+          header_len = type_len + length_len
+          break if buf_size < offset + header_len + length
+
+          payload = buffer.byteslice(offset + header_len, length)
+          offset += header_len + length
+
+          yield type, payload
+        end
+
+        offset
+      end
+    end
+  end
+end