quicsilver 0.2.0 → 0.4.0

data/examples/README.md

@@ -1,105 +1,58 @@
-# Quicsilver Examples
+# Examples
 
-This directory contains examples for testing your Ruby QUIC implementation.
+Self-contained scripts demonstrating quicsilver features. Each boots its own server — no external setup needed.
 
-## 🚀 Quick Start
-
-### 1. Generate Certificates
+## Getting Started
 
 ```bash
-cd examples
-./setup_certs.sh
-```
-
-This creates the necessary certificate files in the `certs/` directory.
-
-### 2. Run the Server
+# Server
+ruby examples/minimal_http3_server.rb
+curl --http3-only -k https://localhost:4433/
+
+# Client
+ruby examples/simple_client_test.rb
+```
+
+## Examples
+
+| Script | Feature |
+|--------|---------|
+| `minimal_http3_server.rb` | Simplest HTTP/3 server |
+| `rack_http3_server.rb` | Rack app with multiple routes |
+| `protocol_http_server.rb` | Protocol-http mode |
+| `simple_client_test.rb` | Basic client request |
+| `connection_pool_demo.rb` | Connection reuse — 6ms first, 0.2ms reused |
+| `feature_demo.rb` | All features in one script |
+| `streaming_sse.rb` | Server-Sent Events over HTTP/3 |
+| `priorities.rb` | Extensible Priorities (RFC 9218) — CSS before images |
+| `trailers.rb` | Trailing headers after body |
+| `grpc_style.rb` | gRPC-style request/response with JSON (no protobuf needed) |
+| `falcon_middleware.rb` | Falcon's middleware stack over HTTP/3 (requires falcon gem) |
+| `benchmark.rb` | Throughput benchmark |
+| `rails_feature_test.rb` | 15 feature tests against a Rails app |
+
+## Rails Integration
 
 ```bash
-# Terminal 1
-ruby examples/test_server.rb
-```
-
-### 3. Test the Connection
-
-```bash
-# Terminal 2  
-ruby examples/test_connection.rb
-```
-
-## 📁 Files
-
-| File | Purpose |
-|------|---------|
-| `setup_certs.sh` | Generate certificates for testing |
-| `test_server.rb` | Ruby QUIC server |
-| `test_connection.rb` | QUIC client test |
-
-## ✅ Expected Output
-
-**Server:**
-```
-🔥 Quicsilver QUIC Server Test
-════════════════════════════════════════
-📋 Server Info:
-   server_id: a47271c7ae4276d5
-   address: 127.0.0.1
-   port: 4433
-   running: false
-   cert_file: /path/to/certs/server.crt
-   key_file: /path/to/certs/server.key
-   max_connections: 100
+# 1. Add to Gemfile
+gem "quicsilver"
 
-🚀 Starting QUIC server on 127.0.0.1:4433
-✅ QUIC server started successfully!
-   🔗 Listening for connections...
-🎯 Server is running! Press Ctrl+C to stop
-```
+# 2. Start
+rackup -s quicsilver -p 4433
 
-**Client:**
+# 3. Test
+curl --http3-only -k https://localhost:4433/
 ```
-🔗 Testing QUIC Connection to 127.0.0.1:4433...
 
-Connected to 127.0.0.1:4433
-✅ SUCCESS! Connected to QUIC server
-   🕐 Connection time: 13.5ms
-   📊 Connected status: true
-   📋 Connection info: {"connected" => true, "failed" => false, ...}
-
-🧪 Testing connection stability...
-   ⏱️  Tick 1: Connected = true
-   ⏱️  Tick 2: Connected = true  
-   ⏱️  Tick 3: Connected = true
-✅ Connection test completed!
-🔒 Connection closed cleanly
-```
+## Falcon Integration
 
-## 🔧 Manual Certificate Setup
-
-If you prefer to create certificates manually:
-
-```bash
-mkdir -p certs
-cd certs
+No extra gems or config needed — just pass Falcon's middleware:
 
