If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/cloudflare/quiche shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 22+ active contributors
• Distributed ownership (top contributor 29% of recent commits)
• BSD-2-Clause licensed
• CI configured
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live cloudflare/quiche repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/cloudflare/quiche.

What it runs against: a local clone of cloudflare/quiche — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in cloudflare/quiche | Confirms the artifact applies here, not a fork | | 2 | License is still BSD-2-Clause | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of cloudflare/quiche. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/cloudflare/quiche.git
#   cd quiche
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of cloudflare/quiche and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "cloudflare/quiche(\\.git)?\\b" \\
  && ok "origin remote is cloudflare/quiche" \\
  || miss "origin remote is not cloudflare/quiche (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(BSD-2-Clause)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"BSD-2-Clause\"" package.json 2>/dev/null) \\
  && ok "license is BSD-2-Clause" \\
  || miss "license drift — was BSD-2-Clause at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "quiche/src/lib.rs" \\
  && ok "quiche/src/lib.rs" \\
  || miss "missing critical file: quiche/src/lib.rs"
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "apps/src/bin/quiche-client.rs" \\
  && ok "apps/src/bin/quiche-client.rs" \\
  || miss "missing critical file: apps/src/bin/quiche-client.rs"
test -f "apps/src/bin/quiche-server.rs" \\
  && ok "apps/src/bin/quiche-server.rs" \\
  || miss "missing critical file: apps/src/bin/quiche-server.rs"
test -f "datagram-socket/src/lib.rs" \\
  && ok "datagram-socket/src/lib.rs" \\
  || miss "missing critical file: datagram-socket/src/lib.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/cloudflare/quiche"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

quiche is Cloudflare's production-grade QUIC transport protocol and HTTP/3 implementation written in Rust, providing a low-level API for processing QUIC packets and managing connection state. It powers HTTP/3 across Cloudflare's edge network, Android's DNS-over-HTTP/3 resolver, and integrates with curl; the library handles protocol mechanics while applications provide I/O and event loop logic. Monorepo with 10 workspace members: quiche/ contains core QUIC/HTTP3 protocol logic, apps/ provides quiche-client and quiche-server reference implementations, datagram-socket/ handles UDP I/O abstraction with mmsg support, buffer-pool/ manages packet memory efficiently, qlog/ implements QUIC event logging, and h3i/ provides HTTP/3-specific utilities. Each crate has independent Cargo.toml but shares workspace dependencies in root Cargo.toml.

Network engineers and systems programmers building HTTP/3 clients/servers or integrating QUIC into existing applications (e.g., curl maintainers, Cloudflare infrastructure teams, Android security engineers). Also relevant for anyone implementing DNS-over-HTTP/3 or experimenting with QUIC at scale.

Production-ready and actively maintained. The codebase shows strong maturity: used by Cloudflare in production, integrated into Android and curl, comprehensive CI via GitHub Actions (stable.yml, nightly.yml, semgrep.yml), and organized as a workspace with multiple specialized sub-crates (quiche, buffer-pool, datagram-socket, qlog, h3i). Last activity and structure indicate active development.

Low risk for stable use; moderate risk if cutting-edge QUIC features needed. Dependencies include established crates (boring for TLS, ring for crypto, mio for I/O) and internal Cloudflare libraries (foundations, netlog). The monorepo structure with 10 workspace members increases local complexity but improves cohesion. QUIC spec evolution (RFC 9000 is recent) means occasional protocol-level updates; check RELEASING.md before upgrading major versions.

Active maintenance visible: CI workflows for stable/nightly testing, dependabot.yml indicating automated dependency updates, semgrep security scanning enabled, and specialized sub-crates suggest ongoing feature expansion (e.g., qlog-dancer for visualization, task-killswitch for resource management). RELEASING.md exists, suggesting versioned releases are regular.

Clone and build: git clone https://github.com/cloudflare/quiche && cd quiche && cargo build. Run the server: cargo run --bin quiche-server -- --cert apps/src/bin/cert.crt --key apps/src/bin/cert.key. Run the client: cargo run --bin quiche-client -- https://cloudflare-quic.com/. Test suite: cargo test.

Daily commands: Dev: cargo build && cargo test for full test suite. Apps: cargo run --bin quiche-server -- [options] and cargo run --bin quiche-client -- [URL]. Fuzzing: cd fuzz && cargo fuzz run quiche (requires cargo-fuzz). Linting: clippy config at clippy.toml, semgrep in CI.

