1use 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
18pub 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 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 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 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 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 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 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 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 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 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}