quicsilver 0.3.0 → 0.4.0

data/lib/quicsilver/client/client.rb

@@ -1,21 +1,21 @@
 # frozen_string_literal: true
 
-require "timeout"
-
 module Quicsilver
   class Client
+    include Protocol::ControlStreamParser
+
     attr_reader :hostname, :port, :unsecure, :connection_timeout, :request_timeout
+    attr_reader :peer_goaway_id, :peer_settings, :peer_max_field_section_size
 
-    AlreadyConnectedError = Class.new(StandardError)
-    NotConnectedError = Class.new(StandardError)
     StreamFailedToOpenError = Class.new(StandardError)
+    GoAwayError = Class.new(StandardError)
 
     FINISHED_EVENTS = %w[RECEIVE_FIN RECEIVE STREAM_RESET STOP_SENDING].freeze
 
     DEFAULT_REQUEST_TIMEOUT = 30  # seconds
     DEFAULT_CONNECTION_TIMEOUT = 5000  # ms
 
-    def initialize(hostname, port = 4433, options = {})
+    def initialize(hostname, port = 4433, **options)
       @hostname = hostname
       @port = port
       @unsecure = options.fetch(:unsecure, true)
@@ -31,55 +31,68 @@ module Quicsilver
       @response_buffers = {}
       @pending_requests = {}  # handle => Request
       @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 = {}
     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, **options, &block)
+        client = pool.checkout(hostname, port, **options)
+        client.public_send(method, path, headers: headers, body: body, &block)
+      ensure
+        pool.checkin(client) if client
+      end
     end
 
+    # Disconnect and close the underlying QUIC connection.
     def disconnect
-      return unless @connection_data
+      return unless @connected
 
       @connected = false
 
-      # Fail pending requests
       @mutex.synchronize do
         @pending_requests.each_value { |req| req.fail(0, "Connection closed") }
         @pending_requests.clear
         @response_buffers.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
+    # Instance-level HTTP methods. Auto-connects on first use.
     #
-    #   # Simple (blocking)
-    #   response = client.get("/users")
-    #
-    #   # 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|
@@ -88,9 +101,23 @@ module Quicsilver
       end
     end
 
-    # Build and send request, returns Request object for lifecycle control
+    def draining?
+      !@peer_goaway_id.nil?
+    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
+
     def build_request(method, path, headers: {}, body: nil)
-      raise NotConnectedError unless @connected
+      ensure_connected!
+      raise GoAwayError, "Connection is draining (GOAWAY received)" if draining?
 
       stream = open_stream
       raise StreamFailedToOpenError unless stream
@@ -121,20 +148,59 @@ module Quicsilver
       "#{@hostname}:#{@port}"
     end
 
+    # :nodoc:
+    def open_connection
+      return self if @connected
+
+      Quicsilver.open_connection
+      config = Quicsilver.create_configuration(@unsecure)
+      raise ConnectionError, "Failed to create configuration" if config.nil?
+
+      start_connection(config)
+      @connected = true
+      @connection_start_time = Time.now
+      send_control_stream
+      Quicsilver.event_loop.start
+
+      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 (stream_id & 0x02) != 0 && (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)
+          (@response_buffers[stream_id] ||= "".b) << data
 
         when "RECEIVE_FIN"
           event = Transport::StreamEvent.new(data, "RECEIVE_FIN")
 
           buffer = @response_buffers.delete(stream_id)
-          full_data = (buffer&.string || "".b) + event.data
+          full_data = (buffer || "".b) + event.data
 
           response_parser = Protocol::ResponseParser.new(full_data, max_body_size: @max_body_size,
             max_header_size: @max_header_size)
@@ -167,6 +233,11 @@ module Quicsilver
 
     private
 
+    def ensure_connected!
+      return if @connected
+      open_connection
+    end
+
     def start_connection(config)
       connection_handle, context_handle = create_connection
       unless Quicsilver.start_connection(connection_handle, config, @hostname, @port)
@@ -205,7 +276,6 @@ module Quicsilver
       @control_stream = open_unidirectional_stream
       @control_stream.send(Protocol.build_control_stream)
 
-      # RFC 9204: QPACK encoder (0x02) and decoder (0x03) streams
       [0x02, 0x03].each do |type|
         stream = open_unidirectional_stream
         stream.send([type].pack("C"))
@@ -246,5 +316,34 @@ module Quicsilver
         raise Error, "Failed to send request"
       end
     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
+        raise Protocol::FrameError, "Duplicate control stream" if @control_stream_id
+        @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
   end
 end

