tag | 77b541ab4a5ba192b27de2663d8634b6ed251927 | |
---|---|---|
tagger | Alessandro Ghedini <alessandro@ghedini.me> | Thu Jan 24 16:31:05 2019 +0000 |
object | 0e8576aaf3729e4f532031dbb3689b74622b531d |
quiche 0.1.0-alpha2
commit | 0e8576aaf3729e4f532031dbb3689b74622b531d | [log] [tgz] |
---|---|---|
author | Alessandro Ghedini <alessandro@ghedini.me> | Thu Jan 24 16:30:54 2019 +0000 |
committer | Alessandro Ghedini <alessandro@ghedini.me> | Thu Jan 24 16:30:54 2019 +0000 |
tree | 7669912d48d630c36a160e843ba65fb874d411ab | |
parent | 39a4ad5f19b1d31d5b58b82cce64c941953eaf40 [diff] |
0.1.0-alpha2
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. The application is responsible for providing I/O (e.g. sockets handling) as well as an event loop with support for timers.
A live QUIC server based on quiche is available at https://quic.tech:4433/
to be used for experimentation.
Note that it is very experimental and unstable software, and many features are still in development.
For more information on how quiche came about and some insights into its design you can read a post on Cloudflare's (where this library is used in production) blog that goes into some more detail.
The first step in establishing a QUIC connection using quiche is creating a configuration object:
let config = quiche::Config::new(quiche::VERSION_DRAFT17).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. # return; }, Err(e) => { // An error occurred, handle it. # return; }, };
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. # return; }, Err(e) => { // An error occurred, handle it. # return; }, }; 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. # return; }, Err(e) => { // An error occurred, handle it. # return; }, }; 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); }
Have a look at the examples/ directory for more complete examples on how to use the quiche API, including examples on how to use quiche in C/C++ applications (see below for more information).
quiche exposes a thin C API on top of the Rust API that can be used to more easily integrate quiche into C/C++ applications (as well as in other languages that allow calling C APIs via some form of FFI). The C API follows the same design of the Rust one, modulo the constraints imposed by the C language itself.
When running cargo build
, a static library called libquiche.a
will be built automatically alongside the Rust one. This is fully stand-alone and can be linked directly into C/C++ applications.
The first step after cloning the git repo is updating the git submodules:
$ git submodule update --init
You can now build quiche using cargo:
$ cargo build --examples
As well as run its tests:
$ cargo test
Note that BoringSSL, used to implement QUIC's cryptographic handshake based on TLS, needs to be built and linked to quiche. This is done automatically when building quiche using cargo, but requires the cmake
and go
commands to be available during the build process.
In alternative you can use your own custom build of BoringSSL by configuring the BoringSSL directory with the QUICHE_BSSL_PATH
environment variable:
$ QUICHE_BSSL_PATH="/path/to/boringssl" cargo build --examples
Copyright (C) 2018, Cloudflare, Inc.
Copyright (C) 2018, Alessandro Ghedini
See COPYING for the license.