@oneuptime/common 12.0.14 → 12.0.16

package/Tests/Utils/NetworkDevice/DeviceHealthStateUtil.test.ts

@@ -0,0 +1,433 @@
+import { describe, expect, test } from "@jest/globals";
+import OneUptimeDate from "../../../Types/Date";
+import {
+  DeviceHealthCounts,
+  NetworkDeviceHealthState,
+  addDeviceHealth,
+  deviceAttentionCount,
+  deviceHealthState,
+  emptyDeviceHealthCounts,
+  mergeDeviceHealthCounts,
+  worstDeviceHealthState,
+} from "../../../Utils/NetworkDevice/DeviceHealthStateUtil";
+
+/*
+ * Issue #3320 — the rule that decides which SITES hold a device somebody
+ * has to look at.
+ *
+ * Everything the hierarchy view claims about an estate of 21,700 devices is
+ * this function summed up, so every branch of it is pinned here: what a
+ * monitor's verdict overrides, what a dark port does to a device that is
+ * otherwise answering, and — the one that matters most — what stays
+ * "unknown" instead of being quietly counted as either a failure or a
+ * success.
+ */
+
+const NOW: Date = OneUptimeDate.fromString("2026-08-21T12:00:00.000Z");
+
+type MinutesAgoFunction = (minutes: number) => Date;
+
+const minutesAgo: MinutesAgoFunction = (minutes: number): Date => {
+  return new Date(NOW.getTime() - minutes * 60 * 1000);
+};
+
+describe("deviceHealthState — a monitor's verdict is the system of record", () => {
+  test("a status the ladder does not call offline makes the device up, whatever the poll says", () => {
+    expect(
+      deviceHealthState(
+        {
+          monitorStatusIsOffline: false,
+          // The SNMP side would say Down on its own.
+          isReachable: false,
+          lastPolledAt: minutesAgo(1),
+        },
+        NOW,
+      ),
+    ).toBe("healthy");
+  });
+
+  test("an offline monitor status makes the device down, whatever the poll says", () => {
+    expect(
+      deviceHealthState(
+        {
+          monitorStatusIsOffline: true,
+          isReachable: true,
+          lastPolledAt: minutesAgo(1),
+          lastSeenAt: minutesAgo(1),
+        },
+        NOW,
+      ),
+    ).toBe("down");
+  });
+
+  test("a monitor-backed device that is up can still be degraded by its ports", () => {
+    expect(
+      deviceHealthState(
+        { monitorStatusIsOffline: false, interfacesDown: 3 },
+        NOW,
+      ),
+    ).toBe("degraded");
+  });
+
+  /*
+   * `undefined` means "no monitor is attached", which is the ordinary case
+   * for an SNMP-walked switch. It must not be read as a verdict of any kind
+   * — doing so would either paint every switch in the estate down or hide
+   * every real outage behind a stamped green.
+   */
+  test("an absent monitor status defers to reachability rather than deciding", () => {
+    expect(
+      deviceHealthState(
+        {
+          monitorStatusIsOffline: undefined,
+          isReachable: false,
+          lastPolledAt: minutesAgo(1),
+        },
+        NOW,
+      ),
+    ).toBe("down");
+    expect(
+      deviceHealthState(
+        {
+          monitorStatusIsOffline: null,
+          isReachable: true,
+          lastPolledAt: minutesAgo(1),
+          lastSeenAt: minutesAgo(1),
+        },
+        NOW,
+      ),
+    ).toBe("healthy");
+  });
+});
+
+/*
+ * The rule that this module exists for, and the one an earlier revision got
+ * wrong: MonitorStatus is a LADDER (Operational 1 ... Offline 3), not a
+ * pair. Reading the operational end counted every "Degraded" device as down
+ * on the site card while the map you reach by clicking that card drew the
+ * same device green — the two halves of the product describing different
+ * networks, which is precisely what a shared classifier is for.
+ *
+ * NetworkDeviceTopology.ts resolves the ladder with
+ * `status.isOfflineState ? "down" : "up"`. These pin the same answer here.
+ */
+describe("the MonitorStatus ladder — a middle rung is not an outage", () => {
+  type LadderRow = {
+    name: string;
+    isOperationalState: boolean;
+    isOfflineState: boolean;
+  };
+
+  // The seeded project rows, plus the middle rung that broke the old rule.
+  const LADDER: Array<LadderRow> = [
+    { name: "Operational", isOperationalState: true, isOfflineState: false },
+    { name: "Degraded", isOperationalState: false, isOfflineState: false },
+    { name: "Maintenance", isOperationalState: false, isOfflineState: false },
+    { name: "Offline", isOperationalState: false, isOfflineState: true },
+  ];
+
+  // Exactly what NetworkDeviceTopology.ts does with a status row.
+  function mapVerdict(row: LadderRow): "up" | "down" {
+    return row.isOfflineState ? "down" : "up";
+  }
+
+  test.each(LADDER)(
+    "$name: the rollup agrees with the map about up/down",
+    (row: LadderRow) => {
+      const state: NetworkDeviceHealthState = deviceHealthState(
+        { monitorStatusIsOffline: row.isOfflineState },
+        NOW,
+      );
+      const rollupSaysDown: boolean = state === "down";
+      expect(rollupSaysDown).toBe(mapVerdict(row) === "down");
+    },
+  );
+
+  test("a Degraded device with no dark ports is healthy, not down", () => {
+    expect(deviceHealthState({ monitorStatusIsOffline: false }, NOW)).toBe(
+      "healthy",
+    );
+  });
+
+  /*
+   * The regression in one assertion. If anybody re-wires this input to the
+   * operational flag, a Degraded row (isOperationalState false) starts
+   * reading "down" here and this fails.
+   */
+  test("only the OFFLINE rung produces down", () => {
+    const downRungs: Array<string> = LADDER.filter((row: LadderRow) => {
+      return (
+        deviceHealthState(
+          { monitorStatusIsOffline: row.isOfflineState },
+          NOW,
+        ) === "down"
+      );
+    }).map((row: LadderRow) => {
+      return row.name;
+    });
+    expect(downRungs).toEqual(["Offline"]);
+  });
+});
+
+describe("deviceHealthState — reachability, when nothing is stamped", () => {
+  test("the probe asked and got nothing: down", () => {
+    expect(
+      deviceHealthState(
+        { isReachable: false, lastPolledAt: minutesAgo(2) },
+        NOW,
+      ),
+    ).toBe("down");
+  });
+
+  test("the probe asked and the device answered: healthy", () => {
+    expect(
+      deviceHealthState(
+        {
+          isReachable: true,
+          lastPolledAt: minutesAgo(2),
+          lastSeenAt: minutesAgo(2),
+        },
+        NOW,
+      ),
+    ).toBe("healthy");
+  });
+
+  /*
+   * The whole point of DeviceReachabilityUtil: a fleet whose real poll
+   * cadence exceeds the old fifteen-minute freshness window is not an
+   * outage. A device that answered two hours ago and has not been asked
+   * since is still up, and the site above it must not turn red for it.
+   */
+  test("a stale but successful poll is still up, not down", () => {
+    expect(
+      deviceHealthState(
+        {
+          isReachable: true,
+          lastPolledAt: minutesAgo(600),
+          lastSeenAt: minutesAgo(600),
+          pollingIntervalInMinutes: 5,
+        },
+        NOW,
+      ),
+    ).toBe("healthy");
+  });
+
+  test("a device nothing has ever polled is unknown, not a failure", () => {
+    expect(deviceHealthState({}, NOW)).toBe("unknown");
+    expect(
+      deviceHealthState({ isReachable: null, interfacesDown: 4 }, NOW),
+    ).toBe("unknown");
+  });
+
+  test("polled but never once answered is down, not pending", () => {
+    expect(deviceHealthState({ lastPolledAt: minutesAgo(30) }, NOW)).toBe(
+      "down",
+    );
+  });
+});
+
+describe("deviceHealthState — degraded", () => {
+  test("an up device with dark ports is degraded", () => {
+    expect(
+      deviceHealthState(
+        {
+          isReachable: true,
+          lastPolledAt: minutesAgo(1),
+          lastSeenAt: minutesAgo(1),
+          interfacesDown: 1,
+        },
+        NOW,
+      ),
+    ).toBe("degraded");
+  });
+
+  /*
+   * Interface counts on a device that does not answer are by definition
+   * stale, so "down" wins. A device reported as both would otherwise be
+   * counted in the softer bucket and drop out of a "Down" filter.
+   */
+  test("down beats degraded when both could apply", () => {
+    expect(
+      deviceHealthState(
+        {
+          isReachable: false,
+          lastPolledAt: minutesAgo(1),
+          interfacesDown: 9,
+        },
+        NOW,
+      ),
+    ).toBe("down");
+  });
+
+  test("zero, negative and non-finite interface counts never degrade", () => {
+    const base: {
+      isReachable: boolean;
+      lastPolledAt: Date;
+      lastSeenAt: Date;
+    } = {
+      isReachable: true,
+      lastPolledAt: minutesAgo(1),
+      lastSeenAt: minutesAgo(1),
+    };
+    expect(deviceHealthState({ ...base, interfacesDown: 0 }, NOW)).toBe(
+      "healthy",
+    );
+    expect(deviceHealthState({ ...base, interfacesDown: -2 }, NOW)).toBe(
+      "healthy",
+    );
+    expect(deviceHealthState({ ...base, interfacesDown: NaN }, NOW)).toBe(
+      "healthy",
+    );
+    expect(deviceHealthState({ ...base, interfacesDown: null }, NOW)).toBe(
+      "healthy",
+    );
+  });
+
+  test("a missing device row is unknown rather than an exception", () => {
+    expect(deviceHealthState(null, NOW)).toBe("unknown");
+    expect(deviceHealthState(undefined, NOW)).toBe("unknown");
+  });
+});
+
+describe("tallies", () => {
+  test("an empty tally is all zeroes and a fresh object each time", () => {
+    const first: DeviceHealthCounts = emptyDeviceHealthCounts();
+    const second: DeviceHealthCounts = emptyDeviceHealthCounts();
+    expect(first).toEqual({
+      total: 0,
+      down: 0,
+      degraded: 0,
+      healthy: 0,
+      unknown: 0,
+    });
+    first.down = 5;
+    expect(second.down).toBe(0);
+  });
+
+  test("adding a device moves total and exactly one state", () => {
+    const counts: DeviceHealthCounts = emptyDeviceHealthCounts();
+    addDeviceHealth(counts, "down");
+    addDeviceHealth(counts, "degraded");
+    addDeviceHealth(counts, "degraded");
+    addDeviceHealth(counts, "healthy");
+    addDeviceHealth(counts, "unknown");
+    expect(counts).toEqual({
+      total: 5,
+      down: 1,
+      degraded: 2,
+      healthy: 1,
+      unknown: 1,
+    });
+  });
+
+  test("the four states always sum to the total", () => {
+    const counts: DeviceHealthCounts = emptyDeviceHealthCounts();
+    const states: Array<NetworkDeviceHealthState> = [
+      "down",
+      "healthy",
+      "healthy",
+      "unknown",
+      "degraded",
+      "healthy",
+    ];
+    for (const state of states) {
+      addDeviceHealth(counts, state);
+    }
+    expect(
+      counts.down + counts.degraded + counts.healthy + counts.unknown,
+    ).toBe(counts.total);
+  });
+
+  test("merging adds field by field without touching either input", () => {
+    const first: DeviceHealthCounts = {
+      total: 3,
+      down: 1,
+      degraded: 0,
+      healthy: 2,
+      unknown: 0,
+    };
+    const second: DeviceHealthCounts = {
+      total: 4,
+      down: 0,
+      degraded: 2,
+      healthy: 1,
+      unknown: 1,
+    };
+    expect(mergeDeviceHealthCounts(first, second)).toEqual({
+      total: 7,
+      down: 1,
+      degraded: 2,
+      healthy: 3,
+      unknown: 1,
+    });
+    expect(first.total).toBe(3);
+    expect(second.total).toBe(4);
+  });
+
+  test("attention is exactly down plus degraded — never unknown", () => {
+    expect(
+      deviceAttentionCount({
+        total: 10,
+        down: 2,
+        degraded: 3,
+        healthy: 1,
+        unknown: 4,
+      }),
+    ).toBe(5);
+    expect(deviceAttentionCount(emptyDeviceHealthCounts())).toBe(0);
+  });
+});
+
+describe("worstDeviceHealthState", () => {
+  test("one down device outranks any number of healthy ones", () => {
+    expect(
+      worstDeviceHealthState({
+        total: 40,
+        down: 1,
+        degraded: 5,
+        healthy: 34,
+        unknown: 0,
+      }),
+    ).toBe("down");
+  });
+
+  test("degraded outranks healthy", () => {
+    expect(
+      worstDeviceHealthState({
+        total: 10,
+        down: 0,
+        degraded: 1,
+        healthy: 9,
+        unknown: 0,
+      }),
+    ).toBe("degraded");
+  });
+
+  test("healthy outranks unknown — one confirmed answer is a verdict", () => {
+    expect(
+      worstDeviceHealthState({
+        total: 5,
+        down: 0,
+        degraded: 0,
+        healthy: 1,
+        unknown: 4,
+      }),
+    ).toBe("healthy");
+  });
+
+  test("a subtree of nothing but never-polled devices is unknown", () => {
+    expect(
+      worstDeviceHealthState({
+        total: 3,
+        down: 0,
+        degraded: 0,
+        healthy: 0,
+        unknown: 3,
+      }),
+    ).toBe("unknown");
+  });
+
+  test("an empty subtree is unknown, not healthy", () => {
+    expect(worstDeviceHealthState(emptyDeviceHealthCounts())).toBe("unknown");
+  });
+});

