up_rust/

uuid.rs

/********************************************************************************
 * Copyright (c) 2023 Contributors to the Eclipse Foundation
 *
 * See the NOTICE file(s) distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Apache License Version 2.0 which is available at
 * https://www.apache.org/licenses/LICENSE-2.0
 *
 * SPDX-License-Identifier: Apache-2.0
 ********************************************************************************/

use std::time::{Duration, SystemTime};
use std::{hash::Hash, str::FromStr};

use bytes::{Buf, Bytes};
use rand::Rng;
use uuid_simd::{AsciiCase, Out};

const BITMASK_VERSION: u64 = 0b1111 << 12;
const VERSION_7: u64 = 0b0111 << 12;
const BITMASK_VARIANT: u64 = 0b11 << 62;
const VARIANT_RFC4122: u64 = 0b10 << 62;

fn is_correct_version(msb: u64) -> bool {
    msb & BITMASK_VERSION == VERSION_7
}

fn is_correct_variant(lsb: u64) -> bool {
    lsb & BITMASK_VARIANT == VARIANT_RFC4122
}

#[derive(Debug)]
pub struct UuidConversionError {
    message: String,
}

impl UuidConversionError {
    pub fn new<T: Into<String>>(message: T) -> UuidConversionError {
        UuidConversionError {
            message: message.into(),
        }
    }
}

impl std::fmt::Display for UuidConversionError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Error converting UUID: {}", self.message)
    }
}

impl std::error::Error for UuidConversionError {}

#[derive(Debug, Clone, PartialEq)]
#[repr(C)]
/// A uProtocol UUIDv7 message identifier (RFC 9562 layout).
pub struct UUID {
    msb: u64,
    lsb: u64,
}

impl std::fmt::Display for UUID {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.to_hyphenated_string())
    }
}

impl UUID {
    /// Creates a new UUID from a byte array.
    ///
    /// # Arguments
    ///
    /// `bytes` - the byte array
    ///
    /// # Returns
    ///
    /// a uProtocol [`UUID`] with the given timestamp and random values.
    ///
    /// # Errors
    ///
    /// Returns an error if the given bytes contain an invalid version and/or variant identifier.
    pub fn from_bytes(bytes: &[u8; 16]) -> Result<Self, UuidConversionError> {
        let mut msb = [0_u8; 8];
        let mut lsb = [0_u8; 8];
        msb.copy_from_slice(&bytes[..8]);
        lsb.copy_from_slice(&bytes[8..]);
        Self::from_u64_pair(u64::from_be_bytes(msb), u64::from_be_bytes(lsb))
    }

    /// Creates a new UUID from a high/low value pair.
    ///
    /// NOTE: This function does *not* check if the given bytes represent a
    ///       [valid uProtocol UUID](Self::is_uprotocol_uuid).
    ///       It should therefore only be used in cases where the bytes passed in are known to be valid.
    ///
    /// # Arguments
    ///
    /// `msb` - the most significant 8 bytes
    /// `lsb` - the least significant 8 bytes
    ///
    /// # Returns
    ///
    /// a uProtocol [`UUID`] with the given timestamp and random values.
    pub(crate) fn from_bytes_unchecked(msb: [u8; 8], lsb: [u8; 8]) -> Self {
        UUID {
            msb: u64::from_be_bytes(msb),
            lsb: u64::from_be_bytes(lsb),
        }
    }

    /// Creates a new UUID from a high/low value pair.
    ///
    /// # Arguments
    ///
    /// `msb` - the most significant 8 bytes
    /// `lsb` - the least significant 8 bytes
    ///
    /// # Returns
    ///
    /// a uProtocol [`UUID`] with the given timestamp and random values.
    ///
    /// # Errors
    ///
    /// Returns an error if the given bytes contain an invalid version and/or variant identifier.
    // [impl->dsn~uuid-spec~1]
    pub fn from_u64_pair(msb: u64, lsb: u64) -> Result<Self, UuidConversionError> {
        if !is_correct_version(msb) {
            return Err(UuidConversionError::new("not a v7 UUID"));
        }
        if !is_correct_variant(lsb) {
            return Err(UuidConversionError::new("not an RFC4122 UUID"));
        }
        Ok(UUID { msb, lsb })
    }

    /// Gets this UUID as a pair of 64 bit integers.
    ///
    /// # Returns
    ///
    /// A tuple of the most significant and least significant 8 bytes,
    /// i.e. the inverse of [`UUID::from_u64_pair`].
    #[must_use]
    pub fn as_u64_pair(&self) -> (u64, u64) {
        (self.msb, self.lsb)
    }

