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

package/src/{insights → plugins/insights}/insights.integration.spec.ts

@@ -4,14 +4,14 @@ import {
 } from "@hot-updater/plugin-core/internal";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
-import { builtInSettings } from "../db/builtInDatabase";
-import { createHotUpdater } from "../index";
-import { insights } from "../plugins/insights";
+import { toolingTargetOf } from "../../db/coreDatabase";
+import { createHotUpdater } from "../../index";
 import {
   createFencedDatabase,
   createRuntimeDatabase,
-} from "../runtime.testFixtures";
+} from "../../runtime.testFixtures";
 import { EVENT_BODY_MAX_BYTES } from "./eventInput";
+import { insights } from "./index";
 
 /** A server with the Insights plugin on an empty in-memory database. */
 const start = () =>
@@ -35,7 +35,6 @@ const event = {
   type: "UNCHANGED",
   updateStrategy: null,
   userId: "user-1",
-  username: "Jane",
   sdkVersion: "2.0.0",
 } as const;
 
@@ -105,7 +104,7 @@ describe("createHotUpdater Insights", () => {
     ).toBe(400);
   });
 
-  it("persists an event and serves the lean Insights views", async () => {
+  it("keeps an UNCHANGED report as the installation's latest event, not a listed event, and serves the lean Insights views", async () => {
     vi.useFakeTimers();
     vi.setSystemTime(new Date("2026-08-12T00:00:00.000Z"));
     const receivedAtMs = Date.now();
@@ -138,24 +137,18 @@ describe("createHotUpdater Insights", () => {
         type: "UNCHANGED",
       }),
     );
+    // A launch without an update is no event of its own.
     expect(events.status).toBe(200);
-    await expect(events.json()).resolves.toMatchObject({
-      data: [
-        {
-          id: expect.any(String),
-          installId: "install-1",
-          receivedAtMs,
-          type: "UNCHANGED",
-          userId: "user-1",
-          username: "Jane",
-        },
-      ],
+    await expect(events.json()).resolves.toEqual({
+      beforeReceivedAtMs: expect.any(Number),
+      data: [],
       nextCursor: null,
     });
     expect(installation.status).toBe(200);
     await expect(installation.json()).resolves.toMatchObject({
       installId: "install-1",
       latestStatus: "UNCHANGED",
+      receivedAtMs,
       userId: "user-1",
     });
     expect(matches.status).toBe(200);
@@ -164,13 +157,12 @@ describe("createHotUpdater Insights", () => {
       nextCursor: null,
     });
     expect(active.status).toBe(200);
-    // Whole hours, ending with the current one.
-    const end = Date.parse("2026-08-12T01:00:00.000Z");
+    // Ending with the current hour, from the UTC day the window reaches into.
     await expect(active.json()).resolves.toEqual({
       platform: "ios",
       channel: "production",
-      sinceMs: end - 24 * 60 * 60 * 1_000,
-      beforeReceivedAtMs: end,
+      sinceMs: Date.parse("2026-08-11T00:00:00.000Z"),
+      beforeReceivedAtMs: Date.parse("2026-08-12T01:00:00.000Z"),
       reportingInstallations: { count: 1, measuredAtMs: Date.now() },
       window: "24h",
     });
@@ -220,16 +212,22 @@ describe("createHotUpdater Insights", () => {
       ),
     );
     expect(overview.status).toBe(200);
-    await expect(overview.json()).resolves.toMatchObject({
+    // install-2's UNCHANGED report counts it among the bundle's latest
+    // events, and in no event count.
+    await expect(overview.json()).resolves.toEqual({
+      platform: "ios",
+      channel: "production",
+      window: "24h",
       sinceMs: 0,
       beforeReceivedAtMs: 60 * 60 * 1_000,
-      reportingInstallations: { count: 2 },
+      reportingInstallations: { count: 2, measuredAtMs: 500 },
       bundle: {
         bundleId: "B",
-        reportingInstallations: { count: 1 },
-        appliedReports: { count: 1 },
-        recoveredReports: { count: 1 },
-        unchangedReports: { count: 1 },
+        reportingInstallations: { count: 1, measuredAtMs: 500 },
+        downloadedReports: { count: 0, measuredAtMs: 500 },
+        appliedReports: { count: 1, measuredAtMs: 500 },
+        recoveredReports: { count: 1, measuredAtMs: 500 },
+        failedReports: { count: 0, measuredAtMs: 500 },
       },
     });
     const drilldown = await hotUpdater.handlers.admin(
@@ -264,6 +262,8 @@ describe("createHotUpdater Insights", () => {
     "/overview?platform=ios&channel=production&platform=android",
     "/events?bundleId=B",
     "/events?platform=ios&channel=production&bundleId=B&outcome=UNCHANGED",
+    // UNCHANGED reports are kept as no events, so no list holds them.
+    "/events?platform=ios&channel=production&bundleId=B&outcome=unchanged",
     "/events?sinceMs=20&beforeReceivedAtMs=10",
     // 90 days and 1 ms, longer than a bundle list covers.
     "/events?platform=ios&channel=production&bundleId=B&outcome=applied&sinceMs=0&beforeReceivedAtMs=7776000001",
@@ -307,7 +307,10 @@ describe("createHotUpdater Insights", () => {
       clientAccess: "public",
     });
     const migrated = createHotUpdater({
-      database: await createFencedDatabase("kysely", builtInSettings),
+      database: await createFencedDatabase(
+        "kysely",
+        toolingTargetOf([insights()]).settings,
+      ),
       plugins: [insights()],
       clientAccess: "public",
     });
@@ -476,18 +479,30 @@ describe("createHotUpdater Insights", () => {
 
   it("records a report with fields it does not know and still checks the ones it does", async () => {
     const hotUpdater = start();
-    const newer = { ...event, networkType: "wifi", screen: { width: 390 } };
+    const recordEvent = vi.spyOn(hotUpdater.api.insights, "recordEvent");
+    // `username` left the contract; an older client's is ignored like any other.
+    const newer = {
+      ...event,
+      networkType: "wifi",
+      screen: { width: 390 },
+      username: "Jane",
+    };
 
     expect((await hotUpdater.handlers.client(eventRequest(newer))).status).toBe(
       204,
     );
+    expect(recordEvent.mock.calls[0]![0].metadata).not.toHaveProperty(
+      "username",
+    );
     const installation = await hotUpdater.handlers.admin(
       new Request("https://example.com/installations/install-1"),
     );
-    await expect(installation.json()).resolves.toMatchObject({
+    const found = await installation.json();
+    expect(found).toMatchObject({
       installId: "install-1",
       latestStatus: "UNCHANGED",
     });
+    expect(found).not.toHaveProperty("username");
     const invalid = await hotUpdater.handlers.client(
       eventRequest({ ...newer, channel: 7 }),
     );
@@ -501,10 +516,253 @@ describe("createHotUpdater Insights", () => {
     expect(tooLarge.status).toBe(413);
   });
 
+  it("records every update failure, reading unknown or malformed parts as unknown, and lists it with what failed", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(Date.UTC(2026, 8, 20, 10));
+    const hotUpdater = start();
+    const failed = {
+      ...event,
+      type: "UPDATE_FAILED",
+      fromBundleId: "bundle-1",
+      toBundleId: "bundle-2",
+      toReleaseId: "release-2",
+      updateStrategy: "appVersion",
+    };
+    const report = async (metadata: unknown) => {
+      const response = await hotUpdater.handlers.client(
+        eventRequest({ ...failed, metadata }),
+      );
+      expect(response.status).toBe(204);
+      vi.advanceTimersByTime(1);
+    };
+    await report({
+      failure: {
+        stage: "download",
+        reason: "http",
+        resource: "artifact",
+        httpStatus: 403,
+        originCode: "AccessDenied",
+      },
+    });
+    // A newer client's stage, reason, resource, and transport.
+    await report({
+      failure: {
+        stage: "verify",
+        reason: "quantum",
+        resource: "shard",
+        transport: "carrier-pigeon",
+      },
+    });
+    // No failure, one that is not an object, and malformed optional fields.
+    await report(undefined);
+    await report({ failure: "broken" });
+    await report({
+      failure: {
+        stage: "install",
+        reason: "storage",
+        httpStatus: "403",
+        originCode: "not a code",
+        previousProcessExit: "x".repeat(65),
+      },
+    });
+
+    const events = await hotUpdater.handlers.admin(
+      new Request(
+        `https://example.com/events?platform=ios&channel=production&bundleId=bundle-2&outcome=failed&beforeReceivedAtMs=${Date.now()}`,
+      ),
+    );
+    expect(events.status).toBe(200);
+    const { data } = (await events.json()) as {
+      data: { type: string; failure: unknown }[];
+    };
+    expect(data.map(({ type }) => type)).toEqual(
+      Array(5).fill("UPDATE_FAILED"),
+    );
+    expect(data.map(({ failure }) => failure)).toEqual([
+      { stage: "install", reason: "storage" },
+      { stage: "unknown", reason: "unknown" },
+      { stage: "unknown", reason: "unknown" },
+      {
+        stage: "unknown",
+        reason: "unknown",
+        resource: "unknown",
+        transport: "unknown",
+      },
+      {
+        stage: "download",
+        reason: "http",
+        resource: "artifact",
+        httpStatus: 403,
+        originCode: "AccessDenied",
+      },
+    ]);
+    // A failure moves no installation: none has reported a launch.
+    expect(
+      (
+        await hotUpdater.handlers.admin(
+          new Request("https://example.com/installations/install-1"),
+        )
+      ).status,
+    ).toBe(404);
+    // Only a structurally invalid report is refused.
+    for (const invalid of [
+      { ...failed, fromBundleId: null },
+      { ...failed, updateStrategy: null },
+      { ...failed, eventId: "not-a-uuid" },
+    ]) {
+      expect(
+        (await hotUpdater.handlers.client(eventRequest(invalid))).status,
+      ).toBe(400);
+    }
+  });
+
+  it("keeps how a bundle arrived and why a crashed process exited", async () => {
+    const hotUpdater = start();
+    const movement = {
+      ...event,
+      fromBundleId: "bundle-1",
+      toBundleId: "bundle-2",
+      toReleaseId: "release-2",
+      updateStrategy: "appVersion",
+    };
+    for (const body of [
+      {
+        ...movement,
+        type: "UPDATE_DOWNLOADED",
+        metadata: { delivery: "archive", patchFallback: true },
+      },
+      {
+        ...movement,
+        type: "RECOVERED",
+        installId: "install-2",
+        metadata: { previousProcessExit: "CRASH_NATIVE" },
+      },
+      {
+        ...movement,
+        type: "UPDATE_DOWNLOADED",
+        installId: "install-3",
+        metadata: { delivery: "teleport", patchFallback: "yes" },
+      },
+    ]) {
+      expect(
+        (await hotUpdater.handlers.client(eventRequest(body))).status,
+      ).toBe(204);
+    }
+    const events = await hotUpdater.handlers.admin(
+      new Request(
+        `https://example.com/events?beforeReceivedAtMs=${Date.now() + 1}`,
+      ),
+    );
+    const { data } = (await events.json()) as {
+      data: Record<string, unknown>[];
+    };
+    const byInstall = Object.fromEntries(
+      data.map((row) => [row.installId, row]),
+    );
+    expect(byInstall["install-1"]).toMatchObject({
+      delivery: "archive",
+      patchFallback: true,
+    });
+    expect(byInstall["install-2"]).toMatchObject({
+      previousProcessExit: "CRASH_NATIVE",
+    });
+    expect(byInstall["install-3"]).toMatchObject({ delivery: "unknown" });
+    expect(byInstall["install-3"]).not.toHaveProperty("patchFallback");
+  });
+
+  it("serves a release's and a channel's update failures to admins", async () => {
+    vi.useFakeTimers();
+    const at = Date.UTC(2026, 8, 20, 10, 30);
+    vi.setSystemTime(at);
+    const hotUpdater = start();
+    const failed = (installId: string, failure: Record<string, unknown>) =>
+      hotUpdater.handlers.client(
+        eventRequest({
+          ...event,
+          installId,
+          type: "UPDATE_FAILED",
+          fromBundleId: "bundle-1",
+          toBundleId: failure.stage === "check" ? "bundle-1" : "bundle-2",
+          toReleaseId: failure.stage === "check" ? null : "release-2",
+          updateStrategy: "appVersion",
+          metadata: { failure },
+        }),
+      );
+    await failed("install-1", {
+      stage: "download",
+      reason: "http",
+      httpStatus: 403,
+    });
+    await failed("install-2", { stage: "check", reason: "http" });
+    const hour = at - (at % 3_600_000);
+    const range = `start=${hour}&end=${hour + 3_600_000}`;
+    const read = (query: string) =>
+      hotUpdater.handlers.admin(
+        new Request(`https://example.com/failures?${query}`),
+      );
+
+    const release = await read(
+      `platform=ios&channel=production&releaseId=release-2&${range}`,
+    );
+    expect(release.status).toBe(200);
+    await expect(release.json()).resolves.toMatchObject({
+      failedUpdates: 1,
+      failedInstallations: 1,
+      downloads: 0,
+      breakdown: [
+        {
+          stage: "download",
+          reason: "http",
+          events: 1,
+          details: [
+            {
+              resource: null,
+              httpStatus: 403,
+              originCode: null,
+              transport: null,
+              events: 1,
+            },
+          ],
+        },
+      ],
+      recoveries: { failedLaunches: 0, byExitReason: [] },
+    });
+    await expect(
+      (
+        await read("platform=ios&channel=production&releaseId=release-2")
+      ).json(),
+    ).resolves.toMatchObject({ failedUpdates: 1, failedInstallations: 1 });
+    const channel = await read(`platform=ios&channel=production&${range}`);
+    await expect(channel.json()).resolves.toMatchObject({
+      failedUpdates: 1,
+      checks: { failures: 1, failedInstallations: 1 },
+      breakdown: [
+        { stage: "check", reason: "http", events: 1 },
+        { stage: "download", reason: "http", events: 1 },
+      ],
+    });
+    for (const invalid of [
+      "channel=production&releaseId=release-2",
+      "platform=ios&channel=production",
+      `platform=ios&channel=production&start=${hour}`,
+      "platform=ios&channel=production&start=a&end=b",
+      // Over 30 days, the console's longest period.
+      `platform=ios&channel=production&start=${hour - 30 * 86_400_000}&end=${hour + 1}`,
+    ]) {
+      expect((await read(invalid)).status).toBe(400);
+    }
+  });
+
   it("counts a retried report once under its client event ID, whichever installation repeats it", async () => {
     const hotUpdater = start();
     const eventId = "01987a6e-4c00-7abc-8def-0123456789ab";
-    const report = { ...event, eventId };
+    const applied = {
+      ...event,
+      type: "UPDATE_APPLIED",
+      fromBundleId: "bundle-0",
+      updateStrategy: "appVersion",
+    } as const;
+    const report = { ...applied, eventId };
     const counts = async () => {
       const overview = await hotUpdater.handlers.admin(
         new Request(
@@ -513,9 +771,9 @@ describe("createHotUpdater Insights", () => {
       );
       return (
         (await overview.json()) as {
-          readonly bundle: { readonly unchangedReports: { count: number } };
+          readonly bundle: { readonly appliedReports: { count: number } };
         }
-      ).bundle.unchangedReports.count;
+      ).bundle.appliedReports.count;
     };
 
     for (let attempt = 0; attempt < 2; attempt += 1) {
@@ -553,12 +811,50 @@ describe("createHotUpdater Insights", () => {
     // Without an ID the server creates one, so each report counts.
     for (let attempt = 0; attempt < 2; attempt += 1) {
       expect(
-        (await hotUpdater.handlers.client(eventRequest(event))).status,
+        (await hotUpdater.handlers.client(eventRequest(applied))).status,
       ).toBe(204);
     }
     await expect(counts()).resolves.toBe(3);
   });
 
+  it("counts an installation's UNCHANGED reports once a UTC day, retried or repeated", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-08-12T10:00:00.000Z"));
+    const hotUpdater = start();
+    const append = vi.spyOn(hotUpdater.api.insights, "recordEvent");
+    const launches = async () => {
+      const {
+        data: [activity],
+      } = await hotUpdater.api.insights.getReleaseActivity({
+        scope: { platform: "ios", channel: "production" },
+        timeRange: {
+          start: Date.parse("2026-08-12T00:00:00.000Z"),
+          end: Date.parse("2026-08-14T00:00:00.000Z"),
+        },
+      });
+      return activity!.metrics.launches;
+    };
+    const report = {
+      ...event,
+      eventId: "01987a6e-4c00-7abc-8def-0123456789ab",
+    };
+
+    // A retry, then relaunches later that day, with and without an ID.
+    for (const body of [report, report, event, event]) {
+      expect(
+        (await hotUpdater.handlers.client(eventRequest(body))).status,
+      ).toBe(204);
+      vi.advanceTimersByTime(60 * 60 * 1_000);
+    }
+    expect(append).toHaveBeenCalledTimes(4);
+    await expect(launches()).resolves.toBe(1);
+
+    // The next UTC day counts the installation again.
+    vi.setSystemTime(new Date("2026-08-13T09:00:00.000Z"));
+    expect((await hotUpdater.handlers.client(eventRequest())).status).toBe(204);
+    await expect(launches()).resolves.toBe(2);
+  });
+
   it.each([
     "event-1",
     "01987A6E-4C00-7ABC-8DEF-0123456789AB",

package/src/plugins/insights/insightsRollout.integration.spec.ts

@@ -1,7 +1,6 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import type { BundleEventRow } from "@hot-updater/plugin-core";
 import {
   runContentionHarness,
   withAdapterLatency,
@@ -17,6 +16,7 @@ import { resolveSchema } from "../../database/resolveSchema";
 import { createSqlAdapter } from "../../database/sql/sqlAdapter";
 import { pgExecutor } from "../../database/sql/sqlTestExecutors";
 import type { CoreReader } from "../definePlugin";
+import type { BundleEventRow } from "./eventRow";
 import { insights, insightsSchema } from "./index";
 
 assertDockerComposeAvailable(
@@ -68,7 +68,6 @@ const move = (
     app_version: "1.0.0",
     channel: "production",
     metadata: {
-      username: null,
       cohort: "1",
       update_strategy: "appVersion",
       fingerprint_hash: null,

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

@@ -1,19 +1,17 @@
 import { PGlite } from "@electric-sql/pglite";
-import type { InsightsModel } from "@hot-updater/plugin-core";
 import {
   createMemoryAdapter,
   type DatabaseAdapter,
 } from "@hot-updater/plugin-core/internal";
-import {
-  createPluginTestHarness,
-  setupInsightsModelTestSuite,
-} from "@hot-updater/test-utils";
+import { createPluginTestHarness } from "@hot-updater/test-utils";
 import { afterAll } from "vitest";
 
 import * as engine from "../../database";
 import { createSqlAdapter } from "../../database/sql/sqlAdapter";
 import { pgliteExecutor } from "../../database/sql/sqlTestExecutors";
 import { createInsightsModel, insights } from "./index";
+import type { InsightsModel } from "./modelTypes";
+import { setupInsightsModelTestSuite } from "./testing";
 
 /** The plugin's model on a fresh adapter per test, behind one stable model. */
 const onFreshAdapter = (adapter: () => DatabaseAdapter) => {

package/src/plugins/insights/model.ts

@@ -1,7 +1,6 @@
-import type { InsightsModel } from "@hot-updater/plugin-core";
-import { createValidatedInsightsModel } from "@hot-updater/plugin-core/internal";
-
+import { createValidatedInsightsModel } from "./contract";
 import type { InsightsApi } from "./index";
+import type { InsightsModel } from "./modelTypes";
 
 /**
  * The plugin's API as `InsightsModel`, validated at its boundary: what the