@oneuptime/common 11.6.1 → 11.7.0

package/Utils/Monitor/NetworkTopologyUtil.ts

@@ -7,6 +7,7 @@ import NetworkTopology, {
 } from "../../Types/Monitor/SnmpMonitor/NetworkTopology";
 import LldpNeighbor from "../../Types/Monitor/SnmpMonitor/LldpNeighbor";
 import CdpNeighbor from "../../Types/Monitor/SnmpMonitor/CdpNeighbor";
+import { normalizeMac } from "./EndpointAttachmentUtil";
 
 export interface TopologyDeviceInput {
   id: string;
@@ -39,6 +40,36 @@ export interface TopologyInterfaceInput {
   errorsPerSecond?: number | undefined;
 }
 
+/*
+ * One discovered endpoint row (NetworkEndpoint), reduced to what rendering
+ * needs. Endpoints attach to their switch via an "fdb" edge; rows without a
+ * resolvable attachment are dropped (and counted) rather than floated.
+ */
+export interface TopologyEndpointInput {
+  id: string;
+  macAddress: string;
+  ipAddress?: string | undefined;
+  vendor?: string | undefined;
+  classification?: string | undefined;
+  vlanId?: number | undefined;
+  attachedNetworkDeviceId?: string | undefined;
+  attachedInterfaceIndex?: number | undefined;
+  attachedPortName?: string | undefined;
+  lastSeenAt?: Date | undefined;
+}
+
+/*
+ * buildTopology's result: the wire-format NetworkTopology plus endpoint
+ * bookkeeping. The extra fields are optional on the wire type, so older
+ * readers are unaffected.
+ */
+export interface TopologyBuildResult extends NetworkTopology {
+  // Endpoints skipped because they had no attachment in the graph.
+  droppedEndpointCount?: number | undefined;
+  // True when more attachable endpoints existed than the render cap allows.
+  endpointsTruncated?: boolean | undefined;
+}
+
 /*
  * A neighbor claim from either discovery protocol, normalized so LLDP and
  * CDP entries flow through the same match/dedupe/enrich pipeline.
@@ -56,6 +87,9 @@ interface NeighborClaim {
 // A device not seen within this window is treated as not currently up.
 const FRESH_WINDOW_MS: number = 15 * 60 * 1000;
 
+// Endpoint nodes rendered per graph; the slice is deterministic (by MAC).
+const ENDPOINT_RENDER_CAP: number = 2000;
+
 export default class NetworkTopologyUtil {
   /*
    * Builds the topology graph from every device in a project. Nodes are the
@@ -66,13 +100,17 @@ export default class NetworkTopologyUtil {
    * both protocols, appears once with the union of what each report knew
    * (ports, protocols, per-end interface state). When `interfaces` rows are
    * provided, each edge end whose interface is identifiable carries its
-   * operational state (up/down, utilization, rates).
+   * operational state (up/down, utilization, rates). When `endpoints` rows
+   * are provided, each one that attaches to a device in the graph becomes an
+   * "endpoint" node linked by an "fdb" edge (capped, deterministic by MAC);
+   * the rest are dropped and counted in droppedEndpointCount.
    */
   public static buildTopology(
     devices: Array<TopologyDeviceInput>,
     now: Date,
     interfaces: Array<TopologyInterfaceInput> = [],
-  ): NetworkTopology {
+    endpoints: Array<TopologyEndpointInput> = [],
+  ): TopologyBuildResult {
     const nodes: Array<NetworkTopologyNode> = [];
 
     // Index managed devices by the identifiers neighbor entries reference.
@@ -106,6 +144,7 @@ export default class NetworkTopologyUtil {
         id: device.id,
         name: device.name,
         isManaged: true,
+        kind: "device",
         status: NetworkTopologyUtil.deviceStatus(device, now),
         interfacesUp: device.interfacesUp,
         interfacesDown: device.interfacesDown,
@@ -145,6 +184,7 @@ export default class NetworkTopologyUtil {
               id: toNodeId,
               name: claim.displayName || "Unknown device",
               isManaged: false,
+              kind: "unmanaged",
               status: "unknown",
               deviceModel: claim.remotePlatform,
             };
@@ -262,7 +302,111 @@ export default class NetworkTopologyUtil {
       }
     }
 
-    return { nodes, edges: Array.from(edgeByKey.values()) };
+    const edges: Array<NetworkTopologyEdge> = Array.from(edgeByKey.values());
+
+    // --- Endpoint nodes + fdb edges ---
+
+    const deviceNodeIds: Set<string> = new Set(
+      devices.map((device: TopologyDeviceInput) => {
+        return device.id;
+      }),
+    );
+
+    /*
+     * Deterministic render order: by normalized MAC, then id, so the capped
+     * slice is stable across rebuilds regardless of query order.
+     */
+    const sortedEndpoints: Array<TopologyEndpointInput> = [...endpoints].sort(
+      (a: TopologyEndpointInput, b: TopologyEndpointInput) => {
+        const aMac: string = normalizeMac(a.macAddress) || a.macAddress;
+        const bMac: string = normalizeMac(b.macAddress) || b.macAddress;
+        if (aMac !== bMac) {
+          return aMac < bMac ? -1 : 1;
+        }
+        return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+      },
+    );
+
+    let droppedEndpointCount: number = 0;
+    let renderedEndpointCount: number = 0;
+    let endpointsTruncated: boolean = false;
+
+    for (const endpoint of sortedEndpoints) {
+      if (
+        !endpoint.attachedNetworkDeviceId ||
+        !deviceNodeIds.has(endpoint.attachedNetworkDeviceId)
+      ) {
+        // No attachment in this graph — nothing to hang the node off.
+        droppedEndpointCount++;
+        continue;
+      }
+
+      if (renderedEndpointCount >= ENDPOINT_RENDER_CAP) {
+        endpointsTruncated = true;
+        continue;
+      }
+      renderedEndpointCount++;
+
+      const nodeId: string = `endpoint:${endpoint.id}`;
+      nodes.push({
+        id: nodeId,
+        name:
+          endpoint.classification ||
+          endpoint.vendor ||
+          endpoint.ipAddress ||
+          endpoint.macAddress,
+        isManaged: false,
+        kind: "endpoint",
+        status: NetworkTopologyUtil.statusFromLastSeen(
+          endpoint.lastSeenAt,
+          now,
+        ),
+        vendor: endpoint.vendor,
+        macAddress: endpoint.macAddress,
+        ipAddress: endpoint.ipAddress,
+        classification: endpoint.classification,
+        vlanId: endpoint.vlanId,
+      });
+
+      // Port label + interface state on the switch end, when identifiable.
+      let switchInterface: TopologyInterfaceInput | undefined = undefined;
+      if (endpoint.attachedInterfaceIndex !== undefined) {
+        switchInterface = interfaceByDeviceAndIndex.get(
+          `${endpoint.attachedNetworkDeviceId}::${endpoint.attachedInterfaceIndex}`,
+        );
+      }
+      let fromPort: string | undefined =
+        endpoint.attachedPortName || switchInterface?.name;
+      if (!fromPort && endpoint.attachedInterfaceIndex !== undefined) {
+        fromPort = `if${endpoint.attachedInterfaceIndex}`;
+      }
+
+      edges.push({
+        fromNodeId: endpoint.attachedNetworkDeviceId,
+        toNodeId: nodeId,
+        fromPort: fromPort,
+        protocols: ["fdb"],
+        fromInterface: switchInterface
+          ? {
+              interfaceIndex: switchInterface.interfaceIndex,
+              interfaceName: switchInterface.name,
+              isOperationallyUp: switchInterface.isOperationallyUp,
+              isAdministrativelyUp: switchInterface.isAdministrativelyUp,
+              utilizationPercent: switchInterface.utilizationPercent,
+              inRateMbps: switchInterface.inRateMbps,
+              outRateMbps: switchInterface.outRateMbps,
+              errorsPerSecond: switchInterface.errorsPerSecond,
+            }
+          : undefined,
+      });
+    }
+
+    return {
+      nodes,
+      edges,
+      droppedEndpointCount,
+      endpointsTruncated,
+    };
   }
 
   /*
@@ -359,10 +503,18 @@ export default class NetworkTopologyUtil {
     device: TopologyDeviceInput,
     now: Date,
   ): NetworkTopologyNodeStatus {
-    if (!device.lastSeenAt) {
+    return NetworkTopologyUtil.statusFromLastSeen(device.lastSeenAt, now);
+  }
+
+  // The shared freshness rule: seen within the window = up, stale = down.
+  private static statusFromLastSeen(
+    lastSeenAt: Date | undefined,
+    now: Date,
+  ): NetworkTopologyNodeStatus {
+    if (!lastSeenAt) {
       return "unknown";
     }
-    const ageMs: number = now.getTime() - new Date(device.lastSeenAt).getTime();
+    const ageMs: number = now.getTime() - new Date(lastSeenAt).getTime();
     if (ageMs > FRESH_WINDOW_MS) {
       return "down";
     }

package/Utils/NetworkSite/CidrMatchUtil.ts

@@ -0,0 +1,296 @@
+/*
+ * Matching helpers for NetworkSite auto-assignment rules: IPv4 CIDR
+ * containment, case-insensitive '*' wildcard hostname patterns, and the
+ * highest-priority-wins rule picker. Pure and dependency-free so the rule
+ * engine's decisions are unit-testable.
+ */
+
+// The shape NetworkSiteAssignmentRule rows are matched with.
+export interface AssignmentRuleCandidate {
+  subnetCidr?: string | null | undefined;
+  hostnamePattern?: string | null | undefined;
+  priority?: number | null | undefined;
+  createdAt?: Date | null | undefined;
+}
+
+// The device attributes a rule is evaluated against.
+export interface RuleMatchTarget {
+  ip?: string | null | undefined;
+  hostname?: string | null | undefined;
+  sysName?: string | null | undefined;
+}
+
+export class CidrMatchUtil {
+  /*
+   * Longest hostname pattern we will evaluate. The column itself is
+   * ShortText (100), and a DNS name tops out at 253 characters, so anything
+   * longer is either a mistake or an attempt to make matching expensive.
+   */
+  public static readonly MAX_HOSTNAME_PATTERN_LENGTH: number = 253;
+
+  /*
+   * Hoisted out of the call sites so the literals are not the object of a
+   * member expression, which `wrap-regex` and Prettier cannot agree on.
+   */
+  private static readonly PREFIX_LENGTH_PATTERN: RegExp = /^\d{1,2}$/;
+
+  private static readonly OCTET_PATTERN: RegExp = /^\d{1,3}$/;
+
+  /*
+   * True when the IPv4 address `ip` falls inside `cidr` ('10.0.0.0/8').
+   * Prefixes /0 through /32 are supported; a bare address is treated as /32.
+   * Any invalid input returns false instead of throwing.
+   */
+  public static ipInCidr(ip: string, cidr: string): boolean {
+    const ipValue: number | null = CidrMatchUtil.parseIpv4(ip);
+    if (ipValue === null) {
+      return false;
+    }
+
+    if (typeof cidr !== "string" || cidr.trim().length === 0) {
+      return false;
+    }
+
+    const parts: Array<string> = cidr.trim().split("/");
+    if (parts.length > 2) {
+      return false;
+    }
+
+    const baseValue: number | null = CidrMatchUtil.parseIpv4(parts[0] || "");
+    if (baseValue === null) {
+      return false;
+    }
+
+    let prefixLength: number = 32;
+    if (parts.length === 2) {
+      const prefixText: string = parts[1] || "";
+      if (!CidrMatchUtil.PREFIX_LENGTH_PATTERN.test(prefixText)) {
+        return false;
+      }
+      prefixLength = parseInt(prefixText, 10);
+      if (prefixLength < 0 || prefixLength > 32) {
+        return false;
+      }
+    }
+
+    /*
+     * JS bitwise ops are 32-bit signed; >>> 0 keeps the mask and the masked
+     * addresses unsigned. A shift by 32 is a no-op in JS, so /0 is special
+     * cased to the all-zero mask (matches everything).
+     */
+    const mask: number =
+      prefixLength === 0 ? 0 : (0xffffffff << (32 - prefixLength)) >>> 0;
+
+    return (ipValue & mask) >>> 0 === (baseValue & mask) >>> 0;
+  }
+
+  // True when `cidr` is a well-formed IPv4 CIDR (or bare address == /32).
+  public static isValidCidr(cidr: string): boolean {
+    if (typeof cidr !== "string" || cidr.trim().length === 0) {
+      return false;
+    }
+    const parts: Array<string> = cidr.trim().split("/");
+    if (parts.length > 2) {
+      return false;
+    }
+    if (CidrMatchUtil.parseIpv4(parts[0] || "") === null) {
+      return false;
+    }
+    if (parts.length === 2) {
+      const prefixText: string = parts[1] || "";
+      if (!CidrMatchUtil.PREFIX_LENGTH_PATTERN.test(prefixText)) {
+        return false;
+      }
+      const prefixLength: number = parseInt(prefixText, 10);
+      if (prefixLength < 0 || prefixLength > 32) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /*
+   * Case-insensitive wildcard match where '*' matches any run of characters
+   * (including none) and every other character is literal. The pattern must
+   * cover the whole hostname. Non-string or missing inputs never match, and
+   * so does an over-long pattern.
+   *
+   * Deliberately NOT a regex: compiling a user-authored pattern into
+   * /^.*a.*a.*a...$/ makes the backtracking engine explore an exponential
+   * number of split points on a long homogeneous input, which blocks the
+   * event loop for minutes. This matcher is O(hostname x pattern) worst case
+   * with no recursion, so a hostile rule cannot hang the process.
+   */
+  public static hostnameMatchesWildcard(
+    hostname: string,
+    pattern: string,
+  ): boolean {
+    if (typeof hostname !== "string" || typeof pattern !== "string") {
+      return false;
+    }
+
+    const text: string = hostname.trim().toLowerCase();
+    const glob: string = pattern.trim().toLowerCase();
+
+    if (glob.length > CidrMatchUtil.MAX_HOSTNAME_PATTERN_LENGTH) {
+      return false;
+    }
+
+    /*
+     * Greedy two-pointer glob match. On a mismatch we rewind only to the
+     * most recent '*' and advance the character it consumed by one, so each
+     * character of the hostname is revisited at most once per '*'.
+     */
+    let textIndex: number = 0;
+    let globIndex: number = 0;
+    let lastStarIndex: number = -1;
+    let textIndexAtLastStar: number = 0;
+
+    while (textIndex < text.length) {
+      if (globIndex < glob.length && glob[globIndex] === "*") {
+        lastStarIndex = globIndex;
+        textIndexAtLastStar = textIndex;
+        globIndex++;
+      } else if (
+        globIndex < glob.length &&
+        glob[globIndex] === text[textIndex]
+      ) {
+        globIndex++;
+        textIndex++;
+      } else if (lastStarIndex !== -1) {
+        globIndex = lastStarIndex + 1;
+        textIndexAtLastStar++;
+        textIndex = textIndexAtLastStar;
+      } else {
+        return false;
+      }
+    }
+
+    // Any trailing '*' in the pattern can still match the empty remainder.
+    while (globIndex < glob.length && glob[globIndex] === "*") {
+      globIndex++;
+    }
+
+    return globIndex === glob.length;
+  }
+
+  /*
+   * True when the rule's populated criteria all match the target. A CIDR
+   * criterion matches the target's ip; a hostname pattern matches either the
+   * hostname or the SNMP sysName. A rule with no criteria never matches.
+   */
+  public static ruleMatches(
+    rule: AssignmentRuleCandidate,
+    target: RuleMatchTarget,
+  ): boolean {
+    const hasCidr: boolean = Boolean(
+      rule.subnetCidr && rule.subnetCidr.trim().length > 0,
+    );
+    const hasPattern: boolean = Boolean(
+      rule.hostnamePattern && rule.hostnamePattern.trim().length > 0,
+    );
+
+    if (!hasCidr && !hasPattern) {
+      return false;
+    }
+
+    if (hasCidr) {
+      if (!target.ip || !CidrMatchUtil.ipInCidr(target.ip, rule.subnetCidr!)) {
+        return false;
+      }
+    }
+
+    if (hasPattern) {
+      const matchesHostname: boolean = Boolean(
+        target.hostname &&
+          CidrMatchUtil.hostnameMatchesWildcard(
+            target.hostname,
+            rule.hostnamePattern!,
+          ),
+      );
+      const matchesSysName: boolean = Boolean(
+        target.sysName &&
+          CidrMatchUtil.hostnameMatchesWildcard(
+            target.sysName,
+            rule.hostnamePattern!,
+          ),
+      );
+      if (!matchesHostname && !matchesSysName) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /*
+   * Picks the winning rule for a target: among matching rules the highest
+   * priority number wins; ties go to the earlier createdAt when both rows
+   * carry one, otherwise the earlier rule in the input order (stable).
+   * Returns null when nothing matches.
+   */
+  public static pickRule<T extends AssignmentRuleCandidate>(
+    rules: Array<T>,
+    target: RuleMatchTarget,
+  ): T | null {
+    let best: T | null = null;
+
+    for (const rule of rules) {
+      if (!CidrMatchUtil.ruleMatches(rule, target)) {
+        continue;
+      }
+
+      if (!best) {
+        best = rule;
+        continue;
+      }
+
+      const bestPriority: number = best.priority || 0;
+      const rulePriority: number = rule.priority || 0;
+
+      if (rulePriority > bestPriority) {
+        best = rule;
+        continue;
+      }
+
+      if (
+        rulePriority === bestPriority &&
+        rule.createdAt &&
+        best.createdAt &&
+        rule.createdAt.getTime() < best.createdAt.getTime()
+      ) {
+        best = rule;
+      }
+    }
+
+    return best;
+  }
+
+  // '10.0.0.1' -> unsigned 32-bit value; anything malformed -> null.
+  private static parseIpv4(ip: string): number | null {
+    if (typeof ip !== "string") {
+      return null;
+    }
+
+    const octets: Array<string> = ip.trim().split(".");
+    if (octets.length !== 4) {
+      return null;
+    }
+
+    let value: number = 0;
+    for (const octetText of octets) {
+      if (!CidrMatchUtil.OCTET_PATTERN.test(octetText)) {
+        return null;
+      }
+      const octet: number = parseInt(octetText, 10);
+      if (octet > 255) {
+        return null;
+      }
+      value = (value * 256 + octet) >>> 0;
+    }
+
+    return value;
+  }
+}
+
+export default CidrMatchUtil;

package/Utils/NetworkSite/MaterializedPathUtil.ts

@@ -0,0 +1,115 @@
+/*
+ * Materialized-path helpers for the NetworkSite hierarchy.
+ *
+ * A site's path is the slash-separated list of its ancestor IDs ending with
+ * its own ID, in '/rootId/childId/.../ownId/' form. Root sites have the path
+ * '/ownId/'. All helpers are pure string operations so the tree math is
+ * unit-testable without a database.
+ */
+export class MaterializedPathUtil {
+  /*
+   * Builds the path for a site given its parent's path (null/undefined/empty
+   * for root sites). Tolerates a parent path missing its leading or trailing
+   * slash so a hand-edited row cannot poison every child path built from it.
+   */
+  public static buildPath(
+    parentPath: string | null | undefined,
+    siteId: string,
+  ): string {
+    const normalizedParent: string = MaterializedPathUtil.normalizePath(
+      parentPath || "",
+    );
+    return `${normalizedParent || "/"}${siteId}/`;
+  }
+
+  // '/a/b/' -> ['a', 'b']; invalid/empty input -> [].
+  public static segmentsOf(path: string | null | undefined): Array<string> {
+    if (!path || typeof path !== "string") {
+      return [];
+    }
+    return path.split("/").filter((segment: string) => {
+      return segment.length > 0;
+    });
+  }
+
+  /*
+   * Number of ancestors above the site this path belongs to: '/a/' -> 0,
+   * '/a/b/' -> 1. Empty/invalid paths report 0.
+   */
+  public static depthOf(path: string | null | undefined): number {
+    const segments: Array<string> = MaterializedPathUtil.segmentsOf(path);
+    return segments.length > 0 ? segments.length - 1 : 0;
+  }
+
+  /*
+   * True when `path` belongs to a strict descendant of the site that owns
+   * `ancestorPath` (a site is not its own descendant).
+   */
+  public static isDescendant(
+    path: string | null | undefined,
+    ancestorPath: string | null | undefined,
+  ): boolean {
+    if (!path || !ancestorPath) {
+      return false;
+    }
+    const normalizedPath: string = MaterializedPathUtil.normalizePath(path);
+    const normalizedAncestor: string =
+      MaterializedPathUtil.normalizePath(ancestorPath);
+    return (
+      normalizedPath.startsWith(normalizedAncestor) &&
+      normalizedPath !== normalizedAncestor
+    );
+  }
+
+  /*
+   * True when making the site with `siteId` a child of the site whose path is
+   * `newParentPath` would create a cycle - i.e. the proposed parent is the
+   * site itself or one of its descendants (its own ID appears anywhere in the
+   * parent's path). A null/empty parent path (becoming a root) can never
+   * create a cycle.
+   */
+  public static wouldCreateCycle(
+    siteId: string,
+    newParentPath: string | null | undefined,
+  ): boolean {
+    if (!siteId || !newParentPath) {
+      return false;
+    }
+    const segments: Array<string> =
+      MaterializedPathUtil.segmentsOf(newParentPath);
+    return segments.includes(siteId);
+  }
+
+  /*
+   * Rewrites subtree paths for a move: every affected path that starts with
+   * `oldParentPath` gets that prefix replaced with `newParentPath`. Paths
+   * outside the moved subtree are returned unchanged, in input order.
+   */
+  public static rebasePaths(
+    oldParentPath: string,
+    newParentPath: string,
+    affectedPaths: Array<string>,
+  ): Array<string> {
+    const oldPrefix: string = MaterializedPathUtil.normalizePath(oldParentPath);
+    const newPrefix: string = MaterializedPathUtil.normalizePath(newParentPath);
+
+    return affectedPaths.map((path: string) => {
+      const normalized: string = MaterializedPathUtil.normalizePath(path);
+      if (!oldPrefix || !normalized.startsWith(oldPrefix)) {
+        return path;
+      }
+      return `${newPrefix}${normalized.slice(oldPrefix.length)}`;
+    });
+  }
+
+  // Ensures '/a/b/' form: leading + trailing slash, no empty segments.
+  private static normalizePath(path: string): string {
+    const segments: Array<string> = MaterializedPathUtil.segmentsOf(path);
+    if (segments.length === 0) {
+      return "";
+    }
+    return `/${segments.join("/")}/`;
+  }
+}
+
+export default MaterializedPathUtil;