Skip to main content

rustango_cms/
config.rs

1//! Process configuration from the environment.
2//!
3//! Every setting the CMS reads is named here, under one prefix, `RCMS_`.
4//! Earlier releases used three (`RCMS_`, `CMS_`, `RUSTANGO_CMS_`), so an
5//! operator who wrote `RCMS_MEDIA_BACKEND` silently got local disk; the old
6//! spellings are still read, after the canonical one.
7//!
8//! | Setting | Purpose |
9//! |---|---|
10//! | `RCMS_SECRET_KEY` | Signs preview tokens, password-reset links and other CMS artifacts; generated into `./var/.rustango_cms_signing.key` when unset |
11//! | `RCMS_RENDITION_SIGNING_KEY` | Signs image rendition URLs |
12//! | `RCMS_API_CORS_ORIGINS` | Origins allowed to call `/api/v2` |
13//! | `RCMS_MEDIA_BACKEND` | `local` (default), `memory` or `s3` |
14//! | `RCMS_MEDIA_CDN_BASE` | Base URL [`crate::media_storage::public_url`] returns for stored objects (`s3`/`memory` backends). Pages the CMS renders keep serving media through `/__media__/…` with year-long immutable caching, so a CDN in front of the site caches them |
15//! | `RCMS_MEDIA_TENANT_BUCKETS` / `RCMS_MEDIA_TENANT_CDNS` | Per-tenant S3 buckets / CDNs, `slug=value,…` |
16//! | `RCMS_S3_BUCKET`, `_REGION`, `_ENDPOINT`, `_ACCESS_KEY_ID`, `_SECRET_ACCESS_KEY`, `_PATH_STYLE` | S3 media backend |
17//! | `RCMS_SITE_HOST_SUFFIXES` | Domains a tenant may add hostnames under without approval |
18//! | `RCMS_DEFAULT_TIMEZONE` | Admin timezone when a user has none |
19//! | `RCMS_DEFAULT_ADMIN_LOCALE` | Admin language when a user has none |
20//! | `RCMS_PERF_LOG` | `1` / `true` logs per-phase render timings |
21//! | `RCMS_NOTIFY_ALLOW_PRIVATE` | `1` lets notification channels deliver to private-network addresses |
22//!
23//! Cache and search backends keep their providers' own variable names
24//! (`CLOUDFLARE_API_TOKEN`, …), documented with each backend.
25//!
26//! The framework's own `RUSTANGO_SECRET_KEY` is needed too: it encrypts
27//! stored secrets such as notification-target tokens. Without it no
28//! notification target can be saved — the CMS logs a warning and a form's
29//! email recipients get nothing.
30
31/// The value of setting `name` — given without its prefix, e.g.
32/// `"MEDIA_BACKEND"` — read as `RCMS_<name>`, then the legacy
33/// `CMS_<name>` and `RUSTANGO_CMS_<name>`. An empty value counts as unset.
34#[must_use]
35pub fn var(name: &str) -> Option<String> {
36    var_in(name, |key| std::env::var(key).ok())
37}
38
39/// [`var`] over any lookup, so the prefix order is testable without
40/// touching the process environment.
41fn var_in(name: &str, lookup: impl Fn(&str) -> Option<String>) -> Option<String> {
42    ["RCMS_", "CMS_", "RUSTANGO_CMS_"]
43        .iter()
44        .find_map(|prefix| lookup(&format!("{prefix}{name}")).filter(|v| !v.trim().is_empty()))
45}
46
47/// `true` when setting `name` is `1` or `true`.
48#[must_use]
49pub fn flag(name: &str) -> bool {
50    matches!(var(name).as_deref().map(str::trim), Some("1" | "true"))
51}
52
53#[cfg(test)]
54mod tests {
55    use super::var_in;
56    use std::collections::HashMap;
57
58    fn env(pairs: &[(&str, &str)]) -> impl Fn(&str) -> Option<String> {
59        let m: HashMap<String, String> =
60            pairs.iter().map(|(k, v)| ((*k).to_owned(), (*v).to_owned())).collect();
61        move |k| m.get(k).cloned()
62    }
63
64    #[test]
65    fn the_canonical_name_wins_and_old_names_still_work() {
66        let both = env(&[("RCMS_MEDIA_BACKEND", "s3"), ("CMS_MEDIA_BACKEND", "local")]);
67        assert_eq!(var_in("MEDIA_BACKEND", both).as_deref(), Some("s3"));
68        let legacy = env(&[("CMS_MEDIA_BACKEND", "s3")]);
69        assert_eq!(var_in("MEDIA_BACKEND", legacy).as_deref(), Some("s3"));
70        let oldest = env(&[("RUSTANGO_CMS_DEFAULT_TIMEZONE", "Europe/Kyiv")]);
71        assert_eq!(var_in("DEFAULT_TIMEZONE", oldest).as_deref(), Some("Europe/Kyiv"));
72    }
73
74    #[test]
75    fn an_empty_value_is_unset() {
76        let e = env(&[("RCMS_SECRET_KEY", "  "), ("CMS_SECRET_KEY", "real")]);
77        assert_eq!(var_in("SECRET_KEY", e).as_deref(), Some("real"));
78        assert_eq!(var_in("SECRET_KEY", env(&[])), None);
79    }
80}