quicsilver 0.3.0 → 0.5.0

data/lib/quicsilver/transport/connection.rb

@@ -3,13 +3,66 @@
 module Quicsilver
   module Transport
     class Connection
+      include Protocol::ControlStreamParser
+
+      # MsQuic QUIC_STATUS_INVALID_STATE (POSIX errno ETOOMANYREFS = 0x59).
+      # Stream already shut down by peer — raised by StreamSend when the
+      # client has reset or closed the stream.
+      MSQUIC_INVALID_STATE = "0x59"
+      # The peer tore the stream down before we finished responding.
+      STREAM_CLOSED = "QUIC stream is closed"
+
       attr_reader :handle, :data, :streams
       attr_reader :control_stream_id, :qpack_encoder_stream_id, :qpack_decoder_stream_id
       attr_reader :server_control_stream
+      attr_reader :peer_goaway_id, :local_goaway_id
+      attr_reader :stream_priorities
+      attr_reader :remote_address, :remote_port, :session_resumed
+
+      def settings_received?
+        @settings_received
+      end
+
+      def datagram_send_enabled?
+        Quicsilver.connection_datagram_send_enabled?(@handle)
+      end
+
+      def reliable_reset_enabled?
+        Quicsilver.connection_reliable_reset_enabled?(@handle)
+      end
 
-      def initialize(handle, data)
+      # WebTransport session flow control is on only when both endpoints have
+      # declared intent by advertising a non-zero WT_INITIAL_MAX_* setting
+      # (draft-16 §5.1). Until it is, at most one session may share the
+      # connection and flow control capsules must be ignored, because the peer
+      # may have sent them before seeing our SETTINGS.
+      def wt_flow_control_enabled?
+        return false unless settings_received?
+
+        Protocol.wt_flow_control_opt_in?(local_settings) &&
+          Protocol.wt_flow_control_opt_in?(@settings)
+      end
+
+      # What we advertise to the peer. Derived rather than captured when the
+      # control stream opens, so there is one source for the promise we make.
+      def local_settings
+        Protocol.control_stream_settings(max_field_section_size: @max_header_size)
+      end
+
+      def webtransport_settings_valid?(protocol)
+        return false unless settings_received? && @settings[Protocol::SETTINGS_H3_DATAGRAM] == 1
+
+        # Compatibility path: the legacy token does not require the newer flag.
+        protocol == Protocol::WebTransport::PROTOCOL_LEGACY ||
+          (@settings[Protocol::SETTINGS_WT_ENABLED] == 1 && reliable_reset_enabled?)
+      end
+
+      def initialize(handle, data, max_header_size: nil, connection_id: nil, transport_server_id: nil)
         @handle = handle
         @data = data
+        @max_header_size = max_header_size
+        @connection_id = hex_string(connection_id)
+        @transport_server_id = transport_server_id
         @streams = {}
         @response_buffers = {}
         @mutex = Mutex.new
@@ -24,6 +77,58 @@ module Quicsilver
 
         @settings = {}
         @settings_received = false
+        @peer_goaway_id = nil
+        @local_goaway_id = nil
+        @stream_priorities = {}
+        @session_resumed = @data[2] == true
+        @remote_address = nil
+        @remote_port = 0
+      end
+
+      # Resolve peer address from MsQuic. Must be called before the connection closes.
+      def resolve_remote_address!
+        result = Quicsilver.connection_remote_address(@handle)
+        @remote_address = result&.first
+        @remote_port = result&.last&.to_i || 0
+      end
+
+      # Stable opaque connection identifier exposed to apps. The current MsQuic
+      # backing value is the original destination CID; consumers must not parse
+      # it as the server-generated routing CID.
+      attr_reader :connection_id
+
+      def active_streams
+        @streams.size
+      end
+
+      # HTTP/3 request streams are client-initiated bidirectional QUIC streams.
+      def active_request_streams
+        @streams.keys.count { |stream_id| StreamId.request?(stream_id) }
+      end
+
+      def request_context(stream_id: nil)
+        connection = connection_metadata
+        if stream_id
+          connection["stream_id"] = stream_id
+          connection["request_id"] = request_id_for(stream_id)
+        end
+
+        {
+          "connection" => connection
+        }
+      end
+
+      def to_h
+        connection_metadata.merge(
+          "remote_address" => @remote_address,
+          "remote_port" => @remote_port,
+          "session_resumed" => @session_resumed,
+          "streams" => {
+            "active" => active_streams,
+            "active_requests" => active_request_streams
+          },
+          "transport" => stats.to_h
+        )
       end
 
       # === Setup (called after connection established) ===
