Struct FlowEngine 

pub struct FlowEngine { /* private fields */ }

Event-sourced workflow engine.

Implementations

impl FlowEngine

pub async fn continuation_chain( &self, run_id: &str, ) -> Result<Vec<WorkflowRunSnapshot>>

Follow persisted continue-as-new links from run_id in execution order.

Every returned snapshot owns an independent, append-only event stream. Missing successors and cycles fail closed instead of silently returning a partial lineage.

pub async fn drive(&self, run_id: &str) -> Result<WorkflowRunSnapshot>

Replay and dispatch until the execution reaches a terminal state or an open wait, hook, retry, or child-workflow suspension.

A continue-as-new terminal event is followed into its fresh successor segment. The returned snapshot therefore belongs to the active leaf of the execution chain, which can differ from run_id.

impl FlowEngine

pub async fn resume_hook( &self, run_id: &str, hook_id: &str, payload: Value, ) -> Result<()>

Resume a hook with an external payload.

Redelivery through a durable outbox is idempotent when the hook already contains the same payload, including after the run becomes terminal. A different payload or a different terminal hook resolution is rejected explicitly instead of being mistaken for the committed outcome. When the resolved run continued as new, matching redelivery follows and repairs its active successor.

pub async fn dispose_hook(&self, run_id: &str, hook_id: &str) -> Result<()>

Dispose an active hook without accepting a callback payload.

This is useful when a host withdraws an approval request, expires a webhook token, or closes an external callback route. Redelivery is idempotent when the hook was already disposed. A received or cancelled hook conflicts with disposal and cannot be reported as successful. When the resolved run continued as new, matching redelivery follows and repairs its active successor.

pub async fn resume_hook_by_token( &self, token: &str, payload: Value, ) -> Result<(String, String)>

Resume an active hook by its external token.

Token lookup intentionally covers only active hooks. Durable consumers that need idempotent redelivery after resolution must retain the stable run and hook identities and call Self::resume_hook.

pub async fn dispose_hook_by_token( &self, token: &str, ) -> Result<(String, String)>

Dispose an active hook by its external token.

This mirrors resume_hook_by_token for callback routers that only know the public token.

impl FlowEngine

pub async fn snapshot(&self, run_id: &str) -> Result<WorkflowRunSnapshot>

Project the current snapshot for run_id from its durable history.

pub async fn history(&self, run_id: &str) -> Result<Vec<FlowEventEnvelope>>

Load the complete durable event history for run_id.

pub async fn list_run_ids(&self) -> Result<Vec<String>>

List all workflow run IDs known to the engine’s store.

pub async fn list_snapshots(&self) -> Result<Vec<WorkflowRunSnapshot>>

Project current snapshots for every workflow run in the store.

pub async fn run_summary(&self) -> Result<WorkflowRunSummary>

Summarize run state across the active store.

Suspension counters include only non-terminal runs, so a cancelled run that still has old suspension history is not reported as actionable.

pub async fn list_open_suspensions( &self, now: DateTime<Utc>, ) -> Result<Vec<WorkflowRunSuspension>>

List open waits, active hooks, signal waits, delayed retries, and child runs.

The due flag on wait and retry suspensions is computed against now. Terminal runs are skipped so cancelled histories do not produce actionable operator work.

pub async fn next_wakeup( &self, now: DateTime<Utc>, ) -> Result<Option<WorkflowRunSuspension>>

Return the earliest open wait or delayed retry across non-terminal runs.

Active hooks and signal waits are intentionally ignored because they do not have a scheduled wake-up time.

pub async fn list_active_hooks(&self) -> Result<Vec<ActiveHookSnapshot>>

List active external callback hooks across non-terminal runs.

impl FlowEngine

pub async fn request_cancellation( &self, run_id: &str, request: CancellationRequest, ) -> Result<WorkflowRunSnapshot>

Request cleanup-aware cancellation and replay the workflow.

The request atomically makes waits, hooks, and retrying/running steps that existed before it non-actionable and propagates persisted policy to first-class child workflows. Workflow code observes the request through WorkflowContext::cancellation_request, performs host-owned cleanup with stable step identities, and returns RuntimeCommand::Cancel. Repeating the same request is idempotent. When run_id names a continued predecessor, the request repairs and follows durable links to the active successor. A terminal leaf is returned without runtime-build admission; a non-terminal leaf must pass admission before the cancellation event or workflow replay.

pub async fn force_cancel( &self, run_id: &str, reason: Option<String>, ) -> Result<()>

Immediately terminate the active continuation leaf without cleanup.

pub async fn cancel(&self, run_id: &str, reason: Option<String>) -> Result<()>

Backward-compatible immediate cancellation API.

New cleanup-aware workflows should call Self::request_cancellation.

