tablo_core/resource/

action.rs

//! Custom actions: the [`Action`] trait, and the [`Actions`] list a
//! [`ResourceDef`](super::ResourceDef) declares them in.

use std::{any::Any, future::Future};

use derive_where::derive_where;
use topcoat::{Result, context::Cx};

mod builtin;

use super::{Mounted, Resource, WriteError};
use crate::{
    BoxFuture,
    form::{FieldError, FieldErrors, FormInput, FormValues},
    naming::{derived_id, sentence_case},
    policy::Ability,
    schema::Schema,
};

/// The keys an action's POST carries besides its input, which no input field may post.
pub(crate) const RESERVED_KEYS: [&str; 3] = [crate::csrf::FIELD_NAME, "confirm", "ids"];

/// A mutation beyond create, update and delete: "publish", "archive",
/// "resend the invite".
///
/// An action runs on one record, from a button in its table row or in the header of its detail or
/// edit page, or on the selection, from the bulk bar: [`PLACES`](Self::PLACES) says which.
/// [`ResourceDef::action`](super::ResourceDef::action) declares it:
///
/// ```rust
/// # #[derive(Debug, Clone, toasty::Model, tablo_core::ModelColumns)]
/// # struct Post {
/// #     #[key] #[auto] id: uuid::Uuid,
/// #     title: String,
/// #     status: String,
/// # }
/// # use tablo_core::{Action, NoForm, Resource};
/// # use toasty::Executor;
/// # use topcoat::{Result, context::Cx};
/// # struct PostResource;
/// #
/// # impl Resource for PostResource {
/// #     type Model = Post;
/// #     type Form = NoForm<Post>;
/// # }
/// struct Publish;
///
/// impl Action<PostResource> for Publish {
///     type Input = ();
///     const NAME: &'static str = "publish";
///
///     fn can_run(_cx: &Cx, post: &Post) -> bool {
///         post.status != "published"
///     }
///
///     async fn run(
///         _cx: &Cx,
///         posts: &[Post],
///         _: (),
///         ex: &mut dyn Executor,
///     ) -> Result<tablo_core::Outcome, tablo_core::WriteError> {
///         for post in posts {
///             Post::filter(Post::fields().id().eq(post.id))
///                 .update()
///                 .status("published".to_string())
///                 .exec(&mut *ex)
///                 .await?;
///         }
///         Ok(tablo_core::Outcome::done())
///     }
/// }
/// ```
///
/// The framework owns everything around [`run`](Self::run), as it does for
/// a delete:
///
/// - the route, `{list}/{key}/-/actions/{NAME}` for one record and `{list}/-/actions/{NAME}` for
///   the selection, and its CSRF check;
/// - the transaction: the records are loaded through [`scoped_query`](super::scoped_query) inside
///   it, `run` writes through the same executor, and an error rolls everything back;
/// - the policy: [`Ability::RunAny`] with the action's `NAME`, asked before the body is read, then
///   [`Ability::View`] and [`Ability::Run`] on every loaded record before `run`. A record `View`
///   refuses fails the whole POST with 403;
/// - the refusal: a row that `Run` or [`can_run`](Self::can_run) refuses answers 403, and a bulk
///   selection runs the records that pass both and reports the refused count as skipped. A
///   selection that passes on none writes nothing and answers with an error notification;
/// - the hooks, with [`Change::Action`](super::Change::Action): [`Resource::before_commit`] in the
///   transaction after `run`, then [`Resource::after_commit`] once it commits; and the success
///   notification.
///
/// An action that asks for an [`Input`](Self::Input) asks for it first: its button opens the
/// input's form in a dialog over the page, whose submit runs the action with the parsed value. The
/// submit parses the input, asks [`validate_input`](Self::validate_input) and checks its choices
/// before the transaction opens, then re-checks a relationship choice inside it. A refused value
/// renders the input as a page with its errors and writes nothing; a key the input does not
/// declare answers 400. The page is titled with the label and the record's title, or the record
/// count for a selection, and its Cancel returns to the page the button was on. Cancel and Escape
/// close the dialog, and opening it again starts from a blank form. A searchable relationship
/// choice searches `{list}/-/actions/{NAME}/options`, behind the checks the POST makes before it
/// loads a record. The dialog needs JavaScript.
///
/// A run from a detail or edit page lands back on that page, its query kept; one from a row or
/// the bulk bar lands on the list. An action that takes the record out of the resource's
/// [`query`](super::Resource::query) or its `View`, such as an archive the list hides, lands on
/// that page's 404: place it on rows and the bulk bar instead.
///
/// No place renders a button for an action the policy refuses `RunAny`, and no row or page renders
/// one for a record that fails `View`, `Run` or `can_run`. A row that no bulk action and no delete
/// allows renders no checkbox.
pub trait Action<R: Resource>: 'static {
    /// What the action asks for before it runs: `()` for nothing, or an
    /// [`FormInput`](derive@crate::FormInput) struct, such as a rejection's reason.
    type Input: FormInput;

    /// The action's URL segment, distinct among the resource's actions.
    ///
    /// [`ResourceDef::action`](super::ResourceDef::action) refuses to compile a name that is not
    /// a single path segment: empty, `.` or `..`, or holding whitespace, a control character, a
    /// quote, a backslash or one of `/ ? # % & = { } ( )`.
    /// [`RouterBuilderPanelExt::panel`](crate::RouterBuilderPanelExt::panel) refuses a name that
    /// another action of the resource shares.
    ///
    /// ```rust,compile_fail,E0080
    /// # use tablo_core::{Action, NoForm, Resource, ResourceDef};
    /// # use topcoat::{Result, context::Cx};
    /// # #[derive(Debug, Clone, toasty::Model, tablo_core::ModelColumns)]
    /// # struct Post { #[key] #[auto] id: uuid::Uuid, title: String }
    /// # struct PostResource;
    /// # impl Resource for PostResource {
    /// #     type Model = Post;
    /// #     type Form = NoForm<Post>;
    /// # }
    /// struct Archive;
    ///
    /// impl Action<PostResource> for Archive {
    ///     type Input = ();
    ///     const NAME: &'static str = "archive/all";
    /// #   fn can_run(_: &Cx, _: &Post) -> bool { true }
    /// #   async fn run(_: &Cx, _: &[Post], _: (), _: &mut dyn toasty::Executor) -> Result<tablo_core::Outcome, tablo_core::WriteError> { Ok(tablo_core::Outcome::done()) }
    /// }
    ///
    /// let def = ResourceDef::<PostResource>::new().action::<Archive>();
    /// ```
    const NAME: &'static str;

    /// Where the action's button renders. Defaults to [`Places::ALL`]: each row, the detail and
    /// edit pages' headers, and the bulk bar.
    ///
    /// It decides where the button shows, not who may run it: the record route serves an action
    /// placed on any of [`Places::RECORD`], and the bulk route one placed on
    /// [`Places::BULK`]; any other POST answers 404. A place no page renders shows the button
    /// nowhere: [`Places::EDIT`] on a resource without a form, or [`Places::DETAIL`] on one whose
    /// view is [`Detail::empty`](crate::Detail::empty).
    const PLACES: Places = Places::ALL;

    /// Whether the action asks first through a confirmation dialog sharing the
    /// delete dialog's mechanism and destructive wording. Defaults to `false`.
    ///
    /// An action with input confirms in its input dialog, or on its input page, instead, which
    /// say the action cannot be undone and whose submit renders destructive. An unconfirmed POST
    /// that would write answers 400. Both dialogs need JavaScript: without it their buttons do
    /// nothing.
    const CONFIRM: bool = false;

    /// The button text. Defaults to the message `action-{NAME}` of the panel's catalogs, else
    /// [`NAME`](Self::NAME) in sentence case: `"publish"` reads "Publish", and `"send-invite"`
    /// reads "Send invite".
    fn label(cx: &Cx) -> String {
        crate::Text::derived(derived_id("action", Self::NAME), sentence_case(Self::NAME))
            .localize(cx)
    }

    /// Whether `record`'s state lets the action run on it: a published post refuses "publish".
    /// Defaults to `true`.
    ///
    /// It sees no policy, so it decides no authorization: the resource's policy answers
    /// [`Ability::Run`] for that, and a panel that mounts the resource with another policy
    /// changes who may run the action.
    fn can_run(_cx: &Cx, _record: &R::Model) -> bool {
        true
    }

    /// Refuse an input [`run`](Self::run) should not receive, such as a reason too short to
    /// act on: each error names an input field's key and renders under its control. Defaults to
    /// none. A key no control renders is a declaration error: the page would show no message.
    ///
    /// It runs after the input parses and before the transaction opens, so it sees no record; a
    /// rule that reads the database refuses from [`run`](Self::run).
    fn validate_input(_cx: &Cx, _input: &Self::Input) -> FieldErrors {
        FieldErrors::new()
    }

    /// Perform the action on `records`, the records of the row or selection that
    /// passed [`Ability::Run`] and [`can_run`](Self::can_run), with the parsed `input`, through
    /// the framework's transaction `ex`, and say what the response does once it commits:
    /// [`Outcome::done`](crate::Outcome::done) for the [`success`](Self::success) notification,
    /// landing back where the action ran from.
    ///
    /// A rule that reads the database refuses the input with [`WriteError::Refused`], keyed by
    /// its form keys: the transaction rolls back and the input page renders with the errors. An
    /// action that asks for nothing has no control to render them under, so its refusal is a
    /// declaration error.
    fn run(
        cx: &Cx,
        records: &[R::Model],
        input: Self::Input,
        ex: &mut dyn toasty::Executor,
    ) -> impl Future<Output = Result<crate::Outcome, WriteError>> + Send;

    /// The success notification after a commit. Defaults to the label and
    /// the record count: `"Publish: 3 records"`. A bulk run the action refused
    /// on some records appends their count out of the selection:
    /// `"Publish: 3 records (2 of 5 skipped)"`.
    fn success(cx: &Cx, count: usize) -> String {
        crate::t!(
            cx,
            "tablo-action-on-records",
            action = Self::label(cx),
            count = count
        )
    }
}

