icydb_core/db/identity/

mod.rs

//! Module: db::identity
//! Responsibility: validated entity/index naming and stable byte ordering contracts.
//! Does not own: schema metadata, relation policy, or storage-layer persistence.
//! Boundary: all identity construction/decoding for db data/index key domains.
//!
//! Invariants:
//! - Identities are ASCII, non-empty, and bounded by MAX_* limits.
//! - All construction paths validate invariants.
//! - Stored byte representation is canonical and order-preserving.
//! - Ordering semantics follow the length-prefixed stored-byte layout, not
//!   lexicographic string ordering.

#![expect(clippy::cast_possible_truncation)]

#[cfg(test)]
mod tests;

use crate::MAX_INDEX_FIELDS;
use icydb_utils::to_snake_case;
use std::{
    cmp::Ordering,
    fmt::{self, Display},
};

///
/// Constants
///

const MAX_ENTITY_NAME_LEN: usize = 64;
const MAX_INDEX_FIELD_NAME_LEN: usize = 64;
const MAX_INDEX_NAME_PREFIX_LEN: usize = 5;
const MAX_ENTITY_NAME_SLUG_LEN: usize = (MAX_ENTITY_NAME_LEN * 3) / 2;
const MAX_INDEX_FIELD_NAME_SLUG_LEN: usize = (MAX_INDEX_FIELD_NAME_LEN * 3) / 2;
const MAX_INDEX_NAME_LEN: usize = MAX_INDEX_NAME_PREFIX_LEN
    + MAX_ENTITY_NAME_SLUG_LEN
    + 2
    + (MAX_INDEX_FIELDS * MAX_INDEX_FIELD_NAME_SLUG_LEN)
    + (MAX_INDEX_FIELDS - 1);
const INDEX_NAME_SEGMENT_DELIMITER: u8 = b'|';

/// Decode error for persisted identity bytes.
///
/// Owned by the identity layer at storage/corruption boundaries.

#[derive(Debug)]
pub enum IdentityDecodeError {
    /// Persisted byte slice has the wrong fixed envelope size.
    InvalidSize,

    /// Persisted length prefix is empty or exceeds the identity limit.
    InvalidLength,

    /// Identity payload contains non-ASCII bytes.
    NonAscii,

    /// Fixed-width padding contains non-zero bytes.
    NonZeroPadding,

    /// Entity identity payload contains the reserved index segment delimiter.
    Delimiter,
}

/// Admission error for generated entity names.
///
/// Owned by the identity layer before entity names enter stable key formats.

#[derive(Debug)]
pub enum EntityNameError {
    /// Entity name is empty.
    Empty,

    /// Entity name exceeds the stable identity byte limit.
    TooLong { len: usize, max: usize },

    /// Entity name contains non-ASCII bytes.
    NonAscii,

    /// Entity name contains the reserved index segment delimiter.
    Delimiter,
}

/// Admission error for generated index names.
///
/// Owned by the identity layer while deriving index names from an entity and
/// field list.

#[derive(Debug)]
pub enum IndexNameError {
    /// Index field list exceeds the supported key-width limit.
    TooManyFields { len: usize, max: usize },

    /// Index field list is empty.
    NoFields,

    /// One index field segment is empty.
    FieldEmpty,

    /// One index field segment exceeds the stable identity byte limit.
    FieldTooLong { field: String, max: usize },

    /// One index field segment contains non-ASCII bytes.
    FieldNonAscii { field: String },

    /// One index field segment contains the reserved segment delimiter.
    FieldDelimiter { field: String },

    /// Derived index name exceeds the stable identity byte limit.
    TooLong { len: usize, max: usize },
}

/// Validated entity identity with fixed-size persisted representation.
///
/// Used by data-key and index-key domains as canonical entity-name bytes.

#[derive(Clone, Copy, Eq, Hash, PartialEq)]
pub struct EntityName {
    len: u8,
    bytes: [u8; MAX_ENTITY_NAME_LEN],
}

