@nodefony/redis 10.0.0-alpha.1
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/LICENSE +544 -0
- package/README.md +110 -0
- package/dist/_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js +9 -0
- package/dist/_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js +6 -0
- package/dist/index.js +58 -0
- package/dist/nodefony/config/config.js +98 -0
- package/dist/nodefony/config/defineModuleConfig.js +90 -0
- package/dist/nodefony/interfaces/IRedisConfig.js +1 -0
- package/dist/nodefony/interfaces/index.js +1 -0
- package/dist/nodefony/registerStores.js +38 -0
- package/dist/nodefony/service/redis.js +177 -0
- package/dist/nodefony/src/Connection.js +111 -0
- package/dist/nodefony/src/RedisTokenStore.js +390 -0
- package/dist/nodefony/src/RedisWebAuthnCredentialStore.js +247 -0
- package/dist/nodefony/src/SessionStorage.js +249 -0
- package/dist/nodefony/src/buildClientOptions.js +63 -0
- package/dist/nodefony/src/keyNamespace.js +80 -0
- package/dist/nodefony/src/scanCursor.js +69 -0
- package/dist/types/index.d.ts +53 -0
- package/dist/types/nodefony/config/config.d.ts +41 -0
- package/dist/types/nodefony/config/defineModuleConfig.d.ts +26 -0
- package/dist/types/nodefony/interfaces/IRedisConfig.d.ts +17 -0
- package/dist/types/nodefony/interfaces/index.d.ts +5 -0
- package/dist/types/nodefony/registerStores.d.ts +5 -0
- package/dist/types/nodefony/service/redis.d.ts +82 -0
- package/dist/types/nodefony/src/Connection.d.ts +39 -0
- package/dist/types/nodefony/src/RedisTokenStore.d.ts +121 -0
- package/dist/types/nodefony/src/RedisWebAuthnCredentialStore.d.ts +108 -0
- package/dist/types/nodefony/src/SessionStorage.d.ts +87 -0
- package/dist/types/nodefony/src/buildClientOptions.d.ts +21 -0
- package/dist/types/nodefony/src/keyNamespace.d.ts +12 -0
- package/dist/types/nodefony/src/scanCursor.d.ts +50 -0
- package/docs/architecture.md +718 -0
- package/docs/configuration.md +773 -0
- package/docs/index.md +295 -0
- package/package.json +95 -0
|
@@ -0,0 +1,249 @@
|
|
|
1
|
+
import { MAX_SCAN, decodeCursor, encodeCursor } from "./scanCursor.js";
|
|
2
|
+
import { assertPageQuery } from "nodefony";
|
|
3
|
+
import { SessionsService } from "@nodefony/http";
|
|
4
|
+
//#region nodefony/src/SessionStorage.ts
|
|
5
|
+
/** Préfixe namespacé des clés de session dans Redis. */
|
|
6
|
+
/**
|
|
7
|
+
* Préfixe HISTORIQUE des clés de session. Il n'est utilisé tel quel que par une
|
|
8
|
+
* application sans cloison ; sinon le service y insère le nom de l'application
|
|
9
|
+
* (cf {@link RedisService.keyPrefix}) — sans quoi deux applications sur un même
|
|
10
|
+
* Redis se partagent l'espace de clés, et le balayage de l'une remonte les
|
|
11
|
+
* sessions de l'autre.
|
|
12
|
+
*/
|
|
13
|
+
const KEY_BASE = "nf:sess";
|
|
14
|
+
/**
|
|
15
|
+
* Stockage de session **Redis** — branché sur la connexion `main` du
|
|
16
|
+
* {@link RedisService}. Implémente le contrat unifié {@link ISessionStorage}
|
|
17
|
+
* consommé par le `SessionsService` de `@nodefony/http`.
|
|
18
|
+
*
|
|
19
|
+
* Atout décisif vs File/SQL : l'expiration est portée par le **TTL natif**
|
|
20
|
+
* (`SET … EX`) → `gc()` est un **no-op** (zéro balayage, zéro requête de purge)
|
|
21
|
+
* et le store est **partagé cross-pod** (source unique de vérité en cluster).
|
|
22
|
+
*
|
|
23
|
+
* Dégradation gracieuse **annoncée** : si la connexion `main` n'est pas (ou
|
|
24
|
+
* plus) ouverte (boot, coupure, shutdown), chaque opération devient un no-op
|
|
25
|
+
* plutôt que de jeter — la session n'est simplement pas persistée le temps de
|
|
26
|
+
* l'indisponibilité. Le repli n'est pas muet : {@link RedisService.getClient}
|
|
27
|
+
* journalise un WARNING à la bascule et un INFO au rétablissement (une seule
|
|
28
|
+
* ligne par transition, pas une par requête).
|
|
29
|
+
*/
|
|
30
|
+
var RedisSessionStorage = class {
|
|
31
|
+
manager;
|
|
32
|
+
/** Idle timeout en secondes (= TTL Redis natif, glissant via `write`/`touch`). */
|
|
33
|
+
idleTimeoutS;
|
|
34
|
+
/** Service Redis résolu en lazy (au 1ᵉʳ accès) depuis le container. */
|
|
35
|
+
#service = null;
|
|
36
|
+
/** Préfixe cloisonné, calculé une seule fois (il est lu à chaque clé). */
|
|
37
|
+
#prefixCache = null;
|
|
38
|
+
constructor(manager) {
|
|
39
|
+
this.manager = manager;
|
|
40
|
+
this.idleTimeoutS = manager.options.idleTimeoutS;
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Client Redis de la connexion `main`, ou `null` si indisponible.
|
|
44
|
+
* Résolution **lazy** du service (l'ordre de boot des modules n'est pas garanti
|
|
45
|
+
* à la construction du storage).
|
|
46
|
+
*/
|
|
47
|
+
#client() {
|
|
48
|
+
if (!this.#service) this.#service = this.manager.get("redis") ?? null;
|
|
49
|
+
return this.#service?.getClient("main") ?? null;
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* Préfixe effectif des clés, cloisonné par application. Mémoïsé : il est lu à
|
|
53
|
+
* chaque clé, et le service ne change pas en cours de vie.
|
|
54
|
+
*/
|
|
55
|
+
#prefix() {
|
|
56
|
+
if (this.#prefixCache === null) {
|
|
57
|
+
this.#client();
|
|
58
|
+
const service = this.#service;
|
|
59
|
+
this.#prefixCache = typeof service?.keyPrefix === "function" ? service.keyPrefix(KEY_BASE) : KEY_BASE;
|
|
60
|
+
}
|
|
61
|
+
return this.#prefixCache;
|
|
62
|
+
}
|
|
63
|
+
#key(id) {
|
|
64
|
+
return `${this.#prefix()}:${id}`;
|
|
65
|
+
}
|
|
66
|
+
async read(id) {
|
|
67
|
+
const client = this.#client();
|
|
68
|
+
if (!client) return {};
|
|
69
|
+
const raw = await client.get(this.#key(id));
|
|
70
|
+
if (!raw) return {};
|
|
71
|
+
return JSON.parse(raw);
|
|
72
|
+
}
|
|
73
|
+
async start(id) {
|
|
74
|
+
return this.read(id);
|
|
75
|
+
}
|
|
76
|
+
async write(id, data) {
|
|
77
|
+
const now = /* @__PURE__ */ new Date();
|
|
78
|
+
const payload = {
|
|
79
|
+
...data,
|
|
80
|
+
createdAt: data.createdAt ?? now,
|
|
81
|
+
updatedAt: now
|
|
82
|
+
};
|
|
83
|
+
const client = this.#client();
|
|
84
|
+
if (client) await client.set(this.#key(id), JSON.stringify(payload), { EX: this.idleTimeoutS });
|
|
85
|
+
return payload;
|
|
86
|
+
}
|
|
87
|
+
async open() {
|
|
88
|
+
this.manager.log(`REDIS SESSIONS STORAGE ==> TTL natif idle (${this.idleTimeoutS}s)`, "INFO");
|
|
89
|
+
return 0;
|
|
90
|
+
}
|
|
91
|
+
close() {
|
|
92
|
+
return true;
|
|
93
|
+
}
|
|
94
|
+
async destroy(id) {
|
|
95
|
+
const client = this.#client();
|
|
96
|
+
if (client) await client.del(this.#key(id));
|
|
97
|
+
return true;
|
|
98
|
+
}
|
|
99
|
+
async gc() {}
|
|
100
|
+
/**
|
|
101
|
+
* Prolonge l'idle d'une session (timeout glissant) en repositionnant le TTL
|
|
102
|
+
* natif (`EXPIRE`, O(1)) — SANS réécrire la valeur (touch NIST/OWASP). C'est le
|
|
103
|
+
* touch le moins coûteux des stores. Clé absente / connexion fermée → no-op.
|
|
104
|
+
*
|
|
105
|
+
* @param idleSeconds - nouvel idle (défaut : l'idle configuré du store).
|
|
106
|
+
*/
|
|
107
|
+
async touch(id, idleSeconds) {
|
|
108
|
+
const client = this.#client();
|
|
109
|
+
if (!client) return;
|
|
110
|
+
await client.expire(this.#key(id), idleSeconds ?? this.idleTimeoutS);
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* Énumération admin (capacité optionnelle d'`ISessionStorage`) par **SCAN**
|
|
114
|
+
* non-bloquant (`MATCH <prefix>:*`, curseur), filtrable par `user`. Cold-path
|
|
115
|
+
* RARE (console admin, jamais le hot-path). `SCAN` est O(keyspace) → plafonné
|
|
116
|
+
* à {@link MAX_SCAN} (au-delà : listing partiel **journalisé**, pas silencieux).
|
|
117
|
+
* Connexion fermée → `[]`.
|
|
118
|
+
*/
|
|
119
|
+
async listAll(filter) {
|
|
120
|
+
const client = this.#client();
|
|
121
|
+
if (!client) return [];
|
|
122
|
+
const prefix = this.#prefix();
|
|
123
|
+
const match = `${prefix}:*`;
|
|
124
|
+
const prefixLen = prefix.length + 1;
|
|
125
|
+
const out = [];
|
|
126
|
+
let cursor = "0";
|
|
127
|
+
let scanned = 0;
|
|
128
|
+
do {
|
|
129
|
+
const res = await client.scan(cursor, {
|
|
130
|
+
MATCH: match,
|
|
131
|
+
COUNT: 200
|
|
132
|
+
});
|
|
133
|
+
cursor = res.cursor;
|
|
134
|
+
for (const key of res.keys) {
|
|
135
|
+
scanned++;
|
|
136
|
+
const raw = await client.get(key);
|
|
137
|
+
if (!raw) continue;
|
|
138
|
+
let data;
|
|
139
|
+
try {
|
|
140
|
+
data = JSON.parse(raw);
|
|
141
|
+
} catch {
|
|
142
|
+
continue;
|
|
143
|
+
}
|
|
144
|
+
if (filter?.user !== void 0 && data.user !== filter.user) continue;
|
|
145
|
+
out.push({
|
|
146
|
+
id: key.slice(prefixLen),
|
|
147
|
+
data
|
|
148
|
+
});
|
|
149
|
+
}
|
|
150
|
+
if (scanned >= 1e4) {
|
|
151
|
+
this.manager.log(`REDIS SESSIONS listAll: scan plafonné à ${MAX_SCAN} clés (listing admin partiel — envisager un index secondaire)`, "WARNING");
|
|
152
|
+
break;
|
|
153
|
+
}
|
|
154
|
+
} while (cursor !== "0");
|
|
155
|
+
return out;
|
|
156
|
+
}
|
|
157
|
+
/**
|
|
158
|
+
* {@inheritDoc ISessionStorage.listPage}
|
|
159
|
+
*
|
|
160
|
+
* **Curseur SCAN** : au plus UN passage `SCAN` par appel (cold-path admin).
|
|
161
|
+
* Capacité réduite ASSUMÉE et annoncée — pas de `total`, pas d'ordre global sur
|
|
162
|
+
* `updatedAt` (Redis n'a pas d'index secondaire ici), et la page peut compter
|
|
163
|
+
* moins d'éléments que `limit` (le filtre s'applique au batch scanné). Le client
|
|
164
|
+
* boucle tant que `hasNext`, en repassant `nextCursor`. La garantie qui compte
|
|
165
|
+
* est tenue : **le keyspace n'est jamais matérialisé** — au plus un batch.
|
|
166
|
+
*
|
|
167
|
+
* ⚠️ **`COUNT` n'est PAS un plafond** — c'est un indice d'effort par itération.
|
|
168
|
+
* Redis peut rendre plus de clés que demandé (typiquement un petit keyspace
|
|
169
|
+
* encodé en listpack : tout arrive en une fois). Sans précaution, la page
|
|
170
|
+
* dépasserait `limit` et violerait le contrat `IPage`. D'où le **curseur
|
|
171
|
+
* composite** `"<consommé>:<curseurRedis>"` : quand un batch contient plus que
|
|
172
|
+
* la page, on ne rend que `limit` éléments et on mémorise combien de clés du
|
|
173
|
+
* batch ont été consommées — la page suivante rejoue le MÊME `SCAN` et reprend
|
|
174
|
+
* là où on s'était arrêté. Coût : un re-scan du batch courant, payé uniquement
|
|
175
|
+
* sur un cold-path d'administration. Rien n'est perdu, rien ne déborde.
|
|
176
|
+
*/
|
|
177
|
+
async listPage(query) {
|
|
178
|
+
assertPageQuery(query, "cursor");
|
|
179
|
+
const limit = Math.max(1, Math.floor(query.limit));
|
|
180
|
+
const client = this.#client();
|
|
181
|
+
if (!client) return {
|
|
182
|
+
items: [],
|
|
183
|
+
limit,
|
|
184
|
+
hasNext: false,
|
|
185
|
+
nextCursor: null
|
|
186
|
+
};
|
|
187
|
+
const { scanCursor, skip } = decodeCursor(query.cursor);
|
|
188
|
+
const res = await client.scan(scanCursor, {
|
|
189
|
+
MATCH: `${this.#prefix()}:*`,
|
|
190
|
+
COUNT: limit
|
|
191
|
+
});
|
|
192
|
+
const next = String(res.cursor);
|
|
193
|
+
const prefixLen = this.#prefix().length + 1;
|
|
194
|
+
const items = [];
|
|
195
|
+
let consumed = 0;
|
|
196
|
+
for (const key of res.keys.slice(skip)) {
|
|
197
|
+
if (items.length >= limit) break;
|
|
198
|
+
consumed += 1;
|
|
199
|
+
const raw = await client.get(key);
|
|
200
|
+
if (!raw) continue;
|
|
201
|
+
let data;
|
|
202
|
+
try {
|
|
203
|
+
data = JSON.parse(raw);
|
|
204
|
+
} catch {
|
|
205
|
+
continue;
|
|
206
|
+
}
|
|
207
|
+
if (query.user !== void 0 && data.user !== query.user) continue;
|
|
208
|
+
if (query.authenticated !== void 0 && !!data.user !== query.authenticated) continue;
|
|
209
|
+
items.push({
|
|
210
|
+
id: key.slice(prefixLen),
|
|
211
|
+
data: {
|
|
212
|
+
...data,
|
|
213
|
+
Attributes: {},
|
|
214
|
+
flashBag: {}
|
|
215
|
+
}
|
|
216
|
+
});
|
|
217
|
+
}
|
|
218
|
+
const nextCursor = skip + consumed < res.keys.length ? encodeCursor(scanCursor, skip + consumed) : next === "0" ? null : encodeCursor(next, 0);
|
|
219
|
+
return {
|
|
220
|
+
items,
|
|
221
|
+
limit,
|
|
222
|
+
hasNext: nextCursor !== null,
|
|
223
|
+
nextCursor
|
|
224
|
+
};
|
|
225
|
+
}
|
|
226
|
+
/**
|
|
227
|
+
* {@inheritDoc ISessionStorage.countSessions}
|
|
228
|
+
*
|
|
229
|
+
* Un comptage exact exigerait un `SCAN` complet O(keyspace) → refusé même sur le
|
|
230
|
+
* cold-path admin : renvoie **`-1`** (« inconnu », capacité réduite Redis
|
|
231
|
+
* assumée). L'appelant affiche l'inconnu, il ne l'invente pas.
|
|
232
|
+
*/
|
|
233
|
+
countSessions(_query) {
|
|
234
|
+
return Promise.resolve(-1);
|
|
235
|
+
}
|
|
236
|
+
/**
|
|
237
|
+
* {@inheritDoc ISessionStorage.countDistinctUsers}
|
|
238
|
+
*
|
|
239
|
+
* Dédupliquer exige d'avoir tout vu : c'est le `SCAN` complet que
|
|
240
|
+
* {@link countSessions} refuse déjà, plus un ensemble à retenir en mémoire.
|
|
241
|
+
* Renvoie **`-1`** — la console affiche « — », elle n'invente pas un chiffre.
|
|
242
|
+
*/
|
|
243
|
+
countDistinctUsers(_query) {
|
|
244
|
+
return Promise.resolve(-1);
|
|
245
|
+
}
|
|
246
|
+
};
|
|
247
|
+
SessionsService.registerStorage("redis", RedisSessionStorage);
|
|
248
|
+
//#endregion
|
|
249
|
+
export { RedisSessionStorage as default };
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
//#region nodefony/src/buildClientOptions.ts
|
|
2
|
+
/**
|
|
3
|
+
* Construit la fonction `reconnectStrategy` de redis v6 à partir de la politique
|
|
4
|
+
* déclarative (`baseMs`/`maxMs`/`maxRetries`) — back-off linéaire borné.
|
|
5
|
+
*
|
|
6
|
+
* @returns une fonction `(retries) => délai ms | Error` consommée par le socket.
|
|
7
|
+
*/
|
|
8
|
+
function buildReconnectStrategy(policy) {
|
|
9
|
+
const { baseMs, maxMs, maxRetries } = policy;
|
|
10
|
+
return (retries) => {
|
|
11
|
+
if (maxRetries > 0 && retries >= maxRetries) return /* @__PURE__ */ new Error(`[@nodefony/redis] reconnexion abandonnée après ${retries} tentatives`);
|
|
12
|
+
return Math.min((retries + 1) * baseMs, maxMs);
|
|
13
|
+
};
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Assemble les options `createClient` (redis v6) d'une connexion nommée à partir
|
|
17
|
+
* de la config validée : `globalOptions` fusionné avec la surcharge de connexion.
|
|
18
|
+
*
|
|
19
|
+
* Précédence : `url` (si présent) > socket de connexion > `globalOptions.socket`.
|
|
20
|
+
* Quand `url` est fourni, host/port/auth en sont extraits par redis lui-même —
|
|
21
|
+
* on ne pose alors PAS de `socket.host/port` (ils seraient ignorés/conflictuels).
|
|
22
|
+
*
|
|
23
|
+
* redis v6 : RESP3 est le protocole par défaut (on l'assume — set/get/pub/sub
|
|
24
|
+
* inchangés côté API) mais `maintNotifications` y bascule à `"auto"` (souscrit aux
|
|
25
|
+
* push frames de maintenance Redis Enterprise + relâche les timeouts socket). On
|
|
26
|
+
* cible Redis OSS → on force `"disabled"` pour un comportement déterministe et
|
|
27
|
+
* zéro listener/frame superflu (règle perf-mémoire).
|
|
28
|
+
*
|
|
29
|
+
* @param config - config racine validée et gelée.
|
|
30
|
+
* @param connection - définition de la connexion (name/database/socket override).
|
|
31
|
+
* @returns options prêtes pour `createClient`.
|
|
32
|
+
*/
|
|
33
|
+
function buildClientOptions(config, connection) {
|
|
34
|
+
const global = config.globalOptions;
|
|
35
|
+
const reconnectStrategy = buildReconnectStrategy(global.socket.reconnectStrategy);
|
|
36
|
+
const options = {
|
|
37
|
+
name: connection.name,
|
|
38
|
+
database: connection.database,
|
|
39
|
+
maintNotifications: "disabled"
|
|
40
|
+
};
|
|
41
|
+
if (global.username) options.username = global.username;
|
|
42
|
+
if (global.password) options.password = global.password;
|
|
43
|
+
if (config.url) {
|
|
44
|
+
options.url = config.url;
|
|
45
|
+
options.socket = { reconnectStrategy };
|
|
46
|
+
return options;
|
|
47
|
+
}
|
|
48
|
+
const socket = {
|
|
49
|
+
...global.socket,
|
|
50
|
+
...connection.socket
|
|
51
|
+
};
|
|
52
|
+
options.socket = {
|
|
53
|
+
host: socket.host,
|
|
54
|
+
port: socket.port,
|
|
55
|
+
family: socket.family,
|
|
56
|
+
connectTimeout: socket.connectTimeout,
|
|
57
|
+
tls: socket.tls === true ? true : void 0,
|
|
58
|
+
reconnectStrategy
|
|
59
|
+
};
|
|
60
|
+
return options;
|
|
61
|
+
}
|
|
62
|
+
//#endregion
|
|
63
|
+
export { buildClientOptions };
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
import { nodefonyError } from "nodefony";
|
|
2
|
+
//#region nodefony/src/keyNamespace.ts
|
|
3
|
+
/**
|
|
4
|
+
* Cloison des clés Redis **par application**.
|
|
5
|
+
*
|
|
6
|
+
* ── Le problème ────────────────────────────────────────────────────────────
|
|
7
|
+
* Un serveur Redis se mutualise très naturellement : c'est peu coûteux, et la
|
|
8
|
+
* `database` (0 par défaut) donne l'illusion d'une séparation. Elle n'en est pas
|
|
9
|
+
* une — elle ne cloisonne ni le pub/sub, ni quoi que ce soit dès lors que deux
|
|
10
|
+
* applications utilisent le même index, ce qui est le cas par défaut.
|
|
11
|
+
*
|
|
12
|
+
* Or les clés étaient nommées en dur : `nf:sess:<id>`, `nf:tok:<id>`,
|
|
13
|
+
* `nf:wac:<id>`. Deux applications côte à côte écrivaient donc dans le même
|
|
14
|
+
* espace, et l'écran Sessions de l'une **listait les sessions de l'autre** — son
|
|
15
|
+
* balayage `nf:sess:*` ne pouvait pas faire la différence. Ce ne sont pas des
|
|
16
|
+
* messages qui fuyaient, ce sont des identités.
|
|
17
|
+
*
|
|
18
|
+
* ── La cloison ─────────────────────────────────────────────────────────────
|
|
19
|
+
* Même règle que `backplane.namespace` côté temps réel, où la même classe de
|
|
20
|
+
* défaut a déjà été corrigée : une cloison explicite, sinon le nom de
|
|
21
|
+
* l'application. Sans cloison résolue, le préfixe historique est conservé — une
|
|
22
|
+
* application seule sur son Redis n'a rien à séparer, et son espace de clés ne
|
|
23
|
+
* doit pas changer sous ses pieds.
|
|
24
|
+
*
|
|
25
|
+
* ── Ce que la cloison sépare, et ce qu'elle NE sépare PAS ──────────────────
|
|
26
|
+
* Elle sépare des **applications**, jamais les instances d'une même application.
|
|
27
|
+
* La distinction est vitale : c'est elle qui décide si une session survit au
|
|
28
|
+
* load-balancer.
|
|
29
|
+
*
|
|
30
|
+
* ```
|
|
31
|
+
* 10 pods de « boutique » → nf:boutique:sess:<id> ← un seul espace
|
|
32
|
+
* « intranet » à côté → nf:intranet:sess:<id> ← espace disjoint
|
|
33
|
+
* ```
|
|
34
|
+
*
|
|
35
|
+
* La cloison est dérivée de `kernel.projectName`, c'est-à-dire du nom de
|
|
36
|
+
* l'application **dans son code** : tous ses pods calculent donc la même. Un
|
|
37
|
+
* utilisateur connecté via le pod 3 est reconnu par le pod 7 — le partage des
|
|
38
|
+
* sessions entre instances est justement ce qu'on attend d'un store Redis, et il
|
|
39
|
+
* reste intact.
|
|
40
|
+
*
|
|
41
|
+
* C'est pourquoi la cloison n'est SURTOUT pas dérivée de quelque chose de propre
|
|
42
|
+
* à l'instance (nom d'hôte, PID) : ce serait donner à chaque pod son propre
|
|
43
|
+
* espace de sessions, donc déconnecter l'utilisateur à chaque requête qui change
|
|
44
|
+
* de pod. Le backplane temps réel, lui, dérive bien un `originId` par instance —
|
|
45
|
+
* mais pour un tout autre usage (ne pas se réémettre à soi-même).
|
|
46
|
+
*
|
|
47
|
+
* Corollaire à connaître : deux DÉPLOIEMENTS de la même application
|
|
48
|
+
* (préproduction et production) portent le même nom, donc la même cloison. S'ils
|
|
49
|
+
* partagent un Redis, il faut leur poser un `keyNamespace` explicite — la même
|
|
50
|
+
* règle que `backplane.namespace`.
|
|
51
|
+
*
|
|
52
|
+
* ── Pourquoi l'application en TÊTE ─────────────────────────────────────────
|
|
53
|
+
* `nf:<app>:sess` plutôt que `nf:sess:<app>`. Les deux cloisonnent aussi bien,
|
|
54
|
+
* mais seul le premier laisse un opérateur voir — ou purger — une application
|
|
55
|
+
* entière d'un seul motif (`nf:boutique:*`). Un namespace placé en fin de préfixe
|
|
56
|
+
* éparpille les clés d'une même application sous chaque type de donnée.
|
|
57
|
+
*/
|
|
58
|
+
/** Caractères admis dans une cloison — alignés sur `backplane.namespace`. */
|
|
59
|
+
const NAMESPACE_PATTERN = /^[\w.-]+$/;
|
|
60
|
+
/**
|
|
61
|
+
* Compose le préfixe de clés d'un store, cloisonné par application.
|
|
62
|
+
*
|
|
63
|
+
* @param base - préfixe historique du store (`nf:sess`, `nf:tok`, `nf:wac`).
|
|
64
|
+
* @param namespace - cloison de l'application ; vide ou absente → pas de cloison.
|
|
65
|
+
* @returns `nf:<namespace>:<type>` si une cloison est posée, `base` sinon.
|
|
66
|
+
* @throws nodefonyError si la cloison contient autre chose que des caractères de
|
|
67
|
+
* mot, `.` ou `-`. Le `:` est le séparateur de clé : l'accepter permettrait de
|
|
68
|
+
* fabriquer un préfixe recouvrant celui d'une autre application, et un `*` de
|
|
69
|
+
* transformer un balayage en filet dérivant.
|
|
70
|
+
*/
|
|
71
|
+
function resolveKeyPrefix(base, namespace) {
|
|
72
|
+
const ns = namespace?.trim();
|
|
73
|
+
if (!ns) return base;
|
|
74
|
+
if (!NAMESPACE_PATTERN.test(ns)) throw new nodefonyError(`Cloison de clés Redis invalide : "${ns}". Caractères autorisés : lettres, chiffres, "_", "." et "-" — ni ":" (séparateur de clé) ni "*" (joker de balayage), qui permettraient à une application d'atteindre l'espace de clés d'une autre.`);
|
|
75
|
+
const separator = base.indexOf(":");
|
|
76
|
+
if (separator === -1) return `${base}:${ns}`;
|
|
77
|
+
return `${base.slice(0, separator)}:${ns}:${base.slice(separator + 1)}`;
|
|
78
|
+
}
|
|
79
|
+
//#endregion
|
|
80
|
+
export { resolveKeyPrefix };
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
//#region 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
|
+
//#endregion
|
|
69
|
+
export { MAX_SCAN, decodeCursor, encodeCursor, scanOrZero };
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @nodefony/redis — Accès Redis générique pour Nodefony.
|
|
3
|
+
*
|
|
4
|
+
* Module d'infrastructure : gère N connexions Redis nommées (lib `redis` v6) à
|
|
5
|
+
* partir d'une config validée par Zod. Il N'IMPOSE aucun usage — il expose le
|
|
6
|
+
* client Redis brut par connexion (`RedisService.getClient(name)`), donc on
|
|
7
|
+
* l'utilise pour TOUT : cache clé-valeur, sessions, files (streams/lists),
|
|
8
|
+
* compteurs, verrous, pub/sub… Les couches qui le consomment (P13.5
|
|
9
|
+
* `RedisBackplane` realtime, P5.12 `RedisSessionStorage`) sont AILLEURS — ce
|
|
10
|
+
* module reste un fournisseur d'accès neutre.
|
|
11
|
+
*
|
|
12
|
+
* Trois connexions par défaut (`main`/`publish`/`subscribe`) : un client Redis
|
|
13
|
+
* abonné (SUBSCRIBE) ne peut plus émettre de commandes normales → le pub/sub
|
|
14
|
+
* impose des clients dédiés. `main` sert les commandes clé-valeur / storage.
|
|
15
|
+
*
|
|
16
|
+
* Voir aussi : CLAUDE.md (décisions figées), MEMORY.md (internals IA),
|
|
17
|
+
* README.md (usage humain), docs/ (doc vulgarisée surfacée dans Studio).
|
|
18
|
+
*/
|
|
19
|
+
import { Kernel, Module } from "nodefony";
|
|
20
|
+
import * as redis from "redis";
|
|
21
|
+
import RedisService from "./nodefony/service/redis.js";
|
|
22
|
+
import { defineRedisConfig, redisConfigJsonSchema } from "./nodefony/config/defineModuleConfig.js";
|
|
23
|
+
import type { IRedisConfig, IRedisConfigInput } from "./nodefony/interfaces/IRedisConfig.js";
|
|
24
|
+
declare module "nodefony" {
|
|
25
|
+
interface NodefonyModuleConfig {
|
|
26
|
+
"@nodefony/redis": IRedisConfigInput;
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
declare class Redis extends Module<IRedisConfig> {
|
|
30
|
+
/** Module optionnel : un échec de son boot ne tue jamais le process (résilience Ph.3). */
|
|
31
|
+
static critical: boolean;
|
|
32
|
+
constructor(kernel: Kernel);
|
|
33
|
+
/** JSON Schema de la config redis → data plane admin (config riche Studio). */
|
|
34
|
+
configSchema(): unknown;
|
|
35
|
+
/**
|
|
36
|
+
* Valide la config (défauts + `module.options` + surcharge env) au boot via
|
|
37
|
+
* `defineRedisConfig`, et l'expose au container sous `redisConfig` pour que le
|
|
38
|
+
* `RedisService` la consomme sans redupliquer la validation. Plante propre
|
|
39
|
+
* avec messages clairs si la config est invalide (cf convention Zod figée
|
|
40
|
+
* 2026-05-28).
|
|
41
|
+
*/
|
|
42
|
+
onKernelRegister(): Promise<this>;
|
|
43
|
+
}
|
|
44
|
+
export default Redis;
|
|
45
|
+
export { RedisService, redis };
|
|
46
|
+
export { default as RedisSessionStorage } from "./nodefony/src/SessionStorage.js";
|
|
47
|
+
export { defineRedisConfig, redisConfigJsonSchema };
|
|
48
|
+
export { redisConfigSchema, type RedisConfig } from "./nodefony/config/config.js";
|
|
49
|
+
export type { IRedisConfig, IRedisConfigInput, IRedisConnectionConfig, } from "./nodefony/interfaces/IRedisConfig.js";
|
|
50
|
+
export { RedisTokenStore } from "./nodefony/src/RedisTokenStore.js";
|
|
51
|
+
export type { RedisClientLike } from "./nodefony/src/RedisTokenStore.js";
|
|
52
|
+
export { RedisWebAuthnCredentialStore } from "./nodefony/src/RedisWebAuthnCredentialStore.js";
|
|
53
|
+
export { registerRedisFrameworkStores } from "./nodefony/registerStores.js";
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
export declare const redisConfigSchema: z.ZodObject<{
|
|
3
|
+
enabled: z.ZodDefault<z.ZodBoolean>;
|
|
4
|
+
url: z.ZodOptional<z.ZodString>;
|
|
5
|
+
globalOptions: z.ZodDefault<z.ZodObject<{
|
|
6
|
+
socket: z.ZodDefault<z.ZodObject<{
|
|
7
|
+
host: z.ZodDefault<z.ZodString>;
|
|
8
|
+
port: z.ZodDefault<z.ZodNumber>;
|
|
9
|
+
family: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<4>, z.ZodLiteral<6>]>>;
|
|
10
|
+
connectTimeout: z.ZodDefault<z.ZodNumber>;
|
|
11
|
+
tls: z.ZodDefault<z.ZodBoolean>;
|
|
12
|
+
reconnectStrategy: z.ZodDefault<z.ZodObject<{
|
|
13
|
+
baseMs: z.ZodDefault<z.ZodNumber>;
|
|
14
|
+
maxMs: z.ZodDefault<z.ZodNumber>;
|
|
15
|
+
maxRetries: z.ZodDefault<z.ZodNumber>;
|
|
16
|
+
}, z.core.$strict>>;
|
|
17
|
+
}, z.core.$strict>>;
|
|
18
|
+
username: z.ZodOptional<z.ZodString>;
|
|
19
|
+
password: z.ZodOptional<z.ZodString>;
|
|
20
|
+
}, z.core.$strict>>;
|
|
21
|
+
keyNamespace: z.ZodOptional<z.ZodString>;
|
|
22
|
+
connections: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
|
|
23
|
+
name: z.ZodString;
|
|
24
|
+
database: z.ZodDefault<z.ZodNumber>;
|
|
25
|
+
socket: z.ZodOptional<z.ZodObject<{
|
|
26
|
+
host: z.ZodOptional<z.ZodString>;
|
|
27
|
+
port: z.ZodOptional<z.ZodNumber>;
|
|
28
|
+
family: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<4>, z.ZodLiteral<6>]>>;
|
|
29
|
+
connectTimeout: z.ZodOptional<z.ZodNumber>;
|
|
30
|
+
tls: z.ZodOptional<z.ZodBoolean>;
|
|
31
|
+
}, z.core.$strict>>;
|
|
32
|
+
}, z.core.$strict>>>;
|
|
33
|
+
}, z.core.$strict>;
|
|
34
|
+
/** Type de sortie (config normalisée + défauts appliqués). */
|
|
35
|
+
export type RedisConfig = z.infer<typeof redisConfigSchema>;
|
|
36
|
+
/**
|
|
37
|
+
* Défauts du module, matérialisés depuis le schéma (source unique). Toujours
|
|
38
|
+
* valides par construction ; passés au `super(..., config)` du Module class.
|
|
39
|
+
*/
|
|
40
|
+
declare const config: RedisConfig;
|
|
41
|
+
export default config;
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import type { IRedisConfig, IRedisConfigInput } from "../interfaces/IRedisConfig.js";
|
|
2
|
+
/**
|
|
3
|
+
* Builder type-safe de la configuration de `@nodefony/redis`.
|
|
4
|
+
*
|
|
5
|
+
* ⭐ TL;DR : MACHINERIE DE BOOT — on n'édite (presque) jamais ce fichier. Même
|
|
6
|
+
* pattern que `nodefony.config.ts` ↔ `defineConfig()` du core : `config.ts` PORTE
|
|
7
|
+
* la config (schéma + défauts), `define<X>Config()` la VALIDE au boot (parse +
|
|
8
|
+
* env + freeze) et publie le JSON Schema Studio.
|
|
9
|
+
*
|
|
10
|
+
* Principes (alignés sur `defineRealtimeConfig` / `defineSecurityConfig`) :
|
|
11
|
+
* - **Source unique** : `./config.ts` (Zod). Le builder VALIDE, applique l'ENV,
|
|
12
|
+
* puis GÈLE — il ne dévie jamais du schéma.
|
|
13
|
+
* - **Auto-documenté** : chaque champ Zod porte un `.describe()` →
|
|
14
|
+
* {@link redisConfigJsonSchema} produit un JSON Schema qu'un formulaire Studio
|
|
15
|
+
* (futur) consommera pour générer son UI d'édition.
|
|
16
|
+
*
|
|
17
|
+
* @param config - configuration brute (sections omises = défauts sûrs).
|
|
18
|
+
* @returns config validée, surchargée par l'env, et gelée.
|
|
19
|
+
* @throws ZodError si la config est invalide.
|
|
20
|
+
*/
|
|
21
|
+
export declare function defineRedisConfig(config?: IRedisConfigInput): IRedisConfig;
|
|
22
|
+
/**
|
|
23
|
+
* JSON Schema introspectable de la config Redis — destiné au formulaire
|
|
24
|
+
* d'édition Studio (futur) et à la documentation générée.
|
|
25
|
+
*/
|
|
26
|
+
export declare function redisConfigJsonSchema(): unknown;
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import type { z } from "zod";
|
|
2
|
+
import type { redisConfigSchema } from "../config/config.js";
|
|
3
|
+
/**
|
|
4
|
+
* Configuration normalisée et gelée de `@nodefony/redis` (sortie du builder
|
|
5
|
+
* {@link defineRedisConfig}, lue par le `RedisService`).
|
|
6
|
+
*
|
|
7
|
+
* Type dérivé du schéma Zod — NE PAS redéclarer les champs à la main (ils
|
|
8
|
+
* divergeraient silencieusement de la source de vérité `config/config.ts`).
|
|
9
|
+
*/
|
|
10
|
+
export type IRedisConfig = z.infer<typeof redisConfigSchema>;
|
|
11
|
+
/**
|
|
12
|
+
* Entrée du builder `defineRedisConfig` — tous les champs portant un défaut
|
|
13
|
+
* sont optionnels (l'app ne fournit que ce qu'elle surcharge).
|
|
14
|
+
*/
|
|
15
|
+
export type IRedisConfigInput = z.input<typeof redisConfigSchema>;
|
|
16
|
+
/** Définition d'une connexion Redis nommée (sous-objet de `connections`). */
|
|
17
|
+
export type IRedisConnectionConfig = IRedisConfig["connections"][string];
|