Expand description
Reading a program’s configuration out of environment variables.
A program configured by the environment and nothing else — no files, no defaults baked into an image, no service discovery — needs one place that turns a variable into a value, so the rules that turn out to matter are stated once. This is that place.
§Three rules worth knowing before anything else
Blank is absent. A variable set to "", or to spaces, means the
same thing as an unset variable. Deployments produce blank values
routinely — a templated value whose source was empty, an .env line
with nothing after the = — and treating those as “configured, to the
empty string” produces failures a long way from their cause. It applies
uniformly, including to integers, where the obvious implementation would
instead try to parse "" and report a malformed number.
Every problem is reported at once. Reader accumulates problems
rather than returning the first, so a program with four missing
variables says so once instead of over four restarts. Each getter
returns a usable value even when it failed, so a whole configuration
reads as one straight run of statements with no ? after every line;
Reader::finish is what decides whether any of it was valid.
A secret never prints. Secret holds one and renders as
<redacted> through both Debug and std::fmt::Display — not
Debug alone, which is the common half-measure that leaves every
Display-based logging macro wide open. A configuration struct ends up
in a log line eventually, and a connection string with an access key in
it must not be what is there.
§Two smaller decisions
An unparseable value is never a silent fallback. Reader::integer_or
takes the default and records the problem, because a program quietly
running on a default nobody chose is harder to diagnose than one that
will not start.
Booleans are read strictly. parse_bool accepts four spellings
each way and answers None to anything else, rather than the tempting
“not false-ish, therefore true” — under which ENABLED=disabled comes
out true and the deployment looks configured.
parse_bool_lenient is there for an existing estate that already
depends on that behaviour.
§Examples
use env_reader::Reader;
let mut reader = Reader::from_pairs([
("SERVICE_NAME", "orders"),
("PORT", "8443"),
("REGION", " "), // blank: the same as absent
]);
let service: String = reader.required_string("SERVICE_NAME");
let port: u16 = reader.integer_or("PORT", 8080);
let region: Option<String> = reader.optional_string("REGION");
reader.finish().expect("the configuration is complete");
assert_eq!(service, "orders");
assert_eq!(port, 8443);
assert_eq!(region, None);A whole configuration, with every problem reported together:
use env_reader::{Errors, Reader, Secret};
#[derive(Debug)]
struct Config {
service_name: String,
port: u16,
database_password: Secret,
}
fn load() -> Result<Config, Errors> {
let mut reader = Reader::from_pairs([("PORT", "eighty")]);
let config = Config {
service_name: reader.required_string("SERVICE_NAME"),
port: reader.integer_or("PORT", 8080),
database_password: reader.required_secret("DB_PASSWORD"),
};
reader.finish_with(config)
}
let errors = load().unwrap_err();
assert_eq!(errors.len(), 3, "all three, not just the first");§Features
uuid— adds [Reader::required_uuid] and [Reader::optional_uuid]. Off by default; with it off this crate has no dependencies at all.
Structs§
- Errors
- Every problem found while reading a configuration.
- Reader
- Reads a configuration from variables, accumulating problems rather than stopping at the first.
- Secret
- A configuration value that never appears in output.
Enums§
- Error
- One thing wrong with one variable.
Constants§
- FALSE_
SPELLINGS - The spellings
parse_boolaccepts as false. - TRUE_
SPELLINGS - The spellings
parse_boolaccepts as true.
Functions§
- parse_
bool - Read a value as a boolean, strictly.
- parse_
bool_ lenient - Read a value as a boolean, leniently: anything not false-ish is true.
- parse_
csv - Split a comma-separated value into its non-empty, trimmed elements.
- parse_
separated parse_csv, with a separator of your choosing.- present
- A value if it is present,
Noneif it is absent or blank.