@@ -31,13 +136,17 @@ module Quicsilver
       def setup_http3_streams
         # Control stream (required)
         @server_control_stream = open_stream(unidirectional: true)
-        @server_control_stream.send(Protocol.build_control_stream)
+        @server_control_stream.send(Protocol.build_control_stream(max_field_section_size: @max_header_size))
 
         # QPACK encoder/decoder streams
         [0x02, 0x03].each do |type|
           stream = open_stream(unidirectional: true)
           stream.send([type].pack("C"))
         end
+
+        # GREASE unidirectional stream (RFC 9114 §6.2)
+        stream = open_stream(unidirectional: true)
+        stream.send(Protocol.encode_varint(Protocol.grease_id) + "GREASE".b)
       end
 
       # === Stream Management ===
@@ -62,14 +171,14 @@ module Quicsilver
 
       def buffer_data(stream_id, data)
         @mutex.synchronize do
-          (@response_buffers[stream_id] ||= StringIO.new("".b)).write(data)
+          (@response_buffers[stream_id] ||= "".b) << data
         end
       end
 
       def complete_stream(stream_id, final_data)
         @mutex.synchronize do
           buffer = @response_buffers.delete(stream_id)
-          (buffer&.string || "".b) + (final_data || "".b)
+          (buffer || "".b) + (final_data || "".b)
         end
       end
 
@@ -78,36 +187,60 @@ module Quicsilver
       def send_goaway(stream_id = nil)
         return unless @server_control_stream
 
-        stream_id ||= last_client_stream_id
+        stream_id ||= last_request_stream_id
+        validate_goaway_id!(stream_id)
+
         @server_control_stream.send(Protocol.build_goaway_frame(stream_id))
+        @local_goaway_id = stream_id
+      rescue ArgumentError
+        raise  # Re-raise validation errors
       rescue => e
         Quicsilver.logger.error("Failed to send GOAWAY: #{e.message}")
       end
 
-      def send_response(stream, status, headers, body, head_request: false)
-        encoder = Protocol::ResponseEncoder.new(status, headers, body, head_request: head_request)
+      # RFC 9114 §5.2: GOAWAY IDs MUST NOT increase from a previous value.
+      def validate_goaway_id!(stream_id)
+        if @local_goaway_id && stream_id > @local_goaway_id
+          raise ArgumentError, "GOAWAY stream ID #{stream_id} exceeds previous #{@local_goaway_id}"
+        end
+      end
+
+      # Send an informational (1xx) response before the final response.
+      # RFC 9114 §4.1: encoded as a HEADERS frame, no FIN.
+      def send_informational(stream, status, headers)
+        data = Protocol::ResponseEncoder.encode_informational(status, headers)
+        stream.send(data, fin: false)
+      rescue RuntimeError, IOError => e
+        raise unless stream_send_error?(e)
+      end
+
+      def send_response(stream, status, headers, body, head_request: false, trailers: nil)
+        body = [] if body.nil?
+        encoder = Protocol::ResponseEncoder.new(status, headers, body, head_request: head_request, trailers: trailers)
 
         if body.respond_to?(:to_ary)
-          Quicsilver.send_stream(stream.stream_handle, encoder.encode, true)
+          stream.send(encoder.encode, fin: true)
         else
           encoder.stream_encode do |frame_data, fin|
-            Quicsilver.send_stream(stream.stream_handle, frame_data, fin) unless frame_data.empty? && !fin
+            stream.send(frame_data, fin: fin) unless frame_data.empty? && !fin
           end
         end
