@flowdular/sdk 0.2.4 → 0.3.1

package/modules/reports/src/services/provider-registry.ts

@@ -0,0 +1,144 @@
+import {
+	REPORT_PROVIDER_LIMITS,
+	type ReportProvider,
+	type ReportProviderRegistry,
+} from '../domain/providers.ts';
+import { ReportsServiceError } from './service-error.ts';
+
+const MODULE_ID = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/;
+const PROVIDER_KEY = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*$/;
+const PERMISSION_ID = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/;
+
+export interface RegisteredReportProvider extends ReportProvider {
+	readonly moduleId: string;
+}
+
+export interface MutableReportProviderRegistry extends ReportProviderRegistry {
+	/** Closes registration. Every later call answers `PROVIDER_REGISTRY_SEALED`. */
+	seal(): void;
+	/** Registration order, which is the order the screen renders in. */
+	list(): readonly RegisteredReportProvider[];
+}
+
+function refuse(code: string, message: string): never {
+	throw new ReportsServiceError(code, message, 500);
+}
+
+function text(
+	value: unknown,
+	field: string,
+	maximum: number,
+	pattern?: RegExp,
+): string {
+	if (typeof value !== 'string' || value.length === 0) {
+		refuse('PROVIDER_INVALID', `A report provider ${field} must be text.`);
+	}
+	if (value.length > maximum) {
+		refuse(
+			'PROVIDER_INVALID',
+			`A report provider ${field} is at most ${maximum} characters.`,
+		);
+	}
+	if (pattern && !pattern.test(value)) {
+		refuse(
+			'PROVIDER_INVALID',
+			`Report provider ${field} "${value}" is not valid.`,
+		);
+	}
+	return value;
+}
+
+/**
+ * The providers of one process. Registration happens while modules compose and
+ * closes before the first request, so every request reads the same list in the
+ * same order and a lookup is an array walk over at most
+ * `REPORT_PROVIDER_LIMITS.providers` entries.
+ */
+export function createReportProviderRegistry(): MutableReportProviderRegistry {
+	const providers: RegisteredReportProvider[] = [];
+	const keys = new Set<string>();
+	let sealed: readonly RegisteredReportProvider[] | null = null;
+
+	return {
+		register(moduleId, entries) {
+			if (sealed) {
+				refuse(
+					'PROVIDER_REGISTRY_SEALED',
+					`${String(moduleId)} registers a report provider after reports.core started.`,
+				);
+			}
+			text(moduleId, 'module id', REPORT_PROVIDER_LIMITS.moduleId, MODULE_ID);
+			if (!Array.isArray(entries)) {
+				refuse(
+					'PROVIDER_INVALID',
+					`${moduleId} must register a list of report providers.`,
+				);
+			}
+			if (
+				providers.length + entries.length >
+				REPORT_PROVIDER_LIMITS.providers
+			) {
+				refuse(
+					'PROVIDER_LIMIT_EXCEEDED',
+					`A deployment registers at most ${REPORT_PROVIDER_LIMITS.providers} report providers.`,
+				);
+			}
+			/* Validated in full before anything is kept, so a bad entry in the
+			   middle of a module's list cannot leave half of it registered. */
+			const accepted: RegisteredReportProvider[] = [];
+			const pending = new Set<string>();
+			for (const provider of entries) {
+				const key = text(
+					provider?.key,
+					'key',
+					REPORT_PROVIDER_LIMITS.key,
+					PROVIDER_KEY,
+				);
+				if (keys.has(key) || pending.has(key)) {
+					refuse(
+						'PROVIDER_DUPLICATE',
+						`Report provider "${key}" is already registered.`,
+					);
+				}
+				pending.add(key);
+				accepted.push({
+					key,
+					moduleId,
+					label: text(provider.label, 'label', REPORT_PROVIDER_LIMITS.label),
+					...(provider.labelKey === undefined
+						? {}
+						: {
+								labelKey: text(
+									provider.labelKey,
+									'label key',
+									REPORT_PROVIDER_LIMITS.key,
+								),
+							}),
+					permission: text(
+						provider.permission,
+						'permission',
+						REPORT_PROVIDER_LIMITS.permission,
+						PERMISSION_ID,
+					),
+					read:
+						typeof provider.read === 'function'
+							? provider.read.bind(provider)
+							: refuse(
+									'PROVIDER_INVALID',
+									`Report provider "${key}" has no read operation.`,
+								),
+				});
+			}
+			for (const provider of accepted) {
+				keys.add(provider.key);
+				providers.push(provider);
+			}
+		},
+		seal() {
+			sealed ??= [...providers];
+		},
+		list() {
+			return sealed ?? providers;
+		},
+	};
+}

