quicsilver 0.4.0 → 0.5.0

data/lib/quicsilver/transport/connection.rb

@@ -9,17 +9,60 @@ module Quicsilver
       # 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 initialize(handle, data, max_header_size: nil)
+      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
+
+      # 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
@@ -37,6 +80,55 @@ module Quicsilver
         @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) ===
@@ -52,7 +144,7 @@ module Quicsilver
           stream.send([type].pack("C"))
         end
 
-        # GREASE unidirectional stream (RFC 9297)
+        # GREASE unidirectional stream (RFC 9114 §6.2)
         stream = open_stream(unidirectional: true)
         stream.send(Protocol.encode_varint(Protocol.grease_id) + "GREASE".b)
       end
@@ -95,7 +187,7 @@ 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))
@@ -117,10 +209,9 @@ module Quicsilver
       # RFC 9114 §4.1: encoded as a HEADERS frame, no FIN.
       def send_informational(stream, status, headers)
         data = Protocol::ResponseEncoder.encode_informational(status, headers)
-        Quicsilver.send_stream(stream.stream_handle, data, false)
-      rescue RuntimeError => e
-        raise unless e.message.include?(MSQUIC_INVALID_STATE) || e.message.include?("StreamSend failed")
-        Quicsilver.logger.debug("Stream send failed (client likely reset): #{e.message}")
+        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)
@@ -128,26 +219,28 @@ module Quicsilver
         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?(MSQUIC_INVALID_STATE) || 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?(MSQUIC_INVALID_STATE) || 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 ===
@@ -162,55 +255,16 @@ module Quicsilver
         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] = (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] = (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] = (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
 
+          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] = "".b }
-        when :qpack_encoder
-          validate_qpack_encoder_data(buf)
-          @mutex.synchronize { @response_buffers[stream_id] = "".b }
-        when :qpack_decoder
-          validate_qpack_decoder_data(buf)
-          @mutex.synchronize { @response_buffers[stream_id] = "".b }
-        end
+        process_unidirectional_payload(stream_id, buf)
       end
 
       def handle_unidirectional_stream(stream, fin: true)
@@ -224,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
@@ -280,6 +419,10 @@ module Quicsilver
         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 ||
@@ -293,26 +436,57 @@ 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
+
+      def request_id_for(stream_id)
+        [@transport_server_id, connection_id, stream_id].compact.join(":")
+      end
+
+      # 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
+      # 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 on_settings_received(settings)
@@ -320,12 +494,29 @@ module Quicsilver
       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 FORBIDDEN_ON_CONTROL.include?(type)
-          raise Protocol::FrameError, "Frame type 0x#{type.to_s(16)} not allowed on control stream"
+          raise Protocol::FrameError.new(
+            "Frame type 0x#{type.to_s(16)} not allowed on control stream",
+            error_code: Protocol::H3_FRAME_UNEXPECTED
+          )
         end
 
-        if type == Protocol::FRAME_PRIORITY_UPDATE
+        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
 
@@ -338,8 +529,12 @@ module Quicsilver
       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]
@@ -348,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

data/lib/quicsilver/transport/connection_stats.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Transport
+    # Immutable snapshot of QUIC transport statistics from MsQuic's QUIC_STATISTICS_V2.
+    #
+    #   stats = client.stats
+    #   stats.rtt                    # => 1234 (microseconds)
+    #   stats.send_total_packets     # => 42
+    #   stats.recv_total_bytes       # => 98765
+    #
+    ConnectionStats = Data.define(
+      # RTT (microseconds)
+      :rtt, :min_rtt, :max_rtt,
+
+      # Handshake
+      :resumption_attempted, :resumption_succeeded,
+
+      # Send
+      :send_path_mtu,
+      :send_total_packets, :send_retransmittable_packets,
+      :send_suspected_lost_packets, :send_spurious_lost_packets,
+      :send_total_bytes, :send_total_stream_bytes,
+      :send_congestion_count, :send_persistent_congestion_count,
+      :send_congestion_window,
+
+      # Recv
+      :recv_total_packets, :recv_reordered_packets,
+      :recv_dropped_packets, :recv_duplicate_packets,
+      :recv_total_bytes, :recv_total_stream_bytes,
+      :recv_decryption_failures, :recv_valid_ack_frames,
+
+      # Misc
+      :key_update_count
+    ) do
+      # Build from the hash returned by the C extension.
+      def self.from_hash(hash)
+        return nil unless hash
+
+        new(**hash.transform_keys(&:to_sym))
+      end
+
+      def resumed?
+        resumption_succeeded
+      end
+
+      def packet_loss_rate
+        return 0.0 if send_total_packets == 0
+        send_suspected_lost_packets.to_f / send_total_packets
+      end
+    end
+  end
+end

data/lib/quicsilver/transport/event_loop.rb

@@ -2,10 +2,33 @@
 
 module Quicsilver
   module Transport
+    # Two threads: one drives MsQuic, one delivers its events to Ruby.
+    #
+    # The poll thread runs Quicsilver.poll, which releases the GVL for the
+    # whole MsQuic iteration: decryption, loss recovery, stream reassembly and
+    # the callbacks that queue events for Ruby all happen without the lock.
+    # The dispatcher thread runs Quicsilver.dispatch_events, which waits on
+    # that queue without the GVL, then takes it to call Server.handle_stream
+    # (or Client#handle_stream_event) for each event in order.
+    #
+    # Before, a single thread did both, and every byte MsQuic processed was
+    # processed while holding the GVL, because the callback at the end of it
+    # called into Ruby. Splitting them lets the datapath run in parallel with
+    # the dispatcher and the worker pool.
+    #
+    # Event order is preserved: the queue is FIFO and there is one consumer.
     class EventLoop
+      # Events delivered per GVL hold. Bounds how long a batch runs; the
+      # dispatcher yields early only when the server's admission queue is
+      # under pressure (Server#enqueue_work). QUICSILVER_DISPATCH_BATCH
+      # overrides it for measurement.
+      DISPATCH_BATCH = Integer(ENV.fetch("QUICSILVER_DISPATCH_BATCH", "64"))
+      DISPATCH_WAIT_MS = 1000
+
       def initialize
         @running = false
         @thread = nil
+        @dispatcher = nil
         @mutex = Mutex.new
       end
 
@@ -14,16 +37,29 @@ module Quicsilver
           return if @running
 
           @running = true
+          Quicsilver.open_event_queue
+          @dispatcher = Thread.new do
+            Thread.current.name = "quicsilver-dispatch"
+            loop do
+              delivered = Quicsilver.dispatch_events(DISPATCH_BATCH, DISPATCH_WAIT_MS)
+              break if delivered.nil? # queue closed and drained
+            end
+          end
           @thread = Thread.new do
+            Thread.current.name = "quicsilver-poll"
             Quicsilver.poll while @running
           end
         end
       end
 
+      # Stop the poll thread first so nothing else is queued, then close the
+      # queue so the dispatcher exits once it has delivered what is there.
       def stop
         @running = false
         Quicsilver.wake
         @thread&.join(2)
+        Quicsilver.close_event_queue
+        @dispatcher&.join(2)
       end
 
       def join