Skip to main content

composer_install/
source.rs

1//! Git `source` installs — the seam for packages the lock pins to a VCS
2//! checkout instead of a dist archive.
3//!
4//! [`SourceFetcher`] materializes one package's locked revision into its
5//! `vendor/` destination. The orchestrator calls it in parallel, once per
6//! source package, and treats the result exactly like an extracted dist:
7//! patches, the Magento deploy, the autoloader and `vendor/bin` all run over
8//! it. Without a `SourceFetcher` a source-only package is a preflight error.
9//!
10//! [`GitSourceFetcher`] is the default: it shells out to the user's `git`,
11//! as Composer does, so ssh keys, credential helpers and proxies work without
12//! configuration. Repositories are cached as bare `--mirror` clones and only
13//! fetched when the locked commit is missing, so a warm cache installs
14//! offline.
15
16use std::path::{Path, PathBuf};
17use std::process::Command;
18use std::sync::OnceLock;
19
20use eyre::{Result, WrapErr, eyre};
21use sha1::Digest as _;
22
23use crate::error::{InstallError, VcsFailure};
24
25/// One package to install from its git `source`.
26#[derive(Debug, Clone, Copy)]
27pub struct SourceSpec<'a> {
28    /// The package name, for error messages.
29    pub package_name: &'a str,
30    /// Clone URL candidates in preference order (a `preferred` mirror before
31    /// the origin host — `LockPackage::source_urls`). Never empty.
32    pub urls: &'a [String],
33    /// The revision to check out — a full commit sha in a lockfile.
34    pub reference: &'a str,
35    /// Where the checkout must end up. Any existing contents are replaced.
36    pub dest: &'a Path,
37}
38
39/// Install one package from its VCS source.
40///
41/// Implementations must be `Sync`: the orchestrator calls `install` from a
42/// rayon parallel iterator.
43pub trait SourceFetcher: Sync {
44    /// Place a checkout of `spec.reference` at `spec.dest`, trying each URL in
45    /// turn. Errors should be (or wrap) [`InstallError::Vcs`] where the cause
46    /// is a git failure, so callers can map them.
47    fn install(&self, spec: &SourceSpec<'_>) -> Result<()>;
48}
49
50/// The default [`SourceFetcher`]: the system `git`, with bare mirrors cached
51/// under a caller-chosen directory.
52#[derive(Debug)]
53pub struct GitSourceFetcher {
54    mirror_root: PathBuf,
55    git_checked: OnceLock<Result<(), String>>,
56}
57
58impl GitSourceFetcher {
59    /// Cache bare mirrors under `mirror_root` (created on first use).
60    /// Composer's equivalent is `~/.composer/cache/vcs/`.
61    pub fn new(mirror_root: impl Into<PathBuf>) -> Self {
62        Self {
63            mirror_root: mirror_root.into(),
64            git_checked: OnceLock::new(),
65        }
66    }
67
68    /// Fail once, with one clear error, when `git` can't run — instead of one
69    /// error per package.
70    fn ensure_git(&self) -> Result<()> {
71        let checked =
72            self.git_checked
73                .get_or_init(|| match Command::new("git").arg("--version").output() {
74                    Ok(out) if out.status.success() => Ok(()),
75                    _ => Err(String::new()),
76                });
77        checked.clone().map_err(|_| git_missing("invocation"))
78    }
79
80    fn install_from(&self, url: &str, reference: &str, dest: &Path) -> Result<()> {
81        let mirror = self.ensure_mirror(url, reference)?;
82
83        // `git clone` refuses a non-empty target, so remove any prior tree.
84        let _ = std::fs::remove_dir_all(dest);
85        if let Some(parent) = dest.parent() {
86            std::fs::create_dir_all(parent)
87                .wrap_err_with(|| format!("creating {}", parent.display()))?;
88        }
89        run_git(
90            "clone",
91            url,
92            None,
93            &[
94                "clone".as_ref(),
95                "--quiet".as_ref(),
96                mirror.as_os_str(),
97                dest.as_os_str(),
98            ],
99        )?;
100        run_git(
101            "checkout",
102            url,
103            Some(dest),
104            &[
105                "checkout".as_ref(),
106                "--quiet".as_ref(),
107                "--detach".as_ref(),
108                reference.as_ref(),
109            ],
110        )?;
111        // Point origin back at the real remote (the clone set it to the local
112        // mirror), so the package stays a usable checkout. Best-effort.
113        let _ = run_git(
114            "set-url",
115            url,
116            Some(dest),
117            &[
118                "remote".as_ref(),
119                "set-url".as_ref(),
120                "origin".as_ref(),
121                url.as_ref(),
122            ],
123        );
124        Ok(())
125    }
126
127    /// Ensure a bare mirror of `url` exists and contains `reference`. Clones
128    /// on first use; otherwise fetches only when the revision is absent.
129    fn ensure_mirror(&self, url: &str, reference: &str) -> Result<PathBuf> {
130        std::fs::create_dir_all(&self.mirror_root)
131            .wrap_err_with(|| format!("creating {}", self.mirror_root.display()))?;
132        let mirror = self.mirror_root.join(mirror_dir_name(url));
133        if mirror.join("HEAD").is_file() {
134            if !reference.is_empty() && !commit_present(&mirror, reference) {
135                run_git(
136                    "fetch",
137                    url,
138                    Some(&mirror),
139                    &["remote".as_ref(), "update".as_ref(), "--prune".as_ref()],
140                )?;
141            }
142        } else {
143            let _ = std::fs::remove_dir_all(&mirror);
144            run_git(
145                "clone",
146                url,
147                None,
148                &[
149                    "clone".as_ref(),
150                    "--mirror".as_ref(),
151                    "--quiet".as_ref(),
152                    url.as_ref(),
153                    mirror.as_os_str(),
154                ],
155            )?;
156        }
157        Ok(mirror)
158    }
159}
160
161impl SourceFetcher for GitSourceFetcher {
162    fn install(&self, spec: &SourceSpec<'_>) -> Result<()> {
163        self.ensure_git()?;
164        let mut last_err = None;
165        for url in spec.urls {
166            match self.install_from(url, spec.reference, spec.dest) {
167                Ok(()) => return Ok(()),
168                Err(e) => last_err = Some(e),
169            }
170        }
171        Err(last_err.unwrap_or_else(|| eyre!("no clone URL")))
172    }
173}
174
175/// Install every source package in parallel. Returns how many were installed
176/// (all of them; any failure aborts).
177pub(crate) fn materialize_sources(
178    fetcher: &dyn SourceFetcher,
179    specs: &[SourceSpec<'_>],
180) -> Result<usize> {
181    use rayon::prelude::*;
182    specs.par_iter().try_for_each(|spec| {
183        if spec.urls.is_empty() {
184            return Err(eyre!(
185                "package `{}` has a git source but no clone URL",
186                spec.package_name
187            ));
188        }
189        fetcher
190            .install(spec)
191            .wrap_err_with(|| format!("installing `{}` from git source", spec.package_name))
192    })?;
193    Ok(specs.len())
194}
195
196/// `true` when `reference` resolves to a commit in the mirror.
197fn commit_present(mirror: &Path, reference: &str) -> bool {
198    run_git(
199        "cat-file",
200        "",
201        Some(mirror),
202        &[
203            "cat-file".as_ref(),
204            "-e".as_ref(),
205            format!("{reference}^{{commit}}").as_ref(),
206        ],
207    )
208    .is_ok()
209}
210
211/// A filesystem-safe directory name for a repository URL: the sanitized tail
212/// of the URL plus a hash, so two URLs that sanitize alike never share a
213/// mirror.
214fn mirror_dir_name(url: &str) -> String {
215    let sanitized: String = url
216        .chars()
217        .map(|c| {
218            if c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-') {
219                c
220            } else {
221                '-'
222            }
223        })
224        .collect();
225    let skip = sanitized.chars().count().saturating_sub(60);
226    let tail: String = sanitized.chars().skip(skip).collect();
227    let digest = sha1::Sha1::digest(url.as_bytes());
228    let mut short = String::with_capacity(16);
229    for b in &digest[..8] {
230        use std::fmt::Write as _;
231        let _ = write!(short, "{b:02x}");
232    }
233    format!("{tail}-{short}")
234}
235
236/// Run `git [-C cwd] <args...>`: a spawn failure means git is missing, and a
237/// non-zero exit is classified from its stderr.
238fn run_git(
239    operation: &str,
240    url: &str,
241    cwd: Option<&Path>,
242    args: &[&std::ffi::OsStr],
243) -> Result<()> {
244    let mut cmd = Command::new("git");
245    if let Some(dir) = cwd {
246        cmd.arg("-C").arg(dir);
247    }
248    cmd.args(args);
249    let out = cmd.output().map_err(|_| git_missing(operation))?;
250    if out.status.success() {
251        Ok(())
252    } else {
253        Err(classify_git(
254            operation,
255            url,
256            &String::from_utf8_lossy(&out.stderr),
257        ))
258    }
259}
260
261fn git_missing(operation: &str) -> eyre::Report {
262    InstallError::Vcs {
263        failure: VcsFailure::GitMissing,
264        operation: operation.to_owned(),
265        url: String::new(),
266        detail: "`git` could not be run".to_owned(),
267    }
268    .into()
269}
270
271/// Classify a failed git command from its stderr.
272fn classify_git(operation: &str, url: &str, stderr: &str) -> eyre::Report {
273    let s = stderr.to_ascii_lowercase();
274    let failure = if [
275        "authentication failed",
276        "could not read username",
277        "could not read password",
278        "permission denied",
279        "access denied",
280        "403",
281        "terminal prompts disabled",
282    ]
283    .iter()
284    .any(|m| s.contains(m))
285    {
286        VcsFailure::Auth
287    } else if [
288        "couldn't find remote ref",
289        "did not match any",
290        "reference is not a tree",
291        "unable to read tree",
292        "not a valid object name",
293        "bad object",
294        "pathspec",
295    ]
296    .iter()
297    .any(|m| s.contains(m))
298    {
299        VcsFailure::MissingRef
300    } else if [
301        "repository not found",
302        "could not read from remote repository",
303        "not found",
304    ]
305    .iter()
306    .any(|m| s.contains(m))
307    {
308        VcsFailure::Unreachable
309    } else {
310        VcsFailure::Other
311    };
312    InstallError::Vcs {
313        failure,
314        operation: operation.to_owned(),
315        url: url.to_owned(),
316        detail: stderr.trim().to_owned(),
317    }
318    .into()
319}
320
321#[cfg(test)]
322pub(crate) mod tests;