@hot-updater/console 1.1.4 → 1.2.0-rc.1

package/src/lib/api.ts

@@ -13,8 +13,13 @@ import {
   getBundleChildren,
   getChannels,
   getConfig,
+  getNativeBuildDetail,
+  getNativeBuildDownloadUrl,
+  getNativeBuildPatches,
+  getNativeBuilds,
   getRelease,
   getReleaseCatalogDiagnostics,
+  getReleaseNativeBuild,
   getReleases,
   preflightRelease as preflightReleaseApi,
   promoteRelease as promoteReleaseApi,
@@ -40,8 +45,45 @@ export const queryKeys = {
       ["bundle-children", "counts", ...bundleIds] as const,
   },
   bundle: (bundleId: string) => ["bundle", bundleId] as const,
+  nativeBuilds: {
+    all: ["native-builds"] as const,
+    list: (page: NativeBuildPage) => ["native-builds", page] as const,
+  },
+  nativeBuild: (id: string) => ["native-build", id] as const,
+  nativeBuildPatches: (minBundleId: string, page: KeysetPage) =>
+    ["native-build-patches", minBundleId, page] as const,
+  nativeBuildDownloadUrl: (id: string) =>
+    ["native-build-download-url", id] as const,
+  releaseNativeBuild: (release: ReleaseNativeBuildInput) =>
+    ["release-native-build", release] as const,
+};
+
+export type KeysetPage = {
+  /** Rows older than this key: the next page. */
+  before?: string;
+  /** Rows newer than this key: the previous page. */
+  after?: string;
+};
+
+export type NativeBuildPage = KeysetPage & {
+  /** Only the builds that embed this channel. */
+  channel?: string;
+};
+
+export type ReleaseNativeBuildInput = {
+  platform: "ios" | "android";
+  channel: string;
+  fingerprintHash: string | null;
+  targetAppVersion: string | null;
 };
 
+/**
+ * How often an open install QR reads its download URL again. Storage gives
+ * no lifetime with the URL, and adapters let it be configured down to
+ * minutes, so the QR never shows one older than this.
+ */
+const DOWNLOAD_URL_REFRESH_MS = 30_000;
+
 export type ReleaseFilters = {
   /** One of the filter sets the release indexes serve; none lists every release. */
   filter?: ReleaseFilter;
@@ -125,6 +167,84 @@ export function useBundleChildCountsQuery(bundleIds: string[]) {
   });
 }
 
