@oneuptime/common 12.0.25 → 12.0.27

package/Utils/NetworkDiscovery/PingMonitorBuilder.ts

@@ -0,0 +1,215 @@
+import Monitor from "../../Models/DatabaseModels/Monitor";
+import { DiscoveredNetworkDevice } from "../../Models/DatabaseModels/NetworkDeviceDiscoveryScan";
+import Hostname from "../../Types/API/Hostname";
+import IP from "../../Types/IP/IP";
+import MonitorCriteriaInstance from "../../Types/Monitor/MonitorCriteriaInstance";
+import MonitorStep from "../../Types/Monitor/MonitorStep";
+import MonitorSteps from "../../Types/Monitor/MonitorSteps";
+import MonitorType from "../../Types/Monitor/MonitorType";
+import ObjectID from "../../Types/ObjectID";
+
+/*
+ * The Ping monitor a ping-only discovered host imports with.
+ *
+ * WHY THIS EXISTS
+ *
+ * A host that answered ICMP but not SNMP imports as a monitor-backed device:
+ * no probe, no credentials, polling off (DiscoveredDeviceBuilder). That is
+ * deliberate — there is nothing to walk it with — but it leaves the device
+ * with NO health source at all. Its status reads "Pending" forever, its
+ * "Last Seen" reads never, and the only way out was for an operator to hand-
+ * create a Ping monitor and hand-bind it, per device. Fourteen discovered
+ * phones meant fourteen monitors and fourteen device edits, which is
+ * OneUptime/oneuptime#3447.
+ *
+ * The probe already proved the host answers ICMP — that is the only reason it
+ * is in the scan results at all (SubnetScanner records a no-SNMP host only
+ * when it was in `pingAliveHosts`). So the monitor this builds is not a guess:
+ * it re-asks, on a schedule, the exact question the scan already answered once.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO
+ *
+ * No database and no permission work — the caller persists it through
+ * MonitorService/ModelAPI so tenant, billing, probe-attachment and status-
+ * timeline hooks still run. Creating a monitor is billable and plan-limited,
+ * so provisioning is always something the operator opted into, never a
+ * side effect of importing.
+ */
+
+/*
+ * Monitor.name is varchar(100), but the real ceiling is the SLUG: Monitor is
+ * @SlugifyColumn("name", "slug") and Slug.getSlug appends a dash plus ten
+ * random digits into its own varchar(100), and the create path THROWS on
+ * overflow rather than truncating. So a name over ~88 characters fails the
+ * create even though the name column would have taken it — the same trap
+ * MAX_DEVICE_NAME_LENGTH exists for on the device side.
+ *
+ * 88 leaves exactly the slug's 11-character tail. Device names already arrive
+ * clamped to 80 by DiscoveredDeviceBuilder and the prefix is 5, so 85 is the
+ * realistic worst case through the import path; this is the backstop for a
+ * device renamed by hand afterwards.
+ */
+export const MAX_PING_MONITOR_NAME_LENGTH: number = 88;
+
+const PING_MONITOR_NAME_PREFIX: string = "Ping ";
+
+/*
+ * How often the provisioned monitor pings, as a cron expression.
+ *
+ * Set explicitly because leaving `monitoringInterval` NULL is NOT "use a
+ * sensible default" — MonitorProbeService falls back to now + 1 MINUTE when
+ * the column is null (both in claimMonitorProbesForProbing's batch UPDATE and
+ * in the per-probe path). Importing a subnet's worth of IP phones would then
+ * ping every one of them every sixty seconds, forever, because nobody chose
+ * that. Five minutes is what the monitor create page pre-seeds, so a
+ * provisioned monitor matches a hand-made one and the operator can change it
+ * from the same dropdown.
+ */
+export const PING_MONITOR_INTERVAL: string = "*/5 * * * *";
+
+/**
+ * The four project-scoped ids every monitor's default criteria are seeded
+ * with. The caller resolves them once per import run — they are properties of
+ * the project, not of any one host — and passes the same set for every device.
+ */
+export interface MonitorCriteriaSeedIds {
+  // The project's operational status, e.g. "Operational".
+  onlineMonitorStatusId: ObjectID;
+  // The project's offline status, e.g. "Offline".
+  offlineMonitorStatusId: ObjectID;
+  defaultIncidentSeverityId: ObjectID;
+  defaultAlertSeverityId: ObjectID;
+}
+
+export interface BuildPingMonitorData {
+  projectId: ObjectID;
+  // The host being imported. Only its address is used.
+  host: DiscoveredNetworkDevice;
+  /*
+   * 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;
+}
+
+/**
+ * The monitor's name: "Ping <device name>", clamped to the column.
+ *
+ * Named after the DEVICE rather than the address because that is what an
+ * operator scanning a monitor list is looking for, and because two devices can
+ * legitimately share an address across separate VRFs while their names differ.
+ */
+export function buildPingMonitorName(deviceName: string): string {
+  const trimmedDeviceName: string = (deviceName || "").trim();
+
+  const composed: string = `${PING_MONITOR_NAME_PREFIX}${trimmedDeviceName}`;
+
+  return composed.length > MAX_PING_MONITOR_NAME_LENGTH
+    ? composed.substring(0, MAX_PING_MONITOR_NAME_LENGTH)
+    : composed;
+}
+
+/**
+ * The destination the monitor pings.
+ *
+ * A discovered host's address is an IP in every case the scanner produces —
+ * it sweeps address ranges — but the column is free text and a hand-written
+ * scan row could hold a name, so anything that does not parse as an IP is
+ * carried as a Hostname rather than rejected. MonitorStep accepts either.
+ */
+export function buildPingMonitorDestination(address: string): IP | Hostname {
+  const trimmedAddress: string = (address || "").trim();
+
+  if (IP.isIP(trimmedAddress)) {
+    return IP.fromString(trimmedAddress);
+  }
+
+  return new Hostname(trimmedAddress);
+}
+
+/**
+ * Turn OFF incident creation on every criteria instance of a step, leaving
+ * `changeMonitorStatus` alone.
+ *
+ * A hand-made Ping monitor defaults to opening an incident when the host stops
+ * answering, which is right for a monitor someone deliberately created for one
+ * service. This is a BULK action: an operator ticking "import 14 hosts" is
+ * recording inventory, and the default would hand them fourteen monitors that
+ * each open an incident — with on-call notifications, workspace posts and
+ * status-page impact — the first time a consumer access point or an IP phone
+ * misses a ping.
+ *
+ * `changeMonitorStatus` stays true because that is the whole point: it is what
+ * moves the monitor's status, which is what the device's status pill reads.
+ * So the device goes Up/Down correctly and nobody gets paged for it. Turning
+ * incidents back on is one edit per monitor, and is the operator's call.
+ */
+function suppressIncidentCreation(step: MonitorStep): void {
+  const criteriaInstances: Array<MonitorCriteriaInstance> =
+    step.data?.monitorCriteria?.data?.monitorCriteriaInstanceArray || [];
+
+  for (const criteriaInstance of criteriaInstances) {
+    if (criteriaInstance.data) {
+      criteriaInstance.data.createIncidents = false;
+    }
+  }
+}
+
+/**
+ * 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).
+ */
+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.",
+    );
+  }
+
+  const monitor: Monitor = new Monitor();
+
+  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.monitorType = MonitorType.Ping;
+  monitor.monitoringInterval = PING_MONITOR_INTERVAL;
+
+  const step: MonitorStep = MonitorStep.getDefaultMonitorStep({
+    monitorName: monitor.name,
+    monitorType: MonitorType.Ping,
+    onlineMonitorStatusId: data.seedIds.onlineMonitorStatusId,
+    offlineMonitorStatusId: data.seedIds.offlineMonitorStatusId,
+    defaultIncidentSeverityId: data.seedIds.defaultIncidentSeverityId,
+    defaultAlertSeverityId: data.seedIds.defaultAlertSeverityId,
+  });
+
+  /*
+   * The destination is what makes the step valid: MonitorStep's validation
+   * rejects a Ping step without one ("Monitor Destination is required").
+   */
+  step.setMonitorDestination(buildPingMonitorDestination(address));
+
+  suppressIncidentCreation(step);
+
+  const monitorSteps: MonitorSteps = new MonitorSteps();
+  monitorSteps.data = {
+    monitorStepsInstanceArray: [step],
+    defaultMonitorStatusId: data.seedIds.onlineMonitorStatusId,
+  };
+
+  monitor.monitorSteps = monitorSteps;
+
+  return monitor;
+}

