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.

15.1 KB
Raw Blame
//! Running a statement as a viewer: build their catalog, compile against it,
//! refuse what they may not write, and drive the engine.

mod schema;
#[cfg(test)]
pub(crate) mod test;

use std::collections::HashMap;
use std::sync::{Arc, Mutex, PoisonError};

use contacts::domain::ports::ContactsService;
use database_sql::resolve::{CompileError, Query};
use database_sql::run::{OutcomeKind, RunError, RunFailure};
use databases::domain::models::{
    DatabaseError, DatabaseId, QueryDefinition, SavedQuery, SavedQueryError, TableId, TableVersion,
    Viewer,
};
use databases::domain::ports::DatabasesService;
use databases::domain::receipt::database_receipt;
use entity_access::domain::models::{AccessError, EditAccessLevel};
use entity_access::domain::ports::EntityAccessService;
use models_databases::MAX_STATEMENT_LENGTH;
use soup::domain::ports::SoupService;

use crate::catalog::ViewerCatalog;
use crate::ops_sink::{ReceiptOpsSink, ReceiptWriteError};
use crate::outcome::{SqlOutcome, shape};
use crate::row_source::{SoupRowSource, SoupSourceError};
use crate::view_only::ViewOnlyAccess;

/// SQL over the databases a viewer can reach. Reads go through Soup and the
/// viewer's contacts; writes go through the databases service's ops.
pub struct DatabasesSql<Databases, Access, Soup, Contacts> {
    databases: Arc<Databases>,
    entity_access: Arc<Access>,
    soup: Arc<Soup>,
    contacts: Arc<Contacts>,
    read_only: bool,
}

impl<Databases, Access, Soup, Contacts> Clone for DatabasesSql<Databases, Access, Soup, Contacts> {
    fn clone(&self) -> Self {
        Self {
            databases: self.databases.clone(),
            entity_access: self.entity_access.clone(),
            soup: self.soup.clone(),
            contacts: self.contacts.clone(),
            read_only: self.read_only,
        }
    }
}

/// One statement to run.
#[derive(Debug, Clone)]
pub struct SqlRequest {
    /// The statement.
    pub sql: String,
    /// The database the statement is written from. Its tables win over
    /// same-named tables of other databases.
    pub scope: Option<DatabaseId>,
    /// Compare-and-set per written table: a written table listed here must
    /// still be at this version. A written table not listed is written
    /// blind, cell by cell, last write wins.
    pub base_versions: HashMap<TableId, TableVersion>,
}

/// The result columns a saved question's chart plots, which its `SELECT`
/// must return.
#[derive(Debug, Clone, Copy)]
pub struct ChartColumns<'chart> {
    /// The label column.
    pub x: &'chart str,
    /// The value columns, each a number.
    pub y: &'chart [String],
    /// The column whose values split the series.
    pub color: Option<&'chart str>,
}

/// Why a statement did not run.
#[derive(Debug, thiserror::Error)]
pub enum SqlError {
    /// The statement did not compile.
    #[error(transparent)]
    Compile(#[from] CompileError),
    /// The engine refused the statement.
    #[error(transparent)]
    Run(#[from] RunError),
    /// The databases service refused the statement's write.
    #[error("{}", refusal(.row, .reason))]
    WriteRefused {
        /// The refused row's place in the statement, from 1, when one row
        /// is at fault.
        row: Option<usize>,
        /// Why, in the service's words.
        reason: String,
    },
    /// A saved query must be a read.
    #[error("a saved query must be a SELECT; it cannot change data")]
    SavedQueryNotSelect,
    /// A chart names a column the saved `SELECT` does not return.
    #[error("the chart names \"{name}\", but the query returns {}", quoted(.returned))]
    ChartColumnNotReturned {
        /// The column named.
        name: String,
        /// The columns the query returns.
        returned: Vec<String>,
    },
    /// A chart plots a column that does not hold numbers.
    #[error("the chart plots \"{name}\", which is not a number")]
    ChartValueNotNumeric {
        /// The column.
        name: String,
    },
    /// The viewer may read the table but not write it.
    #[error("table {table} is read-only")]
    TableReadOnly {
        /// The table's name.
        table: String,
    },
    /// A written table moved past the version the caller read.
    #[error("table {table_id} changed since it was read")]
    VersionConflict {
        /// The table.
        table_id: TableId,
    },
    /// One of the tables in a schema batch moved past the caller's version.
    #[error("database {database_id} changed since its schema was read")]
    SchemaVersionConflict {
        /// The database whose schema should be refreshed.
        database_id: DatabaseId,
    },
    /// The statement is longer than any statement is allowed to be.
    #[error("the statement is too long")]
    TooLong,
    /// The database or saved query does not exist, or the viewer cannot see
    /// it.
    #[error("not found")]
    NotFound,
    /// The table a compiled write names is missing from the catalog it was
    /// compiled against: the engine broke its own invariant.
    #[error("table {table_id} is not in the catalog the statement compiled against")]
    WrittenTableNotInCatalog {
        /// The table.
        table_id: TableId,
    },
    /// The column an `ALTER COLUMN` changed is missing from the catalog it
    /// was compiled against.
    #[error(
        "column {definition} of table {table_id} is not in the catalog the statement compiled against"
    )]
    AlteredColumnNotInCatalog {
        /// The table.
        table_id: TableId,
        /// The column's property definition.
        definition: uuid::Uuid,
    },
    /// The engine answered an `ALTER COLUMN` without the column it changed.
    #[error("the type change answered without the column it changed")]
    AlterWithoutAlteredColumn,
    /// A service the statement needed failed.
    #[error("the databases service failed")]
    Infrastructure(rootcause::Report),
}

