create-flowdular 0.5.1 → 0.6.0

package/template/default/platform/src/server/setup/gate.ts

@@ -0,0 +1,84 @@
+import { ServerRoute, type Context, type Middleware } from '@octanejs/app-core';
+
+export interface FirstRunGate {
+	/** Runs ahead of authentication. Until a workspace exists it answers every
+	 *  request itself, except the pass-through paths. */
+	readonly middleware: Middleware;
+	/** Global middleware runs only for a matched route, so /setup needs one. */
+	readonly routes: readonly ServerRoute[];
+}
+
+export interface FirstRunGateOptions {
+	readonly applicationPath: string;
+	/** Served normally before the first workspace exists, such as /api/ready. */
+	readonly passThrough: readonly string[];
+	readonly workspaceExists: () => Promise<boolean>;
+	/** Builds the /setup handler. `claimed` opens this instance at once. */
+	readonly setup: (
+		claimed: () => void,
+	) => (context: Context) => Promise<Response>;
+}
+
+function redirect(location: string): Response {
+	return new Response(null, {
+		status: 303,
+		headers: { location, 'cache-control': 'no-store' },
+	});
+}
+
+export function createFirstRunGate(options: FirstRunGateOptions): FirstRunGate {
+	let open = false;
+	let checking: Promise<boolean> | null = null;
+	const setup = options.setup(() => {
+		open = true;
+	});
+	/* Asked on every request until it first answers yes, so an instance that
+	   did not run setup itself opens on its next request after another did.
+	   Concurrent requests share one query; a failed one keeps the gate shut. */
+	const workspaceExists = (): Promise<boolean> =>
+		(checking ??= options.workspaceExists().then(
+			(exists) => {
+				checking = null;
+				if (exists) open = true;
+				return exists;
+			},
+			() => {
+				checking = null;
+				return false;
+			},
+		));
+	const middleware: Middleware = async (context, next) => {
+		if (open || (await workspaceExists())) return next();
+		const { pathname } = context.url;
+		if (pathname === '/setup') return setup(context);
+		if (options.passThrough.includes(pathname)) return next();
+		const method = context.request.method;
+		if (
+			(method === 'GET' || method === 'HEAD') &&
+			pathname !== '/api' &&
+			!pathname.startsWith('/api/')
+		) {
+			return redirect('/setup');
+		}
+		return Response.json(
+			{
+				error: {
+					code: 'PLATFORM_NOT_CONFIGURED',
+					message:
+						'Complete the first-run setup at /setup before using the platform.',
+				},
+			},
+			{ status: 503, headers: { 'cache-control': 'no-store' } },
+		);
+	};
+	return {
+		middleware,
+		routes: [
+			new ServerRoute({
+				path: '/setup',
+				methods: ['GET', 'POST'],
+				handler: () => redirect(options.applicationPath),
+			}),
+		],
+	};
+}

package/template/default/platform/src/server/setup/index.ts

