Expand description
§flow-runner
A small decision engine. You write rules in a .flow file; the host passes
in data and gets back a decision. The engine never does I/O, never reads the
clock, and never performs actions: it decides, and the host acts.
use flow_runner::{Decision, Flow, Input, Limits, Value};
let flow = Flow::compile(r#"
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 }
}
"#).unwrap();
let data = Value::obj([
("evaluatedAt", Value::Int(1_774_166_400)),
("deliveredAt", Value::Int(1_772_870_400)),
]);
let decision = flow.run(Input::start("evaluate", data), &Limits::default()).unwrap();
let Decision::Value { value, .. } = decision else { panic!() };
assert_eq!(value, Value::obj([("eligible", Value::Bool(true))]));Expressions inside a flow are temple-dsl.
§How the pieces fit
Flow::compileparses and checks the text and produces aFlow. Problems areDiagnostics, each with a span into the source.Flow::runwalks the flow for oneInputand returns aDecision, with aTokento continue from later.Flow::to_bytesandFlow::from_bytesstore a flow.Documentedits a flow as text, for a visual builder.
§Features
json: conversions to and fromserde_json, and [Graph::to_json].cli: theflowcommand-line tool. Impliesjson.
Structs§
- Annotation
@name = valueon a flow, a param or a node, with its value evaluated.- Annotation
View - An annotation as written.
- AskInfo
- One
ask name(payload) -> node(args)in a node. - Branch
Taken - One branch a run took.
- Branch
View - One branch of a node: a
whenbranch, or the node’s single outcome. - Diagnostic
- One problem found in a
.flowfile. - Diagnostics
- The errors and warnings found in one source, in the order they were
found.
Flow::compilefails with these when any is an error. - Document
- A
.flowfile open for editing. The text is the source of truth; the graph is a view of it. - Edge
- A way from one node to another.
- Expression
Error - A temple evaluation error, flattened so
RunErrorcan compare equal. - Flow
- A compiled flow. Compile it once with
Flow::compile, store it withFlow::to_bytesand load it withFlow::from_bytes. It is immutable and can be shared between threads. - Graph
- Everything a builder needs to draw a flow. Expression texts are exactly
as written in the file; spans are byte offsets into
Document::text. - Input
- What the host asks a flow to do. Build one with
Input::startorInput::resume, then add to it. A mistake, such as a param on a resume, is reported byFlow::run, not dropped. - LetView
- A
letor helper declaration as written. - Limits
- Work limits for one run.
- Node
Info - What a builder or host can read about one node.
- Node
View - A
nodedeclaration as written. - Param
- A flow parameter: a constant the host may set when an instance starts.
- Param
View - A
paramdeclaration as written. - Span
- A byte range
start..endin a source string. - Token
- Where an instance is: its node and the arguments it came with, its params and counters, and what it waits for. Store it with the instance, and pass it back to resume.
- Token
Info - What a
Tokensays. - Trace
- Where a run went, for answering “why did this happen?”. Holds node names and branch positions only, never values.
Enums§
- Branch
Kind - What a branch did.
- Decision
- How a run ended.
- Declaration
- The declaration an annotation sits on.
- Edge
Kind - How an
Edgeis taken. - Edit
- A change a builder can make. Text fields hold flow syntax exactly as it
would be typed: a guard is a temple expression, an outcome is a jump, a
value, an ask or
ignore, and a body is everything afternode name =. A guard or outcome can’t hold a#comment, which would hide the rest of the line it lands on. - Edit
Error - Why an edit was refused. The document is unchanged.
- Input
Error - A mistake by the host: the run didn’t start, and nothing was evaluated.
- Load
Error - Why a stored flow couldn’t be loaded.
- Outcome
View - What a branch does, with each expression as written.
- Rebind
Error - Why
Flow::rebindrefused a token. - RunError
- Why a run failed.
- Severity
- How serious a
Diagnosticis. - Value
- A dynamic value: a render’s input and, unless deserialized into your own type, its output. Numbers are integers or exact decimals, never floats; objects keep insertion order.
Constants§
- BLOB_
VERSION - Layout of
Flow::to_bytesblobs. Bump it when the layout changes. A blob of another version is refused withLoadError::IncompatibleVersion: blobs are rebuilt from source, so no old layout is kept. - MAX_
SOURCE_ BYTES - Largest
.flowsource accepted, in bytes.