@hot-updater/server 1.0.0-rc.1 → 1.0.0-rc.16

package/src/insights/provider.ts

@@ -0,0 +1,667 @@
+import {
+  compareInsightsText,
+  isInsightsMovementEvent,
+  isUUIDv7,
+  type InsightsBundleEventFilter,
+  type BundleEventRow,
+  type InsightsEventCursor,
+  type InsightsEventFilter,
+  type InsightsModel,
+} from "@hot-updater/plugin-core";
+
+import type {
+  ActiveInstallationWindow,
+  InsightsBundleSelection,
+  InsightsScope,
+  EventHistoryRow,
+  InstallationHistoryRow,
+  InstallationRow,
+} from "./domain";
+import { InsightsBadRequestError } from "./errors";
+import { createBundleEventRow } from "./eventInput";
+import type {
+  InsightsEventPageInput,
+  InsightsInstallationEventPageInput,
+  InsightsProvider,
+  InsightsUserInstallationPageInput,
+} from "./types";
+
+const DEFAULT_PAGE_LIMIT = 50;
+const MAX_PAGE_LIMIT = 100;
+const MAX_EVENT_ID_LENGTH = 1_024;
+const MAX_IDENTITY_LENGTH = 255;
+const MAX_CURSOR_LENGTH = 8 * 1_024;
+
+const HOUR_MS = 60 * 60 * 1_000;
+
+const WINDOW_MS: Record<ActiveInstallationWindow, number> = {
+  "24h": 24 * 60 * 60 * 1_000,
+  "7d": 7 * 24 * 60 * 60 * 1_000,
+  "30d": 30 * 24 * 60 * 60 * 1_000,
+};
+
+/**
+ * The longest receipt range, `[sinceMs, beforeReceivedAtMs)`, of a global or
+ * bundle event list, and the range one covers without `sinceMs`: raw events
+ * are listed inside a time range, as analytics products list them. It is a
+ * duration, so a range that ends mid-day touches 91 UTC days. Installation
+ * history is one index range and reads back to `sinceMs`.
+ */
+export const EVENT_LIST_RANGE_MS = 90 * 24 * HOUR_MS;
+
+/** A full page's last row, and the range every page of the list shares. */
+type EventCursorPayload = {
+  readonly after: InsightsEventCursor;
+  readonly beforeReceivedAtMs: number;
+  readonly sinceMs: number;
+  readonly kind: "events";
+  readonly filter: InsightsEventFilter;
+  readonly version: 2;
+};
+
+type UserInstallationCursorPayload = {
+  readonly afterInstallId: string;
+  readonly kind: "user-installations";
+  readonly userId: string;
+  readonly version: 1;
+};
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const requireString = (
+  value: unknown,
+  label: string,
+  maximumLength: number,
+): string => {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.length > maximumLength ||
+    new TextDecoder("utf-8", { ignoreBOM: true }).decode(
+      new TextEncoder().encode(value),
+    ) !== value
+  ) {
+    throw new InsightsBadRequestError(`Invalid ${label}.`);
+  }
+  return value;
+};
+
+const requireTimestamp = (value: unknown, label: string): number => {
+  if (!Number.isSafeInteger(value) || Number(value) < 0) {
+    throw new InsightsBadRequestError(`Invalid ${label}.`);
+  }
+  return Number(value);
+};
+
+const readLimit = (value: number | undefined): number => {
+  const limit = value ?? DEFAULT_PAGE_LIMIT;
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_PAGE_LIMIT) {
+    throw new InsightsBadRequestError("Invalid page limit.");
+  }
+  return limit;
+};
+
+const encodeBase64Url = (value: string): string => {
+  const bytes = new TextEncoder().encode(value);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary)
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replace(/=+$/u, "");
+};
+
+const decodeBase64Url = (value: string): string => {
+  if (value.length === 0 || value.length > MAX_CURSOR_LENGTH) {
+    throw new InsightsBadRequestError("Invalid Insights cursor.");
+  }
+  try {
+    const base64 = value.replaceAll("-", "+").replaceAll("_", "/");
+    const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, "=");
+    const binary = atob(padded);
+    const bytes = Uint8Array.from(binary, (character) =>
+      character.charCodeAt(0),
+    );
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    throw new InsightsBadRequestError("Invalid Insights cursor.");
+  }
+};
+
+const encodeCursor = (
+  value: EventCursorPayload | UserInstallationCursorPayload,
+): string => encodeBase64Url(JSON.stringify(value));
+
+const decodeCursor = (value: string): unknown => {
+  try {
+    return JSON.parse(decodeBase64Url(value));
+  } catch (error) {
+    if (error instanceof InsightsBadRequestError) throw error;
+    throw new InsightsBadRequestError("Invalid Insights cursor.");
+  }
+};
+
+const readScope = (input: InsightsScope): InsightsScope => {
+  if (input.platform !== "ios" && input.platform !== "android") {
+    throw new InsightsBadRequestError("Invalid Insights platform.");
+  }
+  return {
+    platform: input.platform,
+    channel: requireString(input.channel, "channel", MAX_EVENT_ID_LENGTH),
+  };
+};
+
+// Counts and drill-downs share the exact same raw predicate.
+const bundleFilter = (
+  input: InsightsBundleSelection,
+): InsightsBundleEventFilter => {
+  const scope = readScope(input);
+  const bundleId = requireString(
+    input.bundleId,
+    "bundle ID",
+    MAX_EVENT_ID_LENGTH,
+  );
+  switch (input.outcome) {
+    case "downloaded":
+      return { ...scope, type: "UPDATE_DOWNLOADED", toBundleId: bundleId };
+    case "applied":
+      return { ...scope, type: "UPDATE_APPLIED", toBundleId: bundleId };
+    case "recovered":
+      return { ...scope, type: "RECOVERED", fromBundleId: bundleId };
+    case "unchanged":
+      return { ...scope, type: "UNCHANGED", toBundleId: bundleId };
+    default:
+      throw new InsightsBadRequestError("Invalid Insights outcome.");
+  }
+};
+
+const sameFilter = (left: unknown, right: InsightsEventFilter): boolean => {
+  if (!isRecord(left) || left.kind !== right.kind) return false;
+  switch (right.kind) {
+    case "all":
+      return true;
+    case "installationMovement":
+      return left.installId === right.installId;
+    case "bundle":
+      return (
+        left.platform === right.platform &&
+        left.channel === right.channel &&
+        left.type === right.type &&
+        (right.type === "RECOVERED"
+          ? left.fromBundleId === right.fromBundleId
+          : left.toBundleId === right.toBundleId)
+      );
+  }
+};
+
+const readEventCursor = (
+  value: string,
+  filter: InsightsEventFilter,
+): EventCursorPayload => {
+  const cursor = decodeCursor(value);
+  // A cursor names the row it continues after. One that only held a time
+  // (`olderThanMs`) resumed below a window of days, which lists no longer do.
+  if (
+    !isRecord(cursor) ||
+    cursor.version !== 2 ||
+    cursor.kind !== "events" ||
+    !isRecord(cursor.filter) ||
+    !isRecord(cursor.after)
+  ) {
+    throw new InsightsBadRequestError("Invalid Insights cursor.");
+  }
+  if (!sameFilter(cursor.filter, filter)) {
+    throw new InsightsBadRequestError(
+      "Insights cursor does not match the requested events.",
+    );
+  }
+  if (typeof cursor.after.id !== "string" || !isUUIDv7(cursor.after.id)) {
+    throw new InsightsBadRequestError("Invalid Insights event cursor ID.");
+  }
+  return {
+    after: {
+      id: cursor.after.id,
+      receivedAtMs: requireTimestamp(cursor.after.receivedAtMs, "event cursor"),
+    },
+    beforeReceivedAtMs: requireTimestamp(
+      cursor.beforeReceivedAtMs,
+      "event cutoff",
+    ),
+    kind: "events",
+    sinceMs: requireTimestamp(cursor.sinceMs, "event start"),
+    filter,
+    version: 2,
+  };
+};
+
+const readUserInstallationCursor = (
+  value: string,
+  userId: string,
+): UserInstallationCursorPayload => {
+  const cursor = decodeCursor(value);
+  if (
+    !isRecord(cursor) ||
+    cursor.version !== 1 ||
+    cursor.kind !== "user-installations" ||
+    cursor.userId !== userId
+  ) {
+    throw new InsightsBadRequestError(
+      "Insights cursor does not match the requested user ID.",
+    );
+  }
+  return {
+    afterInstallId: requireString(
+      cursor.afterInstallId,
+      "installation cursor",
+      MAX_IDENTITY_LENGTH,
+    ),
+    kind: "user-installations",
+    userId,
+    version: 1,
+  };
+};
+
+const compareEventNewest = (
+  left: Pick<BundleEventRow, "id" | "received_at_ms">,
+  right: Pick<BundleEventRow, "id" | "received_at_ms">,
+): number =>
+  right.received_at_ms - left.received_at_ms ||
+  compareInsightsText(right.id, left.id);
+
+const isAfterEventCursor = (
+  row: BundleEventRow,
+  after: InsightsEventCursor,
+): boolean =>
+  row.received_at_ms < after.receivedAtMs ||
+  (row.received_at_ms === after.receivedAtMs &&
+    compareInsightsText(row.id, after.id) < 0);
+
+const assertEventRows = (
+  rows: readonly BundleEventRow[],
+  input: {
+    readonly after?: InsightsEventCursor;
+    readonly beforeReceivedAtMs: number;
+    readonly limit: number;
+    readonly filter: InsightsEventFilter;
+    readonly sinceMs: number;
+  },
+): void => {
+  if (rows.length > input.limit) {
+    throw new Error("Insights database returned too many event rows.");
+  }
+  for (let index = 0; index < rows.length; index += 1) {
+    const row = rows[index];
+    const previous = rows[index - 1];
+    if (
+      !row ||
+      typeof row.id !== "string" ||
+      !isUUIDv7(row.id) ||
+      !Number.isSafeInteger(row.received_at_ms) ||
+      row.received_at_ms >= input.beforeReceivedAtMs ||
+      row.received_at_ms < input.sinceMs ||
+      (previous !== undefined && compareEventNewest(previous, row) >= 0) ||
+      (input.after !== undefined && !isAfterEventCursor(row, input.after)) ||
+      (input.filter.kind === "installationMovement" &&
+        (row.install_id !== input.filter.installId ||
+          !isInsightsMovementEvent(row))) ||
+      (input.filter.kind === "bundle" &&
+        (row.platform !== input.filter.platform ||
+          row.channel !== input.filter.channel ||
+          row.type !== input.filter.type ||
+          (input.filter.type === "RECOVERED"
+            ? row.from_bundle_id !== input.filter.fromBundleId
+            : row.to_bundle_id !== input.filter.toBundleId)))
+    ) {
+      throw new Error("Insights database returned invalid event rows.");
+    }
+  }
+};
+
+const toEventHistoryRow = (row: BundleEventRow): EventHistoryRow => ({
+  appVersion: row.app_version,
+  channel: row.channel,
+  cohort: row.metadata.cohort,
+  fromBundleId: row.from_bundle_id,
+  id: row.id,
+  installId: row.install_id,
+  platform: row.platform,
+  receivedAtMs: row.received_at_ms,
+  toBundleId: row.to_bundle_id,
+  type: row.type,
+  userId: row.user_id,
+  username: row.metadata.username,
+});
+
+const toInstallationRow = (row: BundleEventRow): InstallationRow => ({
+  appVersion: row.app_version,
+  channel: row.channel,
+  cohort: row.metadata.cohort,
+  installId: row.install_id,
+  lastKnownBundleId:
+    row.type === "UPDATE_DOWNLOADED" ? row.from_bundle_id : row.to_bundle_id,
+  pendingBundleId: row.type === "UPDATE_DOWNLOADED" ? row.to_bundle_id : null,
+  pendingReleaseId: row.type === "UPDATE_DOWNLOADED" ? row.to_release_id : null,
+  latestStatus: row.type,
+  platform: row.platform,
+  receivedAtMs: row.received_at_ms,
+  userId: row.user_id,
+  username: row.metadata.username,
+});
+
+interface EventBounds {
+  readonly beforeReceivedAtMs: number;
+  readonly sinceMs: number;
+}
+
+/**
+ * Where a list without `sinceMs` starts: 90 days before its cutoff for the
+ * global and bundle lists, at the first event for installation history.
+ */
+const defaultEventStart = (
+  filter: InsightsEventFilter,
+  beforeReceivedAtMs: number,
+): number =>
+  filter.kind === "installationMovement"
+    ? 0
+    : Math.max(0, beforeReceivedAtMs - EVENT_LIST_RANGE_MS);
+
+/** Whether a cursor's row lies inside the list's range. */
+const isInsideBounds = ({ after }: EventCursorPayload, bounds: EventBounds) =>
+  after.receivedAtMs >= bounds.sinceMs &&
+  after.receivedAtMs < bounds.beforeReceivedAtMs;
+
+/** A page's range: its cursor's, which the request may repeat but not change. */
+const readEventBounds = (
+  input: InsightsEventPageInput,
+  cursor: EventCursorPayload | undefined,
+  filter: InsightsEventFilter,
+): EventBounds => {
+  const beforeReceivedAtMs =
+    cursor?.beforeReceivedAtMs ??
+    (input.beforeReceivedAtMs === undefined
+      ? Date.now()
+      : requireTimestamp(input.beforeReceivedAtMs, "event cutoff"));
+  if (
+    cursor !== undefined &&
+    input.beforeReceivedAtMs !== undefined &&
+    input.beforeReceivedAtMs !== beforeReceivedAtMs
+  ) {
+    throw new InsightsBadRequestError(
+      "Insights cursor does not match the requested event cutoff.",
+    );
+  }
+  const sinceMs =
+    cursor?.sinceMs ??
+    (input.sinceMs === undefined
+      ? defaultEventStart(filter, beforeReceivedAtMs)
+      : requireTimestamp(input.sinceMs, "event start"));
+  const bounds = { beforeReceivedAtMs, sinceMs };
+  if (
+    sinceMs > beforeReceivedAtMs ||
+    (input.sinceMs !== undefined && input.sinceMs !== sinceMs) ||
+    (cursor !== undefined && !isInsideBounds(cursor, bounds))
+  ) {
+    throw new InsightsBadRequestError(
+      "Insights cursor or range does not match the requested event start.",
+    );
+  }
+  if (
+    filter.kind !== "installationMovement" &&
+    beforeReceivedAtMs - sinceMs > EVENT_LIST_RANGE_MS
+  ) {
+    throw new InsightsBadRequestError(
+      "Insights event lists cover at most 90 days: send a sinceMs no more than 90 days before beforeReceivedAtMs.",
+    );
+  }
+  return bounds;
+};
+
+const pageEventRows = async <T extends EventHistoryRow>(
+  model: InsightsModel,
+  input: InsightsEventPageInput,
+  filter: InsightsEventFilter,
+  map: (row: BundleEventRow) => T,
+) => {
+  const limit = readLimit(input.limit);
+  const cursor =
+    input.cursor === undefined
+      ? undefined
+      : readEventCursor(input.cursor, filter);
+  const bounds = readEventBounds(input, cursor, filter);
+  const query = {
+    filter,
+    ...bounds,
+    ...(cursor === undefined ? {} : { after: cursor.after }),
+    limit,
+  };
+  const rows = await model.listEvents(query);
+  assertEventRows(rows, query);
+  const last = rows.at(-1);
+  return {
+    beforeReceivedAtMs: bounds.beforeReceivedAtMs,
+    data: rows.map(map),
+    // A short page ends the range, so only a full page carries a cursor,
+    // with the range every page shares: the last call may read an empty
+    // page, and no page ends before the range start while events remain.
+    nextCursor:
+      rows.length === limit && last
+        ? encodeCursor({
+            after: { id: last.id, receivedAtMs: last.received_at_ms },
+            ...bounds,
+            kind: "events",
+            filter,
+            version: 2,
+          })
+        : null,
+  };
+};
+
+const assertInstallationRows = (
+  rows: readonly BundleEventRow[],
+  input: {
+    readonly afterInstallId?: string;
+    readonly limit: number;
+    readonly userId: string;
+  },
+): void => {
+  if (rows.length > input.limit) {
+    throw new Error("Insights database returned too many installation rows.");
+  }
+  for (let index = 0; index < rows.length; index += 1) {
+    const row = rows[index];
+    const previous = rows[index - 1];
+    if (
+      !row ||
+      row.user_id !== input.userId ||
+      (input.afterInstallId !== undefined &&
+        compareInsightsText(row.install_id, input.afterInstallId) <= 0) ||
+      (previous !== undefined &&
+        compareInsightsText(previous.install_id, row.install_id) >= 0)
+    ) {
+      throw new Error("Insights database returned invalid installation rows.");
+    }
+  }
+};
+
+export const createInsightsProvider = (
+  model: InsightsModel,
+): InsightsProvider =>
+  Object.freeze({
+    async appendBundleEvent(input) {
+      const event = createBundleEventRow(input);
+      await model.recordEvent({
+        event,
+      });
+    },
+    listEvents(input) {
+      const filter: InsightsEventFilter =
+        input.bundle === undefined
+          ? { kind: "all" }
+          : { kind: "bundle", ...bundleFilter(input.bundle) };
+      return pageEventRows(model, input, filter, toEventHistoryRow);
+    },
+    async listInstallationEvents(input: InsightsInstallationEventPageInput) {
+      if ("bundle" in input && input.bundle !== undefined) {
+        throw new InsightsBadRequestError(
+          "Installation movement queries cannot include a bundle filter.",
+        );
+      }
+      const installId = requireString(
+        input.installId,
+        "install ID",
+        MAX_IDENTITY_LENGTH,
+      );
+      return pageEventRows(
+        model,
+        input,
+        { kind: "installationMovement", installId },
+        (row) => toEventHistoryRow(row) as InstallationHistoryRow,
+      );
+    },
+    async getInstallation({ installId }) {
+      const normalizedInstallId = requireString(
+        installId,
+        "install ID",
+        MAX_IDENTITY_LENGTH,
+      );
+      const rows = await model.findLatestEvents({
+        installId: normalizedInstallId,
+      });
+      const row = rows[0] ?? null;
+      if (
+        rows.length > 1 ||
+        (row !== null && row.install_id !== normalizedInstallId)
+      ) {
+        throw new Error("Insights database returned an invalid installation.");
+      }
+      return row === null ? null : toInstallationRow(row);
+    },
+    async pageInstallationsByCurrentUserId(
+      input: InsightsUserInstallationPageInput,
+    ) {
+      const userId = requireString(
+        input.userId,
+        "user ID",
+        MAX_IDENTITY_LENGTH,
+      );
+      const limit = readLimit(input.limit);
+      const cursor =
+        input.cursor === undefined
+          ? undefined
+          : readUserInstallationCursor(input.cursor, userId);
+      const databaseInput = {
+        userId,
+        ...(cursor === undefined
+          ? {}
+          : { afterInstallId: cursor.afterInstallId }),
+        limit,
+      };
+      const rows = await model.findLatestEvents(databaseInput);
+      assertInstallationRows(rows, databaseInput);
+      const last = rows.at(-1);
+      return {
+        data: rows.map(toInstallationRow),
+        nextCursor:
+          rows.length === limit && last
+            ? encodeCursor({
+                afterInstallId: last.install_id,
+                kind: "user-installations",
+                userId,
+                version: 1,
+              })
+            : null,
+      };
+    },
+    async getReportingOverview(input) {
+      const scope = readScope(input);
+      const { window } = input;
+      if (!Object.hasOwn(WINDOW_MS, window)) {
+        throw new InsightsBadRequestError(
+          "Invalid reporting installation window.",
+        );
+      }
+      // Whole hours, ending with the current one: the counts read only the
+      // maintained hour and day rows, never raw events.
+      const now = Date.now();
+      const beforeReceivedAtMs =
+        now - (now % HOUR_MS) + (now % HOUR_MS === 0 ? 0 : HOUR_MS);
+      const sinceMs = Math.max(0, beforeReceivedAtMs - WINDOW_MS[window]);
+      const measure = async (count: Promise<number>) => {
+        const value = await count;
+        if (!Number.isSafeInteger(value) || value < 0) {
+          throw new Error("Insights database returned an invalid count.");
+        }
+        return { count: value, measuredAtMs: Date.now() };
+      };
+      const bundleId =
+        input.bundleId === undefined
+          ? undefined
+          : requireString(input.bundleId, "bundle ID", MAX_EVENT_ID_LENGTH);
+      const reporting = measure(model.countLatestEvents({ ...scope, sinceMs }));
+      if (bundleId === undefined) {
+        return {
+          ...scope,
+          window,
+          sinceMs,
+          beforeReceivedAtMs,
+          reportingInstallations: await reporting,
+        };
+      }
+      const countOutcome = (outcome: InsightsBundleSelection["outcome"]) =>
+        measure(
+          model.countEvents({
+            filter: bundleFilter({ ...scope, bundleId, outcome }),
+            sinceMs,
+            beforeReceivedAtMs,
+          }),
+        );
+      const [
+        reportingInstallations,
+        bundleInstallations,
+        downloadedReports,
+        appliedReports,
+        recoveredReports,
+        unchangedReports,
+      ] = await Promise.all([
+        reporting,
+        measure(
+          model.countLatestEvents({
+            ...scope,
+            sinceMs,
+            bundle: [
+              {
+                field: "from_bundle_id",
+                value: bundleId,
+                types: ["UPDATE_DOWNLOADED"],
+              },
+              {
+                field: "to_bundle_id",
+                value: bundleId,
+                types: ["UNCHANGED", "UPDATE_APPLIED", "RECOVERED"],
+              },
+            ],
+          }),
+        ),
+        countOutcome("downloaded"),
+        countOutcome("applied"),
+        countOutcome("recovered"),
+        countOutcome("unchanged"),
+      ]);
+      return {
+        ...scope,
+        window,
+        sinceMs,
+        beforeReceivedAtMs,
+        reportingInstallations,
+        bundle: {
+          bundleId,
+          reportingInstallations: bundleInstallations,
+          downloadedReports,
+          appliedReports,
+          recoveredReports,
+          unchangedReports,
+        },
+      };
+    },
+  });