rivetkit 2.3.5-rc.1 → 2.3.6

package/src/test/ready.ts

@@ -0,0 +1,22 @@
+import pRetry from "p-retry";
+import type { Registry } from "@/registry";
+
+export async function waitForRegistryReady(
+	registry: Registry<any>,
+): Promise<void> {
+	await pRetry(
+		async () => {
+			const response = await registry.routes.health();
+			if (!response.ok) {
+				throw new Error(
+					`RivetKit registry is not ready: ${response.status} ${await response.text()}`,
+				);
+			}
+		},
+		{
+			retries: 120,
+			minTimeout: 50,
+			maxTimeout: 250,
+		},
+	);
+}

package/src/unstable/migrations.test.ts

@@ -0,0 +1,170 @@
+import { DatabaseSync } from "node:sqlite";
+import { afterEach, describe, expect, test } from "vitest";
+import {
+	DEFAULT_MIGRATION_TABLE_NAME,
+	migrations,
+	type MigrationDatabase,
+} from "./migrations";
+
+const databases: DatabaseSync[] = [];
+
+afterEach(() => {
+	for (const database of databases.splice(0)) database.close();
+});
+
+function createDatabase(): { raw: DatabaseSync; db: MigrationDatabase } {
+	const raw = new DatabaseSync(":memory:");
+	databases.push(raw);
+	return {
+		raw,
+		db: {
+			execute: async <TRow extends Record<string, unknown>>(
+				sql: string,
+				...args: unknown[]
+			): Promise<TRow[]> => {
+				if (args.length > 0 || /^\s*SELECT\b/i.test(sql)) {
+					return raw.prepare(sql).all(...(args as never[])) as TRow[];
+				}
+				raw.exec(sql);
+				return [];
+			},
+		},
+	};
+}
+
+describe("migrations", () => {
+	test("applies SQL and function migrations once in order", async () => {
+		const { raw, db } = createDatabase();
+		const applied: number[] = [];
+		const migrate = migrations({
+			tableName: "app_schema_version",
+			migrations: [
+				{
+					version: 1,
+					sql: "CREATE TABLE items (id INTEGER PRIMARY KEY, name TEXT NOT NULL)",
+				},
+				{
+					version: 2,
+					up: async (database) => {
+						applied.push(2);
+						await database.execute(
+							"ALTER TABLE items ADD COLUMN active INTEGER NOT NULL DEFAULT 1",
+						);
+					},
+				},
+			],
+		});
+
+		await migrate(db);
+		await migrate(db);
+
+		expect(applied).toEqual([2]);
+		expect(
+			raw
+				.prepare(
+					"SELECT schema_version FROM app_schema_version WHERE singleton = 1",
+				)
+				.get(),
+		).toEqual({ schema_version: 2 });
+		expect(
+			raw
+				.prepare("PRAGMA table_info(items)")
+				.all()
+				.map((row) => row.name),
+		).toEqual(["id", "name", "active"]);
+	});
+
+	test("uses the default migration table", async () => {
+		const { raw, db } = createDatabase();
+		await migrations({
+			migrations: [{ version: 1, sql: "CREATE TABLE item (id INTEGER)" }],
+		})(db);
+
+		expect(
+			raw
+				.prepare(
+					`SELECT schema_version FROM ${DEFAULT_MIGRATION_TABLE_NAME} WHERE singleton = 1`,
+				)
+				.get(),
+		).toEqual({ schema_version: 1 });
+	});
+
+	test("adopts an unversioned schema before applying later migrations", async () => {
+		const { raw, db } = createDatabase();
+		raw.exec(
+			"CREATE TABLE items (id INTEGER PRIMARY KEY, name TEXT NOT NULL)",
+		);
+		const applied: number[] = [];
+
+		await migrations({
+			tableName: "app_schema_version",
+			adopt: async (database) => {
+				const tables = await database.execute<{ name: string }>(
+					"SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'items'",
+				);
+				return tables.length === 0 ? 0 : 1;
+			},
+			migrations: [
+				{
+					version: 1,
+					up: () => {
+						throw new Error("already applied migration ran");
+					},
+				},
+				{
+					version: 2,
+					up: async (database) => {
+						applied.push(2);
+						await database.execute(
+							"ALTER TABLE items ADD COLUMN active INTEGER NOT NULL DEFAULT 1",
+						);
+					},
+				},
+			],
+		})(db);
+
+		expect(applied).toEqual([2]);
+		expect(
+			raw
+				.prepare(
+					"SELECT schema_version FROM app_schema_version WHERE singleton = 1",
+				)
+				.get(),
+		).toEqual({ schema_version: 2 });
+	});
+
+	test("rejects invalid ladders and table names before executing", () => {
+		expect(() => migrations({ migrations: [] })).toThrow(
+			"must not be empty",
+		);
+		expect(() =>
+			migrations({
+				migrations: [{ version: 2, sql: "SELECT 1" }],
+			}),
+		).toThrow("expected version 1");
+		expect(() =>
+			migrations({
+				tableName: "schema; DROP TABLE items",
+				migrations: [{ version: 1, sql: "SELECT 1" }],
+			}),
+		).toThrow("invalid migration table name");
+	});
+
+	test("rejects a database newer than the migration ladder", async () => {
+		const { raw, db } = createDatabase();
+		raw.exec(`
+			CREATE TABLE app_schema_version (
+				singleton INTEGER PRIMARY KEY,
+				schema_version INTEGER NOT NULL
+			) STRICT;
+			INSERT INTO app_schema_version VALUES (1, 2);
+		`);
+
+		await expect(
+			migrations({
+				tableName: "app_schema_version",
+				migrations: [{ version: 1, sql: "SELECT 1" }],
+			})(db),
+		).rejects.toThrow("newer than supported version 1");
+	});
+});