@@ -0,0 +1,181 @@
+import process from 'node:process';
+import type { ServerRoute } from '@octanejs/app-core';
+import {
+	authRuntimeOptionsFromEnvironment,
+	createAuthRuntime,
+} from '@flowdular/sdk/modules/auth/server';
+import {
+	createPlatformDatabaseProvider,
+	databaseProviderConfigFromEnvironment,
+} from '../database.ts';
+import { createSetupAccess } from './access.ts';
+import { createSetupAdapters } from './adapters.ts';
+import { createFirstRunGate, type FirstRunGate } from './gate.ts';
+import { enabledDatabaseModules } from './modules.ts';
+import { createSetupHandler, createSetupRoutes } from './routes.ts';
+import { issueSetupToken } from './token.ts';
+
+export { clearSetupToken } from './token.ts';
+
+const FIRST_RUN_SYMBOL = Symbol.for('flowdular.platform.first-run-setup');
+
+export interface FirstRunSetup {
+	readonly routes: readonly ServerRoute[];
+	readonly token: string;
+	readonly tokenFile: string | null;
+}
+
+export interface FirstRunSetupOptions {
+	readonly environment: NodeJS.ProcessEnv;
+	readonly workspaceRoot: string;
+	readonly databasePreconfigured?: boolean;
+	readonly applicationPath?: string;
+	readonly webMountPaths?: readonly string[];
+	readonly log?: (message: string) => void;
+}
+
+/** A reachable, empty configured database still needs its first owner.
+ * Auth's normal migration path is used before the read, and an outage throws
+ * rather than accidentally opening setup against an existing installation.
+ */
+export async function configuredDatabaseNeedsFirstRun(
+	environment: NodeJS.ProcessEnv,
+	workspaceRoot: string,
+): Promise<boolean> {
+	const databases = createPlatformDatabaseProvider(
+		databaseProviderConfigFromEnvironment(environment, workspaceRoot),
+	);
+	try {
+		await databases.check();
+		const auth = createAuthRuntime({
+			...authRuntimeOptionsFromEnvironment(environment, workspaceRoot),
+			databases,
+		});
+		try {
+			return !(await (await auth.service()).hasAnyTenant());
+		} finally {
+			await auth.dispose();
+		}
+	} finally {
+		await databases.dispose();
+	}
+}
+
+type ProcessWithSetup = NodeJS.Process & {
+	[FIRST_RUN_SYMBOL]?: FirstRunSetup;
+};
+
+function origin(environment: NodeJS.ProcessEnv): string {
+	const configured = environment.FD_AUTH_PUBLIC_ORIGIN?.trim();
+	if (configured) return configured.replace(/\/+$/, '');
+	return `http://127.0.0.1:${environment.PORT?.trim() || '4310'}`;
+}
+
+/**
+ * The routes a deployment serves while it has no database. Held on the process
+ * so a development re-evaluation of the configuration keeps the token, the
+ * lockout counter, and the operator's half-finished session alive; a
+ * production process evaluates the configuration once, so this is a plain
+ * construction there.
+ */
+export function createFirstRunSetup(
+	options: FirstRunSetupOptions,
+): FirstRunSetup {
+	const owner = process as ProcessWithSetup;
+	const existing = owner[FIRST_RUN_SYMBOL];
+	if (existing) return existing;
+	const production = options.environment.NODE_ENV === 'production';
+	const issued = issueSetupToken({
+		workspaceRoot: options.workspaceRoot,
+		origin: origin(options.environment),
+	});
+	const adapters = createSetupAdapters({
+		workspaceRoot: options.workspaceRoot,
+		production,
+	});
+	const enabled = enabledDatabaseModules(options.workspaceRoot);
+	const setup: FirstRunSetup = {
+		token: issued.token,
+		tokenFile: issued.file,
+		routes: createSetupRoutes({
+			environment: options.environment,
+			databasePreconfigured: options.databasePreconfigured ?? false,
+			defaultApplicationPath: options.applicationPath ?? '/app',
+			webMountPaths: options.webMountPaths ?? [],
+			workspaceRoot: options.workspaceRoot,
+			adapters,
+			access: createSetupAccess(issued.token),
+			modules: enabled.modules,
+			modulesApproximated: enabled.approximated,
+			tokenFile: issued.file,
+			secureCookies:
+				options.environment.FD_AUTH_SECURE_COOKIE === 'false'
+					? false
+					: production,
+		}),
+	};
+	owner[FIRST_RUN_SYMBOL] = setup;
+	(options.log ?? console.log)(issued.banner);
+	return setup;
+}
+
+export interface InPlaceFirstRunOptions {
+	readonly environment: NodeJS.ProcessEnv;
+	readonly workspaceRoot: string;
+	readonly applicationPath: string;
+	readonly webMountPaths: readonly string[];
+	readonly passThrough: readonly string[];
+	readonly workspaceExists: () => Promise<boolean>;
+	readonly log?: (message: string) => void;
+}
+
+/**
+ * First run for a deployment that can neither restart itself nor write files,
+ * such as a Vercel Function: the composed application serves setup behind a
+ * gate until a workspace exists. The deploy command keeps the token and the
+ * deployment holds only its SHA-256, so nothing is issued or written here.
+ */
+export function createInPlaceFirstRun(
+	options: InPlaceFirstRunOptions,
+): FirstRunGate {
+	const digest = options.environment.FD_SETUP_TOKEN_SHA256?.trim();
+	if (!digest) {
+		throw new Error(
+			'The database has no workspace yet and FD_SETUP_TOKEN_SHA256 is not set. Run flowdular deploy start vercel --apply, which sets it and prints the setup token.',
+		);
+	}
+	const access = createSetupAccess({ sha256: digest });
+	const production = options.environment.NODE_ENV === 'production';
+	const adapters = createSetupAdapters({
+		workspaceRoot: options.workspaceRoot,
+		production,
+	});
+	const enabled = enabledDatabaseModules(options.workspaceRoot);
+	const gate = createFirstRunGate({
+		applicationPath: options.applicationPath,
+		passThrough: options.passThrough,
+		workspaceExists: options.workspaceExists,
+		setup: (claimed) =>
+			createSetupHandler({
+				environment: options.environment,
+				databasePreconfigured: true,
+				defaultApplicationPath: options.applicationPath,
+				webMountPaths: options.webMountPaths,
+				workspaceRoot: options.workspaceRoot,
+				adapters,
+				access,
+				modules: enabled.modules,
+				modulesApproximated: enabled.approximated,
+				tokenFile: null,
+				secureCookies:
+					options.environment.FD_AUTH_SECURE_COOKIE === 'false'
+						? false
+						: production,
+				inPlace: { onClaimed: claimed },
+			}),
+	});
+	(options.log ?? console.log)(
+		'No workspace exists yet. Open /setup and enter the setup token the deploy command printed.',
+	);
+	return gate;
+}

