@nodefony/realtime 10.0.0-beta.6 → 10.0.0-beta.7

package/dist/nodefony/src/backplane/ingress.js

@@ -0,0 +1,93 @@
+import { BackplaneEcho, openBackplaneEnvelope, openBackplaneEnvelopeBytes } from "./envelope.js";
+// nodefony/src/backplane/ingress.ts
+/**
+* **Entrée d'un bus partagé** — le tri de ce qu'un pilote reçoit, mutualisé pour
+* que tout pilote à transport réseau (Redis aujourd'hui ; Kafka, NATS, RabbitMQ…
+* demain) l'hérite sans le réécrire : écho de ce pod reconnu et compté, sceau
+* vérifié, refus comptés et annoncés.
+*
+* Le pilote ne garde que son transport : il passe chaque message reçu à
+* {@link text} ou {@link bytes} et remet au hub ce qui en sort.
+*
+* Ordre du tri, du moins cher au plus cher :
+*  1. l'ÉCHO de ce pod se reconnaît à la fin du message, sans le décoder — un HMAC
+*     sous un secret (cf {@link BackplaneEcho}) ;
+*  2. sinon, l'enveloppe est ouverte et son sceau vérifié sur la tranche reçue ;
+*  3. un message ouvert qui porte l'origine de ce pod sous une autre forme est
+*     encore un écho — compté, jamais réinjecté (anti-boucle).
+*/
+var BackplaneIngress = class {
+	#originId;
+	#secret;
+	#echo;
+	#notice;
+	#echoTotal = 0;
+	#sealRejectedTotal = 0;
+	/**
+	* @param originId - identité de CE pod sur le bus.
+	* @param secret - secret partagé, ou `null` sur un bus non scellé.
+	* @param notice - annonce des sceaux refusés ; omis = silencieux (tests).
+	*/
+	constructor(originId, secret, notice = null) {
+		this.#originId = originId;
+		this.#secret = secret;
+		this.#echo = new BackplaneEcho(originId, secret);
+		this.#notice = notice;
+	}
+	/**
+	* Trie un message reçu sur le sujet TEXTE du bus.
+	*
+	* @param raw - message brut tel que lu sur le transport.
+	* @returns le message à remettre au hub, ou `null` s'il est jeté (écho de ce
+	*   pod, malformé, sceau refusé — chacun compté).
+	*/
+	text(raw) {
+		if (this.#echo.text(raw)) {
+			this.#echoTotal += 1;
+			return null;
+		}
+		return this.#admit(openBackplaneEnvelope(raw, this.#secret));
+	}
+	/**
+	* Trie un message reçu sur le sujet BINAIRE du bus (ADR-0021 S6).
+	*
+	* @param raw - octets tels que lus sur le transport.
+	* @param codec - le codec binaire du serveur.
+	* @returns le message à remettre au hub, ou `null` s'il est jeté.
+	*/
+	bytes(raw, codec) {
+		if (this.#echo.bytes(raw, codec)) {
+			this.#echoTotal += 1;
+			return null;
+		}
+		return this.#admit(openBackplaneEnvelopeBytes(raw, codec, this.#secret));
+	}
+	/** Échos de ce pod reçus du bus (monotone) — le bus rend ce qu'on y publie. */
+	get echoTotal() {
+		return this.#echoTotal;
+	}
+	/** Messages jetés au sceau refusé, sous un secret (monotone). */
+	get sealRejectedTotal() {
+		return this.#sealRejectedTotal;
+	}
+	/** Fin du tri commune aux deux sujets : refus compté, écho tardif, ou message admis. */
+	#admit(msg) {
+		if (msg === null) {
+			if (this.#secret !== null) this.#sealRejected();
+			return null;
+		}
+		if (msg.originId === this.#originId) {
+			this.#echoTotal += 1;
+			return null;
+		}
+		return msg;
+	}
+	/** Compte un sceau refusé ; annonce le premier, puis un sur cent (pas d'inondation du journal). */
+	#sealRejected() {
+		this.#sealRejectedTotal += 1;
+		const n = this.#sealRejectedTotal;
+		if (n !== 1 && n % 100 !== 0) return;
+		this.#notice?.(`backplane : ${n} message(s) reçu(s) au sceau refusé, JETÉS. Causes : rotation du secret en cours (des exemplaires n'ont pas le même NF_REALTIME_BACKPLANE_SECRET), producteur mal configuré, ou écriture tierce dans le bus. Compteur : sealRejectedTotal.`, "WARNING");
+	}
+};
+export { BackplaneIngress };

