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

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

@@ -0,0 +1,168 @@
+// 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;
+}
+/**
+* Admet les trames entrantes d'un canal que sa règle `allow` vient d'ouvrir à la connexion.
+*
+* Pas de plafond propre : le nombre de canaux ouverts l'est déjà. Sans effet si le
+* canal n'accepte pas d'entrée client.
+*
+* @param state - état de la connexion.
+* @param channel - canal ouvert par `allow`.
+*/
+function admitByRule(state, channel) {
+	const inbound = state.inbound;
+	if (inbound === null || !canAdmit(state, inbound, channel)) return;
+	admittedTable(state, inbound)[channel] = true;
+}
+/**
+* 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 — celle de sa règle
+* `allow`, que rien ne justifie plus. Un verdict du verrou, lui, ne tient qu'à
+* l'identité et survit au désabonnement.
+*
+* @param state - état de la connexion.
+* @param channel - canal quitté.
+*/
+function releaseRuleAdmission(state, channel) {
+	const admitted = state.admitted;
+	if (admitted === null || admitted[channel] !== true) return;
+	if (state.retained?.includes(channel) === true) return;
+	admitted[channel] = false;
+}
+/**
+* Retient le « oui » du verrou pour un canal entrant à politique fixe (jamais un refus).
+*
+* Au plus {@link MAX_RETAINED_FRAME_VERDICTS} par connexion. 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) {
+	const retained = state.retained;
+	if (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. Les admissions par `allow` restent : elles valent autant que
+* l'abonnement qui les porte.
+*
+* @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` que l'abonnement n'a pas admis est refusé ;
+* - un canal entrant à politique fixe passe par le verrou, 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);
+	}
+	if (hub.resolveChannelAdmission(method) !== null) return false;
+	if (!hub.runAuthorizer(frame, state.peer)) return false;
+	retainVerdict(state, method, hub);
+	return true;
+}
+export { MAX_RETAINED_FRAME_VERDICTS, admitByRule, dropRetainedVerdicts, gateFrame, releaseRuleAdmission, revokeAdmission };

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

@@ -26,4 +26,13 @@ const SUBSCRIBED_FRAME_PREFIX = "{\"jsonrpc\":\"2.0\",\"method\":\"realtime:subs
 function subscribedAckFrame(channel) {
 	return SUBSCRIBED_FRAME_PREFIX + JSON.stringify(channel) + "}}";
 }
-export { subscribedAckFrame };
+/**
+* Sérialise `realtime:subscribed { channel, imposed: true }` — l'acquittement d'un abonnement imposé par le serveur.
+*
+* @param channel - le canal imposé (échappé par `JSON.stringify`).
+* @returns la trame JSON-RPC 2.0 prête à écrire sur le transport.
+*/
+function imposedSubscribedAckFrame(channel) {
+	return SUBSCRIBED_FRAME_PREFIX + JSON.stringify(channel) + ",\"imposed\":true}}";
+}
+export { imposedSubscribedAckFrame, subscribedAckFrame };

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

