quicsilver 0.3.0 → 0.5.0

data/lib/quicsilver/transport/connection_stats.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Transport
+    # Immutable snapshot of QUIC transport statistics from MsQuic's QUIC_STATISTICS_V2.
+    #
+    #   stats = client.stats
+    #   stats.rtt                    # => 1234 (microseconds)
+    #   stats.send_total_packets     # => 42
+    #   stats.recv_total_bytes       # => 98765
+    #
+    ConnectionStats = Data.define(
+      # RTT (microseconds)
+      :rtt, :min_rtt, :max_rtt,
+
+      # Handshake
+      :resumption_attempted, :resumption_succeeded,
+
+      # Send
+      :send_path_mtu,
+      :send_total_packets, :send_retransmittable_packets,
+      :send_suspected_lost_packets, :send_spurious_lost_packets,
+      :send_total_bytes, :send_total_stream_bytes,
+      :send_congestion_count, :send_persistent_congestion_count,
+      :send_congestion_window,
+
+      # Recv
+      :recv_total_packets, :recv_reordered_packets,
+      :recv_dropped_packets, :recv_duplicate_packets,
+      :recv_total_bytes, :recv_total_stream_bytes,
+      :recv_decryption_failures, :recv_valid_ack_frames,
+
+      # Misc
+      :key_update_count
+    ) do
+      # Build from the hash returned by the C extension.
+      def self.from_hash(hash)
+        return nil unless hash
+
+        new(**hash.transform_keys(&:to_sym))
+      end
+
+      def resumed?
+        resumption_succeeded
+      end
+
+      def packet_loss_rate
+        return 0.0 if send_total_packets == 0
+        send_suspected_lost_packets.to_f / send_total_packets
+      end
+    end
+  end
+end

data/lib/quicsilver/transport/event_loop.rb

@@ -2,10 +2,33 @@
 
 module Quicsilver
   module Transport
+    # Two threads: one drives MsQuic, one delivers its events to Ruby.
+    #
+    # The poll thread runs Quicsilver.poll, which releases the GVL for the
+    # whole MsQuic iteration: decryption, loss recovery, stream reassembly and
+    # the callbacks that queue events for Ruby all happen without the lock.
+    # The dispatcher thread runs Quicsilver.dispatch_events, which waits on
+    # that queue without the GVL, then takes it to call Server.handle_stream
+    # (or Client#handle_stream_event) for each event in order.
+    #
+    # Before, a single thread did both, and every byte MsQuic processed was
+    # processed while holding the GVL, because the callback at the end of it
+    # called into Ruby. Splitting them lets the datapath run in parallel with
+    # the dispatcher and the worker pool.
+    #
+    # Event order is preserved: the queue is FIFO and there is one consumer.
     class EventLoop
+      # Events delivered per GVL hold. Bounds how long a batch runs; the
+      # dispatcher yields early only when the server's admission queue is
+      # under pressure (Server#enqueue_work). QUICSILVER_DISPATCH_BATCH
+      # overrides it for measurement.
+      DISPATCH_BATCH = Integer(ENV.fetch("QUICSILVER_DISPATCH_BATCH", "64"))
+      DISPATCH_WAIT_MS = 1000
+
       def initialize
         @running = false
         @thread = nil
+        @dispatcher = nil
         @mutex = Mutex.new
       end
 
@@ -14,16 +37,29 @@ module Quicsilver
           return if @running
 
           @running = true
+          Quicsilver.open_event_queue
+          @dispatcher = Thread.new do
+            Thread.current.name = "quicsilver-dispatch"
+            loop do
+              delivered = Quicsilver.dispatch_events(DISPATCH_BATCH, DISPATCH_WAIT_MS)
+              break if delivered.nil? # queue closed and drained
+            end
+          end
           @thread = Thread.new do
+            Thread.current.name = "quicsilver-poll"
             Quicsilver.poll while @running
           end
         end
       end
 
