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

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

@@ -0,0 +1,196 @@
+import type {
+  RemoteConfigActive,
+  RemoteConfigEvaluatedParameter,
+  RemoteConfigEvaluationContext,
+  RemoteConfigTemplateIssue,
+  RemoteConfigVersionDetail,
+  RemoteConfigVersionsPage,
+} from "@hot-updater/server/plugins";
+import { createServerFn } from "@tanstack/react-start";
+
+import { consoleAccess } from "./console-access";
+import type { ConsolePublishResult } from "./server/remoteConfig";
+
+export type { ConsolePublishResult } from "./server/remoteConfig";
+
+/** What the preview shows: each parameter's value for the device, or what to fix first. */
+export type RemoteConfigPreview =
+  | {
+      readonly status: "ok";
+      readonly parameters: Readonly<
+        Record<string, RemoteConfigEvaluatedParameter>
+      >;
+    }
+  | {
+      readonly status: "invalid";
+      readonly issues: readonly RemoteConfigTemplateIssue[];
+    };
+
+/** Remote Config, once the console's access check and the feature guard pass. */
+const remoteConfig = async () => {
+  const [{ prepareConfig }, { requireFeature }] = await Promise.all([
+    import("./server/config.server"),
+    import("./server/runtime.server"),
+  ]);
+  const { runtime } = await prepareConfig();
+  return requireFeature(runtime, "remoteConfig");
+};
+
+const field = (input: unknown, key: string): unknown =>
+  typeof input === "object" && input !== null
+    ? Reflect.get(input, key)
+    : undefined;
+
+const versionNumber = (value: unknown, name: string): number => {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    throw new TypeError(`${name} must be a non-negative integer.`);
+  }
+  return value;
+};
+
+const parseCursor = (input: unknown): { readonly cursor?: string } => {
+  const cursor = field(input, "cursor");
+  if (cursor !== undefined && typeof cursor !== "string") {
+    throw new TypeError("cursor must be text.");
+  }
+  return cursor === undefined ? {} : { cursor };
+};
+
+const parseVersion = (input: unknown): { readonly version: number } => ({
+  version: versionNumber(field(input, "version"), "version"),
+});
+
+const parsePublish = (
+  input: unknown,
+): {
+  readonly template: unknown;
+  readonly baseVersion: number;
+  readonly description?: string;
+} => {
+  const description = field(input, "description");
+  if (description !== undefined && typeof description !== "string") {
+    throw new TypeError("description must be text.");
+  }
+  return {
+    template: field(input, "template"),
+    baseVersion: versionNumber(field(input, "baseVersion"), "baseVersion"),
+    ...(description === undefined ? {} : { description }),
+  };
+};
+
+const parseRollback = (
+  input: unknown,
+): { readonly version: number; readonly baseVersion: number } => ({
+  version: versionNumber(field(input, "version"), "version"),
+  baseVersion: versionNumber(field(input, "baseVersion"), "baseVersion"),
+});
+
+const CONTEXT_FIELDS = [
+  "platform",
+  "appVersion",
+  "channel",
+  "cohort",
+  "fingerprintHash",
+] as const;
+
+const parsePreview = (
+  input: unknown,
+): {
+  readonly template: unknown;
+  readonly context: RemoteConfigEvaluationContext;
+} => {
+  const raw = field(input, "context");
+  const context: Record<string, string> = {};
+  for (const key of CONTEXT_FIELDS) {
+    const value = field(raw, key);
+    if (typeof value === "string" && value.trim().length > 0) {
+      context[key] = value.trim();
+    }
+  }
+  if (
+    context.platform !== undefined &&
+    context.platform !== "ios" &&
+    context.platform !== "android"
+  ) {
+    throw new TypeError('platform must be "ios" or "android".');
+  }
+  const now = field(raw, "now");
+  if (now !== undefined && (typeof now !== "number" || !Number.isFinite(now))) {
+    throw new TypeError("now must be a time in milliseconds since the epoch.");
+  }
+  return {
+    template: field(input, "template"),
+    // Without a time, the preview evaluates at the server's clock, as devices do.
+    context: {
+      ...(context as RemoteConfigEvaluationContext),
+      now: now ?? Date.now(),
+    },
+  };
+};
+
+export const getRemoteConfigRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
+  .handler(
+    async (): Promise<RemoteConfigActive> => (await remoteConfig()).getActive(),
+  );
+
+export const listRemoteConfigVersionsRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
+  .validator(parseCursor)
+  .handler(
+    async ({ data }): Promise<RemoteConfigVersionsPage> =>
+      (await remoteConfig()).listVersions({ limit: 20, ...data }),
+  );
+
+export const getRemoteConfigVersionRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
+  .validator(parseVersion)
+  .handler(
+    async ({ data }): Promise<RemoteConfigVersionDetail | null> =>
+      (await remoteConfig()).getVersion(data.version),
+  );
+
+export const publishRemoteConfigRpc = createServerFn({ method: "POST" })
+  .middleware([consoleAccess])
+  .validator(parsePublish)
+  .handler(
+    async ({ data }): Promise<ConsolePublishResult> =>
+      (await remoteConfig()).publish(data),
+  );
+
+export const rollbackRemoteConfigRpc = createServerFn({ method: "POST" })
+  .middleware([consoleAccess])
+  .validator(parseRollback)
+  .handler(
+    async ({
+      data,
+    }): Promise<ConsolePublishResult | { readonly status: "not_found" }> =>
+      (await remoteConfig()).rollback(data),
+  );
+
+/** What a device with `context` would receive from a template, published or not. */
+export const previewRemoteConfigRpc = createServerFn({ method: "POST" })
+  .middleware([consoleAccess])
+  .validator(parsePreview)
+  .handler(async ({ data }): Promise<RemoteConfigPreview> => {
+    await remoteConfig();
+    const {
+      evaluateRemoteConfig,
+      RemoteConfigValidationError,
+      validateRemoteConfigTemplate,
+    } = await import("@hot-updater/server/plugins");
+    try {
+      return {
+        status: "ok",
+        parameters: evaluateRemoteConfig(
+          validateRemoteConfigTemplate(data.template),
+          data.context,
+        ),
+      };
+    } catch (error) {
+      if (error instanceof RemoteConfigValidationError) {
+        return { status: "invalid", issues: error.issues };
+      }
+      throw error;
+    }
+  });

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/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

