quicsilver 0.4.0 → 0.5.0

data/lib/quicsilver/client/connection_pool.rb

@@ -8,43 +8,80 @@ module Quicsilver
     #   Quicsilver::Client.get("example.com", 4433, "/users")
     #
     class ConnectionPool
-      attr_reader :max_size, :idle_timeout
+      attr_reader :max_size, :idle_timeout, :mode
 
       DEFAULT_MAX_SIZE = 4
       DEFAULT_IDLE_TIMEOUT = 60 # seconds
-
-      def initialize(max_size: DEFAULT_MAX_SIZE, idle_timeout: DEFAULT_IDLE_TIMEOUT)
+      DEFAULT_CHECKOUT_TIMEOUT = 5 # seconds
+
+      # @param mode [:exclusive, :shared] Pool strategy.
+      #   :shared (default) — one connection per host, all threads share it via
+      #     QUIC stream multiplexing. 5x faster, one TLS handshake per host.
+      #   :exclusive — one connection per checkout, like ActiveRecord. Use for
+      #     maintenance tasks that need isolation or servers with low stream limits.
+      def initialize(max_size: DEFAULT_MAX_SIZE, idle_timeout: DEFAULT_IDLE_TIMEOUT, checkout_timeout: DEFAULT_CHECKOUT_TIMEOUT, mode: :shared)
         @max_size = max_size
         @idle_timeout = idle_timeout
-        @pools = {} # "host:port" => [{ client:, checked_out: }]
+        @checkout_timeout = checkout_timeout
+        @mode = mode
+        @pools = {} # connection key => [{ client:, checked_out: }]
+        @keys = {}.compare_by_identity # client => the key it was pooled under
         @mutex = Mutex.new
+        @condition = ConditionVariable.new
       end
 
+      # Options that change the connection itself, so a pooled connection built
+      # with one set must never be handed to a caller asking for another.
+      # unsecure is the important one: it disables certificate validation.
+      CONNECTION_OPTIONS = %i[
+        unsecure
+        datagram_receive_enabled
+        reliable_reset_enabled
+        transport_cibir_id
+        idle_timeout_ms
+      ].freeze
+
       # Check out a connected Client. Reuses an idle one or creates a new one.
+      # In :exclusive mode, blocks with timeout if pool is full.
+      # In :shared mode, returns the shared connection (all threads use one connection).
       def checkout(hostname, port, **options)
-        key = "#{hostname}:#{port}"
+        @mode == :shared ? checkout_shared(hostname, port, **options) : checkout_exclusive(hostname, port, **options)
+      end
+
+      private def checkout_exclusive(hostname, port, **options)
+        key = connection_key(hostname, port, options)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @checkout_timeout
 
         @mutex.synchronize do
-          entries = @pools[key] ||= []
+          loop 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
 
-          # 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
+            # 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
-          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
+            # Room to create a new connection
+            break if entries.size < @max_size
 
-          if entries.size >= @max_size
-            raise ConnectionError, "Connection pool full for #{key} (max: #{@max_size})"
+            # Pool full — wait for a checkin
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            if remaining <= 0
+              raise ConnectionError,
+                "Connection pool full for #{hostname}:#{port} (waited #{@checkout_timeout}s, max: #{@max_size})"
+            end
+            @condition.wait(@mutex, remaining)
           end
         end
 
@@ -54,17 +91,64 @@ module Quicsilver
 
         @mutex.synchronize do
           (@pools[key] ||= []) << { client: client, checked_out: true, last_used: Time.now }
+          @keys[client] = key
         end
 
         client
       end
 
