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.

22.3 KB
Raw Blame
//! Ports between the service and its adapters. `CellStore` is the one place
//! a batch's writes, schema and data, commit together.

use std::collections::HashMap;

use chrono::{DateTime, Utc};
use entity_access::domain::models::{
    AccessLevel, EditAccessLevel, EntityAccessReceipt, OwnerAccessLevel, ViewAccessLevel,
};
use macro_user_id::user_id::MacroUserIdStr;
use models_properties::service::property_definition_with_options::PropertyDefinitionWithOptions;
use models_properties::service::property_option::PropertyOptionValue;
use models_properties::service::property_value::PropertyValue;

use crate::domain::journal::{
    ChangeRecord, JournalActor, JournaledRowChange, RowHistoryEntry, TableChanges, UndoOutcome,
    VersionTouches,
};
use crate::domain::models::{
    AppliedOps, Awareness, CardPosition, ChangeId, Column, ColumnCast, ColumnConversion, ColumnId,
    CreateDatabase, Database, DatabaseDetail, DatabaseError, DatabaseId, DatabaseView, FirstTable,
    InferColumnType, InferColumnTypeOutcome, ListedDatabase, OpBatch, PropertyDefinitionId,
    QueryDefinition, QueryId, RowId, RowRef, SavedQuery, SavedQueryError, Table, TableId,
    TableVersion, ViewId, Viewer, Writes, WritesOutcome,
};
use models_databases::{ColumnKind, OpResult};

/// Persistence for databases, tables, column placements and row identities.
pub trait DatabasesRepo: Send + Sync + 'static {
    /// The error type returned by repository operations.
    type Error: std::error::Error + Send + Sync + 'static;

    /// Create a database with its first table and that table's title
    /// column, granting the creator owner access, all or nothing.
    fn create_database(
        &self,
        command: &CreateDatabase,
        first_table: FirstTable,
    ) -> impl Future<Output = Result<Database, Self::Error>> + Send;

    /// A database and its tables, if it exists.
    fn get_database(
        &self,
        id: DatabaseId,
    ) -> impl Future<Output = Result<Option<(Database, Vec<Table>)>, Self::Error>> + Send;

    /// Rename a database; `false` when it is gone.
    fn rename_database(
        &self,
        id: DatabaseId,
        name: &str,
    ) -> impl Future<Output = Result<bool, Self::Error>> + Send;

    /// Move a database to the trash; `false` when it is gone.
    fn trash_database(
        &self,
        id: DatabaseId,
        trashed_at: DateTime<Utc>,
    ) -> impl Future<Output = Result<bool, Self::Error>> + Send;

    /// Restore a trashed database; `false` when it is gone.
    fn restore_database(
        &self,
        id: DatabaseId,
    ) -> impl Future<Output = Result<bool, Self::Error>> + Send;

    /// File a live database in a folder, or at the root when `project_id`
    /// is `None`, swapping the grants it inherits from folders to match;
    /// `false` when it is trashed or gone.
    fn move_database(
        &self,
        id: DatabaseId,
        project_id: Option<&str>,
    ) -> impl Future<Output = Result<bool, Self::Error>> + Send;

    /// Remove a database permanently.
    fn delete_database(
        &self,
        id: DatabaseId,
    ) -> impl Future<Output = Result<(), Self::Error>> + Send;

    /// Settle an untyped column on a definition, provided no row has a value
    /// in it yet, journaling the change as `actor`'s.
    fn infer_column_type(
        &self,
        table: &Table,
        column: &Column,
        definition_id: PropertyDefinitionId,
        actor: &JournalActor,
    ) -> impl Future<Output = Result<Option<TableVersion>, Self::Error>> + Send;

    /// Every row of a table, in position order.
    fn row_refs(
        &self,
        table_id: TableId,
    ) -> impl Future<Output = Result<Vec<RowRef>, Self::Error>> + Send;

    /// Current versions for a set of tables.
    fn table_versions(
        &self,
        table_ids: &[TableId],
    ) -> impl Future<Output = Result<HashMap<TableId, TableVersion>, Self::Error>> + Send;

    /// Databases by id (missing ids are skipped).
    fn databases_by_ids(
        &self,
        ids: &[DatabaseId],
    ) -> impl Future<Output = Result<Vec<Database>, Self::Error>> + Send;

    /// Every table of the given databases, ordered by database then position.
    fn tables_for_databases(
        &self,
        database_ids: &[DatabaseId],
    ) -> impl Future<Output = Result<Vec<Table>, Self::Error>> + Send;

    /// Every column placement of the given tables, ordered by table then position.
    fn columns_for_tables(
        &self,
        table_ids: &[TableId],
    ) -> impl Future<Output = Result<Vec<Column>, Self::Error>> + Send;

    /// Every view of the given tables, ordered by table then position.
    fn views_for_tables(
        &self,
        table_ids: &[TableId],
    ) -> impl Future<Output = Result<Vec<DatabaseView>, Self::Error>> + Send;

    /// Where a board's cards sit, those that have a place.
    fn view_positions(
        &self,
        view_id: ViewId,
    ) -> impl Future<Output = Result<Vec<CardPosition>, Self::Error>> + Send;

    /// Store a new, immutable query.
    fn save_query(
        &self,
        database_id: Option<DatabaseId>,
        definition: &QueryDefinition,
        created_by: &MacroUserIdStr<'_>,
    ) -> impl Future<Output = Result<SavedQuery, Self::Error>> + Send;

    /// A saved query, if it exists.
    fn get_query(
        &self,
        id: QueryId,
    ) -> impl Future<Output = Result<Option<SavedQuery>, Self::Error>> + Send;

    /// One journaled change of a database, with the rows and columns it
    /// touched; `None` when the database has no such change.
    fn change(
        &self,
        database_id: DatabaseId,
        change: ChangeId,
    ) -> impl Future<Output = Result<Option<ChangeRecord>, Self::Error>> + Send;

    /// A table's journaled changes after a version, oldest first, with the
    /// rows and columns each touched.
    fn changes_after(
        &self,
        table_id: TableId,
        version: TableVersion,
    ) -> impl Future<Output = Result<Vec<ChangeRecord>, Self::Error>> + Send;

    /// What each journaled version of a table after `version` touched,
    /// oldest first.
    fn touches_after(
        &self,
        table_id: TableId,
        version: TableVersion,
    ) -> impl Future<Output = Result<Vec<VersionTouches>, Self::Error>> + Send;

    /// A row's journaled changes in one table of a database, newest first,
    /// the row's removal among them.
    fn row_history(
        &self,
        database_id: DatabaseId,
        table_id: TableId,
        row_id: RowId,
    ) -> impl Future<Output = Result<Vec<JournaledRowChange>, Self::Error>> + Send;
}

