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

package/src/db/index.ts

@@ -2,12 +2,30 @@ import {
   getHotUpdaterCoreMetadata,
   type RuntimeHotUpdaterAPI,
 } from "../createHotUpdaterCore";
-import { generateSchemaFromHotUpdaterSchema } from "./schemaGenerators";
 import { type Migrator, type SchemaGenerator } from "./types";
 
+export { createDatabaseCoreApi, type CoreApi } from "../core/api";
+export {
+  createDatabasePluginApis,
+  createMeasuredDatabase,
+  type MeasuredDatabase,
+  type MeasuredDatabaseOptions,
+} from "../assembly/databasePlugins";
+export { targetBaseCandidateKey } from "../core/baseCandidates";
 export * from "./createBundleDiff";
-export type { Migrator, SchemaGenerator } from "./types";
-export { HotUpdaterSchemaMigrationRequiredError } from "./schemaReadiness";
+export {
+  generateEngineSql,
+  settingsStatements,
+  type EngineSqlOptions,
+} from "./engineSql";
+export type {
+  DatabaseTooling,
+  Migrator,
+  SchemaGenerator,
+  ToolingDatabase,
+  ToolingTarget,
+} from "./types";
+export { HotUpdaterSchemaMigrationRequiredError } from "../database/fence";
 export { HOT_UPDATER_SERVER_VERSION } from "../version";
 
 export type HotUpdaterDBTarget = {
@@ -26,22 +44,33 @@ const getDBMetadata = (hotUpdater: HotUpdaterDBTarget) => {
   return metadata;
 };
 
+/** Whether `hot-updater db generate` writes schema files for a server's database. */
+export const generatesSchema = (hotUpdater: HotUpdaterDBTarget): boolean =>
+  getDBMetadata(hotUpdater).database.generateSchema !== undefined;
+
+/** The migrator for a server's database: its built-in tables and its plugins' tables. */
 export function createMigrator(hotUpdater: HotUpdaterDBTarget): Migrator {
-  const { adapterCapabilities, core } = getDBMetadata(hotUpdater);
-  return (adapterCapabilities.createMigrator ?? core.createMigrator)();
+  const { database, target } = getDBMetadata(hotUpdater);
+  if (database.createMigrator === undefined) {
+    throw new Error(
+      database.generateSchema === undefined
+        ? `The ${database.name} database has no migrator; its provider applies the schema.`
+        : `The ${database.name} database applies its schema from migration files: run \`hot-updater db generate\`, then apply the file with the provider's tooling.`,
+    );
+  }
+  return database.createMigrator(target);
 }
 
 export function generateSchema(
   hotUpdater: HotUpdaterDBTarget,
   ...args: Parameters<SchemaGenerator>
 ): ReturnType<SchemaGenerator> {
-  const { adapterCapabilities, core } = getDBMetadata(hotUpdater);
-  const schemaGenerator =
-    adapterCapabilities.generateSchema ?? core.generateSchema;
-  return generateSchemaFromHotUpdaterSchema(
-    hotUpdater.adapterName,
-    adapterCapabilities.provider,
-    args[0],
-    schemaGenerator(...args),
-  );
+  const { database, target } = getDBMetadata(hotUpdater);
+  if (database.generateSchema === undefined) {
+    throw new Error(
+      `The ${database.name} database has no schema generator; run \`hot-updater db migrate\` instead.`,
+    );
+  }
+  const [version, name] = args;
+  return database.generateSchema(version, name, target);
 }

package/src/db/pluginTables.spec.ts

@@ -0,0 +1,218 @@
+import { PGlite } from "@electric-sql/pglite";
+import { createMemoryAdapter } from "@hot-updater/plugin-core/internal";
+import { Kysely } from "kysely";
+import { PGliteDialect } from "kysely-pglite-dialect";
+import { describe, expect, it, vi } from "vitest";
+
+import { drizzleAdapter } from "../adapters/drizzle";
+import { kyselyAdapter } from "../adapters/kysely";
+import { prismaAdapter } from "../adapters/prisma";
+import { createHotUpdater } from "../createHotUpdaterCore";
+import { HotUpdaterSchemaMigrationRequiredError } from "../database/fence";
+import { defineTable } from "../database/schema";
+import { definePlugin } from "../plugins/definePlugin";
+import { insights } from "../plugins/insights";
+import {
+  builtInTarget,
+  createEngineDatabase,
+  toolingTargetOf,
+} from "./builtInDatabase";
+import { createMigrator, generateSchema } from "./index";
+
+const notes = definePlugin({
+  id: "notes",
+  schemaVersion: "2",
+  schema: {
+    notes: defineTable(
+      {
+        id: { type: "string" },
+        author: { type: "string" },
+        text: { type: "string" },
+      },
+      { key: ["id"], indexes: { byAuthor: { eq: ["author"], sort: ["id"] } } },
+    ),
+  },
+  init: ({ db }) => ({
+    api: {
+      add: (id: string, author: string, text: string) =>
+        db.transaction(async (tx) => {
+          tx.create("notes", { id, author, text });
+        }),
+      read: (id: string) => db.findOne("notes", { id }),
+    },
+  }),
+});
+
+/** `hot-updater db migrate`: the migrator for the server's tables, run. */
+const migrate = async (hotUpdater: { readonly adapterName: string }) => {
+  const result = await createMigrator(hotUpdater).migrateToLatest({
+    mode: "from-schema",
+    updateSettings: true,
+  });
+  await result.execute();
+  return result;
+};
+
+const memoryDatabase = () =>
+  createEngineDatabase({ name: "memory", adapter: createMemoryAdapter() });
+
+describe("third-party plugin tables in db tooling", () => {
+  it("adds each third-party plugin's namespaced tables and settings row to the built-in ones", () => {
+    expect(toolingTargetOf([insights()])).toBe(builtInTarget);
+    const target = toolingTargetOf([insights(), notes]);
+    expect(target.schema.tables.map(({ name }) => name)).toEqual([
+      ...builtInTarget.schema.tables.map(({ name }) => name),
+      "notes_notes",
+    ]);
+    expect(target.settings).toEqual({
+      ...builtInTarget.settings,
+      "schema.notes": "2",
+    });
+  });
+
+  it("migrates an engine database's built-in and plugin tables with its adapter", async () => {
+    const hotUpdater = createHotUpdater({
+      database: memoryDatabase(),
+      plugins: [notes],
+      clientAccess: "public",
+    });
+    await expect(hotUpdater.api.notes.read("n1")).rejects.toBeInstanceOf(
+      HotUpdaterSchemaMigrationRequiredError,
+    );
+
+    const result = await migrate(hotUpdater);
+    expect(result.operations).toContainEqual(
+      expect.objectContaining({
+        type: "create-table",
+        value: expect.objectContaining({ ormName: "notes_notes" }),
+      }),
+    );
+    await hotUpdater.api.notes.add("n1", "ada", "hello");
+    await expect(hotUpdater.api.notes.read("n1")).resolves.toEqual({
+      id: "n1",
+      author: "ada",
+      text: "hello",
+    });
+    await expect(hotUpdater.core.listChannels()).resolves.toEqual([]);
+  });
+
+  it("answers 503 until the plugin's settings row exists, then serves it", async () => {
+    const database = memoryDatabase();
+    await migrate(createHotUpdater({ database, clientAccess: "public" }));
+    const hotUpdater = createHotUpdater({
+      database,
+      plugins: [notes],
+      clientAccess: "public",
+    });
+    await expect(hotUpdater.api.notes.read("n1")).rejects.toThrow(
+      'Hot Updater schema setting "schema.notes" for memory is missing; expected "2". Run `hot-updater db migrate`.',
+    );
+    await expect(hotUpdater.core.listChannels()).rejects.toBeInstanceOf(
+      HotUpdaterSchemaMigrationRequiredError,
+    );
+    const channels = () =>
+      hotUpdater.handlers.admin(new Request("http://localhost/channels"));
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    expect((await channels()).status).toBe(503);
+    error.mockRestore();
+
+    await migrate(hotUpdater);
+    expect((await channels()).status).toBe(200);
+    await expect(hotUpdater.api.notes.read("n1")).resolves.toBeNull();
+    // The server without the plugin was already served.
+    await expect(
+      createHotUpdater({
+        database,
+        clientAccess: "public",
+      }).core.listChannels(),
+    ).resolves.toEqual([]);
+  });
+
+  it("writes a Kysely migration of the plugin's tables and settings row", async () => {
+    const db = new PGlite();
+    const kysely = new Kysely<object>({ dialect: new PGliteDialect(db) });
+    try {
+      const hotUpdater = createHotUpdater({
+        database: kyselyAdapter({ db: kysely, provider: "postgresql" }),
+        plugins: [notes],
+        clientAccess: "public",
+      });
+      const result = await createMigrator(hotUpdater).migrateToLatest({
+        mode: "from-schema",
+        updateSettings: true,
+      });
+      const sql = result.getSQL?.() ?? "";
+      expect(sql).toContain('CREATE TABLE IF NOT EXISTS "notes_notes"');
+      expect(sql).toContain(
+        'CREATE INDEX IF NOT EXISTS "notes_notes_byAuthor" ON "notes_notes" ("author", "id")',
+      );
+      expect(sql).toContain("VALUES ('schema.notes', '2', 0)");
+
+      await result.execute();
+      await hotUpdater.api.notes.add("n1", "ada", "hello");
+      await expect(hotUpdater.api.notes.read("n1")).resolves.toMatchObject({
+        text: "hello",
+      });
+    } finally {
+      await kysely.destroy();
+      await db.close();
+    }
+  });
+
+  it("generates Drizzle and Prisma schemas with the plugin's tables", () => {
+    const generated = (
+      database: Parameters<typeof createHotUpdater>[0]["database"],
+    ) =>
+      generateSchema(
+        createHotUpdater({
+          database,
+          plugins: [notes],
+          clientAccess: "public",
+        }),
+        "latest",
+      ).code;
+
+    expect(
+      generated(drizzleAdapter({ db: {}, provider: "postgresql" })),
+    ).toContain('pgTable("notes_notes"');
+    expect(
+      generated(prismaAdapter({ prisma: {}, provider: "postgresql" })),
+    ).toContain("model notes_notes {");
+  });
+
+  it("rejects a third-party plugin that takes a built-in plugin's id or table", () => {
+    const named = definePlugin({
+      id: "insights",
+      schemaVersion: "1",
+      schema: {
+        notes: defineTable({ id: { type: "string" } }, { key: ["id"] }),
+      },
+      init: () => ({ api: {} }),
+    });
+    const tabled = definePlugin({
+      id: "api",
+      schemaVersion: "1",
+      schema: {
+        keys: defineTable({ id: { type: "string" } }, { key: ["id"] }),
+      },
+      init: () => ({ api: {} }),
+    });
+
+    expect(() =>
+      createHotUpdater({
+        database: memoryDatabase(),
+        plugins: [named],
+        clientAccess: "public",
+      }),
+    ).toThrow(`Plugin "insights" uses a built-in plugin's id.`);
+    expect(() =>
+      createHotUpdater({
+        database: memoryDatabase(),
+        plugins: [tabled],
+        clientAccess: "public",
+      }),
+    ).toThrow(
+      'api.keys: table "api_keys" is also declared by apiKeys.api_keys',
+    );
+  });
+});

package/src/db/releaseCatalog.ts

@@ -1,24 +1,16 @@
 import {
   createReleaseCatalogScopeKey,
-  NIL_UUID,
   RELEASE_CATALOG_FALLBACK_POLICY,
   RELEASE_CATALOG_SCHEMA_VERSION,
-  type ArtifactInfo,
   type ReleaseCatalog,
 } from "@hot-updater/core";
 import {
-  createDatabaseClient,
   projectCompiledCatalog,
   projectCompiledRollbackCatalog,
   type CompiledReleaseCatalog,
-  type DatabasePlugin,
+  type ReleaseCatalogRow,
 } from "@hot-updater/plugin-core";
 
-import { resolveManifestArtifacts } from "./updateArtifacts";
-
-type ResolveFileUrl = (storageUri: string | null) => Promise<string | null>;
-type ReadStorageText = (storageUri: string) => Promise<string | null>;
-
 export type ReleaseCatalogRequest =
   | {
       readonly strategy: "APP_VERSION";
@@ -33,7 +25,8 @@ export type ReleaseCatalogRequest =
       readonly fingerprintHash: string;
     };
 
-const parseCompiledCatalog = (
+/** A stored catalog payload, checked against its strategy's shape. */
+export const parseCompiledCatalog = (
   payload: string,
   strategy: ReleaseCatalogRequest["strategy"],
 ): CompiledReleaseCatalog => {
@@ -63,86 +56,51 @@ const parseCompiledCatalog = (
   return parsed as CompiledReleaseCatalog;
 };
 
-export const createReleaseCatalogReader =
-  (database: DatabasePlugin) =>
-  async (input: ReleaseCatalogRequest): Promise<ReleaseCatalog | null> => {
-    const scopeKey =
-      input.strategy === "APP_VERSION"
-        ? createReleaseCatalogScopeKey({
-            channelKey: input.channelKey,
-            platform: input.platform,
-            strategy: "APP_VERSION",
-          })
-        : createReleaseCatalogScopeKey({
-            channelKey: input.channelKey,
-            fingerprintHash: input.fingerprintHash,
-            platform: input.platform,
-            strategy: "FINGERPRINT",
-          });
-    const row = await database.models.releaseCatalogs.findByScopeKey(scopeKey);
-    if (
-      row === null ||
-      row.platform !== input.platform ||
-      row.strategy !== input.strategy ||
-      row.channel_key !== input.channelKey ||
-      row.scope_key !== scopeKey ||
-      row.fingerprint_hash !==
-        (input.strategy === "FINGERPRINT" ? input.fingerprintHash : null)
-    ) {
-      return null;
-    }
-    const compiled = parseCompiledCatalog(row.payload, input.strategy);
-    const releases = projectCompiledCatalog(
-      compiled,
-      input.strategy === "APP_VERSION" ? input.appVersion : undefined,
-    );
-    const rollbackReleases = projectCompiledRollbackCatalog(
-      compiled,
-      input.strategy === "APP_VERSION" ? input.appVersion : undefined,
-    );
-    return {
-      catalogId: row.catalog_id,
-      catalogHash: row.catalog_hash,
-      fallbackPolicy: RELEASE_CATALOG_FALLBACK_POLICY,
-      generation: row.generation,
-      releases,
-      rollbackReleases,
-      schemaVersion: RELEASE_CATALOG_SCHEMA_VERSION,
-      scopeKey,
-    };
-  };
-
-export const createArtifactResolver = (input: {
-  readonly database: DatabasePlugin;
-  readonly readStorageText?: ReadStorageText;
-  readonly resolveFileUrl: ResolveFileUrl;
-}) => {
-  const databaseClient = createDatabaseClient(input.database);
+/** The scope key an update check reads. */
+export const releaseCatalogScopeKeyOf = (
+  input: ReleaseCatalogRequest,
+): string =>
+  input.strategy === "APP_VERSION"
+    ? createReleaseCatalogScopeKey({
+        channelKey: input.channelKey,
+        platform: input.platform,
+        strategy: "APP_VERSION",
+      })
+    : createReleaseCatalogScopeKey({
+        channelKey: input.channelKey,
+        fingerprintHash: input.fingerprintHash,
+        platform: input.platform,
+        strategy: "FINGERPRINT",
+      });
 
-  return async (
-    targetBundleId: string,
-    currentBundleId: string,
-  ): Promise<ArtifactInfo | null> => {
-    const [targetBundle, currentBundle] = await Promise.all([
-      databaseClient.getBundleById(targetBundleId),
-      currentBundleId === NIL_UUID
-        ? null
-        : databaseClient.getBundleById(currentBundleId),
-    ]);
-    if (targetBundle === null) return null;
-    const fileUrl = await input.resolveFileUrl(targetBundle.storageUri);
-    const base: ArtifactInfo = {
-      fileHash: targetBundle.fileHash,
-      fileUrl,
-    };
-    if (input.readStorageText === undefined) return base;
-    const manifest = await resolveManifestArtifacts({
-      archiveUrlUsable: fileUrl !== null,
-      currentBundle,
-      readStorageText: input.readStorageText,
-      resolveFileUrl: input.resolveFileUrl,
-      targetBundle,
-    });
-    return manifest === null ? base : { ...base, ...manifest };
+/** Projects a stored catalog row for one update check; null when the row is not this scope's. */
+export const projectReleaseCatalogRow = (
+  row: ReleaseCatalogRow | null,
+  input: ReleaseCatalogRequest,
+  scopeKey = releaseCatalogScopeKeyOf(input),
+): ReleaseCatalog | null => {
+  if (
+    row === null ||
+    row.platform !== input.platform ||
+    row.strategy !== input.strategy ||
+    row.channel_key !== input.channelKey ||
+    row.scope_key !== scopeKey ||
+    row.fingerprint_hash !==
+      (input.strategy === "FINGERPRINT" ? input.fingerprintHash : null)
+  ) {
+    return null;
+  }
+  const compiled = parseCompiledCatalog(row.payload, input.strategy);
+  const appVersion =
+    input.strategy === "APP_VERSION" ? input.appVersion : undefined;
+  return {
+    catalogId: row.catalog_id,
+    catalogHash: row.catalog_hash,
+    fallbackPolicy: RELEASE_CATALOG_FALLBACK_POLICY,
+    generation: row.generation,
+    releases: projectCompiledCatalog(compiled, appVersion),
+    rollbackReleases: projectCompiledRollbackCatalog(compiled, appVersion),
+    schemaVersion: RELEASE_CATALOG_SCHEMA_VERSION,
+    scopeKey,
   };
 };

package/src/db/schemaSettings.ts

@@ -0,0 +1,104 @@
+import type {
+  DatabaseAdapter,
+  PhysicalTable,
+  StoredRow,
+  WriteOp,
+} from "@hot-updater/plugin-core/internal";
+
+import {
+  ENGINE_SCHEMA_KEY,
+  ENGINE_SCHEMA_VERSION,
+  HotUpdaterSchemaMigrationRequiredError,
+  isMissingSchemaError,
+  readSettings,
+  SETTINGS_TABLE,
+  type SchemaSettings,
+} from "../database/fence";
+
+/** Refuses a database with `schema.core` but no `schema.engine`: it predates the engine. */
+const assertEngineDatabase = (
+  adapterName: string,
+  stored: ReadonlyMap<string, StoredRow | null>,
+) => {
+  if (stored.get("schema.core") && !stored.get(ENGINE_SCHEMA_KEY)) {
+    throw new HotUpdaterSchemaMigrationRequiredError(
+      adapterName,
+      String(stored.get("schema.core")!.value),
+      { key: ENGINE_SCHEMA_KEY, expected: ENGINE_SCHEMA_VERSION, found: null },
+    );
+  }
+};
+
+const storedSettings = async (
+  adapter: DatabaseAdapter,
+  keys: readonly string[],
+) => {
+  const rows = await readSettings(adapter, keys);
+  return new Map(keys.map((key, position) => [key, rows[position] ?? null]));
+};
+
+/** Writes the settings rows after every table exists, refusing a pre-engine database. */
+export const writeSchemaSettings = async (
+  adapter: DatabaseAdapter,
+  adapterName: string,
+  settings: SchemaSettings,
+): Promise<void> => {
+  const stored = await storedSettings(adapter, [
+    ...new Set(["schema.core", ENGINE_SCHEMA_KEY, ...Object.keys(settings)]),
+  ]);
+  assertEngineDatabase(adapterName, stored);
+  const ops = Object.entries(settings).flatMap(([key, value]): WriteOp[] => {
+    const row = stored.get(key);
+    if (row === null || row === undefined) {
+      return [
+        { type: "insert", table: SETTINGS_TABLE, row: { key, value, _v: 0 } },
+      ];
+    }
+    if (row.value === value) return [];
+    return [
+      {
+        type: "patch",
+        table: SETTINGS_TABLE,
+        key: [key],
+        set: { value },
+        guard: { v: Number(row._v) },
+        previous: row,
+      },
+    ];
+  });
+  if (ops.length === 0) return;
+  const result = await adapter.write(ops);
+  if (!result.ok) {
+    throw new Error(
+      "The schema settings changed during the migration; run it again.",
+    );
+  }
+};
+
+/**
+ * Creates or updates every table, then writes the settings rows last. A
+ * pre-engine database is refused before any table changes.
+ */
+export const migrateSchema = async (
+  adapter: DatabaseAdapter,
+  adapterName: string,
+  tables: readonly PhysicalTable[],
+  settings: SchemaSettings,
+): Promise<void> => {
+  if (adapter.migrations === undefined) {
+    throw new Error(
+      `${adapterName} creates its tables with its own tooling; write only the settings rows.`,
+    );
+  }
+  // A database without the settings table is empty, so nothing is refused.
+  const stored = await storedSettings(adapter, [
+    "schema.core",
+    ENGINE_SCHEMA_KEY,
+  ]).catch((error: unknown) => {
+    if (!isMissingSchemaError(error)) throw error;
+    return new Map<string, StoredRow | null>();
+  });
+  assertEngineDatabase(adapterName, stored);
+  await adapter.migrations.apply([...tables, SETTINGS_TABLE]);
+  await writeSchemaSettings(adapter, adapterName, settings);
+};

package/src/db/settingsMigrator.spec.ts

@@ -0,0 +1,65 @@
+import { DatabaseSync } from "node:sqlite";
+
+import { describe, expect, it } from "vitest";
+
+import { checkSchemaFence, SETTINGS_TABLE } from "../database/fence";
+import { createSqlAdapter } from "../database/sql/sqlAdapter";
+import { createTableStatements } from "../database/sql/sqlSchema";
+import { sqliteExecutor } from "../database/sql/sqlTestExecutors";
+import { createSettingsMigrator } from "./settingsMigrator";
+
+const settings = { "schema.engine": "1", "schema.core": "1.0.0" };
+
+const migratorOver = (database: DatabaseSync) =>
+  createSettingsMigrator({
+    adapterName: "orm",
+    executor: sqliteExecutor(database),
+    settings,
+    applyTables: "the ORM's push",
+  });
+
+describe("the settings-only migrator", () => {
+  it("writes only the settings rows once the ORM applied the tables, then has nothing left", async () => {
+    const database = new DatabaseSync(":memory:");
+    database.exec(createTableStatements("sqlite", [SETTINGS_TABLE]).join(";"));
+    const migrator = migratorOver(database);
+
+    const pending = await migrator.migrateToLatest();
+    expect(pending.operations).toEqual([
+      expect.objectContaining({ type: "custom" }),
+    ]);
+    expect(pending.getSQL?.()).toContain("ON CONFLICT");
+    await pending.execute();
+    await expect(migrator.migrateToLatest()).resolves.toMatchObject({
+      operations: [],
+    });
+    await expect(migrator.getVersion()).resolves.toBe("1.0.0");
+    await expect(
+      checkSchemaFence(
+        createSqlAdapter({ executor: sqliteExecutor(database) }),
+        "orm",
+        settings,
+      ),
+    ).resolves.toBeUndefined();
+  });
+
+  it("asks for the ORM's tables first, refuses a database from before the engine, and rethrows other failures", async () => {
+    await expect(
+      migratorOver(new DatabaseSync(":memory:")).migrateToLatest(),
+    ).rejects.toThrow("the ORM's push");
+
+    const legacy = new DatabaseSync(":memory:");
+    legacy.exec(
+      "CREATE TABLE private_hot_updater_settings (key TEXT PRIMARY KEY, value TEXT NOT NULL); INSERT INTO private_hot_updater_settings VALUES ('schema.core', '1.0.0');",
+    );
+    await expect(migratorOver(legacy).migrateToLatest()).rejects.toMatchObject({
+      setting: { key: "schema.engine", expected: "1", found: null },
+    });
+
+    const closed = new DatabaseSync(":memory:");
+    closed.close();
+    await expect(migratorOver(closed).migrateToLatest()).rejects.toThrow(
+      "database is not open",
+    );
+  });
+});