@hot-updater/server 1.0.0-rc.18 → 1.0.0-rc.21

package/src/plugins/insights/eventRow.ts

@@ -1,209 +0,0 @@
-import {
-  DatabasePluginInputError,
-  type DatabaseJsonObject,
-  type Platform,
-} from "@hot-updater/plugin-core";
-import { isDatabaseJsonObject } from "@hot-updater/plugin-core/internal";
-
-/** Where an update failed, and what failed; open sets, `unknown` for any other value. */
-export type BundleEventFailureStage =
-  | "check"
-  | "download"
-  | "install"
-  | "unknown";
-export type BundleEventFailureReason =
-  | "network"
-  | "http"
-  | "invalid_response"
-  | "hash_mismatch"
-  | "signature"
-  | "patch"
-  | "extract"
-  | "storage"
-  | "unknown";
-
-/** An `UPDATE_FAILED` report's failure, as stored. */
-export type BundleEventFailure = DatabaseJsonObject & {
-  readonly stage: BundleEventFailureStage;
-  readonly reason: BundleEventFailureReason;
-  /** What the client was fetching or writing. */
-  readonly resource?:
-    | "catalog"
-    | "artifact"
-    | "manifest"
-    | "file"
-    | "patch"
-    | "archive"
-    | "unknown";
-  readonly http_status?: number;
-  /** How the connection failed, when it did. */
-  readonly transport?:
-    | "timeout"
-    | "dns"
-    | "tls"
-    | "connection"
-    | "offline"
-    | "cancelled"
-    | "unknown";
-  /** The storage origin's error code, such as `ExpiredToken`. */
-  readonly origin_code?: string;
-  /** Android's `ApplicationExitInfo` reason for the process before this one. */
-  readonly previous_process_exit?: string;
-};
-
-/** Ancillary report data; queryable identity and lifecycle fields stay on the row. */
-export type DatabaseBundleEventMetadata = DatabaseJsonObject & {
-  readonly cohort: string;
-  readonly update_strategy: "fingerprint" | "appVersion" | null;
-  readonly fingerprint_hash: string | null;
-  readonly sdk_version: string | null;
-  /** `UPDATE_FAILED`: what failed. */
-  readonly failure?: BundleEventFailure;
-  /** `UPDATE_DOWNLOADED`: how the bundle arrived. */
-  readonly delivery?: "patch" | "manifest" | "archive" | "unknown";
-  /** `UPDATE_DOWNLOADED`: a patch failed and the full files came instead. */
-  readonly patch_fallback?: boolean;
-  /** `RECOVERED`: Android's `ApplicationExitInfo` reason for the crashed process. */
-  readonly previous_process_exit?: string;
-};
-
-export type BundleEventRowBase = {
-  readonly id: string;
-  readonly install_id: string;
-  readonly user_id: string | null;
-  readonly from_release_id: string | null;
-  readonly to_release_id: string | null;
-  readonly to_bundle_id: string;
-  readonly platform: Platform;
-  readonly app_version: string;
-  readonly channel: string;
-  readonly metadata: DatabaseBundleEventMetadata;
-  readonly received_at_ms: number;
-};
-
-export type BundleEventRow = BundleEventRowBase &
-  (
-    | { readonly type: "UPDATE_DOWNLOADED"; readonly from_bundle_id: string }
-    | {
-        readonly type: "UPDATE_APPLIED" | "RECOVERED";
-        readonly from_bundle_id: string;
-      }
-    /** An update that failed: `from` is the running bundle, `to` the target (for a check, the running bundle). */
-    | { readonly type: "UPDATE_FAILED"; readonly from_bundle_id: string }
-    | { readonly type: "UNCHANGED"; readonly from_bundle_id: null }
-  );
-
-const isOptional = (
-  value: Readonly<Record<string, unknown>>,
-  key: string,
-  valid: (field: unknown) => boolean,
-) => !Object.hasOwn(value, key) || valid(value[key]);
-
-const isString = (value: unknown) => typeof value === "string";
-
-/** An `UPDATE_FAILED` report's stored failure: a stage and a reason, and what else the client knew. */
-const isDatabaseBundleEventFailure = (value: unknown): boolean =>
-  isDatabaseJsonObject(value) &&
-  isString(value.stage) &&
-  isString(value.reason) &&
-  isOptional(value, "resource", isString) &&
-  isOptional(value, "http_status", (status) => Number.isSafeInteger(status)) &&
-  isOptional(value, "transport", isString) &&
-  isOptional(value, "origin_code", isString) &&
-  isOptional(value, "previous_process_exit", isString);
-
-export const isDatabaseBundleEventMetadata = (
-  value: unknown,
-): value is DatabaseBundleEventMetadata =>
-  isDatabaseJsonObject(value) &&
-  typeof value.cohort === "string" &&
-  (value.update_strategy === null ||
-    value.update_strategy === "fingerprint" ||
-    value.update_strategy === "appVersion") &&
-  (value.fingerprint_hash === null ||
-    typeof value.fingerprint_hash === "string") &&
-  (value.sdk_version === null || typeof value.sdk_version === "string") &&
-  isOptional(value, "failure", isDatabaseBundleEventFailure) &&
-  isOptional(value, "delivery", isString) &&
-  isOptional(value, "patch_fallback", (flag) => typeof flag === "boolean") &&
-  isOptional(value, "previous_process_exit", isString);
-
-export const isRecord = (
-  value: unknown,
-): value is Readonly<Record<string, unknown>> =>
-  typeof value === "object" && value !== null && !Array.isArray(value);
-
-const isIdentity = (value: unknown): value is string =>
-  typeof value === "string" && value.length > 0 && value.length <= 255;
-
-const isTextOrNull = (value: unknown) =>
-  value === null || typeof value === "string";
-
-/** Each bundle event field and what it holds. */
-const BUNDLE_EVENT_FIELDS: Readonly<
-  Record<string, (value: unknown) => boolean>
-> = {
-  id: (value) => typeof value === "string",
-  type: (value) =>
-    value === "UPDATE_DOWNLOADED" ||
-    value === "UPDATE_APPLIED" ||
-    value === "RECOVERED" ||
-    value === "UPDATE_FAILED" ||
-    value === "UNCHANGED",
-  install_id: isIdentity,
-  user_id: (value) => value === null || isIdentity(value),
-  from_bundle_id: isTextOrNull,
-  from_release_id: isTextOrNull,
-  to_release_id: isTextOrNull,
-  to_bundle_id: (value) => typeof value === "string",
-  platform: (value) => value === "ios" || value === "android",
-  app_version: (value) => typeof value === "string",
-  channel: (value) => typeof value === "string",
-  metadata: isDatabaseBundleEventMetadata,
-  received_at_ms: (value) =>
-    typeof value === "number" && Number.isSafeInteger(value) && value >= 0,
-};
-
-const updateStrategyOf = (row: Readonly<Record<string, unknown>>) =>
-  isRecord(row.metadata) ? row.metadata.update_strategy : undefined;
-
-/**
- * A movement, or a failed update, names the bundle it left and how the
- * device updates, and a failed update says what failed; an unchanged report
- * names neither.
- */
-const hasEventInvariants = (row: Readonly<Record<string, unknown>>) =>
-  ((row.type === "UPDATE_DOWNLOADED" ||
-    row.type === "UPDATE_APPLIED" ||
-    row.type === "RECOVERED" ||
-    row.type === "UPDATE_FAILED") &&
-    typeof row.from_bundle_id === "string" &&
-    (updateStrategyOf(row) === "fingerprint" ||
-      updateStrategyOf(row) === "appVersion") &&
-    (row.type !== "UPDATE_FAILED" ||
-      (isRecord(row.metadata) && isRecord(row.metadata.failure)))) ||
-  (row.type === "UNCHANGED" &&
-    row.from_bundle_id === null &&
-    updateStrategyOf(row) === null);
-
-/**
- * Throws unless `row` has exactly the bundle event fields, each of its type,
- * and the invariants of its event type: `invalid-field` for an unknown field,
- * `invalid-data` for anything else.
- */
-export const validateBundleEventFields = (row: unknown): void => {
-  if (!isRecord(row)) throw new DatabasePluginInputError("invalid-data");
-  for (const field of Object.keys(row)) {
-    if (!Object.hasOwn(BUNDLE_EVENT_FIELDS, field)) {
-      throw new DatabasePluginInputError("invalid-field");
-    }
-  }
-  for (const [field, valid] of Object.entries(BUNDLE_EVENT_FIELDS)) {
-    if (!Object.hasOwn(row, field) || !valid(row[field])) {
-      throw new DatabasePluginInputError("invalid-data");
-    }
-  }
-  if (!hasEventInvariants(row)) {
-    throw new DatabasePluginInputError("invalid-data");
-  }
-};

