quicsilver 0.5.0-x86_64-linux

data/README.md

@@ -0,0 +1,261 @@
+# Quicsilver
+
+HTTP/3 server and client for Ruby with Rack support.
+
+## Why HTTP/3?
+
+- **No head-of-line blocking** — one slow response doesn't stall others. HTTP/2 multiplexes over TCP, but a single lost packet freezes all streams. QUIC streams are independent.
+- **Faster connections** — QUIC handshake is 1 round trip (TCP+TLS is 3). Returning users get 0-RTT — zero round trips.
+- **Connection migration** — users switch from wifi to cellular without dropping the connection.
+- **True multiplexing** — many concurrent requests on one connection, each on its own stream.
+
+## 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
+- **Falcon middleware compatible** — use Falcon's caching and content encoding over HTTP/3
+
+## Installation
+
+```bash
+git clone https://github.com/hahmed/quicsilver
+cd quicsilver
+bundle install
+rake compile
+```
+
+## Quick Start
+
+### Server
+
+```ruby
+require "quicsilver"
+require "localhost/authority"
+
+app = ->(env) {
+  [200, {"content-type" => "text/plain"}, ["Hello HTTP/3!"]]
+}
+
+authority = Localhost::Authority.fetch
+config = Quicsilver::Transport::Configuration.new(
+  authority.certificate_path,
+  authority.key_path
+)
+
+server = Quicsilver::Server.new(4433, app: app, server_configuration: config)
+server.start
+```
+
+### Client
+
+```ruby
+require "quicsilver"
+
+# Class-level API with automatic connection pooling.
+# Clients verify TLS certificates by default, so the hostname must match the cert.
+response = Quicsilver::Client.get("localhost", 4433, "/")
+puts response[:status]  # => 200
+puts response[:body]    # => "Hello HTTP/3!"
+
+# POST with body
+response = Quicsilver::Client.post("localhost", 4433, "/api/users",
+  body: '{"name": "alice"}',
+  headers: { "content-type" => "application/json" })
+
+# Instance-level for more control. Use unsecure: true only for
+# local/self-signed test servers.
+client = Quicsilver::Client.new("localhost", 4433, unsecure: true)
+response = client.get("/")
+client.disconnect
+```
+
+### Rails
+
+```bash
+rackup -s quicsilver -p 4433
+```
+
+In development, the Rackup handler can use the `localhost` gem to generate
+local certificates automatically. In production, pass both `cert_file` and
+`key_file` Rackup options explicitly:
+
+```bash
+rackup -s quicsilver -p 4433 \
+  -O cert_file=/path/to/fullchain.pem \
+  -O key_file=/path/to/privkey.pem
+```
+
+### curl
+
+```bash
+curl --http3-only -k https://localhost:4433/
+```
+
+### TLS Certificates
+
+HTTP/3 always runs over TLS. Core server configuration never guesses
+certificate paths: `Quicsilver::Transport::Configuration` requires both a
+certificate file and a private key file.
+
+For production, point Quicsilver at the same publicly-trusted certificate and
+key you use for your TCP HTTPS server:
+
+```ruby
+config = Quicsilver::Transport::Configuration.new(
+  ENV.fetch("TLS_CERT_FILE"),
+  ENV.fetch("TLS_KEY_FILE")
+)
+```
+
+For local development, Quicsilver depends on the
+[localhost](https://github.com/socketry/localhost) gem, which can generate a
+certificate for `localhost` or your local development hostname:
+
+```ruby
+require "localhost/authority"
+
+authority = Localhost::Authority.fetch
+config = Quicsilver::Transport::Configuration.new(
+  authority.certificate_path,
+  authority.key_path
+)
+```
+
+Run `bake localhost:install` once to add the localhost CA to your system trust
+store. You can still use `curl -k` or `unsecure: true` for quick local testing
+without trusting the CA.
+
+Quicsilver clients verify certificates by default. Disable verification only
+for local development or tests:
+
+```ruby
+client = Quicsilver::Client.new("localhost", 4433, unsecure: true)
+```
+
+### Browser Access
+
+Any HTTP/3 client connects directly — no extra setup needed.
+
+Browsers discover HTTP/3 via the `Alt-Svc` header from an existing HTTP/1.1
+or HTTP/2 server. Run quicsilver alongside your regular Rails/Rack server on
+the **same port** — TCP for HTTP/1.1+2, UDP for HTTP/3:
+
+```bash
+# Your normal Rails server (HTTP/1.1 + HTTP/2 over TCP)
+bin/rails server -p 3000
+
+# Quicsilver (HTTP/3 over UDP, same port)
+rackup -s quicsilver -p 3000
+```
+
+Add the `Alt-Svc` header so browsers discover HTTP/3. The port must match
+the port quicsilver is listening on:
+
+```ruby
+# config/application.rb
+config.action_dispatch.default_headers["Alt-Svc"] = 'h3=":3000"; ma=86400'
+```
+
+With a publicly-trusted certificate (e.g. Let's Encrypt), browsers upgrade
+to HTTP/3 automatically via Alt-Svc — no special configuration needed.
+
+### Local Development
+
+Both your TCP server and quicsilver need a TLS certificate trusted by
+your system. Both servers **must use the same certificate**. The
+`localhost` gem can generate local certificates — run `bake localhost:install`
+to add the CA to your system trust store.
+
+Chrome requires one additional flag for local development because it
+does not allow QUIC connections with locally-trusted certificates:
+
+```bash
+chrome --origin-to-force-quic-on=myapp.test:3000 https://myapp.test:3000
+```
+
+This is not needed in production with publicly-trusted certificates.
+
+## Configuration
+
+Pass both certificate paths explicitly. Omitting either path raises a
+configuration error.
+
+```ruby
+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 schedules 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")
+```
+
+## Falcon Middleware Mode
+
+Use Falcon's middleware stack (caching, content encoding) over HTTP/3. Quicsilver handles the transport, Falcon's middleware handles the request pipeline:
+
+```ruby
+config = Quicsilver::Transport::Configuration.new(
+  "certificates/server.crt",
+  "certificates/server.key",
+  mode: :falcon
+)
+
+server = Quicsilver::Server.new(4433, app: app, server_configuration: config)
+server.start
+```
+
+| Mode | App Interface | Use Case |
+|------|---------------|----------|
+| `:rack` (default) | Rack env hash | Rails, Sinatra, any Rack app |
+| `:falcon` | Protocol::HTTP::Request | Falcon middleware stack |
+
+## Development
+
+```bash
+rake compile  # Build C extension (macOS: uses Apple clang automatically)
+rake test     # Run tests
+```
+
+## License
+
+MIT License

data/Rakefile

@@ -0,0 +1,130 @@
+require "bundler/setup"
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "rake/extensiontask"
+require_relative "ext/quicsilver/msquic_patch"
+
+Rake::ExtensionTask.new('quicsilver') do |ext|
+  ext.lib_dir = 'lib/quicsilver'
+end
+
+# Keep `rake compile` useful in source checkouts, but let cibuildgem own
+# extension compilation after the workflow has built and bundled MsQuic.
+task :compile => [:build_msquic, :bundle_msquic] unless ENV["CIBUILDGEM"]
+
+# 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')
+    sh 'git submodule add https://github.com/microsoft/msquic.git vendor/msquic'
+    sh 'cd vendor/msquic && git submodule update --init --recursive'
+  end
+end
+
+task :build_msquic => :setup do
+  MsquicPatch.apply!(File.expand_path("vendor/msquic", __dir__))
+  cmake_args = ['-B build', '-DCMAKE_BUILD_TYPE=Release', '-DQUIC_TLS_LIB=quictls', '-DQUIC_LINUX_IOURING_ENABLED=OFF']
+  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'
+  MsquicPatch.record_build!(File.expand_path("vendor/msquic", __dir__))
+end
+
+task :build => [:build_msquic, :compile]
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.ruby_opts << "-W0"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+Rake::TestTask.new(:test_unit) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.ruby_opts << "-W0"
+  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.ruby_opts << "-W0"
+  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

data/benchmarks/baseline.rb

@@ -0,0 +1,175 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Quicsilver baseline benchmark with a single-file Rails app.
+#
+# HTTP/3 is always TLS, so the client connects by the name on the certificate
+# and the server binds an address that name resolves to. Dialling 127.0.0.1
+# against a certificate issued for localhost fails verification, and on macOS
+# localhost resolves to ::1 first, so binding 127.0.0.1 is unreachable. Run
+# `bake localhost:install` once so the localhost CA is trusted.
+#
+# Read Failed before Req/s. A server that sheds reports better latency than one
+# that serves, because rejecting is quicker than answering.
+#
+# STREAMS is the only knob that loads the server. With one connection and one
+# stream nothing is ever concurrent, so Req/s is just 1000 / p50.
+#
+#   REQUESTS=2000                             latency, one request at a time
+#   STREAMS=10 REQUESTS=2000                  concurrent, inside capacity
+#   STREAMS=50 REQUESTS=5000                  concurrent, above the advertised
+#                                             stream limit: QUIC makes the
+#                                             extra streams wait
+#   WORKERS=50 STREAMS=50 REQUESTS=5000       capacity matched to the load
+#   WORKLOAD=big REQUESTS=50                  large bodies
+#   WORKLOAD=sleep SLEEP_SECONDS=0.1 REQUESTS=100   slow handler
+#
+# Capacity is WORKERS threads plus a queue of WORKERS * 4, and that total is
+# what the server advertises as its stream limit. Ten requests is a warm-up,
+# not a result: two runs of ten differed by 48% here.
+#
+# HOST      name to connect to, must match the certificate (default localhost)
+# ADDRESS   address to bind (default ::1, what localhost resolves to first)
+
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem "rails"
+  gem "localhost"
+  gem "falcon"
+  gem "puma"
+  gem "protocol-http"
+end
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "benchmark"
+require "localhost/authority"
+require "quicsilver"
+require_relative "helpers"
+
+REQUESTS = Integer(ENV.fetch("REQUESTS", "10"))
+CONNECTIONS = Integer(ENV.fetch("CONNECTIONS", "1"))
+STREAMS = Integer(ENV.fetch("STREAMS", "1"))
+WORKERS = Integer(ENV.fetch("WORKERS", "5"))
+WORKLOAD = ENV.fetch("WORKLOAD", "tiny")
+SLEEP_SECONDS = Float(ENV.fetch("SLEEP_SECONDS", "0.1"))
+HOST = ENV.fetch("HOST", "localhost")
+PORT = Integer(ENV.fetch("PORT", Benchmarks.random_port.to_s))
+PATH = Benchmarks.path_for(WORKLOAD)
+APP = Benchmarks.rails_app(sleep_seconds: SLEEP_SECONDS, secret_key_base: "quicsilver-benchmark")
+
+def start_server
+  authority = Localhost::Authority.fetch
+  config = Quicsilver::Transport::Configuration.new(authority.certificate_path, authority.key_path)
+  server = Quicsilver::Server.new(
+    PORT,
+    address: ENV.fetch("ADDRESS", "::1"),
+    app: APP,
+    server_configuration: config,
+    threads: WORKERS,
+  )
+
+  thread = Thread.new { server.start }
+  thread.abort_on_exception = true
+  wait_for_server(thread)
+  [server, thread]
+end
+
+def wait_for_server(thread)
+  deadline = Time.now + 10
+
+  while Time.now < deadline
+    abort "server exited while booting" unless thread.alive?
+
+    begin
+      client = Quicsilver::Client.new(HOST, PORT, connection_timeout: 500, request_timeout: 1)
+      client.open_connection
+      response = client.get("/")
+      return if response&.status == 200
+      warn "readiness check returned HTTP #{response&.status}: #{response&.body&.byteslice(0, 120).inspect}" if ENV["DEBUG"]
+    rescue StandardError => error
+      warn "readiness check failed: #{error.class}: #{error.message}" if ENV["DEBUG"]
+      sleep 0.1
+    ensure
+      client&.disconnect rescue nil
+    end
+  end
+
+  abort "server failed to boot: quicsilver://127.0.0.1:#{PORT}"
+end
+
+def stop_server(server, thread)
+  server&.stop rescue nil
+  thread&.join(5)
+end
+
+def start_request(connection, path)
+  connection.get(path) { |request| request }
+end
+
+def finish_request(request)
+  request.response
+end
+
+def request(connection, path)
+  finish_request(start_request(connection, path))
+end
+
+def open_connections
+  Array.new(CONNECTIONS) do
+    Quicsilver::Client.new(HOST, PORT, connection_timeout: 5000, request_timeout: 10).tap(&:open_connection)
+  end
+end
+
+def measure
+  connections = open_connections
+  # Untimed request per connection to warm Rails and establish steady connection state.
+  connections.each { |connection| request(connection, PATH) }
+
+  times = []
+  failed = 0
+
+  elapsed = Benchmark.realtime do
+    remaining = REQUESTS
+
+    while remaining.positive?
+      batch = []
+
+      connections.each do |connection|
+        STREAMS.times do
+          break if batch.length >= remaining
+
+          batch << [Benchmarks.now, start_request(connection, PATH)]
+        end
+      end
+
+      batch.each do |started_at, pending_request|
+        finish_request(pending_request)&.status == 200 ? times << (Benchmarks.now - started_at) : failed += 1
+      rescue StandardError
+        failed += 1
+      end
+
+      remaining -= batch.length
+    end
+  end
+
+  Benchmarks::Result.new(
+    requests: REQUESTS,
+    connections: CONNECTIONS,
+    streams: STREAMS,
+    times: times,
+    failed: failed,
+    elapsed: elapsed,
+  )
+ensure
+  connections&.each { |connection| connection.disconnect rescue nil }
+end
+
+begin
+  server, thread = start_server
+  Benchmarks.print_result("Quicsilver Rails baseline", measure, path: PATH, workers: WORKERS)
+ensure
+  stop_server(server, thread)
+end