@nodefony/realtime 10.0.0-alpha.1

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

@@ -0,0 +1,109 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+//#region nodefony/src/backplane/envelope.ts
+/**
+* **Sceau d'enveloppe backplane** — authenticité des messages transportés sur un
+* bus **PARTAGÉ** (Redis pub/sub, et tout driver userland cross-host : NATS,
+* RabbitMQ…). Mutualisé ici pour qu'un driver tiers hérite de la même garantie
+* sans la réécrire (F83).
+*
+* Pourquoi : un bus partagé n'authentifie pas l'ÉMETTEUR d'un message. Sans sceau,
+* quiconque écrit dans le Redis (autre app d'un Redis mutualisé, credential fuité,
+* SSRF vers le port Redis) publie sur les canaux de **tous** les pods de l'app.
+* Le sceau prouve que le message vient d'un pair qui détient le secret partagé.
+*
+* Ce qui NE s'applique PAS ici : le {@link ClusterBackplane} (IPC). Son transport
+* est authentifié par construction — un canal IPC ne relie qu'un master à SES
+* propres workers, il n'existe aucun tiers capable d'y écrire. Y imposer un secret
+* serait de la friction pure.
+*
+* Algorithme : HMAC-SHA256 sur la **chaîne canonique** `originId\nchannel\npayload`
+* (payload sérialisé), encodé en base64url. Comparaison à temps constant
+* ({@link timingSafeEqual}) — une comparaison `===` fuiterait le sceau attendu
+* octet par octet.
+*
+* Portée : le sceau couvre l'origine, le canal ET la charge → ni repointage de
+* canal (`chat:` → `nodefony:audit`), ni substitution de charge.
+*
+* Hors portée (assumé, cf sémantique at-most-once du port) : le **rejeu**. Un
+* tiers qui lit le bus peut re-publier un message scellé intact ; l'effet se
+* limite à re-diffuser une charge déjà diffusée sur un canal déjà broadcast, que
+* le client realtime re-synchronise. Un anti-rejeu (horodatage + fenêtre) exigerait
+* des horloges alignées entre pods pour un gain nul face à ce modèle de menace.
+*/
+/** Nom du champ portant le sceau dans l'enveloppe sérialisée. */
+const SEAL_FIELD = "sig";
+/**
+* Sceau HMAC-SHA256 (base64url) d'un triplet **déjà sérialisé**. Le `\n` sépare
+* trois fragments JSON : les deux premiers sont des chaînes échappées, donc
+* aucun décalage de frontière n'est possible entre les parties.
+*
+* Prend les fragments et non le message : la charge n'est sérialisée **qu'une
+* fois** par publication (elle sert et au sceau et à l'enveloppe finale) — sur
+* un canal de fan-out, une seconde sérialisation par message se paierait à
+* chaque diffusion.
+*/
+function seal(originIdJson, channelJson, payloadJson, secret) {
+	return createHmac("sha256", secret).update(`${originIdJson}\n${channelJson}\n${payloadJson}`).digest("base64url");
+}
+/**
+* Sérialise un message backplane, scellé si un secret est fourni.
+*
+* L'enveloppe scellée est assemblée par concaténation des fragments déjà
+* sérialisés — un `JSON.stringify` d'objet complet re-sérialiserait la charge
+* une seconde fois.
+*
+* @param msg - message à transporter (canal, charge, origine).
+* @param secret - secret partagé entre pods ; `null`/`undefined` → enveloppe nue.
+* @returns la chaîne à publier sur le bus.
+*/
+function sealBackplaneEnvelope(msg, secret) {
+	if (!secret) return JSON.stringify(msg);
+	const channelJson = JSON.stringify(msg.channel);
+	const originIdJson = JSON.stringify(msg.originId);
+	const payloadJson = JSON.stringify(msg.payload) ?? "null";
+	const sig = seal(originIdJson, channelJson, payloadJson, secret);
+	return `{"channel":${channelJson},"payload":${payloadJson},"originId":${originIdJson},"${SEAL_FIELD}":"${sig}"}`;
+}
+/** Type-guard d'enveloppe — narrowing sûr d'un message brut venu du bus. */
+function isEnvelope(m) {
+	if (typeof m !== "object" || m === null) return false;
+	const e = m;
+	return typeof e.channel === "string" && typeof e.originId === "string";
+}
+/**
+* Parse et **vérifie** une enveloppe reçue du bus partagé.
+*
+* Fail-closed strict quand un secret est posé : une enveloppe sans sceau ou au
+* sceau invalide est rejetée — **aucun downgrade** possible en retirant le champ
+* `sig`. Sans secret, l'enveloppe nue est acceptée (compat ; l'alerte de boot qui
+* signale ce mode non authentifié est portée par le wiring du driver).
+*
+* @param raw - message brut lu sur le bus.
+* @param secret - secret partagé attendu, ou `null`/`undefined` si aucun.
+* @returns le message vérifié, ou `null` s'il doit être ignoré (malformé, non
+*   scellé alors qu'un secret est exigé, sceau invalide).
+*/
+function openBackplaneEnvelope(raw, secret) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return null;
+	}
+	if (!isEnvelope(parsed)) return null;
+	const msg = {
+		channel: parsed.channel,
+		payload: parsed.payload,
+		originId: parsed.originId
+	};
+	if (!secret) return msg;
+	const provided = parsed[SEAL_FIELD];
+	if (typeof provided !== "string") return null;
+	const expected = seal(JSON.stringify(msg.originId), JSON.stringify(msg.channel), JSON.stringify(msg.payload) ?? "null", secret);
+	const a = Buffer.from(provided, "base64url");
+	const b = Buffer.from(expected, "base64url");
+	if (a.length !== b.length || !timingSafeEqual(a, b)) return null;
+	return msg;
+}
+//#endregion
+export { openBackplaneEnvelope, sealBackplaneEnvelope };

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

