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.

19.3 KB
Raw Blame
//! Port definitions for the projects domain.
//!
//! These traits define the contracts implemented by inbound-facing services
//! and outbound infrastructure adapters.

use std::future::Future;

use entity_access::domain::models::{
    EditAccessLevel, EntityAccessReceipt, OwnerAccessLevel, ViewAccessLevel,
};
use entity_mutation::EntityMutationErrorCode;
use macro_user_id::user_id::MacroUserIdStr;
use model::document::ContentType;
use model::folder::{UploadFolderRequest, UploadFolderResponseData, UploadFolderWithIdsResponse};
use model::item::{Item, ItemWithUserAccessLevel};
use model::project::request::{CreateProjectRequest, PatchProjectRequestV2};
use model::project::response::GetProjectResponseData;
use model::project::{
    BasicProject, PendingProject, Project, ProjectPreview, ProjectPreviewV2,
    ProjectWithUploadRequest,
};
use model_entity::Entity;
use model_owner::{CreationPrincipal, Owner};
use models_bulk_upload::{
    BulkUploadRequest, BulkUploadRequestDocuments, UploadExtractFolderRequest,
    UploadExtractFolderResponseData,
};
use models_permissions::share_permission::access_level::AccessLevel;
use models_permissions::share_permission::team_share::TeamShareFacts;
use models_permissions::share_permission::{SharePermissionV2, TeamLinkShareDefault};
use s3_key::BulkUploadStagingKey;
use uuid::Uuid;

use super::models::{
    CreateProjectArgs, EditProjectArgs, MarkedUploadedTree, MutatedProject, ProjectError,
    ProjectTree, PurgedProjectTree, RevertDeleteResult, SoftDeleteResult, UploadFolderRepoArgs,
};