@@ -1,37 +1,36 @@
-import type { InsightsModel } from "@hot-updater/plugin-core";
+import type {
+  InsightsModel,
+  ReleaseReference,
+} from "@hot-updater/server/plugins";
 
 import type { BundleActivityInput } from "../bundle-activity";
-import type { RecoveryReport } from "../insights-recovery";
-import { readInsightsHistory } from "./insightsHistory";
-import { buildRecoveryReport } from "./insightsRecovery";
 
 export async function getBundleActivity(
   model: InsightsModel,
   inputs: readonly BundleActivityInput[],
-  now = Date.now(),
 ) {
   if (inputs.length === 0) return {};
-  // One bounded read for the visible page, independent of the management query.
-  const history = await readInsightsHistory(model, "30d", now);
-  const scopes = new Map<string, RecoveryReport>();
-  const result = new Map<string, RecoveryReport>();
-  for (const input of inputs) {
-    const key = JSON.stringify([input.platform, input.channel]);
-    let report = scopes.get(key);
-    if (!report) {
-      report = buildRecoveryReport(history, {
-        platform: input.platform,
-        channel: input.channel,
-        window: "30d",
-      });
-      scopes.set(key, report);
-    }
-    result.set(input.releaseId, {
-      ...report,
-      series: report.series.filter(
-        (series) => series.releaseId === input.releaseId,
-      ),
-    });
-  }
-  return Object.fromEntries(result);
+  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,
+                launched: item.metrics.applies,
+                failedLaunches: item.metrics.failedLaunches,
+                measuredAtMs: activity.measuredAtMs,
+              },
+            ],
+          ],
+    ),
+  );
 }

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

