Skip to main content

Crate flow_runner

Crate flow_runner 

Source
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

§Features

  • json: conversions to and from serde_json, and [Graph::to_json].
  • cli: the flow command-line tool. Implies json.

Structs§

Annotation
@name = value on a flow, a param or a node, with its value evaluated.
AnnotationView
An annotation as written.
AskInfo
One ask name(payload) -> node(args) in a node.
BranchTaken
One branch a run took.
BranchView
One branch of a node: a when branch, or the node’s single outcome.
Diagnostic
One problem found in a .flow file.
Diagnostics
The errors and warnings found in one source, in the order they were found. Flow::compile fails with these when any is an error.
Document
A .flow file 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.
ExpressionError
A temple evaluation error, flattened so RunError can compare equal.
Flow
A compiled flow. Compile it once with Flow::compile, store it with Flow::to_bytes and load it with Flow::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::start or Input::resume, then add to it. A mistake, such as a param on a resume, is reported by Flow::run, not dropped.
LetView
A let or helper declaration as written.
Limits
Work limits for one run.
NodeInfo
What a builder or host can read about one node.
NodeView
A node declaration as written.
Param
A flow parameter: a constant the host may set when an instance starts.
ParamView
A param declaration as written.
Span
A byte range start..end in 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.
TokenInfo
What a Token says.
Trace
Where a run went, for answering “why did this happen?”. Holds node names and branch positions only, never values.

Enums§

BranchKind
What a branch did.
Decision
How a run ended.
Declaration
The declaration an annotation sits on.
EdgeKind
How an Edge is 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 after node name =. A guard or outcome can’t hold a # comment, which would hide the rest of the line it lands on.
EditError
Why an edit was refused. The document is unchanged.
InputError
A mistake by the host: the run didn’t start, and nothing was evaluated.
LoadError
Why a stored flow couldn’t be loaded.
OutcomeView
What a branch does, with each expression as written.
RebindError
Why Flow::rebind refused a token.
RunError
Why a run failed.
Severity
How serious a Diagnostic is.
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_bytes blobs. Bump it when the layout changes. A blob of another version is refused with LoadError::IncompatibleVersion: blobs are rebuilt from source, so no old layout is kept.
MAX_SOURCE_BYTES
Largest .flow source accepted, in bytes.