    // [impl->dsn~uuid-spec~1]
    pub(crate) fn build_for_timestamp(duration_since_unix_epoch: Duration) -> UUID {
        let timestamp_millis = u64::try_from(duration_since_unix_epoch.as_millis())
            .expect("system time is set to a time too far in the future");
        Self::build_for_timestamp_millis(timestamp_millis)
    }

    // [impl->dsn~uuid-spec~1]
    pub(crate) fn build_for_timestamp_millis(timestamp_millis: u64) -> UUID {
        // fill upper 48 bits with timestamp
        let mut msb = (timestamp_millis << 16).to_be_bytes();
        // fill remaining bits with random bits
        rand::rng().fill_bytes(&mut msb[6..]);
        // set version (7)
        msb[6] = msb[6] & 0b00001111 | 0b01110000;

        let mut lsb = [0u8; 8];
        // fill lsb with random bits
        rand::rng().fill_bytes(&mut lsb);
        // set variant (RFC4122)
        lsb[0] = lsb[0] & 0b00111111 | 0b10000000;
        Self::from_bytes_unchecked(msb, lsb)
    }

    /// Creates a new UUID that can be used for uProtocol messages.
    ///
    /// # Panics
    ///
    /// if the system clock is set to an instant before the UNIX Epoch.
    ///
    /// # Examples
    ///
    /// ```
    /// use std::time::SystemTime;
    /// use up_rust::UUID;
    ///
    /// let uuid = UUID::build();
    /// assert!(uuid.time() <= SystemTime::now()
    ///     .duration_since(SystemTime::UNIX_EPOCH)
    ///     .expect("current system time is set to a point in time before UNIX Epoch")
    ///     .as_millis() as u64);
    /// ```
    // [impl->dsn~uuid-spec~1]
    // [utest->dsn~uuid-spec~1]
    #[must_use]
    pub fn build() -> UUID {
        let duration_since_unix_epoch = SystemTime::UNIX_EPOCH
            .elapsed()
            .expect("current system time is set to a point in time before UNIX Epoch");
        Self::build_for_timestamp(duration_since_unix_epoch)
    }

    /// Serializes this UUID to a hyphenated string as defined by
    /// [RFC 4122, Section 3](https://www.rfc-editor.org/rfc/rfc4122.html#section-3)
    /// using lower case characters.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use up_rust::UUID;
    ///
    /// // timestamp = 1, ver = 0b0111
    /// let msb = 0x0000000000017000_u64;
    /// // variant = 0b10, random = 0x0010101010101a1a
    /// let lsb = 0x8010101010101a1a_u64;
    /// let uuid = UUID::from_u64_pair(msb, lsb).unwrap();
    /// assert_eq!(uuid.to_hyphenated_string(), "00000000-0001-7000-8010-101010101a1a");
    /// ```
    // [impl->req~uuid-hex-and-dash~1]
    #[must_use]
    pub fn to_hyphenated_string(&self) -> String {
        let mut bytes = [0_u8; 16];
        bytes[..8].clone_from_slice(self.msb.to_be_bytes().as_slice());
        bytes[8..].clone_from_slice(self.lsb.to_be_bytes().as_slice());
        let mut out_bytes = [0_u8; 36];
        let out =
            uuid_simd::format_hyphenated(&bytes, Out::from_mut(&mut out_bytes), AsciiCase::Lower);
        String::from_utf8(out.to_vec()).unwrap()
    }

    /// Returns the point in time that this UUID has been created at.
    ///
    /// # Returns
    ///
    /// The number of milliseconds since UNIX EPOCH.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use up_rust::UUID;
    ///
    /// // timestamp = 0x018D548EA8E0 (Monday, 29 January 2024, 9:30:52 AM GMT)
    /// // ver = 0b0111
    /// let msb = 0x018D548EA8E07000u64;
    /// // variant = 0b10
    /// let lsb = 0x8000000000000000u64;
    /// let creation_time = UUID::from_u64_pair(msb, lsb).unwrap().time();
    /// assert_eq!(creation_time, 0x018D548EA8E0_u64);
    /// ```
    // [impl->dsn~uuid-spec~1]
    // [utest->dsn~uuid-spec~1]
    #[must_use]
    pub fn time(&self) -> u64 {
        // the timestamp is contained in the 48 most significant bits
        self.msb >> 16
    }
    /// Deprecated alias for [`Self::time`].
    #[deprecated(since = "0.11.0", note = "renamed to `time`")]
    pub fn get_time(&self) -> u64 {
        self.time()
    }
}

#[cfg(feature = "up-core-api")]
mod core_types_support {
    use super::*;
    use crate::up_core_api::uuid::UUID as UUIDProto;
    use crate::ProtobufMappable;
    use protobuf::{well_known_types::any::Any, Message};

    impl TryFrom<&UUIDProto> for UUID {
        type Error = UuidConversionError;

