@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.
@@ -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;
@@ -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
- const cle = `nf:sess:${session.id}`;
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:89`) mémorise le service puis demande
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:106`)
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: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
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:487`) écrit un à trois
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: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
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:348`) et
367
- `RedisTokenStore.findByHash()` (`RedisTokenStore.ts:330`).
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:550`)
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: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
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:269`) et écarte les siens.
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: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
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:65`) borne les tentatives à un nombre fini **hors production**, quand
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)` et ce qu'il ne couvre pas
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
- Il ne se déclenche **pas** après un `connect()` raté. Puisque la connexion est inscrite dans
491
- `#connections` avant d'être ouverte (`redis.ts:76`) et que `Connection.create()` affecte son client
492
- avant de le connecter (`Connection.ts:86`), `getClient("main")` rend alors un client **non nul et
493
- fermé**. La commande part donc, et la bibliothèque la rejette :
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
- ClientClosedError: The client is closed
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 | `ClientClosedError` propagé jusqu'à l'appelant | ✅ bruyant (mais pas le repli annoncé) |
525
- | Écriture de session, client `null` | **no-op muet** — la session n'est pas persistée, rien n'est journalisé | ❌ **silencieux** |
526
- | Écriture de jeton / passkey, client `null` | **no-op muet** | ❌ **silencieux** |
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: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
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:143`) rend `true`
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` | ❌ **jamais lu** — un client qui en envoie un est ignoré sans avertissement |
551
- | `total` | ❌ jamais rendu — et `countSessions` / `countTokens` / `countCredentials` = `-1` |
552
- | tri / ordre stable | ❌ aucun — `SCAN` ne garantit aucun ordre, et il n'y a pas d'index secondaire |
553
- | page pleine | ❌ une page peut contenir moins d'éléments que `limit` (le filtre porte sur le lot) |
554
-
555
- Le `-1` est un choix, pas un oubli : compter exactement exigerait un `SCAN` complet du keyspace. La
556
- 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.
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
- (`SessionStorage.ts:33`). Quand un lot contient plus d'éléments que la page, le store n'en rend que
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
- ### Une asymétrie sur les curseurs hostiles
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
- Le store de session s'en protège : `scanOrZero()` (`scanCursor.ts:68`) impose le format et retombe
588
- sur `"0"` sinon — repartir du début est faux au pire d'une page, transmettre une valeur arbitraire
589
- échoue à coup sûr. Les stores de jetons (`RedisTokenStore.ts:35`) et de passkeys
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: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
598
598
  `WARNING` quand elle tronque — listing partiel signalé, jamais silencieux.
599
- `RedisTokenStore.listAll()` (`RedisTokenStore.ts:378`), en revanche, boucle jusqu'à la fin du
600
- keyspace sans plafond : à grande échelle, préférez la pagination ou le système de référence SQL pour
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: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
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 | Cause (dans le code) | Correction |
655
- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
656
- | `ClientClosedError` alors que le store « dégrade en douceur » | Connexion posée dans `#connections` avant ouverture (`redis.ts:75`) → client non nul mais fermé | Traiter Redis comme faillible côté appelant ; surveiller le journal de démarrage |
657
- | 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`) |
658
- | 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`) |
659
- | 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`) |
660
- | 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 |
661
- | `?cursor=…` fait échouer un listing de jetons | Curseur transmis sans validation (`RedisTokenStore.ts:46`) | Ne pas fabriquer de curseur à la main ; rejouer `nextCursor` tel quel |
662
- | L'écran d'administration n'affiche aucun total | `countSessions` / `countTokens` rendent `-1` (comptage O(N) refusé) | Afficher « inconnu » ; ne jamais inventer un total |
663
- | Un `offset` envoyé n'a aucun effet | Le mode curseur ne lit que `cursor` (`SessionStorage.ts:196`) | Paginer par curseur, pas par décalage |
664
- | Des passkeys disparaissent | Politique d'éviction Redis (`allkeys-lru`) sur des clés **sans** TTL | `noeviction` + persistance sur l'instance qui porte les passkeys |
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
- - **Aucun test n'exerce la perte de connexion en cours de vie.** Le banc de robustesse simule un
684
- client `null` — un état que le service n'atteint qu'avant l'initialisation ou après la fermeture. Le
685
- chemin réellement emprunté lors d'un incident (client fermé, non nul) n'est couvert nulle part.
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.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
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