@pvidaal07/heydb 0.0.0-stage → 2.0.0-beta.0

package/lib/config/operations.ts

@@ -0,0 +1,75 @@
+import { assertConnectionName } from "../store/guards.ts";
+import type { Config, ConnectionConfig } from "./types.ts";
+import { validateConnection } from "./validate.ts";
+
+// Pure operations on Config, like the knowledge ones: each returns a new value
+// and never mutates its input, and every entry they produce has passed the
+// same validation as a file loaded from disk. Callers decide when to save.
+
+export function emptyConfig(): Config {
+	return { formatVersion: 1, defaultConnection: null, connections: {} };
+}
+
+export function addConnection(config: Config, name: string, entry: ConnectionConfig): Config {
+	assertConnectionName(name);
+	if (Object.hasOwn(config.connections, name)) {
+		throw new Error(`connection "${name}" already exists; update or remove it instead`);
+	}
+	return withConnections(config, { ...config.connections, [name]: validateConnection(entry, name) });
+}
+
+/** Changes only the given fields; the merged entry is validated again. */
+export function updateConnection(config: Config, name: string, changes: Partial<ConnectionConfig>): Config {
+	const existing = requireConnection(config, name);
+	return withConnections(config, { ...config.connections, [name]: validateConnection({ ...existing, ...changes }, name) });
+}
+
+/** Removes a connection; when it was the default, there is no default any more. */
+export function removeConnection(config: Config, name: string): Config {
+	requireConnection(config, name);
+	const connections = Object.fromEntries(Object.entries(config.connections).filter(([key]) => key !== name));
+	const defaultConnection = config.defaultConnection === name ? null : config.defaultConnection;
+	return { formatVersion: 1, defaultConnection, connections };
+}
+
+export function setDefaultConnection(config: Config, name: string | null): Config {
+	if (name !== null) requireConnection(config, name);
+	return { ...config, defaultConnection: name };
+}
+
+/**
+ * The connection a command should use: the name it was given, else the
+ * default, else the only one configured. Anything else would be a guess, and
+ * a wrong guess here means reading the wrong server.
+ */
+export function pickConnection(config: Config, name?: string): { name: string; connection: ConnectionConfig } {
+	const chosen = name ?? config.defaultConnection ?? onlyConnection(config);
+	return { name: chosen, connection: requireConnection(config, chosen) };
+}
+
+function onlyConnection(config: Config): string {
+	const names = sortedNames(config);
+	const [only] = names;
+	if (only === undefined) throw new Error("no connections are configured: add one first");
+	if (names.length > 1) {
+		throw new Error(
+			`several connections are configured (${names.join(", ")}) and none is the default: pass a connection name or set a default`,
+		);
+	}
+	return only;
+}
+
+function requireConnection(config: Config, name: string): ConnectionConfig {
+	if (Object.hasOwn(config.connections, name)) return config.connections[name] as ConnectionConfig;
+	const names = sortedNames(config);
+	const known = names.length === 0 ? "no connections are configured" : `configured: ${names.join(", ")}`;
+	throw new Error(`unknown connection "${name}"; ${known}`);
+}
+
+function withConnections(config: Config, connections: Record<string, ConnectionConfig>): Config {
+	return { ...config, connections };
+}
+
+function sortedNames(config: Config): string[] {
+	return Object.keys(config.connections).sort();
+}

package/lib/config/store.ts

