@flowdular/sdk 0.1.0 → 0.2.0

package/packages/sandbox/src/server/platform-client.ts

@@ -1,189 +0,0 @@
-import { SandboxSetupError } from './workspace-root.ts';
-
-export interface PlatformPrincipal {
-	readonly accountId: string;
-	readonly tenantId: string;
-	readonly email: string;
-	readonly displayName: string;
-	readonly role: string;
-	readonly scopes: readonly string[];
-	readonly tenantName: string;
-	readonly tenantSlug: string;
-}
-
-export interface PlatformAuthority {
-	readonly principal: PlatformPrincipal;
-	readonly authority:
-		| {
-				readonly granted: true;
-				readonly grantId: string;
-				readonly capabilities: readonly string[];
-				readonly expiresAt: number | null;
-		  }
-		| { readonly granted: false; readonly reason: string };
-}
-
-export interface BridgeRequest {
-	readonly method: string;
-	readonly path: string;
-	readonly search: string;
-	readonly accept: string | null;
-}
-
-export interface BridgeResponse {
-	readonly status: number;
-	readonly contentType: string;
-	readonly body: string;
-}
-
-const BRIDGE_TIMEOUT_MS = 15_000;
-const BRIDGE_BODY_LIMIT = 2 * 1024 * 1024;
-
-export interface PlatformClientOptions {
-	readonly platformUrl: string;
-	readonly token: string;
-	readonly fetch?: typeof globalThis.fetch;
-}
-
-export class PlatformClient {
-	readonly #platformUrl: string;
-	readonly #token: string;
-	readonly #fetch: typeof globalThis.fetch;
-
-	constructor(options: PlatformClientOptions) {
-		this.#platformUrl = options.platformUrl.replace(/\/+$/, '');
-		this.#token = options.token;
-		this.#fetch = options.fetch ?? globalThis.fetch;
-	}
-
-	async authority(): Promise<PlatformAuthority> {
-		const response = await this.#request('GET', '/api/sandbox/authority');
-		if (response.status === 401) {
-			throw new SandboxSetupError(
-				'PLATFORM_TOKEN_REJECTED',
-				'The platform rejected this API token. Issue a new one in Administration.',
-			);
-		}
-		if (response.status === 403) {
-			throw new SandboxSetupError(
-				'SANDBOX_SCOPE_MISSING',
-				'The token does not carry sandbox.access.use for this workspace.',
-			);
-		}
-		if (response.status === 404) {
-			throw new SandboxSetupError(
-				'SANDBOX_MODULE_MISSING',
-				'The connected application does not expose sandbox.core. Enable the module there first.',
-			);
-		}
-		if (!response.ok) {
-			throw new SandboxSetupError(
-				'PLATFORM_UNREACHABLE',
-				`The platform answered ${response.status} for the sandbox authority check.`,
-			);
-		}
-		return (await response.json()) as PlatformAuthority;
-	}
-
-	async registerSession(input: {
-		readonly sessionId: string;
-		readonly moduleId: string;
-		readonly title: string;
-		readonly blueprint: string;
-		readonly driver: string;
-		readonly mode: string;
-	}): Promise<void> {
-		await this.#json('POST', '/api/sandbox/sessions', input);
-	}
-
-	async updateSessionState(sessionId: string, state: string): Promise<void> {
-		await this.#json('POST', '/api/sandbox/sessions/state', {
-			sessionId,
-			state,
-		});
-	}
-
-	/* A delivered module is audit evidence on the platform, next to the
-	   session record it came from. */
-	async recordEject(
-		sessionId: string,
-		metadata: Readonly<Record<string, string | number | boolean>>,
-	): Promise<void> {
-		await this.#json('POST', '/api/sandbox/sessions/eject', {
-			sessionId,
-			metadata,
-		});
-	}
-
-	/* The read-only data bridge. A preview screen asks the sandbox for a path
-	   the draft module does not own, and the sandbox forwards it to the real
-	   application under the connected account's own authorization. */
-	async bridge(request: BridgeRequest): Promise<BridgeResponse> {
-		if (request.method !== 'GET' && request.method !== 'HEAD') {
-			return {
-				status: 405,
-				contentType: 'application/json',
-				body: JSON.stringify({
-					error: {
-						code: 'BRIDGE_READ_ONLY',
-						message:
-							'The preview data bridge forwards read requests only. Mutations must run against the real application.',
-					},
-				}),
-			};
-		}
-		const response = await this.#request(
-			request.method,
-			`${request.path}${request.search}`,
-			undefined,
-			request.accept,
-		);
-		const text = await response.text();
-		return {
-			status: response.status,
-			contentType: response.headers.get('content-type') ?? 'application/json',
-			body:
-				text.length > BRIDGE_BODY_LIMIT
-					? JSON.stringify({
-							error: {
-								code: 'BRIDGE_RESPONSE_TOO_LARGE',
-								message: 'The bridged response exceeded the sandbox limit.',
-							},
-						})
-					: text,
-		};
-	}
-
-	async #json(method: string, path: string, body: unknown): Promise<Response> {
-		const response = await this.#request(method, path, body);
-		if (!response.ok) {
-			const payload = (await response.json().catch(() => ({}))) as {
-				error?: { message?: string };
-			};
-			throw new SandboxSetupError(
-				'PLATFORM_REQUEST_FAILED',
-				payload.error?.message ??
-					`The platform answered ${response.status} for ${path}.`,
-			);
-		}
-		return response;
-	}
-
-	#request(
-		method: string,
-		path: string,
-		body?: unknown,
-		accept: string | null = 'application/json',
-	): Promise<Response> {
-		return this.#fetch(`${this.#platformUrl}${path}`, {
-			method,
-			headers: {
-				authorization: `Bearer ${this.#token}`,
-				...(accept ? { accept } : {}),
-				...(body === undefined ? {} : { 'content-type': 'application/json' }),
-			},
-			...(body === undefined ? {} : { body: JSON.stringify(body) }),
-			signal: AbortSignal.timeout(BRIDGE_TIMEOUT_MS),
-		});
-	}
-}

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

