Skip to main content

esh_providers_env/
lib.rs

1//! Environment and dotenv configuration providers.
2
3use async_trait::async_trait;
4use esh_core::{
5    ConfigValue, Error, Provider, ProviderCapability, ProviderId, ProviderMeta, Result,
6};
7use parking_lot::RwLock;
8use std::collections::HashMap;
9use std::env;
10use std::path::{Path, PathBuf};
11
12/// Reads configuration from process environment variables.
13pub struct EnvProvider {
14    meta: ProviderMeta,
15    /// Optional prefix stripped from env keys (e.g. `APP_`).
16    prefix: Option<String>,
17}
18
19impl EnvProvider {
20    /// Create a provider with no prefix.
21    #[must_use]
22    pub fn new() -> Self {
23        Self {
24            meta: ProviderMeta {
25                id: ProviderId::new("env"),
26                name: "Environment Variables".into(),
27                capabilities: ProviderCapability {
28                    bulk: true,
29                    versioned: false,
30                    local: true,
31                },
32            },
33            prefix: None,
34        }
35    }
36
37    /// Only consider env vars starting with `prefix` (prefix removed from key).
38    #[must_use]
39    pub fn with_prefix(mut self, prefix: impl Into<String>) -> Self {
40        self.prefix = Some(prefix.into());
41        self
42    }
43
44    fn env_key(&self, key: &str) -> String {
45        match &self.prefix {
46            Some(p) => format!("{p}{key}"),
47            None => key.to_string(),
48        }
49    }
50}
51
52impl Default for EnvProvider {
53    fn default() -> Self {
54        Self::new()
55    }
56}
57
58#[async_trait]
59impl Provider for EnvProvider {
60    fn meta(&self) -> &ProviderMeta {
61        &self.meta
62    }
63
64    async fn get(&self, key: &str) -> Result<ConfigValue> {
65        let env_key = self.env_key(key);
66        match env::var(&env_key) {
67            Ok(v) => Ok(ConfigValue::secret(v)),
68            Err(env::VarError::NotPresent) => Err(Error::not_found(key)),
69            Err(env::VarError::NotUnicode(_)) => Err(Error::provider(
70                self.meta.id.as_str(),
71                format!("environment variable `{env_key}` is not valid UTF-8"),
72            )),
73        }
74    }
75}
76
77/// Reads from a `.env` file (and optional in-memory overlay).
78pub struct DotenvProvider {
79    meta: ProviderMeta,
80    path: PathBuf,
81    values: RwLock<HashMap<String, String>>,
82}
83
84impl DotenvProvider {
85    /// Load from `path` immediately.
86    pub fn from_path(path: impl AsRef<Path>) -> Result<Self> {
87        let path = path.as_ref().to_path_buf();
88        let mut values = HashMap::new();
89        if path.exists() {
90            let iter = dotenvy::from_path_iter(&path).map_err(|e| {
91                Error::provider("dotenv", format!("failed to read {}: {e}", path.display()))
92            })?;
93            for item in iter {
94                let (k, v) = item.map_err(|e| Error::provider("dotenv", e.to_string()))?;
95                values.insert(k, v);
96            }
97        }
98        Ok(Self {
99            meta: ProviderMeta {
100                id: ProviderId::new("dotenv"),
101                name: "Dotenv File".into(),
102                capabilities: ProviderCapability {
103                    bulk: true,
104                    versioned: false,
105                    local: true,
106                },
107            },
108            path,
109            values: RwLock::new(values),
110        })
111    }
112
113    /// Default `.env` in current directory.
114    pub fn from_default() -> Result<Self> {
115        Self::from_path(".env")
116    }
117
118    /// Reload file from disk.
119    pub fn reload(&self) -> Result<()> {
120        let mut values = HashMap::new();
121        if self.path.exists() {
122            let iter = dotenvy::from_path_iter(&self.path).map_err(|e| {
123                Error::provider(
124                    "dotenv",
125                    format!("failed to read {}: {e}", self.path.display()),
126                )
127            })?;
128            for item in iter {
129                let (k, v) = item.map_err(|e| Error::provider("dotenv", e.to_string()))?;
130                values.insert(k, v);
131            }
132        }
133        *self.values.write() = values;
134        Ok(())
135    }
136}
137
138#[async_trait]
139impl Provider for DotenvProvider {
140    fn meta(&self) -> &ProviderMeta {
141        &self.meta
142    }
143
144    async fn get(&self, key: &str) -> Result<ConfigValue> {
145        self.values
146            .read()
147            .get(key)
148            .cloned()
149            .map(ConfigValue::secret)
150            .ok_or_else(|| Error::not_found(key))
151    }
152}
153
154#[cfg(test)]
155mod tests {
156    use super::*;
157    use esh_test_support::{
158        run_provider_conformance, write_temp_dotenv, ProviderConformanceCfg, SAMPLE_SECRET,
159    };
160    use std::sync::OnceLock;
161    use tokio::sync::Mutex;
162
163    fn env_lock() -> &'static Mutex<()> {
164        static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
165        LOCK.get_or_init(|| Mutex::new(()))
166    }
167
168    #[tokio::test]
169    async fn env_provider_reads_var() {
170        let _g = env_lock().lock().await;
171        env::set_var("ESH_TEST_KEY_XYZ", "value-1");
172        let p = EnvProvider::new();
173        let v = p.get("ESH_TEST_KEY_XYZ").await.unwrap();
174        assert_eq!(v.as_str(), Some("value-1"));
175        env::remove_var("ESH_TEST_KEY_XYZ");
176    }
177
178    #[tokio::test]
179    async fn dotenv_provider_reads_file() {
180        let (_tmp, path) = write_temp_dotenv("DATABASE_URL=postgres://local\n");
181        let p = DotenvProvider::from_path(&path).unwrap();
182        let v = p.get("DATABASE_URL").await.unwrap();
183        assert_eq!(v.as_str(), Some("postgres://local"));
184    }
185
186    #[tokio::test]
187    async fn env_conformance() {
188        let _g = env_lock().lock().await;
189        env::set_var("database_url", SAMPLE_SECRET);
190        let p = EnvProvider::new();
191        run_provider_conformance(
192            &p,
193            &ProviderConformanceCfg {
194                expected_id: "env".into(),
195                expected_capabilities: ProviderCapability {
196                    bulk: true,
197                    versioned: false,
198                    local: true,
199                },
200                present_key: "database_url".into(),
201                present_value: SAMPLE_SECRET.into(),
202                missing_key: "esh_missing_key_zzz".into(),
203                fault_key: None,
204                health_ok: true,
205                test_get_many: true,
206            },
207        )
208        .await;
209        env::remove_var("database_url");
210    }
211
212    #[tokio::test]
213    async fn dotenv_conformance() {
214        let (_tmp, path) = write_temp_dotenv(&format!("database_url={SAMPLE_SECRET}\n"));
215        let p = DotenvProvider::from_path(&path).unwrap();
216        run_provider_conformance(
217            &p,
218            &ProviderConformanceCfg {
219                expected_id: "dotenv".into(),
220                expected_capabilities: ProviderCapability {
221                    bulk: true,
222                    versioned: false,
223                    local: true,
224                },
225                present_key: "database_url".into(),
226                present_value: SAMPLE_SECRET.into(),
227                missing_key: "missing".into(),
228                fault_key: None,
229                health_ok: true,
230                test_get_many: true,
231            },
232        )
233        .await;
234    }
235}