@nodefony/realtime 10.0.0-beta.5 → 10.0.0-beta.7

package/dist/nodefony/src/server/connectionAdmission.js

@@ -0,0 +1,242 @@
+import "./admissionBudget.js";
+import resolveBackplaneOriginId from "../backplane/originId.js";
+import { isPromise } from "nodefony";
+// nodefony/src/server/connectionAdmission.ts
+const QUEUED = 0;
+const IN_FLIGHT = 1;
+const DONE = 2;
+/**
+* Admission des abonnements d'UNE connexion aux canaux qui déclarent `allow` — appels bornés, file d'attente, délai, verdict (ADR-0021 §S10 et §S10 bis).
+*
+* Coûts, par construction :
+* - une règle qui répond `true`/`false` sans promesse ne crée ni minuteur, ni
+*   promesse, ni entrée d'attente ;
+* - au-delà de `maxPendingAllowsPerConnection` appels en vol, la demande ATTEND
+*   son tour (jamais `limit` : le rejeu au `welcome` renvoie tous les canaux
+*   d'un coup) ; la file reste `null` tant que personne n'attend ;
+* - un seul minuteur par connexion, armé sur l'échéance de tête : les demandes
+*   arrivent dans l'ordre de leurs échéances, la plus ancienne non tranchée est
+*   donc toujours la prochaine à expirer.
+*
+* Seul `=== true` admet ; une exception ou un rejet valent `forbidden` ; un
+* délai dépassé ou une saturation valent `unavailable`, et un verdict arrivé
+* après coup est ignoré.
+*/
+var ConnectionAdmission = class {
+	#host;
+	#budget;
+	#who;
+	#explain;
+	#pending = null;
+	#inFlight = 0;
+	#timer = null;
+	#onTimer = null;
+	/**
+	* @param host - la connexion qui ouvre ou refuse.
+	* @param budget - le budget de l'exemplaire (plafond global, coupe-circuit).
+	* @param who - identité d'admission gelée de la connexion.
+	* @param explain - rédiger le détail des refus (hors production).
+	*/
+	constructor(host, budget, who, explain) {
+		this.#host = host;
+		this.#budget = budget;
+		this.#who = who;
+		this.#explain = explain;
+	}
+	/** Demandes en attente de verdict — comptées dans le plafond de canaux de la connexion. */
+	get unsettled() {
+		return this.#pending === null ? 0 : this.#pending.size;
+	}
+	/**
+	* Un abonnement à ce canal attend-il déjà son verdict ? S'il avait été annulé par un `unsubscribe`, il est ranimé : le verdict à venir répondra.
+	*
+	* @returns `true` si la demande est déjà en attente (rien d'autre à faire).
+	*/
+	revive(channel) {
+		const record = this.#pending?.get(channel);
+		if (record === void 0) return false;
+		record.cancelled = false;
+		return true;
+	}
+	/** `unsubscribe` pendant l'attente : le verdict à venir sera jeté sans réponse. */
+	cancel(channel) {
+		const record = this.#pending?.get(channel);
+		if (record !== void 0) record.cancelled = true;
+	}
+	/**
+	* Demande l'admission sur `channel` selon sa règle — l'anonyme est refusé d'office sauf `anonymous: true`.
+	*
+	* @param channel - nom exact du canal demandé.
+	* @param rule - règle résolue par le hub pour ce canal.
+	*/
+	request(channel, rule) {
+		if (!this.#who.authenticated && !rule.anonymous) {
+			this.#host.deny(channel, "forbidden", this.#explain ? `le canal « ${channel} » déclare une règle d'admission (allow) : une connexion anonyme n'y entre pas sans \`anonymous: true\` dans sa politique` : void 0);
+			return;
+		}
+		if (this.#inFlight >= this.#budget.maxPerConnection) {
+			this.#track(channel, rule, QUEUED);
+			return;
+		}
+		this.#call(channel, rule, null);
+	}
+	/** Fermeture de la connexion : minuteur coupé, places rendues, verdicts à venir jetés. */
+	close() {
+		if (this.#timer !== null) {
+			clearTimeout(this.#timer);
+			this.#timer = null;
+		}
+		const pending = this.#pending;
+		if (pending !== null) {
+			for (const record of pending.values()) {
+				if (record.status === IN_FLIGHT) this.#budget.release();
+				record.status = DONE;
+			}
+			this.#pending = null;
+		}
+		this.#inFlight = 0;
+	}
+	/** Appelle `allow` ; `record` est `null` pour une demande qui n'a pas attendu. */
+	#call(channel, rule, record) {
+		const granted = this.#budget.acquire();
+		if (granted !== -1) {
+			if (record !== null) this.#finish(record);
+			this.#host.deny(channel, "unavailable", !this.#explain ? void 0 : granted > 0 ? `admissions suspendues pendant ${granted} ms après une série de règles allow sans réponse sur ce serveur — réessaie après ce délai` : "trop d'admissions en cours sur ce serveur (maxPendingAllowsTotal) — réessaie", granted > 0 ? granted : void 0);
+			return;
+		}
+		let verdict;
+		try {
+			verdict = rule.allow(channel, this.#who);
+		} catch (error) {
+			this.#budget.release();
+			if (record !== null) this.#finish(record);
+			this.#refuseOnError(channel, error);
+			return;
+		}
+		if (!isPromise(verdict)) {
+			this.#budget.release();
+			if (record !== null) this.#finish(record);
+			this.#conclude(channel, verdict);
+			return;
+		}
+		const tracked = record ?? this.#track(channel, rule, IN_FLIGHT);
+		tracked.status = IN_FLIGHT;
+		this.#inFlight += 1;
+		verdict.then((value) => {
+			if (this.#settle(tracked)) this.#conclude(tracked.channel, value);
+			this.#pump();
+		}, (error) => {
+			if (this.#settle(tracked)) this.#refuseOnError(tracked.channel, error);
+			this.#pump();
+		});
+	}
+	/** Verdict d'une règle : seul `true` admet. */
+	#conclude(channel, verdict) {
+		if (verdict === true) {
+			this.#open(channel);
+			return;
+		}
+		this.#host.deny(channel, "forbidden", !this.#explain ? void 0 : verdict === false ? `la règle d'admission (allow) du canal « ${channel} » a refusé cette identité` : `la règle d'admission (allow) du canal « ${channel} » a rendu une valeur de type ${typeof verdict} : seul \`true\` admet`);
+	}
+	/** Une règle qui lève ou rejette refuse (fail-closed) ; le message ne part au client qu'hors production. */
+	#refuseOnError(channel, error) {
+		const warn = this.#budget.shouldWarn("throw", performance.now());
+		const message = warn || this.#explain ? error instanceof Error ? error.message : String(error) : "";
+		if (warn) this.#host.warn(`règle d'admission (allow) du canal « ${channel} » en échec : ${message}`);
+		this.#host.deny(channel, "forbidden", this.#explain ? `la règle d'admission (allow) du canal « ${channel} » a levé : ${message}` : void 0);
+	}
+	/** Ouvre le canal admis ; un échec d'ouverture est journalisé, jamais propagé (rappel de promesse ou de minuteur). */
+	#open(channel) {
+		try {
+			this.#host.open(channel);
+		} catch (error) {
+			this.#host.warn(`canal « ${channel} » admis mais non ouvert : ` + (error instanceof Error ? error.message : String(error)));
+		}
+	}
+	/**
+	* Termine un appel en vol dont le verdict arrive.
+	*
+	* @returns `false` si la demande est déjà tranchée (délai dépassé, connexion
+	*   fermée) ou annulée : le verdict est alors jeté.
+	*/
+	#settle(record) {
+		if (record.status === DONE) return false;
+		this.#inFlight -= 1;
+		this.#budget.release();
+		this.#finish(record);
+		return !record.cancelled;
+	}
+	/** Inscrit une demande qui attend ; arme le minuteur s'il ne l'est pas déjà sur une échéance plus proche. */
+	#track(channel, rule, status) {
+		const deadline = performance.now() + this.#budget.timeoutMs;
+		const record = {
+			channel,
+			rule,
+			deadline,
+			status,
+			cancelled: false
+		};
+		(this.#pending ??= /* @__PURE__ */ new Map()).set(channel, record);
+		if (this.#timer === null) this.#arm(deadline);
+		return record;
+	}
+	/** Marque une demande tranchée et la retire ; plus rien en attente → minuteur coupé. */
+	#finish(record) {
+		record.status = DONE;
+		const pending = this.#pending;
+		if (pending === null) return;
+		pending.delete(record.channel);
+		if (pending.size === 0 && this.#timer !== null) {
+			clearTimeout(this.#timer);
+			this.#timer = null;
+		}
+	}
+	/** Lance les demandes en attente, dans l'ordre, tant que des places se libèrent. */
+	#pump() {
+		while (this.unsettled > this.#inFlight && this.#inFlight < this.#budget.maxPerConnection) {
+			const record = this.#nextQueued();
+			if (record === null) return;
+			if (record.cancelled) {
+				this.#finish(record);
+				continue;
+			}
+			this.#call(record.channel, record.rule, record);
+		}
+	}
+	/** Première demande qui n'a pas encore appelé `allow` — les appels en vol, au plus `maxPerConnection`, la précèdent. */
+	#nextQueued() {
+		if (this.#pending === null) return null;
+		for (const record of this.#pending.values()) if (record.status === QUEUED) return record;
+		return null;
+	}
+	#arm(deadline) {
+		this.#timer = setTimeout(this.#onTimer ??= () => this.#expire(), Math.max(1, Math.ceil(deadline - performance.now())));
+		this.#timer.unref();
+	}
+	/** Échéance de tête atteinte : tranche en `unavailable` toutes les demandes échues, puis réarme sur la suivante. */
+	#expire() {
+		this.#timer = null;
+		const pending = this.#pending;
+		if (pending === null) return;
+		const now = performance.now();
+		let timedOut = null;
+		for (const record of pending.values()) {
+			if (record.deadline > now) {
+				this.#arm(record.deadline);
+				break;
+			}
+			const called = record.status === IN_FLIGHT;
+			if (called) {
+				this.#inFlight -= 1;
+				this.#budget.release();
+				this.#budget.recordTimeout(now);
+				timedOut = record.channel;
+			} else this.#budget.recordQueueExpired();
+			this.#finish(record);
+			if (!record.cancelled) this.#host.deny(record.channel, "unavailable", !this.#explain ? void 0 : called ? `la règle d'admission (allow) du canal « ${record.channel} » n'a pas répondu en ${this.#budget.timeoutMs} ms (allowTimeoutMs) — réessaie` : `demande d'abonnement à « ${record.channel} » restée en attente ${this.#budget.timeoutMs} ms derrière les admissions de cette connexion (allowTimeoutMs) — réessaie`, this.#budget.retryAfter(now));
+		}
+		if (timedOut !== null && this.#budget.shouldWarn("timeout", now)) this.#host.warn(`règle d'admission (allow) du canal « ${timedOut} » sans réponse en ${this.#budget.timeoutMs} ms (exemplaire ${resolveBackplaneOriginId()})`);
+		this.#pump();
+	}
+};
+export { ConnectionAdmission };

