Struct rocket::config::Config

pub struct Config {
    pub environment: Environment,
    pub address: String,
    pub port: u16,
    pub workers: u16,
    pub log_level: LoggingLevel,
    pub extras: HashMap<String, Value>,
    pub config_path: PathBuf,
    // some fields omitted
}

Structure for Rocket application configuration.

A Config structure is typically built using the build method and ConfigBuilder methods:

use rocket::config::{Config, Environment};

let config = Config::build(Environment::Staging)
    .address("127.0.0.1")
    .port(700)
    .workers(12)
    .unwrap();

Fields

environment: Environment

The environment that this configuration corresponds to.

address: String

The address to serve on.

port: u16

The port to serve on.

workers: u16

The number of workers to run concurrently.

log_level: LoggingLevel

How much information to log.

extras: HashMap<String, Value>

Extra parameters that aren't part of Rocket's core config.

config_path: PathBuf

The path to the configuration file this config belongs to.

Methods

impl Config

fn build(env: Environment) -> ConfigBuilder

Returns a builder for Config structure where the default parameters are set to those of env. The root configuration directory is set to the current working directory.

Panics

Panics if the current directory cannot be retrieved.

Example

use rocket::config::{Config, Environment};

let config = Config::build(Environment::Staging)
    .address("127.0.0.1")
    .port(700)
    .workers(12)
    .unwrap();

fn new(env: Environment) -> Result<Config>

Creates a new configuration using the default parameters for the environment env. The root configuration directory is set to the current working directory.

Errors

If the current directory cannot be retrieved, a BadCWD error is returned.

Example

use rocket::config::{Config, Environment};

let mut my_config = Config::new(Environment::Production).expect("cwd");
my_config.set_port(1001);

fn default_for<P>(env: Environment, config_path: P) -> Result<Config> where P: AsRef<Path>

Deprecated since 0.2

: use the new or build methods instead

Returns the default configuration for the environment env given that the configuration was stored at config_path. If config_path is not an absolute path, an Err of ConfigError::BadFilePath is returned.

fn set(&mut self, name: &str, val: &Value) -> Result<()>

Deprecated since 0.2

: use the set_{param} methods instead

Sets the configuration val for the name entry. If the name is one of "address", "port", "session_key", "log", or "workers" (the "default" values), the appropriate value in the self Config structure is set. Otherwise, the value is stored as an extra.

For each of the default values, the following Value variant is expected. If a different variant is supplied, a BadType Err is returned:

• address: String
• port: Integer (16-bit unsigned)
• workers: Integer (16-bit unsigned)
• log: String
• session_key: String (192-bit base64)

fn set_root<P: AsRef<Path>>(&mut self, path: P)

Sets the root directory of this configuration to root.

Example

use rocket::config::{Config, Environment};

let mut config = Config::new(Environment::Staging)?;
config.set_root("/tmp/my_app");

assert_eq!(config.root(), Path::new("/tmp/my_app"));

fn set_address<A: Into<String>>(&mut self, address: A) -> Result<()>

Sets the address of self to address.

Errors

If address is not a valid IP address or hostname, returns a BadType error.

Example

use rocket::config::{Config, Environment};

let mut config = Config::new(Environment::Staging)?;
assert!(config.set_address("localhost").is_ok());
assert!(config.set_address("::").is_ok());
assert!(config.set_address("?").is_err());

fn set_port(&mut self, port: u16)

Sets the port of self to port.

Example

use rocket::config::{Config, Environment};

let mut config = Config::new(Environment::Staging)?;
config.set_port(1024);

fn set_workers(&mut self, workers: u16)

Sets the number of workers in self to workers.

Example

use rocket::config::{Config, Environment};

let mut config = Config::new(Environment::Staging)?;
config.set_workers(64);

fn set_session_key<K: Into<String>>(&mut self, key: K) -> Result<()>

Sets the session_key in self to key which must be a 192-bit base64 encoded string.

Errors

If key is not a valid 192-bit base64 encoded string, returns a BadType error.

Example

use rocket::config::{Config, Environment};

let mut config = Config::new(Environment::Staging)?;
assert!(config.set_session_key("VheMwXIBygSmOlZAhuWl2B+zgvTN3WW5").is_ok());
assert!(config.set_session_key("hello? anyone there?").is_err());

fn set_log_level(&mut self, log_level: LoggingLevel)

Sets the logging level for self to log_level.

