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

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

@@ -1,14 +1,20 @@
-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 { AUTHENTICATE_TIMED_OUT } from "./admissionBudget.js";
 import { WsConnectionTransport } from "../transport/WsConnectionTransport.js";
+import { getRealtimeHub } from "./RealtimeHub.js";
+import { ANONYMOUS_REALTIME_TOKEN } from "./AnonymousRealtimeToken.js";
+import { getRealtimeActions, getRealtimeChannels, getRealtimeInbound, patternChannelFactory } from "../../decorators/realtimeDecorators.js";
 import { welcomeEnv } from "./welcomeEnv.js";
-import { subscribedAckFrame } from "./subscribedAck.js";
-import { deniedDetail } from "./deniedDetail.js";
-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 { registerControllerPolicies } from "./channelPolicyRegistry.js";
+import { welcomeIdentityOf } from "./welcomeIdentity.js";
+import { isRecord } from "../guards.js";
+import { imposedSubscribedAckFrame, subscribedAckFrame } from "./subscribedAck.js";
+import { RealtimeConnection } from "./RealtimeConnection.js";
+import { deniedDetail, explainsDenials } from "./deniedDetail.js";
+import { ConnectionAdmission } from "./connectionAdmission.js";
+import { gateFrame, releaseRuleAdmission, revokeAdmission } from "./frameAdmission.js";
+import { BootConfigurationError, IDENTITY_DEAD_CLOSE_CODE, JsonRpcError, JsonRpcPeer, JsonRpcServerError, ORIGIN_REFUSED_CLOSE_CODE, PLATFORM_INBOUND, RequestContext, RpcEnvelope, RpcError, Scope, TRY_AGAIN_LATER_CLOSE_CODE, TransportState, identityHint, isPromise, negotiateFrameCodec, stripTrailingSlashes } from "nodefony";
+import { isWebsocketContext, parseRequestTarget, readBackpressureOptions, toValidationFields } from "@nodefony/http";
 import { Controller, buildContextParamArgs, getParamArgsMeta, isFrameworkRouter } from "@nodefony/framework";
 // nodefony/src/server/RealtimeController.ts
 /**
@@ -17,6 +23,12 @@ import { Controller, buildContextParamArgs, getParamArgsMeta, isFrameworkRouter
 */
 const NO_ROUTE_PARAMS = Object.freeze({});
 /**
+* Préfixe de la ligne `ERROR` écrite quand la poignée de main lève (socket fermée
+* en 1011). Le harnais de test la relit pour citer l'exception : le client, lui,
+* ne reçoit que « internal error » — rien d'interne ne sort par la socket.
+*/
+const HANDSHAKE_FAILED_LOG = "WS realtime handshake failed";
+/**
 * 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
@@ -38,6 +50,24 @@ function httpStatusOfFrameError(e) {
 	return typeof code === "number" && code >= 400 && code <= 599 ? code : null;
 }
 /**
+* L'attente d'un `Retry-After` (RFC 9110 §10.2.3), en secondes : un délai
+* (`120`) tel quel, une date HTTP ramenée à l'écart avec `now` (jamais
+* négatif). Une valeur illisible, ou absente, ne dit rien : `null`.
+*
+* @param value - l'en-tête posé par l'action, s'il l'a été
+* @param now - l'instant de référence d'une date HTTP, en ms (défaut : l'horloge,
+*   lue seulement pour une date)
+* @returns les secondes à attendre, ou `null`
+*/
+function retryAfterSeconds(value, now) {
+	if (value === void 0) return null;
+	const text = value.trim();
+	if (/^\d+$/u.test(text)) return Number(text);
+	if (!/[A-Za-z]/u.test(text)) return null;
+	const at = Date.parse(text);
+	return Number.isNaN(at) ? null : Math.max(0, Math.ceil((at - (now ?? Date.now())) / 1e3));
+}
+/**
 * 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
@@ -45,18 +75,18 @@ function httpStatusOfFrameError(e) {
 * 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) {
+function toFrameRpcError(e, status, requestId, retryAfter = null) {
 	if (e instanceof RpcError) {
-		if (!requestId) return e;
-		const data = isRecord(e.data) ? {
-			...e.data,
-			requestId
-		} : { requestId };
+		if (!requestId && retryAfter === null) return e;
+		const data = isRecord(e.data) ? { ...e.data } : {};
+		if (requestId) data.requestId = requestId;
+		if (retryAfter !== null) data.retryAfter = retryAfter;
 		return new RpcError(e.message, e.code, data);
 	}
 	if (status !== null) {
 		const data = { status };
 		if (requestId) data.requestId = requestId;
+		if (retryAfter !== null) data.retryAfter = retryAfter;
 		if (status === 422 && e instanceof Error) {
 			const fields = toValidationFields(e);
 			if (fields !== null) data.fields = fields;
@@ -79,6 +109,9 @@ function webSocketServerOf(ctx) {
 	return server && "options" in server ? server : null;
 }
 let warnedUnenforcedPolicies = false;
+/** Connexions déjà prévenues du flux brut refusé sous codec binaire — alloué au premier refus. */
+let rawBinaryNoticed = null;
+let warnedNoIdentity = false;
 /**
 * RealtimeController — base d'un endpoint WebSocket temps réel SERVEUR (JSON-RPC 2.0).
 *
@@ -124,6 +157,11 @@ var RealtimeController = class extends Controller {
 		if (this.scope === "singleton") throw new BootConfigurationError(`Contrôleur temps réel « ${this.name} » déclaré @Scope("singleton") : un RealtimeController vit PAR CONNEXION — son pair JSON-RPC et notifyClient/requestClient désignent la connexion par l'instance. Retirer @Scope("singleton") : la portée d'un RealtimeController est request (une instance par connexion).`);
 	}
 	/**
+	* Le codec négocié au handshake (ADR-0022 §2), `null` hors WebSocket. Choisi par
+	* le constructeur : c'est la dernière fenêtre avant le `101`.
+	*/
+	#codec;
+	/**
 	* @param name - nom du service (celui de la classe, par convention).
 	* @param context - le contexte de la connexion.
 	* @throws BootConfigurationError si la classe se déclare singleton.
@@ -132,6 +170,28 @@ var RealtimeController = class extends Controller {
 		new.target.assertScope();
 		super(name, context);
 		this.#connection = isWebsocketContext(context) ? context : null;
+		this.#codec = this.#connection !== null ? this.#negotiateCodec(this.#connection) : null;
+	}
+	/**
+	* Choisit le codec de la connexion d'après l'offre du handshake (ADR-0022 §2)
+	* et le confie à l'admission, qui le renverra dans le `101` (RFC 6455 §4.2.2 :
+	* le sous-protocole CHOISI, jamais le premier offert). Le contrôleur WS est
+	* construit AVANT l'acceptation (`HttpKernel.handleWebsocket`) : c'est la
+	* dernière fenêtre où ce choix atteint encore le client. Le client, lui, lit
+	* le codec dans `realtime:welcome`, jamais dans cet écho.
+	*
+	* Rien n'est retenu pour un client qui n'offre aucun sous-protocole — le cas
+	* de toute connexion d'avant les codecs. Un `forward` reconstruit une
+	* instance après l'acceptation : son choix, identique, est alors ignoré.
+	*
+	* @param ctx - le contexte de la connexion.
+	* @returns le codec à annoncer dans l'accueil, puis à employer.
+	*/
+	#negotiateCodec(ctx) {
+		const offered = offeredSubprotocols(ctx.request?.headers["sec-websocket-protocol"]);
+		const codec = negotiateFrameCodec(getRealtimeHub().frameCodecs, offered);
+		if (offered.length > 0) ctx.admission?.selectSubprotocol(offered.includes(codec.protocol) ? codec.protocol : false);
+		return codec;
 	}
 	/**
 	* La connexion WebSocket que sert CETTE instance — rétrécie UNE fois, ici,
@@ -188,6 +248,9 @@ var RealtimeController = class extends Controller {
 	* 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).
+	*
+	* Typée par `Listen` (ce que le client émet, 3ᵉ générique) : un canal hors de
+	* la carte ne compile pas, et chaque handler reçoit la forme de SON canal.
 	*/
 	realtimeInbound() {
 		return {};
@@ -196,7 +259,7 @@ var RealtimeController = class extends Controller {
 	* Opt-in du **pont API** (une action, deux transports) : `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")`
+	* action que le GET REST (`socket.get("/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
@@ -229,7 +292,7 @@ var RealtimeController = class extends Controller {
 		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");
+				this.log(`${HANDSHAKE_FAILED_LOG}: ${e instanceof Error ? e.message : String(e)}`, "ERROR");
 				ctx.connection?.close(1011, "internal error");
 			});
 			return;
@@ -239,7 +302,12 @@ var RealtimeController = class extends Controller {
 			state?.transport.feed(message);
 			return;
 		}
-		if (state !== void 0) this.receiveBinary(state.transport, message);
+		if (state === void 0) return;
+		if (state.binaryCodec !== null) {
+			state.transport.feed(message);
+			return;
+		}
+		this.receiveBinary(state.transport, message);
 	}
 	/**
 	* Faute de câblage : `handleRealtime` reçu par une instance qui ne sert pas
@@ -292,11 +360,32 @@ var RealtimeController = class extends Controller {
 	* 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.
+	* Sur une connexion qui a négocié un codec BINAIRE, refusé (ADR-0022 §2) : le
+	* client y lirait ces octets comme une frame du codec. Des octets passent
+	* alors par un canal, avec ses portes.
+	*
+	* @returns `false` si le handshake n'est pas terminé, la connexion fermée, la
+	*   trame jetée par la contre-pression, ou la connexion en codec binaire.
 	*/
 	sendBinaryToClient(data) {
-		return this.coldConnState()?.transport.sendBinary(data) ?? false;
+		const state = this.coldConnState();
+		if (state === void 0) return false;
+		if (state.binaryCodec !== null) {
+			this.noticeRawBinaryUnderCodec(state);
+			return false;
+		}
+		return state.transport.sendBinary(data);
+	}
+	/**
+	* Journalise, une fois par connexion, le flux brut refusé sous codec binaire.
+	*
+	* @param state - l'état de la connexion.
+	*/
+	noticeRawBinaryUnderCodec(state) {
+		rawBinaryNoticed ??= /* @__PURE__ */ new WeakSet();
+		if (rawBinaryNoticed.has(state)) return;
+		rawBinaryNoticed.add(state);
+		this.log(`WS realtime : sendBinaryToClient refusé — la connexion parle ${state.binaryCodec?.protocol ?? "un codec binaire"}, ses trames binaires sont des frames du codec ; publier les octets sur un canal`, "WARNING");
 	}
 	/**
 	* État realtime de CETTE connexion, `undefined` avant le welcome — pour les
@@ -320,6 +409,8 @@ var RealtimeController = class extends Controller {
 	* Échecs (close WebSocket, codes plage applicative RFC 6455 §7.4.2) :
 	*  - Origin refusée    → code 4003 (`forbidden`).
 	*  - `authenticate` throw → code 4001 (`unauthorized`).
+	*  - `authenticate` sans réponse dans `authenticateTimeoutMs` → code 1013
+	*    (`try again later`, ADR-0021 §S11) : le client recule puis revient.
 	*/
 	async onHandshake(ctx) {
 		if (ctx.__nfRealtime?.welcomed) return;
@@ -329,13 +420,19 @@ var RealtimeController = class extends Controller {
 		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");
+			conn.close(ORIGIN_REFUSED_CLOSE_CODE, "origin not allowed");
 			return;
 		}
 		const authenticator = hub.resolveAuthenticator(handshake);
 		let token;
 		if (authenticator?.supports(handshake)) try {
-			token = await authenticator.authenticate(handshake);
+			const outcome = await hub.admissionBudget.authenticateWithin(authenticator.authenticate(handshake));
+			if (outcome === AUTHENTICATE_TIMED_OUT) {
+				if (hub.admissionBudget.shouldWarn("authenticate", performance.now())) this.log(`WS realtime auth (${authenticator.name}) sans réponse en ${hub.admissionBudget.authenticateTimeoutMs} ms (authenticateTimeoutMs) — connexion fermée en 1013, le client reviendra`, "WARNING");
+				conn.close(TRY_AGAIN_LATER_CLOSE_CODE, "try again later");
+				return;
+			}
+			token = outcome;
 			authenticator.onSuccess?.(handshake, token);
 		} catch (e) {
 			const err = e instanceof Error ? e : new Error(String(e));
@@ -343,41 +440,44 @@ var RealtimeController = class extends Controller {
 				authenticator.onFailure?.(handshake, err);
 			} catch {}
 			this.log(`WS realtime auth failed (${authenticator.name}): ${err.message}`, "WARNING");
-			conn.close(4001, "unauthorized");
+			conn.close(IDENTITY_DEAD_CLOSE_CODE, "unauthorized");
 			return;
 		}
 		else token = ANONYMOUS_REALTIME_TOKEN;
+		if (conn.readyState !== TransportState.OPEN) return;
 		const transport = new WsConnectionTransport(conn, readBackpressureOptions(webSocketServerOf(ctx)));
+		const codecs = hub.frameCodecs;
+		const negotiated = this.#codec ?? codecs.text;
+		const binaryCodec = negotiated === codecs.binary ? negotiated : null;
+		const outbound = ctx.outboundTracer();
 		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 = 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);
+			codec: codecs.text,
+			write: outbound === null ? (data) => transport.send(data) : (data, frame) => {
+				transport.send(data);
+				if (carriesId(frame)) outbound(data);
 			},
 			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.beforeDispatch = (frame) => {
+			if (state.admitted?.[frame.method] === true) return true;
+			return gateFrame(state, frame, hub);
+		};
 		peerOptions.onFrameAudit = (reason, frame, auditedPeer) => {
 			if (reason !== "denied") return;
-			this.log("WS realtime frame refused by authorizer", "WARNING");
+			const explained = hub.explainDenial(frame, state.peer);
+			this.log(explained === null ? "WS realtime frame refused by authorizer" : `WS realtime frame refused by authorizer: ${explained}`, "WARNING");
 			if (!isRecord(frame)) return;
 			const f = frame;
 			if (f.id !== void 0) return;
 			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 unadmitted = f.method === channel && state.inbound !== null && Object.hasOwn(state.inbound, channel) && hub.resolveChannelAdmission(channel) !== null;
+				const hint = unadmitted || explained !== null ? null : identityHint(this.kernel);
 				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` + (hint === null ? "" : `. ${hint}`))
+					...deniedDetail(this.kernel?.environment, explained ?? (unadmitted ? `« ${channel} » n'accepte d'entrée que des connexions que sa règle \`allow\` a admises : abonne-toi d'abord au canal (\`subscribe\`), puis pousse une fois l'abonnement acquitté` : `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` + (hint === null ? "" : `. ${hint}`)))
 				};
 				auditedPeer.notify("realtime:denied", denied);
 			}
