@oneuptime/common 11.3.26 → 11.4.0

package/Tests/Types/OnCallDutyPolicy/LayerUtilDailyMutation.test.ts

@@ -0,0 +1,128 @@
+import LayerUtil from "../../../Types/OnCallDutyPolicy/Layer";
+import CalendarEvent from "../../../Types/Calendar/CalendarEvent";
+import RestrictionTimes, {
+  RestrictionType,
+} from "../../../Types/OnCallDutyPolicy/RestrictionTimes";
+import Recurring from "../../../Types/Events/Recurring";
+import OneUptimeDate from "../../../Types/Date";
+import User from "../../../Models/DatabaseModels/User";
+import EventInterval from "../../../Types/Events/EventInterval";
+
+function user(id: string): User {
+  return {
+    id: {
+      toString: () => {
+        return id;
+      },
+    } as any,
+  } as User;
+}
+
+function rotation(t: EventInterval, c: number): Recurring {
+  return Recurring.fromJSON({
+    _type: "Recurring",
+    value: {
+      intervalType: t,
+      intervalCount: { _type: "PositiveNumber", value: c },
+    },
+  } as any);
+}
+
+/*
+ * Build a daily restriction whose start/end are specific wall-clock times in a
+ * given IANA timezone on an arbitrary reference date.
+ */
+function dailyRestrictionTz(
+  startHour: number,
+  startMin: number,
+  endHour: number,
+  endMin: number,
+): RestrictionTimes {
+  const r: RestrictionTimes = new RestrictionTimes();
+  r.restictionType = RestrictionType.Daily;
+  r.dayRestrictionTimes = {
+    startTime: OneUptimeDate.getDateWithCustomTime({
+      hours: startHour,
+      minutes: startMin,
+      seconds: 0,
+    }),
+    endTime: OneUptimeDate.getDateWithCustomTime({
+      hours: endHour,
+      minutes: endMin,
+      seconds: 0,
+    }),
+  };
+  return r;
+}
+
+describe("Daily restriction in-place mutation / DST drift", () => {
+  test("restriction start in the DST spring-forward gap drifts permanently after the transition", () => {
+    const tz: string = "America/New_York";
+    const layerUtil: LayerUtil = new LayerUtil();
+    // 2026 US DST spring-forward: Sun Mar 8, 02:00 -> 03:00. So 02:30 is invalid.
+    const r: RestrictionTimes = dailyRestrictionTz(2, 30, 10, 0); // 02:30 -> 10:00 daily
+
+    // Daily rotation, one user, handoff at 12:00 local. Events span Mar 6 -> Mar 12.
+    const layerStart: Date = new Date(Date.UTC(2026, 2, 6, 5, 0, 0)); // Mar 6 00:00 ET-ish
+    const events: Array<CalendarEvent> = layerUtil.getEvents({
+      users: [user("A")],
+      startDateTimeOfLayer: layerStart,
+      restrictionTimes: r,
+      handOffTime: new Date(Date.UTC(2026, 2, 6, 17, 0, 0)), // arbitrary
+      rotation: rotation(EventInterval.Day, 1),
+      timezone: tz,
+      calendarStartDate: layerStart,
+      calendarEndDate: new Date(Date.UTC(2026, 2, 13, 5, 0, 0)),
+    });
+
+    // eslint-disable-next-line no-console
+    console.log("\n=== DST spring-forward restriction 02:30->10:00 ET ===");
+    for (const e of events) {
+      // eslint-disable-next-line no-console
+      console.log(
+        `  start(ET local h:m)=${startHourET(e.start, tz)}  end=${startHourET(
+          e.end,
+          tz,
+        )}   [${e.start.toISOString()} -> ${e.end.toISOString()}]`,
+      );
+    }
+
+    /*
+     * Gather, per day AFTER the transition (Mar 9, 10, 11), the local start-hour of
+     * the first event that day. If the mutation drifted it, it will be 03:30 not 02:30.
+     */
+    const startHoursAfter: Array<string> = [];
+    for (const e of events) {
+      const localStart: string = startHourET(e.start, tz);
+      const day: number = etDay(e.start, tz);
+      if (day >= 9 && day <= 11 && localStart.endsWith(":30")) {
+        // pick the segment starting near the restriction start
+        startHoursAfter.push(`${day}:${localStart}`);
+      }
+    }
+    // eslint-disable-next-line no-console
+    console.log(
+      "after-transition :30 starts =",
+      JSON.stringify(startHoursAfter),
+    );
+  });
+});
+
+function startHourET(d: Date, tz: string): string {
+  // format hour:minute as seen in tz
+  const s: string = new Intl.DateTimeFormat("en-US", {
+    timeZone: tz,
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+  }).format(d);
+  return s;
+}
+
+function etDay(d: Date, tz: string): number {
+  const s: string = new Intl.DateTimeFormat("en-US", {
+    timeZone: tz,
+    day: "2-digit",
+  }).format(d);
+  return parseInt(s, 10);
+}

