@hot-updater/server 1.0.0-rc.18 → 1.0.0-rc.21

package/src/plugins/insights/provider.ts

@@ -1,704 +0,0 @@
-import { isUUIDv7 } from "@hot-updater/plugin-core";
-
-import { compareInsightsText, isInsightsMovementEvent } from "./contract";
-import type {
-  ActiveInstallationWindow,
-  InsightsBundleSelection,
-  EventHistoryRow,
-  InstallationHistoryRow,
-  InstallationRow,
-} from "./domain";
-import { InsightsBadRequestError } from "./errors";
-import { createBundleEventRow } from "./eventInput";
-import type { BundleEventFailure, BundleEventRow } from "./eventRow";
-import type {
-  InsightsBundleEventFilter,
-  InsightsEventCursor,
-  InsightsEventFilter,
-  InsightsModel,
-  InsightsScope,
-} from "./modelTypes";
-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 DAY_MS = 24 * HOUR_MS;
-
-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 "failed":
-      return { ...scope, type: "UPDATE_FAILED", 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.");
-    }
-  }
-};
-
-/** An `UPDATE_FAILED` row's failure, as the event lists show it. */
-const toFailure = (
-  failure: BundleEventFailure,
-): NonNullable<EventHistoryRow["failure"]> => ({
-  stage: failure.stage,
-  reason: failure.reason,
-  ...(failure.resource === undefined ? {} : { resource: failure.resource }),
-  ...(failure.http_status === undefined
-    ? {}
-    : { httpStatus: failure.http_status }),
-  ...(failure.transport === undefined ? {} : { transport: failure.transport }),
-  ...(failure.origin_code === undefined
-    ? {}
-    : { originCode: failure.origin_code }),
-  ...(failure.previous_process_exit === undefined
-    ? {}
-    : { previousProcessExit: failure.previous_process_exit }),
-});
-
-/** What a row's metadata adds for its type: a failure, a delivery, an exit reason. */
-const eventDetails = ({ type, metadata }: BundleEventRow) => ({
-  ...(type === "UPDATE_FAILED" && metadata.failure !== undefined
-    ? { failure: toFailure(metadata.failure) }
-    : {}),
-  ...(type === "UPDATE_DOWNLOADED" && metadata.delivery !== undefined
-    ? { delivery: metadata.delivery }
-    : {}),
-  ...(type === "UPDATE_DOWNLOADED" && metadata.patch_fallback === true
-    ? { patchFallback: true as const }
-    : {}),
-  ...(type === "RECOVERED" && metadata.previous_process_exit !== undefined
-    ? { previousProcessExit: metadata.previous_process_exit }
-    : {}),
-});
-
-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,
-  ...eventDetails(row),
-});
-
-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,
-});
-
-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.",
-        );
-      }
-      // Ending with the current hour and starting with the UTC day the
-      // window reaches into: latest-event gauges count whole UTC days and
-      // outcome counters whole hours, so the counts read only maintained
-      // rows, never raw events.
-      const now = Date.now();
-      const beforeReceivedAtMs =
-        now - (now % HOUR_MS) + (now % HOUR_MS === 0 ? 0 : HOUR_MS);
-      const reach = Math.max(0, beforeReceivedAtMs - WINDOW_MS[window]);
-      const sinceMs = reach - (reach % DAY_MS);
-      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,
-        failedReports,
-      ] = 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("failed"),
-      ]);
-      return {
-        ...scope,
-        window,
-        sinceMs,
-        beforeReceivedAtMs,
-        reportingInstallations,
-        bundle: {
-          bundleId,
-          reportingInstallations: bundleInstallations,
-          downloadedReports,
-          appliedReports,
-          recoveredReports,
-          failedReports,
-        },
-      };
-    },
-  });