@oneuptime/common 12.0.34 → 13.0.1

package/Server/Utils/Monitor/NetworkDeviceMacLearningUtil.ts

@@ -0,0 +1,158 @@
+import NetworkDevice from "../../../Models/DatabaseModels/NetworkDevice";
+import NetworkDeviceService from "../../Services/NetworkDeviceService";
+import QueryHelper from "../../Types/Database/QueryHelper";
+import LIMIT_MAX from "../../../Types/Database/LimitMax";
+import ObjectID from "../../../Types/ObjectID";
+import DeviceMacLearningUtil, {
+  MacLearningCandidateDevice,
+  MacLearningIpBinding,
+  MacLearningPlanEntry,
+} from "../../../Utils/Monitor/DeviceMacLearningUtil";
+import logger from "../Logger";
+
+/*
+ * Fills NetworkDevice.macAddress from a walked router's ARP table.
+ *
+ * Runs once per successful walk that carried ARP entries, after the
+ * endpoint inventory has been written. The decision of WHICH devices to
+ * stamp is DeviceMacLearningUtil.planMacLearning (pure, tested without a
+ * database); this only fetches the candidates and applies the plan.
+ *
+ * The write is hook-free and compare-and-set: a row is stamped only while
+ * its MAC column still holds what the plan saw (NULL for a first learn, the
+ * previously learned MAC for a correction), so an operator who types a MAC
+ * between the read and the write keeps theirs, and two walks racing on one
+ * row cannot both land. A stable site plans nothing - every device already
+ * holds what the table says - so it costs one indexed read per walk and no
+ * writes, which is what keeps this affordable at fleet scale.
+ *
+ * The write cannot tell the caller whether the compare-and-set matched a
+ * row, so the result counts what was PLANNED, not what landed.
+ */
+
+// Same chunking NetworkDeviceService.getDevicesByHostnames uses.
+const HOSTNAME_LOOKUP_CHUNK_SIZE: number = 500;
+
+export interface MacLearningResult {
+  candidateDeviceCount: number;
+  // Writes issued. A compare-and-set that matched nothing is not subtracted.
+  plannedCount: number;
+}
+
+export default class NetworkDeviceMacLearningUtil {
+  public static async learnFromArpBindings(data: {
+    projectId: ObjectID;
+    // The router (or L3 switch) whose ARP table this is.
+    observingDeviceId: ObjectID;
+    observingSiteId: ObjectID | undefined;
+    ipBindings: Array<MacLearningIpBinding>;
+  }): Promise<MacLearningResult> {
+    const addresses: Array<string> = Array.from(
+      new Set<string>(
+        data.ipBindings
+          .map((binding: MacLearningIpBinding) => {
+            return (binding.ipAddress || "").trim();
+          })
+          .filter((ip: string) => {
+            return ip.length > 0;
+          }),
+      ),
+    );
+
+    if (addresses.length === 0) {
+      return { candidateDeviceCount: 0, plannedCount: 0 };
+    }
+
+    /*
+     * Every live device in the project registered at one of the bound
+     * addresses. Not filtered by site or by an empty MAC column in SQL:
+     * the planner needs to SEE a second device at the same address, or a
+     * device that already has a MAC, to refuse correctly - a query that
+     * hid them would make "exactly one" true by accident.
+     */
+    const candidates: Array<MacLearningCandidateDevice> = [];
+
+    for (
+      let offset: number = 0;
+      offset < addresses.length;
+      offset += HOSTNAME_LOOKUP_CHUNK_SIZE
+    ) {
+      const chunk: Array<string> = addresses.slice(
+        offset,
+        offset + HOSTNAME_LOOKUP_CHUNK_SIZE,
+      );
+
+      const devices: Array<NetworkDevice> = await NetworkDeviceService.findBy({
+        query: {
+          projectId: data.projectId,
+          hostname: QueryHelper.any(chunk),
+          isArchived: false,
+        },
+        select: {
+          _id: true,
+          hostname: true,
+          siteId: true,
+          macAddress: true,
+          isMacAddressLearned: true,
+        },
+        limit: LIMIT_MAX,
+        skip: 0,
+        props: {
+          isRoot: true,
+        },
+      });
+
+      for (const device of devices) {
+        if (!device.id) {
+          continue;
+        }
+        candidates.push({
+          id: device.id.toString(),
+          hostname: device.hostname,
+          siteId: device.siteId?.toString(),
+          macAddress: device.macAddress,
+          isMacAddressLearned: device.isMacAddressLearned,
+        });
+      }
+    }
+
+    const plan: Array<MacLearningPlanEntry> =
+      DeviceMacLearningUtil.planMacLearning({
+        ipBindings: data.ipBindings,
+        devices: candidates,
+        observingSiteId: data.observingSiteId?.toString(),
+      });
+
+    let plannedCount: number = 0;
+
+    for (const entry of plan) {
+      await NetworkDeviceService.updateColumnsByIdWithoutHooks({
+        id: new ObjectID(entry.deviceId),
+        data: {
+          macAddress: entry.macAddress,
+          isMacAddressLearned: true,
+        } as any,
+        /*
+         * Only while the column still holds what the plan saw - empty, or
+         * the learned value being corrected - and never a row that was
+         * deleted between the read and this write.
+         */
+        expectedData: {
+          macAddress: entry.previousMacAddress,
+          deletedAt: null,
+        } as any,
+      });
+      plannedCount++;
+
+      logger.debug(
+        `Planned MAC ${entry.macAddress} for network device ${entry.deviceId} (${entry.ipAddress}) from the ARP table of device ${data.observingDeviceId.toString()}${
+          entry.previousMacAddress
+            ? `, correcting the learned ${entry.previousMacAddress}`
+            : ""
+        }; skipped if the column changed meanwhile.`,
+      );
+    }
+
+    return { candidateDeviceCount: candidates.length, plannedCount };
+  }
+}

