@nodefony/realtime 10.0.0-beta.2 → 10.0.0-beta.4

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

@@ -1,7 +1,7 @@
 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
+import { IDENTITY_REFRESH_CLOSE_CODE, NODEFONY_CHANNEL_NAMESPACE, REVOCATION_REVALIDATE_MS, RevocationWatch, isPlatformChannel } from "nodefony";
+// 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
@@ -45,17 +45,6 @@ const RESERVED_SYSTEM_PREFIXES = [NODEFONY_CHANNEL_NAMESPACE];
 */
 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;
-/**
 * Le MOTIF de famille d'un canal — son dernier segment remplacé par `*`.
 *
 * `"studio:metrics:1s"` → `"studio:metrics:*"`, `"alerts"` → `"*"`. Sert à
@@ -99,7 +88,7 @@ function channelFamily(channel) {
 * 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.
+* directement. Même rôle que `NodefonySocket` côté navigateur.
 */
 var RealtimeHub = class RealtimeHub {
 	#channels = null;
@@ -111,8 +100,12 @@ var RealtimeHub = class RealtimeHub {
 	#notice = null;
 	#noticed = null;
 	#connections = null;
-	#revocable = null;
-	#revalidateTimer = null;
+	#revocation = new RevocationWatch({
+		isValid: (entry) => entry.token.isValid?.(),
+		revoke: (entry) => entry.close(4001, "session revoked"),
+		identityOf: (entry) => entry.token.getUserIdentifier(),
+		refresh: (entry) => entry.close(IDENTITY_REFRESH_CLOSE_CODE, "identity changed")
+	});
 	#backplane = null;
 	#authenticators = null;
 	#peerTokens = null;
@@ -433,51 +426,36 @@ var RealtimeHub = class RealtimeHub {
 	* 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();
-		}
+		this.#revocation.register(entry);
 	}
 	/**
 	* 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;
-		}
+		this.#revocation.unregister(entry);
 	}
 	/**
-	* 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.
+	* Re-valide toutes les connexions révocables et ferme (`4001`) celles dont
+	* l'identité est morte : session détruite ou passée à un autre compte, jeton
+	* expiré ou révoqué. Fail-closed : une re-validation qui lève ferme aussi. Le
+	* registre est celui des flux SSE ({@link RevocationWatch}) — une garde, deux
+	* transports. Exposé (public) pour un test déterministe sans faux minuteur.
 	*/