-      # Return a Client to the pool.
+      # Shared mode: one connection per host, all threads share it.
+      # Each thread opens its own QUIC stream on the shared connection.
+      # No checkout/checkin semantics — the connection is never "owned".
+      private def checkout_shared(hostname, port, **options)
+        key = connection_key(hostname, port, options)
+
+        @mutex.synchronize do
+          entry = @pools[key]&.first
+          if entry && entry[:client].connected? && !entry[:client].draining?
+            entry[:last_used] = Time.now
+            return entry[:client]
+          end
+          # Remove stale entry
+          @pools.delete(key) if entry
+        end
+
+        # Create outside the lock (blocking I/O)
+        client = Client.new(hostname, port, **options)
+        client.open_connection
+
+        @mutex.synchronize do
+          # Double-check — another thread may have created one while we were connecting
+          existing = @pools[key]&.first
+          if existing && existing[:client].connected? && !existing[:client].draining?
+            client.close_connection
+            existing[:last_used] = Time.now
+            return existing[:client]
+          end
+          @pools[key] = [{ client: client, checked_out: false, last_used: Time.now }]
+        end
+
+        client
+      end
+
+      # Block-based checkout — auto-checkin on completion or error.
+      #
+      #   pool.with("example.com", 443) { |client| client.get("/") }
+      #
+      def with(hostname, port, **options)
+        client = checkout(hostname, port, **options)
+        yield client
+      ensure
+        checkin(client) if client
+      end
+
+      # Return a Client to the pool. No-op in shared mode.
       def checkin(client)
-        key = "#{client.hostname}:#{client.port}"
+        return if @mode == :shared
 
         @mutex.synchronize do
-          entries = @pools[key]
+          key = @keys[client]
+          entries = key && @pools[key]
           return unless entries
 
           entry = entries.find { |e| e[:client].equal?(client) }
@@ -75,9 +159,12 @@ module Quicsilver
             entry[:last_used] = Time.now
           else
             entries.delete(entry)
+            @keys.delete(client)
             client.close_connection
             @pools.delete(key) if entries.empty?
           end
+
+          @condition.broadcast  # wake threads waiting for a connection
         end
       end
 
@@ -88,19 +175,28 @@ module Quicsilver
             entries.each { |e| e[:client].close_connection }
           end
           @pools.clear
+          @keys.clear
         end
       end
 
-      # Total clients in the pool, optionally filtered by host:port.
+      # Total clients in the pool, optionally filtered by host and port across
+      # every option set pooled for them.
       def size(host = nil, port = nil)
         @mutex.synchronize do
           if host && port
-            (@pools["#{host}:#{port}"] || []).size
+            prefix = "#{host}:#{port}\0"
+            @pools.sum { |key, entries| key.start_with?(prefix) ? entries.size : 0 }
           else
             @pools.values.sum(&:size)
           end
         end
       end
+
+      private def connection_key(hostname, port, options)
+        defaults = Client::DEFAULT_CONNECTION_OPTIONS
+        identity = CONNECTION_OPTIONS.map { |name| options.fetch(name, defaults[name]).inspect }
+        "#{hostname}:#{port}\0#{identity.join("\0")}"
+      end
     end
   end
 end

data/lib/quicsilver/client/request.rb

@@ -5,9 +5,7 @@ module Quicsilver
     class Request
       attr_reader :stream, :status
 
-      CancelledError = Class.new(StandardError)
-
-      class ResetError < StandardError
+      class ResetError < Quicsilver::Error
         attr_reader :error_code
 
         def initialize(message, error_code = nil)
@@ -21,8 +19,42 @@ module Quicsilver
         @stream = stream
         @status = :pending
         @queue = Queue.new
+        @streaming_queue = Queue.new
         @mutex = Mutex.new
         @response = nil
+        @streaming_response = nil
+        @streaming_requested = false
+      end
+
+      # Whether the caller has opted into streaming via streaming_response.
+      def streaming_requested?
+        @streaming_requested
+      end
+
+      # Block until streaming response headers arrive.
+      # Returns a StreamingResponse with status, headers, and a readable body.
+      # Body data arrives incrementally — call body.read in a loop.
+      #
+      #   streaming = request.streaming_response(timeout: 10)
+      #   streaming.status   # => 200
+      #   streaming.headers  # => {"content-type" => "video/mp4"}
+      #   while (chunk = streaming.body.read)
+      #     file.write(chunk)
+      #   end
+      #
+      def streaming_response(timeout: nil)
+        timeout ||= @client.request_timeout
+        @streaming_requested = true
+        return @streaming_response if @streaming_response
+
+        result = @streaming_queue.pop(timeout: timeout)
+        raise Quicsilver::TimeoutError, "Streaming response timeout after #{timeout}s" if result.nil?
+
+        if result.is_a?(Hash) && result[:error]
+          raise ResetError.new(result[:message] || "Stream reset", result[:error_code])
+        end
+
+        @streaming_response = result
       end
 
       # Block until response arrives or timeout
