@hot-updater/server 0.36.6 → 1.0.0-rc.0

package/src/analytics/bounded/provider.spec.ts

@@ -0,0 +1,219 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { AnalyticsScanLimitExceededError } from "../errors";
+import type {
+  AnalyticsPersistence,
+  AnalyticsScanInput,
+  BundleEventPersistenceRow,
+} from "../persistence";
+import { createAnalyticsProvider } from "./provider";
+import { getWindowRange } from "./scan";
+
+const eventRow = (
+  id: string,
+  receivedAtMs: number,
+  installId = `install-${id}`,
+): BundleEventPersistenceRow => ({
+  id,
+  type: "UPDATE_APPLIED",
+  install_id: installId,
+  user_id: null,
+  username: null,
+  from_release_id: null,
+  from_bundle_id: "old",
+  to_release_id: null,
+  to_bundle_id: "new",
+  platform: "ios",
+  app_version: "1.0.0",
+  channel: "production",
+  cohort: "default",
+  update_strategy: "fingerprint",
+  fingerprint_hash: null,
+  sdk_version: null,
+  received_at_ms: receivedAtMs,
+});
+
+const compareRows = (
+  left: BundleEventPersistenceRow,
+  right: BundleEventPersistenceRow,
+): number =>
+  left.received_at_ms - right.received_at_ms || left.id.localeCompare(right.id);
+
+const inMemoryPersistence = (
+  initialRows: readonly BundleEventPersistenceRow[],
+  maximumPageSize = Number.MAX_SAFE_INTEGER,
+): AnalyticsPersistence => {
+  const rows = [...initialRows];
+  return {
+    async append(row) {
+      rows.push(row);
+    },
+    async scan(input: AnalyticsScanInput) {
+      return rows
+        .filter((row) => row.received_at_ms < input.beforeReceivedAtMs)
+        .filter(
+          (row) =>
+            input.after === undefined ||
+            row.received_at_ms > input.after.receivedAtMs ||
+            (row.received_at_ms === input.after.receivedAtMs &&
+              row.id > input.after.id),
+        )
+        .toSorted(compareRows)
+        .slice(0, Math.min(input.limit, maximumPageSize));
+    },
+  };
+};
+
+describe("createAnalyticsProvider", () => {
+  it("starts windowed analytics scans at the storage lower boundary", async () => {
+    // Given
+    const now = Date.UTC(2026, 1, 2, 12);
+    vi.spyOn(Date, "now").mockReturnValue(now);
+    const scan = vi.fn<AnalyticsPersistence["scan"]>().mockResolvedValue([]);
+    const provider = createAnalyticsProvider({
+      async append() {},
+      scan,
+    });
+
+    // When
+    await provider.getBundleEventAnalytics("new", "24h", 20, 0);
+
+    // Then
+    expect(scan).toHaveBeenCalledWith(
+      expect.objectContaining({
+        after: {
+          id: "00000000-0000-0000-0000-000000000000",
+          receivedAtMs: getWindowRange("24h", now).rangeStart,
+        },
+      }),
+    );
+    vi.restoreAllMocks();
+  });
+  it("counts distinct installations across cursor pages", async () => {
+    const rows = Array.from({ length: 1_001 }, (_, index) =>
+      eventRow(index.toString().padStart(4, "0"), 1_000, `install-${index}`),
+    );
+    const provider = createAnalyticsProvider(inMemoryPersistence(rows));
+
+    await expect(provider.getBundleEventSummary("new")).resolves.toEqual({
+      installed: 1_001,
+      recovered: 0,
+    });
+  });
+
+  it("continues scanning when persistence caps pages below the requested limit", async () => {
+    const rows = Array.from({ length: 101 }, (_, index) =>
+      eventRow(index.toString().padStart(4, "0"), 1_000, `install-${index}`),
+    );
+    const provider = createAnalyticsProvider(inMemoryPersistence(rows, 17));
+
+    await expect(provider.getBundleEventSummary("new")).resolves.toEqual({
+      installed: 101,
+      recovered: 0,
+    });
+  });
+
+  it("collects distinct 30-day movement for multiple Bundles in one scan", async () => {
+    const now = Date.UTC(2026, 7, 18, 12);
+    vi.spyOn(Date, "now").mockReturnValue(now);
+    const applied = eventRow("applied", now - 1_000, "install-applied");
+    const duplicateApplied = eventRow(
+      "applied-again",
+      now - 900,
+      "install-applied",
+    );
+    const recovered = {
+      ...eventRow("recovered", now - 800, "install-recovered"),
+      type: "RECOVERED" as const,
+      from_bundle_id: "new",
+      to_bundle_id: "fallback",
+      update_strategy: "fingerprint" as const,
+    } satisfies BundleEventPersistenceRow;
+    const other = {
+      ...eventRow("other", now - 700, "install-other"),
+      to_bundle_id: "other",
+    };
+    const outsideWindow = eventRow(
+      "outside-window",
+      now - 31 * 24 * 60 * 60 * 1_000,
+      "install-old",
+    );
+    const persistence = inMemoryPersistence([
+      outsideWindow,
+      applied,
+      duplicateApplied,
+      recovered,
+      other,
+    ]);
+    const scan = vi.spyOn(persistence, "scan");
+    const provider = createAnalyticsProvider(persistence);
+
+    await expect(
+      provider.getBundleEventSummaries(["new", "other", "missing"], "30d"),
+    ).resolves.toEqual([
+      { bundleId: "new", installed: 1, recovered: 1 },
+      { bundleId: "other", installed: 1, recovered: 0 },
+      { bundleId: "missing", installed: 0, recovered: 0 },
+    ]);
+    expect(scan).toHaveBeenCalledTimes(2);
+    vi.restoreAllMocks();
+  });
+
+  it("counts an installation whose current bundle is reported by UNCHANGED", async () => {
+    const unchanged: BundleEventPersistenceRow = {
+      ...eventRow("unchanged", 1, "install-unchanged"),
+      type: "UNCHANGED",
+      from_bundle_id: null,
+      update_strategy: null,
+    };
+    const provider = createAnalyticsProvider(inMemoryPersistence([unchanged]));
+
+    await expect(provider.getBundleEventOverview()).resolves.toEqual({
+      trackedInstallations: 1,
+      bundles: [{ bundleId: "new", installations: 1 }],
+    });
+  });
+
+  it.each([
+    [eventRow("same", 1), eventRow("same", 2)],
+    [eventRow("later", 2), eventRow("earlier", 1)],
+  ])(
+    "rejects duplicate ids and rows outside strict cursor order",
+    async (...rows) => {
+      let delivered = false;
+      const provider = createAnalyticsProvider({
+        async append() {},
+        async scan() {
+          if (delivered) return [];
+          delivered = true;
+          return rows;
+        },
+      });
+
+      await expect(provider.getBundleEventSummary("new")).rejects.toMatchObject(
+        {
+          name: "AnalyticsPersistenceOrderError",
+        },
+      );
+    },
+  );
+
+  it("fails instead of returning partial analytics beyond 50,000 rows", async () => {
+    const persistence: AnalyticsPersistence = {
+      async append() {},
+      async scan(input) {
+        const start =
+          input.after === undefined ? 0 : Number(input.after.id) + 1;
+        return Array.from({ length: input.limit }, (_, index) => {
+          const id = start + index;
+          return eventRow(String(id), id);
+        });
+      },
+    };
+    const provider = createAnalyticsProvider(persistence);
+
+    await expect(provider.getBundleEventSummary("new")).rejects.toBeInstanceOf(
+      AnalyticsScanLimitExceededError,
+    );
+  });
+});

