@nodefony/realtime 10.0.0-alpha.1

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

@@ -0,0 +1,601 @@
+import { ANONYMOUS_REALTIME_TOKEN } from "./AnonymousRealtimeToken.js";
+import { getRealtimeHub } from "./RealtimeHub.js";
+import { DEFAULT_ACTION_POLICY, getRealtimeActions, getRealtimeChannelPolicies, getRealtimeChannels, getRealtimeInbound } from "../../decorators/realtimeDecorators.js";
+import { createSyslogUplinkHandler } from "./syslogUplink.js";
+import { WsConnectionTransport } from "../transport/WsConnectionTransport.js";
+import { welcomeEnv } from "./welcomeEnv.js";
+import { deniedDetail } from "./deniedDetail.js";
+import { JsonRpcPeer, PLATFORM_INBOUND, RequestContext, RpcEnvelope, RpcError } from "nodefony";
+import { readBackpressureOptions } from "@nodefony/http";
+import { Controller } from "@nodefony/framework";
+//#region nodefony/src/server/RealtimeController.ts
+/**
+* Statut HTTP-équivalent d'une erreur survenue pendant une invocation du pont.
+*
+* UNE seule lecture pour les trois sources possibles — la `RpcError` déjà mappée
+* (404 d'un path inconnu…), le `nodefonyError` HTTP-like levé par une action ou
+* une garde (`@IsGranted` → 403), et le `HttpError` 405 agrégé du Router. Écrire
+* ce test à trois endroits l'aurait fait diverger (règle : une décision, une
+* fonction).
+*
+* @returns le statut, ou `null` si l'erreur n'est pas HTTP-like (→ opaque).
+*/
+function httpStatusOfFrameError(e) {
+	if (e instanceof RpcError) {
+		const status = e.data?.status;
+		if (typeof status === "number") return status;
+		return e.code === -32602 ? 400 : null;
+	}
+	const code = e.code;
+	return typeof code === "number" && code >= 400 && code <= 599 ? code : null;
+}
+/**
+* Erreur renvoyée au pair pour une invocation en échec.
+*
+* Un refus est une RÉPONSE (statut exposé, symétrie d'un `fetch`) ; une panne
+* reste OPAQUE (`-32603` générique côté peer — Zero Trust). En profiling, l'id
+* du profil est joint aux refus : le client peut alors radiographier son propre
+* refus (le 403 `@IsGranted` devient pédagogique au lieu d'être un mur).
+*/
+function toFrameRpcError(e, status, requestId) {
+	if (e instanceof RpcError) {
+		if (!requestId) return e;
+		const data = typeof e.data === "object" && e.data !== null ? {
+			...e.data,
+			requestId
+		} : { requestId };
+		return new RpcError(e.message, e.code, data);
+	}
+	if (status !== null) {
+		const data = { status };
+		if (requestId) data.requestId = requestId;
+		return new RpcError(e instanceof Error ? e.message : String(e), -32e3, data);
+	}
+	return e;
+}
+let warnedUnenforcedPolicies = false;
+/**
+* RealtimeController — base d'un endpoint WebSocket temps réel SERVEUR (JSON-RPC 2.0).
+*
+* Factorise TOUT le protocole (handshake/welcome, discrimination request/notification/
+* response via {@link JsonRpcPeer}, actions `result`/`error`, pub/sub par canal, cleanup)
+* — écrit UNE fois, partagé par tous les modules. Un contrôleur concret ne déclare que
+* son métier : {@link createRealtimeChannel} (providers de canaux) + {@link realtimeActions}.
+*
+* Chaque connexion compose un `JsonRpcPeer` (le MÊME que `RealtimeClient` côté navigateur
+* — symétrie isomorphe) branché sur un {@link WsConnectionTransport}.
+*
+* Usage : le sous-classe garde sa route WS et délègue —
+* ```ts
+* @route("ws", { path: "/realtime", requirements: { methods: ["WEBSOCKET"] } })
+* async realtime(message: string | Buffer | null) { this.handleRealtime(message); }
+* ```
+*
+* Perf : les canaux sont **partagés** via {@link RealtimeHub} (1 provider/canal/pod, pas
+* 1 par connexion) ; chaque connexion n'ajoute/retire qu'un *sink* (fan-out). Provider
+* créé au 1ᵉʳ abonné, `dispose()` au dernier (`unsubscribe` ou `onFinish`). Le dispatch
+* d'action n'est payé que sur une requête `id`. C'est aussi le seam du backplane Redis.
+*/
+var RealtimeController = class extends Controller {
+	/**
+	* Map des factories de canaux EXACT, lue depuis les décorateurs `@RealtimeChannel`
+	* au handshake (cold-path) et mémoïsée par instance. `null` = pas de décorateur
+	* sur cette classe → la base court-circuite la lecture metadata par frame.
+	*/
+	_decoratedChannels = null;
+	/**
+	* Crée le provider d'un canal (listener/ticker → `publish`) et renvoie son `dispose`.
+	* `null` si le canal est inconnu — la base ne souscrit pas.
+	*
+	* **Deux façons de déclarer un canal** (coexistent sans casse) :
+	*  1. **Décorateur `@RealtimeChannel(name)`** sur une méthode (match EXACT, déclaratif).
+	*  2. **Override de cette méthode** (pattern/regex, suffixe `:<ms>`, drill `@<pid>`).
+	*
+	* La base CONSULTE D'ABORD les décorateurs ; si aucun match, elle appelle
+	* cette méthode (fallback). Défaut : `null`. Un controller qui n'utilise QUE
+	* des décorateurs peut donc se passer d'override.
+	*/
+	createRealtimeChannel(_channel, _publish) {
+		return null;
+	}
+	/** Actions RPC exposées (requête→réponse). À surcharger ; défaut : aucune. */
+	realtimeActions() {
+		return {};
+	}
+	/** Canaux annoncés au handshake. À surcharger ; défaut : aucun. */
+	realtimeChannels() {
+		return [];
+	}
+	/**
+	* Préfixes de canaux **broadcast** (cross-process) de cet endpoint. À surcharger ;
+	* défaut : **aucun** → tous les canaux restent **instance-local** (observabilité,
+	* état du pod). Un canal listé ici traverse le {@link IBackplane} (cluster IPC /
+	* Redis) : chat, présence, notifications… Cf {@link RealtimeHub.markBroadcastChannel}
+	* (défaut sûr : pas de fuite cross-pod de données per-instance sans intention explicite).
+	*/
+	realtimeBroadcastChannels() {
+		return [];
+	}
+	/**
+	* Canaux FULL-DUPLEX acceptant une entrée client (`method` = nom du canal). À
+	* surcharger ; défaut : **aucun** (sûr — un client ne peut rien pousser au serveur
+	* tant qu'un canal n'est pas explicitement déclaré ici). Seam des backings entrants
+	* (SIP, bridge). Cf {@link RealtimeInboundHandler} (params NON FIABLES).
+	*/
+	realtimeInbound() {
+		return {};
+	}
+	/**
+	* Opt-in du **pont API** (« API souveraine », POC Ph.3) : `true` → la
+	* connexion expose la méthode RPC `api.request {path}` qui re-route le path
+	* porté par le message vers l'action controller correspondante — la MÊME
+	* action que le GET REST (`socket.request("/nodefony/kernel/api/modules")`
+	* côté client). Le pont n'atteint QUE les routes déclarant le transport
+	* `WEBSOCKET` dans leurs `methods` (zéro bypass : une action dit à quels
+	* transports elle répond). À surcharger ; défaut : `false` — aucune surface
+	* d'invocation ajoutée à un hub sans intention explicite.
+	*/
+	realtimeApiRequest() {
+		return false;
+	}
+	/**
+	* Point d'entrée à appeler depuis la route WS du contrôleur. `message === null`
+	* = handshake (1ʳᵉ invocation) ; sinon = frame entrante.
+	*
+	* Le handshake est désormais ASYNC (seams sécu #2/#4 : origin check + run
+	* d'authenticator au handshake). Les frames texte entrantes pendant
+	* l'authentification sont DROP silencieusement — le transport JSON-RPC n'est pas
+	* encore branché, il n'existe donc AUCUN canal pour porter un refus. Le silence
+	* est structurel, pas un choix : c'est au client d'attendre `realtime:welcome`
+	* avant de pousser.
+	*
+	* ⚠️ Cette phrase a longtemps ajouté « ce que `RealtimeClient` fait nativement ».
+	* C'était FAUX : le client rejouait ses abonnements dès l'ouverture de la socket,
+	* si bien qu'un `subscribe` posé avant le démarrage et TOUS ceux d'après une
+	* reconnexion étaient perdus ici même, sans un mot des deux côtés. Un contrat écrit
+	* d'un seul côté du fil n'est pas tenu ; il l'est désormais par
+	* `RealtimeClient.replaySubscriptions` et les deux cas « la fenêtre où le serveur
+	* écoute (welcome) » de `RealtimeClientCoverage.test.ts`.
+	*/
+	handleRealtime(message) {
+		const ctx = this.context;
+		if (!ctx) return;
+		if (message == null) {
+			this.onHandshake(ctx);
+			return;
+		}
+		ctx.__nfRealtime?.transport.feed(message.toString());
+	}
+	/**
+	* **L1 — duplex serveur→client.** Émet une REQUÊTE vers le client de CETTE
+	* connexion (sur une action qu'il a exposée via `client.register(...)`) et attend
+	* sa réponse. Possible depuis L0 : le client compose le même `JsonRpcPeer`, il
+	* est donc un *callee* (avant L0 : `-32601` systématique).
+	*
+	* Usages : confirmation d'action (le serveur demande au client de valider),
+	* invalidation de cache poussée AVEC accusé, health applicatif serveur→client.
+	* Pour une notification sans réponse → {@link notifyClient} (ou un canal pub/sub).
+	*
+	* @returns le `result` du handler client ; rejette sur erreur applicative
+	*   ({@link RpcError} `code`/`data` préservés), méthode inconnue (`-32601`),
+	*   timeout, ou connexion fermée (`dispose`).
+	* @throws (rejet) si le handshake n'est pas terminé (aucun peer encore).
+	*/
+	requestClient(method, params, timeoutMs) {
+		const state = this.context.__nfRealtime;
+		if (!state) return Promise.reject(/* @__PURE__ */ new Error("requestClient: connexion realtime non établie (welcome non émis)"));
+		return state.peer.request(method, params, timeoutMs);
+	}
+	/**
+	* Notification CIBLÉE serveur→client (sans réponse) vers CETTE connexion, hors
+	* canal pub/sub — pendant *fire-and-forget* de {@link requestClient}. Pour un
+	* fan-out à N abonnés, préférer un canal (`publish` via le hub). No-op si le
+	* handshake n'est pas terminé.
+	*/
+	notifyClient(method, params) {
+		this.context.__nfRealtime?.peer.notify(method, params);
+	}
+	/**
+	* Handshake : seams sécurité #4 (Origin RFC 6455 §10.2) + #2 (authenticator
+	* réseau) PUIS crée peer+transport, enregistre les actions, welcome + cleanup.
+	*
+	* Pipeline (cold path, 1× par connexion) :
+	*  1. Origin check via `hub.checkOrigin()` (bypass si `csrf.checkOrigin.enabled=false`).
+	*  2. Resolve authenticator via `hub.resolveAuthenticator(handshake)` (matchers
+	*     ordonnés, 1ʳᵉ qui matche capture) → `authenticate()` async.
+	*  3. Aucun match OU `enabled=false` → `ANONYMOUS_REALTIME_TOKEN`.
+	*  4. Pose le token sur `hub.peer → token` (lookup voters P6 hot-path).
+	*
+	* Échecs (close WebSocket, codes plage applicative RFC 6455 §7.4.2) :
+	*  - Origin refusée    → code 4003 (`forbidden`).
+	*  - `authenticate` throw → code 4001 (`unauthorized`).
+	*/
+	async onHandshake(ctx) {
+		const holder = ctx;
+		if (holder.__nfRealtime?.welcomed) return;
+		const conn = ctx.connection;
+		if (!conn) return;
+		const hub = getRealtimeHub();
+		const handshake = buildHandshakeFromContext(ctx);
+		if (!hub.checkOrigin(handshake.origin)) {
+			this.log(`WS realtime upgrade refused: Origin "${handshake.origin ?? "(missing)"}" not allowed`, "WARNING");
+			conn.close(4003, "origin not allowed");
+			return;
+		}
+		const authenticator = hub.resolveAuthenticator(handshake);
+		let token;
+		if (authenticator !== null && authenticator.supports(handshake)) try {
+			token = await authenticator.authenticate(handshake);
+			authenticator.onSuccess?.(handshake, token);
+		} catch (e) {
+			const err = e instanceof Error ? e : new Error(String(e));
+			try {
+				authenticator.onFailure?.(handshake, err);
+			} catch {}
+			this.log(`WS realtime auth failed (${authenticator.name}): ${err.message}`, "WARNING");
+			conn.close(4001, "unauthorized");
+			return;
+		}
+		else token = ANONYMOUS_REALTIME_TOKEN;
+		const transport = new WsConnectionTransport(conn, readBackpressureOptions(ctx.server ?? null));
+		const peerOptions = {
+			send: (frame) => {
+				let json;
+				try {
+					json = JSON.stringify(frame);
+				} catch (e) {
+					this.log(`WS realtime send: payload non sérialisable — ${e instanceof Error ? e.message : String(e)}`, "ERROR");
+					const id = frame.id;
+					if (id === void 0) return;
+					json = JSON.stringify({
+						jsonrpc: "2.0",
+						id,
+						error: {
+							code: -32603,
+							message: "internal error: non-serializable payload"
+						}
+					});
+				}
+				transport.send(json);
+			},
+			onNotification: (method, params) => this.onRealtimeNotification(ctx, method, params),
+			onError: (context, err) => this.log(`${context}: ${err instanceof Error ? err.message : String(err)}`, "ERROR")
+		};
+		peerOptions.beforeDispatch = (frame) => hub.runAuthorizer(frame, peer);
+		peerOptions.onFrameAudit = (reason, frame, auditedPeer) => {
+			if (reason !== "denied") return;
+			this.log("WS realtime frame refused by authorizer", "WARNING");
+			const f = frame;
+			if (f.id !== void 0) return;
+			const channel = f.method === "subscribe" ? typeof f.params?.channel === "string" ? f.params.channel : void 0 : typeof f.method === "string" ? f.method : void 0;
+			if (channel !== void 0) {
+				const denied = {
+					channel,
+					reason: "forbidden",
+					...deniedDetail(this.kernel?.environment, `le verrou de frame a refusé l'accès à « ${channel} » pour cette identité : vérifie les rôles ou scopes exigés par le canal (décorateur \`@RealtimeChannel(nom, { roles })\` ou clé \`realtimeChannels\` de la configuration de sécurité), et ceux que porte le jeton — le \`realtime:welcome\` te les rend`)
+				};
+				auditedPeer.notify("realtime:denied", denied);
+			}
+		};
+		const peer = new JsonRpcPeer(peerOptions);
+		hub.setTokenForPeer(peer, token);
+		transport.onMessage((raw) => {
+			let parsed;
+			try {
+				parsed = JSON.parse(raw);
+			} catch {
+				return;
+			}
+			peer.receive(parsed);
+		});
+		const allActions = {
+			...getRealtimeActions(this),
+			...this.realtimeActions()
+		};
+		for (const [name, handler] of Object.entries(allActions)) {
+			peer.register(name, handler);
+			if (hub.resolveChannelPolicy(name) === null) hub.registerChannelPolicy(name, DEFAULT_ACTION_POLICY);
+		}
+		if (this.realtimeApiRequest()) peer.register("api.request", (params) => this.invokeApiRequest(ctx, params, peer));
+		this._decoratedChannels = getRealtimeChannels(this);
+		const channelPolicies = getRealtimeChannelPolicies(this);
+		if (channelPolicies) {
+			for (const name in channelPolicies) hub.registerChannelPolicy(name, channelPolicies[name]);
+			if (hub.hasUnenforcedChannelPolicies() && !warnedUnenforcedPolicies) {
+				warnedUnenforcedPolicies = true;
+				this.log("Realtime channel policies declared but NO frame authorizer is wired — these policies are NOT enforced (a protected channel is currently open). Load @nodefony/security with a realtime zone to enforce them.", "WARNING");
+			}
+		}
+		hub.onPlatformNotice((message, severity) => this.log(message, severity));
+		hub.registerConnection(transport);
+		let revocable = null;
+		if (typeof token.isValid === "function") {
+			revocable = {
+				token,
+				close: (code, reason) => conn.close(code, reason)
+			};
+			hub.registerRevocable(revocable);
+		}
+		const broadcast = this.realtimeBroadcastChannels();
+		for (let i = 0; i < broadcast.length; i++) hub.markBroadcastChannel(broadcast[i]);
+		const decoratedInbound = getRealtimeInbound(this);
+		const overrideInbound = this.realtimeInbound();
+		const inboundMap = {
+			...decoratedInbound,
+			...overrideInbound
+		};
+		const clientLogs = hub.clientLogsLimits;
+		if (clientLogs !== null && inboundMap[PLATFORM_INBOUND.syslogUplink] === void 0) {
+			const syslog = this.syslog;
+			if (syslog) inboundMap[PLATFORM_INBOUND.syslogUplink] = createSyslogUplinkHandler({
+				syslog,
+				...clientLogs
+			});
+		}
+		const inbound = Object.keys(inboundMap).length > 0 ? inboundMap : null;
+		const state = {
+			welcomed: true,
+			peer,
+			transport,
+			channels: /* @__PURE__ */ new Map(),
+			inbound
+		};
+		holder.__nfRealtime = state;
+		ctx.once?.("onFinish", () => {
+			const liveHub = getRealtimeHub();
+			for (const [channel, sink] of state.channels) liveHub.unsubscribe(channel, sink);
+			state.channels.clear();
+			liveHub.unregisterConnection(transport);
+			if (revocable) liveHub.unregisterRevocable(revocable);
+			transport.fireClose();
+			peer.dispose("ws closed");
+			this.log("WS realtime client disconnected — cleanup done", "INFO");
+		});
+		const announcedChannels = [...this._decoratedChannels ? Object.keys(this._decoratedChannels) : [], ...this.realtimeChannels()].filter((channel) => hub.probeChannel(channel, peer));
+		const env = this.kernel?.environment;
+		const welcome = {
+			ts: Date.now(),
+			protocol: "jsonrpc-2.0",
+			channels: announcedChannels,
+			methods: peer.methods,
+			...welcomeEnv(env),
+			identity: {
+				type: token.type,
+				authenticated: token.isAuthenticated(),
+				userIdentifier: token.getUserIdentifier(),
+				roles: token.getRoles(),
+				scopes: token.getScopes()
+			}
+		};
+		peer.notify("realtime:welcome", welcome);
+		this.log("WS realtime client connected", "INFO");
+	}
+	/**
+	* Notifications entrantes : pub/sub (subscribe/unsubscribe), heartbeat (ping), puis
+	* canaux FULL-DUPLEX déclarés (entrée client → handler `realtimeInbound`).
+	*/
+	onRealtimeNotification(ctx, method, params) {
+		if (method === "subscribe") {
+			this.startChannel(ctx, params?.channel);
+			return;
+		}
+		if (method === "unsubscribe") {
+			this.stopChannel(ctx, params?.channel);
+			return;
+		}
+		const state = ctx.__nfRealtime;
+		const handler = state?.inbound?.[method];
+		if (handler) {
+			getRealtimeHub().recordInbound();
+			handler(params, (payload) => state.peer.notify(method, payload));
+		}
+	}
+	/** Abonne la connexion à un canal via le hub partagé (idempotent par connexion). */
+	startChannel(ctx, channel) {
+		if (!channel) return;
+		const state = ctx.__nfRealtime;
+		if (!state || state.channels.has(channel)) return;
+		const cap = getRealtimeHub().maxChannelsPerConnection;
+		if (cap !== null && state.channels.size >= cap) {
+			const denied = {
+				channel,
+				reason: "limit",
+				...deniedDetail(this.kernel?.environment, `plafond de ${cap} canaux par connexion atteint : désabonne-toi d'un canal avant d'en ouvrir un autre, ou relève \`maxChannelsPerConnection\` dans la configuration realtime`)
+			};
+			state.peer.notify("realtime:denied", denied);
+			this.log(`WS subscribe refusé (cap ${cap} canaux/connexion atteint) → ${channel}`, "DEBUG");
+			return;
+		}
+		const sink = (payload, serialized) => {
+			if (serialized !== void 0) state.transport.send(serialized);
+			else state.peer.notify(channel, payload);
+		};
+		let servedByPattern = false;
+		if (getRealtimeHub().subscribeClient(channel, sink, (ch, publish) => {
+			const decFactory = this._decoratedChannels?.[ch];
+			if (decFactory) return decFactory(ch, publish);
+			const dispose = this.createRealtimeChannel(ch, publish);
+			if (dispose !== null) servedByPattern = true;
+			return dispose;
+		}, (payload) => JSON.stringify(JsonRpcPeer.buildNotification(channel, payload)))) {
+			state.channels.set(channel, sink);
+			if (servedByPattern) getRealtimeHub().noticeUnguardedDynamicChannel(channel);
+			this.log(`WS subscribe → ${channel}`, "DEBUG");
+			return;
+		}
+		const floor = getRealtimeHub().isClosedBySystemFloor(channel);
+		const denied = {
+			channel,
+			reason: floor ? "forbidden" : "unknown",
+			...deniedDetail(this.kernel?.environment, floor ? `« ${channel} » appartient au namespace de plateforme, dont le plancher est CLOS tant qu'aucun module de sécurité n'est chargé — ce n'est pas ton identité qui est en cause` : `aucun producteur pour « ${channel} » sur ce pod : vérifie l'orthographe du canal, puis qu'un \`@RealtimeChannel("${channel}")\` est bien déclaré dans un controller CHARGÉ (le runtime lit \`dist/\`, pas les sources)`)
+		};
+		state.peer.notify("realtime:denied", denied);
+		this.log(floor ? `WS subscribe refusé (canal de plateforme, aucun module de sécurité) → ${channel}` : `WS subscribe refusé (aucun producteur pour ce canal) → ${channel}`, "DEBUG");
+	}
+	/**
+	* Handler de la méthode RPC `api.request {path}` — le **pont API souverain**
+	* (POC Ph.3) : résout le path porté par le message via le Router
+	* (`cleanPathOverride` — l'URL de la connexion n'est jamais mutée) puis
+	* exécute l'action SANS la rendre (`executeAction`) : la valeur nue est
+	* enveloppée `{id, result}` par le peer — snapshot ≡ GET REST par
+	* construction.
+	*
+	* Query : le `?…` du path invoqué est parsé ici (paires plates, clés répétées
+	* → array — sémantique `qs` plate) et porté par `resolver.queryOverride`
+	* (per-invocation : zéro bleed entre requêtes concurrentes de la même
+	* socket). Limitation POC assumée : syntaxe nested `a[b]=c` non supportée
+	* par le pont (doc §11 — le parse complet du transport HTTP n'est pas
+	* mutualisé tant que Ph.6 n'a pas tranché).
+	*
+	* Erreurs → {@link RpcError} (`data.status` = statut HTTP équivalent) :
+	* `-32602` params invalides, 404 path inconnu, 408 timeout d'action…
+	* Tout autre throw de l'action reste opaque (`-32603`, Zero Trust).
+	*/
+	async invokeApiRequest(ctx, params, peer) {
+		const p = params;
+		const path = p?.path;
+		if (typeof path !== "string" || path.charCodeAt(0) !== 47) throw new RpcError("api.request: params.path invalide", -32602);
+		const method = typeof p?.method === "string" ? p.method.toUpperCase() : "GET";
+		if (method !== "GET" && method !== "POST" && method !== "PUT" && method !== "PATCH" && method !== "DELETE") throw new RpcError(`api.request: méthode ${method} non supportée`, -32602);
+		const router = ctx.router;
+		if (!router) throw new RpcError("api.request: router indisponible", -32e3, { status: 500 });
+		const qIdx = path.indexOf("?");
+		const pathname = qIdx === -1 ? path : path.slice(0, qIdx);
+		const frame = ctx.beginFrame(method, path);
+		try {
+			frame?.phaseStart("resolve");
+			let resolver;
+			try {
+				resolver = router.resolve(ctx, pathname, method === "GET" ? void 0 : method);
+			} finally {
+				frame?.phaseEnd("resolve");
+			}
+			if (!resolver.resolve) throw new RpcError(`api.request: not found ${pathname}`, -32e3, { status: 404 });
+			if (frame) frame.resolver = resolver;
+			if (qIdx !== -1 && qIdx < path.length - 1) {
+				const sp = new URLSearchParams(path.slice(qIdx + 1));
+				const query = {};
+				for (const [k, v] of sp) {
+					const prev = query[k];
+					if (prev === void 0) query[k] = v;
+					else if (Array.isArray(prev)) prev.push(v);
+					else query[k] = [prev, v];
+				}
+				resolver.queryOverride = query;
+			}
+			const token = getRealtimeHub().getTokenForPeer(peer);
+			if (token.isValid) {
+				let valid;
+				frame?.phaseStart("identity");
+				try {
+					valid = await token.isValid();
+				} catch {
+					valid = false;
+				} finally {
+					frame?.phaseEnd("identity");
+				}
+				if (!valid) throw new RpcError("api.request: identité de session expirée ou invalide", -32e3, { status: 401 });
+			}
+			const renderSink = {};
+			const result = await RequestContext.run({
+				requestId: ctx.requestId,
+				scheme: ctx.scheme,
+				token,
+				user: token.getAttribute("user"),
+				userId: token.getUserIdentifier(),
+				context: ctx,
+				body: p?.body,
+				idempotencyKey: typeof p?.idempotencyKey === "string" ? p.idempotencyKey : void 0,
+				renderSink,
+				invocation: frame ?? void 0,
+				queries: frame?.profilerQueries ?? void 0
+			}, async () => {
+				frame?.phaseStart("action");
+				try {
+					const { result: actionResult } = await resolver.executeActionGuarded(void 0, true);
+					const raw = await Promise.resolve(actionResult);
+					if (renderSink.body !== void 0) {
+						const text = Buffer.isBuffer(renderSink.body) ? renderSink.body.toString("utf8") : renderSink.body;
+						try {
+							return JSON.parse(text);
+						} catch {
+							return text;
+						}
+					}
+					return raw;
+				} finally {
+					frame?.phaseEnd("action");
+				}
+			});
+			frame?.finish(200);
+			return frame ? new RpcEnvelope(result, { requestId: frame.requestId }) : result;
+		} catch (e) {
+			const status = httpStatusOfFrameError(e);
+			frame?.finish(status ?? 500, e);
+			throw toFrameRpcError(e, status, frame?.requestId);
+		} finally {
+			ctx.collectFrame(frame);
+		}
+	}
+	/** Désabonne la connexion d'un canal (le hub dispose le provider au dernier abonné). */
+	stopChannel(ctx, channel) {
+		if (!channel) return;
+		const state = ctx.__nfRealtime;
+		const sink = state?.channels.get(channel);
+		if (sink) {
+			getRealtimeHub().unsubscribe(channel, sink);
+			state.channels.delete(channel);
+			this.log(`WS unsubscribe → ${channel}`, "DEBUG");
+		}
+	}
+};
+/**
+* Construit un {@link IRealtimeHandshake} immuable depuis le `WebsocketContext`
+* de @nodefony/http — DTO neutre passé aux authenticators réseau (zéro
+* dépendance security/http côté contrat). Cold path (1× par upgrade).
+*
+* - `cookies` est aplati en `Map<string, string>` (Context expose
+*   `Record<string, Cookie>` — on ne garde que `name → value`, les options
+*   path/domain/expires ne sont pas utiles à l'authenticator).
+* - `protocols` : la liste des sous-protocoles annoncés (`Sec-WebSocket-Protocol`,
+*   csv séparé virgule selon RFC 6455 §4.1).
+*/
+function buildHandshakeFromContext(ctx) {
+	const headers = ctx.request?.headers ?? {};
+	const cookies = /* @__PURE__ */ new Map();
+	const rawCookies = ctx.cookies ?? {};
+	for (const name in rawCookies) {
+		const c = rawCookies[name];
+		if (c && typeof c.value === "string") cookies.set(name, c.value);
+	}
+	const rawProto = headers["sec-websocket-protocol"];
+	let protocols;
+	if (Array.isArray(rawProto)) protocols = rawProto.flatMap((p) => p.split(",").map((x) => x.trim()));
+	else if (typeof rawProto === "string") protocols = rawProto.split(",").map((x) => x.trim()).filter(Boolean);
+	else protocols = [];
+	return {
+		headers,
+		cookies,
+		url: handshakePath(ctx),
+		remoteAddress: ctx.remoteAddress ?? "",
+		origin: ctx.origin && ctx.origin.length > 0 ? ctx.origin : void 0,
+		protocols
+	};
+}
+/**
+* Extrait le **path** (pathname + query) de l'URL du handshake. `WebsocketContext.url`
+* est absolue (`url.format(wsUrl)`) ; un path relatif (tests/clients legacy) est
+* conservé tel quel. Jamais throw (cold path, 1× par upgrade).
+*/
+function handshakePath(ctx) {
+	const raw = ctx.url;
+	if (typeof raw !== "string" || raw.length === 0) return "/";
+	try {
+		const u = new URL(raw);
+		return u.pathname + u.search;
+	} catch {
+		return raw.charCodeAt(0) === 47 ? raw : "/";
+	}
+}
+//#endregion
+export { RealtimeController, RealtimeController as default };