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

package/src/insights/eventInput.ts

@@ -0,0 +1,168 @@
+import type {
+  CreateBundleEventRequest,
+  CreateBundleEventRequestBase,
+} from "./domain";
+import {
+  InsightsBadRequestError,
+  InsightsPayloadTooLargeError,
+} from "./errors";
+
+const MAX_EVENT_STRING_LENGTH = 1_024;
+export const EVENT_BODY_MAX_BYTES = 16 * 1_024;
+
+const eventKeys = new Set([
+  "type",
+  "installId",
+  "toBundleId",
+  "userId",
+  "username",
+  "platform",
+  "appVersion",
+  "channel",
+  "cohort",
+  "fingerprintHash",
+  "fromBundleId",
+  "fromReleaseId",
+  "toReleaseId",
+  "updateStrategy",
+  "sdkVersion",
+]);
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function requireStringField(
+  payload: Readonly<Record<string, unknown>>,
+  key: string,
+): string {
+  const value = payload[key];
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.length > MAX_EVENT_STRING_LENGTH
+  ) {
+    throw new InsightsBadRequestError(`Invalid event field: ${key}`);
+  }
+  return value;
+}
+
+function requireNullableStringField(
+  payload: Readonly<Record<string, unknown>>,
+  key: string,
+): string | null {
+  if (payload[key] === null) return null;
+  return requireStringField(payload, key);
+}
+
+async function readBoundedText(request: Request): Promise<string> {
+  const contentLength = request.headers.get("content-length");
+  const declaredByteLength = Number(contentLength);
+  if (
+    contentLength !== null &&
+    Number.isSafeInteger(declaredByteLength) &&
+    declaredByteLength > EVENT_BODY_MAX_BYTES
+  ) {
+    throw new InsightsPayloadTooLargeError(EVENT_BODY_MAX_BYTES);
+  }
+  if (request.body === null) return "";
+  const reader = request.body.getReader();
+  const decoder = new TextDecoder();
+  let byteLength = 0;
+  let text = "";
+  while (true) {
+    const result = await reader.read();
+    if (result.done) break;
+    byteLength += result.value.byteLength;
+    if (byteLength > EVENT_BODY_MAX_BYTES) {
+      await reader.cancel();
+      throw new InsightsPayloadTooLargeError(EVENT_BODY_MAX_BYTES);
+    }
+    text += decoder.decode(result.value, { stream: true });
+  }
+  return text + decoder.decode();
+}
+
+async function parseJson(request: Request): Promise<unknown> {
+  const text = await readBoundedText(request);
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new InsightsBadRequestError("Invalid event payload");
+    }
+    throw error;
+  }
+}
+
+function requireEvent(payload: unknown): CreateBundleEventRequest {
+  if (
+    !isRecord(payload) ||
+    Object.keys(payload).some((key) => !eventKeys.has(key))
+  ) {
+    throw new InsightsBadRequestError("Invalid event payload");
+  }
+  const platform = requireStringField(payload, "platform");
+  if (platform !== "ios" && platform !== "android") {
+    throw new InsightsBadRequestError("Invalid event field: platform");
+  }
+  const base: CreateBundleEventRequestBase = {
+    installId: requireStringField(payload, "installId"),
+    toBundleId: requireStringField(payload, "toBundleId"),
+    ...(payload.userId === undefined
+      ? {}
+      : { userId: requireStringField(payload, "userId") }),
+    ...(payload.username === undefined
+      ? {}
+      : { username: requireStringField(payload, "username") }),
+    platform,
+    appVersion: requireStringField(payload, "appVersion"),
+    channel: requireStringField(payload, "channel"),
+    cohort: requireStringField(payload, "cohort"),
+    fingerprintHash: requireNullableStringField(payload, "fingerprintHash"),
+    sdkVersion:
+      payload.sdkVersion === undefined
+        ? null
+        : requireNullableStringField(payload, "sdkVersion"),
+    fromReleaseId: requireNullableStringField(payload, "fromReleaseId"),
+    toReleaseId: requireNullableStringField(payload, "toReleaseId"),
+  };
+  const type = requireStringField(payload, "type");
+  switch (type) {
+    case "UPDATE_APPLIED":
+    case "RECOVERED":
+    case "RELEASE_ADOPTED": {
+      const updateStrategy = requireStringField(payload, "updateStrategy");
+      if (updateStrategy !== "fingerprint" && updateStrategy !== "appVersion") {
+        throw new InsightsBadRequestError(
+          "Invalid event field: updateStrategy",
+        );
+      }
+      return {
+        ...base,
+        type,
+        fromBundleId: requireStringField(payload, "fromBundleId"),
+        updateStrategy,
+      };
+    }
+    case "UNCHANGED":
+      if (payload.fromBundleId !== null || payload.updateStrategy !== null) {
+        throw new InsightsBadRequestError("Invalid unchanged event shape");
+      }
+      return {
+        ...base,
+        type,
+        fromBundleId: null,
+        updateStrategy: null,
+      };
+    default:
+      throw new InsightsBadRequestError("Invalid event field: type");
+  }
+}
+
+export async function parseBundleEventRequest(
+  request: Request,
+): Promise<CreateBundleEventRequest> {
+  const payload = await parseJson(request);
+  return requireEvent(payload);
+}

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

