rewrite sending emails to notify about mentions to (1) be cleaner code, (2) participate in the daily per-user email throttle limits, (3) NOT disallow sending mentions for users whose projects do not have network access or are not paying -- now everybody can mention, (4) fix a bug that meant no description, and (5) add plain text support. Also slightly more frequent mentions strategy by default.

Author: williamstein

src/packages/backend/accounts/get-email-address.ts

@@ -0,0 +1,15 @@
+// Get email address of an account. If no such account or email not set, returns undefined...
+// Answers are cached for a while.
+
+import getPool from "@cocalc/backend/database";
+
+export default async function getEmailAddress(
+  account_id: string
+): Promise<string | undefined> {
+  const pool = getPool("long");
+  const { rows } = await pool.query(
+    "SELECT email_address FROM accounts WHERE account_id=$1",
+    [account_id]
+  );
+  return rows[0]?.email_address;
+}

src/packages/backend/accounts/get-name.ts

@@ -0,0 +1,13 @@
+// If no such account or no name set, returns "Unknown User".
+// Answers are cached for a while.
+
+import getPool from "@cocalc/backend/database";
+
+export default async function getName(account_id: string): Promise<string> {
+  const pool = getPool("long");
+  const { rows } = await pool.query(
+    "SELECT first_name, last_name FROM accounts WHERE account_id=$1",
+    [account_id]
+  );
+  return `${rows[0]?.first_name ?? "Unknown"} ${rows[0]?.last_name ?? "User"}`;
+}

src/packages/backend/email/sendgrid.ts

@@ -1,6 +1,10 @@
 /* We use the official V3 Sendgrid API:
 
 https://www.npmjs.com/package/@sendgrid/mail
+
+The cocalc ASM group numbers are at
+
+https://app.sendgrid.com/suppressions/advanced_suppression_manager
 */
 
 import getPool from "@cocalc/backend/database";

src/packages/backend/mentions/handle.ts

@@ -0,0 +1,115 @@
+/*
+Handle all mentions that haven't yet been handled.
+*/
+
+import getPool from "@cocalc/backend/database";
+import { delay } from "awaiting";
+import { getLogger } from "@cocalc/backend/logger";
+import type { Action, Key } from "./types";
+import notify from "./notify";
+
+const logger = getLogger("mentions - handle");
+
+// TODO: should be in the database server settings; also should be
+// user configurable, and this is just a default
+const minEmailInterval = "6 hours";
+const maxPerInterval = 2; // get up to 2 emails for a given chatroom every 6 hours.
+
+// We check for new notifications this frequently.
+const polIntervalSeconds = 15;
+
+// Handle all notification, then wait for the given time, then again
+// handle all unhandled notifications.
+export default async function init(): Promise<void> {
+  while (true) {
+    try {
+      await handleAllMentions();
+    } catch (err) {
+      logger.warn(`WARNING -- error handling mentions -- ${err}`);
+    }
+
+    await delay(polIntervalSeconds * 1000);
+  }
+}
+
+async function handleAllMentions(): Promise<void> {
+  const pool = getPool();
+  const { rows } = await pool.query(
+    "SELECT time, project_id, path, source, target, description FROM mentions WHERE action IS null"
+  );
+  for (const row of rows) {
+    const { time, project_id, path, source, target, description } = row;
+    try {
+      await handleMention(
+        { project_id, path, time, target },
+        source,
+        description ?? ""
+      );
+    } catch (err) {
+      logger.warn(
+        `WARNING -- error handling mention (will try later) -- ${err}`
+      );
+    }
+  }
+}
+
+async function handleMention(
+  key: Key,
+  source: string,
+  description: string
+): Promise<void> {
+  // Check that source and target are both currently
+  // collaborators on the project.
+  const action: Action = await determineAction(key);
+  try {
+    switch (action) {
+      case "ignore": // already recently notified about this chatroom.
+        await setAction(key, action);
+        return;
+      case "notify":
+        let whatDid = await notify(key, source, description);
+        // record what we did.
+        await setAction(key, whatDid);
+        return;
+      default:
+        throw Error(`BUG: unknown action "${action}"`);
+    }
+  } catch (err) {
+    await setError(key, action, `${err}`);
+  }
+}
+
+async function determineAction(key: Key): Promise<Action> {
+  const pool = getPool();
+  const { rows } = await pool.query(
+    `SELECT COUNT(*) FROM mentions WHERE project_id=$1 AND path=$2 AND target=$3 AND action = 'email' AND time >= NOW() - INTERVAL '${parseInt(
+      minEmailInterval
+    )}'`,
+    [key.project_id, key.path, key.target]
+  );
+  const count: number = parseInt(rows[0]?.count ?? 0);
+  if (count >= maxPerInterval) {
+    return "ignore";
+  }
+  return "notify";
+}
+
+async function setAction(key: Key, action: Action): Promise<void> {
+  const pool = getPool();
+  await pool.query(
+    "UPDATE mentions SET action=$1 WHERE project_id=$2 AND path=$3 AND time=$4 AND target=$5",
+    [action, key.project_id, key.path, key.time, key.target]
+  );
+}
+
+async function setError(
+  key: Key,
+  action: Action,
+  error: string
+): Promise<void> {
+  const pool = getPool();
+  await pool.query(
+    "UPDATE mentions SET action=$1, error=$2 WHERE project_id=$3 AND path=$4 AND time=$5 AND target=$6",
+    [action, error, key.project_id, key.path, key.time, key.target]
+  );
+}