@@ -1,98 +1,45 @@
-import {
-  assertStorageOperations,
-  createDatabaseClient,
-  type DatabaseClient,
-  type StoragePluginWith,
-} from "@hot-updater/plugin-core";
+import type { HotUpdaterCoreApi } from "@hot-updater/plugin-core";
 import { getRequest } from "@tanstack/react-start/server";
 
-import type { ResolvedHotUpdaterConsoleConfig } from "../../index";
 import { requireConsoleAccess } from "./auth.server";
-import { resolveConsoleConfig } from "./console-runtime.server";
-
-type ResolvedConsoleConfig = ResolvedHotUpdaterConsoleConfig & {
-  readonly console: NonNullable<ResolvedHotUpdaterConsoleConfig["console"]>;
-};
+import {
+  resolveConsoleConfig,
+  type ResolvedConsoleConfig,
+} from "./console-runtime.server";
+import type { ConsoleRuntime } from "./runtime.server";
 
 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 storagePluginPromise: Promise<
-  StoragePluginWith<"get" | "put" | "exists" | "delete">
-> | null = null;
+let core: HotUpdaterCoreApi | null = null;
+let runtime: ConsoleRuntime | null = null;
 
 const loadCachedConfig = async (request: Request) => {
   if (!configPromise) {
-    configPromise = resolveConsoleConfig(request)
-      .then((config) => ({
-        ...config,
-        console: config.console ?? {},
-      }))
-      .catch((error) => {
-        configPromise = null;
-        throw error;
-      });
+    configPromise = resolveConsoleConfig(request).catch((error) => {
+      configPromise = null;
+      throw error;
+    });
   }
 
   return configPromise;
 };
 
