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.

14.9 KB
Raw Blame
//! Kafka event models for the `macro.documents` topic.
//!
//! Follows the canonical pattern in `macro_event_broker/examples/example_event.rs`:
//! per-variant metadata structs, a [`TopicEvent`] enum tagged by `event_type`,
//! and a [`MacroEvent`] wrapper keyed by document id.

#[cfg(test)]
mod test;

use activity::Actor;
use chrono::{DateTime, Utc};
use document_sub_type::DocumentSubType;
use macro_event_broker::{Event, MacroEvent, TopicEvent};
use macro_event_topics::MacroDocumentsTopic;
use macro_user_id::user_id::MacroUserIdStr;
use model::document::FileType;
use model_owner::Owner;
use serde::{Deserialize, Serialize};

use super::models::FileTypeUpdate;

/// Metadata for [`DocumentTopicEvent::Created`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct DocumentCreatedMetadata {
    /// The id of the created document.
    pub document_id: String,
    /// The principal who owns the document.
    #[cfg_attr(feature = "schema", schema(value_type = String))]
    pub owner: Owner,
    /// Who mechanically created the document. Absent on events published
    /// before attribution: ingest derives a user/bot actor from [`Self::owner`].
    /// Team owners fall back to [`Self::on_behalf_of`], then the system bot.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "schema", schema(value_type = Option<String>))]
    pub actor: Option<Actor<'static>>,
    /// The user whose feed this creation belongs on, when different from
    /// [`Self::actor`]. Absent means the actor is also the subject.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub on_behalf_of: Option<MacroUserIdStr<'static>>,
    /// The document name, with any file extension stripped.
    pub document_name: String,
    /// File type of the document, when known.
    pub file_type: Option<FileType>,
    /// Project the document was created in, when any.
    pub project_id: Option<String>,
    /// Sub type (task / snippet), when any.
    pub sub_type: Option<DocumentSubType>,
    /// Creation timestamp reported by the repository.
    pub created_at: Option<DateTime<Utc>>,
}

/// Metadata for [`DocumentTopicEvent::Updated`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct DocumentUpdatedMetadata {
    /// The id of the updated document.
    pub document_id: String,
    /// The owner of the document.
    #[cfg_attr(feature = "schema", schema(value_type = String))]
    pub owner: Owner,
    /// The authenticated user who performed the update; `None` for
    /// unauthenticated or internal callers.
    pub actor_user_id: Option<MacroUserIdStr<'static>>,
    /// Who mechanically updated the document. Absent on events published
    /// before attribution, and on user-receipt writes (ingest then uses
    /// [`Self::actor_user_id`]).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "schema", schema(value_type = Option<String>))]
    pub actor: Option<Actor<'static>>,
    /// The user whose feed this update belongs on, when different from
    /// [`Self::actor`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub on_behalf_of: Option<MacroUserIdStr<'static>>,
    /// New (cleaned) document name; `None` when unchanged.
    pub document_name: Option<String>,
    /// Project id before the update.
    pub previous_project_id: Option<String>,
    /// New project id; `None` when unchanged, `Some("")` when removed from
    /// its project (mirrors the edit repo args semantics).
    pub project_id: Option<String>,
    /// Requested file type change; `None` when unchanged.
    pub file_type: Option<FileTypeUpdate>,
    /// Whether share permissions were updated.
    pub share_permission_updated: bool,
}

/// Metadata for [`DocumentTopicEvent::Deleted`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct DocumentDeletedMetadata {
    /// The id of the deleted document.
    pub document_id: String,
    /// Subtype captured before deletion, so consumers can distinguish tasks.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub sub_type: Option<DocumentSubType>,
    /// The authenticated user who deleted the document; `None` for
    /// unauthenticated or internal callers.
    pub actor_user_id: Option<MacroUserIdStr<'static>>,
    /// Who mechanically deleted the document. Absent on events published
    /// before attribution, and on user-receipt writes (ingest then uses
    /// [`Self::actor_user_id`]).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "schema", schema(value_type = Option<String>))]
    pub actor: Option<Actor<'static>>,
    /// The user whose feed this delete belongs on, when different from
    /// [`Self::actor`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub on_behalf_of: Option<MacroUserIdStr<'static>>,
    /// Project the document belonged to, when any.
    pub project_id: Option<String>,
}

