@oneuptime/common 12.0.32 → 12.0.33

package/Server/Services/NetworkSnmpCredentialProfileService.ts

@@ -0,0 +1,238 @@
+import DatabaseService from "./DatabaseService";
+import NetworkDeviceService from "./NetworkDeviceService";
+import NetworkSiteService from "./NetworkSiteService";
+import Model from "../../Models/DatabaseModels/NetworkSnmpCredentialProfile";
+import CreateBy from "../Types/Database/CreateBy";
+import DeleteBy from "../Types/Database/DeleteBy";
+import Query from "../Types/Database/Query";
+import UpdateBy from "../Types/Database/UpdateBy";
+import { OnCreate, OnDelete, OnUpdate } from "../Types/Database/Hooks";
+import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
+import DatabaseCommonInteractionProps from "../../Types/BaseDatabase/DatabaseCommonInteractionProps";
+import LIMIT_MAX from "../../Types/Database/LimitMax";
+import BadDataException from "../../Types/Exception/BadDataException";
+import ObjectID from "../../Types/ObjectID";
+import PositiveNumber from "../../Types/PositiveNumber";
+import {
+  SnmpCredentialCarrier,
+  hasUsableCredentials,
+} from "../../Utils/NetworkDevice/SnmpCredentialUtil";
+
+/*
+ * A profile is a row of credentials that other rows point at, and most of
+ * what is interesting about it happens elsewhere: the poller resolves it
+ * (device columns, then device profile, then site profile), the model's
+ * column access control keeps its secrets from the roles that may not read
+ * them, and DatabaseService encrypts those secrets at rest. There is no
+ * fan-out on edit because nothing is copied out of a profile - a device
+ * using one is walked with whatever the profile says at poll time.
+ *
+ * The service owns two things.
+ *
+ * THE NAME. It is unique per project and it is the label every device and
+ * site listing shows for the profile it joins, so a trailing space must not
+ * be what makes "Branch v2c" and "Branch v2c " two different profiles, and a
+ * blank one must not get past the required check by being three spaces long.
+ *
+ * THE DELETE GUARD. Both foreign keys onto this table are ON DELETE SET NULL,
+ * so deleting a profile that devices or sites still use does not fail - it
+ * silently drops every one of them down the resolution order, and a device
+ * whose site has no profile either goes from walked to ping-only on its next
+ * poll with nothing anywhere to say why. Refuse instead, and say how many
+ * devices and sites are in the way. Sites count separately from devices
+ * because a site can hold the last reference to a profile while no device
+ * points at it directly - that is exactly what "set it once per site" means.
+ */
+export class Service extends DatabaseService<Model> {
+  public constructor() {
+    super(Model);
+  }
+
+  /**
+   * "Does this profile carry enough to open an SNMP session with?" -
+   * delegated to the pure util so the poller can ask the same question of a
+   * device row with the same function. Exposed here so a caller holding the
+   * service does not have to know where the predicate lives.
+   */
+  public hasUsableCredentials(profile: SnmpCredentialCarrier): boolean {
+    return hasUsableCredentials(profile);
+  }
+
+  @CaptureSpan()
+  protected override async onBeforeCreate(
+    createBy: CreateBy<Model>,
+  ): Promise<OnCreate<Model>> {
+    createBy.data.name = this.normalizeName(createBy.data.name);
+
+    return { createBy, carryForward: null };
+  }
+
+  @CaptureSpan()
+  protected override async onBeforeUpdate(
+    updateBy: UpdateBy<Model>,
+  ): Promise<OnUpdate<Model>> {
+    /*
+     * `!== undefined` rather than a truthiness check: an update that does not
+     * mention the name (a description edit, a rotated community string) must
+     * leave it alone, while an update that sets it to "" or null is a blank
+     * name and is refused the same way a blank create is.
+     */
+    if (updateBy.data.name !== undefined) {
+      updateBy.data.name = this.normalizeName(updateBy.data.name);
+    }
+
+    return { updateBy, carryForward: null };
+  }
+
+  /*
+   * Refuse to delete a profile that any device or any site still points at.
+   *
+   * Counting rather than keeping a rollup column is deliberate - a maintained
+   * counter would make this row hot under every device create and rebind,
+   * and NetworkDeviceOidTemplateService set the precedent for exactly this
+   * guard. Both counts are always taken and both are always reported, so
+   * the operator learns in one message everything that has to move before
+   * the delete can go through, rather than clearing the devices and then
+   * being told about the sites.
+   */
+  @CaptureSpan()
+  protected override async onBeforeDelete(
+    deleteBy: DeleteBy<Model>,
+  ): Promise<OnDelete<Model>> {
+    const profilesToDelete: Array<Model> = await this.findBy({
+      /*
+       * This hook runs BEFORE DatabaseService permission-checks the query, so
+       * a raw isRoot read of deleteBy.query would hand back other tenants'
+       * profiles. Re-apply the caller's tenant, exactly as NetworkSiteService
+       * and NetworkDeviceOidTemplateService do for the same reason.
+       */
+      query: this.scopeQueryToCallerTenant(deleteBy.query, deleteBy.props),
+      select: {
+        _id: true,
+        name: true,
+        projectId: true,
+      },
+      limit: LIMIT_MAX,
+      skip: 0,
+      props: {
+        isRoot: true,
+      },
+    });
+
+    for (const profile of profilesToDelete) {
+      if (!profile.id || !profile.projectId) {
+        continue;
+      }
+
+      const [linkedDeviceCount, linkedSiteCount]: [number, number] =
+        await Promise.all([
+          this.countLinkedDevices({
+            profileId: profile.id,
+            projectId: profile.projectId,
+          }),
+          this.countLinkedSites({
+            profileId: profile.id,
+            projectId: profile.projectId,
+          }),
+        ]);
+
+      if (linkedDeviceCount > 0 || linkedSiteCount > 0) {
+        throw new BadDataException(
+          `This SNMP Credential Profile is used by ${linkedDeviceCount} devices and ${linkedSiteCount} sites. Remove it from them first, or point them at another profile.`,
+        );
+      }
+    }
+
+    return { deleteBy, carryForward: null };
+  }
+
+  /**
+   * How many devices point at this profile directly. Used by the delete
+   * guard above and available to the profile page.
+   *
+   * Read as root, scoped to the profile's own project: the caller who may
+   * delete a profile is not necessarily allowed to read every device, and a
+   * partial count would let the delete through with devices still attached.
+   */
+  @CaptureSpan()
+  public async countLinkedDevices(data: {
+    profileId: ObjectID;
+    projectId: ObjectID;
+  }): Promise<number> {
+    const count: PositiveNumber = await NetworkDeviceService.countBy({
+      query: {
+        projectId: data.projectId,
+        snmpCredentialProfileId: data.profileId,
+      },
+      props: {
+        isRoot: true,
+      },
+    });
+
+    return count.toNumber();
+  }
+
+  /**
+   * How many sites carry this profile as their default. Same shape and same
+   * reasoning as countLinkedDevices.
+   */
+  @CaptureSpan()
+  public async countLinkedSites(data: {
+    profileId: ObjectID;
+    projectId: ObjectID;
+  }): Promise<number> {
+    const count: PositiveNumber = await NetworkSiteService.countBy({
+      query: {
+        projectId: data.projectId,
+        snmpCredentialProfileId: data.profileId,
+      },
+      props: {
+        isRoot: true,
+      },
+    });
+
+    return count.toNumber();
+  }
+
+  /*
+   * See NetworkSiteService for the full explanation: hooks run before
+   * ModelPermission scopes the caller's query, so anything a hook reads with
+   * isRoot has to be re-scoped by hand or it spans projects.
+   */
+  private scopeQueryToCallerTenant(
+    query: Query<Model>,
+    props: DatabaseCommonInteractionProps,
+  ): Query<Model> {
+    if (props.isRoot || !props.tenantId) {
+      return query;
+    }
+
+    return {
+      ...query,
+      projectId: props.tenantId,
+    };
+  }
+
+  /*
+   * The name as it will be stored, or a BadDataException. Only a plain string
+   * is accepted: the column is also used as a label, and a raw SQL expression
+   * (the other shape PartialEntity allows) has no business being one.
+   */
+  private normalizeName(name: unknown): string {
+    if (typeof name !== "string") {
+      throw new BadDataException("SNMP Credential Profile name is required.");
+    }
+
+    const trimmed: string = name.trim();
+
+    if (!trimmed) {
+      throw new BadDataException(
+        "SNMP Credential Profile name cannot be blank.",
+      );
+    }
+
+    return trimmed;
+  }
+}
+
+export default new Service();

