@nodefony/redis 10.0.0-beta.2 → 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.
@@ -48,3 +48,35 @@ export declare function decodeCursor(cursor?: string): {
48
48
  };
49
49
  /** Un curseur `SCAN` exploitable (chiffres) ou `"0"` — jamais du texte libre. */
50
50
  export declare function scanOrZero(value: string): string;
51
+ /** Un lot `SCAN` tel que node-redis le rend : curseur suivant (string) + clés. */
52
+ export interface IScanBatch {
53
+ cursor: string;
54
+ keys: readonly string[];
55
+ }
56
+ /**
57
+ * Rend UNE page d'un balayage `SCAN` filtré — règle unique des trois stores.
58
+ *
59
+ * Les lots s'enchaînent jusqu'à **remplir** la page, finir le balayage, ou
60
+ * épuiser l'effort borné ({@link MAX_SCAN} emplacements examinés par appel).
61
+ * 🔴 Un seul lot ne suffit pas : `SCAN COUNT` examine des emplacements de TOUT
62
+ * le keyspace (autres applications, idempotence, jetons), et un lot peut ne
63
+ * contenir aucune clé retenue par le filtre. Rendre cette page vide ferait
64
+ * conclure « rien » à tout consommateur qui ne suit pas le curseur — c'était
65
+ * le cas de la console « Mes sessions » sur un Redis partagé.
66
+ *
67
+ * Le curseur rendu est composite ({@link encodeCursor}) : une page pleine au
68
+ * milieu d'un lot reprend au MÊME lot, à la bonne position. Le keyspace n'est
69
+ * jamais matérialisé — un lot à la fois.
70
+ *
71
+ * @param scan - lance un `SCAN` depuis ce curseur (MATCH et COUNT fixés par
72
+ * l'appelant ; `COUNT` doit rester le même d'une page à l'autre)
73
+ * @param cursor - curseur reçu du client (non fiable — décodé et validé)
74
+ * @param limit - taille maximale de la page
75
+ * @param accept - lit une clé et rend l'élément à publier, ou `null` s'il est
76
+ * écarté (filtre, clé expirée, valeur corrompue)
77
+ * @returns les éléments de la page et le curseur suivant (`null` = fin)
78
+ */
79
+ export declare function scanPage<T>(scan: (cursor: string) => Promise<IScanBatch>, cursor: string | undefined, limit: number, accept: (key: string) => Promise<T | null>): Promise<{
80
+ items: T[];
81
+ nextCursor: string | null;
82
+ }>;
@@ -0,0 +1,89 @@
1
+ /**
2
+ * Index Redis des sessions — compter sans balayer.
3
+ *
4
+ * Les sessions vivent sous `<préfixe>:<id>` avec un TTL natif : Redis les efface
5
+ * seul, sans passer par notre code. Les compter exigeait donc un `SCAN` de tout
6
+ * le keyspace, et le store renvoyait « inconnu » — la console affichait « — »,
7
+ * et l'on parcourait une liste sans savoir combien elle comptait.
8
+ *
9
+ * L'index tient, pour chaque session, sa date d'EXPIRATION comme score :
10
+ *
11
+ * | Clé | Type | Contenu |
12
+ * | --------------------------- | ---- | ----------------------------------------------- |
13
+ * | `<base>:all` | ZSET | toutes les sessions → expiration (ms) |
14
+ * | `<base>:auth` | ZSET | les sessions authentifiées |
15
+ * | `<base>:u:<utilisateur>` | ZSET | les sessions d'un utilisateur |
16
+ * | `<base>:users` | ZSET | utilisateur → expiration la plus tardive |
17
+ * | `<base>:owner` | HASH | session → utilisateur (`""` = anonyme) |
18
+ * | `<base>:built` | STR | l'index couvre les sessions antérieures |
19
+ *
20
+ * 🔴 **Une expiration n'a pas besoin d'être vue pour être comptée juste** : une
21
+ * entrée dont le score est passé est simplement hors de `ZCOUNT (maintenant
22
+ * +inf`. La purge ({@link SessionIndex.prune}) ne sert qu'à borner la mémoire.
23
+ *
24
+ * `<base>` = `<préfixe>~{idx}` : hors du motif `<préfixe>:*` que balaie le
25
+ * listing (un `GET` sur un ZSET rendrait `WRONGTYPE`), sous la même cloison
26
+ * d'application, et une seule étiquette de hachage — toutes les clés de l'index
27
+ * dans le même slot si le déploiement passe un jour en Redis Cluster.
28
+ *
29
+ * Chaque mutation est UN script Lua (atomique, un aller-retour), lancé en même
30
+ * temps que la commande de session : le chemin d'une requête ne paie pas un
31
+ * aller-retour de plus.
32
+ */
33
+ /** Ce que l'index demande au client : charger et exécuter un script. */
34
+ export interface IScriptClient {
35
+ scriptLoad(script: string): Promise<string>;
36
+ evalSha(sha: string, options: {
37
+ keys: string[];
38
+ arguments: string[];
39
+ }): Promise<unknown>;
40
+ }
41
+ /** Une session vue par l'index : à qui elle est, et quand elle expire. */
42
+ export interface IIndexedSession {
43
+ id: string;
44
+ /** Propriétaire ; `""` pour une session anonyme. */
45
+ user: string;
46
+ /** Expiration, en millisecondes depuis l'époque. */
47
+ expiresAt: number;
48
+ }
49
+ /** Ce que l'on compte — le même périmètre que le filtre de liste. */
50
+ export type IndexCount = "all" | "auth" | "users" | {
51
+ user: string;
52
+ };
53
+ /** Taille d'un lot de purge : borne le temps d'un script, qui bloque Redis. */
54
+ export declare const PRUNE_BATCH = 500;
55
+ /**
56
+ * Index des sessions d'UN store (une cloison d'application).
57
+ *
58
+ * Il ne lève jamais vers le chemin d'une requête : un échec d'indexation est
59
+ * rendu à l'appelant, qui le journalise et INVALIDE l'index ({@link invalidate})
60
+ * — le prochain comptage le reconstruit plutôt que de rendre un chiffre faux.
61
+ */
62
+ export declare class SessionIndex {
63
+ #private;
64
+ /** Base des clés : `<préfixe>~{idx}`. */
65
+ readonly base: string;
66
+ constructor(prefix: string);
67
+ /** Clé du marqueur « l'index couvre les sessions antérieures ». */
68
+ get builtKey(): string;
69
+ /** Clé du verrou de reconstruction (un seul pod reconstruit). */
70
+ get lockKey(): string;
71
+ /** Inscrit ou réinscrit une session. */
72
+ add(client: IScriptClient, s: IIndexedSession): Promise<void>;
73
+ /**
74
+ * Prolonge une session indexée.
75
+ *
76
+ * @returns `false` si la session n'est pas dans l'index (antérieure à lui, ou
77
+ * écrite par une version qui ne l'alimentait pas) : à l'appelant de l'y
78
+ * inscrire, lui seul sait lire son propriétaire.
79
+ */
80
+ touch(client: IScriptClient, id: string, expiresAt: number): Promise<boolean>;
81
+ /** Retire une session détruite. */
82
+ drop(client: IScriptClient, id: string): Promise<void>;
83
+ /** Purge les entrées expirées, par lots — borne la mémoire de l'index. */
84
+ prune(client: IScriptClient, now: number): Promise<number>;
85
+ /** Compte les entrées vivantes d'un ensemble de l'index. */
86
+ count(client: IScriptClient, what: IndexCount, now: number): Promise<number>;
87
+ }
88
+ /** Le client sait-il exécuter des scripts ? (un double de test, non.) */
89
+ export declare function supportsScripts(client: unknown): client is IScriptClient;
@@ -291,7 +291,7 @@ démarrage raté, la connexion existe, le client existe — mais il est fermé.
291
291
  Prenons une lecture de session. Elle traverse exactement quatre gestes :