package/modules/reports/src/services/range.ts

@@ -0,0 +1,65 @@
+import type { ReportRange } from '../domain/providers.ts';
+import { REPORT_LIMITS } from '../domain/types.ts';
+import { ReportsServiceError } from './service-error.ts';
+
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+const DAY_MS = 86_400_000;
+
+/* UTC so a workspace report does not move when a reader's clock does, and the
+   same unit every shipped rollup already buckets by. */
+export function utcDay(timestamp: number): string {
+	return new Date(timestamp).toISOString().slice(0, 10);
+}
+
+function day(value: string, field: string): string {
+	const normalized = value.trim();
+	if (
+		!DAY.test(normalized) ||
+		Number.isNaN(Date.parse(`${normalized}T00:00:00Z`))
+	) {
+		throw new ReportsServiceError(
+			'INVALID_RANGE',
+			`${field} must be a UTC day in YYYY-MM-DD form.`,
+		);
+	}
+	return normalized;
+}
+
+/**
+ * The range a request asks for, refused before any provider is called. `to`
+ * defaults to today and `from` to the 30 day window ending there, so a client
+ * that names neither still gets a bounded answer. The width bound equals the
+ * point bound, which is what lets a daily series stay inside one answer.
+ */
+export function readReportRange(
+	input: { readonly from?: string | null; readonly to?: string | null },
+	now: number,
+): ReportRange {
+	const to =
+		input.to === undefined || input.to === null || input.to === ''
+			? utcDay(now)
+			: day(input.to, 'to');
+	const from =
+		input.from === undefined || input.from === null || input.from === ''
+			? utcDay(
+					Date.parse(`${to}T00:00:00Z`) -
+						(REPORT_LIMITS.defaultRangeDays - 1) * DAY_MS,
+				)
+			: day(input.from, 'from');
+	if (from > to) {
+		throw new ReportsServiceError(
+			'INVALID_RANGE',
+			'from must not be later than to.',
+		);
+	}
+	if (
+		Date.parse(`${to}T00:00:00Z`) - Date.parse(`${from}T00:00:00Z`) >
+		(REPORT_LIMITS.rangeDays - 1) * DAY_MS
+	) {
+		throw new ReportsServiceError(
+			'INVALID_RANGE',
+			`The range must cover at most ${REPORT_LIMITS.rangeDays} days.`,
+		);
+	}
+	return { from, to };
+}

package/modules/reports/src/services/reports-service.ts