/// Reusable database storage without a Macro entity, owner grant, or trash state.
/// Callers are trusted domain services: each consumer must authorize its own
/// resource and validate writes before using this port. Macro database requests
/// use [`CellStore`] to enforce the app entity's lifecycle in the transaction.
pub trait DatabaseStorage: Send + Sync + 'static {
    /// Persistence failure, including an attempt to delete an attached resource.
    type Error: std::error::Error + Send + Sync + 'static;

    /// Allocate an empty core database without creating an app entity or grants.
    fn create_storage(&self) -> impl Future<Output = Result<DatabaseId, Self::Error>> + Send;

    /// A bounded page of identities from a host-authorized storage table.
    fn storage_row_page(
        &self,
        table: TableId,
        after: Option<RowId>,
        limit: i64,
    ) -> impl Future<Output = Result<Vec<RowRef>, Self::Error>> + Send;

    /// Delete unbound storage, its tables, cells, definitions and journal.
    /// An attached app entity prevents deletion through its foreign key.
    fn delete_storage(
        &self,
        id: DatabaseId,
    ) -> impl Future<Output = Result<(), Self::Error>> + Send;

    /// Apply a validated batch atomically, checking resource existence and table
    /// versions. Consumer-specific entity lifecycle and access are the caller's.
    fn apply_storage_writes(
        &self,
        writes: &Writes,
    ) -> impl Future<Output = Result<WritesOutcome, Self::Error>> + Send;
}

