Extend `DispatchListRequest` and `DispatchListResponse` to support ordering and pagination.

[thomas-nicolai-frequenz]

What's needed?

We need to extend the DispatchListRequest message to support ordering by "start time," "create time," or "last update time".

Proposed solution

+import "frequenz/api/common/v1/pagination/pagination_info.proto";
+import "frequenz/api/common/v1/pagination/pagination_params.proto";

service MicrogridDispatchService {
  // Returns a list of all dispatches
-  rpc ListMicrogridDispatches(DispatchListRequest) returns (DispatchList);
+  rpc ListMicrogridDispatches(DispatchListRequest) returns (DispatchListResponse);

  // ...
}  

+// Enum for the fields to by sorted by.
+enum SortField {
+  // UNSPECIFIED: Default, unspecified sort field.
+  SORT_FIELD_UNSPECIFIED = 0;  
+
+  // START_TIME: Sort by start time of the dispatch.
+  SORT_FIELD_START_TIME = 1;  
+
+  // CREATE_TIME: Sort by creation time of the dispatch.
+  SORT_FIELD_CREATE_TIME = 2; 
+
+  // MODIFICATION_TIME: Sort by last update time of the dispatch.
+  SORT_FIELD_LAST_MODIFICATION_TIME = 3; 
+
+  // END_TIME: Sort by end time of the dispatch.
+  SORT_FIELD_END_TIME = 4; 
+}

+// Enum for sort order.
+enum SortOrder {
+  // UNSPECIFIED: Default, unspecified sort order.
+  SORT_ORDER_UNSPECIFIED = 0;  
+
+  // ASCENDING: Results are returned in ascending order.
+  SORT_ORDER_ASCENDING = 1;
+
+  // DESCENDING: Results are returned in descending order.
+  SORT_ORDER_DESCENDING = 2;              
+}

+ // Message defining parameters for sorting list requests.
+ //
+ // Example Usage:
+ // To retrieve dispatches sorted by creation time in descending order:
+ // sort_options: { field: CREATE_TIME, order: DESCENDING }
+ //
+message SortOptions {
+  // Optional field by which to sort the results.
+  SortField sort_field = 1;
+
+  // Optional Order in which to sort the results.
+  SortOrder sort_order = 2;               
+}

-// Message for listing dispatches for a given microgrid, and an optional filter
+// Message for listing dispatches for a given microgrid.
+// 
+// Allows retrieval of dispatches for a specified microgrid with optional filtering and sorting.
+// Sorting can be specified by setting 'sort_field' and 'sort_order'. If no sorting is specified,
+// the results will be returned by their create time in a descending order.
message DispatchListRequest {
  // The microgrid ID.
  uint64 microgrid_id = 1;          

- // Additional filter parameters
+ // Optional filters to apply to the dispatch list.         
  DispatchFilter filter = 2;            
+       
+ // Sorting options for the results.
+ SortOptions sort_options = 3;

+ // Pagination parameters.
+ frequenz.api.common.v1.pagination.PaginationParams pagination_params = 4; 
}

-// A list of dispatches
+ // Response from listing dispatches for a given microgrid.
-message DispatchList {
+message DispatchListResponse {
-  // The dispatches
+  // List of all dispatches with their details.
  repeated Dispatch dispatches = 1;

+  // Metadata for pagination, including token for next page to retrieve.
+  frequenz.api.common.v1.pagination.PaginationInfo pagination_info = 2;  
}

Use cases

No response

Alternatives and workarounds

No response

Additional context

No response

[thomas-nicolai-frequenz]

Given the changes introduced by https://github.com/frequenz-floss/frequenz-api-dispatch/issues/166 the patch has to be modified:

+import "frequenz/api/common/v1/pagination/pagination_info.proto";
+import "frequenz/api/common/v1/pagination/pagination_params.proto";

+// Enum for the fields to by sorted by.
+enum SortField {
+  // UNSPECIFIED: Default, unspecified sort field.
+  SORT_FIELD_UNSPECIFIED = 0;  
+
+  // START_TIME: Sort by start time of the dispatch.
+  SORT_FIELD_START_TIME = 1;  
+
+  // CREATE_TIME: Sort by creation time of the dispatch.
+  SORT_FIELD_CREATE_TIME = 2; 
+
+  // UPDATE_TIME: Sort by last update time of the dispatch.
+  SORT_FIELD_LAST_UPDATE_TIME = 3; 
+}

+// Enum for sort order.
+enum SortOrder {
+  // UNSPECIFIED: Default, unspecified sort order.
+  SORT_ORDER_UNSPECIFIED = 0;  
+
+  // ASCENDING: Results are returned in ascending order.
+  SORT_ORDER_ASCENDING = 1;
+
+  // DESCENDING: Results are returned in descending order.
+  SORT_ORDER_DESCENDING = 2;              
+}

+ // Message defining parameters for sorting list requests.
+ //
+ // Example Usage:
+ // To retrieve dispatches sorted by creation time in descending order:
+ // sort_options: { field: CREATE_TIME, order: DESCENDING }
+ //
+message SortOptions {
+  // Optional field by which to sort the results.
+  SortField sort_field = 1;
+
+  // Optional Order in which to sort the results.
+  SortOrder sort_order = 2;               
+}

-// Message for listing dispatches for a given microgrid, and an optional filter
+// Message for listing dispatches for a given microgrid.
+// 
+// Allows retrieval of dispatches for a specified microgrid with optional filtering and sorting.
+// Sorting can be specified by setting 'sort_field' and 'sort_order'. If no sorting is specified,
+// the results will be returned by their create time in a descending order.
message ListMicrogridDispatchRequest {
  // The microgrid ID.
  uint64 microgrid_id = 1;          

- // Additional filter parameters
+ // Optional filters to apply to the dispatch list.         
  DispatchFilter filter = 2;            
+       
+ // Sorting options for the results.
+ SortOptions sort_options = 3;

+ // Pagination parameters.
+ frequenz.api.common.v1.pagination.PaginationParams pagination_params = 4; 
}

// Response from listing dispatches for a given microgrid.
message ListMicrogridDispatchResponse {
  // ID of the microgrid the list of dispatches belongs to.
  uint64 microgrid_id = 1;

  // List of all dispatches with their details.
  repeated DispatchDetail dispatch_detail = 2;

+  // Metadata for pagination, including token for next page to retrieve.
+  frequenz.api.common.v1.pagination.PaginationInfo pagination_info = 2;  
}