Struct ListenerConfig 

pub struct ListenerConfig<ServerType>
where
    ServerType: Server,
{ /* private fields */ }

An advanced listener builder.

Holds the inputs shared across every listener — handler (supplied at spawn), swansong, shared state, HTTP config — and a set of registered listeners. Each bind_* method claims its address eagerly (failing fast) and the listeners are adopted into the runtime when the server is spawned, after Handler::init has run exactly once across all of them.

Construct one from a Config with Config::listeners: the global server configuration (swansong, shared state, HTTP config, nodelay, max-connections, signals) is set on the Config, then carried over; the builder adds listener topology.

Implementations

impl<ServerType> ListenerConfig<ServerType>

where ServerType: Server,

pub fn bind_tcp( self, addr: impl IntoListenAddr, ) -> Result<ListenerConfig<ServerType>, Error>

Register a plaintext TCP listener. The address is resolved and bound immediately; an error means the address could not be resolved or the bind failed (e.g. the port is in use). Binding to port 0 selects an ephemeral port, which will be reflected in the bound address reported after spawn.

pub fn bind_tls<A>( self, addr: impl IntoListenAddr, acceptor: A, ) -> Result<ListenerConfig<ServerType>, Error>

where A: Acceptor<<ServerType as Server>::Transport>,

Register a TLS listener, terminating TLS with the provided acceptor (e.g. from trillium-rustls or trillium-native-tls). The protocols offered (h1, h2) follow the acceptor’s ALPN configuration. Like bind_tcp, the address is resolved and bound immediately.

pub fn bind_fd(self, index: usize) -> Result<ListenerConfig<ServerType>, Error>

Register a plaintext TCP listener inherited from the environment as the file descriptor at index (as passed by a socket-activation supervisor such as systemfd or systemd, via the LISTEN_FDS protocol). The descriptor is claimed immediately; an error here means no inherited TCP listener was present at that index.

Unlike the single-listener Config path, which auto-detects LISTEN_FD, this is explicit: each inherited descriptor is bound by index, so several can be adopted.

pub fn bind_env(self) -> Result<ListenerConfig<ServerType>, Error>

Register a single listener resolved from the environment, following trillium’s 12-factor conventions: HOST (default localhost) and PORT (default 8080), a listener inherited via the LISTEN_FDS socket-activation protocol if present, and — on unix — a HOST beginning with /, ., or ~ treated as a Unix-domain-socket path (the port is ignored).

This is the explicit, fallible equivalent of the implicit binding that Config performs when no listener is configured. The listener is plaintext; for a TLS listener resolved the same way use bind_env_tls.

pub fn bind_env_tls<A>( self, acceptor: A, ) -> Result<ListenerConfig<ServerType>, Error>

where A: Acceptor<<ServerType as Server>::Transport>,

Register a single TLS listener resolved from the environment, terminating TLS with the provided acceptor. The TLS equivalent of bind_env; see it for the resolution rules.

pub fn bind_fd_tls<A>( self, index: usize, acceptor: A, ) -> Result<ListenerConfig<ServerType>, Error>

where A: Acceptor<<ServerType as Server>::Transport>,

Register a TLS listener over a TCP descriptor inherited from the environment at index; see bind_fd for how the descriptor is claimed.

pub fn bind_uds( self, path: impl AsRef<Path>, ) -> Result<ListenerConfig<ServerType>, Error>

Register a plaintext listener on a Unix-domain socket at path. The socket is bound immediately; an error here means the bind failed (e.g. the path already exists).

pub fn bind_uds_tls<A>( self, path: impl AsRef<Path>, acceptor: A, ) -> Result<ListenerConfig<ServerType>, Error>

where A: Acceptor<<ServerType as Server>::Transport>,

Register a TLS listener on a Unix-domain socket at path.

pub fn bind_server( self, server: impl Into<ServerType>, ) -> ListenerConfig<ServerType>

Adopt a server the caller has already bound into the runtime (the multi-listener equivalent of Config::with_prebound_server). Plaintext; for a TLS-terminating prebound server use bind_server_tls.

Infallible — there is no bind to fail. The adopted server’s bound address is discovered by running its Server::init hook at spawn.

pub fn bind_server_tls<A>( self, server: impl Into<ServerType>, acceptor: A, ) -> ListenerConfig<ServerType>

where A: Acceptor<<ServerType as Server>::Transport>,

Adopt an already-bound server terminating TLS with the provided acceptor. The TLS equivalent of bind_server.

pub fn bind_quic<Q>( self, addr: impl IntoListenAddr, quic: Q, ) -> Result<ListenerConfig<ServerType>, Error>

where Q: QuicConfig<ServerType>,

Register a QUIC listener for HTTP/3, using the provided QUIC configuration (e.g. from trillium-quinn). The address’s UDP socket is claimed immediately for fail-fast binding; the QUIC endpoint itself is constructed inside the runtime when the server is spawned.

bind_quic does not by itself cause an alt-svc header to be advertised on any TCP listener. If a TCP or TLS listener is bound on the same port as this QUIC listener, the builder will auto-pair the two and advertise alt-svc: h3=":<port>" on that TCP listener’s responses. Use with_alt_svc to express any non-matching pairing (e.g. h3 on a different port from the TLS port that advertises it).

pub fn with_alt_svc(self, from: u16, to: u16) -> ListenerConfig<ServerType>

Advertise an alt-svc: h3=":<to>" header on responses from the TCP/TLS listener bound to from, pointing at the QUIC listener bound to to. May be chained for multiple alternatives — values sharing a from port are merged into one header value.

A matching same-port pair (a bind_tcp(p) or bind_tls(p, _) together with a bind_quic(p, _)) is auto-advertised without an explicit call; use this method only for pairings the builder cannot infer.

from need not be a TLS port — emitting alt-svc from a plaintext listener is valid in topologies where something upstream (a TLS-terminating proxy or load balancer) provides the TLS view a client sees.

pub fn handle(&self) -> ServerHandle

Return a ServerHandle for this builder, usable to await startup, retrieve the bound BoundInfo, or initiate shutdown.

pub async fn run_async(self, handler: impl Handler)

Initialize the handler once and drive every registered listener’s accept loop until shutdown. This is the appropriate entrypoint when embedding in an already-running runtime; see run and spawn for the terminal forms.

pub fn spawn(self, handler: impl Handler) -> ServerHandle

Spawn the server onto its runtime, returning a ServerHandle immediately.

pub fn run(self, handler: impl Handler)

Start the runtime and block on the server until shutdown.

Trait Implementations

impl<ServerType> Debug for ListenerConfig<ServerType>

where ServerType: Server,

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

Formats the value using the given formatter.