@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.
- package/README.md +13 -8
- package/dist/_virtual/{_@oxc-project_runtime@0.151.0 → _@oxc-project_runtime@0.153.0}/helpers/esm/decorate.js +1 -1
- package/dist/_virtual/{_@oxc-project_runtime@0.151.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 +77 -79
- package/docs/configuration.md +44 -34
- package/docs/index.md +1 -1
- package/package.json +16 -15
|
@@ -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
|
@@ -191,7 +191,8 @@ class RedisDiagnosticController extends Controller {
|
|
|
191
191
|
const main = redis?.getConnection("main");
|
|
192
192
|
const client = redis?.getClient("main");
|
|
193
193
|
|
|
194
|
-
|
|
194
|
+
// Le préfixe porte la cloison de l'application : `nf:<app>:sess` (`keyPrefix()`).
|
|
195
|
+
const cle = `${redis?.keyPrefix("nf:sess")}:${session.id}`;
|
|
195
196
|
// -2 = clé absente, -1 = clé sans TTL (anomalie ici), n > 0 = secondes restantes.
|
|
196
197
|
const ttl = client && main?.connected ? await client.ttl(cle) : -2;
|
|
197
198
|
|
|
@@ -223,11 +224,11 @@ Puis, côté requête :
|
|
|
223
224
|
```bash
|
|
224
225
|
curl -s -c cookies.txt http://127.0.0.1:5151/diagnostic/redis/session
|
|
225
226
|
# {"connexions":["main","publish","subscribe"],"mainConnectee":true,
|
|
226
|
-
# "cle":"nf:sess:9f2c…","ttlSecondes":1800}
|
|
227
|
+
# "cle":"nf:mon-app:sess:9f2c…","ttlSecondes":1800}
|
|
227
228
|
|
|
228
229
|
# La même clé, vue du serveur — le TTL est bien porté par Redis lui-même.
|
|
229
|
-
redis-cli TTL nf:sess:9f2c… # (integer) 1800
|
|
230
|
-
redis-cli TYPE nf:sess:9f2c… # string
|
|
230
|
+
redis-cli TTL nf:mon-app:sess:9f2c… # (integer) 1800
|
|
231
|
+
redis-cli TYPE nf:mon-app:sess:9f2c… # string
|
|
231
232
|
```
|
|
232
233
|
|
|
233
234
|
Rejoue la requête après quelques secondes : le TTL est **remonté à 1800**. C'est le timeout glissant,
|
|
@@ -290,7 +291,7 @@ démarrage raté, la connexion existe, le client existe — mais il est fermé.
|
|
|
290
291
|
Prenons une lecture de session. Elle traverse exactement quatre gestes :
|
|
291
292
|
|
|
292
293
|
1. Le store résout le service **paresseusement**, au premier accès seulement :
|
|
293
|
-
`RedisSessionStorage.#client()` (`SessionStorage.ts:
|
|
294
|
+
`RedisSessionStorage.#client()` (`SessionStorage.ts:96`) mémorise le service puis demande
|
|
294
295
|
`getClient("main")` à chaque appel. La résolution tardive est nécessaire — l'ordre de démarrage
|
|
295
296
|
des modules n'est pas garanti, le store est construit avant que Redis soit prêt.
|
|
296
297
|
2. `RedisService.getClient()` (`redis.ts:220`) rend le client de la connexion nommée, ou `null`.
|
|
@@ -319,6 +320,11 @@ exclusifs. Le module tranche par la topologie : `main` pour les commandes, `publ
|
|
|
319
320
|
Le module n'écrit rien. Ce qui suit appartient aux quatre stores et au backplane. Le tableau donne la
|
|
320
321
|
vue d'ensemble ; les fiches détaillent les choix qui surprennent.
|
|
321
322
|
|
|
323
|
+
> [!NOTE]
|
|
324
|
+
> Les préfixes sont donnés **sans la cloison** de l'application, pour la lisibilité. Une application
|
|
325
|
+
> nommée les reçoit cloisonnés : `nf:sess` devient `nf:<application>:sess` (`RedisService.keyPrefix()`,
|
|
326
|
+
> `redis.ts:105`), la cloison venant de `keyNamespace` ou, à défaut, du nom du projet.
|
|
327
|
+
|
|
322
328
|
| Clé | Structure | Durée de vie | Écrit par |
|
|
323
329
|
| --------------------------- | -------------- | --------------------------------------------- | ----------------------------------------------- |
|
|
324
330
|
| `nf:sess:<id>` | STRING (JSON) | TTL = idle, reposé à chaque écriture/touch | `RedisSessionStorage` |
|
|
@@ -335,13 +341,13 @@ vue d'ensemble ; les fiches détaillent les choix qui surprennent.
|
|
|
335
341
|
|
|
336
342
|
### `nf:sess:*` — la session, une chaîne et un TTL
|
|
337
343
|
|
|
338
|
-
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`)
|
|
339
345
|
pose **systématiquement** un `EX` : une clé de session sans TTL serait une session immortelle, donc un
|
|
340
346
|
défaut de sécurité, pas une commodité.
|
|
341
347
|
|
|
342
348
|
L'expiration par inactivité (« idle ») est donc portée par Redis lui-même. Deux conséquences
|
|
343
349
|
directes : `gc()` (`SessionStorage.ts:151`) est un **no-op** assumé — aucun balayage, aucune requête
|
|
344
|
-
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
|
|
345
351
|
réécrire la valeur**. C'est le renouvellement le moins coûteux de tous les backends de session.
|
|
346
352
|
|
|
347
353
|
L'expiration **absolue** (âge maximal, jamais prolongé) ne s'exprime pas par un TTL glissant. Elle est
|
|
@@ -351,22 +357,22 @@ survivre dans Redis jusqu'à la fin de son TTL d'inactivité, mais elle est refu
|
|
|
351
357
|
### `nf:tok:*` — les jetons, un HASH et quatre index
|
|
352
358
|
|
|
353
359
|
Pourquoi un HASH plutôt qu'un blob JSON comme la session ? Parce qu'un jeton est **mis à jour en
|
|
354
|
-
place** à chaque usage. `RedisTokenStore.markUsed()` (`RedisTokenStore.ts:
|
|
360
|
+
place** à chaque usage. `RedisTokenStore.markUsed()` (`RedisTokenStore.ts:533`) écrit un à trois
|
|
355
361
|
champs (`lastUsedAt`, IP, agent) sans relire l'enregistrement, sans le réécrire, et **sans toucher au
|
|
356
362
|
TTL**. Avec un blob, chaque appel d'API coûterait une lecture, une désérialisation, une réécriture —
|
|
357
363
|
et remettrait en jeu la date d'expiration.
|
|
358
364
|
|
|
359
365
|
Ce choix impose une précaution : `HSET` sur une clé absente la **recrée**, et une clé recréée n'a pas
|
|
360
|
-
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
|
|
361
367
|
l'identifiant est inconnu. Sans ce test, un jeton expiré ressusciterait, immortel, à sa prochaine
|
|
362
368
|
utilisation.
|
|
363
369
|
|
|
364
370
|
Les quatre index secondaires sont des SET (`subj`, `fam`) et des chaînes (`hash`, `revsub`). Aucun
|
|
365
371
|
n'a de TTL : ils sont nettoyés **paresseusement**, quand une lecture tombe sur un membre dont
|
|
366
|
-
l'enregistrement a expiré — voir `RedisTokenStore.findBySubject()` (`RedisTokenStore.ts:
|
|
367
|
-
`RedisTokenStore.findByHash()` (`RedisTokenStore.ts:
|
|
372
|
+
l'enregistrement a expiré — voir `RedisTokenStore.findBySubject()` (`RedisTokenStore.ts:405`) et
|
|
373
|
+
`RedisTokenStore.findByHash()` (`RedisTokenStore.ts:387`).
|
|
368
374
|
|
|
369
|
-
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`)
|
|
370
376
|
pose la date et la raison, puis — si le jeton n'avait **pas** d'expiration (cas d'un PAT) — lui donne
|
|
371
377
|
un TTL égal à la durée de rétention. Un jeton révoqué reste donc consultable un temps, puis disparaît
|
|
372
378
|
tout seul.
|
|
@@ -378,7 +384,7 @@ d'ailleurs pas de méthode de maintenance. Deux structures suffisent : un HASH p
|
|
|
378
384
|
SET d'identifiants par utilisateur.
|
|
379
385
|
|
|
380
386
|
Un point de conception mérite d'être connu : `countByUser()`
|
|
381
|
-
(`RedisWebAuthnCredentialStore.ts:
|
|
387
|
+
(`RedisWebAuthnCredentialStore.ts:220`) utilise `SCARD`, en O(1), sans lire un seul HASH. Il peut donc
|
|
382
388
|
**sur-compter** les membres orphelins qu'une lecture n'a pas encore nettoyés. L'écart est assumé et
|
|
383
389
|
orienté **fail-closed** : au pire un enrôlement supplémentaire est refusé, jamais un de trop accepté.
|
|
384
390
|
|
|
@@ -427,7 +433,7 @@ dérivent le même nom : il faut alors un namespace explicite.
|
|
|
427
433
|
**L'anti-echo est structurel.** Redis renvoie à l'émetteur ce qu'il publie, puisque les connexions
|
|
428
434
|
`publish` et `subscribe` appartiennent au même pod. Sans filtre, chaque message serait diffusé deux
|
|
429
435
|
fois localement. Le tri d'entrée `RedisBackplane.#ingress()` compare donc l'identifiant d'origine à
|
|
430
|
-
la réception (`RedisBackplane.ts:
|
|
436
|
+
la réception (`RedisBackplane.ts:295`) et écarte les siens.
|
|
431
437
|
|
|
432
438
|
**La livraison est au mieux, jamais garantie.** Le pub/sub Redis ne persiste ni ne rejoue : un pod
|
|
433
439
|
déconnecté rate ce qui a été émis pendant sa coupure. Le contrat l'assume au lieu de simuler une
|
|
@@ -450,7 +456,7 @@ muet ne l'est pas. Voici ce que le code fait réellement, moment par moment.
|
|
|
450
456
|
### Moment 1 — Redis est absent au démarrage
|
|
451
457
|
|
|
452
458
|
Le module est déclaré non critique (`index.ts:36`), et l'initialisation du service est **bornée dans
|
|
453
|
-
le temps** : `Kernel.guardInitialize()` (`Kernel.ts:
|
|
459
|
+
le temps** : `Kernel.guardInitialize()` (`Kernel.ts:4336`) enveloppe l'appel dans un délai maximal de
|
|
454
460
|
démarrage. Un `init()` qui pend ne gèle donc pas le boot ; l'échec est agrégé au rapport de démarrage,
|
|
455
461
|
qui fait dire « démarrage DÉGRADÉ » au superviseur au lieu de mentir sur un état sain.
|
|
456
462
|
|
|
@@ -461,7 +467,7 @@ schéma vaut `0`, c'est-à-dire **illimité** : avec ce réglage, `connect()` ne
|
|
|
461
467
|
tant que Redis ne répond pas.
|
|
462
468
|
|
|
463
469
|
D'où un garde-fou spécifique au développement : `applyResilienceDefaults()`
|
|
464
|
-
(`defineModuleConfig.ts:
|
|
470
|
+
(`defineModuleConfig.ts:52`) borne les tentatives à un nombre fini **hors production**, quand
|
|
465
471
|
l'application ne l'a pas fixé elle-même. Sans lui, démarrer sans Redis faisait pendre le boot au lieu
|
|
466
472
|
d'échouer proprement.
|
|
467
473
|
|
|
@@ -479,29 +485,18 @@ partent ; si la stratégie abandonne, elles sont rejetées.
|
|
|
479
485
|
`Connection.connected` repasse à `false` — mais **`Connection.client` reste affecté**. C'est le point
|
|
480
486
|
suivant.
|
|
481
487
|
|
|
482
|
-
### Moment 3 — le garde `if (!client)
|
|
483
|
-
|
|
484
|
-
Tous les stores commencent par le même geste : demander le client, et se replier s'il vaut `null`. Ce
|
|
485
|
-
garde ne se déclenche que dans deux situations exactes :
|
|
486
|
-
|
|
487
|
-
- **avant** l'initialisation du service — la carte des connexions vaut encore `null` ;
|
|
488
|
-
- **après** `RedisService.closeConnections()` (`redis.ts:243`), qui remet la carte à `null`.
|
|
488
|
+
### Moment 3 — le garde `if (!client)`, et ce qu'il couvre
|
|
489
489
|
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
avant
|
|
493
|
-
|
|
490
|
+
Tous les stores commencent par le même geste : demander le client, et se replier s'il vaut `null`.
|
|
491
|
+
`RedisService.getClient()` (`redis.ts:218`) rend `null` dès que le socket **n'est pas ouvert** :
|
|
492
|
+
avant l'initialisation, après `RedisService.closeConnections()`, mais aussi après un `connect()` raté
|
|
493
|
+
— la connexion reste inscrite dans la carte avec un client jamais ouvert, et c'est l'ouverture
|
|
494
|
+
(`isOpen`), pas la présence, qui est testée. Pendant une reconnexion, en revanche, le socket est
|
|
495
|
+
ouvert : les commandes attendent dans la file hors ligne de la bibliothèque.
|
|
494
496
|
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
> [!CAUTION]
|
|
500
|
-
> Le repli documenté par les stores (« la connexion n'est pas ou plus ouverte → no-op ») décrit le
|
|
501
|
-
> comportement du démarrage et de l'arrêt, **pas celui d'un incident**. Un Redis injoignable au
|
|
502
|
-
> démarrage laisse une connexion fermée dans la carte : les stores ne se replient pas, ils propagent
|
|
503
|
-
> l'erreur du client. Tester votre application « Redis éteint » consiste donc à l'éteindre **après**
|
|
504
|
-
> le démarrage _et_ à la démarrer sans lui — les deux chemins ne sont pas les mêmes.
|
|
497
|
+
L'indisponibilité est **journalisée à la transition** : un `WARNING` « connexion indisponible » à la
|
|
498
|
+
première bascule (pas un par appel), puis un `INFO` « rétablie » quand la connexion revient.
|
|
499
|
+
`client-availability.test.ts` verrouille les trois comportements.
|
|
505
500
|
|
|
506
501
|
### Moment 4 — l'arrêt
|
|
507
502
|
|
|
@@ -521,16 +516,16 @@ L'ordre compte : les écouteurs sont retirés même si la fermeture échoue.
|
|
|
521
516
|
| Démarrage du module en échec | non critique → agrégé au rapport, « démarrage DÉGRADÉ » | ✅ superviseur |
|
|
522
517
|
| Perte de connexion en cours de vie | `ERROR` / `WARNING` / `INFO` + événements réémis | ✅ journal + événements |
|
|
523
518
|
| Commande pendant la reconnexion | file d'attente hors ligne, puis envoi ou rejet | ✅ l'appelant reçoit le rejet |
|
|
524
|
-
| Commande sur une connexion jamais ouverte | `
|
|
525
|
-
| Écriture de session, client `null` |
|
|
526
|
-
| Écriture de jeton / passkey, client `null` |
|
|
519
|
+
| Commande sur une connexion jamais ouverte | `getClient` → `null`, repli du store | ✅ `WARNING` à la transition |
|
|
520
|
+
| Écriture de session, client `null` | no-op — la session n'est pas persistée | ✅ annoncé au journal (transition) |
|
|
521
|
+
| Écriture de jeton / passkey, client `null` | no-op | ✅ annoncé au journal (transition) |
|
|
527
522
|
| Backplane : module ou connexions absents | `WARNING` nommant la cause, hub laissé en local | ✅ modèle du genre |
|
|
528
523
|
| Idempotence : `redis` demandé, module absent | échec franc au démarrage | ✅ fail-loud |
|
|
529
524
|
|
|
530
525
|
Les deux lignes rouges sont un **écart réel au principe** du framework : `RedisSessionStorage.write()`
|
|
531
|
-
(`SessionStorage.ts:
|
|
526
|
+
(`SessionStorage.ts:165`) rend la charge utile sans la persister et sans un mot. Sur la fenêtre
|
|
532
527
|
étroite qu'il couvre — avant l'ouverture, après la fermeture — l'impact est faible ; le principe, lui,
|
|
533
|
-
voudrait une trace. À l'inverse, `RedisSessionStorage.destroy()` (`SessionStorage.ts:
|
|
528
|
+
voudrait une trace. À l'inverse, `RedisSessionStorage.destroy()` (`SessionStorage.ts:216`) rend `true`
|
|
534
529
|
sans connexion **délibérément** : l'appelant est une déconnexion, et lui répondre « échec » laisserait
|
|
535
530
|
l'utilisateur croire qu'il est resté connecté.
|
|
536
531
|
|
|
@@ -547,13 +542,21 @@ même capacité réduite.
|
|
|
547
542
|
| -------------------- | ----------------------------------------------------------------------------------- |
|
|
548
543
|
| `limit` respectée | ✅ garantie par le curseur composite (voir plus bas) |
|
|
549
544
|
| `cursor` / `hasNext` | ✅ le client boucle tant que `hasNext`, en repassant `nextCursor` |
|
|
550
|
-
| `offset` | ❌ **
|
|
551
|
-
| `total` | ❌ jamais rendu —
|
|
552
|
-
| tri / ordre stable | ❌ aucun — `SCAN` ne garantit aucun ordre
|
|
553
|
-
| page pleine |
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
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.
|
|
557
560
|
|
|
558
561
|
Un mot sur ce que `SCAN` garantit vraiment : une clé présente du début à la fin du parcours est rendue
|
|
559
562
|
**au moins** une fois — ce qui autorise les doublons, et laisse indéterminé le sort des clés créées ou
|
|
@@ -567,7 +570,7 @@ Redis rend **toutes** les clés d'un coup, quel que soit le `COUNT` demandé. Un
|
|
|
567
570
|
alors la `limit` et violerait le contrat.
|
|
568
571
|
|
|
569
572
|
D'où un curseur de la forme `"<déjà consommé>:<curseur Redis>"`, encodé par `encodeCursor()`
|
|
570
|
-
(`
|
|
573
|
+
(`scanCursor.ts`). Quand un lot contient plus d'éléments que la page, le store n'en rend que
|
|
571
574
|
`limit`, mémorise combien de clés du lot ont été consommées, et la page suivante **rejoue le même
|
|
572
575
|
`SCAN`** pour reprendre à la bonne position. Le coût est un re-parcours du lot courant, payé
|
|
573
576
|
uniquement sur un chemin d'administration. Les trois stores partagent ce mécanisme, à l'identique.
|
|
@@ -579,26 +582,23 @@ uniquement sur un chemin d'administration. Les trois stores partagent ce mécani
|
|
|
579
582
|
> serveur qui a révélé le débordement. Sans `NF_REDIS_TEST_URL`, les bancs de pagination passent au vert
|
|
580
583
|
> **sans avoir testé la seule chose que ce code résout**.
|
|
581
584
|
|
|
582
|
-
###
|
|
585
|
+
### Les curseurs hostiles
|
|
583
586
|
|
|
584
587
|
Le curseur arrive de l'extérieur (chaîne de requête d'un écran d'administration, client qui rejoue une
|
|
585
588
|
page) : il n'est pas digne de confiance. Un curseur `SCAN` valide est toujours une suite de chiffres.
|
|
586
589
|
|
|
587
|
-
|
|
588
|
-
sur `"0"` sinon — repartir du début est faux au
|
|
589
|
-
|
|
590
|
-
(`RedisWebAuthnCredentialStore.ts:31`) ne font **pas** cette validation : ils transmettent le curseur
|
|
591
|
-
tel quel, et Redis rejette la commande. Un paramètre malformé y transforme une simple consultation en
|
|
592
|
-
erreur.
|
|
590
|
+
Les trois stores s'en protègent par la même règle : `decodeCursor()` puis `scanOrZero()`
|
|
591
|
+
(`scanCursor.ts:68`) imposent le format et retombent sur `"0"` sinon — repartir du début est faux au
|
|
592
|
+
pire d'une page, transmettre une valeur arbitraire échouerait à coup sûr.
|
|
593
593
|
|
|
594
594
|
### Les vidages complets
|
|
595
595
|
|
|
596
596
|
À côté de la pagination, deux méthodes déversent tout. `RedisSessionStorage.listAll()`
|
|
597
|
-
(`SessionStorage.ts:
|
|
597
|
+
(`SessionStorage.ts:293`) est **plafonnée** à un maximum de clés parcourues et journalise un
|
|
598
598
|
`WARNING` quand elle tronque — listing partiel signalé, jamais silencieux.
|
|
599
|
-
`RedisTokenStore.listAll()` (`RedisTokenStore.ts:
|
|
600
|
-
|
|
601
|
-
la gouvernance.
|
|
599
|
+
`RedisTokenStore.listAll()` (`RedisTokenStore.ts:435`) l'est aussi, à `MAX_SCAN` clés, avec le même
|
|
600
|
+
`WARNING` de listing partiel : à grande échelle, préférez la pagination ou le système de référence
|
|
601
|
+
SQL pour la gouvernance.
|
|
602
602
|
|
|
603
603
|
Redaction : la page de sessions vide explicitement les sacs de données métier avant de sortir
|
|
604
604
|
(`SessionStorage.ts:296`) — un enregistrement d'administration ne transporte jamais le contenu
|
|
@@ -618,7 +618,7 @@ Le module suit la règle de coût du framework : ne rien allouer « au cas où
|
|
|
618
618
|
- **Trames de maintenance coupées** (`buildClientOptions.ts:58`) : zéro écouteur et zéro trame
|
|
619
619
|
superflus sur un Redis OSS.
|
|
620
620
|
- **Renouvellement de session en O(1)** : `EXPIRE` seul, sans réécrire la valeur
|
|
621
|
-
(`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
|
|
622
622
|
le store.
|
|
623
623
|
- **Aucun balayage périodique** : le TTL natif remplace le ramasse-miettes applicatif que les backends
|
|
624
624
|
SQL doivent programmer.
|
|
@@ -651,19 +651,17 @@ surfacé par les écrans transverses ci-dessus.
|
|
|
651
651
|
|
|
652
652
|
## ⚠️ Pièges (symptôme → cause → correction)
|
|
653
653
|
|
|
654
|
-
| Symptôme
|
|
655
|
-
|
|
|
656
|
-
|
|
|
657
|
-
|
|
|
658
|
-
|
|
|
659
|
-
|
|
|
660
|
-
|
|
|
661
|
-
|
|
|
662
|
-
|
|
|
663
|
-
|
|
|
664
|
-
|
|
|
665
|
-
| 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 |
|
|
666
|
-
| 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) |
|
|
654
|
+
| Symptôme | Cause (dans le code) | Correction |
|
|
655
|
+
| -------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
|
|
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`) |
|
|
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`) |
|
|
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`) |
|
|
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 |
|
|
660
|
+
| L'écran d'administration n'affiche aucun total | `countSessions` / `countTokens` rendent `-1` (comptage O(N) refusé) | Afficher « inconnu » ; ne jamais inventer un total |
|
|
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 |
|
|
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 |
|
|
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 |
|
|
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) |
|
|
667
665
|
|
|
668
666
|
## 🧪 Tests & couverture
|
|
669
667
|
|
|
@@ -680,9 +678,9 @@ cette prose. Ce qui doit être dit ici, c'est **ce qui est prouvé, et par quoi*
|
|
|
680
678
|
|
|
681
679
|
**Ce qui manque, et qu'il faut savoir :**
|
|
682
680
|
|
|
683
|
-
- **
|
|
684
|
-
client
|
|
685
|
-
|
|
681
|
+
- **La perte de connexion en cours de vie n'est exercée que par son effet sur `getClient`**
|
|
682
|
+
(`client-availability.test.ts`) : une coupure réelle d'un serveur Redis pendant le trafic n'a pas
|
|
683
|
+
de banc dédié.
|
|
686
684
|
- **La branche de reprise du curseur composite n'est atteinte qu'avec un serveur réel** (voir plus
|
|
687
685
|
haut) : le double ne déborde jamais.
|
|
688
686
|
- **Pas de banc de charge ni de test de mémoire dédiés** dans ce module — voir le skill
|
|
@@ -696,7 +694,7 @@ cette prose. Ce qui doit être dit ici, c'est **ce qui est prouvé, et par quoi*
|
|
|
696
694
|
> **Une suite verte ne prouve rien sans serveur Redis.** Les bancs d'intégration se **skippent**
|
|
697
695
|
> quand l'infra manque, et un skip compte comme un succès : on peut lire « tout est vert » sur une
|
|
698
696
|
> suite qui n'a rien exercé. La gate du module est déclarée une seule fois — `REDIS_GATE` dans
|
|
699
|
-
> `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
|
|
700
698
|
> satisfaire. **Les variables et la commande docker se lisent là, pas ici** : les recopier dans cette
|
|
701
699
|
> page les condamnerait à diverger.
|
|
702
700
|
|