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

package/src/insights/queryInput.ts

@@ -1,102 +1,141 @@
 import type {
-  ActiveInstallationInput,
-  BundleEventInsightsWindow,
+  ActiveInstallationWindow,
+  InsightsBundleSelection,
+  InsightsScope,
 } from "./domain";
 import { InsightsBadRequestError } from "./errors";
+import type {
+  InsightsEventPageInput,
+  InsightsUserInstallationPageInput,
+} from "./types";
 
-type IntegerBounds = {
-  readonly defaultValue: number;
-  readonly minimum: number;
-  readonly maximum?: number;
-};
+const MAX_PAGE_LIMIT = 100;
+const MAX_IDENTITY_LENGTH = 255;
+const MAX_CURSOR_LENGTH = 8 * 1_024;
 
-const EVENT_LIST_BOUNDS = {
-  defaultValue: 50,
-  maximum: 100,
-  minimum: 1,
-} as const satisfies IntegerBounds;
-const EVENT_LIST_OFFSET_BOUNDS = {
-  defaultValue: 0,
-  minimum: 0,
-} as const satisfies IntegerBounds;
-const MAX_USER_ID_LENGTH = 1_024;
+const readSingle = (url: URL, key: string): string | undefined => {
+  const values = url.searchParams.getAll(key);
+  if (values.length > 1) {
+    throw new InsightsBadRequestError(`Duplicate '${key}' query parameter.`);
+  }
+  return values[0];
+};
 
-export type PaginationInput = {
-  readonly limit: number;
-  readonly offset: number;
+const readPageLimit = (url: URL): number | undefined => {
+  const value = readSingle(url, "limit");
+  if (value === undefined) return undefined;
+  const limit = Number(value);
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_PAGE_LIMIT) {
+    throw new InsightsBadRequestError("Invalid 'limit' query parameter.");
+  }
+  return limit;
 };
 
