@nodefony/redis 10.0.0-beta.3 → 10.0.0-beta.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,9 +1,8 @@
1
- //#region \0@oxc-project+runtime@0.153.0/helpers/esm/decorate.js
1
+ // \0@oxc-project+runtime@0.155.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);
5
5
  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
6
6
  return c > 3 && r && Object.defineProperty(target, key, r), r;
7
7
  }
8
- //#endregion
9
8
  export { __decorate as default };
package/dist/index.js CHANGED
@@ -4,12 +4,11 @@ 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.153.0/helpers/esm/decorateMetadata.js";
8
- import __decorate from "./_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorate.js";
7
+ import __decorate from "./_virtual/_@oxc-project_runtime@0.155.0/helpers/esm/decorate.js";
9
8
  import RedisSessionStorage from "./nodefony/src/SessionStorage.js";
10
- import { Kernel, Module, services } from "nodefony";
9
+ import { Module, services } from "nodefony";
11
10
  import * as redis from "redis";
12
- //#region index.ts
11
+ // index.ts
13
12
  /**
14
13
  * @nodefony/redis — Accès Redis générique pour Nodefony.
15
14
  *
@@ -52,7 +51,6 @@ let Redis = class Redis extends Module {
52
51
  return this;
53
52
  }
54
53
  };
55
- Redis = __decorate([services([RedisService]), __decorateMetadata("design:paramtypes", [typeof Kernel === "undefined" ? Object : Kernel])], Redis);
54
+ Redis = __decorate([services([RedisService])], Redis);
56
55
  var redis_default = Redis;
57
- //#endregion
58
56
  export { RedisService, RedisSessionStorage, RedisTokenStore, RedisWebAuthnCredentialStore, redis_default as default, defineRedisConfig, redis, redisConfigJsonSchema, redisConfigSchema, registerRedisFrameworkStores };
@@ -1,5 +1,5 @@
1
1
  import { z } from "zod";
2
- //#region nodefony/config/config.ts
2
+ // nodefony/config/config.ts
3
3
  /**
4
4
  * @nodefony/redis — CONFIGURATION DU MODULE (schéma Zod = source unique).
5
5
  *
@@ -98,5 +98,4 @@ const redisConfigSchema = z.strictObject({
98
98
  * valides par construction ; passés au `super(..., config)` du Module class.
99
99
  */
100
100
  const config = redisConfigSchema.parse({});
101
- //#endregion
102
101
  export { config as default, redisConfigSchema };
@@ -1,6 +1,6 @@
1
1
  import { redisConfigSchema } from "./config.js";
2
2
  import { z } from "zod";
3
- //#region nodefony/config/configSchema.ts
3
+ // nodefony/config/configSchema.ts
4
4
  /**
5
5
  * JSON Schema de la configuration de `@nodefony/redis` — lu SANS démarrer
6
6
  * l'application, par `nodefony env` et la notice `.env.example`, qui y
@@ -15,5 +15,4 @@ import { z } from "zod";
15
15
  function configJsonSchema() {
16
16
  return z.toJSONSchema(redisConfigSchema);
17
17
  }
18
- //#endregion
19
18
  export { configJsonSchema };
@@ -1,7 +1,7 @@
1
1
  import { redisConfigSchema } from "./config.js";
2
2
  import { configJsonSchema } from "./configSchema.js";
3
3
  import { parseModuleConfig, resolveInfra } from "nodefony";
4
- //#region nodefony/config/defineModuleConfig.ts
4
+ // nodefony/config/defineModuleConfig.ts
5
5
  /**
6
6
  * Applique l'URL d'infrastructure de cache APRÈS le parse Zod.
7
7
  *
@@ -77,5 +77,4 @@ function defineRedisConfig(config = {}) {
77
77
  function redisConfigJsonSchema() {
78
78
  return configJsonSchema();
79
79
  }
80
- //#endregion
81
80
  export { defineRedisConfig, redisConfigJsonSchema };
@@ -2,7 +2,7 @@ import { RedisTokenStore } from "./src/RedisTokenStore.js";
2
2
  import { RedisWebAuthnCredentialStore } from "./src/RedisWebAuthnCredentialStore.js";
3
3
  import { durableStoreRemedy, runNeedsExternalServices } from "nodefony";
4
4
  import { getTokenStoreFactory, getWebAuthnStoreFactory, registerTokenStore, registerWebAuthnStore } from "@nodefony/security";
5
- //#region nodefony/registerStores.ts
5
+ // nodefony/registerStores.ts
6
6
  /**
7
7
  * AUTO-ENREGISTREMENT des backends framework portés par Redis — « charger le
8
8
  * module = ses backends deviennent sélectionnables par simple nom » (convention-
@@ -37,5 +37,4 @@ function registerRedisFrameworkStores() {
37
37
  });
38
38
  if (!getWebAuthnStoreFactory("redis")) registerWebAuthnStore("redis", (ctx) => RedisWebAuthnCredentialStore.from(resolveRedisService(`passkeys.store "redis"`, ctx.container)));
39
39
  }
40
- //#endregion
41
40
  export { registerRedisFrameworkStores };
@@ -2,7 +2,7 @@ import Connection from "../src/Connection.js";
2
2
  import { buildClientOptions } from "../src/buildClientOptions.js";
3
3
  import { resolveKeyPrefix } from "../src/keyNamespace.js";
4
4
  import { Nodefony, Service, runNeedsExternalServices } from "nodefony";
5
- //#region nodefony/service/redis.ts
5
+ // nodefony/service/redis.ts
6
6
  const serviceName = "redis";
7
7
  /**
8
8
  * Service Redis Nodefony — orchestre N connexions nommées (par défaut `main`,
@@ -192,5 +192,4 @@ var RedisService = class extends Service {
192
192
  return Nodefony.generateId();
193
193
  }
194
194
  };
195
- //#endregion
196
195
  export { RedisService as default };
@@ -1,6 +1,6 @@
1
1
  import { Service } from "nodefony";
2
2
  import { createClient } from "redis";
3
- //#region nodefony/src/Connection.ts
3
+ // nodefony/src/Connection.ts
4
4
  /**
5
5
  * Une connexion Redis nommée — enveloppe un client `redis` v6 et gère son cycle
6
6
  * de vie (création, écoute des événements, fermeture propre).
@@ -107,5 +107,4 @@ var Connection = class extends Service {
107
107
  }
108
108
  }
109
109
  };
110
- //#endregion
111
110
  export { Connection as default };
@@ -1,6 +1,6 @@
1
1
  import { MAX_SCAN, scanPage } from "./scanCursor.js";
2
2
  import { assertPageQuery } from "nodefony";
3
- //#region nodefony/src/RedisTokenStore.ts
3
+ // nodefony/src/RedisTokenStore.ts
4
4
  /**
5
5
  * Champ d'un jeton relu dont la forme n'est pas celle que ce store écrit : on
6
6
  * REFUSE l'enregistrement plutôt que de le compléter. Une audience vide retombe
@@ -441,5 +441,4 @@ var RedisTokenStore = class RedisTokenStore {
441
441
  return Promise.resolve(0);
442
442
  }
443
443
  };
444
- //#endregion
445
444
  export { MONOTONIC_SET_SCRIPT, RedisTokenStore };
@@ -1,6 +1,6 @@
1
1
  import { scanPage } from "./scanCursor.js";
2
2
  import { assertPageQuery } from "nodefony";
3
- //#region nodefony/src/RedisWebAuthnCredentialStore.ts
3
+ // nodefony/src/RedisWebAuthnCredentialStore.ts
4
4
  /** Préfixe namespacé des clés de credentials WebAuthn dans Redis. */
5
5
  /**
6
6
  * Préfixe HISTORIQUE des clés (identifiants WebAuthn). Utilisé tel quel par une application sans
@@ -251,5 +251,4 @@ var RedisWebAuthnCredentialStore = class RedisWebAuthnCredentialStore {
251
251
  };
252
252
  }
253
253
  };
254
- //#endregion
255
254
  export { RedisWebAuthnCredentialStore };
@@ -2,7 +2,7 @@ import { MAX_SCAN, scanPage } from "./scanCursor.js";
2
2
  import { SessionIndex, supportsScripts } from "./sessionIndex.js";
3
3
  import { assertPageQuery } from "nodefony";
4
4
  import { SessionsService } from "@nodefony/http";
5
- //#region nodefony/src/SessionStorage.ts
5
+ // nodefony/src/SessionStorage.ts
6
6
  /** Préfixe namespacé des clés de session dans Redis. */
7
7
  /**
8
8
  * Préfixe HISTORIQUE des clés de session. Il n'est utilisé tel quel que par une
@@ -394,5 +394,4 @@ var RedisSessionStorage = class {
394
394
  }
395
395
  };
396
396
  SessionsService.registerStorage("redis", RedisSessionStorage);
397
- //#endregion
398
397
  export { RedisSessionStorage as default };
@@ -1,4 +1,4 @@
1
- //#region nodefony/src/buildClientOptions.ts
1
+ // nodefony/src/buildClientOptions.ts
2
2
  /**
3
3
  * Construit la fonction `reconnectStrategy` de redis v6 à partir de la politique
4
4
  * déclarative (`baseMs`/`maxMs`/`maxRetries`) — back-off linéaire borné.
@@ -59,5 +59,4 @@ function buildClientOptions(config, connection) {
59
59
  };
60
60
  return options;
61
61
  }
62
- //#endregion
63
62
  export { buildClientOptions };
@@ -1,5 +1,5 @@
1
1
  import { nodefonyError } from "nodefony";
2
- //#region nodefony/src/keyNamespace.ts
2
+ // nodefony/src/keyNamespace.ts
3
3
  /**
4
4
  * Cloison des clés Redis **par application**.
5
5
  *
@@ -76,5 +76,4 @@ function resolveKeyPrefix(base, namespace) {
76
76
  if (separator === -1) return `${base}:${ns}`;
77
77
  return `${base.slice(0, separator)}:${ns}:${base.slice(separator + 1)}`;
78
78
  }
79
- //#endregion
80
79
  export { resolveKeyPrefix };
@@ -1,4 +1,4 @@
1
- //#region nodefony/src/scanCursor.ts
1
+ // nodefony/src/scanCursor.ts
2
2
  /**
3
3
  * Curseur de pagination `SCAN` — **règle unique** des trois stores Redis
4
4
  * (sessions, jetons, identifiants WebAuthn).
@@ -118,5 +118,4 @@ async function scanPage(scan, cursor, limit, accept) {
118
118
  };
119
119
  }
120
120
  }
121
- //#endregion
122
121
  export { MAX_SCAN, decodeCursor, encodeCursor, scanOrZero, scanPage };
@@ -1,4 +1,4 @@
1
- //#region nodefony/src/sessionIndex.ts
1
+ // nodefony/src/sessionIndex.ts
2
2
  /** Taille d'un lot de purge : borne le temps d'un script, qui bloque Redis. */