/// Metadata for [`DocumentTopicEvent::ContentUploaded`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct DocumentContentUploadedMetadata {
    /// The id of the document whose stored bytes changed.
    pub document_id: String,
    /// The owner of the document (used by the extractor to resolve S3 keys).
    #[cfg_attr(feature = "schema", schema(value_type = String))]
    pub owner: Owner,
    /// File type of the uploaded object (may differ from the document's own
    /// type, e.g. `pdf` for the converted rendition of a docx).
    pub file_type: FileType,
    /// Version written, or the converted-file marker; `None` for unversioned
    /// writes (mirrors `SearchExtractorMessage::document_version_id`).
    pub document_version_id: Option<String>,
}

/// An editor reported by Sync from an authenticated session.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct DocumentSyncEditor {
    /// Invocation from the editor's signed document grant.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub agent_correlation_id: Option<uuid::Uuid>,
    /// User or bot that performed the edit.
    #[cfg_attr(feature = "schema", schema(value_type = String))]
    pub actor: Actor<'static>,
    /// User represented by an agent, if any.
    pub on_behalf_of: Option<MacroUserIdStr<'static>>,
}

/// Metadata for [`DocumentTopicEvent::SyncContentUpdated`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct DocumentSyncContentUpdatedMetadata {
    /// The id of the live-collab document whose content changed.
    pub document_id: String,
    /// File type of the sync document, resolved by the document backend.
    pub file_type: FileType,
    /// Version marker for the sync snapshot, when the caller supplies one.
    pub document_version_id: Option<String>,
    /// Legacy single-editor attribution; newer Sync callers send `editors`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "schema", schema(value_type = Option<String>))]
    pub actor: Option<Actor<'static>>,
    /// The user whose feed this edit belongs on, when different from
    /// [`Self::actor`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub on_behalf_of: Option<MacroUserIdStr<'static>>,
    /// Distinct editors since the preceding snapshot notification.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub editors: Vec<DocumentSyncEditor>,
}

impl DocumentSyncContentUpdatedMetadata {
    /// Build metadata from extract-sync strings. Invalid actor or subject
    /// ids are dropped so a bad payload still extracts the document.
    pub fn from_extract(
        document_id: String,
        file_type: FileType,
        document_version_id: Option<String>,
        actor: Option<String>,
        on_behalf_of: Option<String>,
    ) -> Self {
        Self {
            document_id,
            file_type,
            document_version_id,
            actor: actor.and_then(|id| Actor::try_from(id).ok()),
            on_behalf_of: on_behalf_of.and_then(|id| MacroUserIdStr::try_from(id).ok()),
            editors: Vec::new(),
        }
    }
}

/// Metadata for [`DocumentTopicEvent::Purged`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct DocumentPurgedMetadata {
    /// The id of the hard-deleted document.
    pub document_id: String,
}

/// Why a document interaction was reported.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
#[serde(rename_all = "snake_case")]
pub enum InteractionReason {
    /// A periodic save of pending content changes.
    Edited,
    /// The first peer joined the document session.
    FirstJoin,
    /// The last connected peer left the document session.
    LastLeave,
}

/// Metadata for [`DocumentTopicEvent::Interaction`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct DocumentInteractionMetadata {
    /// The id of the document.
    pub document_id: String,
    /// What triggered this interaction.
    pub reason: InteractionReason,
}

/// Metadata for [`DocumentTopicEvent::Copied`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct DocumentCopiedMetadata {
    /// The id of the newly created copy.
    pub document_id: String,
    /// The id of the document that was copied.
    pub source_document_id: String,
    /// The specific source version copied, when requested.
    pub source_version_id: Option<i64>,
    /// The principal who owns the new copy.
    #[cfg_attr(feature = "schema", schema(value_type = String))]
    pub owner: Owner,
    /// Who mechanically created the copy.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "schema", schema(value_type = Option<String>))]
    pub actor: Option<Actor<'static>>,
    /// The user whose feed this copy belongs on, when different from the actor.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub on_behalf_of: Option<MacroUserIdStr<'static>>,
    /// The name of the new document.
    pub document_name: String,
    /// File type of the document, when known.
    pub file_type: Option<FileType>,
    /// Project the copy belongs to, when any.
    pub project_id: Option<String>,
    /// Sub type (task / snippet), when any.
    pub sub_type: Option<DocumentSubType>,
}