package/template/default/platform/src/server/setup/modules.ts

@@ -0,0 +1,123 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import {
+	DATABASE_CAPABILITY_IDS,
+	DATABASE_DIALECT_IDS,
+	type ModuleDatabaseRequirements,
+} from '@flowdular/sdk/database';
+import projectManifest from '../../../../flowdular.json';
+
+/**
+ * What every database-owning module in this repository asks its lease for. The
+ * module manifest carries no machine-readable database block yet, so the
+ * platform applies the strictest set any enabled module requests rather than
+ * guessing a looser one per module. The precise fix is a `database` block in
+ * packages/contracts/schemas/module.schema.json that each module fills in.
+ */
+export const PLATFORM_MODULE_DATABASE_REQUIREMENTS = Object.freeze({
+	dialectIds: Object.freeze([DATABASE_DIALECT_IDS.postgresql]),
+	capabilities: Object.freeze([
+		DATABASE_CAPABILITY_IDS.MIGRATION_LOCK,
+		DATABASE_CAPABILITY_IDS.SCHEMA_INTROSPECTION,
+		DATABASE_CAPABILITY_IDS.TRANSACTIONAL_DDL,
+		DATABASE_CAPABILITY_IDS.TRANSACTIONS,
+	]),
+});
+
+export interface EnabledDatabaseModules {
+	readonly modules: readonly ModuleDatabaseRequirements[];
+	/**
+	 * True when the module manifests could not be read, so every enabled module
+	 * is treated as owning tenant-scoped tables. Over-approximating keeps the
+	 * check strict; the review screen says the list came from this fallback.
+	 */
+	readonly approximated: boolean;
+}
+
+interface ModuleManifest {
+	readonly id?: unknown;
+	readonly capabilities?: unknown;
+	readonly tenancy?: unknown;
+}
+
+interface ProjectManifest {
+	readonly modules?: {
+		readonly roots?: unknown;
+		readonly enabled?: unknown;
+	};
+}
+
+function readJson<T>(path: string): T | null {
+	try {
+		return JSON.parse(readFileSync(path, 'utf8')) as T;
+	} catch {
+		return null;
+	}
+}
+
+function stringList(value: unknown): readonly string[] {
+	return Array.isArray(value)
+		? value.filter((entry): entry is string => typeof entry === 'string')
+		: [];
+}
+
+function requirements(
+	moduleId: string,
+	tenantOwned: boolean,
+): ModuleDatabaseRequirements {
+	return {
+		moduleId,
+		tenantOwned,
+		dialectIds: PLATFORM_MODULE_DATABASE_REQUIREMENTS.dialectIds,
+		capabilities: PLATFORM_MODULE_DATABASE_REQUIREMENTS.capabilities,
+	};
+}
+
+/**
+ * The enabled modules that own database tables, in `flowdular.json` order.
+ * A container image ships only `platform/dist`, so the enabled list falls back
+ * to the manifest bundled at build time and, without the module manifests
+ * beside it, every enabled module is assumed to own tenant-scoped tables.
+ */
+export function enabledDatabaseModules(
+	workspaceRoot: string,
+): EnabledDatabaseModules {
+	const project =
+		readJson<ProjectManifest>(resolve(workspaceRoot, 'flowdular.json')) ??
+		(projectManifest as ProjectManifest);
+	const enabled = stringList(project.modules?.enabled);
+	if (enabled.length === 0) return { modules: [], approximated: false };
+	const roots = stringList(project.modules?.roots);
+	const manifests = new Map<string, ModuleManifest>();
+	for (const root of roots.length > 0 ? roots : ['modules']) {
+		const directory = resolve(workspaceRoot, root);
+		let entries: readonly string[];
+		try {
+			entries = readdirSync(directory);
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			const manifest = readJson<ModuleManifest>(
+				join(directory, entry, 'module.json'),
+			);
+			if (typeof manifest?.id === 'string') {
+				manifests.set(manifest.id, manifest);
+			}
+		}
+	}
+	if (manifests.size === 0) {
+		return {
+			modules: enabled.map((moduleId) => requirements(moduleId, true)),
+			approximated: true,
+		};
+	}
+	const modules: ModuleDatabaseRequirements[] = [];
+	for (const moduleId of enabled) {
+		const manifest = manifests.get(moduleId);
+		if (!manifest) continue;
+		if (!stringList(manifest.capabilities).includes('database')) continue;
+		modules.push(requirements(moduleId, manifest.tenancy === 'required'));
+	}
+	return { modules, approximated: false };
+}