@oneuptime/common 12.0.25 → 12.0.27

package/Types/Monitor/SnmpMonitor/LldpNeighbor.ts

@@ -9,4 +9,15 @@ export default interface LldpNeighbor {
   remoteChassisId?: string | undefined;
   remotePortId?: string | undefined;
   remoteSysName?: string | undefined;
+  /*
+   * The neighbor's management address, joined in from lldpRemManAddrTable
+   * (a separate table whose index carries the address). Optional: plenty of
+   * agents do not implement it, an IPv6-only entry is skipped, and older
+   * payloads predate the column.
+   *
+   * See CdpNeighbor.remoteIpAddress for why it is worth the extra walk — it
+   * matches devices we manage by address, and it is what turns an unmanaged
+   * peer on the map into something that can actually be monitored.
+   */
+  remoteIpAddress?: string | undefined;
 }

package/Types/Monitor/SnmpMonitor/NetworkTopology.ts

@@ -108,10 +108,17 @@ export interface NetworkTopologyNode {
   // For unmanaged CDP peers this carries the reported platform string.
   deviceModel?: string | undefined;
   /*
-   * Endpoint identity (endpoint nodes only), all best-effort: MAC from the
-   * FDB, IP from the ARP join, classification from OUI/heuristics (e.g.
-   * "pos-terminal", "camera", "printer"), VLAN from the FDB entry that
-   * learned the MAC. Optional so older payloads stay valid.
+   * Endpoint identity, all best-effort: MAC from the FDB, IP from the ARP
+   * join, classification from OUI/heuristics (e.g. "pos-terminal",
+   * "camera", "printer"), VLAN from the FDB entry that learned the MAC.
+   * Optional so older payloads stay valid.
+   *
+   * `ipAddress` is the exception to "endpoint nodes only": an UNMANAGED
+   * peer carries it too, from the management address its neighbours
+   * advertise for it (CDP cdpCacheAddress / LLDP lldpRemManAddrTable). It
+   * is the field that makes such a peer actionable rather than merely
+   * visible — nothing can be monitored without an address — so a reader
+   * must not assume a node with an ipAddress is an endpoint.
    */
   macAddress?: string | undefined;
   ipAddress?: string | undefined;

package/Types/NetworkAutomation/RuleRunResult.ts

@@ -93,8 +93,30 @@ export interface AutoImportRuleRunResult {
   // Matched hosts whose create threw. Logged server-side, never fatal.
   devicesFailed: number;
   /*
-   * True when the run stopped at the DEVICE cap with matched hosts left
-   * over. Running again continues: already-imported hosts are skipped.
+   * Active Network Device monitors a dry run predicts it would create from
+   * the rule's selected Monitor Template. Always zero on a real run: real
+   * work is counted by monitorsCreated / monitorsFailed instead.
+   */
+  monitorsWouldCreate: number;
+  // Active Network Device monitors actually created and linked to a template.
+  monitorsCreated: number;
+  /*
+   * Matched devices left alone because a Network Device monitor already
+   * watches them. Existing manual monitors count too: automation must never
+   * add a duplicate simply because it did not create the first one.
+   */
+  monitorsSkippedAlreadyExisting: number;
+  /*
+   * Matched hosts that can become inventory records but cannot be backed by a
+   * Network Device monitor, such as a ping-only discovery result.
+   */
+  monitorsSkippedUnsupportedHost: number;
+  // Monitor creates that failed after the device was available.
+  monitorsFailed: number;
+  /*
+   * True when the run stopped at the device-create or monitor-create cap
+   * with work left over. Running again continues from idempotent inventory
+   * and provisioning keys.
    */
   isTruncated: boolean;
   /*
@@ -132,7 +154,163 @@ function readCount(json: JSONObject, key: string): number {
   return value;
 }
 
+function hosts(count: number): string {
+  return `${count} ${count === 1 ? "host" : "hosts"}`;
+}
+
+function activeMonitors(count: number): string {
+  return `${count} active Network Device ${
+    count === 1 ? "monitor" : "monitors"
+  }`;
+}
+
 export class RuleRunResultUtil {
+  /*
+   * The sentences the auto-import report shows. A run that imported nothing is
+   * the common case once a rule has been run, and "0 imported" with no reason
+   * reads as a broken button — so every bucket the server counted is reported
+   * only when it happened.
+   *
+   * It lives here rather than beside the browser modal so the App test suite,
+   * which has no react in its import graph, can exercise the wording without
+   * pulling in the component's react dependency.
+   */
+  public static describeAutoImportRun(result: AutoImportRuleRunResult): string {
+    const lines: Array<string> = [];
+
+    if (result.isDryRun) {
+      /*
+       * A dry run creates nothing, so devicesCreated is always zero. What a
+       * real run would attempt is matched minus already-registered — the
+       * server reports it exactly this way (see the engine's dry-run branch).
+       */
+      const wouldImport: number = Math.max(
+        result.hostsMatched - result.hostsSkippedAlreadyRegistered,
+        0,
+      );
+
+      if (wouldImport > 0) {
+        lines.push(
+          `This rule would import ${hosts(
+            wouldImport,
+          )} as network devices. Nothing was written — this was a dry run.`,
+        );
+      } else {
+        lines.push(
+          `This rule would import nothing. It matched ${hosts(
+            result.hostsMatched,
+          )} out of the ${hosts(
+            result.hostsEvaluated,
+          )} discovered hosts it looked at.`,
+        );
+      }
+    } else if (result.devicesCreated > 0) {
+      lines.push(
+        `Imported ${hosts(result.devicesCreated)} as network devices.`,
+      );
+    } else {
+      lines.push(
+        `No devices were imported. This rule matched ${hosts(
+          result.hostsMatched,
+        )} out of the ${hosts(
+          result.hostsEvaluated,
+        )} discovered hosts it looked at.`,
+      );
+    }
+
+    /*
+     * Device import and active-monitor provisioning are separate outcomes. A
+     * monitor can fail after its inventory record was safely created, and a
+     * dry run predicts monitor work without claiming anything was written.
+     */
+    if (result.isDryRun && result.monitorsWouldCreate > 0) {
+      lines.push(
+        `It would also create ${activeMonitors(
+          result.monitorsWouldCreate,
+        )} from the selected Monitor Template.`,
+      );
+    } else if (!result.isDryRun && result.monitorsCreated > 0) {
+      lines.push(
+        `Created ${activeMonitors(
+          result.monitorsCreated,
+        )} from the selected Monitor Template.`,
+      );
+    }
+
+    if (result.monitorsSkippedAlreadyExisting > 0) {
+      const skippedRequestedMonitors: string = `${
+        result.monitorsSkippedAlreadyExisting
+      } requested active Network Device ${
+        result.monitorsSkippedAlreadyExisting === 1 ? "monitor" : "monitors"
+      }`;
+      lines.push(
+        `${skippedRequestedMonitors} ${
+          result.monitorsSkippedAlreadyExisting === 1 ? "was" : "were"
+        } skipped because the device already had the requested automatic monitor or a manually configured Network Device monitor.`,
+      );
+    }
+
+    if (result.monitorsSkippedUnsupportedHost > 0) {
+      lines.push(
+        `${activeMonitors(
+          result.monitorsSkippedUnsupportedHost,
+        )} could not be provisioned because the discovery result was not SNMP-capable (for example, a ping-only host).`,
+      );
+    }
+
+    if (result.monitorsFailed > 0) {
+      lines.push(
+        `${activeMonitors(
+          result.monitorsFailed,
+        )} could not be created. Their network devices remain imported; check the server logs for the reason.`,
+      );
+    }
+
+    if (result.hostsExcluded > 0) {
+      lines.push(`An exclusion rule vetoed ${hosts(result.hostsExcluded)}.`);
+    }
+
+    if (result.hostsSkippedAlreadyRegistered > 0) {
+      lines.push(
+        `${hosts(
+          result.hostsSkippedAlreadyRegistered,
+        )} already had network devices at those addresses, so no duplicate device records were imported.`,
+      );
+    }
+
+    if (result.devicesFailed > 0) {
+      lines.push(
+        `${hosts(
+          result.devicesFailed,
+        )} could not be imported. Check the server logs for the reason.`,
+      );
+    }
+
+    /*
+     * Two different caps, two different truths. The device cap resumes:
+     * re-running skips what is already imported and continues. The scan cap
+     * does NOT: a re-run re-reads the same newest scans, so promising "run
+     * again to continue" there would send the operator in a circle.
+     */
+    if (result.isTruncated && !result.isDryRun) {
+      lines.push(
+        "Stopped at the run cap — run again to continue; already-imported hosts are skipped.",
+      );
+    } else if (result.isTruncated) {
+      lines.push(
+        "Stopped counting at the run cap — a real run is bounded by the same device-import and active-monitor creation limits.",
+      );
+    }
+
+    if (result.hasMoreScans) {
+      lines.push(
+        "Only the newest 100 completed scans were read — hosts that appear only in older scans were not evaluated by this run.",
+      );
+    }
+
+    return lines.join(" ");
+  }
+
   public static parseSiteAssignmentRuleRunResult(
     json: JSONObject | undefined | null,
   ): SiteAssignmentRuleRunResult {
@@ -196,6 +374,17 @@ export class RuleRunResultUtil {
       ),
       devicesCreated: readCount(source, "devicesCreated"),
       devicesFailed: readCount(source, "devicesFailed"),
+      monitorsWouldCreate: readCount(source, "monitorsWouldCreate"),
+      monitorsCreated: readCount(source, "monitorsCreated"),
+      monitorsSkippedAlreadyExisting: readCount(
+        source,
+        "monitorsSkippedAlreadyExisting",
+      ),
+      monitorsSkippedUnsupportedHost: readCount(
+        source,
+        "monitorsSkippedUnsupportedHost",
+      ),
+      monitorsFailed: readCount(source, "monitorsFailed"),
       isTruncated: source["isTruncated"] === true,
       hasMoreScans: source["hasMoreScans"] === true,
       isDryRun: source["isDryRun"] === true,

package/Types/NetworkSite/SiteHealthRollupPolicy.ts

@@ -0,0 +1,96 @@
+/*
+ * How a NetworkSite turns the health of the devices in its subtree into ONE
+ * status for itself.
+ *
+ * The two policies answer different questions, and which one a site should
+ * use depends entirely on what the site represents:
+ *
+ *   - A Unit (one store, one branch) wants WorstStatus. Four switches and a
+ *     firewall in one building are not independent - one of them dark is a
+ *     problem at that address, and averaging it away hides the outage.
+ *
+ *   - A Region above four hundred stores wants PercentThreshold. Under
+ *     WorstStatus a single dark switch in store 12,000 paints the whole
+ *     region Offline, which is true in the narrowest sense and useless in
+ *     every practical one: the region card can never be green, so it stops
+ *     carrying information.
+ *
+ * WorstStatus is the default so that upgrading changes nothing about how any
+ * existing site rolls up.
+ */
+export enum SiteHealthRollupPolicy {
+  /*
+   * The worst status any device in the subtree reports wins, where "worst"
+   * is the highest MonitorStatus.priority. One offline device makes the site
+   * offline, however many healthy devices sit beside it.
+   */
+  WorstStatus = "WorstStatus",
+
+  /*
+   * The site's status is decided by what SHARE of the subtree's devices are
+   * non-operational:
+   *
+   *   share >= offlineThresholdPercent -> the project's offline status
+   *   share > 0                        -> the project's degraded status
+   *                                       (its offline status when the
+   *                                       project has no degraded row)
+   *   share == 0                       -> the project's operational status
+   *
+   * Devices that have never reported are not counted in either the numerator
+   * or the denominator - the same rule WorstStatus uses when it skips a
+   * pending device rather than reading it as an outage.
+   */
+  PercentThreshold = "PercentThreshold",
+}
+
+/*
+ * Every policy value, for the settings dropdown and for validation. Kept
+ * next to the enum so a new policy cannot be added without the picker
+ * learning about it.
+ */
+export const SiteHealthRollupPolicyValues: Array<SiteHealthRollupPolicy> = [
+  SiteHealthRollupPolicy.WorstStatus,
+  SiteHealthRollupPolicy.PercentThreshold,
+];
+
+// Applied to any site that has never been given an explicit policy.
+export const DefaultSiteHealthRollupPolicy: SiteHealthRollupPolicy =
+  SiteHealthRollupPolicy.WorstStatus;
+
+/*
+ * Share of a subtree's reporting devices that must be non-operational before
+ * a PercentThreshold site calls itself offline. Half is a deliberately
+ * unopinionated starting point: it is the one value where "most of this
+ * region is down" and "most of this region is up" swap places.
+ */
+export const DefaultSiteOfflineThresholdPercent: number = 50;
+
+// Human-readable label for one policy, shared by the settings UI.
+export function getSiteHealthRollupPolicyLabel(
+  policy: SiteHealthRollupPolicy,
+): string {
+  if (policy === SiteHealthRollupPolicy.PercentThreshold) {
+    return "Percentage of devices down";
+  }
+  return "Worst status of any device";
+}
+
+/*
+ * Narrows an arbitrary stored string to a policy. A row written before the
+ * column existed, or by a client that invented a value, falls back to the
+ * default rather than throwing - a rollup must never fail because of one bad
+ * settings string.
+ */
+export function parseSiteHealthRollupPolicy(
+  value: string | null | undefined,
+): SiteHealthRollupPolicy {
+  if (
+    value &&
+    SiteHealthRollupPolicyValues.includes(value as SiteHealthRollupPolicy)
+  ) {
+    return value as SiteHealthRollupPolicy;
+  }
+  return DefaultSiteHealthRollupPolicy;
+}
+
+export default SiteHealthRollupPolicy;