quicsilver 0.1.0 → 0.3.0

data/lib/quicsilver/transport/connection.rb

@@ -0,0 +1,350 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Transport
+    class Connection
+      attr_reader :handle, :data, :streams
+      attr_reader :control_stream_id, :qpack_encoder_stream_id, :qpack_decoder_stream_id
+      attr_reader :server_control_stream
+
+      def initialize(handle, data)
+        @handle = handle
+        @data = data
+        @streams = {}
+        @response_buffers = {}
+        @mutex = Mutex.new
+
+        # Client's control streams (received)
+        @control_stream_id = nil
+        @qpack_encoder_stream_id = nil
+        @qpack_decoder_stream_id = nil
+
+        # Server's control stream (sent)
+        @server_control_stream = nil
+
+        @settings = {}
+        @settings_received = false
+      end
+
+      # === Setup (called after connection established) ===
+
+      def setup_http3_streams
+        # Control stream (required)
+        @server_control_stream = open_stream(unidirectional: true)
+        @server_control_stream.send(Protocol.build_control_stream)
+
+        # QPACK encoder/decoder streams
+        [0x02, 0x03].each do |type|
+          stream = open_stream(unidirectional: true)
+          stream.send([type].pack("C"))
+        end
+      end
+
+      # === Stream Management ===
+
+      def add_stream(stream)
+        @streams[stream.stream_id] = stream
+      end
+
+      def get_stream(stream_id)
+        @streams[stream_id]
+      end
+
+      def remove_stream(stream_id)
+        @streams.delete(stream_id)
+      end
+
+      def track_client_stream(stream_id)
+        @streams[stream_id] = true
+      end
+
+      # === Data Handling ===
+
+      def buffer_data(stream_id, data)
+        @mutex.synchronize do
+          (@response_buffers[stream_id] ||= StringIO.new("".b)).write(data)
+        end
+      end
+
+      def complete_stream(stream_id, final_data)
+        @mutex.synchronize do
+          buffer = @response_buffers.delete(stream_id)
+          (buffer&.string || "".b) + (final_data || "".b)
+        end
+      end
+
+      # === HTTP/3 Frames ===
+
+      def send_goaway(stream_id = nil)
+        return unless @server_control_stream
+
+        stream_id ||= last_client_stream_id
+        @server_control_stream.send(Protocol.build_goaway_frame(stream_id))
+      rescue => e
+        Quicsilver.logger.error("Failed to send GOAWAY: #{e.message}")
+      end
+
+      def send_response(stream, status, headers, body, head_request: false)
+        encoder = Protocol::ResponseEncoder.new(status, headers, body, head_request: head_request)
+
+        if body.respond_to?(:to_ary)
+          Quicsilver.send_stream(stream.stream_handle, encoder.encode, true)
+        else
+          encoder.stream_encode do |frame_data, fin|
+            Quicsilver.send_stream(stream.stream_handle, frame_data, fin) unless frame_data.empty? && !fin
+          end
+        end
+      rescue RuntimeError => e
+        # Stream may have been reset by client - this is expected
+        raise unless e.message.include?("0x59") || e.message.include?("StreamSend failed")
+        Quicsilver.logger.debug("Stream send failed (client likely reset): #{e.message}")
+      end
+
+      def send_error(stream, status, message)
+        body = ["#{status} #{message}"]
+        encoder = Protocol::ResponseEncoder.new(status, { "content-type" => "text/plain" }, body)
+        Quicsilver.send_stream(stream.stream_handle, encoder.encode, true)
+      rescue RuntimeError => e
+        # Stream may have been reset by client - this is expected
+        raise unless e.message.include?("0x59") || e.message.include?("StreamSend failed")
+        Quicsilver.logger.debug("Stream send failed (client likely reset): #{e.message}")
+      end
+
+      # === Control Stream Handling ===
+
+      # Process incoming data on a unidirectional stream incrementally.
+      # Called on each RECEIVE event — control streams never send FIN.
+      def receive_unidirectional_data(stream_id, data)
+        @mutex.synchronize do
+          (@response_buffers[stream_id] ||= StringIO.new("".b)).write(data)
+        end
+
+        buf = @mutex.synchronize { @response_buffers[stream_id]&.string || "".b }
+        return if buf.empty?
+
+        # First time seeing this stream: identify stream type
+        unless @uni_stream_types&.key?(stream_id)
+          @uni_stream_types ||= {}
+          stream_type, type_len = Protocol.decode_varint(buf.bytes, 0)
+          return if type_len == 0  # need more data
+
+          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
+            # Remove the stream type byte from the buffer
+            @mutex.synchronize { @response_buffers[stream_id] = StringIO.new(buf[type_len..] || "".b) }
+          when 0x01
+            raise Protocol::FrameError, "Client must not send push streams"
+          when 0x02 # QPACK encoder stream
+            raise Protocol::FrameError, "Duplicate QPACK encoder stream" if @qpack_encoder_stream_id
+            @qpack_encoder_stream_id = stream_id
+            @uni_stream_types[stream_id] = :qpack_encoder
+            @mutex.synchronize { @response_buffers[stream_id] = StringIO.new(buf[type_len..] || "".b) }
+          when 0x03 # QPACK decoder stream
+            raise Protocol::FrameError, "Duplicate QPACK decoder stream" if @qpack_decoder_stream_id
+            @qpack_decoder_stream_id = stream_id
+            @uni_stream_types[stream_id] = :qpack_decoder
+            @mutex.synchronize { @response_buffers[stream_id] = StringIO.new(buf[type_len..] || "".b) }
+          else
+            # Unknown unidirectional stream types MUST be ignored (RFC 9114 §6.2)
+            @uni_stream_types[stream_id] = :unknown
+            return
+          end
+
+          buf = @mutex.synchronize { @response_buffers[stream_id]&.string || "".b }
+        end
+
+        stream_type = @uni_stream_types[stream_id]
+        return if buf.empty?
+
+        case stream_type
+        when :control
+          parse_control_frames(buf)
+          # Clear parsed data from buffer
+          @mutex.synchronize { @response_buffers[stream_id] = StringIO.new("".b) }
+        when :qpack_encoder
+          validate_qpack_encoder_data(buf)
+          @mutex.synchronize { @response_buffers[stream_id] = StringIO.new("".b) }
+        when :qpack_decoder
+          validate_qpack_decoder_data(buf)
+          @mutex.synchronize { @response_buffers[stream_id] = StringIO.new("".b) }
+        end
+      end
+
+      def handle_unidirectional_stream(stream, fin: true)
+        stream_id = stream.stream_id
+
+        # Already known as critical stream — closure via FIN is an error
+        if fin && critical_stream?(stream_id)
+          raise Protocol::FrameError.new("Closure of critical stream", error_code: Protocol::H3_CLOSED_CRITICAL_STREAM)
+        end
+
+        data = stream.data
+        return if data.empty?
+
+        stream_type, type_len = Protocol.decode_varint(data.bytes, 0)
+        return if type_len == 0
+        payload = data[type_len..-1]
+
+        case stream_type
+        when 0x00
+          set_control_stream(stream_id, payload)
+          if fin
+            raise Protocol::FrameError.new("Closure of critical stream", error_code: Protocol::H3_CLOSED_CRITICAL_STREAM)
+          end
+        when 0x01
+          raise Protocol::FrameError, "Client must not send push streams"
+        when 0x02
+          raise Protocol::FrameError, "Duplicate QPACK encoder stream" if @qpack_encoder_stream_id
+          @qpack_encoder_stream_id = stream_id
+          if fin
+            raise Protocol::FrameError.new("Closure of critical stream", error_code: Protocol::H3_CLOSED_CRITICAL_STREAM)
+          end
+        when 0x03
+          raise Protocol::FrameError, "Duplicate QPACK decoder stream" if @qpack_decoder_stream_id
+          @qpack_decoder_stream_id = stream_id
+          if fin
+            raise Protocol::FrameError.new("Closure of critical stream", error_code: Protocol::H3_CLOSED_CRITICAL_STREAM)
+          end
+        end
+      end
+
+      def set_control_stream(stream_id, payload = nil)
+        raise Protocol::FrameError, "Duplicate control stream" if @control_stream_id
+        @control_stream_id = stream_id
+        parse_control_frames(payload) if payload && !payload.empty?
+      end
+
+      def settings
+        @settings
+      end
+
+      def critical_stream?(stream_id)
+        stream_id == @control_stream_id ||
+          stream_id == @qpack_encoder_stream_id ||
+          stream_id == @qpack_decoder_stream_id
+      end
+
+      # === Shutdown ===
+
+      def shutdown(error_code = 0)
+        send_goaway
+        Quicsilver.connection_shutdown(@handle, error_code, false)
+      end
+
+      private
+
+      def open_stream(unidirectional: false)
+        handle = Quicsilver.open_stream(@data, unidirectional)
+        Stream.new(handle)
+      end
+
+      def last_client_stream_id
+        @streams.keys.select { |id| (id & 0x02) == 0 }.max || 0
+      end
+
+      # 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
+
+      # Frame types forbidden on the control stream
+      FORBIDDEN_ON_CONTROL = [
+        0x00, # DATA — request streams only
+        0x01, # HEADERS — request streams only
+        0x02, # HTTP/2 PRIORITY (reserved)
+        0x05, # PUSH_PROMISE — request streams only
+        0x06, # HTTP/2 PING (reserved)
+        0x08, # HTTP/2 WINDOW_UPDATE (reserved)
+        0x09, # HTTP/2 CONTINUATION (reserved)
+      ].freeze
+
+      def parse_control_frames(data)
+        offset = 0
+        first_frame = !@settings_received
+
+        while offset < data.bytesize
+          frame_type, type_len = Protocol.decode_varint(data.bytes, offset)
+          frame_length, length_len = Protocol.decode_varint(data.bytes, offset + type_len)
+          break if type_len == 0 || length_len == 0
+
+          if first_frame && 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
+
+          if FORBIDDEN_ON_CONTROL.include?(frame_type)
+            raise Protocol::FrameError, "Frame type 0x#{frame_type.to_s(16)} not allowed on control stream"
+          end
+
+          if frame_type == Protocol::FRAME_SETTINGS
+            raise Protocol::FrameError, "Duplicate SETTINGS frame on control stream" if @settings_received
+            parse_settings(data[offset + type_len + length_len, frame_length])
+            @settings_received = true
+          end
+
+          offset += type_len + length_len + frame_length
+        end
+      end
+
+      def parse_settings(payload)
+        offset = 0
+        seen = Set.new
+        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
+      end
+      # RFC 9204 §4.1.3: Validate QPACK encoder stream instructions.
+      # We advertise QPACK_MAX_TABLE_CAPACITY = 0, so any Set Dynamic Table Capacity
+      # instruction with value > 0 is an error.
+      def validate_qpack_encoder_data(data)
+        return if data.empty?
+        byte = data.bytes[0]
+
+        # Set Dynamic Table Capacity (001xxxxx)
+        if (byte & 0xE0) == 0x20
+          capacity, _ = Protocol.decode_varint(data.bytes, 0)
+          capacity &= 0x1F  # mask off the instruction prefix
+          # We advertised capacity 0, any non-zero is an error
+          raise Protocol::FrameError.new(
+            "Dynamic table capacity exceeds advertised maximum",
+            error_code: Protocol::QPACK_ENCODER_STREAM_ERROR
+          )
+        end
+      end
+
+      # RFC 9204 §4.4.3: Validate QPACK decoder stream instructions.
+      # Insert Count Increment of 0 is a decoder stream error.
+      def validate_qpack_decoder_data(data)
+        return if data.empty?
+        byte = data.bytes[0]
+
+        # Insert Count Increment (00xxxxxx)
+        if (byte & 0xC0) == 0x00
+          increment, _ = Protocol.decode_varint(data.bytes, 0)
+          increment &= 0x3F  # mask off prefix bits
+          if increment == 0
+            raise Protocol::FrameError.new(
+              "Insert Count Increment of 0 on decoder stream",
+              error_code: Protocol::QPACK_DECODER_STREAM_ERROR
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/quicsilver/transport/event_loop.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Transport
+    class EventLoop
+      def initialize
+        @running = false
+        @thread = nil
+        @mutex = Mutex.new
+      end
+
+      def start
+        @mutex.synchronize do
+          return if @running
+
+          @running = true
+          @thread = Thread.new do
+            Quicsilver.poll while @running
+          end
+        end
+      end
+
+      def stop
+        @running = false
+        Quicsilver.wake
+        @thread&.join(2)
+      end
+
+      def join
+        @thread&.join
+      end
+    end
+  end
+
+  def self.event_loop
+    @event_loop ||= Transport::EventLoop.new.tap(&:start)
+  end
+end

data/lib/quicsilver/transport/inbound_stream.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Transport
+    class InboundStream
+      attr_reader :stream_id, :is_unidirectional, :buffer
+      attr_accessor :stream_handle
+
+      def initialize(stream_id, is_unidirectional: nil)
+        @stream_id = stream_id
+        @is_unidirectional = is_unidirectional.nil? ? !bidirectional? : is_unidirectional
+        @buffer = StringIO.new.tap { |io| io.set_encoding(Encoding::ASCII_8BIT) }
+        @stream_handle = nil
+      end
+
+      def bidirectional?
+        (stream_id & 0x02) == 0
+      end
+
+      def writable?
+        !stream_handle.nil?
+      end
+
+      def append_data(data)
+        @buffer.write(data)
+      end
+
+      def data
+        @buffer.string
+      end
+    end
+  end
+end

data/lib/quicsilver/transport/stream.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Transport
+    # Wraps a QUIC stream opened by Ruby code (client requests, server control streams).
+    # Encapsulates the C handle — callers use send/reset/stop_sending methods instead
+    # of passing raw pointers to Quicsilver.send_stream etc.
+    class Stream
+      attr_reader :handle
+
+      def initialize(handle)
+        @handle = handle
+      end
+
+      def send(data, fin: false)
+        Quicsilver.send_stream(@handle, data, fin)
+      end
+
+      def reset(error_code = Protocol::H3_REQUEST_CANCELLED)
+        Quicsilver.stream_reset(@handle, error_code)
+      end
+
+      def stop_sending(error_code = Protocol::H3_REQUEST_CANCELLED)
+        Quicsilver.stream_stop_sending(@handle, error_code)
+      end
+    end
+  end
+end

data/lib/quicsilver/transport/stream_event.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Transport
+    # Parses the binary data packed by the C extension for stream completion events.
+    # C packs events as:
+    #   RECEIVE_FIN:  [stream_handle(8)][payload...]
+    #   STREAM_RESET: [stream_handle(8)][error_code(8)]
+    #   STOP_SENDING: [stream_handle(8)][error_code(8)]
+    class StreamEvent
+      attr_reader :handle, :data, :error_code
+
+      def initialize(raw_data, event_type)
+        @handle = raw_data[0, 8].unpack1("Q")
+        remaining = raw_data[8..] || "".b
+
+        case event_type
+        when "RECEIVE_FIN"
+          @data = remaining
+        when "STREAM_RESET", "STOP_SENDING"
+          @error_code = remaining.unpack1("Q")
+        end
+      end
+    end
+  end
+end

data/lib/quicsilver/version.rb

@@ -1,3 +1,3 @@
 module Quicsilver
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/quicsilver.rb

@@ -1,16 +1,40 @@
 # frozen_string_literal: true
 
+require "logger"
 require_relative "quicsilver/version"
-require_relative "quicsilver/client"
-require_relative "quicsilver/listener_data"
-require_relative "quicsilver/server"
-require_relative "quicsilver/server_configuration"
-require_relative "quicsilver/http3"
-require_relative "quicsilver/http3/request_parser"
-require_relative "quicsilver/http3/request_encoder"
-require_relative "quicsilver/http3/response_encoder"
+
+# Protocol layer (pure HTTP/3 codec)
+require_relative "quicsilver/protocol/frames"
+require_relative "quicsilver/protocol/qpack/encoder"
+require_relative "quicsilver/protocol/request_parser"
+require_relative "quicsilver/protocol/request_encoder"
+require_relative "quicsilver/protocol/response_parser"
+require_relative "quicsilver/protocol/response_encoder"
+
+# Transport layer (QUIC primitives)
+require_relative "quicsilver/transport/stream"
+require_relative "quicsilver/transport/stream_event"
+require_relative "quicsilver/transport/inbound_stream"
+require_relative "quicsilver/transport/event_loop"
+require_relative "quicsilver/transport/configuration"
+require_relative "quicsilver/transport/connection"
+
+# Server
+require_relative "quicsilver/server/listener_data"
+require_relative "quicsilver/server/request_registry"
+require_relative "quicsilver/server/request_handler"
+require_relative "quicsilver/server/server"
+
+# Client
+require_relative "quicsilver/client/request"
+require_relative "quicsilver/client/client"
+
+# C extension
 require_relative "quicsilver/quicsilver"
 
+# Rackup handler
+require_relative "rackup/handler/quicsilver"
+
 module Quicsilver
   class Error < StandardError; end
   class ServerIsRunningError < Error; end
@@ -19,4 +43,20 @@ module Quicsilver
   class ServerError < Error; end
   class ConnectionError < Error; end
   class TimeoutError < Error; end
-end
+
+  class << self
+    attr_writer :logger
+
+    def logger
+      @logger ||= default_logger
+    end
+
+    private
+
+    def default_logger
+      Logger.new($stdout, level: Logger::INFO).tap do |log|
+        log.progname = "Quicsilver"
+      end
+    end
+  end
+end

data/lib/rackup/handler/quicsilver.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "rackup/handler"
+require "localhost"
+
+module Quicsilver
+  module RackHandler
+    DEFAULT_OPTIONS = {
+      Host: "0.0.0.0",
+      Port: 4433,
+    }
+
+    def self.run(app, **options)
+      normalized_options = {
+        host: options[:Host] || options[:host] || DEFAULT_OPTIONS[:Host],
+        port: (options[:Port] || options[:port] || DEFAULT_OPTIONS[:Port]).to_i,
+      }
+
+      cert_file = options[:cert_file]
+      key_file = options[:key_file]
+
+      if cert_file.nil? && key_file.nil?
+        env = options[:environment] || ENV['RACK_ENV'] || ENV['RAILS_ENV'] || 'development'
+
+        if env == 'production'
+          raise ArgumentError, "cert_file and key_file are required in production"
+        else
+          require 'localhost/authority'
+          authority = Localhost::Authority.fetch
+          cert_file = authority.certificate_path
+          key_file = authority.key_path
+          Quicsilver.logger.info("Using auto-generated certificates for localhost")
+          Quicsilver.logger.info("  Cert: #{cert_file}")
+          Quicsilver.logger.info("  Key: #{key_file}")
+        end
+      end
+
+      config = ::Quicsilver::Transport::Configuration.new(cert_file, key_file)
+
+      server = ::Quicsilver::Server.new(
+        normalized_options[:port],
+        address: normalized_options[:host],
+        app: app,
+        server_configuration: config
+      )
+
+      yield server if block_given?
+
+      server.start
+    end
+
+    def self.valid_options
+      {
+        "Host=HOST" => "Hostname to listen on (default: 0.0.0.0)",
+        "Port=PORT" => "Port to listen on (default: 4433)",
+        "cert_file=PATH" => "Path to TLS certificate file (required)",
+        "key_file=PATH" => "Path to TLS key file (required)"
+      }
+    end
+
+  end
+end
+
+module Rackup
+  module Handler
+    module Quicsilver
+      def self.run(app, **options, &block)
+        ::Quicsilver::RackHandler.run(app, **options, &block)
+      end
+
+      def self.valid_options
+        ::Quicsilver::RackHandler.valid_options
+      end
+    end
+    register :quicsilver, Quicsilver
+  end
+end

data/quicsilver.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Haroon Ahmed"]
   spec.email         = ["haroon.ahmed25@gmail.com"]
 
-  spec.summary       = %q{Minimal HTTP/3 server implementation for Ruby}
-  spec.description   = %q{A minimal HTTP/3 server implementation for Ruby using Microsoft's MSQUIC library.}
+  spec.summary       = %q{HTTP/3 server implementation for Ruby}
+  spec.description   = %q{HTTP/3 server implementation for Ruby}
   spec.homepage      = "https://github.com/hahmed/quicsilver"
 
   # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
@@ -33,12 +33,19 @@ Gem::Specification.new do |spec|
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
+  spec.required_ruby_version = ">= 3.2.0"
 
   spec.extensions = ['ext/quicsilver/extconf.rb']
 
   spec.add_development_dependency "bundler", "~> 2.0"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency 'rake-compiler', '~> 1.2'
   spec.add_development_dependency 'rake-compiler-dock', '~> 1.3'
   spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "minitest-focus", "~> 1.3"
+  spec.add_development_dependency "benchmark-ips", "~> 2.12"
+  spec.add_dependency "logger"
+  spec.add_dependency "localhost", "~> 1.6"
+  spec.add_dependency "rack", "~> 3.0"
+  spec.add_dependency "rackup", "~> 2.0"
 end