• quiche/src/lib.rs — Core QUIC protocol implementation and connection state machine—entry point for all packet processing and stream handling logic
• Cargo.toml — Workspace manifest defining all crates (quiche, h3i, qlog, tokio-quiche, etc.) and their dependencies—essential for understanding project structure
• apps/src/bin/quiche-client.rs — Reference QUIC client implementation demonstrating the public API surface and practical usage patterns
• apps/src/bin/quiche-server.rs — Reference QUIC server implementation showing connection handling, I/O loops, and event-driven architecture patterns
• datagram-socket/src/lib.rs — Platform-abstraction layer for UDP sockets and multi-message I/O (mmsg)—critical for understanding I/O integration points
• qlog/src/lib.rs — Diagnostic logging and event tracing framework used throughout the codebase for debugging QUIC protocol state

Add a New QUIC Frame Type

1. Define the frame type enum variant in the Frame enum (quiche/src/frame.rs)
2. Implement parsing logic in the frame's parse() function (quiche/src/frame.rs)
3. Add handling in Connection::recv_pkt() to process the new frame type (quiche/src/lib.rs)
4. Add corresponding qlog event emission for tracing (qlog/src/lib.rs)
5. Add test cases in the frame module's tests and fuzzing corpus (fuzz/corpus/packet_recv_client/)

Implement a New Stream Feature

1. Add state field or flag to the Stream struct (quiche/src/stream.rs)
2. Implement state transition logic in Stream methods (quiche/src/stream.rs)
3. Expose new stream methods or callbacks in the Connection API (quiche/src/lib.rs)
4. Update example apps to demonstrate new functionality (apps/src/bin/quiche-server.rs)

Add HTTP/3 Header Compression Logic

1. Add QPACK encoder/decoder state to the HTTP/3 connection (h3i/src/lib.rs)
2. Implement or extend QPACK frame parsing and generation (h3i/src/frame.rs)
3. Integrate with stream data writing in HTTP/3 connection handler (h3i/src/lib.rs)
4. Add test vectors and verify against HTTP/3 spec examples (h3i/src/lib.rs)

Optimize Packet I/O Path

1. Profile current batch send/recv in datagram-socket mmsg implementation (datagram-socket/src/mmsg.rs)
2. Adjust batch sizes and buffer allocations in buffer-pool (buffer-pool/src/lib.rs)
3. Update example apps to tune socket and buffer configuration (apps/src/bin/quiche-server.rs)
4. Add qlog events to trace I/O latencies and batch efficiency (qlog/src/lib.rs)

• Rust — Memory safety without GC, zero-cost abstractions, and fine-grained control over I/O critical paths required for high-performance QUIC implementation
• TLS 1.3 (via BoringSSL bindings) — QUIC mandates TLS 1.3 for encryption; BoringSSL provides well-tested cryptographic primitives and TLS state machine
• Multi-message I/O (mmsg) — Batch packet send/receive reduces syscall overhead and improves throughput on high-packet-rate connections
• qlog format — Standardized diagnostic event format enables vendor-independent protocol debugging and interoperability validation
• Workspace monorepo (Cargo) — Cleanly separates protocol layers (quiche/h3i/qlog) and optional features (tokio-quiche) without tight coupling

• Application-driven I/O (no internal socket ownership)

  • Why: Enables integration with any event loop (tokio, async-std, custom) without framework lock-in
  • Consequence: Application must handle UDP socket creation, event loop, and timer scheduling—higher initial integration burden but maximum flexibility

• Single-threaded connection API (no Sync on Connection)

  • Why: Avoids locking overhead in the hot path for packet processing and stream data movement
  • Consequence: One connection per thread or async task; multiplexing must happen at the socket/dispatcher level (see quiche-server example)

• Eager packet processing (recv_packet returns immediately)

  • Why: Predictable latency and integration with existing polling I/O models
  • Consequence: No backpressure mechanism within the connection; app must manage its own buffer allocation and flow control

• Configuration at connection creation, not per-packet

  • Why: Reduces per-packet overhead and simplifies state management
  • Consequence: Cannot dynamically change transport parameters mid-connection; requires reconnection for parameter adjustments

• Does not implement complete TLS certificate validation—applications must integrate their own X.509 verification logic
• Not a network driver or kernel module; relies on OS socket APIs
• Does not provide automatic load balancing or connection migration across addresses—migration must be explicitly triggered by the app
• Does not include an HTTP client or server framework—only protocol state machine; applications build on top
• Not intended for real-time media streaming (e.g., WebRTC); QUIC datagram support is minimal

