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

package/docs/configuration.md

@@ -57,8 +57,8 @@ est validé puis **gelé** avant que le moindre canal existe.
 flowchart TD
   SCHEMA["Schéma Zod du module<br/>realtimeConfigSchema — les valeurs d'usine"]
   APP["Ton application<br/>use('@nodefony/realtime', { … }) dans nodefony.config.ts"]
-  ENVGEN["Déploiement<br/>NF__REALTIME__&lt;CHEMIN&gt;=valeur"]
-  BUILD["Builder<br/>defineRealtimeConfig() : parse Zod → NF_REALTIME_DRIVER → freeze"]
+  ENVGEN["Déploiement<br/>NF_REALTIME_DRIVER · NF__REALTIME__&lt;CHEMIN&gt;=valeur"]
+  BUILD["Builder<br/>defineRealtimeConfig() : parse Zod → freeze"]
   HUB["RealtimeHub<br/>garde d'origine · plafond de canaux · seuil de sonde"]
   BP["Driver de backplane<br/>résolu par nom dans le registre"]
   SCHEMA --> APP --> ENVGEN --> BUILD
@@ -131,10 +131,11 @@ explication en `.describe()`. Les défauts effectifs sont **dérivés** du sché
 d'usine serait écrite, donc pas de dérive silencieuse possible entre la doc du champ et son
 comportement.
 
-Le builder `defineRealtimeConfig()` (`defineModuleConfig.ts:35`) reste **pur** : il analyse l'entrée,
-applique les variables d'environnement dédiées (`NF_REALTIME_DRIVER`,
-`NF_REALTIME_BACKPLANE_NAMESPACE`, `NF_REALTIME_BACKPLANE_SECRET` — toutes prioritaires sur le
-fichier), et gèle le résultat. Il ne décide rien.
+Le builder `defineRealtimeConfig()` (`defineModuleConfig.ts:39`) reste **pur** : il analyse l'entrée
+et gèle le résultat. Il ne lit aucune variable d'environnement. Les trois variables du module
+(`NF_REALTIME_DRIVER`, `NF_REALTIME_BACKPLANE_NAMESPACE`, `NF_REALTIME_BACKPLANE_SECRET`) sont
+déclarées sur leur champ dans le schéma (`.meta({ env })`, `config.ts:59`, `:76`, `:93`) et posées
+par le Kernel **avant** l'analyse : le schéma les valide comme une valeur écrite dans le fichier.
 
 Le module **augmente le registre de types** (`index.ts:167`) : `use("@nodefony/realtime", { … })`
 propose ses clés en autocomplétion et **refuse** une clé inconnue à la compilation.
@@ -251,7 +252,7 @@ regarder quand un message ne traverse pas.
 
 > [!TIP]
 > Ces quatre lignes viennent du même endroit du code (`Realtime.#wireBackplane()`,
-> `src/packages/@nodefony/realtime/index.ts:279`) et de la carte d'identité que chaque driver publie.
+> `src/packages/@nodefony/realtime/index.ts:292`) et de la carte d'identité que chaque driver publie.
 > Aucun repli n'est silencieux : si le fan-out est dégradé, c'est écrit.
 
 ## ⚙️ Le schéma, clé par clé
@@ -288,7 +289,7 @@ contre-pression, eux, se règlent sur le serveur WebSocket de `@nodefony/http`
 
 Poser `false` charge le module sans rien activer. Concrètement : pas d'API d'administration
 enregistrée, pas de backplane câblé, pas de sonde de pod
-(`Realtime.onKernelBoot()`, `src/packages/@nodefony/realtime/index.ts:239`), et le service devient
+(`Realtime.onKernelBoot()`, `src/packages/@nodefony/realtime/index.ts:246`), et le service devient
 inerte (`RealtimeService.init()`, `RealtimeService.ts:77`).
 
 > [!WARNING]
@@ -329,7 +330,7 @@ Ne concerne que les drivers qui traversent les machines. Le canal de transport d
 `nodefony:realtime:<namespace>` (`resolveRedisChannel()`, `RedisBackplane.ts:31`).
 
 Le défaut est **dérivé du nom de l'application**
-(`src/packages/@nodefony/realtime/index.ts:132`) — ce qui suffit à séparer deux applications
+(`src/packages/@nodefony/realtime/index.ts:139`) — ce qui suffit à séparer deux applications
 distinctes sur un Redis mutualisé, et **ne suffit pas** à séparer deux déploiements de la **même**
 application. Préproduction et production portent le même nom d'application, donc le même canal
 dérivé, donc le même flux.
@@ -377,13 +378,13 @@ jamais instancié, donc zéro minuteur, zéro message IPC — et l'endpoint de s
 de l'instance courante.
 
 Deux leviers coupent la sonde, et **l'un ou l'autre suffit** : cette clé, ou la variable
-`NF_CLUSTER_PROBE=0` (`src/packages/@nodefony/realtime/index.ts:391`). C'est ce qui permet
+`NF_CLUSTER_PROBE=0` (`src/packages/@nodefony/realtime/index.ts:404`). C'est ce qui permet
 d'éteindre une sonde sur un pod en incident sans redéployer une configuration.
 
 ### `slowConsumer.bytes` — un compteur, pas un frein
 
 Seuil de `bufferedAmount` — les octets en attente d'envoi sur une socket — au-delà duquel la sonde
-compte la connexion comme « lente » (`RealtimeHub.probe()`, `RealtimeHub.ts:865`).
+compte la connexion comme « lente » (`RealtimeHub.probe()`, `RealtimeHub.ts:847`).
 
 > [!IMPORTANT]
 > **Cette clé observe, elle n'agit pas.** Elle ne change que le compteur `slowConsumers` de la