@@ -38,28 +70,55 @@ module Quicsilver
           case result
           when nil
             raise Quicsilver::TimeoutError, "Request timeout after #{timeout}s"
+          when Response
+            @status = :completed
+            @response = result
           when Hash
-            if result[:error]
-              @status = :error
-              raise ResetError.new(result[:message] || "Stream reset by peer", result[:error_code])
-            else
-              @status = :completed
-              @response = result
-            end
+            # Error hash from #fail
+            @status = :error
+            raise ResetError.new(result[:message] || "Stream reset by peer", result[:error_code])
           end
         end
 
         @response
       end
 
+      # Stream request body in chunks. Only valid when build_request was
+      # called with body: :stream.
+      #
+      #   req = client.build_request('POST', '/upload', body: :stream)
+      #   req.stream_body do |writer|
+      #     File.open('big.mp4') do |f|
+      #       while (chunk = f.read(16_384))
+      #         writer.write(chunk)
+      #       end
+      #     end
+      #   end
+      #   req.response  # wait for server response
+      #
+      def stream_body
+        writer = BodyWriter.new(@stream)
+        yield writer
+        writer.finish
+      end
+
+      # Reprioritise this stream (RFC 9218). Sends PRIORITY_UPDATE on the
+      # control stream. Can be called while the response is in flight.
+      #
+      #   req = client.build_request("GET", "/video", priority: Priority.new(urgency: 2))
+      #   req.update_priority(Priority.new(urgency: 6))  # deprioritise
+      #
+      def update_priority(priority)
+        @client.send_priority_update(@stream.stream_id, priority)
+      end
+
       # Cancel the request (sends RESET_STREAM + STOP_SENDING to server)
       # error_code defaults to H3_REQUEST_CANCELLED (0x10c)
       def cancel(error_code: Protocol::H3_REQUEST_CANCELLED)
         @mutex.synchronize do
           return false unless @status == :pending
 
-          @stream.reset(error_code)
-          @stream.stop_sending(error_code)
+          @stream.abort(error_code)
           @status = :cancelled
         end
         true
@@ -80,18 +139,51 @@ module Quicsilver
         @status == :cancelled
       end
 
-      # Called by Client when response arrives
+      # Writes request body DATA frames to a QUIC stream.
+      class BodyWriter
+        def initialize(stream)
+          @stream = stream
+          @finished = false
+        end
+
+        # Write a chunk as an HTTP/3 DATA frame.
+        def write(chunk)
+          raise "Body already finished" if @finished
+          payload = chunk.b
+          data = Protocol.encode_varint(Protocol::FRAME_DATA) +
+                 Protocol.encode_varint(payload.bytesize) +
+                 payload
+          @stream.send(data, fin: false)
+        end
+
+        # Send FIN to close the request body. Called automatically
+        # at the end of stream_body.
+        def finish
+          return if @finished
+          @finished = true
+          @stream.send("".b, fin: true)
+        end
+      end
+
+      # Called by Client when buffered response arrives
       def complete(response) # :nodoc:
         @queue.push(response)
       end
 
+      # Called by Client when streaming headers are parsed
+      def deliver_streaming(streaming_response) # :nodoc:
+        @streaming_queue.push(streaming_response)
+      end
+
       # Called by Client on stream reset from peer or connection close
       def fail(error_code, message = nil) # :nodoc:
         @mutex.synchronize do
           return if @status == :cancelled
           @status = :error
         end
-        @queue.push({ error: true, error_code: error_code, message: message })
+        error = { error: true, error_code: error_code, message: message }
+        @queue.push(error)
+        @streaming_queue.push(error)
       end
     end
   end

