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_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.

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.

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=<factory>, 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.