@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,773 @@
1
+ ---
2
+ title: "Configuration — déclarer l'accès Redis"
3
+ navTitle: Configuration
4
+ lang: fr
5
+ module: "@nodefony/redis"
6
+ topic: redis
7
+ section: "Persistance"
8
+ audience: [developer, devops]
9
+ tags:
10
+ [
11
+ redis,
12
+ configuration,
13
+ zod,
14
+ environnement,
15
+ connexions,
16
+ tls,
17
+ reconnexion,
18
+ infra,
19
+ deploiement,
20
+ ]
21
+ version: "doc"
22
+ status: stable
23
+ updated: 2026-07-19
24
+ source: "src/packages/@nodefony/redis/docs/configuration.md"
25
+ coverageModule: redis
26
+ ---
27
+
28
+ # Configuration de @nodefony/redis
29
+
30
+ > Une seule question à trancher : **quelle machine Redis, et comment y entrer**. Tout le reste a un
31
+ > défaut sûr. Cette page donne la liste complète des clés avec leur valeur d'usine réelle, les quatre
32
+ > variables d'environnement et l'ordre exact dans lequel elles gagnent, puis six situations de
33
+ > déploiement — du poste de développement au service managé chiffré. Ce que le module fait _dedans_
34
+ > avec ces valeurs (cycle des connexions, reconnexion, dégradation) est décrit par la page voisine,
35
+ > [Architecture interne](./architecture.md) : ici, on décide ; là-bas, on comprend.
36
+
37
+ 📍 [Documentation](../../../../../docs/index.md) › [@nodefony/redis](index.md) › **Configuration**
38
+
39
+ ## 🧠 Le modèle mental — d'où vient chaque valeur
40
+
41
+ Trois sources alimentent une configuration Redis, et elles sont empilées dans un ordre fixe. Chaque
42
+ étage ne réécrit que ce qu'il nomme ; le reste traverse intact.
43
+
44
+ ```mermaid
45
+ flowchart TD
46
+ D["1 · Défauts du schéma<br/>config.ts — un .default() par champ"]
47
+ A["2 · Configuration de l'application<br/>use('@nodefony/redis', …) dans nodefony.config.ts"]
48
+ E["3 · Environnement<br/>NF_REDIS_URL · NF_REDIS_HOST · NF_REDIS_PORT · NF_REDIS_PASSWORD"]
49
+ P["defineRedisConfig()<br/>parse ▸ garde-fou reconnexion ▸ env ▸ gel"]
50
+ B["buildClientOptions(config, connexion)<br/>url ▸ socket de la connexion ▸ socket global"]
51
+ C1["client main"]
52
+ C2["client publish"]
53
+ C3["client subscribe"]
54
+
55
+ D --> P
56
+ A --> P
57
+ E --> P
58
+ P --> B
59
+ B --> C1
60
+ B --> C2
61
+ B --> C3
62
+ ```
63
+
64
+ Deux résolutions distinctes, souvent confondues :
65
+
66
+ 1. **La configuration du module** est résolue **une fois**, au démarrage, par `defineRedisConfig()`
67
+ (`defineModuleConfig.ts:98`). Le résultat est **gelé** — plus personne ne le modifie ensuite.
68
+ 2. **Les options d'un client** sont assemblées **par connexion**, au moment de l'ouverture, par
69
+ `buildClientOptions()` (`buildClientOptions.ts:45`). C'est là que `url` écrase l'hôte, et que la
70
+ surcharge d'une connexion se pose par-dessus le socket global.
71
+
72
+ > [!TIP]
73
+ > Quand une valeur ne « prend » pas, la question utile est donc : est-elle perdue à l'étage 1
74
+ > (fusion / validation) ou à l'étage 2 (assemblage du client) ? La section
75
+ > [Situations de déploiement](#situations-de-déploiement) et la table des pièges, en fin de page,
76
+ > sont rangées selon cette coupure.
77
+
78
+ ## 📖 Lexique
79
+
80
+ | Terme | Sens |
81
+ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
82
+ | Schéma Zod | Description exécutable d'une configuration : type, contrainte, valeur par défaut et texte d'aide, dans un seul objet qui sait valider. |
83
+ | Défaut d'usine | La valeur qu'un champ prend quand personne ne le nomme. Ici, elle est toujours écrite dans le schéma — jamais recopiée ailleurs. |
84
+ | Fusion profonde | Assemblage récursif de deux objets : les clés nommées écrasent, les autres sont conservées. C'est ainsi qu'une surcharge reste partielle. |
85
+ | Gel (`freeze`) | Après validation, l'objet de configuration est rendu immuable : aucun code d'exécution ne peut le modifier en douce. |
86
+ | Connexion nommée | Un client Redis identifié par un nom logique (`main`, `publish`…). Le nom sert aussi côté serveur, pour `CLIENT LIST`. |
87
+ | Infra déclarée | Modèle où l'exploitant déclare son infrastructure par des URLs (`NF_REDIS_URL`), plutôt que de configurer chaque brique une par une. |
88
+ | Store | Backend de persistance d'une brique (session, jetons…). Le vocabulaire du framework pour les **données**. |
89
+ | TLS | _Transport Layer Security_ : chiffrement du canal. Côté Redis, il se demande par le protocole `rediss://` ou par un drapeau de socket. |
90
+ | ACL | _Access Control List_ : le système d'utilisateurs de Redis 6+. Avant lui, une seule authentification globale par mot de passe (`requirepass`). |
91
+ | Back-off | Attente croissante entre deux tentatives de reconnexion — pour ne pas marteler un serveur déjà en difficulté. |
92
+ | Redis Cluster | Mode natif de Redis où les clés sont réparties sur plusieurs nœuds ; le client doit suivre les redirections de partition. |
93
+ | Sentinel | Mode de haute disponibilité de Redis : des sentinelles élisent le maître et le client leur demande où écrire. |
94
+ | JSON Schema | Description standard d'une structure de données, publiée par le module pour que Studio dérive son formulaire au lieu de le coder à la main. |
95
+
96
+ ## Qu'est-ce que configurer Redis ?
97
+
98
+ Configurer ce module, c'est répondre à trois questions, dans cet ordre d'importance :
99
+
100
+ 1. **Où est le serveur ?** Un hôte et un port, ou bien une URL complète quand l'hébergeur n'en donne
101
+ qu'une.
102
+ 2. **Comment s'y authentifier ?** Un mot de passe, éventuellement un utilisateur ACL — et jamais dans
103
+ un fichier versionné.
104
+ 3. **Combien de canaux ouvrir, et sur quelles bases ?** Trois connexions par défaut, parce que le
105
+ protocole Redis l'impose au temps réel.
106
+
107
+ Tout le reste — délais, back-off, famille IP — a une valeur d'usine raisonnable qu'on ne touche que
108
+ pour une raison précise.
109
+
110
+ Il y a une quatrième question, invisible dans le schéma mais décisive en production : **déclarer une
111
+ URL Redis dans l'environnement change aussi le comportement d'autres modules**. Une infra de cache
112
+ déclarée rend les sessions et l'idempotence éligibles à Redis sans que personne ne les nomme. C'est
113
+ un service rendu, mais il faut le savoir : voir
114
+ [Le double effet de l'URL d'infra](#le-double-effet-de-lurl-dinfra).
115
+
116
+ ## La vision Nodefony — le schéma EST la configuration
117
+
118
+ Le module ne possède pas de « fichier de valeurs par défaut » à côté d'une « documentation des
119
+ options ». Il possède **un schéma Zod commenté**, et tout en dérive :
120
+
121
+ - **Les défauts** sont les `.default(...)` du schéma. Les valeurs d'usine effectivement chargées au
122
+ démarrage sont produites par le schéma lui-même — `redisConfigSchema.parse({})` (`config.ts:248`) —
123
+ et non retapées à la main.
124
+ - **Le type TypeScript** est inféré, jamais redéclaré : `IRedisConfig` (`IRedisConfig.ts:11`) et son
125
+ pendant d'entrée `IRedisConfigInput` (`IRedisConfig.ts:17`), où tout champ portant un défaut devient
126
+ optionnel.
127
+ - **Le texte d'aide** vit dans les `.describe()` du schéma, ce qui permet à
128
+ `redisConfigJsonSchema()` (`defineModuleConfig.ts:110`) de publier un JSON Schema **documenté** que
129
+ Studio transforme en formulaire.
130
+ - **Les champs sensibles se déclarent** : `url` et `password` portent un `.meta({ secret: true })`
131
+ (`config.ts:187`), ce qui les fait masquer là où la configuration est affichée.
132
+
133
+ Le schéma reste volontairement **pur** : il ne lit jamais `process.env`. Sans cette règle, il
134
+ deviendrait non déterministe et le JSON Schema publié dépendrait de la machine qui l'a produit. La
135
+ lecture de l'environnement est donc une couche explicite, appliquée après coup par
136
+ `applyEnvOverrides()` (`defineModuleConfig.ts:23`).
137
+
138
+ Cette organisation est la convention de configuration du framework, tenue à deux fichiers et deux
139
+ seulement : `config.ts` porte **le quoi** (schéma, contraintes, défauts), `defineModuleConfig.ts`
140
+ porte **le comment** (valider, superposer l'environnement, geler, publier le JSON Schema). Un
141
+ troisième fichier de configuration, dans un module Nodefony, est un signal d'alarme.
142
+
143
+ > [!NOTE]
144
+ > La configuration du module est **immuable après le démarrage** : `defineRedisConfig()` rend un objet
145
+ > gelé (`defineModuleConfig.ts:103`). Changer de serveur Redis suppose donc un redémarrage — aucune
146
+ > clé n'est modifiable à chaud.
147
+
148
+ ## 🚀 Démarrage rapide
149
+
150
+ Vu depuis une application créée par `nodefony create app`. Trois gestes : déclarer, authentifier,
151
+ vérifier.
152
+
153
+ ### 1. Déclarer le module
154
+
155
+ ```ts
156
+ // nodefony.config.ts — l'orchestrateur de l'application
157
+ export default defineConfig(() => ({
158
+ modules: [
159
+ // Redis d'abord : il enregistre ses fabriques de stores pendant
160
+ // l'enregistrement des modules, donc avant tout consommateur.
161
+ use("@nodefony/redis", {
162
+ globalOptions: {
163
+ socket: {
164
+ host: "127.0.0.1",
165
+ port: 6379,
166
+ // 5 s pour établir le socket : au-delà, on échoue au lieu de pendre.
167
+ connectTimeout: 5_000,
168
+ },
169
+ // Aucun secret ici : le mot de passe arrive par NF_REDIS_PASSWORD.
170
+ },
171
+ connections: {
172
+ // S'AJOUTE à main / publish / subscribe (fusion profonde des défauts) —
173
+ // une base séparée pour un cache applicatif qu'on pourra vider seul.
174
+ cache: { name: "cache", database: 1 },
175
+ },
176
+ }),
177
+ "@nodefony/http",
178
+ "@nodefony/framework",
179
+ ],
180
+ }));
181
+ ```
182
+
183
+ Le mot de passe, lui, ne descend jamais dans un fichier versionné :
184
+
185
+ ```bash
186
+ export NF_REDIS_PASSWORD=nodefony-dev
187
+ ```
188
+
189
+ ### 2. La variante sans configuration — l'infra déclarée
190
+
191
+ Si l'hébergeur ne fournit qu'une URL, il n'y a **rien** à écrire dans `nodefony.config.ts` :
192
+
193
+ ```ts
194
+ // nodefony.config.ts — le module suffit à lui-même, la cible vient de l'environnement
195
+ export default defineConfig(() => ({
196
+ modules: ["@nodefony/redis", "@nodefony/http", "@nodefony/framework"],
197
+ }));
198
+ ```
199
+
200
+ ```bash
201
+ # Hôte, port, base, utilisateur et mot de passe : tout est dans l'URL.
202
+ export NF_REDIS_URL=redis://:motdepasse@redis.interne:6379
203
+ ```
204
+
205
+ Cette seconde forme fait **deux** choses, pas une : elle vise le serveur, **et** elle déclare une
206
+ infra de cache pour tout le framework. C'est ce qui bascule automatiquement les sessions et
207
+ l'idempotence sur Redis — détaillé plus bas.
208
+
209
+ ### 3. Vérifier la cible réellement retenue
210
+
211
+ Après trois étages de superposition, la seule vérité est ce qui a été passé au client. Ce contrôleur
212
+ la rend lisible :
213
+
214
+ ```ts
215
+ // nodefony/controllers/RedisTargetController.ts — complet, compile tel quel
216
+ import { Controller, controller, Get } from "@nodefony/framework";
217
+ import type { RedisService } from "@nodefony/redis";
218
+
219
+ @controller("/diagnostic/redis")
220
+ class RedisTargetController extends Controller {
221
+ @Get("/cible")
222
+ cible() {
223
+ // Le service se résout par son NOM dans le conteneur — jamais par import.
224
+ const redis = this.get<RedisService>("redis");
225
+ const main = redis?.getConnection("main");
226
+ // `options` = ce qui a RÉELLEMENT été remis au client pour cette connexion,
227
+ // après défauts, configuration applicative, environnement et fusion.
228
+ const socket = main?.options.socket as
229
+ { host?: string; port?: number; tls?: boolean } | undefined;
230
+
231
+ return this.renderJson({
232
+ connexions: Object.keys(redis?.connections ?? {}),
233
+ // On n'expose jamais l'URL : elle porte le mot de passe.
234
+ viaUrl: Boolean(main?.options.url),
235
+ hote: socket?.host ?? null,
236
+ port: socket?.port ?? null,
237
+ tls: socket?.tls === true,
238
+ base: main?.options.database ?? null,
239
+ ouverte: main?.connected ?? false,
240
+ });
241
+ }
242
+ }
243
+
244
+ export default RedisTargetController;
245
+ ```
246
+
247
+ ### 4. Ce qu'on observe
248
+
249
+ Au démarrage, chaque connexion annonce sa cible — le point d'entrée est journalisé avec les
250
+ identifiants masqués, par `Connection.#endpoint()` (`Connection.ts:70`) :
251
+
252
+ ```
253
+ REDIS CONNECTION main CONNECT 127.0.0.1:6379
254
+ REDIS CONNECTION publish CONNECT 127.0.0.1:6379
255
+ REDIS CONNECTION subscribe CONNECT 127.0.0.1:6379
256
+ REDIS CONNECTION cache CONNECT 127.0.0.1:6379
257
+ ```
258
+
259
+ Puis, à la demande :
260
+
261
+ ```bash
262
+ curl -s http://127.0.0.1:5151/diagnostic/redis/cible
263
+ # {"connexions":["main","publish","subscribe","cache"],"viaUrl":false,
264
+ # "hote":"127.0.0.1","port":6379,"tls":false,"base":0,"ouverte":true}
265
+ ```
266
+
267
+ Quatre connexions, pas trois : la clé `cache` s'est **ajoutée** aux défauts au lieu de les remplacer.
268
+ C'est la fusion profonde du manifeste, et c'est le comportement voulu.
269
+
270
+ ## ⚙️ Toutes les clés du schéma
271
+
272
+ Les défauts ci-dessous sont ceux du schéma, lus dans `redisConfigSchema` (`config.ts:200`). Une seule
273
+ valeur effective diffère du schéma au démarrage — `maxRetries`, traitée dans sa propre section.
274
+
275
+ ### Racine
276
+
277
+ <!-- prettier-ignore -->
278
+ | Clé | Type | Défaut | Effet |
279
+ | --- | --- | --- | --- |
280
+ | `enabled` | booléen | `true` | `false` = module chargé mais inerte : aucune connexion ouverte, aucun socket. |
281
+ | `url` | chaîne (secret) | _absent_ | URL complète `redis[s]://[[user][:pass]@]host[:port][/db]`. Prend le pas sur `globalOptions`. |
282
+ | `globalOptions` | objet | défauts de `globalOptionsSchema` | Options communes fusionnées dans **chaque** connexion. |
283
+ | `connections` | dictionnaire nom → objet | `main`, `publish`, `subscribe` | Les connexions à ouvrir au démarrage. |
284
+ | `keyNamespace` | chaîne | nom de l'application | Cloison des **clés** par application sur un Redis mutualisé (cf ci-dessous). |
285
+
286
+ Le sous-objet `connections` est un dictionnaire libre : la clé est le nom logique, la valeur décrit la
287
+ connexion. Les trois entrées par défaut sont matérialisées dans `redisConfigSchema` (`config.ts:200`).
288
+
289
+ #### `keyNamespace` — deux applications sur un même Redis
290
+
291
+ Un serveur Redis se mutualise volontiers. La `database` donne l'illusion d'une séparation, mais elle
292
+ vaut `0` par défaut et n'isole rien de plus : deux applications y écrivent alors dans le même espace de
293
+ clés. Comme les clés portaient un nom fixe (`nf:sess:<id>`), l'écran Sessions de l'une **listait les
294
+ sessions de l'autre** — son balayage `nf:sess:*` ne pouvait pas les distinguer.
295
+
296
+ La cloison insère le nom de l'application dans le préfixe :
297
+
298
+ ```
299
+ nf:boutique:sess:<id> nf:boutique:tok:<id> nf:boutique:wac:<id>
300
+ nf:intranet:sess:<id> nf:intranet:tok:<id> nf:intranet:wac:<id>
301
+ ```
302
+
303
+ **Ce qu'elle sépare, et ce qu'elle ne sépare pas.** Elle sépare des _applications_, jamais les
304
+ instances d'une même application — c'est ce qui décide si une session survit au load-balancer :
305
+
306
+ | | |
307
+ | ---------------------------- | --------------------------------------------------------------------------------------------------- |
308
+ | 10 pods de « boutique » | **même** cloison → même espace de clés → une session ouverte via un pod est lue par tous les autres |
309
+ | « boutique » et « intranet » | cloisons **différentes** → espaces disjoints → aucune ne voit l'autre |
310
+
311
+ La cloison est dérivée de `kernel.projectName`, c'est-à-dire du nom de l'application **dans son code** :
312
+ tous ses pods calculent donc la même valeur. Le partage des sessions entre instances — la raison d'être
313
+ d'un store Redis — reste entier. Elle n'est surtout pas dérivée du nom d'hôte ou du PID : chaque pod
314
+ aurait son propre espace, et l'utilisateur serait déconnecté dès qu'une requête change de pod.
315
+
316
+ **Le cas à connaître** : deux _déploiements_ de la même application (préproduction et production)
317
+ portent le même nom, donc la même cloison. S'ils partagent un serveur Redis, posez-leur un
318
+ `keyNamespace` explicite — par la variable `NF_REDIS_KEY_NAMESPACE`, qui prend le pas sur la
319
+ configuration (une cloison distingue des environnements, elle n'a pas à être figée dans le code).
320
+
321
+ ```ts
322
+ use("@nodefony/redis", { keyNamespace: "boutique-preprod" });
323
+ ```
324
+
325
+ Une application seule sur son Redis n'a rien à cloisonner : sans cloison résolue, les préfixes
326
+ historiques (`nf:sess`, `nf:tok`, `nf:wac`) sont conservés tels quels.
327
+
328
+ ### `globalOptions`
329
+
330
+ | Clé | Type | Défaut | Effet |
331
+ | ---------- | --------------- | ------------------------- | --------------------------------------------------------------------------------------------------------- |
332
+ | `socket` | objet | défauts de `socketSchema` | Les options TCP/TLS communes. |
333
+ | `username` | chaîne | _absent_ | Utilisateur ACL (Redis 6+). Absent avec un `password` présent = authentification héritée `requirepass`. |
334
+ | `password` | chaîne (secret) | _absent_ | Mot de passe. Marqué secret dans `globalOptionsSchema` (`config.ts:187`) → masqué là où il s'afficherait. |
335
+
336
+ `username` n'a **pas** de variable d'environnement dédiée : sur un serveur à ACL, il se pose dans la
337
+ configuration de l'application (il n'est pas secret par lui-même), ou dans l'URL.
338
+
339
+ ### `globalOptions.socket`
340
+
341
+ <!-- prettier-ignore -->
342
+ | Clé | Type | Défaut | Effet |
343
+ | --- | --- | --- | --- |
344
+ | `host` | chaîne non vide | `"localhost"` | Hôte du serveur. Jamais d'hôte d'infrastructure en dur dans le framework. |
345
+ | `port` | entier `1..65535` | `6379` | Port TCP. Hors plage → la configuration est **refusée** au démarrage. |
346
+ | `family` | `0` \| `4` \| `6` | `0` | Famille IP pour la résolution DNS ; `0` laisse Node choisir. Utile quand une pile IPv6 traîne. |
347
+ | `connectTimeout` | entier > 0 (ms) | `5000` | Délai maximal d'établissement du socket. Empêche un démarrage qui pend sur un serveur muet. |
348
+ | `tls` | booléen | `false` | Chiffre le canal. Voir la limite de forme plus bas — c'est un drapeau, pas un jeu de certificats. |
349
+ | `reconnectStrategy` | objet | défauts de `reconnectStrategySchema` | La politique de reconnexion, décrite juste après. |
350
+
351
+ Ces contraintes sont portées par `socketSchema` (`config.ts:79`) : ce sont elles qui font échouer le
352
+ démarrage plutôt que de laisser passer un port fantaisiste.
353
+
354
+ ### `globalOptions.socket.reconnectStrategy`
355
+
356
+ | Clé | Type | Défaut du schéma | Effet |
357
+ | ------------ | ---------- | ---------------- | ------------------------------------------------------------------------------------------- |
358
+ | `baseMs` | entier > 0 | `100` | Pas du back-off linéaire : la n-ième tentative attend `n × baseMs`. |
359
+ | `maxMs` | entier > 0 | `10000` | Plafond de l'attente. Au-delà, les tentatives s'espacent d'un intervalle constant. |
360
+ | `maxRetries` | entier ≥ 0 | `0` | Nombre de tentatives avant abandon. `0` = illimité. **Valeur effective : voir ci-dessous.** |
361
+
362
+ Ces trois valeurs sont déclaratives ; elles sont converties en fonction par
363
+ `buildReconnectStrategy()` (`buildClientOptions.ts:13`) au moment d'assembler le client, parce qu'un
364
+ schéma Zod ne sait pas transporter une fonction.
365
+
366
+ ### `connections.<nom>`
367
+
368
+ | Clé | Type | Défaut | Effet |
369
+ | ---------- | --------------- | --------------- | --------------------------------------------------------------------------------------------------- |
370
+ | `name` | chaîne non vide | **obligatoire** | Nom logique du client. Posé aussi côté serveur (`CLIENT SETNAME`) → visible dans `CLIENT LIST`. |
371
+ | `database` | entier ≥ 0 | `0` | Base Redis sélectionnée. **N'isole que les commandes clé-valeur** — le pub/sub ignore la base. |
372
+ | `socket` | objet partiel | _absent_ | Surcharge du socket pour cette connexion seulement ; les champs omis restent ceux du socket global. |
373
+
374
+ `name` est le seul champ sans valeur d'usine dans tout le schéma (`connectionSchema` (`config.ts:143`)) :
375
+ une connexion sans nom serait invisible dans les journaux et côté serveur, on refuse donc de deviner.
376
+
377
+ ### `connections.<nom>.socket` — la surcharge
378
+
379
+ Cinq champs, tous facultatifs et **tous sans défaut** : `host`, `port`, `family`, `connectTimeout`,
380
+ `tls`. C'est une décision de conception, portée par `socketOverrideSchema` (`config.ts:133`) : un
381
+ schéma partiel qui réappliquerait ses propres défauts écraserait silencieusement le socket global —
382
+ poser un `host` particulier ramènerait le port à `6379` sans le dire.
383
+
384
+ ```ts ignore
385
+ // Une connexion d'archive sur une autre machine : SEUL l'hôte change.
386
+ connections: {
387
+ archive: { name: "archive", database: 2, socket: { host: "redis-archive.interne" } },
388
+ }
389
+ // port, family, connectTimeout, tls, reconnexion → hérités du socket global.
390
+ ```
391
+
392
+ ## Variables d'environnement et ordre de précédence
393
+
394
+ ### Les quatre variables lues
395
+
396
+ Toutes sont appliquées **après** la validation, par `applyEnvOverrides()`
397
+ (`defineModuleConfig.ts:23`).
398
+
399
+ | Variable | Ce qu'elle vise | Comportement |
400
+ | ------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------- |
401
+ | `NF_REDIS_URL` (ou `REDIS_URL`) | `url` | Résolue par `resolveInfra()` (`infra.ts:134`) ; `NF_REDIS_URL` l'emporte sur l'alias de plateforme. |
402
+ | `NF_REDIS_HOST` | `globalOptions.socket.host` | Posée telle quelle, sans validation supplémentaire. |
403
+ | `NF_REDIS_PORT` | `globalOptions.socket.port` | **Ignorée en silence** si ce n'est pas un entier de `1` à `65535`. |
404
+ | `NF_REDIS_PASSWORD` | `globalOptions.password` | Le seul chemin recommandé pour le secret : jamais dans un fichier versionné. |
405
+
406
+ `REDIS_URL` est accepté comme **alias de plateforme** parce que c'est le nom que posent la plupart des
407
+ hébergeurs. Quand les deux existent, la variable préfixée gagne — le préfixe `NF_` sert précisément à
408
+ reprendre la main sur une variable imposée par l'environnement d'hébergement.
409
+
410
+ ### L'ordre, prouvé par le code
411
+
412
+ `defineRedisConfig()` (`defineModuleConfig.ts:98`) exécute quatre gestes, toujours dans le même
413
+ ordre :
414
+
415
+ 1. `redisConfigSchema.parse(entrée)` — les défauts comblent ce que l'application n'a pas dit, et la
416
+ validation refuse ce qui est hors bornes.
417
+ 2. `applyResilienceDefaults()` (`defineModuleConfig.ts:65`) — le garde-fou de reconnexion, qui
418
+ inspecte l'entrée **brute** pour savoir si l'application s'est prononcée.
419
+ 3. `applyEnvOverrides()` (`defineModuleConfig.ts:23`) — l'environnement écrase ce qu'il nomme.
420
+ 4. `Object.freeze` — plus rien ne bouge.
421
+
422
+ D'où la règle, dans cet ordre croissant d'autorité : **défauts du schéma → configuration de
423
+ l'application → environnement**. Le comportement est verrouillé par les tests unitaires
424
+ (`config.test.ts:56` pour l'hôte, le port et le mot de passe ; `config.test.ts:72` pour le port
425
+ invalide ignoré).
426
+
427
+ > [!IMPORTANT]
428
+ > L'environnement gagne **même contre une valeur explicite de l'application**. Une `url` écrite dans
429
+ > `use("@nodefony/redis", { url: … })` est remplacée dès qu'une URL d'infra est présente dans
430
+ > l'environnement. C'est voulu — l'exploitant doit pouvoir déplacer une application sans la
431
+ > recompiler — mais c'est aussi la première cause de « ma configuration est ignorée ».
432
+
433
+ Un cinquième geste vient plus tard, à l'ouverture de chaque connexion : la précédence **`url` ▸ socket
434
+ de la connexion ▸ socket global**, tranchée par `buildClientOptions()` (`buildClientOptions.ts:45`)
435
+ et prouvée par `config.test.ts:128`.
436
+
437
+ ### Le double effet de l'URL d'infra
438
+
439
+ `NF_REDIS_URL` n'est pas seulement la cible de ce module : c'est la déclaration d'une **infra de
440
+ cache** pour le framework entier. `resolveAutoStore()` (`infra.ts:241`) s'en sert pour les briques
441
+ dont le store vaut `auto` :
442
+
443
+ | Brique | Nature de la donnée | Avec une infra de cache déclarée |
444
+ | ------------------------- | ------------------- | -------------------------------- |
445
+ | Sessions | `session` | ✅ bascule sur Redis toute seule |
446
+ | Idempotence | `ephemeral` | ✅ bascule sur Redis toute seule |
447
+ | Jetons, passkeys | `durable` | ❌ jamais — il faut le demander |
448
+ | Identité, audit, webhooks | `durable` | ❌ jamais — pas de version Redis |
449
+
450
+ Le raisonnement du framework : ce qui est périssable va au magasin périssable, ce qui est durable
451
+ reste dans la base de vérité. Un choix **explicite** l'emporte toujours sur cette résolution
452
+ automatique — `use("@nodefony/http", { session: { store: "redis" } })` se comporte pareil quelle que
453
+ soit l'infra déclarée, ce qui est exactement ce qu'on veut quand développement et production doivent
454
+ se ressembler.
455
+
456
+ Le store retenu et **sa raison** sont journalisés au démarrage et affichés dans Studio : on ne devine
457
+ jamais où les sessions ont atterri. Le comparatif transverse vit dans
458
+ [choisir un store de sessions](../../../../../docs/guides/session-storage.md).
459
+
460
+ ### Quand une URL est posée, ce qui devient sans effet
461
+
462
+ Dès que `url` est renseignée — par l'application ou par l'environnement — `buildClientOptions()`
463
+ (`buildClientOptions.ts:68`) **ne pose plus** `socket.host` ni `socket.port` : ils entreraient en
464
+ conflit avec ceux de l'URL. Trois conséquences à connaître :
465
+
466
+ <!-- prettier-ignore -->
467
+ | Réglage | Avec une `url` présente |
468
+ | --- | --- |
469
+ | `socket.host` / `socket.port`, `NF_REDIS_HOST` / `NF_REDIS_PORT` | **sans effet** — l'adresse vient de l'URL |
470
+ | `socket.tls` | **sans effet** — c'est le protocole (`redis://` ou `rediss://`) qui décide |
471
+ | `connections.<nom>.database` | **écrasé** si l'URL porte un chemin (`…:6379/2`) — toutes les connexions sur cette base |
472
+ | `NF_REDIS_PASSWORD` | conservé **seulement** si l'URL ne porte pas de mot de passe |
473
+ | `reconnectStrategy` | conservé dans tous les cas — c'est la seule option de socket transmise avec l'URL |
474
+
475
+ Les trois dernières lignes viennent de la bibliothèque `redis` elle-même : à la construction du
476
+ client, les valeurs extraites de l'URL sont recopiées **par-dessus** les options fournies. Une URL
477
+ n'est donc pas un raccourci pour « hôte et port », c'est une **source qui prend la main**.
478
+
479
+ > [!WARNING]
480
+ > Le cas coûteux est celui de la base : `NF_REDIS_URL=redis://…/2` annule le cloisonnement `database`
481
+ > de **toutes** les connexions nommées, sans un mot. Sur une instance mutualisée, préférez déclarer
482
+ > l'URL sans chemin et laisser chaque connexion choisir sa base — ou accepter une base unique, en le
483
+ > sachant.
484
+
485
+ ## Reconnexion — le défaut effectif n'est pas celui du schéma
486
+
487
+ C'est la seule clé du module dont la valeur d'usine dépend de l'environnement d'exécution, et elle
488
+ mérite qu'on s'y arrête.
489
+
490
+ **Le schéma dit `0` — illimité.** C'est le réglage juste **en production** : un orchestrateur relèvera
491
+ le serveur Redis, et le client doit patienter aussi longtemps qu'il faut plutôt que d'abandonner
492
+ définitivement.
493
+
494
+ **Hors production, ce réglage fait pendre le démarrage.** Avec des tentatives illimitées, la première
495
+ ouverture ne rend jamais la main tant que Redis ne répond pas ; la file d'attente hors ligne du client
496
+ retient les commandes, et un démarrage sans serveur se transforme en attente infinie plutôt qu'en
497
+ échec lisible. D'où `applyResilienceDefaults()` (`defineModuleConfig.ts:65`), qui borne les tentatives
498
+ à `DEV_DEFAULT_MAX_RETRIES` (`defineModuleConfig.ts:45`) — cinq — quand, et seulement quand,
499
+ l'application ne s'est pas prononcée.
500
+
501
+ | `NODE_ENV` | L'application fixe `maxRetries` ? | Valeur effective |
502
+ | ----------------------------------- | --------------------------------- | ----------------------------------- |
503
+ | `production` | non | `0` — illimité |
504
+ | `production` | oui | celle de l'application |
505
+ | autre (développement, test, absent) | non | **`5`** — abandon après cinq essais |
506
+ | autre | oui, même `0` | celle de l'application |
507
+
508
+ La distinction « fixé / non fixé » se lit sur l'**entrée brute** de l'application, avant le parcours du
509
+ schéma : une fois les défauts appliqués, un `0` d'usine serait indiscernable d'un `0` voulu. Les trois
510
+ branches sont couvertes par les tests (`config.test.ts:85`, `config.test.ts:91`, `config.test.ts:99`).
511
+
512
+ **Le calcul du délai.** `buildReconnectStrategy()` (`buildClientOptions.ts:13`) rend
513
+ `min((tentative + 1) × baseMs, maxMs)`, et une erreur — donc l'abandon — dès que le nombre de
514
+ tentatives atteint `maxRetries`, si celui-ci est fini. Avec les valeurs d'usine, hors production :
515
+
516
+ | Tentative | 1 | 2 | 3 | 4 | 5 | 6 |
517
+ | --------- | ------ | ------ | ------ | ------ | ------ | ---------------- |
518
+ | Attente | 100 ms | 200 ms | 300 ms | 400 ms | 500 ms | abandon (erreur) |
519
+
520
+ Soit environ une seconde et demie avant de conclure — assez court pour un aller-retour de développement,
521
+ assez long pour absorber un redémarrage de conteneur.
522
+
523
+ > [!CAUTION]
524
+ > Le JSON Schema publié pour Studio est produit à partir du schéma seul : il annonce donc
525
+ > `maxRetries: 0`, y compris hors production où la valeur réellement chargée est `5`. Le formulaire
526
+ > décrit le schéma, pas la superposition. Pour connaître la valeur en vigueur, lisez la configuration
527
+ > effective du service, pas le formulaire.
528
+
529
+ ## Les connexions — trois par défaut, autant qu'on veut
530
+
531
+ Le défaut ouvre **trois** clients : `main` pour les commandes clé-valeur, `publish` pour l'émission,
532
+ `subscribe` pour l'écoute. Ce n'est pas une précaution, c'est une contrainte du protocole : un client
533
+ abonné ne peut plus émettre de commandes normales. Une connexion unique rendrait le temps réel et le
534
+ stockage mutuellement exclusifs.
535
+
536
+ Ajouter une connexion se fait en nommant une nouvelle clé. La fusion du manifeste est **profonde** —
537
+ `loadModulesFromManifest()` (`Kernel.ts:1492`) fusionne la configuration de `use()` sous les défauts
538
+ déjà matérialisés du module — donc les trois connexions d'usine restent en place :
539
+
540
+ ```ts ignore
541
+ use("@nodefony/redis", {
542
+ connections: {
543
+ cache: { name: "cache", database: 1 },
544
+ archive: { name: "archive", database: 2 },
545
+ },
546
+ });
547
+ // Résultat au démarrage : main, publish, subscribe, cache, archive — cinq clients.
548
+ ```
549
+
550
+ Chaque connexion coûte un socket et un client par process ; en multi-process, multipliez. C'est la
551
+ contrepartie assumée de la séparation imposée par le protocole.
552
+
553
+ > [!NOTE]
554
+ > Le pub/sub Redis est **global au serveur** : il ignore complètement le numéro de base. Le champ
555
+ > `database` cloisonne les commandes clé-valeur, jamais les messages. Deux applications qui partagent
556
+ > une instance ont besoin d'un espace de noms de canal, pas d'une base différente — voir
557
+ > [Architecture interne](./architecture.md).
558
+
559
+ ## Situations de déploiement
560
+
561
+ Six situations couvrent l'essentiel. Le tableau pour choisir, les fiches pour la configuration exacte.
562
+
563
+ | Situation | Ce qui la caractérise | Ce qu'on écrit |
564
+ | ------------------------- | ---------------------------------------------- | --------------------------------------------- |
565
+ | Développement local | Redis dans un conteneur, sur la boucle locale | rien, ou l'hôte ; le mot de passe en variable |
566
+ | Application conteneurisée | Redis est un service voisin, joint par son nom | l'hôte = le nom du service |
567
+ | Service managé chiffré | une URL `rediss://` fournie par l'hébergeur | rien : tout est dans l'URL |
568
+ | Orchestrateur | l'URL vient d'un secret monté à l'exécution | rien : la variable est injectée |
569
+ | Intégration continue | pas de serveur Redis du tout | `enabled: false`, ou rien du tout |
570
+ | Cluster ou Sentinel | plusieurs nœuds, redirections de partition | **non pris en charge** — lire la fiche |
571
+
572
+ ### `developpement-local` — Redis dans un conteneur
573
+
574
+ Le serveur de développement du dépôt tourne avec authentification, sur la boucle locale uniquement, en
575
+ politique mémoire `noeviction`. Il n'y a **rien** à écrire dans la configuration : les défauts du
576
+ schéma visent déjà `localhost:6379`. Une seule variable est nécessaire.
577
+
578
+ ```bash
579
+ docker compose -f docker/docker-compose.yml up -d redis
580
+ export NF_REDIS_PASSWORD=nodefony-dev
581
+ ```
582
+
583
+ L'authentification est exigée **même en développement** : une instance sans mot de passe habitue à un
584
+ réglage qui n'existe nulle part ailleurs, et masque les erreurs `NOAUTH` jusqu'à la mise en production.
585
+
586
+ ### `conteneur` — Redis est un service voisin
587
+
588
+ Dans une composition de conteneurs, le serveur n'est plus sur la boucle locale : il porte le nom du
589
+ service dans le réseau. C'est le seul champ à changer.
590
+
591
+ ```ts ignore
592
+ use("@nodefony/redis", {
593
+ globalOptions: { socket: { host: "redis", port: 6379 } },
594
+ });
595
+ ```
596
+
597
+ Le mot de passe reste une variable d'environnement du conteneur applicatif. Si la composition fournit
598
+ déjà une URL complète, ne configurez rien : posez `NF_REDIS_URL` et laissez le module la suivre.
599
+
600
+ ### `manage-tls` — un service Redis managé, chiffré
601
+
602
+ Les hébergeurs ne donnent en général qu'une URL, qui porte l'hôte, le port, les identifiants et le
603
+ protocole. Le protocole `rediss://` suffit à activer le chiffrement : le drapeau `socket.tls` est
604
+ inutile, et sans effet, dès qu'une URL est présente.
605
+
606
+ ```bash
607
+ export NF_REDIS_URL=rediss://default:LE_JETON@eu1-xxxx.exemple-managed.io:6380
608
+ ```
609
+
610
+ Aucune ligne dans `nodefony.config.ts`. Le mot de passe voyage dans l'URL : traitez-la comme un
611
+ secret entier, jamais comme une adresse.
612
+
613
+ **La limite de forme à connaître** : le schéma n'expose qu'un **booléen** `tls`
614
+ (`socketSchema` (`config.ts:114`)). Autorité de certification privée, certificat client, nom de
615
+ serveur explicite — rien de tout cela n'est exprimable. Un service managé à certificat public
616
+ fonctionne ; une authentification mutuelle par certificat n'est pas couverte par la configuration du
617
+ module.
618
+
619
+ ### `orchestrateur` — l'URL vient d'un secret
620
+
621
+ En orchestration, la cible n'est pas connue à la construction de l'image : elle est injectée à
622
+ l'exécution. Le modèle d'infra déclarée est fait pour ça — l'image ne contient aucune adresse, la
623
+ variable arrive du magasin de secrets.
624
+
625
+ ```bash
626
+ # Injecté par l'orchestrateur, jamais présent dans l'image.
627
+ NF_REDIS_URL=redis://:$(cat /run/secrets/redis-password)@redis.production.svc:6379
628
+ ```
629
+
630
+ En production, laissez `maxRetries` à son défaut : les tentatives illimitées sont le bon réglage
631
+ quand un superviseur externe relève le serveur. Fixer une valeur finie ferait abandonner
632
+ définitivement un client qui aurait suffi d'attendre.
633
+
634
+ ### `integration-continue` — sans serveur Redis
635
+
636
+ Deux réponses, selon l'intention.
637
+
638
+ **Ne pas charger Redis du tout** : retirer le module du manifeste. C'est le plus propre quand aucune
639
+ brique n'en dépend.
640
+
641
+ **Le charger, inerte** : `enabled: false` (`redisConfigSchema` (`config.ts:202`)) laisse le module en
642
+ place sans ouvrir un seul socket. Utile quand le manifeste est commun à plusieurs environnements.
643
+
644
+ ```ts ignore
645
+ use("@nodefony/redis", { enabled: false });
646
+ ```
647
+
648
+ > [!WARNING]
649
+ > `enabled: false` n'annule **pas** la sélection des stores. Une brique explicitement configurée sur
650
+ > `redis` reste branchée sur un service sans connexion : les fabriques sont enregistrées, mais aucun
651
+ > client n'existe. Désactiver le module suppose donc de ne pas avoir nommé `redis` ailleurs.
652
+
653
+ ### `cluster-sentinel` — ce qui n'est pas couvert
654
+
655
+ Le module construit ses clients avec la fabrique **client simple** de la bibliothèque `redis` —
656
+ `buildClientOptions()` (`buildClientOptions.ts:45`) produit des options de client, pas de grappe. Ni
657
+ Redis Cluster (répartition par partitions, redirections `MOVED`/`ASK`), ni Sentinel (élection du
658
+ maître) ne sont exprimables dans le schéma.
659
+
660
+ Ce que cela laisse comme options :
661
+
662
+ - un service managé qui expose un **point d'entrée unique** et masque sa topologie — le cas le plus
663
+ courant, et il fonctionne tel quel ;
664
+ - un mandataire (proxy) devant la grappe, vu du module comme un serveur ordinaire ;
665
+ - une instance simple avec réplication, en acceptant sa disponibilité.
666
+
667
+ Mieux vaut le savoir en concevant l'infrastructure qu'en la déployant.
668
+
669
+ ## Quand la connexion échoue au démarrage
670
+
671
+ Deux échecs très différents partagent le même symptôme apparent — « Redis ne marche pas » — et se
672
+ règlent à des endroits opposés.
673
+
674
+ **La configuration est invalide.** `Redis.onKernelRegister()` (`index.ts:54`) valide avant tout le
675
+ reste et refuse de démarrer sur une valeur hors bornes. Le message nomme le champ fautif
676
+ (`index.ts:68`) :
677
+
678
+ ```
679
+ [@nodefony/redis] Invalid config: globalOptions.socket.port: Too big: expected number to be <=65535
680
+ ```
681
+
682
+ C'est un défaut de configuration : rien à chercher côté réseau.
683
+
684
+ **Le serveur ne répond pas.** La configuration est bonne, l'ouverture échoue. Le module est déclaré
685
+ **non critique** — `Redis.critical` (`index.ts:36`) vaut `false` — donc l'application démarre quand
686
+ même, en état dégradé annoncé. Chaque connexion est tentée indépendamment et journalisée en `ERROR`
687
+ par `RedisService.init()` (`redis.ts:123`) : une connexion en échec n'empêche pas les suivantes.
688
+
689
+ Ce que ce démarrage dégradé implique côté appelants — pourquoi le garde `if (!client)` des stores ne
690
+ suffit pas après une ouverture ratée, ce que devient une commande pendant une reconnexion — est
691
+ détaillé dans [Architecture interne](./architecture.md), section « Résilience ». C'est la lecture à
692
+ faire avant une mise en production.
693
+
694
+ ## ⚠️ Pièges
695
+
696
+ <!-- prettier-ignore -->
697
+ | Symptôme | Cause | Correction |
698
+ | --- | --- | --- |
699
+ | Une clé de configuration n'a aucun effet, aucune erreur | Clé inconnue du schéma : la validation Zod **écarte** les clés qu'elle ne connaît pas | Vérifier l'orthographe dans les tables ci-dessus ; contrôler la cible effective (§ Démarrage rapide) |
700
+ | L'hôte configuré est ignoré | Une `url` est présente — `buildClientOptions()` (`buildClientOptions.ts:68`) ne pose plus host/port | Retirer `NF_REDIS_URL`/`REDIS_URL`, ou tout mettre dans l'URL |
701
+ | `NF_REDIS_PORT` semble sans effet | Valeur non entière ou hors `1..65535` : `applyEnvOverrides()` (`defineModuleConfig.ts:32`) l'ignore | Corriger la valeur — l'ignorance est silencieuse par conception |
702
+ | Toutes les connexions atterrissent sur la même base | L'URL porte un chemin (`…/2`) qui écrase le `database` de chaque connexion | Déclarer l'URL sans chemin et laisser `database` cloisonner |
703
+ | Le démarrage pend, sans erreur, sans Redis | Tentatives illimitées : la première ouverture ne rend pas la main | Hors production c'est déjà borné (`applyResilienceDefaults()` (`defineModuleConfig.ts:65`)) ; sinon fixer une valeur finie |
704
+ | Erreur `NOAUTH` alors que le mot de passe est configuré | L'URL porte des identifiants qui recouvrent `NF_REDIS_PASSWORD` | Ne pas mélanger : l'URL **ou** hôte + mot de passe |
705
+ | Les sessions ont changé de magasin sans qu'on touche à la configuration | `NF_REDIS_URL` déclare une infra de cache → `resolveAutoStore()` (`infra.ts:241`) bascule les briques `auto` | Nommer le store explicitement pour un comportement identique partout |
706
+ | Une surcharge de connexion ramène le port à `6379` | Un schéma partiel qui réappliquerait ses défauts — d'où `socketOverrideSchema` (`config.ts:133`) sans défaut | Ne poser que les champs voulus ; les autres héritent du socket global |
707
+ | Le module démarre mais n'ouvre rien | `enabled: false` — module chargé, inerte (`RedisService.init()` (`redis.ts:123`)) | Le réactiver, ou retirer le module du manifeste |
708
+ | Le formulaire Studio annonce `maxRetries: 0` en développement | Le JSON Schema décrit le schéma, pas la superposition d'exécution | Lire la configuration effective du service |
709
+ | Une valeur changée à chaud ne prend pas | La configuration est **gelée** après le démarrage (`defineRedisConfig()` (`defineModuleConfig.ts:103`)) | Redémarrer le process |
710
+ | L'auto-complétion ne propose aucune clé dans `use()` | Le module ne s'inscrit pas au registre de types des configurations de modules | S'appuyer sur les tables de cette page ; une clé fautive ne sera pas signalée à la compilation |
711
+
712
+ ## 📡 Observabilité — Studio
713
+
714
+ - **Carte du module** (`/nodefony/modules/redis`) : la configuration validée, rendue par un formulaire
715
+ **dérivé** du JSON Schema que publie `Redis.configSchema()` (`index.ts:43`). Les champs marqués
716
+ secrets — `url`, `password` — y sont masqués par construction, pas par une liste d'exclusion tenue
717
+ à la main.
718
+ - **Écran Stores** (`/nodefony/stores`) : pour chaque brique, le store réellement retenu au démarrage
719
+ **et la raison** (« infra cache », choix explicite). C'est là qu'on vérifie l'effet d'une
720
+ `NF_REDIS_URL` sur les sessions et l'idempotence, sans relire une configuration.
721
+ - **Journal de démarrage** : une ligne par connexion, avec le point d'entrée et les identifiants
722
+ masqués.
723
+
724
+ Le module n'expose pas de plan de données propre : il n'a ni état métier ni introspection spécifique,
725
+ et ce qui compte de lui est déjà surfacé par les écrans transverses.
726
+
727
+ ## 🧪 Tests & couverture
728
+
729
+ Les compteurs sont régénérés depuis vitest et vivent dans la carte de l'aperçu — jamais figés dans
730
+ cette prose. Ce qui doit être dit ici, c'est **ce que la configuration a de prouvé**.
731
+
732
+ <!-- prettier-ignore -->
733
+ | Ce qui est vérifié | Où |
734
+ | --- | --- |
735
+ | Défauts d'usine et sous-défauts | `config.test.ts:15` (hôte, port, TLS, trois connexions) |
736
+ | Refus d'une valeur hors bornes | `config.test.ts:38` (port hors plage) |
737
+ | Superposition de l'environnement | `config.test.ts:56` et `config.test.ts:66` |
738
+ | Port d'environnement invalide ignoré | `config.test.ts:72` |
739
+ | Garde-fou de reconnexion, ses trois branches | `config.test.ts:85`, `config.test.ts:91`, `config.test.ts:99` |
740
+ | Gel de la configuration | `config.test.ts:51` |
741
+ | Assemblage des options du client | `config.test.ts:107` (fusion) et `config.test.ts:128` (précédence de l'URL) |
742
+ | Back-off et abandon | `config.test.ts:139` |
743
+
744
+ Ces bancs sont **unitaires** : ils tournent sans serveur. La configuration est donc la partie du
745
+ module dont la vérification ne dépend d'aucune infrastructure — c'est aussi pour ça que le schéma doit
746
+ rester pur.
747
+
748
+ > [!IMPORTANT]
749
+ > **Une suite verte ne prouve rien du reste sans serveur Redis.** Les bancs d'intégration se
750
+ > **skippent** quand l'infra manque, et un skip compte comme un succès : on peut lire « tout est
751
+ > vert » sur une suite qui n'a rien exercé. La gate du module est déclarée une seule fois —
752
+ > `REDIS_GATE` (`vitest.gates.ts:329`) — et la fin de run nomme la cible non exercée avec la commande
753
+ > exacte pour la satisfaire. **Les variables et la commande docker se lisent là, pas ici** : les
754
+ > recopier dans cette page les condamnerait à diverger.
755
+
756
+ Couverture : `npm run coverage` dans `@nodefony/redis`.
757
+
758
+ ## 🔗 Pour aller plus loin
759
+
760
+ - ⬆️ **Retour au hub** : [@nodefony/redis — vue d'ensemble](index.md) · [Toute la documentation](../../../../../docs/index.md)
761
+ - 🧭 **Page sœur** : [Architecture interne](./architecture.md) — connexions, résilience, structures de
762
+ données, et ce qui se passe quand Redis tombe
763
+ - 🧩 **Les briques qui consomment cette configuration** : [sessions](../../http/docs/session.md) ·
764
+ [jetons](../../security/docs/tokens.md) · [passkeys](../../security/docs/webauthn.md) ·
765
+ [idempotence](../../framework/docs/idempotence.md)
766
+ - ⚙️ **Configurer une application Nodefony** : [le guide `defineConfig`](../../../../../docs/guides/configuration.md) ·
767
+ [déclarer son infra](../../../../../docs/guides/persistence.md) ·
768
+ [choisir un store de sessions](../../../../../docs/guides/session-storage.md)
769
+ - 📡 **Le temps réel cross-pod** : [choisir son driver de backplane](../../realtime/docs/configuration.md)
770
+ - 🗄️ **Le durable, à côté** : [`@nodefony/drizzle`](../../drizzle/docs/index.md) ·
771
+ [`@nodefony/mongoose`](../../mongoose/docs/index.md)
772
+ - 🗺️ **Se situer** : [vue d'ensemble du framework](../../../../../docs/architecture/vue-ensemble.md) ·
773
+ [lexique général](../../../../../docs/lexique.md)