Struct trillium_server_common::Config
source · [−]pub struct Config<ServerType: ?Sized, AcceptorType> { /* private fields */ }
Expand description
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 theHOST
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.
- On
- Port will be selected from explicit configuration using
Config::with_port
or else thePORT
environment variable, or else a default of 8080.
- Host will be selected from explicit configuration using
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
sourceimpl<ServerType, AcceptorType> Config<ServerType, AcceptorType>where
ServerType: Server + ?Sized,
AcceptorType: Acceptor<ServerType::Transport>,
impl<ServerType, AcceptorType> Config<ServerType, AcceptorType>where
ServerType: Server + ?Sized,
AcceptorType: Acceptor<ServerType::Transport>,
sourcepub fn run<H: Handler>(self, h: H)
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
sourcepub async fn run_async(self, handler: impl Handler)
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
sourcepub fn with_port(self, port: u16) -> Self
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
sourcepub fn with_host(self, host: &str) -> Self
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”
sourcepub fn without_signals(self) -> Self
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.
sourcepub fn with_nodelay(self) -> Self
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.
sourcepub fn with_acceptor<A: Acceptor<ServerType::Transport>>(
self,
acceptor: A
) -> Config<ServerType, A>
pub fn with_acceptor<A: Acceptor<ServerType::Transport>>(
self,
acceptor: A
) -> Config<ServerType, A>
Configures the tls acceptor for this server
sourcepub fn with_stopper(self, stopper: Stopper) -> Self
pub fn with_stopper(self, stopper: Stopper) -> Self
use the specific Stopper
provided
sourcepub fn with_max_connections(self, max_connections: Option<usize>) -> Self
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.
Trait Implementations
sourceimpl<ServerType, AcceptorType> ConfigExt<ServerType, AcceptorType> for Config<ServerType, AcceptorType>where
ServerType: Server + Send + ?Sized,
AcceptorType: Acceptor<<ServerType as Server>::Transport>,
impl<ServerType, AcceptorType> ConfigExt<ServerType, AcceptorType> for Config<ServerType, AcceptorType>where
ServerType: Server + Send + ?Sized,
AcceptorType: Acceptor<<ServerType as Server>::Transport>,
sourcefn port(&self) -> u16
fn port(&self) -> u16
PORT
, or a default
of 8080
Read moresourcefn host(&self) -> String
fn host(&self) -> String
HOST
env var, or "localhost"
Read moresourcefn socket_addrs(&self) -> Vec<SocketAddr>
fn socket_addrs(&self) -> Vec<SocketAddr>
sourcefn should_register_signals(&self) -> bool
fn should_register_signals(&self) -> bool
cfg(unix)
systems, and false
elsewhere. Read moresourcefn nodelay(&self) -> bool
fn nodelay(&self) -> bool
sourcefn counter(&self) -> &CloneCounterⓘNotable traits for CloneCounterimpl Future for CloneCounter type Output = ();
fn counter(&self) -> &CloneCounterⓘNotable traits for CloneCounterimpl Future for CloneCounter type Output = ();
CloneCounter
for this server. please note that
cloning this type has implications for graceful shutdown and
needs to be done with care. Read moresourcefn graceful_shutdown<'async_trait>(
self
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>where
Self: 'async_trait,
fn graceful_shutdown<'async_trait>(
self
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>where
Self: 'async_trait,
CloneCounter
in this
config to drop, indicating that all outstanding requests are
complete Read moresourcefn 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,
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,
trillium_http
]’s http implementation. this is the default inner
loop for most trillium servers Read moresourcefn build_listener<Listener>(&self) -> Listenerwhere
Listener: TryFrom<TcpListener>,
<Listener as TryFrom<TcpListener>>::Error: Debug,
fn build_listener<Listener>(&self) -> Listenerwhere
Listener: TryFrom<TcpListener>,
<Listener as TryFrom<TcpListener>>::Error: Debug,
ConfigExt::port
,
ConfigExt::host
, or ConfigExt::socket_addrs
. Read moresourcefn over_capacity(&self) -> bool
fn over_capacity(&self) -> bool
Config::with_max_connections
. Read more