@@ -0,0 +1,73 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { stableJson, writeFileAtomic } from "../store/files.ts";
+import { assertNoSymlinks } from "../store/guards.ts";
+import { HEYDB_DIR } from "../store/project.ts";
+import { emptyConfig } from "./operations.ts";
+import type { Config } from "./types.ts";
+import { validateConfig } from "./validate.ts";
+
+// .heydb/config.json: the connections of the project, committed, without
+// secrets. Written like the snapshot (sorted keys, atomic rename), so a git
+// diff of a config change shows only the changed fields.
+
+const SUPPORTED_FORMAT_VERSION = 1;
+const FILE_NAME = "config.json";
+
+export function configPath(projectRoot: string): string {
+	return join(projectRoot, HEYDB_DIR, FILE_NAME);
+}
+
+export function saveConfig(projectRoot: string, config: Config): void {
+	assertNoSymlinks(projectRoot, FILE_NAME);
+	// Validated again on the way out: a config that could not be loaded back is never written.
+	writeFileAtomic(configPath(projectRoot), stableJson(validateConfig(config)));
+}
+
+/** Returns the stored config; a project without config.json has no connections yet. */
+export function loadConfig(projectRoot: string): Config {
+	const path = configPath(projectRoot);
+	assertNoSymlinks(projectRoot, FILE_NAME);
+
+	let text: string;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch (error) {
+		if (isMissingFile(error)) return emptyConfig();
+		throw error;
+	}
+
+	let data: unknown;
+	try {
+		data = JSON.parse(text);
+	} catch {
+		throw new Error(`${FILE_NAME} is not valid JSON (${path})`);
+	}
+	return checkConfig(data);
+}
+
+function checkConfig(data: unknown): Config {
+	if (data === null || typeof data !== "object" || Array.isArray(data)) {
+		throw new Error(`${FILE_NAME} is not a heydb config: expected a JSON object`);
+	}
+	const record = data as Record<string, unknown>;
+	if (!("formatVersion" in record)) {
+		throw new Error(`${FILE_NAME} is not a heydb config: missing "formatVersion"`);
+	}
+	if (record.formatVersion !== SUPPORTED_FORMAT_VERSION) {
+		throw new Error(
+			`${FILE_NAME}: unsupported config formatVersion ${JSON.stringify(record.formatVersion)} (expected ${SUPPORTED_FORMAT_VERSION}); update heydb`,
+		);
+	}
+	try {
+		return validateConfig(data);
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		throw new Error(`${FILE_NAME} is not a heydb config: ${reason}`, { cause: error });
+	}
+}
+
+function isMissingFile(error: unknown): boolean {
+	return error instanceof Error && "code" in error && error.code === "ENOENT";
+}

package/lib/config/types.ts

@@ -0,0 +1,37 @@
+// The connections of a project live in .heydb/config.json, which is committed:
+// teammates share host, port, engine and user through git. That only works
+// because the file holds NO secrets. A password is always a reference such as
+// "env:HEYDB_PROD_PASSWORD", resolved on the machine that connects (ADR-0005).
+
+/** Engines a connection may use. */
+export type ConnectionEngine = "mysql" | "mariadb" | "postgresql";
+
+export interface ConnectionConfig {
+	readonly engine: ConnectionEngine;
+	readonly host: string;
+	readonly port: number;
+	readonly user: string;
+	/** Only a reference, "env:HEYDB_NAME"; never the password itself. */
+	readonly password: string;
+	/**
+	 * Databases to capture; null captures every database the user can see.
+	 * PostgreSQL: exactly one, the database to connect to, because a PostgreSQL
+	 * connection only ever reaches the database it was opened on.
+	 */
+	readonly databases: readonly string[] | null;
+	/**
+	 * PostgreSQL only: schemas to capture inside that database; null captures
+	 * every non-system schema. Absent for MySQL and MariaDB, where each database
+	 * is its own schema.
+	 */
+	readonly schemas?: readonly string[] | null;
+}
+
+export interface Config {
+	/** Bumped only when the shape of this file changes incompatibly. */
+	readonly formatVersion: 1;
+	/** Used when a command names no connection; null when none was chosen. */
+	readonly defaultConnection: string | null;
+	/** By connection name; names follow the same allow-list as snapshot files. */
+	readonly connections: Readonly<Record<string, ConnectionConfig>>;
+}

package/lib/config/validate.ts

