@nodefony/framework 10.0.0-alpha.1

package/dist/nodefony/src/PlaygroundAdminApi.js

@@ -0,0 +1,97 @@
+import { extractActionScopes, resolveActionMeta } from "../decorators/routerDecorators.js";
+import router_default from "../service/router.js";
+import AdminApiController from "../controller/AdminApiController.js";
+//#region nodefony/src/PlaygroundAdminApi.ts
+/** Normalise `requirements.methods` (string | string[]) → tableau majuscule. */
+function methodsOf(route) {
+	const m = route.requirements?.methods ?? route.method;
+	if (Array.isArray(m)) return m.map((x) => String(x).toUpperCase());
+	if (typeof m === "string") return m.split(",").map((s) => s.trim().toUpperCase()).filter(Boolean);
+	return ["ANY"];
+}
+/** Défauts de la route sans la clé interne `controller` (jamais un input user). */
+function publicDefaults(route) {
+	const out = {};
+	for (const [k, v] of Object.entries(route.defaults)) if (k !== "controller") out[k] = v;
+	return out;
+}
+/** Sérialise une route en action playground (métadonnées figées, JSON-safe). */
+function serializeAction(route) {
+	const meta = resolveActionMeta(route);
+	const methods = methodsOf(route);
+	const scopes = route.controller && route.classMethod ? extractActionScopes(route.controller, route.classMethod) : [];
+	return {
+		route: route.name,
+		path: route.path ?? null,
+		methods,
+		duplex: methods.includes("WEBSOCKET"),
+		action: route.classMethod ?? null,
+		variables: [...route.variables],
+		defaults: publicDefaults(route),
+		params: meta.paramsMeta?.map((p) => ({
+			source: p.source,
+			key: p.key ?? null,
+			index: p.index,
+			stream: p.stream === true
+		})).sort((a, b) => a.index - b.index) ?? [],
+		guards: {
+			security: meta.security ? { clauses: meta.security.clauses.map((c) => ({
+				anyOf: [...c.anyOf],
+				subjectParam: c.subjectParam ?? null
+			})) } : null,
+			scopes,
+			idempotent: meta.idempotent ? { required: meta.idempotent.required } : null,
+			csrfProtect: meta.csrfProtect,
+			csrfExempt: meta.csrfExempt,
+			session: meta.sessionIntent,
+			bypassFirewall: route.bypassFirewall === true
+		}
+	};
+}
+/**
+* Construit le snapshot playground : toutes les routes à controller, groupées
+* par classe de controller, triées (module puis nom, actions par path).
+*
+* Exclut les routes du **pont admin** (`AdminApiController.dispatch`) : le data
+* plane a déjà son catalogue (`GET /nodefony/framework/api/admin`) et ses ~50
+* routes techniques noieraient les controllers applicatifs.
+*
+* @returns la liste des controllers jouables, prête pour la page Studio.
+*/
+function buildPlaygroundSnapshot() {
+	const byController = /* @__PURE__ */ new Map();
+	for (const route of router_default.routes) {
+		const ctor = route.controller;
+		if (!ctor || !route.classMethod) continue;
+		if (ctor === AdminApiController) continue;
+		let group = byController.get(ctor);
+		if (!group) {
+			group = {
+				name: ctor.name ?? "Controller",
+				module: route.module?.name ?? null,
+				actions: []
+			};
+			byController.set(ctor, group);
+		}
+		group.actions.push(serializeAction(route));
+	}
+	const controllers = [...byController.values()];
+	for (const c of controllers) c.actions.sort((a, b) => (a.path ?? "").localeCompare(b.path ?? ""));
+	controllers.sort((a, b) => (a.module ?? "~").localeCompare(b.module ?? "~") || a.name.localeCompare(b.name));
+	return { controllers };
+}
+/**
+* Endpoints playground à greffer au producteur `framework` (dev uniquement —
+* cf gating dans `createFrameworkAdminApi`).
+*
+* @returns `GET /nodefony/framework/api/playground/routes`.
+*/
+function createPlaygroundEndpoints() {
+	return [{
+		path: "playground/routes",
+		summary: "Playground (dev) — controllers + actions + transports + params + guards, form-ready",
+		handler: () => buildPlaygroundSnapshot()
+	}];
+}
+//#endregion
+export { buildPlaygroundSnapshot, createPlaygroundEndpoints };