impl EntityName {
    /// Fixed on-disk size in bytes (stable, protocol-level)
    pub const STORED_SIZE_BYTES: u64 = 1 + (MAX_ENTITY_NAME_LEN as u64);

    /// Fixed in-memory size (for buffers and arrays)
    pub const STORED_SIZE_USIZE: usize = Self::STORED_SIZE_BYTES as usize;

    /// Validate and construct an entity name from one ASCII string.
    pub fn try_from_str(name: &str) -> Result<Self, EntityNameError> {
        // Phase 1: validate user-visible identity constraints.
        let bytes = name.as_bytes();
        let len = bytes.len();

        if len == 0 {
            return Err(EntityNameError::Empty);
        }
        if len > MAX_ENTITY_NAME_LEN {
            return Err(EntityNameError::TooLong {
                len,
                max: MAX_ENTITY_NAME_LEN,
            });
        }
        if !bytes.is_ascii() {
            return Err(EntityNameError::NonAscii);
        }
        if bytes.contains(&INDEX_NAME_SEGMENT_DELIMITER) {
            return Err(EntityNameError::Delimiter);
        }

        // Phase 2: write into fixed-size canonical storage.
        let mut out = [0u8; MAX_ENTITY_NAME_LEN];
        out[..len].copy_from_slice(bytes);

        Ok(Self {
            len: len as u8,
            bytes: out,
        })
    }

    /// Return the stored entity-name length.
    #[must_use]
    pub const fn len(&self) -> usize {
        self.len as usize
    }

    /// Return whether the stored entity-name length is zero.
    #[must_use]
    pub const fn is_empty(&self) -> bool {
        self.len() == 0
    }

    /// Borrow raw identity bytes excluding trailing fixed-buffer padding.
    #[must_use]
    pub fn as_bytes(&self) -> &[u8] {
        &self.bytes[..self.len()]
    }

    /// Borrow the entity name as UTF-8 text.
    ///
    /// # Panics
    ///
    /// Panics if the stored entity-name bytes violate the ASCII-only identity
    /// invariant. Construction and decoding are expected to prevent this.
    #[must_use]
    pub fn as_str(&self) -> &str {
        // Invariant: construction and decoding enforce ASCII-only storage,
        // so UTF-8 decoding cannot fail.
        std::str::from_utf8(self.as_bytes()).expect("EntityName invariant: ASCII-only storage")
    }

    /// Encode this identity into its fixed-size persisted representation.
    #[must_use]
    pub fn to_bytes(self) -> [u8; Self::STORED_SIZE_USIZE] {
        let mut out = [0u8; Self::STORED_SIZE_USIZE];
        out[0] = self.len;
        out[1..].copy_from_slice(&self.bytes);
        out
    }

    /// Decode one fixed-size persisted entity identity payload.
    pub fn from_bytes(bytes: &[u8]) -> Result<Self, IdentityDecodeError> {
        // Phase 1: validate layout and payload bounds.
        if bytes.len() != Self::STORED_SIZE_USIZE {
            return Err(IdentityDecodeError::InvalidSize);
        }

        let len = bytes[0] as usize;
        if len == 0 || len > MAX_ENTITY_NAME_LEN {
            return Err(IdentityDecodeError::InvalidLength);
        }
        if !bytes[1..=len].is_ascii() {
            return Err(IdentityDecodeError::NonAscii);
        }
        if bytes[1..=len].contains(&INDEX_NAME_SEGMENT_DELIMITER) {
            return Err(IdentityDecodeError::Delimiter);
        }
        if bytes[1 + len..].iter().any(|&b| b != 0) {
            return Err(IdentityDecodeError::NonZeroPadding);
        }

        // Phase 2: materialize canonical fixed-buffer identity storage.
        let mut name = [0u8; MAX_ENTITY_NAME_LEN];
        name.copy_from_slice(&bytes[1..]);

        Ok(Self {
            len: len as u8,
            bytes: name,
        })
    }
}

