@oneuptime/common 14.0.9 → 14.0.10

package/Server/Utils/Workspace/MicrosoftTeams/MicrosoftTeamsCreateCommands.ts

@@ -0,0 +1,418 @@
+import { TurnContext } from "botbuilder";
+import { JSONObject } from "../../../../Types/JSON";
+import ObjectID from "../../../../Types/ObjectID";
+import NotAuthorizedException from "../../../../Types/Exception/NotAuthorizedException";
+import DatabaseCommonInteractionProps from "../../../../Types/BaseDatabase/DatabaseCommonInteractionProps";
+import { DatabaseBaseModelType } from "../../../../Models/DatabaseModels/DatabaseBaseModel/DatabaseBaseModel";
+import ScheduledMaintenance from "../../../../Models/DatabaseModels/ScheduledMaintenance";
+import logger from "../../Logger";
+import CaptureSpan from "../../Telemetry/CaptureSpan";
+import WorkspaceActionAuthorization from "../WorkspaceActionAuthorization";
+import MicrosoftTeamsAuthAction, {
+  MicrosoftTeamsAccountNotLinkedException,
+} from "./Actions/Auth";
+import MicrosoftTeamsIncidentActions, {
+  MicrosoftTeamsNewIncidentFormChoices,
+} from "./Actions/Incident";
+import MicrosoftTeamsScheduledMaintenanceActions, {
+  MicrosoftTeamsNewScheduledMaintenanceFormChoices,
+} from "./Actions/ScheduledMaintenance";
+import MicrosoftTeamsMessageSize from "./MicrosoftTeamsMessageSize";
+import MicrosoftTeamsReplies from "./MicrosoftTeamsReplies";
+import MicrosoftTeamsTimezone from "./MicrosoftTeamsTimezone";
+
+/*
+ * "create incident" and "create maintenance" typed to the Microsoft Teams bot.
+ *
+ * Each answers with exactly one message: the form, or a reason it cannot be
+ * shown that says what to do next (issue #4111 answered both with a generic
+ * "Sorry, I encountered an error...", twice).
+ *
+ * 1. In a personal chat the sender is the only one who can submit the form,
+ *    so a sender without a connected account, who is not a member of the
+ *    project, or who may not create the thing, is told so before filling it
+ *    in, not after. In a channel or group chat anyone there may submit it, and
+ *    the submit checks whoever does, so the form is posted for everyone.
+ * 2. The form's lists (monitors, labels, on-call policies...) are read in name
+ *    order up to a cap, and the card is fitted to a size budget that Teams
+ *    accepts; a card Teams still refuses as too large is sent again smaller,
+ *    and finally without the lists at all.
+ */
+
+export interface CreateFormText {
+  // "an incident", "a scheduled maintenance event": what the form creates.
+  what: string;
+  // Below the project in the dashboard, where the same thing can be created.
+  dashboardRoute: string;
+  // Completes "To ...": why the sender needs a connected account.
+  purpose: string;
+  // The lists that are left off a card refused as too large.
+  lists: string;
+}
+
+const INCIDENT_FORM: CreateFormText = {
+  what: "an incident",
+  dashboardRoute: "/incidents/create",
+  purpose: "create incidents from Microsoft Teams",
+  lists: "monitors, labels and on-call policies",
+};
+
+const SCHEDULED_MAINTENANCE_FORM: CreateFormText = {
+  what: "a scheduled maintenance event",
+  dashboardRoute: "/scheduled-maintenance-events/create",
+  purpose: "schedule maintenance from Microsoft Teams",
+  lists: "monitors and labels",
+};
+
+export default class MicrosoftTeamsCreateCommands {
+  @CaptureSpan()
+  public static async handleCreateIncidentCommand(data: {
+    turnContext: TurnContext;
+    activity: JSONObject;
+    projectId: ObjectID;
+    initialTitle?: string | undefined;
+  }): Promise<void> {
+    const { turnContext, activity, projectId } = data;
+
+    if (
+      this.isPersonalConversation(activity) &&
+      !(await this.authorizeSender({
+        turnContext: turnContext,
+        activity: activity,
+        projectId: projectId,
+        form: INCIDENT_FORM,
+      }))
+    ) {
+      return;
+    }
+
+    let choices: MicrosoftTeamsNewIncidentFormChoices;
+
+    try {
+      choices =
+        await MicrosoftTeamsIncidentActions.getNewIncidentFormChoices(
+          projectId,
+        );
+    } catch (error) {
+      await this.replyFormCouldNotLoad({
+        turnContext: turnContext,
+        projectId: projectId,
+        form: INCIDENT_FORM,
+        error: error,
+      });
+      return;
+    }
+
+    if (choices.severities.choices.length === 0) {
+      const severitySettingsUrl: string | null =
+        await MicrosoftTeamsReplies.getDashboardLink({
+          projectId: projectId,
+          route: "/incidents/settings/severity",
+        });
+
+      await MicrosoftTeamsReplies.sendBestEffort(
+        turnContext,
+        `An incident needs a severity, and this project has no incident severities yet. Add one in OneUptime under ${
+          severitySettingsUrl
+            ? `[Incidents → Settings → Incident Severity](${severitySettingsUrl})`
+            : "Incidents → Settings → Incident Severity"
+        }, then try again.`,
+      );
+      return;
+    }
+
+    const createInOneUptimeUrl: string | null =
+      await MicrosoftTeamsReplies.getDashboardLink({
+        projectId: projectId,
+        route: INCIDENT_FORM.dashboardRoute,
+      });
+
+    await this.sendForm({
+      turnContext: turnContext,
+      projectId: projectId,
+      form: INCIDENT_FORM,
+      createInOneUptimeUrl: createInOneUptimeUrl,
+      buildCard: (budgetInBytes: number): JSONObject => {
+        return MicrosoftTeamsIncidentActions.buildNewIncidentCardForBudget({
+          choices: choices,
+          budgetInBytes: budgetInBytes,
+          initialTitle: data.initialTitle,
+          createInOneUptimeUrl: createInOneUptimeUrl,
+        });
+      },
+    });
+  }
+
+  @CaptureSpan()
+  public static async handleCreateScheduledMaintenanceCommand(data: {
+    turnContext: TurnContext;
+    activity: JSONObject;
+    projectId: ObjectID;
+    initialTitle?: string | undefined;
+  }): Promise<void> {
+    const { turnContext, activity, projectId } = data;
+
+    if (
+      this.isPersonalConversation(activity) &&
+      !(await this.authorizeSender({
+        turnContext: turnContext,
+        activity: activity,
+        projectId: projectId,
+        form: SCHEDULED_MAINTENANCE_FORM,
+        // Submitting checks the same permission.
+        createPermission: {
+          modelType: ScheduledMaintenance,
+          action: "create a scheduled maintenance event",
+        },
+      }))
+    ) {
+      return;
+    }
+
+    let choices: MicrosoftTeamsNewScheduledMaintenanceFormChoices;
+
+    try {
+      choices =
+        await MicrosoftTeamsScheduledMaintenanceActions.getNewScheduledMaintenanceFormChoices(
+          projectId,
+        );
+    } catch (error) {
+      await this.replyFormCouldNotLoad({
+        turnContext: turnContext,
+        projectId: projectId,
+        form: SCHEDULED_MAINTENANCE_FORM,
+        error: error,
+      });
+      return;
+    }
+
+    const createInOneUptimeUrl: string | null =
+      await MicrosoftTeamsReplies.getDashboardLink({
+        projectId: projectId,
+        route: SCHEDULED_MAINTENANCE_FORM.dashboardRoute,
+      });
+
+    // The zone the start and end are typed in; see MicrosoftTeamsTimezone.
+    const timezone: string | undefined =
+      MicrosoftTeamsTimezone.getTimezoneFromActivity(activity);
+
+    await this.sendForm({
+      turnContext: turnContext,
+      projectId: projectId,
+      form: SCHEDULED_MAINTENANCE_FORM,
+      createInOneUptimeUrl: createInOneUptimeUrl,
+      buildCard: (budgetInBytes: number): JSONObject => {
+        return MicrosoftTeamsScheduledMaintenanceActions.buildNewScheduledMaintenanceCardForBudget(
+          {
+            choices: choices,
+            budgetInBytes: budgetInBytes,
+            initialTitle: data.initialTitle,
+            createInOneUptimeUrl: createInOneUptimeUrl,
+            timezone: timezone,
+          },
+        );
+      },
+    });
+  }
+
+  // A 1:1 chat with the bot, where whoever asks for a form is the one to submit it.
+  private static isPersonalConversation(activity: JSONObject): boolean {
+    return (
+      ((activity["conversation"] as JSONObject | undefined)?.[
+        "conversationType"
+      ] as string | undefined) === "personal"
+    );
+  }
+
+  /*
+   * True when the sender can submit the form. Otherwise the sender is told
+   * why (no connected account, not a project member, no permission) and this
+   * returns false.
+   */
+  private static async authorizeSender(data: {
+    turnContext: TurnContext;
+    activity: JSONObject;
+    projectId: ObjectID;
+    form: CreateFormText;
+    createPermission?:
+      | {
+          modelType: DatabaseBaseModelType;
+          action: string;
+        }
+      | undefined;
+  }): Promise<boolean> {
+    const { turnContext, activity, projectId, form } = data;
+
+    const teamsUserId: string =
+      ((activity["from"] as JSONObject | undefined)?.["aadObjectId"] as
+        | string
+        | undefined) || "";
+
+    if (!teamsUserId) {
+      logger.warn(
+        "A Microsoft Teams create command arrived without the sender's AAD object id",
+        {
+          projectId: projectId.toString(),
+        },
+      );
+      await MicrosoftTeamsReplies.sendBestEffort(
+        turnContext,
+        `Sorry, I couldn't tell who sent this message, so I can't open the form to create ${form.what}. Please try again.`,
+      );
+      return false;
+    }
+
+    try {
+      const userId: ObjectID =
+        await MicrosoftTeamsAuthAction.getOneUptimeUserIdFromTeamsUserId({
+          teamsUserId: teamsUserId,
+          projectId: projectId,
+        });
+
+      const props: DatabaseCommonInteractionProps =
+        await WorkspaceActionAuthorization.getProjectMemberProps({
+          userId: userId,
+          projectId: projectId,
+        });
+
+      if (data.createPermission) {
+        await WorkspaceActionAuthorization.assertCanCreate({
+          props: props,
+          modelType: data.createPermission.modelType,
+          action: data.createPermission.action,
+        });
+      }
+
+      return true;
+    } catch (error) {
+      if (error instanceof MicrosoftTeamsAccountNotLinkedException) {
+        await MicrosoftTeamsReplies.sendBestEffort(
+          turnContext,
+          await MicrosoftTeamsReplies.getAccountNotLinkedMessage({
+            projectId: projectId,
+            purpose: form.purpose,
+          }),
+        );
+        return false;
+      }
+
+      if (error instanceof NotAuthorizedException) {
+        await MicrosoftTeamsReplies.sendBestEffort(turnContext, error.message);
+        return false;
+      }
+
+      MicrosoftTeamsReplies.logFailure(
+        "Could not check the Microsoft Teams sender of a create command",
+        error,
+        {
+          projectId: projectId.toString(),
+        },
+      );
+      await MicrosoftTeamsReplies.sendBestEffort(
+        turnContext,
+        `Sorry, I couldn't open the form to create ${form.what} because OneUptime could not check your account just now. Please try again in a minute.`,
+      );
+      return false;
+    }
+  }
+
+  private static async sendForm(data: {
+    turnContext: TurnContext;
+    projectId: ObjectID;
+    form: CreateFormText;
+    createInOneUptimeUrl: string | null;
+    buildCard: (budgetInBytes: number) => JSONObject;
+  }): Promise<void> {
+    try {
+      await MicrosoftTeamsReplies.sendCardWithinSizeLimit({
+        turnContext: data.turnContext,
+        buildCard: data.buildCard,
+      });
+    } catch (error) {
+      MicrosoftTeamsReplies.logFailure(
+        `Microsoft Teams did not accept the form to create ${data.form.what}`,
+        error,
+        {
+          projectId: data.projectId.toString(),
+        },
+      );
+
+      await MicrosoftTeamsReplies.sendBestEffort(
+        data.turnContext,
+        this.getFormNotAcceptedMessage({
+          form: data.form,
+          error: error,
+          createInOneUptimeUrl: data.createInOneUptimeUrl,
+        }),
+      );
+    }
+  }
+
+  private static async replyFormCouldNotLoad(data: {
+    turnContext: TurnContext;
+    projectId: ObjectID;
+    form: CreateFormText;
+    error: unknown;
+  }): Promise<void> {
+    MicrosoftTeamsReplies.logFailure(
+      `Could not load the Microsoft Teams form to create ${data.form.what}`,
+      data.error,
+      {
+        projectId: data.projectId.toString(),
+      },
+    );
+
+    const createInOneUptimeUrl: string | null =
+      await MicrosoftTeamsReplies.getDashboardLink({
+        projectId: data.projectId,
+        route: data.form.dashboardRoute,
+      });
+
+    await MicrosoftTeamsReplies.sendBestEffort(
+      data.turnContext,
+      `Sorry, I couldn't open the form to create ${data.form.what} because OneUptime could not load the lists it needs just now. Please try again in a minute, ${this.getCreateInOneUptimeHint(
+        createInOneUptimeUrl,
+        "or create it",
+      )}`,
+    );
+  }
+
+  public static getFormNotAcceptedMessage(data: {
+    form: CreateFormText;
+    error: unknown;
+    createInOneUptimeUrl: string | null;
+  }): string {
+    const createInOneUptime: string = this.getCreateInOneUptimeHint(
+      data.createInOneUptimeUrl,
+      "You can create it",
+    );
+
+    if (MicrosoftTeamsMessageSize.isMessageTooLargeError(data.error)) {
+      return `Sorry, I couldn't open the form to create ${data.form.what}: Microsoft Teams refused it as too large, even without the lists of ${data.form.lists}. ${createInOneUptime}`;
+    }
+
+    const statusCode: number | undefined =
+      MicrosoftTeamsMessageSize.getErrorStatusCode(data.error);
+    const code: string | undefined = MicrosoftTeamsMessageSize.getErrorCode(
+      data.error,
+    );
+    const teamsReason: string = [statusCode, code]
+      .filter((part: string | number | undefined) => {
+        return part !== undefined && part !== "";
+      })
+      .join(" ");
+
+    return `Sorry, I couldn't open the form to create ${data.form.what}: Microsoft Teams did not accept it${
+      teamsReason ? ` (${teamsReason})` : ""
+    }. ${createInOneUptime}`;
+  }
+
+  private static getCreateInOneUptimeHint(
+    createInOneUptimeUrl: string | null,
+    lead: string,
+  ): string {
+    return createInOneUptimeUrl
+      ? `${lead} in OneUptime instead: ${createInOneUptimeUrl}`
+      : `${lead} in OneUptime instead.`;
+  }
+}

