nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/client/syslog/Pdu.js

@@ -0,0 +1,224 @@
+//#region src/syslog/Pdu.ts
+var SysLogSeverity = /* @__PURE__ */ function(SysLogSeverity) {
+	SysLogSeverity[SysLogSeverity["EMERGENCY"] = 0] = "EMERGENCY";
+	SysLogSeverity[SysLogSeverity["ALERT"] = 1] = "ALERT";
+	SysLogSeverity[SysLogSeverity["CRITIC"] = 2] = "CRITIC";
+	SysLogSeverity[SysLogSeverity["ERROR"] = 3] = "ERROR";
+	SysLogSeverity[SysLogSeverity["WARNING"] = 4] = "WARNING";
+	SysLogSeverity[SysLogSeverity["NOTICE"] = 5] = "NOTICE";
+	SysLogSeverity[SysLogSeverity["INFO"] = 6] = "INFO";
+	SysLogSeverity[SysLogSeverity["DEBUG"] = 7] = "DEBUG";
+	return SysLogSeverity;
+}(SysLogSeverity || {});
+const sysLogSeverity = [
+	0,
+	1,
+	2,
+	3,
+	4,
+	5,
+	6,
+	7
+];
+/**
+* Les noms de sévérité RFC 5424, **dans l'ordre de l'enum** (l'index EST la
+* valeur : `SEVERITY_NAMES[3] === "ERROR"`). Les huit niveaux de la RFC, et
+* rien d'autre : une animation de terminal n'est pas un niveau de journal.
+*
+* Source **unique** du vocabulaire, côté serveur comme côté navigateur (le
+* bundle client la réexporte). Elle existe parce qu'elle était écrite trois
+* fois — deux copies dans la console d'administration, dans deux ORDRES
+* différents, et aucune côté data plane, si bien qu'un `?severity=CRITICAL`
+* n'était refusé nulle part : il rendait le journal entier.
+*
+* Pour un sélecteur qui va du moins au plus grave, lire `[...SEVERITY_NAMES]
+* .reverse()` — l'ordre d'affichage se dérive, il ne se redéclare pas.
+*/
+const SEVERITY_NAMES = [
+	"EMERGENCY",
+	"ALERT",
+	"CRITIC",
+	"ERROR",
+	"WARNING",
+	"NOTICE",
+	"INFO",
+	"DEBUG"
+];
+/**
+* `moduleName` porté par une entrée de journal venue d'un NAVIGATEUR.
+*
+* Valeur de confiance : le pod l'impose lui-même en recevant un lot sur le canal
+* montant, sans jamais reprendre ce que la page prétend être. Une ligne qui la porte
+* a donc traversé ce canal, et rien d'autre ne peut la produire.
+*
+* Elle vit ICI, dans le cœur isomorphe, pour la même raison que
+* {@link SEVERITY_NAMES} : le serveur l'écrit, le navigateur la lit pour distinguer
+* ces lignes à l'écran. Une copie côté console d'administration dériverait le jour
+* où le mot change — et un écran qui ne reconnaît plus l'origine ne se plaint pas,
+* il affiche simplement une ligne de plus au milieu des autres.
+*/
+const BROWSER_ORIGIN = "browser";
+const translateSeverity = function(severity = "INFO") {
+	if (typeof severity === "number") {
+		if (sysLogSeverity[severity] !== void 0) return sysLogSeverity[severity];
+		else throw new Error(`Not a valid nodefony syslog severity: ${severity}`);
+	} else if (SysLogSeverity[severity] !== void 0) return SysLogSeverity[severity];
+	else throw new Error(`Not a valid nodefony syslog severity: ${severity}`);
+};
+const sysLogSeverityObj = Object.entries(SysLogSeverity).reduce((acc, [key, value]) => {
+	acc[key] = value;
+	return acc;
+}, {});
+const severityNameMap = new Map(Object.entries(SysLogSeverity).filter(([, v]) => typeof v === "number").map(([k, v]) => [v, k]));
+const _gBuffer = globalThis.Buffer;
+const PID = globalThis.process?.pid ?? 0;
+const fastTypeOf = (value) => {
+	if (value === null) return null;
+	const t = typeof value;
+	if (t !== "object") return t;
+	if (Array.isArray(value)) return "array";
+	if (value instanceof Date) return "date";
+	if (value instanceof RegExp) return "RegExp";
+	if (value instanceof Error) return "Error";
+	if (_gBuffer?.isBuffer(value)) return "buffer";
+	return "object";
+};
+/**
+* Process Data Unit — entrée de log unitaire conforme RFC 5424.
+*
+* Une instance représente un événement de log dans le pipeline Syslog.
+* Stockée dans le `CircularBuffer` (O(1)) et diffusée aux transports
+* via l'event `onLog` du {@link Syslog}.
+*
+* @example
+* ```ts
+* const pdu = new Pdu("user logged in", "INFO", "AUTH", "USER_LOGIN", "user@example.com");
+* pdu.severity;      // 6
+* pdu.severityName;  // "INFO"
+* pdu.payload;       // "user logged in"
+* ```
+*
+* @remarks `pdu.severity` est numérique (RFC 5424) pour comparaisons rapides.
+*   `pdu.severityName` est la string (`"INFO"`, `"CRITIC"` — pas `"CRITICAL"`).
+*/
+let guid = 0;
+var Pdu = class Pdu {
+	payload;
+	uid;
+	severity;
+	timeStamp;
+	severityName;
+	typePayload;
+	moduleName;
+	msgid;
+	msg;
+	status;
+	/** PID du process émetteur (= procid RFC 5424). Constant, capturé au chargement du module. */
+	pid;
+	/**
+	* Identifiant de la requête en cours (corrélation log↔requête).
+	*
+	* Présent UNIQUEMENT si le Pdu est créé dans une bulle `RequestContext` active
+	* (ALS Node) ET que {@link Pdu.requestIdProvider} a été branché côté Node — voir
+	* `src/index.ts` (barrel Node uniquement, isomorphisme préservé : le bundle
+	* client/browser ne branche pas, le provider reste `null` → 0 alloc, 0 lecture).
+	*
+	* Combiné à `pid` (procid RFC 5424), permet la corrélation **complète** :
+	* `pid` = quel worker, `requestId` = quelle requête. Voyage dans ring buffer +
+	* `nodefony:syslog` + transports JSON (champ public sérialisé naturellement).
+	*/
+	requestId;
+	/**
+	* Provider injectable du `requestId` courant (ALS). Branché par le barrel
+	* Node (`src/index.ts`) sur `RequestContext.getRequestId`. Reste `null` côté
+	* browser/debugbar (le bundle client n'importe pas `node:async_hooks`) et
+	* pendant les phases boot pré-Kernel (cohérent : pas de requête en cours).
+	*
+	* Coût : 1 test de référence par Pdu (~5 ns) quand `null` ; ~50-100 ns quand
+	* branché (lecture ALS + accès propriété). Pas d'alloc supplémentaire si
+	* `requestId` est `undefined` (le champ reste non-défini sur l'instance).
+	*/
+	static requestIdProvider = null;
+	/**
+	* Construit un Pdu prêt à être publié dans le pipeline Syslog.
+	*
+	* @param pci - payload (string, Error, objet — typé `unknown`, narrower côté lecteur).
+	* @param severity - niveau RFC 5424 (string `"INFO"` ou numérique `6`). Défaut `"INFO"`.
+	* @param moduleName - nom du module/service qui a produit le log. Défaut `"nodefony"`.
+	* @param msgid - catégorie de message (`"AUTH"`, `"ROUTER"`, etc.). Défaut `""`.
+	* @param msg - détail libre optionnel. Défaut `""`.
+	* @param date - timestamp (number, Date, ou string parsable). Défaut `Date.now()`.
+	* @throws Si `severity` n'est pas une valeur valide de {@link SysLogSeverity}.
+	*/
+	constructor(pci, severity, moduleName = "nodefony", msgid = "", msg = "", date) {
+		if (date === void 0) this.timeStamp = Date.now();
+		else if (typeof date === "number") this.timeStamp = date;
+		else if (date instanceof Date) this.timeStamp = date.getTime();
+		else this.timeStamp = new Date(date).getTime();
+		this.uid = ++guid;
+		this.severity = translateSeverity(severity);
+		const sName = severityNameMap.get(this.severity);
+		if (sName === void 0) throw new Error(`Invalid severity value: ${this.severity}`);
+		this.severityName = sName;
+		this.typePayload = fastTypeOf(pci);
+		this.payload = pci;
+		this.moduleName = moduleName;
+		this.msgid = msgid;
+		this.msg = msg;
+		this.status = "NOTDEFINED";
+		this.pid = PID;
+		this.requestId = Pdu.requestIdProvider !== null ? Pdu.requestIdProvider() : void 0;
+	}
+	/**
+	* Map bidirectionnelle des sévérités RFC 5424 (`{ INFO: 6, 6: "INFO", ... }`).
+	*
+	* @returns dictionnaire `{ severityName: severityValue }` plus enum reverse.
+	*/
+	static sysLogSeverity() {
+		return sysLogSeverityObj;
+	}
+	/**
+	* Convertit une sévérité numérique ou string en son nom canonique.
+	*
+	* @param severity - valeur numérique (`6`) ou string (`"INFO"` ou `"6"`).
+	* @returns nom canonique (`"INFO"`) ou `undefined` si invalide.
+	*/
+	static severityToString(severity) {
+		const numericSeverity = typeof severity === "string" ? parseInt(severity, 10) : severity;
+		if (!isNaN(numericSeverity) && SysLogSeverity[numericSeverity] !== void 0) return SysLogSeverity[numericSeverity];
+		const severityKey = Pdu.severityToString(SysLogSeverity[severity]);
+		return severityKey !== void 0 ? severityKey : void 0;
+	}
+	/**
+	* Retourne le timestamp formaté `HH:MM:SS GMT±HHMM (TZ Name)`.
+	*
+	* @returns time string lisible par humain.
+	*/
+	getDate() {
+		return new Date(this.timeStamp).toTimeString();
+	}
+	/**
+	* Sérialise le Pdu en string mono-ligne pour transport console/file.
+	*
+	* @returns ligne formatée `TimeStamp:... Log:... ModuleName:... SeverityName:... MessageID:... UID:... Message:...`.
+	*/
+	toString() {
+		return `TimeStamp:${this.getDate()}  Log:${this.payload}  ModuleName:${this.moduleName}  SeverityName:${this.severityName}  MessageID:${this.msgid}  UID:${this.uid}  Message:${this.msg}`;
+	}
+	/**
+	* Réhydrate un Pdu existant à partir d'une string JSON — mute uniquement les
+	* clés déjà présentes sur l'instance (filtre `key in this`).
+	*
+	* @param str - JSON sérialisé d'un Pdu.
+	* @returns objet parsé (ou `null` si JSON vide). Mute l'instance courante au passage.
+	*/
+	parseJson(str) {
+		const json = JSON.parse(str);
+		Object.entries(json).forEach(([key, value]) => {
+			if (key in this) this[key] = value;
+		});
+		return json;
+	}
+};
+//#endregion
+export { BROWSER_ORIGIN, SEVERITY_NAMES, Pdu as default };