Module workflow

cano

Module workflow 

Source
Expand description

§Workflow API - Build Simple Workflows

This module provides the core Workflow type for building async workflow systems. It includes state machine-driven workflow execution with type-safe routing and supports both Tasks and Nodes for maximum flexibility.

§🎯 Core Concepts

§State Machine-Based Workflows

The Workflow API provides a state machine-driven approach to workflow orchestration:

  • Define your workflow states using custom enums
  • Register Tasks or Nodes for each state using the unified .register() method
  • Set up state transitions based on Task/Node outcomes
  • Configure exit states to terminate the workflow

§Tasks & Nodes - Your Custom Logic

Choose the right processing approach for your needs:

§Tasks

Simple, flexible interface with a single run() method:

  • Perfect for prototypes and simple operations
  • Maximum flexibility in implementation
  • Direct control over execution flow
§Nodes

Structured three-phase lifecycle for production workloads:

  1. Prep: Load data, validate inputs, setup resources
  2. Exec: Core processing logic (with automatic retry support)
  3. Post: Store results, cleanup, determine next action

Every Node automatically implements Task, so you can mix both in the same workflow.

§🚀 Advanced Features

§Type-Safe State Routing

Workflows use user-defined enums for state management and routing. Your Tasks and Nodes return enum values that determine the next state to execute, providing compile-time safety and clear workflow logic.

§Exit State Management

Register specific enum values as exit states to cleanly terminate workflows when certain conditions are met (success, error, completion, etc.).

§💡 Best Practices

§State Design

  • Use descriptive enum variants for workflow states
  • Group related states logically (e.g., validation, processing, cleanup)
  • Define clear exit states for different termination scenarios

§Error Handling

  • Use CanoError for rich error context
  • Define error states in your enum for graceful error handling
  • Configure retries at the node level for transient failures

§store Usage

  • Use store to pass data between nodes
  • Keep store keys consistent across your workflow
  • Consider using strongly-typed store wrappers for complex data

§🔄 Concurrent Workflows

The ConcurrentWorkflow type enables executing multiple workflow instances in parallel:

  • Flexible timeout strategies for different execution patterns
  • Enhanced monitoring with detailed status tracking
  • Configurable completion criteria for batch processing

§Timeout Strategies

  • WaitStrategy::WaitForever - Execute all workflows to completion
  • [WaitStrategy::WaitForQuota(n)] - Complete a specific number, then cancel the rest
  • [WaitStrategy::WaitDuration(duration)] - Execute within a time limit
  • WaitStrategy::WaitQuotaOrDuration - Complete quota OR wait for duration, whichever comes first

Structs§

ConcurrentWorkflow
Concurrent workflow orchestration for executing multiple workflow instances in parallel
ConcurrentWorkflowBuilder
Builder for creating ConcurrentWorkflow instances with a fluent API
ConcurrentWorkflowStatus
Status of a concurrent workflow execution
Workflow
State machine workflow orchestration
WorkflowBuilder
Builder for creating Workflow instances with a fluent API

Enums§

WaitStrategy
Wait strategy for concurrent workflow execution
WorkflowResult
Result of a single workflow execution in a concurrent batch

Traits§

CloneableTaskTrait
Trait for tasks that can be cloned for concurrent workflow execution
DynTaskTrait
Trait object-safe version of the Task trait for dynamic dispatch

Type Aliases§

CloneableTask
Type alias for cloneable task trait objects for concurrent workflows
DynTask
Type alias for trait objects that can store different task types