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

package/dist/nodefony/src/backplane/RedisBackplane.js

@@ -1,7 +1,9 @@
-import { isCallable, isRecord, isThenable } from "../guards.js";
 import resolveBackplaneOriginId from "./originId.js";
-import { openBackplaneEnvelope, sealBackplaneEnvelope } from "./envelope.js";
+import { isCallable, isRecord, isThenable } from "../guards.js";
+import { sealBackplaneEnvelope, sealBackplaneEnvelopeBytes } from "./envelope.js";
+import { BackplaneIngress } from "./ingress.js";
 import { BackplanePublishQueue } from "./publishQueue.js";
+import { containsBytes } from "nodefony";
 // nodefony/src/backplane/RedisBackplane.ts
 /**
 * BASE du canal Redis **dédié** transportant les enveloppes realtime entre pods.
@@ -28,22 +30,18 @@ function resolveRedisChannel(namespace) {
 	return namespace ? `${REDIS_RT_CHANNEL}:${namespace}` : REDIS_RT_CHANNEL;
 }
 /**
-* Adapte deux clients Redis (publisher + subscriber dédié) au seam
-* {@link IRedisBackplaneTransport}. SEUL point de contact avec la lib `redis` —
-* et même ici le couplage est **structurel** (aucun import). Le consommateur
-* branche typiquement les connexions du module `@nodefony/redis` :
+* Construit le **sujet binaire** du bus (ADR-0021 S6) : le canal texte suffixé du
+* protocole du codec. Un second sujet, versionné par son nom, que les exemplaires
+* plus anciens n'écoutent pas — le message texte n'est pas touché, et un codec
+* binaire d'un autre format aurait son propre sujet.
 *
-* ```ts
-* const redis = kernel.get("redis"); // RedisService
-* const bp = new RedisBackplane(
-*   createRedisServiceTransport(redis.getClient("publish")!, redis.getClient("subscribe")!),
-* );
-* defineRealtimeConfig({ backplane: { driver: "redis" } }, { backplane: bp });
-* ```
-*
-* Le listener Redis est conservé pour un `unsubscribe(channel, listener)` ciblé
-* (n'arrache pas d'éventuels autres abonnés du même client).
+* @param redisChannel - le canal texte effectif ({@link resolveRedisChannel}).
+* @param codec - le codec binaire du serveur.
+* @returns le nom du canal Redis qui porte les enveloppes binaires.
 */
+function resolveRedisBytesChannel(redisChannel, codec) {
+	return `${redisChannel}:${codec.protocol}`;
+}
 /**
 * Vrai si la valeur expose la surface d'un client Redis publisher — vérifié au
 * démarrage, sur le client que rend le service `redis`.
@@ -55,27 +53,77 @@ function isRedisPublisher(value) {
 function isRedisSubscriber(value) {
 	return isRecord(value) && isCallable(value.subscribe) && isCallable(value.unsubscribe);
 }
+/**
+* Vrai si la valeur expose la surface d'un client abonné capable du mode octets.
+*
+* La forme ne dit pas si le troisième argument est compris : ce garde vaut pour
+* le client que rend le service `redis` (node-redis, qui l'accepte). Un client qui
+* l'ignorerait livrerait du texte au sujet binaire — illisible pour le codec,
+* donc jeté, compté sous un secret (`sealRejectedTotal`), jamais réinjecté.
+*/
+function isRedisBytesSubscriber(value) {
+	return isRedisSubscriber(value);
+}
 /** Ramène l'acquittement d'une commande Redis au contrat du transport. */
 function settled(ack) {
 	return isThenable(ack) ? ack.then(() => void 0) : void 0;
 }