/// Repository for reading project data from persistent storage.
///
/// SQL and transaction details belong in the outbound adapter implementing
/// this trait.
#[cfg_attr(test, mockall::automock(type Err = anyhow::Error;))]
pub trait ProjectRepo: Send + Sync + 'static {
    /// Error returned by repository operations.
    type Err: Into<anyhow::Error> + Send + std::fmt::Debug;

    /// Get a basic project row, including soft-deleted projects.
    fn get_basic_project(
        &self,
        project_id: &str,
    ) -> impl Future<Output = Result<Option<BasicProject>, Self::Err>> + Send;

    /// Get a full, non-deleted project row.
    fn get_project_by_id(
        &self,
        project_id: &str,
    ) -> impl Future<Output = Result<Option<Project>, Self::Err>> + Send;

    /// List non-deleted, uploaded projects in the user's view history.
    fn get_projects_for_user(
        &self,
        user_id: &str,
    ) -> impl Future<Output = Result<Vec<Project>, Self::Err>> + Send;

    /// List non-deleted projects the user can access via `entity_access`.
    ///
    /// Includes pending uploads. Soft-deleted projects are excluded. Order is
    /// newest `updatedAt` first.
    fn get_accessible_projects_for_user(
        &self,
        user_id: &str,
    ) -> impl Future<Output = Result<Vec<Project>, Self::Err>> + Send;

    /// List non-deleted, pending root projects owned by the user.
    fn get_pending_root_projects(
        &self,
        user_id: &str,
    ) -> impl Future<Output = Result<Vec<ProjectWithUploadRequest>, Self::Err>> + Send;

    /// Get depth-one project, document, and chat children in display order.
    fn get_project_children(
        &self,
        project_id: &str,
    ) -> impl Future<Output = Result<Vec<Item>, Self::Err>> + Send;

    /// Get the live folders below a project and the live documents and chats
    /// filed in it or them. Returns at most `limit` folders and at most
    /// `limit` items, so a caller detects an oversized tree by asking for
    /// one more than it accepts.
    fn get_project_tree(
        &self,
        project_id: &str,
        limit: usize,
    ) -> impl Future<Output = Result<ProjectTree, Self::Err>> + Send;

    /// Get the project's share permission configuration.
    fn get_project_share_permission(
        &self,
        project_id: &str,
    ) -> impl Future<Output = Result<SharePermissionV2, Self::Err>> + Send;

    /// Load the canonical team-share facts (persisted owner, owner's team,
    /// current explicit grant, revision) the owner policy authorizes against.
    fn get_team_share_facts(
        &self,
        project_id: &str,
    ) -> impl Future<Output = Result<TeamShareFacts, ProjectError>> + Send;

    /// Get previews for the supplied project identifiers.
    fn batch_get_project_preview(
        &self,
        project_ids: &[String],
    ) -> impl Future<Output = Result<Vec<ProjectPreviewV2>, Self::Err>> + Send;

    /// Get the link-share preference of the team `owner` resolves to, per
    /// [`model_owner::team::owner_team`]. Bots resolve through their team or
    /// owning user; a teamless owner has no team default.
    fn get_team_default_link_share(
        &self,
        owner: &Owner,
    ) -> impl Future<Output = Result<Option<TeamLinkShareDefault>, Self::Err>> + Send;

    /// Atomically create a project and its permission, history, and owner-access rows.
    fn create_project(
        &self,
        args: CreateProjectArgs,
    ) -> impl Future<Output = Result<MutatedProject, Self::Err>> + Send;

    /// Edit project fields and optional sharing configuration atomically.
    fn edit_project(
        &self,
        args: EditProjectArgs,
    ) -> impl Future<Output = Result<MutatedProject, ProjectError>> + Send;

    /// Return whether the proposed parent is inside the project's subtree.
    fn is_project_recursively_nested(
        &self,
        project_id: &str,
        parent_id: &str,
    ) -> impl Future<Output = Result<bool, Self::Err>> + Send;

    /// Soft-delete a project and all of its active descendants.
    fn soft_delete_project(
        &self,
        project_id: &str,
    ) -> impl Future<Output = Result<SoftDeleteResult, Self::Err>> + Send;

    /// Permanently purge an already-soft-deleted project subtree and its child data.
    fn purge_deleted_project_tree(
        &self,
        project_id: &str,
    ) -> impl Future<Output = Result<PurgedProjectTree, Self::Err>> + Send;

    /// Restore a deleted project subtree and the owners' history rows.
    fn revert_delete_project(
        &self,
        project_id: &str,
        previous_parent_id: Option<String>,
    ) -> impl Future<Output = Result<RevertDeleteResult, Self::Err>> + Send;

    /// Create and commit a pending project tree with empty documents.
    fn upload_folder(
        &self,
        args: UploadFolderRepoArgs,
    ) -> impl Future<Output = Result<UploadFolderWithIdsResponse, Self::Err>> + Send;

    /// Delete a committed upload tree as compensation for later failures.
    fn delete_uploaded_tree(
        &self,
        project_ids: &[String],
        document_ids: &[String],
    ) -> impl Future<Output = Result<(), Self::Err>> + Send;

    /// Recursively finalize the uploaded state of a project tree.
    fn mark_projects_uploaded(
        &self,
        root_project_id: &str,
    ) -> impl Future<Output = Result<MarkedUploadedTree, Self::Err>> + Send;

    /// Update the project's modified timestamp.
    fn update_project_modified(
        &self,
        project_id: &str,
    ) -> impl Future<Output = Result<(), Self::Err>> + Send;
}

/// Port for creating and inspecting bulk-upload requests.
pub trait BulkUploadRequestPort: Send + Sync + 'static {
    /// Create a bulk-upload request.
    fn create_bulk_upload_request(
        &self,
        request_id: Uuid,
        user_id: &str,
        name: Option<&str>,
        parent_id: Option<&str>,
    ) -> impl Future<Output = anyhow::Result<BulkUploadRequest>> + Send;

    /// Get document statuses for a bulk-upload request.
    fn get_bulk_upload_document_statuses(
        &self,
        upload_request_id: &str,
    ) -> impl Future<Output = anyhow::Result<BulkUploadRequestDocuments>> + Send;
}