@@ -1,340 +0,0 @@
-import {
-	DatabaseError,
-	type DatabaseAdapterLease,
-	type DatabaseCapabilities,
-	type DatabaseOperationOptions,
-	type DatabaseProvider,
-	type DatabaseSession,
-	type DatabaseTransaction,
-	type DatabaseTransactionOptions,
-} from '@flowdular/sdk/database';
-import {
-	isPreviewDatabaseRequest,
-	previewDatabaseError,
-	previewDatabaseFailure,
-	PREVIEW_DATABASE_REPLY,
-	type PreviewDatabaseCall,
-	type PreviewDatabaseGrant,
-	type PreviewDatabaseLeaseRequest,
-	type PreviewDatabaseReply,
-	type PreviewDatabaseTarget,
-	type PreviewDatabaseTransactionOptions,
-} from './preview-database-protocol.ts';
-
-export interface PreviewDatabaseHostOptions {
-	/** Opens the session engine on the first lease. Never called after close. */
-	open(): Promise<DatabaseProvider>;
-	send(reply: PreviewDatabaseReply): void;
-}
-
-export interface PreviewDatabaseHost {
-	/** True when the message belonged to the preview database protocol. */
-	accept(message: unknown): boolean;
-	/** Idempotent. Rolls every open transaction back, then closes the engine. */
-	close(): Promise<void>;
-}
-
-interface OpenTransaction {
-	/** The pinned session once BEGIN landed. Rejects when it never did. */
-	readonly session: Promise<DatabaseTransaction>;
-	/** Serialises every operation and the commit. Never rejects. */
-	gate: Promise<void>;
-	settle(error: Error | null): void;
-	readonly finished: Promise<void>;
-}
-
-function withoutDialectSql(
-	capabilities: DatabaseCapabilities,
-): PreviewDatabaseGrant['capabilities'] {
-	const { sql: _dialectSql, ...serializable } = capabilities;
-	return serializable;
-}
-
-function operationOptions(call: {
-	readonly timeoutMs?: number;
-}): DatabaseOperationOptions {
-	return call.timeoutMs === undefined ? {} : { timeoutMs: call.timeoutMs };
-}
-
-function transactionOptions(
-	options: PreviewDatabaseTransactionOptions,
-): DatabaseTransactionOptions {
-	return {
-		...(options.access === undefined ? {} : { access: options.access }),
-		...(options.isolation === undefined
-			? {}
-			: { isolation: options.isolation }),
-		...(options.tenantId === undefined ? {} : { tenantId: options.tenantId }),
-		...operationOptions(options),
-	};
-}
-
-/**
- * Serves the preview worker's database calls against the real session engine.
- * The worker holds the contract; this side holds the connections, so every
- * transaction it opens is this side's to commit, roll back, or reclaim when the
- * worker dies.
- */
-export function createPreviewDatabaseHost(
-	options: PreviewDatabaseHostOptions,
-): PreviewDatabaseHost {
-	const leases = new Map<number, DatabaseAdapterLease>();
-	const transactions = new Map<number, OpenTransaction>();
-	let provider: Promise<DatabaseProvider> | undefined;
-	let closing: Promise<void> | undefined;
-
-	const send = (reply: PreviewDatabaseReply) => {
-		try {
-			options.send(reply);
-		} catch {
-			/* The worker went away between its request and this reply. */
-		}
-	};
-
-	async function grant(
-		lease: number,
-		request: PreviewDatabaseLeaseRequest,
-	): Promise<PreviewDatabaseGrant> {
-		provider ??= options.open();
-		const acquired = await (await provider).acquire(request);
-		if (closing) {
-			await acquired.release();
-			throw new DatabaseError(
-				'ADAPTER_DISPOSED',
-				'The preview database host is closed.',
-			);
-		}
-		leases.set(lease, acquired);
-		return {
-			adapterId: acquired.database.adapterId,
-			dialectId: acquired.database.dialectId,
-			capabilities: withoutDialectSql(acquired.database.capabilities),
-		};
-	}
-
-	/* One parent connection is pinned to a transaction, and the worker may
-	   abandon a statement whose deadline fired, so the next statement and the
-	   commit both wait for the one still in flight. */
-	function within<T>(
-		id: number,
-		run: (transaction: DatabaseTransaction) => Promise<T>,
-	): Promise<T> {
-		const entry = transactions.get(id);
-		if (!entry) {
-			throw new DatabaseError(
-				'TRANSACTION_CONTEXT_MISUSE',
-				'The preview database transaction has already ended.',
-			);
-		}
-		const result = entry.gate.then(() => entry.session).then(run);
-		entry.gate = result.then(
-			() => undefined,
-			() => undefined,
-		);
-		return result;
-	}
-
-	function onTarget<T>(
-		target: PreviewDatabaseTarget,
-		run: (session: DatabaseSession) => Promise<T>,
-	): Promise<T> {
-		if (target.transaction !== undefined)
-			return within(target.transaction, run);
-		const lease = leases.get(target.lease);
-		if (!lease) {
-			throw new DatabaseError(
-				'ADAPTER_DISPOSED',
-				'The preview database lease was released.',
-			);
-		}
-		return run(lease.database);
-	}
-
-	async function begin(
-		lease: number,
-		id: number,
-		wanted: PreviewDatabaseTransactionOptions,
-	): Promise<undefined> {
-		const held = leases.get(lease);
-		if (!held) {
-			throw new DatabaseError(
-				'ADAPTER_DISPOSED',
-				'The preview database lease was released.',
-			);
-		}
-		let ready!: (transaction: DatabaseTransaction) => void;
-		const pinned = new Promise<DatabaseTransaction>((resolve) => {
-			ready = resolve;
-		});
-		let settle!: (error: Error | null) => void;
-		const body = new Promise<void>((resolve, reject) => {
-			settle = (error) => (error ? reject(error) : resolve());
-		});
-		/* A begin that fails leaves nobody inside the callback to observe this. */
-		void body.catch(() => undefined);
-		const finished = held.database.transaction(async (transaction) => {
-			ready(transaction);
-			await body;
-		}, transactionOptions(wanted));
-		/* BEGIN, the tenant context statement, or the options themselves can fail
-		   before the callback runs. The gate must then reject rather than leave a
-		   settle request waiting forever. */
-		const session = Promise.race([
-			pinned,
-			finished.then(
-				() => {
-					throw new DatabaseError(
-						'TRANSACTION_CONTEXT_MISUSE',
-						'The preview database transaction ended before it began.',
-					);
-				},
-				(error: unknown) => {
-					throw error;
-				},
-			),
-		]);
-		const entry: OpenTransaction = {
-			session,
-			gate: session.then(
-				() => undefined,
-				() => undefined,
-			),
-			settle,
-			finished,
-		};
-		transactions.set(id, entry);
-		try {
-			await session;
-		} catch (error) {
-			transactions.delete(id);
-			throw error;
-		}
-		return undefined;
-	}
-
-	async function end(id: number, failure: Error | null): Promise<undefined> {
-		const entry = transactions.get(id);
-		/* An unknown token is the worker cleaning up a begin it never received. */
-		if (!entry) return undefined;
-		transactions.delete(id);
-		const done = entry.gate.then(() => {
-			entry.settle(failure);
-			return entry.finished;
-		});
-		entry.gate = done.then(
-			() => undefined,
-			() => undefined,
-		);
-		try {
-			await done;
-		} catch (error) {
-			/* A rollback the worker asked for rethrows the failure it already owns. */
-			if (!failure) throw error;
-		}
-		return undefined;
-	}
-
-	async function perform(call: PreviewDatabaseCall): Promise<unknown> {
-		if (closing) {
-			throw new DatabaseError(
-				'ADAPTER_DISPOSED',
-				'The preview database host is closed.',
-			);
-		}
-		switch (call.kind) {
-			case 'acquire':
-				return await grant(call.lease, call.request);
-			case 'release': {
-				const lease = leases.get(call.lease);
-				leases.delete(call.lease);
-				await lease?.release();
-				return undefined;
-			}
-			case 'begin':
-				return await begin(call.lease, call.transaction, call.options);
-			case 'settle':
-				return await end(
-					call.transaction,
-					call.error ? previewDatabaseError(call.error) : null,
-				);
-			case 'migration-lock':
-				return await within(call.transaction, (transaction) =>
-					transaction.acquireMigrationLock(call.namespace),
-				);
-			case 'query':
-				return await onTarget(call.target, (session) =>
-					session.query(call.statement, operationOptions(call)),
-				);
-			case 'execute':
-				return await onTarget(call.target, (session) =>
-					session.execute(call.statement, operationOptions(call)),
-				);
-			case 'script':
-				return await onTarget(call.target, (session) =>
-					session.executeScript(call.script, operationOptions(call)),
-				);
-			case 'has-table':
-				return await onTarget(call.target, (session) =>
-					session.schema.hasTable(call.name, operationOptions(call)),
-				);
-			case 'has-index':
-				return await onTarget(call.target, (session) =>
-					session.schema.hasIndex(call.name, operationOptions(call)),
-				);
-			case 'has-column':
-				return await onTarget(call.target, (session) =>
-					session.schema.hasColumn(
-						call.table,
-						call.column,
-						operationOptions(call),
-					),
-				);
-		}
-	}
-
-	return {
-		accept(message: unknown): boolean {
-			if (!isPreviewDatabaseRequest(message)) return false;
-			const id = message.id;
-			void perform(message.call).then(
-				(value) => send({ type: PREVIEW_DATABASE_REPLY, id, ok: true, value }),
-				(error: unknown) =>
-					send({
-						type: PREVIEW_DATABASE_REPLY,
-						id,
-						ok: false,
-						error: previewDatabaseFailure(error),
-					}),
-			);
-			return true;
-		},
-		close(): Promise<void> {
-			closing ??= (async () => {
-				const open = [...transactions.values()];
-				transactions.clear();
-				const reason = new DatabaseError(
-					'ADAPTER_DISPOSED',
-					'The preview worker stopped while the transaction was open.',
-				);
-				await Promise.allSettled(
-					open.map((entry) =>
-						entry.gate.then(() => {
-							entry.settle(reason);
-							return entry.finished;
-						}),
-					),
-				);
-				await Promise.allSettled(
-					[...leases.values()].map((lease) => lease.release()),
-				);
-				leases.clear();
-				const opened = provider;
-				provider = undefined;
-				if (!opened) return;
-				const engine = await opened.catch(() => undefined);
-				await engine?.dispose();
-			})();
-			return closing;
-		},
-	};
-}

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

