# Technical Documentation: quinn-rs/quinn
> ℹ️ **Provenance:** Hybrid Fusion: `quinn-rs/quinn` (README + 8 In-Tree Chapters) · [CodeWiki Reference](https://codewiki.google/github.com/quinn-rs/quinn) · Recency: Active (< 180 days)
## 1. Project Overview & Quickstart (quinn-rs/quinn)
[](https://docs.rs/quinn/)
[](https://crates.io/crates/quinn)
[](https://github.com/djc/quinn/actions?query=workflow%3ACI)
[](https://codecov.io/gh/quinn-rs/quinn)
[](https://matrix.to/#/#quinn:matrix.org)
[](https://discord.gg/SGPEcDfVzh)
[](LICENSE-MIT)
[](LICENSE-APACHE)
Quinn is a pure-Rust, async-compatible implementation of the IETF [QUIC][quic] transport protocol.
The project was founded by [Dirkjan Ochtman](https://github.com/djc) and
[Benjamin Saunders](https://github.com/Ralith) as a side project in 2018, and has seen more than
30 releases since then. If you're using Quinn in a commercial setting, please consider
[sponsoring](https://opencollective.com/quinn-rs) the project.
## 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][rustls] and [*ring*][ring]
- Application-layer datagrams for small, unreliable messages
- Future-based async API
- Minimum supported Rust version of 1.80.0
## Overview
- **quinn:** High-level async API based on tokio, see [examples][examples] 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][sans-io] 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.
- **bench:** Benchmarks without any framework.
- **fuzz:** Fuzz tests.
# Getting Started
**Examples**
```sh
$ 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][talk]; [slides][slides]; [YouTube][youtube]
- Usage [examples][examples]
- Guide [book][documentation]
## 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][letsencrypt]
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 customizing the `rustls` configuration; see the
[insecure_connection.rs][insecure] example for details.
When operating your own certificate authority doesn't make sense, [rcgen][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][issues].
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.
[quic]: https://quicwg.github.io/
[issues]: https://github.com/djc/quinn/issues
[rustls]: https://github.com/ctz/rustls
[ring]: https://github.com/briansmith/ring
[talk]: https://paris.rustfest.eu/sessions/a-quic-future-in-rust
[slides]: https://github.com/djc/talks/blob/ff760845b51ba4836cce82e7f2c640ecb5fd59fa/2018-05-26%20A%20QUIC%20future%20in%20Rust/Quinn-Speaker.pdf
[animation]: https://dirkjan.ochtman.nl/files/head-of-line-blocking.html
[youtube]: https://www.youtube.com/watch?v=EHgyY5DNdvI
[letsencrypt]: https://letsencrypt.org/
[rcgen]: https://crates.io/crates/rcgen
[examples]: https://github.com/djc/quinn/tree/main/quinn/examples
[documentation]: https://quinn-rs.github.io/quinn/networking-introduction.html
[sans-io]: https://sans-io.readthedocs.io/how-to-sans-io.html
[insecure]: https://github.com/quinn-rs/quinn/blob/main/quinn/examples/insecure_connection.rs
## 2. In-Tree Documentation Chapters (quinn-rs/quinn)
## File: README.md
[](https://docs.rs/quinn/)
[](https://crates.io/crates/quinn)
[](https://github.com/djc/quinn/actions?query=workflow%3ACI)
[](https://codecov.io/gh/quinn-rs/quinn)
[](https://matrix.to/#/#quinn:matrix.org)
[](https://discord.gg/SGPEcDfVzh)
[](LICENSE-MIT)
[](LICENSE-APACHE)
Quinn is a pure-Rust, async-compatible implementation of the IETF [QUIC][quic] transport protocol.
The project was founded by [Dirkjan Ochtman](https://github.com/djc) and
[Benjamin Saunders](https://github.com/Ralith) as a side project in 2018, and has seen more than
30 releases since then. If you're using Quinn in a commercial setting, please consider
[sponsoring](https://opencollective.com/quinn-rs) the project.
## 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][rustls] and [*ring*][ring]
- Application-layer datagrams for small, unreliable messages
- Future-based async API
- Minimum supported Rust version of 1.80.0
## Overview
- **quinn:** High-level async API based on tokio, see [examples][examples] 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][sans-io] 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.
- **bench:** Benchmarks without any framework.
- **fuzz:** Fuzz tests.
# Getting Started
**Examples**
```sh
$ 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][talk]; [slides][slides]; [YouTube][youtube]
- Usage [examples][examples]
- Guide [book][documentation]
## 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][letsencrypt]
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 customizing the `rustls` configuration; see the
[insecure_connection.rs][insecure] example for details.
When operating your own certificate authority doesn't make sense, [rcgen][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][issues].
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.
[quic]: https://quicwg.github.io/
[issues]: https://github.com/djc/quinn/issues
[rustls]: https://github.com/ctz/rustls
[ring]: https://github.com/briansmith/ring
[talk]: https://paris.rustfest.eu/sessions/a-quic-future-in-rust
[slides]: https://github.com/djc/talks/blob/ff760845b51ba4836cce82e7f2c640ecb5fd59fa/2018-05-26%20A%20QUIC%20future%20in%20Rust/Quinn-Speaker.pdf
[animation]: https://dirkjan.ochtman.nl/files/head-of-line-blocking.html
[youtube]: https://www.youtube.com/watch?v=EHgyY5DNdvI
[letsencrypt]: https://letsencrypt.org/
[rcgen]: https://crates.io/crates/rcgen
[examples]: https://github.com/djc/quinn/tree/main/quinn/examples
[documentation]: https://quinn-rs.github.io/quinn/networking-introduction.html
[sans-io]: https://sans-io.readthedocs.io/how-to-sans-io.html
[insecure]: https://github.com/quinn-rs/quinn/blob/main/quinn/examples/insecure_connection.rs
---
## File: docs/book/src/quinn/certificate.md
# Certificates
In this chapter, we discuss the configuration of the certificates that are **required** for a working Quinn connection.
As QUIC uses TLS 1.3 for authentication of connections, the server needs to provide the client with a certificate confirming its identity, and the client must be configured to trust the certificates it receives from the server.
## Insecure Connection
For our example use case, the easiest way to allow the client to trust our server is to disable certificate verification (don't do this in production!).
When the [rustls][3] `dangerous_configuration` feature flag is enabled, a client can be configured to trust any server.
Start by adding a [rustls][3] dependency with the `dangerous_configuration` feature flag to your `Cargo.toml` file.
```toml
quinn = "0.11"
rustls = "0.23"
```
Then, allow the client to skip the certificate validation by implementing [ServerCertVerifier][ServerCertVerifier] and letting it assert verification for any server.
```rust
{{#include ../bin/certificate.rs:36:88}}
```
After that, modify the [ClientConfig][ClientConfig] to use this [ServerCertVerifier][ServerCertVerifier] implementation.
```rust
{{#include ../bin/certificate.rs:25:34}}
```
Finally, if you plug this [ClientConfig][ClientConfig] into the [Endpoint::set_default_client_config()][set_default_client_config] your client endpoint should verify all connections as trustworthy.
## Using Certificates
In this section, we look at certifying an endpoint with a certificate.
The certificate can be signed with its key, or with a certificate authority's key.
### Self Signed Certificates
Relying on [self-signed][5] certificates means that clients allow servers to sign their certificates.
This is simpler because no third party is involved in signing the server's certificate.
However, self-signed certificates do not protect users from person-in-the-middle attacks, because an interceptor can trivially replace the certificate with one that it has signed. Self-signed certificates, among other options, can be created using the [rcgen][4] crate or the openssl binary.
This example uses [rcgen][4] to generate a certificate.
Let's look at an example:
```rust
{{#include ../bin/certificate.rs:90:96}}
```
_Note that [generate_simple_self_signed][generate_simple_self_signed] returns a [Certificate][2] that can be serialized to both `.der` and `.pem` formats._
### Non-self-signed Certificates
For this example, we use [Let's Encrypt][6], a well-known Certificate Authority ([CA][1]) (certificate issuer) which distributes certificates for free.
**Generate Certificate**
[certbot][7] can be used with Let's Encrypt to generate certificates; its website comes with clear instructions.
Because we're generating a certificate for an internal test server, the process used will be slightly different compared to what you would do when generating certificates for an existing (public) website.
On the certbot website, select that you do not have a public web server and follow the given installation instructions.
certbot must answer a cryptographic challenge of the Let's Encrypt API to prove that you control the domain.
It needs to listen on port 80 (HTTP) or 443 (HTTPS) to achieve this. Open the appropriate port in your firewall and router.
If certbot is installed, run `certbot certonly --standalone`, this command will start a web server in the background and start the challenge.
certbot asks for the required data and writes the certificates to `fullchain.pem` and the private key to `privkey.pem`.
These files can then be referenced in code.
```rust
{{#include ../bin/certificate.rs:98:106}}
```
### Configuring Certificates
Now that you have a valid certificate, the client and server need to be configured to use it.
After configuring plug the configuration into the `Endpoint`.
**Configure Server**
```rust
{{#include ../bin/certificate.rs:20}}
```
This is the only thing you need to do for your server to be secured.
**Configure Client**
```rust
{{#include ../bin/certificate.rs:21}}
```
This is the only thing you need to do for your client to trust a server certificate signed by a conventional certificate authority.
[Next](set-up-connection.md), let's have a look at how to set up a connection.
[1]: https://en.wikipedia.org/wiki/Certificate_authority
[2]: https://en.wikipedia.org/wiki/Public_key_certificate
[3]: https://github.com/ctz/rustls
[4]: https://github.com/est31/rcgen
[5]: https://en.wikipedia.org/wiki/Self-signed_certificate#:~:text=In%20cryptography%20and%20computer%20security,a%20CA%20aim%20to%20provide.
[6]: https://letsencrypt.org/getting-started/
[7]: https://certbot.eff.org/instructions
[ClientConfig]: https://docs.rs/quinn/latest/quinn/struct.ClientConfig.html
[ServerCertVerifier]: https://docs.rs/rustls/latest/rustls/client/trait.ServerCertVerifier.html
[set_default_client_config]: https://docs.rs/quinn/latest/quinn/struct.Endpoint.html#method.set_default_client_config
[generate_simple_self_signed]: https://docs.rs/rcgen/latest/rcgen/fn.generate_simple_self_signed.html
[Certificate]: https://docs.rs/rcgen/latest/rcgen/struct.Certificate.html
---
## File: docs/book/src/quinn/data-transfer.md
# Data Transfer
The [previous chapter](set-up-connection.md) explained how to set up an [Endpoint][Endpoint]
and then get access to a [Connection][Connection].
This chapter continues with the subject of sending data over this connection.
## Multiplexing
Multiplexing is the act of combining data from multiple streams into a single stream.
This can have a significant positive effect on the performance of the application.
With QUIC, the programmer is in full control over the stream allocation.
## Stream Types
QUIC provides support for both stream and message-based communication.
Streams and messages can be initiated both on the client and server.
| Type | Description | Reference |
| :----------------------------------- | :-------------------------------------- | :--------------------------------- |
| **Bidirectional Stream** | two way stream communication. | see [open_bi][open_bi] |
| **Unidirectional Stream** | one way stream communication. | see [open_uni][open_uni] |
| **Unreliable Messaging (extension)** | message based unreliable communication. | see [send_datagram][send_datagram] |
## How to Use
New streams can be created with [Connection][Connection]'s [open_bi()][open_bi] and
[open_uni()][open_uni] methods.
## Bidirectional Streams
With bidirectional streams, data can be sent in both directions.
For example, from the connection initiator to the peer and the other way around.
_open bidirectional stream_
```rust
{{#include ../bin/data-transfer.rs:7:13}}
```
_iterate incoming bidirectional stream(s)_
```rust
{{#include ../bin/data-transfer.rs:16:24}}
```
## Unidirectional Streams
With unidirectional streams, you can carry data only in one direction: from the initiator of the stream to its peer.
It is possible to get reliability without ordering (so no head-of-line blocking) by opening a new stream for each packet.
_open unidirectional stream_
```rust
{{#include ../bin/data-transfer.rs:27:32}}
```
_iterating incoming unidirectional stream(s)_
```rust
{{#include ../bin/data-transfer.rs:35:41}}
```
## Unreliable Messaging
With unreliable messaging, you can transfer data without reliability.
This could be useful if data arrival isn't essential or when high throughput is important.
_send datagram_
```rust
{{#include ../bin/data-transfer.rs:44:47}}
```
_iterating datagram stream(s)_
```rust
{{#include ../bin/data-transfer.rs:50:56}}
```
[Endpoint]: https://docs.rs/quinn/latest/quinn/struct.Endpoint.html
[Connection]: https://docs.rs/quinn/latest/quinn/struct.Connection.html
[open_bi]: https://docs.rs/quinn/latest/quinn/struct.Connection.html#method.open_bi
[open_uni]: https://docs.rs/quinn/latest/quinn/struct.Connection.html#method.open_uni
[send_datagram]: https://docs.rs/quinn/latest/quinn/struct.Connection.html#method.send_datagram
---
## File: docs/book/src/quinn/set-up-connection.md
# Connection Setup
In the [previous chapter](certificate.md) we looked at how to configure a certificate.
This aspect is omitted in this chapter to prevent duplication.
But **remember** that this is required to get your [Endpoint][Endpoint] up and running.
This chapter explains how to set up a connection and prepare it for data transfer.
It all starts with the [Endpoint][Endpoint] struct, this is the entry point of the library.
## Example
Let's start by defining some constants.
```rust
{{#include ../bin/set-up-connection.rs:35:38}}
```
**Server**
First, the server endpoint should be bound to a socket.
The [server()][server] method, which can be used for this, returns the `Endpoint` type.
`Endpoint` is used to start outgoing connections and accept incoming connections.
```rust
{{#include ../bin/set-up-connection.rs:8:20}}
```
**Client**
The [client()][client] returns only a `Endpoint` type.
The client needs to connect to the server using the [connect(server_name)][connect] method.
The `SERVER_NAME` argument is the DNS name, matching the certificate configured in the server.
```rust
{{#include ../bin/set-up-connection.rs:23:33}}
```
[Next up](data-transfer.md), let's have a look at sending data over this connection.
[Endpoint]: https://docs.rs/quinn/latest/quinn/struct.Endpoint.html
[server]: https://docs.rs/quinn/latest/quinn/struct.Endpoint.html#method.server
[client]: https://docs.rs/quinn/latest/quinn/struct.Endpoint.html#method.client
[connect]: https://docs.rs/quinn/latest/quinn/struct.Endpoint.html#method.connect
---
## File: docs/book/src/networking-introduction.md
# Networking Introduction
In this chapter, you will find a very short introduction to various networking concepts.
These concepts are important to understanding when to use QUIC.
## 1. TCP/IP and UDP Comparison
Let's compare TCP, UDP, and QUIC.
- **unreliable**: Transport packets are not assured of arrival and ordering.
- **reliable**: Transport packets are assured of arrival and ordering.
| Feature | TCP | UDP | QUIC
| :-------------: | :-------------: | :-------------: | :-------------: |
| [Connection-Oriented][6] | Yes | No | Yes
| Transport Guarantees | Reliable | Unreliable | Reliable ('a)
| Packet Transfer | [Stream-based][4] | Message based | Stream based
| Header Size | ~20 bytes | 8 bytes | ~16 bytes (depending on connection id)
| [Control Flow, Congestion Avoidance/Control][5] | Yes | No | Yes ('b)
| Based On | [IP][3] | [IP][3] | UDP
'a. Unreliable is supported as an extension.
'b. QUIC control flow/congestion implementations will run in userspace whereas in TCP it's running in kernel space,
however, there might be a kernel implementation for QUIC in the future.
## 2. Issues with TCP
TCP has been around for a long time and was not designed with the modern internet in mind.
It has several difficulties that QUIC tries to resolve.
### Head-of-line Blocking
One of the biggest issues with TCP is that of Head-of-line blocking.
It is a convenient feature because it ensures that all packages are sent and arrive in order.
However, in cases of high throughput (multiplayer game networking) and big load in a short time (web page load), this can severely impact latency.
The issue is demonstrated in the following animation:
![Head of line blocking][animation]
This animation shows that if a certain packet drops in transmission, all packets have to wait at the transport layer until it is resent by the other end. Once the delayed packet arrives at its destination, all later packets are passed on to the destination application together.
Let's look at two areas where head-of-line blocking causes problems.
**Web Networking**
As websites increasingly need a larger number of HTTP requests (HTML, CSS, JavaScript, images) to display all content, the impact of head-of-line blocking has also increased.
To improve on this, HTTP 2 introduced request multiplexing within a TCP data stream, which allows servers to stream multiple responses at the same time.
However, data loss of a single packet will still block all response streams because they exist within the context of a single TCP stream.
### Connection Setup Duration
In the usual TCP + TLS + HTTP stack, TCP needs 6 handshake messages to set up a session between server and client. TLS performs its own, sending 4 messages for setting up an initial connection over TLS 1.3. By integrating the transport protocol and TLS handshakes, QUIC can make connection setup more efficient.
[animation]: ./images/hol.gif
[1]: https://en.wikipedia.org/wiki/Packet_loss
[2]: https://observersupport.viavisolutions.com/html_doc/current/index.html#page/gigastor_hw/packet_deduplicating.html
[3]: https://nl.wikipedia.org/wiki/Internetprotocol
[4]: https://en.wikipedia.org/wiki/Stream_(computing)
[5]: https://en.wikipedia.org/wiki/TCP_congestion_control
[6]: https://en.wikipedia.org/wiki/Connection-oriented_communication
[7]: https://en.wikipedia.org/wiki/Internet_protocol_suite
[8]: https://en.wikipedia.org/wiki/IP_fragmentation
---
## File: docs/book/src/quic.md
# The QUIC protocol
[QUIC] is a general-purpose network protocol built on top of UDP,
and [standardized][rfc] by the [IETF]. Although QUIC is still relatively new,
the protocol is used for all connections from Chrome web browsers to the Google servers.
QUIC solves a number of transport-layer and application-layer problems experienced by modern web applications.
It is very similar to TCP+TLS+HTTP2, but implemented on top of UDP.
Having QUIC as a self-contained protocol allows innovations which aren’t
possible with existing protocols as they are hampered by legacy clients and middleboxes.
Key advantages of QUIC over TCP+TLS+HTTP2 include:
* Improved connection establishment speed (0-rtt).
* Improved congestion control by moving congestion control algorithms into the user space at both endpoints.
* Improved bandwidth estimation in each direction to avoid congestion.
* Improved multiplexing without head-of-line blocking.
* Contains forward error correction (FEC).
While QUIC's intentions are originally web-oriented, it offers interesting opportunities in other areas like game networking.
One thing is for sure, QUIC has many great potentials and will serve us in the future with HTTP/3.
In the upcoming chapter we will be discussing various aspects of QUIC also in relation to Quinn.
[rfc]: https://www.rfc-editor.org/rfc/rfc9000.html
[IETF]: https://www.ietf.org/
[QUIC]: https://en.wikipedia.org/wiki/QUIC
---
## File: docs/book/src/SUMMARY.md
# Summary
- [Networking introduction](networking-introduction.md)
- [QUIC introduction](quic.md)
- [QUINN Introduction](quinn.md)
- [Certificate Configuration](quinn/certificate.md)
- [Connection Setup](quinn/set-up-connection.md)
- [Data Transfer](quinn/data-transfer.md)
---
## File: quinn/examples/README.md
## HTTP/0.9 File Serving Example
The `server` and `client` examples demonstrate fetching files using a HTTP-like toy protocol.
1. Server (`server.rs`)
The server listens for any client requesting a file.
If the file path is valid and allowed, it returns the contents.
Open up a terminal and execute:
```text
$ cargo run --example server ./
```
2. Client (`client.rs`)
The client requests a file and prints it to the console.
If the file is on the server, it will receive the response.
In a new terminal execute:
```test
$ cargo run --example client https://localhost:4433/Cargo.toml
```
where `Cargo.toml` is any file in the directory passed to the server.
**Result:**
The output will be the contents of this README.
**Troubleshooting:**
If the client times out with no activity on the server, try forcing the server to run on IPv4 by
running it with `cargo run --example server -- ./ --listen 127.0.0.1:4433`. The server listens on
IPv6 by default, `localhost` tends to resolve to IPv4, and support for accepting IPv4 packets on
IPv6 sockets varies between platforms.
If the client prints `failed to process request: failed reading file`, the request was processed
successfully but the path segment of the URL did not correspond to a file in the directory being
served.
## Minimal Example
The `connection.rs` example intends to use the smallest amount of code to make a simple QUIC connection.
The server issues it's own certificate and passes it to the client to trust.
```text
$ cargo run --example connection
```
This example will make a QUIC connection on localhost, and you should see output like:
```text
[client] connected: addr=127.0.0.1:5000
[server] connection accepted: addr=127.0.0.1:53712
```
## Insecure Connection Example
The `insecure_connection.rs` example demonstrates how to make a QUIC connection that ignores the server certificate.
```text
$ cargo run --example insecure_connection --features="rustls/dangerous_configuration"
```
## Single Socket Example
You can have multiple QUIC connections over a single UDP socket. This is especially
useful, if you are building a peer-to-peer system where you potentially need to communicate with
thousands of peers or if you have a
[hole punched](https://en.wikipedia.org/wiki/UDP_hole_punching) UDP socket.
Additionally, QUIC servers and clients can both operate on the same UDP socket.
This example demonstrates how to make multiple outgoing connections on a single UDP socket.
```text
$ cargo run --example single_socket
```
The expected output should be something like:
```text
[client] connected: addr=127.0.0.1:5000
[server] incoming connection: addr=127.0.0.1:48930
[client] connected: addr=127.0.0.1:5001
[client] connected: addr=127.0.0.1:5002
[server] incoming connection: addr=127.0.0.1:48930
[server] incoming connection: addr=127.0.0.1:48930
```
Notice how the server sees multiple incoming connections with different IDs coming from the same
endpoint.
--- METRICS ---
- Files Extracted: 9
- Estimated Token Budget: ~6937 tokens
- Recency Window: Active (< 180 days)
- Canonical Reference: https://codewiki.google/github.com/quinn-rs/quinn