spin_templates/
source.rs

1use std::path::{Path, PathBuf};
2
3use anyhow::{anyhow, Context};
4use tempfile::{tempdir, TempDir};
5use tokio::process::Command;
6use url::Url;
7
8use crate::{directory::subdirectories, git::UnderstandGitResult};
9
10const TEMPLATE_SOURCE_DIR: &str = "templates";
11const TEMPLATE_VERSION_TAG_PREFIX: &str = "spin/templates/v";
12
13/// A source from which to install templates.
14#[derive(Debug)]
15pub enum TemplateSource {
16    /// Install from a Git repository at the specified URL. If a branch is
17    /// specified, templates are installed from that branch or tag; otherwise,
18    /// they are installed from HEAD.
19    ///
20    /// Templates much be in a `/templates` directory under the root of the
21    /// repository.
22    Git(GitTemplateSource),
23    /// Install from a directory in the file system.
24    ///
25    /// Templates much be in a `/templates` directory under the specified
26    /// root.
27    File(PathBuf),
28    /// Install from a remote tarball.
29    ///
30    /// Templates should be in a `/templates` directory under the root of the tarball.
31    /// The implementation also allows for there to be a single root directory containing
32    /// the `templates` directory - this makes it compatible with GitHub release tarballs.
33    RemoteTar(Url),
34}
35
36/// Settings for installing templates from a Git repository.
37#[derive(Debug)]
38pub struct GitTemplateSource {
39    /// The URL of the Git repository from which to install templates.
40    url: Url,
41    /// The branch or tag from which to install templates; inferred if omitted.
42    branch: Option<String>,
43    /// The version of the Spin client, used for branch inference.
44    // We have to pass this through because vergen is only on the root bin
45    spin_version: String,
46}
47
48impl TemplateSource {
49    /// Creates a `TemplateSource` referring to the specified Git repository
50    /// and branch.
51    pub fn try_from_git(
52        git_url: impl AsRef<str>,
53        branch: &Option<String>,
54        spin_version: &str,
55    ) -> anyhow::Result<Self> {
56        let url_str = git_url.as_ref();
57        let url =
58            Url::parse(url_str).with_context(|| format!("Failed to parse {} as URL", url_str))?;
59        Ok(Self::Git(GitTemplateSource {
60            url,
61            branch: branch.clone(),
62            spin_version: spin_version.to_owned(),
63        }))
64    }
65
66    pub(crate) fn to_install_record(&self) -> Option<crate::reader::RawInstalledFrom> {
67        match self {
68            Self::Git(g) => Some(crate::reader::RawInstalledFrom::Git {
69                git: g.url.to_string(),
70            }),
71            Self::File(p) => {
72                // Saving a relative path would be meaningless (but should never happen)
73                if p.is_absolute() {
74                    Some(crate::reader::RawInstalledFrom::File {
75                        dir: format!("{}", p.display()),
76                    })
77                } else {
78                    None
79                }
80            }
81            Self::RemoteTar(url) => Some(crate::reader::RawInstalledFrom::RemoteTar {
82                url: url.to_string(),
83            }),
84        }
85    }
86
87    // Sorry I know this is a bit ugly
88    /// For a Git source, resolves the tag to use as the source.
89    /// For other sources, returns None.
90    pub async fn resolved_tag(&self) -> Option<String> {
91        match self {
92            Self::Git(g) => version_matched_tag(g.url.as_str(), &g.spin_version).await,
93            _ => None,
94        }
95    }
96}
97
98pub(crate) struct LocalTemplateSource {
99    root: PathBuf,
100    _temp_dir: Option<TempDir>,
101}
102
103impl TemplateSource {
104    pub(crate) async fn get_local(&self) -> anyhow::Result<LocalTemplateSource> {
105        match self {
106            Self::Git(git_source) => clone_local(git_source).await,
107            Self::File(path) => check_local(path).await,
108            Self::RemoteTar(url) => download_untar_local(url).await,
109        }
110    }
111
112    pub(crate) fn requires_copy(&self) -> bool {
113        match self {
114            Self::Git { .. } => true,
115            Self::File(_) => false,
116            Self::RemoteTar(_) => true,
117        }
118    }
119}
120
121impl LocalTemplateSource {
122    pub async fn template_directories(&self) -> anyhow::Result<Vec<PathBuf>> {
123        let templates_root = self.root.join(TEMPLATE_SOURCE_DIR);
124        if templates_root.exists() {
125            subdirectories(&templates_root).with_context(|| {
126                format!(
127                    "Failed to read contents of '{}' directory",
128                    TEMPLATE_SOURCE_DIR
129                )
130            })
131        } else {
132            Err(anyhow!(
133                "Template source {} does not contain a '{}' directory",
134                self.root.display(),
135                TEMPLATE_SOURCE_DIR
136            ))
137        }
138    }
139}
140
141async fn clone_local(git_source: &GitTemplateSource) -> anyhow::Result<LocalTemplateSource> {
142    let temp_dir = tempdir()?;
143    let path = temp_dir.path().to_owned();
144
145    let url_str = git_source.url.as_str();
146
147    let actual_branch = match &git_source.branch {
148        Some(b) => Some(b.clone()),
149        None => version_matched_tag(url_str, &git_source.spin_version).await,
150    };
151
152    let mut git = Command::new("git");
153    git.arg("clone");
154    git.arg("--depth").arg("1");
155
156    if let Some(b) = actual_branch {
157        git.arg("--branch").arg(b);
158    }
159
160    git.arg(url_str).arg(&path);
161
162    let clone_result = git.output().await.understand_git_result();
163    match clone_result {
164        Ok(_) => Ok(LocalTemplateSource {
165            root: path,
166            _temp_dir: Some(temp_dir),
167        }),
168        Err(e) => Err(anyhow!("Error cloning Git repo {}: {}", url_str, e)),
169    }
170}
171
172async fn version_matched_tag(url: &str, spin_version: &str) -> Option<String> {
173    let preferred_tag = version_preferred_tag(spin_version);
174
175    let mut git = Command::new("git");
176    git.arg("ls-remote");
177    git.arg("--exit-code");
178    git.arg(url);
179    git.arg(&preferred_tag);
180
181    match git.output().await.understand_git_result() {
182        Ok(_) => Some(preferred_tag),
183        Err(_) => None,
184    }
185}
186
187fn version_preferred_tag(text: &str) -> String {
188    let mm_version = match semver::Version::parse(text) {
189        Ok(version) => format!("{}.{}", version.major, version.minor),
190        Err(_) => text.to_owned(),
191    };
192    format!("{}{}", TEMPLATE_VERSION_TAG_PREFIX, mm_version)
193}
194
195async fn check_local(path: &Path) -> anyhow::Result<LocalTemplateSource> {
196    if path.exists() {
197        Ok(LocalTemplateSource {
198            root: path.to_owned(),
199            _temp_dir: None,
200        })
201    } else {
202        Err(anyhow!("Path not found: {}", path.display()))
203    }
204}
205
206/// Download a tarball to a temorary directory
207async fn download_untar_local(url: &Url) -> anyhow::Result<LocalTemplateSource> {
208    use bytes::buf::Buf;
209
210    let temp_dir = tempdir()?;
211    let path = temp_dir.path().to_owned();
212
213    let resp = reqwest::get(url.clone())
214        .await
215        .with_context(|| format!("Failed to download from {url}"))?;
216    let tar_content = resp
217        .bytes()
218        .await
219        .with_context(|| format!("Failed to download from {url}"))?;
220
221    let reader = flate2::read::GzDecoder::new(tar_content.reader());
222    let mut archive = tar::Archive::new(reader);
223    archive
224        .unpack(&path)
225        .context("Failed to unpack tar archive")?;
226
227    let templates_root = bypass_gh_added_root(path);
228
229    Ok(LocalTemplateSource {
230        root: templates_root,
231        _temp_dir: Some(temp_dir),
232    })
233}
234
235/// GitHub adds a prefix directory to release tarballs (e.g. spin-v3.0.0/...).
236/// We try to locate the repo root within the unpacked tarball.
237fn bypass_gh_added_root(unpack_dir: PathBuf) -> PathBuf {
238    // If the unpack dir directly contains a `templates` dir then we are done.
239    if has_templates_dir(&unpack_dir) {
240        return unpack_dir;
241    }
242
243    let Ok(dirs) = unpack_dir.read_dir() else {
244        // If we can't traverse the unpack directory then return it and
245        // let the top level try to make sense of it.
246        return unpack_dir;
247    };
248
249    // Is there a single directory at the root?  If not, we can't be in the GitHub situation:
250    // return the root of the unpacking. (The take(2) here is because we don't need to traverse
251    // the full list - we only care whether there is more than one.)
252    let dirs = dirs.filter_map(|de| de.ok()).take(2).collect::<Vec<_>>();
253    if dirs.len() != 1 {
254        return unpack_dir;
255    }
256
257    // If we get here, there is a single directory (dirs has a single element). Look in it to see if it's a plausible repo root.
258    let candidate_repo_root = dirs[0].path();
259    let Ok(mut candidate_repo_dirs) = candidate_repo_root.read_dir() else {
260        // Again, if it all goes awry, propose the base unpack directory.
261        return unpack_dir;
262    };
263    let has_templates_dir = candidate_repo_dirs.any(is_templates_dir);
264
265    if has_templates_dir {
266        candidate_repo_root
267    } else {
268        unpack_dir
269    }
270}
271
272fn has_templates_dir(path: &Path) -> bool {
273    let Ok(mut dirs) = path.read_dir() else {
274        return false;
275    };
276
277    dirs.any(is_templates_dir)
278}
279
280fn is_templates_dir(dir_entry: Result<std::fs::DirEntry, std::io::Error>) -> bool {
281    dir_entry.is_ok_and(|d| d.file_name() == TEMPLATE_SOURCE_DIR)
282}
283
284#[cfg(test)]
285mod test {
286    use super::*;
287
288    #[test]
289    fn preferred_tag_excludes_patch_version() {
290        assert_eq!("spin/templates/v1.2", version_preferred_tag("1.2.3"));
291    }
292
293    #[test]
294    fn preferred_tag_excludes_prerelease_and_build() {
295        assert_eq!(
296            "spin/templates/v1.2",
297            version_preferred_tag("1.2.3-preview.1")
298        );
299        assert_eq!(
300            "spin/templates/v1.2",
301            version_preferred_tag("1.2.3+build.0f74628")
302        );
303        assert_eq!(
304            "spin/templates/v1.2",
305            version_preferred_tag("1.2.3-alpha+0f74628")
306        );
307    }
308
309    #[test]
310    fn preferred_tag_defaults_sensibly_on_bad_semver() {
311        assert_eq!("spin/templates/v1.2", version_preferred_tag("1.2"));
312        assert_eq!("spin/templates/v1.2.3.4", version_preferred_tag("1.2.3.4"));
313        assert_eq!("spin/templates/vgarbage", version_preferred_tag("garbage"));
314    }
315}
spin_templates/source.rs

spin_templates/
source.rs
