khive_types/

id.rs

//! 128-bit identifier — wire format is canonical hyphenated UUID, nil sentinel at all-zeros.

// REASON: `manual_range_contains` fires on the `b'0'..=b'9'` byte-range matches
// in `hex_val`. The range-contains form (`c >= b'0' && c <= b'9'`) is less
// readable for byte-literal matching and offers no correctness benefit here.
#![allow(clippy::manual_range_contains)]

use core::fmt;
use core::str::FromStr;

/// Return whether every byte is an ASCII digit or a lowercase hexadecimal letter.
///
/// The empty string returns `true`; callers retain their own length requirements.
#[inline]
pub fn is_lowercase_hex(value: &str) -> bool {
    value
        .bytes()
        .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
}

/// A 128-bit opaque identifier stored as 16 bytes, formatted as a hyphenated UUID string.
#[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct Id128([u8; 16]);

impl Id128 {
    /// The all-zeros nil identifier, used as a sentinel for "no record".
    pub const NIL: Self = Self([0; 16]);

    /// Construct an `Id128` from its raw 16-byte representation.
    #[inline]
    pub const fn from_bytes(bytes: [u8; 16]) -> Self {
        Self(bytes)
    }

    /// Return a reference to the underlying 16-byte array.
    #[inline]
    pub const fn as_bytes(&self) -> &[u8; 16] {
        &self.0
    }

    /// Return `true` if all 16 bytes are zero (the nil sentinel).
    #[inline]
    pub const fn is_nil(&self) -> bool {
        let b = &self.0;
        let mut i = 0;
        while i < 16 {
            if b[i] != 0 {
                return false;
            }
            i += 1;
        }
        true
    }

    /// Construct an `Id128` from a `u128` in big-endian byte order.
    #[inline]
    pub const fn from_u128(v: u128) -> Self {
        Self(v.to_be_bytes())
    }

    /// Convert the identifier back to its `u128` big-endian representation.
    #[inline]
    pub const fn to_u128(&self) -> u128 {
        u128::from_be_bytes(self.0)
    }
}

const HEX_CHARS: &[u8; 16] = b"0123456789abcdef";

impl fmt::Display for Id128 {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let b = &self.0;
        let mut buf = [0u8; 36];
        let mut pos = 0;

        // Groups: 4 bytes, 2 bytes, 2 bytes, 2 bytes, 6 bytes
        let groups: &[(usize, usize)] = &[(0, 4), (4, 6), (6, 8), (8, 10), (10, 16)];
        for (gi, &(start, end)) in groups.iter().enumerate() {
            if gi > 0 {
                buf[pos] = b'-';
                pos += 1;
            }
            for i in start..end {
                buf[pos] = HEX_CHARS[(b[i] >> 4) as usize];
                buf[pos + 1] = HEX_CHARS[(b[i] & 0x0f) as usize];
                pos += 2;
            }
        }
        f.write_str(core::str::from_utf8(&buf[..pos]).expect("hex chars are valid utf8"))
    }
}

impl fmt::Debug for Id128 {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "Id128({self})")
    }
}

/// Error returned when an `Id128` string cannot be parsed.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ParseIdError {
    /// The input was not 32 hex chars or 36 chars with hyphens.
    InvalidLength,
    /// The input contained a character that is not a valid hex digit.
    InvalidHex,
}

impl ParseIdError {
    /// Exact `Display` text for [`ParseIdError::InvalidLength`].
    ///
    /// Callers that classify parse failures by message text (e.g. the
    /// `propose` changeset error-shape split) match on this constant rather
    /// than on prose heuristics. The pinning test in this module fails loudly
    /// if the wording ever changes.
    pub const INVALID_LENGTH_TEXT: &'static str = "expected UUID: 32 hex chars or 36 with hyphens";

    /// Exact `Display` text for [`ParseIdError::InvalidHex`]. See
    /// [`ParseIdError::INVALID_LENGTH_TEXT`] for the matching contract.
    pub const INVALID_HEX_TEXT: &'static str = "invalid hex character in UUID";
}

impl fmt::Display for ParseIdError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::InvalidLength => f.write_str(Self::INVALID_LENGTH_TEXT),
            Self::InvalidHex => f.write_str(Self::INVALID_HEX_TEXT),
        }
    }
}

#[cfg(feature = "std")]
impl std::error::Error for ParseIdError {}

fn hex_val(c: u8) -> Option<u8> {
    match c {
        b'0'..=b'9' => Some(c - b'0'),
        b'a'..=b'f' => Some(c - b'a' + 10),
        b'A'..=b'F' => Some(c - b'A' + 10),
        _ => None,
    }
}

fn parse_hex_bytes(hex: &[u8]) -> Result<[u8; 16], ParseIdError> {
    if hex.len() != 32 {
        return Err(ParseIdError::InvalidLength);
    }
    let mut bytes = [0u8; 16];
    for i in 0..16 {
        let hi = hex_val(hex[i * 2]).ok_or(ParseIdError::InvalidHex)?;
        let lo = hex_val(hex[i * 2 + 1]).ok_or(ParseIdError::InvalidHex)?;
        bytes[i] = (hi << 4) | lo;
    }
    Ok(bytes)
}

impl FromStr for Id128 {
    type Err = ParseIdError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let b = s.as_bytes();
        match b.len() {
            32 => Ok(Self(parse_hex_bytes(b)?)),
            36 => {
                // Strip hyphens at positions 8, 13, 18, 23
                if b[8] != b'-' || b[13] != b'-' || b[18] != b'-' || b[23] != b'-' {
                    return Err(ParseIdError::InvalidHex);
                }
                let mut hex = [0u8; 32];
                hex[..8].copy_from_slice(&b[..8]);
                hex[8..12].copy_from_slice(&b[9..13]);
                hex[12..16].copy_from_slice(&b[14..18]);
                hex[16..20].copy_from_slice(&b[19..23]);
                hex[20..32].copy_from_slice(&b[24..36]);
                Ok(Self(parse_hex_bytes(&hex)?))
            }
            _ => Err(ParseIdError::InvalidLength),
        }
    }
}

impl Default for Id128 {
    #[inline]
    fn default() -> Self {
        Self::NIL
    }
}

#[cfg(feature = "serde")]
impl serde::Serialize for Id128 {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        use alloc::string::ToString;
        serializer.serialize_str(&self.to_string())
    }
}

#[cfg(feature = "serde")]
impl<'de> serde::Deserialize<'de> for Id128 {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        // Deserialize into owned String so this works when the deserializer
        // holds owned data (e.g. serde_json::Value) and cannot lend a &str.
        let s = alloc::string::String::deserialize(deserializer)?;
        s.parse().map_err(serde::de::Error::custom)
    }
}

#[cfg(test)]
#[path = "id_tests.rs"]
mod tests;