@hot-updater/console 1.0.0-rc.9 → 1.0.0

package/src/lib/release-adoption-api.ts

@@ -0,0 +1,214 @@
+import { useQueries, useQuery } from "@tanstack/react-query";
+
+import { insightsPeriodEnd, recoveryWindows } from "./insights-recovery";
+import type { InsightsWindow } from "./insights-rpc";
+import type { HealthChart } from "./insights-search";
+import {
+  DEFAULT_ADOPTION_RELEASES,
+  type AdoptionRelease,
+  type BundleEventType,
+  type BundleEventsSeries,
+  MAX_ADOPTION_RELEASES,
+} from "./release-adoption";
+import {
+  getAdoptionReleaseRpc,
+  getBundleEventsRpc,
+  listAdoptionReleasesRpc,
+} from "./release-adoption-rpc";
+
+/** What each Release health chart reads per bundle. */
+const READS: Record<HealthChart, readonly BundleEventType[]> = {
+  adoption: ["DOWNLOADED", "LAUNCHED"],
+  crashes: ["LAUNCHED", "RECOVERED"],
+};
+
+/** One compared bundle and the counts read for it so far. */
+export type ComparedBundle = {
+  readonly release: AdoptionRelease;
+  readonly downloaded?: BundleEventsSeries;
+  readonly launched?: BundleEventsSeries;
+  readonly recovered?: BundleEventsSeries;
+  readonly error: Error | null;
+};
+
+/** What Release health shows: the period, the bundles, their reports. */
+export type ReleaseHealthState = {
+  readonly period: {
+    readonly startMs: number;
+    readonly endMs: number;
+    readonly durationMs: number;
+    readonly intervalMs: number;
+  };
+  /** The newest bundle deployments, newest first; undefined while loading. */
+  readonly candidates: readonly AdoptionRelease[] | undefined;
+  /** The compared bundles; undefined until they are known. */
+  readonly releases: readonly ComparedBundle[] | undefined;
+  /** True when the bundles are the default, not a choice. */
+  readonly isDefault: boolean;
+  readonly error: Error | null;
+  readonly isFetching: boolean;
+  readonly refresh: () => void;
+};
+
+/**
+ * Release health's reads, each keyed by what it depends on: the newest
+ * deployments by channel and platform, kept five minutes; a bundle the
+ * newest leave out, kept; and one count series per bundle and report type,
+ * so adding a bundle or opening the other chart reads only what is new.
+ */
+export function useReleaseHealth({
+  platform,
+  channel,
+  window,
+  releaseIds,
+  focusReleaseId,
+  chart,
+}: {
+  readonly platform: "ios" | "android";
+  readonly channel: string;
+  readonly window: InsightsWindow;
+  /** Chosen bundles; undefined, the focus and its previous, or the newest. */
+  readonly releaseIds: readonly string[] | undefined;
+  readonly focusReleaseId: string | undefined;
+  readonly chart: HealthChart;
+}): ReleaseHealthState {
+  const { durationMs, intervalMs } = recoveryWindows[window];
+  // Every series of one chart reads the same hours: the period ends with the
+  // current hour, so a new hour reads them all again, together.
+  const endMs = insightsPeriodEnd(Date.now());
+  const scope = { platform, channel };
+  const candidatesQuery = useQuery({
+    queryKey: ["insights", "adoption-releases", scope],
+    queryFn: () => listAdoptionReleasesRpc({ data: scope }),
+    staleTime: 5 * 60_000,
+  });
+  const candidates = candidatesQuery.data;
+  const focusIndex =
+    focusReleaseId === undefined || candidates === undefined
+      ? -1
+      : candidates.findIndex((release) => release.releaseId === focusReleaseId);
+  // A focus among the newest has its previous bundle there too, unless it is
+  // the oldest of them.
+  const focusQuery = useQuery({
+    queryKey: ["insights", "adoption-release", scope, focusReleaseId, true],
+    queryFn: () =>
+      getAdoptionReleaseRpc({
+        data: { ...scope, releaseId: focusReleaseId!, withPrevious: true },
+      }),
+    enabled:
+      releaseIds === undefined &&
+      focusReleaseId !== undefined &&
+      candidates !== undefined &&
+      (focusIndex === -1 || focusIndex === candidates.length - 1),
+    staleTime: Number.POSITIVE_INFINITY,
+  });
+  const known = new Map<string, AdoptionRelease>();
+  for (const release of [
+    ...(focusQuery.data?.release ? [focusQuery.data.release] : []),
+    ...(focusQuery.data?.previous ? [focusQuery.data.previous] : []),
+    // The newest list last, so a rolled-back bundle shows as it is now.
+    ...(candidates ?? []),
+  ])
+    known.set(release.releaseId, release);
+  const newest = (list: readonly AdoptionRelease[]) =>
+    list
+      .slice(0, DEFAULT_ADOPTION_RELEASES)
+      .map((release) => release.releaseId);
+  const chosen: readonly string[] | undefined =
+    releaseIds !== undefined
+      ? releaseIds.slice(0, MAX_ADOPTION_RELEASES)
+      : candidates === undefined
+        ? undefined
+        : focusReleaseId === undefined
+          ? newest(candidates)
+          : focusIndex !== -1 && focusIndex < candidates.length - 1
+            ? [focusReleaseId, candidates[focusIndex + 1]!.releaseId]
+            : focusQuery.data === undefined
+              ? undefined
+              : focusQuery.data.release === null
+                ? // A focus that is no bundle of this scope: the newest.
+                  newest(candidates)
+                : [
+                    focusQuery.data.release.releaseId,
+                    focusQuery.data.previous?.releaseId,
+                  ].filter((id) => id !== undefined);
+  // A chosen bundle the newest leave out, as from a copied link.
+  const unknown = (chosen ?? []).filter(
+    (releaseId) => !known.has(releaseId) && releaseId !== focusReleaseId,
+  );
+  const labelQueries = useQueries({
+    queries: unknown.map((releaseId) => ({
+      queryKey: ["insights", "adoption-release", scope, releaseId, false],
+      queryFn: () => getAdoptionReleaseRpc({ data: { ...scope, releaseId } }),
+      staleTime: Number.POSITIVE_INFINITY,
+    })),
+  });
+  for (const query of labelQueries)
+    if (query.data?.release)
+      known.set(query.data.release.releaseId, query.data.release);
+  const releases =
+    chosen === undefined || labelQueries.some((query) => query.isPending)
+      ? undefined
+      : chosen.flatMap((releaseId) => {
+          const release = known.get(releaseId);
+          return release === undefined ? [] : [release];
+        });
+  const reads = (releases ?? []).flatMap((release) =>
+    READS[chart].map((type) => ({ release, type })),
+  );
+  const seriesQueries = useQueries({
+    queries: reads.map(({ release, type }) => {
+      const data = {
+        ...scope,
+        window,
+        endMs,
+        bundleId: release.bundleId,
+        type,
+      };
+      return {
+        queryKey: ["insights", "bundle-events", data],
+        queryFn: () => getBundleEventsRpc({ data }),
+        staleTime: 30_000,
+        // Keep a bundle's line while its next period loads.
+        placeholderData: (
+          previous: BundleEventsSeries | undefined,
+        ): BundleEventsSeries | undefined =>
+          previous?.bundleId === release.bundleId && previous.type === type
+            ? previous
+            : undefined,
+      };
+    }),
+  });
+  const seriesOf = (bundleId: string, type: BundleEventType) => {
+    const index = reads.findIndex(
+      (read) => read.release.bundleId === bundleId && read.type === type,
+    );
+    return index === -1 ? undefined : seriesQueries[index];
+  };
+  return {
+    period: { startMs: endMs - durationMs, endMs, durationMs, intervalMs },
+    candidates,
+    releases: releases?.map((release) => {
+      const downloaded = seriesOf(release.bundleId, "DOWNLOADED");
+      const launched = seriesOf(release.bundleId, "LAUNCHED");
+      const recovered = seriesOf(release.bundleId, "RECOVERED");
+      return {
+        release,
+        downloaded: downloaded?.data,
+        launched: launched?.data,
+        recovered: recovered?.data,
+        error: downloaded?.error ?? launched?.error ?? recovered?.error ?? null,
+      };
+    }),
+    isDefault: releaseIds === undefined,
+    error: candidatesQuery.error ?? focusQuery.error ?? null,
+    isFetching:
+      candidatesQuery.isFetching ||
+      focusQuery.isFetching ||
+      seriesQueries.some((query) => query.isFetching),
+    refresh: () => {
+      void candidatesQuery.refetch();
+      for (const query of seriesQueries) void query.refetch();
+    },
+  };
+}