src/packages/backend/mentions/notify.ts

@@ -0,0 +1,62 @@
+import type { Action, Key } from "./types";
+import getName from "@cocalc/backend/accounts/get-name";
+import getEmailAddress from "@cocalc/backend/accounts/get-email-address";
+import getProjectTitle from "@cocalc/backend/projects/get-title";
+import { trunc } from "@cocalc/util/misc";
+import siteURL from "@cocalc/backend/server-settings/site-url";
+import { getServerSettings } from "@cocalc/backend/server-settings";
+import sendEmail from "@cocalc/backend/email/send-email";
+
+export default async function sendNotificationIfPossible(
+  key: Key,
+  source: string,
+  description: string
+): Promise<Action> {
+  const to = await getEmailAddress(key.target);
+  if (!to) {
+    // Email is the only notification method at present.
+    // Nothing more to do -- target user has no known email address.
+    // They will see notification when they sign in.
+    return "nothing";
+  }
+
+  const sourceName = trunc(await getName(source), 60);
+  const projectTitle = await getProjectTitle(key.project_id);
+
+  const context =
+    description.length > 0
+      ? `<br/><blockquote>${description}</blockquote>`
+      : "";
+  const subject = `[${trunc(projectTitle, 40)}] ${key.path}`;
+  const url = `${await siteURL()}/projects/${key.project_id}/files/${key.path}`;
+  const html = `
+${sourceName} mentioned you in
+<a href="${url}">a chat at ${key.path} in ${projectTitle}</a>.
+${context}
+`;
+
+  const text = `
+${sourceName} mentioned you in a chat at ${key.path} in ${projectTitle}.
+
+    ${url}
+
+${description ? "> " : ""}${description}
+`;
+
+  const { help_email } = await getServerSettings();
+  const from = `${sourceName} <${help_email}>`;
+
+  await sendEmail(
+    {
+      from,
+      to,
+      subject,
+      text,
+      html,
+      categories: ["notification"],
+      asm_group: 148185, // see https://app.sendgrid.com/suppressions/advanced_suppression_manager
+    },
+    source
+  );
+  return "email";
+}

src/packages/backend/mentions/types.ts

@@ -0,0 +1,10 @@
+export interface Key {
+  project_id: string;
+  path: string;
+  time: Date;
+  target: string;
+}
+
+
+export type Action = "ignore" | "notify" | "email" | "nothing";
+

src/packages/backend/package-lock.json

@@ -34,6 +34,7 @@
     "@types/pg": "^8.6.1",
     "async": "^1.5.2",
     "async-await-utils": "^3.0.1",
+    "awaiting": "^3.0.0",
     "debug": "^4.3.2",
     "lru-cache": "^6.0.0",
     "nodemailer": "^6.6.5",

src/packages/backend/package.json

@@ -0,0 +1,10 @@
+import getPool from "@cocalc/backend/database";
+
+export default async function getTitle(project_id: string): Promise<string> {
+  const pool = getPool("long");
+  const { rows } = await pool.query(
+    "SELECT title FROM projects WHERE project_id=$1",
+    [project_id]
+  );
+  return rows[0]?.title ?? "Untitled Project";
+}

src/packages/backend/projects/get-title.ts

@@ -23,7 +23,7 @@ import base_path from "@cocalc/backend/base-path";
 import { migrate_account_token } from "./postgres/migrate-account-token";
 import { init_start_always_running_projects } from "./postgres/always-running";
 import { set_agent_endpoint } from "./health-checks";
-import { handle_mentions_loop } from "./mentions/handle";
+import initHandleMentions from "@cocalc/backend/mentions/handle";
 const MetricsRecorder = require("./metrics-recorder"); // import * as MetricsRecorder from "./metrics-recorder";
 import { start as startHubRegister } from "./hub_register";
 const initZendesk = require("./support").init_support; // import { init_support as initZendesk } from "./support";
@@ -152,7 +152,7 @@ async function startServer(): Promise<void> {
   // Mentions
   if (program.mentions) {
     winston.info("enabling handling of mentions...");
-    handle_mentions_loop(database);
+    initHandleMentions();
   }
 
   // Project control
@@ -215,7 +215,7 @@ async function startServer(): Promise<void> {
     projectControl,
     proxyServer: !!program.proxyServer,
     nextServer: !!program.nextServer,
-        cert: program.httpsCert,
+    cert: program.httpsCert,
     key: program.httpsKey,
   });
 
@@ -227,7 +227,6 @@ async function startServer(): Promise<void> {
     host: program.hostname,
   });
 
-
   winston.info(`starting webserver listening on ${program.hostname}:${port}`);
   await callback(httpServer.listen.bind(httpServer), port, program.hostname);