envigil 0.1.0

Keep vigil over your environment — load, parse, and validate env vars with zero dependencies.
Documentation
//! Loading environment variables into a typed container.
//!
//! [`EnvSource`] declares variables via [`VarBuilder`], reads
//! `std::env`, and produces an [`Env`] — a typed, immutable map.
//!
//! # Examples
//!
//! ```rust,no_run
//! use envigil::{EnvSource, VarBuilder};
//!
//! # fn main() -> Result<(), envigil::Error> {
//! let cfg = EnvSource::new()
//!     .prefix("APP_")
//!     .declare(VarBuilder::new("PORT", |v| v.parse::<u16>().map_err(|e| e.to_string()))
//!         .default(8080))
//!     .declare(VarBuilder::new("NAME", |v| Ok(v.to_owned()))
//!         .required())
//!     .load()?;
//!
//! let port: &u16 = cfg.get("PORT")?;
//! let name: &String = cfg.get("NAME")?;
//! # Ok(())
//! # }
//! ```

use std::any::Any;
use std::collections::HashMap;
use std::fmt;

use crate::error::Error;
use crate::secret::Secret;
use crate::var::VarBuilder;

// ---------------------------------------------------------------------------
// Type-erased variable (private)
// ---------------------------------------------------------------------------
trait DynVar {
    fn name(&self) -> &str;
    fn resolve_raw(&self, raw: Option<&str>) -> Result<Option<Box<dyn Any>>, Error>;
}

impl<T: Clone + 'static> DynVar for VarBuilder<T> {
    fn name(&self) -> &str {
        self.name()
    }

    fn resolve_raw(&self, raw: Option<&str>) -> Result<Option<Box<dyn Any>>, Error> {
        let resolved = self.resolve(raw)?;

        match resolved {
            Some(v) if self.is_secret() => Ok(Some(Box::new(Secret::new(v)) as Box<dyn Any>)),
            Some(v) => Ok(Some(Box::new(v) as Box<dyn Any>)),
            None => Ok(None),
        }
    }
}

// ---------------------------------------------------------------------------
// EnvSource
// ---------------------------------------------------------------------------

/// Builder that declares environment variables and loads them.
///
/// # Examples
///
/// ```rust,no_run
/// use envigil::{EnvSource, VarBuilder};
///
/// # fn main() -> Result<(), envigil::Error> {
/// let cfg = EnvSource::new()
///     .declare(VarBuilder::new("PORT", |v| v.parse::<u16>().map_err(|e| e.to_string()))
///         .default(8080))
///     .load()?;
/// # Ok(())
/// # }
/// ```
pub struct EnvSource {
    prefix: String,
    vars: Vec<Box<dyn DynVar>>,
    dotenv_entries: Vec<(String, String)>,
}

impl EnvSource {
    /// Create an empty source with no prefix.
    pub fn new() -> Self {
        Self {
            prefix: String::new(),
            vars: Vec::new(),
            dotenv_entries: Vec::new(),
        }
    }

    /// Set a prefix prepended to every variable name.
    ///
    /// ```rust,no_run
    /// use envigil::{EnvSource, VarBuilder};
    ///
    /// # fn main() -> Result<(), envigil::Error> {
    /// let cfg = EnvSource::new()
    ///     .prefix("APP_")
    ///     .declare(VarBuilder::new("PORT", |v| v.parse::<u16>().map_err(|e| e.to_string()))
    ///         .default(8080))
    ///     .load()?;
    /// // reads APP_PORT from the environment
    /// # Ok(())
    /// # }
    /// ```
    pub fn prefix(mut self, prefix: impl Into<String>) -> Self {
        self.prefix = prefix.into();
        self
    }

