kinetic_config/

interpolation.rs

//! Environment variable interpolation for configuration files.
//!
//! Supports substituting `${ENV_VAR}` or `$ENV_VAR` in strings.

use regex::Regex;
use snafu::Snafu;
use std::collections::HashMap;
use std::env;
use std::sync::OnceLock;

#[derive(Debug, Snafu)]
pub enum Error {
    #[snafu(display("Environment variable not found: {}", var))]
    EnvVarNotFound { var: String },
}

type Result<T, E = Error> = std::result::Result<T, E>;

/// Returns a pre-compiled regex for matching `${VAR}` or `$VAR` patterns.
fn get_interp_regex() -> &'static Regex {
    static REGEX: OnceLock<Regex> = OnceLock::new();
    REGEX.get_or_init(|| {
        // Matches ${VAR} or ${VAR:-default} or $VAR.
        // Captures the variable name in group 1 or 3.
        // Captures the default value in group 2.
        // SAFETY: This is a compile-time constant regex pattern that is known to be valid.
        Regex::new(r"\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}|\$([A-Za-z_][A-Za-z0-9_]*)")
            .expect("interpolation regex is a valid constant pattern")
    })
}

/// Interpolates a string by replacing environment variables.
///
/// If an environment variable is referenced but not set, returns `Error::EnvVarNotFound`.
pub fn interpolate_string(s: &str) -> Result<String> {
    // Avoid regex overhead if there are no dollar signs.
    if !s.contains('$') {
        return Ok(s.to_string());
    }

    let re = get_interp_regex();
    let mut result = String::with_capacity(s.len());
    let mut last_match = 0;

    for caps in re.captures_iter(s) {
        // SAFETY: Group 0 always exists for any successful regex capture.
        let m = caps.get(0).expect("regex group 0 always exists");

        // Append text before the match
        result.push_str(&s[last_match..m.start()]);

        // SAFETY: The regex guarantees that either group 1 (braced form) or group 3 (bare form) matches.
        let var_name = caps
            .get(1)
            .or_else(|| caps.get(3))
            .expect("regex guarantees group 1 or 3 matches")
            .as_str();
        let default_val = caps.get(2).map(|m| m.as_str());

        // Look up the environment variable
        let val = env::var(var_name).or_else(|_| {
            default_val
                .map(String::from)
                .ok_or_else(|| Error::EnvVarNotFound {
                    var: var_name.to_string(),
                })
        })?;

        result.push_str(&val);
        last_match = m.end();
    }

    // Append remaining text
    result.push_str(&s[last_match..]);

    Ok(result)
}

/// Helper struct for interpolating a raw configuration (e.g. JSON/YAML AST).
///
/// Currently operates on strings directly, but designed to be applied
/// iteratively over parsed configuration trees if needed.
pub struct Interpolator {
    // We could add custom mock env vars here for testing if desired.
    env_overrides: Option<HashMap<String, String>>,
}

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

impl Interpolator {
    pub fn new() -> Self {
        Self {
            env_overrides: None,
        }
    }

    #[cfg(test)]
    pub fn with_overrides(overrides: HashMap<String, String>) -> Self {
        Self {
            env_overrides: Some(overrides),
        }
    }

    /// Interpolate a string using the environment or mock overrides.
    pub fn interpolate(&self, s: &str) -> Result<String> {
        if !s.contains('$') {
            return Ok(s.to_string());
        }

        let re = get_interp_regex();
        let mut result = String::with_capacity(s.len());
        let mut last_match = 0;

        for caps in re.captures_iter(s) {
            // SAFETY: Group 0 always exists for any successful regex capture.
            let m = caps.get(0).expect("regex group 0 always exists");
            result.push_str(&s[last_match..m.start()]);
            // SAFETY: The regex guarantees that either group 1 (braced form) or group 3 (bare form) matches.
            let var_name = caps
                .get(1)
                .or_else(|| caps.get(3))
                .expect("regex guarantees group 1 or 3 matches")
                .as_str();
            let default_val = caps.get(2).map(|m| m.as_str());

            let val = self.get_var(var_name).or_else(|_| {
                default_val
                    .map(String::from)
                    .ok_or_else(|| Error::EnvVarNotFound {
                        var: var_name.to_string(),
                    })
            })?;
            result.push_str(&val);

            last_match = m.end();
        }

        result.push_str(&s[last_match..]);
        Ok(result)
    }

    fn get_var(&self, name: &str) -> Result<String> {
        if let Some(overrides) = &self.env_overrides
            && let Some(v) = overrides.get(name)
        {
            return Ok(v.clone());
        }

        env::var(name).map_err(|_| Error::EnvVarNotFound {
            var: name.to_string(),
        })
    }
}

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

    #[test]
    fn test_interpolation_no_vars() {
        let interp = Interpolator::new();
        assert_eq!(interp.interpolate("hello world").unwrap(), "hello world");
    }

    #[test]
    fn test_interpolation_with_vars() {
        let mut envs = HashMap::new();
        envs.insert("NAME".to_string(), "world".to_string());
        envs.insert("PORT".to_string(), "8080".to_string());

        let interp = Interpolator::with_overrides(envs);

        assert_eq!(interp.interpolate("hello ${NAME}").unwrap(), "hello world");
        assert_eq!(
            interp.interpolate("listening on $PORT").unwrap(),
            "listening on 8080"
        );
        assert_eq!(
            interp.interpolate("http://${NAME}:$PORT/api").unwrap(),
            "http://world:8080/api"
        );
    }

    #[test]
    fn test_interpolation_with_default_values() {
        let interp = Interpolator::new();
        assert_eq!(
            interp.interpolate("hello ${UNDEFINED_VAR:-world}").unwrap(),
            "hello world"
        );
        assert_eq!(
            interp.interpolate("hello ${UNDEFINED_VAR:-}").unwrap(),
            "hello "
        );
    }

    #[test]
    fn test_interpolation_missing_var() {
        let interp = Interpolator::new();
        let result = interp.interpolate("hello ${MISSING_VAR_XYZ}");
        assert!(matches!(result, Err(Error::EnvVarNotFound { .. })));
    }
}