@decohere/data-typeorm 0.0.1-dev.125 → 0.0.1-dev.5

package/src/server-manager.ts

@@ -0,0 +1,300 @@
+import { type ConnectionInfo, DataConfigurationError } from "@decohere/data";
+import { Pool } from "pg";
+import {
+	alterDatabaseOwnerQuery,
+	createSchemaQuery,
+	createUserQuery,
+	databaseOwnerQuery,
+	defaultPrivilegesForAppQueries,
+	grantConnectQuery,
+	grantRoleMembershipQuery,
+	grantSchemaCreateQuery,
+	grantSchemaPrivilegesQuery,
+	grantSchemaUsageQuery,
+	hasDatabasePrivilegeQuery,
+	hasRolePrivilegesQuery,
+	hasSchemaPrivilegeQuery,
+	quoteIdent,
+	revokeRoleMembershipQuery,
+	roleExistsQuery,
+	type SqlQuery,
+} from "./scripts/user.js";
+
+export type ProvisionRolesOptions = {
+	database: string;
+	appUsername: string;
+	/** Omit only when the server is declared `auth: trust`. */
+	appPassword?: string;
+	migrateUsername?: string;
+	migratePassword?: string;
+	/** When true (TypeORM synchronize), grant CREATE on the schema to the app role (dev only). */
+	allowAppDdl: boolean;
+	/** The schema the app role works in, created when missing. Default `public`. */
+	schema?: string;
+};
+
+/**
+ * Official Postgres images always have this DB. `pg` defaults an omitted
+ * `database` to the username — bootstrap roles like `decohere_bootstrap` are
+ * not databases, so connect here before CREATE DATABASE.
+ */
+const MAINTENANCE_DATABASE = "postgres";
+
+export class PostgresServerManager {
+	private pool: Pool;
+	private client: import("pg").PoolClient;
+
+	public constructor(
+		private readonly applicationName: string,
+		private readonly config: ConnectionInfo,
+	) {}
+
+	/** `auth: trust`: the server lets every connection in, so roles have no password. */
+	private get trusted(): boolean {
+		return this.config.auth === "trust";
+	}
+
+	public async connect() {
+		const { adminUser, adminPassword, host, port } = this.config;
+		if (!adminUser || (!adminPassword && !this.trusted)) {
+			throw new DataConfigurationError(
+				`Data source "${this.config.name}": adminUser and adminPassword are required to bootstrap the database (adminPassword may be left out only with auth: trust)`,
+			);
+		}
+		this.pool = new Pool({
+			user: adminUser,
+			host,
+			password: adminPassword,
+			port,
+			database: MAINTENANCE_DATABASE,
+			application_name: this.applicationName,
+		});
+		try {
+			this.client = await this.pool.connect();
+		} catch (err) {
+			const cause = err instanceof Error ? err.message : String(err);
+			throw new DataConfigurationError(
+				`Cannot connect to PostgreSQL at ${host}:${port}. Is the server running? Cause: ${cause}`,
+			);
+		}
+	}
+
+	public async initializeDatabase(database: string) {
+		quoteIdent(database, "database");
+		const result = await this.pool.query(
+			`SELECT datname FROM pg_catalog.pg_database WHERE lower(datname) = lower($1)`,
+			[database],
+		);
+		if (result.rowCount === 1) {
+			return;
+		}
+
+		const dbIdent = quoteIdent(database, "database");
+		await this.pool.query(`CREATE DATABASE ${dbIdent}`);
+	}
+
+	/**
+	 * Create the runtime app role (+ optional migrate role) and its schema, with least-privilege
+	 * grants. Running it again changes nothing: each grant is made only where the role lacks it,
+	 * since Postgres checks the grantor's rights even for a grant that would change nothing.
+	 *
+	 * The admin acts with the database owner's rights while it runs (it is made a member of the
+	 * owner, and of the migrate role, only for as long as it needs to be). That is how it creates a
+	 * schema and grants on it once the migrate role owns the database.
+	 */
+	public async provisionRoles(options: ProvisionRolesOptions): Promise<void> {
+		const {
+			database,
+			appUsername,
+			appPassword,
+			migrateUsername,
+			migratePassword,
+			allowAppDdl,
+			schema = "public",
+		} = options;
+		quoteIdent(schema, "schema");
+
+		if (appUsername === this.config.adminUser) {
+			throw new DataConfigurationError(
+				`Runtime username "${appUsername}" must not equal adminUser — use a dedicated app role`,
+			);
+		}
+		if (migrateUsername && migrateUsername === appUsername) {
+			throw new DataConfigurationError(
+				"migrateUsername must differ from the runtime app username",
+			);
+		}
+		if (migrateUsername && migrateUsername === this.config.adminUser) {
+			throw new DataConfigurationError("migrateUsername must not equal adminUser");
+		}
+
+		const adminUser = this.config.adminUser;
+		if (!adminUser) {
+			throw new DataConfigurationError("adminUser is required to provision database roles");
+		}
+
+		const pool = new Pool({
+			host: this.config.host,
+			port: this.config.port,
+			user: adminUser,
+			database,
+			password: this.config.adminPassword,
+			application_name: this.applicationName,
+		});
+
+		try {
+			await using roles = new BorrowedRoles(pool, adminUser);
+
+			if (migrateUsername) {
+				await this.ensureRole(pool, migrateUsername, migratePassword);
+				// Membership is required for OWNER TO and DEFAULT PRIVILEGES FOR ROLE (not superuser).
+				await roles.borrow(migrateUsername);
+				// The owner holds every privilege on the database, so no separate GRANT is needed.
+				if ((await databaseOwner(pool, database)) !== migrateUsername) {
+					await pool.query(alterDatabaseOwnerQuery(database, migrateUsername).text);
+				}
+			}
+
+			const owner = await databaseOwner(pool, database);
+			if (owner !== adminUser) await roles.borrow(owner);
+
+			// Owned by the database owner (the migrate role, when there is one), like `public`.
+			await pool.query(createSchemaQuery(schema, owner).text);
+
+			if (
+				migrateUsername &&
+				!(await hasAll(pool, (privilege) =>
+					hasSchemaPrivilegeQuery(migrateUsername, schema, privilege),
+				))
+			) {
+				await pool.query(grantSchemaPrivilegesQuery(migrateUsername, schema).text);
+			}
+
+			await this.ensureRole(pool, appUsername, appPassword);
+			if (
+				!(await granted(pool, hasDatabasePrivilegeQuery(appUsername, database, "CONNECT")))
+			) {
+				await pool.query(grantConnectQuery(appUsername, database).text);
+			}
+			if (!(await granted(pool, hasSchemaPrivilegeQuery(appUsername, schema, "USAGE")))) {
+				await pool.query(grantSchemaUsageQuery(appUsername, schema).text);
+			}
+			// Dev synchronize: the app connection must be able to CREATE tables.
+			if (
+				allowAppDdl &&
+				!(await granted(pool, hasSchemaPrivilegeQuery(appUsername, schema, "CREATE")))
+			) {
+				await pool.query(grantSchemaCreateQuery(appUsername, schema).text);
+			}
+
+			if (migrateUsername) {
+				// Setting a default privilege that is already set changes nothing.
+				for (const q of defaultPrivilegesForAppQueries(migrateUsername, appUsername, schema)) {
+					await pool.query(q.text);
+				}
+			}
+		} finally {
+			await pool.end();
+		}
+	}
+
+	/** @deprecated Use provisionRoles. */
+	public async createApiUser(
+		username: string,
+		password: string,
+		database: string,
+		_role?: string,
+	) {
+		await this.provisionRoles({
+			database,
+			appUsername: username,
+			appPassword: password,
+			migrateUsername: this.config.migrateUsername,
+			migratePassword: this.config.migratePassword,
+			allowAppDdl: this.config.synchronize === true,
+			schema: this.config.schema,
+		});
+	}
+
+	private async ensureRole(pool: Pool, username: string, password?: string): Promise<void> {
+		if (!password && !this.trusted) {
+			throw new DataConfigurationError(
+				`A password is required for database role "${username}" unless the data source sets auth: trust`,
+			);
+		}
+		const exists = roleExistsQuery(username);
+		const found = await pool.query(exists.text, exists.values);
+		if (found.rowCount === 1) {
+			return;
+		}
+		const create = createUserQuery(username, password);
+		await pool.query(create.text, create.values);
+	}
+
+	public [Symbol.asyncDispose]() {
+		return this.closeConnection();
+	}
+
+	public async closeConnection() {
+		this.client?.release();
+		await this.pool?.end();
+	}
+}
+
+async function granted(pool: Pool, query: SqlQuery): Promise<boolean> {
+	const result = await pool.query(query.text, query.values);
+	return result.rows[0]?.granted === true;
+}
+
+/** Every schema privilege that `GRANT ALL ON SCHEMA` gives. Checked one at a time: Postgres
+ * answers true for a list when any one of them is held. */
+async function hasAll(pool: Pool, query: (privilege: string) => SqlQuery): Promise<boolean> {
+	for (const privilege of ["USAGE", "CREATE"]) {
+		if (!(await granted(pool, query(privilege)))) return false;
+	}
+	return true;
+}
+
+async function databaseOwner(pool: Pool, database: string): Promise<string> {
+	const query = databaseOwnerQuery(database);
+	const result = await pool.query(query.text, query.values);
+	const owner: string | undefined = result.rows[0]?.owner;
+	if (owner == null) {
+		throw new DataConfigurationError(`Database "${database}" does not exist`);
+	}
+	return owner;
+}
+
+/**
+ * Roles the admin is made a member of for one provisioning run, so it acts with their rights.
+ * Disposing gives back exactly what was borrowed, even when the run fails: memberships the admin
+ * already had (or rights it has as a superuser) are left alone.
+ */
+class BorrowedRoles {
+	private readonly borrowed: string[] = [];
+
+	public constructor(
+		private readonly pool: Pool,
+		private readonly adminUser: string,
+	) {}
+
+	public async borrow(role: string): Promise<void> {
+		if (this.borrowed.includes(role)) return;
+		if (await granted(this.pool, hasRolePrivilegesQuery(this.adminUser, role))) return;
+		try {
+			await this.pool.query(grantRoleMembershipQuery(this.adminUser, role).text);
+		} catch (err) {
+			throw new DataConfigurationError(
+				`Bootstrap role "${this.adminUser}" cannot act as "${role}". Make it a member of "${role}" (or create "${role}" with it), then run again.`,
+				{ cause: err },
+			);
+		}
+		this.borrowed.push(role);
+	}
+
+	public async [Symbol.asyncDispose](): Promise<void> {
+		for (const role of this.borrowed.reverse()) {
+			await this.pool.query(revokeRoleMembershipQuery(this.adminUser, role).text);
+		}
+	}
+}