impl Ord for EntityName {
    fn cmp(&self, other: &Self) -> Ordering {
        // Keep ordering consistent with `to_bytes()` (length prefix first).
        // This is deterministic protocol/storage ordering, not lexical string order.
        self.len.cmp(&other.len).then(self.bytes.cmp(&other.bytes))
    }
}

impl PartialOrd for EntityName {
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        Some(self.cmp(other))
    }
}

impl Display for EntityName {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.as_str())
    }
}

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

/// Validated index identity with fixed-size persisted representation.
///
/// Used by index-store key domains as canonical index-name bytes.

#[derive(Clone, Copy, Eq, Hash, PartialEq)]
pub struct IndexName {
    len: u16,
    bytes: [u8; MAX_INDEX_NAME_LEN],
}

impl IndexName {
    /// Fixed on-disk size in bytes (stable, protocol-level).
    pub const STORED_SIZE_BYTES: u64 = 2 + (MAX_INDEX_NAME_LEN as u64);
    /// Fixed in-memory size (for buffers and arrays).
    pub const STORED_SIZE_USIZE: usize = Self::STORED_SIZE_BYTES as usize;

    /// Validate and construct one non-unique index identity from an entity +
    /// field list.
    pub fn try_from_entity_fields(
        entity: &EntityName,
        fields: &[&str],
    ) -> Result<Self, IndexNameError> {
        Self::try_from_entity_fields_with_prefix("idx", entity, fields)
    }

    /// Validate and construct one unique index identity from an entity + field
    /// list.
    pub fn try_unique_from_entity_fields(
        entity: &EntityName,
        fields: &[&str],
    ) -> Result<Self, IndexNameError> {
        Self::try_from_entity_fields_with_prefix("uniq", entity, fields)
    }

    fn try_from_entity_fields_with_prefix(
        prefix: &str,
        entity: &EntityName,
        fields: &[&str],
    ) -> Result<Self, IndexNameError> {
        // Phase 1: validate index-field count and per-field identity constraints.
        if fields.is_empty() {
            return Err(IndexNameError::NoFields);
        }
        if fields.len() > MAX_INDEX_FIELDS {
            return Err(IndexNameError::TooManyFields {
                len: fields.len(),
                max: MAX_INDEX_FIELDS,
            });
        }

        let mut field_slugs = Vec::with_capacity(fields.len());
        for field in fields {
            let field_len = field.len();
            if field_len == 0 {
                return Err(IndexNameError::FieldEmpty);
            }
            if field_len > MAX_INDEX_FIELD_NAME_LEN {
                return Err(IndexNameError::FieldTooLong {
                    field: (*field).to_string(),
                    max: MAX_INDEX_FIELD_NAME_LEN,
                });
            }
            if !field.is_ascii() {
                return Err(IndexNameError::FieldNonAscii {
                    field: (*field).to_string(),
                });
            }
            if field.as_bytes().contains(&INDEX_NAME_SEGMENT_DELIMITER) {
                return Err(IndexNameError::FieldDelimiter {
                    field: (*field).to_string(),
                });
            }
            let slug = index_name_slug(field);
            if slug.is_empty() {
                return Err(IndexNameError::FieldEmpty);
            }
            field_slugs.push(slug);
        }

        let entity_slug = index_name_slug(entity.as_str());
        let total_len = prefix
            .len()
            .saturating_add(1)
            .saturating_add(entity_slug.len())
            .saturating_add(2)
            .saturating_add(field_slugs.iter().map(String::len).sum::<usize>())
            .saturating_add(field_slugs.len().saturating_sub(1));
        if total_len > MAX_INDEX_NAME_LEN {
            return Err(IndexNameError::TooLong {
                len: total_len,
                max: MAX_INDEX_NAME_LEN,
            });
        }

        // Phase 2: encode canonical `idx_entity__field...` bytes into fixed storage.
        let mut out = [0u8; MAX_INDEX_NAME_LEN];
        let mut len = 0usize;

        Self::push_bytes(&mut out, &mut len, prefix.as_bytes());
        Self::push_bytes(&mut out, &mut len, b"_");
        Self::push_bytes(&mut out, &mut len, entity_slug.as_bytes());
        Self::push_bytes(&mut out, &mut len, b"__");
        for (index, field_slug) in field_slugs.iter().enumerate() {
            if index > 0 {
                Self::push_bytes(&mut out, &mut len, b"_");
            }
            Self::push_bytes(&mut out, &mut len, field_slug.as_bytes());
        }

        Ok(Self {
            len: len as u16,
            bytes: out,
        })
    }