+      # Stop the poll thread first so nothing else is queued, then close the
+      # queue so the dispatcher exits once it has delivered what is there.
       def stop
         @running = false
         Quicsilver.wake
         @thread&.join(2)
+        Quicsilver.close_event_queue
+        @dispatcher&.join(2)
       end
 
       def join

data/lib/quicsilver/transport/inbound_stream.rb

@@ -14,7 +14,7 @@ module Quicsilver
       end
 
       def bidirectional?
-        (stream_id & 0x02) == 0
+        StreamId.bidirectional?(stream_id)
       end
 
       def writable?
@@ -28,6 +28,26 @@ module Quicsilver
       def data
         @buffer.string
       end
+
+      def send(data, fin: false)
+        return unless writable?
+        Quicsilver.send_stream(@stream_handle, data, fin)
+      end
+
+      def reset(error_code = Protocol::H3_REQUEST_CANCELLED)
+        return unless writable?
+        Quicsilver.stream_reset(@stream_handle, error_code)
+      end
+
+      def stop_sending(error_code = Protocol::H3_REQUEST_CANCELLED)
+        return unless writable?
+        Quicsilver.stream_stop_sending(@stream_handle, error_code)
+      end
+
+      def abort(error_code = Protocol::H3_REQUEST_CANCELLED)
+        return unless writable?
+        Quicsilver.stream_abort(@stream_handle, error_code)
+      end
     end
   end
 end

data/lib/quicsilver/transport/stream.rb

@@ -2,9 +2,7 @@
 
 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.
+    # The handle is an opaque native registry token, not a pointer.
     class Stream
       attr_reader :handle
 
@@ -12,10 +10,23 @@ module Quicsilver
         @handle = handle
       end
 
+      # Returns nil until asynchronous stream startup completes, or after shutdown.
+      def stream_id
+        Quicsilver.get_stream_id(@handle)
+      end
+
       def send(data, fin: false)
         Quicsilver.send_stream(@handle, data, fin)
       end
 
+      def reliable_offset=(offset)
+        Quicsilver.set_stream_reliable_offset(@handle, offset)
+      end
+
+      def grant_receive_credit(bytes, chunks)
+        Quicsilver.grant_stream_receive_credit(@handle, bytes, chunks)
+      end
+
       def reset(error_code = Protocol::H3_REQUEST_CANCELLED)
         Quicsilver.stream_reset(@handle, error_code)
       end
@@ -23,6 +34,10 @@ module Quicsilver
       def stop_sending(error_code = Protocol::H3_REQUEST_CANCELLED)
         Quicsilver.stream_stop_sending(@handle, error_code)
       end
+
+      def abort(error_code = Protocol::H3_REQUEST_CANCELLED)
+        Quicsilver.stream_abort(@handle, error_code)
+      end
     end
   end
 end

data/lib/quicsilver/transport/stream_event.rb

@@ -5,22 +5,45 @@ module Quicsilver
     # 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)]
+    #   STREAM_RESET: [stream_handle(8)][error_code(8)][final_size(8)]
     #   STOP_SENDING: [stream_handle(8)][error_code(8)]
     class StreamEvent
+      # A reset stream's final size is unknown to MsQuic until RESET_STREAM or
+      # FIN settles it; the C extension reports that as this sentinel so it
+      # never has to be confused with a real length.
+      FINAL_SIZE_UNKNOWN = (2**64) - 1
+
       attr_reader :handle, :data, :error_code
 
+      # The total number of bytes the peer sent on this stream, from the
+      # RESET_STREAM frame (RFC 9000 4.5). nil when it is not settled or the
+      # event does not carry one. WebTransport session flow control needs it to
+      # charge the bytes a reset discarded (draft-ietf-webtrans-http3-16 5.4).
+      attr_reader :final_size
+
       def initialize(raw_data, event_type)
         @handle = raw_data[0, 8].unpack1("Q")
         remaining = raw_data[8..] || "".b
 
         case event_type
