gix_validate/
reference.rs

1use bstr::{BStr, BString, ByteSlice};
2
3///
4pub mod name {
5    use bstr::BString;
6    use std::convert::Infallible;
7
8    /// The error used in [name()][super::name()] and [`name_partial()`][super::name_partial()]
9    #[derive(Debug)]
10    #[allow(missing_docs)]
11    #[non_exhaustive]
12    pub enum Error {
13        InvalidByte { byte: BString },
14        StartsWithSlash,
15        RepeatedSlash,
16        RepeatedDot,
17        LockFileSuffix,
18        ReflogPortion,
19        Asterisk,
20        StartsWithDot,
21        EndsWithDot,
22        EndsWithSlash,
23        Empty,
24        SomeLowercase,
25        Reserved { name: BString },
26    }
27
28    impl std::fmt::Display for Error {
29        fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
30            match self {
31                Error::InvalidByte { byte } => write!(f, "Reference name contains invalid byte: {byte:?}"),
32                Error::StartsWithSlash => write!(f, "Reference name cannot start with a slash"),
33                Error::RepeatedSlash => write!(f, "Reference name cannot contain repeated slashes"),
34                Error::RepeatedDot => write!(f, "Reference name cannot contain repeated dots"),
35                Error::LockFileSuffix => write!(f, "Reference name cannot end with '.lock'"),
36                Error::ReflogPortion => write!(f, "Reference name cannot contain '@{{'"),
37                Error::Asterisk => write!(f, "Reference name cannot contain '*'"),
38                Error::StartsWithDot => write!(f, "Reference name cannot start with a dot"),
39                Error::EndsWithDot => write!(f, "Reference name cannot end with a dot"),
40                Error::EndsWithSlash => write!(f, "Reference name cannot end with a slash"),
41                Error::Empty => write!(f, "Reference name cannot be empty"),
42                Error::SomeLowercase => write!(f, "Standalone references must be all uppercased, like 'HEAD'"),
43                Error::Reserved { name } => write!(f, "Reference name is reserved and cannot be used: {name:?}"),
44            }
45        }
46    }
47
48    impl std::error::Error for Error {}
49
50    impl From<crate::tag::name::Error> for Error {
51        fn from(err: crate::tag::name::Error) -> Self {
52            match err {
53                crate::tag::name::Error::InvalidByte { byte } => Error::InvalidByte { byte },
54                crate::tag::name::Error::StartsWithSlash => Error::StartsWithSlash,
55                crate::tag::name::Error::RepeatedSlash => Error::RepeatedSlash,
56                crate::tag::name::Error::RepeatedDot => Error::RepeatedDot,
57                crate::tag::name::Error::LockFileSuffix => Error::LockFileSuffix,
58                crate::tag::name::Error::ReflogPortion => Error::ReflogPortion,
59                crate::tag::name::Error::Asterisk => Error::Asterisk,
60                crate::tag::name::Error::StartsWithDot => Error::StartsWithDot,
61                crate::tag::name::Error::EndsWithDot => Error::EndsWithDot,
62                crate::tag::name::Error::EndsWithSlash => Error::EndsWithSlash,
63                crate::tag::name::Error::Empty => Error::Empty,
64            }
65        }
66    }
67
68    impl From<Infallible> for Error {
69        fn from(_: Infallible) -> Self {
70            unreachable!("this impl is needed to allow passing a known valid partial path as parameter")
71        }
72    }
73}
74
75/// Validate a reference name running all the tests in the book. This disallows lower-case references like `lower`, but also allows
76/// ones like `HEAD`, and `refs/lower`.
77pub fn name(path: &BStr) -> Result<&BStr, name::Error> {
78    match validate(path, Mode::Complete)? {
79        None => Ok(path),
80        Some(_) => {
81            unreachable!("Without sanitization, there is no chance a sanitized version is returned.")
82        }
83    }
84}
85
86/// Validate a reference name for use as a local branch.
87///
88/// This is like [`name()`], but also rejects `refs/heads/HEAD`, matching Git's branch-specific validation.
89pub fn branch_name(path: &BStr) -> Result<&BStr, name::Error> {
90    let path = name(path)?;
91    if path == "refs/heads/HEAD" {
92        return Err(name::Error::Reserved { name: path.into() });
93    }
94    Ok(path)
95}
96
97/// Validate a partial reference name. As it is assumed to be partial, names like `some-name` is allowed
98/// even though these would be disallowed with when using [`name()`].
99pub fn name_partial(path: &BStr) -> Result<&BStr, name::Error> {
100    match validate(path, Mode::Partial)? {
101        None => Ok(path),
102        Some(_) => {
103            unreachable!("Without sanitization, there is no chance a sanitized version is returned.")
104        }
105    }
106}
107
108/// The infallible version of [`name_partial()`] which instead of failing, alters `path` and returns it to be a valid
109/// partial name, which would also pass [`name_partial()`].
110///
111/// Note that an empty `path` is replaced with a `-` in order to be valid.
112pub fn name_partial_or_sanitize(path: &BStr) -> BString {
113    validate(path, Mode::PartialSanitize)
114        .expect("BUG: errors cannot happen as any issue is fixed instantly")
115        .expect("we always rebuild the path")
116}
117
118enum Mode {
119    Complete,
120    Partial,
121    /// like Partial, but instead of failing, a sanitized version is returned.
122    PartialSanitize,
123}
124
125fn validate(path: &BStr, mode: Mode) -> Result<Option<BString>, name::Error> {
126    let out = crate::tag::name_inner(
127        path,
128        match mode {
129            Mode::Complete | Mode::Partial => crate::tag::Mode::Validate,
130            Mode::PartialSanitize => crate::tag::Mode::Sanitize,
131        },
132    )?;
133    if let Mode::Complete = mode {
134        let input = out.as_ref().map_or(path, |b| b.as_bstr());
135        let saw_slash = input.find_byte(b'/').is_some();
136        if !saw_slash && !input.iter().all(|c| c.is_ascii_uppercase() || *c == b'_') {
137            return Err(name::Error::SomeLowercase);
138        }
139    }
140    Ok(out)
141}
gix_validate/reference.rs

gix_validate/
reference.rs
