quicsilver 0.3.0 → 0.5.0

data/lib/quicsilver/client/client.rb

@@ -1,104 +1,181 @@
 # frozen_string_literal: true
 
-require "timeout"
-
 module Quicsilver
   class Client
-    attr_reader :hostname, :port, :unsecure, :connection_timeout, :request_timeout
+    include Protocol::ControlStreamParser
 
-    AlreadyConnectedError = Class.new(StandardError)
-    NotConnectedError = Class.new(StandardError)
-    StreamFailedToOpenError = Class.new(StandardError)
+    attr_reader :hostname, :port, :unsecure, :connection_timeout, :request_timeout, :idle_timeout_ms
+    attr_reader :peer_goaway_id, :peer_settings, :peer_max_field_section_size
 
-    FINISHED_EVENTS = %w[RECEIVE_FIN RECEIVE STREAM_RESET STOP_SENDING].freeze
+    FINISHED_EVENTS = %w[RECEIVE_FIN RECEIVE STREAM_RESET STOP_SENDING DATAGRAM_RECEIVED STREAM_START_COMPLETE STREAM_PEER_ACCEPTED].freeze
 
     DEFAULT_REQUEST_TIMEOUT = 30  # seconds
     DEFAULT_CONNECTION_TIMEOUT = 5000  # ms
 
-    def initialize(hostname, port = 4433, options = {})
+    # Options that shape the QUIC connection rather than a single request.
+    # ConnectionPool keys pooled connections on these, so a connection built
+    # with one set is never reused for a caller asking for another.
+    DEFAULT_CONNECTION_OPTIONS = {
+      unsecure: false,
+      datagram_receive_enabled: true,
+      reliable_reset_enabled: true,
+      transport_cibir_id: nil,
+      idle_timeout_ms: Transport::Configuration::DEFAULT_IDLE_TIMEOUT_MS
+    }.freeze
+
+    def initialize(hostname, port = 4433, **options)
       @hostname = hostname
       @port = port
-      @unsecure = options.fetch(:unsecure, true)
+      @unsecure = options.fetch(:unsecure, DEFAULT_CONNECTION_OPTIONS[:unsecure])
+      @datagram_receive_enabled = options.fetch(:datagram_receive_enabled,
+        DEFAULT_CONNECTION_OPTIONS[:datagram_receive_enabled])
+      @reliable_reset_enabled = options.fetch(:reliable_reset_enabled,
+        DEFAULT_CONNECTION_OPTIONS[:reliable_reset_enabled])
       @connection_timeout = options.fetch(:connection_timeout, DEFAULT_CONNECTION_TIMEOUT)
+      @idle_timeout_ms = options.fetch(:idle_timeout_ms, DEFAULT_CONNECTION_OPTIONS[:idle_timeout_ms])
       @request_timeout = options.fetch(:request_timeout, DEFAULT_REQUEST_TIMEOUT)
       @max_body_size = options[:max_body_size]
       @max_header_size = options[:max_header_size]
 
+      # MsQuic CIBIR bytes for connecting to a CIBIR-configured listener.
+      # Must be set before ConnectionStart; MsQuic currently supports offset 0 only.
+      @transport_cibir_id = normalize_transport_cibir_id(options[:transport_cibir_id])
+
       @connection_data = nil
       @connected = false
       @connection_start_time = nil
 
-      @response_buffers = {}
-      @pending_requests = {}  # handle => Request
+      @response_buffers = {}  # stream_id => binary data
+      @streaming = {}  # stream_id => { body:, frame_buffer: }
+      @inflight = {}  # handle => { request:, stream_id: }
       @mutex = Mutex.new
+
+      # Server control stream state
+      @peer_settings = {}
+      @peer_max_field_section_size = nil
+      @peer_goaway_id = nil
+      @settings_received = false
+      @control_stream_id = nil
+      @uni_stream_types = {}
+      @datagram_callback = nil
+      @resumption_ticket = nil  # stored ticket for 0-RTT reconnection
     end
 
-    def connect
-      raise AlreadyConnectedError if @connected
+    # --- Class-level API (automatic pooling) ---
+    #
+    #   Quicsilver::Client.get("example.com", 4433, "/users")
+    #   Quicsilver::Client.post("example.com", 4433, "/data", body: json)
+    #
+    class << self
+      attr_writer :pool
 