package/src/analytics/bounded/provider.ts

@@ -0,0 +1,229 @@
+import type {
+  BundleEventAnalyticsWindow,
+  InstallationHistoryRow,
+} from "../domain";
+import type {
+  AnalyticsPersistence,
+  BundleEventPersistenceRow,
+} from "../persistence";
+import type { AnalyticsProvider } from "../types";
+import { collectActiveInstallationOverview } from "./activeOverview";
+import { searchEventInstallations } from "./installationSearch";
+import { createBundleEventRow } from "./persistence";
+import {
+  ANALYTICS_SCAN_MAX_ROWS,
+  collectEventActivity,
+  compareCodePoints,
+  compareEventNewest,
+  materializeActiveRows,
+  materializeEventRows,
+  materializeRowsForWindow,
+} from "./scan";
+
+type TransitionEventRow = BundleEventPersistenceRow & {
+  readonly type: "UPDATE_APPLIED" | "RECOVERED";
+};
+
+const isTransitionEventRow = (
+  row: BundleEventPersistenceRow,
+): row is TransitionEventRow =>
+  row.type === "UPDATE_APPLIED" || row.type === "RECOVERED";
+
+const toHistoryRow = (row: TransitionEventRow): InstallationHistoryRow => ({
+  id: row.id,
+  type: row.type,
+  fromBundleId: row.from_bundle_id,
+  toBundleId: row.to_bundle_id,
+  username: row.username,
+  userId: row.user_id,
+  platform: row.platform,
+  appVersion: row.app_version,
+  channel: row.channel,
+  cohort: row.cohort,
+  receivedAtMs: row.received_at_ms,
+});
+
+const isInstalledForBundle = (
+  row: TransitionEventRow,
+  bundleId: string,
+): boolean => row.type === "UPDATE_APPLIED" && row.to_bundle_id === bundleId;
+
+const isRecoveredFromBundle = (
+  row: TransitionEventRow,
+  bundleId: string,
+): boolean => row.type === "RECOVERED" && row.from_bundle_id === bundleId;
+
+const countDistinctInstallations = (
+  rows: readonly BundleEventPersistenceRow[],
+): number => new Set(rows.map(({ install_id }) => install_id)).size;
+
+const getAnalyticsResult = async (
+  persistence: AnalyticsPersistence,
+  bundleId: string,
+  window: BundleEventAnalyticsWindow,
+  limit: number,
+  offset: number,
+) => {
+  const scope = { persistence, cutoffMs: Date.now() };
+  const rows = (await materializeRowsForWindow(scope, window)).filter(
+    isTransitionEventRow,
+  );
+  const installedRows = rows.filter((row) =>
+    isInstalledForBundle(row, bundleId),
+  );
+  const recoveredRows = rows.filter((row) =>
+    isRecoveredFromBundle(row, bundleId),
+  );
+  const installed = collectEventActivity({
+    rows: installedRows,
+    window,
+    cutoffMs: scope.cutoffMs,
+  });
+  const recovered = collectEventActivity({
+    rows: recoveredRows,
+    window,
+    cutoffMs: scope.cutoffMs,
+  });
+  const recentRows = [...installedRows, ...recoveredRows].sort(
+    compareEventNewest,
+  );
+  return {
+    summary: { installed: installed.summary, recovered: recovered.summary },
+    series: { installed: installed.series, recovered: recovered.series },
+    cohorts: { installed: installed.cohorts, recovered: recovered.cohorts },
+    recentEvents: {
+      data: recentRows.slice(offset, offset + limit).map(toHistoryRow),
+      pagination: { total: recentRows.length, limit, offset },
+    },
+  };
+};
+
+const getAnalyticsSummaries = async (
+  persistence: AnalyticsPersistence,
+  bundleIds: readonly string[],
+  window: BundleEventAnalyticsWindow,
+) => {
+  const normalizedBundleIds = [...new Set(bundleIds)];
+  if (normalizedBundleIds.length === 0) return [];
+
+  const requestedBundleIds = new Set(normalizedBundleIds);
+  const installedByBundleId = new Map<string, Set<string>>();
+  const recoveredByBundleId = new Map<string, Set<string>>();
+  const rows = (
+    await materializeRowsForWindow(
+      { persistence, cutoffMs: Date.now() },
+      window,
+    )
+  ).filter(isTransitionEventRow);
+
+  for (const row of rows) {
+    const bundleId =
+      row.type === "UPDATE_APPLIED" ? row.to_bundle_id : row.from_bundle_id;
+    if (!requestedBundleIds.has(bundleId)) continue;
+
+    const counts =
+      row.type === "UPDATE_APPLIED" ? installedByBundleId : recoveredByBundleId;
+    const installIds = counts.get(bundleId) ?? new Set<string>();
+    installIds.add(row.install_id);
+    counts.set(bundleId, installIds);
+  }
+
+  return normalizedBundleIds.map((bundleId) => ({
+    bundleId,
+    installed: installedByBundleId.get(bundleId)?.size ?? 0,
+    recovered: recoveredByBundleId.get(bundleId)?.size ?? 0,
+  }));
+};
+
+export const createAnalyticsProvider = (
+  persistence: AnalyticsPersistence,
+): AnalyticsProvider =>
+  Object.freeze({
+    mode: "bounded",
+    maxMatchingRows: ANALYTICS_SCAN_MAX_ROWS,
+    async appendBundleEvent(input) {
+      await persistence.append(createBundleEventRow(input));
+    },
+    async getBundleEventSummary(bundleId) {
+      const rows = (
+        await materializeEventRows({ persistence, cutoffMs: Date.now() })
+      ).filter(isTransitionEventRow);
+      return {
+        installed: countDistinctInstallations(
+          rows.filter((row) => isInstalledForBundle(row, bundleId)),
+        ),
+        recovered: countDistinctInstallations(
+          rows.filter((row) => isRecoveredFromBundle(row, bundleId)),
+        ),
+      };
+    },
+    getBundleEventSummaries(bundleIds, window) {
+      return getAnalyticsSummaries(persistence, bundleIds, window);
+    },
+    getBundleEventAnalytics(bundleId, window, limit, offset) {
+      return getAnalyticsResult(persistence, bundleId, window, limit, offset);
+    },
+    async getBundleEventOverview() {
+      const rows = await materializeEventRows({
+        persistence,
+        cutoffMs: Date.now(),
+      });
+      const latestByInstall = new Map<string, BundleEventPersistenceRow>();
+      for (const row of rows) {
+        const current = latestByInstall.get(row.install_id);
+        if (current === undefined || compareEventNewest(row, current) < 0) {
+          latestByInstall.set(row.install_id, row);
+        }
+      }
+      const counts = new Map<string, number>();
+      for (const row of latestByInstall.values()) {
+        counts.set(row.to_bundle_id, (counts.get(row.to_bundle_id) ?? 0) + 1);
+      }
+      return {
+        trackedInstallations: latestByInstall.size,
+        bundles: [...counts]
+          .map(([bundleId, installations]) => ({ bundleId, installations }))
+          .sort(
+            (left, right) =>
+              right.installations - left.installations ||
+              compareCodePoints(left.bundleId, right.bundleId),
+          ),
+      };
+    },
+    async getActiveInstallationOverview(input) {
+      const asOfMs = Date.now();
+      const rows = await materializeActiveRows(
+        { persistence, cutoffMs: asOfMs },
+        input.window,
+      );
+      return collectActiveInstallationOverview({
+        rows,
+        asOfMs,
+        window: input.window,
+        ...(input.userId === undefined ? {} : { userId: input.userId }),
+      });
+    },
+    async searchInstallations(query, limit, offset) {
+      const rows = await materializeEventRows({
+        persistence,
+        cutoffMs: Date.now(),
+      });
+      return searchEventInstallations({ rows, query, limit, offset });
+    },
+    async getInstallationHistory(installId, limit, offset) {
+      const rows = await materializeEventRows({
+        persistence,
+        cutoffMs: Date.now(),
+      });
+      const ordered = rows
+        .filter(
+          (row): row is TransitionEventRow =>
+            row.install_id === installId && isTransitionEventRow(row),
+        )
+        .toSorted(compareEventNewest);
+      return {
+        data: ordered.slice(offset, offset + limit).map(toHistoryRow),
+        pagination: { total: ordered.length, limit, offset },
+      };
+    },
+  } satisfies AnalyticsProvider);

