@nodefony/http 10.0.0-alpha.1

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

@@ -0,0 +1,97 @@
+import HttpResponse from "../http/Response.js";
+import { extend } from "nodefony";
+import http from "node:http";
+import http2 from "node:http2";
+//#region nodefony/src/context/http2/Response.ts
+const HTTP2_HEADER_STATUS = http2.constants.HTTP2_HEADER_STATUS;
+var Http2Response = class extends HttpResponse {
+	statusCode = 200;
+	stream = null;
+	streamId;
+	constructor(response, context) {
+		super(response, context);
+		if (response) {
+			this.stream = response.stream;
+			this.streamId = this.stream.id;
+		}
+		if (this.stream && this.stream.pushAllowed) this.context.pushAllowed = true;
+	}
+	isHeaderSent() {
+		if (this.stream) return this.stream.headersSent;
+		return super.isHeaderSent();
+	}
+	writeHead(statusCode, headers) {
+		if (this.stream) {
+			if (statusCode) this.setStatusCode(statusCode);
+			if (this.stream.destroyed || this.stream.closed) {
+				this.log("HTTP/2 stream destroyed before writeHead — skip", "DEBUG");
+				return;
+			}
+			if (!this.stream.headersSent) {
+				if (this.statusCode) {
+					if (typeof this.statusCode === "string") this.statusCode = parseInt(this.statusCode, 10);
+					if (this.statusCode > 599) this.statusCode = 500;
+				}
+				this.statusMessage = this.getStatusMessage();
+				this.setLength();
+				this.ensureContentTypeHeader();
+				this.headers = extend(true, { "X-Status-Message": this.statusMessage }, this.getHeaders(), headers);
+				this.headers[HTTP2_HEADER_STATUS] = this.statusCode;
+				const requestId = this.context.requestId;
+				if (requestId) this.headers["x-request-id"] = requestId;
+				const traceparent = this.context.traceparent;
+				if (traceparent) this.headers["traceparent"] = traceparent;
+				this.stream.respond(this.headers, { endStream: false });
+			} else this.log("Headers already sent !!", "WARNING");
+		} else return super.writeHead(statusCode, headers);
+	}
+	async send(chunk, encoding, _flush = false) {
+		if (this.context.isRedirect) {
+			if (this.stream && !this.stream.headersSent) this.writeHead();
+			await this.end();
+			return this;
+		}
+		const stream = this.stream;
+		if (!stream) return await super.send(chunk, encoding);
+		if (stream.destroyed || !stream.writable) {
+			this.log("HTTP/2 stream not writable before send — skip", "DEBUG");
+			return this;
+		}
+		if (chunk) this.setBody(chunk);
+		if (this.body === null) this.body = Buffer.alloc(0);
+		return new Promise((resolve, reject) => {
+			stream.write(this.body, encoding || this.encoding, (error) => {
+				if (error) return reject(error);
+				return resolve(this);
+			});
+		});
+	}
+	end(chunk, encoding) {
+		return new Promise((resolve, reject) => {
+			try {
+				if (this.stream) {
+					if (this.stream.destroyed || this.stream.closed) return resolve(this.stream);
+					return resolve(this.stream.end(chunk, encoding || this.encoding));
+				}
+				return resolve(super.end(chunk, encoding));
+			} catch (e) {
+				return reject(e);
+			}
+		});
+	}
+	getStatusMessage(code) {
+		if (code) {
+			if (this.response) return http.STATUS_CODES[code] || this.statusMessage;
+		}
+		if (this.response) return this.statusMessage || http.STATUS_CODES[this.statusCode];
+		return this.statusMessage || http.STATUS_CODES[this.statusCode];
+	}
+	getStatus() {
+		return {
+			code: this.getStatusCode(),
+			message: ""
+		};
+	}
+};
+//#endregion
+export { Http2Response as default };

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

