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` for file search
18//! - `SecretProvider` for secret storage
19//! - Connection is optional; Mountain can function without Air (graceful
20//! degradation)
21//! - Service discovery and health checking via gRPC
22//!
23//! MODULE STRUCTURE:
24//! - `AirClient` - gRPC client wrapper with connection management
25//! - `AirServiceProvider` - high-level provider with automatic request ID
26//! generation
27//! - `AirServiceTypesStub` - stub types for when Air library is unavailable
28//! (legacy)
29//!
30//! CONNECTION PATTERNS:
31//! - Uses tonic gRPC client for transport
32//! - Connection establishment via `connect()` method
33//! - Health checking with timeout protection
34//! - Thread-safe operations via `Arc<AirClient>`
35//!
36//! ERROR HANDLING:
37//! - All gRPC errors translated to
38//! [`CommonError::IPCError`](CommonLibrary::Error::CommonError)
39//! - Connection failures logged and return error
40//! - Service unavailability handled gracefully (return error, caller decides
41//! fallback)
42//!
43//! PERFORMANCE:
44//! - gRPC channels are expensive; reuse via `Arc<AirClient>`
45//! - Non-blocking async operations via tokio
46//! - Request ID generation for tracing
47//!
48//! VS CODE REFERENCE:
49//! - `vs/platform/telemetry/common/telemetry.ts` - telemetry/analytics service
50//! pattern
51//! - `vs/platform/update/common/update.ts` - update service integration
52//! - `vs/workbench/services/search/common/search.ts` - search service
53//! architecture
54//!
55//! TODO:
56//! - Implement connection retry with exponential backoff
57//! - Add connection pooling for multiple concurrent requests
58//! - Implement request caching for frequently accessed data (auth tokens, etc.)
59//! - Add metrics collection for Air service calls (latency, success rate,
60//! errors)
61//! - Implement fallback strategies when Air unavailable (local search, etc.)
62//! - Support for multiple Air daemons (load balancing/failover)
63//! - Add request timeout configuration (configurable per operation type)
64//! - Implement request/response logging for debugging
65//! - Add telemetry for Air service health and usage
66//! - Implement bidirectional streaming for real-time updates
67//!
68//! MODULE CONTENTS:
69//! - Re-exports: `AirClient`, `AirServiceProvider`, response types, and helper
70//! functions
71
72// Module sub-modules
73pub mod AirClient;
74pub mod AirServiceProvider;
75
76// Stub types for Air integration when AirLibrary is not available (legacy)
77// Note: These are kept for backward compatibility but should not be used in new
78// code
79#[deprecated(note = "Use AirClient and AirServiceProvider instead")]
80pub mod AirServiceTypesStub;