@nodefony/redis 10.0.0-beta.2 → 10.0.0-beta.4

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.
@@ -49,12 +49,13 @@ declare class RedisSessionStorage implements ISessionStorage {
49
49
  /**
50
50
  * {@inheritDoc ISessionStorage.listPage}
51
51
  *
52
- * **Curseur SCAN** : au plus UN passage `SCAN` par appel (cold-path admin).
53
- * Capacité réduite ASSUMÉE et annoncée — pas de `total`, pas d'ordre global sur
54
- * `updatedAt` (Redis n'a pas d'index secondaire ici), et la page peut compter
55
- * moins d'éléments que `limit` (le filtre s'applique au batch scanné). Le client
56
- * boucle tant que `hasNext`, en repassant `nextCursor`. La garantie qui compte
57
- * est tenue : **le keyspace n'est jamais matérialisé** — au plus un batch.
52
+ * **Curseur SCAN** : les lots `SCAN` s'enchaînent jusqu'à REMPLIR la page, finir
53
+ * le balayage, ou épuiser l'effort borné ({@link MAX_SCAN} emplacements
54
+ * examinés par appel, cold-path admin). Capacité réduite ASSUMÉE et annoncée —
55
+ * pas de `total`, pas d'ordre global sur `updatedAt` (Redis n'a pas d'index
56
+ * secondaire ici). Une page n'est incomplète qu'en FIN de balayage ou budget
57
+ * épuisé, et porte alors son `nextCursor`. La garantie qui compte est tenue :
58
+ * **le keyspace n'est jamais matérialisé** — un lot à la fois.
58
59
  *
59
60
  * ⚠️ **`COUNT` n'est PAS un plafond** — c'est un indice d'effort par itération.
60
61
  * Redis peut rendre plus de clés que demandé (typiquement un petit keyspace
@@ -70,18 +71,19 @@ declare class RedisSessionStorage implements ISessionStorage {
70
71
  /**
71
72
  * {@inheritDoc ISessionStorage.countSessions}
72
73
  *
73
- * Un comptage exact exigerait un `SCAN` complet O(keyspace) → refusé même sur le
74
- * cold-path admin : renvoie **`-1`** (« inconnu », capacité réduite Redis
75
- * assumée). L'appelant affiche l'inconnu, il ne l'invente pas.
74
+ * Compté par l'INDEX (`sessionIndex.ts`), jamais par balayage : `ZCOUNT` sur
75
+ * les sessions dont l'expiration est à venir. Même périmètre que le filtre
76
+ * de liste — filtres contradictoires (`user` + `authenticated: false`) = 0.
77
+ * Rend **`-1`** (« inconnu ») quand l'index n'est pas disponible : client
78
+ * sans scripts, ou reconstruction en cours sur un autre pod.
76
79
  */
77
- countSessions(_query?: Partial<ISessionListQuery>): Promise<number>;
80
+ countSessions(query?: Partial<ISessionListQuery>): Promise<number>;
78
81
  /**
79
82
  * {@inheritDoc ISessionStorage.countDistinctUsers}
80
83
  *
81
- * Dédupliquer exige d'avoir tout vu : c'est le `SCAN` complet que
82
- * {@link countSessions} refuse déjà, plus un ensemble à retenir en mémoire.
83
- * Renvoie **`-1`** — la console affiche « — », elle n'invente pas un chiffre.
84
+ * Les PERSONNES : l'index tient chaque utilisateur avec l'expiration de sa
85
+ * session la plus tardive — il disparaît du compte avec sa dernière session.
84
86
  */
85
- countDistinctUsers(_query?: Partial<ISessionListQuery>): Promise<number>;
87
+ countDistinctUsers(query?: Partial<ISessionListQuery>): Promise<number>;
86
88
  }
87
89
  export default RedisSessionStorage;
@@ -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;
@@ -127,18 +127,18 @@ service par la chaîne `"redis"` dans le conteneur, jamais par un `import`. `Red
127
127
  `import type`, effacé à la compilation. Résultat, aucune dépendance runtime ne circule entre l'infra
128
128
  et la sécurité, dans aucun sens — et le graphe de modules reste acyclique.
129
129
 
130
- **Charger le module suffit.** `Redis.onKernelRegister()` (`index.ts:64`) valide la configuration puis
131
- appelle `registerRedisFrameworkStores()` (`registerStores.ts:72`), qui inscrit les fabriques `redis`
130
+ **Charger le module suffit.** `Redis.onKernelRegister()` (`index.ts#Redis.onKernelRegister`) valide la configuration puis
131
+ appelle `registerRedisFrameworkStores()` (`registerStores.ts#registerRedisFrameworkStores`), qui inscrit les fabriques `redis`
132
132
  dans les registres de jetons et de passkeys. Le store de session, lui, s'auto-déclare à l'import du
