Struct Connection

pub struct Connection { /* private fields */ }

Protocol state and logic for a single QUIC connection

Objects of this type receive ConnectionEvents and emit EndpointEvents and application Events to make progress. To handle timeouts, a Connection returns timer updates and expects timeouts through various methods. A number of simple getter methods are exposed to allow callers to inspect some of the connection state.

Connection has roughly 4 types of methods:

• A. Simple getters, taking &self
• B. Handlers for incoming events from the network or system, named handle_*.
• C. State machine mutators, for incoming commands from the application. For convenience we refer to this as “performing I/O” below, however as per the design of this library none of the functions actually perform system-level I/O. For example, read and write, but also things like reset.
• D. Polling functions for outgoing events or actions for the caller to take, named poll_*.

The simplest way to use this API correctly is to call (B) and (C) whenever appropriate, then after each of those calls, as soon as feasible call all polling methods (D) and deal with their outputs appropriately, e.g. by passing it to the application or by making a system-level I/O call. You should call the polling functions in this order:

1. poll_transmit
2. poll_timeout
3. poll_endpoint_events
4. poll

Currently the only actual dependency is from (2) to (1), however additional dependencies may be added in future, so the above order is recommended.

(A) may be called whenever desired.

Care should be made to ensure that the input events represent monotonically increasing time. Specifically, calling handle_timeout with events of the same Instant may be interleaved in any order with a call to handle_event at that same instant; however events or timeouts with different instants must not be interleaved.

Implementations

impl Connection

pub fn poll_timeout(&mut self) -> Option<Instant>

Returns the next time at which handle_timeout should be called

The value returned may change after:

• the application performed some I/O on the connection
• a call was made to handle_event
• a call to poll_transmit returned Some
• a call was made to handle_timeout

pub fn poll(&mut self) -> Option<Event>

Returns application-facing events

Connections should be polled for events after:

• a call was made to handle_event
• a call was made to handle_timeout

pub fn poll_endpoint_events(&mut self) -> Option<EndpointEvent>

Return endpoint-facing events

pub fn streams(&mut self) -> Streams<'_>

Provide control over streams

pub fn recv_stream(&mut self, id: StreamId) -> RecvStream<'_>

Provide control over streams

pub fn send_stream(&mut self, id: StreamId) -> SendStream<'_>

Provide control over streams

pub fn poll_transmit( &mut self, now: Instant, max_datagrams: usize, buf: &mut Vec<u8>, ) -> Option<Transmit>

Returns packets to transmit

Connections should be polled for transmit after:

• the application performed some I/O on the connection
• a call was made to handle_event
• a call was made to handle_timeout

max_datagrams specifies how many datagrams can be returned inside a single Transmit using GSO. This must be at least 1.

pub fn handle_event(&mut self, event: ConnectionEvent)

Process ConnectionEvents generated by the associated Endpoint

Will execute protocol logic upon receipt of a connection event, in turn preparing signals (including application Events, EndpointEvents and outgoing datagrams) that should be extracted through the relevant methods.

pub fn handle_timeout(&mut self, now: Instant)

Process timer expirations

Executes protocol logic, potentially preparing signals (including application Events, EndpointEvents and outgoing datagrams) that should be extracted through the relevant methods.

It is most efficient to call this immediately after the system clock reaches the latest Instant that was output by poll_timeout; however spurious extra calls will simply no-op and therefore are safe.

pub fn close(&mut self, now: Instant, error_code: VarInt, reason: Bytes)

Close a connection immediately

This does not ensure delivery of outstanding data. It is the application’s responsibility to call this only when all important communications have been completed, e.g. by calling SendStream::finish on outstanding streams and waiting for the corresponding StreamEvent::Finished event.

If Streams::send_streams returns 0, all outstanding stream data has been delivered. There may still be data from the peer that has not been received.

pub fn datagrams(&mut self) -> Datagrams<'_>

Control datagrams

pub fn stats(&self) -> ConnectionStats

Returns connection statistics

pub fn ping(&mut self)

Ping the remote endpoint

Causes an ACK-eliciting packet to be transmitted.

pub fn crypto_session(&self) -> &dyn Session

Get a session reference

pub fn is_handshaking(&self) -> bool

Whether the connection is in the process of being established

If this returns false, the connection may be either established or closed, signaled by the emission of a Connected or ConnectionLost message respectively.

pub fn is_closed(&self) -> bool

Whether the connection is closed

Closed connections cannot transport any further data. A connection becomes closed when either peer application intentionally closes it, or when either transport layer detects an error such as a time-out or certificate validation failure.

A ConnectionLost event is emitted with details when the connection becomes closed.

pub fn is_drained(&self) -> bool

Whether there is no longer any need to keep the connection around

Closed connections become drained after a brief timeout to absorb any remaining in-flight packets from the peer. All drained connections have been closed.

pub fn accepted_0rtt(&self) -> bool

For clients, if the peer accepted the 0-RTT data packets

The value is meaningless until after the handshake completes.

pub fn has_0rtt(&self) -> bool

Whether 0-RTT is/was possible during the handshake

pub fn has_pending_retransmits(&self) -> bool

Whether there are any pending retransmits

pub fn side(&self) -> Side

Look up whether we’re the client or server of this Connection

pub fn remote_address(&self) -> SocketAddr

The latest socket address for this connection’s peer

pub fn local_ip(&self) -> Option<IpAddr>

The local IP address which was used when the peer established the connection

This can be different from the address the endpoint is bound to, in case the endpoint is bound to a wildcard address like 0.0.0.0 or ::.

This will return None for clients, or when no local_ip was passed to Endpoint::handle() for the datagrams establishing this connection.

pub fn rtt(&self) -> Duration

Current best estimate of this connection’s latency (round-trip-time)

pub fn congestion_state(&self) -> &dyn Controller

Current state of this connection’s congestion controller, for debugging purposes

pub fn network_path_changed(&mut self)

Resets path-specific settings.

This will force-reset several subsystems related to a specific network path. Currently this is the congestion controller, round-trip estimator, and the MTU discovery.

This is useful when it is know the underlying network path has changed and the old state of these subsystems is no longer valid.

pub fn set_max_concurrent_streams(&mut self, dir: Dir, count: VarInt)

Modify the number of remotely initiated streams that may be concurrently open

No streams may be opened by the peer unless fewer than count are already open. Large counts increase both minimum and worst-case memory consumption.

pub fn max_concurrent_streams(&self, dir: Dir) -> u64

Current number of remotely initiated streams that may be concurrently open

If the target for this limit is reduced using set_max_concurrent_streams, it will not change immediately, even if fewer streams are open. Instead, it will decrement by one for each time a remotely initiated stream of matching directionality is closed.

pub fn set_receive_window(&mut self, receive_window: VarInt)

See TransportConfig::receive_window()

pub fn local_address_changed(&mut self)

Handle a change in the local address, i.e. an active migration

pub fn current_mtu(&self) -> u16

Storage size required for the largest packet known to be supported by the current path

Buffers passed to Connection::poll_transmit should be at least this large.

Trait Implementations

impl Debug for Connection

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.