aioquic Documentation

aioquic is a Python library for the QUIC network protocol. It provides three distinct API patterns depending on your integration needs:

1. QUIC API: Follows a "bring your own I/O" pattern. This is designed for embedding the protocol logic into any existing I/O framework or event loop.
2. HTTP/3 API: Also follows the "bring your own I/O" pattern, allowing you to implement HTTP/3 over custom I/O layers.
3. asyncio QUIC API: A convenience API built specifically on top of Python's standard asyncio framework for easier use in standard asynchronous applications.

Both the QUIC and HTTP/3 APIs in aioquic follow the sans-io pattern. This means the library does not perform actual I/O operations (like reading from or writing to a socket) itself. Instead, it manages the protocol logic and state, leaving the responsibility of moving bytes to and from the network to the API user.

This design allows you to integrate aioquic with any concurrency model or I/O loop and makes the protocol logic highly testable.

Encryption in aioquic is split into two layers to meet QUIC's specific requirements:

1. TLS 1.3 Logic: A minimal TLS 1.3 implementation is used, built on top of the cryptography library. This is necessary because QUIC requires specific capabilities not found in standard OpenSSL implementations, such as extracting traffic secrets and operating directly on TLS messages without the standard TLS record layer.

2. Packet Protection: Header protection and payload encryption are implemented as a C extension linked to OpenSSL to ensure high performance, as these operations occur for every single packet.

The QUIC API communicates state changes and incoming data through QuicEvent objects (from aioquic.quic.events). When you feed received data into the connection, it will produce events that you must handle. Key events include:

• HandshakeCompleted: The TLS handshake is finished.
• StreamDataReceived: New data has arrived on a specific stream.
• StreamReset: A stream was reset.
• ConnectionTerminated: The connection was closed.
• PingAcknowledged: A ping was acknowledged.
• StopSendingReceived: The peer requested to stop receiving data.

The HTTP/3 API communicates via events defined in aioquic.h3.events. When processing data from the connection, you should check the type of H3Event received to determine how to react. Supported event types include:

• DatagramReceived: Triggered when a QUIC datagram is received.
• DataReceived: Triggered when stream data is received.
• HeadersReceived: Triggered when HTTP headers are received.
• PushPromiseReceived: Triggered when a server push promise is received.
• WebTransportStreamDataReceived: Triggered when WebTransport stream data is received.

The simplest way to install aioquic is using pip.

pip install aioquic

The HTTP/3 examples include a server capable of handling both HTTP/0.9 and HTTP/3, and a client for making requests.

Server usage: Run the server by providing a TLS certificate and private key.

Client usage:

• Standard HTTP/3: Perform a standard request using --ca-certs.
• Legacy HTTP/0.9: Use the --legacy-http flag to perform an HTTP/0.9 request.
• WebSockets: Use the wss:// scheme to open a WebSocket over HTTP/3.

To run the provided examples, you must install the project along with several required dependencies including dnslib, jinja2, starlette, and wsproto.

pip install . dnslib jinja2 starlette wsproto