Crate wfe 

wfe — Umbrella crate for the WFE workflow engine.

This crate re-exports everything from wfe-core and adds WorkflowHost, the main orchestrator that ties persistence, locking, queuing, and execution into a single runtime.

Getting started

A minimal workflow host needs three providers: persistence, locking, and queuing. For local development or testing, use the in-memory providers from wfe-core::test_support, or use wfe-sqlite for file-based persistence.

use std::sync::Arc;
use wfe::{WorkflowHostBuilder, WorkflowHost};
use wfe_core::test_support::{InMemoryPersistenceProvider, InMemoryLockProvider, InMemoryQueueProvider};

let host = WorkflowHostBuilder::new()
    .use_persistence(Arc::new(InMemoryPersistence::new()))
    .use_lock_provider(Arc::new(InMemoryLockProvider::new()))
    .use_queue_provider(Arc::new(InMemoryQueueProvider::new()))
    .build()?;

// Register a workflow definition built with the fluent API.
host.register_workflow::<serde_json::Value>(
    &|builder| {
        builder
            .start_with::<MyStep>()
            .name("do the thing")
            .end_workflow()
    },
    "my-workflow",
    1,
).await;

// Register the step type so the executor can construct it.
host.register_step::<MyStep>().await;

// Start background consumer tasks.
host.start().await?;

// Launch an instance.
let id = host.start_workflow("my-workflow", 1, serde_json::json!({"key": "value"})).await?;

Architecture

┌─────────────────────────────────────────────┐
│              WorkflowHost                   │
│  ┌─────────┐  ┌─────────┐  ┌────────────┐ │
│  │Registry │  │Executor │  │ Providers  │ │
│  │(defs)   │  │(run)    │  │(persist)   │ │
│  └────┬────┘  └────┬────┘  └─────┬──────┘ │
│       │            │             │        │
│  ┌────┴────────────┴─────────────┴──────┐ │
│  │         Background Consumers          │ │
│  │   (workflow queue + event queue)      │ │
│  └───────────────────────────────────────┘ │
└─────────────────────────────────────────────┘

Lifecycle

1. Build the host with WorkflowHostBuilder.
2. Register workflow definitions with WorkflowHost::register_workflow.
3. Register step types with WorkflowHost::register_step.
4. Start the host with WorkflowHost::start to spawn background consumers.
5. Launch instances with WorkflowHost::start_workflow.
6. Publish events with WorkflowHost::publish_event to resume waiting workflows.
7. Query / control instances with WorkflowHost::get_workflow, WorkflowHost::suspend_workflow, WorkflowHost::resume_workflow, WorkflowHost::terminate_workflow.

Re-exports

Everything from wfe-core is re-exported at the top level for convenience: WorkflowBuilder, StepBody, ExecutionResult, models, traits, and primitives.

Feature flags

Feature	Description
otel	OpenTelemetry tracing integration

Re-exports

pub use host::WorkflowHost;

pub use host_builder::WorkflowHostBuilder;

pub use purger::purge_workflows;

pub use registry::InMemoryWorkflowRegistry;

pub use sync_runner::run_workflow_sync;

Modules

artifact_volume

Artifact volume abstraction for distributed workflow execution. Artifact volume abstraction for distributed workflow execution.

builder

Fluent builder API for composing workflow definitions.

error

Error types and the Result alias used throughout WFE.

executor

The workflow executor and supporting infrastructure.

host

The main orchestrator that ties all workflow engine components together.

host_builder

Fluent builder for constructing a WorkflowHost.

local_artifact_store

Local filesystem artifact store (OCI Image Layout). Local filesystem-based artifact store using the OCI Image Layout.

models

Data models for workflows, instances, pointers, events, and execution results. Core data models for workflows, execution pointers, events, and results.

primitives

Built-in control-flow primitives (if, while, foreach, saga, etc.). Built-in control-flow primitives for workflow definitions.

purger

Workflow cleanup utilities.

registry

In-memory workflow definition registry.

sync_runner

Synchronous blocking runner for integration tests.

test_support

In-memory test doubles for every provider trait.

traits

Core traits that define the plugin architecture.

Macros

lock_suite

Generates a test suite for any DistributedLockProvider implementation.

persistence_suite

Generates a test suite for any PersistenceProvider implementation.

queue_suite

Generates a test suite for any QueueProvider implementation.

Structs

ArtifactVolume

A portable collection of raw artifacts resolved for a single workflow step.

ArtifactVolumePackage

Serialized, transmissible form of an ArtifactVolume.

LocalArtifactStore

A local filesystem artifact store following the OCI Image Layout.

Enums

WfeError

Wfeerror.

Functions

extract_artifact_to_dir

Extract an artifact blob (gzip-compressed tar) into a directory.

Type Aliases

Result

Result.