@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.
- package/README.md +5 -1
- package/dist/_virtual/{_@oxc-project_runtime@0.152.0 → _@oxc-project_runtime@0.153.0}/helpers/esm/decorate.js +1 -1
- package/dist/_virtual/{_@oxc-project_runtime@0.152.0 → _@oxc-project_runtime@0.153.0}/helpers/esm/decorateMetadata.js +1 -1
- package/dist/index.js +2 -2
- package/dist/nodefony/config/config.js +7 -3
- package/dist/nodefony/config/configSchema.js +19 -0
- package/dist/nodefony/config/defineModuleConfig.js +13 -22
- package/dist/nodefony/src/RedisTokenStore.js +56 -25
- package/dist/nodefony/src/RedisWebAuthnCredentialStore.js +26 -19
- package/dist/nodefony/src/SessionStorage.js +201 -55
- package/dist/nodefony/src/scanCursor.js +54 -1
- package/dist/nodefony/src/sessionIndex.js +185 -0
- package/dist/types/nodefony/config/configSchema.d.ts +12 -0
- package/dist/types/nodefony/src/SessionStorage.d.ts +16 -14
- package/dist/types/nodefony/src/scanCursor.d.ts +32 -0
- package/dist/types/nodefony/src/sessionIndex.d.ts +89 -0
- package/docs/architecture.md +35 -27
- package/docs/configuration.md +40 -30
- package/docs/index.md +1 -1
- package/package.json +15 -14
|
@@ -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;
|
package/docs/architecture.md
CHANGED
|
@@ -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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
373
|
-
`RedisTokenStore.findByHash()` (`RedisTokenStore.ts:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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` | ❌ **
|
|
546
|
-
| `total` | ❌ jamais rendu —
|
|
547
|
-
| tri / ordre stable | ❌ aucun — `SCAN` ne garantit aucun ordre
|
|
548
|
-
| page pleine |
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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
|
|
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
|
|
package/docs/configuration.md
CHANGED
|
@@ -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:
|
|
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:
|
|
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:
|
|
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
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
|
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
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
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
|
-
|
|
421
|
-
|
|
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
|
|
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:
|
|
499
|
-
à `DEV_DEFAULT_MAX_RETRIES` (`defineModuleConfig.ts:
|
|
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:
|
|
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`
|
|
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:
|
|
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:
|
|
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
|
|
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
|
|
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.
|
|
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.
|
|
55
|
-
"@nodefony/http": "^10.0.0-beta.
|
|
56
|
-
"@nodefony/security": "^10.0.0-beta.
|
|
57
|
-
"@types/node": "26.6.
|
|
58
|
-
"@vitest/coverage-v8": "5.0.
|
|
59
|
-
"nodefony": "^10.0.0-beta.
|
|
60
|
-
"vitest": "5.0.
|
|
55
|
+
"@nodefony/framework": "^10.0.0-beta.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.
|
|
64
|
-
"@nodefony/http": "^10.0.0-beta.
|
|
65
|
-
"@nodefony/security": "^10.0.0-beta.
|
|
66
|
-
"nodefony": "^10.0.0-beta.
|
|
67
|
-
"zod": "^4.6.
|
|
64
|
+
"@nodefony/framework": "^10.0.0-beta.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",
|