flow-runner 0.1.0

An embeddable, deterministic, sans-I/O decision engine — flows are graphs of nodes whose expressions are temple-dsl templates
Documentation

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 flow_runner::{Decision, Flow, Input, Limits};

let flow = Flow::compile(&src)?;
let decision = flow.run(Input::start("evaluate", data), &Limits::default())?;
if let Decision::Value { value, .. } = decision {
    // {"eligible": true}
}

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

cargo install --path . --features cli      # from a checkout, until it's on crates.io

flow check return.flow                     # errors and warnings
flow run return.flow --data '{"evaluatedAt": 1774166400}'
flow run return.flow --token <token> --event approve
flow test examples/flows                   # every *.flow.test.yaml below the directory
flow graph return.flow                     # the graph as JSON, for editors

Tests sit next to the flow they test:

# return-lifecycle.flow.test.yaml
tests:
  - name: approve, receive, inspect, refund
    answers:
      warehouse.inspect: { result: { passed: true, acceptedValue: 1200 } }
    steps:
      - entry: requested
        data: { evaluatedAt: 1774166400, returnId: R-1 }
        expect: { node: requested, value: { status: INITIATED } }
      - event: approve
        expect: { node: awaitingParcel, wakeAt: 1774771200 }

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