Mountain/Environment/IPCProvider.rs
1//! # IPCProvider (Environment)
2//!
3//! RESPONSIBILITIES:
4//! - Implements [`IPCProvider`](CommonLibrary::IPC::IPCProvider) for
5//! [`MountainEnvironment`]
6//! - Serves as the IPC bridge between Mountain and extension sidecar processes
7//! (Cocoon)
8//! - Delegates all communications to the Vine gRPC client for transport
9//! - Provides both request/response and notification patterns
10//!
11//! ARCHITECTURAL ROLE:
12//! - Thin wrapper layer over `Vine::Client`
13//! - All IPC operations are async and use JSON-RPC 2.0 protocol
14//! - Sidecar routing via `SideCarIdentifier` to target specific extension hosts
15//! - Error translation from Vine errors to
16//! [`CommonError::IPCError`](CommonLibrary::Error::CommonError)
17//!
18//! COMMUNICATION PATTERNS:
19//! - **Request/Response** `SendRequestToSideCar`:
20//! - Synchronous RPC with timeout protection
21//! - Returns `Result<Value, CommonError>`
22//! - Used for config resolution, URI lookup, content retrieval
23//! - **Notification** `SendNotificationToSideCar`:
24//! - Fire-and-forget pattern
25//! - Returns `Result<(), CommonError>` (indicating send success only)
26//! - Used for document changes, diagnostics, UI events
27//!
28//! PERFORMANCE:
29//! - Vine client manages connection pooling and reuse
30//! - Timeouts enforced on requests to prevent blocking (caller-specified)
31//! - TODO: Add request queuing, batching, and priority handling
32//!
33//! VS CODE REFERENCE:
34//! - `vs/workbench/services/extensions/common/extensionHostProtocol.ts` -
35//! main-ext host IPC
36//! - `vs/base/parts/ipc/common/ipc.net.ts` - IPC transport layer
37//! - `vs/workbench/services/extensions/common/rpcProtocol.ts` - JSON-RPC
38//! protocol
39//!
40//! TODO:
41//! - Add message queuing for offline scenarios (caching when sidecar is down)
42//! - Implement bidirectional request handling (sidecar → main process)
43//! - Add request/response streaming support for large data transfers
44//! - Implement request cancellation with token support
45//! - Add request metrics and telemetry (latency, success rate, etc.)
46//! - Implement priority queue for urgent messages
47//! - Add support for batch IPC operations
48//! - Consider adding request deduplication
49//! - Implement proper connection health checking
50//! - Add support for IPC over Unix domain sockets for local sidecars
51//!
52//! MODULE CONTENTS:
53//! - [`IPCProvider`](CommonLibrary::IPC::IPCProvider) implementation:
54//! - `SendNotificationToSideCar` - fire-and-forget
55//! - `SendRequestToSideCar` - synchronous RPC
56//! - Delegate: `Vine::Client` handles all transport concerns
57
58use CommonLibrary::{Error::CommonError::CommonError, IPC::IPCProvider::IPCProvider};
59use async_trait::async_trait;
60use serde_json::Value;
61
62use super::MountainEnvironment::MountainEnvironment;
63use crate::Vine::Client;
64
65#[async_trait]
66impl IPCProvider for MountainEnvironment {
67 /// Sends a fire-and-forget notification to a specified sidecar.
68 async fn SendNotificationToSideCar(
69 &self,
70
71 SideCarIdentifier:String,
72
73 Method:String,
74
75 Parameters:Value,
76 ) -> Result<(), CommonError> {
77 Client::SendNotification(SideCarIdentifier, Method, Parameters)
78 .await
79 .map_err(|Error| CommonError::IPCError { Description:Error.to_string() })
80 }
81
82 /// Sends a request to a specified sidecar and awaits a response.
83 async fn SendRequestToSideCar(
84 &self,
85
86 SideCarIdentifier:String,
87
88 Method:String,
89
90 Parameters:Value,
91
92 TimeoutMilliseconds:u64,
93 ) -> Result<Value, CommonError> {
94 Client::SendRequest(&SideCarIdentifier, Method, Parameters, TimeoutMilliseconds)
95 .await
96 .map_err(|Error| CommonError::IPCError { Description:Error.to_string() })
97 }
98}