@@ -0,0 +1,316 @@
+import {
+	REPORT_PROVIDER_LIMITS,
+	type ReportPrincipal,
+	type ReportProviderAnswer,
+	type ReportRange,
+	type ReportSeries,
+	type ReportTile,
+} from '../domain/providers.ts';
+import {
+	REPORT_LIMITS,
+	type ReportProviderSummary,
+	type WorkspaceReport,
+	type WorkspaceReportPage,
+} from '../domain/types.ts';
+import type {
+	MutableReportProviderRegistry,
+	RegisteredReportProvider,
+} from './provider-registry.ts';
+import { bounded, ReportsServiceError } from './service-error.ts';
+
+/** Widest and narrowest time budget a setting may put on one provider. */
+export const PROVIDER_TIMEOUT_RANGE = {
+	minimum: 200,
+	maximum: 30_000,
+} as const;
+
+export interface ReportsBudget {
+	/** Time one provider gets for one request. */
+	readonly providerTimeoutMs: number;
+}
+
+export interface ReportsQueryInput {
+	readonly principal: ReportPrincipal;
+	readonly range: ReportRange;
+}
+
+export interface ReportsServiceOptions {
+	readonly registry: MutableReportProviderRegistry;
+	/** Read live, so a settings change applies to the next request. */
+	readonly budget: () => ReportsBudget;
+}
+
+function summary(provider: RegisteredReportProvider): ReportProviderSummary {
+	return {
+		key: provider.key,
+		moduleId: provider.moduleId,
+		label: provider.label,
+		...(provider.labelKey === undefined ? {} : { labelKey: provider.labelKey }),
+		permission: provider.permission,
+	};
+}
+
+function finite(value: unknown, provider: string, field: string): number {
+	const number = typeof value === 'number' ? value : Number.NaN;
+	if (!Number.isFinite(number)) {
+		throw new ReportsServiceError(
+			'PROVIDER_ANSWER_INVALID',
+			`Report provider "${provider}" answered with a ${field} that is not a number.`,
+			502,
+		);
+	}
+	return number;
+}
+
+function readTile(value: ReportTile, provider: string): ReportTile {
+	const tile: {
+		key: string;
+		label: string;
+		tileLabelKey?: string;
+		value: number;
+		unit?: string;
+		delta?: number;
+	} = {
+		key: bounded(value?.key, 'tile key', 1, REPORT_PROVIDER_LIMITS.key),
+		label: bounded(value.label, 'tile label', 1, REPORT_PROVIDER_LIMITS.label),
+		value: finite(value.value, provider, 'tile value'),
+	};
+	if (value.tileLabelKey !== undefined && value.tileLabelKey !== null) {
+		tile.tileLabelKey = bounded(
+			value.tileLabelKey,
+			'tile label key',
+			1,
+			REPORT_PROVIDER_LIMITS.key,
+		);
+	}
+	if (value.unit !== undefined && value.unit !== null) {
+		tile.unit = bounded(
+			value.unit,
+			'tile unit',
+			0,
+			REPORT_PROVIDER_LIMITS.unit,
+		);
+	}
+	if (value.delta !== undefined && value.delta !== null) {
+		tile.delta = finite(value.delta, provider, 'tile delta');
+	}
+	return tile;
+}
+
+function readSeries(value: ReportSeries, provider: string): ReportSeries {
+	if (!Array.isArray(value?.points)) {
+		throw new ReportsServiceError(
+			'PROVIDER_ANSWER_INVALID',
+			`Report provider "${provider}" answered with a series without points.`,
+			502,
+		);
+	}
+	if (value.points.length > REPORT_PROVIDER_LIMITS.points) {
+		throw new ReportsServiceError(
+			'PROVIDER_ANSWER_INVALID',
+			`Report provider "${provider}" answered with more than ${REPORT_PROVIDER_LIMITS.points} points.`,
+			502,
+		);
+	}
+	return {
+		key: bounded(value.key, 'series key', 1, REPORT_PROVIDER_LIMITS.key),
+		label: bounded(
+			value.label,
+			'series label',
+			1,
+			REPORT_PROVIDER_LIMITS.label,
+		),
+		...(value.seriesLabelKey === undefined || value.seriesLabelKey === null
+			? {}
+			: {
+					seriesLabelKey: bounded(
+						value.seriesLabelKey,
+						'series label key',
+						1,
+						REPORT_PROVIDER_LIMITS.key,
+					),
+				}),
+		points: value.points.map((point) => ({
+			at: bounded(point?.at, 'point position', 1, REPORT_PROVIDER_LIMITS.at),
+			value: finite(point.value, provider, 'point value'),
+		})),
+	};
+}
+
+/**
+ * What a provider answered, checked and bounded. A provider is foreign code on
+ * a request path: nothing it returns reaches a response before it is read here,
+ * and anything unreadable makes that provider unavailable rather than failing
+ * the whole report.
+ */
+export function readAnswer(
+	answer: ReportProviderAnswer,
+	provider: RegisteredReportProvider,
+): {
+	readonly tiles: readonly ReportTile[];
+	readonly series: readonly ReportSeries[];
+	readonly period?: ReportRange;
+} {
+	if (!answer || !Array.isArray(answer.tiles)) {
+		throw new ReportsServiceError(
+			'PROVIDER_ANSWER_INVALID',
+			`Report provider "${provider.key}" answered without tiles.`,
+			502,
+		);
+	}
+	if (answer.tiles.length > REPORT_PROVIDER_LIMITS.tiles) {
+		throw new ReportsServiceError(
+			'PROVIDER_ANSWER_INVALID',
+			`Report provider "${provider.key}" answered with more than ${REPORT_PROVIDER_LIMITS.tiles} tiles.`,
+			502,
+		);
+	}
+	const series = answer.series ?? [];
+	if (!Array.isArray(series) || series.length > REPORT_PROVIDER_LIMITS.series) {
+		throw new ReportsServiceError(
+			'PROVIDER_ANSWER_INVALID',
+			`Report provider "${provider.key}" answered with more than ${REPORT_PROVIDER_LIMITS.series} series.`,
+			502,
+		);
+	}
+	return {
+		tiles: answer.tiles.map((tile) => readTile(tile, provider.key)),
+		series: series.map((entry) => readSeries(entry, provider.key)),
+		/* Bounded like a point position and not checked for shape: a period the
+		   screen cannot parse is captioned as the text it is, which costs a
+		   caption, while refusing it would cost the reader the numbers. */
+		...(answer.period === undefined || answer.period === null
+			? {}
+			: {
+					period: {
+						from: bounded(
+							answer.period.from,
+							'period start',
+							1,
+							REPORT_PROVIDER_LIMITS.at,
+						),
+						to: bounded(
+							answer.period.to,
+							'period end',
+							1,
+							REPORT_PROVIDER_LIMITS.at,
+						),
+					},
+				}),
+	};
+}
+
+/**
+ * One provider call, bounded by the time budget. The losing side of the race is
+ * always settled, so an abandoned provider cannot surface later as an unhandled
+ * rejection, and the abort listener is removed either way.
+ */
+async function runProvider(
+	provider: RegisteredReportProvider,
+	input: Omit<Parameters<RegisteredReportProvider['read']>[0], 'signal'>,
+	timeoutMs: number,
+): Promise<ReportProviderAnswer> {
+	const signal = AbortSignal.timeout(timeoutMs);
+	let onAbort: (() => void) | undefined;
+	const expiry = new Promise<never>((_resolve, reject) => {
+		onAbort = () =>
+			reject(
+				new ReportsServiceError(
+					'PROVIDER_TIMEOUT',
+					`Report provider "${provider.key}" exceeded its ${timeoutMs} ms budget.`,
+					504,
+				),
+			);
+		signal.addEventListener('abort', onAbort, { once: true });
+	});
+	expiry.catch(() => undefined);
+	try {
+		return await Promise.race([provider.read({ ...input, signal }), expiry]);
+	} finally {
+		if (onAbort) signal.removeEventListener('abort', onAbort);
+	}
+}
+
+export class ReportsService {
+	readonly #registry: MutableReportProviderRegistry;
+	readonly #budget: () => ReportsBudget;
+
+	constructor(options: ReportsServiceOptions) {
+		this.#registry = options.registry;
+		this.#budget = options.budget;
+	}
+
+	/** Every provider whose permission this principal holds, in merge order. */
+	providers(principal: ReportPrincipal): readonly ReportProviderSummary[] {
+		return this.#permitted(principal).map(summary);
+	}
+
+	/**
+	 * The workspace report for one range. Every permitted provider is asked in
+	 * parallel under the same budget; one that fails, times out or answers
+	 * something unreadable is named in `unavailable` and costs the reader that
+	 * provider's numbers, never the report.
+	 */
+	async read(input: ReportsQueryInput): Promise<WorkspaceReportPage> {
+		const permitted = this.#permitted(input.principal);
+		const timeoutMs = this.#timeout();
+		/* The only tenant a provider ever sees, taken from the principal the
+		   endpoint resolved and never from anything the request carried. */
+		const tenantId = bounded(
+			input.principal.tenantId,
+			'tenantId',
+			1,
+			REPORT_LIMITS.tenantId,
+		);
+		const settled = await Promise.allSettled(
+			permitted.map((provider) =>
+				runProvider(
+					provider,
+					{ tenantId, principal: input.principal, range: input.range },
+					timeoutMs,
+				),
+			),
+		);
+
+		const reports: WorkspaceReport[] = [];
+		const unavailable: string[] = [];
+		for (let index = 0; index < permitted.length; index += 1) {
+			const provider = permitted[index]!;
+			const result = settled[index]!;
+			if (result.status !== 'fulfilled') {
+				unavailable.push(provider.key);
+				continue;
+			}
+			try {
+				reports.push({
+					...summary(provider),
+					...readAnswer(result.value, provider),
+				});
+			} catch {
+				/* A provider that answers nonsense is unavailable for this request;
+				   it never turns the reader's whole report into an error. */
+				unavailable.push(provider.key);
+			}
+		}
+		return { range: input.range, reports, unavailable };
+	}
+
+	/* Filtering happens here, before any call: a provider the reader may not
+	   see is never asked, never listed and never named as unavailable, so the
+	   report does not reveal that it exists. */
+	#permitted(principal: ReportPrincipal): readonly RegisteredReportProvider[] {
+		const granted = new Set(principal.scopes);
+		return this.#registry
+			.list()
+			.filter((provider) => granted.has(provider.permission));
+	}
+
+	#timeout(): number {
+		const value = this.#budget().providerTimeoutMs;
+		if (!Number.isFinite(value)) return PROVIDER_TIMEOUT_RANGE.minimum;
+		return Math.min(
+			PROVIDER_TIMEOUT_RANGE.maximum,
+			Math.max(PROVIDER_TIMEOUT_RANGE.minimum, Math.trunc(value)),
+		);
+	}
+}

