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 aQuicConnectionProtocol
which can be used to create streams.
connect()
also accepts the following optional arguments: :rtype:AsyncGenerator
[QuicConnectionProtocol
,None
]
configuration
is aQuicConfiguration
configuration object.
create_protocol
allows customizing theProtocol
that manages the connection. It should be a callable or class accepting the same arguments asQuicConnectionProtocol
and returning an instance ofQuicConnectionProtocol
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: aasyncio.StreamReader
and aasyncio.StreamWriter
.
wait_connected
indicates whether the context manager should wait for the connection to be established before yielding theQuicConnectionProtocol
. 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.
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 aQuicConfiguration
containing TLS certificate and private key as theconfiguration
argument.
serve()
also accepts the following optional arguments: :rtype:QuicServer
create_protocol
allows customizing theProtocol
that manages the connection. It should be a callable or class accepting the same arguments asQuicConnectionProtocol
and returning an instance ofQuicConnectionProtocol
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: aasyncio.StreamReader
and aasyncio.StreamWriter
.
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:
- close(error_code=QuicErrorCode.NO_ERROR, reason_phrase='')¶
Close the connection.
- connect(addr, transmit=True)¶
Initiate the TLS handshake.
This method can only be called for clients and a single time.
- Return type:
- 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
andasyncio.StreamWriter
classes.
- Return type:
Tuple
[StreamReader
,StreamWriter
]
- quic_event_received(event)¶
Called when a QUIC event is received.
Reimplement this in your subclass to handle the events.
- Return type:
- 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: