@nodefony/framework 10.0.0-beta.2 → 10.0.0-beta.4

package/dist/nodefony/service/router.js

@@ -1,13 +1,12 @@
 import Route from "../src/Route.js";
-import { routeExpectsBodyStream } from "../decorators/routerDecorators.js";
+import { assertRouteSchemaDeclaration, routeExpectsBodyStream } from "../decorators/routerDecorators.js";
 import Resolver from "../src/Resolver.js";
-import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
-import __decorate from "../../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
-import { Injector, Module, Service, injectable, isPromise } from "nodefony";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.155.0/helpers/esm/decorate.js";
+import { BootConfigurationError, Injector, Module, Service, injectable, isPromise, stripTrailingSlashes } from "nodefony";
 import { HttpError, isDomainAllowed } from "@nodefony/http";
-//#region nodefony/service/router.ts
+// nodefony/service/router.ts
 var _Router;
-let routeNoticePromoted = null;
+let routeMatchLogged = null;
 /**
 * Méthodes que sert une route — lues sur le `methodsSet` COMPILÉ par
 * `Route.compileRequirements`, jamais recalculées depuis la config brute.
@@ -52,25 +51,13 @@ function invalidateRouteIndex() {
 function buildRouteIndex() {
 	const statics = /* @__PURE__ */ new Map();
 	const dynamics = [];
