Skip to main content

tuwunel_core/config/
normalize.rs

1#[cfg(test)]
2mod tests;
3
4use std::{cell::RefCell, iter::once};
5
6use figment::{
7	Error, Figment, Metadata, Profile, Provider,
8	error::Kind,
9	providers::Env,
10	util::nest,
11	value::{Dict, Map, Tag, Value},
12};
13use serde::de::IgnoredAny;
14use smallstr::SmallString;
15use smallvec::SmallVec;
16
17use super::regenerate::{FieldClass, FieldSpec, SectionSpec, schema};
18use crate::utils::BoolExt as _;
19
20type EnvironmentKey = SmallString<[u8; 64]>;
21
22type SourceData = Map<Profile, Dict>;
23
24type PathKeys<'a> = SmallVec<[&'a str; 4]>;
25
26type Rewrites = SmallVec<[Rewrite; 4]>;
27
28#[derive(Clone)]
29struct Rewrite {
30	profile: Profile,
31	tag: Tag,
32	from: &'static str,
33	to: &'static str,
34}
35
36struct Normalized {
37	data: RefCell<Option<SourceData>>,
38	metadata: Metadata,
39	profile: Option<Profile>,
40	metadata_map: Option<Map<Tag, Metadata>>,
41}
42
43pub(super) fn environment(prefix: &'static str) -> Result<impl Provider, Error> {
44	let aggregate = Env::raw()
45		.filter(move |key| key.starts_with(prefix))
46		.lowercase(false)
47		.iter()
48		.filter_map(|(name, value)| environment_assignment(prefix, name.as_str(), &value))
49		.fold(Figment::new(), Figment::merge);
50
51	let provider = Normalized {
52		data: RefCell::new(Some(aggregate.data()?)),
53		metadata: Env::prefixed(prefix).metadata(),
54		metadata_map: aggregate.__metadata_map(),
55		profile: None,
56	};
57
58	normalize(provider)
59}
60
61fn environment_assignment(prefix: &str, name: &str, value: &str) -> Option<Normalized> {
62	let path = name
63		.get(prefix.len()..)
64		.map(str::trim)
65		.map(|path| path.replace("__", "."))
66		.map(lowercase)
67		.filter(|path| path.split('.').any(str::is_empty).is_false())?;
68
69	let value = value
70		.parse()
71		.expect("environment values parse infallibly");
72
73	let values = nest(&path, value)
74		.into_dict()
75		.expect("nonempty environment path produces a dictionary");
76
77	let name = name.to_owned();
78	let metadata = Metadata::named(format!("environment variable {name}"))
79		.interpolater(move |_, _| name.clone());
80
81	Some(Normalized {
82		data: RefCell::new(Some(Profile::Global.collect(values))),
83		metadata,
84		metadata_map: None,
85		profile: None,
86	})
87}
88
89fn lowercase(mut value: String) -> String {
90	value.make_ascii_lowercase();
91	value
92}
93
94pub(super) fn normalize(provider: impl Provider) -> Result<impl Provider, Error> {
95	normalize_with(provider, schema())
96}
97
98fn normalize_with(
99	provider: impl Provider,
100	sections: &[&SectionSpec],
101) -> Result<Normalized, Error> {
102	let data = provider.data()?;
103	let rewrites = data
104		.iter()
105		.flat_map(|(profile, values)| rewrites_for(profile, values, sections))
106		.collect::<Rewrites>();
107
108	let metadata = provenance(provider.metadata(), &rewrites, Tag::Default);
109	let metadata_map = provider.__metadata_map().map(|metadata| {
110		metadata
111			.into_iter()
112			.map(|(tag, metadata)| (tag, provenance(metadata, &rewrites, tag)))
113			.collect()
114	});
115
116	let data = data
117		.into_iter()
118		.map(|(profile, values)| {
119			normalize_values(values, aliases_in(sections)).map(|values| (profile, values))
120		})
121		.collect::<Result<_, _>>()
122		.map_err(|error| attributed(error, metadata.clone()))?;
123
124	Ok(Normalized {
125		data: RefCell::new(Some(data)),
126		metadata,
127		metadata_map,
128		profile: provider.profile(),
129	})
130}
131
132fn rewrites_for<'a>(
133	profile: &'a Profile,
134	values: &'a Dict,
135	sections: &'a [&'a SectionSpec],
136) -> impl Iterator<Item = Rewrite> + 'a {
137	aliases_in(sections).filter_map(move |(from, field)| {
138		find(values, from).map(|value| Rewrite {
139			profile: profile.clone(),
140			tag: value.tag(),
141			from,
142			to: field.path,
143		})
144	})
145}
146
147impl Provider for Normalized {
148	#[inline]
149	fn metadata(&self) -> Metadata { self.metadata.clone() }
150
151	fn data(&self) -> Result<Map<Profile, Dict>, Error> {
152		self.data
153			.borrow_mut()
154			.take()
155			.ok_or_else(|| Error::from("Normalized configuration source was already consumed."))
156	}
157
158	#[inline]
159	fn profile(&self) -> Option<Profile> { self.profile.clone() }
160
161	#[inline]
162	fn __metadata_map(&self) -> Option<Map<Tag, Metadata>> { self.metadata_map.clone() }
163}
164
165fn aliases() -> impl Iterator<Item = (&'static str, &'static FieldSpec)> + Clone {
166	aliases_in(schema())
167}
168
169fn aliases_in<'a>(
170	sections: &'a [&SectionSpec],
171) -> impl Iterator<Item = (&'static str, &'a FieldSpec)> + Clone {
172	fields(sections).flat_map(|field| {
173		field
174			.legacy
175			.iter()
176			.map(move |from| (*from, field))
177	})
178}
179
180fn fields<'a>(sections: &'a [&SectionSpec]) -> impl Iterator<Item = &'a FieldSpec> + Clone {
181	sections.iter().flat_map(|section| section.fields)
182}
183
184fn provenance(metadata: Metadata, rewrites: &Rewrites, tag: Tag) -> Metadata {
185	let rewrites = rewrites
186		.iter()
187		.filter(|rewrite| rewrite.tag == tag)
188		.cloned()
189		.collect::<Rewrites>();
190
191	let original = metadata.clone();
192
193	metadata.interpolater(move |profile, keys| {
194		let path = keys.join(".");
195		let native = rewrites
196			.iter()
197			.find_map(|rewrite| {
198				profile
199					.eq(&rewrite.profile)
200					.and_then(|| path.strip_prefix(rewrite.to))
201					.filter(|suffix| suffix.is_empty() || suffix.starts_with('.'))
202					.map(|suffix| format!("{}{suffix}", rewrite.from))
203			})
204			.unwrap_or(path);
205
206		let prefix = original
207			.name
208			.strip_prefix('`')
209			.and_then(|name| name.split_once('`'));
210
211		match prefix {
212			| Some((prefix, _)) => format!("{prefix}{}", environment_key(&native)),
213			| None => original.interpolate(profile, &native.split('.').collect::<PathKeys<'_>>()),
214		}
215	})
216}
217
218fn environment_key(native: &str) -> EnvironmentKey {
219	native
220		.chars()
221		.flat_map(|character| {
222			let separator = character == '.';
223			let character = if separator { '_' } else { character.to_ascii_uppercase() };
224
225			once(character).chain(separator.then_some('_'))
226		})
227		.collect()
228}
229
230fn normalize_values<'a, Aliases>(values: Dict, aliases: Aliases) -> Result<Dict, Error>
231where
232	Aliases: Iterator<Item = (&'static str, &'a FieldSpec)> + Clone,
233{
234	aliases.clone().try_for_each(|(from, field)| {
235		let duplicate = field
236			.legacy
237			.iter()
238			.copied()
239			.chain([field.path])
240			.find(|other| *other != from && find(&values, other).is_some());
241
242		duplicate
243			.filter(|_| find(&values, from).is_some())
244			.map_or(Ok(()), |other| {
245				Err(Error::from(format!(
246					"Conflicting configuration paths {from:?} and {other:?}."
247				)))
248			})
249	})?;
250
251	rewrite_values(values, aliases)
252}
253
254fn rewrite_values<'a, Aliases>(values: Dict, mut aliases: Aliases) -> Result<Dict, Error>
255where
256	Aliases: Iterator<Item = (&'static str, &'a FieldSpec)>,
257{
258	aliases.try_fold(values, |mut values, (from, field)| {
259		let Some(value) = take(&mut values, from) else {
260			return Ok(values);
261		};
262
263		insert(&mut values, field.path, value)?;
264		Ok(values)
265	})
266}
267
268fn attributed(mut error: Error, metadata: Metadata) -> Error {
269	error.metadata = Some(metadata);
270	error
271}
272
273pub(super) fn unknown(raw: &Figment) -> impl Iterator<Item = String> + '_ {
274	schema()
275		.iter()
276		.filter(|section| section.group)
277		.flat_map(move |section| unknown_in(raw, section))
278}
279
280#[expect(clippy::zero_sized_map_values)]
281fn unknown_in<'a>(
282	raw: &'a Figment,
283	section: &'static SectionSpec,
284) -> impl Iterator<Item = String> + 'a {
285	let path = section.section.trim_start_matches("global.");
286	let known = move |key: &str| {
287		section
288			.fields
289			.iter()
290			.any(|field| field.name == key)
291	};
292
293	raw.extract_inner(path)
294		.into_iter()
295		.flat_map(move |values: Map<String, IgnoredAny>| {
296			values
297				.into_keys()
298				.filter(move |key| known(key).is_false())
299				.map(move |key| format!("{path}.{key}"))
300		})
301}
302
303/// Omits the contents of errors at, above or below a sensitive field.
304///
305/// A value assigned above a sensitive field, such as a scalar given for its
306/// whole section, can carry the secret into the reported value. Every other
307/// error keeps its detail, so the operator still sees the expected type.
308pub(super) fn redact_error(error: Error) -> Error {
309	error
310		.into_iter()
311		.map(|error| {
312			let sensitive = fields(schema())
313				.filter(|field| field.sensitive)
314				.any(|field| path_overlaps(&error.path, field.path));
315
316			if sensitive { redact_leaf(error) } else { error }
317		})
318		.reduce(Error::chain)
319		.expect("a configuration error has at least one cause")
320}
321
322fn path_overlaps(path: &[String], field: &str) -> bool {
323	if path.is_empty() {
324		return false;
325	}
326
327	path.iter()
328		.zip(field.split('.'))
329		.all(|(part, expected)| part == expected)
330}
331
332fn redact_leaf(mut error: Error) -> Error {
333	error.kind = Kind::Message("invalid configuration value (contents omitted)".to_owned());
334	error
335}
336
337pub(super) fn assert_canonical(raw: &Figment) -> Result<(), Error> {
338	match aliases().find(|(from, _)| raw.contains(from)) {
339		| None => Ok(()),
340		| Some((from, _)) =>
341			Err(format!("Configuration provider was not normalized at {from:?}.").into()),
342	}
343}
344
345pub(super) fn validate_registry(sections: &[&SectionSpec]) {
346	for section in sections {
347		let path = section.section.trim_matches(['[', ']']);
348		let path = path.strip_prefix("global.").unwrap_or(path);
349
350		assert!(!reserved(path), "reserved canonical configuration section");
351		assert!(
352			section
353				.fields
354				.iter()
355				.all(|field| !reserved(field.path)),
356			"reserved canonical configuration field"
357		);
358	}
359
360	for (index, (from, field)) in aliases_in(sections).enumerate() {
361		assert!(
362			aliases_in(sections)
363				.take(index)
364				.all(|(previous, _)| !overlapping(previous, from)),
365			"overlapping legacy configuration path: {from}"
366		);
367		assert!(field.class != FieldClass::Forbidden, "legacy alias targets a forbidden control");
368		assert!(!reserved(from), "reserved legacy configuration path");
369		assert!(
370			valid_source(sections, from, field),
371			"legacy configuration path collides with a canonical field or alias: {from}"
372		);
373	}
374}
375
376fn reserved(path: &str) -> bool { path.split('.').next().eq(&Some("config")) }
377
378fn overlapping(left: &str, right: &str) -> bool {
379	left.split('.')
380		.zip(right.split('.'))
381		.all(|(left, right)| left == right)
382}
383
384fn valid_source(sections: &[&SectionSpec], from: &str, target: &FieldSpec) -> bool {
385	fields(sections).all(|candidate| {
386		let ancestor = from
387			.strip_prefix(candidate.path)
388			.is_some_and(|tail| tail.starts_with('.'));
389
390		let canonical = !overlapping(candidate.path, from)
391			|| (ancestor && registered_group(sections, candidate));
392
393		let aliases = candidate
394			.aliases
395			.iter()
396			.all(|alias| target.path == candidate.path || distinct_alias(candidate, alias, from));
397
398		canonical && aliases
399	})
400}
401
402fn registered_group(sections: &[&SectionSpec], field: &FieldSpec) -> bool {
403	field.class == FieldClass::Structural
404		&& sections.iter().any(|section| {
405			section.group
406				&& section
407					.section
408					.trim_matches(['[', ']'])
409					.strip_prefix("global.")
410					.eq(&Some(field.path))
411		})
412}
413
414fn distinct_alias(field: &FieldSpec, alias: &str, from: &str) -> bool {
415	field
416		.path
417		.rsplit_once('.')
418		.into_iter()
419		.flat_map(|(parent, _)| parent.split('.'))
420		.chain(alias.split('.'))
421		.zip(from.split('.'))
422		.any(|(left, right)| left != right)
423}
424
425fn find<'a>(values: &'a Dict, path: &str) -> Option<&'a Value> {
426	match path.split_once('.') {
427		| None => values.get(path),
428		| Some((head, tail)) => find(values.get(head)?.as_dict()?, tail),
429	}
430}
431
432fn take(values: &mut Dict, path: &str) -> Option<Value> {
433	match path.split_once('.') {
434		| None => values.remove(path),
435		| Some((head, tail)) => {
436			let Value::Dict(_, children) = values.get_mut(head)? else {
437				return None;
438			};
439
440			take(children, tail)
441		},
442	}
443}
444
445fn insert(values: &mut Dict, path: &str, value: Value) -> Result<(), Error> {
446	let Some((head, tail)) = path.split_once('.') else {
447		values.insert(path.to_owned(), value);
448		return Ok(());
449	};
450
451	let child = values
452		.entry(head.to_owned())
453		.or_insert_with(|| Value::Dict(value.tag(), Dict::new()));
454
455	let Value::Dict(_, children) = child else {
456		return Err(
457			format!("Configuration path {path:?} encounters scalar ancestor {head:?}.").into()
458		);
459	};
460
461	insert(children, tail, value)
462}