-	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 {}
-			}
-		}
+	revalidateRevocable() {
+		return this.#revocation.revalidate();
+	}
+	/**
+	* Ferme tout de suite les connexions qui ont figé cette identité — ses droits
+	* ont changé (`IDENTITY_CHANGED_EVENT`). Code {@link IDENTITY_REFRESH_CLOSE_CODE},
+	* reconnectable : le client revient avec ses rôles frais. Le registre est
+	* celui des flux SSE — une règle, deux transports.
+	*
+	* @param identifier - identifiant de connexion de l'identité changée.
+	* @returns le nombre de connexions fermées.
+	*/
+	refreshIdentity(identifier) {
+		return this.#revocation.refreshIdentity(identifier);
 	}
 	/**
 	* Compte une frame entrante full-duplex (canaux gated SIP/bridge). Appelé par le
@@ -811,9 +789,10 @@ var RealtimeHub = class RealtimeHub {
 	* @param channel - le canal servi dynamiquement, cité en exemple dans l'alerte.
 	*/
 	noticeUnguardedDynamicChannel(channel) {
+		if (isReservedSystemChannel(channel)) return;
 		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("${channelFamily(channel)}", { … }) — ou porter la vérification dans la fabrique elle-même.`);
+		this.#notifyOnce("unguarded-dynamic-channel", `le canal "${channel}" n'a aucune règle d'accès : tout client connecté peut s'y abonner. Il est produit par createRealtimeChannel(), et une règle déclarée sur un nom exact ne couvre pas ses variantes (suffixe de cadence, identifiant). Pour le protéger : @RealtimeChannel("${channelFamily(channel)}", { roles: [ … ] }), ou vérifier les droits dans createRealtimeChannel().`);
 	}
 	/**
 	* Enregistre la **factory d'un canal système** (plateforme) — un module bas
@@ -943,5 +922,4 @@ let _hub = null;
 function getRealtimeHub() {
 	return _hub ??= new RealtimeHub();
 }
-//#endregion
 export { RESERVED_SYSTEM_PREFIXES, REVOCATION_REVALIDATE_MS, RealtimeHub, RealtimeHub as default, SLOW_CONSUMER_BYTES, channelFamily, getRealtimeHub, isReservedSystemChannel };

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

@@ -1,5 +1,5 @@
 import { getRealtimeHub } from "./RealtimeHub.js";
-//#region nodefony/src/server/ServerRealtimeSocket.ts
+// nodefony/src/server/ServerRealtimeSocket.ts
 /**
 * **L4 — façade serveur « la socket Nodefony ».** Un handle SERVEUR qui implémente
 * le contrat ISOMORPHE {@link IRealtimeSocket} au-dessus du {@link RealtimeHub} : un
@@ -17,8 +17,9 @@ import { getRealtimeHub } from "./RealtimeHub.js";
 *    l'état créé est passif, et c'est la fabrique du controller qui tranchera quand
 *    une connexion cliente le demandera. Un service n'invente donc jamais un canal
 *    pour les autres.
-*  - `request` : **non supporté** — un handle au-dessus du hub n'a PAS de pair unique
-*    (le hub est multi-clients). Pour un RPC serveur→client 1-1, utiliser
+*  - `request` : **non supporté, et déprécié** — un handle au-dessus du hub n'a PAS de
+*    pair unique (le hub est multi-clients), et le contrat commun `IRealtimeSocket` ne
+*    le promet plus. Pour un RPC serveur→client 1-1, utiliser
 *    `RealtimeController.requestClient` (par connexion, L1).
 *
 * Lazy : aucune structure allouée tant que le service n'`on`/`subscribe`/`publish` pas.
@@ -72,8 +73,22 @@ var ServerRealtimeSocket = class {
 			sinks.delete(c);
 		}
 	}
-	/** Branche un handler de réception sur un canal. Renvoie un `dispose`. */
+	/**
+	* Branche un handler de réception sur un canal. Renvoie un `dispose`.
+	*
+	* Le handler typé par `Listen` se range sans conversion sous
+	* `RealtimeHandler`, qui porte la frontière du contrat typé : il reçoit ce
+	* que le hub publie, dont `Listen` décrit la forme sans la valider.
+	*/
 	on(channel, handler) {
+		return this.#addHandler(channel, handler);
+	}
+	/** Retire un handler d'un canal — même frontière que {@link on}. */
+	off(channel, handler) {
+		this.#removeHandler(channel, handler);
+	}
+	/** Porte non typée de {@link on} : un nom de canal quelconque, un handler `unknown`. */
+	#addHandler(channel, handler) {
 		const handlers = this.#handlers ??= /* @__PURE__ */ new Map();
 		let set = handlers.get(channel);
 		if (!set) {
@@ -81,16 +96,19 @@ var ServerRealtimeSocket = class {
 			handlers.set(channel, set);
 		}
 		set.add(handler);
-		return () => this.off(channel, handler);
+		return () => this.#removeHandler(channel, handler);
 	}
