Struct Runtime 

pub struct Runtime<S> { /* private fields */ }

Executes effects against a store. Cheap to clone; clones share state.

Implementations

impl<S: EffectStore> Runtime<S>

pub fn compensation( &self, name: impl Into<String>, key: impl Display, ) -> CompensationBuilder<'_, S>

Starts undoing the closure effect (name, key). See CompensationBuilder::run.

impl<S: EffectStore> Runtime<S>

pub async fn recover(&self) -> Result<RecoveryReport, RuntimeError>

One recovery pass, in two steps.

1. Every effect whose worker’s lease expired mid-attempt or mid-verification becomes Unknown, never Failed: it may have changed the outside world.
2. Every unsettled effect nobody holds (see Self::pending) whose name has a registered handler is finished from its stored input, exactly as if its caller had called again: verified, re-run if that is safe, or escalated. This includes effects left Pending by a crash. Effects waiting for an operator, and retries scheduled for later, are left alone. Unsettled closure effects are reported as unhandled: only a caller can re-run them.

Effects are resumed one at a time, so a pass lasts as long as their retries and verifications take. Safe to run from several workers at once: every change happens under a lease.

Errors

RuntimeError::Store if the store fails. Progress made before the failure is kept. A handler that cannot run is reported in resume_errors instead.

pub async fn run_recovery(&self, interval: Duration)

Runs Self::recover every interval, forever, followed by Self::prune when the runtime has a retention policy. Spawn it:

tokio::spawn({
    let runtime = runtime.clone();
    async move { runtime.run_recovery(Duration::from_secs(30)).await }
});

A failed pass is logged and retried at the next tick.

pub async fn pending( &self, after: Option<EffectId>, limit: usize, ) -> Result<Vec<EffectRecord>, RuntimeError>

Effects waiting for a caller to re-run them or an operator to decide, ordered by creation, limit at a time after after.

These are the effects that are unsettled with nobody working on them: Pending (for example a worker died during a backoff wait), Executing or Verifying with an expired lease (not yet recovered), Unknown, NeedsIntervention, AwaitingApproval, an interrupted Compensating, and CompensationFailed.

Errors

RuntimeError::Store if the store fails.

pub async fn resolve( &self, id: EffectId, resolution: Resolution, actor: impl Into<String>, note: impl Into<String>, ) -> Result<EffectRecord, RuntimeError>

Records an operator’s decision about an effect that is Unknown or NeedsIntervention. actor identifies the operator (e.g. operator:alice); note says why, for the audit trail.

Errors

RuntimeError::Store wrapping:

• StoreError::NotFound for an unknown id;
• StoreError::InvalidTransition if the effect is not unresolved, for example already committed;
• StoreError::LeaseHeld while a caller or worker is working on it;
• StoreError::VersionConflict if it changed during the call.

pub async fn approve( &self, id: EffectId, actor: impl Into<String>, note: impl Into<String>, ) -> Result<EffectRecord, RuntimeError>

Approves an effect waiting in AwaitingApproval. It becomes Pending: a caller’s next call runs it, and so does recovery for a registered handler. actor is recorded as the approver.

Errors

As for Self::resolve; InvalidTransition if it is not awaiting approval.

pub async fn deny( &self, id: EffectId, actor: impl Into<String>, reason: impl Into<String>, ) -> Result<EffectRecord, RuntimeError>

Denies an effect waiting in AwaitingApproval. It ends Rejected, with reason as its error.

Errors

As for Self::approve.

impl<S: EffectStore> Runtime<S>

pub async fn prune(&self) -> Result<PruneReport, RuntimeError>

Deletes the settled records the retention policy says are old enough, in batches, with their audit trails. Does nothing without a policy. Self::run_recovery calls it every round; call it yourself to prune on another schedule.

Errors

RuntimeError::Store if the store fails. Batches deleted before the failure stay deleted.

impl<S: EffectStore> Runtime<S>

pub fn new(store: S) -> Self

A runtime with default settings.

pub fn builder(store: S) -> RuntimeBuilder<S>

Starts configuring a runtime.

pub fn effect( &self, name: impl Into<String>, key: impl Display, ) -> EffectBuilder<S>

Describes an effect: name is its type (e.g. payment.charge), key identifies this occurrence (e.g. the order id). Every call with the same name and key refers to the same effect.

pub fn submit<H: EffectHandler>( &self, key: impl Display, input: H::Input, ) -> Submission<'_, S, H>

Runs a registered handler’s effect with input, or attaches to an earlier run with the same key. Await the returned Submission.

Behaves like EffectBuilder::run, with the handler’s properties. The input is stored in full, so recovery can finish the effect if this process dies.

pub fn compensate<H: EffectHandler>( &self, key: impl Display, ) -> CompensationSubmission<'_, S, H>

Undoes a registered, compensable handler’s effect. Await the returned submission. See compensation.

pub fn store(&self) -> &S

The underlying store.

pub fn worker_id(&self) -> &WorkerId

This runtime’s lease-holder identity.

pub async fn wait<T: DeserializeOwned>( &self, id: EffectId, timeout: Duration, ) -> Result<EffectOutcome<T>, RuntimeError>

Waits until nobody is working on effect id, or timeout passes, and reports where it stands. For a caller that got EffectOutcome::InProgress.

Returns InProgress if the effect is still being worked on at the deadline, or if it is unsettled and nobody holds it (for example a worker crashed while waiting to retry). Running the effect again then takes it over.

Errors

RuntimeError::Store if the store fails or has no such effect, and RuntimeError::Output if a committed output does not deserialize into T.

Trait Implementations

impl<S> Clone for Runtime<S>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.