133
- fichier (`SessionStorage.ts:323`). Aucune application n'a de câblage à écrire : il ne reste qu'à
133
+ fichier (`SessionStorage.ts#RedisSessionStorage.listAll`). Aucune application n'a de câblage à écrire : il ne reste qu'à
134
134
  nommer le store — ou à laisser `auto` choisir.
135
135
 
136
- **Le module est déclaré non critique.** `Redis.critical` vaut `false` (`index.ts:36`) : un échec de
136
+ **Le module est déclaré non critique.** `Redis.critical` vaut `false` (`index.ts#nodefony`) : un échec de
137
137
  son démarrage ne tue jamais le process. C'est un choix assumé de disponibilité — dont cette page
138
138
  détaille exactement le prix dans « Résilience ».
139
139
 
140
140
  Le contrepoint de ces trois choix : la configuration, elle, est **stricte**. Une config invalide
141
- arrête le démarrage avec un message qui nomme le champ fautif (`index.ts:62`). Tout est dans
141
+ arrête le démarrage avec un message qui nomme le champ fautif (`index.ts#Redis.onKernelRegister`). Tout est dans
142
142
  [Configuration](./configuration.md) — cette page n'en reprend aucune clé.
143
143
 
144
144
  ## 🚀 Démarrage rapide
@@ -246,7 +246,7 @@ reposé à chaque écriture — et repositionné sans réécrire la valeur quand
246
246
  | Options | `nodefony/src/buildClientOptions.ts` | Traduire la config déclarative en options `createClient` (dont la reconnexion). |
247
247
 
248
248
  Le service porte sa carte en **allocation paresseuse** : `#connections` vaut `null` tant qu'aucune
249
- connexion n'est ouverte (`redis.ts:33`), et redevient `null` à la fermeture. Une application qui
249
+ connexion n'est ouverte (`redis.ts#RedisService.module`), et redevient `null` à la fermeture. Une application qui
250
250
  charge le module sans jamais ouvrir de connexion ne paie donc pas un seul objet.
251
251
 
252
252
  ### Le démarrage, étape par étape
@@ -277,11 +277,11 @@ sequenceDiagram
277
277
 
278
278
  Trois détails de ce schéma décident de tout le comportement en panne :
279
279
 
280
- 1. `RedisService.init()` (`redis.ts:123`) enveloppe **chaque** connexion dans son propre `try/catch` :
280
+ 1. `RedisService.init()` (`redis.ts#RedisService.init`) enveloppe **chaque** connexion dans son propre `try/catch` :
281
281
  une connexion qui échoue est journalisée en `ERROR` et les suivantes sont quand même tentées.
282
- 2. `RedisService.createConnection()` (`redis.ts:175`) inscrit la connexion dans `#connections`
283
- **avant** d'attendre son ouverture (`redis.ts:75`).
284
- 3. `Connection.create()` (`Connection.ts:86`) affecte `this.client` **avant** d'appeler `connect()`.
282
+ 2. `RedisService.createConnection()` (`redis.ts#RedisService.createConnection`) inscrit la connexion dans `#connections`
283
+ **avant** d'attendre son ouverture (`redis.ts#RedisService.connections`).
284
+ 3. `Connection.create()` (`Connection.ts#Connection.create`) affecte `this.client` **avant** d'appeler `connect()`.
285
285
 
286
286
  Les points 2 et 3 sont la cause d'un comportement contre-intuitif détaillé plus bas : après un
287
287
  démarrage raté, la connexion existe, le client existe — mais il est fermé.
@@ -291,10 +291,10 @@ démarrage raté, la connexion existe, le client existe — mais il est fermé.
291
291
  Prenons une lecture de session. Elle traverse exactement quatre gestes :
292
292
 
293
293
  1. Le store résout le service **paresseusement**, au premier accès seulement :
294
- `RedisSessionStorage.#client()` (`SessionStorage.ts:89`) mémorise le service puis demande
294
+ `RedisSessionStorage.#client()` (`SessionStorage.ts#RedisSessionStorage.#client`) 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
- 2. `RedisService.getClient()` (`redis.ts:220`) rend le client de la connexion nommée, ou `null`.
297
+ 2. `RedisService.getClient()` (`redis.ts#RedisService.getClient`) rend le client de la connexion nommée, ou `null`.
298
298
  3. Le store teste `null` et décide de son repli.
299
299
  4. La commande part sur le socket.
300
300
 
