@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.
@@ -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:98`). Le résultat est **gelé** — plus personne ne le modifie ensuite.
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:45`). C'est là que `url` écrase l'hôte, et que la
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:248`) —
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:11`) et son
125
- pendant d'entrée `IRedisConfigInput` (`IRedisConfig.ts:17`), où tout champ portant un défaut devient
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:121`) de publier un JSON Schema **documenté** que
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:187`), ce qui les fait masquer là où la configuration est affichée.
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:23`).
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:103`). Changer de serveur Redis suppose donc un redémarrage — aucune
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:70`) :
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:200`). Une seule
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:200`).
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:173`) → masqué là où il s'afficherait. |
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:79`) : ce sont elles qui font échouer le
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:13`) au moment d'assembler le client, parce qu'un
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:143`)) :
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:133`) : un
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
- 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
- | `NF_REDIS_KEY_NAMESPACE` | `keyNamespace` | Prioritaire sur la config ; cloison de déploiement. |
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
- `defineRedisConfig()` (`defineModuleConfig.ts:98`) exécute quatre gestes, toujours dans le même
414
- ordre :
415
-
416
- 1. `redisConfigSchema.parse(entrée)` — les défauts comblent ce que l'application n'a pas dit, et la
417
- validation refuse ce qui est hors bornes.
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
- 3. `applyEnvOverrides()` (`defineModuleConfig.ts:23`) — l'environnement écrase ce qu'il nomme.
421
- 4. `Object.freeze` — plus rien ne bouge.
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:56` pour l'hôte, le port et le mot de passe ; `config.test.ts:72` pour le port
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:45`)
436
- et prouvée par `config.test.ts:128`.
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:289`) s'en sert pour les briques
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:45`) **ne pose plus** `socket.host` ni `socket.port` : ils entreraient en
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:65`), qui borne les tentatives
499
- à `DEV_DEFAULT_MAX_RETRIES` (`defineModuleConfig.ts:52`) — cinq — quand, et seulement quand,
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:85`, `config.test.ts:91`, `config.test.ts:99`).
532
+ branches sont couvertes par les tests (`config.test.ts`).
512
533
 
513
- **Le calcul du délai.** `buildReconnectStrategy()` (`buildClientOptions.ts:13`) rend
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:1714`) fusionne la configuration de `use()` sous les défauts
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:79`)). Autorité de certification privée, certificat client, nom de
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:202`)) laisse le module en
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:45`) produit des options de client, pas de grappe. Ni
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:64`) valide avant tout le
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:68`) :
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:46`) vaut `false` — donc l'application démarre quand
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:123`) : une connexion en échec n'empêche pas les suivantes.
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:45`) ne pose plus host/port | Retirer `NF_REDIS_URL`/`REDIS_URL`, ou tout mettre dans l'URL |
702
- | `NF_REDIS_PORT` semble sans effet | Valeur non entière ou hors `1..65535` : `applyEnvOverrides()` (`defineModuleConfig.ts:24`) l'ignore | Corriger la valeur — l'ignorance est silencieuse par conception |
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:65`)) ; sinon fixer une valeur finie |
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:297`) bascule les briques `auto` | Nommer le store explicitement pour un comportement identique partout |
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:133`) sans défaut | Ne poser que les champs voulus ; les autres héritent du socket global |
708
- | 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 |
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:103`)) | Redémarrer le process |
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:53`). Les champs marqués
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: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` |
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.gates.ts:339`) — et la fin de run nomme la cible non exercée avec la commande
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:176`), et la résolution automatique ne propose Redis
103
- que pour les natures non durables (`resolveAutoStore()`, `infra.ts:289`).
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:36`) — un Redis
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:72`) inscrit les
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:323`). Aucun câblage applicatif — il ne reste qu'à nommer le store, ou à laisser
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.gates.ts:339` — et la
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.2",
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.0.0"
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.2",
55
- "@nodefony/http": "^10.0.0-beta.2",
56
- "@nodefony/security": "^10.0.0-beta.2",
57
- "@types/node": "26.6.3",
58
- "@vitest/coverage-v8": "5.0.3",
59
- "nodefony": "^10.0.0-beta.2",
60
- "vitest": "5.0.3"
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.2",
64
- "@nodefony/http": "^10.0.0-beta.2",
65
- "@nodefony/security": "^10.0.0-beta.2",
66
- "nodefony": "^10.0.0-beta.2",
67
- "zod": "^4.6.5"
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 };