-      rescue RuntimeError => e
-        # Stream may have been reset by client - this is expected
-        raise unless e.message.include?("0x59") || e.message.include?("StreamSend failed")
-        Quicsilver.logger.debug("Stream send failed (client likely reset): #{e.message}")
+      rescue RuntimeError, IOError => e
+        raise unless stream_send_error?(e)
+      ensure
+        # RFC 9110: Always close the body to release resources (file handles, fibers, etc.)
+        body.close if body.respond_to?(:close)
       end
 
       def send_error(stream, status, message)
         body = ["#{status} #{message}"]
-        encoder = Protocol::ResponseEncoder.new(status, { "content-type" => "text/plain" }, body)
-        Quicsilver.send_stream(stream.stream_handle, encoder.encode, true)
-      rescue RuntimeError => e
-        # Stream may have been reset by client - this is expected
-        raise unless e.message.include?("0x59") || e.message.include?("StreamSend failed")
-        Quicsilver.logger.debug("Stream send failed (client likely reset): #{e.message}")
+        headers = { "content-type" => "text/plain" }
+        # RFC 9110 §15.6.4: 503 responses SHOULD include Retry-After
+        headers["retry-after"] = "1" if status == 503
+        encoder = Protocol::ResponseEncoder.new(status, headers, body)
+        stream.send(encoder.encode, fin: true)
+      rescue RuntimeError, IOError => e
+        raise unless stream_send_error?(e)
       end
 
       # === Control Stream Handling ===
@@ -116,61 +249,22 @@ module Quicsilver
       # Called on each RECEIVE event — control streams never send FIN.
       def receive_unidirectional_data(stream_id, data)
         @mutex.synchronize do
-          (@response_buffers[stream_id] ||= StringIO.new("".b)).write(data)
+          (@response_buffers[stream_id] ||= "".b) << data
         end
 
-        buf = @mutex.synchronize { @response_buffers[stream_id]&.string || "".b }
+        buf = @mutex.synchronize { @response_buffers[stream_id] || "".b }
         return if buf.empty?
 
-        # First time seeing this stream: identify stream type
         unless @uni_stream_types&.key?(stream_id)
           @uni_stream_types ||= {}
-          stream_type, type_len = Protocol.decode_varint(buf.bytes, 0)
-          return if type_len == 0  # need more data
-
-          case stream_type
-          when 0x00 # Control stream
-            raise Protocol::FrameError, "Duplicate control stream" if @control_stream_id
-            @control_stream_id = stream_id
-            @uni_stream_types[stream_id] = :control
-            # Remove the stream type byte from the buffer
-            @mutex.synchronize { @response_buffers[stream_id] = StringIO.new(buf[type_len..] || "".b) }
-          when 0x01
-            raise Protocol::FrameError, "Client must not send push streams"
-          when 0x02 # QPACK encoder stream
-            raise Protocol::FrameError, "Duplicate QPACK encoder stream" if @qpack_encoder_stream_id
-            @qpack_encoder_stream_id = stream_id
-            @uni_stream_types[stream_id] = :qpack_encoder
-            @mutex.synchronize { @response_buffers[stream_id] = StringIO.new(buf[type_len..] || "".b) }
-          when 0x03 # QPACK decoder stream
-            raise Protocol::FrameError, "Duplicate QPACK decoder stream" if @qpack_decoder_stream_id
-            @qpack_decoder_stream_id = stream_id
-            @uni_stream_types[stream_id] = :qpack_decoder
-            @mutex.synchronize { @response_buffers[stream_id] = StringIO.new(buf[type_len..] || "".b) }
-          else
-            # Unknown unidirectional stream types MUST be ignored (RFC 9114 §6.2)
-            @uni_stream_types[stream_id] = :unknown
-            return
-          end
+          stream_type, payload = decode_unidirectional_stream(buf)
+          return unless stream_type
 
-          buf = @mutex.synchronize { @response_buffers[stream_id]&.string || "".b }
+          register_unidirectional_stream(stream_id, stream_type, payload)
+          buf = @mutex.synchronize { @response_buffers[stream_id] || "".b }
         end
 
