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

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

@@ -0,0 +1,189 @@
+import { describe, expect, it } from "vitest";
+
+import type { BundleEventPersistenceRow } from "../persistence";
+import { collectActiveInstallationOverview } from "./activeOverview";
+
+const HOUR_MS = 60 * 60 * 1_000;
+const DAY_MS = 24 * HOUR_MS;
+
+type EventRowOptions = {
+  readonly id: string;
+  readonly receivedAtMs: number;
+  readonly installId?: string;
+  readonly userId?: string | null;
+  readonly bundleId?: string;
+};
+
+type SeriesWindow = {
+  readonly startMs: number;
+  readonly bucketCount: number;
+  readonly bucketSizeMs: number;
+};
+
+function eventRow(options: EventRowOptions): BundleEventPersistenceRow {
+  return {
+    id: options.id,
+    type: "UPDATE_APPLIED",
+    install_id: options.installId ?? `install-${options.id}`,
+    user_id: options.userId ?? null,
+    username: null,
+    from_release_id: null,
+    from_bundle_id: "old",
+    to_release_id: null,
+    to_bundle_id: options.bundleId ?? "new",
+    platform: "ios",
+    app_version: "1.0.0",
+    channel: "production",
+    cohort: "default",
+    update_strategy: "fingerprint",
+    fingerprint_hash: null,
+    sdk_version: null,
+    received_at_ms: options.receivedAtMs,
+  };
+}
+
+function expectedSeries(
+  window: SeriesWindow,
+  values: Readonly<Record<number, number>>,
+): { readonly bucketStartMs: number; readonly value: number }[] {
+  return Array.from({ length: window.bucketCount }, (_, index) => ({
+    bucketStartMs: window.startMs + index * window.bucketSizeMs,
+    value: values[index] ?? 0,
+  }));
+}
+
+describe("collectActiveInstallationOverview", () => {
+  it("uses the strict window and latest installation rows for a user", () => {
+    const asOfMs = 100 * HOUR_MS;
+    const windowStartMs = asOfMs - 24 * HOUR_MS;
+    const window = {
+      startMs: windowStartMs,
+      bucketCount: 24,
+      bucketSizeMs: HOUR_MS,
+    } as const;
+    const rows = [
+      eventRow({
+        id: "a-start",
+        receivedAtMs: windowStartMs,
+        installId: "install-a",
+        userId: "user-a",
+        bundleId: "bundle-b",
+      }),
+      eventRow({
+        id: "a-latest",
+        receivedAtMs: asOfMs - 1,
+        installId: "install-a",
+        userId: "user-a",
+        bundleId: "bundle-a",
+      }),
+      eventRow({
+        id: "before-window",
+        receivedAtMs: windowStartMs - 1,
+        userId: "user-a",
+      }),
+      eventRow({
+        id: "at-cutoff",
+        receivedAtMs: asOfMs,
+        userId: "user-a",
+      }),
+      eventRow({
+        id: "tie-a",
+        receivedAtMs: asOfMs - HOUR_MS,
+        installId: "install-tie",
+        userId: "user-a",
+        bundleId: "bundle-b",
+      }),
+      eventRow({
+        id: "tie-z",
+        receivedAtMs: asOfMs - HOUR_MS,
+        installId: "install-tie",
+        userId: "user-a",
+        bundleId: "bundle-c",
+      }),
+      eventRow({
+        id: "changed-user-old",
+        receivedAtMs: windowStartMs,
+        installId: "install-changed-user",
+        userId: "user-a",
+      }),
+      eventRow({
+        id: "changed-user-new",
+        receivedAtMs: asOfMs - 1,
+        installId: "install-changed-user",
+        userId: "user-b",
+      }),
+    ];
+
+    expect(
+      collectActiveInstallationOverview({
+        rows,
+        asOfMs,
+        window: "24h",
+        userId: "user-a",
+      }),
+    ).toEqual({
+      asOfMs,
+      window: "24h",
+      activeInstallations: 2,
+      series: expectedSeries(window, { 0: 1, 23: 2 }),
+      bundleSeries: [
+        {
+          bundleId: "bundle-a",
+          series: expectedSeries(window, { 23: 1 }),
+        },
+        {
+          bundleId: "bundle-b",
+          series: expectedSeries(window, { 0: 1 }),
+        },
+        {
+          bundleId: "bundle-c",
+          series: expectedSeries(window, { 23: 1 }),
+        },
+      ],
+      bundles: [
+        { bundleId: "bundle-a", installations: 1 },
+        { bundleId: "bundle-c", installations: 1 },
+      ],
+    });
+  });
+
+  it("includes installations with any user when the filter is omitted", () => {
+    const asOfMs = 10 * DAY_MS;
+    const windowStartMs = asOfMs - 7 * DAY_MS;
+    const window = {
+      startMs: windowStartMs,
+      bucketCount: 7,
+      bucketSizeMs: DAY_MS,
+    } as const;
+    const rows = [
+      eventRow({
+        id: "user-a",
+        receivedAtMs: windowStartMs,
+        userId: "user-a",
+        bundleId: "bundle-b",
+      }),
+      eventRow({
+        id: "anonymous",
+        receivedAtMs: asOfMs - 1,
+        bundleId: "bundle-a",
+      }),
+    ];
+
+    const result = collectActiveInstallationOverview({
+      rows,
+      asOfMs,
+      window: "7d",
+    });
+
+    expect(result.activeInstallations).toBe(2);
+    expect(result.series).toEqual(expectedSeries(window, { 0: 1, 6: 1 }));
+    expect(result.bundles).toEqual([
+      { bundleId: "bundle-a", installations: 1 },
+      { bundleId: "bundle-b", installations: 1 },
+    ]);
+    expect(result.bundleSeries.map(({ bundleId }) => bundleId)).toEqual([
+      "bundle-a",
+      "bundle-b",
+    ]);
+  });
+});

package/src/analytics/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/analytics/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/analytics/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/analytics/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,
+      };
+  }
+}