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

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

@@ -0,0 +1,486 @@
+import { MAX_PRESENCE_CHANNELS, isUnknownPresenceMessage, readPresenceAlive, readPresenceMessage } from "../backplane/presenceMessage.js";
+import { RemotePresence } from "./remotePresence.js";
+import { PLATFORM_BUS_CHANNELS } from "nodefony";
+import { Buffer } from "node:buffer";
+// nodefony/src/server/presenceBus.ts
+/** Fenêtre des lots, demandes et réponses entre pods (ms) — ADR-0025 P2. */
+const PRESENCE_BATCH_MS = 50;
+/** Intervalle local de la preuve de vie (ms), annoncé aux pairs — ADR-0025 P2, « Oubli ». */
+const PRESENCE_INTERVAL_MS = 5e3;
+/** Délai d'oubli d'un pair muet, en intervalles ANNONCÉS (≥ 2) — ADR-0025 P2. */
+const PRESENCE_FORGET_FACTOR = 3;
+/** Octets UTF-8 au plus par message (estimés à l'encodage JSON), sous les 64 Ko de l'ADR. */
+const PRESENCE_MESSAGE_BYTES = 6e4;
+/** Coût fixe estimé d'une entrée de canal (clés, ponctuation, `unnamed`). */
+const ENTRY_BYTES = 48;
+const EMPTY_PAIRS = Object.freeze([]);
+/** Coût estimé d'une paire `[identité, onglets]` sur le fil. */
+function pairBytes(key) {
+	return (typeof key === "string" ? Buffer.byteLength(key, "utf8") : 0) + 10;
+}
+/**
+* Découpe des entrées de canal en parts d'au plus {@link PRESENCE_MESSAGE_BYTES} octets estimés et {@link MAX_PRESENCE_CHANNELS} entrées ; une entrée trop grosse s'étend sur plusieurs parts (ses paires s'additionnent, valeurs absolues).
+*
+* @param pairsOf - les paires d'une entrée ; `rebuild` en fait une entrée
+*   réduite à une tranche de ces paires (`last` : la dernière tranche, qui
+*   garde ce qui n'est pas découpé).
+*/
+function split(entries, pairsOf, rebuild) {
+	const parts = [];
+	let part = [];
+	let size = 0;
+	for (const entry of entries) {
+		const head = Buffer.byteLength(entry.channel, "utf8") + ENTRY_BYTES;
+		if (part.length >= 4096 || part.length > 0 && size + head > PRESENCE_MESSAGE_BYTES) {
+			parts.push(part);
+			part = [];
+			size = 0;
+		}
+		const pairs = pairsOf(entry);
+		let from = 0;
+		let cost = head;
+		for (let i = 0; i < pairs.length; i += 2) {
+			const bytes = pairBytes(pairs[i]);
+			if (size + cost + bytes > PRESENCE_MESSAGE_BYTES && i > from) {
+				part.push(rebuild(entry, pairs.slice(from, i), false));
+				parts.push(part);
+				part = [];
+				size = 0;
+				from = i;
+				cost = head;
+			}
+			cost += bytes;
+		}
+		part.push(from === 0 ? entry : rebuild(entry, pairs.slice(from), true));
+		size += cost;
+	}
+	if (part.length > 0 || parts.length === 0) parts.push(part);
+	return parts;
+}
+/**
+* Présence répartie d'UN pod (ADR-0025 P2) — ce qu'il émet sur le bus (lots de 50 ms, demandes d'état, réponses, preuve de vie) et ce qu'il en reçoit (vue des pairs, {@link RemotePresence}).
+*
+* Sans minuteur ni horloge : le hub la fait avancer à son tic UNIQUE
+* ({@link PresenceBus.tick}) et arme ce tic sur {@link PresenceBus.due}, O(1).
+* Elle ne parle qu'à `IBackplane` par son hôte : un pilote neuf (Kafka,
+* NATS…) n'écrit rien pour la présence.
+*
+* Coût : rien n'existe tant qu'aucun canal à présence n'est diffusé ; un
+* changement local = un ajout dans un `Set` ; un lot = un parcours des seuls
+* canaux changés.
+*/
+var PresenceBus = class {
+	/** Vue des pairs. */
+	remote;
+	/** Vie de ce processus : `Date.now() × 1024 + aléa sur 10 bits` (entier sûr jusqu'en 2248). */
+	incarnation;
+	#host;
+	#interval;
+	#random;
+	#seq = 0;
+	#lastBatch = 0;
+	#dirty = null;
+	#ask = null;
+	#answer = null;
+	#answerDue = false;
+	#touched = null;
+	#syncing = null;
+	#syncHead = 0;
+	#gapped = false;
+	#gapTotalSeen = 0;
+	#batchAt = Number.POSITIVE_INFINITY;
+	#requestAt = Number.POSITIVE_INFINITY;
+	#aliveAt = Number.POSITIVE_INFINITY;
+	#expireAt = Number.POSITIVE_INFINITY;
+	#batchTotal = 0;
+	#requestTotal = 0;
+	#answerTotal = 0;
+	#aliveTotal = 0;
+	#echoSeen = -1;
+	#echoExpected = false;
+	#busLost = false;
+	#busLostTotal = 0;
+	#rearmTotal = 0;
+	#ended = false;
+	/**
+	* @throws RangeError si le délai d'oubli est sous 2 intervalles (cf `RemotePresence`).
+	*/
+	constructor(host, options = {}) {
+		this.#host = host;
+		this.#interval = options.interval ?? 5e3;
+		this.#random = options.random ?? Math.random;
+		const wall = options.wallClock ?? Date.now;
+		this.incarnation = Math.floor(wall()) * 1024 + Math.floor(this.#random() * 1024);
+		this.remote = new RemotePresence({
+			lookup: (channel) => {
+				const presence = host.lookup(channel);
+				if (presence !== null && presence !== false) this.#touch(presence);
+				return presence;
+			},
+			factor: options.factor ?? 3,
+			interval: this.#interval
+		});
+	}
+	/** Prochain instant (ms monotone) où le bus a quelque chose à faire — O(1). */
+	due() {
+		let next = this.#batchAt;
+		if (this.#requestAt < next) next = this.#requestAt;
+		if (this.#aliveAt < next) next = this.#aliveAt;
+		if (this.#expireAt < next) next = this.#expireAt;
+		const syncing = this.#syncing;
+		if (syncing !== null) {
+			const head = syncing[this.#syncHead];
+			if (head !== void 0 && head.syncUntil < next) next = head.syncUntil;
+		}
+		return next;
+	}
+	/**
+	* Présences à rafraîchir depuis le dernier appel (agrégat changé, état incomplet changé) — `null` si aucune ; le hub les touche.
+	*/
+	takeTouched() {
+		const touched = this.#touched;
+		this.#touched = null;
+		return touched;
+	}
+	/**
+	* Un canal à présence diffusé vient d'être servi (premier abonné local) : la vue reste incomplète le temps que la demande d'état groupée soit servie.
+	*/
+	served(presence, now) {
+		if (this.#ended) return;
+		(this.#ask ??= /* @__PURE__ */ new Set()).add(presence.channel);
+		presence.syncUntil = now + 150;
+		presence.setPartial(true);
+		(this.#syncing ??= []).push(presence);
+		this.#armBatch(now);
+		this.#activate(now);
+	}
+	/** La part locale d'une présence a changé : elle part au prochain lot. */
+	changed(presence, now) {
+		if (this.#ended) return;
+		(this.#dirty ??= /* @__PURE__ */ new Set()).add(presence);
+		this.#armBatch(now);
+		this.#activate(now);
+	}
+	/**
+	* Applique un message du canal des lots, demandes et réponses.
+	*
+	* @returns `true` si c'est un type de message inconnu de cette version (le
+	*   hub le compte dans `ingressUnknownDiscardedTotal`) ; `false` sinon — y
+	*   compris refusé, compté ici (`presenceRejectedTotal`).
+	*/
+	receive(origin, payload, now) {
+		if (this.#ended) return false;
+		const message = readPresenceMessage(payload);
+		if (message === null) {
+			if (isUnknownPresenceMessage(payload)) return true;
+			this.remote.countRejected();
+			return false;
+		}
+		const request = this.remote.receive(origin, message, now);
+		if (request !== null) this.#queueAnswer(request, now);
+		this.#afterReceive(now);
+		return false;
+	}
+	/** Applique une preuve de vie ; une forme fausse est refusée et comptée. */
+	receiveAlive(origin, payload, now) {
+		if (this.#ended) return;
+		const alive = readPresenceAlive(payload);
+		if (alive === null) {
+			this.remote.countRejected();
+			return;
+		}
+		this.remote.receiveAlive(origin, alive, now);
+		this.#afterReceive(now);
+	}
+	/** Fait avancer la présence répartie à l'instant `now` (tic unique du hub). */
+	tick(now) {
+		if (this.#ended) return;
+		const remote = this.remote;
+		if (now - this.due() > this.#interval) this.#rearm(now);
+		if (now >= this.#batchAt) {
+			this.#batchAt = Number.POSITIVE_INFINITY;
+			this.#flushBatch();
+			this.#flushAsk();
+			this.#flushAnswers();
+		}
+		const alive = now >= this.#aliveAt;
+		if (alive) this.#checkEcho(now);
+		if (now >= this.#expireAt && !this.#busLost) remote.expire(now);
+		if (now >= this.#requestAt) {
+			this.#requestAt = Number.POSITIVE_INFINITY;
+			this.#sendRequests(now);
+		}
+		if (alive) {
+			this.#sendAlive(false);
+			this.#aliveAt = this.#active() ? now + this.#interval : Number.POSITIVE_INFINITY;
+		}
+		const syncing = this.#syncing;
+		if (syncing !== null) {
+			let head = this.#syncHead;
+			while (head < syncing.length) {
+				const presence = syncing[head];
+				if (presence === void 0 || presence.syncUntil > now) break;
+				presence.syncUntil = 0;
+				if (presence.live) {
+					presence.setPartial(this.#incomplete());
+					this.#touch(presence);
+				}
+				head += 1;
+			}
+			if (head === syncing.length) {
+				this.#syncing = null;
+				this.#syncHead = 0;
+			} else this.#syncHead = head;
+		}
+		this.#expireAt = remote.size > 0 && !this.#busLost ? remote.nextDeadline() : Number.POSITIVE_INFINITY;
+		this.#refreshGaps(now);
+	}
+	/**
+	* Arrêt propre (ADR-0025 P5) : le dernier lot part, puis une preuve de vie FINALE — les pairs retirent aussitôt les présents de ce pod, sans attendre le délai d'oubli. Plus rien ne part ensuite ; idempotent.
+	*
+	* Rien n'est émis si ce pod ne s'est jamais annoncé (aucune preuve de vie
+	* émise ni vue des pairs) : personne n'a rien à retirer.
+	*/
+	end() {
+		if (this.#ended) return;
+		if (this.#aliveTotal > 0 || this.#active()) {
+			this.#flushBatch();
+			this.#sendAlive(true);
+		}
+		this.#ended = true;
+		this.#batchAt = Number.POSITIVE_INFINITY;
+		this.#requestAt = Number.POSITIVE_INFINITY;
+		this.#aliveAt = Number.POSITIVE_INFINITY;
+		this.#expireAt = Number.POSITIVE_INFINITY;
+		this.#dirty = null;
+		this.#ask = null;
+		this.#answer = null;
+		this.#syncing = null;
+		this.#touched = null;
+	}
+	/** Arrêt propre émis ? */
+	get ended() {
+		return this.#ended;
+	}
+	/** Bus perdu, constaté par l'écho : la vue est figée et `partial` (instantané). */
+	get busLost() {
+		return this.#busLost;
+	}
+	/** Pertes du bus constatées par l'écho. */
+	get busLostTotal() {
+		return this.#busLostTotal;
+	}
+	/** Réarmements du délai d'oubli (tic en retard, retour de l'écho). */
+	get rearmTotal() {
+		return this.#rearmTotal;
+	}
+	/** Compteurs de la sonde. */
+	get batchTotal() {
+		return this.#batchTotal;
+	}
+	/** Demandes d'état émises (ciblées et non ciblées). */
+	get requestTotal() {
+		return this.#requestTotal;
+	}
+	/** Parts de réponse d'état émises. */
+	get answerTotal() {
+		return this.#answerTotal;
+	}
+	/** Preuves de vie émises. */
+	get aliveTotal() {
+		return this.#aliveTotal;
+	}
+	#touch(presence) {
+		(this.#touched ??= /* @__PURE__ */ new Set()).add(presence);
+	}
+	#armBatch(now) {
+		if (this.#batchAt === Number.POSITIVE_INFINITY) this.#batchAt = now + 50;
+	}
+	/** Bat-il ? Dès qu'il sert un canal à présence diffusé OU garde une vue des pairs. */
+	#active() {
+		return this.#host.servedCount() > 0 || this.remote.size > 0;
+	}
+	/** Arme le premier battement, avec une gigue de 0 à 25 % de l'intervalle. */
+	#activate(now) {
+		if (this.#aliveAt === Number.POSITIVE_INFINITY && this.#active()) this.#aliveAt = now + this.#interval * .25 * this.#random();
+	}
+	#afterReceive(now) {
+		const remote = this.remote;
+		if (remote.gapTotal !== this.#gapTotalSeen) {
+			this.#gapTotalSeen = remote.gapTotal;
+			const at = now + 50;
+			if (at < this.#requestAt) this.#requestAt = at;
+		}
+		const closer = remote.takeCloserDeadline();
+		if (closer < this.#expireAt && !this.#busLost) this.#expireAt = closer;
+		this.#activate(now);
+		this.#refreshGaps(now);
+	}
+	/** La vue des pairs est-elle incomplète (trou chez un pair) ou figée (bus perdu) ? */
+	#incomplete() {
+		return this.remote.gaps > 0 || this.#busLost;
+	}
+	/**
+	* Un trou s'ouvre ou se ferme chez un pair, le bus se perd ou revient : la vue des canaux servis change d'état.
+	*/
+	#refreshGaps(now) {
+		if (this.remote.gaps > 0 && this.#requestAt === Number.POSITIVE_INFINITY) this.#requestAt = now + this.#interval;
+		const incomplete = this.#incomplete();
+		if (incomplete === this.#gapped) return;
+		this.#gapped = incomplete;
+		for (const presence of this.#host.servedPresences()) {
+			if (presence.syncUntil !== 0) continue;
+			presence.setPartial(incomplete);
+			this.#touch(presence);
+		}
+	}
+	/**
+	* Relève l'écho au tic de la preuve de vie : une preuve de vie partie au relevé précédent et aucun écho depuis = bus perdu ; l'écho qui revient réarme le délai d'oubli de tous les pairs.
+	*/
+	#checkEcho(now) {
+		const total = this.#host.echoTotal();
+		if (total === void 0) return;
+		if (total !== this.#echoSeen) {
+			if (this.#busLost) {
+				this.#busLost = false;
+				this.#rearm(now);
+			}
+		} else if (this.#echoExpected && !this.#busLost) {
+			this.#busLost = true;
+			this.#busLostTotal += 1;
+		}
+		this.#echoSeen = total;
+		this.#echoExpected = true;
+	}
+	#rearm(now) {
+		if (this.remote.size === 0) return;
+		this.remote.rearm(now);
+		this.#rearmTotal += 1;
+	}
+	#queueAnswer(request, now) {
+		const targeted = request.to !== null;
+		if (targeted && request.to !== this.#host.originId) return;
+		const answer = this.#answer ??= /* @__PURE__ */ new Map();
+		for (const channel of request.channels) if (targeted || answer.get(channel) !== true) answer.set(channel, targeted);
+		if (targeted) this.#answerDue = true;
+		this.#armBatch(now);
+	}
+	#flushBatch() {
+		const dirty = this.#dirty;
+		if (dirty === null) return;
+		this.#dirty = null;
+		let entries = null;
+		for (const presence of dirty) {
+			const entry = presence.takeBusDelta();
+			if (entry !== null) (entries ??= []).push(entry);
+		}
+		if (entries === null) return;
+		const parts = split(entries, (entry) => entry.set ?? EMPTY_PAIRS, (entry, set, last) => last ? {
+			...entry,
+			set
+		} : {
+			...entry,
+			set,
+			gone: null
+		});
+		for (const channels of parts) {
+			const seq = ++this.#seq;
+			this.#host.publish(PLATFORM_BUS_CHANNELS.presence, {
+				op: "batch",
+				incarnation: this.incarnation,
+				seq,
+				prev: this.#lastBatch,
+				channels
+			});
+			this.#lastBatch = seq;
+			this.#batchTotal += 1;
+		}
+	}
+	#flushAsk() {
+		const ask = this.#ask;
+		if (ask === null) return;
+		this.#ask = null;
+		this.#request([...ask], null);
+	}
+	#sendRequests(now) {
+		const remote = this.remote;
+		if (remote.gaps === 0) return;
+		const channels = [];
+		for (const presence of this.#host.servedPresences()) channels.push(presence.channel);
+		const targets = remote.takeRequests(now, channels);
+		if (targets !== null) for (const to of targets) this.#request(channels, to);
+		if (remote.gaps > 0) this.#requestAt = now + this.#interval;
+	}
+	/** Publie une demande, découpée par {@link MAX_PRESENCE_CHANNELS} canaux. */
+	#request(channels, to) {
+		for (let from = 0; from < channels.length || from === 0;) {
+			const slice = channels.length <= 4096 ? channels : channels.slice(from, from + MAX_PRESENCE_CHANNELS);
+			this.#host.publish(PLATFORM_BUS_CHANNELS.presence, {
+				op: "request",
+				incarnation: this.incarnation,
+				seq: ++this.#seq,
+				channels: slice,
+				to
+			});
+			this.#requestTotal += 1;
+			from += MAX_PRESENCE_CHANNELS;
+		}
+	}
+	#flushAnswers() {
+		const answer = this.#answer;
+		if (answer === null) return;
+		const due = this.#answerDue;
+		this.#answer = null;
+		this.#answerDue = false;
+		const entries = [];
+		for (const [channel, named] of answer) {
+			const presence = this.#host.served(channel);
+			if (presence?.hasLocal === true) entries.push(presence.localState());
+			else if (named) entries.push({
+				channel,
+				members: EMPTY_PAIRS,
+				unnamed: 0
+			});
+		}
+		if (entries.length === 0 && !due) return;
+		const parts = split(entries, (entry) => entry.members, (entry, members) => ({
+			channel: entry.channel,
+			members,
+			unnamed: entry.unnamed
+		}));
+		const n = parts.length;
+		const last = this.#lastBatch;
+		for (let i = 0; i < n; i += 1) {
+			this.#host.publish(PLATFORM_BUS_CHANNELS.presence, {
+				op: "state",
+				incarnation: this.incarnation,
+				seq: ++this.#seq,
+				last,
+				i,
+				n,
+				channels: parts[i]
+			});
+			this.#answerTotal += 1;
+		}
+	}
+	#sendAlive(final) {
+		const incarnation = this.incarnation;
+		const seq = ++this.#seq;
+		const last = this.#lastBatch;
+		const interval = this.#interval;
+		this.#host.publish(PLATFORM_BUS_CHANNELS.presenceAlive, final ? {
+			incarnation,
+			seq,
+			last,
+			interval,
+			final: true
+		} : {
+			incarnation,
+			seq,
+			last,
+			interval
+		});
+		this.#aliveTotal += 1;
+	}
+};
+export { PRESENCE_BATCH_MS, PRESENCE_FORGET_FACTOR, PRESENCE_INTERVAL_MS, PresenceBus };

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

@@ -0,0 +1,31 @@
+import { withTimeout } from "nodefony";
+// nodefony/src/server/realtimeShutdown.ts
+/**
+* Délai laissé au bus pour faire partir ce qui est déjà émis à l'arrêt (ms) — sous la limite d'arrêt du noyau (15 s) et sous le délai de grâce d'un orchestrateur.
+*/
+const BACKPLANE_STOP_TIMEOUT_MS = 2e3;
+/**
+* Arrêt propre du temps réel d'un processus — la présence répartie annonce sa fin (dernier lot, puis preuve de vie FINALE, ADR-0025 P5), puis le bus POSSÉDÉ s'arrête en laissant partir ce qui est émis, dans une limite de temps.
+*
+* Sans l'attente du bus, la sortie du processus au tick suivant perdait la
+* preuve de vie finale sur un bus réseau (Redis) : les pairs gardaient ce
+* serveur jusqu'au délai d'oubli. Un bus fourni par l'application (`owned`
+* `null`) n'est pas arrêté ici : c'est à elle de le faire.
+*
+* @param hub - le hub du processus.
+* @param owned - le bus que l'appelant a créé et doit arrêter, `null` sinon.
+* @param timeoutMs - limite de l'arrêt du bus.
+* @returns `false` si le bus n'a pas fini dans la limite (ou a échoué) — ce
+*   qui restait peut être perdu, les pairs oublieront ce serveur au délai.
+*/
+async function shutdownRealtime(hub, owned, timeoutMs = BACKPLANE_STOP_TIMEOUT_MS) {
+	hub.endPresence();
+	if (owned === null) return true;
+	try {
+		await withTimeout(Promise.resolve(owned.stop()), timeoutMs, "realtime backplane stop");
+		return true;
+	} catch {
+		return false;
+	}
+}
+export { BACKPLANE_STOP_TIMEOUT_MS, shutdownRealtime };