@nodefony/drizzle 10.0.0-alpha.1

package/dist/nodefony/src/DrizzleAuditStore.js

@@ -0,0 +1,203 @@
+import { execTable } from "./orm-core/DrizzleRepository.js";
+import { auditEventTable, createAuditEventTable } from "../entity/auditEventEntity.js";
+import { assertPageQuery } from "nodefony";
+import { and, count, desc, eq, gte, lt, lte, or } from "drizzle-orm";
+//#region nodefony/src/DrizzleAuditStore.ts
+/** Rétention par défaut d'un événement : 365 jours (aligné `MemoryAuditStore`). */
+const DEFAULT_RETENTION_MS = 31536e6;
+/** Taille de page par défaut / plafond (alignés `MemoryAuditStore`). */
+const DEFAULT_LIMIT = 100;
+const MAX_LIMIT = 500;
+/** Séparateur du curseur composite `<ts>:<id>` (cf `#parseCursor`). */
+const CURSOR_SEPARATOR = ":";
+/**
+* Journal d'audit **Drizzle** (driver `better-sqlite3` en test, Postgres/MySQL en
+* prod) — implémentation SQL d'{@link IAuditStore} (append-only, tamper-evident)
+* pour la **rétention longue** et le **partage cross-pod**, là où le store mémoire
+* par défaut reste affine à un pod et volatile.
+*
+* **Append-only** : `append` est la seule écriture (INSERT) ; aucune mutation ni
+* suppression ciblée d'un événement — seul {@link DrizzleAuditStore.gc} (rétention)
+* retire des lignes. L'immuabilité EST la garantie d'audit.
+*
+* **Pagination curseur EXACTE (`listPage`)** — via le query builder Drizzle
+* (dialect-agnostique), l'ordre total est `(ts DESC, id DESC)` : `ts` porte l'ordre
+* chronologique, `id` casse les collisions à la milliseconde (rafales de login). Le
+* curseur transporte **les deux** (`<ts>:<id>`) et se compare en **composite**
+* `(ts, id) < (cursorTs, cursorId)` — non exprimable en critère `IRepository`
+* AND-only, d'où la trappe native (ADR-0003, comme `DrizzleIdempotencyStore`). Une
+* ligne de garde (`limit + 1`) détermine `hasNext` sans page vide parasite.
+*
+* **Résolution LAZY + dégradation gracieuse** (calqué sur les stores frères) : le
+* handle Drizzle est résolu à CHAQUE appel, pas capturé à la construction — l'ordre
+* de boot n'est pas garanti (l'app câble à `onKernelBoot`, l'ORM peut n'être pas
+* encore connecté) et l'ORM se déconnecte au shutdown avant le drain des serveurs.
+* Si le handle est `null` : `append` est un no-op **best-effort** (l'audit ne
+* bloque ni ne fait échouer le flux métier — un événement au boot/shutdown est
+* perdu plutôt que de crasher un login), `listPage` rend une page vide et `gc` rend 0.
+*
+* Horloge injectable (`now`) pour des tests déterministes.
+*/
+var DrizzleAuditStore = class DrizzleAuditStore {
+	#resolveDb;
+	#table;
+	/** Colonnes par nom logique, vue canonique (les specs colKit partagent les
+	*  NOMS entre dialectes → le query builder reste dialecte-agnostique). */
+	#c;
+	#now;
+	#retentionMs;
+	#location;
+	/**
+	* @param resolveDb - résolveur **lazy** du handle Drizzle (`null` = ORM non
+	*   connecté → dégradation gracieuse).
+	* @param now - horloge (epoch ms) injectable pour des tests déterministes.
+	* @param retentionMs - fenêtre de rétention (ms) avant purge par `gc`.
+	* @param table - variante de table à utiliser (dialecte). Défaut = SQLite.
+	* @param location - emplacement physique de la base (fichier SQLite) pour Studio
+	*   ({@link DrizzleOrm.location}) ; `undefined` pour un backend réseau/`:memory:`.
+	*/
+	constructor(resolveDb, now = Date.now, retentionMs = DEFAULT_RETENTION_MS, table = auditEventTable, location) {
+		this.#resolveDb = resolveDb;
+		this.#table = table;
+		this.#c = execTable(table);
+		this.#now = now;
+		this.#retentionMs = retentionMs;
+		this.#location = location;
+	}
+	/**
+	* Emplacement physique de la base (fichier SQLite) pour l'écran Studio « Stores »
+	* — lu par `readStoreLocation`. `undefined` = backend réseau ou `:memory:`.
+	*/
+	get location() {
+		return this.#location;
+	}
+	/**
+	* Construit le store depuis un {@link DrizzleOrm}. Le handle est résolu **lazy**
+	* (gardé par `isConnected()` → `null` tant que l'ORM n'est pas/plus connecté).
+	* L'entité (`registerAuditEntities`) doit avoir été enregistrée **avant**
+	* `orm.connect()` (la table est créée au connect) — sur la **variante de table
+	* du dialecte de l'ORM** (S3 multi-dialecte).
+	*
+	* @param orm - ORM Drizzle hébergeant la table `audit_event`.
+	* @param now - horloge injectable (tests).
+	* @param retentionMs - fenêtre de rétention (ms).
+	*/
+	static from(orm, now, retentionMs) {
+		return new DrizzleAuditStore(() => orm.isConnected() ? orm.getNativeConnection() : null, now, retentionMs, createAuditEventTable(orm.dialect), orm.location);
+	}
+	async append(event) {
+		const db = this.#resolveDb();
+		if (!db) return;
+		await db.insert(execTable(this.#table)).values({
+			id: event.id,
+			ts: event.ts,
+			category: event.category,
+			action: event.action,
+			outcome: event.outcome,
+			actor: event.actor ?? null,
+			resource: event.resource ?? null,
+			reason: event.reason ?? null,
+			ip: event.ip ?? null,
+			userAgent: event.userAgent ?? null,
+			requestId: event.requestId ?? null,
+			flags: event.flags ?? null,
+			metadata: event.metadata ?? null
+		});
+	}
+	async listPage(query) {
+		assertPageQuery(query, "cursor");
+		const limit = Math.min(Math.max(1, query.limit ?? DEFAULT_LIMIT), MAX_LIMIT);
+		const db = this.#resolveDb();
+		if (!db) return {
+			items: [],
+			limit,
+			hasNext: false,
+			nextCursor: null,
+			total: 0
+		};
+		const table = execTable(this.#table);
+		const c = this.#c;
+		const filterWhere = this.#buildFilter(query);
+		let total;
+		if (query.withTotal !== false) {
+			const totalRows = await db.select({ n: count() }).from(table).where(filterWhere);
+			total = Number(totalRows[0]?.n ?? 0);
+		}
+		let where = filterWhere;
+		const cursor = this.#parseCursor(query.cursor);
+		if (cursor) {
+			const cursorCond = or(lt(c.ts, cursor.ts), and(eq(c.ts, cursor.ts), lt(c.id, cursor.id)));
+			where = filterWhere ? and(filterWhere, cursorCond) : cursorCond;
+		}
+		const rows = await db.select().from(table).where(where).orderBy(desc(c.ts), desc(c.id)).limit(limit + 1);
+		const hasNext = rows.length > limit;
+		const pageRows = hasNext ? rows.slice(0, limit) : rows;
+		const items = pageRows.map((row) => this.#toEvent(row));
+		const last = pageRows[pageRows.length - 1];
+		return {
+			items,
+			limit,
+			hasNext,
+			nextCursor: hasNext && last ? `${last.ts}${CURSOR_SEPARATOR}${last.id}` : null,
+			...total !== void 0 ? { total } : {}
+		};
+	}
+	/**
+	* Décode le curseur composite `<ts>:<id>` (format privé au store, comme son
+	* pendant mémoire). Jeton absent ou malformé → `null` : la lecture repart de
+	* la page la plus récente plutôt que d'échouer sur une consultation.
+	*/
+	#parseCursor(cursor) {
+		if (cursor === void 0) return null;
+		const sep = cursor.indexOf(CURSOR_SEPARATOR);
+		if (sep <= 0) return null;
+		const ts = Number(cursor.slice(0, sep));
+		return Number.isFinite(ts) ? {
+			ts,
+			id: cursor.slice(sep + 1)
+		} : null;
+	}
+	async gc(now = this.#now()) {
+		const db = this.#resolveDb();
+		if (!db) return 0;
+		const threshold = now - this.#retentionMs;
+		const result = await db.delete(execTable(this.#table)).where(lt(this.#c.ts, threshold));
+		if (Array.isArray(result)) return result[0]?.affectedRows ?? 0;
+		const r = result;
+		return r.changes ?? r.rowCount ?? 0;
+	}
+	/** Compose la clause `WHERE` des filtres AND ; `undefined` si aucun (= tout). */
+	#buildFilter(filter) {
+		const c = this.#c;
+		const clauses = [];
+		if (filter.category !== void 0) clauses.push(eq(c.category, filter.category));
+		if (filter.outcome !== void 0) clauses.push(eq(c.outcome, filter.outcome));
+		if (filter.actor !== void 0) clauses.push(eq(c.actor, filter.actor));
+		if (filter.action !== void 0) clauses.push(eq(c.action, filter.action));
+		if (filter.requestId !== void 0) clauses.push(eq(c.requestId, filter.requestId));
+		if (filter.since !== void 0) clauses.push(gte(c.ts, filter.since));
+		if (filter.until !== void 0) clauses.push(lte(c.ts, filter.until));
+		return clauses.length > 0 ? and(...clauses) : void 0;
+	}
+	/** Mappe une ligne SQL vers un événement (NULL → optionnel absent). */
+	#toEvent(row) {
+		const event = {
+			id: row.id,
+			ts: row.ts,
+			category: row.category,
+			action: row.action,
+			outcome: row.outcome,
+			actor: row.actor,
+			resource: row.resource,
+			reason: row.reason,
+			ip: row.ip,
+			userAgent: row.userAgent,
+			requestId: row.requestId
+		};
+		if (row.flags) event.flags = row.flags;
+		if (row.metadata) event.metadata = row.metadata;
+		return event;
+	}
+};
+//#endregion
+export { DrizzleAuditStore };

package/dist/nodefony/src/DrizzleIdempotencyStore.js

@@ -0,0 +1,278 @@
+import { execTable } from "./orm-core/DrizzleRepository.js";
+import { createIdempotencyTable, idempotencyKeyTable } from "../entity/idempotencyEntity.js";
+import { reserveIdempotencyKeyMysql } from "./queryKit.js";
+import { assertPageQuery } from "nodefony";
+import { and, asc, count, eq, gt, is, like, lt, lte } from "drizzle-orm";
+import { MySqlTable } from "drizzle-orm/mysql-core";
+//#region nodefony/src/DrizzleIdempotencyStore.ts
+/**
+* Lignes affectées d'une mutation builder, normalisées par driver :
+* better-sqlite3 `{changes}` / pg `{rowCount}` / mysql2 tuple
+* `[ResultSetHeader{affectedRows}, fields]`.
+*/
+function affectedOf(result) {
+	if (Array.isArray(result)) return result[0]?.affectedRows ?? 0;
+	const r = result;
+	return r.changes ?? r.rowCount ?? 0;
+}
+/** Bail par défaut d'une entrée *in-flight* : 60 s (au-delà = exécution abandonnée). */
+const DEFAULT_LEASE_MS = 6e4;
+/** Rétention par défaut d'une réponse mémorisée : 10 min (rejeu plausible). */
+const DEFAULT_TTL_MS = 6e5;
+/**
+* Store d'idempotence **Drizzle** (driver `better-sqlite3` en test, Postgres/MySQL
+* en prod) — implémentation SQL d'{@link IIdempotencyStore} (contrat au CORE) pour
+* dédoublonner les mutations rejouées PARTAGÉ cross-pod, là où le store mémoire par
+* défaut reste affine à un pod.
+*
+* **Pourquoi SQL plutôt que Redis** : un cluster qui possède déjà une base
+* (Postgres) mais pas de Redis obtient la dédup cross-pod sans nouvelle infra.
+*
+* **Réservation atomique (`begin`)** — clé de voûte. Un `INSERT … ON CONFLICT(key)
+* DO UPDATE SET … WHERE expiresAt < now RETURNING` = l'équivalent SQL du `SET … NX
+* PX` Redis, en **une seule instruction atomique** côté serveur :
+*  - clé absente → l'`INSERT` passe → 1 ligne retournée → `fresh` ;
+*  - clé présente mais **morte** (bail/rétention expirés) → le `DO UPDATE … WHERE
+*    expirée` la **vole** atomiquement → 1 ligne retournée → `fresh` ;
+*  - clé présente et **vivante** → le `WHERE` du `DO UPDATE` échoue → 0 ligne
+*    retournée → on lit l'état (`in-flight` / `replayed` / `mismatch`).
+*
+* Cette atomicité au niveau de l'INSTRUCTION est ce qui rend la dédup correcte
+* sous concurrence inter-pods (deux `begin` simultanés sur deux pods : un seul
+* gagne la réservation). Le store ne renvoie JAMAIS `fresh` sur le chemin de
+* contention → anti double-effet garanti (l'invariant capital d'un store
+* d'idempotence).
+*
+* **Pas de TTL natif** (≠ Redis `PX`) → un {@link DrizzleIdempotencyStore.gc}
+* applicatif purge les entrées expirées. À mutualiser avec la maintenance du store
+* de session (chantier « GC moderne »).
+*
+* **Empreinte préservée à la complétion** : `complete()` ne touche pas la colonne
+* `fingerprint` (UPDATE ciblé) → un rejeu de la clé avec un AUTRE payload après
+* complétion est toujours détecté (`mismatch` 422, draft §2.7).
+*
+* ⚠️ **SQLite = banc de test de la sémantique** : un fichier SQLite est
+* mono-machine (lock d'écriture) → aucun intérêt multi-pod. La cible RÉELLE est
+* **Postgres/MySQL** (changement de driver). La preuve cross-pod réelle passe par
+* un e2e Postgres (≠ test SQLite, qui valide la sémantique séquentielle).
+*
+* **Résolution LAZY + dégradation gracieuse** (calqué sur `RedisIdempotencyStore`,
+* le frère idempotence) : le store ne capture PAS le handle Drizzle à la
+* construction mais le résout à CHAQUE appel — l'ordre de boot n'est pas garanti
+* (le framework résout ce store à `onKernelBoot`, quand l'ORM peut ne pas être
+* encore connecté), et l'ORM se déconnecte au shutdown avant le drain des
+* serveurs (cf le gotcha `SessionStorage`). Si le handle est `null` (ORM non
+* connecté), `begin` renvoie `fresh` (la mutation s'exécute SANS dédup) et
+* `complete`/`abort`/`gc` sont des no-op — l'idempotence est temporairement
+* inactive plutôt que de crasher une mutation en vol. Trade-off identique à Redis
+* (un rejeu pendant la fenêtre peut ré-exécuter) ; en pratique la base
+* d'idempotence = la base applicative → « connectée » est vrai sur tout le service.
+*
+* **Câblage** : la classe reste PURE (`import type` du contrat core), mais le
+* module drizzle s'enregistre LUI-MÊME au boot — `registerStores.ts:311-316` pose
+* l'entité (`registerIdempotencyEntities`) puis la fabrique
+* (`registerIdempotencyStore("drizzle", …)`, registre `@nodefony/framework`), sans
+* rien demander à l'application. Celle-ci choisit seulement le store à employer
+* (`idempotency.store`). L'enregistrement est idempotent : une fabrique déjà
+* posée n'est pas écrasée, donc une app peut fournir la sienne avant le boot.
+*/
+var DrizzleIdempotencyStore = class DrizzleIdempotencyStore {
+	#resolveDb;
+	#table;
+	/** Colonnes par nom logique, vue canonique (les specs colKit partagent les
+	*  NOMS entre dialectes → les builders restent dialecte-agnostiques). */
+	#c;
+	/** `true` si la table injectée est la variante MySQL → `begin` route sur la
+	*  réservation `ON DUPLICATE KEY UPDATE` du queryKit (pas de RETURNING). */
+	#mysql;
+	#now;
+	#leaseMs;
+	#ttlMs;
+	#resolveLocation;
+	/** Compteur LOCAL best-effort des réservations faites par CE pod (cf {@link size}). */
+	#pending = 0;
+	/**
+	* @param resolveDb - résolveur **lazy** du handle Drizzle (`null` = ORM non
+	*   connecté → dégradation gracieuse). Lazy car l'ordre de boot/shutdown n'est
+	*   pas garanti à la construction.
+	* @param now - horloge (epoch ms) injectable pour des tests déterministes.
+	* @param leaseMs - bail d'une entrée *in-flight* (ms).
+	* @param ttlMs - rétention d'une réponse mémorisée (ms).
+	* @param table - variante de table à utiliser (dialecte). Défaut = variante
+	*   SQLite ; `from()` injecte la variante du dialecte de l'ORM.
+	* @param resolveLocation - résolveur **lazy** de l'emplacement physique de la
+	*   base ({@link DrizzleOrm.location}) pour Studio. Lazy (comme `resolveDb`) car
+	*   le store est fabriqué AVANT le connect de l'ORM → l'emplacement n'est lisible
+	*   qu'une fois l'ORM enregistré (lu au `onReady`, pas à la construction).
+	*/
+	constructor(resolveDb, now = Date.now, leaseMs = DEFAULT_LEASE_MS, ttlMs = DEFAULT_TTL_MS, table = idempotencyKeyTable, resolveLocation) {
+		this.#resolveDb = resolveDb;
+		this.#table = table;
+		this.#c = execTable(table);
+		this.#mysql = is(table, MySqlTable);
+		this.#now = now;
+		this.#leaseMs = leaseMs;
+		this.#ttlMs = ttlMs;
+		this.#resolveLocation = resolveLocation;
+	}
+	/**
+	* Emplacement physique de la base (fichier SQLite) pour l'écran Studio « Stores »
+	* — lu par `readStoreLocation`. Résolu **lazy** (l'ORM n'existe pas à la
+	* construction) : `undefined` tant que l'ORM n'est pas enregistré, en `:memory:`,
+	* ou sur un backend réseau (pg/mysql → voir l'infra déclarée).
+	*/
+	get location() {
+		return this.#resolveLocation?.();
+	}
+	/**
+	* Construit le store depuis un {@link DrizzleOrm}. Le handle est résolu **lazy**
+	* (gardé par `isConnected()` → `null` tant que l'ORM n'est pas/plus connecté).
+	* L'entité (`registerIdempotencyEntities`) doit avoir été enregistrée **avant**
+	* `orm.connect()` (la table est créée au connect).
+	*
+	* @param orm - ORM Drizzle hébergeant la table `idempotency_key` (dialecte
+	*   sélectionne la variante de table — `orm.dialect`).
+	* @param now - horloge injectable (tests).
+	* @param leaseMs - bail *in-flight* (ms).
+	* @param ttlMs - rétention d'une réponse mémorisée (ms).
+	*/
+	static from(orm, now, leaseMs, ttlMs) {
+		return new DrizzleIdempotencyStore(() => orm.isConnected() ? orm.getNativeConnection() : null, now, leaseMs, ttlMs, createIdempotencyTable(orm.dialect), () => orm.location);
+	}
+	/**
+	* Approximation **per-pod, best-effort** : compteur local des réservations
+	* faites par CE pod (incrémenté au `fresh`, décrémenté au `complete`/`abort`),
+	* non décrémenté si le bail expire sans complétion, et désaligné cross-pod. La
+	* vérité cluster passe par un `COUNT(*)`, jamais ce getter (sync). Borné à ≥ 0.
+	*/
+	get size() {
+		return this.#pending < 0 ? 0 : this.#pending;
+	}
+	async begin(key, fingerprint) {
+		const db = this.#resolveDb();
+		if (!db) return { state: "fresh" };
+		const now = this.#now();
+		const leaseExpiresAt = now + this.#leaseMs;
+		let reserved;
+		if (this.#mysql) reserved = await reserveIdempotencyKeyMysql(db, {
+			key,
+			fingerprint,
+			now,
+			leaseExpiresAt
+		});
+		else reserved = (await db.insert(execTable(this.#table)).values({
+			key,
+			fingerprint,
+			state: "if",
+			response: null,
+			expiresAt: leaseExpiresAt
+		}).onConflictDoUpdate({
+			target: this.#c.key,
+			set: {
+				fingerprint,
+				state: "if",
+				response: null,
+				expiresAt: leaseExpiresAt
+			},
+			setWhere: lt(this.#c.expiresAt, now)
+		}).returning({ key: this.#c.key })).length > 0;
+		if (reserved) {
+			this.#pending++;
+			return { state: "fresh" };
+		}
+		const existing = (await db.select().from(execTable(this.#table)).where(eq(this.#c.key, key)))[0];
+		if (existing === void 0) return { state: "in-flight" };
+		if (existing.fingerprint !== fingerprint) return { state: "mismatch" };
+		if (existing.state === "done" && existing.response !== null) return {
+			state: "replayed",
+			response: existing.response
+		};
+		return { state: "in-flight" };
+	}
+	async complete(key, response) {
+		const db = this.#resolveDb();
+		if (!db) return;
+		if (affectedOf(await db.update(execTable(this.#table)).set({
+			state: "done",
+			response,
+			expiresAt: this.#now() + this.#ttlMs
+		}).where(and(eq(this.#c.key, key), eq(this.#c.state, "if")))) > 0) this.#dec();
+	}
+	async abort(key) {
+		const db = this.#resolveDb();
+		if (!db) return;
+		if (affectedOf(await db.delete(execTable(this.#table)).where(and(eq(this.#c.key, key), eq(this.#c.state, "if")))) > 0) this.#dec();
+	}
+	/**
+	* Purge les entrées mortes (`expiresAt <= now`) — supplée l'absence de TTL natif
+	* SQL (≠ Redis `PX`). À déclencher périodiquement (timer de maintenance, à
+	* mutualiser avec le GC du store de session).
+	*
+	* @param now - horloge de purge (défaut : horloge injectée).
+	* @returns le nombre d'entrées supprimées.
+	*/
+	async gc(now = this.#now()) {
+		const db = this.#resolveDb();
+		if (!db) return 0;
+		return affectedOf(await db.delete(execTable(this.#table)).where(lte(this.#c.expiresAt, now)));
+	}
+	/**
+	* {@inheritDoc IIdempotencyStore.listPage}
+	*
+	* Query builder dialect-agnostique (comme `gc`) : `LIMIT/OFFSET` + `COUNT`
+	* filtré. On ne SELECTe QUE les colonnes exposées — la réponse mémorisée
+	* (`response`) ne quitte jamais la base par ce chemin, quelle que soit la
+	* taille de la page.
+	*
+	* Les entrées expirées sont exclues (`expiresAt > now`) : le GC applicatif
+	* passe plus tard, mais une clé échue n'est déjà plus opposable.
+	*/
+	async listPage(query) {
+		assertPageQuery(query, "offset");
+		const limit = Math.max(1, Math.floor(query.limit));
+		const offset = Math.max(0, Math.floor(query.offset ?? 0));
+		const db = this.#resolveDb();
+		if (!db) return {
+			items: [],
+			total: 0,
+			limit,
+			offset,
+			hasNext: false
+		};
+		const table = execTable(this.#table);
+		const conds = [gt(this.#c.expiresAt, this.#now())];
+		if (query.state !== void 0) conds.push(eq(this.#c.state, query.state === "in-flight" ? "if" : "done"));
+		if (query.q !== void 0 && query.q.length > 0) conds.push(like(this.#c.key, `${query.q}%`));
+		const where = conds.length === 1 ? conds[0] : and(...conds);
+		const rows = await db.select({
+			key: this.#c.key,
+			state: this.#c.state,
+			expiresAt: this.#c.expiresAt
+		}).from(table).where(where).orderBy(asc(this.#c.expiresAt), asc(this.#c.key)).limit(limit + 1).offset(offset);
+		const hasNext = rows.length > limit;
+		const page = hasNext ? rows.slice(0, limit) : rows;
+		let total;
+		if (query.withTotal !== false) {
+			const counted = await db.select({ cnt: count() }).from(table).where(where);
+			total = Number(counted[0]?.cnt ?? 0);
+		}
+		return {
+			items: page.map((row) => ({
+				key: row.key,
+				state: row.state === "if" ? "in-flight" : "done",
+				expiresAtMs: Number(row.expiresAt),
+				hasResponse: row.state !== "if"
+			})),
+			total,
+			limit,
+			offset,
+			hasNext
+		};
+	}
+	/** Décrémente le compteur local borné à 0. */
+	#dec() {
+		if (this.#pending > 0) this.#pending--;
+	}
+};
+//#endregion
+export { DrizzleIdempotencyStore };