@hot-updater/server 1.0.0-rc.18 → 1.0.0-rc.21

package/src/database/fence.spec.ts

@@ -1,223 +0,0 @@
-import { DatabaseSync } from "node:sqlite";
-
-import { PGlite } from "@electric-sql/pglite";
-import {
-  createMemoryAdapter,
-  type DatabaseAdapter,
-} from "@hot-updater/plugin-core/internal";
-import { afterAll, describe, expect, it, vi } from "vitest";
-
-import {
-  coreSettings,
-  createEngineDatabase,
-  migrateCoreSchema,
-} from "../db/coreDatabase";
-import { migrateSchema, writeSchemaSettings } from "../db/schemaSettings";
-import { createHotUpdater } from "../index";
-import {
-  checkSchemaFence,
-  HotUpdaterSchemaMigrationRequiredError,
-  isMissingSchemaError,
-  SETTINGS_TABLE,
-  withSchemaFence,
-} from "./fence";
-import { createSqlAdapter } from "./sql/sqlAdapter";
-import { pgliteExecutor, sqliteExecutor } from "./sql/sqlTestExecutors";
-
-const settings = { "schema.engine": "1", "schema.core": "1.0.0" };
-
-/** Counts the adapter's point reads. */
-const counted = (adapter: DatabaseAdapter) => {
-  const calls = { gets: 0 };
-  return {
-    calls,
-    adapter: {
-      ...adapter,
-      get: (table, keys) => {
-        calls.gets += 1;
-        return adapter.get(table, keys);
-      },
-    } satisfies DatabaseAdapter,
-  };
-};
-
-const mismatch = (promise: Promise<unknown>) =>
-  promise.then(
-    () => undefined,
-    (error: unknown) =>
-      error instanceof HotUpdaterSchemaMigrationRequiredError
-        ? error.setting
-        : error,
-  );
-
-describe("schema fence", () => {
-  it("passes once migrations wrote every setting, and names the first missing or different one", async () => {
-    const memory = createMemoryAdapter();
-    await expect(
-      mismatch(checkSchemaFence(memory, "memory", settings)),
-    ).resolves.toEqual({
-      key: "schema.engine",
-      expected: "1",
-      found: null,
-    });
-
-    await migrateSchema(memory, "memory", [], settings);
-    await expect(
-      checkSchemaFence(memory, "memory", settings),
-    ).resolves.toBeUndefined();
-    await expect(
-      mismatch(
-        checkSchemaFence(memory, "memory", {
-          ...settings,
-          "schema.insights": "1.0.0",
-        }),
-      ),
-    ).resolves.toEqual({
-      key: "schema.insights",
-      expected: "1.0.0",
-      found: null,
-    });
-    await expect(
-      mismatch(checkSchemaFence(memory, "memory", { "schema.core": "2.0.0" })),
-    ).resolves.toEqual({
-      key: "schema.core",
-      expected: "2.0.0",
-      found: "1.0.0",
-    });
-  });
-
-  it("checks before a process's first read only, and again after a failure", async () => {
-    const memory = createMemoryAdapter();
-    const { adapter, calls } = counted(memory);
-    const fenced = withSchemaFence(adapter, "memory", settings);
-    await expect(fenced.get(SETTINGS_TABLE, [["x"]])).rejects.toBeInstanceOf(
-      HotUpdaterSchemaMigrationRequiredError,
-    );
-    await expect(fenced.get(SETTINGS_TABLE, [["x"]])).rejects.toBeInstanceOf(
-      HotUpdaterSchemaMigrationRequiredError,
-    );
-    expect(calls.gets).toBe(2);
-
-    await migrateSchema(memory, "memory", [], settings);
-    calls.gets = 0;
-    await fenced.get(SETTINGS_TABLE, [["x"]]);
-    await fenced.get(SETTINGS_TABLE, [["x"]]);
-    // one fence read, then the two reads themselves
-    expect(calls.gets).toBe(3);
-  });
-
-  it("rewrites only changed settings and refuses a database from before the engine", async () => {
-    const memory = createMemoryAdapter();
-    await migrateSchema(memory, "memory", [], settings);
-    const writes: unknown[] = [];
-    const recorded: DatabaseAdapter = {
-      ...memory,
-      write: (ops) => {
-        writes.push(ops);
-        return memory.write(ops);
-      },
-    };
-    await writeSchemaSettings(recorded, "memory", settings);
-    expect(writes).toEqual([]);
-    await writeSchemaSettings(recorded, "memory", {
-      ...settings,
-      "schema.insights": "1.0.0",
-    });
-    expect(writes).toHaveLength(1);
-
-    const legacy = createMemoryAdapter();
-    await legacy.write([
-      {
-        type: "insert",
-        table: SETTINGS_TABLE,
-        row: { key: "schema.core", value: "1.0.0", _v: 0 },
-      },
-    ]);
-    await expect(
-      mismatch(writeSchemaSettings(legacy, "memory", settings)),
-    ).resolves.toEqual({ key: "schema.engine", expected: "1", found: null });
-  });
-  it("reads a missing table as missing settings and rethrows any other failure", async () => {
-    const empty = createSqlAdapter({
-      executor: sqliteExecutor(new DatabaseSync(":memory:")),
-    });
-    await expect(
-      mismatch(checkSchemaFence(empty, "sqlite", settings)),
-    ).resolves.toEqual({ key: "schema.engine", expected: "1", found: null });
-
-    const refused = new Error("connect ECONNREFUSED 127.0.0.1:5432");
-    const offline: DatabaseAdapter = {
-      ...createMemoryAdapter(),
-      get: async () => {
-        throw refused;
-      },
-    };
-    await expect(checkSchemaFence(offline, "memory", settings)).rejects.toBe(
-      refused,
-    );
-    await expect(migrateSchema(offline, "memory", [], settings)).rejects.toBe(
-      refused,
-    );
-  });
-
-  it.each([
-    [
-      "PostgreSQL",
-      Object.assign(new Error('relation "x" does not exist'), {
-        code: "42P01",
-      }),
-    ],
-    [
-      "MySQL",
-      Object.assign(new Error("Table 'db.x' doesn't exist"), {
-        code: "ER_NO_SUCH_TABLE",
-      }),
-    ],
-    ["SQLite", new Error("SQLITE_ERROR: no such table: x")],
-    [
-      "an ORM wrapping the driver",
-      new Error("Failed query", { cause: new Error("no such column: _v") }),
-    ],
-  ])("recognizes a missing table or column from %s", (_, error) => {
-    expect(isMissingSchemaError(error)).toBe(true);
-  });
-
-  it("does not take a missing database or a driver failure for a missing table", () => {
-    expect(isMissingSchemaError(new Error('database "x" does not exist'))).toBe(
-      false,
-    );
-    expect(
-      isMissingSchemaError(Object.assign(new Error("x"), { code: "28P01" })),
-    ).toBe(false);
-  });
-});
-
-describe("a provider's fenced database on PGlite", () => {
-  const pglite = new PGlite();
-  afterAll(() => pglite.close());
-
-  it("answers 503 before migrations and serves after them", async () => {
-    const adapter = createSqlAdapter({
-      executor: pgliteExecutor(pglite),
-      tablePrefix: "fence_",
-    });
-    const hotUpdater = createHotUpdater({
-      database: createEngineDatabase({ name: "pglite", adapter }),
-      clientAccess: "public",
-    });
-    const channels = () =>
-      hotUpdater.handlers.admin(
-        new Request("https://updates.example.com/channels"),
-      );
-
-    const error = vi.spyOn(console, "error").mockImplementation(() => {});
-    expect((await channels()).status).toBe(503);
-    error.mockRestore();
-    await migrateCoreSchema(adapter, "pglite");
-    await expect(
-      checkSchemaFence(adapter, "pglite", coreSettings),
-    ).resolves.toBeUndefined();
-    expect((await channels()).status).toBe(200);
-    await expect(hotUpdater.core.listChannels()).resolves.toEqual([]);
-  });
-});

