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, HasWorkflowId, Never, PgStore, Workflow, WorkflowId,
    WorkflowRuntime, WorkflowServiceConfig,
};

struct CounterWorkflow;

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

    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, Self::Rejection> {
        Decision::accept(CounterEvent::Incremented)
    }
}

// Build the service and execute a workflow input.
let store = PgStore::new(pool);
let service = WorkflowRuntime::builder(store, WorkflowServiceConfig::default())
    .register_without_effects::<CounterWorkflow>()
    .build_service()?;
service
    .execute::<CounterWorkflow>(&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::ObservationOutcome;

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

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 after a delay. The actual fire time is computed DB-side as now() + delay when the timer is written, so this type doesn’t need to read the wall clock and decide stays deterministic.

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

Decision

What Workflow::decide returns for an input.

Error

Errors that can occur in ironflow operations.

ExecuteOutcome

Result of WorkflowService::execute and WorkflowService::execute_dynamic.

Never

Uninhabited Workflow::Rejection type for workflows that can never reject.

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.