fn quoted(names: &[String]) -> String {
    names
        .iter()
        .map(|name| format!("\"{name}\""))
        .collect::<Vec<_>>()
        .join(", ")
}

fn refusal(row: &Option<usize>, reason: &str) -> String {
    match row {
        Some(row) => format!("row {row}: {reason}"),
        None => reason.to_owned(),
    }
}

impl<Databases, Access, Soup, Contacts> DatabasesSql<Databases, Access, Soup, Contacts>
where
    Databases: DatabasesService,
    Access: EntityAccessService,
    Soup: SoupService,
    Contacts: ContactsService,
{
    /// SQL over these services.
    pub fn new(
        databases: Arc<Databases>,
        entity_access: Arc<Access>,
        soup: Arc<Soup>,
        contacts: Arc<Contacts>,
    ) -> Self {
        Self {
            databases,
            entity_access,
            soup,
            contacts,
            read_only: false,
        }
    }

    /// The same SQL over access capped at view: it reads what the viewer can
    /// see, and every write is refused as the access check refuses a viewer.
    pub fn view_only(&self) -> DatabasesSql<Databases, ViewOnlyAccess<Access>, Soup, Contacts> {
        DatabasesSql {
            databases: self.databases.clone(),
            entity_access: Arc::new(ViewOnlyAccess((*self.entity_access).clone())),
            read_only: true,
            soup: self.soup.clone(),
            contacts: self.contacts.clone(),
        }
    }

    /// Save a read as a question, scoped to `database_id`, once it compiles
    /// as a `SELECT` against the viewer's catalog that returns every column
    /// `chart` plots.
    #[tracing::instrument(skip_all, err)]
    pub async fn save_query(
        &self,
        viewer: Viewer,
        database_id: Option<DatabaseId>,
        definition: QueryDefinition,
        chart: Option<ChartColumns<'_>>,
    ) -> Result<SavedQuery, SqlError> {
        let sql = definition.sql();
        let catalog = self.catalog(&viewer, database_id).await?;
        let Query::Select(select) = database_sql::compile(catalog.catalog(), sql)? else {
            return Err(SqlError::SavedQueryNotSelect);
        };
        if let Some(chart) = chart {
            check_chart(
                &database_sql::result_columns(catalog.catalog(), &select)?,
                chart,
            )?;
        }
        self.databases
            .save_query(viewer, database_id, definition)
            .await
            .map_err(|error| match error {
                SavedQueryError::NotFound => SqlError::NotFound,
                SavedQueryError::TooLong => SqlError::TooLong,
                SavedQueryError::Repo(report) => SqlError::Infrastructure(report),
            })
    }

    /// Run one statement, a read or a write.
    #[tracing::instrument(skip_all, err)]
    pub async fn execute(
        &self,
        viewer: Viewer,
        request: SqlRequest,
    ) -> Result<SqlOutcome, SqlError> {
        if request.sql.len() > MAX_STATEMENT_LENGTH {
            return Err(SqlError::TooLong);
        }
        if let Some(command) =
            database_sql::parse::parse_schema(&request.sql).map_err(CompileError::Parse)?
        {
            return self.execute_schema(viewer, request, command).await;
        }
        let catalog = self.catalog(&viewer, request.scope).await?;
        let query = database_sql::compile(catalog.catalog(), &request.sql)?;
        let mut write_receipt = None;
        let mut written = None;
        if let Some(table) = written_table(&query) {
            let (database, detail) = catalog
                .table(table)
                .ok_or(SqlError::WrittenTableNotInCatalog { table_id: table })?;
            let receipt = database_receipt::<EditAccessLevel, _>(
                self.entity_access.as_ref(),
                &viewer,
                database.database.id,
            )
            .await
            .map_err(|error| match error {
                AccessError::Unauthorized | AccessError::UnauthorizedWithMessage(_) => {
                    SqlError::TableReadOnly {
                        table: detail.table.name.clone(),
                    }
                }
                AccessError::NotFound(_) => SqlError::NotFound,
                other => SqlError::Infrastructure(rootcause::Report::new(other).into_dynamic()),
            })?;
            write_receipt = Some((database.database.id, receipt));
            written = Some((table, detail.table.name.clone()));
            if request
                .base_versions
                .get(&table)
                .is_some_and(|expected| *expected != detail.table.version)
            {
                return Err(SqlError::VersionConflict { table_id: table });
            }
        }

        let source = SoupRowSource {
            soup: self.soup.as_ref(),
            contacts: self.contacts.as_ref(),
            viewer: &viewer.user_id,
            catalog: catalog.catalog(),
        };
        let sink = ReceiptOpsSink {
            databases: self.databases.as_ref(),
            receipt: write_receipt,
            viewer: &viewer,
            base_versions: &request.base_versions,
            versions: Mutex::new(HashMap::new()),
        };
        let outcome = database_sql::run(catalog.catalog(), &request.sql, &source, &sink)
            .await
            .map_err(|failure| run_failure(failure, written))?;
        // The lock only guards single inserts, so a poisoned map is still whole.
        let new_versions = sink
            .versions
            .into_inner()
            .unwrap_or_else(PoisonError::into_inner);
        shape(&catalog, &query, &outcome, new_versions)
    }

    async fn catalog(
        &self,
        viewer: &Viewer,
        scope: Option<DatabaseId>,
    ) -> Result<ViewerCatalog, SqlError> {
        let databases = self
            .databases
            .database_details(viewer.clone())
            .await
            .map_err(|error| match error {
                DatabaseError::Repo(report) => SqlError::Infrastructure(report),
                DatabaseError::NotFound | DatabaseError::Unauthorized => SqlError::NotFound,
                // Refusals of a write: a listing returning one is a broken service.
                other @ (DatabaseError::InvalidSchemaOperation(_)
                | DatabaseError::InvalidSharing(_)
                | DatabaseError::VersionConflict
                | DatabaseError::RowInUse
                | DatabaseError::OptionInUse
                | DatabaseError::InvalidOp(_)) => {
                    SqlError::Infrastructure(rootcause::Report::new(other).into_dynamic())
                }
            })?;
        let catalog = ViewerCatalog::new(databases, scope);
        if let Some(database_id) = scope
            && !catalog.has_database(database_id)
        {
            return Err(SqlError::NotFound);
        }
        Ok(catalog)
    }
}

