Struct rocket::Config

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

Structure for Rocket application configuration.

Usage

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();

General Configuration

For more information about Rocket's configuration, see the config module documentaiton.

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.

limits: Limits

Streaming read size limits.

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

pub 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();

pub 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);

pub fn development() -> Result<Config>

Returns a builder for Config structure where the default parameters are set to those of the development environment. 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::development().unwrap();
my_config.set_port(1001);

pub fn staging() -> Result<Config>

Creates a new configuration using the default parameters from the staging environment. 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::staging().expect("cwd");
my_config.set_port(1001);

pub fn production() -> Result<Config>

Creates a new configuration using the default parameters from the production environment. 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::production().expect("cwd");
my_config.set_port(1001);

pub 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"));

pub 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());

pub 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);

pub 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);

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

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

Errors

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

Example

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

let mut config = Config::new(Environment::Staging)?;
let key = "8Xui8SN4mI+7egV/9dlfYYLGQJeEx4+DwmSQLwDVXJg=";
assert!(config.set_secret_key(key).is_ok());
assert!(config.set_secret_key("hello? anyone there?").is_err());

pub fn set_log_level(&mut self, log_level: LoggingLevel)

Sets the logging level for self to log_level.

Example

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

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

pub fn set_limits(&mut self, limits: Limits)

Set the receive limits in self to limits.

Example

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

let mut config = Config::development()?;
config.set_limits(Limits::default().limit("json", 4 * (1 << 20)));

pub fn set_tls(&mut self, certs_path: &str, key_path: &str) -> Result<()>

Sets the TLS configuration in self.

Certificates are read from certs_path. The certificate chain must be in X.509 PEM format. The private key is read from key_path. The private key must be an RSA key in either PKCS#1 or PKCS#8 PEM format.

Errors

If reading either the certificates or private key fails, an error of variant Io is returned. If either the certificates or private key files are malformed or cannot be parsed, an error of BadType is returned.

Example

use rocket::config::Config;

let mut config = Config::development()?;
config.set_tls("/etc/ssl/my_certs.pem", "/etc/ssl/priv.key")?;

pub 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};

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

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

config.set_extras(extras);

pub 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};

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());
extras.insert("templates".to_string(), "my_dir".into());
config.set_extras(extras);

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

pub 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"));

pub 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));

pub 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));

pub 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));

pub fn get_slice(&self, name: &str) -> Result<&Array>

Attempts to retrieve the extra named name as a slice of an array.

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 array, returns a BadType error.

Example

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

let config = Config::build(Environment::Staging)
    .extra("numbers", vec![1, 2, 3])
    .unwrap();

assert!(config.get_slice("numbers").is_ok());

pub fn get_table(&self, name: &str) -> Result<&Table>

Attempts to retrieve the extra named name as a table.

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 table, returns a BadType error.

Example

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

let mut table = BTreeMap::new();
table.insert("my_value".to_string(), 1);

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

assert!(config.get_table("my_table").is_ok());

pub fn get_datetime(&self, name: &str) -> Result<&Datetime>

Attempts to retrieve the extra named name as a datetime value.

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 datetime, returns a BadType error.

Example

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

let date = "1979-05-27T00:32:00-07:00".parse::<Datetime>().unwrap();

let config = Config::build(Environment::Staging)
    .extra("my_date", Value::Datetime(date.clone()))
    .unwrap();

assert_eq!(config.get_datetime("my_date"), Ok(&date));

pub 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 Clone for Config

fn clone(&self) -> Config

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

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 secret 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 !=.