package/Server/Utils/Monitor/NetworkInventoryUtil.ts

@@ -1,6 +1,7 @@
 import NetworkDevice from "../../../Models/DatabaseModels/NetworkDevice";
 import NetworkDeviceService from "../../Services/NetworkDeviceService";
 import NetworkEndpointService from "../../Services/NetworkEndpointService";
+import NetworkDeviceMacLearningUtil from "./NetworkDeviceMacLearningUtil";
 import NetworkInterfaceService, {
   InterfaceWalkUpsertResult,
 } from "../../Services/NetworkInterfaceService";
@@ -445,6 +446,32 @@ export default class NetworkInventoryUtil {
             now: now,
           });
         }
+
+        /*
+         * --- Device MAC learning (ARP) ---
+         * The ARP table also names the MACs of managed devices registered
+         * at the addresses it binds - the ping-only registers and handsets
+         * that the switches' forwarding tables can put on a port, but only
+         * once something has said which MAC is theirs. Stamped on the
+         * device, once, while its MAC column is empty. Its own try/catch:
+         * the endpoint inventory above is already written, and a failure
+         * here must not read as one there.
+         */
+        if (endpointResult.ipBindings.length > 0) {
+          try {
+            await NetworkDeviceMacLearningUtil.learnFromArpBindings({
+              projectId: data.projectId,
+              observingDeviceId: deviceId,
+              observingSiteId: ownedDevice.siteId,
+              ipBindings: endpointResult.ipBindings,
+            });
+          } catch (err) {
+            logger.error(
+              `Failed to learn device MAC addresses from the ARP table of network device ${deviceId.toString()}:`,
+            );
+            logger.error(err);
+          }
+        }
       }
     } catch (err) {
       // Inventory bookkeeping must never fail the walk pipeline.

package/Server/Utils/Monitor/SeriesResourceLabels.ts

@@ -118,6 +118,26 @@ export const CephClusterNameLabelKeys: ReadonlyArray<string> = [
   "ceph.cluster.name",
 ];
 
+/*
+ * vCenter identity rides the agent-stamped resource attribute
+ * (`vmware.vcenter.name` — one value per vCenter Server or standalone
+ * ESXi host the VMware Agent connects to) and its ClickHouse
+ * `resource.`-prefixed twin. Ingest keys vCenter rows by name only —
+ * there is no `oneuptime.*.id` stamp for vCenters — so only name keys
+ * exist. The name maps to the VMwareVCenter model's `name` column. The
+ * shipped VMware alert templates group by the vSphere object's own
+ * resource attribute (`resource.vcenter.host.name`,
+ * `resource.vcenter.vm.name`, `resource.vcenter.datastore.name`, ...),
+ * so their series labels do NOT carry these keys; the deterministic
+ * vCenter link for those monitors comes from the monitor step config
+ * instead (see MonitorResourceContext). These keys cover user-built
+ * monitors that group by the vCenter attribute.
+ */
+export const VMwareVCenterNameLabelKeys: ReadonlyArray<string> = [
+  "resource.vmware.vcenter.name",
+  "vmware.vcenter.name",
+];
+
 /*
  * IoT fleet identity rides the agent-stamped resource attribute
  * (`iot.fleet.name`) and its ClickHouse `resource.`-prefixed twin.
@@ -188,6 +208,7 @@ export const AllResourceIdentityLabelKeys: ReadonlyArray<string> = [
   ...KubernetesClusterIdLabelKeys,
   ...KubernetesClusterNameLabelKeys,
   ...ProxmoxClusterNameLabelKeys,
+  ...VMwareVCenterNameLabelKeys,
   ...CephClusterNameLabelKeys,
   ...IoTFleetNameLabelKeys,
   ...ServiceIdLabelKeys,
@@ -212,6 +233,7 @@ export interface SeriesResourceRefs {
   kubernetesClusterNames: Array<string>;
   dockerSwarmClusterNames: Array<string>;
   proxmoxClusterNames: Array<string>;
+  vmwareVCenterNames: Array<string>;
   cephClusterNames: Array<string>;
   iotFleetNames: Array<string>;
   serviceIds: Array<string>;
@@ -288,6 +310,10 @@ export default class SeriesResourceLabels {
         seriesLabels,
         ProxmoxClusterNameLabelKeys,
       ),
+      vmwareVCenterNames: this.collectLabelValues(
+        seriesLabels,
+        VMwareVCenterNameLabelKeys,
+      ),
       cephClusterNames: this.collectLabelValues(
         seriesLabels,
         CephClusterNameLabelKeys,

package/Server/Utils/Monitor/SeriesResourceLinker.ts

@@ -7,6 +7,7 @@ import KubernetesCluster from "../../../Models/DatabaseModels/KubernetesCluster"
 import PodmanHost from "../../../Models/DatabaseModels/PodmanHost";
 import ProxmoxCluster from "../../../Models/DatabaseModels/ProxmoxCluster";
 import Service from "../../../Models/DatabaseModels/Service";
+import VMwareVCenter from "../../../Models/DatabaseModels/VMwareVCenter";
 import Includes from "../../../Types/BaseDatabase/Includes";
 import { LIMIT_PER_PROJECT } from "../../../Types/Database/LimitMax";
 import { JSONObject } from "../../../Types/JSON";
@@ -21,6 +22,7 @@ import KubernetesClusterService from "../../Services/KubernetesClusterService";
 import PodmanHostService from "../../Services/PodmanHostService";
 import ProxmoxClusterService from "../../Services/ProxmoxClusterService";
 import ServiceService from "../../Services/ServiceService";
+import VMwareVCenterService from "../../Services/VMwareVCenterService";
 import QueryHelper from "../../Types/Database/QueryHelper";
 import SeriesResourceLabels, {
   SeriesResourceRefs,
@@ -63,6 +65,7 @@ export interface SeriesLinkableModel {
   kubernetesClusters?: Array<KubernetesCluster> | undefined;
   services?: Array<Service> | undefined;
   proxmoxClusters?: Array<ProxmoxCluster> | undefined;
+  vmwareVCenters?: Array<VMwareVCenter> | undefined;
   cephClusters?: Array<CephCluster> | undefined;
   dockerSwarmClusters?: Array<DockerSwarmCluster> | undefined;
   iotFleets?: Array<IoTFleet> | undefined;
@@ -79,6 +82,7 @@ export interface SeriesResolvedResourceIds {
   kubernetesClusterIds: Array<string>;
   serviceIds: Array<string>;
   proxmoxClusterIds: Array<string>;
+  vmwareVCenterIds: Array<string>;
   cephClusterIds: Array<string>;
   dockerSwarmClusterIds: Array<string>;
   iotFleetIds: Array<string>;
@@ -151,7 +155,7 @@ export default class SeriesResourceLinker {
   /*
    * The one place that turns identifiers into database ids, shared by
    * the series-label path and the monitor-step-config path
-   * (MonitorStepResourceIdentity). Keeping the nine-way lookup table,
+   * (MonitorStepResourceIdentity). Keeping the ten-way lookup table,
    * the project scoping and the `Includes` batching in a single
    * function is what stops the two paths from resolving the same
    * identifier to different rows.
@@ -164,9 +168,10 @@ export default class SeriesResourceLinker {
     const refs: SeriesResourceRefs = input.refs;
 
     /*
-     * Proxmox / Ceph / Docker Swarm / IoT carry no `oneuptime.*.id`
-     * stamp at ingest — they are addressable by name only — so their
-     * `ids` lists are empty by construction, not by omission.
+     * Proxmox / VMware / Ceph / Docker Swarm / IoT carry no
+     * `oneuptime.*.id` stamp at ingest — they are addressable by name
+     * only — so their `ids` lists are empty by construction, not by
+     * omission.
      */
     const specs: Array<ResourceResolutionSpec> = [
       {
@@ -205,6 +210,12 @@ export default class SeriesResourceLinker {
         nameColumn: "name",
         findBy: ProxmoxClusterService.findBy.bind(ProxmoxClusterService),
       },
+      {
+        ids: [],
+        names: refs.vmwareVCenterNames,
+        nameColumn: "name",
+        findBy: VMwareVCenterService.findBy.bind(VMwareVCenterService),
+      },
       {
         ids: [],
         names: refs.cephClusterNames,
@@ -234,6 +245,7 @@ export default class SeriesResourceLinker {
       kubernetesClusterIds,
       serviceIds,
       proxmoxClusterIds,
+      vmwareVCenterIds,
       cephClusterIds,
       dockerSwarmClusterIds,
       iotFleetIds,
@@ -257,6 +269,7 @@ export default class SeriesResourceLinker {
       kubernetesClusterIds: kubernetesClusterIds || [],
       serviceIds: serviceIds || [],
       proxmoxClusterIds: proxmoxClusterIds || [],
+      vmwareVCenterIds: vmwareVCenterIds || [],
       cephClusterIds: cephClusterIds || [],
       dockerSwarmClusterIds: dockerSwarmClusterIds || [],
       iotFleetIds: iotFleetIds || [],
@@ -385,6 +398,16 @@ export default class SeriesResourceLinker {
       );
     }
 
+    if (resolved.vmwareVCenterIds.length > 0) {
+      model.vmwareVCenters = this.mergeById(
+        model.vmwareVCenters,
+        resolved.vmwareVCenterIds,
+        (): VMwareVCenter => {
+          return new VMwareVCenter();
+        },
+      );
+    }
+
     if (resolved.cephClusterIds.length > 0) {
       model.cephClusters = this.mergeById(
         model.cephClusters,
@@ -452,7 +475,7 @@ export default class SeriesResourceLinker {
   /*
    * Turn one resource type's ids and names into deduped database ids.
    * Costs zero round-trips when the series carries neither, which is the
-   * common case for most of the nine types on any given series.
+   * common case for most of the ten types on any given series.
    *
    * `nameMatch: "exact"` is for series labels. Every identifier column
    * read here is written by ingest from the same attribute the series

package/Server/Utils/ResourceFeed/ResourceFeedUtil.ts

@@ -5,13 +5,13 @@ import UserService from "../../Services/UserService";
 /*
  * Shared formatting for the infrastructure and catalog resource feeds
  * (Kubernetes clusters, Docker / Podman hosts, Docker Swarm / Proxmox / Ceph
- * clusters, servers, cloud resources and catalog services).
+ * clusters, VMware vCenters, servers, cloud resources and catalog services).
  *
  * These resources come into existence two very different ways - somebody adds
  * one by hand, or ingest registers one the first moment telemetry mentions it -
  * and the overview page cannot tell you which happened. That is exactly the
  * question the feed exists to answer, so the wording for it lives here once
- * rather than nine times over.
+ * rather than ten times over.
  */
 
 /*
@@ -20,7 +20,7 @@ import UserService from "../../Services/UserService";
  * Deliberately a whitelist. Every one of these resources is written on each
  * heartbeat (lastSeenAt, otelCollectorStatus, agentVersion, and the rollup
  * counters like nodeCount / containersRunning), so a blacklist would let the
- * next counter column added to any of the nine models silently start posting
+ * next counter column added to any of the ten models silently start posting
  * a feed item every 60 seconds per resource.
  */
 export const MEANINGFUL_UPDATE_COLUMNS: Array<string> = [

package/Server/Utils/SecurityEvent/ConnectorErrorMessage.ts

@@ -27,10 +27,9 @@ import logger from "../Logger";
  * explain the outage are precisely the ones the outage prevented from
  * being written, so the failure is completely silent.
  *
- * Hence the two halves of this file: clamp the message to something a
- * column will always accept, and run the write inside its own try/catch
- * that logs and swallows. Whatever happens, the loop advances to the next
- * item.
+ * Messages are bounded by default; callers storing full diagnostics in a
+ * text column can explicitly disable truncation. The guarded write logs
+ * and swallows persistence failures so the loop advances to the next item.
  */
 
 export const MAX_CONNECTOR_ERROR_MESSAGE_LENGTH: number = 1000;
@@ -52,11 +51,14 @@ const UNKNOWN_ERROR_MESSAGE: string = "Unknown error.";
 
 export default class ConnectorErrorMessage {
   /*
-   * Anything thrown -> a message short enough that storing it cannot be
-   * what fails next. Errors contribute their .message; everything else is
-   * stringified.
+   * Errors contribute their .message; everything else is stringified.
+   * Truncation is the default for existing callers. Disable it only when
+   * the destination supports a complete error message.
    */
-  public static toMessage(error: unknown): string {
+  public static toMessage(
+    error: unknown,
+    options: { truncate?: boolean | undefined } = {},
+  ): string {
     let message: string = "";
 
     if (error instanceof Error) {
@@ -71,7 +73,10 @@ export default class ConnectorErrorMessage {
       return UNKNOWN_ERROR_MESSAGE;
     }
 
-    if (message.length <= MAX_CONNECTOR_ERROR_MESSAGE_LENGTH) {
+    if (
+      options.truncate === false ||
+      message.length <= MAX_CONNECTOR_ERROR_MESSAGE_LENGTH
+    ) {
       return message;
     }