@hot-updater/server 1.0.0-rc.1 → 1.0.0-rc.16

package/src/core/releases.spec.ts

@@ -0,0 +1,308 @@
+import {
+  createReleaseCatalogScopeKey,
+  encodeChannelKey,
+} from "@hot-updater/core";
+import {
+  compileReleaseCatalog,
+  releaseRowToRelease,
+  type BundleRow,
+  type ReleaseCatalogScope,
+  type ReleaseRow,
+} from "@hot-updater/plugin-core";
+import { createMemoryAdapter } from "@hot-updater/plugin-core/internal";
+import { describe, expect, it } from "vitest";
+
+import {
+  createBundlePatchRowFixture,
+  createBundleRowFixture,
+} from "../../../test-utils/src/databaseTestFixtures";
+import { createDatabaseEngine } from "../database/database";
+import { resolveSchema } from "../database/resolveSchema";
+import {
+  changeReleases,
+  coreModule,
+  createCoreReads,
+  insertBundle,
+  insertChannel,
+  rebuildCatalog,
+  targetBaseCandidateKey,
+  type ReleaseChangeInput,
+} from "./index";
+
+const channel = { id: "channel-production", name: "production" };
+const channelKey = encodeChannelKey(channel.name);
+const scope: ReleaseCatalogScope = {
+  channelId: channel.id,
+  channelName: channel.name,
+  platform: "ios",
+  scopeKey: createReleaseCatalogScopeKey({
+    channelKey,
+    platform: "ios",
+    strategy: "APP_VERSION",
+  }),
+  strategy: "APP_VERSION",
+  fingerprintHash: null,
+};
+
+const releaseOf = (bundle: BundleRow): Omit<ReleaseRow, "id"> => ({
+  revision: 1,
+  scope_key: scope.scopeKey,
+  channel_id: channel.id,
+  platform: "ios",
+  kind: "BUNDLE",
+  bundle_id: bundle.id,
+  strategy: "APP_VERSION",
+  target_app_version: "1.0.0",
+  fingerprint_hash: null,
+  enabled: true,
+  should_force_update: false,
+  message: null,
+  rollout_cohort_count: 1000,
+  target_cohorts: [],
+  operation: "DEPLOY",
+  source_release_id: null,
+  created_at_ms: 1,
+  updated_at_ms: 1,
+});
+
+const deploy = (bundle: BundleRow): ReleaseChangeInput => ({
+  scope,
+  bundle: { row: bundle, patches: [] },
+  change: { operation: "insert", row: releaseOf(bundle) },
+  updatedAtMs: 10,
+});
+
+const setup = async () => {
+  const adapter = createMemoryAdapter();
+  const schema = resolveSchema([coreModule]);
+  const engine = createDatabaseEngine({ adapter, schema, verify: true });
+  const db = engine.database(coreModule);
+  await insertChannel(db, channel);
+  return {
+    adapter,
+    schema,
+    engine,
+    db,
+    reads: createCoreReads(db, { resolveFileUrl: async () => null }),
+  };
+};
+
+const baseKey = targetBaseCandidateKey({
+  channel: channel.name,
+  platform: "ios",
+  fingerprintHash: null,
+  appVersion: "1.0.0",
+})!;
+const NEWEST = "ffffffff-ffff-7fff-bfff-ffffffffffff";
+
+describe("release changes rooted at the catalog", () => {
+  it("deploys a bundle with its release and compiles the scope's catalog in one transaction", async () => {
+    const { db, reads } = await setup();
+    const bundle = createBundleRowFixture("501");
+    const patchBase = createBundleRowFixture("500");
+    await db.transaction(async (tx) => insertBundle(tx, patchBase));
+    const patch = createBundlePatchRowFixture("1", bundle.id, patchBase.id);
+    const [result] = await changeReleases(db, [
+      { ...deploy(bundle), bundle: { row: bundle, patches: [patch] } },
+    ]);
+    const release = result!.release!;
+    expect(release.id > bundle.id).toBe(true);
+    const compiled = await compileReleaseCatalog({
+      strategy: "APP_VERSION",
+      releases: [releaseRowToRelease(release)],
+    });
+    expect(result!.catalog).toMatchObject({
+      scope_key: scope.scopeKey,
+      channel_key: channelKey,
+      generation: 1,
+      payload: compiled.canonicalPayload,
+      catalog_hash: compiled.catalogHash,
+      is_tombstone: false,
+      updated_at_ms: 10,
+    });
+    await expect(
+      reads.getReleaseCatalog({
+        strategy: "APP_VERSION",
+        platform: "ios",
+        channelKey,
+        appVersion: "1.0.0",
+      }),
+    ).resolves.toMatchObject({
+      generation: 1,
+      releases: [{ releaseId: release.id, bundleId: bundle.id }],
+    });
+    await expect(reads.getBundle(bundle.id)).resolves.toMatchObject({
+      patches: [patch],
+    });
+    await expect(reads.countBundles("ios")).resolves.toBe(2);
+    await expect(reads.findBaseBundleIds(baseKey, NEWEST, 3)).resolves.toEqual([
+      bundle.id,
+    ]);
+  });
+
+  it("updates and deletes a release with the next catalog generation each", async () => {
+    const { db, reads } = await setup();
+    const bundle = createBundleRowFixture("511");
+    const [deployed] = await changeReleases(db, [deploy(bundle)]);
+    const id = deployed!.release!.id;
+
+    const [disabled] = await changeReleases(db, [
+      {
+        scope,
+        change: { operation: "update", id, update: { enabled: false } },
+        updatedAtMs: 20,
+      },
+    ]);
+    expect(disabled!.release).toMatchObject({ revision: 2, enabled: false });
+    expect(disabled!.catalog).toMatchObject({
+      generation: 2,
+      is_tombstone: true,
+      catalog_id: deployed!.catalog.catalog_id,
+    });
+    await expect(reads.findBaseBundleIds(baseKey, NEWEST, 3)).resolves.toEqual(
+      [],
+    );
+
+    const [deleted] = await changeReleases(db, [
+      { scope, change: { operation: "delete", id }, updatedAtMs: 30 },
+    ]);
+    expect(deleted).toMatchObject({
+      release: null,
+      catalog: { generation: 3 },
+    });
+    await expect(reads.getRelease(id)).resolves.toBeNull();
+  });
+
+  it("orders ids after the scope's latest release and refuses one that does not sort after it", async () => {
+    const { db } = await setup();
+    const first = createBundleRowFixture("521");
+    const second = createBundleRowFixture("522");
+    const [one] = await changeReleases(db, [deploy(first)]);
+    const [two] = await changeReleases(db, [deploy(second)]);
+    expect(two!.release!.id > one!.release!.id).toBe(true);
+
+    await expect(
+      changeReleases(db, [
+        {
+          scope,
+          change: {
+            operation: "insert",
+            row: { ...releaseOf(first), id: one!.release!.id },
+          },
+          updatedAtMs: 40,
+        },
+      ]),
+    ).rejects.toMatchObject({ code: "NON_MONOTONIC_RELEASE_ID" });
+  });
+
+  it("refuses a release outside its scope and a scope whose catalog history is missing", async () => {
+    const { adapter, schema, db } = await setup();
+    await expect(
+      changeReleases(db, [
+        {
+          scope,
+          change: { operation: "delete", id: NEWEST },
+          updatedAtMs: 50,
+        },
+      ]),
+    ).rejects.toMatchObject({ code: "RELEASE_NOT_FOUND" });
+
+    await changeReleases(db, [deploy(createBundleRowFixture("531"))]);
+    // A restore that lost the catalog row: a write under the engine, which
+    // keeps a catalog while its scope has releases.
+    const table = schema.models.get("release_catalogs")!.table;
+    const [row] = await adapter.get(table, [[scope.scopeKey]]);
+    await adapter.write([
+      {
+        type: "delete",
+        table,
+        key: [scope.scopeKey],
+        guard: { v: Number(row!._v) },
+        previous: row!,
+      },
+    ]);
+    await expect(
+      changeReleases(db, [deploy(createBundleRowFixture("532"))]),
+    ).rejects.toMatchObject({ code: "CATALOG_IDENTITY_MISSING" });
+    await expect(rebuildCatalog(db, scope, 60)).rejects.toMatchObject({
+      code: "CATALOG_IDENTITY_MISSING",
+    });
+  });
+
+  it("serializes concurrent deploys in one scope through its catalog row", async () => {
+    const { db, reads } = await setup();
+    const bundles = Array.from({ length: 8 }, (_, n) =>
+      createBundleRowFixture(String(541 + n)),
+    );
+    const results = await Promise.all(
+      bundles.map((bundle) => changeReleases(db, [deploy(bundle)])),
+    );
+    const generations = results.map(([result]) => result!.catalog.generation);
+    expect(generations.toSorted((a, b) => a - b)).toEqual([
+      1, 2, 3, 4, 5, 6, 7, 8,
+    ]);
+    const byGeneration = results
+      .map(([result]) => result!)
+      .sort((a, b) => a.catalog.generation - b.catalog.generation);
+    const ids = byGeneration.map(({ release }) => release!.id);
+    expect(ids).toEqual(ids.toSorted());
+    await expect(
+      reads.getReleaseCatalogRow(scope.scopeKey),
+    ).resolves.toMatchObject({ generation: 8 });
+    await expect(
+      reads.listReleases({
+        filter: { kind: "scope", scopeKey: scope.scopeKey },
+        limit: 10,
+      }),
+    ).resolves.toHaveLength(8);
+  });
+
+  it("reads only the scope's enabled releases and its latest id, all of them used", async () => {
+    const { engine, db } = await setup();
+    const bundles = Array.from({ length: 5 }, (_, n) =>
+      createBundleRowFixture(String(551 + n)),
+    );
+    const deployed: string[] = [];
+    for (const bundle of bundles) {
+      const [result] = await changeReleases(db, [deploy(bundle)]);
+      deployed.push(result!.release!.id);
+    }
+    for (const id of deployed.slice(0, 2)) {
+      await changeReleases(db, [
+        {
+          scope,
+          change: { operation: "update", id, update: { enabled: false } },
+          updatedAtMs: 70,
+        },
+      ]);
+    }
+    const measured = await engine.measureReads(() =>
+      changeReleases(db, [deploy(createBundleRowFixture("556"))]),
+    );
+    // three enabled releases for the compile, one row for the latest id
+    expect(measured.adapter.rows).toBe(4);
+    expect(measured.adapter.queries).toBe(2);
+  });
+
+  it("rebuilds a catalog only when its releases changed underneath it", async () => {
+    const { db } = await setup();
+    const [deployed] = await changeReleases(db, [
+      deploy(createBundleRowFixture("561")),
+    ]);
+    await expect(rebuildCatalog(db, scope, 80)).resolves.toMatchObject({
+      changed: false,
+      catalog: { generation: 1 },
+    });
+    // The release changes underneath the catalog, as only a raw write does.
+    await db.transaction(async (tx) => {
+      const stored = await tx.findOne("releases", {
+        id: deployed!.release!.id,
+      });
+      tx.update("releases", stored!, { message: "hotfix", revision: 2 });
+    });
+    await expect(rebuildCatalog(db, scope, 90)).resolves.toMatchObject({
+      changed: true,
+      catalog: { generation: 2, updated_at_ms: 90 },
+    });
+  });
+});

