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    ///
142    /// # Example
143    ///
144    /// ```
145    /// use id_forge::uuid::Uuid;
146    ///
147    /// let id = Uuid::nil();
148    /// assert_eq!(id.as_bytes(), &[0u8; 16]);
149    /// ```
150    pub const fn as_bytes(&self) -> &[u8; 16] {
151        &self.0
152    }
153
154    /// Return the version nibble (the high 4 bits of byte 6).
155    ///
156    /// `4` for v4, `7` for v7, `0` for [`Uuid::nil`], `15` for [`Uuid::max`].
157    ///
158    /// # Example
159    ///
160    /// ```
161    /// use id_forge::uuid::Uuid;
162    ///
163    /// assert_eq!(Uuid::v4().version(), 4);
164    /// assert_eq!(Uuid::v7().version(), 7);
165    /// assert_eq!(Uuid::nil().version(), 0);
166    /// ```
167    pub const fn version(&self) -> u8 {
168        self.0[6] >> 4
169    }
170
171    /// Parse a UUID from its canonical 36-character hyphenated form
172    /// (e.g. `f47ac10b-58cc-4372-a567-0e02b2c3d479`).
173    ///
174    /// Parsing is case-insensitive. Returns [`ParseError`] if the
175    /// input is not exactly 36 characters, has hyphens in the wrong
176    /// positions, or contains a non-hex digit.
177    ///
178    /// # Example
179    ///
180    /// ```
181    /// use id_forge::uuid::Uuid;
182    ///
183    /// let id = Uuid::parse_str("f47ac10b-58cc-4372-a567-0e02b2c3d479").unwrap();
184    /// assert_eq!(id.to_string(), "f47ac10b-58cc-4372-a567-0e02b2c3d479");
185    /// ```
186    pub fn parse_str(input: &str) -> Result<Self, ParseError> {
187        let bytes = input.as_bytes();
188        if bytes.len() != 36 {
189            return Err(ParseError::InvalidLength(bytes.len()));
190        }
191        let hyphen_positions = [8usize, 13, 18, 23];
192        for &p in &hyphen_positions {
193            if bytes[p] != b'-' {
194                return Err(ParseError::InvalidGroup(p));
195            }
196        }
197        let mut out = [0u8; 16];
198        let mut hex_idx = 0;
199        let mut byte_idx = 0;
200        while hex_idx < 36 {
201            if hyphen_positions.contains(&hex_idx) {
202                hex_idx += 1;
203                continue;
204            }
205            let hi = hex_value(bytes[hex_idx]).ok_or(ParseError::InvalidChar(hex_idx))?;
206            let lo = hex_value(bytes[hex_idx + 1]).ok_or(ParseError::InvalidChar(hex_idx + 1))?;
207            out[byte_idx] = (hi << 4) | lo;
208            byte_idx += 1;
209            hex_idx += 2;
210        }
211        Ok(Self(out))
212    }
213}
214
215impl Default for Uuid {
216    fn default() -> Self {
217        Self::nil()
218    }
219}
220
221impl fmt::Display for Uuid {
222    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
223        let b = &self.0;
224        write!(
225            f,
226            "{:02x}{:02x}{:02x}{:02x}-{:02x}{:02x}-{:02x}{:02x}-{:02x}{:02x}-{:02x}{:02x}{:02x}{:02x}{:02x}{:02x}",
227            b[0], b[1], b[2], b[3], b[4], b[5], b[6], b[7],
228            b[8], b[9], b[10], b[11], b[12], b[13], b[14], b[15]
229        )
230    }
231}
232
233impl core::str::FromStr for Uuid {
234    type Err = ParseError;
235    fn from_str(s: &str) -> Result<Self, Self::Err> {
236        Self::parse_str(s)
237    }
238}
239
240/// Error returned by [`Uuid::parse_str`].
241#[derive(Debug, Clone, Copy, PartialEq, Eq)]
242pub enum ParseError {
243    /// Input was not exactly 36 characters. The value is the actual length.
244    InvalidLength(usize),
245    /// A hyphen was missing at the given byte position (expected 8, 13, 18, or 23).
246    InvalidGroup(usize),
247    /// A non-hex digit was found at the given byte position.
248    InvalidChar(usize),
249}
250
251impl fmt::Display for ParseError {
252    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
253        match self {
254            Self::InvalidLength(n) => write!(f, "expected 36 characters, got {n}"),
255            Self::InvalidGroup(p) => write!(f, "expected hyphen at position {p}"),
256            Self::InvalidChar(p) => write!(f, "invalid hex digit at position {p}"),
257        }
258    }
259}
260
261impl std::error::Error for ParseError {}
262
263#[inline]
264const fn hex_value(c: u8) -> Option<u8> {
265    match c {
266        b'0'..=b'9' => Some(c - b'0'),
267        b'a'..=b'f' => Some(c - b'a' + 10),
268        b'A'..=b'F' => Some(c - b'A' + 10),
269        _ => None,
270    }
271}
272
273#[cfg(test)]
274mod tests {
275    use super::*;
276
277    #[test]
278    fn v4_version_and_variant() {
279        let id = Uuid::v4();
280        assert_eq!(id.version(), 4);
281        assert_eq!(id.0[8] & 0xc0, 0x80);
282    }
283
284    #[test]
285    fn v7_version_and_variant() {
286        let id = Uuid::v7();
287        assert_eq!(id.version(), 7);
288        assert_eq!(id.0[8] & 0xc0, 0x80);
289    }
290
291    #[test]
292    fn display_format_canonical() {
293        let id = Uuid::v4();
294        let s = id.to_string();
295        assert_eq!(s.len(), 36);
296        let hyphen_positions: Vec<usize> = s
297            .char_indices()
298            .filter_map(|(i, c)| if c == '-' { Some(i) } else { None })
299            .collect();
300        assert_eq!(hyphen_positions, vec![8, 13, 18, 23]);
301    }
302
303    #[test]
304    fn v4_pair_differs() {
305        assert_ne!(Uuid::v4(), Uuid::v4());
306    }
307
308    #[test]
309    fn v7_pair_differs() {
310        assert_ne!(Uuid::v7(), Uuid::v7());
311    }
312
313    #[test]
314    fn v7_time_ordered_across_ms() {
315        let a = Uuid::v7();
316        std::thread::sleep(std::time::Duration::from_millis(2));
317        let b = Uuid::v7();
318        assert!(b.as_bytes() > a.as_bytes());
319    }
320
321    #[test]
322    fn nil_and_max() {
323        assert_eq!(Uuid::nil().as_bytes(), &[0u8; 16]);
324        assert_eq!(Uuid::max().as_bytes(), &[0xffu8; 16]);
325        assert_eq!(
326            Uuid::nil().to_string(),
327            "00000000-0000-0000-0000-000000000000"
328        );
329        assert_eq!(
330            Uuid::max().to_string(),
331            "ffffffff-ffff-ffff-ffff-ffffffffffff"
332        );
333    }
334
335    #[test]
336    fn default_is_nil() {
337        assert_eq!(Uuid::default(), Uuid::nil());
338    }
339
340    #[test]
341    fn from_bytes_roundtrip() {
342        let id = Uuid::v4();
343        assert_eq!(Uuid::from_bytes(id.as_bytes()), id);
344    }
345
346    // RFC 9562 Appendix A.2 — v4 example.
347    #[test]
348    fn parse_rfc9562_v4_example() {
349        let s = "919108f7-52d1-4320-9bac-f847db4148a8";
350        let id = Uuid::parse_str(s).unwrap();
351        assert_eq!(id.version(), 4);
352        assert_eq!(id.0[8] & 0xc0, 0x80);
353        assert_eq!(id.to_string(), s);
354    }
355
356    // RFC 9562 Appendix A.6 — v7 example.
357    #[test]
358    fn parse_rfc9562_v7_example() {
359        let s = "017f22e2-79b0-7cc3-98c4-dc0c0c07398f";
360        let id = Uuid::parse_str(s).unwrap();
361        assert_eq!(id.version(), 7);
362        assert_eq!(id.0[8] & 0xc0, 0x80);
363        assert_eq!(id.to_string(), s);
364    }
365
366    #[test]
367    fn parse_uppercase() {
368        let id = Uuid::parse_str("F47AC10B-58CC-4372-A567-0E02B2C3D479").unwrap();
369        assert_eq!(id.to_string(), "f47ac10b-58cc-4372-a567-0e02b2c3d479");
370    }
371
372    #[test]
373    fn parse_nil() {
374        let id = Uuid::parse_str("00000000-0000-0000-0000-000000000000").unwrap();
375        assert_eq!(id, Uuid::nil());
376    }
377
378    #[test]
379    fn parse_rejects_short() {
380        assert!(matches!(
381            Uuid::parse_str("abc"),
382            Err(ParseError::InvalidLength(3))
383        ));
384    }
385
386    #[test]
387    fn parse_rejects_missing_hyphen() {
388        assert!(matches!(
389            Uuid::parse_str("f47ac10b_58cc-4372-a567-0e02b2c3d479"),
390            Err(ParseError::InvalidGroup(8))
391        ));
392    }
393
394    #[test]
395    fn parse_rejects_bad_hex() {
396        assert!(matches!(
397            Uuid::parse_str("g47ac10b-58cc-4372-a567-0e02b2c3d479"),
398            Err(ParseError::InvalidChar(0))
399        ));
400    }
401
402    #[test]
403    fn from_str_works() {
404        let id: Uuid = "f47ac10b-58cc-4372-a567-0e02b2c3d479".parse().unwrap();
405        assert_eq!(id.to_string(), "f47ac10b-58cc-4372-a567-0e02b2c3d479");
406    }
407
408    #[test]
409    fn many_v4_unique() {
410        use std::collections::HashSet;
411        let mut set = HashSet::new();
412        for _ in 0..10_000 {
413            assert!(set.insert(Uuid::v4()));
414        }
415    }
416}
id_forge/uuid.rs

id_forge/
uuid.rs