-const loadCachedStoragePlugin = async (config: ResolvedConsoleConfig) => {
-  if (!storagePluginPromise) {
-    storagePluginPromise = Promise.resolve(config.storage)
-      .then((storagePlugin) => {
-        assertStorageOperations(storagePlugin, [
-          "get",
-          "put",
-          "exists",
-          "delete",
-        ]);
-        return storagePlugin;
-      })
-      .catch((error) => {
-        storagePluginPromise = null;
-        throw error;
-      });
-  }
-
-  return storagePluginPromise;
-};
-
 export const prepareConfig = async (request: Request = getRequest()) => {
   try {
     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 assembled as the
+    // server's, on the server's own path, or a self-hosted server's admin API.
+    core ??= config.core;
 
-    if (!apiKeyStoreResolved) {
-      const { createApiKeyStore } = await import("./runtime.server");
-      apiKeyStore = createApiKeyStore(config);
-      apiKeyStoreResolved = true;
+    // The console's features: those of the plugins its config lists.
+    if (!runtime) {
+      const { createConsoleRuntime } = await import("./runtime.server");
+      runtime = createConsoleRuntime(config);
     }
 
-    const storagePlugin = await loadCachedStoragePlugin(config);
-
-    return {
-      config,
-      databaseClient,
-      hotUpdater,
-      apiKeyStore,
-      storagePlugin,
-    };
+    // Each bundle file is read and deleted with its protocol's storage.
+    return { config, core, runtime, storage: config.storage };
   } catch (error) {
     if (
       !(
@@ -105,5 +52,3 @@ export const prepareConfig = async (request: Request = getRequest()) => {
     throw error;
   }
 };
-
-export const isConfigLoaded = () => Boolean(configPromise);

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

@@ -0,0 +1,70 @@
+import type { RemoteDatabase } from "@hot-updater/plugin-core";
+import {
+  type ApiKeyManagementAPI,
+  createInsightsAdminReads,
+  createInsightsModel,
+  createInsightsReads,
+  type InsightsApi,
+  type InsightsModel,
+  type RemoteConfigApi,
+} from "@hot-updater/server/plugins";
+
+import {
+  type ConsoleFeature,
+  ConsoleFeatureUnavailableError,
+} from "../console-features";
+import {
+  type ConsoleRemoteConfig,
+  createAdminRemoteConfig,
+  createLocalRemoteConfig,
+} from "./remoteConfig";
+
+/** 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: createInsightsReads,
+    remote: (fetchAdmin: FetchAdmin) =>
+      createInsightsAdminReads(fetchAdmin, {
+        unavailable: () =>
+          new ConsoleFeatureUnavailableError("insights", { remote: true }),
+      }),
+  }),
+  insightsAnalytics: featureApi({
+    local: (api: InsightsApi): InsightsModel => createInsightsModel(api),
+  }),
+  remoteConfig: featureApi({
+    local: (api: RemoteConfigApi): ConsoleRemoteConfig =>
+      createLocalRemoteConfig(api),
+    remote: createAdminRemoteConfig,
+  }),
+  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,42 +1,61 @@
+import {
+  type AnyHotUpdaterPlugin,
+  type ConfiguredDatabase,
+  createMemoryAdapter,
+  type EngineDatabase,
+  type HotUpdaterCoreApi,
+  isRemoteDatabase,
+  type StorageAdapter,
+} from "@hot-updater/plugin-core";
+import { createHotUpdater } from "@hot-updater/server";
+
 import type {
   ConsoleAuthAdapter,
-  ConsoleSigningConfig,
   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;
-};
+/** What the console runs on, assembled from its config as the server is. */
+export interface ResolvedConsoleConfig {
+  readonly gitUrl?: string;
+  /** The server's database, or its admin API. */
+  readonly database: ConfiguredDatabase;
+  /**
+   * Core's API, assembled over the database as the server assembles it, so
+   * the console's writes take the server's path, or a self-hosted server's
+   * admin API.
+   */
+  readonly core: HotUpdaterCoreApi;
+  /** The server's storage, which reads the bundle files. */
+  readonly storage: StorageAdapter;
+  /** The plugins the server runs, as the config lists them. */
+  readonly plugins: readonly AnyHotUpdaterPlugin[];
+  /**
+   * The plugins' APIs by id, which serve their features; absent over a
+   * self-hosted server's admin API, whose plugins run on the server.
+   */
+  readonly api?: Readonly<Record<string, unknown>>;
+}
 
-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),
-  };
-};
+/**
+ * Core and the plugins over `database`, assembled by `createHotUpdater` as
+ * the server assembles them, with public client routes unless a plugin
+ * provides clientAuth: the console mounts no handlers. cli-tools'
+ * `assembleServer` does the same for the CLI; the console keeps its own
+ * copy, since a hosted console never loads cli-tools.
+ */
+const assemble = (
+  database: EngineDatabase,
+  storage: StorageAdapter,
+  plugins: readonly AnyHotUpdaterPlugin[],
+) =>
+  createHotUpdater({
+    database,
+    storage,
+    plugins,
+    ...(plugins.some((plugin) => plugin.provides?.clientAuth)
+      ? {}
+      : { clientAccess: "public" }),
+  } as Parameters<typeof createHotUpdater>[0]);
 
 export const getConsoleAuthAdapter = async (): Promise<ConsoleAuthAdapter> => {
   const module = await import("virtual:hot-updater-console/auth");
@@ -45,17 +64,42 @@ export const getConsoleAuthAdapter = async (): Promise<ConsoleAuthAdapter> => {
 
 export const resolveConsoleConfig = async (
   request: Request,
-): Promise<ResolvedHotUpdaterConsoleConfig> => {
+): Promise<ResolvedConsoleConfig> => {
   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);
+  const { database, storage, plugins = [] } = config;
+  const gitUrl =
+    config.console?.gitUrl === undefined
+      ? {}
+      : { gitUrl: config.console.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.
+  if (isRemoteDatabase(database)) {
+    const checked = assemble(
+      { name: "memory", adapter: createMemoryAdapter() },
+      storage,
+      plugins,
+    );
+    return {
+      ...gitUrl,
+      database,
+      core: database.core,
+      storage,
+      plugins: checked.plugins,
+    };
+  }
+  const server = assemble(database, storage, plugins);
   return {
-    ...configWithoutSigning,
-    ...(signing === undefined ? {} : { signing }),
+    ...gitUrl,
+    database,
+    core: server.core,
+    storage,
+    plugins: server.plugins,
+    api: server.api,
   };
 };