spin_environments/

lib.rs

use std::{collections::HashMap, sync::Arc};

use anyhow::{Context, anyhow};

mod environment;
mod loader;

use environment::{CandidateWorld, CandidateWorlds, TargetEnvironment, TriggerType};
pub use environment::{Catalogue, EnvironmentDefinition, load_environment_def};
pub use loader::ApplicationToValidate;
use loader::ComponentToValidate;
use spin_manifest::schema::v2::TargetEnvironmentRef;

use crate::environment::RealisedTargets;

#[derive(Default)]
pub struct Targets<'a> {
    pub default: &'a [TargetEnvironmentRef],
    pub overrides: HashMap<String, &'a [TargetEnvironmentRef]>,
}

impl<'a> Targets<'a> {
    fn is_empty(&self) -> bool {
        self.default.is_empty() && self.overrides.is_empty()
    }

    fn all_refs(&self) -> Vec<&TargetEnvironmentRef> {
        let mut set = std::collections::HashSet::new();
        for env_id in self.default {
            set.insert(env_id);
        }
        for list in self.overrides.values() {
            for env_id in *list {
                set.insert(env_id);
            }
        }
        set.into_iter().collect()
    }
}

/// The result of validating an application against a list of target environments.
/// If `is_ok` returns true (or equivalently if the `errors` collection is empty),
/// the application passed validation, and can run in all the environments against
/// which it was checked. Otherwise, at least one component cannot run in at least
/// one target environment, and the `errors` collection contains the details.
#[derive(Default)]
pub struct TargetEnvironmentValidation(Vec<anyhow::Error>);

impl TargetEnvironmentValidation {
    pub fn is_ok(&self) -> bool {
        self.0.is_empty()
    }

    pub fn errors(&self) -> &[anyhow::Error] {
        &self.0
    }
}

/// Validates *all* application components against the list of referenced target enviroments. Each component must conform
/// to *all* environments to pass.
///
/// If the return value is `Ok(...)`, this means only that we were able to perform the validation.
/// The caller **MUST** still check the returned [TargetEnvironmentValidation] to determine the
/// outcome of validation.
///
/// If the return value is `Err(...)`, then we weren't able even to attempt validation.
pub async fn validate_application_against_environment_ids<'a>(
    application: &ApplicationToValidate,
    targets: Targets<'a>,
    cache_root: Option<std::path::PathBuf>,
    app_dir: &std::path::Path,
) -> anyhow::Result<TargetEnvironmentValidation> {
    if targets.is_empty() {
        return Ok(Default::default());
    }

    let envs = TargetEnvironment::load_all(targets, cache_root, app_dir).await?;
    validate_application_against_environments(application, &envs).await
}

/// Validates *all* application components against the list of (realised) target enviroments. Each component must conform
/// to *all* environments to pass.
///
/// For the slightly funky return type, see [validate_application_against_environment_ids].
async fn validate_application_against_environments(
    application: &ApplicationToValidate,
    envs: &RealisedTargets,
) -> anyhow::Result<TargetEnvironmentValidation> {
    for trigger_type in application.trigger_types() {
        if let Some(env) = envs.iter().find(|e| !e.supports_trigger_type(trigger_type)) {
            anyhow::bail!(
                "Environment {} does not support trigger type {trigger_type}",
                env.name()
            );
        }
    }

    let components_by_trigger_type = application.components_by_trigger_type().await?;

    let mut errs = vec![];

    for (trigger_type, component) in components_by_trigger_type {
        for component in &component {
            let envs = envs.get(component.id());
            errs.extend(
                validate_component_against_environments(envs, &trigger_type, component).await,
            );
        }
    }

    Ok(TargetEnvironmentValidation(errs))
}

/// Validates the component against the list of target enviroments. The component must conform
/// to *all* environments to pass.
///
/// The return value contains the list of validation errors. There may be up to one error per
/// target environment, explaining why the component cannot run in that environment.
/// An empty list means the component has passed validation and is compatible with
/// all target environments.
async fn validate_component_against_environments(
    envs: &[Arc<TargetEnvironment>],
    trigger_type: &TriggerType,
    component: &ComponentToValidate<'_>,
) -> Vec<anyhow::Error> {
    let mut errs = vec![];

    for env in envs {
        let worlds = env.worlds(trigger_type);
        if let Some(e) = validate_wasm_against_any_world(env, worlds, component)
            .await
            .err()
        {
            errs.push(e);
        }

        let host_caps = env.capabilities(trigger_type);
        if let Some(e) = validate_host_reqs(env, host_caps, component).err() {
            errs.push(e);
        }
    }

    if errs.is_empty() {
        tracing::info!(
            "Validated component {} {} against all target worlds",
            component.id(),
            component.source_description()
        );
    }

    errs
}

