Struct wtransport::connection::Connection

pub struct Connection { /* private fields */ }

A WebTransport session connection.

For more details, see the module documentation.

Implementations

impl Connection

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

Asynchronously accepts a unidirectional stream.

This method is used to accept incoming unidirectional streams that have been initiated by the remote peer. It waits for the next unidirectional stream to be available, then wraps it in a RecvStream that can be used to read data from the stream.

Cancel safety

This method is cancel safe.

pub async fn accept_bi( &self ) -> Result<(SendStream, RecvStream), ConnectionError>

Asynchronously accepts a bidirectional stream.

This method is used to accept incoming bidirectional streams that have been initiated by the remote peer. It waits for the next bidirectional stream to be available, then wraps it in a tuple containing a SendStream for sending data and a RecvStream for receiving data on the stream.

Cancel safety

This method is cancel safe.

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

Asynchronously opens a new unidirectional stream.

This method is used to initiate the opening of a new unidirectional stream.

Asynchronous Behavior

This method is asynchronous and involves two await points:

1. The first await occurs during the initial phase of opening the stream, which may involve awaiting the flow controller. This wait is necessary to ensure proper resource allocation and flow control. It is safe to cancel this await point if needed.

2. The second await is internal to the returned OpeningUniStream object when it is used to initialize the WebTransport stream. Cancelling this latter future before it completes may result in the stream being closed during initialization.

Example

let send_stream = connection.open_uni().await?.await?;

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

Asynchronously opens a new bidirectional stream.

This method is used to initiate the opening of a new bidirectional stream.

Asynchronous Behavior

This method is asynchronous and involves two await points:

1. The first await occurs during the initial phase of opening the stream, which may involve awaiting the flow controller. This wait is necessary to ensure proper resource allocation and flow control. It is safe to cancel this await point if needed.

2. The second await is internal to the returned OpeningBiStream object when it is used to initialize the WebTransport stream. Cancelling this latter future before it completes may result in the stream being closed during initialization.

Example

let (send_stream, recv_stream) = connection.open_bi().await?.await?;

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

Asynchronously receives an application datagram from the remote peer.

This method is used to receive an application datagram sent by the remote peer over the connection. It waits for a datagram to become available and returns the received Datagram.

Example

let datagram = connection.receive_datagram().await?;

pub fn send_datagram<D>(&self, payload: D) -> Result<(), SendDatagramError>

where D: AsRef<[u8]>,

Sends an application datagram to the remote peer.

This method is used to send an application datagram to the remote peer over the connection. The datagram payload is provided as a reference to a slice of bytes.

Example

connection.send_datagram(b"Hello, wtransport!")?;

pub fn close(&self, error_code: VarInt, reason: &[u8])

Closes the connection immediately.

pub async fn closed(&self) -> ConnectionError

Waits for the connection to be closed for any reason.

pub fn session_id(&self) -> SessionId

Returns the WebTransport session identifier.

pub fn remote_address(&self) -> SocketAddr

Returns the peer’s UDP address.

Note: as QUIC supports migration, remote address may change during connection. Furthermore, when IPv6 support is enabled, IPv4 addresses may be mapped to IPv6.

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

pub fn rtt(&self) -> Duration

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

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.

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.

pub fn peer_identity(&self) -> Option<CertificateChain>

Returns the peer’s identity as a certificate chain if available.

This function returns an Option containing a CertificateChain. If the peer’s identity is available, it is converted into a CertificateChain and returned. If the peer’s identity is not available, None is returned.

pub fn handshake_data(&self) -> HandshakeData

Retrieves handshake data associated with the connection.

Trait Implementations

impl Debug for Connection

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

Formats the value using the given formatter.