package/src/lib/release-adoption-rpc.ts

@@ -0,0 +1,49 @@
+import { createServerFn } from "@tanstack/react-start";
+
+import { consoleAccess } from "./console-access";
+import {
+  readAdoptionReleaseInput,
+  readAdoptionReleasesInput,
+  readBundleEventsInput,
+} from "./release-adoption";
+
+export const listAdoptionReleasesRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
+  .validator(readAdoptionReleasesInput)
+  .handler(async ({ data }) => {
+    const [{ prepareConfig }, { listAdoptionReleases }] = await Promise.all([
+      import("./server/config.server"),
+      import("./server/releaseAdoption"),
+    ]);
+    const { core } = await prepareConfig();
+    return listAdoptionReleases(core, data);
+  });
+
+export const getAdoptionReleaseRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
+  .validator(readAdoptionReleaseInput)
+  .handler(async ({ data }) => {
+    const [{ prepareConfig }, { getAdoptionRelease }] = await Promise.all([
+      import("./server/config.server"),
+      import("./server/releaseAdoption"),
+    ]);
+    const { core } = await prepareConfig();
+    return getAdoptionRelease(core, data);
+  });
+
+export const getBundleEventsRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
+  .validator(readBundleEventsInput)
+  .handler(async ({ data }) => {
+    const [{ prepareConfig }, { getBundleEvents }, { requireFeature }] =
+      await Promise.all([
+        import("./server/config.server"),
+        import("./server/releaseAdoption"),
+        import("./server/runtime.server"),
+      ]);
+    const { runtime } = await prepareConfig();
+    return getBundleEvents(
+      await requireFeature(runtime, "insightsAnalytics"),
+      data,
+    );
+  });