package/src/analytics/bounded/scan.ts

@@ -0,0 +1,235 @@
+import type {
+  ActiveInstallationWindow,
+  BundleEventAnalyticsWindow,
+} from "../domain";
+import { AnalyticsScanLimitExceededError } from "../errors";
+import type {
+  AnalyticsPersistence,
+  BundleEventPersistenceRow,
+} from "../persistence";
+import {
+  ACTIVE_BUNDLE_EVENT_TYPES,
+  getActiveWindowDefinition,
+} from "./activeOverview";
+
+export const ANALYTICS_SCAN_MAX_ROWS = 50_000;
+export const ANALYTICS_MATERIALIZATION_LIMIT = ANALYTICS_SCAN_MAX_ROWS + 1;
+export const ANALYTICS_SCAN_PAGE_SIZE = 1_000;
+const ANALYTICS_LOWER_BOUND_ID = "00000000-0000-0000-0000-000000000000";
+
+export type AnalyticsScanScope = {
+  readonly persistence: AnalyticsPersistence;
+  readonly cutoffMs: number;
+  readonly lowerBoundMs?: number;
+};
+
+type EventActivityRequest = {
+  readonly rows: readonly BundleEventPersistenceRow[];
+  readonly window: BundleEventAnalyticsWindow;
+  readonly cutoffMs: number;
+};
+
+export const compareCodePoints = (left: string, right: string): number => {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+};
+
+export const compareEventNewest = (
+  left: BundleEventPersistenceRow,
+  right: BundleEventPersistenceRow,
+): number =>
+  right.received_at_ms - left.received_at_ms ||
+  compareCodePoints(right.id, left.id);
+
+const compareEventOldest = (
+  left: { readonly received_at_ms: number; readonly id: string },
+  right: { readonly received_at_ms: number; readonly id: string },
+): number =>
+  left.received_at_ms - right.received_at_ms ||
+  compareCodePoints(left.id, right.id);
+
+export const materializeEventRows = async (
+  scope: AnalyticsScanScope,
+): Promise<readonly BundleEventPersistenceRow[]> => {
+  const rows: BundleEventPersistenceRow[] = [];
+  const seenIds = new Set<string>();
+  let after =
+    scope.lowerBoundMs === undefined
+      ? undefined
+      : { receivedAtMs: scope.lowerBoundMs, id: ANALYTICS_LOWER_BOUND_ID };
+  while (rows.length < ANALYTICS_MATERIALIZATION_LIMIT) {
+    const limit = Math.min(
+      ANALYTICS_SCAN_PAGE_SIZE,
+      ANALYTICS_MATERIALIZATION_LIMIT - rows.length,
+    );
+    const page = await scope.persistence.scan({
+      beforeReceivedAtMs: scope.cutoffMs,
+      ...(after === undefined ? {} : { after }),
+      limit,
+    });
+    if (page.length === 0) break;
+    if (page.length > limit) throw new AnalyticsPersistenceOrderError();
+    let previous =
+      after === undefined
+        ? undefined
+        : { received_at_ms: after.receivedAtMs, id: after.id };
+    for (const row of page) {
+      if (
+        row.received_at_ms >= scope.cutoffMs ||
+        (previous !== undefined && compareEventOldest(previous, row) >= 0) ||
+        seenIds.has(row.id)
+      ) {
+        throw new AnalyticsPersistenceOrderError();
+      }
+      seenIds.add(row.id);
+      rows.push(row);
+      previous = row;
+    }
+    const last = page.at(-1);
+    if (last !== undefined) {
+      after = { receivedAtMs: last.received_at_ms, id: last.id };
+    }
+    if (rows.length > ANALYTICS_SCAN_MAX_ROWS) {
+      throw new AnalyticsScanLimitExceededError(ANALYTICS_SCAN_MAX_ROWS);
+    }
+  }
+  return rows;
+};
+
+export class AnalyticsPersistenceOrderError extends Error {
+  readonly name = "AnalyticsPersistenceOrderError";
+
+  constructor() {
+    super("Analytics persistence did not advance its scan cursor.");
+  }
+}
+
+export const materializeActiveRows = async (
+  scope: AnalyticsScanScope,
+  window: ActiveInstallationWindow,
+): Promise<readonly BundleEventPersistenceRow[]> => {
+  const definition = getActiveWindowDefinition(window);
+  const durationMs = definition.bucketCount * definition.bucketSizeMs;
+  return (
+    await materializeEventRows({
+      ...scope,
+      lowerBoundMs: scope.cutoffMs - durationMs,
+    })
+  ).filter(
+    (row) =>
+      row.received_at_ms >= scope.cutoffMs - durationMs &&
+      ACTIVE_BUNDLE_EVENT_TYPES.includes(row.type),
+  );
+};
+
+const startOfUtcHour = (value: number): number => {
+  const date = new Date(value);
+  return Date.UTC(
+    date.getUTCFullYear(),
+    date.getUTCMonth(),
+    date.getUTCDate(),
+    date.getUTCHours(),
+  );
+};
+
+const startOfUtcDay = (value: number): number => {
+  const date = new Date(value);
+  return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate());
+};
+
+export const getWindowRange = (
+  window: Exclude<BundleEventAnalyticsWindow, "all">,
+  now: number,
+): { readonly sizeMs: number; readonly rangeStart: number } => {
+  if (window === "24h") {
+    return {
+      sizeMs: 60 * 60 * 1_000,
+      rangeStart: startOfUtcHour(now) - 23 * 60 * 60 * 1_000,
+    };
+  }
+  const days = window === "7d" ? 7 : 30;
+  return {
+    sizeMs: 24 * 60 * 60 * 1_000,
+    rangeStart: startOfUtcDay(now) - (days - 1) * 24 * 60 * 60 * 1_000,
+  };
+};
+
+export const materializeRowsForWindow = async (
+  scope: AnalyticsScanScope,
+  window: BundleEventAnalyticsWindow,
+): Promise<readonly BundleEventPersistenceRow[]> => {
+  if (window === "all") return materializeEventRows(scope);
+  const range = getWindowRange(window, scope.cutoffMs);
+  const rows = await materializeEventRows({
+    ...scope,
+    lowerBoundMs: range.rangeStart,
+  });
+  return rows.filter(
+    ({ received_at_ms }) => received_at_ms >= range.rangeStart,
+  );
+};
+
+const bucketStart = (receivedAtMs: number, sizeMs: number): number =>
+  sizeMs === 60 * 60 * 1_000
+    ? startOfUtcHour(receivedAtMs)
+    : startOfUtcDay(receivedAtMs);
+
+const createSeries = (request: EventActivityRequest) => {
+  const range =
+    request.window === "all"
+      ? undefined
+      : getWindowRange(request.window, request.cutoffMs);
+  const sizeMs = range?.sizeMs ?? 24 * 60 * 60 * 1_000;
+  const installIdsByBucket = new Map<number, Set<string>>();
+  let oldestMs = request.cutoffMs;
+  for (const row of request.rows) {
+    oldestMs = Math.min(oldestMs, row.received_at_ms);
+    const start = bucketStart(row.received_at_ms, sizeMs);
+    const installIds = installIdsByBucket.get(start) ?? new Set<string>();
+    installIds.add(row.install_id);
+    installIdsByBucket.set(start, installIds);
+  }
+  const first = range?.rangeStart ?? startOfUtcDay(oldestMs);
+  const last = bucketStart(request.cutoffMs, sizeMs);
+  return Array.from(
+    { length: Math.floor((last - first) / sizeMs) + 1 },
+    (_, index) => {
+      const start = first + index * sizeMs;
+      return {
+        bucketStartMs: start,
+        value: installIdsByBucket.get(start)?.size ?? 0,
+      };
+    },
+  );
+};
+
+export const collectEventActivity = (request: EventActivityRequest) => {
+  const range =
+    request.window === "all"
+      ? undefined
+      : getWindowRange(request.window, request.cutoffMs);
+  const rows =
+    range === undefined
+      ? request.rows
+      : request.rows.filter(
+          ({ received_at_ms }) =>
+            received_at_ms >= range.rangeStart &&
+            received_at_ms < request.cutoffMs,
+        );
+  const installs = new Set<string>();
+  const installsByCohort = new Map<string, Set<string>>();
+  for (const row of rows) {
+    installs.add(row.install_id);
+    const cohort = installsByCohort.get(row.cohort) ?? new Set<string>();
+    cohort.add(row.install_id);
+    installsByCohort.set(row.cohort, cohort);
+  }
+  return {
+    summary: installs.size,
+    cohorts: [...installsByCohort]
+      .sort(([left], [right]) => compareCodePoints(left, right))
+      .map(([cohort, installIds]) => ({ cohort, value: installIds.size })),
+    series: createSeries({ ...request, rows }),
+  };
+};