Mountain/RunTime/mod.rs
1//! # RunTime Module
2//!
3//! ## RESPONSIBILITIES
4//!
5//! Effect execution engine for the Mountain application. This module provides
6//! the runtime environment for executing effects through the Echo scheduler.
7//!
8//! ### Core Functions:
9//! - **Effect Execution**: Execute effects through the Echo scheduler
10//! - **Task Management**: Submit tasks to the async runtime
11//! - **Environment Integration**: Provide access to MountainEnvironment
12//! - **Result Handling**: Collect and return effect results
13//! - **Lifecycle Management**: Orchestrate graceful shutdown of all services
14//! - **Error Recovery**: Comprehensive error handling and recovery mechanisms
15//!
16//! ## Architectural Role
17//!
18//! The RunTime module is the **execution engine** in Mountain's architecture:
19//!
20//! ```text
21//! Track (Router) ──► RunTime (Executor) ──► Eco:Scheduler ──► Providers
22//! Command ─────────────────────────────────────────────────────────┘
23//! ```
24//!
25//! ### Design Principles:
26//! 1. **Async-First**: All execution happens in an async context
27//! 2. **Effect-Based**: Effects describe "what" to do, runtime determines "how"
28//! 3. **Non-Blocking**: Uses Echo's work-stealing scheduler
29//! 4. **Type-Safe**: Effect execution is type-safe through generics
30//! 5. **Error Recovery**: Continues shutdown even when services fail
31//! 6. **Graceful Degradation**: Provides fallback strategies for service
32//! unavailability
33//!
34//! ## Key Components
35//!
36//! - **ApplicationRunTime**: Main runtime struct and orchestration
37//! - **Execute**: Effect execution logic (Run, RunWithTimeout, RunWithRetry)
38//! - **Shutdown**: Service shutdown and lifecycle management
39//!
40//! ## TODOs
41//! Medium Priority:
42//! - [ ] Add effect timeout handling
43//! - [ ] Implement effect execution metrics
44//! - [ ] Add effect cancellation support
45//! - [ ] Add effect tracing
46//! - [ ] Implement effect prioritization
47//!
48//! Low Priority:
49//! - [ ] Add effect execution limits (rate limiting)
50//! - [ ] Implement distributed effect execution across instances
51//! - [ ] Add effect result caching for idempotent operations
52//! - [ ] Implement effect pipeline with chaining and composition
53
54// --- Sub-modules ---
55
56/// Application runtime module containing the struct definition.
57/// The struct is accessible as
58/// `RunTime::ApplicationRunTime::ApplicationRunTime`.
59pub mod ApplicationRunTime;
60
61/// Effect execution logic.
62pub mod Execute;
63
64/// Service shutdown and lifecycle management.
65pub mod Shutdown;