runtara_workflows/
lib.rs

1// Copyright (C) 2025 SyncMyOrders Sp. z o.o.
2// SPDX-License-Identifier: AGPL-3.0-or-later
3//! Runtara Workflows - Workflow Compilation to Native Binaries
4//!
5//! This crate compiles workflow definitions (DSL scenarios) into native Linux binaries.
6//! The compiled binaries are standalone executables that communicate with runtara-core
7//! via the SDK for durability, checkpointing, and signal handling.
8//!
9//! # Architecture
10//!
11//! ```text
12//! ┌─────────────────────────────────────────────────────────────────────────┐
13//! │                        Workflow Compilation Pipeline                     │
14//! └─────────────────────────────────────────────────────────────────────────┘
15//!
16//!     ┌─────────────┐      ┌─────────────┐      ┌─────────────┐
17//!     │    DSL      │      │    Rust     │      │   Native    │
18//!     │  Scenario   │─────▶│    AST      │─────▶│   Binary    │
19//!     │  (JSON)     │      │  (codegen)  │      │  (rustc)    │
20//!     └─────────────┘      └─────────────┘      └─────────────┘
21//!           │                                         │
22//!           ▼                                         ▼
23//!     ┌─────────────┐                          ┌─────────────┐
24//!     │ Dependency  │                          │ OCI Image   │
25//!     │  Analysis   │                          │ (optional)  │
26//!     └─────────────┘                          └─────────────┘
27//! ```
28//!
29//! # Compilation Pipeline
30//!
31//! 1. **Parse**: Load the DSL scenario from JSON
32//! 2. **Analyze Dependencies**: Identify child scenarios and agent dependencies
33//! 3. **Generate AST**: Convert the execution graph to Rust AST using `codegen`
34//! 4. **Write Source**: Write generated Rust code to temp directory
35//! 5. **Invoke rustc**: Compile with musl target for static linking
36//! 6. **Package**: Optionally create OCI image for containerized execution
37//!
38//! # Usage
39//!
40//! ```ignore
41//! use runtara_workflows::{compile_scenario, CompilationInput};
42//!
43//! // Load scenario from JSON
44//! let scenario: Scenario = serde_json::from_str(&json)?;
45//!
46//! // Compile to native binary
47//! let input = CompilationInput {
48//!     scenario: &scenario,
49//!     tenant_id: "tenant-1",
50//!     scenario_id: "scenario-1",
51//!     version: 1,
52//!     output_dir: PathBuf::from("./output"),
53//!     child_scenarios: vec![],
54//! };
55//!
56//! let result = compile_scenario(&input).await?;
57//! println!("Binary at: {:?}", result.binary_path);
58//! ```
59//!
60//! # Important Notes
61//!
62//! - This crate has **NO database dependencies**. Child workflows must be loaded
63//!   by the caller and passed to compilation functions.
64//! - Compilation requires `rustc` and `musl-tools` to be installed.
65//! - The generated binary is statically linked for maximum portability.
66//!
67//! # Modules
68//!
69//! - [`agents_library`]: Pre-compiled agents library management
70//! - [`codegen`]: AST code generation from execution graphs
71//! - [`compile`]: Compilation orchestration and rustc invocation
72//! - [`dependency_analysis`]: Dependency resolution for child scenarios
73//! - [`paths`]: File path utilities for scenarios and data
74
75#![deny(missing_docs)]
76
77/// Pre-compiled agents library management.
78pub mod agents_library;
79
80/// AST code generation from execution graphs.
81pub mod codegen;
82
83/// Compilation orchestration and rustc invocation.
84pub mod compile;
85
86/// Dependency analysis for child scenarios.
87pub mod dependency_analysis;
88
89/// File path utilities for scenarios and data.
90pub mod paths;
91
92/// Workflow validation for security and correctness.
93pub mod validation;
94
95// Re-export main types
96pub use agents_library::{NativeLibraryInfo, get_native_library, get_stdlib_name};
97pub use compile::{
98    ChildDependency, ChildScenarioInput, CompilationInput, NativeCompilationResult,
99    compile_scenario, translate_scenario, workflow_has_side_effects,
100};
101pub use dependency_analysis::{DependencyGraph, ScenarioReference};
102pub use paths::{get_data_dir, get_scenario_dir, get_scenario_json_path};
103pub use validation::{ValidationError, validate_workflow};
104
105// Re-export DSL types for convenience
106pub use runtara_dsl::{ExecutionGraph, Scenario};
runtara_workflows/lib.rs

runtara_workflows/
lib.rs
