quicsilver 0.5.0-x86_64-linux

data/lib/quicsilver/transport/event_loop.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+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
+
+      def start
+        @mutex.synchronize do
+          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
+        @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,53 @@
+# 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?
+        StreamId.bidirectional?(stream_id)
+      end
+
+      def writable?
+        !stream_handle.nil?
+      end
+
+      def append_data(data)
+        @buffer.write(data)
+      end
+
+      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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Transport
+    # The handle is an opaque native registry token, not a pointer.
+    class Stream
+      attr_reader :handle
+
+      def initialize(handle)
+        @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
+
+      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

@@ -0,0 +1,49 @@
+# 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)][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", "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

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

data/lib/quicsilver.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "logger"
+require_relative "quicsilver/version"
+require_relative "quicsilver/errors"
+require_relative "quicsilver/response"
+
+# 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"
+
+# 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
+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 << 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
+
+    private
+
+    def default_logger
+      Logger.new($stdout, level: Logger::INFO).tap do |log|
+        log.progname = "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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "rackup/handler"
+
+module Quicsilver
+  module RackHandler
+    DEFAULT_OPTIONS = {
+      Host: "0.0.0.0",
+      Port: 4433,
+    }
+
+    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, key_file = certificate_paths(options)
+        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 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
+          [cert_file, key_file]
+        end
+      end
+
+      def production?(options)
+        env = options[:environment] || ENV["RACK_ENV"] || ENV["RAILS_ENV"] || "development"
+        env == "production"
+      end
+
+      def localhost_certificate_paths
+        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
+  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

@@ -0,0 +1,66 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "quicsilver/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "quicsilver"
+  spec.version       = Quicsilver::VERSION
+  spec.authors       = ["Haroon Ahmed"]
+  spec.email         = ["haroon.ahmed25@gmail.com"]
+
+  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.
+  if spec.respond_to?(:metadata)
+    spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+    spec.metadata["homepage_uri"] = spec.homepage
+    spec.metadata["source_code_uri"] = "https://github.com/hahmed/quicsilver"
+    spec.metadata["changelog_uri"] = "https://github.com/hahmed/quicsilver/blob/main/CHANGELOG.md"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against " \
+      "public gem pushes."
+  end
+
+  # 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
+    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.4.0"
+
+  spec.extensions = ['ext/quicsilver/extconf.rb']
+
+  spec.add_development_dependency "bundler", "~> 2.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 "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"
+  spec.add_dependency "rackup", "~> 2.0"
+end