quicsilver 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36065332b2efe43090097b945882282ba770a6b6b5a54d16d7229bf8977dfb6e
-  data.tar.gz: 22f94375fdaa43b465b6ff9b866985ca7dd06732ea5e0cbf98a94c7c92eb97df
+  metadata.gz: d4926d24fbce141791505bb14d59e543a30a6c5cbf8ca3c3fd36c9123b2941db
+  data.tar.gz: 45c128c6bf9fc48b8267ba2927414f8429607e8f99e4169235d12ebe26863ccc
 SHA512:
-  metadata.gz: edcac1b797654202cf22ef471e3de5cd23a8409f0ded8d940652cb6194d14974f0c08f7118af1f76e1895dca0598ae646764687d0fabb0555317e67a3587f690
-  data.tar.gz: a1521e2a828ba6bd394939a5c7b1034d1951f92329444f1adee5135db96df9703128b731c673c10c6309d104f238aa95589a9c9cfb581c6e050bc5ef6a261c8f
+  metadata.gz: ad6f92657375909bac67ce88bfa64d47c53a2dd69bb424a36f297927778389247714c092b004287cc278c5ecdf94c0f186a4c15f4fa4cfff62dbef9fcfc155f6
+  data.tar.gz: 1f5d2812bfb18a15b1821c8afcb18f779663ec3066495ef69dfd9a1c79f8d83f13f7c6287b8ce56be318476ea69fd6c520c1dc4298ceb807c64f6de0747b3035

data/.github/workflows/ci.yml

@@ -22,7 +22,7 @@ jobs:
     runs-on: ubuntu-24.04
     strategy:
       matrix:
-        ruby-version: ["3.2"]
+        ruby-version: ["3.4"]
 
     steps:
     - uses: actions/checkout@v4

data/.github/workflows/cibuildgem.yaml

@@ -0,0 +1,93 @@
+name: "Package and release gems with precompiled binaries"
+on:
+  workflow_dispatch:
+    inputs:
+      release:
+        description: "If the whole build passes on all platforms, release the gems on RubyGems.org"
+        required: false
+        type: boolean
+        default: false
+env:
+  CIBUILDGEM: 1
+jobs:
+  compile:
+    timeout-minutes: 20
+    name: "Cross compile the gem on different ruby versions"
+    strategy:
+      matrix:
+        os: ["macos-latest", "ubuntu-22.04"]
+    runs-on: "${{ matrix.os }}"
+    steps:
+      - name: "Checkout code"
+        uses: "actions/checkout@v5"
+        with:
+          submodules: recursive
+      - name: "Setup Ruby"
+        uses: "ruby/setup-ruby@v1"
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+      - name: "Build MsQuic"
+        run: bundle exec rake build_msquic
+      - name: "Run cibuildgem"
+        uses: "shopify/cibuildgem/.github/actions/cibuildgem@main"
+        with:
+          step: "compile"
+  test:
+    timeout-minutes: 20
+    name: "Run the test suite"
+    needs: compile
+    strategy:
+      matrix:
+        os: ["macos-latest", "ubuntu-22.04"]
+        rubies: ["3.4", "4.0"]
+        type: ["cross", "native"]
+    runs-on: "${{ matrix.os }}"
+    steps:
+      - name: "Checkout code"
+        uses: "actions/checkout@v5"
+      - name: "Setup Ruby"
+        uses: "ruby/setup-ruby@v1"
+        with:
+          ruby-version: "${{ matrix.rubies }}"
+          bundler-cache: true
+      - name: "Run cibuildgem"
+        uses: "shopify/cibuildgem/.github/actions/cibuildgem@main"
+        with:
+          step: "test_${{ matrix.type }}"
+  install:
+    timeout-minutes: 5
+    name: "Verify the gem can be installed"
+    needs: test
+    strategy:
+      matrix:
+        os: ["macos-latest", "ubuntu-22.04"]
+    runs-on: "${{ matrix.os }}"
+    steps:
+      - name: "Setup Ruby"
+        uses: "ruby/setup-ruby@v1"
+        with:
+          ruby-version: "4.0.0"
+      - name: "Run cibuildgem"
+        uses: "shopify/cibuildgem/.github/actions/cibuildgem@main"
+        with:
+          step: "install"
+  release:
+    environment: release
+    permissions:
+      id-token: write
+      contents: read
+    timeout-minutes: 5
+    if: ${{ inputs.release }}
+    name: "Release all gems with RubyGems"
+    needs: install
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: "Setup Ruby"
+        uses: "ruby/setup-ruby@v1"
+        with:
+          ruby-version: "4.0.0"
+      - name: "Run cibuildgem"
+        uses: "shopify/cibuildgem/.github/actions/cibuildgem@main"
+        with:
+          step: "release"

