# 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
```rust
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`:
```toml
[dependencies]
execution-engine = { path = "../v2-execution-engine-rust" }
```
### As Git Dependency
```toml
[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/](./docs/)**
### Quick Links
- **Getting Started**: [docs/IMPLEMENTATION-GUIDE.md](./docs/IMPLEMENTATION-GUIDE.md) - Step-by-step implementation
- **API Reference**: [docs/api.md](./docs/api.md) - All public methods
- **Architecture**: [docs/architecture.md](./docs/architecture.md) - System design
- **Configuration**: [docs/configuration.md](./docs/configuration.md) - Config options
- **Storage Strategy**: [docs/STORAGE-STRATEGY.md](./docs/STORAGE-STRATEGY.md) - Data flow and use cases
### For Developers
- **[CLAUDE.md](./CLAUDE.md)** - Development guide for Claude Code
- **[docs/IMPLEMENTATION-VS-DESIGN.md](./docs/IMPLEMENTATION-VS-DESIGN.md)** - Implementation status vs design
- **[docs/OUTPUT-STORAGE-EXPLAINED.md](./docs/OUTPUT-STORAGE-EXPLAINED.md)** - Output storage internals
### External Documentation
Full architecture docs from v2-architecture-docs repository:
- [Execution Engine Docs](https://github.com/escher/v2-architecture-docs/tree/main/docs/04-services/libraries/execution-engine)
---
## Development
### Build & Test
```bash
# 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
```bash
# Run standalone example
cargo run --example standalone
```
### Benchmarks
```bash
# Run all benchmarks
cargo bench
# Run specific benchmark
cargo bench execution_overhead
```
### Code Quality
```bash
# 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](./IMPLEMENTATION-GUIDE.md) for detailed phase breakdown.
---
## Usage in Tauri App
Once implemented, integrate with Tauri:
```rust
// 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](./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](./IMPLEMENTATION-GUIDE.md)
- Review [docs/architecture.md](./docs/architecture.md)
- See full documentation: https://github.com/escher/v2-architecture-docs