@nodefony/realtime 10.0.0-beta.4 → 10.0.0-beta.6

package/docs/cookbook-chat.md

@@ -35,6 +35,25 @@ coverageModule: realtime
 
 📍 [Documentation](../../../../../docs/index.md) › [@nodefony/realtime](index.md) › **Cookbook — un chat**
 
+## ⚡ Le geste — deux commandes avant d'écrire une ligne
+
+Une ressource REST et un canal temps réel ne s'écrivent pas à la main : les générateurs de
+l'application les posent, câblés et testés. Depuis la racine de l'application :
+
+```bash
+npx nodefony create entity Message body:text room:string:index --route /api/messages
+npx nodefony create controller room --kind realtime
+```
+
+| Commande                            | Ce qu'elle pose                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `create entity`                     | la table (`nodefony/entity/Message.ts`), ses schémas de validation, un service CRUD, `MessageController` — REST sur `/api/messages`, et ses lectures répondent aussi par la socket —, un test unitaire et un test e2e, le tout inscrit dans `index.ts` — puis, si l'application versionne ses migrations (toute application complète), la migration de la table, écrite et appliquée à la base de développement ; sinon la table naît au prochain démarrage |
+| `create controller --kind realtime` | `RoomController` : la socket `/api/room/realtime`, le canal `room:events`, ses actions, et un test qui la pilote sans serveur ni navigateur                                                                                                                                                                                                                                                                                                                 |
+
+La suite de ce cookbook construit le même salon À LA MAIN, dans un seul contrôleur : c'est ce qui
+permet de comprendre ce que les générateurs écrivent, et de le retoucher. Pour avancer, partir des
+générateurs ; pour comprendre, lire la suite.
+
 ## 🎯 Ce qu'on construit
 
 **En une phrase** : un salon de discussion où plusieurs personnes échangent des messages et des