package/modules/reports/src/services/service-error.ts

@@ -0,0 +1,26 @@
+export class ReportsServiceError extends Error {
+	constructor(
+		readonly code: string,
+		message: string,
+		readonly status = 400,
+	) {
+		super(message);
+		this.name = 'ReportsServiceError';
+	}
+}
+
+export function bounded(
+	value: unknown,
+	field: string,
+	min: number,
+	max: number,
+): string {
+	const normalized = typeof value === 'string' ? value.trim() : '';
+	if (normalized.length < min || normalized.length > max) {
+		throw new ReportsServiceError(
+			'INVALID_INPUT',
+			`${field} must contain between ${min} and ${max} characters.`,
+		);
+	}
+	return normalized;
+}

package/modules/reports/src/settings.ts

@@ -0,0 +1,49 @@
+import {
+	defineModuleSettings,
+	PLATFORM_SETTINGS_TENANT,
+	type ModuleSettingsRuntime,
+} from '@flowdular/sdk/kernel';
+import {
+	PROVIDER_TIMEOUT_RANGE,
+	type ReportsBudget,
+} from './services/reports-service.ts';
+
+export const REPORTS_MODULE_ID = 'reports.core';
+
+const DEFAULT_PROVIDER_TIMEOUT_MS = 3_000;
+
+export const REPORTS_MODULE_SETTINGS = defineModuleSettings({
+	moduleId: REPORTS_MODULE_ID,
+	settings: {
+		providerTimeoutMs: {
+			type: 'number',
+			defaultValue: DEFAULT_PROVIDER_TIMEOUT_MS,
+			min: PROVIDER_TIMEOUT_RANGE.minimum,
+			max: PROVIDER_TIMEOUT_RANGE.maximum,
+			visibility: 'shared',
+			client: false,
+			scope: 'platform',
+			labelKey: 'reports.settings.providerTimeoutMs.label',
+			label: 'Provider time budget (ms)',
+			descriptionKey: 'reports.settings.providerTimeoutMs.description',
+			description:
+				'Time one provider gets per request before it is reported unavailable.',
+		},
+	},
+});
+
+/* A settings read must never take a request down, so the accessor falls back to
+   the declared default when the runtime has not registered it yet. */
+export function reportsBudget(settings: ModuleSettingsRuntime): ReportsBudget {
+	try {
+		return {
+			providerTimeoutMs: settings.get<number>(
+				PLATFORM_SETTINGS_TENANT,
+				REPORTS_MODULE_ID,
+				'providerTimeoutMs',
+			),
+		};
+	} catch {
+		return { providerTimeoutMs: DEFAULT_PROVIDER_TIMEOUT_MS };
+	}
+}

