@flowdular/sdk 0.2.4 → 0.3.0

package/packages/kernel/src/module-registry.ts

@@ -15,9 +15,31 @@ function compareModules(
 	return left.manifest.id.localeCompare(right.manifest.id);
 }
 
+/* Every provider of a capability id, by module id. A capability has one
+   provider: two modules registering the same id would race at composition. */
+export function capabilityProviders(
+	modules: Iterable<RegisteredModule>,
+): ReadonlyMap<string, string> {
+	const providers = new Map<string, string>();
+	for (const module of modules) {
+		for (const capability of module.manifest.provides ?? []) {
+			const existing = providers.get(capability);
+			if (existing && existing !== module.manifest.id) {
+				throw new RegistryError(
+					'MODULE_CAPABILITY_DUPLICATE',
+					`Capability "${capability}" is provided by both "${existing}" and "${module.manifest.id}".`,
+				);
+			}
+			providers.set(capability, module.manifest.id);
+		}
+	}
+	return providers;
+}
+
 function visitModule(
 	id: string,
 	modules: ReadonlyMap<string, RegisteredModule>,
+	providers: ReadonlyMap<string, string>,
 	visiting: Set<string>,
 	visited: Set<string>,
 	ordered: RegisteredModule[],
@@ -53,7 +75,24 @@ function visitModule(
 			dependency,
 			modules.get(dependency.id)!.manifest.version,
 		);
-		visitModule(dependency.id, modules, visiting, visited, ordered);
+		visitModule(dependency.id, modules, providers, visiting, visited, ordered);
+	}
+	/* A required capability orders its provider first, like a dependency. An
+	   optional one is resolved lazily by the consumer, so it neither fails when
+	   absent nor takes part in ordering. */
+	for (const requirement of [...(current.manifest.requires ?? [])].sort(
+		(a, b) => a.id.localeCompare(b.id),
+	)) {
+		if (requirement.optional) continue;
+		const provider = providers.get(requirement.id);
+		if (!provider) {
+			throw new RegistryError(
+				'MODULE_CAPABILITY_MISSING',
+				`Module "${id}" requires capability "${requirement.id}" and no registered module provides it.`,
+			);
+		}
+		if (provider === id) continue;
+		visitModule(provider, modules, providers, visiting, visited, ordered);
 	}
 	visiting.delete(id);
 	visited.add(id);
@@ -96,11 +135,19 @@ export function createModuleRegistry(
 		}
 	}
 
