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

package/docs/configuration.md

@@ -29,7 +29,7 @@ source: "src/packages/@nodefony/realtime/docs/configuration.md"
 
 # Configuration — le fond de panier, les bornes, la porte d'entrée
 
-> Le module temps réel expose **six réglages**, pas un de plus. Un seul décide vraiment de quelque
+> Le module temps réel expose **sept blocs de réglages**, pas un de plus. Un seul décide vraiment de quelque
 > chose : le **driver de backplane**, c'est-à-dire la façon dont deux processus de ton application se
 > transmettent une publication. Les autres bornent la connexion et gardent la porte. Cette page les
 > donne tous, avec leur valeur d'usine lue dans le schéma, l'effet observable de chacun, et les trois
@@ -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,19 +131,19 @@ 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.
 
 > [!IMPORTANT]
-> C'est ce filet qui compte, bien plus que le confort d'écriture. Sans lui, une faute de frappe ne se
-> verrait ni à l'écriture ni au démarrage : le schéma **retire** les clés inconnues sans se plaindre.
-> `slowConsummer: { bytes: 4096 }` donnerait le défaut, en silence. Avec l'augmentation, la même
-> faute ne compile pas.
+> Ce filet attrape la faute dès l'écriture. Le schéma, lui, est strict : une clé inconnue arrête le
+> démarrage (`BootConfigurationError`, avec le chemin complet de la clé). `slowConsummer: { bytes:
+4096 }` est donc refusé au boot ; avec l'augmentation, la même faute ne compile même pas.
 
 ## 🚀 Démarrage rapide
 
@@ -252,12 +252,12 @@ 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é
 
-Six blocs, douze clés au total. Le tableau donne la vérité complète ; les sections qui suivent
+Sept blocs, seize clés au total. Le tableau donne la vérité complète ; les sections qui suivent
 expliquent quand et pourquoi en changer.
 
 <!-- prettier-ignore -->
@@ -274,16 +274,22 @@ expliquent quand et pourquoi en changer.
 | `csrf.checkOrigin.enabled` | `boolean` | `false` | active le contrôle d'`Origin` à l'ouverture de la socket |
 | `csrf.checkOrigin.allowList` | `string[]` | `[]` | origines acceptées, **comparaison exacte**. Vide + activé = tout est refusé |
 | `csrf.checkOrigin.allowMissingOrigin` | `boolean` | `false` | accepter une ouverture sans en-tête `Origin` (clients non-navigateur) |
+| `clientLogs.enabled` | `boolean` | `false` | accepte les journaux du navigateur sur le canal montant `nodefony:syslog:uplink`. Surface d'écriture, fermée par défaut ; une connexion anonyme ne pousse rien |
+| `clientLogs.maxEntriesPerBatch` | `number` | `50` | entrées acceptées par lot |
+| `clientLogs.maxEntriesPerWindow` | `number` | `300` | entrées acceptées par fenêtre de débit |
+| `clientLogs.windowMs` | `number` | `10000` | durée de la fenêtre de débit, en ms |
+| `clientLogs.maxStringLength` | `number` | `4096` | longueur maximale d'une chaîne reçue |
 
 C'est **tout**. Il n'existe ni réglage de ping, ni de cadence, ni de fréquence d'échantillonnage de
-la sonde, ni de seuil de contre-pression configurable : ces comportements existent, mais leurs
-valeurs sont des constantes du code, pas des clés.
+la sonde : ces comportements existent, mais leurs valeurs sont des constantes du code. Les seuils de
+contre-pression, eux, se règlent sur le serveur WebSocket de `@nodefony/http`
+(`websocket.maxBackpressure`, `.backpressurePolicy`, `.backpressureCloseAfterDrops`).
 
 ### `enabled` — le module au repos
 
 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]
@@ -324,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.
@@ -372,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
@@ -434,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 :
 
@@ -445,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.
@@ -457,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é :
@@ -522,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
@@ -547,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.
 
@@ -557,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.
 
@@ -645,8 +651,8 @@ 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 **retire** toute clé
-> qu'il ne connaît pas — dont une instance de classe. Pour brancher un objet déjà construit, utilise
+> 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`.
 
 Le détail du contrat, de l'anti-écho et du cycle de vie d'un driver est dans
@@ -660,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` |
@@ -672,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
@@ -695,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.
 
@@ -714,10 +724,10 @@ import { defineRealtimeConfig } from "@nodefony/realtime";
 
 const cfg = defineRealtimeConfig({ backplane: { driver: "redis" } });
 // cfg.limits.maxChannelsPerConnection === 256 — les sections omises gardent leurs défauts.
-// Une valeur invalide lève une ZodError, avec le chemin exact du champ fautif.
+// 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.
@@ -748,16 +758,16 @@ Trois endroits, par ordre de fiabilité décroissante.
 
 ## ⚠️ Pièges
 
