Update dispatch filter for recurrence and end time

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

Author: Marenz

RELEASE_NOTES.md

@@ -20,6 +20,7 @@ In this release, we have made some changes to the API to improve the user experi
 * Add YEARLY frequency to the recurrence definition.
 * Add parameters for pagination and sorting.
 * Documentation of valid values for `count` and `interval` fields was added.
+* Extended filter parameters for recurrence and end time.
 
 ## Bug Fixes
 

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

@@ -151,17 +151,68 @@ message DispatchDetail {
 
 // Filter parameter for specifying multiple time intervals
 message TimeIntervalFilter {
-  // Filter by start_time >= this timestamp
-  google.protobuf.Timestamp start_from = 1;
+  // Filter by time >= this timestamp.
+  google.protobuf.Timestamp from = 1;
 
-  // Filter by start_time < this timestamp
-  google.protobuf.Timestamp start_to = 2;
+  // Filter by time < this timestamp.
+  google.protobuf.Timestamp to = 2;
+}
+
+// Parameters for filtering the dispatch list
+message DispatchFilter {
+  message RecurrenceFilter {
+    // Filter by recurring status
+    // True: Only recurring dispatches will be returned.
+    // False: Only non-recurring dispatches will be returned.
+    // Unset: Both recurring and non-recurring dispatches will be returned,
+    //        recurring dispatches will be filtered based on the recurrence
+    //        filter, while non-recurring dispatches will be returned regardless.
+    // Examples:
+    // - To retrieve only recurring dispatches:
+    //   filter { recurrence_filter { is_recurring: true } }
+    // - To retrieve only non-recurring dispatches:
+    //   filter { recurrence_filter { is_recurring: false } }
+    // - To retrieve all dispatches:
+    //   filter { recurrence_filter {} }
+    // - To retrieve only recurring dispatches with a specific frequency:
+    //   filter { recurrence_filter { is_recurring: true, freq: [FREQUENCY_DAILY] } }
+    // - To retrieve only recurring dispatches with a specific frequency but
+    //   also include non-recurring dispatches:
+    //   filter { recurrence_filter { freq: [FREQUENCY_DAILY] } }
+
+    // - only_recurring = true: Only recurring dispatches will be returned.
+    optional bool is_recurring = 1;
+
+    // Filter by frequency
+    // If not specified, all frequencies will be returned.
+    repeated RecurrenceRule.Frequency freqs = 2;
+  }
+
+  // Optional filter by component ID or category.
+  repeated ComponentSelector selectors = 1;
+
+  // Optional filter by active status.
+  // If this field is not set, dispatches of any active status will be included.
+  optional bool is_active = 2;
+
+  // Optional filter by dry run status.
+  // If this field is not set, dispatches of any dry run status will be included.
+  optional bool is_dry_run = 3;
+
+  // Optional recurrence filter
+  // If not specified both types will be returned.
+  RecurrenceFilter recurrence_filter = 4;
 
-  // Filter by recurrence.end_criteria.until >= this timestamp
-  google.protobuf.Timestamp end_from = 3;
+  // Optional filter by start time.
+  // If no interval is provided, all dispatches will be returned.
+  TimeIntervalFilter start_time_interval = 5;
 
-  // Filter by recurrence.end_criteria.until < this timestamp
-  google.protobuf.Timestamp end_to = 4;
+  // Optional filter by end time
+  // Filter dispatches based on their explicit end time.
+  TimeIntervalFilter end_time_interval = 6;
+
+  // Optional filter by update time
+  TimeIntervalFilter update_time_interval = 7;
 }
 
 // Parameter for controlling which components a dispatch applies to
@@ -371,25 +422,6 @@ message ListMicrogridDispatchesRequest {
   frequenz.api.common.v1.pagination.PaginationParams pagination_params = 4;
 }
 
-// Parameters for filtering the dispatch list
-message DispatchFilter {
-  // Filter by component ID or category
-  repeated ComponentSelector selectors = 1;
-
-  // Filter by time interval
-  // If no interval is provided, all dispatches starting from the
-  // current timestamp will be included.
-  TimeIntervalFilter time_interval = 2;
-
-  // Filter by active status
-  // If this field is not set, dispatches of any active status will be included.
-  optional bool is_active = 3;
-
-  // Filter by dry run status
-  // If this field is not set, dispatches of any dry run status will be included.
-  optional bool is_dry_run = 4;
-}
-
 // A list of dispatches
 message ListMicrogridDispatchesResponse {
   // The dispatches