package/dist/nodefony/src/server/contractRoutes.js

@@ -0,0 +1,75 @@
+import { isRecord } from "../guards.js";
+import { BootConfigurationError, bridgeServesVerb, isSimpleRouteTemplate } from "nodefony";
+// nodefony/src/server/contractRoutes.ts
+const BRIDGE_VERBS = /* @__PURE__ */ new Set([
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE"
+]);
+const ROUTE_PARTS = [
+	"body",
+	"query",
+	"params"
+];
+/** Chemin comparable : barres finales retirées, la racine reste `/`. */
+function normalizePath(path) {
+	let end = path.length;
+	while (end > 1 && path.charCodeAt(end - 1) === 47) end--;
+	return end === path.length ? path : path.slice(0, end);
+}
+/**
+* Lit la table `serverRoutes` qu'une classe de contrôleur déclare en statique —
+* `null` quand elle n'en déclare pas (aucun contrôle).
+*
+* @param ctor - la classe du contrôleur.
+* @returns la table, ou `null`.
+* @throws BootConfigurationError si la table n'est pas un objet.
+*/
+function readContractRoutes(ctor) {
+	const table = Reflect.get(ctor, "serverRoutes");
+	if (table === void 0) return null;
+	if (!isRecord(table)) throw new BootConfigurationError(`${typeof ctor === "function" ? ctor.name : "(contrôleur)"} : « serverRoutes » doit être un objet { "<VERBE> <chemin>": { body?, query? } }.`);
+	return table;
+}
+/**
+* Vérifie, au démarrage, que chaque route du contrat est SERVIE par le pont :
+* une route montée au même chemin, qui accepte le verbe par la socket, et dont
+* les schémas sont LES MÊMES OBJETS que ceux que la table déclare. Coût nul par
+* requête : la vérification n'a lieu qu'une fois.
+*
+* Sans elle, un contrat qui type `chat.post("/chat/send", …)` compilerait
+* contre une route absente, servie en HTTP seulement, ou validant un autre
+* schéma — et l'erreur n'apparaîtrait qu'au premier appel.
+*
+* @param owner - nom de la classe qui déclare la table (pour le message).
+* @param table - la table `serverRoutes` (`"<VERBE> <chemin>"` → `{ body?, query? }`).
+* @param mounted - les routes montées.
+* @throws BootConfigurationError à la première entrée qui n'est pas servie ;
+*   le message nomme la classe, l'entrée et la cause.
+*/
+function assertContractRoutes(owner, table, mounted) {
+	for (const entry in table) {
+		const where = `${owner}.serverRoutes « ${entry} »`;
+		const space = entry.indexOf(" ");
+		const verb = space === -1 ? "" : entry.slice(0, space);
+		const rawPath = space === -1 ? "" : entry.slice(space + 1);
+		if (!BRIDGE_VERBS.has(verb) || rawPath.charCodeAt(0) !== 47) throw new BootConfigurationError(`${where} : la clé s'écrit "<VERBE> <chemin>", VERBE parmi ${[...BRIDGE_VERBS].join(", ")}, chemin commençant par « / ».`);
+		const declared = table[entry];
+		if (!isRecord(declared)) throw new BootConfigurationError(`${where} : la valeur s'écrit { body?, query?, params? } (les schémas de la route).`);
+		for (const key in declared) if (key !== "body" && key !== "query" && key !== "params") throw new BootConfigurationError(`${where} : clé « ${key} » inconnue — seuls body, query et params se déclarent.`);
+		if (!isSimpleRouteTemplate(rawPath)) throw new BootConfigurationError(`${where} : seuls des segments « {nom} » entiers se déclarent dans un contrat — pas de contrainte en ligne « {id}(\\d+) », de segment facultatif « {slug}? » ni de variable collée « .{format} ». Contraindre la variable par « requirements » sur la route.`);
+		const path = normalizePath(rawPath);
+		const atPath = mounted.filter((r) => normalizePath(r.path) === path);
+		if (atPath.length === 0) throw new BootConfigurationError(`${where} : aucune route montée au chemin ${path}.`);
+		const route = atPath.find((r) => bridgeServesVerb(r.methods, verb));
+		if (route === void 0) throw new BootConfigurationError(`${where} : la route ${path} ne sert pas ${verb} par la socket — ses méthodes doivent inclure "${verb}" et "WEBSOCKET"${verb === "GET" ? " (ou « WEBSOCKET » seul)" : ""}.`);
+		for (const part of ROUTE_PARTS) {
+			const expected = declared[part];
+			const actual = route.schema?.[part];
+			if (expected !== actual) throw new BootConfigurationError(`${where} : le schéma « ${part} » ${expected === void 0 ? "n'est pas déclaré, mais la route en valide un" : actual === void 0 ? "est déclaré, mais la route n'en valide aucun" : "n'est pas celui que la route valide (même objet attendu)"}.`);
+		}
+	}
+}
+export { assertContractRoutes, readContractRoutes };

