@nodefony/realtime 10.0.0-beta.3 → 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 { 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 };

package/dist/nodefony/testing/index.js

@@ -1,6 +1,7 @@
+import { isRecord } from "../src/guards.js";
 import { getRealtimeHub } from "../src/server/RealtimeHub.js";
 import { RequestContext } from "nodefony";
-//#region nodefony/testing/index.ts
+// nodefony/testing/index.ts
 /**
 * `@nodefony/realtime/testing` — **harnais de test d'un controller temps réel**.
 *
@@ -53,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.
 *
@@ -85,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) => {
@@ -96,6 +158,7 @@ function createRealtimeHarness(create, options = {}) {
 		}
 	};
 	const controller = create({
+		type: "websocket",
 		connection,
 		once: (event, fn) => {
 			if (event === "onFinish") onFinish = fn;
@@ -147,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({
@@ -187,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;
@@ -201,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/interfaces/IRealtimeConnectionState.d.ts

@@ -0,0 +1,40 @@
+import type { JsonRpcPeer } from "nodefony";
+import type { WsConnectionTransport } from "../src/transport/WsConnectionTransport.js";
+import type { ChannelSink } from "../src/server/RealtimeHub.js";
+import type { RealtimeInboundHandler } from "./IRealtimeController.js";
+/**
+ * État du protocole temps réel d'UNE connexion WebSocket — posé au welcome, et
+ * relu à chaque frame jusqu'à la fermeture.
+ *
+ * Il vit sur la CONNEXION (`WebsocketContext`), pas sur le contrôleur : un
+ * `forward` fait construire une instance neuve qui sert la même socket, et
+ * l'état doit lui survivre.
+ *
+ * Le pair y est rangé sous son contrat EFFACÉ, ce qu'il est d'ailleurs à sa
+ * construction. Plusieurs contrôleurs peuvent servir la même connexion, et aucun
+ * type ne relie cet état à l'un d'eux : chacun le relit sous son propre contrat
+ * (`RealtimeController.requestClient` → `JsonRpcPeer.requestAs`).
+ */
+export interface IRealtimeConnectionState {
+    /** `realtime:welcome` émis : la poignée de main ne se rejoue pas. */
+    welcomed: boolean;
+    /** Le pair JSON-RPC de la connexion, sous son contrat effacé. */
+    peer: JsonRpcPeer;
+    /** Le transport qui relie le pair à la socket (contre-pression, sonde). */
+    transport: WsConnectionTransport;
+    /** Canal → sink de CETTE connexion auprès du hub partagé, pour s'en désabonner. */
+    channels: Map<string, ChannelSink>;
+    /** Canaux full-duplex qui acceptent une entrée client ; `null` s'il n'y en a aucun. */
+    inbound: Record<string, RealtimeInboundHandler> | null;
+}
+declare module "@nodefony/http" {
+    interface IWebsocketConnectionState {
+        /**
+         * État du protocole temps réel de la connexion, posé par
+         * `@nodefony/realtime` au welcome ; `undefined` avant, et sur toute socket
+         * qu'aucun `RealtimeController` ne sert. Réservé au module : le lire,
+         * jamais l'écrire.
+         */
+        __nfRealtime?: IRealtimeConnectionState;
+    }
+}

package/dist/types/nodefony/interfaces/IRealtimeToken.d.ts

@@ -45,4 +45,17 @@ export interface IRealtimeToken {
      * (publish/subscribe), payé seulement sur `api.request`.
      */
     isValid?(nowMs?: number): boolean | Promise<boolean>;
+    /**
+     * Le COMPTE qui a ouvert la socket existe-t-il toujours, actif, et est-ce
+     * bien le même ? `false` si le compte a disparu, a été désactivé ou
+     * verrouillé, ou si un AUTRE compte a repris son identifiant (suppression
+     * hors framework puis recréation). Optionnel — absent = considéré confirmé.
+     *
+     * Distinct d'{@link isValid} parce que son coût l'est : il relit l'annuaire
+     * des comptes (une lecture, comme une requête HTTP en zone), là où
+     * `isValid` ne lit qu'un store de jetons ou de sessions. Appelé par le pont
+     * `api.request` SEULEMENT, jamais par la re-validation périodique du hub —
+     * qui le paierait pour chaque socket ouverte, à chaque tour.
+     */
+    confirmAccount?(): Promise<boolean>;
 }

package/dist/types/nodefony/interfaces/index.d.ts

@@ -11,6 +11,7 @@
 export type { IBackplane, IBackplaneMessage, BackplaneHandler, } from "./IBackplane.js";
 export type { IRealtimeController, RealtimePublish, RealtimeInboundHandler, } from "./IRealtimeController.js";
 export type { IChannelPolicy } from "./IChannelPolicy.js";
+export type { IRealtimeConnectionState } from "./IRealtimeConnectionState.js";
 export type { IRealtimeProbe, IRealtimeHealth, IRealtimeClusterHealth, IRealtimeChannelStat, IRealtimeConnProbe, } from "./IRealtimeProbe.js";
 export type { IRealtimeToken } from "./IRealtimeToken.js";
 export type { IRealtimeHandshake } from "./IRealtimeHandshake.js";

package/dist/types/nodefony/src/server/RealtimeController.d.ts

