@oneuptime/common 12.0.29 → 12.0.31

package/Utils/EnterpriseLicense/EnterpriseLicenseSeats.ts

@@ -0,0 +1,271 @@
+import EnterpriseLicenseInstanceSummary from "../../Types/EnterpriseLicense/EnterpriseLicenseInstanceSummary";
+
+/*
+ * Everything the seat calculation needs, taken as plain values so this file
+ * stays a pure function the tests can drive directly. The server reads these
+ * off GlobalConfig; the browser reads them off the /global-config/license
+ * response.
+ */
+export interface SeatUsageInput {
+  /*
+   * The seat limit mirrored from oneuptime.com. Null, undefined or anything
+   * that is not a positive whole number means "no limit to enforce" — see
+   * getSeatUsage for why zero is included in that.
+   */
+  userLimit?: number | null | undefined;
+
+  /*
+   * Users that exist on THIS installation right now. The live number, counted
+   * at the moment of the check rather than taken from the last daily report,
+   * because the whole point of enforcement is to catch the user who is being
+   * added a second after the report was sent.
+   */
+  localUserCount: number;
+
+  /*
+   * Unique users across every instance sharing this license, as oneuptime.com
+   * last computed it. Up to a day stale, and only meaningful for a customer
+   * running more than one instance on one key.
+   */
+  aggregatedUserCount?: number | null | undefined;
+
+  /*
+   * Per-instance breakdown from the same report. Used only to work out how
+   * much of aggregatedUserCount belongs to OTHER instances.
+   */
+  instances?: Array<EnterpriseLicenseInstanceSummary> | null | undefined;
+
+  // This installation's own instance id, so it can find itself in `instances`.
+  thisInstanceId?: string | null | undefined;
+}
+
+export interface SeatUsage {
+  /*
+   * False when the license carries no usable seat limit. Every other field is
+   * still filled in — a caller that wants to display usage can, it just must
+   * not block anything.
+   */
+  isEnforced: boolean;
+
+  // The limit actually being enforced, or null when there is none.
+  userLimit: number | null;
+
+  /*
+   * The best estimate of how many licensed seats are consumed right now,
+   * across every instance on this license. See getSeatUsage for how it is
+   * derived and which way it is allowed to be wrong.
+   */
+  seatsInUse: number;
+
+  // Null when there is no limit. Never negative — a breach reads as 0 free.
+  seatsRemaining: number | null;
+
+  /*
+   * The single question enforcement asks. True whenever there is no limit, so
+   * a caller can use this on its own without re-checking isEnforced.
+   */
+  hasSeatForNewUser: boolean;
+
+  /*
+   * How many of seatsInUse are users this installation has never seen. Zero
+   * whenever the topology is not known well enough to say, which is the
+   * conservative answer — see getSeatUsage.
+   */
+  seatsUsedByOtherInstances: number;
+}
+
+export default class EnterpriseLicenseSeatsUtil {
+  /*
+   * How many seats are in use, and whether one more user fits.
+   *
+   * The awkward part is that a license is shared by every instance the
+   * customer runs, and only oneuptime.com can deduplicate users across them —
+   * the same person on staging and production is one seat. So this instance
+   * has two numbers and neither one is the answer on its own:
+   *
+   *   localUserCount      live, but blind to the customer's other instances.
+   *   aggregatedUserCount complete, but up to a day old, so it does not know
+   *                       about anyone added since the last daily report —
+   *                       including the user being added right now.
+   *
+   * Combining them needs to know how much of the aggregate is NOT ours, which
+   * is what the per-instance breakdown is for: subtract our own last reported
+   * count from the aggregate and what is left is other instances. Add the live
+   * local count back and the result is current on this instance and complete
+   * on the others.
+   *
+   * When the breakdown does not say — an older license server that sends no
+   * instance list, an instance that has never registered — there is nothing to
+   * subtract, and the fallback is the larger of the two numbers on their own.
+   * That is the only case where the stale aggregate decides anything: with a
+   * usable breakdown it is deliberately NOT maxed in, because it would then
+   * outvote the live count in the one direction that hurts. Free twenty seats
+   * by deleting twenty users and a stale aggregate would go on refusing new
+   * ones until the next daily report.
+   *
+   * Which way it is allowed to be wrong: under-enforcing is recoverable (the
+   * next daily report corrects the count, and the breach emails already go
+   * out), over-enforcing locks a paying customer out of their own instance.
+   * So every "I cannot tell" branch below resolves towards under-enforcing.
+   */
+  public static getSeatUsage(input: SeatUsageInput): SeatUsage {
+    const userLimit: number | null = this.parseUserLimit(input.userLimit);
+    const localUserCount: number = this.parseCount(input.localUserCount) ?? 0;
+    const aggregatedUserCount: number | null = this.parseCount(
+      input.aggregatedUserCount,
+    );
+
+    /*
+     * Null means the report is not complete enough to attribute seats to
+     * anybody, which is a different thing from attributing zero to them.
+     */
+    const otherInstanceSeats: number | null = this.getSeatsUsedByOtherInstances(
+      {
+        aggregatedUserCount: aggregatedUserCount,
+        instances: input.instances,
+        thisInstanceId: input.thisInstanceId,
+      },
+    );
+
+    const seatsUsedByOtherInstances: number = otherInstanceSeats ?? 0;
+
+    const seatsInUse: number =
+      otherInstanceSeats === null
+        ? Math.max(localUserCount, aggregatedUserCount ?? 0)
+        : otherInstanceSeats + localUserCount;
+
+    if (userLimit === null) {
+      return {
+        isEnforced: false,
+        userLimit: null,
+        seatsInUse: seatsInUse,
+        seatsRemaining: null,
+        hasSeatForNewUser: true,
+        seatsUsedByOtherInstances: seatsUsedByOtherInstances,
+      };
+    }
+
+    return {
+      isEnforced: true,
+      userLimit: userLimit,
+      seatsInUse: seatsInUse,
+      seatsRemaining: Math.max(0, userLimit - seatsInUse),
+      hasSeatForNewUser: seatsInUse < userLimit,
+      seatsUsedByOtherInstances: seatsUsedByOtherInstances,
+    };
+  }
+
+  /*
+   * The message an administrator reads when a seat could not be taken. Built
+   * here rather than at each throw site so the invite form, the signup form
+   * and SSO/SCIM provisioning all explain the same thing the same way, and so
+   * the tests can assert on it without copying the wording.
+   */
+  public static getSeatLimitReachedMessage(data: {
+    seatsInUse: number;
+    userLimit: number;
+  }): string {
+    return (
+      `This OneUptime installation has reached the ${data.userLimit.toLocaleString()}-user ` +
+      `limit of its enterprise license (${data.seatsInUse.toLocaleString()} in use). New users ` +
+      `cannot be invited, signed up or provisioned until a seat is freed up or the license is ` +
+      `expanded. Contact sales@oneuptime.com to add seats, then use "Refresh license" in the ` +
+      `edition dialog to apply the new limit.`
+    );
+  }
+
+  /*
+   * The part of the aggregate that belongs to instances other than this one,
+   * or null when the report does not say.
+   *
+   * Null rather than zero, because the two lead somewhere different: zero means
+   * "this installation is the only one holding seats", and null means "the
+   * report cannot be decomposed, fall back to comparing the two totals". Every
+   * missing or unusable field lands on null.
+   *
+   * In particular, an instance list that does not contain us is NOT treated as
+   * "then all of the aggregate is somebody else's". That reading is right for a
+   * genuinely unregistered instance, and catastrophic for an instance whose id
+   * changed after its users were already counted under the old one: it would
+   * count this installation's users twice and lock it out.
+   */
+  private static getSeatsUsedByOtherInstances(data: {
+    aggregatedUserCount: number | null;
+    instances?: Array<EnterpriseLicenseInstanceSummary> | null | undefined;
+    thisInstanceId?: string | null | undefined;
+  }): number | null {
+    const aggregatedUserCount: number | null = data.aggregatedUserCount;
+
+    if (aggregatedUserCount === null) {
+      return null;
+    }
+
+    if (!Array.isArray(data.instances) || data.instances.length === 0) {
+      return null;
+    }
+
+    const thisInstanceId: string =
+      typeof data.thisInstanceId === "string" ? data.thisInstanceId.trim() : "";
+
+    if (!thisInstanceId) {
+      return null;
+    }
+
+    const thisInstance: EnterpriseLicenseInstanceSummary | undefined =
+      data.instances.find(
+        (instance: EnterpriseLicenseInstanceSummary): boolean => {
+          return Boolean(instance) && instance.instanceId === thisInstanceId;
+        },
+      );
+
+    if (!thisInstance) {
+      return null;
+    }
+
+    const ownReportedCount: number | null = this.parseCount(
+      thisInstance.userCount,
+    );
+
+    if (ownReportedCount === null) {
+      return null;
+    }
+
+    return Math.max(0, aggregatedUserCount - ownReportedCount);
+  }
+
+  /*
+   * A limit is only a limit when it is a positive whole number.
+   *
+   * Zero is deliberately read as "no limit" rather than "no seats at all",
+   * matching every other place in the product that measures seat usage
+   * (the license modal, the breach notification job). A license that really
+   * grants nobody an account is not a thing OneUptime issues, and reading a
+   * stray zero the other way would leave an installation unable to create even
+   * its first user.
+   */
+  private static parseUserLimit(value: unknown): number | null {
+    if (
+      typeof value !== "number" ||
+      !Number.isFinite(value) ||
+      !Number.isInteger(value) ||
+      value <= 0
+    ) {
+      return null;
+    }
+
+    return value;
+  }
+
+  private static parseCount(value: unknown): number | null {
+    if (
+      typeof value !== "number" ||
+      !Number.isFinite(value) ||
+      !Number.isInteger(value) ||
+      value < 0
+    ) {
+      return null;
+    }
+
+    return value;
+  }
+}