/// Events that can be published to [`MacroDocumentsTopic`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
#[serde(tag = "event_type", content = "metadata")]
pub enum DocumentTopicEvent {
    /// A document was created.
    #[serde(rename = "document.created")]
    Created(DocumentCreatedMetadata),
    /// A document's metadata / permissions were updated.
    #[serde(rename = "document.updated")]
    Updated(DocumentUpdatedMetadata),
    /// A document was soft-deleted.
    #[serde(rename = "document.deleted")]
    Deleted(DocumentDeletedMetadata),
    /// The document's stored bytes were (re)written to S3.
    #[serde(rename = "document.content_uploaded")]
    ContentUploaded(DocumentContentUploadedMetadata),
    /// A live-collab (sync) document's content changed and should be re-extracted.
    #[serde(rename = "document.sync_content_updated")]
    SyncContentUpdated(DocumentSyncContentUpdatedMetadata),
    /// The document row was permanently deleted (hard delete).
    #[serde(rename = "document.purged")]
    Purged(DocumentPurgedMetadata),
    /// A document was copied.
    #[serde(rename = "document.copied")]
    Copied(DocumentCopiedMetadata),
    /// A peer joined, left, or a periodic save occurred.
    #[serde(rename = "document.interaction")]
    Interaction(DocumentInteractionMetadata),
}

impl TopicEvent for DocumentTopicEvent {
    type Topic = MacroDocumentsTopic;

    const SCHEMA_VERSION: u8 = 1;
}

/// Publishable event for [`MacroDocumentsTopic`], keyed by document id.
pub struct DocumentMacroEvent {
    key: String,
    event: Event<DocumentTopicEvent>,
}

impl DocumentMacroEvent {
    /// Build a created event keyed by the new document id.
    pub fn created(key: impl Into<String>, metadata: DocumentCreatedMetadata) -> Self {
        Self::new(key, DocumentTopicEvent::Created(metadata))
    }

    /// Build an updated event keyed by the updated document id.
    pub fn updated(key: impl Into<String>, metadata: DocumentUpdatedMetadata) -> Self {
        Self::new(key, DocumentTopicEvent::Updated(metadata))
    }

    /// Build a deleted event keyed by the deleted document id.
    pub fn deleted(key: impl Into<String>, metadata: DocumentDeletedMetadata) -> Self {
        Self::new(key, DocumentTopicEvent::Deleted(metadata))
    }

    /// Build a content-uploaded event keyed by the document id.
    pub fn content_uploaded(
        key: impl Into<String>,
        metadata: DocumentContentUploadedMetadata,
    ) -> Self {
        Self::new(key, DocumentTopicEvent::ContentUploaded(metadata))
    }

    /// Build a sync-content-updated event keyed by the document id.
    pub fn sync_content_updated(
        key: impl Into<String>,
        metadata: DocumentSyncContentUpdatedMetadata,
    ) -> Self {
        Self::new(key, DocumentTopicEvent::SyncContentUpdated(metadata))
    }

    /// Build a purged event keyed by the document id.
    pub fn purged(key: impl Into<String>, metadata: DocumentPurgedMetadata) -> Self {
        Self::new(key, DocumentTopicEvent::Purged(metadata))
    }

    /// Build a copied event keyed by the new document id.
    pub fn copied(key: impl Into<String>, metadata: DocumentCopiedMetadata) -> Self {
        Self::new(key, DocumentTopicEvent::Copied(metadata))
    }

    /// Build an interaction event keyed by the document id.
    pub fn interaction(key: impl Into<String>, metadata: DocumentInteractionMetadata) -> Self {
        Self::new(key, DocumentTopicEvent::Interaction(metadata))
    }

    /// Build an event from a topic-specific event variant.
    pub fn new(key: impl Into<String>, event: DocumentTopicEvent) -> Self {
        Self::with_event(key, Event::new(event))
    }

    /// Build an event from a pre-built envelope.
    pub fn with_event(key: impl Into<String>, event: Event<DocumentTopicEvent>) -> Self {
        Self {
            key: key.into(),
            event,
        }
    }
}

impl MacroEvent for DocumentMacroEvent {
    type EventPayload = DocumentTopicEvent;

    fn key(&self) -> &str {
        &self.key
    }

    fn event(&self) -> &Event<Self::EventPayload> {
        &self.event
    }

    fn from_event(key: String, event: Event<Self::EventPayload>) -> Self {
        Self::with_event(key, event)
    }
}