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

package/dist/nodefony/src/Controller.js

@@ -1,18 +1,20 @@
 import { isDevelopment, singletonWriteMessage } from "./singletonGuard.js";
+import { fileServingSchema } from "../config/config.js";
+import { evaluatePreconditions, fileValidators, ifRangeHolds, parseHttpDate } from "./conditionalRequest.js";
+import { VIEW_NONCE_LOCAL, signTemplateTags } from "./viewNonce.js";
 import { FileClass, RequestContext, Service } from "nodefony";
 import { HttpContext, HttpError, acceptsEventStream } from "@nodefony/http";
-import fs, { createReadStream } from "node:fs";
-import { promisify } from "node:util";
+import { createReadStream } from "node:fs";
+import { Readable } from "node:stream";
 // nodefony/src/Controller.ts
-const fsClose = promisify(fs.close);
 /**
-* Un `<script>` EN LIGNE qui ne porte pas d'attribut `nonce`.
+* Un `<script>` ou un `<style>` qui ne porte pas d'attribut `nonce`.
 *
-* `(?![^>]*\bnonce=)` refuse la balise déjà signée ; `(?![^>]*\bsrc=)` refuse
-* le script SERVI depuis un fichier, qui n'a pas besoin de nonce et satisfait
-* `script-src 'self'`. Reste exactement le cas que le navigateur bloquera.
+* Sous `'strict-dynamic'` (ADR-0024 §C1), un script SERVI depuis un fichier
+* de même origine est refusé lui aussi sans nonce : `'self'` n'y compte plus.
+* Un `<style>` sans nonce l'est sous la politique de styles (§C2).
 */
-const INLINE_SCRIPT_SANS_NONCE = /<script(?![^>]*\bnonce=)(?![^>]*\bsrc=)[^>]*>\s*\S/iu;
+const UNSIGNED_SCRIPT_OR_STYLE = /<(?:script|style)\b(?![^>]*\bnonce\s*=)/iu;
 /**
 * Le CSP posé sur cette réponse exige-t-il un nonce sur les scripts ?
 *
@@ -32,7 +34,7 @@ const INLINE_SCRIPT_SANS_NONCE = /<script(?![^>]*\bnonce=)(?![^>]*\bsrc=)[^>]*>\
 * @param csp - valeur de l'en-tête `Content-Security-Policy`, si posée.
 * @returns `true` quand un script en ligne devra porter un nonce.
 */