/// A row's cells, kept by the properties system as entity properties of the
/// `DATABASE_ROW` entity the row id names. Authorization is the domain
/// service's, resolved through the row's database; the store trusts its
/// caller.
pub trait CellStore: Send + Sync + 'static {
    /// The error type returned by the store.
    type Error: std::error::Error + Send + Sync + 'static;

    /// The cells of these rows, keyed by row then definition. A row with no
    /// cells is absent from the map.
    fn cells(
        &self,
        rows: &[RowId],
    ) -> impl Future<
        Output = Result<HashMap<RowId, HashMap<PropertyDefinitionId, PropertyValue>>, Self::Error>,
    > + Send;

    /// One column's cells of these rows: what `definition` holds on each, for
    /// the rows where it holds something.
    fn column_cells(
        &self,
        rows: &[RowId],
        definition: PropertyDefinitionId,
    ) -> impl Future<Output = Result<HashMap<RowId, PropertyValue>, Self::Error>> + Send;

    /// Apply a request's writes in one transaction, in order: schema, row
    /// identities, cells and options together. The database is locked (for
    /// a write to its tables) or shared, each written table locked, checked
    /// live and at its expected version, each new definition created before
    /// any column binds it, each updated or deleted row checked to belong to
    /// its table, each related row to its target table, each changed option
    /// or column to its definition, all affected required cells checked in the final
    /// batch state, and each changed table's version bumped
    /// once. Anything but [`WritesOutcome::Applied`] wrote nothing.
    fn apply_writes(
        &self,
        writes: &Writes,
    ) -> impl Future<Output = Result<WritesOutcome, Self::Error>> + Send;
}

/// Which databases a viewer can reach, as `entity_access` answers it: the
/// boundary of what a listing, and so the SQL adapter's catalog, can see.
/// Trash is not its concern: a trashed database's grants are still answered,
/// and the service drops them.
pub trait AccessDirectory: Send + Sync + 'static {
    /// The error type returned by directory operations.
    type Error: std::error::Error + Send + Sync + 'static;

    /// Every database the viewer holds a grant on, at the highest level.
    fn accessible_databases(
        &self,
        viewer: &Viewer,
    ) -> impl Future<Output = Result<Vec<(DatabaseId, AccessLevel)>, Self::Error>> + Send;

    /// The viewer's highest level on one database; `None` without a grant.
    fn database_access(
        &self,
        viewer: &Viewer,
        database_id: DatabaseId,
    ) -> impl Future<Output = Result<Option<AccessLevel>, Self::Error>> + Send;
}

/// The definitions behind columns: creating database-owned ones, binding
/// existing ones, and reading them back with their options.
pub trait ColumnDefinitionStore: Send + Sync + 'static {
    /// The error type returned by the store.
    type Error: std::error::Error + Send + Sync + 'static;

    /// An existing definition the viewer may bind in `database_id`; `None`
    /// when it is missing or not theirs to bind.
    fn bindable_definition(
        &self,
        database_id: DatabaseId,
        viewer: &Viewer,
        id: PropertyDefinitionId,
    ) -> impl Future<Output = Result<Option<PropertyDefinitionId>, Self::Error>> + Send;

    /// Create a definition owned by the database with its first options, in
    /// display order, together. Each option takes the palette colour of its
    /// position (`properties::TagColor::for_position`).
    fn create_typed_definition(
        &self,
        database_id: DatabaseId,
        name: &str,
        data_type: models_properties::DataType,
        is_multi_select: bool,
        specific_entity_type: Option<models_properties::EntityType>,
        options: &[PropertyOptionValue],
    ) -> impl Future<Output = Result<PropertyDefinitionWithOptions, Self::Error>> + Send;

    /// Remove a definition that no column binds any more.
    fn delete_unused_definition(
        &self,
        id: PropertyDefinitionId,
    ) -> impl Future<Output = Result<(), Self::Error>> + Send;

    /// Definitions by id, with their options.
    fn definitions(
        &self,
        ids: &[PropertyDefinitionId],
    ) -> impl Future<Output = Result<Vec<PropertyDefinitionWithOptions>, Self::Error>> + Send;

    /// The definitions among `ids` the viewer may change as the properties
    /// system decides it for definitions outside any database: their own, or
    /// a team's they belong to; never a system one.
    fn editable_definitions(
        &self,
        viewer: &Viewer,
        ids: &[PropertyDefinitionId],
    ) -> impl Future<Output = Result<Vec<PropertyDefinitionId>, Self::Error>> + Send;
}

/// Liveness: tell open clients a database or table changed.
pub trait TableEventPublisher: Send + Sync + 'static {
    /// The error type returned by the publisher.
    type Error: std::error::Error + Send + Sync + 'static;

    /// Announce changed database metadata so viewers re-read it as themselves.
    fn database_changed(
        &self,
        database_id: DatabaseId,
    ) -> impl Future<Output = Result<(), Self::Error>> + Send;

    /// Announce a table's new version.
    fn table_changed(
        &self,
        database_id: DatabaseId,
        table_id: TableId,
        version: TableVersion,
    ) -> impl Future<Output = Result<(), Self::Error>> + Send;

    /// Relay where a viewer is to the database's other viewers, and whether
    /// their grant lets them edit.
    fn awareness(
        &self,
        database_id: DatabaseId,
        user_id: &MacroUserIdStr<'_>,
        can_edit: bool,
        state: &Awareness,
    ) -> impl Future<Output = Result<(), Self::Error>> + Send;
}