-      Quicsilver.open_connection
-      config = Quicsilver.create_configuration(@unsecure)
-      raise ConnectionError, "Failed to create configuration" if config.nil?
+      def pool
+        @pool ||= ConnectionPool.new
+      end
 
-      start_connection(config)
-      @connected = true
-      @connection_start_time = Time.now
-      send_control_stream
-      Quicsilver.event_loop.start
+      def close_pool
+        @pool&.close
+        @pool = nil
+      end
 
-      self
-    rescue => e
-      cleanup_failed_connection
-      raise e.is_a?(ConnectionError) || e.is_a?(TimeoutError) ? e : ConnectionError.new("Connection failed: #{e.message}")
-    ensure
-      Quicsilver.close_configuration(config)
+      # Fire-and-forget HTTP methods with automatic pooling.
+      %i[get post patch delete head put].each do |method|
+        define_method(method) do |hostname, port, path, headers: {}, body: nil, **options, &block|
+          request(hostname, port, method, path, headers: headers, body: body, **options, &block)
+        end
+      end
+
+      def request(hostname, port, method, path, headers: {}, body: nil, priority: nil, timeout: nil, **options, &block)
+        client = pool.checkout(hostname, port, **options)
+        client.public_send(method, path, headers: headers, body: body, priority: priority, timeout: timeout, &block)
+      ensure
+        pool.checkin(client) if client
+      end
     end
 
+    # Disconnect and close the underlying QUIC connection.
+    # Saves the resumption ticket for 0-RTT on the next connect.
     def disconnect
-      return unless @connection_data
+      return unless @connected
 
       @connected = false
 
-      # Fail pending requests
+      # Save resumption ticket before closing (for 0-RTT reconnection)
+      if @connection_data
+        ticket = Quicsilver.get_resumption_ticket(@connection_data[1])
+        @resumption_ticket = ticket if ticket
+      end
+
       @mutex.synchronize do
-        @pending_requests.each_value { |req| req.fail(0, "Connection closed") }
-        @pending_requests.clear
+        @inflight.each_value { |entry| entry[:request].fail(0, "Connection closed") }
+        @streaming.each_value { |state| state[:body]&.close(RuntimeError.new("Connection closed")) }
+        @inflight.clear
         @response_buffers.clear
+        @streaming.clear
       end
 
-      Quicsilver.close_connection_handle(@connection_data) if @connection_data
-      @connection_data = nil
+      close_connection
     end
 
-    # HTTP methods - block gives you request control, no block returns response directly
-    #
-    #   # Simple (blocking)
-    #   response = client.get("/users")
+    # Instance-level HTTP methods. Auto-connects on first use.
     #
-    #   # With control
-    #   client.get("/users") do |req|
-    #     req.cancel if should_abort?
-    #     req.response
-    #   end
+    #   client = Quicsilver::Client.new("example.com", 4433)
+    #   client.get("/users")   # connects automatically
+    #   client.post("/data", body: json)
     #
     %i[get post patch delete head put].each do |method|
-      define_method(method) do |path, headers: {}, body: nil, &block|
-        req = build_request(method.to_s.upcase, path, headers: headers, body: body)
-        block ? block.call(req) : req.response
+      define_method(method) do |path, headers: {}, body: nil, priority: nil, timeout: nil, &block|
+        req = build_request(method.to_s.upcase, path, headers: headers, body: body, priority: priority)
+        block ? block.call(req) : req.response(timeout: timeout)
+      end
+    end
+
+    def draining?
+      !@peer_goaway_id.nil?
+    end
+
+    # Send an unreliable datagram (RFC 9297 / QUIC RFC 9221).
+    # Data must fit in a single QUIC packet (~1200 bytes).
+    # Not retransmitted — best effort delivery.
+    #
+    #   client.datagram_send("real-time-update")
+    #
+    def datagram_send(data)
+      ensure_connected!
+      Quicsilver.datagram_send(@connection_data, data.to_s.b)
+    end
+
+    # Register a callback for received datagrams.
+    #
+    #   client.on_datagram { |data| puts "Got: #{data}" }
+    #
+    def on_datagram(&block)
+      @datagram_callback = block
+    end
+
+    def receive_control_data(stream_id, data) # :nodoc:
+      buf = @uni_stream_types.key?(stream_id) ? data : identify_and_strip_stream_type(stream_id, data)
+      return if buf.nil? || buf.empty?
+
+      case @uni_stream_types[stream_id]
+      when :control
+        parse_control_frames(buf)
       end
     end
 