package/Tests/Types/OnCallDutyPolicy/LayerUtilDailyProbe.test.ts

@@ -0,0 +1,203 @@
+import LayerUtil from "../../../Types/OnCallDutyPolicy/Layer";
+import CalendarEvent from "../../../Types/Calendar/CalendarEvent";
+import RestrictionTimes, {
+  RestrictionType,
+} from "../../../Types/OnCallDutyPolicy/RestrictionTimes";
+import Recurring from "../../../Types/Events/Recurring";
+import OneUptimeDate from "../../../Types/Date";
+import User from "../../../Models/DatabaseModels/User";
+import EventInterval from "../../../Types/Events/EventInterval";
+
+function user(id: string): User {
+  return {
+    id: {
+      toString: () => {
+        return id;
+      },
+    } as any,
+  } as User;
+}
+
+function rotation(t: EventInterval, c: number): Recurring {
+  return Recurring.fromJSON({
+    _type: "Recurring",
+    value: {
+      intervalType: t,
+      intervalCount: { _type: "PositiveNumber", value: c },
+    },
+  } as any);
+}
+
+function dailyRestrictionHM(
+  sH: number,
+  sM: number,
+  eH: number,
+  eM: number,
+): RestrictionTimes {
+  const r: RestrictionTimes = new RestrictionTimes();
+  r.restictionType = RestrictionType.Daily;
+  r.dayRestrictionTimes = {
+    startTime: OneUptimeDate.getDateWithCustomTime({
+      hours: sH,
+      minutes: sM,
+      seconds: 0,
+    }),
+    endTime: OneUptimeDate.getDateWithCustomTime({
+      hours: eH,
+      minutes: eM,
+      seconds: 0,
+    }),
+  };
+  return r;
+}
+
+function fmt(d: Date): string {
+  return OneUptimeDate.toString(d);
+}
+
+function dump(label: string, events: Array<CalendarEvent>): void {
+  // eslint-disable-next-line no-console
+  console.log(`\n=== ${label} (${events.length} events) ===`);
+  for (const e of events) {
+    // eslint-disable-next-line no-console
+    console.log(`  ${e.title}: ${fmt(e.start)}  ->  ${fmt(e.end)}`);
+  }
+}
+
+function coveringUser(events: Array<CalendarEvent>, t: Date): string | null {
+  for (const e of events) {
+    if (e.start.getTime() <= t.getTime() && e.end.getTime() > t.getTime()) {
+      return e.title;
+    }
+  }
+  return null;
+}
+
+describe("Daily restriction probe", () => {
+  test("A) full-day 00:00 -> 23:59 daily restriction, daily rotation midnight handoff", () => {
+    const layerUtil: LayerUtil = new LayerUtil();
+    const layerStart: Date = new Date(2026, 0, 5, 0, 0, 0);
+    const events: Array<CalendarEvent> = layerUtil.getEvents({
+      users: [user("A"), user("B")],
+      startDateTimeOfLayer: layerStart,
+      restrictionTimes: dailyRestrictionHM(0, 0, 23, 59),
+      handOffTime: new Date(2026, 0, 5, 0, 0, 0),
+      rotation: rotation(EventInterval.Day, 1),
+      calendarStartDate: layerStart,
+      calendarEndDate: new Date(2026, 0, 8, 0, 0, 0),
+    });
+    dump("A full-day 00:00-23:59", events);
+    // check coverage at various instants
+    // eslint-disable-next-line no-console
+    console.log(
+      "cover Jan6 23:59:30 =",
+      coveringUser(events, new Date(2026, 0, 6, 23, 59, 30)),
+    );
+    // eslint-disable-next-line no-console
+    console.log(
+      "cover Jan6 12:00 =",
+      coveringUser(events, new Date(2026, 0, 6, 12, 0, 0)),
+    );
+  });
+
+  test("B) 00:00 -> 00:00 daily restriction (user may intend all-day)", () => {
+    const layerUtil: LayerUtil = new LayerUtil();
+    const layerStart: Date = new Date(2026, 0, 5, 0, 0, 0);
+    const events: Array<CalendarEvent> = layerUtil.getEvents({
+      users: [user("A")],
+      startDateTimeOfLayer: layerStart,
+      restrictionTimes: dailyRestrictionHM(0, 0, 0, 0),
+      handOffTime: new Date(2026, 0, 5, 0, 0, 0),
+      rotation: rotation(EventInterval.Day, 1),
+      calendarStartDate: layerStart,
+      calendarEndDate: new Date(2026, 0, 8, 0, 0, 0),
+    });
+    dump("B 00:00-00:00", events);
+  });
+
+  test("C) in-place mutation of dayRestrictionTimes", () => {
+    const layerUtil: LayerUtil = new LayerUtil();
+    const layerStart: Date = new Date(2026, 0, 5, 0, 0, 0);
+    const r: RestrictionTimes = dailyRestrictionHM(9, 0, 17, 0);
+    const beforeStart: Date = r.dayRestrictionTimes!.startTime;
+    const beforeEnd: Date = r.dayRestrictionTimes!.endTime;
+    // eslint-disable-next-line no-console
+    console.log("BEFORE start:", fmt(beforeStart), "end:", fmt(beforeEnd));
+    layerUtil.getEvents({
+      users: [user("A"), user("B")],
+      startDateTimeOfLayer: layerStart,
+      restrictionTimes: r,
+      handOffTime: new Date(2026, 0, 5, 12, 0, 0),
+      rotation: rotation(EventInterval.Day, 1),
+      calendarStartDate: layerStart,
+      calendarEndDate: new Date(2026, 0, 15, 0, 0, 0),
+    });
+    // eslint-disable-next-line no-console
+    console.log(
+      "AFTER  start:",
+      fmt(r.dayRestrictionTimes!.startTime),
+      "end:",
+      fmt(r.dayRestrictionTimes!.endTime),
+    );
+  });
+
+  test("D) overnight 22:00 -> 06:00, daily rotation 09:00 handoff, coverage completeness", () => {
+    const layerUtil: LayerUtil = new LayerUtil();
+    const layerStart: Date = new Date(2026, 0, 5, 9, 0, 0);
+    const events: Array<CalendarEvent> = layerUtil.getEvents({
+      users: [user("A"), user("B")],
+      startDateTimeOfLayer: layerStart,
+      restrictionTimes: dailyRestrictionHM(22, 0, 6, 0),
+      handOffTime: new Date(2026, 0, 5, 9, 0, 0),
+      rotation: rotation(EventInterval.Day, 1),
+      calendarStartDate: layerStart,
+      calendarEndDate: new Date(2026, 0, 9, 0, 0, 0),
+    });
+    dump("D overnight 22-06", events);
+    for (const [label, t] of [
+      ["Jan5 23:00", new Date(2026, 0, 5, 23, 0, 0)],
+      ["Jan6 03:00", new Date(2026, 0, 6, 3, 0, 0)],
+      ["Jan6 06:00", new Date(2026, 0, 6, 6, 0, 0)],
+      ["Jan6 12:00", new Date(2026, 0, 6, 12, 0, 0)],
+      ["Jan6 22:00", new Date(2026, 0, 6, 22, 0, 0)],
+    ] as Array<[string, Date]>) {
+      // eslint-disable-next-line no-console
+      console.log(`cover ${label} =`, coveringUser(events, t));
+    }
+  });
+
+  test("E) live 1-second window at overnight boundary instants", () => {
+    const layerUtil: LayerUtil = new LayerUtil();
+    const resolveAt: (now: Date) => string | null = (
+      now: Date,
+    ): string | null => {
+      const events: Array<CalendarEvent> = layerUtil.getMultiLayerEvents(
+        {
+          layers: [
+            {
+              users: [user("A"), user("B")],
+              startDateTimeOfLayer: new Date(2026, 0, 5, 9, 0, 0),
+              restrictionTimes: dailyRestrictionHM(22, 0, 6, 0),
+              handOffTime: new Date(2026, 0, 5, 9, 0, 0),
+              rotation: rotation(EventInterval.Day, 1),
+            },
+          ],
+          calendarStartDate: now,
+          calendarEndDate: OneUptimeDate.addRemoveSeconds(now, 1),
+        },
+        { getNumberOfEvents: 1 },
+      );
+      return events[0]?.title ?? null;
+    };
+    for (const [label, t] of [
+      ["Jan6 05:59:59", new Date(2026, 0, 6, 5, 59, 59)],
+      ["Jan6 06:00:00", new Date(2026, 0, 6, 6, 0, 0)],
+      ["Jan6 21:59:59", new Date(2026, 0, 6, 21, 59, 59)],
+      ["Jan6 22:00:00", new Date(2026, 0, 6, 22, 0, 0)],
+      ["Jan6 00:00:00", new Date(2026, 0, 6, 0, 0, 0)],
+    ] as Array<[string, Date]>) {
+      // eslint-disable-next-line no-console
+      console.log(`live ${label} =`, resolveAt(t));
+    }
+  });
+});

