quicsilver 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb40bd31dbb1c684ae68ec9b8a5f9fd0caee6972d360dc2be67984e473fdd15a
-  data.tar.gz: 2f46305042b7253d9fedc0018947404d6f27b045aef43be7a03ec32d3fe0bb8d
+  metadata.gz: 36065332b2efe43090097b945882282ba770a6b6b5a54d16d7229bf8977dfb6e
+  data.tar.gz: 22f94375fdaa43b465b6ff9b866985ca7dd06732ea5e0cbf98a94c7c92eb97df
 SHA512:
-  metadata.gz: 48810a1f5a78021b027cb416bca181388b23889456e61c4c05702bd228f15da52026c25b2eedf375473054133300c62efd88c486367ddb987490676c8575a302
-  data.tar.gz: 7ebe3bdb83efaf1854655f6553e324ee4c425c4b2d202e76cb2c2adce0bfd814e567003fb2b315cb6b373acf8cfed8fb7f08dffa3859e4e103e3480d4877d8c6
+  metadata.gz: edcac1b797654202cf22ef471e3de5cd23a8409f0ded8d940652cb6194d14974f0c08f7118af1f76e1895dca0598ae646764687d0fabb0555317e67a3587f690
+  data.tar.gz: a1521e2a828ba6bd394939a5c7b1034d1951f92329444f1adee5135db96df9703128b731c673c10c6309d104f238aa95589a9c9cfb581c6e050bc5ef6a261c8f

data/.github/workflows/ci.yml

@@ -26,11 +26,10 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
+      with:
+        submodules: recursive
     - name: Set up Ruby
-    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
-    # change this to (see https://github.com/ruby/setup-ruby#versioning):
-    # uses: ruby/setup-ruby@v1
-      uses: ruby/setup-ruby@55283cc23133118229fd3f97f9336ee23a179fcf # v1.146.0
+      uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby-version }}
         bundler-cache: true # runs 'bundle install' and caches installed gems automatically

data/CHANGELOG.md

@@ -5,6 +5,55 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-03-23
+
+### Added
+- QPACK Huffman coding with 8-bit decode table and encode/decode caching
+- 0-RTT replay protection for unsafe HTTP methods
+- Bounded backpressure support
+- Buffer size limits to prevent memory exhaustion (configurable `max_body_size`, `max_header_size`, `max_header_count`, `max_frame_payload_size`)
+- Content-length validation
+- Multi-value header support for duplicate header fields
+- Headers validation: reject connection-specific headers, require `:authority` or `host` for http/https schemes
+- Incremental unidirectional stream processing with critical stream protection
+- QPACK encoder and decoder stream instruction validation
+- Spec-correct error signaling with error codes on `FrameError` and `MessageError`
+- Suppress response body for HEAD requests per RFC 9114 §4.1
+- Allow `te: trailers` header in requests per RFC 9114 §4.2
+- Custom ALPN support (no longer hardcoded to `h3`)
+- `Stream` and `StreamEvent` abstractions to encapsulate C extension details
+- Dual-stack (IPv4/IPv6) listener support — fixes TLS handshake failures on macOS
+- Client `PUT` method
+- Integration test suite for curl HTTP/3
+
+### Fixed
+- Memory leaks: free `StreamContext` on `SHUTDOWN_COMPLETE`, free `ConnectionContext` on `CONNECTION_SHUTDOWN_COMPLETE`, close `EventQ`/`ExecContext`/`WakeFd` on shutdown
+- Double-free and handle leaks in C extension
+- `dispatch_to_ruby` safety with `rb_protect`; client use-after-free fix
+- Infinite loop on truncated varint in request/response parsers
+- Frame ordering: `DATA` before `HEADERS` now raises `FrameError`
+- `STOP_SENDING` / `STREAM_RESET` compliance — server properly cancels streams and resets send side
+- Control stream validation: reject duplicate settings, forbidden frame types, and reserved HTTP/2 types
+- QPACK static table index 57/58 casing (`includeSubDomains`)
+- Stale stream handle guard in cancel and C extension
+- Replaced `Thread.kill` with `Thread.raise(DrainTimeoutError)` for clean drain
+- Binary encoding for `buffer_data` and empty FIN handling
+- Linux/GitHub CI: use epoll instead of kqueue on non-Darwin platforms
+- Circular require warning
+
+### Changed
+- Reorganized gem structure: `protocol/`, `server/`, `transport/` directories
+- Server owns the 0-RTT policy
+- QPACK encoder uses O(1) static table lookup with multi-level caching
+- QPACK decoder uses string-based decoding with result caching
+- HTTP/3 parsers optimized with parse-level caching and lazy allocation
+- Varint encoding/decoding optimized with precomputed tables
+- HTTP/3 encoders handle framing only; QPACK handles field encoding (cleaner separation)
+- MsQuic custom execution mode with configurable worker pool and throughput settings
+
+### Limitations
+- Client does not reuse connections
+
 ## [0.2.0] - 2025-12-17
 
 ### Added