@@ -512,7 +531,7 @@ requirements: {
 Cette méthode est alors joignable de **deux** façons, et c'est **le même code** qui s'exécute :
 
 - `GET /chat/history` en HTTP ;
-- `socket.request("/chat/history")` par la socket déjà ouverte.
+- `socket.get("/chat/history")` par la socket déjà ouverte — la méthode porte le **verbe** de la route.
 
 Le passage par la socket emprunte un pont interne qui rejoue le routage sur le chemin demandé, puis
 exécute l'action. Ce pont ne peut atteindre **que** les routes ayant explicitement déclaré le
@@ -575,14 +594,15 @@ import { useEffect } from "react";
 // aucune poignée de main TLS de plus.
 useEffect(() => {
   void socket
-    .request<ChatMessage[]>("/chat/history?limit=50")
+    .get<ChatMessage[]>("/chat/history", { query: { limit: 50 } })
     .then((past) => setMessages(past));
 }, [socket]);
 ```
 
-Le chemin commence par `/` : le client le reconnaît comme un appel d'API et emprunte le pont. Une
-méthode RPC ordinaire, elle, ne commence jamais par `/` — il n'y a pas de collision possible entre
-les deux formes.
+`get` emprunte le pont : la même action que `GET /chat/history`, par la socket. La query se passe
+en objet et voyage dans le chemin (`?limit=50`), comme en HTTP. Le `<ChatMessage[]>` est une
+promesse faite au compilateur, pas une vérification : l'[étape 5](#quatre--un-contrat-pour-les-deux-côtés--lenvoi-et-les-messages-privés-typés)
+la remplace par un contrat qui DÉDUIT le type de la route.
 
 ### Ce qu'on observe
 
@@ -595,7 +615,7 @@ curl -k "https://127.0.0.1:5152/chat/history?limit=5"
 
 ```ts ignore
 // Transport 2 — la socket déjà ouverte, depuis la console du navigateur
-await chatSocket.request("/chat/history?limit=5");
+await chatSocket.get("/chat/history", { query: { limit: 5 } });
 ```
 
 Les deux renvoient le même tableau JSON. Si tu ajoutes une garde d'autorisation sur la méthode, elle
@@ -837,13 +857,13 @@ connaître la hiérarchie des rôles et l'identité réelle.
 
 C'est ici qu'il faut être précis, car **tous les chemins ne se valent pas**.
 
-Un handler `@RealtimeInbound` reçoit `(params, reply)` — et **rien d'autre**. Il ne reçoit ni la
-connexion, ni le jeton d'identité résolu à la poignée de main. Autrement dit : depuis un canal
-inbound brut, le serveur **ne peut pas savoir qui parle**. Le canal peut être _gardé_ par une
-politique (personne d'anonyme ne s'y abonne), mais le nom de l'auteur reste, lui, déclaré par le
-client.
+Un handler `@RealtimeInbound` reçoit `(params, reply, connection)`. Le troisième argument porte
+l'identité résolue à la poignée de main : `connection.userId` est l'auteur, et c'est lui qu'on
+écrit dans le message — jamais un champ de la charge, où le client peut mentir. Ce qu'un canal
+inbound n'offre pas, en revanche : la validation du corps, la garde `@IsGranted`, le rejeu sans
+doublon (`@Idempotent`), et la même porte en HTTP.
 
-La voie qui donne l'identité est celle de l'[étape 2](#-étape-2--le-même-contrôleur-sert-http-et-websocket) :
+Ces garanties-là viennent par la voie de l'[étape 2](#-étape-2--le-même-contrôleur-sert-http-et-websocket) :
 une **action de contrôleur**, atteinte par la socket. Sur ce chemin, le framework établit le contexte
 de requête avec le jeton de la connexion — exactement comme en HTTP — et les décorateurs habituels
 fonctionnent :
@@ -851,52 +871,57 @@ fonctionnent :
 ```ts ignore
 // 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";
+import { z } from "zod";
+import { Idempotent, IsGranted } from "@nodefony/framework";
+import type { RouteInput } from "@nodefony/framework";
+
+/** Ce que l'envoi accepte — VALIDÉ par le framework avant l'action, par les deux portes. */
+const SendBody = z.object({ text: z.string().trim().min(1).max(2000) });
 
 /**
  * L'envoi devient une action, joignable en POST HTTP comme par la socket.
  * On y gagne ce qu'un canal inbound ne peut pas offrir : l'identité vérifiée
- * (`@CurrentUser`), la garde d'autorisation, et le pipeline complet.
+ * (`this.user`), la garde d'autorisation, la validation du corps et le
+ * pipeline complet.
  */
 @route("chat-send", {
   path: "/send",
   requirements: { methods: ["POST", "WEBSOCKET"] },
+  schema: { body: SendBody },
 })
 @IsGranted(["ROLE_USER"])
-async send(
-  @Body() payload: { text?: string },
-  @CurrentUser() user: IUser,
-) {
-  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);
-  }
-
-  // L'auteur vient du SERVEUR. Le client ne peut plus mentir dessus.
+@Idempotent()
+send(input: RouteInput<{ body: typeof SendBody }>) {
+  // Corps vide, trop long, champ manquant : refusé AVANT d'arriver ici, par un
+  // 422 qui nomme le champ — en HTTP comme par la socket. Ici, `input.body.text`
+  // est une chaîne valide, rognée.
+  // L'auteur vient du SERVEUR (la zone l'a posé). Le client ne peut plus mentir dessus.
   const message: ChatMessage = {
-    author: user.identifier,
-    text,
+    author: this.user?.identifier ?? "anon.",
+    text: input.body.text,
     sentAt: Date.now(),
   };
 
   getRealtimeHub().publish(ROOM_CHANNEL, message);
-  return { ok: true, sentAt: message.sentAt };
+  return { sentAt: message.sentAt };
 }
 ```
 
-Côté navigateur, l'envoi passe alors par `mutate`, qui porte la méthode HTTP logique et une clé
-d'idempotence — une socket qui se reconnecte peut rejouer une frame, la clé évite le doublon :
+Côté navigateur, l'envoi passe par `post` — le **verbe de la route** : une route `POST` s'appelle
+`socket.post(…)`, une route `GET` `socket.get(…)`, rien d'autre à apprendre. La socket pose seule une
+**clé d'idempotence** sur chaque écriture : une socket qui se reconnecte peut rejouer une trame, et
+`@Idempotent()` reconnaît la clé et rend la réponse déjà calculée au lieu de publier deux fois.
 
 ```tsx ignore
 // frontend/src/ChatRoom.tsx (étape 5)
