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.

9.0 KB
Raw Blame
//! Reading and editing uploaded Word (`.docx`) documents for AI tools.
//!
//! A DOCX has a live collaborative copy in the sync service; the editing
//! worker reads and edits that copy, so people with the document open see an
//! agent's edits as they land. The first editor to open an upload seeds the
//! copy; when an agent gets there first, this service seeds it the same way.

mod models;
mod seed;
pub use models::*;
pub use seed::seed_snapshot;

use super::{
    markdown_backfill::SyncServiceProbe,
    permission_token::encode_permission_token,
    ports::{DocumentService, editing::EditingWorkerService, markdown::SyncInitializeSnapshotPort},
};
use anyhow::Context;
use entity_access::domain::models::{EditAccessLevel, EntityAccessReceipt, ViewAccessLevel};
use macro_user_id::user_id::MacroUserIdStr;
use models_permissions::share_permission::access_level::AccessLevel;
use std::sync::Arc;

/// Most operations one edit may apply.
pub const MAX_OPERATIONS: usize = 50;

/// Longest author name an edit may record.
pub const MAX_AUTHOR_LENGTH: usize = 100;

/// Narrow document metadata capability the Word document workflows need.
#[cfg_attr(test, mockall::automock)]
pub trait WordDocumentLookup: Send + Sync + 'static {
    /// The document's file type, as stored.
    fn file_type(
        &self,
        document_id: &str,
    ) -> impl std::future::Future<Output = anyhow::Result<Option<String>>> + Send;

    /// The name a user goes by, when they set one.
    fn display_name(
        &self,
        user_id: &str,
    ) -> impl std::future::Future<Output = anyhow::Result<Option<String>>> + Send;
}

impl<D: DocumentService> WordDocumentLookup for D {
    async fn file_type(&self, document_id: &str) -> anyhow::Result<Option<String>> {
        Ok(self
            .internal_get_basic_document(document_id)
            .await?
            .file_type)
    }

    async fn display_name(&self, user_id: &str) -> anyhow::Result<Option<String>> {
        Ok(self.internal_get_user_display_name(user_id).await?)
    }
}

/// Reads uploaded Word files. Object-safe so hosts can wire a store into an
/// already-built tool context.
#[async_trait::async_trait]
pub trait WordDocumentFiles: Send + Sync + 'static {
    /// The DOCX as uploaded, or `None` while the upload is still being
    /// extracted.
    async fn original(&self, document_id: &str) -> anyhow::Result<Option<Vec<u8>>>;
}

/// A Word document request the caller can fix: the wrong file type, a bad
/// batch, an upload still being extracted, or operations the editor refused.
/// Nothing changed.
#[derive(Debug, thiserror::Error)]
#[error("{0}")]
pub struct WordDocumentRejected(pub String);

/// Used where no file store is wired: seeding fails with a clear message.
pub struct NoWordDocumentFiles;

#[async_trait::async_trait]
impl WordDocumentFiles for NoWordDocumentFiles {
    async fn original(&self, _document_id: &str) -> anyhow::Result<Option<Vec<u8>>> {
        anyhow::bail!("Word documents nobody has opened yet cannot be prepared from this host")
    }
}

/// Runs Word document workflows after the caller obtains the required receipt.
pub struct WordDocumentService<D, W, S> {
    documents: Arc<D>,
    worker: Arc<W>,
    sync: Arc<S>,
    files: Arc<dyn WordDocumentFiles>,
    token_secret: String,
}