        fn try_from(value: &UUIDProto) -> Result<Self, Self::Error> {
            UUID::from_u64_pair(value.msb, value.lsb)
        }
    }

    impl TryFrom<UUIDProto> for UUID {
        type Error = UuidConversionError;

        fn try_from(value: UUIDProto) -> Result<Self, Self::Error> {
            Self::try_from(&value)
        }
    }

    impl From<&UUID> for UUIDProto {
        fn from(value: &UUID) -> Self {
            UUIDProto {
                msb: value.msb,
                lsb: value.lsb,
                ..Default::default()
            }
        }
    }

    impl ProtobufMappable for UUID {
        fn parse_from_protobuf_bytes(proto: &[u8]) -> Result<Self, crate::SerializationError> {
            let uuid_proto = UUIDProto::parse_from_bytes(proto)
                .map_err(|err| crate::SerializationError::new(err.to_string()))?;
            UUID::try_from(uuid_proto)
                .map_err(|err| crate::SerializationError::new(err.to_string()))
        }

        fn parse_from_packed_protobuf_bytes(
            proto: &[u8],
        ) -> Result<Self, crate::SerializationError> {
            Any::parse_from_bytes(proto)
                .map_err(|err| crate::SerializationError::new(err.to_string()))
                .and_then(|any| match any.unpack::<UUIDProto>() {
                    Ok(Some(v)) => UUID::try_from(v)
                        .map_err(|err| crate::SerializationError::new(err.to_string())),
                    Ok(None) => Err(crate::SerializationError::new(
                        "cannot unpack UUID, type mismatch",
                    )),
                    Err(e) => Err(crate::SerializationError::from(e)),
                })
        }

        fn write_to_protobuf_bytes(&self) -> Result<Vec<u8>, crate::SerializationError> {
            UUIDProto::from(self)
                .write_to_bytes()
                .map_err(|err| crate::SerializationError::new(err.to_string()))
        }

        fn write_to_packed_protobuf_bytes(&self) -> Result<Vec<u8>, crate::SerializationError> {
            Any::pack(&UUIDProto::from(self))
                .map_err(|err| {
                    crate::SerializationError::new(format!("Failed to pack UUID: {err}"))
                })
                .and_then(|any| any.write_to_protobuf_bytes())
        }
    }
}

impl Eq for UUID {}

impl Hash for UUID {
    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
        let bytes = (self.msb, self.lsb);
        bytes.hash(state)
    }
}

impl TryFrom<Vec<u8>> for UUID {
    type Error = UuidConversionError;

    /// Creates a UUID from a byte vector.
    ///
    /// # Arguments
    ///
    /// `value` - the byte vector
    ///
    /// # Returns
    ///
    /// a uProtocol UUID with the given timestamp and random values.
    ///
    /// # Errors
    ///
    /// Returns an error
    /// * if the given vector does not have a length of 16 bytes, or
    /// * if the given bytes contain an invalid version and/or variant identifier.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use up_rust::UUID;
    ///
    /// // timestamp = 1, ver = 0b0111, variant = 0b10
    /// let bytes: Vec<u8> = vec![
    ///     0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x70, 0x00,
    ///     0x80, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    /// ];
    /// let conversion_attempt = UUID::try_from(bytes);
    /// assert!(conversion_attempt.is_ok());
    /// let uuid = conversion_attempt.unwrap();
    /// assert_eq!(uuid.time(), 0x1_u64);
    /// ```
    fn try_from(value: Vec<u8>) -> Result<Self, Self::Error> {
        let mut buf: Bytes = value.into();
        if buf.len() != 16 {
            return Err(UuidConversionError::new(
                "byte vector length is not 16 bytes",
            ));
        }
        UUID::from_u64_pair(buf.get_u64(), buf.get_u64())
    }
}

impl From<UUID> for Vec<u8> {
    fn from(value: UUID) -> Self {
        Self::from(&value)
    }
}

impl From<&UUID> for Vec<u8> {
    /// Serializes this UUID to a byte vector.
    ///
    /// # Returns
    ///
    /// a byte vector containing the 16 bytes of this UUID in big-endian order.
    ///
    /// # Examples
    ////
    /// ```rust
    /// use up_rust::UUID;
    ///
    /// // timestamp = 1, ver = 0b0111
    /// let msb = 0x0000000000017000_u64;
    /// // variant = 0b10, random = 0x0010101010101a1a
    /// let lsb = 0x8010101010101a1a_u64;
    /// let uuid = UUID::from_u64_pair(msb, lsb).unwrap();
    /// let bytes: Vec<u8> = uuid.into();
    /// assert_eq!(bytes, vec![
    ///     0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x70, 0x00,
    ///     0x80, 0x10, 0x10, 0x10, 0x10, 0x10, 0x1a, 0x1a,
    /// ]);
    /// ```
    fn from(value: &UUID) -> Self {
        let mut bytes = Vec::with_capacity(16);
        bytes.extend_from_slice(&value.msb.to_be_bytes());
        bytes.extend_from_slice(&value.lsb.to_be_bytes());
        bytes
    }
}