-await socket.mutate("/chat/send", {
-  method: "POST",
-  body: { text },
-  idempotencyKey: crypto.randomUUID(),
-});
+await socket.post("/chat/send", { text });
 ```
 
+> [!NOTE]
+> Une clé par **appel**, posée par la socket. Pour dédoublonner une **intention** — un double clic
+> sur « Envoyer » qui part deux fois —, l'écran fournit la sienne : `socket.post("/chat/send", { text
+}, { idempotencyKey: brouillon.id })`. Deux appels, une seule clé, un seul message.
+
 > [!TIP]
 > **La règle à retenir.** Canal inbound = flux volatil, à haute fréquence, dont l'expéditeur importe
 > peu (« untel écrit »). Action de contrôleur = tout ce qui doit être **attribué, autorisé ou
@@ -917,6 +942,212 @@ const identity = useNodefonyIdentity();
 //   identity.roles                     → pour masquer ce qui n'est pas permis
 ```
 
+### Quatre : un contrat pour les deux côtés — l'envoi et les messages privés typés
+
+À ce stade, tout marche, mais rien ne relie les deux côtés. `socket.post("/chat/send", { texte:
+"salut" })` — avec une faute de frappe — compile, part sur le réseau, et revient en 422. Le résultat
+de `post` est `unknown`. Le message privé n'existe pas encore. Les trois se règlent par **un seul
+fichier** que le serveur et le navigateur partagent : le **contrat**.
+
+**Le principe : une seule source.** Le corps de `/chat/send`, c'est le schéma `SendBody` que la route
+valide. Le contrat ne le **recopie** pas (`body: { text: string }`) : il le **référence**
+(`typeof SendBody`). Recopier, c'est écrire deux formes qui divergeront un jour sans que rien ne le
+dise — le schéma accepte `to`, la copie l'ignore, et le navigateur ne peut plus l'envoyer.
+
+#### Le schéma partagé — fichier **créé**
+
+```ts ignore
+// shared/chatSchemas.ts — la SEULE définition du corps de l'envoi
+import { z } from "zod";
+
+export const SendBody = z.object({
+  text: z.string().trim().min(1).max(2000),
+  /** Destinataire d'un message privé : l'`id` STABLE de son compte. Absent = le salon. */
+  to: z.string().optional(),
+});
+
+/** La query de l'historique — une query arrive en texte, `coerce` la convertit. */
+export const HistoryQuery = z.object({
+  limit: z.coerce.number().int().min(1).max(200).default(50),
+  /** Rattrapage après une coupure : les messages postérieurs à cet instant. */
+  since: z.coerce.number().optional(),
+});
+```
+
+#### Le contrat — fichier **créé**
+
+```ts ignore
+// shared/chatContract.ts — des TYPES seulement
+import type { IRealtimeContract } from "nodefony/client";
+import type { HistoryQuery, SendBody } from "./chatSchemas";
+
+export interface ChatMessage {
+  author: string;
+  text: string;
+  sentAt: number;
+  /** Présent sur un message privé. */
+  to?: string;
+}
+
+/** Ce qu'on annonce au salon quand un fichier a fini d'arriver (étape 6). */
+export interface ChatAttachment {
+  author: string;
+  filename: string;
+  size: number;
+  mimeType: string | null | undefined;
+  sentAt: number;
+}
+
+export interface ChatContract extends IRealtimeContract {
+  /** Ce que le serveur pousse : le salon, et le canal personnel de chacun. */
+  serverToClient: {
+    "chat:room": ChatMessage | ChatAttachment;
+    [channel: `user:${string}`]: ChatMessage;
+  };
+  /** Les routes que la socket appelle : "<VERBE> <chemin>" → corps, query, résultat. */
+  serverRoutes: {
+    "POST /chat/send": { body: typeof SendBody; result: { sentAt: number } };
+    "GET /chat/history": { query: typeof HistoryQuery; result: ChatMessage[] };
+  };
+}
+```
+
+`import type` est le point qui compte : le navigateur lit `typeof SendBody` **à la compilation**, et
+n'embarque **aucun octet** de zod. Le fichier du contrat, fait de types seuls, disparaît à la
+construction.
+
+#### Le serveur — fichier **modifié**
+
+```ts ignore
+// modules/chat/nodefony/controllers/ChatController.ts
+import { ContractRealtimeController, getRealtimeHub } from "@nodefony/realtime";
+import type { ContractRouteSchemas } from "nodefony";
+import type { RouteInput } from "@nodefony/framework";
+import { HistoryQuery, SendBody } from "../../../../shared/chatSchemas";
+import type {
+  ChatContract,
+  ChatMessage,
+} from "../../../../shared/chatContract";
+
+@controller("/chat")
+class ChatController extends ContractRealtimeController<ChatContract> {
+  /**
+   * Les VALEURS des routes du contrat — le schéma même que chaque route valide.
+   * Vérifiées au démarrage (voir plus bas) ; jamais envoyées au navigateur.
+   */
+  static readonly serverRoutes = {
+    "POST /chat/send": { body: SendBody },
+    "GET /chat/history": { query: HistoryQuery },
+  } satisfies ContractRouteSchemas<ChatContract>;
+
+  // La route de l'historique valide désormais `schema: { query: HistoryQuery }`
+  // (version complète plus bas) ; l'envoi, son corps :
+  @route("chat-send", {
+    path: "/send",
+    requirements: { methods: ["POST", "WEBSOCKET"] },
+    schema: { body: SendBody },
+  })
+  @IsGranted(["ROLE_USER"])
+  @Idempotent()
+  send(input: RouteInput<{ body: typeof SendBody }>) {
+    const me = this.user;
+    if (me === null) throw new HttpError("connexion requise", 401);
+    const { text, to } = input.body;
+    const message: ChatMessage = {
+      author: me.identifier,
+      text,
+      sentAt: Date.now(),
+    };
+    const hub = getRealtimeHub<ChatContract>();
+    if (to === undefined) {
+      hub.publish("chat:room", message);
+    } else {
+      // Message privé : le destinataire, sur TOUS ses onglets et TOUS les
+      // serveurs — et une copie à l'expéditeur, pour ses autres onglets.
+      hub.publishToUser(to, { ...message, to });
+      hub.publishToUser(me.id, { ...message, to });
+    }
+    return { sentAt: message.sentAt };
+  }
+}
+```
+
+`satisfies ContractRouteSchemas<ChatContract>` fait vérifier la table par le compilateur : une route
+du contrat **oubliée**, une route **en trop**, un **autre** schéma que `typeof SendBody` — et le
+fichier ne compile pas. `getRealtimeHub<ChatContract>()` type la diffusion : `hub.publish("chat:room",
+{ txt: "…" })` ne compile pas davantage.
+
+Le message privé ne demande **rien d'autre**. Le canal personnel `user:<id>` est une brique du
+framework : seule l'identité `<id>` peut s'y abonner, il traverse le bus entre serveurs, et
+personne ne paie rien tant qu'aucun écran ne l'écoute (détail : [securite.md](./securite.md)).
+
+#### Le navigateur — fichier **modifié**
+
+```ts ignore
+// frontend/src/realtime.ts — la socket, typée par le contrat
+import { NodefonySocket } from "nodefony/client";
+import type { ChatContract } from "../../shared/chatContract";
+
+export const chatSocket = NodefonySocket.fromContract<ChatContract>({
+  url: `${scheme}://${window.location.host}/chat/realtime`,
+});
+```
+
+```tsx ignore
+// frontend/src/ChatRoom.tsx (étape 5, typée)
+// Les messages privés de CET utilisateur : `m` est un ChatMessage, sans annotation.
+useEffect(() => chatSocket.onUser((m) => addPrivate(m)), []);
+
+// L'historique : ChatMessage[] — déduit de la route, query vérifiée.
+const past = await chatSocket.get("/chat/history", { query: { limit: 50 } });
+
+// L'envoi : le corps est l'ENTRÉE du schéma, le résultat est { sentAt: number }.
+const { sentAt } = await chatSocket.post("/chat/send", { text });
+await chatSocket.post("/chat/send", { text, to: bob.id }); // message privé
+
+// Et ce qui ne compile plus :
+await chatSocket.post("/chat/send", { texte: "x" }); // ✗ `texte` n'existe pas dans SendBody
+await chatSocket.post("/chat/send"); // ✗ le schéma exige un corps
+```
+
+Un chemin **hors contrat** reste libre — `chatSocket.get("/stats")` rend `unknown`,
+`chatSocket.get<Stats>("/stats")` le type choisi — : le contrat type ce qu'il déclare, il n'interdit
+rien d'autre.
+
+Une route à **paramètre de chemin** se déclare par son gabarit — la clé est le chemin de la route,
+`{id}` compris — et s'appelle en NOMMANT ce gabarit ; la socket le remplit :
+
+```ts ignore
+// contrat — la route valide `schema: { params: IdParams }`
+"GET /chat/messages/{id}": { params: typeof IdParams; result: ChatMessage };
+
+// navigateur
+const m = await chatSocket.get("/chat/messages/{id}", { params: { id } });
+await chatSocket.get("/chat/messages/{id}");                 // ✗ `params.id` manquant
+```
+
+Chaque valeur est encodée pour tenir dans **un** segment : un identifiant qui contient `/` ou `?`
+ne peut pas détourner l'appel vers une autre route, et une valeur vide, `.` ou `..` — que la
+normalisation du chemin résoudrait en remontant d'un cran — est refusée avant l'envoi. Sans
+schéma `params`, les valeurs sont typées par les `{noms}` du gabarit. Seuls des segments
+`{nom}` entiers se déclarent : une contrainte s'écrit dans `requirements` de la route, pas en
+ligne (`{id}(\d+)`) — le démarrage le refuse en nommant l'entrée.
+
+#### Ce que le démarrage refuse
+
+Le contrat est un **type** : il fait compiler `chatSocket.post("/chat/send", …)` même si la route
+n'existe pas. C'est la table `serverRoutes` qui porte les **valeurs**, et le démarrage les confronte
+aux routes montées — une fois, coût nul par requête. Trois fautes, trois refus qui nomment l'entrée :
+
+| Faute                                                         | Le démarrage s'arrête sur                                                                |
+| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| La route n'existe pas (chemin mal recopié, module non chargé) | `ChatController.serverRoutes « POST /chat/send » : aucune route montée au chemin …`      |
+| La route sert HTTP seulement (`methods: ["POST"]`)            | `… ne sert pas POST par la socket — ses méthodes doivent inclure "POST" et "WEBSOCKET".` |
+| La route valide un autre schéma (copie, ou schéma redéclaré)  | `… le schéma « body » n'est pas celui que la route valide (même objet attendu).`         |
+
+Sans ce contrôle, chacune de ces fautes compilerait, démarrerait, et n'apparaîtrait qu'au premier
+message envoyé — chez l'utilisateur.
+
 ### Ce que voit précisément un intrus
 
 Rien n'échoue en silence, et rien ne renseigne l'attaquant sur **pourquoi** il échoue.
