use std::collections::BTreeMap;
use std::str::FromStr;
use crate::error::{Error, Errors};
use crate::secret::Secret;
use crate::value::{parse_bool, parse_bool_lenient, parse_csv, present};
const A_WHOLE_NUMBER: &str = "a whole number";
#[derive(Debug, Clone)]
pub struct Reader {
source: BTreeMap<String, String>,
errors: Vec<Error>,
}
impl Reader {
#[must_use]
pub fn from_env() -> Self {
Self::from_pairs(std::env::vars())
}
pub fn from_pairs<K, V, I>(pairs: I) -> Self
where
I: IntoIterator<Item = (K, V)>,
K: Into<String>,
V: Into<String>,
{
Self {
source: pairs
.into_iter()
.map(|(key, value)| (key.into(), value.into()))
.collect(),
errors: Vec::new(),
}
}
#[must_use]
pub fn raw(&self, name: &str) -> Option<&str> {
present(self.source.get(name).map(String::as_str))
}
#[must_use]
pub fn is_set(&self, name: &str) -> bool {
self.raw(name).is_some()
}
pub fn required_string(&mut self, name: &str) -> String {
if let Some(value) = self.raw(name) {
value.to_string()
} else {
self.errors.push(Error::missing(name));
String::new()
}
}
#[must_use]
pub fn optional_string(&self, name: &str) -> Option<String> {
self.raw(name).map(str::to_string)
}
#[must_use]
pub fn string_or(&self, name: &str, default: &str) -> String {
self.raw(name).unwrap_or(default).to_string()
}
pub fn required_secret(&mut self, name: &str) -> Secret {
Secret::new(self.required_string(name))
}
#[must_use]
pub fn optional_secret(&self, name: &str) -> Option<Secret> {
self.raw(name).map(Secret::new)
}
pub fn required_integer<T>(&mut self, name: &str) -> T
where
T: FromStr + Default,
{
self.required_parse(name, A_WHOLE_NUMBER).unwrap_or_default()
}
pub fn optional_integer<T>(&mut self, name: &str) -> Option<T>
where
T: FromStr,
{
self.optional_parse(name, A_WHOLE_NUMBER)
}
pub fn integer_or<T>(&mut self, name: &str, default: T) -> T
where
T: FromStr,
{
self.parse_or(name, A_WHOLE_NUMBER, default)
}
pub fn optional_positive_integer<T>(&mut self, name: &str) -> Option<T>
where
T: FromStr + PartialOrd + Default,
{
let raw = self.raw(name)?.to_string();
let parsed: T = self.parse(name, &raw, A_WHOLE_NUMBER)?;
if parsed > T::default() {
Some(parsed)
} else {
self.errors.push(Error::invalid(
name,
"a positive integer when provided",
raw,
));
None
}
}
pub fn required_parse<T>(&mut self, name: &str, expected: &str) -> Option<T>
where
T: FromStr,
{
match self.raw(name) {
None => {
self.errors.push(Error::missing(name));
None
}
Some(value) => {
let value = value.to_string();
self.parse(name, &value, expected)
}
}
}
pub fn optional_parse<T>(&mut self, name: &str, expected: &str) -> Option<T>
where
T: FromStr,
{
let value = self.raw(name)?.to_string();
self.parse(name, &value, expected)
}
pub fn parse_or<T>(&mut self, name: &str, expected: &str, default: T) -> T
where
T: FromStr,
{
match self.raw(name) {
None => default,
Some(value) => {
let value = value.to_string();
self.parse(name, &value, expected).unwrap_or(default)
}
}
}
pub fn bool_or(&mut self, name: &str, default: bool) -> bool {
let Some(raw) = self.raw(name) else {
return default;
};
let raw = raw.to_string();
if let Some(parsed) = parse_bool(Some(&raw)) {
parsed
} else {
self.errors.push(Error::invalid(
name,
"true, 1, yes, on, false, 0, no or off",
raw,
));
default
}
}
#[must_use]
pub fn lenient_bool_or(&self, name: &str, default: bool) -> bool {
parse_bool_lenient(self.raw(name)).unwrap_or(default)
}
#[must_use]
pub fn list(&self, name: &str) -> Vec<String> {
parse_csv(self.raw(name))
}
pub fn required_list(&mut self, name: &str) -> Vec<String> {
let Some(value) = self.raw(name) else {
self.errors.push(Error::missing(name));
return Vec::new();
};
let value = value.to_string();
let parsed = parse_csv(Some(&value));
if parsed.is_empty() {
self.errors.push(Error::invalid(
name,
"a comma-separated list with at least one value",
value,
));
}
parsed
}
pub fn list_or(&mut self, name: &str, default: &str) -> Vec<String> {
match self.raw(name) {
None => parse_csv(Some(default)),
Some(value) => {
let value = value.to_string();
let parsed = parse_csv(Some(&value));
if parsed.is_empty() {
self.errors.push(Error::invalid(
name,
"a comma-separated list with at least one value",
value,
));
}
parsed
}
}
}
pub fn required_one_of(&mut self, name: &str, accepted: &[&str]) -> Option<String> {
if self.raw(name).is_none() {
self.errors.push(Error::missing(name));
return None;
}
self.optional_one_of(name, accepted)
}
pub fn optional_one_of(&mut self, name: &str, accepted: &[&str]) -> Option<String> {
let value = self.raw(name)?.to_string();
if accepted.contains(&value.as_str()) {
Some(value)
} else {
self.errors.push(Error::invalid(
name,
format!("one of {}", accepted.join(", ")),
value,
));
None
}
}
#[cfg(feature = "uuid")]
pub fn required_uuid(&mut self, name: &str) -> uuid::Uuid {
self.required_parse(name, "a UUID")
.unwrap_or_else(uuid::Uuid::nil)
}
#[cfg(feature = "uuid")]
pub fn optional_uuid(&mut self, name: &str) -> Option<uuid::Uuid> {
self.optional_parse(name, "a UUID")
}
pub fn invalid(
&mut self,
name: impl Into<String>,
expected: impl Into<String>,
got: impl Into<String>,
) {
self.errors.push(Error::invalid(name, expected, got));
}
pub fn conflict(&mut self, message: impl Into<String>) {
self.errors.push(Error::conflict(message));
}
#[must_use]
pub fn has_errors(&self) -> bool {
!self.errors.is_empty()
}
#[must_use]
pub fn error_count(&self) -> usize {
self.errors.len()
}
pub fn finish(self) -> Result<(), Errors> {
if self.errors.is_empty() {
Ok(())
} else {
Err(Errors::new(self.errors))
}
}
pub fn finish_with<T>(self, value: T) -> Result<T, Errors> {
self.finish().map(|()| value)
}
fn parse<T: FromStr>(&mut self, name: &str, value: &str, expected: &str) -> Option<T> {
if let Ok(parsed) = value.parse::<T>() {
Some(parsed)
} else {
self.errors.push(Error::invalid(name, expected, value));
None
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn every_problem_is_reported_at_once() {
let mut reader = Reader::from_pairs([("PORT", "two")]);
let _ = reader.required_string("SERVICE_NAME");
let _ = reader.required_string("REGION");
let _: u16 = reader.integer_or("PORT", 8080);
let errors = reader.finish().unwrap_err();
assert_eq!(errors.len(), 3);
assert_eq!(errors.to_string().lines().count(), 3);
}
#[test]
fn problems_come_back_in_the_order_they_were_found() {
let mut reader = Reader::from_pairs([] as [(&str, &str); 0]);
let _ = reader.required_string("FIRST");
let _ = reader.required_string("SECOND");
let errors = reader.finish().unwrap_err();
let names: Vec<_> = errors.iter().filter_map(Error::name).collect();
assert_eq!(names, ["FIRST", "SECOND"]);
}
#[test]
fn a_blank_integer_is_absent_rather_than_a_parse_failure() {
let mut reader = Reader::from_pairs([("A", " ")]);
assert_eq!(reader.optional_integer::<u32>("A"), None);
assert_eq!(reader.integer_or::<u32>("A", 7), 7);
assert!(reader.finish().is_ok());
}
#[test]
fn an_unparseable_value_does_not_silently_take_the_default() {
let mut reader = Reader::from_pairs([("PORT", "eighty")]);
assert_eq!(reader.integer_or::<u16>("PORT", 8080), 8080);
assert!(reader.has_errors());
}
#[test]
fn a_failed_getter_still_returns_something_usable() {
let mut reader = Reader::from_pairs([] as [(&str, &str); 0]);
assert_eq!(reader.required_string("A"), "");
assert_eq!(reader.required_integer::<u16>("B"), 0);
assert!(reader.required_list("C").is_empty());
assert_eq!(reader.error_count(), 3);
}
#[test]
fn any_from_str_type_can_be_read() {
use std::net::{IpAddr, SocketAddr};
use std::path::PathBuf;
let mut reader = Reader::from_pairs([
("BIND", "10.0.0.1"),
("PEER", "10.0.0.2:9000"),
("BUNDLE", "/etc/ca.pem"),
]);
assert_eq!(
reader.required_parse::<IpAddr>("BIND", "an IP address"),
Some("10.0.0.1".parse().unwrap())
);
assert_eq!(
reader.required_parse::<SocketAddr>("PEER", "a socket address"),
Some("10.0.0.2:9000".parse().unwrap())
);
assert_eq!(
reader.optional_parse::<PathBuf>("BUNDLE", "a path"),
Some(PathBuf::from("/etc/ca.pem"))
);
assert!(reader.finish().is_ok());
}
#[test]
fn the_expected_phrase_reaches_the_message() {
use std::net::IpAddr;
let mut reader = Reader::from_pairs([("BIND", "localhost")]);
assert_eq!(reader.required_parse::<IpAddr>("BIND", "an IP address"), None);
let errors = reader.finish().unwrap_err();
assert_eq!(
errors.to_string(),
r#"invalid configuration: BIND must be an IP address, got "localhost""#
);
}
#[test]
fn a_strict_boolean_records_what_it_cannot_read() {
let mut reader = Reader::from_pairs([("A", "on"), ("B", "disabled")]);
assert!(reader.bool_or("A", false));
assert!(reader.bool_or("B", true), "the default, having recorded");
assert!(reader.bool_or("C", true), "absent takes the default silently");
let errors = reader.finish().unwrap_err();
assert_eq!(errors.len(), 1);
assert_eq!(errors.iter().next().and_then(Error::name), Some("B"));
}
#[test]
fn a_lenient_boolean_records_nothing() {
let mut reader = Reader::from_pairs([("B", "disabled")]);
assert!(reader.lenient_bool_or("B", false));
assert!(!reader.lenient_bool_or("C", false));
let _ = reader.bool_or("ABSENT", true);
assert!(reader.finish().is_ok());
}
#[test]
fn a_positive_integer_rejects_zero_but_not_absence() {
let mut reader = Reader::from_pairs([("A", "0")]);
assert_eq!(reader.optional_positive_integer::<u32>("A"), None);
assert_eq!(reader.optional_positive_integer::<u32>("ABSENT"), None);
assert_eq!(reader.error_count(), 1, "only the configured zero");
}
#[test]
fn a_fixed_set_lists_what_it_accepted() {
const LEVELS: &[&str] = &["info", "warn"];
let mut reader = Reader::from_pairs([("L", "verbose")]);
assert_eq!(reader.optional_one_of("L", LEVELS), None);
assert_eq!(reader.required_one_of("M", LEVELS), None);
let text = reader.finish().unwrap_err().to_string();
assert!(text.contains("one of info, warn"), "{text}");
assert!(text.contains("missing required configuration: M"), "{text}");
}
#[test]
fn a_required_fixed_set_reports_missing_once_not_twice() {
const LEVELS: &[&str] = &["info"];
let mut reader = Reader::from_pairs([] as [(&str, &str); 0]);
assert_eq!(reader.required_one_of("L", LEVELS), None);
assert_eq!(reader.error_count(), 1);
}
#[test]
fn a_list_of_only_separators_is_a_problem_not_an_empty_list() {
let mut reader = Reader::from_pairs([("A", " , ")]);
assert!(reader.list_or("A", "x").is_empty());
assert!(reader.list("A").is_empty(), "the plain reader has no opinion");
assert_eq!(reader.error_count(), 1);
}
#[test]
fn finish_with_carries_a_value_through() {
let mut reader = Reader::from_pairs([("PORT", "8443")]);
let port = reader.integer_or::<u16>("PORT", 8080);
assert_eq!(reader.finish_with(port).unwrap(), 8443);
let mut reader = Reader::from_pairs([] as [(&str, &str); 0]);
let _ = reader.required_string("A");
assert!(reader.finish_with(1).is_err());
}
#[test]
fn blank_is_absent_everywhere_it_matters() {
let mut reader = Reader::from_pairs([
("S", " "),
("I", "\t"),
("B", " "),
("L", ""),
("K", " "),
]);
assert_eq!(reader.optional_string("S"), None);
assert_eq!(reader.optional_integer::<u32>("I"), None);
assert!(!reader.lenient_bool_or("B", false));
assert!(reader.list("L").is_empty());
assert!(reader.optional_secret("K").is_none());
assert!(!reader.is_set("S"));
assert!(reader.finish().is_ok(), "none of that is a problem");
}
#[test]
fn a_reader_can_come_from_the_process_environment() {
let reader = Reader::from_env();
assert!(!reader.has_errors());
}
#[cfg(feature = "uuid")]
#[test]
fn a_uuid_is_read_and_a_bad_one_is_recorded() {
let mut reader = Reader::from_pairs([
("GOOD", "00000000-0000-0000-0000-000000000001"),
("BAD", "not-a-uuid"),
]);
assert_eq!(
reader.required_uuid("GOOD").to_string(),
"00000000-0000-0000-0000-000000000001"
);
assert!(reader.required_uuid("BAD").is_nil());
assert!(reader.optional_uuid("ABSENT").is_none());
let text = reader.finish().unwrap_err().to_string();
assert!(text.contains("BAD must be a UUID"), "{text}");
}
}