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

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,
+              },
+            ],
+          ],
+    ),
+  );
+}

package/src/lib/server/config.server.ts

@@ -1,28 +1,23 @@
 import {
   assertStorageOperations,
-  createDatabaseClient,
-  type DatabaseClient,
+  type HotUpdaterCoreApi,
   type StoragePluginWith,
 } from "@hot-updater/plugin-core";
+import { createDatabaseCoreApi } from "@hot-updater/server/db";
 import { getRequest } from "@tanstack/react-start/server";
 
-import type { ResolvedHotUpdaterConsoleConfig } from "../../index";
+import type { HotUpdaterConsoleConfig } from "../../index";
 import { requireConsoleAccess } from "./auth.server";
 import { resolveConsoleConfig } from "./console-runtime.server";
+import type { ConsoleRuntime } from "./runtime.server";
 
-type ResolvedConsoleConfig = ResolvedHotUpdaterConsoleConfig & {
-  readonly console: NonNullable<ResolvedHotUpdaterConsoleConfig["console"]>;
+type ResolvedConsoleConfig = HotUpdaterConsoleConfig & {
+  readonly console: NonNullable<HotUpdaterConsoleConfig["console"]>;
 };
 
 let configPromise: Promise<ResolvedConsoleConfig> | null = null;
-let databaseClient: DatabaseClient | null = null;
-let hotUpdater: ReturnType<
-  typeof import("./runtime.server").createRuntimeHotUpdater
-> | null = null;
-let apiKeyStore: ReturnType<
-  typeof import("./runtime.server").createApiKeyStore
-> | null = null;
-let apiKeyStoreResolved = false;
+let core: HotUpdaterCoreApi | null = null;
+let runtime: ConsoleRuntime | null = null;
 let storagePluginPromise: Promise<
   StoragePluginWith<"get" | "put" | "exists" | "delete">
 > | null = null;
@@ -69,30 +64,19 @@ export const prepareConfig = async (request: Request = getRequest()) => {
     await requireConsoleAccess(request);
     const config = await loadCachedConfig(request);
 
-    if (!databaseClient) {
-      databaseClient = createDatabaseClient(config.database);
-    }
-
-    if (!hotUpdater) {
-      const { createRuntimeHotUpdater } = await import("./runtime.server");
-      hotUpdater = createRuntimeHotUpdater(config);
-    }
+    // Bundles, releases, catalogs, and channels: core's API, in process or
+    // over a self-hosted server's admin API.
+    core ??= createDatabaseCoreApi(config.database);
 
-    if (!apiKeyStoreResolved) {
-      const { createApiKeyStore } = await import("./runtime.server");
-      apiKeyStore = createApiKeyStore(config);
-      apiKeyStoreResolved = true;
+    // The console's features: those of the plugins the server runs.
+    if (!runtime) {
+      const { createConsoleRuntime } = await import("./runtime.server");
+      runtime = createConsoleRuntime(config);
     }
 
     const storagePlugin = await loadCachedStoragePlugin(config);
 
-    return {
-      config,
-      databaseClient,
-      hotUpdater,
-      apiKeyStore,
-      storagePlugin,
-    };
+    return { config, core, runtime, storagePlugin };
   } catch (error) {
     if (
       !(

package/src/lib/server/console-feature-apis.ts

@@ -0,0 +1,59 @@
+import type { RemoteDatabase } from "@hot-updater/plugin-core";
+import type { ApiKeyManagementAPI } from "@hot-updater/server/plugins/api-keys";
+import {
+  createInsightsModel,
+  createInsightsProvider,
+  type InsightsApi,
+  type InsightsModel,
+} from "@hot-updater/server/plugins/insights";
+
+import type { ConsoleFeature } from "../console-features";
+import {
+  type ConsoleInsightsReads,
+  createAdminInsightsReads,
+} from "./adminInsights";
+
+/** A GET on a self-hosted server's admin handler. */
+export type FetchAdmin = RemoteDatabase["fetchAdmin"];
+
+/**
+ * What serves one console feature: `local` builds it from the API of the
+ * feature's plugin, which the console assembles over the database as the
+ * server does; `remote` builds it over a self-hosted server's admin API, for
+ * a feature that API serves.
+ */
+export interface ConsoleFeatureApi<TPluginApi, TApi> {
+  readonly local: (pluginApi: TPluginApi) => TApi;
+  readonly remote?: (fetchAdmin: FetchAdmin) => TApi;
+}
+
+const featureApi = <TPluginApi, TApi>(
+  api: ConsoleFeatureApi<TPluginApi, TApi>,
+): ConsoleFeatureApi<TPluginApi, TApi> => api;
+
+/** What serves each console feature, keyed like `consoleFeatures`. */
+export const consoleFeatureApis = {
+  insights: featureApi({
+    local: (api: InsightsApi): ConsoleInsightsReads => ({
+      ...createInsightsProvider(createInsightsModel(api)),
+      getRetention: async () => api.retention,
+      getUpdateFailures: api.getUpdateFailures,
+    }),
+    remote: createAdminInsightsReads,
+  }),
+  insightsAnalytics: featureApi({
+    local: (api: InsightsApi): InsightsModel => createInsightsModel(api),
+  }),
+  apiKeys: featureApi({
+    local: (api: ApiKeyManagementAPI) => api,
+  }),
+} satisfies {
+  readonly [F in ConsoleFeature]: ConsoleFeatureApi<never, unknown>;
+};
+
+/** What serves each console feature, as its server functions use it. */
+export type ConsoleFeatureApis = {
+  readonly [F in ConsoleFeature]: ReturnType<
+    (typeof consoleFeatureApis)[F]["local"]
+  >;
+};

package/src/lib/server/console-runtime.server.ts

@@ -1,43 +1,9 @@
 import type {
   ConsoleAuthAdapter,
-  ConsoleSigningConfig,
+  HotUpdaterConsoleConfig,
   HotUpdaterConsoleConfigSource,
-  ResolvedHotUpdaterConsoleConfig,
 } from "../../index";
 
-const readString = (value: unknown, key: string): string | undefined => {
-  if (typeof value !== "object" || value === null) return undefined;
-  const member = Reflect.get(value, key);
-  return typeof member === "string" && member.trim().length > 0
-    ? member.trim()
-    : undefined;
-};
-
-const getProviderName = (signing: unknown): string => {
-  return (
-    readString(signing, "name")?.slice(0, 80) ??
-    (readString(signing, "privateKeyPath") ? "localSigning" : undefined) ??
-    "Configured provider"
-  );
-};
-
-export const sanitizeConsoleSigningConfig = (
-  signing: unknown,
-): ConsoleSigningConfig | undefined => {
-  if (typeof signing !== "object" || signing === null) return undefined;
-  const privateKeyPath = readString(signing, "privateKeyPath");
-  if (
-    Reflect.get(signing, "enabled") === false ||
-    (privateKeyPath && Reflect.get(signing, "enabled") !== true)
-  )
-    return undefined;
-
-  return {
-    enabled: true,
-    provider: getProviderName(signing),
-  };
-};
-
 export const getConsoleAuthAdapter = async (): Promise<ConsoleAuthAdapter> => {
   const module = await import("virtual:hot-updater-console/auth");
   return module.default;
@@ -45,17 +11,17 @@ export const getConsoleAuthAdapter = async (): Promise<ConsoleAuthAdapter> => {
 
 export const resolveConsoleConfig = async (
   request: Request,
-): Promise<ResolvedHotUpdaterConsoleConfig> => {
+): Promise<HotUpdaterConsoleConfig> => {
   const { default: source } =
     (await import("virtual:hot-updater-console/config")) as {
       readonly default: HotUpdaterConsoleConfigSource;
     };
 
   const config = typeof source === "function" ? await source(request) : source;
-  const { signing: signingSource, ...configWithoutSigning } = config;
-  const signing = sanitizeConsoleSigningConfig(signingSource);
   return {
-    ...configWithoutSigning,
-    ...(signing === undefined ? {} : { signing }),
+    console: config.console,
+    database: config.database,
+    storage: config.storage,
+    ...(config.plugins === undefined ? {} : { plugins: config.plugins }),
   };
 };

package/src/lib/server/deleteBundle.ts

@@ -3,10 +3,11 @@ import {
   getManifestStorageUri,
   getPatchStorageUri,
 } from "@hot-updater/core";
-import type {
-  Bundle,
-  DatabaseClient,
-  StoragePluginWith,
+import {
+  type Bundle,
+  type HotUpdaterCoreApi,
+  rowToBundle,
+  type StoragePluginWith,
 } from "@hot-updater/plugin-core";
 
 interface DeleteBundleInput {
@@ -18,7 +19,7 @@ interface DeleteBundlesInput {
 }
 
 interface DeleteBundleDependencies {
-  databaseClient: DatabaseClient;
+  core: Pick<HotUpdaterCoreApi, "getBundle" | "deleteBundles">;
   storagePlugin: StoragePluginWith<"delete">;
   waitForStorageCleanup?: boolean;
 }
@@ -54,8 +55,7 @@ async function cleanupBundleStorage(
     if (resolvedStorageUri) cleanupUris.add(resolvedStorageUri);
   };
 
-  addCleanupUri(bundle.storageUri);
-  addCleanupUri(getManifestStorageUri(bundle) ?? undefined);
+  addCleanupUri(getManifestStorageUri(bundle));
   addCleanupUri(getPatchStorageUri(bundle) ?? undefined);
   for (const patch of getBundlePatches(bundle)) {
     addCleanupUri(patch.patchStorageUri);
@@ -73,30 +73,24 @@ async function cleanupBundleStorage(
 export async function deleteBundles(
   { bundleIds }: DeleteBundlesInput,
   {
-    databaseClient,
+    core,
     storagePlugin,
     waitForStorageCleanup = true,
   }: DeleteBundleDependencies,
 ) {
   const uniqueBundleIds = [...new Set(bundleIds)];
-  const { data: matchedBundles } = await databaseClient.getBundles({
-    where: { id: { in: uniqueBundleIds } },
-    limit: uniqueBundleIds.length,
-  });
-  const matchedById = new Map(
-    matchedBundles.map((bundle) => [bundle.id, bundle]),
+  const details = await Promise.all(
+    uniqueBundleIds.map((bundleId) => core.getBundle(bundleId)),
+  );
+  const bundles = details.flatMap((detail) =>
+    detail === null ? [] : [rowToBundle(detail.bundle, detail.patches)],
   );
-  const bundles = uniqueBundleIds.flatMap((bundleId) => {
-    const bundle = matchedById.get(bundleId);
-    return bundle ? [bundle] : [];
-  });
   const missingBundleIds = uniqueBundleIds.filter(
-    (bundleId) => !matchedById.has(bundleId),
+    (_bundleId, position) => details[position] === null,
   );
 
   for (const bundle of bundles) {
     const cleanupCandidates = [
-      bundle.storageUri,
       getManifestStorageUri(bundle),
       getPatchStorageUri(bundle),
       ...getBundlePatches(bundle).map((patch) => patch.patchStorageUri),
@@ -106,12 +100,9 @@ export async function deleteBundles(
     }
   }
 
+  // One core write; a bundle a release still uses refuses the whole batch.
   if (bundles.length > 0) {
-    await databaseClient.mutate(async (mutation) => {
-      for (const bundle of bundles) {
-        await mutation.deleteBundleById(bundle.id);
-      }
-    });
+    await core.deleteBundles(bundles.map((bundle) => bundle.id));
   }
 
   const cleanupStorage = async () => {