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

package/src/{insights → plugins/insights}/provider.ts

@@ -1,24 +1,23 @@
-import {
-  compareInsightsText,
-  isInsightsMovementEvent,
-  isUUIDv7,
-  type InsightsBundleEventFilter,
-  type BundleEventRow,
-  type InsightsEventCursor,
-  type InsightsEventFilter,
-  type InsightsModel,
-} from "@hot-updater/plugin-core";
+import { isUUIDv7 } from "@hot-updater/plugin-core";
 
+import { compareInsightsText, isInsightsMovementEvent } from "./contract";
 import type {
   ActiveInstallationWindow,
   InsightsBundleSelection,
-  InsightsScope,
   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,
@@ -33,6 +32,7 @@ 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,
@@ -169,8 +169,8 @@ const bundleFilter = (
       return { ...scope, type: "UPDATE_APPLIED", toBundleId: bundleId };
     case "recovered":
       return { ...scope, type: "RECOVERED", fromBundleId: bundleId };
-    case "unchanged":
-      return { ...scope, type: "UNCHANGED", toBundleId: bundleId };
+    case "failed":
+      return { ...scope, type: "UPDATE_FAILED", toBundleId: bundleId };
     default:
       throw new InsightsBadRequestError("Invalid Insights outcome.");
   }
@@ -318,6 +318,41 @@ const assertEventRows = (
   }
 };
 
+/** 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,
@@ -330,7 +365,7 @@ const toEventHistoryRow = (row: BundleEventRow): EventHistoryRow => ({
   toBundleId: row.to_bundle_id,
   type: row.type,
   userId: row.user_id,
-  username: row.metadata.username,
+  ...eventDetails(row),
 });
 
 const toInstallationRow = (row: BundleEventRow): InstallationRow => ({
@@ -346,7 +381,6 @@ const toInstallationRow = (row: BundleEventRow): InstallationRow => ({
   platform: row.platform,
   receivedAtMs: row.received_at_ms,
   userId: row.user_id,
-  username: row.metadata.username,
 });
 
 interface EventBounds {
@@ -581,12 +615,15 @@ export const createInsightsProvider = (
           "Invalid reporting installation window.",
         );
       }
-      // Whole hours, ending with the current one: the counts read only the
-      // maintained hour and day rows, never raw events.
+      // 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 sinceMs = Math.max(0, beforeReceivedAtMs - WINDOW_MS[window]);
+      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) {
@@ -622,7 +659,7 @@ export const createInsightsProvider = (
         downloadedReports,
         appliedReports,
         recoveredReports,
-        unchangedReports,
+        failedReports,
       ] = await Promise.all([
         reporting,
         measure(
@@ -646,7 +683,7 @@ export const createInsightsProvider = (
         countOutcome("downloaded"),
         countOutcome("applied"),
         countOutcome("recovered"),
-        countOutcome("unchanged"),
+        countOutcome("failed"),
       ]);
       return {
         ...scope,
@@ -660,7 +697,7 @@ export const createInsightsProvider = (
           downloadedReports,
           appliedReports,
           recoveredReports,
-          unchangedReports,
+          failedReports,
         },
       };
     },

package/src/{insights → plugins/insights}/queryInput.ts

@@ -1,9 +1,9 @@
 import type {
   ActiveInstallationWindow,
   InsightsBundleSelection,
-  InsightsScope,
 } from "./domain";
 import { InsightsBadRequestError } from "./errors";
+import type { InsightsScope } from "./modelTypes";
 import type {
   InsightsEventPageInput,
   InsightsUserInstallationPageInput,
@@ -88,7 +88,7 @@ export const parseEventPageInput = (
       outcome !== "downloaded" &&
       outcome !== "applied" &&
       outcome !== "recovered" &&
-      outcome !== "unchanged"
+      outcome !== "failed"
     ) {
       throw new InsightsBadRequestError("Invalid 'outcome' query parameter.");
     }

package/src/plugins/insights/reads.spec.ts

@@ -1,19 +1,19 @@
-import type { BundleEventRow } from "@hot-updater/plugin-core";
 import {
-  addInsightsDistinct,
-  countInsightsDistinct,
+  addDistinct,
+  countDistinct,
   createMemoryAdapter,
   type DatabaseAdapter,
-  mergeInsightsDistinct,
+  mergeDistinct,
 } from "@hot-updater/plugin-core/internal";
 import { createPluginTestHarness } from "@hot-updater/test-utils";
 import { describe, expect, it } from "vitest";
 
 import * as engine from "../../database";
-import { InsightsBadRequestError } from "../../insights/errors";
-import { createInsightsProvider } from "../../insights/provider";
-import type { InsightsEventPageInput } from "../../insights/types";
+import { InsightsBadRequestError } from "./errors";
+import type { BundleEventRow } from "./eventRow";
 import { createInsightsModel, insights } from "./index";
+import { createInsightsProvider } from "./provider";
+import type { InsightsEventPageInput } from "./types";
 
 const HOUR = 3_600_000;
 const DAY = 86_400_000;
@@ -39,7 +39,6 @@ const event = (
     app_version: "1.0.0",
     channel: "production",
     metadata: {
-      username: null,
       cohort: "1",
       update_strategy: "appVersion",
       fingerprint_hash: null,
@@ -51,9 +50,7 @@ const event = (
 
 /** The HLL estimate for these installs, as the stored sketches merge to. */
 const distinct = (installs: readonly string[]) =>
