refactor(oncall): reorganize Shift API underneath Schedules

grafanaplane/oncall/main.libsonnet

@@ -8,5 +8,4 @@ local raw = import '../zz/main.libsonnet';
   escalationChain: import './escalationchain.libsonnet',
   integration: import './integration.libsonnet',
   schedule: import './schedule.libsonnet',
-  shift: import './shift.libsonnet',
 }

grafanaplane/oncall/schedule.libsonnet

@@ -6,36 +6,78 @@ local schedule = raw.oncall.v1alpha1.schedule;
 local forProvider = schedule.spec.parameters.forProvider;
 
 {
-  local base = self,
-
-  '#new':: d.func.new(
-    '`new` creates a Schedule. The `name` is a display-friendly string.',
-    [d.argument.new('name', d.T.string)]
-  ),
-  new(name)::
-    schedule.new(xtd.ascii.stringToRFC1123(name))
-    + schedule.spec.parameters.forProvider.withName(name),
-
-  '#withId':: d.func.new(
-    '`withId` sets the resource name for a Schedule',
-    [d.argument.new('id', d.T.string)]
-  ),
-  withId(id):: schedule.metadata.withName(id),
-
-  '#withShifts':: d.func.new(
-    |||
-      `withShifts` sets a Schedule to type `calendar` and configures shifts.
-      Shifts are only applicable to `calendar` type Schedules. `shifts` is an
-      array of Shift resource names.
-    |||,
-    [
-      d.argument.new('shifts', d.T.array),
-    ]
-  ),
-  withShifts(shifts)::
-    forProvider.withType('calendar')
-    + forProvider.withShiftsRef([
-      forProvider.shiftsRef.withName(shift)
-      for shift in shifts
-    ]),
+  calendar: {
+    '#new':: d.func.new(
+      |||
+        `new` creates a Schedule with type `calendar`. It automatically
+        includes references to Shift objects which are members of its `shifts`
+        field. `shifts` is an object representing zero or more shifts.
+
+        Shifts are unordered, and so are supplied as an object to allow for
+        reuse. For example, a Primary/Secondary pair of Schedules could be
+        declared like:
+
+            local calendar = grafanaplane.oncall.schedule.calendar,
+            local onCallUsers = [['[email protected]'], ['[email protected]']],
+
+            primary: calendar.new('Primary', {
+              weekday:  // 24 hour daily shift
+                calendar.shift.new('Weekday', '2025-01-01T12:00:00', 24 * 60 * 60)
+                + calendar.shift.withByDay(['MO', 'TU', 'WE', 'TH', 'FR'])
+                + calendar.shift.withRollingUsers('daily', onCallUsers),
+              weekend:  // 72 hour weekend shift
+                calendar.shift.new('Weekend', '2025-01-01T12:00:00', 72 * 60 * 60)
+                + calendar.shift.withByDay(['FR', 'SA', 'SU', 'MO'])
+                + calendar.shift.withRollingUsers('weekly', onCallUsers),
+            }),
+
+            secondary: calendar.new('Secondary', {
+              [shift.key]:
+                shift.value
+                // replace the resource ID
+                + calendar.shift.withId('secondary-' + shift.value.metadata.name)
+                // start rotating from the second person
+                + calendar.shift.withStartRotationFromUserIndex(1)
+              for shift in std.objectKeysValues(self.primary.shifts)
+            }),
+      |||,
+      [
+        d.argument.new('name', d.T.string),
+        d.argument.new('shifts', d.T.object, default='{}'),
+      ]
+    ),
+    new(name, shifts={}): {
+      scheduleName:: xtd.ascii.stringToRFC1123(name),
+      schedule:
+        schedule.new(self.scheduleName)
+        + forProvider.withName(name)
+        + forProvider.withType('calendar')
+        + forProvider.withShiftsRef([
+          forProvider.shiftsRef.withName(shift.metadata.name)
+          for shift in std.objectValues(self.shifts)
+        ]),
+      shifts: shifts,
+    },
+
+    '#withId':: d.func.new(
+      '`withId` sets the resource name for a Schedule',
+      [d.argument.new('id', d.T.string)]
+    ),
+    withId(id):: {
+      scheduleName:: id,
+      schedule+: schedule.metadata.withName(id),
+    },
+
+    '#withShifts':: d.func.new(
+      |||
+        `withShifts` sets a map of Shifts on a calendar-type Schedule.
+      |||,
+      [d.argument.new('shifts', d.T.object)]
+    ),
+    withShifts(shifts):: {
+      shifts: shifts,
+    },
+
+    shift: import './shift.libsonnet',
+  },
 }

grafanaplane/oncall/shift.libsonnet

@@ -7,12 +7,23 @@ local forProvider = shift.spec.parameters.forProvider;
 
 {
   '#new':: d.func.new(
-    '`new` creates an OnCallShift. The `name` is a display-friendly string.',
-    [d.argument.new('name', d.T.string)]
+    |||
+      `new` creates an OnCallShift, which can be used in Schedules of type
+      `calendar`. `name` is a display-friendly string. `start` is a datetime as
+      `yyyy-MM-dd'T'HH:mm:ss`, such as `“2020-09-05T08:00:00”`. `duration` is
+      the length of the shift in seconds.
+    |||,
+    [
+      d.argument.new('name', d.T.string),
+      d.argument.new('start', d.T.string),
+      d.argument.new('duration', d.T.number),
+    ]
   ),
-  new(name)::
+  new(name, start, duration)::
     shift.new(xtd.ascii.stringToRFC1123(name))
-    + forProvider.withName(name),
+    + forProvider.withName(name)
+    + forProvider.withStart(start)
+    + forProvider.withDuration(duration),
 
   '#withId':: d.func.new(
     '`withId` sets the resource name for a Shift',
@@ -57,8 +68,6 @@ local forProvider = shift.spec.parameters.forProvider;
     + forProvider.withFrequency(frequency),
 
   // Expose some generated functions here.
-  '#withStart':: forProvider['#withStart'],
-  withStart:: forProvider.withStart,
   '#withStartRotationFromUserIndex':: forProvider['#withStartRotationFromUserIndex'],
   withStartRotationFromUserIndex:: forProvider.withStartRotationFromUserIndex,
   '#withByDay':: forProvider['#withByDay'],