git_lfs_pointer/
oid.rs

1use std::fmt;
2use std::str::FromStr;
3
4/// Hex form of the SHA-256 of the empty input. Used as the OID of the empty
5/// pointer (which represents an empty file — see `docs/spec.md`).
6pub const EMPTY_HEX: &str =
7    "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
8
9/// A SHA-256 object identifier.
10///
11/// Stored as the raw 32 bytes; rendered as 64 lowercase hex characters by
12/// [`fmt::Display`]. Construction via [`Oid::from_hex`] enforces the spec's
13/// strict-lowercase, exactly-64-hex-character format.
14#[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
15pub struct Oid([u8; 32]);
16
17impl Oid {
18    /// SHA-256 of the empty input. The OID of the [empty pointer].
19    ///
20    /// [empty pointer]: crate::Pointer::empty
21    pub const EMPTY: Oid = Oid([
22        0xe3, 0xb0, 0xc4, 0x42, 0x98, 0xfc, 0x1c, 0x14, 0x9a, 0xfb, 0xf4, 0xc8, 0x99, 0x6f, 0xb9,
23        0x24, 0x27, 0xae, 0x41, 0xe4, 0x64, 0x9b, 0x93, 0x4c, 0xa4, 0x95, 0x99, 0x1b, 0x78, 0x52,
24        0xb8, 0x55,
25    ]);
26
27    /// Construct an OID from raw 32 hash bytes (e.g. the output of a
28    /// streaming SHA-256 hasher).
29    pub const fn from_bytes(bytes: [u8; 32]) -> Self {
30        Self(bytes)
31    }
32
33    /// Parse an OID from its 64-character lowercase hex form.
34    pub fn from_hex(s: &str) -> Result<Self, OidParseError> {
35        if s.len() != 64 {
36            return Err(OidParseError::InvalidLength(s.len()));
37        }
38        let mut out = [0u8; 32];
39        let bytes = s.as_bytes();
40        for (i, byte) in out.iter_mut().enumerate() {
41            let hi = hex_digit(bytes[i * 2])?;
42            let lo = hex_digit(bytes[i * 2 + 1])?;
43            *byte = (hi << 4) | lo;
44        }
45        Ok(Oid(out))
46    }
47
48    /// Borrow the raw 32-byte hash.
49    pub fn as_bytes(&self) -> &[u8; 32] {
50        &self.0
51    }
52}
53
54fn hex_digit(b: u8) -> Result<u8, OidParseError> {
55    match b {
56        b'0'..=b'9' => Ok(b - b'0'),
57        b'a'..=b'f' => Ok(b - b'a' + 10),
58        // Uppercase A-F is rejected on purpose: the spec mandates lowercase.
59        _ => Err(OidParseError::InvalidCharacter(b as char)),
60    }
61}
62
63impl fmt::Display for Oid {
64    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
65        for byte in &self.0 {
66            write!(f, "{byte:02x}")?;
67        }
68        Ok(())
69    }
70}
71
72impl fmt::Debug for Oid {
73    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
74        write!(f, "Oid({self})")
75    }
76}
77
78impl FromStr for Oid {
79    type Err = OidParseError;
80    fn from_str(s: &str) -> Result<Self, Self::Err> {
81        Oid::from_hex(s)
82    }
83}
84
85#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
86pub enum OidParseError {
87    #[error("oid must be 64 hex characters, got {0}")]
88    InvalidLength(usize),
89    #[error("oid contains invalid character {0:?} (must be lowercase 0-9a-f)")]
90    InvalidCharacter(char),
91}
92
93#[cfg(test)]
94mod tests {
95    use super::*;
96
97    #[test]
98    fn empty_const_matches_empty_hex() {
99        assert_eq!(Oid::EMPTY, Oid::from_hex(EMPTY_HEX).unwrap());
100        assert_eq!(Oid::EMPTY.to_string(), EMPTY_HEX);
101    }
102
103    #[test]
104    fn round_trip_hex() {
105        let hex = "4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393";
106        let oid = Oid::from_hex(hex).unwrap();
107        assert_eq!(oid.to_string(), hex);
108    }
109
110    #[test]
111    fn rejects_wrong_length() {
112        assert_eq!(Oid::from_hex(""), Err(OidParseError::InvalidLength(0)));
113        assert_eq!(Oid::from_hex("abc"), Err(OidParseError::InvalidLength(3)));
114        assert_eq!(
115            Oid::from_hex(&"a".repeat(63)),
116            Err(OidParseError::InvalidLength(63))
117        );
118        assert_eq!(
119            Oid::from_hex(&"a".repeat(65)),
120            Err(OidParseError::InvalidLength(65))
121        );
122    }
123
124    #[test]
125    fn rejects_uppercase() {
126        // Spec mandates lowercase; uppercase A-F is not accepted.
127        let upper = "4D7A214614AB2935C943F9E0FF69D22EADBB8F32B1258DAAA5E2CA24D17E2393";
128        assert_eq!(
129            Oid::from_hex(upper),
130            Err(OidParseError::InvalidCharacter('D'))
131        );
132    }
133
134    #[test]
135    fn rejects_non_hex() {
136        let mut bad = "a".repeat(63);
137        bad.push('z');
138        assert_eq!(Oid::from_hex(&bad), Err(OidParseError::InvalidCharacter('z')));
139
140        let trailing_amp =
141            "4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393&"; // 65 chars
142        assert_eq!(
143            Oid::from_hex(trailing_amp),
144            Err(OidParseError::InvalidLength(65))
145        );
146    }
147
148    #[test]
149    fn from_str_works() {
150        let hex = "4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393";
151        let oid: Oid = hex.parse().unwrap();
152        assert_eq!(oid.to_string(), hex);
153    }
154}
git_lfs_pointer/oid.rs

git_lfs_pointer/
oid.rs
