Skip to main content

appstruct_module_sdk/
lib.rs

1//! Stable module manifests and deterministic capability graph resolution.
2
3mod manifest;
4mod registry;
5
6pub use manifest::{
7    MODULE_API_VERSION, ModuleArtifact, ModuleManifest, module_namespace, validate_manifest,
8    validate_relative_path,
9};
10pub use registry::{
11    RegistryArtifact, RegistryEnvelope, RegistryPackage, RegistryVerificationError,
12    verify_registry_envelope,
13};
14
15use std::collections::{BTreeMap, BTreeSet};
16use std::error::Error;
17use std::fmt;
18
19#[derive(Clone, Debug, PartialEq, Eq)]
20pub struct ResolvedModule {
21    pub manifest: ModuleManifest,
22    pub startup_order: u32,
23}
24
25#[derive(Clone, Debug, PartialEq, Eq)]
26pub enum ModuleGraphError {
27    InvalidManifest {
28        module: String,
29        message: String,
30    },
31    DuplicateModule {
32        module: String,
33    },
34    DuplicateProvider {
35        capability: String,
36        first: String,
37        second: String,
38    },
39    MissingCapability {
40        module: String,
41        capability: String,
42    },
43    DependencyCycle {
44        modules: Vec<String>,
45    },
46}
47
48impl fmt::Display for ModuleGraphError {
49    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
50        match self {
51            Self::InvalidManifest { module, message } => {
52                write!(
53                    formatter,
54                    "module `{module}` has an invalid manifest: {message}"
55                )
56            }
57            Self::DuplicateModule { module } => {
58                write!(formatter, "module `{module}` is declared more than once")
59            }
60            Self::DuplicateProvider {
61                capability,
62                first,
63                second,
64            } => write!(
65                formatter,
66                "capability `{capability}` has multiple providers: `{first}` and `{second}`"
67            ),
68            Self::MissingCapability { module, capability } => write!(
69                formatter,
70                "module `{module}` requires missing capability `{capability}`"
71            ),
72            Self::DependencyCycle { modules } => {
73                write!(
74                    formatter,
75                    "module dependency cycle includes {}",
76                    modules.join(", ")
77                )
78            }
79        }
80    }
81}
82
83impl Error for ModuleGraphError {}
84
85/// Resolve manifests into a stable provider-before-consumer startup order.
86///
87/// # Errors
88///
89/// Returns an error for invalid manifests, duplicate declarations or providers,
90/// missing required capabilities, and dependency cycles.
91///
92/// # Panics
93///
94/// This function does not panic for a valid manifest set. Internal lookups use
95/// assertions to defend the graph invariants established during resolution.
96pub fn resolve_modules(
97    manifests: impl IntoIterator<Item = ModuleManifest>,
98) -> Result<Vec<ResolvedModule>, ModuleGraphError> {
99    let mut modules = BTreeMap::new();
100    for mut manifest in manifests {
101        validate_manifest(&mut manifest)?;
102        let name = manifest.name.clone();
103        if modules.insert(name.clone(), manifest).is_some() {
104            return Err(ModuleGraphError::DuplicateModule { module: name });
105        }
106    }
107
108    let providers = capability_providers(&modules)?;
109    let mut dependencies = BTreeMap::<String, BTreeSet<String>>::new();
110    let mut consumers = BTreeMap::<String, BTreeSet<String>>::new();
111    for (name, manifest) in &modules {
112        let required = manifest
113            .requires
114            .iter()
115            .map(|capability| {
116                providers.get(capability).cloned().ok_or_else(|| {
117                    ModuleGraphError::MissingCapability {
118                        module: name.clone(),
119                        capability: capability.clone(),
120                    }
121                })
122            })
123            .collect::<Result<BTreeSet<_>, _>>()?;
124        for provider in required.iter().filter(|provider| *provider != name) {
125            consumers
126                .entry(provider.clone())
127                .or_default()
128                .insert(name.clone());
129        }
130        dependencies.insert(
131            name.clone(),
132            required
133                .into_iter()
134                .filter(|provider| provider != name)
135                .collect(),
136        );
137    }
138
139    let mut ready = dependencies
140        .iter()
141        .filter_map(|(name, required)| required.is_empty().then_some(name.clone()))
142        .collect::<BTreeSet<_>>();
143    let mut ordered = Vec::with_capacity(modules.len());
144    while let Some(name) = ready.pop_first() {
145        let manifest = modules.get(&name).expect("ready module exists").clone();
146        let startup_order =
147            u32::try_from(ordered.len()).map_err(|_| ModuleGraphError::InvalidManifest {
148                module: name.clone(),
149                message: "too many modules to represent startup order".to_owned(),
150            })?;
151        ordered.push(ResolvedModule {
152            manifest,
153            startup_order,
154        });
155        for consumer in consumers.get(&name).into_iter().flatten() {
156            let required = dependencies
157                .get_mut(consumer)
158                .expect("consumer dependency set exists");
159            required.remove(&name);
160            if required.is_empty() {
161                ready.insert(consumer.clone());
162            }
163        }
164    }
165
166    if ordered.len() != modules.len() {
167        let resolved = ordered
168            .iter()
169            .map(|module| module.manifest.name.as_str())
170            .collect::<BTreeSet<_>>();
171        let cycle = modules
172            .keys()
173            .filter(|name| !resolved.contains(name.as_str()))
174            .cloned()
175            .collect();
176        return Err(ModuleGraphError::DependencyCycle { modules: cycle });
177    }
178    Ok(ordered)
179}
180
181fn capability_providers(
182    modules: &BTreeMap<String, ModuleManifest>,
183) -> Result<BTreeMap<String, String>, ModuleGraphError> {
184    let mut providers = BTreeMap::new();
185    for (name, manifest) in modules {
186        for capability in &manifest.provides {
187            if let Some(first) = providers.insert(capability.clone(), name.clone()) {
188                return Err(ModuleGraphError::DuplicateProvider {
189                    capability: capability.clone(),
190                    first,
191                    second: name.clone(),
192                });
193            }
194        }
195    }
196    Ok(providers)
197}
198
199#[cfg(test)]
200mod tests {
201    use super::{ModuleGraphError, ModuleManifest, resolve_modules};
202
203    fn manifest(name: &str, provides: &[&str], requires: &[&str]) -> ModuleManifest {
204        ModuleManifest::new(
205            name,
206            "1",
207            provides.iter().copied(),
208            requires.iter().copied(),
209        )
210    }
211
212    #[test]
213    fn resolves_provider_before_consumer_deterministically() {
214        let resolved = resolve_modules([
215            manifest("audit", &["audit.events"], &["auth.identity"]),
216            manifest("mail", &["mail.delivery"], &[]),
217            manifest("auth", &["auth.identity"], &[]),
218        ])
219        .unwrap();
220        let names = resolved
221            .iter()
222            .map(|module| module.manifest.name.as_str())
223            .collect::<Vec<_>>();
224        assert_eq!(names, ["auth", "audit", "mail"]);
225        assert_eq!(resolved[1].startup_order, 1);
226    }
227
228    #[test]
229    fn rejects_missing_capabilities() {
230        let error = resolve_modules([manifest("tenant", &["tenant.context"], &["auth.identity"])])
231            .unwrap_err();
232        assert!(matches!(
233            error,
234            ModuleGraphError::MissingCapability { capability, .. }
235                if capability == "auth.identity"
236        ));
237    }
238
239    #[test]
240    fn rejects_invalid_and_duplicate_manifests() {
241        let invalid = resolve_modules([manifest("", &["identity"], &[])]).unwrap_err();
242        assert!(matches!(invalid, ModuleGraphError::InvalidManifest { .. }));
243
244        let duplicate = resolve_modules([
245            manifest("auth", &["identity"], &[]),
246            manifest("auth", &["roles"], &[]),
247        ])
248        .unwrap_err();
249        assert_eq!(
250            duplicate,
251            ModuleGraphError::DuplicateModule {
252                module: "auth".to_owned()
253            }
254        );
255    }
256
257    #[test]
258    fn rejects_duplicate_providers() {
259        let error = resolve_modules([
260            manifest("first", &["storage"], &[]),
261            manifest("second", &["storage"], &[]),
262        ])
263        .unwrap_err();
264        assert!(matches!(error, ModuleGraphError::DuplicateProvider { .. }));
265    }
266
267    #[test]
268    fn rejects_dependency_cycles() {
269        let error = resolve_modules([
270            manifest("first", &["first"], &["second"]),
271            manifest("second", &["second"], &["first"]),
272        ])
273        .unwrap_err();
274        assert_eq!(
275            error,
276            ModuleGraphError::DependencyCycle {
277                modules: vec!["first".to_owned(), "second".to_owned()]
278            }
279        );
280    }
281
282    #[test]
283    fn graph_errors_display_stable_messages() {
284        assert!(
285            ModuleGraphError::InvalidManifest {
286                module: "auth".to_owned(),
287                message: "bad".to_owned(),
288            }
289            .to_string()
290            .contains("invalid manifest")
291        );
292        assert!(
293            ModuleGraphError::DuplicateModule {
294                module: "auth".to_owned(),
295            }
296            .to_string()
297            .contains("more than once")
298        );
299        assert!(
300            ModuleGraphError::DuplicateProvider {
301                capability: "storage".to_owned(),
302                first: "a".to_owned(),
303                second: "b".to_owned(),
304            }
305            .to_string()
306            .contains("multiple providers")
307        );
308        assert!(
309            ModuleGraphError::MissingCapability {
310                module: "tenant".to_owned(),
311                capability: "auth.identity".to_owned(),
312            }
313            .to_string()
314            .contains("missing capability")
315        );
316        assert!(
317            ModuleGraphError::DependencyCycle {
318                modules: vec!["a".to_owned(), "b".to_owned()],
319            }
320            .to_string()
321            .contains("cycle")
322        );
323    }
324
325    #[test]
326    fn self_provided_capabilities_do_not_create_dependencies() {
327        let resolved =
328            resolve_modules([manifest("auth", &["auth.identity"], &["auth.identity"])]).unwrap();
329        assert_eq!(resolved[0].manifest.name, "auth");
330        assert_eq!(resolved[0].startup_order, 0);
331    }
332}