@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.
Files changed (36) hide show
  1. package/LICENSE +544 -0
  2. package/README.md +110 -0
  3. package/dist/_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js +9 -0
  4. package/dist/_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js +6 -0
  5. package/dist/index.js +58 -0
  6. package/dist/nodefony/config/config.js +98 -0
  7. package/dist/nodefony/config/defineModuleConfig.js +90 -0
  8. package/dist/nodefony/interfaces/IRedisConfig.js +1 -0
  9. package/dist/nodefony/interfaces/index.js +1 -0
  10. package/dist/nodefony/registerStores.js +38 -0
  11. package/dist/nodefony/service/redis.js +177 -0
  12. package/dist/nodefony/src/Connection.js +111 -0
  13. package/dist/nodefony/src/RedisTokenStore.js +390 -0
  14. package/dist/nodefony/src/RedisWebAuthnCredentialStore.js +247 -0
  15. package/dist/nodefony/src/SessionStorage.js +249 -0
  16. package/dist/nodefony/src/buildClientOptions.js +63 -0
  17. package/dist/nodefony/src/keyNamespace.js +80 -0
  18. package/dist/nodefony/src/scanCursor.js +69 -0
  19. package/dist/types/index.d.ts +53 -0
  20. package/dist/types/nodefony/config/config.d.ts +41 -0
  21. package/dist/types/nodefony/config/defineModuleConfig.d.ts +26 -0
  22. package/dist/types/nodefony/interfaces/IRedisConfig.d.ts +17 -0
  23. package/dist/types/nodefony/interfaces/index.d.ts +5 -0
  24. package/dist/types/nodefony/registerStores.d.ts +5 -0
  25. package/dist/types/nodefony/service/redis.d.ts +82 -0
  26. package/dist/types/nodefony/src/Connection.d.ts +39 -0
  27. package/dist/types/nodefony/src/RedisTokenStore.d.ts +121 -0
  28. package/dist/types/nodefony/src/RedisWebAuthnCredentialStore.d.ts +108 -0
  29. package/dist/types/nodefony/src/SessionStorage.d.ts +87 -0
  30. package/dist/types/nodefony/src/buildClientOptions.d.ts +21 -0
  31. package/dist/types/nodefony/src/keyNamespace.d.ts +12 -0
  32. package/dist/types/nodefony/src/scanCursor.d.ts +50 -0
  33. package/docs/architecture.md +718 -0
  34. package/docs/configuration.md +773 -0
  35. package/docs/index.md +295 -0
  36. 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];
@@ -0,0 +1,5 @@
1
+ /**
2
+ * Barrel des interfaces publiques de `@nodefony/redis`.
3
+ * Réexporté par `index.ts` racine via `export type { ... }`.
4
+ */
5
+ export type { IRedisConfig, IRedisConfigInput, IRedisConnectionConfig, } from "./IRedisConfig.js";
@@ -0,0 +1,5 @@
1
+ /**
2
+ * Enregistre les fabriques de stores Redis dans les registres de
3
+ * `@nodefony/security`. Idempotent (guards) — rejouable sans effet.
4
+ */
5
+ export declare function registerRedisFrameworkStores(): void;