1mod 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
85pub 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}