frequenz-floss / frequenz-api-dispatch Goto Github PK

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

  // Create a new dispatch
-  rpc CreateMicrogridDispatch(DispatchCreateRequest) returns (google.protobuf.Empty);
+  rpc CreateMicrogridDispatch(CreateMicrogridDispatchRequest) 
+         returns (CreateMicrogridDispatchResponse);
  
  // Update a dispatch
-  rpc UpdateMicrogridDispatch(DispatchUpdateRequest) returns (google.protobuf.Empty);
+  rpc UpdateMicrogridDispatch(UpdateMicrogridDispatchRequest) 
+         returns (UpdateMicrogridDispatchResponse);
  
  // Get a single dispatch
-  rpc GetMicrogridDispatch(DispatchGetRequest) returns (Dispatch);
+  rpc GetMicrogridDispatch(GetMicrogridDispatchRequest) 
+         returns (GetMicrogridDispatchResponse);

  // Delete a given dispatch
  rpc DeleteMicrogridDispatch(DispatchDeleteRequest) returns (google.protobuf.Empty);
}

// Message representing one dispatch.
-//
-// Timezone Note: Timestamps are in UTC. It is the responsibility of each microgrid to translate UTC
-// to its local timezone.
message Dispatch {
-  // The dispatch identifier
-  uint64 id = 1;

-  // The microgrid identifier
-  uint64 microgrid_id = 2;

  // The dispatch type.
  // Contains user-defined information about what "type" of dispatch this is.
  // Downstream applications that consume the dispatch API are responsible for
  // understanding and processing this field.
-  string type = 3;
+  string type = 1;

-  // The creation time in UTC
-  // This is set when a dispatch is created via the create request message
-  google.protobuf.Timestamp create_time = 4;

-  // The update time in UTC
-  // This is set when a dispatch is modified via the update request message
-  google.protobuf.Timestamp update_time = 5;

-  // The start time in UTC
+  // The dispatch start time in UTC. 
+  // For reoccuring dispatches this is when the first time execution occurs. When 
+  // creating a dispatch, ensure that the starting timestamp is set to the current 
+  // time or any future time. Timestamps earlier than the current time are not allowed.
-  google.protobuf.Timestamp start_time = 6;
+  google.protobuf.Timestamp start_time = 2;

  // Duration in seconds
-  uint32 duration = 7;
+  optional uint32 duration = 3;

-  // The component selector
+  // Dispatch microgrid component selector.
-  ComponentSelector selector = 8;
+  ComponentSelector selector = 4;

-  // The "active" status
-  // An active dispatch is eligible for processing, either immediately or at a scheduled
-  // time in the future, including recurring dispatches. If a dispatch is set to
-  // inactive, it won't be processed even if it matches all other conditions, allowing
-  // for temporary disabling of dispatches without deletion.
-  bool is_active = 9;
+  bool is_active = 5;

-  // The "dry run" status
-  // A dry run dispatch is executed for logging and monitoring purposes
-  // without affecting the microgrid components. This is useful, for example,
-  // in scenarios where a user may want to test dispatch behavior without
-  // actually affecting any component states.
-  // Notably, a dispatch can be both "dry run" and "active," allowing for
-  // the system to generate logs and observe behavior without making actual changes.
-  bool is_dry_run = 10;
+  bool is_dry_run = 6;

-  // The dispatch payload
-  google.protobuf.Struct payload = 11;
+  google.protobuf.Struct payload = 7;

-  // The recurrence rule
-  RecurrenceRule recurrence = 12;
+  -  RecurrenceRule recurrence = 8;
}

+// Represents a microgrid dispatch with full details, including its ID, state and associated
+// UTC timestamps.
+message DispatchDetail {
+  // Unique identifier of the microgrid dispatch.
+  uint64 dispatch_id = 1;
+
+  // The details of the dispatch.
+  Dispatch dispatch = 2;
+
+  // UTC Timestamp when the order was created.
+  google.protobuf.Timestamp create_time = 3;
+
+  // UTC Timestamp of the last update to the order.
+  google.protobuf.Timestamp modification_time = 4;
+}