@@ -0,0 +1,47 @@
+//#region nodefony/src/context/metaData.ts
+/**
+* Assemble l'enveloppe `metaData` d'une requête EN PLACE (builder monomorphe) :
+* met à jour les champs de `target.nodefony` dans un ordre fixe → V8 garde une
+* hidden class stable et inline les écritures. Remplace l'ancien
+* `extend(true, …)` qui deep-clonait/dispatchait à chaque réponse JSON et chaque
+* frame WS — inutile ici puisque `target` est l'objet metaData per-requête
+* (jamais partagé).
+*
+* `route` est un **snapshot per-requête** `{ name, path, variablesMap }` : on ne
+* diffuse jamais l'instance `Route` partagée (statique), dont les variables
+* matchées seraient écrasées par toute requête/connexion concurrente (bleed).
+*
+* `override` (ex. frame WS `{ nodefony: { websocket } }`) est fusionné *shallow*
+* dans l'enveloppe : le seul cas réel est l'ajout d'un sous-objet `nodefony`
+* peu profond — pas besoin du deep-merge récursif générique. Toute clé top-level
+* hors `nodefony` est préservée telle quelle.
+*
+* @param target - objet metaData per-requête à muter (et retourner)
+* @param src - source structurelle (le `Context` réel, ou un faux en test)
+* @param override - overrides optionnels de l'appelant
+* @returns le même `target`, muté
+*/
+function buildMetaData(target, src, override) {
+	const nf = target.nodefony;
+	nf.name = src.kernel?.projectName;
+	nf.version = src.kernel?.version;
+	nf.url = src.request?.href ?? src.request?.url;
+	nf.environment = src.kernel?.environment;
+	nf.debug = src.kernel?.debug;
+	nf.scheme = src.scheme;
+	nf.requestId = src.requestId;
+	const r = src.resolver;
+	nf.route = r && r.route ? {
+		name: r.route.name,
+		path: r.route.path,
+		variablesMap: r.getMatchedParams()
+	} : void 0;
+	if (override) {
+		const ovr = override.nodefony;
+		if (ovr) Object.assign(nf, ovr);
+		for (const k in override) if (k !== "nodefony") target[k] = override[k];
+	}
+	return target;
+}
+//#endregion
+export { buildMetaData };

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

@@ -0,0 +1,41 @@
+//#region nodefony/src/context/requestId.ts
+/**
+* Validation de l'identifiant de corrélation `X-Request-Id` fourni par le
+* client, avant qu'il ne soit adopté comme `Context.requestId`.
+*
+* Le `requestId` finit (1) réfléchi dans la réponse (`X-Request-Id`),
+* (2) écrit dans les logs (`ID : …`), (3) propagé en ALS à tout le pipeline.
+* Une valeur cliente non assainie ouvre donc : log-injection (CR/LF dans les
+* logs), forging de corrélation, et throw `setHeader` natif (→ 500/DoS) sur
+* caractère de contrôle ou non-ASCII. Cf RFC 9110 §5.5 (field values) + Zero
+* Trust (mémoire `feedback_security_rfc_rigor`).
+*/
+/**
+* Longueur maximale acceptée pour un `X-Request-Id` client. Borne anti-abus
+* (log flooding / header oversize). 128 couvre largement un UUID (36), un
+* nanoid, ou un `traceparent` (55).
+*/
+const MAX_REQUEST_ID_LENGTH = 128;
+/**
+* Caractères sûrs : ASCII alphanumérique + `.`, `_`, `-`. Exclut tout caractère
+* de contrôle (CR/LF → response splitting / log injection), espace, et
+* non-ASCII (→ throw `setHeader` Node = DoS). Ancré + quantifieur borné : pas
+* de backtracking catastrophique (ReDoS).
+*/
+const SAFE_REQUEST_ID = /^[A-Za-z0-9._-]{1,128}$/u;
+/**
+* Valide un `X-Request-Id` entrant. Retourne la valeur si elle est sûre, sinon
+* `null` (l'appelant conserve alors l'UUID généré côté serveur).
+*
+* On REJETTE (plutôt que tronquer/nettoyer) une valeur invalide : nettoyer
+* donnerait au client un faux contrôle sur l'identifiant et masquerait l'abus.
+*
+* @param raw - valeur brute du header `x-request-id` (ou `undefined`/`null`).
+* @returns la valeur si sûre, sinon `null`.
+*/
+function sanitizeRequestId(raw) {
+	if (!raw || raw.length > 128) return null;
+	return SAFE_REQUEST_ID.test(raw) ? raw : null;
+}
+//#endregion
+export { MAX_REQUEST_ID_LENGTH, sanitizeRequestId };

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

