@oneuptime/common 11.6.1 → 11.7.0

package/Tests/Utils/NetworkSite/SiteStatusRollupUtil.test.ts

@@ -0,0 +1,221 @@
+import SiteStatusRollupUtil, {
+  DeviceHealthState,
+  RollupStatusOption,
+} from "../../../Utils/NetworkSite/SiteStatusRollupUtil";
+
+/*
+ * MonitorStatus priority is HIGHER = WORSE (seeded: Operational 1,
+ * Degraded 2, Offline 3).
+ */
+const OPERATIONAL: RollupStatusOption = {
+  monitorStatusId: "status-operational",
+  priority: 1,
+};
+const DEGRADED: RollupStatusOption = {
+  monitorStatusId: "status-degraded",
+  priority: 2,
+};
+const OFFLINE: RollupStatusOption = {
+  monitorStatusId: "status-offline",
+  priority: 3,
+};
+
+const NOW: Date = new Date("2026-07-22T12:00:00Z");
+
+function minutesAgo(minutes: number): Date {
+  return new Date(NOW.getTime() - minutes * 60 * 1000);
+}
+
+function worst(
+  deviceStates: Array<DeviceHealthState>,
+  overrides?: {
+    operationalStatus?: RollupStatusOption | null;
+    offlineStatus?: RollupStatusOption | null;
+    freshnessWindowInMinutes?: number;
+  },
+): string | null {
+  return SiteStatusRollupUtil.worstStatus({
+    deviceStates,
+    operationalStatus:
+      overrides && "operationalStatus" in overrides
+        ? overrides.operationalStatus
+        : OPERATIONAL,
+    offlineStatus:
+      overrides && "offlineStatus" in overrides
+        ? overrides.offlineStatus
+        : OFFLINE,
+    now: NOW,
+    freshnessWindowInMinutes: overrides?.freshnessWindowInMinutes,
+  });
+}
+
+describe("SiteStatusRollupUtil.worstStatus", () => {
+  it("returns null for an empty device set (no-op)", () => {
+    expect(worst([])).toBeNull();
+  });
+
+  it("a single monitored device contributes its stamped status", () => {
+    expect(
+      worst([
+        {
+          currentMonitorStatusId: DEGRADED.monitorStatusId,
+          monitorStatusPriority: DEGRADED.priority,
+        },
+      ]),
+    ).toBe(DEGRADED.monitorStatusId);
+  });
+
+  it("the worst (highest priority) stamped status wins", () => {
+    expect(
+      worst([
+        {
+          currentMonitorStatusId: OPERATIONAL.monitorStatusId,
+          monitorStatusPriority: OPERATIONAL.priority,
+        },
+        {
+          currentMonitorStatusId: OFFLINE.monitorStatusId,
+          monitorStatusPriority: OFFLINE.priority,
+        },
+        {
+          currentMonitorStatusId: DEGRADED.monitorStatusId,
+          monitorStatusPriority: DEGRADED.priority,
+        },
+      ]),
+    ).toBe(OFFLINE.monitorStatusId);
+  });
+
+  it("a fresh unmonitored device maps to the operational equivalent", () => {
+    expect(worst([{ lastSeenAt: minutesAgo(5) }])).toBe(
+      OPERATIONAL.monitorStatusId,
+    );
+  });
+
+  it("a stale unmonitored device maps to the offline equivalent", () => {
+    expect(worst([{ lastSeenAt: minutesAgo(30) }])).toBe(
+      OFFLINE.monitorStatusId,
+    );
+  });
+
+  it("a never-seen unmonitored device maps to the offline equivalent", () => {
+    expect(worst([{}])).toBe(OFFLINE.monitorStatusId);
+    expect(worst([{ lastSeenAt: null }])).toBe(OFFLINE.monitorStatusId);
+  });
+
+  it("freshness boundary: exactly 15 minutes is still fresh, beyond is not", () => {
+    expect(worst([{ lastSeenAt: minutesAgo(15) }])).toBe(
+      OPERATIONAL.monitorStatusId,
+    );
+    expect(
+      worst([{ lastSeenAt: new Date(minutesAgo(15).getTime() - 1) }]),
+    ).toBe(OFFLINE.monitorStatusId);
+  });
+
+  it("mix: a stale unmonitored device outranks a monitored operational one", () => {
+    expect(
+      worst([
+        {
+          currentMonitorStatusId: OPERATIONAL.monitorStatusId,
+          monitorStatusPriority: OPERATIONAL.priority,
+        },
+        { lastSeenAt: minutesAgo(60) },
+      ]),
+    ).toBe(OFFLINE.monitorStatusId);
+  });
+
+  it("mix: a monitored offline device outranks fresh unmonitored ones", () => {
+    expect(
+      worst([
+        { lastSeenAt: minutesAgo(1) },
+        {
+          currentMonitorStatusId: OFFLINE.monitorStatusId,
+          monitorStatusPriority: OFFLINE.priority,
+        },
+        { lastSeenAt: minutesAgo(2) },
+      ]),
+    ).toBe(OFFLINE.monitorStatusId);
+  });
+
+  it("a stamped status whose priority is unknown falls back to freshness", () => {
+    // The MonitorStatus row was deleted: treat the device by lastSeenAt.
+    expect(
+      worst([
+        {
+          currentMonitorStatusId: "deleted-status",
+          monitorStatusPriority: undefined,
+          lastSeenAt: minutesAgo(1),
+        },
+      ]),
+    ).toBe(OPERATIONAL.monitorStatusId);
+    expect(
+      worst([
+        {
+          currentMonitorStatusId: "deleted-status",
+          monitorStatusPriority: null,
+          lastSeenAt: minutesAgo(120),
+        },
+      ]),
+    ).toBe(OFFLINE.monitorStatusId);
+  });
+
+  it("priority ties keep the first contributor (stable)", () => {
+    expect(
+      worst([
+        {
+          currentMonitorStatusId: "status-a",
+          monitorStatusPriority: 2,
+        },
+        {
+          currentMonitorStatusId: "status-b",
+          monitorStatusPriority: 2,
+        },
+      ]),
+    ).toBe("status-a");
+  });
+
+  it("returns null when only freshness fallbacks apply but the project has no flagged rows", () => {
+    expect(
+      worst([{ lastSeenAt: minutesAgo(1) }, { lastSeenAt: minutesAgo(60) }], {
+        operationalStatus: null,
+        offlineStatus: null,
+      }),
+    ).toBeNull();
+  });
+
+  it("skips devices without a usable fallback but keeps the rest", () => {
+    expect(
+      worst(
+        [
+          { lastSeenAt: minutesAgo(60) }, // offline equivalent missing -> skipped
+          {
+            currentMonitorStatusId: DEGRADED.monitorStatusId,
+            monitorStatusPriority: DEGRADED.priority,
+          },
+        ],
+        { offlineStatus: null },
+      ),
+    ).toBe(DEGRADED.monitorStatusId);
+  });
+
+  it("honors a custom freshness window", () => {
+    expect(
+      worst([{ lastSeenAt: minutesAgo(20) }], {
+        freshnessWindowInMinutes: 30,
+      }),
+    ).toBe(OPERATIONAL.monitorStatusId);
+    expect(
+      worst([{ lastSeenAt: minutesAgo(20) }], {
+        freshnessWindowInMinutes: 10,
+      }),
+    ).toBe(OFFLINE.monitorStatusId);
+  });
+
+  it("a lastSeenAt in the future counts as fresh, not an error", () => {
+    expect(worst([{ lastSeenAt: minutesAgo(-5) }])).toBe(
+      OPERATIONAL.monitorStatusId,
+    );
+  });
+
+  it("exposes the default freshness window as 15 minutes", () => {
+    expect(SiteStatusRollupUtil.DEFAULT_FRESHNESS_WINDOW_IN_MINUTES).toBe(15);
+  });
+});

