Skip to main content

flux_bin/config/
value.rs

1//! Untyped configuration values that remember where they were written.
2//!
3//! Configuration files are parsed into [`ConfigValue`] trees in which every node carries its
4//! [`Location`]. Trees from different files are merged and then deserialized into typed settings.
5//! Deserialization errors point to the location of the offending value, and fields of type
6//! [`Located<T>`] keep the location of their value, e.g., to resolve a relative path against the
7//! file that defines it.
8
9use std::{
10    collections::{BTreeMap, btree_map},
11    fmt, fs,
12    marker::PhantomData,
13    ops::Range,
14    vec,
15};
16
17use anyhow::{Context, bail};
18use cargo_metadata::camino::{Utf8Path, Utf8PathBuf};
19use serde::{
20    Deserialize, Deserializer,
21    de::{
22        self, DeserializeOwned, DeserializeSeed, IgnoredAny, IntoDeserializer, MapAccess,
23        SeqAccess, Visitor,
24        value::{MapDeserializer, StrDeserializer},
25    },
26    forward_to_deserialize_any,
27};
28use toml::{
29    Spanned,
30    de::{DeTable, DeValue},
31};
32
33/// Where a configuration value was written.
34#[derive(Clone, Debug)]
35pub struct Location {
36    /// The configuration file, `<base>/<dir>/config.toml`, where `<dir>` is `.flux` or the Flux
37    /// home.
38    path: Utf8PathBuf,
39    /// Byte range of the value in the file.
40    span: Range<usize>,
41}
42
43impl Location {
44    /// Directory that relative paths resolve against: the parent of the directory containing the
45    /// file.
46    fn base(&self) -> &Utf8Path {
47        let dir = self.path.parent().unwrap_or(&self.path);
48        dir.parent().unwrap_or(dir)
49    }
50}
51
52impl fmt::Display for Location {
53    /// Formats the location as `path:line:column`. The file is read again to find the line and
54    /// column, which only happens when reporting errors.
55    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
56        let line_column = fs::read_to_string(&self.path)
57            .ok()
58            .and_then(|contents| line_column(&contents, self.span.start));
59        match line_column {
60            Some((line, column)) => write!(f, "{}:{line}:{column}", self.path),
61            None => write!(f, "{}", self.path),
62        }
63    }
64}
65
66/// One-based line and column of the byte `offset` in `contents`.
67fn line_column(contents: &str, offset: usize) -> Option<(usize, usize)> {
68    let before = contents.get(..offset)?;
69    let line_start = before.rfind('\n').map_or(0, |i| i + 1);
70    Some((before.matches('\n').count() + 1, before[line_start..].chars().count() + 1))
71}
72
73/// A configuration value together with its [`Location`]. It can only be deserialized from a
74/// [`ConfigValue`].
75#[derive(Clone, Debug)]
76pub struct Located<T> {
77    pub value: T,
78    pub location: Location,
79}
80
81impl Located<Utf8PathBuf> {
82    /// Resolves the path against the directory of the file that defines it.
83    pub fn resolve(&self) -> Utf8PathBuf {
84        self.location.base().join(&self.value)
85    }
86}
87
88/// Name and fields of the struct through which a [`ConfigValue`] hands a value and its location to
89/// [`Located`]. They cannot clash with the name of any other struct.
90const LOCATED: &str = "$__flux_private_Located";
91const VALUE_FIELD: &str = "$__flux_private_value";
92const LOCATION_FIELD: &str = "$__flux_private_location";
93
94impl<'de, T: Deserialize<'de>> Deserialize<'de> for Located<T> {
95    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
96        struct LocatedVisitor<T>(PhantomData<T>);
97
98        impl<'de, T: Deserialize<'de>> Visitor<'de> for LocatedVisitor<T> {
99            type Value = Located<T>;
100
101            fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
102                f.write_str("a value from a configuration file")
103            }
104
105            fn visit_map<A: MapAccess<'de>>(self, mut map: A) -> Result<Located<T>, A::Error> {
106                let (_, value) = map
107                    .next_entry::<IgnoredAny, T>()?
108                    .ok_or_else(|| de::Error::missing_field(VALUE_FIELD))?;
109                let (_, (path, start, end)) = map
110                    .next_entry::<IgnoredAny, (Utf8PathBuf, usize, usize)>()?
111                    .ok_or_else(|| de::Error::missing_field(LOCATION_FIELD))?;
112                Ok(Located { value, location: Location { path, span: start..end } })
113            }
114        }
115
116        deserializer.deserialize_struct(
117            LOCATED,
118            &[VALUE_FIELD, LOCATION_FIELD],
119            LocatedVisitor(PhantomData),
120        )
121    }
122}
123
124/// An untyped configuration value. Every node remembers its [`Location`].
125#[derive(Clone, Debug)]
126pub enum ConfigValue {
127    String(String, Location),
128    Integer(i64, Location),
129    Boolean(bool, Location),
130    List(Vec<ConfigValue>, Location),
131    Table(BTreeMap<String, ConfigValue>, Location),
132}
133
134impl ConfigValue {
135    /// Parses a configuration file.
136    pub fn parse_file(path: &Utf8Path) -> anyhow::Result<ConfigValue> {
137        let contents =
138            fs::read_to_string(path).with_context(|| format!("failed to read `{path}`"))?;
139        let table =
140            DeTable::parse(&contents).with_context(|| format!("failed to parse `{path}`"))?;
141        let location = Location { path: path.to_owned(), span: table.span() };
142        Self::from_table(table.into_inner(), location)
143    }
144
145    fn from_spanned(value: Spanned<DeValue>, path: &Utf8Path) -> anyhow::Result<ConfigValue> {
146        let location = Location { path: path.to_owned(), span: value.span() };
147        Ok(match value.into_inner() {
148            DeValue::String(s) => ConfigValue::String(s.into_owned(), location),
149            DeValue::Integer(i) => {
150                let Ok(i) = i64::from_str_radix(i.as_str(), i.radix()) else {
151                    bail!("{location}: integer out of range");
152                };
153                ConfigValue::Integer(i, location)
154            }
155            DeValue::Boolean(b) => ConfigValue::Boolean(b, location),
156            DeValue::Array(array) => {
157                let items = array
158                    .into_iter()
159                    .map(|item| Self::from_spanned(item, path))
160                    .collect::<anyhow::Result<_>>()?;
161                ConfigValue::List(items, location)
162            }
163            DeValue::Table(table) => Self::from_table(table, location)?,
164            DeValue::Float(_) => bail!("{location}: floats are not supported"),
165            DeValue::Datetime(_) => bail!("{location}: dates and times are not supported"),
166        })
167    }
168
169    fn from_table(table: DeTable, location: Location) -> anyhow::Result<ConfigValue> {
170        let entries = table
171            .into_iter()
172            .map(|(key, value)| {
173                Ok((key.into_inner().into_owned(), Self::from_spanned(value, &location.path)?))
174            })
175            .collect::<anyhow::Result<_>>()?;
176        Ok(ConfigValue::Table(entries, location))
177    }
178
179    pub fn location(&self) -> &Location {
180        match self {
181            ConfigValue::String(_, location)
182            | ConfigValue::Integer(_, location)
183            | ConfigValue::Boolean(_, location)
184            | ConfigValue::List(_, location)
185            | ConfigValue::Table(_, location) => location,
186        }
187    }
188
189    fn kind(&self) -> &'static str {
190        match self {
191            ConfigValue::Table(..) => "a table",
192            ConfigValue::List(..) => "an array",
193            _ => "a value",
194        }
195    }
196
197    /// Removes `key` if `self` is a table.
198    pub fn remove(&mut self, key: &str) -> Option<ConfigValue> {
199        match self {
200            ConfigValue::Table(entries, _) => entries.remove(key),
201            _ => None,
202        }
203    }
204
205    /// Merges values ordered from lowest to highest precedence. Returns `None` if there are none.
206    pub fn merge_all(
207        values: impl IntoIterator<Item = ConfigValue>,
208    ) -> anyhow::Result<Option<ConfigValue>> {
209        let mut merged: Option<ConfigValue> = None;
210        for value in values {
211            match &mut merged {
212                Some(merged) => merged.merge(value, "")?,
213                None => merged = Some(value),
214            }
215        }
216        Ok(merged)
217    }
218
219    /// Merges `src` into `self`, where `src` has higher precedence. Tables are merged key by key,
220    /// arrays are concatenated, and any other value is replaced.
221    fn merge(&mut self, src: ConfigValue, key: &str) -> anyhow::Result<()> {
222        match (self, src) {
223            (ConfigValue::Table(dst, _), ConfigValue::Table(src, _)) => {
224                for (src_key, src_value) in src {
225                    let full_key =
226                        if key.is_empty() { src_key.clone() } else { format!("{key}.{src_key}") };
227                    match dst.get_mut(&src_key) {
228                        Some(dst_value) => dst_value.merge(src_value, &full_key)?,
229                        None => {
230                            dst.insert(src_key, src_value);
231                        }
232                    }
233                }
234            }
235            (ConfigValue::List(dst, _), ConfigValue::List(src, _)) => dst.extend(src),
236            (dst, src) if dst.kind() == src.kind() => *dst = src,
237            (dst, src) => {
238                bail!(
239                    "`{key}` is {} in {} but {} in {}",
240                    dst.kind(),
241                    dst.location(),
242                    src.kind(),
243                    src.location()
244                );
245            }
246        }
247        Ok(())
248    }
249
250    /// Deserializes the value into `T`.
251    pub fn deserialize_into<T: DeserializeOwned>(self) -> Result<T, ConfigError> {
252        let location = self.location().clone();
253        T::deserialize(self).map_err(|err| err.at_location(&location))
254    }
255}
256
257/// An error deserializing a [`ConfigValue`].
258#[derive(Debug)]
259pub struct ConfigError {
260    message: String,
261    /// Keys leading to the value that caused the error, outermost first.
262    keys: Vec<String>,
263    /// Location of the value that caused the error.
264    location: Option<Location>,
265}
266
267impl ConfigError {
268    /// Records that the error happened inside the value of `key`.
269    fn in_key(mut self, key: &str) -> Self {
270        self.keys.insert(0, key.to_owned());
271        self
272    }
273
274    /// Records the location of the error unless a more precise one is already known.
275    fn at_location(mut self, location: &Location) -> Self {
276        self.location.get_or_insert_with(|| location.clone());
277        self
278    }
279}
280
281impl de::Error for ConfigError {
282    fn custom<T: fmt::Display>(msg: T) -> Self {
283        ConfigError { message: msg.to_string(), keys: vec![], location: None }
284    }
285}
286
287impl fmt::Display for ConfigError {
288    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
289        if let Some(location) = &self.location {
290            write!(f, "{location}: ")?;
291        }
292        if !self.keys.is_empty() {
293            write!(f, "`{}`: ", self.keys.join("."))?;
294        }
295        write!(f, "{}", self.message)
296    }
297}
298
299impl std::error::Error for ConfigError {}
300
301impl<'de> Deserializer<'de> for ConfigValue {
302    type Error = ConfigError;
303
304    fn deserialize_any<V: Visitor<'de>>(self, visitor: V) -> Result<V::Value, ConfigError> {
305        match self {
306            ConfigValue::String(s, _) => visitor.visit_string(s),
307            ConfigValue::Integer(i, _) => visitor.visit_i64(i),
308            ConfigValue::Boolean(b, _) => visitor.visit_bool(b),
309            ConfigValue::List(items, _) => {
310                visitor.visit_seq(ListAccess { items: items.into_iter() })
311            }
312            ConfigValue::Table(entries, _) => {
313                visitor.visit_map(TableAccess { entries: entries.into_iter(), value: None })
314            }
315        }
316    }
317
318    fn deserialize_option<V: Visitor<'de>>(self, visitor: V) -> Result<V::Value, ConfigError> {
319        // Missing keys never get here, they are handled by `#[serde(default)]`
320        visitor.visit_some(self)
321    }
322
323    fn deserialize_newtype_struct<V: Visitor<'de>>(
324        self,
325        _name: &'static str,
326        visitor: V,
327    ) -> Result<V::Value, ConfigError> {
328        visitor.visit_newtype_struct(self)
329    }
330
331    fn deserialize_enum<V: Visitor<'de>>(
332        self,
333        _name: &'static str,
334        _variants: &'static [&'static str],
335        visitor: V,
336    ) -> Result<V::Value, ConfigError> {
337        match self {
338            ConfigValue::String(s, _) => visitor.visit_enum(s.into_deserializer()),
339            value => value.deserialize_any(visitor),
340        }
341    }
342
343    fn deserialize_struct<V: Visitor<'de>>(
344        self,
345        name: &'static str,
346        _fields: &'static [&'static str],
347        visitor: V,
348    ) -> Result<V::Value, ConfigError> {
349        if name == LOCATED {
350            // Hand the location to `Located` as a `(path, start, end)` tuple
351            let location = self.location().clone();
352            let encoded = ConfigValue::List(
353                vec![
354                    ConfigValue::String(location.path.to_string(), location.clone()),
355                    ConfigValue::Integer(location.span.start as i64, location.clone()),
356                    ConfigValue::Integer(location.span.end as i64, location.clone()),
357                ],
358                location,
359            );
360            let fields = [(VALUE_FIELD, self), (LOCATION_FIELD, encoded)];
361            return visitor.visit_map(MapDeserializer::new(fields.into_iter()));
362        }
363        self.deserialize_any(visitor)
364    }
365
366    forward_to_deserialize_any! {
367        bool i8 i16 i32 i64 i128 u8 u16 u32 u64 u128 f32 f64 char str string bytes byte_buf unit
368        unit_struct seq tuple tuple_struct map identifier ignored_any
369    }
370}
371
372impl<'de> IntoDeserializer<'de, ConfigError> for ConfigValue {
373    type Deserializer = Self;
374
375    fn into_deserializer(self) -> Self {
376        self
377    }
378}
379
380struct TableAccess {
381    entries: btree_map::IntoIter<String, ConfigValue>,
382    /// The entry whose key was deserialized last.
383    value: Option<(String, ConfigValue)>,
384}
385
386impl<'de> MapAccess<'de> for TableAccess {
387    type Error = ConfigError;
388
389    fn next_key_seed<K: DeserializeSeed<'de>>(
390        &mut self,
391        seed: K,
392    ) -> Result<Option<K::Value>, ConfigError> {
393        let Some((key, value)) = self.entries.next() else { return Ok(None) };
394        let deserializer: StrDeserializer<ConfigError> = key.as_str().into_deserializer();
395        // An unknown key is reported at the location of its value
396        let result = seed
397            .deserialize(deserializer)
398            .map_err(|err| err.at_location(value.location()));
399        self.value = Some((key, value));
400        result.map(Some)
401    }
402
403    fn next_value_seed<V: DeserializeSeed<'de>>(
404        &mut self,
405        seed: V,
406    ) -> Result<V::Value, ConfigError> {
407        let (key, value) = self
408            .value
409            .take()
410            .expect("`next_value_seed` called before `next_key_seed`");
411        let location = value.location().clone();
412        seed.deserialize(value)
413            .map_err(|err| err.at_location(&location).in_key(&key))
414    }
415}
416
417struct ListAccess {
418    items: vec::IntoIter<ConfigValue>,
419}
420
421impl<'de> SeqAccess<'de> for ListAccess {
422    type Error = ConfigError;
423
424    fn next_element_seed<T: DeserializeSeed<'de>>(
425        &mut self,
426        seed: T,
427    ) -> Result<Option<T::Value>, ConfigError> {
428        let Some(item) = self.items.next() else { return Ok(None) };
429        let location = item.location().clone();
430        seed.deserialize(item)
431            .map(Some)
432            .map_err(|err| err.at_location(&location))
433    }
434
435    fn size_hint(&self) -> Option<usize> {
436        Some(self.items.len())
437    }
438}