tablo_core/

tenancy.rs

//! Scopes resources to the request tenant.
//!
//! [`tenant_id`] answers the request's tenant: the signed-in user's
//! [`membership`](crate::membership) unless a server-set `Tenant` request extension or a `Tenant`
//! scoped value overrides it, so app middleware and `Router::handle` tests can set it
//! deliberately. No request header supplies a tenant: learning another tenant's UUID does not make
//! anyone that tenant.

use toasty::stmt::{Expr, Path};
use topcoat::context::{Cx, try_context};

use crate::{
    DeclarationErrorKind, TenancyFault,
    toasty_compat::model::{self, ModelPath},
};

mod tenant_id;

pub use tenant_id::{TenantColumn, TenantId};

/// One tenant a user may act for: its id, and the name the tenant switcher
/// shows. A [`PanelUser`](crate::auth::PanelUser) lists its memberships in
/// [`tenants`](crate::auth::PanelUser::tenants).
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct Membership {
    pub tenant: TenantId,
    pub name: String,
}

impl Membership {
    /// The membership of `tenant`, shown as `name`.
    pub fn new(tenant: TenantId, name: impl Into<String>) -> Self {
        Self {
            tenant,
            name: name.into(),
        }
    }
}

/// Request-scoped tenant identifier.
///
/// App code may put it on the `Cx` with `cx.with(Tenant(id))`, and server code
/// and tests may carry it as a request extension; either wins over the signed-in
/// user's tenant. No request header sets it. A `Tenant` registered on the router
/// with `.with(Tenant(id))` reaches every request, so every user acts for that
/// tenant whatever their memberships.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Tenant(pub TenantId);

/// The tenant a test claims its request acts for, as a request extension: what
/// `tablo::testing::TestClient::tenant` sends. Unlike a [`Tenant`] override it is no seam
/// around membership: a signed-in user acts for it only while a member, as after switching to it
/// from the tenant menu, and otherwise for the tenant they would act for without it. A request
/// with nobody signed in, such as one to a panel with auth disabled, acts for it.
#[doc(hidden)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct ClaimedTenant(pub TenantId);

/// The tenant the request acts for, if any.
///
/// Checks a `Tenant` request extension first (a server-set override — the
/// deliberate seam app middleware and `Router::handle` tests use), then a
/// `Tenant` scoped value app code put on the `Cx`, then the signed-in user's
/// [`membership`](crate::auth::membership). No request header is consulted.
pub fn tenant_id(cx: &Cx) -> Option<TenantId> {
    if let Some(parts) = try_context::<http::request::Parts>(cx)
        && let Some(t) = parts.extensions.get::<Tenant>()
    {
        return Some(t.0);
    }
    if let Some(t) = try_context::<Tenant>(cx) {
        return Some(t.0);
    }
    let TenantSource(session) = try_context::<TenantSource>(cx)?;
    session(cx)
}

/// Finds the tenant the request's session acts for; the first panel mounted on a
/// router installs it.
pub(crate) struct TenantSource(pub(crate) fn(&Cx) -> Option<TenantId>);

/// Requires a tenant, returning an error if missing (for tenant-owned resources).
///
/// # Errors
///
/// 403 when the request acts for no tenant.
pub fn require_tenant(cx: &Cx) -> Result<TenantId, topcoat::Error> {
    tenant_id(cx).ok_or_else(|| topcoat::router::error::forbidden().into())
}

/// How a resource's rows belong to a tenant.
///
/// A resource declares one with [`ResourceDef::tenancy`](crate::ResourceDef::tenancy). A
/// scoped tenancy names, by lens, the [`TenantId`] column each row is filtered on:
///
/// ```rust
/// # use tablo_core::{NoForm, Resource, ResourceDef, Tenancy, TenantId, lens};
/// # #[derive(Debug, Clone, toasty::Model, tablo_core::ModelColumns)]
/// # struct Post { #[key] #[auto] id: uuid::Uuid, tenant_id: TenantId }
/// # #[derive(Debug, Clone, toasty::Model, tablo_core::ModelColumns)]
/// # struct Comment {
/// #     #[key] #[auto] id: uuid::Uuid,
/// #     post_id: uuid::Uuid,
/// #     #[belongs_to(key = post_id, references = id)]
/// #     post: toasty::Deferred<Post>,
/// # }
/// # struct PostResource;
/// # impl Resource for PostResource { type Model = Post; type Form = NoForm<Post>; }
/// # struct CommentResource;
/// # impl Resource for CommentResource { type Model = Comment; type Form = NoForm<Comment>; }
/// let posts: ResourceDef<PostResource> =
///     ResourceDef::new().tenancy(Tenancy::column(lens!(Post.tenant_id)));
///
/// let comments: ResourceDef<CommentResource> =
///     ResourceDef::new().tenancy(Tenancy::via(Comment::fields().post().tenant_id()));
/// ```
///
/// A scoped resource answers 403 to a request with no tenant, in every handler,
/// instead of serving unscoped rows or writing rows with no tenant.
pub struct Tenancy<M> {
    scope: Scope,
    _model: std::marker::PhantomData<fn() -> M>,
}

/// The model field a [`Tenancy::column`] stamps and filters on.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct TenantField {
    /// The field's index in its model.
    pub(crate) index: usize,
    /// The field's name, which is also its form key.
    pub(crate) name: String,
}

/// `<lens> = tenant` for one tenant.
type TenantFilter = Box<dyn Fn(TenantId) -> Expr<bool> + Send + Sync>;