-# Generate private key
-openssl genrsa -out server.key 2048
+```ruby
+require "falcon"
+require "quicsilver"
 
-# Generate certificate with proper QUIC extensions
-openssl req -new -x509 -key server.key -out server.crt -days 365 \
-  -subj "/CN=localhost/O=QuicsilverTest/C=US" \
-  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1" \
-  -addext "extendedKeyUsage=serverAuth"
+middleware = Falcon::Server.middleware(Rails.application)
+config = Quicsilver::Transport::Configuration.new(cert, key, mode: :falcon)
+Quicsilver::Server.new(4433, app: middleware, server_configuration: config).start
 ```
-
-## 🐛 Troubleshooting
-
-**Port in use error:** The server automatically cleans up port 4433 before starting.
-
-**Connection refused:** Make sure the server is running before testing the client.
-
-**Certificate errors:** Run `./setup_certs.sh` to regenerate certificates with proper QUIC extensions.
-
----
-
-That's it! No Docker, no external servers, just pure Ruby QUIC. 🎯 

data/examples/benchmark.rb

@@ -0,0 +1,111 @@
+#!/usr/bin/env ruby
+
+# Quicsilver benchmark — self-contained, boots its own server.
+#
+#   ruby examples/benchmark.rb
+
+require_relative "example_helper"
+
+HOST = "localhost"
+PORT = 4433
+WARMUP = 10
+ITERATIONS = 200
+
+app = ->(env) {
+  case env["PATH_INFO"]
+  when "/large"
+    [200, { "content-type" => "application/octet-stream" }, ["x" * 50_000]]
+  else
+    [200, { "content-type" => "application/json" }, ['{"ok":true}']]
+  end
+}
+
+server = Quicsilver::Server.new(PORT, app: app, server_configuration: EXAMPLE_TLS_CONFIG)
+server_thread = Thread.new { server.start }
+sleep 0.3
+
+def run_benchmark(name, iterations)
+  times = iterations.times.map { yield }
+  total = times.sum
+  avg = (total / times.size).round(2)
+  p50 = times.sort[times.size / 2].round(2)
+  p99 = times.sort[(times.size * 0.99).to_i].round(2)
+  rps = (times.size / (total / 1000.0)).round(0)
+  puts "  Total:   #{total.round(1)}ms"
+  puts "  Avg:     #{avg}ms"
+  puts "  p50:     #{p50}ms"
+  puts "  p99:     #{p99}ms"
+  puts "  RPS:     #{rps} req/s"
+end
+
+puts "🔨 Quicsilver Benchmark"
+puts "=" * 60
+
+# === 1. Sequential (single connection) ===
+puts "\n📊 Sequential — single connection, #{ITERATIONS} requests"
+puts "-" * 60
+
+client = Quicsilver::Client.new(HOST, PORT, unsecure: true)
+WARMUP.times { client.get("/ping") }
+
+run_benchmark("Sequential", ITERATIONS) do
+  t = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  client.get("/ping")
+  (Process.clock_gettime(Process::CLOCK_MONOTONIC) - t) * 1000
+end
+client.disconnect
+
+# === 2. Pooled ===
+puts "\n📊 Pooled — connection pool, #{ITERATIONS} requests"
+puts "-" * 60
+
+WARMUP.times { Quicsilver::Client.get(HOST, PORT, "/ping", unsecure: true) }
+
+run_benchmark("Pooled", ITERATIONS) do
+  t = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  Quicsilver::Client.get(HOST, PORT, "/ping", unsecure: true)
+  (Process.clock_gettime(Process::CLOCK_MONOTONIC) - t) * 1000
+end
+Quicsilver::Client.close_pool
+
+# === 3. Large payload ===
+puts "\n📊 Large payload — 50KB response, #{ITERATIONS} requests"
+puts "-" * 60
+
+client = Quicsilver::Client.new(HOST, PORT, unsecure: true)
+WARMUP.times { client.get("/large") }
+
+run_benchmark("Large", ITERATIONS) do
+  t = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  client.get("/large")
+  (Process.clock_gettime(Process::CLOCK_MONOTONIC) - t) * 1000
+end
+
+client.disconnect
+
+# === 4. True multiplexing ===
+puts "\n📊 True multiplexing — concurrent streams, single connection"
+puts "-" * 60
+
+client = Quicsilver::Client.new(HOST, PORT, unsecure: true)
+WARMUP.times { client.get("/ping") }
+
+[1, 5, 10, 20, 50].each do |concurrent|
+  t = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  requests = concurrent.times.map { client.get("/ping") { |req| req } }
+  responses = requests.map(&:response)
+  elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t) * 1000).round(1)
+  ok = responses.count { |r| r[:status] == 200 }
+  rps = (concurrent / (elapsed / 1000.0)).round(0)
+  puts "  #{concurrent.to_s.rjust(3)} streams: #{elapsed.to_s.rjust(7)}ms  #{ok}/#{concurrent} ok  #{rps} req/s"
+end
+
+client.disconnect
+
+# Cleanup
+Quicsilver::Client.close_pool
+server.stop
+server_thread.join(2)
+
+puts "\n" + "=" * 60
+puts "✅ Benchmark complete"

