Struct Session

pub struct Session { /* private fields */ }

A Session, able to accept/create streams and send/recv datagrams.

Can be cloned to create multiple handles to the same underlying connection.

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

Closing the session immediately immediately sends a CONNECTION_CLOSE frame and then 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. Session::close() describes in more detail how to gracefully close a session without losing application data.

Implementations

impl Session

pub fn peer_key(&self) -> Option<&SubjectPublicKeyInfoDer<'_>>

The public key of the remote peer.

This may be unavailable if require_client_auth returned false in the Endpoint’s AllowConnection instance.

pub unsafe fn as_quic(&self) -> &Connection

Get access to the underlying QUIC Connection.

Safety: you must not use any methods that alter the session state, nor any that send packets. This may corrupt the WebTransport state layered on top.

Accessing statistical and factual information (such as peer_identity(), remote_address(), stats(), close_reason(), etc) is safe.

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

Wait until the peer creates a new unidirectional stream.

Will error if the connection is closed.

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

Wait until the peer creates a new bidirectional stream.

pub async fn open_bi(&self) -> Result<(SendStream, RecvStream), Error>

Open a new bidirectional stream.

May wait when there are too many concurrent streams.

pub async fn open_uni(&self) -> Result<SendStream, Error>

Open a new unidirectional stream.

May wait when there are too many concurrent streams.

pub fn send_datagram(&self, payload: Bytes) -> Result<(), Error>

Send an unreliable datagram over the network.

QUIC datagrams may be dropped for any reason, including (non-exhaustive):

• Network congestion
• Random packet loss
• Payload is larger than max_datagram_size()
• Peer is not receiving datagrams
• Peer has too many outstanding datagrams

pub async fn max_datagram_size(&self) -> usize

The maximum size of a datagram that can be sent.

pub async fn recv_datagram(&self) -> Result<Bytes, Error>

Receive a datagram over the network.

pub fn close(&self, code: u32, reason: &str)

Close the session immediately.

Pending operations will fail immediately with Connection(ConnectionError::LocallyClosed). No more data is sent to the peer beyond a CONNECTION_CLOSE frame, and the peer may drop buffered data upon receiving the CONNECTION_CLOSE frame.

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 session

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 session, 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 session after 30 seconds.

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, 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 async fn closed(&self) -> Result<Option<ApplicationClose>, Error>

Wait until the connection is closed.

Returns Ok(None) if the connection was closed locally, Ok(Some(_)) if the connection was closed by a peer (e.g. with close()), and Err(_) for other unexpected reasons.

Trait Implementations

impl Clone for Session

fn clone(&self) -> Session

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Session

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

Formats the value using the given formatter.

impl PartialEq for Session

fn eq(&self, other: &Session) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Session

impl StructuralPartialEq for Session