data/.gitignore

@@ -11,4 +11,6 @@
 /certificates/*
 *.bundle
 lib/quicsilver/quicsilver.bundle
-*.gem
+*.gem
+autoresearch.*
+ext/quicsilver/Makefile

data/CHANGELOG.md

@@ -5,6 +5,38 @@ 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.4.0] - 2026-04-25
+
+### Added
+- Client connection pool with automatic reuse (`Quicsilver::Client.get/post` class-level API)
+- GREASE support (RFC 9297) — settings, frames, and unidirectional streams
+- GOAWAY validation (RFC 9114 §7.2.6) — monotonically decreasing IDs, stream ID validation
+- Trailer support (RFC 9114 §4.1) — parse and send trailing HEADERS frames
+- Extensible Priorities (RFC 9218) — parse `priority` header, PRIORITY_UPDATE frames on control stream, MsQuic stream priority mapping
+- FrameParser base class — unified frame walking, ordering, body accumulation, size limits
+- FrameReader module — shared byte-level frame extraction for request/response/control streams
+- Trailer wiring in Adapter and StreamOutput for protocol-http integration
+- Informational 1xx responses (§4.1) — 103 Early Hints with `rack.early_hints` support for Rails
+- Two-phase GOAWAY shutdown (§5.2) — server sends decreasing GOAWAY IDs during graceful shutdown
+- Client processes server SETTINGS (§7.2.4) — parses peer's SETTINGS including MAX_FIELD_SECTION_SIZE
+- Client processes server GOAWAY (§5.2) — tracks peer_goaway_id, blocks new requests, connection pool evicts draining connections
+- MIT license in gemspec
+
+### Fixed
+- QPACK prefix decoding — decode Required Insert Count and Delta Base as varints instead of hardcoded `offset = 2`
+- Default decoder rejects payloads referencing the dynamic table
+- Response parser now enforces `max_frame_payload_size` (was missing)
+- Duplicate `frames` method in FrameParser
+- Consistent `@headers` and `@trailers` initialization (`{}` not `nil`)
+- extconf.rb — force Apple clang on macOS (Homebrew clang produces broken MsQuic binaries)
+
+### Changed
+- RequestParser and ResponseParser inherit from FrameParser (reduced ~230 lines of duplication)
+- `store_header`, `body`, `DEFAULT_DECODER`, `EMPTY_BODY`, `parse!` moved to FrameParser base class
+- `@body_io` renamed to `@body` in ResponseParser for consistency
+- ResponseEncoder accepts optional `trailers:` hash
+- StreamOutput accepts `send_fin:` parameter for trailer support
+
 ## [0.3.0] - 2026-03-23
 
 ### Added

data/Gemfile.lock

@@ -1,9 +1,12 @@
 PATH
   remote: .
   specs:
-    quicsilver (0.2.0)
+    quicsilver (0.4.0)
+      console
       localhost (~> 1.6)
       logger
+      protocol-http (~> 0.49)
+      protocol-rack (~> 0.22)
       rack (~> 3.0)
       rackup (~> 2.0)
 
@@ -11,15 +14,30 @@ GEM
   remote: https://rubygems.org/
   specs:
     benchmark-ips (2.14.0)
+    console (1.34.3)
+      fiber-annotation
+      fiber-local (~> 1.1)
+      json
+    fiber-annotation (0.2.0)
+    fiber-local (1.1.0)
+      fiber-storage
+    fiber-storage (1.0.1)
+    io-stream (0.11.1)
+    json (2.15.2)
     localhost (1.6.0)
     logger (1.7.0)
     minitest (5.27.0)
     minitest-focus (1.4.0)
       minitest (>= 4, < 6)
+    protocol-http (0.60.0)
+    protocol-rack (0.22.1)
+      io-stream (>= 0.10)
+      protocol-http (~> 0.58)
+      rack (>= 1.0)
     rack (3.2.4)
     rackup (2.2.1)
       rack (>= 3)
-    rake (13.3.1)
+    rake (13.4.2)
     rake-compiler (1.3.0)
       rake
     rake-compiler-dock (1.9.1)

data/README.md

@@ -1,13 +1,25 @@
 # Quicsilver
 
-HTTP/3 server for Ruby with Rack support.
-
-**Status:** Experimental (v0.2.0)
+HTTP/3 server and client for Ruby with Rack support.
+
+## Features
+
+- **HTTP/3 server** — serve any Rack app over QUIC/HTTP/3
+- **HTTP/3 client** — make requests with automatic connection pooling
+- **Rack integration** — `rackup -s quicsilver` works with Rails, Sinatra, any Rack app
+- **Streaming** — dispatch on HEADERS, stream body chunks as they arrive
+- **Extensible Priorities** (RFC 9218) — CSS before images, server respects client priority hints
+- **Trailers** (RFC 9114 §4.1) — send/receive trailing headers after the body
+- **GREASE** (RFC 9297) — extensibility testing on settings, frames, and streams
+- **GOAWAY** (RFC 9114 §7.2.6) — graceful connection draining with validation
+- **0-RTT** — fast reconnection with replay protection
+- **Connection pooling** — client reuses connections automatically
+- **protocol-http integration** — works with Falcon and protocol-http ecosystem
 
 ## Installation
 
 ```bash
-git clone <repository>
+git clone https://github.com/hahmed/quicsilver
 cd quicsilver
 bundle install
 rake compile
@@ -21,18 +33,11 @@ rake compile
 require "quicsilver"
 
 app = ->(env) {
-  case env['PATH_INFO']
-  when '/'
-    [200, {'content-type' => 'text/plain'}, ["Hello HTTP/3!"]]
-  when '/api/users'
-    [200, {'content-type' => 'application/json'}, ['{"users": ["alice", "bob"]}']]
-  else
-    [404, {'content-type' => 'text/plain'}, ["Not Found"]]
-  end
+  [200, {"content-type" => "text/plain"}, ["Hello HTTP/3!"]]
 }
 
 server = Quicsilver::Server.new(4433, app: app)
-server.start  # Blocks until shutdown
+server.start
 ```
 
 ### Client
@@ -40,44 +45,102 @@ server.start  # Blocks until shutdown
 ```ruby
 require "quicsilver"
 
-client = Quicsilver::Client.new("127.0.0.1", 4433, unsecure: true)
-client.connect
-
-response = client.get("/api/users")
-puts response[:body]
+# Class-level API with automatic connection pooling
+response = Quicsilver::Client.get("127.0.0.1", 4433, "/")
+puts response[:status]  # => 200
+puts response[:body]    # => "Hello HTTP/3!"
 
-response = client.post("/api/users", body: '{"name": "charlie"}')
+# POST with body
+response = Quicsilver::Client.post("127.0.0.1", 4433, "/api/users",
+  body: '{"name": "alice"}',
+  headers: { "content-type" => "application/json" })
 
+# Instance-level for more control
+client = Quicsilver::Client.new("127.0.0.1", 4433, unsecure: true)
+response = client.get("/")
 client.disconnect
 ```
 
-## Usage with Rails
+### Rails
 
 ```bash
 rackup -s quicsilver -p 4433
 ```
 
+### curl
+
+```bash
+curl --http3-only https://localhost: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
+config = Quicsilver::Transport::Configuration.new(
+  "certificates/server.crt",
+  "certificates/server.key",
+  idle_timeout_ms: 10_000,
+  max_concurrent_requests: 100,
+  max_body_size: 10 * 1024 * 1024,      # 10MB body limit (optional)
+  max_header_size: 64 * 1024,            # 64KB header limit (optional)
+  max_header_count: 128,                 # Header count limit (optional)
+  stream_receive_window: 262_144,        # 256KB per stream
+  connection_flow_control_window: 16_777_216  # 16MB per connection
 )
 
-server = Quicsilver::Server.new(4433,
-  app: app,
-  address: "0.0.0.0",
-  server_configuration: config
+server = Quicsilver::Server.new(4433, app: app, server_configuration: config)
+server.start
+```
+
+## Priorities
+
+Browsers send priority hints on requests. Quicsilver parses them and tells MsQuic to schedule high-priority streams first.
+
+```
+GET /style.css  → priority: u=0    → sent first (highest urgency)
+GET /app.js     → priority: u=1    → sent second
+GET /hero.png   → priority: u=5    → sent later
+```
+
+No configuration needed — it works automatically.
+
+## Trailers
+
+Send headers after the body — useful for checksums, streaming status, and gRPC.
+
+```ruby
+# Trailers work with protocol-http's Headers#trailer! API
+headers = Protocol::HTTP::Headers.new
+headers.add("content-type", "text/plain")
+headers.trailer!
+headers.add("x-checksum", "abc123")
+```
+
+## Protocol-HTTP Mode
+
+For integration with [Falcon](https://github.com/socketry/falcon) and the protocol-http ecosystem:
+
+```ruby
+config = Quicsilver::Transport::Configuration.new(
+  "certificates/server.crt",
+  "certificates/server.key",
+  mode: :protocol_http
 )
+
+server = Quicsilver::Server.new(4433, app: app, server_configuration: config)
+server.start
 ```
 
+| Mode | Body Handling | Use Case |
+|------|---------------|----------|
+| `:rack` (default) | Buffered | Standard Rack apps |
+| `:protocol_http` | Streaming | Falcon, protocol-http apps |
+
 ## Development
 
 ```bash
-rake compile  # Build C extension
+rake compile  # Build C extension (macOS: uses Apple clang automatically)
 rake test     # Run tests
-rake clean    # Clean build artifacts
 ```
 
 ## License

data/Rakefile

@@ -1,3 +1,4 @@
+require "bundler/setup"
 require "bundler/gem_tasks"
 require "rake/testtask"
 require "rake/extensiontask"
@@ -6,6 +7,27 @@ Rake::ExtensionTask.new('quicsilver') do |ext|
   ext.lib_dir = 'lib/quicsilver'
 end
 
+# Ensure MsQuic is built before compiling the C extension
+task :compile => :build_msquic
+
+# Copy MsQuic dylib next to the compiled extension for gem packaging
+task :bundle_msquic do
+  lib_dir = 'lib/quicsilver'
+  if RUBY_PLATFORM =~ /darwin/
+    dylib = 'vendor/msquic/build/bin/Release/libmsquic.2.dylib'
+    if File.exist?(dylib)
+      cp dylib, "#{lib_dir}/libmsquic.2.dylib"
+      # Update rpath so the bundle finds the dylib in the same directory
+      sh "install_name_tool -add_rpath @loader_path #{lib_dir}/quicsilver.bundle 2>/dev/null || true"
+    end
+  elsif RUBY_PLATFORM =~ /linux/
+    so = 'vendor/msquic/build/bin/Release/libmsquic.so.2'
+    cp so, "#{lib_dir}/libmsquic.so.2" if File.exist?(so)
+  end
+end
+
+task :build => :bundle_msquic
+
 task :setup do
   # Initialize git submodule if it doesn't exist
   unless File.exist?('vendor/msquic')
@@ -19,9 +41,14 @@ task :build_msquic => :setup do
   if RUBY_PLATFORM =~ /darwin/
     cmake_args << '-DCMAKE_EXE_LINKER_FLAGS="-framework CoreServices"'
     cmake_args << '-DCMAKE_SHARED_LINKER_FLAGS="-framework CoreServices"'
+    # Ensure QuicTLS uses Xcode SDK, not Homebrew OpenSSL
+    sdk_path = `xcrun --show-sdk-path 2>/dev/null`.strip
+    cmake_args << "-DCMAKE_OSX_SYSROOT=#{sdk_path}" unless sdk_path.empty?
   end
-  sh "cd vendor/msquic && cmake #{cmake_args.join(' ')}"
-  sh 'cd vendor/msquic && cmake --build build --config Release'
+  # Override PATH so QuicTLS openssldir detection finds system openssl, not Homebrew
+  env = { 'PATH' => "/usr/bin:#{ENV['PATH']}" }
+  sh env, "cd vendor/msquic && cmake #{cmake_args.join(' ')}"
+  sh env, 'cd vendor/msquic && cmake --build build --config Release'
 end
 
 task :build => [:build_msquic, :compile]
@@ -32,6 +59,44 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList["test/**/*_test.rb"]
 end
 