impl<D, W, S> WordDocumentService<D, W, S>
where
    D: WordDocumentLookup,
    W: EditingWorkerService,
    S: SyncServiceProbe + SyncInitializeSnapshotPort,
{
    /// Compose the domain service from document, execution, sync and file
    /// ports.
    pub fn new(
        documents: Arc<D>,
        worker: Arc<W>,
        sync: Arc<S>,
        files: Arc<dyn WordDocumentFiles>,
        token_secret: String,
    ) -> Self {
        Self {
            documents,
            worker,
            sync,
            files,
            token_secret,
        }
    }

    /// Describe the live document with its paragraph and table ids.
    pub async fn read(
        &self,
        receipt: EntityAccessReceipt<ViewAccessLevel>,
        user: &MacroUserIdStr<'_>,
        actor: Option<&str>,
        start: Option<u32>,
        count: Option<u32>,
    ) -> anyhow::Result<WordDocumentResponse> {
        self.run(
            &receipt.entity().entity_id,
            user,
            actor,
            AccessLevel::View,
            WordDocumentRequest::Read { start, count },
        )
        .await
    }

    /// Apply an atomic batch of edits to the live document. Tracked changes
    /// and comments are attributed to `options.author`, else to the
    /// requesting user (never to the agent): they are the user's redline.
    pub async fn edit(
        &self,
        receipt: EntityAccessReceipt<EditAccessLevel>,
        user: &MacroUserIdStr<'_>,
        actor: Option<&str>,
        operations: Vec<WordDocumentOperation>,
        options: WordEditOptions,
    ) -> anyhow::Result<WordDocumentResponse> {
        if operations.is_empty() || operations.len() > MAX_OPERATIONS {
            return Err(WordDocumentRejected(format!(
                "Send between 1 and {MAX_OPERATIONS} operations."
            ))
            .into());
        }
        let author = match options.author.as_deref().map(str::trim) {
            Some(name) if !name.is_empty() => {
                if name.chars().count() > MAX_AUTHOR_LENGTH || name.contains(['\n', '\r']) {
                    return Err(WordDocumentRejected(format!(
                        "author must be one line of at most {MAX_AUTHOR_LENGTH} characters."
                    ))
                    .into());
                }
                name.to_owned()
            }
            _ => self.user_name(user).await,
        };
        self.run(
            &receipt.entity().entity_id,
            user,
            actor,
            AccessLevel::Edit,
            WordDocumentRequest::Edit {
                operations,
                track_changes: options.track_changes,
                author,
            },
        )
        .await
    }

    /// The requesting user's name as Word should show it: the name they set,
    /// else their email's local part.
    async fn user_name(&self, user: &MacroUserIdStr<'_>) -> String {
        match self.documents.display_name(user.as_ref()).await {
            Ok(Some(name)) => name.chars().take(MAX_AUTHOR_LENGTH).collect(),
            Ok(None) => email_name(user),
            Err(error) => {
                tracing::warn!(error = ?error, "could not look up the user's name");
                email_name(user)
            }
        }
    }

    async fn run(
        &self,
        document_id: &str,
        user: &MacroUserIdStr<'_>,
        actor: Option<&str>,
        access: AccessLevel,
        request: WordDocumentRequest,
    ) -> anyhow::Result<WordDocumentResponse> {
        let file_type = self.documents.file_type(document_id).await?;
        if file_type.as_deref() != Some("docx") {
            return Err(WordDocumentRejected(
                "This works on uploaded Word (.docx) documents only. Use EditDocument for Macro markdown documents and ReadContent for other files.".to_owned(),
            )
            .into());
        }
        let token = encode_permission_token(
            Some(user.to_string()),
            document_id.to_owned(),
            access,
            &self.token_secret,
            actor.map(str::to_owned),
        )?;
        self.ensure_live_copy(document_id).await?;
        self.worker
            .word_document(document_id, &token, &request)
            .await
    }

    /// Seed the live copy from the uploaded file unless someone already has.
    #[tracing::instrument(
        name = "word_document.ensure_live_copy",
        skip(self),
        fields(seeded, docx_bytes, snapshot_bytes),
        err
    )]
    async fn ensure_live_copy(&self, document_id: &str) -> anyhow::Result<()> {
        let exists = self.sync.exists(document_id).await?;
        tracing::Span::current().record("seeded", !exists);
        if exists {
            return Ok(());
        }
        let Some(original) = self.files.original(document_id).await? else {
            return Err(WordDocumentRejected(
                "This Word document is still being processed after upload. Try again in a few seconds.".to_owned(),
            )
            .into());
        };
        tracing::Span::current().record("docx_bytes", original.len());
        let snapshot = tokio::task::spawn_blocking(move || seed_snapshot(original))
            .await?
            .context("This Word document could not be opened for editing")?;
        tracing::Span::current().record("snapshot_bytes", snapshot.len());
        if let Err(error) = self
            .sync
            .initialize_from_snapshot(document_id, &snapshot)
            .await
        {
            // Someone opening the document may have seeded it first; both
            // seeds are the same document with the same ids.
            if !self.sync.exists(document_id).await? {
                return Err(error);
            }
        }
        Ok(())
    }
}

fn email_name(user: &MacroUserIdStr<'_>) -> String {
    let email = user.email_str();
    email.split('@').next().unwrap_or(email).to_owned()
}

#[cfg(test)]
mod test;