-    # Build and send request, returns Request object for lifecycle control
-    def build_request(method, path, headers: {}, body: nil)
-      raise NotConnectedError unless @connected
+    def build_request(method, path, headers: {}, body: nil, priority: nil)
+      ensure_connected!
+      raise GoAwayError, "Connection is draining (GOAWAY received)" if draining?
 
       stream = open_stream
       raise StreamFailedToOpenError unless stream
 
       request = Request.new(self, stream)
-      @mutex.synchronize { @pending_requests[stream.handle] = request }
+      @mutex.synchronize do
+        @inflight[stream.handle] = { request: request, stream_id: nil }
+      end
 
-      send_to_stream(stream, method, path, headers, body)
+      send_to_stream(stream, method, path, headers, body, priority: priority)
 
       request
     end
@@ -107,6 +184,15 @@ module Quicsilver
       @connected && @connection_data && connection_alive?
     end
 
+    # Returns QUIC transport statistics (RTT, packet counts, congestion, etc.)
+    # from MsQuic's QUIC_STATISTICS_V2. Returns nil when not connected.
+    def stats
+      return nil unless @connected && @connection_data
+      Transport::ConnectionStats.from_hash(Quicsilver.connection_statistics(@connection_data[0]))
+    rescue
+      nil
+    end
+
     def connection_info
       info = @connection_data ? Quicsilver.connection_status(@connection_data[1]) : {}
       info.merge(hostname: @hostname, port: @port, uptime: connection_uptime)
@@ -121,43 +207,104 @@ module Quicsilver
       "#{@hostname}:#{@port}"
     end
 
+    # :nodoc:
+    def open_connection
+      return self if @connected
+
+      Quicsilver.open_connection
+      # The poll thread is the only thing that drives MsQuic, including this
+      # handshake; wait_for_connection only watches for the result. In a
+      # process with no server the loop is not running yet, so start it first.
+      Quicsilver.event_loop.start
+      config = create_configuration
+      raise ConnectionError, "Failed to create configuration" if config.nil?
+
+      start_connection(config)
+      @connected = true
+      @connection_start_time = Time.now
+      send_control_stream
+
+      self
+    rescue => e
+      cleanup_failed_connection
+      raise e.is_a?(ConnectionError) || e.is_a?(TimeoutError) ? e : ConnectionError.new("Connection failed: #{e.message}")
+    ensure
+      Quicsilver.close_configuration(config) if config
+    end
+
+    # :nodoc:
+    def close_connection
+      Quicsilver.close_connection_handle(@connection_data) if @connection_data
+      @connection_data = nil
+      @connected = false
+    end
+
     # Called directly by C extension via dispatch_to_ruby
     def handle_stream_event(stream_id, event, data, _early_data) # :nodoc:
       return unless FINISHED_EVENTS.include?(event)
 
+      # Server unidirectional streams (control, QPACK) — process incrementally
+      if Transport::StreamId.unidirectional?(stream_id) && (event == "RECEIVE" || event == "RECEIVE_FIN")
+        begin
+          receive_control_data(stream_id, data)
+        rescue Protocol::FrameError => e
+          Quicsilver.logger.error("Control stream error: #{e.message} (0x#{e.error_code.to_s(16)})")
+        end
+        return
+      end
+
       @mutex.synchronize do
         case event
         when "RECEIVE"
-          (@response_buffers[stream_id] ||= StringIO.new("".b)).write(data)
-
+          handle_receive(stream_id, data)
         when "RECEIVE_FIN"
-          event = Transport::StreamEvent.new(data, "RECEIVE_FIN")
-
-          buffer = @response_buffers.delete(stream_id)
-          full_data = (buffer&.string || "".b) + event.data
-
-          response_parser = Protocol::ResponseParser.new(full_data, max_body_size: @max_body_size,
-            max_header_size: @max_header_size)
-          response_parser.parse
-
-          response = {
-            status: response_parser.status,
-            headers: response_parser.headers,
-            body: response_parser.body.read
-          }
-
-          request = @pending_requests.delete(event.handle)
-          request&.complete(response)
-
+          handle_receive_fin(stream_id, data)
         when "STREAM_RESET"
           event = Transport::StreamEvent.new(data, "STREAM_RESET")