+	const providers = capabilityProviders(byId.values());
 	const ordered: RegisteredModule[] = [];
 	const visiting = new Set<string>();
 	const visited = new Set<string>();
 	for (const module of [...input].sort(compareModules)) {
-		visitModule(module.manifest.id, byId, visiting, visited, ordered);
+		visitModule(
+			module.manifest.id,
+			byId,
+			providers,
+			visiting,
+			visited,
+			ordered,
+		);
 	}
 
 	return Object.freeze({

package/packages/kernel/src/module-settings.ts

@@ -4,6 +4,11 @@ export type ModuleSettingType = 'string' | 'number' | 'boolean';
    shared by every tenant; auth uses them for knobs that apply before a tenant
    is known, such as sign-up availability. */
 export type ModuleSettingScope = 'platform' | 'tenant';
+/* A feature flag is a boolean setting an operator turns on or off per
+   workspace. It is stored, read and validated exactly like any other setting;
+   the kind is what makes the change audited as a flag change and listed on the
+   Flags screen. */
+export type ModuleSettingKind = 'flag';
 
 export interface ModuleSettingDefinition {
 	readonly type: ModuleSettingType;
@@ -12,6 +17,8 @@ export interface ModuleSettingDefinition {
 	readonly client: boolean;
 	/** Write-only: the API never returns the value, only whether one is set. */
 	readonly secret?: boolean;
+	/** `flag` requires a tenant-scoped, non-secret boolean, labelled and described. */
+	readonly kind?: ModuleSettingKind;
 	readonly scope?: ModuleSettingScope;
 	/** Fully qualified client translation key; `label` remains the fallback. */
 	readonly labelKey?: string;
@@ -45,13 +52,15 @@ export interface ModuleSettingRecord {
 	readonly updatedAt: number;
 }
 
+/* Storage may be a database or a network, so every operation is asynchronous;
+   the runtime serves reads from a snapshot it primes per tenant. */
 export interface ModuleSettingsStore {
 	load(
 		tenantId: string,
 		moduleId: string,
-	): Readonly<Record<string, ModuleSettingValue>>;
-	save(record: ModuleSettingRecord): void;
-	clear(tenantId: string, moduleId: string, key: string): void;
+	): Promise<Readonly<Record<string, ModuleSettingValue>>>;
+	save(record: ModuleSettingRecord): Promise<void>;
+	clear(tenantId: string, moduleId: string, key: string): Promise<void>;
 }
 
 export interface ModuleSettingEntry {
@@ -71,6 +80,15 @@ export interface ModuleSettingChange {
 	readonly key: string;
 	/** True when the stored value was removed and the default applies again. */
 	readonly cleared: boolean;
+	/** Declared kind, so a listener can audit a flag change as a flag change. */
+	readonly kind?: ModuleSettingKind;
+	/**
+	 * Effective values around the write, default included, so an audit trail
+	 * records what an operator actually changed. Both are null for a secret,
+	 * whose value never leaves the store.
+	 */
+	readonly previous: ModuleSettingValue | null;
+	readonly next: ModuleSettingValue | null;
 	/** The set() caller and the workspace the change was made from. */
 	readonly actor: {
 		readonly accountId: string;
@@ -81,27 +99,34 @@ export interface ModuleSettingChange {
 export interface ModuleSettingsRuntime {
 	declare(declaration: ModuleSettingsDeclaration): void;
 	declarations(): readonly ModuleSettingsDeclaration[];
-	/** Live read: the stored value, else the declared default. */
+	/**
+	 * Loads the stored values of every declared module for this tenant, and the
+	 * platform-scoped ones, into memory. Idempotent and memoised: a primed
+	 * tenant costs one lookup. `get` and `list` answer from that snapshot, so a
+	 * request path primes the tenant before it reads.
+	 */
+	prime(tenantId: string): Promise<void>;
+	/** The stored value, else the declared default; throws for an unprimed tenant. */
 	get<T extends ModuleSettingValue>(
 		tenantId: string,
 		moduleId: string,
 		key: string,
 	): T;
 	list(tenantId: string): readonly ModuleSettingEntry[];
-	/** Validates against the declaration; null clears the stored value. */
+	/** Validates against the declaration; null clears the stored value. Resolves once the store holds it and the snapshot is refreshed. */
 	set(
 		tenantId: string,
 		moduleId: string,
 		key: string,
 		value: ModuleSettingValue | null,
 		actor: string,
-	): void;
+	): Promise<void>;
 	onChange(listener: (change: ModuleSettingChange) => void): () => void;
 }
 
 export interface ModuleSettingsRuntimeOptions {
 	readonly now?: () => number;
-	/** Bound on cached (tenant, module) value sets; least recently read is evicted. */
+	/** Bound on tenants held in memory; the least recently primed is evicted, the platform tenant stays. */
 	readonly cacheLimit?: number;
 }
 
@@ -124,6 +149,22 @@ function invalid(name: string, detail: string): ModuleSettingsError {
 	);
 }
 
+/* One compiled pattern per declared setting. Every read validates the stored
+   value against its declaration, so compiling here rather than per call keeps
+   the regular expression off the request path; `defineModuleSettings` builds it
+   while it checks the declared default. Keyed by the definition, so a
+   declaration that goes away takes its pattern with it. */
+const patterns = new WeakMap<ModuleSettingDefinition, RegExp>();
+
+function patternOf(definition: ModuleSettingDefinition): RegExp {
+	let compiled = patterns.get(definition);
+	if (compiled === undefined) {
+		compiled = new RegExp(`^(?:${definition.pattern})$`, 'u');
+		patterns.set(definition, compiled);
+	}
+	return compiled;
+}
+
 export function assertSettingValue(
 	moduleId: string,
 	key: string,
@@ -158,7 +199,7 @@ export function assertSettingValue(
 		}
 		if (
 			definition.pattern !== undefined &&
-			!new RegExp(`^(?:${definition.pattern})$`, 'u').test(value)
+			!patternOf(definition).test(value)
 		) {
 			throw invalid(name, 'has an unsupported format.');
 		}
@@ -225,6 +266,30 @@ export function defineModuleSettings(
 				`Secret setting ${declaration.moduleId}.${key} cannot be shared or sent to clients.`,
 			);
 		}
+		/* A flag is offered to an operator as a bare switch on a screen that
+		   shows no module documentation, so the declaration has to carry the
+		   words that explain it; a secret one could be neither read back nor
+		   audited with its values. A flag is on or off for one workspace, and
+		   the screen that turns it on is that workspace's, so a platform-scoped
+		   one would let an operator switch every other workspace from inside
+		   their own. */
+		if (definition.kind === 'flag') {
+			if (definition.type !== 'boolean' || definition.secret) {
+				throw new Error(
+					`Flag ${declaration.moduleId}.${key} must be a non-secret boolean setting.`,
+				);
+			}
+			if (definition.scope === 'platform') {
+				throw new Error(
+					`Flag ${declaration.moduleId}.${key} must be tenant-scoped; a platform setting carries one value for every workspace.`,
+				);
+			}
+			if (!definition.label || !definition.description) {
+				throw new Error(
+					`Flag ${declaration.moduleId}.${key} must declare a label and a description.`,
+				);
+			}
+		}
 	}
 	return Object.freeze(declaration);
 }
@@ -238,7 +303,17 @@ export function createModuleSettingsRuntime(
 	const now = options.now ?? Date.now;
 	const cacheLimit = options.cacheLimit ?? 512;
 	const declarations = new Map<string, ModuleSettingsDeclaration>();
-	const cache = new Map<string, Readonly<Record<string, ModuleSettingValue>>>();
+	/* Tenant, then module, to the values the store holds. Filled by prime and
+	   by set, never by a read: a read of a tenant that is not here fails. */
+	const snapshots = new Map<
+		string,
+		Map<string, Readonly<Record<string, ModuleSettingValue>>>
+	>();
+	const loads = new Map<string, Promise<void>>();
+	/* The declaration generation a tenant was primed at; a module declared
+	   later makes the next prime load what is missing. */
+	const primed = new Map<string, number>();
+	let generation = 0;
 	const listeners = new Set<ChangeListener>();
 
 	const definitionOf = (
@@ -280,24 +355,95 @@ export function createModuleSettingsRuntime(
 		return tenantId;
 	};
 
+	const tenantSnapshot = (
+		tenantId: string,
+	): Map<string, Readonly<Record<string, ModuleSettingValue>>> => {
+		let snapshot = snapshots.get(tenantId);
+		if (snapshot) return snapshot;
+		if (snapshots.size >= cacheLimit) {
+			for (const oldest of snapshots.keys()) {
+				if (oldest === PLATFORM_SETTINGS_TENANT) continue;
+				snapshots.delete(oldest);
+				primed.delete(oldest);
+				break;
+			}
+		}
+		snapshot = new Map();
+		snapshots.set(tenantId, snapshot);
+		return snapshot;
+	};
+
+	const loadModule = (tenantId: string, moduleId: string): Promise<void> => {
+		if (snapshots.get(tenantId)?.has(moduleId)) return Promise.resolve();
+		const loadKey = `${tenantId} ${moduleId}`;
+		const inflight = loads.get(loadKey);
+		if (inflight) return inflight;
+		const pending = store
+			.load(tenantId, moduleId)
+			.then((values) => {
+				tenantSnapshot(tenantId).set(moduleId, values);
+			})
+			.finally(() => loads.delete(loadKey));
+		loads.set(loadKey, pending);
+		return pending;
+	};
+
+	const scopesOf = (
+		declaration: ModuleSettingsDeclaration,
+	): { readonly tenant: boolean; readonly platform: boolean } => {
+		let tenant = false;
+		let platform = false;
+		for (const definition of Object.values(declaration.settings)) {
+			if (definition.scope === 'platform') platform = true;
+			else tenant = true;
+		}
+		return { tenant, platform };
+	};
+
+	const prime = async (tenantId: string): Promise<void> => {
+		const at = generation;
+		if (primed.get(tenantId) === at) {
+			const snapshot = snapshots.get(tenantId);
+			if (snapshot) {
+				snapshots.delete(tenantId);
+				snapshots.set(tenantId, snapshot);
+			}
+			return;
+		}
+		const pending: Promise<void>[] = [];
+		for (const declaration of declarations.values()) {
+			const scopes = scopesOf(declaration);
+			if (scopes.platform) {
+				pending.push(
+					loadModule(PLATFORM_SETTINGS_TENANT, declaration.moduleId),
+				);
+			}
+			if (scopes.tenant && tenantId !== PLATFORM_SETTINGS_TENANT) {
+				pending.push(loadModule(tenantId, declaration.moduleId));
+			}
+		}
+		await Promise.all(pending);
+		tenantSnapshot(tenantId);
+		primed.set(tenantId, at);
+	};
+
 	const stored = (
 		tenantId: string,
 		moduleId: string,
 	): Readonly<Record<string, ModuleSettingValue>> => {
-		const cacheKey = `${tenantId} ${moduleId}`;
-		const hit = cache.get(cacheKey);
-		if (hit) {
-			cache.delete(cacheKey);
-			cache.set(cacheKey, hit);
-			return hit;
-		}
-		const loaded = store.load(tenantId, moduleId);
-		if (cache.size >= cacheLimit) {
-			const oldest = cache.keys().next().value;
-			if (oldest !== undefined) cache.delete(oldest);
+		const values = snapshots.get(tenantId)?.get(moduleId);
+		if (!values) {
+			throw new ModuleSettingsError(
+				'SETTINGS_NOT_PRIMED',
+				`Settings of ${moduleId} for ${
+					tenantId === PLATFORM_SETTINGS_TENANT
+						? 'the platform'
+						: `tenant ${tenantId}`
+				} are not loaded; await settings.prime(tenantId) before reading.`,
+				500,
+			);
 		}
-		cache.set(cacheKey, loaded);
-		return loaded;
+		return values;
 	};
 
 	const resolve = (
@@ -332,10 +478,12 @@ export function createModuleSettingsRuntime(
 				);
 			}
 			declarations.set(declaration.moduleId, defineModuleSettings(declaration));
+			generation += 1;
 		},
 		declarations() {
 			return [...declarations.values()];
 		},
+		prime,
 		get(tenantId, moduleId, key) {
 			return resolve(tenantId, moduleId, key, definitionOf(moduleId, key))
 				.value as never;
@@ -361,27 +509,41 @@ export function createModuleSettingsRuntime(
 			}
 			return entries;
 		},
-		set(tenantId, moduleId, key, value, actor) {
+		async set(tenantId, moduleId, key, value, actor) {
 			const definition = definitionOf(moduleId, key);
 			const target = storageTenant(definition, moduleId, key, tenantId);
+			const next =
+				value === null
+					? definition.defaultValue
+					: assertSettingValue(moduleId, key, definition, value);
+			/* Read before the write, so the change carries the value that was
+			   replaced. The snapshot keeps serving the old values until the
+			   reload lands, so a concurrent read never finds a gap. */
+			await loadModule(target, moduleId);
+			const previous = definition.secret
+				? null
+				: resolve(tenantId, moduleId, key, definition).value;
 			if (value === null) {
-				store.clear(target, moduleId, key);
+				await store.clear(target, moduleId, key);
 			} else {
-				store.save({
+				await store.save({
 					tenantId: target,
 					moduleId,
 					key,
-					value: assertSettingValue(moduleId, key, definition, value),
+					value: next,
 					updatedBy: actor,
 					updatedAt: now(),
 				});
 			}
-			cache.delete(`${target} ${moduleId}`);
+			tenantSnapshot(target).set(moduleId, await store.load(target, moduleId));
 			const change: ModuleSettingChange = {
 				tenantId: target,
 				moduleId,
 				key,
 				cleared: value === null,
+				...(definition.kind ? { kind: definition.kind } : {}),
+				previous,
+				next: definition.secret ? null : next,
 				actor: { accountId: actor, tenantId },
 			};
 			for (const listener of listeners) {

package/packages/server/package.json

@@ -13,7 +13,8 @@
 		"@octanejs/app-core": "0.0.47",
 		"@flowdular/contracts": "workspace:*",
 		"@flowdular/kernel": "workspace:*",
-		"@flowdular/database": "workspace:*"
+		"@flowdular/database": "workspace:*",
+		"@flowdular/storage": "workspace:*"
 	},
 	"devDependencies": {
 		"typescript": "5.9.3",

package/packages/server/src/composition.ts

@@ -1,11 +1,16 @@
 import type { ServerRoute } from '@octanejs/app-core';
 import type { ModuleWebSurface } from '@flowdular/sdk/contracts';
 import type { DatabaseProvider } from '@flowdular/sdk/database';
+import type { StoragePort } from '@flowdular/sdk/storage';
+import type { MailPort } from './mail/index.ts';
+import type { ModuleMetrics } from './metrics.ts';
+import type { Tracer } from './trace/index.ts';
 import type {
 	ModuleSettingsDeclaration,
 	ModuleSettingsRuntime,
 	PlatformAgentRegistry,
 	PlatformCapabilityRegistry,
+	PlatformDataClassRegistry,
 	PlatformToolRegistry,
 } from '@flowdular/sdk/kernel';
 
@@ -24,10 +29,43 @@ export interface ModuleServerContext<Auth> {
 	readonly agentTools: PlatformToolRegistry;
 	/** Business agent definitions modules register before the platform starts. */
 	readonly agentDefinitions: PlatformAgentRegistry;
+	/**
+	 * The data a module owns, declared while it composes. The platform seals
+	 * the registry after every composition ran, so `list()` answers the whole
+	 * catalogue from any module's view; the binding limits what a module may
+	 * declare, never what it may read.
+	 */
+	readonly dataClasses: PlatformDataClassRegistry;
 	/** Typed public services shared by composed modules without database access. */
 	readonly capabilities: PlatformCapabilityRegistry;
 	/** Platform-owned database leases. Modules never receive a DSN or pool. */
 	readonly databases: DatabaseProvider;
+	/**
+	 * Platform-owned object storage. The tenant id is the first key segment and
+	 * comes from the principal, never from the request, because no row-level
+	 * security reaches an object store.
+	 */
+	readonly storage: StoragePort;
+	/**
+	 * Platform-owned outbound mail. A module hands it a bounded message and
+	 * never selects a transport; `configured` is false when the deployment
+	 * composed none, and every send is refused with MAIL_NOT_CONFIGURED.
+	 */
+	readonly mail: MailPort;
+	/**
+	 * The counters and histograms this module owns, already bound to its id by
+	 * the generated composition. Every series it opens is exposed on
+	 * `/api/metrics` as `flowdular_module_<module id>_<name>`, under the same
+	 * bounds the request series have.
+	 */
+	readonly metrics: ModuleMetrics;
+	/**
+	 * Spans for the work this module does. A module that enqueues work stores
+	 * `currentTraceParent()` on the row it enqueues and hands that value back as
+	 * `traceparent` when it starts the span for the claimed item, so a job
+	 * carries the trace that enqueued it.
+	 */
+	readonly tracer: Tracer;
 }
 
 export interface ModuleServerComposition {

package/packages/server/src/endpoint.ts

@@ -1,4 +1,12 @@
 import { ServerRoute, type Context } from '@octanejs/app-core';
+import { serverLogger } from './log.ts';
+import { serverMetrics } from './metrics.ts';
+import {
+	formatTraceParent,
+	runWithTrace,
+	type TraceContext,
+} from './trace/context.ts';
+import { serverTracer, type Span } from './trace/tracer.ts';
 
 export interface EndpointIdentity {
 	readonly subjectId: string;
@@ -7,6 +15,12 @@ export interface EndpointIdentity {
 
 export interface EndpointExecutionContext {
 	readonly requestId: string;
+	/**
+	 * The W3C trace this request runs in: the caller's `traceparent` when it
+	 * sent a usable one, a new root otherwise. It is the ambient trace for
+	 * everything the handler awaits and it is returned in the response header.
+	 */
+	readonly trace: TraceContext;
 	readonly identity: EndpointIdentity | null;
 	readonly octane: Context;
 }
@@ -46,10 +60,11 @@ function problem(
 	code: string,
 	message: string,
 	requestId: string,
+	traceparent: string,
 ): Response {
 	return Response.json(
 		{ error: { code, message }, requestId },
-		{ status, headers: { 'cache-control': 'no-store' } },
+		{ status, headers: { 'cache-control': 'no-store', traceparent } },
 	);
 }
 
@@ -81,56 +96,98 @@ export function defineEndpoint(
 		);
 	}
 
+	const serve = async (
+		context: Context,
+		requestId: string,
+		span: Span,
+	): Promise<Response> => {
+		const traceparent = formatTraceParent(span.context);
+		const startedAt = performance.now();
+		let identity: EndpointIdentity | null = null;
+		let status = 500;
+		try {
+			if (
+				definition.access.kind === 'permission' &&
+				'resolveIdentity' in definition
+			) {
+				identity = await definition.resolveIdentity(context);
+				if (!identity) {
+					status = 401;
+					return problem(
+						401,
+						'UNAUTHENTICATED',
+						'Authentication is required.',
+						requestId,
+						traceparent,
+					);
+				}
+				if (!identity.permissions.has(definition.access.permission)) {
+					status = 403;
+					return problem(
+						403,
+						'FORBIDDEN',
+						'The required permission was not granted.',
+						requestId,
+						traceparent,
+					);
+				}
+			}
+
+			const response = await definition.handler({
+				requestId,
+				trace: span.context,
+				identity,
+				octane: context,
+			});
+			response.headers.set('x-request-id', requestId);
+			response.headers.set('traceparent', traceparent);
+			status = response.status;
+			return response;
+		} catch (error) {
+			/* An unexpected error may carry SQL parameters, provider responses, or
+			   credentials in its message and attached fields. The request id and
+			   endpoint identify the failure without sending that value to a logger. */
+			serverLogger().error('endpoint failed', {
+				requestId,
+				endpoint: definition.id,
+				err: { name: error instanceof Error ? error.name : 'non-error' },
+			});
+			return problem(
+				500,
+				'INTERNAL_ERROR',
+				'The request could not be completed.',
+				requestId,
+				traceparent,
+			);
+		} finally {
+			span.setAttribute('http.response.status_code', status);
+			span.end(status >= 500 ? 'error' : 'ok');
+			serverMetrics().recordHttpRequest({
+				endpoint: definition.id,
+				method: context.request.method,
+				status,
+				durationSeconds: (performance.now() - startedAt) / 1000,
+			});
+		}
+	};
+
 	const serverRoute = new ServerRoute({
 		path: definition.path,
 		methods: definition.methods.map((method) => method.toUpperCase()),
-		handler: async (context) => {
+		handler: (context) => {
 			const requestId = requestIdOf(context);
-			let identity: EndpointIdentity | null = null;
-			try {
-				if (
-					definition.access.kind === 'permission' &&
-					'resolveIdentity' in definition
-				) {
-					identity = await definition.resolveIdentity(context);
-					if (!identity)
-						return problem(
-							401,
-							'UNAUTHENTICATED',
-							'Authentication is required.',
-							requestId,
-						);
-					if (!identity.permissions.has(definition.access.permission)) {
-						return problem(
-							403,
-							'FORBIDDEN',
-							'The required permission was not granted.',
-							requestId,
-						);
-					}
-				}
-
-				const response = await definition.handler({
-					requestId,
-					identity,
-					octane: context,
-				});
-				response.headers.set('x-request-id', requestId);
-				return response;
-			} catch (error) {
-				/* An unexpected error may carry SQL parameters, provider responses, or
-				   credentials in its message and attached fields. The request id and
-				   endpoint identify the failure without sending that value to a logger. */
-				console.error(
-					`[${requestId}] endpoint ${definition.id} failed (${error instanceof Error ? 'Error' : 'non-error'})`,
-				);
-				return problem(
-					500,
-					'INTERNAL_ERROR',
-					'The request could not be completed.',
-					requestId,
-				);
-			}
+			/* An inbound header names the parent; an absent or malformed one is a
+			   new root, so a request always belongs to exactly one trace. */
+			const span = serverTracer().startSpan(definition.id, {
+				traceparent: context.request.headers.get('traceparent'),
+				kind: 'server',
+				attributes: {
+					'flowdular.endpoint': definition.id,
+					'flowdular.request_id': requestId,
+					'http.request.method': context.request.method,
+				},
+			});
+			return runWithTrace(span.context, () => serve(context, requestId, span));
 		},
 	});