package/Tests/Types/OnCallDutyPolicy/LayerUtilDiffFuzz.test.ts

@@ -0,0 +1,322 @@
+/**
+ * EMPIRICAL differential & invariant fuzzing (audit lens).
+ *
+ * (1) DIFFERENTIAL: for many rotation configs, compare the WINDOWED current-user
+ *     resolution (getEvents starting at `at` with getNumberOfEvents:1) against a
+ *     FULL expansion from layer start, at many OFF-boundary sampled instants.
+ * (2) INVARIANTS: 24/7 coverage contiguity, fairness, rotation order.
+ *
+ * Any off-boundary mismatch is a real bug and is reported with the exact
+ * config + instant + expected/actual.
+ */
+import LayerUtil, { LayerProps } from "../../../Types/OnCallDutyPolicy/Layer";
+import CalendarEvent from "../../../Types/Calendar/CalendarEvent";
+import RestrictionTimes, {
+  RestrictionType,
+} from "../../../Types/OnCallDutyPolicy/RestrictionTimes";
+import Recurring from "../../../Types/Events/Recurring";
+import OneUptimeDate from "../../../Types/Date";
+import User from "../../../Models/DatabaseModels/User";
+import EventInterval from "../../../Types/Events/EventInterval";
+import PositiveNumber from "../../../Types/PositiveNumber";
+
+function user(id: string): User {
+  return {
+    id: {
+      toString: (): string => {
+        return id;
+      },
+    } as any,
+  } as User;
+}
+
+function noRestriction(): RestrictionTimes {
+  const r: RestrictionTimes = new RestrictionTimes();
+  r.restictionType = RestrictionType.None;
+  r.dayRestrictionTimes = null;
+  return r;
+}
+
+function dailyRestriction(
+  startHour: number,
+  endHour: number,
+): RestrictionTimes {
+  const r: RestrictionTimes = new RestrictionTimes();
+  r.restictionType = RestrictionType.Daily;
+  r.dayRestrictionTimes = {
+    startTime: OneUptimeDate.getDateWithCustomTime({
+      hours: startHour,
+      minutes: 0,
+      seconds: 0,
+    }),
+    endTime: OneUptimeDate.getDateWithCustomTime({
+      hours: endHour,
+      minutes: 0,
+      seconds: 0,
+    }),
+  };
+  return r;
+}
+
+interface Config {
+  name: string;
+  intervalType: EventInterval;
+  intervalCount: number;
+  userIds: string[];
+  restriction: RestrictionTimes;
+  timezone?: string | undefined;
+  start: Date;
+}
+
+function rotationOf(c: Config): Recurring {
+  const rot: Recurring = new Recurring();
+  rot.intervalType = c.intervalType;
+  rot.intervalCount = new PositiveNumber(c.intervalCount);
+  return rot;
+}
+
+function layerOf(c: Config): LayerProps {
+  const rot: Recurring = rotationOf(c);
+  const handoff: Date = Recurring.getNextDateInterval(c.start, rot);
+  return {
+    users: c.userIds.map(user),
+    startDateTimeOfLayer: c.start,
+    restrictionTimes: c.restriction,
+    handOffTime: handoff,
+    rotation: rot,
+    timezone: c.timezone,
+  };
+}
+
+// Windowed "who is on call at `at`" (what the live roster resolution uses).
+function windowedUserAt(layer: LayerProps, at: Date): string | null {
+  const util: LayerUtil = new LayerUtil();
+  const events: Array<CalendarEvent> = util.getEvents(
+    {
+      ...layer,
+      calendarStartDate: at,
+      calendarEndDate: OneUptimeDate.addRemoveDays(at, 40),
+    },
+    { getNumberOfEvents: 1 },
+  );
+  return events[0]?.title ?? null;
+}
+
+// Full expansion from layer start over [start, to].
+function fullExpand(layer: LayerProps, to: Date): Array<CalendarEvent> {
+  const util: LayerUtil = new LayerUtil();
+  return util.getEvents({
+    ...layer,
+    calendarStartDate: layer.startDateTimeOfLayer,
+    calendarEndDate: to,
+  });
+}
+
+// Find the event that covers `at` (start <= at < end), interior only.
+function coveringEvent(
+  events: Array<CalendarEvent>,
+  at: Date,
+): CalendarEvent | null {
+  for (const e of events) {
+    if (
+      OneUptimeDate.isOnOrAfter(at, e.start) &&
+      OneUptimeDate.isBefore(at, e.end)
+    ) {
+      return e;
+    }
+  }
+  return null;
+}
+
+// Next event that starts strictly after `at`.
+function nextEventAfter(
+  events: Array<CalendarEvent>,
+  at: Date,
+): CalendarEvent | null {
+  let best: CalendarEvent | null = null;
+  for (const e of events) {
+    if (OneUptimeDate.isAfter(e.start, at)) {
+      if (best === null || OneUptimeDate.isBefore(e.start, best.start)) {
+        best = e;
+      }
+    }
+  }
+  return best;
+}
+
+// period length in ms for sampling offsets (approx; used only to pick instants).
+function approxPeriodMs(c: Config): number {
+  const base: Record<string, number> = {
+    [EventInterval.Hour]: 3600000,
+    [EventInterval.Day]: 86400000,
+    [EventInterval.Week]: 604800000,
+    [EventInterval.Month]: 30 * 86400000,
+    [EventInterval.Year]: 365 * 86400000,
+  };
+  return (base[c.intervalType] || 86400000) * c.intervalCount;
+}
+
+const FIXED_START_JAN: Date = OneUptimeDate.fromString(
+  "2025-01-06T00:00:00.000Z",
+); // a Monday 00:00 UTC
+
+// Build the config matrix.
+function buildConfigs(): Config[] {
+  const configs: Config[] = [];
+  const intervals: EventInterval[] = [
+    EventInterval.Hour,
+    EventInterval.Day,
+    EventInterval.Week,
+    EventInterval.Month,
+  ];
+  const counts: number[] = [1, 2, 3];
+  const userSets: string[][] = [
+    ["A"],
+    ["A", "B"],
+    ["A", "B", "C"],
+    ["A", "B", "C", "D", "E"],
+  ];
+  const timezones: (string | undefined)[] = [
+    undefined,
+    "America/New_York",
+    "Asia/Kolkata",
+  ];
+
+  for (const it of intervals) {
+    for (const count of counts) {
+      for (const users of userSets) {
+        for (const tz of timezones) {
+          configs.push({
+            name: `${count}x${it} users=${users.length} tz=${tz ?? "local"} unrestricted`,
+            intervalType: it,
+            intervalCount: count,
+            userIds: users,
+            restriction: noRestriction(),
+            timezone: tz,
+            start: FIXED_START_JAN,
+          });
+        }
+      }
+    }
+  }
+  return configs;
+}
+
+// Off-boundary offsets (in units of periods) to probe.
+const PERIOD_OFFSETS: number[] = [
+  0.13, 0.37, 0.5, 0.63, 0.87, 1.29, 2.41, 3.17, 5.53, 7.31, 10.42, 13.19,
+  20.61, 30.28, 50.44,
+];
+
+describe("DIFFERENTIAL: windowed resolution == full expansion (unrestricted, off-boundary)", () => {
+  const configs: Config[] = buildConfigs();
+
+  for (const c of configs) {
+    it(`${c.name}`, () => {
+      const layer: LayerProps = layerOf(c);
+      const periodMs: number = approxPeriodMs(c);
+      const mismatches: string[] = [];
+
+      for (const off of PERIOD_OFFSETS) {
+        const at: Date = new Date(
+          c.start.getTime() + Math.round(off * periodMs),
+        );
+        // Full expansion needs to comfortably contain `at` plus a next event.
+        const to: Date = new Date(at.getTime() + 3 * periodMs);
+        const full: Array<CalendarEvent> = fullExpand(layer, to);
+        const cover: CalendarEvent | null = coveringEvent(full, at);
+        const windowed: string | null = windowedUserAt(layer, at);
+
+        if (cover) {
+          if (windowed !== cover.title) {
+            mismatches.push(
+              `at=${at.toISOString()} off=${off} expected(full-cover)=${cover.title} windowed=${windowed}`,
+            );
+          }
+        } else {
+          // In an unrestricted rotation there should ALWAYS be coverage.
+          mismatches.push(
+            `at=${at.toISOString()} off=${off} NO full coverage (unexpected in 24/7 rotation) windowed=${windowed}`,
+          );
+        }
+      }
+
+      expect({ config: c.name, mismatches }).toEqual({
+        config: c.name,
+        mismatches: [],
+      });
+    });
+  }
+});
+
+describe("DIFFERENTIAL: restricted daily 09-17 covered-instant agreement", () => {
+  const restrictedConfigs: Config[] = [];
+  const intervals: EventInterval[] = [EventInterval.Day, EventInterval.Week];
+  const counts: number[] = [1, 2];
+  const userSets: string[][] = [
+    ["A", "B"],
+    ["A", "B", "C"],
+  ];
+  const timezones: (string | undefined)[] = [
+    undefined,
+    "America/New_York",
+    "Asia/Kolkata",
+  ];
+  for (const it of intervals) {
+    for (const count of counts) {
+      for (const users of userSets) {
+        for (const tz of timezones) {
+          restrictedConfigs.push({
+            name: `${count}x${it} users=${users.length} tz=${tz ?? "local"} daily09-17`,
+            intervalType: it,
+            intervalCount: count,
+            userIds: users,
+            restriction: dailyRestriction(9, 17),
+            timezone: tz,
+            start: FIXED_START_JAN,
+          });
+        }
+      }
+    }
+  }
+
+  for (const c of restrictedConfigs) {
+    it(`${c.name}`, () => {
+      const layer: LayerProps = layerOf(c);
+      const periodMs: number = approxPeriodMs(c);
+      const mismatches: string[] = [];
+
+      for (const off of PERIOD_OFFSETS) {
+        const at: Date = new Date(
+          c.start.getTime() + Math.round(off * periodMs),
+        );
+        const to: Date = new Date(at.getTime() + 5 * periodMs);
+        const full: Array<CalendarEvent> = fullExpand(layer, to);
+        const cover: CalendarEvent | null = coveringEvent(full, at);
+        const windowed: string | null = windowedUserAt(layer, at);
+
+        if (cover) {
+          // `at` is inside a covered restriction window: must agree.
+          if (windowed !== cover.title) {
+            mismatches.push(
+              `COVERED at=${at.toISOString()} off=${off} expected=${cover.title} windowed=${windowed}`,
+            );
+          }
+        } else {
+          // `at` in a gap: windowed should equal the NEXT covered user.
+          const nxt: CalendarEvent | null = nextEventAfter(full, at);
+          if (nxt && windowed !== nxt.title) {
+            mismatches.push(
+              `GAP at=${at.toISOString()} off=${off} expectedNext=${nxt.title} windowed=${windowed}`,
+            );
+          }
+        }
+      }
+
+      expect({ config: c.name, mismatches }).toEqual({
+        config: c.name,
+        mismatches: [],
+      });
+    });
+  }
+});