@oneuptime/common 14.0.6 → 14.0.8

package/Types/Incident/IncidentAlertLink.ts

@@ -12,6 +12,25 @@
  */
 export const INCIDENT_ALERT_IDS_TO_LINK_KEY: string = "alertIdsToLink";
 
+/*
+ * Declaring an incident from alerts does not, on its own, change the alerts:
+ * they keep escalating until somebody acknowledges them. Sending
+ * `miscDataProps[INCIDENT_ACKNOWLEDGE_ALERTS_TO_LINK_KEY] = true` along with
+ * INCIDENT_ALERT_IDS_TO_LINK_KEY also acknowledges them, as the declaring
+ * user, once they are linked - which is what stops their on-call escalation.
+ * Alerts already acknowledged (or past it) are left as they are, and the
+ * caller must be allowed to change the state of every alert that is not.
+ * Off unless asked for.
+ *
+ * One exception: when the incident is declared straight into an
+ * acknowledged or resolved state and the project's linked-alert switches
+ * already move linked alerts along with it, those alerts are left to the
+ * switches (one writer per alert) - acknowledged or resolved as the switch
+ * does it, not credited to the declaring user.
+ */
+export const INCIDENT_ACKNOWLEDGE_ALERTS_TO_LINK_KEY: string =
+  "acknowledgeAlertsToLink";
+
 /*
  * The create-incident page reads the alerts to declare an incident from out of
  * this query string parameter, as a comma separated list of alert ids.

package/Types/SafeHtml.ts

@@ -0,0 +1,93 @@
+/*
+ * A value that is ALREADY HTML and may go into an HTML document as written.
+ *
+ * Status page subscriber emails are filled from two kinds of value, and a
+ * plain string cannot say which one it holds:
+ *
+ *   - plain text: an incident, episode, maintenance or announcement title, a
+ *     severity or state name, a status page or resource name, a URL. Project
+ *     members type these, and a title is exactly what someone outside the
+ *     team gets to influence (an incident created from a monitor, an API
+ *     call, a Slack command). Put into HTML as written, a title such as
+ *     `<a href="https://evil.example">Reset your password</a>` becomes a live
+ *     link in an email the recipient trusts.
+ *   - HTML this code produced itself: Markdown.convertToHTML output (which
+ *     escapes the raw HTML an author typed and keeps only http, https and
+ *     mailto links), the date helper's multi-timezone HTML, and the resource
+ *     list StatusPageResourceUtil.getResourcesGroupedByGroupName builds from
+ *     escaped names.
+ *
+ * So the HTML ones travel wrapped in this type, and anything that is still a
+ * string is treated as plain text and escaped where it meets HTML (see
+ * SubscriberNotificationTemplateCompiler.compileEmailBodyTemplate). A value
+ * nobody thought about is therefore escaped, which at worst shows the reader
+ * an "&amp;" too many; it can never become markup by accident.
+ *
+ * Kept free of server dependencies so both the server and the dashboard can
+ * use it.
+ */
+
+/*
+ * Marks instances without instanceof, which a second copy of this module (a
+ * test's isolated module registry, a duplicated bundle) would defeat.
+ */
+const SAFE_HTML_BRAND: unique symbol = Symbol.for("OneUptime.SafeHtml");
+
+export default class SafeHtml {
+  // Read by isSafeHtml; a symbol key, so JSON.stringify leaves it out.
+  public readonly [SAFE_HTML_BRAND]: boolean = true;
+
+  private readonly html: string;
+
+  private constructor(html: string) {
+    this.html = html;
+  }
+
+  /*
+   * Wraps markup this code produced from values it had already made safe:
+   * Markdown.convertToHTML(..., MarkdownContentType.Email) output,
+   * OneUptimeDate.getDateAsFormattedHTMLInMultipleTimezones output, and
+   * StatusPageResourceUtil.getResourcesGroupedByGroupName output. Never a
+   * value a user typed.
+   */
+  public static fromTrustedHtml(html: string | null | undefined): SafeHtml {
+    return new SafeHtml(html || "");
+  }
+
+  // Plain text, escaped so it reads the same in HTML.
+  public static fromPlainText(text: string | null | undefined): SafeHtml {
+    return new SafeHtml(SafeHtml.escape(text || ""));
+  }
+
+  /*
+   * Escapes the five characters that can break out of HTML text or a quoted
+   * attribute value. The ampersand goes first, so the entities the other
+   * four become are not escaped a second time.
+   *
+   * This is the one implementation: Markdown.escapeHtml calls it.
+   */
+  public static escape(text: string): string {
+    return String(text)
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;")
+      .replace(/'/g, "&#39;");
+  }
+
+  public static isSafeHtml(value: unknown): value is SafeHtml {
+    return (
+      typeof value === "object" &&
+      value !== null &&
+      (value as { [SAFE_HTML_BRAND]?: unknown })[SAFE_HTML_BRAND] === true
+    );
+  }
+
+  public toHtml(): string {
+    return this.html;
+  }
+
+  public toString(): string {
+    return this.html;
+  }
+}

package/Types/StatusPage/IncidentCreatedRenotify.ts

@@ -0,0 +1,224 @@
+import { JSONObject } from "../JSON";
+import IncidentScopeAddedPagesNotification from "./IncidentScopeAddedPagesNotification";
+import StatusPageSubscriberNotificationStatus from "./StatusPageSubscriberNotificationStatus";
+
+/*
+ * Status page subscribers hear about an incident once, when it is created -
+ * but only if it is visible on status pages at that moment. A common routine
+ * is to declare an incident hidden, work out who is affected, and then turn
+ * 'Visible on Status Page' on. The 'created' notification of such an incident
+ * is settled as Skipped (hidden from status pages), so without a way back
+ * nobody was ever told.
+ *
+ * Whether publishing should announce the incident is the editor's call: for a
+ * live outage it should, but making an old, resolved incident visible "for the
+ * record" must not email everyone about a "new" incident. So it is asked when
+ * the incident is published, not decided automatically, and the answer travels
+ * with that update request as a misc data prop (like SubscriberUpdateNotification,
+ * it is not a column - a stored flag would either stick or have to be reset
+ * behind the caller's back). IncidentService turns it into a Pending 'created'
+ * notification status, and the Incident:SendNotificationToSubscribers job
+ * sends it.
+ *
+ * The same goes for status pages added to an incident's scope while it was
+ * hidden. Adding a page to a visible incident can tell that page it was
+ * created (IncidentScopeAddedPagesNotification), but a hidden incident is not
+ * sent anywhere, so a page added then was never told - and once it is in the
+ * scope it is no longer "added" by any later edit. So publishing also offers
+ * the notification when the incident's scope holds pages its record of told
+ * pages (Incident.statusPagesNotifiedOnCreation) does not list. The job then
+ * sends it to those pages only.
+ *
+ * API callers keep the route they already had: set
+ * subscriberNotificationStatusOnIncidentCreated to Pending.
+ *
+ * Everything here is shared by the dashboard, which offers the checkbox, the
+ * server, which acts on it, and the worker, which writes the skip reason, so
+ * they cannot drift apart.
+ */
+
+export interface IncidentCreatedRenotifyState {
+  subscriberNotificationStatusOnIncidentCreated?:
+    | StatusPageSubscriberNotificationStatus
+    | undefined
+    | null;
+  shouldStatusPageSubscribersBeNotifiedOnIncidentCreated?:
+    | boolean
+    | undefined
+    | null;
+  isVisibleOnStatusPage?: boolean | undefined | null;
+  isPrivate?: boolean | undefined | null;
+  /*
+   * The status pages the incident is limited to, and the job's record of the
+   * pages it told (Incident.statusPagesNotifiedOnCreation). Only needed to
+   * offer the notification to pages added while the incident was hidden.
+   */
+  statusPages?: unknown;
+  statusPagesNotifiedOnCreation?: unknown;
+}
+
+export default class IncidentCreatedRenotify {
+  // The misc data prop an update request carries to ask for the notification.
+  public static readonly miscDataKey: string =
+    "notifySubscribersOfIncidentCreatedOnPublish";
+
+  /*
+   * Why the worker skipped the 'created' notification of a hidden incident.
+   * The data migration that settled incidents left InProgress by the old
+   * worker writes the same text, so both read alike on the dashboard.
+   */
+  public static readonly hiddenFromStatusPagesMessage: string =
+    "Incident is not visible on status pages. Skipping notifications to subscribers.";
+
+  // How the dashboard labels that skip next to the notification status.
+  public static readonly hiddenFromStatusPagesLabel: string =
+    "Skipped: hidden from status pages";
+
+  public static readonly queuedMessage: string =
+    "Incident published on status pages. Subscribers will be notified that this incident was created.";
+
+  public static readonly formFieldTitle: string =
+    "Notify subscribers that this incident was created";
+
+  public static readonly formFieldDescription: string =
+    "Subscribers were not told about this incident because it was hidden from status pages. Tick this to send them the incident-created notification now. It starts unticked for resolved incidents, so publishing an old incident for the record does not announce it as new.";
+
+  // The same checkbox, for an incident whose earlier subscribers were told.
+  public static readonly untoldStatusPagesFormFieldDescription: string =
+    "Some status pages this incident is limited to were never sent the notification that it was created, for example pages added while it was hidden. Tick this to send it to them now. Pages that were already told are not sent it again.";
+
+  /*
+   * Only a real yes counts. The flag arrives over JSON, so accept the string
+   * form a hand-written API request might send, and nothing looser: a stray
+   * "false" or 1 must never email every subscriber of a status page.
+   */
+  public static isRequested(
+    miscDataProps: JSONObject | undefined | null,
+  ): boolean {
+    if (!miscDataProps || typeof miscDataProps !== "object") {
+      return false;
+    }
+
+    const value: unknown = miscDataProps[this.miscDataKey];
+
+    return value === true || value === "true";
+  }
+
+  public static getMiscDataProps(): JSONObject {
+    return {
+      [this.miscDataKey]: true,
+    };
+  }
+
+  /*
+   * Whether publishing this incident may queue its 'created' notification
+   * again, given what is stored for it right now:
+   *
+   * - it is hidden today, so this really is the publish;
+   * - notifying on creation is on. An incident created with notifications
+   *   off was deliberately kept quiet, and publishing does not change that;
+   * - it is not private. Private incidents are hidden from every status page,
+   *   so there is nothing to publish;
+   * - and there is someone left to tell. Either its 'created' notification
+   *   was Skipped, so nobody was told; or it went out (Success, or Failed
+   *   part-way) and the incident is limited to status pages its record does
+   *   not list - typically pages added while it was hidden (see
+   *   hasUntoldStatusPages). Pending and InProgress are on their way already
+   *   (and a Pending send reads the incident when it goes out, so it will see
+   *   it visible).
+   */
+  public static canRenotifyOnPublish(
+    incident: IncidentCreatedRenotifyState,
+  ): boolean {
+    if (
+      incident.isVisibleOnStatusPage === true ||
+      incident.shouldStatusPageSubscribersBeNotifiedOnIncidentCreated !==
+        true ||
+      incident.isPrivate === true
+    ) {
+      return false;
+    }
+
+    return (
+      incident.subscriberNotificationStatusOnIncidentCreated ===
+        StatusPageSubscriberNotificationStatus.Skipped ||
+      this.hasUntoldStatusPages(incident)
+    );
+  }
+
+  /*
+   * Whether a notification that already went out left status pages of the
+   * incident's scope untold: its record exists and misses one of them. Pages
+   * added while the incident was hidden land here, as do pages whose send
+   * failed. A page in the scope that lists none of the incident's monitors,
+   * or does not show incidents, is never told either; offering the checkbox
+   * for it sends nothing, and the incident feed says so.
+   *
+   * An incident without a record is not offered it: its notification went out
+   * before the record existed, to every page that listed its monitors (see
+   * IncidentScopeAddedPagesNotification).
+   */
+  public static hasUntoldStatusPages(
+    incident: IncidentCreatedRenotifyState,
+  ): boolean {
+    if (
+      incident.subscriberNotificationStatusOnIncidentCreated !==
+        StatusPageSubscriberNotificationStatus.Success &&
+      incident.subscriberNotificationStatusOnIncidentCreated !==
+        StatusPageSubscriberNotificationStatus.Failed
+    ) {
+      return false;
+    }
+
+    const recorded: Array<string> | null =
+      IncidentScopeAddedPagesNotification.getRecordedStatusPageIds(
+        incident.statusPagesNotifiedOnCreation,
+      );
+
+    if (recorded === null) {
+      return false;
+    }
+
+    return IncidentScopeAddedPagesNotification.normalizeStatusPageIds(
+      incident.statusPages,
+    ).some((id: string): boolean => {
+      return !recorded.includes(id);
+    });
+  }
+
+  // The checkbox's description, for the case canRenotifyOnPublish found.
+  public static getFormFieldDescription(
+    incident: IncidentCreatedRenotifyState,
+  ): string {
+    return incident.subscriberNotificationStatusOnIncidentCreated ===
+      StatusPageSubscriberNotificationStatus.Skipped
+      ? this.formFieldDescription
+      : this.untoldStatusPagesFormFieldDescription;
+  }
+
+  /*
+   * The checkbox starts ticked while the incident is unresolved - publishing
+   * a live incident is the moment its audience should hear about it - and
+   * unticked once it is resolved, so making an old incident visible for the
+   * record does not announce it as new.
+   */
+  public static isTickedByDefault(data: {
+    isResolved: boolean | undefined | null;
+  }): boolean {
+    return data.isResolved !== true;
+  }
+
+  /*
+   * Whether a stored status and message say the 'created' notification was
+   * skipped because the incident was hidden from status pages.
+   */
+  public static isHiddenFromStatusPagesSkip(data: {
+    status: StatusPageSubscriberNotificationStatus | undefined | null;
+    message: string | undefined | null;
+  }): boolean {
+    return (
+      data.status === StatusPageSubscriberNotificationStatus.Skipped &&
+      data.message === this.hiddenFromStatusPagesMessage
+    );
+  }
+}

package/Types/StatusPage/IncidentCreatedResend.ts

@@ -0,0 +1,108 @@
+import { JSONObject } from "../JSON";
+import StatusPageSubscriberNotificationStatus from "./StatusPageSubscriberNotificationStatus";
+
+/*
+ * 'Resend to all pages' for the notification that an incident was created.
+ *
+ * That notification keeps a record of the status pages it was sent to in
+ * full (Incident.statusPagesNotifiedOnCreation), and the job skips them. Two
+ * ways of sending it again already existed, and both stay as they are:
+ *
+ * - setting subscriberNotificationStatusOnIncidentCreated back to Pending
+ *   (the API route, and the dashboard's Retry): IncidentService empties the
+ *   record in the same write, so it reaches every page again - except after
+ *   a failure, where Retry resumes after the pages the failed send finished,
+ *   so they are not sent it twice (see
+ *   IncidentService.clearCreatedNotificationRecordOnResend);
+ * - adding pages to the scope, or publishing a hidden incident, with their
+ *   checkboxes (IncidentScopeAddedPagesNotification, IncidentCreatedRenotify),
+ *   which tell only the pages the record does not list.
+ *
+ * What was missing is sending it to every page on purpose: after a failure,
+ * to start over rather than resume (a template or an SMTP setting was fixed
+ * since, and the pages that "went through" should get the corrected email
+ * too), and after a success, without relying on an implied rule. This misc
+ * data prop asks for exactly that. IncidentService turns it into a Pending
+ * status and an empty record, in the caller's own update, so the column
+ * check that runs after the hook decides whether the caller may.
+ *
+ * Like the other notification requests (SubscriberUpdateNotification,
+ * IncidentCreatedRenotify, IncidentScopeAddedPagesNotification) it is a misc
+ * data prop, not a column: a stored "resend" flag would either stick or have
+ * to be reset behind the caller's back.
+ *
+ * It is only accepted for a notification that went out - Success, or Failed
+ * part-way. A skipped one was never sent to anyone, and one that is Pending
+ * or being sent is on its way; see getRefusalReason.
+ */
+export default class IncidentCreatedResend {
+  // The misc data prop an update request carries to ask for the resend.
+  public static readonly miscDataKey: string =
+    "resendIncidentCreatedToAllStatusPages";
+
+  // The status message of a notification queued by this request.
+  public static readonly queuedMessage: string =
+    "Queued to be sent again to every status page this incident reaches, including the pages that were already sent it.";
+
+  /*
+   * The status message the dashboard's Retry writes: it resumes after the
+   * pages already reached.
+   */
+  public static readonly retryQueuedMessage: string =
+    "Queued to be sent again to the status pages that were not sent it in full. The pages already reached are not sent it again.";
+
+  public static readonly skippedRefusalMessage: string =
+    "Subscribers were never sent the notification that this incident was created (it was skipped), so there is nothing to send again.";
+
+  public static readonly inFlightRefusalMessage: string =
+    "The notification that this incident was created is queued or being sent right now. Wait until it has finished, then send it again.";
+
+  public static readonly conflictingStatusMessage: string =
+    "A request to send the incident-created notification to every status page again cannot also set its status. Leave the status out.";
+
+  public static readonly noPermissionMessage: string =
+    "You do not have permission to send the incident-created notification again. It needs the permission to edit incidents.";
+
+  /*
+   * Only a real yes counts. The flag arrives over JSON, so accept the string
+   * form a hand-written API request might send, and nothing looser: a stray
+   * "false" or 1 must never email every subscriber of every status page.
+   */
+  public static isRequested(
+    miscDataProps: JSONObject | undefined | null,
+  ): boolean {
+    if (!miscDataProps || typeof miscDataProps !== "object") {
+      return false;
+    }
+
+    const value: unknown = miscDataProps[this.miscDataKey];
+
+    return value === true || value === "true";
+  }
+
+  public static getMiscDataProps(): JSONObject {
+    return {
+      [this.miscDataKey]: true,
+    };
+  }
+
+  /*
+   * Why a notification in `status` cannot be sent to every page again, or
+   * null when it can (it went out: Success, or Failed part-way).
+   */
+  public static getRefusalReason(
+    status: StatusPageSubscriberNotificationStatus | undefined | null,
+  ): string | null {
+    switch (status) {
+      case StatusPageSubscriberNotificationStatus.Success:
+      case StatusPageSubscriberNotificationStatus.Failed:
+        return null;
+      case StatusPageSubscriberNotificationStatus.Pending:
+      case StatusPageSubscriberNotificationStatus.InProgress:
+        return this.inFlightRefusalMessage;
+      default:
+        // Skipped, and a missing status, which the column's default rules out.
+        return this.skippedRefusalMessage;
+    }
+  }
+}