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.4 KB
Raw Blame
//! The forms service: all authorization policy beyond receipt minting, and
//! every use case's orchestration, over its ports.

mod answers;
mod authoring;
mod create;
mod drafts;
mod layout;
mod lifecycle;
mod managed;
mod names;
mod responses;
mod sharing;
mod submit;
#[cfg(test)]
mod test;

use crate::domain::drafts::{FormDraftRepository, FormDraftStore};

use std::sync::Arc;

use databases::domain::models::{DatabaseError, TableDetail, Viewer};
use databases::domain::ports::{DatabaseMetadataReads, DatabaseRowReads, DatabasesService};
use entity_access::domain::models::{
    AccessLevel, EditAccessLevel, EntityAccessAuth, EntityAccessReceipt, EntityPermission,
    EntityType, OwnerAccessLevel, RequiredPermission, ViewAccessLevel,
};
use macro_event_broker::MacroEventBroker;
use macro_user_id::user_id::MacroUserIdStr;
use tracing::Level;

use crate::domain::events::{self, FormMacroEvent, FormTopicEvent};
use crate::domain::models::{
    DatabaseId, Form, FormAccess, FormDetail, FormError, FormId, FormLayout, FormTally, ListedForm,
    MyResponse, Respondent, ResponseSummary, StoredForm, Submission, SubmissionOutcome, UpdateForm,
};
use crate::domain::ports::{
    Clock, CreateFormCommand, FormAccessDirectory, FormEventPublisher, FormImageFiles, FormsRepo,
    FormsService,
};

/// Concrete forms service backed by its ports. `Databases` is the databases
/// domain service, the only way a form reads or writes its table; `Access`
/// lists the forms a user holds grants on; `Events` pings a form's open
/// pages after it changes; `Images` reads the files its branding shows.
#[derive(Debug, Clone)]
pub struct FormsServiceImpl<Repository, Databases, Access, Events, Now, Broker, Drafts, Images> {
    repository: Repository,
    databases: Arc<Databases>,
    access: Access,
    events: Events,
    clock: Now,
    broker: Broker,
    drafts: Drafts,
    images: Images,
}

fn repository_error<Error: std::error::Error + Send + Sync + 'static>(error: Error) -> FormError {
    FormError::Repository(rootcause::Report::new(error).into_dynamic())
}

/// A databases failure the form has no better word for.
fn database_error(error: DatabaseError) -> FormError {
    match error {
        DatabaseError::VersionConflict => FormError::Conflict,
        other => FormError::Database(other),
    }
}

/// The form a receipt was minted for.
fn receipt_form_id<Level: RequiredPermission>(
    receipt: &EntityAccessReceipt<Level>,
) -> Result<FormId, FormError> {
    let entity = receipt.entity();
    if entity.entity_type != EntityType::Form {
        return Err(FormError::NotFound);
    }
    entity.entity_id.parse().map_err(|_| FormError::NotFound)
}

/// The database a receipt was minted for.
fn receipt_database_id<Level: RequiredPermission>(
    receipt: &EntityAccessReceipt<Level>,
) -> Result<DatabaseId, FormError> {
    let entity = receipt.entity();
    if entity.entity_type != EntityType::Database {
        return Err(FormError::NotFound);
    }
    entity.entity_id.parse().map_err(|_| FormError::NotFound)
}

/// The caller's level a receipt proves. Receipts minted for internal callers
/// carry the level their minting asserted.
fn receipt_access<Level: RequiredPermission>(receipt: &EntityAccessReceipt<Level>) -> FormAccess {
    access_of(match receipt.entity_permission() {
        EntityPermission::AccessLevel { access_level } => *access_level,
        _ => AccessLevel::View,
    })
}

/// A grant's level as a form names it: comment is view on a form.
fn access_of(level: AccessLevel) -> FormAccess {
    match level {
        AccessLevel::Owner => FormAccess::Owner,
        AccessLevel::Edit => FormAccess::Edit,
        AccessLevel::View | AccessLevel::Comment => FormAccess::View,
    }
}

/// Who a receipt says is acting, as events record it. Internal and
/// anonymous receipts have nobody to attribute the change to.
fn receipt_attribution<Level: RequiredPermission>(
    receipt: &EntityAccessReceipt<Level>,
) -> Option<events::Attribution> {
    match receipt.auth() {
        EntityAccessAuth::Authenticated(user) => Some(events::Attribution::user(user.clone())),
        EntityAccessAuth::Bot(bot) => Some(events::Attribution {
            actor: activity::Actor::new_from_bot(bot.bot_id()),
            on_behalf_of: bot.scope().acting_user_id().cloned(),
        }),
        EntityAccessAuth::Unauthenticated | EntityAccessAuth::Internal => None,
    }
}

/// Who is responding under a receipt: the signed-in person, or the agent's
/// user, or nobody.
fn receipt_respondent<Level: RequiredPermission>(
    receipt: &EntityAccessReceipt<Level>,
) -> Respondent {
    match receipt.acting_user_id() {
        Some(user) => Respondent::Member(user.clone()),
        None => Respondent::Anonymous,
    }
}

