Struct Connection 

pub struct Connection(/* private fields */);

Available on crate features quic and std only.

A QUIC connection.

If all references to a connection (including every clone of the Connection handle, streams of incoming streams, and the various stream types) have been dropped, then the connection will be automatically closed with an error_code of 0 and an empty reason. You can also close the connection explicitly by calling Connection::close().

Closing the connection immediately abandons efforts to deliver data to the peer. Upon receiving CONNECTION_CLOSE the peer may drop any stream data not yet delivered to the application. Connection::close() describes in more detail how to gracefully close a connection without losing application data.

May be cloned to obtain another handle to the same connection. Connection-scoped extensions are shared by all handles and can be accessed through ExtensionsRef::extensions, independently of the transport state lock.

Implementations

impl Connection

pub fn open_uni(&self) -> OpenUni<'_>

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

pub fn open_bi(&self) -> OpenBi<'_>

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

pub fn try_reserve_bi( &self, ) -> Result<Option<BiStreamReservation>, ConnectionError>

Reserve bidirectional stream credit without assigning a stream ID.

Returns None before the handshake completes or while credit is exhausted. Dropping an unused reservation returns its credit without emitting a reset. Ordinary stream opens cannot consume reserved credit.

pub fn stream_budget_watch(&self, dir: Dir) -> Changed<usize>

Subscribe before trying admission to observe newly available stream credit.

Values are change revisions, not capacities. A signal means credit was returned or increased, or the handshake finished; retry reservation or inspect Self::available_streams. Acquisitions do not wake subscribers.

pub fn accept_uni(&self) -> AcceptUni<'_>

Accept the next incoming uni-directional stream

pub fn accept_bi(&self) -> AcceptBi<'_>

Accept the next incoming bidirectional stream

Important Note: The Connection that calls open_bi() must write to its SendStream before the other Connection is able to accept_bi(). Calling open_bi() then waiting on the RecvStream without writing anything to SendStream will never succeed.

pub fn read_datagram(&self) -> ReadDatagram<'_>

Receive an application datagram

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.

pub fn close_reason(&self) -> Option<ConnectionError>

If the connection is closed, the reason why.

Returns None if the connection is still open.

pub fn close(&self, error_code: impl Into<VarInt>, reason: &[u8])

Close 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, and Endpoint::wait_idle() can be used 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.

pub fn close_transport(&self, error: Error)

Available on crate feature test-utils only.

Send a transport CONNECTION_CLOSE for protocol interoperability tests.

Application shutdown normally uses Self::close. This hook exercises peers which finish with transport NO_ERROR, rather than an application code.

pub async fn handshake_confirmed(&self) -> Result<(), ConnectionError>

Wait for the handshake to be confirmed.

As a server, who must be authenticated by clients, this happens when the handshake completes upon receiving a TLS Finished message from the client. In return, the server send a HANDSHAKE_DONE frame.

As a client, this happens when receiving a HANDSHAKE_DONE frame. At this point, the server has either accepted our authentication, or, if client authentication is not required, accepted our lack of authentication.

pub fn send_datagram(&self, data: Bytes) -> Result<(), SendDatagramError>

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

Previously queued datagrams which are still unsent may be discarded to make space for this datagram, in order of oldest to newest.

pub fn try_send_datagram(&self, data: Bytes) -> Result<(), SendDatagramError>

Transmit data as an unreliable, unordered application datagram without waiting or discarding queued datagrams: a full send buffer returns SendDatagramError::Blocked.

See send_datagram() for details.

pub fn send_datagram_wait(&self, data: Bytes) -> SendDatagram<'_>

Transmit data as an unreliable, unordered application datagram

Unlike send_datagram(), this method will wait for buffer space during congestion conditions, which effectively prioritizes old datagrams over new datagrams.

See send_datagram() for details.

pub fn max_datagram_size(&self) -> Option<usize>

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

pub fn datagram_receive_enabled(&self) -> bool

Whether this connection accepts QUIC DATAGRAM frames from its peer: this endpoint advertised max_datagram_frame_size (RFC 9221 §3), whatever the peer supports.

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.

pub fn side(&self) -> Side

Which side of the connection this is: the one that opened it, or the one that accepted it.

pub fn remote_address(&self) -> SocketAddr

The peer’s UDP address

If ServerConfig::migration is true, clients may change addresses at will, e.g. when switching to a cellular internet connection.

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 the platform does not expose this information. See rama_udp::DatagramCapabilities::receive_local_ip for platform support.

pub fn rtt(&self) -> Duration

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

pub fn min_rtt(&self) -> Duration

Minimum RTT seen on this path, ignoring ack delay

pub fn stats(&self) -> ConnectionStats

Returns connection statistics

pub fn version(&self) -> Version

