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

package/README.md

@@ -163,20 +163,39 @@ authenticator aurait résolue, et le verrou de frame que `@nodefony/security` po
 Sans verrou, une `policy` déclarée n'est appliquée par personne — c'est vrai en test comme
 en production, `@nodefony/realtime` ne connaissant pas `@nodefony/security`.
 
+Les deux sont fournis par `@nodefony/security/testing` — le verrou est celui du pare-feu, pas
+une copie :
+
 ```ts
-const h = createRealtimeHarness((ctx) => new ChatController(ctx), {
-  identity: monToken, // IRealtimeToken
-  frameAuthorizer: buildFrameAuthorizer(firewall, {
-    // @nodefony/security
-    channelResolver: getRealtimeHub(),
-    systemRules: DEFAULT_SYSTEM_RULES,
-  }),
+import {
+  createTestFrameAuthorizer,
+  createTestIdentity,
+} from "@nodefony/security/testing";
+
+// `chat:room` exige une connexion authentifiée. Sans `identity`, le harnais
+// pose le jeton anonyme, comme le repli du runtime : le canal est refusé.
+const anonyme = createRealtimeHarness((ctx) => new ChatController(ctx), {
+  frameAuthorizer: createTestFrameAuthorizer(getRealtimeHub()),
 });
-await h.connect();
-await h.subscribe("chat:admin");
-expect(h.denials().map((d) => d.channel)).toEqual(["chat:admin"]); // refusé
+await anonyme.connect();
+await anonyme.subscribe("chat:room");
+expect(anonyme.denials().map((d) => d.channel)).toEqual(["chat:room"]);
+anonyme.dispose();
+
+// Avec une identité, le même canal est accordé.
+const alice = createRealtimeHarness((ctx) => new ChatController(ctx), {
+  identity: createTestIdentity({ identifier: "alice", roles: ["ROLE_USER"] }),
+  frameAuthorizer: createTestFrameAuthorizer(getRealtimeHub()),
+});
+await alice.connect();
+await alice.subscribe("chat:room");
+expect(alice.denials()).toHaveLength(0);
+alice.dispose();
 ```
 
+Les deux cas vont ensemble : le refus seul passerait aussi avec un canal fermé à tous, l'accord
+seul avec un canal ouvert à tous.
+
 | Membre                                      | Rôle                                                            |
 | ------------------------------------------- | --------------------------------------------------------------- |
 | `connect()`                                 | Handshake ; rend le `realtime:welcome`, jette s'il n'arrive pas |

package/dist/nodefony/src/server/RealtimeController.js