/// The databases domain service.
pub trait DatabasesService: Send + Sync + 'static {
    /// Create a database with a starter table.
    fn create_database(
        &self,
        command: CreateDatabase,
    ) -> impl Future<Output = Result<Database, DatabaseError>> + Send;

    /// Every database the viewer can see.
    fn list_databases(
        &self,
        viewer: Viewer,
    ) -> impl Future<Output = Result<Vec<ListedDatabase>, DatabaseError>> + Send;

    /// Every database [`Self::list_databases`] answers, each with its tables
    /// and columns, read in one batch.
    fn database_details(
        &self,
        viewer: Viewer,
    ) -> impl Future<Output = Result<Vec<DatabaseDetail>, DatabaseError>> + Send;

    /// A database with its tables and columns.
    fn get_database(
        &self,
        receipt: EntityAccessReceipt<ViewAccessLevel>,
    ) -> impl Future<Output = Result<DatabaseDetail, DatabaseError>> + Send;

    /// Rename a database.
    fn rename_database(
        &self,
        receipt: EntityAccessReceipt<EditAccessLevel>,
        name: String,
    ) -> impl Future<Output = Result<Database, DatabaseError>> + Send;

    /// Move a database to the trash.
    fn trash_database(
        &self,
        receipt: EntityAccessReceipt<OwnerAccessLevel>,
    ) -> impl Future<Output = Result<(), DatabaseError>> + Send;

    /// Restore a trashed database.
    fn restore_database(
        &self,
        receipt: EntityAccessReceipt<OwnerAccessLevel>,
    ) -> impl Future<Output = Result<(), DatabaseError>> + Send;

    /// Remove a database permanently.
    fn delete_database_permanently(
        &self,
        receipt: EntityAccessReceipt<OwnerAccessLevel>,
    ) -> impl Future<Output = Result<(), DatabaseError>> + Send;

    /// Settle an untyped column's type from its first value.
    fn infer_column_type(
        &self,
        receipt: EntityAccessReceipt<EditAccessLevel>,
        command: InferColumnType,
    ) -> impl Future<Output = Result<InferColumnTypeOutcome, DatabaseError>> + Send;

    /// What changing a column to each type the type menu offers would do to
    /// its values, read in one pass without changing anything.
    fn column_casts(
        &self,
        receipt: EntityAccessReceipt<ViewAccessLevel>,
        table_id: TableId,
        column_id: ColumnId,
    ) -> impl Future<Output = Result<Vec<ColumnCast>, DatabaseError>> + Send;

    /// What one column's values become under `to`: the values that
    /// convert, for a new column of that type beside it, which leaves the
    /// column itself as it is. Changes nothing.
    fn column_conversion(
        &self,
        receipt: EntityAccessReceipt<ViewAccessLevel>,
        table_id: TableId,
        column_id: ColumnId,
        to: ColumnKind,
    ) -> impl Future<Output = Result<ColumnConversion, DatabaseError>> + Send;

    /// Apply a batch of ops to the receipt's database, in order, in one
    /// transaction: all of them, or, when one is refused, none. Every write
    /// to a database's schema or data is one of these ops. A later op may
    /// name what an earlier one created under the id its client minted. Ops
    /// are last-write-wins unless the batch names base versions.
    fn apply_ops(
        &self,
        receipt: EntityAccessReceipt<EditAccessLevel>,
        viewer: Viewer,
        batch: OpBatch,
    ) -> impl Future<Output = Result<Vec<OpResult>, DatabaseError>> + Send;

    /// [`Self::apply_ops`], answering with the journal's change for each
    /// table version the batch produced, which the caller can undo.
    fn apply_ops_with_changes(
        &self,
        receipt: EntityAccessReceipt<EditAccessLevel>,
        viewer: Viewer,
        batch: OpBatch,
    ) -> impl Future<Output = Result<AppliedOps, DatabaseError>> + Send;

    /// Undo one of the viewer's own changes: apply its inverse as a new,
    /// journaled batch, guarded against what others changed since. A cell
    /// changed since is left alone; anything else changed since refuses the
    /// undo. Redo is undoing the undo's change.
    fn undo_change(
        &self,
        receipt: EntityAccessReceipt<EditAccessLevel>,
        viewer: Viewer,
        change: ChangeId,
    ) -> impl Future<Output = Result<UndoOutcome, DatabaseError>> + Send;

    /// Where a board's cards sit: their lane and key, for the cards that
    /// have been placed. Rows that were never moved by hand have none, and
    /// show after the placed ones.
    fn view_positions(
        &self,
        receipt: EntityAccessReceipt<ViewAccessLevel>,
        view_id: ViewId,
    ) -> impl Future<Output = Result<Vec<CardPosition>, DatabaseError>> + Send;

    /// A row's history: every committed change that touched it, newest
    /// first, with who made it, when, and the values of the columns it
    /// touched before and after. It reads after the row is removed, too.
    fn row_history(
        &self,
        receipt: EntityAccessReceipt<ViewAccessLevel>,
        table_id: TableId,
        row_id: RowId,
    ) -> impl Future<Output = Result<Vec<RowHistoryEntry>, DatabaseError>> + Send;

    /// What changed in one of the database's tables since a version: the
    /// rows, each once as it stands now, and the columns. A reader holding
    /// the table at that version reads just those rows, unless the shape
    /// changed, the journal has a gap, or too many rows changed.
    fn table_changes(
        &self,
        receipt: EntityAccessReceipt<ViewAccessLevel>,
        table_id: TableId,
        since: TableVersion,
    ) -> impl Future<Output = Result<TableChanges, DatabaseError>> + Send;

    /// Tell the database's other viewers where this viewer is and whether
    /// they can edit; a viewer who cannot is never relayed as editing. A
    /// relay failure is the caller's error.
    fn share_awareness(
        &self,
        receipt: EntityAccessReceipt<ViewAccessLevel>,
        viewer: Viewer,
        state: Awareness,
    ) -> impl Future<Output = Result<(), DatabaseError>> + Send;

    /// Save a question, scoped to `database_id`, which the viewer must be
    /// able to see. Whether its SQL compiles is the SQL adapter's to check:
    /// the domain stores the definition as it is given.
    fn save_query(
        &self,
        viewer: Viewer,
        database_id: Option<DatabaseId>,
        definition: QueryDefinition,
    ) -> impl Future<Output = Result<SavedQuery, SavedQueryError>> + Send;

    /// A saved query's definition, readable by its creator and by anyone who
    /// can view the live database it is scoped to. Anyone else gets
    /// [`SavedQueryError::NotFound`], so query ids cannot be probed.
    fn get_query(
        &self,
        viewer: Viewer,
        id: QueryId,
    ) -> impl Future<Output = Result<SavedQuery, SavedQueryError>> + Send;
}