package/src/plugins/insights/index.ts

@@ -1,222 +0,0 @@
-import { DatabasePluginInputError } from "@hot-updater/plugin-core";
-
-import { HotUpdaterConfigError } from "../../assembly/configError";
-import { isDatabaseBusyError } from "../../database/busy";
-import type { HotUpdaterDatabase } from "../../database/database";
-import { definePlugin, type PluginEndpoint } from "../definePlugin";
-import type { BundleEventRow } from "./eventRow";
-import { createInsightsModel } from "./model";
-import type {
-  InsightsCountEventsInput,
-  InsightsCountLatestEventsInput,
-  InsightsFindLatestEventsInput,
-  InsightsGetAppUsageInput,
-  InsightsGetReleaseActivityInput,
-  InsightsListEventsInput,
-} from "./modelTypes";
-import { createInsightsProvider } from "./provider";
-import {
-  countEvents,
-  countLatestEvents,
-  findLatestEvents,
-  getAppUsage,
-  getReleaseActivity,
-  getUpdateFailures,
-  type InsightsUpdateFailuresInput,
-  listEvents,
-} from "./reads";
-import { recordEvent } from "./recordEvent";
-import { createInsightsRouteHandlers, INSIGHTS_ROUTES } from "./routes";
-import {
-  createInsightsSchema,
-  DAILY_RETENTION_DAYS,
-  type InsightsRetention,
-  type InsightsSchema,
-  RAW_RETENTION_DAYS,
-} from "./schema";
-
-export type * from "./domain";
-export type {
-  BundleEventFailure,
-  BundleEventFailureReason,
-  BundleEventFailureStage,
-  BundleEventRow,
-  BundleEventRowBase,
-  DatabaseBundleEventMetadata,
-} from "./eventRow";
-export type {
-  InsightsFailureBreakdown,
-  InsightsUpdateFailures,
-  InsightsUpdateFailuresInput,
-} from "./reads";
-export { createInsightsModel } from "./model";
-export type * from "./modelTypes";
-export { createInsightsProvider } from "./provider";
-export { insightsIdentity, type InsightsIdentityParts } from "./recordEvent";
-export {
-  createInsightsSchema,
-  DEFAULT_INSIGHTS_RETENTION,
-  insightsSchema,
-  type InsightsRetention,
-  type InsightsSchema,
-} from "./schema";
-export type * from "./types";
-
-const createInsightsApi = (
-  db: HotUpdaterDatabase<InsightsSchema>,
-  now: () => number,
-  retention: InsightsRetention,
-) => ({
-  /** How long this plugin keeps its rows. */
-  retention,
-  /** Records one validated event row; a repeated id changes nothing. */
-  recordEvent: (event: BundleEventRow) => recordEvent(db, event),
-  listEvents: (input: InsightsListEventsInput) => listEvents(db, input),
-  findLatestEvents: (input: InsightsFindLatestEventsInput) =>
-    findLatestEvents(db, input),
-  countLatestEvents: (input: InsightsCountLatestEventsInput) =>
-    countLatestEvents(db, input),
-  countEvents: (input: InsightsCountEventsInput) => countEvents(db, input),
-  getReleaseActivity: (input: InsightsGetReleaseActivityInput) =>
-    getReleaseActivity(db, input, now, retention),
-  getAppUsage: (input: InsightsGetAppUsageInput) =>
-    getAppUsage(db, input, now, retention),
-  /** A release's or a channel's update failures, and their breakdown over a time range. */
-  getUpdateFailures: (input: InsightsUpdateFailuresInput) =>
-    getUpdateFailures(db, input, now, retention),
-});
-
-export type InsightsApi = ReturnType<typeof createInsightsApi>;
-
-/** `GET /failures`'s query: a scope, an optional release, and a time range or none. */
-const readFailuresQuery = (url: URL): InsightsUpdateFailuresInput => {
-  const query = url.searchParams;
-  const time = (name: string) => {
-    const value = query.get(name);
-    return value === null ? undefined : Number(value);
-  };
-  const [start, end] = [time("start"), time("end")];
-  const platform = query.get("platform");
-  const releaseId = query.get("releaseId");
-  if (
-    (platform !== "ios" && platform !== "android") ||
-    (start === undefined) !== (end === undefined)
-  ) {
-    throw new DatabasePluginInputError("invalid-query");
-  }
-  return {
-    platform,
-    channel: query.get("channel") ?? "",
-    ...(releaseId === null ? {} : { releaseId }),
-    ...(start === undefined ? {} : { timeRange: { start, end: end! } }),
-  };
-};
-
-/**
- * The admin route of the update failures read: a release's (`releaseId`)
- * since its first report, or over `start`–`end`, or a channel's over a range,
- * which covers at most 30 days.
- */
-const failuresEndpoint = (api: InsightsApi): PluginEndpoint => ({
-  access: "admin",
-  method: "GET",
-  path: "/failures",
-  handler: async (request) => {
-    try {
-      return Response.json(
-        await api.getUpdateFailures(readFailuresQuery(new URL(request.url))),
-        { headers: { "cache-control": "private, no-store" } },
-      );
-    } catch (error) {
-      if (error instanceof DatabasePluginInputError) {
-        return Response.json(
-          {
-            error:
-              "Send platform and channel, and releaseId or start and end in epoch milliseconds, at most 30 days apart.",
-          },
-          { status: 400 },
-        );
-      }
-      if (!isDatabaseBusyError(error)) throw error;
-      return Response.json(
-        { error: "Service unavailable" },
-        { status: 503, headers: { "retry-after": "5" } },
-      );
-    }
-  },
-});
-
-export interface InsightsOptions {
-  /**
-   * How long to keep rows, in whole days: `rawDays` (90 by default) for raw
-   * events and hourly rollups, `dailyDays` (400 by default) for daily
-   * rollups and each installation's latest event. Each is at least 1, and
-   * `dailyDays` at least `rawDays`.
-   */
-  readonly retention?: Partial<InsightsRetention>;
-}
-
-const retentionOf = ({ retention }: InsightsOptions): InsightsRetention => {
-  const rawDays = retention?.rawDays ?? RAW_RETENTION_DAYS;
-  const dailyDays = retention?.dailyDays ?? DAILY_RETENTION_DAYS;
-  const whole = (days: number) => Number.isSafeInteger(days) && days >= 1;
-  if (!whole(rawDays) || !whole(dailyDays) || dailyDays < rawDays) {
-    throw new HotUpdaterConfigError(
-      `insights({ retention }) takes whole days of at least 1, with dailyDays at least rawDays; got rawDays ${rawDays} and dailyDays ${dailyDays}.`,
-    );
-  }
-  return { rawDays, dailyDays };
-};
-
-/**
- * Insights: bundle lifecycle events and update failures, each
- * installation's latest event, and the counters, gauges, and sketches its
- * reads come from, each kept for its retention. It serves `POST /events` to
- * clients, and the Insights reads, update failures, and retention to admins.
- */
-export const insights = (options: InsightsOptions = {}) => {
-  const retention = retentionOf(options);
-  return definePlugin({
-    id: "insights",
-    // Keeps its tables' names: bundle_events, bundle_event_heads, insights_*.
-    namespace: false,
-    // 1.2.0 adds update failures (their counters, sketches, and
-    // breakdown) and drops heads' hour-row compatibility, so a database
-    // migrates before a server serves it.
-    schemaVersion: "1.2.0",
-    schema: createInsightsSchema(retention),
-    init: ({ db, now }) => {
-      const api = createInsightsApi(db, now, retention);
-      const routes = createInsightsRouteHandlers(
-        createInsightsProvider(createInsightsModel(api)),
-      );
-      // Declared, so the plugin's type names no runtime's Response.
-      const endpoints: PluginEndpoint[] = [
-        ...INSIGHTS_ROUTES.map(({ access, method, path, handler }) => ({
-          access,
-          method,
-          path,
-          handler: (
-            request: Request,
-            params: Readonly<Record<string, string>>,
-          ) => routes[handler](params, request),
-        })),
-        failuresEndpoint(api),
-        {
-          access: "admin",
-          method: "GET",
-          path: "/retention",
-          handler: async () => Response.json(retention),
-        },
-      ];
-      return { api, endpoints };
-    },
-    // Apps report their events through the SDK's Insights client plugin.
-    cli: {
-      clientPlugin: {
-        module: "@hot-updater/react-native/plugins/insights",
-        name: "insights",
-      },
-    },
-  });
-};