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

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

@@ -0,0 +1,364 @@
+import HttpError from "../../errors/httpError.js";
+import { SSE_STALL_TIMEOUT_MS } from "./SseStream.js";
+import { MAX_TIMER_MS, checkStreamTimer, openStreamLifecycle } from "./StreamLifecycle.js";
+import http from "node:http";
+import { AsyncResource } from "node:async_hooks";
+import { Readable } from "node:stream";
+// nodefony/src/context/http/ByteStream.ts
+/** Erreur d'une source après la fin de son flux : plus personne à prévenir. */
+const IGNORE_LATE_ERROR = () => void 0;
+/**
+* Un flux d'octets en cours sur une réponse — interne : on l'obtient par
+* {@link openByteStream}, qui ne rend que sa promesse de fin.
+*/
+var ByteStream = class {
+	#lifecycle;
+	#source;
+	#settings;
+	done;
+	#resolve;
+	#bytes = 0;
+	/** Les en-têtes sont-ils partis ? Posé au premier morceau, ou à la fin. */
+	#headed = false;
+	/** Raison posée par le flux lui-même ; `null` : le cycle de vie tranchera. */
+	#reason = null;
+	/** La résolution attend la fin de la requête (fin propre, erreur rendue). */
+	#settleLater = false;
+	#waitingDrain = false;
+	/** Octets vus au dernier tour de garde où la source avait avancé. */
+	#seenBytes = 0;
+	/** Heure de ce tour (`Date.now()`) — une lecture par tour, jamais par morceau. */
+	#seenAt = 0;
+	#watchdog = null;
+	/** `Content-Length` annoncé, lu une fois aux en-têtes ; `-1` : aucun. */
+	#declared = -1;
+	/** Requête HEAD : aucun corps, la longueur annoncée est celle du GET. */
+	#head = false;
+	#onData = (chunk) => this.#write(chunk);
+	#onEnd = () => this.#finishClean();
+	#onSourceError = (error) => this.#fail(error, "error");
+	/** Une source détruite sans erreur ni fin : on la tient pour finie. */
+	#onSourceClose = () => {
+		if (this.#source.errored === null) this.#finishClean();
+	};
+	/**
+	* Écouteur `drain` PERMANENT, posé une fois (comme `pipe`) : un `once` par
+	* épisode de contre-pression allouait un enrobage par morceau sur une socket
+	* rapide, où presque chaque écriture de 64 Kio rend `false`.
+	*/
+	#onDrain = () => {
+		if (!this.#waitingDrain) return;
+		this.#waitingDrain = false;
+		this.#lifecycle.clearStall();
+		this.#source.resume();
+	};
+	#onIdle = () => this.#checkIdle();
+	constructor(lifecycle, source, settings) {
+		this.#lifecycle = lifecycle;
+		this.#source = source;
+		this.#settings = settings;
+		this.done = new Promise((resolve) => {
+			this.#resolve = resolve;
+		});
+		lifecycle.onRelease(() => this.#release());
+	}
+	/** Démarre le flux : HEAD, source déjà finie, ou lecture de la source. */
+	start() {
+		const lifecycle = this.#lifecycle;
+		if (lifecycle.closed) return;
+		lifecycle.disarmIdleTimeout();
+		const source = this.#source;
+		source.on("error", this.#onSourceError);
+		if (lifecycle.context.getMethod() === "HEAD") {
+			this.#head = true;
+			this.#finishClean();
+			return;
+		}
+		if (source.errored !== null) {
+			this.#fail(source.errored, "error");
+			return;
+		}
+		if (source.destroyed || source.readableEnded) {
+			this.#finishClean();
+			return;
+		}
+		lifecycle.target.on("drain", this.#onDrain);
+		const idle = this.#settings.idleTimeout;
+		if (idle > 0) {
+			this.#seenAt = Date.now();
+			this.#watchdog = setInterval(this.#onIdle, Math.max(1, Math.floor(idle / 4)));
+			this.#watchdog.unref();
+		}
+		source.once("end", this.#onEnd);
+		source.once("close", this.#onSourceClose);
+		source.on("data", this.#onData);
+	}
+	/**
+	* En-têtes au premier morceau (ou à la fin d'une source vide).
+	*
+	* @param first - octets du premier morceau (0 : source vide).
+	* @throws Error quand ce morceau contredit déjà `Content-Length` — levé
+	*   AVANT `writeHead` : rien n'est parti, la page d'erreur le peut.
+	*/
+	#writeHead(first) {
+		const context = this.#lifecycle.context;
+		const { headers, live, status } = this.#settings;
+		const response = context.response;
+		if (headers !== null) response.setHeaders(headers);
+		response.setDefaultHeader("Content-Type", "application/octet-stream");
+		if (live) {
+			response.setDefaultHeader("Cache-Control", "no-cache, no-transform");
+			response.setDefaultHeader("X-Accel-Buffering", "no");
+		}
+		const length = response.getHeader("content-length");
+		if (length !== void 0) {
+			const declared = Number(length);
+			if (Number.isSafeInteger(declared) && declared >= 0) this.#declared = declared;
+		}
+		if (this.#declared !== -1 && !this.#head && (first === 0 ? this.#declared !== 0 : first > this.#declared)) throw this.#lengthMismatch(first > this.#declared ? "plus" : "moins");
+		context.writeHead(status);
+	}
+	/**
+	* Les en-têtes, sans jamais lever : appelé depuis un écouteur `data` ou
+	* `end`, une exception (valeur d'en-tête refusée) n'aurait personne pour la
+	* rattraper et abattrait le processus. Un échec passe par le chemin d'erreur
+	* d'avant le premier octet — rien n'est parti, la page d'erreur peut l'être.
+	*
+	* @returns `false` quand les en-têtes n'ont pas pu partir.
+	*/
+	#tryWriteHead(first) {
+		try {
+			this.#writeHead(first);
+			this.#headed = true;
+			return true;
+		} catch (e) {
+			this.#fail(e instanceof Error ? e : new Error(String(e)), "error");
+			return false;
+		}
+	}
+	#write(chunk) {
+		if (this.#reason !== null || this.#lifecycle.closed) return;
+		const size = typeof chunk === "string" ? Buffer.byteLength(chunk) : chunk.byteLength;
+		if (!this.#headed && !this.#tryWriteHead(size)) return;
+		if (this.#declared !== -1 && this.#bytes + size > this.#declared) {
+			this.#fail(this.#lengthMismatch("plus"), "error");
+			return;
+		}
+		this.#bytes += size;
+		if (this.#lifecycle.target.write(chunk)) return;
+		this.#source.pause();
+		this.#waitingDrain = true;
+		this.#lifecycle.armStall();
+	}
+	/** Fin propre : en-têtes s'ils manquent, puis fin de la requête. */
+	#finishClean() {
+		const lifecycle = this.#lifecycle;
+		if (this.#reason !== null || lifecycle.closed) return;
+		if (!this.#headed && !this.#tryWriteHead(0)) return;
+		if (!this.#head && this.#declared !== -1 && this.#bytes !== this.#declared) {
+			this.#fail(this.#lengthMismatch("moins"), "error");
+			return;
+		}
+		this.#reason = "end";
+		this.#settleLater = true;
+		const closed = lifecycle.close();
+		if (closed === void 0) this.#settle();
+		else closed.then(this.#settleBound, this.#settleBound);
+	}
+	#settleBound = () => this.#settle();
+	/** L'erreur d'un corps qui ne fait pas la longueur annoncée. */
+	#lengthMismatch(direction) {
+		return /* @__PURE__ */ new Error(`Flux : la source rend ${direction} d'octets que Content-Length n'en annonce (${this.#declared})`);
+	}
+	/**
+	* Échec de la source, ou source muette. Avant le premier octet, la réponse
+	* est ROUVERTE et l'erreur confiée au moteur d'erreurs du noyau — même
+	* statut, même page qu'une action ordinaire. Après, le client voit une
+	* coupure, jamais une fin propre.
+	*/
+	#fail(failure, reason) {
+		const lifecycle = this.#lifecycle;
+		if (this.#reason !== null || lifecycle.closed) return;
+		this.#reason = reason;
+		const context = lifecycle.context;
+		if (!this.#headed && !context.response.isHeaderSent()) {
+			this.#settleLater = true;
+			lifecycle.finish();
+			const kernel = context.httpKernel;
+			if (kernel === null) {
+				this.#settle();
+				return;
+			}
+			context.sended = false;
+			this.#renderError(kernel, failure);
+			return;
+		}
+		if (reason === "error") context.log(failure, "ERROR", "STREAM");
+		context.response.statusCode = "code" in failure && typeof failure.code === "number" && failure.code >= 400 && failure.code <= 599 ? failure.code : 500;
+		const target = lifecycle.target;
+		if (target instanceof http.ServerResponse) target.destroy();
+		else target.destroy(failure);
+		lifecycle.finish();
+	}
+	/**
+	* Rend l'erreur d'avant le premier octet par le moteur d'erreurs du noyau,
+	* puis règle la promesse — qui ne rejette jamais, même si ce rendu échoue.
+	*/
+	async #renderError(kernel, failure) {
+		const context = this.#lifecycle.context;
+		try {
+			await kernel.onError(failure, context);
+		} catch (e) {
+			context.log(e, "ERROR", "STREAM");
+		}
+		this.#settle();
+	}
+	/**
+	* Un tour du chien de garde, tous les quarts de `idleTimeout`. La source a
+	* avancé depuis le tour précédent : on note l'heure. Sinon, et depuis au
+	* moins `idleTimeout` : la source est muette.
+	*/
+	#checkIdle() {
+		if (this.#reason !== null || this.#lifecycle.closed) return;
+		const now = Date.now();
+		if (this.#bytes !== this.#seenBytes || this.#waitingDrain) {
+			this.#seenBytes = this.#bytes;
+			this.#seenAt = now;
+			return;
+		}
+		const idle = this.#settings.idleTimeout;
+		if (now - this.#seenAt < idle) return;
+		this.#fail(new HttpError(`Flux : source muette depuis ${idle} ms`, 504), "timeout");
+	}
+	/** Nettoyage, appelé UNE fois par le cycle de vie, quelle qu'en soit la cause. */
+	#release() {
+		const lifecycle = this.#lifecycle;
+		const reason = this.#reason ?? (lifecycle.cause === "stall" ? "stall" : lifecycle.cause === "server" ? "end" : "client");
+		this.#reason = reason;
+		const source = this.#source;
+		source.removeListener("data", this.#onData);
+		source.removeListener("end", this.#onEnd);
+		source.removeListener("close", this.#onSourceClose);
+		source.on("error", IGNORE_LATE_ERROR);
+		source.removeListener("error", this.#onSourceError);
+		source.destroy();
+		lifecycle.target.removeListener("drain", this.#onDrain);
+		if (this.#watchdog !== null) {
+			clearInterval(this.#watchdog);
+			this.#watchdog = null;
+		}
+		const context = lifecycle.context;
+		if (reason !== "end") context._abortIfPending(`Flux terminé : ${reason}`);
+		context.log(`Flux d'octets terminé (${reason}, ${this.#bytes} octets)`, "DEBUG", "STREAM");
+		const onClose = this.#settings.onClose;
+		if (onClose !== null) try {
+			onClose(reason);
+		} catch (e) {
+			context.log(e, "ERROR", "STREAM");
+		}
+		if (!this.#settleLater) this.#settle();
+	}
+	#settle() {
+		this.#resolve({
+			reason: this.#reason ?? "end",
+			bytes: this.#bytes
+		});
+	}
+};
+/**
+* Un flux web (`fetch().body`) lu comme un flux Node.
+*
+* Pas `Readable.fromWeb` : il attend le `ReadableStream` de `node:stream/web`,
+* que le type global d'une application compilée avec la lib DOM ne satisfait
+* pas. La lecture tient en un lecteur, et la destruction ANNULE le flux web —
+* c'est elle qui ferme la connexion amont d'un `fetch`.
+*/
+function fromWebStream(stream) {
+	const reader = stream.getReader();
+	const onRead = (result) => {
+		if (result.done) readable.push(null);
+		else readable.push(result.value);
+	};
+	const onFail = (error) => {
+		readable.destroy(error instanceof Error ? error : new Error(String(error)));
+	};
+	const readable = new Readable({
+		read() {
+			reader.read().then(onRead, onFail);
+		},
+		destroy(failure, callback) {
+			reader.cancel(failure ?? void 0).catch(IGNORE_LATE_ERROR);
+			callback(failure);
+		}
+	});
+	return readable;
+}
+/** Refuse une option de flux d'octets hors bornes. */
+function checkOptions(options) {
+	const { status, idleTimeout } = options;
+	if (status !== void 0 && (!Number.isInteger(status) || status < 200 || status > 599)) throw new RangeError("Flux : status entier entre 200 et 599 attendu");
+	if (idleTimeout !== void 0 && (!Number.isInteger(idleTimeout) || idleTimeout < 0 || idleTimeout > 2147483647)) throw new RangeError(`Flux : idleTimeout entier entre 0 et ${MAX_TIMER_MS} ms attendu`);
+	checkStreamTimer("Flux", "stallTimeout", options.stallTimeout);
+	checkStreamTimer("Flux", "maxDuration", options.maxDuration);
+}
+/**
+* Répond par un flux d'octets sur la réponse d'un contexte HTTP.
+*
+* Prend la réponse à l'appel (le noyau ne peut plus répondre par-dessus) ;
+* les en-têtes partent au premier morceau de la source. La promesse se règle à
+* la fin du flux, quelle qu'en soit la raison, et ne rejette JAMAIS.
+*
+* @param context - le contexte de la requête, pas encore répondu.
+* @param source - flux Node, ou flux web (`fetch().body`) ; jamais en mode objet.
+* @param options - statut, en-têtes, délais, écouteur de fin.
+* @returns la raison de la fin et le nombre d'octets envoyés.
+* @throws TypeError quand la source est en mode objet.
+* @throws RangeError quand une option est hors bornes.
+* @throws HttpError 500 quand la réponse est déjà partie ; 429 quand l'IP a
+*   déjà tous ses flux et sockets (`wsMaxConnectionsPerIp`).
+*
+* La source appartient au flux dès l'appel : quand l'appel lève, elle est
+* DÉTRUITE (un flux web est annulé) avant que l'erreur ne remonte.
+*/
+function openByteStream(context, source, options = {}) {
+	const readable = source instanceof Readable ? source : fromWebStream(source);
+	let opened;
+	let settings;
+	try {
+		checkOptions(options);
+		if (readable.readableObjectMode) throw new TypeError("Flux : une source en mode objet ne porte pas d'octets — pour Readable.from(), passer { objectMode: false }.");
+		settings = settingsOf(context, options);
+		opened = openStreamLifecycle(context, {
+			label: "Flux",
+			stallTimeout: options.stallTimeout ?? SSE_STALL_TIMEOUT_MS,
+			maxDuration: options.maxDuration ?? false,
+			endsAtShutdown: settings.live
+		});
+	} catch (error) {
+		readable.on("error", IGNORE_LATE_ERROR);
+		readable.destroy();
+		throw error;
+	}
+	const start = (lifecycle) => {
+		const stream = new ByteStream(lifecycle, readable, settings);
+		stream.start();
+		return stream.done;
+	};
+	if (opened instanceof Promise) {
+		readable.on("error", IGNORE_LATE_ERROR);
+		return opened.then(start);
+	}
+	return start(opened);
+}
+/** Les réglages du flux, défauts résolus sur le contexte. */
+function settingsOf(context, options) {
+	const timeout = context.response.timeout;
+	return {
+		status: options.status ?? 200,
+		headers: options.headers ?? null,
+		live: options.live ?? true,
+		idleTimeout: options.idleTimeout ?? (typeof timeout === "number" ? timeout : 3e4),
+		onClose: options.onClose === void 0 ? null : AsyncResource.bind(options.onClose)
+	};
+}
+export { openByteStream };

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

@@ -1,16 +1,19 @@
 import HttpError from "../../errors/httpError.js";
-import { responseEnded } from "../responseEnded.js";
-import { alpnProtocolOf } from "../transport.js";
-import Cookie from "../../cookies/cookie.js";
-import Context from "../Context.js";
 import { sanitizeRequestId } from "../requestId.js";
+import Context from "../Context.js";
 import HttpRequest from "./Request.js";
 import HttpResponse from "./Response.js";
 import Http2Request from "../http2/Request.js";
 import Http2Response from "../http2/Response.js";
+import Cookie from "../../cookies/cookie.js";
 import { describeSessionStoreFailure } from "../../session/sessionStoreFailure.js";
+import { responseEnded } from "../responseEnded.js";
+import { alpnProtocolOf } from "../transport.js";
 import { openSseStream } from "./SseStream.js";
+import { openByteStream } from "./ByteStream.js";
+import { webResponseParts } from "./webResponse.js";
 import { finallyMaybe, isPromise, thenMaybe, typeOf } from "nodefony";
+import net from "node:net";
 import url, { URL } from "node:url";
 // nodefony/src/context/http/HttpContext.ts
 /**
@@ -29,25 +32,35 @@ function switchUrlScheme(from, scheme, port) {
 	return target.href;
 }
 const socketActiveContext = /* @__PURE__ */ new WeakMap();
-const socketTimeoutArmed = /* @__PURE__ */ new WeakSet();
 /**
-* Gestionnaire `timeout` PERMANENT d'une socket h1, fabriqué hors de toute
-* méthode : une fermeture créée dans `HttpContext.setTimeout()` partageait
-* l'environnement d'une autre qui lit `this`, et retenait ainsi le contexte de
-* la PREMIÈRE requête de la connexion tant que celle-ci vivait (#561).
+* Route le délai d'inactivité d'une socket HTTP/1.1 vers la requête qu'elle
+* porte : 503 si une requête est en cours, fermeture si la connexion
+* persistante est inactive. Écouteur `timeout` du SERVEUR — un seul pour
+* toutes ses connexions —, que Node appelle avec la socket en argument
+* (`socketOnTimeout` → `server.emit("timeout", socket)`).
+*
+* Pourquoi au serveur et pas sur la socket : Node y pose déjà son propre
+* écouteur `timeout`, et un second faisait créer à `EventEmitter` un tableau
+* d'écouteurs par CONNEXION. Ce site d'allocation, partagé avec tout le
+* processus et toujours survivant (une connexion vit longtemps), finissait
+* par être basculé dans le vieux tas par V8 (pretenuring) — dans un démarrage
+* sur trois environ, mesuré sous charge. Le graphe de chaque requête y
+* restait alors accroché jusqu'à la collecte complète suivante : +45 % de CPU
+* par requête, 14 à 19 collectes complètes au lieu de 3. Un écouteur par
+* serveur supprime aussi une fermeture et une entrée de registre par connexion.
 *
-* @param socket - la socket h1 dont on route le délai d'inactivité
-* @returns l'écouteur à attacher une fois par socket
+* @param socket - la socket dont le délai a expiré ; une session HTTP/2 (même
+*   événement sur un serveur `allowHTTP1`) est fermée par l'écouteur que pose
+*   `setHttp2SessionTimeout` (`src/servers/http2Limits.ts`)
 */
-function idleSocketTimeoutHandler(socket) {
-	return () => {
-		const ctx = socketActiveContext.get(socket);
-		if (ctx !== void 0 && !ctx.cleaned && !ctx.response.response?.writableEnded) {
-			ctx._onTimeout();
-			return;
-		}
-		socket.destroy();
-	};
+function routeSocketTimeout(socket) {
+	if (!(socket instanceof net.Socket)) return;
+	const ctx = socketActiveContext.get(socket);
+	if (ctx !== void 0 && !ctx.cleaned && !ctx.response.response?.writableEnded) {
+		ctx._onTimeout();
+		return;
+	}
+	socket.destroy();
 }
 const PERF_PROBE_SUB = process.env.NF_PERF_PROBE === "1";
 var HttpContext = class extends Context {
@@ -61,6 +74,15 @@ var HttpContext = class extends Context {
 	* son montage. `null` = servie par l'application (cas de toute requête).
 	*/
 	relayAccessLog = null;
+	/**
+	* L'appel RPC servi sur cette requête (gRPC, gRPC-Web, Connect), `null`
+	* hors appel RPC (ADR-0026 D10) : un champ, aucune allocation. Posé par le
+	* point d'entrée gRPC ; à l'échéance du délai de réponse, {@link _onTimeout}
+	* le termine au lieu d'écrire un 503.
+	*
+	* @experimental Surface gRPC, ADR-0026 D11.
+	*/
+	rpc = null;
 	request;
 	response;
 	uploadService;
@@ -131,11 +153,34 @@ var HttpContext = class extends Context {
 	_onTimeout() {
 		if (this.listenerCount("onTimeout")) this.fire("onTimeout", this);
 		this._abortIfPending("Request timeout");
+		if (this.rpc !== null) {
+			this.rpc.expire();
+			return;
+		}
 		this.httpKernel?.warnUnsentResponse(this);
-		let error;
-		if (this.response.stream) error = new HttpError("Gateway Timeout", 504, this);
-		else error = new HttpError("Request Timeout", 408, this);
-		this.httpKernel?.onError(error, this);
+		this.httpKernel?.onError(new HttpError("Service Unavailable", 503, this), this);
+	}
+	/**
+	* Ré-arme le délai de réponse de la requête à la valeur propre de sa route
+	* (`responseTimeout` d'une option de route), une fois celle-ci résolue.
+	*
+	* Même mécanisme que {@link setTimeout} — délai d'inactivité de la socket
+	* (HTTP/1.1) ou du flux (HTTP/2) —, sans second écouteur : sous HTTP/2,
+	* `setTimeout(ms)` sans rappel remplace le minuteur et garde celui posé par
+	* {@link setTimeout}. `0` désactive le délai pour la requête.
+	*
+	* @param ms - délai de la route, en millisecondes.
+	*/
+	rearmTimeout(ms) {
+		this.response.setTimeout(ms);
+		const res = this.response.response;
+		if (!res) return;
+		if (this.response.stream) {
+			res.setTimeout(ms);
+			return;
+		}
+		const socket = this.activeSocket;
+		if (socket && socket.timeout !== ms) socket.setTimeout(ms);
 	}
 	setScheme() {
 		const req = this.request;
@@ -162,6 +207,8 @@ var HttpContext = class extends Context {
 		if (kernel && (kernel.debug || kernel.listenerCount("onRequest") > 0)) kernel.fire("onRequest", this);
 		if (!this.resolver && this.router) this.resolver = this.router.resolve(this);
 		if (this.resolver?.resolve) {
+			const routeTimeout = this.resolver.route?.responseTimeout;
+			if (routeTimeout !== void 0 && routeTimeout !== null) this.rearmTimeout(routeTimeout);
 			this.setMetaData();
 			return this.resolver.callController();
 		}
@@ -182,27 +229,38 @@ var HttpContext = class extends Context {
 		this.activeSocket = socket;
 		const ms = this.response.timeout;
 		if (socket.timeout !== ms) socket.setTimeout(ms);
-		if (!socketTimeoutArmed.has(socket)) {
-			socketTimeoutArmed.add(socket);
-			socket.on("timeout", idleSocketTimeoutHandler(socket));
-		}
 	}
 	/**
 	* Ligne d'accès — pour une requête RELAYÉE, avec le statut que l'amont a
 	* réellement rendu (le relais écrit la réponse brute, pas celle du
 	* contexte) ; un montage `accessLog: "errors"` ne l'écrit qu'en échec.
 	*
+	* Le statut natif n'est recopié que si la réponse a été TERMINÉE
+	* ({@link responseEnded}) : sinon il n'a jamais atteint le client (200 par
+	* défaut de Node), et le statut du contexte — 499 d'un client parti — dit
+	* vrai. Règle unique pour toute réponse écrite par un tiers (#695, critère
+	* 38).
+	*
 	* @param httpError - l'erreur de la requête, s'il y en a une
 	*/
 	logRequest(httpError) {
+		if (this.rpc !== null) this.adoptNativeStatus();
 		if (this.relayAccessLog !== null) {
-			const raw = this.response.response;
-			if (raw !== null) this.response.statusCode = raw.statusCode;
+			this.adoptNativeStatus();
 			if (this.relayAccessLog === "errors" && this.response.statusCode < 400 && !httpError && !this.error) return;
 		}
 		return super.logRequest(httpError);
 	}
 	/**
+	* Reprend le statut de la réponse native, écrite par un tiers (relais,
+	* adaptateur RPC) — si la réponse est TERMINÉE seulement : sinon ce statut
+	* n'a jamais atteint le client, et celui du contexte (499) dit vrai.
+	*/
+	adoptNativeStatus() {
+		const raw = this.response.response;
+		if (raw !== null && responseEnded(raw)) this.response.statusCode = raw.statusCode;
+	}
+	/**
 	* Nettoie le contexte, et le DÉTACHE de sa socket h1 : la connexion
 	* persistante survit à la requête, et l'entrée de `socketActiveContext`
 	* retiendrait sinon tout le contexte jusqu'à sa fermeture. Seule l'entrée qui
@@ -346,6 +404,7 @@ var HttpContext = class extends Context {
 	*
 	* La requête ne se termine qu'à `close()` du flux, ou au départ du client.
 	*
+	* @typeParam Events - carte des événements du flux (cf `SseStream`).
 	* @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 quand la réponse est déjà partie.
@@ -353,6 +412,54 @@ var HttpContext = class extends Context {
 	openSse(options) {
 		return openSseStream(this, 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.
+	*
+	* La réponse est prise à l'appel, ses en-têtes partent au premier morceau de
+	* la source. La source est DÉTRUITE à la fin, quelle qu'en soit la raison
+	* (jamais `unpipe`, qui laisse un producteur bloqué en écriture). Pour des
+	* événements texte lus par `EventSource`, voir {@link HttpContext.openSse}.
+	* Dans un middleware, la requête est répondue : ne pas appeler la suite.
+	*
+	* @param source - flux Node, ou flux web (`fetch().body`) ; jamais en mode objet.
+	* @param options - statut, en-têtes, délais, écouteur de fin.
+	* @returns la raison de la fin et le nombre d'octets ; ne rejette jamais.
+	* @throws HttpError 500 quand la réponse est déjà partie, 429 au-delà du
+	*   plafond de connexions par IP ; TypeError pour une source en mode objet.
+	*   Quand l'appel lève, la source est DÉTRUITE (un flux web est annulé).
+	*/
+	openStream(source, options) {
+		return openByteStream(this, source, options);
+	}
+	/**
+	* Répond par une `Response` Web standard — celle que rend `fetch()`, ou une
+	* réponse construite (`new Response(…)`, `Response.json(…)`) : son statut,
+	* ses en-têtes, et son corps EN FLUX, jamais lu d'avance.
+	*
+	* C'est ce que fait le framework quand une action renvoie une `Response`.
+	* Une réponse relayée (issue de `fetch`) perd `content-encoding`,
+	* `content-length` et `set-cookie` de l'amont ; une réponse construite garde
+	* les siens. Les en-têtes de connexion ne partent jamais. Le reste — arrêt au
+	* départ du client, contre-pression, délais, HEAD sans lire le corps — est
+	* celui de {@link HttpContext.openStream}.
+	*
+	* @param response - une `Response` dont le corps n'a pas été consommé.
+	* @param options - délais et écouteur de fin ; statut et en-têtes viennent de la réponse.
+	* @returns la raison de la fin et le nombre d'octets ; ne rejette jamais.
+	* @throws HttpError 502 pour `Response.error()` (statut 0, aucune réponse) ;
+	*   les cas de {@link HttpContext.openStream} sinon.
+	*/
+	openWebResponse(response, options) {
+		if (response.type === "error") throw new HttpError("Réponse Web en erreur : Response.error() ne porte aucune réponse", 502, this);
+		const parts = webResponseParts(response);
+		return openByteStream(this, parts.source, {
+			...options,
+			status: parts.status,
+			headers: parts.headers
+		});
+	}
 	flush(chunk, encoding) {
 		return this.response.flush(chunk, encoding);
 	}
@@ -414,7 +521,7 @@ var HttpContext = class extends Context {
 		return this.request.getMethod();
 	}
 	setContentType(type, encoding) {
-		return this.response.setContentType(type, encoding);
+		this.response.setContentType(type, encoding);
 	}
 	resolveIsHtml() {
 		return this.request.acceptHtml;
@@ -437,4 +544,4 @@ var HttpContext = class extends Context {
 		this.response.setContentType("html", encoding);
 	}
 };
-export { HttpContext as default, switchUrlScheme };
+export { HttpContext as default, routeSocketTimeout, switchUrlScheme };