nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/client/client/react/index.js

@@ -0,0 +1,268 @@
+import { isRateChannel, parseRate, rateChannel } from "../../realtime/channelRate.js";
+import { adaptiveRebindKey, connectShared, observeChannel, observeChannelStats, observeIdentity, observeNoticeLog, observeNotices, observeSnapshot, observeState, observeSyslog } from "../realtime/observe.js";
+import * as React from "react";
+//#region src/client/react/index.ts
+/**
+* `nodefony/react` — bindings React **fins** du client temps réel isomorphe.
+*
+* Adapte le {@link RealtimeClient} (agnostique : `on()`/`emit()`/`state`) à la
+* réactivité React, sans MobX ni glue à recopier dans chaque app. Réutilisable
+* par Studio ET n'importe quelle app React servie par `@nodefony/frontend`.
+*
+* Principe : des hooks **ciblés et composables** (un hook = une responsabilité),
+* tous **marqués `nodefony`** (`useNodefony*`) pour les repérer d'un coup d'œil.
+* Pas un god-hook : on compose ce dont la vue a besoin. `react` est une peerDep
+* **optionnelle** (ce module n'est tiré que si on importe `nodefony/react`).
+* Aucun JSX (provider via `createElement`) → le build Core ne dépend pas d'un
+* transform JSX.
+*
+* **Ce fichier ne contient PLUS de règle temps réel.** Souscrire, tenir un
+* dernier reçu, borner un anneau, décoder le format coalescé du journal, ne
+* jamais couper une socket partagée : tout cela vit dans le socle agnostique
+* `nodefony/client` (`observe*`, `connectShared`), que les liaisons Vue, Angular
+* et Svelte consomment à l'identique. Ici ne reste que la traduction *rappel +
+* libération → réactivité React* — la seule chose qu'une liaison a le droit de
+* contenir. Un hook qui réencoderait une règle la ferait diverger des trois
+* autres fronts, en silence.
+*
+* L'app reste maîtresse du **cycle de connexion** (`client.connect()`), montée
+* une fois (ex. au shell). Les hooks ne gèrent QUE l'abonnement aux canaux.
+*
+* @module nodefony/react
+*/
+const NodefonyContext = React.createContext(null);
+/**
+* Injecte le client temps réel Nodefony dans le sous-arbre. À monter une fois,
+* au-dessus des composants qui consomment les hooks `useNodefony*`.
+*
+* @example Cas simple — deux concepts, ce Provider et un hook :
+* ```tsx
+* <NodefonyProvider url="/api/live/realtime">
+*   <Chat />
+* </NodefonyProvider>
+* ```
+*
+* @example Cas avancé — l'application possède le cycle de connexion :
+* ```tsx
+* <NodefonyProvider client={monClient}>…</NodefonyProvider>
+* ```
+*/
+function NodefonyProvider(props) {
+	const { url, client } = props;
+	const connection = React.useMemo(() => connectShared({
+		url,
+		client
+	}), [client, url]);
+	React.useEffect(() => connection.start(), [connection]);
+	return React.createElement(NodefonyContext.Provider, { value: connection.socket }, props.children);
+}
+/**
+* `useNodefony()` — le client temps réel brut (hub : canaux, syslog, stats…).
+* Tête de gondole + échappatoire pour les cas avancés. Référence stable (pas de
+* re-render) ; pour l'état réactif, utiliser les hooks dédiés ci-dessous.
+*
+* @throws si appelé hors d'un `<NodefonyProvider>`.
+*/
+function useNodefony() {
+	const client = React.useContext(NodefonyContext);
+	if (!client) throw new Error("useNodefony() doit être utilisé dans un <NodefonyProvider>.");
+	return client;
+}
+/**
+* `useNodefonyState()` — état de la connexion (`"connected" | "reconnecting" | …`).
+* `useSyncExternalStore` : re-render UNIQUEMENT au changement d'état (snapshot
+* primitif, sans tearing en mode concurrent).
+*
+* Branché sur `onState` — la porte publique — et non sur le nom de l'événement
+* local, qui n'a pas à sortir du client.
+*/
+function useNodefonyState() {
+	const client = useNodefony();
+	return React.useSyncExternalStore((cb) => observeState(client, () => cb()), () => client.state, () => client.state);
+}
+/**
+* `useNodefonyIdentity()` — l'**identité résolue** de la connexion, annoncée par
+* le serveur au `realtime:welcome` (`authenticated`, `roles`, `userIdentifier`,
+* `scopes`). `null` tant qu'aucun welcome n'a été reçu ; une fois reçu, un
+* visiteur anonyme a `authenticated: false`. `useSyncExternalStore` → re-render
+* uniquement quand l'identité change ((re)welcome ou logout). Brique du gating
+* front : `authenticated:false` → écran login, **sans** route `/auth/me`.
+*/
+function useNodefonyIdentity() {
+	const client = useNodefony();
+	return React.useSyncExternalStore((cb) => observeIdentity(client, () => cb()), () => client.identity, () => client.identity);
+}
+/**
+* `useNodefonyChannel()` — s'abonne à un canal pub/sub : `onMessage` est appelé
+* à chaque message. Le socle apparie subscribe/unsubscribe serveur (ref-comptés)
+* et le re-subscribe au reconnect. Le handler peut changer à chaque render sans
+* re-déclencher l'abonnement (capturé via ref) ; passer `deps` si le canal
+* effectif dépend d'autres valeurs.
+*/
+function useNodefonyChannel(channel, onMessage, deps = []) {
+	const client = useNodefony();
+	const handlerRef = React.useRef(onMessage);
+	handlerRef.current = onMessage;
+	React.useEffect(() => {
+		return observeChannel(client, channel, (payload) => handlerRef.current(payload));
+	}, [
+		client,
+		channel,
+		...deps
+	]);
+}
+/**
+* `useNodefonyChannelData()` — la **dernière valeur** reçue sur un canal (cas le
+* plus courant : dernière mesure d'un flux de stats). `null` tant que rien n'est
+* arrivé.
+*/
+function useNodefonyChannelData(channel, initial = null) {
+	const [data, setData] = React.useState(initial);
+	useNodefonyChannel(channel, (payload) => setData(payload), []);
+	return data;
+}
+/**
+* `useNodefonyAdaptiveChannel()` — équivalent **handler-based** de {@link useNodefonyChannel}
+* mais en **cadence adaptative** (AIMD client-driven, cf {@link RealtimeClient.adaptiveChannel}) :
+* la lib recule la cadence sous famine puis la remonte quand c'est sain. `onMessage` reçoit
+* chaque frame (handler riche autorisé) ; **renvoie la cadence effective** (ms) pour un badge.
+* Primitif commun à tous les dashboards d'état (Supervision, ORM…) → **logique live identique**.
+* Réservé aux canaux d'ÉTAT (latest-wins). Réglage `enabled` (off = abonnement fixe).
+*
+* Le ré-abonnement n'est relancé que si `base`, `desiredMs`, `enabled` ou `deps` changent —
+* la clé vient de {@link adaptiveRebindKey}, la MÊME que celle des autres liaisons (le
+* handler + les `opts` sont capturés par ref → identité instable sans re-bind).
+*/
+function useNodefonyAdaptiveChannel(base, onMessage, desiredMs, opts = {}, deps = []) {
+	const client = useNodefony();
+	const handlerRef = React.useRef(onMessage);
+	handlerRef.current = onMessage;
+	const optsRef = React.useRef(opts);
+	optsRef.current = opts;
+	const [intervalMs, setIntervalMs] = React.useState(desiredMs);
+	const enabled = opts.enabled !== false;
+	const rebindKey = adaptiveRebindKey(base, desiredMs, enabled);
+	React.useEffect(() => {
+		const binding = client.adaptiveChannel(base, (...args) => handlerRef.current(args[0]), {
+			...optsRef.current,
+			intervalMs: desiredMs,
+			enabled,
+			onRate: (ms) => setIntervalMs(ms)
+		});
+		return () => binding.dispose();
+	}, [
+		client,
+		rebindKey,
+		...deps
+	]);
+	return intervalMs;
+}
+/**
+* `useNodefonyAdaptiveChannelData()` — comme {@link useNodefonyChannelData} mais en cadence
+* adaptative. Mince surcouche de {@link useNodefonyAdaptiveChannel} : garde la **dernière
+* valeur** reçue + renvoie la cadence effective (badge UI). Réservé aux canaux d'ÉTAT.
+*/
+function useNodefonyAdaptiveChannelData(base, desiredMs, opts = {}, deps = []) {
+	const [data, setData] = React.useState(null);
+	return {
+		data,
+		intervalMs: useNodefonyAdaptiveChannel(base, (payload) => setData(payload), desiredMs, opts, deps)
+	};
+}
+/**
+* `useNodefonyChannelStats()` — stats live d'un canal (débit, série VU-mètre,
+* total). Source = le client Core (`getChannelStats`, échantillonné 1×/s).
+* Implémenté en `state`+effet (pas `useSyncExternalStore`) car le snapshot est
+* un objet recréé → la stabilité de référence requise par le store externe ne
+* tiendrait pas.
+*/
+function useNodefonyChannelStats(channel) {
+	const client = useNodefony();
+	const [stats, setStats] = React.useState(null);
+	React.useEffect(() => observeChannelStats(client, channel, setStats), [client, channel]);
+	return stats;
+}
+/**
+* `useNodefonySnapshot()` — ce que la socket sait d'ELLE-MÊME : état, canaux
+* tenus, trames reçues, trames perdues, dernière trame. Rafraîchi par
+* l'échantillonneur déjà en place — aucune horloge de plus, aucune trame émise
+* pour mesurer.
+*
+* La donnée est au socle, la **boîte qui l'affiche** reste à chaque front : les
+* quatre vitrines lisaient ces cinq champs à la main, c'est-à-dire quatre
+* lectures qui divergeront.
+*/
+function useNodefonySnapshot() {
+	const client = useNodefony();
+	const [snapshot, setSnapshot] = React.useState(null);
+	React.useEffect(() => observeSnapshot(client, setSnapshot), [client]);
+	return snapshot;
+}
+/**
+* `useNodefonySyslog()` — flux syslog prêt à l'emploi : ring buffer borné +
+* filtre de sévérité. Le format **coalescé** du canal (`{ logs: Pdu[], dropped }`),
+* l'entrée unique, la taille de l'anneau et le canal par défaut viennent du
+* socle ({@link observeSyslog}) : ce hook n'en connaît aucun. Brique de la page
+* Logs — un seul appel remplace l'effet + le buffer manuels.
+*/
+function useNodefonySyslog(opts = {}) {
+	const { max, severities, channel } = opts;
+	const client = useNodefony();
+	const sevKey = severities ? severities.join(",") : "";
+	const [entries, setEntries] = React.useState([]);
+	React.useEffect(() => {
+		return observeSyslog(client, setEntries, {
+			max,
+			severities,
+			channel
+		});
+	}, [
+		client,
+		channel,
+		max,
+		sevKey
+	]);
+	return entries;
+}
+/**
+* `useNodefonyNotifications()` — s'abonne au flux de **notices normalisées** du
+* client : criticités qui cassent le temps réel (close codes RFC 6455 interprétés),
+* erreurs serveur poussées, rétablissement de connexion. `onNotice` est appelé
+* pour CHAQUE notice → brancher un centre de notifications (snackbar). Le handler
+* peut changer à chaque render sans re-déclencher l'abonnement (capturé via ref).
+*
+* À monter **une seule fois** (shell de l'app) pour ne pas dupliquer les toasts.
+*/
+function useNodefonyNotifications(onNotice, deps = []) {
+	const client = useNodefony();
+	const handlerRef = React.useRef(onNotice);
+	handlerRef.current = onNotice;
+	React.useEffect(() => {
+		return observeNotices(client, (notice) => handlerRef.current(notice));
+	}, [client, ...deps]);
+}
+/**
+* `useNodefonyNoticeLog()` — ring buffer borné des dernières notices, filtrable
+* par source. Brique du hub temps réel (« incidents temps réel ») : un historique
+* léger des criticités realtime, distinct des toasts éphémères. La taille de
+* l'anneau et le filtrage viennent du socle ({@link observeNoticeLog}).
+*/
+function useNodefonyNoticeLog(opts = {}) {
+	const { max, sources } = opts;
+	const client = useNodefony();
+	const srcKey = sources ? sources.join(",") : "";
+	const [notices, setNotices] = React.useState([]);
+	React.useEffect(() => {
+		return observeNoticeLog(client, setNotices, {
+			max,
+			sources
+		});
+	}, [
+		client,
+		max,
+		srcKey
+	]);
+	return notices;
+}
+//#endregion
+export { NodefonyProvider, isRateChannel, parseRate, rateChannel, useNodefony, useNodefonyAdaptiveChannel, useNodefonyAdaptiveChannelData, useNodefonyChannel, useNodefonyChannelData, useNodefonyChannelStats, useNodefonyIdentity, useNodefonyNoticeLog, useNodefonyNotifications, useNodefonySnapshot, useNodefonyState, useNodefonySyslog };