package/Tests/Utils/NetworkSite/SiteUptimeUtil.test.ts

@@ -0,0 +1,283 @@
+import SiteUptimeUtil, {
+  SiteStatusTimelineRow,
+} from "../../../Utils/NetworkSite/SiteUptimeUtil";
+
+const WINDOW_START: Date = new Date("2026-07-22T00:00:00Z");
+const WINDOW_END: Date = new Date("2026-07-23T00:00:00Z"); // 24h window
+
+function hoursAfterStart(hours: number): Date {
+  return new Date(WINDOW_START.getTime() + hours * 60 * 60 * 1000);
+}
+
+function row(data: {
+  startsAt: Date;
+  endsAt: Date | null;
+  isOperationalState: boolean;
+  priority?: number;
+}): SiteStatusTimelineRow {
+  return {
+    monitorStatusId: data.isOperationalState ? "operational" : "down",
+    startsAt: data.startsAt,
+    endsAt: data.endsAt,
+    priority: data.priority ?? (data.isOperationalState ? 1 : 3),
+    isOperationalState: data.isOperationalState,
+  };
+}
+
+describe("SiteUptimeUtil.calculateUptimePercent", () => {
+  it("is 100 with no timeline rows", () => {
+    expect(
+      SiteUptimeUtil.calculateUptimePercent([], WINDOW_START, WINDOW_END),
+    ).toBe(100);
+  });
+
+  it("is 100 when every row is operational", () => {
+    expect(
+      SiteUptimeUtil.calculateUptimePercent(
+        [
+          row({
+            startsAt: WINDOW_START,
+            endsAt: null,
+            isOperationalState: true,
+          }),
+        ],
+        WINDOW_START,
+        WINDOW_END,
+      ),
+    ).toBe(100);
+  });
+
+  it("is 0 when a non-operational row covers the whole window", () => {
+    expect(
+      SiteUptimeUtil.calculateUptimePercent(
+        [
+          row({
+            startsAt: WINDOW_START,
+            endsAt: WINDOW_END,
+            isOperationalState: false,
+          }),
+        ],
+        WINDOW_START,
+        WINDOW_END,
+      ),
+    ).toBe(0);
+  });
+
+  it("an open row (endsAt null) extends to the window end", () => {
+    // Down from hour 18 onwards -> 6h down of 24h -> 75% up.
+    expect(
+      SiteUptimeUtil.calculateUptimePercent(
+        [
+          row({
+            startsAt: hoursAfterStart(18),
+            endsAt: null,
+            isOperationalState: false,
+          }),
+        ],
+        WINDOW_START,
+        WINDOW_END,
+      ),
+    ).toBe(75);
+  });
+
+  it("clamps rows that extend beyond both window edges", () => {
+    // Down row spans well beyond the window on both sides -> 0% up.
+    expect(
+      SiteUptimeUtil.calculateUptimePercent(
+        [
+          row({
+            startsAt: new Date("2026-07-20T00:00:00Z"),
+            endsAt: new Date("2026-07-25T00:00:00Z"),
+            isOperationalState: false,
+          }),
+        ],
+        WINDOW_START,
+        WINDOW_END,
+      ),
+    ).toBe(0);
+  });
+
+  it("clamps a row that starts before the window", () => {
+    // Down until hour 6 -> 18h up of 24h -> 75%.
+    expect(
+      SiteUptimeUtil.calculateUptimePercent(
+        [
+          row({
+            startsAt: new Date("2026-07-21T12:00:00Z"),
+            endsAt: hoursAfterStart(6),
+            isOperationalState: false,
+          }),
+        ],
+        WINDOW_START,
+        WINDOW_END,
+      ),
+    ).toBe(75);
+  });
+
+  it("ignores rows entirely outside the window", () => {
+    expect(
+      SiteUptimeUtil.calculateUptimePercent(
+        [
+          row({
+            startsAt: new Date("2026-07-20T00:00:00Z"),
+            endsAt: new Date("2026-07-21T00:00:00Z"),
+            isOperationalState: false,
+          }),
+          row({
+            startsAt: new Date("2026-07-24T00:00:00Z"),
+            endsAt: new Date("2026-07-25T00:00:00Z"),
+            isOperationalState: false,
+          }),
+        ],
+        WINDOW_START,
+        WINDOW_END,
+      ),
+    ).toBe(100);
+  });
+
+  it("merges overlapping down rows so no second is counted twice", () => {
+    // [2h, 8h] and [6h, 12h] overlap -> merged 10h down -> ~58.33% up.
+    const percent: number = SiteUptimeUtil.calculateUptimePercent(
+      [
+        row({
+          startsAt: hoursAfterStart(2),
+          endsAt: hoursAfterStart(8),
+          isOperationalState: false,
+        }),
+        row({
+          startsAt: hoursAfterStart(6),
+          endsAt: hoursAfterStart(12),
+          isOperationalState: false,
+        }),
+      ],
+      WINDOW_START,
+      WINDOW_END,
+    );
+    expect(percent).toBeCloseTo(((24 - 10) / 24) * 100, 10);
+  });
+
+  it("merges a row contained inside another", () => {
+    const percent: number = SiteUptimeUtil.calculateUptimePercent(
+      [
+        row({
+          startsAt: hoursAfterStart(2),
+          endsAt: hoursAfterStart(12),
+          isOperationalState: false,
+        }),
+        row({
+          startsAt: hoursAfterStart(4),
+          endsAt: hoursAfterStart(6),
+          isOperationalState: false,
+        }),
+      ],
+      WINDOW_START,
+      WINDOW_END,
+    );
+    expect(percent).toBeCloseTo(((24 - 10) / 24) * 100, 10);
+  });
+
+  it("sums disjoint down rows", () => {
+    // 3h + 3h down -> 18h up -> 75%.
+    const percent: number = SiteUptimeUtil.calculateUptimePercent(
+      [
+        row({
+          startsAt: hoursAfterStart(1),
+          endsAt: hoursAfterStart(4),
+          isOperationalState: false,
+        }),
+        row({
+          startsAt: hoursAfterStart(10),
+          endsAt: hoursAfterStart(13),
+          isOperationalState: false,
+        }),
+      ],
+      WINDOW_START,
+      WINDOW_END,
+    );
+    expect(percent).toBe(75);
+  });
+
+  it("interleaves operational and non-operational rows correctly", () => {
+    // Operational rows never subtract, whatever they overlap.
+    const percent: number = SiteUptimeUtil.calculateUptimePercent(
+      [
+        row({
+          startsAt: WINDOW_START,
+          endsAt: hoursAfterStart(12),
+          isOperationalState: true,
+        }),
+        row({
+          startsAt: hoursAfterStart(12),
+          endsAt: hoursAfterStart(18),
+          isOperationalState: false,
+        }),
+        row({
+          startsAt: hoursAfterStart(18),
+          endsAt: null,
+          isOperationalState: true,
+        }),
+      ],
+      WINDOW_START,
+      WINDOW_END,
+    );
+    expect(percent).toBe(75);
+  });
+
+  it("a zero-length down row contributes nothing", () => {
+    expect(
+      SiteUptimeUtil.calculateUptimePercent(
+        [
+          row({
+            startsAt: hoursAfterStart(5),
+            endsAt: hoursAfterStart(5),
+            isOperationalState: false,
+          }),
+        ],
+        WINDOW_START,
+        WINDOW_END,
+      ),
+    ).toBe(100);
+  });
+
+  it("returns 100 for a zero-length or inverted window", () => {
+    expect(
+      SiteUptimeUtil.calculateUptimePercent([], WINDOW_START, WINDOW_START),
+    ).toBe(100);
+    expect(
+      SiteUptimeUtil.calculateUptimePercent([], WINDOW_END, WINDOW_START),
+    ).toBe(100);
+  });
+
+  it("an open down row starting exactly at windowEnd contributes nothing", () => {
+    expect(
+      SiteUptimeUtil.calculateUptimePercent(
+        [
+          row({
+            startsAt: WINDOW_END,
+            endsAt: null,
+            isOperationalState: false,
+          }),
+        ],
+        WINDOW_START,
+        WINDOW_END,
+      ),
+    ).toBe(100);
+  });
+
+  it("non-operational status of ANY priority counts as down (degraded too)", () => {
+    expect(
+      SiteUptimeUtil.calculateUptimePercent(
+        [
+          row({
+            startsAt: WINDOW_START,
+            endsAt: hoursAfterStart(6),
+            isOperationalState: false,
+            priority: 2, // degraded
+          }),
+        ],
+        WINDOW_START,
+        WINDOW_END,
+      ),
+    ).toBe(75);
+  });
+});

