asyncio API

The asyncio API provides a high-level QUIC API built on top of asyncio, Python’s standard asynchronous I/O framework.

aioquic comes with a selection of examples, including:

• an HTTP/3 client

• an HTTP/3 server

The examples can be browsed on GitHub:

https://github.com/aiortc/aioquic/tree/main/examples

Client

async with aioquic.asyncio.connect(host, port, *, configuration=None, create_protocol=<class 'aioquic.asyncio.protocol.QuicConnectionProtocol'>, session_ticket_handler=None, stream_handler=None, token_handler=None, wait_connected=True, local_port=0)

Connect to a QUIC server at the given host and port.

connect() returns an awaitable. Awaiting it yields a QuicConnectionProtocol which can be used to create streams.

connect() also accepts the following optional arguments:

• configuration is a QuicConfiguration configuration object.

• create_protocol allows customizing the Protocol that manages the connection. It should be a callable or class accepting the same arguments as QuicConnectionProtocol and returning an instance of QuicConnectionProtocol or a subclass.

• session_ticket_handler is a callback which is invoked by the TLS engine when a new session ticket is received.

• stream_handler is a callback which is invoked whenever a stream is created. It must accept two arguments: a asyncio.StreamReader and a asyncio.StreamWriter.

• wait_connected indicates whether the context manager should wait for the connection to be established before yielding the QuicConnectionProtocol. By default this is True but you can set it to False if you want to immediately start sending data using 0-RTT.

• local_port is the UDP port number that this client wants to bind.

Return type:

AsyncGenerator[QuicConnectionProtocol, None]

Server

await aioquic.asyncio.serve(host, port, *, configuration, create_protocol=<class 'aioquic.asyncio.protocol.QuicConnectionProtocol'>, session_ticket_fetcher=None, session_ticket_handler=None, retry=False, stream_handler=None)

Start a QUIC server at the given host and port.

serve() requires a QuicConfiguration containing TLS certificate and private key as the configuration argument.

serve() also accepts the following optional arguments:

• create_protocol allows customizing the Protocol that manages the connection. It should be a callable or class accepting the same arguments as QuicConnectionProtocol and returning an instance of QuicConnectionProtocol or a subclass.

• session_ticket_fetcher is a callback which is invoked by the TLS engine when a session ticket is presented by the peer. It should return the session ticket with the specified ID or None if it is not found.

• session_ticket_handler is a callback which is invoked by the TLS engine when a new session ticket is issued. It should store the session ticket for future lookup.

• retry specifies whether client addresses should be validated prior to the cryptographic handshake using a retry packet.

• stream_handler is a callback which is invoked whenever a stream is created. It must accept two arguments: a asyncio.StreamReader and a asyncio.StreamWriter.

Return type:

QuicServer

Common

class aioquic.asyncio.QuicConnectionProtocol(quic, stream_handler=None)

change_connection_id()

Change the connection ID used to communicate with the peer.

The previous connection ID will be retired.

Return type:

None

close(error_code=QuicErrorCode.NO_ERROR, reason_phrase='')

Close the connection.

Parameters:

• error_code (int) – An error code indicating why the connection is being closed.

• reason_phrase (str) – A human-readable explanation of why the connection is being closed.

Return type:

None

connect(addr, transmit=True)

Initiate the TLS handshake.

This method can only be called for clients and a single time.

Return type:

None

await create_stream(is_unidirectional=False)

Create a QUIC stream and return a pair of (reader, writer) objects.

The returned reader and writer objects are instances of asyncio.StreamReader and asyncio.StreamWriter classes.

Return type:

tuple[StreamReader, StreamWriter]

await ping()

Ping the peer and wait for the response.

Return type:

None

quic_event_received(event)

Called when a QUIC event is received.

Reimplement this in your subclass to handle the events.

Return type:

None

request_key_update()

Request an update of the encryption keys.

Return type:

None

transmit()

Send pending datagrams to the peer and arm the timer if needed.

This method is called automatically when data is received from the peer or when a timer goes off. If you interact directly with the underlying QuicConnection, make sure you call this method whenever data needs to be sent out to the network.

Return type:

None

await wait_closed()

Wait for the connection to be closed.

Return type:

None

await wait_connected()

Wait for the TLS handshake to complete.

Return type:

None