package/modules/reports/translations/en.json

@@ -0,0 +1,35 @@
+{
+	"module.name": "Reports",
+	"navigation.label": "Reports",
+	"navigation.description": "One workspace report composed from what each module already counts.",
+	"page.eyebrow": "Administration",
+	"page.title": "Reports",
+	"page.description": "Every module that keeps a rollup answers for the range you choose. Numbers you may not see are never asked for.",
+	"action.refresh": "Refresh",
+	"action.refreshing": "Refreshing…",
+	"range.legend": "Date range",
+	"range.from": "From",
+	"range.to": "To",
+	"range.help": "UTC days, both included. At most 400 days.",
+	"range.reversed": "The end of the range is before its start.",
+	"range.tooWide": "The range must cover at most {days} days.",
+	"report.range": "{module} · {from} to {to}",
+	"report.emptyTitle": "Nothing counted in this range",
+	"report.emptyHint": "This module kept no numbers for the days you picked.",
+	"tile.delta": "{delta} against the previous period",
+	"series.emptyTitle": "No points in this range",
+	"series.emptyHint": "Pick a wider range to see the line.",
+	"unavailable": "These modules could not answer and are missing from the report: {providers}.",
+	"loading.title": "Asking every module…",
+	"loading.hint": "Each module answers for its own numbers.",
+	"empty.title": "No numbers yet",
+	"empty.hint": "A module contributes to this report once it keeps a rollup you may read.",
+	"denied.title": "Access denied",
+	"denied.hint": "Reading the workspace report needs the reports.workspace.read scope.",
+	"widget.link": "Open reports",
+	"error.load": "Could not load the workspace report.",
+	"error.request": "The reports operation failed.",
+	"error.code.INVALID_RANGE": "The date range is not valid.",
+	"settings.providerTimeoutMs.label": "Provider time budget (ms)",
+	"settings.providerTimeoutMs.description": "Time one provider gets per request before it is reported unavailable."
+}