package/Tests/Utils/NetworkDiscovery/UnclaimedScanDiagnosis.test.ts

@@ -0,0 +1,214 @@
+import {
+  MAX_SCAN_STATUS_MESSAGE_LENGTH,
+  UNCLAIMED_PENDING_MINUTES,
+  UnclaimedScanProbeState,
+  buildUnclaimedScanDiagnosis,
+} from "../../../Utils/NetworkDiscovery/UnclaimedScanDiagnosis";
+import OneUptimeDate from "../../../Types/Date";
+import { describe, expect, test } from "@jest/globals";
+
+/*
+ * The sentence a stuck discovery scan gets to say for itself.
+ *
+ * A scan leaves "Pending" only when a probe asks for it. When no probe ever
+ * does, nothing times out and nothing fails — the row simply never moves, and
+ * before this existed the product said nothing at all about it. OneUptime
+ * issue #3287 is that silence: four scans submitted over an hour, all
+ * "Pending", an em-dash where the result goes, and no way to tell a scan
+ * queued a second ago from one no probe will ever pick up.
+ *
+ * So these tests are about the WORDS, not a state machine: whether an operator
+ * reading the row learns which of the two very different problems they have,
+ * and whether the sentence survives the varchar(500) column it is written to.
+ */
+
+const disconnectedProbe: UnclaimedScanProbeState = {
+  probeName: "Datacentre Probe",
+  isProbeConnected: false,
+  lastAliveAt: OneUptimeDate.getSomeHoursAgo(6),
+};
+
+const connectedProbe: UnclaimedScanProbeState = {
+  probeName: "Datacentre Probe",
+  isProbeConnected: true,
+  lastAliveAt: OneUptimeDate.getCurrentDate(),
+};
+
+describe("buildUnclaimedScanDiagnosis — the probe is not connected", () => {
+  test("names the probe the operator chose", () => {
+    expect(buildUnclaimedScanDiagnosis(disconnectedProbe)).toContain(
+      'Probe "Datacentre Probe"',
+    );
+  });
+
+  test("says the probe is not connected, which is the actual fault", () => {
+    expect(buildUnclaimedScanDiagnosis(disconnectedProbe)).toContain(
+      "is not connected to OneUptime",
+    );
+  });
+
+  /*
+   * "Last seen 6 hours ago" is the difference between "my probe just
+   * restarted" and "that probe has been gone since the upgrade".
+   */
+  test("says when the probe was last seen", () => {
+    expect(buildUnclaimedScanDiagnosis(disconnectedProbe)).toContain(
+      "It was last seen",
+    );
+  });
+
+  test("a probe that has never connected says exactly that, not 'last seen never'", () => {
+    const message: string = buildUnclaimedScanDiagnosis({
+      probeName: "Brand New Probe",
+      isProbeConnected: false,
+      lastAliveAt: null,
+    });
+
+    expect(message).toContain("It has never connected.");
+    expect(message).not.toContain("last seen");
+  });
+
+  test("a missing lastAlive is treated the same as never connecting", () => {
+    expect(
+      buildUnclaimedScanDiagnosis({
+        isProbeConnected: false,
+      }),
+    ).toContain("It has never connected.");
+  });
+
+  /*
+   * The scan is annotated, not failed, so the operator needs to know they do
+   * not have to re-create it.
+   */
+  test("promises the scan still runs once the probe returns", () => {
+    expect(buildUnclaimedScanDiagnosis(disconnectedProbe)).toContain(
+      "as soon as the probe reconnects",
+    );
+  });
+});
+
+describe("buildUnclaimedScanDiagnosis — the probe IS connected", () => {
+  /*
+   * A completely different problem with a completely different fix: the probe
+   * is running and authenticating, but its discovery job is not claiming
+   * scans — an old image, a wedged sweep, or a probe that can reach the
+   * heartbeat route but not the probe-ingest one.
+   */
+  test("does not blame the connection", () => {
+    const message: string = buildUnclaimedScanDiagnosis(connectedProbe);
+
+    expect(message).toContain("is connected but has not picked this scan up");
+    expect(message).not.toContain("is not connected");
+  });
+
+  test("names the two things worth checking", () => {
+    const message: string = buildUnclaimedScanDiagnosis(connectedProbe);
+
+    expect(message).toContain("version that supports");
+    expect(message).toContain("probe-ingest");
+  });
+
+  test("quotes the threshold it actually waited for", () => {
+    expect(buildUnclaimedScanDiagnosis(connectedProbe)).toContain(
+      `${UNCLAIMED_PENDING_MINUTES} minutes`,
+    );
+  });
+
+  test("the two branches are genuinely different sentences", () => {
+    expect(buildUnclaimedScanDiagnosis(connectedProbe)).not.toBe(
+      buildUnclaimedScanDiagnosis(disconnectedProbe),
+    );
+  });
+});
+
+describe("buildUnclaimedScanDiagnosis — a probe with no readable name", () => {
+  test("falls back to a phrase that still reads as a sentence", () => {
+    const message: string = buildUnclaimedScanDiagnosis({
+      isProbeConnected: false,
+      lastAliveAt: null,
+    });
+
+    expect(message).toContain("The assigned probe is not connected");
+    expect(message).not.toContain('Probe ""');
+  });
+
+  test("an empty-string name is treated as no name", () => {
+    expect(
+      buildUnclaimedScanDiagnosis({
+        probeName: "",
+        isProbeConnected: true,
+      }),
+    ).toContain("The assigned probe");
+  });
+});
+
+describe("buildUnclaimedScanDiagnosis — it has to fit the column", () => {
+  /*
+   * statusMessage is a varchar(500) and this message is written through the
+   * full update pipeline, which does NOT clamp. An over-long value throws, and
+   * the diagnosis is lost precisely when it is most needed.
+   */
+  test("the column ceiling is the one the model declares", () => {
+    expect(MAX_SCAN_STATUS_MESSAGE_LENGTH).toBe(500);
+  });
+
+  test("every message fits, for both branches", () => {
+    for (const probeState of [disconnectedProbe, connectedProbe]) {
+      expect(
+        buildUnclaimedScanDiagnosis(probeState).length,
+      ).toBeLessThanOrEqual(MAX_SCAN_STATUS_MESSAGE_LENGTH);
+    }
+  });
+
+  /*
+   * A probe name is a ShortText column, so 100 characters is the real worst
+   * case. Feeding well past it proves the truncation is what bounds the
+   * message rather than the caller's good manners.
+   */
+  test("an absurdly long probe name cannot overflow the column", () => {
+    const longName: string = "N".repeat(400);
+
+    for (const isProbeConnected of [true, false]) {
+      const message: string = buildUnclaimedScanDiagnosis({
+        probeName: longName,
+        isProbeConnected: isProbeConnected,
+        lastAliveAt: OneUptimeDate.getSomeHoursAgo(200),
+      });
+
+      expect(message.length).toBeLessThanOrEqual(
+        MAX_SCAN_STATUS_MESSAGE_LENGTH,
+      );
+    }
+  });
+
+  test("a long name is cut with an ellipsis rather than silently dropped", () => {
+    const message: string = buildUnclaimedScanDiagnosis({
+      probeName: "N".repeat(400),
+      isProbeConnected: false,
+    });
+
+    expect(message).toContain("NNN");
+    expect(message).toContain("…");
+  });
+
+  test("a name that fits is left exactly as the operator typed it", () => {
+    expect(
+      buildUnclaimedScanDiagnosis({
+        probeName: "core-sw-probe-01",
+        isProbeConnected: false,
+      }),
+    ).toContain('Probe "core-sw-probe-01"');
+  });
+});
+
+describe("the grace period", () => {
+  /*
+   * The probe polls every minute, so this is a count of consecutive failed
+   * polls. Too short and a probe redeploy annotates every queued scan; too
+   * long and the operator has given up before the product says anything.
+   */
+  test("is long enough to ride out a probe restart and short enough to be useful", () => {
+    expect(UNCLAIMED_PENDING_MINUTES).toBeGreaterThanOrEqual(5);
+    expect(UNCLAIMED_PENDING_MINUTES).toBeLessThanOrEqual(60);
+  });
+});