data/lib/quicsilver/errors.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  class Error < StandardError; end
+
+  # Transport errors from MsQuic. The C extension raises RuntimeError
+  # which Ruby call sites wrap into typed TransportError subclasses.
+  # Carries the MsQuic QUIC_STATUS code parsed from the error message.
+  #
+  #   rescue Quicsilver::TransportError => e
+  #     e.message  # => "StreamOpen failed, 0x1!"
+  #     e.status   # => 1 (QUIC_STATUS_INVALID_STATE / EPERM)
+  #
+  class TransportError < Error
+    attr_reader :status
+
+    def initialize(message = nil, status: 0)
+      @status = status
+      super(message)
+    end
+
+    # Parse MsQuic hex status from C extension error messages.
+    # "StreamOpen failed, 0x1!" => 0x1 (EPERM / INVALID_STATE)
+    def self.parse_status(message)
+      message&.match(/0x([0-9a-fA-F]+)/) { |m| m[1].to_i(16) } || 0
+    end
+  end
+
+  class ServerIsRunningError < Error; end
+  class ServerConfigurationError < Error; end
+  class ServerListenerError < Error; end
+  class ServerError < Error; end
+  class ConnectionError < Error; end
+  class TimeoutError < Error; end
+  class GoAwayError < Error; end
+  class StreamFailedToOpenError < TransportError; end
+  class CancelledError < Error; end
+
+end

data/lib/quicsilver/protocol/adapter.rb

@@ -3,10 +3,24 @@
 require "protocol/http/request"
 require "protocol/http/response"
 require "protocol/http/headers"
+require "protocol/http/peer"
 require_relative "stream_input"
 require_relative "stream_output"
 
 module Quicsilver
+  module Protocol
+    # HTTP/3 request with peer address from the QUIC connection.
+    class Request < ::Protocol::HTTP::Request
+      attr_reader :peer, :transport_context, :rack_context
+
+      def initialize(*args, peer: nil, transport_context: nil, rack_context: nil, **kwargs)
+        super(*args, **kwargs)
+        @peer = peer
+        @transport_context = transport_context
+        @rack_context = rack_context
+      end
+    end
+  end
   module Protocol
     # Converts between QUIC/HTTP/3 frames and protocol-http Request/Response
     # objects. This enables integration with Falcon and any other server
@@ -37,7 +51,11 @@ module Quicsilver
       # @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)
+      # @param headers [Hash] Parsed headers from RequestParser (includes pseudo-headers).
+      # @param remote_address [String, nil] Peer IP from the QUIC connection (e.g. "127.0.0.1").
+      # @param remote_port [Integer] Peer port from the QUIC connection.
+      # @param transport_context [Hash, nil] Quicsilver transport metadata for request debugging/log tags.
+      def build_request(headers, remote_address: nil, remote_port: 0, transport_context: nil, rack_context: nil)
         method = headers[":method"]
         scheme = headers[":scheme"] || "https"
         authority = headers[":authority"]
@@ -55,9 +73,16 @@ module Quicsilver
           Protocol::StreamInput.new(content_length)
         end
 
-        request = ::Protocol::HTTP::Request.new(
+        peer = if remote_address
+          ::Protocol::HTTP::Peer.new(Addrinfo.tcp(remote_address, remote_port))
+        end
+
+        request = Request.new(
           scheme, authority, method, path, VERSION,
-          protocol_headers, body, protocol
+          protocol_headers, body, protocol,
+          peer: peer,
+          transport_context: transport_context,
+          rack_context: rack_context
         )
 
         [request, body]
@@ -76,7 +101,7 @@ module Quicsilver
         status = response.status
         headers = response.headers
         trailers = extract_trailers(headers)
-        headers_hash = response_headers_hash(headers)
+        headers_hash = response_header_fields(headers)
         body = response.body
 
         if body.nil? || head_request
@@ -143,33 +168,28 @@ module Quicsilver
         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
+      # Response header name/value pairs for ResponseEncoder. Only headers, not trailers.
+      #
+      # Pairs rather than a Hash because a field can legitimately repeat, and set-cookie MUST NOT be
+      # combined (RFC 9110 §5.3). Hashing drops every repeat but the last, which silently discarded
+      # the session cookie of any Rails response that set more than one — the app still worked, it
+      # just never stayed signed in.
+      def response_header_fields(headers)
+        return [] unless headers
+
+        headers.header.each.to_a
       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)
