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

package/src/db/fixedMigratorMongo.spec.ts

@@ -2,6 +2,7 @@ import { MongoClient } from "mongodb";
 import { describe, expect, it, vi } from "vitest";
 
 import { createInMemoryDatabasePlugin } from "../../../test-utils/test/inMemoryDatabasePlugin";
+import { HOT_UPDATER_SCHEMA_VERSION } from "../schema/types";
 import { createDatabasePluginCore } from "./databasePluginCore";
 import { createMongoMigrator } from "./fixedMigrator";
 import { createSchemaReadinessChecker } from "./schemaReadiness";
@@ -29,7 +30,7 @@ function createSettingsMongoClient(
 }
 
 describe("MongoDB migration", () => {
-  it("creates schema 1.0.0 from an empty database", async () => {
+  it("creates the current schema from an empty database", async () => {
     const settings = new Map<string, unknown>();
     const settingsCollection = {
       find: ({ key }: { readonly key: string }) => ({
@@ -50,7 +51,7 @@ describe("MongoDB migration", () => {
     const modelCollection = {
       find: () => ({ toArray: async () => [] }),
       listIndexes: () => ({ toArray: async () => [] }),
-      createIndex: async () => "created",
+      createIndex: vi.fn(async () => "created"),
     };
     const command = vi.fn(
       async (_input: Record<string, unknown>): Promise<void> => undefined,
@@ -76,7 +77,47 @@ describe("MongoDB migration", () => {
       { key: 1 },
       { unique: true },
     );
-    expect(settings.get("schema.core")).toBe("1.0.0");
+    expect(settings.get("schema.core")).toBe(HOT_UPDATER_SCHEMA_VERSION);
+    expect(modelCollection.createIndex).toHaveBeenCalledWith(
+      { install_id: 1 },
+      {
+        name: "bundle_installations_install_id_idx",
+        unique: true,
+        collation: { locale: "simple" },
+      },
+    );
+    expect(modelCollection.createIndex).toHaveBeenCalledWith(
+      {
+        type: 1,
+        platform: 1,
+        channel: 1,
+        from_bundle_id: 1,
+        received_at_ms: 1,
+        id: 1,
+      },
+      {
+        name: "bundle_events_from_bundle_idx",
+        collation: { locale: "simple" },
+      },
+    );
+    expect(modelCollection.createIndex).toHaveBeenCalledWith(
+      {
+        type: 1,
+        platform: 1,
+        channel: 1,
+        to_bundle_id: 1,
+        received_at_ms: 1,
+        id: 1,
+      },
+      { name: "bundle_events_to_bundle_idx", collation: { locale: "simple" } },
+    );
+    expect(modelCollection.createIndex).toHaveBeenCalledWith(
+      { platform: 1, channel: 1, to_bundle_id: 1, received_at_ms: 1 },
+      {
+        name: "bundle_installations_bundle_idx",
+        collation: { locale: "simple" },
+      },
+    );
     const commands = command.mock.calls.map(([input]) => input);
     expect(commands.find(({ collMod }) => collMod === "bundles")).toMatchObject(
       {
@@ -138,24 +179,30 @@ describe("MongoDB migration", () => {
     });
   });
 
-  it("is a no-op when schema.core is already 1.0.0", async () => {
-    const client = createSettingsMongoClient({ "schema.core": "1.0.0" });
+  it("is a no-op when schema.core is current", async () => {
+    const client = createSettingsMongoClient({
+      "schema.core": HOT_UPDATER_SCHEMA_VERSION,
+    });
     const migrator = createMongoMigrator(client);
 
-    await expect(migrator.getVersion()).resolves.toBe("1.0.0");
+    await expect(migrator.getVersion()).resolves.toBe(
+      HOT_UPDATER_SCHEMA_VERSION,
+    );
     await expect(
       migrator.migrateToLatest({ mode: "from-schema" }),
     ).resolves.toMatchObject({ operations: [] });
   });
 
-  it("ignores a leftover version marker when schema.core is 1.0.0", async () => {
+  it("ignores a leftover version marker when schema.core is current", async () => {
     const client = createSettingsMongoClient({
-      "schema.core": "1.0.0",
+      "schema.core": HOT_UPDATER_SCHEMA_VERSION,
       version: "0.36.0",
     });
     const migrator = createMongoMigrator(client);
 
-    await expect(migrator.getVersion()).resolves.toBe("1.0.0");
+    await expect(migrator.getVersion()).resolves.toBe(
+      HOT_UPDATER_SCHEMA_VERSION,
+    );
     await expect(
       migrator.migrateToLatest({ mode: "from-schema" }),
     ).resolves.toMatchObject({ operations: [] });

package/src/db/fixedMigratorMongo.ts

@@ -334,7 +334,11 @@ export const createMongoMigrator = (client: MongoClient): Migrator => {
               await ensureSettingsKeyIndex();
               for (const table of hotUpdaterSchema.tables) {
                 if (table.internal) continue;
+                const isInsights =
+                  table.ormName === "bundle_events" ||
+                  table.ormName === "bundle_installations";
                 const collection = db.collection(table.ormName);
+                const collation = isInsights ? { locale: "simple" } : undefined;
                 const primaryKey = table.columns.find(
                   (column) => column.primaryKey,
                 );
@@ -344,18 +348,13 @@ export const createMongoMigrator = (client: MongoClient): Migrator => {
                   );
                 }
                 const idIndexName = `${table.ormName}_${primaryKey.ormName}_idx`;
-                const existingIndexes = await collection
-                  .listIndexes()
-                  .toArray();
-                const existingIdIndex = existingIndexes.find(
-                  ({ name }) => name === idIndexName,
-                );
-                if (existingIdIndex && existingIdIndex.unique !== true) {
-                  await collection.dropIndex(idIndexName);
-                }
                 await collection.createIndex(
                   { [primaryKey.ormName]: 1 },
-                  { name: idIndexName, unique: true },
+                  {
+                    name: idIndexName,
+                    unique: true,
+                    ...(collation ? { collation } : {}),
+                  },
                 );
                 for (const index of (table.indexes ?? []).filter((item) =>
                   schemaIndexAppliesToProvider(item, "mongodb"),
@@ -367,6 +366,7 @@ export const createMongoMigrator = (client: MongoClient): Migrator => {
                     {
                       name: index.name,
                       ...(index.unique ? { unique: true } : {}),
+                      ...(collation ? { collation } : {}),
                     },
                   );
                 }

package/src/db/index.spec.ts

@@ -415,7 +415,7 @@ describe("server/db hotUpdater (PGlite + Kysely)", async () => {
   });
 
   describe("migrator enhancements", () => {
-    it("registers only schema 1.0.0", () => {
+    it("registers only the initial schema", () => {
       expect(hotUpdaterSchemaVersions.map((schema) => schema.version)).toEqual([
         "1.0.0",
       ]);
@@ -837,6 +837,9 @@ describe("server/db hotUpdater (PGlite + Kysely)", async () => {
         bundle_events: {
           id: "event_id",
         },
+        bundle_installations: {
+          install_id: "install_id",
+        },
         bundle_patches: {
           bundle_id: "bundle_id",
           id: "patch_id",
@@ -878,6 +881,10 @@ describe("server/db hotUpdater (PGlite + Kysely)", async () => {
             findFirst: vi.fn(),
             findMany: vi.fn(),
           },
+          bundle_installations: {
+            findFirst: vi.fn(),
+            findMany: vi.fn(),
+          },
           bundle_patches: {
             findFirst: vi.fn(),
             findMany: vi.fn(),

package/src/db/schema/insightsCollation.ts

@@ -0,0 +1,21 @@
+import { bundleEventsV100, bundleInstallationsV100 } from "../../schema/v1_0_0";
+import type { ORMSQLProvider } from "../types";
+import { getSqlType, sqlColumnDefinition } from "./sql";
+
+export const getInsightsCollationSql = (
+  provider: ORMSQLProvider,
+): readonly string[] =>
+  [bundleEventsV100, bundleInstallationsV100].flatMap((table) =>
+    table.columns.flatMap((column) => {
+      const collation = column.providerCollations?.[provider];
+      if (collation === undefined) return [];
+      if (provider === "mysql") {
+        return [
+          `alter table ${table.ormName} modify column ${sqlColumnDefinition(table, { ...column, primaryKey: undefined }, provider)}`,
+        ];
+      }
+      return [
+        `alter table ${table.ormName} alter column ${column.ormName} type ${getSqlType(column.type, provider)} collate ${collation}`,
+      ];
+    }),
+  );

package/src/db/schema/sql.ts

@@ -5,6 +5,7 @@ import {
   type HotUpdaterColumnType,
   type HotUpdaterForeignKeySchema,
   type HotUpdaterTableSchema,
+  type HotUpdaterVersionedSchema,
 } from "../../schema/types";
 import type {
   MigrationOperation,
@@ -209,9 +210,10 @@ export const createTableStatement = (
 export const createForeignKeySqlStatements = (
   provider: ORMSQLProvider,
   relationMode: RelationMode = "foreign-keys",
+  schema: HotUpdaterVersionedSchema = hotUpdaterSchema,
 ): readonly string[] => {
   if (relationMode !== "foreign-keys" || provider === "sqlite") return [];
-  return hotUpdaterSchema.tables.flatMap((table) =>
+  return schema.tables.flatMap((table) =>
     (table.foreignKeys ?? []).map((foreignKey) =>
       createForeignKeySql(table, foreignKey, provider),
     ),
@@ -221,21 +223,22 @@ export const createForeignKeySqlStatements = (
 export const createTableSql = (
   provider: ORMSQLProvider,
   relationMode: RelationMode = "foreign-keys",
+  schema: HotUpdaterVersionedSchema = hotUpdaterSchema,
 ): readonly string[] => [
-  ...hotUpdaterSchema.tables.map((table) =>
+  ...schema.tables.map((table) =>
     createTableStatement(table, provider, relationMode),
   ),
-  ...hotUpdaterSchema.tables.flatMap((table) =>
+  ...schema.tables.flatMap((table) =>
     (table.indexes ?? [])
       .filter((index) => schemaIndexAppliesToProvider(index, provider))
       .map((index) => createIndexSql(table, index, provider)),
   ),
   ...(provider === "sqlite"
     ? []
-    : hotUpdaterSchema.tables.flatMap((table) =>
+    : schema.tables.flatMap((table) =>
         (table.checks ?? []).map((check) =>
           createCheckSql(table, check, provider),
         ),
       )),
-  ...createForeignKeySqlStatements(provider, relationMode),
+  ...createForeignKeySqlStatements(provider, relationMode, schema),
 ];

package/src/db/schemaGenerators.ts

@@ -7,11 +7,13 @@ import {
   type HotUpdaterTableSchema,
   type HotUpdaterVersionedSchema,
 } from "../schema/types";
+import { getInsightsCollationSql } from "./schema/insightsCollation";
 import {
   getHotUpdaterSchemaVersion,
   hotUpdaterSchema,
   schemaIndexAppliesToProvider,
 } from "./schema/registry";
+import { getSqlType } from "./schema/sql";
 import type { ORMProvider, ORMSQLProvider, SchemaGenerator } from "./types";
 import { getSQLProvider } from "./types";
 
@@ -154,19 +156,33 @@ const prismaIndexes = (
 export const generatePrismaSchema = (
   provider: ORMProvider,
   schema: HotUpdaterVersionedSchema = hotUpdaterSchema,
-) =>
-  schema.tables
-    .map((table) => {
-      const lines = [
-        ...table.columns.map((column) => prismaField(column, provider)),
-        ...prismaRelationFields(table, schema),
-        ...prismaIndexes(table, provider),
-      ];
-      return `model ${table.ormName} {\n${lines
-        .map((line) => `  ${line}`)
-        .join("\n")}\n}`;
-    })
-    .join("\n\n");
+) => {
+  const sqlProvider = getSQLProvider(provider);
+  const collationSql = sqlProvider ? getInsightsCollationSql(sqlProvider) : [];
+  const header =
+    collationSql.length === 0
+      ? ""
+      : [
+          "// Apply these statements in the initial Prisma SQL migration to preserve exact Insights identities and cursors:",
+          ...collationSql.map((statement) => `// ${statement};`),
+          "",
+        ].join("\n");
+  return (
+    header +
+    schema.tables
+      .map((table) => {
+        const lines = [
+          ...table.columns.map((column) => prismaField(column, provider)),
+          ...prismaRelationFields(table, schema),
+          ...prismaIndexes(table, provider),
+        ];
+        return `model ${table.ormName} {\n${lines
+          .map((line) => `  ${line}`)
+          .join("\n")}\n}`;
+      })
+      .join("\n\n")
+  );
+};
 
 const drizzleImportSource = (provider: ORMSQLProvider) =>
   provider === "sqlite"
@@ -186,6 +202,18 @@ const drizzleColumnFn = (
   column: HotUpdaterColumnSchema,
   provider: ORMSQLProvider,
 ): { code: string; imports: readonly string[] } => {
+  const collation = column.providerCollations?.[provider];
+  if (collation !== undefined) {
+    const charset =
+      provider === "mysql"
+        ? ` character set ${collation === "ascii_bin" ? "ascii" : "utf8mb4"}`
+        : "";
+    const dataType = `${getSqlType(column.type, provider)}${charset} collate ${collation}`;
+    return {
+      code: `customType<{ data: string }>({ dataType: () => ${literal(dataType)} })(${literal(column.ormName)})`,
+      imports: ["customType"],
+    };
+  }
   if (provider === "sqlite") {
     if (column.type === "bool") {
       return {

package/src/db/types.spec.ts

@@ -22,9 +22,16 @@ describe("isDatabasePlugin", () => {
         bundles: { ...plugin.models.bundles, findMany: null },
       },
     };
-    const missingAnalytics = {
+    const missingInsights = {
       ...plugin,
-      models: { ...plugin.models, analytics: undefined },
+      models: { ...plugin.models, insights: undefined },
+    };
+    const malformedInsights = {
+      ...plugin,
+      models: {
+        ...plugin.models,
+        insights: { ...plugin.models.insights, listEvents: null },
+      },
     };
     const malformedChannels = {
       ...plugin,
@@ -47,7 +54,8 @@ describe("isDatabasePlugin", () => {
 
     expect(isDatabasePlugin(factory)).toBe(false);
     expect(isDatabasePlugin(malformedBundles)).toBe(false);
-    expect(isDatabasePlugin(missingAnalytics)).toBe(false);
+    expect(isDatabasePlugin(missingInsights)).toBe(false);
+    expect(isDatabasePlugin(malformedInsights)).toBe(false);
     expect(isDatabasePlugin(malformedChannels)).toBe(false);
     expect(isDatabasePlugin(malformedApiKeys)).toBe(false);
     expect(isDatabasePlugin(malformedDispose)).toBe(false);

package/src/db/types.ts

@@ -123,13 +123,19 @@ export function isDatabasePlugin(plugin: unknown): plugin is DatabasePlugin {
     typeof plugin.models.channels.list === "function" &&
     "delete" in plugin.models.channels &&
     typeof plugin.models.channels.delete === "function" &&
-    "analytics" in plugin.models &&
-    typeof plugin.models.analytics === "object" &&
-    plugin.models.analytics !== null &&
-    "append" in plugin.models.analytics &&
-    typeof plugin.models.analytics.append === "function" &&
-    "scan" in plugin.models.analytics &&
-    typeof plugin.models.analytics.scan === "function" &&
+    "insights" in plugin.models &&
+    typeof plugin.models.insights === "object" &&
+    plugin.models.insights !== null &&
+    "record" in plugin.models.insights &&
+    typeof plugin.models.insights.record === "function" &&
+    "listEvents" in plugin.models.insights &&
+    typeof plugin.models.insights.listEvents === "function" &&
+    "findInstallations" in plugin.models.insights &&
+    typeof plugin.models.insights.findInstallations === "function" &&
+    "countEvents" in plugin.models.insights &&
+    typeof plugin.models.insights.countEvents === "function" &&
+    "countInstallations" in plugin.models.insights &&
+    typeof plugin.models.insights.countInstallations === "function" &&
     "apiKeys" in plugin.models &&
     typeof plugin.models.apiKeys === "object" &&
     plugin.models.apiKeys !== null &&

package/src/handler-standalone.integration.spec.ts

@@ -156,7 +156,7 @@ const commitTestRelease = async (
 };
 
 describe("Handler <-> Standalone Repository Integration", () => {
-  it("uses Standalone for bundle management and the server database for Analytics", async () => {
+  it("uses Standalone for bundle management and the server database for Insights", async () => {
     const bundleId = uuidv7();
     const installId = "standalone-install";
     await createStandaloneClient().insertBundle(
@@ -186,15 +186,13 @@ describe("Handler <-> Standalone Repository Integration", () => {
         }),
       }),
     );
-    const overview = await api.handlers.admin(
-      new Request(`${baseUrl}/installations/overview`),
-    );
+    const events = await api.handlers.admin(new Request(`${baseUrl}/events`));
 
     expect(ingestion.status).toBe(204);
-    expect(overview.status).toBe(200);
-    await expect(overview.json()).resolves.toEqual({
-      bundles: [{ bundleId, installations: 1 }],
-      trackedInstallations: 1,
+    expect(events.status).toBe(200);
+    await expect(events.json()).resolves.toMatchObject({
+      data: [{ installId, toBundleId: bundleId, type: "UPDATE_APPLIED" }],
+      nextCursor: null,
     });
   });
 

package/src/handler.ts

@@ -1,9 +1,3 @@
-import {
-  createAnalyticsRouteHandlers,
-  registerAnalyticsAdminRoutes,
-  registerAnalyticsClientRoutes,
-} from "./analytics/routes";
-import type { AnalyticsProvider } from "./analytics/types";
 import { createBundleRouteHandlers } from "./handlerBundleRoutes";
 import { HandlerBadRequestError } from "./handlerErrors";
 import { createReleaseCatalogRouteHandlers } from "./handlerReleaseCatalogRoutes";
@@ -15,6 +9,12 @@ import type {
   RouteHandler,
 } from "./handlerTypes";
 import { createVersionRouteHandlers } from "./handlerVersionRoutes";
+import {
+  createInsightsRouteHandlers,
+  registerInsightsAdminRoutes,
+  registerInsightsClientRoutes,
+} from "./insights/routes";
+import type { InsightsProvider } from "./insights/types";
 import { addRoute, createRouter, findRoute } from "./internalRouter";
 
 export type {
@@ -142,7 +142,7 @@ export function createHandlers(api: HandlerAPI): HotUpdaterHandlers {
 
 export function createHotUpdaterHandlers(
   api: HandlerAPI,
-  analytics?: AnalyticsProvider,
+  insights?: InsightsProvider,
   apiKeyAuth?: {
     readonly authenticate: (request: Request) => Promise<boolean>;
     readonly headerName: string;
@@ -157,7 +157,7 @@ export function createHotUpdaterHandlers(
     ...createReleaseCatalogRouteHandlers(apiKeyAuth?.headerName),
     ...createReleaseManagementRouteHandlers(),
     ...createBundleRouteHandlers(),
-    ...(analytics === undefined ? {} : createAnalyticsRouteHandlers(analytics)),
+    ...(insights === undefined ? {} : createInsightsRouteHandlers(insights)),
     ...(downloadStorageObject === undefined
       ? {}
       : {
@@ -196,8 +196,8 @@ export function createHotUpdaterHandlers(
     "/artifacts/:targetBundleId/from/:currentBundleId",
     "artifact",
   );
-  if (analytics !== undefined) {
-    registerAnalyticsClientRoutes(addClientRoute);
+  if (insights !== undefined) {
+    registerInsightsClientRoutes(addClientRoute);
   }
 
   const adminRouter = createRouter<string>();
@@ -224,8 +224,8 @@ export function createHotUpdaterHandlers(
   addAdminRoute("POST", "/bundles", "createBundles");
   addAdminRoute("PATCH", "/bundles/:id", "updateBundle");
   addAdminRoute("DELETE", "/bundles/:id", "deleteBundle");
-  if (analytics !== undefined) {
-    registerAnalyticsAdminRoutes(addAdminRoute);
+  if (insights !== undefined) {
+    registerInsightsAdminRoutes(addAdminRoute);
   }
 
   return Object.freeze({

package/src/index.ts

@@ -4,9 +4,9 @@ export type {
   HotUpdaterHandler,
   HotUpdaterHandlers,
 } from "./handler";
-export { createAnalyticsProvider } from "./analytics/bounded/provider";
-export type * from "./analytics/domain";
-export type { AnalyticsProvider } from "./analytics/types";
+export { createInsightsProvider } from "./insights/provider";
+export type * from "./insights/domain";
+export type * from "./insights/types";
 export {
   API_KEY_HEADER_NAME,
   createApiKey,

package/src/insights/domain.ts

@@ -0,0 +1,103 @@
+export type CreateBundleEventRequestBase = {
+  readonly installId: string;
+  readonly toBundleId: string;
+  readonly userId?: string;
+  readonly username?: string;
+  readonly platform: "ios" | "android";
+  readonly appVersion: string;
+  readonly channel: string;
+  readonly cohort: string;
+  readonly fingerprintHash: string | null;
+  readonly sdkVersion?: string | null;
+  readonly fromReleaseId: string | null;
+  readonly toReleaseId: string | null;
+};
+
+export type CreateBundleEventRequest =
+  | (CreateBundleEventRequestBase & {
+      readonly type: "UPDATE_APPLIED" | "RECOVERED" | "RELEASE_ADOPTED";
+      readonly fromBundleId: string;
+      readonly updateStrategy: "fingerprint" | "appVersion";
+    })
+  | (CreateBundleEventRequestBase & {
+      readonly type: "UNCHANGED";
+      readonly fromBundleId: null;
+      readonly updateStrategy: null;
+    });
+
+export type ActiveInstallationWindow = "24h" | "7d" | "30d";
+
+export type EventHistoryRow = {
+  readonly id: string;
+  readonly installId: string;
+  readonly type:
+    | "UPDATE_APPLIED"
+    | "RECOVERED"
+    | "RELEASE_ADOPTED"
+    | "UNCHANGED";
+  readonly fromBundleId: string | null;
+  readonly toBundleId: string;
+  readonly username: string | null;
+  readonly userId: string | null;
+  readonly platform: "ios" | "android";
+  readonly appVersion: string;
+  readonly channel: string;
+  readonly cohort: string;
+  readonly receivedAtMs: number;
+};
+
+export type InstallationHistoryRow = EventHistoryRow & {
+  readonly type: "UPDATE_APPLIED" | "RECOVERED";
+  readonly fromBundleId: string;
+};
+
+export type InstallationRow = {
+  readonly installId: string;
+  readonly username: string | null;
+  readonly userId: string | null;
+  readonly lastKnownBundleId: string;
+  readonly latestStatus: EventHistoryRow["type"];
+  readonly platform: "ios" | "android";
+  readonly appVersion: string;
+  readonly channel: string;
+  readonly cohort: string;
+  readonly receivedAtMs: number;
+};
+
+export type CursorPage<T> = {
+  readonly data: readonly T[];
+  readonly nextCursor: string | null;
+};
+
+export type EventCursorPage<T extends EventHistoryRow> = CursorPage<T> & {
+  readonly beforeReceivedAtMs: number;
+};
+
+export type InsightsScope = {
+  readonly platform: "ios" | "android";
+  readonly channel: string;
+};
+
+export type InsightsBundleSelection = InsightsScope & {
+  readonly bundleId: string;
+  readonly outcome: "applied" | "recovered" | "adopted";
+};
+
+export type InsightsCountMeasurement = {
+  readonly count: number;
+  readonly measuredAtMs: number;
+};
+
+export type ReportingOverview = InsightsScope & {
+  readonly window: ActiveInstallationWindow;
+  readonly sinceMs: number;
+  readonly beforeReceivedAtMs: number;
+  readonly reportingInstallations: InsightsCountMeasurement;
+  readonly bundle?: {
+    readonly bundleId: string;
+    readonly reportingInstallations: InsightsCountMeasurement;
+    readonly appliedReports: InsightsCountMeasurement;
+    readonly recoveredReports: InsightsCountMeasurement;
+    readonly adoptedReports: InsightsCountMeasurement;
+  };
+};

package/src/insights/errors.ts

@@ -0,0 +1,11 @@
+export class InsightsBadRequestError extends Error {
+  readonly name = "InsightsBadRequestError";
+}
+
+export class InsightsPayloadTooLargeError extends Error {
+  readonly name = "InsightsPayloadTooLargeError";
+
+  constructor(readonly maximumBytes: number) {
+    super(`Event payload exceeds ${maximumBytes} bytes`);
+  }
+}