quicsilver 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36065332b2efe43090097b945882282ba770a6b6b5a54d16d7229bf8977dfb6e
-  data.tar.gz: 22f94375fdaa43b465b6ff9b866985ca7dd06732ea5e0cbf98a94c7c92eb97df
+  metadata.gz: 9f3ec155af92a08642dd37953aa75728a021f9868c964c0240a61b98399f72be
+  data.tar.gz: 6c5effb85af855cfd60761fc7aef9bdf0cc6901df1c56b478d22557705c55925
 SHA512:
-  metadata.gz: edcac1b797654202cf22ef471e3de5cd23a8409f0ded8d940652cb6194d14974f0c08f7118af1f76e1895dca0598ae646764687d0fabb0555317e67a3587f690
-  data.tar.gz: a1521e2a828ba6bd394939a5c7b1034d1951f92329444f1adee5135db96df9703128b731c673c10c6309d104f238aa95589a9c9cfb581c6e050bc5ef6a261c8f
+  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.2"]
+        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

@@ -0,0 +1,117 @@
+name: "Package and release gems with precompiled binaries"
+on:
+  workflow_dispatch:
+    inputs:
+      release:
+        description: "If the whole build passes on all platforms, release the gems on RubyGems.org"
+        required: false
+        type: boolean
+        default: false
+env:
+  CIBUILDGEM: 1
+  RELEASE: "true"
+jobs:
+  compile:
+    timeout-minutes: 20
+    name: "Cross compile the gem on different ruby versions"
+    strategy:
+      matrix:
+        os: ["macos-latest", "ubuntu-22.04"]
+    runs-on: "${{ matrix.os }}"
+    steps:
+      - name: "Checkout code"
+        uses: "actions/checkout@v5"
+        with:
+          submodules: recursive
+      - name: "Setup Ruby"
+        uses: "ruby/setup-ruby@v1"
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+      - name: "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"
+    needs: compile
+    strategy:
+      matrix:
+        os: ["macos-latest", "ubuntu-22.04"]
+        rubies: ["3.4", "4.0"]
+        type: ["cross"]
+    runs-on: "${{ matrix.os }}"
+    steps:
+      - name: "Checkout code"
+        uses: "actions/checkout@v5"
+      - name: "Setup Ruby"
+        uses: "ruby/setup-ruby@v1"
+        with:
+          ruby-version: "${{ matrix.rubies }}"
+          bundler-cache: true
+      - name: "Run cibuildgem"
+        uses: "shopify/cibuildgem/.github/actions/cibuildgem@main"
+        with:
+          step: "test_${{ matrix.type }}"
+  install:
+    timeout-minutes: 5
+    name: "Verify the gem can be installed"
+    needs: test
+    strategy:
+      matrix:
+        os: ["macos-latest", "ubuntu-22.04"]
+    runs-on: "${{ matrix.os }}"
+    steps:
+      - name: "Setup Ruby"
+        uses: "ruby/setup-ruby@v1"
+        with:
+          ruby-version: "4.0.0"
+      - name: "Download platform gems"
+        uses: "actions/download-artifact@v5"
+        with:
+          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:
+      id-token: write
+      contents: read
+    timeout-minutes: 5
+    if: ${{ inputs.release }}
+    name: "Release all gems with RubyGems"
+    needs: install
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: "Setup Ruby"
+        uses: "ruby/setup-ruby@v1"
+        with:
+          ruby-version: "4.0.0"
+      - name: "Run cibuildgem"
+        uses: "shopify/cibuildgem/.github/actions/cibuildgem@main"
+        with:
+          step: "release"

data/.gitignore

