@nodefony/framework 10.0.0-alpha.1

package/dist/nodefony/src/FrameworkAdminApi.js

@@ -0,0 +1,268 @@
+import router_default from "../service/router.js";
+import { createPlaygroundEndpoints } from "./PlaygroundAdminApi.js";
+import { parseFilters, parsePageQuery } from "nodefony";
+//#region nodefony/src/FrameworkAdminApi.ts
+/**
+* Capacités de page d'un endpoint, ÉVALUÉES sous filet.
+*
+* `sortable` et `search` sont des fonctions parce que la réponse dépend du
+* store effectivement branché au démarrage — donc elles peuvent lever. Ce
+* catalogue est lu au chargement de la console : une exception ici privait
+* l'application entière de sa navigation à cause d'un seul module en panne. Ne
+* rien publier est le repli sûr — le plan REFUSE en 400 ce qui n'est pas
+* déclaré, une capacité tue ne promet donc rien de faux.
+*
+* @param caps - la déclaration du producteur, ou `undefined`.
+* @returns le fragment `{ page }` à fusionner, ou rien.
+*/
+function readPageCapabilities(caps) {
+	if (!caps) return {};
+	try {
+		return { page: {
+			sortable: caps.sortable?.() ?? [],
+			filters: caps.filters ?? {},
+			search: caps.search?.() ?? false,
+			facets: caps.facets ?? {}
+		} };
+	} catch {
+		return {};
+	}
+}
+/**
+* Producteur `IAdminApi` du module **framework** — exposé sous
+* `/nodefony/framework/api/*`.
+*
+* 3ᵉ producteur du data plane admin (kernel, http, puis framework). Introspecte
+* le **Router** : c'est l'équivalent web de `nodefony router:dump` et la source
+* de la future vue « Routes » de Studio (P10.8).
+*
+* Le framework héberge le broker → il s'enregistre directement (pas besoin de
+* passer par `IAdminRegistry` du container comme un module externe).
+*
+* Endpoints :
+*  - `GET /nodefony/framework/api/routes` → toutes les routes enregistrées
+*  - `GET /nodefony/framework/api/info`   → résumé (nb routes, méthodes, modules)
+*  - `GET /nodefony/framework/api/admin`  → **catalogue** du data plane admin
+*    (tous les producteurs + descriptors + endpoints) — pièce « discovery »
+*    de P10.2 que Studio lit pour générer sa navigation admin.
+*
+* @param broker - le broker admin (pour le catalogue). Optionnel : sans lui,
+*   `admin` renvoie une liste vide.
+* @param opts - composition (`playground: true` → endpoints Playground, dev-only).
+* @returns le contrat admin de framework, prêt à `broker.register()`.
+*/
+function createFrameworkAdminApi(broker, opts) {
+	/** Normalise `requirements.methods` (string | string[]) → tableau majuscule. */
+	const methodsOf = (route) => {
+		const m = route.requirements?.methods ?? route.method;
+		if (Array.isArray(m)) return m.map((x) => String(x).toUpperCase());
+		if (typeof m === "string") return m.split(",").map((s) => s.trim().toUpperCase()).filter(Boolean);
+		return ["ANY"];
+	};
+	const serializeRoute = (route) => ({
+		name: route.name,
+		path: route.path ?? null,
+		methods: methodsOf(route),
+		controller: route.controller?.name ?? null,
+		action: route.classMethod ?? null,
+		module: route.module?.name ?? null,
+		host: route.host ?? null,
+		bypassFirewall: route.bypassFirewall
+	});
+	const descriptor = {
+		label: "Routes",
+		icon: "route",
+		order: 2
+	};
+	/** Premier param d'une query (string|string[]). */
+	const one = (v) => Array.isArray(v) ? v[0] : v;
+	/**
+	* Colonnes sur lesquelles `routes/page` sait trier — l'allowlist que
+	* `parsePageQuery` fait respecter. Elle a exactement les clés que {@link cell}
+	* sait rendre : un `order` sur autre chose est refusé (400) au lieu de trier
+	* sur une chaîne vide, ce qui rendait l'ordre arbitraire sans le dire.
+	*/
+	const SORTABLE_COLUMNS = [
+		"methods",
+		"path",
+		"name",
+		"controller",
+		"module",
+		"firewall"
+	];
+	/**
+	* `routes/page` sait TOUJOURS chercher : sa collection est le dump du Router,
+	* en mémoire, donc `q` est un simple balayage — ce qui n'est vrai d'aucune
+	* ressource persistée, d'où la déclaration explicite plutôt qu'un défaut.
+	*
+	* Constante partagée entre la publication (`page.search`) et le handler
+	* (`parsePageQuery(..., { searchable })`) : les écrire séparément recréerait
+	* la divergence que la publication vient supprimer — une console qui affiche
+	* une barre de recherche que le serveur refuse en 400.
+	*/
+	const SEARCHABLE = true;
+	/** Valeur d'une colonne pour le tri/filtre serveur (clés = colonnes du front). */
+	const cell = (r, key) => {
+		switch (key) {
+			case "methods": return r.methods.join(",");
+			case "path": return r.path ?? "";
+			case "name": return r.name ?? "";
+			case "controller": return [r.controller, r.action].filter(Boolean).join(".");
+			case "module": return r.module ?? "";
+			case "firewall": return r.bypassFirewall ? "bypass" : "protected";
+			default: return "";
+		}
+	};
+	/**
+	* Applique un opérateur de filtre (miroir serveur du DataGrid).
+	*
+	* ⚠️ **Ce langage d'opérateurs appartient à CET endpoint, pas au framework.**
+	* Le contrat de filtre (`parseFilters`, cœur) est `nom=valeur` sans opérateur ;
+	* `routes/page` peut se permettre davantage parce que sa collection est en
+	* mémoire (le dump du Router) et qu'aucun store n'a à l'indexer. Un data plane
+	* adossé à une ressource persistée déclare un `IFilterSpec` et laisse le cœur
+	* valider — il ne recopie pas ce `matchOp`.
+	*/
+	const matchOp = (raw, op, value) => {
+		const s = String(raw ?? "");
+		const v = String(value ?? "");
+		if (op !== "isEmpty" && op !== "notEmpty" && v === "") return true;
+		switch (op) {
+			case "contains": return s.toLowerCase().includes(v.toLowerCase());
+			case "equals": return s === v;
+			case "in": {
+				const split = (list) => list.split(",").map((t) => t.trim()).filter((t) => t !== "");
+				const wanted = split(v);
+				if (wanted.length === 0) return true;
+				return split(s).some((c) => wanted.includes(c));
+			}
+			case "startsWith": return s.toLowerCase().startsWith(v.toLowerCase());
+			case "endsWith": return s.toLowerCase().endsWith(v.toLowerCase());
+			case "isEmpty": return s === "";
+			case "notEmpty": return s !== "";
+			default: return true;
+		}
+	};
+	const endpoints = [
+		{
+			path: "routes",
+			summary: "All registered routes (Router dump) — name, path, methods, controller",
+			handler: () => router_default.routes.map(serializeRoute)
+		},
+		{
+			path: "routes/page",
+			summary: "Routes paginées côté SERVEUR — contrat IPageQuery : ?limit&offset&order=champ:ASC&q, plus filters(JSON) — langage d'opérateurs PROPRE à cet endpoint (collection en mémoire), sérialisé par la vue Routes seule. Rend un IPage.",
+			page: {
+				sortable: () => SORTABLE_COLUMNS,
+				search: () => SEARCHABLE
+			},
+			handler: (request) => {
+				const query = parsePageQuery(request.query, {
+					defaultLimit: 25,
+					sortable: SORTABLE_COLUMNS,
+					searchable: SEARCHABLE
+				});
+				parseFilters(request.query, {}, { accepts: ["filters"] });
+				const search = query.q?.toLowerCase() ?? "";
+				let filters = [];
+				try {
+					const raw = one(request.query.filters);
+					if (raw) filters = JSON.parse(raw);
+				} catch {
+					filters = [];
+				}
+				let rows = router_default.routes.map(serializeRoute);
+				if (search) rows = rows.filter((r) => [
+					r.methods.join(","),
+					r.path,
+					r.name,
+					r.controller,
+					r.action,
+					r.module,
+					r.bypassFirewall ? "bypass" : "protected"
+				].filter(Boolean).join(" ").toLowerCase().includes(search));
+				for (const f of filters) rows = rows.filter((r) => matchOp(cell(r, f.key), f.op, f.value));
+				const total = rows.length;
+				if (query.order?.length) {
+					const order = query.order;
+					rows = [...rows].sort((a, b) => {
+						for (const [key, dir] of order) {
+							const cmp = cell(a, key).localeCompare(cell(b, key));
+							if (cmp !== 0) return dir === "DESC" ? -cmp : cmp;
+						}
+						return 0;
+					});
+				}
+				const offset = query.offset ?? 0;
+				return {
+					items: rows.slice(offset, offset + query.limit),
+					total,
+					limit: query.limit,
+					offset,
+					hasNext: offset + query.limit < total
+				};
+			}
+		},
+		{
+			path: "info",
+			summary: "Routing summary — total routes, methods, owning modules",
+			handler: () => {
+				const routes = router_default.routes;
+				const methods = /* @__PURE__ */ new Set();
+				const modules = /* @__PURE__ */ new Set();
+				for (const r of routes) {
+					methodsOf(r).forEach((m) => methods.add(m));
+					if (r.module?.name) modules.add(r.module.name);
+				}
+				return {
+					routesTotal: routes.length,
+					methods: [...methods].sort(),
+					modules: [...modules].sort()
+				};
+			}
+		},
+		{
+			path: "admin",
+			summary: "Admin data plane catalog — producers, descriptors, endpoints",
+			handler: () => {
+				if (!broker) return { producers: [] };
+				const descByNs = new Map(broker.list().map((p) => [p.adminNamespace, p.adminDescriptor()]));
+				const byNs = /* @__PURE__ */ new Map();
+				for (const r of broker.routes()) {
+					let arr = byNs.get(r.namespace);
+					if (!arr) {
+						arr = [];
+						byNs.set(r.namespace, arr);
+					}
+					const caps = r.endpoint.page;
+					arr.push({
+						method: r.method,
+						path: r.path,
+						role: r.role,
+						summary: r.endpoint.summary ?? null,
+						...readPageCapabilities(caps)
+					});
+				}
+				return { producers: [...byNs.keys()].map((ns) => {
+					const d = descByNs.get(ns);
+					return {
+						namespace: ns,
+						label: d?.label ?? ns,
+						icon: d?.icon ?? null,
+						order: d?.order ?? 99,
+						role: d?.role ?? null,
+						endpoints: byNs.get(ns)
+					};
+				}).sort((a, b) => a.order - b.order) };
+			}
+		}
+	];
+	if (opts?.playground) endpoints.push(...createPlaygroundEndpoints());
+	return {
+		adminNamespace: "framework",
+		adminDescriptor: () => descriptor,
+		adminEndpoints: () => endpoints
+	};
+}
+//#endregion
+export { createFrameworkAdminApi };