Support augmenting bounds from the client

Signed-off-by: Sahas Subramanian <sahas.subramanian@proton.me>

Author: shsms

src/client/instruction.rs

@@ -3,13 +3,17 @@
 
 //! Instructions that can be sent to the client actor from client handles.
 
+use chrono::TimeDelta;
 use tokio::sync::{broadcast, oneshot};
 
 use crate::{
     Error,
-    proto::common::microgrid::electrical_components::{
-        ElectricalComponent, ElectricalComponentCategory, ElectricalComponentConnection,
-        ElectricalComponentTelemetry,
+    proto::common::{
+        metrics::{Bounds, Metric},
+        microgrid::electrical_components::{
+            ElectricalComponent, ElectricalComponentCategory, ElectricalComponentConnection,
+            ElectricalComponentTelemetry,
+        },
     },
 };
 
@@ -30,4 +34,11 @@ pub(super) enum Instruction {
         destination_electrical_component_ids: Vec<u64>,
         response_tx: oneshot::Sender<Result<Vec<ElectricalComponentConnection>, Error>>,
     },
+    AugmentElectricalComponentBounds {
+        electrical_component_id: u64,
+        target_metric: Metric,
+        bounds: Vec<Bounds>,
+        request_lifetime: Option<TimeDelta>,
+        response_tx: oneshot::Sender<Result<Option<chrono::DateTime<chrono::Utc>>, Error>>,
+    },
 }

src/client/microgrid_api_client.rs

@@ -7,6 +7,7 @@
 use tonic::transport::Channel;
 
 use crate::proto::microgrid::{
+    AugmentElectricalComponentBoundsRequest, AugmentElectricalComponentBoundsResponse,
     ListElectricalComponentConnectionsRequest, ListElectricalComponentConnectionsResponse,
     ListElectricalComponentsRequest, ListElectricalComponentsResponse,
     ReceiveElectricalComponentTelemetryStreamRequest,
@@ -44,6 +45,11 @@ pub trait MicrogridApiClient: Send + Sync + 'static {
         &mut self,
         request: impl tonic::IntoRequest<ReceiveElectricalComponentTelemetryStreamRequest> + Send,
     ) -> std::result::Result<tonic::Response<Self::TelemetryStream>, tonic::Status>;
+
+    async fn augment_electrical_component_bounds(
+        &mut self,
+        request: impl tonic::IntoRequest<AugmentElectricalComponentBoundsRequest> + Send,
+    ) -> std::result::Result<tonic::Response<AugmentElectricalComponentBoundsResponse>, tonic::Status>;
 }
 
 /// Implement the MicrogridApiClient trait for the generated gRPC client.
@@ -78,4 +84,12 @@ impl MicrogridApiClient for crate::proto::microgrid::microgrid_client::Microgrid
         self.receive_electrical_component_telemetry_stream(request)
             .await
     }
+
+    async fn augment_electrical_component_bounds(
+        &mut self,
+        request: impl tonic::IntoRequest<AugmentElectricalComponentBoundsRequest> + Send,
+    ) -> std::result::Result<tonic::Response<AugmentElectricalComponentBoundsResponse>, tonic::Status>
+    {
+        self.augment_electrical_component_bounds(request).await
+    }
 }

src/client/microgrid_client_actor.rs

@@ -11,9 +11,9 @@ use crate::{
         ReceiveElectricalComponentTelemetryStreamResponse,
     },
 };
-use std::collections::HashMap;
-
+use chrono::DateTime;
 use futures::{Stream, StreamExt};
