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

package/src/adapters/drizzle.ts

@@ -1,144 +1,64 @@
-import { createDatabasePlugin } from "@hot-updater/plugin-core";
+import { createSqlAdapter } from "../database/sql/sqlAdapter";
 import {
-  createDatabasePluginAdapter,
-  type DatabasePluginImplementation,
-  type TransactionDatabasePluginImplementation,
-} from "@hot-updater/plugin-core/internal";
-
-import {
-  getHotUpdaterSchemaVersion,
-  hotUpdaterSchema,
-} from "../db/schema/registry";
-import { generateDrizzleSchema } from "../db/schemaGenerators";
+  builtInSettings,
+  builtInTarget,
+  createEngineDatabase,
+} from "../db/builtInDatabase";
+import { generateDrizzleEngineSchema } from "../db/engineDrizzleSchema";
+import { createSettingsMigrator } from "../db/settingsMigrator";
 import type {
-  DatabaseAdapterWithCapabilities,
-  ORMProvider,
+  ORMSQLProvider,
   SchemaGenerator,
+  ToolingDatabase,
 } from "../db/types";
-import { createDrizzleCrud } from "./drizzleCrud";
-import { createLazyDB } from "./drizzleLazyDB";
+import { drizzleExecutor } from "./drizzleExecutor";
+import { checkSqlProvider } from "./sqlProviders";
 
-export type DrizzleProvider = Exclude<
-  ORMProvider,
-  "cockroachdb" | "mongodb" | "mssql"
->;
+export {
+  DrizzleTransactionUnsupportedError,
+  SUPPORTED_DRIZZLE_DRIVERS,
+} from "./drizzleExecutor";
+
+export type DrizzleProvider = ORMSQLProvider;
 
 export interface DrizzleConfig {
+  /** A Drizzle database, or a function that returns one on first use. */
   readonly db: unknown | (() => unknown | Promise<unknown>);
   readonly provider: DrizzleProvider;
+  /** Ignored: Hot Updater reads through SQL; the schema file is for drizzle-kit. */
   readonly schema?: Record<string, unknown>;
-  readonly transaction?: boolean;
 }
 
