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:
- 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:
- address: [string] an IP address or host the application will
listen on
- examples:
"localhost"
,"0.0.0.0"
,"1.2.3.4"
- examples:
- port: [integer] a port number to listen on
- examples:
"8000"
,"80"
,"4242"
- examples:
- log: [string] how much information to log; one of
"normal"
,"debug"
, or"critical"
- session_key: [string] a 192-bit base64 encoded string (32
characters) to use as the session key
- example:
"VheMwXIBygSmOlZAhuWl2B+zgvTN3WW5"
- example:
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 |
Result |
Wraps |
Table |
Type representing a TOML table, payload of the |