Struct ActionContract

pub struct ActionContract {
    pub availability: Availability,
    pub kind: ActionKind,
    pub field: Option<String>,
    pub risk: RiskLevel,
    pub confirmation: ConfirmationPolicy,
    pub retry: RetryPolicy,
    pub execution: ExecutionMode,
    pub result: ResultSpec,
    pub tags: Vec<String>,
    pub offload: Option<Offload>,
}

Expand description

Complete operational contract copied into every inert descriptor.

Fields§

§availability: Availability§kind: ActionKind

What the action is able to do: read, change only the document, or reach outside it. Whether Undo takes it back and whether it asks first follow from it. What a grant must allow is its need, which every door decides with the action’s place in the published tree: the kind, unless the action’s scope reaches nothing a workspace governs (Self::scoped).

§field: Option<String>

The one field of its resource the action writes, when it writes only one: the action sits below that field in the tree, so a grant on the field (commenting is writing comments) reaches it.

§risk: RiskLevel§confirmation: ConfirmationPolicy§retry: RetryPolicy§execution: ExecutionMode§result: ResultSpec§tags: Vec<String>§offload: Option<Offload>

The action is heavy enough to run on another of the invoker’s devices, and how: see Offload. None (the default) runs it where it is invoked, always.

Implementations§

§

impl ActionContract

pub fn need(&self) -> ActionNeed

What an invocation needs when its value does not say otherwise: its kind, scoped.

pub fn scoped(&self, need: ActionNeed) -> ActionNeed

The authority need asks of a workspace once this action’s scope is accounted for. The kind says what the action does (whether Undo takes it back, whether it asks first); the need says what a grant must allow, and the scope is where they part: a change of the person’s own record (OWN_RECORD_SCOPE) and an outside effect on the person’s own device (OWN_DEVICE_SCOPE, ATTENDED_TAG) reach nothing a workspace’s grants govern, so they need only what reading needs.

pub fn view() -> ActionContract

Safe defaults for a presentation-only operation.

pub fn live_view(item_schema: Value) -> ActionContract

A view whose result stays current (ExecutionMode::Live), each item matching item_schema.

pub const fn is_live(&self) -> bool

Whether the action’s result stays current (ExecutionMode::Live).

pub fn for_operation(operation: OperationKind) -> ActionContract

The defaults for an operation of operation’s kind: a view reads, a document operation changes only the document, an effect reaches outside it.

pub fn is_own_device(&self) -> bool

Whether the effect’s scope is the invoking person’s own device and nothing shared. See OWN_DEVICE_SCOPE.

pub fn is_own_record(&self) -> bool

Whether the action changes a record of the invoking person’s own. See OWN_RECORD_SCOPE.

pub fn set_own_record(&mut self)

Mark the action as carried out on a record of the invoking person’s own: it keeps its kind and needs only what reading needs. See OWN_RECORD_SCOPE.

pub fn is_attended(&self) -> bool

Whether the action needs its person attending. See ATTENDED_TAG.

pub fn runs_on_invokers_device(&self) -> bool

Whether the action acts on the device of whoever invokes it, so only the person at that device (and those acting for them) runs it: an effect of OWN_DEVICE_SCOPE or one its person attends (ATTENDED_TAG).

pub fn audience(&self) -> Audience

Who the action is listed for, as its tags record it. See Audience.

pub fn set_audience(&mut self, audience: Audience)

Record audience in the tags, replacing any audience before it.

pub fn reaches_people(&self) -> bool

Whether people’s listings offer it. See Audience::reaches_people.

pub fn reaches_agents(&self) -> bool

Whether agents’ listings offer it. See Audience::reaches_agents.

pub fn reads_document(&self) -> bool

Whether the action reads the open document’s first page. See DOCUMENT_READ_TAG.

pub fn opens_path(&self) -> bool

Whether the action opens the file its path names. See OPENS_PATH_TAG.

pub fn opened_extensions(&self) -> impl Iterator<Item = &str>

The file extensions an opens_path action is declared for; none means any file. See OPENS_PATH_EXTENSION_PREFIX.

pub fn carries_untrusted_content(&self) -> bool

Whether the action’s result carries content from outside the user’s own data. See UNTRUSTED_CONTENT_TAG.

pub fn can_be_undone(&self) -> bool

Whether the action, once taken, can be undone: the host’s undo reverts an Undoable change, and an outside one declared with its compensation (COMPENSATED_UNDO_TAG) is undone by queueing it. One that also loses what Undo cannot bring back (IRREVERSIBLE_TAG) cannot.

pub fn requires_confirmation(&self) -> bool

Whether an invocation of this action must be confirmed before it runs: its risk asks for it and Undo cannot take it back (RiskLevel::requires_confirmation_when).

pub fn settle_confirmation(&mut self)

Bring the declared policy in line with the risk and whether Undo takes the action back: a deletion Undo takes back asks nothing, one it cannot asks with a click. An explicit typed phrase, and the policy of any other risk, stay as declared. Every builder that changes the risk, the undo or the tags calls this, so the order they are called in never decides whether a person is asked.

The kind is read through settled_kind, so a deletion built before the kind that makes it undoable still ends up asking nothing, and one a declaration says reaches outside still asks.

pub fn settled_kind(&self) -> ActionKind

The kind this contract says the action is, where kind cannot say it alone: a change to its own document is undoable unless it keeps something Undo cannot bring back (IRREVERSIBLE_TAG), or unless it reaches outside and queues its compensation (COMPENSATED_UNDO_TAG).

pub fn deletion_kind(&self) -> ActionKind

The kind of a deletion, which has to say which it is: what its kind settles to, less where Undo cannot take the change back at all.

pub fn confirmation_depends_on_arguments(&self) -> bool

Whether confirmation depends on the invocation’s arguments. See ARGUMENT_RISK_TAG.

pub fn advertised_confirmation(&self) -> ConfirmationPolicy

The confirmation a caller that cannot classify arguments must assume: the declared policy, or ConfirmationPolicy::Confirm for an action whose risk depends on its arguments. A trust boundary that only sees this inert contract (the session broker) gates on it; the publishing host, which can classify, asks ActionSpec::confirmation_for_json.

pub fn asks_for_argument(&self, argument: Option<&str>) -> bool

Whether an invocation with argument asks the person an agent acts for, whatever their broader answers allow: it needs a confirmation (Self::confirmation_for_argument) or its person attending (Self::is_attended).

pub fn confirmation_for_argument( &self, argument: Option<&str>, ) -> ConfirmationPolicy

The confirmation an invocation with argument (the wire argument: typed JSON behind ARGUMENTS_JSON_PREFIX) needs, decided without the publishing app’s code: the declared policy; for a generic field edit, the edit itself read by tilo_action_policy::edits::field_edit_asks; for any other action whose risk depends on its arguments, Self::advertised_confirmation.

pub fn validate_declaration(&self) -> Vec<String>

Validate the contract as inert protocol data. This is intentionally usable at both publication ends: a well-behaved app checks before it sends, and the broker repeats the check at its trust boundary.

§