@nodefony/http 10.0.0-alpha.1

package/dist/nodefony/service/error-renderer.js

@@ -0,0 +1,320 @@
+import HttpError from "../src/errors/httpError.js";
+import { toWsCloseCode } from "../src/context/websocket/WebsocketContext.js";
+import { Nodefony, nodefonyError } from "nodefony";
+//#region nodefony/service/error-renderer.ts
+/** Une donnée rejetée par la validation n'est pas une requête malformée : 422, pas 400. */
+const VALIDATION_STATUS = 422;
+/**
+* Statut d'un conflit d'ÉTAT : la requête est valide, c'est l'état courant du
+* serveur qui la refuse (RFC 9110 §15.5.10). Réécrire une valeur déclarée unique
+* est exactement ce cas — ni 400 (le corps est lisible), ni 422 (le contenu
+* respecte le schéma), ni 500 (rien n'est cassé).
+*/
+const CONFLICT_STATUS = 409;
+/**
+* Codes rendus par les pilotes de base de données quand une écriture viole une
+* contrainte d'UNICITÉ — le seul signal fiable, commun à tous les moteurs.
+*
+* Volontairement restreint aux codes qui ne désignent QUE l'unicité : le
+* `SQLITE_CONSTRAINT` générique couvre aussi NOT NULL, CHECK et les clés
+* étrangères, et le retenir rendrait un 409 là où la vérité est un 422 (ou un
+* 500). Un code inconnu retombe donc sur le comportement d'avant — l'oubli coûte
+* un statut trop pessimiste, jamais un mensonge.
+*/
+const UNIQUE_VIOLATION_CODES = /* @__PURE__ */ new Set([
+	"SQLITE_CONSTRAINT_UNIQUE",
+	"SQLITE_CONSTRAINT_PRIMARYKEY",
+	"23505",
+	"ER_DUP_ENTRY",
+	"1062",
+	"11000",
+	"11001"
+]);
+/**
+* Ce qu'un client reçoit sur un doublon.
+*
+* Le message du pilote (« UNIQUE constraint failed: posts.slug ») nomme la table
+* ET la colonne : c'est de la cartographie de schéma offerte à qui frappe la
+* porte. Le détail reste dans la `stack` — journal côté serveur, et corps de
+* réponse hors production.
+*/
+const UNIQUE_VIOLATION_MESSAGE = "Conflict — a resource with these unique values already exists";
+/**
+* Ce qu'un client reçoit à la place du détail d'une panne serveur, en production.
+*
+* Le message d'une exception non maîtrisée cite volontiers un chemin de fichier,
+* un nom de table, une requête SQL ou un identifiant interne. Le rendre à un
+* client — a fortiori **anonyme**, un close WS partant avant le firewall —
+* revient à publier de la reconnaissance gratuite.
+*/
+const OPAQUE_SERVER_ERROR = "Internal Server Error";
+/**
+* Clés d'un `HttpError` sérialisé qui décrivent les ENTRAILLES du serveur et ne
+* doivent jamais franchir la frontière en production.
+*/
+const INTERNAL_ERROR_KEYS = [
+	"stack",
+	"controller",
+	"action",
+	"bundle",
+	"url",
+	"pdu"
+];
+/**
+* Vrai si le runtime tourne en production — le détail des erreurs reste alors au
+* journal, seul le serveur le voit.
+*
+* ⚠️ La comparaison porte sur `"production"` **en toutes lettres** : `Kernel.setEnv`
+* réduit toujours l'environnement à `"development" | "production"`
+* (`Kernel.resolveRuntimeEnv`). Une garde écrite `=== "prod"` ne se déclenche donc
+* JAMAIS, même si `"prod"` est une valeur acceptée en entrée.
+*
+* Résolu à chaque rendu (pas de cache) : une erreur est déjà un chemin froid, et
+* mémoïser rendrait le masquage insensible à un changement d'environnement entre
+* deux tests — un gate qu'on ne peut plus voir mordre.
+*/
+const isProduction = () => Nodefony.getKernel()?.environment === "production";
+/**
+* Reconnaît une erreur de validation Zod et en extrait les champs fautifs.
+*
+* Reconnaissance **structurelle** (`name` + `issues`), pas `instanceof ZodError` :
+* une application peut embarquer sa propre copie de zod (résolutions npm multiples),
+* et `instanceof` échouerait alors en silence — la validation retomberait en 500.
+* Même parti-pris que le duck-typing de `isPromise` dans le framework.
+*
+* Ne coûte rien au chemin nominal : ce code ne tourne que sur une erreur déjà levée.
+*
+* @param error - erreur remontée par le pipeline.
+* @returns les champs fautifs, ou `null` si ce n'est pas une erreur de validation.
+*/
+function toValidationFields(error) {
+	const candidate = error;
+	if (error.name !== "ZodError" || !Array.isArray(candidate.issues)) return null;
+	return candidate.issues.map((issue) => ({
+		field: Array.isArray(issue.path) ? issue.path.join(".") : "",
+		message: issue.message ?? "invalide",
+		rule: issue.code
+	}));
+}
+/**
+* Construit l'erreur **422** exposée au client à partir des champs fautifs.
+*
+* Pourquoi 422 et pas 400 : la requête est syntaxiquement correcte (le corps a été
+* parsé) — c'est son **contenu** qui viole le contrat (RFC 9110 §15.5.21). Un 400
+* dirait « corps illisible » et enverrait le client chercher au mauvais endroit.
+*
+* Le message d'origine de zod (un JSON d'anomalies) est remplacé par un résumé
+* lisible ; la **stack d'origine est conservée** (débogage), et `fields` est porté par
+* l'erreur elle-même : `toJSON()` sérialise les propriétés propres, donc le client
+* reçoit `error.fields` et sait QUEL champ corriger — pas seulement que « ça a échoué ».
+*/
+function toValidationError(error, fields) {
+	const summary = fields.map((f) => f.field ? `${f.field}: ${f.message}` : f.message).join(" · ");
+	const validation = new nodefonyError(`Validation failed — ${summary}`, VALIDATION_STATUS);
+	validation.stack = error.stack;
+	validation.fields = fields;
+	return validation;
+}
+/**
+* Vrai si l'erreur — ou l'une de ses causes — est une violation de contrainte
+* d'unicité remontée par un pilote de base de données.
+*
+* **La descente dans `cause` n'est pas un raffinement, c'est la condition pour
+* que ça marche** : Drizzle enveloppe toute erreur de pilote dans un
+* `DrizzleQueryError` dont le `code` vaut `undefined`. Sans elle, une écriture
+* en doublon reste un 500.
+*
+* Reconnaissance par CODE seul, jamais par message : « duplicate key » dans un
+* texte d'erreur est un indice, pas une preuve, et un faux positif déguiserait
+* une panne réelle en conflit — le client réessaierait autrement au lieu
+* d'alerter. Même parti-pris de duck-typing que `toValidationFields`, pour la
+* même raison (l'application peut embarquer sa propre copie du pilote).
+*
+* Ne coûte rien au chemin nominal : ne tourne que sur une erreur déjà levée.
+*
+* @param error - erreur remontée par le pipeline.
+* @returns vrai si un code de violation d'unicité est trouvé dans la chaîne.
+*/
+function isUniqueViolation(error) {
+	let current = error;
+	for (let depth = 0; depth < 5 && current instanceof Error; depth += 1) {
+		const candidate = current;
+		if (candidate.code !== void 0 && UNIQUE_VIOLATION_CODES.has(String(candidate.code)) || candidate.errno !== void 0 && UNIQUE_VIOLATION_CODES.has(String(candidate.errno))) return true;
+		current = candidate.cause;
+	}
+	return false;
+}
+/**
+* Codes rendus par les pilotes quand la requête porte sur une TABLE ou une
+* COLONNE que la base n'a pas — la signature d'un schéma en retard sur le code.
+*
+* Jumelle de {@link UNIQUE_VIOLATION_CODES}, et pour la même raison : le code
+* est le seul signal fiable. Reconnaître « does not exist » dans un message
+* serait un piège — la formulation change d'un pilote et d'une version à
+* l'autre, et la même phrase apparaît dans des erreurs qui n'ont rien à voir.
+*
+* **SQLite n'a pas sa place ici** : il ne rend qu'un `SQLITE_ERROR` générique,
+* partagé avec la syntaxe invalide et bien d'autres fautes — le mettre dans
+* cette table le rendrait aussi ferme que `42P01`, ce qu'il n'est pas. Il est
+* reconnu à part, et plus faiblement, par {@link SQLITE_SCHEMA_PREFIXES}.
+*/
+const SCHEMA_MISMATCH_CODES = /* @__PURE__ */ new Set([
+	"42703",
+	"42P01",
+	"ER_BAD_FIELD_ERROR",
+	"1054",
+	"ER_NO_SUCH_TABLE",
+	"1146"
+]);
+/**
+* Ce que SQLite dit, faute de code dédié.
+*
+* SQLite ne rend qu'un `SQLITE_ERROR` générique — partagé avec la syntaxe
+* invalide et bien d'autres fautes —, donc le code seul ne tranche pas. Ces
+* deux préfixes, eux, sont sans ambiguïté : ils viennent du source de SQLite,
+* ils y sont stables depuis toujours, et aucune autre faute ne les produit.
+*
+* Ce n'est PAS un retour à la reconnaissance par message : on n'accepte que
+* des débuts de message figés, et seulement après avoir constaté le code du
+* pilote. Une formulation libre du genre « does not exist » resterait un
+* piège — elle change d'un pilote et d'une version à l'autre.
+*/
+const SQLITE_SCHEMA_PREFIXES = ["no such table:", "no such column:"];
+/**
+* Reconnaît, dans une erreur ou l'une de ses causes, un schéma en retard sur
+* le code — et dit avec quelle FORCE.
+*
+* Détecteur UNIQUE de ce fait dans tout le framework : le corps d'erreur rendu
+* au développeur le lit, et le rechargement d'un instantané au démarrage
+* aussi. Deux reconnaissances de la même chose divergeraient en silence, et
+* chacune passerait ses propres tests.
+*
+* Chaque lecteur choisit son SEUIL, et c'est là que la graduation sert. Le
+* corps d'erreur n'accepte que `certain` : il nomme des tables à un client, et
+* une aide qui se trompe de cause coûte plus cher que pas d'aide du tout. Un
+* appelant qui sait déjà ce qu'il a demandé — une table précise, au démarrage —
+* peut accepter `probable` : il ne publie rien, il décide seulement de ne pas
+* hurler.
+*
+* Même descente dans `cause` que {@link isUniqueViolation}, et pour la même
+* raison : Drizzle enveloppe toute erreur de pilote dans un `DrizzleQueryError`
+* dont le `code` vaut `undefined`. Sans elle, la reconnaissance ne mord jamais.
+*
+* Ne coûte rien au chemin nominal : ne tourne que sur une erreur déjà levée.
+*
+* @param error - erreur remontée par un pilote, éventuellement enveloppée.
+* @returns la force du signal, ou `null` si rien ne dit ça.
+*/
+function schemaMismatchOf(error) {
+	let current = error;
+	for (let depth = 0; depth < 5 && current instanceof Error; depth += 1) {
+		const candidate = current;
+		if (candidate.code !== void 0 && SCHEMA_MISMATCH_CODES.has(String(candidate.code)) || candidate.errno !== void 0 && SCHEMA_MISMATCH_CODES.has(String(candidate.errno))) return "certain";
+		if (String(candidate.code) === "SQLITE_ERROR" && SQLITE_SCHEMA_PREFIXES.some((p) => candidate.message?.startsWith(p))) return "probable";
+		current = candidate.cause;
+	}
+	return null;
+}
+/**
+* L'aide rendue au développeur quand la base est en retard sur le code.
+*
+* Elle ne cite PAS le message du pilote : c'est lui que le lecteur vient de
+* recevoir sans le comprendre, et le répéter n'apprend rien. Elle nomme la
+* cause — le schéma — et donne les deux gestes, dans l'ordre où ils se tentent.
+*/
+const SCHEMA_MISMATCH_HINT = {
+	kind: "schema-mismatch",
+	message: "La base ne correspond pas au code : une table ou une colonne que le code déclare n'existe pas. C'est le schéma qui est en retard, pas la requête.",
+	actions: [
+		"Redémarrer le serveur — en développement, les colonnes qui acceptent le vide sont rattrapées au démarrage.",
+		"nodefony orm:migrate:status — dire ce qui manque, sans rien modifier.",
+		"nodefony orm:reset --connector default — SUPPRIME et recrée la base de développement."
+	]
+};
+/**
+* Default Nodefony error renderer — preserves the legacy JSON error shape.
+*
+* HTTP body (unchanged across the migration):
+*   {
+*     code:    <http status>,
+*     message: <error message>,
+*     error:   <HttpError.toJSON() — stack, controller, action, jsonResponse...>,
+*     nodefony: { requestId, scheme, name, version, environment, debug, ... },
+*     result:  null,
+*   }
+*
+* WS close frame:
+*   code:   clamped to WS range (1000-4999), 1011 if HTTP-style code, 500→1011
+*   reason: error.message
+*
+* Stateless singleton — zero per-request allocation. Override via
+* `httpKernel.setErrorRenderer(custom)` for prod hardening or RFC 7807.
+*/
+var DefaultErrorRenderer = class {
+	renderHttp(error, context) {
+		const httpError = this.toHttpError(error, context);
+		const status = this.normalizeHttpStatus(httpError.code);
+		httpError.code = status;
+		const obj = context.metaData;
+		const serialized = httpError.toJSON();
+		const message = isProduction() && status >= 500 ? OPAQUE_SERVER_ERROR : httpError.message;
+		if (isProduction()) {
+			for (const key of INTERNAL_ERROR_KEYS) delete serialized[key];
+			serialized.message = message;
+		}
+		obj.error = serialized;
+		obj.code = status;
+		obj.message = message;
+		if (!isProduction() && schemaMismatchOf(error) === "certain") obj.hint = SCHEMA_MISMATCH_HINT;
+		return {
+			status,
+			message,
+			body: obj
+		};
+	}
+	renderWebsocket(error, context) {
+		const httpError = this.toHttpError(error, context);
+		const rawCode = httpError.code;
+		let code = typeof rawCode === "number" && Number.isInteger(rawCode) ? rawCode : 500;
+		if (context && context.rejected === false) code = toWsCloseCode(code);
+		else if (code > 599) code = 500;
+		const internal = code === 1011 || code >= 500 && code <= 599;
+		const reason = isProduction() && internal ? OPAQUE_SERVER_ERROR : httpError.message;
+		return {
+			code,
+			reason
+		};
+	}
+	toHttpError(error, context) {
+		if (error instanceof HttpError) return error;
+		const fields = toValidationFields(error);
+		if (fields) {
+			const httpError = new HttpError(toValidationError(error, fields), VALIDATION_STATUS, context);
+			httpError.fields = fields;
+			return httpError;
+		}
+		if (isUniqueViolation(error)) {
+			const conflict = new nodefonyError(UNIQUE_VIOLATION_MESSAGE, CONFLICT_STATUS);
+			conflict.stack = error.stack;
+			return new HttpError(conflict, CONFLICT_STATUS, context);
+		}
+		const code = error.code;
+		return new HttpError(error, typeof code === "number" ? code : void 0, context);
+	}
+	/**
+	* Ramène un `code` d'erreur à un statut HTTP réellement émettable.
+	*
+	* Le filtre de type n'est pas défensif « au cas où » : `nodefonyError.parseMessage`
+	* RECOPIE le code de l'erreur source, et pilotes comme Node en produisent des
+	* textuels (`"ENOENT"`, `"ECONNRESET"`, `"23505"`). Sans lui, la chaîne partait
+	* telle quelle en statut de réponse et le serveur répondait hors RFC 9110 §15.
+	*/
+	normalizeHttpStatus(code) {
+		if (typeof code !== "number" || !Number.isInteger(code)) return 500;
+		if (code === 200) return 500;
+		if (code < 100 || code > 599) return 500;
+		return code;
+	}
+};
+//#endregion
+export { DefaultErrorRenderer as default, schemaMismatchOf };