@flowdular/sdk 0.1.0

package/packages/sandbox/src/server/preview-database-proxy.ts

@@ -0,0 +1,356 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import {
+	assertNotAborted,
+	databaseDialectSql,
+	DatabaseError,
+	operationSignal,
+	type DatabaseAdapterLease,
+	type DatabaseCapabilities,
+	type DatabaseCommandResult,
+	type DatabaseHandle,
+	type DatabaseOperationOptions,
+	type DatabaseProvider,
+	type DatabaseProviderRequest,
+	type DatabaseQueryResult,
+	type DatabaseRow,
+	type DatabaseSchemaIntrospector,
+	type DatabaseSession,
+	type DatabaseStatement,
+	type DatabaseTransaction,
+	type DatabaseTransactionOptions,
+} from '@flowdular/sdk/database';
+import {
+	isPreviewDatabaseReply,
+	previewDatabaseError,
+	previewDatabaseFailure,
+	PREVIEW_DATABASE_REQUEST,
+	type PreviewDatabaseCall,
+	type PreviewDatabaseGrant,
+	type PreviewDatabaseLeaseRequest,
+	type PreviewDatabaseReply,
+	type PreviewDatabaseRequest,
+	type PreviewDatabaseTarget,
+	type PreviewDatabaseTransactionOptions,
+} from './preview-database-protocol.ts';
+
+export interface PreviewDatabasePort {
+	send(request: PreviewDatabaseRequest): void;
+	/** Every message the host puts on the channel, database or not. */
+	subscribe(listener: (message: unknown) => void): void;
+}
+
+interface LeaseMetadata {
+	readonly adapterId: string;
+	readonly dialectId: string;
+	readonly capabilities: DatabaseCapabilities;
+}
+
+function deadline(options: DatabaseOperationOptions): {
+	readonly timeoutMs?: number;
+} {
+	return options.timeoutMs === undefined
+		? {}
+		: { timeoutMs: options.timeoutMs };
+}
+
+function combinedSignal(
+	base: AbortSignal | undefined,
+	options: DatabaseOperationOptions,
+): AbortSignal | undefined {
+	const current = operationSignal(options);
+	return base && current ? AbortSignal.any([base, current]) : (base ?? current);
+}
+
+function leaseRequest(
+	request: DatabaseProviderRequest,
+): PreviewDatabaseLeaseRequest {
+	return {
+		namespace: request.namespace,
+		purpose: request.purpose,
+		...(request.requirements === undefined
+			? {}
+			: { requirements: request.requirements }),
+		...deadline(request),
+	};
+}
+
+function transactionOptions(
+	options: DatabaseTransactionOptions,
+): PreviewDatabaseTransactionOptions {
+	return {
+		...(options.access === undefined ? {} : { access: options.access }),
+		...(options.isolation === undefined
+			? {}
+			: { isolation: options.isolation }),
+		...(options.tenantId === undefined ? {} : { tenantId: options.tenantId }),
+		...deadline(options),
+	};
+}
+
+/**
+ * A database provider that satisfies the ordinary contract while its engine
+ * lives in the parent process. Draft module code never learns it is remote.
+ */
+export function createRemoteDatabaseProvider(
+	port: PreviewDatabasePort,
+): DatabaseProvider {
+	const pending = new Map<number, (reply: PreviewDatabaseReply) => void>();
+	const leases = new Set<number>();
+	/* A transaction callback runs here while its connection stays pinned in the
+	   parent, which cannot see this callback at all. The root handle is refused
+	   locally instead: the embedded engine is a single connection, so a root
+	   operation would queue behind the transaction that is waiting for it. */
+	const inTransaction = new AsyncLocalStorage<true>();
+	let requests = 0;
+	let resources = 0;
+	let disposed = false;
+
+	port.subscribe((message) => {
+		if (!isPreviewDatabaseReply(message)) return;
+		const settle = pending.get(message.id);
+		if (!settle) return;
+		pending.delete(message.id);
+		settle(message);
+	});
+
+	async function call<T>(
+		payload: PreviewDatabaseCall,
+		signal?: AbortSignal,
+	): Promise<T> {
+		assertNotAborted(signal);
+		const id = ++requests;
+		return await new Promise<T>((resolve, reject) => {
+			/* The parent keeps working on a request whose local deadline fired.
+			   Dropping the entry frees the caller; the reply is discarded. */
+			const abandon = () => {
+				if (!pending.delete(id)) return;
+				reject(
+					new DatabaseError(
+						'OPERATION_ABORTED',
+						'Database operation was aborted.',
+						{ cause: signal?.reason },
+					),
+				);
+			};
+			pending.set(id, (reply) => {
+				signal?.removeEventListener('abort', abandon);
+				if (reply.ok) resolve(reply.value as T);
+				else reject(previewDatabaseError(reply.error));
+			});
+			signal?.addEventListener('abort', abandon, { once: true });
+			try {
+				port.send({ type: PREVIEW_DATABASE_REQUEST, id, call: payload });
+			} catch (cause) {
+				pending.delete(id);
+				signal?.removeEventListener('abort', abandon);
+				reject(
+					new DatabaseError(
+						'ADAPTER_DISPOSED',
+						'The preview database channel is closed.',
+						{ cause },
+					),
+				);
+			}
+		});
+	}
+
+	function remoteSession(
+		target: PreviewDatabaseTarget,
+		metadata: LeaseMetadata,
+		base: AbortSignal | undefined,
+		guard: () => void,
+	): DatabaseSession {
+		const schema: DatabaseSchemaIntrospector = {
+			async hasTable(name, options = {}) {
+				guard();
+				return await call<boolean>(
+					{ kind: 'has-table', target, name, ...deadline(options) },
+					combinedSignal(base, options),
+				);
+			},
+			async hasColumn(table, column, options = {}) {
+				guard();
+				return await call<boolean>(
+					{ kind: 'has-column', target, table, column, ...deadline(options) },
+					combinedSignal(base, options),
+				);
+			},
+			async hasIndex(name, options = {}) {
+				guard();
+				return await call<boolean>(
+					{ kind: 'has-index', target, name, ...deadline(options) },
+					combinedSignal(base, options),
+				);
+			},
+		};
+		return {
+			adapterId: metadata.adapterId,
+			dialectId: metadata.dialectId,
+			capabilities: metadata.capabilities,
+			schema,
+			async query<Row extends DatabaseRow = DatabaseRow>(
+				statement: DatabaseStatement,
+				options: DatabaseOperationOptions = {},
+			): Promise<DatabaseQueryResult<Row>> {
+				guard();
+				return await call<DatabaseQueryResult<Row>>(
+					{ kind: 'query', target, statement, ...deadline(options) },
+					combinedSignal(base, options),
+				);
+			},
+			async execute(
+				statement: DatabaseStatement,
+				options: DatabaseOperationOptions = {},
+			): Promise<DatabaseCommandResult> {
+				guard();
+				return await call<DatabaseCommandResult>(
+					{ kind: 'execute', target, statement, ...deadline(options) },
+					combinedSignal(base, options),
+				);
+			},
+			async executeScript(
+				script: string,
+				options: DatabaseOperationOptions = {},
+			): Promise<void> {
+				guard();
+				await call<undefined>(
+					{ kind: 'script', target, script, ...deadline(options) },
+					combinedSignal(base, options),
+				);
+			},
+		};
+	}
+
+	function remoteHandle(
+		lease: number,
+		metadata: LeaseMetadata,
+	): DatabaseHandle {
+		const assertRoot = () => {
+			if (!inTransaction.getStore()) return;
+			throw new DatabaseError(
+				'TRANSACTION_CONTEXT_MISUSE',
+				'Use the transaction argument inside a transaction callback.',
+			);
+		};
+		return {
+			...remoteSession({ lease }, metadata, undefined, assertRoot),
+			async transaction<T>(
+				operation: (transaction: DatabaseTransaction) => Promise<T>,
+				options: DatabaseTransactionOptions = {},
+			): Promise<T> {
+				assertRoot();
+				const signal = operationSignal(options);
+				const transaction = ++resources;
+				try {
+					await call<undefined>(
+						{
+							kind: 'begin',
+							lease,
+							transaction,
+							options: transactionOptions(options),
+						},
+						signal,
+					);
+				} catch (error) {
+					/* A begin whose local deadline fired may still have pinned the
+					   parent connection, so the rollback is asked for by token. */
+					void call<undefined>({
+						kind: 'settle',
+						transaction,
+						error: previewDatabaseFailure(error),
+					}).catch(() => undefined);
+					throw error;
+				}
+				let active = true;
+				const guard = () => {
+					if (active) return;
+					throw new DatabaseError(
+						'TRANSACTION_CONTEXT_MISUSE',
+						'The preview database transaction callback has already ended.',
+					);
+				};
+				const pinned: DatabaseTransaction = {
+					...remoteSession({ lease, transaction }, metadata, signal, guard),
+					async acquireMigrationLock(namespace: string): Promise<void> {
+						guard();
+						await call<undefined>(
+							{ kind: 'migration-lock', transaction, namespace },
+							signal,
+						);
+					},
+				};
+				let value: T;
+				try {
+					value = await inTransaction.run(true, () => operation(pinned));
+				} catch (error) {
+					active = false;
+					/* The settle carries no signal: an aborted transaction still has
+					   to reach the parent, which is holding the connection open. */
+					await call<undefined>({
+						kind: 'settle',
+						transaction,
+						error: previewDatabaseFailure(error),
+					}).catch(() => undefined);
+					throw error;
+				}
+				active = false;
+				await call<undefined>({ kind: 'settle', transaction, error: null });
+				return value;
+			},
+		};
+	}
+
+	return {
+		async acquire(
+			request: DatabaseProviderRequest,
+		): Promise<DatabaseAdapterLease> {
+			if (disposed) {
+				throw new DatabaseError(
+					'ADAPTER_DISPOSED',
+					'The preview database provider is not accepting leases.',
+				);
+			}
+			const signal = operationSignal(request);
+			const lease = ++resources;
+			let granted: PreviewDatabaseGrant;
+			try {
+				granted = await call<PreviewDatabaseGrant>(
+					{ kind: 'acquire', lease, request: leaseRequest(request) },
+					signal,
+				);
+			} catch (error) {
+				void call<undefined>({ kind: 'release', lease }).catch(() => undefined);
+				throw error;
+			}
+			leases.add(lease);
+			const metadata: LeaseMetadata = {
+				adapterId: granted.adapterId,
+				dialectId: granted.dialectId,
+				capabilities: Object.freeze({
+					...granted.capabilities,
+					sql: databaseDialectSql(granted.dialectId),
+				}),
+			};
+			const database = remoteHandle(lease, metadata);
+			let released = false;
+			return {
+				database,
+				async release(): Promise<void> {
+					if (released) return;
+					released = true;
+					leases.delete(lease);
+					await call<undefined>({ kind: 'release', lease });
+				},
+			};
+		},
+		async dispose(): Promise<void> {
+			if (disposed) return;
+			disposed = true;
+			const open = [...leases];
+			leases.clear();
+			await Promise.allSettled(
+				open.map((lease) => call<undefined>({ kind: 'release', lease })),
+			);
+		},
+	};
+}

