@oneuptime/common 12.0.32 → 12.0.34

package/Utils/NetworkDiscovery/PingMonitorBuilder.ts

@@ -93,6 +93,41 @@ export interface BuildPingMonitorData {
   seedIds: MonitorCriteriaSeedIds;
 }
 
+/**
+ * Where a Ping monitor is being built FROM. The sentence it writes into the
+ * monitor's description is the only thing that differs, and it matters: an
+ * operator reading the monitor list months later should be told whether a
+ * scan, a form, or a bulk action put it there.
+ */
+export enum PingMonitorOrigin {
+  // A host that answered a discovery sweep's ping but not its SNMP probe.
+  DiscoveryImport = "DiscoveryImport",
+  // The device create form, with "create a Ping monitor" ticked.
+  DeviceCreateForm = "DeviceCreateForm",
+  // The "Create Ping Monitor" button on a device's Overview or Monitors page.
+  DevicePage = "DevicePage",
+  // The device list's bulk "Create Ping Monitors" action.
+  BulkAction = "BulkAction",
+}
+
+export interface BuildPingMonitorForAddressData {
+  projectId: ObjectID;
+  /*
+   * The device's address as recorded on the device — an IP or a hostname.
+   * NetworkDevice.hostname is free text and required, so this is never empty
+   * for a real device; it is still validated because the bulk action and the
+   * create form both hand over whatever the operator typed.
+   */
+  address: string;
+  /*
+   * The name of the NetworkDevice this monitor will be bound to, so the two
+   * read as a pair in a monitor list that also contains unrelated monitors.
+   */
+  deviceName: string;
+  seedIds: MonitorCriteriaSeedIds;
+  origin: PingMonitorOrigin;
+}
+
 /**
  * The monitor's name: "Ping <device name>", clamped to the column.
  *
@@ -157,24 +192,54 @@ function suppressIncidentCreation(step: MonitorStep): void {
 }
 
 /**
- * One ping-only discovered host -> the Ping monitor that will report its
- * health once bound to the device through `NetworkDevice.monitorId`.
+ * The sentence a provisioned monitor carries so its origin is legible later.
+ * Exported so the surfaces that build one can be tested against the exact
+ * wording rather than a paraphrase.
+ */
+export function buildPingMonitorDescription(data: {
+  address: string;
+  origin: PingMonitorOrigin;
+}): string {
+  const reachability: string = `Reachability for ${data.address}`;
+
+  switch (data.origin) {
+    case PingMonitorOrigin.DiscoveryImport:
+      return `${reachability}, created when this device was imported from a network discovery scan. The device answered ping but not SNMP, so this monitor is what reports whether it is up.`;
+    case PingMonitorOrigin.DeviceCreateForm:
+      return `${reachability}, created with this network device. The device is monitor-backed — nothing polls it over SNMP — so this monitor is what reports whether it is up.`;
+    case PingMonitorOrigin.BulkAction:
+      return `${reachability}, created by the device list's "Create Ping Monitors" action. The device is monitor-backed — nothing polls it over SNMP — so this monitor is what reports whether it is up.`;
+    case PingMonitorOrigin.DevicePage:
+    default:
+      return `${reachability}, created from this network device's page. The device is monitor-backed — nothing polls it over SNMP — so this monitor is what reports whether it is up.`;
+  }
+}
+
+/**
+ * One device address -> the Ping monitor that will report the device's
+ * health once bound to it through `NetworkDevice.monitorId`.
  *
- * The caller creates this monitor FIRST, then creates the device carrying the
- * new monitor's id: `NetworkDeviceService.onCreateSuccess` stamps the
- * monitor's current status onto the device at bind time, so the device's
- * status pill resolves on the first render rather than waiting for the
- * monitor's next status CHANGE (which on a healthy network may never come —
- * that was OneUptime/oneuptime#3392).
+ * This is the shape every provisioning surface shares: discovery import, the
+ * device create form, the "Create Ping Monitor" button on a device's page and
+ * the bulk action on the device list. They differ only in where the address
+ * and the name come from and in the origin sentence; the monitor itself —
+ * type, interval, criteria, incident suppression — is identical, which is
+ * what lets an operator treat every provisioned monitor the same way.
+ *
+ * Order of operations is the caller's: discovery creates the monitor FIRST
+ * and then the device carrying its id (so the create-time stamp resolves the
+ * pill immediately), while the create form and the bulk action create or
+ * already have the device and bind afterwards — which re-stamps through
+ * `NetworkDeviceService.onUpdateSuccess`, so the pill resolves just the same.
  */