@@ -307,10 +307,10 @@ Le protocole Redis bascule un client en mode écoute dès qu'il s'abonne : il ne
307
307
  `GET`/`SET`. Une seule connexion partagée rendrait donc le temps réel et le stockage mutuellement
308
308
  exclusifs. Le module tranche par la topologie : `main` pour les commandes, `publish` pour l'émission,
309
309
  `subscribe` pour l'écoute. Les trois sont assemblées par `buildClientOptions()`
310
- (`buildClientOptions.ts:45`), qui fusionne les options globales avec la surcharge de la connexion.
310
+ (`buildClientOptions.ts#buildClientOptions`), qui fusionne les options globales avec la surcharge de la connexion.
311
311
 
312
312
  > [!NOTE]
313
- > `maintNotifications: "disabled"` est forcé dans les options (`buildClientOptions.ts:58`). En
313
+ > `maintNotifications: "disabled"` est forcé dans les options (`buildClientOptions.ts#buildClientOptions`). En
314
314
  > `redis` v6, le défaut RESP3 souscrit aux notifications de maintenance de Redis Enterprise et
315
315
  > relâche les délais du socket. Nodefony cible Redis OSS : on coupe, pour un comportement
316
316
  > déterministe et zéro trame superflue.
@@ -323,7 +323,7 @@ vue d'ensemble ; les fiches détaillent les choix qui surprennent.
323
323
  > [!NOTE]
324
324
  > Les préfixes sont donnés **sans la cloison** de l'application, pour la lisibilité. Une application
325
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.
326
+ > `redis.ts#RedisService.keyPrefix`), la cloison venant de `keyNamespace` ou, à défaut, du nom du projet.
327
327
 
328
328
  | Clé | Structure | Durée de vie | Écrit par |
329
329
  | --------------------------- | -------------- | --------------------------------------------- | ----------------------------------------------- |
@@ -341,13 +341,13 @@ vue d'ensemble ; les fiches détaillent les choix qui surprennent.
341
341
 
342
342
  ### `nf:sess:*` — la session, une chaîne et un TTL
343
343
 
344
- Une session est un blob JSON écrit d'un coup. `RedisSessionStorage.write()` (`SessionStorage.ts:106`)
344
+ Une session est un blob JSON écrit d'un coup. `RedisSessionStorage.write()` (`SessionStorage.ts#RedisSessionStorage.write`)
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
- directes : `gc()` (`SessionStorage.ts:151`) est un **no-op** assumé — aucun balayage, aucune requête
350
- de purge périodique — et `touch()` (`SessionStorage.ts:166`) se réduit à un `EXPIRE`, en O(1), **sans
349
+ directes : `gc()` (`SessionStorage.ts#RedisSessionStorage.read`) est un **no-op** assumé — aucun balayage, aucune requête
350
+ de purge périodique — et `touch()` (`SessionStorage.ts#RedisSessionStorage.touch`) se réduit à un `EXPIRE`, en O(1), **sans
351
351
  réécrire la valeur**. C'est le renouvellement le moins coûteux de tous les backends de session.
352
352
 
353
353
  L'expiration **absolue** (âge maximal, jamais prolongé) ne s'exprime pas par un TTL glissant. Elle est
@@ -357,22 +357,22 @@ survivre dans Redis jusqu'à la fin de son TTL d'inactivité, mais elle est refu
357
357
  ### `nf:tok:*` — les jetons, un HASH et quatre index
358
358
 
359
359
  Pourquoi un HASH plutôt qu'un blob JSON comme la session ? Parce qu'un jeton est **mis à jour en
360
- place** à chaque usage. `RedisTokenStore.markUsed()` (`RedisTokenStore.ts:487`) écrit un à trois
360
+ place** à chaque usage. `RedisTokenStore.markUsed()` (`RedisTokenStore.ts#RedisTokenStore.markUsed`) écrit un à trois
361
361
  champs (`lastUsedAt`, IP, agent) sans relire l'enregistrement, sans le réécrire, et **sans toucher au
362
362
  TTL**. Avec un blob, chaque appel d'API coûterait une lecture, une désérialisation, une réécriture —
363
363
  et remettrait en jeu la date d'expiration.
364
364
 
365
365
  Ce choix impose une précaution : `HSET` sur une clé absente la **recrée**, et une clé recréée n'a pas
366
- de TTL. Le store vérifie donc l'existence d'abord (`RedisTokenStore.ts:494`) et ne fait rien si
366
+ de TTL. Le store vérifie donc l'existence d'abord (`RedisTokenStore.ts#RedisClientLike.hSet`) et ne fait rien si
367
367
  l'identifiant est inconnu. Sans ce test, un jeton expiré ressusciterait, immortel, à sa prochaine