package/src/sql-pretty.transport.ts

@@ -0,0 +1,29 @@
+import type { LogQuery } from "@decohere/data";
+import pinoPretty from "pino-pretty";
+import { PlatformTools } from "typeorm/platform/PlatformTools.js";
+
+export const SqlPretty = (opts?) =>
+	pinoPretty({
+		colorizeObjects: true,
+		customLevels:
+			Object.entries(opts?.levels ?? [])
+				.map(([key, value]) => `${key}:${value}`)
+				.join(",") ?? [],
+
+		customPrettifiers: {
+			sql: tryParseSql,
+		},
+
+		...opts,
+	});
+
+function tryParseSql(value: string | LogQuery) {
+	const isString = typeof value === "string";
+	const statement = isString ? value : value.statement;
+	try {
+		const formatted = PlatformTools.highlightSql(PlatformTools.formatSql(statement));
+		return formatted;
+	} catch {
+		return statement;
+	}
+}

package/src/type-orm.module.ts

@@ -0,0 +1,155 @@
+import {
+	type ConnectionInfo,
+	type DatabaseConfig,
+	DataConfigurationError,
+	DEFAULT_DATA_SOURCE,
+	type Dialect,
+	type Provider,
+} from "@decohere/data";
+import { type IReadinessCheck, ReadinessCheckToken } from "@decohere/http";
+import type { ContainerBuilder } from "@decohere/di";
+import { memoize } from "@decohere/core/caching";
+import type { DataSource, Logger } from "typeorm";
+import { bootstrapDataSources } from "./bootstrap.js";
+import { DataSourceFactory } from "./data-source.factory.js";
+import type { ModuleConfig } from "./database-options.js";
+import { typeOrmDataSourceToken } from "./inject-data-source.js";
+import { TypeOrmScribeLogger } from "./typeorm-scribe.logger.js";
+import { TypeOrmUnitOfWork } from "./unit-of-work.js";
+
+export type TypeOrmModuleOptions = {
+	applicationName: string;
+	databaseConfig: DatabaseConfig;
+	moduleConfigurations: ModuleConfig[];
+	containerBuilder: ContainerBuilder;
+};
+
+export class TypeOrmModule {
+	/** Registers and opens a DataSource per module. Returns the names it registered them under. */
+	public async configure(options: TypeOrmModuleOptions): Promise<(string | symbol)[]> {
+		const { moduleConfigurations, databaseConfig, containerBuilder, applicationName } =
+			options;
+
+		if (databaseConfig.dataSources.length === 0) {
+			throw new DataConfigurationError("No datasources detected in config");
+		}
+
+		const modules = this.resolveDataSources(databaseConfig, moduleConfigurations);
+		// Once, before any DataSource opens: modules sharing a database must not race to create it.
+		await bootstrapDataSources(
+			modules.map((m) => m.connectionInfo),
+			{ applicationName },
+		);
+
+		return await Promise.all(
+			modules.map(async ({ name, connectionInfo, moduleConfig }) => {
+				await this.init(applicationName, name, connectionInfo, moduleConfig, containerBuilder);
+				return name;
+			}),
+		);
+	}
+
+	private resolveDataSources(
+		databaseConfig: DatabaseConfig,
+		moduleConfigurations: ModuleConfig[],
+	): { name: string | symbol; connectionInfo: ConnectionInfo; moduleConfig: ModuleConfig }[] {
+		if (databaseConfig.dataSources.length === 1 && moduleConfigurations.length === 1) {
+			const moduleConfig = moduleConfigurations.at(0);
+			return [
+				{
+					name: moduleConfig.name ?? DEFAULT_DATA_SOURCE,
+					connectionInfo: databaseConfig.dataSources.at(0),
+					moduleConfig,
+				},
+			];
+		}
+
+		return moduleConfigurations.map((moduleConfig) => {
+			const { name } = moduleConfig;
+			if (name == null) {
+				throw new DataConfigurationError(
+					`Name is required if there is more than one datasource`,
+				);
+			}
+
+			const connectionInfo = databaseConfig.dataSources.find((ds) => ds.name === name);
+			if (connectionInfo == null) {
+				throw new DataConfigurationError(`Cannot find connection info for ${name.toString()}`);
+			}
+
+			return { name, connectionInfo, moduleConfig };
+		});
+	}
+
+	private async init(
+		applicationName: string,
+		name: string | symbol,
+		connectionInfo: ConnectionInfo,
+		moduleConfig: ModuleConfig,
+		builder: ContainerBuilder,
+	) {
+		const logger = this.getLoggerFor(name, connectionInfo.dialect);
+		const dataSource = await this.configureTypeOrmDataSource(
+			applicationName,
+			name,
+			moduleConfig,
+			connectionInfo,
+			builder,
+			logger,
+		);
+		if (connectionInfo.seed) {
+			await moduleConfig.seed?.(dataSource);
+		}
+	}
+
+	private async configureTypeOrmDataSource(
+		applicationName: string,
+		name: string | symbol,
+		moduleConfig: ModuleConfig,
+		connectionInfo: ConnectionInfo,
+		builder: ContainerBuilder,
+		logger: Logger,
+	) {
+		const { entities, repositories } = moduleConfig;
+		const dataSource = DataSourceFactory.create(
+			{
+				entities,
+				applicationName,
+				...connectionInfo,
+			},
+			logger,
+		);
+
+		await dataSource.initialize();
+		const unitOfWork = () => new TypeOrmUnitOfWork(dataSource);
+		builder.registerRequestScoped(name, unitOfWork);
+		builder.registerSingleton(typeOrmDataSourceToken(name), dataSource);
+		builder.registerSingleton(
+			ReadinessCheckToken,
+			createTypeOrmReadinessCheck(name, dataSource),
+		);
+
+		for (const repo of repositories ?? []) {
+			builder.registerRequestScoped(repo);
+		}
+
+		return dataSource;
+	}
+
+	@memoize()
+	private getLoggerFor(name: string | symbol, dialectOrProvider: Dialect | Provider) {
+		return new TypeOrmScribeLogger(name.toString(), dialectOrProvider);
+	}
+}
+
+function createTypeOrmReadinessCheck(
+	name: string | symbol,
+	dataSource: DataSource,
+): IReadinessCheck {
+	return {
+		name: `typeorm:${String(name)}`,
+		async check() {
+			await dataSource.query("SELECT 1");
+		},
+	};
+}

