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

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

@@ -3,7 +3,7 @@ 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 { DEFAULT_ACTION_POLICY, getRealtimeActions, getRealtimeChannels, getRealtimeInbound } from "../../decorators/realtimeDecorators.js";
+import { getRealtimeActions, getRealtimeChannels, getRealtimeInbound, patternChannelFactory } from "../../decorators/realtimeDecorators.js";
 import { welcomeEnv } from "./welcomeEnv.js";
 import { registerControllerPolicies } from "./channelPolicyRegistry.js";
 import { welcomeIdentityOf } from "./welcomeIdentity.js";
@@ -12,7 +12,7 @@ import { imposedSubscribedAckFrame, subscribedAckFrame } from "./subscribedAck.j
 import { RealtimeConnection } from "./RealtimeConnection.js";
 import { deniedDetail, explainsDenials } from "./deniedDetail.js";
 import { ConnectionAdmission } from "./connectionAdmission.js";
-import { admitByRule, gateFrame, releaseRuleAdmission, revokeAdmission } from "./frameAdmission.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";
@@ -23,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
@@ -44,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
@@ -51,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;
@@ -268,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;
@@ -441,18 +465,19 @@ var RealtimeController = class extends Controller {
 		};
 		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 unadmitted = f.method === channel && state.inbound !== null && Object.hasOwn(state.inbound, channel) && hub.resolveChannelAdmission(channel) !== null;
-				const hint = unadmitted ? null : identityHint(this.kernel);
+				const hint = unadmitted || explained !== null ? null : identityHint(this.kernel);
 				const denied = {
 					channel,
 					reason: "forbidden",
-					...deniedDetail(this.kernel?.environment, 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}`))
+					...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);
 			}
@@ -475,9 +500,9 @@ var RealtimeController = class extends Controller {
 		};
 		for (const [name, handler] of Object.entries(allActions)) {
 			peer.register(name, handler);
-			if (!hub.hasExactChannelPolicy(name)) 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);
 		registerControllerPolicies(hub, this.constructor, null);
 		if (!warnedUnenforcedPolicies && hub.hasUnenforcedChannelPolicies()) {
@@ -489,15 +514,7 @@ var RealtimeController = class extends Controller {
 		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);
@@ -544,6 +561,14 @@ var RealtimeController = class extends Controller {
 			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 = {
@@ -593,12 +618,14 @@ var RealtimeController = class extends Controller {
 	*/
 	acknowledgeSubscription(state, channel) {
 		const connection = state.connection;
-		if (connection?.isImposing(channel) === true) {
-			state.transport.send(imposedSubscribedAckFrame(channel));
-			connection.settleImposed(channel, true);
-			return;
-		}
-		state.transport.send(subscribedAckFrame(channel));
+		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.
@@ -612,8 +639,13 @@ var RealtimeController = class extends Controller {
 			const peer = state.peer;
 			connection = new RealtimeConnection({
 				impose: (channel) => this.imposeChannel(ctx, channel),
-				end: (channel, reason) => this.endChannel(ctx, channel, reason)
-			}, () => getRealtimeHub().getTokenForPeer(peer).getIdentity?.().id ?? null);
+				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;
@@ -674,9 +706,10 @@ var RealtimeController = class extends Controller {
 	leaveChannel(state, channel) {
 		const sink = state.channels.get(channel);
 		if (sink === void 0) return false;
-		getRealtimeHub().unsubscribe(channel, sink);
+		const hub = getRealtimeHub();
+		hub.unsubscribe(channel, sink);
 		state.channels.delete(channel);
-		releaseRuleAdmission(state, channel);
+		releaseRuleAdmission(state, channel, hub);
 		return true;
 	}
 	/**
@@ -740,10 +773,7 @@ var RealtimeController = class extends Controller {
 				return;
 			}
 			admission = new ConnectionAdmission({
-				open: (ch) => {
-					this.openChannel(ctx, state, ch);
-					if (state.channels.has(ch)) admitByRule(state, ch);
-				},
+				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");
@@ -787,6 +817,12 @@ var RealtimeController = class extends Controller {
 		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;
@@ -859,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);
@@ -875,9 +912,8 @@ var RealtimeController = class extends Controller {
 		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,
@@ -897,7 +933,7 @@ 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");
 				}
@@ -908,6 +944,7 @@ var RealtimeController = class extends Controller {
 					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);
@@ -931,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;
@@ -960,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);
@@ -980,6 +1017,12 @@ var RealtimeController = class extends Controller {
 	}
 };
 /**
+* 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.
@@ -1043,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 };