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.

10.0 KB
Raw Blame
//! Storage ports for activities.

use std::collections::HashMap;
use std::num::NonZeroU32;

use chrono::{DateTime, Utc};
use macro_user_id::user_id::MacroUserIdStr;
use model_entity::EntityType;
use uuid::Uuid;

use super::{
    models::{Activity, ActivityRecord},
    overview::{ActivityOverview, ActivityWindow},
};

/// Human-readable metadata for a property referenced by an activity event.
#[cfg(feature = "ai_tools")]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ActivityPropertyMetadata {
    /// The property definition's display name.
    pub display_name: String,
    /// The canonical property data type (for example `tag` or `select_string`).
    pub data_type: String,
    /// Select-option ids mapped to their human-readable labels.
    pub option_labels: HashMap<String, String>,
}

/// Resolves user-visible metadata referenced by stored activity payloads.
///
/// Implementations enforce the viewer's property-definition visibility and
/// return only metadata the viewer may read. Resolution is best-effort: an
/// unavailable secondary service returns an empty map so the primary activity
/// read can still succeed.
#[cfg(feature = "ai_tools")]
#[async_trait::async_trait]
pub trait ActivityMetadataResolver: Send + Sync + 'static {
    /// Resolve the requested property definition ids for `viewer`.
    async fn resolve_properties(
        &self,
        viewer: &macro_user_id::user_id::MacroUserIdStr<'_>,
        property_ids: &[String],
    ) -> HashMap<String, ActivityPropertyMetadata>;
}

/// Activity rows grouped per requested entity, newest first within each.
pub type EntityActivityMap = HashMap<(EntityType, String), Vec<ActivityRecord>>;

/// One keyset page of a subject's activity.
#[derive(Debug, Clone, PartialEq)]
pub struct ActivityFeedPage {
    /// Decoded rows, newest first. May be shorter than the requested limit
    /// when corrupt rows were skipped; `next` still advances past them.
    pub records: Vec<ActivityRecord>,
    /// Keyset position to resume after; `None` when the feed is exhausted.
    /// Derived from the raw fetched rows *before* decode-skipping, so one
    /// bad row can never end pagination early.
    pub next: Option<(DateTime<Utc>, Uuid)>,
}

/// A bounded time-range read of one subject's activity.
#[derive(Debug, Clone, PartialEq)]
pub struct ActivityRange {
    /// Decoded rows in the requested range, newest first.
    pub records: Vec<ActivityRecord>,
    /// Whether more matching raw rows existed beyond the requested limit.
    pub truncated: bool,
}

/// Announces durably recorded activities to realtime subscribers.
///
/// Best-effort: implementations bound delivery time and log failures instead
/// of failing the durable write. Clients refetch on reconnect to recover
/// missed pushes. Uncommitted source offsets may also replay announcements.
pub trait ActivityRealtimePublisher: Send + Sync {
    /// Announces recorded activities to their subjects and current accessors.
    fn publish_recorded(&self, activities: &[Activity]) -> impl Future<Output = ()> + Send;

    /// Announces the durable removal of activity rows.
    fn publish_invalidated(&self) -> impl Future<Output = ()> + Send;
}

/// Announce through both publishers, in order; each remains best-effort.
impl<A: ActivityRealtimePublisher, B: ActivityRealtimePublisher> ActivityRealtimePublisher
    for (A, B)
{
    async fn publish_recorded(&self, activities: &[Activity]) {
        self.0.publish_recorded(activities).await;
        self.1.publish_recorded(activities).await;
    }

    async fn publish_invalidated(&self) {
        self.0.publish_invalidated().await;
        self.1.publish_invalidated().await;
    }
}

/// Resolves who may currently see an entity's activity.
///
/// Used at publish time to widen realtime delivery beyond the acting
/// subject: entity timelines are watched by everyone with access to the
/// entity, not only whoever acted.
pub trait ActivityAudienceExpander: Send + Sync {
    /// The adapter's error type.
    type Err: std::error::Error + Send + Sync + 'static;

    /// Returns all users with current access to the entity.
    fn entity_audience(
        &self,
        entity_type: EntityType,
        entity_id: &str,
    ) -> impl Future<Output = Result<Vec<MacroUserIdStr<'static>>, Self::Err>> + Send;

    /// Check a particular viewer, including link-based access that cannot be
    /// enumerated as an audience. The conservative default uses explicit recipients.
    fn viewer_can_see(
        &self,
        entity_type: EntityType,
        entity_id: &str,
        viewer: &MacroUserIdStr<'_>,
    ) -> impl Future<Output = Result<bool, Self::Err>> + Send {
        async move {
            Ok(self
                .entity_audience(entity_type, entity_id)
                .await?
                .iter()
                .any(|user| user == viewer))
        }
    }
}

/// Publishes an already addressed activity announcement.
pub trait ActivityEventPublisher: Send + Sync {
    /// The transport's error type.
    type Err: std::fmt::Debug + Send + Sync + 'static;
    /// Delivers a domain event without deciding its recipients.
    fn publish(
        &self,
        event: super::events::ActivityTopicEvent,
    ) -> impl Future<Output = Result<(), Self::Err>> + Send;
}