package/src/type-orm.provider.ts

@@ -0,0 +1,37 @@
+import type { Entity, IDataProvider } from "@decohere/data";
+import type { Constructable } from "@decohere/core/reflection";
+import type { FindManyOptions, FindOneOptions } from "typeorm";
+import type { TypeOrmUnitOfWork } from "./unit-of-work.js";
+
+export class TypeOrmQueryProvider implements IDataProvider {
+	public constructor(private unitOfWork: TypeOrmUnitOfWork) {}
+
+	public firstOrDefault<T extends Entity>(
+		entity: Constructable<T>,
+		options: FindOneOptions<T>,
+	) {
+		return this.unitOfWork.entityManager.findOne(entity, options);
+	}
+
+	public all<T>(entity: Constructable, options?: FindManyOptions<T>): Promise<T[]> {
+		return this.unitOfWork.getRepository<T>(entity).find(options);
+	}
+
+	public findById<T extends Entity>(entity: Constructable<T>, key: number | string) {
+		return this.unitOfWork.entityManager.findOneBy<Entity>(entity, {
+			id: key,
+		}) as Promise<T>;
+	}
+
+	public save<T>(entity: T): Promise<T> {
+		return this.unitOfWork.entityManager.save(entity);
+	}
+
+	public query<T extends Entity>(entity: Constructable<T>, filter: FindManyOptions<T>) {
+		return this.unitOfWork.entityManager.find(entity, filter);
+	}
+
+	public delete<T>(entity: T) {
+		return this.unitOfWork.entityManager.remove(entity);
+	}
+}

