cano 0.12.0

High-performance orchestration engine for building resilient, self-healing systems in Rust. Uses Finite State Machines (FSM) for strict, type-safe transitions.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

//! # RouterTask — Conditional Branching in a Workflow
//!
//! Run with: `cargo run --example router_task`
//!
//! Demonstrates [`RouterTask`] as a side-effect-free branching unit. A router reads
//! a configuration value from [`Resources`] and decides which processing path to take
//! — without touching the store, without side effects, without consuming a checkpoint
//! sequence number.
//!
//! Workflow shape:
//!
//! ```text
//!   Classify ──(router)──► FastPath ──► Done
//!                     │
//!                     └──► SlowPath ──► Done
//! ```
//!
//! The example runs twice: once with a flag that routes to the fast path, and once with
//! a flag that routes to the slow path.

use cano::prelude::*;

// ---------------------------------------------------------------------------
// State enum
// ---------------------------------------------------------------------------

#[derive(Debug, Clone, PartialEq, Eq, Hash)]
enum Step {
    /// Router state: inspects config and branches.
    Classify,
    /// Taken when `Config::use_fast_path` is `true`.
    FastPath,
    /// Taken when `Config::use_fast_path` is `false`.
    SlowPath,
    /// Terminal exit state.
    Done,
}

// ---------------------------------------------------------------------------
// Shared configuration resource — carries the branching flag
// ---------------------------------------------------------------------------

/// Workflow configuration injected via [`Resources`].
struct Config {
    use_fast_path: bool,
}

// `Resource` lifecycle hooks default to no-ops; we just need the trait impl to
// store this in `Resources`.
#[resource]
impl Resource for Config {}

// ---------------------------------------------------------------------------
// Router task
// ---------------------------------------------------------------------------

/// Reads `Config` from resources and returns the appropriate next step.
///
/// This is the only task in the workflow with branching logic. It is
/// side-effect-free: it reads, never writes.
struct Classifier;

#[task::router(state = Step)]
impl Classifier {
    async fn route(&self, res: &Resources) -> Result<TaskResult<Step>, CanoError> {
        let config = res.get::<Config, _>("config")?;
        if config.use_fast_path {
            println!("classifier : fast path selected");
            Ok(TaskResult::Single(Step::FastPath))
        } else {
            println!("classifier : slow path selected");
            Ok(TaskResult::Single(Step::SlowPath))
        }
    }
}

// ---------------------------------------------------------------------------
// Downstream tasks
// ---------------------------------------------------------------------------

struct FastProcessor;

#[task(state = Step)]
impl FastProcessor {
    async fn run_bare(&self) -> Result<TaskResult<Step>, CanoError> {
        println!("fast path  : processing quickly...");
        Ok(TaskResult::Single(Step::Done))
    }
}

struct SlowProcessor;

#[task(state = Step)]
impl SlowProcessor {
    async fn run_bare(&self) -> Result<TaskResult<Step>, CanoError> {
        println!("slow path  : processing thoroughly...");
        Ok(TaskResult::Single(Step::Done))
    }
}

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

fn build_workflow(use_fast_path: bool) -> Workflow<Step> {
    let config = Config { use_fast_path };
    let resources = Resources::new().insert("config", config);

    Workflow::new(resources)
        // `register_router` stores the task as a Router state entry:
        // dispatched like a normal state but writes no CheckpointRow.
        .register_router(Step::Classify, Classifier)
        .register(Step::FastPath, FastProcessor)
        .register(Step::SlowPath, SlowProcessor)
        .add_exit_state(Step::Done)
}

// ---------------------------------------------------------------------------
// Entry point
// ---------------------------------------------------------------------------

#[tokio::main]
async fn main() -> CanoResult<()> {
    println!("=== fast-path run ===");
    let workflow = build_workflow(true);
    let result = workflow.orchestrate(Step::Classify).await?;
    assert_eq!(result, Step::Done);
    println!("completed at {result:?}\n");

    println!("=== slow-path run ===");
    let workflow = build_workflow(false);
    let result = workflow.orchestrate(Step::Classify).await?;
    assert_eq!(result, Step::Done);
    println!("completed at {result:?}");

    Ok(())
}