@@ -0,0 +1,35 @@
+import { hostname } from "node:os";
+import { randomUUID } from "node:crypto";
+//#region nodefony/src/backplane/originId.ts
+/**
+* Résout l'identifiant d'origine d'un backplane — l'étiquette que l'anti-écho
+* compare pour jeter les messages qui reviennent à leur émetteur.
+*
+* POURQUOI pas `String(process.pid)` (ex-défaut) : en conteneur, le namespace
+* PID est PAR conteneur → deux pods k8s peuvent tous deux être PID 1. Avec un
+* backplane cross-pod (Redis/Kafka), l'anti-écho confond alors les pods et
+* jette SILENCIEUSEMENT le fan-out légitime (dette 🔴 #2 du module).
+*
+* Résolution (du plus explicite au filet) :
+*  1. `NF_POD_NAME` (downward API k8s, opt-in opérateur) ;
+*  2. `os.hostname()` — en k8s = nom du pod (unique), en docker = id court du
+*     conteneur (unique), en bare-metal = nom de machine ;
+*  3. suffixe `:pid` TOUJOURS ajouté : distingue les workers d'un même host
+*     (cluster bare-metal `-w N` + driver redis = même hostname, pids ≠) ;
+*  4. hostname indisponible/vide (exotique) → `randomUUID()` (l'anti-écho n'a
+*     pas besoin de stabilité entre restarts, seulement d'unicité à l'instant t).
+*
+* Évalué à la CONSTRUCTION du backplane (boot) — 0 coût par message.
+*/
+function resolveBackplaneOriginId() {
+	let host = process.env.NF_POD_NAME;
+	if (!host) try {
+		host = hostname();
+	} catch {
+		host = "";
+	}
+	if (!host) return randomUUID();
+	return `${host}:${process.pid}`;
+}
+//#endregion
+export { resolveBackplaneOriginId as default, resolveBackplaneOriginId };

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