package/Tests/Utils/ObjectUtil.test.ts

@@ -0,0 +1,30 @@
+import ObjectUtil from "../../Utils/ObjectUtil";
+import { GlobalObject } from "../../Types/Object";
+
+describe("ObjectUtil.isEmpty", () => {
+  test("should return true for an object with no own keys", () => {
+    expect(ObjectUtil.isEmpty({} as GlobalObject)).toBe(true);
+  });
+
+  test("should return false when the object has keys", () => {
+    expect(ObjectUtil.isEmpty({ a: 1 } as unknown as GlobalObject)).toBe(false);
+  });
+
+  test("should return false when a key holds an undefined value", () => {
+    // The key still exists, so the object is not empty.
+    expect(
+      ObjectUtil.isEmpty({ a: undefined } as unknown as GlobalObject),
+    ).toBe(false);
+  });
+
+  test("should ignore inherited properties", () => {
+    const parent: GlobalObject = { inherited: true } as unknown as GlobalObject;
+    const child: GlobalObject = Object.create(parent) as GlobalObject;
+
+    expect(ObjectUtil.isEmpty(child)).toBe(true);
+  });
+
+  test("should treat an empty array as empty", () => {
+    expect(ObjectUtil.isEmpty([] as unknown as GlobalObject)).toBe(true);
+  });
+});