+use std::collections::HashMap;
 use tokio::{
     select,
     sync::{broadcast, mpsc},
@@ -180,6 +180,39 @@ async fn handle_instruction<T: MicrogridApiClient>(
                 .send(connections)
                 .map_err(|_| Error::internal("failed to send response"))?;
         }
+        Some(Instruction::AugmentElectricalComponentBounds {
+            electrical_component_id,
+            target_metric,
+            bounds,
+            request_lifetime,
+            response_tx,
+        }) => {
+            let response = client
+                .augment_electrical_component_bounds(
+                    crate::proto::microgrid::AugmentElectricalComponentBoundsRequest {
+                        electrical_component_id,
+                        target_metric: target_metric as i32,
+                        bounds: bounds,
+                        request_lifetime: request_lifetime.map(|d| d.as_seconds_f64() as u64),
+                    },
+                )
+                .await
+                .map_err(|e| {
+                    Error::api_server_error(format!(
+                        "augment_electrical_component_bounds failed: {e}"
+                    ))
+                })
+                .map(|r| {
+                    r.into_inner()
+                        .valid_until_time
+                        .map(|t| DateTime::from_timestamp(t.seconds, t.nanos as u32))
+                        .flatten()
+                });
+
+            response_tx
+                .send(response)
+                .map_err(|_| Error::internal("failed to send response"))?;
+        }
         None => {}
     }
 

src/client/microgrid_client_handle.rs

@@ -6,13 +6,16 @@
 //! Instructions received by this handle are sent to the microgrid client actor,
 //! which owns the connection to the microgrid API service.
 
+use chrono::TimeDelta;
 use tokio::sync::{broadcast, mpsc, oneshot};
 use tonic::transport::Channel;
 
 use crate::{
-    Error,
+    Bounds, Error,
     client::MicrogridApiClient,
+    metric::Metric,
     proto::{
+        common::metrics::Bounds as PbBounds,
         common::microgrid::electrical_components::{
             ElectricalComponent, ElectricalComponentCategory, ElectricalComponentConnection,
             ElectricalComponentTelemetry,
@@ -155,6 +158,55 @@ impl MicrogridClientHandle {
             .await
             .map_err(|e| Error::internal(format!("failed to receive response: {e}")))?
     }
+
+    /// Augments the overall bounds for a given metric of a given electrical
+    /// component with the provided bounds.
+    /// Returns the UTC time at which the provided bounds will expire and its
+    /// effects will no longer be visible in the overall bounds for the
+    /// given metric.
+    ///
+    /// The request parameters allows users to select a duration until
+    /// which the bounds will stay in effect. If no duration is provided, then the
+    /// bounds will be removed after a default duration of 5 seconds.
+    ///
+    /// Inclusion bounds give the range that the system will try to keep the
+    /// metric within. If the metric goes outside of these bounds, the system will
+    /// try to bring it back within the bounds.
+    /// If the bounds for a metric are [Symbol’s value as variable is void: lower_1End.
+    /// ---- values here are considered out of range.
+    /// ==== values here are considered within range.
+    ///
+    /// Note that for power metrics, regardless of the bounds, 0W is always
+    /// allowed.
+    pub async fn augment_electrical_component_bounds<M, I>(
+        &mut self,
+        electrical_component_id: u64,
+        #[allow(unused_variables)] target_metric: M,
+        bounds: Vec<I>,
+        request_lifetime: Option<TimeDelta>,
+    ) -> Result<Option<chrono::DateTime<chrono::Utc>>, Error>
+    where
+        M: Metric,
+        Bounds<M::QuantityType>: Into<PbBounds>,
+        I: Into<Bounds<M::QuantityType>>,
+    {
+        let (response_tx, response_rx) = oneshot::channel();
+
+        self.instructions_tx
+            .send(Instruction::AugmentElectricalComponentBounds {
+                response_tx,
+                electrical_component_id,
+                target_metric: M::METRIC,
+                bounds: bounds.into_iter().map(|x| x.into().into()).collect(),
+                request_lifetime,
+            })
+            .await
+            .map_err(|_| Error::internal("failed to send instruction"))?;
+
+        response_rx
+            .await
+            .map_err(|e| Error::internal(format!("failed to receive response: {e}")))?
+    }
 }
 
 #[cfg(test)]

src/error.rs

@@ -58,7 +58,8 @@ ErrorKind!(
     (ChronoError, chrono_error),
     (DroppedUnusedFormulas, dropped_unused_formulas),
     (FormulaEngineError, formula_engine_error),
-    (Internal, internal)
+    (Internal, internal),
+    (APIServerError, api_server_error),
 );
 
 /// An error that can occur during the creation or traversal of a