@@ -0,0 +1,144 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createInMemoryDatabasePlugin } from "../../../test-utils/test/inMemoryDatabasePlugin";
+import { createHotUpdater } from "../index";
+import { createSchemaManagedDatabase } from "../runtime.testFixtures";
+import { HOT_UPDATER_SCHEMA_VERSION } from "../schema/types";
+
+const event = {
+  appVersion: "1.0.0",
+  channel: "production",
+  cohort: "default",
+  fingerprintHash: null,
+  fromBundleId: null,
+  fromReleaseId: null,
+  installId: "install-1",
+  platform: "ios",
+  toBundleId: "bundle-1",
+  toReleaseId: null,
+  type: "UNCHANGED",
+  updateStrategy: null,
+  sdkVersion: "2.0.0",
+} as const;
+
+const eventRequest = (body: unknown = event) =>
+  new Request("https://example.com/events", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe("createHotUpdater Insights", () => {
+  it("always persists events and serves queries without a server Insights flag", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-08-12T00:00:00.000Z"));
+    const database = createInMemoryDatabasePlugin();
+    const append = vi.spyOn(database.models.insights, "append");
+    const hotUpdater = createHotUpdater({
+      database,
+      clientAccess: { type: "public" },
+    });
+
+    const ingestion = await hotUpdater.handlers.client(eventRequest());
+    vi.advanceTimersByTime(1);
+    const overview = await hotUpdater.handlers.admin(
+      new Request("https://example.com/installations/overview"),
+    );
+
+    expect(ingestion.status).toBe(204);
+    expect(append).toHaveBeenCalledWith(
+      expect.objectContaining({
+        install_id: "install-1",
+        sdk_version: "2.0.0",
+        to_bundle_id: "bundle-1",
+        type: "UNCHANGED",
+      }),
+    );
+    expect(hotUpdater.insights).toMatchObject({
+      mode: "bounded",
+      maxMatchingRows: 50_000,
+    });
+    expect(overview.status).toBe(200);
+    await expect(overview.json()).resolves.toEqual({
+      bundles: [{ bundleId: "bundle-1", installations: 1 }],
+      trackedInstallations: 1,
+    });
+  });
+
+  it("checks the official schema before Insights reads and writes", async () => {
+    const database = createSchemaManagedDatabase(
+      "kysely",
+      HOT_UPDATER_SCHEMA_VERSION,
+    );
+    const createMigrator = vi.spyOn(database, "createMigrator");
+    const hotUpdater = createHotUpdater({
+      database,
+      clientAccess: { type: "public" },
+    });
+
+    expect((await hotUpdater.handlers.client(eventRequest())).status).toBe(204);
+    await hotUpdater.insights?.getBundleEventOverview();
+
+    expect(createMigrator).toHaveBeenCalledOnce();
+  });
+
+  it("keeps ingestion and queries on separate handler surfaces", async () => {
+    const hotUpdater = createHotUpdater({
+      database: createInMemoryDatabasePlugin(),
+      clientAccess: { type: "public" },
+    });
+
+    expect((await hotUpdater.handlers.client(eventRequest())).status).toBe(204);
+    const clientQuery = await hotUpdater.handlers.client(
+      new Request("https://example.com/installations/overview"),
+    );
+    const adminIngestion = await hotUpdater.handlers.admin(eventRequest());
+    const adminQuery = await hotUpdater.handlers.admin(
+      new Request("https://example.com/installations/overview"),
+    );
+
+    expect(clientQuery.status).toBe(404);
+    expect(adminIngestion.status).toBe(404);
+    expect(adminQuery.status).toBe(200);
+    expect(adminQuery.headers.get("cache-control")).toBe("private, no-store");
+  });
+
+  it("returns a stable client error for malformed event payloads", async () => {
+    const hotUpdater = createHotUpdater({
+      database: createInMemoryDatabasePlugin(),
+      clientAccess: { type: "public" },
+    });
+
+    const response = await hotUpdater.handlers.client(
+      eventRequest({ ...event, platform: "web" }),
+    );
+
+    expect(response.status).toBe(400);
+    await expect(response.json()).resolves.toEqual({
+      error: "Invalid event field: platform",
+    });
+  });
+
+  it.each(["fromReleaseId", "toReleaseId"] as const)(
+    "rejects an omitted %s instead of treating it as null",
+    async (field) => {
+      const hotUpdater = createHotUpdater({
+        database: createInMemoryDatabasePlugin(),
+        clientAccess: { type: "public" },
+      });
+      const payload: Record<string, unknown> = { ...event };
+      delete payload[field];
+
+      const response = await hotUpdater.handlers.client(eventRequest(payload));
+
+      expect(response.status).toBe(400);
+      await expect(response.json()).resolves.toEqual({
+        error: `Invalid event field: ${field}`,
+      });
+    },
+  );
+});

