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

package/src/insights/bounded/activeOverview.ts

@@ -0,0 +1,148 @@
+import type {
+  ActiveInstallationOverview,
+  ActiveInstallationWindow,
+} from "../domain";
+import type { BundleEventPersistenceRow } from "../persistence";
+
+const HOUR_MS = 60 * 60 * 1_000;
+const DAY_MS = 24 * HOUR_MS;
+
+export const ACTIVE_BUNDLE_EVENT_TYPES = [
+  "UPDATE_APPLIED",
+  "RECOVERED",
+  "RELEASE_ADOPTED",
+  "UNCHANGED",
+] as const;
+
+const activeWindowDefinitions = {
+  "24h": { bucketCount: 24, bucketSizeMs: HOUR_MS },
+  "7d": { bucketCount: 7, bucketSizeMs: DAY_MS },
+  "30d": { bucketCount: 30, bucketSizeMs: DAY_MS },
+} as const satisfies Record<
+  ActiveInstallationWindow,
+  { readonly bucketCount: number; readonly bucketSizeMs: number }
+>;
+
+type ActiveWindowDefinition =
+  (typeof activeWindowDefinitions)[ActiveInstallationWindow];
+
+export function getActiveWindowDefinition(
+  window: ActiveInstallationWindow,
+): ActiveWindowDefinition {
+  return activeWindowDefinitions[window];
+}
+
+type ActiveOverviewRequest = {
+  readonly rows: readonly BundleEventPersistenceRow[];
+  readonly asOfMs: number;
+  readonly window: ActiveInstallationWindow;
+  readonly userId?: string;
+};
+
+function compareCodePoints(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
+function isNewer(
+  candidate: BundleEventPersistenceRow,
+  current: BundleEventPersistenceRow,
+): boolean {
+  return (
+    candidate.received_at_ms > current.received_at_ms ||
+    (candidate.received_at_ms === current.received_at_ms &&
+      compareCodePoints(candidate.id, current.id) > 0)
+  );
+}
+
+export function collectActiveInstallationOverview(
+  request: ActiveOverviewRequest,
+): ActiveInstallationOverview {
+  const definition = getActiveWindowDefinition(request.window);
+  const windowStartMs =
+    request.asOfMs - definition.bucketCount * definition.bucketSizeMs;
+  const rows = request.rows.filter(
+    (row) =>
+      row.received_at_ms >= windowStartMs &&
+      row.received_at_ms < request.asOfMs,
+  );
+  const latestByInstall = new Map<string, BundleEventPersistenceRow>();
+  for (const row of rows) {
+    const current = latestByInstall.get(row.install_id);
+    if (current === undefined || isNewer(row, current)) {
+      latestByInstall.set(row.install_id, row);
+    }
+  }
+  const selectedRows = [...latestByInstall.values()].filter(
+    (row) => request.userId === undefined || row.user_id === request.userId,
+  );
+  const selectedInstallIds = new Set(selectedRows.map((row) => row.install_id));
+  const bundleCounts = new Map<string, number>();
+  for (const row of selectedRows) {
+    bundleCounts.set(
+      row.to_bundle_id,
+      (bundleCounts.get(row.to_bundle_id) ?? 0) + 1,
+    );
+  }
+  const latestByBucket = Array.from(
+    { length: definition.bucketCount },
+    () => new Map<string, BundleEventPersistenceRow>(),
+  );
+  for (const row of rows) {
+    if (!selectedInstallIds.has(row.install_id)) continue;
+    const bucketIndex = Math.floor(
+      (row.received_at_ms - windowStartMs) / definition.bucketSizeMs,
+    );
+    const bucket = latestByBucket[bucketIndex];
+    if (bucket === undefined) continue;
+    const current = bucket.get(row.install_id);
+    if (current === undefined || isNewer(row, current)) {
+      bucket.set(row.install_id, row);
+    }
+  }
+  const bundleCountsByBucket = latestByBucket.map((bucket) => {
+    const counts = new Map<string, number>();
+    for (const row of bucket.values()) {
+      counts.set(row.to_bundle_id, (counts.get(row.to_bundle_id) ?? 0) + 1);
+    }
+    return counts;
+  });
+  const bundleObservationTotals = new Map<string, number>();
+  for (const counts of bundleCountsByBucket) {
+    for (const [bundleId, count] of counts) {
+      bundleObservationTotals.set(
+        bundleId,
+        (bundleObservationTotals.get(bundleId) ?? 0) + count,
+      );
+    }
+  }
+  return {
+    asOfMs: request.asOfMs,
+    window: request.window,
+    activeInstallations: selectedInstallIds.size,
+    series: latestByBucket.map((bucket, index) => ({
+      bucketStartMs: windowStartMs + index * definition.bucketSizeMs,
+      value: bucket.size,
+    })),
+    bundleSeries: [...bundleObservationTotals]
+      .sort(
+        ([leftId, leftTotal], [rightId, rightTotal]) =>
+          rightTotal - leftTotal || compareCodePoints(leftId, rightId),
+      )
+      .map(([bundleId]) => ({
+        bundleId,
+        series: bundleCountsByBucket.map((counts, index) => ({
+          bucketStartMs: windowStartMs + index * definition.bucketSizeMs,
+          value: counts.get(bundleId) ?? 0,
+        })),
+      })),
+    bundles: [...bundleCounts]
+      .map(([bundleId, installations]) => ({ bundleId, installations }))
+      .sort(
+        (left, right) =>
+          right.installations - left.installations ||
+          compareCodePoints(left.bundleId, right.bundleId),
+      ),
+  };
+}

package/src/insights/bounded/installationSearch.spec.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it } from "vitest";
+
+import type { BundleEventPersistenceRow } from "../persistence";
+import { searchEventInstallations } from "./installationSearch";
+
+type UpdateAppliedRow = BundleEventPersistenceRow & {
+  readonly type: "UPDATE_APPLIED";
+};
+
+function eventRow(overrides: Partial<UpdateAppliedRow> = {}): UpdateAppliedRow {
+  return {
+    id: "event-1",
+    type: "UPDATE_APPLIED",
+    install_id: "install-1",
+    user_id: "user-1",
+    username: "alice",
+    from_release_id: null,
+    from_bundle_id: "bundle-old",
+    to_release_id: null,
+    to_bundle_id: "bundle-new",
+    platform: "ios",
+    app_version: "1.0.0",
+    channel: "production",
+    cohort: "default",
+    update_strategy: "fingerprint",
+    fingerprint_hash: null,
+    sdk_version: null,
+    received_at_ms: 1,
+    ...overrides,
+  };
+}
+
+describe("searchEventInstallations", () => {
+  it.each([
+    ["installation id", "INSTALL-1"],
+    ["user id", "USER-1"],
+    ["username", "ALICE"],
+  ])("matches %s without case sensitivity", (_identity, query) => {
+    const row = eventRow();
+
+    const result = searchEventInstallations({
+      rows: [row],
+      query,
+      limit: 10,
+      offset: 0,
+    });
+
+    expect(result.data.map(({ installId }) => installId)).toEqual([
+      "install-1",
+    ]);
+  });
+
+  it("returns the newest state when an older identity matches", () => {
+    const rows = [
+      eventRow({
+        id: "event-old",
+        username: "legacy-name",
+        to_bundle_id: "bundle-old",
+        received_at_ms: 1,
+      }),
+      eventRow({
+        id: "event-new",
+        username: "current-name",
+        to_bundle_id: "bundle-current",
+        received_at_ms: 2,
+      }),
+    ];
+
+    const result = searchEventInstallations({
+      rows,
+      query: "LEGACY-NAME",
+      limit: 10,
+      offset: 0,
+    });
+
+    expect(result.data).toEqual([
+      {
+        installId: "install-1",
+        username: "current-name",
+        userId: "user-1",
+        lastKnownBundleId: "bundle-current",
+        latestStatus: "UPDATE_APPLIED",
+        platform: "ios",
+        appVersion: "1.0.0",
+        channel: "production",
+        cohort: "default",
+        receivedAtMs: 2,
+      },
+    ]);
+  });
+
+  it("sorts installation ids by code point", () => {
+    const rows = [
+      eventRow({ install_id: "install-z" }),
+      eventRow({ install_id: "install-a" }),
+      eventRow({ install_id: "install-A" }),
+    ];
+
+    const result = searchEventInstallations({
+      rows,
+      query: "",
+      limit: 10,
+      offset: 0,
+    });
+
+    expect(result.data.map(({ installId }) => installId)).toEqual([
+      "install-A",
+      "install-a",
+      "install-z",
+    ]);
+  });
+
+  it("applies the offset and caps the page size at 100", () => {
+    const rows = Array.from({ length: 105 }, (_, index) =>
+      eventRow({ install_id: `install-${index.toString().padStart(3, "0")}` }),
+    );
+
+    const result = searchEventInstallations({
+      rows,
+      query: "",
+      limit: 200,
+      offset: 2,
+    });
+
+    expect(result.data).toHaveLength(100);
+    expect(result.data.at(0)?.installId).toBe("install-002");
+    expect(result.data.at(-1)?.installId).toBe("install-101");
+    expect(result.pagination).toEqual({ total: 105, limit: 200, offset: 2 });
+  });
+});

