bc_components/id/
uuid.rs

1use std::str::FromStr;
2
3use anyhow::{ Result, Error };
4use dcbor::prelude::*;
5use crate::tags;
6
7/// A Universally Unique Identifier (UUID).
8///
9/// UUIDs are 128-bit (16-byte) identifiers that are designed to be unique across space and time.
10/// This implementation creates type 4 (random) UUIDs, following the UUID specification:
11///
12/// - Version field (bits 48-51) is set to 4, indicating a random UUID
13/// - Variant field (bits 64-65) is set to 2, indicating RFC 4122/DCE 1.1 UUID variant
14///
15/// Unlike ARIDs, UUIDs:
16/// - Are shorter (128 bits vs 256 bits)
17/// - Contain version and variant metadata within the identifier
18/// - Have a canonical string representation with 5 groups separated by hyphens
19///
20/// The canonical textual representation of a UUID takes the form:
21/// `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` where each `x` is a hexadecimal digit.
22#[derive(Clone, Copy, Debug, Eq, PartialEq)]
23pub struct UUID([u8; Self::UUID_SIZE]);
24
25impl UUID {
26    pub const UUID_SIZE: usize = 16;
27
28    /// Creates a new type 4 (random) UUID.
29    pub fn new() -> Self {
30        let mut uuid = [0u8; Self::UUID_SIZE];
31        bc_rand::fill_random_data(&mut uuid);
32        uuid[6] = (uuid[6] & 0x0f) | 0x40; // set version to 4
33        uuid[8] = (uuid[8] & 0x3f) | 0x80; // set variant to 2
34        Self(uuid)
35    }
36
37    /// Restores a UUID from data.
38    pub fn from_data(data: [u8; Self::UUID_SIZE]) -> Self {
39        Self(data)
40    }
41
42    /// Restores a UUID from data.
43    pub fn from_data_ref(data: impl AsRef<[u8]>) -> Option<Self> {
44        let data = data.as_ref();
45        if data.len() != Self::UUID_SIZE {
46            return None;
47        }
48        let mut arr = [0u8; Self::UUID_SIZE];
49        arr.copy_from_slice(data);
50        Some(Self::from_data(arr))
51    }
52
53    /// Returns the data of the UUID.
54    pub fn data(&self) -> &[u8; Self::UUID_SIZE] {
55        self.into()
56    }
57}
58
59/// Implements Default for UUID to create a new random UUID.
60impl Default for UUID {
61    fn default() -> Self {
62        Self::new()
63    }
64}
65
66/// Implements conversion from a UUID reference to a byte array reference.
67impl<'a> From<&'a UUID> for &'a [u8; UUID::UUID_SIZE] {
68    fn from(value: &'a UUID) -> Self {
69        &value.0
70    }
71}
72
73/// Implements AsRef<[u8]> to allow UUID to be treated as a byte slice.
74impl AsRef<[u8]> for UUID {
75    fn as_ref(&self) -> &[u8] {
76        &self.0
77    }
78}
79
80/// Implements CBORTagged trait to provide CBOR tag information.
81impl CBORTagged for UUID {
82    fn cbor_tags() -> Vec<Tag> {
83        tags_for_values(&[tags::TAG_UUID])
84    }
85}
86
87/// Implements conversion from UUID to CBOR for serialization.
88impl From<UUID> for CBOR {
89    fn from(value: UUID) -> Self {
90        value.tagged_cbor()
91    }
92}
93
94/// Implements CBORTaggedEncodable to provide CBOR encoding functionality.
95impl CBORTaggedEncodable for UUID {
96    fn untagged_cbor(&self) -> CBOR {
97        CBOR::to_byte_string(self.0)
98    }
99}
100
101/// Implements `TryFrom<CBOR>` for UUID to support conversion from CBOR data.
102impl TryFrom<CBOR> for UUID {
103    type Error = dcbor::Error;
104
105    fn try_from(cbor: CBOR) -> dcbor::Result<Self> {
106        Self::from_tagged_cbor(cbor)
107    }
108}
109
110/// Implements CBORTaggedDecodable to provide CBOR decoding functionality.
111impl CBORTaggedDecodable for UUID {
112    fn from_untagged_cbor(cbor: CBOR) -> dcbor::Result<Self> {
113        let bytes = CBOR::try_into_byte_string(cbor)?;
114        if bytes.len() != Self::UUID_SIZE {
115            return Err("invalid UUID size".into());
116        }
117        let mut uuid = [0u8; Self::UUID_SIZE];
118        uuid.copy_from_slice(&bytes);
119        Ok(Self::from_data(uuid))
120    }
121}
122
123/// Implements Display for UUID to format it in the standard UUID string format.
124impl std::fmt::Display for UUID {
125    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
126        write!(f, "{}", String::from(self))
127    }
128}
129
130/// Implements conversion from UUID to String in the standard format with dashes.
131impl From<UUID> for String {
132    fn from(uuid: UUID) -> Self {
133        let hex = hex::encode(uuid.0);
134        format!("{}-{}-{}-{}-{}", &hex[0..8], &hex[8..12], &hex[12..16], &hex[16..20], &hex[20..32])
135    }
136}
137
138/// Implements conversion from UUID reference to String.
139impl From<&UUID> for String {
140    fn from(uuid: &UUID) -> Self {
141        String::from(*uuid)
142    }
143}
144
145/// Implements string parsing to create a UUID.
146impl FromStr for UUID {
147    type Err = Error;
148
149    fn from_str(s: &str) -> Result<Self, Self::Err> {
150        let s = s.trim();
151        let s = s.replace('-', "");
152        let bytes = hex::decode(s).unwrap();
153        let mut uuid = [0u8; Self::UUID_SIZE];
154        uuid.copy_from_slice(&bytes);
155        Ok(Self::from_data(uuid))
156    }
157}
bc_components/id/uuid.rs

bc_components/id/
uuid.rs
