Struct trillium_server_common::Config

pub struct Config<ServerType, AcceptorType> { /* 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.

For runtime adapter authors

In order to use this to implement a trillium server, see trillium_server_common::ConfigExt

Implementations

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

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

pub fn run<H: Handler>(self, h: H)

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::stop

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>

Configures the tls acceptor for this server

pub fn with_stopper(self, stopper: Stopper) -> Self

use the specific Stopper provided

pub fn with_observer(self, observer: CloneCounterObserver) -> Self

use the specified CloneCounterObserver to monitor or modify the outstanding connection count for graceful shutdown

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_http_config(self, http_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.

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

pub fn new() -> Self

build a new config with default acceptor

Trait Implementations

impl<ServerType, AcceptorType> Clone for Config<ServerType, AcceptorType>

where ServerType: Server, AcceptorType: Acceptor<ServerType::Transport> + Clone,

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<ServerType, AcceptorType> ConfigExt<ServerType, AcceptorType> for Config<ServerType, AcceptorType>

where ServerType: Server + Send + ?Sized, AcceptorType: Acceptor<<ServerType as Server>::Transport>,

fn port(&self) -> u16

resolve a port for this application, either directly configured, from the environmental variable PORT, or a default of 8080

fn host(&self) -> String

resolve the host for this application, either directly from configuration, from the HOST env var, or "localhost"

fn socket_addrs(&self) -> Vec<SocketAddr>

use the ConfigExt::port and ConfigExt::host to resolve a vec of potential socket addrs

fn should_register_signals(&self) -> bool

returns whether this server should register itself for operating system signals. this flag does nothing aside from communicating to the server implementer that this is desired. defaults to true on cfg(unix) systems, and false elsewhere.

fn nodelay(&self) -> bool

returns whether the server should set TCP_NODELAY on the TcpListener, if that is applicable

fn stopper(&self) -> Stopper

returns a clone of the Stopper associated with this server, to be used in conjunction with signals or other service interruption methods

fn acceptor(&self) -> &AcceptorType

returns the tls acceptor for this server

fn counter_observer(&self) -> &CloneCounterObserver

returns the CloneCounterObserver for this server

fn graceful_shutdown<'async_trait>( self ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait,

waits for the last clone of the CloneCounter in this config to drop, indicating that all outstanding requests are complete

fn handle_stream<'async_trait>( self, stream: ServerType::Transport, handler: impl 'async_trait + Handler ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait,

apply the provided handler to the transport, using [trillium_http]’s http implementation. this is the default inner loop for most trillium servers

fn build_listener<Listener>(&self) -> Listener

where Listener: TryFrom<TcpListener>, <Listener as TryFrom<TcpListener>>::Error: Debug,

builds any type that is TryFromstd::net::TcpListener and configures it for use. most trillium servers should use this if possible instead of using ConfigExt::port, ConfigExt::host, or ConfigExt::socket_addrs.

fn over_capacity(&self) -> bool

determines if the server is currently responding to more than the maximum number of connections set by Config::with_max_connections.

impl<ServerType: Debug, AcceptorType: Debug> Debug for Config<ServerType, AcceptorType>

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.