@@ -193,7 +193,7 @@ var RealtimeController = class extends Controller {
 		return {};
 	}
 	/**
-	* Opt-in du **pont API** (« API souveraine », POC Ph.3) : `true` → la
+	* Opt-in du **pont API** (une action, deux transports) : `true` → la
 	* connexion expose la méthode RPC `api.request {path}` qui re-route le path
 	* porté par le message vers l'action controller correspondante — la MÊME
 	* action que le GET REST (`socket.request("/nodefony/kernel/api/modules")`
@@ -602,7 +602,7 @@ var RealtimeController = class extends Controller {
 		};
 	}
 	/**
-	* Handler de la méthode RPC `api.request {path}` — le **pont API souverain**
+	* Handler de la méthode RPC `api.request {path}` — le **pont socket**
 	* (POC Ph.3) : résout le path porté par le message via le Router
 	* (`cleanPathOverride` — l'URL de la connexion n'est jamais mutée) puis
 	* exécute l'action SANS la rendre (`executeAction`) : la valeur nue est
@@ -713,11 +713,11 @@ var RealtimeController = class extends Controller {
 				}
 			});
 			frame?.finish(200);
-			return frame ? new RpcEnvelope(result, { requestId: frame.requestId }) : result;
+			return frame?.profiled ? new RpcEnvelope(result, { requestId: frame.requestId }) : result;
 		} catch (e) {
 			const status = httpStatusOfFrameError(e);
 			frame?.finish(status ?? 500, e);
-			throw toFrameRpcError(e, status, frame?.requestId);
+			throw toFrameRpcError(e, status, frame?.profiled ? frame.requestId : void 0);
 		} finally {
 			if (store !== null) RequestContext.release(store);
 			ctx.collectFrame(frame);

package/dist/types/nodefony/src/server/RealtimeController.d.ts

@@ -91,7 +91,7 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      */
     protected realtimeInbound(): Record<string, RealtimeInboundHandler>;
     /**
-     * Opt-in du **pont API** (« API souveraine », POC Ph.3) : `true` → la
+     * Opt-in du **pont API** (une action, deux transports) : `true` → la
      * connexion expose la méthode RPC `api.request {path}` qui re-route le path
      * porté par le message vers l'action controller correspondante — la MÊME
      * action que le GET REST (`socket.request("/nodefony/kernel/api/modules")`
@@ -245,7 +245,7 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      */
     private actionParamsWrapper;
     /**
-     * Handler de la méthode RPC `api.request {path}` — le **pont API souverain**
+     * Handler de la méthode RPC `api.request {path}` — le **pont socket**
      * (POC Ph.3) : résout le path porté par le message via le Router
      * (`cleanPathOverride` — l'URL de la connexion n'est jamais mutée) puis
      * exécute l'action SANS la rendre (`executeAction`) : la valeur nue est

package/dist/types/nodefony/testing/index.d.ts

@@ -88,9 +88,11 @@ export interface IRealtimeHarnessOptions {
     /**
      * Verrou de frame (seam #1). Neutre par construction : `@nodefony/realtime`
      * ne connaît pas `@nodefony/security`. Une application qui charge la sécurité
-     * passe ici son `buildFrameAuthorizer(...)` pour éprouver une politique de
-     * canal ou une action gardée par rôle — sans lui, une `policy` déclarée n'est
-     * appliquée par personne, exactement comme au runtime.
+     * passe ici `createTestFrameAuthorizer(getRealtimeHub())` de
+     * `@nodefony/security/testing` — le verrou du pare-feu, jamais une copie —
+     * pour éprouver une politique de canal ou une action gardée par rôle. Sans
+     * lui, une `policy` déclarée n'est appliquée par personne, exactement comme
+     * au runtime.
      */
     readonly frameAuthorizer?: FrameAuthorizer;
     /**

package/docs/actions.md

@@ -638,7 +638,28 @@ describe("ChatController — actions", () => {
 C'est l'attribut `user` du jeton que `@CurrentUser()` rend. Pour éprouver un **refus** (`@IsGranted`,
 `policy` de canal), il faut en plus le verrou de frame de `@nodefony/security`, passé en
 `frameAuthorizer` : `@nodefony/realtime` ne connaît pas la sécurité, et sans ce verrou une règle
-déclarée n'est appliquée par personne — en test comme en production. La table des membres du
+déclarée n'est appliquée par personne — en test comme en production.
+
+`@nodefony/security/testing` fournit les deux pièces, et c'est la forme à préférer au jeton écrit à
+la main ci-dessus : `createTestIdentity({ identifier, roles })`
+(`security/nodefony/testing/index.ts#createTestIdentity`) rend l'identité authentifiée, et
+`createTestFrameAuthorizer(getRealtimeHub())` (`security/nodefony/testing/index.ts#createTestFrameAuthorizer`) le **vrai**
+verrou du pare-feu — même fabrique, même hiérarchie de rôles, mêmes canaux système qu'au runtime.
+Un verrou factice qui ne regarde que `isAuthenticated()` laisse passer au vert un canal mal protégé.
+
+````ts ignore
+import { getRealtimeHub } from "@nodefony/realtime";
+import { createRealtimeHarness } from "@nodefony/realtime/testing";
+import {
+  createTestFrameAuthorizer,
+  createTestIdentity,
+} from "@nodefony/security/testing";
+
+const h = createRealtimeHarness((ctx) => new ChatController(ctx), {
+  identity: createTestIdentity({ identifier: "bob", roles: ["ROLE_USER"] }),
+  frameAuthorizer: createTestFrameAuthorizer(getRealtimeHub()),
+});
+``` La table des membres du
 harnais et l'exemple de refus sont dans le `README.md` du paquet, section « Tester un controller ».
 `nodefony create controller --kind realtime` génère ce test, identité comprise, quand l'application
 porte la sécurité.
@@ -656,3 +677,4 @@ Couverture : `npm run coverage` dans `@nodefony/realtime`.
 - La garde qui décide, côté HTTP comme WebSocket → [firewall](../../security/docs/firewall.md)
 - Les signatures exactes ne sont pas recopiées ici : elles vivent dans le graphe symbolique
   `.ai/symbols.json`, régénéré depuis les TSDoc du code.
+````

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

package/docs/securite.md

@@ -644,11 +644,20 @@ La source de vérité côté security est `buildSessionRevalidator()`
 et vérifie qu'elle est toujours vivante **et toujours celle du même utilisateur** — ce second point
 attrape le changement de compte sur un navigateur partagé.
 
+**Un changement de rôles coupe sur-le-champ, sans attendre le tick.** Quand une mise à jour du compte
+touche ses rôles, le hub ferme toutes les sockets de cette identité avec le code **4005**
+(`realtime/closeCodes.ts#IDENTITY_REFRESH_CLOSE_CODE`, `RealtimeHub.ts#RealtimeHub.#revocation`). À la
+différence de 4001 (identité morte, définitif), 4005 est **reconnectable** : le client se reconnecte
+seul et reçoit ses nouveaux rôles dans l'accueil. Les flux SSE du même compte suivent la même règle.
+Aucune lecture de base par tick ni par frame : le coût n'existe qu'à la mise à jour qui touche
+`roles`.
+
 > [!CAUTION]
 > **Trois limites à connaître.**
 >
 > 1. **Fenêtre de 30 s.** Entre le logout et le tick suivant, les flux continuent. Pour une coupure
->    immédiate, fermer la socket explicitement côté serveur.
+>    immédiate, fermer la socket explicitement côté serveur. (Un changement de **rôles**, lui, coupe
+>    immédiatement — ci-dessus.)
 > 2. **Best-effort si la session est illisible au handshake.** Si l'id ou le store ne sont pas
 >    accessibles, `buildSessionRevalidator()` renvoie `null` ; `UserRealtimeToken.isValid()`
 >    (`UserRealtimeToken.ts#UserRealtimeToken.isValid`) répond alors toujours `true`. La connexion **est** inscrite au

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/realtime",
-  "version": "10.0.0-beta.4",
+  "version": "10.0.0-beta.5",
   "nodefony": {
     "configSchema": "./dist/nodefony/config/configSchema.js"
   },
@@ -44,18 +44,18 @@
     "esm"
   ],
   "peerDependencies": {
-    "@nodefony/framework": "^10.0.0-beta.4",
-    "@nodefony/http": "^10.0.0-beta.4",
-    "nodefony": "^10.0.0-beta.4",
+    "@nodefony/framework": "^10.0.0-beta.5",
+    "@nodefony/http": "^10.0.0-beta.5",
+    "nodefony": "^10.0.0-beta.5",
     "reflect-metadata": "0.2.2",
     "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@nodefony/framework": "^10.0.0-beta.4",
-    "@nodefony/http": "^10.0.0-beta.4",
+    "@nodefony/framework": "^10.0.0-beta.5",
+    "@nodefony/http": "^10.0.0-beta.5",
     "@types/node": "26.6.5",
     "@vitest/coverage-v8": "5.0.5",
-    "nodefony": "^10.0.0-beta.4",
+    "nodefony": "^10.0.0-beta.5",
     "reflect-metadata": "0.2.2",
     "vitest": "5.0.5"
   },