package/src/type-orm.repository.ts

@@ -0,0 +1,33 @@
+import { type Entity, Repository } from "@decohere/data";
+import type { Constructable } from "@decohere/core/reflection";
+import type { FindOneOptions } from "typeorm";
+import { TypeOrmQueryProvider } from "./type-orm.provider.js";
+import type { TypeOrmUnitOfWork } from "./unit-of-work.js";
+
+export abstract class TypeOrmRepository<T extends Entity> extends Repository<T> {
+	protected provider: TypeOrmQueryProvider;
+	protected type: Constructable<T>;
+	public constructor(unitOfWork: TypeOrmUnitOfWork, type: Constructable<T>) {
+		super();
+		this.type = type;
+		this.provider = new TypeOrmQueryProvider(unitOfWork);
+	}
+
+	public firstOrDefault(options: FindOneOptions<T>): Promise<T | null>;
+	public firstOrDefault<U extends Entity>(
+		type: Constructable<U>,
+		options: FindOneOptions<U>,
+	): Promise<U | null>;
+	public firstOrDefault<U extends Entity>(
+		optionsOrType: FindOneOptions<T> | Constructable<U>,
+		options?: FindOneOptions<U>,
+	): Promise<T | U | null> {
+		if (typeof optionsOrType === "function") {
+			if (!options) {
+				throw new Error("options parameter is required when type is provided");
+			}
+			return this.provider.firstOrDefault(optionsOrType, options);
+		}
+		return this.provider.firstOrDefault(this.type, optionsOrType);
+	}
+}

