Struct trillium_server_common::Config

pub struct Config<ServerType: ?Sized, 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 + ?Sized,
    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 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_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_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.

impl<ServerType> Config<ServerType, ()>

pub fn new() -> Self

build a new config with default acceptor

Trait Implementations

impl<ServerType: ?Sized, AcceptorType: Clone> Clone for Config<ServerType, AcceptorType>

fn clone(&self) -> Self

Returns a copy of the value.

const 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(&self) -> &CloneCounter

returns the CloneCounter for this server. please note that cloning this type has implications for graceful shutdown and needs to be done with care.

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) -> Listenerwhere
    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 + ?Sized, AcceptorType: Debug> Debug for Config<ServerType, AcceptorType>

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

Formats the value using the given formatter.

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

fn default() -> Self

Returns the “default value” for a type.