@oneuptime/common 12.0.29 → 12.0.30

package/Server/Utils/Response.ts

@@ -26,6 +26,32 @@ import PositiveNumber from "../../Types/PositiveNumber";
 import Route from "../../Types/API/Route";
 import CaptureSpan from "./Telemetry/CaptureSpan";
 import { GoogleTagManagerEnabled } from "../EnvironmentConfig";
+import { createHash } from "crypto";
+
+/*
+ * How long a calendar client may reuse a feed body before asking again. The
+ * body cache behind the feed routes has the same TTL, so a client that honours
+ * this sees a new body no later than one it would have been served anyway.
+ */
+export const CALENDAR_RESPONSE_MAX_AGE_SECONDS: number = 300;
+
+export const CALENDAR_RESPONSE_CONTENT_TYPE: string =
+  "text/calendar; charset=utf-8";
+
+export const CALENDAR_RESPONSE_FILE_NAME: string = "oneuptime-on-call.ics";
+
+/*
+ * The response headers a calendar feed carries, as a shape the API and its
+ * tests can share. `etag` may be passed bare or already quoted; the helper
+ * emits the quoted strong form either way. `lastModified` is the newest
+ * change to anything the feed was built from, and is what a client's
+ * If-Modified-Since is compared against.
+ */
+export interface CalendarResponseData {
+  body: string;
+  etag: string;
+  lastModified: Date;
+}
 
 /*
  * Raster image types, which is to say the types that cannot carry script and
@@ -485,6 +511,114 @@ export default class Response {
     oneUptimeResponse.end(javascript);
   }
 
+  /*
+   * A strong ETag for a calendar body: the first 32 hex characters of the
+   * SHA-256 of the exact bytes sent, quoted. Strong rather than weak because
+   * the body is byte-deterministic for a given input (the iCalendar serializer
+   * orders properties and folds lines the same way every time), so two bodies
+   * with the same tag are byte-identical and a client may treat them so.
+   * Computed from the body rather than from an update timestamp so a cached
+   * body and a freshly rendered identical one carry the same tag.
+   */
+  public static getCalendarETag(body: string): string {
+    return `"${createHash("sha256").update(body, "utf8").digest("hex").slice(0, 32)}"`;
+  }
+
+  /*
+   * Send an iCalendar feed body with the headers calendar clients expect.
+   *
+   * Deliberately its own method rather than sendCustomResponse: that one
+   * starts from setNoCacheHeaders, which stamps `Pragma: no-cache` and cannot
+   * take it back, and a feed that says both "max-age=300" and "no-cache" is
+   * re-fetched on every open by clients that honour Pragma. Nor
+   * sendTextResponse, which sets no Content-Type at all and would let Express
+   * fall back to text/html.
+   *
+   * Conditional requests are left to Express: `res.send` answers 304 by itself
+   * when `req.fresh` is true (If-None-Match against the ETag set here, weak
+   * `W/` prefixes included, or If-Modified-Since against Last-Modified), and it
+   * strips the body for HEAD. Nothing here inspects the method.
+   *
+   * private, not public: the body is one person's (or one team's) on-call
+   * roster behind a bearer token in the URL, and a shared cache that stored it
+   * would hand it to the next requester of that URL regardless of who they
+   * are. Expires duplicates max-age for the clients that only read Expires.
+   */
+  @CaptureSpan()
+  public static sendCalendarResponse(
+    _req: ExpressRequest,
+    res: ExpressResponse,
+    data: CalendarResponseData,
+  ): void {
+    const oneUptimeResponse: OneUptimeResponse = res as OneUptimeResponse;
+
+    const etag: string = Response.normalizeStrongETag(data.etag);
+
+    const expiresAt: Date = new Date(
+      Date.now() + CALENDAR_RESPONSE_MAX_AGE_SECONDS * 1000,
+    );
+
+    oneUptimeResponse.set("Content-Type", CALENDAR_RESPONSE_CONTENT_TYPE);
+    oneUptimeResponse.set(
+      "Content-Disposition",
+      `inline; filename="${CALENDAR_RESPONSE_FILE_NAME}"`,
+    );
+    oneUptimeResponse.set(
+      "Cache-Control",
+      `private, max-age=${CALENDAR_RESPONSE_MAX_AGE_SECONDS}`,
+    );
+    oneUptimeResponse.set("Expires", expiresAt.toUTCString());
+    oneUptimeResponse.set("ETag", etag);
+    oneUptimeResponse.set("Last-Modified", data.lastModified.toUTCString());
+    oneUptimeResponse.set("X-Content-Type-Options", "nosniff");
+    oneUptimeResponse.set("X-Robots-Tag", "noindex");
+
+    /*
+     * A middleware upstream of the route may already have stamped the
+     * no-cache trio (setNoCacheHeaders). Cache-Control and Expires were just
+     * overwritten; Pragma has no "do cache" value, so the only correct thing
+     * is for it not to be there.
+     */
+    oneUptimeResponse.removeHeader("Pragma");
+
+    /*
+     * Never the body: it is a roster behind a bearer token, and the audit log
+     * is not where it belongs. Enough to know what went out and how big.
+     */
+    oneUptimeResponse.logBody = {
+      contentType: CALENDAR_RESPONSE_CONTENT_TYPE,
+      bytes: Buffer.byteLength(data.body, "utf8"),
+    };
+
+    oneUptimeResponse.status(200).send(data.body);
+  }
+
+  /*
+   * Accept `abc`, `"abc"` or `W/"abc"` and return the strong, quoted form.
+   * The tag is content-derived (see getCalendarETag), so weakening it would
+   * only lose the byte-identical guarantee the client is entitled to.
+   */
+  private static normalizeStrongETag(etag: string): string {
+    let value: string = etag.trim();
+
+    if (value.startsWith("W/")) {
+      value = value.slice(2).trim();
+    }
+
+    if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+      value = value.slice(1, -1);
+    }
+
+    /*
+     * RFC 7232: an entity-tag is quoted and may not itself contain a double
+     * quote. Strip anything that would break the header rather than emit an
+     * unparseable one.
+     */
+    value = value.replace(/["\r\n]/g, "");
+
+    return `"${value}"`;
+  }
+
   public static setNoCacheHeaders(res: ExpressResponse): void {
     const oneUptimeResponse: OneUptimeResponse = res as OneUptimeResponse;
 

package/Server/Utils/StartServer.ts

@@ -3,6 +3,7 @@ import CommonAPI from "../API/Index";
 import { StatusAPIOptions } from "../API/StatusAPI";
 import {
   AppVersion,
+  EncryptionSecretWarning,
   GoogleTagManagerEnabled,
   TrustedProxyHops,
   getFrontendEnvVars,
@@ -314,6 +315,15 @@ const init: InitFunction = async (
 
   logger.info(`App Version: ${AppVersion.toString()}`);
 
+  /*
+   * Said once per process at boot, where an operator reading the startup log
+   * will see it. EnvironmentConfig computes the message but cannot log it
+   * (Logger depends on EnvironmentConfig), so the entrypoint does.
+   */
+  if (EncryptionSecretWarning) {
+    logger.warn(EncryptionSecretWarning);
+  }
+
   await Express.launchApplication(appName, port);
   LocalCache.setString("app", "name", appName);
 

package/Server/Utils/Telemetry/AppMetrics.ts

@@ -239,4 +239,55 @@ export default class AppMetrics {
 
     return this.ingestDroppedCounter;
   }
+
+  // -- On-call calendar feeds -------------------------------------------
+
+  /*
+   * The one bounded attribute these carry: which kind of feed was rendered.
+   * "user" (personal), "schedule" (one schedule, shared link) or "project"
+   * (every schedule in a project). Never the token, the user or the project
+   * id -- those are unbounded and belong on traces and logs.
+   */
+  public static readonly ON_CALL_CALENDAR_FEED_KIND_ATTRIBUTE: string =
+    "oneuptime.oncall_calendar.feed_kind";
+
+  private static onCallCalendarRenderDuration: TelemetryHistogram | null = null;
+  private static onCallCalendarRenderEvents: TelemetryHistogram | null = null;
+
+  /*
+   * Wall-clock time to materialise the shifts and serialise a feed body, on a
+   * cache miss. Rendering expands every layer of every candidate schedule
+   * across a window of up to 180 days, so this is the number that says whether
+   * the render cap and the schedule-level cache are doing their job.
+   */
+  public static getOnCallCalendarRenderDuration(): TelemetryHistogram {
+    if (!this.onCallCalendarRenderDuration) {
+      this.onCallCalendarRenderDuration = Telemetry.getHistogram({
+        name: "oncall_calendar_render_duration_ms",
+        description:
+          "Time taken to render an on-call calendar feed body on a cache miss, partitioned by feed kind.",
+        unit: "ms",
+      });
+    }
+
+    return this.onCallCalendarRenderDuration;
+  }
+
+  /*
+   * How many VEVENTs a rendered feed carried. Distribution matters more than
+   * the total: a fat tail near MAX_EVENTS means windows are being shrunk to
+   * fit and subscribers are losing the far end of their calendar.
+   */
+  public static getOnCallCalendarRenderEvents(): TelemetryHistogram {
+    if (!this.onCallCalendarRenderEvents) {
+      this.onCallCalendarRenderEvents = Telemetry.getHistogram({
+        name: "oncall_calendar_render_events",
+        description:
+          "Number of calendar events in a rendered on-call calendar feed, partitioned by feed kind.",
+        unit: "1",
+      });
+    }
+
+    return this.onCallCalendarRenderEvents;
+  }
 }

package/Tests/App/Dashboard/OnCallCalendarFeedLinks.test.tsx

@@ -0,0 +1,229 @@
+import "@testing-library/jest-dom";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  jest,
+  test,
+} from "@jest/globals";
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import React from "react";
+import getJestMockFunction, { MockFunction } from "../../MockType";
+
+/*
+ * The shared "put this in your calendar" block. What matters here is that each
+ * of the three subscribe actions points at the RIGHT form of the same link
+ * (Google wants the https URL behind its cid parameter, Apple wants webcal,
+ * Outlook wants webcal pasted), that the secret stays hidden until asked for,
+ * and that the schedule filter - when the block is narrowed to one schedule -
+ * reaches all three forms, not just the visible one.
+ */
+
+jest.mock("react-i18next", () => {
+  return {
+    useTranslation: () => {
+      return {
+        t: (key: string, options?: { defaultValue?: string }): string => {
+          return options?.defaultValue ?? key;
+        },
+      };
+    },
+  };
+});
+
+import CalendarFeedLinks from "../../../../App/FeatureSet/Dashboard/src/Components/OnCallPolicy/CalendarFeedLinks";
+import { FeedUrls } from "../../../../App/FeatureSet/Dashboard/src/Components/OnCallPolicy/CalendarFeed/CalendarFeedTypes";
+import {
+  REACHABILITY_COPY,
+  REFRESH_CADENCE_COPY,
+  buildGoogleAddUrl,
+} from "../../../../App/FeatureSet/Dashboard/src/Components/OnCallPolicy/CalendarFeed/CalendarFeedUtil";
+import ObjectID from "../../../Types/ObjectID";
+
+const HTTPS_URL: string =
+  "https://oneuptime.example.com/api/on-call-calendar/user/abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG/shifts.ics";
+const WEBCAL_URL: string = HTTPS_URL.replace("https:", "webcals:");
+
+const URLS: FeedUrls = {
+  https: HTTPS_URL,
+  webcal: WEBCAL_URL,
+  googleAdd: buildGoogleAddUrl(HTTPS_URL),
+};
+
+const SCHEDULE_ID: ObjectID = new ObjectID(
+  "33333333-3333-4333-8333-333333333333",
+);
+
+const windowOpenMock: MockFunction = getJestMockFunction();
+
+describe("CalendarFeedLinks", () => {
+  beforeEach(() => {
+    windowOpenMock.mockReset();
+    Object.defineProperty(window, "open", {
+      value: windowOpenMock,
+      writable: true,
+      configurable: true,
+    });
+  });
+
+  afterEach(() => {
+    cleanup();
+  });
+
+  test("keeps the https link hidden until the reader reveals it", () => {
+    render(<CalendarFeedLinks urls={URLS} />);
+
+    expect(screen.queryByText(HTTPS_URL)).not.toBeInTheDocument();
+    expect(screen.getByRole("hidden-text")).toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole("hidden-text"));
+
+    expect(screen.getByRole("revealed-text")).toHaveTextContent(HTTPS_URL);
+  });
+
+  test("the copy buttons carry the https and webcal forms respectively", () => {
+    render(<CalendarFeedLinks urls={URLS} />);
+
+    // Copy https link (the button next to the hidden text) and Copy webcal link.
+    expect(
+      screen.getByRole("button", { name: "Copy https link" }),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole("button", {
+        name: "Outlook: Add calendar, then Subscribe from web, then paste this link.",
+      }),
+    ).toHaveTextContent("Copy webcal link");
+  });
+
+  test("the Apple / other apps action is a real anchor to the webcal URL", () => {
+    render(<CalendarFeedLinks urls={URLS} />);
+
+    const anchor: HTMLElement = screen.getByTestId("calendar-feed-webcal");
+
+    expect(anchor.tagName).toBe("A");
+    expect(anchor).toHaveAttribute("href", WEBCAL_URL);
+    expect(anchor).toHaveTextContent("Apple / other apps");
+  });
+
+  test("the Google button opens the cid deep link in a new, isolated window", () => {
+    render(<CalendarFeedLinks urls={URLS} />);
+
+    fireEvent.click(screen.getByTestId("calendar-feed-google"));
+
+    expect(windowOpenMock).toHaveBeenCalledTimes(1);
+    expect(windowOpenMock).toHaveBeenCalledWith(
+      URLS.googleAdd,
+      "_blank",
+      "noopener,noreferrer",
+    );
+  });
+
+  test("a schedule filter narrows every form of the link, including the Google one", () => {
+    render(<CalendarFeedLinks urls={URLS} scheduleId={SCHEDULE_ID} />);
+
+    const filteredHttps: string = `${HTTPS_URL}?schedule=${SCHEDULE_ID.toString()}`;
+
+    fireEvent.click(screen.getByRole("hidden-text"));
+    expect(screen.getByRole("revealed-text")).toHaveTextContent(filteredHttps);
+
+    expect(screen.getByTestId("calendar-feed-webcal")).toHaveAttribute(
+      "href",
+      `${WEBCAL_URL}?schedule=${SCHEDULE_ID.toString()}`,
+    );
+
+    fireEvent.click(screen.getByTestId("calendar-feed-google"));
+    expect(windowOpenMock).toHaveBeenCalledWith(
+      buildGoogleAddUrl(filteredHttps),
+      "_blank",
+      "noopener,noreferrer",
+    );
+  });
+
+  test("a string schedule id works the same as an ObjectID", () => {
+    render(<CalendarFeedLinks urls={URLS} scheduleId="sched-string" />);
+
+    expect(screen.getByTestId("calendar-feed-webcal")).toHaveAttribute(
+      "href",
+      `${WEBCAL_URL}?schedule=sched-string`,
+    );
+  });
+
+  test("server warnings render only when the server sent them", () => {
+    const { rerender } = render(<CalendarFeedLinks urls={URLS} />);
+
+    expect(
+      screen.queryByTestId("calendar-feed-host-warning"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("calendar-feed-protocol-warning"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("calendar-feed-truncated-warning"),
+    ).not.toBeInTheDocument();
+
+    rerender(
+      <CalendarFeedLinks
+        urls={URLS}
+        hostWarning="Set HOST to your public hostname"
+        protocolWarning="This link will travel unencrypted"
+        lastRenderTruncated={true}
+      />,
+    );
+
+    expect(screen.getByTestId("calendar-feed-host-warning")).toHaveTextContent(
+      "Set HOST to your public hostname",
+    );
+    expect(
+      screen.getByTestId("calendar-feed-protocol-warning"),
+    ).toHaveTextContent("This link will travel unencrypted");
+    expect(
+      screen.getByTestId("calendar-feed-truncated-warning"),
+    ).toHaveTextContent(
+      "shortened because it would have exceeded the event limit",
+    );
+  });
+
+  test("the refresh alert carries the cadence copy, the reachability sentence and a docs link", () => {
+    render(<CalendarFeedLinks urls={URLS} />);
+
+    const alert: HTMLElement = screen.getByTestId(
+      "calendar-feed-refresh-alert",
+    );
+
+    expect(alert).toHaveTextContent(REFRESH_CADENCE_COPY);
+    expect(alert).toHaveTextContent(REACHABILITY_COPY);
+    expect(alert).toHaveTextContent(
+      "Google Calendar and Outlook on the web fetch this link from their servers; it must be reachable from the internet.",
+    );
+
+    const docsLink: HTMLElement = screen.getByText(
+      "Troubleshooting and per-app steps",
+    );
+    const anchor: HTMLElement | null = docsLink.closest("a");
+
+    expect(anchor).not.toBeNull();
+    expect(anchor!.getAttribute("href")).toContain("/on-call/calendar-feeds");
+    expect(anchor!.getAttribute("target")).toBe("_blank");
+  });
+
+  test("the refresh alert can be switched off when the page renders it once elsewhere", () => {
+    render(<CalendarFeedLinks urls={URLS} showRefreshAlert={false} />);
+
+    expect(
+      screen.queryByTestId("calendar-feed-refresh-alert"),
+    ).not.toBeInTheDocument();
+    // The links themselves are still there.
+    expect(screen.getByTestId("calendar-feed-webcal")).toBeInTheDocument();
+  });
+
+  test("idPrefix namespaces every test id so two blocks on one page stay distinct", () => {
+    render(<CalendarFeedLinks urls={URLS} idPrefix="shared" />);
+
+    expect(screen.getByTestId("shared-links")).toBeInTheDocument();
+    expect(screen.getByTestId("shared-google")).toBeInTheDocument();
+    expect(screen.getByTestId("shared-webcal")).toBeInTheDocument();
+    expect(screen.getByTestId("shared-refresh-alert")).toBeInTheDocument();
+    expect(screen.queryByTestId("calendar-feed-links")).not.toBeInTheDocument();
+  });
+});