@oneuptime/common 12.0.29 → 12.0.31

package/Server/Utils/OnCall/OnCallCalendarFeedUrls.ts

@@ -0,0 +1,230 @@
+import { Host, HttpProtocol } from "../../EnvironmentConfig";
+import { AppApiRoute } from "../../../ServiceRoute";
+import Protocol from "../../../Types/API/Protocol";
+import { OnCallCalendarFeedKind } from "../../../Types/OnCallDutyPolicy/OnCallCalendarFeedUtil";
+
+/*
+ * The subscription URLs of an on-call calendar feed, and the two deployment
+ * warnings the settings page shows next to them.
+ *
+ * Every URL is built from the instance's OWN configuration (HOST and
+ * HTTP_PROTOCOL), never from the request that asked for it: a Host header is
+ * caller-supplied, and a link minted from it would be a link to wherever the
+ * caller said. The three shapes are the three ways calendar clients take a
+ * subscription:
+ *
+ *   https     the plain URL. Google Calendar ("From URL"), Outlook on the web
+ *             and Thunderbird take this as-is.
+ *   webcal    the same URL under the webcal:// scheme (webcals:// when the
+ *             instance serves https). Apple Calendar on macOS and iOS opens it
+ *             straight into a "Subscribe" sheet; Windows without Outlook has no
+ *             handler for it, which the docs explain.
+ *   googleAdd Google Calendar's add-by-URL deep link, the https URL encoded
+ *             into its `cid` parameter.
+ *
+ * The path segments are a public contract shared with the Nginx access-log
+ * exemption (`^/api/on-call-calendar/(user|schedule|project)/`) and the
+ * OnCallCalendarAPI routes; change them together or not at all.
+ */
+
+export const ON_CALL_CALENDAR_ROUTE_PREFIX: string = "/on-call-calendar";
+
+export const PERSONAL_FEED_FILE_NAME: string = "shifts.ics";
+export const SCHEDULE_FEED_FILE_NAME: string = "schedule.ics";
+export const PROJECT_FEED_FILE_NAME: string = "project.ics";
+
+export const GOOGLE_CALENDAR_ADD_BY_URL: string =
+  "https://calendar.google.com/calendar/r?cid=";
+
+export const HOST_WARNING: string =
+  "HOST is not set to a public address, so calendar apps outside this machine cannot reach this link. Set HOST to the address your team uses to open OneUptime.";
+
+export const PROTOCOL_WARNING: string =
+  "HTTP_PROTOCOL is http, so this link travels unencrypted. Anyone who can see the traffic can read the link and the shifts it serves; serve OneUptime over https to fix this.";
+
+/*
+ * Hosts that only ever resolve to the machine the browser runs on. A link
+ * built on one of these works for exactly one person, and only until they
+ * close their laptop.
+ */
+const LOCAL_HOST_NAMES: Array<string> = [
+  "localhost",
+  "127.0.0.1",
+  "0.0.0.0",
+  "::1",
+  "[::1]",
+];
+
+export interface FeedUrls {
+  https: string;
+  webcal: string;
+  googleAdd: string;
+}
+
+export interface FeedUrlOptions {
+  kind: OnCallCalendarFeedKind;
+  token: string;
+  /* Defaults to EnvironmentConfig.Host. */
+  host?: string | undefined;
+  /* Defaults to EnvironmentConfig.HttpProtocol. */
+  protocol?: Protocol | undefined;
+}
+
+export default class OnCallCalendarFeedUrls {
+  /*
+   * The route path (without the /api prefix) a feed of this kind is served
+   * on, e.g. `/on-call-calendar/user/<token>/shifts.ics`.
+   */
+  public static getFeedRoutePath(
+    kind: OnCallCalendarFeedKind,
+    token: string,
+  ): string {
+    const segment: string = OnCallCalendarFeedUrls.getKindSegment(kind);
+    const fileName: string = OnCallCalendarFeedUrls.getFileName(kind);
+
+    return `${ON_CALL_CALENDAR_ROUTE_PREFIX}/${segment}/${encodeURIComponent(
+      token,
+    )}/${fileName}`;
+  }
+
+  /*
+   * The public path INCLUDING the /api prefix that the app router is mounted
+   * under, e.g. `/api/on-call-calendar/user/<token>/shifts.ics`.
+   */
+  public static getFeedPath(
+    kind: OnCallCalendarFeedKind,
+    token: string,
+  ): string {
+    return `${AppApiRoute.toString()}${OnCallCalendarFeedUrls.getFeedRoutePath(
+      kind,
+      token,
+    )}`;
+  }
+
+  /*
+   * The path segment after /on-call-calendar/ for each feed kind. "user" for
+   * the personal feed (not "personal") because it is what the URL says and
+   * what the Nginx location matches.
+   */
+  public static getKindSegment(kind: OnCallCalendarFeedKind): string {
+    switch (kind) {
+      case OnCallCalendarFeedKind.Personal:
+        return "user";
+      case OnCallCalendarFeedKind.Schedule:
+        return "schedule";
+      case OnCallCalendarFeedKind.Project:
+        return "project";
+      default:
+        return "user";
+    }
+  }
+
+  public static getFileName(kind: OnCallCalendarFeedKind): string {
+    switch (kind) {
+      case OnCallCalendarFeedKind.Personal:
+        return PERSONAL_FEED_FILE_NAME;
+      case OnCallCalendarFeedKind.Schedule:
+        return SCHEDULE_FEED_FILE_NAME;
+      case OnCallCalendarFeedKind.Project:
+        return PROJECT_FEED_FILE_NAME;
+      default:
+        return PERSONAL_FEED_FILE_NAME;
+    }
+  }
+
+  public static buildFeedUrls(options: FeedUrlOptions): FeedUrls {
+    const protocol: Protocol =
+      options.protocol === undefined ? HttpProtocol : options.protocol;
+    const host: string = OnCallCalendarFeedUrls.normalizeHost(
+      options.host === undefined ? Host : options.host,
+    );
+
+    const path: string = OnCallCalendarFeedUrls.getFeedPath(
+      options.kind,
+      options.token,
+    );
+
+    const https: string = `${protocol}${host}${path}`;
+
+    const webcalScheme: string =
+      protocol === Protocol.HTTPS ? "webcals://" : "webcal://";
+
+    const webcal: string = `${webcalScheme}${host}${path}`;
+
+    const googleAdd: string = `${GOOGLE_CALENDAR_ADD_BY_URL}${encodeURIComponent(
+      https,
+    )}`;
+
+    return { https, webcal, googleAdd };
+  }
+
+  /*
+   * Non-null when the configured HOST cannot be reached from anywhere but
+   * this machine: empty (the default on a fresh install) or a loopback name.
+   */
+  public static getHostWarning(host?: string | undefined): string | null {
+    const value: string = OnCallCalendarFeedUrls.normalizeHost(
+      host === undefined ? Host : host,
+    );
+
+    if (!value) {
+      return HOST_WARNING;
+    }
+
+    const withoutPort: string = OnCallCalendarFeedUrls.stripPort(value);
+
+    if (LOCAL_HOST_NAMES.includes(withoutPort.toLowerCase())) {
+      return HOST_WARNING;
+    }
+
+    return null;
+  }
+
+  /*
+   * Non-null when the instance serves plain http, so the link -- a bearer
+   * credential -- would cross the network in the clear.
+   */
+  public static getProtocolWarning(
+    protocol?: Protocol | undefined,
+  ): string | null {
+    const value: Protocol = protocol === undefined ? HttpProtocol : protocol;
+
+    if (value !== Protocol.HTTPS) {
+      return PROTOCOL_WARNING;
+    }
+
+    return null;
+  }
+
+  /*
+   * HOST is documented as a bare host[:port], but installs do put a scheme or
+   * a trailing slash in it. Strip both so the URL never reads
+   * "https://https://example.com//api/...".
+   */
+  public static normalizeHost(host: string): string {
+    let value: string = (host || "").trim();
+
+    value = value.replace(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//, "");
+
+    while (value.endsWith("/")) {
+      value = value.slice(0, -1);
+    }
+
+    return value;
+  }
+
+  private static stripPort(host: string): string {
+    // [::1]:443 -> [::1]
+    if (host.startsWith("[")) {
+      const closing: number = host.indexOf("]");
+      return closing === -1 ? host : host.slice(0, closing + 1);
+    }
+
+    // example.com:8443 -> example.com (one colon = host:port, not IPv6)
+    if (host.split(":").length === 2) {
+      return host.split(":")[0] || host;
+    }
+
+    return host;
+  }
+}

package/Server/Utils/OnCall/OnCallShiftChangeListeners.ts

@@ -0,0 +1,227 @@
+import ObjectID from "../../../Types/ObjectID";
+import logger from "../Logger";
+
+/*
+ * A tiny in-process registry of "somebody's on-call shifts may have changed"
+ * listeners.
+ *
+ * The on-call CRUD hooks (layer, layer user, override, policy attachment,
+ * schedule rename/timezone, member leaving the project) already know exactly
+ * which schedules and users an edit touched. Several consumers want that
+ * signal — the shift-reminder change pass (catch-up and reassigned notices),
+ * and later a push-sync engine — but the services must not import them: the
+ * reminder runner lives next to the Workers and imports the materializer,
+ * which imports the services, so a static import back would be a cycle, and
+ * the hooks must keep working in processes (the API tier, tests) where those
+ * consumers are never loaded.
+ *
+ * So the hooks publish here and the consumers subscribe at boot. Delivery is
+ * best-effort by construction: a listener that throws is logged and never
+ * fails the edit that triggered it, and a slow listener never delays the
+ * response because the hooks do not await `notify`.
+ *
+ * Registration is idempotent. Re-registering under the same name replaces the
+ * listener (so a module that is re-imported by a test harness does not stack
+ * duplicates), and registering the very same function twice without a name
+ * is a no-op.
+ */
+
+export enum OnCallShiftChangeReason {
+  LayerChanged = "LayerChanged",
+  LayerUserChanged = "LayerUserChanged",
+  OverrideChanged = "OverrideChanged",
+  PolicyAttachmentChanged = "PolicyAttachmentChanged",
+  ScheduleChanged = "ScheduleChanged",
+  ScheduleDeleted = "ScheduleDeleted",
+  MemberLeftProject = "MemberLeftProject",
+}
+
+export interface OnCallShiftChangeEvent {
+  /*
+   * Project the change happened in. Null only when the hook could not
+   * determine it (a root write with no project on the row) — listeners
+   * should then fall back to resolving it from the schedules.
+   */
+  projectId: ObjectID | null;
+  /*
+   * Schedules whose resolved shifts may differ from what they were. Empty
+   * when the change touched no schedule (e.g. an override for a user who is
+   * on no schedule), in which case only `userIds` is meaningful.
+   */
+  scheduleIds: Array<ObjectID>;
+  /*
+   * Users whose personal shift list may differ: the members of the affected
+   * schedules plus anyone named directly by the change (an override's
+   * original user and substitute, the user added to / removed from a layer,
+   * the member who left). Best-effort — a listener that needs certainty
+   * should re-materialize the schedules.
+   */
+  userIds: Array<ObjectID>;
+  reason: OnCallShiftChangeReason;
+  /*
+   * When the change was observed. Listeners that keep a watermark compare
+   * against it instead of reading the clock again.
+   */
+  occurredAt: Date;
+}
+
+export type OnCallShiftChangeListener = (
+  event: OnCallShiftChangeEvent,
+) => Promise<void> | void;
+
+interface RegisteredListener {
+  name: string | undefined;
+  listener: OnCallShiftChangeListener;
+}
+
+export default class OnCallShiftChangeListeners {
+  private static listeners: Array<RegisteredListener> = [];
+
+  /**
+   * Register a listener. With a name, a later registration under the same
+   * name REPLACES the earlier one; without a name, registering the same
+   * function reference twice is a no-op. Either way a listener is never
+   * invoked twice for one event.
+   */
+  public static register(
+    listener: OnCallShiftChangeListener,
+    name?: string | undefined,
+  ): void {
+    if (typeof listener !== "function") {
+      throw new Error("OnCallShiftChangeListeners.register expects a function");
+    }
+
+    if (name) {
+      const existing: RegisteredListener | undefined =
+        OnCallShiftChangeListeners.listeners.find(
+          (entry: RegisteredListener) => {
+            return entry.name === name;
+          },
+        );
+
+      if (existing) {
+        existing.listener = listener;
+        return;
+      }
+
+      OnCallShiftChangeListeners.listeners.push({ name, listener });
+      return;
+    }
+
+    const alreadyRegistered: boolean =
+      OnCallShiftChangeListeners.listeners.some((entry: RegisteredListener) => {
+        return entry.listener === listener;
+      });
+
+    if (alreadyRegistered) {
+      return;
+    }
+
+    OnCallShiftChangeListeners.listeners.push({ name: undefined, listener });
+  }
+
+  /**
+   * Remove a listener by name or by function reference. Unknown names /
+   * functions are ignored.
+   */
+  public static unregister(
+    listenerOrName: OnCallShiftChangeListener | string,
+  ): void {
+    OnCallShiftChangeListeners.listeners =
+      OnCallShiftChangeListeners.listeners.filter(
+        (entry: RegisteredListener) => {
+          if (typeof listenerOrName === "string") {
+            return entry.name !== listenerOrName;
+          }
+          return entry.listener !== listenerOrName;
+        },
+      );
+  }
+
+  /** Drop every listener. For tests. */
+  public static clear(): void {
+    OnCallShiftChangeListeners.listeners = [];
+  }
+
+  public static getRegisteredNames(): Array<string | undefined> {
+    return OnCallShiftChangeListeners.listeners.map(
+      (entry: RegisteredListener) => {
+        return entry.name;
+      },
+    );
+  }
+
+  public static getCount(): number {
+    return OnCallShiftChangeListeners.listeners.length;
+  }
+
+  /**
+   * Deliver one event to every listener. Never rejects: each listener runs
+   * inside its own try/catch, synchronous throws and rejected promises alike
+   * are logged and swallowed, and the remaining listeners still run. The
+   * returned promise settles when every listener has settled, so a caller
+   * that wants to wait can; the CRUD hooks deliberately do not.
+   */
+  public static async notify(event: OnCallShiftChangeEvent): Promise<void> {
+    // Snapshot so a listener that (un)registers during delivery is safe.
+    const snapshot: Array<RegisteredListener> = [
+      ...OnCallShiftChangeListeners.listeners,
+    ];
+
+    const deliveries: Array<Promise<void>> = snapshot.map(
+      async (entry: RegisteredListener): Promise<void> => {
+        try {
+          await entry.listener(event);
+        } catch (err) {
+          logger.error(
+            `On-call shift change listener${entry.name ? ` "${entry.name}"` : ""} failed (best-effort, ignored).`,
+          );
+          logger.error(err);
+        }
+      },
+    );
+
+    await Promise.all(deliveries);
+  }
+
+  /**
+   * Build an event with defaults: ids deduplicated, `occurredAt` = now.
+   */
+  public static buildEvent(data: {
+    projectId: ObjectID | null | undefined;
+    scheduleIds: Array<ObjectID>;
+    userIds?: Array<ObjectID> | undefined;
+    reason: OnCallShiftChangeReason;
+    occurredAt?: Date | undefined;
+  }): OnCallShiftChangeEvent {
+    return {
+      projectId: data.projectId || null,
+      scheduleIds: OnCallShiftChangeListeners.dedupe(data.scheduleIds),
+      userIds: OnCallShiftChangeListeners.dedupe(data.userIds || []),
+      reason: data.reason,
+      occurredAt: data.occurredAt || new Date(),
+    };
+  }
+
+  public static dedupe(ids: Array<ObjectID>): Array<ObjectID> {
+    const seen: Set<string> = new Set<string>();
+    const result: Array<ObjectID> = [];
+
+    for (const id of ids) {
+      if (!id) {
+        continue;
+      }
+
+      const key: string = id.toString();
+
+      if (!key || seen.has(key)) {
+        continue;
+      }
+
+      seen.add(key);
+      result.push(id);
+    }
+
+    return result;
+  }
+}