Struct trillium_server_common::Config
source · pub struct Config<ServerType, 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§
source§impl<ServerType, AcceptorType> Config<ServerType, AcceptorType>
impl<ServerType, AcceptorType> Config<ServerType, AcceptorType>
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 spawn(self, handler: impl Handler) -> ServerHandle
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
sourcepub fn handle(&self) -> ServerHandle
pub fn handle(&self) -> ServerHandle
Returns a ServerHandle
for this Config. This is useful
when spawning the server onto a runtime.
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_socketaddr(self, socketaddr: SocketAddr) -> Self
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())
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_observer(self, observer: CloneCounterObserver) -> Self
pub fn with_observer(self, observer: CloneCounterObserver) -> Self
use the specified CloneCounterObserver
to monitor or
modify the outstanding connection count for graceful shutdown
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.
sourcepub fn with_http_config(self, http_config: HttpConfig) -> Self
pub fn with_http_config(self, http_config: HttpConfig) -> Self
configures trillium-http performance and security tuning parameters.
See HttpConfig
for documentation
sourcepub fn with_prebound_server(self, server: impl Into<ServerType>) -> Self
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.
Trait Implementations§
source§impl<ServerType, AcceptorType> ConfigExt<ServerType, AcceptorType> for Config<ServerType, AcceptorType>
impl<ServerType, AcceptorType> ConfigExt<ServerType, AcceptorType> for Config<ServerType, AcceptorType>
source§fn port(&self) -> u16
fn port(&self) -> u16
PORT
, or a default
of 8080
source§fn host(&self) -> String
fn host(&self) -> String
HOST
env var, or "localhost"
source§fn socket_addrs(&self) -> Vec<SocketAddr>
fn socket_addrs(&self) -> Vec<SocketAddr>
ConfigExt::port
and ConfigExt::host
to resolve
a vec of potential socket addrssource§fn should_register_signals(&self) -> bool
fn should_register_signals(&self) -> bool
cfg(unix)
systems, and false
elsewhere.source§fn nodelay(&self) -> bool
fn nodelay(&self) -> bool
source§fn stopper(&self) -> Stopper
fn stopper(&self) -> Stopper
Stopper
associated with
this server, to be used in conjunction with signals or other
service interruption methodssource§fn acceptor(&self) -> &AcceptorType
fn acceptor(&self) -> &AcceptorType
source§fn counter_observer(&self) -> &CloneCounterObserver
fn counter_observer(&self) -> &CloneCounterObserver
CloneCounterObserver
for this serversource§fn graceful_shutdown<'life0, 'async_trait>(
&'life0 self,
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
fn graceful_shutdown<'life0, 'async_trait>(
&'life0 self,
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
CloneCounter
in this
config to drop, indicating that all outstanding requests are
completesource§fn handle_stream<'life0, 'async_trait>(
&'life0 self,
stream: ServerType::Transport,
handler: impl 'async_trait + Handler,
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
fn handle_stream<'life0, 'async_trait>(
&'life0 self,
stream: ServerType::Transport,
handler: impl 'async_trait + Handler,
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
trillium_http
’s http implementation. this is the default inner
loop for most trillium serverssource§fn build_listener<Listener>(&self) -> Listener
fn build_listener<Listener>(&self) -> Listener
ConfigExt::port
,
ConfigExt::host
, or ConfigExt::socket_addrs
. Read moresource§fn over_capacity(&self) -> bool
fn over_capacity(&self) -> bool
Config::with_max_connections
.Auto Trait Implementations§
impl<ServerType, AcceptorType> !Freeze for Config<ServerType, AcceptorType>
impl<ServerType, AcceptorType> RefUnwindSafe for Config<ServerType, AcceptorType>where
AcceptorType: RefUnwindSafe,
ServerType: RefUnwindSafe,
impl<ServerType, AcceptorType> Send for Config<ServerType, AcceptorType>
impl<ServerType, AcceptorType> Sync for Config<ServerType, AcceptorType>
impl<ServerType, AcceptorType> Unpin for Config<ServerType, AcceptorType>
impl<ServerType, AcceptorType> UnwindSafe for Config<ServerType, AcceptorType>where
AcceptorType: UnwindSafe,
ServerType: UnwindSafe,
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§default unsafe fn clone_to_uninit(&self, dst: *mut T)
default unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)