@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.
- package/LICENSE +544 -0
- package/README.md +110 -0
- package/dist/_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js +9 -0
- package/dist/_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js +6 -0
- package/dist/index.js +58 -0
- package/dist/nodefony/config/config.js +98 -0
- package/dist/nodefony/config/defineModuleConfig.js +90 -0
- package/dist/nodefony/interfaces/IRedisConfig.js +1 -0
- package/dist/nodefony/interfaces/index.js +1 -0
- package/dist/nodefony/registerStores.js +38 -0
- package/dist/nodefony/service/redis.js +177 -0
- package/dist/nodefony/src/Connection.js +111 -0
- package/dist/nodefony/src/RedisTokenStore.js +390 -0
- package/dist/nodefony/src/RedisWebAuthnCredentialStore.js +247 -0
- package/dist/nodefony/src/SessionStorage.js +249 -0
- package/dist/nodefony/src/buildClientOptions.js +63 -0
- package/dist/nodefony/src/keyNamespace.js +80 -0
- package/dist/nodefony/src/scanCursor.js +69 -0
- package/dist/types/index.d.ts +53 -0
- package/dist/types/nodefony/config/config.d.ts +41 -0
- package/dist/types/nodefony/config/defineModuleConfig.d.ts +26 -0
- package/dist/types/nodefony/interfaces/IRedisConfig.d.ts +17 -0
- package/dist/types/nodefony/interfaces/index.d.ts +5 -0
- package/dist/types/nodefony/registerStores.d.ts +5 -0
- package/dist/types/nodefony/service/redis.d.ts +82 -0
- package/dist/types/nodefony/src/Connection.d.ts +39 -0
- package/dist/types/nodefony/src/RedisTokenStore.d.ts +121 -0
- package/dist/types/nodefony/src/RedisWebAuthnCredentialStore.d.ts +108 -0
- package/dist/types/nodefony/src/SessionStorage.d.ts +87 -0
- package/dist/types/nodefony/src/buildClientOptions.d.ts +21 -0
- package/dist/types/nodefony/src/keyNamespace.d.ts +12 -0
- package/dist/types/nodefony/src/scanCursor.d.ts +50 -0
- package/docs/architecture.md +718 -0
- package/docs/configuration.md +773 -0
- package/docs/index.md +295 -0
- 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)
|