Skip to main content

Crate env_reader

Crate env_reader 

Source
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_bool accepts as false.
TRUE_SPELLINGS
The spellings parse_bool accepts 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, None if it is absent or blank.