package/Utils/NetworkDiscovery/AutoImportRuleMatcher.ts

@@ -34,6 +34,12 @@ import ScanTargetUtil from "./ScanTargetUtil";
  */
 export interface AutoImportRuleCandidate {
   monitorTemplateId?: ObjectID | string | null | undefined;
+  /*
+   * The OID Collection Template imported devices are LINKED to. Purely
+   * carried through the matcher: it never affects whether a host matches,
+   * only what the resulting device collects.
+   */
+  oidTemplateId?: ObjectID | string | null | undefined;
   ipMatchTarget?: string | null | undefined;
   sysNamePattern?: string | null | undefined;
   sysDescrPattern?: string | null | undefined;

package/Utils/NetworkDiscovery/DiscoveredDeviceBuilder.ts

@@ -6,6 +6,7 @@ import SnmpScanConfigUtil, {
   DiscoveryScanSnmpConfig,
 } from "./SnmpScanConfigUtil";
 import { monitoringMethodForDiscoveredHost } from "./DiscoveryImportEligibility";
+import { normalizeReverseDnsName } from "./ReverseDnsNameUtil";
 
 /*
  * One discovered host -> one NetworkDevice, the same way everywhere.
@@ -38,14 +39,84 @@ function truncate(value: string, maxLength: number): string {
   return value.length > maxLength ? value.substring(0, maxLength) : value;
 }
 
-/** The name a discovered host imports under: its sysName, or its address. */
-export function buildDeviceName(host: DiscoveredNetworkDevice): string {
-  return truncate(
-    (host.sysName || "").trim() || host.ipAddress,
-    MAX_DEVICE_NAME_LENGTH,
+/**
+ * What a discovered host is CALLED — in the Review dialog, and (clamped by
+ * `buildDeviceName`) on the device it imports as.
+ *
+ * Three sources, in this order, first non-empty wins:
+ *
+ *   1. `sysName`, the name the device gives for itself over SNMP. It stays
+ *      first because it always has been, and because it is the one name the
+ *      device itself asserts: demoting it would silently rename devices that
+ *      import correctly today, which nobody asked for.
+ *   2. `dnsHostname`, its reverse-DNS (PTR) name (OneUptime issue #3529).
+ *      This is the whole point of the addition, and it lands exactly where
+ *      the complaint was: a host with no readable SNMP has no sysName, so
+ *      before this it fell straight through to its address. On an estate that
+ *      keeps DNS records — the reporter's does — that turns a review list of
+ *      "10.18.166.51, 10.18.166.53, ..." into names an operator recognises.
+ *   3. The address, unchanged, when neither name exists.
+ *
+ * Split out of `buildDeviceName` so the dashboard row and the device it
+ * creates cannot disagree: the operator ticks a box next to a name, and that
+ * is the name the device gets. Returned UNTRUNCATED, so a caller that wants
+ * the full name can have it; the Review dialog and the import both go through
+ * `buildDeviceName`, which clamps, so that what is shown is what is created.
+ *
+ * TWO CONSEQUENCES OF NAMING A DEVICE BY DNS, both accepted deliberately:
+ *
+ *   - Anything that matches on `NetworkDevice.name` now sees a name the
+ *     SCANNED NETWORK chose. NetworkSiteAssignmentRule and the label/owner
+ *     rule engines are the live examples: a rule written against a naming
+ *     convention will match differently for a host that used to be called
+ *     "10.18.166.51" and is now called "core-gw.corp.example.com". That is
+ *     inherent to the feature — the alternative is not naming devices by DNS —
+ *     and it is why the name is put through ReverseDnsNameUtil rather than
+ *     trusted. Rules keyed on `hostname` are unaffected: that stays the IP.
+ *   - Names stop being unique per host. Addresses were; PTR names are not, and
+ *     a wildcard reverse zone over a DHCP range gives every host in it the
+ *     same answer. `buildFallbackDeviceName` is the answer to that, and BOTH
+ *     import paths must use it — the rule engine does, and the dashboard's
+ *     Review-dialog import does since the same wildcard case made collisions
+ *     ordinary rather than rare.
+ */
+export function getDiscoveredHostDisplayName(
+  host: DiscoveredNetworkDevice,
+): string {
+  /*
+   * The PTR name is re-normalised here rather than trusted from the column.
+   * `discoveredDevices` is jsonb stored verbatim from the probe's payload, so
+   * "the probe already checked it" holds only for the probe version that
+   * wrote the row — not for a result from an older or a modified probe, and
+   * not for a row written straight through the API. This function is the last
+   * point before the value becomes a rendered line and a slugified device
+   * name, so it is the right place to be sure. See ReverseDnsNameUtil.
+   */
+  /*
+   * `sysName` is read through a typeof guard rather than trusted, for the
+   * same reason `dnsHostname` is normalised: both come out of the same
+   * verbatim jsonb blob, where the declared TypeScript type is a description
+   * of what the probe SHOULD send rather than a guarantee about what is
+   * stored. `(42).trim()` is a TypeError, and since this function became the
+   * dashboard's name line that TypeError would be thrown during render —
+   * taking out the whole Review dialog rather than one row, which is
+   * precisely the failure normalizeDiscoveredHosts was written to end.
+   */
+  const sysName: string =
+    typeof host.sysName === "string" ? host.sysName.trim() : "";
+
+  return (
+    sysName ||
+    normalizeReverseDnsName(host.dnsHostname) ||
+    String(host.ipAddress ?? "")
   );
 }
 
+/** The name a discovered host imports under, clamped to the slug's ceiling. */
+export function buildDeviceName(host: DiscoveredNetworkDevice): string {
+  return truncate(getDiscoveredHostDisplayName(host), MAX_DEVICE_NAME_LENGTH);
+}
+
 /**
  * The fallback name when `buildDeviceName`'s answer is already taken.
  *
@@ -56,12 +127,42 @@ export function buildDeviceName(host: DiscoveredNetworkDevice): string {
  * ceiling.
  */
 export function buildFallbackDeviceName(host: DiscoveredNetworkDevice): string {
-  const suffix: string = ` (${host.ipAddress})`;
+  /*
+   * The address is read through the SAME coercion the display path uses, not
+   * straight out of the jsonb.
+   *
+   * A raw template read turned a missing address into the literal
+   * " (undefined)" and an object one into " ([object Object])" — and those
+   * tokens are IDENTICAL for every such host, so the fallback produced the
+   * same name again and the retry failed on the very duplicate it was
+   * retrying. This function exists to break a name collision; a suffix that
+   * collides is worse than useless.
+   */
+  const address: string = String(host.ipAddress ?? "").trim();
+
+  /*
+   * An address-less host gets no suffix at all rather than an empty pair of
+   * brackets. There is nothing to tell it apart BY, so the honest outcome is
+   * the base name unchanged — the caller's create then fails on the duplicate,
+   * which is the truth, instead of succeeding under a name that pretends to
+   * carry an address.
+   */
+  const suffix: string = address ? ` (${address})` : "";
+
   const baseName: string = buildDeviceName(host);
 
-  return (
+  /*
+   * Clamped as a whole, not just the base. `Math.max(1, ...)` keeps a
+   * character of the base name however long the suffix is, so an absurd
+   * address — the field is never validated on this path, it is whatever the
+   * probe wrote — could compose a name past the ceiling and fail the create on
+   * the slug's own length, which is the exact overflow the ceiling exists to
+   * prevent.
+   */
+  return truncate(
     truncate(baseName, Math.max(1, MAX_DEVICE_NAME_LENGTH - suffix.length)) +
-    suffix
+      suffix,
+    MAX_DEVICE_NAME_LENGTH,
   );
 }
 
@@ -119,14 +220,40 @@ export function buildNetworkDeviceFromDiscoveredHost(data: {
    * and decides, which is the existing contract for hand-made devices.
    */
   autoApplyVendorHealthTemplate?: boolean | undefined;
+  /*
+   * The OID Collection Template an auto-import rule linked this device to.
+   * Set at create so the device collects its type's OIDs from its very first
+   * poll, with nobody having to touch it afterwards.
+   */
+  oidTemplateId?: ObjectID | undefined;
 }): NetworkDevice {
   const host: DiscoveredNetworkDevice = data.host;
 
   const device: NetworkDevice = new NetworkDevice();
   device.projectId = data.projectId;
   device.name = data.name || buildDeviceName(host);
-  // The address is the device's hostname AND the registered-host dedup key.
-  device.hostname = host.ipAddress;
+  /*
+   * The address is the device's hostname AND the registered-host dedup key.
+   *
+   * It stays the ADDRESS even when the host resolved a PTR name, which is
+   * what issue #3529 asked for in as many words ("retain the IP address as
+   * the address/IP field"), and what the rest of the system needs: this
+   * column is what the ingest path matches a scan's results against
+   * (NetworkDeviceService.getRegisteredHostnames), what the SNMP poller
+   * dials, and what a trap's source IP is correlated to. Storing a name here
+   * would make a device stop polling the day its reverse zone changed, and
+   * would make the same host import twice — once by address, once by name.
+   * The PTR record names the device; it does not address it.
+   *
+   * COERCED, because the dedup key has to be a string. The value comes out of
+   * jsonb, and `getRegisteredHostnames` matches it with `Set.has()` against
+   * hostnames read back from the database — and `Set.has` does not coerce, so
+   * a numeric address stored raw would never match its own registered device
+   * and the host would import again on every review. The dashboard path is
+   * already covered by normalizeDiscoveredHosts; this makes the builder safe
+   * for the rule engine and for any future caller that holds a raw row.
+   */
+  device.hostname = String(host.ipAddress ?? "").trim();
 
   if (host.sysDescr) {
     device.description = truncate(host.sysDescr, MAX_DEVICE_DESCRIPTION_LENGTH);
@@ -145,6 +272,10 @@ export function buildNetworkDeviceFromDiscoveredHost(data: {
     return device;
   }
 
+  if (data.oidTemplateId) {
+    device.oidTemplateId = data.oidTemplateId;
+  }
+
   if (data.autoApplyVendorHealthTemplate) {
     device.autoApplyVendorHealthTemplate = true;
   }

package/Utils/NetworkDiscovery/DiscoveredHostUtil.ts

@@ -1,4 +1,5 @@
 import { DiscoveredNetworkDevice } from "../../Models/DatabaseModels/NetworkDeviceDiscoveryScan";
+import { normalizeReverseDnsName } from "./ReverseDnsNameUtil";
 
 /*
  * Normalisation for a scan's stored results, shared by every reader of the
@@ -40,7 +41,12 @@ function isDiscoveredHostObject(
  *     import, so whether a device already in the inventory got created a
  *     second time depended on which order the probe happened to list them in.
  *
- * All three are fixed here rather than at each call site, so the row the
+ * A fourth was added with reverse DNS (issue #3529) and is not a probe bug at
+ * all — `dnsHostname` is a value the SCANNED NETWORK chooses, so it is
+ * untrusted by construction rather than by accident, and it is normalised
+ * here for the same reason: one reading of the payload for every reader.
+ *
+ * All of them are fixed here rather than at each call site, so the row the
  * operator sees, the badge above it, the list Import walks, and the hosts an
  * auto-import rule evaluates can never be working from different readings of
  * the same payload.
@@ -60,13 +66,59 @@ export function normalizeDiscoveredHosts(
      * truthy, so it used to pass selectability and import as a Network Device
      * whose hostname was a single space.
      */
-    cleaned.push({
+    const normalized: DiscoveredNetworkDevice = {
       ...host,
       ipAddress:
         host.ipAddress === undefined || host.ipAddress === null
           ? ""
           : String(host.ipAddress).trim(),
-    });
+    };
+
+    /*
+     * `sysName` is read straight out of the jsonb, its declared type is not
+     * enforced by anything, and every reader calls a string method on it. A
+     * numeric sysName reached getDiscoveredHostDisplayName and threw inside
+     * the Review dialog's render, taking out the whole modal rather than one
+     * row — the same failure the null-row case above is about.
+     *
+     * A non-string is blanked rather than STRINGIFIED, which is where this
+     * differs from the address above. `String(null)` is "null" and
+     * `String({})` is "[object Object]", and both are truthy — so stringifying
+     * would not merely fail to name the host, it would win the naming contest
+     * outright and create a device called "null", beating a perfectly good PTR
+     * record on the very same row. An empty string is falsy, so naming falls
+     * through to `dnsHostname` and then to the address, which is exactly what
+     * a host with no readable system name deserves.
+     *
+     * Only rewritten when it is NOT already a string, so a host that never had
+     * the key does not gain an empty one — `sysName` is optional and
+     * `"sysName" in host` is a question other code is entitled to ask.
+     */
+    if (host.sysName !== undefined && typeof host.sysName !== "string") {
+      normalized.sysName = "";
+    }
+
+    /*
+     * The PTR name gets the same treatment, for a sharper version of the same
+     * reason (OneUptime issue #3529): unlike every other field here, its
+     * value was chosen by whoever runs DNS for the scanned subnet — routinely
+     * not this project — and it is stored verbatim in jsonb. So the rules
+     * about what a name may contain are applied on the way OUT of the column
+     * as well as on the way in, and anything that fails them is DELETED
+     * rather than blanked, so a reader that checks `if (host.dnsHostname)`
+     * and a reader that checks `"dnsHostname" in host` cannot disagree.
+     */
+    const dnsHostname: string | undefined = normalizeReverseDnsName(
+      host.dnsHostname,
+    );
+
+    if (dnsHostname) {
+      normalized.dnsHostname = dnsHostname;
+    } else {
+      delete normalized.dnsHostname;
+    }
+
+    cleaned.push(normalized);
   }
 
   // An address the scan reports as registered is registered on every row.