Skip to main content

rushls_common/config/
interpolate.rs

1//! Environment substitution in TOML string values, before source overrides.
2//! Keys are never interpolated. Inserted values are literal, not TOML source.
3
4use std::{collections::BTreeMap, ffi::OsString};
5
6use thiserror::Error;
7
8#[derive(Clone, Debug, Error, Eq, PartialEq)]
9pub enum InterpolationError {
10    #[error("unclosed environment reference; a variable is written as ${{NAME}}")]
11    Unclosed,
12    #[error("${{{0}}} names no variable, and no `:-` fallback was given")]
13    Undefined(String),
14    #[error("invalid environment variable name in interpolation")]
15    Malformed,
16}
17
18/// The environment a document is interpolated against.
19pub struct Environment(BTreeMap<String, String>);
20
21impl Environment {
22    pub fn new(variables: impl IntoIterator<Item = (OsString, OsString)>) -> Self {
23        Self(
24            variables
25                .into_iter()
26                .filter_map(|(key, value)| {
27                    Some((key.into_string().ok()?, value.into_string().ok()?))
28                })
29                .collect(),
30        )
31    }
32
33    /// Substitutes every string leaf in `document`, in place.
34    ///
35    /// Keys and table names are never touched: a variable that could name a
36    /// setting rather than a value would make the shape of the configuration
37    /// depend on the environment, which is not something an operator reading
38    /// the file could follow.
39    pub fn interpolate(&self, document: &mut toml::Value) -> Result<(), InterpolationError> {
40        match document {
41            toml::Value::String(value) => {
42                *value = self.expand(value)?;
43                Ok(())
44            }
45            toml::Value::Array(values) => values
46                .iter_mut()
47                .try_for_each(|value| self.interpolate(value)),
48            toml::Value::Table(table) => table
49                .iter_mut()
50                .try_for_each(|(_, value)| self.interpolate(value)),
51            _ => Ok(()),
52        }
53    }
54
55    fn expand(&self, value: &str) -> Result<String, InterpolationError> {
56        let mut out = String::with_capacity(value.len());
57        let mut rest = value;
58
59        while let Some(index) = rest.find('$') {
60            out.push_str(&rest[..index]);
61            rest = &rest[index..];
62
63            // `$$` is a literal dollar. This matters rather than being
64            // pedantry: passphrases and stream keys legitimately contain one,
65            // and silently interpolating those would corrupt a working
66            // credential.
67            if let Some(tail) = rest.strip_prefix("$$") {
68                out.push('$');
69                rest = tail;
70                continue;
71            }
72
73            let Some(tail) = rest.strip_prefix("${") else {
74                // A lone `$` that opens nothing is itself. Refusing here would
75                // make every dollar in a password an error.
76                out.push('$');
77                rest = &rest[1..];
78                continue;
79            };
80            let Some(end) = tail.find('}') else {
81                return Err(InterpolationError::Unclosed);
82            };
83            out.push_str(&self.lookup(&tail[..end])?);
84            rest = &tail[end + 1..];
85        }
86
87        out.push_str(rest);
88        Ok(out)
89    }
90
91    /// Resolves one `NAME` or `NAME:-fallback` reference.
92    fn lookup(&self, reference: &str) -> Result<String, InterpolationError> {
93        let (name, fallback) = match reference.split_once(":-") {
94            Some((name, fallback)) => (name, Some(fallback)),
95            None => (reference, None),
96        };
97        let name = name.trim();
98        if !name.starts_with(|c: char| c.is_ascii_alphabetic() || c == '_')
99            || !name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_')
100        {
101            return Err(InterpolationError::Malformed);
102        }
103
104        match self.0.get(name) {
105            // `:-` means what it means in a shell: unset *or empty* takes the
106            // fallback. Orchestrators often define a variable as empty rather
107            // than leaving it out, and that should not silently win.
108            Some(value) if value.is_empty() && fallback.is_some() => {
109                Ok(fallback.unwrap_or_default().to_owned())
110            }
111            Some(value) => Ok(value.clone()),
112            // An undefined variable is an error rather than an empty string.
113            // Substituting `""` into a token would silently disable the check
114            // it was protecting, which is the worst way to learn a variable was
115            // missing. Where empty is genuinely wanted, `${VAR:-}` says so.
116            None => fallback
117                .map(ToOwned::to_owned)
118                .ok_or_else(|| InterpolationError::Undefined(name.to_owned())),
119        }
120    }
121}
122
123#[cfg(test)]
124mod tests {
125    use super::*;
126
127    fn environment(pairs: &[(&str, &str)]) -> Environment {
128        Environment::new(
129            pairs
130                .iter()
131                .map(|(key, value)| (OsString::from(*key), OsString::from(*value))),
132        )
133    }
134
135    fn expand(value: &str, pairs: &[(&str, &str)]) -> Result<String, InterpolationError> {
136        environment(pairs).expand(value)
137    }
138
139    #[test]
140    fn a_variable_is_replaced_by_its_value() {
141        assert_eq!(
142            expand("${NAME}", &[("NAME", "studio")]),
143            Ok("studio".into())
144        );
145    }
146
147    #[test]
148    fn a_value_may_be_composed_from_several_variables_and_literal_text() {
149        // The reason for the braces: without them there is no way to say where
150        // a name ends and the text after it begins.
151        assert_eq!(
152            expand(
153                "https://${HOST}:${PORT}/admit",
154                &[("HOST", "auth.internal"), ("PORT", "8081")]
155            ),
156            Ok("https://auth.internal:8081/admit".into())
157        );
158    }
159
160    #[test]
161    fn an_undefined_variable_is_an_error_rather_than_an_empty_string() {
162        assert_eq!(
163            expand("${MISSING}", &[]),
164            Err(InterpolationError::Undefined("MISSING".into())),
165            "substituting nothing would silently disable the check the value \
166             was protecting"
167        );
168    }
169
170    #[test]
171    fn a_fallback_makes_an_absent_variable_deliberate() {
172        assert_eq!(expand("${MISSING:-local}", &[]), Ok("local".into()));
173        assert_eq!(
174            expand("${MISSING:-}", &[]),
175            Ok(String::new()),
176            "an empty fallback is how an operator asks for empty on purpose"
177        );
178        assert_eq!(
179            expand("${NAME:-local}", &[("NAME", "studio")]),
180            Ok("studio".into()),
181            "a set variable wins over its fallback"
182        );
183        assert_eq!(
184            expand("${NAME:-local}", &[("NAME", "")]),
185            Ok("local".into()),
186            "as in a shell, an empty variable takes the fallback too"
187        );
188        assert_eq!(
189            expand("${NAME}", &[("NAME", "")]),
190            Ok(String::new()),
191            "without a fallback, a deliberately empty variable stays empty"
192        );
193    }
194
195    #[test]
196    fn a_literal_dollar_is_escaped_and_survives_intact() {
197        // A passphrase may legitimately contain a dollar, and interpolating it
198        // would corrupt a working credential.
199        assert_eq!(expand("p$$ssw0rd", &[]), Ok("p$ssw0rd".into()));
200        assert_eq!(expand("$$${NAME}", &[("NAME", "x")]), Ok("$x".into()));
201    }
202
203    #[test]
204    fn a_dollar_that_opens_nothing_is_itself() {
205        assert_eq!(expand("100$ per hour", &[]), Ok("100$ per hour".into()));
206    }
207
208    #[test]
209    fn an_unclosed_reference_is_refused() {
210        assert!(matches!(
211            expand("${NAME", &[("NAME", "x")]),
212            Err(InterpolationError::Unclosed)
213        ));
214    }
215
216    #[test]
217    fn a_record_pattern_passes_through_untouched() {
218        // `record.path` uses bare braces and is expanded per segment by a
219        // different layer. The sigils are distinct so that one cannot eat the
220        // other.
221        let pattern = "{stream}/{time:%Y/%m/%d}/{rendition}_{segment}.m4s";
222        assert_eq!(expand(pattern, &[]), Ok(pattern.to_owned()));
223    }
224
225    #[test]
226    fn only_string_leaves_are_substituted() {
227        let mut document: toml::Value = toml::from_str(
228            r#"
229name = "${NAME}"
230shutdown_grace = "10s"
231streams = 256
232
233[publish]
234codecs = ["${CODEC}", "aac"]
235"#,
236        )
237        .expect("the fixture parses");
238
239        environment(&[("NAME", "studio"), ("CODEC", "opus")])
240            .interpolate(&mut document)
241            .expect("every reference resolves");
242
243        assert_eq!(document["name"].as_str(), Some("studio"));
244        assert_eq!(document["shutdown_grace"].as_str(), Some("10s"));
245        assert_eq!(document["streams"].as_integer(), Some(256));
246        assert_eq!(document["publish"]["codecs"][0].as_str(), Some("opus"));
247        assert_eq!(document["publish"]["codecs"][1].as_str(), Some("aac"));
248    }
249}