@nodefony/redis 10.0.0-beta.8 → 10.0.0-beta.9

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.
@@ -1,5 +1,4 @@
1
- import { MAX_SCAN, scanPage } from "./scanCursor.js";
2
- import { assertPageQuery } from "nodefony";
1
+ import { MAX_SCAN, assertPageQuery, scanPage } from "nodefony";
3
2
  // nodefony/src/RedisTokenStore.ts
4
3
  /**
5
4
  * Champ d'un jeton relu dont la forme n'est pas celle que ce store écrit : on
@@ -298,7 +297,7 @@ var RedisTokenStore = class RedisTokenStore {
298
297
  if (Object.keys(h).length > 0) out.push(this.#decode(h));
299
298
  }
300
299
  scanned += res.keys.length;
301
- if (scanned >= 1e4) {
300
+ if (scanned >= MAX_SCAN) {
302
301
  this.#notify(`REDIS TOKENS listAll: balayage plafonné à ${MAX_SCAN} clés (${out.length} jetons rendus) — listing PARTIEL`);
303
302
  break;
304
303
  }
@@ -308,11 +307,11 @@ var RedisTokenStore = class RedisTokenStore {
308
307
  /**
309
308
  * {@inheritDoc ITokenStore.listPage}
310
309
  *
311
- * **Curseur SCAN pur** : UN passage `SCAN` par appel (cold-path admin). Capacité
310
+ * **Curseur SCAN** (`scanPage`, cœur — cold-path admin) : les lots s'enchaînent
311
+ * jusqu'à remplir la page, finir le balayage ou épuiser l'effort borné. Capacité
312
312
  * réduite ASSUMÉE et annoncée — pas de `total`, pas d'ordre global sur `createdAt`
313
- * (Redis n'a pas d'index secondaire ici), la page peut compter moins d'éléments
314
- * que `limit` (le filtre s'applique au batch). Le client boucle tant que
315
- * `hasNext` en repassant `nextCursor`. Renvoie les records BRUTS.
313
+ * (Redis n'a pas d'index secondaire ici). Le client boucle tant que `hasNext`
314
+ * en repassant `nextCursor`. Renvoie les records BRUTS.
316
315
  */
