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

package/dist/nodefony/testing/backplaneConformance.js

@@ -0,0 +1,271 @@
+import { RealtimeHub } from "../src/server/RealtimeHub.js";
+import { readControlOrder } from "../src/backplane/controlOrder.js";
+import { PLATFORM_BUS_CHANNELS, PLATFORM_CHANNELS } from "nodefony";
+import { randomBytes, randomUUID } from "node:crypto";
+import assert from "node:assert/strict";
+// nodefony/testing/backplaneConformance.ts
+/**
+* Suite de conformité d'un **driver de backplane** — la définition exécutable du
+* contrat {@link IBackplane}, une seule pour tous les drivers (ADR-0022 §6,
+* décision 4).
+*
+* Un driver écrit par un tiers (journal partitionné, bus de messages…) compile et
+* démarre même mal réglé : un groupe de lecteurs partagé entre serveurs répartit
+* les messages au lieu de les diffuser, une lecture depuis le début du journal
+* rejoue des fins de partie sur des parties rouvertes. Rien ne lève, tout se perd
+* en silence. Cette suite rend ces défauts visibles : elle relie plusieurs pairs du
+* driver sur un même bus et vérifie ce que le hub tient pour acquis.
+*
+* ```ts
+* import { describe, it } from "vitest";
+* import { runBackplaneConformance } from "@nodefony/realtime/testing";
+*
+* runBackplaneConformance("mon-bus", (secret) => new MonBackplane({ url, secret }), { describe, it });
+* ```
+*
+* Le lanceur de tests est PASSÉ, jamais importé : le paquet publié ne dépend
+* d'aucun lanceur, et la suite tourne sous vitest, `node:test` ou `bun test`. Les
+* assertions passent par `node:assert`, qu'ils rapportent tous.
+*
+* @packageDocumentation
+*/
+/** Noms des cas — stables : un test négatif les désigne. */
+const BACKPLANE_CONFORMANCE_CASES = {
+	fanout: "diffusion : chaque pair reçoit TOUT, l'émetteur ne reçoit pas son écho",
+	order: "ordre par émetteur : les publications d'un pair arrivent dans l'ordre",
+	noReplay: "pas de rejeu : un pair démarré après une publication ne la reçoit pas",
+	seal: "sceau : un message non scellé ou mal scellé est refusé",
+	control: "ordres de contrôle : le canal de contrôle traverse intact",
+	reserved: "espace réservé : refusé et compté à l'entrée du hub, la diffusion passe sans revenir",
+	replaceHandler: "onMessage remplace le handler précédent",
+	stop: "stop coupe la réception, et se rappelle sans erreur"
+};
+const POLL_MS = 5;
+/** Charges de contrôle de fidélité : objet imbriqué, tableau, texte non ASCII. */
+function sample(seq) {
+	return {
+		seq,
+		text: "é — 😀",
+		list: [
+			seq,
+			"a",
+			null,
+			{ deep: true }
+		]
+	};
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function seqOf(payload) {
+	return typeof payload === "object" && payload !== null && "seq" in payload ? payload.seq : void 0;
+}
+function isFrom(payload, from) {
+	return typeof payload === "object" && payload !== null && "from" in payload && payload.from === from;
+}
+/** Attend qu'une condition tienne, ou échoue en nommant ce qui manquait (lu à l'échec). */
+async function until(done, timeoutMs, what) {
+	const deadline = Date.now() + timeoutMs;
+	while (!done()) {
+		if (Date.now() > deadline) assert.fail(`délai dépassé (${timeoutMs} ms) : ${what()}`);
+		await sleep(POLL_MS);
+	}
+}
+/**
+* Boîte de réception d'un pair, filtrée sur les canaux du cas courant. Posée
+* AVANT `start`, comme le hub le fait : un driver qui livrerait dès l'abonnement
+* (un rejeu, par exemple) est vu.
+*/
+var Inbox = class {
+	messages = [];
+	#prefix;
+	constructor(peer, prefix) {
+		this.#prefix = prefix;
+		peer.onMessage((msg) => {
+			if (msg.channel.startsWith(this.#prefix)) this.messages.push(msg);
+		});
+	}
+	payloads() {
+		return this.messages.map((m) => m.payload);
+	}
+};
+/**
+* Déclare la suite de conformité d'un driver de backplane auprès du lanceur de
+* tests de l'appelant.
+*
+* Vérifie, sur plusieurs pairs reliés au même bus : la diffusion à TOUS les pairs
+* sans écho, l'ordre par émetteur, l'absence de rejeu au démarrage, le sceau
+* (message non scellé ou mal scellé refusé), le transport des ordres de contrôle,
+* le refus de l'espace réservé à l'entrée du hub, le remplacement du handler et
+* l'arrêt.
+*
+* @param name - nom du driver, affiché dans le rapport.
+* @param makePeer - fabrique d'un pair relié au bus commun.
+* @param options - le lanceur (`describe`, `it`) et les réglages.
+*/
+function runBackplaneConformance(name, makePeer, options) {
+	const sealed = options.sealed ?? true;
+	const quietMs = options.quietMs ?? 100;
+	const timeoutMs = options.timeoutMs ?? 2e3;
+	const secret = sealed ? randomBytes(32).toString("hex") : null;
+	const C = BACKPLANE_CONFORMANCE_CASES;
+	/**
+	* Cadre d'un cas : pairs ouverts puis tous arrêtés, et un préfixe de canal
+	* unique — un bus partagé entre cas ne mélange jamais leurs messages.
+	*/
+	const scenario = (body) => {
+		return async () => {
+			const peers = [];
+			const prefix = `conformance:${randomUUID()}:`;
+			const open = async (peerSecret = secret) => {
+				const peer = await makePeer(peerSecret);
+				peers.push(peer);
+				const inbox = new Inbox(peer, prefix);
+				await peer.start();
+				return {
+					peer,
+					inbox
+				};
+			};
+			try {
+				await body(open, prefix);
+			} finally {
+				await Promise.all(peers.map(async (p) => {
+					await p.stop();
+				}));
+			}
+		};
+	};
+	options.describe(`conformité du backplane « ${name} »`, () => {
+		options.it(C.fanout, scenario(async (open, prefix) => {
+			const a = await open();
+			const b = await open();
+			const c = await open();
+			const sent = Array.from({ length: 10 }, (_, i) => sample(i));
+			for (const p of sent) a.peer.publish(`${prefix}fanout`, p);
+			await until(() => b.inbox.messages.length >= sent.length && c.inbox.messages.length >= sent.length, timeoutMs, () => `B et C attendaient ${sent.length} messages, reçus ${b.inbox.messages.length} et ${c.inbox.messages.length} — le bus répartit-il les messages entre pairs ?`);
+			b.peer.publish(`${prefix}fanout`, { seq: -1 });
+			await until(() => a.inbox.messages.some((m) => m.originId === b.peer.originId), timeoutMs, () => "A n'a pas reçu la sentinelle de B");
+			await sleep(quietMs);
+			assert.deepEqual(b.inbox.payloads(), sent, "B : charges reçues fidèlement");
+			assert.deepEqual(c.inbox.messages.filter((m) => m.originId === a.peer.originId).map((m) => m.payload), sent, "C : charges reçues fidèlement");
+			for (const m of b.inbox.messages) assert.equal(m.originId, a.peer.originId);
+			assert.ok(a.inbox.messages.every((m) => m.originId === b.peer.originId), "l'émetteur a reçu son propre écho");
+		}));
+		options.it(C.order, scenario(async (open, prefix) => {
+			const a = await open();
+			const b = await open();
+			const count = 100;
+			for (let i = 0; i < count; i += 1) a.peer.publish(`${prefix}order`, { seq: i });
+			await until(() => b.inbox.messages.length >= count, timeoutMs, () => `B attendait ${count} messages, reçus ${b.inbox.messages.length}`);
+			assert.deepEqual(b.inbox.payloads().map(seqOf), Array.from({ length: count }, (_, i) => i), "ordre d'émission perdu — la clé de partition doit être l'émetteur, jamais le canal");
+		}));
+		options.it(C.noReplay, scenario(async (open, prefix) => {
+			const a = await open();
+			const witness = await open();
+			a.peer.publish(`${prefix}replay`, { seq: 0 });
+			await until(() => witness.inbox.messages.length === 1, timeoutMs, () => "le témoin n'a pas reçu la première publication");
+			const late = await open();
+			a.peer.publish(`${prefix}replay`, { seq: 1 });
+			await until(() => late.inbox.messages.some((m) => seqOf(m.payload) === 1), timeoutMs, () => "le pair démarré en retard n'a pas reçu la publication suivante");
+			await sleep(quietMs);
+			assert.deepEqual(late.inbox.payloads().map(seqOf), [1], "rejeu au démarrage — lire à partir du dernier message, jamais depuis le début");
+		}));
+		options.it(C.seal, scenario(async (open, prefix) => {
+			if (!sealed) {
+				const { peer } = await open(null);
+				assert.notEqual(peer.describe().crossPod, true, "un bus qui quitte la machine (crossPod) doit sceller : retirer `sealed: false`");
+				return;
+			}
+			const receiver = await open();
+			const bare = await open(null);
+			const forged = await open(randomBytes(32).toString("hex"));
+			const genuine = await open();
+			bare.peer.publish(`${prefix}seal`, { from: "non scellé" });
+			forged.peer.publish(`${prefix}seal`, { from: "autre secret" });
+			genuine.peer.publish(`${prefix}seal`, { from: "scellé" });
+			await until(() => receiver.inbox.messages.some((m) => isFrom(m.payload, "scellé")), timeoutMs, () => "le message scellé du bon secret n'est pas arrivé");
+			await sleep(quietMs);
+			assert.deepEqual(receiver.inbox.payloads(), [{ from: "scellé" }], "un message non scellé ou mal scellé a été accepté");
+		}));
+		options.it(C.control, scenario(async (open, prefix) => {
+			const a = await open();
+			const b = await open();
+			const got = [];
+			b.peer.onMessage((msg) => {
+				if (msg.channel !== PLATFORM_BUS_CHANNELS.control) return;
+				const order = readControlOrder(msg.payload);
+				if (order?.channel.startsWith(prefix) === true) got.push(order);
+			});
+			const orders = [{
+				op: "close",
+				channel: `${prefix}room`
+			}, {
+				op: "evictUser",
+				channel: `${prefix}chat`,
+				user: "u-42",
+				generation: 3
+			}];
+			for (const o of orders) a.peer.publish(PLATFORM_BUS_CHANNELS.control, o);
+			await until(() => got.length >= orders.length, timeoutMs, () => `ordres de contrôle reçus : ${got.length} sur ${orders.length}`);
+			assert.deepEqual(got, orders);
+		}));
+		options.it(C.reserved, scenario(async (open, prefix) => {
+			const a = await open();
+			const b = await open();
+			const hubA = new RealtimeHub();
+			const hubB = new RealtimeHub();
+			try {
+				hubA.setBackplane(a.peer);
+				hubB.setBackplane(b.peer);
+				hubA.markBroadcastChannel(prefix);
+				hubB.markBroadcastChannel(prefix);
+				const noop = () => () => {};
+				const channel = `${prefix}room`;
+				const gotA = [];
+				const gotB = [];
+				const audit = [];
+				hubA.subscribe(channel, (p) => gotA.push(p), noop);
+				hubB.subscribe(channel, (p) => gotB.push(p), noop);
+				hubB.subscribe(PLATFORM_CHANNELS.audit, (p) => audit.push(p), noop);
+				a.peer.publish(PLATFORM_CHANNELS.audit, { forged: "faux évènement d'audit" });
+				hubA.publish(channel, { ok: 1 });
+				await until(() => gotB.length > 0, timeoutMs, () => "la diffusion déclarée n'a pas atteint le hub B");
+				await sleep(quietMs);
+				assert.deepEqual(audit, [], "un canal réservé a atteint les abonnés locaux");
+				assert.equal(hubB.probe().ingressRejectedTotal, 1, "rejet non compté");
+				assert.deepEqual(gotB, [{ ok: 1 }]);
+				assert.deepEqual(gotA, [{ ok: 1 }], "message renvoyé sur le bus (boucle)");
+			} finally {
+				hubA.clear();
+				hubB.clear();
+			}
+		}));
+		options.it(C.replaceHandler, scenario(async (open, prefix) => {
+			const a = await open();
+			const b = await open();
+			const second = [];
+			b.peer.onMessage((m) => {
+				if (m.channel.startsWith(prefix)) second.push(m.payload);
+			});
+			a.peer.publish(`${prefix}handler`, { seq: 0 });
+			await until(() => second.length > 0, timeoutMs, () => "le second handler n'a rien reçu");
+			await sleep(quietMs);
+			assert.equal(b.inbox.messages.length, 0, "l'ancien handler reçoit encore");
+			assert.deepEqual(second, [{ seq: 0 }]);
+		}));
+		options.it(C.stop, scenario(async (open, prefix) => {
+			const a = await open();
+			const b = await open();
+			const witness = await open();
+			await b.peer.stop();
+			await b.peer.stop();
+			const after = new Inbox(b.peer, prefix);
+			a.peer.publish(`${prefix}stop`, { seq: 0 });
+			await until(() => witness.inbox.messages.length > 0, timeoutMs, () => "le témoin n'a pas reçu la publication");
+			await sleep(quietMs);
+			assert.equal(after.messages.length, 0, "un pair arrêté reçoit encore");
+		}));
+	});
+}
+export { BACKPLANE_CONFORMANCE_CASES, runBackplaneConformance };

package/dist/nodefony/testing/index.js

@@ -1,5 +1,7 @@
 import { isRecord } from "../src/guards.js";
+import { createAdmissionResolver, registerControllerPolicies } from "../src/server/channelPolicyRegistry.js";
 import { getRealtimeHub } from "../src/server/RealtimeHub.js";
+import { BACKPLANE_CONFORMANCE_CASES, runBackplaneConformance } from "./backplaneConformance.js";
 import { RequestContext } from "nodefony";
 // nodefony/testing/index.ts
 /**
@@ -61,7 +63,8 @@ async function waitFor(predicate, ticks) {
 const DENIED_REASONS = {
 	forbidden: true,
 	limit: true,
-	unknown: true
+	unknown: true,
+	unavailable: true
 };
 function isDeniedReason(reason) {
 	return Object.hasOwn(DENIED_REASONS, reason);
@@ -114,6 +117,8 @@ function readDenied(params) {
 	};
 	throw new Error(`createRealtimeHarness: realtime:denied malformé — ${JSON.stringify(params)}`);
 }
+/** Compteur des vhosts de harnais — un par harnais à identité, jamais réutilisé. */
+let harnessCount = 0;
 /**
 * Monte un controller temps réel sur une fausse connexion et rend de quoi le
 * piloter.
@@ -129,9 +134,18 @@ function readDenied(params) {
 function createRealtimeHarness(create, options = {}) {
 	const hub = getRealtimeHub();
 	if (options.resetHub !== false) hub.clear();
+	let headers = options.headers ?? {};
 	if (options.identity !== void 0) {
 		const token = options.identity;
-		hub.useAuthenticator({ pattern: /.*/u }, {
+		const host = headers["host"] ?? `harness-${++harnessCount}.invalid`;
+		headers = {
+			...headers,
+			host
+		};
+		hub.useAuthenticator({
+			pattern: /.*/u,
+			host
+		}, {
 			name: "harness",
 			supports: () => true,
 			authenticate: () => Promise.resolve(token)
@@ -159,12 +173,13 @@ function createRealtimeHarness(create, options = {}) {
 	};
 	const controller = create({
 		type: "websocket",
+		outboundTracer: () => null,
 		connection,
 		once: (event, fn) => {
 			if (event === "onFinish") onFinish = fn;
 		},
 		request: {
-			headers: options.headers ?? {},
+			headers,
 			url
 		},
 		cookies: options.cookies ?? {},
@@ -172,6 +187,8 @@ function createRealtimeHarness(create, options = {}) {
 		remoteAddress: "127.0.0.1",
 		origin: options.origin ?? ""
 	});
+	const admissions = options.admissions;
+	if (admissions !== void 0) registerControllerPolicies(hub, controller.constructor, createAdmissionResolver((_key, admissionClass) => admissions.find((admission) => admission instanceof admissionClass), () => {}));
 	const bridge = controller;
 	let nextId = 1;
 	const identity = options.identity;
@@ -275,4 +292,4 @@ function createRealtimeHarness(create, options = {}) {
 		}
 	};
 }
-export { createRealtimeHarness };
+export { BACKPLANE_CONFORMANCE_CASES, createRealtimeHarness, runBackplaneConformance };

package/dist/types/index.d.ts

@@ -27,7 +27,7 @@ import RealtimeController from "./nodefony/src/server/RealtimeController.js";
 import ServerRealtimeSocket, { serverSocket } from "./nodefony/src/server/ServerRealtimeSocket.js";
 import RealtimeHub, { getRealtimeHub, SLOW_CONSUMER_BYTES, RESERVED_SYSTEM_PREFIXES, isReservedSystemChannel } from "./nodefony/src/server/RealtimeHub.js";
 import LoopbackBackplane from "./nodefony/src/backplane/LoopbackBackplane.js";
-import RedisBackplane, { createRedisServiceTransport, resolveRedisChannel, REDIS_RT_CHANNEL } from "./nodefony/src/backplane/RedisBackplane.js";
+import RedisBackplane, { createRedisServiceTransport, resolveRedisChannel, resolveRedisBytesChannel, REDIS_RT_CHANNEL } from "./nodefony/src/backplane/RedisBackplane.js";
 import { resolveBackplaneOriginId } from "./nodefony/src/backplane/originId.js";
 import ClusterBackplane, { processIpcTransport } from "./nodefony/src/backplane/ClusterBackplane.js";
 import { registerBackplaneDriver, getBackplaneDriver, listBackplaneDrivers } from "./nodefony/src/backplane/backplaneRegistry.js";
@@ -70,26 +70,53 @@ declare class Realtime extends Module<IRealtimeConfig> {
      * `onKernelBoot` court donc avant et garantit l'ordre.
      */
     onKernelBoot(): Promise<this>;
+    /**
+     * Phase `onReady` — inscrit au hub les politiques de canal de TOUS les contrôleurs temps réel connus, et résout leurs classes d'admission, avant que le moindre serveur n'écoute.
+     *
+     * Pas à `onKernelBoot` : chaque module enregistre ses contrôleurs dans SON
+     * `onBoot` (`@controllers`), et ceux d'un module listé après celui-ci n'y
+     * seraient pas encore. `onReady` passe après tous les `onBoot` et avant
+     * `initServers` : aucune poignée de main ne précède l'inscription, et un
+     * exemplaire qui n'émet que des webhooks a ses politiques comme les autres.
+     *
+     * @throws BootConfigurationError Politique illisible, `allow` sur une
+     *   action, classe d'admission sans singleton, sans `allow` ou dont une
+     *   dépendance manque — la classe et le canal sont nommés.
+     */
+    onKernelReady(): Promise<this>;
+    /**
+     * Les routes montées par le routeur du framework, vues par le contrôle des
+     * routes de contrat : chemin, méthodes, schémas d'entrée.
+     *
+     * @returns la liste, vide si le routeur du framework est absent.
+     */
+    private mountedRoutes;
 }
 export default Realtime;
 export { Realtime };
-export { RealtimeController, ServerRealtimeSocket, serverSocket, RealtimeHub, getRealtimeHub, SLOW_CONSUMER_BYTES, RESERVED_SYSTEM_PREFIXES, isReservedSystemChannel, LoopbackBackplane, ClusterBackplane, RedisBackplane, createRedisServiceTransport, resolveRedisChannel, resolveBackplaneOriginId, REDIS_RT_CHANNEL, registerBackplaneDriver, getBackplaneDriver, listBackplaneDrivers, processIpcTransport, ClusterProbeClient, setClusterProbeClient, processProbeTransport, clusterProbeHealth, clusterProbeRequestEnrich, clusterProbeInstance, mergeClusterHealth, WsConnectionTransport, createRealtimeAdminApi, buildRealtimeHealth, buildOwnHealth, RealtimeService, };
-export { ANONYMOUS_REALTIME_TOKEN } from "./nodefony/src/server/AnonymousRealtimeToken.js";
+export { RealtimeController, ServerRealtimeSocket, serverSocket, RealtimeHub, getRealtimeHub, SLOW_CONSUMER_BYTES, RESERVED_SYSTEM_PREFIXES, isReservedSystemChannel, LoopbackBackplane, ClusterBackplane, RedisBackplane, createRedisServiceTransport, resolveRedisChannel, resolveRedisBytesChannel, resolveBackplaneOriginId, REDIS_RT_CHANNEL, registerBackplaneDriver, getBackplaneDriver, listBackplaneDrivers, processIpcTransport, ClusterProbeClient, setClusterProbeClient, processProbeTransport, clusterProbeHealth, clusterProbeRequestEnrich, clusterProbeInstance, mergeClusterHealth, WsConnectionTransport, createRealtimeAdminApi, buildRealtimeHealth, buildOwnHealth, RealtimeService, };
+export { ANONYMOUS_REALTIME_TOKEN, ANONYMOUS_SUBSCRIBER_IDENTITY, } from "./nodefony/src/server/AnonymousRealtimeToken.js";
 export { defineRealtimeConfig, realtimeConfigJsonSchema, } from "./nodefony/config/defineModuleConfig.js";
 export type { IRealtimeConfig, IRealtimeConfigInput, } from "./nodefony/config/defineModuleConfig.js";
-export { RealtimeAction, RealtimeBroadcast, RealtimeChannel, RealtimeInbound, getDeclaredBroadcastPrefixes, } from "./nodefony/decorators/realtimeDecorators.js";
+export { RealtimeAction, RealtimeBroadcast, RealtimeChannel, RealtimeInbound, RealtimePolicy, getDeclaredBroadcastPrefixes, } from "./nodefony/decorators/realtimeDecorators.js";
 export type { RealtimeChannelFactory } from "./nodefony/decorators/realtimeDecorators.js";
-export type { IRealtimeController, RealtimePublish, RealtimeInboundHandler, } from "./nodefony/interfaces/IRealtimeController.js";
+export { ContractRealtimeController, ContractRealtimeControllerBase, ContractRealtimeControllerStrict, } from "./nodefony/src/server/ContractRealtimeController.js";
+export type { ContractRealtimeMethodHandlers, ContractPolicyNames, RealtimeContractOf, } from "./nodefony/src/server/ContractRealtimeController.js";
+export type { IContractRealtimeHub } from "./nodefony/src/server/RealtimeHub.js";
+export type { IRealtimeController, RealtimePublish, ContractRealtimePublish, RealtimeInboundHandler, TypedRealtimeInboundHandler, RealtimeInboundHandlers, RealtimeActionHandler, } from "./nodefony/interfaces/IRealtimeController.js";
 export type { IChannelPolicy } from "./nodefony/interfaces/IChannelPolicy.js";
 export type { IRealtimeConnectionState } from "./nodefony/interfaces/IRealtimeConnectionState.js";
+export type { IRealtimeConnection } from "./nodefony/interfaces/IRealtimeConnection.js";
 export type { IClientLogsLimits } from "./nodefony/interfaces/IClientLogsLimits.js";
 export { createSyslogUplinkHandler, BROWSER_ORIGIN, MAX_CLIENT_SEVERITY, } from "./nodefony/src/server/syslogUplink.js";
 export type { SyslogUplinkHandlerOptions, ClientSeverity, } from "./nodefony/src/server/syslogUplink.js";
-export type { ChannelSink, ChannelFactory, } from "./nodefony/src/server/RealtimeHub.js";
+export type { ChannelSink, ChannelFactory, ChannelFrameBuilder, } from "./nodefony/src/server/RealtimeHub.js";
+export { ChannelFrame } from "./nodefony/src/server/RealtimeHub.js";
 export type { IBackplane, IBackplaneMessage, BackplaneHandler, IBackplaneInfo, } from "./nodefony/interfaces/IBackplane.js";
 export type { IClusterBackplaneTransport, ClusterBackplaneEnvelope, } from "./nodefony/src/backplane/ClusterBackplane.js";
-export type { IRedisBackplaneTransport, IRedisPublisher, IRedisSubscriber, } from "./nodefony/src/backplane/RedisBackplane.js";
+export type { IRedisBackplaneTransport, IRedisPublisher, IRedisSubscriber, IRedisBytesSubscriber, } from "./nodefony/src/backplane/RedisBackplane.js";
 export type { BackplaneFactory, IBackplaneFactoryContext, } from "./nodefony/src/backplane/backplaneRegistry.js";
+export { sealBackplaneEnvelope, openBackplaneEnvelope, } from "./nodefony/src/backplane/envelope.js";
 export type { IClusterProbeTransport } from "./nodefony/src/cluster/ClusterProbeClient.js";
 export type { RawWsConnection } from "./nodefony/src/transport/WsConnectionTransport.js";
 export type { IRealtimeProbe, IRealtimeHealth, IRealtimeClusterHealth, IRealtimeChannelStat, IRealtimeConnProbe, } from "./nodefony/interfaces/IRealtimeProbe.js";

package/dist/types/nodefony/config/config.d.ts

@@ -1,6 +1,10 @@
 import { z } from "zod";
 export declare const realtimeConfigSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
+    codec: z.ZodDefault<z.ZodEnum<{
+        cbor: "cbor";
+        json: "json";
+    }>>;
     backplane: z.ZodDefault<z.ZodObject<{
         driver: z.ZodDefault<z.ZodString>;
         namespace: z.ZodOptional<z.ZodString>;
@@ -18,6 +22,11 @@ export declare const realtimeConfigSchema: z.ZodObject<{
     limits: z.ZodDefault<z.ZodObject<{
         maxChannelsPerConnection: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
     }, z.core.$strict>>;
+    authenticateTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    allowTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    maxPendingAllowsPerConnection: z.ZodDefault<z.ZodNumber>;
+    maxPendingAllowsTotal: z.ZodDefault<z.ZodNumber>;
+    publicOrigin: z.ZodOptional<z.ZodString>;
     csrf: z.ZodDefault<z.ZodObject<{
         checkOrigin: z.ZodDefault<z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;

package/dist/types/nodefony/decorators/realtimeDecorators.d.ts

@@ -19,9 +19,28 @@
  *  `undefined` (pas d'allocation), fallback sur les overrides classiques.
  */
 import "reflect-metadata";
-import type { RpcActionHandler } from "nodefony";
+import type { ChannelAdmissionClass, ChannelAllow, RpcActionHandler } from "nodefony";
 import type { RealtimePublish, RealtimeInboundHandler } from "../interfaces/IRealtimeController.js";
 import type { IChannelPolicy } from "../interfaces/IChannelPolicy.js";
+import type { ContractPolicyNames, RealtimeContractOf } from "../src/server/ContractRealtimeController.js";
+/**
+ * `allow` désigne-t-il une classe d'admission (`@injectable`) plutôt qu'une flèche ?
+ *
+ * Tranché par la métadonnée `@injectable`, jamais par le texte de la fonction
+ * (`class …`), qu'un minifieur réécrit (ADR-0021 §S10 bis).
+ *
+ * @param allow - valeur du membre `allow` d'une politique déjà validée.
+ * @returns `true` pour une classe à résoudre par l'injecteur.
+ */
+export declare function isAdmissionClass(allow: ChannelAllow): allow is ChannelAdmissionClass;
+/**
+ * Défaut d'une politique de canal, ou `null` si elle est recevable — en clair, pour que le refus au démarrage dise QUOI corriger.
+ *
+ * @param value - valeur lue sous la métadonnée des politiques (`unknown` :
+ *   `Reflect.defineMetadata` est public).
+ * @returns la raison du refus, ou `null`.
+ */
+export declare function channelPolicyDefect(value: unknown): string | null;
 /**
  * Politique appliquée à une action RPC dont l'auteur n'a rien déclaré :
  * **exiger une connexion authentifiée**. Une action est une méthode que le pair
@@ -89,6 +108,50 @@ export type RealtimeChannelFactory = (channel: string, publish: RealtimePublish)
  *   }
  */
 export declare function RealtimeAction(method: string, policy?: IChannelPolicy): MethodDecorator;
+/**
+ * Noms d'une table de politiques absents du contrat de la classe décorée —
+ * `never` quand tous y sont, ou que la classe n'a pas de contrat.
+ */
+type NamesNotInContract<P, T> = [RealtimeContractOf<T>] extends [never] ? never : Exclude<keyof P, ContractPolicyNames<RealtimeContractOf<T>>>;
+/**
+ * Contrainte posée sur la classe décorée : aucune si les noms sont tous dans le
+ * contrat ; sinon un membre `notInContract` exigé, que l'erreur affiche avec les
+ * noms fautifs.
+ */
+type PolicyNamesCheck<P, T> = [NamesNotInContract<P, T>] extends [never] ? unknown : {
+    readonly notInContract: NamesNotInContract<P, T>;
+};
+/**
+ * Décorateur de **classe** — pose les politiques d'accès d'actions ou de canaux
+ * par leur NOM, sans déclarer de handler.
+ *
+ * C'est la voie des actions servies par la table de `realtimeActions()` : cette
+ * table ne sait pas porter de politique, et un `@RealtimeAction` ajouté pour la
+ * seule politique ferait fabriquer, à chaque connexion, un handler aussitôt
+ * écrasé par la table (et contournerait l'injection de ses paramètres décorés).
+ * Ici, rien par connexion : les politiques sont écrites UNE fois, à la
+ * définition de la classe, dans le même registre que celles des décorateurs de
+ * méthode. Une action de la table sans politique garde le défaut FERMÉ
+ * (connexion authentifiée).
+ *
+ * Un nom qui porte `*` est un motif (famille de canaux), comme partout ailleurs.
+ *
+ * **Sur un contrôleur de contrat** (`extends ContractRealtimeController<C>`), le
+ * décorateur lit le contrat sur la classe qu'il décore : chaque nom doit être
+ * une méthode ou un canal de `C`, sinon la classe ne compile pas, et l'erreur
+ * nomme le fautif (`notInContract`). Le contrat ne se répète pas. Sur un
+ * contrôleur sans contrat, tout nom est accepté. Vérification à la compilation
+ * seulement : coût d'exécution nul.
+ *
+ * @param policies - nom d'action ou de canal → politique.
+ *
+ * @example
+ *   @RealtimePolicy({ "orders:quote": { roles: ["ROLE_SALES"] } })
+ *   class OrdersRt extends ContractRealtimeController<OrdersContract> { … }
+ */
+export declare function RealtimePolicy<P extends {
+    readonly [name: string]: IChannelPolicy | undefined;
+}>(policies: P): <T extends abstract new (...args: never[]) => object>(target: T & PolicyNamesCheck<P, T>) => void;
 /**
  * Décorateur **méthode** — expose un **canal pub/sub** sous le nom `channel`
  * (match EXACT, sans préfixe `:<ms>` ni regex). La méthode décorée DOIT renvoyer
@@ -164,11 +227,27 @@ export declare function getRealtimeChannels(instance: object): Record<string, Re
 /** Lecture (lazy, au handshake) du registre des canaux inbound décorés. */
 export declare function getRealtimeInbound(instance: object): Record<string, RealtimeInboundHandler> | null;
 /**
- * Lecture (lazy, au handshake) des politiques d'autorisation déclarées
- * (`@RealtimeChannel`/`@RealtimeInbound` avec opts). `null` si aucune → le
- * controller n'enregistre rien au hub (0 alloc). Donnée pure (pas de `bind` :
- * une policy n'est pas une méthode), renvoyée telle quelle pour publication au
- * hub realtime, qui l'expose à `@nodefony/security`.
+ * La classe déclare-t-elle une ACTION (`@RealtimeAction`) sous ce nom ? Sert à refuser un `allow` posé sur une action, que rien n'appliquerait.
+ *
+ * @param ctor - constructeur du contrôleur.
+ * @param name - nom d'action ou de canal.
+ */
+export declare function declaresAction(ctor: object, name: string): boolean;
+/**
+ * Politiques d'autorisation déclarées sur une CLASSE de contrôleur (`@RealtimeChannel`/`@RealtimeInbound`/`@RealtimePolicy` avec politique), validées — lues au démarrage du noyau, jamais par trame.
+ *
+ * @param ctor - constructeur du contrôleur.
+ * @returns nom de canal ou de méthode → politique, ou `null` si la classe n'en
+ *   déclare aucune (0 allocation).
+ * @throws BootConfigurationError Une politique est illisible : la classe, le
+ *   canal et le défaut sont nommés.
+ */
+export declare function getChannelPoliciesOf(ctor: object): Record<string, IChannelPolicy> | null;
+/**
+ * Politiques déclarées sur la classe d'une instance de contrôleur — même lecture que {@link getChannelPoliciesOf}.
+ *
+ * @param instance - contrôleur instancié.
+ * @returns nom → politique, ou `null` si aucune.
  */
 export declare function getRealtimeChannelPolicies(instance: object): Record<string, IChannelPolicy> | null;
 /**
@@ -205,3 +284,4 @@ export declare function getDeclaredBroadcastPrefixes(): string[];
 export declare function applyDeclaredBroadcastPrefixes(hub: {
     markBroadcastChannel(prefix: string): void;
 }): void;
+export {};