368
368
  utilisation.
369
369
 
370
370
  Les quatre index secondaires sont des SET (`subj`, `fam`) et des chaînes (`hash`, `revsub`). Aucun
371
371
  n'a de TTL : ils sont nettoyés **paresseusement**, quand une lecture tombe sur un membre dont
372
- l'enregistrement a expiré — voir `RedisTokenStore.findBySubject()` (`RedisTokenStore.ts:348`) et
373
- `RedisTokenStore.findByHash()` (`RedisTokenStore.ts:330`).
372
+ l'enregistrement a expiré — voir `RedisTokenStore.findBySubject()` (`RedisTokenStore.ts#RedisTokenStore.findBySubject`) et
373
+ `RedisTokenStore.findByHash()` (`RedisTokenStore.ts#RedisTokenStore.findByHash`).
374
374
 
375
- La révocation combine les deux régimes. `RedisTokenStore.#applyRevoke()` (`RedisTokenStore.ts:550`)
375
+ La révocation combine les deux régimes. `RedisTokenStore.#applyRevoke()` (`RedisTokenStore.ts#RedisTokenStore.#applyRevoke`)
376
376
  pose la date et la raison, puis — si le jeton n'avait **pas** d'expiration (cas d'un PAT) — lui donne
377
377
  un TTL égal à la durée de rétention. Un jeton révoqué reste donc consultable un temps, puis disparaît
378
378
  tout seul.
@@ -384,7 +384,7 @@ d'ailleurs pas de méthode de maintenance. Deux structures suffisent : un HASH p
384
384
  SET d'identifiants par utilisateur.
385
385
 
386
386
  Un point de conception mérite d'être connu : `countByUser()`
387
- (`RedisWebAuthnCredentialStore.ts:199`) utilise `SCARD`, en O(1), sans lire un seul HASH. Il peut donc
387
+ (`RedisWebAuthnCredentialStore.ts#RedisWebAuthnCredentialStore.countByUser`) 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
 
@@ -421,26 +421,26 @@ sequenceDiagram
421
421
  Quatre propriétés à retenir.
422
422
 
423
423
  **Un seul canal, pas un par sujet.** Les canaux applicatifs voyagent **dans** l'enveloppe. Le
424
- backplane fait donc un unique `SUBSCRIBE` au démarrage (`RedisBackplane.ts:18`), jamais
424
+ backplane fait donc un unique `SUBSCRIBE` au démarrage (`RedisBackplane.ts#REDIS_RT_CHANNEL`), jamais
425
425
  d'abonnement dynamique. C'est ce qui rend le coût indépendant du nombre de canaux applicatifs.
426
426
 
427
427
  **Le cloisonnement n'est pas le numéro de base.** Le pub/sub Redis est **global au serveur** : il
428
428
  ignore complètement le `database`. Deux applications sur un Redis mutualisé se parleraient. D'où le
429
- suffixe de canal calculé par `resolveRedisChannel()` (`RedisBackplane.ts:31`) — issu de la config, ou
429
+ suffixe de canal calculé par `resolveRedisChannel()` (`RedisBackplane.ts#resolveRedisChannel`) — issu de la config, ou
430
430
  à défaut du nom du projet. Deux déploiements de la **même** application (préproduction et production)
431
431
  dérivent le même nom : il faut alors un namespace explicite.
432
432
 
433
433
  **L'anti-echo est structurel.** Redis renvoie à l'émetteur ce qu'il publie, puisque les connexions
434
434
  `publish` et `subscribe` appartiennent au même pod. Sans filtre, chaque message serait diffusé deux
435
435
  fois localement. Le tri d'entrée `RedisBackplane.#ingress()` compare donc l'identifiant d'origine à
436
- la réception (`RedisBackplane.ts:269`) et écarte les siens.
436
+ la réception (`RedisBackplane.ts#RedisBackplane.#ingress`) 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
440
440
  fiabilité que le support n'offre pas — c'est le client temps réel qui se resynchronise.
441
441
 
442
442
  Le branchement lui-même est **fail-soft annoncé** : la fabrique du pilote `redis`
443
- (`realtime/index.ts:108`) journalise un `WARNING` explicite — « module absent » ou « connexions
443
+ (`realtime/index.ts`) journalise un `WARNING` explicite — « module absent » ou « connexions
444
444
  indisponibles » — et rend `null`, ce qui laisse le hub en mode local. L'application continue de
445
445
  fonctionner sur un seul pod, et le journal dit pourquoi elle n'en fait pas plus.
446
446
 
@@ -455,25 +455,25 @@ muet ne l'est pas. Voici ce que le code fait réellement, moment par moment.
455
455
 
456
456
  ### Moment 1 — Redis est absent au démarrage
457
457
 
458
- Le module est déclaré non critique (`index.ts:36`), et l'initialisation du service est **bornée dans
459
- le temps** : `Kernel.guardInitialize()` (`Kernel.ts:4043`) enveloppe l'appel dans un délai maximal de
458
+ Le module est déclaré non critique (`index.ts#nodefony`), et l'initialisation du service est **bornée dans
459
+ le temps** : `Kernel.guardInitialize()` (`Kernel.ts#Kernel.guardInitialize`) 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
 
463
463
  La politique de reconnexion, elle, joue un rôle inattendu **au tout premier `connect()`**.
464
- `buildReconnectStrategy()` (`buildClientOptions.ts:13`) rend un délai croissant borné, et une `Error`
464
+ `buildReconnectStrategy()` (`buildClientOptions.ts#buildReconnectStrategy`) rend un délai croissant borné, et une `Error`
465
465
  au-delà du nombre maximal de tentatives — mais seulement si ce maximum est fini. Or le défaut du
466
466
  schéma vaut `0`, c'est-à-dire **illimité** : avec ce réglage, `connect()` ne rend jamais la main
467
467
  tant que Redis ne répond pas.
468
468
 
469
469
  D'où un garde-fou spécifique au développement : `applyResilienceDefaults()`
470
- (`defineModuleConfig.ts:65`) borne les tentatives à un nombre fini **hors production**, quand
470
+ (`defineModuleConfig.ts#applyResilienceDefaults`) 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
 
474
474
  ### Moment 2 — la connexion est perdue en cours de vie
475
475
 
476
- `Connection.create()` (`Connection.ts:86`) attache cinq écouteurs — `error`, `connect`, `ready`,
476
+ `Connection.create()` (`Connection.ts#Connection.create`) attache cinq écouteurs — `error`, `connect`, `ready`,
477
477
  `end`, `reconnecting` — qui font deux choses : journaliser et **réémettre** l'événement sur le
478
478
  service. La perte est donc visible dans le journal (`ERROR` sur l'erreur, `INFO` sur la fin,
479
479
  `WARNING` à chaque tentative) et observable par tout code qui écoute le service.
@@ -488,7 +488,7 @@ suivant.
488
488
  ### Moment 3 — le garde `if (!client)`, et ce qu'il couvre
489
489
 
490
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** :
491
+ `RedisService.getClient()` (`redis.ts#RedisService.getClient`) rend `null` dès que le socket **n'est pas ouvert** :
492
492
  avant l'initialisation, après `RedisService.closeConnections()`, mais aussi après un `connect()` raté
493
493
  — la connexion reste inscrite dans la carte avec un client jamais ouvert, et c'est l'ouverture
494
494
  (`isOpen`), pas la présence, qui est testée. Pendant une reconnexion, en revanche, le socket est
@@ -501,10 +501,10 @@ première bascule (pas un par appel), puis un `INFO` « rétablie » quand la co
501
501
  ### Moment 4 — l'arrêt
502
502
 
503
503
  Le service s'abonne une fois pour toutes à la fin de vie du kernel dans son constructeur
504
- (`redis.ts:243`). `closeConnections()` (`redis.ts:243`) ferme chaque connexion, avale et journalise les
505
- échecs individuels, puis libère la carte. `Connection.close()` (`Connection.ts:146`) appelle la
504
+ (`redis.ts#RedisService.closeConnections`). `closeConnections()` (`redis.ts#RedisService.closeConnections`) ferme chaque connexion, avale et journalise les
505
+ échecs individuels, puis libère la carte. `Connection.close()` (`Connection.ts#Connection.close`) appelle la
506
506
  fermeture gracieuse du client — qui draine les commandes en vol — puis retire **explicitement** les
507
- cinq écouteurs via `Connection.#removeListeners()`, dans un bloc `finally` (`Connection.ts:122`).
507
+ cinq écouteurs via `Connection.#removeListeners()`, dans un bloc `finally` (`Connection.ts#Connection.#removeListeners`).
508
508
  L'ordre compte : les écouteurs sont retirés même si la fermeture échoue.
509
509
 
510
510
  ### Synthèse — est-ce annoncé ?
@@ -523,17 +523,17 @@ L'ordre compte : les écouteurs sont retirés même si la fermeture échoue.
523
523
  | Idempotence : `redis` demandé, module absent | échec franc au démarrage | ✅ fail-loud |
524
524
 
525
525
  Les deux lignes rouges sont un **écart réel au principe** du framework : `RedisSessionStorage.write()`
526
- (`SessionStorage.ts:106`) rend la charge utile sans la persister et sans un mot. Sur la fenêtre
526
+ (`SessionStorage.ts#RedisSessionStorage.write`) rend la charge utile sans la persister et sans un mot. Sur la fenêtre
527
527
  étroite qu'il couvre — avant l'ouverture, après la fermeture — l'impact est faible ; le principe, lui,
528
- voudrait une trace. À l'inverse, `RedisSessionStorage.destroy()` (`SessionStorage.ts:143`) rend `true`
528
+ voudrait une trace. À l'inverse, `RedisSessionStorage.destroy()` (`SessionStorage.ts#RedisSessionStorage.destroy`) 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
 
532
532
  ## L'énumération d'administration — ce que la pagination sait et ne sait pas
533
533
 
534
534
  Trois stores savent énumérer pour un écran d'administration : les sessions
535
- (`SessionStorage.ts:258`), les jetons (`RedisTokenStore.ts:351`) et les passkeys
536
- (`RedisWebAuthnCredentialStore.ts:272`). Tous fonctionnent **en mode curseur**, et tous assument la
535
+ (`SessionStorage.ts#RedisSessionStorage.touch`), les jetons (`RedisTokenStore.ts#RedisTokenStore.put`) et les passkeys
536
+ (`RedisWebAuthnCredentialStore.ts#RedisWebAuthnCredentialStore.delete`). Tous fonctionnent **en mode curseur**, et tous assument la
537
537
  même capacité réduite.
538
538
 
539
539
  ### Ce que le mode curseur rend — et ce qu'il ignore
@@ -542,13 +542,21 @@ même capacité réduite.
542
542
  | -------------------- | ----------------------------------------------------------------------------------- |
543
543
  | `limit` respectée | ✅ garantie par le curseur composite (voir plus bas) |
544
544
  | `cursor` / `hasNext` | ✅ le client boucle tant que `hasNext`, en repassant `nextCursor` |
545
- | `offset` | ❌ **jamais lu** — un client qui en envoie un est ignoré sans avertissement |
546
- | `total` | ❌ jamais rendu — et `countSessions` / `countTokens` / `countCredentials` = `-1` |
547
- | tri / ordre stable | ❌ aucun — `SCAN` ne garantit aucun ordre, et il n'y a pas d'index secondaire |
548
- | page pleine | ❌ une page peut contenir moins d'éléments que `limit` (le filtre porte sur le lot) |
549
-
550
- Le `-1` est un choix, pas un oubli : compter exactement exigerait un `SCAN` complet du keyspace. La
551
- valeur signifie « inconnu », et l'appelant doit l'afficher comme tel plutôt que l'inventer.
545
+ | `offset` | ❌ **refusé** au-delà de 0 — `400 PaginationModeError` ; la console suit le curseur |
546
+ | `total` | ❌ jamais rendu par la LISTE — mais les sessions se COMPTENT (voir ci-dessous) |
547
+ | tri / ordre stable | ❌ aucun — `SCAN` ne garantit aucun ordre |
548
+ | page pleine | ✅ les lots `SCAN` s'enchaînent jusqu'à remplir la page (`scanPage`), effort borné |
549
+
550
+ **Les sessions se comptent par un index** (`sessionIndex.ts`) : des ensembles triés dont le score
551
+ est la date d'EXPIRATION de chaque session — toutes, authentifiées, par utilisateur, et les
552
+ utilisateurs eux-mêmes (score = leur session la plus tardive). Chaque écriture, rafraîchissement ou
553
+ destruction de session y répercute son effet par un script Lua lancé dans le même aller-retour ;
554
+ compter devient un `ZCOUNT` sur ce qui expire après maintenant — une expiration n'a pas besoin
555
+ d'être observée pour être exclue. Les sessions antérieures à l'index sont reprises au premier
556
+ comptage, par un seul pod (verrou), une fois. Coût mesuré : environ +0,12 ms par écriture de session.
557
+
558
+ Les jetons et les passkeys, eux, ne comptent toujours pas : `countTokens` / `countCredentials` = `-1`,
559
+ qui signifie « inconnu » — l'appelant l'affiche comme tel plutôt que de l'inventer.
552
560
 
553
561
  Un mot sur ce que `SCAN` garantit vraiment : une clé présente du début à la fin du parcours est rendue
554
562
  **au moins** une fois — ce qui autorise les doublons, et laisse indéterminé le sort des clés créées ou
@@ -569,7 +577,7 @@ uniquement sur un chemin d'administration. Les trois stores partagent ce mécani
569
577
 
570
578
  > [!IMPORTANT]
571
579
  > **Ce mécanisme n'est pas exercé sans serveur Redis réel.** Le double utilisé par défaut,
572
- > `FakePaginatingRedis` (`session-pagination.test.ts:39`), découpe ses lots à exactement `COUNT`
580
+ > `FakePaginatingRedis` (`session-pagination.test.ts#FakePaginatingRedis`), découpe ses lots à exactement `COUNT`
573
581
  > clés — il ne déborde jamais, donc la branche de reprise n'est jamais atteinte. Or c'est un vrai
574
582
  > serveur qui a révélé le débordement. Sans `NF_REDIS_TEST_URL`, les bancs de pagination passent au vert
575
583
  > **sans avoir testé la seule chose que ce code résout**.
@@ -580,20 +588,20 @@ Le curseur arrive de l'extérieur (chaîne de requête d'un écran d'administrat
580
588
  page) : il n'est pas digne de confiance. Un curseur `SCAN` valide est toujours une suite de chiffres.