@@ -1204,19 +1435,23 @@ La seule chose qui n'y figure pas est la persistance : `ChatController.history`
 mémoire, que l'[étape 4](#-étape-4--persister-lhistorique) remplace par un appel à ton service.
 C'est délibéré — ce fichier doit compiler sans supposer ta base.
 
+Il importe les deux fichiers partagés de l'[étape 5](#quatre--un-contrat-pour-les-deux-côtés--lenvoi-et-les-messages-privés-typés) :
+`shared/chatSchemas.ts` (les schémas que les routes valident) et `shared/chatContract.ts` (le
+contrat, types seuls).
+
 ```ts ignore
 // modules/chat/nodefony/controllers/ChatController.ts — version finale
 import {
   controller,
   route,
-  Body,
-  Query,
-  CurrentUser,
+  Idempotent,
   IsGranted,
   UploadedFile,
 } from "@nodefony/framework";
+import type { RouteInput } from "@nodefony/framework";
 import {
-  RealtimeController,
+  ContractRealtimeController,
+  RealtimeBroadcast,
   RealtimeChannel,
   RealtimeInbound,
   getRealtimeHub,
@@ -1224,29 +1459,30 @@ 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 {
-  author: string;
-  text: string;
-  sentAt: number;
-}
-
-/** Ce qu'on annonce au salon quand un fichier a fini d'arriver. */
-export interface ChatAttachment {
-  author: string;
-  filename: string;
-  size: number;
-  mimeType: string | null | undefined;
-  sentAt: number;
-}
+import type { ContractRouteSchemas } from "nodefony";
+import { HistoryQuery, SendBody } from "../../../../shared/chatSchemas";
+import type {
+  ChatAttachment,
+  ChatContract,
+  ChatMessage,
+} from "../../../../shared/chatContract";
 
 /** Le nom du canal du salon. Cité côté serveur ET côté client → une constante. */
 export const ROOM_CHANNEL = "chat:room";
 
+// Le salon traverse les serveurs (étape 7) : sans cette ligne, il reste sur le sien.
+@RealtimeBroadcast("chat:")
 @controller("/chat")
-class ChatController extends RealtimeController {
+class ChatController extends ContractRealtimeController<ChatContract> {
+  /**
+   * Les VALEURS des routes du contrat — le schéma même que chaque route valide.
+   * Vérifiées au démarrage ; jamais envoyées au navigateur.
+   */
+  static readonly serverRoutes = {
+    "POST /chat/send": { body: SendBody },
+    "GET /chat/history": { query: HistoryQuery },
+  } satisfies ContractRouteSchemas<ChatContract>;
+
   /** Stock en mémoire — remplacé par un repository à l'étape 4. */
   static history: ChatMessage[] = [];
 
@@ -1262,9 +1498,6 @@ class ChatController extends RealtimeController {
     return true;
   }
 
-  /** Ce qui doit franchir les frontières de processus (étape 7). */
-  // (préfixe diffusable déclaré par `@RealtimeBroadcast` sur la classe)
-
   // ── La porte WebSocket ────────────────────────────────────────────────────
 
   @route("chat-realtime", {
@@ -1277,38 +1510,50 @@ class ChatController extends RealtimeController {
 
   // ── Les actions : HTTP et WebSocket, même code ────────────────────────────
 
-  /** Historique — `GET /chat/history` ou `socket.request("/chat/history")`. */
+  /** Historique — `GET /chat/history` ou `socket.get("/chat/history")`. */
   @route("chat-history", {
     path: "/history",
     requirements: { methods: ["GET", "WEBSOCKET"] },
+    schema: { query: HistoryQuery },
   })
-  historyAction(@Query("limit") limit?: string): ChatMessage[] {
-    const max = Math.min(Number(limit) || 50, 200);
-    return ChatController.history.slice(-max);
+  historyAction(
+    input: RouteInput<{ query: typeof HistoryQuery }>,
+  ): ChatMessage[] {
+    const { limit, since } = input.query;
+    return ChatController.history
+      .filter((m) => since === undefined || m.sentAt > since)
+      .slice(-limit);
   }
 
-  /** Envoi — l'auteur vient du serveur, jamais du client. */
+  /** Envoi — au salon, ou en privé à une personne ; l'auteur vient du serveur. */
   @route("chat-send", {
     path: "/send",
     requirements: { methods: ["POST", "WEBSOCKET"] },
+    schema: { body: SendBody },
   })
   @IsGranted(["ROLE_USER"])
-  async send(
-    @Body() payload: { text?: 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);
-    }
+  @Idempotent()
+  send(input: RouteInput<{ body: typeof SendBody }>): { sentAt: number } {
+    const me = this.user;
+    if (me === null) throw new HttpError("connexion requise", 401);
+    const { text, to } = input.body;
     const message: ChatMessage = {
-      author: user.identifier,
+      author: me.identifier,
       text,
       sentAt: Date.now(),
     };
-    ChatController.history.push(message);
-    getRealtimeHub().publish(ROOM_CHANNEL, message);
-    return { ok: true, sentAt: message.sentAt };
+    const hub = getRealtimeHub<ChatContract>();
+    if (to === undefined) {
+      ChatController.history.push(message);
+      hub.publish(ROOM_CHANNEL, message);
+    } else {
+      // Le destinataire sur tous ses onglets et tous les serveurs, et une copie
+      // à l'expéditeur pour ses autres onglets. Rien à déclarer : `user:<id>`
+      // est un canal du framework.
+      hub.publishToUser(to, { ...message, to });
+      hub.publishToUser(me.id, { ...message, to });
+    }
+    return { sentAt: message.sentAt };
   }
 
   /** Pièce jointe — entre en POST multipart, ressort par le canal. */
@@ -1319,13 +1564,12 @@ class ChatController extends RealtimeController {
   @IsGranted(["ROLE_USER"])
   async upload(
     @UploadedFile() file?: IUploadedFile,
-    @CurrentUser() user: IUser,
-  ): Promise<{ ok: true; filename: string; size: number }> {
+  ): Promise<{ filename: string; size: number }> {
     if (!file) {
       throw new HttpError("aucun fichier reçu", 400);
     }
     const announcement: ChatAttachment = {
-      author: user.identifier,
+      author: this.user?.identifier ?? "anon.",
       filename: file.filename,
       size: file.size,
       mimeType: file.mimeType,
@@ -1334,7 +1578,7 @@ class ChatController extends RealtimeController {
     // La requête HTTP répondra à SON auteur ; cette publication atteint tout le
     // salon. Un transport entre, un autre sort — dans la même méthode.
     getRealtimeHub().publish(ROOM_CHANNEL, announcement);
-    return { ok: true, filename: file.filename, size: file.size };
+    return { filename: file.filename, size: file.size };
   }
 
   // ── Les canaux ────────────────────────────────────────────────────────────
@@ -1367,7 +1611,11 @@ class ChatController extends RealtimeController {
   /** Le seul canal entrant restant : haute fréquence, sans enjeu d'identité. */
   @RealtimeInbound("chat:typing")
   onTyping(params: unknown): void {
-    const author = (params as { author?: unknown } | null)?.author;
+    // Une entrée réseau n'est pas fiable : on la RÉDUIT, on ne la convertit pas.
+    const author =
+      typeof params === "object" && params !== null && "author" in params
+        ? params.author
+        : undefined;
     if (typeof author !== "string" || author.length === 0) return;
     getRealtimeHub().publish("chat:typing", { author: author.slice(0, 40) });
   }
@@ -1402,7 +1650,7 @@ useEffect(() => {
   if (state !== "connected") return;
   const lastSeen = messages.at(-1)?.sentAt ?? 0;
   void socket
-    .request<ChatMessage[]>(`/chat/history?since=${lastSeen}`)
+    .get<ChatMessage[]>("/chat/history", { query: { since: lastSeen } })
     .then((missed) => setMessages((previous) => [...previous, ...missed]));
 }, [state]);
 ```
