Struct Config

pub struct Config {

    pub profile: Profile,
    pub workers: usize,
    pub max_blocking: usize,
    pub ident: Ident,
    pub ip_header: Option<Uncased<'static>>,
    pub proxy_proto_header: Option<Uncased<'static>>,
    pub limits: Limits,
    pub temp_dir: RelativePathBuf,
    pub keep_alive: u32,
    pub secret_key: SecretKey,
    pub shutdown: ShutdownConfig,
    pub log_level: Option<Level>,
    pub log_format: TraceFormat,
    pub cli_colors: CliColors,
    /* private fields */
}

Rocket server configuration.

See the module level docs as well as the configuration guide for further details.

Defaults

All configuration values have a default, documented in the fields section below. Config::debug_default() returns the default values for the debug profile while Config::release_default() the default values for the release profile. The Config::default() method automatically selects the appropriate of the two based on the selected profile. With the exception of log_level and log_format, which are info / pretty in debug and error / compact in release, and secret_key, which is regenerated from a random value if not set in “debug” mode only, all default values are identical in all profiles.

Provider Details

Config is a Figment Provider with the following characteristics:

• Profile

  The profile is set to the value of the profile field.

• Metadata

  This provider is named Rocket Config. It does not specify a Source and uses default interpolation.

• Data

  The data emitted by this provider are the keys and values corresponding to the fields and values of the structure. The dictionary is emitted to the “default” meta-profile.

Note that these behaviors differ from those of Config::figment().

Fields

profile: Profile

The selected profile. (default: debug debug / release release)

Note: This field is never serialized nor deserialized. When a Config is merged into a Figment as a Provider, this profile is selected on the Figment. When a Config is extracted, this field is set to the extracting Figment’s selected Profile.

workers: usize

Number of threads to use for executing futures. (default: num_cores)

Note: Rocket only reads this value from sources in the default provider.

max_blocking: usize

Limit on threads to start for blocking tasks. (default: 512)

ident: Ident

How, if at all, to identify the server via the Server header. (default: "Rocket")

ip_header: Option<Uncased<'static>>

The name of a header, whose value is typically set by an intermediary server or proxy, which contains the real IP address of the connecting client. Used internally and by Request::client_ip() and Request::real_ip().

To disable using any header for this purpose, set this value to false or None. Deserialization semantics are identical to those of Ident except that the value must syntactically be a valid HTTP header name.

(default: "X-Real-IP")

proxy_proto_header: Option<Uncased<'static>>

The name of a header, whose value is typically set by an intermediary server or proxy, which contains the protocol (“http” or “https”) used by the connecting client. This is usually "X-Forwarded-Proto", as that is the de-facto standard.

The header value is parsed into a ProxyProto, accessible via Request::proxy_proto(). The value influences Request::context_is_likely_secure() and the default value for the Secure flag in cookies added to CookieJars.

To disable using any header for this purpose, set this value to false or None. Deserialization semantics are identical to those of Config::ip_header (the value must be a valid HTTP header name).

(default: None)

limits: Limits

Streaming read size limits. (default: Limits::default())

temp_dir: RelativePathBuf

Directory to store temporary files in. (default: std::env::temp_dir())

keep_alive: u32

Keep-alive timeout in seconds; disabled when 0. (default: 5)

secret_key: SecretKey

Available on crate feature secrets only.

The secret key for signing and encrypting. (default: 0)

Note: This field always serializes as a 256-bit array of 0s to aid in preventing leakage of the secret key.

shutdown: ShutdownConfig

Graceful shutdown configuration. (default: ShutdownConfig::default())

log_level: Option<Level>

Max level to log. (default: debug info / release error)

log_format: TraceFormat

Format to use when logging. (default: debug pretty / release compact)

cli_colors: CliColors

Whether to use colors and emoji when logging. (default: CliColors::Auto)

Implementations

impl Config

pub fn debug_default() -> Config

Returns the default configuration for the debug profile, irrespective of the Rust compilation profile and ROCKET_PROFILE.

This may differ from the configuration used by default, Config::default(), which is selected based on the Rust compilation profile. See defaults and provider details for specifics.

Example

use rocket::Config;

let config = Config::debug_default();

pub fn release_default() -> Config

Returns the default configuration for the release profile, irrespective of the Rust compilation profile and ROCKET_PROFILE.

This may differ from the configuration used by default, Config::default(), which is selected based on the Rust compilation profile. See defaults and provider details for specifics.

Example

use rocket::Config;

let config = Config::release_default();

pub fn figment() -> Figment

Returns the default provider figment used by rocket::build().

The default figment reads from the following sources, in ascending priority order:

1. Config::default() (see defaults)
2. Rocket.toml or filename in ROCKET_CONFIG environment variable
3. ROCKET_ prefixed environment variables