package/Server/Services/NotificationService.ts

@@ -12,6 +12,10 @@ import ObjectID from "../../Types/ObjectID";
 import Project from "../../Models/DatabaseModels/Project";
 import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
 import SlackUtil from "../Utils/Workspace/Slack/Slack";
+import {
+  BillingFailureNoticeKind,
+  shouldSendBillingFailureNotice,
+} from "../Utils/Billing/BillingFailureNoticeThrottle";
 import URL from "../../Types/API/URL";
 import Exception from "../../Types/Exception/Exception";
 
@@ -24,7 +28,27 @@ export class NotificationService extends BaseService {
   public async rechargeBalance(
     projectId: ObjectID,
     amountInUSD: number,
+    options?: {
+      /*
+       * Whether a successful recharge is worth telling the owners about.
+       *
+       * True for the manual "Recharge" button in Project Settings, where the
+       * email is the only confirmation a person gets that their card was
+       * charged: Project.sendInvoicesByEmail defaults to false, so the Stripe
+       * invoice is filed rather than sent, and the Slack notification is an
+       * operator webhook that most installs never configure.
+       *
+       * False for rechargeIfBalanceIsLow, which runs inline on every SMS,
+       * call, WhatsApp and Telegram attempt - there, "we topped your balance
+       * up" is not news, and during a paging storm it is one email to every
+       * owner per recharge.
+       */
+      sendOwnerConfirmationEmail?: boolean | undefined;
+    },
   ): Promise<number> {
+    const sendOwnerConfirmationEmail: boolean =
+      options?.sendOwnerConfirmationEmail !== false;
+
     const project: Project | null = await ProjectService.findOneById({
       id: projectId,
       select: {
@@ -48,13 +72,36 @@ export class NotificationService extends BaseService {
       return 0;
     }
 
+    /*
+     * The no-payment-method branch below throws, and that throw lands in this
+     * method's own catch. Without this the FIRST no-payment-method failure
+     * sends two "ACTION REQUIRED" emails about the same fact, one from each
+     * place. This is a local flag rather than a mutation of `project` so it is
+     * obvious it exists only to coordinate those two blocks.
+     */
+    let ownersAlreadyToldAboutThisFailure: boolean = false;
+
     try {
       if (
         !(await BillingService.hasPaymentMethods(
           project.paymentProviderCustomerId!,
         ))
       ) {
-        if (!project.failedCallAndSMSBalanceChargeNotificationSentToOwners) {
+        /*
+         * The same 24h window as the catch below, for the same reason: the
+         * project boolean this branch used to latch on is cleared only by a
+         * SUCCESSFUL recharge, so a project that never manages one was told
+         * once and then never again. A window says it once a day until
+         * somebody fixes it, which is what an ACTION REQUIRED message is for.
+         */
+        ownersAlreadyToldAboutThisFailure = true;
+
+        const shouldTellOwners: boolean = await shouldSendBillingFailureNotice({
+          projectId: project.id!,
+          kind: BillingFailureNoticeKind.SmsAndCallRechargeFailed,
+        });
+
+        if (shouldTellOwners) {
           await ProjectService.updateOneById({
             data: {
               failedCallAndSMSBalanceChargeNotificationSentToOwners: true,
@@ -110,16 +157,27 @@ export class NotificationService extends BaseService {
         },
       });
 
-      await ProjectService.sendEmailToProjectOwners(
-        project.id!,
-        "SMS and Call Recharge Successful for project - " +
-          (project.name || ""),
-        `We have successfully recharged your SMS and Call balance for project - ${
-          project.name || ""
-        } by ${amountInUSD} USD. Your current balance is ${
-          updatedAmount / 100
-        } USD.`,
-      );
+      /*
+       * The confirmation is suppressed for AUTO-recharge only. This used to
+       * fire unconditionally, and because rechargeIfBalanceIsLow runs inline
+       * on every SMS, call, WhatsApp and Telegram attempt, a project that
+       * auto-recharges during a paging storm mailed every owner once per
+       * recharge. Somebody who deliberately clicked "Recharge" still gets
+       * told: nothing else reliably tells them, because
+       * Project.sendInvoicesByEmail defaults to false.
+       */
+      if (sendOwnerConfirmationEmail) {
+        await ProjectService.sendEmailToProjectOwners(
+          project.id!,
+          "SMS and Call Recharge Successful for project - " +
+            (project.name || ""),
+          `We have successfully recharged your SMS and Call balance for project - ${
+            project.name || ""
+          } by ${amountInUSD} USD. Your current balance is ${
+            updatedAmount / 100
+          } USD.`,
+        );
+      }
 
       // Send Slack notification for balance refill
       this.sendBalanceRefillSlackNotification({
@@ -137,23 +195,46 @@ export class NotificationService extends BaseService {
 
       return updatedAmount;
     } catch (err) {
-      await ProjectService.updateOneById({
-        data: {
-          failedCallAndSMSBalanceChargeNotificationSentToOwners: true,
-        },
-        id: project.id!,
-        props: {
-          isRoot: true,
-        },
-      });
-      await ProjectService.sendEmailToProjectOwners(
-        project.id!,
-        "ACTION REQUIRED: SMS and Call Recharge Failed for project - " +
-          (project.name || ""),
-        `We have tried recharged your SMS and Call balance for project - ${
-          project.name || ""
-        } and failed. Please make sure your payment method is upto date and has sufficient balance. You can add new payment methods in Project Settings.`,
-      );
+      /*
+       * This block used to write failedCallAndSMSBalanceChargeNotificationSent
+       * ToOwners and then send WITHOUT ever reading it, so a project with a
+       * declined card mailed every owner once per paging attempt - inline on
+       * every SMS and call, during the outage the pages were about.
+       *
+       * The guard is a 24h window rather than that boolean deliberately. The
+       * boolean is only cleared by a successful recharge, so latching on it
+       * would mean: no card -> mail once and latch -> owner adds a card -> the
+       * card is declined -> the recharge can never succeed -> the latch never
+       * clears -> nobody is ever told the new card failed, and paging quietly
+       * stops. A window collapses the storm to one email a day and still
+       * reports a new failure within a day. See BillingFailureNoticeThrottle.
+       */
+      if (!ownersAlreadyToldAboutThisFailure) {
+        const shouldTellOwners: boolean = await shouldSendBillingFailureNotice({
+          projectId: project.id!,
+          kind: BillingFailureNoticeKind.SmsAndCallRechargeFailed,
+        });
+
+        if (shouldTellOwners) {
+          await ProjectService.updateOneById({
+            data: {
+              failedCallAndSMSBalanceChargeNotificationSentToOwners: true,
+            },
+            id: project.id!,
+            props: {
+              isRoot: true,
+            },
+          });
+          await ProjectService.sendEmailToProjectOwners(
+            project.id!,
+            "ACTION REQUIRED: SMS and Call Recharge Failed for project - " +
+              (project.name || ""),
+            `We have tried recharged your SMS and Call balance for project - ${
+              project.name || ""
+            } and failed. Please make sure your payment method is upto date and has sufficient balance. You can add new payment methods in Project Settings.`,
+          );
+        }
+      }
       logger.error(err, { projectId: projectId?.toString() } as LogAttributes);
       throw err;
     }
@@ -214,6 +295,15 @@ export class NotificationService extends BaseService {
           const updatedAmount: number = await this.rechargeBalance(
             projectId,
             autoRechargeSmsOrCallByBalanceInUSD,
+            {
+              /*
+               * This method is called inline from SmsService, CallService,
+               * WhatsAppService and TelegramService on EVERY notification
+               * attempt, so a success email here is one message to every owner
+               * per recharge, in the middle of the storm that caused it.
+               */
+              sendOwnerConfirmationEmail: false,
+            },
           );
           project.smsOrCallCurrentBalanceInUSDCents = updatedAmount;
         }

package/Server/Services/ProjectService.ts

@@ -65,6 +65,7 @@ import {
 } from "../../Types/BrandColors";
 import Color from "../../Types/Color";
 import LIMIT_MAX from "../../Types/Database/LimitMax";
+import SortOrder from "../../Types/BaseDatabase/SortOrder";
 import QueryDeepPartialEntity from "../../Types/Database/PartialEntity";
 import OneUptimeDate from "../../Types/Date";
 import EmailTemplateType from "../../Types/Email/EmailTemplateType";
@@ -85,6 +86,10 @@ import {
   DEFAULT_NETWORK_DEVICE_ROLES,
   DefaultNetworkDeviceRole,
 } from "../../Types/NetworkDevice/DefaultNetworkDeviceRole";
+import {
+  DefaultNetworkSiteTypeCreationOrder,
+  DefaultNetworkSiteTypeParent,
+} from "../../Types/NetworkSite/DefaultNetworkSiteTypeHierarchy";
 import Model from "../../Models/DatabaseModels/Project";
 import BaseModel from "../../Models/DatabaseModels/DatabaseBaseModel/DatabaseBaseModel";
 import PromoCode from "../../Models/DatabaseModels/PromoCode";
@@ -1912,21 +1917,50 @@ These are no longer recorded against the project and have to be cancelled by han
    * addDefaultAlertSeverity / addDefaultAlertState.
    */
   @CaptureSpan()
-  public async addDefaultNetworkSiteTypes(createdItem: Model): Promise<Model> {
+  public async addDefaultNetworkSiteTypes(
+    createdItem: Model,
+    options?: { setParentRelationships?: boolean },
+  ): Promise<Model> {
     const projectId: ObjectID = createdItem.id!;
 
-    // Idempotent — see getExistingProjectScopedNames.
-    const existingNames: Set<string | undefined> =
-      await this.getExistingProjectScopedNames(
-        NetworkSiteTypeService,
-        projectId,
-      );
+    const existingNetworkSiteTypes: Array<NetworkSiteType> = [];
+    let networkSiteTypeSkip: number = 0;
+
+    while (true) {
+      const page: Array<NetworkSiteType> = await NetworkSiteTypeService.findBy({
+        query: { projectId },
+        select: { _id: true, name: true },
+        sort: { _id: SortOrder.Ascending },
+        limit: LIMIT_MAX,
+        skip: networkSiteTypeSkip,
+        props: { isRoot: true },
+      });
+
+      existingNetworkSiteTypes.push(...page);
+
+      if (page.length < LIMIT_MAX) {
+        break;
+      }
+
+      networkSiteTypeSkip += page.length;
+    }
+
+    const networkSiteTypeByName: Map<string, NetworkSiteType> = new Map<
+      string,
+      NetworkSiteType
+    >();
+
+    for (const networkSiteType of existingNetworkSiteTypes) {
+      if (networkSiteType.name) {
+        networkSiteTypeByName.set(networkSiteType.name, networkSiteType);
+      }
+    }
 
     /*
-     * Listed broadest-first: the array position is the hierarchy level, so the
-     * index drives `order` (1..7, lower = higher in the hierarchy). Names come
-     * from DefaultNetworkSiteType so that enum stays the single source of
-     * truth for the defaults, shared with the backfill data migration.
+     * DefaultNetworkSiteTypeCreationOrder lists parents before children, so a
+     * parent's ID is always available by the time its child is created. The
+     * parent mapping itself is shared with the data migration that repairs
+     * projects created before type parents existed.
      *
      * isUnitLevel is true for "Unit" only. It is load-bearing, not a label:
      * the network map drills sites of a unit-level type into their device
@@ -1934,81 +1968,104 @@ These are no longer recorded against the project and have to be cancelled by han
      * as units. Downstream code keys off this flag rather than the name,
      * because the name is user-editable once seeded.
      */
-    const defaultNetworkSiteTypes: Array<{
-      name: DefaultNetworkSiteType;
-      description: string;
-      isUnitLevel: boolean;
-    }> = [
-      {
-        name: DefaultNetworkSiteType.AccountType,
+    const defaultNetworkSiteTypes: Readonly<
+      Record<
+        DefaultNetworkSiteType,
+        {
+          description: string;
+          isUnitLevel: boolean;
+        }
+      >
+    > = {
+      [DefaultNetworkSiteType.AccountType]: {
         description:
           "Top level grouping - the kind of account the sites underneath it belong to.",
         isUnitLevel: false,
       },
-      {
-        name: DefaultNetworkSiteType.Region,
+      [DefaultNetworkSiteType.Region]: {
         description:
           "A broad geographic region that groups markets and the sites within them.",
         isUnitLevel: false,
       },
-      {
-        name: DefaultNetworkSiteType.Franchisee,
+      [DefaultNetworkSiteType.Franchisee]: {
         description:
           "An operator or franchise partner responsible for a group of sites.",
         isUnitLevel: false,
       },
-      {
-        name: DefaultNetworkSiteType.Market,
+      [DefaultNetworkSiteType.Market]: {
         description: "A metro or trade area that groups the sites within it.",
         isUnitLevel: false,
       },
-      {
-        name: DefaultNetworkSiteType.Unit,
+      [DefaultNetworkSiteType.Unit]: {
         description:
           "An individual location with network devices. This is the leaf level of the hierarchy.",
         isUnitLevel: true,
       },
-      {
-        name: DefaultNetworkSiteType.DataCenter,
+      [DefaultNetworkSiteType.DataCenter]: {
         description:
           "A data center or core facility that hosts shared infrastructure.",
         isUnitLevel: false,
       },
-      {
-        name: DefaultNetworkSiteType.Other,
+      [DefaultNetworkSiteType.Other]: {
         description: "Any site that does not fit the other levels.",
         isUnitLevel: false,
       },
-    ];
+    };
 
-    for (
-      let index: number = 0;
-      index < defaultNetworkSiteTypes.length;
-      index++
-    ) {
+    /*
+     * `order` is a sibling display order, not a proxy for depth. Increment a
+     * separate counter per parent: the default chain's only child is 1 at each
+     * level, while the three roots are Account Type (1), Data Center (2), and
+     * Other (3).
+     */
+    const nextOrderByParent: Map<DefaultNetworkSiteType | null, number> =
+      new Map<DefaultNetworkSiteType | null, number>();
+
+    for (const name of DefaultNetworkSiteTypeCreationOrder) {
       const defaultNetworkSiteType: {
-        name: DefaultNetworkSiteType;
         description: string;
         isUnitLevel: boolean;
-      } = defaultNetworkSiteTypes[index]!;
-
-      if (existingNames.has(defaultNetworkSiteType.name)) {
+      } = defaultNetworkSiteTypes[name];
+      const parentName: DefaultNetworkSiteType | null =
+        options?.setParentRelationships === false
+          ? null
+          : DefaultNetworkSiteTypeParent[name];
+      const siblingOrder: number = (nextOrderByParent.get(parentName) || 0) + 1;
+      nextOrderByParent.set(parentName, siblingOrder);
+
+      if (networkSiteTypeByName.has(name)) {
         continue;
       }
 
       const networkSiteType: NetworkSiteType = new NetworkSiteType();
-      networkSiteType.name = defaultNetworkSiteType.name;
+      networkSiteType.name = name;
       networkSiteType.description = defaultNetworkSiteType.description;
       networkSiteType.isUnitLevel = defaultNetworkSiteType.isUnitLevel;
       networkSiteType.projectId = projectId;
-      networkSiteType.order = index + 1;
+      networkSiteType.order = siblingOrder;
 
-      await NetworkSiteTypeService.create({
-        data: networkSiteType,
-        props: {
-          isRoot: true,
-        },
-      });
+      if (parentName) {
+        const parent: NetworkSiteType | undefined =
+          networkSiteTypeByName.get(parentName);
+
+        if (!parent?.id) {
+          throw new BadDataException(
+            `Cannot create the default ${name} Network Site Type because its ${parentName} parent could not be resolved.`,
+          );
+        }
+
+        networkSiteType.parentNetworkSiteTypeId = parent.id;
+      }
+
+      const createdNetworkSiteType: NetworkSiteType =
+        await NetworkSiteTypeService.create({
+          data: networkSiteType,
+          props: {
+            isRoot: true,
+          },
+        });
+
+      networkSiteTypeByName.set(name, createdNetworkSiteType);
     }
 
     return createdItem;