/// Port for generating project-upload destinations.
pub trait ProjectUploadUrlPort: Send + Sync + 'static {
    /// Generate a presigned URL for a bulk-upload archive.
    fn put_upload_zip_staging_presigned_url(
        &self,
        key: BulkUploadStagingKey,
        sha: String,
    ) -> impl Future<Output = anyhow::Result<String>> + Send;

    /// Generate a presigned URL for document storage.
    fn put_document_storage_presigned_url(
        &self,
        key: String,
        sha: String,
        content_type: ContentType,
    ) -> impl Future<Output = anyhow::Result<String>> + Send;

    /// Generate a presigned URL for DOCX staging.
    fn put_docx_upload_presigned_url(
        &self,
        key: String,
        sha: String,
        content_type: ContentType,
    ) -> impl Future<Output = anyhow::Result<String>> + Send;

    /// Get the document-storage bucket name for internal destinations.
    fn document_storage_bucket(&self) -> &str;

    /// Get the DOCX-upload bucket name for internal destinations.
    fn docx_upload_bucket(&self) -> &str;
}

/// Port for updating persisted content-hash reference counts.
pub trait ShaCounterPort: Send + Sync + 'static {
    /// Decrement each SHA reference count by the supplied amount.
    fn decrement_counts(
        &self,
        sha_counts: &[(String, i64)],
    ) -> impl Future<Output = anyhow::Result<()>> + Send;
}

/// Port for publishing document search-removal and deletion work.
// TODO: Remove this port and its SQS adapter after the documents migration.
pub trait ProjectSearchIndexer: Send + Sync + 'static {
    /// Remove documents from the search index.
    fn remove_documents(
        &self,
        document_ids: Vec<String>,
    ) -> impl Future<Output = anyhow::Result<()>> + Send;

    /// Enqueue document deletion work as `(document_id, owner_id)` pairs.
    fn enqueue_document_deletes(
        &self,
        documents: Vec<(String, String)>,
    ) -> impl Future<Output = anyhow::Result<()>> + Send;
}

/// What a folder duplication needs from other domains, acting as the user who
/// duplicates the folder.
///
/// The composition root implements it over `entity_access` and the owning
/// domains' duplicate and move capabilities, so the projects domain never
/// depends on the documents or chat crates.
pub trait ProjectContentCopier: Send + Sync {
    /// The user's view receipt for `entity`, or `None` when they cannot view
    /// it or it no longer exists.
    fn view_receipt(
        &self,
        entity: &Entity<'static>,
    ) -> impl Future<
        Output = Result<Option<EntityAccessReceipt<ViewAccessLevel>>, EntityMutationErrorCode>,
    > + Send;

    /// Whether the user may add items to the project.
    fn can_add_to_project(
        &self,
        project_id: &str,
    ) -> impl Future<Output = Result<bool, EntityMutationErrorCode>> + Send;

    /// Duplicate the document or chat `receipt` covers, as the user, and file
    /// the copy in `project_id`, returning the copy. `name` is the source's
    /// name, kept on the copy where its domain allows a chosen name. On
    /// failure nothing this call created remains.
    fn copy_into_project(
        &self,
        receipt: EntityAccessReceipt<ViewAccessLevel>,
        name: String,
        project_id: &str,
    ) -> impl Future<Output = Result<Entity<'static>, EntityMutationErrorCode>> + Send;
}

/// Unwired upload-URL port for hosts that expose project operations without
/// upload flows (e.g. AI tools). Upload methods fail loudly if reached.
#[derive(Clone, Copy, Debug, Default)]
pub struct UnavailableProjectUploadUrlPort;

impl ProjectUploadUrlPort for UnavailableProjectUploadUrlPort {
    async fn put_upload_zip_staging_presigned_url(
        &self,
        _key: BulkUploadStagingKey,
        _sha: String,
    ) -> anyhow::Result<String> {
        anyhow::bail!("project upload URLs are not available in this host")
    }

    async fn put_document_storage_presigned_url(
        &self,
        _key: String,
        _sha: String,
        _content_type: ContentType,
    ) -> anyhow::Result<String> {
        anyhow::bail!("project upload URLs are not available in this host")
    }