@@ -0,0 +1,167 @@
+import { BlockList, isIPv4, isIPv6 } from "node:net";
+//#region nodefony/src/context/trustProxy.ts
+const PRESETS = {
+	loopback: [[
+		"127.0.0.0",
+		8,
+		"ipv4"
+	], [
+		"::1",
+		128,
+		"ipv6"
+	]],
+	linklocal: [[
+		"169.254.0.0",
+		16,
+		"ipv4"
+	], [
+		"fe80::",
+		10,
+		"ipv6"
+	]],
+	uniquelocal: [
+		[
+			"10.0.0.0",
+			8,
+			"ipv4"
+		],
+		[
+			"172.16.0.0",
+			12,
+			"ipv4"
+		],
+		[
+			"192.168.0.0",
+			16,
+			"ipv4"
+		],
+		[
+			"fc00::",
+			7,
+			"ipv6"
+		]
+	]
+};
+/** Normalise une adresse IPv4-mapped IPv6 (`::ffff:127.0.0.1`) en IPv4. */
+const normalize = (addr) => addr.startsWith("::ffff:") && isIPv4(addr.slice(7)) ? addr.slice(7) : addr;
+const TRUST_ALL = { isTrusted: () => true };
+const TRUST_NONE = { isTrusted: () => false };
+/**
+* Ajoute une entrée (IP, CIDR ou preset) à la `BlockList`.
+*
+* @throws {Error} si l'entrée n'est ni une IP, ni un CIDR, ni un preset connu.
+*/
+function addEntry(list, raw) {
+	const entry = raw.trim();
+	if (!entry) return;
+	const preset = PRESETS[entry.toLowerCase()];
+	if (preset) {
+		for (const [net, prefix, family] of preset) list.addSubnet(net, prefix, family);
+		return;
+	}
+	const slash = entry.indexOf("/");
+	if (slash !== -1) {
+		const net = entry.slice(0, slash);
+		const prefix = Number(entry.slice(slash + 1));
+		const family = isIPv6(net) ? "ipv6" : "ipv4";
+		list.addSubnet(net, prefix, family);
+		return;
+	}
+	if (isIPv4(entry)) {
+		list.addAddress(entry, "ipv4");
+		return;
+	}
+	if (isIPv6(entry)) {
+		list.addAddress(entry, "ipv6");
+		return;
+	}
+	throw new Error(`trustProxy: invalid IP/CIDR/preset "${raw}"`);
+}
+/**
+* Compile une config `trustProxy` en un {@link TrustProxyChecker} (une fois, au
+* boot — pas par requête). Les entrées invalides lèvent à la compilation (fail
+* fast) plutôt que silencieusement par requête.
+*
+* @param config - voir {@link TrustProxyConfig}. `undefined` → aucune confiance.
+* @returns un checker `isTrusted(remoteAddress)`.
+*/
+function buildTrustProxy(config) {
+	if (config === true) return TRUST_ALL;
+	if (!config) return TRUST_NONE;
+	const entries = Array.isArray(config) ? config : [config];
+	const list = new BlockList();
+	for (const entry of entries) addEntry(list, entry);
+	return { isTrusted(remoteAddress) {
+		if (!remoteAddress) return false;
+		const addr = normalize(remoteAddress);
+		const family = isIPv6(addr) ? "ipv6" : isIPv4(addr) ? "ipv4" : null;
+		return family ? list.check(addr, family) : false;
+	} };
+}
+/**
+* Cœur de la résolution **from-right** (OWASP) partagé par `X-Forwarded-For`
+* (de-facto) et le paramètre `for` du header `Forwarded` (RFC 7239 §5.2).
+*
+* `chain` = liste des maillons forwarded NORMALISÉS (IP nues, gauche→droite :
+* `[client, proxy1, proxy2]`), telle qu'écrite par les proxies par **append à
+* droite**. La partie gauche est forgeable par le client (cf {@link extractClientIp}).
+* La résolution part de la **connexion réelle** (le socket, non forgeable) et
+* remonte de DROITE à GAUCHE : tant que le maillon courant est un proxy de
+* confiance, on passe au précédent ; le **premier maillon non fiable** est l'IP
+* cliente réelle.
+*
+* Un maillon `null` (identifiant obfusqué `_secret`, `unknown`, ou node illisible
+* — RFC 7239 §6.3/§8.3) est une **barrière non franchissable** : on ne peut pas
+* en vérifier la confiance → on s'arrête et on retourne le dernier maillon de
+* confiance connu (une vraie IP de l'infra), jamais `null` ni la valeur obfusquée.
+*
+* @param chain - maillons forwarded normalisés (IP ou `null` si obfusqué).
+* @param socketAddress - `socket.remoteAddress` (connexion TCP réelle, fiable).
+* @param checker - politique de confiance ({@link buildTrustProxy}).
+* @returns l'IP cliente réelle résolue (toujours une valeur fiable).
+*/
+function resolveFromRight(chain, socketAddress, checker) {
+	let candidate = socketAddress;
+	for (let i = chain.length - 1; i >= 0; i -= 1) {
+		if (!checker.isTrusted(candidate)) return candidate;
+		const next = chain[i];
+		if (next === null) return candidate;
+		candidate = next;
+	}
+	return candidate;
+}
+/**
+* Résout l'adresse IP cliente RÉELLE à partir de la connexion socket et de la
+* chaîne `X-Forwarded-For`, en dépouillant les proxies de confiance **de droite
+* à gauche** (algorithme OWASP).
+*
+* `X-Forwarded-For` (de-facto) est construit par **append de gauche à droite** :
+* `XFF: client, proxy1, proxy2`. Chaque proxy ajoute À DROITE l'adresse qu'il a
+* vue. La partie **gauche** est donc entièrement **forgeable** par le client
+* (il peut envoyer `X-Forwarded-For: 1.2.3.4` ; le 1ᵉʳ proxy ne fait qu'append
+* l'IP réelle après). Lire `XFF[0]` revient à lire la valeur du client →
+* **IP spoofing** (contournement de ban / rate-limit / allow-list / audit).
+*
+* Hot path préservé : sans `X-Forwarded-For` (cas direct usuel) la fonction
+* retourne immédiatement le socket — 0 allocation (pas de split). Pour le header
+* standard `Forwarded` (RFC 7239), voir `resolveForwarded` (module `forwarded`).
+*
+* @param xff - valeur brute de l'en-tête `X-Forwarded-For` (string, ou string[]
+*   si l'en-tête est répété), ou `undefined`.
+* @param socketAddress - `socket.remoteAddress` (la connexion TCP réelle).
+* @param checker - politique de confiance ({@link buildTrustProxy}).
+* @returns l'IP cliente réelle, ou `null` si aucune connexion socket fiable.
+*/
+function extractClientIp(xff, socketAddress, checker) {
+	if (!socketAddress) return null;
+	if (!xff) return socketAddress;
+	const s = Array.isArray(xff) ? xff.join(",") : xff;
+	if (s.indexOf(",") === -1) {
+		const ip = s.trim();
+		if (!ip) return socketAddress;
+		return checker.isTrusted(socketAddress) ? ip : socketAddress;
+	}
+	return resolveFromRight(s.split(",").map((part) => part.trim()).filter(Boolean), socketAddress, checker);
+}
+//#endregion
+export { buildTrustProxy, extractClientIp, resolveFromRight };

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