-        when "RECEIVE_FIN"
+        when "RECEIVE", "RECEIVE_FIN"
           @data = remaining
         when "STREAM_RESET", "STOP_SENDING"
           @error_code = remaining.unpack1("Q")
+          @final_size = parse_final_size(remaining)
         end
       end
+
+      private
+
+      # Older packings carry only the error code, so a missing final size is
+      # not an error.
+      def parse_final_size(remaining)
+        return unless remaining.bytesize >= 16
+
+        value = remaining.unpack1("@8Q")
+        value unless value == FINAL_SIZE_UNKNOWN
+      end
     end
   end
 end

data/lib/quicsilver/transport/stream_id.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Transport
+    module StreamId
+      INITIATOR_MASK = 0x01
+      DIRECTION_MASK = 0x02
+      REQUEST_STREAM_MASK = INITIATOR_MASK | DIRECTION_MASK
+
+      module_function
+
+      def bidirectional?(stream_id)
+        (stream_id & DIRECTION_MASK).zero?
+      end
+
+      def unidirectional?(stream_id)
+        !bidirectional?(stream_id)
+      end
+
+      # HTTP/3 requests run on client-initiated bidirectional QUIC streams.
+      def request?(stream_id)
+        (stream_id & REQUEST_STREAM_MASK).zero?
+      end
+    end
+  end
+end

data/lib/quicsilver/version.rb

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

data/lib/quicsilver.rb

@@ -2,51 +2,75 @@
 
 require "logger"
 require_relative "quicsilver/version"
+require_relative "quicsilver/errors"
+require_relative "quicsilver/response"
 
-# Protocol layer (pure HTTP/3 codec)
+# Protocol layer
 require_relative "quicsilver/protocol/frames"
+require_relative "quicsilver/protocol/datagram"
+require_relative "quicsilver/protocol/capsule"
+require_relative "quicsilver/protocol/web_transport"
+require_relative "quicsilver/protocol/unidirectional_stream"
+require_relative "quicsilver/protocol/priority"
 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"
+require_relative "quicsilver/protocol/stream_input"
+require_relative "quicsilver/protocol/stream_output"
+require_relative "quicsilver/protocol/adapter"
+require_relative "quicsilver/protocol/control_stream_parser"
+require "protocol/rack"
 
-# Transport layer (QUIC primitives)
+# Rack integration
+require_relative "quicsilver/rack/context"
+
+# Transport layer
+require_relative "quicsilver/transport/stream_id"
 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"
+require_relative "quicsilver/transport/connection_stats"
 
 # Server
 require_relative "quicsilver/server/listener_data"
 require_relative "quicsilver/server/request_registry"
 require_relative "quicsilver/server/request_handler"
+require_relative "quicsilver/server/rack_adapter"
+require_relative "quicsilver/server/web_transport_flow_control"
+require_relative "quicsilver/server/web_transport_manager"
 require_relative "quicsilver/server/server"
 
 # Client
 require_relative "quicsilver/client/request"
+require_relative "quicsilver/client/connection_pool"
 require_relative "quicsilver/client/client"
 
 # C extension
-require_relative "quicsilver/quicsilver"
+begin
+  ruby_version = /(\d+\.\d+)/.match(RUBY_VERSION)
+  require "quicsilver/#{ruby_version}/quicsilver"
+rescue LoadError
+  require "quicsilver/quicsilver"
+end
 
 # Rackup handler
 require_relative "rackup/handler/quicsilver"
 
 module Quicsilver
-  class Error < StandardError; 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 << self
     attr_writer :logger
 
+    def stream_abort(handle, error_code)
+      receiving_stopped = stream_stop_sending(handle, error_code)
+      sending_reset = stream_reset(handle, error_code)
+      receiving_stopped || sending_reset
+    end
+
     def logger
       @logger ||= default_logger
     end
@@ -59,4 +83,14 @@ module Quicsilver
       end
     end
   end