/// Every column `chart` names is one the query returns, and every value
/// column holds numbers.
fn check_chart(
    returned: &[database_sql::OutcomeColumn],
    chart: ChartColumns<'_>,
) -> Result<(), SqlError> {
    let named = std::iter::once(chart.x)
        .chain(chart.y.iter().map(String::as_str))
        .chain(chart.color);
    for name in named {
        if !returned.iter().any(|column| column.name == name) {
            return Err(SqlError::ChartColumnNotReturned {
                name: name.to_owned(),
                returned: returned.iter().map(|column| column.name.clone()).collect(),
            });
        }
    }
    for name in chart.y {
        if returned
            .iter()
            .any(|column| column.name == *name && column.kind != OutcomeKind::Number)
        {
            return Err(SqlError::ChartValueNotNumeric { name: name.clone() });
        }
    }
    Ok(())
}

/// A failed run in the viewer's terms; `written` is the table the statement
/// writes, with its name.
fn run_failure(
    failure: RunFailure<SoupSourceError, ReceiptWriteError>,
    written: Option<(TableId, String)>,
) -> SqlError {
    match failure {
        RunFailure::Engine(error) => SqlError::Run(error),
        RunFailure::Source(error) => SqlError::Infrastructure(error.into_report()),
        RunFailure::Write(ReceiptWriteError::Database(error)) => match (error, written) {
            (DatabaseError::InvalidOp(refusal), _) => SqlError::WriteRefused {
                row: refusal.row.map(|row| row + 1),
                reason: refusal.reason,
            },
            (DatabaseError::VersionConflict, Some((table_id, _))) => {
                SqlError::VersionConflict { table_id }
            }
            (DatabaseError::Unauthorized, Some((_, table))) => SqlError::TableReadOnly { table },
            (DatabaseError::NotFound, _) => SqlError::NotFound,
            (DatabaseError::Repo(report), _) => SqlError::Infrastructure(report),
            (other, _) => SqlError::Infrastructure(rootcause::Report::new(other).into_dynamic()),
        },
        RunFailure::Write(error @ ReceiptWriteError::UnauthorizedDatabase { .. }) => {
            tracing::error!(error = %error, "a statement wrote a database it was not authorized for");
            SqlError::Infrastructure(rootcause::Report::new(error).into_dynamic())
        }
    }
}

fn written_table(query: &Query) -> Option<TableId> {
    match query {
        Query::Select(_) => None,
        Query::Insert(insert) => Some(insert.table),
        Query::Update(update) => Some(update.table),
        Query::Delete(delete) => Some(delete.table),
        Query::AlterColumnType(alter) => Some(alter.table),
    }
}