Mountain/Track/
mod.rs

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