The profile selected is the value set in the ROCKET_PROFILE environment variable. If it is not set, it defaults to debug when compiled in debug mode and release when compiled in release mode.

Example

use rocket::Config;
use serde::Deserialize;

#[derive(Deserialize)]
struct MyConfig {
    app_key: String,
}

let my_config = Config::figment().extract::<MyConfig>();

pub fn try_from<T: Provider>(provider: T) -> Result<Self>

Attempts to extract a Config from provider, returning the result.

Example

use rocket::Config;
use rocket::figment::providers::{Toml, Format, Env};

// Use Rocket's default `Figment`, but allow values from `MyApp.toml`
// and `MY_APP_` prefixed environment variables to supersede its values.
let figment = Config::figment()
    .merge(("some-thing", 123))
    .merge(Env::prefixed("CONFIG_"));

let config = Config::try_from(figment);

pub fn from<T: Provider>(provider: T) -> Self

Extract a Config from provider, panicking if extraction fails.

Panics

If extraction fails, logs an error message indicating the error and panics. For a version that doesn’t panic, use Config::try_from().

Example

use rocket::Config;
use rocket::figment::providers::{Toml, Format, Env};

// Use Rocket's default `Figment`, but allow values from `MyApp.toml`
// and `MY_APP_` prefixed environment variables to supersede its values.
let figment = Config::figment()
    .merge(Toml::file("MyApp.toml").nested())
    .merge(Env::prefixed("MY_APP_"));

let config = Config::from(figment);

impl Config

Associated constants for default profiles.

pub const DEBUG_PROFILE: Profile = _

The default debug profile: debug.

pub const RELEASE_PROFILE: Profile = _

The default release profile: release.

pub const DEFAULT_PROFILE: Profile = Self::DEBUG_PROFILE

The default profile: “debug” on debug, “release” on release.

impl Config

Associated constants for stringy versions of configuration parameters.

pub const WORKERS: &'static str = "workers"

The stringy parameter name for setting/extracting Config::workers.

pub const MAX_BLOCKING: &'static str = "max_blocking"

The stringy parameter name for setting/extracting Config::max_blocking.

pub const KEEP_ALIVE: &'static str = "keep_alive"

The stringy parameter name for setting/extracting Config::keep_alive.

pub const IDENT: &'static str = "ident"

The stringy parameter name for setting/extracting Config::ident.

pub const IP_HEADER: &'static str = "ip_header"

The stringy parameter name for setting/extracting Config::ip_header.

pub const PROXY_PROTO_HEADER: &'static str = "proxy_proto_header"

The stringy parameter name for setting/extracting Config::proxy_proto_header.

pub const LIMITS: &'static str = "limits"

The stringy parameter name for setting/extracting Config::limits.

pub const SECRET_KEY: &'static str = "secret_key"

The stringy parameter name for setting/extracting Config::secret_key.

pub const TEMP_DIR: &'static str = "temp_dir"

The stringy parameter name for setting/extracting Config::temp_dir.

pub const LOG_LEVEL: &'static str = "log_level"

The stringy parameter name for setting/extracting Config::log_level.

pub const LOG_FORMAT: &'static str = "log_format"

The stringy parameter name for setting/extracting Config::log_format.

pub const SHUTDOWN: &'static str = "shutdown"

The stringy parameter name for setting/extracting Config::shutdown.

pub const CLI_COLORS: &'static str = "cli_colors"

The stringy parameter name for setting/extracting Config::cli_colors.

pub const PARAMETERS: &'static [&'static str] = _

An array of all of the stringy parameter names.

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 Default for Config

fn default() -> Config

Returns the default configuration based on the Rust compilation profile. This is Config::debug_default() in debug and Config::release_default() in release.

Example

use rocket::Config;

let config = Config::default();

impl<'de> Deserialize<'de> for Config

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<'r> FromRequest<'r> for &'r Config

type Error = Infallible

The associated error to be returned if derivation fails.

fn from_request<'life0, 'async_trait>( req: &'r Request<'life0>, ) -> Pin<Box<dyn Future<Output = Outcome<Self, Self::Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'r: 'async_trait, 'life0: 'async_trait,

Derives an instance of Self from the incoming request metadata.

impl PartialEq for Config

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Provider for Config

fn metadata(&self) -> Metadata

Returns the Metadata for this provider, identifying itself and its configuration sources.

fn data(&self) -> Result<Map<Profile, Dict>>

Returns the configuration data.

fn profile(&self) -> Option<Profile>

Optionally returns a profile to set on the Figment this provider is merged into. The profile is only set if self is merged.

impl Serialize for Config

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Trace for Config

fn trace(&self, level: Level)

fn trace_info(&self)

fn trace_warn(&self)

fn trace_error(&self)

fn trace_debug(&self)

fn trace_trace(&self)

impl StructuralPartialEq for Config