/// Plain reads of a table's cells for a domain that decides access itself
/// (forms, for a respondent's own answers and a poll's tallies), so it
/// never reaches a databases adapter. A port of its own, like sharing, so
/// the many `DatabasesService` stand-ins need not grow reads they never use.
pub trait DatabaseRowReads: Send + Sync + 'static {
    /// The cells of those of `rows` that belong to the table, each as the
    /// op writing it would name it, in column order; a row of the table with
    /// no cells maps to none, and a row not in the table is left out.
    fn cells_of_rows(
        &self,
        receipt: EntityAccessReceipt<ViewAccessLevel>,
        table_id: TableId,
        rows: &[RowId],
    ) -> impl Future<
        Output = Result<HashMap<RowId, Vec<models_databases::CellWrite>>, DatabaseError>,
    > + Send;

    /// One column's nonempty cells, by row, across the whole table.
    fn column_cells(
        &self,
        receipt: EntityAccessReceipt<ViewAccessLevel>,
        table_id: TableId,
        column_id: ColumnId,
    ) -> impl Future<Output = Result<HashMap<RowId, models_databases::CellValue>, DatabaseError>> + Send;

    /// How many rows the table has.
    fn row_count(
        &self,
        receipt: EntityAccessReceipt<ViewAccessLevel>,
        table_id: TableId,
    ) -> impl Future<Output = Result<u64, DatabaseError>> + Send;
}

/// A database's own facts, for a domain that decides access itself and
/// names something after a database (forms, for a form that created its own
/// database). A port of its own, like [`DatabaseRowReads`], so the many
/// `DatabasesService` stand-ins need not grow it.
pub trait DatabaseMetadataReads: Send + Sync + 'static {
    /// The receipt's database, in the trash or not: what it is called
    /// outlives its tables being readable.
    fn database_metadata(
        &self,
        receipt: EntityAccessReceipt<ViewAccessLevel>,
    ) -> impl Future<Output = Result<Database, DatabaseError>> + Send;
}