@nodefony/realtime 10.0.0-beta.1 → 10.0.0-beta.3

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

@@ -1,3 +1,4 @@
+import { isRecord } from "../guards.js";
 import { ANONYMOUS_REALTIME_TOKEN } from "./AnonymousRealtimeToken.js";
 import { getRealtimeHub } from "./RealtimeHub.js";
 import { DEFAULT_ACTION_POLICY, getRealtimeActions, getRealtimeChannelPolicies, getRealtimeChannels, getRealtimeInbound } from "../../decorators/realtimeDecorators.js";
@@ -5,11 +6,16 @@ import { createSyslogUplinkHandler } from "./syslogUplink.js";
 import { WsConnectionTransport } from "../transport/WsConnectionTransport.js";
 import { welcomeEnv } from "./welcomeEnv.js";
 import { deniedDetail } from "./deniedDetail.js";
-import { BootConfigurationError, JsonRpcPeer, PLATFORM_INBOUND, RequestContext, RpcEnvelope, RpcError, Scope, identityHint } from "nodefony";
+import { BootConfigurationError, JsonRpcError, JsonRpcPeer, JsonRpcServerError, PLATFORM_INBOUND, RequestContext, RpcEnvelope, RpcError, Scope, identityHint, isJsonRpcId, isPromise, jsonRpcFailure } from "nodefony";
 import { readBackpressureOptions } from "@nodefony/http";
