QUIC API

The QUIC API performs no I/O on its own, leaving this to the API user. This allows you to integrate QUIC in any Python application, regardless of the concurrency model you are using.

Connection

class aioquic.quic.connection.QuicConnection(*, configuration, original_destination_connection_id=None, retry_source_connection_id=None, session_ticket_fetcher=None, session_ticket_handler=None, token_handler=None)

A QUIC connection.

The state machine is driven by three kinds of sources:

• the API user requesting data to be send out (see connect(), reset_stream(), send_ping(), send_datagram_frame() and send_stream_data())

• data being received from the network (see receive_datagram())

• a timer firing (see handle_timer())

Parameters:

configuration (QuicConfiguration) – The QUIC configuration to use.

change_connection_id()

Switch to the next available connection ID and retire the previous one.

Note

After calling this method you need to call the QUIC connection datagrams_to_send() method to retrieve data which needs to be sent over the network. If you are using the asyncio API, calling the transmit() method will do it for you.

Return type:

None

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

Close the connection.

Note

After calling this method you need to call the QUIC connection datagrams_to_send() method to retrieve data which needs to be sent over the network. If you are using the asyncio API, calling the transmit() method will do it for you.

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, now)

Initiate the TLS handshake.

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

Note

After calling this method you need to call the QUIC connection datagrams_to_send() method to retrieve data which needs to be sent over the network. If you are using the asyncio API, calling the transmit() method will do it for you.

Parameters:

• addr (Any) – The network address of the remote peer.

• now (float) – The current time.

Return type:

None

datagrams_to_send(now)

Return a list of (data, addr) tuples of datagrams which need to be sent, and the network address to which they need to be sent.

After calling this method call get_timer() to know when the next timer needs to be set.

Parameters:

now (float) – The current time.

Return type:

list[tuple[bytes, Any]]

get_next_available_stream_id(is_unidirectional=False)

Return the stream ID for the next stream created by this endpoint.

Return type:

int

get_peer_address()

Return the peer address to which datagrams are currently sent, or None if none is known yet.

This address can change during the connection’s lifetime when either endpoint migrates, see RFC 9000 section 9.

Return type:

Optional[Any]

get_timer()

Return the time at which the timer should fire or None if no timer is needed.

Return type:

Optional[float]

handle_timer(now)

Handle the timer.

Note

After calling this method you need to call the QUIC connection datagrams_to_send() method to retrieve data which needs to be sent over the network. If you are using the asyncio API, calling the transmit() method will do it for you.

Parameters:

now (float) – The current time.

Return type:

None

next_event()

Retrieve the next event from the event buffer.

Returns None if there are no buffered events.

Return type:

Optional[QuicEvent]

receive_datagram(data, addr, now)

Handle an incoming datagram.

Note

After calling this method you need to call the QUIC connection datagrams_to_send() method to retrieve data which needs to be sent over the network. If you are using the asyncio API, calling the transmit() method will do it for you.

Parameters:

• data (bytes) – The datagram which was received.

• addr (Any) – The network address from which the datagram was received.

• now (float) – The current time.

Return type:

None

request_key_update()

Request an update of the encryption keys.

If the handshake is not confirmed yet, the key update is deferred until it is.

Note

After calling this method you need to call the QUIC connection datagrams_to_send() method to retrieve data which needs to be sent over the network. If you are using the asyncio API, calling the transmit() method will do it for you.

Return type:

None

reset_stream(stream_id, error_code)

Abruptly terminate the sending part of a stream.

This method has no effect if a reset has already been triggered either by a call to reset_stream() or by the reception of a STOP_SENDING frame, or if all the stream’s data has already been acknowledged.

Note

After calling this method you need to call the QUIC connection datagrams_to_send() method to retrieve data which needs to be sent over the network. If you are using the asyncio API, calling the transmit() method will do it for you.

Parameters:

• stream_id (int) – The stream’s ID.

• error_code (int) – An error code indicating why the stream is being reset.

Return type:

None

send_datagram_frame(data)

Send a DATAGRAM frame.

Note

After calling this method you need to call the QUIC connection datagrams_to_send() method to retrieve data which needs to be sent over the network. If you are using the asyncio API, calling the transmit() method will do it for you.

Parameters:

data (bytes) – The data to be sent.

Return type:

None

send_ping(uid)

Send a PING frame to the peer.

Note

After calling this method you need to call the QUIC connection datagrams_to_send() method to retrieve data which needs to be sent over the network. If you are using the asyncio API, calling the transmit() method will do it for you.

Parameters:

uid (int) – A unique ID for this PING.

Return type:

None

send_stream_data(stream_id, data, end_stream=False)

Send data on the specific stream.

Note

After calling this method you need to call the QUIC connection datagrams_to_send() method to retrieve data which needs to be sent over the network. If you are using the asyncio API, calling the transmit() method will do it for you.

Parameters:

• stream_id (int) – The stream’s ID.

