Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
//! The collab-surface service implementation.
#[cfg(test)]
mod test;
use std::sync::Arc;
use entity_access::domain::models::{AnyEntityPermission, EntityAccessReceipt};
use macro_sync_service_jwt::DocumentPermissionToken;
use macro_user_id::user_id::MacroUserIdStr;
use model_entity::{Entity, EntityType};
use models_permissions::share_permission::access_level::AccessLevel;
use uuid::Uuid;
use crate::domain::models::{
CollabSurface, CollabSurfaceError, SurfaceOwnership, SurfaceSnapshot, SurfaceState,
SurfaceUpdate, surface_ownership,
};
use crate::domain::ports::{
CollabSurfaceRepo, CollabSurfaceService, DocumentIds, FormIds, OwnedSurfaceService,
SurfaceInitializer,
};
use crate::domain::token::{
access_level_for, encode_service_surface_token, encode_surface_token, surface_access_level,
};
/// Upper bound on initial markdown, mirroring the lexical-service request cap.
const MAX_INITIAL_MARKDOWN_LEN: usize = 1_000_000;
/// What a new surface's sync-service session starts from.
#[derive(Clone, Copy)]
enum InitialContent<'a> {
/// Markdown, converted to a Loro snapshot by the initializer.
Markdown(&'a str),
/// An opaque Loro snapshot, stored as-is.
Snapshot(&'a [u8]),
}
/// Whether the public API may create and delete surfaces under `parent`.
fn caller_owned(parent: &Entity<'_>) -> bool {
surface_ownership(parent.entity_type) == Some(SurfaceOwnership::Callers)
}
/// The form ids of a service that only serves [`OwnedSurfaceService`]. It
/// implements no [`FormIds`], so such a service has no public API: the public
/// API takes caller-chosen ids and must keep them off forms' ids.
#[derive(Debug, Clone, Copy)]
pub struct OwnedSurfacesOnly;
/// Production implementation of [`CollabSurfaceService`] and
/// [`OwnedSurfaceService`]. The public API needs `Forms` to implement
/// [`FormIds`]; see [`CollabSurfaceServiceImpl::with_form_ids`].
pub struct CollabSurfaceServiceImpl<Repository, Initializer, Documents, Forms = OwnedSurfacesOnly> {
repo: Arc<Repository>,
initializer: Arc<Initializer>,
documents: Arc<Documents>,
forms: Arc<Forms>,
jwt_secret: String,
}
impl<Repository, Initializer, Documents>
CollabSurfaceServiceImpl<Repository, Initializer, Documents>
{
/// Build the owned-surface service from its ports and the sync-service
/// JWT secret.
pub fn new(
repo: Arc<Repository>,
initializer: Arc<Initializer>,
documents: Arc<Documents>,
jwt_secret: String,
) -> Self {
Self {
repo,
initializer,
documents,
forms: Arc::new(OwnedSurfacesOnly),
jwt_secret,
}
}
}
impl<Repository, Initializer, Documents, Forms>
CollabSurfaceServiceImpl<Repository, Initializer, Documents, Forms>
{
/// The same service with the forms domain's ids, which serves the public
/// API too.
pub fn with_form_ids<FormDomain: FormIds>(
self,
forms: Arc<FormDomain>,
) -> CollabSurfaceServiceImpl<Repository, Initializer, Documents, FormDomain> {
CollabSurfaceServiceImpl {
repo: self.repo,
initializer: self.initializer,
documents: self.documents,
forms,
jwt_secret: self.jwt_secret,
}
}
}
/// The parent entity and caller identity a receipt proves.
///
/// The receipt is the only source of the parent — a caller cannot name an
/// entity it has not proven access to, because there is nowhere else to put
/// the id. The receipt must also have been minted for this caller, or one
/// user could act using another's receipt.
fn resolve_parent(
user_id: &MacroUserIdStr<'_>,
receipt: &EntityAccessReceipt<AnyEntityPermission>,
) -> Result<Entity<'static>, CollabSurfaceError> {
let receipt_user = receipt
.get_authenticated_user()
.map_err(|_| CollabSurfaceError::AccessDenied)?;
if receipt_user.as_ref() != user_id.as_ref() {
return Err(CollabSurfaceError::AccessDenied);
}
let entity = receipt.entity();
Ok(entity
.entity_type
.with_entity_string(entity.entity_id.to_string()))
}
/// Surface ids are chosen by the caller, so the public API only takes random
/// ones (UUID v4 or v7).
fn is_random_id(id: Uuid) -> bool {
matches!(
id.get_version(),
Some(uuid::Version::Random | uuid::Version::SortRand)
)
}
/// Verify a receipt (already minted against the surface's parent by the
/// inbound layer) actually names that parent. Defense in depth: the inbound
/// layer resolves the parent via [`CollabSurfaceService::get_parent`], so a
/// mismatch means a coding error, not a malicious caller — but the check makes
/// the invariant unskippable.
fn verify_receipt_matches_parent(
surface: &CollabSurface,
parent: &Entity<'static>,
) -> Result<(), CollabSurfaceError> {
if surface.parent.entity_type != parent.entity_type
|| surface.parent.entity_id != parent.entity_id
{
return Err(CollabSurfaceError::AccessDenied);
}
Ok(())
}
impl<Repository, Initializer, Documents, Forms> CollabSurfaceService
for CollabSurfaceServiceImpl<Repository, Initializer, Documents, Forms>
where
Repository: CollabSurfaceRepo,
Initializer: SurfaceInitializer,
Documents: DocumentIds,
Forms: FormIds,
{
#[tracing::instrument(err, skip(self, user_id, parent_receipt, initial_markdown))]
async fn ensure_surface(
&self,
user_id: &MacroUserIdStr<'_>,
parent_receipt: EntityAccessReceipt<AnyEntityPermission>,
id: Uuid,
initial_markdown: String,
) -> Result<CollabSurface, CollabSurfaceError> {
let parent = resolve_parent(user_id, &parent_receipt)?;
if !caller_owned(&parent) {
return Err(CollabSurfaceError::AccessDenied);
}
// A form ensures its surface lazily, under its own id, so the id is
// the form's before any surface holds it. Checked before the existing
// row too, so nothing bound to a form's id is handed to a caller.
if self.forms.is_form_id(id).await? {
return Err(CollabSurfaceError::IdReserved);
}
self.ensure_bound(parent, id, InitialContent::Markdown(&initial_markdown))
.await
}
#[tracing::instrument(err, skip(self, user_id, parent_receipt))]
async fn get_surface(
&self,
user_id: &MacroUserIdStr<'_>,
parent_receipt: EntityAccessReceipt<AnyEntityPermission>,
id: Uuid,
) -> Result<CollabSurface, CollabSurfaceError> {
let parent = resolve_parent(user_id, &parent_receipt)?;
let surface = self.get_live(id).await?;
verify_receipt_matches_parent(&surface, &parent)?;
Ok(surface)
}
#[tracing::instrument(err, skip(self))]
async fn get_parent(&self, id: Uuid) -> Result<Entity<'static>, CollabSurfaceError> {
let parent = self.get_live(id).await?.parent;
if parent.entity_type == EntityType::Form && !self.parent_form_exists(&parent).await? {
// Its form was deleted without the forms domain retiring it.
self.retire_surface(id).await?;
return Err(CollabSurfaceError::NotFound);
}
Ok(parent)
}
#[tracing::instrument(err, skip(self, user_id, parent_receipt))]
async fn mint_token(
&self,
user_id: &MacroUserIdStr<'_>,
parent_receipt: EntityAccessReceipt<AnyEntityPermission>,
id: Uuid,
) -> Result<DocumentPermissionToken, CollabSurfaceError> {
let parent = resolve_parent(user_id, &parent_receipt)?;
let surface = self.get_live(id).await?;
verify_receipt_matches_parent(&surface, &parent)?;
// A pending row has not proven that its session is the surface's own
// (initialization failed or never ran), so it is not connectable.
if surface.state != SurfaceState::Ready {
return Err(CollabSurfaceError::NotReady);
}
// Checked on every mint, not only at creation, so a surface whose id
// names a document never connects to it, however it was bound.
self.refuse_document_id(surface.id).await?;
let access_level =
surface_access_level(parent.entity_type, parent_receipt.entity_permission())?;
encode_surface_token(
parent_receipt
.get_authenticated_user()
.map_err(|_| CollabSurfaceError::AccessDenied)?
.clone(),
surface.id.to_string(),
access_level,
&self.jwt_secret,
)
}
#[tracing::instrument(err, skip(self, user_id, parent_receipt))]
async fn delete_surface(
&self,
user_id: &MacroUserIdStr<'_>,
parent_receipt: EntityAccessReceipt<AnyEntityPermission>,
id: Uuid,
) -> Result<(), CollabSurfaceError> {
let parent = resolve_parent(user_id, &parent_receipt)?;
let surface = self.get_live(id).await?;
verify_receipt_matches_parent(&surface, &parent)?;
// A deleted id never comes back, so a surface its parent's domain owns
// (e.g. a project description) is retired only by that domain.
if !caller_owned(&parent) {
return Err(CollabSurfaceError::AccessDenied);
}
// Deletion requires an edit-capable permission on the parent; there is
// no per-surface owner. `access_level_for` already maps channel
// membership to Edit and view-only presences to View.
let level = access_level_for(parent_receipt.entity_permission())?;
if level < AccessLevel::Edit {
return Err(CollabSurfaceError::AccessDenied);
}
self.repo
.soft_delete(id)
.await
.map_err(|e| rootcause::Report::new(e).into_dynamic())?;
Ok(())
}
}
impl<Repository, Initializer, Documents, Forms> OwnedSurfaceService
for CollabSurfaceServiceImpl<Repository, Initializer, Documents, Forms>
where
Repository: CollabSurfaceRepo,
Initializer: SurfaceInitializer,
Documents: DocumentIds,
Forms: Send + Sync + 'static,
{
#[tracing::instrument(err, skip(self, initial_markdown))]
async fn ensure_owned_surface(
&self,
parent: Entity<'static>,
id: Uuid,
initial_markdown: String,
) -> Result<CollabSurface, CollabSurfaceError> {
self.ensure_bound(parent, id, InitialContent::Markdown(&initial_markdown))
.await
}
#[tracing::instrument(err, skip(self, snapshot), fields(snapshot_len = snapshot.len()))]
async fn ensure_owned_surface_from_snapshot(
&self,
parent: Entity<'static>,
id: Uuid,
snapshot: Vec<u8>,
) -> Result<CollabSurface, CollabSurfaceError> {
self.ensure_bound(parent, id, InitialContent::Snapshot(&snapshot))
.await
}
#[tracing::instrument(err, skip(self))]
async fn owned_surface_markdown(&self, id: Uuid) -> Result<Option<String>, CollabSurfaceError> {
match self.get_optional(id).await? {
Some(surface) if surface.state == SurfaceState::Ready => {
Ok(Some(self.initializer.markdown(&id.to_string()).await?))
}
_ => Ok(None),
}
}
#[tracing::instrument(err, skip(self))]
async fn owned_surface_snapshot(
&self,
parent: Entity<'static>,
id: Uuid,
) -> Result<SurfaceSnapshot, CollabSurfaceError> {
let surface = self.ready_owned_surface(&parent, id).await?;
let session_id = surface.id.to_string();
let token =
encode_service_surface_token(session_id.clone(), AccessLevel::View, &self.jwt_secret)?;
self.initializer.snapshot(&session_id, &token).await
}
#[tracing::instrument(
err,
skip(self, expected_revision, update),
fields(update_len = update.len())
)]
async fn update_owned_surface(
&self,
parent: Entity<'static>,
id: Uuid,
expected_revision: Vec<u8>,
update: Vec<u8>,
) -> Result<SurfaceUpdate, CollabSurfaceError> {
let surface = self.ready_owned_surface(&parent, id).await?;
let session_id = surface.id.to_string();
let token =
encode_service_surface_token(session_id.clone(), AccessLevel::Edit, &self.jwt_secret)?;
self.initializer
.update(&session_id, &token, &expected_revision, &update)
.await
}
#[tracing::instrument(err, skip(self))]
async fn retire_surface(&self, id: Uuid) -> Result<(), CollabSurfaceError> {
self.repo
.soft_delete(id)
.await
.map_err(|e| rootcause::Report::new(e).into_dynamic())?;
Ok(())
}
}
impl<Repository, Initializer, Documents, Forms>
CollabSurfaceServiceImpl<Repository, Initializer, Documents, Forms>
where
Repository: CollabSurfaceRepo,
Initializer: SurfaceInitializer,
Documents: DocumentIds,
{
/// Load-or-create surface `id` bound to `parent`, returning once it is
/// `ready`. See [`CollabSurfaceService::ensure_surface`] for the rules.
async fn ensure_bound(
&self,
parent: Entity<'static>,
id: Uuid,
initial_content: InitialContent<'_>,
) -> Result<CollabSurface, CollabSurfaceError> {
if !is_random_id(id) {
return Err(CollabSurfaceError::BadRequest(
"surface ids must be random UUIDs".to_string(),
));
}
match initial_content {
InitialContent::Markdown(markdown) if markdown.len() > MAX_INITIAL_MARKDOWN_LEN => {
return Err(CollabSurfaceError::BadRequest(format!(
"initial markdown exceeds {MAX_INITIAL_MARKDOWN_LEN} bytes"
)));
}
InitialContent::Snapshot([]) => {
return Err(CollabSurfaceError::BadRequest(
"initial snapshot is empty".to_string(),
));
}
InitialContent::Markdown(_) | InitialContent::Snapshot(_) => {}
}
// Fast path: the surface already exists. A `pending` row still gets
// its initialization retried in `finish_init`.
if let Some(existing) = self.get_optional(id).await? {
verify_receipt_matches_parent(&existing, &parent)?;
if existing.state == SurfaceState::Pending {
// A document may have taken the id since the row was written.
self.refuse_document_id(id).await?;
}
return self.finish_init(existing, initial_content).await;
}
// A new surface creates its own session, so its id must be free in the
// namespace surfaces share with documents: no document and no session
// yet. Checked before inserting, so a refusal leaves no row behind.
self.refuse_taken_id(id).await?;
let now = chrono::Utc::now();
let surface = CollabSurface {
id,
parent,
state: SurfaceState::Pending,
created_at: now,
updated_at: now,
};
let inserted = self
.repo
.insert(&surface)
.await
.map_err(|e| rootcause::Report::new(e).into_dynamic())?;
if !inserted {
// Lost a race with a concurrent ensure (which passed the same
// checks), or the id belongs to a soft-deleted surface (which never
// comes back).
let Some(existing) = self.get_optional(id).await? else {
return Err(CollabSurfaceError::Gone);
};
verify_receipt_matches_parent(&existing, &surface.parent)?;
return self.finish_init(existing, initial_content).await;
}
self.finish_init(surface, initial_content).await
}
/// The ready surface `id` under `parent`, for the domain that owns it to
/// read or write its state. Nothing here creates or initializes a surface.
async fn ready_owned_surface(
&self,
parent: &Entity<'static>,
id: Uuid,
) -> Result<CollabSurface, CollabSurfaceError> {
if surface_ownership(parent.entity_type) != Some(SurfaceOwnership::ParentDomain) {
return Err(CollabSurfaceError::AccessDenied);
}
let surface = self.get_live(id).await?;
verify_receipt_matches_parent(&surface, parent)?;
if surface.state != SurfaceState::Ready {
return Err(CollabSurfaceError::NotReady);
}
self.refuse_document_id(surface.id).await?;
Ok(surface)
}
/// Fetch a live (non-deleted) surface or `NotFound`.
async fn get_live(&self, id: Uuid) -> Result<CollabSurface, CollabSurfaceError> {
self.get_optional(id)
.await?
.ok_or(CollabSurfaceError::NotFound)
}
/// Fetch a live (non-deleted) surface, absent as `None`.
async fn get_optional(&self, id: Uuid) -> Result<Option<CollabSurface>, CollabSurfaceError> {
Ok(self
.repo
.get(id)
.await
.map_err(|e| rootcause::Report::new(e).into_dynamic())?)
}
/// Refuse an id that names a document. Surfaces share the document
/// namespace in sync-service, so a surface never uses a document's id.
async fn refuse_document_id(&self, id: Uuid) -> Result<(), CollabSurfaceError> {
if self.documents.is_document_id(id).await? {
return Err(CollabSurfaceError::IdReserved);
}
Ok(())
}
/// Refuse a new id that names a document or already has a sync-service
/// session: the initializer would take that session as this surface's. A
/// deleted surface keeps its session, so its id is `Gone` rather than
/// reserved; that is only looked up once the check fires.
async fn refuse_taken_id(&self, id: Uuid) -> Result<(), CollabSurfaceError> {
let session_id = id.to_string();
let (names_document, has_session) = tokio::try_join!(
async { Ok::<_, CollabSurfaceError>(self.documents.is_document_id(id).await?) },
self.initializer.session_exists(&session_id),
)?;
if !(names_document || has_session) {
return Ok(());
}
let deleted = self
.repo
.is_deleted(id)
.await
.map_err(|e| rootcause::Report::new(e).into_dynamic())?;
Err(if deleted {
CollabSurfaceError::Gone
} else {
CollabSurfaceError::IdReserved
})
}
/// Take a surface the caller may act on to `Ready`, (re)initializing its
/// sync-service session when it is still `Pending`. The initializer treats
/// an already-initialized session as success, so this is safe to run
/// concurrently and after partial failures: a pending row whose session
/// was initialized before `mark_ready` failed heals here.
async fn finish_init(
&self,
surface: CollabSurface,
initial_content: InitialContent<'_>,
) -> Result<CollabSurface, CollabSurfaceError> {
if surface.state == SurfaceState::Ready {
return Ok(surface);
}
let session_id = surface.id.to_string();
match initial_content {
InitialContent::Markdown(markdown) => {
self.initializer.initialize(&session_id, markdown).await?
}
InitialContent::Snapshot(snapshot) => {
self.initializer
.initialize_from_snapshot(&session_id, snapshot)
.await?
}
}
self.repo
.mark_ready(surface.id)
.await
.map_err(|e| rootcause::Report::new(e).into_dynamic())?;
Ok(CollabSurface {
state: SurfaceState::Ready,
..surface
})
}
}
impl<Repository, Initializer, Documents, Forms>
CollabSurfaceServiceImpl<Repository, Initializer, Documents, Forms>
where
Forms: FormIds,
{
/// Whether a form parent still exists, trashed or not. A form never comes
/// back once its row is gone.
async fn parent_form_exists(&self, parent: &Entity<'_>) -> Result<bool, CollabSurfaceError> {
let Ok(form) = parent.entity_id.parse::<Uuid>() else {
return Ok(false);
};
Ok(self.forms.is_form_id(form).await?)
}
}