Sienna Meridian Satterwhite
386cd2255d
Root README covers architecture, Rust builder API quick start, YAML pipeline quick start, provider table, deno executor overview, feature flags, and testing instructions. Per-crate READMEs follow consistent structure: one-liner, what it does, quick start code example, API reference, configuration, testing, license. Engineering-confident tone throughout.
86 lines
3.2 KiB
Markdown
86 lines
3.2 KiB
Markdown
# 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:
|
|
|
|
```rust
|
|
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 `WorkflowDefinition`s. 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
|
|
|
|
```sh
|
|
cargo test -p wfe-core
|
|
```
|
|
|
|
No external dependencies required.
|
|
|
|
## License
|
|
|
|
MIT
|