quicsilver 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4926d24fbce141791505bb14d59e543a30a6c5cbf8ca3c3fd36c9123b2941db
-  data.tar.gz: 45c128c6bf9fc48b8267ba2927414f8429607e8f99e4169235d12ebe26863ccc
+  metadata.gz: 9f3ec155af92a08642dd37953aa75728a021f9868c964c0240a61b98399f72be
+  data.tar.gz: 6c5effb85af855cfd60761fc7aef9bdf0cc6901df1c56b478d22557705c55925
 SHA512:
-  metadata.gz: ad6f92657375909bac67ce88bfa64d47c53a2dd69bb424a36f297927778389247714c092b004287cc278c5ecdf94c0f186a4c15f4fa4cfff62dbef9fcfc155f6
-  data.tar.gz: 1f5d2812bfb18a15b1821c8afcb18f779663ec3066495ef69dfd9a1c79f8d83f13f7c6287b8ce56be318476ea69fd6c520c1dc4298ceb807c64f6de0747b3035
+  metadata.gz: 26490f0003dc3424abb07afaddd5fa9057d36a3cb2e974be2ea46b740069dc4114f95a46afa8d43e8f48c2d8dcc0a294187e6c9852806a97ae83f6841e01c9d9
+  data.tar.gz: 793d530b463494c8df0e6a0268686f0cd3588246300f1ef1763462f770949bbe0c04b20ef55599046486c3fb1383cf7207c9f317d8a0002a7c579b61f95d668a

data/.github/workflows/ci.yml

@@ -20,9 +20,17 @@ jobs:
   test:
 
     runs-on: ubuntu-24.04
+    continue-on-error: ${{ matrix.allow-failure }}
     strategy:
+      fail-fast: false
       matrix:
-        ruby-version: ["3.4"]
+        include:
+          - ruby-version: "3.4"
+            allow-failure: false
+          - ruby-version: "4.0"
+            allow-failure: false
+          - ruby-version: "head"
+            allow-failure: true
 
     steps:
     - uses: actions/checkout@v4

data/.github/workflows/cibuildgem.yaml

@@ -9,6 +9,7 @@ on:
         default: false
 env:
   CIBUILDGEM: 1
+  RELEASE: "true"
 jobs:
   compile:
     timeout-minutes: 20
@@ -28,11 +29,32 @@ jobs:
           ruby-version: "3.4"
           bundler-cache: true
       - name: "Build MsQuic"
-        run: bundle exec rake build_msquic
+        run: bundle exec rake build_msquic bundle_msquic
+      - name: "Verify bundled MsQuic"
+        run: |
+          ls -la lib/quicsilver
+          test -f lib/quicsilver/libmsquic.2.dylib || test -f lib/quicsilver/libmsquic.so.2
+      - name: "Verify package file list"
+        run: |
+          ruby -e 'puts "RELEASE=#{ENV["RELEASE"].inspect}"; spec = Gem::Specification.load("quicsilver.gemspec"); puts spec.files.grep(/libmsquic/)'
       - name: "Run cibuildgem"
         uses: "shopify/cibuildgem/.github/actions/cibuildgem@main"
         with:
           step: "compile"