581
589
 
582
590
  Les trois stores s'en protègent par la même règle : `decodeCursor()` puis `scanOrZero()`
583
- (`scanCursor.ts:68`) imposent le format et retombent sur `"0"` sinon — repartir du début est faux au
591
+ (`scanCursor.ts#scanOrZero`) imposent le format et retombent sur `"0"` sinon — repartir du début est faux au
584
592
  pire d'une page, transmettre une valeur arbitraire échouerait à coup sûr.
585
593
 
586
594
  ### Les vidages complets
587
595
 
588
596
  À côté de la pagination, deux méthodes déversent tout. `RedisSessionStorage.listAll()`
589
- (`SessionStorage.ts:181`) est **plafonnée** à un maximum de clés parcourues et journalise un
597
+ (`SessionStorage.ts#RedisSessionStorage.listAll`) est **plafonnée** à un maximum de clés parcourues et journalise un
590
598
  `WARNING` quand elle tronque — listing partiel signalé, jamais silencieux.
591
- `RedisTokenStore.listAll()` (`RedisTokenStore.ts:378`) l'est aussi, à `MAX_SCAN` clés, avec le même
599
+ `RedisTokenStore.listAll()` (`RedisTokenStore.ts#RedisTokenStore.listAll`) 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
 
595
603
  Redaction : la page de sessions vide explicitement les sacs de données métier avant de sortir
