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)¶

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.

After calling this method call datagrams_to_send() to retrieve data which needs to be sent.

Return type: None

close(error_code=QuicErrorCode.NO_ERROR, frame_type=None, 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, now)¶

Initiate the TLS handshake.

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

After calling this method call datagrams_to_send() to retrieve data which needs to be sent.

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.

After calling this method call datagrams_to_send() to retrieve data which needs to be sent.

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.

After calling this method call datagrams_to_send() to retrieve data which needs to be sent.

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.

Return type: None

reset_stream(stream_id, error_code)¶

Abruptly terminate the sending part of a stream.

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.

Parameters: data (bytes) – The data to be sent.
Return type: None

send_ping(uid)¶

Send a PING frame to the peer.

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.

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.

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, connection_id_length=8, idle_timeout=60.0, is_client=True, max_data=1048576, max_stream_data=1048576, quic_logger=None, secrets_log_file=None, server_name=None, session_ticket=None, cadata=None, cafile=None, capath=None, certificate=None, certificate_chain=<factory>, cipher_suites=None, initial_rtt=0.1, max_datagram_frame_size=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.

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_stream_data: int = 1048576¶: Per-stream flow control limit.

quic_logger: Optional[QuicLogger] = None¶: The QuicLogger instance to log events to.

secrets_log_file: 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 send during the TLS handshake the Server Name Indication.

Note

This is only used by clients.

session_ticket: Optional[SessionTicket] = None¶: The TLS session ticket which should be used for session resumption.

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

QUIC API¶

Connection¶

Configuration¶

Events¶

Navigation

Related Topics