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

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

@@ -0,0 +1,488 @@
+import { isRecord } from "../guards.js";
+// nodefony/src/server/channelPresence.ts
+/**
+* Fenêtre de regroupement des changements de présence vers le navigateur (ms) — front montant : le premier changement d'un canal calme part tout de suite, les suivants attendent la fin de la fenêtre (ADR-0025 P2 bis).
+*/
+const PRESENCE_WINDOW_MS = 250;
+/** Seuil par défaut d'identités nommées au-delà duquel la trame ne porte que les nombres (ADR-0025 P2 bis). */
+const DEFAULT_PRESENCE_MAX_NAMED = 1e3;
+const PRESENCE_OPTION_KEYS = /* @__PURE__ */ new Set(["grace", "maxNamed"]);
+/**
+* Départ d'un PAIR retenu par la grâce (pod oublié, arrêté, remplacé) — ses onglets restent comptés jusqu'à l'échéance. Forme fixe : alloué au seul départ d'un pod, chemin froid.
+*/
+var RemoteDeparture = class {
+	deadline;
+	tabs;
+	constructor(deadline, tabs) {
+		this.deadline = deadline;
+		this.tabs = tabs;
+	}
+};
+/** Entier sûr ≥ 0 ? */
+function isCount(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+/**
+* Défaut de la valeur de la clé `presence` d'une politique, ou `null` si elle est recevable — en clair, pour que le refus au démarrage dise QUOI corriger.
+*
+* @param value - valeur de `policy.presence` (`unknown` : une politique se lit
+*   depuis une métadonnée publique).
+*/
+function presenceDefect(value) {
+	if (value === void 0 || typeof value === "boolean") return null;
+	if (!isRecord(value) || Array.isArray(value)) return "« presence » doit être un booléen ou un objet d'options";
+	for (const key of Object.keys(value)) if (!PRESENCE_OPTION_KEYS.has(key)) return `« presence » : option inconnue « ${key} » (options admises : ${[...PRESENCE_OPTION_KEYS].join(", ")})`;
+	if (value.grace !== void 0 && !isCount(value.grace)) return "« presence.grace » doit être un entier de millisecondes ≥ 0";
+	if (value.maxNamed !== void 0 && !isCount(value.maxNamed)) return "« presence.maxNamed » doit être un entier ≥ 0";
+	return null;
+}
+/**
+* Réglages résolus de la présence qu'une politique déclare, ou `null` si elle n'en déclare pas.
+*
+* Précondition : la politique a passé {@link presenceDefect}.
+*/
+function presenceSettingsOf(policy) {
+	const presence = policy?.presence;
+	if (presence === void 0 || presence === false) return null;
+	if (presence === true) return {
+		grace: 0,
+		maxNamed: DEFAULT_PRESENCE_MAX_NAMED
+	};
+	return {
+		grace: presence.grace ?? 0,
+		maxNamed: presence.maxNamed ?? 1e3
+	};
+}
+/**
+* Deux politiques déclarent-elles la même présence ? Défauts appliqués : `true` et `{ grace: 0 }` sont la même.
+*
+* Sert à refuser deux déclarations d'un même nom qui ne diffèrent que par la
+* présence — une seule s'appliquerait. Démarrage seulement.
+*/
+function samePresence(a, b) {
+	const x = presenceSettingsOf(a);
+	const y = presenceSettingsOf(b);
+	if (x === null || y === null) return x === y;
+	return x.grace === y.grace && x.maxNamed === y.maxNamed;
+}
+/**
+* État de présence LOCAL d'un canal à présence (ADR-0025 P2 bis, P5) — identités nommées et onglets, connexions non nommées, version, changements en attente de la fenêtre, départs en grâce.
+*
+* Alloué au premier client d'un canal qui déclare `presence`, jamais pour un
+* autre canal. Ne connaît ni l'horloge ni le protocole : le hub lui passe
+* l'instant et fabrique les trames. Les changements portent des valeurs
+* ABSOLUES (nombre d'onglets, départ), donc rejouer un changement déjà inclus
+* dans une liste ne change rien — c'est ce qui permet de servir à un nouvel
+* abonné la liste prise au dernier envoi, encodée une fois.
+*
+* Sur un canal DIFFUSÉ entre pods, c'est aussi l'agrégat de la vue des pairs
+* ({@link IPresenceAggregate}) : les compteurs portent le TOTAL (local + pairs),
+* et une table à part garde la seule part locale — ce que ce pod annonce à ses
+* pairs, en deltas par lot. Ailleurs, cette table n'existe pas.
+*/
+var ChannelPresence = class {
+	channel;
+	settings;
+	/** Canal diffusé entre pods : sa part locale part sur le bus, la vue des pairs s'y ajoute. */
+	distributed;
+	/** Fin de la fenêtre de regroupement en cours (horloge monotone, ms). */
+	windowEnd = Number.NEGATIVE_INFINITY;
+	/** Liste complète encodée, servie telle quelle jusqu'au prochain envoi. */
+	listFrame = null;
+	/** Le canal est-il encore tenu par le hub ? `false` après son retrait. */
+	live = true;
+	/**
+	* Fin de la synchronisation initiale avec les pairs (ms monotone) — la vue
+	* n'est que locale tant que la demande d'état du premier abonné n'a pas eu le
+	* temps d'être servie ; `0` = synchronisée (ou canal non diffusé).
+	*/
+	syncUntil = 0;
+	#named = /* @__PURE__ */ new Map();
+	#unnamed = 0;
+	#local;
+	#localUnnamed = 0;
+	#busBefore = null;
+	#busUnnamedBefore = -1;
+	#partial = false;
+	#version = 0;
+	#dirty = null;
+	#countsDirty = false;
+	#namedSent = true;
+	#resumeNamed;
+	#leaving = null;
+	#remoteLeaving = null;
+	/**
+	* @param distributed - le canal est diffusé entre pods (bus branché, préfixe
+	*   diffusé) : la part locale est tenue à part pour le bus.
+	*/
+	constructor(channel, settings, distributed = false) {
+		this.channel = channel;
+		this.settings = settings;
+		this.distributed = distributed;
+		this.#local = distributed ? /* @__PURE__ */ new Map() : null;
+		this.#resumeNamed = settings.maxNamed - Math.floor(settings.maxNamed / 10);
+	}
+	/** La part locale a-t-elle changé depuis le dernier lot ? */
+	get busDirty() {
+		return this.#busBefore !== null || this.#busUnnamedBefore >= 0;
+	}
+	/** La vue est-elle connue incomplète (synchronisation initiale, trou chez un pair) ? */
+	get partial() {
+		return this.#partial;
+	}
+	/** Version courante de la vue (+1 par trame de changements). */
+	get version() {
+		return this.#version;
+	}
+	/** Des changements attendent-ils un envoi ? */
+	get dirty() {
+		return this.#dirty !== null || this.#countsDirty;
+	}
+	/**
+	* Une connexion entre.
+	*
+	* @param key - identité nommée, ou `null` pour une connexion non nommée.
+	*/
+	join(key) {
+		const local = this.#local;
+		if (key === null) {
+			this.#unnamed += 1;
+			this.#countsDirty = true;
+			if (local !== null) this.#addLocalUnnamed(1);
+			return;
+		}
+		if (this.#leaving?.delete(key) === true) return;
+		const named = this.#named;
+		const before = named.get(key) ?? 0;
+		const total = before - this.#cancelRemoteDeparture(key) + 1;
+		named.set(key, total);
+		if (total !== before) this.#markDirty(key);
+		if (local !== null) this.#setLocal(local, key, (local.get(key) ?? 0) + 1);
+	}
+	/**
+	* Une connexion sort.
+	*
+	* Un départ nommé attend la grâce du canal ; un départ non nommé est décompté
+	* tout de suite (rien ne reconnaîtrait son retour).
+	*
+	* @param key - même valeur qu'à {@link ChannelPresence.join}.
+	* @param now - instant monotone (ms), pour la grâce.
+	*/
+	leave(key, now) {
+		const local = this.#local;
+		if (key === null) {
+			this.#unnamed -= 1;
+			this.#countsDirty = true;
+			if (local !== null) this.#addLocalUnnamed(-1);
+			return;
+		}
+		const grace = this.settings.grace;
+		const tabs = this.#named.get(key);
+		if (tabs === void 0) return;
+		if (tabs > 1) {
+			this.#named.set(key, tabs - 1);
+			this.#markDirty(key);
+			if (local !== null) {
+				const mine = local.get(key) ?? 0;
+				if (mine > 0) this.#setLocal(local, key, mine - 1);
+			}
+			return;
+		}
+		if (grace > 0) {
+			(this.#leaving ??= /* @__PURE__ */ new Map()).set(key, now + grace);
+			return;
+		}
+		this.#named.delete(key);
+		this.#markDirty(key);
+		if (local !== null) this.#setLocal(local, key, 0);
+	}
+	/** Publie les départs dont la grâce est écoulée. */
+	expire(now) {
+		const leaving = this.#leaving;
+		const local = this.#local;
+		if (this.#remoteLeaving !== null) this.#expireRemote(now);
+		if (leaving === null) return;
+		for (const [key, deadline] of leaving) {
+			if (deadline > now) break;
+			leaving.delete(key);
+			this.#named.delete(key);
+			this.#markDirty(key);
+			if (local !== null) this.#setLocal(local, key, 0);
+		}
+		if (leaving.size === 0) this.#leaving = null;
+	}
+	/** Prochaine échéance de grâce (ms monotone), `Infinity` sans départ retenu — O(1). */
+	nextDeadline() {
+		let next = Number.POSITIVE_INFINITY;
+		if (this.#leaving !== null) for (const deadline of this.#leaving.values()) {
+			next = deadline;
+			break;
+		}
+		if (this.#remoteLeaving !== null) for (const departure of this.#remoteLeaving.values()) {
+			if (departure.deadline < next) next = departure.deadline;
+			break;
+		}
+		return next;
+	}
+	/**
+	* Trame complète à la version COURANTE — la liste, ou les nombres seuls au-delà du seuil.
+	*
+	* Une liste ne prend jamais de numéro : servie à un nouvel abonné, elle ferait
+	* voir un trou à tous les autres (ADR-0025 P2 bis).
+	*/
+	listParams() {
+		const named = this.#named;
+		const count = named.size;
+		const channel = this.channel;
+		const version = this.#version;
+		const unnamed = this.#unnamed;
+		if (!this.#wantsNamed(count)) return this.#partial ? {
+			channel,
+			version,
+			count,
+			unnamed,
+			partial: true
+		} : {
+			channel,
+			version,
+			count,
+			unnamed
+		};
+		const members = pairsOf(named);
+		return this.#partial ? {
+			channel,
+			version,
+			count,
+			unnamed,
+			members,
+			partial: true
+		} : {
+			channel,
+			version,
+			count,
+			unnamed,
+			members
+		};
+	}
+	/**
+	* Consomme les changements en attente et rend la trame à envoyer à tous les membres, ou `null` s'il n'y en a pas.
+	*
+	* Sous le seuil : les changements, version +1. Au-delà : les nombres seuls,
+	* version inchangée (trame complète). Au retour sous le seuil : la liste.
+	* Toute trame envoyée périme la liste encodée.
+	*/
+	takeChanges() {
+		if (!this.dirty) return null;
+		const dirty = this.#dirty;
+		this.#dirty = null;
+		this.#countsDirty = false;
+		this.listFrame = null;
+		const named = this.#wantsNamed(this.#named.size);
+		if (!named || !this.#namedSent) {
+			this.#namedSent = named;
+			return this.listParams();
+		}
+		this.#version += 1;
+		let set = null;
+		let gone = null;
+		if (dirty !== null) for (const key of dirty) {
+			const tabs = this.#named.get(key);
+			if (tabs === void 0) (gone ??= []).push(key);
+			else (set ??= []).push(key, tabs);
+		}
+		const changes = set === null ? gone === null ? {} : { gone } : gone === null ? { set } : {
+			set,
+			gone
+		};
+		const channel = this.channel;
+		const version = this.#version;
+		const count = this.#named.size;
+		const unnamed = this.#unnamed;
+		return this.#partial ? {
+			channel,
+			version,
+			count,
+			unnamed,
+			changes,
+			partial: true
+		} : {
+			channel,
+			version,
+			count,
+			unnamed,
+			changes
+		};
+	}
+	/** Vue de l'observateur serveur : les membres toujours, une copie. */
+	view() {
+		const members = /* @__PURE__ */ new Map();
+		for (const [key, tabs] of this.#named) members.set(key, { tabs });
+		return {
+			count: this.#named.size,
+			unnamed: this.#unnamed,
+			members,
+			partial: this.#partial
+		};
+	}
+	/**
+	* Pose l'état « incomplet » de la vue ; un changement fait partir une trame (la version suit) et périme la liste encodée.
+	*/
+	setPartial(partial) {
+		if (partial === this.#partial) return;
+		this.#partial = partial;
+		this.#countsDirty = true;
+		this.listFrame = null;
+	}
+	/** {@inheritDoc IPresenceAggregate.remoteTabs} */
+	remoteTabs(key, delta) {
+		const named = this.#named;
+		const before = named.get(key) ?? 0;
+		let total = before;
+		if (delta > 0) {
+			if (this.#leaving?.delete(key) === true) {
+				total -= 1;
+				const local = this.#local;
+				if (local !== null) this.#setLocal(local, key, 0);
+			} else total -= this.#cancelRemoteDeparture(key);
+		}
+		total += delta;
+		if (total > 0) named.set(key, total);
+		else named.delete(key);
+		if (total !== before) this.#markDirty(key);
+	}
+	/** {@inheritDoc IPresenceAggregate.remoteUnnamed} */
+	remoteUnnamed(delta) {
+		this.#unnamed += delta;
+		this.#countsDirty = true;
+	}
+	/** {@inheritDoc IPresenceAggregate.remoteLeave} */
+	remoteLeave(key, tabs, now) {
+		const grace = this.settings.grace;
+		if (grace === 0 || (this.#named.get(key) ?? 0) > tabs) {
+			this.remoteTabs(key, -tabs);
+			return;
+		}
+		const leaving = this.#remoteLeaving ??= /* @__PURE__ */ new Map();
+		const pending = leaving.get(key);
+		if (pending !== void 0) pending.tabs += tabs;
+		else leaving.set(key, new RemoteDeparture(now + grace, tabs));
+	}
+	/**
+	* Consomme les changements de la part locale depuis le dernier lot et rend l'entrée du lot, en valeurs absolues — `null` s'ils s'annulent tous.
+	*/
+	takeBusDelta() {
+		const local = this.#local;
+		const before = this.#busBefore;
+		const unnamedBefore = this.#busUnnamedBefore;
+		this.#busBefore = null;
+		this.#busUnnamedBefore = -1;
+		if (local === null) return null;
+		let set = null;
+		let gone = null;
+		if (before !== null) for (const [key, was] of before) {
+			const tabs = local.get(key) ?? 0;
+			if (tabs === was) continue;
+			if (tabs === 0) (gone ??= []).push(key);
+			else (set ??= []).push(key, tabs);
+		}
+		const unnamed = this.#localUnnamed;
+		if (set === null && gone === null && (unnamedBefore < 0 || unnamedBefore === unnamed)) return null;
+		return {
+			channel: this.channel,
+			set,
+			gone,
+			unnamed
+		};
+	}
+	/** État COMPLET de la part locale, pour une réponse d'état (paires à plat). */
+	localState() {
+		const local = this.#local;
+		return {
+			channel: this.channel,
+			members: local === null ? [] : pairsOf(local),
+			unnamed: this.#localUnnamed
+		};
+	}
+	/**
+	* Des départs LOCAUX attendent-ils la fin de leur grâce ? Le dernier client
+	* parti d'un pod n'y échappe pas : la présence reste servie au bus jusqu'à
+	* l'échéance (ADR-0025 P5), puis se libère.
+	*/
+	get hasLocalGrace() {
+		return this.#leaving !== null;
+	}
+	/** La part locale compte-t-elle quelqu'un ? */
+	get hasLocal() {
+		return (this.#local?.size ?? 0) > 0 || this.#localUnnamed > 0;
+	}
+	/**
+	* Le canal n'est plus servi ici : toute la part locale part à zéro au prochain lot, pour que les pairs ne gardent aucun fantôme.
+	*/
+	release() {
+		const local = this.#local;
+		if (local === null) return;
+		for (const key of local.keys()) this.#setLocal(local, key, 0);
+		this.#leaving = null;
+		if (this.#localUnnamed !== 0) this.#addLocalUnnamed(-this.#localUnnamed);
+		this.#remoteLeaving = null;
+	}
+	/** Annule le départ en grâce d'un pair pour `key` ; rend les onglets qu'il retenait (`0` sans départ). */
+	#cancelRemoteDeparture(key) {
+		const leaving = this.#remoteLeaving;
+		if (leaving === null) return 0;
+		const departure = leaving.get(key);
+		if (departure === void 0) return 0;
+		leaving.delete(key);
+		if (leaving.size === 0) this.#remoteLeaving = null;
+		return departure.tabs;
+	}
+	/** Départs de pairs dont la grâce est écoulée — échéances croissantes, arrêt à la première non échue. */
+	#expireRemote(now) {
+		const leaving = this.#remoteLeaving;
+		if (leaving === null) return;
+		const named = this.#named;
+		for (const [key, departure] of leaving) {
+			if (departure.deadline > now) break;
+			leaving.delete(key);
+			const total = (named.get(key) ?? 0) - departure.tabs;
+			if (total > 0) named.set(key, total);
+			else named.delete(key);
+			this.#markDirty(key);
+		}
+		if (leaving.size === 0) this.#remoteLeaving = null;
+	}
+	/**
+	* La trame complète doit-elle nommer `count` présents ? Nommée : tant qu'on ne
+	* dépasse pas `maxNamed`. En nombres seuls : seulement revenu au seuil de retour.
+	*/
+	#wantsNamed(count) {
+		return count <= (this.#namedSent ? this.settings.maxNamed : this.#resumeNamed);
+	}
+	#markDirty(key) {
+		(this.#dirty ??= /* @__PURE__ */ new Set()).add(key);
+	}
+	/** Pose les onglets LOCAUX d'une identité, en retenant la valeur du dernier lot. */
+	#setLocal(local, key, tabs) {
+		const before = local.get(key) ?? 0;
+		if (tabs === before) return;
+		const pending = this.#busBefore ??= /* @__PURE__ */ new Map();
+		if (!pending.has(key)) pending.set(key, before);
+		if (tabs === 0) local.delete(key);
+		else local.set(key, tabs);
+	}
+	#addLocalUnnamed(delta) {
+		if (this.#busUnnamedBefore < 0) this.#busUnnamedBefore = this.#localUnnamed;
+		this.#localUnnamed += delta;
+	}
+};
+/** Paires à plat `[identité, onglets, …]` d'une table — tableau pré-dimensionné, rempli en place. */
+function pairsOf(table) {
+	const pairs = new Array(table.size * 2);
+	let i = 0;
+	for (const [key, tabs] of table) {
+		pairs[i++] = key;
+		pairs[i++] = tabs;
+	}
+	return pairs;
+}
+export { ChannelPresence, DEFAULT_PRESENCE_MAX_NAMED, PRESENCE_WINDOW_MS, presenceDefect, presenceSettingsOf, samePresence };