596
- (`SessionStorage.ts:296`) — un enregistrement d'administration ne transporte jamais le contenu
604
+ (`SessionStorage.ts#RedisSessionStorage.listAll`) — un enregistrement d'administration ne transporte jamais le contenu
597
605
  applicatif d'une session.
598
606
 
599
607
  ## ⚡ Performance & mémoire
@@ -601,21 +609,21 @@ applicatif d'une session.
601
609
  Le module suit la règle de coût du framework : ne rien allouer « au cas où », ne jamais laisser un
602
610
  écouteur derrière soi.
603
611
 
604
- - **Carte de connexions paresseuse** : `null` jusqu'à la première ouverture (`redis.ts:33`), `null` à
612
+ - **Carte de connexions paresseuse** : `null` jusqu'à la première ouverture (`redis.ts#RedisService.module`), `null` à
605
613
  nouveau après fermeture. Un objet `Object.create(null)` est utilisé plutôt qu'une `Map` — quelques
606
614
  entrées, accès par nom, c'est le moins cher.
607
- - **Écouteurs retirés explicitement** : `Connection.#removeListeners()` (`Connection.ts:122`) détache
615
+ - **Écouteurs retirés explicitement** : `Connection.#removeListeners()` (`Connection.ts#Connection.#removeListeners`) détache
608
616
  les cinq écouteurs et relâche les références. Sans ce geste, recréer une connexion accumulerait des
