Skip to main content

rushls_common/config/
mod.rs

1//! One loading contract for application-owned `conf::Conf` schemas.
2//!
3//! Values resolve as defaults < TOML < environment < CLI. Loading never changes
4//! the process environment or constructs application services. Schema derives
5//! supply field names, parsing, help, and secret-aware diagnostics.
6
7use conf::{
8    Conf, ConfSerde,
9    introspection::{ConfigEvent, ValueSource},
10};
11use std::{
12    collections::{BTreeMap, BTreeSet},
13    ffi::OsString,
14    path::{Path, PathBuf},
15};
16use thiserror::Error;
17
18pub mod example;
19pub mod interpolate;
20pub mod reference;
21mod secret;
22mod values;
23pub use bytesize::ByteSize;
24pub use humantime::parse_duration;
25pub use secret::{SecretString, TextSource, deserialize_secret};
26pub use values::{
27    OptionalAddress, OptionalBytes, OptionalDuration, TomlTable, TomlValue, parse_optional_address,
28    parse_optional_bytes, parse_optional_duration, read_credential,
29};
30
31/// Tests use explicit paths so developer files cannot change their defaults.
32#[derive(Clone, Copy, Debug, Eq, PartialEq)]
33pub enum ConfigSearch {
34    ExplicitOnly,
35    WellKnown,
36}
37
38/// Metadata only: configuration values, including credentials, are never kept.
39#[derive(Clone, Debug, Eq, PartialEq)]
40pub enum Source {
41    Default,
42    Cli,
43    Environment(String),
44    File(String),
45    Other,
46}
47
48pub struct Loaded<T> {
49    pub config: T,
50    pub path: Option<PathBuf>,
51    pub sources: BTreeMap<String, Source>,
52    /// Nonfatal diagnostics, containing variable names but never their values.
53    pub warnings: Vec<String>,
54}
55
56#[derive(Debug, Error)]
57pub enum ConfigError {
58    #[error("could not read configuration file {path}: {source}")]
59    Read {
60        path: PathBuf,
61        source: std::io::Error,
62    },
63    // Parser source text can contain credentials. Keep syntax diagnostics but
64    // never display the source line, including through Debug or error chains.
65    #[error("invalid TOML in {path} at byte {offset}: {message}")]
66    Toml {
67        path: PathBuf,
68        offset: usize,
69        message: String,
70    },
71    #[error("could not interpolate {path}: {source}")]
72    Interpolation {
73        path: PathBuf,
74        source: interpolate::InterpolationError,
75    },
76    #[error(transparent)]
77    Sources(#[from] conf::Error),
78    #[error("could not read {secret} from {path}: {source}")]
79    SecretRead {
80        secret: String,
81        path: PathBuf,
82        source: std::io::Error,
83    },
84}
85
86impl ConfigError {
87    /// Help and version use exit status zero. Startup errors use status two.
88    pub fn exit_code(&self) -> i32 {
89        match self {
90            Self::Sources(error) => error.exit_code(),
91            _ => 2,
92        }
93    }
94}
95
96/// The application selects its namespace and schema; the loader owns sources.
97#[derive(Clone, Copy, Debug)]
98pub struct Loader {
99    pub name: &'static str,
100    pub env_prefix: &'static str,
101    pub search: ConfigSearch,
102}
103
104impl Loader {
105    pub const fn new(name: &'static str, env_prefix: &'static str) -> Self {
106        Self {
107            name,
108            env_prefix,
109            search: ConfigSearch::WellKnown,
110        }
111    }
112
113    pub const fn explicit_only(mut self) -> Self {
114        self.search = ConfigSearch::ExplicitOnly;
115        self
116    }
117
118    pub fn load<T: ConfSerde>(&self) -> Result<Loaded<T>, ConfigError> {
119        self.load_from(std::env::args_os(), std::env::vars_os())
120    }
121
122    /// Uses a snapshot so parsing and interpolation see exactly the same inputs.
123    pub fn load_from<T: ConfSerde>(
124        &self,
125        args: impl IntoIterator<Item = impl Into<OsString>>,
126        env: impl IntoIterator<Item = (impl Into<OsString>, impl Into<OsString>)>,
127    ) -> Result<Loaded<T>, ConfigError> {
128        let args: Vec<OsString> = args.into_iter().map(Into::into).collect();
129        let env: Vec<(OsString, OsString)> =
130            env.into_iter().map(|(k, v)| (k.into(), v.into())).collect();
131        // Help remains usable even when the configured file or environment is
132        // broken. The actual parser decides whether a token is a help request.
133        if args
134            .iter()
135            .skip(1)
136            .take_while(|arg| *arg != "--")
137            .any(|arg| matches!(arg.to_str(), Some("--help" | "-h" | "--version" | "-V")))
138            && let Err(error) = T::conf_builder()
139                .args(args.clone())
140                .env(Vec::<(OsString, OsString)>::new())
141                .try_parse()
142            && error.exit_code() == 0
143        {
144            return Err(error.into());
145        }
146        let warnings = self.environment_warnings::<T>(&env);
147        let config_env = format!("{}CONFIG", self.env_prefix);
148        let path = conf::find_parameter("config", args.iter().cloned())
149            .map(PathBuf::from)
150            .or_else(|| {
151                env.iter()
152                    .rev()
153                    .find(|(key, _)| key == config_env.as_str())
154                    .map(|(_, value)| PathBuf::from(value))
155            })
156            .or_else(|| match self.search {
157                ConfigSearch::ExplicitOnly => None,
158                ConfigSearch::WellKnown => {
159                    self.config_paths().into_iter().find(|path| path.is_file())
160                }
161            });
162        let mut sources = BTreeMap::new();
163        let record = |event: &dyn ConfigEvent| {
164            let source = match event.value_source() {
165                ValueSource::Args { .. } => Source::Cli,
166                ValueSource::Env { var, .. } => Source::Environment(var.to_string()),
167                ValueSource::Document { name, .. } => Source::File(name.to_string()),
168                ValueSource::Default { .. } => Source::Default,
169                _ => Source::Other,
170            };
171            sources.insert(event.program_option().id().to_string(), source);
172        };
173        let builder = T::conf_builder()
174            .args(args)
175            .env(env.clone())
176            .config_logger(record);
177        let config = match &path {
178            Some(path) => {
179                let text = std::fs::read_to_string(path).map_err(|source| ConfigError::Read {
180                    path: path.clone(),
181                    source,
182                })?;
183                let mut document: toml::Value =
184                    toml::from_str(&text).map_err(|error: toml::de::Error| ConfigError::Toml {
185                        path: path.clone(),
186                        offset: error.span().map_or(0, |span| span.start),
187                        // Generic syntax text can include a duplicate key chosen by
188                        // the input. Values and whole source lines are not retained.
189                        message: error.message().to_owned(),
190                    })?;
191                interpolate::Environment::new(env)
192                    .interpolate(&mut document)
193                    .map_err(|source| ConfigError::Interpolation {
194                        path: path.clone(),
195                        source,
196                    })?;
197                builder
198                    .doc(path.display().to_string(), document)
199                    .try_parse()?
200            }
201            None => builder.try_parse()?,
202        };
203        Ok(Loaded {
204            config,
205            path,
206            sources,
207            warnings,
208        })
209    }
210
211    /// Warns about unknown names in this application's namespace, in stable order.
212    pub fn environment_warnings<T: Conf>(&self, env: &[(OsString, OsString)]) -> Vec<String> {
213        // The public introspection view omits aliases. Use the same generated
214        // option metadata as conf's parser so accepted aliases do not produce warnings.
215        let mut known = BTreeSet::new();
216        for option in T::PROGRAM_OPTIONS.iter() {
217            known.extend(
218                option
219                    .env_form
220                    .iter()
221                    .chain(option.env_aliases.iter())
222                    .map(ToString::to_string),
223            );
224        }
225        let unknown: BTreeSet<String> = env
226            .iter()
227            .map(|(key, _)| key.to_string_lossy().into_owned())
228            .filter(|key| key.starts_with(self.env_prefix) && !known.contains(key))
229            .collect();
230        unknown.into_iter()
231            .map(|name| format!("unrecognized environment variable {name} is ignored as a configuration override"))
232            .collect()
233    }
234
235    /// Discovery order is working directory, local config, roaming config,
236    /// then, on Unix, the system-wide `/etc/<name>/<name>.toml` where a
237    /// packaged service conventionally keeps it.
238    pub fn config_paths(&self) -> Vec<PathBuf> {
239        let filename = format!("{}.toml", self.name);
240        let mut paths = Vec::new();
241        if let Ok(cwd) = std::env::current_dir() {
242            paths.push(cwd.join(&filename));
243        }
244        if let Some(dirs) = directories::ProjectDirs::from("", "", self.name) {
245            for directory in [dirs.config_local_dir(), dirs.config_dir()] {
246                let path = directory.join(&filename);
247                if !paths.contains(&path) {
248                    paths.push(path);
249                }
250            }
251        }
252        if cfg!(unix) {
253            paths.push(Path::new("/etc").join(self.name).join(&filename));
254        }
255        paths
256    }
257}
258
259/// The same byte-size spelling for environment variables and CLI arguments.
260pub fn parse_bytes(value: &str) -> Result<usize, String> {
261    let bytes: ByteSize = value.parse()?;
262    usize::try_from(bytes.as_u64())
263        .map_err(|_| "byte size exceeds this platform's address space".into())
264}
265
266/// TOML can use an integer byte count or the human-readable CLI spelling.
267pub fn deserialize_bytes<'de, D: serde::Deserializer<'de>>(
268    deserializer: D,
269) -> Result<usize, D::Error> {
270    #[derive(serde::Deserialize)]
271    #[serde(untagged)]
272    enum Bytes {
273        Count(usize),
274        Text(String),
275    }
276    match <Bytes as serde::Deserialize>::deserialize(deserializer)? {
277        Bytes::Count(value) => Ok(value),
278        Bytes::Text(value) => parse_bytes(&value).map_err(serde::de::Error::custom),
279    }
280}
281
282#[cfg(test)]
283mod tests;