Add RPC streaming methods

Signed-off-by: Mathias L. Baumann <[email protected]>

Author: Marenz

RELEASE_NOTES.md

@@ -17,6 +17,7 @@ In this release, we have made some changes to the API to improve the user experi
 * Create and Update request now returns the new dispatch object.
 * Documentation about authentication and encryption was added.
 * Enhanced `payload` documentation.
+* Add RPC streaming methods.
 * Add YEARLY frequency to the recurrence definition.
 * Add parameters for pagination and sorting.
 * Documentation of valid values for `count` and `interval` fields was added.

proto/frequenz/api/dispatch/v1/dispatch.proto

@@ -67,6 +67,9 @@ service MicrogridDispatchService {
   // Returns a list of all dispatches
   rpc ListMicrogridDispatches(ListMicrogridDispatchesRequest) returns (ListMicrogridDispatchesResponse);
 
+  // Streaming RPC for receiving dispatch updates for a given microgrid
+  rpc StreamMicrogridDispatches(StreamMicrogridDispatchesRequest) returns (stream StreamMicrogridDispatchesResponse);
+
   // Create a new dispatch
   rpc CreateMicrogridDispatch(CreateMicrogridDispatchRequest) returns (CreateMicrogridDispatchResponse);
 
@@ -80,6 +83,38 @@ service MicrogridDispatchService {
   rpc DeleteMicrogridDispatch(DeleteMicrogridDispatchRequest) returns (DeleteMicrogridDispatchResponse);
 }
 
+// Subscribe to a stream of microgrid dispatch requests.
+// This method provides real-time updates on newly or updated dispatch requests for edge-based
+// realtime decision making.
+message StreamMicrogridDispatchesRequest {
+  // ID of the microgrid to subscribe to
+  uint64 microgrid_id = 1;
+}
+
+// Response to a subscription request for a stream of microgrid dispatches.
+// Real-time information on dispatches affecting a certain microgrid are pushed through this response.
+message StreamMicrogridDispatchesResponse {
+  enum Event {
+    // Default, unspecified event
+    EVENT_UNSPECIFIED = 0;
+
+    // A new dispatch has been created
+    EVENT_CREATED = 1;
+
+    // An existing dispatch has been updated
+    EVENT_UPDATED = 2;
+
+    // An existing dispatch has been deleted
+    EVENT_DELETED = 3;
+  }
+
+  // Dispatch record returned.
+  DispatchDetail dispatch_detail = 1;
+
+  // Which event this response was triggered by
+  Event event = 2;
+}
+
 // Represents a dispatches data, including its type, start time, duration, component selector,
 //
 // Timezone Note: Timestamps are in UTC. It is the responsibility of each microgrid to translate UTC