-  countInsightsDistinct(
-    mergeInsightsDistinct(installs.map((id) => addInsightsDistinct(null, id))),
-  );
+  countDistinct(mergeDistinct(installs.map((id) => addDistinct(null, id))));
 const installs = Array.from({ length: 24 }, (_, n) => `install-${n + 1}`);
 
 /** Rows each table returned, and the point reads it served. */
@@ -108,17 +105,14 @@ describe("insights latest events by bundle", () => {
         types: ["UNCHANGED", "UPDATE_APPLIED", "RECOVERED"],
       },
     ] as const;
-    // Whole hours from gauges, then a partial hour from heads.
-    for (const sinceMs of [T0, T0 + 1]) {
-      await expect(
-        harness.api.countLatestEvents({
-          platform: "ios",
-          channel: "production",
-          sinceMs,
-          bundle,
-        }),
-      ).resolves.toBe(4);
-    }
+    await expect(
+      harness.api.countLatestEvents({
+        platform: "ios",
+        channel: "production",
+        sinceMs: T0,
+        bundle,
+      }),
+    ).resolves.toBe(4);
   });
 
   it("counts a head once when a from and a to predicate of one type both match it", async () => {
@@ -152,29 +146,48 @@ describe("insights latest events by bundle", () => {
         sinceMs,
         bundle,
       });
-    // Whole hours from gauges, then a partial hour from heads.
-    for (const sinceMs of [T0, T0 + 1]) {
-      // From A or to B: A→B, A→C, D→B, and B→B. The gauges alone say 5,
-      // counting A→B under both predicates.
-      await expect(
-        count(
-          [
-            { field: "from_bundle_id", value: "A", types },
-            { field: "to_bundle_id", value: "B", types },
-          ],
-          sinceMs,
-        ),
-      ).resolves.toBe(4);
-      // B→B matches from B and to B through one pair: A→B, D→B, B→B.
-      await expect(
-        count(
-          [
-            { field: "from_bundle_id", value: "B", types },
-            { field: "to_bundle_id", value: "B", types },
-          ],
-          sinceMs,
-        ),
-      ).resolves.toBe(3);
+    // From A or to B: A→B, A→C, D→B, and B→B. The gauges alone say 5,
+    // counting A→B under both predicates.
+    await expect(
+      count(
+        [
+          { field: "from_bundle_id", value: "A", types },
+          { field: "to_bundle_id", value: "B", types },
+        ],
+        T0,
+      ),
+    ).resolves.toBe(4);
+    // B→B matches from B and to B through one pair: A→B, D→B, B→B.
+    await expect(
+      count(
+        [
+          { field: "from_bundle_id", value: "B", types },
+          { field: "to_bundle_id", value: "B", types },
+        ],
+        T0,
+      ),
+    ).resolves.toBe(3);
+  });
+
+  it("counts whole UTC days only, and rejects a start inside one", async () => {
+    const harness = await setup();
+    await harness.api.recordEvent(event(1, { received_at_ms: halfPast }));
+    await harness.api.recordEvent(
+      event(2, { received_at_ms: T0 + DAY + HOUR }),
+    );
+    const since = (sinceMs: number) =>
+      harness.api.countLatestEvents({
+        platform: "ios",
+        channel: "production",
+        sinceMs,
+      });
+    await expect(since(T0)).resolves.toBe(2);
+    await expect(since(T0 + DAY)).resolves.toBe(1);
+    await expect(since(T0 + 2 * DAY)).resolves.toBe(0);
+    for (const sinceMs of [T0 + 1, T0 + HOUR]) {
+      await expect(since(sinceMs)).rejects.toMatchObject({
+        code: "invalid-query",
+      });
     }
   });
 });
