quicsilver 0.3.0 → 0.5.0

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

data/lib/quicsilver/protocol/frames.rb

@@ -10,9 +10,53 @@ module Quicsilver
     FRAME_PUSH_PROMISE = 0x05
     FRAME_GOAWAY = 0x07
     FRAME_MAX_PUSH_ID = 0x0d
+    FRAME_PRIORITY_UPDATE = 0xF0700  # RFC 9218 — request stream priority update
+
+    # Settings identifiers
+    SETTINGS_QPACK_MAX_TABLE_CAPACITY = 0x01
+    SETTINGS_QPACK_BLOCKED_STREAMS = 0x07
+    SETTINGS_ENABLE_CONNECT_PROTOCOL = 0x08  # RFC 9220
+    SETTINGS_H3_DATAGRAM = 0x33              # RFC 9297
+    SETTINGS_ENABLE_WEBTRANSPORT = 0x2b603742 # WebTransport draft-06
+    SETTINGS_WT_ENABLED = 0x2c7cf000          # WebTransport over HTTP/3
+    SETTINGS_WT_MAX_SESSIONS = 0x14e9cd29    # Legacy WebTransport session limit
+    SETTINGS_WT_INITIAL_MAX_DATA = 0x2b61
+    SETTINGS_WT_INITIAL_MAX_STREAMS_UNI = 0x2b64
+    SETTINGS_WT_INITIAL_MAX_STREAMS_BIDI = 0x2b65
+
+    # Declaring a non-zero value for any of these is how an endpoint opts into
+    # WebTransport session flow control (draft-16 §5.1). It is a promise to
+    # implement the whole of §5, so do not advertise one until the capsules
+    # and accounting exist.
+    # The session flow control window we advertise. 16 MiB leaves room for
+    # many children above the 1 MiB each queues, and 100 streams per direction
+    # bounds concurrency without being a limit an application trips over.
+    # Both are our choice; the draft only defines the mechanism.
+    WT_INITIAL_MAX_DATA = 16 * 1024 * 1024
+    WT_INITIAL_MAX_STREAMS = 100
+
+    WT_FLOW_CONTROL_SETTINGS = [
+      SETTINGS_WT_INITIAL_MAX_DATA,
+      SETTINGS_WT_INITIAL_MAX_STREAMS_UNI,
+      SETTINGS_WT_INITIAL_MAX_STREAMS_BIDI
+    ].freeze
+    SETTINGS_MAX_FIELD_SECTION_SIZE = 0x06   # RFC 9114 §7.2.4.1
 
     # Frame types forbidden on request streams (RFC 9114 Section 7.2.4, 7.2.6, 7.2.7)
     CONTROL_ONLY_FRAMES = [FRAME_CANCEL_PUSH, FRAME_SETTINGS, FRAME_GOAWAY, FRAME_MAX_PUSH_ID].freeze
+    CONTROL_ONLY_FRAME_SET = CONTROL_ONLY_FRAMES.to_h { |type| [type, true] }.freeze
+
+    # HTTP/2 frame types, reserved in HTTP/3 so that an HTTP/2 frame arriving
+    # here is rejected rather than mistaken for an extension (RFC 9114 7.2.8)
+    HTTP2_RESERVED_FRAME_SET = {0x02 => true, 0x06 => true, 0x08 => true, 0x09 => true}.freeze
+
+    # WT_STREAM is registered as a frame type to reserve the code point, but it
+    # carries no length and is only legal as the very first bytes of a request
+    # stream, where the server classifies it before any frame parsing. Anywhere
+    # else it is a connection error (draft-ietf-webtrans-http3-16 §4.3).
+    FRAME_WT_STREAM = 0x41
+    # HTTP/3 Datagram Error Code (RFC 9297 Section 5.2)
+    H3_DATAGRAM_ERROR = 0x33
 
     # HTTP/3 Error Codes (RFC 9114 Section 8.1)
     H3_NO_ERROR = 0x100
@@ -41,15 +85,20 @@ module Quicsilver
     # Protocol errors that carry an HTTP/3 error code for CONNECTION_CLOSE / RESET_STREAM.
     # FrameError → connection error (CONNECTION_CLOSE)
     # MessageError → stream error (RESET_STREAM) on request streams
-    class FrameError < StandardError
+    class FrameError < Quicsilver::Error
       attr_reader :error_code
+      # The default suits a frame that is valid but arrived somewhere it is not
+      # allowed (RFC 9114 4.1, 7.2.4), which is the common case. Anything else
+      # must pass its own code: callers that leave this implicit are asserting
+      # H3_FRAME_UNEXPECTED is correct, and the handler turns that into a
+      # connection error.
       def initialize(msg = nil, error_code: H3_FRAME_UNEXPECTED)
         @error_code = error_code
         super(msg)
       end
     end
 
-    class MessageError < StandardError
+    class MessageError < Quicsilver::Error
       attr_reader :error_code
       def initialize(msg = nil, error_code: H3_MESSAGE_ERROR)
         @error_code = error_code
@@ -184,6 +233,27 @@ module Quicsilver
     MAX_STREAM_ID = (2**62) - 4
 
     class << self
