Mountain/Vine/mod.rs
1//! # Vine gRPC Module
2//!
3//! This module encapsulates all logic related to the gRPC-based
4//! Inter-Process Communication (IPC) system, codenamed "Vine".
5//!
6//! ## Architecture Overview
7//!
8//! Vine implements a bidirectional gRPC communication protocol between:
9//! - **Mountain**: The main VS Code extension host process
10//! - **Cocoon**: The sidecar process handling web-based operations
11//!
12//! The system uses two complementary gRPC services:
13//!
14//! ### MountainService (Cocoon → Mountain)
15//! - **ProcessCocoonRequest**: Request-response pattern for Cocoon to query
16//! Mountain
17//! - **SendCocoonNotification**: Fire-and-forget notifications from Cocoon to
18//! Mountain
19//! - **CancelOperation**: Request cancellation of long-running operations
20//!
21//! ### CocoonService (Mountain → Cocoon)
22//! - **ProcessMountainRequest**: Request-response pattern for Mountain to query
23//! Cocoon
24//! - **SendMountainNotification**: Fire-and-forget notifications from Mountain
25//! to Cocoon
26//! - **CancelOperation**: Request cancellation of long-running operations
27//!
28//! ## Communication Protocol
29//!
30//! All RPC messages use Protocol Buffers for serialization:
31//! - **GenericRequest**: Contains request ID, method name, and JSON parameters
32//! - **GenericResponse**: Contains request ID, JSON result, or optional error
33//! - **GenericNotification**: Fire-and-forget message with method name and JSON
34//! parameters
35//! - **RpcError**: JSON-RPC compliant error structure with code, message, and
36//! optional data
37//!
38//! ## Data Flow
39//!
40//! ```text
41//! Cocoon (Sidecar) Mountain (Extension Host)
42//! │ │
43//! ├──────────────────────────►│ ProcessCocoonRequest
44//! │ Extension/Query │ (returns GenericResponse)
45//! │ │
46//! ├──────────────────────────►│ SendCocoonNotification
47//! │ Status Updates │ (returns Empty)
48//! │ │
49//! │◄───────────────────────────┤ ProcessMountainRequest
50//! │ Webview Operations │ (returns GenericResponse)
51//! │ │
52//! │◄───────────────────────────┤ SendMountainNotification
53//! │ Configuration Changes │ (returns Empty)
54//! │ │
55//! ◄═════════════════════════════╡ CancelOperation
56//! Cancels either process
57//! ```
58//!
59//! ## Key Features
60//!
61//! - **Thread-Safe Client**: Connection pool with Arc<Mutex<>> for concurrent
62//! access
63//! - **Request Timeout**: Configurable timeout per RPC call
64//! - **Error Handling**: Comprehensive error types with gRPC status conversion
65//! - **Graceful Degradation**: System continues when Cocoon is unavailable
66//! - **Health Checks**: Connection validation before RPC calls
67//! - **Retry Logic**: Automatic reconnection attempts for transient failures
68//!
69//! ## Message Validation
70//!
71//! - Maximum message size: 4MB (default tonic limit)
72//! - JSON serialization validation on all parameters
73//! - Request ID tracking for operation correlation
74//! - Method whitelisting for security
75//!
76//! ## Modules
77//!
78//! - [`Client`]: gRPC client for connecting to Cocoon services
79//! - [`Error`]: Comprehensive error types for Vine operations
80//! - [`Generated`]: Auto-generated protobuf code from Vine.proto
81//! - [`Server`]: gRPC server implementations for Mountain services
82
83// --- Sub-modules ---
84pub mod Client;
85
86pub mod Error;
87
88pub mod Generated;
89
90pub mod Server;