/// Where an [`Action`]'s button renders: [`Action::PLACES`].
///
/// ```rust
/// # use tablo_core::Places;
/// // On the detail page and the bulk bar, not on each row or the edit page.
/// const PLACES: Places = Places::DETAIL.with(Places::BULK);
/// assert!(PLACES.contains(Places::BULK));
/// assert!(!PLACES.contains(Places::ROW));
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Places(u8);

impl Places {
    /// A button in each table row, the related tables' included.
    pub const ROW: Self = Self(1);
    /// A button in the detail page's header.
    pub const DETAIL: Self = Self(1 << 1);
    /// A button in the edit page's header. It posts a form of its own, so it runs on the record
    /// as stored, and a change typed into the edit form and not saved is lost.
    pub const EDIT: Self = Self(1 << 2);
    /// An entry in the bulk bar, run on the selection.
    pub const BULK: Self = Self(1 << 3);
    /// Every place that shows one record: [`ROW`](Self::ROW), [`DETAIL`](Self::DETAIL) and
    /// [`EDIT`](Self::EDIT).
    pub const RECORD: Self = Self(Self::ROW.0 | Self::DETAIL.0 | Self::EDIT.0);
    /// Every place.
    pub const ALL: Self = Self(Self::RECORD.0 | Self::BULK.0);

