1use std::{
2 cmp::Ordering,
3 fmt::Write as _,
4 iter::once,
5 path::{Path, PathBuf},
6 sync::LazyLock,
7};
8
9mod overlay;
10#[cfg(test)]
11mod tests;
12mod tree;
13mod write;
14
15use figment::{
16 Figment,
17 providers::{Data, Format as _},
18 value::{Dict, Value},
19};
20use itertools::Itertools as _;
21use link_section::TypedSection;
22use serde::Serialize as _;
23use smallvec::SmallVec;
24use toml::{Value as TomlValue, ser::ValueSerializer};
25use toml_writer::TomlWrite as _;
26
27use self::{
28 overlay::{filter_nonconfig_environment, is_file_value, validate_file_overlay},
29 tree::{
30 ConfigPath, Instance, PathPart, find_path, normalize_aliases, remove_path,
31 resolve_instances,
32 },
33 write::write_atomic,
34};
35use super::{Config, DEPRECATED_KEYS, Sources, format::Toml, normalize::validate_registry};
36use crate::{Err, Result, err, implement, utils::BoolExt};
37
38const NEVER_EMIT: [&str; 2] = ["database_restore_backup", "force_migration"];
39
40#[derive(Clone, Copy, Debug, Eq, PartialEq)]
41pub(super) enum FieldClass {
42 Documented,
43 Structural,
44 Hidden,
45 Forbidden,
46}
47
48#[derive(Clone, Copy, Debug)]
49pub(super) struct FieldSpec {
50 pub(super) name: &'static str,
51 pub(super) path: &'static str,
52 pub(super) legacy: &'static [&'static str],
53 pub(super) aliases: &'static [&'static str],
54 pub(super) example: &'static str,
55 pub(super) class: FieldClass,
56 pub(super) sensitive: bool,
57}
58
59#[derive(Clone, Copy, Debug)]
60pub(super) struct SectionSpec {
61 pub(super) section: &'static str,
62 pub(super) aliases: &'static [&'static str],
63 pub(super) about: &'static str,
64 pub(super) example: &'static str,
65 pub(super) fields: &'static [FieldSpec],
66 pub(super) group: bool,
67}
68
69#[derive(Clone, Copy, Debug, Default)]
74pub struct RegenerateOptions<'a> {
75 pub output: Option<&'a Path>,
80
81 pub force: bool,
86
87 pub include_env: bool,
92
93 pub strip_unknown: bool,
98}
99
100#[derive(Clone, Copy, Debug, Eq, PartialEq)]
105pub enum Overwrite {
106 Deny,
110
111 Allow,
115}
116
117#[derive(Debug)]
123pub struct RegenerationSummary {
124 output: PathBuf,
125 input_count: usize,
126 configured: usize,
127 residue: usize,
128 dropped: [bool; NEVER_EMIT.len()],
129}
130
131#[derive(Default)]
132struct RenderStats {
133 configured: usize,
134 residue: usize,
135 dropped: [bool; NEVER_EMIT.len()],
136}
137
138struct RenderContext<'a> {
139 environment: Option<(&'a Figment, &'a Dict)>,
140 strip_unknown: bool,
141 expected: &'a mut Dict,
142 stats: &'a mut RenderStats,
143}
144
145#[derive(Clone, Copy)]
146enum Block<'a, 'v> {
147 Instance(&'a Instance<'v>),
148 Environment(&'a Instance<'v>, (&'a Figment, &'a Dict)),
149 Template,
150}
151
152#[derive(Clone, Copy)]
153enum ResidueKind {
154 Deprecated,
155 Hidden,
156 Unknown,
157}
158
159#[derive(Clone, Copy)]
160enum ResidueDisposition {
161 Active,
162 Commented,
163}
164
165#[link_section::section(typed)]
166pub(super) static REGISTERED_SECTIONS: TypedSection<SectionSpec>;
167
168type MetadataKeys<'a> = SmallVec<[&'a str; 4]>;
169
170type OrderedSections = SmallVec<[&'static SectionSpec; 16]>;
171
172static ORDERED_SECTIONS: LazyLock<OrderedSections> = LazyLock::new(ordered_sections);
173
174#[inline]
175pub(super) fn schema() -> &'static [&'static SectionSpec] { ORDERED_SECTIONS.as_slice() }
176
177fn ordered_sections() -> OrderedSections {
178 let mut sections = REGISTERED_SECTIONS
179 .as_slice()
180 .iter()
181 .collect::<OrderedSections>();
182
183 sections.sort_unstable_by_key(|section| section.section.trim_matches(['[', ']']));
185 validate_schema(§ions);
186
187 sections
188}
189
190fn validate_schema(sections: &[&SectionSpec]) {
191 validate_registry(sections);
192 let first = sections
193 .first()
194 .expect("configuration schema must contain the global section");
195
196 assert_eq!(first.section, "global", "global must be the first configuration section");
197
198 for (index, section) in sections.iter().enumerate() {
199 assert!(
200 sections[..index]
201 .iter()
202 .all(|previous| previous.section != section.section),
203 "configuration section {:?} is registered more than once",
204 section.section,
205 );
206 }
207}
208
209pub fn example_config() -> Result<String> {
214 let values = Dict::new();
215 let mut expected = Dict::new();
216 let mut stats = RenderStats::default();
217 let rendered = {
218 let mut context = RenderContext {
219 environment: None,
220 strip_unknown: false,
221 expected: &mut expected,
222 stats: &mut stats,
223 };
224
225 render_schema(&values, &mut context)?
226 };
227
228 Ok(rendered)
229}
230
231pub fn write_example_config(path: &Path, overwrite: Overwrite) -> Result {
236 let rendered = example_config()?;
237
238 write_atomic(path, rendered.as_bytes(), matches!(overwrite, Overwrite::Allow))
239}
240
241pub fn regenerate_config(
246 sources: &Sources,
247 options: RegenerateOptions<'_>,
248) -> Result<RegenerationSummary> {
249 let paths = sources.file_paths().collect_vec();
250 let input_count = paths.iter().sorted_unstable().dedup().count();
251
252 if paths.is_empty() {
253 return Err!("Configuration regeneration requires at least one input file.");
254 }
255
256 if input_count > 1 && options.output.is_none() {
257 return Err!(
258 "Layered configuration files require an explicit output path because they are \
259 collapsed into one document."
260 );
261 }
262
263 let output = options
264 .output
265 .map(Path::to_path_buf)
266 .unwrap_or_else(|| adjacent_new_path(&paths[0]));
267
268 let files = Config::load_files(paths.iter().map(PathBuf::as_path))?;
269 validate_file_overlay(&files)?;
270
271 let file_values = options
272 .include_env
273 .is_false()
274 .then(|| files.extract::<Dict>())
275 .transpose()?;
276
277 let effective = Config::merge_environment(files)?;
278
279 Config::new(&effective)?;
280
281 let mut values = match file_values {
282 | Some(values) => values,
283 | None => {
284 let mut values = effective.extract::<Dict>()?;
285
286 filter_nonconfig_environment(&effective, &mut values)?;
287 values
288 },
289 };
290
291 normalize_aliases(&mut values, schema());
292
293 let effective_values = options
294 .include_env
295 .is_false()
296 .then(|| effective.extract::<Dict>())
297 .transpose()?
298 .map(|mut values| {
299 normalize_aliases(&mut values, schema());
300
301 values
302 });
303
304 let mut expected = values.clone();
305 let mut stats = RenderStats::default();
306 let rendered = {
307 let mut context = RenderContext {
308 environment: Some((&effective, effective_values.as_ref().unwrap_or(&values))),
309 strip_unknown: options.strip_unknown,
310 expected: &mut expected,
311 stats: &mut stats,
312 };
313
314 render_schema(&values, &mut context)?
315 };
316
317 verify_rendered(&rendered, &expected)?;
318 write_atomic(&output, rendered.as_bytes(), options.force)?;
319 verify_file(&output, &expected).map_err(|error| {
320 err!(
321 "Configuration was written to {} but post-write verification failed. Inspect the \
322 written file and restore its adjacent `.bak` backup if present before retrying: \
323 {error}",
324 output.display(),
325 )
326 })?;
327
328 let summary = RegenerationSummary {
329 output,
330 input_count,
331 configured: stats.configured,
332 residue: stats.residue,
333 dropped: stats.dropped,
334 };
335
336 Ok(summary)
337}
338
339#[implement(RegenerationSummary)]
344#[inline]
345#[must_use]
346pub fn output(&self) -> &Path { &self.output }
347
348#[implement(RegenerationSummary)]
353#[inline]
354#[must_use]
355pub fn input_count(&self) -> usize { self.input_count }
356
357#[implement(RegenerationSummary)]
361#[inline]
362#[must_use]
363pub fn configured(&self) -> usize { self.configured }
364
365#[implement(RegenerationSummary)]
369#[inline]
370#[must_use]
371pub fn residue(&self) -> usize { self.residue }
372
373#[implement(RegenerationSummary)]
378pub fn dropped_keys(&self) -> impl Iterator<Item = &'static str> + '_ {
379 NEVER_EMIT
380 .into_iter()
381 .zip(self.dropped)
382 .filter_map(|(key, dropped)| dropped.then_some(key))
383}
384
385fn render_schema(values: &Dict, context: &mut RenderContext<'_>) -> Result<String> {
386 let schema = schema();
387 let capacity = schema
388 .iter()
389 .flat_map(|spec| [spec.about, spec.example])
390 .map(str::len)
391 .sum();
392
393 schema
394 .iter()
395 .try_fold(String::with_capacity(capacity), |output, &spec| {
396 render_section(output, spec, values, context)
397 })
398}
399
400fn render_section(
401 output: String,
402 spec: &SectionSpec,
403 values: &Dict,
404 context: &mut RenderContext<'_>,
405) -> Result<String> {
406 let environment = context.environment;
407 let instances = resolve_instances(spec, values);
408 let environment_instances = environment
409 .map(|(_, environment_values)| resolve_instances(spec, environment_values))
410 .unwrap_or_default();
411
412 let rendered = instances.is_empty().is_false()
413 || environment_instances
414 .iter()
415 .any(|candidate| is_unrendered(&instances, candidate));
416
417 let templated = is_dynamic(spec.section) || rendered.is_false();
418 let environment_blocks = environment_instances
419 .iter()
420 .filter(|candidate| is_unrendered(&instances, candidate))
421 .filter_map(|candidate| {
422 environment.map(|environment| Block::Environment(candidate, environment))
423 });
424
425 instances
426 .iter()
427 .map(Block::Instance)
428 .chain(environment_blocks)
429 .chain(templated.then_some(Block::Template))
430 .enumerate()
431 .try_fold(output, |output, (index, block)| {
432 render_block(output, index, spec, block, context)
433 })
434}
435
436fn is_unrendered<'v>(instances: &[Instance<'v>], candidate: &Instance<'v>) -> bool {
437 instances
438 .iter()
439 .all(|instance| instance.path != candidate.path)
440}
441
442fn render_block(
443 mut output: String,
444 index: usize,
445 spec: &SectionSpec,
446 block: Block<'_, '_>,
447 context: &mut RenderContext<'_>,
448) -> Result<String> {
449 let lead = if index == 0 { spec.about } else { "\n\n" };
450
451 output.push_str(lead);
452 match block {
453 | Block::Instance(instance) => render_instance(&mut output, spec, instance, context)?,
454 | Block::Environment(instance, environment) =>
455 render_environment_instance(&mut output, spec, instance, environment)?,
456 | Block::Template => output.push_str(spec.example),
457 }
458
459 Ok(output)
460}
461
462fn render_instance(
463 output: &mut String,
464 spec: &SectionSpec,
465 instance: &Instance<'_>,
466 context: &mut RenderContext<'_>,
467) -> Result {
468 for line in spec.example.split_inclusive('\n') {
469 let body = line.strip_suffix('\n').unwrap_or(line);
470
471 if is_template_header(body, spec.section) {
472 write_active_header(output, spec.section, &instance.section);
473 if line.ends_with('\n') {
474 output.push('\n');
475 }
476
477 continue;
478 }
479
480 let Some(name) = assignment_name(body) else {
481 output.push_str(line);
482 continue;
483 };
484
485 let Some(field) = spec
486 .fields
487 .iter()
488 .find(|field| field.class == FieldClass::Documented && field.name == name)
489 else {
490 output.push_str(line);
491 continue;
492 };
493
494 let path = field_path(&instance.path, field.name);
495 annotate_environment(
496 output,
497 context.environment,
498 &path,
499 instance.values.get(field.name),
500 )?;
501
502 match instance.values.get(field.name) {
503 | None => output.push_str(line),
504 | Some(value) => {
505 write_assignment(output, field.name, value)?;
506 context.stats.configured = context.stats.configured.saturating_add(1);
507 },
508 }
509 }
510
511 render_unlisted_fields(output, spec, instance, context)
512}
513
514#[cfg(test)]
515pub(super) fn render_fixture(spec: &SectionSpec, values: &Dict) -> Result<String> {
516 let mut output = String::new();
517 let mut expected = Dict::new();
518 let mut stats = RenderStats::default();
519 let mut context = RenderContext {
520 environment: None,
521 strip_unknown: false,
522 expected: &mut expected,
523 stats: &mut stats,
524 };
525
526 for instance in resolve_instances(spec, values) {
527 render_instance(&mut output, spec, &instance, &mut context)?;
528 }
529
530 Ok(output)
531}
532
533fn render_environment_instance(
534 output: &mut String,
535 spec: &SectionSpec,
536 instance: &Instance<'_>,
537 environment: (&Figment, &Dict),
538) -> Result {
539 for line in spec.example.split_inclusive('\n') {
540 let body = line.strip_suffix('\n').unwrap_or(line);
541
542 if is_template_header(body, spec.section) {
543 output.push('#');
544 write_active_header(output, spec.section, &instance.section);
545 if line.ends_with('\n') {
546 output.push('\n');
547 }
548
549 continue;
550 }
551
552 if let Some(field) = assignment_name(body).and_then(|name| {
553 spec.fields
554 .iter()
555 .find(|field| field.class == FieldClass::Documented && field.name == name)
556 }) {
557 let path = field_path(&instance.path, field.name);
558
559 annotate_environment(output, Some(environment), &path, None)?;
560 }
561
562 output.push_str(line);
563 }
564
565 for field in spec
566 .fields
567 .iter()
568 .filter(|field| field.class == FieldClass::Hidden)
569 {
570 let path = field_path(&instance.path, field.name);
571
572 render_hidden_environment(output, field, Some(environment), &path)?;
573 }
574
575 Ok(())
576}
577
578fn render_unlisted_fields(
579 output: &mut String,
580 spec: &SectionSpec,
581 instance: &Instance<'_>,
582 context: &mut RenderContext<'_>,
583) -> Result {
584 for field in spec.fields {
585 let Some(value) = instance.values.get(field.name) else {
586 if field.class == FieldClass::Hidden {
587 let path = field_path(&instance.path, field.name);
588
589 render_hidden_environment(output, field, context.environment, &path)?;
590 }
591
592 continue;
593 };
594
595 let path = field_path(&instance.path, field.name);
596
597 match field.class {
598 | FieldClass::Documented | FieldClass::Structural => {},
599 | FieldClass::Hidden => {
600 annotate_environment(output, context.environment, &path, Some(value))?;
601 render_residue(
602 output,
603 field.name,
604 value,
605 ResidueKind::Hidden,
606 ResidueDisposition::Active,
607 )?;
608
609 context.stats.residue = context.stats.residue.saturating_add(1);
610 },
611 | FieldClass::Forbidden => {
612 remove_path(context.expected, &path);
613 mark_dropped(context.stats, field.name);
614 },
615 }
616 }
617
618 for (name, value) in instance.values {
619 if spec.fields.iter().any(|field| field.name == name) {
620 continue;
621 }
622
623 let path = field_path(&instance.path, name);
624 let kind = is_deprecated(&path)
625 .then_some(ResidueKind::Deprecated)
626 .unwrap_or(ResidueKind::Unknown);
627
628 let disposition = if context.strip_unknown {
629 ResidueDisposition::Commented
630 } else {
631 ResidueDisposition::Active
632 };
633
634 annotate_environment(output, context.environment, &path, Some(value))?;
635 render_residue(output, name, value, kind, disposition)?;
636 context.stats.residue = context.stats.residue.saturating_add(1);
637
638 if context.strip_unknown {
639 remove_path(context.expected, &path);
640 }
641 }
642
643 Ok(())
644}
645
646fn render_hidden_environment(
647 output: &mut String,
648 field: &FieldSpec,
649 environment: Option<(&Figment, &Dict)>,
650 path: &[PathPart<'_>],
651) -> Result {
652 let Some((figment, value)) = environment_value(environment, path) else {
653 return Ok(());
654 };
655
656 writeln!(
657 output,
658 "\n# UNDOCUMENTED: `{}` is valid but omitted from the example configuration.",
659 field.name
660 )
661 .expect("written to configuration buffer");
662
663 output.push_str("# currently set by ");
664 write_environment_name(output, figment, value, path);
665 output.push_str(".\n");
666
667 match field.example {
668 | "" => writeln!(output, "#{} =", field.name),
669 | example => writeln!(output, "#{} = {example}", field.name),
670 }
671 .expect("written to configuration buffer");
672
673 Ok(())
674}
675
676fn render_residue(
677 output: &mut String,
678 name: &str,
679 value: &Value,
680 kind: ResidueKind,
681 disposition: ResidueDisposition,
682) -> Result {
683 match kind {
684 | ResidueKind::Hidden => writeln!(
685 output,
686 "\n# UNDOCUMENTED: `{name}` is valid but omitted from the example configuration."
687 )
688 .expect("written to configuration buffer"),
689 | ResidueKind::Deprecated => {
690 writeln!(
691 output,
692 "\n# DEPRECATED: `{name}` is no longer used by tuwunel and is ignored."
693 )
694 .expect("written to configuration buffer");
695
696 writeln!(output, "# Preserved from the previous configuration; it can be deleted.")
697 .expect("written to configuration buffer");
698 },
699 | ResidueKind::Unknown => {
700 writeln!(output, "\n# UNKNOWN: `{name}` is not a tuwunel configuration option.")
701 .expect("written to configuration buffer");
702
703 writeln!(output, "# Preserved from the previous configuration.")
704 .expect("written to configuration buffer");
705 },
706 }
707
708 if matches!(disposition, ResidueDisposition::Commented) {
709 output.push('#');
710 }
711
712 write_assignment(output, name, value)?;
713
714 Ok(())
715}
716
717fn annotate_environment(
718 output: &mut String,
719 environment: Option<(&Figment, &Dict)>,
720 path: &[PathPart<'_>],
721 file_value: Option<&Value>,
722) -> Result {
723 let Some((figment, value)) = environment_value(environment, path) else {
724 return Ok(());
725 };
726
727 let action = match file_value {
728 | None => "currently set by",
729 | Some(value) if is_file_value(figment, value) => "currently overridden by",
730 | Some(_) => "materialized from",
731 };
732
733 write!(output, "# {action} ").expect("written to configuration buffer");
734 write_environment_name(output, figment, value, path);
735 output.push_str(".\n");
736
737 Ok(())
738}
739
740fn environment_value<'a>(
741 environment: Option<(&'a Figment, &'a Dict)>,
742 path: &[PathPart<'_>],
743) -> Option<(&'a Figment, &'a Value)> {
744 let (figment, values) = environment?;
745
746 find_path(values, path)
747 .filter(|value| !is_file_value(figment, value))
748 .map(|value| (figment, value))
749}
750
751fn write_assignment(output: &mut String, name: &str, value: &Value) -> Result {
752 output
753 .key(name)
754 .expect("written to configuration buffer");
755
756 output.push_str(" = ");
757 write_value(output, value)?;
758 output.push('\n');
759
760 Ok(())
761}
762
763fn write_value(output: &mut String, value: &Value) -> Result {
764 value
765 .serialize(ValueSerializer::new(output))
766 .map_err(|error| err!("Failed to serialize a configuration value: {error}"))?;
767
768 Ok(())
769}
770
771fn assignment_name(line: &str) -> Option<&str> {
772 let (name, _) = line.strip_prefix('#')?.split_once(" =")?;
773
774 name.chars()
775 .all(|character| {
776 character.is_ascii_lowercase() || character.is_ascii_digit() || character == '_'
777 })
778 .then_some(name)
779}
780
781fn is_template_header(line: &str, section: &str) -> bool {
782 match section == "global" {
783 | true => line == "[global]",
784 | false => line
785 .strip_prefix("#[")
786 .and_then(|line| line.strip_suffix(']'))
787 .is_some_and(|line| line == section),
788 }
789}
790
791fn write_active_header(output: &mut String, section: &str, resolved: &str) {
792 if section.starts_with('[') {
793 write!(output, "[[{resolved}]]").expect("written to configuration buffer");
794 } else {
795 write!(output, "[{resolved}]").expect("written to configuration buffer");
796 }
797}
798
799fn is_dynamic(section: &str) -> bool { section.contains('<') || section.starts_with('[') }
800
801fn field_path<'a>(base: &ConfigPath<'a>, field: &'a str) -> ConfigPath<'a> {
802 base.iter()
803 .copied()
804 .chain(once(PathPart::Key(field)))
805 .collect()
806}
807
808fn is_deprecated(path: &[PathPart<'_>]) -> bool {
809 DEPRECATED_KEYS.iter().any(|deprecated| {
810 deprecated
811 .split('.')
812 .eq(path.iter().filter_map(|part| match part {
813 | PathPart::Key(key) => Some(*key),
814 | PathPart::Index(_) => None,
815 }))
816 })
817}
818
819fn mark_dropped(stats: &mut RenderStats, name: &str) {
820 if let Some(index) = NEVER_EMIT.iter().position(|key| *key == name) {
821 stats.dropped[index] = true;
822 }
823}
824
825fn write_environment_name(
826 output: &mut String,
827 figment: &Figment,
828 value: &Value,
829 path: &[PathPart<'_>],
830) {
831 if let Some(metadata) = figment.get_metadata(value.tag()) {
832 let keys = path
833 .iter()
834 .filter_map(|part| match part {
835 | PathPart::Key(key) => Some(*key),
836 | PathPart::Index(_) => None,
837 })
838 .collect::<MetadataKeys<'_>>();
839
840 let profile = value
841 .tag()
842 .profile()
843 .unwrap_or_else(|| figment.profile().clone());
844
845 output.push_str(&metadata.interpolate(&profile, &keys));
846 }
847}
848
849fn verify_rendered(rendered: &str, expected: &Dict) -> Result {
850 let output = Figment::new().merge(Data::nested(Toml::string(rendered)));
851 let actual = output.extract::<Dict>()?;
852
853 if !toml_equivalent(&actual, expected)? {
854 return Err!("Regenerated configuration failed its semantic round-trip check.");
855 }
856
857 Ok(())
858}
859
860fn verify_file(path: &Path, expected: &Dict) -> Result {
861 let output = Config::load_files([path].into_iter())?;
862 let actual = output.extract::<Dict>()?;
863
864 if !toml_equivalent(&actual, expected)? {
865 return Err!("Written configuration failed its semantic round-trip check.");
866 }
867
868 Ok(())
869}
870
871fn toml_equivalent(left: &Dict, right: &Dict) -> Result<bool> {
872 let left = TomlValue::try_from(left)
873 .map_err(|error| err!("Failed to normalize regenerated values: {error}"))?;
874
875 let right = TomlValue::try_from(right)
876 .map_err(|error| err!("Failed to normalize expected values: {error}"))?;
877
878 Ok(toml_values_equivalent(&left, &right))
879}
880
881fn toml_values_equivalent(left: &TomlValue, right: &TomlValue) -> bool {
882 match (left, right) {
883 | (TomlValue::Float(left), TomlValue::Float(right)) =>
884 left.is_nan() && right.is_nan()
885 || left
886 .partial_cmp(right)
887 .is_some_and(Ordering::is_eq),
888 | (TomlValue::Array(left), TomlValue::Array(right)) =>
889 left.len() == right.len()
890 && left
891 .iter()
892 .zip(right)
893 .all(|(left, right)| toml_values_equivalent(left, right)),
894 | (TomlValue::Table(left), TomlValue::Table(right)) =>
895 left.len() == right.len()
896 && left.iter().all(|(key, left)| {
897 right
898 .get(key)
899 .is_some_and(|right| toml_values_equivalent(left, right))
900 }),
901 | _ => left == right,
902 }
903}
904
905fn adjacent_new_path(input: &Path) -> PathBuf {
906 let mut output = input.as_os_str().to_owned();
907
908 output.push(".new");
909
910 output.into()
911}