@oneuptime/common 12.0.34 → 13.0.1

package/Server/Utils/Dashboard/PublicDashboardResourceListPolicy.ts

@@ -21,6 +21,7 @@ import DashboardModelQueryInterpolation, {
   AttributeToColumnMap,
 } from "../../../Utils/Dashboard/ModelQueryVariableInterpolation";
 import DashboardVariableInterpolation from "../../../Utils/Dashboard/VariableInterpolation";
+import DashboardLabelVariable from "../../../Utils/Dashboard/LabelVariable";
 
 export interface PublicDashboardResourceListPolicyResult {
   resourceType: string;
@@ -137,6 +138,29 @@ const PROXMOX_NODE_ATTRIBUTE_TO_COLUMN: AttributeToColumnMap = {
   "pve.id": "name",
 };
 
+/*
+ * The vcenter receiver stamps identity on RESOURCE attributes, so a
+ * dashboard variable may be keyed either as the bare attribute or as the
+ * `resource.`-prefixed form the metrics explorer exposes.
+ */
+const VMWARE_HOST_ATTRIBUTE_TO_COLUMN: AttributeToColumnMap = {
+  "vcenter.host.name": "name",
+  "resource.vcenter.host.name": "name",
+  "vcenter.cluster.name": "clusterName",
+  "resource.vcenter.cluster.name": "clusterName",
+  "vcenter.datacenter.name": "datacenterName",
+  "resource.vcenter.datacenter.name": "datacenterName",
+};
+
+const VMWARE_VIRTUAL_MACHINE_ATTRIBUTE_TO_COLUMN: AttributeToColumnMap = {
+  "vcenter.vm.name": "name",
+  "resource.vcenter.vm.name": "name",
+  "vcenter.host.name": "hostName",
+  "resource.vcenter.host.name": "hostName",
+  "vcenter.cluster.name": "clusterName",
+  "resource.vcenter.cluster.name": "clusterName",
+};
+
 const CEPH_OSD_ATTRIBUTE_TO_COLUMN: AttributeToColumnMap = {
   ceph_daemon: "externalId",
 };
@@ -180,6 +204,7 @@ export default class PublicDashboardResourceListPolicy {
       componentType: componentType as DashboardComponentType,
       argumentsObject,
       requestedQuery: data.requestedQuery,
+      variables,
     });
 
     let query: Record<string, unknown> = draft.query;
@@ -412,6 +437,41 @@ export default class PublicDashboardResourceListPolicy {
           proxmoxClusterId: true,
           proxmoxCluster: { name: true },
         };
