env-reader
Read a program's configuration out of environment variables: blank is absent, every problem is reported at once, and a secret never prints.
use ;
Three variables wrong is one error listing all three, not three restarts:
missing required configuration: SERVICE_NAME
invalid configuration: PORT must be a whole number, got "eighty"
missing required configuration: DB_PASSWORD
Three rules
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. Each getter returns a usable value even when it
failed — a missing required string comes back empty — so a whole
configuration reads as one straight run of statements with no ? after every
line. finish is what decides whether any of it was valid.
A secret never prints. Secret renders as <redacted> through both
Debug and Display — not Debug alone, which is the common half-measure
that leaves every Display-based logging macro wide open. The value comes out
only through expose(), which is deliberately awkward to type and easy to
grep for.
# use Secret;
let config = Config ;
let printed = format!;
assert!;
assert!;
Two smaller decisions
An unparseable value is never a silent fallback. 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 true/1/yes/on and
false/0/no/off in any case, 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 and Reader::lenient_bool_or exist for an estate that
already depends on that older behaviour.
What you can read
| Strings | required_string, optional_string, string_or |
| Secrets | required_secret, optional_secret |
| Integers | required_integer, optional_integer, integer_or, optional_positive_integer |
Anything with FromStr |
required_parse, optional_parse, parse_or |
| Booleans | bool_or, lenient_bool_or |
| Lists | list, required_list, list_or |
| Fixed sets | required_one_of, optional_one_of |
| UUIDs (feature) | required_uuid, optional_uuid |
| Your own checks | invalid, conflict |
The parse family takes the noun phrase its error message uses — an IP address, a socket address, an RFC 3339 timestamp — because that phrase is
the whole difference between a message somebody can act on and one they
cannot:
use IpAddr;
use Reader;
let mut reader = from_pairs;
assert_eq!;
let errors = reader.finish.unwrap_err;
assert_eq!;
Testing
Reader::from_pairs is the constructor for tests and for configuration that
arrives from somewhere other than the environment. Reader::from_env is the
only function in the crate that touches global state — which
std::env::set_var is unsafe for good reason — so nothing else needs it.
Dependencies
None, with default features. uuid is optional and off by default.
License
MIT or Apache-2.0, at your option.