    /// These places and `other`'s.
    #[must_use]
    pub const fn with(self, other: Self) -> Self {
        Self(self.0 | other.0)
    }

    /// Whether every place of `other` is one of these.
    #[must_use]
    pub const fn contains(self, other: Self) -> bool {
        self.0 & other.0 == other.0
    }

    /// Whether any place of `other` is one of these.
    #[must_use]
    pub const fn intersects(self, other: Self) -> bool {
        self.0 & other.0 != 0
    }
}

impl<M> Ability<'_, M> {
    /// Whether the ability is [`RunAny`](Ability::RunAny) or [`Run`](Ability::Run) for the action
    /// `A`.
    ///
    /// It compares against `A::NAME`, so renaming the action keeps the policy matching it, and a
    /// type that is not an action of the resource does not compile. `R` is inferred when `A` is an
    /// action of one resource.
    ///
    /// ```rust
    /// # use tablo_core::{Ability, Action, NoForm, Resource};
    /// # use topcoat::{Result, context::Cx};
    /// # #[derive(Debug, Clone, toasty::Model, tablo_core::ModelColumns)]
    /// # struct Post { #[key] #[auto] id: uuid::Uuid, published: bool }
    /// # struct PostResource;
    /// # impl Resource for PostResource {
    /// #     type Model = Post;
    /// #     type Form = NoForm<Post>;
    /// # }
    /// # struct Publish;
    /// # impl Action<PostResource> for Publish {
    /// #     type Input = ();
    /// #     const NAME: &'static str = "publish";
    /// #     async fn run(_: &Cx, _: &[Post], _: (), _: &mut dyn toasty::Executor) -> Result<tablo_core::Outcome, tablo_core::WriteError> { Ok(tablo_core::Outcome::done()) }
    /// # }
    /// # fn is_editor(_cx: &Cx) -> bool { true }
    /// fn post_policy(cx: &Cx, ability: Ability<'_, Post>) -> bool {
    ///     match ability {
    ///         Ability::Run { record, .. } if ability.is_action::<Publish, _>() => !record.published,
    ///         Ability::ViewAny | Ability::View(_) => true,
    ///         _ => is_editor(cx),
    ///     }
    /// }
    /// ```
    pub fn is_action<A, R>(self) -> bool
    where
        A: Action<R>,
        R: Resource<Model = M>,
    {
        matches!(self, Ability::RunAny { action } | Ability::Run { action, .. } if action == A::NAME)
    }
}

