@nodefony/http 10.0.0-alpha.1

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

@@ -0,0 +1,389 @@
+import { hasForwardingHeaders, resolveForwarded } from "../forwarded.js";
+import Context from "../Context.js";
+import WebsocketResponse from "./Response.js";
+import { sanitizeRequestId } from "../requestId.js";
+import { FrameProfile } from "../../profiler/FrameProfile.js";
+import { formatWsLogContent } from "./wsLogContent.js";
+import { RequestContext, logColor } from "nodefony";
+import Ws from "ws";
+import { AsyncResource } from "node:async_hooks";
+import url, { URL } from "node:url";
+//#region nodefony/src/context/websocket/WebsocketContext.ts
+/**
+* Coerce un code (applicatif / HTTP / WS) en code de fermeture WebSocket VALIDE
+* et conforme RFC 6455 §7.4, en PRÉFÉRANT les codes standard §7.4.1 quand le
+* sens existe :
+*  - code déjà valide émissible (1000-1003, 1007-1011, 3000-4999) → conservé ;
+*  - HTTP 5xx / interne / code absent → **1011** (Internal Error) ;
+*  - HTTP 401 / 403 / 421 → **1008** (Policy Violation) ;
+*  - autre `< 1000` (ex. 404, sans équivalent RFC) → **4004**, plage privée
+*    4000-4999 (§7.4.2, « undefined by this protocol » → convention applicative).
+*
+* Évite d'émettre un code de la plage 0-999 (« not used », rejeté par `ws`) ou
+* un code réservé non émissible (1004/1005/1006/1015).
+*
+* @param code - code source (number, undefined…).
+* @returns un code de fermeture WS valide.
+*/
+function toWsCloseCode(code) {
+	if (typeof code !== "number" || !Number.isInteger(code)) return 1011;
+	if (code === 1e3 || code >= 1001 && code <= 1003 || code >= 1007 && code <= 1011 || code >= 3e3 && code <= 4999) return code;
+	if (code >= 500 && code < 600) return 1011;
+	if (code === 401 || code === 403 || code === 421) return 1008;
+	if (code >= 400 && code < 500) return 4004;
+	return 1011;
+}
+/**
+* Drapeau « logger le CONTENU des messages WS » — résolu **une seule fois** au
+* premier message (kernel présent). `true` hors production : le Suivi de requête
+* (Studio) affiche alors les frames RECEIVE/SEND/BROADCAST. En prod → `false` →
+* le gate court-circuite AVANT toute allocation/concat (0 surcoût hot path).
+*/
+let wsContentLogging = null;
+var WebsocketContext = class extends Context {
+	request;
+	response = null;
+	acceptedProtocol;
+	port;
+	rejected = false;
+	teardownWired = false;
+	connection = null;
+	origin;
+	proxy = null;
+	forwarded = null;
+	wsUrl = null;
+	queryGet = {};
+	queryRequest = {};
+	wsPath = "";
+	#frameSeq = 0;
+	constructor(scope, req, ws, type) {
+		super(scope, type);
+		this.webSocketState = "handshake";
+		this.request = req;
+		this.connection = ws;
+		this.response = new WebsocketResponse(ws, this);
+		this.method = this.getMethod();
+		this.origin = req.headers.origin ?? "";
+		const checker = this.httpKernel?.getTrustProxyChecker();
+		const socketAddress = req.socket?.remoteAddress;
+		if (checker && checker.isTrusted(socketAddress) && hasForwardingHeaders(req.headers)) this.forwarded = resolveForwarded(req.headers, socketAddress, checker);
+		this.remoteAddress = this.getRemoteAddress();
+		this.acceptedProtocol = req.headers["sec-websocket-protocol"];
+		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.queryGet = Object.fromEntries(this.wsUrl.searchParams.entries());
+		this.queryRequest = { ...this.queryGet };
+		this.wsPath = this.wsUrl.pathname + this.wsUrl.search;
+		this.url = url.format(this.wsUrl);
+		this.port = parseInt(this.wsUrl.port, 10) || (type === "websocket-secure" ? 443 : 80);
+		this.request.url = this.wsUrl;
+		this.request.queryGet = this.queryGet;
+		this.request.query = this.queryRequest;
+		this.request.path = this.wsPath;
+		try {
+			this.originUrl = new URL(this.origin);
+		} catch {
+			this.originUrl = new URL(this.url);
+		}
+		this.parseCookies();
+		this.cookieSession = this.getCookieSession(this.getSessionCookieName());
+		this.domain = this.getHostName();
+		this.validDomain = this.isValidDomain();
+		this.rejected = false;
+		const fwd = this.forwarded;
+		if (fwd) {
+			this.proxy = {
+				proxyServer: req.headers["x-forwarded-server"] ?? "unknown",
+				proxyProto: fwd.proto ?? req.headers["x-forwarded-proto"],
+				proxyPort: req.headers["x-forwarded-port"],
+				proxyFor: fwd.forwardedFor ?? req.headers["x-forwarded-for"],
+				proxyHost: fwd.host ?? req.headers["x-forwarded-host"],
+				proxyVia: req.headers.via
+			};
+			this.log(`PROXY WEBSOCKET REQUEST ${fwd.fromStandard ? "Forwarded (RFC 7239)" : "x-forwarded"} VIA : ${this.proxy?.proxyVia}`, "DEBUG");
+		}
+	}
+	log(pci, severity, msgid, msg) {
+		if (!msgid) msgid = "WEBSOCKET CONTEXT";
+		return super.log(pci, severity, msgid, msg);
+	}
+	logRequest(httpError, acceptedProtocol) {
+		try {
+			const logger = this.httpKernel?.getRequestLogger();
+			if (!logger) return;
+			const entry = logger.renderWebsocket(this, httpError ?? null, acceptedProtocol ?? null);
+			const pdu = this.log(entry.text, entry.severity, entry.msgid);
+			if (pdu && pdu.requestId === void 0) pdu.requestId = this.requestId;
+			return pdu;
+		} catch {}
+	}
+	async connect() {
+		if (!this.response || !this.request || !this.connection) throw new Error("Nodefony Websocket Bad request/response/connection");
+		if (this.rejected) throw new Error("Nodefony Websocket rejected");
+		this.response.setConnection(this.connection);
+		this.connection.on("close", AsyncResource.bind(this.onClose.bind(this)));
+		this.connection.on("error", AsyncResource.bind(this.onConnectionError.bind(this)));
+		this.teardownWired = true;
+		await this.fireAsync("onConnect", this, this.connection);
+		this.requestEnded = true;
+		this.connection.on("message", AsyncResource.bind(this.handleMessage.bind(this)));
+		this.logRequest(null, this.acceptedProtocol ?? null);
+		this.webSocketState = "connected";
+		return this.connection;
+	}
+	async handle(data) {
+		if (this.rejected) {
+			this.webSocketState = "error";
+			throw new Error("Nodefony Websocket rejected");
+		}
+		if (!this.resolver) this.resolver = this.router?.resolve(this);
+		else try {
+			this.resolver.match(this.resolver.route, this);
+		} catch (e) {
+			if (!this.rejected) this.reject(e.code ?? void 0, e.message);
+			throw e;
+		}
+		await this.fireAsync("onRequest", this, this.resolver);
+		await this.kernel?.fireAsync("onRequest", this, this.resolver);
+		if (this.resolver && this.resolver.resolve) {
+			this.setMetaData({ nodefony: { websocket: {
+				state: this.webSocketState,
+				protocol: this.acceptedProtocol
+			} } });
+			await this.resolver.callController(data).then(async () => {
+				await this.saveSession().then((session) => {
+					if (session) this.log(`SAVE SESSION ID : ${session.id}`, "DEBUG");
+				}).catch((e) => {
+					throw e;
+				});
+				return this;
+			}).catch((error) => {
+				if (!this.rejected) {
+					if (this.requestEnded) throw this.close(error.code, error.message);
+					this.reject(error.code ?? void 0, error.message);
+					this.rejected = true;
+					this.webSocketState = "error";
+					throw error;
+				}
+			});
+		} else if (!this.rejected) {
+			this.reject(4004, "Not Found");
+			this.rejected = true;
+			this.webSocketState = "error";
+		}
+		return this;
+	}
+	async render(chunk, encoding) {
+		let data = chunk;
+		if (this.isJson) data = JSON.stringify(chunk);
+		return this.send(data, encoding);
+	}
+	async send(data, encoding) {
+		if (this.response) {
+			const payload = data ?? this.response.body;
+			const sink = RequestContext.get()?.renderSink;
+			if (sink) {
+				sink.body = payload;
+				return this.response;
+			}
+			this.logMessageContent("SEND", payload);
+			this.fire("onMessage", payload, this, "SEND");
+			this.fire("onSend", payload, this);
+			return this.response.send(payload, encoding);
+		}
+		throw new Error("No response found");
+	}
+	broadcast(data, encoding) {
+		if (this.response) {
+			const payload = data ?? this.response.body;
+			if (payload) {
+				this.logMessageContent("BROADCAST", payload);
+				this.fire("onMessage", payload, this, "BROADCAST");
+				this.fire("onBroadcast", payload, this);
+				return this.response.broadcast(payload, encoding);
+			}
+		}
+		return null;
+	}
+	/**
+	* Logge le CONTENU d'un message WS (corrélé `requestId` via l'override `log`),
+	* gaté hors prod et borné — le Suivi de requête (Studio) le surface alors par
+	* direction. Hot path : le gate booléen court-circuite en prod AVANT toute
+	* construction de chaîne (0 allocation / 0 concat).
+	*
+	* @param dir - sens du message du point de vue serveur.
+	* @param data - charge utile (string, Buffer binaire, objet, ou null).
+	*/
+	logMessageContent(dir, data) {
+		if (wsContentLogging === null) wsContentLogging = this.kernel?.environment !== "production";
+		if (!wsContentLogging) return;
+		this.log(formatWsLogContent(data), "DEBUG", `WS ${dir}`);
+	}
+	/**
+	* Ouvre le profil d'**une invocation** du pont RPC (une frame `api.request`).
+	*
+	* Le contexte WS vit pour la CONNEXION : ses `phases` sont cumulatives et son
+	* `requestId` est unique pour toute la socket. Une frame reçoit donc son
+	* propre profil, identifié `<requestId de la connexion>.<n° de frame>` — le
+	* `id` JSON-RPC ne peut pas servir de clé : il est choisi par le client.
+	*
+	* @param method - méthode LOGIQUE de l'invocation (`GET`, `POST`…).
+	* @param framePath - chemin invoqué par la frame (jamais l'URL de la
+	*          connexion) — nommé ainsi parce que `url` masquerait le module
+	*          `node:url`, importé ici et utilisé par `connect()`.
+	* @returns le profil, ou `null` si profiler ET timing sont éteints (prod) —
+	*          zéro allocation dans ce cas.
+	*/
+	beginFrame(method, framePath) {
+		if (!this.profiling && !this.timingEnabled) return null;
+		this.#frameSeq += 1;
+		return new FrameProfile({
+			requestId: `${this.requestId}.${this.#frameSeq}`,
+			type: this.type,
+			scheme: this.scheme,
+			method,
+			url: framePath,
+			remoteAddress: this.remoteAddress ?? null,
+			traceparent: this.traceparent,
+			security: this.security ?? null,
+			securityTrace: this.securityTrace,
+			timing: this.timingEnabled,
+			queries: this.profiling
+		});
+	}
+	/**
+	* Enregistre le profil d'une invocation terminée dans le ring buffer du
+	* Profiler (no-op hors dev, ou si aucun profil n'a été ouvert).
+	*/
+	collectFrame(frame) {
+		if (frame === null || !this.profiling) return;
+		this.get("profiler")?.collect(frame);
+	}
+	/**
+	* Les phases émises pendant une invocation du pont (`initialize` par le
+	* Resolver, `render` par le Controller…) vont dans le profil de **la frame**,
+	* pas du contexte : sans cette redirection, `Context.phases` accumulerait deux
+	* entrées par message pour toute la vie de la socket (timeline cumulative
+	* ET croissance sans borne). Hors invocation (handshake), comportement de base.
+	*/
+	phaseStart(name) {
+		if (!this.timingEnabled) return;
+		const frame = RequestContext.get()?.invocation;
+		if (frame) {
+			frame.phaseStart(name);
+			return;
+		}
+		super.phaseStart(name);
+	}
+	phaseEnd(name) {
+		if (!this.timingEnabled) return;
+		const frame = RequestContext.get()?.invocation;
+		if (frame) {
+			frame.phaseEnd(name);
+			return;
+		}
+		super.phaseEnd(name);
+	}
+	async handleMessage(data, isBinary) {
+		this.webSocketState = "message";
+		const message = isBinary ? data : data.toString();
+		this.logMessageContent("RECEIVE", message);
+		if (this.response) this.response.body = Buffer.isBuffer(data) ? data : Buffer.from(data.toString());
+		try {
+			if (!this.resolver) this.resolver = this.router?.resolve(this);
+			else this.resolver.match(this.resolver?.route, this);
+			await this.fireAsync("onMessage", message, this, "RECEIVE");
+			if (this.resolver.resolve) {
+				this.setMetaData({ nodefony: { websocket: {
+					state: this.webSocketState,
+					protocol: this.acceptedProtocol
+				} } });
+				return this.resolver.callController([message]).catch((e) => {
+					throw e;
+				});
+			} else if (!this.rejected) {
+				this.reject(4004, "Not Found");
+				this.rejected = true;
+			}
+		} catch (e) {
+			this.reject(1011, "Internal Error");
+			throw e;
+		}
+	}
+	onClose(code, reason) {
+		const description = reason.toString();
+		this.log(`${logColor.cyan("URL")} : ${this.url}  ${logColor.cyan("FROM")} : ${this.remoteAddress} ${logColor.cyan("ORIGIN")} : ${this.originUrl?.host} ${logColor.cyan("ID")} : ${this.requestId} ${logColor.cyan("Description")} : ${description}`, "INFO", `${this.type} ${logColor.magenta(code)} CLOSE ${this.method}`);
+		if (this.connection?.readyState !== Ws.CLOSED) {
+			try {
+				this.response?.drop(code, description);
+			} catch (e) {
+				this.log(`${logColor.cyan("URL")} : ${this.url}  ${logColor.cyan("FROM")} : ${this.remoteAddress} ${logColor.cyan("ORIGIN")} : ${this.originUrl?.host} ${logColor.cyan("ID")} : ${this.requestId} ${logColor.cyan("error")} : ${e.message}`, "ERROR", `${this.type} CLOSE ${logColor.red(this.method ?? "")}`);
+			}
+			this.fire("onClose", code, description, this.connection);
+		} else this.fire("onClose", code, description, this.connection);
+		this.fire("onFinish", this, code, description);
+		this.webSocketState = "closed";
+	}
+	/**
+	* Listener `error` de la socket ws (OBLIGATOIRE — sans lui, un 'error' émis
+	* sans listener crashe le process via EventEmitter). `ws` émet 'error' PUIS
+	* 'close' → le teardown se fait dans {@link onClose} ; ici on logge seulement
+	* (pas de double-close). Erreur transport (reset TCP, frame corrompue…).
+	*
+	* @param error - erreur émise par la socket.
+	*/
+	onConnectionError(error) {
+		this.webSocketState = "error";
+		this.log(`${logColor.cyan("URL")} : ${this.url}  ${logColor.cyan("FROM")} : ${this.remoteAddress} ${logColor.cyan("ID")} : ${this.requestId} ${logColor.cyan("error")} : ${error?.message}`, "ERROR", `${this.type} ${logColor.red("SOCKET ERROR")} ${this.method}`);
+		this.fire("onError", error, this);
+	}
+	setScheme() {
+		return this.wsUrl?.protocol.replace(":", "");
+	}
+	getRemoteAddress() {
+		if (this.forwarded) return this.forwarded.clientIp;
+		return this.request?.socket?.remoteAddress ?? null;
+	}
+	getHost() {
+		return this.request?.headers.host;
+	}
+	getHostName() {
+		return this.wsUrl?.hostname;
+	}
+	getUserAgent() {
+		return this.request?.headers["user-agent"];
+	}
+	getMethod() {
+		return "WEBSOCKET";
+	}
+	setContextJson() {
+		this.isJson = true;
+	}
+	clean() {
+		this.request = null;
+		if (this.response) this.response.clean();
+		this.response = null;
+		this.connection = null;
+		this.container?.clean();
+		super.clean();
+	}
+	close(reasonCode, description) {
+		if (this.response) return this.response.close(toWsCloseCode(reasonCode), description);
+	}
+	drop(reasonCode, description) {
+		if (this.response) return this.response.drop(reasonCode, description);
+	}
+	reject(code, message) {
+		if (this.connection && this.connection.readyState === Ws.OPEN) {
+			const raw = typeof code === "string" ? parseInt(code, 10) : code;
+			this.connection.close(toWsCloseCode(raw), message ?? "Rejected");
+		}
+		this.rejected = true;
+	}
+};
+//#endregion
+export { WebsocketContext as default, toWsCloseCode };

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