data/examples/connection_pool_demo.rb

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+
+# Demonstrates connection pooling.
+#
+#   ruby examples/connection_pool_demo.rb
+#
+# To compare with main (no pooling), checkout main and run:
+#
+#   ruby examples/simple_client_test.rb
+#
+# Each request on main pays the full QUIC handshake cost.
+# With pooling, only the first request pays it.
+
+require_relative "example_helper"
+
+PORT = 4433
+HOST = "localhost"
+
+# Start a simple server in-process
+app = ->(env) { [200, { "content-type" => "text/plain" }, ["Hello from #{env['PATH_INFO']}"]] }
+server = Quicsilver::Server.new(PORT, app: app, server_configuration: EXAMPLE_TLS_CONFIG)
+server_thread = Thread.new { server.start }
+sleep 0.3
+
+puts "Connection Pool Demo"
+puts "=" * 50
+
+puts "\n🔄 Client.get — pooling is automatic"
+puts "-" * 50
+
+6.times do |i|
+  t = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  response = Quicsilver::Client.get(HOST, PORT, "/request-#{i}", unsecure: true)
+  elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t) * 1000).round(1)
+
+  label = i == 0 ? "← new connection + QUIC handshake" : "← reused"
+  puts "  Request #{i}: #{response[:status]} — #{elapsed}ms #{label}"
+end
+
+puts "\n  Pool: #{Quicsilver::Client.pool.size} connection(s) ready for reuse"
+
+# --- Cleanup ---
+Quicsilver::Client.close_pool
+server.stop
+server_thread.join(2)
+
+puts "\n✅ Done"

data/examples/example_helper.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Shared helper for examples — uses the `localhost` gem to generate
+# self-signed TLS certificates so examples work without manual setup.
+#
+# Usage:
+#   require_relative "example_helper"
+#   server = Quicsilver::Server.new(4433, app: app, server_configuration: EXAMPLE_TLS_CONFIG)
+
+require "bundler/setup"
+require "quicsilver"
+require "localhost/authority"
+
+authority = Localhost::Authority.fetch
+EXAMPLE_TLS_CONFIG = Quicsilver::Transport::Configuration.new(
+  authority.certificate_path,
+  authority.key_path
+)

