Skip to main content

spin_loader/
local.rs

1use std::path::{Path, PathBuf};
2
3use anyhow::{Context, Result, anyhow, bail, ensure};
4use futures::future::try_join_all;
5use reqwest::Url;
6use spin_common::{paths::parent_dir, sloth, ui::quoted_path};
7use spin_expressions::Resolver;
8use spin_locked_app::{
9    locked::{
10        self, ContentPath, ContentRef, LockedApp, LockedComponent, LockedComponentDependency,
11        LockedComponentSource, LockedTrigger,
12    },
13    values::{ValuesMap, ValuesMapBuilder},
14};
15use spin_manifest::schema::v2::{self, AppManifest, KebabId, WasiFilesMount};
16use spin_outbound_networking_config::allowed_hosts::{AllowedHostConfig, AllowedHostsConfig};
17use spin_serde::DependencyName;
18use std::collections::BTreeMap;
19use tokio::sync::Semaphore;
20
21use crate::{
22    FilesMountStrategy,
23    cache::Cache,
24    http::{DestinationConvention, verified_download_stream},
25};
26
27mod trigger_components;
28
29#[derive(Debug)]
30pub struct LocalLoader {
31    app_root: PathBuf,
32    files_mount_strategy: FilesMountStrategy,
33    file_loading_permits: std::sync::Arc<Semaphore>,
34    wasm_loader: WasmLoader,
35    profile: Option<String>,
36}
37
38impl LocalLoader {
39    pub async fn new(
40        app_root: &Path,
41        files_mount_strategy: FilesMountStrategy,
42        profile: Option<&str>,
43        cache_root: Option<PathBuf>,
44    ) -> Result<Self> {
45        let app_root = safe_canonicalize(app_root)
46            .with_context(|| format!("Invalid manifest dir `{}`", app_root.display()))?;
47        let file_loading_permits =
48            std::sync::Arc::new(Semaphore::new(crate::MAX_FILE_LOADING_CONCURRENCY));
49        Ok(Self {
50            app_root: app_root.clone(),
51            files_mount_strategy,
52            // Limit concurrency to avoid hitting system resource limits
53            file_loading_permits: file_loading_permits.clone(),
54            wasm_loader: WasmLoader::new(app_root, cache_root, Some(file_loading_permits)).await?,
55            profile: profile.map(|s| s.to_owned()),
56        })
57    }
58
59    // Load the manifest file (spin.toml) at the given path into a LockedApp,
60    // preparing all its content for execution.
61    pub async fn load_file(&self, path: impl AsRef<Path>) -> Result<LockedApp> {
62        // Parse manifest
63        let path = path.as_ref();
64        let manifest = spin_manifest::manifest_from_file(path).with_context(|| {
65            format!(
66                "Failed to read Spin app manifest from {}",
67                quoted_path(path)
68            )
69        })?;
70        let mut locked = self
71            .load_manifest(manifest, self.profile())
72            .await
73            .with_context(|| format!("Failed to load Spin app from {}", quoted_path(path)))?;
74
75        // Set origin metadata
76        locked
77            .metadata
78            .insert("origin".into(), file_url(path)?.into());
79
80        // Set build profile metadata
81        if let Some(profile) = self.profile.as_ref() {
82            locked
83                .metadata
84                .insert("profile".into(), profile.as_str().into());
85        }
86
87        Ok(locked)
88    }
89
90    // Load the given manifest into a LockedApp, ready for execution.
91    pub(crate) async fn load_manifest(
92        &self,
93        mut manifest: AppManifest,
94        profile: Option<&str>,
95    ) -> Result<LockedApp> {
96        spin_manifest::normalize::normalize_manifest(&mut manifest, profile)?;
97
98        manifest.validate_required_fields()?;
99        manifest.validate_dependencies()?;
100
101        let AppManifest {
102            spin_manifest_version: _,
103            application,
104            variables,
105            triggers,
106            components,
107        } = manifest;
108
109        let metadata = locked_metadata(application, triggers.keys().cloned())?;
110
111        let variables = variables
112            .into_iter()
113            .map(|(name, v)| Ok((name.to_string(), locked_variable(v)?)))
114            .collect::<Result<BTreeMap<_, _>>>()?;
115        let resolver = Resolver::new(variables.clone())?;
116
117        let triggers = try_join_all(triggers.into_iter().flat_map(|(trigger_type, configs)| {
118            configs
119                .into_iter()
120                .map(|trigger| {
121                    let trigger_type_2 = trigger_type.clone();
122                    let id = trigger.id.clone();
123                    async move {
124                        self.load_trigger(&id, &trigger_type_2, trigger)
125                            .await
126                            .with_context(|| {
127                                format!("Failed to load `{}` trigger `{}`", trigger_type_2, id)
128                            })
129                    }
130                })
131                .collect::<Vec<_>>()
132        }))
133        .await?;
134
135        let sloth_guard = warn_if_component_load_slothful();
136
137        // Load all components concurrently
138        let components = try_join_all(components.into_iter().map(|(id, c)| {
139            let resolver = &resolver;
140            async move {
141                self.load_component(&id, c, resolver)
142                    .await
143                    .with_context(|| format!("Failed to load component `{id}`"))
144            }
145        }))
146        .await?;
147
148        drop(sloth_guard);
149
150        let locked = LockedApp {
151            spin_lock_version: Default::default(),
152            metadata,
153            must_understand: vec![],
154            host_requirements: spin_locked_app::values::ValuesMap::new(),
155            variables,
156            triggers,
157            components,
158        };
159
160        let mut locked = trigger_components::reassign_trigger_deps(locked);
161
162        if !locked.host_requirements.is_empty() {
163            locked
164                .must_understand
165                .push(spin_locked_app::locked::MustUnderstand::HostRequirements);
166        }
167        if locked
168            .components
169            .iter()
170            .any(|c| !c.host_requirements.is_empty())
171        {
172            locked
173                .must_understand
174                .push(spin_locked_app::locked::MustUnderstand::ComponentHostRequirements);
175        }
176
177        Ok(locked)
178    }
179
180    async fn load_trigger(
181        &self,
182        id: &str,
183        trigger_type: &str,
184        trigger: v2::Trigger,
185    ) -> Result<LockedTrigger> {
186        fn reference_id(spec: v2::ComponentSpec) -> toml::Value {
187            let v2::ComponentSpec::Reference(id) = spec else {
188                unreachable!("should have already been normalized");
189            };
190            id.as_ref().into()
191        }
192
193        let mut config = trigger.config;
194
195        if let Some(id) = trigger.component.map(reference_id) {
196            config.insert("component".into(), id);
197        }
198
199        let locked_deps = if !trigger.dependencies.is_empty() {
200            self.load_trigger_dependencies(id, trigger.dependencies.iter())
201                .await?
202        } else {
203            BTreeMap::new()
204        };
205
206        Ok(LockedTrigger {
207            id: trigger.id,
208            trigger_type: trigger_type.to_string(),
209            trigger_config: config.try_into()?,
210            trigger_dependencies: locked_deps,
211        })
212    }
213
214    // Load the given component into a LockedComponent, ready for execution.
215    async fn load_component(
216        &self,
217        id: &KebabId,
218        component: v2::Component,
219        resolver: &Resolver,
220    ) -> Result<LockedComponent> {
221        let allowed_outbound_hosts = component
222            .normalized_allowed_outbound_hosts()
223            .context("`allowed_http_hosts` is malformed")?;
224        AllowedHostsConfig::validate(&allowed_outbound_hosts, resolver)
225            .context("`allowed_outbound_hosts` is malformed")?;
226
227        let component_requires_service_chaining = requires_service_chaining(&component);
228
229        let metadata = ValuesMapBuilder::new()
230            .string("description", component.description)
231            .string_array("allowed_outbound_hosts", allowed_outbound_hosts)
232            .string_array("key_value_stores", component.key_value_stores)
233            .string_array("databases", component.sqlite_databases)
234            .string_array("ai_models", component.ai_models)
235            .serializable("build", component.build)?
236            .take();
237
238        let source = self
239            .load_component_source(id, component.source.clone())
240            .await
241            .with_context(|| format!("Failed to load Wasm source {}", component.source))?;
242
243        let dependencies = self
244            .load_component_dependencies(id, &component.dependencies)
245            .await?;
246
247        let env = component.environment.into_iter().collect();
248
249        let files = if component.files.is_empty() {
250            vec![]
251        } else {
252            match &self.files_mount_strategy {
253                FilesMountStrategy::Copy(files_mount_root) => {
254                    let component_mount_root = files_mount_root.join(id.as_ref());
255                    // Copy mounted files into component mount root, concurrently
256                    try_join_all(component.files.iter().map(|f| {
257                        self.copy_file_mounts(f, &component_mount_root, &component.exclude_files)
258                    }))
259                    .await?;
260
261                    // All component files (copies) are in `component_mount_root` now
262                    vec![ContentPath {
263                        content: file_content_ref(component_mount_root)?,
264                        path: "/".into(),
265                    }]
266                }
267                FilesMountStrategy::Direct => {
268                    ensure!(
269                        component.exclude_files.is_empty(),
270                        "Cannot load a component with `exclude_files` using --direct-mounts"
271                    );
272                    let mut files = vec![];
273                    for mount in &component.files {
274                        // Validate (and canonicalize) direct mount directory
275                        files.push(self.resolve_direct_mount(mount).await?);
276                    }
277                    files
278                }
279            }
280        };
281
282        let config = component
283            .variables
284            .into_iter()
285            .map(|(k, v)| (k.into(), v))
286            .collect();
287
288        let mut host_requirements = ValuesMapBuilder::new();
289        if component_requires_service_chaining {
290            host_requirements.string(
291                spin_locked_app::locked::SERVICE_CHAINING_KEY,
292                spin_locked_app::locked::HOST_REQ_REQUIRED,
293            );
294        }
295        let host_requirements = host_requirements.build();
296
297        Ok(LockedComponent {
298            id: id.as_ref().into(),
299            metadata,
300            source,
301            env,
302            files,
303            config,
304            dependencies,
305            trigger_dependencies: Default::default(), // We will fix this up later
306            host_requirements,
307        })
308    }
309
310    async fn load_component_dependencies(
311        &self,
312        id: &KebabId,
313        dependencies: &v2::ComponentDependencies,
314    ) -> Result<BTreeMap<DependencyName, LockedComponentDependency>> {
315        Ok(try_join_all(dependencies.inner.iter().map(
316            |(dependency_name, dependency)| async move {
317                let locked_dependency = self
318                    .load_component_dependency(dependency_name.clone(), dependency.clone())
319                    .await
320                    .with_context(|| {
321                        format!(
322                            "Failed to load component dependency `{dependency_name}` for `{id}`"
323                        )
324                    })?;
325
326                anyhow::Ok((dependency_name.clone(), locked_dependency))
327            },
328        ))
329        .await?
330        .into_iter()
331        .collect())
332    }
333
334    async fn load_component_dependency(
335        &self,
336        dependency_name: DependencyName,
337        dependency: v2::ComponentDependency,
338    ) -> Result<LockedComponentDependency> {
339        self.wasm_loader
340            .load_component_dependency(&dependency_name, &dependency)
341            .await
342    }
343
344    async fn load_trigger_dependencies(
345        &self,
346        id: &str,
347        dependencies: impl Iterator<Item = (&String, &v2::TriggerDependencies)>,
348    ) -> Result<BTreeMap<String, Vec<LockedComponentDependency>>> {
349        let mut loaded = BTreeMap::new();
350
351        for (role, deps) in dependencies {
352            let locked_deps = self.load_trigger_dependencies_vec(id, &deps.0).await?;
353            loaded.insert(role.clone(), locked_deps);
354        }
355
356        Ok(loaded)
357    }
358
359    async fn load_trigger_dependencies_vec(
360        &self,
361        id: &str,
362        dependencies: &[v2::TriggerDependency],
363    ) -> Result<Vec<LockedComponentDependency>> {
364        Ok(
365            try_join_all(dependencies.iter().map(|dependency| async move {
366                let locked_dependency = self
367                    .load_trigger_dependency(dependency.clone())
368                    .await
369                    .with_context(|| {
370                        format!("Failed to load trigger dependency `{dependency:?}` for `{id}`")
371                    })?;
372
373                anyhow::Ok(locked_dependency)
374            }))
375            .await?
376            .into_iter()
377            .collect(),
378        )
379    }
380
381    async fn load_trigger_dependency(
382        &self,
383        dependency: v2::TriggerDependency,
384    ) -> Result<LockedComponentDependency> {
385        self.wasm_loader.load_trigger_dependency(&dependency).await
386    }
387
388    // Load a Wasm source from the given ContentRef and update the source
389    // URL with an absolute path to the content.
390    async fn load_component_source(
391        &self,
392        component_id: &KebabId,
393        source: v2::ComponentSource,
394    ) -> Result<LockedComponentSource> {
395        let path = self
396            .wasm_loader
397            .load_component_source(component_id.as_ref(), &source)
398            .await?;
399        Ok(LockedComponentSource {
400            content_type: "application/wasm".into(),
401            content: file_content_ref(path)?,
402        })
403    }
404
405    // Copy content(s) from the given `mount`
406    async fn copy_file_mounts(
407        &self,
408        mount: &WasiFilesMount,
409        dest_root: &Path,
410        exclude_files: &[String],
411    ) -> Result<()> {
412        match mount {
413            WasiFilesMount::Pattern(pattern) => {
414                self.copy_glob_or_path(pattern, dest_root, exclude_files)
415                    .await
416            }
417            WasiFilesMount::Placement {
418                source,
419                destination,
420            } => {
421                let src = Path::new(source);
422                let dest = dest_root.join(destination.trim_start_matches('/'));
423                self.copy_file_or_directory(src, &dest, destination, exclude_files)
424                    .await
425            }
426        }
427    }
428
429    // Copy files matching glob pattern or single file/directory path.
430    async fn copy_glob_or_path(
431        &self,
432        glob_or_path: &str,
433        dest_root: &Path,
434        exclude_files: &[String],
435    ) -> Result<()> {
436        if glob_or_path == ".." || glob_or_path.ends_with("/..") {
437            bail!(
438                "A file pattern can't end in a parent directory path (..)\nIf you want to include a directory, use source-destination form, or a glob pattern ending in **/*.\nLearn more: https://spinframework.dev/writing-apps#including-files-with-components"
439            );
440        }
441        if glob_or_path == "." || glob_or_path.ends_with("/.") {
442            bail!(
443                "A file pattern can't end in a current directory path (.)\nIf you want to include a directory, use source-destination form, or a glob pattern ending in **/*.\nLearn more: https://spinframework.dev/writing-apps#including-files-with-components"
444            );
445        }
446
447        if glob_or_path == "*" {
448            tracing::warn!(
449                alert_in_dev = true,
450                "A component is including the entire application directory as asset files. This is unlikely to be what you want.\nIf this is what you want, use the pattern \"./*\" to avoid this warning.\nLearn more: https://spinframework.dev/writing-apps#including-files-with-components\n"
451            );
452        }
453        if glob_or_path == "**/*" {
454            tracing::warn!(
455                alert_in_dev = true,
456                "A component is including the entire application directory tree as asset files. This is unlikely to be what you want.\nIf this is what you want, use the pattern \"./**/*\" to avoid this warning.\nLearn more: https://spinframework.dev/writing-apps#including-files-with-components\n"
457            );
458        }
459
460        let path = self.app_root.join(glob_or_path);
461        if path.exists() {
462            let dest = dest_root.join(glob_or_path);
463            if path.is_dir() {
464                // "single/dir"
465                let pattern = path.join("**/*");
466                self.copy_glob(&pattern, &self.app_root, &dest, exclude_files)
467                    .await?;
468            } else {
469                // "single/file.txt"
470                self.copy_single_file(&path, &dest, glob_or_path).await?;
471            }
472        } else if looks_like_glob_pattern(glob_or_path) {
473            // "glob/pattern/*"
474            self.copy_glob(&path, &self.app_root, dest_root, exclude_files)
475                .await?;
476        } else {
477            bail!("{glob_or_path:?} does not exist and doesn't appear to be a glob pattern");
478        }
479        Ok(())
480    }
481
482    // Copy a single file or entire directory from `src` to `dest`
483    async fn copy_file_or_directory(
484        &self,
485        src: &Path,
486        dest: &Path,
487        guest_dest: &str,
488        exclude_files: &[String],
489    ) -> Result<()> {
490        let src_path = self.app_root.join(src);
491        let meta = crate::fs::metadata(&src_path)
492            .await
493            .map_err(|e| explain_file_mount_source_error(e, src))?;
494        if meta.is_dir() {
495            // { source = "host/dir", destination = "guest/dir" }
496            let pattern = src_path.join("**/*");
497            self.copy_glob(&pattern, &src_path, dest, exclude_files)
498                .await?;
499        } else {
500            // { source = "host/file.txt", destination = "guest/file.txt" }
501            self.copy_single_file(&src_path, dest, guest_dest).await?;
502        }
503        Ok(())
504    }
505
506    // Copy files matching glob `pattern` into `dest_root`.
507    async fn copy_glob(
508        &self,
509        pattern: &Path,
510        src_prefix: &Path,
511        dest_root: &Path,
512        exclude_files: &[String],
513    ) -> Result<()> {
514        let pattern = pattern
515            .to_str()
516            .with_context(|| format!("invalid (non-utf8) file pattern {pattern:?}"))?;
517
518        let paths = glob::glob(pattern)
519            .with_context(|| format!("Failed to resolve glob pattern {pattern:?}"))?;
520
521        let exclude_patterns = exclude_files
522            .iter()
523            .map(|pattern| {
524                glob::Pattern::new(pattern)
525                    .with_context(|| format!("Invalid exclude_files glob pattern {pattern:?}"))
526            })
527            .collect::<Result<Vec<_>>>()?;
528
529        crate::fs::create_dir_all(dest_root)
530            .await
531            .with_context(|| {
532                format!(
533                    "Failed to create parent directory {}",
534                    quoted_path(&dest_root)
535                )
536            })?;
537
538        for path_res in paths {
539            let src = path_res?;
540            if !src.is_file() {
541                continue;
542            }
543
544            let Ok(app_root_path) = src.strip_prefix(&self.app_root) else {
545                bail!(
546                    "{pattern} cannot be mapped because it is outside the application directory. Files must be within the application directory."
547                );
548            };
549
550            if exclude_patterns
551                .iter()
552                .any(|pattern| pattern.matches_path(app_root_path))
553            {
554                tracing::debug!(
555                    "File {app_root_path:?} excluded by exclude_files {exclude_files:?}"
556                );
557                continue;
558            }
559
560            let relative_path = src.strip_prefix(src_prefix)?;
561            let dest = dest_root.join(relative_path);
562            self.copy_single_file(&src, &dest, &relative_path.to_string_lossy())
563                .await?;
564        }
565        Ok(())
566    }
567
568    // Copy a single file from `src` to `dest`, creating parent directories.
569    async fn copy_single_file(&self, src: &Path, dest: &Path, guest_dest: &str) -> Result<()> {
570        // Sanity checks: src is in app_root...
571        src.strip_prefix(&self.app_root)?;
572        // ...and dest is in the Copy root.
573        if let FilesMountStrategy::Copy(files_mount_root) = &self.files_mount_strategy {
574            dest.strip_prefix(files_mount_root)?;
575        } else {
576            unreachable!();
577        }
578
579        let _loading_permit = self.file_loading_permits.acquire().await?;
580        let dest_parent = parent_dir(dest)?;
581        crate::fs::create_dir_all(&dest_parent)
582            .await
583            .with_context(|| {
584                format!(
585                    "Failed to create parent directory {}",
586                    quoted_path(&dest_parent)
587                )
588            })?;
589        crate::fs::copy(src, dest)
590            .await
591            .or_else(|e| Self::failed_to_copy_single_file_error(src, dest, guest_dest, e))?;
592        tracing::debug!("Copied {src:?} to {dest:?}");
593        Ok(())
594    }
595
596    fn failed_to_copy_single_file_error<T>(
597        src: &Path,
598        dest: &Path,
599        guest_dest: &str,
600        e: anyhow::Error,
601    ) -> anyhow::Result<T> {
602        let src_text = quoted_path(src);
603        let dest_text = quoted_path(dest);
604        let base_msg = format!("Failed to copy {src_text} to working path {dest_text}");
605
606        if let Some(io_error) = e.downcast_ref::<std::io::Error>()
607            && (Self::is_directory_like(guest_dest)
608                || io_error.kind() == std::io::ErrorKind::NotFound)
609        {
610            return Err(anyhow::anyhow!(
611                r#""{guest_dest}" is not a valid destination file name"#
612            ))
613            .context(base_msg);
614        }
615
616        Err(e).with_context(|| format!("{base_msg} (for destination path \"{guest_dest}\")"))
617    }
618
619    /// Does a guest path appear to be a directory name, e.g. "/" or ".."? This is for guest
620    /// paths *only* and does not consider Windows separators.
621    fn is_directory_like(guest_path: &str) -> bool {
622        guest_path.ends_with('/') || guest_path.ends_with('.') || guest_path.ends_with("..")
623    }
624
625    // Resolve the given direct mount directory, checking that it is valid for
626    // direct mounting and returning its canonicalized source path.
627    async fn resolve_direct_mount(&self, mount: &WasiFilesMount) -> Result<ContentPath> {
628        let (src, dest) = match mount {
629            WasiFilesMount::Pattern(pattern) => (pattern, pattern),
630            WasiFilesMount::Placement {
631                source,
632                destination,
633            } => (source, destination),
634        };
635        let path = self.app_root.join(src);
636        if !path.is_dir() {
637            bail!(
638                "Only directory mounts are supported with `--direct-mounts`; {src:?} is not a directory."
639            );
640        }
641        Ok(ContentPath {
642            content: file_content_ref(src)?,
643            path: dest.into(),
644        })
645    }
646
647    fn profile(&self) -> Option<&str> {
648        self.profile.as_deref()
649    }
650}
651
652fn explain_file_mount_source_error(e: anyhow::Error, src: &Path) -> anyhow::Error {
653    if let Some(io_error) = e.downcast_ref::<std::io::Error>()
654        && io_error.kind() == std::io::ErrorKind::NotFound
655    {
656        return anyhow::anyhow!("File or directory {} does not exist", quoted_path(src));
657    }
658    e.context(format!("invalid file mount source {}", quoted_path(src)))
659}
660
661#[cfg(feature = "async-io")]
662async fn verified_download(
663    url: &str,
664    digest: &str,
665    dest: &Path,
666    convention: crate::http::DestinationConvention,
667) -> Result<()> {
668    crate::http::verified_download(url, digest, dest, convention)
669        .await
670        .with_context(|| format!("Error fetching source URL {url:?}"))
671}
672
673#[cfg(not(feature = "async-io"))]
674async fn verified_download(
675    _url: &str,
676    _digest: &str,
677    _dest: &Path,
678    _convention: crate::http::DestinationConvention,
679) -> Result<()> {
680    panic!("async-io feature is required for downloading Wasm sources")
681}
682
683fn safe_canonicalize(path: &Path) -> std::io::Result<PathBuf> {
684    use path_absolutize::Absolutize;
685    Ok(path.absolutize()?.into_owned())
686}
687
688fn locked_metadata(
689    details: v2::AppDetails,
690    trigger_types: impl Iterator<Item = String>,
691) -> Result<ValuesMap> {
692    let mut builder = ValuesMapBuilder::new();
693    builder
694        .string("name", details.name)
695        .string("version", details.version)
696        .string("description", details.description)
697        .string_array("authors", details.authors)
698        .serializable("triggers", &details.trigger_global_configs)?;
699
700    // Duplicate single-trigger global options into "trigger" with "type"
701    // key to maintain backward compatibility for a while.
702    let types = trigger_types.collect::<Vec<_>>();
703    if types.len() == 1 {
704        let trigger_type = types.into_iter().next().unwrap();
705        let mut single_trigger = details
706            .trigger_global_configs
707            .get(&trigger_type)
708            .cloned()
709            .unwrap_or_default();
710        single_trigger.insert("type".into(), trigger_type.into());
711        builder.serializable("trigger", single_trigger).unwrap();
712    }
713
714    Ok(builder.build())
715}
716
717fn locked_variable(variable: v2::Variable) -> Result<locked::Variable> {
718    ensure!(
719        variable.required ^ variable.default.is_some(),
720        "must be `required` OR have a `default`"
721    );
722    Ok(locked::Variable {
723        description: variable.description,
724        default: variable.default.clone(),
725        secret: variable.secret,
726    })
727}
728
729#[derive(Debug)]
730/// Handles loading of component Wasm from different sources.
731pub struct WasmLoader {
732    app_root: PathBuf,
733    cache: Cache,
734    file_loading_permits: std::sync::Arc<Semaphore>,
735}
736
737impl WasmLoader {
738    /// Create a new instance of WasmLoader.
739    pub async fn new(
740        app_root: PathBuf,
741        cache_root: Option<PathBuf>,
742        file_loading_permits: Option<std::sync::Arc<Semaphore>>,
743    ) -> Result<Self> {
744        let file_loading_permits = file_loading_permits.unwrap_or_else(|| {
745            std::sync::Arc::new(Semaphore::new(crate::MAX_FILE_LOADING_CONCURRENCY))
746        });
747        Ok(Self {
748            app_root,
749            cache: Cache::new(cache_root).await?,
750            file_loading_permits,
751        })
752    }
753
754    /// Load a Wasm source from the given ComponentSource and return a path
755    /// to a file location from where it can be read.
756    pub async fn load_component_source(
757        &self,
758        component_id: &str,
759        source: &v2::ComponentSource,
760    ) -> Result<PathBuf> {
761        let content = match source {
762            v2::ComponentSource::Local(path) => self.app_root.join(path),
763            v2::ComponentSource::Remote { url, digest } => {
764                self.load_http_source(url, digest).await?
765            }
766            v2::ComponentSource::Registry {
767                registry,
768                package,
769                version,
770            } => {
771                let version = semver::Version::parse(version).with_context(|| format!("Component {component_id} specifies an invalid semantic version ({version:?}) for its package version"))?;
772                let version_req = format!("={version}").parse().expect("version");
773
774                self.load_registry_source(registry.as_ref(), package, &version_req)
775                    .await?
776            }
777        };
778        Ok(content)
779    }
780
781    /// Load a Wasm source from `url`, verifying it against `digest`
782    /// (`sha256:...`), and return a path to the cached local copy.
783    pub async fn load_http_source(&self, url: &str, digest: &str) -> Result<PathBuf> {
784        ensure!(
785            digest.starts_with("sha256:"),
786            "invalid `digest` {digest:?}; must start with 'sha256:'"
787        );
788        let path = if let Ok(cached_path) = self.cache.wasm_file(digest) {
789            cached_path
790        } else {
791            let _loading_permit = self.file_loading_permits.acquire().await?;
792
793            self.cache.ensure_dirs().await?;
794            let dest = self.cache.wasm_path(digest);
795            verified_download(
796                url,
797                digest,
798                &dest,
799                crate::http::DestinationConvention::ContentIndexed,
800            )
801            .await
802            .with_context(|| format!("Error fetching source URL {url:?}"))?;
803            dest
804        };
805        Ok(path)
806    }
807
808    /// Load the best matching release of `package` from `registry` (or the
809    /// default registry) and return a path to the cached Wasm file.
810    pub async fn load_registry_source(
811        &self,
812        registry: Option<&wasm_pkg_client::Registry>,
813        package: &wasm_pkg_client::PackageRef,
814        version: &semver::VersionReq,
815    ) -> Result<PathBuf> {
816        let mut client_config = wasm_pkg_client::Config::global_defaults().await?;
817
818        if let Some(registry) = registry.cloned() {
819            let mapping = wasm_pkg_client::RegistryMapping::Registry(registry);
820            client_config.set_package_registry_override(package.clone(), mapping);
821        }
822        let pkg_loader = wasm_pkg_client::Client::new(client_config);
823
824        let mut releases = pkg_loader.list_all_versions(package).await.map_err(|e| {
825            if matches!(e, wasm_pkg_client::Error::NoRegistryForNamespace(_)) && registry.is_none() {
826                anyhow!("No default registry specified for wasm-pkg-loader. Create a default config, or set `registry` for package {package:?}")
827            } else {
828                e.into()
829            }
830        })?;
831
832        releases.sort();
833
834        let release_version = releases
835            .iter()
836            .rev()
837            .find(|release| version.matches(&release.version) && !release.yanked)
838            .with_context(|| format!("No matching version found for {package} {version}",))?;
839
840        let release = pkg_loader
841            .get_release(package, &release_version.version)
842            .await?;
843
844        let digest = match &release.content_digest {
845            wasm_pkg_client::ContentDigest::Sha256 { hex } => format!("sha256:{hex}"),
846        };
847
848        let path = if let Ok(cached_path) = self.cache.wasm_file(&digest) {
849            cached_path
850        } else {
851            let stm = pkg_loader.stream_content(package, &release).await?;
852
853            self.cache.ensure_dirs().await?;
854            let final_dest = self.cache.wasm_path(&digest);
855
856            verified_download_stream(
857                stm,
858                &format!("{}:{}", package.namespace(), package.name()),
859                &digest,
860                &final_dest,
861                DestinationConvention::ContentIndexed,
862            )
863            .await?;
864
865            final_dest
866        };
867
868        Ok(path)
869    }
870
871    /// Loads a dependency and returns a fully resolved locked component dependency.
872    pub async fn load_component_dependency(
873        &self,
874        dependency_name: &DependencyName,
875        dependency: &v2::ComponentDependency,
876    ) -> Result<locked::LockedComponentDependency> {
877        let inherit = locked_inherit(dependency);
878
879        let (content, export) = self
880            .load_dependency_content(dependency_name, dependency)
881            .await?;
882
883        Ok(locked::LockedComponentDependency {
884            source: locked::LockedComponentSource {
885                content_type: "application/wasm".into(),
886                content: file_content_ref(content)?,
887            },
888            export,
889            inherit,
890        })
891    }
892
893    /// Loads a dependency and returns a fully resolved locked component dependency.
894    pub async fn load_trigger_dependency(
895        &self,
896        dependency: &v2::TriggerDependency,
897    ) -> Result<locked::LockedComponentDependency> {
898        let as_component_dep = match dependency.clone() {
899            v2::TriggerDependency::Package {
900                version,
901                registry,
902                package,
903                inherit_configuration,
904            } => v2::ComponentDependency::Package {
905                version,
906                registry,
907                package: Some(package),
908                export: None,
909                inherit_configuration,
910            },
911            v2::TriggerDependency::Local {
912                path,
913                inherit_configuration,
914            } => v2::ComponentDependency::Local {
915                path,
916                export: None,
917                inherit_configuration,
918            },
919            v2::TriggerDependency::HTTP {
920                url,
921                digest,
922                inherit_configuration,
923            } => v2::ComponentDependency::HTTP {
924                url,
925                digest,
926                export: None,
927                inherit_configuration,
928            },
929            v2::TriggerDependency::AppComponent {
930                component,
931                inherit_configuration,
932            } => v2::ComponentDependency::AppComponent {
933                component,
934                export: None,
935                inherit_configuration,
936            },
937        };
938
939        let inherit = locked_inherit(&as_component_dep);
940
941        let fake_dep_name =
942            DependencyName::Plain(KebabId::try_from("to-do-fix-fix-fix".to_string()).unwrap());
943
944        let (content, export) = self
945            .load_dependency_content(&fake_dep_name, &as_component_dep)
946            .await?;
947
948        Ok(locked::LockedComponentDependency {
949            source: locked::LockedComponentSource {
950                content_type: "application/wasm".into(),
951                content: file_content_ref(content)?,
952            },
953            export,
954            inherit,
955        })
956    }
957
958    /// Loads the content path and export for a dependency.
959    pub async fn load_dependency_content(
960        &self,
961        dependency_name: &DependencyName,
962        dependency: &v2::ComponentDependency,
963    ) -> Result<(PathBuf, Option<String>)> {
964        match dependency.clone() {
965            v2::ComponentDependency::Version(version) => {
966                let version = semver::VersionReq::parse(&version).with_context(|| format!("Component dependency {dependency_name:?} specifies an invalid semantic version requirement ({version:?}) for its package version"))?;
967
968                // This `unwrap()` should be OK because we've already validated
969                // this form of dependency requires a package name, i.e. the
970                // dependency name is not a kebab id.
971                let package = dependency_name.package().unwrap();
972
973                let content = self.load_registry_source(None, package, &version).await?;
974                Ok((content, None))
975            }
976            v2::ComponentDependency::Package {
977                version,
978                registry,
979                package,
980                export,
981                ..
982            } => {
983                let version = semver::VersionReq::parse(&version).with_context(|| format!("Component dependency {dependency_name:?} specifies an invalid semantic version requirement ({version:?}) for its package version"))?;
984
985                let package = match package {
986                    Some(package) => {
987                        package.parse().with_context(|| format!("Component dependency {dependency_name:?} specifies an invalid package name ({package:?})"))?
988                    }
989                    None => {
990                        // This `unwrap()` should be OK because we've already validated
991                        // this form of dependency requires a package name, i.e. the
992                        // dependency name is not a kebab id.
993                        dependency_name
994                            .package()
995                            .cloned()
996                            .unwrap()
997                    }
998                };
999
1000                let registry = match registry {
1001                    Some(registry) => {
1002                        registry
1003                            .parse()
1004                            .map(Some)
1005                            .with_context(|| format!("Component dependency {dependency_name:?} specifies an invalid registry name ({registry:?})"))?
1006                    }
1007                    None => None,
1008                };
1009
1010                let content = self
1011                    .load_registry_source(registry.as_ref(), &package, &version)
1012                    .await?;
1013                Ok((content, export))
1014            }
1015            v2::ComponentDependency::Local { path, export, .. } => {
1016                let content = self.app_root.join(path);
1017                Ok((content, export))
1018            }
1019            v2::ComponentDependency::HTTP {
1020                url,
1021                digest,
1022                export,
1023                ..
1024            } => {
1025                let content = self.load_http_source(&url, &digest).await?;
1026                Ok((content, export))
1027            }
1028            v2::ComponentDependency::AppComponent { .. } => {
1029                panic!("Internal error: component ID dependency was not resolved to a source");
1030            }
1031        }
1032    }
1033}
1034
1035fn locked_inherit(dependency: &v2::ComponentDependency) -> locked::InheritConfiguration {
1036    match dependency.inherit_configuration() {
1037        Some(v2::InheritConfiguration::All(true)) => locked::InheritConfiguration::All,
1038        Some(v2::InheritConfiguration::Some(keys)) => {
1039            locked::InheritConfiguration::Some(keys.clone())
1040        }
1041        Some(v2::InheritConfiguration::All(false)) | None => {
1042            locked::InheritConfiguration::Some(vec![])
1043        }
1044    }
1045}
1046
1047fn looks_like_glob_pattern(s: impl AsRef<str>) -> bool {
1048    let s = s.as_ref();
1049    glob::Pattern::escape(s) != s
1050}
1051
1052fn file_content_ref(path: impl AsRef<Path>) -> Result<ContentRef> {
1053    Ok(ContentRef {
1054        source: Some(file_url(path)?),
1055        ..Default::default()
1056    })
1057}
1058
1059fn file_url(path: impl AsRef<Path>) -> Result<String> {
1060    let path = path.as_ref();
1061    let abs_path = safe_canonicalize(path)
1062        .with_context(|| format!("Couldn't resolve `{}`", path.display()))?;
1063    Ok(Url::from_file_path(abs_path).unwrap().to_string())
1064}
1065
1066/// Determines if a component requires the host to support local
1067/// service chaining.
1068pub fn requires_service_chaining(component: &spin_manifest::schema::v2::Component) -> bool {
1069    component
1070        .normalized_allowed_outbound_hosts()
1071        .unwrap_or_default()
1072        .iter()
1073        .any(|h| is_chaining_host(h))
1074}
1075
1076fn is_chaining_host(pattern: &str) -> bool {
1077    AllowedHostConfig::parse(pattern).is_ok_and(|config| config.is_for_service_chaining())
1078}
1079
1080const SLOTH_WARNING_DELAY_MILLIS: u64 = 1250;
1081
1082fn warn_if_component_load_slothful() -> sloth::SlothGuard {
1083    let message = "Loading Wasm components is taking a few seconds...";
1084    sloth::warn_if_slothful(SLOTH_WARNING_DELAY_MILLIS, format!("{message}\n"))
1085}
1086
1087#[cfg(test)]
1088mod test {
1089    use super::*;
1090
1091    async fn load_test_case(
1092        testcase_dir: &str,
1093        manifest_file: &str,
1094    ) -> anyhow::Result<(tempfile::TempDir, LockedApp)> {
1095        let app_root = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
1096            .join("tests")
1097            .join(testcase_dir);
1098        let wd = tempfile::tempdir()?;
1099        let loader = LocalLoader::new(
1100            &app_root,
1101            FilesMountStrategy::Copy(wd.path().to_owned()),
1102            None,
1103            None,
1104        )
1105        .await?;
1106        let locked_app = loader.load_file(app_root.join(manifest_file)).await;
1107        locked_app.map(|locked| (wd, locked))
1108    }
1109
1110    #[tokio::test]
1111    async fn bad_destination_filename_is_explained() -> anyhow::Result<()> {
1112        let err = load_test_case("file-errors", "bad.toml")
1113            .await
1114            .expect_err("loader should not have succeeded");
1115        let err_ctx = format!("{err:#}");
1116        assert!(
1117            err_ctx.contains(r#""/" is not a valid destination file name"#),
1118            "expected error to show destination file name but got {err_ctx}",
1119        );
1120        Ok(())
1121    }
1122
1123    fn trigger_by_route<'a>(locked: &'a LockedApp, route: &str) -> &'a LockedTrigger {
1124        fn route_of(trigger: &LockedTrigger) -> &str {
1125            trigger
1126                .trigger_config
1127                .get("route")
1128                .and_then(|v| v.as_str())
1129                .unwrap()
1130        }
1131        locked
1132            .triggers
1133            .iter()
1134            .find(|t| route_of(t) == route)
1135            .unwrap()
1136    }
1137
1138    fn component_for_route<'a>(locked: &'a LockedApp, route: &str) -> &'a LockedComponent {
1139        let component_id = component_id(trigger_by_route(locked, route));
1140        locked
1141            .components
1142            .iter()
1143            .find(|c| c.id == component_id)
1144            .unwrap()
1145    }
1146
1147    fn component_id(trigger: &LockedTrigger) -> &str {
1148        trigger
1149            .trigger_config
1150            .get("component")
1151            .and_then(|v| v.as_str())
1152            .unwrap()
1153    }
1154
1155    fn component_trigger_deps_for_route<'a>(
1156        locked: &'a LockedApp,
1157        route: &str,
1158        key: &str,
1159    ) -> &'a Vec<LockedComponentDependency> {
1160        let component = component_for_route(locked, route);
1161        component
1162            .trigger_dependencies
1163            .get(key)
1164            .expect("should have had trigger deps for key")
1165    }
1166
1167    #[tokio::test]
1168    async fn unenriched_lockfile_is_unchanged() {
1169        let (_wd, locked_app) = load_test_case("extra-components", "vanilla.toml")
1170            .await
1171            .unwrap();
1172        assert_eq!(3, locked_app.triggers.len());
1173        assert_eq!(2, locked_app.components.len());
1174    }
1175
1176    #[tokio::test]
1177    async fn enriched_lockfile_only_one_trigger_per_component_no_changes() {
1178        let (_wd, locked_app) = load_test_case("extra-components", "inoffensive.toml")
1179            .await
1180            .unwrap();
1181        assert_eq!(2, locked_app.triggers.len());
1182        assert_eq!("a", component_id(trigger_by_route(&locked_app, "/a")));
1183        assert_eq!("b", component_id(trigger_by_route(&locked_app, "/b")));
1184        assert_eq!(5, locked_app.components.len());
1185    }
1186
1187    #[tokio::test]
1188    async fn enriched_lockfile_multiple_enriched_triggers_per_component_get_split() {
1189        let (_wd, locked_app) = load_test_case("extra-components", "three-to-one.toml")
1190            .await
1191            .unwrap();
1192        assert_eq!(4, locked_app.triggers.len());
1193        // Splitting should result in triggers pointing to different IDs, but the same primary source
1194        assert_ne!("a", component_id(trigger_by_route(&locked_app, "/a1")));
1195        assert!(
1196            component_for_route(&locked_app, "/a1")
1197                .source
1198                .content
1199                .source
1200                .as_ref()
1201                .unwrap()
1202                .ends_with("/a.dummy.wasm.txt")
1203        );
1204        assert_ne!("a", component_id(trigger_by_route(&locked_app, "/a2")));
1205        assert!(
1206            component_for_route(&locked_app, "/a3")
1207                .source
1208                .content
1209                .source
1210                .as_ref()
1211                .unwrap()
1212                .ends_with("/a.dummy.wasm.txt")
1213        );
1214        assert_ne!("a", component_id(trigger_by_route(&locked_app, "/a3")));
1215        assert!(
1216            component_for_route(&locked_app, "/a3")
1217                .source
1218                .content
1219                .source
1220                .as_ref()
1221                .unwrap()
1222                .ends_with("/a.dummy.wasm.txt")
1223        );
1224        // Triggers that don't need splitting should be unaffected
1225        assert_eq!("b", component_id(trigger_by_route(&locked_app, "/b")));
1226        // There should be new components inserted for the split
1227        assert_eq!(8, locked_app.components.len());
1228    }
1229
1230    // Content refs have `file:` URIs with absolute paths. This is great for
1231    // definiteness but not so convenient for testing!
1232    fn content_ref_to_file_name(content_ref: &ContentRef) -> String {
1233        let url = content_ref.source.as_ref().unwrap();
1234        let url = Url::parse(url).unwrap();
1235        let file_path = PathBuf::from(url.path());
1236        file_path.file_name().unwrap().to_string_lossy().to_string()
1237    }
1238
1239    #[tokio::test]
1240    async fn enriched_lockfile_captures_composition_graph_in_split_component() {
1241        let (_wd, locked_app) = load_test_case("extra-components", "three-to-one.toml")
1242            .await
1243            .unwrap();
1244        assert_eq!(4, locked_app.triggers.len());
1245
1246        let a1_mw = component_trigger_deps_for_route(&locked_app, "/a1", "middleware");
1247        assert_eq!(2, a1_mw.len());
1248        assert_eq!(
1249            "a.dummy.wasm.txt",
1250            content_ref_to_file_name(&a1_mw[0].source.content)
1251        );
1252        assert_eq!(
1253            "b.dummy.wasm.txt",
1254            content_ref_to_file_name(&a1_mw[1].source.content)
1255        );
1256
1257        let a2_mw = component_trigger_deps_for_route(&locked_app, "/a2", "middleware");
1258        assert_eq!(2, a2_mw.len());
1259        assert_eq!(
1260            "b.dummy.wasm.txt",
1261            content_ref_to_file_name(&a2_mw[0].source.content)
1262        );
1263        assert_eq!(
1264            "c.dummy.wasm.txt",
1265            content_ref_to_file_name(&a2_mw[1].source.content)
1266        );
1267
1268        let a3_mw = component_trigger_deps_for_route(&locked_app, "/a3", "middleware");
1269        assert_eq!(3, a3_mw.len());
1270        assert_eq!(
1271            "c.dummy.wasm.txt",
1272            content_ref_to_file_name(&a3_mw[0].source.content)
1273        );
1274        assert_eq!(
1275            "b.dummy.wasm.txt",
1276            content_ref_to_file_name(&a3_mw[1].source.content)
1277        );
1278        assert_eq!(
1279            "a.dummy.wasm.txt",
1280            content_ref_to_file_name(&a3_mw[2].source.content)
1281        );
1282
1283        // Unsplit things should still get the shunt
1284        let b_mw = component_trigger_deps_for_route(&locked_app, "/b", "middleware");
1285        assert_eq!(2, b_mw.len());
1286        assert_eq!(
1287            "a.dummy.wasm.txt",
1288            content_ref_to_file_name(&b_mw[0].source.content)
1289        );
1290        assert_eq!(
1291            "c.dummy.wasm.txt",
1292            content_ref_to_file_name(&b_mw[1].source.content)
1293        );
1294    }
1295
1296    #[tokio::test]
1297    async fn deps_moved_off_trigger() {
1298        let (_wd, locked_app) = load_test_case("extra-components", "three-to-one.toml")
1299            .await
1300            .unwrap();
1301        assert_eq!(4, locked_app.triggers.len());
1302
1303        for t in &locked_app.triggers {
1304            assert!(t.trigger_dependencies.is_empty());
1305        }
1306    }
1307}