@@ -0,0 +1,56 @@
+//#region nodefony/src/context/websocket/wsBackpressure.ts
+/**
+* Relit le seuil + la politique depuis les options du `WebSocketServer`.
+*
+* `ws` préserve nos clés custom (`maxBackpressure`/`backpressurePolicy`) dans
+* `wss.options` via le spread de son constructeur. Appelé UNE fois hors de la boucle
+* `broadcast()` (pas par frame).
+*
+* @param wss - le serveur WebSocket (ou null/undefined → backpressure désactivée)
+* @returns seuil résolu (`max`, 0 = off) + politique (`policy`, défaut `"drop"`)
+*/
+const readBackpressureOptions = (wss) => {
+	const opts = wss?.options ?? {};
+	return {
+		max: opts.maxBackpressure ?? 0,
+		policy: opts.backpressurePolicy ?? "drop",
+		closeAfterDrops: opts.backpressureCloseAfterDrops ?? 0
+	};
+};
+/**
+* Décide si une frame doit partir vers `ws` selon la backpressure SORTANTE
+* (serveur → client). Protège la RAM d'envoi du serveur quand le client est lent à
+* RECEVOIR (ne lit pas assez vite → `ws.bufferedAmount` gonfle → OOM). `broadcast()`
+* amplifie : un seul client lent peut, sans borne, faire tomber la diffusion entière.
+*
+* PERF (hot path WS) : lecture O(1) de `ws.bufferedAmount`, **0 allocation sous le
+* seuil** (chemin nominal = comportement inchangé). Au-delà : incrémente `_nfDrops`
+* (lazy) et, si la politique est `close`, ferme la socket (RFC 6455 close 1013
+* « Try Again Later » → le client peut back-off + reconnecter). NE FAIT PAS le `send()`
+* — le caller émet uniquement si le retour vaut `"send"`.
+*
+* @param ws - la socket destinataire
+* @param max - seuil d'octets (`<= 0` → désactivé)
+* @param policy - action au dépassement
+* @returns `"send"` (émettre) · `"drop"` (sauter cette frame) · `"close"` (socket fermée)
+*/
+const decideSend = (ws, max, policy, closeAfterDrops = 0) => {
+	const sock = ws;
+	if (max <= 0 || (ws.bufferedAmount ?? 0) <= max) {
+		if (sock._nfDropStreak) sock._nfDropStreak -= 1;
+		return "send";
+	}
+	sock._nfDrops = (sock._nfDrops ?? 0) + 1;
+	const streak = sock._nfDropStreak = (sock._nfDropStreak ?? 0) + 1;
+	if (policy === "close") {
+		ws.close(1013, "backpressure");
+		return "close";
+	}
+	if (closeAfterDrops > 0 && streak >= closeAfterDrops) {
+		ws.close(1013, "backpressure");
+		return "close";
+	}
+	return "drop";
+};
+//#endregion
+export { decideSend, readBackpressureOptions };

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