292
292
 
293
293
  1. Le store résout le service **paresseusement**, au premier accès seulement :
294
- `RedisSessionStorage.#client()` (`SessionStorage.ts:89`) mémorise le service puis demande
294
+ `RedisSessionStorage.#client()` (`SessionStorage.ts:96`) mémorise le service puis demande
295
295
  `getClient("main")` à chaque appel. La résolution tardive est nécessaire — l'ordre de démarrage
296
296
  des modules n'est pas garanti, le store est construit avant que Redis soit prêt.
297
297
  2. `RedisService.getClient()` (`redis.ts:220`) rend le client de la connexion nommée, ou `null`.
@@ -341,13 +341,13 @@ vue d'ensemble ; les fiches détaillent les choix qui surprennent.
341
341
 
342
342
  ### `nf:sess:*` — la session, une chaîne et un TTL
343
343
 
344
- Une session est un blob JSON écrit d'un coup. `RedisSessionStorage.write()` (`SessionStorage.ts:106`)
344
+ Une session est un blob JSON écrit d'un coup. `RedisSessionStorage.write()` (`SessionStorage.ts:165`)
345
345
  pose **systématiquement** un `EX` : une clé de session sans TTL serait une session immortelle, donc un
346
346
  défaut de sécurité, pas une commodité.
