Module rocket::config[−][src]

Expand description

Application configuration and configuration parameter retrieval.

This module implements configuration handling for Rocket. It implements the parsing and interpretation of the Rocket.toml config file and ROCKET_{PARAM} environment variables. It also allows libraries to access user-configured values.

Application Configuration

Environments

Rocket applications are always running in one of three environments:

development or dev
staging or stage
production or prod

Each environment can contain different configuration parameters. By default, Rocket applications run in the development environment. The environment can be changed via the ROCKET_ENV environment variable. For example, to start a Rocket application in the production environment:

ROCKET_ENV=production ./target/release/rocket_app

Configuration Parameters

Each environments consists of several standard configuration parameters as well as an arbitrary number of extra configuration parameters, which are not used by Rocket itself but can be used by external libraries. The standard configuration parameters are:

name	type	description	examples
address	string	ip address or host to listen on	`"localhost"`, `"1.2.3.4"`
port	integer	port number to listen on	`8000`, `80`
keep_alive	integer	keep-alive timeout in seconds	`0` (disable), `10`
read_timeout	integer	data read timeout in seconds	`0` (disable), `5`
write_timeout	integer	data write timeout in seconds	`0` (disable), `5`
workers	integer	number of concurrent thread workers	`36`, `512`
log	string	max log level: `"off"`, `"normal"`, `"debug"`, `"critical"`	`"off"`, `"normal"`
secret_key	256-bit base64	secret key for private cookies	`"8Xui8SI..."` (44 chars)
tls	table	tls config table with two keys (`certs`, `key`)	see below
tls.certs	string	path to certificate chain in PEM format	`"private/cert.pem"`
tls.key	string	path to private key for `tls.certs` in PEM format	`"private/key.pem"`
limits	table	map from data type (string) to data limit (integer: bytes)	`{ forms = 65536 }`

Rocket.toml

Rocket.toml is a Rocket application’s configuration file. It can optionally be used to specify the configuration parameters for each environment. If it is not present, the default configuration parameters or environment supplied parameters are used.

The file must be a series of TOML tables, at most one for each environment, and an optional “global” table, where each table contains key-value pairs corresponding to configuration parameters for that environment. If a configuration parameter is missing, the default value is used. The following is a complete Rocket.toml file, where every standard configuration parameter is specified with the default value:

[development]
address = "localhost"
port = 8000
workers = [number_of_cpus * 2]
keep_alive = 5
read_timeout = 5
write_timeout = 5
log = "normal"
secret_key = [randomly generated at launch]
limits = { forms = 32768 }

[staging]
address = "0.0.0.0"
port = 8000
workers = [number_of_cpus * 2]
keep_alive = 5
read_timeout = 5
write_timeout = 5
log = "normal"
secret_key = [randomly generated at launch]
limits = { forms = 32768 }

[production]
address = "0.0.0.0"
port = 8000
workers = [number_of_cpus * 2]
keep_alive = 5
read_timeout = 5
write_timeout = 5
log = "critical"
secret_key = [randomly generated at launch]
limits = { forms = 32768 }

The workers and secret_key default parameters are computed by Rocket automatically; the values above are not valid TOML syntax. When manually specifying the number of workers, the value should be an integer: workers = 10. When manually specifying the secret key, the value should a 256-bit base64 encoded string. Such a string can be generated with the openssl command line tool: openssl rand -base64 32.

The “global” pseudo-environment can be used to set and/or override configuration parameters globally. A parameter defined in a [global] table sets, or overrides if already present, that parameter in every environment. For example, given the following Rocket.toml file, the value of address will be "1.2.3.4" in every environment:

[global]
address = "1.2.3.4"

[development]
address = "localhost"

[production]
address = "0.0.0.0"

TLS Configuration

TLS can be enabled by specifying the tls.key and tls.certs parameters. Rocket must be compiled with the tls feature enabled for the parameters to take effect. The recommended way to specify the parameters is via the global environment:

[global.tls]
certs = "/path/to/certs.pem"
key = "/path/to/key.pem"

Environment Variables

All configuration parameters, including extras, can be overridden through environment variables. To override the configuration parameter {param}, use an environment variable named ROCKET_{PARAM}. For instance, to override the “port” configuration parameter, you can run your application with:

ROCKET_PORT=3721 ./your_application

Environment variables take precedence over all other configuration methods: if the variable is set, it will be used as the value for the parameter. Variable values are parsed as if they were TOML syntax. As illustration, consider the following examples:

ROCKET_INTEGER=1
ROCKET_FLOAT=3.14
ROCKET_STRING=Hello
ROCKET_STRING="Hello"
ROCKET_BOOL=true
ROCKET_ARRAY=[1,"b",3.14]
ROCKET_DICT={key="abc",val=123}

Retrieving Configuration Parameters

Configuration parameters for the currently active configuration environment can be retrieved via the Rocket::config() Rocket and get_ methods on Config structure.

The retrivial of configuration parameters usually occurs at launch time via a launch fairing. If information about the configuraiton is needed later in the program, an attach fairing can be used to store the information as managed state. As an example of the latter, consider the following short program which reads the token configuration parameter and stores the value or a default in a Token managed state value:

use rocket::fairing::AdHoc;

struct Token(i64);

fn main() {
    rocket::ignite()
        .attach(AdHoc::on_attach("Token Config", |rocket| {
            println!("Adding token managed state from config...");
            let token_val = rocket.config().get_int("token").unwrap_or(-1);
            Ok(rocket.manage(Token(token_val)))
        }))
}