@nodefony/realtime 10.0.0-beta.6 → 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"
 ---
 
@@ -628,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 :
@@ -745,9 +748,21 @@ drivers livrés, exporté pour lui : `sealBackplaneEnvelope` à l'émission,
 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, le refus de l'espace
-réservé à l'entrée du hub, 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.
+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";

package/docs/canaux-a-membres.md

@@ -173,6 +173,12 @@ du canal — ses onglets, quel que soit l'exemplaire qui les sert. Il rend le no
 é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`
@@ -226,7 +232,10 @@ transporte les **publications** et deux **ordres** — terminer un canal, éject
 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).
+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 :
@@ -248,8 +257,9 @@ marcherait en développement et une fois sur N en production serait le pire des
   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,
-  inventés ou visant un canal de la plateforme rejetés et comptés (`ingressRejectedTotal`). Sur un
+  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.

package/docs/cas-d-usage.md

@@ -517,8 +517,8 @@ export class MatchRealtime extends RealtimeController {
     return () => {};
   }
 
-  // Un canal décoré n'est servi que sous son nom exact : la famille l'est ici,
-  // et seulement pour une partie qui existe.
+  // Le motif servirait toute la famille : la surcharge la FILTRE — seule une
+  // partie qui existe est servie, tout autre nom est refusé (`null`).
   override createRealtimeChannel(channel: string): (() => void) | null {
     return this.matches.exists(channel) ? () => {} : null;
   }
@@ -758,7 +758,8 @@ export class RoomRealtime extends RealtimeController {
     return () => {};
   }
 
-  // Un canal décoré n'est servi que sous son nom exact : la famille l'est ici.
+  // La surcharge FILTRE la famille : un nom qui n'est pas un salon est refusé
+  // (`null`). Sans elle, le motif servirait tout `room:*`, sous `allow`.
   override createRealtimeChannel(channel: string): (() => void) | null {
     return RoomService.roomOf(channel) === null ? null : () => {};
   }

package/docs/configuration.md

@@ -23,7 +23,7 @@ tags:
   ]
 version: "doc"
 status: stable
-updated: 2026-07-19
+updated: 2026-11-10
 source: "src/packages/@nodefony/realtime/docs/configuration.md"
 ---
 
@@ -750,7 +750,8 @@ class NatsBackplane implements IBackplane {
     this.#handler = handler;
   }
   async stop(): Promise<void> {
-    /* fermer, libérer les écouteurs — idempotent */
+    /* laisser partir ce qui est déjà émis (résoudre APRÈS l'acquittement),
+       puis fermer et libérer les écouteurs — idempotent */
   }
   describe(): IBackplaneInfo {
     return {
@@ -782,6 +783,13 @@ Quatre points que la fabrique doit respecter :
 4. `describe()` alimente **trois** sorties depuis une source unique : la ligne de journal, la sonde
    de santé et l'écran Studio. Remplis-la honnêtement, en particulier `crossPod`.
 
+Côté driver, un point compte à l'arrêt : **`stop()` laisse partir ce qui est déjà émis**. Le
+processus sort au tick qui suit l'arrêt du noyau. Un `stop()` qui ferme la connexion sans attendre
+l'acquittement perd la dernière publication, c'est-à-dire la fin de la présence de ce serveur. Les
+autres serveurs gardent alors ses présents jusqu'au délai d'oubli. Le pilote Redis attend sa file
+d'envoi (`publishQueue.ts#BackplanePublishQueue.settled`) ; un pilote maison bâti sur
+`BackplanePublishQueue` en hérite.
+
 **L'autre voie : fournir une instance déjà construite.** Déclare un service nommé
 `realtimeBackplane` dans le conteneur d'injection de ton module. `RealtimeService.init()`
 (`RealtimeService.ts#RealtimeService.init`) le lit et le branche **avant** que le registre soit consulté : une instance
@@ -795,6 +803,34 @@ backplane })`), et la documentation d'architecture présente cette voie. En prat
 > 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`.
 
+### Arrêter proprement un bus que tu fournis
+
+À l'arrêt du noyau, le module arrête **le bus qu'il a créé lui-même** depuis le registre. Il appelle
+`shutdownRealtime` (`realtimeShutdown.ts#shutdownRealtime`), qui fait trois choses :
+
+1. la présence des canaux annonce sa fin : dernier lot, puis preuve de vie finale ;
+2. le bus s'arrête en laissant partir ce qui est déjà émis ;
+3. le tout est borné à `BACKPLANE_STOP_TIMEOUT_MS` (2 s), pour qu'un bus injoignable ne retienne
+   pas l'arrêt.
+
+Un bus fourni par `realtimeBackplane` reste **à toi** : le module envoie bien la fin de la
+présence, mais n'arrête pas ce bus. Branche le même appel à l'arrêt du module qui l'a construit :
+
+```ts ignore
+import { getRealtimeHub, shutdownRealtime } from "@nodefony/realtime";
+
+// Dans le module qui a construit `bus` et l'a déclaré comme `realtimeBackplane`.
+this.kernel?.once("onTerminate", async () => {
+  const stopped = await shutdownRealtime(getRealtimeHub(), bus);
+  if (!stopped)
+    this.log("bus temps réel : arrêt non terminé dans le délai", "WARNING");
+});
+```
+
+`shutdownRealtime` rend `false` quand le bus n'a pas fini à temps. Ce qui restait en vol peut alors
+être perdu, et les autres serveurs oublieront celui-ci au délai d'oubli, sans fantôme durable.
+L'appel est idempotent : la présence ne s'annonce terminée qu'une fois.
+
 Le détail du contrat, de l'anti-écho et du cycle de vie d'un driver est dans
 [Architecture](./architecture.md).