Crate floxide

Floxide: Distributed Workflow Framework for Rust

Floxide is a professional, extensible framework for building distributed, parallel, and event-driven workflows in Rust. It enables you to model complex business processes, data pipelines, and automation tasks as directed graphs, with robust support for distributed execution, checkpointing, and custom node logic.

Key Features

• Distributed Execution: Run workflows across multiple workers or nodes, with in-memory or pluggable backends for queues and checkpointing.
• Parallelism: Express parallel branches and concurrent processing natively in your workflow graphs.
• Type-Safe Nodes: Each node defines its own input/output types, ensuring correctness at compile time.
• Checkpointing & Recovery: Built-in support for checkpointing workflow state, enabling fault tolerance and resumability.
• Declarative Workflow Definition: Use the workflow! and node! macros to define nodes, edges, and transitions in a clear, maintainable way.
• Production-Ready: Designed for reliability, observability, and integration with async runtimes and tracing.

Example: Distributed Parallel Workflow

use floxide::{workflow, node, Transition, WorkflowCtx, FloxideError, SharedState, Node};
use async_trait::async_trait;
use std::sync::Arc;
use tokio::sync::Mutex;
use serde::{Serialize, Deserialize};

#[derive(Clone, Debug, Serialize, Deserialize, Default)]
struct Ctx { counter: SharedState<i32> }

// Define a node that increments the counter
node! {
    pub struct StartNode {};
    context = Ctx;
    input = ();
    output = ();
    |ctx, _input| {
        let mut c = ctx.counter.get().await;
        *c += 1;
        Ok(Transition::Next(()))
    }
}

// Define a branch node that increments the counter by 10
node! {
    pub struct BranchNode {};
    context = Ctx;
    input = ();
    output = String;
    |ctx, _input| {
        let mut c = ctx.counter.get().await;
        *c += 10;
        Ok(Transition::Next(format!("done: {}", c)))
    }
}

workflow! {
    pub struct ExampleWorkflow {
        start: StartNode,
        a: BranchNode,
        b: BranchNode,
    }
    start = start;
    context = Ctx;
    edges {
        start => { [ a, b ] };
        a => {};
        b => {};
    }
}

Getting Started

Add Floxide to your Cargo.toml:

[dependencies]
floxide = "1.0.0"

For full examples and advanced usage, see the examples/ directory and the project documentation.

Modules

batch

checkpoint

composite

context

The context for a workflow execution.

distributed

error

merge

Merge trait for user-defined context merging

node

retry

Retry integration is handled via a wrapper node (RetryNode) around any Node. This preserves the existing Transition API without adding a retry variant.

source

Abstraction for value-producing (source) nodes: nodes with Input=() that emit a stream of outputs.

split

transition

workflow

Workflow Execution Modes in Floxide

Macros

node

Define a Node with fields and a process body in one macro invocation.

workflow

Define a Workflow with fields and edges in one macro invocation.

Structs

BatchNode

A node adapter that runs an inner node on a batch of inputs, collecting outputs in parallel

Checkpoint

A snapshot of a workflow’s pending work and its context.

CompositeNode

CompositeNode wraps a Workflow so it implements Node

InMemoryCheckpointStore

A simple in-memory checkpoint store using JSON serialization

RetryNode

Wrapper node that applies a RetryPolicy on inner node failures.

RetryPolicy

Policy controlling retry behavior for nodes.

SharedState

Arc<Mutex> wrapper with custom (de)serialization and debug support

Source

A channel source: external code can send values in, and this source will drive a workflow for each received item until the channel closes.

SplitNode

A node that splits its input into multiple outputs using the provided function.

WorkflowCtx

The context for a workflow execution.

Enums

BackoffStrategy

Strategy for computing backoff durations.

CheckpointError

Errors occurring during checkpoint persistence.

FloxideError

RetryError

Which errors should be retried.

Transition

Transition result of a node: Next->next node, Abort->error Transition result of a node.

Traits

CheckpointStore

A trait for persisting and loading workflow checkpoints.

Merge

A trait representing a merge operation (monoid) over values of the same type.

Node

A node takes an input and a context, and returns a transition.

WorkItem

Trait for a workflow work item.

Workflow

Trait for a workflow.

Functions

source

Create a channel-backed source node and its sender handle.

with_retry

Wrap an existing node with retry behavior according to the given policy.

Derive Macros

Merge

Derive implementation for the Merge trait.