Crate quinn

QUIC transport protocol support for Tokio

QUIC is a modern transport protocol addressing shortcomings of TCP, such as head-of-line blocking, poor security, slow handshakes, and inefficient congestion control. This crate provides a portable userspace implementation.

The entry point of this crate is the Endpoint.

The futures and streams defined in this crate are not Send because they necessarily share state with each other. As a result, they must be spawned on a single-threaded tokio runtime.

let mut runtime = tokio::runtime::current_thread::Runtime::new().unwrap();
let mut builder = quinn::Endpoint::builder();
// <configure builder>
let (endpoint_driver, endpoint, _) = builder.bind("[::]:0").unwrap();
runtime.spawn(endpoint_driver.map_err(|e| panic!("IO error: {}", e)));
// ...

About QUIC

A QUIC connection is an association between two endpoints. The endpoint which initiates the connection is termed the client, and the endpoint which accepts it is termed the server. A single endpoint may function as both client and server for different connections, for example in a peer-to-peer application. To communicate application data, each endpoint may open streams up to a limit dictated by its peer. Typically, that limit is increased as old streams are finished.

Streams may be unidirectional or bidirectional, and are cheap to create and disposable. For example, a traditionally datagram-oriented application could use a new stream for every message it wants to send, no longer needing to worry about MTUs. Bidirectional streams behave much like a traditional TCP connection, and are useful for sending messages that have an immediate response, such as an HTTP request. Stream data is delivered reliably, and there is no ordering enforced between data on different streams.

By avoiding head-of-line blocking and providing unified congestion control across all streams of a connection, QUIC is able to provide higher throughput and lower latency than one or multiple TCP connections between the same two hosts, while providing more useful behavior than raw UDP sockets.

QUIC uses encryption and identity verification built directly on TLS 1.3. Just as with a TLS server, it is useful for a QUIC server to be identified by a certificate signed by a trusted authority. If this is infeasible--for example, if servers are short-lived or not associated with a domain name--then as with TLS, self-signed certificates can be used to provide encryption alone.

Re-exports

pub use crate::tls::Certificate;

pub use crate::tls::CertificateChain;

pub use crate::tls::PrivateKey;

Modules

tls	TLS-related helpers

Structs

ClientConfig	Configuration for outgoing connections
ClientConfigBuilder	Helper for creating new outgoing connections.
Connecting	Connecting future
Connection	A QUIC connection.
ConnectionDriver	A future that drives protocol logic for a connection
ConnectionId	Protocol-level identifier for a connection.
Endpoint	A QUIC endpoint.
EndpointBuilder	A helper for constructing an Endpoint.
EndpointDriver	A future that drives IO on an endpoint
Incoming	Stream of incoming connections.
IncomingStreams	A stream of QUIC streams initiated by a remote peer.
ReadToEnd	Future produced by read_to_end
RecvStream	A stream that can only be used to receive data
SendStream	A stream that can only be used to send data
ServerConfig	Parameters governing incoming connections.
ServerConfigBuilder	Helper for constructing a ServerConfig to be passed to EndpointBuilder::listen to enable incoming connections.
Transmit	An outgoing packet
TransportConfig	Parameters governing the core QUIC state machine

Enums

ConnectError	Errors in the parameters being used to create a new connection
ConnectionError	Reasons why a connection might be lost.
DatagramEvent	Event resulting from processing a single datagram
EndpointError	Errors that can occur during the construction of an Endpoint.
NewStream	A stream initiated by a remote peer.
ReadError	Errors that arise from reading from a stream.
WriteError	Errors that arise from writing to a stream

Constants

ALPN_QUIC_H3	TLS ALPN value for H3
ALPN_QUIC_HTTP	TLS ALPN value for HTTP over QUIC