@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.
- package/dist/_virtual/{_@oxc-project_runtime@0.153.0 → _@oxc-project_runtime@0.155.0}/helpers/esm/decorate.js +1 -2
- package/dist/index.js +4 -6
- package/dist/nodefony/config/config.js +1 -2
- package/dist/nodefony/config/configSchema.js +1 -2
- package/dist/nodefony/config/defineModuleConfig.js +1 -2
- package/dist/nodefony/registerStores.js +1 -2
- package/dist/nodefony/service/redis.js +1 -2
- package/dist/nodefony/src/Connection.js +1 -2
- package/dist/nodefony/src/RedisTokenStore.js +1 -2
- package/dist/nodefony/src/RedisWebAuthnCredentialStore.js +1 -2
- package/dist/nodefony/src/SessionStorage.js +1 -2
- package/dist/nodefony/src/buildClientOptions.js +1 -2
- package/dist/nodefony/src/keyNamespace.js +1 -2
- package/dist/nodefony/src/scanCursor.js +1 -2
- package/dist/nodefony/src/sessionIndex.js +1 -2
- package/docs/architecture.md +67 -67
- package/docs/configuration.md +87 -76
- package/docs/index.md +6 -6
- package/package.json +12 -12
- package/dist/_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorateMetadata.js +0 -6
|
@@ -1,9 +1,8 @@
|
|
|
1
|
-
|
|
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
|
|
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 {
|
|
9
|
+
import { Module, services } from "nodefony";
|
|
11
10
|
import * as redis from "redis";
|
|
12
|
-
|
|
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])
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 };
|
package/docs/architecture.md
CHANGED
|
@@ -57,7 +57,7 @@ flowchart TD
|
|
|
57
57
|
CSUB["Connection subscribe"]
|
|
58
58
|
LIB["clients lib redis v6"]
|
|
59
59
|
|
|
60
|
-
MOD
|
|
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
|
|
131
|
-
appelle `registerRedisFrameworkStores()` (`registerStores.ts
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
283
|
-
**avant** d'attendre son ouverture (`redis.ts
|
|
284
|
-
3. `Connection.create()` (`Connection.ts
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
350
|
-
de purge périodique — et `touch()` (`SessionStorage.ts
|
|
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
|
|
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
|
|
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
|
|
373
|
-
`RedisTokenStore.findByHash()` (`RedisTokenStore.ts
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
459
|
-
le temps** : `Kernel.guardInitialize()` (`Kernel.ts
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
505
|
-
échecs individuels, puis libère la carte. `Connection.close()` (`Connection.ts
|
|
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
|
|
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
|
|
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
|
|
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
|
|
536
|
-
(`RedisWebAuthnCredentialStore.ts
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
639
|
-
cache) ». Le choix automatique lui-même vient de `resolveAutoStore()` (`infra.ts
|
|
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
|
|
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)
|
|
655
|
-
| -------------------------------------------------------- |
|
|
656
|
-
| Le démarrage pend sans Redis | Tentatives illimitées : `connect()` ne rend pas la main
|
|
657
|
-
| Deux applications se renvoient leurs messages temps réel | Le pub/sub ignore le numéro de base — cloisonnement inexistant
|
|
658
|
-
| Les mêmes messages sont diffusés deux fois localement | Anti-echo court-circuité (identifiant d'origine partagé)
|
|
659
|
-
| Un jeton expiré « revient » et n'expire plus | `HSET` recrée une clé absente, sans TTL
|
|
660
|
-
| L'écran d'administration n'affiche aucun total | `countSessions` / `countTokens` rendent `-1` (comptage O(N) refusé)
|
|
661
|
-
| Un `offset` envoyé n'a aucun effet | Le mode curseur ne lit que `cursor` (`SessionStorage.ts
|
|
662
|
-
| Des passkeys disparaissent | Politique d'éviction Redis (`allkeys-lru`) sur des clés **sans** TTL
|
|
663
|
-
| Une session survit à son âge maximal côté Redis | Le TTL glissant n'exprime pas l'absolu (`SessionStorage.ts
|
|
664
|
-
| Une surcharge de connexion écrase l'hôte global | Un schéma partiel qui réapplique ses défauts clobberait la valeur globale
|
|
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
|
|
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
|
|
package/docs/configuration.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
|
125
|
-
pendant d'entrée `IRedisConfigInput` (`IRedisConfig.ts
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
400
|
-
(`defineModuleConfig.ts
|
|
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
|
|
403
|
-
(`envShortcuts.ts
|
|
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
|
|
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
|
|
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
|
|
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
|
|
446
|
-
et prouvée par `config.test.ts
|
|
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
|
|
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
|
|
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
|
|
509
|
-
à `DEV_DEFAULT_MAX_RETRIES` (`defineModuleConfig.ts
|
|
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
|
|
532
|
+
branches sont couvertes par les tests (`config.test.ts`).
|
|
522
533
|
|
|
523
|
-
**Le calcul du délai.** `buildReconnectStrategy()` (`buildClientOptions.ts
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
718
|
-
| Le module démarre mais n'ouvre rien | `enabled: false` — module chargé, inerte (`RedisService.init()` (`redis.ts
|
|
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
|
|
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
|
|
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
|
|
746
|
-
| Refus d'une valeur hors bornes | `config.test.ts
|
|
747
|
-
| Superposition de l'environnement | `config.test.ts
|
|
748
|
-
| Port d'environnement invalide ignoré | `config.test.ts
|
|
749
|
-
| Garde-fou de reconnexion, ses trois branches | `config.test.ts
|
|
750
|
-
| Gel de la configuration | `config.test.ts
|
|
751
|
-
| Assemblage des options du client | `config.test.ts
|
|
752
|
-
| Back-off et abandon | `config.test.ts
|
|
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
|
|
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
|
|
103
|
-
que pour les natures non durables (`resolveAutoStore()`, `infra.ts
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
+
"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.
|
|
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.
|
|
56
|
-
"@nodefony/http": "^10.0.0-beta.
|
|
57
|
-
"@nodefony/security": "^10.0.0-beta.
|
|
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.
|
|
60
|
-
"nodefony": "^10.0.0-beta.
|
|
61
|
-
"vitest": "5.0.
|
|
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.
|
|
65
|
-
"@nodefony/http": "^10.0.0-beta.
|
|
66
|
-
"@nodefony/security": "^10.0.0-beta.
|
|
67
|
-
"nodefony": "^10.0.0-beta.
|
|
64
|
+
"@nodefony/framework": "^10.0.0-beta.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 };
|