-        stream_type = @uni_stream_types[stream_id]
-        return if buf.empty?
-
-        case stream_type
-        when :control
-          parse_control_frames(buf)
-          # Clear parsed data from buffer
-          @mutex.synchronize { @response_buffers[stream_id] = StringIO.new("".b) }
-        when :qpack_encoder
-          validate_qpack_encoder_data(buf)
-          @mutex.synchronize { @response_buffers[stream_id] = StringIO.new("".b) }
-        when :qpack_decoder
-          validate_qpack_decoder_data(buf)
-          @mutex.synchronize { @response_buffers[stream_id] = StringIO.new("".b) }
-        end
+        process_unidirectional_payload(stream_id, buf)
       end
 
       def handle_unidirectional_stream(stream, fin: true)
@@ -184,35 +278,120 @@ module Quicsilver
         data = stream.data
         return if data.empty?
 
-        stream_type, type_len = Protocol.decode_varint(data.bytes, 0)
-        return if type_len == 0
-        payload = data[type_len..-1]
+        stream_type, payload = decode_unidirectional_stream(data)
+        return unless stream_type
 
         case stream_type
-        when 0x00
+        when Protocol::UnidirectionalStream::CONTROL
           set_control_stream(stream_id, payload)
           if fin
             raise Protocol::FrameError.new("Closure of critical stream", error_code: Protocol::H3_CLOSED_CRITICAL_STREAM)
           end
-        when 0x01
-          raise Protocol::FrameError, "Client must not send push streams"
-        when 0x02
-          raise Protocol::FrameError, "Duplicate QPACK encoder stream" if @qpack_encoder_stream_id
+        when Protocol::UnidirectionalStream::PUSH
+          raise Protocol::FrameError.new("Client must not send push streams",
+            error_code: Protocol::H3_STREAM_CREATION_ERROR)
+        when Protocol::UnidirectionalStream::QPACK_ENCODER
+          raise Protocol::FrameError.new("Duplicate QPACK encoder stream",
+            error_code: Protocol::H3_STREAM_CREATION_ERROR) if @qpack_encoder_stream_id
           @qpack_encoder_stream_id = stream_id
           if fin
             raise Protocol::FrameError.new("Closure of critical stream", error_code: Protocol::H3_CLOSED_CRITICAL_STREAM)
           end
-        when 0x03
-          raise Protocol::FrameError, "Duplicate QPACK decoder stream" if @qpack_decoder_stream_id
+        when Protocol::UnidirectionalStream::QPACK_DECODER
+          raise Protocol::FrameError.new("Duplicate QPACK decoder stream",
+            error_code: Protocol::H3_STREAM_CREATION_ERROR) if @qpack_decoder_stream_id
           @qpack_decoder_stream_id = stream_id
           if fin
             raise Protocol::FrameError.new("Closure of critical stream", error_code: Protocol::H3_CLOSED_CRITICAL_STREAM)
           end