-function createRedisServiceTransport(publisher, subscriber) {
-	let listener = null;
-	return {
+/**
+* Adapte deux clients Redis (publisher + subscriber dédié) au seam
+* {@link IRedisBackplaneTransport}. SEUL point de contact avec la lib `redis` —
+* et même ici le couplage est **structurel** (aucun import). Le consommateur
+* branche typiquement les connexions du module `@nodefony/redis` :
+*
+* ```ts
+* const redis = kernel.get("redis"); // RedisService
+* const bp = new RedisBackplane(
+*   createRedisServiceTransport(redis.getClient("publish")!, redis.getClient("subscribe")!),
+* );
+* defineRealtimeConfig({ backplane: { driver: "redis" } }, { backplane: bp });
+* ```
+*
+* Chaque listener Redis est conservé, par canal, pour un `unsubscribe(channel,
+* listener)` ciblé (n'arrache pas d'éventuels autres abonnés du même client).
+*
+* @param publisher - connexion de publication.
+* @param subscriber - connexion d'abonnement dédiée.
+* @param bytesSubscriber - la MÊME connexion d'abonnement, vue en mode octets
+*   ({@link IRedisBytesSubscriber}) ; absente, le transport n'offre pas de sujet
+*   binaire et les octets restent sur le serveur qui les publie.
+* @returns le transport du {@link RedisBackplane}.
+*/
+function createRedisServiceTransport(publisher, subscriber, bytesSubscriber) {
+	const listeners = /* @__PURE__ */ new Map();
+	const transport = {
 		publish(channel, message) {
-			const ack = publisher.publish(channel, message);
+			const ack = publisher.publish(channel, typeof message === "string" ? message : Buffer.from(message.buffer, message.byteOffset, message.byteLength));
 			return isThenable(ack) ? ack : void 0;
 		},
 		subscribe(channel, onMessage) {
-			listener = (message) => onMessage(message);
-			return settled(subscriber.subscribe(channel, listener));
+			const fn = (message) => onMessage(message);
+			listeners.set(channel, {
+				bytes: false,
+				fn
+			});
+			return settled(subscriber.subscribe(channel, fn));
 		},
 		unsubscribe(channel) {
-			const current = listener;
-			listener = null;
-			return settled(current ? subscriber.unsubscribe(channel, current) : subscriber.unsubscribe(channel));
+			const current = listeners.get(channel);
+			listeners.delete(channel);
+			if (current === void 0) return settled(subscriber.unsubscribe(channel));
+			if (!current.bytes) return settled(subscriber.unsubscribe(channel, current.fn));
+			return settled(bytesSubscriber?.unsubscribe(channel, current.fn, true));
 		}
 	};
+	if (bytesSubscriber !== void 0) transport.subscribeBytes = (channel, onMessage) => {
+		const fn = (message) => onMessage(message);
+		listeners.set(channel, {
+			bytes: true,
+			fn
+		});
+		return settled(bytesSubscriber.subscribe(channel, fn, true));
+	};
+	return transport;
 }
 /**
 * Backplane **Redis pub/sub** (P13.5) — implémentation du port {@link IBackplane}
@@ -119,14 +167,24 @@ var RedisBackplane = class RedisBackplane {
 	#secret;
 	/** Borne mémoire des publications en vol (cf {@link BackplanePublishQueue}). */
 	#queue;
+	#notice;
+	/** Tri de l'entrée : écho, sceau, refus comptés (brique commune aux pilotes). */
+	#ingress;
 	#handler = null;
 	#started = false;
+	/**
+	* Sujet binaire : son codec et son canal Redis ({@link resolveRedisBytesChannel}) ;
+	* `null` tant que {@link enableBytes} n'a pas armé les octets.
+	*/
+	#bytes = null;
 	constructor(transport, originId = resolveBackplaneOriginId(), redisChannel = REDIS_RT_CHANNEL, secret = null, options = {}) {
 		this.#transport = transport;
 		this.originId = originId;
 		this.#redisChannel = redisChannel;
 		this.#secret = secret;
-		this.#queue = new BackplanePublishQueue(options.maxQueueBytes ?? 8388608, options.onNotice ?? null);
+		this.#notice = options.onNotice ?? null;
+		this.#queue = new BackplanePublishQueue(options.maxQueueBytes ?? 8388608, this.#notice);
+		this.#ingress = new BackplaneIngress(originId, secret, this.#notice);
 	}
 	/**
 	* Abonne au canal Redis dédié. Idempotent (le flag est posé avant l'`await` →
@@ -135,7 +193,32 @@ var RedisBackplane = class RedisBackplane {
 	async start() {
 		if (this.#started) return;
 		this.#started = true;
-		await this.#transport.subscribe(this.#redisChannel, (raw) => this.#ingress(raw));
+		await Promise.all([this.#transport.subscribe(this.#redisChannel, (raw) => this.#receive(raw)), this.#subscribeBytes()]);
+	}
+	/**
+	* Arme le sujet binaire (ADR-0021 S6) : les charges qui contiennent des octets
+	* partent en enveloppe encodée par `codec` sur un second canal Redis, et ce
+	* canal est écouté. Les charges sans octets gardent le sujet texte, intact pour
+	* les exemplaires plus anciens. Idempotent.
+	*
+	* @param codec - le codec binaire du serveur.
+	* @returns `false` si le transport ne sait pas s'abonner en octets.
+	*/
+	enableBytes(codec) {
+		if (this.#transport.subscribeBytes === void 0) return false;
+		if (this.#bytes !== null) return true;
+		this.#bytes = {
+			codec,
+			channel: resolveRedisBytesChannel(this.#redisChannel, codec)
+		};
+		if (this.#started) this.#subscribeBytes().catch((err) => this.#notice?.(`backplane : abonnement au sujet binaire en échec — les octets des autres exemplaires ne seront pas reçus (${err instanceof Error ? err.message : String(err)})`, "WARNING"));
+		return true;
+	}
+	/** Abonne le sujet binaire s'il est armé ; sinon rien. */
+	async #subscribeBytes() {
+		const bytes = this.#bytes;
+		if (bytes === null) return;
+		await this.#transport.subscribeBytes?.(bytes.channel, (raw) => this.#receiveBytes(raw, bytes.codec));
 	}
 	/**
 	* Propage une publication locale aux autres pods via Redis. NE refait PAS le
@@ -144,7 +227,8 @@ var RedisBackplane = class RedisBackplane {
 	* L'envoi passe par la **file bornée** : si le bus n'acquitte plus, les
 	* publications suivantes sont jetées et comptées plutôt que d'empiler des
 	* mégaoctets dans le client Redis (sémantique at-most-once déjà assumée par le
-	* port ; le client realtime re-synchronise).
+	* port ; le client realtime re-synchronise). Un ordre de contrôle, lui, part
+	* toujours (cf {@link BackplanePublishQueue.send}).
 	*/
 	publish(channel, payload) {
 		const env = {
@@ -152,30 +236,48 @@ var RedisBackplane = class RedisBackplane {
 			payload,
 			originId: this.originId
 		};
+		const bytes = this.#bytes;
+		if (bytes !== null && containsBytes(payload)) {
+			const bin = sealBackplaneEnvelopeBytes(env, bytes.codec, this.#secret);
+			this.#queue.send(channel, bin.byteLength, () => this.#transport.publish(bytes.channel, bin));
+			return;
+		}
 		const raw = sealBackplaneEnvelope(env, this.#secret);
-		this.#queue.send(Buffer.byteLength(raw), () => this.#transport.publish(this.#redisChannel, raw));
+		this.#queue.send(channel, Buffer.byteLength(raw), () => this.#transport.publish(this.#redisChannel, raw));
 	}
 	/** Un seul handler d'ingress ; un appel ultérieur remplace le précédent. */
 	onMessage(handler) {
 		this.#handler = handler;
 	}
 	/**
-	* Ouverture d'enveloppe (parse + vérification du sceau) + anti-echo + délégation.
-	* Robuste par construction : un message malformé, non scellé alors qu'un secret
-	* est exigé, ou au sceau invalide, est **ignoré** — jamais réinjecté, jamais fatal.
+	* Remet au hub ce que le tri d'entrée admet ({@link BackplaneIngress}) : l'écho
+	* de ce pod (Redis renvoie à l'émetteur) est compté sans être décodé ; un message
+	* malformé ou au sceau refusé est **ignoré** — jamais réinjecté, jamais fatal —,
+	* compté et annoncé la première fois puis une fois sur cent (ADR-0021 S6).
 	*/
-	#ingress(raw) {
-		const msg = openBackplaneEnvelope(raw, this.#secret);
-		if (msg === null) return;
-		if (msg.originId === this.originId) return;
-		this.#handler?.(msg);
+	#receive(raw) {
+		const msg = this.#ingress.text(raw);
+		if (msg !== null) this.#handler?.(msg);
+	}
+	/** Même tri que {@link #receive}, sur le sujet binaire. */
+	#receiveBytes(raw, codec) {
+		const msg = this.#ingress.bytes(raw, codec);
+		if (msg !== null) this.#handler?.(msg);
 	}
-	/** Désabonne du canal Redis et détache le handler. Idempotent. */
+	/**
+	* Laisse partir les publications déjà émises (acquittées ou refusées par Redis), puis désabonne du canal et détache le handler. Idempotent.
+	*
+	* Sans l'attente, un arrêt suivi de la sortie du processus perdait ce qui
+	* était encore dans la file — la preuve de vie FINALE de la présence comprise,
+	* et les pairs gardaient alors ce pod jusqu'au délai d'oubli. Un Redis qui ne
+	* répond plus fait attendre : l'appelant borne (l'arrêt du module le fait).
+	*/
 	async stop() {
 		this.#handler = null;
 		if (!this.#started) return;
 		this.#started = false;
-		await this.#transport.unsubscribe(this.#redisChannel);
+		await this.#queue.settled();
+		await Promise.all([this.#transport.unsubscribe(this.#redisChannel), this.#bytes !== null ? this.#transport.unsubscribe(this.#bytes.channel) : void 0]);
 	}
 	describe() {
 		return {
@@ -185,8 +287,11 @@ var RedisBackplane = class RedisBackplane {
 			crossPod: true,
 			channel: this.#redisChannel,
 			sealed: this.#secret !== null,
-			queue: this.#queue.describe()
+			...this.#secret !== null && { sealRejectedTotal: this.#ingress.sealRejectedTotal },
+			echoTotal: this.#ingress.echoTotal,
+			queue: this.#queue.describe(),
+			...this.#bytes !== null && { bytes: true }
 		};
 	}
 };
-export { REDIS_RT_CHANNEL, RedisBackplane, RedisBackplane as default, createRedisServiceTransport, isRedisPublisher, isRedisSubscriber, resolveRedisChannel };
+export { REDIS_RT_CHANNEL, RedisBackplane, RedisBackplane as default, createRedisServiceTransport, isRedisBytesSubscriber, isRedisPublisher, isRedisSubscriber, resolveRedisBytesChannel, resolveRedisChannel };

package/dist/nodefony/src/backplane/controlOrder.js

@@ -0,0 +1,86 @@
+import { ownField } from "nodefony";
+// nodefony/src/backplane/controlOrder.ts
+/**
+* Ordres de contrôle entre serveurs — la LISTE FERMÉE de ce qui circule sur le
+* canal `PLATFORM_BUS_CHANNELS.control` (ADR-0022 §6 décision 4).
+*
+* Un ordre ne fait qu'ENLEVER : terminer un canal, éjecter un compte d'un
+* canal. Aucun n'admet — seul `allow` fait entrer. Il voyage dans la charge
+* d'un message ordinaire du bus, donc sous le sceau de l'enveloppe
+* (`envelope.ts#sealBackplaneEnvelope`), sans champ neuf dans l'enveloppe ni
+* méthode neuve dans `IBackplane` : un driver tiers le transporte sans le savoir.
+*/
+/** Longueur maximale d'un champ texte d'un ordre (nom de canal, identifiant de compte). */
+const MAX_CONTROL_FIELD_LENGTH = 1024;
+/**
+* Un texte venu du bus est-il recevable — chaîne non vide d'au plus {@link MAX_CONTROL_FIELD_LENGTH} caractères ?
+*
+* Seule borne des textes du bus (nom de canal, identifiant de compte), lue par
+* les ordres de contrôle ET par les messages de présence (ADR-0025 P2).
+*
+* @param value - champ reçu (forme inconnue).
+*/
+function isBoundedBusText(value) {
+	return typeof value === "string" && value.length > 0 && value.length <= 1024;
+}
+/** Les types d'ordre que cette version sait appliquer — liste fermée. */
+function isKnownOp(op) {
+	return op === "close" || op === "evictUser";
+}
+/**
+* La charge est-elle un ordre d'un TYPE que cette version ne connaît pas — `op` lisible, mais hors de la liste fermée ?
+*
+* C'est ce qu'émet un serveur d'une version plus récente pendant un
+* déploiement progressif (ADR-0025, « Règle de lecture du bus ») : l'ordre
+* n'est pas appliqué, mais il ne se compte pas comme une injection. Rien
+* d'autre que `op` n'est lu — ses autres champs appartiennent à une version
+* qui n'est pas celle-ci. Une charge sans `op` textuel, ou d'un type CONNU de
+* forme fausse, n'est pas « inconnue » : elle est invalide.
+*
+* @param payload - la charge du message reçu (forme inconnue).
+* @returns `true` si le type d'ordre est inconnu de cette version.
+*/
+function isUnknownControlOrder(payload) {
+	const op = ownField(payload, "op");
+	return isBoundedBusText(op) && !isKnownOp(op);
+}
+/**
+* Lit un ordre de contrôle dans une charge venue du bus — `null` si la forme n'est pas celle d'un ordre connu.
+*
+* Une seule garde pour les deux bords : l'émetteur la passe avant de publier
+* (il n'émet jamais ce que ses pairs refuseraient), le récepteur avant
+* d'appliquer. Lecture par champs PROPRES (`ownField`) : une charge dont le
+* prototype porterait `op` ne passe pas. Un champ inconnu est toléré — c'est
+* ce qui laisse une version suivante ajouter un champ sans faire refuser ses
+* ordres pendant un déploiement progressif ; un champ CONNU de forme fausse
+* fait refuser l'ordre entier.
+*
+* @param payload - la charge du message reçu (forme inconnue).
+* @returns l'ordre, ou `null`.
+*/
+function readControlOrder(payload) {
+	const channel = ownField(payload, "channel");
+	if (!isBoundedBusText(channel)) return null;
+	const op = ownField(payload, "op");
+	if (!isKnownOp(op)) return null;
+	if (op === "close") return {
+		op,
+		channel
+	};
+	const user = ownField(payload, "user");
+	if (!isBoundedBusText(user)) return null;
+	const generation = ownField(payload, "generation");
+	if (generation === void 0) return {
+		op,
+		channel,
+		user
+	};
+	if (typeof generation !== "number" || !Number.isSafeInteger(generation) || generation < 0) return null;
+	return {
+		op,
+		channel,
+		user,
+		generation
+	};
+}
+export { MAX_CONTROL_FIELD_LENGTH, isBoundedBusText, isUnknownControlOrder, readControlOrder };