[][src]Crate quiche

Savoury implementation of the QUIC transport protocol and HTTP/3.

quiche is an implementation of the QUIC transport protocol as specified by the IETF. It provides a low level API for processing QUIC packets and handling connection state, while leaving I/O (including dealing with sockets) to the application.

The first step in establishing a QUIC connection using quiche is creating a configuration object:

let config = quiche::Config::new(quiche::VERSION_DRAFT18).unwrap();

This is shared among multiple connections and can be used to configure a QUIC endpoint.

Now a connection can be created, for clients the connect() utility function can be used, while accept() is for servers:

// Client connection.
let conn = quiche::connect(Some(&server_name), &scid, &mut config).unwrap();

// Server connection.
let conn = quiche::accept(&scid, None, &mut config).unwrap();

Using the connection's recv() method the application can process incoming packets from the network that belong to that connection:

let read = socket.recv(&mut buf).unwrap();

let read = match conn.recv(&mut buf[..read]) {
    Ok(v) => v,

    Err(quiche::Error::Done) => {
        // Done reading.
    },

    Err(e) => {
        // An error occurred, handle it.
    },
};

Outgoing packet are generated using the connection's send() method instead:

let write = match conn.send(&mut out) {
    Ok(v) => v,

    Err(quiche::Error::Done) => {
        // Done writing.
    },

    Err(e) => {
        // An error occurred, handle it.
    },
};

socket.send(&out[..write]).unwrap();

When packets are sent, the application is responsible for maintainig a timer to react to time-based connection events. The timer expiration can be obtained using the connection's timeout() method.

let timeout = conn.timeout();

The application is responsible for providing a timer implementation, which can be specific to the operating system or networking framework used. When a timer expires, the connection's on_timeout() method should be called, after which additional packets might need to be sent on the network:

// Timeout expired, do something.
conn.on_timeout();

let write = match conn.send(&mut out) {
    Ok(v) => v,

    Err(quiche::Error::Done) => {
        // Done writing.
    },

    Err(e) => {
        // An error occurred, handle it.
    },
};

socket.send(&out[..write]).unwrap();

After some back and forth, the connection will complete its handshake and will be ready for sending or receiving application data:

if conn.is_established() {
    // Handshake completed, send some data on stream 0.
    conn.stream_send(0, b"hello", true);
}

Modules

h3

HTTP/3 wire protocol and QPACK implementation.

Structs

Config

Stores configuration shared between multiple connections.

Connection

A QUIC connection.

Header

A QUIC packet's header.

Readable

An iterator over the streams that have outstanding data to read.

Stats

Statistics about the connection.

Enums

Error

A QUIC error.

Type

QUIC packet type.

Constants

MAX_CONN_ID_LEN

The maximum length of a connection ID.

VERSION_DRAFT18

The current QUIC wire version.

Functions

accept

Creates a new server-side connection.

connect

Creates a new client-side connection.

negotiate_version

Writes a version negotiation packet.

retry

Writes a stateless retry packet.

Type Definitions

Result

A specialized Result type for quiche operations.