@nodefony/redis 10.0.0-beta.2 → 10.0.0-beta.4
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/README.md +5 -1
- package/dist/_virtual/{_@oxc-project_runtime@0.152.0 → _@oxc-project_runtime@0.155.0}/helpers/esm/decorate.js +1 -2
- package/dist/index.js +4 -6
- package/dist/nodefony/config/config.js +8 -5
- package/dist/nodefony/config/configSchema.js +18 -0
- package/dist/nodefony/config/defineModuleConfig.js +14 -24
- package/dist/nodefony/registerStores.js +1 -2
- package/dist/nodefony/service/redis.js +1 -2
- package/dist/nodefony/src/Connection.js +1 -2
- package/dist/nodefony/src/RedisTokenStore.js +57 -27
- package/dist/nodefony/src/RedisWebAuthnCredentialStore.js +27 -21
- package/dist/nodefony/src/SessionStorage.js +202 -57
- package/dist/nodefony/src/buildClientOptions.js +1 -2
- package/dist/nodefony/src/keyNamespace.js +1 -2
- package/dist/nodefony/src/scanCursor.js +55 -3
- package/dist/nodefony/src/sessionIndex.js +184 -0
- package/dist/types/nodefony/config/configSchema.d.ts +12 -0
- package/dist/types/nodefony/src/SessionStorage.d.ts +16 -14
- package/dist/types/nodefony/src/scanCursor.d.ts +32 -0
- package/dist/types/nodefony/src/sessionIndex.d.ts +89 -0
- package/docs/architecture.md +81 -73
- package/docs/configuration.md +111 -90
- package/docs/index.md +6 -6
- package/package.json +16 -15
- package/dist/_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js +0 -6
package/docs/configuration.md
CHANGED
|
@@ -64,9 +64,9 @@ flowchart TD
|
|
|
64
64
|
Deux résolutions distinctes, souvent confondues :
|
|
65
65
|
|
|
66
66
|
1. **La configuration du module** est résolue **une fois**, au démarrage, par `defineRedisConfig()`
|
|
67
|
-
(`defineModuleConfig.ts
|
|
67
|
+
(`defineModuleConfig.ts#defineRedisConfig`). Le résultat est **gelé** — plus personne ne le modifie ensuite.
|
|
68
68
|
2. **Les options d'un client** sont assemblées **par connexion**, au moment de l'ouverture, par
|
|
69
|
-
`buildClientOptions()` (`buildClientOptions.ts
|
|
69
|
+
`buildClientOptions()` (`buildClientOptions.ts#buildClientOptions`). C'est là que `url` écrase l'hôte, et que la
|
|
70
70
|
surcharge d'une connexion se pose par-dessus le socket global.
|
|
71
71
|
|
|
72
72
|
> [!TIP]
|
|
@@ -119,21 +119,21 @@ Le module ne possède pas de « fichier de valeurs par défaut » à côté d'un
|
|
|
119
119
|
options ». Il possède **un schéma Zod commenté**, et tout en dérive :
|
|
120
120
|
|
|
121
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
|
|
122
|
+
démarrage sont produites par le schéma lui-même — `redisConfigSchema.parse({})` (`config.ts#redisConfigSchema`) —
|
|
123
123
|
et non retapées à la main.
|
|
124
|
-
- **Le type TypeScript** est inféré, jamais redéclaré : `IRedisConfig` (`IRedisConfig.ts
|
|
125
|
-
pendant d'entrée `IRedisConfigInput` (`IRedisConfig.ts
|
|
124
|
+
- **Le type TypeScript** est inféré, jamais redéclaré : `IRedisConfig` (`IRedisConfig.ts#IRedisConfig`) et son
|
|
125
|
+
pendant d'entrée `IRedisConfigInput` (`IRedisConfig.ts#IRedisConfigInput`), où tout champ portant un défaut devient
|
|
126
126
|
optionnel.
|
|
127
127
|
- **Le texte d'aide** vit dans les `.describe()` du schéma, ce qui permet à
|
|
128
|
-
`redisConfigJsonSchema()` (`defineModuleConfig.ts
|
|
128
|
+
`redisConfigJsonSchema()` (`defineModuleConfig.ts#redisConfigJsonSchema`) de publier un JSON Schema **documenté** que
|
|
129
129
|
Studio transforme en formulaire.
|
|
130
130
|
- **Les champs sensibles se déclarent** : `url` et `password` portent un `.meta({ secret: true })`
|
|
131
|
-
(`config.ts
|
|
131
|
+
(`config.ts#globalOptionsSchema`), ce qui les fait masquer là où la configuration est affichée.
|
|
132
132
|
|
|
133
133
|
Le schéma reste volontairement **pur** : il ne lit jamais `process.env`. Sans cette règle, il
|
|
134
134
|
deviendrait non déterministe et le JSON Schema publié dépendrait de la machine qui l'a produit. La
|
|
135
135
|
lecture de l'environnement est donc une couche explicite, appliquée après coup par
|
|
136
|
-
`applyEnvOverrides()` (`defineModuleConfig.ts
|
|
136
|
+
`applyEnvOverrides()` (`defineModuleConfig.ts#applyEnvOverrides`).
|
|
137
137
|
|
|
138
138
|
Cette organisation est la convention de configuration du framework, tenue à deux fichiers et deux
|
|
139
139
|
seulement : `config.ts` porte **le quoi** (schéma, contraintes, défauts), `defineModuleConfig.ts`
|
|
@@ -142,7 +142,7 @@ troisième fichier de configuration, dans un module Nodefony, est un signal d'al
|
|
|
142
142
|
|
|
143
143
|
> [!NOTE]
|
|
144
144
|
> La configuration du module est **immuable après le démarrage** : `defineRedisConfig()` rend un objet
|
|
145
|
-
> gelé (`defineModuleConfig.ts
|
|
145
|
+
> gelé (`defineModuleConfig.ts#defineRedisConfig`). Changer de serveur Redis suppose donc un redémarrage — aucune
|
|
146
146
|
> clé n'est modifiable à chaud.
|
|
147
147
|
|
|
148
148
|
## 🚀 Démarrage rapide
|
|
@@ -153,27 +153,38 @@ vérifier.
|
|
|
153
153
|
### 1. Déclarer le module
|
|
154
154
|
|
|
155
155
|
```ts
|
|
156
|
+
// nodefony/config/redis.ts — le fragment du module, importé par le manifeste
|
|
157
|
+
import type { IRedisConfigInput } from "@nodefony/redis";
|
|
158
|
+
|
|
159
|
+
export const redisConfig = () =>
|
|
160
|
+
({
|
|
161
|
+
globalOptions: {
|
|
162
|
+
socket: {
|
|
163
|
+
host: "127.0.0.1",
|
|
164
|
+
port: 6379,
|
|
165
|
+
// 5 s pour établir le socket : au-delà, on échoue au lieu de pendre.
|
|
166
|
+
connectTimeout: 5_000,
|
|
167
|
+
},
|
|
168
|
+
// Aucun secret ici : le mot de passe arrive par NF_REDIS_PASSWORD.
|
|
169
|
+
},
|
|
170
|
+
connections: {
|
|
171
|
+
// S'AJOUTE à main / publish / subscribe (fusion profonde des défauts) —
|
|
172
|
+
// une base séparée pour un cache applicatif qu'on pourra vider seul.
|
|
173
|
+
cache: { name: "cache", database: 1 },
|
|
174
|
+
},
|
|
175
|
+
}) satisfies IRedisConfigInput;
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
```ts ignore
|
|
156
179
|
// nodefony.config.ts — l'orchestrateur de l'application
|
|
180
|
+
import { defineConfig, use } from "nodefony";
|
|
181
|
+
import { redisConfig } from "./nodefony/config/redis";
|
|
182
|
+
|
|
157
183
|
export default defineConfig(() => ({
|
|
158
184
|
modules: [
|
|
159
185
|
// Redis d'abord : il enregistre ses fabriques de stores pendant
|
|
160
186
|
// 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
|
-
}),
|
|
187
|
+
use("@nodefony/redis", redisConfig()),
|
|
177
188
|
"@nodefony/http",
|
|
178
189
|
"@nodefony/framework",
|
|
179
190
|
],
|
|
@@ -247,7 +258,7 @@ export default RedisTargetController;
|
|
|
247
258
|
### 4. Ce qu'on observe
|
|
248
259
|
|
|
249
260
|
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
|
|
261
|
+
identifiants masqués, par `Connection.#endpoint()` (`Connection.ts#Connection.#endpoint`) :
|
|
251
262
|
|
|
252
263
|
```
|
|
253
264
|
REDIS CONNECTION main CONNECT 127.0.0.1:6379
|
|
@@ -269,7 +280,7 @@ C'est la fusion profonde du manifeste, et c'est le comportement voulu.
|
|
|
269
280
|
|
|
270
281
|
## ⚙️ Toutes les clés du schéma
|
|
271
282
|
|
|
272
|
-
Les défauts ci-dessous sont ceux du schéma, lus dans `redisConfigSchema` (`config.ts
|
|
283
|
+
Les défauts ci-dessous sont ceux du schéma, lus dans `redisConfigSchema` (`config.ts#redisConfigSchema`). Une seule
|
|
273
284
|
valeur effective diffère du schéma au démarrage — `maxRetries`, traitée dans sa propre section.
|
|
274
285
|
|
|
275
286
|
### Racine
|
|
@@ -284,7 +295,7 @@ valeur effective diffère du schéma au démarrage — `maxRetries`, traitée da
|
|
|
284
295
|
| `keyNamespace` | chaîne | nom de l'application | Cloison des **clés** par application sur un Redis mutualisé (cf ci-dessous). |
|
|
285
296
|
|
|
286
297
|
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
|
|
298
|
+
connexion. Les trois entrées par défaut sont matérialisées dans `redisConfigSchema` (`config.ts#redisConfigSchema`).
|
|
288
299
|
|
|
289
300
|
#### `keyNamespace` — deux applications sur un même Redis
|
|
290
301
|
|
|
@@ -327,11 +338,11 @@ historiques (`nf:sess`, `nf:tok`, `nf:wac`) sont conservés tels quels.
|
|
|
327
338
|
|
|
328
339
|
### `globalOptions`
|
|
329
340
|
|
|
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
|
|
341
|
+
| Clé | Type | Défaut | Effet |
|
|
342
|
+
| ---------- | --------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
343
|
+
| `socket` | objet | défauts de `socketSchema` | Les options TCP/TLS communes. |
|
|
344
|
+
| `username` | chaîne | _absent_ | Utilisateur ACL (Redis 6+). Absent avec un `password` présent = authentification héritée `requirepass`. |
|
|
345
|
+
| `password` | chaîne (secret) | _absent_ | Mot de passe. Marqué secret dans `globalOptionsSchema` (`config.ts#globalOptionsSchema`) → masqué là où il s'afficherait. |
|
|
335
346
|
|
|
336
347
|
`username` n'a **pas** de variable d'environnement dédiée : sur un serveur à ACL, il se pose dans la
|
|
337
348
|
configuration de l'application (il n'est pas secret par lui-même), ou dans l'URL.
|
|
@@ -348,7 +359,7 @@ configuration de l'application (il n'est pas secret par lui-même), ou dans l'UR
|
|
|
348
359
|
| `tls` | booléen | `false` | Chiffre le canal. Voir la limite de forme plus bas — c'est un drapeau, pas un jeu de certificats. |
|
|
349
360
|
| `reconnectStrategy` | objet | défauts de `reconnectStrategySchema` | La politique de reconnexion, décrite juste après. |
|
|
350
361
|
|
|
351
|
-
Ces contraintes sont portées par `socketSchema` (`config.ts
|
|
362
|
+
Ces contraintes sont portées par `socketSchema` (`config.ts#socketSchema`) : ce sont elles qui font échouer le
|
|
352
363
|
démarrage plutôt que de laisser passer un port fantaisiste.
|
|
353
364
|
|
|
354
365
|
### `globalOptions.socket.reconnectStrategy`
|
|
@@ -360,7 +371,7 @@ démarrage plutôt que de laisser passer un port fantaisiste.
|
|
|
360
371
|
| `maxRetries` | entier ≥ 0 | `0` | Nombre de tentatives avant abandon. `0` = illimité. **Valeur effective : voir ci-dessous.** |
|
|
361
372
|
|
|
362
373
|
Ces trois valeurs sont déclaratives ; elles sont converties en fonction par
|
|
363
|
-
`buildReconnectStrategy()` (`buildClientOptions.ts
|
|
374
|
+
`buildReconnectStrategy()` (`buildClientOptions.ts#buildReconnectStrategy`) au moment d'assembler le client, parce qu'un
|
|
364
375
|
schéma Zod ne sait pas transporter une fonction.
|
|
365
376
|
|
|
366
377
|
### `connections.<nom>`
|
|
@@ -371,13 +382,13 @@ schéma Zod ne sait pas transporter une fonction.
|
|
|
371
382
|
| `database` | entier ≥ 0 | `0` | Base Redis sélectionnée. **N'isole que les commandes clé-valeur** — le pub/sub ignore la base. |
|
|
372
383
|
| `socket` | objet partiel | _absent_ | Surcharge du socket pour cette connexion seulement ; les champs omis restent ceux du socket global. |
|
|
373
384
|
|
|
374
|
-
`name` est le seul champ sans valeur d'usine dans tout le schéma (`connectionSchema` (`config.ts
|
|
385
|
+
`name` est le seul champ sans valeur d'usine dans tout le schéma (`connectionSchema` (`config.ts#connectionSchema`)) :
|
|
375
386
|
une connexion sans nom serait invisible dans les journaux et côté serveur, on refuse donc de deviner.
|
|
376
387
|
|
|
377
388
|
### `connections.<nom>.socket` — la surcharge
|
|
378
389
|
|
|
379
390
|
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
|
|
391
|
+
`tls`. C'est une décision de conception, portée par `socketOverrideSchema` (`config.ts#socketOverrideSchema`) : un
|
|
381
392
|
schéma partiel qui réappliquerait ses propres défauts écraserait silencieusement le socket global —
|
|
382
393
|
poser un `host` particulier ramènerait le port à `6379` sans le dire.
|
|
383
394
|
|
|
@@ -393,16 +404,28 @@ connections: {
|
|
|
393
404
|
|
|
394
405
|
### Les cinq variables lues
|
|
395
406
|
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
|
407
|
+
Deux mécanismes, et un seul endroit chacun :
|
|
408
|
+
|
|
409
|
+
- **`NF_REDIS_URL`** (alias de plateforme `REDIS_URL`) est une variable d'**infrastructure** : résolue
|
|
410
|
+
par `resolveInfra()` (`infra.ts#resolveInfra`) et posée sur `url` par `applyEnvOverrides()`
|
|
411
|
+
(`defineModuleConfig.ts#applyEnvOverrides`), après la validation.
|
|
412
|
+
- Les **quatre noms courts** sont DÉCLARÉS sur leur champ dans le schéma — `.meta({ env: "NF_REDIS_HOST" })`
|
|
413
|
+
(`config.ts#socketSchema`). Le Kernel les pose avant la validation, par `applyEnvShortcuts()`
|
|
414
|
+
(`envShortcuts.ts#applyEnvShortcuts`) ; le schéma les valide donc comme une valeur de l'application.
|
|
415
|
+
|
|
416
|
+
| Variable | Ce qu'elle vise | Comportement |
|
|
417
|
+
| ------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------- |
|
|
418
|
+
| `NF_REDIS_URL` (ou `REDIS_URL`) | `url` | Résolue par `resolveInfra()` ; `NF_REDIS_URL` l'emporte sur l'alias de plateforme. |
|
|
419
|
+
| `NF_REDIS_HOST` | `globalOptions.socket.host` | Validée par le schéma (chaîne non vide). |
|
|
420
|
+
| `NF_REDIS_PORT` | `globalOptions.socket.port` | Validée par le schéma : hors `1..65535`, ou pas un entier, le **démarrage est refusé**. |
|
|
421
|
+
| `NF_REDIS_PASSWORD` | `globalOptions.password` | Le seul chemin recommandé pour le secret. Monté en fichier : `NF_REDIS_PASSWORD_FILE=/run/secrets/…`. |
|
|
422
|
+
| `NF_REDIS_KEY_NAMESPACE` | `keyNamespace` | Cloison de déploiement, prioritaire sur la config. Pas un secret (déclaré `secret: false`). |
|
|
423
|
+
|
|
424
|
+
Chaque nom court accepte aussi la forme `_FILE` (secret monté par Docker ou Kubernetes) ; poser la
|
|
425
|
+
variable ET son `_FILE` arrête le démarrage. Une variable vide vaut absente. Le même réglage visé par
|
|
426
|
+
un nom court et par `NF__REDIS__…` est refusé en production, et tranché en faveur de `NF__` (avec un
|
|
427
|
+
avertissement) en développement — règle commune à tous les modules, décrite dans le guide
|
|
428
|
+
[configuration](../../../../../docs/guides/configuration.md).
|
|
406
429
|
|
|
407
430
|
`REDIS_URL` est accepté comme **alias de plateforme** parce que c'est le nom que posent la plupart des
|
|
408
431
|
hébergeurs. Quand les deux existent, la variable préfixée gagne — le préfixe `NF_` sert précisément à
|
|
@@ -410,20 +433,18 @@ reprendre la main sur une variable imposée par l'environnement d'hébergement.
|
|
|
410
433
|
|
|
411
434
|
### L'ordre, prouvé par le code
|
|
412
435
|
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
2. `applyResilienceDefaults()` (`defineModuleConfig.ts:65`) — le garde-fou de reconnexion, qui
|
|
436
|
+
1. Le **Kernel** pose les noms courts (`NF_REDIS_HOST`…) puis les surcharges `NF__REDIS__…` sur la
|
|
437
|
+
configuration de l'application, avant toute validation.
|
|
438
|
+
2. `defineRedisConfig()` (`defineModuleConfig.ts#defineRedisConfig`) valide — les défauts comblent ce que personne
|
|
439
|
+
n'a dit, la validation refuse ce qui est hors bornes, d'où qu'il vienne.
|
|
440
|
+
3. `applyResilienceDefaults()` (`defineModuleConfig.ts#applyResilienceDefaults`) — le garde-fou de reconnexion, qui
|
|
419
441
|
inspecte l'entrée **brute** pour savoir si l'application s'est prononcée.
|
|
420
|
-
|
|
421
|
-
|
|
442
|
+
4. `applyEnvOverrides()` (`defineModuleConfig.ts#applyEnvOverrides`) — l'URL d'infrastructure écrase `url`.
|
|
443
|
+
5. `Object.freeze` — plus rien ne bouge.
|
|
422
444
|
|
|
423
445
|
D'où la règle, dans cet ordre croissant d'autorité : **défauts du schéma → configuration de
|
|
424
446
|
l'application → environnement**. Le comportement est verrouillé par les tests unitaires
|
|
425
|
-
(`config.test.ts
|
|
426
|
-
invalide ignoré).
|
|
447
|
+
(`config.test.ts` : les noms courts déclarés, posés puis validés, et le port invalide REFUSÉ).
|
|
427
448
|
|
|
428
449
|
> [!IMPORTANT]
|
|
429
450
|
> L'environnement gagne **même contre une valeur explicite de l'application**. Une `url` écrite dans
|
|
@@ -432,13 +453,13 @@ invalide ignoré).
|
|
|
432
453
|
> recompiler — mais c'est aussi la première cause de « ma configuration est ignorée ».
|
|
433
454
|
|
|
434
455
|
Un cinquième geste vient plus tard, à l'ouverture de chaque connexion : la précédence **`url` ▸ socket
|
|
435
|
-
de la connexion ▸ socket global**, tranchée par `buildClientOptions()` (`buildClientOptions.ts
|
|
436
|
-
et prouvée par `config.test.ts
|
|
456
|
+
de la connexion ▸ socket global**, tranchée par `buildClientOptions()` (`buildClientOptions.ts#buildClientOptions`)
|
|
457
|
+
et prouvée par `config.test.ts`.
|
|
437
458
|
|
|
438
459
|
### Le double effet de l'URL d'infra
|
|
439
460
|
|
|
440
461
|
`NF_REDIS_URL` n'est pas seulement la cible de ce module : c'est la déclaration d'une **infra de
|
|
441
|
-
cache** pour le framework entier. `resolveAutoStore()` (`infra.ts
|
|
462
|
+
cache** pour le framework entier. `resolveAutoStore()` (`infra.ts#resolveAutoStore`) s'en sert pour les briques
|
|
442
463
|
dont le store vaut `auto` :
|
|
443
464
|
|
|
444
465
|
| Brique | Nature de la donnée | Avec une infra de cache déclarée |
|
|
@@ -461,7 +482,7 @@ jamais où les sessions ont atterri. Le comparatif transverse vit dans
|
|
|
461
482
|
### Quand une URL est posée, ce qui devient sans effet
|
|
462
483
|
|
|
463
484
|
Dès que `url` est renseignée — par l'application ou par l'environnement — `buildClientOptions()`
|
|
464
|
-
(`buildClientOptions.ts
|
|
485
|
+
(`buildClientOptions.ts#buildClientOptions`) **ne pose plus** `socket.host` ni `socket.port` : ils entreraient en
|
|
465
486
|
conflit avec ceux de l'URL. Trois conséquences à connaître :
|
|
466
487
|
|
|
467
488
|
<!-- prettier-ignore -->
|
|
@@ -495,8 +516,8 @@ définitivement.
|
|
|
495
516
|
**Hors production, ce réglage fait pendre le démarrage.** Avec des tentatives illimitées, la première
|
|
496
517
|
ouverture ne rend jamais la main tant que Redis ne répond pas ; la file d'attente hors ligne du client
|
|
497
518
|
retient les commandes, et un démarrage sans serveur se transforme en attente infinie plutôt qu'en
|
|
498
|
-
échec lisible. D'où `applyResilienceDefaults()` (`defineModuleConfig.ts
|
|
499
|
-
à `DEV_DEFAULT_MAX_RETRIES` (`defineModuleConfig.ts
|
|
519
|
+
échec lisible. D'où `applyResilienceDefaults()` (`defineModuleConfig.ts#applyResilienceDefaults`), qui borne les tentatives
|
|
520
|
+
à `DEV_DEFAULT_MAX_RETRIES` (`defineModuleConfig.ts#DEV_DEFAULT_MAX_RETRIES`) — cinq — quand, et seulement quand,
|
|
500
521
|
l'application ne s'est pas prononcée.
|
|
501
522
|
|
|
502
523
|
| `NODE_ENV` | L'application fixe `maxRetries` ? | Valeur effective |
|
|
@@ -508,9 +529,9 @@ l'application ne s'est pas prononcée.
|
|
|
508
529
|
|
|
509
530
|
La distinction « fixé / non fixé » se lit sur l'**entrée brute** de l'application, avant le parcours du
|
|
510
531
|
schéma : une fois les défauts appliqués, un `0` d'usine serait indiscernable d'un `0` voulu. Les trois
|
|
511
|
-
branches sont couvertes par les tests (`config.test.ts
|
|
532
|
+
branches sont couvertes par les tests (`config.test.ts`).
|
|
512
533
|
|
|
513
|
-
**Le calcul du délai.** `buildReconnectStrategy()` (`buildClientOptions.ts
|
|
534
|
+
**Le calcul du délai.** `buildReconnectStrategy()` (`buildClientOptions.ts#buildReconnectStrategy`) rend
|
|
514
535
|
`min((tentative + 1) × baseMs, maxMs)`, et une erreur — donc l'abandon — dès que le nombre de
|
|
515
536
|
tentatives atteint `maxRetries`, si celui-ci est fini. Avec les valeurs d'usine, hors production :
|
|
516
537
|
|
|
@@ -535,7 +556,7 @@ abonné ne peut plus émettre de commandes normales. Une connexion unique rendra
|
|
|
535
556
|
stockage mutuellement exclusifs.
|
|
536
557
|
|
|
537
558
|
Ajouter une connexion se fait en nommant une nouvelle clé. La fusion du manifeste est **profonde** —
|
|
538
|
-
`loadModulesFromManifest()` (`Kernel.ts
|
|
559
|
+
`loadModulesFromManifest()` (`Kernel.ts#Kernel.loadModulesFromManifest`) fusionne la configuration de `use()` sous les défauts
|
|
539
560
|
déjà matérialisés du module — donc les trois connexions d'usine restent en place :
|
|
540
561
|
|
|
541
562
|
```ts ignore
|
|
@@ -612,7 +633,7 @@ Aucune ligne dans `nodefony.config.ts`. Le mot de passe voyage dans l'URL : trai
|
|
|
612
633
|
secret entier, jamais comme une adresse.
|
|
613
634
|
|
|
614
635
|
**La limite de forme à connaître** : le schéma n'expose qu'un **booléen** `tls`
|
|
615
|
-
(`socketSchema` (`config.ts
|
|
636
|
+
(`socketSchema` (`config.ts#socketSchema`)). Autorité de certification privée, certificat client, nom de
|
|
616
637
|
serveur explicite — rien de tout cela n'est exprimable. Un service managé à certificat public
|
|
617
638
|
fonctionne ; une authentification mutuelle par certificat n'est pas couverte par la configuration du
|
|
618
639
|
module.
|
|
@@ -639,7 +660,7 @@ Deux réponses, selon l'intention.
|
|
|
639
660
|
**Ne pas charger Redis du tout** : retirer le module du manifeste. C'est le plus propre quand aucune
|
|
640
661
|
brique n'en dépend.
|
|
641
662
|
|
|
642
|
-
**Le charger, inerte** : `enabled: false` (`redisConfigSchema` (`config.ts
|
|
663
|
+
**Le charger, inerte** : `enabled: false` (`redisConfigSchema` (`config.ts#redisConfigSchema`)) laisse le module en
|
|
643
664
|
place sans ouvrir un seul socket. Utile quand le manifeste est commun à plusieurs environnements.
|
|
644
665
|
|
|
645
666
|
```ts ignore
|
|
@@ -654,7 +675,7 @@ use("@nodefony/redis", { enabled: false });
|
|
|
654
675
|
### `cluster-sentinel` — ce qui n'est pas couvert
|
|
655
676
|
|
|
656
677
|
Le module construit ses clients avec la fabrique **client simple** de la bibliothèque `redis` —
|
|
657
|
-
`buildClientOptions()` (`buildClientOptions.ts
|
|
678
|
+
`buildClientOptions()` (`buildClientOptions.ts#buildClientOptions`) produit des options de client, pas de grappe. Ni
|
|
658
679
|
Redis Cluster (répartition par partitions, redirections `MOVED`/`ASK`), ni Sentinel (élection du
|
|
659
680
|
maître) ne sont exprimables dans le schéma.
|
|
660
681
|
|
|
@@ -672,9 +693,9 @@ Mieux vaut le savoir en concevant l'infrastructure qu'en la déployant.
|
|
|
672
693
|
Deux échecs très différents partagent le même symptôme apparent — « Redis ne marche pas » — et se
|
|
673
694
|
règlent à des endroits opposés.
|
|
674
695
|
|
|
675
|
-
**La configuration est invalide.** `Redis.onKernelRegister()` (`index.ts
|
|
696
|
+
**La configuration est invalide.** `Redis.onKernelRegister()` (`index.ts#Redis.onKernelRegister`) valide avant tout le
|
|
676
697
|
reste et refuse de démarrer sur une valeur hors bornes. Le message nomme le champ fautif
|
|
677
|
-
(`index.ts
|
|
698
|
+
(`index.ts#Redis.onKernelRegister`) :
|
|
678
699
|
|
|
679
700
|
```
|
|
680
701
|
[@nodefony/redis] configuration invalide — globalOptions.socket.port : Too big: expected number to be <=65535
|
|
@@ -683,9 +704,9 @@ reste et refuse de démarrer sur une valeur hors bornes. Le message nomme le cha
|
|
|
683
704
|
C'est un défaut de configuration : rien à chercher côté réseau.
|
|
684
705
|
|
|
685
706
|
**Le serveur ne répond pas.** La configuration est bonne, l'ouverture échoue. Le module est déclaré
|
|
686
|
-
**non critique** — `Redis.critical` (`index.ts
|
|
707
|
+
**non critique** — `Redis.critical` (`index.ts#Redis.critical`) vaut `false` — donc l'application démarre quand
|
|
687
708
|
même, en état dégradé annoncé. Chaque connexion est tentée indépendamment et journalisée en `ERROR`
|
|
688
|
-
par `RedisService.init()` (`redis.ts
|
|
709
|
+
par `RedisService.init()` (`redis.ts#RedisService.init`) : une connexion en échec n'empêche pas les suivantes.
|
|
689
710
|
|
|
690
711
|
Ce que ce démarrage dégradé implique côté appelants — pourquoi le garde `if (!client)` des stores couvre
|
|
691
712
|
aussi une ouverture ratée, ce que devient une commande pendant une reconnexion — est
|
|
@@ -698,21 +719,21 @@ faire avant une mise en production.
|
|
|
698
719
|
| Symptôme | Cause | Correction |
|
|
699
720
|
| --- | --- | --- |
|
|
700
721
|
| Le démarrage échoue avec `configuration invalide — <chemin>` | Clé inconnue (faute de frappe) : le schéma est strict | Corriger l'orthographe d'après les tables ci-dessus |
|
|
701
|
-
| L'hôte configuré est ignoré | Une `url` est présente — `buildClientOptions()` (`buildClientOptions.ts
|
|
702
|
-
| `NF_REDIS_PORT`
|
|
722
|
+
| L'hôte configuré est ignoré | Une `url` est présente — `buildClientOptions()` (`buildClientOptions.ts#buildClientOptions`) ne pose plus host/port | Retirer `NF_REDIS_URL`/`REDIS_URL`, ou tout mettre dans l'URL |
|
|
723
|
+
| Le démarrage échoue en nommant `NF_REDIS_PORT` | Valeur non entière ou hors `1..65535` : le schéma la refuse | Corriger la valeur — un port faux n'est plus ignoré, il arrête le démarrage |
|
|
703
724
|
| 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 |
|
|
704
|
-
| 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
|
|
725
|
+
| 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#applyResilienceDefaults`)) ; sinon fixer une valeur finie |
|
|
705
726
|
| 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 |
|
|
706
|
-
| Les sessions ont changé de magasin sans qu'on touche à la configuration | `NF_REDIS_URL` déclare une infra de cache → `resolveAutoStore()` (`infra.ts
|
|
707
|
-
| Une surcharge de connexion ramène le port à `6379` | Un schéma partiel qui réappliquerait ses défauts — d'où `socketOverrideSchema` (`config.ts
|
|
708
|
-
| Le module démarre mais n'ouvre rien | `enabled: false` — module chargé, inerte (`RedisService.init()` (`redis.ts
|
|
727
|
+
| Les sessions ont changé de magasin sans qu'on touche à la configuration | `NF_REDIS_URL` déclare une infra de cache → `resolveAutoStore()` (`infra.ts#resolveAutoStore`) bascule les briques `auto` | Nommer le store explicitement pour un comportement identique partout |
|
|
728
|
+
| Une surcharge de connexion ramène le port à `6379` | Un schéma partiel qui réappliquerait ses défauts — d'où `socketOverrideSchema` (`config.ts#socketOverrideSchema`) sans défaut | Ne poser que les champs voulus ; les autres héritent du socket global |
|
|
729
|
+
| Le module démarre mais n'ouvre rien | `enabled: false` — module chargé, inerte (`RedisService.init()` (`redis.ts#RedisService.init`)) | Le réactiver, ou retirer le module du manifeste |
|
|
709
730
|
| 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 |
|
|
710
|
-
| Une valeur changée à chaud ne prend pas | La configuration est **gelée** après le démarrage (`defineRedisConfig()` (`defineModuleConfig.ts
|
|
731
|
+
| Une valeur changée à chaud ne prend pas | La configuration est **gelée** après le démarrage (`defineRedisConfig()` (`defineModuleConfig.ts#defineRedisConfig`)) | Redémarrer le process |
|
|
711
732
|
|
|
712
733
|
## 📡 Observabilité — Studio
|
|
713
734
|
|
|
714
735
|
- **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
|
|
736
|
+
**dérivé** du JSON Schema que publie `Redis.configSchema()` (`index.ts#Redis.configSchema`). Les champs marqués
|
|
716
737
|
secrets — `url`, `password` — y sont masqués par construction, pas par une liste d'exclusion tenue
|
|
717
738
|
à la main.
|
|
718
739
|
- **Écran Stores** (`/nodefony/stores`) : pour chaque brique, le store réellement retenu au démarrage
|
|
@@ -732,14 +753,14 @@ cette prose. Ce qui doit être dit ici, c'est **ce que la configuration a de pro
|
|
|
732
753
|
<!-- prettier-ignore -->
|
|
733
754
|
| Ce qui est vérifié | Où |
|
|
734
755
|
| --- | --- |
|
|
735
|
-
| Défauts d'usine et sous-défauts | `config.test.ts
|
|
736
|
-
| Refus d'une valeur hors bornes | `config.test.ts
|
|
737
|
-
| Superposition de l'environnement | `config.test.ts
|
|
738
|
-
| Port d'environnement invalide ignoré | `config.test.ts
|
|
739
|
-
| Garde-fou de reconnexion, ses trois branches | `config.test.ts
|
|
740
|
-
| Gel de la configuration | `config.test.ts
|
|
741
|
-
| Assemblage des options du client | `config.test.ts
|
|
742
|
-
| Back-off et abandon | `config.test.ts
|
|
756
|
+
| Défauts d'usine et sous-défauts | `config.test.ts` (hôte, port, TLS, trois connexions) |
|
|
757
|
+
| Refus d'une valeur hors bornes | `config.test.ts` (port hors plage) |
|
|
758
|
+
| Superposition de l'environnement | `config.test.ts` et `config.test.ts` |
|
|
759
|
+
| Port d'environnement invalide ignoré | `config.test.ts` |
|
|
760
|
+
| Garde-fou de reconnexion, ses trois branches | `config.test.ts` |
|
|
761
|
+
| Gel de la configuration | `config.test.ts` |
|
|
762
|
+
| Assemblage des options du client | `config.test.ts` (fusion) et `config.test.ts` (précédence de l'URL) |
|
|
763
|
+
| Back-off et abandon | `config.test.ts` |
|
|
743
764
|
|
|
744
765
|
Ces bancs sont **unitaires** : ils tournent sans serveur. La configuration est donc la partie du
|
|
745
766
|
module dont la vérification ne dépend d'aucune infrastructure — c'est aussi pour ça que le schéma doit
|
|
@@ -749,7 +770,7 @@ rester pur.
|
|
|
749
770
|
> **Une suite verte ne prouve rien du reste sans serveur Redis.** Les bancs d'intégration se
|
|
750
771
|
> **skippent** quand l'infra manque, et un skip compte comme un succès : on peut lire « tout est
|
|
751
772
|
> vert » sur une suite qui n'a rien exercé. La gate du module est déclarée une seule fois —
|
|
752
|
-
> `REDIS_GATE` (`vitest
|
|
773
|
+
> `REDIS_GATE` (`scripts/test/vitest/gates.ts#REDIS_GATE`) — et la fin de run nomme la cible non exercée avec la commande
|
|
753
774
|
> exacte pour la satisfaire. **Les variables et la commande docker se lisent là, pas ici** : les
|
|
754
775
|
> recopier dans cette page les condamnerait à diverger.
|
|
755
776
|
|
package/docs/index.md
CHANGED
|
@@ -99,8 +99,8 @@ pour quoi il est bon. Redis se déclare de nature `cache` et annonce quatre briq
|
|
|
99
99
|
`package.json` (clé `nodefony.stores`) — ni plus, ni moins.
|
|
100
100
|
|
|
101
101
|
La nuance décisive n'est pas « couvert / pas couvert », c'est **qui choisit**. Chaque brique déclare
|
|
102
|
-
la nature de sa donnée (`StoreKind`, `infra.ts
|
|
103
|
-
que pour les natures non durables (`resolveAutoStore()`, `infra.ts
|
|
102
|
+
la nature de sa donnée (`StoreKind`, `infra.ts#StoreKind`), et la résolution automatique ne propose Redis
|
|
103
|
+
que pour les natures non durables (`resolveAutoStore()`, `infra.ts#resolveAutoStore`).
|
|
104
104
|
|
|
105
105
|
<!-- prettier-ignore -->
|
|
106
106
|
| Brique | Nature | Implémentation | Choisi par `auto` ? | Où on l'allume explicitement |
|
|
@@ -218,7 +218,7 @@ flowchart TD
|
|
|
218
218
|
```
|
|
219
219
|
|
|
220
220
|
Le module ne connaît aucun de ses consommateurs : il expose un service, ils s'y branchent. C'est aussi
|
|
221
|
-
pour ça qu'il se déclare **non critique** (`Redis.critical` vaut `false`, `index.ts
|
|
221
|
+
pour ça qu'il se déclare **non critique** (`Redis.critical` vaut `false`, `index.ts#nodefony`) — un Redis
|
|
222
222
|
injoignable au démarrage n'empêche pas l'application de monter.
|
|
223
223
|
|
|
224
224
|
## 🧰 Surface publique
|
|
@@ -227,9 +227,9 @@ injoignable au démarrage n'empêche pas l'application de monter.
|
|
|
227
227
|
`RedisTokenStore`, `RedisWebAuthnCredentialStore` —, le builder `defineRedisConfig` avec son schéma,
|
|
228
228
|
et un ré-export de la bibliothèque `redis` elle-même pour qui a besoin de ses types.
|
|
229
229
|
|
|
230
|
-
Charger le module suffit : `registerRedisFrameworkStores()` (`registerStores.ts
|
|
230
|
+
Charger le module suffit : `registerRedisFrameworkStores()` (`registerStores.ts#registerRedisFrameworkStores`) inscrit les
|
|
231
231
|
fabriques `redis` dans les registres de `@nodefony/security`, et le store de session s'auto-déclare
|
|
232
|
-
(`SessionStorage.ts
|
|
232
|
+
(`SessionStorage.ts#RedisSessionStorage.listAll`). Aucun câblage applicatif — il ne reste qu'à nommer le store, ou à laisser
|
|
233
233
|
`auto` faire.
|
|
234
234
|
|
|
235
235
|
Les signatures exactes vivent dans le graphe généré (`jq '.symbols.RedisService' .ai/symbols.json`),
|
|
@@ -273,7 +273,7 @@ chose**.
|
|
|
273
273
|
> [!IMPORTANT]
|
|
274
274
|
> **Une suite verte ne prouve rien sans serveur Redis.** Les bancs d'intégration se **skippent** quand
|
|
275
275
|
> l'infra manque, et un skip compte comme un succès : on peut lire « tout est vert » sur une suite qui
|
|
276
|
-
> n'a rien exercé. Le module déclare donc sa gate — `REDIS_GATE` dans `vitest
|
|
276
|
+
> n'a rien exercé. Le module déclare donc sa gate — `REDIS_GATE` dans `scripts/test/vitest/gates.ts#REDIS_GATE` — et la
|
|
277
277
|
> fin de run nomme la cible non testée avec la commande exacte pour la satisfaire. **Lis ce bloc avant
|
|
278
278
|
> de conclure.** Les variables et la commande docker viennent de là, pas de cette page : les recopier
|
|
279
279
|
> ici les condamnerait à diverger.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nodefony/redis",
|
|
3
|
-
"version": "10.0.0-beta.
|
|
3
|
+
"version": "10.0.0-beta.4",
|
|
4
4
|
"description": "Connecteur Redis de Nodefony : dépôts clé-valeur, cache, sessions partagées et transport de diffusion entre instances",
|
|
5
5
|
"nodefony": {
|
|
6
6
|
"storeKind": "cache",
|
|
@@ -9,7 +9,8 @@
|
|
|
9
9
|
"tokens",
|
|
10
10
|
"passkeys",
|
|
11
11
|
"idempotency"
|
|
12
|
-
]
|
|
12
|
+
],
|
|
13
|
+
"configSchema": "./dist/nodefony/config/configSchema.js"
|
|
13
14
|
},
|
|
14
15
|
"contributors": [],
|
|
15
16
|
"main": "./dist/index.js",
|
|
@@ -34,7 +35,7 @@
|
|
|
34
35
|
},
|
|
35
36
|
"private": false,
|
|
36
37
|
"engines": {
|
|
37
|
-
"node": ">=24.
|
|
38
|
+
"node": ">=24.14.0"
|
|
38
39
|
},
|
|
39
40
|
"keywords": [
|
|
40
41
|
"nodefony",
|
|
@@ -51,20 +52,20 @@
|
|
|
51
52
|
"tslib": "2.8.1"
|
|
52
53
|
},
|
|
53
54
|
"devDependencies": {
|
|
54
|
-
"@nodefony/framework": "^10.0.0-beta.
|
|
55
|
-
"@nodefony/http": "^10.0.0-beta.
|
|
56
|
-
"@nodefony/security": "^10.0.0-beta.
|
|
57
|
-
"@types/node": "26.6.
|
|
58
|
-
"@vitest/coverage-v8": "5.0.
|
|
59
|
-
"nodefony": "^10.0.0-beta.
|
|
60
|
-
"vitest": "5.0.
|
|
55
|
+
"@nodefony/framework": "^10.0.0-beta.4",
|
|
56
|
+
"@nodefony/http": "^10.0.0-beta.4",
|
|
57
|
+
"@nodefony/security": "^10.0.0-beta.4",
|
|
58
|
+
"@types/node": "26.6.5",
|
|
59
|
+
"@vitest/coverage-v8": "5.0.5",
|
|
60
|
+
"nodefony": "^10.0.0-beta.4",
|
|
61
|
+
"vitest": "5.0.5"
|
|
61
62
|
},
|
|
62
63
|
"peerDependencies": {
|
|
63
|
-
"@nodefony/framework": "^10.0.0-beta.
|
|
64
|
-
"@nodefony/http": "^10.0.0-beta.
|
|
65
|
-
"@nodefony/security": "^10.0.0-beta.
|
|
66
|
-
"nodefony": "^10.0.0-beta.
|
|
67
|
-
"zod": "^4.6.
|
|
64
|
+
"@nodefony/framework": "^10.0.0-beta.4",
|
|
65
|
+
"@nodefony/http": "^10.0.0-beta.4",
|
|
66
|
+
"@nodefony/security": "^10.0.0-beta.4",
|
|
67
|
+
"nodefony": "^10.0.0-beta.4",
|
|
68
|
+
"zod": "^4.6.7"
|
|
68
69
|
},
|
|
69
70
|
"repository": {
|
|
70
71
|
"type": "git",
|
|
@@ -1,6 +0,0 @@
|
|
|
1
|
-
//#region \0@oxc-project+runtime@0.152.0/helpers/esm/decorateMetadata.js
|
|
2
|
-
function __decorateMetadata(k, v) {
|
|
3
|
-
if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
|
|
4
|
-
}
|
|
5
|
-
//#endregion
|
|
6
|
-
export { __decorateMetadata as default };
|