package/src/insights/bounded/installationSearch.ts

@@ -0,0 +1,69 @@
+import type { InstallationSearchRow, OffsetPaginationResult } from "../domain";
+import type { BundleEventPersistenceRow } from "../persistence";
+import { compareCodePoints, compareEventNewest } from "./scan";
+
+type InstallationSearchRequest = {
+  readonly rows: readonly BundleEventPersistenceRow[];
+  readonly query: string;
+  readonly limit: number;
+  readonly offset: number;
+};
+
+function toSearchRow(row: BundleEventPersistenceRow): InstallationSearchRow {
+  return {
+    installId: row.install_id,
+    username: row.username,
+    userId: row.user_id,
+    lastKnownBundleId: row.to_bundle_id,
+    latestStatus: row.type,
+    platform: row.platform,
+    appVersion: row.app_version,
+    channel: row.channel,
+    cohort: row.cohort,
+    receivedAtMs: row.received_at_ms,
+  };
+}
+
+function matchesIdentity(
+  row: BundleEventPersistenceRow,
+  query: string,
+): boolean {
+  return (
+    row.install_id.toLowerCase().includes(query) ||
+    row.user_id?.toLowerCase().includes(query) === true ||
+    row.username?.toLowerCase().includes(query) === true
+  );
+}
+
+export function searchEventInstallations(
+  request: InstallationSearchRequest,
+): OffsetPaginationResult<InstallationSearchRow> {
+  const query = request.query.toLowerCase();
+  const matchingInstallIds = new Set<string>();
+  for (const row of request.rows) {
+    if (query.length === 0 || matchesIdentity(row, query)) {
+      matchingInstallIds.add(row.install_id);
+    }
+  }
+  const latestByInstall = new Map<string, BundleEventPersistenceRow>();
+  for (const row of request.rows) {
+    if (!matchingInstallIds.has(row.install_id)) continue;
+    const current = latestByInstall.get(row.install_id);
+    if (current === undefined || compareEventNewest(row, current) < 0) {
+      latestByInstall.set(row.install_id, row);
+    }
+  }
+  const matchingRows = [...latestByInstall.values()].sort((left, right) =>
+    compareCodePoints(left.install_id, right.install_id),
+  );
+  const pageSize = Math.min(Math.max(request.limit, 0), 100);
+  const page = matchingRows.slice(request.offset, request.offset + pageSize);
+  return {
+    data: page.map(toSearchRow),
+    pagination: {
+      total: matchingRows.length,
+      limit: request.limit,
+      offset: request.offset,
+    },
+  };
+}