@@ -0,0 +1,181 @@
+import Cookie from "../../cookies/cookie.js";
+import { decideSend, readBackpressureOptions } from "./wsBackpressure.js";
+import Ws from "ws";
+import http from "node:http";
+//#region nodefony/src/context/websocket/Response.ts
+/**
+* Codes d'erreur d'écriture « le client est PARTI » : reload de page, onglet
+* fermé, HMR — la socket TCP est morte côté client pendant qu'une frame était
+* en vol. Race réseau INÉVITABLE (la garde `readyState === OPEN` ne la couvre
+* pas : l'état bascule après l'échec d'écriture) — c'est du réseau normal, pas
+* une erreur serveur.
+*/
+const PEER_GONE_CODES = /* @__PURE__ */ new Set([
+	"EPIPE",
+	"ECONNRESET",
+	"ECONNABORTED",
+	"ERR_STREAM_DESTROYED",
+	"ERR_STREAM_WRITE_AFTER_END"
+]);
+/**
+* `true` si l'erreur d'écriture signifie seulement que le client s'est
+* déconnecté (frame perdue, connexion en cours de fermeture) — à logger DEBUG,
+* jamais ERROR + stack (vécu : un simple reload de page pendant un ping WS
+* remplissait le journal d'« Error: write EPIPE »).
+*/
+function isPeerGoneError(error) {
+	const code = error?.code;
+	return typeof code === "string" && PEER_GONE_CODES.has(code);
+}
+const WS_CLOSE_DESCRIPTIONS = {
+	1e3: "Normal Closure",
+	1001: "Going Away",
+	1002: "Protocol Error",
+	1003: "Unsupported Data",
+	1005: "No Status Received",
+	1006: "Abnormal Closure",
+	1007: "Invalid frame payload data",
+	1008: "Policy Violation",
+	1009: "Message too big",
+	1010: "Missing Extension",
+	1011: "Internal Error",
+	1012: "Service Restart",
+	1013: "Try Again Later",
+	1015: "TLS Handshake"
+};
+var WebsocketResponse = class {
+	context;
+	statusCode = 1e3;
+	body = null;
+	encoding = "utf-8";
+	connection = null;
+	statusMessage = "";
+	webSocketVersion;
+	cookies = {};
+	constructor(connection, context) {
+		this.context = context;
+		this.connection = connection;
+	}
+	log(pci, severity, msgid, msg) {
+		const syslog = this.context?.container?.get("syslog");
+		if (!msgid) msgid = "WEBSOCKET RESPONSE";
+		return syslog?.log(pci, severity, msgid, msg);
+	}
+	setConnection(connection) {
+		this.connection = connection;
+		return connection;
+	}
+	async send(data, encoding) {
+		const payload = data ?? this.body;
+		if (payload == null) throw new Error("no data");
+		return new Promise((resolve, reject) => {
+			if (!this.connection || this.connection.readyState !== Ws.OPEN) return reject(/* @__PURE__ */ new Error("WebSocket not open"));
+			const { max, policy, closeAfterDrops } = readBackpressureOptions(this.context?.server);
+			const decision = decideSend(this.connection, max, policy, closeAfterDrops);
+			if (decision !== "send") {
+				this.logFirstDrop(this.connection, decision, max);
+				return resolve(this);
+			}
+			const sendData = encoding === "binary" && Buffer.isBuffer(payload) ? payload : payload instanceof Buffer ? payload.toString(encoding ?? this.encoding) : payload;
+			this.connection.send(sendData, (error) => {
+				if (error) {
+					if (isPeerGoneError(error)) {
+						this.log(`WS send: client déconnecté pendant l'écriture (${error.code}) — frame perdue`, "DEBUG");
+						return resolve(this);
+					}
+					this.log(error, "ERROR");
+					return reject(error);
+				}
+				return resolve(this);
+			});
+		});
+	}
+	broadcast(data, type) {
+		const payload = data ?? this.body;
+		if (!payload) return;
+		const wss = this.context?.server;
+		if (!wss) return;
+		const sendData = type === "binary" && Buffer.isBuffer(payload) ? payload : payload instanceof Buffer ? payload.toString(this.encoding) : payload;
+		const { max, policy, closeAfterDrops } = readBackpressureOptions(wss);
+		const onWriteError = (error) => {
+			if (error && !isPeerGoneError(error)) this.log(error, "ERROR");
+		};
+		wss.clients.forEach((client) => {
+			if (client.readyState !== Ws.OPEN) return;
+			const decision = decideSend(client, max, policy, closeAfterDrops);
+			if (decision !== "send") {
+				this.logFirstDrop(client, decision, max);
+				return;
+			}
+			client.send(sendData, onWriteError);
+		});
+	}
+	/**
+	* Logge UNE seule fois par connexion (au 1er drop) qu'un client subit la
+	* backpressure — observabilité opérateur sans bruit dans le hot path.
+	*/
+	logFirstDrop(ws, decision, max) {
+		if (ws._nfDrops === 1) this.log(`WS backpressure → ${decision} (bufferedAmount > ${max} o) — client lent à recevoir`, "WARNING");
+	}
+	setBody(ele, encoding) {
+		if (typeof ele === "string") this.body = Buffer.from(ele, encoding ?? this.encoding);
+		else if (ele instanceof ArrayBuffer || ele instanceof SharedArrayBuffer) this.body = Buffer.from(ele);
+		else if ("buffer" in ele && ele.buffer instanceof ArrayBuffer) this.body = Buffer.from(ele.buffer);
+		return this.body;
+	}
+	drop(reasonCode, description) {
+		if (this.connection && this.connection.readyState === Ws.OPEN) return this.connection.close(reasonCode ?? this.statusCode, description);
+		throw new Error("Connection already closed");
+	}
+	close(reasonCode, description) {
+		if (this.connection && this.connection.readyState === Ws.OPEN) return this.connection.close(reasonCode ?? this.statusCode, description ?? "closed");
+		throw new Error("Connection already closed");
+	}
+	getStatus() {
+		return {
+			code: this.getStatusCode(),
+			message: this.getStatusMessage()
+		};
+	}
+	getStatusCode() {
+		return this.statusCode;
+	}
+	getStatusMessage() {
+		return this.statusMessage;
+	}
+	setStatusCode(status, message) {
+		if (typeof status !== "number") {
+			status = parseInt(status, 10);
+			if (isNaN(status)) status = 500;
+		}
+		if (!status) status = 500;
+		this.statusCode = status;
+		if (!message) message = WS_CLOSE_DESCRIPTIONS[this.statusCode] ?? http.STATUS_CODES[this.statusCode];
+		this.statusMessage = message ?? "";
+		return {
+			code: this.statusCode,
+			message: this.statusMessage
+		};
+	}
+	clean() {
+		this.connection = null;
+		this.body = null;
+	}
+	setEncoding(encoding) {
+		return this.encoding = encoding;
+	}
+	setHeader() {
+		return true;
+	}
+	setHeaders() {
+		return true;
+	}
+	addCookie(cookie) {
+		if (cookie instanceof Cookie) this.cookies[cookie.name] = cookie;
+		else throw new Error("Response addCookies not valid cookies");
+	}
+	setCookies() {}
+	setCookie(_cookie) {}
+};
+//#endregion
+export { WebsocketResponse as default, isPeerGoneError };