package/src/lib/release-adoption.ts

@@ -0,0 +1,164 @@
+import { recoveryWindows } from "./insights-recovery";
+import type { InsightsWindow } from "./insights-rpc";
+
+/**
+ * Bundles Release health compares at most: the newest two and two more.
+ * Each is a read of its counts over the period, and four hues stay apart.
+ */
+export const MAX_ADOPTION_RELEASES = 4;
+/** Bundles Release health compares when none are chosen: the newest two. */
+export const DEFAULT_ADOPTION_RELEASES = 2;
+/** Bundle deployments Release health offers to add. */
+export const ADOPTION_CANDIDATES = 10;
+/** A crash rate at which Release health recommends rolling a bundle back. */
+export const CRASH_RATE_THRESHOLD = 0.05;
+/** Attempts below which a crash rate is too noisy to recommend anything. */
+export const CRASH_MIN_ATTEMPTS = 20;
+
+/** A deployed bundle, as Release health labels and rolls it back. */
+export type AdoptionRelease = {
+  readonly releaseId: string;
+  readonly bundleId: string;
+  readonly deployedAtMs: number;
+  readonly targetAppVersion: string | null;
+  readonly enabled: boolean;
+  readonly revision: number;
+};
+
+/** A channel and platform's newest bundle deployments. */
+export type AdoptionReleasesInput = {
+  readonly platform: "ios" | "android";
+  readonly channel: string;
+};
+
+/** One bundle deployment, and with `withPrevious` the one before it. */
+export type AdoptionReleaseInput = AdoptionReleasesInput & {
+  readonly releaseId: string;
+  readonly withPrevious?: boolean;
+};
+
+export type AdoptionReleaseResult = {
+  readonly release: AdoptionRelease | null;
+  readonly previous?: AdoptionRelease | null;
+};
+
+/**
+ * What Release health charts per bundle: downloads (download reports, and
+ * the downloads a launch or crash implied when its download report never
+ * arrived), launches (apply reports, and the kept reports that moved an
+ * installation to the bundle with no apply report), and recoveries.
+ */
+export type BundleEventType = "DOWNLOADED" | "LAUNCHED" | "RECOVERED";
+
+/** One bundle's reports of one type over the period that ends at `endMs`. */
+export type BundleEventsInput = AdoptionReleasesInput & {
+  readonly window: InsightsWindow;
+  /** The end of an hour; every bundle of one chart reads the same one. */
+  readonly endMs: number;
+  readonly bundleId: string;
+  readonly type: BundleEventType;
+};
+
+/**
+ * A bundle's counts of one type in each interval of the period, every
+ * interval present: downloads of it, launches of it, or recoveries from it.
+ * Each counts an installation once when it downloads the bundle, first
+ * reports running it, or crashes on it; one that comes back counts again.
+ */
+export type BundleEventsSeries = {
+  readonly bundleId: string;
+  readonly type: BundleEventType;
+  readonly measuredAtMs: number;
+  readonly points: readonly {
+    readonly startMs: number;
+    readonly events: number;
+  }[];
+  readonly total: number;
+};
+
+const HOUR_MS = 3_600_000;
+
+const isText = (value: unknown): value is string =>
+  typeof value === "string" && value.trim().length > 0 && value.length <= 1024;
+
+const invalid = (): never => {
+  throw new Error("Choose a platform, channel, period, and bundle.");
+};
+
+export function readAdoptionReleasesInput(
+  input: AdoptionReleasesInput,
+): AdoptionReleasesInput {
+  if (
+    !input ||
+    (input.platform !== "ios" && input.platform !== "android") ||
+    !isText(input.channel)
+  )
+    invalid();
+  return { platform: input.platform, channel: input.channel };
+}
+
+export function readAdoptionReleaseInput(
+  input: AdoptionReleaseInput,
+): AdoptionReleaseInput {
+  const scope = readAdoptionReleasesInput(input);
+  if (
+    !isText(input.releaseId) ||
+    (input.withPrevious !== undefined &&
+      typeof input.withPrevious !== "boolean")
+  )
+    invalid();
+  return {
+    ...scope,
+    releaseId: input.releaseId,
+    ...(input.withPrevious ? { withPrevious: true } : {}),
+  };
+}
+
+export function readBundleEventsInput(
+  input: BundleEventsInput,
+): BundleEventsInput {
+  const scope = readAdoptionReleasesInput(input);
+  if (
+    !Object.hasOwn(recoveryWindows, input.window) ||
+    typeof input.endMs !== "number" ||
+    !Number.isSafeInteger(input.endMs) ||
+    input.endMs <= 0 ||
+    input.endMs % HOUR_MS !== 0 ||
+    !isText(input.bundleId) ||
+    (input.type !== "DOWNLOADED" &&
+      input.type !== "LAUNCHED" &&
+      input.type !== "RECOVERED")
+  )
+    invalid();
+  return {
+    ...scope,
+    window: input.window,
+    endMs: input.endMs,
+    bundleId: input.bundleId,
+    type: input.type,
+  };
+}
+
+/**
+ * Of the installations that tried a bundle, the share whose launch crashed
+ * and rolled back: one that crashes never reports a launch, so attempts
+ * count both.
+ */
+export const crashRateOf = (launched: number, recovered: number) => {
+  const attempts = launched + recovered;
+  return { attempts, rate: attempts === 0 ? 0 : recovered / attempts };
+};
+
+/** Whether a bundle's crashes call for rolling it back. */
+export const recommendsRollback = (
+  release: Pick<AdoptionRelease, "enabled">,
+  launched: number,
+  recovered: number,
+) => {
+  const { attempts, rate } = crashRateOf(launched, recovered);
+  return (
+    release.enabled &&
+    attempts >= CRASH_MIN_ATTEMPTS &&
+    rate >= CRASH_RATE_THRESHOLD
+  );
+};

