emdash 0.33.0 → 0.35.0

package/src/migrations/direct-executor.ts

@@ -0,0 +1,141 @@
+import { type Dialect, Kysely } from "kysely";
+
+import {
+	getExactMigrationStatus,
+	runMigrations,
+	type ExactMigrationStatus,
+} from "../database/migrations/runner.js";
+import type { Database } from "../database/types.js";
+import { getI18nConfig, setI18nConfig } from "../i18n/config.js";
+import { getCoreMigrationIdentity } from "./identity.js";
+import type {
+	MigrationExecutor,
+	MigrationReport,
+	MigrationRequest,
+	MigrationTarget,
+} from "./protocol.js";
+
+export interface DirectMigrationExecutorOptions {
+	target: MigrationTarget;
+	createDialect: () => Dialect | Promise<Dialect>;
+}
+
+function createReport(
+	target: MigrationTarget,
+	status: ExactMigrationStatus,
+	executed: readonly string[],
+): MigrationReport {
+	return {
+		target,
+		knownApplied: [...status.knownApplied],
+		pending: [...status.pending],
+		unknownApplied: [...status.unknownApplied],
+		executed: [...executed],
+	};
+}
+
+async function verifyRequest(request: MigrationRequest): Promise<void> {
+	const identity = await getCoreMigrationIdentity();
+	if (
+		request.artifact.emdashVersion !== identity.emdashVersion ||
+		request.artifact.migrationSetFingerprint !== identity.fingerprint
+	) {
+		throw new Error(
+			"Migration artifact does not match the loaded EmDash version and migration registry.",
+		);
+	}
+}
+
+async function executeRequest(
+	db: Kysely<Database>,
+	target: MigrationTarget,
+	request: MigrationRequest,
+): Promise<MigrationReport> {
+	const initialStatus = await getExactMigrationStatus(db);
+	if (request.action === "check") {
+		return createReport(target, initialStatus, []);
+	}
+
+	if (initialStatus.unknownApplied.length > 0) {
+		throw new Error(
+			`Cannot apply migrations with unknown applied migrations: ${initialStatus.unknownApplied.join(", ")}`,
+		);
+	}
+	if (initialStatus.pending.length === 0) {
+		return createReport(target, initialStatus, []);
+	}
+
+	const result = await runMigrations(db);
+	const finalStatus = await getExactMigrationStatus(db);
+	return createReport(target, finalStatus, result.applied);
+}
+
+export function createDirectMigrationExecutor(
+	options: DirectMigrationExecutorOptions,
+): MigrationExecutor {
+	const target = Object.freeze({ ...options.target });
+	let used = false;
+	let disposed = false;
+	let activeDb: Kysely<Database> | undefined;
+	let closePromise: Promise<void> | undefined;
+
+	const closeActiveDb = (): Promise<void> => {
+		if (!activeDb) return Promise.resolve();
+		closePromise ??= activeDb.destroy();
+		return closePromise;
+	};
+
+	return {
+		target,
+		async execute(request) {
+			if (disposed) {
+				throw new Error("Migration executor has been disposed.");
+			}
+			if (used) {
+				throw new Error("Migration executors are single-use.");
+			}
+			used = true;
+
+			if (request.action !== "check" && request.action !== "apply") {
+				throw new Error("Unsupported migration action.");
+			}
+			await verifyRequest(request);
+
+			const dialect = await options.createDialect();
+			const db = new Kysely<Database>({ dialect });
+			activeDb = db;
+			if (disposed) {
+				await closeActiveDb();
+				throw new Error("Migration executor has been disposed.");
+			}
+			const previousI18n = getI18nConfig();
+			let executionFailed = false;
+			let executionError: unknown;
+			let report: MigrationReport | undefined;
+			setI18nConfig(request.i18n);
+
+			try {
+				report = await executeRequest(db, target, request);
+			} catch (error) {
+				executionFailed = true;
+				executionError = error;
+			} finally {
+				setI18nConfig(previousI18n);
+				try {
+					await closeActiveDb();
+				} catch {
+					console.error("[migrations] Database close failed.");
+					closePromise = Promise.resolve();
+				}
+			}
+
+			if (executionFailed) throw executionError;
+			if (!report) throw new Error("Migration execution did not produce a report.");
+			return report;
+		},
+		dispose() {
+			disposed = true;
+			return closeActiveDb();
+		},
+	};
+}

