Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

7.6 KB
Raw Blame
#![deny(missing_docs)]
//! Types shared by `entity_registry` and `entity_registry_db_utils`.
//!
//! Reads and owner-grant policy live in `entity_registry`. Transactional writes
//! go through `entity_registry_db_utils`, which applies that policy when
//! registering owned entities. [`PurgeOwnedEntity`] is the permanent delete
//! each owning service exposes to callers that remove an owner.
//!
//! ```
//! use model_entity::EntityType;
//! use model_owner::OwnerType;
//! use shared_entity_registry::{NewEntityRecord, Owner, RegisteredEntityType};
//! use uuid::Uuid;
//!
//! let owner = Owner::parse(OwnerType::User, "macro|[email protected]").unwrap();
//! let record = NewEntityRecord::try_new(Uuid::nil(), EntityType::Chat, owner.clone()).unwrap();
//! assert_eq!(record.entity_type, RegisteredEntityType::Chat);
//! assert!(NewEntityRecord::try_new(Uuid::nil(), EntityType::Initiative, owner).is_err());
//! ```

#[cfg(test)]
mod test;

use chrono::{DateTime, Utc};
use model_entity::EntityType;
use rootcause::Report;
use serde::{Deserialize, Serialize};
use uuid::Uuid;

pub use model_owner::Owner;

/// The entity kinds the `entity` table accepts: its CHECK constraint as a type.
///
/// Serializes as its [`EntityType`] spelling, and deserializing any other
/// kind fails.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(into = "EntityType", try_from = "EntityType")]
pub enum RegisteredEntityType {
    /// `project`
    Project,
    /// `document`
    Document,
    /// `chat`
    Chat,
    /// `agent_session`
    AgentSession,
    /// `scheduled_action`
    ScheduledAction,
    /// `external_chat`
    ExternalChat,
}

impl RegisteredEntityType {
    /// Every registered kind.
    pub const ALL: [Self; 6] = [
        Self::Project,
        Self::Document,
        Self::Chat,
        Self::AgentSession,
        Self::ScheduledAction,
        Self::ExternalChat,
    ];

    /// The stored spelling.
    #[must_use]
    pub fn as_str(self) -> &'static str {
        EntityType::from(self).into()
    }
}

impl From<RegisteredEntityType> for EntityType {
    fn from(kind: RegisteredEntityType) -> Self {
        match kind {
            RegisteredEntityType::Project => Self::Project,
            RegisteredEntityType::Document => Self::Document,
            RegisteredEntityType::Chat => Self::Chat,
            RegisteredEntityType::AgentSession => Self::AgentSession,
            RegisteredEntityType::ScheduledAction => Self::ScheduledAction,
            RegisteredEntityType::ExternalChat => Self::ExternalChat,
        }
    }
}

/// An [`EntityType`] the registry does not record.
#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
#[error("{0} is not a registered entity type")]
pub struct UnregisteredEntityType(pub EntityType);

impl TryFrom<EntityType> for RegisteredEntityType {
    type Error = UnregisteredEntityType;

    fn try_from(value: EntityType) -> Result<Self, Self::Error> {
        match value {
            EntityType::Project => Ok(Self::Project),
            EntityType::Document => Ok(Self::Document),
            EntityType::Chat => Ok(Self::Chat),
            EntityType::AgentSession => Ok(Self::AgentSession),
            EntityType::ScheduledAction => Ok(Self::ScheduledAction),
            EntityType::ExternalChat => Ok(Self::ExternalChat),
            other => Err(UnregisteredEntityType(other)),
        }
    }
}

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

/// Input to register a row.
///
/// `None` timestamps take the database clock. Inside one transaction that
/// is the same instant the caller's own `DEFAULT now()` columns received,
/// so a create path passes nothing and the two rows agree.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct NewEntityRecord {
    /// The resource's id.
    pub id: Uuid,
    /// The kind of resource.
    pub entity_type: RegisteredEntityType,
    /// Who owns it.
    pub owner: Owner,
    /// `None` = database `now()`.
    pub created_at: Option<DateTime<Utc>>,
    /// `None` = database `now()`.
    pub updated_at: Option<DateTime<Utc>>,
}

impl NewEntityRecord {
    /// A record stamped by the database clock. The create-path constructor.
    #[must_use]
    pub fn new(id: Uuid, entity_type: RegisteredEntityType, owner: Owner) -> Self {
        Self {
            id,
            entity_type,
            owner,
            created_at: None,
            updated_at: None,
        }
    }

    /// Narrow a wide [`EntityType`] at the caller that holds it.
    pub fn try_new(
        id: Uuid,
        entity_type: EntityType,
        owner: Owner,
    ) -> Result<Self, UnregisteredEntityType> {
        Ok(Self::new(
            id,
            RegisteredEntityType::try_from(entity_type)?,
            owner,
        ))
    }

    /// Carry the resource row's own stamps. The backfill constructor.
    #[must_use]
    pub fn with_timestamps(self, created_at: DateTime<Utc>, updated_at: DateTime<Utc>) -> Self {
        Self {
            created_at: Some(created_at),
            updated_at: Some(updated_at),
            ..self
        }
    }
}

/// What an insert into the registry did.
///
/// `AlreadyRegistered` means a row with this id existed; it does **not**
/// mean that row matches the input.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum InsertOutcome {
    /// A new row was written.
    Inserted,
    /// A row with this id already existed; nothing was written.
    AlreadyRegistered,
}

/// What an id-targeted write did.
///
/// `NotFound` is an outcome, not an error. Callers that want strictness check
/// the value.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum WriteOutcome {
    /// Exactly one row matched and was written.
    Applied,
    /// No row with that id exists.
    NotFound,
}

/// Failure kinds of the registry.
#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
pub enum EntityRegistryError {
    /// An owned bot has no resolvable user/team sponsor.
    #[error("bot sponsor is missing or invalid")]
    InvalidBotSponsor,
    /// An existing id has a different recorded owner or entity type.
    #[error("entity registration conflicts with the recorded owner or type")]
    RegistrationConflict,
    /// A stored row could not be decoded into a registry record.
    /// The attached id says which row.
    #[error("entity row is corrupt")]
    CorruptRow,
    /// The database failed. The attached cause is the driver error.
    #[error("entity registry persistence failed")]
    Infrastructure,
}

/// Typed report returned by every registry operation, read or write.
pub type EntityRegistryResult<T> = Result<T, Report<EntityRegistryError>>;

/// What an owner-checked permanent delete did.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum OwnedPurgeOutcome {
    /// The entity is gone: deleted by this call, or already missing.
    Purged,
    /// The entity exists under a different owner. Nothing was deleted.
    OwnedElsewhere,
}

/// Permanent delete of one entity, conditional on its recorded owner.
///
/// The service that owns each [`RegisteredEntityType`] implements it, for
/// callers that remove everything an owner holds. Those callers retry until
/// the owner lists nothing, so a repeated call must converge.
pub trait PurgeOwnedEntity: Send + Sync {
    /// Permanently delete `entity_id`, live or trashed, if `expected_owner`
    /// is its recorded owner. A missing entity is [`OwnedPurgeOutcome::Purged`].
    fn purge_owned(
        &self,
        entity_id: Uuid,
        expected_owner: &Owner,
    ) -> impl Future<Output = Result<OwnedPurgeOutcome, Report>> + Send;
}