Struct Server

pub struct Server<T> { /* private fields */ }

Serve an app over HTTP.

Implementations

impl<State> Server<State>

where State: Send + Sync + 'static,

pub fn new(app: App<State>) -> Self

Creates a new server for the provided app.

pub fn listen<A: ToSocketAddrs>( self, address: A, ) -> impl Future<Output = Result<ExitCode, Box<dyn Error + Send + Sync>>>

Starts the server and listens for incoming connections at the provided address. Returns a future that resolves when the server is shutdown.

Errors

If the server fails to bind to the provided address or is unable to finish serving all of the inflight connections within the specified shutdown timeout when a shutdown signal is received.

Exit Codes

An ExitCode::SUCCESS can be viewed as a confirmation that every request was served before exiting the accept loop.

An ExitCode::FAILURE is an indicator that an unrecoverable error occured which requires that the server be restarted in order to function as intended.

If you are running your Via application as a daemon with a process supervisor such as upstart or systemd, you can use the exit code to determine whether or not the process should restart.

If you are running your Via application in a cluster behind a load balancer you can use the exit code to properly configure node replacement and / or decommissioning logic.

When high availability is mission-critical, and you are scaling your Via application both horizontally and vertically using a combination of the aforementioned deployment strategies, we recommend configuring a temporal threshold for the number of restarts caused by an ExitCode::FAILURE. If the threshold is exceeded the cluster should immutably replace the node and the process supervisor should not make further attempts to restart the process.

This approach significantly reduces the impact of environmental entropy on your application’s availability while preventing conflicts between the process supervisor of an individual node and the replacement and decommissioning logic of the cluster.

pub fn shutdown_timeout(self, timeout: u64) -> Self

Set the amount of time in seconds that the server will wait for inflight connections to complete before shutting down. The default value is 30 seconds.

pub fn max_request_size(self, limit: usize) -> Self

pub fn max_connections(self, limit: usize) -> Self

Sets the maximum number of concurrent connections that the server can accept. The default value is 256.

We suggest not setting this value unless you know what you are doing and have a good reason to do so. If you are unsure, it is best to leave this value at the default and scale horizontally.

If you do set this value, we suggest doing so by profiling the stack size of your application when it’s under load and incrementally increasing this value until you find a balance between performance and worry-free programming. In other words, the closer this value is to the limit based on your application’s stack consumption and the stack size of your server, the more careful you will need to be when allocating values on the stack (i.e dereferencing a heap pointer). Otherwise, you may encounter a stack overflow. In addition to the stack size, you should also consider not setting this value higher than the number of available file descriptors (or ulimit -n) on POSIX systems.