+        when Protocol::WebTransport::UNI_STREAM_TYPE
+          @uni_stream_types ||= {}
+          @uni_stream_types[stream_id] = :webtransport_uni
+          [:webtransport_uni, payload || "".b]
+        end
+      end
+
+      def decode_unidirectional_stream(data)
+        stream_type, type_len = Protocol.decode_varint_str(data, 0)
+        return if type_len == 0
+
+        [stream_type, data[type_len..] || "".b]
+      end
+
+      def register_unidirectional_stream(stream_id, stream_type, payload)
+        case stream_type
+        when Protocol::UnidirectionalStream::CONTROL
+          raise Protocol::FrameError.new("Duplicate control stream",
+            error_code: Protocol::H3_STREAM_CREATION_ERROR) if @control_stream_id
+          @control_stream_id = stream_id
+          @uni_stream_types[stream_id] = :control
+          @mutex.synchronize { @response_buffers[stream_id] = payload }
+        when Protocol::UnidirectionalStream::PUSH
+          raise Protocol::FrameError.new("Client must not send push streams",
+            error_code: Protocol::H3_STREAM_CREATION_ERROR)
+        when Protocol::UnidirectionalStream::QPACK_ENCODER
+          raise Protocol::FrameError.new("Duplicate QPACK encoder stream",
+            error_code: Protocol::H3_STREAM_CREATION_ERROR) if @qpack_encoder_stream_id
+          @qpack_encoder_stream_id = stream_id
+          @uni_stream_types[stream_id] = :qpack_encoder
+          @mutex.synchronize { @response_buffers[stream_id] = payload }
+        when Protocol::UnidirectionalStream::QPACK_DECODER
+          raise Protocol::FrameError.new("Duplicate QPACK decoder stream",
+            error_code: Protocol::H3_STREAM_CREATION_ERROR) if @qpack_decoder_stream_id
+          @qpack_decoder_stream_id = stream_id
+          @uni_stream_types[stream_id] = :qpack_decoder
+          @mutex.synchronize { @response_buffers[stream_id] = payload }
+        when Protocol::WebTransport::UNI_STREAM_TYPE
+          @uni_stream_types[stream_id] = :webtransport_uni
+          @mutex.synchronize { @response_buffers[stream_id] = payload }
+        else
+          @uni_stream_types[stream_id] = :unknown
+        end
+      end
+
+      def process_unidirectional_payload(stream_id, payload)
+        return if payload.empty?
+
+        case @uni_stream_types[stream_id]
+        when :webtransport_uni
+          @mutex.synchronize { @response_buffers[stream_id] = "".b }
+          [:webtransport_uni, payload]
+        when :control
+          # Keep whatever did not form a whole frame. Clearing the buffer
+          # discarded the front of a frame that arrived split across two
+          # receives; its tail then parsed as a new frame, which fails the
+          # connection. Control streams never send FIN, so nothing recovers
+          # it later.
+          consume_unidirectional(stream_id, payload, parse_control_frames(payload))
+        when :qpack_encoder
+          # Unlike :control this validates the leading instruction byte rather
+          # than reassembling frames, so clearing the buffer loses nothing.
+          # An instruction split across receives could still be misread; not
+          # observed, and it would need incremental QPACK decoding to fix.
+          validate_qpack_encoder_data(payload)
+          @mutex.synchronize { @response_buffers[stream_id] = "".b }
+        when :qpack_decoder
+          validate_qpack_decoder_data(payload)
+          @mutex.synchronize { @response_buffers[stream_id] = "".b }
+        end
+      end
+
+      # Drop the bytes a parser consumed, keeping any partial frame. The buffer
+      # may have grown while we parsed, so only what we read is removed.
+      def consume_unidirectional(stream_id, payload, consumed)
+        @mutex.synchronize do
+          buffer = @response_buffers[stream_id]
+          next if buffer.nil?
+
+          remainder = (consumed >= payload.bytesize) ? "".b : payload.byteslice(consumed..)
+          @response_buffers[stream_id] =
+            (buffer.bytesize > payload.bytesize) ? remainder + buffer.byteslice(payload.bytesize..) : remainder
         end
       end
 
       def set_control_stream(stream_id, payload = nil)
-        raise Protocol::FrameError, "Duplicate control stream" if @control_stream_id
+        raise Protocol::FrameError.new("Duplicate control stream",
+            error_code: Protocol::H3_STREAM_CREATION_ERROR) if @control_stream_id
         @control_stream_id = stream_id
         parse_control_frames(payload) if payload && !payload.empty?
       end
@@ -221,6 +400,29 @@ module Quicsilver
         @settings
       end
 
+      # Get the priority for a stream. Returns default Priority if not set.
+      def stream_priority(stream_id)
+        @stream_priorities[stream_id] || Protocol::Priority.new
+      end
+
+      # Apply priority to a QUIC stream via MsQuic.
+      # MsQuic: 0 = lowest, 0xFFFF = highest.
+      # HTTP urgency: 0 = highest, 7 = lowest.
+      # Maps urgency into evenly spaced bands across the uint16 range.
+      # The priority is queued and applied on the MsQuic event thread.
+      def apply_stream_priority(stream, priority)
+        handle = stream.respond_to?(:stream_handle) ? stream.stream_handle : nil
+        return unless handle
+        quic_priority = (7 - priority.urgency) * 0x2000
+        Quicsilver.set_stream_priority(handle, quic_priority)
+      rescue => e
+        Quicsilver.logger.debug("Failed to set stream priority: #{e.message}")
+      end
+
+      def uni_stream_type(stream_id)
+        @uni_stream_types&.dig(stream_id)
+      end
+
       def critical_stream?(stream_id)
         stream_id == @control_stream_id ||
           stream_id == @qpack_encoder_stream_id ||
