devset_core/
source.rs

1//! Where a layer's profile comes from: a local directory, or a git repository at one commit.
2
3use alloc::borrow::Cow;
4use alloc::sync::Arc;
5use core::fmt;
6use std::collections::HashMap;
7use std::io::{self, Read};
8use std::sync::Mutex;
9
10use camino::{Utf8Component, Utf8Path, Utf8PathBuf};
11use derive_more::{Display, Into};
12use etcetera::BaseStrategy;
13use schemars::{JsonSchema, Schema, SchemaGenerator};
14use serde::{Deserialize, Serialize};
15use walkdir::WalkDir;
16
17use crate::errors::{Result, SourceError};
18use crate::git;
19use crate::path::RelPath;
20use crate::profile::MANIFEST;
21use crate::tree::Tree;
22
23/// Where a layer's profile comes from; written as [`SourceSpec`].
24#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
25#[serde(try_from = "SourceSpec", into = "SourceSpec")]
26pub enum Source {
27    /// A directory, relative to the target root unless absolute.
28    Dir(Utf8PathBuf),
29    /// A git repository.
30    Git {
31        /// Anything `git fetch` accepts.
32        url: String,
33        /// Which commit.
34        at: GitRef,
35        /// The profile's directory in the repository; its root if `None`.
36        path: Option<RelPath>,
37    },
38}
39
40/// Which commit of a git source.
41#[derive(Clone, Debug, PartialEq, Eq)]
42pub enum GitRef {
43    /// The remote's default branch.
44    Head,
45    /// A branch.
46    Branch(String),
47    /// A tag.
48    Tag(String),
49    /// A commit.
50    Rev(Oid),
51}
52
53/// A full commit id: 40 or 64 hex digits, lowercase.
54#[derive(Clone, PartialEq, Eq, Display, derive_more::Debug, Into, Serialize, Deserialize)]
55#[debug("{_0}")]
56#[into(String)]
57#[serde(try_from = "String", into = "String")]
58pub struct Oid(Box<str>);
59
60/// A source as written in `config.toml`: Cargo's git-dependency fields.
61#[derive(Debug, Default, Serialize, Deserialize, JsonSchema)]
62#[serde(deny_unknown_fields)]
63pub struct SourceSpec {
64    /// Repository URL.
65    #[serde(default, skip_serializing_if = "Option::is_none")]
66    pub git: Option<String>,
67    /// Tag to use; only with `git`.
68    #[serde(default, skip_serializing_if = "Option::is_none")]
69    pub tag: Option<String>,
70    /// Branch to use; only with `git`.
71    #[serde(default, skip_serializing_if = "Option::is_none")]
72    pub branch: Option<String>,
73    /// Full commit id to use; only with `git`.
74    #[serde(default, skip_serializing_if = "Option::is_none")]
75    pub rev: Option<String>,
76    /// The profile's directory: relative to the target, or within the repository with `git`.
77    #[serde(default, skip_serializing_if = "Option::is_none")]
78    pub path: Option<String>,
79}
80
81impl TryFrom<SourceSpec> for Source {
82    type Error = SourceError;
83
84    fn try_from(spec: SourceSpec) -> Result<Self, SourceError> {
85        let SourceSpec { git, tag, branch, rev, path } = spec;
86        let Some(url) = git else {
87            if tag.is_some() || branch.is_some() || rev.is_some() {
88                return Err(SourceError::RefWithoutGit);
89            }
90            let path = path.ok_or(SourceError::NoLocation)?;
91            return dir(&path).map(Self::Dir).ok_or(SourceError::EmptyPath);
92        };
93        // A leading `-` would reach git as an option.
94        if url.is_empty() || url.starts_with('-') {
95            return Err(SourceError::Url { url });
96        }
97        let at = match (tag, branch, rev) {
98            (None, None, None) => GitRef::Head,
99            (Some(tag), None, None) => GitRef::Tag(tag),
100            (None, Some(branch), None) => GitRef::Branch(branch),
101            (None, None, Some(rev)) => GitRef::Rev(Oid::try_from(rev)?),
102            _ => return Err(SourceError::TwoRefs),
103        };
104        let path = path.filter(|p| !p.is_empty()).map(RelPath::try_from).transpose()?;
105        Ok(Self::Git { url, at, path })
106    }
107}
108
109/// `path` without `.` components, so one directory has one spelling; `None` when empty.
110fn dir(path: &str) -> Option<Utf8PathBuf> {
111    if path.is_empty() {
112        return None;
113    }
114    let dir: Utf8PathBuf =
115        Utf8Path::new(path).components().filter(|c| *c != Utf8Component::CurDir).collect();
116    Some(if dir.as_str().is_empty() { Utf8PathBuf::from(".") } else { dir })
117}
118
119impl From<Source> for SourceSpec {
120    fn from(source: Source) -> Self {
121        match source {
122            Source::Dir(path) => Self { path: Some(path.into_string()), ..Self::default() },
123            Source::Git { url, at, path } => {
124                let mut spec =
125                    Self { git: Some(url), path: path.map(String::from), ..Self::default() };
126                match at {
127                    GitRef::Head => {},
128                    GitRef::Branch(branch) => spec.branch = Some(branch),
129                    GitRef::Tag(tag) => spec.tag = Some(tag),
130                    GitRef::Rev(rev) => spec.rev = Some(rev.into()),
131                }
132                spec
133            },
134        }
135    }
136}
137
138impl JsonSchema for Source {
139    fn schema_name() -> Cow<'static, str> {
140        SourceSpec::schema_name()
141    }
142
143    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
144        SourceSpec::json_schema(generator)
145    }
146}
147
148impl Source {
149    /// Whether `other` is this profile at another ref: one repository and path, two refs.
150    pub(crate) fn twin(&self, other: &Self) -> bool {
151        match (self, other) {
152            (
153                Self::Git { url, at, path },
154                Self::Git { url: other_url, at: other_at, path: other_path },
155            ) => url == other_url && path == other_path && at != other_at,
156            (Self::Dir(_) | Self::Git { .. }, Self::Dir(_) | Self::Git { .. }) => false,
157        }
158    }
159}
160
161impl fmt::Display for Source {
162    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
163        match self {
164            Self::Dir(path) => f.write_str(path.as_str()),
165            Self::Git { url, at, path } => {
166                f.write_str(url)?;
167                match at {
168                    GitRef::Head => {},
169                    GitRef::Branch(branch) => write!(f, " branch {branch}")?,
170                    GitRef::Tag(tag) => write!(f, " tag {tag}")?,
171                    GitRef::Rev(rev) => write!(f, " rev {rev}")?,
172                }
173                path.as_ref().map_or(Ok(()), |path| write!(f, " path {path}"))
174            },
175        }
176    }
177}
178
179impl Oid {
180    /// The id as hex.
181    #[must_use]
182    pub fn as_str(&self) -> &str {
183        &self.0
184    }
185
186    /// Its first seven digits, as git abbreviates it.
187    #[must_use]
188    pub fn short(&self) -> &str {
189        self.0.get(..7).unwrap_or(&self.0)
190    }
191}
192
193impl TryFrom<String> for Oid {
194    type Error = SourceError;
195
196    fn try_from(mut id: String) -> Result<Self, SourceError> {
197        if !matches!(id.len(), 40 | 64) || !id.bytes().all(|b| b.is_ascii_hexdigit()) {
198            return Err(SourceError::Rev { rev: id });
199        }
200        id.make_ascii_lowercase();
201        Ok(Self(id.into_boxed_str()))
202    }
203}
204
205/// Remote access for a git layer, reported through [`Cache::on_fetch`].
206#[derive(Clone, Copy, Debug)]
207pub enum Fetch<'a> {
208    /// About to contact this URL.
209    Start(&'a str),
210    /// Finished with it.
211    Done(&'a str),
212}
213
214/// What [`Cache::on_fetch`] installs.
215type Hook = Arc<dyn Fn(Fetch<'_>) + Send + Sync>;
216
217/// Fetched git profiles, shared by every target on the machine.
218///
219/// One process sees one commit per ref: each ref is asked of its remote once.
220#[derive(Clone, derive_more::Debug)]
221pub struct Cache {
222    /// Where it lives.
223    dir: Utf8PathBuf,
224    /// Told about remote access.
225    #[debug(skip)]
226    hook: Option<Hook>,
227    /// Refs resolved so far, by URL and ref name, so one process sees one commit per ref.
228    #[debug(skip)]
229    refs: Arc<Mutex<HashMap<(String, String), Oid>>>,
230    /// Whether git may ask for credentials on the terminal.
231    prompts: bool,
232}
233
234impl Cache {
235    /// The per-user cache: `$XDG_CACHE_HOME/devset`, or the platform's equivalent.
236    ///
237    /// # Errors
238    /// [`Error::Io`](crate::Error::Io), there is no home directory, or its path is not UTF-8.
239    pub fn user() -> Result<Self> {
240        let base = etcetera::choose_base_strategy().map_err(io::Error::other)?;
241        let dir = Utf8PathBuf::try_from(base.cache_dir()).map_err(io::Error::other)?;
242        Ok(Self::at(dir.join("devset")))
243    }
244
245    /// A cache in `dir`.
246    #[must_use]
247    pub fn at(dir: Utf8PathBuf) -> Self {
248        Self { dir, hook: None, refs: Arc::new(Mutex::new(HashMap::new())), prompts: false }
249    }
250
251    /// This cache, calling `hook` around every remote access so a caller can show progress.
252    #[must_use]
253    pub fn on_fetch<F: Fn(Fetch<'_>) + Send + Sync + 'static>(mut self, hook: F) -> Self {
254        self.hook = Some(Arc::new(hook));
255        self
256    }
257
258    /// This cache, letting git ask for credentials on the terminal when `allowed`.
259    ///
260    /// Off unless asked for, so a run with no one to answer fails rather than waits.
261    #[must_use]
262    pub const fn prompting(mut self, allowed: bool) -> Self {
263        self.prompts = allowed;
264        self
265    }
266
267    /// Whether git may ask for credentials on the terminal.
268    pub(crate) const fn prompts(&self) -> bool {
269        self.prompts
270    }
271
272    /// Where the cache lives.
273    #[must_use]
274    pub fn path(&self) -> &Utf8Path {
275        &self.dir
276    }
277
278    /// The commit `name` at `url` was resolved to earlier in this process.
279    pub(crate) fn resolved(&self, url: &str, name: &str) -> Option<Oid> {
280        let refs = self.refs.lock().ok()?;
281        refs.get(&(url.to_owned(), name.to_owned())).cloned()
282    }
283
284    /// Remembers that `name` at `url` is `rev`.
285    pub(crate) fn remember(&self, url: &str, name: &str, rev: &Oid) {
286        if let Ok(mut refs) = self.refs.lock() {
287            refs.insert((url.to_owned(), name.to_owned()), rev.clone());
288        }
289    }
290
291    /// Reports `event` to the hook, if any.
292    pub(crate) fn notify(&self, event: Fetch<'_>) {
293        if let Some(hook) = &self.hook {
294            hook(event);
295        }
296    }
297}
298
299/// A source opened at one revision.
300#[derive(Debug)]
301pub(crate) enum Reader {
302    /// A local directory.
303    Dir(Utf8PathBuf),
304    /// A commit in the cache.
305    Git(git::Commit),
306}
307
308impl Source {
309    /// Opens the source: a git source at `pin` if given, else at its ref, fetching as needed.
310    pub(crate) fn open(&self, root: &Utf8Path, pin: Option<&Oid>, cache: &Cache) -> Result<Reader> {
311        match self {
312            Self::Dir(dir) => Ok(Reader::Dir(root.join(dir))),
313            Self::Git { url, at, path } => {
314                git::Commit::open(&locate(url, root), url, at, path.as_ref(), pin, cache)
315                    .map(Reader::Git)
316            },
317        }
318    }
319}
320
321/// `url` as `git` sees it from any directory: a local path is made absolute against `root`.
322///
323/// Git's rule: `host:path` is scp-like only when the colon precedes any slash.
324fn locate<'a>(url: &'a str, root: &Utf8Path) -> Cow<'a, str> {
325    let remote = url.contains("://")
326        || url.find(':').is_some_and(|colon| url.find('/').is_none_or(|slash| colon < slash));
327    if remote { Cow::Borrowed(url) } else { Cow::Owned(root.join(url).into_string()) }
328}
329
330impl Reader {
331    /// The commit, for a versioned source.
332    pub(crate) const fn rev(&self) -> Option<&Oid> {
333        match self {
334            Self::Dir(_) => None,
335            Self::Git(commit) => Some(commit.rev()),
336        }
337    }
338
339    /// Every directory the source holds that is a profile, as its `path` would name it.
340    pub(crate) fn profiles(&self, configured: &Source) -> Vec<String> {
341        match (self, configured) {
342            (Self::Git(commit), _) => commit.profiles(),
343            (Self::Dir(root), Source::Dir(written)) => local_profiles(root, written),
344            (Self::Dir(_), Source::Git { .. }) => Vec::new(),
345        }
346    }
347
348    /// The files at `paths` under `dir` in the profile, keyed by `paths`; absent ones left out.
349    pub(crate) fn read(&self, dir: &str, paths: &[RelPath]) -> Result<Tree> {
350        match self {
351            Self::Dir(root) => read_dir(&root.join(dir), paths),
352            Self::Git(commit) => commit.read(dir, paths),
353        }
354    }
355}
356
357/// The profiles around `root`, as `path` would name them.
358///
359/// The two directories above it, for a path pointing inside a profile, and two levels below,
360/// hidden ones left out.
361fn local_profiles(root: &Utf8Path, written: &Utf8Path) -> Vec<String> {
362    let above = root
363        .ancestors()
364        .zip(written.ancestors())
365        .skip(1)
366        .take(2)
367        .filter(|(dir, name)| !name.as_str().is_empty() && dir.join(MANIFEST).is_file())
368        .map(|(_, name)| name.to_string());
369    let below = WalkDir::new(root)
370        .min_depth(1)
371        .max_depth(2)
372        .follow_links(true)
373        .into_iter()
374        .filter_entry(|entry| {
375            entry.file_type().is_dir() && !entry.file_name().as_encoded_bytes().starts_with(b".")
376        })
377        .filter_map(Result::ok)
378        .filter(|entry| entry.path().join(MANIFEST).is_file())
379        .filter_map(|entry| {
380            let inside = Utf8Path::from_path(entry.path().strip_prefix(root).ok()?)?;
381            Some(written.join(inside).into_string())
382        });
383    let mut found: Vec<String> = above.chain(below).collect();
384    found.sort();
385    found
386}
387
388/// [`Reader::read`] for a local directory.
389fn read_dir(dir: &Utf8Path, paths: &[RelPath]) -> Result<Tree> {
390    let mut tree = Tree::default();
391    for path in paths {
392        let file = path.under(dir);
393        match fs_err::symlink_metadata(&file) {
394            Ok(meta) if meta.is_file() => {
395                tree.insert(path.clone(), |buf| {
396                    fs_err::File::open(&file)?.read_to_end(buf)?;
397                    Ok(())
398                })?;
399            },
400            Ok(_) => {
401                return Err(SourceError::NotAFile { file: file.into_string() }.into());
402            },
403            Err(e) if e.kind() == io::ErrorKind::NotFound => {},
404            Err(e) => return Err(e.into()),
405        }
406    }
407    Ok(tree)
408}
409
410#[cfg(test)]
411mod tests {
412    use super::{GitRef, Source, SourceSpec};
413
414    fn parse(toml: &str) -> Result<Source, String> {
415        toml::from_str::<SourceSpec>(toml)
416            .map_err(|e| e.to_string())
417            .and_then(|spec| Source::try_from(spec).map_err(|e| e.to_string()))
418    }
419
420    #[test]
421    fn valid() {
422        assert_eq!(parse(r#"path = "../p""#), Ok(Source::Dir("../p".into())), "local directory");
423        for (written, dir) in [("./../p/", "../p"), ("./p", "p"), (".", "."), ("./", ".")] {
424            let toml = format!("path = \"{written}\"");
425            assert_eq!(parse(&toml), Ok(Source::Dir(dir.into())), "{written:?} has one spelling");
426        }
427        let Ok(Source::Git { url, at, path }) = parse(
428            r#"git = "https://h/r"
429tag = "v1"
430path = "rust""#,
431        ) else {
432            panic!("git source should parse");
433        };
434        assert_eq!(
435            (url.as_str(), at, path.map(String::from)),
436            ("https://h/r", GitRef::Tag("v1".into()), Some("rust".into())),
437            "fields"
438        );
439        let rev = "A".repeat(40);
440        let Ok(Source::Git { at: GitRef::Rev(oid), .. }) =
441            parse(&format!("git = \"u\"\nrev = \"{rev}\""))
442        else {
443            panic!("rev should parse");
444        };
445        assert_eq!(oid.as_str(), "a".repeat(40), "commit ids are lowercased");
446    }
447
448    #[test]
449    fn invalid() {
450        for toml in [
451            "",
452            r#"path = """#,
453            r#"tag = "v1""#,
454            r#"path = "p"
455branch = "b""#,
456            r#"git = "u"
457tag = "v1"
458branch = "b""#,
459            r#"git = "u"
460rev = "abc""#,
461            r#"git = "--upload-pack=x""#,
462            r#"git = "u"
463path = "../x""#,
464            r#"git = "u"
465bogus = 1"#,
466        ] {
467            assert!(parse(toml).is_err(), "should be rejected: {toml:?}");
468        }
469    }
470
471    #[test]
472    fn local_git_paths_are_anchored() {
473        let root = camino::Utf8Path::new("/work/repo");
474        for (url, want) in [
475            ("../p.git", "/work/repo/../p.git"),
476            ("/abs/p.git", "/abs/p.git"),
477            ("https://h/p", "https://h/p"),
478            ("file:///p", "file:///p"),
479            ("git@h:org/p", "git@h:org/p"),
480            ("./a:b", "/work/repo/./a:b"),
481        ] {
482            assert_eq!(super::locate(url, root), want, "{url}");
483        }
484    }
485
486    #[test]
487    fn round_trips() {
488        let toml = "git = \"https://h/r\"\nbranch = \"main\"\npath = \"a/b\"\n";
489        let source = parse(toml).unwrap();
490        assert_eq!(toml::to_string(&source).unwrap(), toml, "serialized as written");
491    }
492}
devset_core/source.rs

devset_core/
source.rs