package/dist/nodefony/src/server/deniedDetail.js

@@ -22,7 +22,14 @@
 *   sinon un objet vide.
 */
 function deniedDetail(env, detail) {
-	if (!env || env === "production") return {};
-	return { detail };
+	return explainsDenials(env) ? { detail } : {};
 }
-export { deniedDetail };
+/**
+* Le détail d'un refus part-il au client dans ce mode ? Hors production seulement — la règle de {@link deniedDetail}, lue AVANT de rédiger la phrase : en production, aucune chaîne n'est composée pour être jetée.
+*
+* @param env - le mode du kernel serveur, s'il est connu ; une absence vaut production.
+*/
+function explainsDenials(env) {
+	return !!env && env !== "production";
+}
+export { deniedDetail, explainsDenials };

package/dist/nodefony/src/server/frameAdmission.js

@@ -0,0 +1,160 @@
+// nodefony/src/server/frameAdmission.ts
+/**
+* Verdicts du verrou retenus par connexion, au plus (ADR-0022 §6, décision 1 ter).
+*
+* Borne la table qu'un client remplit en poussant sur des canaux entrants : au-delà,
+* le verrou est consulté à chaque trame, il n'est jamais contourné. Une admission
+* par `allow` n'y est pas soumise — elle est déjà bornée par le plafond de canaux
+* de la connexion.
+*/
+const MAX_RETAINED_FRAME_VERDICTS = 64;
+/**
+* Méthodes du protocole : leurs trames ne sont JAMAIS admises d'office, même si un
+* canal entrant porte ce nom. `subscribe` et `api.request` restent sur le verrou ;
+* `ping` et `unsubscribe` passent sans règle (le verrou n'a rien à en dire).
+*/
+const PROTOCOL_METHODS = /* @__PURE__ */ new Set([
+	"subscribe",
+	"unsubscribe",
+	"ping",
+	"api.request"
+]);
+/**
+* La connexion peut-elle admettre d'office les trames de ce nom ?
+*
+* Seulement un canal ENTRANT déclaré — une clé PROPRE de la table, jamais une
+* héritée de son prototype —, qui n'est ni une méthode du protocole ni une
+* action : la lecture admise ne regarde que le nom, et une requête d'action du
+* même nom passerait sinon sans le verrou. Cold path (admission, jamais par trame).
+*/
+function canAdmit(state, inbound, name) {
+	return Object.hasOwn(inbound, name) && !PROTOCOL_METHODS.has(name) && !state.peer.methods.includes(name);
+}
+/**
+* Table des admis de la connexion, créée à la première admission.
+*
+* Mêmes clés, dans le même ordre, que la table entrante, toutes à `false` :
+* toutes les connexions d'un contrôleur partagent ainsi UNE forme d'objet, et la
+* lecture chaude reste monomorphe. Mesuré sur la trame réelle (médiane de 9) :
+* objet de forme commune ≈ 0 ns, objets de formes diverses +15 ns, `Set` +26 à
+* +30 ns. Une admission passe une clé existante à `true`, un retrait à `false` —
+* jamais d'ajout ni de `delete`, qui changeraient la forme.
+*/
+function admittedTable(state, inbound) {
+	let admitted = state.admitted;
+	if (admitted === null) {
+		admitted = {};
+		for (const name of Object.keys(inbound)) admitted[name] = false;
+		state.admitted = admitted;
+	}
+	return admitted;
+}
+/**
+* Retire TOUTE admission d'un canal à la connexion — marque de sa règle ET verdict retenu du verrou — quand le serveur l'en éjecte ou le termine (ADR-0022 §6 décision 3).
+*
+* Plus fort que {@link releaseRuleAdmission}, qui garde le verdict du verrou :
+* après une éjection, une trame entrante sur ce canal repasse par le verrou.
+*
+* @param state - état de la connexion.
+* @param channel - canal dont la connexion est retirée.
+*/
+function revokeAdmission(state, channel) {
+	const retained = state.retained;
+	if (retained !== null) {
+		const at = retained.indexOf(channel);
+		if (at !== -1) {
+			retained.splice(at, 1);
+			if (retained.length === 0) state.retained = null;
+		}
+	}
+	const admitted = state.admitted;
+	if (admitted?.[channel] === true) admitted[channel] = false;
+}
+/**
+* Retire l'admission d'un canal à la fin de son abonnement quand elle en dépendait — celle d'un canal à `allow`, dont l'abonnement est la condition.
+*
+* Un verdict du verrou sur un canal SANS `allow` ne tient qu'à l'identité et
+* survit au désabonnement ; sur un canal à `allow`, il ne valait que le temps
+* de l'abonnement (ADR-0022 §6, décisions 1 et 1 quater).
+*
+* @param state - état de la connexion.
+* @param channel - canal quitté.
+* @param hub - hub qui porte les règles d'admission.
+*/
+function releaseRuleAdmission(state, channel, hub) {
+	if (state.admitted?.[channel] !== true) return;
+	if (hub.resolveChannelAdmission(channel) !== null) revokeAdmission(state, channel);
+}
+/**
+* Retient le « oui » du verrou pour un canal entrant (jamais un refus).
+*
+* Au plus {@link MAX_RETAINED_FRAME_VERDICTS} par connexion, sauf sur un canal
+* à `allow` (`bySubscription`) : ceux-là sont déjà bornés par le plafond de
+* canaux ouverts. La première retenue inscrit la connexion auprès du hub, qui
+* pourra la vider si une politique arrive après coup.
+*/
+function retainVerdict(state, method, hub, bySubscription) {
+	const retained = state.retained;
+	if (!bySubscription && retained !== null && retained.length >= 64) return;
+	const inbound = state.inbound;
+	if (inbound === null || !canAdmit(state, inbound, method)) return;
+	admittedTable(state, inbound)[method] = true;
+	if (retained === null) {
+		state.retained = [method];
+		hub.trackRetainedVerdicts(state);
+	} else retained.push(method);
+}
+/**
+* Oublie les verdicts du verrou retenus par la connexion — leur politique vient
+* de changer. Ceux des canaux à `allow` compris : une écriture inscrite après
+* coup doit être jugée à la trame suivante, abonnement ou pas. `allow`, lui,
+* n'est pas redemandé — l'abonnement reste.
+*
+* @param state - état de la connexion.
+*/
+function dropRetainedVerdicts(state) {
+	const retained = state.retained;
+	if (retained === null) return;
+	const admitted = state.admitted;
+	if (admitted !== null) for (const name of retained) admitted[name] = false;
+	state.retained = null;
+}
+/**
+* Juge une trame entrante que la connexion n'a pas admise d'office (ADR-0022 §6, décision 1 ter).
+*
+* Dans l'ordre :
+* - une REQUÊTE (action, `api.request`) passe par le verrou, toujours ;
+* - `ping` et `unsubscribe` passent sans règle ;
+* - `subscribe` passe par le verrou (`allow` est jugé après, à l'ouverture) ;
+* - un nom hérité du prototype de la table entrante est refusé ;
+* - un canal entrant à `allow` exige l'abonnement de CETTE connexion (`allow`
+*   n'est jamais rappelé), puis passe par le verrou comme les autres ;
+* - un canal entrant passe par le verrou — lecture ET écriture —, dont le « oui »
+*   est retenu ;
+* - toute autre notification passe par le verrou.
+*
+* Le premier test du contrôleur (`admitted[method] === true`) a déjà écarté les trames
+* admises : rien ici n'est sur le chemin d'une trame chaude.
+*
+* @param state - état de la connexion.
+* @param frame - trame déjà classée par le pair.
+* @param hub - hub qui porte le verrou et les règles.
+* @returns `true` si la trame peut être distribuée.
+*/
+function gateFrame(state, frame, hub) {
+	if ("id" in frame) return hub.runAuthorizer(frame, state.peer);
+	const method = frame.method;
+	if (method === "ping" || method === "unsubscribe") return true;
+	const inbound = state.inbound;
+	if (method === "subscribe" || inbound === null) return hub.runAuthorizer(frame, state.peer);
+	if (!Object.hasOwn(inbound, method)) {
+		if (method in inbound) return false;
+		return hub.runAuthorizer(frame, state.peer);
+	}
+	const bySubscription = hub.resolveChannelAdmission(method) !== null;
+	if (bySubscription && !state.channels.has(method)) return false;
+	if (!hub.runAuthorizer(frame, state.peer)) return false;
+	retainVerdict(state, method, hub, bySubscription);
+	return true;
+}
+export { MAX_RETAINED_FRAME_VERDICTS, dropRetainedVerdicts, gateFrame, releaseRuleAdmission, revokeAdmission };