package/packages/sandbox/src/server/preview-database.ts

@@ -0,0 +1,109 @@
+import { join } from 'node:path';
+import {
+	assertNamespace,
+	DatabaseError,
+	PostgresDatabaseAdapter,
+	type DatabaseAdapter,
+	type DatabaseAdapterLease,
+	type DatabaseProvider,
+	type DatabaseProviderRequest,
+} from '@flowdular/sdk/database';
+import { createPgliteCluster } from '@flowdular/sdk/database-pglite';
+
+const RUNTIME_ROLE = 'coreloom_runtime';
+const BACKGROUND_ROLE = 'coreloom_background';
+
+/* Created before the first lease, so every table the migration lease creates is
+   reachable by the runtime role without a second grant step. */
+const BOOTSTRAP = `DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '${RUNTIME_ROLE}') THEN
+    CREATE ROLE ${RUNTIME_ROLE} NOSUPERUSER NOBYPASSRLS;
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '${BACKGROUND_ROLE}') THEN
+    CREATE ROLE ${BACKGROUND_ROLE} NOSUPERUSER NOBYPASSRLS;
+  END IF;
+END
+$$;
+GRANT USAGE ON SCHEMA public TO ${RUNTIME_ROLE}, ${BACKGROUND_ROLE};
+ALTER DEFAULT PRIVILEGES IN SCHEMA public
+  GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ${RUNTIME_ROLE};
+`;
+
+/* A preview owns its database the way it owns its authentication runtime: one
+   embedded PostgreSQL under the session data directory, the only place the
+   preview worker may write, thrown away with the session. A draft therefore
+   meets the same forced row-level security a deployment enforces, and it is
+   never handed a deployment adapter or a DSN. */
+export function createPreviewDatabaseProvider(
+	dataPath: string,
+): DatabaseProvider {
+	const cluster = createPgliteCluster({
+		dataDirectory: join(dataPath, 'preview-postgres'),
+		bootstrap: BOOTSTRAP,
+	});
+	let adapters: {
+		migrator: DatabaseAdapter;
+		runtime: DatabaseAdapter;
+		background: DatabaseAdapter;
+	} | null = null;
+	let disposed = false;
+
+	const opened = () => {
+		adapters ??= {
+			migrator: new PostgresDatabaseAdapter({ pool: cluster.pool() }),
+			runtime: new PostgresDatabaseAdapter({
+				pool: cluster.pool(RUNTIME_ROLE),
+				tenantRequired: true,
+			}),
+			/* A draft that polls across tenants meets the same narrow role a
+			   deployment gives it: no default table grant, so it reads only the
+			   columns a migration named under that table's own policy. */
+			background: new PostgresDatabaseAdapter({
+				pool: cluster.pool(BACKGROUND_ROLE),
+			}),
+		};
+		return adapters;
+	};
+
+	return {
+		async acquire(
+			request: DatabaseProviderRequest,
+		): Promise<DatabaseAdapterLease> {
+			if (disposed) {
+				throw new DatabaseError(
+					'ADAPTER_DISPOSED',
+					'The preview database provider is not accepting leases.',
+				);
+			}
+			assertNamespace(request.namespace);
+			const { migrator, runtime, background } = opened();
+			/* Releasing a lease closes nothing: a draft that leaks one must not be
+			   able to keep the preview generation from retiring. */
+			return {
+				database:
+					request.purpose === 'migration'
+						? migrator
+						: request.purpose === 'background'
+							? background
+							: runtime,
+				release: () => Promise.resolve(),
+			};
+		},
+		async dispose() {
+			if (disposed) return;
+			disposed = true;
+			const open = adapters;
+			adapters = null;
+			if (open) {
+				await Promise.allSettled([
+					open.background.dispose(),
+					open.runtime.dispose(),
+					open.migrator.dispose(),
+				]);
+				return;
+			}
+			await cluster.close();
+		},
+	};
+}

