quicsilver 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e879e4531621883da97721256a2b0db478ba995d8bf54c93ddf959fca9cd36d
-  data.tar.gz: 579023d40239d8c7a77671be44fb37265d735f864a13072887598406908c0aae
+  metadata.gz: 36065332b2efe43090097b945882282ba770a6b6b5a54d16d7229bf8977dfb6e
+  data.tar.gz: 22f94375fdaa43b465b6ff9b866985ca7dd06732ea5e0cbf98a94c7c92eb97df
 SHA512:
-  metadata.gz: 25c070017404e15d673cfcb267ef90722dd255af0c68dd3488f1065ebe8fcc84614054b7ae3b5b0e2cd1bc74ca725a7ddd4e0500b80f849580ebef3306705443
-  data.tar.gz: 61f273afb32f2a45d07bc2f634a8f6d52973654b4e874ed01dd87a674126046f2e332741ca464b6f41a025e206064172a9614c602bb7285dab0b68b6efa7d09a
+  metadata.gz: edcac1b797654202cf22ef471e3de5cd23a8409f0ded8d940652cb6194d14974f0c08f7118af1f76e1895dca0598ae646764687d0fabb0555317e67a3587f690
+  data.tar.gz: a1521e2a828ba6bd394939a5c7b1034d1951f92329444f1adee5135db96df9703128b731c673c10c6309d104f238aa95589a9c9cfb581c6e050bc5ef6a261c8f

data/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Ruby
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        ruby-version: ["3.2"]
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        submodules: recursive
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Build MSQUIC
+      run: bundle exec rake build_msquic
+    - name: Compile
+      run: bundle exec rake compile
+    - name: Run tests
+      run: bundle exec rake

data/.gitignore

@@ -8,5 +8,7 @@
 /tmp/
 /vendor/*
 /certs/*
+/certificates/*
 *.bundle
-lib/quicsilver/quicsilver.bundle
+lib/quicsilver/quicsilver.bundle
+*.gem

data/CHANGELOG.md

@@ -5,6 +5,82 @@ 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
+- Graceful shutdown with GOAWAY frames (RFC 9114 compliant)
+- Streaming response support for lazy/chunked bodies
+- Flow control settings for backpressure management
+- Client HTTP verb helpers: `get`, `post`, `patch`, `delete`, `head`
+- Integration test suite
+- Benchmarking examples for Rails
+
+### Fixed
+- Memory leak: send buffers now freed on SEND_COMPLETE callback
+- Segfault in event loop when client_obj was invalid
+- Content-Type header handling for Rack compatibility
+- String concatenation performance using StringIO
+
+### Changed
+- `server.start` now blocks until shutdown (no separate `wait_for_connections` needed)
+- Refactored to global event loop architecture
+- Simplified server internals with Connection and QuicStream classes
+- Replaced debug puts with proper logging
+
+### Limitations
+- No server push or trailer support
+- No dynamic QPACK table (static table only)
+- Client does not reuse connections
+
 ## [0.1.0] - 2025-10-28
 
 ### Added
@@ -15,8 +91,3 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - QPACK header compression (static table support)
 - Bidirectional request/response streams
 - Request body buffering for large payloads
-
-### Limitations
-This is still in prototype, it has the following known limitations:
-- No server push, GOAWAY, or trailer support
-- Limited error handling

data/Gemfile.lock

@@ -1,13 +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:
-    minitest (5.25.5)
-    rake (10.5.0)
+    benchmark-ips (2.14.0)
+    localhost (1.6.0)
+    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 (13.3.1)
     rake-compiler (1.3.0)
       rake
     rake-compiler-dock (1.9.1)
@@ -17,10 +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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Haroon Ahmed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -2,7 +2,7 @@
 
 HTTP/3 server for Ruby with Rack support.
 
-Disclaimer: currenly in early prototype.
+**Status:** Experimental (v0.2.0)
 
 ## Installation
 
@@ -15,89 +15,69 @@ rake compile
 
 ## Quick Start
 
-### 1. Set up certificates
-
-```bash
-bash examples/setup_certs.sh
-```
-
-### 2. Run a Rack app over HTTP/3
+### Server
 
 ```ruby
 require "quicsilver"
 
-# Define your Rack app
 app = ->(env) {
-  path = env['PATH_INFO']
-
-  case path
+  case env['PATH_INFO']
   when '/'
-    [200, {'Content-Type' => 'text/plain'}, ["Hello HTTP/3!"]]
+    [200, {'content-type' => 'text/plain'}, ["Hello HTTP/3!"]]
   when '/api/users'
-    [200, {'Content-Type' => 'application/json'}, ['{"users": ["alice", "bob"]}']]
+    [200, {'content-type' => 'application/json'}, ['{"users": ["alice", "bob"]}']]
   else
-    [404, {'Content-Type' => 'text/plain'}, ["Not Found"]]
+    [404, {'content-type' => 'text/plain'}, ["Not Found"]]
   end
 }
 
-# Start HTTP/3 server with Rack app
 server = Quicsilver::Server.new(4433, app: app)
-server.start
-server.wait_for_connections
+server.start  # Blocks until shutdown
 ```
 
-### 3. Test with the client
-
-```bash
-ruby examples/minimal_http3_client.rb
-```
-
-## Usage
-
-### Rack HTTP/3 Server
+### Client
 
 ```ruby
 require "quicsilver"
 
-app = ->(env) {
-  [200, {'Content-Type' => 'text/html'}, ["<h1>Hello from HTTP/3!</h1>"]]
-}
+client = Quicsilver::Client.new("127.0.0.1", 4433, unsecure: true)
+client.connect
 
-server = Quicsilver::Server.new(4433, app: app)
-server.start
-server.wait_for_connections
+response = client.get("/api/users")
+puts response[:body]
+
+response = client.post("/api/users", body: '{"name": "charlie"}')
+
+client.disconnect
 ```
 
-### HTTP/3 Client
+## Usage with Rails
 
-```ruby
-require "quicsilver"
+```bash
+rackup -s quicsilver -p 4433
+```
 
-client = Quicsilver::Client.new("127.0.0.1", 4433, unsecure: true)
-client.connect
+## Configuration
 
-# Send HTTP/3 request
-request = Quicsilver::HTTP3::RequestEncoder.new(
-  method: 'GET',
-  path: '/api/users',
-  authority: 'example.com'
+```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
 )
-client.send_data(request.encode)
 
-client.disconnect
+server = Quicsilver::Server.new(4433,
+  app: app,
+  address: "0.0.0.0",
+  server_configuration: config
+)
 ```
 
 ## Development
 
 ```bash
-# Run tests
-rake test
-
-# Build extension
-rake compile
-
-# Clean build artifacts
-rake clean
+rake compile  # Build C extension
+rake test     # Run tests
+rake clean    # Clean build artifacts
 ```
 
 ## License

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