-export type InsightsQueryInput = PaginationInput & {
-  readonly window: BundleEventInsightsWindow;
+const readCursor = (url: URL): string | undefined => {
+  const cursor = readSingle(url, "cursor");
+  if (
+    cursor !== undefined &&
+    (cursor.length === 0 || cursor.length > MAX_CURSOR_LENGTH)
+  ) {
+    throw new InsightsBadRequestError("Invalid 'cursor' query parameter.");
+  }
+  return cursor;
 };
 
-function parseInteger(url: URL, key: string, bounds: IntegerBounds): number {
-  const value = url.searchParams.get(key);
-  if (value === null) return bounds.defaultValue;
-  const parsed = Number(value);
+const readId = (
+  url: URL,
+  key: string,
+  maximumLength = MAX_IDENTITY_LENGTH,
+): string => {
+  const value = readSingle(url, key);
   if (
-    !Number.isSafeInteger(parsed) ||
-    parsed < bounds.minimum ||
-    (bounds.maximum !== undefined && parsed > bounds.maximum)
+    value === undefined ||
+    value.length === 0 ||
+    value.length > maximumLength
   ) {
     throw new InsightsBadRequestError(`Invalid '${key}' query parameter.`);
   }
-  return parsed;
-}
+  return value;
+};
+
+const readTimestamp = (url: URL, key: string): number | undefined => {
+  const raw = readSingle(url, key);
+  if (raw === undefined) return undefined;
+  const value = Number(raw);
+  if (!raw.length || !Number.isSafeInteger(value) || value < 0) {
+    throw new InsightsBadRequestError(`Invalid '${key}' query parameter.`);
+  }
+  return value;
+};
 
-export const parsePagination = (request: Request): PaginationInput => {
+const readScope = (url: URL): InsightsScope => {
+  const platform = readSingle(url, "platform");
+  if (platform !== "ios" && platform !== "android") {
+    throw new InsightsBadRequestError("Invalid 'platform' query parameter.");
+  }
+  return { platform, channel: readId(url, "channel", 1_024) };
+};
+
+export const parseEventPageInput = (
+  request: Request,
+): InsightsEventPageInput => {
   const url = new URL(request.url);
+  const bundleFields = ["bundleId", "outcome", "platform", "channel"];
+  let bundle: InsightsBundleSelection | undefined;
+  if (bundleFields.some((key) => url.searchParams.has(key))) {
+    const outcome = readSingle(url, "outcome");
+    if (
+      outcome !== "applied" &&
+      outcome !== "recovered" &&
+      outcome !== "adopted"
+    ) {
+      throw new InsightsBadRequestError("Invalid 'outcome' query parameter.");
+    }
+    bundle = {
+      ...readScope(url),
+      bundleId: readId(url, "bundleId", 1_024),
+      outcome,
+    };
+  }
   return {
-    limit: parseInteger(url, "limit", EVENT_LIST_BOUNDS),
-    offset: parseInteger(url, "offset", EVENT_LIST_OFFSET_BOUNDS),
+    beforeReceivedAtMs: readTimestamp(url, "beforeReceivedAtMs"),
+    sinceMs: readTimestamp(url, "sinceMs"),
+    cursor: readCursor(url),
+    limit: readPageLimit(url),
+    ...(bundle === undefined ? {} : { bundle }),
   };
 };
 
-export const parseInsightsQuery = (request: Request): InsightsQueryInput => {
+export const parseUserInstallationPageInput = (
+  request: Request,
+): InsightsUserInstallationPageInput => {
   const url = new URL(request.url);
-  const window = url.searchParams.get("window") ?? "24h";
-  if (
-    window !== "24h" &&
-    window !== "7d" &&
-    window !== "30d" &&
-    window !== "all"
-  ) {
-    throw new InsightsBadRequestError("Invalid 'window' query parameter.");
-  }
-  return { ...parsePagination(request), window };
+  const cursor = readCursor(url);
+  const limit = readPageLimit(url);
+  return {
+    userId: readId(url, "userId"),
+    ...(cursor === undefined ? {} : { cursor }),
+    ...(limit === undefined ? {} : { limit }),
+  };
 };
 
-export const parseActiveInstallationInput = (
+export const parseReportingOverviewInput = (
   request: Request,
-): ActiveInstallationInput => {
+): InsightsScope & {
+  readonly window: ActiveInstallationWindow;
+  readonly bundleId?: string;
+} => {
   const url = new URL(request.url);
-  const windows = url.searchParams.getAll("window");
-  if (windows.length > 1) {
-    throw new InsightsBadRequestError("Duplicate 'window' query parameter.");
-  }
-  const window = windows[0] ?? "30d";
+  const window = readSingle(url, "window") ?? "30d";
   if (window !== "24h" && window !== "7d" && window !== "30d") {
     throw new InsightsBadRequestError("Invalid 'window' query parameter.");
   }
-  const userIds = url.searchParams.getAll("userId");
-  if (userIds.length > 1) {
-    throw new InsightsBadRequestError("Duplicate 'userId' query parameter.");
-  }
-  const userId = userIds[0];
-  if (
-    userId !== undefined &&
-    (userId.length === 0 || userId.length > MAX_USER_ID_LENGTH)
-  ) {
-    throw new InsightsBadRequestError("Invalid 'userId' query parameter.");
-  }
-  return userId === undefined ? { window } : { window, userId };
+  const bundleId = readSingle(url, "bundleId");
+  return {
+    ...readScope(url),
+    window,
+    ...(bundleId === undefined
+      ? {}
+      : { bundleId: readId(url, "bundleId", 1_024) }),
+  };
 };
-
-export const parseSearchInput = (
-  request: Request,
-): PaginationInput & { readonly query: string } => ({
-  ...parsePagination(request),
-  query: new URL(request.url).searchParams.get("query")?.trim() ?? "",
-});
-
-export const parseEmptyInput = (): undefined => undefined;

package/src/insights/routes.ts

@@ -2,14 +2,12 @@ import type { RouteHandler } from "../handlerTypes";
 import {
   InsightsBadRequestError,
   InsightsPayloadTooLargeError,
-  InsightsScanLimitExceededError,
 } from "./errors";
 import { parseBundleEventRequest } from "./eventInput";
 import {
-  parseActiveInstallationInput,
-  parseInsightsQuery,
-  parsePagination,
-  parseSearchInput,
+  parseReportingOverviewInput,
+  parseEventPageInput,
+  parseUserInstallationPageInput,
 } from "./queryInput";
 import type { InsightsProvider } from "./types";
 
@@ -27,7 +25,11 @@ const requireParam = (
   if (value === undefined || value.length === 0) {
     throw new InsightsBadRequestError(`Missing route parameter: ${key}`);
   }
-  return value;
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    throw new InsightsBadRequestError(`Invalid route parameter: ${key}`);
+  }
 };
 
 const run = async (operation: () => Promise<Response>): Promise<Response> => {
@@ -40,17 +42,6 @@ const run = async (operation: () => Promise<Response>): Promise<Response> => {
     if (error instanceof InsightsPayloadTooLargeError) {
       return json({ error: error.message }, 413);
     }
-    if (error instanceof InsightsScanLimitExceededError) {
-      return json(
-        {
-          error: {
-            code: "INSIGHTS_SCAN_LIMIT_EXCEEDED",
-            limit: error.limit,
-          },
-        },
-        503,
-      );
-    }
     throw error;
   }
 };
@@ -66,43 +57,34 @@ export const createInsightsRouteHandlers = (
       await provider.appendBundleEvent(await parseBundleEventRequest(request));
       return new Response(null, { status: 204 });
     }),
-  getBundleEventSummary: (params) =>
-    query(() => provider.getBundleEventSummary(requireParam(params, "id"))),
-  getBundleEventInsights: (params, request) =>
-    query(() => {
-      const input = parseInsightsQuery(request);
-      return provider.getBundleEventInsights(
-        requireParam(params, "id"),
-        input.window,
-        input.limit,
-        input.offset,
-      );
+  getReportingOverview: (_params, request) =>
+    query(() =>
+      provider.getReportingOverview(parseReportingOverviewInput(request)),
+    ),
+  getInstallation: (params) =>
+    run(async () => {
+      const installation = await provider.getInstallation({
+        installId: requireParam(params, "installId"),
+      });
+      return installation === null
+        ? json({ error: "Installation not found" }, 404)
+        : json(installation, 200);
     }),
-  getBundleEventOverview: () => query(() => provider.getBundleEventOverview()),
-  getActiveInstallationOverview: (_params, request) =>
+  listEvents: (_params, request) =>
+    query(() => provider.listEvents(parseEventPageInput(request))),
+  listInstallationEvents: (params, request) =>
+    query(() =>
+      provider.listInstallationEvents({
+        ...parseEventPageInput(request),
+        installId: requireParam(params, "installId"),
+      }),
+    ),
+  pageInstallationsByCurrentUserId: (_params, request) =>
     query(() =>
-      provider.getActiveInstallationOverview(
-        parseActiveInstallationInput(request),
+      provider.pageInstallationsByCurrentUserId(
+        parseUserInstallationPageInput(request),
       ),
     ),
-  searchInstallations: (_params, request) =>
-    query(() => {
-      const input = parseSearchInput(request);
-      return provider.searchInstallations(
-        input.query,
-        input.limit,
-        input.offset,
-      );
-    }),
-  getInstallationHistory: (params, request) =>
-    query(() => {
-      const input = parsePagination(request);
-      return provider.getInstallationHistory(
-        requireParam(params, "installId"),
-        input.limit,
-        input.offset,
-      );
-    }),
 });
 
 export const registerInsightsClientRoutes = (
@@ -114,10 +96,9 @@ export const registerInsightsClientRoutes = (
 export const registerInsightsAdminRoutes = (
   add: (method: string, path: string, handler: string) => void,
 ): void => {
-  add("GET", "/bundles/:id/events/summary", "getBundleEventSummary");
-  add("GET", "/bundles/:id/events/insights", "getBundleEventInsights");
-  add("GET", "/installations/overview", "getBundleEventOverview");
-  add("GET", "/installations/active", "getActiveInstallationOverview");
-  add("GET", "/installations", "searchInstallations");
-  add("GET", "/installations/:installId/events", "getInstallationHistory");
+  add("GET", "/events", "listEvents");
+  add("GET", "/overview", "getReportingOverview");
+  add("GET", "/installations", "pageInstallationsByCurrentUserId");
+  add("GET", "/installations/:installId/events", "listInstallationEvents");
+  add("GET", "/installations/:installId", "getInstallation");
 };

package/src/insights/types.ts

@@ -1,44 +1,55 @@
 import type {
-  ActiveInstallationInput,
-  ActiveInstallationOverview,
-  BundleEventInsightsResult,
-  BundleEventInsightsWindow,
-  BundleEventOverview,
-  BundleEventSummary,
-  BundleEventSummaryByBundle,
+  ReportingOverview,
+  InsightsBundleSelection,
+  InsightsScope,
+  ActiveInstallationWindow,
   CreateBundleEventRequest,
+  CursorPage,
+  EventCursorPage,
+  EventHistoryRow,
   InstallationHistoryRow,
-  InstallationSearchRow,
-  OffsetPaginationResult,
+  InstallationRow,
 } from "./domain";
 
+export type InsightsEventPageInput = {
+  readonly beforeReceivedAtMs?: number;
+  readonly sinceMs?: number;
+  readonly bundle?: InsightsBundleSelection;
+  readonly cursor?: string;
+  readonly limit?: number;
+};
+
+export type InsightsInstallationEventPageInput = Omit<
+  InsightsEventPageInput,
+  "bundle"
+> & {
+  readonly installId: string;
+};
+
+export type InsightsUserInstallationPageInput = {
+  readonly userId: string;
+  readonly cursor?: string;
+  readonly limit?: number;
+};
+
 export type InsightsProvider = {
-  readonly mode: "bounded";
-  readonly maxMatchingRows: number;
   appendBundleEvent(input: CreateBundleEventRequest): Promise<void>;
-  getBundleEventSummary(bundleId: string): Promise<BundleEventSummary>;
-  getBundleEventSummaries(
-    bundleIds: readonly string[],
-    window: BundleEventInsightsWindow,
-  ): Promise<readonly BundleEventSummaryByBundle[]>;
-  getBundleEventInsights(
-    bundleId: string,
-    window: BundleEventInsightsWindow,
-    limit: number,
-    offset: number,
-  ): Promise<BundleEventInsightsResult>;
-  getBundleEventOverview(): Promise<BundleEventOverview>;
-  getActiveInstallationOverview(
-    input: ActiveInstallationInput,
-  ): Promise<ActiveInstallationOverview>;
-  searchInstallations(
-    query: string,
-    limit: number,
-    offset: number,
-  ): Promise<OffsetPaginationResult<InstallationSearchRow>>;
-  getInstallationHistory(
-    installId: string,
-    limit: number,
-    offset: number,
-  ): Promise<OffsetPaginationResult<InstallationHistoryRow>>;
+  listEvents(
+    input: InsightsEventPageInput,
+  ): Promise<EventCursorPage<EventHistoryRow>>;
+  listInstallationEvents(
+    input: InsightsInstallationEventPageInput,
+  ): Promise<EventCursorPage<InstallationHistoryRow>>;
+  getInstallation(input: {
+    readonly installId: string;
+  }): Promise<InstallationRow | null>;
+  pageInstallationsByCurrentUserId(
+    input: InsightsUserInstallationPageInput,
+  ): Promise<CursorPage<InstallationRow>>;
+  getReportingOverview(
+    input: InsightsScope & {
+      readonly window: ActiveInstallationWindow;
+      readonly bundleId?: string;
+    },
+  ): Promise<ReportingOverview>;
 };

package/src/schema/dsl-all-versions.spec.ts

@@ -4,6 +4,7 @@ import { hotUpdaterSchemaVersions } from "./index";
 import { createSettingsTable } from "./settings";
 import {
   bundlePatchesV100,
+  bundleInstallationsV100,
   bundlesV100,
   channelsV100,
   releaseCatalogsV100,
@@ -17,6 +18,7 @@ describe("versioned schema DSL", () => {
     expect(channelsV100.dsl).toBe("table");
     expect(bundlesV100.dsl).toBe("table");
     expect(bundlePatchesV100.dsl).toBe("table");
+    expect(bundleInstallationsV100.dsl).toBe("table");
     expect(releasesV100.dsl).toBe("table");
     expect(releaseCatalogsV100.dsl).toBe("table");
     expect(createSettingsTable("1.0.0").dsl).toBe("table");
@@ -27,7 +29,7 @@ describe("versioned schema DSL", () => {
     }
   });
 
-  it("registers only schema 1.0.0", () => {
+  it("registers only the initial schema 1.0.0", () => {
     expect(hotUpdaterSchemaVersions.map((item) => item.version)).toEqual([
       "1.0.0",
     ]);

package/src/schema/v1_0_0.spec.ts

@@ -7,6 +7,7 @@ import {
 } from "../db/schemaGenerators";
 import {
   bundleEventsV100,
+  bundleInstallationsV100,
   bundlePatchesV100,
   bundlesV100,
   releaseCatalogsV100,
@@ -57,7 +58,7 @@ describe("v1.0.0 Release Catalog schema", () => {
     const patchSize = bundlePatchesV100.columns.find(
       ({ ormName }) => ormName === "byte_size",
     );
-    const sql = createTableSql("postgresql").join("\n");
+    const sql = createTableSql("postgresql", "foreign-keys", v1_0_0).join("\n");
     const prisma = generatePrismaSchema("postgresql", v1_0_0);
     const drizzle = generateDrizzleSchema("postgresql", v1_0_0);
 
@@ -96,6 +97,79 @@ describe("v1.0.0 Release Catalog schema", () => {
     ).toBeUndefined();
   });
 
+  it("stores one current row per installation with the required lookup indexes", () => {
+    expect(
+      bundleInstallationsV100.columns.find(
+        ({ ormName }) => ormName === "install_id",
+      )?.primaryKey,
+    ).toBe(true);
+    expect(bundleInstallationsV100.indexes).toEqual(
+      expect.arrayContaining([
+        {
+          columns: ["user_id", "install_id"],
+          name: "bundle_installations_user_id_idx",
+        },
+        {
+          columns: ["received_at_ms"],
+          name: "bundle_installations_received_at_idx",
+        },
+      ]),
+    );
+
+    const sql = createTableSql("postgresql", "foreign-keys", v1_0_0).join("\n");
+    const prisma = generatePrismaSchema("postgresql", v1_0_0);
+    const drizzle = generateDrizzleSchema("postgresql", v1_0_0);
+    expect(sql).toContain("create table bundle_installations");
+    expect(sql).toContain(
+      'install_id varchar(255) collate "C" primary key not null',
+    );
+    expect(sql).toContain(
+      "create index bundle_installations_user_id_idx on bundle_installations(user_id, install_id)",
+    );
+    expect(sql).toContain(
+      "create index bundle_installations_received_at_idx on bundle_installations(received_at_ms)",
+    );
+    expect(sql).toContain(
+      "create index bundle_installations_bundle_idx on bundle_installations(platform, channel, to_bundle_id, received_at_ms)",
+    );
+    expect(sql).toContain(
+      "create index bundle_events_from_bundle_idx on bundle_events(type, platform, channel, from_bundle_id, received_at_ms, id)",
+    );
+    expect(prisma).toContain("initial Prisma SQL migration");
+    expect(prisma).toContain(
+      'alter table bundle_installations alter column install_id type varchar(255) collate "C"',
+    );
+    expect(prisma).toContain("model bundle_installations {");
+    expect(prisma).toContain("install_id String @db.VarChar(255) @id");
+    expect(drizzle).toContain("export const bundle_installations = pgTable(");
+    expect(drizzle).toContain(
+      'index("bundle_installations_user_id_idx").on(table.user_id, table.install_id)',
+    );
+  });
+
+  it("keeps identity indexes valid on MySQL and MSSQL", () => {
+    const mysql = createTableSql("mysql", "foreign-keys", v1_0_0).join("\n");
+    const mssql = createTableSql("mssql", "foreign-keys", v1_0_0).join("\n");
+
+    expect(mysql).toContain(
+      "install_id varchar(255) character set utf8mb4 collate utf8mb4_0900_bin not null",
+    );
+    expect(mysql).toContain("user_id varchar(255)");
+    expect(mssql).toContain("install_id nvarchar(255) not null");
+    expect(mssql).toContain("user_id nvarchar(255)");
+
+    for (const sql of [mysql, mssql]) {
+      expect(sql).toContain(
+        "create index bundle_events_install_idx on bundle_events(install_id, type, received_at_ms, id)",
+      );
+      expect(sql).toContain(
+        "create index bundle_installations_user_id_idx on bundle_installations(user_id, install_id)",
+      );
+    }
+    expect(mssql).not.toContain("install_id nvarchar(max)");
+    expect(mssql).not.toContain("user_id nvarchar(max)");
+  });
+
   it("generates nullable source and artifact relations with the intended deletion rules", () => {
     const prisma = generatePrismaSchema("postgresql", v1_0_0);
     const drizzle = generateDrizzleSchema("postgresql", v1_0_0);
@@ -111,7 +185,7 @@ describe("v1.0.0 Release Catalog schema", () => {
   });
 
   it("creates both projection tables and their constraints from empty", () => {
-    const sql = createTableSql("postgresql").join("\n");
+    const sql = createTableSql("postgresql", "foreign-keys", v1_0_0).join("\n");
 
     expect(sql).toContain("create table releases");
     expect(sql).toContain("create table release_catalogs");
@@ -124,7 +198,7 @@ describe("v1.0.0 Release Catalog schema", () => {
   });
 
   it("uses byte-bounded MySQL catalog keys", () => {
-    const sql = createTableSql("mysql").join("\n");
+    const sql = createTableSql("mysql", "foreign-keys", v1_0_0).join("\n");
 
     expect(sql).toContain(
       "scope_key varchar(2048) character set ascii collate ascii_bin",