envigil 0.4.0

Keep vigil over your environment — load, parse, and validate env vars with zero dependencies.
Documentation
//! Pluggable configuration sources.
//!
//! A [`Layer`] provides raw string values for environment variable names.
//! Layers are queried in order; the first `Some(value)` wins.
//!
//! # Built-in layers
//!
//! - [`env()`] — reads from `std::env`.
//! - [`map()`] / [`map_from()`] — in-memory key-value store.
//! - [`dotenv()`] / [`dotenv_path()`] — `.env` file (requires feature `dotenv`).
//!
//! # Custom layers
//!
//! Any closure `Fn(&str) -> Option<String>` implements `Layer` via a
//! blanket impl:
//!
//! ```
//! use envigil::layer::Layer;
//!
//! let hardcoded = |name: &str| -> Option<String> {
//!     match name {
//!         "APP_PORT" => Some("9090".to_owned()),
//!         _ => None,
//!     }
//! };
//!
//! assert_eq!(hardcoded.lookup("APP_PORT"), Some("9090".to_owned()));
//! assert_eq!(hardcoded.lookup("MISSING"), None);
//! ```

/// A single source of raw configuration values.
///
/// Return `Some(value)` if this layer knows about `name`, or `None` to
/// defer to the next layer.
pub trait Layer {
    /// Look up a raw value by variable name.
    fn lookup(&self, name: &str) -> Option<String>;
}

impl<F> Layer for F
where
    F: Fn(&str) -> Option<String>,
{
    fn lookup(&self, name: &str) -> Option<String> {
        (self)(name)
    }
}

/// A layer that reads from the real process environment (`std::env`).
#[derive(Debug, Clone, Copy)]
pub struct EnvLayer;

/// Create a layer backed by `std::env`.
///
/// This is typically the highest-priority layer so that real environment
/// variables override everything else.
/// # Examples
///
/// ```no_run
/// use envigil::layer::{self, Layer};
///
/// let l = layer::env();
/// // Returns Some(...) if HOME is set, None otherwise.
/// let _home = l.lookup("HOME");
/// ```
#[must_use]
pub const fn env() -> EnvLayer {
    EnvLayer
}

impl Layer for EnvLayer {
    fn lookup(&self, name: &str) -> Option<String> {
        std::env::var(name).ok()
    }
}

/// An in-memory layer backed by a `Vec<(String, String)>`.
#[derive(Debug, Clone)]
pub struct MapLayer {
    entries: Vec<(String, String)>,
}

/// Create an in-memory layer from an iterable of key-value pairs.
///
/// Useful for tests and hardcoded defaults.
///
/// # Examples
///
/// ```
/// use envigil::layer::{self, Layer};
///
/// let l = layer::map([("PORT", "8080"), ("HOST", "localhost")]);
/// assert_eq!(l.lookup("PORT"), Some("8080".to_owned()));
/// assert_eq!(l.lookup("MISSING"), None);
/// ```
pub fn map(iter: impl IntoIterator<Item = (impl Into<String>, impl Into<String>)>) -> MapLayer {
    MapLayer {
        entries: iter
            .into_iter()
            .map(|(k, v)| (k.into(), v.into()))
            .collect(),
    }
}

/// Alias for [`map()`].
pub fn map_from(
    iter: impl IntoIterator<Item = (impl Into<String>, impl Into<String>)>,
) -> MapLayer {
    map(iter)
}

impl Layer for MapLayer {
    fn lookup(&self, name: &str) -> Option<String> {
        self.entries
            .iter()
            .find(|(k, _)| k == name)
            .map(|(_, v)| v.clone())
    }
}

#[cfg(feature = "dotenv")]
mod dotenv_layer {
    use super::Layer;

    /// A layer backed by a parsed `.env` file.
    #[derive(Debug, Clone)]
    pub struct DotenvLayer {
        entries: Vec<(String, String)>,
    }

    /// Create a layer from the `.env` file in the current working directory.
    ///
    /// If the file does not exist or cannot be read, the layer is empty
    /// (missing files are silently ignored, matching the existing
    /// `EnvSource::dotenv()` behaviour).
    #[must_use]
    pub fn dotenv() -> DotenvLayer {
        dotenv_path(".env")
    }

    /// Create a layer from a specific `.env` file path.
    ///
    /// Missing or unreadable files produce an empty layer.
    pub fn dotenv_path(path: impl AsRef<std::path::Path>) -> DotenvLayer {
        let entries = std::fs::read_to_string(path)
            .map_or_else(|_| Vec::new(), |content| crate::dotenv::parse(&content));
        DotenvLayer { entries }
    }

    impl Layer for DotenvLayer {
        fn lookup(&self, name: &str) -> Option<String> {
            self.entries
                .iter()
                .find(|(k, _)| k == name)
                .map(|(_, v)| v.clone())
        }
    }
}

#[cfg(feature = "dotenv")]
pub use dotenv_layer::{DotenvLayer, dotenv, dotenv_path};

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn env_layer_reads_real_env() {
        unsafe {
            std::env::set_var("EVIGIL_LAYER_TEST_VAR", "hello");
        }
        let l = env();
        assert_eq!(l.lookup("EVIGIL_LAYER_TEST_VAR"), Some("hello".to_owned()));
        assert_eq!(l.lookup("EVIGIL_LAYER_NONEXISTENT"), None);
        unsafe {
            std::env::remove_var("EVIGIL_LAYER_TEST_VAR");
        }
    }

    #[test]
    fn map_layer_basic() {
        let l = map([("A", "1"), ("B", "2")]);
        assert_eq!(l.lookup("A"), Some("1".to_owned()));
        assert_eq!(l.lookup("B"), Some("2".to_owned()));
        assert_eq!(l.lookup("C"), None);
    }

    #[test]
    fn map_layer_empty() {
        let l = map(std::iter::empty::<(&str, &str)>());
        assert_eq!(l.lookup("ANYTHING"), None);
    }

    #[test]
    fn closure_as_layer() {
        let l = |name: &str| -> Option<String> {
            if name == "X" {
                Some("found".to_owned())
            } else {
                None
            }
        };
        assert_eq!(l.lookup("X"), Some("found".to_owned()));
        assert_eq!(l.lookup("Y"), None);
    }

    #[cfg(feature = "dotenv")]
    #[test]
    fn dotenv_layer_missing_file_is_empty() {
        let l = dotenv_path("/nonexistent/envigil_test/.env");
        assert_eq!(l.lookup("ANYTHING"), None);
    }
}