@@ -234,83 +436,105 @@ module Quicsilver
         Quicsilver.connection_shutdown(@handle, error_code, false)
       end
 
-      private
+      # Returns QUIC transport statistics for this connection.
+      def stats
+        ConnectionStats.from_hash(Quicsilver.connection_statistics(@handle))
+      end
 
       def open_stream(unidirectional: false)
         handle = Quicsilver.open_stream(@data, unidirectional)
         Stream.new(handle)
       end
 
-      def last_client_stream_id
-        @streams.keys.select { |id| (id & 0x02) == 0 }.max || 0
+      private
+
+      def hex_string(value)
+        value.unpack1("H*") if value
+      end
+
+      def connection_metadata
+        metadata = {}
+        metadata["connection_id"] = connection_id if connection_id
+        metadata
       end
 
-      # 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 request_id_for(stream_id)
+        [@transport_server_id, connection_id, stream_id].compact.join(":")
+      end
 
-      # Frame types forbidden on the control stream
+      # Stream may have been reset by client — expected during normal operation.
+      def stream_send_error?(error)
+        unless error.message.include?(MSQUIC_INVALID_STATE) ||
+            error.message.include?("StreamSend failed") ||
+            error.message.include?(STREAM_CLOSED)
+          return false
+        end
+        Quicsilver.logger.debug("Stream send failed (client likely reset): #{error.message}")
+        true
+      end
+
+      def last_request_stream_id
+        @streams.keys.select { |stream_id| StreamId.request?(stream_id) }.max || 0
+      end
+
+      # Frame types forbidden on the control stream (RFC 9114 §7.2.4)
+      # Note: CANCEL_PUSH (0x03) and MAX_PUSH_ID (0x0d) ARE allowed on control stream.
       FORBIDDEN_ON_CONTROL = [
         0x00, # DATA — request streams only
         0x01, # HEADERS — request streams only
-        0x02, # HTTP/2 PRIORITY (reserved)
+        0x02, # HTTP/2 PRIORITY (reserved, §7.2.8)
         0x05, # PUSH_PROMISE — request streams only
-        0x06, # HTTP/2 PING (reserved)
-        0x08, # HTTP/2 WINDOW_UPDATE (reserved)
-        0x09, # HTTP/2 CONTINUATION (reserved)
+        0x06, # HTTP/2 PING (reserved, §7.2.8)
+        0x08, # HTTP/2 WINDOW_UPDATE (reserved, §7.2.8)
+        0x09, # HTTP/2 CONTINUATION (reserved, §7.2.8)
       ].freeze
 
-      def parse_control_frames(data)
-        offset = 0
-        first_frame = !@settings_received
-
-        while offset < data.bytesize
-          frame_type, type_len = Protocol.decode_varint(data.bytes, offset)
-          frame_length, length_len = Protocol.decode_varint(data.bytes, offset + type_len)
-          break if type_len == 0 || length_len == 0
-
-          if first_frame && 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
+      def on_settings_received(settings)
+        @settings.merge!(settings)
+      end
 
-          if FORBIDDEN_ON_CONTROL.include?(frame_type)
-            raise Protocol::FrameError, "Frame type 0x#{frame_type.to_s(16)} not allowed on control stream"
-          end
+      def handle_control_frame(type, payload)
+        # WT_STREAM belongs at the front of a request stream and nowhere else;
+        # on the control stream it is H3_FRAME_ERROR, not H3_FRAME_UNEXPECTED
+        # (draft-ietf-webtrans-http3-16 §4.3).
+        if type == Protocol::FRAME_WT_STREAM
+          raise Protocol::FrameError.new(
+            "WT_STREAM is not allowed on the control stream",
+            error_code: Protocol::H3_FRAME_ERROR
+          )
+        end
 