/// A form's owner, as the user its writes act for when nobody signed in.
fn owner_of(form: &Form) -> Result<MacroUserIdStr<'static>, FormError> {
    MacroUserIdStr::try_from(form.owner_id.clone()).map_err(|error| {
        FormError::Repository(rootcause::report!(
            "stored form owner is not a user id: {error}"
        ))
    })
}

/// The receipt the forms service acts on its table's database with: it has
/// already decided the caller may do what it is about to do.
fn internal_receipt<Level: RequiredPermission>(
    database_id: DatabaseId,
) -> EntityAccessReceipt<Level> {
    EntityAccessReceipt::dangerously_assert_internal_user(
        &database_id.to_string(),
        EntityType::Database,
    )
}

impl<Repository, Databases, Access, Events, Now, Broker, Drafts, Images>
    FormsServiceImpl<Repository, Databases, Access, Events, Now, Broker, Drafts, Images>
where
    Repository: FormsRepo + FormDraftRepository,
    Databases: DatabasesService + DatabaseRowReads + DatabaseMetadataReads,
    Access: FormAccessDirectory,
    Events: FormEventPublisher,
    Now: Clock,
    Broker: MacroEventBroker,
    Drafts: FormDraftStore,
    Images: FormImageFiles,
{
    /// Create a forms service from its ports.
    #[expect(clippy::too_many_arguments, reason = "one adapter per port")]
    pub fn new(
        repository: Repository,
        databases: Arc<Databases>,
        access: Access,
        events: Events,
        clock: Now,
        broker: Broker,
        drafts: Drafts,
        images: Images,
    ) -> Self {
        Self {
            repository,
            databases,
            access,
            events,
            clock,
            broker,
            drafts,
            images,
        }
    }

    /// Publish one domain event. The change it describes already committed,
    /// so a broker failure is logged rather than surfaced.
    fn emit(&self, event: FormTopicEvent) {
        if let Err(error) = self.broker.send_event(&FormMacroEvent::new(event)) {
            tracing::warn!(error = ?error, "failed to publish form event");
        }
    }

    /// Now, to the microsecond, as a stored timestamp keeps it, so what a
    /// write answers equals what is read back.
    fn now(&self) -> chrono::DateTime<chrono::Utc> {
        use chrono::SubsecRound;
        self.clock.now().trunc_subsecs(6)
    }

    /// Tell the form's open pages it changed. The change already committed,
    /// so a failed ping is logged rather than surfaced; pages still read
    /// fresh on their next load.
    async fn announce(&self, form: FormId) {
        if let Err(error) = self.events.form_changed(form).await {
            tracing::warn!(error = ?error, form_id = %form, "failed to announce a form change");
        }
    }

    /// A form whatever its trash state; lifecycle operations act on trashed
    /// ones too.
    async fn stored_form(&self, id: FormId) -> Result<StoredForm, FormError> {
        self.repository
            .form(id)
            .await
            .map_err(repository_error)?
            .ok_or(FormError::NotFound)
    }

    /// A form that is not in the trash, as stored; a trashed one reads as
    /// missing.
    async fn live_stored_form(&self, id: FormId) -> Result<StoredForm, FormError> {
        let stored = self.stored_form(id).await?;
        if stored.trashed_at.is_some() {
            return Err(FormError::NotFound);
        }
        Ok(stored)
    }

    /// A form that is not in the trash, under the name it goes by.
    async fn live_form(&self, id: FormId) -> Result<Form, FormError> {
        let stored = self.live_stored_form(id).await?;
        self.named(stored.form, stored.name_follows_database).await
    }

    /// The form's table, read under the form's internal receipt; `None` when
    /// its database is in the trash or the table is gone.
    async fn table_of(&self, form: &Form) -> Result<Option<TableDetail>, FormError> {
        let detail = match self
            .databases
            .get_database(internal_receipt::<ViewAccessLevel>(form.database_id))
            .await
        {
            Ok(detail) => detail,
            Err(DatabaseError::NotFound) => return Ok(None),
            Err(error) => return Err(database_error(error)),
        };
        Ok(detail
            .tables
            .into_iter()
            .find(|table| table.table.id == form.table_id))
    }

    /// [`Self::table_of`], refusing a form whose table is gone.
    async fn live_table_of(&self, form: &Form) -> Result<TableDetail, FormError> {
        self.table_of(form).await?.ok_or(FormError::TableGone)
    }
}

/// Validate a one-line name: trimmed, nonempty, not too long.
fn validated_name(name: &str) -> Result<String, FormError> {
    let trimmed = name.trim();
    if trimmed.is_empty() {
        return Err(FormError::InvalidName("a form needs a name"));
    }
    if trimmed.chars().count() > models_forms::MAX_TITLE_LENGTH {
        return Err(FormError::InvalidName("the name is too long"));
    }
    Ok(trimmed.to_string())
}

/// Refuse a text longer than `max` characters.
fn within(text: &str, max: usize) -> Result<(), FormError> {
    if text.chars().count() > max {
        return Err(FormError::InvalidLayout(
            models_forms::LayoutProblem::TextTooLong { max },
        ));
    }
    Ok(())
}