pub async fn terminate_for_timeout( &self, run_id: &str, deadline: DateTime<Utc>, reason: Option<String>, ) -> Result<()>

Immediately terminate a run with a typed timeout outcome.

pub async fn terminate_for_host_shutdown( &self, run_id: &str, reason: Option<String>, ) -> Result<()>

Explicitly abandon a run under a non-resumable host-shutdown policy.

Ordinary process shutdown must not call this method: durable runs should normally remain non-terminal and resume on a replacement host.

pub async fn record_progress( &self, run_id: &str, progress: WorkflowProgress, ) -> Result<()>

Persist a host-reported progress update exactly once on the active leaf.

pub async fn link_child_operation( &self, run_id: &str, child: ChildOperationReference, ) -> Result<()>

Persist a parent-to-child reference exactly once on the active leaf.

impl FlowEngine

pub async fn start(&self, spec: WorkflowSpec, input: Value) -> Result<String>

Start a workflow run and drive it until completion or suspension.

pub async fn start_with_id( &self, run_id: impl Into<String>, spec: WorkflowSpec, input: Value, ) -> Result<String>

Start a workflow run using a caller-provided durable run id.

Reusing the same run_id with the same workflow spec and input is idempotent. A fully terminal execution is acknowledged without runtime build admission; an active leaf still requires its pinned build before replay. Reusing the id with different spec or input returns a conflict.

impl FlowEngine

pub async fn resume_wait(&self, run_id: &str, wait_id: &str) -> Result<()>

Resume a wait once its timer has fired.

Redelivery is idempotent after the existing wait has completed or its run has become terminal. A resolved wait still drives recovery through any committed continue-as-new boundary, but no second wait_completed event is appended.

pub async fn list_due_waits( &self, now: DateTime<Utc>, ) -> Result<Vec<(String, String)>>

List active waits whose resume_at is at or before now.

Scheduler integrations can use this to inspect due timers before deciding how aggressively to drive them.

pub async fn resume_due_waits( &self, now: DateTime<Utc>, ) -> Result<Vec<(String, String)>>

Complete every due wait and drive the affected workflows.

Returns only the (run_id, wait_id) pairs completed by this call. A wait completed or cancelled by another caller after the due scan is safely skipped.

pub async fn list_due_retries( &self, now: DateTime<Utc>, ) -> Result<Vec<(String, String)>>

List pending step retries whose retry_after is at or before now.

pub async fn list_due_wakeups( &self, now: DateTime<Utc>, ) -> Result<Vec<ScheduledWakeup>>

List all due wait timers and delayed retries through the store boundary.

pub async fn resume_due_retries( &self, now: DateTime<Utc>, ) -> Result<Vec<(String, String)>>

Drive every run with a due step retry.

pub async fn resume_scheduled_run( &self, run_id: &str, now: DateTime<Utc>, ) -> Result<Vec<ScheduledWakeup>>

Resume the due waits and delayed retries for one targeted run.

Unlike the compatibility-wide resume_due_* methods, this path loads only run_id and never performs another global due-wakeup query. The returned records describe the wakeups that were still due when the task began handling.

impl FlowEngine

pub async fn send_signal( &self, run_id: &str, signal: WorkflowSignal, ) -> Result<WorkflowRunSnapshot>

Durably deliver a named asynchronous signal to an active execution.

The target follows persisted continue-as-new links. Retrying with the same target run ID and signal_id is idempotent across that descendant chain; changing the name or payload is an explicit conflict. New and matching deliveries repair and drive the active leaf, including a successor missing after its predecessor link committed.

impl FlowEngine

pub fn builder(runtime: Arc<dyn FlowRuntime>) -> FlowEngineBuilder

Create an engine builder for runtime.

pub fn new( store: Arc<dyn FlowEventStore>, runtime: Arc<dyn FlowRuntime>, ) -> Self

Create an engine with the supplied store, runtime, and default limits.

pub fn in_memory(runtime: Arc<dyn FlowRuntime>) -> Self

Create an engine backed by a new in-memory event store.

pub fn store(&self) -> Arc<dyn FlowEventStore>

Clone the engine’s event-store handle.

pub fn observer(&self) -> Arc<dyn FlowEventObserver>

Clone the engine’s event-observer handle.

pub fn runtime_build_compatibility(&self) -> Option<&RuntimeBuildCompatibility>

Return this engine’s explicit runtime-build admission policy.

pub fn supports_runtime_build( &self, required_build_id: Option<&RuntimeBuildId>, ) -> bool

Return whether this engine can replay a pinned or legacy run.

pub async fn runtime_build_id( &self, run_id: &str, ) -> Result<Option<RuntimeBuildId>>

Read the runtime build identity pinned by one run.

Trait Implementations

impl Clone for FlowEngine

fn clone(&self) -> FlowEngine

Returns a duplicate of the value.

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

Performs copy-assignment from source.