@oneuptime/common 11.6.1 → 11.6.2

package/Utils/NetworkSite/SiteStatusRollupUtil.ts

@@ -0,0 +1,97 @@
+/*
+ * Worst-of health rollup for a NetworkSite's device subtree.
+ *
+ * Each device contributes one MonitorStatus candidate and the highest
+ * priority number wins - MonitorStatus.priority is HIGHER = WORSE per the
+ * seeded rows (Operational 1 ... Offline 3), regardless of what the column
+ * docstring claims. Pure so the whole decision matrix is unit-testable.
+ */
+
+// One device's health inputs, denormalized by the rollup engine.
+export interface DeviceHealthState {
+  /*
+   * The MonitorStatus stamped by the monitor bridge (string form). When set
+   * together with its priority, it is the device's authoritative status.
+   */
+  currentMonitorStatusId?: string | null | undefined;
+  // Priority of that status row; missing when the row no longer exists.
+  monitorStatusPriority?: number | null | undefined;
+  // Last SNMP contact; drives the freshness fallback for unmonitored devices.
+  lastSeenAt?: Date | null | undefined;
+}
+
+// A project MonitorStatus row a freshness fallback can resolve to.
+export interface RollupStatusOption {
+  monitorStatusId: string;
+  priority: number;
+}
+
+export class SiteStatusRollupUtil {
+  // A device is considered alive when SNMP data arrived within this window.
+  public static readonly DEFAULT_FRESHNESS_WINDOW_IN_MINUTES: number = 15;
+
+  /*
+   * Returns the winning MonitorStatus id for a set of devices, or null when
+   * no device contributes anything (empty subtree, or freshness fallbacks
+   * unavailable because the project has no operational/offline rows) - the
+   * caller treats null as "leave the site's status untouched".
+   *
+   * Per device: a stamped monitor status (with a known priority) wins;
+   * otherwise lastSeenAt within the freshness window maps to the project's
+   * isOperationalState row and anything staler (or never seen) maps to the
+   * isOfflineState row. Priority ties keep the first contributor (stable).
+   */
+  public static worstStatus(data: {
+    deviceStates: Array<DeviceHealthState>;
+    operationalStatus?: RollupStatusOption | null | undefined;
+    offlineStatus?: RollupStatusOption | null | undefined;
+    now?: Date | undefined;
+    freshnessWindowInMinutes?: number | undefined;
+  }): string | null {
+    const now: Date = data.now || new Date();
+    const windowInMinutes: number =
+      data.freshnessWindowInMinutes ??
+      SiteStatusRollupUtil.DEFAULT_FRESHNESS_WINDOW_IN_MINUTES;
+    const windowInMs: number = windowInMinutes * 60 * 1000;
+
+    let winner: RollupStatusOption | null = null;
+
+    for (const device of data.deviceStates) {
+      let candidate: RollupStatusOption | null = null;
+
+      if (
+        device.currentMonitorStatusId &&
+        typeof device.monitorStatusPriority === "number" &&
+        Number.isFinite(device.monitorStatusPriority)
+      ) {
+        candidate = {
+          monitorStatusId: device.currentMonitorStatusId,
+          priority: device.monitorStatusPriority,
+        };
+      } else {
+        const lastSeenAtInMs: number | null = device.lastSeenAt
+          ? new Date(device.lastSeenAt).getTime()
+          : null;
+        const isFresh: boolean =
+          lastSeenAtInMs !== null &&
+          now.getTime() - lastSeenAtInMs <= windowInMs;
+
+        candidate = isFresh
+          ? data.operationalStatus || null
+          : data.offlineStatus || null;
+      }
+
+      if (!candidate) {
+        continue;
+      }
+
+      if (!winner || candidate.priority > winner.priority) {
+        winner = candidate;
+      }
+    }
+
+    return winner ? winner.monitorStatusId : null;
+  }
+}
+
+export default SiteStatusRollupUtil;

package/Utils/NetworkSite/SiteUptimeUtil.ts

