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

package/src/insights/queryInput.ts

@@ -1,102 +1,142 @@
 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 !== "downloaded" &&
+      outcome !== "applied" &&
+      outcome !== "recovered" &&
+      outcome !== "unchanged"
+    ) {
+      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

@@ -1,21 +1,26 @@
-import type { RouteHandler } from "../handlerTypes";
 import {
   InsightsBadRequestError,
   InsightsPayloadTooLargeError,
-  InsightsScanLimitExceededError,
+  isDatabaseBusyError,
 } from "./errors";
 import { parseBundleEventRequest } from "./eventInput";
 import {
-  parseActiveInstallationInput,
-  parseInsightsQuery,
-  parsePagination,
-  parseSearchInput,
+  parseReportingOverviewInput,
+  parseEventPageInput,
+  parseUserInstallationPageInput,
 } from "./queryInput";
 import type { InsightsProvider } from "./types";
 
-const json = (body: unknown, status: number): Response =>
+/** Seconds a client waits before it resends a request the busy database refused. */
+const RETRY_AFTER_SECONDS = 5;
+
+const json = (
+  body: unknown,
+  status: number,
+  headers: Readonly<Record<string, string>> = {},
+): Response =>
   Response.json(body, {
-    headers: { "cache-control": "private, no-store" },
+    headers: { "cache-control": "private, no-store", ...headers },
     status,
   });
 
@@ -27,7 +32,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,16 +49,17 @@ 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,
+    // Back-pressure: a busy database has not failed the request, so the
+    // client may send it again after Retry-After. A 500 would read as a fault.
+    // The warning keeps the overload visible to whoever runs the server.
+    if (isDatabaseBusyError(error)) {
+      console.warn(
+        "[hot-updater] Insights answered 503: the database is busy.",
+        error,
       );
+      return json({ error: "Service unavailable" }, 503, {
+        "retry-after": String(RETRY_AFTER_SECONDS),
+      });
     }
     throw error;
   }