package/modules/reports/translations/pl.json

@@ -0,0 +1,35 @@
+{
+	"module.name": "Raporty",
+	"navigation.label": "Raporty",
+	"navigation.description": "Jeden raport przestrzeni złożony z tego, co każdy moduł już liczy.",
+	"page.eyebrow": "Administracja",
+	"page.title": "Raporty",
+	"page.description": "Każdy moduł, który prowadzi własne zestawienie, odpowiada za wybrany zakres. O dane bez uprawnienia nikt nie pyta.",
+	"action.refresh": "Odśwież",
+	"action.refreshing": "Odświeżanie…",
+	"range.legend": "Zakres dat",
+	"range.from": "Od",
+	"range.to": "Do",
+	"range.help": "Dni UTC, oba włącznie. Najwyżej 400 dni.",
+	"range.reversed": "Koniec zakresu wypada przed jego początkiem.",
+	"range.tooWide": "Zakres może obejmować najwyżej {days} dni.",
+	"report.range": "{module} · {from} do {to}",
+	"report.emptyTitle": "Brak danych w tym zakresie",
+	"report.emptyHint": "Ten moduł nie ma liczb dla wybranych dni.",
+	"tile.delta": "{delta} wobec poprzedniego okresu",
+	"series.emptyTitle": "Brak punktów w tym zakresie",
+	"series.emptyHint": "Wybierz szerszy zakres, aby zobaczyć wykres.",
+	"unavailable": "Te moduły nie mogły odpowiedzieć i brakuje ich w raporcie: {providers}.",
+	"loading.title": "Pytamy każdy moduł…",
+	"loading.hint": "Każdy moduł odpowiada za własne liczby.",
+	"empty.title": "Jeszcze brak liczb",
+	"empty.hint": "Moduł trafi do raportu, gdy będzie prowadził zestawienie dostępne dla Ciebie.",
+	"denied.title": "Brak dostępu",
+	"denied.hint": "Odczyt raportu przestrzeni wymaga uprawnienia reports.workspace.read.",
+	"widget.link": "Otwórz raporty",
+	"error.load": "Nie udało się wczytać raportu przestrzeni.",
+	"error.request": "Operacja raportów nie powiodła się.",
+	"error.code.INVALID_RANGE": "Zakres dat jest nieprawidłowy.",
+	"settings.providerTimeoutMs.label": "Budżet czasu dostawcy (ms)",
+	"settings.providerTimeoutMs.description": "Czas, jaki jeden dostawca dostaje na żądanie, zanim zostanie uznany za niedostępny."
+}