@nodefony/redis 10.0.0-alpha.9 → 10.0.0-beta.2

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/README.md CHANGED
@@ -10,7 +10,7 @@ sessions, files d'attente, compteurs, verrous, pub/sub — c'est vous qui décid
10
10
 
11
11
  ## Installation
12
12
 
13
- Module workspace du monorepo Nodefony. Déclaré dans `@modules()` racine.
13
+ Module workspace du monorepo Nodefony. Déclaré dans le manifeste `modules` de `nodefony.config.ts`.
14
14
 
15
15
  ```bash
16
16
  docker compose -f docker/docker-compose.yml up -d # Redis 7, password "nodefony-dev"
@@ -53,13 +53,14 @@ export default {
53
53
 
54
54
  ### Variables d'environnement
55
55
 
56
- | Variable | Effet |
57
- | ------------------- | -------------------------------------------------------- |
58
- | `NF_REDIS_URL` | URL complète `redis[s]://…` — **la forme qui l'emporte** |
59
- | `REDIS_URL` | même effet, alias posé par les hébergeurs — lu en SECOND |
60
- | `NF_REDIS_HOST` | hôte du serveur |
61
- | `NF_REDIS_PORT` | port (validé) |
62
- | `NF_REDIS_PASSWORD` | mot de passe (jamais committé) |
56
+ | Variable | Effet |
57
+ | ------------------------ | -------------------------------------------------------- |
58
+ | `NF_REDIS_URL` | URL complète `redis[s]://…` — **la forme qui l'emporte** |
59
+ | `REDIS_URL` | même effet, alias posé par les hébergeurs — lu en SECOND |
60
+ | `NF_REDIS_HOST` | hôte du serveur |
61
+ | `NF_REDIS_PORT` | port (validé) |
62
+ | `NF_REDIS_PASSWORD` | mot de passe (jamais committé) |
63
+ | `NF_REDIS_KEY_NAMESPACE` | cloison des clés de cette application (prioritaire) |
63
64
 
64
65
  Si les deux URL sont posées, **`NF_REDIS_URL` gagne** : c'est votre réglage, il passe
65
66
  devant celui que la plateforme d'hébergement a injecté.