+/** One page of native builds, newest first, kept on screen while the next loads. */
+export function useNativeBuildsQuery(page: NativeBuildPage) {
+  return useQuery({
+    queryKey: queryKeys.nativeBuilds.list(page),
+    queryFn: () => getNativeBuilds({ data: page }),
+    placeholderData: (previousData) => previousData,
+    staleTime: 60_000,
+  });
+}
+
+/**
+ * A native build's page in one round trip, or null for an unknown ID. The
+ * page reads it again when it opens, since its catalog and patches change
+ * with each deploy.
+ */
+export function useNativeBuildDetailQuery(id: string) {
+  return useQuery({
+    queryKey: queryKeys.nativeBuild(id),
+    queryFn: () => getNativeBuildDetail({ data: { id } }),
+    enabled: id.length > 0,
+  });
+}
+
+/**
+ * A page of patches from a built-in bundle other than the newest, which the
+ * build's page already holds; kept on screen while the next one loads.
+ */
+export function useNativeBuildPatchesQuery(
+  minBundleId: string,
+  page: KeysetPage,
+  enabled: boolean,
+) {
+  return useQuery({
+    queryKey: queryKeys.nativeBuildPatches(minBundleId, page),
+    queryFn: () => getNativeBuildPatches({ data: { minBundleId, ...page } }),
+    enabled: enabled && minBundleId.length > 0,
+    placeholderData: (previousData) => previousData,
+  });
+}
+
+/**
+ * The newest native build of a release's scope, or none: read only for a
+ * release one build can serve, by its fingerprint or one exact app version.
+ */
+export function useReleaseNativeBuildQuery(
+  release: ReleaseNativeBuildInput | null,
+) {
+  return useQuery({
+    queryKey: queryKeys.releaseNativeBuild(
+      release ?? {
+        platform: "ios",
+        channel: "",
+        fingerprintHash: null,
+        targetAppVersion: null,
+      },
+    ),
+    queryFn: () => getReleaseNativeBuild({ data: release! }),
+    enabled: release !== null,
+    staleTime: 60_000,
+  });
+}
+
+/**
+ * The storage URL a phone downloads a build from, read while the install
+ * QR is open and again before it expires.
+ */
+export function useNativeBuildDownloadUrlQuery(id: string, enabled: boolean) {
+  return useQuery({
+    queryKey: queryKeys.nativeBuildDownloadUrl(id),
+    queryFn: () => getNativeBuildDownloadUrl({ data: { id } }),
+    enabled,
+    staleTime: DOWNLOAD_URL_REFRESH_MS,
+    // A storage without download URLs has none to refresh.
+    refetchInterval: (query) =>
+      query.state.data?.url === null ? false : DOWNLOAD_URL_REFRESH_MS,
+  });
+}
+
 // Mutation Hooks
 export function useCreateChannelMutation() {
   const queryClient = useQueryClient();

package/src/lib/native-builds.ts

@@ -0,0 +1,162 @@
+import type {
+  NativeBuildArtifactKind,
+  NativeBuildRow,
+  NativeBuildScope,
+} from "@hot-updater/plugin-core";
+import {
+  canonicalizeAppVersion,
+  createReleaseCatalogScopeKey,
+  decodeChannelKey,
+  encodeChannelKey,
+} from "@hot-updater/protocol";
+
+import { shellQuote } from "./shell";
+
+/** How each artifact installs, as the Console's install dialog shows it. */
+export const nativeBuildArtifacts: Record<
+  NativeBuildArtifactKind,
+  { readonly label: string; readonly installs: string }
+> = {
+  apk: { label: "APK", installs: "Android device or emulator" },
+  aab: { label: "AAB", installs: "Google Play or bundletool" },
+  app: { label: "Simulator app", installs: "iOS Simulator" },
+  ipa: { label: "IPA", installs: "registered iOS devices" },
+};
+
+/** A platform's name as the console shows it. */
+export const platformLabel = (platform: "ios" | "android") =>
+  platform === "ios" ? "iOS" : "Android";
+
+/** The console route that redirects to a build's artifact in storage. */
+export const nativeBuildDownloadPath = (id: string) =>
+  `/api/native-builds/${encodeURIComponent(id)}/download`;
+
+/** The console page of one native build. */
+export const nativeBuildDetailPath = (id: string) =>
+  `/native-builds/${encodeURIComponent(id)}`;
+
+const CHANNEL_ID_PREFIX = "channel:";
+
+/** A channel row's ID, `channel:` and its channel key. */
+export const channelIdOf = (channel: string) =>
+  `${CHANNEL_ID_PREFIX}${encodeChannelKey(channel)}`;
+
+/** The name of the channel a build embeds, decoded from its channel ID: no read. */
+export const nativeBuildChannel = (build: Pick<NativeBuildRow, "channel_id">) =>
+  decodeChannelKey(build.channel_id.slice(CHANNEL_ID_PREFIX.length));
+
+/** The scope a build was registered in, as `findNativeBuild` takes it. */
+export const nativeBuildScope = (build: NativeBuildRow): NativeBuildScope =>
+  build.fingerprint_hash === null
+    ? {
+        platform: build.platform,
+        channel: nativeBuildChannel(build),
+        fingerprintHash: null,
+        appVersion: build.app_version ?? "",
+      }
+    : {
+        platform: build.platform,
+        channel: nativeBuildChannel(build),
+        fingerprintHash: build.fingerprint_hash,
+        appVersion: null,
+      };
+
+/**
+ * The Release Catalog scope whose releases an install of the build is
+ * offered. A fingerprint build's scope key is that catalog's own key; an
+ * app-version build's adds its exact app version, which the catalog of
+ * every app version leaves out.
+ */
+export const nativeBuildCatalogScopeKey = (build: NativeBuildRow): string => {
+  const channelKey = build.channel_id.slice(CHANNEL_ID_PREFIX.length);
+  return build.fingerprint_hash === null
+    ? createReleaseCatalogScopeKey({
+        channelKey,
+        platform: build.platform,
+        strategy: "APP_VERSION",
+      })
+    : createReleaseCatalogScopeKey({
+        channelKey,
+        fingerprintHash: build.fingerprint_hash,
+        platform: build.platform,
+        strategy: "FINGERPRINT",
+      });
+};
+
+/**
+ * The native build scope a release serves, or null when no one build has
+ * it: a release of an app version range, rather than one exact version,
+ * targets many builds.
+ */
+export const releaseNativeBuildScope = (release: {
+  readonly platform: "ios" | "android";
+  readonly channel: string;
+  readonly fingerprintHash: string | null;
+  readonly targetAppVersion: string | null;
+}): NativeBuildScope | null => {
+  if (release.fingerprintHash !== null) {
+    return {
+      platform: release.platform,
+      channel: release.channel,
+      fingerprintHash: release.fingerprintHash,
+      appVersion: null,
+    };
+  }
+  const target = release.targetAppVersion;
+  if (target === null || canonicalizeAppVersion(target) !== target) {
+    return null;
+  }
+  return {
+    platform: release.platform,
+    channel: release.channel,
+    fingerprintHash: null,
+    appVersion: target,
+  };
+};
+
+/**
+ * The artifact's file name, the last path segment of its storage URI, so a
+ * public URL's query or fragment stays out of it.
+ */
+export const nativeBuildFileName = (build: NativeBuildRow): string => {
+  const path = build.artifact_storage_uri.split(/[?#]/, 1)[0] ?? "";
+  const segment = path.split("/").at(-1) ?? "";
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+};
+
+/** What the build compiled in: its app version, or its fingerprint. */
+export const nativeBuildTarget = (build: NativeBuildRow) =>
+  build.app_version === null
+    ? { label: "Fingerprint", value: build.fingerprint_hash ?? "" }
+    : { label: "App version", value: build.app_version };
+
+const UNITS = ["B", "KB", "MB", "GB"] as const;
+
+/** A byte count in the largest unit that keeps it at or above 1. */
+export const formatByteSize = (bytes: number): string => {
+  let value = bytes;
+  let unit = 0;
+  while (value >= 1024 && unit < UNITS.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${unit === 0 ? value : value.toFixed(1)} ${UNITS[unit]}`;
+};
+
+/**
+ * The commands that install a simulator build: unzip the download, then
+ * install the `.app` on the booted simulator.
+ */
+export const simulatorInstallCommand = (build: NativeBuildRow) => {
+  const archive = nativeBuildFileName(build);
+  const app = archive.replace(/\.zip$/, "");
+  return `unzip -o ${shellQuote(archive)} && xcrun simctl install booted ${shellQuote(app)}`;
+};
+
+/** The command that installs a downloaded APK on an Android device or emulator. */
+export const apkInstallCommand = (build: NativeBuildRow) =>
+  `adb install -r ${shellQuote(nativeBuildFileName(build))}`;

package/src/lib/qr-code.ts

@@ -0,0 +1,16 @@
+import { encode } from "uqr";
+
+/**
+ * A QR code of `value` as one SVG path of unit squares, with the standard
+ * four-module quiet zone: `size` is the side of its viewBox.
+ */
+export const qrCodePath = (value: string): { size: number; path: string } => {
+  const { data, size } = encode(value, { ecc: "M", border: 4 });
+  let path = "";
+  data.forEach((row, y) =>
+    row.forEach((dark, x) => {
+      if (dark) path += `M${x} ${y}h1v1h-1z`;
+    }),
+  );
+  return { size, path };
+};

package/src/lib/schema-migration-api.ts

@@ -0,0 +1,54 @@
+import { queryOptions, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useCallback, useSyncExternalStore } from "react";
+
+import { getSchemaMigrationRpc } from "./schema-migration-rpc";
+
+export const schemaMigrationQueryKey = ["schema-migration"] as const;
+
+export const schemaMigrationQueryOptions = () =>
+  queryOptions({
+    queryKey: schemaMigrationQueryKey,
+    queryFn: () => getSchemaMigrationRpc(),
+    retry: false,
+  });
+
+const isSchemaQuery = (queryKey: readonly unknown[]) =>
+  queryKey[0] === schemaMigrationQueryKey[0];
+
+/**
+ * The schema fence's refusal of the console's database, asked for once any
+ * page's read fails, so a healthy console reads nothing more. `retry` asks
+ * again, and once the fence passes, reads the failed pages again.
+ */
+export const useSchemaMigration = () => {
+  const queryClient = useQueryClient();
+  const cache = queryClient.getQueryCache();
+  const failing = useSyncExternalStore(
+    (onChange) => cache.subscribe(onChange),
+    () =>
+      cache
+        .getAll()
+        .some(
+          ({ queryKey, state }) =>
+            !isSchemaQuery(queryKey) && state.fetchFailureCount > 0,
+        ),
+    () => false,
+  );
+  const { data } = useQuery({
+    ...schemaMigrationQueryOptions(),
+    enabled: failing,
+  });
+  const retry = useCallback(async () => {
+    const status = await queryClient.fetchQuery({
+      ...schemaMigrationQueryOptions(),
+      staleTime: 0,
+    });
+    if (status !== null) return;
+    await queryClient.resetQueries({
+      predicate: ({ queryKey, state }) =>
+        !isSchemaQuery(queryKey) &&
+        (state.fetchFailureCount > 0 || state.status === "error"),
+    });
+  }, [queryClient]);
+  return { status: data ?? null, retry };
+};

package/src/lib/schema-migration-rpc.ts

@@ -0,0 +1,26 @@
+import { createServerFn } from "@tanstack/react-start";
+
+import { consoleAccess } from "./console-access";
+import {
+  type SchemaMigrationStatus,
+  schemaMigrationOf,
+} from "./schema-migration";
+
+/**
+ * Whether the schema fence refuses the console's database, and what it
+ * found: one read through core, which the console makes only after a page's
+ * read failed. Null when the read passes or fails for another reason, which
+ * the page reports itself.
+ */
+export const getSchemaMigrationRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
+  .handler(async (): Promise<SchemaMigrationStatus | null> => {
+    const { prepareConfig } = await import("./server/config.server");
+    const { config, core } = await prepareConfig();
+    try {
+      await core.listChannels();
+      return null;
+    } catch (error) {
+      return schemaMigrationOf(error, config.plugins);
+    }
+  });

package/src/lib/schema-migration.ts

@@ -0,0 +1,101 @@
+/** A schema setting the fence found missing or different. */
+export interface SchemaSetting {
+  readonly key: string;
+  readonly expected: string;
+  readonly found: string | null;
+}
+
+/**
+ * The database needs migrations before the console can read it: what the
+ * schema fence reported, as plain data. TanStack Start sends a thrown error
+ * as its message alone, so the console asks for this separately.
+ */
+export interface SchemaMigrationStatus {
+  readonly message: string;
+  readonly settings: readonly SchemaSetting[];
+  /** The plugins whose tables a migration has yet to create or change. */
+  readonly plugins: readonly string[];
+  /**
+   * Whether a migration moves it forward: every setting is missing or older.
+   * False for a database a newer release migrated, a different storage
+   * layout, or a v0 database, which doctor reports and nothing moves.
+   */
+  readonly migratable: boolean;
+}
+
+/** Compares dotted numeric versions, such as "1" and "1.2.0"; NaN when either is not one. */
+const compareVersions = (left: string, right: string): number => {
+  const parse = (version: string) => version.split(".").map(Number);
+  const [a, b] = [parse(left), parse(right)];
+  if ([...a, ...b].some(Number.isNaN)) return Number.NaN;
+  for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+    const difference = (a[index] ?? 0) - (b[index] ?? 0);
+    if (difference !== 0) return difference;
+  }
+  return 0;
+};
+
+/** The brand Hot Updater's own plugin factories set, read as the server reads it. */
+const OFFICIAL = Symbol.for("@hot-updater/server/official-plugin");
+
+/**
+ * Whether a migration moves a setting forward: a missing one, or an older
+ * version of core's or of one of Hot Updater's own plugins. Another plugin's
+ * changed tables need its own migration.
+ */
+const migrates = (
+  { key, expected, found }: SchemaSetting,
+  official: ReadonlySet<string>,
+) =>
+  found === null ||
+  ((key === "schema.core" || official.has(key)) &&
+    compareVersions(found, expected) < 0);
+
+/**
+ * The fence's refusal in `error`, recognized by name: plugin-core may be
+ * another copy than the console's. Null for any other error.
+ */
+export const schemaMigrationOf = (
+  error: unknown,
+  /** The plugins the console's config lists. */
+  plugins: readonly unknown[] = [],
+): SchemaMigrationStatus | null => {
+  if (
+    !(error instanceof Error) ||
+    error.name !== "HotUpdaterSchemaMigrationRequiredError"
+  ) {
+    return null;
+  }
+  const official = new Set(
+    plugins.flatMap((plugin) =>
+      typeof plugin === "object" &&
+      plugin !== null &&
+      Reflect.get(plugin, OFFICIAL) === true
+        ? [`schema.${String(Reflect.get(plugin, "id"))}`]
+        : [],
+    ),
+  );
+  const {
+    settings = [],
+    plugins: refused = [],
+    currentVersion,
+  } = error as Error & {
+    readonly settings?: readonly SchemaSetting[];
+    readonly plugins?: readonly string[];
+    /** A v0 database's schema version. */
+    readonly currentVersion?: string;
+  };
+  return {
+    message: error.message,
+    settings: settings.map(({ key, expected, found }) => ({
+      key,
+      expected,
+      found,
+    })),
+    plugins: [...refused],
+    migratable:
+      currentVersion === undefined &&
+      settings.length > 0 &&
+      settings.every((setting) => migrates(setting, official)),
+  };
+};

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

@@ -23,23 +23,32 @@ const loadCachedConfig = async (request: Request) => {
   return configPromise;
 };
 
+/**
+ * The console's config, core, and features, without the access check: for
+ * routes that take no session, such as a channel link's QR code. Everything
+ * else goes through {@link prepareConfig}.
+ */
+export const loadConsole = async (request: Request = getRequest()) => {
+  const config = await loadCachedConfig(request);
+
+  // Bundles, releases, catalogs, and channels: core assembled as the
+  // server's, on the server's own path, or a self-hosted server's admin API.
+  core ??= config.core;
+
+  // The console's features: those of the plugins its config lists.
+  if (!runtime) {
+    const { createConsoleRuntime } = await import("./runtime.server");
+    runtime = createConsoleRuntime(config);
+  }
+
+  // Each bundle file is read and deleted with its protocol's storage.
+  return { config, core, runtime, storage: config.storage };
+};
+
 export const prepareConfig = async (request: Request = getRequest()) => {
   try {
     await requireConsoleAccess(request);
-    const config = await loadCachedConfig(request);
-
-    // Bundles, releases, catalogs, and channels: core assembled as the
-    // server's, on the server's own path, or a self-hosted server's admin API.
-    core ??= config.core;
-
-    // The console's features: those of the plugins its config lists.
-    if (!runtime) {
-      const { createConsoleRuntime } = await import("./runtime.server");
-      runtime = createConsoleRuntime(config);
-    }
-
-    // Each bundle file is read and deleted with its protocol's storage.
-    return { config, core, runtime, storage: config.storage };
+    return await loadConsole(request);
   } catch (error) {
     if (
       !(

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

@@ -72,10 +72,8 @@ export const resolveConsoleConfig = async (
 
   const config = typeof source === "function" ? await source(request) : source;
   const { database, storage, plugins = [] } = config;
-  const gitUrl =
-    config.console?.gitUrl === undefined
-      ? {}
-      : { gitUrl: config.console.gitUrl };
+  const { gitUrl } = config.console ?? {};
+  const consoleOptions = gitUrl === undefined ? {} : { gitUrl };
   // A self-hosted server runs the plugins itself: core is its admin API.
   // The plugins are still checked as the server checks them, on a database
   // nothing reads, so one the server would refuse is refused here too.
@@ -86,7 +84,7 @@ export const resolveConsoleConfig = async (
       plugins,
     );
     return {
-      ...gitUrl,
+      ...consoleOptions,
       database,
       core: database.core,
       storage,
@@ -95,7 +93,7 @@ export const resolveConsoleConfig = async (
   }
   const server = assemble(database, storage, plugins);
   return {
-    ...gitUrl,
+    ...consoleOptions,
     database,
     core: server.core,
     storage,