@nodefony/realtime 10.0.0-alpha.1

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

@@ -0,0 +1,926 @@
+import { LoopbackBackplane } from "../backplane/LoopbackBackplane.js";
+import { ANONYMOUS_REALTIME_TOKEN } from "./AnonymousRealtimeToken.js";
+import { NODEFONY_CHANNEL_NAMESPACE, isPlatformChannel } from "nodefony";
+//#region nodefony/src/server/RealtimeHub.ts
+/**
+* Seuil d'alerte slow-consumer (octets de `bufferedAmount`). Au-delà, la connexion
+* est comptée comme « lente » par la sonde (PAS encore de drop/close — la sonde MESURE
+* avant qu'on optimise : stringify unique → seuil de drop → coalescing). 1 MiB =
+* `websocket.maxPayload` par défaut : une file qui dépasse une frame max pleine est
+* déjà anormale pour des canaux d'ÉTAT (latest-wins).
+*/
+const SLOW_CONSUMER_BYTES = 1 << 20;
+/**
+* **Namespace de canaux RÉSERVÉ À LA PLATEFORME** — un seul préfixe, `nodefony:`.
+*
+* Les canaux qu'il couvre exposent l'état interne du pod : journaux, requêtes de
+* base, métriques process, supervision, contrôle du noyau, journal d'audit. Aucun
+* n'appartient au métier d'une application — ils décrivent le serveur lui-même.
+*
+* La liste reste exposée **ici** (au pluriel, sous forme de tableau) parce que le hub
+* est propriétaire de l'espace de nommage des canaux : c'est lui qui les sert.
+* `@nodefony/security`, quand il est chargé, y attache des POLITIQUES (quels rôles)
+* qu'il lit sur cette liste via la surface de service — il ne la redéclare pas. Deux
+* listes auraient divergé au premier namespace ajouté. Le tableau survit à la
+* réduction à une entrée : la forme est un contrat public (`reservedSystemPrefixes()`),
+* et rien n'interdit qu'un jour un second namespace de plateforme apparaisse.
+*
+* Le nom des canaux, lui, vient de la table `PLATFORM_CHANNELS` du cœur (isomorphe) :
+* le navigateur doit connaître les mêmes noms que le serveur.
+*
+* Sans module de sécurité, ces canaux sont **fermés** aux connexions clientes
+* (cf {@link RealtimeHub.subscribeClient}) : aucune identité n'existe alors, donc
+* personne ne peut prouver qu'il a le droit de les lire.
+*/
+const RESERVED_SYSTEM_PREFIXES = [NODEFONY_CHANNEL_NAMESPACE];
+/**
+* Le canal appartient-il au namespace réservé à la plateforme ?
+*
+* Alias de {@link isPlatformChannel} (cœur isomorphe) sous le nom que porte cette
+* notion côté hub : le hub raisonne en « canal réservé », le client en « surface de
+* plateforme ». Une seule implémentation — la comparaison est insensible à la casse,
+* sinon `NODEFONY:syslog` échapperait au plancher que `nodefony:syslog` subit.
+*
+* @param channel - nom du canal demandé (suffixes de cadence et de forage inclus).
+*/
+const isReservedSystemChannel = isPlatformChannel;
+/**
+* Période de re-validation des identités RÉVOCABLES — F4 (revue 0.6).
+* Le verrou de frame est SYNC par doctrine (identité figée au handshake, cf
+* {@link FrameAuthorizer}) → il ne peut pas re-lire la session par frame. Un socket
+* survivrait donc à sa session (`subscribe` garderait ses flux après un logout HTTP),
+* là où `api.request` re-valide déjà par requête (`isValid()`). Ce tick ferme
+* l'écart : toutes les `REVOCATION_REVALIDATE_MS`, les tokens révocables sont
+* re-validés et la connexion fermée si l'identité n'est plus valide (≤ 1 fenêtre de
+* délai). Ordre de grandeur aligné sur le heartbeat WS (`keepaliveInterval` 20 s).
+*/
+const REVOCATION_REVALIDATE_MS = 3e4;
+/**
+* RealtimeHub — broker temps réel **PAR INSTANCE** (1 pod = 1 process = 1 hub local).
+*
+* Élève le realtime serveur du modèle **per-connexion** (chaque connexion son propre
+* ticker/listener = N fois le même travail) au modèle **canaux PARTAGÉS** : un canal a
+* **UN provider** créé au 1ᵉʳ abonné et un **fan-out** vers tous les abonnés. C'est le
+* gain cloud-native (1 ticker/canal/pod) ET le **seam du backplane Redis** (le cross-pod
+* se branchera dans {@link publish} : fan-out local + forward Redis, l'ingress backplane
+* ne refaisant QUE du fan-out local — règle anti-boucle). Cf vision « la socket Nodefony ».
+*
+* Périmètre actuel : canaux **broadcast** (même flux pour tous les abonnés — stats,
+* syslog, orm…). Les canaux **privés/par-connexion** (ex. une ligne SIP par user) =
+* seam futur (le provider serait per-connexion, pas partagé).
+*
+* Perf (règle ABSOLUE) : map des canaux **lazy** (rien alloué tant qu'aucun abonné) ;
+* provider créé au 1ᵉʳ abonné, **disposé au dernier** (aucun timer/listener orphelin) ;
+* fan-out isolé (une connexion fautive ne casse pas la diffusion). Le hub lui-même est
+* **sans dépendance** : ce sont les *factories* (fournies par les contrôleurs) qui
+* portent les deps.
+*
+* Vocabulaire : la **socket** ({@link IRealtimeSocket}) est la prise que tient le métier ;
+* ce **hub** est le broker serveur caché derrière (registre + fan-out local). La socket
+* multiplexe des canaux ; le hub aiguille entre les sockets. La façade *consommateur*
+* côté serveur EXISTE — {@link ServerRealtimeSocket} (`subscribe/on/publish`), exportée
+* par le barrel du module : c'est elle qu'un service back tient, jamais ce hub
+* directement. Même rôle que `RealtimeClient` côté navigateur.
+*/
+var RealtimeHub = class RealtimeHub {
+	#channels = null;
+	#publishTotal = 0;
+	#fanoutTotal = 0;
+	#inboundTotal = 0;
+	#ingressRejectedTotal = 0;
+	#systemFloorDeniedTotal = 0;
+	#notice = null;
+	#noticed = null;
+	#connections = null;
+	#revocable = null;
+	#revalidateTimer = null;
+	#backplane = null;
+	#authenticators = null;
+	#peerTokens = null;
+	#frameAuthorizer = null;
+	#channelProbe = null;
+	#channelPolicies = null;
+	/**
+	* Politiques déclarées par MOTIF de nom (`chat:room:*`), triées du plus
+	* spécifique au plus général, et `null` tant qu'aucune n'est déclarée.
+	*
+	* 🔴 Pourquoi une liste À PART de la Map exacte, et pourquoi elle reste
+	* `null` : `resolveChannelPolicy` est appelé à CHAQUE `subscribe`. Le nom
+	* exact doit rester une lecture O(1) sans allocation ; les motifs ne sont
+	* parcourus que si aucun nom exact ne répond ET qu'il en existe. Une
+	* application qui n'en déclare aucun ne paie rien — pas même le test d'un
+	* tableau vide.
+	*
+	* Le tri à l'insertion (littéral le plus long d'abord) évite de trancher au
+	* moment de la lecture : entre `chat:*` et `chat:room:*`, c'est le second qui
+	* doit gagner sur `chat:room:12`, et l'ordre le dit une fois pour toutes.
+	*/
+	#channelPolicyPatterns = null;
+	#systemChannelFactories = null;
+	#clientLogs = null;
+	#originGuard = null;
+	#maxChannelsPerConnection = 256;
+	#slowConsumerBytes = SLOW_CONSUMER_BYTES;
+	#broadcastPrefixes = null;
+	/**
+	* Abonnement demandé par une **connexion cliente** — même chose que
+	* {@link subscribe}, plus le plancher des canaux de plateforme.
+	*
+	* Pourquoi deux portes : un service du serveur qui écoute ses propres journaux
+	* est légitime ; une connexion distante qui demande `nodefony:syslog` alors
+	* qu'aucun module de sécurité n'est chargé ne l'est pas. Le hub ne peut pas
+	* deviner l'origine d'un appel — le contrôleur, lui, sait qu'il traite une
+	* frame venue du réseau, et passe donc par ici.
+	*
+	* Le plancher ne s'applique **que** sans verrou de frame. Dès qu'un module de
+	* sécurité en pose un, c'est lui qui décide (avec les rôles, ce que le hub ne
+	* sait pas faire) et le plancher s'efface.
+	*
+	* @returns `true` si abonné, `false` si canal inconnu ou fermé par le plancher.
+	*/
+	subscribeClient(channel, sink, factory, serialize) {
+		if (channel.includes("*")) {
+			this.#notifyOnce("wildcard-channel", `abonnement REFUSÉ au canal "${channel}" : le caractère « * » est réservé aux MOTIFS de politique et n'a pas de sens dans un nom de canal servi. Un motif garde une famille, il ne se souscrit pas.`);
+			return false;
+		}
+		if (this.#frameAuthorizer === null && isReservedSystemChannel(channel)) {
+			this.#systemFloorDeniedTotal += 1;
+			this.#notifyOnce("system-floor", `canal de plateforme "${channel}" REFUSÉ : aucun module de sécurité n'est chargé, donc aucune identité ne peut être vérifiée. Les namespaces réservés (${RESERVED_SYSTEM_PREFIXES.join(" ")}) sont fermés à toutes les connexions. Deux causes possibles : la sécurité n'est pas installée (charger @nodefony/security et déclarer une zone protégée), ou ce canal applicatif porte par erreur un préfixe réservé — dans ce cas, le renommer suffit.`);
+			return false;
+		}
+		return this.subscribe(channel, sink, factory, serialize);
+	}
+	/**
+	* Abonne un consommateur qui **répond du canal** : il apporte la `factory`, donc
+	* la réponse à « ce canal existe-t-il, et qui le produit ? ». Le provider partagé
+	* est créé au 1ᵉʳ abonné de ce genre. Le sink est inscrit AVANT l'appel à
+	* `factory` → le 1ᵉʳ paquet immédiat éventuel du provider (ex. tick initial de
+	* `createBrokerTicker`) atteint bien cet abonné.
+	*
+	* Un canal en état **passif** (ouvert par des écouteurs seuls, cf {@link listen})
+	* n'est PAS considéré comme existant : la fabrique est rejouée et tranche. Un
+	* refus laisse les écouteurs en place — ils n'ont jamais prétendu le produire.
+	*
+	* @returns `true` si abonné, `false` si canal inconnu (`factory` a renvoyé `null`).
+	*/
+	subscribe(channel, sink, factory, serialize) {
+		const channels = this.#channels ??= /* @__PURE__ */ new Map();
+		let st = channels.get(channel);
+		if (st) {
+			if (st.owned) {
+				st.sinks.add(sink);
+				if (st.serialize === null && serialize !== void 0) st.serialize = serialize;
+				return true;
+			}
+			st.sinks.add(sink);
+			const dispose = this.#createProvider(channel, factory);
+			if (dispose === null) {
+				st.sinks.delete(sink);
+				return false;
+			}
+			st.dispose = dispose;
+			st.owned = true;
+			if (serialize !== void 0) st.serialize = serialize;
+			return true;
+		}
+		st = {
+			dispose: null,
+			owned: false,
+			sinks: /* @__PURE__ */ new Set([sink]),
+			serialize: serialize ?? null,
+			messages: 0,
+			forward: this.#isBroadcast(channel)
+		};
+		channels.set(channel, st);
+		const dispose = this.#createProvider(channel, factory);
+		if (dispose === null) {
+			channels.delete(channel);
+			return false;
+		}
+		st.dispose = dispose;
+		st.owned = true;
+		return true;
+	}
+	/**
+	* **Écoute passive** — un service du serveur reçoit ce qui passe sur un canal
+	* sans prétendre le produire. C'est la porte de {@link ServerRealtimeSocket} :
+	* un service back qui `subscribe` sur sa façade écoute, il n'ouvre rien.
+	*
+	* Différence avec {@link subscribe} : aucune fabrique, donc aucun provider et
+	* **aucune revendication d'existence**. Si le canal n'a pas encore de
+	* propriétaire, l'état créé est marqué passif ; la première connexion cliente
+	* qui le demandera fera trancher la fabrique du controller. Un canal déjà
+	* ouvert est simplement rejoint (le provider partagé n'est pas touché).
+	*
+	* Un écouteur n'échoue jamais : il entendra si — et quand — quelqu'un publie.
+	* Cold path (abonnement d'un service, pas une frame réseau).
+	*/
+	listen(channel, sink) {
+		const channels = this.#channels ??= /* @__PURE__ */ new Map();
+		const st = channels.get(channel);
+		if (st !== void 0) {
+			st.sinks.add(sink);
+			return;
+		}
+		channels.set(channel, {
+			dispose: null,
+			owned: false,
+			sinks: /* @__PURE__ */ new Set([sink]),
+			serialize: null,
+			messages: 0,
+			forward: this.#isBroadcast(channel)
+		});
+	}
+	/**
+	* Le canal a-t-il un propriétaire (une fabrique a fourni son provider) ?
+	* `false` = inconnu, ou tenu par de seuls écouteurs ({@link listen}).
+	*/
+	isChannelOwned(channel) {
+		return this.#channels?.get(channel)?.owned ?? false;
+	}
+	/**
+	* Crée le provider d'un canal : fabrique de l'abonné d'abord, registre des
+	* canaux SYSTÈME en dernier recours. `null` = canal inconnu des deux.
+	*/
+	#createProvider(channel, factory) {
+		const publishFn = (ch, payload) => this.publish(ch, payload);
+		const dispose = factory(channel, publishFn);
+		if (dispose !== null) return dispose;
+		const sys = this.#systemChannelFactories?.get(channel);
+		return sys ? sys(channel, publishFn) : null;
+	}
+	/**
+	* Désabonne une connexion d'un canal. Au **dernier** abonné, `dispose()` le provider
+	* et retire le canal (libère timers/listeners). No-op si non abonné.
+	*/
+	unsubscribe(channel, sink) {
+		const st = this.#channels?.get(channel);
+		if (!st) return;
+		st.sinks.delete(sink);
+		if (st.sinks.size === 0) {
+			try {
+				st.dispose?.();
+			} catch {}
+			this.#channels.delete(channel);
+		}
+	}
+	/**
+	* Publie une charge sur un canal : **fan-out local** **+** propagation conditionnelle
+	* au {@link IBackplane} (autres workers/pods). C'est le point d'entrée des providers
+	* locaux (tickers, listeners) ET de tout code serveur.
+	*
+	* Forward **opt-in par canal** : la charge ne traverse le backplane que si le canal
+	* est déclaré **broadcast** ({@link markBroadcastChannel}). Par défaut un canal est
+	* **instance-local** (per-instance : observabilité, état du pod) → il reste dans le
+	* process. Le flag est mis en cache dans l'état du canal (lu en O(1)) ; pour un
+	* `publish` serveur sans abonné local (pas d'état), la politique est évaluée à la volée.
+	*
+	* Anti-boucle : un message **reçu** du backplane ne repasse PAS par ici (il appelle
+	* `publishLocal` directement) → aucune ré-émission cross-process, pas de tempête.
+	*/
+	publish(channel, payload) {
+		const st = this.#channels?.get(channel);
+		if (st !== void 0) this.#fanout(st, payload);
+		if (this.#backplane === null) return;
+		if (st !== void 0 ? st.forward : this.#isBroadcast(channel)) this.#backplane.publish(channel, payload);
+	}
+	/**
+	* Fan-out d'une charge aux **seuls abonnés locaux** d'un canal (process courant).
+	* NE propage PAS au backplane → c'est la voie d'**ingress** d'un message venu d'un
+	* autre pair (le hub câble `backplane.onMessage` dessus dans {@link setBackplane}) :
+	* réinjection locale sans reboucler. Aussi appelable directement pour un push
+	* strictement local (jamais propagé).
+	*/
+	publishLocal(channel, payload) {
+		const st = this.#channels?.get(channel);
+		if (st !== void 0) this.#fanout(st, payload);
+	}
+	/** Fan-out interne (sonde + livraison isolée). Partagé par `publish`/`publishLocal`. */
+	#fanout(st, payload) {
+		this.#publishTotal += 1;
+		st.messages += 1;
+		this.#fanoutTotal += st.sinks.size;
+		let raw;
+		if (st.serialize !== null && st.sinks.size > 1) try {
+			raw = st.serialize(payload);
+		} catch {
+			raw = void 0;
+		}
+		for (const sink of st.sinks) try {
+			sink(payload, raw);
+		} catch {}
+	}
+	/**
+	* Déclare un **préfixe** de canal **broadcast** : ses publications traversent le
+	* {@link IBackplane} (cross-process). Tout le reste demeure instance-local (défaut sûr).
+	* Le préfixe couvre la granularité de cadence (`chat:` matche `chat:room1:1000`).
+	*
+	* Idempotent ; cold-path (appelé au handshake/boot d'un endpoint realtime, jamais
+	* sur le chemin chaud). Réévalue les canaux DÉJÀ actifs → l'ordre déclaration/abonnement
+	* n'a pas d'importance.
+	*
+	* @param prefix - préfixe de canal à forwarder (ex. `"chat:"`, `"presence:"`).
+	*/
+	markBroadcastChannel(prefix) {
+		if (isReservedSystemChannel(prefix)) {
+			this.#notifyOnce("reserved-broadcast", `déclaration de diffusion IGNORÉE pour "${prefix}" : ce namespace est réservé à la plateforme (${RESERVED_SYSTEM_PREFIXES.join(" ")}). Le diffuser entre pods ouvrirait l'entrée du bus à ce canal — un tiers pourrait y injecter du contenu. Utiliser un préfixe applicatif.`);
+			return;
+		}
+		const prefixes = this.#broadcastPrefixes ??= [];
+		if (prefixes.includes(prefix)) return;
+		prefixes.push(prefix);
+		if (this.#channels) {
+			for (const [channel, st] of this.#channels) if (!st.forward && channel.startsWith(prefix)) st.forward = true;
+		}
+	}
+	/** Un canal est-il broadcast (préfixe déclaré) ? `false` si aucune politique (défaut local). */
+	#isBroadcast(channel) {
+		const prefixes = this.#broadcastPrefixes;
+		if (prefixes === null) return false;
+		for (let i = 0; i < prefixes.length; i++) if (channel.startsWith(prefixes[i])) return true;
+		return false;
+	}
+	/**
+	* Branche le {@link IBackplane} cross-process (cluster IPC, Redis…) et câble son
+	* ingress ({@link #admitFromBackplane}) : un message reçu d'un autre pair est
+	* réinjecté en **fan-out local uniquement** ({@link publishLocal}) — barrière
+	* anti-boucle côté hub (le backplane filtre déjà son propre echo). Remplace un
+	* backplane précédent (l'appelant est responsable de `stop()` l'ancien). Démarre
+	* le transport.
+	*
+	* @returns le backplane branché (chaînage).
+	*/
+	setBackplane(backplane) {
+		this.#backplane = backplane;
+		backplane.onMessage((msg) => this.#admitFromBackplane(msg));
+		backplane.start();
+		return backplane;
+	}
+	/**
+	* **Contrôle d'admission de l'ingress backplane** (F83) — un message venu d'un
+	* pair n'est réinjecté QUE si son canal est déclaré **broadcast**
+	* ({@link markBroadcastChannel}) ; sinon il est compté et jeté.
+	*
+	* POURQUOI : la politique de forward était asymétrique. En SORTIE, `publish` ne
+	* traverse le backplane que pour un canal broadcast ; en ENTRÉE, tout était
+	* accepté. Un pair (ou quiconque écrit dans un bus partagé, cf `envelope.ts`)
+	* pouvait donc pousser sur des canaux **instance-local** que la politique refuse
+	* précisément de faire voyager — `syslog:`, `nodefony:audit`, `nodefony:socket` —
+	* et injecter de faux évènements dans les écrans d'admin de TOUS les pods.
+	*
+	* Symétrie rétablie, et **quel que soit le driver** : un driver userland qui
+	* n'authentifierait rien ne peut pas contourner cette porte. Zéro régression
+	* nominale : un pair légitime n'émet que des canaux broadcast (`publish` filtre à
+	* la source), et un canal ne peut avoir d'abonné local que si l'endpoint qui le
+	* sert a été handshaké — donc ses préfixes déjà déclarés.
+	*/
+	#admitFromBackplane(msg) {
+		if (!this.#isBroadcast(msg.channel)) {
+			this.#ingressRejectedTotal += 1;
+			return;
+		}
+		this.publishLocal(msg.channel, msg.payload);
+	}
+	/** Backplane cross-process branché, ou `null` en mono-process (lecture/tests/sonde). */
+	get backplane() {
+		return this.#backplane;
+	}
+	/** Nombre d'abonnés locaux d'un canal (observabilité / tests). */
+	subscriberCount(channel) {
+		return this.#channels?.get(channel)?.sinks.size ?? 0;
+	}
+	/**
+	* Inscrit une connexion au registre de la sonde (au handshake). Lazy : alloue le
+	* Set au 1ᵉʳ appel. Le hub ne lit ces connexions QUE dans {@link probe} (jamais
+	* sur le chemin chaud). À équilibrer par {@link unregisterConnection} au close.
+	*/
+	registerConnection(conn) {
+		(this.#connections ??= /* @__PURE__ */ new Set()).add(conn);
+	}
+	/** Retire une connexion du registre de la sonde (au close). No-op si absente. */
+	unregisterConnection(conn) {
+		this.#connections?.delete(conn);
+	}
+	/**
+	* Inscrit une connexion à identité RÉVOCABLE au registre de
+	* re-validation (F4, revue 0.6). Démarre le tick au 1ᵉʳ inscrit (timer `unref`,
+	* 0 timer au repos). À équilibrer par {@link unregisterRevocable} au close.
+	* N'inscrire QUE les tokens portant `isValid` (le controller filtre) : une identité
+	* non révocable (anonyme/JWT sans revalidation) ne doit pas y entrer.
+	*/
+	registerRevocable(entry) {
+		(this.#revocable ??= /* @__PURE__ */ new Set()).add(entry);
+		if (this.#revalidateTimer === null) {
+			this.#revalidateTimer = setInterval(() => {
+				this.revalidateRevocable();
+			}, REVOCATION_REVALIDATE_MS);
+			this.#revalidateTimer.unref?.();
+		}
+	}
+	/**
+	* Retire une connexion du registre de révocation (au close). Arrête le tick dès que
+	* le registre est vide (0 timer au repos). No-op si absente.
+	*/
+	unregisterRevocable(entry) {
+		if (this.#revocable === null) return;
+		this.#revocable.delete(entry);
+		if (this.#revocable.size === 0 && this.#revalidateTimer !== null) {
+			clearInterval(this.#revalidateTimer);
+			this.#revalidateTimer = null;
+		}
+	}
+	/**
+	* Tick de re-validation (F4) : re-lit l'identité de chaque connexion révocable
+	* (`token.isValid()`) et FERME la socket (`4001`) si l'identité est morte : session
+	* détruite ou passée à un autre compte, jeton expiré ou révoqué.
+	* Fail-closed : une re-validation qui throw ferme aussi (parité `invokeApiRequest`).
+	* Snapshot du registre AVANT les `await` (le `close` mute le registre via le cleanup
+	* `onFinish`). Exposé (public) pour un test déterministe sans fake timers.
+	*/
+	async revalidateRevocable() {
+		if (this.#revocable === null || this.#revocable.size === 0) return;
+		const snapshot = [...this.#revocable];
+		for (const entry of snapshot) {
+			let valid;
+			try {
+				valid = await entry.token.isValid?.();
+			} catch {
+				valid = false;
+			}
+			if (valid === false) {
+				this.unregisterRevocable(entry);
+				try {
+					entry.close(4001, "session revoked");
+				} catch {}
+			}
+		}
+	}
+	/**
+	* Compte une frame entrante full-duplex (canaux gated SIP/bridge). Appelé par le
+	* contrôleur quand un handler `realtimeInbound` traite un message client.
+	*/
+	recordInbound() {
+		this.#inboundTotal += 1;
+	}
+	/**
+	* Snapshot d'auto-observabilité de la socket (per-instance). Lecture PURE (aucune
+	* alloc sur le chemin chaud, jamais throw) : agrège canaux + fan-out + connexions +
+	* **backpressure** (`bufferedAmount`, risque #1). Appelé à la demande (endpoint HTTP)
+	* ou par le ticker hub `nodefony:socket`. Les cumuls sont monotones → débit dérivé
+	* côté lecteur. Cf {@link IRealtimeProbe}.
+	*/
+	probe() {
+		const channels = [];
+		if (this.#channels) for (const [channel, st] of this.#channels) channels.push({
+			channel,
+			subscribers: st.sinks.size,
+			messages: st.messages
+		});
+		let connectionCount = 0;
+		let bytesSentTotal = 0;
+		let messagesSentTotal = 0;
+		let maxBufferedAmount = 0;
+		let totalBufferedAmount = 0;
+		let slowConsumers = 0;
+		let drops = 0;
+		if (this.#connections) for (const c of this.#connections) {
+			connectionCount += 1;
+			bytesSentTotal += c.bytesSent;
+			messagesSentTotal += c.messagesSent;
+			drops += c.dropped;
+			const buf = c.bufferedAmount;
+			if (buf > maxBufferedAmount) maxBufferedAmount = buf;
+			totalBufferedAmount += buf;
+			if (buf >= this.#slowConsumerBytes) slowConsumers += 1;
+		}
+		return {
+			ts: Date.now(),
+			channels,
+			channelCount: channels.length,
+			publishTotal: this.#publishTotal,
+			fanoutTotal: this.#fanoutTotal,
+			inboundTotal: this.#inboundTotal,
+			ingressRejectedTotal: this.#ingressRejectedTotal,
+			systemFloorDeniedTotal: this.#systemFloorDeniedTotal,
+			connectionCount,
+			bytesSentTotal,
+			messagesSentTotal,
+			backpressure: {
+				maxBufferedAmount,
+				totalBufferedAmount,
+				slowConsumers,
+				drops
+			},
+			backplane: this.#backplane?.describe() ?? {
+				driver: LoopbackBackplane.driver,
+				kind: "local",
+				originId: String(process.pid),
+				crossPod: false
+			}
+		};
+	}
+	/** Canaux actifs (≥ 1 abonné). Lecture seule. */
+	get activeChannels() {
+		return this.#channels ? [...this.#channels.keys()] : [];
+	}
+	/**
+	* **Seam #2 (P13 → P6)** — enregistre un authenticator pour les handshakes
+	* WS dont l'URL matche `matcher`. Ordre d'enregistrement préservé : le
+	* **1ʳᵉ** matcher qui capture la connexion gagne. Convention : enregistrer
+	* les patterns les plus spécifiques en premier.
+	*
+	* Idempotent par couple `(matcher, authenticator)` — appel multiple = même
+	* effet (push si pas déjà présent). Cold-path (boot via P6/userland).
+	*
+	* @param matcher        sélecteur (pattern URL + vhost optionnel)
+	* @param authenticator  stratégie d'auth réseau (handshake → IRealtimeToken)
+	*/
+	useAuthenticator(matcher, authenticator) {
+		const list = this.#authenticators ??= [];
+		const compiled = compileMatcher(matcher);
+		for (let i = 0; i < list.length; i++) if (list[i].authenticator === authenticator) return;
+		list.push({
+			matcher: compiled,
+			authenticator
+		});
+	}
+	/**
+	* Résout l'authenticator capturant ce handshake (1ʳᵉ matcher qui matche),
+	* ou `null` si aucun (le RealtimeController posera un token anonyme).
+	* Cold path (1× par upgrade) — lecture array.
+	*/
+	resolveAuthenticator(handshake) {
+		const list = this.#authenticators;
+		if (list === null) return null;
+		for (let i = 0; i < list.length; i++) {
+			const entry = list[i];
+			if (entry.matcher.match(handshake)) return entry.authenticator;
+		}
+		return null;
+	}
+	/**
+	* **Seam #4 (P13 → P6)** — pose la politique Origin (RFC 6455 §10.2).
+	* `null` = aucune politique (toutes origines acceptées). Posée 1× par
+	* `RealtimeService.init()` depuis `defineRealtimeConfig().csrf.checkOrigin`.
+	*/
+	setOriginGuard(guard) {
+		this.#originGuard = guard;
+	}
+	/**
+	* Vérifie qu'une origin est autorisée (politique CSRF). `true` si aucune
+	* politique posée (rétrocompat). Cold path (1× par upgrade).
+	*/
+	checkOrigin(origin) {
+		return this.#originGuard === null ? true : this.#originGuard(origin);
+	}
+	/**
+	* F6a (revue 0.6) — plafond de canaux par connexion (anti-OOM). Posé 1× au
+	* boot par `RealtimeService.init()` depuis
+	* `defineRealtimeConfig().limits.maxChannelsPerConnection`. `null` = illimité.
+	*/
+	setMaxChannelsPerConnection(max) {
+		this.#maxChannelsPerConnection = max;
+	}
+	/** Plafond courant de canaux par connexion (`null` = illimité). Lu par `startChannel`. */
+	get maxChannelsPerConnection() {
+		return this.#maxChannelsPerConnection;
+	}
+	/**
+	* F9 (revue 0.6) — pose le seuil de comptage des consommateurs lents (`probe()`).
+	* Posé 1× au boot par `RealtimeService.init()` depuis
+	* `defineRealtimeConfig().slowConsumer.bytes` (sinon la clé de config serait morte).
+	*/
+	setSlowConsumerBytes(bytes) {
+		this.#slowConsumerBytes = bytes;
+	}
+	/**
+	* Associe un token au peer (posé par `RealtimeController.onHandshake()` après
+	* succès `authenticator.authenticate()` ou fallback anonyme). Lazy alloc de
+	* la `WeakMap` au 1ᵉʳ appel (0 coût si aucun authenticator enregistré).
+	*/
+	setTokenForPeer(peer, token) {
+		(this.#peerTokens ??= /* @__PURE__ */ new WeakMap()).set(peer, token);
+	}
+	/**
+	* Renvoie le token associé au peer, ou `ANONYMOUS_REALTIME_TOKEN` si aucun
+	* (cas Zero Trust : la lecture ne renvoie JAMAIS `null` — slot #6 audit
+	* lookup garanti, voters P6 ne se posent jamais la question « actor ? »).
+	*/
+	getTokenForPeer(peer) {
+		return this.#peerTokens?.get(peer) ?? ANONYMOUS_REALTIME_TOKEN;
+	}
+	/**
+	* **Seam #1 (P13 → P6)** — pose le verrou de frame (cf {@link FrameAuthorizer}).
+	* `null` retire la politique (bypass total). Posé 1× au boot par
+	* `@nodefony/security` depuis les zones `realtime: true`. Cold path.
+	*/
+	setFrameAuthorizer(authorizer, options) {
+		this.#frameAuthorizer = authorizer;
+		this.#channelProbe = options?.silentProbe ?? null;
+	}
+	/**
+	* Un verrou de frame est-il posé ?
+	*
+	* Sert au DIAGNOSTIC (`hasUnenforcedChannelPolicies`, introspection, tests) —
+	* **plus** à décider si on arme le verrou sur une connexion : le contrôleur
+	* l'arme toujours, précisément pour qu'une politique posée après coup garde
+	* les sockets déjà ouvertes.
+	*/
+	hasFrameAuthorizer() {
+		return this.#frameAuthorizer !== null;
+	}
+	/**
+	* Branche l'alerte du plancher système — tirée **une seule fois**, au premier
+	* canal de plateforme refusé faute de module de sécurité.
+	*
+	* Posée par le contrôleur : le hub est sans dépendance (aucun journal), et une
+	* fermeture silencieuse serait exactement la dégradation muette qu'on cherche
+	* à interdire.
+	*
+	* @param notify - reçoit le message à journaliser (niveau avertissement).
+	*/
+	onPlatformNotice(notify) {
+		this.#notice = notify;
+	}
+	/**
+	* Émet un avertissement de plateforme, **une seule fois par motif**.
+	*
+	* @param key      - motif (clé de déduplication), pas le texte.
+	* @param message  - ce que lira l'exploitant.
+	* @param severity - niveau de journal.
+	*/
+	#notifyOnce(key, message, severity = "WARNING") {
+		if (this.#notice === null) return;
+		const seen = this.#noticed ??= /* @__PURE__ */ new Set();
+		if (seen.has(key)) return;
+		seen.add(key);
+		this.#notice(message, severity);
+	}
+	/**
+	* Ce canal serait-il fermé par le plancher système ? Lecture PURE (ni compteur,
+	* ni alerte) — elle sert à expliquer un refus au client plutôt qu'à le décider.
+	*
+	* Sans elle, un abonnement refusé resterait sans réponse : le client attendrait
+	* indéfiniment des données qui ne viendront pas, ce qui est exactement la
+	* dégradation muette que ce plancher est censé faire disparaître.
+	*/
+	isClosedBySystemFloor(channel) {
+		return this.#frameAuthorizer === null && isReservedSystemChannel(channel);
+	}
+	/**
+	* F1 (revue 0.6) — des politiques de canal sont-elles DÉCLARÉES (`@RealtimeChannel`
+	* avec `roles`/`scopes`/`authenticated`) sans `frameAuthorizer` pour les faire
+	* respecter ? `true` = **dégradation silencieuse** : un canal se croit gardé mais
+	* aucun décideur n'est câblé → un subscribe passe non gardé. Vrai uniquement sans
+	* `@nodefony/security` (ou toutes les zones en `realtime: false`). Lu par le
+	* RealtimeController pour émettre un WARNING au boot (fail-loud, jamais silencieux).
+	*/
+	hasUnenforcedChannelPolicies() {
+		return this.hasChannelPolicies() && this.#frameAuthorizer === null;
+	}
+	/**
+	* **Seam #1b** — déclare la politique d'autorisation d'un canal/méthode
+	* (`@RealtimeChannel`/`@RealtimeInbound` avec opts). Appelé au handshake par
+	* le controller pour CHAQUE canal décoré (idempotent : même nom = écrase, les
+	* controllers d'un même endpoint déclarent la même policy). Cold path.
+	*
+	* Deux formes de nom, et la seconde garde une FAMILLE :
+	*
+	* - un nom **exact** (`chat:room`) — lecture O(1) au `subscribe` ;
+	* - un **motif** (`chat:room:*`) — il couvre tout canal dérivé servi par une
+	*   fabrique dynamique (`chat:room:1000`), ce qu'un nom exact ne faisait pas.
+	*   Le `*` remplace n'importe quelle suite de caractères ; tout le reste du
+	*   motif est littéral (échappé), y compris `.` et `(`.
+	*
+	* Précédence : le nom **exact** l'emporte toujours — c'est ainsi qu'on ouvre
+	* une exception dans une famille gardée. Entre deux motifs, le plus
+	* **spécifique** gagne (littéral le plus long).
+	*
+	* @param name   - nom exact du canal (subscribe), de la méthode inbound, ou
+	*   MOTIF de famille s'il contient `*`.
+	* @param policy - exigences ({@link IChannelPolicy}) lues par security.
+	*/
+	registerChannelPolicy(name, policy) {
+		if (isReservedSystemChannel(name)) this.#notifyOnce("reserved-policy", `le canal "${name}" est déclaré dans un namespace RÉSERVÉ à la plateforme (${RESERVED_SYSTEM_PREFIXES.join(" ")}) : le plancher système s'y applique et exigera un rôle d'administration, quelle que soit la politique déclarée ici. Renommer le canal avec un préfixe applicatif si ce n'est pas voulu.`);
+		if (name.includes("*")) {
+			this.#registerChannelPolicyPattern(name, policy);
+			return;
+		}
+		(this.#channelPolicies ??= /* @__PURE__ */ new Map()).set(name, policy);
+	}
+	/**
+	* Nombre maximum de `*` dans un motif.
+	*
+	* Ce n'est pas une limite de confort : chaque `*` devient un `.*` dans
+	* l'expression compilée, et plusieurs `.*` sur une chaîne qui NE matche pas
+	* font revenir le moteur sur ses pas — un coût qui explose avec leur nombre.
+	* Un motif de canal en demande un, deux au pire ; au-delà, c'est une erreur
+	* de déclaration, et on le DIT plutôt que d'exposer un chemin coûteux à ce
+	* qu'un client peut nommer.
+	*/
+	static MAX_PATTERN_WILDCARDS = 3;
+	/**
+	* Compile un motif et l'insère à son rang de spécificité.
+	*
+	* Le motif est ÉCHAPPÉ intégralement avant que `*` ne devienne `.*` : rien de
+	* ce que l'auteur écrit n'est interprété comme une expression régulière. Un
+	* `.` reste un point, un `(` reste une parenthèse — sans quoi une déclaration
+	* anodine deviendrait une expression, avec ce que cela ouvre.
+	*/
+	#registerChannelPolicyPattern(source, policy) {
+		const etoiles = source.split("*").length - 1;
+		if (etoiles > RealtimeHub.MAX_PATTERN_WILDCARDS) {
+			this.#notifyOnce(`pattern-too-broad:${source}`, `le motif de politique "${source}" porte ${etoiles} caractères « * » (maximum ${RealtimeHub.MAX_PATTERN_WILDCARDS}) : il est IGNORÉ. Un motif de canal en demande un, deux au pire — au-delà, la mise en correspondance coûte cher sur des noms que le client choisit.`);
+			return;
+		}
+		const echappe = source.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+		const re = new RegExp(`^${echappe.split("\\*").join(".*")}$`, "u");
+		const weight = source.split("*").join("").length;
+		const policies = this.#channelPolicyPatterns ??= [];
+		const existing = policies.findIndex((p) => p.source === source);
+		const policyEntry = {
+			source,
+			re,
+			weight,
+			policy
+		};
+		if (existing >= 0) {
+			policies[existing] = policyEntry;
+			return;
+		}
+		const rang = policies.findIndex((p) => p.weight < weight);
+		if (rang < 0) policies.push(policyEntry);
+		else policies.splice(rang, 0, policyEntry);
+	}
+	/**
+	* Politique déclarée pour ce canal/méthode, ou `null` si aucune. Lu par
+	* `@nodefony/security` (`resolveChannelPolicy` de la surface DI) au moment de
+	* la frame `subscribe`/inbound. O(1), 0 alloc quand le registre est vide.
+	*/
+	resolveChannelPolicy(name) {
+		const exact = this.#channelPolicies?.get(name);
+		if (exact !== void 0) return exact;
+		const patterns = this.#channelPolicyPatterns;
+		if (patterns === null) return null;
+		for (let i = 0; i < patterns.length; i++) if (patterns[i].re.test(name)) return patterns[i].policy;
+		return null;
+	}
+	/** Des politiques de canal sont-elles déclarées (au moins une) ? */
+	hasChannelPolicies() {
+		return (this.#channelPolicies?.size ?? 0) > 0 || (this.#channelPolicyPatterns?.length ?? 0) > 0;
+	}
+	/**
+	* Avertit — **une seule fois** — qu'un canal servi par une fabrique
+	* DYNAMIQUE n'est couvert par aucune politique déclarée, alors que d'autres
+	* canaux du module en portent une.
+	*
+	* Le registre des politiques est indexé par nom **EXACT** : `@RealtimeChannel`
+	* déclare `"chat:room"`, mais un canal dérivé (`chat:room:1000` — cadence,
+	* forage, suffixe) est servi par la fabrique dynamique et **ne matche pas**.
+	* L'auteur croit alors son canal gardé ; il ne l'est pas, et rien ne le lui
+	* dit. C'est ce silence qu'on ferme ici — et depuis qu'une politique peut se
+	* déclarer par MOTIF (`chat:room:*`), cet avertissement ne parle plus que des
+	* canaux qu'aucun motif ne couvre : il désigne un vrai trou, pas une limite
+	* de l'outil.
+	*
+	* Appelé par le contrôleur, seul à savoir par quelle voie le canal a été
+	* servi. Muet si aucune politique n'est déclarée (module aux canaux libres :
+	* il n'y a alors aucune promesse à trahir).
+	*
+	* @param channel - le canal servi dynamiquement, cité en exemple dans l'alerte.
+	*/
+	noticeUnguardedDynamicChannel(channel) {
+		if (!this.hasChannelPolicies()) return;
+		if (this.resolveChannelPolicy(channel) !== null) return;
+		this.#notifyOnce("unguarded-dynamic-channel", `le canal "${channel}" est servi par une fabrique DYNAMIQUE et n'est couvert par AUCUNE politique déclarée, alors que ce module en déclare pour d'autres canaux. Un canal dérivé (suffixe de cadence, forage, identifiant) n'hérite pas de la politique de son parent : un nom exact ne garde que lui-même. Déclarer un MOTIF pour garder la famille — @RealtimeChannel("${channel.replace(/[^:]*$/u, "*")}", { … }) — ou porter la vérification dans la fabrique elle-même.`);
+	}
+	/**
+	* Enregistre la **factory d'un canal système** (plateforme) — un module bas
+	* niveau (ex. `@nodefony/security` : `nodefony:audit`) déclare au boot comment
+	* produire le provider d'un canal, SANS qu'aucun `RealtimeController` ne le
+	* connaisse. `subscribe` consulte ce registre quand la factory du controller
+	* renvoie `null` → le canal devient servable par TOUT endpoint (présent/futur),
+	* zéro couplage à Studio. La factory garde la sémantique lazy du hub (créée au
+	* 1ᵉʳ abonné, `dispose` au dernier).
+	*
+	* @param channel - nom EXACT du canal système (match exact, pas un préfixe).
+	* @param factory - {@link ChannelFactory} qui crée le provider partagé.
+	*/
+	registerSystemChannel(channel, factory) {
+		(this.#systemChannelFactories ??= /* @__PURE__ */ new Map()).set(channel, factory);
+	}
+	/**
+	* Pont hot-path entre `JsonRpcPeer.beforeDispatch` et le verrou métier : lit
+	* le token déjà caché du peer (O(1), 0 lecture base) puis délègue à
+	* l'authorizer. `true` (autorisée) si aucun verrou posé (bypass 0-coût) —
+	* mais en pratique `beforeDispatch` n'est branché que si `hasFrameAuthorizer()`.
+	*
+	* @param frame - frame JSON-RPC entrante (brute) à autoriser.
+	* @param peer  - peer émetteur (clé du mapping `peer → token`).
+	* @returns `true` si la frame peut être dispatchée, `false` si refusée.
+	*/
+	/**
+	* Ouvre (ou referme) la réception des journaux du navigateur, avec ses bornes.
+	*
+	* @param limits - bornes de débit et de taille, ou `null` pour refermer le canal.
+	*/
+	setClientLogsLimits(limits) {
+		this.#clientLogs = limits;
+	}
+	/** Bornes en vigueur, ou `null` si le canal montant est fermé. */
+	get clientLogsLimits() {
+		return this.#clientLogs;
+	}
+	runAuthorizer(frame, peer) {
+		if (this.#frameAuthorizer === null) return true;
+		return this.#frameAuthorizer(frame, this.getTokenForPeer(peer));
+	}
+	/**
+	* Ce peer pourrait-il s'abonner à ce canal ? — même décision que `subscribe`,
+	* sans trace ni effet de bord.
+	*
+	* Rend `true` quand aucune sonde n'est posée : sans sécurité chargée, aucun
+	* canal n'est refusé, et l'absence de sonde ne doit jamais faire DISPARAÎTRE
+	* des canaux d'un welcome. Un filtre qui échoue doit échouer ouvert ici —
+	* c'est le verrou, pas l'annonce, qui protège l'accès.
+	*
+	* @param channel - le canal interrogé.
+	* @param peer - la connexion, d'où l'on tire le jeton résolu au handshake.
+	* @returns `true` si un `subscribe` sur ce canal serait accepté.
+	*/
+	probeChannel(channel, peer) {
+		if (this.#channelProbe === null) return true;
+		return this.#channelProbe({
+			method: "subscribe",
+			params: { channel }
+		}, this.getTokenForPeer(peer));
+	}
+	/** Authenticators enregistrés (debug / tests). Lecture seule. */
+	get registeredAuthenticators() {
+		if (this.#authenticators === null) return EMPTY_AUTH_LIST;
+		return this.#authenticators.map((e) => e.authenticator);
+	}
+	/** Dispose tous les providers et vide le hub (arrêt process / reset de test). */
+	clear() {
+		if (this.#channels) {
+			for (const st of this.#channels.values()) try {
+				st.dispose?.();
+			} catch {}
+			this.#channels.clear();
+			this.#channels = null;
+		}
+		this.#connections?.clear();
+		this.#connections = null;
+		this.#broadcastPrefixes = null;
+		this.#authenticators = null;
+		this.#peerTokens = null;
+		this.#frameAuthorizer = null;
+		this.#channelPolicies?.clear();
+		this.#channelPolicies = null;
+		this.#channelPolicyPatterns = null;
+		this.#originGuard = null;
+		this.#backplane = null;
+		this.#publishTotal = 0;
+		this.#fanoutTotal = 0;
+		this.#inboundTotal = 0;
+		this.#ingressRejectedTotal = 0;
+		this.#systemFloorDeniedTotal = 0;
+		this.#noticed = null;
+		this.#notice = null;
+	}
+};
+const EMPTY_AUTH_LIST = Object.freeze([]);
+/**
+* Compile un matcher utilisateur en forme efficace (RegExp précompilée + host
+* lowercase). Cold path (1× par `useAuthenticator`).
+*
+* - `pattern` RegExp : utilisée telle quelle (l'utilisateur sait ce qu'il fait).
+* - `pattern` string : compilée en RegExp **préfixe** ancrée (`^<escaped>`).
+*   Compromis sûr : `"/admin/"` matche `/admin/` ET `/admin/foo` SANS escape
+*   à la main (90 % des cas userland), tout en restant déterministe pour les
+*   tests.
+*/
+function compileMatcher(m) {
+	const pattern = m.pattern instanceof RegExp ? m.pattern : new RegExp("^" + RegExp.escape(m.pattern));
+	const host = m.host?.toLowerCase();
+	return {
+		pattern,
+		host,
+		match(handshake) {
+			if (host !== void 0) {
+				const raw = handshake.headers["host"];
+				if (((Array.isArray(raw) ? raw[0] : raw) ?? "").toLowerCase() !== host) return false;
+			}
+			const qi = handshake.url.indexOf("?");
+			const path = qi === -1 ? handshake.url : handshake.url.slice(0, qi);
+			return pattern.test(path);
+		}
+	};
+}
+let _hub = null;
+/** Renvoie le hub realtime du process (singleton lazy). */
+function getRealtimeHub() {
+	return _hub ??= new RealtimeHub();
+}
+//#endregion
+export { RESERVED_SYSTEM_PREFIXES, REVOCATION_REVALIDATE_MS, RealtimeHub, RealtimeHub as default, SLOW_CONSUMER_BYTES, getRealtimeHub, isReservedSystemChannel };