rocket/config/mod.rs
1//! Server and application configuration.
2//!
3//! See the [configuration guide] for full details.
4//!
5//! [configuration guide]: https://rocket.rs/master/guide/configuration/
6//!
7//! ## Extracting Configuration Parameters
8//!
9//! Rocket exposes the active [`Figment`] via [`Rocket::figment()`]. Any value
10//! that implements [`Deserialize`] can be extracted from the figment:
11//!
12//! ```rust
13//! use rocket::fairing::AdHoc;
14//!
15//! #[derive(serde::Deserialize)]
16//! struct AppConfig {
17//! id: Option<usize>,
18//! port: u16,
19//! }
20//!
21//! #[rocket::launch]
22//! fn rocket() -> _ {
23//! rocket::build().attach(AdHoc::config::<AppConfig>())
24//! }
25//! ```
26//!
27//! [`Figment`]: figment::Figment
28//! [`Rocket::figment()`]: crate::Rocket::figment()
29//! [`Rocket::figment()`]: crate::Rocket::figment()
30//! [`Deserialize`]: serde::Deserialize
31//!
32//! ## Workers
33//!
34//! The `workers` parameter sets the number of threads used for parallel task
35//! execution; there is no limit to the number of concurrent tasks. Due to a
36//! limitation in upstream async executers, unlike other values, the `workers`
37//! configuration value cannot be reconfigured or be configured from sources
38//! other than those provided by [`Config::figment()`]. In other words, only the
39//! values set by the `ROCKET_WORKERS` environment variable or in the `workers`
40//! property of `Rocket.toml` will be considered - all other `workers` values
41//! are ignored.
42//!
43//! ## Custom Providers
44//!
45//! A custom provider can be set via [`rocket::custom()`], which replaces calls to
46//! [`rocket::build()`]. The configured provider can be built on top of
47//! [`Config::figment()`], [`Config::default()`], both, or neither. The
48//! [Figment](figment) documentation has full details on instantiating existing
49//! providers like [`Toml`]() and [`Env`] as well as creating custom providers for
50//! more complex cases.
51//!
52//! Configuration values can be overridden at runtime by merging figment's tuple
53//! providers with Rocket's default provider:
54//!
55//! ```rust
56//! # #[macro_use] extern crate rocket;
57//! use rocket::data::{Limits, ToByteUnit};
58//!
59//! #[launch]
60//! fn rocket() -> _ {
61//! let figment = rocket::Config::figment()
62//! .merge(("port", 1111))
63//! .merge(("limits", Limits::new().limit("json", 2.mebibytes())));
64//!
65//! rocket::custom(figment).mount("/", routes![/* .. */])
66//! }
67//! ```
68//!
69//! An application that wants to use Rocket's defaults for [`Config`], but not
70//! its configuration sources, while allowing the application to be configured
71//! via an `App.toml` file that uses top-level keys as profiles (`.nested()`)
72//! and `APP_` environment variables as global overrides (`.global()`), and
73//! `APP_PROFILE` to configure the selected profile, can be structured as
74//! follows:
75//!
76//! ```rust
77//! # #[macro_use] extern crate rocket;
78//! use serde::{Serialize, Deserialize};
79//! use figment::{Figment, Profile, providers::{Format, Toml, Serialized, Env}};
80//! use rocket::fairing::AdHoc;
81//!
82//! #[derive(Debug, Deserialize, Serialize)]
83//! struct Config {
84//! app_value: usize,
85//! /* and so on.. */
86//! }
87//!
88//! impl Default for Config {
89//! fn default() -> Config {
90//! Config { app_value: 3, }
91//! }
92//! }
93//!
94//! #[launch]
95//! fn rocket() -> _ {
96//! let figment = Figment::from(rocket::Config::default())
97//! .merge(Serialized::defaults(Config::default()))
98//! .merge(Toml::file("App.toml").nested())
99//! .merge(Env::prefixed("APP_").global())
100//! .select(Profile::from_env_or("APP_PROFILE", "default"));
101//!
102//! rocket::custom(figment)
103//! .mount("/", routes![/* .. */])
104//! .attach(AdHoc::config::<Config>())
105//! }
106//! ```
107//!
108//! [`rocket::custom()`]: crate::custom()
109//! [`rocket::build()`]: crate::build()
110//! [`Toml`]: figment::providers::Toml
111//! [`Env`]: figment::providers::Env
112
113#[macro_use]
114mod ident;
115mod config;
116mod cli_colors;
117mod http_header;
118#[cfg(test)]
119mod tests;
120
121pub use ident::Ident;
122pub use config::Config;
123pub use cli_colors::CliColors;
124
125pub use crate::trace::{TraceFormat, Level};
126pub use crate::shutdown::ShutdownConfig;
127
128#[cfg(feature = "tls")]
129pub use crate::tls::TlsConfig;
130
131#[cfg(feature = "mtls")]
132pub use crate::mtls::MtlsConfig;
133
134#[cfg(feature = "secrets")]
135mod secret_key;
136
137#[cfg(unix)]
138pub use crate::shutdown::Sig;
139
140#[cfg(feature = "secrets")]
141pub use secret_key::SecretKey;