quicsilver 0.5.0-x86_64-linux

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

@@ -0,0 +1,58 @@
+# Examples
+
+Self-contained scripts demonstrating quicsilver features. Each boots its own server — no external setup needed.
+
+## Getting Started
+
+```bash
+# 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
+# 1. Add to Gemfile
+gem "quicsilver"
+
+# 2. Start
+rackup -s quicsilver -p 4433
+
+# 3. Test
+curl --http3-only -k https://localhost:4433/
+```
+
+## Falcon Integration
+
+No extra gems or config needed — just pass Falcon's middleware:
+
+```ruby
+require "falcon"
+require "quicsilver"
+
+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
+```

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

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"