-	for (const [i, route] of routes.entries()) {
-		const path = route.path;
-		if (path !== void 0 && route.variables.length === 0 && !REG_NON_LITERAL.test(path)) {
-			const key = path.toLowerCase();
-			let list = statics.get(key);
-			if (list === void 0) {
-				list = [];
-				statics.set(key, list);
-			}
-			list.push({
-				route,
-				pos: i,
-				prefix: ""
-			});
-		} else dynamics.push({
-			route,
-			pos: i,
-			prefix: literalPrefix(path)
-		});
+	const total = routes.length;
+	for (let pass = 0; pass < 2; pass++) {
+		const fallbackPass = pass === 1;
+		for (const [rank, route] of routes.entries()) {
+			if (route.fallback !== fallbackPass) continue;
+			indexRoute(route, fallbackPass ? total + rank : rank, statics, dynamics);
+		}
 	}
 	return routeIndex = {
 		statics,
@@ -80,10 +67,45 @@ function buildRouteIndex() {
 		last: routes[routes.length - 1]
 	};
 }
+/**
+* Range une route dans l'index — littérale par son chemin exact, dynamique
+* sinon — à la position `i` qui décide de son rang dans la fusion de `resolve`.
+*/
+function indexRoute(route, i, statics, dynamics) {
+	const path = route.path;
+	if (path !== void 0 && route.variables.length === 0 && !REG_NON_LITERAL.test(path)) {
+		const key = path.toLowerCase();
+		let list = statics.get(key);
+		if (list === void 0) {
+			list = [];
+			statics.set(key, list);
+		}
+		list.push({
+			route,
+			pos: i,
+			prefix: ""
+		});
+	} else dynamics.push({
+		route,
+		pos: i,
+		prefix: literalPrefix(path)
+	});
+}
+/**
+* Marque du Router de `@nodefony/framework` — ce que {@link isFrameworkRouter}
+* lit. `Symbol.for` : la même marque pour deux copies installées du framework,
+* là où `instanceof` échouerait en silence. Un faux routeur de test s'en
+* réclame explicitement.
+*/
+const FRAMEWORK_ROUTER = Symbol.for("nodefony.framework.router");
 let Router = class Router extends Service {
 	static {
 		_Router = this;
 	}
+	/** Marque {@link FRAMEWORK_ROUTER} — sur le prototype, aucun champ par instance. */
+	get [FRAMEWORK_ROUTER]() {
+		return true;
+	}
 	static routes = routes;
 	routes = _Router.routes;
 	singletonControllers = null;
@@ -127,6 +149,23 @@ let Router = class Router extends Service {
 		return pending;
 	}
 	/**
+	* Dit si au moins une route déclare le transport `WEBSOCKET` pour ce chemin
+	* — contrôle d'avant `101` du pipeline WebSocket (cf `IRequestRouter`).
+	*
+	* Parcours de la table entière, sans l'index de `resolve` : il est lu une
+	* fois par CONNEXION (pas par message), et une route dont les méthodes
+	* changent après coup (`addRequirement`) ne laisse ainsi aucun index périmé.
+	* Même normalisation que `resolve` (`stripTrailingSlashes`), même motif.
+	*
+	* @param pathname - chemin de l'URL d'upgrade
+	* @returns `true` si une route WebSocket a un motif qui couvre ce chemin
+	*/
+	servesWebsocket(pathname) {
+		const path = stripTrailingSlashes(pathname);
+		for (const route of routes) if (route.methodsSet?.has("WEBSOCKET") === true && route.pattern?.test(path) === true) return true;
+		return false;
+	}
+	/**
 	* Résout une route pour un contexte donné.
 	*
 	* @param context - le contexte HTTP/WS courant (porte container, méthode, URL…).
@@ -138,7 +177,10 @@ let Router = class Router extends Service {
 	*   WEBSOCKET (pont WS-RPC `api.request` d'une MUTATION) : lève l'ambiguïté
 	*   GET-via-WS / POST-via-WS sur un même chemin (`context.method` = "WEBSOCKET").
 	*   `undefined` (GET/HTTP) → match historique sur `context.method`.
-	* @returns un `Resolver` (`.resolve === true` si une route a matché).
+	* @returns un `Resolver` (`.resolve === true` si une route a matché) — ou,
+	*   pour un chemin servi en WebSocket SEULEMENT et demandé en HTTP, un
+	*   `Resolver` dont `exception` porte le `426` (en-têtes `Upgrade` posés) :
+	*   le pipeline le lève après le pare-feu.
 	*/
 	resolve(context, cleanPathOverride, methodOverride) {
 		const resolver = new Resolver(context);
@@ -171,8 +213,8 @@ let Router = class Router extends Service {
 			}
 			try {
 				if (resolver.match(route, context, cleanPath, fromLiterals)) {
-					routeNoticePromoted ??= this.kernel?.environment !== "production";
-					if (routeNoticePromoted) this.log(`Match route : ${route.name}`, "NOTICE");
+					routeMatchLogged ??= this.kernel?.environment !== "production";
+					if (routeMatchLogged) this.log(`Match route : ${route.name}`, "DEBUG");
 					resolver.exception = void 0;
 					routeExpectsBodyStream(route);
 					return resolver;
@@ -192,11 +234,13 @@ let Router = class Router extends Service {
 			}
 			const servesWebsocket = allowed.delete("WEBSOCKET");
 			if (allowed.size === 0 && servesWebsocket) {
-				context.response?.setHeaders({
+				const req = context.request;
+				if ((req && "request" in req ? req.request : req)?.httpVersionMajor !== 2) context.response?.setHeaders({
 					Upgrade: "websocket",
 					Connection: "Upgrade"
 				});
-				throw new HttpError("Upgrade Required: websocket", 426, context);
+				resolver.exception = new HttpError("Upgrade Required: websocket", 426, context);
+				return resolver;
 			}
 			if (allowed.size > 0) {
 				const allowHeader = Array.from(allowed).join(", ");
@@ -247,6 +291,7 @@ let Router = class Router extends Service {
 		}
 	}
 	static createRoute(name, obj) {
+		if ("schema" in obj || "bodyStream" in obj) throw new BootConfigurationError(`Route "${name}" : « schema » et « bodyStream » se déclarent par un décorateur de route (@Get, @Post, @route…), pas par createRoute.`);
 		const routenew = new Route(name, obj);
 		routes.push(routenew);
 		invalidateRouteIndex();
@@ -278,7 +323,10 @@ let Router = class Router extends Service {
 		});
 		const key = `${module.name}:${myconstructor.name}`;
 		if (Module.controllers[key]) module.log(/* @__PURE__ */ new Error(`Controller already exist ${key}`), "WARNING");
-		for (const r of routes) if (r.controller === myconstructor) r.module = { name: module.name };
+		for (const r of routes) if (r.controller === myconstructor) {
+			assertRouteSchemaDeclaration(r);
+			r.module = { name: module.name };
+		}
 		return Module.controllers[key] = myconstructor;
 	}
 	/**
@@ -290,7 +338,22 @@ let Router = class Router extends Service {
 		return routes.filter((r) => r.controller === myconstructor);
 	}
 };
-Router = _Router = __decorate([injectable(), __decorateMetadata("design:paramtypes", [typeof Module === "undefined" ? Object : Module])], Router);
+Router = _Router = __decorate([injectable()], Router);
+/**
+* Dit si le service `router` d'un contexte est le Router de
+* `@nodefony/framework` — la garde qui rétrécit le contrat `IRequestRouter` de
+* `@nodefony/http` sans conversion, pour qui lit des membres propres au
+* framework (le Resolver complet que rend `resolve`).
+*
+* Lit la marque {@link FRAMEWORK_ROUTER}, jamais `instanceof` : deux copies
+* installées du framework feraient échouer `instanceof` en silence. Une
+* lecture de propriété.
+*
+* @param router - le routeur lu sur le contexte (`context.router`).
+* @returns `true` si c'est le Router du framework.
+*/
+function isFrameworkRouter(router) {
+	return router != null && FRAMEWORK_ROUTER in router;
+}
 var router_default = Router;
-//#endregion
-export { router_default as default };
+export { FRAMEWORK_ROUTER, router_default as default, isFrameworkRouter };

package/dist/nodefony/src/Controller.js

@@ -1,9 +1,9 @@
 import { isDevelopment, singletonWriteMessage } from "./singletonGuard.js";
 import { FileClass, RequestContext, Service } from "nodefony";
-import { HttpError } from "@nodefony/http";
+import { HttpContext, HttpError, acceptsEventStream } from "@nodefony/http";
 import fs, { createReadStream } from "node:fs";
 import { promisify } from "node:util";
-//#region nodefony/src/Controller.ts
+// nodefony/src/Controller.ts
 const fsClose = promisify(fs.close);
 /**
 * Un `<script>` EN LIGNE qui ne porte pas d'attribut `nonce`.
@@ -108,10 +108,9 @@ var Controller = class extends Service {
 	#request = null;
 	#response = null;
 	#method = null;
-	#queryGet = null;
 	#query = null;
-	#queryFile = null;
-	#queryPost = null;
+	#files = null;
+	#body = null;
 	module;
 	template;
 	/**
@@ -167,6 +166,15 @@ var Controller = class extends Service {
 		this.#assertPerRequest("response");
 		this.#response = response;
 	}
+	/**
+	* L'utilisateur CONNECTÉ, ou `null` — anonyme, ou route hors de toute zone
+	* du pare-feu. C'est l'identité que le pare-feu a établie pour cette
+	* requête : aucun appel de plus. Une page publique qui veut savoir qui la
+	* visite se place sous une zone `authenticators: ["session", "anonymous"]`.
+	*/
+	get user() {
+		return RequestContext.getAuthenticatedUser();
+	}
 	get method() {
 		return this.#method ?? this.context?.method ?? void 0;
 	}
@@ -175,21 +183,11 @@ var Controller = class extends Service {
 		this.#method = method ?? null;
 	}
 	/**
-	* Query string de l'appel en cours — pour un singleton invoqué par le pont
-	* `api.request`, celle du chemin INVOQUÉ (résolveur d'appel dans l'ALS), pas
-	* celle du handshake de la connexion. Une seule lecture de l'ALS.
+	* Paramètres d'URL de l'appel en cours — jamais le corps, qui reste dans
+	* {@link body}. Pour un singleton invoqué par le pont `api.request`,
+	* ceux du chemin INVOQUÉ (résolveur d'appel dans l'ALS), pas ceux du
+	* handshake de la connexion. Une seule lecture de l'ALS.
 	*/
-	get queryGet() {
-		if (this.#queryGet !== null) return this.#queryGet;
-		if (this.#context !== null) return this.#context.request?.queryGet;
-		const store = RequestContext.get();
-		return (store?.resolver)?.queryOverride ?? ((store?.context)?.request)?.queryGet;
-	}
-	set queryGet(value) {
-		this.#assertPerRequest("queryGet");
-		this.#queryGet = value;
-	}
-	/** Comme {@link queryGet}, pour la query fusionnée (`query`). */
 	get query() {
 		if (this.#query !== null) return this.#query;
 		if (this.#context !== null) return this.#context.request?.query;
@@ -200,35 +198,30 @@ var Controller = class extends Service {
 		this.#assertPerRequest("query");
 		this.#query = value;
 	}
-	get queryFile() {
-		return this.#queryFile ?? (this.context?.request)?.queryFile;
-	}
-	set queryFile(value) {
-		this.#assertPerRequest("queryFile");
-		this.#queryFile = value;
-	}
-	get queryPost() {
-		return this.#queryPost ?? (this.context?.request)?.queryPost;
+	/**
+	* Les fichiers reçus dans un corps multipart (`UploadedFile`) ; les champs
+	* texte du même corps sont dans {@link body}. Pour une action typée,
+	* préférer `@UploadedFiles()`.
+	*/
+	get files() {
+		return this.#files ?? (this.context?.request)?.files;
 	}
-	set queryPost(value) {
-		this.#assertPerRequest("queryPost");
-		this.#queryPost = value;
+	set files(value) {
+		this.#assertPerRequest("files");
+		this.#files = value;
 	}
 	/**
 	* Le CORPS de la requête, parsé — nom universel de l'écosystème (Express,
-	* Fastify, NestJS), alias de {@link queryPost}.
-	*
-	* Ne pas confondre avec {@link query}, qui FUSIONNE la query string et le
-	* corps. Pour une action typée, préférer le décorateur `@Body()`.
-	*
-	* Getter (aucune allocation) : `queryPost` reste la source unique.
+	* Fastify, NestJS). Jamais un paramètre d'URL : ceux-là sont dans
+	* {@link query}, et les deux ne fusionnent pas. Pour une action typée,
+	* préférer le décorateur `@Body()`.
 	*/
 	get body() {
-		return this.queryPost;
+		return this.#body ?? (this.context?.request)?.body;
 	}
 	set body(value) {
 		this.#assertPerRequest("body");
-		this.queryPost = value;
+		this.#body = value;
 	}
 	/**
 	* Session courante, ou `null`. Getter direct sur `context.session` (peuplé au
@@ -345,14 +338,13 @@ var Controller = class extends Service {
 		const fe = this.get("frontend");
 		if (!fe?.renderTags) return param;
 		const nonce = this.context?.cspNonce;
-		const host = this.context?.domain;
 		const renderTags = fe.renderTags;
 		const renderDocument = fe.renderDocument;
 		return {
-			frontendTags: (entry) => renderTags(entry, nonce, host),
+			frontendTags: (entry) => renderTags(entry, nonce),
 			frontendDocument: (entry) => {
 				if (!renderDocument) throw new Error("frontend service does not expose renderDocument");
-				return renderDocument(entry, nonce, host);
+				return renderDocument(entry, nonce);
 			},
 			asset: (p) => fe.assetUrl ? fe.assetUrl(p) : p,
 			...param
@@ -370,6 +362,43 @@ var Controller = class extends Service {
 		this.setContextJson();
 		return this.renderResponse(data, "utf8", status, headers);
 	}
+	/**
+	* Le client demande-t-il un flux d'événements (`Accept: text/event-stream`) ?
+	*
+	* La route ne change pas de méthode pour autant : un même `POST` répond en
+	* JSON ou en flux selon cette réponse. Toujours `false` sur WebSocket.
+	*
+	* @returns `true` quand `text/event-stream` est accepté avec un poids non nul.
+	*/
+	acceptsSse() {
+		if (!(this.context instanceof HttpContext)) return false;
+		return acceptsEventStream(this.context.request.headers.accept);
+	}
+	/**
+	* Répond par un flux d'événements serveur, en HTTP/1.1 comme en HTTP/2.
+	*
+	* L'action garde la main : elle `send()` à son rythme et `close()` quand elle
+	* a fini ; le départ du client ferme le flux (`sse.closed`, `sse.onClose`).
+	* Rendre le flux depuis l'action est sans effet — la réponse est déjà prise.
+	*
+	* @example
+	* ```ts
+	* @Get("/progress")
+	* async progress() {
+	*   const sse = await this.renderSse();
+	*   for (const step of steps) await sse.send(step, { event: "step" });
+	*   return sse.close();
+	* }
+	* ```
+	*
+	* @param options - battement de cœur, délai `retry:` initial.
+	* @returns le flux, ou sa promesse quand une session est à sauver d'abord.
+	* @throws HttpError 500 hors HTTP (WebSocket) ou quand la réponse est partie.
+	*/
+	renderSse(options) {
+		if (!(this.context instanceof HttpContext)) throw new HttpError("SSE : un flux d'événements exige une requête HTTP", 500, this.context);
+		return this.context.openSse(options);
+	}
 	setRoute(route) {
 		this.#assertPerRequest("route");
 		this.#route = route;
@@ -617,5 +646,4 @@ var Controller = class extends Service {
 		return this.streamFile(File, head, value);
 	}
 };
-//#endregion
 export { Controller as default, parseByteRange };

package/dist/nodefony/src/FrameworkAdminApi.js

@@ -1,7 +1,7 @@
 import router_default from "../service/router.js";
 import { createPlaygroundEndpoints } from "./PlaygroundAdminApi.js";
-import { parseFilters, parsePageQuery } from "nodefony";
-//#region nodefony/src/FrameworkAdminApi.ts
+import { PageQueryError, parseFilters, parsePageQuery } from "nodefony";
+// nodefony/src/FrameworkAdminApi.ts
 /**
 * Capacités de page d'un endpoint, ÉVALUÉES sous filet.
 *
@@ -29,6 +29,34 @@ function readPageCapabilities(caps) {
 	}
 }
 /**
+* Lit le paramètre `filters` de `routes/page` : un tableau JSON de
+* `{ key, op, value }`. Absent → aucun filtre.
+*
+* @throws PageQueryError (400) si le JSON est cassé ou d'une autre forme — un
+*   filtre ignoré rendrait TOUTES les routes, lues comme son résultat.
+*/
+function parseRouteFilters(raw) {
+	if (!raw) return [];
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw new PageQueryError(`Invalid "filters": not JSON.`);
+	}
+	if (!Array.isArray(parsed)) throw new PageQueryError(`Invalid "filters": expected a JSON array.`);
+	const entries = parsed;
+	const filters = [];
+	for (const item of entries) {
+		if (typeof item !== "object" || item === null || !("key" in item) || !("op" in item) || typeof item.key !== "string" || typeof item.op !== "string") throw new PageQueryError(`Invalid "filters": each entry needs a string "key" and "op".`);
+		filters.push({
+			key: item.key,
+			op: item.op,
+			value: "value" in item ? item.value : void 0
+		});
+	}
+	return filters;
+}
+/**
 * Producteur `IAdminApi` du module **framework** — exposé sous
 * `/nodefony/framework/api/*`.
 *
@@ -68,7 +96,8 @@ function createFrameworkAdminApi(broker, opts) {
 		scope: route.controller?.scope ?? null,
 		module: route.module?.name ?? null,
 		host: route.host ?? null,
-		bypassFirewall: route.bypassFirewall
+		bypassFirewall: route.bypassFirewall,
+		fallback: route.fallback
 	});
 	const descriptor = {
 		label: "Routes",
@@ -204,13 +233,7 @@ function createFrameworkAdminApi(broker, opts) {
 				});
 				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 = [];
-				}
+				const filters = parseRouteFilters(one(request.query.filters));
 				let rows = router_default.routes.map(serializeRoute);
 				if (search) rows = rows.filter((r) => matchesSearch(r, search));
 				for (const f of filters) rows = rows.filter((r) => matchOp(cell(r, f.key), f.op, f.value));
@@ -296,5 +319,4 @@ function createFrameworkAdminApi(broker, opts) {
 		adminEndpoints: () => endpoints
 	};
 }
-//#endregion
 export { createFrameworkAdminApi };