Cloudops Execution Engine

Repository: v2-execution-engine-rust Language: Rust Status: Implementation Phase

Production-ready async execution engine for system commands.

Features

• Async/Non-blocking: Built on Tokio, returns immediately
• Real-time Streaming: Line-by-line output streaming
• Concurrency Control: Semaphore-based limiting (default: 100 concurrent)
• Memory Management: Automatic cleanup system (configurable retention)
• Resource Limits: Timeout, output size, concurrency limits
• Event-Driven: Pluggable event handlers for real-time updates

Quick Start

use execution_engine::*;
use std::sync::Arc;

#[tokio::main]
async fn main() {
    // Create engine
    let config = ExecutionConfig::default();
    let engine = Arc::new(ExecutionEngine::new(config));

    // Start cleanup task
    engine.start_cleanup_task();

    // Execute command
    let request = ExecutionRequest {
        id: Uuid::new_v4(),
        command: Command::Shell {
            command: "echo 'Hello World'".to_string(),
            shell: "/bin/bash".to_string(),
        },
        timeout_ms: Some(5000),
        env: HashMap::new(),
        working_dir: None,
    };

    let execution_id = engine.execute(request).await.unwrap();

    // Get result (non-blocking)
    tokio::time::sleep(Duration::from_secs(1)).await;
    let result = engine.get_result(execution_id).await.unwrap();

    println!("Success: {}", result.success);
    println!("Output: {}", result.stdout);
}

Installation

As Local Path (Development)

In your Cargo.toml:

[dependencies]
execution-engine = { path = "../v2-execution-engine-rust" }

As Git Dependency

[dependencies]
execution-engine = { git = "https://github.com/escher-dbai/v2-execution-engine-rust", branch = "main" }

Project Structure

v2-execution-engine-rust/
├── src/
│   ├── lib.rs              # Public API exports
│   ├── engine.rs           # ExecutionEngine (main entry point)
│   ├── executor.rs         # Command execution logic
│   ├── config.rs           # ExecutionConfig
│   ├── types.rs            # Request/Result types
│   ├── events.rs           # Event system
│   ├── errors.rs           # Error types
│   ├── commands.rs         # Command builder
│   ├── cleanup.rs          # Memory cleanup system
│   └── tests/              # Unit tests
│
├── tests/                  # Integration tests
│   ├── integration_tests.rs
│   ├── concurrency_tests.rs
│   ├── cleanup_tests.rs
│   └── output_limiting_tests.rs
│
├── examples/               # Usage examples
│   └── standalone.rs
│
├── benches/                # Performance benchmarks
│   └── execution_benchmarks.rs
│
└── docs/                   # Reference documentation
    ├── architecture.md
    ├── api.md
    ├── types.md
    ├── configuration.md
    └── error-handling.md

Documentation

📚 Complete documentation available in docs/

Quick Links

• Getting Started: docs/IMPLEMENTATION-GUIDE.md - Step-by-step implementation
• API Reference: docs/api.md - All public methods
• Architecture: docs/architecture.md - System design
• Configuration: docs/configuration.md - Config options
• Storage Strategy: docs/STORAGE-STRATEGY.md - Data flow and use cases

For Developers

• CLAUDE.md - Development guide for Claude Code
• docs/IMPLEMENTATION-VS-DESIGN.md - Implementation status vs design
• docs/OUTPUT-STORAGE-EXPLAINED.md - Output storage internals

External Documentation

Full architecture docs from v2-architecture-docs repository:

• Execution Engine Docs

Development

Build & Test

# Build
cargo build

# Run tests
cargo test

# Run tests with output
cargo test -- --nocapture

# Run specific test
cargo test test_basic_execution

# Run integration tests only
cargo test --test integration_tests

Examples

# Run standalone example
cargo run --example standalone

Benchmarks

# Run all benchmarks
cargo bench

# Run specific benchmark
cargo bench execution_overhead

Code Quality

# Format code
cargo fmt

# Check formatting
cargo fmt --check

# Run linter
cargo clippy -- -D warnings

# Check for unused dependencies
cargo +nightly udeps

Implementation Status

• Phase 1: Project Setup & Core Types (1-2 hours)
• Phase 2: Command Executor (2-3 hours)
• Phase 3: ExecutionEngine Core (2-3 hours)
• Phase 4: Operational Features (3-4 hours)
• Phase 5: Testing & Documentation (2-3 hours)

See IMPLEMENTATION-GUIDE.md for detailed phase breakdown.

Usage in Tauri App

Once implemented, integrate with Tauri:

// src-tauri/src/main.rs

use execution_engine::{ExecutionEngine, ExecutionConfig};
use std::sync::Arc;

#[tokio::main]
async fn main() {
    // Create engine
    let config = ExecutionConfig::default();
    let engine = Arc::new(ExecutionEngine::new(config));

    // Start cleanup
    engine.start_cleanup_task();

    // Share with Tauri
    tauri::Builder::default()
        .manage(engine)
        .invoke_handler(tauri::generate_handler![
            execute_command,
            get_execution_status,
            get_execution_result,
        ])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

#[tauri::command]
async fn execute_command(
    request: ExecutionRequest,
    engine: State<'_, Arc<ExecutionEngine>>,
) -> Result<String, String> {
    let execution_id = engine.execute(request).await
        .map_err(|e| e.to_string())?;

    Ok(execution_id.to_string())
}

Performance Targets

• Execution overhead: <50ms per command
• Concurrent throughput: 100+ concurrent executions
• Memory usage: Bounded by config (default: ~100MB for 1000 executions)
• Cleanup performance: <1s for 1000 executions

License

Private and Confidential

This software is proprietary and confidential. Unauthorized copying, distribution, or use of this software, via any medium, is strictly prohibited.

Contributing

1. Read IMPLEMENTATION-GUIDE.md
2. Create feature branch
3. Implement with tests
4. Run cargo test and cargo clippy
5. Submit PR

Support

For questions or issues:

• Check IMPLEMENTATION-GUIDE.md
• Review docs/architecture.md
• See full documentation: https://github.com/escher/v2-architecture-docs