yeti_types/

types.rs

//! Common type aliases and newtypes used throughout the platform.

use std::ops::Deref;

/// Generate a newtype wrapper for strings with common trait implementations.
macro_rules! string_newtype {
    (
        $(#[$meta:meta])*
        $name:ident
    ) => {
        $(#[$meta])*
        #[derive(Debug, Clone, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
        #[serde(transparent)]
        pub struct $name(String);

        impl $name {
            /// Create a new instance.
            #[must_use]
            pub fn new(value: impl Into<String>) -> Self {
                Self(value.into())
            }

            /// Get the inner string value.
            #[must_use]
            pub fn as_str(&self) -> &str {
                &self.0
            }

            /// Get the length of the string.
            #[must_use]
            pub const fn len(&self) -> usize {
                self.0.len()
            }

            /// Check if the string is empty.
            #[must_use]
            pub const fn is_empty(&self) -> bool {
                self.0.is_empty()
            }

            /// Convert into the inner string.
            #[must_use]
            pub fn into_inner(self) -> String {
                self.0
            }
        }

        impl From<String> for $name {
            fn from(s: String) -> Self {
                Self(s)
            }
        }

        impl From<&str> for $name {
            fn from(s: &str) -> Self {
                Self(s.to_string())
            }
        }

        impl From<&$name> for $name {
            fn from(v: &$name) -> Self {
                v.clone()
            }
        }

        impl From<&String> for $name {
            fn from(s: &String) -> Self {
                Self(s.clone())
            }
        }

        impl AsRef<str> for $name {
            fn as_ref(&self) -> &str {
                &self.0
            }
        }

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

        impl Deref for $name {
            type Target = str;

            fn deref(&self) -> &Self::Target {
                &self.0
            }
        }
    };
}

string_newtype!(
    /// Key prefix identifier (application ID for key namespacing).
    KeyPrefix
);

string_newtype!(
    /// Type-safe table name.
    TableName
);

string_newtype!(
    /// Type-safe application ID.
    AppId
);

string_newtype!(
    /// Type-safe database namespace within an app.
    ///
    /// Default `"data"`. Apps may declare multiple databases via the
    /// `@table(database: "...")` directive to scope tables; databases
    /// are routing namespaces, not security boundaries.
    DatabaseName
);

string_newtype!(
    /// Stable hash identifying a yeti deployment.
    ///
    /// Every deployment runs as its own OS process on every node that
    /// holds it; the deployment hash is the public address segment
    /// (`{deployment_hash}.apps.yetirocks.com`) and the routing key
    /// the per-node multiplexer uses to dispatch incoming RPCs to the
    /// owning process. Customer scoping is a property of the
    /// deployment (one deployment ⇒ one tenant context), so it is NOT
    /// carried inside per-record identifiers like `TableId`; it
    /// lives at the mux layer where it determines which Unix socket
    /// gets the request, and inside the inter-node replication frame
    /// header where it determines which peer process consumes the
    /// payload. Wire frames addressed by `DeploymentHash` are
    /// independently encrypted per-deployment so the multiplexed
    /// gRPC link between two nodes cannot leak across tenants.
    DeploymentHash
);

/// Identity of a table within a single deployment's data plane.
///
/// A deployment is one OS process; everything inside it shares the
/// same tenant context, so `TableId` carries only the in-process
/// coordinates: which application, which database namespace, which
/// table. The deployment-level scope (whose data this is, which node
/// presents it on which subdomain) is expressed by
/// [`DeploymentHash`] at the routing layer, never duplicated here.
///
/// Used as the addressable unit on the replication wire below the
/// per-deployment frame, in audit records, and in any cross-node
/// observation of writes.
///
/// String-based in v0. Future optimization: interned numeric ordinals
/// via a per-deployment registry, reducing wire overhead from
/// ~32 bytes/record to ~8. Drop-in replaceable when profiling
/// justifies; v0 prefers clarity.
#[derive(Debug, Clone, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub struct TableId {
    /// Application identifier within the deployment.
    pub app: AppId,
    /// Database namespace within the application (default `"data"`).
    pub database: DatabaseName,
    /// Physical table name within the database.
    pub table: TableName,
}

impl TableId {
    /// Construct a new `TableId`.
    pub fn new(
        app: impl Into<AppId>,
        database: impl Into<DatabaseName>,
        table: impl Into<TableName>,
    ) -> Self {
        Self {
            app: app.into(),
            database: database.into(),
            table: table.into(),
        }
    }
}

impl std::fmt::Display for TableId {
    /// Format as `{app}/{database}/{table}` — the canonical
    /// hierarchical path within a deployment. Slashes are reserved
    /// separators; individual segments must not contain them. Used
    /// for log messages, audit records, and key-prefix encoding.
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}/{}/{}", self.app, self.database, self.table)
    }
}

/// Thread-safe reference to a key-value backend.
pub type BackendRef = std::sync::Arc<dyn crate::backend::KvBackend>;

/// Thread-safe reference to the pub/sub manager.
pub type PubSubRef = std::sync::Arc<crate::pubsub::PubSubManager>;