package/src/database/fence.ts

@@ -1,175 +0,0 @@
-import type {
-  DatabaseAdapter,
-  PhysicalTable,
-  StoredRow,
-} from "@hot-updater/plugin-core/internal";
-
-/** The settings rows migrations write, last, and the fence reads. */
-export const SETTINGS_TABLE: PhysicalTable = {
-  name: "private_hot_updater_settings",
-  columns: [
-    { name: "key", type: "string", nullable: false, maxLength: 255 },
-    { name: "value", type: "string", nullable: false, maxLength: 255 },
-    { name: "_v", type: "integer", nullable: false, default: 0 },
-  ],
-  key: ["key"],
-  indexes: [],
-};
-
-/** The engine's storage-layout generation; it changes only with a migration. */
-export const ENGINE_SCHEMA_KEY = "schema.engine";
-export const ENGINE_SCHEMA_VERSION = "1";
-
-/** A schema setting the fence found missing or different. */
-export interface SchemaSettingMismatch {
-  readonly key: string;
-  readonly expected: string;
-  readonly found: string | null;
-}
-
-const settingMessage = (
-  adapterName: string,
-  { key, expected, found }: SchemaSettingMismatch,
-) =>
-  `Hot Updater schema setting "${key}" for ${adapterName} is ${found === null ? "missing" : `"${found}"`}; expected "${expected}". ${
-    key === ENGINE_SCHEMA_KEY
-      ? "Create a new empty database and run `hot-updater db migrate`; databases from before the storage engine are not converted."
-      : "Run `hot-updater db migrate`."
-  }`;
-
-/** The database needs `hot-updater db migrate`, or a new database; the handler answers 503. */
-export class HotUpdaterSchemaMigrationRequiredError extends Error {
-  constructor(
-    readonly adapterName: string,
-    readonly currentVersion: string | undefined,
-    readonly setting?: SchemaSettingMismatch,
-    options?: ErrorOptions,
-  ) {
-    super(
-      setting !== undefined
-        ? settingMessage(adapterName, setting)
-        : currentVersion === undefined
-          ? `Hot Updater database schema is not initialized for ${adapterName}. Run \`hot-updater db migrate\` before using this adapter.`
-          : `Hot Updater v1 cannot migrate schema ${currentVersion} in place. Create a new empty database and run \`hot-updater db migrate\`.`,
-      options,
-    );
-    this.name = "HotUpdaterSchemaMigrationRequiredError";
-  }
-}
-
-/** Settings keys and the values a process expects, `schema.engine` included. */
-export type SchemaSettings = Readonly<Record<string, string>>;
-
-/** Driver codes for a table or column the database lacks. */
-const MISSING_SCHEMA_CODES = new Set([
-  "42P01", // PostgreSQL undefined_table
-  "42703", // PostgreSQL undefined_column
-  "ER_NO_SUCH_TABLE", // MySQL 1146
-  "ER_BAD_FIELD_ERROR", // MySQL 1054
-]);
-const MISSING_SCHEMA_MESSAGE =
-  /no such (?:table|column)|(?:relation|column) .+ does not exist|table .+ doesn't exist|unknown column/iu;
-
-/**
- * Whether a read failed because a table or column is missing, so the
- * database needs migrations. ORMs may wrap the driver's error in `cause`.
- */
-export const isMissingSchemaError = (error: unknown): boolean => {
-  for (let depth = 0; error instanceof Object && depth < 8; depth += 1) {
-    const { code, message, cause } = error as Record<string, unknown>;
-    if (
-      MISSING_SCHEMA_CODES.has(String(code)) ||
-      (typeof message === "string" && MISSING_SCHEMA_MESSAGE.test(message))
-    ) {
-      return true;
-    }
-    error = cause;
-  }
-  return false;
-};
-
-export const readSettings = (
-  adapter: DatabaseAdapter,
-  keys: readonly string[],
-) =>
-  adapter.get(
-    SETTINGS_TABLE,
-    keys.map((key) => [key]),
-  );
-
-/** Throws unless every expected setting is stored with its value: one batch read. */
-export const checkSchemaFence = async (
-  adapter: DatabaseAdapter,
-  adapterName: string,
-  expected: SchemaSettings,
-): Promise<void> => {
-  const keys = Object.keys(expected);
-  let rows: readonly (StoredRow | null)[];
-  try {
-    rows = await readSettings(adapter, keys);
-  } catch (cause) {
-    // A connection or driver failure is not a schema to migrate.
-    if (!isMissingSchemaError(cause)) throw cause;
-    throw new HotUpdaterSchemaMigrationRequiredError(
-      adapterName,
-      undefined,
-      { key: ENGINE_SCHEMA_KEY, expected: ENGINE_SCHEMA_VERSION, found: null },
-      { cause },
-    );
-  }
-  keys.forEach((key, position) => {
-    const found = rows[position]?.value;
-    if (found !== expected[key]) {
-      throw new HotUpdaterSchemaMigrationRequiredError(adapterName, undefined, {
-        key,
-        expected: expected[key]!,
-        found: typeof found === "string" ? found : null,
-      });
-    }
-  });
-};
-
-/** The database name a fenced adapter carries, so a server can fence its plugins' rows too. */
-const FENCED: unique symbol = Symbol.for("@hot-updater/server/schema-fence");
-
-interface FencedAdapter extends DatabaseAdapter {
-  readonly [FENCED]?: string;
-}
-
-/** The database name an adapter behind the schema fence reports under. */
-export const fencedName = (adapter: FencedAdapter): string | undefined =>
-  adapter[FENCED];
-
-/**
- * The adapter behind the schema fence: a process's first read or write
- * checks the settings first. Success is kept; a failure is checked again on
- * the next call.
- */
-export const withSchemaFence = (
-  adapter: DatabaseAdapter,
-  adapterName: string,
-  expected: SchemaSettings,
-): FencedAdapter => {
-  let ready: Promise<void> | undefined;
-  const fence = () => {
-    ready ??= checkSchemaFence(adapter, adapterName, expected).catch(
-      (error: unknown) => {
-        ready = undefined;
-        throw error;
-      },
-    );
-    return ready;
-  };
-  return {
-    ...adapter,
-    [FENCED]: adapterName,
-    get: (table, keys) => fence().then(() => adapter.get(table, keys)),
-    query: (table, request) =>
-      fence().then(() => adapter.query(table, request)),
-    write: (ops) => fence().then(() => adapter.write(ops)),
-    ...(adapter.prune && {
-      prune: (table, before, limit) =>
-        fence().then(() => adapter.prune!(table, before, limit)),
-    }),
-  };
-};