+Rake::TestTask.new(:test_unit) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"].reject { |f|
+    f.include?("integration") || f.include?("stream_control") ||
+    f =~ /quicsilver_test|event_loop_test/
+  }
+end
+
+Rake::TestTask.new(:test_integration) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList[
+    "test/stream_control_integration_test.rb",
+    "test/integration/**/*_test.rb",
+    "test/quicsilver_test.rb",
+    "test/event_loop_test.rb"
+  ]
+end
+
+desc "Run unit and integration tests in parallel"
+task :test_parallel do
+  threads = []
+  results = {}
+
+  threads << Thread.new {
+    results[:unit] = system("bundle exec rake test_unit 2>&1 > /dev/null")
+  }
+  threads << Thread.new {
+    results[:integration] = system("bundle exec rake test_integration 2>&1 > /dev/null")
+  }
+
+  threads.each(&:join)
+  unless results.values.all?
+    abort "Tests failed: #{results.inspect}"
+  end
+end
+
 namespace :benchmark do
   desc "Run throughput benchmark"
   task :throughput do

data/benchmarks/concurrent.rb

@@ -26,7 +26,7 @@ def test_multiplexing(host, port)
   mutex = Mutex.new
 
   client = Quicsilver::Client.new(host, port, unsecure: true)
-  client.connect
+  client.open_connection
 
   elapsed = Benchmark.realtime do
     threads = MULTIPLEX_REQUESTS.times.map do |i|