package/dist/nodefony/src/backplane/presenceMessage.js

@@ -0,0 +1,205 @@
+import { isBoundedBusText } from "./controlOrder.js";
+import { ownField } from "nodefony";
+// nodefony/src/backplane/presenceMessage.ts
+/**
+* Messages de la présence répartie entre serveurs — la LISTE FERMÉE de ce qui
+* circule sur `PLATFORM_BUS_CHANNELS.presence` (lots, demandes, réponses d'état)
+* et `PLATFORM_BUS_CHANNELS.presenceAlive` (preuve de vie), ADR-0025 P2.
+*
+* Comme un ordre de contrôle (`controlOrder.ts#readControlOrder`), chaque
+* message voyage dans la charge d'un message ordinaire du bus, sous le sceau de
+* l'enveloppe : aucun champ neuf dans l'enveloppe, aucune méthode neuve dans
+* `IBackplane`. L'émetteur (`originId`) se lit dans l'enveloppe, jamais dans la
+* charge.
+*
+* Lecture par champs PROPRES (`ownField`), textes bornés (`isBoundedBusText`),
+* entiers sûrs ; un champ inconnu est toléré (déploiement progressif), un champ
+* connu de forme fausse fait refuser le message entier. Les tableaux rendus
+* sont CEUX reçus, validés en place — aucune copie, aucune allocation par
+* membre : le lecteur ne les modifie pas, l'appelant non plus.
+*/
+/** Plus petit intervalle de preuve de vie qu'un pair peut annoncer (ms). */
+const MIN_PRESENCE_INTERVAL_MS = 100;
+/** Plus grand intervalle de preuve de vie qu'un pair peut annoncer (ms) — 10 min. */
+const MAX_PRESENCE_INTERVAL_MS = 6e5;
+/**
+* Plafond d'identités nommées qu'un pod peut annoncer pour UN canal — au-delà,
+* l'entrée est refusée (ADR-0025 P2, « plafond de membres par pod et par canal »).
+*/
+const MAX_PRESENCE_MEMBERS = 1e5;
+/** Plafond d'entrées de canal dans un même message (lot, demande ou part de réponse). */
+const MAX_PRESENCE_CHANNELS = 4096;
+/** Plafond de parts d'une réponse d'état (`n`). */
+const MAX_PRESENCE_PARTS = 4096;
+/** Entier sûr ≥ 0. */
+function isCount(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+/**
+* Paires à plat `[identité, onglets, …]` recevables : longueur paire, au plus
+* {@link MAX_PRESENCE_MEMBERS} identités, textes bornés, onglets entiers ≥ 1.
+* Un seul parcours, aucune allocation.
+*/
+function isPairs(value) {
+	if (!Array.isArray(value)) return false;
+	const length = value.length;
+	if ((length & 1) !== 0 || length > 2e5) return false;
+	for (let i = 0; i < length; i += 2) {
+		if (!isBoundedBusText(value[i])) return false;
+		const tabs = value[i + 1];
+		if (typeof tabs !== "number" || !Number.isSafeInteger(tabs) || tabs < 1) return false;
+	}
+	return true;
+}
+/** Liste de textes bornés d'au plus `max` éléments. */
+function isTextList(value, max) {
+	if (!Array.isArray(value) || value.length > max) return false;
+	for (let i = 0; i < value.length; i += 1) if (!isBoundedBusText(value[i])) return false;
+	return true;
+}
+/** Numéro de message recevable : entier sûr ≥ 1. */
+function isSeq(value) {
+	return isCount(value) && value >= 1;
+}
+/** Un champ « numéro précédent » (`prev`, `last`) : entier sûr ≥ 0, strictement sous `seq`. */
+function readBefore(payload, key, seq) {
+	const value = ownField(payload, key);
+	return isCount(value) && value < seq ? value : null;
+}
+function readDeltas(value) {
+	if (!Array.isArray(value) || value.length > 4096) return null;
+	const out = new Array(value.length);
+	for (let i = 0; i < value.length; i += 1) {
+		const entry = value[i];
+		const channel = ownField(entry, "channel");
+		const unnamed = ownField(entry, "unnamed");
+		if (!isBoundedBusText(channel) || !isCount(unnamed)) return null;
+		const set = ownField(entry, "set");
+		if (set !== void 0 && set !== null && !isPairs(set)) return null;
+		const gone = ownField(entry, "gone");
+		if (gone !== void 0 && gone !== null && !isTextList(gone, 1e5)) return null;
+		out[i] = {
+			channel,
+			set: set ?? null,
+			gone: gone ?? null,
+			unnamed
+		};
+	}
+	return out;
+}
+function readStates(value) {
+	if (!Array.isArray(value) || value.length > 4096) return null;
+	const out = new Array(value.length);
+	for (let i = 0; i < value.length; i += 1) {
+		const entry = value[i];
+		const channel = ownField(entry, "channel");
+		const unnamed = ownField(entry, "unnamed");
+		const members = ownField(entry, "members");
+		if (!isBoundedBusText(channel) || !isCount(unnamed) || !isPairs(members)) return null;
+		out[i] = {
+			channel,
+			members,
+			unnamed
+		};
+	}
+	return out;
+}
+/** Les types de message que cette version sait lire sur le canal de présence — liste fermée. */
+function isKnownOp(op) {
+	return op === "batch" || op === "request" || op === "state";
+}
+/**
+* Lit un message du canal de présence — `null` si sa forme n'est pas celle d'un message connu.
+*
+* Une seule garde pour les deux bords : l'émetteur la passe en test (il n'émet
+* jamais ce que ses pairs refuseraient), le récepteur avant d'appliquer.
+*
+* @param payload - la charge du message reçu (forme inconnue).
+* @returns le message, ou `null` (forme invalide, ou type inconnu : cf
+*   {@link isUnknownPresenceMessage} pour les distinguer).
+*/
+function readPresenceMessage(payload) {
+	const op = ownField(payload, "op");
+	if (!isKnownOp(op)) return null;
+	const incarnation = ownField(payload, "incarnation");
+	const seq = ownField(payload, "seq");
+	if (!isCount(incarnation) || !isSeq(seq)) return null;
+	const raw = ownField(payload, "channels");
+	if (op === "batch") {
+		const prev = readBefore(payload, "prev", seq);
+		if (prev === null) return null;
+		const channels = readDeltas(raw);
+		return channels === null ? null : {
+			op,
+			incarnation,
+			seq,
+			prev,
+			channels
+		};
+	}
+	if (op === "request") {
+		if (!isTextList(raw, 4096)) return null;
+		const to = ownField(payload, "to");
+		if (to !== void 0 && to !== null && !isBoundedBusText(to)) return null;
+		return {
+			op,
+			incarnation,
+			seq,
+			channels: raw,
+			to: to ?? null
+		};
+	}
+	const last = readBefore(payload, "last", seq);
+	const i = ownField(payload, "i");
+	const n = ownField(payload, "n");
+	if (last === null || !isCount(n) || n < 1 || n > 4096 || !isCount(i) || i >= n) return null;
+	const channels = readStates(raw);
+	return channels === null ? null : {
+		op,
+		incarnation,
+		seq,
+		last,
+		i,
+		n,
+		channels
+	};
+}
+/**
+* La charge est-elle un message de présence d'un TYPE que cette version ne connaît pas — `op` lisible, hors de la liste fermée ?
+*
+* C'est ce qu'émet un serveur plus récent pendant un déploiement progressif :
+* jeté et compté dans `ingressUnknownDiscardedTotal`, jamais comme une
+* injection (ADR-0025, « Règle de lecture du bus »).
+*
+* @param payload - la charge du message reçu (forme inconnue).
+*/
+function isUnknownPresenceMessage(payload) {
+	const op = ownField(payload, "op");
+	return isBoundedBusText(op) && !isKnownOp(op);
+}
+/**
+* Lit une preuve de vie — `null` si sa forme est fausse.
+*
+* `interval` hors de [{@link MIN_PRESENCE_INTERVAL_MS}, {@link MAX_PRESENCE_INTERVAL_MS}]
+* est refusé : un pair qui annoncerait 1 ms se ferait oublier à chaque tic, un
+* qui annoncerait une heure garderait ses fantômes une demi-journée.
+*
+* @param payload - la charge du message reçu (forme inconnue).
+*/
+function readPresenceAlive(payload) {
+	const incarnation = ownField(payload, "incarnation");
+	const seq = ownField(payload, "seq");
+	if (!isCount(incarnation) || !isSeq(seq)) return null;
+	const last = readBefore(payload, "last", seq);
+	const interval = ownField(payload, "interval");
+	const final = ownField(payload, "final");
+	if (last === null || !isCount(interval) || interval < 100 || interval > 6e5 || final !== void 0 && typeof final !== "boolean") return null;
+	return {
+		incarnation,
+		seq,
+		last,
+		interval,
+		final: final === true
+	};
+}
+export { MAX_PRESENCE_CHANNELS, MAX_PRESENCE_INTERVAL_MS, MAX_PRESENCE_MEMBERS, MAX_PRESENCE_PARTS, MIN_PRESENCE_INTERVAL_MS, isUnknownPresenceMessage, readPresenceAlive, readPresenceMessage };

package/dist/nodefony/src/backplane/publishQueue.js

@@ -1,4 +1,47 @@
 import { isThenable } from "../guards.js";
+import { PLATFORM_BUS_CHANNELS, isPriorityBusChannel } from "nodefony";
+// nodefony/src/backplane/publishQueue.ts
+/**
+* **File d'envoi bornée d'un backplane** — protège la mémoire du pod quand le bus
+* n'absorbe pas le débit publié. Mutualisée ici (comme le sceau d'enveloppe) pour
+* qu'un driver à transport réseau — Redis, et tout driver userland : NATS, Kafka,
+* RabbitMQ — hérite de la garantie sans la réécrire.
+*
+* Pourquoi : `IBackplane.publish` est **fire-and-forget** par contrat (il rend
+* `void`). Un client réseau met alors la commande dans SA file tant que la socket
+* n'est pas drainée — file interne, invisible, sans limite. Une rafale y accumule
+* des mégaoctets : 583 MB observés sur le banc multi-pods, pour 152 MB au repos.
+* Aucune fuite (tout redescend), mais rien ne borne le pic → OOM sous rafale plus
+* longue.
+*
+* Doctrine — la MÊME que le transport WS (seuil, compteur de jetés, avertissement),
+* parce que le problème est le même : un pair qui ne draine pas. Deux règles en
+* découlent :
+*  - **on protège la mémoire** : au-delà du seuil, les publications suivantes sont
+*    jetées (sémantique at-most-once déjà assumée par le port — le client realtime
+*    re-synchronise) ;
+*  - **on ne jette jamais en silence** : compteurs exposés dans la carte d'identité
+*    du backplane (donc sonde + Studio) et transitions annoncées.
+*    Cf `project_resilience_no_silent_degradation`.
+*
+* Ce qui est jeté est le message **nouveau**, pas le plus ancien : contrairement au
+* WS (drop latest-wins sur une file qu'on possède), ce qui est déjà remis au client
+* réseau ne peut plus être repris.
+*
+* **Les ordres de contrôle ne sont JAMAIS jetés** (#762) : terminer un canal ou
+* éjecter un compte passe hors quota, même file saturée. Sinon, sous charge, un
+* modérateur éjecte un compte sur un serveur et ce compte continue de lire sur un
+* autre, sans que personne le sache. Les ordres sont rares et petits (une décision
+* du serveur, quelques dizaines d'octets) : les exempter ne rouvre pas la mémoire.
+* La **preuve de vie** de la présence répartie passe aussi hors quota (ADR-0025
+* P2) : jetée, elle ferait oublier un pod vivant chez ses pairs ; elle est petite
+* et d'intervalle borné. Liste des canaux prioritaires : `isPriorityBusChannel`
+* (cœur), seule source.
+* Un ordre que le bus REFUSE malgré tout (bus injoignable) est compté à part
+* (`controlLostTotal`) et annoncé une fois par épisode.
+*/
+/** Canal des ordres de contrôle, lu une fois au chargement (pas d'accès de propriété par envoi). */
+const CONTROL_CHANNEL = PLATFORM_BUS_CHANNELS.control;
 /**
 * Seuil par défaut d'octets en vol vers le bus : **8 MiB**, aligné sur le seuil de
 * coupure d'un slow-consumer WS. Un bus sain acquitte en quelques millisecondes
@@ -23,6 +66,14 @@ var BackplanePublishQueue = class {
 	#saturated = false;
 	/** Jetés de l'épisode de saturation courant — chiffre annoncé au retour à la normale. */
 	#droppedInEpisode = 0;
+	/** Ordres de contrôle refusés par le transport (monotone). */
+	#controlLostTotal = 0;
+	/** Ordres perdus de l'épisode courant ; `> 0` = épisode ouvert (1 log par épisode). */
+	#controlLostInEpisode = 0;
+	/** Publications réseau en vol (un entier : le compte, pas les octets — un message vide compte). */
+	#inFlight = 0;
+	/** Attentes de {@link BackplanePublishQueue.settled} ; `null` tant que personne n'attend (arrêt seulement). */
+	#idle = null;
 	/**
 	* @param maxBytes - seuil d'octets en vol ; `0` (ou négatif) = illimité.
 	* @param notice - annonce des transitions ; omis = silencieux (tests unitaires).
@@ -39,13 +90,18 @@ var BackplanePublishQueue = class {
 	* (sinon elle ne partirait jamais — famine silencieuse), quitte à dépasser
 	* transitoirement. Même règle que le drop WS, qui teste `bufferedAmount` seul.
 	*
+	* Un canal prioritaire (`isPriorityBusChannel` du cœur : ordre de contrôle,
+	* preuve de vie de la présence) est admis hors quota : la file l'applique, pas
+	* le driver, pour qu'un driver qui emploie la file la porte sans y penser.
+	*
+	* @param channel - canal logique de la publication.
 	* @param bytes - taille de la charge sérialisée.
 	* @param emit - envoi réel ; appelé UNIQUEMENT si la publication est admise.
 	*   Son retour est suivi s'il s'agit d'une promesse (transport asynchrone).
 	* @returns `true` si la publication est partie, `false` si elle a été jetée.
 	*/
-	send(bytes, emit) {
-		if (this.#maxBytes > 0 && this.#bytes >= this.#maxBytes) {
+	send(channel, bytes, emit) {
+		if (this.#maxBytes > 0 && this.#bytes >= this.#maxBytes && !isPriorityBusChannel(channel)) {
 			this.#droppedTotal += 1;
 			this.#droppedInEpisode += 1;
 			if (!this.#saturated) {
@@ -57,10 +113,18 @@ var BackplanePublishQueue = class {
 		const result = emit();
 		if (!isThenable(result)) return true;
 		this.#bytes += bytes;
+		this.#inFlight += 1;
 		const settle = (failed) => {
 			this.#bytes -= bytes;
 			if (failed) this.#failedTotal += 1;
+			if ((failed || this.#controlLostInEpisode > 0) && channel === CONTROL_CHANNEL) this.#controlSettled(failed);
 			this.#drain();
+			this.#inFlight -= 1;
+			if (this.#inFlight === 0 && this.#idle !== null) {
+				const waiting = this.#idle;
+				this.#idle = null;
+				for (const resolve of waiting) resolve();
+			}
 		};
 		result.then(() => settle(false), () => settle(true));
 		return true;
@@ -79,13 +143,43 @@ var BackplanePublishQueue = class {
 		this.#droppedInEpisode = 0;
 		this.#notice?.(`backplane : file d'envoi drainée (${this.#bytes} octets en vol) — ${lost} publication(s) perdue(s) pendant la saturation.`, "INFO");
 	}
+	/**
+	* Suit l'acquittement d'un ordre de contrôle : un refus ouvre un épisode,
+	* annoncé une fois ; le premier ordre de nouveau acquitté le ferme, avec le
+	* bilan des pertes.
+	*/
+	#controlSettled(failed) {
+		if (failed) {
+			this.#controlLostTotal += 1;
+			this.#controlLostInEpisode += 1;
+			if (this.#controlLostInEpisode === 1) this.#notice?.("backplane : un ordre de contrôle (terminer un canal, éjecter un compte) a été REFUSÉ par le bus — les autres serveurs ne l'appliqueront pas. Cause : bus injoignable. Compteur : controlLostTotal.", "WARNING");
+			return;
+		}
+		if (this.#controlLostInEpisode === 0) return;
+		const lost = this.#controlLostInEpisode;
+		this.#controlLostInEpisode = 0;
+		this.#notice?.(`backplane : ordres de contrôle de nouveau acquittés — ${lost} ordre(s) perdu(s) pendant la coupure.`, "INFO");
+	}
+	/**
+	* Attend que toutes les publications en vol soient acquittées ou refusées par le bus — à l'arrêt, pour que ce qui est déjà émis (la preuve de vie finale de la présence) parte avant la sortie du processus.
+	*
+	* Ne borne rien : un bus qui ne répond plus ne la résout jamais. L'appelant
+	* pose la limite (l'arrêt du noyau a la sienne).
+	*/
+	settled() {
+		if (this.#inFlight === 0) return Promise.resolve();
+		return new Promise((resolve) => {
+			(this.#idle ??= []).push(resolve);
+		});
+	}
 	/** Compteurs pour la carte d'identité du backplane (sonde + Studio). */
 	describe() {
 		return {
 			bytes: this.#bytes,
 			maxBytes: this.#maxBytes,
 			droppedTotal: this.#droppedTotal,
-			failedTotal: this.#failedTotal
+			failedTotal: this.#failedTotal,
+			controlLostTotal: this.#controlLostTotal
 		};
 	}
 };

package/dist/nodefony/src/server/RealtimeConnection.js

@@ -15,26 +15,51 @@ var RealtimeConnection = class {
 	#host;
 	#identify;
 	#userId = null;
+	#account = false;
 	#open = true;
 	#imposing = null;
 	/**
 	* @param host - le contrôleur qui sert la connexion.
-	* @param identify - lit l'identifiant du compte, figé au handshake ; appelé
+	* @param identify - lit l'identité d'admission, figée au handshake ; appelé
 	*   au plus une fois.
 	*/
 	constructor(host, identify) {
 		this.#host = host;
 		this.#identify = identify;
 	}
+	/** Lit l'identité au premier besoin, une fois. */
+	#resolveIdentity() {
+		const identify = this.#identify;
+		if (identify === null) return;
+		this.#identify = null;
+		const identity = identify();
+		this.#userId = identity?.id ?? null;
+		this.#account = identity?.account === true;
+	}
 	/** Identifiant du compte connecté ; `null` pour l'anonyme. */
 	get userId() {
-		const identify = this.#identify;
-		if (identify !== null) {
-			this.#identify = null;
-			this.#userId = identify();
-		}
+		this.#resolveIdentity();
 		return this.#userId;
 	}
+	/**
+	* `userId` désigne-t-il un compte LOCAL ? `false` pour l'anonyme et l'appelant
+	* machine sans compte (`<émetteur>#<sujet>`) — ceux que la présence compte sans
+	* les nommer (ADR-0025 P3).
+	*/
+	get account() {
+		this.#resolveIdentity();
+		return this.#account;
+	}
+	/**
+	* Écrit une trame PARTAGÉE (encodée une fois par codec) sur cette connexion — rien si la socket est fermée.
+	*
+	* Voie des notifications du protocole qui visent les membres d'un canal (la
+	* présence) : elles ne passent pas par le sink du canal, qui les livrerait
+	* sous le nom du canal.
+	*/
+	deliver(frame) {
+		if (this.#open) this.#host.send(frame);
+	}
 	/** `false` une fois la socket fermée. */
 	get open() {
 		return this.#open;