@flowdular/sdk 0.3.0 → 0.3.2

package/modules/system/src/platform.ts

@@ -2,14 +2,54 @@ import type {
 	PlatformServerComposition,
 	PlatformServerContext,
 } from '@flowdular/sdk/modules/auth/server';
+import { installModuleActivationGate } from '@flowdular/sdk/server';
+import {
+	composedModules,
+	SYSTEM_MODULES_CAPABILITY,
+	type ComposedModule,
+} from './domain/modules.ts';
 import { createSystemRoutes } from './server/endpoints.ts';
+import { readModuleCatalog } from './server/module-catalog.ts';
+import { createSystemRuntime } from './server/runtime.ts';
+import type { SystemModulesCapability } from './server/capability.ts';
 import { SYSTEM_MODULE_SETTINGS } from './settings.ts';
 
 export function createServerComposition(
 	context: PlatformServerContext,
 ): PlatformServerComposition {
+	/* The composed set is baked at build, so the manifests are read once per
+	   composition, which in development is once per reload. */
+	let composed: readonly ComposedModule[] | null = null;
+	const modules = () =>
+		(composed ??= composedModules(
+			readModuleCatalog(context.workspaceRoot).filter((entry) => entry.enabled),
+		));
+	const runtime = createSystemRuntime({
+		databases: context.databases,
+		purpose:
+			context.environment.NODE_ENV === 'test'
+				? 'test'
+				: context.environment.NODE_ENV === 'production'
+					? 'runtime'
+					: 'preview',
+		modules,
+		audit: async (actor, change) =>
+			(await context.auth.service()).recordModuleActivation(actor, change),
+	});
+	const capability: SystemModulesCapability = {
+		isActive: async (tenantId, moduleId) =>
+			(await runtime.service()).isActive(tenantId, moduleId),
+		activeIds: async (tenantId) =>
+			(await runtime.service()).activeIds(tenantId),
+	};
+	context.capabilities.register(SYSTEM_MODULES_CAPABILITY, capability);
+	installModuleActivationGate(capability);
 	return {
-		routes: createSystemRoutes(context),
+		routes: createSystemRoutes({ ...context, activation: runtime }),
 		settings: SYSTEM_MODULE_SETTINGS,
+		dispose: async () => {
+			installModuleActivationGate(null);
+			await runtime.dispose();
+		},
 	};
 }

package/modules/system/src/server/capability.ts

@@ -0,0 +1,6 @@
+/** `system.modules.v1`: which composed modules are active in a workspace. */
+export interface SystemModulesCapability {
+	isActive(tenantId: string, moduleId: string): Promise<boolean>;
+	/** Sorted ids of the composed modules active in the workspace. */
+	activeIds(tenantId: string): Promise<readonly string[]>;
+}

package/modules/system/src/server/endpoints.ts

@@ -26,12 +26,57 @@ import {
 	SYSTEM_MODULE_ID,
 	TENANT_TIME_ZONE_KEY,
 } from '../domain/time-zone.ts';
-import { readModuleCatalog } from './module-catalog.ts';
+import type { ModuleActivationEntry } from '../domain/modules.ts';
+import { ModuleActivationError } from '../services/module-activation-service.ts';
+import {
+	readModuleCatalog,
+	type ModuleCatalogEntry,
+} from './module-catalog.ts';
+import type { SystemRuntime } from './runtime.ts';
 
 export interface SystemRouteOptions {
 	readonly workspaceRoot: string;
 	readonly auth: AuthRuntime;
 	readonly settings: ModuleSettingsRuntime;
+	/** Per-workspace activation of the composed modules. */
+	readonly activation: SystemRuntime;
+}
+
+/** A catalog row with its activation in the asking principal's workspace. */
+export interface ModuleCatalogPayload extends ModuleCatalogEntry {
+	readonly active: boolean;
+	readonly optional: boolean;
+	readonly dependents: readonly string[];
+}
+
+/* A module the workspace holds but the application does not compose has no
+   activation to speak of: it is listed as available and never active. */
+function catalogPayload(
+	entry: ModuleCatalogEntry,
+	activation: ModuleActivationEntry | undefined,
+): ModuleCatalogPayload {
+	return {
+		...entry,
+		active: activation?.active ?? false,
+		optional: activation?.optional ?? true,
+		dependents: activation?.dependents ?? [],
+	};
+}
+
+function activationProblem(error: unknown): Response {
+	if (error instanceof ModuleActivationError) {
+		return jsonResponse(
+			{
+				error: {
+					code: error.code,
+					message: error.message,
+					modules: error.modules,
+				},
+			},
+			error.status,
+		);
+	}
+	return problemResponse(error, 'The module activation request failed.');
 }
 
 const MAIL_TRANSPORT_REQUIRED =