package/src/insights/bounded/persistence.ts

@@ -0,0 +1,43 @@
+import { createUUIDv7 } from "@hot-updater/plugin-core";
+
+import type { CreateBundleEventRequest } from "../domain.js";
+import type { BundleEventPersistenceRow } from "../persistence.js";
+
+export function createBundleEventRow(
+  input: CreateBundleEventRequest,
+): BundleEventPersistenceRow {
+  const base = {
+    id: createUUIDv7(),
+    install_id: input.installId,
+    user_id: input.userId ?? null,
+    username: input.username ?? null,
+    from_release_id: input.fromReleaseId,
+    to_release_id: input.toReleaseId,
+    to_bundle_id: input.toBundleId,
+    platform: input.platform,
+    app_version: input.appVersion,
+    channel: input.channel,
+    cohort: input.cohort,
+    fingerprint_hash: input.fingerprintHash,
+    sdk_version: input.sdkVersion ?? null,
+    received_at_ms: Date.now(),
+  };
+  switch (input.type) {
+    case "UPDATE_APPLIED":
+    case "RECOVERED":
+    case "RELEASE_ADOPTED":
+      return {
+        ...base,
+        type: input.type,
+        from_bundle_id: input.fromBundleId,
+        update_strategy: input.updateStrategy,
+      };
+    case "UNCHANGED":
+      return {
+        ...base,
+        type: input.type,
+        from_bundle_id: null,
+        update_strategy: null,
+      };
+  }
+}

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

@@ -0,0 +1,219 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { InsightsScanLimitExceededError } from "../errors";
+import type {
+  InsightsPersistence,
+  InsightsScanInput,
+  BundleEventPersistenceRow,
+} from "../persistence";
+import { createInsightsProvider } 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,
+): InsightsPersistence => {
+  const rows = [...initialRows];
+  return {
+    async append(row) {
+      rows.push(row);
+    },
+    async scan(input: InsightsScanInput) {
+      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("createInsightsProvider", () => {
+  it("starts windowed insights 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<InsightsPersistence["scan"]>().mockResolvedValue([]);
+    const provider = createInsightsProvider({
+      async append() {},
+      scan,
+    });
+
+    // When
+    await provider.getBundleEventInsights("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 = createInsightsProvider(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 = createInsightsProvider(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 = createInsightsProvider(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 = createInsightsProvider(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 = createInsightsProvider({
+        async append() {},
+        async scan() {
+          if (delivered) return [];
+          delivered = true;
+          return rows;
+        },
+      });
+
+      await expect(provider.getBundleEventSummary("new")).rejects.toMatchObject(
+        {
+          name: "InsightsPersistenceOrderError",
+        },
+      );
+    },
+  );
+
+  it("fails instead of returning partial insights beyond 50,000 rows", async () => {
+    const persistence: InsightsPersistence = {
+      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 = createInsightsProvider(persistence);
+
+    await expect(provider.getBundleEventSummary("new")).rejects.toBeInstanceOf(
+      InsightsScanLimitExceededError,
+    );
+  });
+});