impl From<UUID> for String {
    fn from(value: UUID) -> Self {
        Self::from(&value)
    }
}

impl From<&UUID> for String {
    fn from(value: &UUID) -> Self {
        value.to_hyphenated_string()
    }
}

impl FromStr for UUID {
    type Err = UuidConversionError;

    /// Parses a string into a UUID.
    ///
    /// # Returns
    ///
    /// a uProtocol [`UUID`] based on the bytes encoded in the string.
    ///
    /// # Errors
    ///
    /// Returns an error
    /// * if the given string does not represent a UUID as defined by
    ///   [RFC 4122, Section 3](https://www.rfc-editor.org/rfc/rfc4122.html#section-3), or
    /// * if the bytes encoded in the string contain an invalid version and/or variant identifier.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use up_rust::UUID;
    ///
    /// // parsing a valid uProtocol UUID succeeds
    /// let parsing_attempt = "00000000-0001-7000-8010-101010101a1A".parse::<UUID>();
    /// assert!(parsing_attempt.is_ok());
    ///
    /// // parsing an invalid UUID fails
    /// assert!("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8"
    ///     .parse::<UUID>()
    ///     .is_err());
    ///
    /// // parsing a string that is not a UUID fails
    /// assert!("this-is-not-a-UUID"
    ///     .parse::<UUID>()
    ///     .is_err());
    /// ```
    // [impl->req~uuid-hex-and-dash~1]
    fn from_str(uuid_str: &str) -> Result<Self, Self::Err> {
        let mut uuid = [0u8; 16];
        uuid_simd::parse_hyphenated(uuid_str.as_bytes(), Out::from_mut(&mut uuid))
            .map_err(|err| UuidConversionError::new(err.to_string()))
            .and_then(|bytes| UUID::from_bytes(bytes))
    }
}

#[cfg(test)]
mod tests {

    use super::*;

    // [utest->dsn~uuid-spec~1]
    // [utest->req~uuid-type~1]
    #[test]
    fn test_from_u64_pair() {
        // timestamp = 1, ver = 0b0111
        let msb = 0x0000000000017000_u64;
        // variant = 0b10
        let lsb = 0x8000000000000000_u64;
        let conversion_attempt = UUID::from_u64_pair(msb, lsb);
        assert!(conversion_attempt
            .is_ok_and(|uuid| { uuid.time() == 0x1_u64 && uuid.msb == msb && uuid.lsb == lsb }));

        // timestamp = 1, (invalid) ver = 0b0000
        let msb = 0x0000000000010000_u64;
        // variant= 0b10
        let lsb = 0x80000000000000ab_u64;
        assert!(UUID::from_u64_pair(msb, lsb).is_err());

        // timestamp = 1, ver = 0b0111
        let msb = 0x0000000000017000_u64;
        // (invalid) variant= 0b00
        let lsb = 0x00000000000000ab_u64;
        assert!(UUID::from_u64_pair(msb, lsb).is_err());
    }

    // [utest->dsn~uuid-spec~1]
    #[test]
    fn test_from_bytes() {
        // timestamp = 1, ver = 0b0111, variant = 0b10
        let bytes: [u8; 16] = [
            0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x70, 0x00, 0x80, 0x00, 0x00, 0x00, 0x00, 0x00,
            0x00, 0x00,
        ];
        let conversion_attempt = UUID::from_bytes(&bytes);
        assert!(conversion_attempt.is_ok());
        let uuid = conversion_attempt.unwrap();
        assert_eq!(uuid.time(), 0x1_u64);
    }

    #[test]
    fn test_try_from_vec_fails() {
        // not 16 bytes
        let bytes: Vec<u8> = vec![0x00, 0x00, 0x00, 0x00];
        assert!(UUID::try_from(bytes).is_err());
    }

    #[test]
    // [utest->req~uuid-hex-and-dash~1]
    fn test_into_string() {
        // timestamp = 1, ver = 0b0111
        let msb = 0x0000000000017000_u64;
        // variant = 0b10, random = 0x0010101010101a1a
        let lsb = 0x8010101010101a1a_u64;
        let uuid = UUID { msb, lsb };

        assert_eq!(String::from(&uuid), "00000000-0001-7000-8010-101010101a1a");
        assert_eq!(String::from(uuid), "00000000-0001-7000-8010-101010101a1a");
    }
}