package/src/insights/persistence.ts

@@ -0,0 +1,10 @@
+import type {
+  InsightsScanCursor,
+  InsightsScanInput,
+  InsightsModel,
+  BundleEventRow,
+} from "@hot-updater/plugin-core";
+
+export type BundleEventPersistenceRow = BundleEventRow;
+export type InsightsPersistence = InsightsModel;
+export type { InsightsScanCursor, InsightsScanInput };

package/src/insights/queryInput.ts

@@ -0,0 +1,102 @@
+import type {
+  ActiveInstallationInput,
+  BundleEventInsightsWindow,
+} from "./domain";
+import { InsightsBadRequestError } from "./errors";
+
+type IntegerBounds = {
+  readonly defaultValue: number;
+  readonly minimum: number;
+  readonly maximum?: number;
+};
+
+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;
+
+export type PaginationInput = {
+  readonly limit: number;
+  readonly offset: number;
+};
+
+export type InsightsQueryInput = PaginationInput & {
+  readonly window: BundleEventInsightsWindow;
+};
+
+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);
+  if (
+    !Number.isSafeInteger(parsed) ||
+    parsed < bounds.minimum ||
+    (bounds.maximum !== undefined && parsed > bounds.maximum)
+  ) {
+    throw new InsightsBadRequestError(`Invalid '${key}' query parameter.`);
+  }
+  return parsed;
+}
+
+export const parsePagination = (request: Request): PaginationInput => {
+  const url = new URL(request.url);
+  return {
+    limit: parseInteger(url, "limit", EVENT_LIST_BOUNDS),
+    offset: parseInteger(url, "offset", EVENT_LIST_OFFSET_BOUNDS),
+  };
+};
+
+export const parseInsightsQuery = (request: Request): InsightsQueryInput => {
+  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 };
+};
+
+export const parseActiveInstallationInput = (
+  request: Request,
+): ActiveInstallationInput => {
+  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";
+  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 };
+};
+
+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

