synapse-primitives 0.0.2

//! Strongly-typed identifiers with SipHash integration
//!
//! This module provides type-safe wrappers around numeric IDs that are derived
//! from string names via SipHash. This provides both efficiency (4-byte IDs on wire)
//! and type safety (can't mix up different ID types).
//!
//! # Examples
//!
//! ```
//! use synapse_primitives::id::{InterfaceId, MethodId, ServiceId, HeaderKeyId};
//!
//! // Create IDs from names
//! let interface_id = InterfaceId::from_name("mensa.user.v2.UserInterface");
//! let method_id = MethodId::from_name("GetUser");
//! let service_id = ServiceId::from_name("user-service");
//! let header_id = HeaderKeyId::from_name("trace_id");
//!
//! // Use in protobuf or network protocols
//! let wire_format: u32 = interface_id.into();
//! let restored = InterfaceId::from_raw(wire_format);
//! assert_eq!(interface_id, restored);
//! ```

use crate::siphash::hash_name_u32;
use serde::{Deserialize, Serialize};
use std::fmt;

/// Service identifier - represents a logical service unit
///
/// Services are hashed from their names (e.g., "user-service", "payment-service")
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
pub struct ServiceId(u32);

impl ServiceId {
    /// Create a ServiceId from a service name
    ///
    /// # Examples
    ///
    /// ```
    /// use synapse_primitives::id::ServiceId;
    ///
    /// let id = ServiceId::from_name("user-service");
    /// ```
    pub fn from_name(name: &str) -> Self {
        Self(hash_name_u32(name))
    }

    /// Create from raw u32 (e.g., from wire protocol)
    pub const fn from_raw(id: u32) -> Self {
        Self(id)
    }

    /// Get the raw u32 value
    pub const fn as_u32(&self) -> u32 {
        self.0
    }
}

impl From<ServiceId> for u32 {
    fn from(id: ServiceId) -> u32 {
        id.0
    }
}

impl From<u32> for ServiceId {
    fn from(id: u32) -> ServiceId {
        ServiceId(id)
    }
}

impl fmt::Display for ServiceId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "ServiceId(0x{:08X})", self.0)
    }
}

/// Interface identifier - represents a protobuf-defined RPC interface
///
/// Interfaces are hashed from their fully-qualified names, including version:
/// e.g., "mensa.user.v2.UserInterface"
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
pub struct InterfaceId(u32);

impl InterfaceId {
    /// Create an InterfaceId from a fully-qualified interface name
    ///
    /// # Examples
    ///
    /// ```
    /// use synapse_primitives::id::InterfaceId;
    ///
    /// let id = InterfaceId::from_name("mensa.user.v2.UserInterface");
    /// ```
    pub fn from_name(name: &str) -> Self {
        Self(hash_name_u32(name))
    }

    /// Create from raw u32 (e.g., from wire protocol)
    pub const fn from_raw(id: u32) -> Self {
        Self(id)
    }

    /// Get the raw u32 value
    pub const fn as_u32(&self) -> u32 {
        self.0
    }
}

impl From<InterfaceId> for u32 {
    fn from(id: InterfaceId) -> u32 {
        id.0
    }
}

impl From<u32> for InterfaceId {
    fn from(id: u32) -> InterfaceId {
        InterfaceId(id)
    }
}

impl fmt::Display for InterfaceId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "InterfaceId(0x{:08X})", self.0)
    }
}

/// Method identifier - represents a method within an RPC interface
///
/// Methods are hashed from their names (e.g., "GetUser", "CreateUser")
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
pub struct MethodId(u32);

impl MethodId {
    /// Create a MethodId from a method name
    ///
    /// # Examples
    ///
    /// ```
    /// use synapse_primitives::id::MethodId;
    ///
    /// let id = MethodId::from_name("GetUser");
    /// ```
    pub fn from_name(name: &str) -> Self {
        Self(hash_name_u32(name))
    }

    /// Create from raw u32 (e.g., from wire protocol)
    pub const fn from_raw(id: u32) -> Self {
        Self(id)
    }

    /// Get the raw u32 value
    pub const fn as_u32(&self) -> u32 {
        self.0
    }
}

impl From<MethodId> for u32 {
    fn from(id: MethodId) -> u32 {
        id.0
    }
}

