1use 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#[derive(Clone, Copy, Debug, Eq, PartialEq)]
33pub enum ConfigSearch {
34 ExplicitOnly,
35 WellKnown,
36}
37
38#[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 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 #[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 pub fn exit_code(&self) -> i32 {
89 match self {
90 Self::Sources(error) => error.exit_code(),
91 _ => 2,
92 }
93 }
94}
95
96#[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 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 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 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 pub fn environment_warnings<T: Conf>(&self, env: &[(OsString, OsString)]) -> Vec<String> {
213 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 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
259pub 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
266pub 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;