Example

use rocket::LoggingLevel;
use rocket::config::{Config, Environment};

let mut config = Config::new(Environment::Staging)?;
config.set_log_level(LoggingLevel::Critical);

fn set_extras(&mut self, extras: HashMap<String, Value>)

Sets the extras for self to be the key/value pairs in extras. encoded string.

Example

use std::collections::HashMap;
use rocket::config::{Config, Environment, IntoValue};

let mut config = Config::new(Environment::Staging)?;

// Create the `extras` map.
let mut extras = HashMap::new();
extras.insert("another_port".to_string(), 1044.into_value());
extras.insert("templates".to_string(), "my_dir".into_value());

config.set_extras(extras);

fn extras<'a>(&'a self) -> impl Iterator<Item=(&'a str, &'a Value)>

Returns an iterator over the names and values of all of the extras in self.

Example

use std::collections::HashMap;
use rocket::config::{Config, Environment, IntoValue};

let mut config = Config::new(Environment::Staging)?;
assert_eq!(config.extras().count(), 0);

// Add a couple of extras to the config.
let mut extras = HashMap::new();
extras.insert("another_port".to_string(), 1044.into_value());
extras.insert("templates".to_string(), "my_dir".into_value());
config.set_extras(extras);

assert_eq!(config.extras().count(), 2);

fn take_session_key(&self) -> Option<String>

Moves the session key string out of the self Config, if there is one. Because the value is moved out, subsequent calls will result in a return value of None.

Example

use rocket::config::{Config, Environment};

// Create a new config with a session key.
let key = "adL5fFIPmZBrlyHk2YT4NLV3YCk2gFXz";
let config = Config::build(Environment::Staging)
    .session_key(key)
    .unwrap();

// Get the key for the first time.
let session_key = config.take_session_key();
assert_eq!(session_key, Some(key.to_string()));

// Try to get the key again.
let session_key_again = config.take_session_key();
assert_eq!(session_key_again, None);

fn get_str<'a>(&'a self, name: &str) -> Result<&'a str>

Attempts to retrieve the extra named name as a string.

Errors

If an extra with name doesn't exist, returns an Err of NotFound. If an extra with name does exist but is not a string, returns a BadType error.

Example

use rocket::config::{Config, Environment};

let config = Config::build(Environment::Staging)
    .extra("my_extra", "extra_value")
    .unwrap();

assert_eq!(config.get_str("my_extra"), Ok("extra_value"));

fn get_int(&self, name: &str) -> Result<i64>

Attempts to retrieve the extra named name as an integer.

Errors

If an extra with name doesn't exist, returns an Err of NotFound. If an extra with name does exist but is not an integer, returns a BadType error.

Example

use rocket::config::{Config, Environment};

let config = Config::build(Environment::Staging)
    .extra("my_extra", 1025)
    .unwrap();

assert_eq!(config.get_int("my_extra"), Ok(1025));

fn get_bool(&self, name: &str) -> Result<bool>

Attempts to retrieve the extra named name as a boolean.

Errors

If an extra with name doesn't exist, returns an Err of NotFound. If an extra with name does exist but is not a boolean, returns a BadType error.

Example

use rocket::config::{Config, Environment};

let config = Config::build(Environment::Staging)
    .extra("my_extra", true)
    .unwrap();

assert_eq!(config.get_bool("my_extra"), Ok(true));

fn get_float(&self, name: &str) -> Result<f64>

Attempts to retrieve the extra named name as a float.

Errors

If an extra with name doesn't exist, returns an Err of NotFound. If an extra with name does exist but is not a float, returns a BadType error.

Example

use rocket::config::{Config, Environment};

let config = Config::build(Environment::Staging)
    .extra("pi", 3.14159)
    .unwrap();

assert_eq!(config.get_float("pi"), Ok(3.14159));

fn root(&self) -> &Path

Returns the path at which the configuration file for self is stored. For instance, if the configuration file is at /tmp/Rocket.toml, the path /tmp is returned.

Example

use std::env::current_dir;
use rocket::config::{Config, Environment};

let config = Config::new(Environment::Staging)
    .expect("can retrieve current directory");

assert_eq!(config.root(), current_dir().unwrap());

Trait Implementations

impl Debug for Config

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

Formats the value using the given formatter.

impl PartialEq for Config

Doesn't consider the session key or config path.

fn eq(&self, other: &Config) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.