@oneuptime/common 12.0.25 → 12.0.26

package/Utils/Monitor/InterfaceInventoryUtil.ts

@@ -0,0 +1,251 @@
+import ColumnLength from "../../Types/Database/ColumnLength";
+import SnmpInterface from "../../Types/Monitor/SnmpMonitor/SnmpInterface";
+
+/*
+ * Pure helpers that turn ONE device's IF-MIB walk into the exact rows the
+ * NetworkInterface inventory should insert and update, plus the set of
+ * interface indexes the user has muted. Everything here is deterministic and
+ * side-effect free so the column-by-column contract can be tested without a
+ * database; the batched SQL that applies it lives in NetworkInterfaceService.
+ *
+ * This mirrors EndpointAttachmentUtil.decideUpsert / NetworkEndpointService:
+ * the decision is pure, the persistence is one statement per chunk.
+ */
+
+/*
+ * The stored row, as far as planning cares. Only these two columns are read
+ * back from the database: the walk is authoritative for every other column,
+ * and isMonitored is the one column it must never touch.
+ */
+export interface InterfaceExistingRowSnapshot {
+  /*
+   * Optional to mirror the model, where every column is optional. A stored
+   * row without one cannot be matched to a walked interface and is skipped.
+   */
+  interfaceIndex?: number | undefined;
+  isMonitored?: boolean | undefined;
+}
+
+/*
+ * A NetworkInterface row that does not exist yet.
+ *
+ * Deliberately NARROWER than InterfaceUpdateRow: the create path has never
+ * written inRateMbps / outRateMbps / utilizationPercent / errorsPerSecond,
+ * and it must not start. Those four are computed server-side from the delta
+ * against the PREVIOUS walk, so on the walk that first discovers an interface
+ * they carry whatever the rate util managed to derive with no baseline —
+ * writing them here would publish a rate nobody can reproduce. The absence of
+ * those fields on this type is the guardrail.
+ *
+ * isMonitored is `true` rather than `boolean` for the same reason in the
+ * opposite direction: new ports are monitored by default, and typing it as a
+ * literal keeps a future edit from routing a user-owned value through here.
+ */
+export interface InterfaceInsertRow {
+  interfaceIndex: number;
+  name: string;
+  alias: string | null;
+  macAddress: string | null;
+  interfaceType: number | null;
+  isMonitored: true;
+  isOperationallyUp: boolean;
+  isAdministrativelyUp: boolean;
+  speedInMbps: number | null;
+  lastSeenAt: Date;
+}
+
+/*
+ * A NetworkInterface row the walk re-observed.
+ *
+ * There is NO isMonitored member here, and that omission is load-bearing:
+ * isMonitored is user-owned (the per-interface mute toggle in the dashboard).
+ * A walk that wrote it would silently un-mute every port a user muted on the
+ * very next poll, and the mute would appear to "not stick" with nothing in
+ * the logs. Keeping the field off the type makes that a compile error.
+ *
+ * Every other column is written unconditionally, `null` included: the walk is
+ * the authority on interface state, so an interface that stops reporting an
+ * alias / MAC / speed has genuinely lost it and the stored value must clear.
+ */
+export interface InterfaceUpdateRow {
+  interfaceIndex: number;
+  name: string;
+  alias: string | null;
+  macAddress: string | null;
+  interfaceType: number | null;
+  isOperationallyUp: boolean;
+  isAdministrativelyUp: boolean;
+  speedInMbps: number | null;
+  inRateMbps: number | null;
+  outRateMbps: number | null;
+  utilizationPercent: number | null;
+  errorsPerSecond: number | null;
+  lastSeenAt: Date;
+}
+
+export interface InterfaceUpsertPlan {
+  inserts: Array<InterfaceInsertRow>;
+  updates: Array<InterfaceUpdateRow>;
+  /*
+   * Walked interfaces whose stored row has isMonitored === false. The caller
+   * prunes these out of the in-flight walk response so criteria and
+   * per-interface metrics ignore them — while the inventory rows above still
+   * record every walked port.
+   */
+  unmonitoredInterfaceIndexes: Array<number>;
+}
+
+// Bits/sec on the wire; Mbps in the inventory.
+const BITS_PER_MEGABIT: number = 1000000;
+
+/*
+ * Rate columns are stored rounded to three decimals (kbps resolution). The
+ * rounding is part of the stored value, not presentation: it keeps a rate
+ * that wobbles in the ninth decimal from writing a new row version every poll.
+ */
+const RATE_DECIMAL_SCALE: number = 1000;
+
+/*
+ * ShortText columns are varchar(100). Truncating HERE rather than at write
+ * time matters: the raw batched INSERT/UPDATE has no model validation in
+ * front of it (DatabaseService.create throws on an over-length value instead
+ * of truncating), so one 300-character ifAlias from a chatty agent would
+ * abort the whole chunk it rides in and lose every other interface with it.
+ */
+function truncateShortText(value: string | undefined): string | null {
+  if (!value) {
+    return null;
+  }
+  return value.length > ColumnLength.ShortText
+    ? value.substring(0, ColumnLength.ShortText)
+    : value;
+}
+
+export default class InterfaceInventoryUtil {
+  /*
+   * (walked interfaces, stored rows, walk timestamp) -> (rows to insert,
+   * rows to update, muted indexes).
+   *
+   * lastSeenAt is stamped from the caller's single `now` for every row, so a
+   * 400-port chassis does not end up with 400 slightly different timestamps
+   * that make "which ports answered on this walk" unanswerable.
+   */
+  public static planWalkUpsert(data: {
+    walkedInterfaces: Array<SnmpInterface>;
+    existingRows: Array<InterfaceExistingRowSnapshot>;
+    now: Date;
+  }): InterfaceUpsertPlan {
+    const plan: InterfaceUpsertPlan = {
+      inserts: [],
+      updates: [],
+      unmonitoredInterfaceIndexes: [],
+    };
+
+    /*
+     * De-duplicate by ifIndex before anything else.
+     *
+     * ON CONFLICT DO UPDATE cannot touch the same row twice in one statement
+     * — Postgres raises "ON CONFLICT DO UPDATE command cannot affect row a
+     * second time" and aborts the statement, which here would abort the whole
+     * walk. Agents do send duplicate ifIndex rows (a bridge that reports the
+     * same port under two ifTable entries, a proxy agent merging two
+     * sub-agents). Map.set keeps the FIRST occurrence's position and the LAST
+     * occurrence's data, which is what the previous row-at-a-time loop
+     * converged on: it applied both writes in order, so the last one won.
+     */
+    const walkedByIndex: Map<number, SnmpInterface> = new Map();
+    for (const walked of data.walkedInterfaces) {
+      walkedByIndex.set(walked.interfaceIndex, walked);
+    }
+
+    const existingByIndex: Map<number, InterfaceExistingRowSnapshot> =
+      new Map();
+    for (const existing of data.existingRows) {
+      if (existing.interfaceIndex !== undefined) {
+        existingByIndex.set(existing.interfaceIndex, existing);
+      }
+    }
+
+    for (const walked of walkedByIndex.values()) {
+      const existing: InterfaceExistingRowSnapshot | undefined =
+        existingByIndex.get(walked.interfaceIndex);
+
+      /*
+       * Only a walked interface can be pruned from the walk response, so the
+       * muted set is built from the walk, not from the whole stored table.
+       */
+      if (existing && existing.isMonitored === false) {
+        plan.unmonitoredInterfaceIndexes.push(walked.interfaceIndex);
+      }
+
+      if (existing) {
+        plan.updates.push({
+          interfaceIndex: walked.interfaceIndex,
+          name: InterfaceInventoryUtil.interfaceName(walked),
+          alias: truncateShortText(walked.alias),
+          macAddress: truncateShortText(walked.macAddress),
+          interfaceType: walked.interfaceType ?? null,
+          isOperationallyUp: walked.isOperationallyUp,
+          isAdministrativelyUp: walked.isAdministrativelyUp,
+          speedInMbps: InterfaceInventoryUtil.toMbps(
+            walked.speedInBitsPerSecond,
+          ),
+          inRateMbps: InterfaceInventoryUtil.toRoundedMbps(
+            walked.inBitsPerSecond,
+          ),
+          outRateMbps: InterfaceInventoryUtil.toRoundedMbps(
+            walked.outBitsPerSecond,
+          ),
+          utilizationPercent: walked.utilizationPercent ?? null,
+          errorsPerSecond: walked.errorsPerSecond ?? null,
+          lastSeenAt: data.now,
+        });
+      } else {
+        plan.inserts.push({
+          interfaceIndex: walked.interfaceIndex,
+          name: InterfaceInventoryUtil.interfaceName(walked),
+          alias: truncateShortText(walked.alias),
+          macAddress: truncateShortText(walked.macAddress),
+          interfaceType: walked.interfaceType ?? null,
+          isMonitored: true,
+          isOperationallyUp: walked.isOperationallyUp,
+          isAdministrativelyUp: walked.isAdministrativelyUp,
+          speedInMbps: InterfaceInventoryUtil.toMbps(
+            walked.speedInBitsPerSecond,
+          ),
+          lastSeenAt: data.now,
+        });
+      }
+    }
+
+    return plan;
+  }
+
+  /*
+   * `name` is NOT NULL in the schema, and some agents return an empty
+   * ifDescr for tunnel/loopback pseudo-interfaces — hence the empty-string
+   * floor rather than a null.
+   */
+  private static interfaceName(walked: SnmpInterface): string {
+    return (walked.name || "").substring(0, ColumnLength.ShortText);
+  }
+
+  // ifSpeed/ifHighSpeed are bits per second; speedInMbps is megabits.
+  private static toMbps(bitsPerSecond: number | undefined): number | null {
+    return bitsPerSecond !== undefined
+      ? bitsPerSecond / BITS_PER_MEGABIT
+      : null;
+  }
+
+  private static toRoundedMbps(
+    bitsPerSecond: number | undefined,
+  ): number | null {
+    if (bitsPerSecond === undefined) {
+      return null;
+    }
+    return (
+      Math.round((bitsPerSecond / BITS_PER_MEGABIT) * RATE_DECIMAL_SCALE) /
+      RATE_DECIMAL_SCALE
+    );
+  }
+}