/// Validates the component against the list of candidate worlds. The component must conform
/// to *at least one* candidate world to pass (since if it can run in one world provided by
/// the target environment, it can run in the target environment).
async fn validate_wasm_against_any_world(
    env: &TargetEnvironment,
    worlds: &CandidateWorlds,
    component: &ComponentToValidate<'_>,
) -> anyhow::Result<()> {
    let mut result = Ok(());
    for target_world in worlds {
        tracing::debug!(
            "Trying component {} {} against target world {target_world}",
            component.id(),
            component.source_description(),
        );
        match validate_wasm_against_world(env, target_world, component).await {
            Ok(()) => {
                tracing::info!(
                    "Validated component {} {} against target world {target_world}",
                    component.id(),
                    component.source_description(),
                );
                return Ok(());
            }
            Err(e) => {
                // Record the error, but continue in case a different world succeeds
                tracing::info!(
                    "Rejecting component {} {} for target world {target_world} because {e:?}",
                    component.id(),
                    component.source_description(),
                );
                result = Err(e);
            }
        }
    }
    result
}

async fn validate_wasm_against_world(
    env: &TargetEnvironment,
    target_world: &CandidateWorld,
    component: &ComponentToValidate<'_>,
) -> anyhow::Result<()> {
    use wac_types::{ItemKind, Package as WacPackage, Types as WacTypes, WorldId, validate_target};

    // Gets the selected world from the component encoded WIT package
    // TODO: make this an export on `wac_types::Types`.
    fn get_wit_world(
        types: &WacTypes,
        top_level_world: WorldId,
        world_name: &str,
    ) -> anyhow::Result<WorldId> {
        let top_level_world = &types[top_level_world];
        let world = top_level_world
            .exports
            .get(world_name)
            .with_context(|| format!("wit package did not contain a world named '{world_name}'"))?;

        let ItemKind::Type(wac_types::Type::World(world_id)) = world else {
            // We expect the top-level world to export a world type
            anyhow::bail!("wit package was not encoded properly")
        };
        let wit_world = &types[*world_id];
        let world = wit_world.exports.values().next();
        let Some(ItemKind::Component(w)) = world else {
            // We expect the nested world type to export a component
            anyhow::bail!("wit package was not encoded properly")
        };
        Ok(*w)
    }

    let mut types = WacTypes::default();

    let target_world_package = WacPackage::from_bytes(
        &target_world.package_namespaced_name(),
        target_world.package_version(),
        target_world.package_bytes(),
        &mut types,
    )?;

    let target_world_id =
        get_wit_world(&types, target_world_package.ty(), target_world.world_name())?;

    let component_package =
        WacPackage::from_bytes(component.id(), None, component.wasm_bytes(), &mut types)?;

    let target_result = validate_target(&types, target_world_id, component_package.ty());

    match target_result {
        Ok(_) => Ok(()),
        Err(report) => Err(format_target_result_error(
            &types,
            env.name(),
            target_world.to_string(),
            component.id(),
            component.source_description(),
            &report,
        )),
    }
}

fn validate_host_reqs(
    env: &TargetEnvironment,
    host_caps: &[String],
    component: &ComponentToValidate,
) -> anyhow::Result<()> {
    let unsatisfied: Vec<_> = component
        .host_requirements()
        .iter()
        .filter(|host_req| !satisfies(host_caps, host_req))
        .cloned()
        .collect();
    if unsatisfied.is_empty() {
        Ok(())
    } else {
        Err(anyhow!(
            "Component {} can't run in environment {} because it requires the feature(s) '{}' which the environment does not support",
            component.id(),
            env.name(),
            unsatisfied.join(", ")
        ))
    }
}

fn satisfies(host_caps: &[String], host_req: &String) -> bool {
    host_caps.contains(host_req)
}

fn format_target_result_error(
    types: &wac_types::Types,
    env_name: &str,
    target_world_name: String,
    component_id: &str,
    source_description: &str,
    report: &wac_types::TargetValidationReport,
) -> anyhow::Error {
    let mut error_string = format!(
        "Component {component_id} ({source_description}) can't run in environment {env_name} (world {target_world_name}).\n",
    );

    for (idx, import) in report.imports_not_in_target().enumerate() {
        if idx == 0 {
            error_string.push_str(
                "The component requires the following imports, which the environment does not provide:\n  - ",
            );
        } else {
            error_string.push_str("  - ");
        }
        error_string.push_str(import);
        error_string.push('\n');
    }

    for (idx, (export, export_kind)) in report.missing_exports().enumerate() {
        if idx == 0 {
            error_string.push_str(
                "The environment requires the following exports, which the component does not provide:\n  - ",
            );
        } else {
            error_string.push_str("  - ");
        }
        error_string.push_str(export);
        error_string.push_str(" (");
        error_string.push_str(export_kind.desc(types));
        error_string.push_str(")\n");
    }

    for (name, extern_kind, error) in report.mismatched_types() {
        error_string.push_str("Found a type mismatch for ");
        error_string.push_str(&format!("{extern_kind} {name}: {error}"));
    }

    anyhow!(error_string)
}