@nodefony/redis 10.0.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/LICENSE +544 -0
  2. package/README.md +110 -0
  3. package/dist/_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js +9 -0
  4. package/dist/_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js +6 -0
  5. package/dist/index.js +58 -0
  6. package/dist/nodefony/config/config.js +98 -0
  7. package/dist/nodefony/config/defineModuleConfig.js +90 -0
  8. package/dist/nodefony/interfaces/IRedisConfig.js +1 -0
  9. package/dist/nodefony/interfaces/index.js +1 -0
  10. package/dist/nodefony/registerStores.js +38 -0
  11. package/dist/nodefony/service/redis.js +177 -0
  12. package/dist/nodefony/src/Connection.js +111 -0
  13. package/dist/nodefony/src/RedisTokenStore.js +390 -0
  14. package/dist/nodefony/src/RedisWebAuthnCredentialStore.js +247 -0
  15. package/dist/nodefony/src/SessionStorage.js +249 -0
  16. package/dist/nodefony/src/buildClientOptions.js +63 -0
  17. package/dist/nodefony/src/keyNamespace.js +80 -0
  18. package/dist/nodefony/src/scanCursor.js +69 -0
  19. package/dist/types/index.d.ts +53 -0
  20. package/dist/types/nodefony/config/config.d.ts +41 -0
  21. package/dist/types/nodefony/config/defineModuleConfig.d.ts +26 -0
  22. package/dist/types/nodefony/interfaces/IRedisConfig.d.ts +17 -0
  23. package/dist/types/nodefony/interfaces/index.d.ts +5 -0
  24. package/dist/types/nodefony/registerStores.d.ts +5 -0
  25. package/dist/types/nodefony/service/redis.d.ts +82 -0
  26. package/dist/types/nodefony/src/Connection.d.ts +39 -0
  27. package/dist/types/nodefony/src/RedisTokenStore.d.ts +121 -0
  28. package/dist/types/nodefony/src/RedisWebAuthnCredentialStore.d.ts +108 -0
  29. package/dist/types/nodefony/src/SessionStorage.d.ts +87 -0
  30. package/dist/types/nodefony/src/buildClientOptions.d.ts +21 -0
  31. package/dist/types/nodefony/src/keyNamespace.d.ts +12 -0
  32. package/dist/types/nodefony/src/scanCursor.d.ts +50 -0
  33. package/docs/architecture.md +718 -0
  34. package/docs/configuration.md +773 -0
  35. package/docs/index.md +295 -0
  36. package/package.json +95 -0