609
617
  fermetures à chaque cycle.
610
- - **Trames de maintenance coupées** (`buildClientOptions.ts:58`) : zéro écouteur et zéro trame
618
+ - **Trames de maintenance coupées** (`buildClientOptions.ts#buildClientOptions`) : zéro écouteur et zéro trame
611
619
  superflus sur un Redis OSS.
612
620
  - **Renouvellement de session en O(1)** : `EXPIRE` seul, sans réécrire la valeur
613
- (`redis/nodefony/src/SessionStorage.ts:161`). Sur une application authentifiée, c'est le geste le plus fréquent de tout
621
+ (`redis/nodefony/src/SessionStorage.ts#RedisSessionStorage.touch`). 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.
617
625
  - **Coût du temps réel** : une publication cross-pod alloue une enveloppe et une sérialisation
618
- (`RedisBackplane.ts:197`) — sur le chemin de diffusion, jamais sur le chemin chaud HTTP. En
626
+ (`RedisBackplane.ts#RedisBackplane`) — sur le chemin de diffusion, jamais sur le chemin chaud HTTP. En
619
627
  mono-process, le backplane n'est même pas instancié.
620
628
  - **Les chemins coûteux sont froids** : `SCAN` est en O(keyspace). Il n'apparaît que dans les
621
629
  énumérations d'administration, jamais dans une lecture de session ou une vérification de jeton.
