@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.
- package/dist/nodefony/src/RedisTokenStore.js +6 -7
- package/dist/nodefony/src/RedisWebAuthnCredentialStore.js +5 -6
- package/dist/nodefony/src/SessionStorage.js +105 -35
- package/dist/types/nodefony/src/RedisTokenStore.d.ts +4 -4
- package/dist/types/nodefony/src/RedisWebAuthnCredentialStore.d.ts +4 -4
- package/dist/types/nodefony/src/SessionStorage.d.ts +17 -6
- package/docs/architecture.md +37 -22
- package/package.json +9 -9
- package/dist/nodefony/src/scanCursor.js +0 -121
- package/dist/types/nodefony/src/scanCursor.d.ts +0 -82
|
@@ -1,5 +1,4 @@
|
|
|
1
|
-
import { MAX_SCAN, scanPage } from "
|
|
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 >=
|
|
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
|
|
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)
|
|
314
|
-
*
|
|
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 "
|
|
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
|
|
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)
|
|
189
|
-
*
|
|
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
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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 >=
|
|
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`.
|
|
250
|
-
*
|
|
251
|
-
*
|
|
252
|
-
*
|
|
253
|
-
*
|
|
254
|
-
* sur un cold-path d'administration. Rien n'est perdu,
|
|
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
|
|
267
|
-
const
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
}
|
|
272
|
-
|
|
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
|
|
297
|
+
id,
|
|
280
298
|
data: {
|
|
281
299
|
...data,
|
|
282
300
|
Attributes: {},
|
|
283
301
|
flashBag: {}
|
|
284
302
|
}
|
|
285
303
|
};
|
|
286
|
-
}
|
|
287
|
-
const
|
|
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
|
-
|
|
331
|
-
|
|
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
|
-
|
|
336
|
-
id:
|
|
389
|
+
adds.push(index.add(client, {
|
|
390
|
+
id: (keys[i] ?? "").slice(prefixLen),
|
|
337
391
|
user: ownerOf(data),
|
|
338
|
-
expiresAt:
|
|
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
|
|
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)
|
|
107
|
-
*
|
|
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
|
|
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)
|
|
90
|
-
*
|
|
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`.
|
|
64
|
-
*
|
|
65
|
-
*
|
|
66
|
-
*
|
|
67
|
-
*
|
|
68
|
-
* sur un cold-path d'administration. Rien n'est perdu,
|
|
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
|
/**
|
package/docs/architecture.md
CHANGED
|
@@ -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.
|
|
529
|
-
sans connexion
|
|
530
|
-
|
|
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
|
|
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
|
-
###
|
|
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
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
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
|
-
> **
|
|
580
|
-
>
|
|
581
|
-
>
|
|
582
|
-
>
|
|
583
|
-
>
|
|
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
|
|
591
|
-
|
|
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
|
|
685
|
-
haut) :
|
|
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
|
|
690
|
-
|
|
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.
|
|
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.
|
|
56
|
-
"@nodefony/http": "^10.0.0-beta.
|
|
57
|
-
"@nodefony/security": "^10.0.0-beta.
|
|
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.
|
|
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.
|
|
65
|
-
"@nodefony/http": "^10.0.0-beta.
|
|
66
|
-
"@nodefony/security": "^10.0.0-beta.
|
|
67
|
-
"nodefony": "^10.0.0-beta.
|
|
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
|
-
}>;
|