-          request = @pending_requests.delete(event.handle)
-          request&.fail(event.error_code, "Stream reset by peer")
-
+          state = @streaming.delete(stream_id)
+          state&.dig(:body)&.close(RuntimeError.new("Stream reset by peer"))
+          entry = @inflight.delete(event.handle)
+          entry[:request]&.fail(event.error_code, "Stream reset by peer") if entry
         when "STOP_SENDING"
           event = Transport::StreamEvent.new(data, "STOP_SENDING")
-          request = @pending_requests.delete(event.handle)
-          request&.fail(event.error_code, "Peer sent STOP_SENDING")
+          state = @streaming.delete(stream_id)
+          state&.dig(:body)&.close(RuntimeError.new("Peer sent STOP_SENDING"))
+          entry = @inflight.delete(event.handle)
+          entry[:request]&.fail(event.error_code, "Peer sent STOP_SENDING") if entry
+        when "DATAGRAM_RECEIVED"
+          @datagram_callback&.call(data)
+        when "STREAM_START_COMPLETE"
+          # QUIC stream concurrency limit (MAX_STREAMS, RFC 9000 §4.6):
+          #
+          # The peer advertises how many streams can be open simultaneously
+          # on this connection via the initial_max_streams_bidi transport
+          # parameter. Controlled server-side by max_concurrent_requests
+          # (default 100, matches quic-go and Chromium).
+          #
+          # When the limit is hit, MsQuic queues new streams locally and
+          # sends a STREAMS_BLOCKED frame to the peer (RFC 9000 §19.14,
+          # SHOULD send, useful for debugging — not a flow control
+          # mechanism). The peer independently raises the limit by
+          # sending MAX_STREAMS as existing streams close.
+          #
+          # peer_accepted=true:  stream is flowing immediately.
+          # peer_accepted=false: stream queued, connection is saturated.
+          #
+          # When saturated, the shared pool could open a second connection
+          # to the same host. Each QUIC connection has independent stream
+          # capacity, congestion control, and TLS state — so a saturated
+          # connection doesn't block a fresh one. This scales to
+          # N connections × 100 streams = N×100 concurrent requests.
+          # The ceiling is the server's max_connections (default 100).
+          #
+          # Rotation can be useful for long-lived streams:
+          # SSE, WebTransport data channels, gRPC streaming RPCs.
+          accepted = data.getbyte(8) == 1
+          Quicsilver.logger.debug("Stream #{stream_id} start complete (peer_accepted=#{accepted})")
+        when "STREAM_PEER_ACCEPTED"
+          # Previously queued stream now accepted — peer sent MAX_STREAMS
+          # (existing streams closed, freeing stream concurrency capacity).
+          Quicsilver.logger.debug("Stream #{stream_id} accepted by peer (MAX_STREAMS raised)")
         end
       end
     rescue => e
@@ -167,8 +314,29 @@ module Quicsilver
 
     private
 
+    def create_configuration
+      Quicsilver.create_configuration(@unsecure, @datagram_receive_enabled, @reliable_reset_enabled,
+        nil, nil, @idle_timeout_ms)
+    end
+
+    def ensure_connected!
+      return if @connected
+      @mutex.synchronize do
+        return if @connected
+        open_connection
+      end
+    end
+
     def start_connection(config)
       connection_handle, context_handle = create_connection
+
+      configure_cibir(connection_handle)
+
+      # Apply saved resumption ticket for 0-RTT reconnection
+      if @resumption_ticket
+        Quicsilver.set_resumption_ticket(connection_handle, @resumption_ticket)
+      end
+
       unless Quicsilver.start_connection(connection_handle, config, @hostname, @port)
         cleanup_failed_connection
         raise ConnectionError, "Failed to start connection"
@@ -185,6 +353,23 @@ module Quicsilver
       @connection_data
     end
 
