laterite_core/
config.rs

1//! Layered configuration loading.
2
3use std::path::Path;
4
5use config::{Config, Environment, File};
6use serde::de::DeserializeOwned;
7use serde::Deserialize;
8
9use crate::error::{CoreError, CoreResult};
10
11/// Database connection settings.
12#[derive(Debug, Clone, Deserialize)]
13pub struct DatabaseConfig {
14    pub url: String,
15    #[serde(default = "default_max_connections")]
16    pub max_connections: u32,
17    #[serde(default = "default_acquire_timeout_secs")]
18    pub acquire_timeout_secs: u64,
19}
20
21/// HTTP listener settings.
22#[derive(Debug, Clone, Deserialize)]
23pub struct ServerConfig {
24    #[serde(default = "default_listen")]
25    pub listen: String,
26}
27
28/// Application-level metadata. The `name` is the human-readable application
29/// name, the baseline for the admin brand: a `BrandSetting` in the admin can
30/// override it, but this is the default when none is set.
31///
32/// Non-exhaustive: build one with [`Default`] and set fields, so a field added
33/// in a later release is additive.
34#[derive(Debug, Clone, Deserialize)]
35#[serde(default)]
36#[non_exhaustive]
37pub struct AppMeta {
38    /// The display name of the application (e.g. `"Acme Blog"`). Shown as the
39    /// admin brand unless overridden by a brand setting.
40    pub name: String,
41    /// The application's public base URL (scheme and host, with any port), such
42    /// as `https://acme.example`. It is the canonical origin absolute links build
43    /// on, distinct from the server bind address (they differ behind a proxy or a
44    /// local `.test` domain). When unset, [`base_url`] derives it from the bind
45    /// address.
46    pub url: Option<String>,
47    /// The application's default locale (BCP 47, e.g. `"en"`): the deployment
48    /// default for UI-string translation, the last stop in a request's locale
49    /// chain before the English source when neither the operator's preference nor
50    /// the request's `Accept-Language` resolves.
51    pub locale: String,
52    /// Debug mode: error pages include the internal cause. Off by default;
53    /// enable only in development. Read via [`debug`] where request context is
54    /// not available (error rendering).
55    pub debug: bool,
56    /// The prefix of the environment variables that override this configuration
57    /// (`<PREFIX>__SECTION__KEY`). Declared here so the application and the `lat`
58    /// command agree on it; unset means the framework default. Read from the files
59    /// alone by [`declared_env_prefix`], since it selects the environment layer.
60    pub env_prefix: Option<String>,
61}
62
63impl Default for AppMeta {
64    fn default() -> Self {
65        Self {
66            name: "Laterite".to_string(),
67            url: None,
68            locale: "en".to_string(),
69            debug: false,
70            env_prefix: None,
71        }
72    }
73}
74
75/// Records whether the deployment is in debug mode, once, at boot from the loaded
76/// config. Later calls are ignored (the first wins), so error rendering has a
77/// stable answer without threading config through every handler.
78pub fn set_debug(on: bool) {
79    let _ = DEBUG.set(on);
80}
81
82/// Whether the deployment is in debug mode (default `false` until [`set_debug`]).
83pub fn debug() -> bool {
84    *DEBUG.get().unwrap_or(&false)
85}
86
87static DEBUG: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
88
89/// The application's public base URL, without a trailing slash: the configured
90/// `url` when set and non-empty, otherwise derived from the server bind address
91/// as `http://<listen>`. A wildcard bind host (`0.0.0.0` or `[::]`) is shown via
92/// loopback so the result is browsable. Absolute links (the admin URL in the
93/// startup banner, and later notifications and share cards) build on this.
94pub fn base_url(url: Option<&str>, listen: &str) -> String {
95    match url.map(str::trim).filter(|u| !u.is_empty()) {
96        Some(url) => url.trim_end_matches('/').to_string(),
97        None => format!("http://{}", browsable_host(listen)),
98    }
99}
100
101/// Rewrites a wildcard bind host to a loopback address so a bind string like
102/// `0.0.0.0:8080` yields a URL a browser can actually open.
103fn browsable_host(listen: &str) -> String {
104    if let Some(port) = listen.strip_prefix("0.0.0.0") {
105        format!("127.0.0.1{port}")
106    } else if let Some(port) = listen.strip_prefix("[::]") {
107        format!("[::1]{port}")
108    } else {
109        listen.to_string()
110    }
111}
112
113/// Deployment-level backend settings. Per-install brand and per-operator preferences
114/// live in the settings and preferences stores, not here.
115///
116/// Non-exhaustive: build one with [`Default`] and set fields, so a field added
117/// in a later release is additive.
118#[derive(Debug, Clone, Deserialize)]
119#[serde(default)]
120#[non_exhaustive]
121pub struct BackendConfig {
122    /// Set the `Secure` attribute on the admin session cookie. Enable behind HTTPS
123    /// in production; leave off for plain-HTTP local development.
124    pub secure_cookie: bool,
125    /// The default display timezone for the admin (an IANA name like
126    /// `Asia/Kolkata`). Storage is always UTC; this only affects how dates render.
127    /// An operator's own preference overrides it (later); it falls back to UTC.
128    pub timezone: String,
129    /// Admin path overrides, keyed by module id (`"rainmill.location"`) or by a
130    /// module id and one contribution's declared path
131    /// (`"rainmill.location/nodes"`), the more specific winning. Values are
132    /// absolute under the admin mount, so they survive a relocated panel. Lets a
133    /// deployment move a plugin's screens without forking it.
134    pub paths: std::collections::BTreeMap<String, String>,
135    /// The URL path the admin panel is mounted under, without a trailing slash
136    /// (default `/admin`). Change it to move or obscure the panel (`/manage`,
137    /// `/backend`). A leading slash is added if missing and a trailing slash is
138    /// stripped; an empty value falls back to `/admin`.
139    pub path: String,
140}
141
142impl Default for BackendConfig {
143    fn default() -> Self {
144        Self {
145            secure_cookie: false,
146            timezone: "UTC".to_string(),
147            paths: std::collections::BTreeMap::new(),
148            path: "/admin".to_string(),
149        }
150    }
151}
152
153fn default_max_connections() -> u32 {
154    10
155}
156
157fn default_acquire_timeout_secs() -> u64 {
158    5
159}
160
161fn default_listen() -> String {
162    "127.0.0.1:8080".to_string()
163}
164
165/// Loads a layered configuration into any deserializable type.
166///
167/// Layers, later overriding earlier:
168/// 1. `<dir>/default.toml` (required)
169/// 2. `<dir>/<APP_ENV>.toml` (optional; `APP_ENV` defaults to `development`)
170/// 3. `<dir>/local.toml` (optional, git-ignored developer overrides)
171/// 4. Environment variables `<PREFIX>__SECTION__KEY` (e.g. `LAT__DATABASE__URL`);
172///    the prefix an application declares as `app.env_prefix` is read with
173///    [`declared_env_prefix`] and passed here.
174pub fn load<T: DeserializeOwned>(dir: &Path, env_prefix: &str) -> CoreResult<T> {
175    file_layers(dir)
176        .add_source(
177            Environment::with_prefix(env_prefix)
178                .prefix_separator("__")
179                .separator("__"),
180        )
181        .build()
182        .and_then(Config::try_deserialize)
183        .map_err(|e| CoreError::Config(e.to_string()))
184}
185
186/// The environment-variable prefix a configuration declares as `app.env_prefix`,
187/// read from the files alone: it selects the environment layer, so it cannot come
188/// from there. `None` when undeclared or blank, meaning the framework default.
189pub fn declared_env_prefix(dir: &Path) -> CoreResult<Option<String>> {
190    #[derive(Deserialize)]
191    struct Declared {
192        #[serde(default)]
193        app: DeclaredApp,
194    }
195    #[derive(Deserialize, Default)]
196    struct DeclaredApp {
197        env_prefix: Option<String>,
198    }
199    let declared: Declared = file_layers(dir)
200        .build()
201        .and_then(Config::try_deserialize)
202        .map_err(|e| CoreError::Config(e.to_string()))?;
203    Ok(declared
204        .app
205        .env_prefix
206        .map(|prefix| prefix.trim().to_string())
207        .filter(|prefix| !prefix.is_empty()))
208}
209
210/// The file layers of a config directory, in override order: `default.toml`
211/// (required), `<APP_ENV>.toml`, then `local.toml`.
212fn file_layers(dir: &Path) -> config::ConfigBuilder<config::builder::DefaultState> {
213    let app_env = std::env::var("APP_ENV").unwrap_or_else(|_| "development".into());
214    Config::builder()
215        .add_source(File::from(dir.join("default.toml")).required(true))
216        .add_source(File::from(dir.join(format!("{app_env}.toml"))).required(false))
217        .add_source(File::from(dir.join("local.toml")).required(false))
218}
219
220#[cfg(test)]
221mod tests {
222    use super::*;
223
224    #[derive(Deserialize)]
225    struct TestConfig {
226        server: ServerConfig,
227        database: DatabaseConfig,
228    }
229
230    #[test]
231    fn loads_defaults_env_overrides_and_serde_defaults() {
232        let dir = tempfile::tempdir().unwrap();
233        std::fs::write(
234            dir.path().join("default.toml"),
235            "[server]\nlisten = \"0.0.0.0:9999\"\n\n[database]\nurl = \"postgres://from-file\"\n",
236        )
237        .unwrap();
238        std::env::set_var("LATERITE_TEST__DATABASE__URL", "postgres://from-env");
239        let cfg: TestConfig = load(dir.path(), "LATERITE_TEST").unwrap();
240        std::env::remove_var("LATERITE_TEST__DATABASE__URL");
241        assert_eq!(cfg.server.listen, "0.0.0.0:9999");
242        assert_eq!(cfg.database.url, "postgres://from-env");
243        assert_eq!(cfg.database.max_connections, 10);
244        assert_eq!(cfg.database.acquire_timeout_secs, 5);
245    }
246
247    #[test]
248    fn backend_config_defaults_and_loads() {
249        #[derive(Deserialize)]
250        struct C {
251            #[serde(default)]
252            backend: BackendConfig,
253        }
254        let dir = tempfile::tempdir().unwrap();
255        std::fs::write(dir.path().join("default.toml"), "").unwrap();
256        let c: C = load(dir.path(), "LATERITE_BE_NONE").unwrap();
257        assert!(!c.backend.secure_cookie);
258        assert_eq!(c.backend.timezone, "UTC");
259
260        std::fs::write(
261            dir.path().join("default.toml"),
262            "[backend]\nsecure_cookie = true\ntimezone = \"Asia/Kolkata\"\n",
263        )
264        .unwrap();
265        let c: C = load(dir.path(), "LATERITE_BE_SET").unwrap();
266        assert!(c.backend.secure_cookie);
267        assert_eq!(c.backend.timezone, "Asia/Kolkata");
268    }
269
270    #[test]
271    fn declared_env_prefix_comes_from_the_files_alone() {
272        let dir = tempfile::tempdir().unwrap();
273        std::fs::write(dir.path().join("default.toml"), "[app]\nname = \"Acme\"\n").unwrap();
274        assert_eq!(declared_env_prefix(dir.path()).unwrap(), None);
275        std::fs::write(
276            dir.path().join("default.toml"),
277            "[app]\nenv_prefix = \"ACME\"\n",
278        )
279        .unwrap();
280        assert_eq!(
281            declared_env_prefix(dir.path()).unwrap().as_deref(),
282            Some("ACME")
283        );
284        // local.toml overrides it, and a blank value counts as undeclared.
285        std::fs::write(
286            dir.path().join("local.toml"),
287            "[app]\nenv_prefix = \"  \"\n",
288        )
289        .unwrap();
290        assert_eq!(declared_env_prefix(dir.path()).unwrap(), None);
291    }
292
293    #[test]
294    fn base_url_prefers_config_then_derives_from_listen() {
295        // Configured URL wins and loses any trailing slash.
296        assert_eq!(
297            base_url(Some("https://acme.example/"), "127.0.0.1:8080"),
298            "https://acme.example"
299        );
300        // Blank configured URL falls through to the derived form.
301        assert_eq!(
302            base_url(Some("  "), "127.0.0.1:9000"),
303            "http://127.0.0.1:9000"
304        );
305        // No URL: derive from the bind address.
306        assert_eq!(base_url(None, "127.0.0.1:8080"), "http://127.0.0.1:8080");
307        // A wildcard bind host is shown via loopback so the URL is browsable.
308        assert_eq!(base_url(None, "0.0.0.0:8080"), "http://127.0.0.1:8080");
309        assert_eq!(base_url(None, "[::]:8080"), "http://[::1]:8080");
310    }
311
312    #[test]
313    fn missing_default_file_is_a_config_error() {
314        let dir = tempfile::tempdir().unwrap();
315        let result: CoreResult<TestConfig> = load(dir.path(), "LATERITE_TEST_MISSING");
316        assert!(matches!(result, Err(CoreError::Config(_))));
317    }
318}
laterite_core/config.rs

laterite_core/
config.rs