impl From<u32> for MethodId {
    fn from(id: u32) -> MethodId {
        MethodId(id)
    }
}

impl fmt::Display for MethodId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "MethodId(0x{:08X})", self.0)
    }
}

/// Header key identifier - represents a header name in RPC messages
///
/// Header keys are hashed from their names (e.g., "trace_id", "request_id")
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
pub struct HeaderKeyId(u32);

impl HeaderKeyId {
    /// Create a HeaderKeyId from a header name
    ///
    /// # Examples
    ///
    /// ```
    /// use synapse_primitives::id::HeaderKeyId;
    ///
    /// let trace_id = HeaderKeyId::from_name("trace_id");
    /// let request_id = HeaderKeyId::from_name("request_id");
    /// ```
    pub fn from_name(name: &str) -> Self {
        Self(hash_name_u32(name))
    }

    /// Create from raw u32 (e.g., from wire protocol)
    pub const fn from_raw(id: u32) -> Self {
        Self(id)
    }

    /// Get the raw u32 value
    pub const fn as_u32(&self) -> u32 {
        self.0
    }
}

impl From<HeaderKeyId> for u32 {
    fn from(id: HeaderKeyId) -> u32 {
        id.0
    }
}

impl From<u32> for HeaderKeyId {
    fn from(id: u32) -> HeaderKeyId {
        HeaderKeyId(id)
    }
}

impl fmt::Display for HeaderKeyId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "HeaderKeyId(0x{:08X})", self.0)
    }
}

/// Metric identifier - represents a metric name for monitoring
///
/// Metrics are hashed from their names (e.g., "request_count", "request_duration_ms")
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
pub struct MetricId(u32);

impl MetricId {
    /// Create a MetricId from a metric name
    ///
    /// # Examples
    ///
    /// ```
    /// use synapse_primitives::id::MetricId;
    ///
    /// let request_count = MetricId::from_name("request_count");
    /// let error_count = MetricId::from_name("error_count");
    /// ```
    pub fn from_name(name: &str) -> Self {
        Self(hash_name_u32(name))
    }

    /// Create from raw u32 (e.g., from wire protocol)
    pub const fn from_raw(id: u32) -> Self {
        Self(id)
    }

    /// Get the raw u32 value
    pub const fn as_u32(&self) -> u32 {
        self.0
    }
}

impl From<MetricId> for u32 {
    fn from(id: MetricId) -> u32 {
        id.0
    }
}

impl From<u32> for MetricId {
    fn from(id: u32) -> MetricId {
        MetricId(id)
    }
}

impl fmt::Display for MetricId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "MetricId(0x{:08X})", self.0)
    }
}

/// Instance identifier - represents a specific running instance of a service
///
/// Instances use 128-bit UUIDs for globally unique identification
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct InstanceId(u128);

impl InstanceId {
    /// Create a new random instance ID using UUID v4
    pub fn new_random() -> Self {
        let uuid = uuid::Uuid::new_v4();
        Self(u128::from_be_bytes(*uuid.as_bytes()))
    }

    /// Create from raw u128
    pub const fn from_raw(id: u128) -> Self {
        Self(id)
    }

    /// Create from bytes
    pub fn from_bytes(bytes: [u8; 16]) -> Self {
        Self(u128::from_be_bytes(bytes))
    }

    /// Get the raw u128 value
    pub const fn as_u128(&self) -> u128 {
        self.0
    }

    /// Get as bytes
    pub fn as_bytes(&self) -> [u8; 16] {
        self.0.to_be_bytes()
    }
}

impl From<InstanceId> for u128 {
    fn from(id: InstanceId) -> u128 {
        id.0
    }
}

impl From<u128> for InstanceId {
    fn from(id: u128) -> InstanceId {
        InstanceId(id)
    }
}

impl fmt::Display for InstanceId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "InstanceId(0x{:032X})", self.0)
    }
}

/// Common header key IDs for standard headers
///
/// Values are precomputed from `HeaderKeyId::from_name()` (SipHash) to ensure
/// these constants match runtime-computed values exactly.
pub mod well_known {
    use super::HeaderKeyId;
    use once_cell::sync::Lazy;