347
347
 
348
348
  L'expiration par inactivité (« idle ») est donc portée par Redis lui-même. Deux conséquences
349
349
  directes : `gc()` (`SessionStorage.ts:151`) est un **no-op** assumé — aucun balayage, aucune requête
350
- de purge périodique — et `touch()` (`SessionStorage.ts:166`) se réduit à un `EXPIRE`, en O(1), **sans
350
+ de purge périodique — et `touch()` (`SessionStorage.ts:247`) se réduit à un `EXPIRE`, en O(1), **sans
351
351
  réécrire la valeur**. C'est le renouvellement le moins coûteux de tous les backends de session.
352
352
 
353
353
  L'expiration **absolue** (âge maximal, jamais prolongé) ne s'exprime pas par un TTL glissant. Elle est
@@ -357,22 +357,22 @@ survivre dans Redis jusqu'à la fin de son TTL d'inactivité, mais elle est refu
357
357
  ### `nf:tok:*` — les jetons, un HASH et quatre index
358
358
 
359
359
  Pourquoi un HASH plutôt qu'un blob JSON comme la session ? Parce qu'un jeton est **mis à jour en
360
- place** à chaque usage. `RedisTokenStore.markUsed()` (`RedisTokenStore.ts:487`) écrit un à trois
360
+ place** à chaque usage. `RedisTokenStore.markUsed()` (`RedisTokenStore.ts:533`) écrit un à trois
361
361
  champs (`lastUsedAt`, IP, agent) sans relire l'enregistrement, sans le réécrire, et **sans toucher au
362
362
  TTL**. Avec un blob, chaque appel d'API coûterait une lecture, une désérialisation, une réécriture —
363
363
  et remettrait en jeu la date d'expiration.
364
364
 
365
365
  Ce choix impose une précaution : `HSET` sur une clé absente la **recrée**, et une clé recréée n'a pas
366
- de TTL. Le store vérifie donc l'existence d'abord (`RedisTokenStore.ts:494`) et ne fait rien si
366
+ de TTL. Le store vérifie donc l'existence d'abord (`RedisTokenStore.ts:539`) et ne fait rien si
367
367
  l'identifiant est inconnu. Sans ce test, un jeton expiré ressusciterait, immortel, à sa prochaine
368
368
  utilisation.
369
369
 
370
370
  Les quatre index secondaires sont des SET (`subj`, `fam`) et des chaînes (`hash`, `revsub`). Aucun
371
371
  n'a de TTL : ils sont nettoyés **paresseusement**, quand une lecture tombe sur un membre dont
372
- l'enregistrement a expiré — voir `RedisTokenStore.findBySubject()` (`RedisTokenStore.ts:348`) et
373
- `RedisTokenStore.findByHash()` (`RedisTokenStore.ts:330`).
372
+ l'enregistrement a expiré — voir `RedisTokenStore.findBySubject()` (`RedisTokenStore.ts:405`) et
373
+ `RedisTokenStore.findByHash()` (`RedisTokenStore.ts:387`).
374
374
 