package/src/typeorm-scribe.logger.ts

@@ -0,0 +1,55 @@
+import type { Dialect, Provider } from "@decohere/data";
+import { cache } from "@decohere/core/caching";
+import { type DefaultLevels, type Logger, scribe } from "@decohere/scribe";
+import {
+	AbstractLogger,
+	type LogLevel,
+	type LogMessage,
+	type LogMessageType,
+	type QueryRunner,
+} from "typeorm";
+
+const MessageTypeMap = {
+	log: "info",
+	info: "info",
+	query: "info",
+	warn: "warn",
+	error: "error",
+	"query-error": "error",
+	"query-slow": "warn",
+	"schema-build": "info",
+	migration: "info",
+} satisfies Record<LogMessageType, DefaultLevels>;
+
+export class TypeOrmScribeLogger extends AbstractLogger {
+	private readonly logger: Logger;
+	private readonly dialect: Dialect | Provider;
+	public constructor(name: string, dialect: Dialect | Provider, enable: boolean = true) {
+		super(enable);
+		this.dialect = dialect;
+		this.logger = scribe.logger(`${name ?? "TypeOrm"}`);
+	}
+
+	protected writeLog(
+		level: LogLevel,
+		logMessage: LogMessage | LogMessage[],
+		_queryRunner?: QueryRunner,
+	) {
+		const messages = Array.isArray(logMessage) ? logMessage : [logMessage];
+		for (const message of messages) {
+			const logLevel = this.getLogLevel(message.type);
+			const prefix = message.type ?? level;
+			const statement = { sql: { statement: message.message, language: this.dialect } };
+			this.logger[logLevel](prefix, statement);
+		}
+	}
+
+	@cache()
+	private getLogLevel(type: LogMessageType | LogLevel) {
+		const level = Object.entries(MessageTypeMap)
+			.find(([key]) => type === key)
+			?.at(1);
+
+		return this.logger.isLevelEnabled(level) ? level : this.logger.currentLevel;
+	}
+}