data/examples/falcon_middleware.rb

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+
+# Quicsilver with Falcon's middleware stack over HTTP/3.
+#
+# Falcon provides caching, content encoding, and protocol-rack.
+# Quicsilver provides the HTTP/3 transport.
+#
+# Prerequisites: gem install falcon
+#
+#   ruby examples/falcon_middleware.rb
+#   curl --http3-only -k https://localhost:4433/
+
+require_relative "example_helper"
+
+begin
+  require "falcon"
+rescue LoadError
+  puts "❌ Falcon not installed. Run: gem install falcon"
+  exit 1
+end
+
+app = ->(env) {
+  [200, { "content-type" => "application/json" }, [
+    %({"protocol":"#{env['SERVER_PROTOCOL']}","server":"quicsilver+falcon"})
+  ]]
+}
+
+# Falcon's middleware adds caching, content encoding, etc.
+middleware = Falcon::Server.middleware(app)
+
+config = Quicsilver::Transport::Configuration.new(
+  EXAMPLE_TLS_CONFIG.cert_file,
+  EXAMPLE_TLS_CONFIG.key_file,
+  mode: :falcon
+)
+
+server = Quicsilver::Server.new(4433, app: middleware, server_configuration: config)
+
+puts "🦅 Quicsilver + Falcon Middleware"
+puts "   https://localhost:4433"
+puts "   curl --http3-only -k https://localhost:4433/"
+puts
+
+server.start

data/examples/feature_demo.rb

@@ -0,0 +1,125 @@
+#!/usr/bin/env ruby
+
+# Demonstrates all major quicsilver features in one script.
+#
+#   ruby examples/feature_demo.rb
+
+require_relative "example_helper"
+
+PORT = 4433
+HOST = "localhost"
+
+# === Server with multiple endpoints ===
+app = ->(env) {
+  path = env["PATH_INFO"]
+  method = env["REQUEST_METHOD"]
+
+  case path
+  when "/"
+    [200, { "content-type" => "text/plain" }, ["Hello HTTP/3!\n"]]
+
+  when "/api/users"
+    [200, { "content-type" => "application/json" },
+     ['{"users":["alice","bob","charlie"]}']]
+
+  when "/stream"
+    # Streaming body — chunks sent as they're generated
+    body = Enumerator.new do |y|
+      5.times do |i|
+        y << "chunk #{i}\n"
+        sleep 0.01
+      end
+    end
+    [200, { "content-type" => "text/plain" }, body]
+
+  when "/large"
+    # Large response for priority testing
+    [200, { "content-type" => "text/plain" }, ["x" * 10_000]]
+
+  when "/echo"
+    # Echo POST body back
+    body = env["rack.input"]&.read || ""
+    [200, { "content-type" => "text/plain", "content-length" => body.bytesize.to_s }, [body]]
+
+  else
+    [404, { "content-type" => "text/plain" }, ["Not Found"]]
+  end
+}
+
+server = Quicsilver::Server.new(PORT, app: app, server_configuration: EXAMPLE_TLS_CONFIG)
+server_thread = Thread.new { server.start }
+sleep 0.3
+
+puts "🚀 Quicsilver Feature Demo"
+puts "=" * 60
+
+# === 1. Connection Pooling ===
+puts "\n1️⃣  Connection Pooling"
+puts "-" * 60
+
+6.times do |i|
+  t = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  response = Quicsilver::Client.get(HOST, PORT, "/", unsecure: true)
+  elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t) * 1000).round(1)
+  label = i == 0 ? "← handshake" : "← reused"
+  puts "  Request #{i}: #{response[:status]} — #{elapsed}ms #{label}"
+end
+
+# === 2. Multiple Endpoints ===
+puts "\n2️⃣  Multiple Endpoints"
+puts "-" * 60
+
+["/", "/api/users", "/stream", "/nonexistent"].each do |path|
+  response = Quicsilver::Client.get(HOST, PORT, path, unsecure: true)
+  body_preview = response[:body][0..50].gsub("\n", "\\n")
+  puts "  GET #{path} → #{response[:status]} | #{body_preview}"
+end
+
+# === 3. POST with Body ===
+puts "\n3️⃣  POST with Echo"
+puts "-" * 60
+
+response = Quicsilver::Client.post(HOST, PORT, "/echo",
+  body: "Hello from quicsilver client!",
+  headers: { "content-type" => "text/plain" },
+  unsecure: true)
+puts "  POST /echo → #{response[:status]} | #{response[:body]}"
+
+# === 4. Concurrent Requests ===
+puts "\n4️⃣  Concurrent Requests (multiplexing)"
+puts "-" * 60
+
+client = Quicsilver::Client.new(HOST, PORT, unsecure: true)
+t_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+10.times do |i|
+  t = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  response = client.get("/api/users")
+  elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t) * 1000).round(1)
+  puts "  Request #{i}: #{response[:status]} — #{elapsed}ms"
+end
+total = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t_start) * 1000).round(1)
+puts "  All 10 completed in #{total}ms (single connection)"
+client.disconnect
+
+# === 5. HTTP Methods ===
+puts "\n5️⃣  HTTP Methods"
+puts "-" * 60
+
+client = Quicsilver::Client.new(HOST, PORT, unsecure: true)
+%i[get post put patch delete head].each do |method|
+  response = client.public_send(method, "/api/users")
+  body_size = response[:body]&.bytesize || 0
+  puts "  #{method.to_s.upcase.ljust(6)} /api/users → #{response[:status]} (#{body_size} bytes)"
+end
+client.disconnect
+
+# === Summary ===
+puts "\n" + "=" * 60
+puts "✅ All features working!"
+puts "   Pool: #{Quicsilver::Client.pool.size} connection(s)"
+
+# === Cleanup ===
+Quicsilver::Client.close_pool
+server.stop
+server_thread.join(2)
+puts "👋 Done"

