Skip to main content

sapphire_framework_settings/
registry.rs

1//! The merged namespace of every owner's settings.
2
3use std::collections::HashMap;
4use std::sync::Arc;
5
6use sapphire_bridge_api::settings::{Kind, Scope, SettingDef};
7
8use crate::owner::SettingsOwner;
9use crate::{Error, Result};
10
11/// Every owner's definitions in one namespace, checked for clashes.
12pub struct Registry {
13    owners: Vec<Arc<dyn SettingsOwner>>,
14    /// Definitions with the index of their owner, in owner then definition order.
15    defs: Vec<(SettingDef, usize)>,
16    by_key: HashMap<String, usize>,
17}
18
19impl Registry {
20    /// Merge the owners' definitions.
21    ///
22    /// `reserved_for` maps a top-level name (a key's first segment) to the one owner, by
23    /// index, allowed to use it; names not listed are free. A key defined twice is
24    /// [`Error::Duplicate`], a reserved name used by another owner is [`Error::Reserved`],
25    /// and a definition without scopes or a secret outside the device scope is
26    /// [`Error::InvalidDef`].
27    pub fn new(
28        owners: Vec<Arc<dyn SettingsOwner>>,
29        reserved_for: &[(&str, usize)],
30    ) -> Result<Registry> {
31        let mut defs = Vec::new();
32        let mut by_key = HashMap::new();
33        for (idx, owner) in owners.iter().enumerate() {
34            for def in owner.defs() {
35                check(&def)?;
36                let top = def.key.split('.').next().unwrap_or_default();
37                if reserved_for
38                    .iter()
39                    .any(|(name, allowed)| *name == top && *allowed != idx)
40                {
41                    return Err(Error::Reserved {
42                        name: top.to_string(),
43                        key: def.key,
44                    });
45                }
46                if by_key.insert(def.key.clone(), defs.len()).is_some() {
47                    return Err(Error::Duplicate(def.key));
48                }
49                defs.push((def, idx));
50            }
51        }
52        Ok(Registry {
53            owners,
54            defs,
55            by_key,
56        })
57    }
58
59    /// The definition of `key` and the owner that holds its files.
60    pub fn def(&self, key: &str) -> Result<(&SettingDef, &dyn SettingsOwner)> {
61        let i = *self
62            .by_key
63            .get(key)
64            .ok_or_else(|| Error::UnknownKey(key.to_string()))?;
65        let (def, owner) = &self.defs[i];
66        Ok((def, self.owners[*owner].as_ref()))
67    }
68
69    /// The definitions whose key is `prefix` or starts with `prefix.`.
70    pub fn under(&self, prefix: &str) -> Vec<&SettingDef> {
71        self.defs
72            .iter()
73            .map(|(def, _)| def)
74            .filter(|def| {
75                def.key == prefix
76                    || def
77                        .key
78                        .strip_prefix(prefix)
79                        .is_some_and(|rest| rest.starts_with('.'))
80            })
81            .collect()
82    }
83
84    /// Every definition.
85    pub fn schema(&self) -> Vec<SettingDef> {
86        self.defs.iter().map(|(def, _)| def.clone()).collect()
87    }
88
89    /// Every definition with its owner.
90    pub(crate) fn entries(&self) -> impl Iterator<Item = (&SettingDef, &dyn SettingsOwner)> {
91        self.defs
92            .iter()
93            .map(|(def, owner)| (def, self.owners[*owner].as_ref()))
94    }
95}
96
97/// The rules every definition keeps: it names its home (the first scope), and a secret
98/// lives on the device only — its file is this host's, never synced.
99fn check(def: &SettingDef) -> Result<()> {
100    let invalid = |message: &str| Error::InvalidDef {
101        key: def.key.clone(),
102        message: message.to_string(),
103    };
104    if def.scopes.is_empty() {
105        return Err(invalid("it names no scope"));
106    }
107    if def.kind == Kind::Secret && def.scopes != [Scope::Device] {
108        return Err(invalid("a secret's only scope must be the device"));
109    }
110    Ok(())
111}
112
113#[cfg(test)]
114mod tests {
115    use super::*;
116    use crate::Error;
117    use crate::owner::test_support::{TestOwner, def};
118    use std::sync::Arc;
119
120    fn owner(keys: &[&str]) -> Arc<dyn SettingsOwner> {
121        Arc::new(TestOwner::new(
122            keys.iter().map(|k| def(k, Kind::Bool)).collect(),
123        ))
124    }
125
126    #[test]
127    fn a_def_without_scopes_is_rejected() {
128        let mut d = def("a.b", Kind::Bool);
129        d.scopes = vec![];
130        let err = Registry::new(vec![Arc::new(TestOwner::new(vec![d]))], &[])
131            .err()
132            .unwrap();
133        assert!(matches!(err, Error::InvalidDef { key, .. } if key == "a.b"));
134    }
135
136    #[test]
137    fn a_secret_outside_the_device_scope_is_rejected() {
138        for scopes in [
139            vec![Scope::Workgroup],
140            vec![Scope::Device, Scope::Workgroup],
141        ] {
142            let mut d = def("a.key", Kind::Secret);
143            d.scopes = scopes;
144            let err = Registry::new(vec![Arc::new(TestOwner::new(vec![d]))], &[])
145                .err()
146                .unwrap();
147            assert!(matches!(err, Error::InvalidDef { key, .. } if key == "a.key"));
148        }
149        let mut d = def("a.key", Kind::Secret);
150        d.scopes = vec![Scope::Device];
151        assert!(Registry::new(vec![Arc::new(TestOwner::new(vec![d]))], &[]).is_ok());
152    }
153
154    #[test]
155    fn duplicate_keys_across_owners_are_rejected() {
156        let err = Registry::new(vec![owner(&["net.relays"]), owner(&["net.relays"])], &[])
157            .err()
158            .unwrap();
159        assert!(matches!(err, Error::Duplicate(k) if k == "net.relays"));
160    }
161
162    #[test]
163    fn a_reserved_name_is_rejected_for_another_owner() {
164        let err = Registry::new(
165            vec![owner(&["net.a"]), owner(&["embed.x"])],
166            &[("embed", 0)],
167        )
168        .err()
169        .unwrap();
170        assert!(
171            matches!(err, Error::Reserved { key, name } if key == "embed.x" && name == "embed")
172        );
173    }
174
175    #[test]
176    fn the_reserved_owner_and_free_names_are_accepted() {
177        let reg = Registry::new(
178            vec![owner(&["embed.x", "embed.y.z"]), owner(&["mine.a"])],
179            &[("embed", 0)],
180        )
181        .unwrap();
182        assert_eq!(reg.under("embed").len(), 2);
183        assert_eq!(reg.under("embed.y").len(), 1);
184        assert_eq!(reg.under("emb").len(), 0);
185        assert_eq!(reg.schema().len(), 3);
186        assert!(reg.def("mine.a").is_ok());
187        assert!(matches!(
188            reg.def("nope").err().unwrap(),
189            Error::UnknownKey(_)
190        ));
191    }
192}