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

package/src/{analytics → insights}/eventInput.ts

@@ -1,13 +1,16 @@
+import { createUUIDv7, type BundleEventRow } from "@hot-updater/plugin-core";
+
 import type {
   CreateBundleEventRequest,
   CreateBundleEventRequestBase,
 } from "./domain";
 import {
-  AnalyticsBadRequestError,
-  AnalyticsPayloadTooLargeError,
+  InsightsBadRequestError,
+  InsightsPayloadTooLargeError,
 } from "./errors";
 
 const MAX_EVENT_STRING_LENGTH = 1_024;
+const MAX_IDENTITY_LENGTH = 255;
 export const EVENT_BODY_MAX_BYTES = 16 * 1_024;
 
 const eventKeys = new Set([
@@ -40,9 +43,12 @@ function requireStringField(
   if (
     typeof value !== "string" ||
     value.length === 0 ||
-    value.length > MAX_EVENT_STRING_LENGTH
+    value.length > MAX_EVENT_STRING_LENGTH ||
+    new TextDecoder("utf-8", { ignoreBOM: true }).decode(
+      new TextEncoder().encode(value),
+    ) !== value
   ) {
-    throw new AnalyticsBadRequestError(`Invalid event field: ${key}`);
+    throw new InsightsBadRequestError(`Invalid event field: ${key}`);
   }
   return value;
 }
@@ -55,6 +61,17 @@ function requireNullableStringField(
   return requireStringField(payload, key);
 }
 
+function requireIdentityField(
+  payload: Readonly<Record<string, unknown>>,
+  key: "installId" | "userId",
+): string {
+  const value = requireStringField(payload, key);
+  if (value.length > MAX_IDENTITY_LENGTH) {
+    throw new InsightsBadRequestError(`Invalid event field: ${key}`);
+  }
+  return value;
+}
+
 async function readBoundedText(request: Request): Promise<string> {
   const contentLength = request.headers.get("content-length");
   const declaredByteLength = Number(contentLength);
@@ -63,7 +80,7 @@ async function readBoundedText(request: Request): Promise<string> {
     Number.isSafeInteger(declaredByteLength) &&
     declaredByteLength > EVENT_BODY_MAX_BYTES
   ) {
-    throw new AnalyticsPayloadTooLargeError(EVENT_BODY_MAX_BYTES);
+    throw new InsightsPayloadTooLargeError(EVENT_BODY_MAX_BYTES);
   }
   if (request.body === null) return "";
   const reader = request.body.getReader();
@@ -76,7 +93,7 @@ async function readBoundedText(request: Request): Promise<string> {
     byteLength += result.value.byteLength;
     if (byteLength > EVENT_BODY_MAX_BYTES) {
       await reader.cancel();
-      throw new AnalyticsPayloadTooLargeError(EVENT_BODY_MAX_BYTES);
+      throw new InsightsPayloadTooLargeError(EVENT_BODY_MAX_BYTES);
     }
     text += decoder.decode(result.value, { stream: true });
   }
@@ -89,7 +106,7 @@ async function parseJson(request: Request): Promise<unknown> {
     return JSON.parse(text);
   } catch (error) {
     if (error instanceof SyntaxError) {
-      throw new AnalyticsBadRequestError("Invalid event payload");
+      throw new InsightsBadRequestError("Invalid event payload");
     }
     throw error;
   }
@@ -100,18 +117,18 @@ function requireEvent(payload: unknown): CreateBundleEventRequest {
     !isRecord(payload) ||
     Object.keys(payload).some((key) => !eventKeys.has(key))
   ) {
-    throw new AnalyticsBadRequestError("Invalid event payload");
+    throw new InsightsBadRequestError("Invalid event payload");
   }
   const platform = requireStringField(payload, "platform");
   if (platform !== "ios" && platform !== "android") {
-    throw new AnalyticsBadRequestError("Invalid event field: platform");
+    throw new InsightsBadRequestError("Invalid event field: platform");
   }
   const base: CreateBundleEventRequestBase = {
-    installId: requireStringField(payload, "installId"),
+    installId: requireIdentityField(payload, "installId"),
     toBundleId: requireStringField(payload, "toBundleId"),
     ...(payload.userId === undefined
       ? {}
-      : { userId: requireStringField(payload, "userId") }),
+      : { userId: requireIdentityField(payload, "userId") }),
     ...(payload.username === undefined
       ? {}
       : { username: requireStringField(payload, "username") }),
@@ -134,7 +151,7 @@ function requireEvent(payload: unknown): CreateBundleEventRequest {
     case "RELEASE_ADOPTED": {
       const updateStrategy = requireStringField(payload, "updateStrategy");
       if (updateStrategy !== "fingerprint" && updateStrategy !== "appVersion") {
-        throw new AnalyticsBadRequestError(
+        throw new InsightsBadRequestError(
           "Invalid event field: updateStrategy",
         );
       }
@@ -147,7 +164,7 @@ function requireEvent(payload: unknown): CreateBundleEventRequest {
     }
     case "UNCHANGED":
       if (payload.fromBundleId !== null || payload.updateStrategy !== null) {
-        throw new AnalyticsBadRequestError("Invalid unchanged event shape");
+        throw new InsightsBadRequestError("Invalid unchanged event shape");
       }
       return {
         ...base,
@@ -156,7 +173,7 @@ function requireEvent(payload: unknown): CreateBundleEventRequest {
         updateStrategy: null,
       };
     default:
-      throw new AnalyticsBadRequestError("Invalid event field: type");
+      throw new InsightsBadRequestError("Invalid event field: type");
   }
 }
 
@@ -166,3 +183,43 @@ export async function parseBundleEventRequest(
   const payload = await parseJson(request);
   return requireEvent(payload);
 }
+
+export function createBundleEventRow(
+  input: CreateBundleEventRequest,
+): BundleEventRow {
+  input = requireEvent(input);
+  const base = {
+    app_version: input.appVersion,
+    channel: input.channel,
+    cohort: input.cohort,
+    fingerprint_hash: input.fingerprintHash,
+    from_release_id: input.fromReleaseId,
+    id: createUUIDv7(),
+    install_id: input.installId,
+    platform: input.platform,
+    received_at_ms: Date.now(),
+    sdk_version: input.sdkVersion ?? null,
+    to_bundle_id: input.toBundleId,
+    to_release_id: input.toReleaseId,
+    user_id: input.userId ?? null,
+    username: input.username ?? null,
+  };
+  switch (input.type) {
+    case "UPDATE_APPLIED":
+    case "RECOVERED":
+    case "RELEASE_ADOPTED":
+      return {
+        ...base,
+        from_bundle_id: input.fromBundleId,
+        type: input.type,
+        update_strategy: input.updateStrategy,
+      };
+    case "UNCHANGED":
+      return {
+        ...base,
+        from_bundle_id: null,
+        type: input.type,
+        update_strategy: null,
+      };
+  }
+}

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

@@ -0,0 +1,381 @@
+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,
+  userId: "user-1",
+  username: "Jane",
+  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("persists an event and serves the lean Insights views", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-08-12T00:00:00.000Z"));
+    const receivedAtMs = Date.now();
+    const database = createInMemoryDatabasePlugin();
+    const append = vi.spyOn(database.models.insights, "record");
+    const hotUpdater = createHotUpdater({
+      database,
+      clientAccess: { type: "public" },
+    });
+
+    const ingestion = await hotUpdater.handlers.client(eventRequest());
+    vi.advanceTimersByTime(1);
+    const events = await hotUpdater.handlers.admin(
+      new Request("https://example.com/events"),
+    );
+    const installation = await hotUpdater.handlers.admin(
+      new Request("https://example.com/installations/install-1"),
+    );
+    const matches = await hotUpdater.handlers.admin(
+      new Request("https://example.com/installations?userId=user-1"),
+    );
+    const active = await hotUpdater.handlers.admin(
+      new Request(
+        "https://example.com/overview?platform=ios&channel=production&window=24h",
+      ),
+    );
+
+    expect(ingestion.status).toBe(204);
+    expect(append).toHaveBeenCalledWith(
+      expect.objectContaining({
+        event: expect.objectContaining({
+          install_id: "install-1",
+          sdk_version: "2.0.0",
+          to_bundle_id: "bundle-1",
+          type: "UNCHANGED",
+        }),
+      }),
+    );
+    expect(events.status).toBe(200);
+    await expect(events.json()).resolves.toMatchObject({
+      data: [
+        {
+          id: expect.any(String),
+          installId: "install-1",
+          receivedAtMs,
+          type: "UNCHANGED",
+          userId: "user-1",
+          username: "Jane",
+        },
+      ],
+      nextCursor: null,
+    });
+    expect(installation.status).toBe(200);
+    await expect(installation.json()).resolves.toMatchObject({
+      installId: "install-1",
+      latestStatus: "UNCHANGED",
+      userId: "user-1",
+    });
+    expect(matches.status).toBe(200);
+    await expect(matches.json()).resolves.toMatchObject({
+      data: [{ installId: "install-1", userId: "user-1" }],
+      nextCursor: null,
+    });
+    expect(active.status).toBe(200);
+    await expect(active.json()).resolves.toEqual({
+      platform: "ios",
+      channel: "production",
+      sinceMs: Date.now() - 24 * 60 * 60 * 1_000,
+      beforeReceivedAtMs: Date.now(),
+      reportingInstallations: { count: 1, measuredAtMs: Date.now() },
+      window: "24h",
+    });
+  });
+
+  it("serves scoped bundle counts and the same half-open recovery drill-down", async () => {
+    vi.useFakeTimers();
+    const hotUpdater = createHotUpdater({
+      database: createInMemoryDatabasePlugin(),
+      clientAccess: { type: "public" },
+    });
+    const report = async (
+      receivedAtMs: number,
+      overrides: Record<string, unknown>,
+    ) => {
+      vi.setSystemTime(receivedAtMs);
+      const response = await hotUpdater.handlers.client(
+        eventRequest({ ...event, ...overrides }),
+      );
+      expect(response.status).toBe(204);
+    };
+    await report(100, {
+      type: "UPDATE_APPLIED",
+      fromBundleId: "A",
+      toBundleId: "B",
+      updateStrategy: "appVersion",
+    });
+    await report(200, {
+      type: "RECOVERED",
+      fromBundleId: "B",
+      toBundleId: "A",
+      updateStrategy: "appVersion",
+    });
+    await report(300, {
+      installId: "install-2",
+      type: "RELEASE_ADOPTED",
+      fromBundleId: "B",
+      toBundleId: "B",
+      updateStrategy: "appVersion",
+    });
+    await report(400, {
+      installId: "install-3",
+      platform: "android",
+      toBundleId: "B",
+    });
+    vi.setSystemTime(500);
+    const overview = await hotUpdater.handlers.admin(
+      new Request(
+        "https://example.com/overview?platform=ios&channel=production&window=24h&bundleId=B",
+      ),
+    );
+    expect(overview.status).toBe(200);
+    await expect(overview.json()).resolves.toMatchObject({
+      sinceMs: 0,
+      beforeReceivedAtMs: 500,
+      reportingInstallations: { count: 2 },
+      bundle: {
+        bundleId: "B",
+        reportingInstallations: { count: 1 },
+        appliedReports: { count: 1 },
+        recoveredReports: { count: 1 },
+        adoptedReports: { count: 1 },
+      },
+    });
+    const drilldown = await hotUpdater.handlers.admin(
+      new Request(
+        "https://example.com/events?platform=ios&channel=production&bundleId=B&outcome=recovered&sinceMs=200&beforeReceivedAtMs=300",
+      ),
+    );
+    await expect(drilldown.json()).resolves.toMatchObject({
+      data: [
+        {
+          type: "RECOVERED",
+          fromBundleId: "B",
+          toBundleId: "A",
+          receivedAtMs: 200,
+        },
+      ],
+      nextCursor: null,
+    });
+    const outside = await hotUpdater.handlers.admin(
+      new Request(
+        "https://example.com/events?platform=ios&channel=production&bundleId=B&outcome=recovered&sinceMs=0&beforeReceivedAtMs=200",
+      ),
+    );
+    await expect(outside.json()).resolves.toMatchObject({
+      data: [],
+      nextCursor: null,
+    });
+  });
+
+  it.each([
+    "/overview?window=24h",
+    "/overview?platform=ios&channel=production&platform=android",
+    "/events?bundleId=B",
+    "/events?platform=ios&channel=production&bundleId=B&outcome=UNCHANGED",
+    "/events?sinceMs=20&beforeReceivedAtMs=10",
+    "/installations/install-1/events?platform=ios&channel=production&bundleId=B&outcome=applied",
+  ])("rejects ambiguous or invalid Insights query %s", async (path) => {
+    const hotUpdater = createHotUpdater({
+      database: createInMemoryDatabasePlugin(),
+      clientAccess: { type: "public" },
+    });
+    expect(
+      (
+        await hotUpdater.handlers.admin(
+          new Request(`https://example.com${path}`),
+        )
+      ).status,
+    ).toBe(400);
+  });
+
+  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.listEvents({});
+
+    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/events"),
+    );
+    const adminIngestion = await hotUpdater.handlers.admin(eventRequest());
+    const adminQuery = await hotUpdater.handlers.admin(
+      new Request("https://example.com/events"),
+    );
+
+    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(["installId", "userId"] as const)(
+    "rejects a 256-character event %s",
+    async (field) => {
+      const hotUpdater = createHotUpdater({
+        database: createInMemoryDatabasePlugin(),
+        clientAccess: { type: "public" },
+      });
+
+      const response = await hotUpdater.handlers.client(
+        eventRequest({ ...event, [field]: "x".repeat(256) }),
+      );
+
+      expect(response.status).toBe(400);
+      await expect(response.json()).resolves.toEqual({
+        error: `Invalid event field: ${field}`,
+      });
+    },
+  );
+
+  it("preserves a leading Unicode BOM in exact installation and current-user IDs", async () => {
+    const hotUpdater = createHotUpdater({
+      database: createInMemoryDatabasePlugin(),
+      clientAccess: { type: "public" },
+    });
+    const installId = "\uFEFFinstall";
+    const userId = "\uFEFFuser";
+    expect(
+      (
+        await hotUpdater.handlers.client(
+          eventRequest({ ...event, installId, userId }),
+        )
+      ).status,
+    ).toBe(204);
+    const installation = await hotUpdater.handlers.admin(
+      new Request(
+        `https://example.com/installations/${encodeURIComponent(installId)}`,
+      ),
+    );
+    expect(installation.status).toBe(200);
+    await expect(installation.json()).resolves.toMatchObject({
+      installId,
+      userId,
+    });
+    const matches = await hotUpdater.handlers.admin(
+      new Request(
+        `https://example.com/installations?userId=${encodeURIComponent(userId)}`,
+      ),
+    );
+    expect(matches.status).toBe(200);
+    await expect(matches.json()).resolves.toMatchObject({
+      data: [{ installId, userId }],
+    });
+  });
+
+  it.each(["\uD800", "\uDC00"])(
+    "rejects an unmatched surrogate identity %j",
+    async (installId) => {
+      const hotUpdater = createHotUpdater({
+        database: createInMemoryDatabasePlugin(),
+        clientAccess: { type: "public" },
+      });
+      expect(
+        (
+          await hotUpdater.handlers.client(
+            eventRequest({ ...event, installId }),
+          )
+        ).status,
+      ).toBe(400);
+    },
+  );
+
+  it("rejects 256-character installation query identities", async () => {
+    const hotUpdater = createHotUpdater({
+      database: createInMemoryDatabasePlugin(),
+      clientAccess: { type: "public" },
+    });
+    const tooLong = "x".repeat(256);
+
+    const user = await hotUpdater.handlers.admin(
+      new Request(`https://example.com/installations?userId=${tooLong}`),
+    );
+    const installation = await hotUpdater.handlers.admin(
+      new Request(`https://example.com/installations/${tooLong}`),
+    );
+
+    expect(user.status).toBe(400);
+    expect(installation.status).toBe(400);
+  });
+
+  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}`,
+      });
+    },
+  );
+});