-export function buildPingMonitorForDiscoveredHost(
-  data: BuildPingMonitorData,
+export function buildPingMonitorForAddress(
+  data: BuildPingMonitorForAddressData,
 ): Monitor {
-  const address: string = (data.host?.ipAddress || "").trim();
+  const address: string = (data.address || "").trim();
 
   if (!address) {
     throw new Error(
-      "A discovered host needs an address before a Ping monitor can be built for it.",
+      "A device needs an address before a Ping monitor can be built for it.",
     );
   }
 
@@ -182,7 +247,10 @@ export function buildPingMonitorForDiscoveredHost(
 
   monitor.projectId = new ObjectID(data.projectId.toString());
   monitor.name = buildPingMonitorName(data.deviceName);
-  monitor.description = `Reachability for ${address}, created when this device was imported from a network discovery scan. The device answered ping but not SNMP, so this monitor is what reports whether it is up.`;
+  monitor.description = buildPingMonitorDescription({
+    address: address,
+    origin: data.origin,
+  });
   monitor.monitorType = MonitorType.Ping;
   monitor.monitoringInterval = PING_MONITOR_INTERVAL;
 
@@ -213,3 +281,37 @@ export function buildPingMonitorForDiscoveredHost(
 
   return monitor;
 }
+
+/**
+ * One ping-only discovered host -> the Ping monitor that will report its
+ * health once bound to the device through `NetworkDevice.monitorId`.
+ *
+ * The caller creates this monitor FIRST, then creates the device carrying the
+ * new monitor's id: `NetworkDeviceService.onCreateSuccess` stamps the
+ * monitor's current status onto the device at bind time, so the device's
+ * status pill resolves on the first render rather than waiting for the
+ * monitor's next status CHANGE (which on a healthy network may never come —
+ * that was OneUptime/oneuptime#3392).
+ *
+ * A thin adapter over `buildPingMonitorForAddress`: the only thing a
+ * discovered host contributes is its address.
+ */
+export function buildPingMonitorForDiscoveredHost(
+  data: BuildPingMonitorData,
+): Monitor {
+  const address: string = (data.host?.ipAddress || "").trim();
+
+  if (!address) {
+    throw new Error(
+      "A discovered host needs an address before a Ping monitor can be built for it.",
+    );
+  }
+
+  return buildPingMonitorForAddress({
+    projectId: data.projectId,
+    address: address,
+    deviceName: data.deviceName,
+    seedIds: data.seedIds,
+    origin: PingMonitorOrigin.DiscoveryImport,
+  });
+}

package/Utils/NetworkSite/SiteStatusRollupUtil.ts

@@ -1,6 +1,7 @@
 import DeviceReachabilityUtil, {
   NetworkDeviceReachability,
 } from "../NetworkDevice/DeviceReachabilityUtil";
+import { NetworkDeviceMonitoringMethodUtil } from "../../Types/NetworkDevice/NetworkDeviceMonitoringMethod";
 import SiteHealthRollupPolicy, {
   DefaultSiteOfflineThresholdPercent,
 } from "../../Types/NetworkSite/SiteHealthRollupPolicy";
@@ -25,14 +26,26 @@ import SiteHealthRollupPolicy, {
  *
  * Both policies agree on which devices get a vote at all: a device that has
  * never reported anything is not evidence of an outage and is skipped by
- * each of them.
+ * each of them. And both agree on what a device's vote IS: for a
+ * monitor-backed device the stamped MonitorStatus, for a probe-polled one
+ * the outcome of its last poll — the stamp on a probe-polled device is
+ * informational (see the field docs), the same precedence the device list
+ * pill, the site card and the map apply.
  */
 
 // 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.
+   * together with its priority ON A MONITOR-BACKED DEVICE, it is the
+   * device's authoritative status.
+   *
+   * A probe-polled device can carry one too — a Network Device monitor
+   * watching its walk stamps it, and an "interface down → Offline" criterion
+   * will stamp Offline on a switch that answers every ping. Its health
+   * source is the poll (`isReachable`, which is what its own pill reads), so
+   * the stamp is ignored here for it, or one dark port would turn a site of
+   * answering devices offline while every row under it reads Up.
    */
   currentMonitorStatusId?: string | null | undefined;
   // Priority of that status row; missing when the row no longer exists.
@@ -50,16 +63,32 @@ export interface DeviceHealthState {
    */
   monitorStatusIsOperational?: boolean | null | undefined;
   /*
-   * The SNMP fallback for devices no monitor stamps, resolved by the shared
-   * DeviceReachabilityUtil rule: the OUTCOME of the last poll, not the age
-   * of the last success. Rolling a site up from freshness alone is what
-   * turned "the probe is behind on a 900-device fleet" into a red site card
-   * over devices that were all answering.
+   * The poll verdict for probe-polled devices, resolved by the shared
+   * DeviceReachabilityUtil rule: the OUTCOME of the last poll (ping, or the
+   * SNMP walk), not the age of the last success. Rolling a site up from
+   * freshness alone is what turned "the probe is behind on a 900-device
+   * fleet" into a red site card over devices that were all answering.
    */
   isReachable?: boolean | null | undefined;
   lastPolledAt?: Date | null | undefined;
   lastSeenAt?: Date | null | undefined;
   pollingIntervalInMinutes?: number | null | undefined;
+  /*
+   * How this device's health is established. NULL, empty and anything
+   * unrecognised read as Probe — see NetworkDeviceMonitoringMethodUtil.parse,
+   * which is why an omitted value keeps every existing caller on the poll
+   * rule unchanged.
+   *
+   * Load-bearing twice. It decides whether the stamped status above is the
+   * device's vote at all (only for a monitor-backed device). And a
+   * monitor-backed device (monitoringMethod "Monitor") that has no stamp
+   * yet — or whose stamped row could not be resolved — has poll columns
+   * that mean nothing (NULL, or the last thing a probe found before it
+   * stopped asking). The shared rule reads it as Pending and both policies
+   * skip it, exactly as they skip a never-polled probe device, rather than
+   * letting a months-old lastSeenAt cast a vote against the site.
+   */
+  monitoringMethod?: string | null | undefined;
   /*
    * How many real devices this entry stands for.
    *
@@ -118,13 +147,13 @@ export class SiteStatusRollupUtil {
    * 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 the device's SNMP reachability maps Up to the project's
-   * isOperationalState row and Down to its isOfflineState row. A device
-   * that has never been polled contributes nothing at all - it is not
-   * evidence of an outage, and counting it as one used to pin a site red
-   * for as long as it took the first walk to land. Priority ties keep the
-   * first contributor (stable).
+   * Per device: on a monitor-backed device a stamped monitor status (with a
+   * known priority) is the vote; otherwise the device's poll reachability
+   * maps Up to the project's isOperationalState row and Down to its
+   * isOfflineState row. A device that has never been polled contributes
+   * nothing at all - it is not evidence of an outage, and counting it as
+   * one used to pin a site red for as long as it took the first poll to
+   * land. Priority ties keep the first contributor (stable).
    */
   public static worstStatus(data: {
     deviceStates: Array<DeviceHealthState>;
@@ -148,6 +177,7 @@ export class SiteStatusRollupUtil {
       let candidate: RollupStatusOption | null = null;
 
       if (
+        SiteStatusRollupUtil.isStampAuthoritative(device) &&
         device.currentMonitorStatusId &&
         typeof device.monitorStatusPriority === "number" &&
         Number.isFinite(device.monitorStatusPriority)
@@ -200,12 +230,12 @@ export class SiteStatusRollupUtil {
    * How the subtree splits between operational and not, in DEVICES rather
    * than in buckets.
    *
-   * A device counts as non-operational when its stamped MonitorStatus is not
-   * the operational one, or - for devices no monitor stamps - when its SNMP
-   * reachability is Down. Never-reported devices are excluded from both the
-   * numerator and the denominator, so a region half-way through its first
-   * discovery walk is scored on the half that has answered rather than
-   * marked down for the half that has not.
+   * A monitor-backed device counts as non-operational when its stamped
+   * MonitorStatus is not the operational one; a probe-polled device when its
+   * poll reachability is Down. Never-reported devices are excluded from both
+   * the numerator and the denominator, so a region half-way through its
+   * first discovery walk is scored on the half that has answered rather
+   * than marked down for the half that has not.
    */
   public static deviceHealthShare(data: {
     deviceStates: Array<DeviceHealthState>;
@@ -238,6 +268,7 @@ export class SiteStatusRollupUtil {
       const count: number = SiteStatusRollupUtil.deviceCountOf(device);
 
       if (
+        SiteStatusRollupUtil.isStampAuthoritative(device) &&
         device.currentMonitorStatusId &&
         typeof device.monitorStatusIsOperational === "boolean"
       ) {
@@ -415,6 +446,19 @@ export class SiteStatusRollupUtil {
     return Math.floor(value);
   }
 
+  /*
+   * Whether this device's stamped MonitorStatus is its vote — true only for
+   * a monitor-backed device. One gate for both policies, so the same fleet
+   * cannot read differently depending on which one a site uses; and the
+   * same gate DeviceHealthStateUtil and the topology map apply, so the site
+   * card, the map and this rollup describe one network.
+   */
+  private static isStampAuthoritative(device: DeviceHealthState): boolean {
+    return NetworkDeviceMonitoringMethodUtil.isMonitorBacked(
+      device.monitoringMethod,
+    );
+  }
+
   private static deviceCountOf(device: DeviceHealthState): number {
     if (
       typeof device.deviceCount !== "number" ||
@@ -436,6 +480,8 @@ export class SiteStatusRollupUtil {
         lastPolledAt: device.lastPolledAt,
         lastSeenAt: device.lastSeenAt,
         pollingIntervalInMinutes: device.pollingIntervalInMinutes,
+        // See the field docs: decides whether the columns above mean anything.
+        monitoringMethod: device.monitoringMethod,
       },
       now,
     );

package/Utils/NetworkSite/TypeHierarchyUtil.ts

@@ -0,0 +1,313 @@
+import NetworkSiteType from "../../Models/DatabaseModels/NetworkSiteType";
+
+export interface NetworkSiteTypeHierarchyNode {
+  networkSiteType: NetworkSiteType;
+  depth: number;
+  children: Array<NetworkSiteTypeHierarchyNode>;
+}
+
+export interface NetworkSiteTypeHierarchyIndex {
+  byId: Map<string, NetworkSiteType>;
+  childrenByParentId: Map<string | null, Array<NetworkSiteType>>;
+}
+
+/*
+ * Network site types describe the shape of a project's site tree. Keep the
+ * read-side helpers defensive: a direct database write or a partially applied
+ * migration can still leave an orphan or a cycle, and neither should make a
+ * settings page hang or hide a type from its operator.
+ */
+export default class NetworkSiteTypeHierarchyUtil {
+  public static getParentId(networkSiteType: NetworkSiteType): string | null {
+    const parentId: string | null =
+      networkSiteType.parentNetworkSiteTypeId?.toString() ||
+      networkSiteType.parentNetworkSiteType?.id?.toString() ||
+      null;
+
+    if (
+      parentId &&
+      parentId.toLowerCase() === networkSiteType.id?.toString().toLowerCase()
+    ) {
+      return null;
+    }
+
+    return parentId;
+  }
+
+  public static buildIndex(data: {
+    networkSiteTypes: Array<NetworkSiteType>;
+  }): NetworkSiteTypeHierarchyIndex {
+    const byId: Map<string, NetworkSiteType> = new Map<
+      string,
+      NetworkSiteType
+    >();
+    const childrenByParentId: Map<
+      string | null,
+      Array<NetworkSiteType>
+    > = new Map<string | null, Array<NetworkSiteType>>();
+
+    for (const networkSiteType of data.networkSiteTypes) {
+      const id: string | undefined = networkSiteType.id
+        ?.toString()
+        .toLowerCase();
+
+      if (id) {
+        byId.set(id, networkSiteType);
+      }
+
+      const parentId: string | null = this.getParentId(networkSiteType);
+      const normalizedParentId: string | null = parentId
+        ? parentId.toLowerCase()
+        : null;
+      const siblings: Array<NetworkSiteType> | undefined =
+        childrenByParentId.get(normalizedParentId);
+
+      if (siblings) {
+        siblings.push(networkSiteType);
+      } else {
+        childrenByParentId.set(normalizedParentId, [networkSiteType]);
+      }
+    }
+
+    for (const siblings of childrenByParentId.values()) {
+      this.sortInPlace(siblings);
+    }
+
+    return { byId, childrenByParentId };
+  }
+
+  public static getAncestorNetworkSiteTypes(data: {
+    networkSiteType: NetworkSiteType;
+    networkSiteTypes: Array<NetworkSiteType>;
+    index?: NetworkSiteTypeHierarchyIndex | undefined;
+  }): Array<NetworkSiteType> {
+    const index: NetworkSiteTypeHierarchyIndex =
+      data.index || this.buildIndex(data);
+    const ancestors: Array<NetworkSiteType> = [];
+    const visited: Set<string> = new Set<string>();
+
+    const ownId: string | undefined = data.networkSiteType.id
+      ?.toString()
+      .toLowerCase();
+    if (ownId) {
+      visited.add(ownId);
+    }
+
+    let parentId: string | null = this.getParentId(data.networkSiteType);
+
+    while (parentId) {
+      const normalizedParentId: string = parentId.toLowerCase();
+      if (visited.has(normalizedParentId)) {
+        break;
+      }
+
+      const parent: NetworkSiteType | undefined =
+        index.byId.get(normalizedParentId);
+      if (!parent) {
+        break;
+      }
+
+      ancestors.push(parent);
+      visited.add(normalizedParentId);
+      parentId = this.getParentId(parent);
+    }
+
+    return ancestors;
+  }
+
+  public static getDescendantNetworkSiteTypes(data: {
+    networkSiteType: NetworkSiteType;
+    networkSiteTypes: Array<NetworkSiteType>;
+    index?: NetworkSiteTypeHierarchyIndex | undefined;
+  }): Array<NetworkSiteType> {
+    const index: NetworkSiteTypeHierarchyIndex =
+      data.index || this.buildIndex(data);
+    const descendants: Array<NetworkSiteType> = [];
+    const visited: Set<string> = new Set<string>();
+
+    const ownId: string | undefined = data.networkSiteType.id
+      ?.toString()
+      .toLowerCase();
+    if (ownId) {
+      visited.add(ownId);
+    }
+
+    let frontier: Array<NetworkSiteType> = ownId
+      ? [...(index.childrenByParentId.get(ownId) || [])]
+      : [];
+
+    while (frontier.length > 0) {
+      const nextFrontier: Array<NetworkSiteType> = [];
+
+      for (const networkSiteType of frontier) {
+        const id: string | undefined = networkSiteType.id
+          ?.toString()
+          .toLowerCase();
+
+        if (!id || visited.has(id)) {
+          continue;
+        }
+
+        visited.add(id);
+        descendants.push(networkSiteType);
+        nextFrontier.push(...(index.childrenByParentId.get(id) || []));
+      }
+
+      frontier = nextFrontier;
+    }
+
+    return descendants;
+  }
+
+  /*
+   * Parent picker candidates. A leaf/unit type cannot own child types, and a
+   * type cannot be placed under itself or anything already below it.
+   */
+  public static getValidParentCandidates(data: {
+    networkSiteType: NetworkSiteType;
+    networkSiteTypes: Array<NetworkSiteType>;
+    index?: NetworkSiteTypeHierarchyIndex | undefined;
+  }): Array<NetworkSiteType> {
+    const index: NetworkSiteTypeHierarchyIndex =
+      data.index || this.buildIndex(data);
+    const excludedIds: Set<string> = new Set<string>();
+    const ownId: string | undefined = data.networkSiteType.id
+      ?.toString()
+      .toLowerCase();
+
+    if (ownId) {
+      excludedIds.add(ownId);
+    }
+
+    for (const descendant of this.getDescendantNetworkSiteTypes({
+      ...data,
+      index,
+    })) {
+      const descendantId: string | undefined = descendant.id
+        ?.toString()
+        .toLowerCase();
+      if (descendantId) {
+        excludedIds.add(descendantId);
+      }
+    }
+
+    return this.sort(
+      data.networkSiteTypes.filter((candidate: NetworkSiteType) => {
+        const candidateId: string | undefined = candidate.id
+          ?.toString()
+          .toLowerCase();
+        return (
+          Boolean(candidateId) &&
+          !excludedIds.has(candidateId!) &&
+          candidate.isUnitLevel !== true
+        );
+      }),
+    );
+  }
+
+  public static getBreadcrumbLabel(data: {
+    networkSiteType: NetworkSiteType;
+    networkSiteTypes: Array<NetworkSiteType>;
+    separator?: string | undefined;
+    index?: NetworkSiteTypeHierarchyIndex | undefined;
+  }): string {
+    const ancestors: Array<NetworkSiteType> =
+      this.getAncestorNetworkSiteTypes(data).reverse();
+
+    return [...ancestors, data.networkSiteType]
+      .map((networkSiteType: NetworkSiteType) => {
+        return networkSiteType.name || "Unnamed Site Type";
+      })
+      .join(data.separator || " › ");
+  }
+
+  public static buildTree(data: {
+    networkSiteTypes: Array<NetworkSiteType>;
+    index?: NetworkSiteTypeHierarchyIndex | undefined;
+  }): Array<NetworkSiteTypeHierarchyNode> {
+    const index: NetworkSiteTypeHierarchyIndex =
+      data.index || this.buildIndex(data);
+    const visited: Set<string> = new Set<string>();
+
+    const buildNode: (
+      networkSiteType: NetworkSiteType,
+      depth: number,
+    ) => NetworkSiteTypeHierarchyNode = (
+      networkSiteType: NetworkSiteType,
+      depth: number,
+    ): NetworkSiteTypeHierarchyNode => {
+      const id: string | undefined = networkSiteType.id
+        ?.toString()
+        .toLowerCase();
+      if (id) {
+        visited.add(id);
+      }
+
+      const children: Array<NetworkSiteTypeHierarchyNode> = id
+        ? (index.childrenByParentId.get(id) || [])
+            .filter((child: NetworkSiteType) => {
+              const childId: string | undefined = child.id
+                ?.toString()
+                .toLowerCase();
+              return Boolean(childId) && !visited.has(childId!);
+            })
+            .map((child: NetworkSiteType) => {
+              return buildNode(child, depth + 1);
+            })
+        : [];
+
+      return { networkSiteType, depth, children };
+    };
+
+    const roots: Array<NetworkSiteType> = this.sort(
+      data.networkSiteTypes.filter((networkSiteType: NetworkSiteType) => {
+        const parentId: string | null = this.getParentId(networkSiteType);
+        return !parentId || !index.byId.has(parentId.toLowerCase());
+      }),
+    );
+
+    const tree: Array<NetworkSiteTypeHierarchyNode> = roots.map(
+      (networkSiteType: NetworkSiteType) => {
+        return buildNode(networkSiteType, 0);
+      },
+    );
+
+    /*
+     * A component containing only a cycle has no natural root. Promote one
+     * member so all rows remain visible, and the visited set breaks the loop.
+     */
+    for (const networkSiteType of this.sort(data.networkSiteTypes)) {
+      const id: string | undefined = networkSiteType.id
+        ?.toString()
+        .toLowerCase();
+      if (!id || visited.has(id)) {
+        continue;
+      }
+
+      tree.push(buildNode(networkSiteType, 0));
+    }
+
+    return tree;
+  }
+
+  private static sort(
+    networkSiteTypes: Array<NetworkSiteType>,
+  ): Array<NetworkSiteType> {
+    const copy: Array<NetworkSiteType> = [...networkSiteTypes];
+    this.sortInPlace(copy);
+    return copy;
+  }
+
+  private static sortInPlace(networkSiteTypes: Array<NetworkSiteType>): void {
+    networkSiteTypes.sort((a: NetworkSiteType, b: NetworkSiteType) => {
+      const aOrder: number = a.order ?? Number.MAX_SAFE_INTEGER;
+      const bOrder: number = b.order ?? Number.MAX_SAFE_INTEGER;
+
+      if (aOrder !== bOrder) {
+        return aOrder - bOrder;
+      }
+
+      return (a.name || "").localeCompare(b.name || "");
+    });
+  }
+}