Crate iroh_quinn

QUIC transport protocol implementation

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. It builds on top of quinn-proto, which implements protocol logic independent of any particular runtime.

The entry point of this crate is the Endpoint.

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.

Quinn also exposes unreliable datagrams, which are a low-level primitive preferred when automatic fragmentation and retransmission of certain data is not desired.

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 rustls;

pub use udp;

Modules

congestion

Logic for controlling the rate at which data is sent

crypto

Traits and implementations for the QUIC cryptography protocol

Structs

Accept

Future produced by Endpoint::accept

AcceptBi

Future produced by Connection::accept_bi

AcceptUni

Future produced by Connection::accept_uni

AckFrequencyConfig

Parameters for controlling the peer’s acknowledgement frequency

ApplicationClose

Reason given by an application for closing the connection

AsyncStdRuntime

A Quinn runtime for async-std

Chunk

A chunk of data from the receive stream

ClientConfig

Configuration for outgoing connections

ClosedStream

Error indicating that a stream has not been opened or has already been finished or reset

Connecting

In-progress connection attempt future

Connection

A QUIC connection.

ConnectionClose

Reason given by the transport for closing the connection

ConnectionId

Protocol-level identifier for a connection.

ConnectionStats

Connection statistics

Endpoint

A QUIC endpoint.

EndpointConfig

Global configuration for the endpoint, affecting all connections

EndpointStats

Statistics on Endpoint activity

FrameStats

Number of frames transmitted of each frame type

FrameType

A QUIC frame type

IdleTimeout

Maximum duration of inactivity to accept before timing out the connection

Incoming

An incoming connection for which the server has not yet begun its part of the handshake

IncomingFuture

Basic adapter to let Incoming be await-ed like a Connecting

MtuDiscoveryConfig

Parameters governing MTU discovery.

NoneTokenLog

Null implementation of TokenLog, which never accepts tokens

NoneTokenStore

Null implementation of TokenStore, which does not store any tokens

OpenBi

Future produced by Connection::open_bi

OpenUni

Future produced by Connection::open_uni

PathStats

Statistics related to a transmission path

ReadDatagram

Future produced by Connection::read_datagram

RecvStream

A stream that can only be used to receive data

RetryError

Error for attempting to retry an Incoming which already bears a token from a previous retry

SendDatagram

Future produced by Connection::send_datagram_wait

SendStream

A stream that can only be used to send data

ServerConfig

Parameters governing incoming connections

SmolRuntime

A Quinn runtime for smol

StdSystemTime

Default implementation of TimeSource

StreamId

Identifier for a stream within a particular connection

TokenReuseError

Error for when a validation token may have been reused

TokioRuntime

A Quinn runtime for Tokio

Transmit

An outgoing packet

TransportConfig

Parameters governing the core QUIC state machine

TransportErrorCode

Transport-level error code

UdpStats

Statistics about UDP datagrams transmitted or received on a connection

ValidationTokenConfig

Configuration for sending and handling validation tokens in incoming connections

VarInt

An integer less than 2^62

VarIntBoundsExceeded

Error returned when constructing a VarInt from a value >= 2^62

WeakConnectionHandle

A handle to some connection internals, use with care.

Written

Indicates how many bytes and chunks had been transferred in a write operation

ZeroRttAccepted

Future that completes when a connection is fully established

Enums

ConfigError

Errors in the configuration of an endpoint

ConnectError

Errors in the parameters being used to create a new connection

ConnectionError

Reasons why a connection might be lost

Dir

Whether a stream communicates data in both directions or only from the initiator

EcnCodepoint

Explicit congestion notification codepoint

ReadError

Errors that arise from reading from a stream.

ReadExactError

Errors that arise from reading from a stream.

ReadToEndError

Errors from RecvStream::read_to_end

ResetError

Errors that arise while waiting for a stream to be reset

SendDatagramError

Errors that can arise when sending a datagram

Side

Whether an endpoint was the initiator of a connection

StoppedError

Errors that arise while monitoring for a send stream stop from the peer

WriteError

Errors that arise from writing to a stream

Traits

AsyncTimer

Abstract implementation of an async timer for runtime independence

AsyncUdpSocket

Abstract implementation of a UDP socket for runtime independence

ConnectionIdGenerator

Generates connection IDs for incoming connections

Runtime

Abstracts I/O and timer operations for runtime independence

TimeSource

Object to get current SystemTime

TokenLog

Responsible for limiting clients’ ability to reuse validation tokens

TokenStore

Responsible for storing validation tokens received from servers and retrieving them for use in subsequent connections

UdpPoller

An object polled to detect when an associated AsyncUdpSocket is writable

Functions

default_runtime

Automatically select an appropriate runtime from those enabled at compile time