    async fn put_docx_upload_presigned_url(
        &self,
        _key: String,
        _sha: String,
        _content_type: ContentType,
    ) -> anyhow::Result<String> {
        anyhow::bail!("project upload URLs are not available in this host")
    }

    fn document_storage_bucket(&self) -> &str {
        ""
    }

    fn docx_upload_bucket(&self) -> &str {
        ""
    }
}

/// Unwired bulk-upload port for hosts that expose project operations without
/// upload flows (e.g. AI tools). Methods fail loudly if reached.
#[derive(Clone, Copy, Debug, Default)]
pub struct UnavailableBulkUploadRequestPort;

impl BulkUploadRequestPort for UnavailableBulkUploadRequestPort {
    async fn create_bulk_upload_request(
        &self,
        _request_id: Uuid,
        _user_id: &str,
        _name: Option<&str>,
        _parent_id: Option<&str>,
    ) -> anyhow::Result<BulkUploadRequest> {
        anyhow::bail!("bulk-upload requests are not available in this host")
    }

    async fn get_bulk_upload_document_statuses(
        &self,
        _upload_request_id: &str,
    ) -> anyhow::Result<BulkUploadRequestDocuments> {
        anyhow::bail!("bulk-upload requests are not available in this host")
    }
}

/// Unwired content-hash counter for hosts that expose project operations
/// without deletion flows (e.g. AI tools). Fails loudly if reached.
#[derive(Clone, Copy, Debug, Default)]
pub struct UnavailableShaCounterPort;

impl ShaCounterPort for UnavailableShaCounterPort {
    async fn decrement_counts(&self, _sha_counts: &[(String, i64)]) -> anyhow::Result<()> {
        anyhow::bail!("content-hash counting is not available in this host")
    }
}

/// Unwired search indexer for hosts that expose project operations without
/// deletion flows (e.g. AI tools). Methods fail loudly if reached.
#[derive(Clone, Copy, Debug, Default)]
pub struct UnavailableProjectSearchIndexer;

impl ProjectSearchIndexer for UnavailableProjectSearchIndexer {
    async fn remove_documents(&self, _document_ids: Vec<String>) -> anyhow::Result<()> {
        anyhow::bail!("project search indexing is not available in this host")
    }

    async fn enqueue_document_deletes(
        &self,
        _documents: Vec<(String, String)>,
    ) -> anyhow::Result<()> {
        anyhow::bail!("project search indexing is not available in this host")
    }
}

