@hot-updater/console 1.0.0-rc.2 → 1.0.0-rc.21

package/src/lib/insights-recovery.ts

@@ -0,0 +1,68 @@
+import type { InsightsCoverage } from "@hot-updater/server/plugins/insights";
+
+import type { InsightsWindow } from "./insights-rpc";
+
+export type RecoveryInput = {
+  readonly platform: "ios" | "android";
+  readonly channel: string;
+  readonly window: InsightsWindow;
+  readonly releaseId?: string;
+};
+
+export type RecoveryReport = {
+  readonly downloads: number;
+  /**
+   * Distinct installations that reported in the scope and period, or that
+   * launched the release; estimated.
+   */
+  readonly activeInstallations: number;
+  /**
+   * Installation-days: each installation once for each UTC day it launched,
+   * and once more on a day an update applied or recovered.
+   */
+  readonly activeDays: number;
+  readonly failedLaunches: number;
+  readonly points: readonly {
+    readonly startMs: number;
+    /** That UTC day's daily active installations. */
+    readonly dailyActiveInstallations: number;
+    readonly failedLaunches: number;
+  }[];
+  readonly startMs: number;
+  readonly endMs: number;
+  readonly measuredAtMs: number;
+  readonly coverage: InsightsCoverage;
+};
+
+export const recoveryWindows = {
+  "24h": { durationMs: 86_400_000, intervalMs: 3_600_000 },
+  "7d": { durationMs: 7 * 86_400_000, intervalMs: 6 * 3_600_000 },
+  "30d": { durationMs: 30 * 86_400_000, intervalMs: 86_400_000 },
+} as const;
+
+/**
+ * Where a period ends: the end of the current UTC hour, as the server's
+ * reporting overview ends. The counters keep whole hours, so this is the
+ * latest end that still counts a report received just now; every Insights
+ * card ends here, so their numbers cover the same hours.
+ */
+export const insightsPeriodEnd = (now: number): number =>
+  Math.ceil(now / 3_600_000) * 3_600_000;
+
+export function readRecoveryInput(input: RecoveryInput): RecoveryInput {
+  if (
+    !input ||
+    (input.platform !== "ios" && input.platform !== "android") ||
+    typeof input.channel !== "string" ||
+    !input.channel.trim() ||
+    input.channel.length > 1_024 ||
+    !Object.hasOwn(recoveryWindows, input.window) ||
+    (input.releaseId !== undefined &&
+      (typeof input.releaseId !== "string" ||
+        !input.releaseId.trim() ||
+        input.releaseId.length > 1_024))
+  ) {
+    throw new Error("Choose a platform, channel, and time window.");
+  }
+  return input;
+}

package/src/lib/insights-retention.ts

@@ -0,0 +1,21 @@
+/** How long the server's `insights()` keeps rows, in days. */
+export interface InsightsRetentionDays {
+  /** Raw events and hourly totals. */
+  readonly rawDays: number;
+  /** Daily totals, distributions, and each installation's latest report. */
+  readonly dailyDays: number;
+}
+
+/** `insights()`'s defaults, for a server that does not report its periods. */
+export const DEFAULT_INSIGHTS_RETENTION: InsightsRetentionDays = {
+  rawDays: 90,
+  dailyDays: 400,
+};
+
+export const formatDays = (days: number): string =>
+  `${days.toLocaleString("en")} ${days === 1 ? "day" : "days"}`;
+
+/** Whether daily totals cover App usage's 12-month period: 52 weeks. */
+export const keepsTwelveMonths = ({
+  dailyDays,
+}: InsightsRetentionDays): boolean => dailyDays >= 364;

package/src/lib/insights-rpc.ts

@@ -1,13 +1,13 @@
 import type {
-  ReportingOverview,
   InsightsScope,
+  ReportingOverview,
   InsightsEventPageInput,
   InsightsInstallationEventPageInput,
   ActiveInstallationWindow,
-  InsightsProvider,
-} from "@hot-updater/server";
+} from "@hot-updater/server/plugins/insights";
 import { createServerFn } from "@tanstack/react-start";
 
