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 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§

source§

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

source

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

source

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

source

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

source

pub fn handle(&self) -> ServerHandle

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

source

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

source

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”

source

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.

source

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.

source

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())

source

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

Configures the tls acceptor for this server

source

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

use the specific Stopper provided

source

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

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

source

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.

source

pub fn with_http_config(self, http_config: HttpConfig) -> Self

configures trillium-http performance and security tuning parameters.

See HttpConfig for documentation

source

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.

source§

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

source

pub fn new() -> Self

build a new config with default acceptor

Trait Implementations§

source§

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

source§

fn clone(&self) -> Self

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl<ServerType, AcceptorType> ConfigExt<ServerType, AcceptorType> for Config<ServerType, AcceptorType>
where ServerType: Server + Send + ?Sized, AcceptorType: Acceptor<<ServerType as Server>::Transport>,

source§

fn port(&self) -> u16

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

fn host(&self) -> String

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

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

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

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.
source§

fn nodelay(&self) -> bool

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

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
source§

fn acceptor(&self) -> &AcceptorType

returns the tls acceptor for this server
source§

fn counter_observer(&self) -> &CloneCounterObserver

returns the CloneCounterObserver for this server
source§

fn graceful_shutdown<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

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

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,

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

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. Read more
source§

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.
source§

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

source§

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

Formats the value using the given formatter. Read more
source§

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

source§

fn default() -> Self

Returns the “default value” for a type. Read more

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>
where AcceptorType: Send, ServerType: Send,

§

impl<ServerType, AcceptorType> Sync for Config<ServerType, AcceptorType>
where AcceptorType: Sync, ServerType: Sync + Send,

§

impl<ServerType, AcceptorType> Unpin for Config<ServerType, AcceptorType>
where AcceptorType: Unpin, ServerType: Unpin,

§

impl<ServerType, AcceptorType> UnwindSafe for Config<ServerType, AcceptorType>
where AcceptorType: UnwindSafe, ServerType: UnwindSafe,

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

default unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.