quicsilver 0.2.0 → 0.3.0

data/lib/quicsilver/client/client.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module Quicsilver
+  class Client
+    attr_reader :hostname, :port, :unsecure, :connection_timeout, :request_timeout
+
+    AlreadyConnectedError = Class.new(StandardError)
+    NotConnectedError = Class.new(StandardError)
+    StreamFailedToOpenError = 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 = {})
+      @hostname = hostname
+      @port = port
+      @unsecure = options.fetch(:unsecure, true)
+      @connection_timeout = options.fetch(:connection_timeout, DEFAULT_CONNECTION_TIMEOUT)
+      @request_timeout = options.fetch(:request_timeout, DEFAULT_REQUEST_TIMEOUT)
+      @max_body_size = options[:max_body_size]
+      @max_header_size = options[:max_header_size]
+
+      @connection_data = nil
+      @connected = false
+      @connection_start_time = nil
+
+      @response_buffers = {}
+      @pending_requests = {}  # handle => Request
+      @mutex = Mutex.new
+    end
+
+    def connect
+      raise AlreadyConnectedError 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)
+    end
+
+    def disconnect
+      return unless @connection_data
+
+      @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
+    end
+
+    # HTTP methods - block gives you request control, no block returns response directly
+    #
+    #   # Simple (blocking)
+    #   response = client.get("/users")
+    #
+    #   # With control
+    #   client.get("/users") do |req|
+    #     req.cancel if should_abort?
+    #     req.response
+    #   end
+    #
+    %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
+      end
+    end
+
+    # Build and send request, returns Request object for lifecycle control
+    def build_request(method, path, headers: {}, body: nil)
+      raise NotConnectedError unless @connected
+
+      stream = open_stream
+      raise StreamFailedToOpenError unless stream
+
+      request = Request.new(self, stream)
+      @mutex.synchronize { @pending_requests[stream.handle] = request }
+
+      send_to_stream(stream, method, path, headers, body)
+
+      request
+    end
+
+    def connected?
+      @connected && @connection_data && connection_alive?
+    end
+
+    def connection_info
+      info = @connection_data ? Quicsilver.connection_status(@connection_data[1]) : {}
+      info.merge(hostname: @hostname, port: @port, uptime: connection_uptime)
+    end
+
+    def connection_uptime
+      return 0 unless @connection_start_time
+      Time.now - @connection_start_time
+    end
+
+    def authority
+      "#{@hostname}:#{@port}"
+    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)
+
+      @mutex.synchronize do
+        case event
+        when "RECEIVE"
+          (@response_buffers[stream_id] ||= StringIO.new("".b)).write(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)
+
+        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")
+
+        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")
+        end
+      end
+    rescue => e
+      Quicsilver.logger.error("Error handling client stream: #{e.class} - #{e.message}")
+      Quicsilver.logger.debug(e.backtrace.first(5).join("\n"))
+    end
+
+    private
+
+    def start_connection(config)
+      connection_handle, context_handle = create_connection
+      unless Quicsilver.start_connection(connection_handle, config, @hostname, @port)
+        cleanup_failed_connection
+        raise ConnectionError, "Failed to start connection"
+      end
+
+      result = Quicsilver.wait_for_connection(context_handle, @connection_timeout)
+      handle_connection_result(result)
+    end
+
+    def create_connection
+      @connection_data = Quicsilver.create_connection(self)
+      raise ConnectionError, "Failed to create connection" if @connection_data.nil?
+
+      @connection_data
+    end
+
+    def cleanup_failed_connection
+      Quicsilver.close_connection_handle(@connection_data) if @connection_data
+      @connection_data = nil
+      @connected = false
+    end
+
+    def open_stream
+      handle = Quicsilver.open_stream(@connection_data, false)
+      Transport::Stream.new(handle)
+    end
+
+    def open_unidirectional_stream
+      handle = Quicsilver.open_stream(@connection_data, true)
+      Transport::Stream.new(handle)
+    end
+
+    def send_control_stream
+      @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"))
+      end
+    end
+
+    def handle_connection_result(result)
+      if result.key?("error")
+        cleanup_failed_connection
+        raise ConnectionError, "Connection failed: status 0x#{result['status'].to_s(16)}, code: #{result['code']}"
+      elsif result.key?("timeout")
+        cleanup_failed_connection
+        raise TimeoutError, "Connection timed out after #{@connection_timeout}ms"
+      end
+    end
+
+    def connection_alive?
+      return false unless (info = Quicsilver.connection_status(@connection_data[1]))
+      info["connected"] && !info["failed"]
+    rescue
+      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
+
+      result = stream.send(encoded_response, fin: true)
+
+      unless result
+        @mutex.synchronize { @pending_requests.delete(stream.handle) }
+        raise Error, "Failed to send request"
+      end
+    end
+  end
+end