Certificates: The example cert/key in apps/src/bin/ are self-signed and hardcoded; production use requires custom TLS setup via Config methods. Event loop: quiche does NOT provide async/await—applications must implement their own event loop (see apps for mio-based example). Timers: connection.on_timeout() must be called after timer expiration; missing this breaks congestion control. Buffer management: datagram-socket may impose platform limits (Linux UDP_GRO, GSO); check your kernel version and network stack. Dependencies: boring and ring are large; feature flags in Cargo.toml control crypto backends. Fuzzing: fuzz/ is excluded from workspace; build separately. Cross-compilation: Cross.toml present—some features may not work on all platforms.

• QUIC Packet Structure & Frame Types — Understanding QUIC's packet layout (header, payload, frames like STREAM, ACK, CRYPTO) is essential to navigate quiche/src/frame.rs and packet.rs—the core codec.
• Connection State Machine — quiche/src/connection.rs implements a complex state machine (Initial → Handshake → Established → Closed); understanding transitions is key to debugging connection lifecycle issues.
• Flow Control (Window-Based) — QUIC uses per-stream and per-connection flow control windows; quiche enforces these in connection.rs and stream.rs, critical for backpressure and memory safety.
• Congestion Control (CUBIC or similar) — quiche implements QUIC-compatible congestion control; understanding loss detection and cwnd updates in recovery.rs helps optimize performance tuning.
• TLS 1.3 Handshake in QUIC — QUIC embeds TLS 1.3 handshake in Initial/Handshake packets; boring's integration in quiche/src/crypto.rs differs from standalone TLS—understand this for debugging auth failures.
• HTTP/3 Frame Multiplexing — HTTP/3 multiplexes multiple requests over QUIC streams; quiche/src/h3.rs manages stream-to-request mapping and frame sequencing—critical for understanding how data flows.
• Loss Detection & ACK Handling — quiche/src/recovery.rs tracks packet loss via ACKs and timers; incorrect implementation causes stalled connections—understanding rtt sampling and pto is essential for debugging network issues.

• quinn-rs/quinn — Alternative async-first Rust QUIC implementation; compare design (callbacks vs. async/await) and protocol compliance for learning.
• google/gquic — Google's gQUIC (v44) reference implementation; historical context for QUIC protocol evolution before RFC 9000.
• cloudflare/wrangler — Cloudflare's edge compute platform; uses quiche for HTTP/3 support in worker environments.
• curl/curl — quiche is integrated as a TLS backend for HTTP/3 in curl; testing ground for real-world interoperability.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive fuzzing corpus and documentation for datagram-socket edge cases

The fuzz directory contains corpus for packet_recv_client but lacks coverage for datagram-socket module's buffer handling, mmsg operations, and socket_stats tracking. The datagram-socket crate (version 0.8.0) is a critical dependency used across the workspace, but has minimal fuzzing coverage. This would improve reliability of the UDP I/O layer that quiche depends on.

• [ ] Review datagram-socket/src/mmsg.rs for untested edge cases (e.g., sendmmsg with partial failures, recvmmsg with fragmented packets)
• [ ] Review datagram-socket/src/buffer.rs and raw_pool_buf_io.rs for buffer pool exhaustion scenarios
• [ ] Create new fuzzing targets in fuzz/src/lib.rs for datagram operations similar to packet_recv_client
• [ ] Add corpus samples to fuzz/corpus/datagram_send and fuzz/corpus/datagram_recv directories
• [ ] Document fuzzing strategy in fuzz/README.md for datagram-socket

Add integration tests for multi-stream HTTP/3 pipelining in apps/src/bin/quiche-client.rs and quiche-server.rs

The example applications (quiche-client and quiche-server) exist but there are no visible integration tests exercising HTTP/3 pipelining, header compression edge cases, or connection migration scenarios. Given that quiche targets HTTP/3 compliance, these tests would validate real-world usage patterns and prevent regressions.

• [ ] Create tests/integration_http3.rs that spawns quiche-server and quiche-client as subprocesses
• [ ] Add test cases for: multiple concurrent streams, request pipelining, header compression with large headers, settings frame negotiation
• [ ] Reference apps/src/client.rs and apps/src/bin/quiche-client.rs to understand the client API
• [ ] Add CI workflow to .github/workflows/ to run integration tests (or extend existing stable.yml)
• [ ] Document test setup in CONTRIBUTING.md or similar

Refactor and expand qlog module documentation with qlog-dancer integration examples

The workspace includes both qlog (version 0.17.0) and qlog-dancer modules but there's no documented integration showing how to use qlog for QUIC event logging with qlog-dancer for visualization. This is valuable for debugging and performance analysis. The current lack of examples makes this feature undiscoverable.