package/Utils/NetworkDiscovery/RescanIntervalUtil.ts

@@ -0,0 +1,148 @@
+/*
+ * The recurrence cadence of a Network Device Discovery Scan: how often a
+ * recurring scan re-runs, and when the next run is due.
+ *
+ * WHY IT LIVES IN Common
+ *
+ * Four places have an opinion about this number and they must not disagree:
+ *
+ *   - the create/edit form (App Dashboard, DiscoveryScanFormValidation) — so
+ *     the operator is told the floor before they save, not after;
+ *   - the write hooks (Common server service) — which derive `nextScanAt` on
+ *     an edit, because the requeue worker only ever looks at that column and
+ *     a NULL there means "never runs again";
+ *   - the probe-ingest result endpoint (App Telemetry) — which stamps
+ *     `nextScanAt` when a run finishes;
+ *   - the requeue worker (App Workers) — which is sized against this floor.
+ *
+ * The floor and the clamp used to be written out three times, in three
+ * packages, with three chances to drift. Same reason ScanTargetUtil and
+ * ScanNameUtil sit next door.
+ */
+
+import OneUptimeDate from "../../Types/Date";
+
+/*
+ * The shortest cadence a recurring discovery scan may run at.
+ *
+ * A sweep is bounded but heavy: at the ScanTargetUtil.MAX_SCAN_HOSTS ceiling
+ * (32,768 addresses) it can take the better part of an hour, and a probe runs
+ * one sweep at a time. Re-queueing more often than this simply stacks scans on
+ * the probe, which never catches up.
+ */
+export const MINIMUM_RESCAN_INTERVAL_IN_MINUTES: number = 15;
+
+export type ClampRescanIntervalFunction = (
+  intervalInMinutes: number | null | undefined,
+) => number | null;
+
+/*
+ * The cadence a stored interval actually runs at.
+ *
+ * Clamped rather than rejected, and that is deliberate: rows written before
+ * the form enforced a floor — and rows written by an API client, which the
+ * server does not refuse — still recur, just no faster than the probe can
+ * keep up with. Returns null for a value that does not describe a cadence at
+ * all (absent, zero, negative, NaN), which is the caller's signal that there
+ * is no next run to schedule.
+ */
+export const clampRescanIntervalInMinutes: ClampRescanIntervalFunction = (
+  intervalInMinutes: number | null | undefined,
+): number | null => {
+  if (
+    typeof intervalInMinutes !== "number" ||
+    !isFinite(intervalInMinutes) ||
+    intervalInMinutes <= 0
+  ) {
+    return null;
+  }
+
+  return Math.max(intervalInMinutes, MINIMUM_RESCAN_INTERVAL_IN_MINUTES);
+};
+
+/*
+ * The scan state that decides when — or whether — a scan runs again. Kept
+ * structural rather than typed as the model, so a partially-selected row
+ * satisfies it and so this module does not drag a database model into the
+ * Probe's bundle. Same shape rule as ScanNameUtil.
+ */
+export interface RescanScheduleInput {
+  isRecurring?: boolean | null | undefined;
+  rescanIntervalInMinutes?: number | null | undefined;
+  /*
+   * "Pending" / "In Progress" / "Completed" / "Failed". A run that is still
+   * queued or in flight has no next run to schedule yet — the ingest endpoint
+   * stamps one when it reports.
+   */
+  status?: string | null | undefined;
+  // When the last run finished. The clock the next run is measured from.
+  completedAt?: Date | null | undefined;
+}
+
+export type GetNextScanAtFunction = (
+  scan: RescanScheduleInput,
+  now: Date,
+) => Date | null;
+
+/*
+ * When a scan is next due, derived from the scan itself.
+ *
+ * `nextScanAt` is not an independent fact, it is a function of the recurrence
+ * settings and the last completion — which is exactly why it can be recomputed
+ * when those settings change. Before it was derived, the only writer was the
+ * result-ingest endpoint at the moment a run finished, so turning recurrence
+ * ON for a scan that had already completed stamped nothing: the column stayed
+ * NULL, `("nextScanAt" <= now)` is UNKNOWN for NULL, and the requeue worker
+ * never matched the row again. The scan advertised "Every 60 min" in the list
+ * and never ran (OneUptime issue #3444).
+ *
+ * The value returned for an unchanged, already-recurring scan is the same one
+ * the ingest endpoint stamped (it wrote `completedAt + interval` too), so
+ * recomputing is a no-op rather than a rescheduling.
+ *
+ *   - not recurring, or no usable interval -> null, i.e. never
+ *   - still Pending or In Progress -> null; the run in flight will stamp it
+ *   - Completed / Failed -> the moment one interval after it finished. Already
+ *     in the past is fine and means "due now": the worker's predicate is
+ *     `nextScanAt <= now`.
+ */
+export const getNextScanAt: GetNextScanAtFunction = (
+  scan: RescanScheduleInput,
+  now: Date,
+): Date | null => {
+  if (!scan.isRecurring) {
+    return null;
+  }
+
+  const intervalInMinutes: number | null = clampRescanIntervalInMinutes(
+    scan.rescanIntervalInMinutes,
+  );
+
+  if (intervalInMinutes === null) {
+    return null;
+  }
+
+  if (scan.status !== "Completed" && scan.status !== "Failed") {
+    return null;
+  }
+
+  /*
+   * A Completed row without a completedAt should not exist — every writer of
+   * one writes the other — but a row hand-edited or written by an older build
+   * still deserves a next run rather than being stranded, so it is scheduled
+   * from now.
+   */
+  const lastRunAt: Date = scan.completedAt || now;
+
+  /*
+   * Deliberately NOT clamped forward to `now`. A moment already in the past is
+   * a correct answer — it means "due, and the worker has not got to it yet" —
+   * and clamping would cost the property that makes this safe to re-derive on
+   * every save: the same row always produces the same answer, so re-posting an
+   * unchanged schedule writes nothing.
+   */
+  return OneUptimeDate.addRemoveMinutes(
+    OneUptimeDate.fromString(lastRunAt),
+    intervalInMinutes,
+  );
+};