@@ -10,5 +10,12 @@
 /certs/*
 /certificates/*
 *.bundle
+*.bundle.*
+*.so
+*.so.*
+*.dylib
+*.dylib.*
 lib/quicsilver/quicsilver.bundle
-*.gem
+*.gem
+autoresearch.*
+ext/quicsilver/Makefile

data/CHANGELOG.md

@@ -5,6 +5,88 @@ 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
+- Client connection pool with automatic reuse (`Quicsilver::Client.get/post` class-level API)
+- GREASE support (RFC 9297) — settings, frames, and unidirectional streams
+- GOAWAY validation (RFC 9114 §7.2.6) — monotonically decreasing IDs, stream ID validation
+- Trailer support (RFC 9114 §4.1) — parse and send trailing HEADERS frames
+- Extensible Priorities (RFC 9218) — parse `priority` header, PRIORITY_UPDATE frames on control stream, MsQuic stream priority mapping
+- FrameParser base class — unified frame walking, ordering, body accumulation, size limits
+- FrameReader module — shared byte-level frame extraction for request/response/control streams
+- Trailer wiring in Adapter and StreamOutput for protocol-http integration
+- Informational 1xx responses (§4.1) — 103 Early Hints with `rack.early_hints` support for Rails
+- Two-phase GOAWAY shutdown (§5.2) — server sends decreasing GOAWAY IDs during graceful shutdown
+- Client processes server SETTINGS (§7.2.4) — parses peer's SETTINGS including MAX_FIELD_SECTION_SIZE
+- Client processes server GOAWAY (§5.2) — tracks peer_goaway_id, blocks new requests, connection pool evicts draining connections
+- MIT license in gemspec
+
+### Fixed
+- QPACK prefix decoding — decode Required Insert Count and Delta Base as varints instead of hardcoded `offset = 2`
+- Default decoder rejects payloads referencing the dynamic table
+- Response parser now enforces `max_frame_payload_size` (was missing)
+- Duplicate `frames` method in FrameParser
+- Consistent `@headers` and `@trailers` initialization (`{}` not `nil`)
+- extconf.rb — force Apple clang on macOS (Homebrew clang produces broken MsQuic binaries)
+
+### Changed
+- RequestParser and ResponseParser inherit from FrameParser (reduced ~230 lines of duplication)
+- `store_header`, `body`, `DEFAULT_DECODER`, `EMPTY_BODY`, `parse!` moved to FrameParser base class
+- `@body_io` renamed to `@body` in ResponseParser for consistency
+- ResponseEncoder accepts optional `trailers:` hash
+- StreamOutput accepts `send_fin:` parameter for trailer support
+
 ## [0.3.0] - 2026-03-23
 
 ### Added

data/Gemfile.lock

@@ -1,9 +1,12 @@
 PATH
   remote: .
   specs:
-    quicsilver (0.2.0)
+    quicsilver (0.5.0)
+      console
       localhost (~> 1.6)
       logger
+      protocol-http (~> 0.49)
+      protocol-rack (~> 0.22)
       rack (~> 3.0)
       rackup (~> 2.0)
 
@@ -11,18 +14,39 @@ 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)
+      json
+    fiber-annotation (0.2.0)
+    fiber-local (1.1.0)
+      fiber-storage
+    fiber-storage (1.0.1)
+    io-stream (0.11.1)
+    json (2.15.2)
     localhost (1.6.0)
     logger (1.7.0)
     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)
+      protocol-http (~> 0.58)
+      rack (>= 1.0)
     rack (3.2.4)
     rackup (2.2.1)
       rack (>= 3)
-    rake (13.3.1)
+    rake (13.4.2)
     rake-compiler (1.3.0)
       rake
     rake-compiler-dock (1.9.1)
+    thor (1.5.0)
 
 PLATFORMS
   arm64-darwin-23
@@ -31,6 +55,7 @@ PLATFORMS
 DEPENDENCIES
   benchmark-ips (~> 2.12)
   bundler (~> 2.0)
+  cibuildgem
   minitest (~> 5.0)
   minitest-focus (~> 1.3)
   quicsilver!

data/README.md

@@ -1,13 +1,32 @@
 # Quicsilver
 
-HTTP/3 server for Ruby with Rack support.
+HTTP/3 server and client for Ruby with Rack support.
 
-**Status:** Experimental (v0.2.0)
+## 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 <repository>
+git clone https://github.com/hahmed/quicsilver
 cd quicsilver
 bundle install
 rake compile
@@ -19,20 +38,20 @@ rake compile
 
 ```ruby
 require "quicsilver"
+require "localhost/authority"
 
 app = ->(env) {
-  case env['PATH_INFO']
-  when '/'
-    [200, {'content-type' => 'text/plain'}, ["Hello HTTP/3!"]]
-  when '/api/users'
-    [200, {'content-type' => 'application/json'}, ['{"users": ["alice", "bob"]}']]
-  else
-    [404, {'content-type' => 'text/plain'}, ["Not Found"]]
-  end
+  [200, {"content-type" => "text/plain"}, ["Hello HTTP/3!"]]
 }
 
-server = Quicsilver::Server.new(4433, app: app)
-server.start  # Blocks until shutdown
+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
@@ -40,44 +59,201 @@ server.start  # Blocks until shutdown
 ```ruby
 require "quicsilver"
 
-client = Quicsilver::Client.new("127.0.0.1", 4433, unsecure: true)
-client.connect
+# 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!"
 
-response = client.get("/api/users")
-puts response[:body]
-
-response = client.post("/api/users", body: '{"name": "charlie"}')
+# 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
 ```
 
-## Usage with Rails
+### 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::ServerConfiguration.new("/path/to/cert.pem", "/path/to/key.pem",
-  idle_timeout_ms: 10_000,        # Connection idle timeout (ms)
-  max_concurrent_requests: 100    # Max concurrent requests per connection
+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,
-  address: "0.0.0.0",
-  server_configuration: config
+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
+rake compile  # Build C extension (macOS: uses Apple clang automatically)
 rake test     # Run tests
-rake clean    # Clean build artifacts
 ```
 
 ## License