    /// Borrow raw index-identity bytes excluding trailing fixed-buffer padding.
    #[must_use]
    pub fn as_bytes(&self) -> &[u8] {
        &self.bytes[..self.len as usize]
    }

    /// Borrow the index identity as UTF-8 text.
    ///
    /// # Panics
    ///
    /// Panics if the stored index-name bytes violate the ASCII-only identity
    /// invariant. Construction and decoding are expected to prevent this.
    #[must_use]
    pub fn as_str(&self) -> &str {
        // Invariant: construction and decoding enforce ASCII-only storage,
        // so UTF-8 decoding cannot fail.
        std::str::from_utf8(self.as_bytes()).expect("IndexName invariant: ASCII-only storage")
    }

    /// Encode this identity into its fixed-size persisted representation.
    #[must_use]
    pub fn to_bytes(self) -> [u8; Self::STORED_SIZE_USIZE] {
        let mut out = [0u8; Self::STORED_SIZE_USIZE];
        out[..2].copy_from_slice(&self.len.to_be_bytes());
        out[2..].copy_from_slice(&self.bytes);
        out
    }

    /// Decode one fixed-size persisted index identity payload.
    ///
    /// This validates the canonical fixed-width byte envelope only. It does not
    /// reconstruct field segments or prove the bytes were produced by
    /// `try_from_entity_fields`; callers must ensure persisted bytes originate from a
    /// previously validated `IndexName`.
    pub fn from_bytes(bytes: &[u8]) -> Result<Self, IdentityDecodeError> {
        // Phase 1: validate layout and payload bounds.
        if bytes.len() != Self::STORED_SIZE_USIZE {
            return Err(IdentityDecodeError::InvalidSize);
        }

        let len = u16::from_be_bytes([bytes[0], bytes[1]]) as usize;
        if len == 0 || len > MAX_INDEX_NAME_LEN {
            return Err(IdentityDecodeError::InvalidLength);
        }
        if !bytes[2..2 + len].is_ascii() {
            return Err(IdentityDecodeError::NonAscii);
        }
        if bytes[2 + len..].iter().any(|&b| b != 0) {
            return Err(IdentityDecodeError::NonZeroPadding);
        }

        // Phase 2: materialize canonical fixed-buffer identity storage.
        let mut name = [0u8; MAX_INDEX_NAME_LEN];
        name.copy_from_slice(&bytes[2..]);

        Ok(Self {
            len: len as u16,
            bytes: name,
        })
    }

    // Append bytes into the fixed-size identity buffer while tracking write offset.
    fn push_bytes(out: &mut [u8; MAX_INDEX_NAME_LEN], len: &mut usize, bytes: &[u8]) {
        let end = *len + bytes.len();
        out[*len..end].copy_from_slice(bytes);
        *len = end;
    }
}

fn index_name_slug(value: &str) -> String {
    let separated = value
        .chars()
        .map(|ch| if ch.is_ascii_alphanumeric() { ch } else { '_' })
        .collect::<String>();

    to_snake_case(separated.as_str())
}

impl Ord for IndexName {
    fn cmp(&self, other: &Self) -> Ordering {
        self.to_bytes().cmp(&other.to_bytes())
    }
}

impl PartialOrd for IndexName {
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        Some(self.cmp(other))
    }
}

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

impl Display for IndexName {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.as_str())
    }
}