+        Protocol.build_headers_frame(pairs, encoder: @qpack_encoder)
       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)
+        Protocol.build_headers_frame(pairs, encoder: @qpack_encoder)
       end
     end
   end

data/lib/quicsilver/protocol/capsule.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Protocol
+    module Capsule
+      DATAGRAM = 0x00
+      MAX_PAYLOAD_SIZE = 1_048_576
+
+      ParseError = Class.new(StandardError)
+      PayloadTooLarge = Class.new(ParseError)
+
+      class << self
+        def encode(type, payload)
+          payload = payload.to_s.b
+          Protocol.encode_varint(type) + Protocol.encode_varint(payload.bytesize) + payload
+        end
+
+        def parse(buffer, max_payload_size: MAX_PAYLOAD_SIZE)
+          type, type_length = Protocol.decode_varint_str(buffer, 0)
+          return unless type_length > 0
+
+          length, length_length = Protocol.decode_varint_str(buffer, type_length)
+          return unless length_length > 0
+
+          raise PayloadTooLarge, "Capsule payload too large" if length > max_payload_size
+
+          header_length = type_length + length_length
+          return if buffer.bytesize < header_length + length
+
+          payload = buffer.byteslice(header_length, length) || "".b
+          remainder = buffer.byteslice(header_length + length..-1) || "".b
+
+          [type, payload, remainder]
+        end
+      end
+    end
+  end
+end

data/lib/quicsilver/protocol/connect_stream_decoder.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "frame_parser"
+
+module Quicsilver
+  module Protocol
+    # Incrementally yields CONNECT DATA payloads without waiting for whole
+    # frames. Unknown frame payloads are skipped as bytes arrive.
+    class ConnectStreamDecoder
+      def initialize
+        @buffer = "".b
+        @frame_type = nil
+        @frame_remaining = nil
+      end
+
+      # A caller may break after a terminal capsule. Unprocessed bytes remain
+      # available to buffered? so it can reject data following that capsule.
+      def each(data)
+        @buffer << data if data
+        until @buffer.empty?
+          break unless @frame_remaining || read_frame_header
+
+          chunk = consume_payload
+          yield chunk if @frame_type == FRAME_DATA
+        end
+      end
+
+      def buffered?
+        !@buffer.empty?
+      end
+
+      def finish!
+        if buffered? || @frame_remaining
+          raise FrameError.new("Truncated HTTP/3 frame", error_code: H3_FRAME_ERROR)
+        end
+      end
+
+      def clear
+        @buffer.clear
+        @frame_remaining = nil
+      end
+
+      private
+
+      def read_frame_header
+        type, type_length = Protocol.decode_varint_str(@buffer, 0)
+        return false if type_length == 0
+        length, length_length = Protocol.decode_varint_str(@buffer, type_length)
+        return false if length_length == 0
+
+        # RFC 9114 §4.4 forbids known non-DATA frames after CONNECT,
+        # including HEADERS trailers; these are connection errors.
+        if CONTROL_ONLY_FRAME_SET.key?(type) ||
+            HTTP2_RESERVED_FRAME_SET.key?(type) ||
+            [FRAME_HEADERS, FRAME_PUSH_PROMISE, FRAME_PRIORITY_UPDATE].include?(type)
+          raise FrameError, "Frame not allowed on CONNECT"
+        end
+
+        @frame_type = type
+        @frame_remaining = length
+        @buffer = @buffer.byteslice(type_length + length_length..) || "".b
+        true
+      end
+
+      def consume_payload
+        count = [@frame_remaining, @buffer.bytesize].min
+        chunk = @buffer.byteslice(0, count)
+        @buffer = @buffer.byteslice(count..) || "".b
+        @frame_remaining -= count
+        @frame_remaining = nil if @frame_remaining.zero?
+        chunk
+      end
+    end
+  end
+end