Mountain/Track/mod.rs
1//! # Track Module
2//!
3//! ## Responsibilities
4
5#![allow(unused_imports, unused_variables)]
6//! This module acts as the central request dispatcher for the Mountain
7//! application. It is the primary entry point for all incoming commands and RPC
8//! calls, whether they originate from the `Sky` frontend or a `Cocoon`
9//! sidecar.
10//!
11//! ### Core Functions:
12//! - **Request Routing**: Route all incoming requests from frontend and
13//! sidecars
14//! - **Effect Creation**: Transform string-based command/RPC names into
15//! strongly-typed ActionEffects
16//! - **Command Dispatching**: Execute effects through the ApplicationRunTime
17//! - **Error Handling**: Provide comprehensive error handling and recovery
18//! - **Type Safety**: Ensure type-safe message passing through Rust's type
19//! system
20//!
21//! ## Architectural Role
22//!
23//! The Track module serves as the **routing layer** in Mountain's architecture:
24//!
25//! ```text
26//! Sky (Frontend) ──► Track (Router) ──► ApplicationRunTime (Executor) ──► Services
27//! Cocoon (Sidecar) ──► Track (Router) ──► ApplicationRunTime (Executor) ──► Providers
28//! ```
29//!
30//! ### Design Principles:
31//! 1. **Declarative Effects**: Commands create declarative ActionEffects that
32//! describe "what" needs to happen, not "how"
33//! 2. **Type-Safe Dispatch**: String-based method names are mapped to
34//! strongly-typed effects
35//! 3. **Performance-Critical**: Direct provider calls are used for hot paths
36//! 4. **Comprehensive Logging**: All routing decisions are logged for
37//! observability
38//!
39//! ## Key Components
40//!
41//! - **FrontendCommand**: Frontend command dispatch via Tauri
42//! - **SideCarRequest**: Sidecar RPC request dispatch via gRPC
43//! - **UIRequest**: UI request-response result handler
44//! - **Webview**: Webview message forwarder
45//! - **Effect**: Effect creation and routing
46//!
47//! ## TODOs
48//! High Priority:
49//! - [x] Atomize DispatchLogic into submodules
50//! - [ ] Add metrics/telemetry for dispatch latency
51//! - [ ] Implement command caching for frequently used effects
52//! - [ ] Add circuit breaker pattern for failing provider calls
53//!
54//! Medium Priority:
55//! - [ ] Split CreateEffectForRequest into individual effect modules
56//! - [ ] Add request rate limiting per client
57//! - [ ] Implement command batching for related operations
58//! - [ ] Add warm-up phase for critical paths
59//!
60//! Low Priority:
61//! - [ ] Add request tracing across the entire pipeline
62//! - [ ] Implement request replay for debugging
63//! - [ ] Add command versioning for backwards compatibility
64
65// --- Sub-modules ---
66
67/// Frontend command dispatch handling.
68pub mod FrontendCommand;
69
70/// Sidecar RPC request dispatch handling.
71pub mod SideCarRequest;
72
73/// UI request-response result handling.
74pub mod UIRequest;
75
76/// Webview message forwarding.
77pub mod Webview;
78
79/// Effect creation and routing.
80pub mod Effect;
81
82// --- Re-exports for backward compatibility ---
83
84pub use FrontendCommand::DispatchFrontendCommand;
85pub use SideCarRequest::DispatchSideCarRequest;
86pub use UIRequest::ResolveUIRequest;
87pub use Webview::MountainWebviewPostMessageFromGuest;
88pub use Effect::{CreateEffectForRequest, MappedEffect};