quicsilver 0.5.0-x86_64-linux

data/lib/quicsilver/client/connection_pool.rb

@@ -0,0 +1,202 @@
+# 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, :mode
+
+      DEFAULT_MAX_SIZE = 4
+      DEFAULT_IDLE_TIMEOUT = 60 # seconds
+      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
+        @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)
+        @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
+          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
+
+            # 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
+
+            # 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
+
+        # 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 }
+          @keys[client] = key
+        end
+
+        client
+      end
+
+      # 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)
+        return if @mode == :shared
+
+        @mutex.synchronize do
+          key = @keys[client]
+          entries = key && @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)
+            @keys.delete(client)
+            client.close_connection
+            @pools.delete(key) if entries.empty?
+          end
+
+          @condition.broadcast  # wake threads waiting for a connection
+        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
+          @keys.clear
+        end
+      end
+
+      # 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
+            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

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  class Client
+    class Request
+      attr_reader :stream, :status
+
+      class ResetError < Quicsilver::Error
+        attr_reader :error_code
+
+        def initialize(message, error_code = nil)
+          super(message)
+          @error_code = error_code
+        end
+      end
+
+      def initialize(client, stream)
+        @client = client
+        @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
+      # Returns response hash { status:, headers:, body: }
+      # Raises TimeoutError, CancelledError, or ResetError
+      def response(timeout: nil)
+        timeout ||= @client.request_timeout
+        return @response if @status == :completed
+
+        result = @queue.pop(timeout: timeout)
+
+        @mutex.synchronize do
+          case result
+          when nil
+            raise Quicsilver::TimeoutError, "Request timeout after #{timeout}s"
+          when Response
+            @status = :completed
+            @response = result
+          when Hash
+            # 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.abort(error_code)
+          @status = :cancelled
+        end
+        true
+      rescue => e
+        Quicsilver.logger.error("Failed to cancel request: #{e.message}")
+        false
+      end
+
+      def pending?
+        @status == :pending
+      end
+
+      def completed?
+        @status == :completed
+      end
+
+      def cancelled?
+        @status == :cancelled
+      end
+
+      # 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
+        error = { error: true, error_code: error_code, message: message }
+        @queue.push(error)
+        @streaming_queue.push(error)
+      end
+    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

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+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
+    # 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.
+      # @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"]
+        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
+
+        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,
+          peer: peer,
+          transport_context: transport_context,
+          rack_context: rack_context
+        )
+
+        [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_header_fields(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
+
+      # 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_headers_frame(status, headers)
+        pairs = [[":status", status.to_s]]
+        headers.each { |name, value| pairs << [name.to_s.downcase, value.to_s] }
+        Protocol.build_headers_frame(pairs, encoder: @qpack_encoder)
+      end
+
+      def build_trailer_frame(trailers)
+        pairs = trailers.map { |name, value| [name.to_s.downcase, value.to_s] }
+        Protocol.build_headers_frame(pairs, encoder: @qpack_encoder)
+      end
+    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