package/dist/client/client/realtime/AdaptiveRate.js

@@ -0,0 +1,240 @@
+import { rateChannel } from "../../realtime/channelRate.js";
+//#region src/client/realtime/AdaptiveRate.ts
+/**
+* AdaptiveRate — cadence ADAPTATIVE automatique d'un canal d'ÉTAT, **client-driven**
+* (niveau 1, zéro changement serveur). Pendant exact de l'ABR vidéo (HLS/DASH ajustent
+* la qualité selon le buffer) et du contrôle de congestion réseau (TCP **AIMD**).
+*
+* Idée : la cadence vit dans le nom du canal (cf {@link rateChannel} — 1 canal = 1 cadence
+* = 1 ticker serveur). Si le client observe que les frames arrivent **plus lentement** que
+* demandé (famine ⇒ event-loop serveur ou réseau sous pression), il se ré-abonne à une
+* cadence **plus grossière** (`1s→2s→5s`) → moins de pushes → la pression retombe → le flux
+* récupère ; quand c'est sain durablement, il remonte **doucement** vers la cadence désirée.
+*
+* AIMD (asymétrie anti-oscillation, comme TCP) :
+*  - **Multiplicative Decrease** : famine ⇒ on monte d'un cran l'échelle (cadence grossie),
+*    immédiat. L'échelle géométrique (×2) rend la décrue multiplicative.
+*  - **Additive Increase** : on ne redescend d'un cran (cadence affinée) qu'après une
+*    **fenêtre** de N échantillons sains → reprise lente.
+*  - **bande morte** (hystérésis) entre « sain » et « famine » : aucun changement → pas de
+*    flip-flop.
+*
+* Réservé aux canaux d'**ÉTAT** (latest-wins : supervision, stats) où décimer est sans perte.
+* PAS pour les canaux d'**ÉVÉNEMENTS** (syslog, frames protocole) où chaque item compte
+* (eux se batchent, pas se décimer).
+*
+* Cette classe est la **machine à états pure** (aucun timer, aucune socket) → déterministe
+* et testable. Le câblage à une socket réelle vit dans {@link bindAdaptiveChannel}.
+*
+* @see {@link bindAdaptiveChannel} — glue socket + watchdog.
+* @see {@link rateChannel} — convention de nommage cadencé partagée client↔serveur.
+*/
+/** Construit une échelle géométrique ×2 de `intervalMs` à `maxMs` (bornes incluses). */
+function deriveLadder(intervalMs, maxMs) {
+	const ladder = [];
+	let ms = intervalMs;
+	while (ms < maxMs) {
+		ladder.push(ms);
+		ms *= 2;
+	}
+	ladder.push(maxMs);
+	return ladder;
+}
+var AdaptiveRate = class {
+	ladder;
+	starvationFactor;
+	healthyFactor;
+	recoveryWindow;
+	/** Position dans l'échelle (0 = cadence la plus fine = désirée). */
+	idx = 0;
+	/** Échantillons sains consécutifs depuis le dernier changement. */
+	healthy = 0;
+	/** Timestamp (ms) de la dernière frame ; `null` = pas de référence (post-switch/init). */
+	lastFrameTs = null;
+	constructor(options) {
+		const maxMs = options.maxMs ?? 6e4;
+		const ladder = options.ladder && options.ladder.length > 0 ? [...options.ladder].sort((a, b) => a - b) : deriveLadder(options.intervalMs, Math.max(options.intervalMs, maxMs));
+		this.ladder = ladder;
+		this.starvationFactor = options.starvationFactor ?? 1.8;
+		this.healthyFactor = options.healthyFactor ?? 1.25;
+		this.recoveryWindow = options.recoveryWindow ?? 4;
+	}
+	/** Cadence courante (ms). */
+	current() {
+		return this.ladder[this.idx];
+	}
+	/** Décale d'un cran vers le grossier (MD) ; renvoie `true` si la cadence a changé. */
+	decrease() {
+		if (this.idx >= this.ladder.length - 1) return false;
+		this.idx += 1;
+		return true;
+	}
+	/** Décale d'un cran vers le fin (AI) ; renvoie `true` si la cadence a changé. */
+	increase() {
+		if (this.idx <= 0) return false;
+		this.idx -= 1;
+		return true;
+	}
+	/** Réamorce la mesure (après un changement de cadence). */
+	resetSample() {
+		this.lastFrameTs = null;
+		this.healthy = 0;
+	}
+	/**
+	* À appeler à CHAQUE frame reçue. Pilote l'**AI** (reprise) et détecte aussi la famine
+	* sur frames lentes (**MD**).
+	*
+	* @param now - horloge (ms).
+	* @returns une {@link RateDecision} si la cadence doit changer, sinon `null`.
+	*/
+	noteFrame(now) {
+		const prev = this.lastFrameTs;
+		this.lastFrameTs = now;
+		if (prev === null) return null;
+		const gap = now - prev;
+		const cur = this.current();
+		if (gap > this.starvationFactor * cur) {
+			if (this.decrease()) {
+				this.resetSample();
+				return {
+					intervalMs: this.current(),
+					reason: "decrease"
+				};
+			}
+			this.healthy = 0;
+			return null;
+		}
+		if (gap <= this.healthyFactor * cur) {
+			this.healthy += 1;
+			if (this.healthy >= this.recoveryWindow && this.increase()) {
+				this.resetSample();
+				return {
+					intervalMs: this.current(),
+					reason: "increase"
+				};
+			}
+			return null;
+		}
+		this.healthy = 0;
+		return null;
+	}
+	/**
+	* Watchdog : à appeler périodiquement. Détecte la famine **totale** (plus aucune frame)
+	* que {@link noteFrame} ne verrait pas (faute de frame).
+	*
+	* @param now - horloge (ms).
+	* @returns une {@link RateDecision} (toujours `"decrease"`) si la cadence doit grossir.
+	*/
+	checkStarvation(now) {
+		if (this.lastFrameTs === null) return null;
+		if (now - this.lastFrameTs > this.starvationFactor * this.current()) {
+			if (this.decrease()) {
+				this.resetSample();
+				return {
+					intervalMs: this.current(),
+					reason: "decrease"
+				};
+			}
+		}
+		return null;
+	}
+};
+const defaultScheduler = {
+	set: (cb, ms) => setInterval(cb, ms),
+	clear: (h) => clearInterval(h)
+};
+const defaultClock = () => typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+/**
+* Câble un {@link AdaptiveRate} à une socket réelle : abonne `base` à sa cadence désirée,
+* mesure la gigue d'arrivée, et **ré-abonne** automatiquement à une cadence plus grossière
+* en cas de famine (MD) puis plus fine quand c'est sain (AI). Les frames continuent d'être
+* livrées à `handler` à travers les changements de cadence.
+*
+* Réservé aux canaux d'ÉTAT (latest-wins). Pour les canaux d'événements, ne pas décimer.
+*
+* @param socket - la socket Nodefony ({@link IRealtimeSocket}).
+* @param base - canal de base (sans suffixe de cadence).
+* @param handler - reçoit le payload de chaque frame.
+* @param options - cadence désirée + réglages AIMD + injections.
+* @returns une {@link AdaptiveChannelBinding} (cadence courante + `dispose`).
+*/
+function bindAdaptiveChannel(socket, base, handler, options) {
+	if (options.enabled === false) {
+		const channel = rateChannel(base, options.intervalMs, options.defaultMs);
+		socket.subscribe(channel);
+		const offFixed = socket.on(channel, handler);
+		options.onRate?.(options.intervalMs, "init");
+		let downFixed = false;
+		return {
+			get intervalMs() {
+				return options.intervalMs;
+			},
+			get channel() {
+				return channel;
+			},
+			dispose() {
+				if (downFixed) return;
+				downFixed = true;
+				offFixed();
+				socket.unsubscribe(channel);
+			}
+		};
+	}
+	const clock = options.clock ?? defaultClock;
+	const scheduler = options.scheduler ?? defaultScheduler;
+	const ar = new AdaptiveRate(options);
+	let currentMs = ar.current();
+	let currentChannel = rateChannel(base, currentMs, options.defaultMs);
+	let off = null;
+	let watchdog;
+	let disposed = false;
+	const wrapped = (...args) => {
+		const decision = ar.noteFrame(clock());
+		handler(...args);
+		if (decision) applyDecision(decision);
+	};
+	const armWatchdog = () => {
+		if (watchdog !== void 0) scheduler.clear(watchdog);
+		watchdog = scheduler.set(() => {
+			const decision = ar.checkStarvation(clock());
+			if (decision) applyDecision(decision);
+		}, currentMs);
+	};
+	function applyDecision(decision) {
+		if (disposed) return;
+		const nextChannel = rateChannel(base, decision.intervalMs, options.defaultMs);
+		currentMs = decision.intervalMs;
+		if (nextChannel !== currentChannel) {
+			const oldChannel = currentChannel;
+			const oldOff = off;
+			socket.subscribe(nextChannel);
+			off = socket.on(nextChannel, wrapped);
+			oldOff?.();
+			socket.unsubscribe(oldChannel);
+			currentChannel = nextChannel;
+		}
+		armWatchdog();
+		options.onRate?.(currentMs, decision.reason);
+	}
+	socket.subscribe(currentChannel);
+	off = socket.on(currentChannel, wrapped);
+	armWatchdog();
+	options.onRate?.(currentMs, "init");
+	return {
+		get intervalMs() {
+			return currentMs;
+		},
+		get channel() {
+			return currentChannel;
+		},
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			if (watchdog !== void 0) scheduler.clear(watchdog);
+			off?.();
+			socket.unsubscribe(currentChannel);
+		}
+	};
+}
+//#endregion
+export { AdaptiveRate, AdaptiveRate as default, bindAdaptiveChannel };