package/Tests/Utils/Slo/SloBurnRateRuleState.test.ts

@@ -0,0 +1,124 @@
+import SloStatus from "../../../Types/ServiceLevelObjective/SloStatus";
+import {
+  canSloFireBurnRateAlerts,
+  isBurnRateRuleFiring,
+} from "../../../Utils/Slo/SloBurnRateRuleState";
+
+const FIRED_AT: Date = new Date("2026-07-25T10:00:00.000Z");
+
+describe("SloBurnRateRuleState", () => {
+  describe("isBurnRateRuleFiring", () => {
+    it("is false for a rule that has never fired", () => {
+      expect(isBurnRateRuleFiring({})).toBe(false);
+      expect(
+        isBurnRateRuleFiring({
+          lastAlertCreatedAt: null,
+          lastAlertResolvedAt: null,
+        }),
+      ).toBe(false);
+    });
+
+    it("is true when a fire has never been resolved", () => {
+      expect(isBurnRateRuleFiring({ lastAlertCreatedAt: FIRED_AT })).toBe(true);
+    });
+
+    it("is false when the resolve is newer than the fire", () => {
+      expect(
+        isBurnRateRuleFiring({
+          lastAlertCreatedAt: FIRED_AT,
+          lastAlertResolvedAt: new Date("2026-07-25T10:30:00.000Z"),
+        }),
+      ).toBe(false);
+    });
+
+    it("is true when the rule re-fired after an older resolve", () => {
+      expect(
+        isBurnRateRuleFiring({
+          lastAlertCreatedAt: FIRED_AT,
+          lastAlertResolvedAt: new Date("2026-07-25T09:00:00.000Z"),
+        }),
+      ).toBe(true);
+    });
+
+    it("treats an equal-timestamp pair as resolved, not firing", () => {
+      /*
+       * The worker always writes the resolve strictly after the fire, so
+       * an equal pair can only be one lifecycle — leaving a red "Firing"
+       * pill on a rule with nothing open would be the worse error.
+       */
+      expect(
+        isBurnRateRuleFiring({
+          lastAlertCreatedAt: FIRED_AT,
+          lastAlertResolvedAt: new Date(FIRED_AT.getTime()),
+        }),
+      ).toBe(false);
+    });
+
+    it("is false when only a resolve is recorded", () => {
+      // Defensive: a resolve with no fire is not a firing state.
+      expect(isBurnRateRuleFiring({ lastAlertResolvedAt: FIRED_AT })).toBe(
+        false,
+      );
+    });
+  });
+
+  describe("canSloFireBurnRateAlerts", () => {
+    it("is true for a healthy, enabled SLO", () => {
+      expect(
+        canSloFireBurnRateAlerts({
+          isEnabled: true,
+          sloStatus: SloStatus.Healthy,
+        }),
+      ).toBe(true);
+    });
+
+    it("is true while the budget is at risk or exhausted — that is when rules fire", () => {
+      expect(
+        canSloFireBurnRateAlerts({
+          isEnabled: true,
+          sloStatus: SloStatus.AtRisk,
+        }),
+      ).toBe(true);
+      expect(
+        canSloFireBurnRateAlerts({
+          isEnabled: true,
+          sloStatus: SloStatus.BudgetExhausted,
+        }),
+      ).toBe(true);
+    });
+
+    it("is false for a disabled SLO", () => {
+      /*
+       * Disabling resolves every open alert without stamping the rule's
+       * lastAlertResolvedAt, so the rule columns alone would still read as
+       * firing.
+       */
+      expect(
+        canSloFireBurnRateAlerts({
+          isEnabled: false,
+          sloStatus: SloStatus.AtRisk,
+        }),
+      ).toBe(false);
+    });
+
+    it("is false for the two guard statuses that resolve without stamping", () => {
+      expect(
+        canSloFireBurnRateAlerts({
+          isEnabled: true,
+          sloStatus: SloStatus.Misconfigured,
+        }),
+      ).toBe(false);
+      expect(
+        canSloFireBurnRateAlerts({
+          isEnabled: true,
+          sloStatus: SloStatus.Paused,
+        }),
+      ).toBe(false);
+    });
+
+    it("stays optimistic when the fields were not loaded", () => {
+      // Never hide a genuinely firing rule because a fetch has not landed.
+      expect(canSloFireBurnRateAlerts({})).toBe(true);
+    });
+  });
+});