@@ -236,8 +281,9 @@ async function readActivity(
 	return keys.map((date) => ({ date, count: counts.get(date) ?? 0 }));
 }
 
-/* Metadata only: manifests and specifications from the workspace. Enabling or
-   disabling a module stays a CLI operation with its own approval trail. */
+/* Manifests and specifications from the workspace, with the per-workspace
+   activation of the composed ones. Enabling or disabling a module stays a CLI
+   operation with its own approval trail. */
 export function createSystemRoutes(options: SystemRouteOptions) {
 	const modules = defineEndpoint({
 		id: 'system.modules.list',
@@ -245,10 +291,18 @@ export function createSystemRoutes(options: SystemRouteOptions) {
 		methods: ['GET'],
 		access: { kind: 'permission', permission: SYSTEM_PERMISSIONS.modulesRead },
 		resolveIdentity: endpointIdentityFromContext,
-		handler: () => {
+		handler: async ({ octane }) => {
 			try {
+				const principal = principalFromContext(octane)!;
+				const activations = new Map(
+					(
+						await (await options.activation.service()).list(principal.tenantId)
+					).map((entry) => [entry.id, entry]),
+				);
 				return jsonResponse({
-					modules: readModuleCatalog(options.workspaceRoot),
+					modules: readModuleCatalog(options.workspaceRoot).map((entry) =>
+						catalogPayload(entry, activations.get(entry.id)),
+					),
 					commands: {
 						enable: 'pnpm flowdular module enable <id> --apply',
 						disable: 'pnpm flowdular module disable <id> --apply',
@@ -263,6 +317,66 @@ export function createSystemRoutes(options: SystemRouteOptions) {
 		},
 	});
 
+	const activeModules = defineEndpoint({
+		id: 'system.modules.active',
+		path: '/api/system/modules/active',
+		methods: ['GET'],
+		access: {
+			kind: 'permission',
+			permission: SYSTEM_PERMISSIONS.workspaceAccess,
+		},
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			try {
+				const principal = principalFromContext(octane)!;
+				const service = await options.activation.service();
+				return jsonResponse({
+					modules: await service.activeIds(principal.tenantId),
+				});
+			} catch (error) {
+				return activationProblem(error);
+			}
+		},
+	});
+
+	const activation = (id: string, path: string, active: boolean) =>
+		defineEndpoint({
+			id,
+			path,
+			methods: ['POST'],
+			access: {
+				kind: 'permission',
+				permission: SYSTEM_PERMISSIONS.settingsManage,
+			},
+			resolveIdentity: endpointIdentityFromContext,
+			handler: async ({ octane }) => {
+				const denial = sessionMutationDenial(octane, options.auth);
+				if (denial) return denial;
+				try {
+					const principal = principalFromContext(octane)!;
+					const body = await readJsonObject(octane.request);
+					const moduleId = requiredString(body, 'moduleId', { max: 128 });
+					const service = await options.activation.service();
+					const entry = active
+						? await service.activate(principal, moduleId)
+						: await service.deactivate(principal, moduleId);
+					return jsonResponse({ module: entry });
+				} catch (error) {
+					return activationProblem(error);
+				}
+			},
+		});
+	const activateModule = activation(
+		'system.modules.activate',
+		'/api/system/modules/activate',
+		true,
+	);
+	const deactivateModule = activation(
+		'system.modules.deactivate',
+		'/api/system/modules/deactivate',
+		false,
+	);
+
 	/* Module names come from the workspace specs; the catalog is read once per
 	   composition, which in development is once per reload. */
 	let names: ReadonlyMap<
@@ -409,6 +523,9 @@ export function createSystemRoutes(options: SystemRouteOptions) {
 
 	return [
 		modules.serverRoute,
+		activeModules.serverRoute,
+		activateModule.serverRoute,
+		deactivateModule.serverRoute,
 		overview.serverRoute,
 		settingsList.serverRoute,
 		settingsUpdate.serverRoute,
@@ -417,6 +534,9 @@ export function createSystemRoutes(options: SystemRouteOptions) {
 
 export const endpoints = [
 	'system.modules.list',
+	'system.modules.active',
+	'system.modules.activate',
+	'system.modules.deactivate',
 	'system.overview.read',
 	'system.settings.list',
 	'system.settings.update',

package/modules/system/src/server/index.ts

@@ -1,5 +1,6 @@
 export { createSystemRoutes, endpoints } from './endpoints.ts';
 export type {
+	ModuleCatalogPayload,
 	OverviewActivityPoint,
 	OverviewModulePoint,
 	SettingsEntryPayload,
@@ -9,3 +10,28 @@ export type {
 } from './endpoints.ts';
 export { readModuleCatalog } from './module-catalog.ts';
 export type { ModuleCatalogEntry } from './module-catalog.ts';
+export type { SystemModulesCapability } from './capability.ts';
+export { createSystemRuntime } from './runtime.ts';
+export type { SystemRuntime, SystemRuntimeOptions } from './runtime.ts';
+export {
+	DEFAULT_SNAPSHOT_TENANTS,
+	DEFAULT_SNAPSHOT_TTL_MS,
+	ModuleActivationError,
+	ModuleActivationService,
+} from '../services/module-activation-service.ts';
+export type {
+	ModuleActivationErrorCode,
+	ModuleActivationServiceOptions,
+} from '../services/module-activation-service.ts';
+export {
+	DatabaseModuleActivationRepository,
+	migrateSystemDatabase,
+} from '../services/database-repository.ts';
+export {
+	databaseMigrations,
+	SYSTEM_TENANT_TABLES,
+} from '../services/migration.ts';
+export type {
+	ModuleActivationRecord,
+	ModuleActivationRepository,
+} from '../services/repository.ts';

package/modules/system/src/server/module-catalog.ts

@@ -16,6 +16,11 @@ export interface ModuleCatalogEntry {
 	readonly platform: { readonly server: boolean; readonly client: boolean };
 	readonly enabled: boolean;
 	readonly directory: string;
+	/** Declared module dependencies, by id. */
+	readonly dependencies: readonly string[];
+	readonly provides: readonly string[];
+	/** Capability ids the module requires, optional requirements excluded. */
+	readonly requires: readonly string[];
 }
 
 interface Manifest {
@@ -23,6 +28,9 @@ interface Manifest {
 	version?: unknown;
 	capabilities?: unknown;
 	platform?: { server?: unknown; client?: unknown };
+	dependencies?: { id?: unknown }[];
+	provides?: unknown;
+	requires?: { id?: unknown; optional?: unknown }[];
 }
 
 interface Spec {
@@ -111,6 +119,17 @@ export function readModuleCatalog(
 			},
 			enabled: enabled.has(manifest.id),
 			directory,
+			dependencies: strings(
+				(Array.isArray(manifest.dependencies) ? manifest.dependencies : []).map(
+					(dependency) => dependency?.id,
+				),
+			),
+			provides: strings(manifest.provides),
+			requires: strings(
+				(Array.isArray(manifest.requires) ? manifest.requires : [])
+					.filter((requirement) => requirement?.optional !== true)
+					.map((requirement) => requirement?.id),
+			),
 		});
 	}
 	return entries;

package/modules/system/src/server/runtime.ts

@@ -0,0 +1,102 @@
+import type {
+	DatabaseAdapterLease,
+	DatabaseProvider,
+	DatabaseProviderRequest,
+} from '@flowdular/sdk/database';
+import {
+	DATABASE_CAPABILITY_IDS,
+	DATABASE_DIALECT_IDS,
+} from '@flowdular/sdk/database';
+import {
+	DatabaseModuleActivationRepository,
+	migrateSystemDatabase,
+} from '../services/database-repository.ts';
+import {
+	ModuleActivationService,
+	type ModuleActivationServiceOptions,
+} from '../services/module-activation-service.ts';
+import type { ModuleActivationRepository } from '../services/repository.ts';
+
+export interface SystemRuntimeOptions
+	extends Omit<ModuleActivationServiceOptions, 'repository'> {
+	/** Platform-owned provider. Modules never receive a DSN or a pool. */
+	readonly databases: DatabaseProvider;
+	readonly purpose: Exclude<DatabaseProviderRequest['purpose'], 'migration'>;
+	/** Supplied by tests that own the lease themselves. */
+	readonly repository?: ModuleActivationRepository;
+}
+
+export interface SystemRuntime {
+	service(): Promise<ModuleActivationService>;
+	dispose(): Promise<void>;
+}
+
+export function createSystemRuntime(
+	options: SystemRuntimeOptions,
+): SystemRuntime {
+	let disposed = false;
+	let runtimeLeasePromise: Promise<DatabaseAdapterLease> | undefined;
+	let servicePromise: Promise<ModuleActivationService> | undefined;
+	const { databases, purpose, repository, ...serviceOptions } = options;
+
+	const build = (store: ModuleActivationRepository): ModuleActivationService =>
+		new ModuleActivationService({ ...serviceOptions, repository: store });
+
+	/* Schema work runs on the migrator role and that lease is released before the
+	   runtime one is taken, so request handling never holds a schema owner. */
+	const initialize = async (): Promise<ModuleActivationService> => {
+		if (repository) return build(repository);
+		const migrationLease = await databases.acquire({
+			namespace: 'system.core',
+			purpose: 'migration',
+			requirements: {
+				dialectIds: [DATABASE_DIALECT_IDS.postgresql],
+				capabilities: [
+					DATABASE_CAPABILITY_IDS.MIGRATION_LOCK,
+					DATABASE_CAPABILITY_IDS.SCHEMA_INTROSPECTION,
+					DATABASE_CAPABILITY_IDS.TRANSACTIONAL_DDL,
+				],
+			},
+		});
+		try {
+			await migrateSystemDatabase(migrationLease.database);
+		} finally {
+			await migrationLease.release();
+		}
+		runtimeLeasePromise = databases.acquire({
+			namespace: 'system.core',
+			purpose,
+			requirements: {
+				dialectIds: [DATABASE_DIALECT_IDS.postgresql],
+				capabilities: [
+					DATABASE_CAPABILITY_IDS.TRANSACTIONS,
+					DATABASE_CAPABILITY_IDS.TENANT_CONTEXT,
+				],
+			},
+		});
+		const lease = await runtimeLeasePromise;
+		return build(new DatabaseModuleActivationRepository(lease.database));
+	};
+
+	return {
+		service: () => {
+			if (disposed) {
+				return Promise.reject(new Error('System runtime is disposed.'));
+			}
+			servicePromise ??= initialize();
+			return servicePromise;
+		},
+		async dispose() {
+			if (disposed) return;
+			disposed = true;
+			if (!runtimeLeasePromise) {
+				await servicePromise?.catch(() => undefined);
+			}
+			if (!runtimeLeasePromise) return;
+			const lease = await runtimeLeasePromise;
+			await lease.release();
+			runtimeLeasePromise = undefined;
+			servicePromise = undefined;
+		},
+	};
+}

package/modules/system/src/services/database-repository.ts

@@ -0,0 +1,91 @@
+import type { DatabaseHandle } from '@flowdular/sdk/database';
+import { runDatabaseMigrations } from '@flowdular/sdk/database';
+import { databaseMigrations } from './migration.ts';
+import type {
+	ModuleActivationRecord,
+	ModuleActivationRepository,
+} from './repository.ts';
+
+interface ActivationRow {
+	tenant_id: string;
+	module_id: string;
+	active: number | bigint | string;
+	changed_by: string;
+	changed_at: number | bigint | string;
+}
+
+const SQL = {
+	list: `SELECT tenant_id, module_id, active, changed_by, changed_at
+	 FROM system_module_activations
+	 WHERE tenant_id = $1
+	 ORDER BY module_id`,
+	set: `INSERT INTO system_module_activations
+	 (tenant_id, module_id, active, changed_by, changed_at)
+	 VALUES ($1, $2, $3, $4, $5)
+	 ON CONFLICT (tenant_id, module_id) DO UPDATE
+	 SET active = EXCLUDED.active,
+	     changed_by = EXCLUDED.changed_by,
+	     changed_at = EXCLUDED.changed_at
+	 WHERE system_module_activations.tenant_id = $1`,
+} as const;
+
+/* PostgreSQL returns BIGINT as a string, and a flag column as a number this
+   module compares only after normalizing. */
+function integer(value: number | bigint | string, field: string): number {
+	const normalized = Number(value);
+	if (!Number.isSafeInteger(normalized) || normalized < 0) {
+		throw new Error(`The system database returned an invalid ${field}.`);
+	}
+	return normalized;
+}
+
+function fromRow(row: ActivationRow): ModuleActivationRecord {
+	return {
+		tenantId: row.tenant_id,
+		moduleId: row.module_id,
+		active: integer(row.active, 'flag') === 1,
+		changedBy: row.changed_by,
+		changedAt: integer(row.changed_at, 'timestamp'),
+	};
+}
+
+export class DatabaseModuleActivationRepository
+	implements ModuleActivationRepository
+{
+	constructor(private readonly database: DatabaseHandle) {}
+
+	async list(tenantId: string): Promise<readonly ModuleActivationRecord[]> {
+		const result = await this.database.transaction(
+			(transaction) =>
+				transaction.query<ActivationRow>({
+					text: SQL.list,
+					parameters: [tenantId],
+				}),
+			{ access: 'read', tenantId },
+		);
+		return result.rows.map(fromRow);
+	}
+
+	async set(record: ModuleActivationRecord): Promise<void> {
+		await this.database.transaction(
+			(transaction) =>
+				transaction.execute({
+					text: SQL.set,
+					parameters: [
+						record.tenantId,
+						record.moduleId,
+						record.active ? 1 : 0,
+						record.changedBy,
+						record.changedAt,
+					],
+				}),
+			{ access: 'write', tenantId: record.tenantId },
+		);
+	}
+}
+
+export async function migrateSystemDatabase(
+	database: DatabaseHandle,
+): Promise<void> {
+	await runDatabaseMigrations(database, 'system.core', databaseMigrations);
+}

package/modules/system/src/services/migration.ts

@@ -0,0 +1,39 @@
+import type { DatabaseMigration } from '@flowdular/sdk/database';
+import { postgresTenantTableState } from '@flowdular/sdk/database';
+
+/* Mirrors migrations/0001_system_module_activations.up.sql byte for byte;
+   tests/migrations.test.ts fails on drift. */
+export const SYSTEM_MIGRATION_001 = `-- One row per module whose activation an owner changed for a workspace. A
+-- composed module without a row is active; the row keeps the last decision and
+-- who made it. The primary key is the only lookup: the snapshot reads every row
+-- of one tenant at once.
+CREATE TABLE IF NOT EXISTS system_module_activations (
+  tenant_id TEXT NOT NULL,
+  module_id TEXT NOT NULL CHECK (length(module_id) BETWEEN 1 AND 128),
+  active SMALLINT NOT NULL CHECK (active IN (0, 1)),
+  changed_by TEXT NOT NULL CHECK (length(changed_by) BETWEEN 1 AND 64),
+  changed_at BIGINT NOT NULL,
+  PRIMARY KEY (tenant_id, module_id)
+);
+ALTER TABLE system_module_activations ENABLE ROW LEVEL SECURITY;
+ALTER TABLE system_module_activations FORCE ROW LEVEL SECURITY;
+CREATE POLICY system_module_activations_tenant_policy ON system_module_activations
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+`;
+
+/** Every tenant table of this module, with the policy each one must carry. */
+export const SYSTEM_TENANT_TABLES = ['system_module_activations'] as const;
+
+export const databaseMigrations: readonly DatabaseMigration[] = [
+	{
+		id: '0001_system_module_activations',
+		sql: { postgresql: SYSTEM_MIGRATION_001 },
+		inspectExisting: (database) =>
+			postgresTenantTableState(
+				database,
+				'system_module_activations',
+				'system_module_activations_tenant_policy',
+			),
+	},
+];