@@ -0,0 +1,123 @@
+import type { RouteHandler } from "../handlerTypes";
+import {
+  InsightsBadRequestError,
+  InsightsPayloadTooLargeError,
+  InsightsScanLimitExceededError,
+} from "./errors";
+import { parseBundleEventRequest } from "./eventInput";
+import {
+  parseActiveInstallationInput,
+  parseInsightsQuery,
+  parsePagination,
+  parseSearchInput,
+} from "./queryInput";
+import type { InsightsProvider } from "./types";
+
+const json = (body: unknown, status: number): Response =>
+  Response.json(body, {
+    headers: { "cache-control": "private, no-store" },
+    status,
+  });
+
+const requireParam = (
+  params: Readonly<Record<string, string>>,
+  key: string,
+): string => {
+  const value = params[key];
+  if (value === undefined || value.length === 0) {
+    throw new InsightsBadRequestError(`Missing route parameter: ${key}`);
+  }
+  return value;
+};
+
+const run = async (operation: () => Promise<Response>): Promise<Response> => {
+  try {
+    return await operation();
+  } catch (error) {
+    if (error instanceof InsightsBadRequestError) {
+      return json({ error: error.message }, 400);
+    }
+    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;
+  }
+};
+
+const query = (operation: () => Promise<unknown>): Promise<Response> =>
+  run(async () => json(await operation(), 200));
+
+export const createInsightsRouteHandlers = (
+  provider: InsightsProvider,
+): Record<string, RouteHandler> => ({
+  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,
+      );
+    }),
+  getBundleEventOverview: () => query(() => provider.getBundleEventOverview()),
+  getActiveInstallationOverview: (_params, request) =>
+    query(() =>
+      provider.getActiveInstallationOverview(
+        parseActiveInstallationInput(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

@@ -0,0 +1,44 @@
+import type {
+  ActiveInstallationInput,
+  ActiveInstallationOverview,
+  BundleEventInsightsResult,
+  BundleEventInsightsWindow,
+  BundleEventOverview,
+  BundleEventSummary,
+  BundleEventSummaryByBundle,
+  CreateBundleEventRequest,
+  InstallationHistoryRow,
+  InstallationSearchRow,
+  OffsetPaginationResult,
+} from "./domain";
+
+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>>;
+};

package/src/node.spec.ts

@@ -4,14 +4,12 @@ import { toNodeHandler } from "./node";
 
 describe("server node entry", () => {
   it("converts a Web Request handler to Node middleware", async () => {
-    const hotUpdater = {
-      handler: async (request: Request) =>
-        Response.json({
-          method: request.method,
-          pathname: new URL(request.url).pathname,
-        }),
-    };
-    const middleware = toNodeHandler(hotUpdater);
+    const middleware = toNodeHandler(async (request: Request) =>
+      Response.json({
+        method: request.method,
+        pathname: new URL(request.url).pathname,
+      }),
+    );
     const headers = new Map<string, string | string[]>();
     const response = {
       body: "",
@@ -23,8 +21,8 @@ describe("server node entry", () => {
       setHeader(name: string, value: string | string[]) {
         headers.set(name, value);
       },
-      send(body: string) {
-        this.body = body;
+      send(body: Uint8Array) {
+        this.body = new TextDecoder().decode(body);
       },
       end() {},
     };
@@ -47,4 +45,75 @@ describe("server node entry", () => {
       pathname: "/api/check",
     });
   });
+
+  it("uses the mount-relative URL supplied by Express", async () => {
+    const middleware = toNodeHandler(async (request: Request) =>
+      Response.json({ pathname: new URL(request.url).pathname }),
+    );
+    const response = {
+      body: "",
+      statusCode: 0,
+      status(code: number) {
+        this.statusCode = code;
+        return this;
+      },
+      setHeader() {},
+      send(body: Uint8Array) {
+        this.body = new TextDecoder().decode(body);
+      },
+      end() {},
+    };
+
+    await middleware(
+      {
+        method: "GET",
+        url: "/channels",
+        headers: { host: "example.com" },
+        protocol: "https",
+        get: (name: string) => (name === "host" ? "example.com" : undefined),
+      },
+      response,
+    );
+
+    expect(JSON.parse(response.body)).toEqual({
+      pathname: "/channels",
+    });
+  });
+
+  it("preserves binary response bytes", async () => {
+    const bytes = new Uint8Array([0x50, 0x4b, 0x03, 0x04, 0xff, 0xfe, 0x00]);
+    const middleware = toNodeHandler(
+      async () =>
+        new Response(bytes, {
+          headers: { "content-type": "application/zip" },
+        }),
+    );
+    const response = {
+      body: new Uint8Array(),
+      statusCode: 0,
+      status(code: number) {
+        this.statusCode = code;
+        return this;
+      },
+      setHeader() {},
+      send(body: Uint8Array) {
+        this.body = new Uint8Array(body);
+      },
+      end() {},
+    };
+
+    await middleware(
+      {
+        method: "GET",
+        url: "/hot-updater/storage/token/signature",
+        headers: { host: "example.com" },
+        protocol: "https",
+        get: (name: string) => (name === "host" ? "example.com" : undefined),
+      },
+      response,
+    );
+
+    expect(response.statusCode).toBe(200);
+    expect([...response.body]).toEqual([...bytes]);
+  });
 });