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()
andsend_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 thetransmit()
method will do it for you.- Return type:
- 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 thetransmit()
method will do it for you.
- 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 thetransmit()
method will do it for you.
- 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.
- get_next_available_stream_id(is_unidirectional=False)¶
Return the stream ID for the next stream created by this endpoint.
- Return type:
- get_timer()¶
Return the time at which the timer should fire or None if no timer is needed.
- 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 thetransmit()
method will do it for you.
- next_event()¶
Retrieve the next event from the event buffer.
Returns None if there are no buffered events.
- 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 thetransmit()
method will do it for you.
- 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 thetransmit()
method will do it for you.- Return type:
- reset_stream(stream_id, error_code)¶
Abruptly terminate the sending 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 thetransmit()
method will do it for you.
- 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 thetransmit()
method will do it for you.
- 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 thetransmit()
method will do it for you.
- 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 thetransmit()
method will do it for you.
- 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 thetransmit()
method will do it for you.
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.
-
congestion_control_algorithm:
str
= 'reno'¶ The name of the congestion control algorithm to use.
Currently supported algorithms: “reno”, `”cubic”.
-
idle_timeout:
float
= 60.0¶ The idle timeout in seconds.
The connection is terminated if nothing is received for the given duration.
- load_cert_chain(certfile, keyfile=None, password=None)¶
Load a private key and the corresponding certificate.
- Return type:
- 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:
-
max_datagram_size:
int
= 1200¶ The maximum QUIC payload size in bytes to send, excluding UDP or IP overhead.
-
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 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.
-
congestion_control_algorithm:
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.
- class aioquic.quic.events.HandshakeCompleted(alpn_protocol, early_data_accepted, session_resumed)¶
The HandshakeCompleted event is fired when the TLS handshake completes.
- class aioquic.quic.events.PingAcknowledged(uid)¶
The PingAcknowledged event is fired when a PING frame is acknowledged.
- 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.
- class aioquic.quic.events.StreamDataReceived(data, end_stream, stream_id)¶
The StreamDataReceived event is fired whenever data is received on a stream.