@nodefony/framework 10.0.0-alpha.9 → 10.0.0-beta.2

package/dist/nodefony/service/router.js

@@ -1,20 +1,23 @@
 import Route from "../src/Route.js";
 import { routeExpectsBodyStream } from "../decorators/routerDecorators.js";
 import Resolver from "../src/Resolver.js";
-import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.151.0/helpers/esm/decorateMetadata.js";
-import __decorate from "../../_virtual/_@oxc-project_runtime@0.151.0/helpers/esm/decorate.js";
-import { Module, Service, injectable } from "nodefony";
+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 { HttpError, isDomainAllowed } from "@nodefony/http";
 //#region nodefony/service/router.ts
 var _Router;
 let routeNoticePromoted = null;
+/**
+* Méthodes que sert une route — lues sur le `methodsSet` COMPILÉ par
+* `Route.compileRequirements`, jamais recalculées depuis la config brute.
+* Deux lectures de la même règle avaient divergé : la route acceptait HEAD
+* (implicite sur GET, RFC 9110 §9.1) quand le `Allow` du 405 l'omettait.
+*/
 function collectSupportedMethods(route) {
-	const set = /* @__PURE__ */ new Set();
-	const m = route.requirements?.methods;
-	if (typeof m === "string") m.split(",").map((s) => s.trim().toUpperCase()).filter(Boolean).forEach((x) => set.add(x));
-	else if (Array.isArray(m)) m.map((s) => String(s).toUpperCase()).forEach((x) => set.add(x));
-	return set;
+	return route.methodsSet ?? NO_METHODS;
 }
+const NO_METHODS = /* @__PURE__ */ new Set();
 const routes = [];
 const serviceName = "router";
 const REG_NON_LITERAL = /[{}*+?()[\]^$|\\]/;
