Flow Runner
flow-runner runs business processes written as small graphs. You describe a process in a
.flow file (a return, an approval, a delivery quote) and your service asks it what should happen
next. The answer is plain data. flow-runner doesn't send the email or call the carrier; your code
does that. It never touches the network, the disk or the clock, which is what makes it safe to
run flows that your users write.
Expressions inside a flow are temple-dsl.
edition 2026
flow return-window
entry evaluate
param windowDays = 30
node evaluate =
let age = input.data.evaluatedAt - input.data.deliveredAt
when {
age > windowDays * 86400: { "eligible": false, "reason": "WindowExpired" }
else: { "eligible": true }
}
Compile a flow once, when it's saved, then run it as often as you like. A compiled Flow is
immutable, so every thread can share one.
use ;
let flow = compile?;
let decision = flow.run?;
if let Value = decision
Processes that wait
Most processes spend their time waiting for a manager, a parcel or a payment. A flow can wait too, and flow-runner keeps nothing in memory while it does. Every run hands back a token; you save it next to your own record, and when something happens you pass it back in with the event.
sequenceDiagram
participant Service as Your service
participant Engine as flow-runner
participant Store as Your database
Service->>Engine: start at requested
Engine-->>Service: status INITIATED, token
Service->>Store: save the token
Note over Service,Store: a day later, a manager approves
Service->>Engine: resume the token with event approve
Engine-->>Service: status INPROGRESS, wake in 7 days, token
Service->>Store: save the token and schedule a tick
Note over Service,Store: the parcel arrives
Service->>Engine: resume with event parcel.received
Engine-->>Service: ask warehouse.inspect, token
Service->>Service: call the warehouse
Service->>Engine: resume with the warehouse's answer
Engine-->>Service: refund 1200, token
Here is the part of that flow that waits for the parcel:
node awaitingParcel(approvedAt) = when {
input.event == 'parcel.received': inspecting(input.payload.lines)
input.event == 'tick': { "status": "INPROGRESS", "flag": "STALLED" }
input.arrived: { "status": "INPROGRESS" } wake approvedAt + 7 * 86400
else: ignore
}
node inspecting(lines) =
ask warehouse.inspect({ "returnId": input.data.returnId, "lines": lines }) -> inspected()
A branch ends in one of four ways. It jumps to another node, returns a value (and can ask to be
woken later with wake), asks your service for something with ask, or does nothing with
ignore. How you answer an ask is your business: an HTTP call, a database lookup, another flow.
The whole flow is in examples/flows/return-lifecycle.flow,
and examples/lifecycle.rs drives it the way a service would.
Why use it
Rules change more often than the code around them, and the people who own them often don't write
Rust. Keeping them in flows means they can change without a deploy, and a visual editor can open
a flow as a graph and edit it; Document applies each edit to the file's text and leaves the rest
of the file alone.
It's quick enough to call on every request: a decision usually takes a few microseconds (see BENCHMARKS.md). A flow can't loop forever or use more work than its step budget, and mistakes are compile errors that point at the line. The same flow and input give the same answer everywhere, WebAssembly included.
The flow command
Tests sit next to the flow they test:
# return-lifecycle.flow.test.yaml
tests:
- name: approve, receive, inspect, refund
answers:
warehouse.inspect:
steps:
- entry: requested
data:
expect:
- event: approve
expect:
Cargo features
json adds conversions between Value and serde_json and Graph::to_json. It's off by
default because it turns on serde_json's arbitrary_precision and preserve_order for your
whole build. cli builds the flow command.
Further reading
DESIGN.md covers the language, the checks the compiler makes, and what tokens, hashes and stored flows promise. ARCHITECTURE.md is a map of the code. examples/ has a program for each way to use the crate and four complete flows with their tests. CONTRIBUTING.md explains how changes get in and how releases go out; CHANGELOG.md lists what changed.
License
MIT