• data (bytes) – The data to be sent.

• end_stream (bool) – If set to True, the FIN bit will be set.

Return type:

None

stop_stream(stream_id, error_code)

Request termination of the receiving part of a stream.

Note

After calling this method you need to call the QUIC connection datagrams_to_send() method to retrieve data which needs to be sent over the network. If you are using the asyncio API, calling the transmit() method will do it for you.

Parameters:

• stream_id (int) – The stream’s ID.

• error_code (int) – An error code indicating why the stream is being stopped.

Return type:

None

Configuration

class aioquic.quic.configuration.QuicConfiguration(alpn_protocols=None, congestion_control_algorithm='reno', connection_id_length=8, idle_timeout=60.0, is_client=True, max_data=1048576, max_datagram_size=1200, max_stream_data=1048576, quic_logger=None, secrets_log_file=None, server_name=None, session_ticket=None, token=b'', cadata=None, cafile=None, capath=None, certificate=None, certificate_chain=list(), cipher_suites=None, initial_rtt=0.1, max_datagram_frame_size=None, original_version=None, private_key=None, quantum_readiness_test=False, supported_versions=<factory>, verify_mode=None)

A QUIC configuration.

alpn_protocols: Optional[list[str]] = None

A list of supported ALPN protocols.

congestion_control_algorithm: str = 'reno'

The name of the congestion control algorithm to use.

Currently supported algorithms: “reno”, `”cubic”.

connection_id_length: int = 8

The length in bytes of local connection IDs.

idle_timeout: float = 60.0

The idle timeout in seconds.

The connection is terminated if nothing is received for the given duration.

is_client: bool = True

Whether this is the client side of the QUIC connection.

load_cert_chain(certfile, keyfile=None, password=None)

Load a private key and the corresponding certificate.

Return type:

None

load_verify_locations(cafile=None, capath=None, cadata=None)

Load a set of “certification authority” (CA) certificates used to validate other peers’ certificates.

Return type:

None

max_data: int = 1048576

Connection-wide flow control limit.

max_datagram_size: int = 1200

The maximum QUIC payload size in bytes to send, excluding UDP or IP overhead.

max_stream_data: int = 1048576

Per-stream flow control limit.

quic_logger: Optional[QuicLogger] = None

The QuicLogger instance to log events to.

secrets_log_file: Optional[TextIO] = None

A file-like object in which to log traffic secrets.

This is useful to analyze traffic captures with Wireshark.

server_name: Optional[str] = None

The server name to use when verifying the server’s TLS certificate, which can either be a DNS name or an IP address.

If it is a DNS name, it is also sent during the TLS handshake in the Server Name Indication (SNI) extension.

Note

This is only used by clients.

session_ticket: Optional[SessionTicket] = None

The TLS session ticket which should be used for session resumption.

token: bytes = b''

The address validation token that can be used to validate future connections.

Note

This is only used by clients.

class aioquic.quic.logger.QuicLogger

A QUIC event logger which stores traces in memory.

to_dict()

Return the traces as a dictionary which can be written as JSON.

Return type:

dict[str, Any]

Events

class aioquic.quic.events.QuicEvent

Base class for QUIC events.

class aioquic.quic.events.ConnectionTerminated(error_code, frame_type, reason_phrase)

The ConnectionTerminated event is fired when the QUIC connection is terminated.

error_code: int

The error code which was specified when closing the connection.

frame_type: Optional[int]

The frame type which caused the connection to be closed, or None.

reason_phrase: str

The human-readable reason for which the connection was closed.

class aioquic.quic.events.HandshakeCompleted(alpn_protocol, early_data_accepted, session_resumed)

The HandshakeCompleted event is fired when the TLS handshake completes.

alpn_protocol: Optional[str]

The protocol which was negotiated using ALPN, or None.

early_data_accepted: bool

Whether early (0-RTT) data was accepted by the remote peer.

session_resumed: bool

Whether a TLS session was resumed.

class aioquic.quic.events.PingAcknowledged(uid)

The PingAcknowledged event is fired when a PING frame is acknowledged.

uid: int

The unique ID of the PING.

class aioquic.quic.events.StopSendingReceived(error_code, stream_id)

The StopSendingReceived event is fired when the remote peer requests stopping data transmission on a stream.

error_code: int

The error code that was sent from the peer.

stream_id: int

The ID of the stream that the peer requested stopping data transmission.

class aioquic.quic.events.StreamDataReceived(data, end_stream, stream_id)

The StreamDataReceived event is fired whenever data is received on a stream.

data: bytes

The data which was received.

end_stream: bool

Whether the STREAM frame had the FIN bit set.

stream_id: int

The ID of the stream the data was received for.

class aioquic.quic.events.StreamReset(error_code, stream_id)

The StreamReset event is fired when the remote peer resets a stream.

error_code: int

The error code that triggered the reset.

stream_id: int

The ID of the stream that was reset.