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

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

@@ -5,11 +5,12 @@ import { DEFAULT_ACTION_POLICY, getRealtimeActions, getRealtimeChannelPolicies,
 import { createSyslogUplinkHandler } from "./syslogUplink.js";
 import { WsConnectionTransport } from "../transport/WsConnectionTransport.js";
 import { welcomeEnv } from "./welcomeEnv.js";
+import { subscribedAckFrame } from "./subscribedAck.js";
 import { deniedDetail } from "./deniedDetail.js";
 import { BootConfigurationError, JsonRpcError, JsonRpcPeer, JsonRpcServerError, PLATFORM_INBOUND, RequestContext, RpcEnvelope, RpcError, Scope, identityHint, isJsonRpcId, isPromise, jsonRpcFailure } from "nodefony";
-import { readBackpressureOptions } from "@nodefony/http";
-import { Controller, buildContextParamArgs, getParamArgsMeta } from "@nodefony/framework";
-//#region nodefony/src/server/RealtimeController.ts
+import { isWebsocketContext, readBackpressureOptions, toValidationFields } from "@nodefony/http";
+import { Controller, buildContextParamArgs, getParamArgsMeta, isFrameworkRouter } from "@nodefony/framework";
+// nodefony/src/server/RealtimeController.ts
 /**
 * Une action RPC n'a ni variables de route ni URL : `@Param` et `@Query` y
 * lisent cet objet vide.
@@ -32,6 +33,7 @@ function httpStatusOfFrameError(e) {
 		if (typeof status === "number") return status;
 		return e.code === JsonRpcError.INVALID_PARAMS ? 400 : null;
 	}
+	if (e instanceof Error && toValidationFields(e) !== null) return 422;
 	const code = isRecord(e) ? e.code : void 0;
 	return typeof code === "number" && code >= 400 && code <= 599 ? code : null;
 }
@@ -55,6 +57,10 @@ function toFrameRpcError(e, status, requestId) {
 	if (status !== null) {
 		const data = { status };
 		if (requestId) data.requestId = requestId;
+		if (status === 422 && e instanceof Error) {
+			const fields = toValidationFields(e);
+			if (fields !== null) data.fields = fields;
+		}
 		return new RpcError(e instanceof Error ? e.message : String(e), JsonRpcServerError.DEFAULT, data);
 	}
 	return e;
@@ -125,8 +131,20 @@ var RealtimeController = class extends Controller {
 	constructor(name, context) {
 		new.target.assertScope();
 		super(name, context);
+		this.#connection = isWebsocketContext(context) ? context : null;
 	}
 	/**
+	* La connexion WebSocket que sert CETTE instance — rétrécie UNE fois, ici,
+	* plutôt qu'à chaque frame.
+	*
+	* Sûr parce que l'instance est liée à sa connexion pour toute sa vie : la
+	* portée `singleton` est refusée au constructeur, et le contexte n'est posé
+	* qu'à la construction. `null` si la classe sert aussi une route HTTP et que
+	* cette instance en est issue. Le chemin de chaque frame lit ce champ au lieu
+	* de l'accesseur `context` : une lecture de champ, sans appel.
+	*/
+	#connection;
+	/**
 	* Map des factories de canaux EXACT, lue depuis les décorateurs `@RealtimeChannel`
 	* au handshake (cold-path) et mémoïsée par instance. `null` = pas de décorateur
 	* sur cette classe → la base court-circuite la lecture metadata par frame.
@@ -175,7 +193,7 @@ var RealtimeController = class extends Controller {
 		return {};
 	}
 	/**
-	* Opt-in du **pont API** (« API souveraine », POC Ph.3) : `true` → la
+	* Opt-in du **pont API** (une action, deux transports) : `true` → la
 	* connexion expose la méthode RPC `api.request {path}` qui re-route le path
 	* porté par le message vers l'action controller correspondante — la MÊME
 	* action que le GET REST (`socket.request("/nodefony/kernel/api/modules")`
@@ -207,8 +225,8 @@ var RealtimeController = class extends Controller {
 	* écoute (welcome) » de `NodefonySocketCoverage.test.ts`.
 	*/
 	handleRealtime(message) {
-		const ctx = this.context;
-		if (!ctx) return;
+		const ctx = this.#connection;
+		if (ctx === null) throw this.outsideWebsocketError();
 		if (message == null) {
 			this.onHandshake(ctx).catch((e) => {
 				this.log(`WS realtime handshake failed: ${e instanceof Error ? e.message : String(e)}`, "ERROR");
@@ -216,7 +234,28 @@ var RealtimeController = class extends Controller {
 			});
 			return;
 		}
-		ctx.__nfRealtime?.transport.feed(message.toString());
+		const state = ctx.__nfRealtime;
+		if (typeof message === "string") {
+			state?.transport.feed(message);
+			return;
+		}
+		if (state !== void 0) this.receiveBinary(state.transport, message);
+	}
+	/**
+	* Faute de câblage : `handleRealtime` reçu par une instance qui ne sert pas
+	* une connexion WebSocket — route sans `methods: ["WEBSOCKET"]`, ou faux
+	* contexte de test sans `type`. Levée plutôt que passée sous silence : le
+	* client attendrait un welcome qui ne vient jamais. Chemin froid.
+	*/
+	outsideWebsocketError() {
+		return /* @__PURE__ */ new TypeError(`${this.constructor.name}.handleRealtime : cette instance ne sert pas une connexion WebSocket (contexte de type « ${String(this.context?.type)} »). La route doit déclarer requirements: { methods: ["WEBSOCKET"] } ; un faux contexte de test déclare type: "websocket".`);
+	}
+	receiveBinary(transport, data) {
+		if (this.onRealtimeBinary !== void 0) {
+			this.onRealtimeBinary(data);
+			return;
+		}
+		if (transport.discard("binary") === 1) this.log("WS realtime : trame binaire reçue et écartée — le protocole est du JSON-RPC texte ; pour la lire, surcharger onRealtimeBinary()", "WARNING");
 	}
 	/**
 	* **L1 — duplex serveur→client.** Émet une REQUÊTE vers le client de CETTE
@@ -234,9 +273,9 @@ var RealtimeController = class extends Controller {
 	* @throws (rejet) si le handshake n'est pas terminé (aucun peer encore).
 	*/
 	requestClient(method, params, timeoutMs) {
-		const state = this.context.__nfRealtime;
+		const state = this.coldConnState();
 		if (!state) return Promise.reject(/* @__PURE__ */ new Error("requestClient: connexion realtime non établie (welcome non émis)"));
-		return state.peer.request(method, params, timeoutMs);
+		return state.peer.requestAs(method, params, timeoutMs);
 	}
 	/**
 	* Notification CIBLÉE serveur→client (sans réponse) vers CETTE connexion, hors
@@ -245,7 +284,27 @@ var RealtimeController = class extends Controller {
 	* handshake n'est pas terminé.
 	*/
 	notifyClient(method, params) {
-		this.context.__nfRealtime?.peer.notify(method, params);
+		this.#connection?.__nfRealtime?.peer.notify(method, params);
+	}
+	/**
+	* Émet une trame BINAIRE vers CETTE connexion, sans la sérialiser — pendant
+	* sortant de {@link onRealtimeBinary}, et de `NodefonySocket.sendBinary` côté
+	* client. Même contre-pression que les frames JSON-RPC.
+	*
+	* @param data - les octets à émettre (`Uint8Array`, donc un `Buffer` aussi).
+	* @returns `false` si le handshake n'est pas terminé, la connexion fermée ou
+	*   la trame jetée par la contre-pression.
+	*/
+	sendBinaryToClient(data) {
+		return this.coldConnState()?.transport.sendBinary(data) ?? false;
+	}
+	/**
+	* État realtime de CETTE connexion, `undefined` avant le welcome — pour les
+	* chemins FROIDS (requête sortante, binaire). `notifyClient` et la réception
+	* gardent leur lecture en ligne : ils sont sur le chemin de chaque frame.
+	*/
+	coldConnState() {
+		return this.#connection?.__nfRealtime;
 	}
 	/**
 	* Handshake : seams sécurité #4 (Origin RFC 6455 §10.2) + #2 (authenticator
@@ -263,8 +322,7 @@ var RealtimeController = class extends Controller {
 	*  - `authenticate` throw → code 4001 (`unauthorized`).
 	*/
 	async onHandshake(ctx) {
-		const holder = ctx;
-		if (holder.__nfRealtime?.welcomed) return;
+		if (ctx.__nfRealtime?.welcomed) return;
 		const conn = ctx.connection;
 		if (!conn) return;
 		const hub = getRealtimeHub();
@@ -331,6 +389,7 @@ var RealtimeController = class extends Controller {
 			try {
 				parsed = JSON.parse(raw);
 			} catch {
+				if (transport.discard("malformed") === 1) this.log("WS realtime : trame texte illisible (pas du JSON) reçue et écartée", "WARNING");
 				return;
 			}
 			peer.receive(parsed);
@@ -391,7 +450,7 @@ var RealtimeController = class extends Controller {
 			channels: /* @__PURE__ */ new Map(),
 			inbound
 		};
-		holder.__nfRealtime = state;
+		ctx.__nfRealtime = state;
 		ctx.once("onFinish", () => {
 			const liveHub = getRealtimeHub();
 			for (const [channel, sink] of state.channels) liveHub.unsubscribe(channel, sink);
@@ -409,6 +468,7 @@ var RealtimeController = class extends Controller {
 			protocol: "jsonrpc-2.0",
 			channels: announcedChannels,
 			methods: peer.methods,
+			subscriptionAcks: true,
 			...welcomeEnv(env),
 			identity: {
 				type: token.type,
@@ -441,11 +501,25 @@ var RealtimeController = class extends Controller {
 			handler(params, (payload) => state.peer.notify(method, payload));
 		}
 	}
+	/**
+	* Acquitte un abonnement ACCEPTÉ (`realtime:subscribed`) — le seul signal
+	* qui dise au client à partir de quand le flux du canal lui est livré.
+	*
+	* Un refus n'y passe jamais : il a `realtime:denied`. Cold path (1×/canal et
+	* par connexion).
+	*/
+	acknowledgeSubscription(state, channel) {
+		state.transport.send(subscribedAckFrame(channel));
+	}
 	/** Abonne la connexion à un canal via le hub partagé (idempotent par connexion). */
 	startChannel(ctx, channel) {
 		if (!channel) return;
 		const state = ctx.__nfRealtime;
-		if (!state || state.channels.has(channel)) return;
+		if (!state) return;
+		if (state.channels.has(channel)) {
+			this.acknowledgeSubscription(state, channel);
+			return;
+		}
 		const cap = getRealtimeHub().maxChannelsPerConnection;
 		if (cap !== null && state.channels.size >= cap) {
 			const denied = {
@@ -472,6 +546,7 @@ var RealtimeController = class extends Controller {
 		}, (payload) => JSON.stringify(JsonRpcPeer.buildNotification(channel, payload)))) {
 			state.channels.set(channel, sink);
 			if (isServedByPattern()) getRealtimeHub().noticeUnguardedDynamicChannel(channel);
+			this.acknowledgeSubscription(state, channel);
 			this.log(`WS subscribe → ${channel}`, "DEBUG");
 			return;
 		}
@@ -527,7 +602,7 @@ var RealtimeController = class extends Controller {
 		};
 	}
 	/**
-	* Handler de la méthode RPC `api.request {path}` — le **pont API souverain**
+	* Handler de la méthode RPC `api.request {path}` — le **pont socket**
 	* (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
 	* exécute l'action SANS la rendre (`executeAction`) : la valeur nue est
@@ -552,52 +627,21 @@ var RealtimeController = class extends Controller {
 		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`, JsonRpcError.INVALID_PARAMS);
 		const router = ctx.router;
-		if (!router) throw new RpcError("api.request: router indisponible", JsonRpcServerError.DEFAULT, { status: 500 });
+		if (!isFrameworkRouter(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);
+		let store = null;
 		try {
-			frame?.phaseStart("resolve");
-			let resolver;
-			try {
-				resolver = router.resolve(ctx, pathname, method === "GET" ? void 0 : method);
-			} finally {
-				frame?.phaseEnd("resolve");
-			}
-			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));
-				const query = {};
-				for (const [k, v] of sp) {
-					const prev = query[k];
-					if (prev === void 0) query[k] = v;
-					else if (Array.isArray(prev)) prev.push(v);
-					else query[k] = [prev, v];
-				}
-				resolver.queryOverride = query;
-			}
 			const token = getRealtimeHub().getTokenForPeer(peer);
-			if (token.isValid) {
-				let valid;
-				frame?.phaseStart("identity");
-				try {
-					valid = await token.isValid();
-				} catch {
-					valid = false;
-				} finally {
-					frame?.phaseEnd("identity");
-				}
-				if (!valid) throw new RpcError("api.request: identité de session expirée ou invalide", JsonRpcServerError.DEFAULT, { status: 401 });
-			}
 			const renderSink = {};
-			const store = {
-				requestId: ctx.requestId,
+			const frameStore = {
+				requestId: frame?.requestId ?? ctx.requestId,
 				scheme: ctx.scheme,
 				token,
 				user: token.getAttribute("user"),
 				context: ctx,
-				resolver,
+				resolver: void 0,
 				scope: ctx.container instanceof Scope ? ctx.container : void 0,
 				body: p?.body,
 				idempotencyKey: typeof p?.idempotencyKey === "string" ? p.idempotencyKey : void 0,
@@ -605,46 +649,77 @@ var RealtimeController = class extends Controller {
 				invocation: frame ?? void 0,
 				queries: frame?.profilerQueries ?? void 0
 			};
-			let result;
-			try {
-				result = await RequestContext.run(store, async () => {
-					frame?.phaseStart("action");
+			store = frameStore;
+			const result = await RequestContext.run(frameStore, async () => {
+				frame?.phaseStart("resolve");
+				let resolver;
+				try {
+					resolver = router.resolve(ctx, pathname, method === "GET" ? void 0 : method);
+				} finally {
+					frame?.phaseEnd("resolve");
+				}
+				if (!resolver.resolve) throw new RpcError(`api.request: not found ${pathname}`, JsonRpcServerError.DEFAULT, { status: 404 });
+				if (frame) frame.resolver = resolver;
+				frameStore.resolver = resolver;
+				if (qIdx !== -1 && qIdx < path.length - 1) {
+					const sp = new URLSearchParams(path.slice(qIdx + 1));
+					const query = {};
+					for (const [k, v] of sp) {
+						const prev = query[k];
+						if (prev === void 0) query[k] = v;
+						else if (Array.isArray(prev)) prev.push(v);
+						else query[k] = [prev, v];
+					}
+					resolver.queryOverride = query;
+				}
+				if (token.isValid) {
+					let valid;
+					frame?.phaseStart("identity");
 					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;
+						valid = await token.isValid();
+						if (valid && token.confirmAccount) valid = await token.confirmAccount();
+					} catch {
+						valid = false;
 					} finally {
-						frame?.phaseEnd("action");
+						frame?.phaseEnd("identity");
 					}
-				});
-			} finally {
-				RequestContext.release(store);
-			}
+					if (!valid) throw new RpcError("api.request: identité de session expirée ou invalide", JsonRpcServerError.DEFAULT, { status: 401 });
+				}
+				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");
+				}
+			});
 			frame?.finish(200);
-			return frame ? new RpcEnvelope(result, { requestId: frame.requestId }) : result;
+			return frame?.profiled ? new RpcEnvelope(result, { requestId: frame.requestId }) : result;
 		} catch (e) {
 			const status = httpStatusOfFrameError(e);
 			frame?.finish(status ?? 500, e);
-			throw toFrameRpcError(e, status, frame?.requestId);
+			throw toFrameRpcError(e, status, frame?.profiled ? frame.requestId : void 0);
 		} finally {
+			if (store !== null) RequestContext.release(store);
 			ctx.collectFrame(frame);
 		}
 	}
@@ -709,5 +784,4 @@ function handshakePath(ctx) {
 		return raw.charCodeAt(0) === 47 ? raw : "/";
 	}
 }
-//#endregion
 export { RealtimeController, RealtimeController as default };

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 { IDENTITY_REFRESH_CLOSE_CODE, NODEFONY_CHANNEL_NAMESPACE, REVOCATION_REVALIDATE_MS, RevocationWatch, isPlatformChannel } from "nodefony";
-//#region nodefony/src/server/RealtimeHub.ts
+// 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
@@ -789,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
@@ -921,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,11 +73,17 @@ 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. */
+	/** Retire un handler d'un canal — même frontière que {@link on}. */
 	off(channel, handler) {
 		this.#removeHandler(channel, handler);
 	}
@@ -96,9 +103,12 @@ var ServerRealtimeSocket = class {
 		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."));
@@ -174,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,6 +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`).
@@ -103,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

@@ -2,7 +2,7 @@ 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.
@@ -238,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 };