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

package/dist/nodefony/src/cluster/ClusterProbeClient.js

@@ -1,5 +1,15 @@
+import { isRecord } from "../guards.js";
 import { CLUSTER_PROBE_CTL_KIND, CLUSTER_PROBE_KIND, CLUSTER_PROBE_SNAPSHOT_KIND, RichProcessProbe, isClusterMessage, isClusterProbeEnrich, readOrmRich } from "nodefony";
-//#region nodefony/src/cluster/ClusterProbeClient.ts
+// nodefony/src/cluster/ClusterProbeClient.ts
+/**
+* Vrai si la valeur est une liste de santés d'instance. Le snapshot vient du
+* master du cluster par IPC — un process de la MÊME application, pas le
+* réseau : on vérifie la forme qui sert de clé (`instanceId`), le reste est
+* la sonde du même code.
+*/
+function isRealtimeHealthList(value) {
+	return Array.isArray(value) && value.every((h) => isRecord(h) && typeof h.instanceId === "string");
+}
 /** Transport de production : `process.send` + `process.on("message")`. */
 const processProbeTransport = {
 	send(report) {
@@ -213,10 +223,11 @@ var ClusterProbeClient = class {
 			return;
 		}
 		if (!isClusterMessage(msg) || msg.kind !== CLUSTER_PROBE_SNAPSHOT_KIND) return;
-		const snap = msg;
-		if (Array.isArray(snap.instances)) {
-			this.#lastInstances = snap.instances;
-			this.#snapTs = typeof snap.ts === "number" ? snap.ts : Date.now();
+		if (!isRecord(msg)) return;
+		const { ts, instances } = msg;
+		if (isRealtimeHealthList(instances)) {
+			this.#lastInstances = instances;
+			this.#snapTs = typeof ts === "number" ? ts : Date.now();
 		}
 	}
 	/** Vue POD agrégée, ou `null` tant qu'aucun snapshot n'est reçu (cold start). */
@@ -280,5 +291,4 @@ function clusterProbeInstance(pid) {
 	if (!health) return null;
 	return health.instances.find((i) => i.process?.pid === pid || i.instanceId === String(pid)) ?? null;
 }
-//#endregion
 export { ClusterProbeClient, ClusterProbeClient as default, clusterProbeHealth, clusterProbeInstance, clusterProbeRequestEnrich, mergeClusterHealth, processProbeTransport, setClusterProbeClient };

package/dist/nodefony/src/guards.js

@@ -0,0 +1,40 @@
+// nodefony/src/guards.ts
+/**
+* Gardes de type internes au paquet — elles remplacent une conversion (`as`)
+* par une vérification faite à l'exécution, pour qu'une valeur d'une autre
+* forme soit écartée au lieu de traverser le code sous un type qui ment.
+*
+* Non exportées par le paquet : ce sont des détails d'implémentation.
+*/
+/**
+* Vrai si la valeur est un objet non nul : ses propriétés se lisent alors,
+* typées `unknown`, et chacune se vérifie avant usage.
+*
+* @param value - valeur venue du réseau, d'une métadonnée ou du conteneur
+* @returns `true` pour tout objet (tableau compris), `false` pour `null` et les primitives
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+/**
+* Vrai si la valeur est une fonction. Toute fonction JavaScript s'appelle avec
+* n'importe quels arguments et rend une valeur inconnue : la signature annoncée
+* ne promet rien de plus que ce que `typeof` a vérifié.
+*
+* @param value - valeur lue par son nom (métadonnée, propriété dynamique)
+* @returns `true` si la valeur est appelable
+*/
+function isCallable(value) {
+	return typeof value === "function";
+}
+/**
+* Vrai si la valeur se comporte comme une promesse (transport asynchrone) —
+* un client Redis rend une promesse, un faux transport de test rend `void`.
+*
+* @param value - retour d'un transport
+* @returns `true` si la valeur porte une méthode `then`
+*/
+function isThenable(value) {
+	return isRecord(value) && typeof value.then === "function";
+}
+export { isCallable, isRecord, isThenable };

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

@@ -1,4 +1,4 @@
-//#region nodefony/src/server/AnonymousRealtimeToken.ts
+// nodefony/src/server/AnonymousRealtimeToken.ts
 /**
 * Token realtime ANONYME — fallback Zero Trust quand aucun matcher
 * `IRealtimeAuthenticatorMatcher` ne capture le handshake.
@@ -12,7 +12,6 @@
 * token avec `isAuthenticated() === false` et appliqueront leur politique
 * (Zero Trust : zone protégée → frame refusée par `beforeDispatch`).
 */
-const anonymousAttributes = Object.freeze({});
 const ANONYMOUS_REALTIME_TOKEN = Object.freeze({
 	type: "anonymous",
 	getUserIdentifier() {
@@ -27,9 +26,6 @@ const ANONYMOUS_REALTIME_TOKEN = Object.freeze({
 	getScopes() {
 		return [];
 	},
-	getAttribute(key) {
-		return anonymousAttributes[key];
-	}
+	getAttribute(_key) {}
 });
-//#endregion
 export { ANONYMOUS_REALTIME_TOKEN, ANONYMOUS_REALTIME_TOKEN as default };

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

@@ -2,7 +2,7 @@ import { getRealtimeHub } from "./RealtimeHub.js";
 import { listBackplaneDrivers } from "../backplane/backplaneRegistry.js";
 import { clusterProbeHealth } from "../cluster/ClusterProbeClient.js";
 import { Nodefony, ProcessProbe, readOrmHealth } from "nodefony";
-//#region nodefony/src/server/RealtimeAdminApi.ts
+// nodefony/src/server/RealtimeAdminApi.ts
 const processProbe = new ProcessProbe();
 /**
 * Producteur `IAdminApi` de la **socket Nodefony** — exposé sous
@@ -83,5 +83,4 @@ function createRealtimeAdminApi() {
 		adminEndpoints: () => endpoints
 	};
 }
-//#endregion
 export { buildOwnHealth, buildRealtimeHealth, createRealtimeAdminApi };

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

@@ -1,14 +1,21 @@
+import { isRecord } from "../guards.js";
 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 { subscribedAckFrame } from "./subscribedAck.js";
 import { deniedDetail } from "./deniedDetail.js";
-import { BootConfigurationError, JsonRpcPeer, PLATFORM_INBOUND, RequestContext, RpcEnvelope, RpcError, Scope, identityHint } from "nodefony";
-import { readBackpressureOptions } from "@nodefony/http";
-import { Controller } from "@nodefony/framework";
-//#region nodefony/src/server/RealtimeController.ts
+import { BootConfigurationError, JsonRpcError, JsonRpcPeer, JsonRpcServerError, PLATFORM_INBOUND, RequestContext, RpcEnvelope, RpcError, Scope, identityHint, isJsonRpcId, isPromise, jsonRpcFailure } from "nodefony";
+import { isWebsocketContext, readBackpressureOptions, toValidationFields } from "@nodefony/http";
+import { Controller, buildContextParamArgs, getParamArgsMeta, isFrameworkRouter } from "@nodefony/framework";
+// nodefony/src/server/RealtimeController.ts
+/**
+* Une action RPC n'a ni variables de route ni URL : `@Param` et `@Query` y
+* lisent cet objet vide.
+*/
+const NO_ROUTE_PARAMS = Object.freeze({});
 /**
 * Statut HTTP-équivalent d'une erreur survenue pendant une invocation du pont.
 *
@@ -22,11 +29,12 @@ import { Controller } from "@nodefony/framework";
 */
 function httpStatusOfFrameError(e) {
 	if (e instanceof RpcError) {
-		const status = e.data?.status;
+		const status = isRecord(e.data) ? e.data.status : void 0;
 		if (typeof status === "number") return status;
-		return e.code === -32602 ? 400 : null;
+		return e.code === JsonRpcError.INVALID_PARAMS ? 400 : null;
 	}
-	const code = e.code;
+	if (e instanceof Error && toValidationFields(e) !== null) return 422;
+	const code = isRecord(e) ? e.code : void 0;
 	return typeof code === "number" && code >= 400 && code <= 599 ? code : null;
 }
 /**
@@ -40,7 +48,7 @@ function httpStatusOfFrameError(e) {
 function toFrameRpcError(e, status, requestId) {
 	if (e instanceof RpcError) {
 		if (!requestId) return e;
-		const data = typeof e.data === "object" && e.data !== null ? {
+		const data = isRecord(e.data) ? {
 			...e.data,
 			requestId
 		} : { requestId };
@@ -49,10 +57,27 @@ function toFrameRpcError(e, status, requestId) {
 	if (status !== null) {
 		const data = { status };
 		if (requestId) data.requestId = requestId;
-		return new RpcError(e instanceof Error ? e.message : String(e), -32e3, data);
+		if (status === 422 && e instanceof Error) {
+			const fields = toValidationFields(e);
+			if (fields !== null) data.fields = fields;
+		}
+		return new RpcError(e instanceof Error ? e.message : String(e), JsonRpcServerError.DEFAULT, data);
 	}
 	return e;
 }
+/** Le canal nommé par les params d'un `subscribe`/`unsubscribe` — entrée réseau. */
+function channelParam(params) {
+	return isRecord(params) && typeof params.channel === "string" ? params.channel : void 0;
+}
+/**
+* Le serveur WebSocket qui sert la connexion, ou `null` — lu une fois par
+* poignée de main pour ses réglages de contre-pression. Un `WebSocketServer`
+* porte toujours ses `options` ; aucun serveur HTTP n'en déclare.
+*/
+function webSocketServerOf(ctx) {
+	const server = ctx.server;
+	return server && "options" in server ? server : null;
+}
 let warnedUnenforcedPolicies = false;
 /**
 * RealtimeController — base d'un endpoint WebSocket temps réel SERVEUR (JSON-RPC 2.0).
@@ -62,7 +87,7 @@ let warnedUnenforcedPolicies = false;
 * — é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
+* Chaque connexion compose un `JsonRpcPeer` (le MÊME que `NodefonySocket` côté navigateur
 * — symétrie isomorphe) branché sur un {@link WsConnectionTransport}.
 *
 * Usage : le sous-classe garde sa route WS et délègue —
@@ -106,8 +131,20 @@ var RealtimeController = class extends Controller {
 	constructor(name, context) {
 		new.target.assertScope();
 		super(name, context);
+		this.#connection = isWebsocketContext(context) ? context : null;
 	}
 	/**
+	* La connexion WebSocket que sert CETTE instance — rétrécie UNE fois, ici,
+	* plutôt qu'à chaque frame.
+	*
+	* Sûr parce que l'instance est liée à sa connexion pour toute sa vie : la
+	* portée `singleton` est refusée au constructeur, et le contexte n'est posé
+	* qu'à la construction. `null` si la classe sert aussi une route HTTP et que
+	* cette instance en est issue. Le chemin de chaque frame lit ce champ au lieu
+	* de l'accesseur `context` : une lecture de champ, sans appel.
+	*/
+	#connection;
+	/**
 	* 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.
@@ -179,17 +216,17 @@ var RealtimeController = class extends Controller {
 	* 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 ».
+	* ⚠️ Cette phrase a longtemps ajouté « ce que le client 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`.
+	* `NodefonySocket.replaySubscriptions` et les deux cas « la fenêtre où le serveur
+	* écoute (welcome) » de `NodefonySocketCoverage.test.ts`.
 	*/
 	handleRealtime(message) {
-		const ctx = this.context;
-		if (!ctx) return;
+		const ctx = this.#connection;
+		if (ctx === null) throw this.outsideWebsocketError();
 		if (message == null) {
 			this.onHandshake(ctx).catch((e) => {
 				this.log(`WS realtime handshake failed: ${e instanceof Error ? e.message : String(e)}`, "ERROR");
@@ -197,7 +234,28 @@ var RealtimeController = class extends Controller {
 			});
 			return;
 		}
-		ctx.__nfRealtime?.transport.feed(message.toString());
+		const state = ctx.__nfRealtime;
+		if (typeof message === "string") {
+			state?.transport.feed(message);
+			return;
+		}
+		if (state !== void 0) this.receiveBinary(state.transport, message);
+	}
+	/**
+	* Faute de câblage : `handleRealtime` reçu par une instance qui ne sert pas
+	* une connexion WebSocket — route sans `methods: ["WEBSOCKET"]`, ou faux
+	* contexte de test sans `type`. Levée plutôt que passée sous silence : le
+	* client attendrait un welcome qui ne vient jamais. Chemin froid.
+	*/
+	outsideWebsocketError() {
+		return /* @__PURE__ */ new TypeError(`${this.constructor.name}.handleRealtime : cette instance ne sert pas une connexion WebSocket (contexte de type « ${String(this.context?.type)} »). La route doit déclarer requirements: { methods: ["WEBSOCKET"] } ; un faux contexte de test déclare type: "websocket".`);
+	}
+	receiveBinary(transport, data) {
+		if (this.onRealtimeBinary !== void 0) {
+			this.onRealtimeBinary(data);
+			return;
+		}
+		if (transport.discard("binary") === 1) this.log("WS realtime : trame binaire reçue et écartée — le protocole est du JSON-RPC texte ; pour la lire, surcharger onRealtimeBinary()", "WARNING");
 	}
 	/**
 	* **L1 — duplex serveur→client.** Émet une REQUÊTE vers le client de CETTE
@@ -215,9 +273,9 @@ var RealtimeController = class extends Controller {
 	* @throws (rejet) si le handshake n'est pas terminé (aucun peer encore).
 	*/
 	requestClient(method, params, timeoutMs) {
-		const state = this.context.__nfRealtime;
+		const state = this.coldConnState();
 		if (!state) return Promise.reject(/* @__PURE__ */ new Error("requestClient: connexion realtime non établie (welcome non émis)"));
-		return state.peer.request(method, params, timeoutMs);
+		return state.peer.requestAs(method, params, timeoutMs);
 	}
 	/**
 	* Notification CIBLÉE serveur→client (sans réponse) vers CETTE connexion, hors
@@ -226,7 +284,27 @@ var RealtimeController = class extends Controller {
 	* handshake n'est pas terminé.
 	*/
 	notifyClient(method, params) {
-		this.context.__nfRealtime?.peer.notify(method, params);
+		this.#connection?.__nfRealtime?.peer.notify(method, params);
+	}
+	/**
+	* Émet une trame BINAIRE vers CETTE connexion, sans la sérialiser — pendant
+	* sortant de {@link onRealtimeBinary}, et de `NodefonySocket.sendBinary` côté
+	* client. Même contre-pression que les frames JSON-RPC.
+	*
+	* @param data - les octets à émettre (`Uint8Array`, donc un `Buffer` aussi).
+	* @returns `false` si le handshake n'est pas terminé, la connexion fermée ou
+	*   la trame jetée par la contre-pression.
+	*/
+	sendBinaryToClient(data) {
+		return this.coldConnState()?.transport.sendBinary(data) ?? false;
+	}
+	/**
+	* État realtime de CETTE connexion, `undefined` avant le welcome — pour les
+	* chemins FROIDS (requête sortante, binaire). `notifyClient` et la réception
+	* gardent leur lecture en ligne : ils sont sur le chemin de chaque frame.
+	*/
+	coldConnState() {
+		return this.#connection?.__nfRealtime;
 	}
 	/**
 	* Handshake : seams sécurité #4 (Origin RFC 6455 §10.2) + #2 (authenticator
@@ -244,8 +322,7 @@ var RealtimeController = class extends Controller {
 	*  - `authenticate` throw → code 4001 (`unauthorized`).
 	*/
 	async onHandshake(ctx) {
-		const holder = ctx;
-		if (holder.__nfRealtime?.welcomed) return;
+		if (ctx.__nfRealtime?.welcomed) return;
 		const conn = ctx.connection;
 		if (!conn) return;
 		const hub = getRealtimeHub();
@@ -270,7 +347,7 @@ var RealtimeController = class extends Controller {
 			return;
 		}
 		else token = ANONYMOUS_REALTIME_TOKEN;
-		const transport = new WsConnectionTransport(conn, readBackpressureOptions(ctx.server ?? null));
+		const transport = new WsConnectionTransport(conn, readBackpressureOptions(webSocketServerOf(ctx)));
 		const peerOptions = {
 			send: (frame) => {
 				let json;
@@ -278,16 +355,9 @@ var RealtimeController = class extends Controller {
 					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"
-						}
-					});
+					const id = isRecord(frame) ? frame.id : void 0;
+					if (!isJsonRpcId(id)) return;
+					json = JSON.stringify(jsonRpcFailure(id, JsonRpcError.INTERNAL_ERROR, "internal error: non-serializable payload"));
 				}
 				transport.send(json);
 			},
@@ -298,9 +368,10 @@ var RealtimeController = class extends Controller {
 		peerOptions.onFrameAudit = (reason, frame, auditedPeer) => {
 			if (reason !== "denied") return;
 			this.log("WS realtime frame refused by authorizer", "WARNING");
+			if (!isRecord(frame)) return;
 			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;
+			const channel = f.method === "subscribe" ? channelParam(f.params) : typeof f.method === "string" ? f.method : void 0;
 			if (channel !== void 0) {
 				const hint = identityHint(this.kernel);
 				const denied = {
@@ -318,12 +389,13 @@ var RealtimeController = class extends Controller {
 			try {
 				parsed = JSON.parse(raw);
 			} catch {
+				if (transport.discard("malformed") === 1) this.log("WS realtime : trame texte illisible (pas du JSON) reçue et écartée", "WARNING");
 				return;
 			}
 			peer.receive(parsed);
 		});
 		const allActions = {
-			...getRealtimeActions(this),
+			...getRealtimeActions(this, this.actionParamsWrapper(ctx)),
 			...this.realtimeActions()
 		};
 		for (const [name, handler] of Object.entries(allActions)) {
@@ -378,7 +450,7 @@ var RealtimeController = class extends Controller {
 			channels: /* @__PURE__ */ new Map(),
 			inbound
 		};
-		holder.__nfRealtime = state;
+		ctx.__nfRealtime = state;
 		ctx.once("onFinish", () => {
 			const liveHub = getRealtimeHub();
 			for (const [channel, sink] of state.channels) liveHub.unsubscribe(channel, sink);
@@ -396,6 +468,7 @@ var RealtimeController = class extends Controller {
 			protocol: "jsonrpc-2.0",
 			channels: announcedChannels,
 			methods: peer.methods,
+			subscriptionAcks: true,
 			...welcomeEnv(env),
 			identity: {
 				type: token.type,
@@ -414,11 +487,11 @@ var RealtimeController = class extends Controller {
 	*/
 	onRealtimeNotification(ctx, method, params) {
 		if (method === "subscribe") {
-			this.startChannel(ctx, params?.channel);
+			this.startChannel(ctx, channelParam(params));
 			return;
 		}
 		if (method === "unsubscribe") {
-			this.stopChannel(ctx, params?.channel);
+			this.stopChannel(ctx, channelParam(params));
 			return;
 		}
 		const state = ctx.__nfRealtime;
@@ -428,11 +501,25 @@ var RealtimeController = class extends Controller {
 			handler(params, (payload) => state.peer.notify(method, payload));
 		}
 	}
+	/**
+	* Acquitte un abonnement ACCEPTÉ (`realtime:subscribed`) — le seul signal
+	* qui dise au client à partir de quand le flux du canal lui est livré.
+	*
+	* Un refus n'y passe jamais : il a `realtime:denied`. Cold path (1×/canal et
+	* par connexion).
+	*/
+	acknowledgeSubscription(state, channel) {
+		state.transport.send(subscribedAckFrame(channel));
+	}
 	/** 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;
+		if (!state) return;
+		if (state.channels.has(channel)) {
+			this.acknowledgeSubscription(state, channel);
+			return;
+		}
 		const cap = getRealtimeHub().maxChannelsPerConnection;
 		if (cap !== null && state.channels.size >= cap) {
 			const denied = {
@@ -459,6 +546,7 @@ var RealtimeController = class extends Controller {
 		}, (payload) => JSON.stringify(JsonRpcPeer.buildNotification(channel, payload)))) {
 			state.channels.set(channel, sink);
 			if (isServedByPattern()) getRealtimeHub().noticeUnguardedDynamicChannel(channel);
+			this.acknowledgeSubscription(state, channel);
 			this.log(`WS subscribe → ${channel}`, "DEBUG");
 			return;
 		}
@@ -472,6 +560,48 @@ var RealtimeController = class extends Controller {
 		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");
 	}
 	/**
+	* Enveloppe des actions `@RealtimeAction` dont un paramètre est décoré
+	* (`@Body`, `@CurrentUser`…) : l'action reçoit ses arguments comme une route,
+	* résolus par la fonction du framework et non par une copie.
+	*
+	* L'identité ne change PAS : un message est déjà traité dans la bulle
+	* `RequestContext` du handshake (`WebsocketContext` lie son écouteur par
+	* `AsyncResource.bind`), où le pare-feu a posé `user` et `token`. La bulle
+	* ouverte ici HÉRITE de ce store et n'y ajoute que la charge (`body`, que
+	* `@Body` lit dans l'ALS comme pour `api.request`) — une écriture
+	* `RequestContext.set()` dans l'action reste ainsi propre à l'appel.
+	*
+	* Une action sans paramètre décoré est rendue telle quelle : rien ne change
+	* pour elle, ni comportement ni coût. Les métadonnées se lisent ICI, une fois
+	* par connexion.
+	*
+	* @param ctx - le contexte de la connexion
+	* @returns l'enveloppe passée à {@link getRealtimeActions}
+	*/
+	actionParamsWrapper(ctx) {
+		const proto = Reflect.getPrototypeOf(this);
+		return (method, propertyKey) => {
+			if (proto === null) return method;
+			const metas = getParamArgsMeta(proto, propertyKey);
+			if (metas === null) return method;
+			return (params) => {
+				const store = {
+					requestId: ctx.requestId,
+					...RequestContext.get(),
+					body: params
+				};
+				const result = RequestContext.run(store, () => method(...buildContextParamArgs(metas, ctx, NO_ROUTE_PARAMS, NO_ROUTE_PARAMS)));
+				if (isPromise(result)) {
+					const release = () => RequestContext.release(store);
+					result.then(release, release);
+					return result;
+				}
+				RequestContext.release(store);
+				return result;
+			};
+		};
+	}
+	/**
 	* 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
@@ -491,77 +621,91 @@ var RealtimeController = class extends Controller {
 	* Tout autre throw de l'action reste opaque (`-32603`, Zero Trust).
 	*/
 	async invokeApiRequest(ctx, params, peer) {
-		const p = params;
+		const p = isRecord(params) ? params : void 0;
 		const path = p?.path;
-		if (typeof path !== "string" || path.charCodeAt(0) !== 47) throw new RpcError("api.request: params.path invalide", -32602);
+		if (typeof path !== "string" || path.charCodeAt(0) !== 47) throw new RpcError("api.request: params.path invalide", JsonRpcError.INVALID_PARAMS);
 		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);
+		if (method !== "GET" && method !== "POST" && method !== "PUT" && method !== "PATCH" && method !== "DELETE") throw new RpcError(`api.request: méthode ${method} non supportée`, JsonRpcError.INVALID_PARAMS);
 		const router = ctx.router;
-		if (!router) throw new RpcError("api.request: router indisponible", -32e3, { status: 500 });
+		if (!isFrameworkRouter(router)) throw new RpcError("api.request: router indisponible", JsonRpcServerError.DEFAULT, { status: 500 });
 		const qIdx = path.indexOf("?");
 		const pathname = qIdx === -1 ? path : path.slice(0, qIdx);
 		const frame = ctx.beginFrame(method, path);
+		let store = null;
 		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,
+			const frameStore = {
+				requestId: frame?.requestId ?? ctx.requestId,
 				scheme: ctx.scheme,
 				token,
 				user: token.getAttribute("user"),
-				userId: token.getUserIdentifier(),
 				context: ctx,
-				resolver,
+				resolver: void 0,
 				scope: ctx.container instanceof Scope ? ctx.container : void 0,
 				body: p?.body,
 				idempotencyKey: typeof p?.idempotencyKey === "string" ? p.idempotencyKey : void 0,
 				renderSink,
 				invocation: frame ?? void 0,
 				queries: frame?.profilerQueries ?? void 0
-			}, async () => {
+			};
+			store = frameStore;
+			const result = await RequestContext.run(frameStore, async () => {
+				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}`, JsonRpcServerError.DEFAULT, { status: 404 });
+				if (frame) frame.resolver = resolver;
+				frameStore.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;
+				}
+				if (token.isValid) {
+					let valid;
+					frame?.phaseStart("identity");
+					try {
+						valid = await token.isValid();
+						if (valid && token.confirmAccount) valid = await token.confirmAccount();
+					} catch {
+						valid = false;
+					} finally {
+						frame?.phaseEnd("identity");
+					}
+					if (!valid) throw new RpcError("api.request: identité de session expirée ou invalide", JsonRpcServerError.DEFAULT, { status: 401 });
+				}
 				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;
+						let body;
 						try {
-							return JSON.parse(text);
+							body = JSON.parse(text);
 						} catch {
-							return text;
+							body = text;
+						}
+						const status = renderSink.status;
+						if (status !== void 0 && status >= 400) {
+							const error = isRecord(body) ? body.error : void 0;
+							throw new RpcError(typeof error === "string" ? error : `api.request: HTTP ${status}`, JsonRpcServerError.DEFAULT, {
+								status,
+								body
+							});
 						}
+						return body;
 					}
 					return raw;
 				} finally {
@@ -575,6 +719,7 @@ var RealtimeController = class extends Controller {
 			frame?.finish(status ?? 500, e);
 			throw toFrameRpcError(e, status, frame?.requestId);
 		} finally {
+			if (store !== null) RequestContext.release(store);
 			ctx.collectFrame(frame);
 		}
 	}
@@ -639,5 +784,4 @@ function handshakePath(ctx) {
 		return raw.charCodeAt(0) === 47 ? raw : "/";
 	}
 }
-//#endregion
 export { RealtimeController, RealtimeController as default };