quicsilver 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb40bd31dbb1c684ae68ec9b8a5f9fd0caee6972d360dc2be67984e473fdd15a
-  data.tar.gz: 2f46305042b7253d9fedc0018947404d6f27b045aef43be7a03ec32d3fe0bb8d
+  metadata.gz: d4926d24fbce141791505bb14d59e543a30a6c5cbf8ca3c3fd36c9123b2941db
+  data.tar.gz: 45c128c6bf9fc48b8267ba2927414f8429607e8f99e4169235d12ebe26863ccc
 SHA512:
-  metadata.gz: 48810a1f5a78021b027cb416bca181388b23889456e61c4c05702bd228f15da52026c25b2eedf375473054133300c62efd88c486367ddb987490676c8575a302
-  data.tar.gz: 7ebe3bdb83efaf1854655f6553e324ee4c425c4b2d202e76cb2c2adce0bfd814e567003fb2b315cb6b373acf8cfed8fb7f08dffa3859e4e103e3480d4877d8c6
+  metadata.gz: ad6f92657375909bac67ce88bfa64d47c53a2dd69bb424a36f297927778389247714c092b004287cc278c5ecdf94c0f186a4c15f4fa4cfff62dbef9fcfc155f6
+  data.tar.gz: 1f5d2812bfb18a15b1821c8afcb18f779663ec3066495ef69dfd9a1c79f8d83f13f7c6287b8ce56be318476ea69fd6c520c1dc4298ceb807c64f6de0747b3035

data/.github/workflows/ci.yml

@@ -22,15 +22,14 @@ jobs:
     runs-on: ubuntu-24.04
     strategy:
       matrix:
-        ruby-version: ["3.2"]
+        ruby-version: ["3.4"]
 
     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/.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,87 @@ 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
+- 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,43 @@
 PATH
   remote: .
   specs:
-    quicsilver (0.1.0)
+    quicsilver (0.4.0)
+      console
       localhost (~> 1.6)
+      logger
+      protocol-http (~> 0.49)
+      protocol-rack (~> 0.22)
       rack (~> 3.0)
       rackup (~> 2.0)
 
 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)
-    minitest (5.25.5)
+    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 (10.5.0)
+    rake (13.4.2)
     rake-compiler (1.3.0)
       rake
     rake-compiler-dock (1.9.1)
@@ -26,11 +47,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

@@ -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,43 +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
-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
+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, 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 test     # Run tests (122 passing)
-rake clean    # Clean build artifacts
+rake compile  # Build C extension (macOS: uses Apple clang automatically)
+rake test     # Run tests
 ```
 
 ## 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')
@@ -15,9 +37,18 @@ 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"'
-  sh 'cd vendor/msquic && cmake --build build --config Release'
+  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"'
+    # 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
+  # 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]
@@ -28,4 +59,65 @@ 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
+    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