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

package/docs/architecture.md

@@ -21,7 +21,7 @@ tags:
   ]
 version: "doc"
 status: stable
-updated: 2026-07-19
+updated: 2026-11-10
 source: "src/packages/@nodefony/realtime/docs/architecture.md"
 ---
 
@@ -344,11 +344,11 @@ La pile se lit de haut en bas ; chaque étage ne connaît que son voisin du dess
 dispatch des notifications, gestion des erreurs, `dispose()` propre. Deux points
 d'interception y sont posés :
 
-- `beforeDispatch` (`JsonRpcPeer.ts#JsonRpcPeerOptions.beforeDispatch`) — un verrou **synchrone** appelé avant tout
+- `beforeDispatch` (`JsonRpcPeer.ts#IJsonRpcPeerHooks.beforeDispatch`) — un verrou **synchrone** appelé avant tout
   traitement de frame. Il rend `true`/`false`. Un refus sur une requête produit
   `-32001 unauthorized` ; sur une notification, la frame est jetée
   (`JsonRpcPeer.ts#JsonRpcPeer.receive`).
-- `onFrameAudit` (`JsonRpcPeer.ts#JsonRpcPeerOptions.onFrameAudit`) — la trace des événements protocolaires notables
+- `onFrameAudit` (`JsonRpcPeer.ts#IJsonRpcPeerHooks.onFrameAudit`) — la trace des événements protocolaires notables
   (frame invalide, refusée, méthode inconnue, erreur interne).
 
 La contrainte de synchronisme n'est pas un oubli : un `await` par frame coûterait une
@@ -445,7 +445,8 @@ Les étapes, dans l'ordre exact du code :
    est révocable, préfixes de canaux broadcast, canaux entrants.
 6. **Message de bienvenue** `realtime:welcome` : canaux et méthodes découvrables, plus
    l'identité résolue (type, authentifié ou non, rôles, portées). Le client sait **qui il
-   est** sans appeler la moindre route.
+   est** sans appeler la moindre route. Le champ `codec`, quand il est posé, dit le codec de
+   trame des frames suivantes ; absent, c'est JSON-RPC texte (ADR-0022 §2).
 
 À la fermeture, un unique `onFinish` (`RealtimeController.ts#RealtimeController.onHandshake`) fait le ménage complet :
 désabonnement de chaque canal tenu, retrait des deux registres, `fireClose()` du transport,
@@ -627,8 +628,11 @@ même process). Sans filtre, le fan-out local serait fait deux fois. D'où **deu
 et non une :
 
 1. **Côté hub** : l'arrivée passe par `publishLocal`, jamais par `publish`. Rien ne repart.