impl<M> crate::policy::Abilities<M> {
    /// Who may run the record action `A` on a record: [`Run`](Ability::Run) with `A`'s
    /// [`NAME`](Action::NAME). It also allows [`RunAny`](Ability::RunAny) for `A`, which
    /// [`run_any`](Self::run_any) narrows. An action no `run` declares is refused.
    ///
    /// ```rust
    /// # use tablo_core::{Abilities, Action, NoForm, Resource};
    /// # use topcoat::{Result, context::Cx};
    /// # #[derive(Debug, Clone, toasty::Model, tablo_core::ModelColumns)]
    /// # struct Post { #[key] #[auto] id: uuid::Uuid, published: bool }
    /// # struct PostResource;
    /// # impl Resource for PostResource {
    /// #     type Model = Post;
    /// #     type Form = NoForm<Post>;
    /// # }
    /// # struct Publish;
    /// # impl Action<PostResource> for Publish {
    /// #     type Input = ();
    /// #     const NAME: &'static str = "publish";
    /// #     async fn run(_: &Cx, _: &[Post], _: (), _: &mut dyn toasty::Executor) -> Result<tablo_core::Outcome, tablo_core::WriteError> { Ok(tablo_core::Outcome::done()) }
    /// # }
    /// let policy = Abilities::<Post>::new()
    ///     .view_any(|_cx| true)
    ///     .view(|_cx, _post| true)
    ///     .run::<Publish, _>(|_cx, post| !post.published);
    /// # let _ = policy;
    /// ```
    #[must_use]
    pub fn run<A, R>(mut self, check: impl Fn(&Cx, &M) -> bool + Send + Sync + 'static) -> Self
    where
        A: Action<R>,
        R: Resource<Model = M>,
    {
        self.set_action_record(A::NAME, Box::new(check));
        self
    }

    /// Who may run the record action `A` at all: [`RunAny`](Ability::RunAny) with `A`'s
    /// [`NAME`](Action::NAME). Defaults to whether [`run`](Self::run) declares `A`.
    #[must_use]
    pub fn run_any<A, R>(mut self, check: impl Fn(&Cx) -> bool + Send + Sync + 'static) -> Self
    where
        A: Action<R>,
        R: Resource<Model = M>,
    {
        self.set_action_any(A::NAME, Box::new(check));
        self
    }
}

/// An erased action's body: it acts on the records with the parsed input inside the transaction.
pub(crate) type RunAction<R> = for<'a> fn(
    &'a Cx,
    &'a [<R as Resource>::Model],
    ErasedInput,
    &'a mut dyn toasty::Executor,
) -> BoxFuture<'a, Result<crate::Outcome, WriteError>>;

/// A parsed [`Action::Input`] with its type erased; `run` downcasts it back.
pub(crate) type ErasedInput = Box<dyn Any + Send>;

/// What an erased input parse returns.
pub(crate) type InputResult = std::result::Result<ErasedInput, Vec<FieldError>>;

/// What an action asks for before it runs, its type erased: the input's schema and its parse.
#[derive(Clone, Copy)]
pub(crate) struct InputSpec {
    /// The input form's schema: empty for a delete and an action asking for nothing.
    pub(crate) schema: fn() -> Schema,
    /// Whether [`schema`](Self::schema) declares a field, so the action asks for it on a page.
    pub(crate) takes_input: bool,
    /// Parses and validates the input from a submission, as the value `run` takes.
    pub(crate) parse: fn(&Cx, &FormValues) -> InputResult,
}

impl InputSpec {
    /// The input of type `I`, parsed and validated by `parse`.
    pub(crate) fn of<I: FormInput>(parse: fn(&Cx, &FormValues) -> InputResult) -> Self {
        Self {
            schema: I::schema,
            takes_input: !I::schema().is_empty(),
            parse,
        }
    }

