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

package/src/plugins/insights/schema.ts

@@ -3,87 +3,153 @@ import { defineAggregate, defineTable } from "../../database/schema";
 export const HOUR_MS = 3_600_000;
 export const DAY_MS = 86_400_000;
 
-const MOVEMENTS = new Set(["UPDATE_DOWNLOADED", "UPDATE_APPLIED", "RECOVERED"]);
-
-const bundleEvents = defineTable(
-  {
-    id: { type: "string", maxLength: 36 },
-    type: { type: "string", maxLength: 32 },
-    install_id: { type: "string", maxLength: 255 },
-    user_id: { type: "string", maxLength: 255, required: false },
-    from_release_id: { type: "string", maxLength: 36, required: false },
-    from_bundle_id: { type: "string", maxLength: 36, required: false },
-    to_release_id: { type: "string", maxLength: 36, required: false },
-    to_bundle_id: { type: "string", maxLength: 36 },
-    platform: { type: "string", maxLength: 16 },
-    app_version: { type: "string" },
-    channel: { type: "string" },
-    metadata: { type: "json" },
-    received_at_ms: { type: "integer" },
-  },
-  {
-    key: ["id"],
-    derived: {
-      /** The UTC day the event was received in. */
-      day: {
-        type: "integer",
-        compute: (row) => row.received_at_ms - (row.received_at_ms % DAY_MS),
-      },
-      /** Set only for events that belong in installation history. */
-      movement_install_id: {
-        type: "string",
-        compute: (row) => (MOVEMENTS.has(row.type) ? row.install_id : null),
-      },
-      /** The bundle a bundle filter matches: `from:<bundle>` for RECOVERED, else `to:<bundle>`. */
-      bundle_ref: {
-        type: "string",
-        multi: true,
-        compute: (row) => [
-          row.type === "RECOVERED" && row.from_bundle_id !== null
-            ? `from:${row.from_bundle_id}`
-            : `to:${row.to_bundle_id}`,
-        ],
-      },
+/** How long Insights keeps its rows, in whole days. Lifetime counters are kept. */
+export interface InsightsRetention {
+  /** Raw events and hourly rollups. */
+  readonly rawDays: number;
+  /** Daily rollups, and each installation's latest event and the gauges that count it. */
+  readonly dailyDays: number;
+}
+
+/**
+ * The default periods (decision 59): 90 days, and 13 months as 400 days, so
+ * the same month a year ago stays whole.
+ */
+export const RAW_RETENTION_DAYS = 90;
+export const DAILY_RETENTION_DAYS = 400;
+export const DEFAULT_INSIGHTS_RETENTION: InsightsRetention = {
+  rawDays: RAW_RETENTION_DAYS,
+  dailyDays: DAILY_RETENTION_DAYS,
+};
+
+/** Rows keyed by a bucket that expire `days` after it starts. */
+interface BucketRetention {
+  readonly field: "bucket_start_ms";
+  readonly days: number;
+}
+const bucketRetention = (days: number): BucketRetention => ({
+  field: "bucket_start_ms",
+  days,
+});
+
+const MOVEMENTS = new Set([
+  "UPDATE_DOWNLOADED",
+  "UPDATE_APPLIED",
+  "RECOVERED",
+  "UPDATE_FAILED",
+]);
+
+/** A failed update check: it names no target bundle, so no bundle list shows it. */
+export const isFailedCheck = (row: {
+  readonly type: string;
+  readonly metadata: unknown;
+}): boolean =>
+  row.type === "UPDATE_FAILED" &&
+  (row.metadata as { failure?: { stage?: unknown } } | null)?.failure?.stage ===
+    "check";
+
+/**
+ * Downloads, applies, recoveries, and update failures, whole. An UNCHANGED
+ * report counts as a launch and moves its installation's head, but no list
+ * shows it, so no row keeps it.
+ */
+const bundleEvents = (days: number) =>
+  defineTable(
+    {
+      id: { type: "string", maxLength: 36 },
+      type: { type: "string", maxLength: 32 },
+      install_id: { type: "string", maxLength: 255 },
+      user_id: { type: "string", maxLength: 255, required: false },
+      from_release_id: { type: "string", maxLength: 36, required: false },
+      from_bundle_id: { type: "string", maxLength: 36, required: false },
+      to_release_id: { type: "string", maxLength: 36, required: false },
+      to_bundle_id: { type: "string", maxLength: 36 },
+      platform: { type: "string", maxLength: 16 },
+      app_version: { type: "string" },
+      channel: { type: "string" },
+      metadata: { type: "json" },
+      received_at_ms: { type: "integer" },
     },
-    indexes: {
-      recent: { eq: ["channel", "platform", "day"], sort: ["received_at_ms"] },
-      movementsByInstall: {
-        eq: ["movement_install_id"],
-        sort: ["received_at_ms"],
+    {
+      key: ["id"],
+      derived: {
+        /** The UTC day the event was received in. */
+        day: {
+          type: "integer",
+          compute: (row) => row.received_at_ms - (row.received_at_ms % DAY_MS),
+        },
+        /** Set only for events that belong in installation history. */
+        movement_install_id: {
+          type: "string",
+          compute: (row) => (MOVEMENTS.has(row.type) ? row.install_id : null),
+        },
+        /**
+         * The bundle a bundle filter matches: `from:<bundle>` for RECOVERED,
+         * none for a failed check, else `to:<bundle>`.
+         */
+        bundle_ref: {
+          type: "string",
+          multi: true,
+          compute: (row) =>
+            isFailedCheck(row)
+              ? []
+              : [
+                  row.type === "RECOVERED" && row.from_bundle_id !== null
+                    ? `from:${row.from_bundle_id}`
+                    : `to:${row.to_bundle_id}`,
+                ],
+        },
       },
-      byBundle: {
-        eq: ["platform", "channel", "type", "bundle_ref", "day"],
-        sort: ["received_at_ms"],
+      indexes: {
+        recent: {
+          eq: ["channel", "platform", "day"],
+          sort: ["received_at_ms"],
+        },
+        movementsByInstall: {
+          eq: ["movement_install_id"],
+          sort: ["received_at_ms"],
+        },
+        byBundle: {
+          eq: ["platform", "channel", "type", "bundle_ref", "day"],
+          sort: ["received_at_ms"],
+        },
+        /** Events of every scope by day, for the console's unfiltered event list. */
+        byDay: { eq: ["day"], sort: ["received_at_ms"] },
       },
-      /** Events of every scope by day, for the console's unfiltered event list. */
-      byDay: { eq: ["day"], sort: ["received_at_ms"] },
+      // A day's events go together, oldest days first, walking `byDay`.
+      retention: { field: "day", days },
     },
-  },
-);
-
-/** Each installation's latest event, whole, so reading it is one point read. */
-const bundleEventHeads = defineTable(
-  {
-    install_id: { type: "string", maxLength: 255 },
-    id: { type: "string", maxLength: 36 },
-    type: { type: "string", maxLength: 32 },
-    user_id: { type: "string", maxLength: 255, required: false },
-    from_release_id: { type: "string", maxLength: 36, required: false },
-    from_bundle_id: { type: "string", maxLength: 36, required: false },
-    to_release_id: { type: "string", maxLength: 36, required: false },
-    to_bundle_id: { type: "string", maxLength: 36 },
-    platform: { type: "string", maxLength: 16 },
-    app_version: { type: "string" },
-    channel: { type: "string" },
-    metadata: { type: "json" },
-    received_at_ms: { type: "integer" },
-    current_release_id: { type: "string", maxLength: 36, required: false },
-  },
-  {
-    key: ["install_id"],
-    indexes: { byUser: { eq: ["user_id"], sort: ["install_id"] } },
-  },
-);
+  );
+
+/**
+ * Each installation's latest event, whole, so reading it is one point read.
+ * Its gauges count it in the UTC day of that event. An update failure moves
+ * nothing, so no head holds one.
+ */
+const bundleEventHeads = (days: number) =>
+  defineTable(
+    {
+      install_id: { type: "string", maxLength: 255 },
+      id: { type: "string", maxLength: 36 },
+      type: { type: "string", maxLength: 32 },
+      user_id: { type: "string", maxLength: 255, required: false },
+      from_release_id: { type: "string", maxLength: 36, required: false },
+      from_bundle_id: { type: "string", maxLength: 36, required: false },
+      to_release_id: { type: "string", maxLength: 36, required: false },
+      to_bundle_id: { type: "string", maxLength: 36 },
+      platform: { type: "string", maxLength: 16 },
+      app_version: { type: "string" },
+      channel: { type: "string" },
+      metadata: { type: "json" },
+      received_at_ms: { type: "integer" },
+    },
+    {
+      key: ["install_id"],
+      indexes: { byUser: { eq: ["user_id"], sort: ["install_id"] } },
+      // An installation unseen for the daily period is gone, with its gauges' day.
+      retention: { field: "received_at_ms", days },
+    },
+  );
 
 /**
  * Shards are keyed by install id. Counters are blind increments and never
@@ -93,6 +159,10 @@ const bundleEventHeads = defineTable(
  * on DynamoDB Local retried 2–24% at 16, almost all on gauge rows, and 1–5%
  * with gauges at 32. Sketches stay at 16: each shard row carries 2 KB of
  * registers that every read merges.
+ *
+ * Every Insights aggregate is `batched`: on DynamoDB and Firestore, which
+ * bill each write, an event's changes apply after it commits, merged with
+ * other events' into one write per row, on one shard per writer.
  */
 const COUNTER_SHARDS = 8;
 const GAUGE_SHARDS = 32;
@@ -105,109 +175,197 @@ const identityFields = {
 } as const;
 const window = { eq: ["identity"], sort: ["bucket_start_ms"] } as const;
 
-const insightsOverview = defineAggregate(identityFields, {
-  key: ["identity", "bucket_start_ms"],
-  counters: ["downloads", "launches", "failed_launches"],
-  shards: COUNTER_SHARDS,
-  indexes: { window },
-});
+/**
+ * Counters of one period kind: hourly, daily, or lifetime at bucket 0. A
+ * release or channel row counts downloads, launches, and failed launches,
+ * and downloads a patch delivered and those that fell back from one. A
+ * release's lifetime row counts its failed updates (`failed_updates`), since
+ * no breakdown row outlives the raw period; windowed reads sum
+ * `insights_failures` instead.
+ */
+const counters = (retention?: BucketRetention) =>
+  defineAggregate(identityFields, {
+    key: ["identity", "bucket_start_ms"],
+    counters: [
+      "downloads",
+      "launches",
+      "failed_launches",
+      "failed_updates",
+      "patch_downloads",
+      "patch_fallbacks",
+    ],
+    shards: COUNTER_SHARDS,
+    batched: true,
+    indexes: { window },
+    ...(retention === undefined ? {} : { retention }),
+  });
 
-const insightsSketches = defineAggregate(identityFields, {
-  key: ["identity", "bucket_start_ms"],
-  distinct: ["launch_users", "activity_users"],
-  shards: SKETCH_SHARDS,
-  indexes: { window },
-});
+/**
+ * Unique-installation sketches of one period kind. Rows of a failure
+ * identity (`failure` and `check` scopes) keep only `failed_users`, so a
+ * release's launch rows never grow by a failure's registers.
+ */
+const sketches = (retention: BucketRetention) =>
+  defineAggregate(identityFields, {
+    key: ["identity", "bucket_start_ms"],
+    distinct: ["launch_users", "activity_users", "failed_users"],
+    shards: SKETCH_SHARDS,
+    batched: true,
+    indexes: { window },
+    retention,
+  });
 
-/** Installations counted in the hour of their latest event. */
-const insightsDistribution = defineAggregate(
-  {
-    channel: { type: "string" },
-    platform: { type: "string", maxLength: 16 },
-    app_version: { type: "string" },
-    release_id: { type: "string", maxLength: 36 },
-    bucket_start_ms: { type: "integer" },
-  },
-  {
-    key: [
-      "channel",
-      "platform",
-      "app_version",
-      "release_id",
-      "bucket_start_ms",
-    ],
-    gauges: ["latest_installations"],
-    shards: GAUGE_SHARDS,
-    indexes: {
-      byScope: { eq: ["channel", "platform"], sort: ["bucket_start_ms"] },
-      byVersion: {
-        eq: ["channel", "platform", "app_version"],
-        sort: ["bucket_start_ms"],
+/** Installations whose update to a release failed, since its first failure: kept, at bucket 0. */
+const lifetimeSketches = () =>
+  defineAggregate(identityFields, {
+    key: ["identity", "bucket_start_ms"],
+    distinct: ["failed_users"],
+    shards: SKETCH_SHARDS,
+    batched: true,
+    indexes: { window },
+  });
+
+/**
+ * Update failures by what failed, and recoveries by why the crashed process
+ * exited, a row an hour. `release_id` is the failed update's target release,
+ * or empty for a failed check or an unknown target, and the recovered
+ * release for a recovery. A failure's `stage` and `reason` say where and why
+ * it failed, and `detail` what else the client knew, as the JSON array
+ * `[resource, httpStatus, originCode, transport]`. A recovery's stage is
+ * `launch` and its reason the exit reason, with an empty detail. Every index
+ * is in key order, so its counters stay blind increments.
+ */
+const insightsFailures = (retention: BucketRetention) =>
+  defineAggregate(
+    {
+      platform: { type: "string", maxLength: 16 },
+      channel: { type: "string" },
+      bucket_start_ms: { type: "integer" },
+      release_id: { type: "string", maxLength: 36 },
+      stage: { type: "string", maxLength: 16 },
+      reason: { type: "string", maxLength: 64 },
+      detail: { type: "string", maxLength: 160 },
+    },
+    {
+      key: [
+        "platform",
+        "channel",
+        "bucket_start_ms",
+        "release_id",
+        "stage",
+        "reason",
+        "detail",
+      ],
+      counters: ["events"],
+      shards: COUNTER_SHARDS,
+      batched: true,
+      indexes: {
+        byScope: { eq: ["platform", "channel"], sort: ["bucket_start_ms"] },
       },
+      retention,
     },
-  },
-);
-
-/** Latest events by the bundle they came from or went to. */
-const insightsLatestByBundle = defineAggregate(
-  {
-    platform: { type: "string", maxLength: 16 },
-    channel: { type: "string" },
-    bundle_field: { type: "string", maxLength: 16 },
-    bundle_id: { type: "string", maxLength: 36 },
-    type: { type: "string", maxLength: 32 },
-    bucket_start_ms: { type: "integer" },
-  },
-  {
-    key: [
-      "platform",
-      "channel",
-      "bundle_field",
-      "bundle_id",
-      "type",
-      "bucket_start_ms",
-    ],
-    gauges: ["installations"],
-    shards: GAUGE_SHARDS,
-    indexes: {
-      byBundle: {
-        eq: ["platform", "channel", "bundle_field", "bundle_id", "type"],
-        sort: ["bucket_start_ms"],
+  );
+
+/** Installations counted in the UTC day of their latest event, so reads sum whole UTC days. */
+const insightsDistribution = (retention: BucketRetention) =>
+  defineAggregate(
+    {
+      channel: { type: "string" },
+      platform: { type: "string", maxLength: 16 },
+      app_version: { type: "string" },
+      release_id: { type: "string", maxLength: 36 },
+      bucket_start_ms: { type: "integer" },
+    },
+    {
+      key: [
+        "channel",
+        "platform",
+        "app_version",
+        "release_id",
+        "bucket_start_ms",
+      ],
+      gauges: ["latest_installations"],
+      shards: GAUGE_SHARDS,
+      batched: true,
+      indexes: {
+        byScope: { eq: ["channel", "platform"], sort: ["bucket_start_ms"] },
+        byVersion: {
+          eq: ["channel", "platform", "app_version"],
+          sort: ["bucket_start_ms"],
+        },
+      },
+      retention,
+    },
+  );
+
+/** Latest events by the bundle they came from or went to, bucketed like the distribution. */
+const insightsLatestByBundle = (retention: BucketRetention) =>
+  defineAggregate(
+    {
+      platform: { type: "string", maxLength: 16 },
+      channel: { type: "string" },
+      bundle_field: { type: "string", maxLength: 16 },
+      bundle_id: { type: "string", maxLength: 36 },
+      type: { type: "string", maxLength: 32 },
+      bucket_start_ms: { type: "integer" },
+    },
+    {
+      key: [
+        "platform",
+        "channel",
+        "bundle_field",
+        "bundle_id",
+        "type",
+        "bucket_start_ms",
+      ],
+      gauges: ["installations"],
+      shards: GAUGE_SHARDS,
+      batched: true,
+      indexes: {
+        byBundle: {
+          eq: ["platform", "channel", "bundle_field", "bundle_id", "type"],
+          sort: ["bucket_start_ms"],
+        },
       },
+      retention,
     },
-  },
-);
+  );
 
 /**
- * Events by outcome and the bundle a bundle filter matches, a row an hour;
- * and every event, a row a UTC day (`DAILY_EVENTS`). Bundle counts sum the
- * hourly rows, and event lists read either to skip days without events.
+ * Stored events by outcome and the bundle a bundle filter matches, a row an
+ * hour, which a failed check has none of; and every stored event, a row a UTC
+ * day (`DAILY_EVENTS`). Bundle counts sum the hourly rows, and event lists
+ * read either to skip days without events.
  */
-const insightsOutcomes = defineAggregate(
-  {
-    platform: { type: "string", maxLength: 16 },
-    channel: { type: "string" },
-    type: { type: "string", maxLength: 32 },
-    bundle_ref: { type: "string", maxLength: 41 },
-    bucket_start_ms: { type: "integer" },
-  },
-  {
-    key: ["platform", "channel", "type", "bundle_ref", "bucket_start_ms"],
-    counters: ["events"],
-    shards: COUNTER_SHARDS,
-    indexes: {
-      byRef: {
-        eq: ["platform", "channel", "type", "bundle_ref"],
-        sort: ["bucket_start_ms"],
+const insightsOutcomes = (retention: BucketRetention) =>
+  defineAggregate(
+    {
+      platform: { type: "string", maxLength: 16 },
+      channel: { type: "string" },
+      type: { type: "string", maxLength: 32 },
+      bundle_ref: { type: "string", maxLength: 41 },
+      bucket_start_ms: { type: "integer" },
+    },
+    {
+      key: ["platform", "channel", "type", "bundle_ref", "bucket_start_ms"],
+      counters: ["events"],
+      shards: COUNTER_SHARDS,
+      batched: true,
+      indexes: {
+        byRef: {
+          eq: ["platform", "channel", "type", "bundle_ref"],
+          sort: ["bucket_start_ms"],
+        },
       },
+      // The per-day rows too: they count raw events, which keep the raw period.
+      retention,
     },
-  },
-);
+  );
 
 /**
- * The `insights_outcomes` identity that counts every event, for the global
- * event list. Its bucket is a UTC day, not an hour. Every event's platform
- * is ios or android, so no outcome row of a bundle filter shares it.
+ * The `insights_outcomes` identity that counts every stored event, for the
+ * global event list. Its bucket is a UTC day, not an hour. Every event's
+ * platform is ios or android, so no outcome row of a bundle filter shares it.
  */
 export const DAILY_EVENTS = {
   platform: "*",
@@ -216,14 +374,36 @@ export const DAILY_EVENTS = {
   bundle_ref: "",
 } as const;
 
-export const insightsSchema = {
-  bundle_events: bundleEvents,
-  bundle_event_heads: bundleEventHeads,
-  insights_overview: insightsOverview,
-  insights_sketches: insightsSketches,
-  insights_distribution: insightsDistribution,
-  insights_latest_by_bundle: insightsLatestByBundle,
-  insights_outcomes: insightsOutcomes,
-} as const;
+/**
+ * Insights' tables, each expiring after its period. The periods are values
+ * the engine applies at runtime; the tables and indexes are the same for
+ * any periods.
+ */
+export const createInsightsSchema = ({
+  rawDays,
+  dailyDays,
+}: InsightsRetention = DEFAULT_INSIGHTS_RETENTION) => {
+  const hourly = bucketRetention(rawDays);
+  const daily = bucketRetention(dailyDays);
+  return {
+    bundle_events: bundleEvents(rawDays),
+    bundle_event_heads: bundleEventHeads(dailyDays),
+    /** Hourly counters and sketches: the raw period. */
+    insights_overview: counters(hourly),
+    insights_sketches: sketches(hourly),
+    /** Daily counters and sketches: the daily period. */
+    insights_overview_daily: counters(daily),
+    insights_sketches_daily: sketches(daily),
+    /** A release's counters since its first event, and its failed installations: kept. */
+    insights_overview_lifetime: counters(),
+    insights_sketches_lifetime: lifetimeSketches(),
+    insights_distribution: insightsDistribution(daily),
+    insights_latest_by_bundle: insightsLatestByBundle(daily),
+    insights_outcomes: insightsOutcomes(hourly),
+    insights_failures: insightsFailures(hourly),
+  } as const;
+};
+
+export const insightsSchema = createInsightsSchema();
 
 export type InsightsSchema = typeof insightsSchema;

package/src/plugins/insights/testing/expectInsightsIndex.spec.ts

@@ -0,0 +1,42 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { expectInsightsIndex } from "./expectInsightsIndex";
+
+afterEach(() => vi.useRealTimers());
+
+describe("Insights index assertions", () => {
+  it("waits for acknowledged writes to become visible in a lagging index", async () => {
+    vi.useFakeTimers();
+    const query = vi
+      .fn()
+      .mockResolvedValueOnce([])
+      .mockResolvedValue(["report"]);
+    const result = expectInsightsIndex(query, ["report"]);
+    await vi.advanceTimersByTimeAsync(50);
+    await result;
+    expect(query).toHaveBeenCalledTimes(2);
+  });
+
+  it("propagates a native query failure even after an earlier incomplete result", async () => {
+    vi.useFakeTimers();
+    const failure = new Error("native index unavailable");
+    const query = vi.fn().mockResolvedValueOnce([]).mockRejectedValue(failure);
+    const result = expect(expectInsightsIndex(query, ["report"])).rejects.toBe(
+      failure,
+    );
+    await vi.advanceTimersByTimeAsync(50);
+    await result;
+    expect(query).toHaveBeenCalledTimes(2);
+  });
+
+  it("fails with the actual result when the bounded catch-up interval expires", async () => {
+    vi.useFakeTimers();
+    const query = vi.fn().mockResolvedValue([]);
+    const result = expect(
+      expectInsightsIndex(query, ["report"]),
+    ).rejects.toThrow();
+    await vi.advanceTimersByTimeAsync(5_000);
+    await result;
+    expect(query).toHaveBeenCalledTimes(101);
+  });
+});

package/src/plugins/insights/testing/expectInsightsIndex.ts

@@ -0,0 +1,20 @@
+import { expect } from "vitest";
+
+/** Allow committed secondary indexes to catch up; query failures still fail. */
+export const expectInsightsIndex = async <T>(
+  query: () => Promise<T>,
+  expected: T,
+): Promise<void> => {
+  const deadline = Date.now() + 5_000;
+  for (;;) {
+    // Keep native errors outside the assertion retry handler.
+    const actual = await query();
+    try {
+      expect(actual).toEqual(expected);
+      return;
+    } catch (error) {
+      if (Date.now() >= deadline) throw error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+};