Struct QuicListeners

pub struct QuicListeners { /* private fields */ }

A QUIC listener that can serve multiple virtual servers, accepting incoming connections.

Creating Listeners

Use QuicListenersBuilder to configure the listener, then call QuicListenersBuilder::listen to start accepting connections.

Note: Only one QuicListeners instance can run at a time globally. To stop the listeners, call QuicListeners::shutdown or drop all references to the Arc<QuicListeners>.

Managing Servers

Add multiple virtual servers by calling QuicListeners::add_server multiple times. Each server is identified by its server name (SNI) and handles connections independently.

• Servers can share the same network interfaces
• Servers can be added without initially binding to any interface

Connection Handling

Call QuicListeners::accept to receive incoming connections. The listener automatically:

• Routes connections to the appropriate server based on SNI (Server Name Indication)
• Rejects connections if the target server isn’t listening on the receiving interface
• Returns connections that may still be completing their QUIC handshake

Implementations

impl QuicListeners

pub fn builder() -> Result<QuicListenersBuilder<ConfigBuilder<ServerConfig, WantsVerifier>>, BuildServerError>

Start to build a QuicListeners.

pub fn builder_with_crypto_provieder( provider: Arc<CryptoProvider>, ) -> Result<QuicListenersBuilder<ConfigBuilder<ServerConfig, WantsVerifier>>, BuildServerError>

Start to build a QuicServer with the given tls crypto provider.

pub fn builder_with_tls<T>( tls_config: T, ) -> Result<QuicListenersBuilder<T>, BuildServerError>

Start to build a QuicListeners with the given TLS configuration.

This is useful when you want to customize the TLS configuration, or integrate qm-quic with other crates.

pub fn add_server( &self, server_name: impl Into<String>, cert_chain: impl ToCertificate, private_key: impl ToPrivateKey, bind_uris: impl IntoIterator<Item = impl Into<BindUri>>, ocsp: impl Into<Option<Vec<u8>>>, ) -> Result<(), ServerError>

Add a virtual server with its certificate chain and private key.

Creates a new virtual host identified by its server name (SNI). The server will use the certificate chain and private key that matches the SNI in the client’s ClientHello message. If no matching server is found, the connection will be rejected.

A server can be added without binding to any interface initially, but will not accept connections until interfaces are added via bind_interfaces. This allows flexible server configuration and hot-swapping of network bindings.

Related Methods

• bind_interfaces - Add more interfaces to this server
• unbind_interface - Remove specific interfaces
• remove_server - Remove the entire server

pub fn remove_server(&self, server_name: &str) -> bool

Remove a virtual server and all its associated interfaces.

Completely removes a server from the listeners, including all network interfaces it was bound to (if the interface is not used by other servers). This is the inverse operation of add_server and provides a clean way to decommission a virtual host.

Returns true if the server existed and was removed, false if no server with the specified name was found. You must remove an existing server before adding a new one with the same name.

Related Methods

• add_server - Create a server (counterpart operation)
• unbind_interface - Remove specific interfaces only

pub fn bind_interfaces( &self, server_name: impl Into<String>, bind_uris: impl IntoIterator<Item = impl Into<BindUri>>, ) -> Result<(), ServerError>

Add additional network interfaces to an existing virtual server.

Extends an existing server to listen on additional network interfaces, enabling horizontal scaling and multi-homed server configurations. Interfaces that are already bound to the server will be silently ignored, allowing for idempotent operations.

The server must have been created with add_server first. Added interfaces can later be removed selectively with unbind_interface, supporting hot-swapping and zero-downtime updates.

Related Methods

• add_server - Create the server first
• unbind_interface - Remove specific interfaces

pub fn get_server<'l>( &'l self, server_name: &str, ) -> Option<impl Deref<Target = Server> + 'l>

Get the server by its name.

pub fn unbind_interface<'s>( &self, server_names: Option<impl IntoIterator<Item = &'s str>>, bind_uri: BindUri, )

Remove a specific network interface from one or more servers.

Provides fine-grained control over interface management, allowing selective removal of interfaces without affecting the server’s core configuration or other interfaces. This is the counterpart to bind_interfaces for flexible network topology management.

The server_names parameter controls the scope:

• Some(server_names) - Remove the interface only from specified servers
• None - Remove the interface from ALL servers currently using it

Operations are graceful: non-existent servers or unbound interfaces are silently ignored, enabling safe cleanup and idempotent scripts.

Related Methods

• bind_interfaces - Add interfaces (counterpart operation)
• remove_server - Remove entire server instead

pub async fn accept(&self) -> Result<(Arc<Connection>, String, Pathway, Link)>

Accept an incoming QUIC connection from the queue.

Returns the connection, connected server name, and network path information. Connections are automatically routed based on SNI (Server Name Indication).

The connection queue size is limited by the backlog parameter in QuicListenersBuilder::listen. When the queue is full, new incoming packets may be dropped at the network level.

pub fn shutdown(&self)

Close the QuicListeners, stops accepting new connections.

Unaccepted connections will be closed

Trait Implementations

impl Drop for QuicListeners

fn drop(&mut self)

Executes the destructor for this type.