@@ -58,66 +68,112 @@ const run = async (operation: () => Promise<Response>): Promise<Response> => {
 const query = (operation: () => Promise<unknown>): Promise<Response> =>
   run(async () => json(await operation(), 200));
 
+/** Every Insights route: where it mounts, and the handler it runs. */
+export const INSIGHTS_ROUTES = [
+  {
+    access: "client",
+    method: "POST",
+    path: "/events",
+    handler: "appendBundleEvent",
+  },
+  { access: "admin", method: "GET", path: "/events", handler: "listEvents" },
+  {
+    access: "admin",
+    method: "GET",
+    path: "/overview",
+    handler: "getReportingOverview",
+  },
+  {
+    access: "admin",
+    method: "GET",
+    path: "/installations",
+    handler: "pageInstallationsByCurrentUserId",
+  },
+  {
+    access: "admin",
+    method: "GET",
+    path: "/installations/:installId/events",
+    handler: "listInstallationEvents",
+  },
+  {
+    access: "admin",
+    method: "GET",
+    path: "/installations/:installId",
+    handler: "getInstallation",
+  },
+] as const;
+
+export type InsightsRouteName = (typeof INSIGHTS_ROUTES)[number]["handler"];
+
+export type InsightsRouteHandler = (
+  params: Readonly<Record<string, string>>,
+  request: Request,
+) => Promise<Response>;
+
+/** Without the insights plugin, its routes answer 204 and say Insights is off. */
+export const insightsDisabled: InsightsRouteHandler = async () =>
+  new Response(null, {
+    headers: {
+      "cache-control": "private, no-store",
+      "x-hot-updater-insights": "disabled",
+    },
+    status: 204,
+  });
+
+/** What a server without the insights plugin logs on the first event it drops. */
+export const INSIGHTS_OFF_WARNING =
+  "[hot-updater] Insights is off, so POST /events answered 204 and stored nothing. Add insights() from @hot-updater/server/plugins/insights to plugins to record app events, or set insights: false in the app's HotUpdater.init to stop sending them. This warning prints once per server.";
+
+/**
+ * The client's `POST /events` without the insights plugin. It answers as
+ * {@link insightsDisabled} does, so apps need no change, and warns on the
+ * first event it drops, so a server that left out `insights()` says so.
+ */
+export const createDroppedEventHandler = (): InsightsRouteHandler => {
+  let warned = false;
+  return (params, request) => {
+    if (!warned) {
+      warned = true;
+      console.warn(INSIGHTS_OFF_WARNING);
+    }
+    return insightsDisabled(params, request);
+  };
+};
+
 export const createInsightsRouteHandlers = (
   provider: InsightsProvider,
-): Record<string, RouteHandler> => ({
+): Record<InsightsRouteName, InsightsRouteHandler> => ({
   appendBundleEvent: async (_params, request) =>
     run(async () => {
       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.getActiveInstallationOverview(
-        parseActiveInstallationInput(request),
+      provider.listInstallationEvents({
+        ...parseEventPageInput(request),
+        installId: requireParam(params, "installId"),
+      }),
+    ),
+  pageInstallationsByCurrentUserId: (_params, request) =>
+    query(() =>
+      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 = (
-  add: (method: string, path: string, handler: string) => void,
-): void => {
-  add("POST", "/events", "appendBundleEvent");
-};
-
-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");
-};

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/lintRules.spec.ts

@@ -0,0 +1,76 @@
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { afterAll, describe, expect, it } from "vitest";
+
+const root = path.resolve(import.meta.dirname, "../../..");
+const oxlint = path.join(root, "node_modules/.bin/oxlint");
+const dir = mkdtempSync(path.join(os.tmpdir(), "hot-updater-lint-"));
+
+afterAll(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+/**
+ * The lines `hot-updater/no-filtered-find-many` reports on `source` under the
+ * repo's oxlint config. oxlint lints only paths under its working directory,
+ * so it runs from the scratch directory.
+ */
+const reported = (file: string, source: string): number[] => {
+  writeFileSync(path.join(dir, file), source);
+  let output: string;
+  try {
+    output = execFileSync(
+      oxlint,
+      ["-c", path.join(root, ".oxlintrc.json"), "--format", "json", file],
+      { cwd: dir, encoding: "utf8" },
+    );
+  } catch (error) {
+    // oxlint exits 1 when it reports an error.
+    output = (error as { stdout: string }).stdout;
+  }
+  const { diagnostics } = JSON.parse(output) as {
+    diagnostics: {
+      code: string;
+      labels: { span: { line: number } }[];
+    }[];
+  };
+  return diagnostics
+    .filter(({ code }) => code === "hot-updater(no-filtered-find-many)")
+    .map(({ labels }) => labels[0]!.span.line);
+};
+
+const filtered = [
+  "export const a = async (db: any) =>",
+  '  (await db.findMany("t", {})).rows.filter((row: any) => row.ok);',
+  "export const b = async (db: any) => {",
+  '  const page = await db.findMany("t", {});',
+  "  return page.rows.find((row: any) => row.ok);",
+  "};",
+  "export const c = async (db: any) => {",
+  '  const { rows } = await db.findMany("t", {});',
+  "  return rows.filter(Boolean);",
+  "};",
+].join("\n");
+
+describe("hot-updater/no-filtered-find-many", () => {
+  it("reports findMany rows filtered in code", () => {
+    expect(reported("reads.ts", filtered)).toEqual([2, 5, 9]);
+  });
+
+  it("allows rows used whole, other arrays, and tests", () => {
+    expect(
+      reported(
+        "whole.ts",
+        [
+          "export const d = async (db: any) =>",
+          '  (await db.findMany("t", {})).rows.map((row: any) => row.id);',
+          "export const e = (items: number[]) => items.filter(Boolean);",
+        ].join("\n"),
+      ),
+    ).toEqual([]);
+    expect(reported("reads.spec.ts", filtered)).toEqual([]);
+  });
+});