package/src/lib/remote-config-api.ts

@@ -0,0 +1,119 @@
+import {
+  keepPreviousData,
+  useInfiniteQuery,
+  useMutation,
+  useQuery,
+  useQueryClient,
+} from "@tanstack/react-query";
+
+import type { RemoteConfigTemplate } from "./remote-config-draft";
+import {
+  getRemoteConfigRpc,
+  getRemoteConfigVersionRpc,
+  listRemoteConfigVersionsRpc,
+  previewRemoteConfigRpc,
+  publishRemoteConfigRpc,
+  rollbackRemoteConfigRpc,
+} from "./remote-config-rpc";
+
+export const remoteConfigQueryKeys = {
+  all: ["remote-config"] as const,
+  active: ["remote-config", "active"] as const,
+  versions: ["remote-config", "versions"] as const,
+  version: (version: number) => ["remote-config", "version", version] as const,
+  preview: (input: unknown) => ["remote-config", "preview", input] as const,
+};
+
+/** The published template, read once a visit unless a publish changes it. */
+export const useRemoteConfigQuery = () =>
+  useQuery({
+    queryKey: remoteConfigQueryKeys.active,
+    queryFn: () => getRemoteConfigRpc(),
+    staleTime: 60_000,
+  });
+
+/** Published versions, newest first, a page at a time. */
+export const useRemoteConfigVersionsQuery = ({
+  enabled,
+}: {
+  readonly enabled: boolean;
+}) =>
+  useInfiniteQuery({
+    queryKey: remoteConfigQueryKeys.versions,
+    queryFn: ({ pageParam }) =>
+      listRemoteConfigVersionsRpc({
+        data: pageParam === undefined ? {} : { cursor: pageParam },
+      }),
+    initialPageParam: undefined as string | undefined,
+    getNextPageParam: (page) => page.next,
+    staleTime: 60_000,
+    enabled,
+  });
+
+/** One version with its template; a version never changes once published. */
+export const useRemoteConfigVersionQuery = (version: number | null) =>
+  useQuery({
+    queryKey: remoteConfigQueryKeys.version(version ?? 0),
+    queryFn: () => getRemoteConfigVersionRpc({ data: { version: version! } }),
+    enabled: version !== null,
+    staleTime: Infinity,
+  });
+
+const useRefreshAfterPublish = () => {
+  const queryClient = useQueryClient();
+  return async () => {
+    await Promise.all([
+      queryClient.invalidateQueries({ queryKey: remoteConfigQueryKeys.active }),
+      queryClient.invalidateQueries({
+        queryKey: remoteConfigQueryKeys.versions,
+      }),
+    ]);
+  };
+};
+
+export const usePublishRemoteConfigMutation = () => {
+  const refresh = useRefreshAfterPublish();
+  return useMutation({
+    mutationFn: (input: {
+      readonly template: RemoteConfigTemplate;
+      readonly baseVersion: number;
+      readonly description?: string;
+    }) => publishRemoteConfigRpc({ data: input }),
+    onSuccess: async (result) => {
+      if (result.status === "published" || result.status === "conflict") {
+        await refresh();
+      }
+    },
+  });
+};
+
+export const useRollbackRemoteConfigMutation = () => {
+  const refresh = useRefreshAfterPublish();
+  return useMutation({
+    mutationFn: (input: {
+      readonly version: number;
+      readonly baseVersion: number;
+    }) => rollbackRemoteConfigRpc({ data: input }),
+    onSuccess: refresh,
+  });
+};
+
+/** A device's view of the draft, kept on screen while the next one loads. */
+export const useRemoteConfigPreviewQuery = (input: {
+  readonly template: RemoteConfigTemplate;
+  /** The device's fields, and `now` to evaluate at a chosen time. */
+  readonly context: {
+    readonly platform?: string;
+    readonly channel?: string;
+    readonly appVersion?: string;
+    readonly cohort?: string;
+    readonly fingerprintHash?: string;
+    readonly now?: number;
+  };
+}) =>
+  useQuery({
+    queryKey: remoteConfigQueryKeys.preview(input),
+    queryFn: () => previewRemoteConfigRpc({ data: input }),
+    placeholderData: keepPreviousData,
+    staleTime: Infinity,
+  });