quicsilver 0.3.0 → 0.5.0

data/docs/connection_identity.md

@@ -0,0 +1,141 @@
+# Connection identity and QUIC routing IDs
+
+## Rack request identity
+
+Rack apps receive these env values:
+
+- `env["quicsilver.connection_id"]`
+  - Opaque QUIC connection identity.
+  - Stable across requests/streams on the same QUIC connection.
+  - Currently backed by MsQuic's original destination connection ID.
+  - Do not parse this for load-balancing or backend routing decisions.
+
+- `env["quicsilver.stream_id"]`
+  - QUIC stream id for this HTTP/3 request.
+  - Different requests on the same connection have different stream ids.
+
+- `env["quicsilver.request_id"]`
+  - Recommended app/log/correlation identity.
+  - Format without fixed server id:
+    - `<connection_id>:<stream_id>`
+  - Format with fixed server id:
+    - `<transport_server_id>:<connection_id>:<stream_id>`
+  - This is the value applications and middleware should prefer.
+
+Quicsilver does not expose separate Rack env fields for transport-only routing metadata such as `transport_server_id` or the original destination CID. Use `quicsilver.request_id` for request correlation.
+
+## Fixed MsQuic Server ID
+
+`transport_server_id` configures MsQuic's fixed 4-byte Server ID.
+
+- Purpose:
+  - Allows QUIC-aware load balancers to route using the server id embedded in MsQuic-generated connection IDs.
+  - Useful after the server has generated CIDs for an established connection.
+
+- Configuration:
+
+  ```ruby
+  config = Quicsilver::Transport::Configuration.new(
+    cert_file,
+    key_file,
+    transport_server_id: "01020304"
+  )
+  ```
+
+- Rules:
+  - Must be exactly 4 bytes encoded as 8 hex characters.
+  - Hex is normalized to lowercase.
+  - Server startup applies this before MsQuic is opened.
+  - This is MsQuic process-global state, so set it once per server process/pod.
+
+- Common deployment pattern:
+
+  ```ruby
+  config = Quicsilver::Transport::Configuration.new(
+    cert_file,
+    key_file,
+    transport_server_id: ENV["QUICSILVER_TRANSPORT_SERVER_ID"]
+  )
+  ```
+
+  ```sh
+  QUICSILVER_TRANSPORT_SERVER_ID=01020304 bundle exec ruby server.rb
+  ```
+
+When configured, Rack request ids include the server id prefix:
+
+```text
+01020304:7f9a23c001de88b0:4
+```
+
+## CIBIR ID
+
+`cibir_id` configures MsQuic CIBIR: Connection ID Based Implicit Routing.
+
+- Purpose:
+  - Provides routing bytes in the client's destination connection ID.
+  - Useful for routing the first packet/initial connection to the right listener or shard.
+  - The meaning of the bytes is application/load-balancer defined.
+
+- Server/listener configuration:
+
+  ```ruby
+  config = Quicsilver::Transport::Configuration.new(
+    cert_file,
+    key_file,
+    cibir_id: "0a"
+  )
+  ```
+
+- Client configuration:
+
+  ```ruby
+  client = Quicsilver::Client.new(
+    "example.com",
+    4433,
+    transport_cibir_id: "0a"
+  )
+  ```
+
+- Rules:
+  - Must be 1..6 bytes encoded as an even-length hex string.
+  - Hex is normalized to lowercase.
+  - MsQuic currently supports CIBIR at offset `0` only.
+  - CIBIR must be configured consistently on both ends:
+    - Server/listener: `cibir_id: "0a"`
+    - Client: `transport_cibir_id: "0a"`
+  - If one side uses CIBIR and the other side does not, MsQuic rejects the connection during handshake.
+  - If the client sends the wrong CIBIR bytes, packets may not route to the configured listener/backend.
+  - CIBIR is transport routing configuration, not Rack request identity.
+
+## How the pieces differ
+
+- `cibir_id`
+  - Client-selected routing bytes.
+  - Used at listener/connection start time.
+  - Helps route initial packets before server-generated CIDs matter.
+
+- `transport_server_id`
+  - Server-selected fixed 4-byte id.
+  - Embedded by MsQuic in server-generated CIDs.
+  - Helps QUIC-aware load balancers route established connections by backend/server.
+
+- `connection_id`
+  - App-facing opaque connection identity.
+  - Stable across streams on the same QUIC connection.
+  - Not guaranteed to be the same CID a load balancer sees on the wire.
+
+- `stream_id`
+  - Per-request QUIC stream identity.
+
+- `request_id`
+  - App-facing request correlation value.
+  - Combines the stable connection identity and stream id.
+  - Includes `transport_server_id` as a prefix when configured.
+
+## Recommended usage
+
+- Log `env["quicsilver.request_id"]` for application request correlation.
+- Treat `env["quicsilver.connection_id"]` as opaque.
+- Configure `transport_server_id` when QUIC-aware infrastructure needs backend routing by server-generated CIDs.
+- Configure `cibir_id` / `transport_cibir_id` together when client-chosen destination CID bytes are part of your routing scheme.

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,191 @@
+#!/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]]
+  when "/work"
+    sleep 0.001
+    [200, { "content-type" => "application/json" }, ['{"ok":true}']]
+  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
+# === 5. Multi-threaded concurrency ===
+puts "\n📊 Multi-threaded — concurrent clients, #{ITERATIONS} total requests"
+puts "-" * 60
+
+[1, 2, 4, 8].each do |thread_count|
+  requests_per_thread = ITERATIONS / thread_count
+  err_count = 0
+  mu = Mutex.new
+
+  # Connect all clients sequentially (connection setup is serialized)
+  clients = thread_count.times.map do
+    c = Quicsilver::Client.new(HOST, PORT, unsecure: true, request_timeout: 10)
+    c.open_connection
+    c
+  end
+
+  # Run requests in parallel
+  start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  threads = clients.map do |client|
+    Thread.new do
+      requests_per_thread.times do
+        client.get("/ping")
+      rescue => e
+        mu.synchronize { err_count += 1 }
+      end
+    end
+  end
+  threads.each(&:join)
+  elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(1)
+
+  clients.each(&:disconnect)
+
+  rps = (ITERATIONS / (elapsed / 1000.0)).round(0)
+  err = err_count > 0 ? "  (#{err_count} errors)" : ""
+  puts "  #{thread_count.to_s.rjust(3)} threads: #{elapsed.to_s.rjust(7)}ms  #{rps} req/s#{err}"
+  sleep 0.1
+end
+
+# === 6. Multi-threaded with simulated work ===
+puts "\n📊 Multi-threaded with 1ms app work, 50 total requests"
+puts "-" * 60
+
+[1, 2, 4, 8].each do |thread_count|
+  reqs = 50
+  requests_per_thread = reqs / thread_count
+  err_count = 0
+  mu = Mutex.new
+
+  clients = thread_count.times.map do
+    c = Quicsilver::Client.new(HOST, PORT, unsecure: true, request_timeout: 10)
+    c.open_connection
+    c
+  end
+
+  start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  threads = clients.map do |client|
+    Thread.new do
+      requests_per_thread.times do
+        client.get("/work")
+      rescue => e
+        mu.synchronize { err_count += 1 }
+      end
+    end
+  end
+  threads.each(&:join)
+  elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(1)
+
+  clients.each(&:disconnect)
+
+  rps = (reqs / (elapsed / 1000.0)).round(0)
+  err = err_count > 0 ? "  (#{err_count} errors)" : ""
+  puts "  #{thread_count.to_s.rjust(3)} threads: #{elapsed.to_s.rjust(7)}ms  #{rps} req/s#{err}"
+  sleep 0.1
+end
+
+# 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,69 @@
+# 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 "json"
+require "socket"
+require "thread"
+require "quicsilver"
+require "localhost/authority"
+
+authority = Localhost::Authority.fetch
+EXAMPLE_TLS_CONFIG = Quicsilver::Transport::Configuration.new(
+  authority.certificate_path,
+  authority.key_path
+)
+
+module Example
+  module_function
+
+  def wait_until(timeout: 5, interval: 0.01)
+    deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+    until yield
+      raise "timed out waiting" if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+      sleep interval
+    end
+  end
+
+  def available_udp_port(host = "127.0.0.1")
+    socket = UDPSocket.new
+    socket.bind(host, 0)
+    socket.addr[1]
+  ensure
+    socket&.close
+  end
+
+  def json_response(status, body)
+    [status, { "content-type" => "application/json" }, [JSON.generate(body) << "\n"]]
+  end
+
+  def text_response(status, body)
+    [status, { "content-type" => "text/plain" }, [body]]
+  end
+
+  def say(line = "")
+    puts line
+  end
+
+  def heading(text, level: 2)
+    say unless heading_count.zero?
+    say "#{'#' * level} #{text}"
+    @heading_count += 1
+  end
+
+  def detail(label, value, width: 22)
+    say format("  %-#{width}s %s", label, value)
+  end
+
+
+  def heading_count
+    @heading_count ||= 0
+  end
+end

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