@@ -1,163 +0,0 @@
-import {
-	DatabaseError,
-	type DatabaseCapabilities,
-	type DatabaseErrorCode,
-	type DatabaseIsolationLevel,
-	type DatabaseProviderRequest,
-	type DatabaseRequirements,
-	type DatabaseStatement,
-} from '@flowdular/sdk/database';
-
-/* The preview worker runs under Node's permission model, which denies
-   process.binding unconditionally, and the embedded PostgreSQL build needs it.
-   So the engine stays in the sandbox process and the worker drives it over the
-   IPC channel it already owns. Only structured-clone values cross that channel:
-   no AbortSignal, no capability functions, no Error instances. */
-
-export const PREVIEW_DATABASE_REQUEST = 'flowdular.preview-database.request';
-export const PREVIEW_DATABASE_REPLY = 'flowdular.preview-database.reply';
-
-/** Static lease metadata, sent once when the lease is granted. */
-export interface PreviewDatabaseGrant {
-	readonly adapterId: string;
-	readonly dialectId: string;
-	/** The dialect-owned `sql` functions are rebuilt from `dialectId`. */
-	readonly capabilities: Omit<DatabaseCapabilities, 'sql'>;
-}
-
-export interface PreviewDatabaseLeaseRequest {
-	readonly namespace: string;
-	readonly purpose: DatabaseProviderRequest['purpose'];
-	readonly requirements?: DatabaseRequirements;
-	readonly timeoutMs?: number;
-}
-
-export interface PreviewDatabaseTransactionOptions {
-	readonly access?: 'read' | 'write';
-	readonly isolation?: DatabaseIsolationLevel;
-	readonly tenantId?: string;
-	readonly timeoutMs?: number;
-}
-
-/** Names the parent-side connection an operation runs on. */
-export interface PreviewDatabaseTarget {
-	readonly lease: number;
-	/** Set for a statement issued inside a transaction callback. */
-	readonly transaction?: number;
-}
-
-interface PreviewDatabaseOperation {
-	readonly target: PreviewDatabaseTarget;
-	readonly timeoutMs?: number;
-}
-
-export type PreviewDatabaseCall =
-	| {
-			readonly kind: 'acquire';
-			readonly lease: number;
-			readonly request: PreviewDatabaseLeaseRequest;
-	  }
-	| { readonly kind: 'release'; readonly lease: number }
-	| {
-			readonly kind: 'begin';
-			readonly lease: number;
-			readonly transaction: number;
-			readonly options: PreviewDatabaseTransactionOptions;
-	  }
-	| {
-			readonly kind: 'settle';
-			readonly transaction: number;
-			/** Null commits. Anything else rolls back with that failure. */
-			readonly error: PreviewDatabaseFailure | null;
-	  }
-	| {
-			readonly kind: 'migration-lock';
-			readonly transaction: number;
-			readonly namespace: string;
-	  }
-	| (PreviewDatabaseOperation & {
-			readonly kind: 'query' | 'execute';
-			readonly statement: DatabaseStatement;
-	  })
-	| (PreviewDatabaseOperation & {
-			readonly kind: 'script';
-			readonly script: string;
-	  })
-	| (PreviewDatabaseOperation & {
-			readonly kind: 'has-table' | 'has-index';
-			readonly name: string;
-	  })
-	| (PreviewDatabaseOperation & {
-			readonly kind: 'has-column';
-			readonly table: string;
-			readonly column: string;
-	  });
-
-export interface PreviewDatabaseRequest {
-	readonly type: typeof PREVIEW_DATABASE_REQUEST;
-	readonly id: number;
-	readonly call: PreviewDatabaseCall;
-}
-
-export interface PreviewDatabaseFailure {
-	readonly name: string;
-	readonly message: string;
-	readonly code?: string;
-	readonly stack?: string;
-}
-
-export type PreviewDatabaseReply = {
-	readonly type: typeof PREVIEW_DATABASE_REPLY;
-	readonly id: number;
-} & (
-	| { readonly ok: true; readonly value: unknown }
-	| { readonly ok: false; readonly error: PreviewDatabaseFailure }
-);
-
-export function isPreviewDatabaseRequest(
-	message: unknown,
-): message is PreviewDatabaseRequest {
-	return (
-		typeof message === 'object' &&
-		message !== null &&
-		(message as PreviewDatabaseRequest).type === PREVIEW_DATABASE_REQUEST
-	);
-}
-
-export function isPreviewDatabaseReply(
-	message: unknown,
-): message is PreviewDatabaseReply {
-	return (
-		typeof message === 'object' &&
-		message !== null &&
-		(message as PreviewDatabaseReply).type === PREVIEW_DATABASE_REPLY
-	);
-}
-
-/* Module code and the platform suites branch on DatabaseError.code and on the
-   driver's own SQLSTATE, and neither survives structured cloning of an Error.
-   Both travel as data and are put back together on the far side. */
-export function previewDatabaseFailure(error: unknown): PreviewDatabaseFailure {
-	if (!(error instanceof Error)) {
-		return { name: 'Error', message: String(error) };
-	}
-	const code = (error as { readonly code?: unknown }).code;
-	return {
-		name: error.name,
-		message: error.message,
-		...(typeof code === 'string' ? { code } : {}),
-		...(typeof error.stack === 'string' ? { stack: error.stack } : {}),
-	};
-}
-
-export function previewDatabaseError(failure: PreviewDatabaseFailure): Error {
-	const error =
-		failure.name === 'DatabaseError' && failure.code !== undefined
-			? new DatabaseError(failure.code as DatabaseErrorCode, failure.message)
-			: Object.assign(new Error(failure.message), {
-					name: failure.name,
-					...(failure.code === undefined ? {} : { code: failure.code }),
-				});
-	if (failure.stack !== undefined) error.stack = failure.stack;
-	return error;
-}