317
316
  async listPage(query) {
318
317
  assertPageQuery(query, "cursor");
@@ -1,5 +1,4 @@
1
- import { scanPage } from "./scanCursor.js";
2
- import { assertPageQuery } from "nodefony";
1
+ import { assertPageQuery, scanPage } from "nodefony";
3
2
  // nodefony/src/RedisWebAuthnCredentialStore.ts
4
3
  /** Préfixe namespacé des clés de credentials WebAuthn dans Redis. */
5
4
  /**
@@ -183,11 +182,11 @@ var RedisWebAuthnCredentialStore = class RedisWebAuthnCredentialStore {
183
182
  /**
184
183
  * {@inheritDoc IWebAuthnCredentialStore.listPage}
185
184
  *
186
- * **Curseur SCAN pur** : UN passage `SCAN` par appel (cold-path admin). Capacité
185
+ * **Curseur SCAN** (`scanPage`, cœur — cold-path admin) : les lots s'enchaînent
186
+ * jusqu'à remplir la page, finir le balayage ou épuiser l'effort borné. Capacité
187
187
  * réduite ASSUMÉE et annoncée — pas de `total`, pas d'ordre global sur
188
- * `createdAt` (Redis n'a pas d'index secondaire ici), la page peut compter moins
189
- * d'éléments que `limit` (le filtre s'applique au batch). Le client boucle tant
190
- * que `hasNext` en repassant `nextCursor`.
188
+ * `createdAt` (Redis n'a pas d'index secondaire ici). Le client boucle tant que
189
+ * `hasNext` en repassant `nextCursor`.
191
190
  *
192
191
  * ⚠️ On SCANne les HASH de credentials, pas les Set par utilisateur : le filtre
193
192
  * `userId` reste un filtre de page. Passer par `sMembers` serait plus direct
@@ -1,6 +1,5 @@
1
- import { MAX_SCAN, scanPage } from "./scanCursor.js";
2
1
  import { SessionIndex, supportsScripts } from "./sessionIndex.js";
3
- import { assertPageQuery } from "nodefony";
2
+ import { MAX_SCAN, assertPageQuery, scanPage } from "nodefony";
4
3
  import { SessionsService } from "@nodefony/http";
5
4
  // nodefony/src/SessionStorage.ts
6
5
  /** Préfixe namespacé des clés de session dans Redis. */
@@ -13,6 +12,13 @@ import { SessionsService } from "@nodefony/http";
13
12
  */
14
13
  const KEY_BASE = "nf:sess";
15
14
  /**
15
+ * Marque d'un curseur de page lu dans l'INDEX d'un compte (`ZSCAN`), par
16
+ * opposition au balayage du parc (`SCAN`). Les deux curseurs ne désignent pas
17
+ * le même espace : un curseur de l'autre mode repart du début — au pire un
18
+ * doublon, jamais une perte.
19
+ */
20
+ const INDEX_CURSOR = "u";
21
+ /**
16
22
  * Relit une session stockée : `null` si la valeur n'est pas du JSON, ou pas un
17
23
  * objet. La forme des sacs se contrôle ensuite au seul consommateur
18
24
  * (`Session.deSerialize`, @nodefony/http) — pour tous les stores à la fois.
@@ -148,14 +154,13 @@ var RedisSessionStorage = class {
148
154
  }
149
155
  async destroy(id) {
150
156
  const client = this.#client();
151
- if (client) {
152
- const deleted = client.del(this.#key(id));
153
- if (supportsScripts(client)) {
154
- const dropped = this.#index().drop(client, id).catch((e) => this.#indexFailed(client, e));
155
- await Promise.all([deleted, dropped]);
156
- } else await deleted;
157
+ if (!client) return false;
158
+ const deleted = client.del(this.#key(id));
159
+ if (supportsScripts(client)) {
160
+ const [count] = await Promise.all([deleted, this.#index().drop(client, id).catch((e) => this.#indexFailed(client, e))]);
161
+ return count > 0;
157
162
  }
158
- return true;
163
+ return await deleted > 0;
159
164
  }
160
165
  async gc() {}
161
166
  /**
@@ -213,9 +218,11 @@ var RedisSessionStorage = class {
213
218
  COUNT: 200
214
219
  });
215
220
  cursor = res.cursor;
216
- for (const key of res.keys) {
221
+ const raws = await Promise.all(res.keys.map((key) => client.get(key)));
222
+ for (let i = 0; i < res.keys.length; i += 1) {
217
223
  scanned++;
218
- const raw = await client.get(key);
224
+ const key = res.keys[i] ?? "";
225
+ const raw = raws[i];
219
226
  if (!raw) continue;
220
227
  const data = parseSession(raw);
221
228
  if (!data) continue;
@@ -225,7 +232,7 @@ var RedisSessionStorage = class {
225
232
  data
226
233
  });
227
234
  }
228
- if (scanned >= 1e4) {
235
+ if (scanned >= MAX_SCAN) {
229
236
  this.manager.log(`REDIS SESSIONS listAll: scan plafonné à ${MAX_SCAN} clés (listing admin partiel — envisager un index secondaire)`, "WARNING");
230
237
  break;
231
238
  }
@@ -246,12 +253,23 @@ var RedisSessionStorage = class {
246
253
  * ⚠️ **`COUNT` n'est PAS un plafond** — c'est un indice d'effort par itération.
247
254
  * Redis peut rendre plus de clés que demandé (typiquement un petit keyspace
248
255
  * encodé en listpack : tout arrive en une fois). Sans précaution, la page
249
- * dépasserait `limit` et violerait le contrat `IPage`. D'où le **curseur
250
- * composite** `"<consommé>:<curseurRedis>"` : quand un batch contient plus que
251
- * la page, on ne rend que `limit` éléments et on mémorise combien de clés du
252
- * batch ont été consommées — la page suivante rejoue le MÊME `SCAN` et reprend
253
- * là où on s'était arrêté. Coût : un re-scan du batch courant, payé uniquement
254
- * sur un cold-path d'administration. Rien n'est perdu, rien ne déborde.
256
+ * dépasserait `limit` et violerait le contrat `IPage`. Une page pleine au
257
+ * milieu d'un lot rend un curseur qui REJOUE ce lot en sautant, par
258
+ * empreinte, les clés déjà parcourues (`scanPage`, cœur) — jamais par
259
+ * position : Redis peut recomposer le lot entre deux pages, et un parcours
260
+ * qui supprime (`destroyByUser`) le recompose à coup sûr. Coût : un re-scan du
261
+ * lot courant, payé sur un cold-path d'administration. Rien n'est perdu,
262
+ * rien ne déborde, et le curseur ne transporte aucun identifiant de session.
263
+ *
264
+ * **Les sessions d'UN compte** (`user` nommé) se lisent dans l'INDEX du compte
265
+ * (`ZSCAN <base>:u:<user>`), pas dans le parc : ce chemin porte la création de
266
+ * compte, le changement de mot de passe et « déconnecter partout », et le
267
+ * parcours du parc coûtait une lecture par session existante (48 s pour un
268
+ * compte parmi 20 000). `ZSCAN` a les garanties de `SCAN` — tout élément
269
+ * présent du début à la fin du parcours est rendu — et passe par la MÊME règle
270
+ * de reprise ({@link scanPage}). L'index n'est cru que s'il est COMPLET (marqué
271
+ * construit) ; en reconstruction sur un autre pod, ou sans scripts, le parc
272
+ * reste la vérité de repli.
255
273
  */
256
274
  async listPage(query) {
257
275
  assertPageQuery(query, "cursor");
@@ -263,28 +281,59 @@ var RedisSessionStorage = class {
263
281
  hasNext: false,
264
282
  nextCursor: null
265
283
  };
266
- const prefixLen = this.#prefix().length + 1;
267
- const match = `${this.#prefix()}:*`;
268
- const { items, nextCursor } = await scanPage((cursor) => client.scan(cursor, {
269
- MATCH: match,
270
- COUNT: limit
271
- }), query.cursor, limit, async (key) => {
272
- const raw = await client.get(key);
284
+ const values = /* @__PURE__ */ new Map();
285
+ const prefetch = async (items, keyOf) => {
286
+ values.clear();
287
+ const raws = await Promise.all(items.map((i) => client.get(keyOf(i))));
288
+ for (let i = 0; i < items.length; i += 1) values.set(items[i] ?? "", raws[i] ?? null);
289
+ };
290
+ const record = (id, raw) => {
273
291
  if (!raw) return null;
274
292
  const data = parseSession(raw);
275
293
  if (!data) return null;
276
294
  if (query.user !== void 0 && data.user !== query.user) return null;
277
295
  if (query.authenticated !== void 0 && !!data.user !== query.authenticated) return null;
278
296
  return {
279
- id: key.slice(prefixLen),
297
+ id,
280
298
  data: {
281
299
  ...data,
282
300
  Attributes: {},
283
301
  flashBag: {}
284
302
  }
285
303
  };
286
- });
287
- const total = await this.countSessions(query);
304
+ };
305
+ const fromIndex = query.cursor?.startsWith(INDEX_CURSOR) === true;
306
+ const indexed = await this.#accountIndex(query.user);
307
+ let items;
308
+ let nextCursor;
309
+ if (indexed !== null) {
310
+ const userKey = `${this.#index().base}:u:${indexed.user}`;
311
+ const keyOf = (id) => this.#key(id);
312
+ const page = await scanPage(async (cursor) => {
313
+ const res = await indexed.client.zScan(userKey, cursor, { COUNT: limit });
314
+ const ids = res.members.map((m) => m.value);
315
+ await prefetch(ids, keyOf);
316
+ return {
317
+ cursor: res.cursor,
318
+ keys: ids
319
+ };
320
+ }, fromIndex ? query.cursor?.slice(1) : void 0, limit, (id) => Promise.resolve(record(id, values.get(id))));
321
+ items = page.items;
322
+ nextCursor = page.nextCursor === null ? null : INDEX_CURSOR + page.nextCursor;
323
+ } else {
324
+ const match = `${this.#prefix()}:*`;
325
+ const prefixLen = this.#prefix().length + 1;
326
+ const same = (key) => key;
327
+ ({items, nextCursor} = await scanPage(async (cursor) => {
328
+ const res = await client.scan(cursor, {
329
+ MATCH: match,
330
+ COUNT: limit
331
+ });
332
+ await prefetch(res.keys, same);
333
+ return res;
334
+ }, fromIndex ? void 0 : query.cursor, limit, (key) => Promise.resolve(record(key.slice(prefixLen), values.get(key)))));
335
+ }
336
+ const total = query.withTotal === false ? -1 : await this.countSessions(query);
288
337
  return {
289
338
  items,
290
339
  limit,
@@ -327,18 +376,24 @@ var RedisSessionStorage = class {
327
376
  COUNT: 500
328
377
  });
329
378
  cursor = res.cursor;
330
- for (const key of res.keys) {
331
- const [raw, ttl] = await Promise.all([client.get(key), client.pTTL(key)]);
379
+ const keys = res.keys;
380
+ const [raws, ttls] = await Promise.all([Promise.all(keys.map((key) => client.get(key))), Promise.all(keys.map((key) => client.pTTL(key)))]);
381
+ const now = Date.now();
382
+ const adds = [];
383
+ for (let i = 0; i < keys.length; i += 1) {
384
+ const raw = raws[i];
385
+ const ttl = ttls[i] ?? 0;
332
386
  if (!raw || ttl <= 0) continue;
333
387
  const data = parseSession(raw);
334
388
  if (!data) continue;
335
- await index.add(client, {
336
- id: key.slice(prefixLen),
389
+ adds.push(index.add(client, {
390
+ id: (keys[i] ?? "").slice(prefixLen),
337
391
  user: ownerOf(data),
338
- expiresAt: Date.now() + ttl
339
- });
340
- indexed += 1;
392
+ expiresAt: now + ttl
393
+ }));
341
394
  }
395
+ await Promise.all(adds);
396
+ indexed += adds.length;
342
397
  } while (cursor !== "0");
343
398
  await client.set(index.builtKey, String(Date.now()));
344
399
  this.manager.log(`REDIS SESSIONS index reconstruit : ${indexed} session(s)`, "INFO");
@@ -347,6 +402,21 @@ var RedisSessionStorage = class {
347
402
  await client.del(index.lockKey);
348
403
  }
349
404
  }
405
+ /**
406
+ * L'index d'un compte, s'il peut être CRU : un compte nommé (l'anonyme n'a pas
407
+ * d'ensemble à lui), un client qui exécute les scripts, et un index marqué
408
+ * construit — il couvre alors les sessions antérieures à lui, et chaque
409
+ * écriture l'alimente dans le même aller-retour. Sinon `null` : le parc fait foi.
410
+ */
411
+ async #accountIndex(user) {
412
+ if (user === void 0 || user === "") return null;
413
+ const client = this.#clientForIndex();
414
+ if (!client || !await this.#ensureIndexBuilt(client)) return null;
415
+ return {
416
+ client,
417
+ user
418
+ };
419
+ }
350
420
  /** Le client `main`, s'il sait exécuter les scripts de l'index. */
351
421
  #clientForIndex() {
352
422
  const client = this.#client();
@@ -101,11 +101,11 @@ export declare class RedisTokenStore implements ITokenStore {
101
101
  /**
102
102
  * {@inheritDoc ITokenStore.listPage}
103
103
  *
104
- * **Curseur SCAN pur** : UN passage `SCAN` par appel (cold-path admin). Capacité
104
+ * **Curseur SCAN** (`scanPage`, cœur — cold-path admin) : les lots s'enchaînent
105
+ * jusqu'à remplir la page, finir le balayage ou épuiser l'effort borné. Capacité
105
106
  * réduite ASSUMÉE et annoncée — pas de `total`, pas d'ordre global sur `createdAt`
106
- * (Redis n'a pas d'index secondaire ici), la page peut compter moins d'éléments
107
- * que `limit` (le filtre s'applique au batch). Le client boucle tant que
108
- * `hasNext` en repassant `nextCursor`. Renvoie les records BRUTS.
107
+ * (Redis n'a pas d'index secondaire ici). Le client boucle tant que `hasNext`
108
+ * en repassant `nextCursor`. Renvoie les records BRUTS.
109
109
  */
110
110
  listPage(query: ITokenListQuery): Promise<IPage<IAccessTokenRecord>>;
111
111
  /**
@@ -84,11 +84,11 @@ export declare class RedisWebAuthnCredentialStore implements IWebAuthnCredential
84
84
  /**
85
85
  * {@inheritDoc IWebAuthnCredentialStore.listPage}
86
86
  *
87
- * **Curseur SCAN pur** : UN passage `SCAN` par appel (cold-path admin). Capacité
87
+ * **Curseur SCAN** (`scanPage`, cœur — cold-path admin) : les lots s'enchaînent
88
+ * jusqu'à remplir la page, finir le balayage ou épuiser l'effort borné. Capacité
88
89
  * réduite ASSUMÉE et annoncée — pas de `total`, pas d'ordre global sur
89
- * `createdAt` (Redis n'a pas d'index secondaire ici), la page peut compter moins
90
- * d'éléments que `limit` (le filtre s'applique au batch). Le client boucle tant
91
- * que `hasNext` en repassant `nextCursor`.
90
+ * `createdAt` (Redis n'a pas d'index secondaire ici). Le client boucle tant que
91
+ * `hasNext` en repassant `nextCursor`.
92
92
  *
93
93
  * ⚠️ On SCANne les HASH de credentials, pas les Set par utilisateur : le filtre
94
94
  * `userId` reste un filtre de page. Passer par `sMembers` serait plus direct
@@ -60,12 +60,23 @@ declare class RedisSessionStorage implements ISessionStorage {
60
60
  * ⚠️ **`COUNT` n'est PAS un plafond** — c'est un indice d'effort par itération.
61
61
  * Redis peut rendre plus de clés que demandé (typiquement un petit keyspace
62
62
  * encodé en listpack : tout arrive en une fois). Sans précaution, la page
63
- * dépasserait `limit` et violerait le contrat `IPage`. D'où le **curseur
64
- * composite** `"<consommé>:<curseurRedis>"` : quand un batch contient plus que
65
- * la page, on ne rend que `limit` éléments et on mémorise combien de clés du
66
- * batch ont été consommées — la page suivante rejoue le MÊME `SCAN` et reprend
67
- * là où on s'était arrêté. Coût : un re-scan du batch courant, payé uniquement
68
- * sur un cold-path d'administration. Rien n'est perdu, rien ne déborde.
63
+ * dépasserait `limit` et violerait le contrat `IPage`. Une page pleine au
64
+ * milieu d'un lot rend un curseur qui REJOUE ce lot en sautant, par
65
+ * empreinte, les clés déjà parcourues (`scanPage`, cœur) — jamais par
66
+ * position : Redis peut recomposer le lot entre deux pages, et un parcours
67
+ * qui supprime (`destroyByUser`) le recompose à coup sûr. Coût : un re-scan du
68
+ * lot courant, payé sur un cold-path d'administration. Rien n'est perdu,
69
+ * rien ne déborde, et le curseur ne transporte aucun identifiant de session.
70
+ *
71
+ * **Les sessions d'UN compte** (`user` nommé) se lisent dans l'INDEX du compte
72
+ * (`ZSCAN <base>:u:<user>`), pas dans le parc : ce chemin porte la création de
73
+ * compte, le changement de mot de passe et « déconnecter partout », et le
74
+ * parcours du parc coûtait une lecture par session existante (48 s pour un
75
+ * compte parmi 20 000). `ZSCAN` a les garanties de `SCAN` — tout élément
76
+ * présent du début à la fin du parcours est rendu — et passe par la MÊME règle
77
+ * de reprise ({@link scanPage}). L'index n'est cru que s'il est COMPLET (marqué
78
+ * construit) ; en reconstruction sur un autre pod, ou sans scripts, le parc
79
+ * reste la vérité de repli.
69
80
  */
70
81
  listPage(query: ISessionListQuery): Promise<IPage<ISessionRecord>>;
71
82
  /**
@@ -525,9 +525,11 @@ L'ordre compte : les écouteurs sont retirés même si la fermeture échoue.
525
525
  Les deux lignes rouges sont un **écart réel au principe** du framework : `RedisSessionStorage.write()`
526
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#RedisSessionStorage.destroy`) rend `true`
529
- sans connexion **délibérément** : l'appelant est une déconnexion, et lui répondre « échec » laisserait
530
- l'utilisateur croire qu'il est resté connecté.
528
+ voudrait une trace. `RedisSessionStorage.destroy()` (`SessionStorage.ts#RedisSessionStorage.destroy`), lui, ne
529
+ lève pas sans connexion et rend `false` : rien n'a été retiré, la session est peut-être toujours dans
530
+ Redis. La déconnexion d'un utilisateur ne dépend pas de ce booléen — `Session.destroy` l'ignore et efface
531
+ le cookie ; ceux qui le lisent sont les révocations, qui l'auditent, et un `true` y ferait journaliser une
532
+ révocation qui n'a pas eu lieu. Le contrat est le même sur tous les stores (`ISessionStorage.destroy`).
531
533
 
532
534
  ## L'énumération d'administration — ce que la pagination sait et ne sait pas
533
535
 
@@ -540,7 +542,7 @@ même capacité réduite.
540
542
 
541
543
  | Attente du contrat | État réel sur Redis |
542
544
  | -------------------- | ----------------------------------------------------------------------------------- |
543
- | `limit` respectée | ✅ garantie par le curseur composite (voir plus bas) |
545
+ | `limit` respectée | ✅ garantie par la reprise au milieu d'un lot (voir plus bas) |
544
546
  | `cursor` / `hasNext` | ✅ le client boucle tant que `hasNext`, en repassant `nextCursor` |
545
547
  | `offset` | ❌ **refusé** au-delà de 0 — `400 PaginationModeError` ; la console suit le curseur |
546
548
  | `total` | ❌ jamais rendu par la LISTE — mais les sessions se COMPTENT (voir ci-dessous) |
@@ -563,33 +565,46 @@ Un mot sur ce que `SCAN` garantit vraiment : une clé présente du début à la
563
565
  détruites pendant l'itération. L'invariant « toutes les pages, sans trou ni doublon » ne tient donc
564
566
  que sur un parc figé.
565
567
 
566
- ### Le curseur composite, et pourquoi il existe
568
+ ### Reprendre au milieu d'un lot, sans rien perdre
567
569
 
568
570
  `COUNT` n'est pas un plafond. C'est un indice d'effort : sur un petit keyspace encodé en listpack,
569
571
  Redis rend **toutes** les clés d'un coup, quel que soit le `COUNT` demandé. Une page nue déborderait
570
572
  alors la `limit` et violerait le contrat.
571
573
 
572
- D'où un curseur de la forme `"<déjà consommé>:<curseur Redis>"`, encodé par `encodeCursor()`
573
- (`scanCursor.ts`). Quand un lot contient plus d'éléments que la page, le store n'en rend que
574
- `limit`, mémorise combien de clés du lot ont été consommées, et la page suivante **rejoue le même
575
- `SCAN`** pour reprendre à la bonne position. Le coût est un re-parcours du lot courant, payé
576
- uniquement sur un chemin d'administration. Les trois stores partagent ce mécanisme, à l'identique.
574
+ Quand un lot contient plus d'éléments que la page, le store n'en rend que `limit`, et la page
575
+ suivante **rejoue le même `SCAN`** en sautant les clés déjà parcourues. Elle les désigne **par
576
+ empreinte** (53 bits par clé), jamais par position : Redis ne rend pas forcément deux fois le même
577
+ lot pour un même curseur — une insertion, une suppression ou un rehash le recompose. Sauter « les N
578
+ premières » clés sautait alors des clés jamais rendues, et un parcours qui supprime ce qu'il lit
579
+ (« déconnecter partout ») pouvait laisser vivre une session. Le curseur a la forme
580
+ `"<curseur Redis>.<empreintes>"` — 7 octets par empreinte, en base64url : rien à échapper dans
581
+ une URL.
582
+
583
+ Le curseur ne transporte **aucune clé** : une clé de session est l'identifiant de session, et un
584
+ curseur voyage dans une URL, donc dans les journaux d'accès. Le coût est un re-parcours du lot
585
+ courant, payé uniquement sur un chemin d'administration. La règle est unique — `scanPage`
586
+ (`scanPage.ts#scanPage`), portée par le cœur `nodefony` — et partagée par les trois stores de
587
+ ce module et par le store d'idempotence de `@nodefony/framework`.
577
588
 
578
589
  > [!IMPORTANT]
579
- > **Ce mécanisme n'est pas exercé sans serveur Redis réel.** Le double utilisé par défaut,
580
- > `FakePaginatingRedis` (`session-pagination.test.ts#FakePaginatingRedis`), découpe ses lots à exactement `COUNT`
581
- > clés — il ne déborde jamais, donc la branche de reprise n'est jamais atteinte. Or c'est un vrai
582
- > serveur qui a révélé le débordement. Sans `NF_REDIS_TEST_URL`, les bancs de pagination passent au vert
583
- > **sans avoir testé la seule chose que ce code résout**.
590
+ > **Les doubles prouvent la règle, pas Redis.** La règle elle-même est éprouvée sans serveur : lot qui
591
+ > déborde la page, lot réordonné ou amputé entre deux pages (`scanPage.test.ts` au cœur,
592
+ > `scanCursor.test.ts` ici). Mais seul un vrai serveur **recompose** ses lots de lui-même : le
593
+ > parcours qui détruit ce qu'il lit, sur un keyspace qui bouge, ne se joue qu'avec
594
+ > `NF_REDIS_TEST_URL` (`session-pagination.test.ts`). Sans lui, ce banc se **skippe** — et l'ancienne
595
+ > reprise par position y sautait des dizaines de sessions sur six cents.
584
596
 
585
597
  ### Les curseurs hostiles
586
598
 
587
599
  Le curseur arrive de l'extérieur (chaîne de requête d'un écran d'administration, client qui rejoue une
588
600
  page) : il n'est pas digne de confiance. Un curseur `SCAN` valide est toujours une suite de chiffres.
589
601
 
590
- Les trois stores s'en protègent par la même règle : `decodeCursor()` puis `scanOrZero()`
591
- (`scanCursor.ts#scanOrZero`) 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.
602
+ Les stores s'en protègent par la même règle (`scanPage.ts#decodeCursor`) : au moindre écart de
603
+ format, le curseur **entier** est jeté et le balayage repart de `"0"` — repartir du début est faux
604
+ au pire d'une page, transmettre une valeur arbitraire échouerait à coup sûr, et appliquer des
605
+ empreintes à un autre lot que le leur sauterait des clés au hasard. Un curseur forgé ne peut rien
606
+ faire lire que `SCAN` n'ait rendu ; des empreintes forgées ne masquent que les clés de celui qui
607
+ les forge.
593
608
 
594
609
  ### Les vidages complets
595
610
 
@@ -681,13 +696,13 @@ cette prose. Ce qui doit être dit ici, c'est **ce qui est prouvé, et par quoi*
681
696
  - **La perte de connexion en cours de vie n'est exercée que par son effet sur `getClient`**
682
697
  (`client-availability.test.ts`) : une coupure réelle d'un serveur Redis pendant le trafic n'a pas
683
698
  de banc dédié.
684
- - **La branche de reprise du curseur composite n'est atteinte qu'avec un serveur réel** (voir plus
685
- haut) : le double ne déborde jamais.
699
+ - **La recomposition d'un lot par Redis lui-même n'est exercée qu'avec un serveur réel** (voir plus
700
+ haut) : les doubles rejouent des lots écrits à la main.
686
701
  - **Pas de banc de charge ni de test de mémoire dédiés** dans ce module — voir le skill
687
702
  `nodefony-load-test` pour dimensionner, et `nodefony-check-memory-health` pour la mémoire du
688
703
  pipeline.
689
- - **Pas de test d'attaque** (`*.attack.test.ts`) : les curseurs hostiles sont couverts côté session
690
- uniquement, et par le banc de robustesse.
704
+ - **Pas de test d'attaque** (`*.attack.test.ts`) : les curseurs hostiles et forgés sont couverts
705
+ sur les trois stores (`scanCursor.test.ts`) et par le banc de robustesse.
691
706
  - Le cross-pod du backplane est prouvé **ailleurs** (bancs de `@nodefony/realtime`), pas ici.
692
707
 
693
708
  > [!IMPORTANT]
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nodefony/redis",
3
- "version": "10.0.0-beta.8",
3
+ "version": "10.0.0-beta.9",
4
4
  "description": "Connecteur Redis de Nodefony : dépôts clé-valeur, cache, sessions partagées et transport de diffusion entre instances",
5
5
  "nodefony": {
6
6
  "storeKind": "cache",
@@ -52,19 +52,19 @@
52
52
  "tslib": "2.9.1"
53
53
  },
54
54
  "devDependencies": {
55
- "@nodefony/framework": "^10.0.0-beta.8",
56
- "@nodefony/http": "^10.0.0-beta.8",
57
- "@nodefony/security": "^10.0.0-beta.8",
55
+ "@nodefony/framework": "^10.0.0-beta.9",
56
+ "@nodefony/http": "^10.0.0-beta.9",
57
+ "@nodefony/security": "^10.0.0-beta.9",
58
58
  "@types/node": "26.6.6",
59
59
  "@vitest/coverage-v8": "5.1.0",
60
- "nodefony": "^10.0.0-beta.8",
60
+ "nodefony": "^10.0.0-beta.9",
61
61
  "vitest": "5.1.0"
62
62
  },
63
63
  "peerDependencies": {
64
- "@nodefony/framework": "^10.0.0-beta.8",
65
- "@nodefony/http": "^10.0.0-beta.8",
66
- "@nodefony/security": "^10.0.0-beta.8",
67
- "nodefony": "^10.0.0-beta.8",
64
+ "@nodefony/framework": "^10.0.0-beta.9",
65
+ "@nodefony/http": "^10.0.0-beta.9",
66
+ "@nodefony/security": "^10.0.0-beta.9",
67
+ "nodefony": "^10.0.0-beta.9",
68
68
  "zod": "^4.6.7"
69
69
  },
70
70
  "repository": {
@@ -1,121 +0,0 @@
1
- // nodefony/src/scanCursor.ts
2
- /**
3
- * Curseur de pagination `SCAN` — **règle unique** des trois stores Redis
4
- * (sessions, jetons, identifiants WebAuthn).
5
- *
6
- * Pourquoi un fichier partagé : ces trois stores portaient chacun leur copie de
7
- * `encodeCursor`/`decodeCursor`. La copie du store de session a été durcie (un
8
- * curseur venu de l'extérieur y est validé) ; les deux autres ne l'ont jamais
9
- * été — un `?cursor=` arbitraire y partait tel quel vers Redis et faisait
10
- * **échouer une simple consultation**. Deux implémentations d'une même règle
11
- * dérivent toujours : il n'y en a plus qu'une.
12
- */
13
- /**
14
- * Plafond de sécurité d'un balayage administratif complet : au-delà, on s'arrête
15
- * et on **journalise** (listing partiel signalé, jamais tronqué en silence).
16
- *
17
- * `SCAN` est O(keyspace) — un index secondaire (`SET` d'ids) serait
18
- * l'optimisation v2 pour un très grand parc.
19
- */
20
- const MAX_SCAN = 1e4;
21
- /**
22
- * Curseur de page **composite** : `"<skip>:<curseurRedis>"`.
23
- *
24
- * Pourquoi composer plutôt que passer le curseur Redis nu : `SCAN COUNT` est un
25
- * indice d'effort, pas un plafond — Redis peut rendre plus de clés que demandé
26
- * (petit keyspace encodé en listpack → tout arrive d'un coup). Sans précaution
27
- * la page dépasserait `limit` et violerait `IPage`. Le `skip` mémorise combien
28
- * de clés du batch courant ont déjà été rendues, pour que la page suivante
29
- * rejoue le même `SCAN` et reprenne à la bonne position. Rien n'est perdu, rien
30
- * ne déborde.
31
- */
32
- function encodeCursor(scanCursor, skip) {
33
- return `${skip}:${scanCursor}`;
34
- }
35
- /**
36
- * Inverse d'{@link encodeCursor} — tolère un curseur absent, vide ou malformé.
37
- *
38
- * Le jeton vient de l'extérieur (query string du data plane admin, client qui
39
- * rejoue une page) : il n'est donc PAS digne de confiance. Un curseur `SCAN`
40
- * Redis est toujours une suite de chiffres — tout le reste repart de `"0"`
41
- * plutôt que d'être transmis au serveur, qui répondrait par une erreur et ferait
42
- * échouer une simple consultation. Repartir du début est faux au pire d'une
43
- * page ; jeter serait faux à coup sûr.
44
- *
45
- * Le split se fait au PREMIER `:` : le curseur Redis est opaque et reste intact
46
- * même s'il contenait lui-même un `:`.
47
- */
48
- function decodeCursor(cursor) {
49
- if (!cursor) return {
50
- scanCursor: "0",
51
- skip: 0
52
- };
53
- const sep = cursor.indexOf(":");
54
- if (sep === -1) return {
55
- scanCursor: scanOrZero(cursor),
56
- skip: 0
57
- };
58
- const skip = Number.parseInt(cursor.slice(0, sep), 10);
59
- return {
60
- scanCursor: scanOrZero(cursor.slice(sep + 1)),
61
- skip: Number.isFinite(skip) && skip > 0 ? skip : 0
62
- };
63
- }
64
- /** Un curseur `SCAN` exploitable (chiffres) ou `"0"` — jamais du texte libre. */
65
- function scanOrZero(value) {
66
- return /^\d+$/.test(value) ? value : "0";
67
- }
68
- /**
69
- * Rend UNE page d'un balayage `SCAN` filtré — règle unique des trois stores.
70
- *
71
- * Les lots s'enchaînent jusqu'à **remplir** la page, finir le balayage, ou
72
- * épuiser l'effort borné ({@link MAX_SCAN} emplacements examinés par appel).
73
- * 🔴 Un seul lot ne suffit pas : `SCAN COUNT` examine des emplacements de TOUT
74
- * le keyspace (autres applications, idempotence, jetons), et un lot peut ne
75
- * contenir aucune clé retenue par le filtre. Rendre cette page vide ferait
76
- * conclure « rien » à tout consommateur qui ne suit pas le curseur — c'était
77
- * le cas de la console « Mes sessions » sur un Redis partagé.
78
- *
79
- * Le curseur rendu est composite ({@link encodeCursor}) : une page pleine au
80
- * milieu d'un lot reprend au MÊME lot, à la bonne position. Le keyspace n'est
81
- * jamais matérialisé — un lot à la fois.
82
- *
83
- * @param scan - lance un `SCAN` depuis ce curseur (MATCH et COUNT fixés par
84
- * l'appelant ; `COUNT` doit rester le même d'une page à l'autre)
85
- * @param cursor - curseur reçu du client (non fiable — décodé et validé)
86
- * @param limit - taille maximale de la page
87
- * @param accept - lit une clé et rend l'élément à publier, ou `null` s'il est
88
- * écarté (filtre, clé expirée, valeur corrompue)
89
- * @returns les éléments de la page et le curseur suivant (`null` = fin)
90
- */
91
- async function scanPage(scan, cursor, limit, accept) {
92
- let { scanCursor, skip } = decodeCursor(cursor);
93
- const items = [];
94
- let budget = Math.max(1, Math.ceil(MAX_SCAN / limit));
95
- for (;;) {
96
- const res = await scan(scanCursor);
97
- budget -= 1;
98
- let consumed = 0;
99
- for (const key of res.keys.slice(skip)) {
100
- if (items.length >= limit) break;
101
- consumed += 1;
102
- const item = await accept(key);
103
- if (item !== null) items.push(item);
104
- }
105
- if (skip + consumed < res.keys.length) return {
106
- items,
107
- nextCursor: encodeCursor(scanCursor, skip + consumed)
108
- };
109
- if (res.cursor === "0") return {
110
- items,
111
- nextCursor: null
112
- };
113
- scanCursor = scanOrZero(res.cursor);
114
- skip = 0;
115
- if (items.length >= limit || budget <= 0) return {
116
- items,
117
- nextCursor: encodeCursor(scanCursor, 0)
118
- };
119
- }
120
- }
121
- export { MAX_SCAN, decodeCursor, encodeCursor, scanOrZero, scanPage };
@@ -1,82 +0,0 @@
1
- /**
2
- * Curseur de pagination `SCAN` — **règle unique** des trois stores Redis
3
- * (sessions, jetons, identifiants WebAuthn).
4
- *
5
- * Pourquoi un fichier partagé : ces trois stores portaient chacun leur copie de
6
- * `encodeCursor`/`decodeCursor`. La copie du store de session a été durcie (un
7
- * curseur venu de l'extérieur y est validé) ; les deux autres ne l'ont jamais
8
- * été — un `?cursor=` arbitraire y partait tel quel vers Redis et faisait
9
- * **échouer une simple consultation**. Deux implémentations d'une même règle
10
- * dérivent toujours : il n'y en a plus qu'une.
11
- */
12
- /**
13
- * Plafond de sécurité d'un balayage administratif complet : au-delà, on s'arrête
14
- * et on **journalise** (listing partiel signalé, jamais tronqué en silence).
15
- *
16
- * `SCAN` est O(keyspace) — un index secondaire (`SET` d'ids) serait
17
- * l'optimisation v2 pour un très grand parc.
18
- */
19
- export declare const MAX_SCAN = 10000;
20
- /**
21
- * Curseur de page **composite** : `"<skip>:<curseurRedis>"`.
22
- *
23
- * Pourquoi composer plutôt que passer le curseur Redis nu : `SCAN COUNT` est un
24
- * indice d'effort, pas un plafond — Redis peut rendre plus de clés que demandé
25
- * (petit keyspace encodé en listpack → tout arrive d'un coup). Sans précaution
26
- * la page dépasserait `limit` et violerait `IPage`. Le `skip` mémorise combien
27
- * de clés du batch courant ont déjà été rendues, pour que la page suivante
28
- * rejoue le même `SCAN` et reprenne à la bonne position. Rien n'est perdu, rien
29
- * ne déborde.
30
- */
31
- export declare function encodeCursor(scanCursor: string, skip: number): string;
32
- /**
33
- * Inverse d'{@link encodeCursor} — tolère un curseur absent, vide ou malformé.
34
- *
35
- * Le jeton vient de l'extérieur (query string du data plane admin, client qui
36
- * rejoue une page) : il n'est donc PAS digne de confiance. Un curseur `SCAN`
37
- * Redis est toujours une suite de chiffres — tout le reste repart de `"0"`
38
- * plutôt que d'être transmis au serveur, qui répondrait par une erreur et ferait
39
- * échouer une simple consultation. Repartir du début est faux au pire d'une
40
- * page ; jeter serait faux à coup sûr.
41
- *
42
- * Le split se fait au PREMIER `:` : le curseur Redis est opaque et reste intact
43
- * même s'il contenait lui-même un `:`.
44
- */
45
- export declare function decodeCursor(cursor?: string): {
46
- scanCursor: string;
47
- skip: number;
48
- };
49
- /** Un curseur `SCAN` exploitable (chiffres) ou `"0"` — jamais du texte libre. */
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
- }>;