-function cspExigeUnNonce(csp) {
+function cspRequiresNonce(csp) {
 	return typeof csp === "string" && csp.includes("'nonce-");
 }
 /**
@@ -72,15 +74,71 @@ function parseByteRange(range, length) {
 		end: last === "" ? length - 1 : Math.min(parseInt(last, 10), length - 1)
 	};
 }
+/** Une HTTP-date déjà passée (RFC 9110 §5.6.7) : le début de l'ère Unix. */
+const EXPIRED_HTTP_DATE = "Thu, 01 Jan 1970 00:00:00 GMT";
 /**
-* Garantit une `Error` comme motif de rejet : une valeur levée par un tiers
-* (`fs`, flux) peut être n'importe quoi.
+* Défaut des fichiers servis par une action, pour TOUTE l'application — la
+* section `fileServing` de la config du module, posée au boot par
+* {@link configureFileServing}. Initialisé depuis le schéma (seule source des
+* défauts) : un contrôleur testé sans noyau reçoit les mêmes valeurs.
+*/
+let fileServing = fileServingSchema.parse({});
+/**
+* Fixe le défaut des fichiers servis (validateurs, `Cache-Control`) pour
+* toute l'application. Appelé par le module au boot avec sa config validée.
 *
-* @param e - valeur interceptée.
-* @returns `e` si c'est déjà une `Error`, sinon une `Error` qui en porte le texte.
+* @param config - section `fileServing` validée
+*/
+function configureFileServing(config) {
+	fileServing = config;
+}
+/** Aucun validateur : `If-Range` ne tient jamais, aucune précondition n'est évaluée. */
+const NO_VALIDATORS = Object.freeze({
+	etag: null,
+	lastModified: null,
+	lastModifiedStrong: false
+});
+/**
+* En-têtes qu'un 304 doit porter, ceux qu'aurait portés le 200 (RFC 9110
+* §15.4.5) — en minuscules.
 */
-function asError(e) {
-	return e instanceof Error ? e : new Error(String(e));
+const NOT_MODIFIED_FIELDS = /* @__PURE__ */ new Set([
+	"cache-control",
+	"content-location",
+	"etag",
+	"expires",
+	"last-modified",
+	"vary"
+]);
+/** Valeur d'un en-tête d'un objet d'en-têtes, quelle que soit la casse de sa clé. */
+function headerIn(headers, name) {
+	if (headers === void 0) return void 0;
+	for (const key of Object.keys(headers)) if (key.toLowerCase() === name) return headers[key];
+}
+/**
+* Encode une valeur en `ext-value` UTF-8 (RFC 8187 §3.2) : tout ce qui n'est
+* pas un `attr-char` part en pourcentage — `encodeURIComponent` laisse passer
+* `'`, `(`, `)` et `*`, qui n'en sont pas.
+*/
+function encodeExtValue(value) {
+	return encodeURIComponent(value).replace(/['()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+/**
+* Valeur d'un en-tête `Content-Disposition` (RFC 6266) pour un nom de fichier
+* QUELCONQUE. `filename` seul quand le nom s'y écrit fidèlement ; sinon un
+* repli ASCII, suivi de `filename*` en UTF-8 (RFC 6266 §4.3 : le destinataire
+* prend `filename*`). Le repli remplace par `_` ce que l'annexe D écarte :
+* hors ASCII imprimable, `"`, `\` et `%` — un nom accentué ne lève donc
+* jamais `ERR_INVALID_CHAR`, et un guillemet ne casse pas la valeur.
+*
+* @param type - `attachment` (téléchargement) ou `inline` (affiché).
+* @param name - le nom du fichier, tel quel.
+* @returns la valeur de l'en-tête.
+*/
+function contentDisposition(type, name) {
+	const fallback = name.replace(/[^\x20-\x7e]|["\\%]/g, "_");
+	if (fallback === name) return `${type}; filename="${name}"`;
+	return `${type}; filename="${fallback}"; filename*=UTF-8''${encodeExtValue(name)}`;
 }
 var Controller = class extends Service {
 	static prefix = "/";
@@ -140,6 +198,16 @@ var Controller = class extends Service {
 		this.#context = context ?? null;
 	}
 	/**
+	* Journalise au nom du module du contrôleur, pas du noyau : `moduleName`
+	* explicite, sinon le module posé sur la requête (`context.logModule`),
+	* sinon le module propriétaire du contrôleur.
+	*
+	* @param moduleName - module qui signe CETTE ligne
+	*/
+	log(pci, severity, msgid, msg, moduleName) {
+		return super.log(pci, severity, msgid, msg, moduleName ?? this.context?.logModule ?? this.module?.name);
+	}
+	/**
 	* 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
@@ -258,14 +326,17 @@ var Controller = class extends Service {
 		return this.context?.setContextHtml(encoding);
 	}
 	/**
-	* Dit, EN DÉVELOPPEMENT SEULEMENT, qu'un script en ligne ne s'exécutera pas.
+	* Dit, EN DÉVELOPPEMENT SEULEMENT, qu'un script ou un style ne s'appliquera pas.
 	*
-	* Le navigateur refuse un `<script>` en ligne sous une politique de contenu à
-	* nonce, et il le dit dans SA console — que personne ne lit quand la page est
+	* Une vue rendue par {@link Controller.renderView} est signée par le
+	* framework (`viewNonce.ts#signTemplateTags`) : ce qui reste ici, c'est du
+	* HTML produit autrement — une chaîne bâtie dans l'action, une valeur insérée
+	* brute. Le navigateur refuse alors la balise, et il le dit dans SA console — que personne ne lit quand la page est
 	* produite par un test, un `curl` ou un agent. Le serveur, lui, a les deux
-	* moitiés sous la main : l'en-tête qu'il vient de poser et le corps qu'il
-	* s'apprête à écrire. Il le dit donc au moment exact où le geste manque, avec
-	* le geste — c'est ce qui distingue un refus utilisable d'un refus juste.
+	* moitiés sous la main : l'en-tête qu'il vient d'émettre et le corps qu'il
+	* vient d'écrire — lus APRÈS l'envoi, la politique n'étant posée qu'au
+	* `writeHead`. Il le dit donc à la requête même où le geste manque, avec le
+	* geste — c'est ce qui distingue un refus utilisable d'un refus juste.
 	*
 	* ⚠️ Coût nul hors développement : la garde d'environnement est le PREMIER
 	* test, avant toute lecture d'en-tête et toute expression régulière. Une page
@@ -274,13 +345,13 @@ var Controller = class extends Service {
 	* @param data - le corps HTML sur le point d'être envoyé.
 	* @returns rien — cette sonde n'échoue jamais et ne change aucune réponse.
 	*/
-	#warnScriptWithoutNonce(data) {
+	#warnUnsignedTags(data) {
 		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");
+		if (!cspRequiresNonce(response.getHeader("Content-Security-Policy")) || !UNSIGNED_SCRIPT_OR_STYLE.test(data)) return;
+		this.log("Cette réponse porte un <script> ou un <style> sans attribut `nonce`, et la politique de contenu de cette application exige un nonce : le navigateur REFUSERA la balise (« violates the following Content Security Policy directive »). Deux gestes, au choix :\n  • rendre la page par une VUE (`this.renderView(…)`) : le framework signe chaque <script> et <style> écrit dans le gabarit ;\n  • signer la balise à la main — `<script nonce=\"${this.context?.cspNonce}\">`.\n  Ne desserre PAS la politique (`'unsafe-inline'`) : le détail vit dans `@nodefony/security/docs/headers.md`.", "WARNING", "CSP");
 	}
 	/**
 	* Rend une donnée sur la réponse de la requête courante (JSON, HTML ou
@@ -294,8 +365,13 @@ var Controller = class extends Service {
 	* @returns la réponse, ou sa promesse.
 	*/
 	render(data, encoding, status, headers) {
-		this.#warnScriptWithoutNonce(data);
-		return this.context?.render(data, encoding, status, headers);
+		const sent = this.context?.render(data, encoding, status, headers);
+		if (sent instanceof Promise && isDevelopment(this.context?.kernel?.environment)) return sent.then((response) => {
+			this.#warnUnsignedTags(data);
+			return response;
+		});
+		this.#warnUnsignedTags(data);
+		return sent;
 	}
 	/**
 	* Envoie une donnée déjà sérialisée sur le transport de la requête (HTTP ou
@@ -316,19 +392,34 @@ var Controller = class extends Service {
 			const file = typeof path === "string" ? await FileClass.from(path) : path;
 			this.context?.phaseStart("render");
 			try {
-				data = await this.template?.render((await file.readAsync()).toString(), this.withFrontendLocals(param));
+				data = await this.template?.render(signTemplateTags((await file.readAsync()).toString()), this.withNonceLocal(this.withFrontendLocals(param)));
 			} finally {
 				this.context?.phaseEnd("render");
 			}
 			this.setContextHtml();
-			this.#warnScriptWithoutNonce(data);
-			return await this.renderResponse(data, "utf8", status, headers);
+			const response = await this.renderResponse(data, "utf8", status, headers);
+			this.#warnUnsignedTags(data);
+			return response;
 		} catch (e) {
 			this.log(e, "ERROR");
 			throw e;
 		}
 	}
 	/**
+	* Expose le nonce CSP de la requête à la vue (`cspNonce`), lu seulement si
+	* le gabarit s'en sert : un accesseur, pas une valeur — une vue sans
+	* `<script>` ni `<style>` ne tire aucun nonce. Une valeur `cspNonce`
+	* fournie par l'action est gardée.
+	*/
+	withNonceLocal(param) {
+		if ("cspNonce" in param) return param;
+		const context = this.context;
+		return Object.defineProperty({ ...param }, VIEW_NONCE_LOCAL, {
+			get: () => context?.cspNonce ?? "",
+			enumerable: false
+		});
+	}
+	/**
 	* Injecte les helpers frontend (`frontendTags`/`frontendDocument`) dans les
 	* locals du template (passés en data, pas de registre global de fonctions).
 	* Service `frontend` résolu par nom (pas d'import `@nodefony/frontend`). Les
@@ -391,6 +482,12 @@ var Controller = class extends Service {
 	* }
 	* ```
 	*
+	* Typé par le contrat temps réel de l'application, le flux lit la MÊME carte
+	* que la socket : `this.renderSse<ContractServerEmit<ChatContract>>()`, puis
+	* `sse.send(m, { event: "chat:room" })`. Sans paramètre de type, il reste
+	* libre — un flux hors contrat est valide.
+	*
+	* @typeParam Events - carte des événements du flux (défaut : libre).
 	* @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.
@@ -399,6 +496,57 @@ var Controller = class extends Service {
 		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);
 	}
+	/**
+	* Répond par un FLUX D'OCTETS : un `<video src>`, un `fetch()`, un
+	* téléchargement ou un outil tiers (curl) le consomment comme n'importe quelle
+	* réponse HTTP, une réponse par consommateur. Pour des ÉVÉNEMENTS texte lus
+	* par `EventSource`, voir {@link Controller.renderSse}. Pour UNE source
+	* d'octets diffusée à N lecteurs par la socket, publier un `Uint8Array` sur
+	* un canal temps réel (`@nodefony/realtime`), pas une réponse HTTP.
+	*
+	* La réponse est prise à l'appel ; les en-têtes partent au premier morceau.
+	* Une erreur de la source AVANT lui rend la page d'erreur ordinaire (500, ou
+	* le code d'une `HttpError`) ; APRÈS, le client voit une coupure. La source
+	* appartient au flux dès l'appel : détruite à la fin, quelle qu'en soit la
+	* raison, et détruite aussi quand l'appel lève (un flux web est annulé). La
+	* promesse ne rejette jamais : elle rend la raison de la fin et les octets
+	* envoyés.
+	*
+	* @example
+	* ```ts
+	* const ff = spawn("ffmpeg", args, { stdio: ["ignore", "pipe", "ignore"], windowsHide: true });
+	* try {
+	*   await this.renderStream(ff.stdout, { headers: { "content-type": "video/mp4" } });
+	* } finally {
+	*   ff.kill("SIGKILL"); // le flux est fini, quelle qu'en soit la raison
+	* }
+	* ```
+	*
+	* Relais d'un autre service — le signal coupe l'amont au départ du client ;
+	* ne recopier que `content-type` (`fetch` a déjà décompressé le corps) :
+	* ```ts
+	* const r = await fetch(url, { signal: this.context.signal });
+	* if (!r.ok || r.body === null) throw new HttpError(502);
+	* return this.renderStream(r.body, {
+	*   headers: { "content-type": r.headers.get("content-type") ?? "application/octet-stream" },
+	* });
+	* ```
+	*
+	* @param source - flux Node, ou flux web ; jamais en mode objet.
+	* @param options - statut, en-têtes, `idleTimeout`, `stallTimeout`,
+	*   `maxDuration`, `onClose(reason)`.
+	* @returns la raison de la fin et le nombre d'octets envoyés.
+	* @throws HttpError 500 hors HTTP (WebSocket) ou quand la réponse est partie ;
+	*   429 au-delà du plafond de connexions par IP. La source est alors détruite.
+	*/
+	renderStream(source, options) {
+		if (!(this.context instanceof HttpContext)) {
+			if (source instanceof Readable) source.destroy();
+			else source.cancel().catch(() => void 0);
+			throw new HttpError("Flux : une réponse en flux exige une requête HTTP", 500, this.context);
+		}
+		return this.context.openStream(source, options);
+	}
 	setRoute(route) {
 		this.#assertPerRequest("route");
 		this.#route = route;
@@ -494,15 +642,16 @@ var Controller = class extends Service {
 	* @param file - chemin ou `FileClass` du fichier à servir.
 	* @param options - options de `createReadStream`.
 	* @param headers - en-têtes ajoutés (écrasent ceux posés par défaut).
-	* @returns le flux de lecture, une fois la réponse écoulée.
+	* @returns le flux de lecture, une fois la réponse écoulée — `null` quand
+	*   les préconditions ont répondu 304 ou 412 (cf {@link Controller.streamFile}).
 	*/
 	async renderFileDownload(file, options, headers = {}) {
 		const File = await this.getFileAsync(file);
 		const length = File.stats.size;
 		const head = {
-			"Content-Disposition": `attachment; filename="${File.name}"`,
+			"Content-Disposition": contentDisposition("attachment", File.name),
 			"Content-Length": length,
-			Expires: "0",
+			Expires: EXPIRED_HTTP_DATE,
 			"Content-Description": "File Transfer",
 			"Content-Type": File.mimeType || "application/octet-stream",
 			...headers
@@ -520,98 +669,156 @@ var Controller = class extends Service {
 	* `Content-Range`). Annoncer `Accept-Ranges: bytes` depuis ici est un piège :
 	* le client croit pouvoir se déplacer et reçoit tout le fichier.
 	*
-	* Ce que cette méthode garantit et qui justifie son existence : le NETTOYAGE.
-	* Le flux est ouvert en `autoClose: false` ; un client qui raccroche en plein
-	* téléchargement laisserait sinon un descripteur ouvert et une promesse pendue.
+	* Le cycle de vie est celui de toute réponse en flux
+	* ({@link Controller.renderStream}) : la réponse est prise à l'appel, les
+	* en-têtes partent au premier morceau, le flux est DÉTRUIT (descripteur
+	* fermé) quand le client raccroche. Un fichier illisible à l'ouverture
+	* (`EACCES`) rend la page d'erreur ordinaire, 500 ; une lecture qui échoue
+	* en cours de route coupe la connexion. Sans délai d'inactivité (un disque
+	* n'est pas une source muette).
+	*
+	* **Requêtes conditionnelles** (RFC 9110 §13) : le fichier ENTIER porte une
+	* `ETag` forte et un `Last-Modified`, tirés de sa taille et de sa date de
+	* modification ; `If-Match`, `If-Unmodified-Since`, `If-None-Match` et
+	* `If-Modified-Since` y sont évalués dans l'ordre de §13.2.2 → 304 ou 412,
+	* sans ouvrir le fichier. Une `ETag` ou un `Last-Modified` passés dans
+	* `headers` (ou déjà posés sur la réponse) l'emportent, et servent à la
+	* comparaison. `Cache-Control: private, no-cache` est posé si l'action n'en
+	* fixe aucun — en passer un dans `headers` le remplace. Un EXTRAIT
+	* (`start`/`end`) n'est pas la représentation entière : il ne reçoit ni
+	* validateur ni évaluation.
+	* `{ validators: false }` dans `options` coupe le tout — validateurs,
+	* évaluation et `Cache-Control` par défaut — pour des fichiers dont la date
+	* n'est pas fiable ; une `ETag` tirée du contenu garde, elle, le 304.
 	*
 	* @param file - chemin ou `FileClass` du fichier à servir.
 	* @param headers - en-têtes ajoutés à la réponse (le type MIME est déduit si absent).
 	* @param options - options de `createReadStream` (`start`/`end` pour un extrait).
-	* @returns le flux de lecture, une fois la réponse écoulée.
-	* @throws Si la réponse n'est pas disponible, ou si le fichier est illisible.
+	* @returns le flux de lecture, une fois la réponse écoulée — détruit, quelle
+	*   que soit la fin ; `null` quand les préconditions ont répondu 304 ou 412 :
+	*   aucun fichier n'a alors été ouvert.
+	* @throws HttpError 404 si le fichier n'existe pas ; 500 hors HTTP
+	*   (WebSocket) ou quand la réponse est déjà partie.
 	*/
-	async streamFile(file, headers, options = {}) {
+	async streamFile(file, headers, options) {
+		const fileDetails = await this.getFileAsync(file);
+		if (options?.start !== void 0 || options?.end !== void 0 || !(options?.validators ?? fileServing.validators)) return this.#sendFile(fileDetails, headers, options);
+		const condition = this.#fileCondition(fileDetails, headers, true);
+		if (condition.outcome !== 200) return this.#answerPrecondition(condition);
+		return this.#sendFile(fileDetails, condition.head, options);
+	}
+	/**
+	* Validateurs d'un fichier servi, et verdict des préconditions de la
+	* requête (RFC 9110 §13.2.2). Hors HTTP, rien n'est évalué : l'envoi
+	* refusera de lui-même.
+	*
+	* @param file - fichier servi
+	* @param headers - en-têtes fixés par l'action
+	* @param enabled - `false` (option `validators`) : ni validateur, ni
+	*   évaluation, ni `Cache-Control` par défaut — les en-têtes de l'action
+	*   seuls
+	*/
+	#fileCondition(file, headers, enabled) {
 		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"]))) {
-				headers ??= {};
-				this.response.response?.removeHeader("Content-Length");
-				this.response.response?.removeHeader("content-length");
-				headers["Content-Length"] = fileDetails.stats.size;
-			}
-			streamFile = createReadStream(fileDetails.path, options);
-		} catch (e) {
-			this.log(e, "ERROR");
-			throw e;
+		if (!(context instanceof HttpContext)) return {
+			head: headers ?? {},
+			validators: NO_VALIDATORS,
+			outcome: 200,
+			request: {}
+		};
+		const request = context.request.headers;
+		if (!enabled) return {
+			head: headers ?? {},
+			validators: NO_VALIDATORS,
+			outcome: 200,
+			request
+		};
+		const computed = fileValidators(file.stats, Date.now());
+		const response = context.response;
+		const given = (name) => headerIn(headers, name) ?? response.getHeader(name);
+		const head = {};
+		const etag = given("etag");
+		const lastModified = given("last-modified");
+		if (etag === void 0 && computed.etag !== null) head.ETag = computed.etag;
+		if (lastModified === void 0 && computed.lastModified !== null) head["Last-Modified"] = new Date(computed.lastModified).toUTCString();
+		const cacheControl = fileServing.cacheControl;
+		if (cacheControl !== null && given("cache-control") === void 0) head["Cache-Control"] = cacheControl;
+		const validators = etag === void 0 && lastModified === void 0 ? computed : {
+			etag: etag === void 0 ? computed.etag : String(etag),
+			lastModified: lastModified === void 0 ? computed.lastModified : parseHttpDate(String(lastModified)),
+			lastModifiedStrong: lastModified === void 0 ? computed.lastModifiedStrong : false
+		};
+		Object.assign(head, headers);
+		return {
+			head,
+			validators,
+			outcome: evaluatePreconditions(this.method ?? "GET", request, validators),
+			request
+		};
+	}
+	/**
+	* Répond 304 (rien n'a changé) ou 412 (une condition est fausse) sans
+	* ouvrir le fichier. Le 304 porte les en-têtes qu'aurait portés le 200 :
+	* validateurs, `Cache-Control`, `Expires`, `Vary` (RFC 9110 §15.4.5).
+	*/
+	async #answerPrecondition(condition) {
+		if (condition.outcome === 304) {
+			const kept = {};
+			for (const key of Object.keys(condition.head)) if (NOT_MODIFIED_FIELDS.has(key.toLowerCase())) kept[key] = condition.head[key];
+			await this.renderResponse("", "utf8", 304, kept);
+			return null;
 		}
-		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();
+		await this.renderResponse("Precondition Failed", "utf8", 412, { "Content-Type": "text/plain; charset=utf-8" });
+		return null;
+	}
+	/**
+	* Envoie le fichier déjà résolu sur la brique de flux — le cœur de
+	* {@link Controller.streamFile}, sans préconditions.
+	*/
+	async #sendFile(fileDetails, headers, options) {
+		const context = this.context;
+		if (!(context instanceof HttpContext)) throw new HttpError("Flux : un fichier en flux exige une requête HTTP", 500, context);
+		const response = context.response;
+		response.removeHeader("content-type");
+		let head = headers;
+		if (!(head && (head["Content-Type"] || head["content-type"]))) response.setFileMimeType(fileDetails.name);
+		const size = fileDetails.stats.size;
+		const start = options?.start ?? 0;
+		const end = Math.min(options?.end ?? size - 1, size - 1);
+		const length = Math.max(0, end - start + 1);
+		if (!(head && (head["Content-Length"] || head["content-length"]))) {
+			response.removeHeader("content-length");
+			head = {
+				...head,
+				"Content-Length": length
 			};
-			streamFile.on("end", onStreamEnd);
-			streamFile.on("close", onStreamEnd);
-			streamFile.on("error", (error) => {
-				this.log(error, "ERROR");
-				endContext();
-				reject(error);
-			});
+		}
+		const stream = createReadStream(fileDetails.path, length === 0 ? options : {
+			...options,
+			end
 		});
+		await context.openStream(stream, {
+			status: response.statusCode,
+			headers: head,
+			live: false,
+			idleTimeout: 0
+		});
+		return stream;
 	}
 	async renderMediaStream(file, headers = {}, options = {}) {
 		const File = await this.getFileAsync(file);
+		const condition = this.#fileCondition(File, headers, options.validators ?? fileServing.validators);
+		if (condition.outcome !== 200) return this.#answerPrecondition(condition);
 		this.response?.setEncoding("binary");
-		const range = this.request?.headers.range;
+		const ifRange = condition.request["if-range"];
+		const range = this.method === "GET" && (ifRange === void 0 || ifRangeHolds(ifRange, condition.validators)) ? condition.request.range : void 0;
 		const length = File.stats.size;
 		let head;
 		let value;
-		const response = this.response.response;
+		const contextResponse = this.response;
 		const parsed = range ? parseByteRange(range, length) : null;
-		if (parsed === "unsatisfiable") return this.renderResponse("", "utf8", 416, {
+		if (parsed === "unsatisfiable") return this.renderResponse(`Range Not Satisfiable (representation length ${length})`, "utf8", 416, {
+			"Content-Type": "text/plain; charset=utf-8",
 			"Content-Range": `bytes */${length}`,
 			"Accept-Ranges": "bytes"
 		});
@@ -628,22 +835,22 @@ var Controller = class extends Service {
 				"Accept-Ranges": "bytes",
 				"Content-Length": chunksize.toString(),
 				"Content-Type": File.mimeType || "application/octet-stream",
-				...headers
+				...condition.head
 			};
-			response?.removeHeader("content-type");
+			contextResponse.removeHeader("content-type");
 			this.response?.setStatusCode(206);
 		} else {
 			value = { ...options };
 			head = {
 				"Content-Type": File.mimeType || "application/octet-stream",
 				"Content-Length": length.toString(),
-				"Content-Disposition": ` inline; filename="${File.name}"`,
+				"Content-Disposition": contentDisposition("inline", File.name),
 				"Accept-Ranges": "bytes",
-				...headers
+				...condition.head
 			};
-			response?.removeHeader("content-type");
+			contextResponse.removeHeader("content-type");
 		}
-		return this.streamFile(File, head, value);
+		return this.#sendFile(File, head, value);
 	}
 };
-export { Controller as default, parseByteRange };
+export { configureFileServing, Controller as default, parseByteRange };

package/dist/nodefony/src/PlaygroundAdminApi.js

@@ -1,5 +1,5 @@
-import { extractActionScopes, resolveActionMeta } from "../decorators/routerDecorators.js";
 import router_default from "../service/router.js";
+import { extractActionScopes, resolveActionMeta } from "../decorators/routerDecorators.js";
 import AdminApiController from "../controller/AdminApiController.js";
 import { standardJsonSchemaOf } from "nodefony";
 // nodefony/src/PlaygroundAdminApi.ts

package/dist/nodefony/src/Resolver.js

@@ -4,7 +4,7 @@ import { buildParamArgs, computeActionMeta, readInvocationBody, readRouteInput,
 import { computeFingerprint, evaluateIdempotency, isMutationMethod, resolveIdempotencyKey, resolveIdentity } from "./idempotency.js";
 import { authenticationShortfall, stepUpChallenge } from "./requireAuthentication.js";
 import { RequestContext, finallyMaybe, identityHint, isArray, isPlainObject, isPromise, nodefonyError, thenMaybe, typeOf } from "nodefony";
-import { Http2Response, HttpResponse, WebsocketResponse } from "@nodefony/http";
+import { Http2Response, HttpResponse, WebsocketResponse, isContentlessStatus } from "@nodefony/http";
 // nodefony/src/Resolver.ts
 /**
 * Résout une route vers son couple controller/action et exécute l'action —
@@ -396,7 +396,7 @@ var Resolver = class {
 	* (`returnController`) — le chemin du **pont `api.request`** (WS) : la valeur
 	* nue est enveloppée `{id, result}` par le peer, jamais rendue sur le
 	* transport. La méthode HTTP logique d'une mutation du pont voyage dans
-	* {@link methodOverride} ; sans porte ici, un rejeu `socket.mutate` (socket
+	* {@link methodOverride} ; sans porte ici, un rejeu `socket.post` (socket
 	* qui reconnecte) ré-exécuterait la mutation (doublon — vécu au banc duplex).
 	*
 	* @returns `{ result }` — la valeur retournée par l'action (ou la réponse
@@ -668,15 +668,18 @@ var Resolver = class {
 					return this.context.render(result);
 				}
 				switch (this.context.type) {
-					case "http": this.context.waitAsync = true;
+					case "http":
+						this.context.waitAsync = true;
+						this.unrendered = `une instance de ${(typeof result === "object" && result !== null ? result.constructor.name : void 0) ?? "classe"}`;
 				}
 				return;
 			default: switch (this.context.type) {
 				case "http":
 					if (this.context.sended) return;
 					if (this.context.isRedirect) return this.context.send();
-					if (NO_BODY_STATUS.has(this.getResponseStatus())) return this.context.send();
+					if (isContentlessStatus(this.getResponseStatus())) return this.context.send();
 					this.context.waitAsync = true;
+					this.unrendered = result === null ? "null" : typeof result;
 			}
 		}
 	}
@@ -710,10 +713,4 @@ var Resolver = class {
 		throw new nodefonyError(identityHint(this.context.kernel) === null ? "Authentication required" : `Authentication required — ${cause}. Reconnectez-vous (\`@RequireAuthentication\` de la route).`, 401);
 	}
 };
-/** Statuts dont la réponse n'a, par définition, pas de corps (RFC 9110). */
-const NO_BODY_STATUS = /* @__PURE__ */ new Set([
-	204,
-	205,
-	304
-]);
 export { Resolver as default };