data/Gemfile.lock

@@ -1,22 +1,25 @@
 PATH
   remote: .
   specs:
-    quicsilver (0.1.0)
+    quicsilver (0.2.0)
       localhost (~> 1.6)
+      logger
       rack (~> 3.0)
       rackup (~> 2.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    benchmark-ips (2.14.0)
     localhost (1.6.0)
-    minitest (5.25.5)
+    logger (1.7.0)
+    minitest (5.27.0)
     minitest-focus (1.4.0)
       minitest (>= 4, < 6)
     rack (3.2.4)
     rackup (2.2.1)
       rack (>= 3)
-    rake (10.5.0)
+    rake (13.3.1)
     rake-compiler (1.3.0)
       rake
     rake-compiler-dock (1.9.1)
@@ -26,11 +29,12 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  benchmark-ips (~> 2.12)
   bundler (~> 2.0)
   minitest (~> 5.0)
   minitest-focus (~> 1.3)
   quicsilver!
-  rake (~> 10.0)
+  rake (~> 13.0)
   rake-compiler (~> 1.2)
   rake-compiler-dock (~> 1.3)
 

data/README.md

@@ -60,14 +60,15 @@ rackup -s quicsilver -p 4433
 ## Configuration
 
 ```ruby
+config = Quicsilver::ServerConfiguration.new("/path/to/cert.pem", "/path/to/key.pem",
+  idle_timeout_ms: 10_000,        # Connection idle timeout (ms)
+  max_concurrent_requests: 100    # Max concurrent requests per connection
+)
+
 server = Quicsilver::Server.new(4433,
   app: app,
   address: "0.0.0.0",
-  idle_timeout: 10_000,           # Connection idle timeout (ms)
-  initial_window_size: 65536,     # Flow control window
-  max_streams_bidi: 100,          # Max concurrent requests
-  cert_path: "/path/to/cert.pem", # TLS certificate
-  key_path: "/path/to/key.pem"    # TLS private key
+  server_configuration: config
 )
 ```
 
@@ -75,7 +76,7 @@ server = Quicsilver::Server.new(4433,
 
 ```bash
 rake compile  # Build C extension
-rake test     # Run tests (122 passing)
+rake test     # Run tests
 rake clean    # Clean build artifacts
 ```
 

data/Rakefile

@@ -15,8 +15,12 @@ task :setup do
 end
 
 task :build_msquic => :setup do
-  # Build MSQUIC using CMake with proper macOS framework linking
-  sh 'cd vendor/msquic && cmake -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXE_LINKER_FLAGS="-framework CoreServices" -DCMAKE_SHARED_LINKER_FLAGS="-framework CoreServices"'
+  cmake_args = ['-B build', '-DCMAKE_BUILD_TYPE=Release']
+  if RUBY_PLATFORM =~ /darwin/
+    cmake_args << '-DCMAKE_EXE_LINKER_FLAGS="-framework CoreServices"'
+    cmake_args << '-DCMAKE_SHARED_LINKER_FLAGS="-framework CoreServices"'
+  end
+  sh "cd vendor/msquic && cmake #{cmake_args.join(' ')}"
   sh 'cd vendor/msquic && cmake --build build --config Release'
 end
 
@@ -28,4 +32,27 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList["test/**/*_test.rb"]
 end
 
+namespace :benchmark do
+  desc "Run throughput benchmark"
+  task :throughput do
+    ruby "benchmarks/throughput.rb"
+  end
+
+  desc "Run concurrency benchmark"
+  task :concurrent do
+    ruby "benchmarks/concurrent.rb"
+  end
+
+  desc "Run component micro-benchmarks"
+  task :components do
+    ruby "benchmarks/components.rb"
+  end
+
+  desc "Run all benchmarks"
+  task :all => [:components, :throughput, :concurrent]
+end
+
+desc "Run all benchmarks"
+task :benchmark => "benchmark:all"
+
 task :default => :test

data/benchmarks/components.rb

@@ -0,0 +1,191 @@
+#!/usr/bin/env ruby
+# Component micro-benchmarks using benchmark-ips.
+# No server needed — pure in-process measurements.
+#
+# Usage: ruby benchmarks/components.rb
+
+require "bundler/setup"
+require "quicsilver"
+require "benchmark/ips"
+
+# --- Varint ---
+
+puts "=" * 60
+puts "Varint encode/decode"
+puts "=" * 60
+
+small  = 6
+medium = 1_000
+large  = 1_000_000
+
+encoded_small  = Quicsilver::Protocol.encode_varint(small)
+encoded_medium = Quicsilver::Protocol.encode_varint(medium)
+encoded_large  = Quicsilver::Protocol.encode_varint(large)
+
+Benchmark.ips do |x|
+  x.config(warmup: 1, time: 3)
+
+  x.report("encode small (#{small})")     { Quicsilver::Protocol.encode_varint(small) }
+  x.report("encode medium (#{medium})")   { Quicsilver::Protocol.encode_varint(medium) }
+  x.report("encode large (#{large})")     { Quicsilver::Protocol.encode_varint(large) }
+  x.report("decode small")   { Quicsilver::Protocol.decode_varint(encoded_small.bytes, 0) }
+  x.report("decode medium")  { Quicsilver::Protocol.decode_varint(encoded_medium.bytes, 0) }
+  x.report("decode large")   { Quicsilver::Protocol.decode_varint(encoded_large.bytes, 0) }
+
+  x.compare!
+end
+
+# --- Huffman ---
+
+puts
+puts "=" * 60
+puts "Huffman encode/decode"
+puts "=" * 60
+
+huffman_inputs = [
+  "www.example.com",
+  "application/json",
+  "text/html; charset=utf-8",
+  "GET",
+  "/api/v1/users?page=1&limit=50"
+]
+
+encoded_huffman = huffman_inputs.map { |s| Quicsilver::Protocol::Qpack::Huffman.encode(s) }
+
+Benchmark.ips do |x|
+  x.config(warmup: 1, time: 3)
+
+  huffman_inputs.each do |input|
+    x.report("encode #{input[0..20]}") { Quicsilver::Protocol::Qpack::Huffman.encode(input) }
+  end
+  encoded_huffman.each_with_index do |enc, i|
+    x.report("decode #{huffman_inputs[i][0..20]}") { Quicsilver::Protocol::Qpack::Huffman.decode(enc) }
+  end
+
+  x.compare!
+end
+
+# --- QPACK Encoder ---
+
+puts
+puts "=" * 60
+puts "QPACK Encoder"
+puts "=" * 60
+
+headers = [
+  [":method", "GET"],
+  [":path", "/api/v1/users"],
+  [":scheme", "https"],
+  [":authority", "example.com"],
+  ["accept", "application/json"],
+  ["user-agent", "quicsilver-bench/1.0"],
+  ["accept-encoding", "gzip, deflate"]
+]
+
+encoder_huffman = Quicsilver::Protocol::Qpack::Encoder.new(huffman: true)
+encoder_raw     = Quicsilver::Protocol::Qpack::Encoder.new(huffman: false)
+
+Benchmark.ips do |x|
+  x.config(warmup: 1, time: 3)
+
+  x.report("encode (huffman on)")  { encoder_huffman.encode(headers) }
+  x.report("encode (huffman off)") { encoder_raw.encode(headers) }
+
+  x.compare!
+end
+
+# --- QPACK Decoder ---
+
+puts
+puts "=" * 60
+puts "QPACK Decoder (string decoding)"
+puts "=" * 60
+
+# Build payloads for decode_qpack_string
+huffman_payload = Quicsilver::Protocol::Qpack::Huffman.encode("application/json")
+huffman_bytes = [0x80 | huffman_payload.bytesize] + huffman_payload.bytes  # Huffman flag set
+
+raw_string = "application/json"
+raw_bytes = [raw_string.bytesize] + raw_string.bytes  # No Huffman flag
+
+# Include the decoder module in a throwaway object
+decoder = Object.new
+decoder.extend(Quicsilver::Protocol::Qpack::Decoder)
+
+Benchmark.ips do |x|
+  x.config(warmup: 1, time: 3)
+
+  x.report("decode huffman string") { decoder.decode_qpack_string(huffman_bytes, 0) }
+  x.report("decode raw string")     { decoder.decode_qpack_string(raw_bytes, 0) }
+
+  x.compare!
+end
+
+# --- Request Parser ---
+
+puts
+puts "=" * 60
+puts "Request Parser"
+puts "=" * 60
+
+# Build a realistic GET request frame
+request_encoder = Quicsilver::Protocol::Qpack::Encoder.new(huffman: true)
+request_headers_payload = request_encoder.encode([
+  [":method", "GET"],
+  [":path", "/api/v1/users?page=1"],
+  [":scheme", "https"],
+  [":authority", "example.com"],
+  ["accept", "application/json"],
+  ["user-agent", "quicsilver-bench/1.0"]
+])
+
+# HEADERS frame: type=0x01, varint length, payload
+request_frame = Quicsilver::Protocol.encode_varint(0x01) +
+  Quicsilver::Protocol.encode_varint(request_headers_payload.bytesize) +
+  request_headers_payload
+
+Benchmark.ips do |x|
+  x.config(warmup: 1, time: 3)
+
+  x.report("parse GET request") do
+    parser = Quicsilver::Protocol::RequestParser.new(request_frame)
+    parser.parse
+  end
+
+  x.compare!
+end
+
+# --- Response Parser ---
+
+puts
+puts "=" * 60
+puts "Response Parser"
+puts "=" * 60
+
+# Build a realistic 200 response with body
+response_encoder = Quicsilver::Protocol::Qpack::Encoder.new(huffman: true)
+response_headers_payload = response_encoder.encode([
+  [":status", "200"],
+  ["content-type", "application/json"],
+  ["server", "quicsilver"]
+])
+
+body = '{"users":[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]}'
+
+response_frame = Quicsilver::Protocol.encode_varint(0x01) +
+  Quicsilver::Protocol.encode_varint(response_headers_payload.bytesize) +
+  response_headers_payload +
+  Quicsilver::Protocol.encode_varint(0x00) +
+  Quicsilver::Protocol.encode_varint(body.bytesize) +
+  body
+
+Benchmark.ips do |x|
+  x.config(warmup: 1, time: 3)
+
+  x.report("parse 200 response + body") do
+    parser = Quicsilver::Protocol::ResponseParser.new(response_frame)
+    parser.parse
+  end
+
+  x.compare!
+end

data/benchmarks/concurrent.rb

@@ -0,0 +1,110 @@
+#!/usr/bin/env ruby
+# Concurrency benchmark: tests HTTP/3 multiplexing and multi-connection overhead.
+#
+# Self-contained:
+#   ruby benchmarks/concurrent.rb
+#
+# External server:
+#   HOST=127.0.0.1 PORT=4433 ruby benchmarks/concurrent.rb
+
+require_relative "helpers"
+require "benchmark"
+
+MULTIPLEX_REQUESTS = ENV.fetch("MULTIPLEX_REQUESTS", "50").to_i
+NUM_CLIENTS        = ENV.fetch("NUM_CLIENTS", "20").to_i
+REQUESTS_PER_CLIENT = ENV.fetch("REQUESTS_PER_CLIENT", "5").to_i
+HOST = ENV["HOST"]
+PORT = ENV["PORT"]&.to_i
+
+def test_multiplexing(host, port)
+  Benchmarks::Helpers.print_header(
+    "Test 1: Single-connection multiplexing",
+    requests: MULTIPLEX_REQUESTS
+  )
+
+  request_times = []
+  mutex = Mutex.new
+
+  client = Quicsilver::Client.new(host, port, unsecure: true)
+  client.connect
+
+  elapsed = Benchmark.realtime do
+    threads = MULTIPLEX_REQUESTS.times.map do |i|
+      Thread.new do
+        start = Time.now
+        client.get("/multiplex/#{i}")
+        req_time = Time.now - start
+        mutex.synchronize { request_times << req_time }
+      end
+    end
+    threads.each(&:join)
+  end
+
+  client.disconnect
+
+  concurrency_factor = request_times.any? ? (request_times.sum / elapsed).round(2) : 0
+  puts "  Wall clock:          #{(elapsed * 1000).round(2)}ms"
+  puts "  Avg request time:    #{(request_times.sum / request_times.size * 1000).round(2)}ms"
+  puts "  Throughput:          #{(MULTIPLEX_REQUESTS / elapsed).round(2)} req/s"
+  puts "  Concurrency factor:  #{concurrency_factor}x"
+  Benchmarks::Helpers.print_stats("Latency", request_times)
+end
+
+def test_concurrent_clients(host, port)
+  Benchmarks::Helpers.print_header(
+    "Test 2: Concurrent clients",
+    clients:            NUM_CLIENTS,
+    requests_per_client: REQUESTS_PER_CLIENT
+  )
+
+  request_times = []
+  mutex = Mutex.new
+  successful = 0
+
+  elapsed = Benchmark.realtime do
+    threads = NUM_CLIENTS.times.map do |i|
+      Thread.new do
+        client = Quicsilver::Client.new(host, port, unsecure: true)
+        client.connect
+
+        REQUESTS_PER_CLIENT.times do |req|
+          start = Time.now
+          client.get("/client#{i}/request#{req}")
+          req_time = Time.now - start
+          mutex.synchronize { request_times << req_time }
+        end
+
+        client.disconnect
+        mutex.synchronize { successful += 1 }
+      rescue => e
+        $stderr.puts "  Client #{i} error: #{e.message}"
+      end
+    end
+    threads.each(&:join)
+  end
+
+  total_requests = request_times.size
+  concurrency_factor = request_times.any? ? (request_times.sum / elapsed).round(2) : 0
+
+  puts "  Successful clients:  #{successful}/#{NUM_CLIENTS}"
+  puts "  Total requests:      #{total_requests}"
+  puts "  Wall clock:          #{(elapsed * 1000).round(2)}ms"
+  puts "  Avg request time:    #{request_times.any? ? (request_times.sum / request_times.size * 1000).round(2) : "N/A"}ms"
+  puts "  Throughput:          #{(total_requests / elapsed).round(2)} req/s"
+  puts "  Concurrency factor:  #{concurrency_factor}x"
+  Benchmarks::Helpers.print_stats("Latency", request_times)
+end
+
+def run_all(host, port)
+  test_multiplexing(host, port)
+  test_concurrent_clients(host, port)
+end
+
+if HOST && PORT
+  run_all(HOST, PORT)
+else
+  puts "Booting inline server..."
+  Benchmarks::Helpers.with_server(Benchmarks::Helpers.benchmark_app) do |port|
+    run_all("127.0.0.1", port)
+  end
+end

data/benchmarks/helpers.rb

@@ -0,0 +1,88 @@
+require "bundler/setup"
+require "quicsilver"
+require "localhost/authority"
+
+module Benchmarks
+  module Helpers
+    # Boot a Quicsilver server on a random port, yield the port, then tear down.
+    def self.with_server(app, &block)
+      authority = Localhost::Authority.fetch
+      config = Quicsilver::Transport::Configuration.new(
+        authority.certificate_path,
+        authority.key_path
+      )
+
+      port = random_port
+      server = Quicsilver::Server.new(port, app: app, server_configuration: config)
+      server_thread = Thread.new { server.start }
+      sleep 0.5 # let listener settle
+
+      yield port
+    ensure
+      server&.stop rescue nil
+      server_thread&.join(2)
+    end
+
+    # Compute latency stats from an array of float durations (in seconds).
+    # Returns a Hash with :avg, :min, :max, :p50, :p95, :p99 (all in ms).
+    def self.stats(times)
+      return nil if times.empty?
+
+      sorted = times.sort
+      n = sorted.size
+      {
+        count: n,
+        avg:   (times.sum / n * 1000).round(2),
+        min:   (sorted.first * 1000).round(2),
+        max:   (sorted.last * 1000).round(2),
+        p50:   (sorted[n / 2] * 1000).round(2),
+        p95:   (sorted[(n * 0.95).to_i] * 1000).round(2),
+        p99:   (sorted[(n * 0.99).to_i] * 1000).round(2)
+      }
+    end
+
+    def self.print_header(title, **opts)
+      puts
+      puts "=" * 60
+      puts title
+      puts "=" * 60
+      opts.each { |k, v| puts "  #{k}: #{v}" }
+      puts "-" * 60
+    end
+
+    def self.print_stats(label, times)
+      s = stats(times)
+      unless s
+        puts "  #{label}: no data"
+        return
+      end
+      puts "  #{label}: #{s[:count]} reqs | avg=#{s[:avg]}ms p50=#{s[:p50]}ms p95=#{s[:p95]}ms p99=#{s[:p99]}ms (min=#{s[:min]}ms max=#{s[:max]}ms)"
+    end
+
+    def self.print_results(total_time:, total_requests:, times:, failed: 0, latency: false)
+      s = stats(times)
+      puts "-" * 60
+      puts "  Total time:  #{total_time.round(3)}s"
+      puts "  Requests:    #{total_requests} (#{failed} failed)"
+      puts "  Throughput:  #{(total_requests / total_time).round(2)} req/s"
+      if latency && s
+        puts "  Latency:     avg=#{s[:avg]}ms p50=#{s[:p50]}ms p95=#{s[:p95]}ms p99=#{s[:p99]}ms"
+        puts "               min=#{s[:min]}ms max=#{s[:max]}ms"
+      end
+      puts "=" * 60
+    end
+
+    def self.random_port
+      server = TCPServer.new("127.0.0.1", 0)
+      server.addr[1]
+    ensure
+      server&.close
+    end
+
+    def self.benchmark_app
+      ->(env) {
+        [200, { "content-type" => "text/plain" }, ["OK"]]
+      }
+    end
+  end
+end

data/benchmarks/quicsilver_server.rb

@@ -26,7 +26,7 @@ authority = Localhost::Authority.fetch
 cert_file = authority.certificate_path
 key_file = authority.key_path
 
-config = ::Quicsilver::ServerConfiguration.new(cert_file, key_file)
+config = ::Quicsilver::Transport::Configuration.new(cert_file, key_file)
 
 server = ::Quicsilver::Server.new(
   port.to_i,