    /// Register a variable declaration.
    pub fn declare<T: Clone + 'static>(mut self, var: VarBuilder<T>) -> Self {
        let var = var.prefixed(&self.prefix);
        self.vars.push(Box::new(var));
        self
    }

    #[cfg(feature = "dotenv")]
    pub fn dotenv(mut self) -> Self {
        if let Ok(content) = std::fs::read_to_string(".env") {
            self.dotenv_entries.extend(crate::dotenv::parse(&content));
        }
        self
    }

    #[cfg(feature = "dotenv")]
    pub fn dotenv_path(mut self, path: impl AsRef<std::path::Path>) -> Self {
        if let Ok(content) = std::fs::read_to_string(path) {
            self.dotenv_entries.extend(crate::dotenv::parse(&content));
        }
        self
    }

    /// Read the environment and resolve every declared variable.
    ///
    /// All errors are collected and returned together via
    /// [`Error::multiple`].
    pub fn load(self) -> Result<Env, Error> {
        let mut values: HashMap<String, Box<dyn Any>> = HashMap::new();
        let mut errors: Vec<Error> = Vec::new();

        for var in &self.vars {
            // Real env wins; .env is fallback.
            let raw = std::env::var(var.name()).ok().or_else(|| {
                self.dotenv_entries
                    .iter()
                    .find(|(k, _)| k == var.name())
                    .map(|(_, v)| v.clone())
            });

            match var.resolve_raw(raw.as_deref()) {
                Ok(Some(v)) => {
                    values.insert(var.name().to_owned(), v);
                }
                Ok(None) => {}
                Err(e) => {
                    errors.push(e);
                }
            }
        }

        if errors.is_empty() {
            Ok(Env { values })
        } else if errors.len() == 1 {
            Err(errors.into_iter().next().expect("len == 1"))
        } else {
            Err(Error::multiple(errors))
        }
    }
}

impl Default for EnvSource {
    fn default() -> Self {
        Self::new()
    }
}

// ---------------------------------------------------------------------------
// Env
// ---------------------------------------------------------------------------

/// An immutable, typed map of loaded environment variables.
pub struct Env {
    values: HashMap<String, Box<dyn Any>>,
}

impl Env {
    /// Retrieve a variable by name.
    ///
    /// The type parameter must match the parser's output type.
    /// Secret variables are stored as [`Secret<T>`].
    ///
    /// # Errors
    ///
    /// Returns [`Error::not_found`] if the name was not declared or
    /// the type does not match.
    pub fn get<T: 'static>(&self, name: &str) -> Result<&T, Error> {
        let value = self
            .values
            .get(name)
            .ok_or_else(|| Error::not_found(name))?;

        value
            .downcast_ref::<T>()
            .ok_or_else(|| Error::not_found(name))
    }

    /// Check whether a variable was loaded.
    pub fn contains(&self, name: &str) -> bool {
        self.values.contains_key(name)
    }
}