/// Persists activities.
pub trait ActivityRepo {
    /// The adapter's error type.
    type Err: std::error::Error + Send + Sync + 'static;

    /// Inserts activities idempotently: an activity whose id already exists is left
    /// untouched, so at-least-once redelivery is safe.
    fn insert_activities(
        &self,
        activities: &[Activity],
    ) -> impl Future<Output = Result<(), Self::Err>> + Send;

    /// Hard-deletes every activity for the purged entities.
    fn purge_entities(
        &self,
        entities: &[(EntityType, String)],
    ) -> impl Future<Output = Result<(), Self::Err>> + Send;
}

/// Reads activities. Rows come back newest-first (`occurred_at DESC, id
/// DESC` — the stored keyset order), decoded forward-tolerantly: rows whose
/// action this reader doesn't know surface as
/// [`RecordedAction::Unknown`](super::models::RecordedAction::Unknown), and
/// rows too corrupt to represent (unparseable actor or entity type) are
/// skipped, not errors.
pub trait ActivityReads {
    /// The adapter's error type.
    type Err: std::error::Error + Send + Sync + 'static;

    /// One page of a subject's activity, newest first. `cursor` is the
    /// `(occurred_at, id)` returned as the previous page's
    /// [`next`](ActivityFeedPage::next); rows strictly before it (in keyset
    /// order) are returned. `limit` is non-zero by type: a zero-row page
    /// could not carry a `next` position and would misreport an exhausted
    /// feed.
    fn subject_feed(
        &self,
        subject_id: &str,
        cursor: Option<(DateTime<Utc>, Uuid)>,
        limit: NonZeroU32,
    ) -> impl Future<Output = Result<ActivityFeedPage, Self::Err>> + Send;

    /// One page of the activity of everyone who shares a team with
    /// `viewer_id`, the viewer excluded, newest first, on entities shared
    /// with the viewer: the same audience `get_users_by_entity` resolves
    /// (grants to the viewer, their teams, or their channels; channel
    /// participation; owned inboxes), so a link share alone does not count.
    /// Form rows are never included: they name respondents.
    ///
    /// Each page reads a bounded number of rows, so it may hold fewer than
    /// `limit` rows, or none, while `next` is set; callers keep paging
    /// until `next` is `None`. No visible row is skipped between pages.
    fn teammate_feed(
        &self,
        viewer_id: &str,
        cursor: Option<(DateTime<Utc>, Uuid)>,
        limit: NonZeroU32,
    ) -> impl Future<Output = Result<ActivityFeedPage, Self::Err>> + Send;

    /// The newest `per_entity_limit` activities for each requested entity,
    /// in one round trip. Entities with no activity are absent from the map.
    fn entity_activity(
        &self,
        keys: &[(EntityType, String)],
        per_entity_limit: u32,
    ) -> impl Future<Output = Result<EntityActivityMap, Self::Err>> + Send;

    /// Sparse day counts and the top entities for `subject_id` inside one
    /// local-date window. Counts every stored action, including views.
    fn subject_overview(
        &self,
        subject_id: &str,
        window: ActivityWindow,
    ) -> impl Future<Output = Result<ActivityOverview, Self::Err>> + Send;

    /// The subject's activity in the half-open interval `[from, to)`, newest
    /// first, capped at `limit`. `truncated` reports whether more matching raw
    /// rows exist, so callers can disclose that the bounded result is partial.
    fn subject_activity_range(
        &self,
        subject_id: &str,
        from: DateTime<Utc>,
        to: DateTime<Utc>,
        limit: NonZeroU32,
    ) -> impl Future<Output = Result<ActivityRange, Self::Err>> + Send;
}

/// Paginated entity history, separate from subject feeds and batched previews.
/// Callers must hold entity access and verify references embedded in payloads.
pub trait EntityActivityReads: Send + Sync + 'static {
    /// Persistence error.
    type Err: std::error::Error + Send + Sync + 'static;

    /// Read one entity in stable `(occurred_at DESC, id DESC)` order. The raw-row
    /// cursor advances even when a corrupt row cannot be decoded.
    fn entity_feed(
        &self,
        entity_type: EntityType,
        entity_id: &str,
        cursor: Option<(DateTime<Utc>, Uuid)>,
        limit: NonZeroU32,
    ) -> impl Future<Output = Result<ActivityFeedPage, Self::Err>> + Send;
}

/// Reads activity caused by one agent session. Its owning domain supplies access.
pub trait AgentActivityReads: Send + Sync + 'static {
    /// Persistence failure.
    type Err: std::error::Error + Send + Sync + 'static;

    /// A stable page across the session's invocations, optionally narrowed to one.
    fn agent_activity(
        &self,
        session_id: Uuid,
        correlation_id: Option<Uuid>,
        cursor: Option<(DateTime<Utc>, Uuid)>,
        limit: NonZeroU32,
    ) -> impl Future<Output = Result<ActivityFeedPage, Self::Err>> + Send;
}