-import { Controller } from "@nodefony/framework";
+import { Controller, buildContextParamArgs, getParamArgsMeta } from "@nodefony/framework";
 //#region nodefony/src/server/RealtimeController.ts
 /**
+* Une action RPC n'a ni variables de route ni URL : `@Param` et `@Query` y
+* lisent cet objet vide.
+*/
+const NO_ROUTE_PARAMS = Object.freeze({});
+/**
 * Statut HTTP-équivalent d'une erreur survenue pendant une invocation du pont.
 *
 * UNE seule lecture pour les trois sources possibles — la `RpcError` déjà mappée
@@ -22,11 +28,11 @@ import { Controller } from "@nodefony/framework";
 */
 function httpStatusOfFrameError(e) {
 	if (e instanceof RpcError) {
-		const status = e.data?.status;
+		const status = isRecord(e.data) ? e.data.status : void 0;
 		if (typeof status === "number") return status;
-		return e.code === -32602 ? 400 : null;
+		return e.code === JsonRpcError.INVALID_PARAMS ? 400 : null;
 	}
-	const code = e.code;
+	const code = isRecord(e) ? e.code : void 0;
 	return typeof code === "number" && code >= 400 && code <= 599 ? code : null;
 }
 /**
@@ -40,7 +46,7 @@ function httpStatusOfFrameError(e) {
 function toFrameRpcError(e, status, requestId) {
 	if (e instanceof RpcError) {
 		if (!requestId) return e;
-		const data = typeof e.data === "object" && e.data !== null ? {
+		const data = isRecord(e.data) ? {
 			...e.data,
 			requestId
 		} : { requestId };
@@ -49,10 +55,23 @@ function toFrameRpcError(e, status, requestId) {
 	if (status !== null) {
 		const data = { status };
 		if (requestId) data.requestId = requestId;
-		return new RpcError(e instanceof Error ? e.message : String(e), -32e3, data);
+		return new RpcError(e instanceof Error ? e.message : String(e), JsonRpcServerError.DEFAULT, data);
 	}
 	return e;
 }
+/** Le canal nommé par les params d'un `subscribe`/`unsubscribe` — entrée réseau. */
+function channelParam(params) {
+	return isRecord(params) && typeof params.channel === "string" ? params.channel : void 0;
+}
+/**
+* Le serveur WebSocket qui sert la connexion, ou `null` — lu une fois par
+* poignée de main pour ses réglages de contre-pression. Un `WebSocketServer`
+* porte toujours ses `options` ; aucun serveur HTTP n'en déclare.
+*/
+function webSocketServerOf(ctx) {
+	const server = ctx.server;
+	return server && "options" in server ? server : null;
+}
 let warnedUnenforcedPolicies = false;
 /**
 * RealtimeController — base d'un endpoint WebSocket temps réel SERVEUR (JSON-RPC 2.0).
@@ -62,7 +81,7 @@ let warnedUnenforcedPolicies = false;
 * — écrit UNE fois, partagé par tous les modules. Un contrôleur concret ne déclare que
 * son métier : {@link createRealtimeChannel} (providers de canaux) + {@link realtimeActions}.
 *
-* Chaque connexion compose un `JsonRpcPeer` (le MÊME que `RealtimeClient` côté navigateur
+* Chaque connexion compose un `JsonRpcPeer` (le MÊME que `NodefonySocket` côté navigateur
 * — symétrie isomorphe) branché sur un {@link WsConnectionTransport}.
 *
 * Usage : le sous-classe garde sa route WS et délègue —
@@ -179,13 +198,13 @@ var RealtimeController = class extends Controller {
 	* est structurel, pas un choix : c'est au client d'attendre `realtime:welcome`
 	* avant de pousser.
 	*
-	* ⚠️ Cette phrase a longtemps ajouté « ce que `RealtimeClient` fait nativement ».
+	* ⚠️ Cette phrase a longtemps ajouté « ce que le client fait nativement ».
 	* C'était FAUX : le client rejouait ses abonnements dès l'ouverture de la socket,
 	* si bien qu'un `subscribe` posé avant le démarrage et TOUS ceux d'après une
 	* reconnexion étaient perdus ici même, sans un mot des deux côtés. Un contrat écrit
 	* d'un seul côté du fil n'est pas tenu ; il l'est désormais par
-	* `RealtimeClient.replaySubscriptions` et les deux cas « la fenêtre où le serveur
-	* écoute (welcome) » de `RealtimeClientCoverage.test.ts`.
+	* `NodefonySocket.replaySubscriptions` et les deux cas « la fenêtre où le serveur
+	* écoute (welcome) » de `NodefonySocketCoverage.test.ts`.
 	*/
 	handleRealtime(message) {
 		const ctx = this.context;
@@ -270,7 +289,7 @@ var RealtimeController = class extends Controller {
 			return;
 		}
 		else token = ANONYMOUS_REALTIME_TOKEN;
-		const transport = new WsConnectionTransport(conn, readBackpressureOptions(ctx.server ?? null));
+		const transport = new WsConnectionTransport(conn, readBackpressureOptions(webSocketServerOf(ctx)));
 		const peerOptions = {
 			send: (frame) => {
 				let json;
@@ -278,16 +297,9 @@ var RealtimeController = class extends Controller {
 					json = JSON.stringify(frame);
 				} catch (e) {
 					this.log(`WS realtime send: payload non sérialisable — ${e instanceof Error ? e.message : String(e)}`, "ERROR");
-					const id = frame.id;
-					if (id === void 0) return;
-					json = JSON.stringify({
-						jsonrpc: "2.0",
-						id,
-						error: {
-							code: -32603,
-							message: "internal error: non-serializable payload"
-						}
-					});
+					const id = isRecord(frame) ? frame.id : void 0;
+					if (!isJsonRpcId(id)) return;
+					json = JSON.stringify(jsonRpcFailure(id, JsonRpcError.INTERNAL_ERROR, "internal error: non-serializable payload"));
 				}
 				transport.send(json);
 			},
@@ -298,9 +310,10 @@ var RealtimeController = class extends Controller {
 		peerOptions.onFrameAudit = (reason, frame, auditedPeer) => {
 			if (reason !== "denied") return;
 			this.log("WS realtime frame refused by authorizer", "WARNING");
+			if (!isRecord(frame)) return;
 			const f = frame;
 			if (f.id !== void 0) return;
-			const channel = f.method === "subscribe" ? typeof f.params?.channel === "string" ? f.params.channel : void 0 : typeof f.method === "string" ? f.method : void 0;
+			const channel = f.method === "subscribe" ? channelParam(f.params) : typeof f.method === "string" ? f.method : void 0;
 			if (channel !== void 0) {
 				const hint = identityHint(this.kernel);
 				const denied = {
@@ -323,7 +336,7 @@ var RealtimeController = class extends Controller {
 			peer.receive(parsed);
 		});
 		const allActions = {
-			...getRealtimeActions(this),
+			...getRealtimeActions(this, this.actionParamsWrapper(ctx)),
 			...this.realtimeActions()
 		};
 		for (const [name, handler] of Object.entries(allActions)) {
@@ -414,11 +427,11 @@ var RealtimeController = class extends Controller {
 	*/
 	onRealtimeNotification(ctx, method, params) {
 		if (method === "subscribe") {
-			this.startChannel(ctx, params?.channel);
+			this.startChannel(ctx, channelParam(params));
 			return;
 		}
 		if (method === "unsubscribe") {
-			this.stopChannel(ctx, params?.channel);
+			this.stopChannel(ctx, channelParam(params));
 			return;
 		}
 		const state = ctx.__nfRealtime;
@@ -472,6 +485,48 @@ var RealtimeController = class extends Controller {
 		this.log(floor ? `WS subscribe refusé (canal de plateforme, aucun module de sécurité) → ${channel}` : `WS subscribe refusé (aucun producteur pour ce canal) → ${channel}`, "DEBUG");
 	}
 	/**
+	* Enveloppe des actions `@RealtimeAction` dont un paramètre est décoré
+	* (`@Body`, `@CurrentUser`…) : l'action reçoit ses arguments comme une route,
+	* résolus par la fonction du framework et non par une copie.
+	*
+	* L'identité ne change PAS : un message est déjà traité dans la bulle
+	* `RequestContext` du handshake (`WebsocketContext` lie son écouteur par
+	* `AsyncResource.bind`), où le pare-feu a posé `user` et `token`. La bulle
+	* ouverte ici HÉRITE de ce store et n'y ajoute que la charge (`body`, que
+	* `@Body` lit dans l'ALS comme pour `api.request`) — une écriture
+	* `RequestContext.set()` dans l'action reste ainsi propre à l'appel.
+	*
+	* Une action sans paramètre décoré est rendue telle quelle : rien ne change
+	* pour elle, ni comportement ni coût. Les métadonnées se lisent ICI, une fois
+	* par connexion.
+	*
+	* @param ctx - le contexte de la connexion
+	* @returns l'enveloppe passée à {@link getRealtimeActions}
+	*/
+	actionParamsWrapper(ctx) {
+		const proto = Reflect.getPrototypeOf(this);
+		return (method, propertyKey) => {
+			if (proto === null) return method;
+			const metas = getParamArgsMeta(proto, propertyKey);
+			if (metas === null) return method;
+			return (params) => {
+				const store = {
+					requestId: ctx.requestId,
+					...RequestContext.get(),
+					body: params
+				};
+				const result = RequestContext.run(store, () => method(...buildContextParamArgs(metas, ctx, NO_ROUTE_PARAMS, NO_ROUTE_PARAMS)));
+				if (isPromise(result)) {
+					const release = () => RequestContext.release(store);
+					result.then(release, release);
+					return result;
+				}
+				RequestContext.release(store);
+				return result;
+			};
+		};
+	}
+	/**
 	* Handler de la méthode RPC `api.request {path}` — le **pont API souverain**
 	* (POC Ph.3) : résout le path porté par le message via le Router
 	* (`cleanPathOverride` — l'URL de la connexion n'est jamais mutée) puis
@@ -491,13 +546,13 @@ var RealtimeController = class extends Controller {
 	* Tout autre throw de l'action reste opaque (`-32603`, Zero Trust).
 	*/
 	async invokeApiRequest(ctx, params, peer) {
-		const p = params;
+		const p = isRecord(params) ? params : void 0;
 		const path = p?.path;
-		if (typeof path !== "string" || path.charCodeAt(0) !== 47) throw new RpcError("api.request: params.path invalide", -32602);
+		if (typeof path !== "string" || path.charCodeAt(0) !== 47) throw new RpcError("api.request: params.path invalide", JsonRpcError.INVALID_PARAMS);
 		const method = typeof p?.method === "string" ? p.method.toUpperCase() : "GET";
-		if (method !== "GET" && method !== "POST" && method !== "PUT" && method !== "PATCH" && method !== "DELETE") throw new RpcError(`api.request: méthode ${method} non supportée`, -32602);
+		if (method !== "GET" && method !== "POST" && method !== "PUT" && method !== "PATCH" && method !== "DELETE") throw new RpcError(`api.request: méthode ${method} non supportée`, JsonRpcError.INVALID_PARAMS);
 		const router = ctx.router;
-		if (!router) throw new RpcError("api.request: router indisponible", -32e3, { status: 500 });
+		if (!router) throw new RpcError("api.request: router indisponible", JsonRpcServerError.DEFAULT, { status: 500 });
 		const qIdx = path.indexOf("?");
 		const pathname = qIdx === -1 ? path : path.slice(0, qIdx);
 		const frame = ctx.beginFrame(method, path);
@@ -509,7 +564,7 @@ var RealtimeController = class extends Controller {
 			} finally {
 				frame?.phaseEnd("resolve");
 			}
-			if (!resolver.resolve) throw new RpcError(`api.request: not found ${pathname}`, -32e3, { status: 404 });
+			if (!resolver.resolve) throw new RpcError(`api.request: not found ${pathname}`, JsonRpcServerError.DEFAULT, { status: 404 });
 			if (frame) frame.resolver = resolver;
 			if (qIdx !== -1 && qIdx < path.length - 1) {
 				const sp = new URLSearchParams(path.slice(qIdx + 1));
@@ -533,15 +588,14 @@ var RealtimeController = class extends Controller {
 				} finally {
 					frame?.phaseEnd("identity");
 				}
-				if (!valid) throw new RpcError("api.request: identité de session expirée ou invalide", -32e3, { status: 401 });
+				if (!valid) throw new RpcError("api.request: identité de session expirée ou invalide", JsonRpcServerError.DEFAULT, { status: 401 });
 			}
 			const renderSink = {};
-			const result = await RequestContext.run({
+			const store = {
 				requestId: ctx.requestId,
 				scheme: ctx.scheme,
 				token,
 				user: token.getAttribute("user"),
-				userId: token.getUserIdentifier(),
 				context: ctx,
 				resolver,
 				scope: ctx.container instanceof Scope ? ctx.container : void 0,
@@ -550,24 +604,40 @@ var RealtimeController = class extends Controller {
 				renderSink,
 				invocation: frame ?? void 0,
 				queries: frame?.profilerQueries ?? void 0
-			}, async () => {
-				frame?.phaseStart("action");
-				try {
-					const { result: actionResult } = await resolver.executeActionGuarded(void 0, true);
-					const raw = await Promise.resolve(actionResult);
-					if (renderSink.body !== void 0) {
-						const text = Buffer.isBuffer(renderSink.body) ? renderSink.body.toString("utf8") : renderSink.body;
-						try {
-							return JSON.parse(text);
-						} catch {
-							return text;
+			};
+			let result;
+			try {
+				result = await RequestContext.run(store, async () => {
+					frame?.phaseStart("action");
+					try {
+						const { result: actionResult } = await resolver.executeActionGuarded(void 0, true);
+						const raw = await Promise.resolve(actionResult);
+						if (renderSink.body !== void 0) {
+							const text = Buffer.isBuffer(renderSink.body) ? renderSink.body.toString("utf8") : renderSink.body;
+							let body;
+							try {
+								body = JSON.parse(text);
+							} catch {
+								body = text;
+							}
+							const status = renderSink.status;
+							if (status !== void 0 && status >= 400) {
+								const error = isRecord(body) ? body.error : void 0;
+								throw new RpcError(typeof error === "string" ? error : `api.request: HTTP ${status}`, JsonRpcServerError.DEFAULT, {
+									status,
+									body
+								});
+							}
+							return body;
 						}
+						return raw;
+					} finally {
+						frame?.phaseEnd("action");
 					}
-					return raw;
-				} finally {
-					frame?.phaseEnd("action");
-				}
-			});
+				});
+			} finally {
+				RequestContext.release(store);
+			}
 			frame?.finish(200);
 			return frame ? new RpcEnvelope(result, { requestId: frame.requestId }) : result;
 		} catch (e) {

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

@@ -1,6 +1,6 @@
 import { LoopbackBackplane } from "../backplane/LoopbackBackplane.js";
 import { ANONYMOUS_REALTIME_TOKEN } from "./AnonymousRealtimeToken.js";
-import { NODEFONY_CHANNEL_NAMESPACE, isPlatformChannel } from "nodefony";
+import { IDENTITY_REFRESH_CLOSE_CODE, NODEFONY_CHANNEL_NAMESPACE, REVOCATION_REVALIDATE_MS, RevocationWatch, isPlatformChannel } from "nodefony";
 //#region nodefony/src/server/RealtimeHub.ts
 /**
 * Seuil d'alerte slow-consumer (octets de `bufferedAmount`). Au-delà, la connexion
@@ -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

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

@@ -74,6 +74,14 @@ var ServerRealtimeSocket = class {
 	}
 	/** Branche un handler de réception sur un canal. Renvoie un `dispose`. */
 	on(channel, handler) {
+		return this.#addHandler(channel, handler);
+	}
+	/** Retire un handler d'un canal. */
+	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,10 +89,10 @@ 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);
 	}
 	/**
@@ -102,7 +110,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 +118,7 @@ var ServerRealtimeSocket = class {
 				};
 			},
 			send(payload) {
-				hub.publish(name, payload);
+				hub.hub.publish(name, payload);
 			},
 			open() {
 				hub.subscribe(name);

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

@@ -1,3 +1,4 @@
+import { isRecord } from "../guards.js";
 import { BROWSER_ORIGIN, Pdu } from "nodefony";
 //#region nodefony/src/server/syslogUplink.ts
 /**
@@ -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) ?? "";

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

@@ -1,3 +1,4 @@
+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";
@@ -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");

package/dist/nodefony/testing/index.js

@@ -1,5 +1,37 @@
 import { getRealtimeHub } from "../src/server/RealtimeHub.js";
+import { RequestContext } from "nodefony";
 //#region 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. */
@@ -79,8 +111,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) => ({

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;

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

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import type { z } from "zod";
 import { realtimeConfigSchema, type IRealtimeSchemaConfig } from "./config.js";
 import type { IBackplane } from "../interfaces/IBackplane.js";
 /**
@@ -19,11 +19,13 @@ import type { IBackplane } from "../interfaces/IBackplane.js";
  *   faire dans un JSON Schema Studio). L'instance, si fournie, prend précédence
  *   sur `driver` côté service ; ce dernier reste source d'introspection/UI.
  *
- * **Layering d'environnement** (convention-frère avec `REDIS_*` de
- * `@nodefony/redis`) : `NF_REALTIME_DRIVER` surcharge le driver backplane
- * APRÈS le parse (schéma pur, déterministe). Indispensable en déploiement
- * (k8s/Docker : `NF_REALTIME_DRIVER=redis`) et fiable quel que soit le
- * timing du merge `module-realtime` côté app (cf chantier ordering config).
+ * **Variables d'environnement** : `NF_REALTIME_DRIVER`,
+ * `NF_REALTIME_BACKPLANE_SECRET` et `NF_REALTIME_BACKPLANE_NAMESPACE` ne se
+ * lisent PAS ici. Chacune est déclarée sur son champ dans `config.ts`
+ * (`.meta({ env })`) et posée par le Kernel AVANT la validation : le schéma
+ * les valide comme une valeur de l'application (un secret de moins de 32
+ * caractères arrête le démarrage). Un appel direct de ce builder, hors Kernel,
+ * ne les voit donc pas.
  *
  * @param config - configuration brute (sections omises = défauts sûrs).
  * @param options.backplane - instance `IBackplane` custom (override le driver à
@@ -34,6 +36,27 @@ import type { IBackplane } from "../interfaces/IBackplane.js";
 export declare function defineRealtimeConfig(config?: IRealtimeConfigInput, options?: {
     backplane?: IBackplane;
 }): IRealtimeConfig;
+/**
+ * Le builder pour une entrée NON typée — la config reçue par le module au
+ * démarrage, dont le schéma décide seul de la forme. Interne au paquet : une
+ * application passe par {@link defineRealtimeConfig}, qui type ce qu'elle écrit.
+ *
+ * @param config - configuration brute, validée par le schéma
+ * @param options.backplane - instance `IBackplane` custom
+ * @returns config gelée prête pour `RealtimeService`.
+ * @throws BootConfigurationError si invalide.
+ */
+export declare function buildRealtimeConfig(config?: unknown, options?: {
+    backplane?: IBackplane;
+}): IRealtimeConfig;
+/**
+ * Vrai si la valeur est une config produite par {@link buildRealtimeConfig}
+ * (donc validée par le schéma). Lu une fois, à l'init du service.
+ *
+ * @param value - la config lue sur le module
+ * @returns `true` si elle sort du builder
+ */
+export declare function isRealtimeConfig(value: unknown): value is IRealtimeConfig;
 /**
  * JSON Schema introspectable de la config realtime — destiné au formulaire
  * d'édition Studio (futur). N'inclut PAS `backplane.instance` (non sérialisable).