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