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

package/src/lib/api.ts

@@ -1,21 +1,12 @@
 import type {
-  ChannelDeleteInput,
-  ChannelInsertInput,
+  ReleaseFilter,
   ReleasePolicyPatch,
 } from "@hot-updater/plugin-core";
-import {
-  type QueryClient,
-  type QueryKey,
-  useMutation,
-  useQuery,
-  useQueryClient,
-} from "@tanstack/react-query";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 
 import {
   createChannel as createChannelApi,
   deleteChannel as deleteChannelApi,
-  deleteBundle as deleteBundleApi,
-  deleteBundles as deleteBundlesApi,
   deleteRelease as deleteReleaseApi,
   getBundle,
   getBundleChildCounts,
@@ -34,14 +25,13 @@ import {
 
 type BundleFilters = {
   platform?: "ios" | "android";
-  page?: number;
-  limit?: string;
+  limit?: number;
+  /** Bundles older than this id: the next page. */
   after?: string;
+  /** Bundles newer than this id: the previous page. */
   before?: string;
 };
 
-type BundlesQueryData = Awaited<ReturnType<typeof getBundles>>;
-
 const bundleListQueryKey = ["bundles"] as const;
 const releaseListQueryKey = ["releases"] as const;
 
@@ -71,51 +61,13 @@ export const queryKeys = {
 };
 
 export type ReleaseFilters = {
-  afterReleaseId?: string;
+  /** One of the filter sets the release indexes serve; none lists every release. */
+  filter?: ReleaseFilter;
+  /** Releases older than this id: the next page. */
   beforeReleaseId?: string;
-  bundleId?: string;
-  channelId?: string;
-  enabled?: boolean;
-  platform?: "ios" | "android";
+  /** Releases newer than this id: the previous page. */
+  afterReleaseId?: string;
   limit?: number;
-  page?: number;
-  targetAppVersion?: string;
-};
-
-function removeBundleFromQueryData(
-  data: BundlesQueryData | undefined,
-  bundleId: string,
-) {
-  if (!data) {
-    return data;
-  }
-
-  return {
-    ...data,
-    data: data.data.filter((bundle) => bundle.id !== bundleId),
-  };
-}
-
-function removeBundlesFromQueryData(
-  data: BundlesQueryData | undefined,
-  bundleIds: readonly string[],
-) {
-  if (!data) {
-    return data;
-  }
-
-  const bundleIdSet = new Set(bundleIds);
-  return {
-    ...data,
-    data: data.data.filter((bundle) => !bundleIdSet.has(bundle.id)),
-  };
-}
-
-const invalidateInBackground = (
-  queryClient: QueryClient,
-  queryKey: QueryKey,
-) => {
-  void queryClient.invalidateQueries({ queryKey }).catch(() => undefined);
 };
 
 // Query Hooks
@@ -213,7 +165,7 @@ export function useCreateChannelMutation() {
   const queryClient = useQueryClient();
 
   return useMutation({
-    mutationFn: (input: ChannelInsertInput) =>
+    mutationFn: (input: { name: string }) =>
       createChannelApi({ data: input }).then((response) => response.data),
     onSuccess: async () => {
       await queryClient.invalidateQueries({ queryKey: queryKeys.channels });
@@ -225,7 +177,7 @@ export function useDeleteChannelMutation() {
   const queryClient = useQueryClient();
 
   return useMutation({
-    mutationFn: (input: ChannelDeleteInput) =>
+    mutationFn: (input: { id: string }) =>
       deleteChannelApi({ data: input }).then((response) => response.data),
     onSettled: async () => {
       await queryClient.invalidateQueries({ queryKey: queryKeys.channels });
@@ -233,48 +185,6 @@ export function useDeleteChannelMutation() {
   });
 }
 
-export function useDeleteBundleMutation() {
-  const queryClient = useQueryClient();
-
-  return useMutation({
-    mutationFn: (params: { bundleId: string }) =>
-      deleteBundleApi({ data: params }),
-    onSuccess: (_, vars) => {
-      queryClient.removeQueries({ queryKey: queryKeys.bundle(vars.bundleId) });
-      queryClient.setQueriesData(
-        { queryKey: queryKeys.bundles.all },
-        (data: BundlesQueryData | undefined) =>
-          removeBundleFromQueryData(data, vars.bundleId),
-      );
-
-      invalidateInBackground(queryClient, queryKeys.bundles.all);
-      invalidateInBackground(queryClient, queryKeys.bundleChildren.all);
-    },
-  });
-}
-
-export function useDeleteBundlesMutation() {
-  const queryClient = useQueryClient();
-
-  return useMutation({
-    mutationFn: (params: { bundleIds: string[] }) =>
-      deleteBundlesApi({ data: params }),
-    onSuccess: (_, vars) => {
-      for (const bundleId of vars.bundleIds) {
-        queryClient.removeQueries({ queryKey: queryKeys.bundle(bundleId) });
-      }
-      queryClient.setQueriesData(
-        { queryKey: queryKeys.bundles.all },
-        (data: BundlesQueryData | undefined) =>
-          removeBundlesFromQueryData(data, vars.bundleIds),
-      );
-
-      invalidateInBackground(queryClient, queryKeys.bundles.all);
-      invalidateInBackground(queryClient, queryKeys.bundleChildren.all);
-    },
-  });
-}
-
 export function useUpdateReleaseMutation() {
   const queryClient = useQueryClient();
   return useMutation({
@@ -315,10 +225,17 @@ export function useDeleteReleaseMutation() {
       queryClient.removeQueries({
         queryKey: queryKeys.release(input.releaseId),
       });
+      // Core deletes the artifact with its last release, and the patches
+      // built on it, so the bundle reads can change too.
       await Promise.all([
         queryClient.invalidateQueries({ queryKey: queryKeys.releases.all }),
         queryClient.invalidateQueries({ queryKey: ["release-catalog"] }),
         queryClient.invalidateQueries({ queryKey: queryKeys.channels }),
+        queryClient.invalidateQueries({ queryKey: queryKeys.bundles.all }),
+        queryClient.invalidateQueries({ queryKey: ["bundle"] }),
+        queryClient.invalidateQueries({
+          queryKey: queryKeys.bundleChildren.all,
+        }),
       ]);
     },
   });

package/src/lib/bundle-activity.ts

@@ -0,0 +1,31 @@
+import { useQuery } from "@tanstack/react-query";
+
+import type { RecoveryInput } from "./insights-recovery";
+import { getBundleActivityRpc } from "./insights-recovery-rpc";
+
+export type BundleActivityInput = Pick<
+  RecoveryInput,
+  "platform" | "channel"
+> & { readonly releaseId: string };
+
+export type BundleActivityReport = {
+  readonly downloads: number;
+  /** Each installation once for each UTC day it launched the release. */
+  readonly activeDays: number;
+  readonly failedLaunches: number;
+  readonly measuredAtMs: number;
+  readonly coverage: import("@hot-updater/server/plugins/insights").InsightsCoverage;
+};
+
+/** Release activity for bundle rows; mounted only where the console reads it. */
+export function useBundleActivityQuery(inputs: readonly BundleActivityInput[]) {
+  const sorted = [...inputs].sort((a, b) =>
+    a.releaseId.localeCompare(b.releaseId),
+  );
+  return useQuery({
+    queryKey: ["bundle-activity", sorted],
+    queryFn: () => getBundleActivityRpc({ data: sorted }),
+    enabled: sorted.length > 0,
+    staleTime: 30_000,
+  });
+}

package/src/lib/console-access.ts

@@ -0,0 +1,20 @@
+import { createMiddleware } from "@tanstack/react-start";
+
+/**
+ * Refuses a caller the console does not authorize before a server function
+ * reads its input. TanStack Start runs a function's middleware before the
+ * function's own validator, so an anonymous or unlisted caller gets the access
+ * check's 401 or 403, never an input error, whatever it sends. Every server
+ * function except the sign-in reads in `auth-rpc.ts` uses it, and
+ * `console-access.spec.ts` checks that.
+ */
+export const consoleAccess = createMiddleware({ type: "function" }).server(
+  async ({ next }) => {
+    const [{ getRequest }, { requireConsoleAccess }] = await Promise.all([
+      import("@tanstack/react-start/server"),
+      import("./server/auth.server"),
+    ]);
+    await requireConsoleAccess(getRequest());
+    return next();
+  },
+);

package/src/lib/console-features-api.ts

@@ -0,0 +1,68 @@
+import {
+  type QueryClient,
+  queryOptions,
+  useQuery,
+} from "@tanstack/react-query";
+import { notFound } from "@tanstack/react-router";
+
+import { type ConsoleFeature, consoleFeatures } from "./console-features";
+import { getConsoleFeaturesRpc } from "./console-features-rpc";
+
+export const consoleFeaturesQueryKey = ["console", "features"] as const;
+
+export const consoleFeaturesQueryOptions = () =>
+  queryOptions({
+    queryKey: consoleFeaturesQueryKey,
+    queryFn: () => getConsoleFeaturesRpc(),
+    // A server's plugins change only when it restarts: one read serves a visit.
+    staleTime: Infinity,
+  });
+
+/** The features the console serves; the authorized layout loads them first. */
+export const useConsoleFeatures = () => useQuery(consoleFeaturesQueryOptions());
+
+/** Whether `feature` is on; false until the features load. */
+export const useConsoleFeature = (feature: ConsoleFeature): boolean =>
+  useConsoleFeatures().data?.features[feature] === true;
+
+/** A feature route's not-found data: the feature its guard found off. */
+type ConsoleFeatureNotFoundData = { readonly feature: ConsoleFeature };
+
+/** The feature in a route's not-found data, when a feature guard threw it. */
+export const notFoundFeature = (data: unknown): ConsoleFeature | undefined => {
+  const feature =
+    typeof data === "object" && data !== null
+      ? Reflect.get(data, "feature")
+      : undefined;
+  return typeof feature === "string" && Object.hasOwn(consoleFeatures, feature)
+    ? (feature as ConsoleFeature)
+    : undefined;
+};
+
+/**
+ * A feature route's `beforeLoad`: not found, naming the feature, when the
+ * console does not serve it. A failed features read lets the route load: the
+ * root layout answers a visitor it does not authorize, and the route's own
+ * reads report any other failure. The failure leaves the cache, which a
+ * server render sends to the browser: a refused visitor's failure is the 401
+ * or 403 Response, which the render cannot serialize.
+ */
+export const requireConsoleFeature = async (
+  queryClient: QueryClient,
+  feature: ConsoleFeature,
+): Promise<void> => {
+  const featureSet = await queryClient
+    .ensureQueryData(consoleFeaturesQueryOptions())
+    .catch(() => {
+      queryClient.removeQueries({
+        queryKey: consoleFeaturesQueryKey,
+        exact: true,
+      });
+      return undefined;
+    });
+  if (featureSet !== undefined && !featureSet.features[feature]) {
+    throw notFound({
+      data: { feature } satisfies ConsoleFeatureNotFoundData,
+    });
+  }
+};

package/src/lib/console-features-rpc.ts

@@ -0,0 +1,13 @@
+import { createServerFn } from "@tanstack/react-start";
+
+import { consoleAccess } from "./console-access";
+import type { ConsoleFeatureSet } from "./console-features";
+
+/** The features this console serves, for navigation and route guards. */
+export const getConsoleFeaturesRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
+  .handler(async (): Promise<ConsoleFeatureSet> => {
+    const { prepareConfig } = await import("./server/config.server");
+    const { runtime } = await prepareConfig();
+    return { features: await runtime.features(), remote: runtime.remote };
+  });

package/src/lib/console-features.ts

@@ -0,0 +1,91 @@
+/**
+ * The console's features and the server plugin each one needs. The console
+ * serves a feature only when its config lists the plugin, as the server runs
+ * it, and against a self-hosted server (`standaloneRepository`) only the
+ * features its admin API serves (`remote`); the rest read the database.
+ * Navigation, route guards, and server functions all read this registry. Its
+ * other halves, keyed by the same features, hold what serves each feature on
+ * the server (`server/console-feature-apis.ts`) and what each adds to pages
+ * (`components/features/console-feature-ui.tsx`).
+ */
+export const consoleFeatures = {
+  /** Event history and installation lookups, which the admin API serves too. */
+  insights: { plugin: "insights", label: "Insights", remote: true },
+  /** App usage, distribution, and release activity, read from the database. */
+  insightsAnalytics: { plugin: "insights", label: "Insights", remote: false },
+  /** API key management: `apiKeys()` mounts no admin routes to manage them. */
+  apiKeys: { plugin: "apiKeys", label: "API keys", remote: false },
+} as const satisfies Readonly<
+  Record<
+    string,
+    {
+      readonly plugin: string;
+      /** How navigation and the not-installed page name the feature. */
+      readonly label: string;
+      readonly remote: boolean;
+    }
+  >
+>;
+
+export type ConsoleFeature = keyof typeof consoleFeatures;
+
+/** Whether each feature is on. */
+export type ConsoleFeatures = Readonly<Record<ConsoleFeature, boolean>>;
+
+/** What the console serves, as its client reads it. */
+export type ConsoleFeatureSet = {
+  readonly features: ConsoleFeatures;
+  /** Whether the console reaches a self-hosted server through its admin API. */
+  readonly remote: boolean;
+};
+
+const featureIds = Object.keys(consoleFeatures) as ConsoleFeature[];
+
+/** The features on for the plugins the console's config lists, from where the console reads them. */
+export const resolveConsoleFeatures = (
+  plugins: readonly string[],
+  { remote }: { readonly remote: boolean },
+): ConsoleFeatures => {
+  const installed = new Set(plugins);
+  return Object.fromEntries(
+    featureIds.map((feature) => {
+      const { plugin, remote: servedRemotely } = consoleFeatures[feature];
+      return [feature, installed.has(plugin) && (servedRemotely || !remote)];
+    }),
+  ) as Record<ConsoleFeature, boolean>;
+};
+
+/** Why a feature is off: its plugin is missing, or it reads a database the console does not open. */
+export const unavailableReason = (
+  feature: ConsoleFeature,
+  { remote }: { readonly remote: boolean },
+): "plugin" | "remote" =>
+  remote && !consoleFeatures[feature].remote ? "remote" : "plugin";
+
+/**
+ * A server function refused a feature the console does not serve: the
+ * features' 404. The client recognizes it by `name`, which survives
+ * serialization where the class does not.
+ */
+export class ConsoleFeatureUnavailableError extends Error {
+  override readonly name = "ConsoleFeatureUnavailableError";
+  readonly status = 404;
+
+  constructor(
+    readonly feature: ConsoleFeature,
+    { remote }: { readonly remote: boolean },
+  ) {
+    super(
+      unavailableReason(feature, { remote }) === "remote"
+        ? "The console reads this from the database, and it reaches a self-hosted server through its admin API instead."
+        : `The server runs without the ${consoleFeatures[feature].plugin}() plugin.`,
+    );
+  }
+}
+
+export const isConsoleFeatureUnavailableError = (
+  error: unknown,
+): error is Error & { readonly feature: ConsoleFeature } =>
+  error instanceof Error &&
+  error.name === "ConsoleFeatureUnavailableError" &&
+  featureIds.includes(Reflect.get(error, "feature") as ConsoleFeature);

package/src/lib/insights-api.ts

@@ -1,9 +1,19 @@
-import type { InsightsEventPageInput } from "@hot-updater/server";
+import type { InsightsEventPageInput } from "@hot-updater/server/plugins/insights";
 import { useQuery } from "@tanstack/react-query";
 
+import {
+  readUpdateFailuresInput,
+  type UpdateFailuresInput,
+} from "./insights-failures";
+import { getUpdateFailuresRpc } from "./insights-failures-rpc";
+import {
+  DEFAULT_INSIGHTS_RETENTION,
+  type InsightsRetentionDays,
+} from "./insights-retention";
 import {
   findInsightsInstallationsRpc,
   getInsightsInstallationRpc,
+  getInsightsRetentionRpc,
   getReportingInstallationsRpc,
   listInsightsEventsRpc,
   listInsightsInstallationEventsRpc,
@@ -98,3 +108,29 @@ export const useInsightsInstallationEventsQuery = (
     refetchOnWindowFocus: true,
     staleTime: STALE_TIME_MS,
   });
+
+/** A release's or a channel's update failures; lifetime for a release without a window. */
+export const useUpdateFailuresQuery = (
+  input: UpdateFailuresInput,
+  enabled = true,
+) =>
+  useQuery({
+    queryKey: ["insights", "update-failures", input],
+    queryFn: () =>
+      getUpdateFailuresRpc({ data: readUpdateFailuresInput(input) }),
+    enabled,
+    refetchOnWindowFocus: true,
+    staleTime: STALE_TIME_MS,
+  });
+
+/**
+ * How long the server keeps Insights rows; the defaults until it answers, or
+ * when it does not report them.
+ */
+export const useInsightsRetention = (): InsightsRetentionDays =>
+  useQuery({
+    queryKey: ["insights", "retention"],
+    queryFn: () => getInsightsRetentionRpc(),
+    // A server's periods change only when it restarts.
+    staleTime: Infinity,
+  }).data ?? DEFAULT_INSIGHTS_RETENTION;

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

@@ -0,0 +1,21 @@
+import { createServerFn } from "@tanstack/react-start";
+
+import { consoleAccess } from "./console-access";
+import { readUpdateFailuresInput } from "./insights-failures";
+
+export const getUpdateFailuresRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
+  .validator(readUpdateFailuresInput)
+  .handler(async ({ data }) => {
+    const [{ prepareConfig }, { getUpdateFailuresReport }, { requireFeature }] =
+      await Promise.all([
+        import("./server/config.server"),
+        import("./server/updateFailures"),
+        import("./server/runtime.server"),
+      ]);
+    const { runtime } = await prepareConfig();
+    return getUpdateFailuresReport(
+      await requireFeature(runtime, "insights"),
+      data,
+    );
+  });

package/src/lib/insights-failures.ts

@@ -0,0 +1,129 @@
+import type {
+  InsightsFailureBreakdown,
+  InsightsUpdateFailures,
+} from "@hot-updater/server/plugins/insights";
+
+import { recoveryWindows } from "./insights-recovery";
+import type { InsightsWindow } from "./insights-rpc";
+import type { InsightsEventRow } from "./insights-view";
+
+export type { InsightsFailureBreakdown };
+
+export type UpdateFailuresInput = {
+  readonly platform: "ios" | "android";
+  readonly channel: string;
+  /** A release's failures; the channel's without it. */
+  readonly releaseId?: string;
+  /** The period that ends with the current hour; a release's since its first report without it. */
+  readonly window?: InsightsWindow;
+};
+
+export type UpdateFailuresReport = InsightsUpdateFailures & {
+  /** Where the period starts, or null since the release's first report. */
+  readonly startMs: number | null;
+  readonly endMs: number;
+};
+
+export function readUpdateFailuresInput(
+  input: UpdateFailuresInput,
+): UpdateFailuresInput {
+  if (
+    !input ||
+    (input.platform !== "ios" && input.platform !== "android") ||
+    typeof input.channel !== "string" ||
+    !input.channel.trim() ||
+    input.channel.length > 1_024 ||
+    (input.releaseId !== undefined &&
+      (typeof input.releaseId !== "string" ||
+        !input.releaseId.trim() ||
+        input.releaseId.length > 36)) ||
+    (input.window === undefined
+      ? input.releaseId === undefined
+      : !Object.hasOwn(recoveryWindows, input.window))
+  ) {
+    throw new Error("Choose a platform, channel, and time window.");
+  }
+  return input;
+}
+
+/**
+ * The failure rate of update attempts: failed download and install reports,
+ * over those plus download reports. Null without either.
+ */
+export const failureRate = ({
+  failedUpdates,
+  downloads,
+}: Pick<InsightsUpdateFailures, "failedUpdates" | "downloads">):
+  | number
+  | null =>
+  failedUpdates + downloads === 0
+    ? null
+    : failedUpdates / (failedUpdates + downloads);
+
+/** Of the downloads that tried a patch, the share that fell back to files or the archive. */
+export const patchFallbackRate = ({
+  patchDownloads,
+  patchFallbacks,
+}: Pick<InsightsUpdateFailures, "patchDownloads" | "patchFallbacks">):
+  | number
+  | null =>
+  patchDownloads + patchFallbacks === 0
+    ? null
+    : patchFallbacks / (patchDownloads + patchFallbacks);
+
+/** Installations whose update check failed, over the active ones; estimates, so at most 100%. */
+export const checkFailureRate = ({
+  failedInstallations,
+  activeInstallations,
+}: NonNullable<InsightsUpdateFailures["checks"]>): number | null =>
+  activeInstallations === 0
+    ? null
+    : Math.min(1, failedInstallations / activeInstallations);
+
+export const formatRate = (rate: number | null): string =>
+  rate === null ? "—" : `${(rate * 100).toFixed(2)}%`;
+
+const STAGES: Readonly<Record<string, string>> = {
+  check: "Update check",
+  download: "Download",
+  install: "Install",
+};
+
+const REASONS: Readonly<Record<string, string>> = {
+  network: "Network",
+  http: "HTTP error",
+  invalid_response: "Invalid response",
+  hash_mismatch: "Hash mismatch",
+  signature: "Signature",
+  patch: "Patch",
+  extract: "Extract",
+  storage: "Storage",
+};
+
+export const failureStageLabel = (stage: string): string =>
+  STAGES[stage] ?? "Unknown stage";
+
+export const failureReasonLabel = (reason: string): string =>
+  REASONS[reason] ?? "Unknown reason";
+
+/** What else the client knew: its resource, HTTP status, origin code, and transport. */
+export const failureDetailParts = (detail: {
+  readonly resource?: string | null;
+  readonly httpStatus?: number | null;
+  readonly originCode?: string | null;
+  readonly transport?: string | null;
+}): string[] => [
+  ...(detail.httpStatus == null ? [] : [`HTTP ${detail.httpStatus}`]),
+  ...(detail.originCode == null ? [] : [detail.originCode]),
+  ...(detail.transport == null ? [] : [detail.transport]),
+  ...(detail.resource == null ? [] : [detail.resource]),
+];
+
+/** An update failure as one line: where, why, and what else the client knew. */
+export const describeFailure = (
+  failure: NonNullable<InsightsEventRow["failure"]>,
+): string =>
+  [
+    `${failureStageLabel(failure.stage)} failed: ${failureReasonLabel(failure.reason)}`,
+    ...failureDetailParts(failure),
+  ].join(" · ");

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

@@ -0,0 +1,51 @@
+import { createServerFn } from "@tanstack/react-start";
+
+import type { BundleActivityInput } from "./bundle-activity";
+import { consoleAccess } from "./console-access";
+import { readRecoveryInput } from "./insights-recovery";
+
+export function readBundleActivityInput(
+  inputs: readonly BundleActivityInput[],
+) {
+  if (!Array.isArray(inputs) || inputs.length > 20)
+    throw new Error("Choose up to 20 bundles.");
+  return inputs.map((input) => {
+    readRecoveryInput({ ...input, window: "30d" });
+    if (!input.releaseId) throw new Error("Choose a bundle ID.");
+    return input;
+  });
+}
+
+export const getBundleActivityRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
+  .validator(readBundleActivityInput)
+  .handler(async ({ data }) => {
+    const [{ prepareConfig }, { getBundleActivity }, { requireFeature }] =
+      await Promise.all([
+        import("./server/config.server"),
+        import("./server/bundleActivity"),
+        import("./server/runtime.server"),
+      ]);
+    const { runtime } = await prepareConfig();
+    return getBundleActivity(
+      await requireFeature(runtime, "insightsAnalytics"),
+      data,
+    );
+  });
+
+export const getRecoveryReportRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
+  .validator(readRecoveryInput)
+  .handler(async ({ data }) => {
+    const [{ prepareConfig }, { getRecoveryReport }, { requireFeature }] =
+      await Promise.all([
+        import("./server/config.server"),
+        import("./server/insightsRecovery"),
+        import("./server/runtime.server"),
+      ]);
+    const { runtime } = await prepareConfig();
+    return getRecoveryReport(
+      await requireFeature(runtime, "insightsAnalytics"),
+      data,
+    );
+  });