@nodefony/redis 10.0.0-beta.1 → 10.0.0-beta.3

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.
@@ -28,7 +28,7 @@ coverageModule: redis
28
28
  # Configuration de @nodefony/redis
29
29
 
30
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
31
+ > défaut sûr. Cette page donne la liste complète des clés avec leur valeur d'usine réelle, les cinq
32
32
  > variables d'environnement et l'ordre exact dans lequel elles gagnent, puis six situations de
33
33
  > déploiement — du poste de développement au service managé chiffré. Ce que le module fait _dedans_
34
34
  > avec ces valeurs (cycle des connexions, reconnexion, dégradation) est décrit par la page voisine,
@@ -64,7 +64,7 @@ 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:85`). 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
69
  `buildClientOptions()` (`buildClientOptions.ts:45`). 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.
@@ -125,7 +125,7 @@ options ». Il possède **un schéma Zod commenté**, et tout en dérive :
125
125
  pendant d'entrée `IRedisConfigInput` (`IRedisConfig.ts:17`), 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:101`) 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
131
  (`config.ts:187`), ce qui les fait masquer là où la configuration est affichée.
@@ -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:85`). Changer de serveur Redis suppose donc un redémarrage — aucune
146
146
  > clé n'est modifiable à chaud.
147
147
 
148
148
  ## 🚀 Démarrage rapide
@@ -391,17 +391,30 @@ connections: {
391
391
 
392
392
  ## Variables d'environnement et ordre de précédence
393
393
 
394
- ### Les quatre variables lues
394
+ ### Les cinq variables lues
395
395
 
396
- Toutes sont appliquées **après** la validation, par `applyEnvOverrides()`
397
- (`defineModuleConfig.ts:23`).
396
+ Deux mécanismes, et un seul endroit chacun :
398
397
 
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é. |
398
+ - **`NF_REDIS_URL`** (alias de plateforme `REDIS_URL`) est une variable d'**infrastructure** : résolue
399
+ par `resolveInfra()` (`infra.ts:134`) et posée sur `url` par `applyEnvOverrides()`
400
+ (`defineModuleConfig.ts:23`), après la validation.
401
+ - Les **quatre noms courts** sont DÉCLARÉS sur leur champ dans le schéma — `.meta({ env: "NF_REDIS_HOST" })`
402
+ (`config.ts:90`). Le Kernel les pose avant la validation, par `applyEnvShortcuts()`
403
+ (`envShortcuts.ts:146`) ; le schéma les valide donc comme une valeur de l'application.
404
+
405
+ | Variable | Ce qu'elle vise | Comportement |
406
+ | ------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------- |
407
+ | `NF_REDIS_URL` (ou `REDIS_URL`) | `url` | Résolue par `resolveInfra()` ; `NF_REDIS_URL` l'emporte sur l'alias de plateforme. |
408
+ | `NF_REDIS_HOST` | `globalOptions.socket.host` | Validée par le schéma (chaîne non vide). |
409
+ | `NF_REDIS_PORT` | `globalOptions.socket.port` | Validée par le schéma : hors `1..65535`, ou pas un entier, le **démarrage est refusé**. |
410
+ | `NF_REDIS_PASSWORD` | `globalOptions.password` | Le seul chemin recommandé pour le secret. Monté en fichier : `NF_REDIS_PASSWORD_FILE=/run/secrets/…`. |
411
+ | `NF_REDIS_KEY_NAMESPACE` | `keyNamespace` | Cloison de déploiement, prioritaire sur la config. Pas un secret (déclaré `secret: false`). |
412
+
413
+ Chaque nom court accepte aussi la forme `_FILE` (secret monté par Docker ou Kubernetes) ; poser la
414
+ variable ET son `_FILE` arrête le démarrage. Une variable vide vaut absente. Le même réglage visé par
415
+ un nom court et par `NF__REDIS__…` est refusé en production, et tranché en faveur de `NF__` (avec un
416
+ avertissement) en développement — règle commune à tous les modules, décrite dans le guide
417
+ [configuration](../../../../../docs/guides/configuration.md).
405
418
 
406
419
  `REDIS_URL` est accepté comme **alias de plateforme** parce que c'est le nom que posent la plupart des
407
420
  hébergeurs. Quand les deux existent, la variable préfixée gagne — le préfixe `NF_` sert précisément à
@@ -409,20 +422,18 @@ reprendre la main sur une variable imposée par l'environnement d'hébergement.
409
422
 
410
423
  ### L'ordre, prouvé par le code
411
424
 
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
425
+ 1. Le **Kernel** pose les noms courts (`NF_REDIS_HOST`…) puis les surcharges `NF__REDIS__…` sur la
426
+ configuration de l'application, avant toute validation.
427
+ 2. `defineRedisConfig()` (`defineModuleConfig.ts:85`) valide — les défauts comblent ce que personne
428
+ n'a dit, la validation refuse ce qui est hors bornes, d'où qu'il vienne.
429
+ 3. `applyResilienceDefaults()` (`defineModuleConfig.ts:52`) — le garde-fou de reconnexion, qui
418
430
  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.
431
+ 4. `applyEnvOverrides()` (`defineModuleConfig.ts:23`) — l'URL d'infrastructure écrase `url`.
432
+ 5. `Object.freeze` — plus rien ne bouge.
421
433
 
422
434
  D'où la règle, dans cet ordre croissant d'autorité : **défauts du schéma → configuration de
423
435
  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é).
436
+ (`config.test.ts` : les noms courts déclarés, posés puis validés, et le port invalide REFUSÉ).
426
437
 
427
438
  > [!IMPORTANT]
428
439
  > L'environnement gagne **même contre une valeur explicite de l'application**. Une `url` écrite dans
@@ -494,8 +505,8 @@ définitivement.
494
505
  **Hors production, ce réglage fait pendre le démarrage.** Avec des tentatives illimitées, la première
495
506
  ouverture ne rend jamais la main tant que Redis ne répond pas ; la file d'attente hors ligne du client
496
507
  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:52`) — cinq — quand, et seulement quand,
