Add rules for recurring dispatches (#57)

Fixes #9

Some examples:

Every 6 months:
```
message RecurrenceRule {
  Frequency freq = FREQUENCY_MONTHLY;
  uint32 interval = 6;
}
```

Weekends only:
```
message RecurrenceRule {
  Frequency freq = FREQUENCY_WEEKLY;
  repeated Weekday byweekdays = [WEEKDAY_SATURDAY, WEEKDAY_SUNDAY];
}
```

Every day at midnight:
```
message RecurrenceRule {
  Frequency freq = FREQUENCY_DAILY;
  repeated uint32 byhours = [0];
}
```

Nightly, assuming "night" means from 8 PM to 6 AM:
```
message RecurrenceRule {
  Frequency freq = FREQUENCY_DAILY;
  repeated uint32 byhours = [20, 21, 22, 23, 0, 1, 2, 3, 4, 5];
}
```

Author: stefan-brus-frequenz

RELEASE_NOTES.md

@@ -2,7 +2,7 @@
 
 ## Summary
 
-<!-- Here goes a general summary of what this release is about -->
+This release is mainly about creating a ruleset for recurring dispatches.
 
 ## Upgrading
 
@@ -11,6 +11,39 @@
 ## New Features
 
 - Package-based versioning has been introduced.
+- Rules for recurring dispatches have been added.
+  Examples:
+    Every 6 months:
+    ```
+    message RecurrenceRule {
+      Frequency freq = FREQUENCY_MONTHLY;
+      uint32 interval = 6;
+    }
+    ```
+
+    Weekends only:
+    ```
+    message RecurrenceRule {
+      Frequency freq = FREQUENCY_WEEKLY;
+      repeated Weekday byweekdays = [WEEKDAY_SATURDAY, WEEKDAY_SUNDAY];
+    }
+    ```
+
+    Every day at midnight:
+    ```
+    message RecurrenceRule {
+      Frequency freq = FREQUENCY_DAILY;
+      repeated uint32 byhours = [0];
+    }
+    ```
+
+    Nightly, assuming "night" means from 8 PM to 6 AM:
+    ```
+    message RecurrenceRule {
+      Frequency freq = FREQUENCY_DAILY;
+      repeated uint32 byhours = [20, 21, 22, 23, 0, 1, 2, 3, 4, 5];
+    }
+    ```
 
 ## Bug Fixes
 

proto/frequenz/dispatch/v1/dispatch.proto

@@ -78,6 +78,9 @@ message Dispatch {
 
   // The dispatch payload
   google.protobuf.Struct payload = 11;
+
+  // The recurrence rule
+  RecurrenceRule recurrence = 12;
 }
 
 // Filter parameter for specifying multiple time intervals
@@ -113,6 +116,98 @@ message DispatchComponentIDs {
   repeated uint64 component_ids = 1;
 }
 
+// Ruleset governing when and how a dispatch should re-occur
+//
+// This definition tries to adhere closely to the iCalendar specification (RFC 5545),
+// particularly for recurrence rules. For advanced use-cases or further clarifications,
+// refer to RFC 5545.
+//
+// Examples:
+//
+// Every 6 months:
+// ```
+// message RecurrenceRule {
+//   Frequency freq = FREQUENCY_MONTHLY;
+//   uint32 interval = 6;
+// }
+// ```
+//
+// Weekends only:
+// ```
+// message RecurrenceRule {
+//   Frequency freq = FREQUENCY_WEEKLY;
+//   repeated Weekday byweekdays = [WEEKDAY_SATURDAY, WEEKDAY_SUNDAY];
+// }
+// ```
+//
+// Every day at midnight:
+// ```
+// message RecurrenceRule {
+//   Frequency freq = FREQUENCY_DAILY;
+//   repeated uint32 byhours = [0];
+// }
+// ```
+//
+// Nightly, assuming "night" means from 8 PM to 6 AM:
+// ```
+// message RecurrenceRule {
+//   Frequency freq = FREQUENCY_DAILY;
+//   repeated uint32 byhours = [20, 21, 22, 23, 0, 1, 2, 3, 4, 5];
+// }
+// ```
+message RecurrenceRule {
+  // Enum representing the day of the week
+  enum Weekday {
+    WEEKDAY_UNSPECIFIED = 0;
+    WEEKDAY_MONDAY = 1;
+    WEEKDAY_TUESDAY = 2;
+    WEEKDAY_WEDNESDAY = 3;
+    WEEKDAY_THURSDAY = 4;
+    WEEKDAY_FRIDAY = 5;
+    WEEKDAY_SATURDAY = 6;
+    WEEKDAY_SUNDAY = 7;
+  }
+
+  // Enum representing the frequency of the recurrence
+  enum Frequency {
+    FREQUENCY_UNSPECIFIED = 0;
+    FREQUENCY_MINUTELY = 1;
+    FREQUENCY_HOURLY = 2;
+    FREQUENCY_DAILY = 3;
+    FREQUENCY_WEEKLY = 4;
+    FREQUENCY_MONTHLY = 5;
+  }
+
+  // The frequency specifier of this recurring dispatch
+  Frequency freq = 1;
+
+  // How often this dispatch should recur, based on the frequency
+  // Example:
+  // - Every 2 hours:
+  //   freq = FREQUENCY_HOURLY
+  //   interval = 2
+  uint32 interval = 2;
+
+  // (Optional) limit the number of occurences
+  // If this field is not set, the dispatch will recur indefinitely
+  optional uint32 count = 3;
+
+  // On which minute(s) of the hour does the event occur
+  repeated uint32 byminutes = 4;
+
+  // On which hour(s) of the day does the event occur
+  repeated uint32 byhours = 5;
+
+  // On which day(s) of the week does the event occur
+  repeated Weekday byweekdays = 6;
+
+  // On which day(s) of the month does the event occur
+  repeated uint32 bymonthdays = 7;
+
+  // On which month(s) of the year does the event occur
+  repeated uint32 bymonths = 8;
+}
+
 // Message for listing dispatches for a given microgrid, and an optional filter
 message DispatchListRequest {
   // The microgrid ID
@@ -167,6 +262,9 @@ message DispatchCreateRequest {
 
   // The dispatch payload
   google.protobuf.Struct payload = 8;
+
+  // The recurrence rule
+  RecurrenceRule recurrence = 9;
 }
 
 // Message to update the dispatch with the given ID, with the given attributes
@@ -194,6 +292,9 @@ message DispatchUpdateRequest {
 
   // The dispatch payload
   google.protobuf.Struct payload = 7;
+
+  // The recurrence rule
+  RecurrenceRule recurrence = 8;
 }
 
 // Message to get a single dispatch by its ID