• [ ] Review qlog/src/ and qlog-dancer/ (referenced in Cargo.toml members) to understand current capabilities
• [ ] Create examples/qlog_logging.rs demonstrating how to enable qlog tracing on a quiche connection
• [ ] Add examples/qlog_dancer_analysis.rs showing how qlog output integrates with qlog-dancer
• [ ] Document the qlog feature flag usage in README.md with a 'Debugging' or 'Analysis' section
• [ ] Add doc comments to key qlog types explaining the event structure and serialization format

• Add comprehensive integration tests for HTTP/3 pipelined requests in quiche/tests/http3.rs—currently minimal coverage for multiplexed streams under high concurrency, would improve confidence in production readiness.
• Document the event-loop pattern expected by applications with a worked example in apps/examples/—quiche's low-level API requires careful timer and I/O coordination that isn't obvious from the reference implementations alone.
• Implement QUIC connection migration tests in quiche/tests/—IPv4/IPv6 address changes are spec-compliant but lack dedicated test coverage, critical for mobile clients.

• High · Hardcoded Test Certificates and Keys — apps/src/bin/cert.key, apps/src/bin/cert.crt, fuzz/cert.key, fuzz/cert.crt. The repository contains hardcoded SSL/TLS certificates and private keys in the source tree (apps/src/bin/cert.crt, apps/src/bin/cert.key, fuzz/cert.crt, fuzz/cert.key). These appear to be test certificates, but storing private keys in version control is a security risk if they were ever used in production or if the repository history is exposed. Fix: Move certificates and keys to environment-specific configuration outside version control. Use certificate generation scripts or management tools for test environments. Ensure production credentials are never committed to repositories.
• High · Incomplete Dependency Specification — Cargo.toml - workspace.dependencies.serde_with. The Cargo.toml workspace dependencies file appears truncated with incomplete dependency specification for 'serde_with' (line ends with 'fal' instead of complete version constraint). This could indicate malformed configuration or incomplete file content, potentially causing build inconsistencies or version resolution issues. Fix: Complete the dependency specification with proper version constraints. Verify all dependencies have complete and valid version specifications. Use 'cargo check' and 'cargo tree' to validate dependency resolution.
• Medium · Dependency on BoringSSL/Boring Crate — Cargo.toml - workspace.dependencies.boring, Dockerfile. The project depends on the 'boring' crate (version 4.3), which is a Rust wrapper around Google's BoringSSL. While BoringSSL is well-maintained, this dependency introduces complexity in the build process (requires clang and cmake) and potential compatibility issues. The Dockerfile explicitly installs build dependencies for BoringSSL. Fix: Keep BoringSSL dependency updated regularly. Monitor security advisories for BoringSSL. Consider using rustls as an alternative if BoringSSL vulnerabilities become problematic. Ensure build dependencies are minimal and properly managed in container images.
• Medium · Docker Base Image Uses 'latest' Tag — Dockerfile - FROM debian:latest AS quiche-base. The Dockerfile uses 'debian:latest' for the runtime image, which can lead to non-deterministic builds and unexpected behavior when Debian releases new versions. This violates container image best practices for reproducibility and security. Fix: Pin the Debian base image to a specific version (e.g., 'debian:bookworm' or 'debian:bookworm-20240101'). Use specific version tags for both the build and runtime base images to ensure reproducibility.
• Medium · Cargo Cache Not Cleared in Docker Build — Dockerfile - build stage. The Dockerfile does not explicitly clear cargo cache or intermediate build artifacts, which could lead to larger image sizes and potential caching issues. The apt-get cache is properly cleaned, but cargo artifacts are not managed. Fix: Use multi-stage builds more aggressively to minimize final image size. Consider adding 'RUN cargo clean' or use cargo-builder patterns to reduce unnecessary artifacts in final images.
• Low · Missing Security Headers in Documentation — README.md, RELEASING.md. The README and repository configuration files do not document security considerations for deployment, such as rate limiting, connection limits, or resource exhaustion protections that are critical for a network protocol implementation. Fix: Add a SECURITY.md file documenting security considerations, known limitations, and best practices for deploying quiche. Include information about DOS protection, resource limits, and security contact procedures.
• Low · Fuzzing Directory Not Excluded from Package — Cargo.toml - exclude field, fuzz/corpus/. The fuzz directory is excluded from workspace members but contains large corpus files that could be accidentally included in distribution packages if not properly configured in Cargo.toml. Fix: Ensure fuzz corpus and test data are properly excluded from crate packaging by using the 'exclude' field in individual crate Cargo.toml files. Verify with 'cargo package --allow-dirty' before publishing.
• Low · Development Dependencies Visibility — undefined. The workspace includes testing and fuzzing crates in the same workspace, which increases the surface area. While appropriately excluded from publication, Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.