@@ -1613,14 +1861,14 @@ Pour qui veut lire l'implémentation derrière chaque étape :
 | La publication et le fan-out | `RealtimeHub.publish()` (`RealtimeHub.ts#RealtimeHub.publish`), réinjection locale `RealtimeHub.publishLocal()` (`RealtimeHub.ts#RealtimeHub.publishLocal`) |
 | Les canaux diffusables | `RealtimeBroadcast` (`realtimeDecorators.ts#RealtimeBroadcast`), `RealtimeHub.markBroadcastChannel()` (`RealtimeHub.ts#RealtimeHub.markBroadcastChannel`) |
 | Le branchement du backplane | `RealtimeHub.setBackplane()` (`RealtimeHub.ts#RealtimeHub.setBackplane`), registre `registerBackplaneDriver()` (`backplaneRegistry.ts#registerBackplaneDriver`), cloison `resolveBackplaneOriginId()` (`originId.ts#resolveBackplaneOriginId`) |
-| Les politiques de canal | `IChannelPolicy` (`IChannelPolicy.ts#IChannelPolicy`), `RealtimeHub.registerChannelPolicy()` (`RealtimeHub.ts#RealtimeHub.registerChannelPolicy`), garde-fou `RealtimeHub.hasUnenforcedChannelPolicies()` (`RealtimeHub.ts#RealtimeHub.hasUnenforcedChannelPolicies`) |
+| Les politiques de canal | `IChannelPolicy` (`nodefony/src/realtime/channelAdmission.ts#IChannelPolicy`), `RealtimeHub.registerChannelPolicy()` (`RealtimeHub.ts#RealtimeHub.registerChannelPolicy`), garde-fou `RealtimeHub.hasUnenforcedChannelPolicies()` (`RealtimeHub.ts#RealtimeHub.hasUnenforcedChannelPolicies`) |
 | Le branchement automatique du firewall | `Firewall.#wireRealtime()` (`firewall.ts#Firewall.#wireRealtime`) |
 | Les refus | `IRealtimeDenied` (`RealtimeEventMap.ts#IRealtimeDenied`), erreur `unauthorized` (`JsonRpcPeer.ts#JsonRpcPeer.receive`), fermetures `origin not allowed` (`RealtimeController.ts#RealtimeController.notifyClient`) et `unauthorized` (`RealtimeController.ts#RealtimeController.onHandshake`) |
 | La révocation en cours de session | `RealtimeHub.revalidateRevocable()` (`RealtimeHub.ts#RealtimeHub.revalidateRevocable`) |
 | Le consommateur lent | seuil `SLOW_CONSUMER_BYTES` (`RealtimeHub.ts#SLOW_CONSUMER_BYTES`), fermeture `slow consumer` (`RealtimeHub.ts#SLOW_CONSUMER_BYTES`) |
 | Le plafond de canaux | `RealtimeHub.maxChannelsPerConnection` (`RealtimeHub.ts#RealtimeHub.maxChannelsPerConnection`) |
 | L'accueil et l'identité | `IRealtimeWelcome` (`RealtimeEventMap.ts#IRealtimeWelcome`) |
