|
| 1 | +//! Spin doctor: check and automatically fix problems with Spin apps. |
| 2 | +#![deny(missing_docs)] |
| 3 | + |
| 4 | +use std::{fmt::Debug, fs, future::Future, path::PathBuf, pin::Pin, process::Command, sync::Arc}; |
| 5 | + |
| 6 | +use anyhow::{ensure, Context, Result}; |
| 7 | +use async_trait::async_trait; |
| 8 | +use tokio::sync::Mutex; |
| 9 | +use toml_edit::Document; |
| 10 | + |
| 11 | +/// Diagnoses for app manifest format problems. |
| 12 | +pub mod manifest; |
| 13 | +/// Test helpers. |
| 14 | +pub mod test; |
| 15 | +/// Diagnoses for Wasm source problems. |
| 16 | +pub mod wasm; |
| 17 | + |
| 18 | +/// Configuration for an app to be checked for problems. |
| 19 | +pub struct Checkup { |
| 20 | + manifest_path: PathBuf, |
| 21 | + diagnose_fns: Vec<DiagnoseFn>, |
| 22 | +} |
| 23 | + |
| 24 | +type DiagnoseFut<'a> = |
| 25 | + Pin<Box<dyn Future<Output = Result<Vec<Box<dyn Diagnosis + 'static>>>> + 'a>>; |
| 26 | +type DiagnoseFn = for<'a> fn(&'a PatientApp) -> DiagnoseFut<'a>; |
| 27 | + |
| 28 | +impl Checkup { |
| 29 | + /// Return a new checkup for the app manifest at the given path. |
| 30 | + pub fn new(manifest_path: impl Into<PathBuf>) -> Self { |
| 31 | + let mut config = Self { |
| 32 | + manifest_path: manifest_path.into(), |
| 33 | + diagnose_fns: vec![], |
| 34 | + }; |
| 35 | + config.add_diagnose::<manifest::version::VersionDiagnosis>(); |
| 36 | + config.add_diagnose::<manifest::trigger::TriggerDiagnosis>(); |
| 37 | + config.add_diagnose::<wasm::missing::WasmMissing>(); |
| 38 | + config |
| 39 | + } |
| 40 | + |
| 41 | + /// Add a detectable problem to this checkup. |
| 42 | + pub fn add_diagnose<D: Diagnose + 'static>(&mut self) -> &mut Self { |
| 43 | + self.diagnose_fns.push(diagnose_boxed::<D>); |
| 44 | + self |
| 45 | + } |
| 46 | + |
| 47 | + fn patient(&self) -> Result<PatientApp> { |
| 48 | + let path = &self.manifest_path; |
| 49 | + ensure!( |
| 50 | + path.is_file(), |
| 51 | + "No Spin app manifest file found at {path:?}" |
| 52 | + ); |
| 53 | + |
| 54 | + let contents = fs::read_to_string(path) |
| 55 | + .with_context(|| format!("Couldn't read Spin app manifest file at {path:?}"))?; |
| 56 | + |
| 57 | + let manifest_doc: Document = contents |
| 58 | + .parse() |
| 59 | + .with_context(|| format!("Couldn't parse manifest file at {path:?} as valid TOML"))?; |
| 60 | + |
| 61 | + Ok(PatientApp { |
| 62 | + manifest_path: path.into(), |
| 63 | + manifest_doc, |
| 64 | + }) |
| 65 | + } |
| 66 | + |
| 67 | + /// Find problems with the configured app, calling the given closure with |
| 68 | + /// each problem found. |
| 69 | + pub async fn for_each_diagnosis<F>(&self, mut f: F) -> Result<usize> |
| 70 | + where |
| 71 | + F: for<'a> FnMut( |
| 72 | + Box<dyn Diagnosis + 'static>, |
| 73 | + &'a mut PatientApp, |
| 74 | + ) -> Pin<Box<dyn Future<Output = Result<()>> + 'a>>, |
| 75 | + { |
| 76 | + let patient = Arc::new(Mutex::new(self.patient()?)); |
| 77 | + let mut count = 0; |
| 78 | + for diagnose in &self.diagnose_fns { |
| 79 | + let patient = patient.clone(); |
| 80 | + let diags = diagnose(&*patient.lock().await) |
| 81 | + .await |
| 82 | + .unwrap_or_else(|err| { |
| 83 | + tracing::debug!("Diagnose failed: {err:?}"); |
| 84 | + vec![] |
| 85 | + }); |
| 86 | + count += diags.len(); |
| 87 | + for diag in diags { |
| 88 | + let mut patient = patient.lock().await; |
| 89 | + f(diag, &mut patient).await?; |
| 90 | + } |
| 91 | + } |
| 92 | + Ok(count) |
| 93 | + } |
| 94 | +} |
| 95 | + |
| 96 | +/// An app "patient" to be checked for problems. |
| 97 | +#[derive(Clone)] |
| 98 | +pub struct PatientApp { |
| 99 | + /// Path to an app manifest file. |
| 100 | + pub manifest_path: PathBuf, |
| 101 | + /// Parsed app manifest TOML document. |
| 102 | + pub manifest_doc: Document, |
| 103 | +} |
| 104 | + |
| 105 | +/// The Diagnose trait implements the detection of a particular Spin app problem. |
| 106 | +#[async_trait] |
| 107 | +pub trait Diagnose: Diagnosis + Send + Sized + 'static { |
| 108 | + /// Check the given [`Patient`], returning any problem(s) found. |
| 109 | + async fn diagnose(patient: &PatientApp) -> Result<Vec<Self>>; |
| 110 | +} |
| 111 | + |
| 112 | +fn diagnose_boxed<D: Diagnose>(patient: &PatientApp) -> DiagnoseFut { |
| 113 | + Box::pin(async { |
| 114 | + let diags = D::diagnose(patient).await?; |
| 115 | + Ok(diags.into_iter().map(|diag| Box::new(diag) as _).collect()) |
| 116 | + }) |
| 117 | +} |
| 118 | + |
| 119 | +/// The Diagnosis trait represents a detected problem with a Spin app. |
| 120 | +pub trait Diagnosis: Debug + Send + Sync { |
| 121 | + /// Return a human-friendly description of this problem. |
| 122 | + fn description(&self) -> String; |
| 123 | + |
| 124 | + /// Return true if this problem is "critical", i.e. if the app's |
| 125 | + /// configuration or environment is invalid. Return false for |
| 126 | + /// "non-critical" problems like deprecations. |
| 127 | + fn is_critical(&self) -> bool { |
| 128 | + true |
| 129 | + } |
| 130 | + |
| 131 | + /// Return a [`Treatment`] that can (potentially) fix this problem, or |
| 132 | + /// None if there is no automatic fix. |
| 133 | + fn treatment(&self) -> Option<&dyn Treatment> { |
| 134 | + None |
| 135 | + } |
| 136 | +} |
| 137 | + |
| 138 | +/// The Treatment trait represents a (potential) fix for a detected problem. |
| 139 | +#[async_trait] |
| 140 | +pub trait Treatment: Sync { |
| 141 | + /// Return a human-readable description of what this treatment will do to |
| 142 | + /// fix the problem, such as a file diff. |
| 143 | + async fn description(&self, patient: &PatientApp) -> Result<String>; |
| 144 | + |
| 145 | + /// Attempt to fix this problem. Return Ok only if the problem is |
| 146 | + /// successfully fixed. |
| 147 | + async fn treat(&self, patient: &mut PatientApp) -> Result<()>; |
| 148 | +} |
| 149 | + |
| 150 | +const SPIN_BIN_PATH: &str = "SPIN_BIN_PATH"; |
| 151 | + |
| 152 | +/// Return a [`Command`] targeting the `spin` binary. The `spin` path is |
| 153 | +/// resolved to the first of these that is available: |
| 154 | +/// - the `SPIN_BIN_PATH` environment variable |
| 155 | +/// - the current executable ([`std::env::current_exe`]) |
| 156 | +/// - the constant `"spin"` (resolved by e.g. `$PATH`) |
| 157 | +pub fn spin_command() -> Command { |
| 158 | + let spin_path = std::env::var_os(SPIN_BIN_PATH) |
| 159 | + .map(PathBuf::from) |
| 160 | + .or_else(|| std::env::current_exe().ok()) |
| 161 | + .unwrap_or("spin".into()); |
| 162 | + Command::new(spin_path) |
| 163 | +} |
0 commit comments