@nodefony/http 10.0.0-beta.2 → 10.0.0-beta.3

package/dist/nodefony/src/context/http/SseStream.js

@@ -0,0 +1,350 @@
+import HttpError from "../../errors/httpError.js";
+import Http2Response from "../http2/Response.js";
+import { RequestContext } from "nodefony";
+import http from "node:http";
+import { AsyncResource } from "node:async_hooks";
+//#region nodefony/src/context/http/SseStream.ts
+/** Battement de cœur par défaut, en ms (§9.2.7 : « every 15 seconds or so »). */
+const SSE_HEARTBEAT_MS = 15e3;
+/** Délai de blocage d'écriture par défaut, en ms. */
+const SSE_STALL_TIMEOUT_MS = 3e4;
+/** Taille maximale d'un événement par défaut, en octets (1 Mio). */
+const SSE_MAX_EVENT_BYTES = 1048576;
+/**
+* Plus long délai qu'un minuteur sait tenir (2^31-1 ms). Au-delà, Node le
+* ramène à 1 ms : un `retry` qui le dépasse ferait reconnecter le client en
+* rafale, un battement qui le dépasse battrait mille fois par seconde.
+*/
+const MAX_TIMER_MS = 2147483647;
+/** Commentaire de battement de cœur — ignoré par tout client conforme. */
+const HEARTBEAT = ":\n\n";
+/** Fin de ligne : CRLF, CR ou LF (§9.2.5). */
+const LINE_BREAK = /\r\n|\r|\n/;
+/**
+* Refuse un champ d'une seule ligne qui contiendrait une fin de ligne.
+*
+* Laisser passer un CR ou un LF dans `event` ou `id` permettrait à une valeur
+* venue d'un utilisateur de clore l'événement et d'en FORGER un autre dans le
+* flux — l'équivalent SSE d'une injection d'en-tête.
+*
+* @throws TypeError quand la valeur contient CR, LF ou NUL.
+*/
+function singleLine(name, value) {
+	if (/[\r\n\0]/.test(value)) throw new TypeError(`Champ SSE « ${name} » : fin de ligne ou NUL interdits`);
+	return value;
+}
+/**
+* Texte d'un événement : la chaîne telle quelle, sinon son JSON.
+*
+* `JSON.stringify` rend `undefined` pour `undefined`, une fonction ou un
+* symbole, et son type `string` le tait : on l'élargit avant de le lire.
+*/
+function serialize(data) {
+	if (typeof data === "string") return data;
+	const json = JSON.stringify(data);
+	return typeof json === "string" ? json : "";
+}
+/**
+* Refuse une option de délai hors de ce qu'un minuteur sait tenir.
+*
+* @throws RangeError quand la valeur n'est ni `false` ni un entier entre 1 et 2^31-1.
+*/
+function checkTimer(name, value) {
+	if (value === void 0 || value === false) return;
+	if (!Number.isInteger(value) || value < 1 || value > MAX_TIMER_MS) throw new RangeError(`SSE : ${name} entier entre 1 et ${MAX_TIMER_MS} ms, ou false, attendu`);
+}
+/** Préfixe chaque ligne d'un texte par `prefix` — `data: ` ou `: `. */
+function lines(prefix, text) {
+	let out = "";
+	for (const line of text.split(LINE_BREAK)) out += `${prefix}${line}\n`;
+	return out;
+}
+/**
+* Un flux `text/event-stream` ouvert sur une réponse.
+*
+* Il s'obtient par {@link openSseStream} (ou `this.renderSse()` dans un
+* contrôleur), jamais par `new` : l'ouverture écrit les en-têtes, et un flux
+* sans en-têtes ne se rattrape pas.
+*/
+var SseStream = class {
+	#context;
+	#target;
+	/** La réponse dont on écoute la fermeture — en HTTP/2, l'objet de compatibilité. */
+	#response;
+	#stallTimeout;
+	#maxEventBytes;
+	#revalidate;
+	/**
+	* Identifiant de connexion de l'identité qui a ouvert le flux (`null` pour
+	* un anonyme) — le registre de révocation ferme par lui les flux d'une
+	* identité dont les droits ont changé.
+	*
+	* @internal
+	*/
+	identifier;
+	#closed = false;
+	#heartbeat = null;
+	/** Coupure d'un client qui ne lit plus — armée seulement sous pression. */
+	#stall = null;
+	/** Fin de vie du flux — armée seulement si `maxDuration` est posé. */
+	#lifetime = null;
+	/** Écouteurs de fermeture — `null` tant que personne n'en pose (lazy). */
+	#onClose = null;
+	/** Attente de `drain` en cours, partagée par tous les `send()` sous pression. */
+	#drain = null;
+	#releaseDrain = null;
+	#onResponseClose = () => this.#finish();
+	#onDrain = () => this.#settleDrain();
+	/**
+	* Le client ne lit plus depuis `stallTimeout` : on coupe la connexion, comme
+	* s'il était parti — la fermeture de la réponse termine le flux.
+	*/
+	#onStall = () => {
+		this.#stall = null;
+		this.#target.destroy();
+	};
+	/** @internal — passer par {@link openSseStream}. */
+	constructor(context, target, response, settings) {
+		this.#context = context;
+		this.#target = target;
+		this.#response = response;
+		this.#stallTimeout = settings.stallTimeout;
+		this.#maxEventBytes = settings.maxEventBytes;
+		this.#revalidate = settings.revalidate;
+		this.identifier = settings.identifier;
+		response.on("close", this.#onResponseClose);
+		const heartbeat = settings.heartbeat;
+		if (settings.maxDuration !== false) {
+			this.#lifetime = setTimeout(() => void this.close(), settings.maxDuration);
+			this.#lifetime.unref();
+		}
+		if (heartbeat !== false && heartbeat > 0) {
+			this.#heartbeat = setInterval(() => {
+				if (this.#drain === null) this.#target.write(HEARTBEAT);
+			}, heartbeat);
+			this.#heartbeat.unref();
+		}
+	}
+	/** Le flux est-il fermé — par le serveur (`close()`) ou par le client parti ? */
+	get closed() {
+		return this.#closed;
+	}
+	/**
+	* L'identité qui a ouvert le flux est-elle toujours valable ? Lu par le
+	* registre de révocation du noyau HTTP.
+	*
+	* @internal
+	*/
+	revalidate() {
+		return this.#revalidate === null ? Promise.resolve(true) : this.#revalidate();
+	}
+	/**
+	* Envoie un événement.
+	*
+	* @param data - texte envoyé tel quel, ou valeur sérialisée en JSON ; un
+	*   texte de plusieurs lignes part en autant de champs `data:`.
+	* @param options - type (`event`) et identifiant (`id`) de l'événement.
+	* @returns rien quand l'écriture est acceptée ; une promesse réglée au
+	*   `drain` quand le client lit moins vite qu'on écrit — l'attendre borne la
+	*   mémoire du serveur. Sans effet une fois le flux fermé.
+	* @throws TypeError quand `event` ou `id` contient une fin de ligne.
+	* @throws RangeError quand l'événement dépasse `maxEventBytes`.
+	*/
+	send(data, options) {
+		let frame = "";
+		if (options?.event !== void 0) frame += `event: ${singleLine("event", options.event)}\n`;
+		if (options?.id !== void 0) frame += `id: ${singleLine("id", options.id)}\n`;
+		frame += `${lines("data: ", serialize(data))}\n`;
+		return this.#write(frame);
+	}
+	/**
+	* Envoie un commentaire — ignoré par le client, utile pour garder une
+	* connexion vivante ou marquer le flux à la lecture.
+	*
+	* @returns comme {@link send}.
+	*/
+	comment(text = "") {
+		return this.#write(`${lines(": ", text)}\n`);
+	}
+	/**
+	* Impose au client un délai de reconnexion (champ `retry:`).
+	*
+	* @param ms - délai en millisecondes, entier positif.
+	* @returns comme {@link send}.
+	* @throws RangeError quand `ms` n'est pas un entier entre 0 et 2^31-1.
+	*/
+	retry(ms) {
+		if (!Number.isInteger(ms) || ms < 0 || ms > MAX_TIMER_MS) throw new RangeError(`retry : entier entre 0 et ${MAX_TIMER_MS} ms attendu`);
+		return this.#write(`retry: ${ms}\n\n`);
+	}
+	/**
+	* Appelle `listener` à la fermeture du flux, quelle qu'en soit la cause.
+	*
+	* L'écouteur est lié au contexte asynchrone de la requête au moment de
+	* l'enregistrement : la fermeture par le client part de la SOCKET, hors de
+	* la bulle de la requête, et un `RequestContext.get()` y rendrait `undefined`.
+	* Un flux déjà fermé appelle l'écouteur au tour suivant.
+	*/
+	onClose(listener) {
+		const bound = AsyncResource.bind(listener);
+		if (this.#closed) {
+			queueMicrotask(bound);
+			return;
+		}
+		this.#onClose ??= [];
+		this.#onClose.push(bound);
+	}
+	/**
+	* Ferme le flux et termine la requête. Idempotent.
+	*
+	* @returns la fin de la requête (hooks `onClose` du contexte compris).
+	*/
+	close() {
+		if (this.#closed) return void 0;
+		this.#finish();
+		const done = this.#context.close();
+		return done instanceof Promise ? done.then(() => void 0) : void 0;
+	}
+	/** Écrit une trame ; une promesse seulement sous contre-pression. */
+	#write(frame) {
+		if (this.#closed) return void 0;
+		const max = this.#maxEventBytes;
+		if (frame.length * 3 > max && Buffer.byteLength(frame) > max) throw new RangeError(`SSE : événement de plus de ${max} octets refusé`);
+		if (this.#target.write(frame)) return void 0;
+		if (this.#drain === null) {
+			this.#drain = new Promise((resolve) => {
+				this.#releaseDrain = resolve;
+			});
+			this.#target.once("drain", this.#onDrain);
+			if (this.#stallTimeout !== false) {
+				this.#stall = setTimeout(this.#onStall, this.#stallTimeout);
+				this.#stall.unref();
+			}
+		}
+		return this.#drain;
+	}
+	#settleDrain() {
+		if (this.#stall !== null) {
+			clearTimeout(this.#stall);
+			this.#stall = null;
+		}
+		const release = this.#releaseDrain;
+		this.#drain = null;
+		this.#releaseDrain = null;
+		release?.();
+	}
+	/** Fin du flux : minuteur, écouteurs et attentes libérés, une seule fois. */
+	#finish() {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#response.removeListener("close", this.#onResponseClose);
+		this.#target.removeListener("drain", this.#onDrain);
+		if (this.#heartbeat !== null) {
+			clearInterval(this.#heartbeat);
+			this.#heartbeat = null;
+		}
+		if (this.#lifetime !== null) {
+			clearTimeout(this.#lifetime);
+			this.#lifetime = null;
+		}
+		if (this.#revalidate !== null) this.#context.httpKernel?.unwatchStream(this);
+		this.#settleDrain();
+		const listeners = this.#onClose;
+		this.#onClose = null;
+		if (listeners !== null) for (const listener of listeners) listener();
+	}
+};
+/**
+* Le client accepte-t-il un flux d'événements ? Lit l'en-tête `Accept`.
+*
+* Un même `POST` répond en JSON ou en flux selon ce que demande le client
+* (porte MCP) : c'est cette fonction qui tranche, et elle seule. Une plage
+* `q=0` est un REFUS explicite (RFC 9110 §12.4.2) ; `*\/*` ne suffit pas — un
+* client qui ne nomme pas le flux ne sait pas le lire.
+*
+* @param accept - valeur de l'en-tête `Accept`, absente ou multiple.
+* @returns `true` quand `text/event-stream` est nommé avec un poids non nul.
+*/
+function acceptsEventStream(accept) {
+	if (accept === void 0) return false;
+	const value = Array.isArray(accept) ? accept.join(",") : accept;
+	for (const range of value.split(",")) {
+		const [type, ...params] = range.split(";");
+		if (type?.trim().toLowerCase() !== "text/event-stream") continue;
+		const q = params.map((p) => p.trim().toLowerCase()).find((p) => p.startsWith("q="));
+		if (q === void 0 || Number.parseFloat(q.slice(2)) > 0) return true;
+	}
+	return false;
+}
+/**
+* Ouvre un flux d'événements sur la réponse d'un contexte HTTP.
+*
+* Sauve la session d'abord — ses cookies partent avec les en-têtes, qu'on ne
+* pourra plus toucher —, puis écrit les en-têtes du flux et désarme le délai
+* d'inactivité de la requête.
+*
+* @param context - le contexte de la requête, pas encore répondu.
+* @param options - battement de cœur, délai `retry:` initial.
+* @returns le flux ouvert, ou sa promesse quand une session est à sauver.
+* @throws HttpError 500 quand la réponse est déjà partie.
+* @throws HttpError 429 quand l'IP du client a déjà tous ses flux et sockets
+*   (`wsMaxConnectionsPerIp`) — refusé AVANT d'écrire quoi que ce soit.
+* @throws RangeError quand un délai n'est ni `false` ni un entier entre 1 et
+*   2^31-1, ou que `maxEventBytes` n'est pas un entier positif.
+*/
+function openSseStream(context, options = {}) {
+	checkTimer("heartbeat", options.heartbeat);
+	checkTimer("stallTimeout", options.stallTimeout);
+	checkTimer("maxDuration", options.maxDuration);
+	const maxEventBytes = options.maxEventBytes ?? 1048576;
+	if (!Number.isInteger(maxEventBytes) || maxEventBytes < 1) throw new RangeError("SSE : maxEventBytes entier positif attendu");
+	if (context.sended || context.finished || context.response.isHeaderSent()) throw new HttpError("SSE : la réponse est déjà partie", 500, context);
+	const kernel = context.httpKernel;
+	const nodeResponse = context.response.response;
+	if (kernel !== null && nodeResponse !== null && !kernel.acquireConnectionSlot(context.request.request, nodeResponse)) throw new HttpError("SSE : trop de connexions ouvertes depuis cette adresse", 429, context);
+	const revalidate = kernel?.firewall?.currentRevalidator?.() ?? null;
+	const identifier = revalidate === null ? null : RequestContext.getAuthenticatedUser()?.identifier ?? null;
+	const settings = {
+		heartbeat: options.heartbeat ?? 15e3,
+		stallTimeout: options.stallTimeout ?? 3e4,
+		maxEventBytes,
+		maxDuration: options.maxDuration ?? false,
+		revalidate,
+		identifier
+	};
+	context.sended = true;
+	if (context.session != null) return context.saveSession().catch((e) => {
+		context.log(e, "ERROR", "SESSION-STORE");
+		return null;
+	}).then(() => startSseStream(context, options, settings));
+	return startSseStream(context, options, settings);
+}
+/** En-têtes, désarmement du délai, puis le flux. */
+function startSseStream(context, options, settings) {
+	const response = context.response;
+	const nodeResponse = response.response;
+	if (nodeResponse === null) throw new HttpError("SSE : réponse introuvable", 500, context);
+	const stream = response instanceof Http2Response ? response.stream : null;
+	const h1 = nodeResponse instanceof http.ServerResponse ? nodeResponse : null;
+	let target;
+	if (stream !== null) target = stream;
+	else if (h1 !== null) target = h1;
+	else throw new HttpError("SSE : transport de réponse inconnu", 500, context);
+	response.setHeaders({
+		"Content-Type": "text/event-stream; charset=utf-8",
+		"Cache-Control": "no-cache, no-transform",
+		"X-Accel-Buffering": "no"
+	});
+	context.writeHead(200);
+	if (stream !== null) stream.setTimeout(0);
+	else if (h1 !== null) {
+		h1.flushHeaders();
+		h1.socket?.setTimeout(0);
+	}
+	const sse = new SseStream(context, target, nodeResponse, settings);
+	if (settings.revalidate !== null) context.httpKernel?.watchStream(sse);
+	if (options.retry !== void 0) sse.retry(options.retry);
+	return sse;
+}
+//#endregion
+export { SSE_HEARTBEAT_MS, SSE_MAX_EVENT_BYTES, SSE_STALL_TIMEOUT_MS, SseStream, acceptsEventStream, openSseStream };

package/dist/nodefony/src/context/responseEnded.js

@@ -0,0 +1,27 @@
+import http2 from "node:http2";
+//#region nodefony/src/context/responseEnded.ts
+/**
+* La réponse a-t-elle été TERMINÉE par le serveur ? Règle UNIQUE, pour HTTP/1.1
+* comme pour HTTP/2 — l'écouteur `close` du noyau (client parti → 499) et le
+* timeout par flux de `HttpContext` l'appellent tous deux.
+*
+* Sous HTTP/2, la réponse Nodefony écrit et termine le FLUX
+* (`stream.respond`/`stream.end`), jamais la réponse de compatibilité : son
+* `writableEnded` reste à `false` alors que le client a tout reçu. Mais le
+* flux seul ne suffit pas non plus : un flux ANNULÉ par le pair (RST_STREAM
+* avant la fin) a LUI AUSSI `writableEnded === true`, Node terminant le côté
+* écriture en le détruisant. `aborted` sépare la fin posée par le serveur de la
+* coupure du client — même sémantique que `writableEnded` en HTTP/1.1.
+*
+* @param response - la réponse Node de la requête
+* @returns `true` si le serveur a terminé la réponse (ou son flux HTTP/2) ;
+*   `false` s'il ne l'a pas terminée, client parti compris
+*/
+function responseEnded(response) {
+	if (response.writableEnded) return true;
+	if (!(response instanceof http2.Http2ServerResponse)) return false;
+	const stream = response.stream;
+	return stream.writableEnded && !stream.aborted;
+}
+//#endregion
+export { responseEnded };

package/dist/nodefony/src/context/websocket/Response.js

@@ -1,6 +1,7 @@
 import Cookie from "../../cookies/cookie.js";
 import { decideSend, readBackpressureOptions } from "./wsBackpressure.js";
 import { toWsCloseReason } from "./wsCloseReason.js";
+import { RequestContext } from "nodefony";
 import http from "node:http";
 import Ws from "ws";
 //#region nodefony/src/context/websocket/Response.ts
@@ -156,6 +157,14 @@ var WebsocketResponse = class {
 			if (isNaN(status)) status = 500;
 		}
 		if (!status) status = 500;
+		const sink = RequestContext.get()?.renderSink;
+		if (sink) {
+			sink.status = status;
+			return {
+				code: status,
+				message: message ?? ""
+			};
+		}
 		this.statusCode = status;
 		if (!message) message = WS_CLOSE_DESCRIPTIONS[this.statusCode] ?? http.STATUS_CODES[this.statusCode];
 		this.statusMessage = message ?? "";

package/dist/nodefony/src/context/websocket/WebsocketContext.js

@@ -5,6 +5,7 @@ import WebsocketResponse from "./Response.js";
 import { sanitizeRequestId } from "../requestId.js";
 import { FrameProfile } from "../../profiler/FrameProfile.js";
 import { formatWsLogContent } from "./wsLogContent.js";
+import { parseWebsocketUrl } from "./websocketUrl.js";
 import { RequestContext, logColor } from "nodefony";
 import Ws from "ws";
 import { AsyncResource } from "node:async_hooks";
@@ -91,9 +92,7 @@ var WebsocketContext = class extends Context {
 		this.scheme = type === "websocket-secure" ? "wss" : "ws";
 		const incomingId = sanitizeRequestId(req.headers["x-request-id"]);
 		if (incomingId) this.requestId = incomingId;
-		const host = req.headers.host ?? "localhost";
-		const rawUrl = req.url ?? "/";
-		this.wsUrl = new URL(`${this.scheme}://${host}${rawUrl}`);
+		this.wsUrl = parseWebsocketUrl(this.scheme, req.headers.host, req.url);
 		this.queryGet = Object.fromEntries(this.wsUrl.searchParams.entries());
 		this.queryRequest = { ...this.queryGet };
 		this.wsPath = this.wsUrl.pathname + this.wsUrl.search;

package/dist/nodefony/src/context/websocket/websocketUrl.js

@@ -0,0 +1,21 @@
+//#region nodefony/src/context/websocket/websocketUrl.ts
+/**
+* URL d'une requête d'upgrade WebSocket, telle que le pipeline la lit.
+*
+* Seule construction : le contexte WebSocket en tire son chemin et sa requête,
+* et le contrôle d'avant `101` en tire le chemin qu'il confronte aux routes.
+* Deux constructions divergeraient — `//a/b` lu comme un chemin d'un côté, comme
+* un hôte de l'autre — et une route acceptée par l'une serait refusée par
+* l'autre.
+*
+* @param scheme - `ws` ou `wss`
+* @param host - en-tête `Host` de la requête (`localhost` s'il manque)
+* @param rawUrl - cible brute de la requête (`/` si elle manque)
+* @returns l'URL analysée
+* @throws TypeError si l'hôte ou la cible ne forment pas une URL
+*/
+function parseWebsocketUrl(scheme, host, rawUrl) {
+	return new URL(`${scheme}://${host ?? "localhost"}${rawUrl ?? "/"}`);
+}
+//#endregion
+export { parseWebsocketUrl };

package/dist/nodefony/src/profiler/Profiler.js

@@ -122,18 +122,14 @@ function readSecurity(ctx) {
 /**
 * Identité de la requête.
 *
-* `context.user` n'est PAS la source de vérité en zone firewall : le token
-* résolu vit dans l'ALS (`RequestContext`), qui n'est plus lisible au teardown
-* où `collect()` s'exécute. Sans le repli sur la trace, une requête pleinement
-* authentifiée (rôles compris) s'afficherait « anonyme ».
+* Le jeton résolu vit dans l'ALS, qui n'est plus lisible au teardown où
+* `collect()` s'exécute : le pare-feu pose donc l'identifiant de l'appelant
+* authentifié sur `context.userIdentifier` (même source que le journal
+* d'audit). La trace du pare-feu prend le relais pour l'anonyme d'une zone
+* `anonymous`, qu'elle nomme.
 */
 function readUser(ctx) {
-	const u = ctx.user;
-	if (u && typeof u === "object") {
-		const username = u.username;
-		if (typeof username === "string") return username;
-	}
-	return ctx.securityTrace?.user ?? null;
+	return ctx.userIdentifier ?? ctx.securityTrace?.user ?? null;
 }
 //#endregion
 export { Profiler, Profiler as default };