@oneuptime/common 12.0.30 → 12.0.32

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/Monitor/NetworkDeviceRoleCatalog.ts

@@ -0,0 +1,232 @@
+import {
+  NetworkTopologyDeviceRole,
+  NetworkTopologyNode,
+  NetworkTopologyNodeShape,
+} from "../../Types/Monitor/SnmpMonitor/NetworkTopology";
+
+/*
+ * The project's configured device roles, reduced to what the topology needs.
+ *
+ * WHY THIS EXISTS. Roles are rows now (NetworkDeviceRole), which means the
+ * label a role is drawn with, the silhouette it uses, whether it sits at the
+ * core and whether it is worth walking with SNMP are all per-project answers.
+ * None of them can be compiled into the client any more.
+ *
+ * The client is NOT given the table to look things up in, though. The topology
+ * builder stamps the four answers onto each node as it builds it, so every
+ * consumer downstream - the shape module, three layouts, the legend, the
+ * detail panel, the accessible label - keeps its current pure signature and
+ * needs no catalogue threaded through it. This module is the one place that
+ * turns rows into that stamp.
+ *
+ * Pure and dependency-free so it runs identically on the server, in the
+ * builder, and in the unit tests.
+ */
+
+/** One configured role, as the topology builder needs it. */
+export interface TopologyDeviceRoleInput {
+  id?: string | undefined;
+  key: string;
+  name: string;
+  topologyShape?: string | undefined;
+  isCoreLayer?: boolean | undefined;
+  isSnmpWalkable?: boolean | undefined;
+}
+
+/** What gets stamped onto a node. Every field optional - see stampForRoleKey. */
+export interface TopologyNodeRoleStamp {
+  roleId?: string | undefined;
+  roleKey?: string | undefined;
+  roleLabel?: string | undefined;
+  roleShape?: NetworkTopologyNodeShape | undefined;
+  isCoreLayerRole?: boolean | undefined;
+  isSnmpWalkableRole?: boolean | undefined;
+}
+
+/*
+ * The silhouettes the renderer can actually draw. A row's topologyShape is a
+ * free-text column - the geometry lives in the client and adding a shape must
+ * not need a migration - so a value that is not one of these is dropped rather
+ * than passed through to a renderer that would have no path for it.
+ */
+const KNOWN_SHAPES: ReadonlySet<string> = new Set<string>([
+  "circle",
+  "rounded-square",
+  "diamond",
+  "triangle",
+  "hexagon",
+  "tower",
+  "cylinder",
+  "rect",
+]);
+
+export type NormalizeRoleKeyFunction = (
+  value: string | undefined | null,
+) => string | undefined;
+
+/*
+ * Keys are matched case- and whitespace-insensitively, the same way
+ * parseDeviceRoleOverride reads the stored column, so a hand-edited or
+ * imported "Router " still finds the Router row.
+ */
+export const normalizeRoleKey: NormalizeRoleKeyFunction = (
+  value: string | undefined | null,
+): string | undefined => {
+  const normalized: string = (value || "").trim().toLowerCase();
+  return normalized || undefined;
+};
+
+/**
+ * Index the project's roles for lookup by key.
+ *
+ * Later rows do not overwrite earlier ones on a key clash. The key is unique
+ * per project in the database, so a clash here means the caller passed rows
+ * from more than one project, and quietly taking the last one would draw the
+ * wrong project's shapes.
+ */
+export type BuildRoleIndexFunction = (
+  roles: ReadonlyArray<TopologyDeviceRoleInput>,
+) => Map<string, TopologyDeviceRoleInput>;
+
+export const buildDeviceRoleIndex: BuildRoleIndexFunction = (
+  roles: ReadonlyArray<TopologyDeviceRoleInput>,
+): Map<string, TopologyDeviceRoleInput> => {
+  const index: Map<string, TopologyDeviceRoleInput> = new Map<
+    string,
+    TopologyDeviceRoleInput
+  >();
+
+  for (const role of roles) {
+    const key: string | undefined = normalizeRoleKey(role.key);
+    if (!key || index.has(key)) {
+      continue;
+    }
+    index.set(key, role);
+  }
+
+  return index;
+};
+
+export type StampForRoleKeyFunction = (
+  roleKey: string | undefined,
+  index: Map<string, TopologyDeviceRoleInput>,
+) => TopologyNodeRoleStamp;
+
+/**
+ * The stamp for one role key.
+ *
+ * Returns an EMPTY object when the project has no row for the key - which is
+ * the normal case for a project that has not been backfilled yet, and the
+ * permanent case for a project that deleted a seeded role the classifier can
+ * still produce. Every field a node does not get falls back to the built-in
+ * behaviour on the client, so an empty stamp draws exactly the map that was
+ * drawn before roles were configurable.
+ *
+ * The one field always present when a row IS found is `roleKey`, because the
+ * legend groups by it and a group with no key cannot be grouped.
+ */
+export const stampForRoleKey: StampForRoleKeyFunction = (
+  roleKey: string | undefined,
+  index: Map<string, TopologyDeviceRoleInput>,
+): TopologyNodeRoleStamp => {
+  const normalized: string | undefined = normalizeRoleKey(roleKey);
+  if (!normalized) {
+    return {};
+  }
+
+  const role: TopologyDeviceRoleInput | undefined = index.get(normalized);
+  if (!role) {
+    return {};
+  }
+
+  const stamp: TopologyNodeRoleStamp = {
+    roleKey: role.key,
+  };
+
+  if (role.id) {
+    stamp.roleId = role.id;
+  }
+
+  if (role.name) {
+    stamp.roleLabel = role.name;
+  }
+
+  if (role.topologyShape && KNOWN_SHAPES.has(role.topologyShape)) {
+    stamp.roleShape = role.topologyShape as NetworkTopologyNodeShape;
+  }
+
+  if (role.isCoreLayer !== undefined) {
+    stamp.isCoreLayerRole = Boolean(role.isCoreLayer);
+  }
+
+  if (role.isSnmpWalkable !== undefined) {
+    stamp.isSnmpWalkableRole = Boolean(role.isSnmpWalkable);
+  }
+
+  return stamp;
+};
+
+export type RoleKeyForNodeFunction = (
+  assignedRoleKey: string | undefined,
+  classifiedRole: NetworkTopologyDeviceRole,
+) => string | undefined;
+
+/**
+ * Which key a node's presentation should come from.
+ *
+ * The operator's assignment wins, exactly as it does for `role` itself. With
+ * no assignment the classifier's answer is used, so a project that renamed
+ * "Router" to "Edge Router" sees the new name on devices it never had to
+ * touch. "unknown" is not a key any row holds and is deliberately not looked
+ * up: it is the classifier declining to answer, and a neutral node is the
+ * honest drawing of that.
+ */
+export const roleKeyForNode: RoleKeyForNodeFunction = (
+  assignedRoleKey: string | undefined,
+  classifiedRole: NetworkTopologyDeviceRole,
+): string | undefined => {
+  const assigned: string | undefined = normalizeRoleKey(assignedRoleKey);
+  if (assigned) {
+    return assigned;
+  }
+  if (classifiedRole === "unknown") {
+    return undefined;
+  }
+  return classifiedRole;
+};
+
+export type ApplyRoleStampFunction = (
+  node: NetworkTopologyNode,
+  stamp: TopologyNodeRoleStamp,
+) => void;
+
+/**
+ * Copy a stamp onto a node, omitting the fields it does not carry.
+ *
+ * Assigning undefined rather than omitting would break the payload's own
+ * contract - "absent means fall back" - for any consumer that checks with
+ * `in` or serialises the node, so absent stays absent.
+ */
+export const applyRoleStamp: ApplyRoleStampFunction = (
+  node: NetworkTopologyNode,
+  stamp: TopologyNodeRoleStamp,
+): void => {
+  if (stamp.roleId !== undefined) {
+    node.roleId = stamp.roleId;
+  }
+  if (stamp.roleKey !== undefined) {
+    node.roleKey = stamp.roleKey;
+  }
+  if (stamp.roleLabel !== undefined) {
+    node.roleLabel = stamp.roleLabel;
+  }
+  if (stamp.roleShape !== undefined) {
+    node.roleShape = stamp.roleShape;
+  }
+  if (stamp.isCoreLayerRole !== undefined) {
+    node.isCoreLayerRole = stamp.isCoreLayerRole;
+  }
+  if (stamp.isSnmpWalkableRole !== undefined) {
+    node.isSnmpWalkableRole = stamp.isSnmpWalkableRole;
+  }
+};

package/Utils/Monitor/NetworkDeviceRoleUtil.ts

@@ -538,7 +538,8 @@ export function labelForDeviceRole(
  * The classifier above is evidence-driven, and its evidence is SNMP: a
  * device nothing walks — a ping-only device imported by discovery, say —
  * offers it a hostname and nothing else, so it comes back "unknown" and
- * stays there forever. `NetworkDevice.deviceRole` is the operator saying
+ * stays there forever. The role an operator ASSIGNED the device
+ * (NetworkDevice.networkDeviceRole, whose key is what arrives here) is them saying
  * what the box actually is, and it is the only statement about a role that
  * is not an inference, so it outranks everything the classifier can find.
  *