Struct Config 

pub struct Config<ServerType: Server, AcceptorType, QuicType: QuicConfig<ServerType> = ()> { /* private fields */ }

Primary entrypoint for configuring and running a trillium server

The associated methods on this struct are intended to be chained.

Example

trillium_smol::config() // or trillium_async_std, trillium_tokio
    .with_port(8080) // the default
    .with_host("localhost") // the default
    .with_nodelay()
    .with_max_connections(Some(10000))
    .without_signals()
    .run(|conn: trillium::Conn| async move { conn.ok("hello") });

Socket binding

The socket binding logic is as follows:

If a LISTEN_FD environment variable is available on cfg(unix) systems, that will be used, overriding host and port settings Otherwise: Host will be selected from explicit configuration using Config::with_host or else the HOST environment variable, or else a default of “localhost”. On cfg(unix) systems only: If the host string (as set by env var or direct config) begins with ., /, or ~, it is interpreted to be a path, and trillium will bind to it as a unix domain socket. Port will be ignored. The socket will be deleted on clean shutdown. Port will be selected from explicit configuration using Config::with_port or else the PORT environment variable, or else a default of 8080.

Signals

On cfg(unix) systems, SIGTERM, SIGINT, and SIGQUIT are all registered to perform a graceful shutdown on the first signal and an immediate shutdown on a subsequent signal. This behavior may change as trillium matures. To disable this behavior, use Config::without_signals.

Implementations

impl<ServerType, AcceptorType, QuicType> Config<ServerType, AcceptorType, QuicType>

where ServerType: Server, AcceptorType: Acceptor<ServerType::Transport>, QuicType: QuicConfig<ServerType>,

pub fn run(self, handler: impl Handler)

Starts an async runtime and runs the provided handler with this config in that runtime. This is the appropriate entrypoint for applications that do not need to spawn tasks outside of trillium’s web server. For applications that embed a trillium server inside of an already-running async runtime, use Config::run_async

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

Runs the provided handler with this config, in an already-running runtime. This is the appropriate entrypoint for an application that needs to spawn async tasks that are unrelated to the trillium application. If you do not need to spawn other tasks, Config::run is the preferred entrypoint

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

Spawns the server onto the async runtime, returning a ServerHandle that can be awaited directly to return an Info or used with ServerHandle::info and ServerHandle::shut_down

pub fn handle(&self) -> ServerHandle

Returns a ServerHandle for this Config. This is useful when spawning the server onto a runtime.

pub fn with_port(self, port: u16) -> Self

Configures the server to listen on this port. The default is the PORT environment variable or 8080

pub fn with_host(self, host: &str) -> Self

Configures the server to listen on this host or ip address. The default is the HOST environment variable or “localhost”

pub fn without_signals(self) -> Self

Configures the server to NOT register for graceful-shutdown signals with the operating system. Default behavior is for the server to listen for SIGINT and SIGTERM and perform a graceful shutdown.

pub fn with_nodelay(self) -> Self

Configures the tcp listener to use TCP_NODELAY. See https://en.wikipedia.org/wiki/Nagle%27s_algorithm for more information on this setting.

pub fn with_socketaddr(self, socketaddr: SocketAddr) -> Self

Configures the server to listen on the ip and port specified by the provided socketaddr. This is identical to self.with_host(&socketaddr.ip().to_string()).with_port(socketaddr.port())

pub fn with_acceptor<A: Acceptor<ServerType::Transport>>( self, acceptor: A, ) -> Config<ServerType, A, QuicType>

Configures the tls acceptor for this server

pub fn with_quic<Q: QuicConfig<ServerType>>( self, quic: Q, ) -> Config<ServerType, AcceptorType, Q>

Configures QUIC/HTTP3 for this server

pub fn with_swansong(self, swansong: Swansong) -> Self

use the specific Swansong provided

pub fn with_max_connections(self, max_connections: Option<usize>) -> Self

Configures the maximum number of connections to accept. The default is 75% of the soft rlimit_nofile (ulimit -n) on unix systems, and None on other sytems.

pub fn with_config(self, config: HttpConfig) -> Self

configures trillium-http performance and security tuning parameters.

See HttpConfig for documentation

pub fn with_prebound_server(self, server: impl Into<ServerType>) -> Self

Use a pre-bound transport stream as server.

The argument to this varies for different servers, but usually accepts the runtime’s TcpListener and, on unix platforms, the UnixListener.

Note well

Many of the other options on this config will be ignored if you provide a listener. In particular, host and port will be ignored. All of the other options will be used.

Additionally, cloning this config will not clone the listener.

pub fn runtime(&self) -> ServerType::Runtime

retrieve the runtime

pub fn port(&self) -> Option<u16>

return the configured port

pub fn host(&self) -> Option<&str>

return the configured host

impl<ServerType: Server> Config<ServerType, ()>

pub fn new() -> Self

build a new config with default acceptor

Trait Implementations

impl<ServerType: Debug + Server, AcceptorType: Debug, QuicType: Debug + QuicConfig<ServerType>> Debug for Config<ServerType, AcceptorType, QuicType>

where ServerType::Runtime: Debug,

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

Formats the value using the given formatter.

impl<ServerType: Server> Default for Config<ServerType, ()>

fn default() -> Self

Returns the “default value” for a type.