reliar-core 0.3.0

//! Identity newtypes shared by every envelope (ADR 0011, ADR 0015).

use core::fmt;

use uuid::Uuid;

/// Validation failures shared by every capped string identity newtype in `reliar-core`.
///
/// ```
/// use reliar_core::{CorrelationId, IdError};
///
/// let err = CorrelationId::parse("").unwrap_err();
/// assert_eq!(err, IdError::Empty);
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum IdError {
    /// The value was empty.
    Empty,

    /// The value exceeded its type's maximum length.
    TooLong {
        /// The value's actual length in bytes.
        len: usize,
        /// The maximum allowed length in bytes.
        max: usize,
    },

    /// The value contained a control character (including CR/LF) — a header-injection
    /// surface once a mapper writes this value onto the wire.
    ControlCharacter,
}

impl fmt::Display for IdError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Empty => f.write_str("value must not be empty"),
            Self::TooLong { len, max } => {
                write!(f, "value length {len} exceeds the maximum of {max}")
            }
            Self::ControlCharacter => f.write_str("value must not contain a control character"),
        }
    }
}

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

/// Shared by every capped string identity newtype (and [`crate::Headers`]): `true` if `s`
/// contains a control character (including CR/LF), which would let a value smuggle extra
/// header/line-oriented content onto the wire once a transport mapper writes it verbatim.
///
/// `char::is_control` matches Unicode category `Cc` (`U+0000..=U+001F`, `U+007F`,
/// `U+0080..=U+009F`) — exactly the code points a line-oriented wire format (an HTTP-style
/// header, a CSV row) treats specially. It is deliberately not a wider "non-printable" or
/// "non-ASCII" check: rejecting e.g. combining marks or emoji would reject legitimate
/// human-readable data this type has no reason to forbid.
pub(crate) fn contains_control_char(s: &str) -> bool {
    s.chars().any(char::is_control)
}

