@nodefony/http 10.0.0-beta.5 → 10.0.0-beta.7

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

@@ -1,21 +1,12 @@
-import HttpError from "../../errors/httpError.js";
-import Http2Response from "../http2/Response.js";
-import { RequestContext } from "nodefony";
+import { MAX_TIMER_MS, STREAM_STALL_TIMEOUT_MS, checkStreamTimer, openStreamLifecycle } from "./StreamLifecycle.js";
 import http from "node:http";
-import { AsyncResource } from "node:async_hooks";
 // 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;
+/** Délai de blocage d'écriture par défaut, en ms — celui de tout flux. */
+const SSE_STALL_TIMEOUT_MS = STREAM_STALL_TIMEOUT_MS;
 /** 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). */
@@ -38,21 +29,19 @@ function singleLine(name, value) {
 *
 * `JSON.stringify` rend `undefined` pour `undefined`, une fonction ou un
 * symbole, et son type `string` le tait : on l'élargit avant de le lire.
+*
+* Des octets sont refusés : un flux SSE est du texte UTF-8 (WHATWG HTML
+* §9.2), et `JSON.stringify` les rendrait en objet (`[1,2,255]` →
+* `{"0":1,"1":2,"2":255}`) sans erreur (ADR-0021 S8).
+*
+* @throws TypeError quand `data` est un `ArrayBuffer` ou une vue sur octets.
 */
 function serialize(data) {
 	if (typeof data === "string") return data;
+	if (ArrayBuffer.isView(data) || data instanceof ArrayBuffer) throw new TypeError("SSE : un flux SSE ne porte que du texte UTF-8, des octets n'y passent pas — les encoder en base64 dans la charge, avec leur type MIME (ex. { mimeType: \"image/png\", data: \"<base64>\" }).");
 	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 = "";
@@ -65,69 +54,53 @@ function lines(prefix, text) {
 * 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.
+*
+* Typé par une carte d'événements (`ContractServerEmit<C>` : le MÊME contrat
+* que la socket temps réel) : `event:` est un canal de la carte et la charge est
+* celle du canal. Deux formes se lisent sur la même carte — **multiplexé**
+* (`send(data, { event: canal })`, plusieurs canaux sur une connexion) ou **un
+* flux = un canal** (carte d'un seul canal, `send(data)` sans `event`). Sans
+* carte, le flux reste libre (porte MCP, flux hors contrat). Le type n'est pas
+* une validation, et ne coûte rien à l'exécution.
+*
+* @typeParam Events - carte des événements du flux.
 */
 var SseStream = class {
-	#context;
-	#target;
-	/** La réponse dont on écoute la fermeture — en HTTP/2, l'objet de compatibilité. */
-	#response;
-	#stallTimeout;
+	/** Cycle de vie partagé avec le flux d'octets : fin, gardes, registre. */
+	#lifecycle;
 	#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;
+	constructor(lifecycle, settings) {
+		this.#lifecycle = lifecycle;
 		this.#maxEventBytes = settings.maxEventBytes;
-		this.#revalidate = settings.revalidate;
-		this.identifier = settings.identifier;
-		response.on("close", this.#onResponseClose);
+		lifecycle.onRelease(() => this.#release());
 		const heartbeat = settings.heartbeat;
-		if (settings.maxDuration !== false) {
-			this.#lifetime = setTimeout(() => void this.close(), settings.maxDuration);
-			this.#lifetime.unref();
-		}
-		if (heartbeat !== false && heartbeat > 0) {
+		if (!lifecycle.closed && heartbeat !== false && heartbeat > 0) {
+			const target = lifecycle.target;
 			this.#heartbeat = setInterval(() => {
-				if (this.#drain === null) this.#target.write(HEARTBEAT);
+				if (this.#drain === null) target.write(HEARTBEAT);
 			}, heartbeat);
 			this.#heartbeat.unref();
 		}
 	}
+	/**
+	* 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
+	*/
+	get identifier() {
+		return this.#lifecycle.identifier;
+	}
 	/** Le flux est-il fermé — par le serveur (`close()`) ou par le client parti ? */
 	get closed() {
-		return this.#closed;
+		return this.#lifecycle.closed;
 	}
 	/**
 	* L'identité qui a ouvert le flux est-elle toujours valable ? Lu par le
@@ -136,7 +109,7 @@ var SseStream = class {
 	* @internal
 	*/
 	revalidate() {
-		return this.#revalidate === null ? Promise.resolve(true) : this.#revalidate();
+		return this.#lifecycle.revalidate();
 	}
 	/**
 	* Envoie un événement.
@@ -147,7 +120,9 @@ var SseStream = class {
 	* @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 TypeError quand `event` ou `id` contient une fin de ligne, ou
+	*   quand `data` est fait d'octets (`Uint8Array`, `Buffer`, `ArrayBuffer`) :
+	*   un flux SSE ne porte que du texte, les encoder soi-même (base64).
 	* @throws RangeError quand l'événement dépasse `maxEventBytes`.
 	*/
 	send(data, options) {
@@ -174,7 +149,7 @@ var SseStream = class {
 	* @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`);
+		if (!Number.isInteger(ms) || ms < 0 || ms > 2147483647) throw new RangeError(`retry : entier entre 0 et ${MAX_TIMER_MS} ms attendu`);
 		return this.#write(`retry: ${ms}\n\n`);
 	}
 	/**
@@ -186,13 +161,7 @@ var SseStream = class {
 	* 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);
+		this.#lifecycle.onClose(listener);
 	}
 	/**
 	* Ferme le flux et termine la requête. Idempotent.
@@ -200,58 +169,40 @@ var SseStream = class {
 	* @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;
+		return this.#lifecycle.close();
 	}
 	/** Écrit une trame ; une promesse seulement sous contre-pression. */
 	#write(frame) {
-		if (this.#closed) return void 0;
+		const lifecycle = this.#lifecycle;
+		if (lifecycle.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;
+		const target = lifecycle.target;
+		if (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();
-			}
+			target.once("drain", this.#onDrain);
+			lifecycle.armStall();
 		}
 		return this.#drain;
 	}
 	#settleDrain() {
-		if (this.#stall !== null) {
-			clearTimeout(this.#stall);
-			this.#stall = null;
-		}
+		this.#lifecycle.clearStall();
 		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);
+	/** Fin du flux, appelée UNE fois par le cycle de vie : battement et attentes libérés. */
+	#release() {
+		this.#lifecycle.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();
 	}
 };
 /**
@@ -293,56 +244,40 @@ function acceptsEventStream(accept) {
 *   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);
+	checkStreamTimer("SSE", "heartbeat", options.heartbeat);
+	checkStreamTimer("SSE", "stallTimeout", options.stallTimeout);
+	checkStreamTimer("SSE", "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
+		maxEventBytes
 	};
-	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"
+	const opened = openStreamLifecycle(context, {
+		label: "SSE",
+		stallTimeout: options.stallTimeout ?? SSE_STALL_TIMEOUT_MS,
+		maxDuration: options.maxDuration ?? false
 	});
-	context.writeHead(200);
-	if (stream !== null) stream.setTimeout(0);
-	else if (h1 !== null) {
-		h1.flushHeaders();
-		h1.socket?.setTimeout(0);
+	return opened instanceof Promise ? opened.then((lifecycle) => startSseStream(lifecycle, options, settings)) : startSseStream(opened, options, settings);
+}
+/**
+* En-têtes, désarmement du délai, puis le flux. Un client parti pendant
+* l'ouverture rend un flux déjà fermé, sans rien écrire.
+*/
+function startSseStream(lifecycle, options, settings) {
+	if (!lifecycle.closed) {
+		const context = lifecycle.context;
+		context.response.setHeaders({
+			"Content-Type": "text/event-stream; charset=utf-8",
+			"Cache-Control": "no-cache, no-transform",
+			"X-Accel-Buffering": "no"
+		});
+		context.writeHead(200);
+		const target = lifecycle.target;
+		if (target instanceof http.ServerResponse) target.flushHeaders();
+		lifecycle.disarmIdleTimeout();
 	}
-	const sse = new SseStream(context, target, nodeResponse, settings);
-	if (settings.revalidate !== null) context.httpKernel?.watchStream(sse);
+	const sse = new SseStream(lifecycle, settings);
 	if (options.retry !== void 0) sse.retry(options.retry);
 	return sse;
 }