@@ -0,0 +1,718 @@
1
+ ---
2
+ title: "Architecture interne — connexions, stores et fond de panier"
3
+ navTitle: Architecture interne
4
+ lang: fr
5
+ module: "@nodefony/redis"
6
+ topic: redis
7
+ section: "Persistance"
8
+ audience: [developer, devops]
9
+ tags:
10
+ [
11
+ redis,
12
+ architecture,
13
+ connexion,
14
+ resilience,
15
+ reconnexion,
16
+ ttl,
17
+ scan,
18
+ pagination,
19
+ backplane,
20
+ pubsub,
21
+ ]
22
+ version: "doc"
23
+ status: stable
24
+ updated: 2026-07-19
25
+ source: "src/packages/@nodefony/redis/docs/architecture.md"
26
+ coverageModule: redis
27
+ ---
28
+
29
+ # Architecture interne de @nodefony/redis
30
+
31
+ > Ce module n'est pas un magasin : c'est un **fournisseur de connexions**. Il ouvre N sockets Redis
32
+ > nommées au démarrage, les surveille, les referme proprement — et les prête à quatre locataires qui
33
+ > ne se connaissent pas : les sessions, les jetons, les passkeys, l'idempotence. Un cinquième, le
34
+ > temps réel, ne stocke rien et se sert du pub/sub. Cette page décrit ce qui se passe **dedans** :
35
+ > le cycle de vie d'une connexion, les structures de données réellement écrites dans Redis, ce que
36
+ > le module fait le jour où Redis tombe, et ce que l'énumération d'administration sait — ou refuse
37
+ > de savoir.
38
+
39
+ 📍 [Documentation](../../../../../docs/index.md) › [@nodefony/redis](index.md) › **Architecture interne**
40
+
41
+ ## 🧠 Le modèle mental — un tuyau, quatre locataires
42
+
43
+ Le module se lit de haut en bas comme une canalisation. En haut, une **classe de module** qui valide
44
+ la configuration au démarrage. Au milieu, un **service** qui tient la carte des connexions ouvertes.
45
+ En bas, des **enveloppes de connexion** qui possèdent chacune un client de la bibliothèque `redis`.
46
+
47
+ Le point important de ce schéma : **les stores ne sont pas dans la canalisation**, ils sont branchés
48
+ dessus. Aucun d'eux n'ouvre de socket ; tous demandent au service la connexion `main` au moment où
49
+ ils en ont besoin, et acceptent qu'elle ne soit pas là.
50
+
51
+ ```mermaid
52
+ flowchart TD
53
+ MOD["Redis (Module)<br/>valide la config, gèle, enregistre les fabriques"]
54
+ SVC["RedisService<br/>carte des connexions, cycle de vie"]
55
+ CMAIN["Connection main<br/>commandes clé-valeur"]
56
+ CPUB["Connection publish"]
57
+ CSUB["Connection subscribe"]
58
+ LIB["clients lib redis v6"]
59
+
60
+ MOD -->|@services| SVC
61
+ SVC --> CMAIN
62
+ SVC --> CPUB
63
+ SVC --> CSUB
64
+ CMAIN --> LIB
65
+ CPUB --> LIB
66
+ CSUB --> LIB
67
+
68
+ SESS["RedisSessionStorage<br/>nf:sess:*"] -.->|getClient main| SVC
69
+ TOK["RedisTokenStore<br/>nf:tok:*"] -.->|getClient main| SVC
70
+ WAC["RedisWebAuthnCredentialStore<br/>nf:wac:*"] -.->|getClient main| SVC
71
+ IDEM["RedisIdempotencyStore<br/>nf:idem:*"] -.->|getClient main| SVC
72
+ BP["RedisBackplane<br/>canal nodefony:realtime"] -.->|getClient publish + subscribe| SVC
73
+ ```
74
+
75
+ Les flèches pleines sont des **possessions** (le service possède ses connexions, il les ferme).
76
+ Les flèches pointillées sont des **emprunts** : le store demande, le service prête, personne ne
77
+ retient rien. C'est ce qui permet à un store d'exister avant que la connexion soit ouverte — et de
78
+ survivre à sa fermeture.
79
+
80
+ ## 📖 Lexique
81
+
82
+ | Terme | Sens |
83
+ | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
84
+ | Keyspace | L'ensemble des clés d'une base Redis. `SCAN` le parcourt ; sa taille conditionne le coût de toute énumération. |
85
+ | TTL | _Time To Live_ : durée de vie posée sur une clé. Redis l'efface seul à l'échéance — aucun balayage applicatif à écrire. |
86
+ | `SET … EX` | Écriture d'une valeur **avec** son TTL en une seule commande. Une écriture sans `EX` crée une clé immortelle. |
87
+ | `EXPIRE` | Repositionne le TTL d'une clé existante sans toucher à sa valeur. O(1) — c'est le « touch » le moins cher. |
88
+ | `SCAN` | Parcours incrémental du keyspace, lot par lot, avec un curseur. L'alternative sûre à `KEYS`, qui bloquerait le serveur. |
89
+ | `COUNT` (de `SCAN`) | **Indice d'effort** par itération, pas un plafond : Redis peut rendre plus de clés que demandé. |
90
+ | Listpack | Encodage compact d'un petit keyspace. C'est lui qui fait rendre _toutes_ les clés d'un coup à un `SCAN`, quel que soit le `COUNT`. |
91
+ | HASH | Structure Redis « un objet à champs ». Permet d'écrire un champ sans réécrire l'objet ni toucher son TTL. |
92
+ | SET (structure) | Ensemble non ordonné de membres. Sert ici d'**index secondaire** (les jetons d'un porteur, les passkeys d'un utilisateur). |
93
+ | Index orphelin | Un membre d'index qui pointe vers un enregistrement déjà expiré. Nettoyé **paresseusement**, à la lecture. |
94
+ | Offline queue | File d'attente interne du client `redis` : pendant une reconnexion, les commandes y patientent au lieu d'échouer tout de suite. |
95
+ | RESP3 | Version 3 du protocole Redis, activée par défaut en `redis` v6. Les commandes utilisées ici sont identiques à RESP2. |
96
+ | Pub/sub | Publication/abonnement : un message atteint tous les abonnés du canal, sans jamais être stocké ni rejoué. |
97
+ | Backplane | « Fond de panier » : le transport qui relie les process entre eux pour que le temps réel dépasse un seul pod. |
98
+ | Anti-echo | Filtre qui écarte les messages qu'un pod a lui-même publiés — Redis les lui renvoie, il ne doit pas les traiter deux fois. |
99
+ | Fail-soft / fail-loud | Deux régimes de panne : continuer en dégradé (disponibilité) / refuser bruyamment (intégrité). Nodefony exige que le dégradé soit **annoncé**. |
100
+
101
+ ## Qu'est-ce que c'est ?
102
+
103
+ Imagine une baie de serveurs. Le module Redis n'est pas un serveur de la baie : c'est le **panneau de
104
+ brassage**. Il ne décide pas de ce qui circule, il garantit que les câbles sont branchés, qu'ils sont
105
+ rebranchés tout seuls si on les arrache, et qu'ils sont débranchés proprement quand on éteint.
106
+
107
+ Concrètement, il résout trois problèmes qu'aucun consommateur ne veut résoudre lui-même :
108
+
109
+ 1. **Ouvrir au bon moment.** Un store de session n'a aucune idée de l'ordre de démarrage des modules.
110
+ Il ne peut donc pas ouvrir sa propre connexion : il en emprunte une, quand il en a besoin.
111
+ 2. **Séparer les rôles.** Le protocole Redis interdit à un client abonné (`SUBSCRIBE`) d'émettre des
112
+ commandes normales. Sans séparation, activer le temps réel casserait les sessions.
113
+ 3. **Fermer sans fuir.** Un client Redis attache des écouteurs d'événements. Les oublier à la
114
+ fermeture, c'est une fuite de mémoire silencieuse à chaque redémarrage de connexion.
115
+
116
+ Ce que le module ne fait **pas** est tout aussi structurant : il n'impose aucun schéma, ne fabrique
117
+ aucune clé, ne connaît aucun de ses consommateurs. Les préfixes `nf:sess`, `nf:tok`, `nf:wac`,
118
+ `nf:idem` appartiennent aux stores, pas à lui.
119
+
120
+ ## La vision Nodefony
121
+
122
+ Trois partis pris expliquent la forme du code.
123
+
124
+ **Le module ne connaît personne ; tout le monde le connaît par son nom.** Les stores résolvent le
125
+ service par la chaîne `"redis"` dans le conteneur, jamais par un `import`. `RedisTokenStore` et
126
+ `RedisWebAuthnCredentialStore` vont plus loin : ils ne connaissent `@nodefony/security` qu'en
127
+ `import type`, effacé à la compilation. Résultat, aucune dépendance runtime ne circule entre l'infra
128
+ et la sécurité, dans aucun sens — et le graphe de modules reste acyclique.
129
+
130
+ **Charger le module suffit.** `Redis.onKernelRegister()` (`index.ts:54`) valide la configuration puis
131
+ appelle `registerRedisFrameworkStores()` (`registerStores.ts:46`), qui inscrit les fabriques `redis`
132
+ dans les registres de jetons et de passkeys. Le store de session, lui, s'auto-déclare à l'import du
133
+ fichier (`SessionStorage.ts:323`). Aucune application n'a de câblage à écrire : il ne reste qu'à
134
+ nommer le store — ou à laisser `auto` choisir.
135
+
136
+ **Le module est déclaré non critique.** `Redis.critical` vaut `false` (`index.ts:36`) : un échec de
137
+ son démarrage ne tue jamais le process. C'est un choix assumé de disponibilité — dont cette page
138
+ détaille exactement le prix dans « Résilience ».
139
+
140
+ Le contrepoint de ces trois choix : la configuration, elle, est **stricte**. Une config invalide
141
+ arrête le démarrage avec un message qui nomme le champ fautif (`index.ts:62`). Tout est dans
142
+ [Configuration](./configuration.md) — cette page n'en reprend aucune clé.
143
+
144
+ ## 🚀 Démarrage rapide
145
+
146
+ Le but ici n'est pas de configurer Redis (c'est la page voisine) mais de **voir la machinerie
147
+ tourner** : brancher les sessions sur Redis, puis regarder l'état réel des connexions et la clé
148
+ écrite dans le serveur.
149
+
150
+ ### 1. Activer le module et y poser les sessions
151
+
152
+ ```ts
153
+ // nodefony.config.ts — l'orchestrateur de l'application
154
+ export default defineConfig(() => ({
155
+ modules: [
156
+ // Redis en premier : il enregistre ses fabriques de stores au moment où le
157
+ // kernel enregistre les modules, donc AVANT que les consommateurs résolvent.
158
+ use("@nodefony/redis", {
159
+ globalOptions: {
160
+ socket: { host: "127.0.0.1", port: 6379, connectTimeout: 5000 },
161
+ },
162
+ }),
163
+ // On nomme le store explicitement : le comportement est alors le même en
164
+ // développement et en production, quelle que soit l'infra déclarée.
165
+ use("@nodefony/http", {
166
+ session: { store: "redis", name: "monapp", idleTimeoutS: 1800 },
167
+ }),
168
+ "@nodefony/framework",
169
+ ],
170
+ }));
171
+ ```
172
+
173
+ ### 2. Regarder la machinerie depuis un contrôleur
174
+
175
+ ```ts
176
+ // nodefony/controllers/RedisDiagnosticController.ts — complet, compile tel quel
177
+ import { Controller, controller, Get, Session } from "@nodefony/framework";
178
+ import type { Session as HttpSession } from "@nodefony/http";
179
+ import type { RedisService } from "@nodefony/redis";
180
+
181
+ @controller("/diagnostic/redis")
182
+ class RedisDiagnosticController extends Controller {
183
+ @Get("/session")
184
+ async inspect(@Session() session: HttpSession) {
185
+ // Écrire marque la session « mutée » : elle sera persistée en fin de requête.
186
+ session.set("vuLe", Date.now());
187
+
188
+ // Le service se résout par son NOM dans le conteneur — jamais par import.
189
+ const redis = this.get<RedisService>("redis");
190
+ // Deux niveaux : l'enveloppe (état de vie) et le client brut (commandes).
191
+ const main = redis?.getConnection("main");
192
+ const client = redis?.getClient("main");
193
+
194
+ const cle = `nf:sess:${session.id}`;
195
+ // -2 = clé absente, -1 = clé sans TTL (anomalie ici), n > 0 = secondes restantes.
196
+ const ttl = client && main?.connected ? await client.ttl(cle) : -2;
197
+
198
+ return this.renderJson({
199
+ connexions: Object.keys(redis?.connections ?? {}),
200
+ mainConnectee: main?.connected ?? false,
201
+ cle,
202
+ ttlSecondes: ttl,
203
+ });
204
+ }
205
+ }
206
+
207
+ export default RedisDiagnosticController;
208
+ ```
209
+
210
+ ### 3. Ce qu'on observe
211
+
212
+ Au démarrage, le journal nomme le backend retenu et la politique d'expiration — on ne devine jamais
213
+ où les sessions ont atterri :
214
+
215
+ ```
216
+ SESSION STORAGE active : redis
217
+ REDIS SESSIONS STORAGE ==> TTL natif idle (1800s)
218
+ REDIS CONNECTION main CONNECT 127.0.0.1:6379
219
+ ```
220
+
221
+ Puis, côté requête :
222
+
223
+ ```bash
224
+ curl -s -c cookies.txt http://127.0.0.1:5151/diagnostic/redis/session
225
+ # {"connexions":["main","publish","subscribe"],"mainConnectee":true,
226
+ # "cle":"nf:sess:9f2c…","ttlSecondes":1800}
227
+
228
+ # La même clé, vue du serveur — le TTL est bien porté par Redis lui-même.
229
+ redis-cli TTL nf:sess:9f2c… # (integer) 1800
230
+ redis-cli TYPE nf:sess:9f2c… # string
231
+ ```
232
+
233
+ Rejoue la requête après quelques secondes : le TTL est **remonté à 1800**. C'est le timeout glissant,
234
+ reposé à chaque écriture — et repositionné sans réécrire la valeur quand la session n'a pas changé.
235
+
236
+ ## 🏗️ Architecture interne
237
+
238
+ ### Les quatre couches
239
+
240
+ | Couche | Fichier | Responsabilité |
241
+ | --------- | ------------------------------------ | ------------------------------------------------------------------------------- |
242
+ | Module | `index.ts` | Valider la config au démarrage, la geler, enregistrer les fabriques de stores. |
243
+ | Service | `nodefony/service/redis.ts` | Tenir la carte des connexions, les ouvrir, les prêter, les fermer. |
244
+ | Connexion | `nodefony/src/Connection.ts` | Posséder un client `redis`, écouter ses événements, nettoyer ses écouteurs. |
245
+ | Options | `nodefony/src/buildClientOptions.ts` | Traduire la config déclarative en options `createClient` (dont la reconnexion). |
246
+
247
+ Le service porte sa carte en **allocation paresseuse** : `#connections` vaut `null` tant qu'aucune
248
+ connexion n'est ouverte (`redis.ts:33`), et redevient `null` à la fermeture. Une application qui
249
+ charge le module sans jamais ouvrir de connexion ne paie donc pas un seul objet.
250
+
251
+ ### Le démarrage, étape par étape
252
+
253
+ ```mermaid
254
+ sequenceDiagram
255
+ participant K as Kernel
256
+ participant M as Redis (Module)
257
+ participant S as RedisService
258
+ participant C as Connection
259
+ participant R as serveur Redis
260
+
261
+ K->>M: onKernelRegister
262
+ M->>M: defineRedisConfig(options) — parse, env, freeze
263
+ M->>M: registerRedisFrameworkStores()
264
+ K->>S: addService → init() sous garde de temps
265
+ loop pour chaque connexion déclarée
266
+ S->>C: new Connection(nom, options)
267
+ S->>S: enregistre la connexion dans la carte
268
+ C->>C: createClient(options) + écouteurs
269
+ C->>R: connect()
270
+ R-->>C: ready
271
+ end
272
+ Note over K,R: … vie de l'application …
273
+ K->>S: onTerminate
274
+ S->>C: close() → client.close() + removeListener
275
+ ```
276
+
277
+ Trois détails de ce schéma décident de tout le comportement en panne :
278
+
279
+ 1. `RedisService.init()` (`redis.ts:123`) enveloppe **chaque** connexion dans son propre `try/catch` :
280
+ une connexion qui échoue est journalisée en `ERROR` et les suivantes sont quand même tentées.
281
+ 2. `RedisService.createConnection()` (`redis.ts:146`) inscrit la connexion dans `#connections`
282
+ **avant** d'attendre son ouverture (`redis.ts:75`).
283
+ 3. `Connection.create()` (`Connection.ts:86`) affecte `this.client` **avant** d'appeler `connect()`.
284
+
285
+ Les points 2 et 3 sont la cause d'un comportement contre-intuitif détaillé plus bas : après un
286
+ démarrage raté, la connexion existe, le client existe — mais il est fermé.
287
+
288
+ ### Le parcours d'une commande
289
+
290
+ Prenons une lecture de session. Elle traverse exactement quatre gestes :
291
+
292
+ 1. Le store résout le service **paresseusement**, au premier accès seulement :
293
+ `RedisSessionStorage.#client()` (`SessionStorage.ts:96`) mémorise le service puis demande
294
+ `getClient("main")` à chaque appel. La résolution tardive est nécessaire — l'ordre de démarrage
295
+ des modules n'est pas garanti, le store est construit avant que Redis soit prêt.
296
+ 2. `RedisService.getClient()` (`redis.ts:191`) rend le client de la connexion nommée, ou `null`.
297
+ 3. Le store teste `null` et décide de son repli.
298
+ 4. La commande part sur le socket.
299
+
300
+ Aucune couche intermédiaire, aucun pool applicatif, aucune sérialisation imposée : le store écrit ce
301
+ qu'il veut avec le client brut. C'est ce qui permet à chaque store de choisir sa structure Redis.
302
+
303
+ ### Pourquoi trois connexions
304
+
305
+ Le protocole Redis bascule un client en mode écoute dès qu'il s'abonne : il ne peut plus émettre de
306
+ `GET`/`SET`. Une seule connexion partagée rendrait donc le temps réel et le stockage mutuellement
307
+ exclusifs. Le module tranche par la topologie : `main` pour les commandes, `publish` pour l'émission,
308
+ `subscribe` pour l'écoute. Les trois sont assemblées par `buildClientOptions()`
309
+ (`buildClientOptions.ts:45`), qui fusionne les options globales avec la surcharge de la connexion.
310
+
311
+ > [!NOTE]
312
+ > `maintNotifications: "disabled"` est forcé dans les options (`buildClientOptions.ts:58`). En
313
+ > `redis` v6, le défaut RESP3 souscrit aux notifications de maintenance de Redis Enterprise et
314
+ > relâche les délais du socket. Nodefony cible Redis OSS : on coupe, pour un comportement
315
+ > déterministe et zéro trame superflue.
316
+
317
+ ## Les données dans Redis — clés, structures, expiration
318
+
319
+ Le module n'écrit rien. Ce qui suit appartient aux quatre stores et au backplane. Le tableau donne la
320
+ vue d'ensemble ; les fiches détaillent les choix qui surprennent.
321
+
322
+ | Clé | Structure | Durée de vie | Écrit par |
323
+ | --------------------------- | -------------- | --------------------------------------------- | ----------------------------------------------- |
324
+ | `nf:sess:<id>` | STRING (JSON) | TTL = idle, reposé à chaque écriture/touch | `RedisSessionStorage` |
325
+ | `nf:tok:rec:<jti>` | HASH | TTL = `exp` du jeton, ou rétention si révoqué | `RedisTokenStore` |
326
+ | `nf:tok:hash:<secretHash>` | STRING → `jti` | même TTL que l'enregistrement | `RedisTokenStore` |
327
+ | `nf:tok:subj:<subjectId>` | SET d'ids | aucun — purge paresseuse à la lecture | `RedisTokenStore` |
328
+ | `nf:tok:fam:<family>` | SET d'ids | aucun — purge paresseuse à la lecture | `RedisTokenStore` |
329
+ | `nf:tok:deny:<jti>` | STRING `"1"` | TTL = durée restante du JWT | `RedisTokenStore` |
330
+ | `nf:tok:revsub:<subjectId>` | STRING (seuil) | aucune — monotone, jamais reculée | `RedisTokenStore` |
331
+ | `nf:wac:cred:<credId>` | HASH | **aucune** — une passkey est permanente | `RedisWebAuthnCredentialStore` |
332
+ | `nf:wac:user:<userId>` | SET d'ids | aucune — purge paresseuse à la lecture | `RedisWebAuthnCredentialStore` |
333
+ | `nf:idem:<clé>` | STRING (JSON) | TTL = fenêtre d'idempotence | `RedisIdempotencyStore` (`@nodefony/framework`) |
334
+ | `nodefony:realtime[:ns]` | canal pub/sub | rien n'est stocké | `RedisBackplane` (`@nodefony/realtime`) |
335
+
336
+ ### `nf:sess:*` — la session, une chaîne et un TTL
337
+
338
+ Une session est un blob JSON écrit d'un coup. `RedisSessionStorage.write()` (`SessionStorage.ts:123`)
339
+ pose **systématiquement** un `EX` : une clé de session sans TTL serait une session immortelle, donc un
340
+ défaut de sécurité, pas une commodité.
341
+
342
+ L'expiration par inactivité (« idle ») est donc portée par Redis lui-même. Deux conséquences
343
+ directes : `gc()` (`SessionStorage.ts:168`) est un **no-op** assumé — aucun balayage, aucune requête
344
+ de purge périodique — et `touch()` (`SessionStorage.ts:166`) se réduit à un `EXPIRE`, en O(1), **sans
345
+ réécrire la valeur**. C'est le renouvellement le moins coûteux de tous les backends de session.
346
+
347
+ L'expiration **absolue** (âge maximal, jamais prolongé) ne s'exprime pas par un TTL glissant. Elle est
348
+ donc honorée à la **lecture**, côté `@nodefony/http`. Une session au-delà de son âge maximal peut
349
+ survivre dans Redis jusqu'à la fin de son TTL d'inactivité, mais elle est refusée à la reprise.
350
+
351
+ ### `nf:tok:*` — les jetons, un HASH et quatre index
352
+
353
+ Pourquoi un HASH plutôt qu'un blob JSON comme la session ? Parce qu'un jeton est **mis à jour en
354
+ place** à chaque usage. `RedisTokenStore.markUsed()` (`RedisTokenStore.ts:436`) écrit un à trois
355
+ champs (`lastUsedAt`, IP, agent) sans relire l'enregistrement, sans le réécrire, et **sans toucher au
356
+ TTL**. Avec un blob, chaque appel d'API coûterait une lecture, une désérialisation, une réécriture —
357
+ et remettrait en jeu la date d'expiration.
358
+
359
+ Ce choix impose une précaution : `HSET` sur une clé absente la **recrée**, et une clé recréée n'a pas
360
+ de TTL. Le store vérifie donc l'existence d'abord (`RedisTokenStore.ts:254`) et ne fait rien si
361
+ l'identifiant est inconnu. Sans ce test, un jeton expiré ressusciterait, immortel, à sa prochaine
362
+ utilisation.
363
+
364
+ Les quatre index secondaires sont des SET (`subj`, `fam`) et des chaînes (`hash`, `revsub`). Aucun
365
+ n'a de TTL : ils sont nettoyés **paresseusement**, quand une lecture tombe sur un membre dont
366
+ l'enregistrement a expiré — voir `RedisTokenStore.findBySubject()` (`RedisTokenStore.ts:294`) et
367
+ `RedisTokenStore.findByHash()` (`RedisTokenStore.ts:276`).
368
+
369
+ La révocation combine les deux régimes. `RedisTokenStore.#applyRevoke()` (`RedisTokenStore.ts:470`)
370
+ pose la date et la raison, puis — si le jeton n'avait **pas** d'expiration (cas d'un PAT) — lui donne
371
+ un TTL égal à la durée de rétention. Un jeton révoqué reste donc consultable un temps, puis disparaît
372
+ tout seul.
373
+
374
+ ### `nf:wac:*` — les passkeys, permanentes par nature
375
+
376
+ Aucun TTL nulle part : un authentifiant WebAuthn ne s'évapore pas. Le contrat de ce store n'a
377
+ d'ailleurs pas de méthode de maintenance. Deux structures suffisent : un HASH par authentifiant, un
378
+ SET d'identifiants par utilisateur.
379
+
380
+ Un point de conception mérite d'être connu : `countByUser()`
381
+ (`RedisWebAuthnCredentialStore.ts:203`) utilise `SCARD`, en O(1), sans lire un seul HASH. Il peut donc
382
+ **sur-compter** les membres orphelins qu'une lecture n'a pas encore nettoyés. L'écart est assumé et
383
+ orienté **fail-closed** : au pire un enrôlement supplémentaire est refusé, jamais un de trop accepté.
384
+
385
+ > [!WARNING]
386
+ > Ces clés n'expirent jamais **de votre point de vue** — mais Redis, lui, peut les évincer si le
387
+ > serveur est configuré avec une politique de mémoire type `allkeys-lru`. Une passkey évincée, c'est
388
+ > un utilisateur enfermé dehors. Sur un Redis qui porte des passkeys, la politique d'éviction doit
389
+ > être `noeviction`, et la persistance activée.
390
+
391
+ ## 🔌 Le backplane temps réel
392
+
393
+ Le backplane est le seul consommateur qui ne stocke rien. Son problème : un message publié sur le pod
394
+ A doit atteindre un client abonné sur le pod B. Redis pub/sub est le transport ; le code vit dans
395
+ `@nodefony/realtime`, pas ici.
396
+
397
+ ```mermaid
398
+ sequenceDiagram
399
+ participant HA as Hub (pod A)
400
+ participant BA as RedisBackplane A
401
+ participant R as Redis pub/sub
402
+ participant BB as RedisBackplane B
403
+ participant HB as Hub (pod B)
404
+
405
+ HA->>HA: fan-out LOCAL (déjà fait)
406
+ HA->>BA: publish(canal, charge)
407
+ BA->>R: PUBLISH nodefony:realtime:ns — canal, charge, originId
408
+ R-->>BA: (Redis renvoie à l'émetteur)
409
+ BA->>BA: originId identique → ignoré (anti-echo)
410
+ R-->>BB: message
411
+ BB->>BB: parse + originId différent
412
+ BB->>HB: fan-out LOCAL uniquement (jamais republié)
413
+ ```
414
+
415
+ Quatre propriétés à retenir.
416
+
417
+ **Un seul canal, pas un par sujet.** Les canaux applicatifs voyagent **dans** l'enveloppe. Le
418
+ backplane fait donc un unique `SUBSCRIBE` au démarrage (`RedisBackplane.ts:18`), jamais
419
+ d'abonnement dynamique. C'est ce qui rend le coût indépendant du nombre de canaux applicatifs.
420
+
421
+ **Le cloisonnement n'est pas le numéro de base.** Le pub/sub Redis est **global au serveur** : il
422
+ ignore complètement le `database`. Deux applications sur un Redis mutualisé se parleraient. D'où le
423
+ suffixe de canal calculé par `resolveRedisChannel()` (`RedisBackplane.ts:31`) — issu de la config, ou
424
+ à défaut du nom du projet. Deux déploiements de la **même** application (préproduction et production)
425
+ dérivent le même nom : il faut alors un namespace explicite.
426
+
427
+ **L'anti-echo est structurel.** Redis renvoie à l'émetteur ce qu'il publie, puisque les connexions
428
+ `publish` et `subscribe` appartiennent au même pod. Sans filtre, chaque message serait diffusé deux
429
+ fois localement. Le tri d'entrée `RedisBackplane.#ingress()` compare donc l'identifiant d'origine à
430
+ la réception (`RedisBackplane.ts:269`) et écarte les siens.
431
+
432
+ **La livraison est au mieux, jamais garantie.** Le pub/sub Redis ne persiste ni ne rejoue : un pod
433
+ déconnecté rate ce qui a été émis pendant sa coupure. Le contrat l'assume au lieu de simuler une
434
+ fiabilité que le support n'offre pas — c'est le client temps réel qui se resynchronise.
435
+
436
+ Le branchement lui-même est **fail-soft annoncé** : la fabrique du pilote `redis`
437
+ (`realtime/index.ts:108`) journalise un `WARNING` explicite — « module absent » ou « connexions
438
+ indisponibles » — et rend `null`, ce qui laisse le hub en mode local. L'application continue de
439
+ fonctionner sur un seul pod, et le journal dit pourquoi elle n'en fait pas plus.
440
+
441
+ Détails du fan-out et du contrat de backplane : [l'architecture du temps réel](../../realtime/docs/architecture.md) ·
442
+ le format des messages : [le protocole](../../realtime/docs/protocole.md).
443
+
444
+ ## Résilience — ce qui se passe quand Redis tombe
445
+
446
+ C'est la section à lire avant une mise en production. Le principe du framework est explicite :
447
+ **fail-soft sur la disponibilité, fail-loud sur la dégradation** — un repli est acceptable, un repli
448
+ muet ne l'est pas. Voici ce que le code fait réellement, moment par moment.
449
+
450
+ ### Moment 1 — Redis est absent au démarrage
451
+
452
+ Le module est déclaré non critique (`index.ts:36`), et l'initialisation du service est **bornée dans
453
+ le temps** : `Kernel.guardInitialize()` (`Kernel.ts:3369`) enveloppe l'appel dans un délai maximal de
454
+ démarrage. Un `init()` qui pend ne gèle donc pas le boot ; l'échec est agrégé au rapport de démarrage,
455
+ qui fait dire « démarrage DÉGRADÉ » au superviseur au lieu de mentir sur un état sain.
456
+
457
+ La politique de reconnexion, elle, joue un rôle inattendu **au tout premier `connect()`**.
458
+ `buildReconnectStrategy()` (`buildClientOptions.ts:13`) rend un délai croissant borné, et une `Error`
459
+ au-delà du nombre maximal de tentatives — mais seulement si ce maximum est fini. Or le défaut du
460
+ schéma vaut `0`, c'est-à-dire **illimité** : avec ce réglage, `connect()` ne rend jamais la main
461
+ tant que Redis ne répond pas.
462
+
463
+ D'où un garde-fou spécifique au développement : `applyResilienceDefaults()`
464
+ (`defineModuleConfig.ts:65`) borne les tentatives à un nombre fini **hors production**, quand
465
+ l'application ne l'a pas fixé elle-même. Sans lui, démarrer sans Redis faisait pendre le boot au lieu
466
+ d'échouer proprement.
467
+
468
+ ### Moment 2 — la connexion est perdue en cours de vie
469
+
470
+ `Connection.create()` (`Connection.ts:86`) attache cinq écouteurs — `error`, `connect`, `ready`,
471
+ `end`, `reconnecting` — qui font deux choses : journaliser et **réémettre** l'événement sur le
472
+ service. La perte est donc visible dans le journal (`ERROR` sur l'erreur, `INFO` sur la fin,
473
+ `WARNING` à chaque tentative) et observable par tout code qui écoute le service.
474
+
475
+ Pendant ce temps, le client `redis` accumule les commandes dans sa file d'attente hors ligne. Les
476
+ `await` des stores **patientent** au lieu d'échouer immédiatement. Si la reconnexion réussit, elles
477
+ partent ; si la stratégie abandonne, elles sont rejetées.
478
+
479
+ `Connection.connected` repasse à `false` — mais **`Connection.client` reste affecté**. C'est le point
480
+ suivant.
481
+
482
+ ### Moment 3 — le garde `if (!client)` et ce qu'il ne couvre pas
483
+
484
+ Tous les stores commencent par le même geste : demander le client, et se replier s'il vaut `null`. Ce
485
+ garde ne se déclenche que dans deux situations exactes :
486
+
487
+ - **avant** l'initialisation du service — la carte des connexions vaut encore `null` ;
488
+ - **après** `RedisService.closeConnections()` (`redis.ts:218`), qui remet la carte à `null`.
489
+
490
+ Il ne se déclenche **pas** après un `connect()` raté. Puisque la connexion est inscrite dans
491
+ `#connections` avant d'être ouverte (`redis.ts:114`) et que `Connection.create()` affecte son client
492
+ avant de le connecter (`Connection.ts:86`), `getClient("main")` rend alors un client **non nul et
493
+ fermé**. La commande part donc, et la bibliothèque la rejette :
494
+
495
+ ```
496
+ ClientClosedError: The client is closed
497
+ ```
498
+
499
+ > [!CAUTION]
500
+ > Le repli documenté par les stores (« la connexion n'est pas ou plus ouverte → no-op ») décrit le
501
+ > comportement du démarrage et de l'arrêt, **pas celui d'un incident**. Un Redis injoignable au
502
+ > démarrage laisse une connexion fermée dans la carte : les stores ne se replient pas, ils propagent
503
+ > l'erreur du client. Tester votre application « Redis éteint » consiste donc à l'éteindre **après**
504
+ > le démarrage _et_ à la démarrer sans lui — les deux chemins ne sont pas les mêmes.
505
+
506
+ ### Moment 4 — l'arrêt
507
+
508
+ Le service s'abonne une fois pour toutes à la fin de vie du kernel dans son constructeur
509
+ (`redis.ts:218`). `closeConnections()` (`redis.ts:218`) ferme chaque connexion, avale et journalise les
510
+ échecs individuels, puis libère la carte. `Connection.close()` (`Connection.ts:146`) appelle la
511
+ fermeture gracieuse du client — qui draine les commandes en vol — puis retire **explicitement** les
512
+ cinq écouteurs via `Connection.#removeListeners()`, dans un bloc `finally` (`Connection.ts:122`).
513
+ L'ordre compte : les écouteurs sont retirés même si la fermeture échoue.
514
+
515
+ ### Synthèse — est-ce annoncé ?
516
+
517
+ <!-- prettier-ignore -->
518
+ | Situation | Ce que fait le code | Annoncé ? |
519
+ | --- | --- | --- |
520
+ | Connexion en échec au démarrage | journalisée en `ERROR`, les autres connexions sont tentées | ✅ journal |
521
+ | Démarrage du module en échec | non critique → agrégé au rapport, « démarrage DÉGRADÉ » | ✅ superviseur |
522
+ | Perte de connexion en cours de vie | `ERROR` / `WARNING` / `INFO` + événements réémis | ✅ journal + événements |
523
+ | Commande pendant la reconnexion | file d'attente hors ligne, puis envoi ou rejet | ✅ l'appelant reçoit le rejet |
524
+ | Commande sur une connexion jamais ouverte | `ClientClosedError` propagé jusqu'à l'appelant | ✅ bruyant (mais pas le repli annoncé) |
525
+ | Écriture de session, client `null` | **no-op muet** — la session n'est pas persistée, rien n'est journalisé | ❌ **silencieux** |
526
+ | Écriture de jeton / passkey, client `null` | **no-op muet** | ❌ **silencieux** |
527
+ | Backplane : module ou connexions absents | `WARNING` nommant la cause, hub laissé en local | ✅ modèle du genre |
528
+ | Idempotence : `redis` demandé, module absent | échec franc au démarrage | ✅ fail-loud |
529
+
530
+ Les deux lignes rouges sont un **écart réel au principe** du framework : `RedisSessionStorage.write()`
531
+ (`SessionStorage.ts:123`) rend la charge utile sans la persister et sans un mot. Sur la fenêtre
532
+ étroite qu'il couvre — avant l'ouverture, après la fermeture — l'impact est faible ; le principe, lui,
533
+ voudrait une trace. À l'inverse, `RedisSessionStorage.destroy()` (`SessionStorage.ts:143`) rend `true`
534
+ sans connexion **délibérément** : l'appelant est une déconnexion, et lui répondre « échec » laisserait
535
+ l'utilisateur croire qu'il est resté connecté.
536
+
537
+ ## L'énumération d'administration — ce que la pagination sait et ne sait pas
538
+
539
+ Trois stores savent énumérer pour un écran d'administration : les sessions
540
+ (`SessionStorage.ts:258`), les jetons (`RedisTokenStore.ts:351`) et les passkeys
541
+ (`RedisWebAuthnCredentialStore.ts:272`). Tous fonctionnent **en mode curseur**, et tous assument la
542
+ même capacité réduite.
543
+
544
+ ### Ce que le mode curseur rend — et ce qu'il ignore
545
+
546
+ | Attente du contrat | État réel sur Redis |
547
+ | -------------------- | ----------------------------------------------------------------------------------- |
548
+ | `limit` respectée | ✅ garantie par le curseur composite (voir plus bas) |
549
+ | `cursor` / `hasNext` | ✅ le client boucle tant que `hasNext`, en repassant `nextCursor` |
550
+ | `offset` | ❌ **jamais lu** — un client qui en envoie un est ignoré sans avertissement |
551
+ | `total` | ❌ jamais rendu — et `countSessions` / `countTokens` / `countCredentials` = `-1` |
552
+ | tri / ordre stable | ❌ aucun — `SCAN` ne garantit aucun ordre, et il n'y a pas d'index secondaire |
553
+ | page pleine | ❌ une page peut contenir moins d'éléments que `limit` (le filtre porte sur le lot) |
554
+
555
+ Le `-1` est un choix, pas un oubli : compter exactement exigerait un `SCAN` complet du keyspace. La
556
+ valeur signifie « inconnu », et l'appelant doit l'afficher comme tel plutôt que l'inventer.
557
+
558
+ Un mot sur ce que `SCAN` garantit vraiment : une clé présente du début à la fin du parcours est rendue
559
+ **au moins** une fois — ce qui autorise les doublons, et laisse indéterminé le sort des clés créées ou
560
+ détruites pendant l'itération. L'invariant « toutes les pages, sans trou ni doublon » ne tient donc
561
+ que sur un parc figé.
562
+
563
+ ### Le curseur composite, et pourquoi il existe
564
+
565
+ `COUNT` n'est pas un plafond. C'est un indice d'effort : sur un petit keyspace encodé en listpack,
566
+ Redis rend **toutes** les clés d'un coup, quel que soit le `COUNT` demandé. Une page nue déborderait
567
+ alors la `limit` et violerait le contrat.
568
+
569
+ D'où un curseur de la forme `"<déjà consommé>:<curseur Redis>"`, encodé par `encodeCursor()`
570
+ (`SessionStorage.ts:33`). Quand un lot contient plus d'éléments que la page, le store n'en rend que
571
+ `limit`, mémorise combien de clés du lot ont été consommées, et la page suivante **rejoue le même
572
+ `SCAN`** pour reprendre à la bonne position. Le coût est un re-parcours du lot courant, payé
573
+ uniquement sur un chemin d'administration. Les trois stores partagent ce mécanisme, à l'identique.
574
+
575
+ > [!IMPORTANT]
576
+ > **Ce mécanisme n'est pas exercé sans serveur Redis réel.** Le double utilisé par défaut,
577
+ > `FakePaginatingRedis` (`session-pagination.test.ts:39`), découpe ses lots à exactement `COUNT`
578
+ > clés — il ne déborde jamais, donc la branche de reprise n'est jamais atteinte. Or c'est un vrai
579
+ > serveur qui a révélé le débordement. Sans `NF_REDIS_TEST_URL`, les bancs de pagination passent au vert
580
+ > **sans avoir testé la seule chose que ce code résout**.
581
+
582
+ ### Une asymétrie sur les curseurs hostiles
583
+
584
+ Le curseur arrive de l'extérieur (chaîne de requête d'un écran d'administration, client qui rejoue une
585
+ page) : il n'est pas digne de confiance. Un curseur `SCAN` valide est toujours une suite de chiffres.
586
+
587
+ Le store de session s'en protège : `scanOrZero()` (`scanCursor.ts:68`) impose le format et retombe
588
+ sur `"0"` sinon — repartir du début est faux au pire d'une page, transmettre une valeur arbitraire
589
+ échoue à coup sûr. Les stores de jetons (`RedisTokenStore.ts:35`) et de passkeys
590
+ (`RedisWebAuthnCredentialStore.ts:31`) ne font **pas** cette validation : ils transmettent le curseur
591
+ tel quel, et Redis rejette la commande. Un paramètre malformé y transforme une simple consultation en
592
+ erreur.
593
+
594
+ ### Les vidages complets
595
+
596
+ À côté de la pagination, deux méthodes déversent tout. `RedisSessionStorage.listAll()`
597
+ (`SessionStorage.ts:198`) est **plafonnée** à un maximum de clés parcourues et journalise un
598
+ `WARNING` quand elle tronque — listing partiel signalé, jamais silencieux.
599
+ `RedisTokenStore.listAll()` (`RedisTokenStore.ts:319`), en revanche, boucle jusqu'à la fin du
600
+ keyspace sans plafond : à grande échelle, préférez la pagination ou le système de référence SQL pour
601
+ la gouvernance.
602
+
603
+ Redaction : la page de sessions vide explicitement les sacs de données métier avant de sortir
604
+ (`SessionStorage.ts:296`) — un enregistrement d'administration ne transporte jamais le contenu
605
+ applicatif d'une session.
606
+
607
+ ## ⚡ Performance & mémoire
608
+
609
+ Le module suit la règle de coût du framework : ne rien allouer « au cas où », ne jamais laisser un
610
+ écouteur derrière soi.
611
+
612
+ - **Carte de connexions paresseuse** : `null` jusqu'à la première ouverture (`redis.ts:33`), `null` à
613
+ nouveau après fermeture. Un objet `Object.create(null)` est utilisé plutôt qu'une `Map` — quelques
614
+ entrées, accès par nom, c'est le moins cher.
615
+ - **Écouteurs retirés explicitement** : `Connection.#removeListeners()` (`Connection.ts:122`) détache
616
+ les cinq écouteurs et relâche les références. Sans ce geste, recréer une connexion accumulerait des
617
+ fermetures à chaque cycle.
618
+ - **Trames de maintenance coupées** (`buildClientOptions.ts:58`) : zéro écouteur et zéro trame
619
+ superflus sur un Redis OSS.
620
+ - **Renouvellement de session en O(1)** : `EXPIRE` seul, sans réécrire la valeur
621
+ (`redis/nodefony/src/SessionStorage.ts:161`). Sur une application authentifiée, c'est le geste le plus fréquent de tout
622
+ le store.
623
+ - **Aucun balayage périodique** : le TTL natif remplace le ramasse-miettes applicatif que les backends
624
+ SQL doivent programmer.
625
+ - **Coût du temps réel** : une publication cross-pod alloue une enveloppe et une sérialisation
626
+ (`RedisBackplane.ts:197`) — sur le chemin de diffusion, jamais sur le chemin chaud HTTP. En
627
+ mono-process, le backplane n'est même pas instancié.
628
+ - **Les chemins coûteux sont froids** : `SCAN` est en O(keyspace). Il n'apparaît que dans les
629
+ énumérations d'administration, jamais dans une lecture de session ou une vérification de jeton.
630
+
631
+ Trois connexions signifient trois sockets et trois clients par process. En multi-process, multipliez :
632
+ c'est la contrepartie assumée de la séparation imposée par le protocole.
633
+
634
+ ## 📡 Observabilité — Studio
635
+
636
+ - **Écran Stores** (`/nodefony/stores`) : pour chaque brique, le store réellement retenu au démarrage
637
+ **et la raison**. La résolution est enregistrée par `SessionsService.initializeStorage()`
638
+ (`sessions-service.ts:231`), qui journalise aussi la décision au format « `auto` → `redis` (infra
639
+ cache) ». Le choix automatique lui-même vient de `resolveAutoStore()` (`infra.ts:241`) : Redis n'est
640
+ proposé que pour les natures non durables.
641
+ - **Écran Sessions** : l'énumération y passe par `listPage` en mode curseur — d'où l'absence de
642
+ compteur total et la navigation « page suivante » seule. C'est la capacité réduite décrite plus
643
+ haut, rendue visible.
644
+ - **Carte du module** (`/nodefony/modules/redis`) : documentation, symboles, tests, couverture, et la
645
+ configuration validée. Le formulaire est dérivé du JSON Schema publié par `Redis.configSchema()`
646
+ (`index.ts:43`), jamais écrit à la main.
647
+
648
+ Le module **n'expose pas** de plan de données propre (`/nodefony/redis/api/*`) : il n'a ni état
649
+ métier ni introspection spécifique. Ce qui compte de lui — quelles connexions, quel store gagne — est
650
+ surfacé par les écrans transverses ci-dessus.
651
+
652
+ ## ⚠️ Pièges (symptôme → cause → correction)
653
+
654
+ | Symptôme | Cause (dans le code) | Correction |
655
+ | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
656
+ | `ClientClosedError` alors que le store « dégrade en douceur » | Connexion posée dans `#connections` avant ouverture (`redis.ts:75`) → client non nul mais fermé | Traiter Redis comme faillible côté appelant ; surveiller le journal de démarrage |
657
+ | Le démarrage pend sans Redis | Tentatives illimitées : `connect()` ne rend pas la main | Fixer un maximum fini ; hors production c'est déjà fait (`defineModuleConfig.ts:65`) |
658
+ | Deux applications se renvoient leurs messages temps réel | Le pub/sub ignore le numéro de base — cloisonnement inexistant | Poser un namespace de canal explicite (`RedisBackplane.ts:31`) |
659
+ | Les mêmes messages sont diffusés deux fois localement | Anti-echo court-circuité (identifiant d'origine partagé) | Un identifiant d'origine distinct par pod (`RedisBackplane.ts:212`) |
660
+ | Un jeton expiré « revient » et n'expire plus | `HSET` recrée une clé absente, sans TTL | Le test d'existence préalable (`RedisTokenStore.ts:254`) — ne pas le retirer |
661
+ | `?cursor=…` fait échouer un listing de jetons | Curseur transmis sans validation (`RedisTokenStore.ts:35`) | Ne pas fabriquer de curseur à la main ; rejouer `nextCursor` tel quel |
662
+ | L'écran d'administration n'affiche aucun total | `countSessions` / `countTokens` rendent `-1` (comptage O(N) refusé) | Afficher « inconnu » ; ne jamais inventer un total |
663
+ | Un `offset` envoyé n'a aucun effet | Le mode curseur ne lit que `cursor` (`SessionStorage.ts:258`) | Paginer par curseur, pas par décalage |
664
+ | Des passkeys disparaissent | Politique d'éviction Redis (`allkeys-lru`) sur des clés **sans** TTL | `noeviction` + persistance sur l'instance qui porte les passkeys |
665
+ | Une session survit à son âge maximal côté Redis | Le TTL glissant n'exprime pas l'absolu (`SessionStorage.ts:168`) | Comportement voulu — l'âge est refusé à la lecture, pas dans le stockage |
666
+ | Une surcharge de connexion écrase l'hôte global | Un schéma partiel qui réapplique ses défauts clobberait la valeur globale | Ne poser que les champs voulus dans la surcharge — voir [Configuration](./configuration.md) |
667
+
668
+ ## 🧪 Tests & couverture
669
+
670
+ Les compteurs sont régénérés depuis vitest et vivent dans la carte de l'aperçu — jamais figés dans
671
+ cette prose. Ce qui doit être dit ici, c'est **ce qui est prouvé, et par quoi**.
672
+
673
+ | Famille | Fichiers | Ce qui est réellement exercé |
674
+ | ------------------ | ---------------------------------------------------------- | ------------------------------------------------------------------------------------ |
675
+ | Unitaire | `tests/unit/config.test.ts` | Schéma, défauts, couches d'environnement, assemblage des options du client |
676
+ | Intégration | `tests/integration/connection.test.ts` | Trois connexions réelles, `set`/`get`, pub/sub, fermeture idempotente, module inerte |
677
+ | Contrat | `session-store.test.ts`, `*-pagination.test.ts` | Les invariants partagés par tous les backends, déroulés sur Redis |
678
+ | Robustesse | `session-resilience.test.ts` | Client absent (chaque verbe), valeur corrompue, curseur hostile |
679
+ | Stores de sécurité | `token-store.test.ts`, `webauthn-credential-store.test.ts` | Cycle de vie des jetons et des authentifiants, TTL, index secondaires |
680
+
681
+ **Ce qui manque, et qu'il faut savoir :**
682
+
683
+ - **Aucun test n'exerce la perte de connexion en cours de vie.** Le banc de robustesse simule un
684
+ client `null` — un état que le service n'atteint qu'avant l'initialisation ou après la fermeture. Le
685
+ chemin réellement emprunté lors d'un incident (client fermé, non nul) n'est couvert nulle part.
686
+ - **La branche de reprise du curseur composite n'est atteinte qu'avec un serveur réel** (voir plus
687
+ haut) : le double ne déborde jamais.
688
+ - **Pas de banc de charge ni de test de mémoire dédiés** dans ce module — voir le skill
689
+ `nodefony-load-test` pour dimensionner, et `nodefony-check-memory-health` pour la mémoire du
690
+ pipeline.
691
+ - **Pas de test d'attaque** (`*.attack.test.ts`) : les curseurs hostiles sont couverts côté session
692
+ uniquement, et par le banc de robustesse.
693
+ - Le cross-pod du backplane est prouvé **ailleurs** (bancs de `@nodefony/realtime`), pas ici.
694
+
695
+ > [!IMPORTANT]
696
+ > **Une suite verte ne prouve rien sans serveur Redis.** Les bancs d'intégration se **skippent**
697
+ > quand l'infra manque, et un skip compte comme un succès : on peut lire « tout est vert » sur une
698
+ > suite qui n'a rien exercé. La gate du module est déclarée une seule fois — `REDIS_GATE` dans
699
+ > `vitest.gates.ts:329` — et la fin de run nomme la cible non exercée avec la commande exacte pour la
700
+ > satisfaire. **Les variables et la commande docker se lisent là, pas ici** : les recopier dans cette
701
+ > page les condamnerait à diverger.
702
+
703
+ Couverture : `npm run coverage` dans `@nodefony/redis`.
704
+
705
+ ## 🔗 Pour aller plus loin
706
+
707
+ - ⬆️ **Retour au hub** : [@nodefony/redis — vue d'ensemble](index.md) · [Toute la documentation](../../../../../docs/index.md)
708
+ - 🧭 **Page sœur** : [Configuration](./configuration.md) — schéma, environnement, situations concrètes
709
+ - 🧩 **Les briques branchées dessus** : [sessions](../../http/docs/session.md) ·
710
+ [jetons](../../security/docs/tokens.md) · [passkeys](../../security/docs/webauthn.md) ·
711
+ [idempotence](../../framework/docs/idempotence.md)
712
+ - 📡 **Le temps réel cross-pod** : [le backplane](../../realtime/docs/architecture.md) ·
713
+ [déployer la socket en multi-pod](../../realtime/docs/configuration.md)
714
+ - 🗄️ **Le durable, à côté** : [`@nodefony/drizzle`](../../drizzle/docs/index.md) ·
715
+ [`@nodefony/mongoose`](../../mongoose/docs/index.md) ·
716
+ [choisir un store de sessions](../../../../../docs/guides/session-storage.md)
717
+ - 🗺️ **Se situer** : [cycle de démarrage du kernel](../../../../../docs/architecture/cycle-boot-kernel.md) ·
718
+ [déclarer son infra](../../../../../docs/guides/persistence.md)