package/packages/sandbox/src/server/preview-ipc.ts

@@ -0,0 +1,15 @@
+import type { ChildProcess } from 'node:child_process';
+import type { PreviewDatabaseReply } from './preview-database-protocol.ts';
+
+/** connected can change between the check and the asynchronous pipe write. */
+export function sendPreviewDatabaseReply(
+	child: Pick<ChildProcess, 'connected' | 'send'>,
+	reply: PreviewDatabaseReply,
+): void {
+	if (!child.connected) return;
+	try {
+		child.send(reply, () => undefined);
+	} catch {
+		// The worker closed the channel before Node could queue the write.
+	}
+}

package/packages/sandbox/src/server/preview-modules.ts

@@ -0,0 +1,83 @@
+import { sandboxDirectory } from './config.ts';
+import { readFile, realpath } from 'node:fs/promises';
+import { dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { SandboxSession } from './sessions.ts';
+
+export interface PreviewModuleSource {
+	readonly id: string;
+	readonly directory: string;
+	readonly path: string;
+	readonly support: boolean;
+}
+
+export const PREVIEW_SUPPORT_ROOT = resolve(
+	dirname(fileURLToPath(import.meta.url)),
+	'../../../../modules',
+);
+const IDENTIFIER = /^[a-z][a-z0-9-]*\.core$/;
+
+async function manifest(
+	path: string,
+	optional: boolean,
+): Promise<{ id?: string; dependencies?: readonly { id: string }[] }> {
+	try {
+		return JSON.parse(await readFile(join(path, 'module.json'), 'utf8'));
+	} catch (error) {
+		if (optional && (error as NodeJS.ErrnoException).code === 'ENOENT')
+			return {};
+		throw error;
+	}
+}
+
+/** Dependencies are read-only platform sources, never copied into the draft or
+ * included in delivery. Only explicitly declared dependencies are composed. */
+export async function resolvePreviewModules(
+	workspaceRoot: string,
+	session: SandboxSession,
+	supportRoot = PREVIEW_SUPPORT_ROOT,
+): Promise<readonly PreviewModuleSource[]> {
+	const draftRoot = join(
+		sandboxDirectory(workspaceRoot),
+		'sessions',
+		session.id,
+		'workspace/modules',
+	);
+	const drafts = new Map(session.modules.map((module) => [module.id, module]));
+	const visiting = new Set<string>();
+	const visited = new Set<string>();
+	const ordered: PreviewModuleSource[] = [];
+	const visit = async (id: string): Promise<void> => {
+		// The preview owns a separate auth runtime and its seeded identity.
+		if (id === 'auth.core' || visited.has(id)) return;
+		if (visiting.has(id)) throw new Error('PREVIEW_DEPENDENCY_CYCLE: ' + id);
+		if (visited.size + visiting.size >= 64)
+			throw new Error('PREVIEW_DEPENDENCY_LIMIT');
+		visiting.add(id);
+		const draft = drafts.get(id);
+		if (!draft && !IDENTIFIER.test(id))
+			throw new Error('PREVIEW_DEPENDENCY_UNAVAILABLE: ' + id);
+		const directory = draft?.directory ?? id.slice(0, -5);
+		if (!/^[a-z][a-z0-9-]*$/.test(directory))
+			throw new Error('PREVIEW_MODULE_DIRECTORY_INVALID');
+		const path = draft
+			? join(draftRoot, directory)
+			: join(supportRoot, directory);
+		if (!draft) {
+			const physical = await realpath(path).catch(() => null);
+			const root = await realpath(supportRoot);
+			if (!physical?.startsWith(root + sep))
+				throw new Error('PREVIEW_DEPENDENCY_UNAVAILABLE: ' + id);
+		}
+		const definition = await manifest(path, Boolean(draft));
+		if (definition.id && definition.id !== id)
+			throw new Error('PREVIEW_DEPENDENCY_ID_MISMATCH: ' + id);
+		for (const dependency of definition.dependencies ?? [])
+			await visit(dependency.id);
+		visiting.delete(id);
+		visited.add(id);
+		ordered.push({ id, directory, path, support: !draft });
+	};
+	for (const module of session.modules) await visit(module.id);
+	return ordered;
+}

package/packages/sandbox/src/server/preview-revision.ts

@@ -0,0 +1,44 @@
+import { createHash } from 'node:crypto';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { PreviewModuleSource } from './preview-modules.ts';
+
+/** Includes dependency sources and deletions, not only the newest entry mtime. */
+export async function previewRevision(
+	sources: readonly PreviewModuleSource[],
+): Promise<string> {
+	const hash = createHash('sha256');
+	const file = async (path: string, name: string) => {
+		try {
+			const content = await readFile(path);
+			hash.update(JSON.stringify([name, content.length]));
+			hash.update(content);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+		}
+	};
+	const directory = async (path: string, prefix: string): Promise<void> => {
+		const entries = await readdir(path, { withFileTypes: true }).catch(
+			(error: NodeJS.ErrnoException) => {
+				if (error.code === 'ENOENT') return [];
+				throw error;
+			},
+		);
+		for (const entry of entries.sort((left, right) =>
+			left.name.localeCompare(right.name),
+		)) {
+			if (entry.name === 'node_modules' || entry.name === 'dist') continue;
+			const name = prefix + '/' + entry.name;
+			if (entry.isDirectory()) await directory(join(path, entry.name), name);
+			else if (entry.isFile()) await file(join(path, entry.name), name);
+		}
+	};
+	for (const source of sources) {
+		hash.update(JSON.stringify([source.id, source.path]));
+		await file(join(source.path, 'module.json'), 'module.json');
+		await file(join(source.path, 'package.json'), 'package.json');
+		await directory(join(source.path, 'src'), 'src');
+		await directory(join(source.path, 'migrations'), 'migrations');
+	}
+	return hash.digest('hex');
+}