package/src/database/index.ts

@@ -1,160 +0,0 @@
-/**
- * What database providers and storage adapter authors build on: the storage
- * adapter contract, the SQL core and key-value helper that implement it,
- * `createEngineDatabase`, which puts an adapter behind the schema fence as a
- * provider's database, core's schema and settings, which its migration
- * writes, and `toolingTargetOf`, which adds a list of plugins' tables.
- */
-export {
-  compareTuples,
-  compareUtf8,
-  createMemoryAdapter,
-  DATABASE_MAX_MULTI_VALUES,
-  DATABASE_MAX_QUERY_LIMIT,
-  DATABASE_VERSION_COLUMN,
-  DatabaseAdapterContractError,
-  DatabaseSchemaError,
-  DatabaseValueError,
-  expiresAt,
-  indexOrderColumns,
-  normalizeStoredRow,
-  normalizeStoredValue,
-  verifyAdapter,
-  type DatabaseAdapter,
-  type DatabaseJson,
-  type DatabaseKey,
-  type DatabaseKeyValue,
-  type DatabaseReadCount,
-  type DatabaseReadMeter,
-  type DatabaseValue,
-  type MemoryAdapterOptions,
-  type NormalizeOptions,
-  type PhysicalColumn,
-  type PhysicalColumnType,
-  type PhysicalIndex,
-  type PhysicalRetention,
-  type PhysicalTable,
-  type QueryBound,
-  type QueryRequest,
-  type StoredRow,
-  type VerifiedDatabaseAdapter,
-  type VerifyAdapterOptions,
-  type WriteGuard,
-  type WriteOp,
-  type WriteResult,
-} from "@hot-updater/plugin-core/internal";
-
-export {
-  MAX_SHARDS,
-  resolveSchema,
-  SHARD_COLUMN,
-  validateSchema,
-  type ResolvedModel,
-  type ResolvedReference,
-  type ResolvedSchema,
-  type SchemaModule,
-} from "./resolveSchema";
-export {
-  defineAggregate,
-  defineTable,
-  type AggregateDefinition,
-  type CheckIndex,
-  type DerivedDefinition,
-  type DerivedFields,
-  type FieldDefinition,
-  type FieldReference,
-  type FieldType,
-  type FieldValue,
-  type IndexDefinition,
-  type ModelDefinition,
-  type ModuleSchema,
-  type ReferenceAction,
-  type RetentionDefinition,
-  type RowOf,
-  type TableDefinition,
-} from "./schema";
-export { DatabaseCursorError } from "./cursor";
-export { aggregateBatchingModule } from "./aggregateBatching";
-export {
-  createEngine,
-  type DatabaseEngineOptions,
-  type Engine,
-  type ReadMeasurement,
-} from "./engine";
-export {
-  createDatabaseEngine,
-  type AggregateChanges,
-  type AggregateIdentity,
-  type AggregateRow,
-  type CreateRow,
-  type DatabaseEngine,
-  type EngineColumns,
-  type FindAggregatesModel,
-  type FindManyModel,
-  type HotUpdaterDatabase,
-  type HotUpdaterTransaction,
-  type KeyLookup,
-  type Lookup,
-  type ReadOptions,
-  type ReadRow,
-  type TableRow,
-  type UpdateSet,
-} from "./database";
-export {
-  DatabaseAmbiguousCommitError,
-  DatabaseConflictError,
-  DatabaseConstraintError,
-  DatabaseTransactionError,
-  type ConstraintReason,
-} from "./errors";
-export { type RetryOptions } from "./engineTransaction";
-export {
-  DatabaseQueryError,
-  type EngineReadCount,
-  type Page,
-  type ReadRange,
-} from "./engineReads";
-export {
-  classifySqlError,
-  createSqlAdapter,
-  createTableStatements,
-  type SqlAdapterOptions,
-  type SqlConnection,
-  type SqlDialect,
-  type SqlExecutor,
-  type SqlResult,
-  type SqlStatement,
-  WRITE_GUARD_TABLE,
-} from "./sql/sqlAdapter";
-export {
-  createKvAdapter,
-  encodeKvKey,
-  type KeyValueStore,
-  type KvAdapterOptions,
-  type KvCondition,
-  type KvItem,
-  type KvKey,
-  type KvOp,
-  type KvRange,
-} from "./kv/kvAdapter";
-export { isMultiIndex } from "./sql/sqlSchema";
-export {
-  coreSchema,
-  coreSettings,
-  coreTarget,
-  createEngineDatabase,
-  migrateCoreSchema,
-  toolingTargetOf,
-  type EngineDatabaseOptions,
-  type PluginTables,
-} from "../db/coreDatabase";
-export { migrateSchema, writeSchemaSettings } from "../db/schemaSettings";
-export {
-  checkSchemaFence,
-  isMissingSchemaError,
-  ENGINE_SCHEMA_KEY,
-  ENGINE_SCHEMA_VERSION,
-  SETTINGS_TABLE,
-  withSchemaFence,
-  type SchemaSettings,
-} from "./fence";

