Struct Endpoint 

pub struct Endpoint { /* private fields */ }

Available on crate features quic and std only.

A QUIC endpoint.

An endpoint corresponds to a single UDP socket, may host many connections, and may act as both client and server for different connections.

May be cloned to obtain another handle to the same endpoint.

Implementations

impl Endpoint

pub fn build(exec: Executor) -> EndpointBuilder

Configure an endpoint whose drivers run through exec on the current Tokio runtime.

An executor carrying a graceful guard ties the endpoint to the application’s shutdown. All convenience constructors accept the same executor explicitly.

pub fn new_client_with_std_socket( exec: Executor, socket: UdpSocket, ) -> Result<Endpoint, DatagramError>

Create a client endpoint on a bound standard UDP socket.

This does not configure packet metadata. Use Self::new_client_with_packet_socket for a prepared socket, or Self::build for custom endpoint settings.

pub fn new_client_with_packet_socket( exec: Executor, socket: UdpPacketSocket, ) -> Result<Endpoint, DatagramError>

Create a client endpoint on a prepared packet socket, preserving its configuration.

Use Self::build for custom endpoint settings.

pub async fn bind_client( exec: Executor, address: impl Into<SocketAddress>, ) -> Result<Endpoint, DatagramError>

Bind a client endpoint, requesting best-effort dual-stack operation for IPv6.

Use Self::build to customise the endpoint or UDP socket configuration.

pub fn new_server_with_std_socket( exec: Executor, config: ServerConfig, socket: UdpSocket, ) -> Result<Endpoint, DatagramError>

Create a server endpoint on a bound standard UDP socket.

This does not configure packet metadata or bind preferred-address sockets. Use Self::new_server_with_packet_socket for a prepared socket, or Self::build for custom endpoint settings.

pub fn new_server_with_packet_socket( exec: Executor, config: ServerConfig, socket: UdpPacketSocket, ) -> Result<Endpoint, DatagramError>

Create a server endpoint on a prepared packet socket, preserving its configuration.

This does not bind preferred-address sockets. Use Self::build for custom settings.

pub async fn bind_server( exec: Executor, config: ServerConfig, address: impl Into<SocketAddress>, ) -> Result<Endpoint, DatagramError>

Bind a server endpoint and any configured preferred-address sockets.

Use Self::build to customise the endpoint or UDP socket configuration.

pub fn advertise_socket( &self, socket: UdpPacketSocket, ) -> Result<(), DatagramError>

Take ownership of a packet socket the caller prepared, bound to an address this endpoint advertises as its preferred one (RFC 9000 §9.6). Datagrams for a connection that moved there leave from this socket.

pub fn stats(&self) -> EndpointStats

Returns relevant stats from this Endpoint

pub fn accept(&self) -> Accept<'_>

Get the next incoming connection attempt from a client

Yields Incomings, or None if the endpoint is closed. Incoming can be awaited to obtain the final Connection, or used to e.g. filter connection attempts or force address validation, or converted into an intermediate Connecting future which can be used to e.g. send 0.5-RTT data.

pub fn set_default_client_config(&mut self, config: ClientConfig)

Set the client configuration used by connect

pub fn connect( &self, addr: SocketAddr, server_name: &str, ) -> Result<Connecting, ConnectError>

Connect to a remote endpoint

server_name must be covered by the certificate presented by the server. This prevents a connection from being intercepted by an attacker with a valid certificate for some other server.

May fail immediately due to configuration errors, or in the future if the connection could not be established.

pub fn connect_with( &self, config: ClientConfig, addr: SocketAddr, server_name: &str, ) -> Result<Connecting, ConnectError>

Connect to a remote endpoint using a custom configuration.

See connect() for details.

pub async fn rebind( &self, address: impl Into<SocketAddress>, socket: UdpSocketConfig, ) -> Result<(), DatagramError>

Bind a new socket through Rama’s shared UDP construction and switch to it.

New connections and attempts use the new socket at once. Each existing connection moves to it only when QUIC allows the address change (RFC 9000 §9): a socket bound to the same address is adopted right away; a client whose handshake is confirmed, whose peer allows active migration and that holds an unused destination connection ID migrates after finishing any partially sent transmit; a client still handshaking or without an unused connection ID migrates once it has both; server connections and clients whose peer disabled active migration keep sending from their current socket. A replaced socket stays open while connections, queued attempts, queued responses or a recent Retry depend on it, up to a bounded number of retained sockets.

On error, nothing changes and the previous socket stays active.

pub fn rebind_packet_socket(&self, socket: UdpPacketSocket) -> Result<(), Error>

Switch to a packet socket the caller prepared. Endpoint::rebind describes what the switch means for existing connections.

pub fn rebind_std_socket(&self, socket: UdpSocket) -> Result<(), Error>

Switch to a bound standard socket. Endpoint::rebind describes what the switch means for existing connections.

pub fn set_server_config(&self, server_config: Option<ServerConfig>)

Replace the server configuration, affecting new incoming connections only

Useful for e.g. refreshing TLS certificates without disrupting existing connections.

pub fn local_addr(&self) -> Result<SocketAddr, Error>

Get the local SocketAddr the underlying socket is bound to

pub fn local_addrs(&self) -> Vec<SocketAddr>

Local addresses of every retained socket, the active one first.

pub fn advertised_addrs(&self) -> Vec<SocketAddr>

Local addresses this endpoint advertises as its preferred ones (RFC 9000 §9.6), in the order they were bound. Empty unless advertise_socket was used.

pub fn open_connections(&self) -> usize

Get the number of connections that are currently open

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

Close all of this endpoint’s connections immediately and cease accepting new connections.

See Connection::close() for details.

pub async fn shutdown(&self) -> ShutdownOutcome

Stop the endpoint and join all drivers, releasing sockets even with retained handles.

pub async fn wait_idle(&self)

Wait for all connections on the endpoint to be cleanly shut down

Waiting for this condition before exiting ensures that a good-faith effort is made to notify peers of recent connection closes, whereas exiting immediately could force them to wait out the idle timeout period.

Does not proactively close existing connections or cause incoming connections to be rejected. Consider calling close() if that is desired.

Trait Implementations

impl Clone for Endpoint

fn clone(&self) -> Endpoint

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Endpoint

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

Formats the value using the given formatter.