@@ -65,7 +65,7 @@ def test_concurrent_clients(host, port)
     threads = NUM_CLIENTS.times.map do |i|
       Thread.new do
         client = Quicsilver::Client.new(host, port, unsecure: true)
-        client.connect
+        client.open_connection
 
         REQUESTS_PER_CLIENT.times do |req|
           start = Time.now

data/benchmarks/rails.rb

@@ -59,7 +59,7 @@ post_elapsed = Benchmark.realtime do
   conn_threads = CONNECTIONS.times.map do |conn_id|
     Thread.new do
       client = Quicsilver::Client.new(HOST, PORT, unsecure: true)
-      client.connect
+      client.open_connection
 
       local_times = []
       local_ids = []
@@ -99,7 +99,7 @@ get_elapsed = Benchmark.realtime do
   conn_threads = CONNECTIONS.times.map do
     Thread.new do
       client = Quicsilver::Client.new(HOST, PORT, unsecure: true)
-      client.connect
+      client.open_connection
 
       local_times = []
 
@@ -132,7 +132,7 @@ delete_elapsed = Benchmark.realtime do
       next if ids.empty?
 
       client = Quicsilver::Client.new(HOST, PORT, unsecure: true)
-      client.connect
+      client.open_connection
 
       local_times = []
 

data/benchmarks/throughput.rb

@@ -29,7 +29,7 @@ def run_benchmark(host, port)
     threads = CONNECTIONS.times.map do
       Thread.new do
         client = Quicsilver::Client.new(host, port, connection_timeout: 5000, request_timeout: 10)
-        client.connect
+        client.open_connection
 
         local = []
         per_conn.times do
@@ -61,7 +61,7 @@ def run_benchmark(host, port)
     threads = CONNECTIONS.times.map do
       Thread.new do
         client = Quicsilver::Client.new(host, port, connection_timeout: 5000, request_timeout: 10)
-        client.connect
+        client.open_connection
 
         local = []
         queue = Queue.new