+      - name: "Upload staged artifacts with MsQuic"
+        uses: "actions/upload-artifact@v4"
+        with:
+          name: "stage-${{ runner.os }}-${{ runner.arch }}"
+          path: |
+            ./tmp/**/*.so
+            ./tmp/**/*.so.*
+            ./tmp/**/*.bundle
+            ./tmp/**/*.dylib
+            ./tmp/**/*.dylib.*
+            ./pkg/*.gem
+          if-no-files-found: error
+          retention-days: 1
+          overwrite: true
   test:
     timeout-minutes: 20
     name: "Run the test suite"
@@ -41,7 +63,7 @@ jobs:
       matrix:
         os: ["macos-latest", "ubuntu-22.04"]
         rubies: ["3.4", "4.0"]
-        type: ["cross", "native"]
+        type: ["cross"]
     runs-on: "${{ matrix.os }}"
     steps:
       - name: "Checkout code"
@@ -68,10 +90,12 @@ jobs:
         uses: "ruby/setup-ruby@v1"
         with:
           ruby-version: "4.0.0"
-      - name: "Run cibuildgem"
-        uses: "shopify/cibuildgem/.github/actions/cibuildgem@main"
+      - name: "Download platform gems"
+        uses: "actions/download-artifact@v5"
         with:
-          step: "install"
+          name: "stage-${{ runner.os }}-${{ runner.arch }}"
+      - name: "Install platform gem"
+        run: ruby -e 'puts Dir["pkg/*-#{Gem::Platform.local}.gem"].fetch(0)' | xargs gem install
   release:
     environment: release
     permissions:

data/.gitignore

@@ -10,6 +10,11 @@
 /certs/*
 /certificates/*
 *.bundle
+*.bundle.*
+*.so
+*.so.*
+*.dylib
+*.dylib.*
 lib/quicsilver/quicsilver.bundle
 *.gem
 autoresearch.*

data/CHANGELOG.md

@@ -5,6 +5,56 @@ 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).
 
+## [Unreleased]
+
+## [0.5.0] - 2026-11-02
+
+### Added
+
+- WebTransport session flow control (draft-ietf-webtrans-http3-16 §5): the `WT_MAX_DATA`, `WT_MAX_STREAMS`, `WT_DATA_BLOCKED` and `WT_STREAMS_BLOCKED` capsules, negotiation via `SETTINGS_WT_INITIAL_MAX_*`, enforcement of limits we advertise, spending of limits a peer grants, and proactive grants as the application consumes. `WebTransportStream#writable?` and `WebTransportSession#on_writable` report send credit. Prohibited per-stream capsules fail the session. §5.1 requires both endpoints to advertise a non-zero initial limit; browsers tested do not, so sessions with them run without it and remain limited to one per connection.
+
+- `Transport::StreamEvent#final_size` reports how many bytes the peer sent on a stream the peer reset, from the RESET_STREAM frame (RFC 9000 §4.5); `nil` when the final size is not settled. WebTransport session flow control needs it to charge the bytes a reset discarded (draft-ietf-webtrans-http3-16 §5.4). MsQuic keeps the value but does not expose it, so it is read through a new vendored patch, `ext/quicsilver/patches/stream-final-size.patch`.
+- Shared connection multiplexing — single QUIC connection serves all threads concurrently (5x faster: 16,000 req/s vs 3,175 req/s exclusive). Default pool mode.
+- `TransportError` base class with MsQuic status code parsing — typed errors instead of string-matching RuntimeError from C extension
+- `StreamFailedToOpenError` wraps `StreamOpen`/`StreamStart` failures with parsed hex status
+- Stream flow control visibility — `QUIC_STREAM_START_FLAG_INDICATE_PEER_ACCEPT` dispatches `STREAM_START_COMPLETE` and `STREAM_PEER_ACCEPTED` events to Ruby
+- H3 Datagram support (RFC 9221/9297) — `client.datagram_send`, `server.datagram_send`, `on_datagram` callbacks, `SETTINGS_H3_DATAGRAM` advertised
+- Client priority support — send `priority` header with extensible priorities (RFC 9218)
+- Client request body streaming — `build_request('POST', path, body: :stream)` with `Request#stream_body`
+- Client response body streaming — `request.streaming_response` returns headers immediately, body arrives incrementally
+- Per-request timeout support
+- Connection pool blocks with timeout (ConditionVariable) instead of raising immediately when full
+- Response unification — single response representation across buffered and streaming paths
+- Multi-threaded benchmarks
+
+### Fixed
+
+- Repeated response headers are sent as separate fields. They were flattened into a Hash keyed by name, which kept only the last value; a Rails response setting a session cookie alongside any other lost the session, so sign-in succeeded and the next request arrived unauthenticated. `set-cookie` MUST NOT be combined (RFC 9110 §5.3).
+- WebTransport rejects the `WT_MAX_STREAM_DATA` and `WT_STREAM_DATA_BLOCKED` capsules. Per-stream data limits belong to the HTTP/2 binding; over HTTP/3 each WebTransport stream is a QUIC stream with its own limits, so receipt is a session error carrying `WT_FLOW_CONTROL_ERROR` (draft-ietf-webtrans-http3-16 §5.4). They were previously ignored as unknown capsule types. Unknown types are still ignored.
+- WebTransport CLOSE and DRAIN capsules use HTTP/3 DATA frames. Session close sends FIN, validates peer close payloads, and terminates both directions on protocol errors.
+- WT_STREAM (`0x41`) is rejected with the connection error `H3_FRAME_ERROR` when it appears anywhere other than the first bytes of a request stream, including on the control stream (draft-ietf-webtrans-http3-16 §4.3). It is only a signal value at the front of a WebTransport stream, never a frame elsewhere.
+- WebTransport capsules sent optimistically on the CONNECT stream are no longer processed before the server responds. They are held unparsed, then processed once `accept!` sends the 2xx or discarded if the session is rejected (§3.2). The hold is bounded at 64 KiB; exceeding it fails the session with `H3_MESSAGE_ERROR`. Previously a CLOSE capsule arriving before the application responded would terminate the session and make it unacceptable.
+- Release GVL during `wait_for_connection` — no longer blocks all Ruby threads during handshake
+- Stream cleanup after response sent — `Connection#@streams` entries removed on completion, not just on connection close
+- Error hierarchy — `FrameError`, `MessageError`, `StreamFailedToOpenError` all inherit from `Quicsilver::Error`
+- Large response crash and concurrent connection race condition
+- Rack adapter owns early hints and trailer wiring (removed from server)
+
+### Changed
+
+- MsQuic callbacks no longer call into Ruby. The poll thread runs the whole MsQuic iteration with the GVL released and queues events; a dispatcher thread delivers them to `Server.handle_stream` in order. `Quicsilver.defer_stream_receive` and `Transport::Stream#defer_receive` are removed: delivery is asynchronous, so a receive cannot be handed back to MsQuic, and a method that always declined would be indistinguishable from one that declined this time. With `receive_backpressure: true`, the one WebTransport receive that can arrive before the first credit grant is delivered whole and may exceed `receive_buffer_bytes`; it is bounded by the initial QUIC stream window instead (RFC 9000 §4.1), and no credit is granted until the reader drains below the limit. Previously the excess was deferred. Credit bounds every receive after that as before. Each connection may have at most 128 datagrams queued ahead of the dispatcher (quic-go's figure); past that the oldest is dropped, as RFC 9221 §5.3 permits and as quiche and neqo do. `Server#stats["datagrams"]["dropped"]` counts drops across connections. `receive_buffer_bytes` was never a bound on what a single `read` returns.
+- `Quicsilver.send_stream` no longer copies the body. The Ruby String is frozen and MsQuic sends from its bytes directly, with the String retained until the send completes. Callers that went on mutating a buffer after sending it must `dup` first; nothing in the library did. Large responses gain about 4% on server-side time; small ones are unchanged. The poll thread's idle spin before sleeping is now configurable via `QUICSILVER_POLL_IDLE_US` (default 0, the previous behaviour); it measured as having no effect under load and is exposed for low-concurrency latency-sensitive deployments to evaluate.
+- WebTransport child streams have bounded receive queues, and a child that fills its buffer now pauses instead of losing its stream. `accept!` takes `receive_buffer_bytes` (default 1 MiB), `receive_buffer_chunks` (default 1024), `receive_overflow_code` and `receive_backpressure` (default `true`); delivery stops until the application reads. A reader that never drains leaves its stream paused indefinitely, and a paused stream holds connection credit, so it can stall its siblings. `receive_backpressure: false` restores the previous policy: an overflowing child is sent `STOP_SENDING` with `receive_overflow_code`, its queued input is discarded and its pending reads fail, while its write side stays open. Limits apply to each child's queued Ruby input, not to native buffers or the whole connection. `WebTransportStream#initialize` now requires these four options rather than defaulting them, so the defaults have a single home in `WebTransportSession::DEFAULT_RECEIVE_OPTIONS`.
+- WebTransport stream resets are directional. `RESET_STREAM` closes only the read side and invokes the new `on_peer_reset`; `STOP_SENDING` closes only the write side and invokes the new `on_peer_stop_sending`. `on_close` fires once both directions are closed. Previously either signal tore down the whole stream and both reported through `on_reset`, which is removed — the `peer_` prefix distinguishes these inbound events from the outbound `reset` and `abort` methods.
+- WebTransport CONNECT waits for peer SETTINGS before reaching Rack, including when headers arrive with FIN. The `webtransport-h3` token requires `WT_ENABLED=1` and `H3_DATAGRAM=1`; the legacy `webtransport` token requires `H3_DATAGRAM=1`. Waiting is limited to one CONNECT and 64 KiB of body data per connection, with cleanup on cancellation or connection closure.
+- WebTransport permits one active session per QUIC connection until session flow control is implemented. Additional CONNECT requests are rejected with `H3_REQUEST_REJECTED`; closing a session allows another. SETTINGS no longer advertise session flow-control credit, and the legacy session limit is one.
+- WebTransport `close(code:, reason:)` rejects invalid UTF-8 and codes outside the unsigned 32-bit range before changing session state. Valid UTF-8 binary strings remain supported; long valid reasons are truncated at a UTF-8 character boundary.
+- Connection pool default mode is `:shared` (multiplexed) — `:exclusive` available as opt-in
+- `open_stream` wraps C extension errors into typed `StreamFailedToOpenError` / `TransportError`
+- MsQuic submodule updated from v2.5.0 to v2.5.7
+- Uni stream default documented: 10 (3 required by HTTP/3, headroom for GREASE and extensions)
+- Scheduler base class extracted for extensibility
+
 ## [0.4.0] - 2026-04-25
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    quicsilver (0.4.0)
+    quicsilver (0.5.0)
       console
       localhost (~> 1.6)
       logger
@@ -14,6 +14,10 @@ GEM
   remote: https://rubygems.org/
   specs:
     benchmark-ips (2.14.0)
+    cibuildgem (0.3.0)
+      prism
+      rake-compiler
+      thor
     console (1.34.3)
       fiber-annotation
       fiber-local (~> 1.1)
@@ -29,6 +33,7 @@ GEM
     minitest (5.27.0)
     minitest-focus (1.4.0)
       minitest (>= 4, < 6)
+    prism (1.9.0)
     protocol-http (0.60.0)
     protocol-rack (0.22.1)
       io-stream (>= 0.10)
@@ -41,6 +46,7 @@ GEM
     rake-compiler (1.3.0)
       rake
     rake-compiler-dock (1.9.1)
+    thor (1.5.0)
 
 PLATFORMS
   arm64-darwin-23
@@ -49,6 +55,7 @@ PLATFORMS
 DEPENDENCIES
   benchmark-ips (~> 2.12)
   bundler (~> 2.0)
+  cibuildgem
   minitest (~> 5.0)
   minitest-focus (~> 1.3)
   quicsilver!

data/README.md

@@ -2,6 +2,13 @@
 
 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
@@ -14,7 +21,7 @@ HTTP/3 server and client for Ruby with Rack support.
 - **GOAWAY** (RFC 9114 §7.2.6) — graceful connection draining with validation
 - **0-RTT** — fast reconnection with replay protection
 - **Connection pooling** — client reuses connections automatically
-- **protocol-http integration** — works with Falcon and protocol-http ecosystem
+- **Falcon middleware compatible** — use Falcon's caching and content encoding over HTTP/3
 
 ## Installation
 
@@ -31,12 +38,19 @@ rake compile
 
 ```ruby
 require "quicsilver"
+require "localhost/authority"
 
 app = ->(env) {
   [200, {"content-type" => "text/plain"}, ["Hello HTTP/3!"]]
 }
 
-server = Quicsilver::Server.new(4433, app: app)
+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
 ```
 
@@ -45,18 +59,20 @@ server.start
 ```ruby
 require "quicsilver"
 
-# Class-level API with automatic connection pooling
-response = Quicsilver::Client.get("127.0.0.1", 4433, "/")
+# 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("127.0.0.1", 4433, "/api/users",
+response = Quicsilver::Client.post("localhost", 4433, "/api/users",
   body: '{"name": "alice"}',
   headers: { "content-type" => "application/json" })
 
-# Instance-level for more control
-client = Quicsilver::Client.new("127.0.0.1", 4433, unsecure: true)
+# 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
 ```
@@ -67,14 +83,111 @@ client.disconnect
 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 https://localhost:4433/
+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",
@@ -94,7 +207,7 @@ server.start
 
 ## Priorities
 
-Browsers send priority hints on requests. Quicsilver parses them and tells MsQuic to schedule high-priority streams first.
+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)
@@ -116,25 +229,25 @@ headers.trailer!
 headers.add("x-checksum", "abc123")
 ```
 
-## Protocol-HTTP Mode
+## Falcon Middleware Mode
 
-For integration with [Falcon](https://github.com/socketry/falcon) and the protocol-http ecosystem:
+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: :protocol_http
+  mode: :falcon
 )
 
 server = Quicsilver::Server.new(4433, app: app, server_configuration: config)
 server.start
 ```
 
-| Mode | Body Handling | Use Case |
+| Mode | App Interface | Use Case |
 |------|---------------|----------|
-| `:rack` (default) | Buffered | Standard Rack apps |
-| `:protocol_http` | Streaming | Falcon, protocol-http apps |
+| `:rack` (default) | Rack env hash | Rails, Sinatra, any Rack app |
+| `:falcon` | Protocol::HTTP::Request | Falcon middleware stack |
 
 ## Development
 

data/Rakefile

@@ -2,13 +2,15 @@ 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
 
-# Ensure MsQuic is built before compiling the C extension
-task :compile => :build_msquic
+# 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
@@ -37,7 +39,8 @@ task :setup do
 end
 
 task :build_msquic => :setup do
-  cmake_args = ['-B build', '-DCMAKE_BUILD_TYPE=Release']
+  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"'
@@ -49,6 +52,7 @@ task :build_msquic => :setup do
   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]
@@ -56,12 +60,14 @@ 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/
@@ -71,6 +77,7 @@ 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",

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