pub struct ConnectionRef { /* private fields */ }Expand description
A reference to a connection that is owned by a connection pool.
Methods from Deref<Target = Connection>§
Sourcepub fn open_uni(&self) -> OpenUni<'_>
pub fn open_uni(&self) -> OpenUni<'_>
Initiates a new outgoing unidirectional stream.
Streams are cheap and instantaneous to open unless blocked by flow control. As a consequence, the peer won’t be notified that a stream has been opened until the stream is actually used.
Sourcepub fn open_bi(&self) -> OpenBi<'_>
pub fn open_bi(&self) -> OpenBi<'_>
Initiates a new outgoing bidirectional stream.
Streams are cheap and instantaneous to open unless blocked by flow control. As a
consequence, the peer won’t be notified that a stream has been opened until the
stream is actually used. Calling open_bi then waiting on the RecvStream
without writing anything to SendStream will never succeed.
Sourcepub fn accept_uni(&self) -> AcceptUni<'_>
pub fn accept_uni(&self) -> AcceptUni<'_>
Accepts the next incoming uni-directional stream.
Sourcepub fn accept_bi(&self) -> AcceptBi<'_>
pub fn accept_bi(&self) -> AcceptBi<'_>
Accept the next incoming bidirectional stream.
Important Note: The peer that calls open_bi must write to its SendStream
before the peer Connection is able to accept the stream using
accept_bi(). Calling open_bi then waiting on the RecvStream without
writing anything to the connected SendStream will never succeed.
Sourcepub fn read_datagram(&self) -> ReadDatagram<'_>
pub fn read_datagram(&self) -> ReadDatagram<'_>
Receives an application datagram.
Sourcepub async fn closed(&self) -> ConnectionError
pub async fn closed(&self) -> ConnectionError
Wait for the connection to be closed for any reason.
Despite the return type’s name, closed connections are often not an error condition
at the application layer. Cases that might be routine include
ConnectionError::LocallyClosed and ConnectionError::ApplicationClosed.
Sourcepub fn close_reason(&self) -> Option<ConnectionError>
pub fn close_reason(&self) -> Option<ConnectionError>
If the connection is closed, the reason why.
Returns None if the connection is still open.
Sourcepub fn close(&self, error_code: VarInt, reason: &[u8])
pub fn close(&self, error_code: VarInt, reason: &[u8])
Closes the connection immediately.
Pending operations will fail immediately with ConnectionError::LocallyClosed. No
more data is sent to the peer and the peer may drop buffered data upon receiving the
CONNECTION_CLOSE frame.
error_code and reason are not interpreted, and are provided directly to the
peer.
reason will be truncated to fit in a single packet with overhead; to improve odds
that it is preserved in full, it should be kept under 1KiB.
§Gracefully closing a connection
Only the peer last receiving application data can be certain that all data is
delivered. The only reliable action it can then take is to close the connection,
potentially with a custom error code. The delivery of the final CONNECTION_CLOSE
frame is very likely if both endpoints stay online long enough, calling
Endpoint::close will wait to provide sufficient time. Otherwise, the remote peer
will time out the connection, provided that the idle timeout is not disabled.
The sending side can not guarantee all stream data is delivered to the remote
application. It only knows the data is delivered to the QUIC stack of the remote
endpoint. Once the local side sends a CONNECTION_CLOSE frame in response to calling
close the remote endpoint may drop any data it received but is as yet
undelivered to the application, including data that was acknowledged as received to
the local endpoint.
Sourcepub fn send_datagram(&self, data: Bytes) -> Result<(), SendDatagramError>
pub fn send_datagram(&self, data: Bytes) -> Result<(), SendDatagramError>
Transmits data as an unreliable, unordered application datagram.
Application datagrams are a low-level primitive. They may be lost or delivered out
of order, and data must both fit inside a single QUIC packet and be smaller than
the maximum dictated by the peer.
Sourcepub fn max_datagram_size(&self) -> Option<usize>
pub fn max_datagram_size(&self) -> Option<usize>
Computes the maximum size of datagrams that may be passed to send_datagram.
Returns None if datagrams are unsupported by the peer or disabled locally.
This may change over the lifetime of a connection according to variation in the path MTU estimate. The peer can also enforce an arbitrarily small fixed limit, but if the peer’s limit is large this is guaranteed to be a little over a kilobyte at minimum.
Not necessarily the maximum size of received datagrams.
Sourcepub fn datagram_send_buffer_space(&self) -> usize
pub fn datagram_send_buffer_space(&self) -> usize
Bytes available in the outgoing datagram buffer.
When greater than zero, calling send_datagram with a
datagram of at most this size is guaranteed not to cause older datagrams to be
dropped.
Sourcepub fn rtt(&self) -> Duration
pub fn rtt(&self) -> Duration
Current best estimate of this connection’s latency (round-trip-time).
Sourcepub fn stats(&self) -> ConnectionStats
pub fn stats(&self) -> ConnectionStats
Returns connection statistics.
Sourcepub fn congestion_state(&self) -> Box<dyn Controller>
pub fn congestion_state(&self) -> Box<dyn Controller>
Current state of the congestion control algorithm, for debugging purposes.
Sourcepub fn handshake_data(&self) -> Option<Box<dyn Any>>
pub fn handshake_data(&self) -> Option<Box<dyn Any>>
Parameters negotiated during the handshake.
Guaranteed to return Some on fully established connections or after
Connecting::handshake_data() succeeds. See that method’s documentations for
details on the returned value.
Sourcepub fn alpn(&self) -> Option<Vec<u8>>
pub fn alpn(&self) -> Option<Vec<u8>>
Extracts the ALPN protocol from the peer’s handshake data.
Sourcepub fn peer_identity(&self) -> Option<Box<dyn Any>>
pub fn peer_identity(&self) -> Option<Box<dyn Any>>
Cryptographic identity of the peer.
The dynamic type returned is determined by the configured Session. For the
default rustls session, the return value can be downcast to a
Vec<rustls::pki_types::CertificateDer>
Sourcepub fn remote_node_id(&self) -> Result<PublicKey, RemoteNodeIdError>
pub fn remote_node_id(&self) -> Result<PublicKey, RemoteNodeIdError>
Sourcepub fn stable_id(&self) -> usize
pub fn stable_id(&self) -> usize
A stable identifier for this connection.
Peer addresses and connection IDs can change, but this value will remain fixed for the lifetime of the connection.
Sourcepub fn export_keying_material(
&self,
output: &mut [u8],
label: &[u8],
context: &[u8],
) -> Result<(), ExportKeyingMaterialError>
pub fn export_keying_material( &self, output: &mut [u8], label: &[u8], context: &[u8], ) -> Result<(), ExportKeyingMaterialError>
Derives keying material from this connection’s TLS session secrets.
When both peers call this method with the same label and context
arguments and output buffers of equal length, they will get the
same sequence of bytes in output. These bytes are cryptographically
strong and pseudorandom, and are suitable for use as keying material.
See RFC5705 for more information.
Sourcepub fn set_max_concurrent_uni_streams(&self, count: VarInt)
pub fn set_max_concurrent_uni_streams(&self, count: VarInt)
Modifies the number of unidirectional streams that may be concurrently opened.
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.
Sourcepub fn set_receive_window(&self, receive_window: VarInt)
pub fn set_receive_window(&self, receive_window: VarInt)
Sourcepub fn set_max_concurrent_bi_streams(&self, count: VarInt)
pub fn set_max_concurrent_bi_streams(&self, count: VarInt)
Modifies the number of bidirectional streams that may be concurrently opened.
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.