@@ -75,11 +75,10 @@ function createSyslogUplinkHandler(opts) {
 	let windowStart = 0;
 	let windowCount = 0;
 	return function onSyslogUplink(params) {
-		if (params === null || typeof params !== "object") return;
-		const batch = params;
-		const entries = batch.entries;
+		if (!isRecord(params)) return;
+		const entries = params.entries;
 		if (!Array.isArray(entries) || entries.length === 0) return;
-		const pageId = safeRequestId(batch.pageId, maxRequestIdLength);
+		const pageId = safeRequestId(params.pageId, maxRequestIdLength);
 		if (pageId === void 0) return;
 		const now = Date.now();
 		if (now - windowStart > windowMs) {

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

@@ -0,0 +1,37 @@
+// nodefony/src/server/welcomeIdentity.ts
+/**
+* Vue PUBLIQUE de l'identité d'une connexion, annoncée au client par `realtime:welcome` — tirée de l'identité d'admission quand le jeton en produit une.
+*
+* Un objet NEUF, champ par champ, et jamais l'identité d'admission elle-même :
+* celle-ci porte `issuer` et `account`, qui restent au serveur — la sérialiser
+* telle quelle les enverrait au client (ADR-0021 §S10 point 1). Les tableaux
+* de rôles et de scopes, eux, sont repris par RÉFÉRENCE : gelés une fois à la
+* construction de l'identité, ils ne se recopient pas.
+*
+* Un jeton sans `getIdentity` (authentificateur tiers) annonce `id: null` : son
+* identifiant stable n'est pas connu, et le déduire du login serait le défaut
+* même que `id` corrige.
+*
+* @param token - jeton figé à la poignée de main.
+* @returns l'identité à placer dans le `welcome`.
+*/
+function welcomeIdentityOf(token) {
+	const who = token.getIdentity?.();
+	if (who !== void 0) return {
+		type: who.type,
+		authenticated: who.authenticated,
+		id: who.id,
+		userIdentifier: who.userIdentifier,
+		roles: who.roles,
+		scopes: who.scopes
+	};
+	return {
+		type: token.type,
+		authenticated: token.isAuthenticated(),
+		id: null,
+		userIdentifier: token.getUserIdentifier(),
+		roles: token.getRoles(),
+		scopes: token.getScopes()
+	};
+}
+export { welcomeIdentityOf };

package/dist/nodefony/src/service/RealtimeService.js

@@ -1,8 +1,11 @@
-import { isRealtimeConfig } from "../../config/defineModuleConfig.js";
 import { RESERVED_SYSTEM_PREFIXES, getRealtimeHub } from "../server/RealtimeHub.js";
+import { realtimeConnectSource } from "./publicOrigin.js";
 import { applyDeclaredBroadcastPrefixes } from "../../decorators/realtimeDecorators.js";
+import { isRealtimeConfig } from "../../config/defineModuleConfig.js";
 import { Service } from "nodefony";
 // nodefony/src/service/RealtimeService.ts
+/** Nom sous lequel ce module contribue à la politique de contenu. */
+const CSP_CONTRIBUTOR = "realtime";
 const serviceName = "realtimeService";
 /**
 * Façade DI publique de la **socket Nodefony** côté serveur.
@@ -70,7 +73,17 @@ var RealtimeService = class extends Service {
 		}
 		hub.setOriginGuard(buildOriginGuard(this.#config));
 		hub.setMaxChannelsPerConnection(this.#config.limits.maxChannelsPerConnection);
+		hub.setAdmissionLimits({
+			authenticateTimeoutMs: this.#config.authenticateTimeoutMs,
+			allowTimeoutMs: this.#config.allowTimeoutMs,
+			maxPendingAllowsPerConnection: this.#config.maxPendingAllowsPerConnection,
+			maxPendingAllowsTotal: this.#config.maxPendingAllowsTotal
+		});
 		hub.setSlowConsumerBytes(this.#config.slowConsumer.bytes);
+		if (this.#config.codec === "cbor") {
+			const { CBOR_FRAME_CODEC } = await import("nodefony/cbor");
+			hub.setFrameCodec(CBOR_FRAME_CODEC);
+		} else hub.setFrameCodec();
 		hub.setClientLogsLimits(this.#config.clientLogs.enabled ? {
 			maxEntriesPerBatch: this.#config.clientLogs.maxEntriesPerBatch,
 			maxEntriesPerWindow: this.#config.clientLogs.maxEntriesPerWindow,
@@ -78,8 +91,26 @@ var RealtimeService = class extends Service {
 			maxStringLength: this.#config.clientLogs.maxStringLength
 		} : null);
 		applyDeclaredBroadcastPrefixes(hub);
+		if (this.#config.publicOrigin !== void 0) this.#declareCspOrigin(this.#config.publicOrigin);
 		return this;
 	}
+	/**
+	* Déclare au pare-feu l'origine publique de la socket dans `connect-src`.
+	*
+	* Différé à `onReady` : au moment de `init`, le module de sécurité peut ne pas
+	* avoir encore enregistré son pare-feu (ordre des modules). Sans pare-feu
+	* (application sans `@nodefony/security`), aucune politique n'est posée :
+	* rien à déclarer.
+	*
+	* @param publicOrigin - origine nue validée par le schéma
+	*/
+	#declareCspOrigin(publicOrigin) {
+		const source = realtimeConnectSource(publicOrigin);
+		if (source === null) return;
+		this.kernel?.once("onReady", () => {
+			this.get("firewall")?.registerCspOrigins?.(CSP_CONTRIBUTOR, { "connect-src": [source] });
+		});
+	}
 	/** Configuration realtime gelée (lue par Studio / introspection). */
 	getConfig() {
 		if (!this.#config) throw new Error(`${serviceName}: not initialized`);
@@ -89,6 +120,14 @@ var RealtimeService = class extends Service {
 	getHub() {
 		return this.#hub ??= getRealtimeHub();
 	}
+	/**
+	* Le codec texte des connexions socket, lu PAR NOM par le REST du plan
+	* d'administration (`AdminApiController`, framework ne dépend pas de realtime) :
+	* les octets d'une réponse `GET` y prennent la même forme que sur la socket.
+	*/
+	get textFrameCodec() {
+		return this.getHub().textFrameCodec;
+	}
 	/** Backplane actuellement branché sur le hub (ou null = Loopback implicite). */
 	getBackplane() {
 		return this.getHub().backplane;
@@ -96,6 +135,8 @@ var RealtimeService = class extends Service {
 	/**
 	* Publie une charge sur un canal — fan-out local + propagation backplane si
 	* canal broadcast. Délégué à `RealtimeHub.publish`.
+	*
+	* @throws TypeError si la charge est un scalaire ou `null` (cf `isRealtimePayload`).
 	*/
 	publish(channel, payload) {
 		this.getHub().publish(channel, payload);

package/dist/nodefony/src/service/publicOrigin.js

@@ -0,0 +1,40 @@
+import { parseBareOrigin } from "nodefony";
+// nodefony/src/service/publicOrigin.ts
+/**
+* Schémas qu'accepte `realtime.publicOrigin` : celui de la socket (`ws:`,
+* `wss:`) ou celui de l'hôte qui la sert (`http:`, `https:`), ramené au
+* premier.
+*/
+const REALTIME_ORIGIN_PROTOCOLS = [
+	"ws:",
+	"wss:",
+	"http:",
+	"https:"
+];
+/** Le schéma de socket qui correspond à chaque schéma accepté. */
+const SOCKET_SCHEME = {
+	"ws:": "ws:",
+	"wss:": "wss:",
+	"http:": "ws:",
+	"https:": "wss:"
+};
+/**
+* Rend la source `connect-src` qui autorise la socket servie à `publicOrigin`,
+* toujours sous son schéma de socket.
+*
+* Une source `wss://hôte` couvre `wss:` ET `https:` du même hôte (CSP Level 3,
+* « scheme-part match ») ; une source `https://hôte` ne couvrirait PAS la
+* socket. D'où la conversion `https:` → `wss:`, `http:` → `ws:`.
+*
+* @param publicOrigin - origine nue où la socket est servie
+* @returns la source à déclarer (`wss://rt.example.com:8443`), ou `null` si la
+*   valeur n'est pas une origine nue d'un schéma accepté
+*/
+function realtimeConnectSource(publicOrigin) {
+	const url = parseBareOrigin(publicOrigin, REALTIME_ORIGIN_PROTOCOLS);
+	if (url === null) return null;
+	const scheme = SOCKET_SCHEME[url.protocol];
+	if (scheme === void 0) return null;
+	return `${scheme}//${url.host}`;
+}
+export { REALTIME_ORIGIN_PROTOCOLS, realtimeConnectSource };

package/dist/nodefony/src/transport/WsConnectionTransport.js

@@ -24,6 +24,16 @@ import { decideSend } from "@nodefony/http";
 * la fermeture est signalée par `fireClose()` (hook `onFinish` du Context). Le
 * `connect`/`onOpen` sont des no-op (la connexion est déjà ouverte au handshake).
 */
+/**
+* Vrai si les octets reposent sur un `ArrayBuffer` ordinaire — ce que le pair
+* et ses codecs reçoivent (`RealtimeFrameData`), jamais un `SharedArrayBuffer`.
+*
+* @param bytes - les octets reçus.
+* @returns `true` si la vue porte sur un `ArrayBuffer`.
+*/
+function isOwnedBytes(bytes) {
+	return bytes.buffer instanceof ArrayBuffer;
+}
 var WsConnectionTransport = class {
 	conn;
 	_onMessage = null;
@@ -78,7 +88,7 @@ var WsConnectionTransport = class {
 	* Compte une trame ENTRANTE écartée et rend le cumul de sa nature — `1` dit
 	* « première », le seul instant où l'appelant journalise.
 	*
-	* @param kind - `binary` (sans lecteur) ou `malformed` (texte non JSON).
+	* @param kind - `binary` (sans lecteur) ou `malformed` (illisible par le codec).
 	* @returns le cumul de cette nature, après incrément.
 	*/
 	discard(kind) {
@@ -88,7 +98,7 @@ var WsConnectionTransport = class {
 	get binaryDiscarded() {
 		return this._binaryDiscarded;
 	}
-	/** Cumul de trames TEXTE reçues et écartées parce que non JSON — monotone. */
+	/** Cumul de trames reçues et écartées parce qu'illisibles par le codec de la connexion — monotone. */
 	get malformedDiscarded() {
 		return this._malformedDiscarded;
 	}
@@ -122,9 +132,22 @@ var WsConnectionTransport = class {
 		this._onClose = cb;
 	}
 	onError() {}
-	/** Pump entrant : le pipeline framework pousse ici chaque message reçu. */
+	/**
+	* Pump entrant : le pipeline framework pousse ici chaque frame reçue — texte,
+	* ou octets d'une connexion qui a négocié un codec binaire (ADR-0022 §2).
+	*
+	* Une vue sur un `SharedArrayBuffer` n'est pas une trame : `ws` livre
+	* toujours un `Buffer` sur un `ArrayBuffer`, le type de Node l'admet
+	* seulement. Elle est comptée comme illisible, jamais transmise au pair.
+	*
+	* @param raw - la trame telle que reçue.
+	*/
 	feed(raw) {
-		this._onMessage?.(raw);
+		if (typeof raw === "string" || isOwnedBytes(raw)) {
+			this._onMessage?.(raw);
+			return;
+		}
+		this._malformedDiscarded += 1;
 	}
 	/** Fermeture : appelée par le owner sur `onFinish` (close WS). */
 	fireClose(code = 1e3, reason = "") {