Crate ironflow 

Event-sourced workflow engine for durable, long-running processes.

Ironflow provides a minimal, type-safe framework for building workflows where:

• Pure functional core — Workflow::evolve and Workflow::decide are deterministic with no side effects
• Event sourcing — State is reconstructed by replaying events
• Async effects — Side effects are queued to an outbox for external processing

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                            Decider<W, S>                                │
│                                                                         │
│   1. Begin unit of work (acquires lock)                                 │
│   2. Replay events → state                                              │
│   3. decide(now, state, input) → events + effects                       │
│   4. Append events to store                                             │
│   5. Enqueue effects to outbox                                          │
│   6. Commit unit of work                                                │
└─────────────────────────────────────────────────────────────────────────┘

Example

use ironflow::{Decision, Decider, HasWorkflowId, PgStore, Workflow, WorkflowId};

struct CounterWorkflow;

impl Workflow for CounterWorkflow {
    type State = i32;
    type Input = CounterInput;
    type Event = CounterEvent;
    type Effect = ();

    const TYPE: &'static str = "counter";

    fn evolve(state: Self::State, event: Self::Event) -> Self::State {
        match event {
            CounterEvent::Incremented => state + 1,
        }
    }

    fn decide(_now: time::OffsetDateTime, _state: &Self::State, _input: &Self::Input)
        -> Decision<Self::Event, Self::Effect, Self::Input>
    {
        Decision::event(CounterEvent::Incremented)
    }
}

// Execute a workflow decision
let store = PgStore::new(pool);
let decider: Decider<CounterWorkflow, _> = Decider::new(store);
decider.execute(&CounterInput::Increment { id: "counter-1".into() }).await?;

Feature Flags

• postgres — Enables PgStore for production use with PostgreSQL

Design Documentation

See DESIGN.md for architectural decisions and future work.

Re-exports

pub use effect::EffectContext;

pub use effect::EffectHandler;

pub use effect::RetryPolicy;

pub use runtime::RuntimeConfig;

pub use runtime::WorkflowBuilder;

pub use runtime::WorkflowRuntime;

pub use store::PgStore;

pub use store::BeginResult;

pub use store::DeadLetter;

pub use store::DeadLetterQuery;

pub use store::EventStore;

pub use store::InputObservation;

pub use store::OutboxStore;

pub use store::ProjectionStore;

pub use store::Store;

pub use store::StoredEvent;

pub use visualization::FieldValue;

pub use visualization::StateDefinition;

pub use visualization::StateInfo;

pub use visualization::StateMachineDefinition;

pub use visualization::StateMachineView;

pub use visualization::TransitionDefinition;

pub use visualization::TransitionInfo;

Modules

effect

Effect execution types for workflow side effects.

runtime

Runtime for executing workflow effects.

store

Storage abstraction for workflow events and effects.

visualization

State machine visualization for workflows.

Structs

Decision

Actions to execute as a result of a workflow decision.

NonEmpty

Non-empty vector.

ProjectionConfig

Configuration for projection workers.

ProjectionEvent

Projection event delivered to projection handlers.

ProjectionWorker

Worker that applies projections using global event ordering.

Timer

A scheduled timer that will deliver an input to the workflow at a future time.

WorkflowEngine

Convenience bundle for a service + runtime pair.

WorkflowId

A workflow instance identifier (business key).

WorkflowRef

Reference to a specific workflow instance.

WorkflowService

App-facing workflow service.

WorkflowServiceConfig

Configuration for the workflow service.

Enums

Error

Errors that can occur in ironflow operations.

Traits

HasWorkflowId

Extracts the workflow instance ID (business key) from an input.

Projection

Projection handler trait.

Workflow

Pure workflow logic: state reconstruction via evolve, decisions via decide.

Type Aliases

Result

A Result alias with Error as the error type.

Derive Macros

HasWorkflowId

Derives HasWorkflowId for an enum.