package/src/database/kv/kvAdapter.batching.integration.spec.ts

@@ -1,15 +0,0 @@
-import { setupAggregateBatchingTestSuite } from "@hot-updater/test-utils";
-
-import * as engine from "../index";
-import { createKvAdapter } from "./kvAdapter";
-import { createMemoryKeyValueStore } from "./kvTestStore";
-
-/** The key-value helper over the in-memory store, whose writes take 100 items as DynamoDB's do. */
-setupAggregateBatchingTestSuite({
-  name: "key-value (in-memory store)",
-  engine,
-  createAdapter: async () => ({
-    adapter: createKvAdapter({ store: createMemoryKeyValueStore() }),
-  }),
-  oversizedRows: 150,
-});

package/src/database/kv/kvAdapter.conformance.integration.spec.ts

@@ -1,19 +0,0 @@
-import { setupDatabaseAdapterConformanceSuite } from "@hot-updater/test-utils";
-
-import { createKvAdapter } from "./kvAdapter";
-import { createMemoryKeyValueStore } from "./kvTestStore";
-
-setupDatabaseAdapterConformanceSuite({
-  name: "key-value (in-memory store)",
-  // The store takes 100 items per write, and a conformance insert is 3: a
-  // row and 2 index items. 33 inserts fit; 34 are 102 items.
-  maxOps: 33,
-  // Rows of a table with retention carry a TTL the store deletes them by.
-  retention: "ttl",
-  createAdapter: async ({ nativePageSize }) => ({
-    adapter: createKvAdapter({
-      store: createMemoryKeyValueStore({ nativePageSize }),
-      tablePrefix: "t_",
-    }),
-  }),
-});

package/src/database/kv/kvAdapter.readBudgets.integration.spec.ts

@@ -1,17 +0,0 @@
-import { setupReadBudgetTestSuite } from "@hot-updater/test-utils";
-
-import { readBudgetServer } from "../../readBudgets.testFixtures";
-import { createKvAdapter } from "./kvAdapter";
-import { createMemoryKeyValueStore } from "./kvTestStore";
-
-/** The key-value helper over the in-memory store, whose writes take 100 items as DynamoDB's do. */
-setupReadBudgetTestSuite({
-  name: "key-value (in-memory store)",
-  server: readBudgetServer,
-  createAdapter: async ({ nativePageSize }) => ({
-    adapter: createKvAdapter({
-      store: createMemoryKeyValueStore({ nativePageSize }),
-    }),
-    indexCopies: true,
-  }),
-});