Module rocket::config [] [src]

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. It also allows libraries to access values that have been configured by the user.

Application Configuration

Environments

Rocket applications are always running in one of three environments:

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:

Rocket.toml

The Rocket.toml file is used to specify the configuration parameters for each environment. The file is optional. If it is not present, the default configuration parameters are used.

The file must be a series of tables, at most one for each environment and a "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
log = "normal"

[staging]
address = "0.0.0.0"
port = 80
log = "normal"
# don't use this key! generate your own and keep it private!
session_key = "VheMwXIBygSmOlZAhuWl2B+zgvTN3WW5"

[production]
address = "0.0.0.0"
port = 80
log = "critical"
# don't use this key! generate your own and keep it private!
session_key = "adL5fFIPmZBrlyHk2YT4NLV3YCk2gFXz"

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"

Retrieving Configuration Parameters

Configuration parameters for the currently active configuration environment can be retrieved via the active function and methods on the Config structure. The general structure is to call active and then one of the get_ methods on the returned Config structure.

As an example, consider the following code used by the Template type to retrieve the value of the template_dir configuration parameter. If the value isn't present or isn't a string, a default value is used.

use rocket::config;

const DEFAULT_TEMPLATE_DIR: &'static str = "templates";

let template_dir = config::active().map(|config| {
    let dir = config.get_str("template_dir")
        .map_err(|e| if !e.is_not_found() { e.pretty_print(); })
        .unwrap_or(DEFAULT_TEMPLATE_DIR);

    config.root().join(dir).to_string_lossy().into_owned()
}).unwrap_or(DEFAULT_TEMPLATE_DIR.to_string());

Libraries should always use a default if a parameter is not defined.

Structs

Config

The core configuration structure.

ParsingError

The type of a configuration parsing error.

Enums

ConfigError

The type of a configuration error.

Environment

An enum corresponding to the valid configuration environments.

Value

Representation of a TOML value.

Functions

active

Retrieve the active configuration, if there is one.

Type Definitions

Array

Type representing a TOML array, payload of the Value::Array variant

Result

Wraps std::result with the error type of ConfigError.

Table

Type representing a TOML table, payload of the Value::Table variant