Trait Action

pub trait Action: Debug {
    // Required method
    fn apply(&self, doc: &mut AutoCommit) -> Result<(), ActionError>;

    // Provided methods
    fn locus(&self) -> ExecutionLocus { ... }
    fn risk(&self) -> RiskLevel { ... }
    fn inverse_before(&self, doc: &AutoCommit) -> Option<Self>
       where Self: Sized { ... }
    fn inverse_encoded(&self, doc: &AutoCommit) -> Option<EncodedAction> { ... }
    fn change_kind(&self) -> ChangeKind { ... }
    fn action_kind(&self) -> ActionKind { ... }
    fn incoming_message(&self) -> bool { ... }
    fn describe(&self, doc: &AutoCommit) -> Option<Described> { ... }
}

Expand description

A value that deterministically mutates a CRDT Doc.

apply MUST be a pure function of (self, doc-state) — no wall-clock reads, no RNG, no local-only state — and MUST NOT commit; the executor owns the commit boundary (actor id + timestamp) so the change is content-addressed identical everywhere.

Concrete actions are app-defined enums deriving Serialize/ Deserialize, registered by type_id in an ActionRegistry so a replaying peer can reconstruct them.

Required Methods§

fn apply(&self, doc: &mut AutoCommit) -> Result<(), ActionError>

Apply this action’s mutation to doc. See the trait contract.

§Errors

Implementations return ActionError::Automerge for a document write failure, or ActionError::Refused if the app declines to carry out an otherwise well-formed action.

Provided Methods§

fn locus(&self) -> ExecutionLocus

Where this action prefers to run. Defaults to ExecutionLocus::ClientLocal.

fn risk(&self) -> RiskLevel

The consequence class of this particular value — what it would do, not what its type can do. A generic edit action classifies each value (deleting a clip is Destructive, trimming one is not), and the host asks for the same confirmation a declared destructive action gets whenever requires_confirmation holds. Must be a pure function of self. Defaults to Low.

fn inverse_before(&self, doc: &AutoCommit) -> Option<Self>
where Self: Sized,

The document action that undoes this one when apply records an outside consequence in the document (an outbox entry, a filesystem op queue). Computed against the document before this action runs, so a delete can still read the row it removes.

When this returns Some, undo applies that action through Action::apply instead of writing Automerge inverse patches — so the compensating queue entry is recorded the same way peers will replay it. Pure CRDT actions with no outside consequence leave this as None; inverse patches remain correct for them. Effects never participate: they have no heads and are not undoable.

fn inverse_encoded(&self, doc: &AutoCommit) -> Option<EncodedAction>

inverse_before as an encoded action, so the door can undo through apply after the concrete type has been erased.

The palette, an agent and a script apply a decoded dyn Action. That value cannot return Self. An action whose apply writes an outside queue implements this and encodes the compensating action under the same registry type id. The default is None: undo stays Automerge inverse patches.

fn change_kind(&self) -> ChangeKind

Whether this value changes the document’s content or is housekeeping about it (a read marker, a reading position). The executor writes it into the change’s ActionContext, where a workspace activity feed reads it. Must be a pure function of self. Defaults to Content.

fn action_kind(&self) -> ActionKind

What kind of action this value is: whether it only changes the document or also reaches outside it. Must be a pure function of self. An action that records an outside consequence in the document (an outbox entry) is Outside; the default is Undoable.

fn incoming_message(&self) -> bool

Whether this value records a message someone received (a chat post, a delivered mail). The executor marks its change with INCOMING_MESSAGE_FACET. Must be a pure function of self.

fn describe(&self, doc: &AutoCommit) -> Option<Described>

What this value does and to which item, as history records it: a field edit with its values before and after, a verb with its plain arguments, or a group of those. Read from doc as it is before the value applies, on the origin only; replicas replay it with the change. None lets the executor describe the value as the verb its encoded form names (crate::Described::from_encoded).

Implementations on Foreign Types§

§

impl<A> Action for ActionGroup<A>
where A: Action + Serialize,

§

fn risk(&self) -> RiskLevel

A group is as consequential as its most consequential member: one deletion in a gesture makes the gesture ask for confirmation.

§

fn describe(&self, doc: &AutoCommit) -> Option<Described>

A gesture records each of its members, and the item they share.

§

fn change_kind(&self) -> ChangeKind

A gesture is someone’s step when any member is: one content change makes it content. Otherwise it is external when any member is, and housekeeping when every member is.

§

fn incoming_message(&self) -> bool

A gesture that records a received message among others still records one.

§

fn apply(&self, doc: &mut AutoCommit) -> Result<(), ActionError>

Read the record, run the method, write back what changed ([apply_operation]).

§

fn change_kind(&self) -> ChangeKind

An outbox settlement is content from outside and forgetting a settled entry is housekeeping: neither is anyone’s undo step, so an undo never sends a mail twice.

§

fn inverse_encoded(&self, doc: &AutoCommit) -> Option<EncodedAction>

A verb that declares its undo is undone by applying that verb, and a change of a record that queues by applying the edits that restore it: either queues the compensating outside consequence.

§