package/dist/client/client/realtime/BrowserWsTransport.js

@@ -0,0 +1,57 @@
+import { TransportState } from "../../realtime/IRealtimeTransport.js";
+//#region src/client/realtime/BrowserWsTransport.ts
+/**
+* BrowserWsTransport — transport {@link IRealtimeTransport} pour le navigateur :
+* wrap d'un `WebSocket` natif. Volontairement « bête » : il ouvre/envoie/ferme et
+* relaie les events. L'orchestration (reconnect, backoff, heartbeat, state machine)
+* vit AU-DESSUS dans `RealtimeClient` — qui crée un transport NEUF à chaque tentative.
+*
+* L'URL reçue est déjà normalisée (ws/wss, token) par l'appelant.
+*/
+var BrowserWsTransport = class {
+	url;
+	ws = null;
+	_onOpen = null;
+	_onMessage = null;
+	_onClose = null;
+	_onError = null;
+	constructor(url) {
+		this.url = url;
+	}
+	connect() {
+		const ws = new WebSocket(this.url);
+		this.ws = ws;
+		ws.addEventListener("open", () => this._onOpen?.());
+		ws.addEventListener("message", (ev) => {
+			if (typeof ev.data === "string") this._onMessage?.(ev.data);
+		});
+		ws.addEventListener("close", (ev) => {
+			this.ws = null;
+			this._onClose?.(ev.code, ev.reason);
+		});
+		ws.addEventListener("error", () => this._onError?.(/* @__PURE__ */ new Error("websocket error")));
+	}
+	send(raw) {
+		if (this.ws?.readyState === TransportState.OPEN) this.ws.send(raw);
+	}
+	close(code, reason) {
+		this.ws?.close(code, reason);
+	}
+	get readyState() {
+		return this.ws?.readyState ?? TransportState.CLOSED;
+	}
+	onOpen(cb) {
+		this._onOpen = cb;
+	}
+	onMessage(cb) {
+		this._onMessage = cb;
+	}
+	onClose(cb) {
+		this._onClose = cb;
+	}
+	onError(cb) {
+		this._onError = cb;
+	}
+};
+//#endregion
+export { BrowserWsTransport, BrowserWsTransport as default };