@@ -0,0 +1,136 @@
+import { PASSWORD_REFERENCE, REFERENCE_RULE, suggestedReference } from "../secrets.ts";
+import { assertConnectionName } from "../store/guards.ts";
+import type { Config, ConnectionConfig, ConnectionEngine } from "./types.ts";
+
+// config.json is committed and edited by hand, so every field is checked at
+// the boundary, like snapshots and knowledge. The result is rebuilt field by
+// field, and an unknown field is an error, not dropped: a password typed under
+// a misspelt key would otherwise stay in the committed file unnoticed. Errors
+// name the exact path, e.g. "connections.prod.port must be an integer from 1 to 65535".
+//
+// The same check runs on every entry the pure operations add or update, so a
+// config in memory is always one that could have been loaded from disk.
+//
+// No message ever repeats the value of a password field, or of an unknown
+// field: either may be the real password.
+
+const ENGINES: readonly ConnectionEngine[] = ["mysql", "mariadb", "postgresql"];
+const ROOT_FIELDS = ["formatVersion", "defaultConnection", "connections"];
+const CONNECTION_FIELDS = ["engine", "host", "port", "user", "password", "databases", "schemas"];
+
+export function validateConfig(data: unknown): Config {
+	const root = object(data, "config");
+	onlyKnownFields(root, ROOT_FIELDS, "config");
+	if (root.formatVersion !== 1) throw new Error("formatVersion must be 1");
+
+	const defaultConnection = read(root, "defaultConnection");
+	if (defaultConnection !== null && typeof defaultConnection !== "string") {
+		throw new Error("defaultConnection must be null or a string");
+	}
+	const entries = object(read(root, "connections"), "connections");
+	// A Map, then Object.fromEntries: the result only has the names that were read.
+	const connections = new Map<string, ConnectionConfig>();
+	for (const [name, value] of Object.entries(entries)) {
+		try {
+			assertConnectionName(name);
+		} catch (error) {
+			throw new Error(`connections: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+		}
+		connections.set(name, validateConnection(value, name));
+	}
+	if (defaultConnection !== null && !connections.has(defaultConnection)) {
+		throw new Error(`defaultConnection ${JSON.stringify(defaultConnection)} is not one of the configured connections`);
+	}
+	return { formatVersion: 1, defaultConnection, connections: Object.fromEntries(connections) };
+}
+
+export function validateConnection(data: unknown, name: string): ConnectionConfig {
+	const path = `connections.${name}`;
+	const entry = object(data, path);
+	onlyKnownFields(entry, CONNECTION_FIELDS, path);
+	const connection = {
+		engine: engine(read(entry, "engine", path), `${path}.engine`),
+		host: text(read(entry, "host", path), `${path}.host`),
+		port: port(read(entry, "port", path), `${path}.port`),
+		user: text(read(entry, "user", path), `${path}.user`),
+		password: password(read(entry, "password", path), `${path}.password`, name),
+		databases: names(read(entry, "databases", path), `${path}.databases`, "every database"),
+	};
+	if (connection.engine !== "postgresql") {
+		// An undefined value counts as absent: it is what spreading a partial update leaves behind.
+		if (entry.schemas !== undefined) {
+			throw new Error(
+				`${path}.schemas is only allowed for postgresql: in MySQL and MariaDB every database is its own schema, so choose them with "databases"`,
+			);
+		}
+		return connection;
+	}
+	if (connection.databases?.length !== 1) {
+		throw new Error(
+			`${path}.databases must list exactly one database for postgresql: a PostgreSQL connection only reaches ` +
+				'the database it connects to, so add one connection per database (and use "schemas" to choose schemas inside it)',
+		);
+	}
+	// Written as an explicit null when absent, like every other "all" in this file.
+	return { ...connection, schemas: names(entry.schemas ?? null, `${path}.schemas`, "every non-system schema") };
+}
+
+function engine(value: unknown, path: string): ConnectionEngine {
+	const found = ENGINES.find((item) => item === value);
+	if (found === undefined) throw new Error(`${path} must be "mysql", "mariadb" or "postgresql"`);
+	return found;
+}
+
+function text(value: unknown, path: string): string {
+	if (typeof value !== "string" || value === "") throw new Error(`${path} must be a non-empty string`);
+	return value;
+}
+
+function port(value: unknown, path: string): number {
+	if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > 65535) {
+		throw new Error(`${path} must be an integer from 1 to 65535`);
+	}
+	return value;
+}
+
+function password(value: unknown, path: string, name: string): string {
+	if (typeof value === "string" && PASSWORD_REFERENCE.test(value)) return value;
+	const example = suggestedReference(name);
+	if (typeof value === "string" && value.startsWith("env:")) {
+		throw new Error(`${path} must be a reference such as "${example}": ${REFERENCE_RULE}`);
+	}
+	throw new Error(
+		`${path} must be a reference such as "${example}", never the password itself: ` +
+			".heydb/config.json is committed to git, so anything written there is readable by everyone with the repository. " +
+			"Put the password in that environment variable (or in .heydb/.env, which git ignores).",
+	);
+}
+
+/** A list of unique names, or null for "all"; `all` says what null means in the message. */
+function names(value: unknown, path: string, all: string): readonly string[] | null {
+	if (value === null) return null;
+	if (!Array.isArray(value) || value.length === 0) {
+		throw new Error(`${path} must be null (${all}) or a non-empty list of names`);
+	}
+	return value.map((item: unknown, index) => {
+		if (typeof item !== "string" || item === "") throw new Error(`${path}[${index}] must be a non-empty string`);
+		if (value.indexOf(item) !== index) throw new Error(`${path} repeats ${JSON.stringify(item)}`);
+		return item;
+	});
+}
+
+/** Names the first unknown field, never its value. */
+function onlyKnownFields(record: Record<string, unknown>, known: readonly string[], path: string): void {
+	const unknown = Object.keys(record).find((key) => !known.includes(key));
+	if (unknown !== undefined) throw new Error(`${path} has an unknown field ${JSON.stringify(unknown)}`);
+}
+
+function read(record: Record<string, unknown>, key: string, path = ""): unknown {
+	if (!(key in record)) throw new Error(`${path === "" ? key : `${path}.${key}`} is missing`);
+	return record[key];
+}
+
+function object(value: unknown, path: string): Record<string, unknown> {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`${path} must be an object`);
+	return value as Record<string, unknown>;
+}

package/lib/engines/index.ts

@@ -0,0 +1,66 @@
+import type { ConnectionConfig } from "../config/types.ts";
+import type { Snapshot } from "../model/snapshot.ts";
+import type { MysqlConnectionOptions } from "./mysql/introspect.ts";
+import type { PostgresConnectionOptions } from "./postgres/introspect.ts";
+
+// The one entry point to every engine. Callers pass a config entry and the
+// already resolved password (lib/secrets.ts); this file picks the engine.
+//
+// Drivers load only when used (ADR-0006): the engine module, and with it its
+// driver, is imported with a dynamic import() inside the function, never at
+// the top of this file. Reading the snapshot, searching or annotating never
+// connect, so they never pay for mysql2 or pg. `import type` above is erased before
+// the code runs and loads nothing; tests/engines/index.test.ts checks both.
+
+// One shared promise per engine module: concurrent callers wait for the same
+// import instead of starting their own. Pi's module loader breaks when two
+// imports of mysql2 run at the same time (seen with two /heydb:status at once).
+let mysqlEngine: Promise<typeof import("./mysql/introspect.ts")> | undefined;
+
+function loadMysqlEngine(): Promise<typeof import("./mysql/introspect.ts")> {
+	mysqlEngine ??= import("./mysql/introspect.ts").catch((error: unknown) => {
+		mysqlEngine = undefined; // a failed load can be retried
+		throw error;
+	});
+	return mysqlEngine;
+}
+
+let postgresEngine: Promise<typeof import("./postgres/introspect.ts")> | undefined;
+
+function loadPostgresEngine(): Promise<typeof import("./postgres/introspect.ts")> {
+	postgresEngine ??= import("./postgres/introspect.ts").catch((error: unknown) => {
+		postgresEngine = undefined; // a failed load can be retried
+		throw error;
+	});
+	return postgresEngine;
+}
+
+/** Captures the structure of the server described by `entry`. */
+export async function introspect(entry: ConnectionConfig, password: string): Promise<Snapshot> {
+	switch (entry.engine) {
+		case "mysql":
+		case "mariadb": {
+			const { introspectMysql } = await loadMysqlEngine();
+			return introspectMysql(mysqlOptions(entry, password));
+		}
+		case "postgresql": {
+			// Built before the import, so a bad entry fails without loading pg.
+			const options = postgresOptions(entry, password);
+			const { introspectPostgres } = await loadPostgresEngine();
+			return introspectPostgres(options);
+		}
+	}
+}
+
+/** MySQL and MariaDB speak the same protocol, so both use the same driver options. */
+export function mysqlOptions(entry: ConnectionConfig, password: string): MysqlConnectionOptions {
+	return { host: entry.host, port: entry.port, user: entry.user, password, databases: entry.databases };
+}
+
+/** A PostgreSQL connection reaches one database: the only entry of `databases`. */
+export function postgresOptions(entry: ConnectionConfig, password: string): PostgresConnectionOptions {
+	const [database, ...others] = entry.databases ?? [];
+	// Config validation already requires exactly one; this guards entries built in code.
+	if (database === undefined || others.length > 0) throw new Error("a postgresql connection needs exactly one database");
+	return { host: entry.host, port: entry.port, user: entry.user, password, database, schemas: entry.schemas ?? null };
+}