@@ -627,15 +635,15 @@ c'est la contrepartie assumée de la séparation imposée par le protocole.
627
635
 
628
636
  - **Écran Stores** (`/nodefony/stores`) : pour chaque brique, le store réellement retenu au démarrage
629
637
  **et la raison**. La résolution est enregistrée par `SessionsService.initializeStorage()`
630
- (`sessions-service.ts:258`), qui journalise aussi la décision au format « `auto` → `redis` (infra
631
- cache) ». Le choix automatique lui-même vient de `resolveAutoStore()` (`infra.ts:297`) : Redis n'est
638
+ (`sessions-service.ts#SessionsService.initializeStorage`), qui journalise aussi la décision au format « `auto` → `redis` (infra
639
+ cache) ». Le choix automatique lui-même vient de `resolveAutoStore()` (`infra.ts#resolveAutoStore`) : Redis n'est
632
640
  proposé que pour les natures non durables.
633
641
  - **Écran Sessions** : l'énumération y passe par `listPage` en mode curseur — d'où l'absence de
634
642
  compteur total et la navigation « page suivante » seule. C'est la capacité réduite décrite plus
635
643
  haut, rendue visible.
636
644
  - **Carte du module** (`/nodefony/modules/redis`) : documentation, symboles, tests, couverture, et la
637
645
  configuration validée. Le formulaire est dérivé du JSON Schema publié par `Redis.configSchema()`
638
- (`index.ts:53`), jamais écrit à la main.
646
+ (`index.ts#Redis.configSchema`), jamais écrit à la main.
639
647
 
640
648
  Le module **n'expose pas** de plan de données propre (`/nodefony/redis/api/*`) : il n'a ni état
641
649
  métier ni introspection spécifique. Ce qui compte de lui — quelles connexions, quel store gagne — est
@@ -643,17 +651,17 @@ surfacé par les écrans transverses ci-dessus.
643
651
 
644
652
  ## ⚠️ Pièges (symptôme → cause → correction)
645
653
 
646
- | Symptôme | Cause (dans le code) | Correction |
647
- | -------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
648
- | 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
- | 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
- | Les mêmes messages sont diffusés deux fois localement | Anti-echo court-circuité (identifiant d'origine partagé) | Un identifiant d'origine distinct par pod (`RedisBackplane.ts:212`) |
651
- | Un jeton expiré « revient » et n'expire plus | `HSET` recrée une clé absente, sans TTL | Le test d'existence préalable (`RedisTokenStore.ts:494`) — ne pas le retirer |
652
- | L'écran d'administration n'affiche aucun total | `countSessions` / `countTokens` rendent `-1` (comptage O(N) refusé) | Afficher « inconnu » ; ne jamais inventer un total |
653
- | Un `offset` envoyé n'a aucun effet | Le mode curseur ne lit que `cursor` (`SessionStorage.ts:196`) | Paginer par curseur, pas par décalage |
654
- | 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
- | 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
- | 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#defineRedisConfig`) |
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#resolveRedisChannel`) |
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#RedisBackplane`) |
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#RedisClientLike.hSet`) — 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#RedisSessionStorage.listAll`) | 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#RedisSessionStorage.write`) | 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) |
657
665
 
658
666
  ## 🧪 Tests & couverture
659
667
 
@@ -686,7 +694,7 @@ cette prose. Ce qui doit être dit ici, c'est **ce qui est prouvé, et par quoi*
686
694
  > **Une suite verte ne prouve rien sans serveur Redis.** Les bancs d'intégration se **skippent**
687
695
  > quand l'infra manque, et un skip compte comme un succès : on peut lire « tout est vert » sur une
688
696
  > suite qui n'a rien exercé. La gate du module est déclarée une seule fois — `REDIS_GATE` dans
689
- > `vitest.gates.ts:339` — et la fin de run nomme la cible non exercée avec la commande exacte pour la
697
+ > `scripts/test/vitest/gates.ts#REDIS_GATE` — 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