@@ -0,0 +1,96 @@
+/**
+* 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
+* (3 ms mesurés cross-pod) : 8 MiB d'arriéré, c'est déjà trois ordres de grandeur
+* au-dessus du régime nominal — le pod a un problème bien avant d'y arriver.
+*/
+const DEFAULT_MAX_QUEUE_BYTES = 1 << 23;
+/** Vrai si la valeur se comporte comme une promesse (transport asynchrone). */
+function isThenable(v) {
+	return typeof v === "object" && v !== null && typeof v.then === "function";
+}
+/**
+* File d'envoi bornée : décide d'admettre ou de jeter une publication, puis suit
+* son acquittement pour rendre la place.
+*
+* Un transport **synchrone** (bus mémoire des tests, IPC) ne rend pas de promesse :
+* il n'a donc pas de file, la garde reste alors inerte et ne jette jamais rien.
+*/
+var BackplanePublishQueue = class {
+	#maxBytes;
+	#notice;
+	#bytes = 0;
+	#droppedTotal = 0;
+	#failedTotal = 0;
+	/** Vrai entre le franchissement du seuil et le retour à la normale (1 log par épisode). */
+	#saturated = false;
+	/** Jetés de l'épisode de saturation courant — chiffre annoncé au retour à la normale. */
+	#droppedInEpisode = 0;
+	/**
+	* @param maxBytes - seuil d'octets en vol ; `0` (ou négatif) = illimité.
+	* @param notice - annonce des transitions ; omis = silencieux (tests unitaires).
+	*/
+	constructor(maxBytes = DEFAULT_MAX_QUEUE_BYTES, notice = null) {
+		this.#maxBytes = maxBytes > 0 ? maxBytes : 0;
+		this.#notice = notice;
+	}
+	/**
+	* Admet ou jette une publication, et suit son acquittement.
+	*
+	* L'admission regarde l'état de la file **avant** l'envoi, pas la taille du
+	* message : une charge plus grosse que le seuil part quand la file est vide
+	* (sinon elle ne partirait jamais — famine silencieuse), quitte à dépasser
+	* transitoirement. Même règle que le drop WS, qui teste `bufferedAmount` seul.
+	*
+	* @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) {
+			this.#droppedTotal += 1;
+			this.#droppedInEpisode += 1;
+			if (!this.#saturated) {
+				this.#saturated = true;
+				this.#notice?.(`backplane : file d'envoi saturée (${this.#bytes} octets en vol ≥ seuil ${this.#maxBytes}) — publications JETÉES tant que le bus ne draine pas. Le fan-out cross-pod est incomplet. Causes : bus lent ou injoignable, débit publié trop élevé. Levier : backplane.maxQueueBytes.`, "WARNING");
+			}
+			return false;
+		}
+		const result = emit();
+		if (!isThenable(result)) return true;
+		this.#bytes += bytes;
+		const settle = (failed) => {
+			this.#bytes -= bytes;
+			if (failed) this.#failedTotal += 1;
+			this.#drain();
+		};
+		result.then(() => settle(false), () => settle(true));
+		return true;
+	}
+	/**
+	* Retour à la normale — annoncé une seule fois, avec le bilan des pertes.
+	*
+	* Hystérésis à la moitié du seuil : repasser sous le seuil tout court ferait
+	* osciller l'état (et les logs) à chaque acquittement en régime saturé.
+	*/
+	#drain() {
+		if (!this.#saturated) return;
+		if (this.#maxBytes > 0 && this.#bytes * 2 > this.#maxBytes) return;
+		const lost = this.#droppedInEpisode;
+		this.#saturated = false;
+		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");
+	}
+	/** Compteurs pour la carte d'identité du backplane (sonde + Studio). */
+	describe() {
+		return {
+			bytes: this.#bytes,
+			maxBytes: this.#maxBytes,
+			droppedTotal: this.#droppedTotal,
+			failedTotal: this.#failedTotal
+		};
+	}
+};
+//#endregion
+export { BackplanePublishQueue, BackplanePublishQueue as default, DEFAULT_MAX_QUEUE_BYTES };

package/dist/nodefony/src/cluster/ClusterProbeClient.js

@@ -0,0 +1,284 @@
+import { CLUSTER_PROBE_CTL_KIND, CLUSTER_PROBE_KIND, CLUSTER_PROBE_SNAPSHOT_KIND, RichProcessProbe, isClusterMessage, isClusterProbeEnrich, readOrmRich } from "nodefony";
+//#region nodefony/src/cluster/ClusterProbeClient.ts
+/** Transport de production : `process.send` + `process.on("message")`. */
+const processProbeTransport = {
+	send(report) {
+		process.send?.(report);
+	},
+	onReceive(cb) {
+		process.on("message", (msg) => cb(msg));
+	}
+};
+/**
+* Consolide N santés per-instance en une vue **POD** ({@link IRealtimeClusterHealth}).
+* Pur (aucune I/O) : somme les scalaires ; la backpressure `maxBufferedAmount` est un MAX
+* (le pire worker), `totalBufferedAmount`/`slowConsumers` des sommes.
+*
+* @param instances - santés per-instance (chaque worker, snapshot master).
+* @param ts - horodatage du snapshot (défaut maintenant).
+*/
+function mergeClusterHealth(instances, ts = Date.now()) {
+	const totals = {
+		channelCount: 0,
+		publishTotal: 0,
+		fanoutTotal: 0,
+		inboundTotal: 0,
+		ingressRejectedTotal: 0,
+		connectionCount: 0,
+		bytesSentTotal: 0,
+		messagesSentTotal: 0,
+		backpressure: {
+			maxBufferedAmount: 0,
+			totalBufferedAmount: 0,
+			slowConsumers: 0,
+			drops: 0
+		}
+	};
+	let orm;
+	let errors;
+	for (const h of instances) {
+		totals.channelCount += h.channelCount;
+		totals.publishTotal += h.publishTotal;
+		totals.fanoutTotal += h.fanoutTotal;
+		totals.inboundTotal += h.inboundTotal;
+		totals.ingressRejectedTotal += h.ingressRejectedTotal;
+		totals.connectionCount += h.connectionCount;
+		totals.bytesSentTotal += h.bytesSentTotal;
+		totals.messagesSentTotal += h.messagesSentTotal;
+		const bp = h.backpressure;
+		if (bp.maxBufferedAmount > totals.backpressure.maxBufferedAmount) totals.backpressure.maxBufferedAmount = bp.maxBufferedAmount;
+		totals.backpressure.totalBufferedAmount += bp.totalBufferedAmount;
+		totals.backpressure.slowConsumers += bp.slowConsumers;
+		totals.backpressure.drops += bp.drops;
+		if (h.orm) {
+			orm ??= {
+				connectors: 0,
+				connected: 0,
+				queryTotal: 0,
+				slowTotal: 0,
+				errorTotal: 0,
+				reconnectTotal: 0,
+				maxEwmaMs: null,
+				assumed: 0
+			};
+			orm.connectors += h.orm.connectors;
+			orm.connected += h.orm.connected;
+			orm.assumed += h.orm.assumed;
+			orm.queryTotal += h.orm.queryTotal;
+			orm.slowTotal += h.orm.slowTotal;
+			orm.errorTotal += h.orm.errorTotal;
+			orm.reconnectTotal += h.orm.reconnectTotal;
+			if (h.orm.maxEwmaMs !== null && (orm.maxEwmaMs === null || h.orm.maxEwmaMs > orm.maxEwmaMs)) orm.maxEwmaMs = h.orm.maxEwmaMs;
+		}
+		if (h.errors) {
+			errors ??= {
+				errorTotal: 0,
+				criticTotal: 0
+			};
+			errors.errorTotal += h.errors.errorTotal;
+			errors.criticTotal += h.errors.criticTotal;
+		}
+	}
+	if (orm) totals.orm = orm;
+	if (errors) totals.errors = errors;
+	return {
+		cluster: true,
+		ts,
+		instanceCount: instances.length,
+		instances,
+		totals
+	};
+}
+/**
+* Client de sonde cluster **côté worker** (Phase 4c) — le pendant de
+* {@link ClusterProbeAggregator} (master). Deux rôles :
+*  - **report** : envoie périodiquement sa santé per-instance au master (`CLUSTER_PROBE_KIND`) ;
+*  - **cache** : reçoit le snapshot agrégé du master (`CLUSTER_PROBE_SNAPSHOT_KIND`) et le garde
+*    → n'importe quel worker sert la vue POD en O(1) (modèle push : 0 latence de requête).
+*
+* **Bypass total quand désactivé** : ce client n'est instancié/`start()` QUE par le module
+* Framework en worker de cluster AVEC la sonde activée. Sinon (mono-process, ou sonde coupée)
+* il n'existe pas → aucun timer, aucun listener, aucun IPC, et {@link clusterProbeHealth}
+* renvoie `null` → l'endpoint santé retombe sur la vue per-instance. Aucun coût « au cas où ».
+*
+* Perf : 1 timer `unref` (report) + 1 listener IPC. Le report sérialise 1 santé / intervalle
+* (≥ 1 s, jamais hot path). SERVEUR uniquement.
+*/
+var ClusterProbeClient = class {
+	#transport;
+	#intervalMs;
+	#lastInstances = null;
+	#snapTs = 0;
+	#timer = null;
+	#started = false;
+	#richProbe = null;
+	#richEnabled = false;
+	#ormRich = null;
+	#ormRichTimer = null;
+	#ormRichEnabled = false;
+	constructor(transport = processProbeTransport, intervalMs = 2e3) {
+		this.#transport = transport;
+		this.#intervalMs = intervalMs;
+	}
+	/**
+	* Démarre le report périodique + l'écoute des snapshots. Idempotent. 1ᵉʳ report immédiat.
+	*
+	* @param buildOwn - fournit la santé per-instance courante (capturée à chaque tick).
+	*/
+	start(buildOwn) {
+		if (this.#started) return;
+		this.#started = true;
+		this.#transport.onReceive((msg) => this.#ingest(msg));
+		this.#report(buildOwn);
+		this.#timer = setInterval(() => this.#report(buildOwn), this.#intervalMs);
+		this.#timer.unref?.();
+	}
+	#report(buildOwn) {
+		const payload = buildOwn();
+		if (this.#richEnabled) {
+			if (this.#richProbe === null) this.#richProbe = new RichProcessProbe();
+			payload.rich = this.#richProbe.read();
+		}
+		if (this.#ormRich !== null) payload.ormRich = this.#ormRich;
+		this.#transport.send({
+			kind: CLUSTER_PROBE_KIND,
+			payload
+		});
+	}
+	/**
+	* Démarre le rafraîchissement périodique du blob ORM riche (facette `"orm"`). Idempotent.
+	* Le `connection/health` étant ASYNC (ping), on ne peut pas le lire dans le report sync :
+	* un ticker `unref` met à jour le cache `#ormRich`, que le report joint ensuite. 1ᵉʳ fetch
+	* immédiat. No-op si aucun driver n'a branché `setOrmRichProvider` (`readOrmRich() === null`).
+	*/
+	#startOrmRich() {
+		if (this.#ormRichTimer !== null) return;
+		const refresh = () => {
+			const p = readOrmRich();
+			if (p === null) {
+				this.#ormRich = null;
+				return;
+			}
+			p.then((r) => {
+				if (this.#ormRichEnabled) this.#ormRich = r;
+			}).catch(() => {});
+		};
+		refresh();
+		this.#ormRichTimer = setInterval(refresh, this.#intervalMs);
+		this.#ormRichTimer.unref?.();
+	}
+	/** Arrête le rafraîchissement ORM riche et purge le cache. Idempotent. */
+	#stopOrmRich() {
+		if (this.#ormRichTimer !== null) {
+			clearInterval(this.#ormRichTimer);
+			this.#ormRichTimer = null;
+		}
+		this.#ormRich = null;
+	}
+	/**
+	* Demande au master d'(arrêter d')enrichir le worker `pid` sur une **facette** (drill-down).
+	* Émis par le worker qui tient la connexion navigateur quand un client subscribe/unsubscribe
+	* le canal `nodefony:supervision@<pid>` (facette `"process"`) ou `nodefony:orm:rich@<pid>` (facette
+	* `"orm"`). No-op hors cluster (`send` no-op).
+	*
+	* @param pid - worker ciblé (identité de la vue pod).
+	* @param enable - `true` = activer la sonde riche sur ce worker, `false` = la couper.
+	* @param facet - quelle sonde riche cibler (défaut `"process"`).
+	*/
+	requestEnrich(pid, enable, facet = "process") {
+		this.#transport.send({
+			kind: CLUSTER_PROBE_CTL_KIND,
+			op: enable ? "enrich" : "stop",
+			pid,
+			facet
+		});
+	}
+	/**
+	* Met en cache le dernier snapshot agrégé, OU applique un ordre d'enrichissement ciblé
+	* du master (`nf:probe:enrich`). Ignore les autres kinds + malformés.
+	*/
+	#ingest(msg) {
+		if (isClusterProbeEnrich(msg)) {
+			if ((msg.facet ?? "process") === "orm") {
+				this.#ormRichEnabled = msg.enabled;
+				if (msg.enabled) this.#startOrmRich();
+				else this.#stopOrmRich();
+				return;
+			}
+			this.#richEnabled = msg.enabled;
+			if (!msg.enabled && this.#richProbe !== null) {
+				this.#richProbe.disable();
+				this.#richProbe = null;
+			}
+			return;
+		}
+		if (!isClusterMessage(msg) || msg.kind !== CLUSTER_PROBE_SNAPSHOT_KIND) return;
+		const snap = msg;
+		if (Array.isArray(snap.instances)) {
+			this.#lastInstances = snap.instances;
+			this.#snapTs = typeof snap.ts === "number" ? snap.ts : Date.now();
+		}
+	}
+	/** Vue POD agrégée, ou `null` tant qu'aucun snapshot n'est reçu (cold start). */
+	getClusterHealth() {
+		if (this.#lastInstances === null) return null;
+		return mergeClusterHealth(this.#lastInstances, this.#snapTs);
+	}
+	/** Arrête le report et purge le cache. Idempotent. Libère la sonde riche (drill). */
+	stop() {
+		if (this.#timer !== null) {
+			clearInterval(this.#timer);
+			this.#timer = null;
+		}
+		this.#started = false;
+		this.#lastInstances = null;
+		this.#richEnabled = false;
+		if (this.#richProbe !== null) {
+			this.#richProbe.disable();
+			this.#richProbe = null;
+		}
+		this.#ormRichEnabled = false;
+		this.#stopOrmRich();
+	}
+};
+let _client = null;
+/** Branche le client de sonde cluster du process (worker). Remplace un éventuel précédent. */
+function setClusterProbeClient(client) {
+	_client = client;
+	return client;
+}
+/**
+* Vue POD agrégée si la sonde cluster est branchée ET a reçu un snapshot, sinon `null`.
+* `null` ⇒ l'endpoint santé sert la vue per-instance (mono-process / sonde désactivée /
+* cold start). Lecture pure, jamais throw.
+*/
+function clusterProbeHealth() {
+	return _client?.getClusterHealth() ?? null;
+}
+/**
+* Demande au master d'(arrêter d')enrichir le worker `pid` sur une **facette** (drill-down
+* Phase 2). Facettes indépendantes : `"process"` (supervision) et `"orm"` (drill ORM).
+*
+* @param pid - worker ciblé.
+* @param enable - activer/couper la sonde riche.
+* @param facet - quelle sonde riche cibler (défaut `"process"`).
+* @returns `true` si la sonde cluster est branchée (worker de cluster) → l'ordre est émis ;
+*   `false` en mono-process / sonde désactivée (pas de drill cross-worker possible → le
+*   consommateur retombe sur la sonde riche locale du process courant).
+*/
+function clusterProbeRequestEnrich(pid, enable, facet = "process") {
+	if (_client === null) return false;
+	_client.requestEnrich(pid, enable, facet);
+	return true;
+}
+/**
+* Santé d'UN worker `pid` extraite du dernier snapshot pod (avec sa sonde riche si le
+* drill est actif), ou `null` (mono-process, pid inconnu, ou cold start). Lecture pure.
+*/
+function clusterProbeInstance(pid) {
+	const health = _client?.getClusterHealth();
+	if (!health) return null;
+	return health.instances.find((i) => i.process?.pid === pid || i.instanceId === String(pid)) ?? null;
+}
+//#endregion
+export { ClusterProbeClient, ClusterProbeClient as default, clusterProbeHealth, clusterProbeInstance, clusterProbeRequestEnrich, mergeClusterHealth, processProbeTransport, setClusterProbeClient };

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

@@ -0,0 +1,35 @@
+//#region nodefony/src/server/AnonymousRealtimeToken.ts
+/**
+* Token realtime ANONYME — fallback Zero Trust quand aucun matcher
+* `IRealtimeAuthenticatorMatcher` ne capture le handshake.
+*
+* Singleton gelé (`Object.freeze`) — 0 alloc par connexion non authentifiée.
+* Aligné sur le pattern `AnonymousToken` de `@nodefony/security` S1 (même
+* surface logique, type `"anonymous"`, `roles = ["ROLE_ANONYMOUS"]`).
+*
+* Stocké par le hub sur la map `peer → token` au handshake si aucun
+* authenticator ne capture la connexion. Les voters P6 (futur) verront un
+* token avec `isAuthenticated() === false` et appliqueront leur politique
+* (Zero Trust : zone protégée → frame refusée par `beforeDispatch`).
+*/
+const anonymousAttributes = Object.freeze({});
+const ANONYMOUS_REALTIME_TOKEN = Object.freeze({
+	type: "anonymous",
+	getUserIdentifier() {
+		return "anonymous";
+	},
+	isAuthenticated() {
+		return false;
+	},
+	getRoles() {
+		return ["ROLE_ANONYMOUS"];
+	},
+	getScopes() {
+		return [];
+	},
+	getAttribute(key) {
+		return anonymousAttributes[key];
+	}
+});
+//#endregion
+export { ANONYMOUS_REALTIME_TOKEN, ANONYMOUS_REALTIME_TOKEN as default };

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

@@ -0,0 +1,87 @@
+import { getRealtimeHub } from "./RealtimeHub.js";
+import { listBackplaneDrivers } from "../backplane/backplaneRegistry.js";
+import { clusterProbeHealth } from "../cluster/ClusterProbeClient.js";
+import { Nodefony, ProcessProbe, readOrmHealth } from "nodefony";
+//#region nodefony/src/server/RealtimeAdminApi.ts
+const processProbe = new ProcessProbe();
+/**
+* Producteur `IAdminApi` de la **socket Nodefony** — exposé sous
+* `/nodefony/realtime/api/*`. Surface l'**auto-observabilité** du {@link RealtimeHub}
+* (la socket s'observe à travers elle-même) : canaux, fan-out, connexions et surtout
+* **backpressure** (`bufferedAmount` = blocker mémoire #1 du multiplexing N canaux/1 WS).
+*
+* Namespace `realtime` (pas `studio`/`framework`) car la socket est une couche du
+* framework, pas de Studio : le jour où `@nodefony/realtime` (P13.1) existera, ce
+* producteur y déménagera sans changer le contrat. Réutilisé par l'endpoint HTTP
+* (1ᵉʳ paint) ET par le ticker hub realtime `nodefony:socket` (push live).
+*
+* Endpoints :
+*  - `GET /nodefony/realtime/api/health` → vue POD agrégée ({@link IRealtimeClusterHealth})
+*    en cluster avec sonde active, sinon snapshot per-instance ({@link IRealtimeHealth}).
+*/
+/**
+* Santé per-instance de CE worker : lecture pure du hub ({@link RealtimeHub.probe}) +
+* identité process. Aucune I/O, jamais throw. C'est ce que chaque worker **remonte** au
+* master (Phase 4c) et le fallback quand il n'y a pas d'agrégat.
+*/
+/**
+* Compteurs d'erreurs Syslog du worker (cumuls monotones), ou `undefined` si le kernel/son
+* syslog n'est pas joignable. Lecture pure de 2 entiers (0 scan du ring buffer).
+*/
+function readInstanceErrorHealth() {
+	const syslog = Nodefony.getKernel()?.syslog;
+	if (!syslog) return void 0;
+	return {
+		errorTotal: syslog.errorTotal,
+		criticTotal: syslog.criticTotal
+	};
+}
+function buildOwnHealth() {
+	const health = {
+		instanceId: String(process.pid),
+		...getRealtimeHub().probe(),
+		process: processProbe.read()
+	};
+	const orm = readOrmHealth();
+	if (orm) health.orm = orm;
+	const errors = readInstanceErrorHealth();
+	if (errors) health.errors = errors;
+	const drivers = listBackplaneDrivers();
+	if (drivers.length) health.backplaneDrivers = drivers;
+	return health;
+}
+/**
+* Construit la **santé de la socket** servie par l'endpoint/le canal `nodefony:socket` :
+* la **vue POD agrégée** si la sonde cluster est branchée et a reçu un snapshot du master
+* (Phase 4c, push), sinon la **vue per-instance** (mono-process, sonde désactivée, ou cold
+* start). Lecture pure, jamais throw. Async pour matcher la signature des tickers broker.
+*
+* @returns {@link IRealtimeClusterHealth} (cluster) ou {@link IRealtimeHealth} (per-instance).
+*/
+async function buildRealtimeHealth() {
+	return clusterProbeHealth() ?? buildOwnHealth();
+}
+const descriptor = {
+	label: "Realtime",
+	icon: "wifi",
+	order: 3
+};
+/**
+* Construit le producteur `IAdminApi` de la socket (namespace `"realtime"`).
+*
+* @returns le contrat admin, prêt à `broker.register()`.
+*/
+function createRealtimeAdminApi() {
+	const endpoints = [{
+		path: "health",
+		summary: "Santé de la socket (per-instance) — canaux + abonnés, fan-out (publish/livraisons), connexions, octets/frames, backpressure (bufferedAmount max/total, slow-consumers).",
+		handler: () => buildRealtimeHealth()
+	}];
+	return {
+		adminNamespace: "realtime",
+		adminDescriptor: () => descriptor,
+		adminEndpoints: () => endpoints
+	};
+}
+//#endregion
+export { buildOwnHealth, buildRealtimeHealth, createRealtimeAdminApi };