data/examples/grpc_style.rb

@@ -0,0 +1,97 @@
+#!/usr/bin/env ruby
+
+# gRPC-style request/response over HTTP/3.
+#
+# gRPC is just HTTP with:
+#   - content-type: application/grpc (or application/grpc+json)
+#   - 5-byte frame prefix: [compressed(1)][length(4)][message]
+#   - Status in trailers: grpc-status, grpc-message
+#
+# This example uses JSON for simplicity. In production you'd use
+# protobuf (google-protobuf gem) for smaller, faster serialization.
+# Quicsilver carries the bytes — the app chooses the encoding.
+#
+#   ruby examples/grpc_style.rb
+
+require_relative "example_helper"
+require "json"
+
+PORT = 4433
+HOST = "localhost"
+
+# gRPC frame: [0x00][4-byte big-endian length][message]
+def grpc_encode(message)
+  data = message.to_json
+  [0, data.bytesize].pack("CN") + data
+end
+
+def grpc_decode(frame)
+  _compressed, length = frame.unpack("CN")
+  JSON.parse(frame[5, length])
+end
+
+app = ->(env) {
+  path = env["PATH_INFO"]
+  body = env["rack.input"]&.read || ""
+
+  case path
+  when "/grpc.UserService/GetUser"
+    request = grpc_decode(body) rescue { "error" => "bad frame" }
+    user = { "id" => request["id"], "name" => "Alice", "email" => "alice@example.com" }
+    response_frame = grpc_encode(user)
+
+    [200,
+     { "content-type" => "application/grpc+json" },
+     [response_frame]]
+
+  when "/grpc.UserService/ListUsers"
+    users = [
+      { "id" => 1, "name" => "Alice" },
+      { "id" => 2, "name" => "Bob" },
+      { "id" => 3, "name" => "Charlie" }
+    ]
+    response_frame = grpc_encode(users)
+
+    [200,
+     { "content-type" => "application/grpc+json" },
+     [response_frame]]
+
+  else
+    [404, { "content-type" => "text/plain" }, ["Unknown gRPC method: #{path}"]]
+  end
+}
+
+server = Quicsilver::Server.new(PORT, app: app, server_configuration: EXAMPLE_TLS_CONFIG)
+server_thread = Thread.new { server.start }
+sleep 0.3
+
+puts "🔌 gRPC-style over HTTP/3 (JSON, no protobuf)"
+puts "=" * 50
+
+client = Quicsilver::Client.new(HOST, PORT, unsecure: true)
+
+# GetUser
+puts "\n  GetUser(id=1):"
+request_frame = grpc_encode({ "id" => 1 })
+response = client.post("/grpc.UserService/GetUser",
+  body: request_frame,
+  headers: { "content-type" => "application/grpc+json" })
+user = grpc_decode(response[:body])
+puts "    → #{user}"
+
+# ListUsers
+puts "\n  ListUsers():"
+request_frame = grpc_encode({})
+response = client.post("/grpc.UserService/ListUsers",
+  body: request_frame,
+  headers: { "content-type" => "application/grpc+json" })
+users = grpc_decode(response[:body])
+puts "    → #{users}"
+
+puts "\n  gRPC is just HTTP + framing. Quicsilver carries the bytes."
+puts "  This example uses JSON — swap in protobuf for production."
+
+client.disconnect
+server.stop
+server_thread.join(2)
+puts "\n✅ Done"