package/src/migrations/identity.ts

@@ -0,0 +1,46 @@
+import { MIGRATION_NAMES } from "../database/migrations/runner.js";
+import { VERSION } from "../version.js";
+
+export interface CoreMigrationIdentity {
+	emdashVersion: string;
+	names: readonly string[];
+	fingerprint: string;
+}
+
+function encodeFingerprintInput(emdashVersion: string, names: readonly string[]): ArrayBuffer {
+	const encoded = new TextEncoder().encode(JSON.stringify({ emdashVersion, names }));
+	const buffer = new ArrayBuffer(encoded.byteLength);
+	new Uint8Array(buffer).set(encoded);
+	return buffer;
+}
+
+function encodeHex(bytes: Uint8Array): string {
+	return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+export async function fingerprintMigrationSet(
+	emdashVersion: string,
+	names: readonly string[],
+): Promise<string> {
+	const digest = await crypto.subtle.digest(
+		"SHA-256",
+		encodeFingerprintInput(emdashVersion, names),
+	);
+	return encodeHex(new Uint8Array(digest));
+}
+
+export async function createCoreMigrationIdentity(
+	emdashVersion: string,
+	names: readonly string[],
+): Promise<CoreMigrationIdentity> {
+	const nameSnapshot = Object.freeze([...names]);
+	return Object.freeze({
+		emdashVersion,
+		names: nameSnapshot,
+		fingerprint: await fingerprintMigrationSet(emdashVersion, nameSnapshot),
+	});
+}
+
+export function getCoreMigrationIdentity(): Promise<CoreMigrationIdentity> {
+	return createCoreMigrationIdentity(VERSION, MIGRATION_NAMES);
+}

package/src/migrations/index.ts

@@ -0,0 +1,19 @@
+export { createDirectMigrationExecutor } from "./direct-executor.js";
+export type { DirectMigrationExecutorOptions } from "./direct-executor.js";
+export {
+	createCoreMigrationIdentity,
+	fingerprintMigrationSet,
+	getCoreMigrationIdentity,
+} from "./identity.js";
+export type { CoreMigrationIdentity } from "./identity.js";
+export type {
+	MigrationAction,
+	MigrationExecutor,
+	MigrationExecutorFactory,
+	MigrationExecutorFactoryContext,
+	MigrationExecutorModule,
+	MigrationReport,
+	MigrationRequest,
+	MigrationTarget,
+	MigrationTargetOverrides,
+} from "./protocol.js";

package/src/migrations/integration-metadata.ts

@@ -0,0 +1,67 @@
+import type { DatabaseDescriptor } from "../db/adapters.js";
+import { validateSecretFreeExecutorConfig } from "./manifest.js";
+
+export const MIGRATION_CONFIG_SYMBOL = Symbol.for("emdash:migration-config");
+
+export interface MigrationIntegrationMetadata {
+	database?: Pick<DatabaseDescriptor, "type" | "migrations">;
+}
+
+function isRecord(value: unknown): value is Record<PropertyKey, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function isMigrationIntegrationMetadata(value: unknown): value is MigrationIntegrationMetadata {
+	if (!isRecord(value)) return false;
+	const database = value.database;
+	if (database === undefined) return true;
+	if (!isRecord(database) || (database.type !== "sqlite" && database.type !== "postgres")) {
+		return false;
+	}
+
+	const migrations = database.migrations;
+	return (
+		migrations === undefined ||
+		(isRecord(migrations) &&
+			typeof migrations.entrypoint === "string" &&
+			Object.hasOwn(migrations, "manifestConfig"))
+	);
+}
+
+export function createMigrationIntegrationMetadata(
+	database?: DatabaseDescriptor,
+): MigrationIntegrationMetadata {
+	if (!database) return {};
+
+	return {
+		database: {
+			type: database.type,
+			migrations: database.migrations
+				? {
+						entrypoint: database.migrations.entrypoint,
+						manifestConfig: validateSecretFreeExecutorConfig(
+							database.migrations.manifestConfig,
+							"database.migrations.manifestConfig",
+						),
+					}
+				: undefined,
+		},
+	};
+}
+
+export function getMigrationIntegrationMetadata(
+	integration: unknown,
+): MigrationIntegrationMetadata | undefined {
+	if (
+		(typeof integration !== "object" || integration === null) &&
+		typeof integration !== "function"
+	) {
+		return undefined;
+	}
+	if (!Object.hasOwn(integration, MIGRATION_CONFIG_SYMBOL)) {
+		return undefined;
+	}
+
+	const metadata: unknown = Reflect.get(integration, MIGRATION_CONFIG_SYMBOL);
+	return isMigrationIntegrationMetadata(metadata) ? metadata : undefined;
+}

package/src/migrations/manifest-builder.ts

@@ -0,0 +1,55 @@
+import type { DatabaseDescriptor } from "../db/adapters.js";
+import type { I18nConfig } from "../i18n/config.js";
+import type { CoreMigrationIdentity } from "./identity.js";
+import { fingerprintMigrationSet } from "./identity.js";
+import type { MigrationManifestV1 } from "./manifest.js";
+import { MigrationManifestValidationError, validateMigrationManifest } from "./manifest.js";
+
+export type ManifestDatabaseDescriptor = Pick<DatabaseDescriptor, "type" | "migrations">;
+
+export interface BuildMigrationManifestOptions {
+	identity: CoreMigrationIdentity;
+	i18n: I18nConfig | null;
+	database: ManifestDatabaseDescriptor;
+}
+
+export class UnsupportedMigrationAdapterError extends Error {
+	constructor() {
+		super("The configured database adapter does not provide a deployment migration executor");
+		this.name = "UnsupportedMigrationAdapterError";
+	}
+}
+
+export async function buildMigrationManifest({
+	identity,
+	i18n,
+	database,
+}: BuildMigrationManifestOptions): Promise<MigrationManifestV1> {
+	const identityFingerprint = await fingerprintMigrationSet(identity.emdashVersion, identity.names);
+	if (identityFingerprint !== identity.fingerprint) {
+		throw new MigrationManifestValidationError(
+			"loaded identity fingerprint does not match its version and ordered names",
+		);
+	}
+	if (!database.migrations) {
+		throw new UnsupportedMigrationAdapterError();
+	}
+
+	return validateMigrationManifest(
+		{
+			schemaVersion: 1,
+			emdashVersion: identity.emdashVersion,
+			migrationSet: {
+				names: [...identity.names],
+				fingerprint: identity.fingerprint,
+			},
+			i18n,
+			database: {
+				type: database.type,
+				executorEntrypoint: database.migrations.entrypoint,
+				executorConfig: database.migrations.manifestConfig,
+			},
+		},
+		identity,
+	);
+}

package/src/migrations/manifest-writer.ts

@@ -0,0 +1,63 @@
+import { randomUUID } from "node:crypto";
+import {
+	mkdir as nodeMkdir,
+	rename as nodeRename,
+	unlink as nodeUnlink,
+	writeFile as nodeWriteFile,
+} from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import type { MigrationManifestV1 } from "./manifest.js";
+import { serializeMigrationManifest, validateMigrationManifest } from "./manifest.js";
+
+export const MIGRATION_MANIFEST_PATH = ".emdash/migrations.json";
+
+export interface ManifestWriterFileSystem {
+	mkdir(path: string, options: { recursive: true }): Promise<unknown>;
+	writeFile(
+		path: string,
+		data: string,
+		options: { encoding: "utf8"; flag: "wx" },
+	): Promise<unknown>;
+	rename(from: string, to: string): Promise<unknown>;
+	unlink(path: string): Promise<unknown>;
+}
+
+const nodeFileSystem: ManifestWriterFileSystem = {
+	mkdir: (path, options) => nodeMkdir(path, options),
+	writeFile: (path, data, options) => nodeWriteFile(path, data, options),
+	rename: (from, to) => nodeRename(from, to),
+	unlink: (path) => nodeUnlink(path),
+};
+
+export async function writeMigrationManifest(
+	projectRoot: string,
+	manifest: MigrationManifestV1,
+	fileSystem: ManifestWriterFileSystem = nodeFileSystem,
+): Promise<string> {
+	const validated = await validateMigrationManifest(manifest);
+	const outputPath = join(projectRoot, MIGRATION_MANIFEST_PATH);
+	const outputDirectory = dirname(outputPath);
+	await fileSystem.mkdir(outputDirectory, { recursive: true });
+
+	const temporaryPath = join(
+		outputDirectory,
+		`.migrations.json.${process.pid}.${randomUUID()}.tmp`,
+	);
+	let temporaryFileMayExist = false;
+	try {
+		temporaryFileMayExist = true;
+		await fileSystem.writeFile(temporaryPath, serializeMigrationManifest(validated), {
+			encoding: "utf8",
+			flag: "wx",
+		});
+		await fileSystem.rename(temporaryPath, outputPath);
+		temporaryFileMayExist = false;
+		return outputPath;
+	} catch (error) {
+		if (temporaryFileMayExist) {
+			await fileSystem.unlink(temporaryPath).catch(() => undefined);
+		}
+		throw error;
+	}
+}

package/src/migrations/manifest.ts

@@ -0,0 +1,197 @@
+import { z } from "zod";
+
+import type { CoreMigrationIdentity } from "./identity.js";
+import { fingerprintMigrationSet } from "./identity.js";
+
+const FINGERPRINT_PATTERN = /^[0-9a-f]{64}$/;
+const MIGRATION_NAME_PATTERN = /^\d{3}_[a-z0-9_]+$/;
+const EXECUTOR_ENTRYPOINT_PATTERN =
+	/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*(?:\/[A-Za-z0-9][A-Za-z0-9._-]*)*$/;
+const ENVIRONMENT_VARIABLE_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ENVIRONMENT_REFERENCE_KEY_PATTERN = /(?:env|envName|envVar)$/i;
+const URL_SCHEME_PATTERN = /^[A-Za-z][A-Za-z0-9+.-]*:/;
+const SECRET_QUERY_KEY_PATTERN = /(?:auth|credential|key|password|secret|signature|token)/i;
+const SECRET_CONFIG_KEY_PATTERN =
+	/(?:accessToken|apiKey|authToken|certificate|connectionString|password|privateKey|secret)/i;
+const SECRET_CONFIG_EXACT_KEY_PATTERN = /^(?:ca|cert|key)$/i;
+const CONNECTION_URL_PROTOCOLS = new Set(["mysql:", "postgres:", "postgresql:"]);
+
+type JsonPrimitive = boolean | number | string | null;
+type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+
+const i18nConfigSchema = z
+	.object({
+		defaultLocale: z.string().min(1),
+		locales: z.array(z.string().min(1)).min(1),
+		fallback: z.record(z.string(), z.string()).optional(),
+		prefixDefaultLocale: z.boolean().optional(),
+	})
+	.strict();
+
+export const migrationManifestV1Schema = z
+	.object({
+		schemaVersion: z.literal(1),
+		emdashVersion: z.string().min(1),
+		migrationSet: z
+			.object({
+				names: z
+					.array(z.string().regex(MIGRATION_NAME_PATTERN))
+					.min(1)
+					.refine((names) => new Set(names).size === names.length),
+				fingerprint: z.string().regex(FINGERPRINT_PATTERN),
+			})
+			.strict(),
+		i18n: i18nConfigSchema.nullable(),
+		database: z
+			.object({
+				type: z.enum(["sqlite", "postgres"]),
+				executorEntrypoint: z.string().regex(EXECUTOR_ENTRYPOINT_PATTERN),
+				executorConfig: z.unknown(),
+			})
+			.strict(),
+	})
+	.strict();
+
+export type MigrationManifestV1 = z.infer<typeof migrationManifestV1Schema>;
+
+export class MigrationManifestValidationError extends Error {
+	constructor(message: string) {
+		super(`Invalid migration manifest: ${message}`);
+		this.name = "MigrationManifestValidationError";
+	}
+}
+
+function isEnvironmentReferenceKey(key: string): boolean {
+	return ENVIRONMENT_REFERENCE_KEY_PATTERN.test(key);
+}
+
+function assertSafeUrl(value: string, path: string): void {
+	if (!URL_SCHEME_PATTERN.test(value)) return;
+
+	let url: URL;
+	try {
+		url = new URL(value);
+	} catch {
+		throw new MigrationManifestValidationError(`${path} contains an invalid URL`);
+	}
+
+	if (CONNECTION_URL_PROTOCOLS.has(url.protocol)) {
+		throw new MigrationManifestValidationError(`${path} contains a database connection URL`);
+	}
+	if (url.username || url.password) {
+		throw new MigrationManifestValidationError(`${path} contains URL credentials`);
+	}
+	for (const key of url.searchParams.keys()) {
+		if (SECRET_QUERY_KEY_PATTERN.test(key)) {
+			throw new MigrationManifestValidationError(`${path} contains a credential query parameter`);
+		}
+	}
+}
+
+function cloneSecretFreeJson(value: unknown, path: string, ancestors: Set<object>): JsonValue {
+	if (value === null || typeof value === "boolean") return value;
+	if (typeof value === "string") {
+		assertSafeUrl(value, path);
+		return value;
+	}
+	if (typeof value === "number") {
+		if (Number.isFinite(value)) return value;
+		throw new MigrationManifestValidationError(`${path} contains a non-finite number`);
+	}
+	if (typeof value !== "object") {
+		throw new MigrationManifestValidationError(`${path} is not JSON-serializable`);
+	}
+	if (ancestors.has(value)) {
+		throw new MigrationManifestValidationError(`${path} contains a cycle`);
+	}
+
+	ancestors.add(value);
+	try {
+		if (Array.isArray(value)) {
+			return value.map((item, index) => cloneSecretFreeJson(item, `${path}[${index}]`, ancestors));
+		}
+
+		const prototype = Object.getPrototypeOf(value);
+		if (prototype !== Object.prototype && prototype !== null) {
+			throw new MigrationManifestValidationError(`${path} contains a non-plain object`);
+		}
+
+		const cloned: Record<string, JsonValue> = {};
+		for (const [key, item] of Object.entries(value)) {
+			const itemPath = `${path}.${key}`;
+			const environmentReference = isEnvironmentReferenceKey(key);
+			if (
+				!environmentReference &&
+				(SECRET_CONFIG_KEY_PATTERN.test(key) || SECRET_CONFIG_EXACT_KEY_PATTERN.test(key))
+			) {
+				throw new MigrationManifestValidationError(`${itemPath} is a credential-bearing field`);
+			}
+			if (environmentReference) {
+				if (typeof item !== "string" || !ENVIRONMENT_VARIABLE_PATTERN.test(item)) {
+					throw new MigrationManifestValidationError(
+						`${itemPath} must contain an environment-variable name`,
+					);
+				}
+			}
+			cloned[key] = cloneSecretFreeJson(item, itemPath, ancestors);
+		}
+		return cloned;
+	} finally {
+		ancestors.delete(value);
+	}
+}
+
+export function validateSecretFreeExecutorConfig(
+	value: unknown,
+	path = "database.executorConfig",
+): unknown {
+	return cloneSecretFreeJson(value, path, new Set());
+}
+
+function identitiesMatch(
+	manifest: MigrationManifestV1,
+	expectedIdentity: CoreMigrationIdentity,
+): boolean {
+	return (
+		manifest.emdashVersion === expectedIdentity.emdashVersion &&
+		manifest.migrationSet.fingerprint === expectedIdentity.fingerprint &&
+		manifest.migrationSet.names.length === expectedIdentity.names.length &&
+		manifest.migrationSet.names.every((name, index) => name === expectedIdentity.names[index])
+	);
+}
+
+export async function validateMigrationManifest(
+	value: unknown,
+	expectedIdentity?: CoreMigrationIdentity,
+): Promise<MigrationManifestV1> {
+	const parsed = migrationManifestV1Schema.safeParse(value);
+	if (!parsed.success) {
+		throw new MigrationManifestValidationError("schema validation failed");
+	}
+
+	const executorConfig = validateSecretFreeExecutorConfig(parsed.data.database.executorConfig);
+	const manifest: MigrationManifestV1 = {
+		...parsed.data,
+		database: { ...parsed.data.database, executorConfig },
+	};
+	const fingerprint = await fingerprintMigrationSet(
+		manifest.emdashVersion,
+		manifest.migrationSet.names,
+	);
+	if (fingerprint !== manifest.migrationSet.fingerprint) {
+		throw new MigrationManifestValidationError(
+			"migrationSet fingerprint does not match its version and ordered names",
+		);
+	}
+	if (expectedIdentity && !identitiesMatch(manifest, expectedIdentity)) {
+		throw new MigrationManifestValidationError(
+			"manifest does not match the loaded EmDash migration identity",
+		);
+	}
+
+	return manifest;
+}
+
+export function serializeMigrationManifest(manifest: MigrationManifestV1): string {
+	return `${JSON.stringify(manifest, null, "\t")}\n`;
+}

package/src/migrations/protocol.ts

@@ -0,0 +1,59 @@
+import type { I18nConfig } from "../i18n/config.js";
+
+export type MigrationAction = "check" | "apply";
+
+export interface MigrationRequest {
+	action: MigrationAction;
+	i18n: I18nConfig | null;
+	artifact: {
+		emdashVersion: string;
+		migrationSetFingerprint: string;
+	};
+}
+
+export interface MigrationTarget {
+	kind: string;
+	label: string;
+	fingerprint: string;
+	accountId?: string;
+	environment?: string;
+	resourceId?: string;
+}
+
+export interface MigrationReport {
+	target: MigrationTarget;
+	knownApplied: string[];
+	pending: string[];
+	unknownApplied: string[];
+	executed: string[];
+}
+
+export interface MigrationExecutor {
+	target: MigrationTarget;
+	execute(request: MigrationRequest): Promise<MigrationReport>;
+	dispose?(): Promise<void>;
+}
+
+export interface MigrationTargetOverrides {
+	database?: string;
+	databaseUrlEnv?: string;
+	d1?: string;
+	accountId?: string;
+	wranglerConfig?: string;
+	wranglerEnv?: string;
+}
+
+export interface MigrationExecutorFactoryContext {
+	projectRoot: string;
+	env: Readonly<Record<string, string | undefined>>;
+	overrides?: Readonly<MigrationTargetOverrides>;
+}
+
+export type MigrationExecutorFactory<ManifestConfig = unknown> = (
+	manifestConfig: ManifestConfig,
+	context: MigrationExecutorFactoryContext,
+) => MigrationExecutor | Promise<MigrationExecutor>;
+
+export interface MigrationExecutorModule<ManifestConfig = unknown> {
+	createMigrationExecutor: MigrationExecutorFactory<ManifestConfig>;
+}

package/src/migrations/target.ts

@@ -0,0 +1,35 @@
+import type { MigrationTarget } from "./protocol.js";
+
+const ENVIRONMENT_VARIABLE_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function encodeHex(bytes: Uint8Array): string {
+	return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+export async function createMigrationTarget(
+	kind: string,
+	label: string,
+	identity: readonly string[],
+): Promise<MigrationTarget> {
+	const encoded = new TextEncoder().encode(JSON.stringify({ kind, identity }));
+	const digest = await crypto.subtle.digest("SHA-256", encoded);
+	return {
+		kind,
+		label,
+		fingerprint: encodeHex(new Uint8Array(digest)),
+	};
+}
+
+export function requireMigrationEnvironment(
+	name: unknown,
+	env: Readonly<Record<string, string | undefined>>,
+): string {
+	if (typeof name !== "string" || !ENVIRONMENT_VARIABLE_PATTERN.test(name)) {
+		throw new Error("Migration credential environment variable name is invalid.");
+	}
+	const value = env[name];
+	if (!value) {
+		throw new Error(`Migration credential environment variable ${name} is not set.`);
+	}
+	return value;
+}