Frank Spitulski
7c04a155c8
squashed messages: fixup for docs and removing extra braces add downcasting hatch pretty print should be Display, not Debug un-needed export fmt and clippy re-expose CCAs to public API reorder constants inline bbr_state remove extra param refactor bbr into its own module refactor bbr into its own module no threadlocal rng, use genrange rename fields for review Update quinn/src/connection.rs Co-authored-by: Benjamin Saunders <ben.e.saunders@gmail.com> Update quinn-proto/src/connection/mod.rs Co-authored-by: Benjamin Saunders <ben.e.saunders@gmail.com> Update quinn-proto/src/connection/mod.rs Co-authored-by: Benjamin Saunders <ben.e.saunders@gmail.com> fill() now supported clippy in cubic was covered by the rebase add links to BBR info refactor to hide internal PathData clarify BBR usage reduce struct scope collapse update_last_sent into on_sent collapse on_loss into on_congestion_event remove dead code Update quinn/src/connection.rs Co-authored-by: Benjamin Saunders <ben.e.saunders@gmail.com> Update quinn-proto/src/congestion/bbr.rs Co-authored-by: Benjamin Saunders <ben.e.saunders@gmail.com> Update quinn-proto/src/congestion.rs Co-authored-by: Benjamin Saunders <ben.e.saunders@gmail.com> Update quinn-proto/src/congestion/cubic.rs Co-authored-by: Benjamin Saunders <ben.e.saunders@gmail.com> clippy safer duration comparison backwards compatibility fill add docs, rename stats cca to congestion remove PacketNumber and bbr_ prefixes rename constants to rust style fix packet number typing enable drain to target bdp mode during probe bw add ack aggregation for better target growth fix not entering growth mode remove extra debug printing enable rtt probe and track min rtt track max bandwidth with minmax filter use minmax filter for max bandwidth estimation switch minmax filter to use round counts instead of times port minmax filter to rust fix: count lost packet size instead of their id fix bw estimation not updating current bw expose congestion configs split bytes acked from end ack method simplify full bandwidth check remove some unused variables add 125% of target full bandwidth condition as per docs fix loss resetting too early, fix bandwidth target units of measurement check if full bw reached calculate recovery window calculate cwnd calculate pacing rate maybe_enter_or_exit_probe_rtt update gain cycle phase refactor bandwidth estimation add cca into stats for debugging add target window add recovery state transitions loss recording bandwidth estimation
Pure-rust QUIC protocol implementation
Quinn is a pure-rust, future-based implementation of the QUIC transport protocol undergoing standardization by the IETF. This library is at draft 32.
Features
- Simultaneous client/server operation
- Ordered and unordered stream reads for improved performance
- Works on stable Rust, tested on Linux, macOS and Windows
- Pluggable cryptography, with a standard implementation backed by rustls and ring
- Application-layer datagrams for small, unreliable messages
- Future-based async API
- Experimental HTTP over QUIC
- The minimum supported Rust version is 1.47.0
Overview
- quinn: High-level async API based on tokio, see for usage. This will be used by most developers. (Basic benchmarks are included.)
- quinn-proto: Deterministic state machine of the protocol which performs no I/O internally and is suitable for use with custom event loops (and potentially a C or C++ API).
- quinn-udp: UDP sockets with ECN information tuned for the protocol.
- quinn-h3: Contains an implementation of HTTP-3 and QPACK. It is split internally in a deterministic state machine and a tokio-based high-level async API.
- bench: Benchmarks without any framework.
- fuzz: Fuzz tests.
Getting Started
Examples
$ cargo run --example server ./
$ cargo run --example client https://localhost:4433/Cargo.toml
This launches an HTTP 0.9 server on the loopback address serving the current
working directory, with the client fetching ./Cargo.toml. By default, the
server generates a self-signed certificate and stores it to disk, where the
client will automatically find and trust it.
Links
- Talk at RustFest Paris (May 2018) presentation; slides; YouTube
- Usage examples
- Guide book
Usage Notes
Click to show the notes
Buffers
A Quinn endpoint corresponds to a single UDP socket, no matter how many
connections are in use. Handling high aggregate data rates on a single endpoint
can require a larger UDP buffer than is configured by default in most
environments. If you observe erratic latency and/or throughput over a stable
network link, consider increasing the buffer sizes used. For example, you could
adjust the SO_SNDBUF and SO_RCVBUF options of the UDP socket to be used
before passing it in to Quinn. Note that some platforms (e.g. Linux) require
elevated privileges or modified system configuration for a process to increase
its UDP buffer sizes.
Certificates
By default, Quinn clients validate the cryptographic identity of servers they connect to. This prevents an active, on-path attacker from intercepting messages, but requires trusting some certificate authority. For many purposes, this can be accomplished by using certificates from Let's Encrypt for servers, and relying on the default configuration for clients.
For some cases, including peer-to-peer, trust-on-first-use, deliberately
insecure applications, or any case where servers are not identified by domain
name, this isn't practical. Arbitrary certificate validation logic can be
implemented by enabling the dangerous_configuration feature of rustls and
constructing a Quinn ClientConfig with an overridden certificate verifier by
hand.
When operating your own certificate authority doesn't make sense, rcgen can be used to generate self-signed certificates on demand. To support trust-on-first-use, servers that automatically generate self-signed certificates should write their generated certificate to persistent storage and reuse it on future runs.
Contribution
All feedback welcome. Feel free to file bugs, requests for documentation and any other feedback to the issue tracker.
The quinn-proto test suite uses simulated IO for reproducibility and to avoid
long sleeps in certain timing-sensitive tests. If the SSLKEYLOGFILE
environment variable is set, the tests will emit UDP packets for inspection
using external protocol analyzers like Wireshark, and NSS-compatible key logs
for the client side of each connection will be written to the path specified in
the variable.
The minimum supported Rust version for published releases of our crates will always be at least 6 months old at the time of release.
Authors
- Dirkjan Ochtman - Project owner & founder
- Benjamin Saunders - Project owner & founder
- Jean-Christophe Begue - Project collaborator, author of the HTTP/3 Implementation