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

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` —
@@ -304,7 +318,7 @@ jamais recopiées ici : elles divergeraient en silence.
 ## ⚙️ Configuration
 
 Un seul point d'entrée : `use("@nodefony/realtime", { … })` dans `nodefony.config.ts`, validé au boot
-contre le schéma du module (`realtimeConfigSchema`, `config.ts:259`). Cinq blocs :
+contre le schéma du module (`realtimeConfigSchema`, `config.ts:259`). Six blocs :
 
 - `backplane` — le driver de fan-out et son espace de nommage. Ce cloisonnement devient
   indispensable dès que **deux déploiements partagent le même Redis** : sans lui, leurs publications
@@ -313,6 +327,7 @@ contre le schéma du module (`realtimeConfigSchema`, `config.ts:259`). Cinq bloc
 - `limits` — le plafond de canaux par connexion, garde anti-saturation mémoire.
 - `slowConsumer` — le seuil à partir duquel un client trop lent est signalé par la sonde.
 - `cluster.probe` — la sonde agrégée du pod, en mode multi-workers.
+- `clientLogs` — la réception des journaux du navigateur (canal montant), fermée par défaut.
 
 Chaque bloc, ses valeurs d'usine et les situations qui justifient d'en changer sont détaillés dans
 [Configuration](./configuration.md).
@@ -325,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
 
@@ -333,24 +348,25 @@ Les compteurs sont régénérés depuis vitest, jamais figés dans cette prose.
 ici, c'est **ce que les suites prouvent** — et ce qu'elles ne prouvent qu'à condition d'avoir
 l'infrastructure sous la main.
 
-| Type            | Où                              | Ce qui est prouvé                                                 |
-| --------------- | ------------------------------- | ----------------------------------------------------------------- |
-| Unitaire        | `nodefony/tests/unit/**`        | hub, registre de drivers, schéma de configuration, décorateurs    |
-| Intégration     | `nodefony/tests/integration/**` | socket réelle : abonnements, chemins de contrôleur, autorisation  |
-| Multi-processus | `clusterIpc.e2e.test.ts`        | fan-out entre workers, sans aucune infrastructure externe         |
-| Cross-machine   | `redisCluster.e2e.test.ts`      | fan-out entre pods via pub/sub Redis                              |
-| Tests d'attaque | `*.attack.test.ts`              | plafond de canaux, révocation d'identité, politique non appliquée |
+| Type            | Où                              | Ce qui est prouvé                                                                       |
+| --------------- | ------------------------------- | --------------------------------------------------------------------------------------- |
+| Unitaire        | `nodefony/tests/unit/**`        | hub, registre de drivers, schéma de configuration, décorateurs                          |
+| Intégration     | `nodefony/tests/integration/**` | socket réelle : abonnements, chemins de contrôleur, autorisation                        |
+| Multi-processus | `clusterIpc.e2e.test.ts`        | fan-out entre workers, sans infrastructure externe (`npm run test:cluster`)             |
+| Cross-machine   | `redisCluster.e2e.test.ts`      | fan-out entre pods via pub/sub Redis                                                    |
+| Tests d'attaque | `*.attack.test.ts`              | plafond de canaux, révocation d'identité, politique non appliquée, injection sur le bus |
 
 > [!WARNING]
 > **Une suite verte ne prouve rien sur le fan-out cross-machine.** Le banc Redis est doublement
 > conditionnel : il ne s'exécute que si tu le demandes (`NF_RUN_CLUSTER_E2E=1`), et il se **saute** de
 > lui-même si aucun Redis n'est joignable. Or un test sauté compte comme un succès — on peut donc
 > lire « tout est vert » sur une suite qui n'a jamais ouvert une seule connexion. Le fan-out entre
-> workers d'un même pod, lui, ne demande aucune infrastructure et tourne toujours.
+> workers d'un même pod ne demande aucune infrastructure externe, mais ne tourne que dans
+> `npm run test:cluster` avec `NF_RUN_CLUSTER_E2E=1`.
 >
 > ```bash
 > # Le seul run qui prouve réellement le fan-out entre machines.
-> NF_RUN_CLUSTER_E2E=1 NF_REDIS_PASSWORD=nodefony-dev npm test
+> NF_RUN_CLUSTER_E2E=1 NF_REDIS_PASSWORD=nodefony-dev npm run test:cluster
 > ```
 
 ## 🔗 Pour aller plus loin

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
@@ -447,7 +449,8 @@ après fusion et validation — la seule vue qui dit ce qui s'applique, plutôt
 
 > [!CAUTION]
 > `slowConsumer.bytes` ne pilote **que la métrique**. Les seuils qui jettent une frame ou ferment une
-> connexion sont des constantes du transport. Baisser cette clé rend le signalement plus précoce ; ça
+> connexion se règlent côté `@nodefony/http` (`websocket.maxBackpressure`, `.backpressurePolicy`,
+> `.backpressureCloseAfterDrops`). Baisser cette clé rend le signalement plus précoce ; ça
 > ne change rien au comportement de la socket.
 
 Couper la sonde cluster est un **contournement total**, pas une mise en sourdine : sans elle, il n'y a
@@ -461,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                                                                   |
@@ -482,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é.
@@ -503,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
@@ -552,7 +555,7 @@ aux sondes qui instrumentent chaque opération et se paient donc à l'usage.
 | `publishTotal` grimpe, `fanoutTotal` stagne                                  | Tu publies dans le vide : personne n'est abonné au canal visé                                                         | Comparer le nom publié et le nom souscrit — presque toujours une faute de frappe                      |
 | Deux appels consécutifs à `/api/health` donnent des chiffres contradictoires | En cluster, la requête tombe sur un worker au hasard et rend une vue per-instance                                     | Lire le champ `cluster` ; si absent, la sonde pod est coupée ou en démarrage à froid                  |
 | La mémoire du processus grimpe sans fuite apparente                          | Une sonde alloue à chaque tick, ou un client lent fait grossir la file d'envoi                                        | Lire `backpressure.totalBufferedAmount` ; simplifier le corps du tick                                 |
-| Baisser `slowConsumer.bytes` ne ferme pas les clients lents                  | Cette clé pilote le **comptage** de la sonde ; les seuils d'action sont des constantes du transport                   | Rien à régler : ce comportement n'est pas configurable                                                |
+| Baisser `slowConsumer.bytes` ne ferme pas les clients lents                  | Cette clé pilote le **comptage** de la sonde ; les seuils d'action sont ceux du serveur WebSocket                     | Régler `maxBackpressure` / `backpressureCloseAfterDrops` dans `@nodefony/http`                        |
 | La cadence demandée n'est pas respectée                                      | Elle a été **ramenée dans les bornes** du canal, silencieusement                                                      | Lire les bornes du canal ; vérifier le nom réellement souscrit dans `channels[]`                      |
 | Deux abonnés au même canal, deux minuteurs                                   | Ils ont demandé des cadences différentes — un canal cadencé est distinct par cadence                                  | Laisser la cadence par défaut (aucun suffixe) quand elle convient : les abonnés partagent un minuteur |
 | Rien n'est visible alors que le trafic est réel                              | La sonde n'observe **jamais** ce à quoi personne n'est abonné : un canal sans abonné n'existe pas                     | Ouvrir l'écran ou s'abonner ; c'est le comportement voulu, pas une panne                              |
@@ -566,7 +569,7 @@ infrastructure, puisque la sonde est une lecture pure.
 | Suite | Ce qui est prouvé |
 | --- | --- |
 | `RealtimeHub.test.ts` | Hub vide → instantané à zéro ; abonnés et publications par canal ; `publishTotal` vs `fanoutTotal` ; comptage des consommateurs lents et `maxBufferedAmount` ; sortie du registre à la déconnexion ; frames entrantes ; descripteur `local` du backplane |
-| `WsConnectionTransport.test.ts` | Les deux seuils de contre-pression : abandon « le dernier gagne », puis fermeture `1013` |
+| `WsConnectionTransport.test.ts` | Les seuils de contre-pression : abandon « le dernier gagne », puis fermeture `1013` |
 | `ClusterProbeClient.test.ts` | Fusion pod (sommes vs maximum), report périodique et cache du snapshot, forage `enrich`/`rich`, repli per-instance quand la sonde est absente |
 
 **Ce qui manque, et qu'il faut savoir** : il n'existe pas de banc de charge dédié à la sonde