data/lib/quicsilver/client/connection_pool.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  class Client
+    # Thread-safe pool of connected Client instances, keyed by (host, port).
+    # Idle connections are reused automatically. Stale ones are evicted at checkout.
+    #
+    #   Quicsilver::Client.get("example.com", 4433, "/users")
+    #
+    class ConnectionPool
+      attr_reader :max_size, :idle_timeout
+
+      DEFAULT_MAX_SIZE = 4
+      DEFAULT_IDLE_TIMEOUT = 60 # seconds
+
+      def initialize(max_size: DEFAULT_MAX_SIZE, idle_timeout: DEFAULT_IDLE_TIMEOUT)
+        @max_size = max_size
+        @idle_timeout = idle_timeout
+        @pools = {} # "host:port" => [{ client:, checked_out: }]
+        @mutex = Mutex.new
+      end
+
+      # Check out a connected Client. Reuses an idle one or creates a new one.
+      def checkout(hostname, port, **options)
+        key = "#{hostname}:#{port}"
+
+        @mutex.synchronize do
+          entries = @pools[key] ||= []
+
+          # Evict dead/stale/draining
+          entries.reject! do |e|
+            if !e[:checked_out] && (!e[:client].connected? || e[:client].draining? || e[:last_used] < Time.now - @idle_timeout)
+              e[:client].close_connection
+              true
+            end
+          end
+
+          # Reuse an idle client (skip draining ones)
+          idle = entries.find { |e| !e[:checked_out] && e[:client].connected? && !e[:client].draining? }
+          if idle
+            idle[:checked_out] = true
+            idle[:last_used] = Time.now
+            return idle[:client]
+          end
+
+          if entries.size >= @max_size
+            raise ConnectionError, "Connection pool full for #{key} (max: #{@max_size})"
+          end
+        end
+
+        # Create outside the lock (blocking I/O)
+        client = Client.new(hostname, port, **options)
+        client.open_connection
+
+        @mutex.synchronize do
+          (@pools[key] ||= []) << { client: client, checked_out: true, last_used: Time.now }
+        end
+
+        client
+      end
+
+      # Return a Client to the pool.
+      def checkin(client)
+        key = "#{client.hostname}:#{client.port}"
+
+        @mutex.synchronize do
+          entries = @pools[key]
+          return unless entries
+
+          entry = entries.find { |e| e[:client].equal?(client) }
+          return unless entry
+
+          if client.connected?
+            entry[:checked_out] = false
+            entry[:last_used] = Time.now
+          else
+            entries.delete(entry)
+            client.close_connection
+            @pools.delete(key) if entries.empty?
+          end
+        end
+      end
+
+      # Close all clients.
+      def close
+        @mutex.synchronize do
+          @pools.each_value do |entries|
+            entries.each { |e| e[:client].close_connection }
+          end
+          @pools.clear
+        end
+      end
+
+      # Total clients in the pool, optionally filtered by host:port.
+      def size(host = nil, port = nil)
+        @mutex.synchronize do
+          if host && port
+            (@pools["#{host}:#{port}"] || []).size
+          else
+            @pools.values.sum(&:size)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/quicsilver/protocol/adapter.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "protocol/http/request"
+require "protocol/http/response"
+require "protocol/http/headers"
+require_relative "stream_input"
+require_relative "stream_output"
+
+module Quicsilver
+  module Protocol
+    # Converts between QUIC/HTTP/3 frames and protocol-http Request/Response
+    # objects. This enables integration with Falcon and any other server
+    # built on protocol-http.
+    #
+    # Usage:
+    #   adapter = Protocol::Adapter.new(app)
+    #   request, body = adapter.build_request(parsed_headers)
+    #   body.write(chunk)               # feed body data
+    #   body.close_write                # signal end of body
+    #   response = adapter.call(request)
+    #   adapter.send_response(response, writer)
+    #
+    class Adapter
+      VERSION = "HTTP/3"
+
+      def initialize(app)
+        @app = app
+        @qpack_encoder = Quicsilver::Protocol::Qpack::Encoder.new
+      end
+
+      # Build a Protocol::HTTP::Request from parsed HTTP/3 headers.
+      #
+      # Returns [request, body] where body is a Protocol::StreamInput that
+      # the transport feeds RECEIVE chunks into.
+      #
+      # @param headers [Hash] Parsed headers from RequestParser (includes pseudo-headers).
+      # @return [Array(Protocol::HTTP::Request, Protocol::StreamInput)] request and body.
+      #   Body is nil for bodyless methods (GET, HEAD, TRACE).
+      #   Caller feeds RECEIVE data into body via write(), then close_write on FIN.
+      def build_request(headers)
+        method = headers[":method"]
+        scheme = headers[":scheme"] || "https"
+        authority = headers[":authority"]
+        path = headers[":path"]
+        protocol = headers[":protocol"]
+        content_length = headers["content-length"]&.to_i
+
+        protocol_headers = ::Protocol::HTTP::Headers.new
+        headers.each do |name, value|
+          next if name.start_with?(":")
+          protocol_headers.add(name, value)
+        end
+
+        body = unless bodyless_request?(method)
+          Protocol::StreamInput.new(content_length)
+        end
+
+        request = ::Protocol::HTTP::Request.new(
+          scheme, authority, method, path, VERSION,
+          protocol_headers, body, protocol
+        )
+
+        [request, body]
+      end
+
+      # Send a Protocol::HTTP::Response via a transport writer.
+      #
+      # Encodes the response headers as an HTTP/3 HEADERS frame, then streams
+      # the response body as DATA frames via Protocol::StreamOutput.
+      #
+      # @param response [Protocol::HTTP::Response] The response to send.
+      # @param writer [#call] Transport writer — accepts (data, fin) for sending bytes.
+      # @param head_request [Boolean] Whether this was a HEAD request.
+      # @return [void]
+      def send_response(response, writer, head_request: false)
+        status = response.status
+        headers = response.headers
+        trailers = extract_trailers(headers)
+        headers_hash = response_headers_hash(headers)
+        body = response.body
+
+        if body.nil? || head_request
+          send_headers_only(status, headers_hash, writer, trailers: trailers)
+        elsif body.respond_to?(:read)
+          stream_response(status, headers_hash, body, writer, trailers: trailers)
+        else
+          buffer_response(status, headers_hash, body, writer, trailers: trailers)
+        end
+      end
+
+      # Call the protocol-http application with the request.
+      #
+      # @param request [Protocol::HTTP::Request]
+      # @return [Protocol::HTTP::Response]
+      def call(request)
+        @app.call(request)
+      end
+
+      private
+
+      # Methods where a body has no defined semantics (RFC 9110 §9.3.1, §9.3.2, §9.3.8).
+      # GET and HEAD SHOULD NOT have a body. TRACE MUST NOT.
+      # DELETE, OPTIONS, CONNECT can all have meaningful bodies.
+      BODYLESS_METHODS = %w[GET HEAD TRACE].freeze
+
+      def bodyless_request?(method)
+        BODYLESS_METHODS.include?(method)
+      end
+
+      # No body — send HEADERS with FIN
+      def send_headers_only(status, headers, writer, trailers: nil)
+        encoder = Quicsilver::Protocol::ResponseEncoder.new(status, headers, [], trailers: trailers)
+        writer.call(encoder.encode, true)
+      end
+
+      # Streaming body (protocol-http Body::Readable) — send HEADERS, then
+      # stream DATA frames as chunks arrive. Used by Falcon mode.
+      def stream_response(status, headers, body, writer, trailers: nil)
+        has_trailers = trailers&.any?
+        writer.call(build_headers_frame(status, headers), false)
+        Protocol::StreamOutput.new(body, &writer).stream(send_fin: !has_trailers)
+        writer.call(build_trailer_frame(trailers), true) if has_trailers
+      end
+
+      # Buffered body (Rack array or enumerable) — encode everything and send.
+      def buffer_response(status, headers, body, writer, trailers: nil)
+        parts = body.respond_to?(:each) ? body : [body.to_s]
+        encoder = Quicsilver::Protocol::ResponseEncoder.new(status, headers, parts, trailers: trailers)
+        writer.call(encoder.encode, true)
+      ensure
+        body.close if body.respond_to?(:close)
+      end
+
+      # Extract trailers from Protocol::HTTP::Headers if present.
+      # Returns a Hash or nil.
+      def extract_trailers(headers)
+        return nil unless headers.respond_to?(:trailer?) && headers.trailer?
+
+        result = {}
+        headers.trailer.each do |name, value|
+          result[name] = value
+        end
+        result
+      end
+
+      # Convert Protocol::HTTP::Headers to a plain Hash for ResponseEncoder.
+      # Only includes headers, not trailers.
+      def response_headers_hash(headers)
+        return {} unless headers
+
+        headers.header.to_h
+      end
+
+      # Build an HTTP/3 HEADERS frame from key-value pairs
+      def build_qpack_frame(pairs)
+        encoded = @qpack_encoder.encode(pairs)
+        Quicsilver::Protocol.encode_varint(Quicsilver::Protocol::FRAME_HEADERS) +
+          Quicsilver::Protocol.encode_varint(encoded.bytesize) +
+          encoded
+      end
+
+      # Build a response HEADERS frame (with :status pseudo-header)
+      def build_headers_frame(status, headers)
+        pairs = [[":status", status.to_s]]
+        headers.each { |name, value| pairs << [name.to_s.downcase, value.to_s] }
+        build_qpack_frame(pairs)
+      end
+
+      # Build a trailer HEADERS frame
+      def build_trailer_frame(trailers)
+        pairs = trailers.map { |name, value| [name.to_s.downcase, value.to_s] }
+        build_qpack_frame(pairs)
+      end
+    end
+  end
+end

data/lib/quicsilver/protocol/control_stream_parser.rb

@@ -0,0 +1,106 @@
+# 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
+
+      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
+
+          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
+
+        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
+      end
+
+      private
+
+      # Override in includer to store settings. Default: no-op.
+      def on_settings_received(settings)
+      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