wfe/wfe-core/README.md

wfe-core

Core traits, models, builder, and executor for the WFE workflow engine.

What it does

wfe-core defines the foundational abstractions that every other WFE crate builds on. It provides the StepBody trait for implementing workflow steps, a fluent WorkflowBuilder for composing workflow definitions, a WorkflowExecutor that drives step execution with locking and persistence, and a library of built-in control-flow primitives (if/while/foreach/parallel/saga).

Quick start

Define a step by implementing StepBody, then wire steps together with the builder:

use async_trait::async_trait;
use wfe_core::builder::WorkflowBuilder;
use wfe_core::models::ExecutionResult;
use wfe_core::traits::step::{StepBody, StepExecutionContext};

#[derive(Default)]
struct Greet;

#[async_trait]
impl StepBody for Greet {
    async fn run(&mut self, _ctx: &StepExecutionContext<'_>) -> wfe_core::Result<ExecutionResult> {
        println!("hello from a workflow step");
        Ok(ExecutionResult::next())
    }
}

let definition = WorkflowBuilder::<serde_json::Value>::new()
    .start_with::<Greet>()
    .name("greet")
    .end_workflow()
    .build("hello-workflow", 1);

API

Type / Trait	Description
StepBody	The core unit of work. Implement run() to define step behavior.
StepExecutionContext	Runtime context passed to each step (workflow data, persistence data, cancellation token).
WorkflowData	Marker trait for data flowing between steps. Auto-implemented for anything Serialize + DeserializeOwned + Send + Sync + Clone.
WorkflowBuilder<D>	Fluent builder for composing WorkflowDefinitions. Supports start_with, then, if_do, while_do, for_each, parallel, saga.
StepBuilder<D>	Per-step builder returned by WorkflowBuilder. Configures name, error behavior, compensation.
WorkflowExecutor	Acquires a lock, loads the instance, runs all active pointers, processes results, persists.
StepRegistry	Maps step type names to factory functions.
PersistenceProvider	Composite trait: WorkflowRepository + EventRepository + SubscriptionRepository + ScheduledCommandRepository.
DistributedLockProvider	Trait for acquiring/releasing workflow-level locks.
QueueProvider	Trait for enqueuing/dequeuing workflow and event work items.

Built-in primitives

Primitive	Purpose
IfStep	Conditional branching
WhileStep	Loop while condition holds
ForEachStep	Iterate over a collection
SequenceStep	Parallel branch container
DecideStep	Multi-way branching
DelayStep	Pause execution for a duration
ScheduleStep	Resume at a specific time
WaitForStep	Suspend until an external event
SagaContainerStep	Transaction-like compensation
RecurStep	Recurring/periodic execution
EndStep	Explicit workflow termination

Features

Feature	Description
test-support	Exposes test_support module with in-memory persistence and helpers for testing workflows.
otel	Enables OpenTelemetry integration via tracing-opentelemetry.

Testing

cargo test -p wfe-core

No external dependencies required.

License

MIT