@@ -26,6 +26,7 @@ import type { IRealtimeController, RealtimePublish, RealtimeInboundHandler } fro
  * d'action n'est payé que sur une requête `id`. C'est aussi le seam du backplane Redis.
  */
 export declare abstract class RealtimeController<Emit extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap> extends Controller implements IRealtimeController {
+    #private;
     /**
      * Une instance PAR CONNEXION, par construction — le défaut `singleton` des
      * contrôleurs ne s'applique pas ici. Le pair JSON-RPC de la connexion capture
@@ -120,6 +121,39 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      * écoute (welcome) » de `NodefonySocketCoverage.test.ts`.
      */
     protected handleRealtime(message: string | Buffer | null): void;
+    /**
+     * Lit les trames BINAIRES de cette connexion — le point d'extension d'un
+     * protocole binaire écrit par l'application, à côté du JSON-RPC ; pendant
+     * serveur de `NodefonySocket.onBinary`.
+     *
+     * Le protocole temps réel est du JSON-RPC texte : il ne sait pas à quel canal
+     * une trame binaire appartient. Sans cette méthode, une trame binaire est
+     * écartée, comptée (`binaryDiscarded` de la sonde de connexion) et journalisée
+     * une fois par connexion. La surcharger la reçoit telle quelle, octets exacts,
+     * en `Uint8Array` — le type que livre aussi `NodefonySocket.onBinary` dans le
+     * navigateur : un décodeur s'écrit une fois pour les deux côtés. À l'exécution
+     * c'est un `Buffer` de `ws`, qui en est un.
+     *
+     * ⚠️ Hors du verrou de trame, et pour toute la série 10 : la trame brute ne
+     * passe ni par l'autorisation `beforeDispatch` ni par les gardes d'action et de
+     * canal du JSON-RPC. La connexion, elle, a déjà franchi Origin, l'authentificateur
+     * et le pare-feu. L'identité se lit par `RequestContext.getAuthenticatedUser()`,
+     * et toute décision d'accès sur une trame binaire appartient à l'application.
+     *
+     * ⚠️ Un `DataView` se construit sur `data.buffer` AVEC `data.byteOffset` et
+     * `data.byteLength` : un `Buffer` issu du pool de Node ne commence pas à 0.
+     *
+     * @param data - les octets reçus.
+     */
+    protected onRealtimeBinary?(data: Uint8Array): void;
+    /**
+     * 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.
+     */
+    private outsideWebsocketError;
+    private receiveBinary;
     /**
      * **L1 — duplex serveur→client.** Émet une REQUÊTE vers le client de CETTE
      * connexion (sur une action qu'il a exposée via `client.register(...)`) et attend
@@ -143,6 +177,22 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      * handshake n'est pas terminé.
      */
     protected notifyClient<K extends EventNames<Emit>>(method: K, params?: EventPayload<Emit, K>): void;
+    /**
+     * É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.
+     */
+    protected sendBinaryToClient(data: Uint8Array): boolean;
+    /**
+     * É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.
+     */
+    private coldConnState;
     /**
      * Handshake : seams sécurité #4 (Origin RFC 6455 §10.2) + #2 (authenticator
      * réseau) PUIS crée peer+transport, enregistre les actions, welcome + cleanup.
@@ -164,6 +214,14 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      * canaux FULL-DUPLEX déclarés (entrée client → handler `realtimeInbound`).
      */
     private onRealtimeNotification;
+    /**
+     * 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).
+     */
+    private acknowledgeSubscription;
     /** Abonne la connexion à un canal via le hub partagé (idempotent par connexion). */
     private startChannel;
     /**

package/dist/types/nodefony/src/server/ServerRealtimeSocket.d.ts

@@ -16,8 +16,9 @@ import { type IRealtimeSocket, type IRealtimeChannel, type IChannelStats, type R
  *    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.
@@ -25,7 +26,7 @@ import { type IRealtimeSocket, type IRealtimeChannel, type IChannelStats, type R
  * @typeParam Emit   — canaux pub/sub SORTANTS (`publish`) = ServerToClient.
  * @typeParam Listen — canaux pub/sub RÉCEPTIONNÉS (`subscribe`/`on`) = ClientToServer.
  */
-export declare class ServerRealtimeSocket<Emit extends EventsMap = DefaultEventsMap, Listen extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap> implements IRealtimeSocket<Emit, Listen, Actions> {
+export declare class ServerRealtimeSocket<Emit extends EventsMap = DefaultEventsMap, Listen extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap> implements IRealtimeSocket<Emit, Listen> {
     #private;
     private readonly hub;
     constructor(hub?: import("./RealtimeHub.js").RealtimeHub);
@@ -39,14 +40,23 @@ export declare class ServerRealtimeSocket<Emit extends EventsMap = DefaultEvents
     subscribe(channel: EventNames<Listen> | (string & {})): void;
     /** Désabonne (ref-compté) : coupe le sink du hub au DERNIER consommateur. */
     unsubscribe(channel: EventNames<Listen> | (string & {})): void;
-    /** 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<K extends string>(channel: K, handler: K extends EventNames<Listen> ? (payload: EventPayload<Listen, K>) => void : RealtimeHandler): () => void;
-    /** Retire un handler d'un canal. */
+    /** Retire un handler d'un canal — même frontière que {@link on}. */
     off<K extends string>(channel: K, handler: K extends EventNames<Listen> ? (payload: EventPayload<Listen, K>) => void : RealtimeHandler): void;
     /**
-     * **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<K extends string, T = unknown>(_method: K, _params?: ContractParams<Actions, K>, _timeoutMs?: number): Promise<ContractResult<Actions, K, T>>;
     /** Vue par-canal ({@link IRealtimeChannel}) — fine liaison sur les primitives. */

package/dist/types/nodefony/src/server/subscribedAck.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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
+ */
+/**
+ * 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.
+ */
+export declare function subscribedAckFrame(channel: string): string;