375
- La révocation combine les deux régimes. `RedisTokenStore.#applyRevoke()` (`RedisTokenStore.ts:550`)
375
+ La révocation combine les deux régimes. `RedisTokenStore.#applyRevoke()` (`RedisTokenStore.ts:596`)
376
376
  pose la date et la raison, puis — si le jeton n'avait **pas** d'expiration (cas d'un PAT) — lui donne
377
377
  un TTL égal à la durée de rétention. Un jeton révoqué reste donc consultable un temps, puis disparaît
378
378
  tout seul.
@@ -384,7 +384,7 @@ d'ailleurs pas de méthode de maintenance. Deux structures suffisent : un HASH p
384
384
  SET d'identifiants par utilisateur.
385
385
 
386
386
  Un point de conception mérite d'être connu : `countByUser()`
387
- (`RedisWebAuthnCredentialStore.ts:199`) utilise `SCARD`, en O(1), sans lire un seul HASH. Il peut donc
387
+ (`RedisWebAuthnCredentialStore.ts:220`) utilise `SCARD`, en O(1), sans lire un seul HASH. Il peut donc
388
388
  **sur-compter** les membres orphelins qu'une lecture n'a pas encore nettoyés. L'écart est assumé et
389
389
  orienté **fail-closed** : au pire un enrôlement supplémentaire est refusé, jamais un de trop accepté.
390
390
 
@@ -433,7 +433,7 @@ dérivent le même nom : il faut alors un namespace explicite.
433
433
  **L'anti-echo est structurel.** Redis renvoie à l'émetteur ce qu'il publie, puisque les connexions
434
434
  `publish` et `subscribe` appartiennent au même pod. Sans filtre, chaque message serait diffusé deux
435
435
  fois localement. Le tri d'entrée `RedisBackplane.#ingress()` compare donc l'identifiant d'origine à
436
- la réception (`RedisBackplane.ts:269`) et écarte les siens.
436
+ la réception (`RedisBackplane.ts:295`) et écarte les siens.
437
437
 
438
438
  **La livraison est au mieux, jamais garantie.** Le pub/sub Redis ne persiste ni ne rejoue : un pod
439
439
  déconnecté rate ce qui a été émis pendant sa coupure. Le contrat l'assume au lieu de simuler une
@@ -456,7 +456,7 @@ muet ne l'est pas. Voici ce que le code fait réellement, moment par moment.
456
456
  ### Moment 1 — Redis est absent au démarrage
457
457
 
458
458
  Le module est déclaré non critique (`index.ts:36`), et l'initialisation du service est **bornée dans
459
- le temps** : `Kernel.guardInitialize()` (`Kernel.ts:4043`) enveloppe l'appel dans un délai maximal de
459
+ le temps** : `Kernel.guardInitialize()` (`Kernel.ts:4336`) enveloppe l'appel dans un délai maximal de
460
460
  démarrage. Un `init()` qui pend ne gèle donc pas le boot ; l'échec est agrégé au rapport de démarrage,
461
461
  qui fait dire « démarrage DÉGRADÉ » au superviseur au lieu de mentir sur un état sain.
462
462
 
@@ -467,7 +467,7 @@ schéma vaut `0`, c'est-à-dire **illimité** : avec ce réglage, `connect()` ne
467
467
  tant que Redis ne répond pas.
468
468
 
469
469
  D'où un garde-fou spécifique au développement : `applyResilienceDefaults()`
470
- (`defineModuleConfig.ts:65`) borne les tentatives à un nombre fini **hors production**, quand
470
+ (`defineModuleConfig.ts:52`) borne les tentatives à un nombre fini **hors production**, quand
471
471
  l'application ne l'a pas fixé elle-même. Sans lui, démarrer sans Redis faisait pendre le boot au lieu
472
472
  d'échouer proprement.
473
473
 
@@ -523,9 +523,9 @@ L'ordre compte : les écouteurs sont retirés même si la fermeture échoue.
523
523
  | Idempotence : `redis` demandé, module absent | échec franc au démarrage | ✅ fail-loud |
524
524
 
525
525
  Les deux lignes rouges sont un **écart réel au principe** du framework : `RedisSessionStorage.write()`
526
- (`SessionStorage.ts:106`) rend la charge utile sans la persister et sans un mot. Sur la fenêtre
526
+ (`SessionStorage.ts:165`) rend la charge utile sans la persister et sans un mot. Sur la fenêtre
527
527
  étroite qu'il couvre — avant l'ouverture, après la fermeture — l'impact est faible ; le principe, lui,
528
- voudrait une trace. À l'inverse, `RedisSessionStorage.destroy()` (`SessionStorage.ts:143`) rend `true`
528
+ voudrait une trace. À l'inverse, `RedisSessionStorage.destroy()` (`SessionStorage.ts:216`) rend `true`
529
529
  sans connexion **délibérément** : l'appelant est une déconnexion, et lui répondre « échec » laisserait
530
530
  l'utilisateur croire qu'il est resté connecté.
531
531
 
@@ -542,13 +542,21 @@ même capacité réduite.
542
542
  | -------------------- | ----------------------------------------------------------------------------------- |
543
543
  | `limit` respectée | ✅ garantie par le curseur composite (voir plus bas) |
544
544
  | `cursor` / `hasNext` | ✅ le client boucle tant que `hasNext`, en repassant `nextCursor` |
545
- | `offset` | ❌ **jamais lu** — un client qui en envoie un est ignoré sans avertissement |
546
- | `total` | ❌ jamais rendu — et `countSessions` / `countTokens` / `countCredentials` = `-1` |
547
- | tri / ordre stable | ❌ aucun — `SCAN` ne garantit aucun ordre, et il n'y a pas d'index secondaire |
548
- | page pleine | ❌ une page peut contenir moins d'éléments que `limit` (le filtre porte sur le lot) |
549
-
550
- Le `-1` est un choix, pas un oubli : compter exactement exigerait un `SCAN` complet du keyspace. La
551
- valeur signifie « inconnu », et l'appelant doit l'afficher comme tel plutôt que l'inventer.
545
+ | `offset` | ❌ **refusé** au-delà de 0 — `400 PaginationModeError` ; la console suit le curseur |
546
+ | `total` | ❌ jamais rendu par la LISTE — mais les sessions se COMPTENT (voir ci-dessous) |
547
+ | tri / ordre stable | ❌ aucun — `SCAN` ne garantit aucun ordre |
548
+ | page pleine | ✅ les lots `SCAN` s'enchaînent jusqu'à remplir la page (`scanPage`), effort borné |
549
+
550
+ **Les sessions se comptent par un index** (`sessionIndex.ts`) : des ensembles triés dont le score
551
+ est la date d'EXPIRATION de chaque session — toutes, authentifiées, par utilisateur, et les
552
+ utilisateurs eux-mêmes (score = leur session la plus tardive). Chaque écriture, rafraîchissement ou
553
+ destruction de session y répercute son effet par un script Lua lancé dans le même aller-retour ;
554
+ compter devient un `ZCOUNT` sur ce qui expire après maintenant — une expiration n'a pas besoin
555
+ d'être observée pour être exclue. Les sessions antérieures à l'index sont reprises au premier
556
+ comptage, par un seul pod (verrou), une fois. Coût mesuré : environ +0,12 ms par écriture de session.
557
+
558
+ Les jetons et les passkeys, eux, ne comptent toujours pas : `countTokens` / `countCredentials` = `-1`,
559
+ qui signifie « inconnu » — l'appelant l'affiche comme tel plutôt que de l'inventer.
552
560
 
553
561
  Un mot sur ce que `SCAN` garantit vraiment : une clé présente du début à la fin du parcours est rendue
554
562
  **au moins** une fois — ce qui autorise les doublons, et laisse indéterminé le sort des clés créées ou
@@ -586,9 +594,9 @@ pire d'une page, transmettre une valeur arbitraire échouerait à coup sûr.
586
594
  ### Les vidages complets
587
595
 
588
596
  À côté de la pagination, deux méthodes déversent tout. `RedisSessionStorage.listAll()`
589
- (`SessionStorage.ts:181`) est **plafonnée** à un maximum de clés parcourues et journalise un
597
+ (`SessionStorage.ts:293`) est **plafonnée** à un maximum de clés parcourues et journalise un
590
598
  `WARNING` quand elle tronque — listing partiel signalé, jamais silencieux.
591
- `RedisTokenStore.listAll()` (`RedisTokenStore.ts:378`) l'est aussi, à `MAX_SCAN` clés, avec le même
599
+ `RedisTokenStore.listAll()` (`RedisTokenStore.ts:435`) l'est aussi, à `MAX_SCAN` clés, avec le même
592
600
  `WARNING` de listing partiel : à grande échelle, préférez la pagination ou le système de référence
593
601
  SQL pour la gouvernance.
594
602
 
@@ -610,7 +618,7 @@ Le module suit la règle de coût du framework : ne rien allouer « au cas où
610
618
  - **Trames de maintenance coupées** (`buildClientOptions.ts:58`) : zéro écouteur et zéro trame
611
619
  superflus sur un Redis OSS.
612
620
  - **Renouvellement de session en O(1)** : `EXPIRE` seul, sans réécrire la valeur
613
- (`redis/nodefony/src/SessionStorage.ts:161`). Sur une application authentifiée, c'est le geste le plus fréquent de tout
621
+ (`redis/nodefony/src/SessionStorage.ts:253`). Sur une application authentifiée, c'est le geste le plus fréquent de tout
614
622
  le store.
615
623
  - **Aucun balayage périodique** : le TTL natif remplace le ramasse-miettes applicatif que les backends
616
624
  SQL doivent programmer.
@@ -648,9 +656,9 @@ surfacé par les écrans transverses ci-dessus.
648
656
  | Le démarrage pend sans Redis | Tentatives illimitées : `connect()` ne rend pas la main | Fixer un maximum fini ; hors production c'est déjà fait (`defineModuleConfig.ts:65`) |
649
657
  | Deux applications se renvoient leurs messages temps réel | Le pub/sub ignore le numéro de base — cloisonnement inexistant | Poser un namespace de canal explicite (`RedisBackplane.ts:31`) |
650
658
  | Les mêmes messages sont diffusés deux fois localement | Anti-echo court-circuité (identifiant d'origine partagé) | Un identifiant d'origine distinct par pod (`RedisBackplane.ts:212`) |
651
- | Un jeton expiré « revient » et n'expire plus | `HSET` recrée une clé absente, sans TTL | Le test d'existence préalable (`RedisTokenStore.ts:494`) — ne pas le retirer |
659
+ | Un jeton expiré « revient » et n'expire plus | `HSET` recrée une clé absente, sans TTL | Le test d'existence préalable (`RedisTokenStore.ts:539`) — ne pas le retirer |
652
660
  | L'écran d'administration n'affiche aucun total | `countSessions` / `countTokens` rendent `-1` (comptage O(N) refusé) | Afficher « inconnu » ; ne jamais inventer un total |
653
- | Un `offset` envoyé n'a aucun effet | Le mode curseur ne lit que `cursor` (`SessionStorage.ts:196`) | Paginer par curseur, pas par décalage |
661
+ | Un `offset` envoyé n'a aucun effet | Le mode curseur ne lit que `cursor` (`SessionStorage.ts:308`) | Paginer par curseur, pas par décalage |
654
662
  | Des passkeys disparaissent | Politique d'éviction Redis (`allkeys-lru`) sur des clés **sans** TTL | `noeviction` + persistance sur l'instance qui porte les passkeys |
655
663
  | Une session survit à son âge maximal côté Redis | Le TTL glissant n'exprime pas l'absolu (`SessionStorage.ts:168`) | Comportement voulu — l'âge est refusé à la lecture, pas dans le stockage |
656
664
  | Une surcharge de connexion écrase l'hôte global | Un schéma partiel qui réapplique ses défauts clobberait la valeur globale | Ne poser que les champs voulus dans la surcharge — voir [Configuration](./configuration.md) |
@@ -686,7 +694,7 @@ cette prose. Ce qui doit être dit ici, c'est **ce qui est prouvé, et par quoi*
686
694
  > **Une suite verte ne prouve rien sans serveur Redis.** Les bancs d'intégration se **skippent**
687
695
  > quand l'infra manque, et un skip compte comme un succès : on peut lire « tout est vert » sur une
688
696
  > suite qui n'a rien exercé. La gate du module est déclarée une seule fois — `REDIS_GATE` dans
689
- > `vitest.gates.ts:339` — et la fin de run nomme la cible non exercée avec la commande exacte pour la
697
+ > `scripts/test/vitest/gates.ts:351` — et la fin de run nomme la cible non exercée avec la commande exacte pour la
690
698
  > satisfaire. **Les variables et la commande docker se lisent là, pas ici** : les recopier dans cette
691
699
  > page les condamnerait à diverger.
692
700
 
@@ -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
@@ -393,16 +393,28 @@ connections: {
393
393
 
394
394
  ### Les cinq variables lues
395
395
 
396
- Toutes sont appliquées **après** la validation, par `applyEnvOverrides()`
397
- (`defineModuleConfig.ts:23`).
398
-
399
- | Variable | Ce qu'elle vise | Comportement |
400
- | ------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------- |
401
- | `NF_REDIS_URL` (ou `REDIS_URL`) | `url` | Résolue par `resolveInfra()` (`infra.ts:134`) ; `NF_REDIS_URL` l'emporte sur l'alias de plateforme. |
402
- | `NF_REDIS_HOST` | `globalOptions.socket.host` | Posée telle quelle, sans validation supplémentaire. |
403
- | `NF_REDIS_PORT` | `globalOptions.socket.port` | **Ignorée en silence** si ce n'est pas un entier de `1` à `65535`. |
404
- | `NF_REDIS_PASSWORD` | `globalOptions.password` | Le seul chemin recommandé pour le secret : jamais dans un fichier versionné. |
405
- | `NF_REDIS_KEY_NAMESPACE` | `keyNamespace` | Prioritaire sur la config ; cloison de déploiement. |
396
+ Deux mécanismes, et un seul endroit chacun :
397
+
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).
406
418
 
407
419
  `REDIS_URL` est accepté comme **alias de plateforme** parce que c'est le nom que posent la plupart des
408
420
  hébergeurs. Quand les deux existent, la variable préfixée gagne — le préfixe `NF_` sert précisément à
@@ -410,20 +422,18 @@ reprendre la main sur une variable imposée par l'environnement d'hébergement.
410
422
 
411
423
  ### L'ordre, prouvé par le code
412
424
 
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
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
419
430
  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.
431
+ 4. `applyEnvOverrides()` (`defineModuleConfig.ts:23`) — l'URL d'infrastructure écrase `url`.
432
+ 5. `Object.freeze` — plus rien ne bouge.
422
433
 
423
434
  D'où la règle, dans cet ordre croissant d'autorité : **défauts du schéma → configuration de
424
435
  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é).
436
+ (`config.test.ts` : les noms courts déclarés, posés puis validés, et le port invalide REFUSÉ).
427
437
 
428
438
  > [!IMPORTANT]
429
439
  > L'environnement gagne **même contre une valeur explicite de l'application**. Une `url` écrite dans
@@ -495,8 +505,8 @@ définitivement.
495
505
  **Hors production, ce réglage fait pendre le démarrage.** Avec des tentatives illimitées, la première
496
506
  ouverture ne rend jamais la main tant que Redis ne répond pas ; la file d'attente hors ligne du client
497
507
  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,
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,
500
510
  l'application ne s'est pas prononcée.
501
511
 
502
512
  | `NODE_ENV` | L'application fixe `maxRetries` ? | Valeur effective |
@@ -535,7 +545,7 @@ abonné ne peut plus émettre de commandes normales. Une connexion unique rendra
535
545
  stockage mutuellement exclusifs.
536
546
 
537
547
  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
548
+ `loadModulesFromManifest()` (`Kernel.ts:1794`) fusionne la configuration de `use()` sous les défauts
539
549
  déjà matérialisés du module — donc les trois connexions d'usine restent en place :
540
550
 
541
551
  ```ts ignore
@@ -699,15 +709,15 @@ faire avant une mise en production.
699
709
  | --- | --- | --- |
700
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 |
701
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 |
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 |
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 |
703
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 |
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 |
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 |
705
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 |
706
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 |
707
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 |
708
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 |
709
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 |
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 |
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.2",
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",
@@ -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.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.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.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",