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` | Requires a signature on every image rendition URL (CMS-rendered URLs are signed either way) |
12//! | `RCMS_RENDITION_MAX_UNSIGNED` | Without a signing key, the most sizes unsigned anonymous requests can create per image (default 128) |
13//! | `RCMS_API_CORS_ORIGINS` | Origins allowed to call `/api/v2` |
14//! | `RCMS_MEDIA_BACKEND` | `local` (default), `memory` or `s3` |
15//! | `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 |
16//! | `RCMS_MEDIA_TENANT_BUCKETS` / `RCMS_MEDIA_TENANT_CDNS` | Per-tenant S3 buckets / CDNs, `slug=value,…` |
17//! | `RCMS_S3_BUCKET`, `_REGION`, `_ENDPOINT`, `_ACCESS_KEY_ID`, `_SECRET_ACCESS_KEY`, `_PATH_STYLE` | S3 media backend |
18//! | `RCMS_SITE_HOST_SUFFIXES` | Domains a tenant may add hostnames under without approval |
19//! | `RCMS_DEFAULT_TIMEZONE` | Admin timezone when a user has none |
20//! | `RCMS_DEFAULT_ADMIN_LOCALE` | Admin language when a user has none |
21//! | `RCMS_PERF_LOG` | `1` / `true` logs per-phase render timings |
22//! | `RCMS_NOTIFY_ALLOW_PRIVATE` | `1` lets notification channels deliver to private-network addresses |
23//!
24//! Cache and search backends keep their providers' own variable names
25//! (`CLOUDFLARE_API_TOKEN`, …), documented with each backend.
26//!
27//! The framework's own `RUSTANGO_SECRET_KEY` is needed too: it encrypts
28//! stored secrets such as notification-target tokens. Without it no
29//! notification target can be saved — the CMS logs a warning and a form's
30//! email recipients get nothing.
31
32/// The value of setting `name` — given without its prefix, e.g.
33/// `"MEDIA_BACKEND"` — read as `RCMS_<name>`, then the legacy
34/// `CMS_<name>` and `RUSTANGO_CMS_<name>`. An empty value counts as unset.
35#[must_use]
36pub fn var(name: &str) -> Option<String> {
37    var_in(name, |key| std::env::var(key).ok())
38}
39
40/// [`var`] over any lookup, so the prefix order is testable without
41/// touching the process environment.
42fn var_in(name: &str, lookup: impl Fn(&str) -> Option<String>) -> Option<String> {
43    ["RCMS_", "CMS_", "RUSTANGO_CMS_"]
44        .iter()
45        .find_map(|prefix| lookup(&format!("{prefix}{name}")).filter(|v| !v.trim().is_empty()))
46}
47
48/// `true` when setting `name` is `1` or `true`.
49#[must_use]
50pub fn flag(name: &str) -> bool {
51    matches!(var(name).as_deref().map(str::trim), Some("1" | "true"))
52}
53
54#[cfg(test)]
55mod tests {
56    use super::var_in;
57    use std::collections::HashMap;
58
59    fn env(pairs: &[(&str, &str)]) -> impl Fn(&str) -> Option<String> {
60        let m: HashMap<String, String> =
61            pairs.iter().map(|(k, v)| ((*k).to_owned(), (*v).to_owned())).collect();
62        move |k| m.get(k).cloned()
63    }
64
65    #[test]
66    fn the_canonical_name_wins_and_old_names_still_work() {
67        let both = env(&[("RCMS_MEDIA_BACKEND", "s3"), ("CMS_MEDIA_BACKEND", "local")]);
68        assert_eq!(var_in("MEDIA_BACKEND", both).as_deref(), Some("s3"));
69        let legacy = env(&[("CMS_MEDIA_BACKEND", "s3")]);
70        assert_eq!(var_in("MEDIA_BACKEND", legacy).as_deref(), Some("s3"));
71        let oldest = env(&[("RUSTANGO_CMS_DEFAULT_TIMEZONE", "Europe/Kyiv")]);
72        assert_eq!(var_in("DEFAULT_TIMEZONE", oldest).as_deref(), Some("Europe/Kyiv"));
73    }
74
75    #[test]
76    fn an_empty_value_is_unset() {
77        let e = env(&[("RCMS_SECRET_KEY", "  "), ("CMS_SECRET_KEY", "real")]);
78        assert_eq!(var_in("SECRET_KEY", e).as_deref(), Some("real"));
79        assert_eq!(var_in("SECRET_KEY", env(&[])), None);
80    }
81}