package/Utils/Monitor/NetworkDeviceMonitorTemplateUtil.ts

@@ -0,0 +1,333 @@
+import Monitor from "../../Models/DatabaseModels/Monitor";
+import MonitorTemplate from "../../Models/DatabaseModels/MonitorTemplate";
+import NetworkDevice from "../../Models/DatabaseModels/NetworkDevice";
+import ColumnLength from "../../Types/Database/ColumnLength";
+import BadDataException from "../../Types/Exception/BadDataException";
+import { JSONObject } from "../../Types/JSON";
+import JSONFunctions from "../../Types/JSONFunctions";
+import MonitorSteps from "../../Types/Monitor/MonitorSteps";
+import MonitorType from "../../Types/Monitor/MonitorType";
+import ObjectID from "../../Types/ObjectID";
+
+/*
+ * Materialises a project MonitorTemplate for one discovered NetworkDevice.
+ *
+ * A Network Device template necessarily contains a concrete device id today:
+ * the ordinary template form uses the same required step editor as a Monitor.
+ * That id is only a design-time placeholder when the template is used by
+ * discovery automation. Every step is therefore cloned and rebound here; the
+ * template object must never be mutated, because the same instance can serve a
+ * whole discovered estate.
+ *
+ * This utility deliberately performs no database or permission work. Callers
+ * remain responsible for fetching a template with its labels, then persisting
+ * the returned Monitor through MonitorService so tenant, billing, reference,
+ * rule-engine, and audit hooks still run.
+ */
+
+type NetworkDeviceId = ObjectID | string | null | undefined;
+
+export interface RebindNetworkDeviceMonitorStepsData {
+  monitorSteps: MonitorSteps | undefined;
+  networkDeviceId: NetworkDeviceId;
+}
+
+export interface BuildSyncedNetworkDeviceMonitorStepsData {
+  templateMonitorSteps: MonitorSteps | undefined;
+  currentMonitorSteps: MonitorSteps | undefined;
+  fallbackNetworkDeviceId?: NetworkDeviceId;
+}
+
+export interface BuildMonitorFromTemplateData {
+  template: MonitorTemplate;
+  networkDevice: NetworkDevice;
+}
+
+export default class NetworkDeviceMonitorTemplateUtil {
+  /**
+   * Deep-clone a Network Device monitor's steps and point every step at the
+   * supplied device. The source MonitorSteps and every nested object remain
+   * untouched.
+   */
+  public static rebindMonitorSteps(
+    data: RebindNetworkDeviceMonitorStepsData,
+  ): MonitorSteps {
+    const networkDeviceId: string =
+      data.networkDeviceId?.toString().trim() || "";
+
+    if (!networkDeviceId) {
+      throw new BadDataException(
+        "Network Device ID is required to bind monitor template steps.",
+      );
+    }
+
+    this.validateMonitorSteps(data.monitorSteps, "Monitor template");
+
+    const clonedSteps: MonitorSteps = MonitorSteps.clone(data.monitorSteps!);
+
+    for (const step of clonedSteps.data!.monitorStepsInstanceArray) {
+      if (!step.data?.networkDeviceMonitor) {
+        throw new BadDataException(
+          "Monitor template contains a Network Device step without Network Device configuration.",
+        );
+      }
+
+      step.data.networkDeviceMonitor.networkDeviceId = networkDeviceId;
+    }
+
+    return clonedSteps;
+  }
+
+  /**
+   * Clone freshly-edited template steps for a linked Monitor while retaining
+   * that Monitor's instance-specific device. Multiple steps may reference the
+   * same device. More than one distinct binding is rejected because choosing
+   * one would silently retarget alerting; when no current binding survives, a
+   * persisted auto-provisioning marker can be supplied as the fallback.
+   */
+  public static buildSyncedMonitorSteps(
+    data: BuildSyncedNetworkDeviceMonitorStepsData,
+  ): MonitorSteps {
+    const currentDeviceIds: Set<string> = new Set<string>();
+
+    for (const step of data.currentMonitorSteps?.data
+      ?.monitorStepsInstanceArray || []) {
+      const currentDeviceId: string | undefined =
+        step.data?.networkDeviceMonitor?.networkDeviceId?.trim() || undefined;
+
+      if (currentDeviceId) {
+        currentDeviceIds.add(currentDeviceId);
+      }
+    }
+
+    if (currentDeviceIds.size > 1) {
+      throw new BadDataException(
+        "Linked Network Device monitor must have exactly one distinct Network Device binding.",
+      );
+    }
+
+    const preservedNetworkDeviceId: string =
+      Array.from(currentDeviceIds)[0] ||
+      data.fallbackNetworkDeviceId?.toString().trim() ||
+      "";
+
+    if (!preservedNetworkDeviceId) {
+      throw new BadDataException(
+        "Linked Network Device monitor has no Network Device binding to preserve.",
+      );
+    }
+
+    return this.rebindMonitorSteps({
+      monitorSteps: data.templateMonitorSteps,
+      networkDeviceId: preservedNetworkDeviceId,
+    });
+  }
+
+  /**
+   * Build (but do not persist) the Monitor managed for one discovered device.
+   */
+  public static buildMonitor(data: BuildMonitorFromTemplateData): Monitor {
+    const monitorTemplate: MonitorTemplate = data.template;
+    const networkDevice: NetworkDevice = data.networkDevice;
+
+    const monitorTemplateId: ObjectID | null = monitorTemplate.id;
+    if (!monitorTemplateId) {
+      throw new BadDataException(
+        "Monitor template ID is required to provision a Network Device monitor.",
+      );
+    }
+
+    const networkDeviceId: ObjectID | null = networkDevice.id;
+    if (!networkDeviceId) {
+      throw new BadDataException(
+        "Network Device ID is required to provision a monitor.",
+      );
+    }
+
+    if (!monitorTemplate.projectId) {
+      throw new BadDataException(
+        "Monitor template project ID is required to provision a Network Device monitor.",
+      );
+    }
+
+    if (!networkDevice.projectId) {
+      throw new BadDataException(
+        "Network Device project ID is required to provision a monitor.",
+      );
+    }
+
+    if (
+      monitorTemplate.projectId.toString() !==
+      networkDevice.projectId.toString()
+    ) {
+      throw new BadDataException(
+        "Monitor template and Network Device must belong to the same project.",
+      );
+    }
+
+    if (monitorTemplate.monitorType !== MonitorType.NetworkDevice) {
+      throw new BadDataException(
+        `Monitor template must have type "${MonitorType.NetworkDevice}" to provision a Network Device monitor.`,
+      );
+    }
+
+    this.validateMonitorSteps(monitorTemplate.monitorSteps, "Monitor template");
+
+    const monitor: Monitor = new Monitor();
+    monitor.projectId = new ObjectID(networkDevice.projectId.toString());
+    monitor.name = this.buildDeviceIdentifiableName({
+      monitorTemplate,
+      networkDevice,
+    });
+    if (monitorTemplate.monitorDescription !== undefined) {
+      monitor.description = monitorTemplate.monitorDescription;
+    }
+    monitor.monitorType = MonitorType.NetworkDevice;
+    monitor.monitorSteps = this.rebindMonitorSteps({
+      monitorSteps: monitorTemplate.monitorSteps,
+      networkDeviceId,
+    });
+    if (monitorTemplate.monitoringInterval !== undefined) {
+      monitor.monitoringInterval = monitorTemplate.monitoringInterval;
+    }
+    if (monitorTemplate.minimumProbeAgreement !== undefined) {
+      monitor.minimumProbeAgreement = monitorTemplate.minimumProbeAgreement;
+    }
+    if (monitorTemplate.customFields !== undefined) {
+      monitor.customFields = this.cloneCustomFields(
+        monitorTemplate.customFields,
+      );
+    }
+    if (monitorTemplate.labels !== undefined) {
+      monitor.labels = [...monitorTemplate.labels];
+    }
+    monitor.monitorTemplateId = new ObjectID(monitorTemplateId.toString());
+    monitor.autoProvisionedNetworkDeviceId = new ObjectID(
+      networkDeviceId.toString(),
+    );
+
+    return monitor;
+  }
+
+  public static validateMonitorSteps(
+    monitorSteps: MonitorSteps | JSONObject | undefined,
+    subject: string = "Network Device monitor",
+  ): void {
+    const normalizedSteps: MonitorSteps = this.normalizeMonitorSteps(
+      monitorSteps,
+      subject,
+    );
+
+    if (
+      !Array.isArray(normalizedSteps.data?.monitorStepsInstanceArray) ||
+      normalizedSteps.data.monitorStepsInstanceArray.length === 0
+    ) {
+      throw new BadDataException(`${subject} monitor steps are required.`);
+    }
+
+    for (const step of normalizedSteps.data.monitorStepsInstanceArray) {
+      if (!step.data?.networkDeviceMonitor) {
+        throw new BadDataException(
+          `${subject} contains a Network Device step without Network Device configuration.`,
+        );
+      }
+    }
+  }
+
+  public static getReferencedNetworkDeviceIds(
+    monitorSteps: MonitorSteps | JSONObject | undefined,
+  ): Set<string> {
+    this.validateMonitorSteps(monitorSteps);
+    const normalizedSteps: MonitorSteps = this.normalizeMonitorSteps(
+      monitorSteps,
+      "Network Device monitor",
+    );
+    const ids: Set<string> = new Set();
+
+    for (const step of normalizedSteps.data!.monitorStepsInstanceArray) {
+      const networkDeviceId: string =
+        step.data!.networkDeviceMonitor!.networkDeviceId?.trim() || "";
+      if (networkDeviceId) {
+        ids.add(networkDeviceId);
+      }
+    }
+
+    return ids;
+  }
+
+  public static assertMonitorStepsBoundToNetworkDevice(data: {
+    monitorSteps: MonitorSteps | JSONObject | undefined;
+    networkDeviceId: ObjectID | string;
+  }): void {
+    const expectedId: string = data.networkDeviceId.toString();
+    const referencedIds: Set<string> = this.getReferencedNetworkDeviceIds(
+      data.monitorSteps,
+    );
+
+    if (referencedIds.size !== 1 || !referencedIds.has(expectedId)) {
+      throw new BadDataException(
+        "An auto-provisioned Network Device monitor cannot be retargeted. Delete it and create a manual monitor for a different device instead.",
+      );
+    }
+  }
+
+  private static normalizeMonitorSteps(
+    monitorSteps: MonitorSteps | JSONObject | undefined,
+    subject: string,
+  ): MonitorSteps {
+    if (monitorSteps instanceof MonitorSteps) {
+      return monitorSteps;
+    }
+
+    if (!monitorSteps) {
+      throw new BadDataException(`${subject} monitor steps are required.`);
+    }
+
+    try {
+      return MonitorSteps.fromJSON(monitorSteps);
+    } catch {
+      throw new BadDataException(`${subject} monitor steps are invalid.`);
+    }
+  }
+
+  private static buildDeviceIdentifiableName(data: {
+    monitorTemplate: MonitorTemplate;
+    networkDevice: NetworkDevice;
+  }): string {
+    const networkDeviceId: string = data.networkDevice.id!.toString();
+    const deviceIdentity: string =
+      data.networkDevice.name?.trim() ||
+      data.networkDevice.hostname?.trim() ||
+      `Network Device ${networkDeviceId}`;
+    const templateMonitorName: string =
+      data.monitorTemplate.monitorName?.trim() || "Monitor";
+
+    return this.truncateWithoutSplittingSurrogatePair(
+      `${deviceIdentity} - ${templateMonitorName}`,
+      ColumnLength.ShortText,
+    );
+  }
+
+  private static truncateWithoutSplittingSurrogatePair(
+    value: string,
+    maximumLength: number,
+  ): string {
+    if (value.length <= maximumLength) {
+      return value;
+    }
+
+    const truncated: string = value.substring(0, maximumLength);
+    const finalCodeUnit: number = truncated.charCodeAt(truncated.length - 1);
+
+    // A cut between an astral character's UTF-16 surrogate pair is invalid.
+    if (finalCodeUnit >= 0xd800 && finalCodeUnit <= 0xdbff) {
+      return truncated.substring(0, truncated.length - 1);
+    }
+
+    return truncated;
+  }
+
+  private static cloneCustomFields(customFields: JSONObject): JSONObject {
+    return JSONFunctions.deserialize(JSONFunctions.serialize(customFields));
+  }
+}