The QUIC version this connection runs in: the client’s first flight version, or the compatible version the server moved it to (RFC 9368).

pub fn original_version(&self) -> Version

The QUIC version of the client’s first flight, which differs from Self::version only after compatible version negotiation moved the connection (RFC 9368 §2.3).

pub fn handshake_data(&self) -> Option<NegotiatedTlsParameters>

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.

pub fn peer_identity(&self) -> Option<Vec<CertificateDer<'static>>>

The certificate chain the peer presented, leaf first, if it presented one.

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.

pub fn force_key_update(&self) -> bool

Update traffic keys now, without waiting for the usage limit that would force one.

Answers whether an update was started. Nothing changes and the answer is false when the connection is not established, when the handshake is not confirmed yet (RFC 9001 §6.1 forbids initiating an update before then, which for a client means after HANDSHAKE_DONE), or when an update is already in flight (§6 allows one at a time). ConnectionStats::key_updates counts the updates this connection has made, whichever side asked for them.

pub fn export_keying_material( &self, output: &mut [u8], label: &[u8], context: &[u8], ) -> Result<(), ExportKeyingMaterialError>

Derive keying material from this connection’s TLS session secrets.

Two peers calling this with the same label, the same context and output buffers of equal length get the same bytes. The bytes are cryptographically strong and pseudorandom, suitable as keying material. A different label or a different context gives different bytes.

TLS 1.3 defines this exporter in RFC 8446 §7.5; RFC 5705 defined the earlier one it replaces.

pub fn driver_stats(&self) -> DriverStats

Socket and receive-queue statistics counted by the driver for this connection.

What the protocol engine counts is Connection::stats.

pub fn set_max_concurrent_uni_streams(&self, count: impl Into<VarInt>)

Modify the number of remotely initiated unidirectional 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

How many remotely initiated streams of dir may be open at once, as this side has allowed them.

Lowering the target with set_max_concurrent_streams does not take effect at once: the number falls by one as each open stream of that direction closes.

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

Unreserved streams that can be opened immediately under peer credit.

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

Exclusive cumulative stream-index limit advertised to the peer for dir.

This is the initial transport limit or the latest transmitted MAX_STREAMS value. A remote stream is within the advertised limit when its index (stream_id / 4) is smaller than this value. Unlike the concurrency target, it includes streams that have already closed.

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

How many remotely initiated streams of dir are open, including those this side has not accepted yet. They count against max_concurrent_streams.

pub fn initial_local_id(&self) -> ConnectionId

The connection ID this endpoint’s generator made for the handshake, from the generator EndpointConfig::set_cid_generator installed.

A connection issues further identifiers as it runs and retires this one in time, so several may be usable at once and this is not “the one in use”. It stays the same for the life of the connection, which is what makes it worth reporting.

pub fn trace_id(&self) -> ConnectionId

The connection ID that names this connection in a qlog trace: the destination the client chose for its first Initial, which both ends know and neither changes.

pub fn qlog_control(&self) -> Option<ConnectionQlogControl>

Control this connection’s configured qlog sink. The handle can outlive the connection and can be inserted into Rama extensions for an application-level trigger. Returns None when no qlog sink was configured before creating the connection.

pub fn path_changed(&self)

Tell the connection its network path changed, so the congestion controller, the round-trip estimate and MTU discovery start again from the transport configuration.

Use it when something outside QUIC says the path is a different one, such as a change of interface. The connection detects a peer’s own move on its own.

pub fn set_send_window(&self, send_window: u64)

Set the maximum data this connection keeps in flight, as TransportConfig::set_send_window does before it is established.

pub fn set_receive_window(&self, receive_window: impl Into<VarInt>)

Set the flow control window this connection advertises, as TransportConfig::set_receive_window does before it is established.

pub fn set_max_concurrent_bi_streams(&self, count: impl Into<VarInt>)

Modify the number of remotely initiated bidirectional 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.

Trait Implementations

impl Clone for Connection

fn clone(&self) -> Connection

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Connection

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

Formats the value using the given formatter.

impl ExtensionsRef for Connection

fn extensions(&self) -> &Extensions

Get reference to the underlying Extensions store

impl<S, Response> Service<Connection> for HttpService<Config, S>

where S: Service<Request, Output = Response, Error = !> + Clone, Response: IntoResponse + Send + 'static,

type Output = ()

The type of the output returned by the service.

type Error = Box<dyn Error + Sync + Send>

The type of error returned by the service.

async fn serve( &self, connection: Connection, ) -> Result<(), Box<dyn Error + Sync + Send>>

Serve an output or an error for the given input

fn boxed(self) -> BoxService<Input, Self::Output, Self::Error>

Box this service to allow for dynamic dispatch.