Interface improvements (#23)

This PR expands the public interface of the crate by introducing a
generic `Bounds` type and a new client API to augment metric bounds,
while also refining metric/component typing and adding convenience impls
for better ergonomics.

**Changes:**
- Add `Bounds<Q>` and a
`MicrogridClientHandle::augment_electrical_component_bounds()` API (plus
actor/instruction/proto plumbing).
- Improve component/metric typing (e.g., `ElectricalComponentCategory`
filters, move `metric` to crate root) and add proto extension/graph
trait impls.
- Add `Display` for `Sample` and extend quantity helpers (const
ctors/getters, min/max, etc.).

Author: shsms

RELEASE_NOTES.md

@@ -2,4 +2,16 @@
 
 ## Summary
 
-This is the first release of Frequenz Microgrid.
+This release makes incremental improvements to the client and the quantity types.
+
+## Upgrading
+
+- The `MicrogridClientHandle::list_electrical_components` method now expects `ElectricalComponentCategory` enum values instead of `i32`, to filter by component category.
+
+## New Features
+
+- The new `MicrogridClientHandle::augment_electrical_component_bounds` method can be used to augment the bounds for specific metrics of electrical components.
+
+- All methods on `Quantity` types are now `const`.
+
+- `Quantity` types have two new methods `min` and `max`, similar to the `min` and `max` methods on fundamental numerical types.

src/bounds.rs

@@ -0,0 +1,67 @@
+// License: MIT
+// Copyright © 2026 Frequenz Energy-as-a-Service GmbH
+
+//! A representation of Bounds for any metric.
+
+use crate::proto::common::metrics::Bounds as PbBounds;
+use crate::quantity::{Current, Power, Quantity, ReactivePower};
+
+/// A set of lower and upper bounds for any metric.
+pub struct Bounds<Q: Quantity> {
+    /// The lower bound.
+    /// If None, there is no lower bound.
+    lower: Option<Q>,
+    /// The upper bound.
+    /// If None, there is no upper bound.
+    upper: Option<Q>,
+}
+
+impl<Q: Quantity> Bounds<Q> {
+    /// Creates a new `Bounds` with the given lower and upper bounds.
+    pub fn new(lower: Option<Q>, upper: Option<Q>) -> Self {
+        Self { lower, upper }
+    }
+
+    /// Returns the lower bound.
+    pub fn lower(&self) -> Option<Q> {
+        self.lower
+    }
+
+    /// Returns the upper bound.
+    pub fn upper(&self) -> Option<Q> {
+        self.upper
+    }
+}
+
+impl<Q: Quantity> From<(Option<Q>, Option<Q>)> for Bounds<Q> {
+    fn from(bounds: (Option<Q>, Option<Q>)) -> Self {
+        Self::new(bounds.0, bounds.1)
+    }
+}
+
+impl From<Bounds<Power>> for PbBounds {
+    fn from(bounds: Bounds<Power>) -> Self {
+        PbBounds {
+            lower: bounds.lower.map(|q| q.as_watts()),
+            upper: bounds.upper.map(|q| q.as_watts()),
+        }
+    }
+}
+
+impl From<Bounds<Current>> for PbBounds {
+    fn from(bounds: Bounds<Current>) -> Self {
+        PbBounds {
+            lower: bounds.lower.map(|q| q.as_amperes()),
+            upper: bounds.upper.map(|q| q.as_amperes()),
+        }
+    }
+}
+
+impl From<Bounds<ReactivePower>> for PbBounds {
+    fn from(bounds: Bounds<ReactivePower>) -> Self {
+        PbBounds {
+            lower: bounds.lower.map(|q| q.as_volt_amperes_reactive()),
+            upper: bounds.upper.map(|q| q.as_volt_amperes_reactive()),
+        }
+    }
+}

src/client.rs

@@ -8,10 +8,15 @@ mod microgrid_client_actor;
 mod retry_tracker;
 
 mod microgrid_api_client;
-pub use microgrid_api_client::MicrogridApiClient;
+pub(crate) use microgrid_api_client::MicrogridApiClient;
 
 mod microgrid_client_handle;
 pub use microgrid_client_handle::MicrogridClientHandle;
 
+pub(crate) mod proto;
+pub use proto::common::microgrid::electrical_components::{
+    ElectricalComponent, ElectricalComponentCategory,
+};
+
 #[cfg(test)]
 pub(crate) mod test_utils;

src/client/instruction.rs

@@ -3,12 +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, ElectricalComponentConnection, ElectricalComponentTelemetry,
+    proto::common::{
+        metrics::{Bounds, Metric},
+        microgrid::electrical_components::{
+            ElectricalComponent, ElectricalComponentCategory, ElectricalComponentConnection,
+            ElectricalComponentTelemetry,
+        },
     },
 };
 
@@ -21,12 +26,19 @@ pub(super) enum Instruction {
     },
     ListElectricalComponents {
         electrical_component_ids: Vec<u64>,
-        electrical_component_categories: Vec<i32>,
+        electrical_component_categories: Vec<ElectricalComponentCategory>,
         response_tx: oneshot::Sender<Result<Vec<ElectricalComponent>, Error>>,
     },
     ListElectricalComponentConnections {
         source_electrical_component_ids: Vec<u64>,
         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},
@@ -149,7 +149,10 @@ async fn handle_instruction<T: MicrogridApiClient>(
             let components = client
                 .list_electrical_components(ListElectricalComponentsRequest {
                     electrical_component_ids,
-                    electrical_component_categories,
+                    electrical_component_categories: electrical_component_categories
+                        .into_iter()
+                        .map(|c| c as i32)
+                        .collect(),
                 })
                 .await
                 .map_err(|e| Error::connection_failure(format!("list_components failed: {e}")))
@@ -177,6 +180,53 @@ 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,
+                        request_lifetime: request_lifetime.and_then(|d| {
+                            let secs = d.num_seconds();
+                            u64::try_from(secs).ok()
+                        }),
+                    },
+                )
+                .await
+                .map_err(|e| {
+                    Error::api_server_error(format!(
+                        "augment_electrical_component_bounds failed: {e}"
+                    ))
+                })
+                .map(|r| {
+                    r.into_inner().valid_until_time.and_then(|t| {
+                        match DateTime::from_timestamp(t.seconds, t.nanos as u32) {
+                            dt @ Some(_) => dt,
+                            None => {
+                                tracing::error!(
+                                    concat!(
+                                        "Received invalid valid_until_time in ",
+                                        "AugmentElectricalComponentBoundsResponse: {:?}"
+                                    ),
+                                    t
+                                );
+                                None
+                            }
+                        }
+                    })
+                });
+
+            response_tx
+                .send(response)
+                .map_err(|_| Error::internal("failed to send response"))?;
+        }
         None => {}
     }