khive_types/
id.rs

1//! 128-bit identifier — wire format is canonical hyphenated UUID, nil sentinel at all-zeros.
2
3// REASON: `manual_range_contains` fires on the `b'0'..=b'9'` byte-range matches
4// in `hex_val`. The range-contains form (`c >= b'0' && c <= b'9'`) is less
5// readable for byte-literal matching and offers no correctness benefit here.
6#![allow(clippy::manual_range_contains)]
7
8use core::fmt;
9use core::str::FromStr;
10
11/// A 128-bit opaque identifier stored as 16 bytes, formatted as a hyphenated UUID string.
12#[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
13pub struct Id128([u8; 16]);
14
15impl Id128 {
16    /// The all-zeros nil identifier, used as a sentinel for "no record".
17    pub const NIL: Self = Self([0; 16]);
18
19    /// Construct an `Id128` from its raw 16-byte representation.
20    #[inline]
21    pub const fn from_bytes(bytes: [u8; 16]) -> Self {
22        Self(bytes)
23    }
24
25    /// Return a reference to the underlying 16-byte array.
26    #[inline]
27    pub const fn as_bytes(&self) -> &[u8; 16] {
28        &self.0
29    }
30
31    /// Return `true` if all 16 bytes are zero (the nil sentinel).
32    #[inline]
33    pub const fn is_nil(&self) -> bool {
34        let b = &self.0;
35        let mut i = 0;
36        while i < 16 {
37            if b[i] != 0 {
38                return false;
39            }
40            i += 1;
41        }
42        true
43    }
44
45    /// Construct an `Id128` from a `u128` in big-endian byte order.
46    #[inline]
47    pub const fn from_u128(v: u128) -> Self {
48        Self(v.to_be_bytes())
49    }
50
51    /// Convert the identifier back to its `u128` big-endian representation.
52    #[inline]
53    pub const fn to_u128(&self) -> u128 {
54        u128::from_be_bytes(self.0)
55    }
56}
57
58const HEX_CHARS: &[u8; 16] = b"0123456789abcdef";
59
60impl fmt::Display for Id128 {
61    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
62        let b = &self.0;
63        let mut buf = [0u8; 36];
64        let mut pos = 0;
65
66        // Groups: 4 bytes, 2 bytes, 2 bytes, 2 bytes, 6 bytes
67        let groups: &[(usize, usize)] = &[(0, 4), (4, 6), (6, 8), (8, 10), (10, 16)];
68        for (gi, &(start, end)) in groups.iter().enumerate() {
69            if gi > 0 {
70                buf[pos] = b'-';
71                pos += 1;
72            }
73            for i in start..end {
74                buf[pos] = HEX_CHARS[(b[i] >> 4) as usize];
75                buf[pos + 1] = HEX_CHARS[(b[i] & 0x0f) as usize];
76                pos += 2;
77            }
78        }
79        f.write_str(core::str::from_utf8(&buf[..pos]).expect("hex chars are valid utf8"))
80    }
81}
82
83impl fmt::Debug for Id128 {
84    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
85        write!(f, "Id128({self})")
86    }
87}
88
89/// Error returned when an `Id128` string cannot be parsed.
90#[derive(Clone, Copy, Debug, PartialEq, Eq)]
91pub enum ParseIdError {
92    /// The input was not 32 hex chars or 36 chars with hyphens.
93    InvalidLength,
94    /// The input contained a character that is not a valid hex digit.
95    InvalidHex,
96}
97
98impl fmt::Display for ParseIdError {
99    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
100        match self {
101            Self::InvalidLength => f.write_str("expected UUID: 32 hex chars or 36 with hyphens"),
102            Self::InvalidHex => f.write_str("invalid hex character in UUID"),
103        }
104    }
105}
106
107#[cfg(feature = "std")]
108impl std::error::Error for ParseIdError {}
109
110fn hex_val(c: u8) -> Option<u8> {
111    match c {
112        b'0'..=b'9' => Some(c - b'0'),
113        b'a'..=b'f' => Some(c - b'a' + 10),
114        b'A'..=b'F' => Some(c - b'A' + 10),
115        _ => None,
116    }
117}
118
119fn parse_hex_bytes(hex: &[u8]) -> Result<[u8; 16], ParseIdError> {
120    if hex.len() != 32 {
121        return Err(ParseIdError::InvalidLength);
122    }
123    let mut bytes = [0u8; 16];
124    for i in 0..16 {
125        let hi = hex_val(hex[i * 2]).ok_or(ParseIdError::InvalidHex)?;
126        let lo = hex_val(hex[i * 2 + 1]).ok_or(ParseIdError::InvalidHex)?;
127        bytes[i] = (hi << 4) | lo;
128    }
129    Ok(bytes)
130}
131
132impl FromStr for Id128 {
133    type Err = ParseIdError;
134
135    fn from_str(s: &str) -> Result<Self, Self::Err> {
136        let b = s.as_bytes();
137        match b.len() {
138            32 => Ok(Self(parse_hex_bytes(b)?)),
139            36 => {
140                // Strip hyphens at positions 8, 13, 18, 23
141                if b[8] != b'-' || b[13] != b'-' || b[18] != b'-' || b[23] != b'-' {
142                    return Err(ParseIdError::InvalidHex);
143                }
144                let mut hex = [0u8; 32];
145                hex[..8].copy_from_slice(&b[..8]);
146                hex[8..12].copy_from_slice(&b[9..13]);
147                hex[12..16].copy_from_slice(&b[14..18]);
148                hex[16..20].copy_from_slice(&b[19..23]);
149                hex[20..32].copy_from_slice(&b[24..36]);
150                Ok(Self(parse_hex_bytes(&hex)?))
151            }
152            _ => Err(ParseIdError::InvalidLength),
153        }
154    }
155}
156
157impl Default for Id128 {
158    #[inline]
159    fn default() -> Self {
160        Self::NIL
161    }
162}
163
164#[cfg(feature = "serde")]
165impl serde::Serialize for Id128 {
166    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
167        use alloc::string::ToString;
168        serializer.serialize_str(&self.to_string())
169    }
170}
171
172#[cfg(feature = "serde")]
173impl<'de> serde::Deserialize<'de> for Id128 {
174    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
175        // Deserialize into owned String so this works when the deserializer
176        // holds owned data (e.g. serde_json::Value) and cannot lend a &str.
177        let s = alloc::string::String::deserialize(deserializer)?;
178        s.parse().map_err(serde::de::Error::custom)
179    }
180}
181
182#[cfg(test)]
183mod tests {
184    use super::*;
185    use alloc::format;
186
187    #[test]
188    fn nil() {
189        assert!(Id128::NIL.is_nil());
190        assert!(!Id128::from_u128(1).is_nil());
191    }
192
193    #[test]
194    fn roundtrip_u128() {
195        let v: u128 = 0xdeadbeef_12345678_9abcdef0_11223344;
196        let id = Id128::from_u128(v);
197        assert_eq!(id.to_u128(), v);
198    }
199
200    #[test]
201    fn display_is_hyphenated_uuid() {
202        let id = Id128::from_u128(0xabcdef0123456789abcdef0123456789);
203        let s = format!("{id}");
204        assert_eq!(s.len(), 36);
205        assert_eq!(s, "abcdef01-2345-6789-abcd-ef0123456789");
206    }
207
208    #[test]
209    fn parse_hyphenated() {
210        let id: Id128 = "abcdef01-2345-6789-abcd-ef0123456789".parse().unwrap();
211        assert_eq!(id.to_u128(), 0xabcdef0123456789abcdef0123456789);
212    }
213
214    #[test]
215    fn parse_simple() {
216        let id: Id128 = "abcdef0123456789abcdef0123456789".parse().unwrap();
217        assert_eq!(id.to_u128(), 0xabcdef0123456789abcdef0123456789);
218    }
219
220    #[test]
221    fn display_parse_roundtrip() {
222        let id = Id128::from_u128(0xabcdef0123456789abcdef0123456789);
223        let s = format!("{id}");
224        let parsed: Id128 = s.parse().unwrap();
225        assert_eq!(parsed, id);
226    }
227
228    #[test]
229    fn parse_errors() {
230        assert_eq!("abc".parse::<Id128>(), Err(ParseIdError::InvalidLength));
231        assert_eq!(
232            "zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz".parse::<Id128>(),
233            Err(ParseIdError::InvalidHex)
234        );
235        // Wrong hyphen positions
236        assert_eq!(
237            "abcdef01-2345-6789-abcd-ef012345678".parse::<Id128>(),
238            Err(ParseIdError::InvalidLength)
239        );
240    }
241
242    #[test]
243    fn ordering() {
244        let a = Id128::from_u128(1);
245        let b = Id128::from_u128(2);
246        assert!(a < b);
247    }
248
249    /// C1 regression: Id128 must deserialize from an owned serde_json::Value string,
250    /// not only from a borrowed &str.  Previously used `<&str>::deserialize` which
251    /// fails when the deserializer holds owned data (e.g. Value-backed deserializer).
252    #[cfg(feature = "serde")]
253    #[test]
254    fn deserialize_from_owned_value() {
255        use alloc::string::ToString;
256        let uuid_str = "abcdef01-2345-6789-abcd-ef0123456789";
257        // serde_json::from_value takes a Value (owned), exercising the owned-string path.
258        let val = serde_json::Value::String(uuid_str.to_string());
259        let id: Id128 = serde_json::from_value(val).expect("Id128 must deserialize from Value");
260        assert_eq!(format!("{id}"), uuid_str);
261    }
262}
khive_types/id.rs

khive_types/
id.rs