+      # Frame types a request stream may carry. Unknown types are extensions and
+      # must be ignored (RFC 9114 9), so only the two reserved sets raise.
+      # Both the buffered parser and the streaming body reader validate here.
+      def reject_unexpected_request_frame!(type)
+        if CONTROL_ONLY_FRAME_SET.key?(type)
+          raise FrameError, "Frame type 0x#{type.to_s(16)} not allowed on request streams"
+        end
+
+        if HTTP2_RESERVED_FRAME_SET.key?(type)
+          raise FrameError.new("Reserved HTTP/2 frame type 0x#{type.to_s(16)} not allowed in HTTP/3",
+            error_code: H3_FRAME_UNEXPECTED)
+        end
+
+        # Reaching here means the stream already parsed as HTTP/3, so this
+        # WT_STREAM is not at the front of the stream (draft-16 §4.3).
+        if type == FRAME_WT_STREAM
+          raise FrameError.new("WT_STREAM is only allowed as the first bytes of a request stream",
+            error_code: H3_FRAME_ERROR)
+        end
+      end
+
       # Precomputed varint encodings for single-byte values (0-63)
       VARINT_SMALL = Array.new(64) { |v| [v].pack('C').freeze }.freeze
       VARINT_MED = Array.new(16384 - 64) { |i| v = i + 64; [0x40 | (v >> 8), v & 0xFF].pack('C*').freeze }.freeze
@@ -230,19 +300,76 @@ module Quicsilver
         frame_type + frame_length + payload
       end
 
-      # Build control stream data
-      def build_control_stream
-        stream_type = [0x00].pack('C')  # Control stream type
-        settings = build_settings_frame({
-          0x01 => 0,  # QPACK_MAX_TABLE_CAPACITY = 0 (no dynamic table)
-          0x07 => 0   # QPACK_BLOCKED_STREAMS = 0
-        })
+      # Generate a random GREASE ID (RFC 9114 §7.2.4.1): 0x1f * N + 0x21
+      def grease_id
+        31 * rand(0..20) + 33
+      end
+
+      # Has this endpoint declared intent to use session flow control? Both
+      # endpoints must, for it to be enabled.
+      def wt_flow_control_opt_in?(settings)
+        WT_FLOW_CONTROL_SETTINGS.any? { |id| settings[id].to_i > 0 }
+      end
+
+      # The SETTINGS we advertise. Kept separate from the frame so a connection
+      # can ask what it promised the peer without re-parsing the wire.
+      #
+      # @param max_field_section_size [Integer, nil] Advertise SETTINGS_MAX_FIELD_SECTION_SIZE (0x06)
+      #   to the peer (RFC 9114 §4.2.2 / §7.2.4.1). nil = don't advertise.
+      def control_stream_settings(max_field_section_size: nil, datagram_receive_enabled: true)
+        settings = {
+          SETTINGS_QPACK_MAX_TABLE_CAPACITY => 0,
+          SETTINGS_QPACK_BLOCKED_STREAMS => 0,
+          SETTINGS_ENABLE_CONNECT_PROTOCOL => 1,
+          SETTINGS_H3_DATAGRAM => datagram_receive_enabled ? 1 : 0,
+          SETTINGS_ENABLE_WEBTRANSPORT => 1,
+          SETTINGS_WT_ENABLED => 1,
+          # Declaring these enables session flow control when the peer also
+          # does (§5.1): the initial limits a session grants its peer, raised
+          # by capsules as we consume data and close streams.
+          #
+          # The data window sits well above the 1 MiB a single child stream
+          # queues, so one stream cannot exhaust a session's credit, in the
+          # same spirit as QUIC keeping its connection window above any one
+          # stream's. Both values are ours to choose; the draft defines only
+          # the mechanism.
+          SETTINGS_WT_INITIAL_MAX_DATA => WT_INITIAL_MAX_DATA,
+          SETTINGS_WT_INITIAL_MAX_STREAMS_BIDI => WT_INITIAL_MAX_STREAMS,
+          SETTINGS_WT_INITIAL_MAX_STREAMS_UNI => WT_INITIAL_MAX_STREAMS,
+          # Still one session per connection. Flow control now permits more
+          # (§5.1), but sharing a connection between sessions is a separate
+          # change.
+          SETTINGS_WT_MAX_SESSIONS => 1
+        }
+        settings[SETTINGS_MAX_FIELD_SECTION_SIZE] = max_field_section_size if max_field_section_size
+        settings
+      end
 
-        stream_type + settings
+      # Build control stream data.
+      def build_control_stream(max_field_section_size: nil, datagram_receive_enabled: true)
+        stream_type = [0x00].pack("C")  # Control stream type
+        settings_hash = control_stream_settings(
+          max_field_section_size: max_field_section_size,
+          datagram_receive_enabled: datagram_receive_enabled
+        )
+        settings_hash[grease_id] = grease_id  # GREASE setting (RFC 9114 §7.2.4.1)
+
+        stream_type + build_settings_frame(settings_hash)
       end
 
       # Build GOAWAY frame (RFC 9114 Section 7.2.6)
       # stream_id: The last client-initiated bidirectional stream ID the server will process
+      # Build an HTTP/3 frame: varint type + varint length + payload.
+      def build_frame(type, payload)
+        payload = payload.to_s.b
+        encode_varint(type) + encode_varint(payload.bytesize) + payload
+      end
+
+      # Build a HEADERS frame from key-value pairs via QPACK.
+      def build_headers_frame(pairs, encoder: Qpack::Encoder.new)
+        build_frame(FRAME_HEADERS, encoder.encode(pairs))
+      end
+
       def build_goaway_frame(stream_id)
         frame_type = encode_varint(FRAME_GOAWAY)
         payload = encode_varint(stream_id)