@@ -49,8 +52,7 @@ function invalidateRouteIndex() {
 function buildRouteIndex() {
 	const statics = /* @__PURE__ */ new Map();
 	const dynamics = [];
-	for (let i = 0; i < routes.length; i++) {
-		const route = routes[i];
+	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();
@@ -90,23 +92,39 @@ let Router = class Router extends Service {
 	}
 	/**
 	* Retourne l'instance singleton d'une classe controller `@Scope("singleton")`,
-	* en la créant au premier appel via `create`. On cache la **promesse** (pas
-	* l'instance) : N requêtes concurrentes pendant la création (`initialize()`
-	* async) attendent le MÊME travail — jamais deux instances (race de création
-	* éliminée structurellement).
+	* en la créant au premier appel via `create`.
+	*
+	* Tant que la création est en cours (`initialize()` async), c'est la
+	* **promesse** qui est en cache : N requêtes concurrentes attendent le MÊME
+	* travail — jamais deux instances (race de création éliminée
+	* structurellement). Dès que l'instance est prête, elle REMPLACE la promesse :
+	* les requêtes suivantes la reçoivent directement, au lieu d'attendre à
+	* chaque fois une promesse déjà tenue (#505).
 	*
 	* @param ctor - la classe controller (clé du cache).
 	* @param create - fabrique exécutée une seule fois (instantiate + initialize).
-	* @returns la promesse de l'instance partagée.
+	* @returns l'instance partagée quand elle existe — ou que `create` la rend
+	*   sans rien attendre —, sinon la promesse de sa création.
+	* @throws ce que `create` lève de façon synchrone ; rien n'est alors mis en
+	*   cache, la requête suivante recrée.
 	*/
 	getSingletonController(ctor, create) {
-		if (this.singletonControllers == null) this.singletonControllers = /* @__PURE__ */ new Map();
-		let instance = this.singletonControllers.get(ctor);
-		if (!instance) {
-			instance = create();
-			this.singletonControllers.set(ctor, instance);
+		this.singletonControllers ??= /* @__PURE__ */ new Map();
+		const cached = this.singletonControllers.get(ctor);
+		if (cached !== void 0) return cached;
+		const created = create();
+		if (!isPromise(created)) {
+			this.singletonControllers.set(ctor, created);
+			return created;
 		}
-		return instance;
+		const pending = Promise.resolve(created);
+		this.singletonControllers.set(ctor, pending);
+		pending.then((instance) => {
+			if (this.singletonControllers?.get(ctor) === pending) this.singletonControllers.set(ctor, instance);
+		}, () => {
+			if (this.singletonControllers?.get(ctor) === pending) this.singletonControllers.delete(ctor);
+		});
+		return pending;
 	}
 	/**
 	* Résout une route pour un contexte donné.
@@ -138,22 +156,29 @@ let Router = class Router extends Service {
 		let di = 0;
 		while (li < litCount || di < dynCount) {
 			let route;
-			if (li < litCount && (di >= dynCount || literals[li].pos < dynamics[di].pos)) route = literals[li++].route;
+			let fromLiterals = false;
+			const literal = literals[li];
+			const candidate = dynamics[di];
+			if (literal !== void 0 && (candidate === void 0 || literal.pos < candidate.pos)) {
+				li++;
+				route = literal.route;
+				fromLiterals = true;
+			} else if (candidate === void 0) break;
 			else {
-				const candidate = dynamics[di++];
+				di++;
 				if (candidate.prefix !== "" && cleanPathLower !== void 0 && !cleanPathLower.startsWith(candidate.prefix)) continue;
 				route = candidate.route;
 			}
 			try {
-				if (resolver.match(route, context, cleanPath)) {
-					if (routeNoticePromoted === null) routeNoticePromoted = this.kernel?.environment !== "production";
+				if (resolver.match(route, context, cleanPath, fromLiterals)) {
+					routeNoticePromoted ??= this.kernel?.environment !== "production";
 					if (routeNoticePromoted) this.log(`Match route : ${route.name}`, "NOTICE");
 					resolver.exception = void 0;
 					routeExpectsBodyStream(route);
 					return resolver;
 				}
 			} catch (e) {
-				this.log(`Match route exception : ${route.name} ${e}`, "DEBUG");
+				this.log(`Match route exception : ${route.name} ${String(e)}`, "DEBUG");
 				resolver.exception = e;
 				continue;
 			}
@@ -165,6 +190,14 @@ let Router = class Router extends Service {
 				const servesDomain = !route.hostRegexp || isDomainAllowed(route.hostRegexp, context.domain);
 				if (route.pattern && route.pattern.test(path) && servesDomain) collectSupportedMethods(route).forEach((x) => allowed.add(x));
 			}
+			const servesWebsocket = allowed.delete("WEBSOCKET");
+			if (allowed.size === 0 && servesWebsocket) {
+				context.response?.setHeaders({
+					Upgrade: "websocket",
+					Connection: "Upgrade"
+				});
+				throw new HttpError("Upgrade Required: websocket", 426, context);
+			}
 			if (allowed.size > 0) {
 				const allowHeader = Array.from(allowed).join(", ");
 				const err = new HttpError(`Method ${context.method} Not Allowed`, 405, context);
@@ -219,7 +252,26 @@ let Router = class Router extends Service {
 		invalidateRouteIndex();
 		return routenew;
 	}
+	/**
+	* Enregistre une classe contrôleur pour un module — l'entonnoir UNIQUE : le
+	* décorateur `@controllers` y passe, comme les contrôleurs internes que le
+	* framework enregistre directement (plan d'administration, OAuth,
+	* WebAuthn…).
+	*
+	* C'est donc ICI que se refusent, au démarrage, les fautes de déclaration
+	* qu'un contrôleur ne révélerait qu'à sa première requête : une dépendance
+	* captive (un singleton qui détient un service de portée `request`), et une
+	* portée que sa classe de base n'admet pas (`Controller.assertScope`).
+	*
+	* @param myconstructor - la classe contrôleur.
+	* @param module - le module qui la porte.
+	* @returns la classe, rangée sous `module:Classe`.
+	* @throws BootConfigurationError sur une dépendance captive ou une portée
+	*   refusée — fatale dans tous les environnements.
+	*/
 	static setController(myconstructor, module) {
+		Injector.assertNoCaptiveDependency(myconstructor);
+		myconstructor.assertScope?.();
 		Object.defineProperty(myconstructor.prototype, "module", {
 			value: module,
 			writable: false

package/dist/nodefony/src/Controller.js

@@ -1,3 +1,4 @@
+import { isDevelopment, singletonWriteMessage } from "./singletonGuard.js";
 import { FileClass, RequestContext, Service } from "nodefony";
 import { HttpError } from "@nodefony/http";
 import fs, { createReadStream } from "node:fs";
@@ -48,12 +49,12 @@ function cspExigeUnNonce(csp) {
 function parseByteRange(range, length) {
 	const unit = /^\s*bytes\s*=\s*(.+)$/i.exec(range);
 	if (!unit) return null;
-	const spec = (unit[1] ?? "").trim();
+	const [, rawSpec = ""] = unit;
+	const spec = rawSpec.trim();
 	if (spec.includes(",")) return null;
 	const parts = /^(\d*)-(\d*)$/.exec(spec);
 	if (!parts) return null;
-	const first = parts[1] ?? "";
-	const last = parts[2] ?? "";
+	const [, first = "", last = ""] = parts;
 	if (first === "" && last === "") return null;
 	if (first === "") {
 		const suffix = parseInt(last, 10);
@@ -71,14 +72,37 @@ function parseByteRange(range, length) {
 		end: last === "" ? length - 1 : Math.min(parseInt(last, 10), length - 1)
 	};
 }
+/**
+* Garantit une `Error` comme motif de rejet : une valeur levée par un tiers
+* (`fs`, flux) peut être n'importe quoi.
+*
+* @param e - valeur interceptée.
+* @returns `e` si c'est déjà une `Error`, sinon une `Error` qui en porte le texte.
+*/
+function asError(e) {
+	return e instanceof Error ? e : new Error(String(e));
+}
 var Controller = class extends Service {
 	static prefix = "/";
 	/**
-	* Scope d'instanciation de la classe — `"request"` par défaut, `"singleton"`
-	* posé par le décorateur `@Scope` (statique hérité, lu via `new.target` au
-	* constructor et par le Resolver : 0 Reflect). Cf {@link ControllerScope}.
+	* Portée d'instanciation de la classe — `"singleton"` par défaut,
+	* `"request"` posé par le décorateur `@Scope` (statique hérité, lu via
+	* `new.target` au constructeur et par le Resolver : 0 Reflect).
+	* Cf {@link ControllerScope}.
 	*/
-	static scope = "request";
+	static scope = "singleton";
+	/**
+	* Vérifie que la portée de la classe est admise par sa lignée. Appelée à
+	* l'enregistrement du contrôleur (`Router.setController`), donc au
+	* démarrage.
+	*
+	* N'impose rien par défaut. Une classe de base qui n'admet qu'une portée la
+	* fait respecter ici — `RealtimeController`, lié à SA connexion par
+	* construction, refuse le singleton.
+	*
+	* @throws BootConfigurationError quand la portée déclarée est refusée.
+	*/
+	static assertScope() {}
 	#context = null;
 	#route = null;
 	#request = null;
@@ -91,66 +115,103 @@ var Controller = class extends Service {
 	module;
 	template;
 	/**
-	* Contexte transport courant. Per-request : champ posé par `setContext`
-	* (constructor) — coût d'accès inchangé. Singleton stateless (V4.3) : champ
-	* jamais posé → lecture de l'ALS `RequestContext` (le `HttpKernel` y place
-	* le contexte à l'entrée du scope, V4.1) — chaque appel de helper retrouve
-	* LA requête en cours, jamais celle d'une requête concurrente.
+	* Refuse d'écrire un état de requête sur un contrôleur singleton : la valeur
+	* serait lue par la requête suivante. Coût nul sur le chemin chaud — ces
+	* accesseurs n'y sont jamais écrits.
+	*
+	* @param member - le membre écrit, pour le message.
+	* @throws TypeError qui nomme le contrôleur, le membre et le remède.
+	*/
+	#assertPerRequest(member) {
+		const ctor = this.constructor;
+		if (ctor.scope === "singleton") throw new TypeError(singletonWriteMessage(ctor.name, member));
+	}
+	/**
+	* Contexte transport courant. Par requête : champ posé par `setContext`
+	* (constructeur). Singleton : champ jamais posé → lecture de l'ALS
+	* `RequestContext`, où le `HttpKernel` place le contexte à l'entrée de la
+	* requête — chaque helper retrouve LA requête en cours, jamais une requête
+	* concurrente.
 	*/
 	get context() {
 		return this.#context ?? RequestContext.getContext();
 	}
 	set context(context) {
+		this.#assertPerRequest("context");
 		this.#context = context ?? null;
 	}
 	/**
-	* Route matchée. Per-request : posée par le Resolver via `setRoute`.
-	* Sans champ (singleton) : dérive du Resolver de la requête courante
-	* (`context.resolver`), donc toujours la route de CETTE requête.
+	* Route de l'appel en cours. Par requête : posée par le Resolver
+	* (`setRoute`). Singleton : celle du résolveur de l'APPEL quand le pont
+	* `api.request` en a posé un dans l'ALS (clé `resolver` — un résolveur par
+	* appel, jamais rangé sur le contexte de la connexion), sinon celle du
+	* contexte.
 	*/
 	get route() {
-		return this.#route ?? this.context?.resolver?.route ?? null;
+		if (this.#route !== null) return this.#route;
+		if (this.#context !== null) return this.#context.resolver?.route ?? null;
+		const store = RequestContext.get();
+		return (store?.resolver)?.route ?? (store?.context)?.resolver?.route ?? null;
 	}
 	get request() {
 		return this.#request ?? this.context?.request ?? null;
 	}
 	set request(request) {
+		this.#assertPerRequest("request");
 		this.#request = request;
 	}
 	get response() {
 		return this.#response ?? this.context?.response ?? null;
 	}
 	set response(response) {
+		this.#assertPerRequest("response");
 		this.#response = response;
 	}
 	get method() {
 		return this.#method ?? this.context?.method ?? void 0;
 	}
 	set method(method) {
+		this.#assertPerRequest("method");
 		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.
+	*/
 	get queryGet() {
-		return this.#queryGet ?? (this.context?.request)?.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() {
-		return this.#query ?? (this.context?.request)?.query;
+		if (this.#query !== null) return this.#query;
+		if (this.#context !== null) return this.#context.request?.query;
+		const store = RequestContext.get();
+		return (store?.resolver)?.queryOverride ?? ((store?.context)?.request)?.query;
 	}
 	set query(value) {
+		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;
 	}
 	set queryPost(value) {
+		this.#assertPerRequest("queryPost");
 		this.#queryPost = value;
 	}
 	/**
@@ -166,6 +227,7 @@ var Controller = class extends Service {
 		return this.queryPost;
 	}
 	set body(value) {
+		this.#assertPerRequest("body");
 		this.queryPost = value;
 	}
 	/**
@@ -184,7 +246,16 @@ var Controller = class extends Service {
 		this.template = this.get("template");
 		if (!singleton) this.setContext(context);
 	}
+	/**
+	* Lie l'instance au contexte de SA requête — contrôleur par requête
+	* seulement : tout l'état de la requête (`request`, `response`, `method`,
+	* `query*`) en dérive ensuite, toujours frais.
+	*
+	* @param context - le contexte de la requête servie par cette instance.
+	* @throws TypeError sur un singleton, qui sert toutes les requêtes.
+	*/
 	setContext(context) {
+		this.#assertPerRequest("context");
 		this.#context = context;
 	}
 	setContextJson(encoding = "utf-8") {
@@ -211,18 +282,36 @@ var Controller = class extends Service {
 	* @returns rien — cette sonde n'échoue jamais et ne change aucune réponse.
 	*/
 	#warnScriptWithoutNonce(data) {
-		const kernel = this.context?.kernel;
-		if (kernel?.environment !== "development" && kernel?.environment !== "dev") return;
+		if (!isDevelopment(this.context?.kernel?.environment)) return;
 		if (typeof data !== "string" || data.length === 0) return;
 		const response = this.response;
 		if (typeof response?.getHeader !== "function") return;
 		if (!cspExigeUnNonce(response.getHeader("Content-Security-Policy")) || !INLINE_SCRIPT_SANS_NONCE.test(data)) return;
 		this.log("Cette réponse porte un <script> EN LIGNE sans attribut `nonce`, et la politique de contenu de cette application exige un nonce sur les scripts : le navigateur REFUSERA de l'exécuter (« Refused to execute inline script »). Deux gestes, au choix :\n  • signer le script — `<script nonce=\"${this.context?.cspNonce}\">` (dans une vue Eta : `<script nonce=\"<%= it.nonce %>\">`, le nonce étant passé en donnée depuis `this.context?.cspNonce`) ;\n  • sortir le script dans un FICHIER servi par l'application — un `<script src=…>` de même origine satisfait `script-src 'self'` sans nonce.\n  Ne desserre PAS la politique (`'unsafe-inline'`) : le détail vit dans `@nodefony/security/docs/headers.md`.", "WARNING", "CSP");
 	}
-	async render(data, encoding, status, headers) {
+	/**
+	* Rend une donnée sur la réponse de la requête courante (JSON, HTML ou
+	* texte selon son type).
+	*
+	* Synchrone quand l'envoi l'est — réponse unique, sans session à sauver ni
+	* hook d'envoi (#505). Un `await` reste valable dans tous les cas ; un
+	* `.then` chaîné ne l'est plus : la valeur n'est une promesse que quand
+	* l'envoi attend.
+	*
+	* @returns la réponse, ou sa promesse.
+	*/
+	render(data, encoding, status, headers) {
 		this.#warnScriptWithoutNonce(data);
 		return this.context?.render(data, encoding, status, headers);
 	}
+	/**
+	* Envoie une donnée déjà sérialisée sur le transport de la requête (HTTP ou
+	* WebSocket), après statut et en-têtes éventuels.
+	*
+	* Synchrone quand l'envoi l'est (#505) — cf {@link render}.
+	*
+	* @returns la réponse, ou sa promesse.
+	*/
 	renderResponse(data, encoding, status, headers) {
 		if (headers) this.response?.setHeaders(headers);
 		if (status) this.response?.setStatusCode(status);
@@ -240,7 +329,7 @@ var Controller = class extends Service {
 			}
 			this.setContextHtml();
 			this.#warnScriptWithoutNonce(data);
-			return this.renderResponse(data, "utf8", status, headers);
+			return await this.renderResponse(data, "utf8", status, headers);
 		} catch (e) {
 			this.log(e, "ERROR");
 			throw e;
@@ -257,24 +346,38 @@ var Controller = class extends Service {
 		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) => fe.renderTags(entry, nonce, host),
-			frontendDocument: (entry) => fe.renderDocument(entry, nonce, host),
+			frontendTags: (entry) => renderTags(entry, nonce, host),
+			frontendDocument: (entry) => {
+				if (!renderDocument) throw new Error("frontend service does not expose renderDocument");
+				return renderDocument(entry, nonce, host);
+			},
 			asset: (p) => fe.assetUrl ? fe.assetUrl(p) : p,
 			...param
 		};
 	}
-	async renderJson(obj, status, headers) {
+	/**
+	* Sérialise en JSON puis envoie ({@link renderResponse}). Synchrone quand
+	* l'envoi l'est (#505).
+	*
+	* @returns la réponse, ou sa promesse.
+	* @throws de façon SYNCHRONE ce que lève `JSON.stringify` (cycle, BigInt).
+	*/
+	renderJson(obj, status, headers) {
 		const data = JSON.stringify(obj);
 		this.setContextJson();
 		return this.renderResponse(data, "utf8", status, headers);
 	}
 	setRoute(route) {
+		this.#assertPerRequest("route");
 		this.#route = route;
 		return route;
 	}
 	getSession() {
-		if (this.context?.session) return this.context?.session;
+		const session = this.context?.session;
+		if (session) return session;
 	}
 	redirect(url, status, headers) {
 		if (!url) throw new Error("Redirect error no url !!!");
@@ -306,7 +409,7 @@ var Controller = class extends Service {
 		if (file instanceof FileClass) File = file;
 		else if (typeof file === "string") File = new FileClass(file);
 		else throw new Error(`File argument bad type for getFile :${typeof file}`);
-		if (File.type !== "File") throw new Error(`getFile bad type for  :${file}`);
+		if (File.type !== "File") throw new Error(`getFile bad type for  :${String(file)}`);
 		return File;
 	}
 	/**
@@ -347,7 +450,7 @@ var Controller = class extends Service {
 		}
 		else throw new Error(`File argument bad type for getFileAsync :${typeof file}`);
 		if (File.type !== "File") {
-			this.log(`ce chemin n'est pas un fichier : ${file}`, "DEBUG");
+			this.log(`ce chemin n'est pas un fichier : ${String(file)}`, "DEBUG");
 			throw new HttpError("Not Found", 404, this.context);
 		}
 		return File;
@@ -375,12 +478,7 @@ var Controller = class extends Service {
 			"Content-Type": File.mimeType || "application/octet-stream",
 			...headers
 		};
-		try {
-			return this.streamFile(File, head, options);
-		} catch (e) {
-			this.log(e, "ERROR");
-			throw e;
-		}
+		return this.streamFile(File, head, options);
 	}
 	/**
 	* Envoie un fichier en FLUX, du disque vers la réponse, sans jamais le charger
@@ -404,73 +502,81 @@ var Controller = class extends Service {
 	* @throws Si la réponse n'est pas disponible, ou si le fichier est illisible.
 	*/
 	async streamFile(file, headers, options = {}) {
+		const context = this.context;
 		if (!this.response) throw new Error(`response not found`);
 		const contextResponse = this.response;
 		const response = contextResponse.response;
 		if (!response) throw new Error(`response not found`);
 		options.autoClose = false;
+		let streamFile;
 		try {
 			const fileDetails = await this.getFileAsync(file);
 			this.response.response?.removeHeader("Content-Type");
 			this.response.response?.removeHeader("content-type");
 			if (!(headers && (headers["Content-Type"] || headers["content-type"]))) this.response.setFileMimeType(fileDetails.name);
 			if (!(headers && (headers["Content-Length"] || headers["content-length"]))) {
-				if (!headers) headers = {};
+				headers ??= {};
 				this.response.response?.removeHeader("Content-Length");
 				this.response.response?.removeHeader("content-length");
 				headers["Content-Length"] = fileDetails.stats.size;
 			}
-			const streamFile = createReadStream(fileDetails.path, options);
-			return new Promise((resolve, reject) => {
-				let handled = false;
-				const onResponseClose = () => {
-					if (!handled) streamFile.destroy();
-				};
-				response.once("close", onResponseClose);
-				streamFile.on("open", () => {
-					try {
-						this.context?.writeHead(contextResponse?.statusCode, headers);
-						streamFile.pipe(response, { end: false });
-					} catch (e) {
-						this.log(e, "ERROR");
-						return reject(e);
-					}
-				});
-				const handleStreamEnd = async () => {
-					try {
-						if (handled) return;
-						handled = true;
-						response.removeListener("close", onResponseClose);
-						if (streamFile) {
-							streamFile.unpipe(response);
-							if (streamFile.fd) await fsClose(streamFile.fd).catch((e) => {
-								return reject(e);
-							});
-							if (!this.context?.finished) this.context?.end();
-							return resolve(streamFile);
-						}
-					} catch (e) {
-						this.log(e, "ERROR");
-						return reject(e);
-					}
-				};
-				streamFile.on("end", handleStreamEnd);
-				streamFile.on("close", handleStreamEnd);
-				streamFile.on("error", (error) => {
-					this.log(error, "ERROR");
-					if (!this.context?.finished) this.context?.end();
-					return reject(error);
-				});
-			});
+			streamFile = createReadStream(fileDetails.path, options);
 		} catch (e) {
 			this.log(e, "ERROR");
 			throw e;
 		}
+		return new Promise((resolve, reject) => {
+			let handled = false;
+			const onResponseClose = () => {
+				if (!handled) streamFile.destroy();
+			};
+			response.once("close", onResponseClose);
+			streamFile.on("open", () => {
+				try {
+					context?.writeHead(contextResponse.statusCode, headers);
+					streamFile.pipe(response, { end: false });
+				} catch (e) {
+					this.log(e, "ERROR");
+					reject(asError(e));
+				}
+			});
+			const endContext = () => {
+				if (context && !context.finished) Promise.resolve(context.end()).catch((e) => {
+					this.log(e, "ERROR");
+				});
+			};
+			const handleStreamEnd = async () => {
+				try {
+					if (handled) return;
+					handled = true;
+					response.removeListener("close", onResponseClose);
+					streamFile.unpipe(response);
+					if (streamFile.fd) await fsClose(streamFile.fd).catch((e) => {
+						reject(asError(e));
+					});
+					endContext();
+					resolve(streamFile);
+				} catch (e) {
+					this.log(e, "ERROR");
+					reject(asError(e));
+				}
+			};
+			const onStreamEnd = () => {
+				handleStreamEnd();
+			};
+			streamFile.on("end", onStreamEnd);
+			streamFile.on("close", onStreamEnd);
+			streamFile.on("error", (error) => {
+				this.log(error, "ERROR");
+				endContext();
+				reject(error);
+			});
+		});
 	}
 	async renderMediaStream(file, headers = {}, options = {}) {
 		const File = await this.getFileAsync(file);
 		this.response?.setEncoding("binary");
-		const range = this.request?.headers?.range;
+		const range = this.request?.headers.range;
 		const length = File.stats.size;
 		let head;
 		let value;

package/dist/nodefony/src/FrameworkAdminApi.js

@@ -54,8 +54,8 @@ function readPageCapabilities(caps) {
 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());
+		const m = route.requirements.methods ?? route.method;
+		if (Array.isArray(m)) return m.map((x) => x.toUpperCase());
 		if (typeof m === "string") return m.split(",").map((s) => s.trim().toUpperCase()).filter(Boolean);
 		return ["ANY"];
 	};
@@ -65,6 +65,7 @@ function createFrameworkAdminApi(broker, opts) {
 		methods: methodsOf(route),
 		controller: route.controller?.name ?? null,
 		action: route.classMethod ?? null,
+		scope: route.controller?.scope ?? null,
 		module: route.module?.name ?? null,
 		host: route.host ?? null,
 		bypassFirewall: route.bypassFirewall
@@ -129,7 +130,7 @@ function createFrameworkAdminApi(broker, opts) {
 		switch (key) {
 			case "methods": return r.methods.join(",");
 			case "path": return r.path ?? "";
-			case "name": return r.name ?? "";
+			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";
@@ -146,9 +147,21 @@ function createFrameworkAdminApi(broker, opts) {
 	* adossé à une ressource persistée déclare un `IFilterSpec` et laisse le cœur
 	* valider — il ne recopie pas ce `matchOp`.
 	*/
+	const filterValueText = (value) => {
+		switch (typeof value) {
+			case "string": return value;
+			case "number":
+			case "boolean":
+			case "bigint": return String(value);
+			case "object": return Array.isArray(value) ? value.map(filterValueText).join(",") : "";
+			case "undefined":
+			case "symbol":
+			case "function": return "";
+		}
+	};
 	const matchOp = (raw, op, value) => {
-		const s = String(raw ?? "");
-		const v = String(value ?? "");
+		const s = raw;
+		const v = filterValueText(value);
 		if (op !== "isEmpty" && op !== "notEmpty" && v === "") return true;
 		switch (op) {
 			case "contains": return s.toLowerCase().includes(v.toLowerCase());
@@ -270,7 +283,7 @@ function createFrameworkAdminApi(broker, opts) {
 						icon: d?.icon ?? null,
 						order: d?.order ?? 99,
 						role: d?.role ?? null,
-						endpoints: byNs.get(ns)
+						endpoints: byNs.get(ns) ?? []
 					};
 				}).sort((a, b) => a.order - b.order) };
 			}