+
+  # Release pooled client connections on process exit.
+  # Closes connection handles so the OS doesn't leak UDP sockets.
+  # MsQuic itself is cleaned up by the OS when the process exits.
+  at_exit do
+    begin
+      Client.close_pool
+    rescue StandardError # rubocop:disable Lint/SuppressedException
+    end
+  end
 end

data/lib/rackup/handler/quicsilver.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "rackup/handler"
-require "localhost"
 
 module Quicsilver
   module RackHandler
@@ -10,54 +9,74 @@ module Quicsilver
       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,
-      }
+    class << self
+      def 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]
+        cert_file, key_file = certificate_paths(options)
+        config = ::Quicsilver::Transport::Configuration.new(cert_file, key_file)
 
-      if cert_file.nil? && key_file.nil?
-        env = options[:environment] || ENV['RACK_ENV'] || ENV['RAILS_ENV'] || 'development'
+        server = ::Quicsilver::Server.new(
+          normalized_options[:port],
+          address: normalized_options[:host],
+          app: app,
+          server_configuration: config
+        )
 
-        if env == 'production'
-          raise ArgumentError, "cert_file and key_file are required in production"
+        yield server if block_given?
+
+        server.start
+      end
+
+      def 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 in production)",
+          "key_file=PATH" => "Path to TLS key file (required in production)"
+        }
+      end
+
+      private
+
+      def certificate_paths(options)
+        cert_file = options[:cert_file]
+        key_file = options[:key_file]
+
+        if cert_file.nil? && key_file.nil?
+          if production?(options)
+            raise ArgumentError, "cert_file and key_file are required in production"
+          else
+            localhost_certificate_paths
+          end
+        elsif cert_file.nil? || key_file.nil?
+          raise ArgumentError, "cert_file and key_file must be provided together"
         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}")
+          [cert_file, 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
-      )
+      def production?(options)
+        env = options[:environment] || ENV["RACK_ENV"] || ENV["RAILS_ENV"] || "development"
+        env == "production"
+      end
 
-      yield server if block_given?
+      def localhost_certificate_paths
+        require "localhost/authority"
+        authority = Localhost::Authority.fetch
+        cert_file = authority.certificate_path
+        key_file = authority.key_path
 
-      server.start
-    end
+        Quicsilver.logger.info("Using auto-generated certificates for localhost")
+        Quicsilver.logger.info("  Cert: #{cert_file}")
+        Quicsilver.logger.info("  Key: #{key_file}")
 
-    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)"
-      }
+        [cert_file, key_file]
+      end
     end
-
   end
 end
 

data/quicsilver.gemspec

@@ -11,6 +11,7 @@ Gem::Specification.new do |spec|
   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"
+  spec.license       = "MIT"
 
   # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
   # to allow pushing to a single host or delete this section to allow pushing to any host.
@@ -28,12 +29,22 @@ Gem::Specification.new do |spec|
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+    files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|vendor)/}) }
+
+    if ENV["RELEASE"]
+      if RUBY_PLATFORM.include?("darwin")
+        files += Dir["lib/quicsilver/libmsquic*.dylib"]
+      elsif RUBY_PLATFORM.include?("linux")
+        files += Dir["lib/quicsilver/libmsquic.so*"]
+      end
+    end
+
+    files
   end
   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.required_ruby_version = ">= 3.4.0"
 
   spec.extensions = ['ext/quicsilver/extconf.rb']
 
@@ -41,9 +52,13 @@ Gem::Specification.new do |spec|
   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 "cibuildgem"
   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 "protocol-http", "~> 0.49"
+  spec.add_dependency "protocol-rack", "~> 0.22"
+  spec.add_dependency "console" # TODO: drop when protocol-rack declares this in its gemspec
   spec.add_dependency "logger"
   spec.add_dependency "localhost", "~> 1.6"
   spec.add_dependency "rack", "~> 3.0"