@@ -387,9 +487,9 @@ var RealtimeController = class extends Controller {
 		transport.onMessage((raw) => {
 			let parsed;
 			try {
-				parsed = JSON.parse(raw);
+				parsed = peer.decode(raw);
 			} catch {
-				if (transport.discard("malformed") === 1) this.log("WS realtime : trame texte illisible (pas du JSON) reçue et écartée", "WARNING");
+				if (transport.discard("malformed") === 1) this.log(typeof raw === "string" ? "WS realtime : trame texte illisible (pas du JSON) reçue et écartée" : `WS realtime : trame binaire illisible pour ${peer.codec.protocol} reçue et écartée`, "WARNING");
 				return;
 			}
 			peer.receive(parsed);
@@ -400,32 +500,21 @@ var RealtimeController = class extends Controller {
 		};
 		for (const [name, handler] of Object.entries(allActions)) {
 			peer.register(name, handler);
-			if (hub.resolveChannelPolicy(name) === null) hub.registerChannelPolicy(name, DEFAULT_ACTION_POLICY);
+			hub.declareActionDefault(name);
 		}
-		if (this.realtimeApiRequest()) peer.register("api.request", (params) => this.invokeApiRequest(ctx, params, peer));
+		if (this.realtimeApiRequest()) peer.register("api.request", (params) => this.invokeApiRequest(ctx, params, token));
 		this._decoratedChannels = getRealtimeChannels(this);
-		const channelPolicies = getRealtimeChannelPolicies(this);
-		if (channelPolicies) {
-			for (const [name, policy] of Object.entries(channelPolicies)) hub.registerChannelPolicy(name, policy);
-			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");
-			}
+		registerControllerPolicies(hub, this.constructor, null);
+		if (!warnedUnenforcedPolicies && hub.hasUnenforcedChannelPolicies()) {
+			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");
 		}
 		const noticeSyslog = this.syslog;
 		const noticeName = this.name;
 		hub.onPlatformNotice((message, severity) => {
 			noticeSyslog?.log(message, severity, noticeName);
 		});
-		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 (const channel of broadcast) hub.markBroadcastChannel(channel);
 		const decoratedInbound = getRealtimeInbound(this);
@@ -447,20 +536,39 @@ var RealtimeController = class extends Controller {
 			welcomed: true,
 			peer,
 			transport,
+			binaryCodec,
 			channels: /* @__PURE__ */ new Map(),
-			inbound
+			inbound,
+			admission: null,
+			admitted: null,
+			retained: null,
+			connection: null
 		};
 		ctx.__nfRealtime = state;
 		ctx.once("onFinish", () => {
 			const liveHub = getRealtimeHub();
 			for (const [channel, sink] of state.channels) liveHub.unsubscribe(channel, sink);
 			state.channels.clear();
+			state.connection?.close();
+			if (state.admission !== null) {
+				state.admission.close();
+				state.admission = null;
+			}
+			hub.untrackRetainedVerdicts(state);
 			liveHub.unregisterConnection(transport);
 			if (revocable) liveHub.unregisterRevocable(revocable);
 			transport.fireClose();
 			peer.dispose("ws closed");
 			this.log("WS realtime client disconnected — cleanup done", "INFO");
 		});
+		hub.registerConnection(transport);
+		if (typeof token.isValid === "function") {
+			revocable = {
+				token,
+				close: (code, reason) => conn.close(code, reason)
+			};
+			hub.registerRevocable(revocable);
+		}
 		const announcedChannels = [...this._decoratedChannels ? Object.keys(this._decoratedChannels) : [], ...this.realtimeChannels()].filter((channel) => hub.probeChannel(channel, peer));
 		const env = this.kernel?.environment;
 		const welcome = {
@@ -470,15 +578,15 @@ var RealtimeController = class extends Controller {
 			methods: peer.methods,
 			subscriptionAcks: true,
 			...welcomeEnv(env),
-			identity: {
-				type: token.type,
-				authenticated: token.isAuthenticated(),
-				userIdentifier: token.getUserIdentifier(),
-				roles: token.getRoles(),
-				scopes: token.getScopes()
-			}
+			identity: welcomeIdentityOf(token)
 		};
+		if (binaryCodec !== null) welcome.codec = binaryCodec.protocol;
+		else if (peer.codec.bytesMarker !== void 0) welcome.bytes = peer.codec.bytesMarker;
 		peer.notify("realtime:welcome", welcome);
+		if (binaryCodec !== null) {
+			peer.codec = binaryCodec;
+			ctx.frameCodec = binaryCodec;
+		}
 		this.log("WS realtime client connected", "INFO");
 	}
 	/**
@@ -498,7 +606,7 @@ var RealtimeController = class extends Controller {
 		const handler = state?.inbound?.[method];
 		if (handler) {
 			getRealtimeHub().recordInbound();
-			handler(params, (payload) => state.peer.notify(method, payload));
+			handler(params, (payload) => state.peer.notify(method, payload), state.connection ?? this.connectionOf(ctx, state));
 		}
 	}
 	/**
@@ -509,9 +617,117 @@ var RealtimeController = class extends Controller {
 	* par connexion).
 	*/
 	acknowledgeSubscription(state, channel) {
-		state.transport.send(subscribedAckFrame(channel));
+		const connection = state.connection;
+		const imposed = connection?.isImposing(channel) === true;
+		if (state.binaryCodec !== null) state.peer.notify("realtime:subscribed", imposed ? {
+			channel,
+			imposed: true
+		} : { channel });
+		else state.transport.send(imposed ? imposedSubscribedAckFrame(channel) : subscribedAckFrame(channel));
+		if (imposed) connection.settleImposed(channel, true);
+		if (connection !== null) getRealtimeHub().presenceSubscribed(channel, connection);
+	}
+	/**
+	* Poignée publique de la connexion, créée au premier besoin (abonnement, trame entrante) puis gardée sur son état.
+	*
+	* Cold path : une fois par connexion. Les deux fermetures la relient à CE
+	* contrôleur, dont les fabriques servent ses canaux.
+	*/
+	connectionOf(ctx, state) {
+		let connection = state.connection;
+		if (connection === null) {
+			const peer = state.peer;
+			connection = new RealtimeConnection({
+				impose: (channel) => this.imposeChannel(ctx, channel),
+				end: (channel, reason) => this.endChannel(ctx, channel, reason),
+				send: (frame) => {
+					const data = frame.encodeFor(peer.codec);
+					if (data !== void 0) state.transport.send(data);
+					else if (frame.claimFailure(peer.codec)) this.log("trame partagée non encodable : non envoyée", "ERROR");
+				}
+			}, () => getRealtimeHub().getTokenForPeer(peer).getIdentity?.() ?? null);
+			state.connection = connection;
+		}
+		return connection;
 	}
-	/** Abonne la connexion à un canal via le hub partagé (idempotent par connexion). */
+	/**
+	* Abonnement imposé par le serveur (`RealtimeHub.subscribeConnection`) — la politique fixe par le verrou des trames, puis le chemin d'un `subscribe` du client, `allow` compris (ADR-0022 §6 décision 2).
+	*
+	* Le verdict est rendu à l'appelant par `RealtimeConnection.settleImposed` :
+	* à l'acquittement ({@link acknowledgeSubscription}) ou au refus
+	* ({@link refuseChannel}) — qui n'envoie alors rien au client, qui n'a rien
+	* demandé.
+	*/
+	imposeChannel(ctx, channel) {
+		const state = ctx.__nfRealtime;
+		const connection = state?.connection;
+		if (!state || !connection) return;
+		if (state.channels.has(channel)) {
+			connection.settleImposed(channel, true);
+			return;
+		}
+		const frame = {
+			method: "subscribe",
+			params: { channel }
+		};
+		if (!getRealtimeHub().runAuthorizer(frame, state.peer)) {
+			connection.settleImposed(channel, false);
+			return;
+		}
+		this.startChannel(ctx, channel);
+	}
+	/**
+	* Met fin à l'abonnement de la connexion à un canal, sur décision du serveur, et le lui notifie (`realtime:closed`).
+	*
+	* Même chemin que l'`unsubscribe` du client (hub ET état de la connexion),
+	* jamais un second : retirer le seul sink du hub laisserait l'entrée de la
+	* connexion, et le `subscribe` suivant serait acquitté sans rien rouvrir.
+	* Retire aussi la marque « admise » et le verdict retenu de ce canal.
+	*
+	* @returns `false` si la connexion n'est pas abonnée à ce canal.
+	*/
+	endChannel(ctx, channel, reason) {
+		const state = ctx.__nfRealtime;
+		if (!state || !this.leaveChannel(state, channel)) return false;
+		revokeAdmission(state, channel);
+		const closed = {
+			channel,
+			reason
+		};
+		state.peer.notify("realtime:closed", closed);
+		this.log(`WS ${reason} → ${channel}`, "DEBUG");
+		return true;
+	}
+	/**
+	* Retire la connexion d'un canal : hub, état de la connexion, admission de sa règle — le chemin UNIQUE d'une sortie, demandée par le client ou décidée par le serveur.
+	*
+	* @returns `false` si la connexion n'était pas abonnée.
+	*/
+	leaveChannel(state, channel) {
+		const sink = state.channels.get(channel);
+		if (sink === void 0) return false;
+		const hub = getRealtimeHub();
+		hub.unsubscribe(channel, sink);
+		state.channels.delete(channel);
+		releaseRuleAdmission(state, channel, hub);
+		return true;
+	}
+	/**
+	* Refus d'un abonnement : rendu à l'appelant serveur s'il s'agit d'une imposition, au client sinon — et aux deux quand le client avait aussi demandé ce canal.
+	*/
+	refuseChannel(state, channel, reason, detail, retryAfterMs) {
+		const connection = state.connection;
+		if (connection !== null && !connection.settleImposed(channel, false)) return;
+		this.denyChannel(state, channel, reason, detail, retryAfterMs);
+	}
+	/**
+	* Abonne la connexion à un canal via le hub partagé (idempotent par connexion).
+	*
+	* Un canal dont la politique déclare `allow` passe d'abord par la file
+	* d'admission de la connexion ; tout autre canal s'ouvre tout de suite, sans
+	* rien lire de plus qu'aujourd'hui (une recherche de politique au `subscribe`,
+	* trame de contrôle rare).
+	*/
 	startChannel(ctx, channel) {
 		if (!channel) return;
 		const state = ctx.__nfRealtime;
@@ -520,30 +736,97 @@ var RealtimeController = class extends Controller {
 			this.acknowledgeSubscription(state, 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);
+		const admission = state.admission;
+		if (admission?.revive(channel) === true) {
+			state.connection?.markClientAsked(channel);
+			return;
+		}
+		const hub = getRealtimeHub();
+		const cap = hub.maxChannelsPerConnection;
+		if (cap !== null && state.channels.size + (admission === null ? 0 : admission.unsettled) >= cap) {
+			this.refuseChannel(state, channel, "limit", `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`);
 			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);
+		const rule = hub.resolveChannelAdmission(channel);
+		if (rule === null) {
+			this.openChannel(ctx, state, channel);
+			return;
+		}
+		this.admitChannel(ctx, state, channel, rule, hub);
+	}
+	/**
+	* Soumet l'abonnement à la règle `allow` du canal — APRÈS le verrou des trames, qui a déjà jugé `authenticated`/`roles`/`scopes` (ADR-0022 §6, décision 1 ter, moment 2).
+	*
+	* `allow` s'applique même sans module de sécurité : il ne fait que retirer
+	* des abonnés, jamais en ajouter — l'ignorer ouvrirait `user:<id>` à tous.
+	* La file de la connexion n'est créée qu'à son premier canal à `allow`.
+	*/
+	admitChannel(ctx, state, channel, rule, hub) {
+		let admission = state.admission;
+		if (admission === null) {
+			const who = hub.getTokenForPeer(state.peer).getIdentity?.();
+			if (who === void 0) {
+				this.refuseChannel(state, channel, "forbidden", "l'authentificateur de cette connexion ne produit pas d'identité d'admission (`getIdentity`) : aucun canal à `allow` ne lui est ouvert");
+				this.log(`WS subscribe refusé : jeton sans getIdentity sur un canal à allow → ${channel}`, warnedNoIdentity ? "DEBUG" : "WARNING");
+				warnedNoIdentity = true;
+				return;
+			}
+			admission = new ConnectionAdmission({
+				open: (ch) => this.openChannel(ctx, state, ch),
+				deny: (ch, reason, detail, retryAfterMs) => {
+					this.refuseChannel(state, ch, reason, detail, retryAfterMs);
+					this.log(`WS subscribe refusé (${reason}) → ${ch}`, "DEBUG");
+				},
+				warn: (message) => this.log(message, "WARNING")
+			}, hub.admissionBudget, who, explainsDenials(this.kernel?.environment));
+			state.admission = admission;
+		}
+		admission.request(channel, rule);
+	}
+	/**
+	* Rend un refus d'abonnement observable (`realtime:denied`) — le détail ne part qu'hors production.
+	*
+	* @param detail - phrase pour le développeur ; `undefined` quand l'appelant
+	*   ne l'a pas rédigée (production).
+	*/
+	denyChannel(state, channel, reason, detail, retryAfterMs) {
+		const denied = {
+			channel,
+			reason,
+			...detail === void 0 ? {} : deniedDetail(this.kernel?.environment, detail),
+			...retryAfterMs === void 0 ? {} : { retryAfterMs }
+		};
+		state.peer.notify("realtime:denied", denied);
+	}
+	/** Ouvre l'abonnement au hub et l'acquitte — canal sans `allow`, ou admis par sa règle. */
+	openChannel(ctx, state, channel) {
+		const sink = (payload, frame) => {
+			if (frame !== void 0) {
+				const data = frame.encodeFor(state.peer.codec);
+				if (data !== void 0) {
+					state.transport.send(data);
+					return;
+				}
+				if (!frame.claimFailure(state.peer.codec)) return;
+			}
+			state.peer.notify(channel, payload);
 		};
 		let servedByPattern = false;
 		const isServedByPattern = () => servedByPattern;
 		if (getRealtimeHub().subscribeClient(channel, sink, (ch, publish) => {
 			const decFactory = this._decoratedChannels?.[ch];
 			if (decFactory) return decFactory(ch, publish);
+			if (this.createRealtimeChannel === BASE_CREATE_CHANNEL) {
+				const byPattern = patternChannelFactory(this, this._decoratedChannels, ch);
+				if (byPattern === null) return null;
+				servedByPattern = true;
+				return byPattern(ch, publish);
+			}
 			const dispose = this.createRealtimeChannel(ch, publish);
 			if (dispose !== null) servedByPattern = true;
 			return dispose;
-		}, (payload) => JSON.stringify(JsonRpcPeer.buildNotification(channel, payload)))) {
+		}, (payload) => JsonRpcPeer.buildNotification(channel, payload), this.connectionOf(ctx, state))) {
 			state.channels.set(channel, sink);
 			if (isServedByPattern()) getRealtimeHub().noticeUnguardedDynamicChannel(channel);
 			this.acknowledgeSubscription(state, channel);
@@ -551,12 +834,7 @@ var RealtimeController = class extends Controller {
 			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.refuseChannel(state, channel, floor ? "forbidden" : "unknown", 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)`);
 		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");
 	}
 	/**
@@ -617,10 +895,11 @@ var RealtimeController = class extends Controller {
 	* 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…
+	* `-32602` params invalides, 404 path inconnu, 408 timeout d'action… Un
+	* `Retry-After` posé par l'action part en `data.retryAfter` (secondes).
 	* Tout autre throw de l'action reste opaque (`-32603`, Zero Trust).
 	*/
-	async invokeApiRequest(ctx, params, peer) {
+	async invokeApiRequest(ctx, params, token) {
 		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", JsonRpcError.INVALID_PARAMS);
@@ -628,13 +907,13 @@ var RealtimeController = class extends Controller {
 		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 (!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 target = parseRequestTarget(path);
+		if (target === null) throw new RpcError("api.request: params.path invalide", JsonRpcError.INVALID_PARAMS);
+		const pathname = stripTrailingSlashes(target.pathname);
 		const frame = ctx.beginFrame(method, path);
 		let store = null;
+		const renderSink = {};
 		try {
-			const token = getRealtimeHub().getTokenForPeer(peer);
-			const renderSink = {};
 			const frameStore = {
 				requestId: frame?.requestId ?? ctx.requestId,
 				scheme: ctx.scheme,
@@ -654,17 +933,18 @@ var RealtimeController = class extends Controller {
 				frame?.phaseStart("resolve");
 				let resolver;
 				try {
-					resolver = router.resolve(ctx, pathname, method === "GET" ? void 0 : method);
+					resolver = router.resolve(ctx, pathname, 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));
+				if (target.search.length > 1) {
+					const sp = new URLSearchParams(target.search.slice(1));
 					const query = {};
 					for (const [k, v] of sp) {
+						if (Object.hasOwn(Object.prototype, k)) continue;
 						const prev = query[k];
 						if (prev === void 0) query[k] = v;
 						else if (Array.isArray(prev)) prev.push(v);
@@ -688,7 +968,7 @@ var RealtimeController = class extends Controller {
 				frame?.phaseStart("action");
 				try {
 					const { result: actionResult } = await resolver.executeActionGuarded(void 0, true);
-					const raw = await Promise.resolve(actionResult);
+					const raw = await actionResult;
 					if (renderSink.body !== void 0) {
 						const text = Buffer.isBuffer(renderSink.body) ? renderSink.body.toString("utf8") : renderSink.body;
 						let body;
@@ -717,7 +997,7 @@ var RealtimeController = class extends Controller {
 		} catch (e) {
 			const status = httpStatusOfFrameError(e);
 			frame?.finish(status ?? 500, e);
-			throw toFrameRpcError(e, status, frame?.profiled ? frame.requestId : void 0);
+			throw toFrameRpcError(e, status, frame?.profiled ? frame.requestId : void 0, status === null ? null : retryAfterSeconds(renderSink.retryAfter));
 		} finally {
 			if (store !== null) RequestContext.release(store);
 			ctx.collectFrame(frame);
@@ -728,15 +1008,29 @@ var RealtimeController = class extends Controller {
 		if (!channel) return;
 		const state = ctx.__nfRealtime;
 		if (!state) return;
-		const sink = state.channels.get(channel);
-		if (sink) {
-			getRealtimeHub().unsubscribe(channel, sink);
-			state.channels.delete(channel);
+		if (this.leaveChannel(state, channel)) {
 			this.log(`WS unsubscribe → ${channel}`, "DEBUG");
+			return;
 		}
+		state.admission?.cancel(channel);
+		state.connection?.settleImposed(channel, false);
 	}
 };
 /**
+* La fabrique par défaut de la base (`null` partout) : une classe qui la garde
+* ne surcharge pas `createRealtimeChannel`, et ses motifs décorés servent alors
+* les noms qu'ils couvrent. Lue une fois, comparée par référence au `subscribe`.
+*/
+const BASE_CREATE_CHANNEL = Reflect.get(RealtimeController.prototype, "createRealtimeChannel");
+/**
+* Une frame JSON-RPC porte-t-elle un `id` — réponse ou requête, jamais une
+* notification ? Même règle que `isNotification` du cœur (`id` absent), sur une
+* frame non typée.
+*/
+function carriesId(frame) {
+	return typeof frame === "object" && frame !== null && Reflect.get(frame, "id") !== void 0;
+}
+/**
 * 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).
@@ -747,6 +1041,18 @@ var RealtimeController = class extends Controller {
 * - `protocols` : la liste des sous-protocoles annoncés (`Sec-WebSocket-Protocol`,
 *   csv séparé virgule selon RFC 6455 §4.1).
 */
+/**
+* Les sous-protocoles offerts au handshake (`Sec-WebSocket-Protocol`, liste
+* séparée par des virgules, RFC 6455 §4.1), dans l'ordre de préférence du
+* client — la lecture unique du DTO du handshake et de la négociation du codec.
+*
+* @param raw - l'en-tête tel que Node le rend : chaîne, liste, ou absent.
+* @returns les noms, sans espaces ni entrées vides ; `[]` sans en-tête.
+*/
+function offeredSubprotocols(raw) {
+	if (raw === void 0) return [];
+	return (typeof raw === "string" ? raw.split(",") : raw.flatMap((p) => p.split(","))).map((x) => x.trim()).filter((x) => x.length > 0);
+}
 function buildHandshakeFromContext(ctx) {
 	const headers = ctx.request?.headers ?? {};
 	const cookies = /* @__PURE__ */ new Map();
@@ -755,11 +1061,7 @@ function buildHandshakeFromContext(ctx) {
 		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 = [];
+	const protocols = offeredSubprotocols(headers["sec-websocket-protocol"]);
 	return {
 		headers,
 		cookies,
@@ -784,4 +1086,4 @@ function handshakePath(ctx) {
 		return raw.charCodeAt(0) === 47 ? raw : "/";
 	}
 }
-export { RealtimeController, RealtimeController as default };
+export { HANDSHAKE_FAILED_LOG, RealtimeController, RealtimeController as default, retryAfterSeconds };