nautilus_core/
uuid.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2025 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! A `UUID4` Universally Unique Identifier (UUID) version 4 (RFC 4122).
17
18use std::{
19    ffi::CStr,
20    fmt::{Debug, Display, Formatter},
21    hash::Hash,
22    io::{Cursor, Write},
23    str::FromStr,
24};
25
26use rand::RngCore;
27use serde::{Deserialize, Deserializer, Serialize, Serializer};
28use uuid::Uuid;
29
30/// The maximum length of ASCII characters for a `UUID4` string value (includes null terminator).
31pub(crate) const UUID4_LEN: usize = 37;
32
33/// Represents a Universally Unique Identifier (UUID)
34/// version 4 based on a 128-bit label as specified in RFC 4122.
35#[repr(C)]
36#[derive(Copy, Clone, Hash, PartialEq, Eq)]
37#[cfg_attr(
38    feature = "python",
39    pyo3::pyclass(module = "nautilus_trader.core.nautilus_pyo3.core")
40)]
41pub struct UUID4 {
42    /// The UUID v4 value as a fixed-length C string byte array (includes null terminator).
43    pub(crate) value: [u8; 37], // cbindgen issue using the constant in the array
44}
45
46impl UUID4 {
47    /// Creates a new [`UUID4`] instance.
48    ///
49    /// The UUID value is stored as a fixed-length C string byte array.
50    #[must_use]
51    pub fn new() -> Self {
52        let mut rng = rand::thread_rng();
53        let mut bytes = [0u8; 16];
54        rng.fill_bytes(&mut bytes);
55
56        bytes[6] = (bytes[6] & 0x0F) | 0x40; // Set the version to 4
57        bytes[8] = (bytes[8] & 0x3F) | 0x80; // Set the variant to RFC 4122
58
59        let mut value = [0u8; UUID4_LEN];
60        let mut cursor = Cursor::new(&mut value[..36]);
61
62        write!(
63            cursor,
64            "{:08x}-{:04x}-{:04x}-{:04x}-{:012x}",
65            u32::from_be_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]),
66            u16::from_be_bytes([bytes[4], bytes[5]]),
67            u16::from_be_bytes([bytes[6], bytes[7]]),
68            u16::from_be_bytes([bytes[8], bytes[9]]),
69            u64::from_be_bytes([
70                bytes[10], bytes[11], bytes[12], bytes[13], bytes[14], bytes[15], 0, 0
71            ]) >> 16
72        )
73        .expect("Error writing UUID string to buffer");
74
75        value[36] = 0; // Add the null terminator
76
77        Self { value }
78    }
79
80    /// Converts the [`UUID4`] to a C string reference.
81    #[must_use]
82    pub fn to_cstr(&self) -> &CStr {
83        // SAFETY: We always store valid C strings
84        CStr::from_bytes_with_nul(&self.value)
85            .expect("UUID byte representation should be a valid C string")
86    }
87
88    fn validate_v4(uuid: &Uuid) {
89        // Validate this is a v4 UUID
90        assert!(
91            !(uuid.get_version() != Some(uuid::Version::Random)),
92            "UUID is not version 4"
93        );
94
95        // Validate RFC4122 variant
96        assert!(
97            !(uuid.get_variant() != uuid::Variant::RFC4122),
98            "UUID is not RFC 4122 variant"
99        );
100    }
101
102    fn from_validated_uuid(uuid: &Uuid) -> Self {
103        let mut value = [0; UUID4_LEN];
104        let uuid_str = uuid.to_string();
105        value[..uuid_str.len()].copy_from_slice(uuid_str.as_bytes());
106        value[uuid_str.len()] = 0; // Add null terminator
107        Self { value }
108    }
109}
110
111impl FromStr for UUID4 {
112    type Err = uuid::Error;
113
114    /// Attempts to create a [`UUID4`] from a string representation.
115    ///
116    /// The string should be a valid UUID in the standard format (e.g., "2d89666b-1a1e-4a75-b193-4eb3b454c757").
117    ///
118    /// # Panics
119    ///
120    /// This function panics:
121    /// - If the `value` is not a valid UUID version 4 RFC 4122.
122    fn from_str(value: &str) -> Result<Self, Self::Err> {
123        let uuid = Uuid::try_parse(value)?;
124        Self::validate_v4(&uuid);
125        Ok(Self::from_validated_uuid(&uuid))
126    }
127}
128
129impl From<&str> for UUID4 {
130    /// Creates a [`UUID4`] from a string slice.
131    ///
132    /// # Panics
133    ///
134    /// This function panics:
135    /// - If the `value` string is not a valid UUID version 4 RFC 4122.
136    fn from(value: &str) -> Self {
137        value
138            .parse()
139            .expect("`value` should be a valid UUID version 4 (RFC 4122)")
140    }
141}
142
143impl From<String> for UUID4 {
144    /// Creates a [`UUID4`] from a string.
145    ///
146    /// # Panics
147    ///
148    /// This function panics:
149    /// - If the `value` string is not a valid UUID version 4 RFC 4122.
150    fn from(value: String) -> Self {
151        Self::from(value.as_str())
152    }
153}
154
155impl From<uuid::Uuid> for UUID4 {
156    /// Creates a [`UUID4`] from a [`uuid::Uuid`].
157    ///
158    /// # Panics
159    ///
160    /// This function panics:
161    /// - If the `value` is not a valid UUID version 4 RFC 4122.
162    fn from(value: uuid::Uuid) -> Self {
163        Self::validate_v4(&value);
164        Self::from_validated_uuid(&value)
165    }
166}
167
168impl Default for UUID4 {
169    /// Creates a new default [`UUID4`] instance.
170    ///
171    /// The default UUID4 is simply a newly generated UUID version 4.
172    fn default() -> Self {
173        Self::new()
174    }
175}
176
177impl Debug for UUID4 {
178    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
179        write!(f, "{}('{}')", stringify!(UUID4), self)
180    }
181}
182
183impl Display for UUID4 {
184    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
185        write!(f, "{}", self.to_cstr().to_string_lossy())
186    }
187}
188
189impl Serialize for UUID4 {
190    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
191    where
192        S: Serializer,
193    {
194        self.to_string().serialize(serializer)
195    }
196}
197
198impl<'de> Deserialize<'de> for UUID4 {
199    fn deserialize<D>(_deserializer: D) -> Result<Self, D::Error>
200    where
201        D: Deserializer<'de>,
202    {
203        let uuid4_str: &str = Deserialize::deserialize(_deserializer)?;
204        let uuid4: Self = uuid4_str.into();
205        Ok(uuid4)
206    }
207}
208
209////////////////////////////////////////////////////////////////////////////////
210// Tests
211////////////////////////////////////////////////////////////////////////////////
212#[cfg(test)]
213mod tests {
214    use std::{
215        collections::hash_map::DefaultHasher,
216        hash::{Hash, Hasher},
217    };
218
219    use rstest::*;
220    use uuid;
221
222    use super::*;
223
224    #[rstest]
225    fn test_new() {
226        let uuid = UUID4::new();
227        let uuid_string = uuid.to_string();
228        let uuid_parsed = Uuid::parse_str(&uuid_string).unwrap();
229        assert_eq!(uuid_parsed.get_version().unwrap(), uuid::Version::Random);
230        assert_eq!(uuid_parsed.to_string().len(), 36);
231
232        // Version 4 requires bits: 0b0100xxxx
233        assert_eq!(&uuid_string[14..15], "4");
234        // RFC4122 variant requires bits: 0b10xxxxxx
235        let variant_char = &uuid_string[19..20];
236        assert!(matches!(variant_char, "8" | "9" | "a" | "b" | "A" | "B"));
237    }
238
239    #[rstest]
240    fn test_uuid_format() {
241        let uuid = UUID4::new();
242        let bytes = uuid.value;
243
244        // Check null termination
245        assert_eq!(bytes[36], 0);
246
247        // Verify dash positions
248        assert_eq!(bytes[8] as char, '-');
249        assert_eq!(bytes[13] as char, '-');
250        assert_eq!(bytes[18] as char, '-');
251        assert_eq!(bytes[23] as char, '-');
252
253        let s = uuid.to_string();
254        assert_eq!(s.chars().nth(14).unwrap(), '4');
255    }
256
257    #[rstest]
258    #[should_panic(expected = "UUID is not version 4")]
259    fn test_from_str_with_non_version_4_uuid_panics() {
260        let uuid_string = "6ba7b810-9dad-11d1-80b4-00c04fd430c8"; // v1 UUID
261        let _ = UUID4::from(uuid_string);
262    }
263
264    #[rstest]
265    fn test_case_insensitive_parsing() {
266        let upper = "2D89666B-1A1E-4A75-B193-4EB3B454C757";
267        let lower = "2d89666b-1a1e-4a75-b193-4eb3b454c757";
268        let uuid_upper = UUID4::from(upper);
269        let uuid_lower = UUID4::from(lower);
270
271        assert_eq!(uuid_upper, uuid_lower);
272        assert_eq!(uuid_upper.to_string(), lower);
273    }
274
275    #[rstest]
276    #[case("6ba7b810-9dad-11d1-80b4-00c04fd430c8")] // v1 (time-based)
277    #[case("000001f5-8fa9-21d1-9df3-00e098032b8c")] // v2 (DCE Security)
278    #[case("3d813cbb-47fb-32ba-91df-831e1593ac29")] // v3 (MD5 hash)
279    #[case("fb4f37c1-4ba3-5173-9812-2b90e76a06f7")] // v5 (SHA-1 hash)
280    #[should_panic(expected = "UUID is not version 4")]
281    fn test_invalid_version(#[case] uuid_string: &str) {
282        let _ = UUID4::from(uuid_string);
283    }
284
285    #[rstest]
286    #[should_panic(expected = "UUID is not RFC 4122 variant")]
287    fn test_non_rfc4122_variant() {
288        // Valid v4 but wrong variant
289        let uuid = "550e8400-e29b-41d4-0000-446655440000";
290        let _ = UUID4::from(uuid);
291    }
292
293    #[rstest]
294    #[case("")] // Empty string
295    #[case("not-a-uuid-at-all")] // Invalid format
296    #[case("6ba7b810-9dad-11d1-80b4")] // Too short
297    #[case("6ba7b810-9dad-11d1-80b4-00c04fd430c8-extra")] // Too long
298    #[case("6ba7b810-9dad-11d1-80b4=00c04fd430c8")] // Wrong separator
299    #[case("6ba7b81019dad111d180b400c04fd430c8")] // No separators
300    #[case("6ba7b810-9dad-11d1-80b4-00c04fd430")] // Truncated
301    #[case("6ba7b810-9dad-11d1-80b4-00c04fd430cg")] // Invalid hex character
302    fn test_invalid_uuid_cases(#[case] invalid_uuid: &str) {
303        assert!(UUID4::from_str(invalid_uuid).is_err());
304    }
305
306    #[rstest]
307    fn test_default() {
308        let uuid: UUID4 = UUID4::default();
309        let uuid_string = uuid.to_string();
310        let uuid_parsed = Uuid::parse_str(&uuid_string).unwrap();
311        assert_eq!(uuid_parsed.get_version().unwrap(), uuid::Version::Random);
312    }
313
314    #[rstest]
315    fn test_from_str() {
316        let uuid_string = "2d89666b-1a1e-4a75-b193-4eb3b454c757";
317        let uuid = UUID4::from(uuid_string);
318        let result_string = uuid.to_string();
319        let result_parsed = Uuid::parse_str(&result_string).unwrap();
320        let expected_parsed = Uuid::parse_str(uuid_string).unwrap();
321        assert_eq!(result_parsed, expected_parsed);
322    }
323
324    #[rstest]
325    fn test_from_uuid() {
326        let original = uuid::Uuid::new_v4();
327        let uuid4 = UUID4::from(original);
328        assert_eq!(uuid4.to_string(), original.to_string());
329    }
330
331    #[rstest]
332    fn test_equality() {
333        let uuid1 = UUID4::from("2d89666b-1a1e-4a75-b193-4eb3b454c757");
334        let uuid2 = UUID4::from("46922ecb-4324-4e40-a56c-841e0d774cef");
335        assert_eq!(uuid1, uuid1);
336        assert_ne!(uuid1, uuid2);
337    }
338
339    #[rstest]
340    fn test_debug() {
341        let uuid_string = "2d89666b-1a1e-4a75-b193-4eb3b454c757";
342        let uuid = UUID4::from(uuid_string);
343        assert_eq!(format!("{uuid:?}"), format!("UUID4('{uuid_string}')"));
344    }
345
346    #[rstest]
347    fn test_display() {
348        let uuid_string = "2d89666b-1a1e-4a75-b193-4eb3b454c757";
349        let uuid = UUID4::from(uuid_string);
350        assert_eq!(format!("{uuid}"), uuid_string);
351    }
352
353    #[rstest]
354    fn test_to_cstr() {
355        let uuid = UUID4::new();
356        let cstr = uuid.to_cstr();
357
358        assert_eq!(cstr.to_str().unwrap(), uuid.to_string());
359        assert_eq!(cstr.to_bytes_with_nul()[36], 0);
360    }
361
362    #[rstest]
363    fn test_hash_consistency() {
364        let uuid = UUID4::new();
365
366        let mut hasher1 = DefaultHasher::new();
367        let mut hasher2 = DefaultHasher::new();
368
369        uuid.hash(&mut hasher1);
370        uuid.hash(&mut hasher2);
371
372        assert_eq!(hasher1.finish(), hasher2.finish());
373    }
374
375    #[rstest]
376    fn test_serialize_json() {
377        let uuid_string = "2d89666b-1a1e-4a75-b193-4eb3b454c757";
378        let uuid = UUID4::from(uuid_string);
379
380        let serialized = serde_json::to_string(&uuid).unwrap();
381        let expected_json = format!("\"{uuid_string}\"");
382        assert_eq!(serialized, expected_json);
383    }
384
385    #[rstest]
386    fn test_deserialize_json() {
387        let uuid_string = "2d89666b-1a1e-4a75-b193-4eb3b454c757";
388        let serialized = format!("\"{uuid_string}\"");
389
390        let deserialized: UUID4 = serde_json::from_str(&serialized).unwrap();
391        assert_eq!(deserialized.to_string(), uuid_string);
392    }
393
394    #[rstest]
395    fn test_serialize_deserialize_round_trip() {
396        let uuid = UUID4::new();
397
398        let serialized = serde_json::to_string(&uuid).unwrap();
399        let deserialized: UUID4 = serde_json::from_str(&serialized).unwrap();
400
401        assert_eq!(uuid, deserialized);
402    }
403}
nautilus_core/uuid.rs

nautilus_core/
uuid.rs