package/dist/nodefony/src/RedisIdempotencyStore.js

@@ -0,0 +1,254 @@
+import { assertPageQuery } from "nodefony";
+//#region nodefony/src/RedisIdempotencyStore.ts
+/** Préfixe namespacé des clés d'idempotence dans Redis. */
+/**
+* Préfixe HISTORIQUE des clés d'idempotence. Utilisé tel quel par une application
+* sans cloison ; sinon le service Redis y insère le nom de l'application (cf
+* `RedisService.keyPrefix`).
+*/
+const KEY_BASE = "nf:idem";
+/**
+* Bail par défaut d'une entrée *in-flight* : 60 s (au-delà = exécution réputée
+* abandonnée → la clé redevient réservable). Porté par le TTL natif (`PX`).
+*/
+const DEFAULT_LEASE_MS = 6e4;
+/**
+* Rétention par défaut d'une réponse mémorisée : 10 min (un rejeu plausible
+* reste dans cette fenêtre). Porté par le TTL natif (`PX`).
+*/
+const DEFAULT_TTL_MS = 6e5;
+/**
+* Encode le curseur composite `"<consommé>:<curseurRedis>"` — cf
+* {@link RedisIdempotencyStore.listPage} pour le pourquoi.
+*/
+function encodeCursor(scanCursor, skip) {
+	return `${skip}:${scanCursor}`;
+}
+/** Inverse d'{@link encodeCursor} — tolère un curseur absent, vide ou malformé. */
+function decodeCursor(cursor) {
+	if (!cursor) return {
+		scanCursor: "0",
+		skip: 0
+	};
+	const sep = cursor.indexOf(":");
+	if (sep === -1) return {
+		scanCursor: cursor,
+		skip: 0
+	};
+	const skip = Number.parseInt(cursor.slice(0, sep), 10);
+	return {
+		scanCursor: cursor.slice(sep + 1) || "0",
+		skip: Number.isFinite(skip) && skip > 0 ? skip : 0
+	};
+}
+/**
+* Store d'idempotence **Redis** (node-redis v6) — implémentation distribuée
+* d'{@link IIdempotencyStore} pour le cluster (dédup des mutations rejouées
+* PARTAGÉE cross-pod, là où l'impl mémoire par défaut reste affine à un pod).
+*
+* **Pourquoi Redis est le bon backing** (modèle Stripe `Idempotency-Key`) :
+*  - `SET key … NX PX` = **réservation atomique côté serveur** → le `409`
+*    in-flight marche VRAIMENT entre pods (deux requêtes concurrentes sur deux
+*    pods : un seul `SET NX` gagne, l'autre voit l'entrée → conflit) ;
+*  - **TTL natif** (`PX`) sur le bail in-flight ET la réponse mémorisée → `gc()`
+*    superflu (zéro balayage applicatif, ≠ Drizzle).
+*
+* **Placement** : vit dans `@nodefony/framework` (le consommateur du contrat),
+* PAS dans `@nodefony/redis` — calqué sur `RedisBackplane` (`@nodefony/realtime`)
+* qui possède son adaptateur Redis et résout le service `redis` par nom (couplage
+* structurel, 0 dépendance directe → 0 cycle). Le contrat `IIdempotencyStore`
+* vit au CORE (`nodefony`), consommé en `import type`.
+*
+* **Modèle de clés** (préfixe `nf:idem`, cloisonné par application) : `<prefix>:<key>` = string JSON de
+* l'{@link Entry}. La `<key>` est DÉJÀ scopée à l'identité par l'appelant
+* (`evaluateIdempotency` compose `[identity, clientKey]`) → anti-IDOR garanti en
+* amont ; le store reste agnostique au scope.
+*
+* **Empreinte préservée à la complétion** : `complete()` ne reçoit pas le
+* fingerprint → il **relit** l'entrée *in-flight* pour reporter son `f` dans
+* l'entrée *done*. Sans ça, un rejeu de la clé avec un AUTRE payload après
+* complétion ne serait pas détecté (`mismatch` 422 perdu, draft §2.7).
+*
+* **Dégradation gracieuse** : si la connexion `main` n'est pas (ou plus) ouverte
+* (boot/shutdown), `begin` renvoie `fresh` (la mutation s'exécute, **sans**
+* dédup) et `complete`/`abort` sont des no-op — l'idempotence est temporairement
+* inactive plutôt que de bloquer la mutation (fail-soft sur la dispo, comme le
+* session/token store Redis). Trade-off assumé : un rejeu pendant une coupure
+* Redis peut ré-exécuter (le client rejoue alors sa clé au rétablissement).
+*/
+var RedisIdempotencyStore = class {
+	#resolveClient;
+	/** Fournit le préfixe cloisonné par application (lazy : le service arrive au boot). */
+	#resolvePrefix;
+	/** Préfixe mémoïsé — il est lu à chaque clé. */
+	#prefixCache = null;
+	#leaseMs;
+	#ttlMs;
+	/** Compteur LOCAL best-effort d'entrées réservées par CE pod (cf {@link size}). */
+	#pending = 0;
+	/**
+	* @param resolveClient - résolveur **lazy** du client Redis (l'ordre de boot
+	*   n'est pas garanti à la construction ; `null` = connexion indisponible).
+	* @param leaseMs - bail d'une entrée *in-flight* (ms).
+	* @param ttlMs - rétention d'une réponse mémorisée (ms).
+	*/
+	constructor(resolveClient, leaseMs = DEFAULT_LEASE_MS, ttlMs = DEFAULT_TTL_MS, resolvePrefix = () => KEY_BASE) {
+		this.#resolveClient = resolveClient;
+		this.#resolvePrefix = resolvePrefix;
+		this.#leaseMs = leaseMs;
+		this.#ttlMs = ttlMs;
+	}
+	/**
+	* Approximation **per-pod, best-effort** : compteur local des réservations
+	* faites par CE pod, non décrémenté si le bail expire sans `complete`/`abort`,
+	* et désaligné cross-pod (un `begin` sur un pod, un `complete` sur un autre).
+	* La vérité cluster passe par `redis-cli` (`SCAN nf:idem:*`/`DBSIZE`), jamais
+	* ce getter (un `SCAN` à chaque lecture serait cher). Borné à ≥ 0.
+	*/
+	get size() {
+		return this.#pending < 0 ? 0 : this.#pending;
+	}
+	/**
+	* {@inheritDoc IIdempotencyStore.listPage}
+	*
+	* **Curseur SCAN** : au plus UN passage par appel (cold-path admin). Capacité
+	* réduite ASSUMÉE — pas de `total` (compter exigerait un SCAN complet du
+	* keyspace, précisément ce qu'on refuse), pas d'ordre global, et la page peut
+	* compter moins que `limit` (le filtre s'applique au batch scanné). Le client
+	* boucle tant que `hasNext` en repassant `nextCursor`.
+	*
+	* ⚠️ **`COUNT` n'est PAS un plafond** mais un indice d'effort : Redis peut
+	* rendre plus de clés que demandé (petit keyspace en listpack → tout arrive
+	* d'un coup). Sans précaution la page dépasserait `limit` et violerait
+	* `IPage`. D'où le **curseur composite** `"<consommé>:<curseurRedis>"` : on ne
+	* rend que `limit` éléments et on mémorise combien de clés du batch ont été
+	* consommées ; la page suivante rejoue le MÊME `SCAN` et reprend là. Bug
+	* réel, invisible contre un double — trouvé sur serveur Redis réel.
+	*/
+	async listPage(query) {
+		assertPageQuery(query, "cursor");
+		const limit = Math.max(1, Math.floor(query.limit));
+		const client = this.#client();
+		if (!client) return {
+			items: [],
+			limit,
+			hasNext: false,
+			nextCursor: null
+		};
+		const { scanCursor, skip } = decodeCursor(query.cursor);
+		const match = query.q !== void 0 && query.q.length > 0 ? `${this.#prefix()}:${query.q}*` : `${this.#prefix()}:*`;
+		const res = await client.scan(scanCursor, {
+			MATCH: match,
+			COUNT: limit
+		});
+		const next = String(res.cursor);
+		const prefixLen = this.#prefix().length + 1;
+		const items = [];
+		let consumed = 0;
+		for (const key of res.keys.slice(skip)) {
+			if (items.length >= limit) break;
+			consumed += 1;
+			const entry = this.#parse(await client.get(key));
+			if (entry === null) continue;
+			const state = entry.s === "if" ? "in-flight" : "done";
+			if (query.state !== void 0 && state !== query.state) continue;
+			const ttl = await client.pTTL(key);
+			items.push({
+				key: key.slice(prefixLen),
+				state,
+				expiresAtMs: ttl > 0 ? Date.now() + ttl : 0,
+				hasResponse: entry.s === "d"
+			});
+		}
+		const nextCursor = skip + consumed < res.keys.length ? encodeCursor(scanCursor, skip + consumed) : next === "0" ? null : encodeCursor(next, 0);
+		return {
+			items,
+			limit,
+			hasNext: nextCursor !== null,
+			nextCursor
+		};
+	}
+	#client() {
+		return this.#resolveClient();
+	}
+	/** Préfixe effectif des clés, cloisonné par application (mémoïsé). */
+	#prefix() {
+		if (this.#prefixCache === null) this.#prefixCache = this.#resolvePrefix();
+		return this.#prefixCache;
+	}
+	#key(key) {
+		return `${this.#prefix()}:${key}`;
+	}
+	/** Parse défensif d'une valeur de clé ; `null` si absente/corrompue. */
+	#parse(raw) {
+		if (raw === null) return null;
+		try {
+			const v = JSON.parse(raw);
+			return v && (v.s === "if" || v.s === "d") ? v : null;
+		} catch {
+			return null;
+		}
+	}
+	async begin(key, fingerprint) {
+		const client = this.#client();
+		if (!client) return { state: "fresh" };
+		const k = this.#key(key);
+		const reservation = JSON.stringify({
+			s: "if",
+			f: fingerprint
+		});
+		if (await client.set(k, reservation, {
+			NX: true,
+			PX: this.#leaseMs
+		}) !== null) {
+			this.#pending++;
+			return { state: "fresh" };
+		}
+		const existing = this.#parse(await client.get(k));
+		if (existing === null) {
+			if (await client.set(k, reservation, {
+				NX: true,
+				PX: this.#leaseMs
+			}) !== null) {
+				this.#pending++;
+				return { state: "fresh" };
+			}
+			return { state: "in-flight" };
+		}
+		if (existing.f !== fingerprint) return { state: "mismatch" };
+		if (existing.s === "d") return {
+			state: "replayed",
+			response: existing.r
+		};
+		return { state: "in-flight" };
+	}
+	async complete(key, response) {
+		const client = this.#client();
+		if (!client) return;
+		const k = this.#key(key);
+		const existing = this.#parse(await client.get(k));
+		if (existing === null || existing.s !== "if") {
+			this.#dec();
+			return;
+		}
+		const done = JSON.stringify({
+			s: "d",
+			f: existing.f,
+			r: response
+		});
+		await client.set(k, done, { PX: this.#ttlMs });
+		this.#dec();
+	}
+	async abort(key) {
+		const client = this.#client();
+		if (!client) return;
+		await client.del(this.#key(key));
+		this.#dec();
+	}
+	/** Décrémente le compteur local borné à 0. */
+	#dec() {
+		if (this.#pending > 0) this.#pending--;
+	}
+};
+//#endregion
+export { RedisIdempotencyStore };