id_forge/
uuid.rs

1//! # UUID generation
2//!
3//! UUID v4 (random) and v7 (time-ordered) per RFC 9562.
4//!
5//! UUIDs produced by this module set the version and variant bits exactly
6//! as the RFC requires, so they round-trip through any conformant parser.
7//!
8//! ```
9//! use id_forge::uuid::Uuid;
10//!
11//! let v4 = Uuid::v4();
12//! let v7 = Uuid::v7();
13//! let parsed = Uuid::parse_str(&v4.to_string()).unwrap();
14//! assert_eq!(v4, parsed);
15//! assert_eq!(v7.to_string().len(), 36);
16//! ```
17//!
18//! ## Randomness
19//!
20//! The random portion is filled by an inline xoshiro256\*\* generator
21//! seeded from process ID, wall-clock nanoseconds, and a per-process
22//! counter. This is fast and unpredictable across processes, but it is
23//! **not** cryptographically secure — use a CSPRNG for session tokens
24//! or API keys.
25
26use core::fmt;
27use std::time::{SystemTime, UNIX_EPOCH};
28
29use crate::rng;
30
31/// A 128-bit UUID.
32///
33/// The internal representation is 16 big-endian bytes per RFC 9562.
34///
35/// # Example
36///
37/// ```
38/// use id_forge::uuid::Uuid;
39///
40/// let id = Uuid::v4();
41/// assert_eq!(id.to_string().len(), 36);
42/// ```
43#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
44pub struct Uuid([u8; 16]);
45
46impl Uuid {
47    /// The Nil UUID: all 128 bits set to zero (RFC 9562 §5.9).
48    ///
49    /// # Example
50    ///
51    /// ```
52    /// use id_forge::uuid::Uuid;
53    ///
54    /// assert_eq!(Uuid::nil().to_string(), "00000000-0000-0000-0000-000000000000");
55    /// ```
56    pub const fn nil() -> Self {
57        Self([0u8; 16])
58    }
59
60    /// The Max UUID: all 128 bits set to one (RFC 9562 §5.10).
61    ///
62    /// # Example
63    ///
64    /// ```
65    /// use id_forge::uuid::Uuid;
66    ///
67    /// assert_eq!(Uuid::max().to_string(), "ffffffff-ffff-ffff-ffff-ffffffffffff");
68    /// ```
69    pub const fn max() -> Self {
70        Self([0xff; 16])
71    }
72
73    /// Construct a v4 (random) UUID per RFC 9562 §5.4.
74    ///
75    /// 122 random bits with the version nibble set to `0100` and the
76    /// variant bits set to `10` (RFC 4122 layout).
77    ///
78    /// # Example
79    ///
80    /// ```
81    /// use id_forge::uuid::Uuid;
82    ///
83    /// let id = Uuid::v4();
84    /// assert_eq!(id.version(), 4);
85    /// ```
86    pub fn v4() -> Self {
87        let mut bytes = rng::next_bytes_16();
88        bytes[6] = (bytes[6] & 0x0f) | 0x40;
89        bytes[8] = (bytes[8] & 0x3f) | 0x80;
90        Self(bytes)
91    }
92
93    /// Construct a v7 (time-ordered) UUID per RFC 9562 §5.7.
94    ///
95    /// 48-bit big-endian millisecond timestamp prefix, 74 random bits,
96    /// with the version nibble set to `0111` and the RFC 4122 variant bits.
97    /// Two v7 IDs generated in different milliseconds compare in
98    /// timestamp order byte-wise.
99    ///
100    /// # Example
101    ///
102    /// ```
103    /// use id_forge::uuid::Uuid;
104    ///
105    /// let id = Uuid::v7();
106    /// assert_eq!(id.version(), 7);
107    /// ```
108    pub fn v7() -> Self {
109        let ms = SystemTime::now()
110            .duration_since(UNIX_EPOCH)
111            .map(|d| d.as_millis() as u64)
112            .unwrap_or(0);
113        let mut bytes = rng::next_bytes_16();
114        let ms_bytes = ms.to_be_bytes();
115        bytes[0..6].copy_from_slice(&ms_bytes[2..8]);
116        bytes[6] = (bytes[6] & 0x0f) | 0x70;
117        bytes[8] = (bytes[8] & 0x3f) | 0x80;
118        Self(bytes)
119    }
120
121    /// Wrap a 16-byte big-endian representation.
122    ///
123    /// The bytes are taken as-is; no version or variant bits are
124    /// touched. Use this to round-trip an externally generated UUID
125    /// or to reconstruct one from storage.
126    ///
127    /// # Example
128    ///
129    /// ```
130    /// use id_forge::uuid::Uuid;
131    ///
132    /// let id = Uuid::v4();
133    /// let copy = Uuid::from_bytes(id.as_bytes());
134    /// assert_eq!(id, copy);
135    /// ```
136    pub const fn from_bytes(bytes: &[u8; 16]) -> Self {
137        Self(*bytes)
138    }
139
140    /// Return the raw 16-byte big-endian representation.
141    pub const fn as_bytes(&self) -> &[u8; 16] {
142        &self.0
143    }
144
145    /// Return the version nibble (the high 4 bits of byte 6).
146    ///
147    /// `4` for v4, `7` for v7, `0` for [`Uuid::nil`], `15` for [`Uuid::max`].
148    pub const fn version(&self) -> u8 {
149        self.0[6] >> 4
150    }
151
152    /// Parse a UUID from its canonical 36-character hyphenated form
153    /// (e.g. `f47ac10b-58cc-4372-a567-0e02b2c3d479`).
154    ///
155    /// Parsing is case-insensitive. Returns [`ParseError`] if the
156    /// input is not exactly 36 characters, has hyphens in the wrong
157    /// positions, or contains a non-hex digit.
158    ///
159    /// # Example
160    ///
161    /// ```
162    /// use id_forge::uuid::Uuid;
163    ///
164    /// let id = Uuid::parse_str("f47ac10b-58cc-4372-a567-0e02b2c3d479").unwrap();
165    /// assert_eq!(id.to_string(), "f47ac10b-58cc-4372-a567-0e02b2c3d479");
166    /// ```
167    pub fn parse_str(input: &str) -> Result<Self, ParseError> {
168        let bytes = input.as_bytes();
169        if bytes.len() != 36 {
170            return Err(ParseError::InvalidLength(bytes.len()));
171        }
172        let hyphen_positions = [8usize, 13, 18, 23];
173        for &p in &hyphen_positions {
174            if bytes[p] != b'-' {
175                return Err(ParseError::InvalidGroup(p));
176            }
177        }
178        let mut out = [0u8; 16];
179        let mut hex_idx = 0;
180        let mut byte_idx = 0;
181        while hex_idx < 36 {
182            if hyphen_positions.contains(&hex_idx) {
183                hex_idx += 1;
184                continue;
185            }
186            let hi = hex_value(bytes[hex_idx]).ok_or(ParseError::InvalidChar(hex_idx))?;
187            let lo = hex_value(bytes[hex_idx + 1]).ok_or(ParseError::InvalidChar(hex_idx + 1))?;
188            out[byte_idx] = (hi << 4) | lo;
189            byte_idx += 1;
190            hex_idx += 2;
191        }
192        Ok(Self(out))
193    }
194}
195
196impl Default for Uuid {
197    fn default() -> Self {
198        Self::nil()
199    }
200}
201
202impl fmt::Display for Uuid {
203    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
204        let b = &self.0;
205        write!(
206            f,
207            "{:02x}{:02x}{:02x}{:02x}-{:02x}{:02x}-{:02x}{:02x}-{:02x}{:02x}-{:02x}{:02x}{:02x}{:02x}{:02x}{:02x}",
208            b[0], b[1], b[2], b[3], b[4], b[5], b[6], b[7],
209            b[8], b[9], b[10], b[11], b[12], b[13], b[14], b[15]
210        )
211    }
212}
213
214impl core::str::FromStr for Uuid {
215    type Err = ParseError;
216    fn from_str(s: &str) -> Result<Self, Self::Err> {
217        Self::parse_str(s)
218    }
219}
220
221/// Error returned by [`Uuid::parse_str`].
222#[derive(Debug, Clone, Copy, PartialEq, Eq)]
223pub enum ParseError {
224    /// Input was not exactly 36 characters. The value is the actual length.
225    InvalidLength(usize),
226    /// A hyphen was missing at the given byte position (expected 8, 13, 18, or 23).
227    InvalidGroup(usize),
228    /// A non-hex digit was found at the given byte position.
229    InvalidChar(usize),
230}
231
232impl fmt::Display for ParseError {
233    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
234        match self {
235            Self::InvalidLength(n) => write!(f, "expected 36 characters, got {n}"),
236            Self::InvalidGroup(p) => write!(f, "expected hyphen at position {p}"),
237            Self::InvalidChar(p) => write!(f, "invalid hex digit at position {p}"),
238        }
239    }
240}
241
242impl std::error::Error for ParseError {}
243
244#[inline]
245const fn hex_value(c: u8) -> Option<u8> {
246    match c {
247        b'0'..=b'9' => Some(c - b'0'),
248        b'a'..=b'f' => Some(c - b'a' + 10),
249        b'A'..=b'F' => Some(c - b'A' + 10),
250        _ => None,
251    }
252}
253
254#[cfg(test)]
255mod tests {
256    use super::*;
257
258    #[test]
259    fn v4_version_and_variant() {
260        let id = Uuid::v4();
261        assert_eq!(id.version(), 4);
262        assert_eq!(id.0[8] & 0xc0, 0x80);
263    }
264
265    #[test]
266    fn v7_version_and_variant() {
267        let id = Uuid::v7();
268        assert_eq!(id.version(), 7);
269        assert_eq!(id.0[8] & 0xc0, 0x80);
270    }
271
272    #[test]
273    fn display_format_canonical() {
274        let id = Uuid::v4();
275        let s = id.to_string();
276        assert_eq!(s.len(), 36);
277        let hyphen_positions: Vec<usize> = s
278            .char_indices()
279            .filter_map(|(i, c)| if c == '-' { Some(i) } else { None })
280            .collect();
281        assert_eq!(hyphen_positions, vec![8, 13, 18, 23]);
282    }
283
284    #[test]
285    fn v4_pair_differs() {
286        assert_ne!(Uuid::v4(), Uuid::v4());
287    }
288
289    #[test]
290    fn v7_pair_differs() {
291        assert_ne!(Uuid::v7(), Uuid::v7());
292    }
293
294    #[test]
295    fn v7_time_ordered_across_ms() {
296        let a = Uuid::v7();
297        std::thread::sleep(std::time::Duration::from_millis(2));
298        let b = Uuid::v7();
299        assert!(b.as_bytes() > a.as_bytes());
300    }
301
302    #[test]
303    fn nil_and_max() {
304        assert_eq!(Uuid::nil().as_bytes(), &[0u8; 16]);
305        assert_eq!(Uuid::max().as_bytes(), &[0xffu8; 16]);
306        assert_eq!(
307            Uuid::nil().to_string(),
308            "00000000-0000-0000-0000-000000000000"
309        );
310        assert_eq!(
311            Uuid::max().to_string(),
312            "ffffffff-ffff-ffff-ffff-ffffffffffff"
313        );
314    }
315
316    #[test]
317    fn default_is_nil() {
318        assert_eq!(Uuid::default(), Uuid::nil());
319    }
320
321    #[test]
322    fn from_bytes_roundtrip() {
323        let id = Uuid::v4();
324        assert_eq!(Uuid::from_bytes(id.as_bytes()), id);
325    }
326
327    // RFC 9562 Appendix A.2 — v4 example.
328    #[test]
329    fn parse_rfc9562_v4_example() {
330        let s = "919108f7-52d1-4320-9bac-f847db4148a8";
331        let id = Uuid::parse_str(s).unwrap();
332        assert_eq!(id.version(), 4);
333        assert_eq!(id.0[8] & 0xc0, 0x80);
334        assert_eq!(id.to_string(), s);
335    }
336
337    // RFC 9562 Appendix A.6 — v7 example.
338    #[test]
339    fn parse_rfc9562_v7_example() {
340        let s = "017f22e2-79b0-7cc3-98c4-dc0c0c07398f";
341        let id = Uuid::parse_str(s).unwrap();
342        assert_eq!(id.version(), 7);
343        assert_eq!(id.0[8] & 0xc0, 0x80);
344        assert_eq!(id.to_string(), s);
345    }
346
347    #[test]
348    fn parse_uppercase() {
349        let id = Uuid::parse_str("F47AC10B-58CC-4372-A567-0E02B2C3D479").unwrap();
350        assert_eq!(id.to_string(), "f47ac10b-58cc-4372-a567-0e02b2c3d479");
351    }
352
353    #[test]
354    fn parse_nil() {
355        let id = Uuid::parse_str("00000000-0000-0000-0000-000000000000").unwrap();
356        assert_eq!(id, Uuid::nil());
357    }
358
359    #[test]
360    fn parse_rejects_short() {
361        assert!(matches!(
362            Uuid::parse_str("abc"),
363            Err(ParseError::InvalidLength(3))
364        ));
365    }
366
367    #[test]
368    fn parse_rejects_missing_hyphen() {
369        assert!(matches!(
370            Uuid::parse_str("f47ac10b_58cc-4372-a567-0e02b2c3d479"),
371            Err(ParseError::InvalidGroup(8))
372        ));
373    }
374
375    #[test]
376    fn parse_rejects_bad_hex() {
377        assert!(matches!(
378            Uuid::parse_str("g47ac10b-58cc-4372-a567-0e02b2c3d479"),
379            Err(ParseError::InvalidChar(0))
380        ));
381    }
382
383    #[test]
384    fn from_str_works() {
385        let id: Uuid = "f47ac10b-58cc-4372-a567-0e02b2c3d479".parse().unwrap();
386        assert_eq!(id.to_string(), "f47ac10b-58cc-4372-a567-0e02b2c3d479");
387    }
388
389    #[test]
390    fn many_v4_unique() {
391        use std::collections::HashSet;
392        let mut set = HashSet::new();
393        for _ in 0..10_000 {
394            assert!(set.insert(Uuid::v4()));
395        }
396    }
397}
id_forge/uuid.rs

id_forge/
uuid.rs