/// Declares a UUID-backed identity newtype: `Clone + Copy + Debug + Eq + Hash + Ord`, `from_uuid`/
/// `as_uuid`, and a `Display` that renders the inner UUID verbatim. Every one Reliar generates is
/// `UUIDv7` (ADR 0015); applications may supply any UUID and Reliar SHALL NOT inspect or reject
/// its version.
///
/// The bare form (`uuid_id!($name)`) additionally mints: a `new()` that generates a fresh
/// `UUIDv7` and a `Default` built on it. That half is for ids Reliar itself originates
/// (`MessageId`). An id that is always **derived** from another value (`ConversationId`, rooted
/// at the envelope's message id) or always **host-supplied** (`RequestId`, read off the inbound
/// request) opts out with `uuid_id!($name, no_mint)` — there is no constructor that hands back a
/// value nobody asked for (ADR 0038).
macro_rules! uuid_id {
    ($(#[$meta:meta])* $name:ident) => {
        uuid_id!(@base $(#[$meta])* $name);
        uuid_id!(@mint $name);
    };
    ($(#[$meta:meta])* $name:ident, no_mint) => {
        uuid_id!(@base $(#[$meta])* $name);
    };
    (@base $(#[$meta:meta])* $name:ident) => {
        $(#[$meta])*
        #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
        pub struct $name(Uuid);

        impl $name {
            /// Wraps an existing UUID without inspecting or rejecting its version.
            ///
            /// ```
            /// // Illustrative for every id type this macro declares.
            /// use reliar_core::MessageId;
            /// use uuid::Uuid;
            ///
            /// let raw = Uuid::now_v7();
            /// assert_eq!(MessageId::from_uuid(raw).as_uuid(), raw);
            /// ```
            #[must_use]
            pub const fn from_uuid(id: Uuid) -> Self {
                Self(id)
            }

            /// Returns the inner UUID.
            ///
            /// ```
            /// // Illustrative for every id type this macro declares.
            /// use reliar_core::MessageId;
            /// use uuid::Uuid;
            ///
            /// let raw = Uuid::now_v7();
            /// assert_eq!(MessageId::from_uuid(raw).as_uuid(), raw);
            /// ```
            #[must_use]
            pub const fn as_uuid(&self) -> Uuid {
                self.0
            }
        }

        impl fmt::Display for $name {
            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
                fmt::Display::fmt(&self.0, f)
            }
        }
    };
    (@mint $name:ident) => {
        impl $name {
            /// Generates a fresh `UUIDv7` id.
            ///
            /// ```
            /// // Illustrative for every id type this macro mints.
            /// use reliar_core::MessageId;
            ///
            /// let id = MessageId::new();
            /// assert!(!id.as_uuid().is_nil());
            /// ```
            #[must_use]
            pub fn new() -> Self {
                Self(Uuid::now_v7())
            }
        }

        impl Default for $name {
            fn default() -> Self {
                Self::new()
            }
        }
    };
}

uuid_id!(
    /// Uniquely identifies one envelope end-to-end: enqueue, storage row, wire message, and,
    /// if it fails permanently, the dead entry.
    ///
    /// ```
    /// use reliar_core::MessageId;
    ///
    /// // Every id Reliar mints is a fresh UUIDv7 — monotonic-ish and time-ordered.
    /// let id = MessageId::new();
    /// assert_eq!(id, MessageId::from_uuid(id.as_uuid()));
    /// ```
    MessageId
);
uuid_id!(
    /// Groups every message in one business conversation. Always **derived**, never minted: an
    /// un-correlated message roots its own conversation at its [`MessageId`] (see
    /// [`crate::EnvelopeBuilder::build`]), and any other value is inherited from storage or the
    /// wire via [`Self::from_uuid`]. There is deliberately no `new()`/`Default` — a random,
    /// unrooted conversation id would silently drop a caller out of the conversation it supplied
    /// (ADR 0038); a host that wants to start one names the UUID explicitly.
    ///
    /// ```
    /// use reliar_core::ConversationId;
    /// use uuid::Uuid;
    ///
    /// // Wrap an id read back from storage or the wire without inspecting its version.
    /// let existing = Uuid::now_v7();
    /// let conversation = ConversationId::from_uuid(existing);
    /// assert_eq!(conversation.as_uuid(), existing);
    /// assert!(!conversation.is_unset());
    /// ```
    ConversationId,
    no_mint
);
uuid_id!(
    /// Correlates an envelope back to the inbound request (HTTP call, RPC, CLI invocation) that
    /// caused it, so an outbound message can be traced to its trigger. Always **host-supplied**:
    /// there is deliberately no `new()`/`Default`, since a minted request id would claim an
    /// inbound request exists when none does (ADR 0038). A host wraps the id it already has with
    /// [`Self::from_uuid`].
    ///
    /// ```
    /// use reliar_core::RequestId;
    /// use uuid::Uuid;
    ///
    /// // Wrap the inbound request's own id — never minted.
    /// let inbound = Uuid::now_v7();
    /// let request_id = RequestId::from_uuid(inbound);
    /// assert_eq!(request_id, RequestId::from_uuid(request_id.as_uuid()));
    /// ```
    RequestId,
    no_mint
);

impl ConversationId {
    /// The reserved "not yet rooted" sentinel: the **nil** UUID. [`CorrelationMetadata`]'s
    /// default uses it, and [`EnvelopeBuilder::build`] replaces it with the envelope's own id —
    /// conversation rooting is decided by *this value*, not by which builder setter was called.
    /// [`Self::from_uuid`] of any non-nil `UUIDv7` is therefore never `UNSET`. An application
    /// SHALL NOT use the nil UUID as a real conversation id.
    ///
    /// [`CorrelationMetadata`]: crate::CorrelationMetadata
    /// [`EnvelopeBuilder::build`]: crate::EnvelopeBuilder::build
    ///
    /// ```
    /// use reliar_core::ConversationId;
    /// use uuid::Uuid;
    ///
    /// assert!(ConversationId::UNSET.is_unset());
    /// assert!(!ConversationId::from_uuid(Uuid::now_v7()).is_unset());
    /// ```
    pub const UNSET: Self = Self::from_uuid(Uuid::nil());

    /// `true` when this id is [`Self::UNSET`].
    ///
    /// ```
    /// use reliar_core::ConversationId;
    /// use uuid::Uuid;
    ///
    /// assert!(ConversationId::UNSET.is_unset());
    /// assert!(!ConversationId::from_uuid(Uuid::now_v7()).is_unset());
    /// ```
    #[must_use]
    pub const fn is_unset(&self) -> bool {
        self.0.is_nil()
    }
}

/// Application/business workflow correlation id — distinct from [`ConversationId`] (Reliar's own
/// conversation root) and a `causation_id` (the direct parent message). Capped at
/// [`Self::MAX_LEN`] bytes: it lands in a `text` column read on every claim.
///
/// ```
/// use reliar_core::CorrelationId;
///
/// let id = CorrelationId::parse("checkout-42")?;
/// assert_eq!(id.as_str(), "checkout-42");
/// # Ok::<(), reliar_core::IdError>(())
/// ```
#[derive(Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct CorrelationId(String);

impl CorrelationId {
    /// Maximum length in bytes.
    pub const MAX_LEN: usize = 256;

    /// Validates and wraps a correlation id. Returns `Err` for an empty string, one containing
    /// a control character (including CR/LF — a header-injection surface), or one over
    /// [`Self::MAX_LEN`] bytes.
    ///
    /// # Errors
    ///
    /// Returns [`IdError::Empty`], [`IdError::ControlCharacter`], or [`IdError::TooLong`].
    ///
    /// ```
    /// use reliar_core::CorrelationId;
    ///
    /// let id = CorrelationId::parse("checkout-42")?;
    /// assert_eq!(id.as_str(), "checkout-42");
    /// assert!(CorrelationId::parse("").is_err());
    /// # Ok::<(), reliar_core::IdError>(())
    /// ```
    pub fn parse(s: impl Into<String>) -> Result<Self, IdError> {
        let s = s.into();

        if s.is_empty() {
            return Err(IdError::Empty);
        }

        if contains_control_char(&s) {
            return Err(IdError::ControlCharacter);
        }

        if s.len() > Self::MAX_LEN {
            return Err(IdError::TooLong {
                len: s.len(),
                max: Self::MAX_LEN,
            });
        }

        Ok(Self(s))
    }

    /// Returns the correlation id as a string slice.
    ///
    /// ```
    /// use reliar_core::CorrelationId;
    ///
    /// let id = CorrelationId::parse("checkout-42")?;
    /// assert_eq!(id.as_str(), "checkout-42");
    /// # Ok::<(), reliar_core::IdError>(())
    /// ```
    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

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

#[cfg(feature = "serde")]
#[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
mod serde_impls {
    use serde::{Deserialize, Serialize, de::Error as _};
    use uuid::Uuid;

    use super::{ConversationId, CorrelationId, MessageId, RequestId};

    // Serialized as the canonical hyphenated UUID string rather than via `uuid`'s own `serde`
    // feature, so enabling `reliar-core/serde` never has to unify `uuid`'s feature set.
    macro_rules! uuid_id_serde {
        ($name:ident) => {
            impl Serialize for $name {
                fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
                    s.collect_str(&self.0)
                }
            }
            impl<'de> Deserialize<'de> for $name {
                fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
                    let raw = String::deserialize(d)?;
                    Uuid::parse_str(&raw).map(Self).map_err(D::Error::custom)
                }
            }
        };
    }
    uuid_id_serde!(MessageId);
    uuid_id_serde!(ConversationId);
    uuid_id_serde!(RequestId);

    impl Serialize for CorrelationId {
        fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
            s.collect_str(&self.0)
        }
    }
    impl<'de> Deserialize<'de> for CorrelationId {
        fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
            let raw = String::deserialize(d)?;

            Self::parse(raw).map_err(D::Error::custom)
        }
    }
}