enum Scope {
    /// Unscoped: [`Tenancy::none`] when `declared`, else the default a resource that never called
    /// [`ResourceDef::tenancy`](crate::ResourceDef::tenancy) holds.
    None { declared: bool },
    /// The model's own column, resolved when declared: its field, or `None`
    /// when the lens names none.
    Column {
        filter: TenantFilter,
        field: Option<TenantField>,
    },
    Via {
        filter: TenantFilter,
        /// Whether the lens is one field of the model: a `via` over its own
        /// column stamps nothing, so the mount refuses it in favor of
        /// [`Tenancy::column`](Self::column).
        single: bool,
        /// The model field the lens's first step names: the relation whose
        /// foreign key the form must write through a relationship field.
        hop: Option<usize>,
    },
}

impl<M: toasty::schema::Model + 'static> Tenancy<M> {
    fn scoped(scope: Scope) -> Self {
        Self {
            scope,
            _model: std::marker::PhantomData,
        }
    }

    /// Rows belong to no tenant: the resource is served as its
    /// [`query`](crate::ResourceDef::query) narrows it, to every request.
    ///
    /// A resource that declares no tenancy is served the same way, unless its model has a
    /// [`TenantId`] column or the panel acts for tenants, offering a tenant registration or
    /// settings page or mounting a resource over tenant-owned rows: mounting the panel refuses
    /// that resource until it declares one, so it declares `Tenancy::none()` to serve every tenant
    /// on purpose.
    pub fn none() -> Self {
        Self::scoped(Scope::None { declared: true })
    }

    /// The tenancy of a resource that never declared one.
    pub(crate) fn undeclared() -> Self {
        Self::scoped(Scope::None { declared: false })
    }

    /// Rows carry their tenant in one [`TenantId`] column of their own model,
    /// `TenantId` or `Option<TenantId>`.
    ///
    /// The framework filters every loader on it and stamps the request's
    /// tenant into it on create, so the record form must not claim it.
    /// Mounting the panel refuses a lens that is not a single field of the
    /// model.
    pub fn column<T>(lens: impl Into<Path<M, T>>) -> Self
    where
        T: TenantColumn,
        M: Send + Sync,
    {
        let lens = lens.into();
        let field = model::field::<M>(&ModelPath::of(&lens))
            .ok()
            .map(|field| TenantField {
                index: field.index,
                name: field.name,
            });
        Self::scoped(Scope::Column {
            filter: Box::new(move |tenant| lens.clone().eq(T::from_tenant(tenant))),
            field,
        })
    }

    /// Rows inherit their tenant through a relation: `lens` reaches the parent's [`TenantId`]
    /// column, as `Comment::fields().post().tenant_id()` does.
    ///
    /// The framework filters every loader on it. It stamps nothing on create:
    /// a row's tenant is its parent's. The lens starts at a `belongs_to`
    /// relation, and mounting the panel requires the form to write that
    /// relation's foreign key through a relationship field over a tenant-scoped
    /// resource, whose key the framework re-checks against that resource's
    /// tenant-scoped query inside the write.
    pub fn via<T>(lens: impl Into<Path<M, T>>) -> Self
    where
        T: TenantColumn,
        M: Send + Sync,
    {
        let lens = lens.into();
        let path = ModelPath::of(&lens);
        let hop = path.steps().first().copied();
        let single = model::field::<M>(&path).is_ok();
        Self::scoped(Scope::Via {
            filter: Box::new(move |tenant| lens.clone().eq(T::from_tenant(tenant))),
            single,
            hop,
        })
    }

    /// Whether the rows belong to a tenant, so every handler requires one.
    pub fn is_scoped(&self) -> bool {
        !matches!(self.scope, Scope::None { .. })
    }

    /// Whether the resource never declared its tenancy.
    pub(crate) fn is_undeclared(&self) -> bool {
        matches!(self.scope, Scope::None { declared: false })
    }

    /// `<lens> = tenant`, or `None` for an unscoped resource.
    pub(crate) fn filter(&self, tenant: TenantId) -> Option<Expr<bool>> {
        match &self.scope {
            Scope::None { .. } => None,
            Scope::Column { filter, .. } | Scope::Via { filter, .. } => Some(filter(tenant)),
        }
    }

    /// Whether a [`via`](Self::via) tenancy names one field of the model,
    /// which [`Tenancy::column`](Self::column) owns. `None` for any other
    /// tenancy.
    pub(crate) fn via_is_single(&self) -> Option<bool> {
        match &self.scope {
            Scope::Via { single, .. } => Some(*single),
            Scope::None { .. } | Scope::Column { .. } => None,
        }
    }

    /// The model field a [`via`](Self::via) lens steps through first.
    pub(crate) fn via_hop(&self) -> Option<usize> {
        match &self.scope {
            Scope::Via { hop, .. } => *hop,
            Scope::None { .. } | Scope::Column { .. } => None,
        }
    }

    /// The model's own tenant column for a [`column`](Self::column) tenancy,
    /// or the mistake of a lens that names none.
    pub(crate) fn column_field(&self) -> Option<Result<&TenantField, DeclarationErrorKind>> {
        match &self.scope {
            Scope::Column { field, .. } => {
                Some(field.as_ref().ok_or(DeclarationErrorKind::Tenancy {
                    fault: TenancyFault::ColumnNotAField,
                }))
            }
            Scope::None { .. } | Scope::Via { .. } => None,
        }
    }
}

#[cfg(test)]
mod tests;