-const createImplementation = (
-  config: DrizzleConfig,
-): DatabasePluginImplementation => {
-  const db = createLazyDB(config);
-  const crud = createDrizzleCrud(db, config.provider);
-  const transaction = db.transaction?.bind(db);
+/**
+ * Hot Updater's database on a Drizzle instance: the storage engine through the
+ * shared SQL core, fenced by the schema settings. `db generate` writes the
+ * Drizzle schema drizzle-kit applies; `db migrate` then writes the settings
+ * rows the fence checks.
+ */
+export const drizzleAdapter = (config: DrizzleConfig): ToolingDatabase => {
+  const provider = checkSqlProvider("drizzleAdapter", config.provider);
+  const executor = drizzleExecutor(config.db, provider);
   return {
-    ...crud,
-    deleteChannel: (input) => {
-      if (transaction === undefined) {
-        throw new Error(
-          "Drizzle channel deletion requires transaction support.",
-        );
+    ...createEngineDatabase({
+      name: "drizzle",
+      adapter: createSqlAdapter({ executor }),
+    }),
+    provider,
+    generateSchema: ((version, _name, { schema } = builtInTarget) => {
+      if (version !== "latest" && version !== builtInSettings["schema.core"]) {
+        throw new Error(`Invalid version ${version}`);
       }
-      return transaction((transactionDatabase) =>
-        createDrizzleCrud(transactionDatabase, config.provider).deleteChannel(
-          input,
-        ),
-      );
-    },
-    ...(transaction
-      ? {
-          delete: (input: Parameters<typeof crud.delete>[0]) =>
-            transaction((transactionDatabase) =>
-              createDrizzleCrud(transactionDatabase, config.provider).delete(
-                input,
-              ),
-            ),
-        }
-      : {}),
-    ...(transaction
-      ? {
-          transaction: async <TResult>(
-            callback: (
-              transaction: TransactionDatabasePluginImplementation,
-            ) => Promise<TResult>,
-          ): Promise<TResult> =>
-            transaction((transaction) =>
-              callback(createDrizzleCrud(transaction, config.provider)),
-            ),
-        }
-      : {}),
+      return {
+        code: generateDrizzleEngineSchema(provider, schema),
+        path: "hot-updater-schema.ts",
+      };
+    }) satisfies SchemaGenerator,
+    createMigrator: ({ settings } = builtInTarget) =>
+      createSettingsMigrator({
+        adapterName: "drizzle",
+        executor,
+        settings,
+        applyTables: "`drizzle-kit push` (or your drizzle-kit migrations)",
+      }),
   };
 };
-
-export const drizzleAdapter = (
-  config: DrizzleConfig,
-): DatabaseAdapterWithCapabilities => {
-  let adapter: ReturnType<typeof createDatabasePluginAdapter> | undefined;
-  const getAdapter = () => {
-    adapter ??= createDatabasePluginAdapter(
-      "drizzle",
-      createImplementation(config),
-    );
-    return adapter;
-  };
-  const plugin = createDatabasePlugin({
-    name: "drizzle",
-    models: {
-      bundles: {
-        findById: (id) => getAdapter().models.bundles.findById(id),
-        findMany: (query) => getAdapter().models.bundles.findMany(query),
-        count: (where) => getAdapter().models.bundles.count(where),
-      },
-      bundlePatches: {
-        findByBundleIds: (bundleIds) =>
-          getAdapter().models.bundlePatches.findByBundleIds(bundleIds),
-      },
-      releases: {
-        findById: (id) => getAdapter().models.releases.findById(id),
-        findMany: (input) => getAdapter().models.releases.findMany(input),
-        findManyByScope: (input) =>
-          getAdapter().models.releases.findManyByScope(input),
-      },
-      releaseCatalogs: {
-        findByScopeKey: (scopeKey) =>
-          getAdapter().models.releaseCatalogs.findByScopeKey(scopeKey),
-        findMany: (input) =>
-          getAdapter().models.releaseCatalogs.findMany(input),
-      },
-      channels: {
-        insert: (input) => getAdapter().models.channels.insert(input),
-        list: (input) => getAdapter().models.channels.list(input),
-        delete: (input) => getAdapter().models.channels.delete(input),
-      },
-      insights: {
-        append: (row) => getAdapter().models.insights.append(row),
-        scan: (input) => getAdapter().models.insights.scan(input),
-      },
-      apiKeys: {
-        create: (row) => getAdapter().models.apiKeys.create(row),
-        findByHash: (hash) => getAdapter().models.apiKeys.findByHash(hash),
-        list: () => getAdapter().models.apiKeys.list(),
-        revoke: (input) => getAdapter().models.apiKeys.revoke(input),
-      },
-    },
-    commit: (input) => getAdapter().commit(input),
-  });
-  return Object.assign(plugin, {
-    adapterName: "drizzle",
-    provider: config.provider,
-    generateSchema: (version: Parameters<SchemaGenerator>[0]) => ({
-      code: generateDrizzleSchema(
-        config.provider,
-        version === "latest"
-          ? hotUpdaterSchema
-          : getHotUpdaterSchemaVersion(version),
-      ),
-      path: "hot-updater-schema.ts",
-    }),
-  });
-};

package/src/adapters/drizzleExecutor.ts

@@ -0,0 +1,166 @@
+import { sql, type SQL } from "drizzle-orm";
+
+import type {
+  SqlConnection,
+  SqlDialect,
+  SqlExecutor,
+  SqlResult,
+  SqlStatement,
+} from "../database/sql/sqlAdapter";
+
+/** The members of a Drizzle database or transaction the executor uses. */
+interface DrizzleRunner {
+  execute?(query: SQL): Promise<unknown>;
+  all?(query: SQL): unknown;
+  run?(query: SQL): unknown;
+  transaction?(fn: (tx: DrizzleRunner) => Promise<unknown>): unknown;
+  /** SQLite drivers: `sync` for better-sqlite3 and bun:sqlite. */
+  readonly resultKind?: "sync" | "async";
+}
+
+export const SUPPORTED_DRIZZLE_DRIVERS =
+  "node-postgres, postgres-js, PGlite, or Neon over WebSockets for PostgreSQL; mysql2 for MySQL; libSQL, better-sqlite3, or bun:sqlite for SQLite";
+
+export class DrizzleTransactionUnsupportedError extends Error {
+  readonly name = "DrizzleTransactionUnsupportedError";
+  constructor(cause: unknown) {
+    super(
+      `This Drizzle driver cannot run interactive transactions, which Hot Updater needs. Use ${SUPPORTED_DRIZZLE_DRIVERS}.`,
+      { cause },
+    );
+  }
+}
+
+/** The SQL core's statement as Drizzle SQL, each placeholder bound as a parameter. */
+const toSql = (dialect: SqlDialect, { sql: text, params }: SqlStatement) => {
+  const pattern = dialect === "postgresql" ? /\$(\d+)/gu : /\?/gu;
+  const chunks: SQL[] = [];
+  let last = 0;
+  let next = 0;
+  for (const match of text.matchAll(pattern)) {
+    chunks.push(sql.raw(text.slice(last, match.index)));
+    const position = dialect === "postgresql" ? Number(match[1]) - 1 : next++;
+    chunks.push(sql`${sql.param(params[position])}`);
+    last = match.index + match[0].length;
+  }
+  chunks.push(sql.raw(text.slice(last)));
+  return sql.join(chunks);
+};
+
+const over = (dialect: SqlDialect, runner: DrizzleRunner): SqlConnection => ({
+  async execute(statement): Promise<SqlResult> {
+    const query = toSql(dialect, statement);
+    if (dialect === "sqlite") {
+      return /^\s*SELECT\b/iu.test(statement.sql)
+        ? {
+            rows: (await runner.all!(query)) as Record<string, unknown>[],
+            changes: 0,
+          }
+        : { rows: [], changes: changesOf(await runner.run!(query)) };
+    }
+    const result = await runner.execute!(query);
+    // mysql2 answers [rows or header, fields]; postgres-js answers the rows.
+    const value =
+      dialect === "mysql" && Array.isArray(result) ? result[0] : result;
+    const rows = Array.isArray(value)
+      ? value
+      : ((value as { rows?: unknown[] }).rows ?? []);
+    return {
+      rows: rows as Record<string, unknown>[],
+      changes:
+        Array.isArray(value) && dialect === "mysql" ? 0 : changesOf(value),
+    };
+  },
+});
+
+const changesOf = (result: unknown): number => {
+  const record = (result ?? {}) as Record<string, unknown>;
+  const meta = record.meta as Record<string, unknown> | undefined;
+  return Number(
+    record.rowCount ??
+      record.affectedRows ??
+      record.rowsAffected ??
+      record.changes ??
+      record.count ??
+      meta?.changes ??
+      0,
+  );
+};
+
+/**
+ * The SQL core's executor over a Drizzle database, or a function that
+ * returns one. Async drivers run Drizzle's transactions; sync SQLite drivers
+ * run one statement at a time, beginning transactions with BEGIN IMMEDIATE.
+ * First use checks that the driver can run a transaction at all.
+ */
+export const drizzleExecutor = (
+  source: unknown,
+  dialect: SqlDialect,
+): SqlExecutor => {
+  const isSync = (runner: DrizzleRunner) =>
+    dialect === "sqlite" && runner.resultKind === "sync";
+  let ready: Promise<DrizzleRunner> | undefined;
+  const resolve = () => {
+    ready ??= (async () => {
+      const runner = (await (typeof source === "function"
+        ? (source as () => unknown)()
+        : source)) as DrizzleRunner;
+      if (isSync(runner)) return runner;
+      let started = false;
+      try {
+        if (typeof runner.transaction !== "function") {
+          throw new TypeError("The Drizzle database has no transaction().");
+        }
+        await runner.transaction(async () => {
+          started = true;
+        });
+      } catch (error) {
+        if (!started) throw new DrizzleTransactionUnsupportedError(error);
+        throw error;
+      }
+      return runner;
+    })();
+    // A failed check runs again next time.
+    ready.catch(() => {
+      ready = undefined;
+    });
+    return ready;
+  };
+  // Sync drivers share one connection: nothing may interleave a transaction.
+  let queue: Promise<unknown> = Promise.resolve();
+  const serial = <T>(task: () => Promise<T>) => {
+    const result = queue.then(task);
+    queue = result.catch(() => undefined);
+    return result;
+  };
+  return {
+    dialect,
+    async execute(statement) {
+      const runner = await resolve();
+      const run = () => over(dialect, runner).execute(statement);
+      return isSync(runner) ? serial(run) : run();
+    },
+    async transaction(fn) {
+      const runner = await resolve();
+      if (!isSync(runner)) {
+        return (await runner.transaction!((tx) =>
+          fn(over(dialect, tx)),
+        )) as Awaited<ReturnType<typeof fn>>;
+      }
+      return serial(async () => {
+        const connection = over(dialect, runner);
+        const raw = (text: string) =>
+          connection.execute({ sql: text, params: [] });
+        await raw("BEGIN IMMEDIATE");
+        try {
+          const result = await fn(connection);
+          await raw("COMMIT");
+          return result;
+        } catch (error) {
+          await raw("ROLLBACK").catch(() => undefined);
+          throw error;
+        }
+      });
+    },
+  };
+};

package/src/adapters/kysely.conformance.integration.spec.ts

@@ -0,0 +1,36 @@
+import { PGlite } from "@electric-sql/pglite";
+import { setupDatabaseAdapterConformanceSuite } from "@hot-updater/test-utils";
+import { Kysely } from "kysely";
+import { PGliteDialect } from "kysely-pglite-dialect";
+
+import { SETTINGS_TABLE } from "../database/fence";
+import { createTableStatements } from "../database/sql/sqlSchema";
+import { builtInSettings } from "../db/builtInDatabase";
+import { settingsStatements } from "../db/engineSql";
+import { kyselyAdapter } from "./kysely";
+
+/**
+ * The adapter `kyselyAdapter` returns, schema fence included, on a new PGlite
+ * per test that holds the conformance tables and the settings rows the fence
+ * checks. PostgreSQL has no cap on one write and no native pages.
+ */
+setupDatabaseAdapterConformanceSuite({
+  name: "kysely (PGlite)",
+  createAdapter: async ({ tables }) => {
+    const client = new PGlite();
+    await client.exec(
+      [
+        ...createTableStatements("postgresql", [...tables, SETTINGS_TABLE]),
+        ...settingsStatements("postgresql", builtInSettings),
+      ].join(";\n"),
+    );
+    const db = new Kysely<object>({ dialect: new PGliteDialect(client) });
+    return {
+      adapter: kyselyAdapter({ db, provider: "postgresql" }).adapter,
+      cleanup: async () => {
+        await db.destroy();
+        await client.close();
+      },
+    };
+  },
+});

package/src/adapters/kysely.readBudgets.integration.spec.ts

@@ -0,0 +1,42 @@
+import { PGlite } from "@electric-sql/pglite";
+import {
+  postgresRowsExamined,
+  setupReadBudgetTestSuite,
+} from "@hot-updater/test-utils";
+import { Kysely } from "kysely";
+import { PGliteDialect } from "kysely-pglite-dialect";
+
+import { createSqlAdapter } from "../database/sql/sqlAdapter";
+import { readBudgetServer } from "../readBudgets.testFixtures";
+import { kyselyAdapter } from "./kysely";
+import { kyselyExecutor } from "./kyselyExecutor";
+
+/**
+ * `kyselyAdapter`'s composition without its schema fence: the SQL core over
+ * the Kysely executor on PGlite, on the tables its migrator creates.
+ */
+setupReadBudgetTestSuite({
+  name: "kysely (PGlite)",
+  server: readBudgetServer,
+  createAdapter: async () => {
+    const client = new PGlite();
+    const db = new Kysely<object>({ dialect: new PGliteDialect(client) });
+    const migrator = kyselyAdapter({ db, provider: "postgresql" })
+      .createMigrator!();
+    await (await migrator.migrateToLatest()).execute();
+    const reads = postgresRowsExamined(
+      async (sql, params) =>
+        (await client.query<Record<string, unknown>>(sql, [...params])).rows,
+    );
+    return {
+      adapter: createSqlAdapter({
+        executor: reads.wrap(kyselyExecutor(db, "postgresql")),
+      }),
+      examined: reads.examined,
+      cleanup: async () => {
+        await db.destroy();
+        await client.close();
+      },
+    };
+  },
+});