data/examples/minimal_http3_server.rb

@@ -1,26 +1,14 @@
 #!/usr/bin/env ruby
 
-require "bundler/setup"
-require "quicsilver"
+require_relative "example_helper"
 
 puts "🚀 Minimal HTTP/3 Server Example"
 puts "=" * 40
 
-# Create and start the server
-server = Quicsilver::Server.new(4433)
+server = Quicsilver::Server.new(4433, server_configuration: EXAMPLE_TLS_CONFIG)
 
-puts "🔧 Starting server..."
-server.start
-
-puts "✅ Server is running on port 4433"
-puts "📋 Server info: #{server.server_info}"
+puts "✅ Listening on https://localhost:4433"
+puts "⏳ Press Ctrl+C to stop."
+puts
 
-# Keep the server running
-puts "⏳ Server is running. Press Ctrl+C to stop..."
-begin
-  server.wait_for_connections
-rescue Interrupt
-  puts "\n🛑 Stopping server..."
-  server.stop
-  puts "👋 Server stopped"
-end 
+server.start

data/examples/priorities.rb

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+
+# HTTP/3 Extensible Priorities (RFC 9218).
+#
+# Browsers send priority hints: CSS is urgency 0 (highest),
+# images are urgency 5 (low). Quicsilver parses these and tells
+# MsQuic to send high-priority data first.
+#
+#   ruby examples/priorities.rb
+#
+# Then from another terminal, the client fires CSS and image
+# requests and shows the priority was parsed.
+
+require_relative "example_helper"
+
+PORT = 4433
+HOST = "localhost"
+
+app = ->(env) {
+  path = env["PATH_INFO"]
+
+  case path
+  when "/style.css"
+    # Browsers send: priority: u=0 (highest urgency)
+    [200, { "content-type" => "text/css" }, ["body { margin: 0; }\n" * 50]]
+  when "/image.png"
+    # Browsers send: priority: u=5 (low urgency)
+    [200, { "content-type" => "image/png" }, ["x" * 10_000]]
+  else
+    [200, { "content-type" => "text/html" }, [
+      "<link rel='stylesheet' href='/style.css'>\n<img src='/image.png'>\n"
+    ]]
+  end
+}
+
+server = Quicsilver::Server.new(PORT, app: app, server_configuration: EXAMPLE_TLS_CONFIG)
+server_thread = Thread.new { server.start }
+sleep 0.3
+
+puts "🎯 HTTP/3 Priorities Demo"
+puts "=" * 50
+
+client = Quicsilver::Client.new(HOST, PORT, unsecure: true)
+
+# Request with priority header (what a browser would send)
+puts "\n  CSS request (high priority):"
+response = client.get("/style.css", headers: { "priority" => "u=0, i" })
+puts "    Status: #{response[:status]}, Size: #{response[:body].bytesize} bytes"
+
+puts "\n  Image request (low priority):"
+response = client.get("/image.png", headers: { "priority" => "u=5" })
+puts "    Status: #{response[:status]}, Size: #{response[:body].bytesize} bytes"
+
+puts "\n  MsQuic schedules CSS data before image data"
+puts "  when both are in flight on the same connection."
+
+client.disconnect
+server.stop
+server_thread.join(2)
+puts "\n✅ Done"