+    def configure_cibir(connection_handle)
+      return unless @transport_cibir_id
+
+      Quicsilver.configure_connection_cibir(connection_handle, [@transport_cibir_id].pack("H*"))
+    end
+
+    def normalize_transport_cibir_id(value)
+      return if value.nil?
+
+      cibir_id = value.to_s
+      unless cibir_id.match?(/\A[[:xdigit:]]+\z/) && cibir_id.bytesize.even? && cibir_id.bytesize.between?(2, 12)
+        raise ArgumentError, "transport_cibir_id must be 1..6 bytes encoded as an even-length hex string"
+      end
+
+      cibir_id.downcase
+    end
+
     def cleanup_failed_connection
       Quicsilver.close_connection_handle(@connection_data) if @connection_data
       @connection_data = nil
@@ -194,6 +379,16 @@ module Quicsilver
     def open_stream
       handle = Quicsilver.open_stream(@connection_data, false)
       Transport::Stream.new(handle)
+    rescue RuntimeError => e
+      status = TransportError.parse_status(e.message)
+      case e.message
+      when /\AStreamOpen failed/, /\AStreamStart failed/
+        raise StreamFailedToOpenError.new(e.message, status: status)
+      when /\AFailed to allocate/
+        raise TransportError.new(e.message, status: status)
+      else
+        raise
+      end
     end
 
     def open_unidirectional_stream
@@ -203,15 +398,28 @@ module Quicsilver
 
     def send_control_stream
       @control_stream = open_unidirectional_stream
-      @control_stream.send(Protocol.build_control_stream)
+      @control_stream.send(Protocol.build_control_stream(datagram_receive_enabled: @datagram_receive_enabled))
 
-      # RFC 9204: QPACK encoder (0x02) and decoder (0x03) streams
       [0x02, 0x03].each do |type|
         stream = open_unidirectional_stream
         stream.send([type].pack("C"))
       end
     end
 
+    # RFC 9218 §7: Send PRIORITY_UPDATE frame on the control stream.
+    # Reprioritises an in-flight stream after it was opened.
+    def send_priority_update(stream_id, priority)
+      return unless @control_stream && priority
+
+      field_value = priority.to_s
+      payload = Protocol.encode_varint(stream_id) + field_value.b
+      frame = Protocol.encode_varint(Protocol::FRAME_PRIORITY_UPDATE) +
+        Protocol.encode_varint(payload.bytesize) + payload
+      @control_stream.send(frame, fin: false)
+    rescue => e
+      Quicsilver.logger.debug("Failed to send PRIORITY_UPDATE: #{e.message}")
+    end
+
     def handle_connection_result(result)
       if result.key?("error")
         cleanup_failed_connection
@@ -229,22 +437,272 @@ module Quicsilver
       false
     end
 
-    def send_to_stream(stream, method, path, headers, body)
-      encoded_response = Protocol::RequestEncoder.new(
-        method: method,
-        path: path,
-        scheme: "https",
-        authority: authority,
-        headers: headers,
-        body: body
-      ).encode
+    def send_to_stream(stream, method, path, headers, body, priority: nil)
+      # RFC 9114 §4.2.2: Enforce server's SETTINGS_MAX_FIELD_SECTION_SIZE
+      if @peer_max_field_section_size
+        header_size = estimate_header_size(method, path, headers)
+        if header_size > @peer_max_field_section_size
+          @mutex.synchronize { @inflight.delete(stream.handle) }
+          raise Error, "Request headers (#{header_size} bytes) exceed server's max field section size (#{@peer_max_field_section_size})"
+        end
+      end
 
-      result = stream.send(encoded_response, fin: true)
+      if body == :stream
+        # Streaming mode: send HEADERS only, body sent later via Request#stream_body
+        encoded = Protocol::RequestEncoder.new(
+          method: method, path: path, scheme: "https",
+          authority: authority, headers: headers, body: nil, priority: priority
+        ).encode
+        result = stream.send(encoded, fin: false)
+      else
+        # Buffered mode: send HEADERS + body + FIN
+        encoded = Protocol::RequestEncoder.new(
+          method: method, path: path, scheme: "https",
+          authority: authority, headers: headers, body: body, priority: priority
+        ).encode
+        result = stream.send(encoded, fin: true)
+      end
 
       unless result
-        @mutex.synchronize { @pending_requests.delete(stream.handle) }
+        @mutex.synchronize { @inflight.delete(stream.handle) }
         raise Error, "Failed to send request"
       end
     end