data/lib/quicsilver/client/request.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  class Client
+    class Request
+      attr_reader :stream, :status
+
+      CancelledError = Class.new(StandardError)
+
+      class ResetError < StandardError
+        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
+        @mutex = Mutex.new
+        @response = nil
+      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 Hash
+            if result[:error]
+              @status = :error
+              raise ResetError.new(result[:message] || "Stream reset by peer", result[:error_code])
+            else
+              @status = :completed
+              @response = result
+            end
+          end
+        end
+
+        @response
+      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)
+          @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
+
+      # Called by Client when response arrives
+      def complete(response) # :nodoc:
+        @queue.push(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 })
+      end
+    end
+  end
+end

data/lib/quicsilver/{http3.rb → protocol/frames.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Quicsilver
-  module HTTP3
+  module Protocol
     # HTTP/3 Frame Types (RFC 9114)
     FRAME_DATA = 0x00
     FRAME_HEADERS = 0x01
@@ -11,6 +11,52 @@ module Quicsilver
     FRAME_GOAWAY = 0x07
     FRAME_MAX_PUSH_ID = 0x0d
 
+    # Frame types forbidden on request streams (RFC 9114 Section 7.2.4, 7.2.6, 7.2.7)
+    CONTROL_ONLY_FRAMES = [FRAME_CANCEL_PUSH, FRAME_SETTINGS, FRAME_GOAWAY, FRAME_MAX_PUSH_ID].freeze
+
+    # HTTP/3 Error Codes (RFC 9114 Section 8.1)
+    H3_NO_ERROR = 0x100
+    H3_GENERAL_PROTOCOL_ERROR = 0x101
+    H3_INTERNAL_ERROR = 0x102
+    H3_STREAM_CREATION_ERROR = 0x103
+    H3_CLOSED_CRITICAL_STREAM = 0x104
+    H3_FRAME_UNEXPECTED = 0x105
+    H3_FRAME_ERROR = 0x106
+    H3_EXCESSIVE_LOAD = 0x107
+    H3_ID_ERROR = 0x108
+    H3_SETTINGS_ERROR = 0x109
+    H3_MISSING_SETTINGS = 0x10a
+    H3_REQUEST_REJECTED = 0x10b
+    H3_REQUEST_CANCELLED = 0x10c
+    H3_REQUEST_INCOMPLETE = 0x10d
+    H3_MESSAGE_ERROR = 0x10e
+    H3_CONNECT_ERROR = 0x10f
+    H3_VERSION_FALLBACK = 0x110
+
+    # QPACK Error Codes (RFC 9204 Section 6)
+    QPACK_DECOMPRESSION_FAILED = 0x200
+    QPACK_ENCODER_STREAM_ERROR = 0x201
+    QPACK_DECODER_STREAM_ERROR = 0x202
+
+    # Protocol errors that carry an HTTP/3 error code for CONNECTION_CLOSE / RESET_STREAM.
+    # FrameError → connection error (CONNECTION_CLOSE)
+    # MessageError → stream error (RESET_STREAM) on request streams
+    class FrameError < StandardError
+      attr_reader :error_code
+      def initialize(msg = nil, error_code: H3_FRAME_UNEXPECTED)
+        @error_code = error_code
+        super(msg)
+      end
+    end
+
+    class MessageError < StandardError
+      attr_reader :error_code
+      def initialize(msg = nil, error_code: H3_MESSAGE_ERROR)
+        @error_code = error_code
+        super(msg)
+      end
+    end
+
     # QPACK Static Table Indices (RFC 9204 Appendix A)
     STATIC_TABLE = [
       [':authority', ''],                                      # 0
@@ -70,8 +116,8 @@ module Quicsilver
       ['content-type', 'text/plain;charset=utf-8'],            # 54
       ['range', 'bytes=0-'],                                   # 55
       ['strict-transport-security', 'max-age=31536000'],       # 56
-      ['strict-transport-security', 'max-age=31536000; includesubdomains'], # 57
-      ['strict-transport-security', 'max-age=31536000; includesubdomains; preload'], # 58
+      ['strict-transport-security', 'max-age=31536000; includeSubDomains'], # 57
+      ['strict-transport-security', 'max-age=31536000; includeSubDomains; preload'], # 58
       ['vary', 'accept-encoding'],                             # 59
       ['vary', 'origin'],                                      # 60
       ['x-content-type-options', 'nosniff'],                   # 61
@@ -134,22 +180,40 @@ module Quicsilver
     QPACK_CONTENT_TYPE_JSON = 46
     QPACK_CONTENT_TYPE_PLAIN = 53
 
+    # Maximum stream ID for initial GOAWAY (2^62 - 4, per RFC 9114)
+    MAX_STREAM_ID = (2**62) - 4
+
     class << self
+      # Precomputed varint encodings for single-byte values (0-63)
+      VARINT_SMALL = Array.new(64) { |v| [v].pack('C').freeze }.freeze
+      VARINT_MED = Array.new(16384 - 64) { |i| v = i + 64; [0x40 | (v >> 8), v & 0xFF].pack('C*').freeze }.freeze
+
+      # Cache for large varint encodings (values >= 16384)
+      VARINT_LARGE_CACHE = {}
+      VARINT_LARGE_CACHE_MAX = 256
+
       # Encode variable-length integer
       def encode_varint(value)
-        case value
-        when 0..63
-          [value].pack('C')
-        when 64..16383
-          [0x40 | (value >> 8), value & 0xFF].pack('C*')
-        when 16384..1073741823
-          [0x80 | (value >> 24), (value >> 16) & 0xFF,
-          (value >> 8) & 0xFF, value & 0xFF].pack('C*')
+        if value < 64
+          VARINT_SMALL[value]
+        elsif value < 16384
+          VARINT_MED[value - 64]
         else
-          [0xC0 | (value >> 56), (value >> 48) & 0xFF,
-          (value >> 40) & 0xFF, (value >> 32) & 0xFF,
-          (value >> 24) & 0xFF, (value >> 16) & 0xFF,
-          (value >> 8) & 0xFF, value & 0xFF].pack('C*')
+          cached = VARINT_LARGE_CACHE[value]
+          return cached if cached
+
+          result = if value < 1073741824
+            [0x80 | (value >> 24), (value >> 16) & 0xFF,
+            (value >> 8) & 0xFF, value & 0xFF].pack('C*').freeze
+          else
+            [0xC0 | (value >> 56), (value >> 48) & 0xFF,
+            (value >> 40) & 0xFF, (value >> 32) & 0xFF,
+            (value >> 24) & 0xFF, (value >> 16) & 0xFF,
+            (value >> 8) & 0xFF, value & 0xFF].pack('C*').freeze
+          end
+
+          VARINT_LARGE_CACHE[value] = result if VARINT_LARGE_CACHE.size < VARINT_LARGE_CACHE_MAX
+          result
         end
       end
 
@@ -169,7 +233,10 @@ module Quicsilver
       # Build control stream data
       def build_control_stream
         stream_type = [0x00].pack('C')  # Control stream type
-        settings = build_settings_frame({})
+        settings = build_settings_frame({
+          0x01 => 0,  # QPACK_MAX_TABLE_CAPACITY = 0 (no dynamic table)
+          0x07 => 0   # QPACK_BLOCKED_STREAMS = 0
+        })
 
         stream_type + settings
       end
@@ -184,32 +251,71 @@ module Quicsilver
         frame_type + frame_length + payload
       end
 
-      # Maximum stream ID for initial GOAWAY (2^62 - 4, per RFC 9114)
-      MAX_STREAM_ID = (2**62) - 4
+      # Cache for decode_varint_str: (object_id << 16 | offset) → [value, consumed]
+      VARINT_STR_CACHE = {}
+      VARINT_STR_CACHE_MAX = 256
+
+      # Decode variable-length integer from a String using getbyte (no array needed)
+      # Returns [value, bytes_consumed]
+      def decode_varint_str(str, offset = 0)
+        cache_key = (str.object_id << 16) | offset
+        cached = VARINT_STR_CACHE[cache_key]
+        return cached if cached
+
+        first = str.getbyte(offset)
+        return [0, 0] unless first
+
+        if first < 0x40
+          result = VARINT_DECODE_SMALL[first]
+        else
+          prefix = (first & 0xC0) >> 6
+          length = 1 << prefix
+
+          return [0, 0] if offset + length > str.bytesize
+
+          result = case prefix
+          when 0
+            [first & 0x3F, 1]
+          when 1
+            [(first & 0x3F) << 8 | str.getbyte(offset + 1), 2]
+          when 2
+            [(first & 0x3F) << 24 | str.getbyte(offset + 1) << 16 |
+            str.getbyte(offset + 2) << 8 | str.getbyte(offset + 3), 4]
+          else
+            [(first & 0x3F) << 56 | str.getbyte(offset + 1) << 48 |
+            str.getbyte(offset + 2) << 40 | str.getbyte(offset + 3) << 32 |
+            str.getbyte(offset + 4) << 24 | str.getbyte(offset + 5) << 16 |
+              str.getbyte(offset + 6) << 8 | str.getbyte(offset + 7), 8]
+          end
+        end
+
+        VARINT_STR_CACHE[cache_key] = result if VARINT_STR_CACHE.size < VARINT_STR_CACHE_MAX
+        result
+      end
+
+      # Precomputed decode results for single-byte varints (0-63)
+      VARINT_DECODE_SMALL = Array.new(64) { |v| [v, 1].freeze }.freeze
 
       # Decode variable-length integer (RFC 9000)
       # Returns [value, bytes_consumed]
       def decode_varint(bytes, offset = 0)
-        return [0, 0] if offset >= bytes.size
-
         first = bytes[offset]
-        return [0, 0] if first.nil?
+        return [0, 0] unless first
 
-        prefix = (first & 0xC0) >> 6 # Extract 2 MSB
-        length = 1 << prefix # 1, 2, 4, or 8 bytes
+        # Fast path for single-byte varints (most common: frame types, small lengths)
+        return VARINT_DECODE_SMALL[first] if first < 0x40
 
-        # Check if we have enough bytes
+        prefix = (first & 0xC0) >> 6
+        length = 1 << prefix
         return [0, 0] if offset + length > bytes.size
 
         case prefix
-        when 0
-          [first & 0x3F, 1]
         when 1
           [(first & 0x3F) << 8 | bytes[offset + 1], 2]
         when 2
           [(first & 0x3F) << 24 | bytes[offset + 1] << 16 |
           bytes[offset + 2] << 8 | bytes[offset + 3], 4]
-        else # when 3
+        else # 3
           [(first & 0x3F) << 56 | bytes[offset + 1] << 48 |
           bytes[offset + 2] << 40 | bytes[offset + 3] << 32 |
           bytes[offset + 4] << 24 | bytes[offset + 5] << 16 |
@@ -219,4 +325,3 @@ module Quicsilver
     end
   end
 end
-