508
+ échec lisible. D'où `applyResilienceDefaults()` (`defineModuleConfig.ts:52`), qui borne les tentatives
509
+ à `DEV_DEFAULT_MAX_RETRIES` (`defineModuleConfig.ts:32`) — cinq — quand, et seulement quand,
499
510
  l'application ne s'est pas prononcée.
500
511
 
501
512
  | `NODE_ENV` | L'application fixe `maxRetries` ? | Valeur effective |
@@ -534,7 +545,7 @@ abonné ne peut plus émettre de commandes normales. Une connexion unique rendra
534
545
  stockage mutuellement exclusifs.
535
546
 
536
547
  Ajouter une connexion se fait en nommant une nouvelle clé. La fusion du manifeste est **profonde** —
537
- `loadModulesFromManifest()` (`Kernel.ts:1714`) fusionne la configuration de `use()` sous les défauts
548
+ `loadModulesFromManifest()` (`Kernel.ts:1794`) fusionne la configuration de `use()` sous les défauts
538
549
  déjà matérialisés du module — donc les trois connexions d'usine restent en place :
539
550
 
540
551
  ```ts ignore
@@ -686,8 +697,8 @@ C'est un défaut de configuration : rien à chercher côté réseau.
686
697
  même, en état dégradé annoncé. Chaque connexion est tentée indépendamment et journalisée en `ERROR`
687
698
  par `RedisService.init()` (`redis.ts:123`) : une connexion en échec n'empêche pas les suivantes.
688
699
 
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
700
+ Ce que ce démarrage dégradé implique côté appelants — pourquoi le garde `if (!client)` des stores couvre
701
+ aussi une ouverture ratée, ce que devient une commande pendant une reconnexion — est
691
702
  détaillé dans [Architecture interne](./architecture.md), section « Résilience ». C'est la lecture à
692
703
  faire avant une mise en production.
693
704
 
@@ -696,18 +707,17 @@ faire avant une mise en production.
696
707
  <!-- prettier-ignore -->
697
708
  | Symptôme | Cause | Correction |
698
709
  | --- | --- | --- |
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) |
710
+ | 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 |
700
711
  | 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 |
701
- | `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 |
712
+ | 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 |
702
713
  | 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 |
714
+ | 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:52`)) ; sinon fixer une valeur finie |
704
715
  | 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
716
  | 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 |
706
717
  | 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
718
  | 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
719
  | 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 |
720
+ | Une valeur changée à chaud ne prend pas | La configuration est **gelée** après le démarrage (`defineRedisConfig()` (`defineModuleConfig.ts:85`)) | Redémarrer le process |
711
721
 
712
722
  ## 📡 Observabilité — Studio
713
723
 
@@ -749,7 +759,7 @@ rester pur.
749
759
  > **Une suite verte ne prouve rien du reste sans serveur Redis.** Les bancs d'intégration se
750
760
  > **skippent** quand l'infra manque, et un skip compte comme un succès : on peut lire « tout est
751
761
  > 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
762
+ > `REDIS_GATE` (`scripts/test/vitest/gates.ts:351`) — et la fin de run nomme la cible non exercée avec la commande
753
763
  > exacte pour la satisfaire. **Les variables et la commande docker se lisent là, pas ici** : les
754
764
  > recopier dans cette page les condamnerait à diverger.
755
765
 
package/docs/index.md CHANGED
@@ -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:351` — 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.1",
3
+ "version": "10.0.0-beta.3",
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",
@@ -47,24 +48,24 @@
47
48
  "esm"
48
49
  ],
49
50
  "dependencies": {
50
- "redis": "6.2.1",
51
+ "redis": "6.3.0",
51
52
  "tslib": "2.8.1"
52
53
  },
53
54
  "devDependencies": {
54
- "@nodefony/framework": "^10.0.0-beta.1",
55
- "@nodefony/http": "^10.0.0-beta.1",
56
- "@nodefony/security": "^10.0.0-beta.1",
57
- "@types/node": "26.6.3",
58
- "@vitest/coverage-v8": "5.0.2",
59
- "nodefony": "^10.0.0-beta.1",
60
- "vitest": "5.0.2"
55
+ "@nodefony/framework": "^10.0.0-beta.3",
56
+ "@nodefony/http": "^10.0.0-beta.3",
57
+ "@nodefony/security": "^10.0.0-beta.3",
58
+ "@types/node": "26.6.5",
59
+ "@vitest/coverage-v8": "5.0.4",
60
+ "nodefony": "^10.0.0-beta.3",
61
+ "vitest": "5.0.4"
61
62
  },
62
63
  "peerDependencies": {
63
- "@nodefony/framework": "^10.0.0-beta.1",
64
- "@nodefony/http": "^10.0.0-beta.1",
65
- "@nodefony/security": "^10.0.0-beta.1",
66
- "nodefony": "^10.0.0-beta.1",
67
- "zod": "^4.6.5"
64
+ "@nodefony/framework": "^10.0.0-beta.3",
65
+ "@nodefony/http": "^10.0.0-beta.3",
66
+ "@nodefony/security": "^10.0.0-beta.3",
67
+ "nodefony": "^10.0.0-beta.3",
68
+ "zod": "^4.6.7"
68
69
  },
69
70
  "repository": {
70
71
  "type": "git",