package/Utils/NetworkDiscovery/ScanModeUtil.ts

@@ -0,0 +1,105 @@
+/*
+ * What a Network Device Discovery Scan actually probes each address with.
+ *
+ * WHY IT EXISTS
+ *
+ * A discovery scan used to be an SNMP scan, full stop: the sweep pinged every
+ * address as a cheap reachability gate and then asked each live one for its
+ * SNMP system group. That is the right sweep for a subnet of managed gear, and
+ * the wrong one for the case operators kept hitting — "I just want to know what
+ * is alive in 10.20.30.0/24". The wizard had no way to say so, and because
+ * SNMP Version was a required field on its own step, an ICMP-only scan could
+ * not even be submitted: "SNMP Version is required" blocked Next regardless of
+ * intent (OneUptime issue #3445).
+ *
+ * `isSnmpEnabled` on the scan is that missing sentence, and this module is the
+ * one place that reads it.
+ *
+ * WHY THE READ IS `!== false` AND NOT `Boolean(...)`
+ *
+ * Three writers can hand a scan row to this predicate, and only one of them is
+ * guaranteed to have the column:
+ *
+ *   - The database, where the column is NOT NULL DEFAULT true, so every scan
+ *     that predates it reads as SNMP-enabled — which is what those scans were.
+ *   - The probe-ingest payload, where the column only appears if the SERVER is
+ *     new enough to select it. A new probe polling an older server would
+ *     otherwise see `undefined`, read it as "SNMP is off", and quietly stop
+ *     doing SNMP discovery on every scan in the project.
+ *   - A direct API call, which may simply omit it.
+ *
+ * So absence means "SNMP", exactly as it did before the column existed, and
+ * only an EXPLICIT false turns it off. Same defensive shape as
+ * `snmpReachable === false` in DiscoveryImportEligibility, and for the same
+ * reason: the legacy value of a new optional flag has to keep meaning what the
+ * rows already on disk meant.
+ *
+ * WHY IT LIVES IN Common
+ *
+ * The question "does this scan do SNMP?" is asked by the create/edit form (App
+ * Dashboard), the probe-ingest endpoints (App Telemetry), the sweep itself
+ * (Probe) and the results dialog. One copy is what stops the wizard hiding the
+ * SNMP fields for a scan the probe then SNMP-probes anyway. Same reason
+ * ScanNameUtil and ScanTargetUtil sit next door.
+ */
+
+/*
+ * The part of a scan that answers "what does this sweep probe with?".
+ * Structural rather than the model type, so a partially-selected row — the
+ * probe selects a dozen columns, the ingest endpoint fewer — satisfies it, and
+ * so this module stays importable from the Probe without dragging a database
+ * model behind it.
+ */
+export interface DiscoveryScanMode {
+  isSnmpEnabled?: boolean | null | undefined;
+}
+
+/*
+ * How a scan describes itself in one short phrase — for a table cell, a badge,
+ * or a log line. Deliberately names ICMP the way the wizard does ("Ping only")
+ * rather than by protocol, because that is the word the operator chose.
+ */
+export enum ScanMethodLabel {
+  PingAndSnmp = "Ping + SNMP",
+  PingOnly = "Ping only",
+}
+
+export class ScanModeUtil {
+  /**
+   * True when this scan should probe SNMP after the ICMP sweep.
+   *
+   * Absence reads as TRUE — see the module comment. Callers must ask through
+   * this rather than reading the column, so that "the wizard hid the SNMP
+   * fields" and "the probe skipped SNMP" can never disagree.
+   */
+  public static isSnmpEnabled(
+    scan: DiscoveryScanMode | null | undefined,
+  ): boolean {
+    return scan?.isSnmpEnabled !== false;
+  }
+
+  /**
+   * True when this scan is an ICMP ping sweep and nothing else.
+   *
+   * The exact negation of isSnmpEnabled, spelled out because most callers read
+   * better asking the positive question about the case they are handling — a
+   * `showIf` that hides the SNMP step, a status message that must not mention
+   * SNMP — and a bare `!` in front of a predicate is easy to lose in a diff.
+   */
+  public static isIcmpOnly(
+    scan: DiscoveryScanMode | null | undefined,
+  ): boolean {
+    return !ScanModeUtil.isSnmpEnabled(scan);
+  }
+
+  /** The scan's method as a short phrase for a badge or a log line. */
+  public static getMethodLabel(
+    scan: DiscoveryScanMode | null | undefined,
+  ): ScanMethodLabel {
+    return ScanModeUtil.isSnmpEnabled(scan)
+      ? ScanMethodLabel.PingAndSnmp
+      : ScanMethodLabel.PingOnly;
+  }
+}
+
+export default ScanModeUtil;