Mountain/Air/mod.rs
1//! # Air (Air Integration Module)
2//!
3//! RESPONSIBILITIES:
4//! - Provides gRPC client connectivity to the Air daemon service
5//! - Implements Air service methods for:
6//! - Update management and distribution
7//! - Authentication and credential management
8//! - File indexing and search operations
9//! - System monitoring and metrics collection
10//! - Handles connection management and error translation to `CommonError`
11//! - Wraps client in `Arc` for shared access across the application
12//!
13//! ARCHITECTURAL ROLE:
14//! - Integration point with the Air background service (daemon)
15//! - Used by multiple Mountain components:
16//! - `UpdateService` for self-updates
17//! - [`SearchProvider`](crate::Environment::SearchProvider) for file search
18//! - [`SecretProvider`](crate::Environment::SecretProvider) for secret
19//! storage
20//! - Connection is optional; Mountain can function without Air (graceful
21//! degradation)
22//! - Service discovery and health checking via gRPC
23//!
24//! MODULE STRUCTURE:
25//! - `AirClient` - gRPC client wrapper with connection management
26//! - `AirServiceProvider` - high-level provider with automatic request ID
27//! generation
28//! - `AirServiceTypesStub` - stub types for when Air library is unavailable
29//! (legacy)
30//!
31//! CONNECTION PATTERNS:
32//! - Uses tonic gRPC client for transport
33//! - Connection establishment via `connect()` method
34//! - Health checking with timeout protection
35//! - Thread-safe operations via `Arc<AirClient>`
36//!
37//! ERROR HANDLING:
38//! - All gRPC errors translated to
39//! [`CommonError::IPCError`](CommonLibrary::Error::CommonError)
40//! - Connection failures logged and return error
41//! - Service unavailability handled gracefully (return error, caller decides
42//! fallback)
43//!
44//! PERFORMANCE:
45//! - gRPC channels are expensive; reuse via `Arc<AirClient>`
46//! - Non-blocking async operations via tokio
47//! - Request ID generation for tracing
48//!
49//! VS CODE REFERENCE:
50//! - `vs/platform/telemetry/common/telemetry.ts` - telemetry/analytics service
51//! pattern
52//! - `vs/platform/update/common/update.ts` - update service integration
53//! - `vs/workbench/services/search/common/search.ts` - search service
54//! architecture
55//!
56//! TODO:
57//! - Implement connection retry with exponential backoff
58//! - Add connection pooling for multiple concurrent requests
59//! - Implement request caching for frequently accessed data (auth tokens, etc.)
60//! - Add metrics collection for Air service calls (latency, success rate,
61//! errors)
62//! - Implement fallback strategies when Air unavailable (local search, etc.)
63//! - Support for multiple Air daemons (load balancing/failover)
64//! - Add request timeout configuration (configurable per operation type)
65//! - Implement request/response logging for debugging
66//! - Add telemetry for Air service health and usage
67//! - Implement bidirectional streaming for real-time updates
68//!
69//! MODULE CONTENTS:
70//! - Re-exports: `AirClient`, `AirServiceProvider`, response types, and helper
71//! functions
72
73// Module sub-modules
74pub mod AirClient;
75pub mod AirServiceProvider;
76
77// Access AirClient struct as: crate::Air::AirClient::AirClientImpl
78// Re-exports using module prefix to avoid naming conflicts
79pub use AirClient::{
80 AirClient as Client,
81 AirMetrics,
82 AirStatus,
83 DEFAULT_AIR_SERVER_ADDRESS,
84 DownloadStream,
85 DownloadStreamChunk,
86 ExtendedFileInfo,
87 FileInfo,
88 FileResult,
89 IndexInfo,
90 ResourceUsage,
91 UpdateInfo,
92};
93
94// Re-export the original name for compatibility (using type alias inside the module)
95pub use AirServiceProvider::generate_request_id;
96
97// Note: AirServiceProvider struct is available via
98// crate::Air::AirServiceProvider::AirServiceProvider
99
100// Stub types for Air integration when AirLibrary is not available (legacy)
101// Note: These are kept for backward compatibility but should not be used in new
102// code
103#[deprecated(note = "Use AirClient and AirServiceProvider instead")]
104pub mod AirServiceTypesStub;