+import { consoleAccess } from "./console-access";
 import type {
   InsightsInstallationViewRow,
   InsightsViewPage,
@@ -30,10 +30,14 @@ type InstallationsPageInput = {
   readonly limit: number;
 };
 
-const runtime = async (): Promise<InsightsProvider> => {
-  const { prepareConfig } = await import("./server/config.server");
-  const { hotUpdater } = await prepareConfig();
-  return hotUpdater;
+/** The Insights reads, once the console's access check and the feature guard pass. */
+const insightsReads = async () => {
+  const [{ prepareConfig }, { requireFeature }] = await Promise.all([
+    import("./server/config.server"),
+    import("./server/runtime.server"),
+  ]);
+  const { runtime } = await prepareConfig();
+  return requireFeature(runtime, "insights");
 };
 
 const readOverview = (input: InsightsOverviewInput) => input;
@@ -44,27 +48,41 @@ const readInstallationPage = (input: InstallationsPageInput) => input;
 const readInstallId = (input: { readonly installId: string }) => input;
 
 export const getReportingInstallationsRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
   .validator(readOverview)
-  .handler(async ({ data }) => (await runtime()).getReportingOverview(data));
+  .handler(async ({ data }) =>
+    (await insightsReads()).getReportingOverview(data),
+  );
 
 export const listInsightsEventsRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
   .validator(readEventsPage)
-  .handler(async ({ data }) => (await runtime()).listEvents(data));
+  .handler(async ({ data }) => (await insightsReads()).listEvents(data));
 
 export const listInsightsInstallationEventsRpc = createServerFn({
   method: "GET",
 })
+  .middleware([consoleAccess])
   .validator(readInstallationEventsPage)
-  .handler(async ({ data }) => (await runtime()).listInstallationEvents(data));
+  .handler(async ({ data }) =>
+    (await insightsReads()).listInstallationEvents(data),
+  );
 
 export const getInsightsInstallationRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
   .validator(readInstallId)
-  .handler(async ({ data }) => (await runtime()).getInstallation(data));
+  .handler(async ({ data }) => (await insightsReads()).getInstallation(data));
+
+/** How long the server's `insights()` keeps rows. */
+export const getInsightsRetentionRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
+  .handler(async () => (await insightsReads()).getRetention());
 
 export const findInsightsInstallationsRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
   .validator(readInstallationPage)
   .handler(async ({ data }) => {
-    const insights = await runtime();
+    const insights = await insightsReads();
     const install = data.cursor
       ? null
       : await insights.getInstallation({ installId: data.identity });

package/src/lib/insights-search.ts

@@ -0,0 +1,58 @@
+import type { InsightsWindow } from "./insights-api";
+import type { AppUsageScope, UsageWindow } from "./insights-usage";
+
+const readText = (value: unknown) =>
+  typeof value === "string" && value.trim().length > 0 && value.length <= 1024
+    ? value
+    : undefined;
+const readWindow = (value: unknown): InsightsWindow | undefined =>
+  value === "24h" || value === "7d" || value === "30d" ? value : undefined;
+const readUsageWindow = (value: unknown): UsageWindow | undefined =>
+  value === "12m" ? value : readWindow(value);
+
+export type InsightsSearch = {
+  platform?: AppUsageScope["platform"];
+  channel?: string;
+  appVersion?: string;
+  window?: UsageWindow;
+  bundleWindow?: InsightsWindow;
+  healthPlatform?: "ios" | "android";
+  healthChannel?: string;
+  releaseId?: string;
+};
+
+export function validateInsightsSearch(
+  search: Record<string, unknown>,
+): InsightsSearch {
+  return {
+    platform:
+      search.platform === "all" ||
+      search.platform === "ios" ||
+      search.platform === "android"
+        ? search.platform
+        : undefined,
+    channel: readText(search.channel),
+    appVersion: readText(search.appVersion),
+    window: readUsageWindow(search.window),
+    bundleWindow: readWindow(search.bundleWindow),
+    healthPlatform:
+      search.healthPlatform === "ios" || search.healthPlatform === "android"
+        ? search.healthPlatform
+        : undefined,
+    healthChannel: readText(search.healthChannel),
+    releaseId: readText(search.releaseId),
+  };
+}
+
+export function validateDistributionSearch(search: Record<string, unknown>) {
+  return {
+    ...validateInsightsSearch(search),
+    version: readText(search.version),
+    page:
+      typeof search.page === "number" &&
+      Number.isSafeInteger(search.page) &&
+      search.page > 0
+        ? search.page
+        : undefined,
+  };
+}

package/src/lib/insights-usage-rpc.ts

@@ -0,0 +1,29 @@
+import { createServerFn } from "@tanstack/react-start";
+
+import { consoleAccess } from "./console-access";
+import { readAppUsageInput, type AppUsageInput } from "./insights-usage";
+
+export const getAppUsageReportRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
+  .validator((input: AppUsageInput) => {
+    readAppUsageInput(input);
+    return {
+      platform: input.platform,
+      channel: input.channel,
+      appVersion: input.appVersion,
+      window: input.window,
+    };
+  })
+  .handler(async ({ data }) => {
+    const [{ prepareConfig }, { getAppUsageReport }, { requireFeature }] =
+      await Promise.all([
+        import("./server/config.server"),
+        import("./server/insightsUsage"),
+        import("./server/runtime.server"),
+      ]);
+    const { runtime } = await prepareConfig();
+    return getAppUsageReport(
+      await requireFeature(runtime, "insightsAnalytics"),
+      data,
+    );
+  });

package/src/lib/insights-usage.ts

@@ -0,0 +1,74 @@
+export type AppUsageInput = {
+  readonly platform: "all" | "ios" | "android";
+  readonly channel: string;
+  readonly appVersion?: string;
+  readonly window: UsageWindow;
+};
+export type AppUsageScope = Omit<AppUsageInput, "window">;
+
+export type UsageDistribution = {
+  readonly name: string;
+  readonly installations: number;
+};
+
+export type BundleDistribution = {
+  readonly appVersion: string;
+  readonly platform: "ios" | "android";
+  readonly releaseId: string | null;
+  readonly installations: number;
+};
+
+export type AppUsageReport = {
+  readonly bundleDistribution: readonly BundleDistribution[];
+  readonly activeInstallations: number;
+  readonly sinceMs: number;
+  /**
+   * Where the distribution starts: the start of the UTC day that contains the
+   * period's start. Latest reports are counted by UTC day, so the
+   * distribution covers every UTC day the period touches.
+   */
+  readonly distributionSinceMs: number;
+  readonly beforeReceivedAtMs: number;
+  readonly intervalMs: number;
+  readonly truncated: boolean;
+  readonly appVersions: readonly string[];
+  readonly versions: readonly UsageDistribution[];
+  readonly platforms: readonly UsageDistribution[];
+  readonly points: readonly {
+    readonly startMs: number;
+    readonly installations: number | null;
+  }[];
+};
+
+export const usageMetrics = {
+  "24h": { label: "DAU", period: "24 hours", interval: "hour" },
+  "7d": { label: "WAU", period: "7 days", interval: "6 hours" },
+  "30d": { label: "MAU", period: "30 days", interval: "day" },
+  "12m": { label: "YAU", period: "12 months", interval: "week" },
+} as const;
+
+/**
+ * An App usage period. Hourly counts are kept 90 days, so the 12-month
+ * period counts whole UTC days, from the daily counts kept 13 months.
+ */
+export type UsageWindow = keyof typeof usageMetrics;
+
+export function readAppUsageInput(input: AppUsageInput): AppUsageInput {
+  if (
+    !input ||
+    (input.platform !== "all" &&
+      input.platform !== "ios" &&
+      input.platform !== "android") ||
+    typeof input.channel !== "string" ||
+    !input.channel.trim() ||
+    input.channel.length > 1_024 ||
+    !Object.hasOwn(usageMetrics, input.window) ||
+    (input.appVersion !== undefined &&
+      (typeof input.appVersion !== "string" ||
+        !input.appVersion.trim() ||
+        input.appVersion.length > 1_024))
+  ) {
+    throw new Error("Choose App usage filters and a time window.");
+  }
+  return input;
+}

package/src/lib/insights-view.ts

@@ -1,4 +1,7 @@
-import type { EventHistoryRow, InstallationRow } from "@hot-updater/server";
+import type {
+  EventHistoryRow,
+  InstallationRow,
+} from "@hot-updater/server/plugins/insights";
 
 export type InsightsEventRow = EventHistoryRow;
 export type InsightsInstallationViewRow = InstallationRow;
@@ -9,7 +12,40 @@ export type InsightsViewPage<TRow> = {
 };
 
 export const outcomeLabels = {
+  downloaded: "Downloaded reports",
   applied: "Applied reports",
   recovered: "Recovered-from reports",
-  adopted: "Adopted reports",
+  failed: "Failed update reports",
 } as const;
+
+const DAY_MS = 86_400_000;
+
+/** The time ranges an event list reads, shortest first. */
+export const eventRanges = {
+  "24h": { period: "24 hours", durationMs: DAY_MS },
+  "7d": { period: "7 days", durationMs: 7 * DAY_MS },
+  "30d": { period: "30 days", durationMs: 30 * DAY_MS },
+  "90d": { period: "90 days", durationMs: 90 * DAY_MS },
+} as const;
+
+export type EventRange = keyof typeof eventRanges;
+
+export const EVENT_RANGES = Object.keys(eventRanges) as readonly EventRange[];
+
+export const DEFAULT_EVENT_RANGE: EventRange = "7d";
+
+/** The next longer range, or undefined for the longest. */
+export const widerEventRange = (range: EventRange): EventRange | undefined =>
+  EVENT_RANGES[EVENT_RANGES.indexOf(range) + 1];
+
+/**
+ * The receipt interval [sinceMs, beforeReceivedAtMs) a range covers. The end
+ * stays fixed while the list pages, so every page reads the same interval.
+ */
+export const eventRangeBounds = (
+  range: EventRange,
+  beforeReceivedAtMs: number,
+) => ({
+  beforeReceivedAtMs,
+  sinceMs: Math.max(0, beforeReceivedAtMs - eventRanges[range].durationMs),
+});

package/src/lib/scroll-restoration.ts

@@ -0,0 +1,21 @@
+import type { AnyRouter, ParsedLocation } from "@tanstack/react-router";
+
+declare module "@tanstack/react-router" {
+  interface StaticDataRouteOption {
+    /**
+     * The route's scroll-restoration key for a location; without one, each
+     * history entry keeps its own scroll position.
+     */
+    readonly scrollRestorationKey?: (location: ParsedLocation) => string;
+  }
+}
+
+/** A location's scroll-restoration key: its route's own, else its history entry's. */
+export const routeScrollRestorationKey = (
+  router: Pick<AnyRouter, "getMatchedRoutes">,
+  location: ParsedLocation,
+): string => {
+  const [, , foundRoute] = router.getMatchedRoutes(location.pathname);
+  const routeKey = foundRoute?.options.staticData?.scrollRestorationKey;
+  return routeKey?.(location) ?? location.state.__TSR_key!;
+};

package/src/lib/server/adminInsights.ts

@@ -0,0 +1,124 @@
+import type {
+  InsightsEventPageInput,
+  InsightsProvider,
+  InsightsUpdateFailures,
+  InsightsUpdateFailuresInput,
+} from "@hot-updater/server/plugins/insights";
+
+import { ConsoleFeatureUnavailableError } from "../console-features";
+import type { InsightsRetentionDays } from "../insights-retention";
+
+/** The Insights reads the console pages use, update failures, and how long rows are kept. */
+export type ConsoleInsightsReads = Omit<
+  InsightsProvider,
+  "appendBundleEvent"
+> & {
+  getRetention(): Promise<InsightsRetentionDays>;
+  getUpdateFailures(
+    input: InsightsUpdateFailuresInput,
+  ): Promise<InsightsUpdateFailures>;
+};
+
+/** A GET on a self-hosted server's admin handler. */
+export type FetchAdmin = (path: string) => Promise<Response>;
+
+/** The `error` a failed admin route answered with, or a message naming its status. */
+const errorOf = async (response: Response, path: string): Promise<Error> => {
+  const body: unknown = await response.json().catch(() => null);
+  return new Error(
+    typeof body === "object" &&
+      body !== null &&
+      typeof Reflect.get(body, "error") === "string"
+      ? String(Reflect.get(body, "error"))
+      : `The server answered ${path.split("?")[0]} with ${response.status}.`,
+  );
+};
+
+const withQuery = (
+  path: string,
+  input: Readonly<Record<string, number | string | undefined>>,
+): string => {
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(input)) {
+    if (value !== undefined) query.set(key, String(value));
+  }
+  const value = query.toString();
+  return value.length === 0 ? path : `${path}?${value}`;
+};
+
+const eventQuery = ({
+  beforeReceivedAtMs,
+  sinceMs,
+  cursor,
+  limit,
+}: Omit<InsightsEventPageInput, "bundle">) => ({
+  beforeReceivedAtMs,
+  sinceMs,
+  cursor,
+  limit,
+});
+
+/**
+ * A self-hosted server's Insights, read through the admin routes its
+ * `insights()` plugin serves.
+ */
+export const createAdminInsightsReads = (
+  fetchAdmin: FetchAdmin,
+): ConsoleInsightsReads => {
+  const read = async <T>(path: string): Promise<T | null> => {
+    const response = await fetchAdmin(path);
+    if (response.status === 404) return null;
+    if (!response.ok) throw await errorOf(response, path);
+    return (await response.json()) as T;
+  };
+  // A route no plugin serves answers 404: the server runs without insights(),
+  // as after a restart without it once the console read its plugins.
+  const required = async <T>(path: string): Promise<T> => {
+    const value = await read<T>(path);
+    if (value === null) {
+      throw new ConsoleFeatureUnavailableError("insights", { remote: true });
+    }
+    return value;
+  };
+
+  return {
+    getReportingOverview: ({ platform, channel, window, bundleId }) =>
+      required(withQuery("/overview", { platform, channel, window, bundleId })),
+    listEvents: ({ bundle, ...input }) =>
+      required(
+        withQuery("/events", {
+          ...eventQuery(input),
+          ...(bundle === undefined
+            ? {}
+            : {
+                platform: bundle.platform,
+                channel: bundle.channel,
+                bundleId: bundle.bundleId,
+                outcome: bundle.outcome,
+              }),
+        }),
+      ),
+    listInstallationEvents: ({ installId, ...input }) =>
+      required(
+        withQuery(
+          `/installations/${encodeURIComponent(installId)}/events`,
+          eventQuery(input),
+        ),
+      ),
+    getInstallation: ({ installId }) =>
+      read(`/installations/${encodeURIComponent(installId)}`),
+    pageInstallationsByCurrentUserId: ({ userId, cursor, limit }) =>
+      required(withQuery("/installations", { userId, cursor, limit })),
+    getUpdateFailures: ({ platform, channel, releaseId, timeRange }) =>
+      required(
+        withQuery("/failures", {
+          platform,
+          channel,
+          releaseId,
+          start: timeRange?.start,
+          end: timeRange?.end,
+        }),
+      ),
+    getRetention: () => required("/retention"),
+  };
+};

package/src/lib/server/auth.server.ts

@@ -13,11 +13,19 @@ const accessError = (
     { status: access.status === "unauthenticated" ? 401 : 403 },
   );
 
-export const getConsoleAccess = async (
-  request: Request,
-): Promise<ConsoleAccess> => {
-  const adapter = await getConsoleAuthAdapter();
-  return adapter.getAccess(request);
+// Server function middleware checks access before input, and prepareConfig
+// checks again for its callers: one request asks the adapter once.
+const accessByRequest = new WeakMap<Request, Promise<ConsoleAccess>>();
+
+export const getConsoleAccess = (request: Request): Promise<ConsoleAccess> => {
+  let access = accessByRequest.get(request);
+  if (!access) {
+    access = getConsoleAuthAdapter().then((adapter) =>
+      adapter.getAccess(request),
+    );
+    accessByRequest.set(request, access);
+  }
+  return access;
 };
 
 export const getConsoleAuthProviders = async (

package/src/lib/server/bundleActivity.ts

@@ -0,0 +1,37 @@
+import type {
+  InsightsModel,
+  ReleaseReference,
+} from "@hot-updater/server/plugins/insights";
+
+import type { BundleActivityInput } from "../bundle-activity";
+
+export async function getBundleActivity(
+  model: InsightsModel,
+  inputs: readonly BundleActivityInput[],
+) {
+  if (inputs.length === 0) return {};
+  const releases: ReleaseReference[] = inputs.map((input) => ({
+    releaseId: input.releaseId,
+    platform: input.platform,
+    channel: input.channel,
+  }));
+  const activity = await model.getReleaseActivity({ releases });
+  return Object.fromEntries(
+    activity.data.flatMap((item) =>
+      item.release === undefined
+        ? []
+        : [
+            [
+              item.release.releaseId,
+              {
+                downloads: item.metrics.downloads,
+                activeDays: item.metrics.launches,
+                failedLaunches: item.metrics.failedLaunches,
+                measuredAtMs: activity.measuredAtMs,
+                coverage: activity.coverage,
+              },
+            ],
+          ],
+    ),
+  );
+}