Adding `phlow_engine` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add phlow-engine

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

phlow-engine = "0.4.2"

The phlow_engine library will be automatically available globally. Read the phlow_engine library documentation.

Back to the crate overview.

Readme

Phlow - A Dynamic Rule-Based Workflow Engine

Phlow is a flexible and extensible rule-based workflow engine written in Rust. It allows users to define and execute dynamic decision trees and conditional workflows using JSON-based configurations and embedded scripting via Rhai.

Features

Dynamic workflows with JSON-defined rules
Embedded scripting with Rhai for advanced expressions
Conditional branching with assert expressions
Step-based execution with context-aware evaluation
Extensible engine with pluggable functions

Example: Decision Tree for Club Membership Approval

This example demonstrates a decision tree to determine if a person can become a club member.

use phlow::phlow;
use phlow::Engine;
use valu3::json;
use phlow::context::Context;

fn main() {
    let decision_tree = json!({
      "steps": [
        {
          "assert": "{{ payload.age >= 18 }}",
          "then": {
            "steps": [
              {
                "assert": "{{ payload.income >= 5000.0 }}",
                "then": {
                  "return": "Approved"
                },
                "else": {
                  "return": "Rejected - Insufficient income"
                }
              }
            ]
          },
          "else": {
            "return": "Rejected - Underage"
          }
        }
      ]
    });

    let engine = Engine::new();
    let phlow = phlow::try_from_value(&engine, &decision_tree, None, None).unwrap();

    let mut context = Context::from_payload(json!({ "age": 20, "income": 6000.0 }));
    let result = phlow.execute_context(&mut context).unwrap();

    println!("Decision: {:?}", result);
}

Modules

phlow - Main structure containing pipelines and execution logic.
context - Manages execution state and variable storage.
pipeline - Defines sequential execution of processing steps.
step_worker - Handles conditional logic and step execution.
script - Integrates Rhai scripting for dynamic evaluation.
engine - Configures and extends the scripting engine.
condition - Evaluates assert expressions for branching.
collector - Logs execution steps and tracks workflow state.

Architecture Overview

The phlow engine processes a workflow pipeline composed of steps. Each step can:

Evaluate conditions (e.g., comparisons, regex matching)
Execute scripts for computations
Branch execution based on conditions
Store and reference previous step outputs

Execution Flow

The engine receives an input JSON workflow definition.
The phlow instance parses and validates the workflow.
The workflow executes step-by-step, evaluating conditions and executing actions.
The final result is returned to the caller.

Advanced Usage

Adding Custom Plugins

Users can extend phlow by adding custom functions to the execution engine:

use phlow::engine::{build_engine, Plugins, PluginFunction};
use valu3::value::Value;
use std::collections::HashMap;
use std::sync::Arc;

fn main() {
    let mut plugins = HashMap::new();

    let custom_function: PluginFunction = Arc::new(|value: Value| {
        Value::from(format!("Processed: {}", value.to_string()))
    });
    
    plugins.insert("custom_process".to_string(), custom_function);
    let engine = build_engine(Some(Plugins { plugins }));

    let result: Value = engine.eval("custom_process(\"Hello\")").unwrap();
    println!("Result: {:?}", result);
}

Handling Execution Errors

Errors during workflow execution are returned as Result<T, PhlowError>:

match phlow.execute_context(&mut context) {
    Ok(result) => println!("Execution succeeded: {:?}", result),
    Err(err) => eprintln!("Execution failed: {:?}", err),
}

License

This project is licensed under the MIT License.

Adding phlow_engine library as a dependency

Adding `phlow_engine` library as a dependency