-2. **Côté backplane** : à la réception, on compare l'`originId` de l'enveloppe au sien et
-   on jette si c'est le même (`RedisBackplane.ts#RedisBackplane.originId`, `ClusterBackplane.ts#ClusterBackplane.#ingress`).
+2. **Côté backplane** : à la réception, l'écho se reconnaît à son `originId` et se jette
+   (`ingress.ts#BackplaneIngress`, `ClusterBackplane.ts#ClusterBackplane.#ingress`). Sur un bus
+   partagé, il se reconnaît à la **fin** du message, sans le décoder : sous un secret, un seul
+   calcul de sceau le vérifie (`envelope.ts#BackplaneEcho`). Chaque écho est compté
+   (`echoTotal` de la carte d'identité du backplane) : tant qu'il revient, le bus est vivant.
 
 L'étiquette elle-même est calculée par `resolveBackplaneOriginId()` (`originId.ts#resolveBackplaneOriginId`), et
 sa recette mérite qu'on s'y arrête :
@@ -647,6 +651,38 @@ sa recette mérite qu'on s'y arrête :
 > celle qui ne lève aucune erreur. L'`originId` est résolu à la construction : coût nul par
 > message.
 
+### Des octets sur le bus
+
+JSON ne sait pas porter des octets : un `Uint8Array` y devient un objet ordinaire
+(`{"0":1,"1":2}`), sans erreur. Les octets traversent donc le bus par une voie à eux, ouverte
+quand le serveur a un codec binaire (`codec: "cbor"`, [configuration](configuration.md)) :
+
+- **`redis`** : un **second canal**, nommé d'après le codec
+  (`nodefony:realtime:<cloison>:nodefony.jsonrpc.cbor.v1`,
+  `RedisBackplane.ts#resolveRedisBytesChannel`). Il porte la même enveloppe
+  `{ channel, payload, originId }`, encodée en CBOR, octets natifs dans `payload`, scellée
+  comme le texte. Une charge sans octets garde le canal texte : un serveur plus ancien, qui
+  n'écoute pas le second canal, continue de recevoir tout le reste.
+- **`cluster`** : le master forke ses workers en sérialisation `advanced` (clonage
+  structuré) — un `Uint8Array` traverse le relais tel quel, sans codec ni sceau : l'IPC ne
+  quitte pas la machine.
+
+Le hub ne confie des octets au bus que si le driver les accepte
+(`IBackplane.enableBytes`, `RealtimeHub.ts#RealtimeHub.publish`). Sinon il les garde sur le
+serveur qui les publie, et un avertissement de plateforme, émis une seule fois, nomme le canal.
+
+| Charge publiée sur un canal diffusé    | Abonnés de ce serveur | Autres serveurs, codec binaire + driver capable | Autres serveurs, sinon         |
+| -------------------------------------- | --------------------- | ----------------------------------------------- | ------------------------------ |
+| valeur JSON (`{ text: "bonjour" }`)    | reçue                 | reçue                                           | reçue                          |
+| `Uint8Array`                           | reçue, intacte        | reçue, intacte                                  | **non envoyée**, avertissement |
+| objet qui **contient** un `Uint8Array` | reçue, intacte        | reçue, intacte                                  | **non envoyée**, avertissement |
+| autre vue typée, `ArrayBuffer`         | reçue, intacte        | **non envoyée**, avertissement                  | **non envoyée**, avertissement |
+
+Sans codec binaire, seule la charge de premier niveau est examinée : chercher des octets au
+fond d'un objet coûterait sur chaque publication d'une application qui n'en publie pas. Un
+objet qui contient des octets sans codec binaire reste donc déformé sur le bus — comme il
+l'est déjà pour les navigateurs, qui le reçoivent en JSON.
+
 ### Le cloisonnement du canal Redis
 
 Le canal pub/sub de base est `nodefony:realtime` (`RedisBackplane.ts#REDIS_RT_CHANNEL`). Problème : le
@@ -693,6 +729,60 @@ Le module se déclare non critique (`src/packages/@nodefony/realtime/index.ts`)
 tout repli est annoncé. Enfin, `enabled: false` rend le module totalement inerte : ni API
 d'administration, ni backplane, ni sonde.
 
+### Écrire un driver, et le prouver
+
+Un driver mal réglé compile, démarre et perd des messages sans un mot. Les exigences qui
+l'en gardent sont écrites sur le contrat (`IBackplane.ts#IBackplane`) ; trois d'entre elles
+piègent tout journal partitionné :
+
+- **chaque serveur lit TOUT** — un groupe de lecteurs par serveur ; un groupe partagé
+  répartirait les messages, et un serveur sur deux ne verrait qu'une partie du trafic ;
+- **l'ordre par émetteur** — la clé de partition est l'`originId`, jamais le canal ;
+- **aucun rejeu au démarrage** — on lit à partir du dernier message : relue depuis le
+  début, une fin de partie fermerait la partie rouverte depuis.
+
+Dès que le bus quitte la machine, le driver **scelle** ses messages avec le sceau des
+drivers livrés, exporté pour lui : `sealBackplaneEnvelope` à l'émission,
+`openBackplaneEnvelope` à la réception (`envelope.ts#sealBackplaneEnvelope`).
+
+La preuve est la même pour tous : `runBackplaneConformance`, exportée par
+`@nodefony/realtime/testing` (`backplaneConformance.ts#runBackplaneConformance`). Elle
+relie plusieurs pairs du driver sur un même bus et vérifie la diffusion à tous, l'ordre,
+l'absence de rejeu, le sceau, le transport des ordres de contrôle et de la preuve de vie même
+file saturée, le refus de l'espace réservé à l'entrée du hub, la présence entre deux pods, le
+remplacement du handler et l'arrêt. Les drivers `cluster` et `redis` la passent dans le
+dépôt ; `loopback`, qui n'a aucun pair, n'a rien à y prouver.
+
+Le cas « présence entre deux pods » branche deux hubs réels sur deux pairs du driver.
+Il vérifie trois choses :
+
+- une identité ouverte sur les deux compte pour un seul présent ;
+- l'arrêt propre d'un hub retire ses présents chez l'autre bien avant le délai d'oubli ;
+- aucun message de présence n'arrive en double ni altéré.
+
+Un bus « au moins une fois », qui relivre un message, y tombe : la présence compte les doublons
+dans `presenceStaleDiscardedTotal`. Le driver n'a rien à écrire pour la présence, qui ne parle
+qu'à `IBackplane`. Ce cas prouve que son transport la porte.
+
+```typescript
+import { describe, it } from "vitest";
+import { runBackplaneConformance } from "@nodefony/realtime/testing";
+
+// Chaque appel rend un pair NEUF, relié au même bus, non démarré.
+runBackplaneConformance(
+  "mon-bus",
+  (secret) => new MonBackplane({ url, secret }),
+  {
+    describe,
+    it,
+  },
+);
+```
+
+Le lanceur de tests est passé, pas importé : la suite tourne sous n'importe quel lanceur
+qui fournit `describe` et `it`. Un bus lent relève `quietMs`, le silence attendu avant de
+conclure qu'un message refusé n'arrivera pas.
+
 ## 🧩 Extension — brancher son propre fond de panier
 
 Trois voies, de la plus déclarative à la plus directe.
@@ -741,10 +831,10 @@ refonte. Ici, seulement **où** ils sont ; le **quoi** et le **comment** sont da
 
 | Point de greffe              | Étage     | Moment         | Ancrage                                                |
 | ---------------------------- | --------- | -------------- | ------------------------------------------------------ |
-| Contrôle d'origine           | hub       | à l'upgrade    | `RealtimeHub.ts#RealtimeHub.publishLocal`              |
-| Authentificateur réseau      | hub       | au handshake   | `RealtimeHub.ts#RealtimeHub.unsubscribe`               |
-| Verrou de frame              | protocole | à chaque frame | `RealtimeHub.ts#RealtimeHub.markBroadcastChannel`      |
-| Politique déclarée par canal | hub       | au handshake   | `RealtimeHub.ts#RealtimeHub.setBackplane`              |
+| Contrôle d'origine           | hub       | à l'upgrade    | `RealtimeHub.ts#RealtimeHub.checkOrigin`               |
+| Authentificateur réseau      | hub       | au handshake   | `RealtimeHub.ts#RealtimeHub.useAuthenticator`          |
+| Verrou de frame              | protocole | à chaque frame | `RealtimeHub.ts#RealtimeHub.setFrameAuthorizer`        |
+| Politique déclarée par canal | hub       | au handshake   | `RealtimeHub.ts#RealtimeHub.registerChannelPolicy`     |
 | Audit de frame               | protocole | sur refus      | `RealtimeController.ts#RealtimeController.onHandshake` |
 
 Deux propriétés architecturales méritent d'être notées ici, parce qu'elles expliquent des
@@ -776,7 +866,7 @@ un débit.
 | Back-pressure  | `maxBufferedAmount`, `totalBufferedAmount`, `slowConsumers`, `drops` | le risque mémoire numéro un      |
 | Fond de panier | `backplane` (la carte d'identité de `describe()`)                    | ce qui est réellement branché    |
 
-Le contrat complet est `IRealtimeProbe` (`IRealtimeProbe.ts#IRealtimeProbe`). La version enrichie
+Le contrat complet est `IRealtimeProbe` (`nodefony/src/realtime/platformHealth.ts#IRealtimeProbe`). La version enrichie
 `buildOwnHealth()` (`RealtimeAdminApi.ts#buildOwnHealth`) y ajoute l'identifiant d'instance et la sonde
 process, plus — si elles sont disponibles — les sondes ORM et les compteurs d'erreurs. Deux
 chemins de lecture, un seul producteur :

package/docs/cadence-et-contre-pression.md

@@ -16,10 +16,11 @@ tags:
     contre-pression,
     sonde,
     1013,
+    4007,
   ]
 version: "doc"
 status: stable
-updated: 2026-10-07
+updated: 2026-10-30
 source: "src/packages/@nodefony/realtime/docs/cadence-et-contre-pression.md"
 coverageModule: realtime
 ---
@@ -70,6 +71,8 @@ flowchart LR
 | **File d'envoi**                      | `bufferedAmount`                              | Les octets acceptés par la socket mais pas encore partis sur le réseau.                                        |
 | **Solde de refus**                    | `_nfDropStreak`                               | Compteur par connexion : +1 par trame refusée, −1 par trame envoyée.                                           |
 | **1013**                              | _Try Again Later_                             | Code de fermeture WebSocket : « reviens plus tard ». Le client le traite comme transitoire et se reconnecte.   |
+| **4007**                              | `BACKPRESSURE_CLOSE_CODE`                     | Code privé Nodefony : le CLIENT ferme parce que SA file d'envoi ne se vide plus. Il se reconnecte ensuite.     |
+| **Borne de débit**                    | `maxFramesPerSecond`                          | Nombre de trames qu'une connexion peut envoyer au serveur par seconde. Au-delà, la trame est écartée.          |
 | **Canal d'état / canal d'événements** | _latest-wins_ / _every-message-counts_        | État : seule la dernière valeur compte. Événements : chaque message compte.                                    |
 | **Sonde**                             | _probe_                                       | Lecture instantanée des compteurs du hub, exposée par HTTP et par un canal de santé.                           |
 | **Abonner avant de couper**           | _make-before-break_                           | Changer de canal en s'abonnant au nouveau avant de quitter l'ancien : aucun trou dans le flux.                 |
@@ -500,6 +503,65 @@ Le client **n'apprend jamais** les seuils : il ne reçoit que leur effet.
   définitifs (`FATAL_CLOSE_CODES`, `notice.ts#FATAL_CLOSE_CODES`), donc `isReconnectableCloseCode()`
   (`notice.ts#isReconnectableCloseCode`) répond oui, et il se reconnecte avec une attente croissante.
 
+### Côté navigateur — la même règle, fermée en `4007`
+
+Un client peut lui aussi produire plus vite que le réseau n'écoule : un jeu qui émet trente
+positions par seconde sur une connexion mobile accumule des positions déjà périmées dans la file
+du navigateur. `NodefonySocket` applique alors **la même règle que le serveur** — elle vit au
+cœur, `backpressure.ts#decideBackpressure`, et les deux côtés l'appellent :
+
+```ts
+import { NodefonySocket } from "nodefony/client";
+
+const socket = new NodefonySocket({
+  url: "/game/realtime",
+  // Au-delà de 64 Kio en attente, la position est jetée au lieu d'être mise en file.
+  maxBufferedAmount: 64 * 1024,
+  // Solde de 200 positions jetées : la connexion est jugée morte, fermée puis rouverte.
+  backpressureCloseAfterDrops: 200,
+});
+
+socket.emit("game:move", { x: 12, y: 4 }); // part, ou est jetée et comptée
+console.log(socket.framesDropped); // positions jetées depuis la création
+```
+
+- Le client lit `bufferedAmount` **avant** de sérialiser : une frame jetée ne coûte pas son
+  `JSON.stringify`. `emit`, `request` et `sendBinary` passent tous par là ; une requête jetée est
+  rejetée aussitôt, sans attendre son délai.
+- Quand le solde atteint `backpressureCloseAfterDrops` (1 000 par défaut), le client ferme en
+  **`4007`** et se reconnecte comme après n'importe quelle coupure. Pas en `1013` : un navigateur
+  n'accepte que `1000` et `3000`-`4999` dans `WebSocket.close()`, et lèverait une erreur.
+- **Désactivé par défaut** dans toute la série 10 : sans `maxBufferedAmount`, rien n'est jamais jeté.
+
+### Dans l'autre sens — borner les trames reçues
+
+Le serveur borne aussi ce qu'il **reçoit**. Un client hostile qui envoie des milliers de trames par
+seconde ferait décoder chacune : la borne de débit les écarte **avant** tout décodage.
+
+```ts
+// nodefony.config.ts — section websocket ET websocketSecure
+use("@nodefony/http", {
+  websocket: { maxFramesPerSecond: 200, frameRateCloseAfterRejects: 1000 },
+  websocketSecure: {
+    maxFramesPerSecond: 200,
+    frameRateCloseAfterRejects: 1000,
+  },
+});
+```
+
+- On compte des **trames**, pas des octets : la taille est déjà bornée par `maxPayload`. Texte et
+  binaire suivent la même règle.
+- Le compte se fait à l'arrivée de la trame brute, dans `@nodefony/http`
+  (`wsFrameRate.ts#admitFrame`) : une trame écartée ne paie ni la conversion en texte, ni le
+  routage, ni `JSON.parse`, ni le décodage binaire.
+- Une trame écartée est **comptée** (`frameRateRejectedTotal`, dans la sonde du hub) ; la connexion
+  reste ouverte. Elle n'est fermée en **`1008`** (violation de politique) que lorsque le solde de
+  refus atteint `frameRateCloseAfterRejects` — jamais au premier dépassement. Le solde descend
+  d'une unité par trame admise : seul un flux qui dépasse **le double** de la borne le fait monter.
+- **Désactivée par défaut** (`maxFramesPerSecond: 0`) dans toute la série 10 : un seul test par
+  trame, aucune lecture d'horloge, aucune allocation. Repère : 50 trames/s d'audio passent avec
+  marge sous une borne de 200.
+
 ## 🔌 Comment les deux étages se rencontrent
 
 Aucune ligne de code ne relie la contre-pression du serveur à la cadence du client. Ils se
@@ -533,6 +595,10 @@ sans activer de trace.
 | `slowConsumers`       | les connexions dont la file atteint `slowConsumer.bytes` (1 Mio par défaut) | non nul = au moins un client prend du retard            |
 | `drops`               | les trames refusées, cumulées                                               | qui **augmente** = la contre-pression agit en ce moment |
 
+Les refus ont leurs propres compteurs, à côté du bloc `backpressure`. **`frameRateRejectedTotal`**
+compte les trames reçues écartées par la borne de débit — cumul du **processus**, relevé dans
+`@nodefony/http`, car une trame écartée n'atteint aucun hub. `0` tant que la borne est désactivée.
+
 > [!IMPORTANT]
 > **`slowConsumer.bytes` compte, il ne freine pas.** C'est le réglage de la **sonde**
 > (`@nodefony/realtime`), pas de la contre-pression (`@nodefony/http`). Le baisser fait apparaître
@@ -557,6 +623,10 @@ Le détail champ par champ et le flux de santé : [Observabilité de la socket](
 | `maxBackpressure`                                     | `@nodefony/http`     | 4 Mio          | file d'envoi au-delà de laquelle la politique s'applique ; 0 = coupé |
 | `backpressurePolicy`                                  | `@nodefony/http`     | `drop`         | `drop` jette la trame ; `close` ferme au premier dépassement         |
 | `backpressureCloseAfterDrops`                         | `@nodefony/http`     | 1000           | solde de refus qui déclenche la fermeture `1013` ; 0 = jamais        |
+| `maxFramesPerSecond`                                  | `@nodefony/http`     | 0              | trames reçues admises par seconde et par connexion ; 0 = coupé       |
+| `frameRateCloseAfterRejects`                          | `@nodefony/http`     | 1000           | solde de trames écartées qui ferme en `1008` ; 0 = jamais            |
+| `maxBufferedAmount` (`NodefonySocket`)                | `nodefony`           | 0              | file d'envoi du navigateur au-delà de laquelle on jette ; 0 = coupé  |
+| `backpressureCloseAfterDrops` (`NodefonySocket`)      | `nodefony`           | 1000           | solde de frames jetées qui ferme en `4007` ; 0 = jamais              |
 | `slowConsumer.bytes`                                  | `@nodefony/realtime` | 1 Mio          | seuil de **comptage** de la sonde ; n'agit sur rien                  |
 | `intervalMs` (hook / client)                          | `nodefony`           | —              | cadence **désirée** ; l'AIMD ne descend jamais en dessous            |
 | `ladder`, `maxMs`                                     | `nodefony`           | ×2, 60 s       | l'échelle des cadences possibles                                     |
@@ -576,6 +646,8 @@ La table complète des réglages du module et leurs schémas : [Configuration](c
 | ---------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
 | RFC 6455 §7.4 — codes de fermeture             | une fermeture porte un code ; la plage 1000-2999 est réservée et enregistrée à l'IANA | ferme en `1013` (`backpressure`)                                                      |
 | Registre IANA des codes de fermeture WebSocket | `1013` = _Try Again Later_ : condition temporaire du serveur                          | le client le traite comme transitoire et se reconnecte                                |
+| RFC 6455 §7.4.1 — `1008`                       | _Policy Violation_ : le pair a enfreint une politique du serveur                      | ferme la connexion qui dépasse durablement la borne de débit entrante                 |
+| WHATWG WebSockets — `close(code)`              | seuls `1000` et `3000`-`4999` sont admis, sinon `InvalidAccessError`                  | le navigateur ferme sa contre-pression en `4007`, jamais en `1013`                    |
 | RFC 5681 — contrôle de congestion TCP          | augmentation additive, diminution multiplicative                                      | **inspiration** de l'AIMD de cadence, appliquée à des abonnements et non à des octets |
 | JSON-RPC 2.0                                   | requêtes, réponses, notifications                                                     | aucune notion de cadence ni de file : tout ce mécanisme est propre à Nodefony         |
 
@@ -596,15 +668,18 @@ La table complète des réglages du module et leurs schémas : [Configuration](c
 
 ## 🧪 Tests
 
-| Suite                                                   | Ce qui est prouvé                                                                                                                         |
-| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `AdaptiveRate.test.ts` (`nodefony`)                     | la machine pure : échelle ×2, première trame sans décision, famine immédiate, reprise après N bons échantillons, chien de garde           |
-| `channelRate.test.ts` (`nodefony`)                      | le nom cadencé : canal nu pour le défaut, suffixe sinon, bornage côté serveur                                                             |
-| `RealtimeNotice.test.ts` (`nodefony`)                   | `1013` fait partie des fermetures transitoires qui déclenchent la reconnexion                                                             |
-| `wsBackpressure.test.ts` (`@nodefony/http`)             | `decideSend()` : désactivé à 0, nominal sous le seuil, `drop` sans fermer, `close` en `1013`                                              |
-| `backpressureConfig.test.ts` (`@nodefony/realtime`)     | le transport temps réel applique la règle de `@nodefony/http` : refus compté, fermeture après N, **le solde décroît** sur un pic passager |
-| `WsConnectionTransport.test.ts` (`@nodefony/realtime`)  | le transport : envoi seulement sur socket ouverte, fermeture déléguée                                                                     |
-| `cadencePressureFigures.test.ts` (`@nodefony/realtime`) | **les courbes de cette page** : rejoue les trois scénarios avec le vrai code et compare chaque valeur                                     |
+| Suite                                                   | Ce qui est prouvé                                                                                                                          |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `AdaptiveRate.test.ts` (`nodefony`)                     | la machine pure : échelle ×2, première trame sans décision, famine immédiate, reprise après N bons échantillons, chien de garde            |
+| `channelRate.test.ts` (`nodefony`)                      | le nom cadencé : canal nu pour le défaut, suffixe sinon, bornage côté serveur                                                              |
+| `RealtimeNotice.test.ts` (`nodefony`)                   | `1013` fait partie des fermetures transitoires qui déclenchent la reconnexion                                                              |
+| `realtimeBackpressure.test.ts` (`nodefony`)             | la règle pure du cœur : un verdict par cas (`send`, `drop`, `close`), le solde qui monte au refus et redescend à l'envoi                   |
+| `clientBackpressure.test.ts` (`nodefony`)               | le navigateur : rien de jeté sans borne ; au-delà, `emit`/`request`/`sendBinary` jettent et comptent ; solde atteint → `4007`, reconnexion |
+| `wsBackpressure.test.ts` (`@nodefony/http`)             | `decideSend()` : désactivé à 0, nominal sous le seuil, `drop` sans fermer, `close` en `1013`                                               |
+| `wsFrameRate.test.ts` (`@nodefony/http`)                | la borne entrante : aucune fenêtre à 0, rafale écartée **sans décodage**, flux soutenu fermé en `1008`                                     |
+| `backpressureConfig.test.ts` (`@nodefony/realtime`)     | le transport temps réel applique la règle de `@nodefony/http` : refus compté, fermeture après N, **le solde décroît** sur un pic passager  |
+| `WsConnectionTransport.test.ts` (`@nodefony/realtime`)  | le transport : envoi seulement sur socket ouverte, fermeture déléguée                                                                      |
+| `cadencePressureFigures.test.ts` (`@nodefony/realtime`) | **les courbes de cette page** : rejoue les trois scénarios avec le vrai code et compare chaque valeur                                      |
 
 Deux bancs complètent, hors des suites (skill `nodefony-load-test`) :
 
@@ -619,7 +694,8 @@ pas éprouvée de bout en bout.
 ```bash
 cd src/nodefony && npx vitest run src/tests/AdaptiveRate.test.ts src/tests/channelRate.test.ts
 cd src/packages/@nodefony/realtime && npm test
-cd src/packages/@nodefony/http && npx vitest run nodefony/tests/unit/wsBackpressure.test.ts
+cd src/packages/@nodefony/http && npx vitest run nodefony/tests/unit/wsBackpressure.test.ts nodefony/tests/unit/wsFrameRate.test.ts
+cd src/nodefony && npx vitest run src/tests/realtimeBackpressure.test.ts src/tests/clientBackpressure.test.ts
 ```
 
 ## Ce qu'il faut retenir

package/docs/canaux-a-membres.md

@@ -0,0 +1,277 @@
+---
+title: "Canal à membres — abonner d'office, éjecter, terminer"
+navTitle: Canal à membres
+lang: fr
+module: "@nodefony/realtime"
+topic: realtime
+section: "Temps réel"
+audience: [developer]
+tags: [canaux, membres, salon, partie, éjection, fermeture, allow]
+version: "doc"
+status: stable
+updated: 2026-11-02
+source: "src/packages/@nodefony/realtime/docs/canaux-a-membres.md"
+coverageModule: realtime
+---
+
+# Canal à membres — abonner d'office, éjecter, terminer
+
+📍 [Documentation](../../../../../docs/index.md) › [Realtime](index.md) › **Canal à membres**
+
+> Un salon fermé, une partie à quatre, un appel, le flux d'une tâche qu'un agent rend à son
+> demandeur : des canaux dont le **serveur** décide qui est dedans. Le canal reste le modèle — il
+> porte son producteur — et le hub sait désormais **qui** y est abonné : il liste ses membres,
+> abonne une connexion d'office, en éjecte une, et termine le canal pour tous.
+
+## 🧠 Le modèle mental
+
+Un canal ordinaire se remplit par la demande des clients : chaque navigateur envoie `subscribe`, la
+politique du canal (rôles, scopes, `allow`) tranche, et le serveur diffuse. Un canal **à membres**
+ajoute cinq gestes au serveur, et une règle qui les tient ensemble :
+
+| Geste                                   | Méthode du hub                          | Portée                   |
+| --------------------------------------- | --------------------------------------- | ------------------------ |
+| Lister les membres                      | `channelMembers(canal)`                 | **ce processus**         |
+| Abonner une connexion d'office          | `subscribeConnection(canal, connexion)` | **ce processus**         |
+| Éjecter une connexion                   | `evictConnection(canal, connexion)`     | **ce processus**         |
+| Éjecter un compte (tous ses onglets)    | `evictUser(canal, compte)`              | **tous les exemplaires** |
+| Terminer le canal pour tous ses membres | `closeChannel(canal)`                   | **tous les exemplaires** |
+
+Ce qui désigne une **connexion** reste local : elle n'existe que dans le processus qui tient sa
+socket. Ce qui désigne un **nom** — un canal, un compte — traverse les exemplaires par le bus.
+
+**La règle : `allow` est seul juge de qui ENTRE.** Abonner d'office passe par la même politique
+qu'un `subscribe` du client, `allow` compris ; éjecter **coupe**, n'exclut pas. Le navigateur
+rejoue ses abonnements à chaque reconnexion, et ce rejeu passe par `allow` : un membre imposé que
+`allow` ne connaît pas serait éjecté à la première coupure réseau, et un éjecté qu'`allow` connaît
+encore reviendrait au rechargement de sa page. L'application écrit donc l'appartenance **là où
+`allow` la lit** — une table, un registre partagé — et les gestes du hub ne font que la suivre.
+
+## 📖 Lexique
+
+- **Membre** — une connexion abonnée à un canal par un CLIENT (sa demande, ou une imposition du
+  serveur). Les écouteurs et services du serveur ne sont pas des membres.
+- **Poignée** (`IRealtimeConnection`) — ce qui désigne une connexion côté serveur : `userId` et
+  `open`. Elle n'existe que dans le processus qui tient la socket.
+- **Abonnement imposé** — le serveur abonne une connexion qui n'a rien demandé ; le client en est
+  averti par `realtime:subscribed { imposed: true }`.
+- **Éjection** — retrait d'UNE connexion d'un canal, motif `evicted`. **Fin** — retrait de tous
+  les membres, motif `ended`.
+- **Instance** — l'occurrence d'un canal à durée de vie, portée par son nom (`game:42:a1b2`).
+
+## 🚀 Démarrage rapide — une partie à quatre
+
+```typescript
+// nodefony/controllers/GameRealtimeController.ts
+import { controller, route } from "@nodefony/framework";
+import { Context } from "@nodefony/http";
+import {
+  RealtimeChannel,
+  RealtimeController,
+  RealtimeInbound,
+  getRealtimeHub,
+} from "@nodefony/realtime";
+import type { IRealtimeConnection } from "@nodefony/realtime";
+
+/** Qui joue à quelle partie — en vrai, une table ou un Redis partagé. */
+const players = new Map<string, Set<string>>();
+/** Parties en cours : une partie finie n'a plus de producteur. */
+const running = new Set<string>();
+
+@controller("/rt")
+class GameRealtimeController extends RealtimeController {
+  constructor(context: Context) {
+    super("GameRealtimeController", context);
+  }
+
+  @route("game-ws", { path: "/game", requirements: { methods: ["WEBSOCKET"] } })
+  async realtime(message: string | Buffer | null): Promise<void> {
+    this.handleRealtime(message);
+  }
+
+  // `allow` lit l'appartenance : c'est elle qui fait entrer, au premier
+  // abonnement comme à chaque reconnexion.
+  @RealtimeChannel("game:*", {
+    allow: (channel, who) =>
+      who.id !== null && (players.get(channel)?.has(who.id) ?? false),
+  })
+  game(): () => void {
+    return () => {};
+  }
+
+  // La fabrique d'un canal à durée de vie rend `null` pour une partie finie :
+  // c'est elle, et elle seule, qui clôt le canal.
+  override createRealtimeChannel(channel: string): (() => void) | null {
+    return running.has(channel) ? () => {} : null;
+  }
+
+  // Le geste part PAR LA SOCKET : il atteint le processus qui la tient. Le
+  // gestionnaire reçoit la connexion en dernier argument.
+  @RealtimeInbound("game:join")
+  async join(
+    _params: unknown,
+    _reply: (payload: unknown) => void,
+    connection: IRealtimeConnection,
+  ): Promise<void> {
+    const game = "game:42:a1b2"; // la partie trouvée par la recherche
+    if (connection.userId === null) return;
+    running.add(game);
+    const members = players.get(game) ?? new Set<string>();
+    members.add(connection.userId);
+    players.set(game, members);
+    const joined = await getRealtimeHub().subscribeConnection(game, connection);
+    if (!joined) this.log(`partie ${game} refusée`, "INFO");
+  }
+}
+
+export default GameRealtimeController;
+
+// Fin de partie, depuis n'importe quel service — la fin atteint tous les exemplaires :
+export function endGame(game: string): void {
+  running.delete(game);
+  players.delete(game);
+  getRealtimeHub().closeChannel(game);
+}
+```
+
+Côté navigateur, rien à écrire pour suivre un canal imposé : l'acquittement
+`realtime:subscribed { channel, imposed: true }` l'inscrit dans les abonnements du client, qui le
+rejoue à la reconnexion comme s'il l'avait demandé. Pour dire la fin à l'écran :
+
+```typescript
+import { NodefonySocket } from "nodefony/client";
+
+const socket = new NodefonySocket({ url: "/rt/game" });
+socket.on("game:42:a1b2", (state) => console.log("état de la partie", state));
+socket.onClosed(({ channel, reason }) => {
+  // `ended` : la partie est finie pour tous ; `evicted` : on en a été retiré.
+  console.log(
+    channel,
+    reason === "ended" ? "partie terminée" : "partie quittée",
+  );
+});
+socket.connect().catch(() => {});
+```
+
+## 📋 Ce que fait chaque geste
+
+**`subscribeConnection(canal, connexion)`** rend une promesse : `true` une fois l'abonnement acquitté,
+`false` sinon — politique refusée, `allow` qui dit non ou ne répond pas dans `allowTimeoutMs`, canal
+sans producteur, connexion fermée pendant l'attente, client qui se désabonne avant le verdict. Un
+refus n'est rendu **qu'à l'appelant** : le client, qui n'a rien demandé, ne reçoit aucun
+`realtime:denied`. Une connexion déjà membre rend `true` sans second acquittement.
+
+**`evictConnection(canal, connexion)`** retire la connexion du canal par le même chemin qu'un
+`unsubscribe` (le hub ET l'état de la connexion — jamais un abonné fantôme), lui retire l'admission
+de ses trames entrantes sur ce canal, et lui envoie `realtime:closed { reason: "evicted" }`. Les
+autres membres restent servis. Le client ne rejoue pas le canal ; une page rechargée, si — et c'est
+`allow` qui tranche alors. Sur un canal **sans** `allow`, la politique fixe le laisse rentrer :
+**exclure d'un canal sans `allow`, c'est lui en donner un**.
+
+**`evictUser(canal, compte)`** éjecte de la même façon **toutes** les connexions de ce compte membres
+du canal — ses onglets, quel que soit l'exemplaire qui les sert. Il rend le nombre de connexions
+éjectées **ici** ; les autres exemplaires l'appliquent sans compte rendu. Un compte vide n'éjecte
+rien. La même règle vaut : retirer l'appartenance là où `allow` la lit, **puis** éjecter.
+
+**Un accès borné dans le temps** (l'invité d'un événement, un abonnement qui expire) ne se périme
+pas seul : le verdict d'`allow` est retenu sur la connexion, et le hub ne relit rien. À l'échéance,
+l'application rejoue sa règle et éjecte qui n'y a plus droit. Un seul minuteur suffit, visé sur
+la prochaine échéance — ni un par accès, ni un balayage périodique qui lirait la base pour rien. La
+démo le fait pour ses salons (`RoomService.closeEnded`, gabarit `create app --demo`).
+
+**`closeChannel(canal)`** envoie `realtime:closed { reason: "ended" }` à chaque membre, sur tous les
+exemplaires, puis libère le producteur. Les écouteurs du serveur (`listen`) restent inscrits, sur un canal redevenu passif. Le
+hub ne garde **aucune marque « fermé »** : le `subscribe` suivant rejoue la fabrique, qui rend `null`
+pour une instance terminée — le client reçoit `realtime:denied { reason: "unknown" }`. D'où la règle
+d'écriture : **le nom d'un canal à durée de vie porte l'identifiant de son instance**
+(`game:42:a1b2`, pas `game:42`), pour qu'une partie rouverte ne soit jamais confondue avec celle
+qu'on vient de finir.
+
+**`channelMembers(canal)`** rend les connexions abonnées par un client — pas les écouteurs ni les
+services du serveur. Chaque poignée porte `userId` (le compte, `null` pour l'anonyme) et `open`.
+
+Un geste qui ne trouve rien rend `false` (ou `0`) : connexion non membre, fermée, ou poignée qui ne
+vient pas de ce processus. Jamais un geste muet.
+
+## 🔩 Où c'est fait
+
+- Le registre des membres vit dans l'état du canal, rempli à l'abonnement par
+  `RealtimeHub.ts#RealtimeHub.subscribeClient` et vidé par `RealtimeHub.ts#RealtimeHub.unsubscribe` ;
+  le fan-out (`RealtimeHub.ts#RealtimeHub.publish`) ne le lit jamais.
+- Les cinq gestes : `RealtimeHub.ts#RealtimeHub.channelMembers`,
+  `RealtimeHub.ts#RealtimeHub.subscribeConnection`, `RealtimeHub.ts#RealtimeHub.evictConnection`,
+  `RealtimeHub.ts#RealtimeHub.evictUser`, `RealtimeHub.ts#RealtimeHub.closeChannel`.
+- Les ordres entre exemplaires, en liste fermée : `controlOrder.ts#readControlOrder` (la même garde
+  à l'émission et à la réception).
+- La poignée : `RealtimeConnection.ts#RealtimeConnection`, créée au premier besoin par le contrôleur.
+- Le chemin unique d'une sortie, demandée ou décidée :
+  `RealtimeController.ts#RealtimeController.leaveChannel` ; la notification de fin :
+  `RealtimeController.ts#RealtimeController.endChannel`.
+- Côté navigateur : `NodefonySocket.ts#NodefonySocket.onClosed`.
+
+## ⚠️ Pièges
+
+- **Imposer sans écrire l'appartenance là où `allow` la lit** : l'abonnement tient jusqu'à la
+  première coupure réseau, puis le rejeu est refusé. Sur mobile, c'est dans la minute.
+- **Éjecter pour exclure** : une page rechargée refait `subscribe`. Retirer l'appartenance d'abord,
+  éjecter ensuite.
+- **Un nom de canal sans identifiant d'instance** (`game:42`) : la partie suivante portera le même
+  nom, et un client resté sur l'ancienne y entrera.
+- **Appeler un geste PAR CONNEXION depuis une requête HTTP** en cluster : la connexion est peut-être
+  tenue par un autre exemplaire. Passer par la socket, par `allow` (section suivante), ou par un
+  geste par NOM (`evictUser`, `closeChannel`), qui atteint tous les exemplaires.
+- **Un bus partagé** (Redis mutualisé) : un tiers qui peut y écrire, même sans le secret, peut
+  rejouer un ordre d'éjection capté. Sur un canal durable (`chat:general`), il recouperait le compte
+  à chaque retour. L'effet reste une coupure, jamais une entrée ; changer le secret du bus rend
+  caducs les ordres déjà captés. **Le bus doit être privé.**
+
+## 🌐 Plusieurs exemplaires (pods, `nodefony cluster`)
+
+Une connexion n'existe que dans la mémoire du processus qui a accepté sa socket. Le backplane
+transporte les **publications** et deux **ordres** — terminer un canal, éjecter un compte — que
+chaque exemplaire applique à SES connexions ; ni membres, ni politiques, ni acquittements. Ces deux
+ordres ne font qu'enlever : seul `allow` fait entrer. Livrés « au plus une fois », comme toute
+publication : un exemplaire qui en manque un, ou qui démarre après, est rattrapé par `allow` (pour
+une éjection) ou par la fabrique qui rend `null` à une instance terminée (pour une fin). Un bus
+chargé ne les sacrifie pas : quand la file d'envoi vers le bus est pleine, les publications en
+trop sont abandonnées, les ordres passent quand même. Seul un bus injoignable en perd un, et la
+perte se compte (`controlLostTotal`) et s'annonce.
+
+Les gestes **par connexion** agissent sur les connexions de ce processus. Deux voies marchent en
+cluster pour eux :
+
+1. **Le geste part par la socket** — un gestionnaire `@RealtimeInbound` reçoit la connexion et
+   s'exécute, par construction, sur le processus qui la tient.
+2. **Le serveur autorise, le navigateur s'abonne** — une requête HTTP (routée sur n'importe quel
+   exemplaire) écrit l'appartenance dans un registre partagé ; le navigateur fait `subscribe`, et
+   `allow` lit ce registre **directement**, sans cache : il n'est appelé qu'une fois par abonnement.
+
+Une requête HTTP qui appellerait `subscribeConnection` sur une connexion tenue par un autre
+exemplaire n'a pas de poignée à lui passer : elle ne peut rien faire, et c'est voulu — un geste qui
+marcherait en développement et une fois sur N en production serait le pire des défauts.
+
+## 🧪 Tests & couverture
+
+- **Serveur** (`channelMembers.test.ts`) : membres listés et retirés à la fermeture de la socket ;
+  éjection (l'éjecté n'est plus servi, les autres si ; il rentre sans `allow`) ; imposition depuis un
+  gestionnaire entrant, refus de `allow` rendu au seul appelant, connexion fermée ou désabonnée
+  pendant l'attente ; fin du canal, producteur libéré, écouteur conservé, fabrique rejouée.
+- **Entre exemplaires** (`memberOrdersAcrossPods.test.ts`) : fin et éjection d'un compte données sur
+  un hub atteignent les membres de l'autre ; canal de contrôle jamais diffusé ; ordres mal formés
+  ou visant un canal de la plateforme rejetés et comptés (`ingressRejectedTotal`), ordre d'un type
+  inconnu de cette version jeté et compté à part (`ingressUnknownDiscardedTotal`). Sur un
+  **Redis réel** (`memberOrdersRedis.test.ts`, gate Redis) : ordre scellé appliqué, ordre non scellé
+  ignoré, et le rejeu d'une éjection captée — le risque accepté — décrit par un test. Sur le **bus du
+  cluster** (`clusterIpc.e2e.test.ts`, `npm run test:cluster`) : deux vrais processus.
+- **Client** (`NodefonySocketClosed.test.ts`) : canal imposé inscrit et rejoué, canal terminé retiré
+  pour tous ses consommateurs et jamais rejoué, attente d'acquittement rejetée, trame mal formée
+  ignorée.
+- **Trames** (`subscribedAck.test.ts`) : l'acquittement imposé est octet pour octet celui du pair
+  JSON-RPC. **Surface figée** (`frozenSurface.test.ts`) : les motifs `ended` et `evicted`.
+
+## 🔗 Pour aller plus loin
+
+- ⬆️ **Retour au hub** : [Realtime — vue d'ensemble](index.md) · [Toute la documentation](../../../../../docs/index.md)
+- [Sécurité](./securite.md) — `allow`, sa forme classe, son délai et son budget.
+- [Protocole](./protocole.md) — les notifications système de la socket.
+- Décisions : ADR-0022 §6 (canaux privés, décisions 2 à 4), ADR-0021 S4 (fin d'un flux).