+
+    # RFC 9114 §4.2.2: Estimate header field section size.
+    # Each field: name length + value length + 32 bytes overhead.
+    def handle_receive(stream_id, data)
+      # Data is prepended with [stream_handle(8)] — extract handle and payload
+      event_obj = Transport::StreamEvent.new(data, "RECEIVE")
+      if (entry = @inflight[event_obj.handle])
+        entry[:stream_id] ||= stream_id
+      end
+
+      state = @streaming[stream_id]
+      if state
+        # Already streaming — feed DATA frames to the body
+        state[:frame_buffer] << event_obj.data
+        drain_streaming_data(state)
+      else
+        (@response_buffers[stream_id] ||= "".b) << event_obj.data
+        strip_informational_frames!(stream_id)
+        # Only transition to streaming when the caller opted in via streaming_response.
+        # Buffered callers (.response) are unaffected.
+        if entry && entry[:request].streaming_requested?
+          try_start_streaming(stream_id, event_obj.handle)
+        end
+      end
+    end
+
+    def handle_receive_fin(stream_id, data)
+      event = Transport::StreamEvent.new(data, "RECEIVE_FIN")
+      state = @streaming.delete(stream_id)
+
+      if state
+        # Streaming mode: feed final data, close body
+        if event.data && !event.data.empty?
+          state[:frame_buffer] << event.data
+          drain_streaming_data(state)
+        end
+        state[:body].close_write
+
+        # Complete for .response() callers — they get the full body retroactively
+        entry = @inflight.delete(event.handle)
+        return unless entry
+        body_str = state[:body].rewind ? state[:body].read : ""
+        entry[:request].complete(Response.new(
+          status: state[:status], headers: state[:headers],
+          body: body_str, trailers: state[:trailers] || {}
+        ))
+      else
+        # Buffered mode: parse everything at once
+        buffer = @response_buffers.delete(stream_id)
+        full_data = (buffer || "".b) + event.data
+        full_data = strip_informational_data(full_data)
+
+        response_parser = Protocol::ResponseParser.new(full_data, max_body_size: @max_body_size,
+          max_header_size: @max_header_size)
+        response_parser.parse
+        response_parser.validate_response!
+
+        body_str = response_parser.body&.read || ""
+        response = Response.new(
+          status: response_parser.status, headers: response_parser.headers,
+          body: body_str, trailers: response_parser.trailers || {}
+        )
+
+        entry = @inflight.delete(event.handle)
+        if entry
+          # Deliver as streaming response if caller opted in but data arrived
+          # before streaming mode could be activated (race condition fallback).
+          if entry[:request].streaming_requested?
+            streaming_body = Protocol::StreamInput.new
+            streaming_body.write(body_str) unless body_str.empty?
+            streaming_body.close_write
+            entry[:request].deliver_streaming(Response.new(
+              status: response_parser.status, headers: response_parser.headers,
+              body: streaming_body, trailers: response_parser.trailers || {}
+            ))
+          end
+          entry[:request].complete(response)
+        end
+      end
+    end
+
+    # Try to parse HEADERS from buffered data and start streaming.
+    def try_start_streaming(stream_id, handle)
+      buf = @response_buffers[stream_id]
+      return unless buf && buf.bytesize >= 2
+
+      # Use FrameReader to find the first HEADERS frame
+      status = nil
+      headers = {}
+      headers_end = 0
+
+      Protocol::FrameReader.each(buf) do |type, payload, offset|
+        if type == Protocol::FRAME_HEADERS
+          s = peek_status(payload)
+          if s && s >= 200
+            status = s
+            PEEK_DECODER.decode(payload) do |name, value|
+              headers[name] = value unless name == ":status"
+            end
+            headers_end = offset
+          end
+        end
+        break # only look at the first frame
+      end
+
+      return unless status  # No final HEADERS yet
+
+      # Transition from buffered to streaming
+      remaining = buf.byteslice(headers_end..-1) || "".b
+      @response_buffers.delete(stream_id)
+
+      body = Protocol::StreamInput.new
+      state = { body: body, frame_buffer: remaining, status: status, headers: headers, trailers: {} }
+      @streaming[stream_id] = state
+
+      # Drain any DATA frames that arrived with the HEADERS
+      drain_streaming_data(state)
+
+      # Deliver StreamingResponse to streaming_response() callers
+      entry = @inflight[handle]
+      entry[:request].deliver_streaming(Response.new(
+        status: status, headers: headers, body: body
+      )) if entry
+    end
+
+    # Extract complete DATA frame payloads from frame_buffer and write to body.
+    def drain_streaming_data(state)
+      buf = state[:frame_buffer]
+      consumed = 0
+
+      Protocol::FrameReader.each(buf) do |type, payload, offset|
+        if type == Protocol::FRAME_DATA
+          state[:body].write(payload)
+        elsif type == Protocol::FRAME_HEADERS && state[:status]
+          # Trailing HEADERS frame — decode as trailers
+          trailers = {}
+          PEEK_DECODER.decode(payload) { |name, value| trailers[name] = value }
+          state[:trailers] = trailers
+        end
+        consumed = offset
+      end
+
+      if consumed > 0
+        state[:frame_buffer] = buf.byteslice(consumed..-1) || "".b
+      end
+    end
+
+    def estimate_header_size(method, path, headers)
+      size = 0
+      # Pseudo-headers
+      size += ":method".bytesize + method.to_s.bytesize + 32
+      size += ":path".bytesize + path.to_s.bytesize + 32
+      size += ":scheme".bytesize + 5 + 32  # "https"
+      size += ":authority".bytesize + authority.bytesize + 32
+      # Regular headers
+      headers.each { |name, value| size += name.to_s.bytesize + value.to_s.bytesize + 32 }
+      size
+    end
+
+    # Strip leading 1xx informational HEADERS frames from data.
+    # RFC 9114 §4.1: Interim responses (1xx) precede the final response.
+    def strip_informational_data(data)
+      skip = Protocol::FrameReader.skip_while(data) do |type, payload|
+        type == Protocol::FRAME_HEADERS &&
+          (status = peek_status(payload)) && status >= 100 && status < 200
+      end
+      skip > 0 ? data.byteslice(skip..-1) || "".b : data
+    end
+
+    def strip_informational_frames!(stream_id)
+      buf = @response_buffers[stream_id]
+      return unless buf && buf.bytesize >= 2
+
+      @response_buffers[stream_id] = strip_informational_data(buf)
+    end
+
+    # Decode just the :status pseudo-header from a QPACK header block.
+    PEEK_DECODER = Protocol::Qpack::HeaderBlockDecoder.new
+
+    def peek_status(qpack_payload)
+      PEEK_DECODER.decode(qpack_payload) do |name, value|
+        return value.to_i if name == ":status"
+      end
+      nil
+    rescue
+      nil
+    end
+
+    # Identify stream type from first byte(s), strip it, return remaining data.
+    # Returns nil for unknown/ignored stream types.
+    def identify_and_strip_stream_type(stream_id, data)
+      stream_type, type_len = Protocol.decode_varint(data.bytes, 0)
+      return nil if type_len == 0
+
+      case stream_type
+      when 0x00 # Control stream
+        if @control_stream_id
+          raise Protocol::FrameError.new("Duplicate control stream",
+            error_code: Protocol::H3_STREAM_CREATION_ERROR)
+        end
+        @control_stream_id = stream_id
+        @uni_stream_types[stream_id] = :control
+      when 0x02 # QPACK encoder stream
+        @uni_stream_types[stream_id] = :qpack_encoder
+      when 0x03 # QPACK decoder stream
+        @uni_stream_types[stream_id] = :qpack_decoder
+      else
+        # Unknown unidirectional stream types MUST be ignored (RFC 9114 §6.2)
+        @uni_stream_types[stream_id] = :unknown
+        return nil
+      end
+
+      data[type_len..] || "".b
+    end
+
+    def on_settings_received(settings)
+      @peer_settings.merge!(settings)
+      @peer_max_field_section_size = settings[0x06] if settings.key?(0x06)
+    end
+
+    # RFC 9114 §5.2: After receiving GOAWAY, fail any in-flight requests
+    # on streams at or above the GOAWAY stream ID — the server won't process them.
+    def on_goaway_received(goaway_stream_id)
+      fail_requests_above_goaway(goaway_stream_id)
+    end
+
+    def fail_requests_above_goaway(goaway_stream_id)
+      @mutex.synchronize do
+        @inflight.each do |handle, entry|
+          sid = entry[:stream_id]
+          next unless sid && sid >= goaway_stream_id
+          @inflight.delete(handle)
+          entry[:request]&.fail(0, "GOAWAY: server will not process stream #{sid}")
+        end
+      end
+    end
   end
 end