@@ -439,7 +440,7 @@ des canaux d'état, où seul le dernier instantané compte.
 Chaque canal ouvert coûte un producteur côté hub, un minuteur le plus souvent, et une entrée de table
 côté connexion. Sans borne, **un seul** client peut s'abonner jusqu'à épuiser la mémoire du
 processus. Le plafond est vérifié à chaque abonnement (`RealtimeController.startChannel()`,
-`RealtimeController.ts:815`).
+`RealtimeController.ts:869`).
 
 Quatre propriétés qui décident du bon réglage :
 
@@ -450,7 +451,7 @@ Quatre propriétés qui décident du bon réglage :
 - Un réabonnement à un canal **déjà tenu** ne consomme pas de place — l'idempotence est vérifiée
   avant le plafond. Un client qui redemande son canal n'est pas puni.
 - La garde existe **même sans configuration** : le hub porte le même défaut de 256
-  (`RealtimeHub.ts:217`), il n'y a pas de fenêtre où elle serait absente.
+  (`RealtimeHub.ts:218`), il n'y a pas de fenêtre où elle serait absente.
 
 `null` retire la borne. C'est un retrait explicite, à réserver aux déploiements dont tu maîtrises
 les clients — un tableau de bord interne qui compose des dizaines de flux, par exemple.
@@ -462,7 +463,7 @@ les clients — un tableau de bord interne qui compose des dizaines de flux, par
 ### `csrf.checkOrigin` — qui a le droit d'ouvrir la socket
 
 Trois clés qui forment une seule politique, appliquée à l'ouverture de la connexion
-(`RealtimeHub.checkOrigin()`, `RealtimeHub.ts:986`). Une origine refusée ferme la socket avec le code
+(`RealtimeHub.checkOrigin()`, `RealtimeHub.ts:967`). Une origine refusée ferme la socket avec le code
 `4003`.
 
 Le défaut est **désactivé**. C'est le seul défaut du module qui n'est pas le réglage recommandé :
@@ -527,7 +528,7 @@ use("@nodefony/realtime", { backplane: { driver: "cluster" } });
 **Ce qui se passe.** Un worker Node ne peut parler qu'au maître. Il lui envoie ses publications, et le
 maître les redistribue aux autres workers. Le driver ne s'active qu'en **rôle worker** et avec la
 variable `NF_CLUSTER=1`, posée par la commande de cluster
-(`src/packages/@nodefony/realtime/index.ts:99`) ; ailleurs, il rend `null` et le hub reste local.
+(`src/packages/@nodefony/realtime/index.ts:106`) ; ailleurs, il rend `null` et le hub reste local.
 
 **Pourquoi c'est précieux.** C'est le banc d'essai qui stabilise l'architecture multi-processus avant
 d'ajouter du réseau. Ton contrôleur, tes canaux diffusables et ton client voient un vrai fan-out