package/src/core/releases.ts

@@ -0,0 +1,345 @@
+import {
+  createReleaseCatalogScopeKey,
+  encodeChannelKey,
+} from "@hot-updater/core";
+import {
+  compileReleaseCatalog,
+  createUUIDv7,
+  createUUIDv7After,
+  isUUIDv7,
+  releaseRowToRelease,
+  ReleaseCatalogMutationError,
+  type BundlePatchRow,
+  type BundleRow,
+  type ReleaseCatalogCompilation,
+  type ReleaseCatalogRow,
+  type ReleaseCatalogScope,
+  type ReleaseRow,
+  type ReleaseRowUpdate,
+} from "@hot-updater/plugin-core";
+
+import { toCatalogRow, toReleaseRow, type CoreDatabase } from "./reads";
+import { insertBundle, type CoreTransaction } from "./writes";
+
+const PAGE = 500;
+
+/** One change to one release, applied with its scope's catalog. */
+export type ReleaseChange =
+  /** `id` is assigned after the scope's latest release unless given. */
+  | {
+      readonly operation: "insert";
+      readonly row: Omit<ReleaseRow, "id"> & { readonly id?: string };
+    }
+  | {
+      readonly operation: "update";
+      readonly id: string;
+      readonly update: Omit<ReleaseRowUpdate, "revision" | "scope_key">;
+    }
+  | { readonly operation: "delete"; readonly id: string };
+
+export interface ReleaseChangeInput {
+  readonly scope: ReleaseCatalogScope;
+  readonly change: ReleaseChange;
+  /** A deploy's new bundle and its patches, written first. */
+  readonly bundle?: {
+    readonly row: BundleRow;
+    readonly patches: readonly BundlePatchRow[];
+  };
+  readonly updatedAtMs: number;
+}
+
+export interface ReleaseChangeResult {
+  readonly catalog: ReleaseCatalogRow;
+  readonly release: ReleaseRow | null;
+  readonly diagnostics: ReleaseCatalogCompilation["diagnostics"];
+}
+
+const fail = (
+  code: ConstructorParameters<typeof ReleaseCatalogMutationError>[0],
+  message: string,
+): never => {
+  throw new ReleaseCatalogMutationError(code, message);
+};
+
+const checkScope = (scope: ReleaseCatalogScope): void => {
+  const channelKey = encodeChannelKey(scope.channelName);
+  const expected =
+    scope.strategy === "APP_VERSION"
+      ? createReleaseCatalogScopeKey({
+          channelKey,
+          platform: scope.platform,
+          strategy: "APP_VERSION",
+        })
+      : createReleaseCatalogScopeKey({
+          channelKey,
+          fingerprintHash: scope.fingerprintHash ?? "",
+          platform: scope.platform,
+          strategy: "FINGERPRINT",
+        });
+  if (
+    (scope.strategy === "FINGERPRINT") !== (scope.fingerprintHash !== null) ||
+    scope.scopeKey !== expected
+  ) {
+    fail("INVALID_SCOPE", "Release catalog scope metadata is inconsistent");
+  }
+};
+
+/** A scope's enabled releases, all of them, under the catalog's guard. */
+const enabledReleases = async (
+  tx: CoreTransaction,
+  scopeKey: string,
+): Promise<ReleaseRow[]> => {
+  const rows: ReleaseRow[] = [];
+  let cursor: string | undefined;
+  do {
+    const page = await tx.findMany("releases", {
+      index: "byScopeEnabled",
+      where: { scope_key: scopeKey, enabled: true },
+      limit: PAGE,
+      ...(cursor === undefined ? {} : { cursor }),
+    });
+    rows.push(...page.rows.map(toReleaseRow));
+    cursor = page.next;
+  } while (cursor !== undefined);
+  return rows;
+};
+
+/** The scope's newest release id: `byScope` descending, limit 1. */
+const latestReleaseId = async (tx: CoreTransaction, scopeKey: string) => {
+  const { rows } = await tx.findMany("releases", {
+    index: "byScope",
+    where: { scope_key: scopeKey },
+    order: "desc",
+    limit: 1,
+  });
+  return rows[0]?.id ?? null;
+};
+
+/** Compiles `enabled` and writes it as the scope's next catalog generation. */
+const writeCatalog = async (
+  tx: CoreTransaction,
+  scope: ReleaseCatalogScope,
+  stored: Awaited<ReturnType<typeof readCatalog>>,
+  enabled: readonly ReleaseRow[],
+  updatedAtMs: number,
+) => {
+  const compilation = await compileReleaseCatalog({
+    strategy: scope.strategy,
+    releases: enabled.map(releaseRowToRelease),
+  });
+  const generation = (stored.generation ?? 0) + 1;
+  if (!Number.isSafeInteger(generation)) {
+    fail(
+      "CATALOG_GENERATION_EXHAUSTED",
+      `Catalog "${scope.scopeKey}" exhausted its generation counter`,
+    );
+  }
+  const catalog: ReleaseCatalogRow = {
+    scope_key: scope.scopeKey,
+    catalog_id: stored.catalog?.catalog_id ?? createUUIDv7(),
+    strategy: scope.strategy,
+    channel_id: scope.channelId,
+    channel_key: encodeChannelKey(scope.channelName),
+    platform: scope.platform,
+    fingerprint_hash: scope.fingerprintHash,
+    generation,
+    payload: compilation.canonicalPayload,
+    catalog_hash: compilation.catalogHash,
+    byte_size: compilation.byteSize,
+    is_tombstone: compilation.payload.releaseDescriptors.length === 0,
+    updated_at_ms: updatedAtMs,
+  };
+  const { scope_key: _scopeKey, ...set } = catalog;
+  if (stored.row === null) tx.create("release_catalogs", catalog);
+  else tx.update("release_catalogs", stored.row, set);
+  return { catalog, compilation };
+};
+
+/** The scope's catalog row, and its compiled catalog and generation if it has one. */
+export const readCatalog = async (tx: CoreTransaction, scopeKey: string) => {
+  const row = await tx.findOne("release_catalogs", { scope_key: scopeKey });
+  return {
+    row,
+    generation: row?.generation ?? null,
+    catalog: row === null ? null : toCatalogRow(row),
+  };
+};
+
+/** A scope with releases and no compiled catalog lost its history. */
+const assertHistory = (
+  stored: Awaited<ReturnType<typeof readCatalog>>,
+  hasReleases: boolean,
+) => {
+  if (stored.catalog === null && hasReleases) {
+    fail(
+      "CATALOG_IDENTITY_MISSING",
+      "Catalog history is missing. Restore its catalog row from backup before rebuilding or deploying.",
+    );
+  }
+};
+
+/** One release change and its scope's next catalog, inside `tx`. */
+export const changeRelease = async (
+  tx: CoreTransaction,
+  { scope, change, bundle, updatedAtMs }: ReleaseChangeInput,
+): Promise<ReleaseChangeResult> => {
+  checkScope(scope);
+  const stored = await readCatalog(tx, scope.scopeKey);
+  const enabled = await enabledReleases(tx, scope.scopeKey);
+  if (bundle !== undefined) {
+    insertBundle(tx, bundle.row);
+    for (const patch of bundle.patches) tx.create("bundle_patches", patch);
+  }
+  let before: ReleaseRow | null = null;
+  let release: ReleaseRow | null;
+  if (change.operation === "insert") {
+    const latest = await latestReleaseId(tx, scope.scopeKey);
+    assertHistory(stored, latest !== null);
+    const floor = [
+      latest,
+      bundle && isUUIDv7(bundle.row.id) ? bundle.row.id : null,
+    ]
+      .filter((id): id is string => id !== null)
+      .sort()
+      .at(-1);
+    const id = change.row.id ?? createUUIDv7After(floor ?? null);
+    if (latest !== null && id <= latest) {
+      fail(
+        "NON_MONOTONIC_RELEASE_ID",
+        `Release "${id}" must sort after "${latest}"`,
+      );
+    }
+    release = { ...change.row, id };
+    if (
+      release.scope_key !== scope.scopeKey ||
+      release.channel_id !== scope.channelId ||
+      release.platform !== scope.platform ||
+      release.strategy !== scope.strategy ||
+      release.fingerprint_hash !== scope.fingerprintHash ||
+      release.revision !== 1
+    ) {
+      fail(
+        "INVALID_SCOPE",
+        "Inserted Release does not match its catalog scope",
+      );
+    }
+    tx.create("releases", release);
+  } else {
+    const row = await tx.findOne("releases", { id: change.id });
+    if (row === null || row.scope_key !== scope.scopeKey) {
+      return fail(
+        "RELEASE_NOT_FOUND",
+        `Release "${change.id}" was not found in scope "${scope.scopeKey}"`,
+      );
+    }
+    assertHistory(stored, true);
+    before = toReleaseRow(row);
+    if (change.operation === "delete") {
+      await tx.delete("releases", row);
+      release = null;
+    } else {
+      const set = { ...change.update, revision: before.revision + 1 };
+      tx.update("releases", row, set);
+      release = { ...before, ...set };
+    }
+  }
+  const changedId = before?.id ?? release?.id;
+  const next = [
+    ...enabled.filter(({ id }) => id !== changedId),
+    ...(release?.enabled ? [release] : []),
+  ].sort((left, right) => (left.id < right.id ? -1 : 1));
+  const { catalog, compilation } = await writeCatalog(
+    tx,
+    scope,
+    stored,
+    next,
+    updatedAtMs,
+  );
+  return { catalog, release, diagnostics: compilation.diagnostics };
+};
+
+/**
+ * Release changes rooted at their catalogs: each reads its scope's catalog
+ * and enabled releases, applies the change, and writes the next catalog
+ * generation, all in one transaction. A concurrent change in a scope bumps
+ * its catalog row, so this transaction reruns instead of publishing a stale
+ * catalog.
+ */
+export const changeReleases = (
+  db: CoreDatabase,
+  inputs: readonly ReleaseChangeInput[],
+): Promise<ReleaseChangeResult[]> => {
+  const scopes = new Set(inputs.map(({ scope }) => scope.scopeKey));
+  if (scopes.size !== inputs.length) {
+    fail("INVALID_SCOPE", "A batch cannot change one catalog scope twice");
+  }
+  return db.transaction(async (tx) => {
+    const results: ReleaseChangeResult[] = [];
+    for (const input of inputs) results.push(await changeRelease(tx, input));
+    return results;
+  });
+};
+
+/** Recompiles a scope's catalog from its enabled releases inside `tx`; an unchanged catalog is not rewritten. */
+export const rebuildScope = async (
+  tx: CoreTransaction,
+  scope: ReleaseCatalogScope,
+  updatedAtMs: number,
+): Promise<{
+  readonly catalog: ReleaseCatalogRow;
+  readonly current: ReleaseCatalogRow | null;
+  readonly changed: boolean;
+  readonly diagnostics: ReleaseCatalogCompilation["diagnostics"];
+}> => {
+  checkScope(scope);
+  const stored = await readCatalog(tx, scope.scopeKey);
+  assertHistory(stored, (await latestReleaseId(tx, scope.scopeKey)) !== null);
+  const enabled = await enabledReleases(tx, scope.scopeKey);
+  const compilation = await compileReleaseCatalog({
+    strategy: scope.strategy,
+    releases: enabled.map(releaseRowToRelease),
+  });
+  const current = stored.catalog;
+  if (
+    current !== null &&
+    current.strategy === scope.strategy &&
+    current.channel_id === scope.channelId &&
+    current.channel_key === encodeChannelKey(scope.channelName) &&
+    current.platform === scope.platform &&
+    current.fingerprint_hash === scope.fingerprintHash &&
+    current.catalog_hash === compilation.catalogHash
+  ) {
+    return {
+      catalog: current,
+      current,
+      changed: false,
+      diagnostics: compilation.diagnostics,
+    };
+  }
+  const written = await writeCatalog(tx, scope, stored, enabled, updatedAtMs);
+  return {
+    catalog: written.catalog,
+    current,
+    changed: true,
+    diagnostics: written.compilation.diagnostics,
+  };
+};
+
+/** Recompiles a scope's catalog from its enabled releases; an unchanged catalog is not rewritten. */
+export const rebuildCatalog = (
+  db: CoreDatabase,
+  scope: ReleaseCatalogScope,
+  updatedAtMs: number,
+): Promise<{
+  readonly catalog: ReleaseCatalogRow;
+  readonly changed: boolean;
+  readonly diagnostics: ReleaseCatalogCompilation["diagnostics"];
+}> =>
+  db.transaction(async (tx) => {
+    const { current: _current, ...rebuilt } = await rebuildScope(
+      tx,
+      scope,
+      updatedAtMs,
+    );
+    return rebuilt;
+  });