package/src/unstable/migrations.ts

@@ -0,0 +1,141 @@
+import type { RawAccess } from "@/common/database/config";
+
+export const DEFAULT_MIGRATION_TABLE_NAME = "rivetkit_schema_version";
+
+export type MigrationDatabase = Pick<RawAccess, "execute">;
+
+export type Migration =
+	| {
+			version: number;
+			sql: string;
+			up?: never;
+	  }
+	| {
+			version: number;
+			sql?: never;
+			up: (db: MigrationDatabase) => Promise<void> | void;
+	  };
+
+export interface MigrationsOptions {
+	/** A table owned by this schema. Override this when multiple schemas share a database. */
+	tableName?: string;
+	/** Detect the version of a schema that predates its migration table. */
+	adopt?: (db: MigrationDatabase) => Promise<number> | number;
+	/** Contiguous migrations numbered from 1. */
+	migrations: readonly Migration[];
+}
+
+/**
+ * Creates an `onMigrate` callback that applies each unapplied migration in order.
+ * RivetKit runs the callback inside its migration savepoint, making the complete
+ * ladder atomic when used with `db({ onMigrate })`.
+ */
+export function migrations({
+	tableName = DEFAULT_MIGRATION_TABLE_NAME,
+	adopt,
+	migrations: ladder,
+}: MigrationsOptions): (db: MigrationDatabase) => Promise<void> {
+	validateTableName(tableName);
+	validateLadder(ladder);
+
+	return async (database) => {
+		const quotedTableName = `"${tableName}"`;
+		await database.execute(`
+			CREATE TABLE IF NOT EXISTS ${quotedTableName} (
+				singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+				schema_version INTEGER NOT NULL CHECK (
+					schema_version BETWEEN 0 AND ${Number.MAX_SAFE_INTEGER}
+				)
+			) STRICT
+		`);
+
+		const rows = await database.execute<{ schema_version: unknown }>(
+			`SELECT schema_version FROM ${quotedTableName} WHERE singleton = 1`,
+		);
+		if (rows.length > 1) {
+			throw new Error(
+				`invalid migration table "${tableName}": expected at most one version row, received ${rows.length}`,
+			);
+		}
+
+		const rawCurrent = rows[0]?.schema_version;
+		let current = rows.length === 0 ? 0 : rawCurrent;
+		if (rows.length === 0 && adopt) {
+			current = await adopt(database);
+		}
+		if (
+			typeof current !== "number" ||
+			!Number.isSafeInteger(current) ||
+			current < 0
+		) {
+			throw new Error(
+				`invalid schema version ${String(current)} in migration table "${tableName}"`,
+			);
+		}
+		if (current > ladder.length) {
+			throw new Error(
+				`migration version ${current} in "${tableName}" is newer than supported version ${ladder.length}`,
+			);
+		}
+		if (rows.length === 0 && current > 0) {
+			await writeVersion(database, quotedTableName, current);
+		}
+
+		for (const migration of ladder.slice(current)) {
+			if (migration.sql !== undefined) {
+				await database.execute(migration.sql);
+			} else {
+				await migration.up(database);
+			}
+			await writeVersion(database, quotedTableName, migration.version);
+		}
+	};
+}
+
+async function writeVersion(
+	database: MigrationDatabase,
+	quotedTableName: string,
+	version: number,
+): Promise<void> {
+	await database.execute(
+		`INSERT INTO ${quotedTableName} (singleton, schema_version)
+		 VALUES (1, ?)
+		 ON CONFLICT(singleton) DO UPDATE SET schema_version = excluded.schema_version`,
+		version,
+	);
+}
+
+function validateTableName(tableName: string): void {
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(tableName)) {
+		throw new Error(
+			`invalid migration table name "${tableName}": expected a SQLite identifier`,
+		);
+	}
+}
+
+function validateLadder(ladder: readonly Migration[]): void {
+	if (ladder.length === 0) {
+		throw new Error("migration ladder must not be empty");
+	}
+
+	for (const [index, migration] of ladder.entries()) {
+		const expectedVersion = index + 1;
+		if (migration.version !== expectedVersion) {
+			throw new Error(
+				`invalid migration ladder: expected version ${expectedVersion}, received ${migration.version}`,
+			);
+		}
+		const hasSql = typeof migration.sql === "string";
+		const hasUp = typeof migration.up === "function";
+		if (hasSql === hasUp) {
+			throw new Error(
+				`invalid migration ${migration.version}: expected exactly one of sql or up`,
+			);
+		}
+		if (hasSql && migration.sql.trim().length === 0) {
+			throw new Error(
+				`invalid migration ${migration.version}: SQL is empty`,
+			);
+		}
+	}
+}