@@ -552,7 +553,7 @@ use("@nodefony/realtime", {
 
 **Comment il se branche.** Le driver ne dépend pas de la bibliothèque `redis` : il consomme deux
 connexions du module `@nodefony/redis` par un adaptateur purement structurel
-(`createRedisServiceTransport()`, `RedisBackplane.ts:100`). Deux et non une, parce qu'un client Redis
+(`createRedisServiceTransport()`, `RedisBackplane.ts:137`). Deux et non une, parce qu'un client Redis
 abonné ne peut plus émettre de commandes ordinaires — le module fournit précisément des connexions
 nommées `publish` et `subscribe` dans ses défauts.
 
@@ -562,7 +563,7 @@ coupure. C'est acceptable pour un salon de discussion — le message est en base
 un bus d'événements critiques. Ne construis pas au-dessus une fiabilité que le support n'offre pas.
 
 **Si Redis est injoignable.** Le démarrage du backplane est attendu **explicitement**, et **borné à
-cinq secondes** (`src/packages/@nodefony/realtime/index.ts:83`). Au-delà, ou en cas d'échec, le
+cinq secondes** (`src/packages/@nodefony/realtime/index.ts:90`). Au-delà, ou en cas d'échec, le
 module renonce, ferme proprement ce qu'il avait ouvert, et laisse le hub local — le démarrage
 continue. Une base de messages en panne ne doit pas empêcher tes serveurs HTTP de monter.
 
@@ -650,7 +651,7 @@ présente court-circuite la sélection par nom.
 > Le builder accepte aussi une instance en second argument (`defineRealtimeConfig(config, {
 backplane })`), et la documentation d'architecture présente cette voie. En pratique elle n'est pas
 > atteignable depuis `nodefony.config.ts` : le module appelle le builder avec la seule configuration
-> fusionnée (`src/packages/@nodefony/realtime/index.ts:216`), et le schéma Zod est strict : une clé
+> fusionnée (`src/packages/@nodefony/realtime/index.ts:230`), et le schéma Zod est strict : une clé
 > inconnue, dont une instance de classe posée dans `backplane`, fait échouer le boot. Pour brancher un objet déjà construit, utilise
 > le service `realtimeBackplane`.
 
@@ -665,7 +666,7 @@ processus se raccorde — et c'est pour cela qu'elles ne vivent pas dans un fich
 
 | Variable                          | Portée                 | Effet                                                                      |
 | --------------------------------- | ---------------------- | -------------------------------------------------------------------------- |
-| `NF_REALTIME_DRIVER`              | ce module              | remplace `backplane.driver`. **Précédence maximale**                       |
+| `NF_REALTIME_DRIVER`              | ce module              | remplace `backplane.driver` — nom libre, un pilote inconnu est signalé     |
 | `NF_REALTIME_BACKPLANE_NAMESPACE` | ce module              | remplace `backplane.namespace` — sépare deux déploiements de la même app   |
 | `NF_REALTIME_BACKPLANE_SECRET`    | ce module              | remplace `backplane.secret` — scelle le transport partagé (≥ 32 car.)      |
 | `NF__REALTIME__<CHEMIN>`          | mécanisme du cœur      | remplace n'importe quelle clé, par son chemin. Ex. `NF__REALTIME__ENABLED` |
@@ -677,13 +678,15 @@ L'ordre de recouvrement, du plus faible au plus fort :
 
 1. **Les valeurs d'usine du schéma** — ce que tu obtiens sans rien écrire.
 2. **La configuration de l'application** — ton `use("@nodefony/realtime", { … })`.
-3. **`NF__REALTIME__<CHEMIN>`** — appliqué après la fusion et **avant** la validation Zod, donc la
-   valeur venue de l'environnement est validée comme les autres. Un chemin introuvable produit un
-   avertissement avec une suggestion, jamais une clé fantôme.
-4. **`NF_REALTIME_DRIVER`**, **`NF_REALTIME_BACKPLANE_NAMESPACE`** et
-   **`NF_REALTIME_BACKPLANE_SECRET`** — appliqués **après** l'analyse, dans le builder
-   (`defineModuleConfig.ts:41`). Ils gagnent sur tout le reste, y compris sur le mécanisme
-   générique `NF__REALTIME__BACKPLANE__…`.
+3. **`NF_REALTIME_DRIVER`**, **`NF_REALTIME_BACKPLANE_NAMESPACE`** et
+   **`NF_REALTIME_BACKPLANE_SECRET`** — posées par le Kernel après la fusion et **avant** la
+   validation Zod (`applyEnvShortcuts`, `Kernel.ts:1989`) : une valeur fausse **arrête le démarrage** en nommant la
+   variable (un secret de moins de 32 caractères, un espace de noms qui contient `:`). Chacune
+   accepte aussi sa forme `<NOM>_FILE` (secret monté par Docker ou Kubernetes).
+4. **`NF__REALTIME__<CHEMIN>`** — même moment, même validation. Un chemin introuvable produit un
+   avertissement avec une suggestion, jamais une clé fantôme. Viser le **même** champ qu'une des
+   trois variables ci-dessus est une ambiguïté : refusée en production, et en développement
+   `NF__…` l'emporte avec un avertissement qui nomme les deux.
 
 Le mécanisme générique mérite d'être connu : le double tiret bas sépare les niveaux, les segments
 sont insensibles à la casse, et les valeurs sont converties (booléens, nombres, listes séparées par
@@ -700,17 +703,19 @@ NF_CLUSTER_PROBE=0        # couper la sonde de pod sur une réplique en incident
 
 > [!TIP]
 > `NF_REALTIME_DRIVER` existe **en plus** du mécanisme générique parce qu'il est la variable qu'on
-> pose en premier sur un déploiement, et qu'elle doit rester fiable quel que soit le moment où la
-> configuration de l'application fusionne. C'est le levier d'urgence : ramener un cluster à
-> `loopback` pour isoler une panne de bus se fait par une variable, sans redéployer de code.
+> pose en premier sur un déploiement : son nom ne dépend pas de la structure interne de la
+> configuration. C'est le levier d'urgence : ramener un cluster à `loopback` pour isoler une panne
+> de bus se fait par une variable, sans redéployer de code. `npx nodefony env` la liste avec sa
+> valeur et sa provenance.
 
 ## 🧰 Le builder et le schéma exportable
 
 Deux fonctions publiques, utiles surtout aux tests et aux outils.
 
-`defineRealtimeConfig(config?, options?)` (`defineModuleConfig.ts:35`) analyse, applique la variable
-de driver et **gèle**. Le module l'appelle lui-même à l'enregistrement
-(`Realtime.onKernelRegister()`, `src/packages/@nodefony/realtime/index.ts:213`) : tu n'as pas à
+`defineRealtimeConfig(config?, options?)` (`defineModuleConfig.ts:39`) analyse et **gèle**. Appelé
+hors Kernel (un test, un outil), il ne voit pas les variables d'environnement : c'est le Kernel
+qui les pose. Le module l'appelle lui-même à l'enregistrement
+(`Realtime.onKernelRegister()`, `src/packages/@nodefony/realtime/index.ts:221`) : tu n'as pas à
 l'invoquer dans une application. En revanche, c'est l'outil qui permet de vérifier une configuration
 sans démarrer un serveur.
 
@@ -722,7 +727,7 @@ const cfg = defineRealtimeConfig({ backplane: { driver: "redis" } });
 // Une valeur invalide ou une clé inconnue lève une BootConfigurationError, avec le chemin exact du champ fautif.
 ```
 
-`realtimeConfigJsonSchema()` (`defineModuleConfig.ts:69`) produit le schéma JSON du module, chaque
+`realtimeConfigJsonSchema()` (`defineModuleConfig.ts:99`) produit le schéma JSON du module, chaque
 champ portant sa description. C'est ce que consomme la page module de Studio pour afficher la
 configuration attendue. L'instance de backplane éventuelle en est absente : une classe n'a rien à
 faire dans un schéma sérialisable.
@@ -762,7 +767,7 @@ Trois endroits, par ordre de fiabilité décroissante.
 | Baisser `slowConsumer.bytes` ne ferme pas les clients lents                         | cette clé ne pilote que le **comptage** de la sonde                                              | régler `websocketSecure.maxBackpressure` / `.backpressureCloseAfterDrops` (@nodefony/http) |
 | Toutes les connexions tombent en `4003` après activation du contrôle d'origine      | `allowList` vide, ou origine non identique au caractère près (port, schéma, sous-domaine)        | inscrire l'origine exacte ; un client non-navigateur relève de `allowMissingOrigin`        |
 | `enabled: false` posé « pour désactiver », et la garde d'origine ne s'applique plus | le service devient inerte et ne pose plus les politiques sur le hub                              | retirer le module du manifeste plutôt que l'éteindre                                       |
-| Le plafond de canaux semble ignoré en test                                          | il ne l'est pas : le hub porte le même défaut de 256 sans configuration (`RealtimeHub.ts:217`)   | vérifier le motif de refus `realtime:denied` côté client                                   |
+| Le plafond de canaux semble ignoré en test                                          | il ne l'est pas : le hub porte le même défaut de 256 sans configuration (`RealtimeHub.ts:218`)   | vérifier le motif de refus `realtime:denied` côté client                                   |
 
 ## 🧪 Tests & couverture
 

package/docs/cookbook-chat.md

@@ -353,7 +353,7 @@ gaspillerait une socket par écran.
 
 ```ts
 // frontend/src/realtime.ts
-import { RealtimeClient } from "nodefony/client";
+import { NodefonySocket } from "nodefony/client";
 
 // `wss` si la page est en HTTPS, `ws` sinon. Une application Nodefony sert en
 // HTTPS par défaut, y compris en développement : ce sera donc `wss` chez toi.
@@ -366,7 +366,7 @@ const scheme = window.location.protocol === "https:" ? "wss" : "ws";
  * La reconnexion automatique, le renvoi des abonnements après une coupure et le
  * heartbeat sont inclus — rien à écrire pour ça.
  */
-export const chatSocket = new RealtimeClient({
+export const chatSocket = new NodefonySocket({
   url: `${scheme}://${window.location.host}/chat/realtime`,
 });
 ```
@@ -445,7 +445,9 @@ import { ChatRoom } from "./ChatRoom";
 
 // La connexion s'ouvre UNE fois, au démarrage de l'application. Les hooks ne
 // gèrent que les abonnements : le cycle de vie de la socket reste à toi.
-void chatSocket.connect();
+// `connect()` rejette si cette première tentative échoue (serveur absent) ;
+// la socket se reconnecte seule ensuite, et l'état se lit par les hooks.
+chatSocket.connect().catch(() => {});
 
 createRoot(document.getElementById("app")!).render(
   <NodefonyProvider client={chatSocket}>
@@ -847,6 +849,7 @@ fonctionnent :
 // modules/chat/nodefony/controllers/ChatController.ts
 // → remplace `@RealtimeInbound("chat:send")` par une ACTION
 import { Body, CurrentUser, IsGranted } from "@nodefony/framework";
+import type { IUser } from "@nodefony/user";
 
 /**
  * L'envoi devient une action, joignable en POST HTTP comme par la socket.
@@ -860,7 +863,7 @@ import { Body, CurrentUser, IsGranted } from "@nodefony/framework";
 @IsGranted(["ROLE_USER"])
 async send(
   @Body() payload: { text?: string },
-  @CurrentUser() user?: { identifier?: string },
+  @CurrentUser() user: IUser,
 ) {
   const text = typeof payload?.text === "string" ? payload.text.trim() : "";
   if (text.length === 0 || text.length > 2000) {
@@ -869,7 +872,7 @@ async send(
 
   // L'auteur vient du SERVEUR. Le client ne peut plus mentir dessus.
   const message: ChatMessage = {
-    author: user?.identifier ?? "inconnu",
+    author: user.identifier,
     text,
     sentAt: Date.now(),
   };
@@ -1218,6 +1221,7 @@ import {
 import type { RealtimePublish } from "@nodefony/realtime";
 import { HttpError } from "@nodefony/http";
 import type { ContextType, IUploadedFile } from "@nodefony/http";
+import type { IUser } from "@nodefony/user";
 
 /** Un message tel qu'il circule sur le canal du salon. */
 export interface ChatMessage {
@@ -1288,14 +1292,14 @@ class ChatController extends RealtimeController {
   @IsGranted(["ROLE_USER"])
   async send(
     @Body() payload: { text?: string },
-    @CurrentUser() user?: { identifier?: string },
+    @CurrentUser() user: IUser,
   ): Promise<{ ok: true; sentAt: number }> {
     const text = typeof payload?.text === "string" ? payload.text.trim() : "";
     if (text.length === 0 || text.length > 2000) {
       throw new HttpError("message vide ou trop long", 400);
     }
     const message: ChatMessage = {
-      author: user?.identifier ?? "inconnu",
+      author: user.identifier,
       text,
       sentAt: Date.now(),
     };
@@ -1312,13 +1316,13 @@ class ChatController extends RealtimeController {
   @IsGranted(["ROLE_USER"])
   async upload(
     @UploadedFile() file?: IUploadedFile,
-    @CurrentUser() user?: { identifier?: string },
+    @CurrentUser() user: IUser,
   ): Promise<{ ok: true; filename: string; size: number }> {
     if (!file) {
       throw new HttpError("aucun fichier reçu", 400);
     }
     const announcement: ChatAttachment = {
-      author: user?.identifier ?? "inconnu",
+      author: user.identifier,
       filename: file.filename,
       size: file.size,
       mimeType: file.mimeType,
@@ -1599,23 +1603,23 @@ Pour qui veut lire l'implémentation derrière chaque étape :
 <!-- prettier-ignore -->
 | Ce que tu as utilisé | Où c'est écrit |
 | --- | --- |
-| Les trois décorateurs | `RealtimeAction()` (`realtimeDecorators.ts:101`), `RealtimeChannel()` (`realtimeDecorators.ts:192`), `RealtimeInbound()` (`realtimeDecorators.ts:231`) |
-| La porte WebSocket | `RealtimeController.handleRealtime()` (`RealtimeController.ts:299`) |
-| Le pont HTTP ⇄ WebSocket | `RealtimeController.realtimeApiRequest()` (`RealtimeController.ts:276`) |
-| L'abonnement et son cycle de vie | `RealtimeHub.subscribe()` (`RealtimeHub.ts:462`), `RealtimeController.startChannel()` (`RealtimeController.ts:815`) |
-| La publication et le fan-out | `RealtimeHub.publish()` (`RealtimeHub.ts:604`), réinjection locale `RealtimeHub.publishLocal()` (`RealtimeHub.ts:623`) |
-| Les canaux diffusables | `RealtimeBroadcast` (`realtimeDecorators.ts:342`), `RealtimeHub.markBroadcastChannel()` (`RealtimeHub.ts:668`) |
-| Le branchement du backplane | `RealtimeHub.setBackplane()` (`RealtimeHub.ts:714`), registre `registerBackplaneDriver()` (`backplaneRegistry.ts:55`), cloison `resolveBackplaneOriginId()` (`originId.ts:24`) |
-| Les politiques de canal | `IChannelPolicy` (`IChannelPolicy.ts:20`), `RealtimeHub.registerChannelPolicy()` (`RealtimeHub.ts:1143`), garde-fou `RealtimeHub.hasUnenforcedChannelPolicies()` (`RealtimeHub.ts:1117`) |
-| Le branchement automatique du firewall | `Firewall.#wireRealtime()` (`firewall.ts:279`) |
-| Les refus | `IRealtimeDenied` (`RealtimeEventMap.ts:269`), erreur `unauthorized` (`JsonRpcPeer.ts:417`), fermetures `origin not allowed` (`RealtimeController.ts:327`) et `unauthorized` (`RealtimeController.ts:397`) |
-| La révocation en cours de session | `RealtimeHub.revalidateRevocable()` (`RealtimeHub.ts:826`) |
-| Le consommateur lent | seuil `SLOW_CONSUMER_BYTES` (`RealtimeHub.ts:56`), fermeture `slow consumer` (`RealtimeHub.ts:63`) |
-| Le plafond de canaux | `RealtimeHub.maxChannelsPerConnection` (`RealtimeHub.ts:1000`) |
+| Les trois décorateurs | `RealtimeAction()` (`realtimeDecorators.ts:191`), `RealtimeChannel()` (`realtimeDecorators.ts:240`), `RealtimeInbound()` (`realtimeDecorators.ts:278`) |
+| La porte WebSocket | `RealtimeController.handleRealtime()` (`RealtimeController.ts:344`) |
+| Le pont HTTP ⇄ WebSocket | `RealtimeController.realtimeApiRequest()` (`RealtimeController.ts:321`) |
+| L'abonnement et son cycle de vie | `RealtimeHub.subscribe()` (`RealtimeHub.ts:464`), `RealtimeController.startChannel()` (`RealtimeController.ts:869`) |
+| La publication et le fan-out | `RealtimeHub.publish()` (`RealtimeHub.ts:610`), réinjection locale `RealtimeHub.publishLocal()` (`RealtimeHub.ts:629`) |
+| Les canaux diffusables | `RealtimeBroadcast` (`realtimeDecorators.ts:420`), `RealtimeHub.markBroadcastChannel()` (`RealtimeHub.ts:674`) |
+| Le branchement du backplane | `RealtimeHub.setBackplane()` (`RealtimeHub.ts:720`), registre `registerBackplaneDriver()` (`backplaneRegistry.ts:55`), cloison `resolveBackplaneOriginId()` (`originId.ts:24`) |
+| Les politiques de canal | `IChannelPolicy` (`IChannelPolicy.ts:20`), `RealtimeHub.registerChannelPolicy()` (`RealtimeHub.ts:1124`), garde-fou `RealtimeHub.hasUnenforcedChannelPolicies()` (`RealtimeHub.ts:1098`) |
+| Le branchement automatique du firewall | `Firewall.#wireRealtime()` (`firewall.ts:306`) |
+| Les refus | `IRealtimeDenied` (`RealtimeEventMap.ts:269`), erreur `unauthorized` (`JsonRpcPeer.ts:449`), fermetures `origin not allowed` (`RealtimeController.ts:422`) et `unauthorized` (`RealtimeController.ts:444`) |
+| La révocation en cours de session | `RealtimeHub.revalidateRevocable()` (`RealtimeHub.ts:815`) |
+| Le consommateur lent | seuil `SLOW_CONSUMER_BYTES` (`RealtimeHub.ts:66`), fermeture `slow consumer` (`RealtimeHub.ts:64`) |
+| Le plafond de canaux | `RealtimeHub.maxChannelsPerConnection` (`RealtimeHub.ts:981`) |
 | L'accueil et l'identité | `IRealtimeWelcome` (`RealtimeEventMap.ts:231`) |
-| La sonde | `RealtimeHub.probe()` (`RealtimeHub.ts:865`), `IRealtimeProbe` (`IRealtimeProbe.ts:61`), `IRealtimeChannelStat` (`IRealtimeProbe.ts:47`) |
+| La sonde | `RealtimeHub.probe()` (`RealtimeHub.ts:847`), `IRealtimeProbe` (`IRealtimeProbe.ts:61`), `IRealtimeChannelStat` (`IRealtimeProbe.ts:47`) |
 | Le point de mesure d'administration | `createRealtimeAdminApi()` (`RealtimeAdminApi.ts:98`), `buildRealtimeHealth()` (`RealtimeAdminApi.ts:74`), `buildOwnHealth()` (`RealtimeAdminApi.ts:52`) |
-| Le service injectable | `RealtimeService.publish()` (`RealtimeService.ts:161`), `RealtimeService.probe()` (`RealtimeService.ts:213`), `RealtimeService.markBroadcastChannel()` (`RealtimeService.ts:222`) |
-| Les hooks React | `useNodefony()` (`client/react/index.ts:145`), `useNodefonyState()` (`client/react/index.ts:163`), `useNodefonyIdentity()` (`client/react/index.ts:182`), `useNodefonyChannel()` (`client/react/index.ts:198`), `useNodefonyChannelData()` (`client/react/index.ts:221`), `useNodefonyAdaptiveChannel()` (`client/react/index.ts:255`) |
-| Le client navigateur | `RealtimeClient.connect()` (`RealtimeClient.ts:389`), `RealtimeClient.subscribe()` (`RealtimeClient.ts:530`), `RealtimeClient.request()` (`RealtimeClient.ts:729`), `RealtimeClient.onDenied()` (`RealtimeClient.ts:471`) |
-| L'upload | `UploadedFile` (`routerDecorators.ts:1286`), `IUploadedFile` (`IUpload.ts:49`), `queryFile` (`Request.ts:226`) |
+| Le service injectable | `RealtimeService.publish()` (`RealtimeService.ts:161`), `RealtimeService.probe()` (`RealtimeService.ts:218`), `RealtimeService.markBroadcastChannel()` (`RealtimeService.ts:222`) |
+| Les hooks React | `useNodefony()` (`client/react/index.ts:255`), `useNodefonyState()` (`client/react/index.ts:273`), `useNodefonyIdentity()` (`client/react/index.ts:292`), `useNodefonyChannel()` (`client/react/index.ts:308`), `useNodefonyChannelData()` (`client/react/index.ts:332`), `useNodefonyAdaptiveChannel()` (`client/react/index.ts:367`) |
+| Le client navigateur | `NodefonySocket.connect()` (`NodefonySocket.ts:592`), `NodefonySocket.subscribe()` (`NodefonySocket.ts:739`), `NodefonySocket.request()` (`NodefonySocket.ts:936`), `NodefonySocket.onDenied()` (`NodefonySocket.ts:678`) |
+| L'upload | `UploadedFile` (`routerDecorators.ts:1311`), `IUploadedFile` (`IUpload.ts:49`), `queryFile` (`Request.ts:215`) |

package/docs/index.md

@@ -37,7 +37,7 @@ coverageModule: realtime
 
 ## 🧭 Par où commencer
 
-Trois parcours selon ce que tu viens faire. L'ordre compte : chaque étape suppose la précédente.
+Quatre parcours selon ce que tu viens faire. L'ordre compte : chaque étape suppose la précédente.
 
 **Je découvre le temps réel Nodefony** — comprendre le modèle avant d'écrire quoi que ce soit.
 
@@ -69,20 +69,31 @@ abonné connecté à l'autre.
 3. [`@nodefony/security`](../../security/docs/index.md) — le pare-feu applicatif, qui protège le
    temps réel avec **le même** modèle de zones que le web.
 
+**Un client ne suit plus** — l'écran prend du retard, la mémoire du serveur monte, une connexion
+se ferme en `1013`.
+
+1. [Cadence et contre-pression](./cadence-et-contre-pression.md) — les deux étages qui encaissent
+   un client lent : la cadence que le client ralentit lui-même, la file que le serveur refuse de
+   laisser grossir. **Commence par le schéma général**, puis les courbes.
+2. [Observabilité](./observabilite.md) — lire les clients lents et les trames refusées dans la
+   sonde, avant que quelqu'un ne se plaigne.
+3. [Configuration](./configuration.md) — serrer les seuils, sur les **deux** serveurs WebSocket.
+
 ## 🗂️ Les pages du module
 
 Le tableau pour choisir en cinq secondes ; les cards en dessous pour savoir ce qu'on y trouve.
 
-| Page                                     | Ce qu'elle résout                                  | Tu en as besoin quand…                       |
-| ---------------------------------------- | -------------------------------------------------- | -------------------------------------------- |
-| [Vocabulaire](./vocabulaire.md)          | les mots du domaine, une bonne fois                | tu lis la doc, ou tu discutes archi          |
-| [Architecture](./architecture.md)        | le trajet d'une frame, étage par étage             | tu veux comprendre plutôt que régler         |
-| [Configuration](./configuration.md)      | drivers, cloisonnement, bornes, contrôle d'origine | tu déploies, ou tu changes de topologie      |
-| [Sécurité](./securite.md)                | identité à la poignée de main, droits par canal    | ta socket est joignable depuis un navigateur |
-| [Protocole](./protocole.md)              | la grammaire d'une frame, et les codes d'erreur    | tu débogues le fil, ou tu écris un client    |
-| [Actions RPC](./actions.md)              | appeler le serveur et attendre une réponse         | tu veux savoir si l'appel a marché           |
-| [Observabilité](./observabilite.md)      | la sonde, les canaux de santé, les écrans          | tu te demandes si ta socket va bien          |
-| [Cookbook — un chat](./cookbook-chat.md) | l'exemple complet, client et serveur               | tu veux du code qui marche tout de suite     |
+| Page                                                          | Ce qu'elle résout                                  | Tu en as besoin quand…                        |
+| ------------------------------------------------------------- | -------------------------------------------------- | --------------------------------------------- |
+| [Vocabulaire](./vocabulaire.md)                               | les mots du domaine, une bonne fois                | tu lis la doc, ou tu discutes archi           |
+| [Architecture](./architecture.md)                             | le trajet d'une frame, étage par étage             | tu veux comprendre plutôt que régler          |
+| [Configuration](./configuration.md)                           | drivers, cloisonnement, bornes, contrôle d'origine | tu déploies, ou tu changes de topologie       |
+| [Sécurité](./securite.md)                                     | identité à la poignée de main, droits par canal    | ta socket est joignable depuis un navigateur  |
+| [Protocole](./protocole.md)                                   | la grammaire d'une frame, et les codes d'erreur    | tu débogues le fil, ou tu écris un client     |
+| [Actions RPC](./actions.md)                                   | appeler le serveur et attendre une réponse         | tu veux savoir si l'appel a marché            |
+| [Observabilité](./observabilite.md)                           | la sonde, les canaux de santé, les écrans          | tu te demandes si ta socket va bien           |
+| [Cadence et contre-pression](./cadence-et-contre-pression.md) | un client trop lent : ralentir, refuser, couper    | un écran prend du retard, ou la mémoire monte |
+| [Cookbook — un chat](./cookbook-chat.md)                      | l'exemple complet, client et serveur               | tu veux du code qui marche tout de suite      |
 
 ```nodefony-cards
 [
@@ -107,6 +118,9 @@ Le tableau pour choisir en cinq secondes ; les cards en dessous pour savoir ce q
   { "icon": "📡", "title": "observabilite", "href": "./observabilite.md",
     "desc": "Ce que la sonde du hub expose, les canaux de santé et leur cadence, ce que Studio en montre — et comment écrire la sienne sans faire fuir la mémoire ni empêcher le processus de s'arrêter.",
     "meta": "tu te demandes si ta socket va bien" },
+  { "icon": "🚦", "title": "cadence-et-contre-pression", "href": "./cadence-et-contre-pression.md",
+    "desc": "Deux étages qui ne se parlent pas et se rencontrent quand même : le client ralentit la cadence de ses canaux d'état (AIMD), le serveur refuse d'empiler au-delà de 4 Mio puis ferme en 1013. Avec les courbes calculées par le vrai code, et les sondes qui le montrent en production.",
+    "meta": "un écran prend du retard, ou la mémoire du serveur monte" },
   { "icon": "🍳", "title": "cookbook-chat", "href": "./cookbook-chat.md",
     "desc": "Un salon de discussion complet : configuration, service métier, contrôleur, client navigateur, puis le passage en cluster.",
     "meta": "du code qui tourne, à déformer vers ton besoin" }
@@ -119,18 +133,18 @@ Quatre propriétés, toutes vérifiables dans le code — c'est ce qui justifie
 WebSocket brute.
 
 **Un contrôleur temps réel est un contrôleur.** `RealtimeController`
-(`RealtimeController.ts:144`) étend le `Controller` du framework : il se déclare avec les mêmes
+(`RealtimeController.ts:203`) étend le `Controller` du framework : il se déclare avec les mêmes
 décorateurs de route, reçoit la même injection, passe par le même pare-feu. HTTP et WebSocket ne sont
 pas deux applications à écrire deux fois, mais deux entrées du même pipeline.
 
 **Une connexion, N canaux, dans les deux sens.** Le client s'abonne à autant de canaux qu'il veut sur
 la même socket. Trois formes de trafic coexistent : le serveur diffuse (`@RealtimeChannel`,
-`realtimeDecorators.ts:192`), le client appelle et attend une réponse (`@RealtimeAction`,
-`realtimeDecorators.ts:142`), le client pousse sans attendre (`@RealtimeInbound`,
-`realtimeDecorators.ts:231`). Rien n'est ouvert qui n'ait été déclaré.
+`realtimeDecorators.ts:240`), le client appelle et attend une réponse (`@RealtimeAction`,
+`realtimeDecorators.ts:191`), le client pousse sans attendre (`@RealtimeInbound`,
+`realtimeDecorators.ts:278`). Rien n'est ouvert qui n'ait été déclaré.
 
 **Le travail est fait une fois par processus, pas une fois par client.** Le `RealtimeHub`
-(`RealtimeHub.ts:213`) tient **un seul producteur par canal** : le premier abonné le démarre, le
+(`RealtimeHub.ts:214`) tient **un seul producteur par canal** : le premier abonné le démarre, le
 dernier départ l'arrête. Chaque connexion supplémentaire n'ajoute qu'une destination de diffusion.
 Un salon suivi par mille personnes coûte un producteur, pas mille.
 
@@ -143,7 +157,7 @@ toucher au cœur.
 > [!IMPORTANT]
 > **Rien ne franchit la frontière du processus sans intention explicite.** Par défaut, un canal reste
 > local. Il faut le déclarer diffusable (`@RealtimeBroadcast`,
-> `realtimeDecorators.ts:342`) pour qu'il emprunte le backplane. C'est volontaire : un canal
+> `realtimeDecorators.ts:420`) pour qu'il emprunte le backplane. C'est volontaire : un canal
 > d'observation qui décrit l'état d'**un** pod n'aurait aucun sens répliqué sur les autres.
 
 Le module se déclare par ailleurs **non critique** (`Realtime.critical`, `index.ts:144`) et son
@@ -239,11 +253,11 @@ export default ChatController;
 Le client est isomorphe : c'est le cœur `nodefony` lui-même, importable côté navigateur.
 
 ```ts
-import { RealtimeClient } from "nodefony/client";
+import { NodefonySocket } from "nodefony/client";
 
 // `shared` réutilise la connexion existante pour une même URL : dix composants
 // qui écoutent dix canaux ouvrent UNE socket, pas dix.
-const socket = RealtimeClient.shared({
+const socket = NodefonySocket.shared({
   url: "wss://127.0.0.1:5152/chat/realtime",
 });
 
@@ -295,7 +309,7 @@ Côté serveur : `RealtimeController` (la classe à étendre), les décorateurs
 publier depuis n'importe quel service injecté, le `RealtimeHub` et sa sonde, les trois backplanes
 natifs, et le registre de drivers pour brancher le tien.
 
-Côté client : `RealtimeClient` via le subpath `nodefony/client`, et les hooks React via
+Côté client : `NodefonySocket` via le subpath `nodefony/client`, et les hooks React via
 `nodefony/react`.
 
 Les signatures exactes vivent dans le graphe généré — `jq '.symbols.RealtimeHub' .ai/symbols.json` —
@@ -326,7 +340,7 @@ vue de tous les workers d'un pod.
 
 Le data plane admin expose `/nodefony/realtime/api/health` — canaux et abonnés, compteurs de
 diffusion, connexions, octets et frames, pression d'écriture. C'est la même donnée que celle rendue à
-l'écran, servie par la sonde du hub (`RealtimeHub.probe()`, `RealtimeHub.ts:865`).
+l'écran, servie par la sonde du hub (`RealtimeHub.probe()`, `RealtimeHub.ts:847`).
 
 ## 🧪 Tests & couverture
 

package/docs/observabilite.md

@@ -96,7 +96,7 @@ temps de réponse — elle mesure **ce qui n'est pas encore parti**.
 Trois partis pris, tous lisibles dans le code.
 
 **1. La sonde est une lecture pure, jamais un collecteur.** `RealtimeHub.probe()`
-(`RealtimeHub.ts:865`) ne fait qu'additionner des primitives déjà tenues à jour par le chemin chaud.
+(`RealtimeHub.ts:847`) ne fait qu'additionner des primitives déjà tenues à jour par le chemin chaud.
 Aucune entrée-sortie, aucune exception possible, aucun état de lecture conservé. Appeler la sonde
 mille fois par seconde ne changerait rien à ce que le hub fait par ailleurs.
 
@@ -228,10 +228,10 @@ Côté navigateur, deux lignes suffisent à consommer le canal :
 
 ```ts
 // frontend/src/shopHealth.ts
-import { RealtimeClient } from "nodefony/client";
+import { NodefonySocket } from "nodefony/client";
 
 const scheme = window.location.protocol === "https:" ? "wss" : "ws";
-const socket = new RealtimeClient({
+const socket = new NodefonySocket({
   url: `${scheme}://${window.location.host}/shop/realtime`,
 });
 
@@ -265,7 +265,7 @@ Le contrat est `IRealtimeProbe` (`IRealtimeProbe.ts:61`). Quatre familles, un di
 | ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
 | `publishTotal`         | Appels à `publish`. **Ce que le serveur a voulu envoyer.**                                                         |
 | `fanoutTotal`          | Livraisons effectives (`publish` × abonnés). **Ce que ça a réellement coûté.**                                     |
-| `inboundTotal`         | Frames poussées par les clients sur les canaux entrants, via `RealtimeHub.recordInbound()` (`RealtimeHub.ts:854`). |
+| `inboundTotal`         | Frames poussées par les clients sur les canaux entrants, via `RealtimeHub.recordInbound()` (`RealtimeHub.ts:836`). |
 | `ingressRejectedTotal` | Messages venus du **backplane** et jetés parce que leur canal n'est pas déclaré diffusable.                        |
 
 Le rapport `fanoutTotal / publishTotal` est la mesure la plus parlante de la page : c'est la **taille
@@ -316,13 +316,15 @@ deux autres. Le débit en octets par seconde se dérive de deux photos.
 
 La source par connexion est `IRealtimeConnProbe` (`IRealtimeProbe.ts:25`), implémentée par le
 transport. Les seuils d'ACTION sont distincts du seuil de comptage, et ils sont
-**configurables** (`@nodefony/http`, `http/nodefony/config/config.ts:1044`) : au-delà de
+**configurables** (`@nodefony/http`, `http/nodefony/config/config.ts:1226`) : au-delà de
 `websocket.maxBackpressure` (4 MiB par défaut) la politique `websocket.backpressurePolicy`
-s'applique — `drop` par défaut, la frame est **jetée** puisque les canaux d'état sont « le
-dernier gagne » et que le prochain instantané la remplacera. La connexion est **fermée** en
-`1013` (« réessaie plus tard ») après `websocket.backpressureCloseAfterDrops` frames jetées
-CONSÉCUTIVES (1000 par défaut) — une seule frame qui repart remet le compteur à zéro — ou
-dès le premier dépassement si la politique est `close`.
+s'applique — `drop` par défaut, la frame est **jetée**. Sur un canal d'état c'est sans
+conséquence, le prochain instantané la remplace ; mais le rejet ne trie rien, et une réponse RPC
+ou un événement jetés sont **perdus**. La connexion est **fermée** en `1013` (« réessaie plus
+tard ») quand le **solde** de refus atteint `websocket.backpressureCloseAfterDrops` (1000 par
+défaut) — +1 par frame jetée, −1 par frame envoyée, si bien qu'un pic passager redescend — ou
+dès le premier dépassement si la politique est `close`. Le mécanisme complet, avec ses courbes :
+[Cadence et contre-pression](./cadence-et-contre-pression.md).
 
 > [!IMPORTANT]
 > `drops` qui croît n'est **pas** une panne : c'est la protection qui fonctionne. Ce qui serait une
@@ -462,11 +464,11 @@ instantané est exact — et ne dit rien des trois autres. Pire : deux appels co
 sur deux workers et sembler se contredire.
 
 **La réponse de Nodefony est un modèle _push_.** Chaque worker remonte périodiquement sa santé au
-maître via `ClusterProbeClient.start()` (`ClusterProbeClient.ts:170`) ; le maître fusionne et
+maître via `ClusterProbeClient.start()` (`ClusterProbeClient.ts:190`) ; le maître fusionne et
 rediffuse ; chaque worker met le résultat en cache. **N'importe lequel** sert alors la vue pod en temps
-constant, sans latence de requête (`ClusterProbeClient.getClusterHealth()`, `ClusterProbeClient.ts:291`).
+constant, sans latence de requête (`ClusterProbeClient.getClusterHealth()`, `ClusterProbeClient.ts:306`).
 
-La fusion, `mergeClusterHealth()` (`ClusterProbeClient.ts:46`), est une fonction pure — et sa règle
+La fusion, `mergeClusterHealth()` (`ClusterProbeClient.ts:60`), est une fonction pure — et sa règle
 mérite d'être connue :
 
 | Grandeur                                                         | Agrégation  | Pourquoi                                                                   |
@@ -483,7 +485,7 @@ garde le détail par worker pour le forage.
 ### On paie ce qu'on regarde
 
 Les sondes coûteuses ne tournent pas en permanence. Le maître peut demander à un worker précis
-d'**enrichir** sa remontée — `ClusterProbeClient.requestEnrich()` (`ClusterProbeClient.ts:239`) — quand
+d'**enrichir** sa remontée — `ClusterProbeClient.requestEnrich()` (`ClusterProbeClient.ts:259`) — quand
 un humain ouvre le forage de ce `pid`. La sonde riche (espaces mémoire, cycles de ramasse-miettes,
 descripteurs actifs) est alors allouée ; à la fermeture de l'écran, elle est libérée et son observateur
 détaché.
@@ -504,7 +506,7 @@ l'orchestrateur finit par le tuer de force à l'expiration du délai de grâce.
 
 La règle est tenue partout dans le code, y compris là où on ne l'attendrait pas — le tick de
 revalidation d'identité du hub, qui ne démarre qu'au premier inscrit, est lui aussi détaché
-(`RealtimeHub.ts:437`), tout comme le report de la sonde cluster (`ClusterProbeClient.ts:170`) et le
+(`RealtimeHub.ts:443`), tout comme le report de la sonde cluster (`ClusterProbeClient.ts:170`) et le
 minuteur générique des canaux (`providers.ts:465`).
 
 ```ts ignore