-| Symptôme                                                                            | Cause                                                                                                                | Correction                                                                                 |
-| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| Un message n'arrive qu'à la moitié des clients, sans aucune erreur                  | plusieurs répliques avec `driver: "loopback"`                                                                        | passer à `redis` et déclarer `@nodefony/redis` dans le manifeste                           |
-| Driver `redis` configuré, journal `RealtimeHub reste local`                         | module `@nodefony/redis` absent du manifeste, ou connexions `publish`/`subscribe` indisponibles                      | déclarer le module ; vérifier que Redis répond                                             |
-| Le fan-out traverse, mais des messages d'un autre environnement arrivent            | `backplane.namespace` non posé : deux déploiements de la même application dérivent le même canal                     | poser un namespace explicite et distinct par environnement                                 |
-| Une clé écrite dans `use()` n'a aucun effet                                         | nom de clé fautif : le registre de types n'étant pas augmenté, l'éditeur ne corrige pas, et Zod **retire** l'inconnu | relire la configuration effective dans Studio, onglet Config                               |
-| 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                                   |
+| Symptôme                                                                            | Cause                                                                                            | Correction                                                                                 |
+| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| Un message n'arrive qu'à la moitié des clients, sans aucune erreur                  | plusieurs répliques avec `driver: "loopback"`                                                    | passer à `redis` et déclarer `@nodefony/redis` dans le manifeste                           |
+| Driver `redis` configuré, journal `RealtimeHub reste local`                         | module `@nodefony/redis` absent du manifeste, ou connexions `publish`/`subscribe` indisponibles  | déclarer le module ; vérifier que Redis répond                                             |
+| Le fan-out traverse, mais des messages d'un autre environnement arrivent            | `backplane.namespace` non posé : deux déploiements de la même application dérivent le même canal | poser un namespace explicite et distinct par environnement                                 |
+| Le démarrage échoue avec `clé inconnue : …`                                         | clé absente du schéma strict (faute de frappe, ou clé retirée)                                   | corriger ou retirer la clé que nomme le message                                            |
+| 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:218`)   | vérifier le motif de refus `realtime:denied` côté client                                   |
 
 ## 🧪 Tests & couverture
 
@@ -778,12 +788,12 @@ qui compte ici, c'est **ce que les suites prouvent sur la configuration**.
 > **Un run vert ne prouve pas le fan-out entre machines.** Le banc Redis est doublement conditionnel :
 > il n'est lancé que sur demande, et il se **saute** de lui-même si aucun Redis ne répond. Un test
 > sauté compte comme un succès — on peut donc lire « tout est vert » sur une suite qui n'a jamais
-> ouvert une connexion. Le fan-out entre workers, lui, ne demande rien et tourne toujours.
+> ouvert une connexion. Le fan-out entre workers ne demande aucune infrastructure externe, mais ne tourne que dans `npm run test:cluster` (avec `NF_RUN_CLUSTER_E2E=1`).
 >
 > ```bash
 > cd src/packages/@nodefony/realtime
-> npm test                                              # unitaires + IPC entre workers
-> NF_RUN_CLUSTER_E2E=1 NF_REDIS_PASSWORD=nodefony-dev npm test # + le fan-out entre machines
+> npm test                                              # unitaires et intégration
+> NF_RUN_CLUSTER_E2E=1 NF_REDIS_PASSWORD=nodefony-dev npm run test:cluster # IPC entre workers + fan-out entre machines
 > npm run coverage                                      # couverture (vitest, v8)
 > ```
 

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,
@@ -1496,7 +1500,7 @@ pour lire ta propre sortie :
 | `backpressure.maxBufferedAmount` | La **pire** file d'envoi observée à l'instant de la mesure. C'est l'indicateur d'alerte. |
 | `backpressure.slowConsumers` | Combien de connexions dépassent le seuil de consommateur lent. |
 | `backpressure.drops` | Messages abandonnés faute de pouvoir être livrés. |
-| `backplane` | Présent uniquement si un relais est branché : son driver, son type, s'il traverse les processus. |
+| `backplane` | Toujours présent : carte d'identité du relais (driver, nature, `crossPod`) ; sans relais, descripteur `local` / `loopback`. |
 
 Deux lectures suffisent à diagnostiquer :
 
@@ -1546,12 +1550,14 @@ Ce qui est couvert, par nature de test :
 - **Unitaires** — le hub (abonnement, fan-out, cycle de vie des providers), les décorateurs et leurs
   métadonnées, le registre de drivers de backplane, le contrôleur, le service, le transport
   WebSocket, la validation de configuration, la dérivation de l'identifiant d'origine.
-- **Tests d'attaque** (`*.attack.test.ts`) — trois scénarios verrouillés en non-régression : le
-  plafond de canaux par connexion, la révocation d'une session en cours de connexion, et le cas
-  d'une politique de canal déclarée **sans** gardien branché (la dégradation doit rester bruyante).
+- **Tests d'attaque** (`*.attack.test.ts`) — quatre scénarios verrouillés en non-régression : le
+  plafond de canaux par connexion, la révocation d'une session en cours de connexion, le cas
+  d'une politique de canal déclarée **sans** gardien branché (la dégradation doit rester bruyante),
+  et l'injection par le bus (un pair ne pousse pas sur un canal non diffusable, un message forgé sur
+  un bus scellé est ignoré).
 - **Intégration de bout en bout** (`*.e2e.test.ts`) — le cheminement complet sur boucle locale, les
-  chemins de contrôleur, l'autorisation de canal, le branchement du firewall, et le cluster IPC avec
-  de vrais processus enfants.
+  chemins de contrôleur, l'autorisation de canal, le branchement du firewall. Le cluster IPC, avec
+  de vrais processus enfants, se lance à part : `npm run test:cluster` avec `NF_RUN_CLUSTER_E2E=1`.
 - **Cluster Redis** — exercé de bout en bout, mais **conditionné à la présence d'un Redis**. Sans
   lui, ces cas sont ignorés, et un test ignoré compte comme réussi : ne conclus pas d'un « tout est
   vert » que le chemin Redis a été vérifié chez toi.
@@ -1597,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:200`) |
+| 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`) |