    /// Standard header: trace_id
    pub static TRACE_ID: Lazy<HeaderKeyId> = Lazy::new(|| HeaderKeyId::from_name("trace_id"));

    /// Standard header: span_id
    pub static SPAN_ID: Lazy<HeaderKeyId> = Lazy::new(|| HeaderKeyId::from_name("span_id"));

    /// Standard header: request_id
    pub static REQUEST_ID: Lazy<HeaderKeyId> = Lazy::new(|| HeaderKeyId::from_name("request_id"));

    /// Standard header: caller_service
    pub static CALLER_SERVICE: Lazy<HeaderKeyId> =
        Lazy::new(|| HeaderKeyId::from_name("caller_service"));

    /// Standard header: idempotency_key
    pub static IDEMPOTENCY_KEY: Lazy<HeaderKeyId> =
        Lazy::new(|| HeaderKeyId::from_name("idempotency_key"));
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_service_id() {
        let id1 = ServiceId::from_name("user-service");
        let id2 = ServiceId::from_name("user-service");
        let id3 = ServiceId::from_name("payment-service");

        assert_eq!(id1, id2, "Same name should produce same ID");
        assert_ne!(id1, id3, "Different names should produce different IDs");

        // Round-trip through u32
        let raw: u32 = id1.into();
        let restored = ServiceId::from_raw(raw);
        assert_eq!(id1, restored);
    }

    #[test]
    fn test_interface_id() {
        let id = InterfaceId::from_name("mensa.user.v2.UserInterface");
        let raw = id.as_u32();
        let restored = InterfaceId::from_raw(raw);
        assert_eq!(id, restored);
    }

    #[test]
    fn test_method_id() {
        let get_user = MethodId::from_name("GetUser");
        let create_user = MethodId::from_name("CreateUser");
        assert_ne!(get_user, create_user);
    }

    #[test]
    fn test_header_key_id() {
        let trace_id = HeaderKeyId::from_name("trace_id");
        let request_id = HeaderKeyId::from_name("request_id");
        assert_ne!(trace_id, request_id);
    }

    #[test]
    fn test_metric_id() {
        let request_count = MetricId::from_name("request_count");
        let error_count = MetricId::from_name("error_count");
        assert_ne!(request_count, error_count);
    }

    #[test]
    fn test_instance_id() {
        let id1 = InstanceId::new_random();

        // Round-trip through bytes
        let bytes = id1.as_bytes();
        let restored = InstanceId::from_bytes(bytes);
        assert_eq!(id1, restored);

        // Verify size
        assert_eq!(bytes.len(), 16);
    }

    #[test]
    fn test_display() {
        let service_id = ServiceId::from_name("test-service");
        let display = format!("{}", service_id);
        assert!(display.starts_with("ServiceId(0x"));
    }

    #[test]
    fn test_well_known_headers() {
        // Well-known headers should match runtime-computed values
        assert_eq!(*well_known::TRACE_ID, HeaderKeyId::from_name("trace_id"));
        assert_eq!(*well_known::SPAN_ID, HeaderKeyId::from_name("span_id"));
        assert_eq!(
            *well_known::REQUEST_ID,
            HeaderKeyId::from_name("request_id")
        );
        assert_eq!(
            *well_known::CALLER_SERVICE,
            HeaderKeyId::from_name("caller_service")
        );
        assert_eq!(
            *well_known::IDEMPOTENCY_KEY,
            HeaderKeyId::from_name("idempotency_key")
        );

        // They should all be distinct
        assert_ne!(*well_known::TRACE_ID, *well_known::SPAN_ID);
    }

    #[test]
    fn test_version_sensitivity() {
        let v1 = InterfaceId::from_name("mensa.user.v1.UserInterface");
        let v2 = InterfaceId::from_name("mensa.user.v2.UserInterface");
        assert_ne!(v1, v2, "Different versions should have different IDs");
    }

    #[test]
    fn test_ordering() {
        let id1 = ServiceId::from_name("aaa");
        let id2 = ServiceId::from_name("bbb");
        let id3 = ServiceId::from_name("ccc");

        // IDs should be orderable
        let mut ids = [id3, id1, id2];
        ids.sort();

        // Ordering is based on hash, not name
        assert_eq!(ids.len(), 3);
    }
}