@@ -1,4 +1,4 @@
1
- //#region \0@oxc-project+runtime@0.151.0/helpers/esm/decorate.js
1
+ //#region \0@oxc-project+runtime@0.152.0/helpers/esm/decorate.js
2
2
  function __decorate(decorators, target, key, desc) {
3
3
  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
4
4
  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -1,4 +1,4 @@
1
- //#region \0@oxc-project+runtime@0.151.0/helpers/esm/decorateMetadata.js
1
+ //#region \0@oxc-project+runtime@0.152.0/helpers/esm/decorateMetadata.js
2
2
  function __decorateMetadata(k, v) {
3
3
  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
4
4
  }
package/dist/index.js CHANGED
@@ -4,8 +4,8 @@ import { defineRedisConfig, redisConfigJsonSchema } from "./nodefony/config/defi
4
4
  import { RedisTokenStore } from "./nodefony/src/RedisTokenStore.js";
5
5
  import { RedisWebAuthnCredentialStore } from "./nodefony/src/RedisWebAuthnCredentialStore.js";
6
6
  import { registerRedisFrameworkStores } from "./nodefony/registerStores.js";
7
- import __decorateMetadata from "./_virtual/_@oxc-project_runtime@0.151.0/helpers/esm/decorateMetadata.js";
8
- import __decorate from "./_virtual/_@oxc-project_runtime@0.151.0/helpers/esm/decorate.js";
7
+ import __decorateMetadata from "./_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
8
+ import __decorate from "./_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
9
9
  import RedisSessionStorage from "./nodefony/src/SessionStorage.js";
10
10
  import { Kernel, Module, services } from "nodefony";
11
11
  import * as redis from "redis";
@@ -19,9 +19,9 @@ import { getTokenStoreFactory, getWebAuthnStoreFactory, registerTokenStore, regi
19
19
  */
20
20
  /** Résout le service redis du container — échec FRANC avec la cause exacte. */
21
21
  function resolveRedisService(store, container) {
22
- const service = container?.get?.("redis") ?? null;
22
+ const service = container?.get("redis") ?? null;
23
23
  if (!service) throw new Error(`${store} : service "redis" introuvable — le module @nodefony/redis est-il chargé (manifeste "modules") ?`);
24
- const kernel = service.module?.kernel ?? null;
24
+ const kernel = service.module.kernel ?? null;
25
25
  if (kernel && !runNeedsExternalServices(kernel)) throw new Error(`${store} : demandé EXPLICITEMENT dans un run qui n'ouvre aucune connexion. Le store serait créé sans client Redis : ses écritures seraient perdues et ses lectures rendraient vide, SANS erreur. ${durableStoreRemedy(false)} Un store "auto" n'atteint jamais ce point — il bascule en mémoire, véridiquement et avec sa raison ; seule une demande EXPLICITE arrive ici.`);
26
26
  return service;
27
27
  }
@@ -31,11 +31,11 @@ function resolveRedisService(store, container) {
31
31
  */
32
32
  function registerRedisFrameworkStores() {
33
33
  if (!getTokenStoreFactory("redis")) registerTokenStore("redis", (ctx) => {
34
- const service = resolveRedisService(`tokenStore "redis"`, ctx?.container);
35
- const days = ctx?.config?.tokenStore?.retentionRevokedDays;
34
+ const service = resolveRedisService(`tokenStore "redis"`, ctx.container);
35
+ const days = ctx.config.tokenStore.retentionRevokedDays;
36
36
  return RedisTokenStore.from(service, void 0, typeof days === "number" ? days * 864e5 : void 0);
37
37
  });
38
- if (!getWebAuthnStoreFactory("redis")) registerWebAuthnStore("redis", (ctx) => RedisWebAuthnCredentialStore.from(resolveRedisService(`passkeys.store "redis"`, ctx?.container)));
38
+ if (!getWebAuthnStoreFactory("redis")) registerWebAuthnStore("redis", (ctx) => RedisWebAuthnCredentialStore.from(resolveRedisService(`passkeys.store "redis"`, ctx.container)));
39
39
  }
40
40
  //#endregion
41
41
  export { registerRedisFrameworkStores };
@@ -132,7 +132,7 @@ var RedisService = class extends Service {
132
132
  if (!definition) throw new Error(`${this.name} connection "${name}" undefined in config`);
133
133
  const options = buildClientOptions(config, definition);
134
134
  const conn = new Connection(name, options, this);
135
- if (this.#connections === null) this.#connections = Object.create(null);
135
+ this.#connections ??= Object.create(null);
136
136
  this.#connections[name] = conn;
137
137
  await conn.create();
138
138
  this.fire("connection", conn.client, conn);
@@ -171,7 +171,7 @@ var RedisService = class extends Service {
171
171
  }
172
172
  return client;
173
173
  }
174
- if (!this.#unavailable) this.#unavailable = /* @__PURE__ */ new Set();
174
+ this.#unavailable ??= /* @__PURE__ */ new Set();
175
175
  if (!this.#unavailable.has(name)) {
176
176
  this.#unavailable.add(name);
177
177
  this.log(`connexion "${name}" indisponible (${client ? "socket fermé" : "jamais ouverte"}) — les consommateurs de cette connexion dégradent tant qu'elle ne revient pas`, "WARNING");
@@ -181,8 +181,8 @@ var RedisService = class extends Service {
181
181
  /** Ferme toutes les connexions ouvertes (idempotent). */
182
182
  async closeConnections() {
183
183
  if (!this.#connections) return;
184
- for (const name in this.#connections) try {
185
- await this.#connections[name].close();
184
+ for (const connection of Object.values(this.#connections)) try {
185
+ await connection.close();
186
186
  } catch (e) {
187
187
  this.log(e, "ERROR");
188
188
  }
@@ -83,7 +83,7 @@ var RedisTokenStore = class RedisTokenStore {
83
83
  }
84
84
  /** Préfixe effectif des clés, cloisonné par application (mémoïsé). */
85
85
  #prefix() {
86
- if (this.#prefixCache === null) this.#prefixCache = this.#resolvePrefix();
86
+ this.#prefixCache ??= this.#resolvePrefix();
87
87
  return this.#prefixCache;
88
88
  }
89
89
  #client() {
@@ -116,7 +116,7 @@ var RedisTokenStore = class RedisTokenStore {
116
116
  #encode(record) {
117
117
  const h = {};
118
118
  const put = (k, v) => {
119
- if (v !== null && v !== void 0) h[k] = String(v);
119
+ if (v !== null) h[k] = String(v);
120
120
  };
121
121
  put("id", record.id);
122
122
  put("kind", record.kind);
@@ -146,21 +146,22 @@ var RedisTokenStore = class RedisTokenStore {
146
146
  }
147
147
  /** Désérialise un HASH en record (`null` pour les champs absents). */
148
148
  #decode(h) {
149
- const str = (k) => k in h ? h[k] : null;
149
+ const str = (k) => h[k] ?? null;
150
150
  const num = (k) => k in h ? Number(h[k]) : null;
151
+ const req = (k) => h[k] ?? "";
151
152
  return {
152
- id: h.id,
153
+ id: req("id"),
153
154
  kind: h.kind,
154
- name: h.name,
155
+ name: req("name"),
155
156
  prefix: str("prefix"),
156
- subjectId: h.subjectId,
157
+ subjectId: req("subjectId"),
157
158
  subjectType: h.subjectType,
158
159
  tenantId: str("tenantId"),
159
160
  scopes: h.scopes ? JSON.parse(h.scopes) : [],
160
161
  audience: h.audience ? JSON.parse(h.audience) : [],
161
162
  resources: h.resources ? JSON.parse(h.resources) : null,
162
- secretHash: h.secretHash,
163
- hashAlg: h.hashAlg,
163
+ secretHash: req("secretHash"),
164
+ hashAlg: req("hashAlg"),
164
165
  clientId: str("clientId"),
165
166
  cnf: str("cnf"),
166
167
  family: str("family"),
@@ -253,7 +254,7 @@ var RedisTokenStore = class RedisTokenStore {
253
254
  MATCH: match,
254
255
  COUNT: 200
255
256
  });
256
- cursor = String(res.cursor);
257
+ cursor = res.cursor;
257
258
  for (const key of res.keys) {
258
259
  const h = await client.hGetAll(key);
259
260
  if (Object.keys(h).length > 0) out.push(this.#decode(h));
@@ -290,7 +291,7 @@ var RedisTokenStore = class RedisTokenStore {
290
291
  MATCH: `${this.#prefix()}:rec:*`,
291
292
  COUNT: limit
292
293
  });
293
- const next = String(res.cursor);
294
+ const next = res.cursor;
294
295
  const now = this.#now();
295
296
  const items = [];
296
297
  let consumed = 0;
@@ -58,7 +58,7 @@ var RedisWebAuthnCredentialStore = class RedisWebAuthnCredentialStore {
58
58
  }
59
59
  /** Préfixe effectif des clés, cloisonné par application (mémoïsé). */
60
60
  #prefix() {
61
- if (this.#prefixCache === null) this.#prefixCache = this.#resolvePrefix();
61
+ this.#prefixCache ??= this.#resolvePrefix();
62
62
  return this.#prefixCache;
63
63
  }
64
64
  #client() {
@@ -89,10 +89,11 @@ var RedisWebAuthnCredentialStore = class RedisWebAuthnCredentialStore {
89
89
  }
90
90
  /** Désérialise un HASH en credential (`lastUsedAt`/`nickname` absents → `null`/omis). */
91
91
  #decode(h) {
92
+ const req = (k) => h[k] ?? "";
92
93
  return {
93
- id: h.id,
94
- userId: h.userId,
95
- publicKey: h.publicKey,
94
+ id: req("id"),
95
+ userId: req("userId"),
96
+ publicKey: req("publicKey"),
96
97
  signCount: Number(h.signCount),
97
98
  transports: h.transports ? JSON.parse(h.transports) : [],
98
99
  backupEligible: h.backupEligible === "1",
@@ -194,7 +195,7 @@ var RedisWebAuthnCredentialStore = class RedisWebAuthnCredentialStore {
194
195
  MATCH: `${this.#prefix()}:cred:*`,
195
196
  COUNT: limit
196
197
  });
197
- const next = String(res.cursor);
198
+ const next = res.cursor;
198
199
  const items = [];
199
200
  let consumed = 0;
200
201
  for (const key of res.keys.slice(skip)) {
@@ -45,7 +45,7 @@ var RedisSessionStorage = class {
45
45
  * à la construction du storage).
46
46
  */
47
47
  #client() {
48
- if (!this.#service) this.#service = this.manager.get("redis") ?? null;
48
+ this.#service ??= this.manager.get("redis") ?? null;
49
49
  return this.#service?.getClient("main") ?? null;
50
50
  }
51
51
  /**
@@ -81,7 +81,10 @@ var RedisSessionStorage = class {
81
81
  updatedAt: now
82
82
  };
83
83
  const client = this.#client();
84
- if (client) await client.set(this.#key(id), JSON.stringify(payload), { EX: this.idleTimeoutS });
84
+ if (client) await client.set(this.#key(id), JSON.stringify(payload), { expiration: {
85
+ type: "EX",
86
+ value: this.idleTimeoutS
87
+ } });
85
88
  return payload;
86
89
  }
87
90
  async open() {
@@ -189,7 +192,7 @@ var RedisSessionStorage = class {
189
192
  MATCH: `${this.#prefix()}:*`,
190
193
  COUNT: limit
191
194
  });
192
- const next = String(res.cursor);
195
+ const next = res.cursor;
193
196
  const prefixLen = this.#prefix().length + 1;
194
197
  const items = [];
195
198
  let consumed = 0;
@@ -50,11 +50,11 @@ function buildClientOptions(config, connection) {
50
50
  ...connection.socket
51
51
  };
52
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,
53
+ ...socket.host !== void 0 && { host: socket.host },
54
+ ...socket.port !== void 0 && { port: socket.port },
55
+ ...socket.family !== void 0 && { family: socket.family },
56
+ ...socket.connectTimeout !== void 0 && { connectTimeout: socket.connectTimeout },
57
+ ...socket.tls && { tls: true },
58
58
  reconnectStrategy
59
59
  };
60
60
  return options;
@@ -127,7 +127,7 @@ service par la chaîne `"redis"` dans le conteneur, jamais par un `import`. `Red
127
127
  `import type`, effacé à la compilation. Résultat, aucune dépendance runtime ne circule entre l'infra
128
128
  et la sécurité, dans aucun sens — et le graphe de modules reste acyclique.
129
129
 
130
- **Charger le module suffit.** `Redis.onKernelRegister()` (`index.ts:54`) valide la configuration puis
130
+ **Charger le module suffit.** `Redis.onKernelRegister()` (`index.ts:64`) valide la configuration puis
131
131
  appelle `registerRedisFrameworkStores()` (`registerStores.ts:72`), qui inscrit les fabriques `redis`
132
132
  dans les registres de jetons et de passkeys. Le store de session, lui, s'auto-déclare à l'import du
133
133
  fichier (`SessionStorage.ts:323`). Aucune application n'a de câblage à écrire : il ne reste qu'à
@@ -191,7 +191,8 @@ class RedisDiagnosticController extends Controller {
191
191
  const main = redis?.getConnection("main");
192
192
  const client = redis?.getClient("main");
193
193
 
194
- const cle = `nf:sess:${session.id}`;
194
+ // Le préfixe porte la cloison de l'application : `nf:<app>:sess` (`keyPrefix()`).
195
+ const cle = `${redis?.keyPrefix("nf:sess")}:${session.id}`;
195
196
  // -2 = clé absente, -1 = clé sans TTL (anomalie ici), n > 0 = secondes restantes.
196
197
  const ttl = client && main?.connected ? await client.ttl(cle) : -2;
197
198
 
@@ -223,11 +224,11 @@ Puis, côté requête :
223
224
  ```bash
224
225
  curl -s -c cookies.txt http://127.0.0.1:5151/diagnostic/redis/session
225
226
  # {"connexions":["main","publish","subscribe"],"mainConnectee":true,
226
- # "cle":"nf:sess:9f2c…","ttlSecondes":1800}
227
+ # "cle":"nf:mon-app:sess:9f2c…","ttlSecondes":1800}
227
228
 
228
229
  # La même clé, vue du serveur — le TTL est bien porté par Redis lui-même.
229
- redis-cli TTL nf:sess:9f2c… # (integer) 1800
230
- redis-cli TYPE nf:sess:9f2c… # string
230
+ redis-cli TTL nf:mon-app:sess:9f2c… # (integer) 1800
231
+ redis-cli TYPE nf:mon-app:sess:9f2c… # string
231
232
  ```
232
233
 
233
234
  Rejoue la requête après quelques secondes : le TTL est **remonté à 1800**. C'est le timeout glissant,
@@ -290,7 +291,7 @@ démarrage raté, la connexion existe, le client existe — mais il est fermé.
290
291
  Prenons une lecture de session. Elle traverse exactement quatre gestes :
291
292
 
292
293
  1. Le store résout le service **paresseusement**, au premier accès seulement :
293
- `RedisSessionStorage.#client()` (`SessionStorage.ts:96`) mémorise le service puis demande
294
+ `RedisSessionStorage.#client()` (`SessionStorage.ts:89`) mémorise le service puis demande
294
295
  `getClient("main")` à chaque appel. La résolution tardive est nécessaire — l'ordre de démarrage
295
296
  des modules n'est pas garanti, le store est construit avant que Redis soit prêt.
296
297
  2. `RedisService.getClient()` (`redis.ts:220`) rend le client de la connexion nommée, ou `null`.
@@ -319,6 +320,11 @@ exclusifs. Le module tranche par la topologie : `main` pour les commandes, `publ
319
320
  Le module n'écrit rien. Ce qui suit appartient aux quatre stores et au backplane. Le tableau donne la
320
321
  vue d'ensemble ; les fiches détaillent les choix qui surprennent.
321
322
 
323
+ > [!NOTE]
324
+ > Les préfixes sont donnés **sans la cloison** de l'application, pour la lisibilité. Une application
325
+ > nommée les reçoit cloisonnés : `nf:sess` devient `nf:<application>:sess` (`RedisService.keyPrefix()`,
326
+ > `redis.ts:105`), la cloison venant de `keyNamespace` ou, à défaut, du nom du projet.
327
+
322
328
  | Clé | Structure | Durée de vie | Écrit par |
323
329
  | --------------------------- | -------------- | --------------------------------------------- | ----------------------------------------------- |
324
330
  | `nf:sess:<id>` | STRING (JSON) | TTL = idle, reposé à chaque écriture/touch | `RedisSessionStorage` |
@@ -340,7 +346,7 @@ pose **systématiquement** un `EX` : une clé de session sans TTL serait une ses
340
346
  défaut de sécurité, pas une commodité.
341
347
 
342
348
  L'expiration par inactivité (« idle ») est donc portée par Redis lui-même. Deux conséquences
343
- directes : `gc()` (`SessionStorage.ts:168`) est un **no-op** assumé — aucun balayage, aucune requête
349
+ directes : `gc()` (`SessionStorage.ts:151`) est un **no-op** assumé — aucun balayage, aucune requête
344
350
  de purge périodique — et `touch()` (`SessionStorage.ts:166`) se réduit à un `EXPIRE`, en O(1), **sans
345
351
  réécrire la valeur**. C'est le renouvellement le moins coûteux de tous les backends de session.
346
352
 
@@ -450,7 +456,7 @@ muet ne l'est pas. Voici ce que le code fait réellement, moment par moment.
450
456
  ### Moment 1 — Redis est absent au démarrage
451
457
 
452
458
  Le module est déclaré non critique (`index.ts:36`), et l'initialisation du service est **bornée dans
453
- le temps** : `Kernel.guardInitialize()` (`Kernel.ts:3943`) enveloppe l'appel dans un délai maximal de
459
+ le temps** : `Kernel.guardInitialize()` (`Kernel.ts:4043`) enveloppe l'appel dans un délai maximal de
454
460
  démarrage. Un `init()` qui pend ne gèle donc pas le boot ; l'échec est agrégé au rapport de démarrage,
455
461
  qui fait dire « démarrage DÉGRADÉ » au superviseur au lieu de mentir sur un état sain.
456
462
 
@@ -479,34 +485,23 @@ partent ; si la stratégie abandonne, elles sont rejetées.
479
485
  `Connection.connected` repasse à `false` — mais **`Connection.client` reste affecté**. C'est le point
480
486
  suivant.
481
487
 
482
- ### Moment 3 — le garde `if (!client)` et ce qu'il ne couvre pas
483
-
484
- Tous les stores commencent par le même geste : demander le client, et se replier s'il vaut `null`. Ce
485
- garde ne se déclenche que dans deux situations exactes :
486
-
487
- - **avant** l'initialisation du service — la carte des connexions vaut encore `null` ;
488
- - **après** `RedisService.closeConnections()` (`redis.ts:247`), qui remet la carte à `null`.
488
+ ### Moment 3 — le garde `if (!client)`, et ce qu'il couvre
489
489
 
490
- Il ne se déclenche **pas** après un `connect()` raté. Puisque la connexion est inscrite dans
491
- `#connections` avant d'être ouverte (`redis.ts:76`) et que `Connection.create()` affecte son client
492
- avant de le connecter (`Connection.ts:86`), `getClient("main")` rend alors un client **non nul et
493
- fermé**. La commande part donc, et la bibliothèque la rejette :
494
-
495
- ```
496
- ClientClosedError: The client is closed
497
- ```
490
+ Tous les stores commencent par le même geste : demander le client, et se replier s'il vaut `null`.
491
+ `RedisService.getClient()` (`redis.ts:218`) rend `null` dès que le socket **n'est pas ouvert** :
492
+ avant l'initialisation, après `RedisService.closeConnections()`, mais aussi après un `connect()` raté
493
+ — la connexion reste inscrite dans la carte avec un client jamais ouvert, et c'est l'ouverture
494
+ (`isOpen`), pas la présence, qui est testée. Pendant une reconnexion, en revanche, le socket est
495
+ ouvert : les commandes attendent dans la file hors ligne de la bibliothèque.
498
496
 
499
- > [!CAUTION]
500
- > Le repli documenté par les stores (« la connexion n'est pas ou plus ouverte → no-op ») décrit le
501
- > comportement du démarrage et de l'arrêt, **pas celui d'un incident**. Un Redis injoignable au
502
- > démarrage laisse une connexion fermée dans la carte : les stores ne se replient pas, ils propagent
503
- > l'erreur du client. Tester votre application « Redis éteint » consiste donc à l'éteindre **après**
504
- > le démarrage _et_ à la démarrer sans lui — les deux chemins ne sont pas les mêmes.
497
+ L'indisponibilité est **journalisée à la transition** : un `WARNING` « connexion indisponible » à la
498
+ première bascule (pas un par appel), puis un `INFO` « rétablie » quand la connexion revient.
499
+ `client-availability.test.ts` verrouille les trois comportements.
505
500
 
506
501
  ### Moment 4 — l'arrêt
507
502
 
508
503
  Le service s'abonne une fois pour toutes à la fin de vie du kernel dans son constructeur
509
- (`redis.ts:247`). `closeConnections()` (`redis.ts:247`) ferme chaque connexion, avale et journalise les
504
+ (`redis.ts:243`). `closeConnections()` (`redis.ts:243`) ferme chaque connexion, avale et journalise les
510
505
  échecs individuels, puis libère la carte. `Connection.close()` (`Connection.ts:146`) appelle la
511
506
  fermeture gracieuse du client — qui draine les commandes en vol — puis retire **explicitement** les
512
507
  cinq écouteurs via `Connection.#removeListeners()`, dans un bloc `finally` (`Connection.ts:122`).
@@ -521,9 +516,9 @@ L'ordre compte : les écouteurs sont retirés même si la fermeture échoue.
521
516
  | Démarrage du module en échec | non critique → agrégé au rapport, « démarrage DÉGRADÉ » | ✅ superviseur |
522
517
  | Perte de connexion en cours de vie | `ERROR` / `WARNING` / `INFO` + événements réémis | ✅ journal + événements |
523
518
  | Commande pendant la reconnexion | file d'attente hors ligne, puis envoi ou rejet | ✅ l'appelant reçoit le rejet |
524
- | Commande sur une connexion jamais ouverte | `ClientClosedError` propagé jusqu'à l'appelant | ✅ bruyant (mais pas le repli annoncé) |
525
- | Écriture de session, client `null` | **no-op muet** — la session n'est pas persistée, rien n'est journalisé | ❌ **silencieux** |
526
- | Écriture de jeton / passkey, client `null` | **no-op muet** | ❌ **silencieux** |
519
+ | Commande sur une connexion jamais ouverte | `getClient` → `null`, repli du store | ✅ `WARNING` à la transition |
520
+ | Écriture de session, client `null` | no-op — la session n'est pas persistée | ✅ annoncé au journal (transition) |
521
+ | Écriture de jeton / passkey, client `null` | no-op | ✅ annoncé au journal (transition) |
527
522
  | Backplane : module ou connexions absents | `WARNING` nommant la cause, hub laissé en local | ✅ modèle du genre |
528
523
  | Idempotence : `redis` demandé, module absent | échec franc au démarrage | ✅ fail-loud |
529
524
 
@@ -567,7 +562,7 @@ Redis rend **toutes** les clés d'un coup, quel que soit le `COUNT` demandé. Un
567
562
  alors la `limit` et violerait le contrat.
568
563
 
569
564
  D'où un curseur de la forme `"<déjà consommé>:<curseur Redis>"`, encodé par `encodeCursor()`
570
- (`SessionStorage.ts:33`). Quand un lot contient plus d'éléments que la page, le store n'en rend que
565
+ (`scanCursor.ts`). Quand un lot contient plus d'éléments que la page, le store n'en rend que
571
566
  `limit`, mémorise combien de clés du lot ont été consommées, et la page suivante **rejoue le même
572
567
  `SCAN`** pour reprendre à la bonne position. Le coût est un re-parcours du lot courant, payé
573
568
  uniquement sur un chemin d'administration. Les trois stores partagent ce mécanisme, à l'identique.
@@ -579,26 +574,23 @@ uniquement sur un chemin d'administration. Les trois stores partagent ce mécani
579
574
  > serveur qui a révélé le débordement. Sans `NF_REDIS_TEST_URL`, les bancs de pagination passent au vert
580
575
  > **sans avoir testé la seule chose que ce code résout**.
581
576
 
582
- ### Une asymétrie sur les curseurs hostiles
577
+ ### Les curseurs hostiles
583
578
 
584
579
  Le curseur arrive de l'extérieur (chaîne de requête d'un écran d'administration, client qui rejoue une
585
580
  page) : il n'est pas digne de confiance. Un curseur `SCAN` valide est toujours une suite de chiffres.
586
581
 
587
- Le store de session s'en protège : `scanOrZero()` (`scanCursor.ts:68`) impose le format et retombe
588
- sur `"0"` sinon — repartir du début est faux au pire d'une page, transmettre une valeur arbitraire
589
- échoue à coup sûr. Les stores de jetons (`RedisTokenStore.ts:35`) et de passkeys
590
- (`RedisWebAuthnCredentialStore.ts:31`) ne font **pas** cette validation : ils transmettent le curseur
591
- tel quel, et Redis rejette la commande. Un paramètre malformé y transforme une simple consultation en
592
- erreur.
582
+ Les trois stores s'en protègent par la même règle : `decodeCursor()` puis `scanOrZero()`
583
+ (`scanCursor.ts:68`) imposent le format et retombent sur `"0"` sinon — repartir du début est faux au
584
+ pire d'une page, transmettre une valeur arbitraire échouerait à coup sûr.
593
585
 
594
586
  ### Les vidages complets
595
587
 
596
588
  À côté de la pagination, deux méthodes déversent tout. `RedisSessionStorage.listAll()`
597
589
  (`SessionStorage.ts:181`) est **plafonnée** à un maximum de clés parcourues et journalise un
598
590
  `WARNING` quand elle tronque — listing partiel signalé, jamais silencieux.
599
- `RedisTokenStore.listAll()` (`RedisTokenStore.ts:378`), en revanche, boucle jusqu'à la fin du
600
- keyspace sans plafond : à grande échelle, préférez la pagination ou le système de référence SQL pour
601
- la gouvernance.
591
+ `RedisTokenStore.listAll()` (`RedisTokenStore.ts:378`) l'est aussi, à `MAX_SCAN` clés, avec le même
592
+ `WARNING` de listing partiel : à grande échelle, préférez la pagination ou le système de référence
593
+ SQL pour la gouvernance.
602
594
 
603
595
  Redaction : la page de sessions vide explicitement les sacs de données métier avant de sortir
604
596
  (`SessionStorage.ts:296`) — un enregistrement d'administration ne transporte jamais le contenu
@@ -635,7 +627,7 @@ c'est la contrepartie assumée de la séparation imposée par le protocole.
635
627
 
636
628
  - **Écran Stores** (`/nodefony/stores`) : pour chaque brique, le store réellement retenu au démarrage
637
629
  **et la raison**. La résolution est enregistrée par `SessionsService.initializeStorage()`
638
- (`sessions-service.ts:241`), qui journalise aussi la décision au format « `auto` → `redis` (infra
630
+ (`sessions-service.ts:258`), qui journalise aussi la décision au format « `auto` → `redis` (infra
639
631
  cache) ». Le choix automatique lui-même vient de `resolveAutoStore()` (`infra.ts:297`) : Redis n'est
640
632
  proposé que pour les natures non durables.
641
633
  - **Écran Sessions** : l'énumération y passe par `listPage` en mode curseur — d'où l'absence de
@@ -643,7 +635,7 @@ c'est la contrepartie assumée de la séparation imposée par le protocole.
643
635
  haut, rendue visible.
644
636
  - **Carte du module** (`/nodefony/modules/redis`) : documentation, symboles, tests, couverture, et la
645
637
  configuration validée. Le formulaire est dérivé du JSON Schema publié par `Redis.configSchema()`
646
- (`index.ts:43`), jamais écrit à la main.
638
+ (`index.ts:53`), jamais écrit à la main.
647
639
 
648
640
  Le module **n'expose pas** de plan de données propre (`/nodefony/redis/api/*`) : il n'a ni état
649
641
  métier ni introspection spécifique. Ce qui compte de lui — quelles connexions, quel store gagne — est
@@ -651,19 +643,17 @@ surfacé par les écrans transverses ci-dessus.
651
643
 
652
644
  ## ⚠️ Pièges (symptôme → cause → correction)
653
645
 
654
- | Symptôme | Cause (dans le code) | Correction |
655
- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
656
- | `ClientClosedError` alors que le store « dégrade en douceur » | Connexion posée dans `#connections` avant ouverture (`redis.ts:75`) → client non nul mais fermé | Traiter Redis comme faillible côté appelant ; surveiller le journal de démarrage |
657
- | Le démarrage pend sans Redis | Tentatives illimitées : `connect()` ne rend pas la main | Fixer un maximum fini ; hors production c'est déjà fait (`defineModuleConfig.ts:65`) |
658
- | Deux applications se renvoient leurs messages temps réel | Le pub/sub ignore le numéro de base — cloisonnement inexistant | Poser un namespace de canal explicite (`RedisBackplane.ts:31`) |
659
- | Les mêmes messages sont diffusés deux fois localement | Anti-echo court-circuité (identifiant d'origine partagé) | Un identifiant d'origine distinct par pod (`RedisBackplane.ts:212`) |
660
- | Un jeton expiré « revient » et n'expire plus | `HSET` recrée une clé absente, sans TTL | Le test d'existence préalable (`RedisTokenStore.ts:494`) — ne pas le retirer |
661
- | `?cursor=…` fait échouer un listing de jetons | Curseur transmis sans validation (`RedisTokenStore.ts:46`) | Ne pas fabriquer de curseur à la main ; rejouer `nextCursor` tel quel |
662
- | L'écran d'administration n'affiche aucun total | `countSessions` / `countTokens` rendent `-1` (comptage O(N) refusé) | Afficher « inconnu » ; ne jamais inventer un total |
663
- | Un `offset` envoyé n'a aucun effet | Le mode curseur ne lit que `cursor` (`SessionStorage.ts:196`) | Paginer par curseur, pas par décalage |
664
- | Des passkeys disparaissent | Politique d'éviction Redis (`allkeys-lru`) sur des clés **sans** TTL | `noeviction` + persistance sur l'instance qui porte les passkeys |
665
- | Une session survit à son âge maximal côté Redis | Le TTL glissant n'exprime pas l'absolu (`SessionStorage.ts:168`) | Comportement voulu — l'âge est refusé à la lecture, pas dans le stockage |
666
- | Une surcharge de connexion écrase l'hôte global | Un schéma partiel qui réapplique ses défauts clobberait la valeur globale | Ne poser que les champs voulus dans la surcharge — voir [Configuration](./configuration.md) |
646
+ | Symptôme | Cause (dans le code) | Correction |
647
+ | -------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
648
+ | Le démarrage pend sans Redis | Tentatives illimitées : `connect()` ne rend pas la main | Fixer un maximum fini ; hors production c'est déjà fait (`defineModuleConfig.ts:65`) |
649
+ | Deux applications se renvoient leurs messages temps réel | Le pub/sub ignore le numéro de base — cloisonnement inexistant | Poser un namespace de canal explicite (`RedisBackplane.ts:31`) |
650
+ | Les mêmes messages sont diffusés deux fois localement | Anti-echo court-circuité (identifiant d'origine partagé) | Un identifiant d'origine distinct par pod (`RedisBackplane.ts:212`) |
651
+ | Un jeton expiré « revient » et n'expire plus | `HSET` recrée une clé absente, sans TTL | Le test d'existence préalable (`RedisTokenStore.ts:494`) — ne pas le retirer |
652
+ | L'écran d'administration n'affiche aucun total | `countSessions` / `countTokens` rendent `-1` (comptage O(N) refusé) | Afficher « inconnu » ; ne jamais inventer un total |
653
+ | Un `offset` envoyé n'a aucun effet | Le mode curseur ne lit que `cursor` (`SessionStorage.ts:196`) | Paginer par curseur, pas par décalage |
654
+ | Des passkeys disparaissent | Politique d'éviction Redis (`allkeys-lru`) sur des clés **sans** TTL | `noeviction` + persistance sur l'instance qui porte les passkeys |
655
+ | Une session survit à son âge maximal côté Redis | Le TTL glissant n'exprime pas l'absolu (`SessionStorage.ts:168`) | Comportement voulu — l'âge est refusé à la lecture, pas dans le stockage |
656
+ | Une surcharge de connexion écrase l'hôte global | Un schéma partiel qui réapplique ses défauts clobberait la valeur globale | Ne poser que les champs voulus dans la surcharge — voir [Configuration](./configuration.md) |
667
657
 
668
658
  ## 🧪 Tests & couverture
669
659
 
@@ -680,9 +670,9 @@ cette prose. Ce qui doit être dit ici, c'est **ce qui est prouvé, et par quoi*
680
670
 
681
671
  **Ce qui manque, et qu'il faut savoir :**
682
672
 
683
- - **Aucun test n'exerce la perte de connexion en cours de vie.** Le banc de robustesse simule un
684
- client `null` — un état que le service n'atteint qu'avant l'initialisation ou après la fermeture. Le
685
- chemin réellement emprunté lors d'un incident (client fermé, non nul) n'est couvert nulle part.
673
+ - **La perte de connexion en cours de vie n'est exercée que par son effet sur `getClient`**
674
+ (`client-availability.test.ts`) : une coupure réelle d'un serveur Redis pendant le trafic n'a pas
675
+ de banc dédié.
686
676
  - **La branche de reprise du curseur composite n'est atteinte qu'avec un serveur réel** (voir plus
687
677
  haut) : le double ne déborde jamais.
688
678
  - **Pas de banc de charge ni de test de mémoire dédiés** dans ce module — voir le skill
@@ -28,7 +28,7 @@ coverageModule: redis
28
28
  # Configuration de @nodefony/redis
29
29
 
30
30
  > Une seule question à trancher : **quelle machine Redis, et comment y entrer**. Tout le reste a un
31
- > défaut sûr. Cette page donne la liste complète des clés avec leur valeur d'usine réelle, les quatre
31
+ > défaut sûr. Cette page donne la liste complète des clés avec leur valeur d'usine réelle, les cinq
32
32
  > variables d'environnement et l'ordre exact dans lequel elles gagnent, puis six situations de
33
33
  > déploiement — du poste de développement au service managé chiffré. Ce que le module fait _dedans_
34
34
  > avec ces valeurs (cycle des connexions, reconnexion, dégradation) est décrit par la page voisine,
@@ -391,7 +391,7 @@ connections: {
391
391
 
392
392
  ## Variables d'environnement et ordre de précédence
393
393
 
394
- ### Les quatre variables lues
394
+ ### Les cinq variables lues
395
395
 
396
396
  Toutes sont appliquées **après** la validation, par `applyEnvOverrides()`
397
397
  (`defineModuleConfig.ts:23`).
@@ -402,6 +402,7 @@ Toutes sont appliquées **après** la validation, par `applyEnvOverrides()`
402
402
  | `NF_REDIS_HOST` | `globalOptions.socket.host` | Posée telle quelle, sans validation supplémentaire. |
403
403
  | `NF_REDIS_PORT` | `globalOptions.socket.port` | **Ignorée en silence** si ce n'est pas un entier de `1` à `65535`. |
404
404
  | `NF_REDIS_PASSWORD` | `globalOptions.password` | Le seul chemin recommandé pour le secret : jamais dans un fichier versionné. |
405
+ | `NF_REDIS_KEY_NAMESPACE` | `keyNamespace` | Prioritaire sur la config ; cloison de déploiement. |
405
406
 
406
407
  `REDIS_URL` est accepté comme **alias de plateforme** parce que c'est le nom que posent la plupart des
407
408
  hébergeurs. Quand les deux existent, la variable préfixée gagne — le préfixe `NF_` sert précisément à
@@ -534,7 +535,7 @@ abonné ne peut plus émettre de commandes normales. Une connexion unique rendra
534
535
  stockage mutuellement exclusifs.
535
536
 
536
537
  Ajouter une connexion se fait en nommant une nouvelle clé. La fusion du manifeste est **profonde** —
537
- `loadModulesFromManifest()` (`Kernel.ts:1656`) fusionne la configuration de `use()` sous les défauts
538
+ `loadModulesFromManifest()` (`Kernel.ts:1714`) fusionne la configuration de `use()` sous les défauts
538
539
  déjà matérialisés du module — donc les trois connexions d'usine restent en place :
539
540
 
540
541
  ```ts ignore
@@ -671,23 +672,23 @@ Mieux vaut le savoir en concevant l'infrastructure qu'en la déployant.
671
672
  Deux échecs très différents partagent le même symptôme apparent — « Redis ne marche pas » — et se
672
673
  règlent à des endroits opposés.
673
674
 
674
- **La configuration est invalide.** `Redis.onKernelRegister()` (`index.ts:54`) valide avant tout le
675
+ **La configuration est invalide.** `Redis.onKernelRegister()` (`index.ts:64`) valide avant tout le
675
676
  reste et refuse de démarrer sur une valeur hors bornes. Le message nomme le champ fautif
676
677
  (`index.ts:68`) :
677
678
 
678
679
  ```
679
- [@nodefony/redis] Invalid config: globalOptions.socket.port: Too big: expected number to be <=65535
680
+ [@nodefony/redis] configuration invalide — globalOptions.socket.port : Too big: expected number to be <=65535
680
681
  ```
681
682
 
682
683
  C'est un défaut de configuration : rien à chercher côté réseau.
683
684
 
684
685
  **Le serveur ne répond pas.** La configuration est bonne, l'ouverture échoue. Le module est déclaré
685
- **non critique** — `Redis.critical` (`index.ts:36`) vaut `false` — donc l'application démarre quand
686
+ **non critique** — `Redis.critical` (`index.ts:46`) vaut `false` — donc l'application démarre quand
686
687
  même, en état dégradé annoncé. Chaque connexion est tentée indépendamment et journalisée en `ERROR`
687
688
  par `RedisService.init()` (`redis.ts:123`) : une connexion en échec n'empêche pas les suivantes.
688
689
 
689
- Ce que ce démarrage dégradé implique côté appelants — pourquoi le garde `if (!client)` des stores ne
690
- suffit pas après une ouverture ratée, ce que devient une commande pendant une reconnexion — est
690
+ Ce que ce démarrage dégradé implique côté appelants — pourquoi le garde `if (!client)` des stores couvre
691
+ aussi une ouverture ratée, ce que devient une commande pendant une reconnexion — est
691
692
  détaillé dans [Architecture interne](./architecture.md), section « Résilience ». C'est la lecture à
692
693
  faire avant une mise en production.
693
694
 
@@ -696,7 +697,7 @@ faire avant une mise en production.
696
697
  <!-- prettier-ignore -->
697
698
  | Symptôme | Cause | Correction |
698
699
  | --- | --- | --- |
699
- | Une clé de configuration n'a aucun effet, aucune erreur | Clé inconnue du schéma : la validation Zod **écarte** les clés qu'elle ne connaît pas | Vérifier l'orthographe dans les tables ci-dessus ; contrôler la cible effective (§ Démarrage rapide) |
700
+ | Le démarrage échoue avec `configuration invalide — <chemin>` | Clé inconnue (faute de frappe) : le schéma est strict | Corriger l'orthographe d'après les tables ci-dessus |
700
701
  | L'hôte configuré est ignoré | Une `url` est présente — `buildClientOptions()` (`buildClientOptions.ts:45`) ne pose plus host/port | Retirer `NF_REDIS_URL`/`REDIS_URL`, ou tout mettre dans l'URL |
701
702
  | `NF_REDIS_PORT` semble sans effet | Valeur non entière ou hors `1..65535` : `applyEnvOverrides()` (`defineModuleConfig.ts:24`) l'ignore | Corriger la valeur — l'ignorance est silencieuse par conception |
702
703
  | Toutes les connexions atterrissent sur la même base | L'URL porte un chemin (`…/2`) qui écrase le `database` de chaque connexion | Déclarer l'URL sans chemin et laisser `database` cloisonner |
@@ -707,12 +708,11 @@ faire avant une mise en production.
707
708
  | Le module démarre mais n'ouvre rien | `enabled: false` — module chargé, inerte (`RedisService.init()` (`redis.ts:123`)) | Le réactiver, ou retirer le module du manifeste |
708
709
  | Le formulaire Studio annonce `maxRetries: 0` en développement | Le JSON Schema décrit le schéma, pas la superposition d'exécution | Lire la configuration effective du service |
709
710
  | Une valeur changée à chaud ne prend pas | La configuration est **gelée** après le démarrage (`defineRedisConfig()` (`defineModuleConfig.ts:103`)) | Redémarrer le process |
710
- | L'auto-complétion ne propose aucune clé dans `use()` | Le module ne s'inscrit pas au registre de types des configurations de modules | S'appuyer sur les tables de cette page ; une clé fautive ne sera pas signalée à la compilation |
711
711
 
712
712
  ## 📡 Observabilité — Studio
713
713
 
714
714
  - **Carte du module** (`/nodefony/modules/redis`) : la configuration validée, rendue par un formulaire
715
- **dérivé** du JSON Schema que publie `Redis.configSchema()` (`index.ts:43`). Les champs marqués
715
+ **dérivé** du JSON Schema que publie `Redis.configSchema()` (`index.ts:53`). Les champs marqués
716
716
  secrets — `url`, `password` — y sont masqués par construction, pas par une liste d'exclusion tenue
717
717
  à la main.
718
718
  - **Écran Stores** (`/nodefony/stores`) : pour chaque brique, le store réellement retenu au démarrage
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nodefony/redis",
3
- "version": "10.0.0-alpha.9",
3
+ "version": "10.0.0-beta.2",
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",
@@ -47,23 +47,23 @@
47
47
  "esm"
48
48
  ],
49
49
  "dependencies": {
50
- "redis": "6.2.1",
50
+ "redis": "6.3.0",
51
51
  "tslib": "2.8.1"
52
52
  },
53
53
  "devDependencies": {
54
- "@nodefony/framework": "^10.0.0-alpha.9",
55
- "@nodefony/http": "^10.0.0-alpha.9",
56
- "@nodefony/security": "^10.0.0-alpha.9",
57
- "@types/node": "26.6.2",
58
- "@vitest/coverage-v8": "5.0.1",
59
- "nodefony": "^10.0.0-alpha.9",
60
- "vitest": "5.0.1"
54
+ "@nodefony/framework": "^10.0.0-beta.2",
55
+ "@nodefony/http": "^10.0.0-beta.2",
56
+ "@nodefony/security": "^10.0.0-beta.2",
57
+ "@types/node": "26.6.3",
58
+ "@vitest/coverage-v8": "5.0.3",
59
+ "nodefony": "^10.0.0-beta.2",
60
+ "vitest": "5.0.3"
61
61
  },
62
62
  "peerDependencies": {
63
- "@nodefony/framework": "^10.0.0-alpha.9",
64
- "@nodefony/http": "^10.0.0-alpha.9",
65
- "@nodefony/security": "^10.0.0-alpha.9",
66
- "nodefony": "^10.0.0-alpha.9",
63
+ "@nodefony/framework": "^10.0.0-beta.2",
64
+ "@nodefony/http": "^10.0.0-beta.2",
65
+ "@nodefony/security": "^10.0.0-beta.2",
66
+ "nodefony": "^10.0.0-beta.2",
67
67
  "zod": "^4.6.5"
68
68
  },
69
69
  "repository": {