// Message to create a new dispatch with the given attributes
-message DispatchCreateRequest {
+message CreateMicrogridDispatchRequest {
  // The microgrid identifier
  uint64 microgrid_id = 1;

-  // The type of dispatch
-  string type = 2;
+  // The details of the dispatch being created.
+  Dispatch dispatch = 2;

-  // The start time
-  // When creating a dispatch, ensure that the starting timestamp is set to
-  // the current time or any future time.
-  // Timestamps earlier than the current time are not allowed.
-  google.protobuf.Timestamp start_time = 3;

-  // Duration in seconds
-  uint32 duration = 4;

-  // The component selector
-  ComponentSelector selector = 5;

-  // The "active" status
-  bool is_active = 6;

-  // The "dry run" status
-  bool is_dry_run = 7;

-  // The dispatch payload
-  google.protobuf.Struct payload = 8;

-  // The recurrence rule
-  RecurrenceRule recurrence = 9;
}

+// Represents the server's response after a new dispatch has been successfully
+// created for a specific microgrid.
+//
+// This response provides essential details about the newly created dispatch, such
+// as the unique dispatch ID and the state of the dispatch.
+message CreateMicrogridDispatchResponse {
+  // ID of the microgrid the dispatch belongs to.
+  uint64 microgrid_id = 1;
+
+  // Details of the newly created microgrid dispatch.
+  DispatchDetail dispatch_detail = 2;
+}

// Message for listing dispatches for a given microgrid, and an optional filter
-message DispatchListRequest {
+message ListMicrogridDispatchRequest {
  // ...
}

-// A list of dispatches
+// Response from listing dispatches for a given microgrid.
-message DispatchList {
+message ListMicrogridDispatchResponse {
+  // ID of the microgrid the list of dispatches belongs to.
+  uint64 microgrid_id = 1;
+  
-  // The dispatches
+  // List of all dispatches with their details.
-   repeated Dispatch dispatches = 1;
+  repeated DispatchDetail dispatch_detail = 2;
}

-// Message to get a single dispatch by its ID
+// // Request to retrieve a single dispatch for a given microgrid.
-message DispatchGetRequest {
+message GetMicrogridDispatchRequest {
+  // ID of the microgrid the dispatch belongs to.
+  uint64 gridpool_id = 1;
  
  // The dispatch identifier
-  uint64 id = 1;
+  uint64 dispatch_id = 2;
}

+// Response from requesting order details for a specific order.
+message GetMicrogridDispatchResponse {
+  // ID of the microgrid the dispatch belongs to.
+  uint64 microgrid_id = 1;
+
+  // Details of the retrieved dispatch.
+  DispatchDetail dispatch_detail = 2;
+}

-// Message to update the dispatch with the given ID, with the given attributes
+// Request to update an existing dispatch for a given microgrid.
-message DispatchRequest {
+message UpdateMicrogridDispatchRequest {
  // Message containing the updated dispatch attributes
  message DispatchUpdate {
      // ...
  }
  
+  // ID of the microgrid the dispatch belongs to.
+  uint64 microgrid_id = 1;
+  
   // The dispatch identifier
-  uint64 id = 1;
+  uint64 dispatch_id = 2;

  // Field mask specifying which fields should be updated
-  google.protobuf.FieldMask update_mask = 2;
+  google.protobuf.FieldMask update_mask = 3;

  // The updated dispatch attributes
-  DispatchUpdate update = 3;
+  DispatchUpdate update = 4;
}

+// Response from updating an existing dispatch for a given microgrid.
+message UpdateMicrogridDispatchResponse {
+  // ID of the microgrid the dispatch belongs to.
+  uint64 microgrid_id = 1;
+
+  // Details of the updated dispatch.
+  DispatchDetail dispatch_detail = 2;
+}

message Dispatch {
  // ...

-  // Duration in seconds
+  // Duration of the dispatch in seconds. 
+  //
+  // !!! note
+  //     This field manages how long the dispatch lasts:
+  //     - `null` value indicates an infinite duration, meaning the dispatch continues indefinitely.
+  //     - A value of `0` indicates a one-time execution, which does not repeat or persist.
+  //     - Positive values specify the duration in seconds for which the dispatch should be active.
+  //
+  //     Example of how to set duration
+  //         duration_seconds: { value: 3600 } // Duration of 1 hour
+  //         duration_seconds: null // Infinite duration
+  //         duration_seconds: { value: 0 } // One-time execution
- //  uint32 duration = 7;
+ //  optional uint32 duration_seconds = 7;
}

-  // The end time in UTC
+  // Duration in seconds
- google.protobuf.Timestamp end_time = 7;
+ uint32 duration = 7;

  // On which month(s) of the year does the event occur
  repeated uint32 bymonths = 8;

+  // The end time in UTC
+  optional google.protobuf.Timestamp end_time = 9;

+// Enum DispatchState represents different stages of a dispatch's lifecycle, including its retrieval 
+// and execution states.
+enum DispatchState {
+  // UNKNOWN: Default status, unknown or not specified.
+  DISPATCH_STATE_UNKNOWN = 0;
+  
+  // PENDING_RETRIEVAL: Dispatch is created and waiting to be retrieved by the controller.
+  // This state is also set when an existing dispatch is updated, requiring re-retrieval to 
+  // incorporate changes.
+  DISPATCH_STATE_PENDING_RETRIEVAL = 1; 
+  
+  // RETRIEVED: Dispatch has been retrieved by the controller.
+  DISPATCH_STATE_RETRIEVED = 2;
+  
+  // STARTED: Dispatch has started execution.
+  DISPATCH_STATE_STARTED = 3;
+  
+  // COMPLETED: Dispatch has been executed and completed.
+  DISPATCH_STATE_COMPLETED = 4;
+
+  // WAITING: Dispatch is waiting to start its next scheduled execution.
+  DISPATCH_STATE_WAITING = 5;
+}

// Represents a microgrid dispatch with full details, including its ID, state and associated
// UTC timestamps.
message DispatchDetail {
  // Unique identifier of the microgrid dispatch.
  uint64 dispatch_id = 1;

  // The details of the dispatch.
  Dispatch dispatch = 2;

+  // Details of the dispatch current state.
+  DispatchState state = 3;

  // UTC Timestamp when the order was created.
-  google.protobuf.Timestamp create_time = 3;
+  google.protobuf.Timestamp create_time = 4;

  // UTC Timestamp of the last update to the order.
-  google.protobuf.Timestamp modification_time = 4;
+  google.protobuf.Timestamp modification_time = 5;
}

+ import "google/protobuf/field_mask.proto";

// Message to update the dispatch with the given ID, with the given attributes
message DispatchUpdateRequest {
  // The dispatch identifier
  uint64 id = 1;

-  // The start time
-  // When updating a dispatch, ensure that the starting timestamp is set to
-  // the current time or any future time.
-  // Timestamps earlier than the current time are not allowed.
-  google.protobuf.Timestamp start_time = 2;

-  // The end time
-  google.protobuf.Timestamp end_time = 3;

-  // The component selector
-  ComponentSelector selector = 4;

-  // The "active" status
-  optional bool is_active = 5;

-  // The "dry run" status
-  optional bool is_dry_run = 6;

-  // The dispatch payload
-  google.protobuf.Struct payload = 7;

-  // The recurrence rule
-  RecurrenceRule recurrence = 8;

+  // Field mask specifying which fields should be updated
+  google.protobuf.FieldMask update_mask = 2;

+  // The fields that can be updated
+  DispatchUpdatableFields updatable_fields = 3;
}

+ // Fields that can be updated for a dispatch
+ message DispatchUpdatableFields {
+   // The start time
+   // When updating a dispatch, ensure that the starting timestamp is set to
+   // the current time or any future time.
+   // Timestamps earlier than the current time are not allowed.
+   google.protobuf.Timestamp start_time = 1;

+   // The end time
+   google.protobuf.Timestamp end_time = 2;

+   // The component selector
+   ComponentSelector selector = 3;

+   // The "active" status
+   optional bool is_active = 4;

+   // The "dry run" status
+   optional bool is_dry_run = 5;

+   // The dispatch payload
+   google.protobuf.Struct payload = 6;

+   // The recurrence rule
+   RecurrenceRule recurrence = 7;
+ }

+ // Enum for the type of dispatch based on its recurrence.
+ enum RecurrenceType {
+   // UNSPECIFIED: Recurrence type is not specified.
+   RECURRENCE_TYPE_UNSPECIFIED = 0;
  
+   // NON_RECURRING: Dispatches that do not recur.
+   RECURRENCE_TYPE_NON_RECURRING = 1;
  
+   // RECURRING: Dispatches that recur.
+   RECURRENCE_TYPE_RECURRING = 2;               
+ }

// Filter parameter for specifying multiple time intervals
message TimeIntervalFilter {
-  // Filter by start_time >= this timestamp
+  // Filter by time >= this timestamp.
-  google.protobuf.Timestamp start_from = 1;
+  google.protobuf.Timestamp from = 1;

-  // Filter by start_time < this timestamp
+  // Filter by time < this timestamp.
-  google.protobuf.Timestamp start_to = 2;
+  google.protobuf.Timestamp to = 2;

-  // Filter by recurrence.end_criteria.until >= this timestamp
-  google.protobuf.Timestamp end_from = 3;

-  // Filter by recurrence.end_criteria.until < this timestamp
-  google.protobuf.Timestamp end_to = 4;
}

// Parameters for filtering the dispatch list
message DispatchFilter {
-  // Filter by component ID or category
+  // Optional 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
+  // Optional filter by active status.
  // If this field is not set, dispatches of any active status will be included.
-  optional bool is_active = 3;
+  optional bool is_active = 2;

-  // Filter by dry run status
+  // 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 = 4;
+  optional bool is_dry_run = 3;

+  // Optional filter by reoccurring and none-reoccurring dispatches.
+ // If not specified both types will be returned.
+  optional RecurrenceType recurrence_type = 4;

+  // Optional filter by start time.
+  // If no interval is provided, all dispatches will be returned.
+  TimeIntervalFilter start_time_interval = 5;

+  // Optional filter by end time
+  // Filter dispatches based on their explicit or estimated end time.
+  TimeIntervalFilter end_time_interval = 6;

+  // Optional filter by update time
+  TimeIntervalFilter update_time_interval = 7;
}

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

+  // Streaming RPC for receiving dispatch updates for a given microgrid
+  rpc StreamMicrogridDispatches(StreamMicrogridDispatchesRequest) returns (stream StreamMicrogridDispatchesResponse);

  // Create a new dispatch
  rpc CreateMicrogridDispatch(DispatchCreateRequest) returns (google.protobuf.Empty);

  // Update a dispatch
  rpc UpdateMicrogridDispatch(DispatchUpdateRequest) returns (google.protobuf.Empty);

  // Get a single dispatch
  rpc GetMicrogridDispatch(DispatchGetRequest) returns (Dispatch);

  // Delete a given dispatch
  rpc DeleteMicrogridDispatch(DispatchDeleteRequest) returns (google.protobuf.Empty);
}

+// 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 {
+   // Dispatch record returned. 
+   Dispatch dispatch = 1;       
+ }

// Message to update the dispatch with the given ID, with the given attributes
message DispatchUpdateRequest {
  // Message containing the updated dispatch attributes
  message DispatchUpdate {
       ...
    }

-    // The type of dispatch
-    optional string type = 1;

  // Create a new dispatch
-  rpc CreateMicrogridDispatch(DispatchCreateRequest) returns (google.protobuf.Empty);
+  rpc CreateMicrogridDispatch(DispatchCreateRequest) returns (Dispatch);

  // Update a dispatch
-  rpc UpdateMicrogridDispatch(DispatchUpdateRequest) returns (google.protobuf.Empty);
+  rpc UpdateMicrogridDispatch(DispatchUpdateRequest) returns (Dispatch);

// Message to update the dispatch with the given ID, with the given attributes
message DispatchUpdateRequest {
  // The dispatch identifier
  uint64 id = 1;

-  // The microgrid identifier
-  optional uint64 microgrid_id = 2;

  ...
}

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

  // Create a new dispatch
-  rpc CreateMicrogridDispatch(DispatchCreateRequest) returns (google.protobuf.Empty);
+  rpc CreateMicrogridDispatch(CreateMicrogridDispatchRequest) returns (CreateMicrogridDispatchResponse);

  // Update a dispatch
-  rpc UpdateMicrogridDispatch(DispatchUpdateRequest) returns (google.protobuf.Empty);
+  rpc UpdateMicrogridDispatch(UpdateMicrogridDispatchRequest) returns (UpdateMicrogridDispatchResponse);

  // Get a single dispatch
-  rpc GetMicrogridDispatch(DispatchGetRequest) returns (Dispatch);
+  rpc GetMicrogridDispatch(GetMicrogridDispatchRequest) returns (GetMicrogridDispatchResponse);

  // Delete a given dispatch
-  rpc DeleteMicrogridDispatch(DispatchDeleteRequest) returns (google.protobuf.Empty);
+  rpc DeleteMicrogridDispatch(DeleteMicrogridDispatchRequest) returns (DeleteMicrogridDispatchResponse);
}

message Dispatch {
  // ...
  
  
  // The dispatch payload.
+  // 
+  // Note!!! 
+  //     The payload field allows for flexible JSON data to be associated with this dispatch.
+  //     The payload must adhere to the following constraints:
+  //      - Maximum JSON nesting depth: 5 levels. 
+  //      - The data should not contain executable code or scripts.
+  //      - Ensure all data is properly sanitized and encoded.
+  //      - The total size of the payload should not exceed 50 KB.
  google.protobuf.Struct payload = 11;

message DispatchFilter {
-  // Filter by dispatch ID
-  repeated uint64 ids = 1;

  // Filter by microgrid ID
-  repeated uint64 microgrid_ids = 2;
+  uint64 microgrid_id = 1;

-  // Filter by dispatch type
-  repeated string types = 3;

  // Filter by component ID or category
-  repeated DispatchComponentSelector selectors = 4;
+  repeated DispatchComponentSelector selectors = 2;

  // Filter by time interval
+  // If start_from is not provided only current and future dispatches will be returned
-  TimeIntervalFilter time_interval = 5;
+  TimeIntervalFilter time_interval = 3;

  // Filter by "active" status
-  optional bool is_active = 6;

  // Filter by "dry run" status
-  optional bool is_dry_run = 7;
}

message Dispatch {
  // ..

+  // Recurrence is immutable once set. Attempting to change a dispatch from recurring to non-recurring,
+  // or from non-recurring to recurring, after creation is prohibited and will result in an error.
  RecurrenceRule recurrence = 12;  

// ...
}

-// Message to update the dispatch with the given ID, with the given attributes
+// DispatchUpdateRequest defines the request structure for updating an existing dispatch.
+//
+// This request is restricted to ensure that the recurrence nature of the dispatch cannot be altered
+// from recurring to non-recurring or vice versa after creation. If such a change is attempted, the API 
+// will return an error stating that modifying the recurrence nature of a dispatch is not allowed.
+//
+// This policy helps maintain the integrity and consistency of dispatch scheduling.
message DispatchUpdateRequest {
   // ...
}

// Service providing operations related to dispatching microgrid components.
service MicrogridDispatchService {
  // Returns a list of all dispatches
-  rpc ListMicrogridDispatches(DispatchListRequest) returns (DispatchList);
+  rpc ListMicrogridDispatches(DispatchListRequest) returns (DispatchListResponse);

// Message for listing dispatches for a given microgrid, and an optional filter
message DispatchListRequest {
  // The microgrid ID
  uint64 microgrid_id = 1;

  // Additional filter parameters
  DispatchFilter filter = 2;
  
+ // maximum number of results to be returned
+ int32 page_size = 3;

+ // identifies a specific page of the list results
+ string page_token = 4;
}

// A list of dispatches
- message DispatchList {
+ message DispatchListResponse {
  // The dispatches
  repeated Dispatch dispatches = 1;

+ // The pagination token to retrieve the next page of results. 
+ // If the value is "", it means no further results for the request. Pass the value of response's 
+ // next_page_token in the subsequent ListMicrogridDispatches method call in page_token field.
+ string next_page_token = 2;
}

// Filter parameter for specifying multiple time intervals
message TimeIntervalFilter {
- // Filter by start_time >= this timestamp
+  // Filter by start_time >= this timestamp in UTC
  google.protobuf.Timestamp start_from = 1;

- // Filter by start_time < this timestamp
+ // Filter by start_time < this timestamp in UTC
  google.protobuf.Timestamp start_to = 2;

- // Filter by recurrence.end_time >= this timestamp
+ // Filter by recurrence.end_time >= this timestamp in UTC
  google.protobuf.Timestamp end_from = 3;

- // Filter by recurrence.end_time < this timestamp
+ // Filter by recurrence.end_time < this timestamp in UTC
  google.protobuf.Timestamp end_to = 4;
}

// ... no changes

message RecurrenceRule {
  // ... no changes

  // When this dispatch should end.
  // A dispatch can either recur a fixed number of times, or until a given timestamp.
-  // If this field is not set, the dispatch will recur indefinitely.bool
+  // If this field is not set, the dispatch will recur indefinitely.
  EndCriteria end_criteria = 3;

  // ... no changes
}

// Message to create a new dispatch with the given attributes
message DispatchCreateRequest {
  // ... no changes

- // The start time
+ // The start time in UTC
  // When creating a dispatch, ensure that the starting timestamp is set to
  // the current time or any future time.
  // Timestamps earlier than the current time are not allowed.
  google.protobuf.Timestamp start_time = 3;

  // ... no changes
}

// Message to update the dispatch with the given ID, with the given attributes
message DispatchUpdateRequest {
    // ... no changes
   
-   // The start time
+   // The start time in UTC
    // When updating a dispatch, ensure that the starting timestamp is set to
    // the current time or any future time.
    // Timestamps earlier than the current time are not allowed.
    google.protobuf.Timestamp start_time = 2;
    
    // ... no changes
}

// Service providing operations related to dispatching microgrid components.
- service DispatchService {
+ service MicrogridDispatchService {
  // Returns a list of all dispatches
-   rpc ListDispatches(DispatchListRequest) returns (DispatchList);
+   rpc ListMicrogridDispatches(DispatchListRequest) returns (DispatchList);

  // Create a new dispatch
-   rpc CreateDispatch(DispatchCreateRequest) returns (google.protobuf.Empty);
+   rpc CreateMicrogridDispatch(DispatchCreateRequest) returns (google.protobuf.Empty);

  // Update a dispatch
-   rpc UpdateDispatch(DispatchUpdateRequest) returns (google.protobuf.Empty);
+   rpc UpdateMicrogridDispatch(DispatchUpdateRequest) returns (google.protobuf.Empty);

  // Get a single dispatch
-   rpc GetDispatch(DispatchGetRequest) returns (Dispatch);
+   rpc GetMicrogridDispatch(DispatchGetRequest) returns (Dispatch);

  // Delete a given dispatch
-   rpc DeleteDispatch(DispatchDeleteRequest) returns (google.protobuf.Empty);
+  rpc DeleteMicrogridDispatch(DispatchDeleteRequest) returns (google.protobuf.Empty);
}

-// Dispatch gRPC API definition.
-//
-// Copyright:
-// Copyright 2022 Frequenz Energy-as-a-Service GmbH
-//
-// License:
-// All rights reserved.
-
-// protolint:disable MAX_LINE_LENGTH
+// Copyright 2023 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.

...

- package frequenz.api.dispatch;
+ package frequenz.dispatch.v1;

+// Service providing operations related to dispatching microgrid components.
service DispatchService {
...

// Dispatch gRPC API definition.
...
// Message to update the dispatch with the given ID, with the given attributes
message DispatchUpdateRequest {
  ...
}

+ // Message to get a dispatch by its ID
+ message DispatchGetRequest {
+   // The dispatch identifier
+   uint64 id = 1;
+ }
+ 
+ // Message to delete a dispatch by its ID
+ message DispatchDeleteRequest {
+   // The dispatch identifier
+   uint64 id = 1;
+ }

service DispatchService {
  ...

  // Update a dispatch
  rpc UpdateDispatch(DispatchUpdateRequest) returns (google.protobuf.Empty) {
    ...
  }

+ // Get a dispatch
+ rpc GetDispatch(DispatchGetRequest) returns (Dispatch) {}
+ 
+ // Delete a dispatch
+ rpc DeleteDispatch(DispatchDeleteRequest) returns (google.protobuf.Empty) {}
}
...

+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;  
}

// Message for listing dispatches for a given microgrid, and an optional filter
message DispatchListRequest {
  // The microgrid ID
  uint64 microgrid_id = 1;

  // Additional filter parameters
  DispatchFilter filter = 2;
}

// Parameters for filtering the dispatch list
message DispatchFilter {
-  // Filter by component ID or category
+ // Optional filter by component ID or category
  repeated ComponentSelector selectors = 1;

-  // Filter by dispatch start time interval
-  // If no interval is provided, all dispatches starting from the
-  // current timestamp will be included.
+  // Optional filter by time interval
+  // Dispatches will be filtered based on the start_time of the dispatch request. 
+  // If no interval is provided, all dispatches starting from the current timestamp will be included.
-  TimeIntervalFilter time_interval = 2;
+  TimeIntervalFilter start_time_interval = 2;

-  // Filter by active status
+  // Optional 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
+  // 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 = 4;

+  // Optional filter by update time.
+  // Include only dispatches updated after this UTC timestamp.
+  google.protobuf.Timestamp modified_since = 5;
}