impl<Repository, Databases, Access, Events, Now, Broker, Drafts, Images> FormsService
    for FormsServiceImpl<Repository, Databases, Access, Events, Now, Broker, Drafts, Images>
where
    Repository: FormsRepo + FormDraftRepository,
    Databases: DatabasesService + DatabaseRowReads + DatabaseMetadataReads,
    Access: FormAccessDirectory,
    Events: FormEventPublisher,
    Now: Clock,
    Broker: MacroEventBroker,
    Drafts: FormDraftStore,
    Images: FormImageFiles,
{
    async fn collaborate_form(
        &self,
        receipt: EntityAccessReceipt<EditAccessLevel>,
    ) -> Result<models_forms::FormCollaboration, FormError> {
        self.collaborate(&receipt).await
    }

    #[tracing::instrument(skip(self, creator, command), err)]
    async fn create_form(
        &self,
        creator: Viewer,
        command: CreateFormCommand,
    ) -> Result<FormDetail, FormError> {
        self.create(creator, command).await
    }

    #[tracing::instrument(skip(self, viewer), err)]
    async fn accessible_forms(&self, viewer: Viewer) -> Result<Vec<ListedForm>, FormError> {
        self.catalog(&viewer).await
    }

    #[tracing::instrument(skip(self, receipt), err)]
    async fn forms_for_database(
        &self,
        receipt: EntityAccessReceipt<ViewAccessLevel>,
    ) -> Result<Vec<Form>, FormError> {
        let database_id = receipt_database_id(&receipt)?;
        let forms = self
            .repository
            .forms_for_database(database_id)
            .await
            .map_err(repository_error)?;
        self.named_forms(forms).await
    }

    #[tracing::instrument(skip(self, receipt), err)]
    async fn get_form(
        &self,
        receipt: EntityAccessReceipt<ViewAccessLevel>,
    ) -> Result<FormDetail, FormError> {
        self.read_detail(&receipt).await
    }

    #[tracing::instrument(skip(self, receipt, update), err)]
    async fn update_form(
        &self,
        receipt: EntityAccessReceipt<EditAccessLevel>,
        update: UpdateForm,
    ) -> Result<Form, FormError> {
        self.change_facts(&receipt, update).await
    }

    #[tracing::instrument(skip(self, receipt, layout), err)]
    async fn put_layout(
        &self,
        receipt: EntityAccessReceipt<EditAccessLevel>,
        layout: FormLayout,
    ) -> Result<models_forms::FormCollaboration, FormError> {
        self.replace_layout(&receipt, layout).await
    }

    #[tracing::instrument(skip(self, receipt, submission), err)]
    async fn submit_response(
        &self,
        receipt: EntityAccessReceipt<ViewAccessLevel>,
        submission: Submission,
    ) -> Result<SubmissionOutcome, FormError> {
        self.submit(&receipt, submission).await
    }

    #[tracing::instrument(skip(self, receipt), err(level = Level::DEBUG))]
    async fn my_response(
        &self,
        receipt: EntityAccessReceipt<ViewAccessLevel>,
    ) -> Result<MyResponse, FormError> {
        self.own_response(&receipt).await
    }

    #[tracing::instrument(skip(self, receipt, submission), err)]
    async fn edit_my_response(
        &self,
        receipt: EntityAccessReceipt<ViewAccessLevel>,
        submission: Submission,
    ) -> Result<SubmissionOutcome, FormError> {
        self.edit(&receipt, submission).await
    }

    #[tracing::instrument(skip(self, receipt), err)]
    async fn response_summary(
        &self,
        receipt: EntityAccessReceipt<EditAccessLevel>,
    ) -> Result<ResponseSummary, FormError> {
        self.summary(&receipt).await
    }

    #[tracing::instrument(skip(self, receipt), err)]
    async fn tally(
        &self,
        receipt: EntityAccessReceipt<ViewAccessLevel>,
    ) -> Result<FormTally, FormError> {
        self.count_choices(&receipt).await
    }

    #[tracing::instrument(skip(self, receipt), err)]
    async fn rename_form(
        &self,
        receipt: EntityAccessReceipt<EditAccessLevel>,
        name: String,
    ) -> Result<Form, FormError> {
        self.rename(&receipt, &name).await
    }

    #[tracing::instrument(skip(self, receipt), err)]
    async fn trash_form(
        &self,
        receipt: EntityAccessReceipt<OwnerAccessLevel>,
    ) -> Result<(), FormError> {
        self.trash(&receipt).await
    }

    #[tracing::instrument(skip(self, receipt), err)]
    async fn restore_form(
        &self,
        receipt: EntityAccessReceipt<OwnerAccessLevel>,
    ) -> Result<(), FormError> {
        self.restore(&receipt).await
    }

    #[tracing::instrument(skip(self, receipt), err)]
    async fn delete_form_permanently(
        &self,
        receipt: EntityAccessReceipt<OwnerAccessLevel>,
    ) -> Result<(), FormError> {
        self.purge(&receipt).await
    }
}