quicsilver 0.5.0-x86_64-linux

data/lib/quicsilver/protocol/connect_stream_decoder.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "frame_parser"
+
+module Quicsilver
+  module Protocol
+    # Incrementally yields CONNECT DATA payloads without waiting for whole
+    # frames. Unknown frame payloads are skipped as bytes arrive.
+    class ConnectStreamDecoder
+      def initialize
+        @buffer = "".b
+        @frame_type = nil
+        @frame_remaining = nil
+      end
+
+      # A caller may break after a terminal capsule. Unprocessed bytes remain
+      # available to buffered? so it can reject data following that capsule.
+      def each(data)
+        @buffer << data if data
+        until @buffer.empty?
+          break unless @frame_remaining || read_frame_header
+
+          chunk = consume_payload
+          yield chunk if @frame_type == FRAME_DATA
+        end
+      end
+
+      def buffered?
+        !@buffer.empty?
+      end
+
+      def finish!
+        if buffered? || @frame_remaining
+          raise FrameError.new("Truncated HTTP/3 frame", error_code: H3_FRAME_ERROR)
+        end
+      end
+
+      def clear
+        @buffer.clear
+        @frame_remaining = nil
+      end
+
+      private
+
+      def read_frame_header
+        type, type_length = Protocol.decode_varint_str(@buffer, 0)
+        return false if type_length == 0
+        length, length_length = Protocol.decode_varint_str(@buffer, type_length)
+        return false if length_length == 0
+
+        # RFC 9114 §4.4 forbids known non-DATA frames after CONNECT,
+        # including HEADERS trailers; these are connection errors.
+        if CONTROL_ONLY_FRAME_SET.key?(type) ||
+            HTTP2_RESERVED_FRAME_SET.key?(type) ||
+            [FRAME_HEADERS, FRAME_PUSH_PROMISE, FRAME_PRIORITY_UPDATE].include?(type)
+          raise FrameError, "Frame not allowed on CONNECT"
+        end
+
+        @frame_type = type
+        @frame_remaining = length
+        @buffer = @buffer.byteslice(type_length + length_length..) || "".b
+        true
+      end
+
+      def consume_payload
+        count = [@frame_remaining, @buffer.bytesize].min
+        chunk = @buffer.byteslice(0, count)
+        @buffer = @buffer.byteslice(count..) || "".b
+        @frame_remaining -= count
+        @frame_remaining = nil if @frame_remaining.zero?
+        chunk
+      end
+    end
+  end
+end

data/lib/quicsilver/protocol/control_stream_parser.rb

@@ -0,0 +1,117 @@
+# 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
+
+      # Returns the number of bytes consumed. A frame split across receives
+      # leaves its bytes unconsumed, and the caller must keep them buffered:
+      # control streams never send FIN, so a partial frame is normal.
+      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
+
+          if seen.include?(id)
+            raise Protocol::FrameError.new("Duplicate setting identifier 0x#{id.to_s(16)}",
+              error_code: Protocol::H3_SETTINGS_ERROR)
+          end
+          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
+        on_goaway_received(stream_id)
+      end
+
+      private
+
+      # Override in includer to store settings. Default: no-op.
+      def on_settings_received(settings)
+      end
+
+      # Override in includer to react to GOAWAY. Default: no-op.
+      def on_goaway_received(stream_id)
+      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/datagram.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Protocol
+    # HTTP/3 DATAGRAM payload framing (RFC 9297).
+    #
+    # The DATAGRAM frame payload starts with a varint quarter stream ID, followed
+    # by the application payload. The quarter stream ID is the HTTP/3 stream ID
+    # divided by four, matching the client-initiated bidirectional request stream
+    # numbering pattern (0, 4, 8, ...).
+    module Datagram
+      STREAM_ID_DIVISOR = 4
+
+      class << self
+        def encode(stream_id, payload)
+          Protocol.encode_varint(quarter_stream_id(stream_id)) + payload.to_s.b
+        end
+
+        def decode(datagram)
+          quarter_stream_id, prefix_length = Protocol.decode_varint_str(datagram, 0)
+          return if prefix_length == 0
+
+          [stream_id(quarter_stream_id), payload(datagram, prefix_length)]
+        end
+
+        def quarter_stream_id(stream_id)
+          stream_id / STREAM_ID_DIVISOR
+        end
+
+        def stream_id(quarter_stream_id)
+          quarter_stream_id * STREAM_ID_DIVISOR
+        end
+
+        def payload(datagram, prefix_length)
+          datagram.byteslice(prefix_length..-1) || "".b
+        end
+      end
+    end
+  end
+end

data/lib/quicsilver/protocol/frame_parser.rb

@@ -0,0 +1,141 @@
+# 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
+
+      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.new(
+              "Frame payload #{payload.bytesize} exceeds limit #{@max_frame_payload_size}",
+              error_code: Protocol::H3_EXCESSIVE_LOAD
+            )
+          end
+
+          (@frames ||= []) << { type: type, length: payload.bytesize, payload: payload }
+
+          Protocol.reject_unexpected_request_frame!(type)
+
+          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,84 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Protocol
+    # Extracts HTTP/3 frames from a byte buffer.
+    # Yields (type, payload, offset) per frame. Returns total bytes consumed.
+    # Existing callers using |type, payload| are unaffected — offset is ignored.
+    #
+    # Usage:
+    #   FrameReader.each(buffer) do |type, payload|
+    #     case type
+    #     when FRAME_HEADERS then ...
+    #     when FRAME_DATA then ...
+    #     end
+    #   end
+    #
+    # With offset (for early exit via throw/catch):
+    #   strip = FrameReader.skip_while(data) { |type, payload| ... }
+    #   data = data.byteslice(strip..) if strip > 0
+    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)
+          break unless len_byte
+          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, offset
+        end
+
+        offset
+      end
+
+      # Skip leading frames while the block returns true.
+      # Returns the byte offset of the first frame that returned false (or 0).
+      #
+      #   skip = FrameReader.skip_while(data) do |type, payload|
+      #     type == FRAME_HEADERS && informational?(payload)
+      #   end
+      #   data = data.byteslice(skip..) if skip > 0
+      def self.skip_while(buffer)
+        skip_to = 0
+
+        catch(:stop) do
+          each(buffer) do |type, payload, offset|
+            if yield(type, payload)
+              skip_to = offset
+            else
+              throw :stop
+            end
+          end
+        end
+
+        skip_to
+      end
+    end
+  end
+end