@oneuptime/common 12.0.31 → 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;
         }