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

package/src/analytics/domain.ts

@@ -0,0 +1,139 @@
+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";
+      readonly fromBundleId: string;
+      readonly updateStrategy: "fingerprint" | "appVersion";
+    })
+  | (CreateBundleEventRequestBase & {
+      readonly type: "RECOVERED";
+      readonly fromBundleId: string;
+      readonly updateStrategy: "fingerprint" | "appVersion";
+    })
+  | (CreateBundleEventRequestBase & {
+      readonly type: "RELEASE_ADOPTED";
+      readonly fromBundleId: string;
+      readonly updateStrategy: "fingerprint" | "appVersion";
+    })
+  | (CreateBundleEventRequestBase & {
+      readonly type: "UNCHANGED";
+      readonly fromBundleId: null;
+      readonly updateStrategy: null;
+    });
+
+export type BundleEventSummary = {
+  readonly installed: number;
+  readonly recovered: number;
+};
+
+export type BundleEventSummaryByBundle = BundleEventSummary & {
+  readonly bundleId: string;
+};
+
+export type BundleEventAnalyticsWindow = "24h" | "7d" | "30d" | "all";
+export type ActiveInstallationWindow = "24h" | "7d" | "30d";
+
+export type InstallationSearchRow = {
+  readonly installId: string;
+  readonly username: string | null;
+  readonly userId: string | null;
+  readonly lastKnownBundleId: string;
+  readonly latestStatus:
+    | "UPDATE_APPLIED"
+    | "RECOVERED"
+    | "RELEASE_ADOPTED"
+    | "UNCHANGED";
+  readonly platform: "ios" | "android";
+  readonly appVersion: string;
+  readonly channel: string;
+  readonly cohort: string;
+  readonly receivedAtMs: number;
+};
+
+export type InstallationHistoryRow = {
+  readonly id: string;
+  readonly type: "UPDATE_APPLIED" | "RECOVERED";
+  readonly fromBundleId: string;
+  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 OffsetPaginationResult<TData> = {
+  readonly data: readonly TData[];
+  readonly pagination: {
+    readonly total: number;
+    readonly limit: number;
+    readonly offset: number;
+  };
+};
+
+export type AnalyticsSeriesPoint = {
+  readonly bucketStartMs: number;
+  readonly value: number;
+};
+
+export type AnalyticsCohortPoint = {
+  readonly cohort: string;
+  readonly value: number;
+};
+
+export type BundleEventAnalyticsResult = {
+  readonly summary: BundleEventSummary;
+  readonly series: {
+    readonly installed: readonly AnalyticsSeriesPoint[];
+    readonly recovered: readonly AnalyticsSeriesPoint[];
+  };
+  readonly cohorts: {
+    readonly installed: readonly AnalyticsCohortPoint[];
+    readonly recovered: readonly AnalyticsCohortPoint[];
+  };
+  readonly recentEvents: OffsetPaginationResult<InstallationHistoryRow>;
+};
+
+export type BundleEventOverview = {
+  readonly trackedInstallations: number;
+  readonly bundles: readonly {
+    readonly bundleId: string;
+    readonly installations: number;
+  }[];
+};
+
+export type ActiveInstallationOverview = {
+  readonly asOfMs: number;
+  readonly window: ActiveInstallationWindow;
+  readonly activeInstallations: number;
+  readonly series: readonly AnalyticsSeriesPoint[];
+  readonly bundleSeries: readonly {
+    readonly bundleId: string;
+    readonly series: readonly AnalyticsSeriesPoint[];
+  }[];
+  readonly bundles: readonly {
+    readonly bundleId: string;
+    readonly installations: number;
+  }[];
+};
+
+export type ActiveInstallationInput = {
+  readonly window: ActiveInstallationWindow;
+  readonly userId?: string;
+};

package/src/analytics/errors.ts

@@ -0,0 +1,18 @@
+export class AnalyticsScanLimitExceededError extends Error {
+  constructor(readonly limit: number) {
+    super(`Analytics event scan exceeded ${limit} rows.`);
+    this.name = "AnalyticsScanLimitExceededError";
+  }
+}
+
+export class AnalyticsBadRequestError extends Error {
+  readonly name = "AnalyticsBadRequestError";
+}
+
+export class AnalyticsPayloadTooLargeError extends Error {
+  readonly name = "AnalyticsPayloadTooLargeError";
+
+  constructor(readonly maximumBytes: number) {
+    super(`Event payload exceeds ${maximumBytes} bytes`);
+  }
+}

package/src/analytics/eventInput.ts

@@ -0,0 +1,168 @@
+import type {
+  CreateBundleEventRequest,
+  CreateBundleEventRequestBase,
+} from "./domain";
+import {
+  AnalyticsBadRequestError,
+  AnalyticsPayloadTooLargeError,
+} 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 AnalyticsBadRequestError(`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 AnalyticsPayloadTooLargeError(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 AnalyticsPayloadTooLargeError(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 AnalyticsBadRequestError("Invalid event payload");
+    }
+    throw error;
+  }
+}
+
+function requireEvent(payload: unknown): CreateBundleEventRequest {
+  if (
+    !isRecord(payload) ||
+    Object.keys(payload).some((key) => !eventKeys.has(key))
+  ) {
+    throw new AnalyticsBadRequestError("Invalid event payload");
+  }
+  const platform = requireStringField(payload, "platform");
+  if (platform !== "ios" && platform !== "android") {
+    throw new AnalyticsBadRequestError("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 AnalyticsBadRequestError(
+          "Invalid event field: updateStrategy",
+        );
+      }
+      return {
+        ...base,
+        type,
+        fromBundleId: requireStringField(payload, "fromBundleId"),
+        updateStrategy,
+      };
+    }
+    case "UNCHANGED":
+      if (payload.fromBundleId !== null || payload.updateStrategy !== null) {
+        throw new AnalyticsBadRequestError("Invalid unchanged event shape");
+      }
+      return {
+        ...base,
+        type,
+        fromBundleId: null,
+        updateStrategy: null,
+      };
+    default:
+      throw new AnalyticsBadRequestError("Invalid event field: type");
+  }
+}
+
+export async function parseBundleEventRequest(
+  request: Request,
+): Promise<CreateBundleEventRequest> {
+  const payload = await parseJson(request);
+  return requireEvent(payload);
+}

package/src/analytics/persistence.ts

@@ -0,0 +1,10 @@
+import type {
+  AnalyticsScanCursor,
+  AnalyticsScanInput,
+  AnalyticsModel,
+  BundleEventRow,
+} from "@hot-updater/plugin-core";
+
+export type BundleEventPersistenceRow = BundleEventRow;
+export type AnalyticsPersistence = AnalyticsModel;
+export type { AnalyticsScanCursor, AnalyticsScanInput };

package/src/analytics/queryInput.ts

@@ -0,0 +1,102 @@
+import type {
+  ActiveInstallationInput,
+  BundleEventAnalyticsWindow,
+} from "./domain";
+import { AnalyticsBadRequestError } 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 AnalyticsQueryInput = PaginationInput & {
+  readonly window: BundleEventAnalyticsWindow;
+};
+
+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 AnalyticsBadRequestError(`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 parseAnalyticsQuery = (request: Request): AnalyticsQueryInput => {
+  const url = new URL(request.url);
+  const window = url.searchParams.get("window") ?? "24h";
+  if (
+    window !== "24h" &&
+    window !== "7d" &&
+    window !== "30d" &&
+    window !== "all"
+  ) {
+    throw new AnalyticsBadRequestError("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 AnalyticsBadRequestError("Duplicate 'window' query parameter.");
+  }
+  const window = windows[0] ?? "30d";
+  if (window !== "24h" && window !== "7d" && window !== "30d") {
+    throw new AnalyticsBadRequestError("Invalid 'window' query parameter.");
+  }
+  const userIds = url.searchParams.getAll("userId");
+  if (userIds.length > 1) {
+    throw new AnalyticsBadRequestError("Duplicate 'userId' query parameter.");
+  }
+  const userId = userIds[0];
+  if (
+    userId !== undefined &&
+    (userId.length === 0 || userId.length > MAX_USER_ID_LENGTH)
+  ) {
+    throw new AnalyticsBadRequestError("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/analytics/routes.ts

@@ -0,0 +1,123 @@
+import type { RouteHandler } from "../handlerTypes";
+import {
+  AnalyticsBadRequestError,
+  AnalyticsPayloadTooLargeError,
+  AnalyticsScanLimitExceededError,
+} from "./errors";
+import { parseBundleEventRequest } from "./eventInput";
+import {
+  parseActiveInstallationInput,
+  parseAnalyticsQuery,
+  parsePagination,
+  parseSearchInput,
+} from "./queryInput";
+import type { AnalyticsProvider } 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 AnalyticsBadRequestError(`Missing route parameter: ${key}`);
+  }
+  return value;
+};
+
+const run = async (operation: () => Promise<Response>): Promise<Response> => {
+  try {
+    return await operation();
+  } catch (error) {
+    if (error instanceof AnalyticsBadRequestError) {
+      return json({ error: error.message }, 400);
+    }
+    if (error instanceof AnalyticsPayloadTooLargeError) {
+      return json({ error: error.message }, 413);
+    }
+    if (error instanceof AnalyticsScanLimitExceededError) {
+      return json(
+        {
+          error: {
+            code: "ANALYTICS_SCAN_LIMIT_EXCEEDED",
+            limit: error.limit,
+          },
+        },
+        503,
+      );
+    }
+    throw error;
+  }
+};
+
+const query = (operation: () => Promise<unknown>): Promise<Response> =>
+  run(async () => json(await operation(), 200));
+
+export const createAnalyticsRouteHandlers = (
+  provider: AnalyticsProvider,
+): 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"))),
+  getBundleEventAnalytics: (params, request) =>
+    query(() => {
+      const input = parseAnalyticsQuery(request);
+      return provider.getBundleEventAnalytics(
+        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 registerAnalyticsClientRoutes = (
+  add: (method: string, path: string, handler: string) => void,
+): void => {
+  add("POST", "/events", "appendBundleEvent");
+};
+
+export const registerAnalyticsAdminRoutes = (
+  add: (method: string, path: string, handler: string) => void,
+): void => {
+  add("GET", "/bundles/:id/events/summary", "getBundleEventSummary");
+  add("GET", "/bundles/:id/events/analytics", "getBundleEventAnalytics");
+  add("GET", "/installations/overview", "getBundleEventOverview");
+  add("GET", "/installations/active", "getActiveInstallationOverview");
+  add("GET", "/installations", "searchInstallations");
+  add("GET", "/installations/:installId/events", "getInstallationHistory");
+};

package/src/analytics/types.ts

@@ -0,0 +1,44 @@
+import type {
+  ActiveInstallationInput,
+  ActiveInstallationOverview,
+  BundleEventAnalyticsResult,
+  BundleEventAnalyticsWindow,
+  BundleEventOverview,
+  BundleEventSummary,
+  BundleEventSummaryByBundle,
+  CreateBundleEventRequest,
+  InstallationHistoryRow,
+  InstallationSearchRow,
+  OffsetPaginationResult,
+} from "./domain";
+
+export type AnalyticsProvider = {
+  readonly mode: "bounded";
+  readonly maxMatchingRows: number;
+  appendBundleEvent(input: CreateBundleEventRequest): Promise<void>;
+  getBundleEventSummary(bundleId: string): Promise<BundleEventSummary>;
+  getBundleEventSummaries(
+    bundleIds: readonly string[],
+    window: BundleEventAnalyticsWindow,
+  ): Promise<readonly BundleEventSummaryByBundle[]>;
+  getBundleEventAnalytics(
+    bundleId: string,
+    window: BundleEventAnalyticsWindow,
+    limit: number,
+    offset: number,
+  ): Promise<BundleEventAnalyticsResult>;
+  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>>;
+};