@@ -0,0 +1,111 @@
+/*
+ * Uptime percentage over a NetworkSiteStatusTimeline window.
+ *
+ * Every row whose status is not flagged operational counts as downtime.
+ * Rows are clamped to the window, an open row (endsAt null) extends to the
+ * window end, and overlapping down rows are merged so no second is counted
+ * twice. Time not covered by any row counts as up - the timeline only gains
+ * rows once a rollup has run, and absence of evidence is not an outage.
+ */
+
+// One timeline row, denormalized with its status row's priority and flag.
+export interface SiteStatusTimelineRow {
+  monitorStatusId: string;
+  startsAt: Date;
+  endsAt: Date | null;
+  priority: number;
+  isOperationalState: boolean;
+}
+
+interface TimeInterval {
+  startInMs: number;
+  endInMs: number;
+}
+
+export class SiteUptimeUtil {
+  /*
+   * Percent of [windowStart, windowEnd) the site was NOT in a
+   * non-operational status. Returns 100 for an empty or inverted window.
+   * The result is exact (not rounded) and clamped to 0..100.
+   */
+  public static calculateUptimePercent(
+    rows: Array<SiteStatusTimelineRow>,
+    windowStart: Date,
+    windowEnd: Date,
+  ): number {
+    const windowStartInMs: number = windowStart.getTime();
+    const windowEndInMs: number = windowEnd.getTime();
+    const windowInMs: number = windowEndInMs - windowStartInMs;
+
+    if (!Number.isFinite(windowInMs) || windowInMs <= 0) {
+      return 100;
+    }
+
+    const downIntervals: Array<TimeInterval> = [];
+
+    for (const row of rows) {
+      if (row.isOperationalState) {
+        continue;
+      }
+
+      const rowStartInMs: number = new Date(row.startsAt).getTime();
+      const rowEndInMs: number = row.endsAt
+        ? new Date(row.endsAt).getTime()
+        : windowEndInMs;
+
+      if (!Number.isFinite(rowStartInMs) || !Number.isFinite(rowEndInMs)) {
+        continue;
+      }
+
+      const clampedStartInMs: number = Math.max(rowStartInMs, windowStartInMs);
+      const clampedEndInMs: number = Math.min(rowEndInMs, windowEndInMs);
+
+      if (clampedEndInMs <= clampedStartInMs) {
+        continue;
+      }
+
+      downIntervals.push({
+        startInMs: clampedStartInMs,
+        endInMs: clampedEndInMs,
+      });
+    }
+
+    const downInMs: number = SiteUptimeUtil.totalCoveredMs(downIntervals);
+
+    const uptimePercent: number = ((windowInMs - downInMs) / windowInMs) * 100;
+    return Math.min(100, Math.max(0, uptimePercent));
+  }
+
+  // Sum of interval lengths after merging overlaps.
+  private static totalCoveredMs(intervals: Array<TimeInterval>): number {
+    if (intervals.length === 0) {
+      return 0;
+    }
+
+    const sorted: Array<TimeInterval> = [...intervals].sort(
+      (a: TimeInterval, b: TimeInterval) => {
+        return a.startInMs - b.startInMs;
+      },
+    );
+
+    let totalInMs: number = 0;
+    let currentStartInMs: number = sorted[0]!.startInMs;
+    let currentEndInMs: number = sorted[0]!.endInMs;
+
+    for (let i: number = 1; i < sorted.length; i++) {
+      const interval: TimeInterval = sorted[i]!;
+      if (interval.startInMs <= currentEndInMs) {
+        currentEndInMs = Math.max(currentEndInMs, interval.endInMs);
+      } else {
+        totalInMs += currentEndInMs - currentStartInMs;
+        currentStartInMs = interval.startInMs;
+        currentEndInMs = interval.endInMs;
+      }
+    }
+
+    totalInMs += currentEndInMs - currentStartInMs;
+    return totalInMs;
+  }
+}
+
+export default SiteUptimeUtil;

package/Utils/Slo/SloStatusColor.ts

@@ -0,0 +1,54 @@
+import { Gray500, Green, Red, Yellow } from "../../Types/BrandColors";
+import Color from "../../Types/Color";
+import SloStatus from "../../Types/ServiceLevelObjective/SloStatus";
+
+/**
+ * The single source of truth for the SloStatus -> pill colour mapping.
+ *
+ * Healthy          -> Green
+ * At Risk          -> Yellow
+ * Budget Exhausted -> Red
+ * Misconfigured    -> Gray  (nothing to measure — not a reliability signal)
+ * Paused           -> Gray  (deliberately not being measured)
+ * unknown/unset    -> Gray  (the worker has not evaluated the SLO yet, so
+ *                            claiming any RAG colour would be a guess)
+ *
+ * Kept free of React so both the SLO pages and the dashboard SLO widget
+ * can import it, and so it is unit-testable without a DOM.
+ */
+export type GetSloStatusColorFunction = (
+  status: SloStatus | undefined | null,
+) => Color;
+
+export const getSloStatusColor: GetSloStatusColorFunction = (
+  status: SloStatus | undefined | null,
+): Color => {
+  if (status === SloStatus.Healthy) {
+    return Green;
+  }
+
+  if (status === SloStatus.AtRisk) {
+    return Yellow;
+  }
+
+  if (status === SloStatus.BudgetExhausted) {
+    return Red;
+  }
+
+  return Gray500;
+};
+
+/**
+ * Text for the status pill. An SLO the worker has not touched yet has a
+ * null `sloStatus`; render that as "Unknown" rather than defaulting to
+ * "Healthy", which would assert a reliability claim we cannot back.
+ */
+export type GetSloStatusTextFunction = (
+  status: SloStatus | undefined | null,
+) => string;
+
+export const getSloStatusText: GetSloStatusTextFunction = (
+  status: SloStatus | undefined | null,
+): string => {
+  return status || "Unknown";
+};