+      case DashboardComponentType.VMwareHostList:
+        return {
+          _id: true,
+          name: true,
+          externalId: true,
+          kind: true,
+          datacenterName: true,
+          clusterName: true,
+          latestCpuPercent: true,
+          latestMemoryPercent: true,
+          cpuCapacityMhz: true,
+          maxMemoryBytes: true,
+          metricsUpdatedAt: true,
+          vmwareVCenterId: true,
+          vmwareVCenter: { name: true },
+        };
+      case DashboardComponentType.VMwareVirtualMachineList:
+        return {
+          _id: true,
+          name: true,
+          externalId: true,
+          kind: true,
+          datacenterName: true,
+          clusterName: true,
+          hostName: true,
+          resourcePoolName: true,
+          isPoweredOn: true,
+          isTemplate: true,
+          latestCpuPercent: true,
+          latestMemoryPercent: true,
+          latestDiskPercent: true,
+          metricsUpdatedAt: true,
+          vmwareVCenterId: true,
+          vmwareVCenter: { name: true },
+        };
       case DashboardComponentType.CephOsdList:
         return {
           _id: true,
@@ -505,8 +565,9 @@ export default class PublicDashboardResourceListPolicy {
     componentType: DashboardComponentType;
     argumentsObject: Record<string, unknown>;
     requestedQuery: unknown;
+    variables: Array<DashboardVariable>;
   }): PolicyDraft {
-    const { componentType, argumentsObject, requestedQuery } = data;
+    const { componentType, argumentsObject, requestedQuery, variables } = data;
 
     switch (componentType) {
       case DashboardComponentType.IncidentList:
@@ -520,6 +581,7 @@ export default class PublicDashboardResourceListPolicy {
       case DashboardComponentType.MonitorList:
         return PublicDashboardResourceListPolicy.buildMonitorPolicy(
           argumentsObject,
+          variables,
         );
       case DashboardComponentType.NetworkMap:
         return PublicDashboardResourceListPolicy.buildNetworkMapPolicy(
@@ -671,6 +733,14 @@ export default class PublicDashboardResourceListPolicy {
         return PublicDashboardResourceListPolicy.buildProxmoxGuestPolicy(
           argumentsObject,
         );
+      case DashboardComponentType.VMwareHostList:
+        return PublicDashboardResourceListPolicy.buildVMwareHostPolicy(
+          argumentsObject,
+        );
+      case DashboardComponentType.VMwareVirtualMachineList:
+        return PublicDashboardResourceListPolicy.buildVMwareVirtualMachinePolicy(
+          argumentsObject,
+        );
       case DashboardComponentType.CephOsdList:
         return PublicDashboardResourceListPolicy.buildCephOsdPolicy(
           argumentsObject,
@@ -814,6 +884,7 @@ export default class PublicDashboardResourceListPolicy {
 
   private static buildMonitorPolicy(
     argumentsObject: Record<string, unknown>,
+    variables: Array<DashboardVariable>,
   ): PolicyDraft {
     const query: Record<string, unknown> = {};
     const statusFilter: string | undefined =
@@ -841,12 +912,22 @@ export default class PublicDashboardResourceListPolicy {
       argumentsObject,
       argumentKey: "monitorTypes",
     });
-    PublicDashboardResourceListPolicy.addIncludesFromArgument({
-      query,
-      queryKey: "labels",
-      argumentsObject,
-      argumentKey: "labelIds",
-    });
+    const labels: ReturnType<typeof DashboardLabelVariable.getFilter> =
+      DashboardLabelVariable.getFilter({
+        labelIds: PublicDashboardResourceListPolicy.optionalStringArray(
+          argumentsObject,
+          "labelIds",
+        ),
+        labelVariableId: PublicDashboardResourceListPolicy.optionalString(
+          argumentsObject,
+          "labelVariableId",
+          false,
+        ),
+        variables,
+      });
+    if (labels) {
+      query["labels"] = labels;
+    }
 
     return PublicDashboardResourceListPolicy.listDraft({
       resourceType: "monitor",
@@ -1190,6 +1271,83 @@ export default class PublicDashboardResourceListPolicy {
     });
   }
 
+  /*
+   * ESXi hosts. The vcenter receiver reports no per-host power or
+   * connection state, so the host widget takes only the shared arguments
+   * (vCenter scope, row cap): no status filter is accepted.
+   */
+  private static buildVMwareHostPolicy(
+    argumentsObject: Record<string, unknown>,
+  ): PolicyDraft {
+    const query: Record<string, unknown> = { kind: "Host" };
+    PublicDashboardResourceListPolicy.addIncludesFromArgument({
+      query,
+      queryKey: "vmwareVCenterId",
+      argumentsObject,
+      argumentKey: "vmwareVCenterIds",
+    });
+
+    return {
+      ...PublicDashboardResourceListPolicy.listDraft({
+        resourceType: "vmware-resource",
+        query,
+        sort: { name: SortOrder.Ascending },
+        argumentsObject,
+      }),
+      attributeToColumn: VMWARE_HOST_ATTRIBUTE_TO_COLUMN,
+    };
+  }
+
+  /*
+   * Virtual machines (kind VirtualMachine covers VMs and VM templates;
+   * templates carry isTemplate = true and a null power state).
+   */
+  private static buildVMwareVirtualMachinePolicy(
+    argumentsObject: Record<string, unknown>,
+  ): PolicyDraft {
+    const query: Record<string, unknown> = { kind: "VirtualMachine" };
+    PublicDashboardResourceListPolicy.addIncludesFromArgument({
+      query,
+      queryKey: "vmwareVCenterId",
+      argumentsObject,
+      argumentKey: "vmwareVCenterIds",
+    });
+
+    const powerStateFilter: string | undefined =
+      PublicDashboardResourceListPolicy.optionalEnum(
+        argumentsObject,
+        "powerStateFilter",
+        ["on", "off"],
+      );
+    if (powerStateFilter === "on") {
+      query["isPoweredOn"] = true;
+    } else if (powerStateFilter === "off") {
+      query["isPoweredOn"] = false;
+    }
+
+    const templateFilter: string | undefined =
+      PublicDashboardResourceListPolicy.optionalEnum(
+        argumentsObject,
+        "templateFilter",
+        ["exclude", "only"],
+      );
+    if (templateFilter === "exclude") {
+      query["isTemplate"] = false;
+    } else if (templateFilter === "only") {
+      query["isTemplate"] = true;
+    }
+
+    return {
+      ...PublicDashboardResourceListPolicy.listDraft({
+        resourceType: "vmware-resource",
+        query,
+        sort: { name: SortOrder.Ascending },
+        argumentsObject,
+      }),
+      attributeToColumn: VMWARE_VIRTUAL_MACHINE_ATTRIBUTE_TO_COLUMN,
+    };
+  }
+
   private static buildCephOsdPolicy(
     argumentsObject: Record<string, unknown>,
   ): PolicyDraft {
@@ -1653,19 +1811,19 @@ export default class PublicDashboardResourceListPolicy {
           storedValue,
           "Stored dashboard variable",
         );
-      if (stored["type"] !== DashboardVariableType.TelemetryAttribute) {
+      const type: unknown = stored["type"];
+      if (
+        type !== DashboardVariableType.TelemetryAttribute &&
+        type !== DashboardVariableType.ProjectLabel
+      ) {
         continue;
       }
 
       const id: unknown = stored["id"];
-      const attributeKey: unknown = stored["attributeKey"];
       if (
         typeof id !== "string" ||
         id.length === 0 ||
-        id.length > MAX_VARIABLE_ID_LENGTH ||
-        typeof attributeKey !== "string" ||
-        attributeKey.trim().length === 0 ||
-        attributeKey.length > MAX_VARIABLE_VALUE_LENGTH
+        id.length > MAX_VARIABLE_ID_LENGTH
       ) {
         throw new BadDataException("Stored dashboard variable is malformed.");
       }
@@ -1700,11 +1858,10 @@ export default class PublicDashboardResourceListPolicy {
       const name: unknown = stored["name"];
       const storedIsMultiSelect: boolean = isMultiSelect === true;
 
-      variables.push({
+      const variable: DashboardVariable = {
         id,
         name: typeof name === "string" ? name : "",
-        type: DashboardVariableType.TelemetryAttribute,
-        attributeKey: attributeKey.trim(),
+        type,
         isMultiSelect: storedIsMultiSelect,
         defaultValue:
           typeof defaultValue === "string" ? defaultValue : undefined,
@@ -1716,12 +1873,63 @@ export default class PublicDashboardResourceListPolicy {
           storedIsMultiSelect && Array.isArray(selectedValues)
             ? (selectedValues as Array<string>)
             : undefined,
-      });
+      };
+
+      if (type === DashboardVariableType.ProjectLabel) {
+        variable.labelOptions =
+          PublicDashboardResourceListPolicy.readLabelOptions(stored);
+      } else {
+        const attributeKey: unknown = stored["attributeKey"];
+        if (
+          typeof attributeKey !== "string" ||
+          attributeKey.trim().length === 0 ||
+          attributeKey.length > MAX_VARIABLE_VALUE_LENGTH
+        ) {
+          throw new BadDataException("Stored dashboard variable is malformed.");
+        }
+        variable.attributeKey = attributeKey.trim();
+      }
+
+      variables.push(variable);
     }
 
     return variables;
   }
 
+  private static readLabelOptions(
+    stored: Record<string, unknown>,
+  ): NonNullable<DashboardVariable["labelOptions"]> {
+    const value: unknown = stored["labelOptions"];
+    if (!Array.isArray(value)) {
+      throw new BadDataException(
+        "Stored dashboard label options are malformed.",
+      );
+    }
+
+    return value.map((entry: unknown): { label: string; value: string } => {
+      const option: Record<string, unknown> =
+        PublicDashboardResourceListPolicy.requireObject(
+          entry,
+          "Stored dashboard label option",
+        );
+      const label: unknown = option["label"];
+      const labelId: unknown = option["value"];
+      if (
+        typeof label !== "string" ||
+        label.length === 0 ||
+        label.length > MAX_VARIABLE_VALUE_LENGTH ||
+        typeof labelId !== "string" ||
+        labelId.length === 0 ||
+        labelId.length > MAX_VARIABLE_VALUE_LENGTH
+      ) {
+        throw new BadDataException(
+          "Stored dashboard label options are malformed.",
+        );
+      }
+      return { label, value: labelId };
+    });
+  }
+
   private static validateRequestedVariableSelections(
     requestedVariables: unknown,
   ): Map<string, Record<string, unknown>> {

package/Server/Utils/DataSource/EgressGuard.ts

@@ -3,6 +3,10 @@ import http from "http";
 import https from "https";
 import net from "net";
 import BadDataException from "../../../Types/Exception/BadDataException";
+import EgressGuardException, {
+  EgressFailureReason,
+} from "../../../Types/Exception/EgressGuardException";
+import logger from "../Logger";
 
 /*
  * SSRF egress guard for outbound connections whose target is chosen by a
@@ -80,6 +84,21 @@ export interface EgressGuardOptions {
    * requests set it to false and receive one indistinguishable failure.
    */
   includeResolvedAddressInError?: boolean | undefined;
+  /*
+   * TOTAL wall-clock budget for name resolution, across every attempt. It is a
+   * safety net against a wedged resolver, not a latency policy: callers with
+   * their own deadline (probe monitors have an execution-context timeout) pass
+   * a value above the resolver's own configured budget so the resolver's
+   * nameserver failover is allowed to finish, and let their deadline do the
+   * real bounding. Defaults to DEFAULT_DNS_RESOLVE_BUDGET_IN_MS.
+   */
+  resolveTimeoutInMs?: number | undefined;
+  /*
+   * How many getaddrinfo attempts to make inside the budget above. Retrying
+   * absorbs the transient resolver failures (EAI_AGAIN, a nameserver
+   * restarting) that otherwise surface as a hard "target is down".
+   */
+  resolveAttempts?: number | undefined;
 }
 
 export interface PinnedAgents {
@@ -112,7 +131,23 @@ export interface AddressVerdict {
   isPrivateNetwork?: boolean | undefined;
 }
 
-const DNS_LOOKUP_TIMEOUT_IN_MS: number = 5000;
+/*
+ * Total resolution budget. Chosen so existing callers see no change in
+ * worst-case latency versus the single 5s lookup this replaced — the retries
+ * below fit INSIDE the same budget rather than extending it.
+ */
+export const DEFAULT_DNS_RESOLVE_BUDGET_IN_MS: number = 5000;
+
+/*
+ * getaddrinfo fails transiently far more often than a host actually
+ * disappears — EAI_AGAIN under resolver load is the classic case, and it is
+ * why the Helm chart ships fallback nameservers. One shot at it turned every
+ * such blip into a monitor-down incident.
+ */
+export const DEFAULT_DNS_RESOLVE_ATTEMPTS: number = 3;
+
+// Short enough that three attempts still fit comfortably in a 5s budget.
+const DNS_RESOLVE_RETRY_DELAY_IN_MS: number = 150;
 
 interface Ipv4Range {
   base: number;
@@ -485,8 +520,9 @@ export default class DataSourceEgressGuard {
     return { blocked: true, reason: "not a valid IP address" };
   }
 
-  private static async defaultResolve(
+  private static async lookupOnce(
     hostname: string,
+    timeoutInMs: number,
   ): Promise<Array<ResolvedAddress>> {
     /*
      * dns.lookup (getaddrinfo) rather than dns.resolve so /etc/hosts and
@@ -506,7 +542,7 @@ export default class DataSourceEgressGuard {
       (_resolve: (value: never) => void, reject: (error: Error) => void) => {
         timeoutHandle = setTimeout(() => {
           reject(new BadDataException(`DNS lookup timed out for ${hostname}`));
-        }, DNS_LOOKUP_TIMEOUT_IN_MS);
+        }, timeoutInMs);
       },
     );
 
@@ -519,6 +555,77 @@ export default class DataSourceEgressGuard {
     }
   }
 
+  /*
+   * Resolve with a bounded number of retries inside ONE total budget.
+   *
+   * A resolver that answers "no" instantly (NXDOMAIN, SERVFAIL, EAI_AGAIN) is
+   * retried within milliseconds, which is exactly the case that used to turn a
+   * momentary blip into an incident. A resolver that HANGS consumes the budget
+   * on its first attempt and is not retried, so the worst case is unchanged
+   * from the single lookup this replaced.
+   */
+  private static async defaultResolve(
+    hostname: string,
+    options?: EgressGuardOptions,
+  ): Promise<Array<ResolvedAddress>> {
+    const budgetInMs: number = Math.max(
+      1,
+      options?.resolveTimeoutInMs ?? DEFAULT_DNS_RESOLVE_BUDGET_IN_MS,
+    );
+    const maxAttempts: number = Math.max(
+      1,
+      options?.resolveAttempts ?? DEFAULT_DNS_RESOLVE_ATTEMPTS,
+    );
+
+    const startedAt: number = Date.now();
+
+    /*
+     * Keep the FIRST failure, not the last. Attempt one gets the whole budget,
+     * so its error is either the real resolver errno or a genuine full-budget
+     * timeout; a later attempt runs on whatever is left and can time out
+     * generically, burying the diagnosis. That errno is the entire value here
+     * — for detail-permitted callers it IS the user-facing message, and for a
+     * probe it is all the operator log has to go on.
+     */
+    let firstError: unknown = undefined;
+
+    for (let attempt: number = 1; attempt <= maxAttempts; attempt++) {
+      const remainingInMs: number = budgetInMs - (Date.now() - startedAt);
+
+      if (remainingInMs <= 0) {
+        break;
+      }
+
+      try {
+        return await this.lookupOnce(hostname, remainingInMs);
+      } catch (error) {
+        if (firstError === undefined) {
+          firstError = error;
+        }
+      }
+
+      /*
+       * Only sleep when another attempt can still start AND finish inside the
+       * budget; otherwise the delay is pure added latency on a failure.
+       */
+      const budgetLeftInMs: number = budgetInMs - (Date.now() - startedAt);
+      if (
+        attempt >= maxAttempts ||
+        budgetLeftInMs <= DNS_RESOLVE_RETRY_DELAY_IN_MS
+      ) {
+        break;
+      }
+
+      await new Promise<void>((resolve: () => void) => {
+        setTimeout(resolve, DNS_RESOLVE_RETRY_DELAY_IN_MS);
+      });
+    }
+
+    throw (
+      firstError ?? new BadDataException(`DNS lookup timed out for ${hostname}`)
+    );
+  }
+
   /*
    * Resolve a hostname (or accept a literal IP) and assert every address it
    * can reach is allowed. Returns the validated addresses so HTTP callers
@@ -533,7 +640,10 @@ export default class DataSourceEgressGuard {
     const label: string = options?.targetLabel || DEFAULT_TARGET_LABEL;
 
     if (!hostname) {
-      throw new BadDataException(`${label} host is required.`);
+      throw new EgressGuardException(
+        `${label} host is required.`,
+        EgressFailureReason.InvalidTarget,
+      );
     }
 
     // Literal [::1] style hosts arrive with brackets from URL parsing.
@@ -542,10 +652,15 @@ export default class DataSourceEgressGuard {
     if (net.isIP(bareHostname) !== 0) {
       const verdict: AddressVerdict = this.checkAddress(bareHostname, options);
       if (verdict.blocked) {
-        throw new BadDataException(
+        /*
+         * A literal IP is echoed back with full detail on purpose: it tells
+         * the caller only what the caller itself typed.
+         */
+        throw new EgressGuardException(
           `${label} host ${bareHostname} is not allowed: ${verdict.reason}.${
             verdict.isPrivateNetwork ? options?.privateNetworkHint || "" : ""
           }`,
+          EgressFailureReason.AddressBlocked,
         );
       }
       return [{ address: bareHostname, family: net.isIP(bareHostname) }];
@@ -554,7 +669,7 @@ export default class DataSourceEgressGuard {
     const resolveFunction: EgressResolveFunction =
       options?.resolveFunction ||
       ((host: string) => {
-        return this.defaultResolve(host);
+        return this.defaultResolve(host, options);
       });
 
     let addresses: Array<ResolvedAddress> = [];
@@ -562,25 +677,40 @@ export default class DataSourceEgressGuard {
       addresses = await resolveFunction(bareHostname);
     } catch (error) {
       if (options?.includeResolvedAddressInError === false) {
-        throw new BadDataException(
+        /*
+         * The cause is destroyed for the caller by design, so log it here:
+         * this is the only place an operator can still learn whether a
+         * monitor failed on DNS or on address policy.
+         */
+        logger.debug(
+          `EgressGuard: could not resolve ${bareHostname} - ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+        throw new EgressGuardException(
           `${label} host ${bareHostname} could not be reached.`,
+          EgressFailureReason.Unreachable,
         );
       }
-      throw new BadDataException(
+      throw new EgressGuardException(
         `Could not resolve ${label.toLowerCase()} host ${bareHostname}: ${
           error instanceof Error ? error.message : String(error)
         }`,
+        EgressFailureReason.ResolutionFailed,
       );
     }
 
     if (addresses.length === 0) {
       if (options?.includeResolvedAddressInError === false) {
-        throw new BadDataException(
+        logger.debug(`EgressGuard: ${bareHostname} resolved to no addresses.`);
+        throw new EgressGuardException(
           `${label} host ${bareHostname} could not be reached.`,
+          EgressFailureReason.Unreachable,
         );
       }
-      throw new BadDataException(
+      throw new EgressGuardException(
         `Could not resolve ${label.toLowerCase()} host ${bareHostname}.`,
+        EgressFailureReason.ResolutionFailed,
       );
     }
 
@@ -591,14 +721,24 @@ export default class DataSourceEgressGuard {
       );
       if (verdict.blocked) {
         if (options?.includeResolvedAddressInError === false) {
-          throw new BadDataException(
+          logger.debug(
+            `EgressGuard: ${bareHostname} resolved to a blocked address - ${verdict.reason}.`,
+          );
+          /*
+           * Reported as Unreachable, NOT AddressBlocked. Sharing one reason
+           * with the DNS branches above is what stops a tenant on a shared
+           * probe from using the difference to enumerate internal names.
+           */
+          throw new EgressGuardException(
             `${label} host ${bareHostname} could not be reached.`,
+            EgressFailureReason.Unreachable,
           );
         }
-        throw new BadDataException(
+        throw new EgressGuardException(
           `${label} host ${bareHostname} resolves to ${resolved.address}, which is not allowed: ${verdict.reason}.${
             verdict.isPrivateNetwork ? options?.privateNetworkHint || "" : ""
           }`,
+          EgressFailureReason.AddressBlocked,
         );
       }
     }
@@ -618,24 +758,29 @@ export default class DataSourceEgressGuard {
     const label: string = options?.targetLabel || DEFAULT_TARGET_LABEL;
 
     if (!urlString) {
-      throw new BadDataException(`${label} URL is required.`);
+      throw new EgressGuardException(
+        `${label} URL is required.`,
+        EgressFailureReason.InvalidTarget,
+      );
     }
 
     let url: URL;
     try {
       url = new URL(urlString);
     } catch {
-      throw new BadDataException(
+      throw new EgressGuardException(
         `Invalid ${label.toLowerCase()} URL: ${urlString}`,
+        EgressFailureReason.InvalidTarget,
       );
     }
 
     if (url.protocol !== "http:" && url.protocol !== "https:") {
-      throw new BadDataException(
+      throw new EgressGuardException(
         `${label} URL must use http or https (got ${url.protocol.replace(
           ":",
           "",
         )}).`,
+        EgressFailureReason.InvalidTarget,
       );
     }
 

package/Server/Utils/Database/TruncateColumnValue.ts

@@ -6,7 +6,7 @@ import ColumnLength from "../../../Types/Database/ColumnLength";
  *
  * Per-value clamps for bounded varchar columns written by the bulk
  * inventory upsert paths (Kubernetes / Docker / Docker Swarm / Podman /
- * Proxmox / Ceph / IoT).
+ * Proxmox / VMware / Ceph / IoT).
  *
  * Those services hand-build `INSERT ... ON CONFLICT` statements and
  * flush them in chunks of 500 rows through

package/Server/Utils/EmailRollup/EmailRollupFlushRunner.ts

@@ -636,6 +636,8 @@ export default class EmailRollupFlushRunner {
           eventType: true,
           rollupCategory: true,
           subject: true,
+          severity: true,
+          currentState: true,
           viewLink: true,
           createdAt: true,
         },
@@ -751,9 +753,18 @@ export default class EmailRollupFlushRunner {
     const projectHomeLink: string = URL.fromString(dashboardUrl.toString())
       .addRoute(`/${bucket.projectId.toString()}/home`)
       .toString();
+    /*
+     * Email Preferences, not Notification Settings: this footer exists to
+     * offer the reader a way out of BATCHING, and the rollup switch lives on
+     * Email Preferences. Notification Settings is one link further on, from
+     * the page this lands on. The segment is duplicated from the Dashboard's
+     * UserSettingsRoutePath for the reason OnCallSetupReminderService gives -
+     * Common/Server cannot import App sources - so a route rename there has
+     * to be repeated here.
+     */
     const preferencesLink: string = URL.fromString(dashboardUrl.toString())
       .addRoute(
-        `/${bucket.projectId.toString()}/user-settings/notification-settings`,
+        `/${bucket.projectId.toString()}/user-settings/email-preferences`,
       )
       .toString();