    /// No input: a delete's.
    pub(crate) fn none() -> Self {
        Self {
            schema: Schema::empty,
            takes_input: false,
            parse: parse_nothing,
        }
    }
}

/// The actions a [`Resource`] declares, in button order.
pub(crate) struct Actions<R: Resource> {
    entries: Vec<ActionEntry<R>>,
}

impl<R: Resource> Default for Actions<R> {
    fn default() -> Self {
        Self {
            entries: Vec::new(),
        }
    }
}

impl<R: Resource> std::fmt::Debug for Actions<R> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_list()
            .entries(self.entries.iter().map(|e| e.name))
            .finish()
    }
}

impl<R: Resource> Actions<R> {
    /// Appends the action `A`, failing to compile when `A::NAME` is not a single path segment.
    pub(crate) fn add<A: Action<R>>(mut self) -> Self {
        const {
            assert!(
                crate::declaration::segment_fault(A::NAME).is_none(),
                "`Action::NAME` must be a single path segment"
            );
        }
        self.entries.push(ActionEntry {
            name: A::NAME,
            label: A::label,
            places: A::PLACES,
            resource_wide: Ability::RunAny { action: A::NAME },
            can_run: can_run_erased::<R, A>,
            input: InputSpec::of::<A::Input>(parse_input_erased::<R, A>),
            run: run_erased::<R, A>,
            success: A::success,
            change: super::acted::<R, A>,
            failure: "tablo-failed-run",
            confirm: A::CONFIRM,
            trashed: super::Trashed::Without,
            removes: false,
            prompt: "tablo-confirm-run",
        });
        self
    }

    /// Appends the built-in restore and force delete a soft-deleting resource offers on its
    /// trashed records.
    pub(crate) fn add_trash_actions(&mut self) {
        self.entries.push(ActionEntry::restore());
        self.entries.push(ActionEntry::force_delete());
    }

