feat(ipc): Implement IPC effects for sidecar communication

This commit introduces three new ActionEffects to facilitate robust Inter-Process Communication (IPC) with sidecar processes:

* **ProxyCallToSideCar**: A high-level effect designed to route an entire RPC call (method and parameters) received by the host to another sidecar. It extracts the method and parameters from a `CallData` JSON object and forwards them using `SendRequestToSideCar`.
* **SendNotificationToSideCar**: An effect for sending fire-and-forget notifications to a sidecar. It takes a target sidecar ID, a method name, and parameters, and executes the send operation without awaiting a response.
* **SendRequestToSideCar**: A core effect for performing request-response RPC calls to a sidecar. It accepts a target sidecar ID, method name, parameters, and a timeout, then awaits and returns the JSON response from the sidecar.

These effects abstract the details of the underlying IPC mechanism (e.g., gRPC) by utilizing a shared `IPCProvider` capability, promoting modularity and testability within the application's architecture.

Author: NikolaRHristov

Source/IPC/ProxyCallToSideCar.rs

@@ -0,0 +1,65 @@
+//! # ProxyCallToSideCar Effect
+//!
+//! Defines the `ActionEffect` for proxying a generic RPC call to a sidecar
+//! process.
+
+use std::sync::Arc;
+
+use serde_json::Value;
+
+use super::IPCProvider::IPCProvider;
+use crate::{Effect::ActionEffect::ActionEffect, Error::CommonError::CommonError};
+
+/// Creates an effect that proxies an RPC call to a specified target sidecar.
+///
+/// This is a powerful utility for scenarios where the host application
+/// (`Mountain`) needs to act as a router, forwarding a request it received from
+/// one process to another without needing to understand the request's content.
+/// The entire call payload is encapsulated within the `CallData` object.
+///
+/// # Parameters
+///
+/// * `TargetSideCarIdentifier`: The unique ID of the sidecar to which the call
+///   should be proxied.
+/// * `CallData`: A JSON `Value` expected to be an object containing `{"Method":
+///   "...", "Parameters": ...}`.
+///
+/// # Returns
+///
+/// An `ActionEffect` that resolves with the JSON `Value` returned by the
+/// target sidecar.
+pub fn ProxyCallToSideCar(
+	TargetSideCarIdentifier:String,
+
+	CallData:Value,
+) -> ActionEffect<Arc<dyn IPCProvider>, CommonError, Value> {
+	ActionEffect::New(Arc::new(move |Provider:Arc<dyn IPCProvider>| {
+		let TargetIdentifierClone = TargetSideCarIdentifier.clone();
+
+		let CallDataClone = CallData.clone();
+
+		Box::pin(async move {
+			let MethodString = CallDataClone
+				.get("Method")
+				.and_then(Value::as_str)
+				.ok_or_else(|| {
+					CommonError::InvalidArgument {
+						ArgumentName:"CallData.Method".to_string(),
+
+						Reason:"Expected a 'Method' string field in CallData for proxying.".to_string(),
+					}
+				})?
+				.to_string();
+
+			let ParametersValue = CallDataClone.get("Parameters").cloned().unwrap_or(Value::Null);
+
+			// Using a default timeout here; a real implementation might make this
+			// configurable by extracting it from the CallData payload.
+			let DefaultTimeoutMilliseconds = 30000;
+
+			Provider
+				.SendRequestToSideCar(TargetIdentifierClone, MethodString, ParametersValue, DefaultTimeoutMilliseconds)
+				.await
+		})
+	}))
+}

Source/IPC/SendNotificationToSideCar.rs

@@ -0,0 +1,51 @@
+//! # SendNotificationToSideCar Effect
+//!
+//! Defines the `ActionEffect` for sending a fire-and-forget notification to a
+//! sidecar process.
+
+use std::sync::Arc;
+
+use serde_json::Value;
+
+use super::IPCProvider::IPCProvider;
+use crate::{Effect::ActionEffect::ActionEffect, Error::CommonError::CommonError};
+
+/// Creates an effect that, when executed, will send a fire-and-forget
+/// notification to a specified sidecar process.
+///
+/// It uses the `IPCProvider` capability from the environment to perform the
+/// actual IPC send operation. Unlike `SendRequestToSideCar`, this effect does
+/// not wait for or expect a response.
+///
+/// # Parameters
+///
+/// * `SideCarIdentifier`: The unique ID of the target sidecar process.
+/// * `Method`: The name of the notification method to be invoked on the
+///   sidecar.
+/// * `Parameters`: A `serde_json::Value` containing the parameters for the
+///   notification.
+///
+/// # Returns
+///
+/// An `ActionEffect` that resolves to `()` on success.
+pub fn SendNotificationToSideCar(
+	SideCarIdentifier:String,
+
+	Method:String,
+
+	Parameters:Value,
+) -> ActionEffect<Arc<dyn IPCProvider>, CommonError, ()> {
+	ActionEffect::New(Arc::new(move |Provider:Arc<dyn IPCProvider>| {
+		let SideCarIdentifierClone = SideCarIdentifier.clone();
+
+		let MethodClone = Method.clone();
+
+		let ParametersClone = Parameters.clone();
+
+		Box::pin(async move {
+			Provider
+				.SendNotificationToSideCar(SideCarIdentifierClone, MethodClone, ParametersClone)
+				.await
+		})
+	}))
+}

Source/IPC/SendRequestToSideCar.rs

@@ -0,0 +1,54 @@
+//! # SendRequestToSideCar Effect
+//!
+//! Defines the `ActionEffect` for sending a request-response RPC call to a
+//! sidecar process.
+
+use std::sync::Arc;
+
+use serde_json::Value;
+
+use super::IPCProvider::IPCProvider;
+use crate::{Effect::ActionEffect::ActionEffect, Error::CommonError::CommonError};
+
+/// Creates an effect that, when executed, will send a request to a specified
+/// sidecar process and await its response.
+///
+/// It uses the `IPCProvider` capability from the environment to perform the
+/// actual IPC request operation over the underlying transport (e.g., gRPC).
+///
+/// # Parameters
+///
+/// * `SideCarIdentifier`: The unique ID of the target sidecar process.
+/// * `Method`: The name of the RPC method to be invoked on the sidecar.
+/// * `Parameters`: A `serde_json::Value` containing the parameters for the
+///   request.
+/// * `TimeoutMilliseconds`: The maximum time to wait for a response before
+///   failing.
+///
+/// # Returns
+///
+/// An `ActionEffect` that resolves with the `serde_json::Value` response from
+/// the sidecar.
+pub fn SendRequestToSideCar(
+	SideCarIdentifier:String,
+
+	Method:String,
+
+	Parameters:Value,
+
+	TimeoutMilliseconds:u64,
+) -> ActionEffect<Arc<dyn IPCProvider>, CommonError, Value> {
+	ActionEffect::New(Arc::new(move |Provider:Arc<dyn IPCProvider>| {
+		let SideCarIdentifierClone = SideCarIdentifier.clone();
+
+		let MethodClone = Method.clone();
+
+		let ParametersClone = Parameters.clone();
+
+		Box::pin(async move {
+			Provider
+				.SendRequestToSideCar(SideCarIdentifierClone, MethodClone, ParametersClone, TimeoutMilliseconds)
+				.await
+		})
+	}))
+}