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

aioquic.asyncio.connect(host, port, *, configuration=None, create_protocol=<class 'aioquic.asyncio.protocol.QuicConnectionProtocol'>, session_ticket_handler=None, stream_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.

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

Return type

AsyncGenerator[QuicConnectionProtocol, None]

Server

async 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()

Close the connection.

Return type

None

connect(addr)

Initiate the TLS handshake.

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

Return type

None

connection_made(transport)

Called when a connection is made.

The argument is the transport representing the pipe connection. To receive data, wait for data_received() calls. When the connection is closed, connection_lost() is called.

Return type

None

coroutine create_stream(self, 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]

datagram_received(data, addr)

Called when some datagram is received.

Return type

None

coroutine ping(self)

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.

Return type

None

coroutine wait_closed(self)

Wait for the connection to be closed.

Return type

None

coroutine wait_connected(self)

Wait for the TLS handshake to complete.

Return type

None