    /// The declared actions, in order.
    pub(crate) fn entries(&self) -> &[ActionEntry<R>] {
        &self.entries
    }

    /// The action named `name`.
    pub(crate) fn find(&self, name: &str) -> Option<&ActionEntry<R>> {
        self.entries.iter().find(|e| e.name == name)
    }
}

/// One mutation of a record or a selection with its type erased: a declared action, or the
/// built-in delete. The panel runs every one through the same pipeline.
#[derive_where(Clone, Copy)]
pub(crate) struct ActionEntry<R: Resource> {
    pub(crate) name: &'static str,
    pub(crate) label: fn(&Cx) -> String,
    pub(crate) places: Places,
    /// The resource-wide ability checked before the body is read.
    pub(crate) resource_wide: Ability<'static, R::Model>,
    /// Whether the mutation may write `record`, which already passed `View`.
    pub(crate) can_run: fn(&Mounted<R>, &Cx, &R::Model) -> bool,
    pub(crate) input: InputSpec,
    pub(crate) run: RunAction<R>,
    pub(crate) success: fn(&Cx, usize) -> String,
    /// What a run on the records changed, for the hooks.
    pub(crate) change: fn(Vec<R::Model>) -> super::Change<R::Model>,
    /// The message the failure toast's title reads.
    pub(crate) failure: &'static str,
    pub(crate) confirm: bool,
    /// The records the mutation takes: the live ones, or the trashed ones.
    pub(crate) trashed: super::Trashed,
    /// Whether the mutation removes its records, so its button lands on the list rather than on
    /// the page of a record that no longer exists.
    pub(crate) removes: bool,
    /// The message the title of the dialog confirming it on a record's page reads.
    pub(crate) prompt: &'static str,
}

impl<R: Resource> ActionEntry<R> {
    /// Whether the mutation may write `record`, which already passed `View`: the record is live
    /// or trashed as the mutation takes it, and the mutation's own check allows it.
    pub(crate) fn allows(&self, resource: &Mounted<R>, cx: &Cx, record: &R::Model) -> bool {
        self.trashed.admits(resource.is_trashed(record)) && (self.can_run)(resource, cx, record)
    }
}

/// The mounted policy's [`Ability::Run`] and [`Action::can_run`] behind a function pointer.
fn can_run_erased<R: Resource, A: Action<R>>(
    resource: &Mounted<R>,
    cx: &Cx,
    record: &R::Model,
) -> bool {
    resource.can(
        cx,
        Ability::Run {
            action: A::NAME,
            record,
        },
    ) && A::can_run(cx, record)
}

/// [`FormInput::parse`], then [`Action::validate_input`], behind a function pointer.
fn parse_input_erased<R: Resource, A: Action<R>>(cx: &Cx, values: &FormValues) -> InputResult {
    parse_validated(cx, values, A::validate_input)
}

/// `I`'s [`FormInput::parse`], then `validate`.
pub(crate) fn parse_validated<I: FormInput>(
    cx: &Cx,
    values: &FormValues,
    validate: fn(&Cx, &I) -> FieldErrors,
) -> InputResult {
    let input = I::parse(cx, values)?;
    let refused: Vec<FieldError> = validate(cx, &input).into_iter().collect();
    if !refused.is_empty() {
        return Err(refused);
    }
    Ok(Box::new(input))
}

/// A delete's input: nothing.
fn parse_nothing(_cx: &Cx, _values: &FormValues) -> InputResult {
    Ok(Box::new(()))
}

/// [`Action::run`] behind a function pointer.
fn run_erased<'a, R: Resource, A: Action<R>>(
    cx: &'a Cx,
    records: &'a [R::Model],
    input: ErasedInput,
    ex: &'a mut dyn toasty::Executor,
) -> BoxFuture<'a, Result<crate::Outcome, WriteError>> {
    let input = *input
        .downcast::<A::Input>()
        .expect("the pipeline parses the input `run` takes");
    Box::pin(A::run(cx, records, input, ex))
}