bc_components/id/
uuid.rs

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

bc_components/id/
uuid.rs