package/Server/Utils/Workspace/MicrosoftTeams/MicrosoftTeamsMessageSize.ts

@@ -0,0 +1,152 @@
+import { JSONObject } from "../../../../Types/JSON";
+import { truncateToLength } from "../../Database/TruncateColumnValue";
+
+/*
+ * How big a message Microsoft Teams takes from a bot.
+ *
+ * Teams measures a bot message as UTF-16 and refuses one over its limit with
+ * HTTP 413 MessageSizeTooBig ("Message size too large."), which the Bot
+ * Framework SDK does not retry. The documented limit has moved over the years
+ * (28 KB, then 40 KB, now "about 100 KB, keep it within 80 KB"), and Teams
+ * checks it against its own internal form of the message rather than the JSON
+ * we send, so 413s are reported well under the documented number. Anything we
+ * build that grows with the size of a project is therefore kept to a budget
+ * with a wide margin, and a card Teams still refuses is sent again, smaller.
+ *
+ * Issue #4111: the "create incident" and "create maintenance" forms listed
+ * every monitor, label and on-call policy of the project, so a few hundred
+ * monitors were enough for Teams to refuse the form.
+ */
+
+/*
+ * Budgets for an adaptive card, in the order they are tried. The next one is
+ * only tried after Teams refused the card built for the previous one. A budget
+ * of 0 leaves every optional list off the card.
+ */
+export const MICROSOFT_TEAMS_CARD_SIZE_BUDGETS_IN_BYTES: ReadonlyArray<number> =
+  [40 * 1024, 20 * 1024, 0];
+
+// Budget for a plain text reply, such as "show active incidents".
+export const MICROSOFT_TEAMS_TEXT_MESSAGE_BUDGET_IN_BYTES: number = 40 * 1024;
+
+const DEFAULT_TRUNCATION_NOTE: string =
+  "…\n\n_This reply was shortened to fit in Microsoft Teams. Open OneUptime to see everything._";
+
+export default class MicrosoftTeamsMessageSize {
+  // Size as Teams counts it: JavaScript strings are UTF-16, two bytes a unit.
+  public static getSizeInBytes(value: string | JSONObject): number {
+    const text: string =
+      typeof value === "string" ? value : JSON.stringify(value);
+
+    return text.length * 2;
+  }
+
+  /*
+   * Whether Teams refused a message as too large.
+   *
+   * The Bot Framework connector throws a RestError that carries statusCode
+   * 413 and code "MessageSizeTooBig". It is matched on those fields and not
+   * on its class: @azure/* is not a dependency of Common (botbuilder brings
+   * it), and the error can come from another JavaScript realm, where
+   * instanceof is false. The status code alone is enough when a proxy in
+   * front of the connector answered 413 with a body that is not JSON.
+   */
+  public static isMessageTooLargeError(error: unknown): boolean {
+    return (
+      this.getErrorStatusCode(error) === 413 ||
+      this.getErrorCode(error) === "MessageSizeTooBig"
+    );
+  }
+
+  // The HTTP status of a failed Bot Framework call, when the error has one.
+  public static getErrorStatusCode(error: unknown): number | undefined {
+    if (!error || typeof error !== "object") {
+      return undefined;
+    }
+
+    const candidate: {
+      statusCode?: unknown;
+      response?: { status?: unknown } | undefined;
+    } = error as {
+      statusCode?: unknown;
+      response?: { status?: unknown } | undefined;
+    };
+
+    if (typeof candidate.statusCode === "number") {
+      return candidate.statusCode;
+    }
+
+    if (typeof candidate.response?.status === "number") {
+      return candidate.response.status;
+    }
+
+    return undefined;
+  }
+
+  // The error code of a failed Bot Framework call, e.g. "MessageSizeTooBig".
+  public static getErrorCode(error: unknown): string | undefined {
+    if (!error || typeof error !== "object") {
+      return undefined;
+    }
+
+    const candidate: {
+      code?: unknown;
+      details?: { error?: { code?: unknown } | undefined } | undefined;
+    } = error as {
+      code?: unknown;
+      details?: { error?: { code?: unknown } | undefined } | undefined;
+    };
+
+    if (typeof candidate.code === "string" && candidate.code) {
+      return candidate.code;
+    }
+
+    if (
+      typeof candidate.details?.error?.code === "string" &&
+      candidate.details.error.code
+    ) {
+      return candidate.details.error.code;
+    }
+
+    return undefined;
+  }
+
+  /*
+   * A text reply cut down to the budget, with a note that it was shortened
+   * when the note fits as well. The cut is made at the last line break that
+   * fits, so no markdown line is split, or mid-line (never inside an emoji)
+   * when the first line alone is over the budget. The result is never over
+   * the budget; text within it is returned as it is.
+   */
+  public static fitTextToBudget(data: {
+    text: string;
+    budgetInBytes?: number | undefined;
+    truncationNote?: string | undefined;
+  }): string {
+    const budgetInBytes: number =
+      data.budgetInBytes ?? MICROSOFT_TEAMS_TEXT_MESSAGE_BUDGET_IN_BYTES;
+
+    if (this.getSizeInBytes(data.text) <= budgetInBytes) {
+      return data.text;
+    }
+
+    const maxUnits: number = Math.max(0, Math.floor(budgetInBytes / 2));
+    const requestedNote: string =
+      data.truncationNote ?? DEFAULT_TRUNCATION_NOTE;
+
+    // A note that does not fit leaves the whole budget to the text.
+    const truncationNote: string =
+      requestedNote.length <= maxUnits ? requestedNote : "";
+    const maxLength: number = maxUnits - truncationNote.length;
+
+    // A line that ends exactly at the cut still fits, so the search includes it.
+    const lastLineBreak: number = data.text.lastIndexOf("\n", maxLength);
+
+    const kept: string =
+      lastLineBreak > 0
+        ? data.text.substring(0, lastLineBreak)
+        : truncateToLength(data.text, maxLength);
+
+    return kept.trimEnd() + truncationNote;
+  }
+}