Skip to main content

DevelopmentNodeEnvironment_MicrosoftVSCodeDependency_22NodeVersion_Bundle_Clean_Debug_ElectronProfile_EsbuildCompiler_Mountain/Vine/
mod.rs

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