-| La sonde | `RealtimeHub.probe()` (`RealtimeHub.ts#RealtimeHub.probe`), `IRealtimeProbe` (`IRealtimeProbe.ts#IRealtimeProbe`), `IRealtimeChannelStat` (`IRealtimeProbe.ts#IRealtimeChannelStat`) |
+| La sonde | `RealtimeHub.probe()` (`RealtimeHub.ts#RealtimeHub.probe`), `IRealtimeProbe` (`nodefony/src/realtime/platformHealth.ts#IRealtimeProbe`), `IRealtimeChannelStat` (`nodefony/src/realtime/platformHealth.ts#IRealtimeChannelStat`) |
 | Le point de mesure d'administration | `createRealtimeAdminApi()` (`RealtimeAdminApi.ts#createRealtimeAdminApi`), `buildRealtimeHealth()` (`RealtimeAdminApi.ts#buildRealtimeHealth`), `buildOwnHealth()` (`RealtimeAdminApi.ts#buildOwnHealth`) |
 | Le service injectable | `RealtimeService.publish()` (`RealtimeService.ts#RealtimeService.publish`), `RealtimeService.probe()` (`RealtimeService.ts#RealtimeService.probe`), `RealtimeService.markBroadcastChannel()` (`RealtimeService.ts#RealtimeService.markBroadcastChannel`) |
 | Les hooks React | `useNodefony()` (`client/react/index.ts#useNodefony`), `useNodefonyState()` (`client/react/index.ts#useNodefonyState`), `useNodefonyIdentity()` (`client/react/index.ts#useNodefonyIdentity`), `useNodefonyChannel()` (`client/react/index.ts#useNodefonyChannel`), `useNodefonyChannelData()` (`client/react/index.ts#useNodefonyChannelData`), `useNodefonyAdaptiveChannel()` (`client/react/index.ts#useNodefonyAdaptiveChannel`) |