-	/** Retire un handler d'un canal. */
-	off(channel, handler) {
+	/** Porte non typée de {@link off}. */
+	#removeHandler(channel, handler) {
 		this.#handlers?.get(channel)?.delete(handler);
 	}
 	/**
-	* **Non supporté.** Un handle au-dessus du hub n'a pas de pair unique
-	* (multi-clients). Pour un RPC serveur→client 1-1, utiliser
-	* `RealtimeController.requestClient` (par connexion, L1).
+	* **Non supporté** : rejette toujours. Un handle au-dessus du hub n'a pas de pair
+	* unique (multi-clients), et le contrat commun `IRealtimeSocket` ne promet plus
+	* `request`. Comportement inchangé pour toute la série 10.
+	*
+	* @deprecated Retrait en 11.0. Pour un RPC serveur→client 1-1, utiliser
+	*   `RealtimeController.requestClient` (par connexion, L1).
 	*/
 	request(_method, _params, _timeoutMs) {
 		return Promise.reject(/* @__PURE__ */ new Error("ServerRealtimeSocket.request: pas de pair unique côté hub (multi-clients). Pour un RPC serveur→client 1-1, utiliser RealtimeController.requestClient."));
@@ -102,7 +120,7 @@ var ServerRealtimeSocket = class {
 		return {
 			name,
 			on(handler) {
-				const dispose = hub.on(name, handler);
+				const dispose = hub.#addHandler(name, handler);
 				disposers.add(dispose);
 				return () => {
 					dispose();
@@ -110,7 +128,7 @@ var ServerRealtimeSocket = class {
 				};
 			},
 			send(payload) {
-				hub.publish(name, payload);
+				hub.hub.publish(name, payload);
 			},
 			open() {
 				hub.subscribe(name);
@@ -166,5 +184,4 @@ var ServerRealtimeSocket = class {
 function serverSocket() {
 	return new ServerRealtimeSocket(getRealtimeHub());
 }
-//#endregion
 export { ServerRealtimeSocket, ServerRealtimeSocket as default, serverSocket };

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

@@ -1,4 +1,4 @@
-//#region nodefony/src/server/deniedDetail.ts
+// nodefony/src/server/deniedDetail.ts
 /**
 * Le détail d'un `realtime:denied` — dit au développeur, tu à l'utilisateur.
 *
@@ -25,5 +25,4 @@ function deniedDetail(env, detail) {
 	if (!env || env === "production") return {};
 	return { detail };
 }
-//#endregion
 export { deniedDetail };

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

@@ -0,0 +1,29 @@
+// nodefony/src/server/subscribedAck.ts
+/**
+* Trame d'acquittement d'abonnement — `realtime:subscribed`, écrite d'un bloc.
+*
+* Tout ce qui précède le nom du canal ne dépend que du protocole : il est
+* calculé une fois au chargement du module. Seul le canal se sérialise par
+* trame. On évite ainsi l'enveloppe allouée et le `JSON.stringify` générique
+* de `JsonRpcPeer.notify` — mesuré à ~0,5 µs par acquittement, soit l'essentiel
+* du surcoût d'un `subscribe` acquitté.
+*
+* ⚠️ C'est une SECONDE écriture du format de notification : son égalité avec
+* `JsonRpcPeer.buildNotification` est verrouillée par `subscribedAck.test.ts`,
+* sur des noms de canal hostiles (guillemets, barres obliques inverses,
+* caractères de contrôle, Unicode).
+*
+* @internal
+*/
+/** Le préfixe invariant de la trame, jusqu'à la valeur `channel` exclue. */
+const SUBSCRIBED_FRAME_PREFIX = "{\"jsonrpc\":\"2.0\",\"method\":\"realtime:subscribed\",\"params\":{\"channel\":";
+/**
+* Sérialise la notification `realtime:subscribed { channel }`.
+*
+* @param channel - le canal acquitté (entrée réseau : échappé par `JSON.stringify`).
+* @returns la trame JSON-RPC 2.0 prête à écrire sur le transport.
+*/
+function subscribedAckFrame(channel) {
+	return SUBSCRIBED_FRAME_PREFIX + JSON.stringify(channel) + "}}";
+}
+export { subscribedAckFrame };

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

@@ -1,5 +1,6 @@
+import { isRecord } from "../guards.js";
 import { BROWSER_ORIGIN, Pdu } from "nodefony";
-//#region nodefony/src/server/syslogUplink.ts
+// nodefony/src/server/syslogUplink.ts
 /**
 * Réception des journaux **remontés par un navigateur** : le pendant serveur du
 * transport client (`nodefony/client` → `installSyslogUplink`).
@@ -89,8 +90,9 @@ function createSyslogUplinkHandler(opts) {
 		for (let i = 0; i < limit; i += 1) {
 			if (windowCount >= maxEntriesPerWindow) return;
 			windowCount += 1;
-			const raw = entries[i];
-			if (raw === null || typeof raw !== "object") continue;
+			const entry = entries[i];
+			if (!isRecord(entry)) continue;
+			const raw = entry;
 			const severity = clampSeverity(raw.severity);
 			const msgid = str(raw.msgid, 64) ?? "";
 			const msg = str(raw.msg, maxStringLength) ?? "";
@@ -101,5 +103,4 @@ function createSyslogUplinkHandler(opts) {
 		}
 	};
 }
-//#endregion
 export { BROWSER_ORIGIN, MAX_CLIENT_SEVERITY, createSyslogUplinkHandler };

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

@@ -1,4 +1,4 @@
-//#region nodefony/src/server/welcomeEnv.ts
+// nodefony/src/server/welcomeEnv.ts
 /**
 * Le mode d'exécution annoncé — ou non — dans `realtime:welcome`.
 *
@@ -21,5 +21,4 @@ function welcomeEnv(env) {
 	if (!env || env === "production") return {};
 	return { env };
 }
-//#endregion
 export { welcomeEnv };

package/dist/nodefony/src/service/RealtimeService.js

@@ -1,7 +1,8 @@
+import { isRealtimeConfig } from "../../config/defineModuleConfig.js";
 import { RESERVED_SYSTEM_PREFIXES, getRealtimeHub } from "../server/RealtimeHub.js";
 import { applyDeclaredBroadcastPrefixes } from "../../decorators/realtimeDecorators.js";
 import { Service } from "nodefony";
-//#region nodefony/src/service/RealtimeService.ts
+// nodefony/src/service/RealtimeService.ts
 const serviceName = "realtimeService";
 /**
 * Façade DI publique de la **socket Nodefony** côté serveur.
@@ -35,7 +36,7 @@ var RealtimeService = class extends Service {
 	#config = null;
 	#hub = null;
 	constructor(module) {
-		super(serviceName, module.container, module.notificationsCenter, module.options);
+		super(serviceName, module.container ?? void 0, module.notificationsCenter, module.options);
 		this.module = module;
 	}
 	/**
@@ -55,7 +56,7 @@ var RealtimeService = class extends Service {
 	*/
 	async init(_module) {
 		const config = this.module.config;
-		if (!config) throw new Error(`${serviceName}: realtimeConfig absente (this.module.config vide) — la Module class doit la valider à onKernelRegister`);
+		if (!isRealtimeConfig(config)) throw new Error(`${serviceName}: realtimeConfig absente (this.module.config vide) — la Module class doit la valider à onKernelRegister`);
 		this.#config = config;
 		if (!this.#config.enabled) {
 			this.log("realtime enabled:false → service inerte (hub non câblé)", "INFO");
@@ -237,5 +238,4 @@ function buildOriginGuard(config) {
 		return allowSet.has(origin);
 	};
 }
-//#endregion
 export { RealtimeService, RealtimeService as default };

package/dist/nodefony/src/transport/WsConnectionTransport.js

@@ -1,6 +1,6 @@
 import { TransportState } from "nodefony";
 import { decideSend } from "@nodefony/http";
-//#region nodefony/src/transport/WsConnectionTransport.ts
+// nodefony/src/transport/WsConnectionTransport.ts
 /**
 * Contre-pression WS — **la règle vit dans `@nodefony/http`**, ce transport ne
 * fait que l'appliquer (`decideSend`). Deux implémentations de la même
@@ -31,6 +31,8 @@ var WsConnectionTransport = class {
 	_bytesSent = 0;
 	_messagesSent = 0;
 	_dropped = 0;
+	_binaryDiscarded = 0;
+	_malformedDiscarded = 0;
 	_max;
 	_policy;
 	_closeAfterDrops;
@@ -51,6 +53,45 @@ var WsConnectionTransport = class {
 		this._messagesSent += 1;
 		this.conn.send(raw, () => {});
 	}
+	/**
+	* Émet des octets tels quels — trame binaire RFC 6455, hors JSON-RPC (#617).
+	* Même contre-pression (`decideSend`, la règle unique) et mêmes compteurs que
+	* {@link send}. Écrite à part, et non en factorisant `send` : `send` est le
+	* chemin de CHAQUE frame JSON-RPC, et n'y paie pas un appel de plus.
+	*
+	* @param data - les octets à émettre.
+	* @returns `true` si la trame est partie, `false` si la connexion était
+	*   fermée ou la contre-pression l'a jetée.
+	*/
+	sendBinary(data) {
+		if (this.conn.readyState !== TransportState.OPEN) return false;
+		if (decideSend(this.conn, this._max, this._policy, this._closeAfterDrops) !== "send") {
+			this._dropped += 1;
+			return false;
+		}
+		this._bytesSent += data.byteLength;
+		this._messagesSent += 1;
+		this.conn.send(data, () => {});
+		return true;
+	}
+	/**
+	* Compte une trame ENTRANTE écartée et rend le cumul de sa nature — `1` dit
+	* « première », le seul instant où l'appelant journalise.
+	*
+	* @param kind - `binary` (sans lecteur) ou `malformed` (texte non JSON).
+	* @returns le cumul de cette nature, après incrément.
+	*/
+	discard(kind) {
+		return kind === "binary" ? ++this._binaryDiscarded : ++this._malformedDiscarded;
+	}
+	/** Cumul de trames BINAIRES reçues et écartées faute de lecteur — monotone. */
+	get binaryDiscarded() {
+		return this._binaryDiscarded;
+	}
+	/** Cumul de trames TEXTE reçues et écartées parce que non JSON — monotone. */
+	get malformedDiscarded() {
+		return this._malformedDiscarded;
+	}
 	close(code, reason) {
 		this.conn.close(code, reason);
 	}
@@ -90,5 +131,4 @@ var WsConnectionTransport = class {
 		this._onClose?.(code, reason);
 	}
 };
-//#endregion
 export { WsConnectionTransport, WsConnectionTransport as default };

package/dist/nodefony/testing/index.js

@@ -1,5 +1,38 @@
+import { isRecord } from "../src/guards.js";
 import { getRealtimeHub } from "../src/server/RealtimeHub.js";
-//#region nodefony/testing/index.ts
+import { RequestContext } from "nodefony";
+// nodefony/testing/index.ts
+/**
+* `@nodefony/realtime/testing` — **harnais de test d'un controller temps réel**.
+*
+* Écrire un test de socket demandait jusqu'ici une centaine de lignes de
+* plomberie FRAMEWORK avant la première assertion : un faux `ContextType` qui ne
+* fournit que ce que la base touche, un pont vers `handleRealtime` (qui est
+* `protected`), la remise à zéro du hub — singleton par process — entre deux
+* cas, et la pose d'une identité au handshake. Cette plomberie se périme au
+* premier changement de signature de la base ; recopiée dans chaque application,
+* elle y aurait vieilli sans que personne ne le sache. Elle vit donc ICI, avec
+* le code dont elle dépend.
+*
+* Le harnais pilote le **côté serveur** : il injecte des frames JSON-RPC 2.0
+* telles qu'un client les enverrait, et lit celles qui sortent. Il n'embarque
+* PAS `NodefonySocket` — le client est un artefact navigateur du cœur, et le
+* tirer ici le ferait entrer dans le paquet serveur publié. Ce qu'on veut
+* prouver d'un controller (ses canaux, ses actions, son plein-duplex, son
+* nettoyage) s'observe entièrement aux frames.
+*
+* ```ts
+* import { createRealtimeHarness } from "@nodefony/realtime/testing";
+*
+* const h = createRealtimeHarness((ctx) => new ChatController(ctx));
+* await h.connect();
+* await h.subscribe("chat:ticker");
+* expect(h.messages("chat:ticker")).to.have.length.greaterThan(0);
+* h.dispose();
+* ```
+*
+* @packageDocumentation
+*/
 /** `readyState` d'une connexion WebSocket ouverte (`ws` / DOM). */
 const OPEN = 1;
 /** Laisse tourner les microtâches et les timers immédiats. */
@@ -21,6 +54,67 @@ async function waitFor(predicate, ticks) {
 	return predicate();
 }
 /**
+* Motifs de refus du protocole, rendus exhaustifs par le compilateur : un motif
+* ajouté à `IRealtimeDenied.reason` casse la compilation ICI, au lieu de faire
+* lever le harnais sur un refus légitime.
+*/
+const DENIED_REASONS = {
+	forbidden: true,
+	limit: true,
+	unknown: true
+};
+function isDeniedReason(reason) {
+	return Object.hasOwn(DENIED_REASONS, reason);
+}
+/** Erreur JSON-RPC 2.0 (§5.1) d'une trame, ou `null` si sa forme est fausse. */
+function readRpcError(error) {
+	if (!isRecord(error) || typeof error.code !== "number" || typeof error.message !== "string") return null;
+	return Object.hasOwn(error, "data") ? {
+		code: error.code,
+		message: error.message,
+		data: error.data
+	} : {
+		code: error.code,
+		message: error.message
+	};
+}
+/**
+* Lit une trame émise par le contrôleur sous test. Une trame dont un champ a
+* la mauvaise forme LÈVE : c'est un défaut du contrôleur, que le test doit
+* voir, pas une donnée à écarter.
+*/
+function readFrame(data) {
+	const value = JSON.parse(data);
+	const fault = () => /* @__PURE__ */ new Error(`createRealtimeHarness: trame JSON-RPC malformée émise — ${data}`);
+	if (!isRecord(value)) throw fault();
+	const { jsonrpc, id, method } = value;
+	if (jsonrpc !== void 0 && typeof jsonrpc !== "string") throw fault();
+	if (id !== void 0 && typeof id !== "number" && typeof id !== "string") throw fault();
+	if (method !== void 0 && typeof method !== "string") throw fault();
+	const error = Object.hasOwn(value, "error") ? readRpcError(value.error) : void 0;
+	if (error === null) throw fault();
+	return {
+		...jsonrpc === void 0 ? {} : { jsonrpc },
+		...id === void 0 ? {} : { id },
+		...method === void 0 ? {} : { method },
+		...Object.hasOwn(value, "params") ? { params: value.params } : {},
+		...Object.hasOwn(value, "result") ? { result: value.result } : {},
+		...error === void 0 ? {} : { error }
+	};
+}
+/** Lit le `params` d'un `realtime:denied` — lève si le contrôleur l'a mal formé. */
+function readDenied(params) {
+	if (isRecord(params) && typeof params.channel === "string" && typeof params.reason === "string" && isDeniedReason(params.reason) && (params.detail === void 0 || typeof params.detail === "string")) return params.detail === void 0 ? {
+		channel: params.channel,
+		reason: params.reason
+	} : {
+		channel: params.channel,
+		reason: params.reason,
+		detail: params.detail
+	};
+	throw new Error(`createRealtimeHarness: realtime:denied malformé — ${JSON.stringify(params)}`);
+}
+/**
 * Monte un controller temps réel sur une fausse connexion et rend de quoi le
 * piloter.
 *
@@ -53,7 +147,7 @@ function createRealtimeHarness(create, options = {}) {
 	const connection = {
 		readyState: OPEN,
 		send: (data, cb) => {
-			received.push(JSON.parse(data));
+			received.push(readFrame(data));
 			cb?.();
 		},
 		close: (code, reason) => {
@@ -64,6 +158,7 @@ function createRealtimeHarness(create, options = {}) {
 		}
 	};
 	const controller = create({
+		type: "websocket",
 		connection,
 		once: (event, fn) => {
 			if (event === "onFinish") onFinish = fn;
@@ -79,8 +174,16 @@ function createRealtimeHarness(create, options = {}) {
 	});
 	const bridge = controller;
 	let nextId = 1;
+	const identity = options.identity;
+	const handshakeStore = identity === void 0 ? { requestId: "realtime-harness" } : {
+		requestId: "realtime-harness",
+		token: identity,
+		user: identity.getAttribute("user")
+	};
 	const feed = async (frame) => {
-		bridge.handleRealtime(frame === null ? null : JSON.stringify(frame));
+		RequestContext.run(handshakeStore, () => {
+			bridge.handleRealtime(frame === null ? null : JSON.stringify(frame));
+		});
 		await tick();
 	};
 	const rpc = (payload) => ({
@@ -107,10 +210,21 @@ function createRealtimeHarness(create, options = {}) {
 			return welcome;
 		},
 		async subscribe(channel) {
+			const from = received.length;
 			await feed(rpc({
 				method: "subscribe",
 				params: { channel }
 			}));
+			await waitFor(() => {
+				for (let i = from; i < received.length; i++) {
+					const f = received[i];
+					if ((f?.method === "realtime:subscribed" || f?.method === "realtime:denied") && isRecord(f.params) && f.params["channel"] === channel) return true;
+				}
+				return false;
+			}, 20);
+		},
+		subscriptions() {
+			return received.filter((f) => f.method === "realtime:subscribed").map((f) => isRecord(f.params) ? String(f.params["channel"]) : "");
 		},
 		async unsubscribe(channel) {
 			await feed(rpc({
@@ -147,7 +261,7 @@ function createRealtimeHarness(create, options = {}) {
 			return received.filter((f) => f.method === channel && f.id === void 0).map((f) => f.params);
 		},
 		denials() {
-			return received.filter((f) => f.method === "realtime:denied").map((f) => f.params);
+			return received.filter((f) => f.method === "realtime:denied").map((f) => readDenied(f.params));
 		},
 		close() {
 			if (closed) return;
@@ -161,5 +275,4 @@ function createRealtimeHarness(create, options = {}) {
 		}
 	};
 }
-//#endregion
 export { createRealtimeHarness };

package/dist/types/index.d.ts

@@ -81,6 +81,7 @@ export { RealtimeAction, RealtimeBroadcast, RealtimeChannel, RealtimeInbound, ge
 export type { RealtimeChannelFactory } from "./nodefony/decorators/realtimeDecorators.js";
 export type { IRealtimeController, RealtimePublish, RealtimeInboundHandler, } from "./nodefony/interfaces/IRealtimeController.js";
 export type { IChannelPolicy } from "./nodefony/interfaces/IChannelPolicy.js";
+export type { IRealtimeConnectionState } from "./nodefony/interfaces/IRealtimeConnectionState.js";
 export type { IClientLogsLimits } from "./nodefony/interfaces/IClientLogsLimits.js";
 export { createSyslogUplinkHandler, BROWSER_ORIGIN, MAX_CLIENT_SEVERITY, } from "./nodefony/src/server/syslogUplink.js";
 export type { SyslogUplinkHandlerOptions, ClientSeverity, } from "./nodefony/src/server/syslogUplink.js";

package/dist/types/nodefony/config/configSchema.d.ts

@@ -0,0 +1,12 @@
+/**
+ * JSON Schema de la configuration de `@nodefony/realtime` — lu SANS démarrer
+ * l'application, par `nodefony env` et la notice `.env.example`, qui y
+ * trouvent les noms courts (`.meta({ env })`).
+ *
+ * Déclaré dans `package.json` → `nodefony.configSchema` ; le nom de l'export
+ * est FIXE. Fichier FEUILLE : il n'importe que zod et le schéma, et n'ouvre
+ * rien à l'import — une commande qui ne démarre pas l'application l'exécute.
+ *
+ * @returns le JSON Schema, métadonnées Nodefony comprises.
+ */
+export declare function configJsonSchema(): unknown;