@@ -241,7 +254,7 @@ describe("insights read budgets", () => {
     expect(user.tables).toEqual({ bundle_event_heads: 3 });
   });
 
-  it("counts whole-hour windows from aggregates alone", async () => {
+  it("counts whole hours and whole UTC days from aggregates alone", async () => {
     const { api, read } = await setup();
     const counted = await read(() =>
       api.countEvents({
@@ -262,11 +275,11 @@ describe("insights read budgets", () => {
       api.countLatestEvents({
         platform: "ios",
         channel: "production",
-        sinceMs: T0 + HOUR,
+        sinceMs: T0 + DAY,
       }),
     );
-    // installs 6–24, plus install-1, whose head moved to day 2
-    expect(latest.result).toBe(20);
+    // install-1, whose head moved to day 2
+    expect(latest.result).toBe(1);
     expect(Object.keys(latest.tables)).toEqual(["insights_distribution"]);
 
     const byBundle = await read(() =>
@@ -301,7 +314,9 @@ describe("insights read budgets", () => {
       launches: 25,
       failedLaunches: 0,
     });
-    expect(Object.keys(lifetime.tables)).toEqual(["insights_overview"]);
+    expect(Object.keys(lifetime.tables)).toEqual([
+      "insights_overview_lifetime",
+    ]);
 
     const scope = await read(() =>
       api.getReleaseActivity({
@@ -317,9 +332,10 @@ describe("insights read budgets", () => {
         { startMs: T0 + 2 * DAY, launches: 1, failedLaunches: 0 },
       ],
     });
+    // Whole UTC days: the daily rollups alone.
     expect(Object.keys(scope.tables).toSorted()).toEqual([
-      "insights_overview",
-      "insights_sketches",
+      "insights_overview_daily",
+      "insights_sketches_daily",
     ]);
 
     const usage = await read(() =>
@@ -349,9 +365,281 @@ describe("insights read budgets", () => {
     });
     expect(Object.keys(usage.tables).toSorted()).toEqual([
       "insights_distribution",
+      "insights_sketches_daily",
+    ]);
+  });
+});
+
+describe("insights update failures", () => {
+  const setup = async () => {
+    const meter = metered(createMemoryAdapter());
+    const harness = await createPluginTestHarness(insights(), {
+      engine,
+      adapter: meter.adapter,
+      now: () => T0 + 30 * DAY,
+    });
+    const record = (
+      n: number,
+      install: number,
+      at: number,
+      overrides: Partial<BundleEventRow>,
+      metadata: Record<string, unknown> = {},
+    ) =>
+      harness.api.recordEvent(
+        event(n, {
+          install_id: `install-${install}`,
+          received_at_ms: at,
+          ...overrides,
+          metadata: { ...event(n).metadata, ...metadata },
+        } as Partial<BundleEventRow>),
+      );
+    const fail = (
+      n: number,
+      install: number,
+      at: number,
+      failure: Record<string, unknown>,
+    ) =>
+      record(
+        n,
+        install,
+        at,
+        failure.stage === "check"
+          ? {
+              type: "UPDATE_FAILED",
+              to_release_id: null,
+              to_bundle_id: "bundle-a",
+            }
+          : { type: "UPDATE_FAILED" },
+        { failure },
+      );
+    const denied = { stage: "download", reason: "http", http_status: 403 };
+    // install-1 fails to download release-b on two days, install-2 once with
+    // another origin code, install-3 on the network, install-4 installing.
+    await fail(1, 1, T0 + HOUR, { ...denied, origin_code: "AccessDenied" });
+    await fail(2, 1, T0 + DAY + HOUR, {
+      ...denied,
+      origin_code: "AccessDenied",
+    });
+    await fail(3, 2, T0 + 2 * HOUR, { ...denied, origin_code: "ExpiredToken" });
+    await fail(4, 3, T0 + 3 * HOUR, {
+      stage: "download",
+      reason: "network",
+      transport: "timeout",
+    });
+    await fail(5, 4, T0 + 4 * HOUR, {
+      stage: "install",
+      reason: "hash_mismatch",
+    });
+    // install-8's update check fails: its channel's, no release's.
+    await fail(6, 8, T0 + 5 * HOUR, { stage: "check", reason: "http" });
+    // Three downloads: two by patch, one that fell back from a patch.
+    for (const [n, install, metadata] of [
+      [7, 5, { delivery: "patch" }],
+      [8, 6, { delivery: "patch" }],
+      [9, 7, { delivery: "archive", patch_fallback: true }],
+    ] as const) {
+      await record(
+        n,
+        install,
+        T0 + 6 * HOUR,
+        { type: "UPDATE_DOWNLOADED" },
+        metadata,
+      );
+    }
+    // Two recoveries from release-b, one with an exit reason.
+    const recovered = {
+      type: "RECOVERED",
+      from_release_id: "release-b",
+      from_bundle_id: "bundle-b",
+      to_release_id: "release-a",
+      to_bundle_id: "bundle-a",
+    } as const;
+    await record(10, 9, T0 + 7 * HOUR, recovered, {
+      previous_process_exit: "CRASH",
+    });
+    await record(11, 10, T0 + 7 * HOUR, recovered);
+    const read = async <T>(call: () => Promise<T>) => {
+      meter.rows.clear();
+      const measured = await harness.measureReads(call);
+      return {
+        ...measured,
+        tables: Object.keys(Object.fromEntries(meter.rows)),
+      };
+    };
+    return { api: harness.api, read };
+  };
+  const scope = { platform: "ios", channel: "production" } as const;
+
+  it("reads a release's failures, installations, and breakdown over a window from aggregates only", async () => {
+    const { api, read } = await setup();
+    const failures = await read(() =>
+      api.getUpdateFailures({
+        ...scope,
+        releaseId: "release-b",
+        timeRange: { start: T0, end: T0 + 2 * DAY },
+      }),
+    );
+    expect(failures.result).toEqual({
+      coverage: { kind: "complete", sinceMs: 0 },
+      measuredAtMs: T0 + 30 * DAY,
+      failedUpdates: 5,
+      failedInstallations: distinct([
+        "install-1",
+        "install-2",
+        "install-3",
+        "install-4",
+      ]),
+      downloads: 3,
+      patchDownloads: 2,
+      patchFallbacks: 1,
+      breakdown: [
+        {
+          stage: "download",
+          reason: "http",
+          events: 3,
+          details: [
+            {
+              resource: null,
+              httpStatus: 403,
+              originCode: "AccessDenied",
+              transport: null,
+              events: 2,
+            },
+            {
+              resource: null,
+              httpStatus: 403,
+              originCode: "ExpiredToken",
+              transport: null,
+              events: 1,
+            },
+          ],
+        },
+        {
+          stage: "download",
+          reason: "network",
+          events: 1,
+          details: [
+            {
+              resource: null,
+              httpStatus: null,
+              originCode: null,
+              transport: "timeout",
+              events: 1,
+            },
+          ],
+        },
+        {
+          stage: "install",
+          reason: "hash_mismatch",
+          events: 1,
+          details: [
+            {
+              resource: null,
+              httpStatus: null,
+              originCode: null,
+              transport: null,
+              events: 1,
+            },
+          ],
+        },
+      ],
+      recoveries: {
+        failedLaunches: 2,
+        byExitReason: [{ exitReason: "CRASH", events: 1 }],
+      },
+    });
+    expect(failures.tables.toSorted()).toEqual([
+      "insights_failures",
+      "insights_overview",
       "insights_sketches",
     ]);
   });
+
+  it("reads a channel's failed checks against its active installations, from daily rows past 48 hours", async () => {
+    const { api, read } = await setup();
+    const failures = await read(() =>
+      api.getUpdateFailures({
+        ...scope,
+        timeRange: { start: T0, end: T0 + 3 * DAY },
+      }),
+    );
+    expect(failures.result).toMatchObject({
+      failedUpdates: 5,
+      failedInstallations: distinct([
+        "install-1",
+        "install-2",
+        "install-3",
+        "install-4",
+      ]),
+      downloads: 3,
+      // A failure is no activity: the downloads' and recoveries' installations.
+      checks: {
+        failures: 1,
+        failedInstallations: distinct(["install-8"]),
+        activeInstallations: distinct([
+          "install-5",
+          "install-6",
+          "install-7",
+          "install-9",
+          "install-10",
+        ]),
+      },
+      recoveries: { failedLaunches: 2 },
+    });
+    expect(
+      failures.result.breakdown!.map(({ stage, reason, events }) => [
+        stage,
+        reason,
+        events,
+      ]),
+    ).toEqual([
+      ["download", "http", 3],
+      ["check", "http", 1],
+      ["download", "network", 1],
+      ["install", "hash_mismatch", 1],
+    ]);
+    expect(failures.tables.toSorted()).toEqual([
+      "insights_failures",
+      "insights_overview_daily",
+      "insights_sketches_daily",
+    ]);
+  });
+
+  it("reads a release's failures since its first from the kept rows, and needs a range of at most 30 days for a channel", async () => {
+    const { api, read } = await setup();
+    const lifetime = await read(() =>
+      api.getUpdateFailures({ ...scope, releaseId: "release-b" }),
+    );
+    expect(lifetime.result).toEqual({
+      coverage: { kind: "complete", sinceMs: 0 },
+      measuredAtMs: T0 + 30 * DAY,
+      failedUpdates: 5,
+      failedInstallations: distinct([
+        "install-1",
+        "install-2",
+        "install-3",
+        "install-4",
+      ]),
+      downloads: 3,
+      patchDownloads: 2,
+      patchFallbacks: 1,
+    });
+    expect(lifetime.tables.toSorted()).toEqual([
+      "insights_overview_lifetime",
+      "insights_sketches_lifetime",
+    ]);
+    for (const invalid of [
+      scope,
+      { ...scope, platform: "web" },
+      { ...scope, releaseId: "release-b", timeRange: { start: 10, end: 10 } },
+      // Longer than the console's longest period, 30 days.
+      { ...scope, timeRange: { start: T0, end: T0 + 30 * DAY + 1 } },
+    ]) {
+      await expect(
+        api.getUpdateFailures(invalid as never),
+      ).rejects.toMatchObject({ code: "invalid-query" });
+    }
+  });
 });
 
 /**