3
3
  const PRUNE_BATCH = 500;
4
4
  /**
@@ -181,5 +181,4 @@ var SessionIndex = class {
181
181
  function supportsScripts(client) {
182
182
  return typeof client === "object" && client !== null && "scriptLoad" in client && typeof client.scriptLoad === "function" && "evalSha" in client && typeof client.evalSha === "function";
183
183
  }
184
- //#endregion
185
184
  export { PRUNE_BATCH, SessionIndex, supportsScripts };
@@ -57,7 +57,7 @@ flowchart TD
57
57
  CSUB["Connection subscribe"]
58
58
  LIB["clients lib redis v6"]
59
59
 
60
- MOD -->|@services| SVC
60
+ MOD -->|"@services"| SVC
61
61
  SVC --> CMAIN
62
62
  SVC --> CPUB
63
63
  SVC --> CSUB
@@ -127,18 +127,18 @@ 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:64`) valide la configuration puis
131
- appelle `registerRedisFrameworkStores()` (`registerStores.ts:72`), qui inscrit les fabriques `redis`
130
+ **Charger le module suffit.** `Redis.onKernelRegister()` (`index.ts#Redis.onKernelRegister`) valide la configuration puis
131
+ appelle `registerRedisFrameworkStores()` (`registerStores.ts#registerRedisFrameworkStores`), 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
- fichier (`SessionStorage.ts:323`). Aucune application n'a de câblage à écrire : il ne reste qu'à
133
+ fichier (`SessionStorage.ts#RedisSessionStorage.listAll`). Aucune application n'a de câblage à écrire : il ne reste qu'à
134
134
  nommer le store — ou à laisser `auto` choisir.
135
135
 
136
- **Le module est déclaré non critique.** `Redis.critical` vaut `false` (`index.ts:36`) : un échec de
136
+ **Le module est déclaré non critique.** `Redis.critical` vaut `false` (`index.ts#nodefony`) : un échec de
137
137
  son démarrage ne tue jamais le process. C'est un choix assumé de disponibilité — dont cette page
138
138
  détaille exactement le prix dans « Résilience ».
139
139
 
140
140
  Le contrepoint de ces trois choix : la configuration, elle, est **stricte**. Une config invalide
141
- arrête le démarrage avec un message qui nomme le champ fautif (`index.ts:62`). Tout est dans
141
+ arrête le démarrage avec un message qui nomme le champ fautif (`index.ts#Redis.onKernelRegister`). Tout est dans
142
142
  [Configuration](./configuration.md) — cette page n'en reprend aucune clé.
143
143
 
144
144
  ## 🚀 Démarrage rapide
@@ -246,7 +246,7 @@ reposé à chaque écriture — et repositionné sans réécrire la valeur quand
246
246
  | Options | `nodefony/src/buildClientOptions.ts` | Traduire la config déclarative en options `createClient` (dont la reconnexion). |
247
247
 
248
248
  Le service porte sa carte en **allocation paresseuse** : `#connections` vaut `null` tant qu'aucune
249
- connexion n'est ouverte (`redis.ts:33`), et redevient `null` à la fermeture. Une application qui
249
+ connexion n'est ouverte (`redis.ts#RedisService.module`), et redevient `null` à la fermeture. Une application qui
250
250
  charge le module sans jamais ouvrir de connexion ne paie donc pas un seul objet.
251
251
 
252
252
  ### Le démarrage, étape par étape
@@ -277,11 +277,11 @@ sequenceDiagram
277
277
 
278
278
  Trois détails de ce schéma décident de tout le comportement en panne :
279
279
 
280
- 1. `RedisService.init()` (`redis.ts:123`) enveloppe **chaque** connexion dans son propre `try/catch` :
280
+ 1. `RedisService.init()` (`redis.ts#RedisService.init`) enveloppe **chaque** connexion dans son propre `try/catch` :
281
281
  une connexion qui échoue est journalisée en `ERROR` et les suivantes sont quand même tentées.
282
- 2. `RedisService.createConnection()` (`redis.ts:175`) inscrit la connexion dans `#connections`
283
- **avant** d'attendre son ouverture (`redis.ts:75`).
284
- 3. `Connection.create()` (`Connection.ts:86`) affecte `this.client` **avant** d'appeler `connect()`.
282
+ 2. `RedisService.createConnection()` (`redis.ts#RedisService.createConnection`) inscrit la connexion dans `#connections`
283
+ **avant** d'attendre son ouverture (`redis.ts#RedisService.connections`).
284
+ 3. `Connection.create()` (`Connection.ts#Connection.create`) affecte `this.client` **avant** d'appeler `connect()`.
285
285
 
286
286
  Les points 2 et 3 sont la cause d'un comportement contre-intuitif détaillé plus bas : après un
287
287
  démarrage raté, la connexion existe, le client existe — mais il est fermé.
@@ -291,10 +291,10 @@ démarrage raté, la connexion existe, le client existe — mais il est fermé.
291
291
  Prenons une lecture de session. Elle traverse exactement quatre gestes :
292
292
 
293
293
  1. Le store résout le service **paresseusement**, au premier accès seulement :
294
- `RedisSessionStorage.#client()` (`SessionStorage.ts:96`) mémorise le service puis demande
294
+ `RedisSessionStorage.#client()` (`SessionStorage.ts#RedisSessionStorage.#client`) mémorise le service puis demande
295
295
  `getClient("main")` à chaque appel. La résolution tardive est nécessaire — l'ordre de démarrage
296
296
  des modules n'est pas garanti, le store est construit avant que Redis soit prêt.
297
- 2. `RedisService.getClient()` (`redis.ts:220`) rend le client de la connexion nommée, ou `null`.
297
+ 2. `RedisService.getClient()` (`redis.ts#RedisService.getClient`) rend le client de la connexion nommée, ou `null`.
298
298
  3. Le store teste `null` et décide de son repli.
299
299
  4. La commande part sur le socket.
300
300
 
@@ -307,10 +307,10 @@ Le protocole Redis bascule un client en mode écoute dès qu'il s'abonne : il ne
307
307
  `GET`/`SET`. Une seule connexion partagée rendrait donc le temps réel et le stockage mutuellement
308
308
  exclusifs. Le module tranche par la topologie : `main` pour les commandes, `publish` pour l'émission,
309
309
  `subscribe` pour l'écoute. Les trois sont assemblées par `buildClientOptions()`
310
- (`buildClientOptions.ts:45`), qui fusionne les options globales avec la surcharge de la connexion.
310
+ (`buildClientOptions.ts#buildClientOptions`), qui fusionne les options globales avec la surcharge de la connexion.
311
311
 
312
312
  > [!NOTE]
313
- > `maintNotifications: "disabled"` est forcé dans les options (`buildClientOptions.ts:58`). En
313
+ > `maintNotifications: "disabled"` est forcé dans les options (`buildClientOptions.ts#buildClientOptions`). En
314
314
  > `redis` v6, le défaut RESP3 souscrit aux notifications de maintenance de Redis Enterprise et
315
315
  > relâche les délais du socket. Nodefony cible Redis OSS : on coupe, pour un comportement
316
316
  > déterministe et zéro trame superflue.
@@ -323,7 +323,7 @@ vue d'ensemble ; les fiches détaillent les choix qui surprennent.
323
323
  > [!NOTE]
324
324
  > Les préfixes sont donnés **sans la cloison** de l'application, pour la lisibilité. Une application
325
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.
326
+ > `redis.ts#RedisService.keyPrefix`), la cloison venant de `keyNamespace` ou, à défaut, du nom du projet.
327
327
 
328
328
  | Clé | Structure | Durée de vie | Écrit par |
329
329
  | --------------------------- | -------------- | --------------------------------------------- | ----------------------------------------------- |
@@ -341,13 +341,13 @@ vue d'ensemble ; les fiches détaillent les choix qui surprennent.
341
341
 
342
342
  ### `nf:sess:*` — la session, une chaîne et un TTL
343
343
 
344
- Une session est un blob JSON écrit d'un coup. `RedisSessionStorage.write()` (`SessionStorage.ts:165`)
344
+ Une session est un blob JSON écrit d'un coup. `RedisSessionStorage.write()` (`SessionStorage.ts#RedisSessionStorage.write`)
345
345
  pose **systématiquement** un `EX` : une clé de session sans TTL serait une session immortelle, donc un
346
346
  défaut de sécurité, pas une commodité.
347
347
 
348
348
  L'expiration par inactivité (« idle ») est donc portée par Redis lui-même. Deux conséquences
349
- directes : `gc()` (`SessionStorage.ts:151`) est un **no-op** assumé — aucun balayage, aucune requête
350
- de purge périodique — et `touch()` (`SessionStorage.ts:247`) se réduit à un `EXPIRE`, en O(1), **sans
349
+ directes : `gc()` (`SessionStorage.ts#RedisSessionStorage.read`) est un **no-op** assumé — aucun balayage, aucune requête
350
+ de purge périodique — et `touch()` (`SessionStorage.ts#RedisSessionStorage.touch`) se réduit à un `EXPIRE`, en O(1), **sans
351
351
  réécrire la valeur**. C'est le renouvellement le moins coûteux de tous les backends de session.
352
352
 
353
353
  L'expiration **absolue** (âge maximal, jamais prolongé) ne s'exprime pas par un TTL glissant. Elle est
@@ -357,22 +357,22 @@ survivre dans Redis jusqu'à la fin de son TTL d'inactivité, mais elle est refu
357
357
  ### `nf:tok:*` — les jetons, un HASH et quatre index
358
358
 
359
359
  Pourquoi un HASH plutôt qu'un blob JSON comme la session ? Parce qu'un jeton est **mis à jour en
360
- place** à chaque usage. `RedisTokenStore.markUsed()` (`RedisTokenStore.ts:533`) écrit un à trois
360
+ place** à chaque usage. `RedisTokenStore.markUsed()` (`RedisTokenStore.ts#RedisTokenStore.markUsed`) écrit un à trois
361
361
  champs (`lastUsedAt`, IP, agent) sans relire l'enregistrement, sans le réécrire, et **sans toucher au
362
362
  TTL**. Avec un blob, chaque appel d'API coûterait une lecture, une désérialisation, une réécriture —
363
363
  et remettrait en jeu la date d'expiration.
364
364
 
365
365
  Ce choix impose une précaution : `HSET` sur une clé absente la **recrée**, et une clé recréée n'a pas
366
- de TTL. Le store vérifie donc l'existence d'abord (`RedisTokenStore.ts:539`) et ne fait rien si
366
+ de TTL. Le store vérifie donc l'existence d'abord (`RedisTokenStore.ts#RedisClientLike.hSet`) et ne fait rien si
367
367
  l'identifiant est inconnu. Sans ce test, un jeton expiré ressusciterait, immortel, à sa prochaine
368
368
  utilisation.
369
369
 
370
370
  Les quatre index secondaires sont des SET (`subj`, `fam`) et des chaînes (`hash`, `revsub`). Aucun
371
371
  n'a de TTL : ils sont nettoyés **paresseusement**, quand une lecture tombe sur un membre dont
372
- l'enregistrement a expiré — voir `RedisTokenStore.findBySubject()` (`RedisTokenStore.ts:405`) et
373
- `RedisTokenStore.findByHash()` (`RedisTokenStore.ts:387`).
372
+ l'enregistrement a expiré — voir `RedisTokenStore.findBySubject()` (`RedisTokenStore.ts#RedisTokenStore.findBySubject`) et
373
+ `RedisTokenStore.findByHash()` (`RedisTokenStore.ts#RedisTokenStore.findByHash`).
374
374
 
375
- La révocation combine les deux régimes. `RedisTokenStore.#applyRevoke()` (`RedisTokenStore.ts:596`)
375
+ La révocation combine les deux régimes. `RedisTokenStore.#applyRevoke()` (`RedisTokenStore.ts#RedisTokenStore.#applyRevoke`)
376
376
  pose la date et la raison, puis — si le jeton n'avait **pas** d'expiration (cas d'un PAT) — lui donne
377
377
  un TTL égal à la durée de rétention. Un jeton révoqué reste donc consultable un temps, puis disparaît
378
378
  tout seul.
@@ -384,7 +384,7 @@ d'ailleurs pas de méthode de maintenance. Deux structures suffisent : un HASH p
384
384
  SET d'identifiants par utilisateur.
385
385
 
386
386
  Un point de conception mérite d'être connu : `countByUser()`
387
- (`RedisWebAuthnCredentialStore.ts:220`) utilise `SCARD`, en O(1), sans lire un seul HASH. Il peut donc
387
+ (`RedisWebAuthnCredentialStore.ts#RedisWebAuthnCredentialStore.countByUser`) utilise `SCARD`, en O(1), sans lire un seul HASH. Il peut donc
388
388
  **sur-compter** les membres orphelins qu'une lecture n'a pas encore nettoyés. L'écart est assumé et
389
389
  orienté **fail-closed** : au pire un enrôlement supplémentaire est refusé, jamais un de trop accepté.
390
390
 
@@ -421,26 +421,26 @@ sequenceDiagram
421
421
  Quatre propriétés à retenir.
422
422
 
423
423
  **Un seul canal, pas un par sujet.** Les canaux applicatifs voyagent **dans** l'enveloppe. Le
424
- backplane fait donc un unique `SUBSCRIBE` au démarrage (`RedisBackplane.ts:18`), jamais
424
+ backplane fait donc un unique `SUBSCRIBE` au démarrage (`RedisBackplane.ts#REDIS_RT_CHANNEL`), jamais
425
425
  d'abonnement dynamique. C'est ce qui rend le coût indépendant du nombre de canaux applicatifs.
426
426
 
427
427
  **Le cloisonnement n'est pas le numéro de base.** Le pub/sub Redis est **global au serveur** : il
428
428
  ignore complètement le `database`. Deux applications sur un Redis mutualisé se parleraient. D'où le
429
- suffixe de canal calculé par `resolveRedisChannel()` (`RedisBackplane.ts:31`) — issu de la config, ou
429
+ suffixe de canal calculé par `resolveRedisChannel()` (`RedisBackplane.ts#resolveRedisChannel`) — issu de la config, ou
430
430
  à défaut du nom du projet. Deux déploiements de la **même** application (préproduction et production)
431
431
  dérivent le même nom : il faut alors un namespace explicite.
432
432
 
433
433
  **L'anti-echo est structurel.** Redis renvoie à l'émetteur ce qu'il publie, puisque les connexions
434
434
  `publish` et `subscribe` appartiennent au même pod. Sans filtre, chaque message serait diffusé deux
435
435
  fois localement. Le tri d'entrée `RedisBackplane.#ingress()` compare donc l'identifiant d'origine à
436
- la réception (`RedisBackplane.ts:295`) et écarte les siens.
436
+ la réception (`RedisBackplane.ts#RedisBackplane.#ingress`) et écarte les siens.
437
437
 
438
438
  **La livraison est au mieux, jamais garantie.** Le pub/sub Redis ne persiste ni ne rejoue : un pod
439
439
  déconnecté rate ce qui a été émis pendant sa coupure. Le contrat l'assume au lieu de simuler une
440
440
  fiabilité que le support n'offre pas — c'est le client temps réel qui se resynchronise.
441
441
 
442
442
  Le branchement lui-même est **fail-soft annoncé** : la fabrique du pilote `redis`
443
- (`realtime/index.ts:108`) journalise un `WARNING` explicite — « module absent » ou « connexions
443
+ (`realtime/index.ts`) journalise un `WARNING` explicite — « module absent » ou « connexions
444
444
  indisponibles » — et rend `null`, ce qui laisse le hub en mode local. L'application continue de
445
445
  fonctionner sur un seul pod, et le journal dit pourquoi elle n'en fait pas plus.
446
446
 
@@ -455,25 +455,25 @@ muet ne l'est pas. Voici ce que le code fait réellement, moment par moment.
455
455
 
456
456
  ### Moment 1 — Redis est absent au démarrage
457
457
 
458
- Le module est déclaré non critique (`index.ts:36`), et l'initialisation du service est **bornée dans
459
- le temps** : `Kernel.guardInitialize()` (`Kernel.ts:4336`) enveloppe l'appel dans un délai maximal de
458
+ Le module est déclaré non critique (`index.ts#nodefony`), et l'initialisation du service est **bornée dans
459
+ le temps** : `Kernel.guardInitialize()` (`Kernel.ts#Kernel.guardInitialize`) enveloppe l'appel dans un délai maximal de
460
460
  démarrage. Un `init()` qui pend ne gèle donc pas le boot ; l'échec est agrégé au rapport de démarrage,
461
461
  qui fait dire « démarrage DÉGRADÉ » au superviseur au lieu de mentir sur un état sain.
462
462
 
463
463
  La politique de reconnexion, elle, joue un rôle inattendu **au tout premier `connect()`**.
464
- `buildReconnectStrategy()` (`buildClientOptions.ts:13`) rend un délai croissant borné, et une `Error`
464
+ `buildReconnectStrategy()` (`buildClientOptions.ts#buildReconnectStrategy`) rend un délai croissant borné, et une `Error`
465
465
  au-delà du nombre maximal de tentatives — mais seulement si ce maximum est fini. Or le défaut du
466
466
  schéma vaut `0`, c'est-à-dire **illimité** : avec ce réglage, `connect()` ne rend jamais la main
467
467
  tant que Redis ne répond pas.
468
468
 
469
469
  D'où un garde-fou spécifique au développement : `applyResilienceDefaults()`
470
- (`defineModuleConfig.ts:52`) borne les tentatives à un nombre fini **hors production**, quand
470
+ (`defineModuleConfig.ts#applyResilienceDefaults`) borne les tentatives à un nombre fini **hors production**, quand
471
471
  l'application ne l'a pas fixé elle-même. Sans lui, démarrer sans Redis faisait pendre le boot au lieu
472
472
  d'échouer proprement.
473
473
 
474
474
  ### Moment 2 — la connexion est perdue en cours de vie
475
475
 
476
- `Connection.create()` (`Connection.ts:86`) attache cinq écouteurs — `error`, `connect`, `ready`,
476
+ `Connection.create()` (`Connection.ts#Connection.create`) attache cinq écouteurs — `error`, `connect`, `ready`,
477
477
  `end`, `reconnecting` — qui font deux choses : journaliser et **réémettre** l'événement sur le
478
478
  service. La perte est donc visible dans le journal (`ERROR` sur l'erreur, `INFO` sur la fin,
479
479
  `WARNING` à chaque tentative) et observable par tout code qui écoute le service.
@@ -488,7 +488,7 @@ suivant.
488
488
  ### Moment 3 — le garde `if (!client)`, et ce qu'il couvre
489
489
 
490
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** :
491
+ `RedisService.getClient()` (`redis.ts#RedisService.getClient`) rend `null` dès que le socket **n'est pas ouvert** :
492
492
  avant l'initialisation, après `RedisService.closeConnections()`, mais aussi après un `connect()` raté
493
493
  — la connexion reste inscrite dans la carte avec un client jamais ouvert, et c'est l'ouverture
494
494
  (`isOpen`), pas la présence, qui est testée. Pendant une reconnexion, en revanche, le socket est
@@ -501,10 +501,10 @@ première bascule (pas un par appel), puis un `INFO` « rétablie » quand la co
501
501
  ### Moment 4 — l'arrêt
502
502
 
503
503
  Le service s'abonne une fois pour toutes à la fin de vie du kernel dans son constructeur
504
- (`redis.ts:243`). `closeConnections()` (`redis.ts:243`) ferme chaque connexion, avale et journalise les
505
- échecs individuels, puis libère la carte. `Connection.close()` (`Connection.ts:146`) appelle la
504
+ (`redis.ts#RedisService.closeConnections`). `closeConnections()` (`redis.ts#RedisService.closeConnections`) ferme chaque connexion, avale et journalise les
505
+ échecs individuels, puis libère la carte. `Connection.close()` (`Connection.ts#Connection.close`) appelle la
506
506
  fermeture gracieuse du client — qui draine les commandes en vol — puis retire **explicitement** les
507
- cinq écouteurs via `Connection.#removeListeners()`, dans un bloc `finally` (`Connection.ts:122`).
507
+ cinq écouteurs via `Connection.#removeListeners()`, dans un bloc `finally` (`Connection.ts#Connection.#removeListeners`).
508
508
  L'ordre compte : les écouteurs sont retirés même si la fermeture échoue.
509
509
 
510
510
  ### Synthèse — est-ce annoncé ?
@@ -523,17 +523,17 @@ L'ordre compte : les écouteurs sont retirés même si la fermeture échoue.
523
523
  | Idempotence : `redis` demandé, module absent | échec franc au démarrage | ✅ fail-loud |
524
524
 
525
525
  Les deux lignes rouges sont un **écart réel au principe** du framework : `RedisSessionStorage.write()`
526
- (`SessionStorage.ts:165`) rend la charge utile sans la persister et sans un mot. Sur la fenêtre
526
+ (`SessionStorage.ts#RedisSessionStorage.write`) rend la charge utile sans la persister et sans un mot. Sur la fenêtre
527
527
  étroite qu'il couvre — avant l'ouverture, après la fermeture — l'impact est faible ; le principe, lui,
528
- voudrait une trace. À l'inverse, `RedisSessionStorage.destroy()` (`SessionStorage.ts:216`) rend `true`
528
+ voudrait une trace. À l'inverse, `RedisSessionStorage.destroy()` (`SessionStorage.ts#RedisSessionStorage.destroy`) rend `true`
529
529
  sans connexion **délibérément** : l'appelant est une déconnexion, et lui répondre « échec » laisserait
530
530
  l'utilisateur croire qu'il est resté connecté.
531
531
 
532
532
  ## L'énumération d'administration — ce que la pagination sait et ne sait pas
533
533
 
534
534
  Trois stores savent énumérer pour un écran d'administration : les sessions
535
- (`SessionStorage.ts:258`), les jetons (`RedisTokenStore.ts:351`) et les passkeys
536
- (`RedisWebAuthnCredentialStore.ts:272`). Tous fonctionnent **en mode curseur**, et tous assument la
535
+ (`SessionStorage.ts#RedisSessionStorage.touch`), les jetons (`RedisTokenStore.ts#RedisTokenStore.put`) et les passkeys
536
+ (`RedisWebAuthnCredentialStore.ts#RedisWebAuthnCredentialStore.delete`). Tous fonctionnent **en mode curseur**, et tous assument la
537
537
  même capacité réduite.
538
538
 
539
539
  ### Ce que le mode curseur rend — et ce qu'il ignore
@@ -577,7 +577,7 @@ uniquement sur un chemin d'administration. Les trois stores partagent ce mécani
577
577
 
578
578
  > [!IMPORTANT]
579
579
  > **Ce mécanisme n'est pas exercé sans serveur Redis réel.** Le double utilisé par défaut,
580
- > `FakePaginatingRedis` (`session-pagination.test.ts:39`), découpe ses lots à exactement `COUNT`
580
+ > `FakePaginatingRedis` (`session-pagination.test.ts#FakePaginatingRedis`), découpe ses lots à exactement `COUNT`
581
581
  > clés — il ne déborde jamais, donc la branche de reprise n'est jamais atteinte. Or c'est un vrai
582
582
  > serveur qui a révélé le débordement. Sans `NF_REDIS_TEST_URL`, les bancs de pagination passent au vert
583
583
  > **sans avoir testé la seule chose que ce code résout**.
@@ -588,20 +588,20 @@ Le curseur arrive de l'extérieur (chaîne de requête d'un écran d'administrat
588
588
  page) : il n'est pas digne de confiance. Un curseur `SCAN` valide est toujours une suite de chiffres.
589
589
 
590
590
  Les trois stores s'en protègent par la même règle : `decodeCursor()` puis `scanOrZero()`
591
- (`scanCursor.ts:68`) imposent le format et retombent sur `"0"` sinon — repartir du début est faux au
591
+ (`scanCursor.ts#scanOrZero`) imposent le format et retombent sur `"0"` sinon — repartir du début est faux au
592
592
  pire d'une page, transmettre une valeur arbitraire échouerait à coup sûr.
593
593
 
594
594
  ### Les vidages complets
595
595
 
596
596
  À côté de la pagination, deux méthodes déversent tout. `RedisSessionStorage.listAll()`
597
- (`SessionStorage.ts:293`) est **plafonnée** à un maximum de clés parcourues et journalise un
597
+ (`SessionStorage.ts#RedisSessionStorage.listAll`) est **plafonnée** à un maximum de clés parcourues et journalise un
598
598
  `WARNING` quand elle tronque — listing partiel signalé, jamais silencieux.
599
- `RedisTokenStore.listAll()` (`RedisTokenStore.ts:435`) l'est aussi, à `MAX_SCAN` clés, avec le même
599
+ `RedisTokenStore.listAll()` (`RedisTokenStore.ts#RedisTokenStore.listAll`) l'est aussi, à `MAX_SCAN` clés, avec le même
600
600
  `WARNING` de listing partiel : à grande échelle, préférez la pagination ou le système de référence
601
601
  SQL pour la gouvernance.
602
602
 
603
603
  Redaction : la page de sessions vide explicitement les sacs de données métier avant de sortir
604
- (`SessionStorage.ts:296`) — un enregistrement d'administration ne transporte jamais le contenu
604
+ (`SessionStorage.ts#RedisSessionStorage.listAll`) — un enregistrement d'administration ne transporte jamais le contenu
605
605
  applicatif d'une session.
606
606
 
607
607
  ## ⚡ Performance & mémoire
@@ -609,21 +609,21 @@ applicatif d'une session.
609
609
  Le module suit la règle de coût du framework : ne rien allouer « au cas où », ne jamais laisser un
610
610
  écouteur derrière soi.
611
611
 
612
- - **Carte de connexions paresseuse** : `null` jusqu'à la première ouverture (`redis.ts:33`), `null` à
612
+ - **Carte de connexions paresseuse** : `null` jusqu'à la première ouverture (`redis.ts#RedisService.module`), `null` à
613
613
  nouveau après fermeture. Un objet `Object.create(null)` est utilisé plutôt qu'une `Map` — quelques
614
614
  entrées, accès par nom, c'est le moins cher.
615
- - **Écouteurs retirés explicitement** : `Connection.#removeListeners()` (`Connection.ts:122`) détache
615
+ - **Écouteurs retirés explicitement** : `Connection.#removeListeners()` (`Connection.ts#Connection.#removeListeners`) détache
616
616
  les cinq écouteurs et relâche les références. Sans ce geste, recréer une connexion accumulerait des
617
617
  fermetures à chaque cycle.
618
- - **Trames de maintenance coupées** (`buildClientOptions.ts:58`) : zéro écouteur et zéro trame
618
+ - **Trames de maintenance coupées** (`buildClientOptions.ts#buildClientOptions`) : zéro écouteur et zéro trame
619
619
  superflus sur un Redis OSS.
620
620
  - **Renouvellement de session en O(1)** : `EXPIRE` seul, sans réécrire la valeur
621
- (`redis/nodefony/src/SessionStorage.ts:253`). Sur une application authentifiée, c'est le geste le plus fréquent de tout
621
+ (`redis/nodefony/src/SessionStorage.ts#RedisSessionStorage.touch`). Sur une application authentifiée, c'est le geste le plus fréquent de tout
622
622
  le store.
623
623
  - **Aucun balayage périodique** : le TTL natif remplace le ramasse-miettes applicatif que les backends
624
624
  SQL doivent programmer.
625
625
  - **Coût du temps réel** : une publication cross-pod alloue une enveloppe et une sérialisation
626
- (`RedisBackplane.ts:197`) — sur le chemin de diffusion, jamais sur le chemin chaud HTTP. En
626
+ (`RedisBackplane.ts#RedisBackplane`) — sur le chemin de diffusion, jamais sur le chemin chaud HTTP. En
627
627
  mono-process, le backplane n'est même pas instancié.
628
628
  - **Les chemins coûteux sont froids** : `SCAN` est en O(keyspace). Il n'apparaît que dans les
629
629
  énumérations d'administration, jamais dans une lecture de session ou une vérification de jeton.
@@ -635,15 +635,15 @@ c'est la contrepartie assumée de la séparation imposée par le protocole.
635
635
 
636
636
  - **Écran Stores** (`/nodefony/stores`) : pour chaque brique, le store réellement retenu au démarrage
637
637
  **et la raison**. La résolution est enregistrée par `SessionsService.initializeStorage()`
638
- (`sessions-service.ts:258`), qui journalise aussi la décision au format « `auto` → `redis` (infra
639
- cache) ». Le choix automatique lui-même vient de `resolveAutoStore()` (`infra.ts:297`) : Redis n'est
638
+ (`sessions-service.ts#SessionsService.initializeStorage`), qui journalise aussi la décision au format « `auto` → `redis` (infra
639
+ cache) ». Le choix automatique lui-même vient de `resolveAutoStore()` (`infra.ts#resolveAutoStore`) : Redis n'est
640
640
  proposé que pour les natures non durables.
641
641
  - **Écran Sessions** : l'énumération y passe par `listPage` en mode curseur — d'où l'absence de
642
642
  compteur total et la navigation « page suivante » seule. C'est la capacité réduite décrite plus
643
643
  haut, rendue visible.
644
644
  - **Carte du module** (`/nodefony/modules/redis`) : documentation, symboles, tests, couverture, et la
645
645
  configuration validée. Le formulaire est dérivé du JSON Schema publié par `Redis.configSchema()`
646
- (`index.ts:53`), jamais écrit à la main.
646
+ (`index.ts#Redis.configSchema`), jamais écrit à la main.
647
647
 
648
648
  Le module **n'expose pas** de plan de données propre (`/nodefony/redis/api/*`) : il n'a ni état
649
649
  métier ni introspection spécifique. Ce qui compte de lui — quelles connexions, quel store gagne — est
@@ -651,17 +651,17 @@ surfacé par les écrans transverses ci-dessus.
651
651
 
652
652
  ## ⚠️ Pièges (symptôme → cause → correction)
653
653
 
654
- | Symptôme | Cause (dans le code) | Correction |
655
- | -------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
656
- | 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`) |
657
- | 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`) |
658
- | 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`) |
659
- | Un jeton expiré « revient » et n'expire plus | `HSET` recrée une clé absente, sans TTL | Le test d'existence préalable (`RedisTokenStore.ts:539`) — ne pas le retirer |
660
- | L'écran d'administration n'affiche aucun total | `countSessions` / `countTokens` rendent `-1` (comptage O(N) refusé) | Afficher « inconnu » ; ne jamais inventer un total |
661
- | Un `offset` envoyé n'a aucun effet | Le mode curseur ne lit que `cursor` (`SessionStorage.ts:308`) | Paginer par curseur, pas par décalage |
662
- | Des passkeys disparaissent | Politique d'éviction Redis (`allkeys-lru`) sur des clés **sans** TTL | `noeviction` + persistance sur l'instance qui porte les passkeys |
663
- | 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 |
664
- | 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) |
654
+ | Symptôme | Cause (dans le code) | Correction |
655
+ | -------------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
656
+ | 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#defineRedisConfig`) |
657
+ | 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#resolveRedisChannel`) |
658
+ | 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#RedisBackplane`) |
659
+ | Un jeton expiré « revient » et n'expire plus | `HSET` recrée une clé absente, sans TTL | Le test d'existence préalable (`RedisTokenStore.ts#RedisClientLike.hSet`) — ne pas le retirer |
660
+ | L'écran d'administration n'affiche aucun total | `countSessions` / `countTokens` rendent `-1` (comptage O(N) refusé) | Afficher « inconnu » ; ne jamais inventer un total |
661
+ | Un `offset` envoyé n'a aucun effet | Le mode curseur ne lit que `cursor` (`SessionStorage.ts#RedisSessionStorage.listAll`) | Paginer par curseur, pas par décalage |
662
+ | Des passkeys disparaissent | Politique d'éviction Redis (`allkeys-lru`) sur des clés **sans** TTL | `noeviction` + persistance sur l'instance qui porte les passkeys |
663
+ | Une session survit à son âge maximal côté Redis | Le TTL glissant n'exprime pas l'absolu (`SessionStorage.ts#RedisSessionStorage.write`) | Comportement voulu — l'âge est refusé à la lecture, pas dans le stockage |
664
+ | 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) |
665
665
 
666
666
  ## 🧪 Tests & couverture
667
667
 
@@ -694,7 +694,7 @@ cette prose. Ce qui doit être dit ici, c'est **ce qui est prouvé, et par quoi*
694
694
  > **Une suite verte ne prouve rien sans serveur Redis.** Les bancs d'intégration se **skippent**
695
695
  > quand l'infra manque, et un skip compte comme un succès : on peut lire « tout est vert » sur une
696
696
  > suite qui n'a rien exercé. La gate du module est déclarée une seule fois — `REDIS_GATE` dans
697
- > `scripts/test/vitest/gates.ts:351` — et la fin de run nomme la cible non exercée avec la commande exacte pour la
697
+ > `scripts/test/vitest/gates.ts#REDIS_GATE` — et la fin de run nomme la cible non exercée avec la commande exacte pour la
698
698
  > satisfaire. **Les variables et la commande docker se lisent là, pas ici** : les recopier dans cette
699
699
  > page les condamnerait à diverger.
700
700
 
@@ -64,9 +64,9 @@ flowchart TD
64
64
  Deux résolutions distinctes, souvent confondues :
65
65
 
66
66
  1. **La configuration du module** est résolue **une fois**, au démarrage, par `defineRedisConfig()`
67
- (`defineModuleConfig.ts:85`). Le résultat est **gelé** — plus personne ne le modifie ensuite.
67
+ (`defineModuleConfig.ts#defineRedisConfig`). Le résultat est **gelé** — plus personne ne le modifie ensuite.
68
68
  2. **Les options d'un client** sont assemblées **par connexion**, au moment de l'ouverture, par
69
- `buildClientOptions()` (`buildClientOptions.ts:45`). C'est là que `url` écrase l'hôte, et que la
69
+ `buildClientOptions()` (`buildClientOptions.ts#buildClientOptions`). C'est là que `url` écrase l'hôte, et que la
70
70
  surcharge d'une connexion se pose par-dessus le socket global.
71
71
 
72
72
  > [!TIP]
@@ -119,21 +119,21 @@ Le module ne possède pas de « fichier de valeurs par défaut » à côté d'un
119
119
  options ». Il possède **un schéma Zod commenté**, et tout en dérive :
120
120
 
121
121
  - **Les défauts** sont les `.default(...)` du schéma. Les valeurs d'usine effectivement chargées au
122
- démarrage sont produites par le schéma lui-même — `redisConfigSchema.parse({})` (`config.ts:248`) —
122
+ démarrage sont produites par le schéma lui-même — `redisConfigSchema.parse({})` (`config.ts#redisConfigSchema`) —
123
123
  et non retapées à la main.
124
- - **Le type TypeScript** est inféré, jamais redéclaré : `IRedisConfig` (`IRedisConfig.ts:11`) et son
125
- pendant d'entrée `IRedisConfigInput` (`IRedisConfig.ts:17`), où tout champ portant un défaut devient
124
+ - **Le type TypeScript** est inféré, jamais redéclaré : `IRedisConfig` (`IRedisConfig.ts#IRedisConfig`) et son
125
+ pendant d'entrée `IRedisConfigInput` (`IRedisConfig.ts#IRedisConfigInput`), où tout champ portant un défaut devient
126
126
  optionnel.
127
127
  - **Le texte d'aide** vit dans les `.describe()` du schéma, ce qui permet à
128
- `redisConfigJsonSchema()` (`defineModuleConfig.ts:101`) de publier un JSON Schema **documenté** que
128
+ `redisConfigJsonSchema()` (`defineModuleConfig.ts#redisConfigJsonSchema`) de publier un JSON Schema **documenté** que
129
129
  Studio transforme en formulaire.
130
130
  - **Les champs sensibles se déclarent** : `url` et `password` portent un `.meta({ secret: true })`
131
- (`config.ts:187`), ce qui les fait masquer là où la configuration est affichée.
131
+ (`config.ts#globalOptionsSchema`), ce qui les fait masquer là où la configuration est affichée.
132
132
 
133
133
  Le schéma reste volontairement **pur** : il ne lit jamais `process.env`. Sans cette règle, il
134
134
  deviendrait non déterministe et le JSON Schema publié dépendrait de la machine qui l'a produit. La
135
135
  lecture de l'environnement est donc une couche explicite, appliquée après coup par
136
- `applyEnvOverrides()` (`defineModuleConfig.ts:23`).
136
+ `applyEnvOverrides()` (`defineModuleConfig.ts#applyEnvOverrides`).
137
137
 
138
138
  Cette organisation est la convention de configuration du framework, tenue à deux fichiers et deux
139
139
  seulement : `config.ts` porte **le quoi** (schéma, contraintes, défauts), `defineModuleConfig.ts`
@@ -142,7 +142,7 @@ troisième fichier de configuration, dans un module Nodefony, est un signal d'al
142
142
 
143
143
  > [!NOTE]
144
144
  > La configuration du module est **immuable après le démarrage** : `defineRedisConfig()` rend un objet
145
- > gelé (`defineModuleConfig.ts:85`). Changer de serveur Redis suppose donc un redémarrage — aucune
145
+ > gelé (`defineModuleConfig.ts#defineRedisConfig`). Changer de serveur Redis suppose donc un redémarrage — aucune
146
146
  > clé n'est modifiable à chaud.
147
147
 
148
148
  ## 🚀 Démarrage rapide
@@ -153,27 +153,38 @@ vérifier.
153
153
  ### 1. Déclarer le module
154
154
 
155
155
  ```ts
156
+ // nodefony/config/redis.ts — le fragment du module, importé par le manifeste
157
+ import type { IRedisConfigInput } from "@nodefony/redis";
158
+
159
+ export const redisConfig = () =>
160
+ ({
161
+ globalOptions: {
162
+ socket: {
163
+ host: "127.0.0.1",
164
+ port: 6379,
165
+ // 5 s pour établir le socket : au-delà, on échoue au lieu de pendre.
166
+ connectTimeout: 5_000,
167
+ },
168
+ // Aucun secret ici : le mot de passe arrive par NF_REDIS_PASSWORD.
169
+ },
170
+ connections: {
171
+ // S'AJOUTE à main / publish / subscribe (fusion profonde des défauts) —
172
+ // une base séparée pour un cache applicatif qu'on pourra vider seul.
173
+ cache: { name: "cache", database: 1 },
174
+ },
175
+ }) satisfies IRedisConfigInput;
176
+ ```
177
+
178
+ ```ts ignore
156
179
  // nodefony.config.ts — l'orchestrateur de l'application
180
+ import { defineConfig, use } from "nodefony";
181
+ import { redisConfig } from "./nodefony/config/redis";
182
+
157
183
  export default defineConfig(() => ({
158
184
  modules: [
159
185
  // Redis d'abord : il enregistre ses fabriques de stores pendant
160
186
  // l'enregistrement des modules, donc avant tout consommateur.
161
- use("@nodefony/redis", {
162
- globalOptions: {
163
- socket: {
164
- host: "127.0.0.1",
165
- port: 6379,
166
- // 5 s pour établir le socket : au-delà, on échoue au lieu de pendre.
167
- connectTimeout: 5_000,
168
- },
169
- // Aucun secret ici : le mot de passe arrive par NF_REDIS_PASSWORD.
170
- },
171
- connections: {
172
- // S'AJOUTE à main / publish / subscribe (fusion profonde des défauts) —
173
- // une base séparée pour un cache applicatif qu'on pourra vider seul.
174
- cache: { name: "cache", database: 1 },
175
- },
176
- }),
187
+ use("@nodefony/redis", redisConfig()),
177
188
  "@nodefony/http",
178
189
  "@nodefony/framework",
179
190
  ],
@@ -247,7 +258,7 @@ export default RedisTargetController;
247
258
  ### 4. Ce qu'on observe
248
259
 
249
260
  Au démarrage, chaque connexion annonce sa cible — le point d'entrée est journalisé avec les
250
- identifiants masqués, par `Connection.#endpoint()` (`Connection.ts:70`) :
261
+ identifiants masqués, par `Connection.#endpoint()` (`Connection.ts#Connection.#endpoint`) :
251
262
 
252
263
  ```
253
264
  REDIS CONNECTION main CONNECT 127.0.0.1:6379
@@ -269,7 +280,7 @@ C'est la fusion profonde du manifeste, et c'est le comportement voulu.
269
280
 
270
281
  ## ⚙️ Toutes les clés du schéma
271
282
 
272
- Les défauts ci-dessous sont ceux du schéma, lus dans `redisConfigSchema` (`config.ts:200`). Une seule
283
+ Les défauts ci-dessous sont ceux du schéma, lus dans `redisConfigSchema` (`config.ts#redisConfigSchema`). Une seule
273
284
  valeur effective diffère du schéma au démarrage — `maxRetries`, traitée dans sa propre section.
274
285
 
275
286
  ### Racine
@@ -284,7 +295,7 @@ valeur effective diffère du schéma au démarrage — `maxRetries`, traitée da
284
295
  | `keyNamespace` | chaîne | nom de l'application | Cloison des **clés** par application sur un Redis mutualisé (cf ci-dessous). |
285
296
 
286
297
  Le sous-objet `connections` est un dictionnaire libre : la clé est le nom logique, la valeur décrit la
287
- connexion. Les trois entrées par défaut sont matérialisées dans `redisConfigSchema` (`config.ts:200`).
298
+ connexion. Les trois entrées par défaut sont matérialisées dans `redisConfigSchema` (`config.ts#redisConfigSchema`).
288
299
 
289
300
  #### `keyNamespace` — deux applications sur un même Redis
290
301
 
@@ -327,11 +338,11 @@ historiques (`nf:sess`, `nf:tok`, `nf:wac`) sont conservés tels quels.
327
338
 
328
339
  ### `globalOptions`
329
340
 
330
- | Clé | Type | Défaut | Effet |
331
- | ---------- | --------------- | ------------------------- | --------------------------------------------------------------------------------------------------------- |
332
- | `socket` | objet | défauts de `socketSchema` | Les options TCP/TLS communes. |
333
- | `username` | chaîne | _absent_ | Utilisateur ACL (Redis 6+). Absent avec un `password` présent = authentification héritée `requirepass`. |
334
- | `password` | chaîne (secret) | _absent_ | Mot de passe. Marqué secret dans `globalOptionsSchema` (`config.ts:173`) → masqué là où il s'afficherait. |
341
+ | Clé | Type | Défaut | Effet |
342
+ | ---------- | --------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
343
+ | `socket` | objet | défauts de `socketSchema` | Les options TCP/TLS communes. |
344
+ | `username` | chaîne | _absent_ | Utilisateur ACL (Redis 6+). Absent avec un `password` présent = authentification héritée `requirepass`. |
345
+ | `password` | chaîne (secret) | _absent_ | Mot de passe. Marqué secret dans `globalOptionsSchema` (`config.ts#globalOptionsSchema`) → masqué là où il s'afficherait. |
335
346
 
336
347
  `username` n'a **pas** de variable d'environnement dédiée : sur un serveur à ACL, il se pose dans la
337
348
  configuration de l'application (il n'est pas secret par lui-même), ou dans l'URL.
@@ -348,7 +359,7 @@ configuration de l'application (il n'est pas secret par lui-même), ou dans l'UR
348
359
  | `tls` | booléen | `false` | Chiffre le canal. Voir la limite de forme plus bas — c'est un drapeau, pas un jeu de certificats. |
349
360
  | `reconnectStrategy` | objet | défauts de `reconnectStrategySchema` | La politique de reconnexion, décrite juste après. |
350
361
 
351
- Ces contraintes sont portées par `socketSchema` (`config.ts:79`) : ce sont elles qui font échouer le
362
+ Ces contraintes sont portées par `socketSchema` (`config.ts#socketSchema`) : ce sont elles qui font échouer le
352
363
  démarrage plutôt que de laisser passer un port fantaisiste.
353
364
 
354
365
  ### `globalOptions.socket.reconnectStrategy`
@@ -360,7 +371,7 @@ démarrage plutôt que de laisser passer un port fantaisiste.
360
371
  | `maxRetries` | entier ≥ 0 | `0` | Nombre de tentatives avant abandon. `0` = illimité. **Valeur effective : voir ci-dessous.** |
361
372
 
362
373
  Ces trois valeurs sont déclaratives ; elles sont converties en fonction par
363
- `buildReconnectStrategy()` (`buildClientOptions.ts:13`) au moment d'assembler le client, parce qu'un
374
+ `buildReconnectStrategy()` (`buildClientOptions.ts#buildReconnectStrategy`) au moment d'assembler le client, parce qu'un
364
375
  schéma Zod ne sait pas transporter une fonction.
365
376
 
366
377
  ### `connections.<nom>`
@@ -371,13 +382,13 @@ schéma Zod ne sait pas transporter une fonction.
371
382
  | `database` | entier ≥ 0 | `0` | Base Redis sélectionnée. **N'isole que les commandes clé-valeur** — le pub/sub ignore la base. |
372
383
  | `socket` | objet partiel | _absent_ | Surcharge du socket pour cette connexion seulement ; les champs omis restent ceux du socket global. |
373
384
 
374
- `name` est le seul champ sans valeur d'usine dans tout le schéma (`connectionSchema` (`config.ts:143`)) :
385
+ `name` est le seul champ sans valeur d'usine dans tout le schéma (`connectionSchema` (`config.ts#connectionSchema`)) :
375
386
  une connexion sans nom serait invisible dans les journaux et côté serveur, on refuse donc de deviner.
376
387
 
377
388
  ### `connections.<nom>.socket` — la surcharge
378
389
 
379
390
  Cinq champs, tous facultatifs et **tous sans défaut** : `host`, `port`, `family`, `connectTimeout`,
380
- `tls`. C'est une décision de conception, portée par `socketOverrideSchema` (`config.ts:133`) : un
391
+ `tls`. C'est une décision de conception, portée par `socketOverrideSchema` (`config.ts#socketOverrideSchema`) : un
381
392
  schéma partiel qui réappliquerait ses propres défauts écraserait silencieusement le socket global —
382
393
  poser un `host` particulier ramènerait le port à `6379` sans le dire.
383
394
 
@@ -396,11 +407,11 @@ connections: {
396
407
  Deux mécanismes, et un seul endroit chacun :
397
408
 
398
409
  - **`NF_REDIS_URL`** (alias de plateforme `REDIS_URL`) est une variable d'**infrastructure** : résolue
399
- par `resolveInfra()` (`infra.ts:134`) et posée sur `url` par `applyEnvOverrides()`
400
- (`defineModuleConfig.ts:23`), après la validation.
410
+ par `resolveInfra()` (`infra.ts#resolveInfra`) et posée sur `url` par `applyEnvOverrides()`
411
+ (`defineModuleConfig.ts#applyEnvOverrides`), après la validation.
401
412
  - Les **quatre noms courts** sont DÉCLARÉS sur leur champ dans le schéma — `.meta({ env: "NF_REDIS_HOST" })`
402
- (`config.ts:90`). Le Kernel les pose avant la validation, par `applyEnvShortcuts()`
403
- (`envShortcuts.ts:146`) ; le schéma les valide donc comme une valeur de l'application.
413
+ (`config.ts#socketSchema`). Le Kernel les pose avant la validation, par `applyEnvShortcuts()`
414
+ (`envShortcuts.ts#applyEnvShortcuts`) ; le schéma les valide donc comme une valeur de l'application.
404
415
 
405
416
  | Variable | Ce qu'elle vise | Comportement |
406
417
  | ------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------- |
@@ -424,11 +435,11 @@ reprendre la main sur une variable imposée par l'environnement d'hébergement.
424
435
 
425
436
  1. Le **Kernel** pose les noms courts (`NF_REDIS_HOST`…) puis les surcharges `NF__REDIS__…` sur la
426
437
  configuration de l'application, avant toute validation.
427
- 2. `defineRedisConfig()` (`defineModuleConfig.ts:85`) valide — les défauts comblent ce que personne
438
+ 2. `defineRedisConfig()` (`defineModuleConfig.ts#defineRedisConfig`) valide — les défauts comblent ce que personne
428
439
  n'a dit, la validation refuse ce qui est hors bornes, d'où qu'il vienne.
429
- 3. `applyResilienceDefaults()` (`defineModuleConfig.ts:52`) — le garde-fou de reconnexion, qui
440
+ 3. `applyResilienceDefaults()` (`defineModuleConfig.ts#applyResilienceDefaults`) — le garde-fou de reconnexion, qui
430
441
  inspecte l'entrée **brute** pour savoir si l'application s'est prononcée.
431
- 4. `applyEnvOverrides()` (`defineModuleConfig.ts:23`) — l'URL d'infrastructure écrase `url`.
442
+ 4. `applyEnvOverrides()` (`defineModuleConfig.ts#applyEnvOverrides`) — l'URL d'infrastructure écrase `url`.
432
443
  5. `Object.freeze` — plus rien ne bouge.
433
444
 
434
445
  D'où la règle, dans cet ordre croissant d'autorité : **défauts du schéma → configuration de
@@ -442,13 +453,13 @@ l'application → environnement**. Le comportement est verrouillé par les tests
442
453
  > recompiler — mais c'est aussi la première cause de « ma configuration est ignorée ».
443
454
 
444
455
  Un cinquième geste vient plus tard, à l'ouverture de chaque connexion : la précédence **`url` ▸ socket
445
- de la connexion ▸ socket global**, tranchée par `buildClientOptions()` (`buildClientOptions.ts:45`)
446
- et prouvée par `config.test.ts:128`.
456
+ de la connexion ▸ socket global**, tranchée par `buildClientOptions()` (`buildClientOptions.ts#buildClientOptions`)
457
+ et prouvée par `config.test.ts`.
447
458
 
448
459
  ### Le double effet de l'URL d'infra
449
460
 
450
461
  `NF_REDIS_URL` n'est pas seulement la cible de ce module : c'est la déclaration d'une **infra de
451
- cache** pour le framework entier. `resolveAutoStore()` (`infra.ts:289`) s'en sert pour les briques
462
+ cache** pour le framework entier. `resolveAutoStore()` (`infra.ts#resolveAutoStore`) s'en sert pour les briques
452
463
  dont le store vaut `auto` :
453
464
 
454
465
  | Brique | Nature de la donnée | Avec une infra de cache déclarée |
@@ -471,7 +482,7 @@ jamais où les sessions ont atterri. Le comparatif transverse vit dans
471
482
  ### Quand une URL est posée, ce qui devient sans effet
472
483
 
473
484
  Dès que `url` est renseignée — par l'application ou par l'environnement — `buildClientOptions()`
474
- (`buildClientOptions.ts:45`) **ne pose plus** `socket.host` ni `socket.port` : ils entreraient en
485
+ (`buildClientOptions.ts#buildClientOptions`) **ne pose plus** `socket.host` ni `socket.port` : ils entreraient en
475
486
  conflit avec ceux de l'URL. Trois conséquences à connaître :
476
487
 
477
488
  <!-- prettier-ignore -->
@@ -505,8 +516,8 @@ définitivement.
505
516
  **Hors production, ce réglage fait pendre le démarrage.** Avec des tentatives illimitées, la première
506
517
  ouverture ne rend jamais la main tant que Redis ne répond pas ; la file d'attente hors ligne du client
507
518
  retient les commandes, et un démarrage sans serveur se transforme en attente infinie plutôt qu'en
508
- échec lisible. D'où `applyResilienceDefaults()` (`defineModuleConfig.ts:52`), qui borne les tentatives
509
- à `DEV_DEFAULT_MAX_RETRIES` (`defineModuleConfig.ts:32`) — cinq — quand, et seulement quand,
519
+ échec lisible. D'où `applyResilienceDefaults()` (`defineModuleConfig.ts#applyResilienceDefaults`), qui borne les tentatives
520
+ à `DEV_DEFAULT_MAX_RETRIES` (`defineModuleConfig.ts#DEV_DEFAULT_MAX_RETRIES`) — cinq — quand, et seulement quand,
510
521
  l'application ne s'est pas prononcée.
511
522
 
512
523
  | `NODE_ENV` | L'application fixe `maxRetries` ? | Valeur effective |
@@ -518,9 +529,9 @@ l'application ne s'est pas prononcée.
518
529
 
519
530
  La distinction « fixé / non fixé » se lit sur l'**entrée brute** de l'application, avant le parcours du
520
531
  schéma : une fois les défauts appliqués, un `0` d'usine serait indiscernable d'un `0` voulu. Les trois
521
- branches sont couvertes par les tests (`config.test.ts:85`, `config.test.ts:91`, `config.test.ts:99`).
532
+ branches sont couvertes par les tests (`config.test.ts`).
522
533
 
523
- **Le calcul du délai.** `buildReconnectStrategy()` (`buildClientOptions.ts:13`) rend
534
+ **Le calcul du délai.** `buildReconnectStrategy()` (`buildClientOptions.ts#buildReconnectStrategy`) rend
524
535
  `min((tentative + 1) × baseMs, maxMs)`, et une erreur — donc l'abandon — dès que le nombre de
525
536
  tentatives atteint `maxRetries`, si celui-ci est fini. Avec les valeurs d'usine, hors production :
526
537
 
@@ -545,7 +556,7 @@ abonné ne peut plus émettre de commandes normales. Une connexion unique rendra
545
556
  stockage mutuellement exclusifs.
546
557
 
547
558
  Ajouter une connexion se fait en nommant une nouvelle clé. La fusion du manifeste est **profonde** —
548
- `loadModulesFromManifest()` (`Kernel.ts:1794`) fusionne la configuration de `use()` sous les défauts
559
+ `loadModulesFromManifest()` (`Kernel.ts#Kernel.loadModulesFromManifest`) fusionne la configuration de `use()` sous les défauts
549
560
  déjà matérialisés du module — donc les trois connexions d'usine restent en place :
550
561
 
551
562
  ```ts ignore
@@ -622,7 +633,7 @@ Aucune ligne dans `nodefony.config.ts`. Le mot de passe voyage dans l'URL : trai
622
633
  secret entier, jamais comme une adresse.
623
634
 
624
635
  **La limite de forme à connaître** : le schéma n'expose qu'un **booléen** `tls`
625
- (`socketSchema` (`config.ts:79`)). Autorité de certification privée, certificat client, nom de
636
+ (`socketSchema` (`config.ts#socketSchema`)). Autorité de certification privée, certificat client, nom de
626
637
  serveur explicite — rien de tout cela n'est exprimable. Un service managé à certificat public
627
638
  fonctionne ; une authentification mutuelle par certificat n'est pas couverte par la configuration du
628
639
  module.
@@ -649,7 +660,7 @@ Deux réponses, selon l'intention.
649
660
  **Ne pas charger Redis du tout** : retirer le module du manifeste. C'est le plus propre quand aucune
650
661
  brique n'en dépend.
651
662
 
652
- **Le charger, inerte** : `enabled: false` (`redisConfigSchema` (`config.ts:202`)) laisse le module en
663
+ **Le charger, inerte** : `enabled: false` (`redisConfigSchema` (`config.ts#redisConfigSchema`)) laisse le module en
653
664
  place sans ouvrir un seul socket. Utile quand le manifeste est commun à plusieurs environnements.
654
665
 
655
666
  ```ts ignore
@@ -664,7 +675,7 @@ use("@nodefony/redis", { enabled: false });
664
675
  ### `cluster-sentinel` — ce qui n'est pas couvert
665
676
 
666
677
  Le module construit ses clients avec la fabrique **client simple** de la bibliothèque `redis` —
667
- `buildClientOptions()` (`buildClientOptions.ts:45`) produit des options de client, pas de grappe. Ni
678
+ `buildClientOptions()` (`buildClientOptions.ts#buildClientOptions`) produit des options de client, pas de grappe. Ni
668
679
  Redis Cluster (répartition par partitions, redirections `MOVED`/`ASK`), ni Sentinel (élection du
669
680
  maître) ne sont exprimables dans le schéma.
670
681
 
@@ -682,9 +693,9 @@ Mieux vaut le savoir en concevant l'infrastructure qu'en la déployant.
682
693
  Deux échecs très différents partagent le même symptôme apparent — « Redis ne marche pas » — et se
683
694
  règlent à des endroits opposés.
684
695
 
685
- **La configuration est invalide.** `Redis.onKernelRegister()` (`index.ts:64`) valide avant tout le
696
+ **La configuration est invalide.** `Redis.onKernelRegister()` (`index.ts#Redis.onKernelRegister`) valide avant tout le
686
697
  reste et refuse de démarrer sur une valeur hors bornes. Le message nomme le champ fautif
687
- (`index.ts:68`) :
698
+ (`index.ts#Redis.onKernelRegister`) :
688
699
 
689
700
  ```
690
701
  [@nodefony/redis] configuration invalide — globalOptions.socket.port : Too big: expected number to be <=65535
@@ -693,9 +704,9 @@ reste et refuse de démarrer sur une valeur hors bornes. Le message nomme le cha
693
704
  C'est un défaut de configuration : rien à chercher côté réseau.
694
705
 
695
706
  **Le serveur ne répond pas.** La configuration est bonne, l'ouverture échoue. Le module est déclaré
696
- **non critique** — `Redis.critical` (`index.ts:46`) vaut `false` — donc l'application démarre quand
707
+ **non critique** — `Redis.critical` (`index.ts#Redis.critical`) vaut `false` — donc l'application démarre quand
697
708
  même, en état dégradé annoncé. Chaque connexion est tentée indépendamment et journalisée en `ERROR`
698
- par `RedisService.init()` (`redis.ts:123`) : une connexion en échec n'empêche pas les suivantes.
709
+ par `RedisService.init()` (`redis.ts#RedisService.init`) : une connexion en échec n'empêche pas les suivantes.
699
710
 
700
711
  Ce que ce démarrage dégradé implique côté appelants — pourquoi le garde `if (!client)` des stores couvre
701
712
  aussi une ouverture ratée, ce que devient une commande pendant une reconnexion — est
@@ -708,21 +719,21 @@ faire avant une mise en production.
708
719
  | Symptôme | Cause | Correction |
709
720
  | --- | --- | --- |
710
721
  | 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 |
711
- | 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 |
722
+ | L'hôte configuré est ignoré | Une `url` est présente — `buildClientOptions()` (`buildClientOptions.ts#buildClientOptions`) ne pose plus host/port | Retirer `NF_REDIS_URL`/`REDIS_URL`, ou tout mettre dans l'URL |
712
723
  | Le démarrage échoue en nommant `NF_REDIS_PORT` | Valeur non entière ou hors `1..65535` : le schéma la refuse | Corriger la valeur — un port faux n'est plus ignoré, il arrête le démarrage |
713
724
  | 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 |
714
- | Le démarrage pend, sans erreur, sans Redis | Tentatives illimitées : la première ouverture ne rend pas la main | Hors production c'est déjà borné (`applyResilienceDefaults()` (`defineModuleConfig.ts:52`)) ; sinon fixer une valeur finie |
725
+ | Le démarrage pend, sans erreur, sans Redis | Tentatives illimitées : la première ouverture ne rend pas la main | Hors production c'est déjà borné (`applyResilienceDefaults()` (`defineModuleConfig.ts#applyResilienceDefaults`)) ; sinon fixer une valeur finie |
715
726
  | Erreur `NOAUTH` alors que le mot de passe est configuré | L'URL porte des identifiants qui recouvrent `NF_REDIS_PASSWORD` | Ne pas mélanger : l'URL **ou** hôte + mot de passe |
716
- | Les sessions ont changé de magasin sans qu'on touche à la configuration | `NF_REDIS_URL` déclare une infra de cache → `resolveAutoStore()` (`infra.ts:297`) bascule les briques `auto` | Nommer le store explicitement pour un comportement identique partout |
717
- | Une surcharge de connexion ramène le port à `6379` | Un schéma partiel qui réappliquerait ses défauts — d'où `socketOverrideSchema` (`config.ts:133`) sans défaut | Ne poser que les champs voulus ; les autres héritent du socket global |
718
- | 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 |
727
+ | Les sessions ont changé de magasin sans qu'on touche à la configuration | `NF_REDIS_URL` déclare une infra de cache → `resolveAutoStore()` (`infra.ts#resolveAutoStore`) bascule les briques `auto` | Nommer le store explicitement pour un comportement identique partout |
728
+ | Une surcharge de connexion ramène le port à `6379` | Un schéma partiel qui réappliquerait ses défauts — d'où `socketOverrideSchema` (`config.ts#socketOverrideSchema`) sans défaut | Ne poser que les champs voulus ; les autres héritent du socket global |
729
+ | Le module démarre mais n'ouvre rien | `enabled: false` — module chargé, inerte (`RedisService.init()` (`redis.ts#RedisService.init`)) | Le réactiver, ou retirer le module du manifeste |
719
730
  | 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 |
720
- | Une valeur changée à chaud ne prend pas | La configuration est **gelée** après le démarrage (`defineRedisConfig()` (`defineModuleConfig.ts:85`)) | Redémarrer le process |
731
+ | Une valeur changée à chaud ne prend pas | La configuration est **gelée** après le démarrage (`defineRedisConfig()` (`defineModuleConfig.ts#defineRedisConfig`)) | Redémarrer le process |
721
732
 
722
733
  ## 📡 Observabilité — Studio
723
734
 
724
735
  - **Carte du module** (`/nodefony/modules/redis`) : la configuration validée, rendue par un formulaire
725
- **dérivé** du JSON Schema que publie `Redis.configSchema()` (`index.ts:53`). Les champs marqués
736
+ **dérivé** du JSON Schema que publie `Redis.configSchema()` (`index.ts#Redis.configSchema`). Les champs marqués
726
737
  secrets — `url`, `password` — y sont masqués par construction, pas par une liste d'exclusion tenue
727
738
  à la main.
728
739
  - **Écran Stores** (`/nodefony/stores`) : pour chaque brique, le store réellement retenu au démarrage
@@ -742,14 +753,14 @@ cette prose. Ce qui doit être dit ici, c'est **ce que la configuration a de pro
742
753
  <!-- prettier-ignore -->
743
754
  | Ce qui est vérifié | Où |
744
755
  | --- | --- |
745
- | Défauts d'usine et sous-défauts | `config.test.ts:15` (hôte, port, TLS, trois connexions) |
746
- | Refus d'une valeur hors bornes | `config.test.ts:38` (port hors plage) |
747
- | Superposition de l'environnement | `config.test.ts:56` et `config.test.ts:66` |
748
- | Port d'environnement invalide ignoré | `config.test.ts:72` |
749
- | Garde-fou de reconnexion, ses trois branches | `config.test.ts:85`, `config.test.ts:91`, `config.test.ts:99` |
750
- | Gel de la configuration | `config.test.ts:51` |
751
- | Assemblage des options du client | `config.test.ts:107` (fusion) et `config.test.ts:128` (précédence de l'URL) |
752
- | Back-off et abandon | `config.test.ts:139` |
756
+ | Défauts d'usine et sous-défauts | `config.test.ts` (hôte, port, TLS, trois connexions) |
757
+ | Refus d'une valeur hors bornes | `config.test.ts` (port hors plage) |
758
+ | Superposition de l'environnement | `config.test.ts` et `config.test.ts` |
759
+ | Port d'environnement invalide ignoré | `config.test.ts` |
760
+ | Garde-fou de reconnexion, ses trois branches | `config.test.ts` |
761
+ | Gel de la configuration | `config.test.ts` |
762
+ | Assemblage des options du client | `config.test.ts` (fusion) et `config.test.ts` (précédence de l'URL) |
763
+ | Back-off et abandon | `config.test.ts` |
753
764
 
754
765
  Ces bancs sont **unitaires** : ils tournent sans serveur. La configuration est donc la partie du
755
766
  module dont la vérification ne dépend d'aucune infrastructure — c'est aussi pour ça que le schéma doit
@@ -759,7 +770,7 @@ rester pur.
759
770
  > **Une suite verte ne prouve rien du reste sans serveur Redis.** Les bancs d'intégration se
760
771
  > **skippent** quand l'infra manque, et un skip compte comme un succès : on peut lire « tout est
761
772
  > vert » sur une suite qui n'a rien exercé. La gate du module est déclarée une seule fois —
762
- > `REDIS_GATE` (`scripts/test/vitest/gates.ts:351`) — et la fin de run nomme la cible non exercée avec la commande
773
+ > `REDIS_GATE` (`scripts/test/vitest/gates.ts#REDIS_GATE`) — et la fin de run nomme la cible non exercée avec la commande
763
774
  > exacte pour la satisfaire. **Les variables et la commande docker se lisent là, pas ici** : les
764
775
  > recopier dans cette page les condamnerait à diverger.
765
776
 
package/docs/index.md CHANGED
@@ -99,8 +99,8 @@ pour quoi il est bon. Redis se déclare de nature `cache` et annonce quatre briq
99
99
  `package.json` (clé `nodefony.stores`) — ni plus, ni moins.
100
100
 
101
101
  La nuance décisive n'est pas « couvert / pas couvert », c'est **qui choisit**. Chaque brique déclare
102
- la nature de sa donnée (`StoreKind`, `infra.ts:176`), et la résolution automatique ne propose Redis
103
- que pour les natures non durables (`resolveAutoStore()`, `infra.ts:289`).
102
+ la nature de sa donnée (`StoreKind`, `infra.ts#StoreKind`), et la résolution automatique ne propose Redis
103
+ que pour les natures non durables (`resolveAutoStore()`, `infra.ts#resolveAutoStore`).
104
104
 
105
105
  <!-- prettier-ignore -->
106
106
  | Brique | Nature | Implémentation | Choisi par `auto` ? | Où on l'allume explicitement |
@@ -218,7 +218,7 @@ flowchart TD
218
218
  ```
219
219
 
220
220
  Le module ne connaît aucun de ses consommateurs : il expose un service, ils s'y branchent. C'est aussi
221
- pour ça qu'il se déclare **non critique** (`Redis.critical` vaut `false`, `index.ts:36`) — un Redis
221
+ pour ça qu'il se déclare **non critique** (`Redis.critical` vaut `false`, `index.ts#nodefony`) — un Redis
222
222
  injoignable au démarrage n'empêche pas l'application de monter.
223
223
 
224
224
  ## 🧰 Surface publique
@@ -227,9 +227,9 @@ injoignable au démarrage n'empêche pas l'application de monter.
227
227
  `RedisTokenStore`, `RedisWebAuthnCredentialStore` —, le builder `defineRedisConfig` avec son schéma,
228
228
  et un ré-export de la bibliothèque `redis` elle-même pour qui a besoin de ses types.
229
229
 
230
- Charger le module suffit : `registerRedisFrameworkStores()` (`registerStores.ts:72`) inscrit les
230
+ Charger le module suffit : `registerRedisFrameworkStores()` (`registerStores.ts#registerRedisFrameworkStores`) inscrit les
231
231
  fabriques `redis` dans les registres de `@nodefony/security`, et le store de session s'auto-déclare
232
- (`SessionStorage.ts:323`). Aucun câblage applicatif — il ne reste qu'à nommer le store, ou à laisser
232
+ (`SessionStorage.ts#RedisSessionStorage.listAll`). Aucun câblage applicatif — il ne reste qu'à nommer le store, ou à laisser
233
233
  `auto` faire.
234
234
 
235
235
  Les signatures exactes vivent dans le graphe généré (`jq '.symbols.RedisService' .ai/symbols.json`),
@@ -273,7 +273,7 @@ chose**.
273
273
  > [!IMPORTANT]
274
274
  > **Une suite verte ne prouve rien sans serveur Redis.** Les bancs d'intégration se **skippent** quand
275
275
  > l'infra manque, et un skip compte comme un succès : on peut lire « tout est vert » sur une suite qui
276
- > n'a rien exercé. Le module déclare donc sa gate — `REDIS_GATE` dans `scripts/test/vitest/gates.ts:351` — et la
276
+ > n'a rien exercé. Le module déclare donc sa gate — `REDIS_GATE` dans `scripts/test/vitest/gates.ts#REDIS_GATE` — et la
277
277
  > fin de run nomme la cible non testée avec la commande exacte pour la satisfaire. **Lis ce bloc avant
278
278
  > de conclure.** Les variables et la commande docker viennent de là, pas de cette page : les recopier
279
279
  > ici les condamnerait à diverger.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nodefony/redis",
3
- "version": "10.0.0-beta.3",
3
+ "version": "10.0.0-beta.5",
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",
@@ -35,7 +35,7 @@
35
35
  },
36
36
  "private": false,
37
37
  "engines": {
38
- "node": ">=24.0.0"
38
+ "node": ">=24.14.0"
39
39
  },
40
40
  "keywords": [
41
41
  "nodefony",
@@ -52,19 +52,19 @@
52
52
  "tslib": "2.8.1"
53
53
  },
54
54
  "devDependencies": {
55
- "@nodefony/framework": "^10.0.0-beta.3",
56
- "@nodefony/http": "^10.0.0-beta.3",
57
- "@nodefony/security": "^10.0.0-beta.3",
55
+ "@nodefony/framework": "^10.0.0-beta.5",
56
+ "@nodefony/http": "^10.0.0-beta.5",
57
+ "@nodefony/security": "^10.0.0-beta.5",
58
58
  "@types/node": "26.6.5",
59
- "@vitest/coverage-v8": "5.0.4",
60
- "nodefony": "^10.0.0-beta.3",
61
- "vitest": "5.0.4"
59
+ "@vitest/coverage-v8": "5.0.5",
60
+ "nodefony": "^10.0.0-beta.5",
61
+ "vitest": "5.0.5"
62
62
  },
63
63
  "peerDependencies": {
64
- "@nodefony/framework": "^10.0.0-beta.3",
65
- "@nodefony/http": "^10.0.0-beta.3",
66
- "@nodefony/security": "^10.0.0-beta.3",
67
- "nodefony": "^10.0.0-beta.3",
64
+ "@nodefony/framework": "^10.0.0-beta.5",
65
+ "@nodefony/http": "^10.0.0-beta.5",
66
+ "@nodefony/security": "^10.0.0-beta.5",
67
+ "nodefony": "^10.0.0-beta.5",
68
68
  "zod": "^4.6.7"
69
69
  },
70
70
  "repository": {
@@ -1,6 +0,0 @@
1
- //#region \0@oxc-project+runtime@0.153.0/helpers/esm/decorateMetadata.js
2
- function __decorateMetadata(k, v) {
3
- if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
4
- }
5
- //#endregion
6
- export { __decorateMetadata as default };