@hot-updater/server 0.36.7 → 1.0.0-rc.0

package/src/createHotUpdaterCore.ts

@@ -1,55 +1,109 @@
-import type {
-  DatabasePlugin,
-  HotUpdaterContext,
-  RuntimeStoragePlugin,
+import {
+  assertStorageOperations,
+  type StoragePlugin,
 } from "@hot-updater/plugin-core";
-import { assertRuntimeStoragePlugin } from "@hot-updater/plugin-core";
 
-import { createPluginDatabaseCore } from "./db/pluginCore";
+import { createAnalyticsProvider } from "./analytics/bounded/provider";
+import type { AnalyticsProvider } from "./analytics/types";
+import {
+  authenticateApiKey,
+  createApiKeyManagement,
+  normalizeApiKeyHeaderName,
+} from "./apiKeys";
+import type { ApiKeyManagementAPI } from "./apiKeys";
+import { createDatabasePluginCore } from "./db/databasePluginCore";
 import { createSchemaReadinessChecker } from "./db/schemaReadiness";
 import {
-  type DatabaseAdapter,
   type DatabaseAdapterCapabilities,
   type DatabaseAPI,
+  type DatabasePlugin,
   isDatabasePlugin,
-  isDatabasePluginFactory,
-  type StoragePluginFactory,
 } from "./db/types";
-import { createHandler, type HandlerRoutes } from "./handler";
-import { normalizeBasePath } from "./route";
+import { createHotUpdaterHandlers, type HotUpdaterHandlers } from "./handler";
 import { createStorageAccess } from "./storageAccess";
 
-export type RuntimeHotUpdaterAPI<TContext = unknown> = DatabaseAPI<TContext> & {
-  readonly basePath: string;
-  readonly handler: (
-    request: Request,
-    context?: HotUpdaterContext<TContext>,
-  ) => Promise<Response>;
+export type RuntimeHotUpdaterAPI = DatabaseAPI & {
+  readonly handlers: HotUpdaterHandlers;
   readonly adapterName: string;
+  /**
+   * Built-in Analytics provider. Client ingestion and admin query routes are
+   * always mounted; React Native clients independently opt into lifecycle
+   * reporting with `HotUpdater.init({ analytics: true })`.
+   */
+  readonly analytics: AnalyticsProvider;
+  /**
+   * In-process API key lifecycle operations for trusted server tooling.
+   * Creation returns the plaintext once; list and revoke expose only metadata.
+   * This capability is never mounted on the client or admin HTTP handlers.
+   */
+  readonly apiKeys: ApiKeyManagementAPI;
 };
 
-export type HotUpdaterAPI<TContext = unknown> = RuntimeHotUpdaterAPI<TContext>;
+export type HotUpdaterAPI = RuntimeHotUpdaterAPI;
 
-export interface CreateHotUpdaterOptions<TContext = unknown> {
-  readonly database: DatabaseAdapter<TContext>;
-  readonly storages?: readonly (
-    | RuntimeStoragePlugin<TContext>
-    | StoragePluginFactory<TContext>
-  )[];
+export type ClientAccessPolicy =
+  | {
+      /**
+       * Leaves Release Catalog, artifact, and Analytics ingestion routes
+       * publicly accessible without a client credential.
+       */
+      readonly type: "public";
+    }
+  | {
+      /**
+       * Requires a key registered in `database.models.apiKeys` for
+       * Release Catalog, artifact, and Analytics ingestion requests.
+       */
+      readonly type: "api-key";
+      /**
+       * Request header containing the API key. Defaults to
+       * `x-api-key`. Clients must send the same header; Release Catalog
+       * responses include it in `Vary` to preserve cache isolation.
+       */
+      readonly headerName?: string;
+    };
+
+export interface CreateHotUpdaterOptions {
+  readonly database: DatabasePlugin;
   /**
-   * @deprecated Use `storages` instead. This field will be removed in a future version.
+   * Required client-route access policy. This choice is explicit so a server
+   * cannot accidentally change between public and authenticated OTA access.
+   * `/version`, storage downloads, and admin-handler routes are unaffected.
    */
-  readonly storagePlugins?: readonly (
-    | RuntimeStoragePlugin<TContext>
-    | StoragePluginFactory<TContext>
-  )[];
-  readonly basePath?: string;
-  readonly cwd?: string;
-  readonly routes?: HandlerRoutes;
+  readonly clientAccess: ClientAccessPolicy;
+  /** Storage implementations used to read provider-specific storage URIs. */
+  readonly storage?: readonly StoragePlugin[];
 }
 
-type PluginDatabaseCore<TContext> = {
-  readonly api: DatabaseAPI<TContext>;
+const normalizeClientAccess = (
+  value: unknown,
+):
+  | { readonly type: "public" }
+  | {
+      readonly type: "api-key";
+      readonly headerName: string;
+    } => {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError("clientAccess must be an object.");
+  }
+  const policy = value as {
+    readonly headerName?: unknown;
+    readonly type?: unknown;
+  };
+  if (policy.type === "public") return { type: "public" };
+  if (policy.type === "api-key") {
+    return {
+      headerName: normalizeApiKeyHeaderName(policy.headerName),
+      type: "api-key",
+    };
+  }
+  throw new TypeError(
+    'clientAccess.type must be either "public" or "api-key".',
+  );
+};
+
+type DatabasePluginCore = {
+  readonly api: DatabaseAPI;
   readonly adapterName: string;
   readonly createMigrator: () => never;
   readonly generateSchema: () => never;
@@ -59,110 +113,120 @@ export const hotUpdaterCoreMetadata = Symbol.for(
   "@hot-updater/server/core-metadata",
 );
 
-export type HotUpdaterCoreMetadata<TContext = unknown> = {
+export type HotUpdaterCoreMetadata = {
   readonly adapterCapabilities: DatabaseAdapterCapabilities;
-  readonly core: PluginDatabaseCore<TContext>;
+  readonly core: DatabasePluginCore;
 };
 
-export type HotUpdaterCore<TContext = unknown> = {
-  readonly api: RuntimeHotUpdaterAPI<TContext>;
+export type HotUpdaterCore = {
+  readonly api: RuntimeHotUpdaterAPI;
   readonly adapterCapabilities: DatabaseAdapterCapabilities;
-  readonly core: PluginDatabaseCore<TContext>;
+  readonly core: DatabasePluginCore;
 };
 
-export function getHotUpdaterCoreMetadata<TContext = unknown>(
-  hotUpdater: RuntimeHotUpdaterAPI<TContext>,
-): HotUpdaterCoreMetadata<TContext> | undefined {
+export function getHotUpdaterCoreMetadata(
+  hotUpdater: RuntimeHotUpdaterAPI,
+): HotUpdaterCoreMetadata | undefined {
   return (
-    hotUpdater as RuntimeHotUpdaterAPI<TContext> & {
-      readonly [hotUpdaterCoreMetadata]?: HotUpdaterCoreMetadata<TContext>;
+    hotUpdater as RuntimeHotUpdaterAPI & {
+      readonly [hotUpdaterCoreMetadata]?: HotUpdaterCoreMetadata;
     }
   )[hotUpdaterCoreMetadata];
 }
 
-export function createHotUpdaterCore<TContext = unknown>(
-  options: CreateHotUpdaterOptions<TContext>,
-): HotUpdaterCore<TContext> {
+export function createHotUpdaterCore(
+  options: CreateHotUpdaterOptions,
+): HotUpdaterCore {
+  for (const key of ["authorityId", "catalogId"]) {
+    if (Object.hasOwn(options, key)) {
+      throw new TypeError(
+        `Remove ${key} from createHotUpdater options. Catalog identity is managed internally.`,
+      );
+    }
+  }
   const database = options.database;
-  const basePath = normalizeBasePath(options.basePath ?? "/api");
-  const storagePlugins = (options.storages ?? options.storagePlugins ?? []).map(
-    (plugin) => {
-      const storagePlugin = typeof plugin === "function" ? plugin() : plugin;
-      assertRuntimeStoragePlugin(storagePlugin);
-      return storagePlugin;
-    },
-  );
-  const { readStorageText, resolveFileUrl } =
+  const storagePlugins = (options.storage ?? []).map((storage) => {
+    assertStorageOperations(storage, ["get", "getDownloadUrl"]);
+    return storage;
+  });
+  const { downloadStorageObject, readStorageText, resolveFileUrl } =
     createStorageAccess(storagePlugins);
+  const adapterCapabilities: DatabaseAdapterCapabilities = database;
 
-  if (!isDatabasePluginFactory(database) && !isDatabasePlugin(database)) {
+  if (!isDatabasePlugin(database)) {
     throw new Error("@hot-updater/server only supports database plugins.");
   }
 
-  const adapterCapabilities = database as DatabaseAdapterCapabilities;
-  const plugin: DatabasePlugin<TContext> = isDatabasePluginFactory(database)
-    ? database()
-    : database;
+  const plugin: DatabasePlugin = database;
   const adapterName = adapterCapabilities.adapterName ?? plugin.name;
   const assertSchemaReady = createSchemaReadinessChecker(
     adapterName,
     adapterCapabilities.createMigrator,
   );
-  const core = createPluginDatabaseCore<TContext>(
-    () => plugin,
-    resolveFileUrl,
-    isDatabasePluginFactory(database)
+  const core = createDatabasePluginCore(plugin, resolveFileUrl, {
+    beforeOperation: assertSchemaReady,
+    readStorageText,
+  });
+  const clientAccess = normalizeClientAccess(options.clientAccess);
+  const analytics = createAnalyticsProvider({
+    async append(row) {
+      await assertSchemaReady();
+      return plugin.models.analytics.append(row);
+    },
+    async scan(input) {
+      await assertSchemaReady();
+      return plugin.models.analytics.scan(input);
+    },
+  });
+  const apiKeys = createApiKeyManagement({
+    apiKeys: plugin.models.apiKeys,
+    beforeOperation: assertSchemaReady,
+  });
+
+  const handlers = createHotUpdaterHandlers(
+    core.api,
+    analytics,
+    clientAccess.type === "api-key"
       ? {
-          createMutationPlugin: () => database(),
-          beforeOperation: assertSchemaReady,
-          readStorageText,
+          authenticate: (request) =>
+            authenticateApiKey({
+              apiKeys: plugin.models.apiKeys,
+              beforeLookup: assertSchemaReady,
+              headerName: clientAccess.headerName,
+              request,
+            }),
+          headerName: clientAccess.headerName,
         }
-      : { beforeOperation: assertSchemaReady, readStorageText },
+      : undefined,
+    downloadStorageObject,
   );
 
-  const internalHandler = createHandler(core.api, {
-    basePath,
-    routes: options.routes,
-  });
-
-  // Some framework adapters strip the mounted base path or pass extra
-  // bindings/execution context arguments. Ignore those extras here so the
-  // handler can still be mounted directly as a plain Request handler.
-  const handler: RuntimeHotUpdaterAPI<TContext>["handler"] = (
-    request,
-    context,
-    ...extraArgs: unknown[]
-  ) => {
-    if (extraArgs.length > 0) {
-      return internalHandler(request);
-    }
-
-    return internalHandler(request, context);
-  };
-
-  const api = {
-    basePath,
-    adapterName: adapterCapabilities.adapterName ?? core.adapterName,
-    handler,
-  };
-  Object.defineProperties(api, Object.getOwnPropertyDescriptors(core.api));
+  const api: RuntimeHotUpdaterAPI = Object.assign(
+    {
+      adapterName: adapterCapabilities.adapterName ?? core.adapterName,
+      analytics,
+      apiKeys,
+      handlers,
+    },
+    core.api,
+  );
   Object.defineProperty(api, hotUpdaterCoreMetadata, {
     enumerable: false,
     value: {
       adapterCapabilities,
       core,
-    } satisfies HotUpdaterCoreMetadata<TContext>,
+    } satisfies HotUpdaterCoreMetadata,
   });
 
   return {
-    api: api as RuntimeHotUpdaterAPI<TContext>,
+    api,
     adapterCapabilities,
     core,
   };
 }
 
-export function createHotUpdater<TContext = unknown>(
-  options: CreateHotUpdaterOptions<TContext>,
-): RuntimeHotUpdaterAPI<TContext> {
+export function createHotUpdater(
+  options: CreateHotUpdaterOptions,
+): RuntimeHotUpdaterAPI {
   return createHotUpdaterCore(options).api;
 }

package/src/db/bundleRows.spec.ts

@@ -0,0 +1,164 @@
+import type { Bundle } from "@hot-updater/core";
+import { describe, expect, it } from "vitest";
+
+import {
+  BundleRowHydrationError,
+  bundleToPatchRows,
+  bundleToRow,
+  rowsToBundles,
+  type BundlePatchRow,
+  type BundleRow,
+} from "./bundleRows";
+
+const createBundle = (id: string): Bundle => ({
+  id,
+  platform: "ios",
+  fileHash: `hash-${id}`,
+  gitCommitHash: null,
+  storageUri: `s3://bucket/${id}.zip`,
+  archiveByteSize: 3_000_000_001,
+});
+
+const toRow = (bundle: Bundle): BundleRow => bundleToRow(bundle);
+
+const createPatchRow = (
+  id: string,
+  bundleId: string,
+  baseBundleId: string,
+  orderIndex: number,
+): BundlePatchRow => ({
+  id,
+  bundle_id: bundleId,
+  base_bundle_id: baseBundleId,
+  base_file_hash: `base-hash-${id}`,
+  patch_file_hash: `patch-hash-${id}`,
+  patch_storage_uri: `s3://bucket/${id}.patch`,
+  byte_size: 3_000_000_002,
+  order_index: orderIndex,
+});
+
+describe("bundle row conversion", () => {
+  it("round-trips bundle fields without embedding patch artifacts in the bundle row", () => {
+    const baseBundle = createBundle("base");
+    const bundle: Bundle = {
+      ...createBundle("target"),
+      metadata: { app_version: "1.0.0" },
+      manifestStorageUri: "s3://bucket/manifest.json",
+      manifestFileHash: "manifest-hash",
+      assetBaseStorageUri: "s3://bucket/assets",
+      patches: [
+        {
+          baseBundleId: baseBundle.id,
+          baseFileHash: "base-hash",
+          byteSize: 3_000_000_002,
+          patchFileHash: "patch-hash",
+          patchStorageUri: "s3://bucket/target.patch",
+        },
+      ],
+    };
+
+    const row = toRow(bundle);
+    const patchRows = bundleToPatchRows(bundle);
+    const hydratedBundles = rowsToBundles([row], patchRows, [
+      toRow(baseBundle),
+    ]);
+
+    expect(row).not.toHaveProperty("patches");
+    expect(row).not.toHaveProperty("patch_file_hash");
+    expect(row).not.toHaveProperty("channel");
+    expect(row).not.toHaveProperty("enabled");
+    expect(hydratedBundles).toHaveLength(1);
+    expect(hydratedBundles[0]).toEqual(bundle);
+  });
+
+  it("orders multiple patches deterministically", () => {
+    const oldest = createBundle("oldest");
+    const newest = createBundle("newest");
+    const target = createBundle("target");
+    const rows: readonly BundleRow[] = [toRow(target)];
+    const later = createPatchRow("later", target.id, newest.id, 1);
+    const firstById = createPatchRow("a-first", target.id, oldest.id, 0);
+    const secondById = createPatchRow("z-second", target.id, newest.id, 0);
+
+    const [hydrated] = rowsToBundles(
+      rows,
+      [later, secondById, firstById],
+      [toRow(oldest), toRow(newest)],
+    );
+
+    expect(hydrated?.patches?.map((patch) => patch.patchFileHash)).toEqual([
+      firstById.patch_file_hash,
+      secondById.patch_file_hash,
+      later.patch_file_hash,
+    ]);
+  });
+
+  it("hydrates an empty patch set", () => {
+    const bundle = createBundle("without-patches");
+
+    const [hydrated] = rowsToBundles([toRow(bundle)], [], []);
+
+    expect(hydrated).toMatchObject({ patches: [] });
+  });
+
+  it("preserves nested metadata at the row boundary", () => {
+    const row: BundleRow = {
+      ...toRow(createBundle("nested-metadata")),
+      metadata: { release: { flags: [true, null, 3] } },
+    };
+
+    const [hydrated] = rowsToBundles([row], [], []);
+
+    expect(hydrated).toMatchObject({
+      metadata: { release: { flags: [true, null, 3] } },
+    });
+  });
+
+  it("rejects duplicate patch ids during aggregate hydration", () => {
+    const base = createBundle("base");
+    const target = createBundle("target");
+    const patch = createPatchRow("duplicate", target.id, base.id, 0);
+    const duplicate = { ...patch, base_file_hash: "different-hash" };
+
+    const hydrate = () =>
+      rowsToBundles([toRow(target)], [patch, duplicate], [toRow(base)]);
+
+    expect(hydrate).toThrowError(BundleRowHydrationError);
+    expect(hydrate).toThrowError(
+      expect.objectContaining({
+        reason: "duplicate_patch_id",
+        patchId: patch.id,
+      }),
+    );
+  });
+
+  it("rejects a patch whose owner bundle row is absent", () => {
+    const base = createBundle("base");
+    const patch = createPatchRow("orphan-owner", "missing", base.id, 0);
+
+    const hydrate = () => rowsToBundles([], [patch], [toRow(base)]);
+
+    expect(hydrate).toThrowError(
+      expect.objectContaining({
+        reason: "orphan_patch_owner",
+        patchId: patch.id,
+        bundleId: patch.bundle_id,
+      }),
+    );
+  });
+
+  it("rejects a patch whose base bundle row is absent", () => {
+    const target = createBundle("target");
+    const patch = createPatchRow("orphan-base", target.id, "missing", 0);
+
+    const hydrate = () => rowsToBundles([toRow(target)], [patch], []);
+
+    expect(hydrate).toThrowError(
+      expect.objectContaining({
+        reason: "orphan_patch_base",
+        patchId: patch.id,
+        bundleId: patch.base_bundle_id,
+      }),
+    );
+  });
+});

package/src/db/bundleRows.ts

@@ -1,140 +1,10 @@
-import type { Bundle, BundlePatchArtifact, Platform } from "@hot-updater/core";
-import {
-  DEFAULT_ROLLOUT_COHORT_COUNT,
-  getAssetBaseStorageUri,
-  getBundlePatches,
-  getManifestFileHash,
-  getManifestStorageUri,
-  stripBundleArtifactMetadata,
-} from "@hot-updater/core";
-
-import { parseBundleMetadata } from "./updateArtifacts";
-
-export type BundleRow = {
-  readonly id: string;
-  readonly platform: string;
-  readonly should_force_update: unknown;
-  readonly enabled: unknown;
-  readonly file_hash: string;
-  readonly git_commit_hash: string | null;
-  readonly message: string | null;
-  readonly channel: string;
-  readonly storage_uri: string;
-  readonly target_app_version: string | null;
-  readonly fingerprint_hash: string | null;
-  readonly metadata?: unknown;
-  readonly manifest_storage_uri?: string | null;
-  readonly manifest_file_hash?: string | null;
-  readonly asset_base_storage_uri?: string | null;
-  readonly rollout_cohort_count?: number | null;
-  readonly target_cohorts?: unknown;
-};
-
-export type BundlePatchRow = {
-  readonly id: string;
-  readonly bundle_id: string;
-  readonly base_bundle_id: string;
-  readonly base_file_hash: string;
-  readonly patch_file_hash: string;
-  readonly patch_storage_uri: string;
-  readonly order_index?: number | null;
-};
-
-const parseTargetCohorts = (value: unknown): string[] | null => {
-  if (!value) return null;
-  if (Array.isArray(value)) {
-    return value.filter((item): item is string => typeof item === "string");
-  }
-  if (typeof value !== "string") return null;
-  try {
-    const parsed = JSON.parse(value) as unknown;
-    return Array.isArray(parsed)
-      ? parsed.filter((item): item is string => typeof item === "string")
-      : null;
-  } catch {
-    return null;
-  }
-};
-
-const buildBundlePatchId = (bundleId: string, baseBundleId: string) =>
-  `${bundleId}:${baseBundleId}`;
-
-export const bundleToRow = (bundle: Bundle): BundleRow => ({
-  id: bundle.id,
-  platform: bundle.platform,
-  should_force_update: bundle.shouldForceUpdate,
-  enabled: bundle.enabled,
-  file_hash: bundle.fileHash,
-  git_commit_hash: bundle.gitCommitHash,
-  message: bundle.message,
-  channel: bundle.channel,
-  storage_uri: bundle.storageUri,
-  target_app_version: bundle.targetAppVersion,
-  fingerprint_hash: bundle.fingerprintHash,
-  metadata: stripBundleArtifactMetadata(bundle.metadata) ?? {},
-  manifest_storage_uri: getManifestStorageUri(bundle),
-  manifest_file_hash: getManifestFileHash(bundle),
-  asset_base_storage_uri: getAssetBaseStorageUri(bundle),
-  rollout_cohort_count:
-    bundle.rolloutCohortCount ?? DEFAULT_ROLLOUT_COHORT_COUNT,
-  target_cohorts: bundle.targetCohorts ?? null,
-});
-
-export const bundleToPatchRows = (bundle: Bundle): BundlePatchRow[] =>
-  getBundlePatches(bundle).map((patch, index) => ({
-    id: buildBundlePatchId(bundle.id, patch.baseBundleId),
-    bundle_id: bundle.id,
-    base_bundle_id: patch.baseBundleId,
-    base_file_hash: patch.baseFileHash,
-    patch_file_hash: patch.patchFileHash,
-    patch_storage_uri: patch.patchStorageUri,
-    order_index: index,
-  }));
-
-const mapPatchRowToPatch = (record: BundlePatchRow): BundlePatchArtifact => ({
-  baseBundleId: record.base_bundle_id,
-  baseFileHash: record.base_file_hash,
-  patchFileHash: record.patch_file_hash,
-  patchStorageUri: record.patch_storage_uri,
-});
-
-export const rowToBundle = (
-  record: BundleRow,
-  patchRecords: readonly BundlePatchRow[] = [],
-): Bundle => {
-  const patches = patchRecords
-    .slice()
-    .sort(
-      (left, right) =>
-        (left.order_index ?? 0) - (right.order_index ?? 0) ||
-        left.base_bundle_id.localeCompare(right.base_bundle_id),
-    )
-    .map(mapPatchRowToPatch);
-  const primaryPatch = patches[0] ?? null;
-
-  return {
-    id: record.id,
-    platform: record.platform as Platform,
-    shouldForceUpdate: Boolean(record.should_force_update),
-    enabled: Boolean(record.enabled),
-    fileHash: record.file_hash,
-    gitCommitHash: record.git_commit_hash ?? null,
-    message: record.message ?? null,
-    channel: record.channel,
-    storageUri: record.storage_uri,
-    targetAppVersion: record.target_app_version ?? null,
-    fingerprintHash: record.fingerprint_hash ?? null,
-    metadata: parseBundleMetadata(record.metadata),
-    manifestStorageUri: record.manifest_storage_uri ?? null,
-    manifestFileHash: record.manifest_file_hash ?? null,
-    assetBaseStorageUri: record.asset_base_storage_uri ?? null,
-    patches,
-    patchBaseBundleId: primaryPatch?.baseBundleId ?? null,
-    patchBaseFileHash: primaryPatch?.baseFileHash ?? null,
-    patchFileHash: primaryPatch?.patchFileHash ?? null,
-    patchStorageUri: primaryPatch?.patchStorageUri ?? null,
-    rolloutCohortCount:
-      record.rollout_cohort_count ?? DEFAULT_ROLLOUT_COHORT_COUNT,
-    targetCohorts: parseTargetCohorts(record.target_cohorts),
-  };
-};
+export {
+  BundleRowHydrationError,
+  BundleRowHydrationErrorReason,
+  bundleToPatchRows,
+  bundleToRow,
+  rowToBundle,
+  rowsToBundles,
+} from "@hot-updater/plugin-core";
+
+export type { BundlePatchRow, BundleRow } from "@hot-updater/plugin-core";