package/docs/index.md

@@ -46,7 +46,9 @@ Quatre parcours selon ce que tu viens faire. L'ordre compte : chaque étape supp
 2. [Ce que le module apporte](#-ce-que-le-module-apporte) — pourquoi une couche de plus au-dessus de
    la WebSocket, et ce qu'elle t'évite d'écrire.
 3. [Architecture](./architecture.md) — le trajet complet d'une frame, du câble jusqu'à ta méthode.
-4. [Cookbook — un chat](./cookbook-chat.md) — l'exemple intégrateur, de bout en bout.
+4. [Cas d'usage](./cas-d-usage.md) — jeu, salon privé, sonde, notification, tâche : l'exemple
+   court qui correspond à ton besoin, et le piège qui l'accompagne.
+5. [Cookbook — un chat](./cookbook-chat.md) — l'exemple intégrateur, de bout en bout.
 
 **Je passe d'un processus à plusieurs** — le moment où le temps réel casse sans prévenir. En
 mono-processus tout marchait ; à deux répliques, un message publié sur l'une n'atteint jamais un
@@ -93,6 +95,8 @@ Le tableau pour choisir en cinq secondes ; les cards en dessous pour savoir ce q
 | [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 |
+| [Canal à membres](./canaux-a-membres.md)                      | abonner d'office, éjecter, terminer un canal       | le serveur décide qui est dans le canal       |
+| [Cas d'usage](./cas-d-usage.md)                               | un exemple court par besoin, et son piège          | tu sais ce que tu veux construire             |
 | [Cookbook — un chat](./cookbook-chat.md)                      | l'exemple complet, client et serveur               | tu veux du code qui marche tout de suite      |
 
 ```nodefony-cards
@@ -121,6 +125,12 @@ Le tableau pour choisir en cinq secondes ; les cards en dessous pour savoir ce q
   { "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": "canaux-a-membres", "href": "./canaux-a-membres.md",
+    "desc": "Une partie à quatre, un salon fermé, un appel : le serveur abonne une connexion d'office, en éjecte une, termine le canal pour tous — et allow reste seul juge de qui entre.",
+    "meta": "le serveur décide qui est dans le canal" },
+  { "icon": "🎯", "title": "cas-d-usage", "href": "./cas-d-usage.md",
+    "desc": "Un jeu, un salon sur invitation, des capteurs, une notification personnelle, la progression d'une tâche : l'exemple de chaque besoin, exécuté par la suite de tests, avec le choix qui le justifie et l'erreur qui ne se voit qu'en production.",
+    "meta": "tu sais ce que tu veux construire" },
   { "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" }