@@ -0,0 +1,68 @@
+//#region nodefony/src/context/websocket/wsLogContent.ts
+/**
+* Formatage **pur** (0 état, 0 dépendance) du CONTENU d'un message WebSocket pour
+* le log de trace (Suivi de requête Studio). Séparé de `WebsocketContext` pour
+* être testable aux limites sans serveur.
+*
+* 🔒 Robustesse binaire (cf doc `ws` — `socket.send(data)` accepte
+* `String | Number | Object | Buffer | ArrayBuffer | TypedArray | DataView |
+* Buffer[] | Blob`, et l'event `message` livre `Buffer | ArrayBuffer | Buffer[]`).
+* **Toute** charge binaire est résumée `[binary N B]` — JAMAIS sérialisée
+* (`JSON.stringify(new Uint8Array(...))` produirait `{"0":..,"1":..}`, énorme et
+* faux). Seules string et objets « JSON » sont rendus en texte (borné).
+*/
+/** Cap de troncature du contenu loggé (octets/chars). Borne ring + JSONL. */
+const WS_LOG_CONTENT_CAP = 4096;
+/**
+* Taille en octets d'une charge **binaire** reconnue, ou `-1` si la valeur n'est
+* pas binaire (→ à traiter en JSON/texte). Couvre tous les types binaires que
+* `ws` accepte/livre : `Buffer`, `ArrayBuffer`, vues (`TypedArray`/`DataView`),
+* `Blob` (Node ≥ 18), et `Buffer[]` (fragments — binaire ssi TOUS ses éléments
+* le sont, sinon c'est un tableau JSON ordinaire).
+*
+* @param data - valeur à mesurer.
+* @returns nombre d'octets, ou `-1` si non binaire.
+*/
+function binaryByteLength(data) {
+	if (Buffer.isBuffer(data)) return data.length;
+	if (data instanceof ArrayBuffer) return data.byteLength;
+	if (ArrayBuffer.isView(data)) return data.byteLength;
+	if (typeof Blob !== "undefined" && data instanceof Blob) return data.size;
+	if (Array.isArray(data)) {
+		let total = 0;
+		for (const part of data) {
+			const n = binaryByteLength(part);
+			if (n < 0) return -1;
+			total += n;
+		}
+		return total;
+	}
+	return -1;
+}
+/**
+* Formate une charge utile WS en chaîne **bornée** et **sûre** pour le log :
+*  - `string` → tronquée à `cap` (+ ellipse) ;
+*  - binaire (cf {@link binaryByteLength}) → `[binary N B]` (jamais de dump) ;
+*  - `null`/`undefined` → `""` ;
+*  - objet « JSON » → `JSON.stringify` compact tronqué (cycle, `bigint`, valeur
+*    non sérialisable → repli `String(...)`).
+*
+* @param data - charge utile (RECEIVE/SEND/BROADCAST).
+* @param cap - longueur max avant troncature (défaut {@link WS_LOG_CONTENT_CAP}).
+*/
+function formatWsLogContent(data, cap = WS_LOG_CONTENT_CAP) {
+	if (typeof data === "string") return data.length > cap ? `${data.slice(0, cap)}…` : data;
+	if (data === null || data === void 0) return "";
+	const bytes = binaryByteLength(data);
+	if (bytes >= 0) return `[binary ${bytes} B]`;
+	let s;
+	try {
+		s = JSON.stringify(data);
+	} catch {
+		return String(data);
+	}
+	if (typeof s !== "string") return String(data);
+	return s.length > cap ? `${s.slice(0, cap)}…` : s;
+}
+//#endregion
+export { WS_LOG_CONTENT_CAP, binaryByteLength, formatWsLogContent };