impl fmt::Debug for Env {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let keys: Vec<&String> = self.values.keys().collect();
        f.debug_struct("Env").field("keys", &keys).finish()
    }
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

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

    // Unique names to avoid collisions in parallel tests.

    #[test]
    fn loads_value_from_env() {
        unsafe {
            std::env::set_var("EVIGIL_T1_PORT", "9090");
        }

        let cfg = EnvSource::new()
            .declare(VarBuilder::new("EVIGIL_T1_PORT", |v| {
                v.parse::<u16>().map_err(|e| e.to_string())
            }))
            .load()
            .unwrap();

        assert_eq!(*cfg.get::<u16>("EVIGIL_T1_PORT").unwrap(), 9090);

        unsafe {
            std::env::remove_var("EVIGIL_T1_PORT");
        }
    }

    #[test]
    fn applies_prefix() {
        unsafe {
            std::env::set_var("MYAPP_PORT", "7070");
        }

        let cfg = EnvSource::new()
            .prefix("MYAPP_")
            .declare(VarBuilder::new("PORT", |v| {
                v.parse::<u16>().map_err(|e| e.to_string())
            }))
            .load()
            .unwrap();

        assert_eq!(*cfg.get::<u16>("MYAPP_PORT").unwrap(), 7070);

        unsafe {
            std::env::remove_var("MYAPP_PORT");
        }
    }

    #[test]
    fn default_when_absent() {
        let cfg = EnvSource::new()
            .declare(
                VarBuilder::new("EVIGIL_T3_MISSING", |v| {
                    v.parse::<u16>().map_err(|e| e.to_string())
                })
                .default(3000),
            )
            .load()
            .unwrap();

        assert_eq!(*cfg.get::<u16>("EVIGIL_T3_MISSING").unwrap(), 3000);
    }

    #[test]
    fn optional_absent_is_not_in_env() {
        let cfg = EnvSource::new()
            .declare(VarBuilder::new("EVIGIL_T4_NOPE", |v| Ok(v.to_owned())))
            .load()
            .unwrap();

        assert!(!cfg.contains("EVIGIL_T4_NOPE"));
        assert!(cfg.get::<String>("EVIGIL_T4_NOPE").is_err());
    }

    #[test]
    fn required_missing_is_error() {
        let err = EnvSource::new()
            .declare(VarBuilder::new("EVIGIL_T5_REQUIRED", |v| Ok(v.to_owned())).required())
            .load()
            .unwrap_err();

        let msg = err.to_string();
        assert!(msg.contains("EVIGIL_T5_REQUIRED"), "message: {msg}");
    }

    #[test]
    fn multiple_errors_collected() {
        let err = EnvSource::new()
            .declare(VarBuilder::new("EVIGIL_T6_A", |v| Ok(v.to_owned())).required())
            .declare(VarBuilder::new("EVIGIL_T6_B", |v| Ok(v.to_owned())).required())
            .load()
            .unwrap_err();

        let msg = err.to_string();
        assert!(msg.contains("2 errors"), "message: {msg}");
        assert!(msg.contains("EVIGIL_T6_A"), "message: {msg}");
        assert!(msg.contains("EVIGIL_T6_B"), "message: {msg}");
    }

    #[test]
    fn secret_wraps_in_secret() {
        unsafe {
            std::env::set_var("EVIGIL_T7_TOKEN", "hunter2");
        }

        let cfg = EnvSource::new()
            .declare(VarBuilder::new("EVIGIL_T7_TOKEN", |v| Ok(v.to_owned())).secret())
            .load()
            .unwrap();

        let token = cfg.get::<Secret<String>>("EVIGIL_T7_TOKEN").unwrap();
        assert_eq!(token.expose(), "hunter2");
        assert_eq!(format!("{token:?}"), "Secret([REDACTED])");

        // Plain String must NOT work:
        assert!(cfg.get::<String>("EVIGIL_T7_TOKEN").is_err());

        unsafe {
            std::env::remove_var("EVIGIL_T7_TOKEN");
        }
    }

    #[test]
    fn validation_runs_on_load() {
        unsafe {
            std::env::set_var("EVIGIL_T8_PORT", "0");
        }

        let err = EnvSource::new()
            .declare(
                VarBuilder::new("EVIGIL_T8_PORT", |v| {
                    v.parse::<u16>().map_err(|e| e.to_string())
                })
                .validate(validate::range(1..=65535)),
            )
            .load()
            .unwrap_err();

        let msg = err.to_string();
        assert!(msg.contains("out of range"), "message: {msg}");

        unsafe {
            std::env::remove_var("EVIGIL_T8_PORT");
        }
    }

    #[test]
    fn contains_returns_true_for_loaded() {
        let cfg = EnvSource::new()
            .declare(VarBuilder::new("EVIGIL_T9_X", |v| Ok(v.to_owned())).default("yes".to_owned()))
            .load()
            .unwrap();

        assert!(cfg.contains("EVIGIL_T9_X"));
        assert!(!cfg.contains("EVIGIL_T9_Y"));
    }
}