/// Inbound-facing service interface for project operations.
pub trait ProjectService: Send + Sync + 'static {
    /// List projects visible through the user's project history.
    fn list_projects(
        &self,
        user_id: MacroUserIdStr<'static>,
    ) -> impl Future<Output = Result<Vec<Project>, ProjectError>> + Send;

    /// List non-deleted projects the user can access via `entity_access`.
    ///
    /// Includes pending uploads so in-progress folder trees appear in Drive.
    fn list_accessible_projects(
        &self,
        user_id: MacroUserIdStr<'static>,
    ) -> impl Future<Output = Result<Vec<Project>, ProjectError>> + Send;

    /// List pending root projects owned by the user.
    fn list_pending_projects(
        &self,
        user_id: MacroUserIdStr<'static>,
    ) -> impl Future<Output = Result<Vec<PendingProject>, ProjectError>> + Send;

    /// Get project metadata and the caller's access level.
    fn get_project(
        &self,
        receipt: EntityAccessReceipt<ViewAccessLevel>,
    ) -> impl Future<Output = Result<GetProjectResponseData, ProjectError>> + Send;

    /// Get depth-one project content with caller-specific access attribution.
    fn get_project_content(
        &self,
        receipt: EntityAccessReceipt<ViewAccessLevel>,
    ) -> impl Future<Output = Result<Vec<ItemWithUserAccessLevel>, ProjectError>> + Send;

    /// Get the live folders, documents, and chats below a project, at most
    /// `limit` folders and `limit` items (see [`ProjectRepo::get_project_tree`]).
    /// The receipt covers the project; callers check each entry themselves.
    fn get_project_tree(
        &self,
        receipt: EntityAccessReceipt<ViewAccessLevel>,
        limit: usize,
    ) -> impl Future<Output = Result<ProjectTree, ProjectError>> + Send;

    /// Get project share permissions for an owner.
    fn get_project_permissions(
        &self,
        receipt: EntityAccessReceipt<OwnerAccessLevel>,
    ) -> impl Future<Output = Result<SharePermissionV2, ProjectError>> + Send;

    /// Get the caller's access level from a validated receipt.
    fn get_project_access_level(
        &self,
        receipt: EntityAccessReceipt<ViewAccessLevel>,
    ) -> impl Future<Output = Result<AccessLevel, ProjectError>> + Send;

    /// Create a project owned by `principal`, optionally beneath an authorized
    /// parent.
    fn create_project(
        &self,
        principal: &CreationPrincipal,
        args: CreateProjectRequest,
    ) -> impl Future<Output = Result<Project, ProjectError>> + Send;

    /// Create a project that takes its last-edit time from what is put in
    /// it: it starts never edited and does not mark its parent updated, and
    /// documents created in it with their own dates date it and the projects
    /// above it. For importers, so a copied tree keeps its source's dates.
    fn create_project_dated_by_contents(
        &self,
        principal: &CreationPrincipal,
        args: CreateProjectRequest,
    ) -> impl Future<Output = Result<Project, ProjectError>> + Send;

    /// Edit project metadata and sharing settings.
    fn edit_project(
        &self,
        receipt: EntityAccessReceipt<EditAccessLevel>,
        project: BasicProject,
        args: PatchProjectRequestV2,
    ) -> impl Future<Output = Result<(), ProjectError>> + Send;

    /// Soft-delete a project subtree.
    fn soft_delete_project(
        &self,
        receipt: EntityAccessReceipt<OwnerAccessLevel>,
        project: BasicProject,
        actor_user_id: String,
    ) -> impl Future<Output = Result<SoftDeleteResult, ProjectError>> + Send;

    /// Permanently purge a soft-deleted project subtree.
    fn permanently_delete_project(
        &self,
        receipt: EntityAccessReceipt<OwnerAccessLevel>,
        project: BasicProject,
    ) -> impl Future<Output = Result<PurgedProjectTree, ProjectError>> + Send;

    /// Restore a soft-deleted project subtree.
    fn revert_delete_project(
        &self,
        receipt: EntityAccessReceipt<OwnerAccessLevel>,
        project: BasicProject,
    ) -> impl Future<Output = Result<RevertDeleteResult, ProjectError>> + Send;

    /// Create a pending project tree and its upload destinations.
    fn upload_folder(
        &self,
        actor: MacroUserIdStr<'static>,
        internal: bool,
        args: UploadFolderRequest,
    ) -> impl Future<Output = Result<UploadFolderResponseData, ProjectError>> + Send;

    /// Create a tracked request for extracting an uploaded archive.
    fn create_upload_extract_request(
        &self,
        actor: MacroUserIdStr<'static>,
        args: UploadExtractFolderRequest,
    ) -> impl Future<Output = Result<UploadExtractFolderResponseData, ProjectError>> + Send;

    /// Finalize the uploaded state of a project tree.
    fn mark_projects_uploaded(
        &self,
        root_project_id: &str,
    ) -> impl Future<Output = Result<Vec<String>, ProjectError>> + Send;

    /// Get project previews without applying per-project access filtering.
    fn get_batch_preview(
        &self,
        actor: Option<MacroUserIdStr<'static>>,
        project_ids: Vec<String>,
    ) -> impl Future<Output = Result<Vec<ProjectPreview>, ProjectError>> + Send;

    /// Get basic project metadata without performing access checks.
    fn internal_get_basic_project(
        &self,
        project_id: &str,
    ) -> impl Future<Output = Result<BasicProject, ProjectError>> + Send;
}