# Hephaestus
A lightweight, compile-time validated workflow engine for Elixir. Define step-based DAG workflows with pattern matching, execute them with built-in support for branching, parallelism, and async operations — all backed by OTP.
## Features
- **Compile-time DAG validation** — catches cycles, unreachable steps, missing terminals, and event mismatches before runtime
- **Pure functional engine** — immutable state transitions, easy to test and reason about
- **Parallel execution** — fan-out to multiple steps, fan-in with automatic predecessor synchronization
- **Async-native** — first-class support for long-running operations, timers, and external event resumption
- **Pluggable adapters** — swap storage (ETS, database, Redis) and runner (local OTP, distributed) implementations
- **Context threading** — immutable initial data plus namespaced step results flowing through the workflow
- **Execution history** — built-in audit trail of every step completion
## Installation
Add `hephaestus` to your list of dependencies in `mix.exs`:
```elixir
def deps do
[
{:hephaestus, "~> 0.1.0"}
]
end
```
## Quick Start
### 1. Configure Hephaestus
```elixir
defmodule MyApp.Hephaestus do
use Hephaestus,
storage: Hephaestus.Runtime.Storage.ETS,
runner: Hephaestus.Runtime.Runner.Local
end
```
Add it to your supervision tree:
```elixir
children = [
MyApp.Hephaestus
]
```
### 2. Define Steps
Each step implements the `Hephaestus.Steps.Step` behaviour:
```elixir
defmodule MyApp.Steps.ValidateOrder do
@behaviour Hephaestus.Steps.Step
@impl true
def events, do: [:valid, :invalid]
@impl true
def execute(_instance, _config, context) do
if context.initial[:item_count] > 0 do
{:ok, :valid, %{validated_at: DateTime.utc_now()}}
else
{:ok, :invalid}
end
end
end
```
Steps return one of:
- `{:ok, event}` — synchronous completion
- `{:ok, event, context_updates}` — completion with data
- `{:async}` — pause and wait for external resume
- `{:error, reason}` — failure
### 3. Define a Workflow
Workflows declare a start step and transitions via pattern matching:
```elixir
defmodule MyApp.Workflows.OrderFlow do
use Hephaestus.Workflow
@impl true
def start, do: MyApp.Steps.ValidateOrder
@impl true
def transit(MyApp.Steps.ValidateOrder, :valid, _ctx), do: MyApp.Steps.ProcessPayment
def transit(MyApp.Steps.ValidateOrder, :invalid, _ctx), do: MyApp.Steps.RejectOrder
def transit(MyApp.Steps.ProcessPayment, :paid, _ctx), do: Hephaestus.Steps.Done
def transit(MyApp.Steps.RejectOrder, :rejected, _ctx), do: Hephaestus.Steps.Done
end
```
The compiler validates the entire DAG at build time — if a path doesn't reach `Hephaestus.Steps.Done`, or if events don't match step declarations, you'll get a compile error.
### 4. Run It
```elixir
{:ok, instance_id} = MyApp.Hephaestus.start_instance(
MyApp.Workflows.OrderFlow,
%{item_count: 3, user_id: 42}
)
```
### 5. Resume Async Workflows
For steps that return `{:async}`, resume them with an external event:
```elixir
:ok = MyApp.Hephaestus.resume(instance_id, :payment_confirmed)
```
## Workflow Patterns
### Branching
```elixir
def transit(StepA, :approved, _ctx), do: ApprovalPath
def transit(StepA, :rejected, _ctx), do: RejectionPath
```
### Parallel Execution (Fan-out / Fan-in)
```elixir
# Fan-out: multiple steps run concurrently
def transit(Start, :done, _ctx), do: [BranchA, BranchB, BranchC]
# Fan-in: all branches must complete before Join activates
def transit(BranchA, :done, _ctx), do: Join
def transit(BranchB, :done, _ctx), do: Join
def transit(BranchC, :done, _ctx), do: Join
```
### Dynamic Routing
Use `@targets` to declare possible destinations for context-dependent transitions:
```elixir
@targets [FastTrack, StandardProcess]
def transit(Triage, :routed, ctx) do
if ctx.initial[:priority] == :high, do: FastTrack, else: StandardProcess
end
```
### Timers and External Events
```elixir
# Wait for a duration
def transit(StepA, :done, _ctx), do: {Hephaestus.Steps.Wait, %{duration: 30, unit: :second}}
def transit(Hephaestus.Steps.Wait, :timeout, _ctx), do: StepB
# Wait for an external event
def transit(StepA, :done, _ctx), do: Hephaestus.Steps.WaitForEvent
def transit(Hephaestus.Steps.WaitForEvent, :received, _ctx), do: StepB
```
## Architecture
```
┌─────────────────────────────────────────────┐
│ Core (pure) │
│ Workflow ─ Engine ─ Instance ─ Context │
└──────────────────┬──────────────────────────┘
│
┌──────────────────┴──────────────────────────┐
│ Runtime (OTP) │
│ Runner (Local/Custom) ─ Storage (ETS/Custom)│
└──────────────────┬──────────────────────────┘
│
┌──────────────────┴──────────────────────────┐
│ Steps │
│ Done ─ Wait ─ WaitForEvent ─ Debug ─ Custom│
└─────────────────────────────────────────────┘
```
- **Core** — pure functional layer: workflow definition, DAG validation, engine state machine, instance/context structs
- **Runtime** — OTP layer: GenServer-based runner, pluggable storage, supervision tree, crash recovery
- **Steps** — behaviour-based units of work: built-in primitives plus your custom steps
## Documentation
Generate docs with:
```bash
mix docs
```
Generate ASCII execution graphs in your workflow moduledocs:
```bash
mix hephaestus.gen.docs
```
## License
Copyright (c) 2025. All rights reserved.
---
<details>
<summary>Versao em Portugues</summary>
# Hephaestus
Um motor de workflows leve e validado em tempo de compilacao para Elixir. Defina workflows baseados em steps como DAGs usando pattern matching, execute-os com suporte nativo a ramificacao, paralelismo e operacoes assincronas — tudo sobre OTP.
## Funcionalidades
- **Validacao de DAG em tempo de compilacao** — detecta ciclos, steps inalcancaveis, terminais ausentes e eventos incompativeis antes da execucao
- **Engine puramente funcional** — transicoes de estado imutaveis, facil de testar e entender
- **Execucao paralela** — fan-out para multiplos steps, fan-in com sincronizacao automatica de predecessores
- **Nativo para async** — suporte de primeira classe para operacoes longas, timers e retomada por eventos externos
- **Adaptadores plugaveis** — troque implementacoes de storage (ETS, banco de dados, Redis) e runner (OTP local, distribuido)
- **Propagacao de contexto** — dados iniciais imutaveis mais resultados de steps com namespace fluindo pelo workflow
- **Historico de execucao** — trilha de auditoria integrada de cada conclusao de step
## Instalacao
Adicione `hephaestus` a sua lista de dependencias no `mix.exs`:
```elixir
def deps do
[
{:hephaestus, "~> 0.1.0"}
]
end
```
## Inicio Rapido
### 1. Configure o Hephaestus
```elixir
defmodule MyApp.Hephaestus do
use Hephaestus,
storage: Hephaestus.Runtime.Storage.ETS,
runner: Hephaestus.Runtime.Runner.Local
end
```
Adicione a sua arvore de supervisao:
```elixir
children = [
MyApp.Hephaestus
]
```
### 2. Defina Steps
Cada step implementa o behaviour `Hephaestus.Steps.Step`:
```elixir
defmodule MyApp.Steps.ValidateOrder do
@behaviour Hephaestus.Steps.Step
@impl true
def events, do: [:valid, :invalid]
@impl true
def execute(_instance, _config, context) do
if context.initial[:item_count] > 0 do
{:ok, :valid, %{validated_at: DateTime.utc_now()}}
else
{:ok, :invalid}
end
end
end
```
Steps retornam um dos seguintes:
- `{:ok, event}` — conclusao sincrona
- `{:ok, event, context_updates}` — conclusao com dados
- `{:async}` — pausa e aguarda retomada externa
- `{:error, reason}` — falha
### 3. Defina um Workflow
Workflows declaram um step inicial e transicoes via pattern matching:
```elixir
defmodule MyApp.Workflows.OrderFlow do
use Hephaestus.Workflow
@impl true
def start, do: MyApp.Steps.ValidateOrder
@impl true
def transit(MyApp.Steps.ValidateOrder, :valid, _ctx), do: MyApp.Steps.ProcessPayment
def transit(MyApp.Steps.ValidateOrder, :invalid, _ctx), do: MyApp.Steps.RejectOrder
def transit(MyApp.Steps.ProcessPayment, :paid, _ctx), do: Hephaestus.Steps.Done
def transit(MyApp.Steps.RejectOrder, :rejected, _ctx), do: Hephaestus.Steps.Done
end
```
O compilador valida o DAG inteiro em build time — se um caminho nao chega ao `Hephaestus.Steps.Done`, ou se os eventos nao correspondem as declaracoes dos steps, voce recebe um erro de compilacao.
### 4. Execute
```elixir
{:ok, instance_id} = MyApp.Hephaestus.start_instance(
MyApp.Workflows.OrderFlow,
%{item_count: 3, user_id: 42}
)
```
### 5. Retome Workflows Assincronos
Para steps que retornam `{:async}`, retome-os com um evento externo:
```elixir
:ok = MyApp.Hephaestus.resume(instance_id, :payment_confirmed)
```
## Padroes de Workflow
### Ramificacao
```elixir
def transit(StepA, :approved, _ctx), do: ApprovalPath
def transit(StepA, :rejected, _ctx), do: RejectionPath
```
### Execucao Paralela (Fan-out / Fan-in)
```elixir
# Fan-out: multiplos steps executam concorrentemente
def transit(Start, :done, _ctx), do: [BranchA, BranchB, BranchC]
# Fan-in: todos os branches devem completar antes do Join ativar
def transit(BranchA, :done, _ctx), do: Join
def transit(BranchB, :done, _ctx), do: Join
def transit(BranchC, :done, _ctx), do: Join
```
### Roteamento Dinamico
Use `@targets` para declarar destinos possiveis em transicoes dependentes de contexto:
```elixir
@targets [FastTrack, StandardProcess]
def transit(Triage, :routed, ctx) do
if ctx.initial[:priority] == :high, do: FastTrack, else: StandardProcess
end
```
### Timers e Eventos Externos
```elixir
# Aguardar por uma duracao
def transit(StepA, :done, _ctx), do: {Hephaestus.Steps.Wait, %{duration: 30, unit: :second}}
def transit(Hephaestus.Steps.Wait, :timeout, _ctx), do: StepB
# Aguardar por um evento externo
def transit(StepA, :done, _ctx), do: Hephaestus.Steps.WaitForEvent
def transit(Hephaestus.Steps.WaitForEvent, :received, _ctx), do: StepB
```
## Arquitetura
```
┌─────────────────────────────────────────────┐
│ Core (puro) │
│ Workflow ─ Engine ─ Instance ─ Context │
└──────────────────┬──────────────────────────┘
│
┌──────────────────┴──────────────────────────┐
│ Runtime (OTP) │
│ Runner (Local/Custom) ─ Storage (ETS/Custom)│
└──────────────────┬──────────────────────────┘
│
┌──────────────────┴──────────────────────────┐
│ Steps │
│ Done ─ Wait ─ WaitForEvent ─ Debug ─ Custom│
└─────────────────────────────────────────────┘
```
- **Core** — camada puramente funcional: definicao de workflow, validacao de DAG, maquina de estados do engine, structs de instance/context
- **Runtime** — camada OTP: runner baseado em GenServer, storage plugavel, arvore de supervisao, recuperacao de crash
- **Steps** — unidades de trabalho baseadas em behaviour: primitivos built-in mais seus steps customizados
## Documentacao
Gere a documentacao com:
```bash
mix docs
```
Gere grafos ASCII de execucao nos moduledocs dos seus workflows:
```bash
mix hephaestus.gen.docs
```
</details>