package/src/typeorm.extensions.ts

@@ -0,0 +1,42 @@
+import { DatabaseConfig } from "@decohere/data";
+import { Builder } from "@decohere/http";
+import { extension } from "@decohere/core/extensibility";
+import type { Logger } from "typeorm";
+import type { ModuleConfig } from "./database-options.js";
+import { typeOrmDataSourceToken } from "./inject-data-source.js";
+import { TypeOrmModule } from "./type-orm.module.js";
+
+declare module "@decohere/http" {
+	interface Builder {
+		withTypeOrm(options?: ModuleConfig[] | ModuleConfig, logger?: Logger): Builder;
+	}
+}
+
+export class BuilderExtensions {
+	@extension(Builder)
+	public static withTypeOrm(builder: Builder, config: ModuleConfig[] | ModuleConfig) {
+		const names: (string | symbol)[] = [];
+		builder.registerPreBuildStep(async (configService, containerBuilder) => {
+			const databaseConfig = await configService.get(DatabaseConfig);
+			const module = new TypeOrmModule();
+			const moduleConfigurations = Array.isArray(config) ? config : [config];
+			const applicationName = builder.applicationName;
+			names.push(
+				...(await module.configure({
+					applicationName,
+					databaseConfig,
+					moduleConfigurations,
+					containerBuilder,
+				})),
+			);
+		});
+		// The container disposes only what it has handed out, and nothing may ever ask for a
+		// DataSource by its token. Resolving each here makes the root container own it, as one of
+		// its first instances, so it is closed last: after hosted services and other services
+		// that use it (#541).
+		builder.registerPostBuildStep((container) => {
+			for (const name of names) container.resolve(typeOrmDataSourceToken(name));
+		});
+		return builder;
+	}
+}