-          if frame_type == Protocol::FRAME_SETTINGS
-            raise Protocol::FrameError, "Duplicate SETTINGS frame on control stream" if @settings_received
-            parse_settings(data[offset + type_len + length_len, frame_length])
-            @settings_received = true
-          end
+        if FORBIDDEN_ON_CONTROL.include?(type)
+          raise Protocol::FrameError.new(
+            "Frame type 0x#{type.to_s(16)} not allowed on control stream",
+            error_code: Protocol::H3_FRAME_UNEXPECTED
+          )
+        end
 
-          offset += type_len + length_len + frame_length
+        case type
+        when Protocol::FRAME_PRIORITY_UPDATE
+          parse_priority_update(payload)
+        when Protocol::FRAME_CANCEL_PUSH, Protocol::FRAME_MAX_PUSH_ID
+          # No-op: we don't implement server push (RFC 9114 §7.2.3, §7.2.7).
+          # These are valid on the control stream — accept and ignore.
         end
       end
 
-      def parse_settings(payload)
-        offset = 0
-        seen = Set.new
-        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
+      # RFC 9218 §7: Parse PRIORITY_UPDATE frame.
+      # Payload is a stream ID varint followed by a Priority Field Value string.
+      def parse_priority_update(payload)
+        stream_id, consumed = Protocol.decode_varint(payload.bytes, 0)
+        priority_value = payload[consumed..]
+        @stream_priorities[stream_id] = Protocol::Priority.parse(priority_value)
       end
+
       # RFC 9204 §4.1.3: Validate QPACK encoder stream instructions.
-      # We advertise QPACK_MAX_TABLE_CAPACITY = 0, so any Set Dynamic Table Capacity
-      # instruction with value > 0 is an error.
+      # We advertise QPACK_MAX_TABLE_CAPACITY = 0, so:
+      # - Set Dynamic Table Capacity to 0 is valid (RFC 9204 §3.2.2)
+      # - Set Dynamic Table Capacity > 0 is an error
+      # - Insert With Name Reference (1xxxxxxx) is an error (no table to insert into)
+      # - Insert With Literal Name (01xxxxxx) is an error (capacity is 0)
+      # - Duplicate (000xxxxx) is an error (table is empty)
       def validate_qpack_encoder_data(data)
         return if data.empty?
         byte = data.bytes[0]
@@ -319,9 +543,29 @@ module Quicsilver
         if (byte & 0xE0) == 0x20
           capacity, _ = Protocol.decode_varint(data.bytes, 0)
           capacity &= 0x1F  # mask off the instruction prefix
-          # We advertised capacity 0, any non-zero is an error
+          # Setting to 0 is valid; non-zero exceeds our advertised maximum.
+          if capacity > 0
+            raise Protocol::FrameError.new(
+              "Dynamic table capacity exceeds advertised maximum",
+              error_code: Protocol::QPACK_ENCODER_STREAM_ERROR
+            )
+          end
+        elsif (byte & 0x80) == 0x80
+          # Insert With Name Reference — cannot insert when capacity=0
+          raise Protocol::FrameError.new(
+            "Insert instruction received but dynamic table capacity is 0",
+            error_code: Protocol::QPACK_ENCODER_STREAM_ERROR
+          )
+        elsif (byte & 0xC0) == 0x40
+          # Insert With Literal Name — cannot insert when capacity=0
+          raise Protocol::FrameError.new(
+            "Insert instruction received but dynamic table capacity is 0",
+            error_code: Protocol::QPACK_ENCODER_STREAM_ERROR
+          )
+        elsif (byte & 0xE0) == 0x00
+          # Duplicate — table is empty, nothing to duplicate
           raise Protocol::FrameError.new(
-            "Dynamic table capacity exceeds advertised maximum",
+            "Duplicate instruction received but dynamic table is empty",
             error_code: Protocol::QPACK_ENCODER_STREAM_ERROR
           )
         end