use conf::{
Conf, ConfSerde,
introspection::{ConfigEvent, ValueSource},
};
use std::{
collections::{BTreeMap, BTreeSet},
ffi::OsString,
path::{Path, PathBuf},
};
use thiserror::Error;
pub mod example;
pub mod interpolate;
pub mod reference;
mod secret;
mod values;
pub use bytesize::ByteSize;
pub use humantime::parse_duration;
pub use secret::{SecretString, TextSource, deserialize_secret};
pub use values::{
OptionalAddress, OptionalBytes, OptionalDuration, TomlTable, TomlValue, parse_optional_address,
parse_optional_bytes, parse_optional_duration, read_credential,
};
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ConfigSearch {
ExplicitOnly,
WellKnown,
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum Source {
Default,
Cli,
Environment(String),
File(String),
Other,
}
pub struct Loaded<T> {
pub config: T,
pub path: Option<PathBuf>,
pub sources: BTreeMap<String, Source>,
pub warnings: Vec<String>,
}
#[derive(Debug, Error)]
pub enum ConfigError {
#[error("could not read configuration file {path}: {source}")]
Read {
path: PathBuf,
source: std::io::Error,
},
#[error("invalid TOML in {path} at byte {offset}: {message}")]
Toml {
path: PathBuf,
offset: usize,
message: String,
},
#[error("could not interpolate {path}: {source}")]
Interpolation {
path: PathBuf,
source: interpolate::InterpolationError,
},
#[error(transparent)]
Sources(#[from] conf::Error),
#[error("could not read {secret} from {path}: {source}")]
SecretRead {
secret: String,
path: PathBuf,
source: std::io::Error,
},
}
impl ConfigError {
pub fn exit_code(&self) -> i32 {
match self {
Self::Sources(error) => error.exit_code(),
_ => 2,
}
}
}
#[derive(Clone, Copy, Debug)]
pub struct Loader {
pub name: &'static str,
pub env_prefix: &'static str,
pub search: ConfigSearch,
}
impl Loader {
pub const fn new(name: &'static str, env_prefix: &'static str) -> Self {
Self {
name,
env_prefix,
search: ConfigSearch::WellKnown,
}
}
pub const fn explicit_only(mut self) -> Self {
self.search = ConfigSearch::ExplicitOnly;
self
}
pub fn load<T: ConfSerde>(&self) -> Result<Loaded<T>, ConfigError> {
self.load_from(std::env::args_os(), std::env::vars_os())
}
pub fn load_from<T: ConfSerde>(
&self,
args: impl IntoIterator<Item = impl Into<OsString>>,
env: impl IntoIterator<Item = (impl Into<OsString>, impl Into<OsString>)>,
) -> Result<Loaded<T>, ConfigError> {
let args: Vec<OsString> = args.into_iter().map(Into::into).collect();
let env: Vec<(OsString, OsString)> =
env.into_iter().map(|(k, v)| (k.into(), v.into())).collect();
if args
.iter()
.skip(1)
.take_while(|arg| *arg != "--")
.any(|arg| matches!(arg.to_str(), Some("--help" | "-h" | "--version" | "-V")))
&& let Err(error) = T::conf_builder()
.args(args.clone())
.env(Vec::<(OsString, OsString)>::new())
.try_parse()
&& error.exit_code() == 0
{
return Err(error.into());
}
let warnings = self.environment_warnings::<T>(&env);
let config_env = format!("{}CONFIG", self.env_prefix);
let path = conf::find_parameter("config", args.iter().cloned())
.map(PathBuf::from)
.or_else(|| {
env.iter()
.rev()
.find(|(key, _)| key == config_env.as_str())
.map(|(_, value)| PathBuf::from(value))
})
.or_else(|| match self.search {
ConfigSearch::ExplicitOnly => None,
ConfigSearch::WellKnown => {
self.config_paths().into_iter().find(|path| path.is_file())
}
});
let mut sources = BTreeMap::new();
let record = |event: &dyn ConfigEvent| {
let source = match event.value_source() {
ValueSource::Args { .. } => Source::Cli,
ValueSource::Env { var, .. } => Source::Environment(var.to_string()),
ValueSource::Document { name, .. } => Source::File(name.to_string()),
ValueSource::Default { .. } => Source::Default,
_ => Source::Other,
};
sources.insert(event.program_option().id().to_string(), source);
};
let builder = T::conf_builder()
.args(args)
.env(env.clone())
.config_logger(record);
let config = match &path {
Some(path) => {
let text = std::fs::read_to_string(path).map_err(|source| ConfigError::Read {
path: path.clone(),
source,
})?;
let mut document: toml::Value =
toml::from_str(&text).map_err(|error: toml::de::Error| ConfigError::Toml {
path: path.clone(),
offset: error.span().map_or(0, |span| span.start),
message: error.message().to_owned(),
})?;
interpolate::Environment::new(env)
.interpolate(&mut document)
.map_err(|source| ConfigError::Interpolation {
path: path.clone(),
source,
})?;
builder
.doc(path.display().to_string(), document)
.try_parse()?
}
None => builder.try_parse()?,
};
Ok(Loaded {
config,
path,
sources,
warnings,
})
}
pub fn environment_warnings<T: Conf>(&self, env: &[(OsString, OsString)]) -> Vec<String> {
let mut known = BTreeSet::new();
for option in T::PROGRAM_OPTIONS.iter() {
known.extend(
option
.env_form
.iter()
.chain(option.env_aliases.iter())
.map(ToString::to_string),
);
}
let unknown: BTreeSet<String> = env
.iter()
.map(|(key, _)| key.to_string_lossy().into_owned())
.filter(|key| key.starts_with(self.env_prefix) && !known.contains(key))
.collect();
unknown.into_iter()
.map(|name| format!("unrecognized environment variable {name} is ignored as a configuration override"))
.collect()
}
pub fn config_paths(&self) -> Vec<PathBuf> {
let filename = format!("{}.toml", self.name);
let mut paths = Vec::new();
if let Ok(cwd) = std::env::current_dir() {
paths.push(cwd.join(&filename));
}
if let Some(dirs) = directories::ProjectDirs::from("", "", self.name) {
for directory in [dirs.config_local_dir(), dirs.config_dir()] {
let path = directory.join(&filename);
if !paths.contains(&path) {
paths.push(path);
}
}
}
if cfg!(unix) {
paths.push(Path::new("/etc").join(self.name).join(&filename));
}
paths
}
}
pub fn parse_bytes(value: &str) -> Result<usize, String> {
let bytes: ByteSize = value.parse()?;
usize::try_from(bytes.as_u64())
.map_err(|_| "byte size exceeds this platform's address space".into())
}
pub fn deserialize_bytes<'de, D: serde::Deserializer<'de>>(
deserializer: D,
) -> Result<usize, D::Error> {
#[derive(serde::Deserialize)]
#[serde(untagged)]
enum Bytes {
Count(usize),
Text(String),
}
match <Bytes as serde::Deserialize>::deserialize(deserializer)? {
Bytes::Count(value) => Ok(value),
Bytes::Text(value) => parse_bytes(&value).map_err(serde::de::Error::custom),
}
}
#[cfg(test)]
mod tests;