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

package/README.md

@@ -95,6 +95,39 @@ Les trois décorateurs prennent `(nom, policy?)` — la politique déclare qui a
 
 Recette complète (salon, présence, historique, upload) : [`docs/cookbook-chat.md`](./docs/cookbook-chat.md).
 
+### Typer les deux bouts — un contrat
+
+Un **contrat** déclare UNE fois ce qui circule, dans un fichier de types seuls partagé par le
+navigateur et le serveur ; le compilateur vérifie alors les deux bouts — une action oubliée, une
+charge de forme fausse ou un nom de politique mal orthographié ne compilent plus.
+
+```typescript
+// shared/chat.ts
+import type { IRealtimeContract } from "nodefony/client";
+export interface ChatContract extends IRealtimeContract {
+  serverToClient: { "chat:room": { from: string; text: string } };
+  serverMethods: { "chat:send": { in: { text: string }; out: { id: string } } };
+}
+
+// navigateur
+const socket = NodefonySocket.fromContract<ChatContract>({
+  url: "/chat/realtime",
+});
+
+// serveur
+@RealtimePolicy({ "chat:send": { roles: ["ROLE_USER"] } })
+class ChatRt extends ContractRealtimeController<ChatContract> {
+  protected realtimeActions() {
+    return {
+      "chat:send": (p: { text: string }) => ({ id: String(p.text.length) }),
+    };
+  }
+}
+```
+
+Ce que chaque bout reçoit (`Jsonify`), ce que le compilateur refuse, et le flux SSE typé par la
+même carte : [`docs/actions.md`](./docs/actions.md#-un-contrat-pour-les-deux-bouts).
+
 ## Backplane
 
 Le backplane est le fond de panier qui relie les pods entre eux. Trois drivers sont livrés avec le
@@ -129,6 +162,10 @@ Détail des réglages : [`docs/configuration.md`](./docs/configuration.md).
 | `LoopbackBackplane` / `ClusterBackplane` / `RedisBackplane` | classes | Les 3 drivers natifs |
 | `registerBackplaneDriver` / `getBackplaneDriver` / `listBackplaneDrivers` | functions | Registre ouvert de drivers |
 | `IBackplane` | interface | Contrat d'un fond de panier |
+| `ContractRealtimeController<C>` | classe | Base d'un contrôleur qui implémente un contrat (`realtimeActions()` complète si le contrat déclare des `serverMethods`, rien sinon) |
+| `getRealtimeHub<C>()` | fonction | Le hub lu par le contrat (`IContractRealtimeHub<C>`) : `publish` d'un service vérifié ; sans paramètre, le hub libre |
+| `ContractRealtimePublish<C>` | type | Le `publish` d'une fabrique de canal, typé par le contrat |
+| `RealtimePolicy` | décorateur | Politiques d'accès par nom, posées sur la classe ; noms vérifiés contre le contrat |
 | `IRealtimeAuthenticator` / `IRealtimeToken` / `IRealtimeHandshake` | interfaces | Seams sécurité du handshake |
 | `ANONYMOUS_REALTIME_TOKEN` | const | Jeton anonyme gelé — fallback Zero Trust |
 
@@ -205,6 +242,19 @@ seul avec un canal ouvert à tous.
 | `closes` / `notices`                        | Fermetures serveur (4003…) · avertissements de plateforme       |
 | `close()` / `dispose()`                     | Ferme la socket · ferme puis remet le hub à zéro                |
 
+Un canal gardé par une **classe d'admission** (`@RealtimeChannel("room:*", { allow: RoomAdmission })`)
+se résout au démarrage, dans le conteneur du noyau — que le harnais n'a pas. Le test la construit
+avec le MÊME service que le controller, et la passe par `admissions` ; sans elle, `connect()` jette
+(code 1011), comme un démarrage qui ne la trouverait pas :
+
+```ts
+const members = new RoomService(createTestModule());
+const alice = createRealtimeHarness((ctx) => new RoomRealtime(ctx, members), {
+  identity: createTestIdentity({ identifier: "alice" }),
+  admissions: [new RoomAdmission(members)],
+});
+```
+
 `nodefony create controller --kind realtime` pose ce test à côté du controller qu'il génère.
 
 ## Doc complète

package/dist/_virtual/{_@oxc-project_runtime@0.155.0 → _@oxc-project_runtime@0.157.0}/helpers/esm/decorate.js

@@ -1,4 +1,4 @@
-// \0@oxc-project+runtime@0.155.0/helpers/esm/decorate.js
+// \0@oxc-project+runtime@0.157.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);

package/dist/index.js

@@ -2,23 +2,28 @@ import config from "./nodefony/config/config.js";
 import { buildRealtimeConfig, defineRealtimeConfig, realtimeConfigJsonSchema } from "./nodefony/config/defineModuleConfig.js";
 import { isCallable, isRecord } from "./nodefony/src/guards.js";
 import { realtimeBackplaneDownNotice, realtimeLocalOnlyNotice } from "./nodefony/src/backplane/bootNotices.js";
-import resolveBackplaneOriginId from "./nodefony/src/backplane/originId.js";
-import { LoopbackBackplane } from "./nodefony/src/backplane/LoopbackBackplane.js";
-import { ANONYMOUS_REALTIME_TOKEN } from "./nodefony/src/server/AnonymousRealtimeToken.js";
-import { RESERVED_SYSTEM_PREFIXES, RealtimeHub, SLOW_CONSUMER_BYTES, getRealtimeHub, isReservedSystemChannel } from "./nodefony/src/server/RealtimeHub.js";
-import { RealtimeAction, RealtimeBroadcast, RealtimeChannel, RealtimeInbound, getDeclaredBroadcastPrefixes } from "./nodefony/decorators/realtimeDecorators.js";
 import { RealtimeService } from "./nodefony/src/service/RealtimeService.js";
-import { BROWSER_ORIGIN, MAX_CLIENT_SEVERITY, createSyslogUplinkHandler } from "./nodefony/src/server/syslogUplink.js";
-import { WsConnectionTransport } from "./nodefony/src/transport/WsConnectionTransport.js";
 import { RealtimeController } from "./nodefony/src/server/RealtimeController.js";
+import { createAdmissionResolver, registerControllerPolicies } from "./nodefony/src/server/channelPolicyRegistry.js";
+import { assertContractRoutes, readContractRoutes } from "./nodefony/src/server/contractRoutes.js";
 import { ServerRealtimeSocket, serverSocket } from "./nodefony/src/server/ServerRealtimeSocket.js";
-import { REDIS_RT_CHANNEL, RedisBackplane, createRedisServiceTransport, isRedisPublisher, isRedisSubscriber, resolveRedisChannel } from "./nodefony/src/backplane/RedisBackplane.js";
+import { ChannelFrame, RESERVED_SYSTEM_PREFIXES, RealtimeHub, SLOW_CONSUMER_BYTES, getRealtimeHub, isReservedSystemChannel } from "./nodefony/src/server/RealtimeHub.js";
+import { LoopbackBackplane } from "./nodefony/src/backplane/LoopbackBackplane.js";
+import { REDIS_RT_CHANNEL, RedisBackplane, createRedisServiceTransport, isRedisBytesSubscriber, isRedisPublisher, isRedisSubscriber, resolveRedisBytesChannel, resolveRedisChannel } from "./nodefony/src/backplane/RedisBackplane.js";
+import resolveBackplaneOriginId from "./nodefony/src/backplane/originId.js";
 import { ClusterBackplane, processIpcTransport } from "./nodefony/src/backplane/ClusterBackplane.js";
 import { getBackplaneDriver, listBackplaneDrivers, registerBackplaneDriver } from "./nodefony/src/backplane/backplaneRegistry.js";
 import { ClusterProbeClient, clusterProbeHealth, clusterProbeInstance, clusterProbeRequestEnrich, mergeClusterHealth, processProbeTransport, setClusterProbeClient } from "./nodefony/src/cluster/ClusterProbeClient.js";
+import { WsConnectionTransport } from "./nodefony/src/transport/WsConnectionTransport.js";
 import { buildOwnHealth, buildRealtimeHealth, createRealtimeAdminApi } from "./nodefony/src/server/RealtimeAdminApi.js";
-import __decorate from "./_virtual/_@oxc-project_runtime@0.155.0/helpers/esm/decorate.js";
+import __decorate from "./_virtual/_@oxc-project_runtime@0.157.0/helpers/esm/decorate.js";
+import { ANONYMOUS_REALTIME_TOKEN, ANONYMOUS_SUBSCRIBER_IDENTITY } from "./nodefony/src/server/AnonymousRealtimeToken.js";
+import { RealtimeAction, RealtimeBroadcast, RealtimeChannel, RealtimeInbound, RealtimePolicy, getDeclaredBroadcastPrefixes } from "./nodefony/decorators/realtimeDecorators.js";
+import { ContractRealtimeController, ContractRealtimeControllerBase, ContractRealtimeControllerStrict } from "./nodefony/src/server/ContractRealtimeController.js";
+import { BROWSER_ORIGIN, MAX_CLIENT_SEVERITY, createSyslogUplinkHandler } from "./nodefony/src/server/syslogUplink.js";
+import { openBackplaneEnvelope, sealBackplaneEnvelope } from "./nodefony/src/backplane/envelope.js";
 import { IDENTITY_CHANGED_EVENT, Module, services, withTimeout } from "nodefony";
+import { getRouteSchema, isFrameworkRouter } from "@nodefony/framework";
 // index.ts
 /**
 * @nodefony/realtime — Couche realtime serveur Nodefony.
@@ -65,7 +70,7 @@ registerBackplaneDriver(RedisBackplane.driver, (ctx) => {
 	const namespace = ctx.config.backplane.namespace ?? ctx.module.kernel?.projectName;
 	const secret = ctx.config.backplane.secret ?? null;
 	if (!secret) ctx.module.log(`driver "${RedisBackplane.driver}" : bus NON AUTHENTIFIÉ — les messages ne sont pas scellés. Quiconque écrit dans ce Redis publie sur les canaux de tous les pods. Poser backplane.secret (ou NF_REALTIME_BACKPLANE_SECRET, ≥ 32 caractères, identique sur tous les pods) pour sceller le transport.`, "WARNING");
-	return new RedisBackplane(createRedisServiceTransport(publisher, subscriber), ctx.originId, resolveRedisChannel(namespace), secret, {
+	return new RedisBackplane(createRedisServiceTransport(publisher, subscriber, isRedisBytesSubscriber(subscriber) ? subscriber : void 0), ctx.originId, resolveRedisChannel(namespace), secret, {
 		maxQueueBytes: ctx.config.backplane.maxQueueBytes,
 		onNotice: (message, severity) => ctx.module.log(message, severity)
 	});
@@ -127,6 +132,55 @@ let Realtime = class Realtime extends Module {
 		return 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.
+	*/
+	async onKernelReady() {
+		if (!this.config.enabled) return this;
+		const hub = getRealtimeHub();
+		const container = this.kernel?.container;
+		const resolveAdmission = createAdmissionResolver((key) => key === null ? void 0 : container?.get(key), (message) => this.log(message, "INFO"));
+		const controllers = Module.controllers;
+		let mounted = null;
+		for (const key in controllers) {
+			const ctor = controllers[key];
+			if (ctor !== void 0 && ctor.prototype instanceof RealtimeController) {
+				registerControllerPolicies(hub, ctor, resolveAdmission);
+				const table = readContractRoutes(ctor);
+				if (table !== null) {
+					mounted ??= this.mountedRoutes();
+					assertContractRoutes(ctor.name, table, mounted);
+				}
+			}
+		}
+		return 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.
+	*/
+	mountedRoutes() {
+		const router = this.kernel?.container?.get("router");
+		if (!isFrameworkRouter(router)) return [];
+		const all = router.getRoutes("");
+		return (Array.isArray(all) ? all : []).flatMap((route) => route.path === void 0 ? [] : [{
+			path: route.path,
+			methods: route.methodsSet,
+			schema: route.controller !== void 0 && route.classMethod !== void 0 ? getRouteSchema(route.controller.prototype, route.classMethod) : null
+		}]);
+	}
+	/**
 	* Sélectionne et branche le backplane via le **registre de drivers** — résout
 	* `config.backplane.driver` (chaîne) → fabrique, SANS connaître aucun nom de
 	* driver en dur (pas de chaîne de `if`). La fabrique construit l'instance (ou
@@ -146,7 +200,10 @@ let Realtime = class Realtime extends Module {
 	async #wireBackplane() {
 		const config = this.config;
 		const hub = getRealtimeHub();
-		if (hub.backplane !== null) return;
+		if (hub.backplane !== null) {
+			this.#logBroadcastPrefixes(hub);
+			return;
+		}
 		const driverName = config.backplane.driver;
 		const factory = getBackplaneDriver(driverName);
 		if (!factory) {
@@ -174,6 +231,16 @@ let Realtime = class Realtime extends Module {
 		hub.setBackplane(backplane);
 		const info = backplane.describe();
 		this.log(`realtime backplane  driver=${info.driver} kind=${info.kind} origin=${info.originId} cross-pod=${info.crossPod ? "yes" : "no"}` + (info.channel ? ` channel=${info.channel}` : ""), "INFO");
+		this.#logBroadcastPrefixes(hub);
+	}
+	/**
+	* Dit au démarrage QUELS canaux traversent le bus : les autres restent sur ce
+	* serveur, et un abonné d'un autre serveur n'en reçoit rien — sans erreur.
+	* Lu une fois, à côté de la ligne du backplane (D5, ADR-0022 §6).
+	*/
+	#logBroadcastPrefixes(hub) {
+		const prefixes = hub.broadcastPrefixes();
+		this.log(`realtime diffusion entre serveurs : ${prefixes.map((p) => `${p}*`).join(", ")} — tout autre canal reste sur ce serveur (\`@RealtimeBroadcast\` pour le diffuser ; oublis comptés par la sonde, \`localOnlyTotal\`)`, "INFO");
 	}
 	/**
 	* `backplane.start()` borné par un **timeout** — un driver réseau (Redis/Kafka)
@@ -220,4 +287,4 @@ let Realtime = class Realtime extends Module {
 };
 Realtime = __decorate([services([RealtimeService])], Realtime);
 var realtime_default = Realtime;
-export { ANONYMOUS_REALTIME_TOKEN, BROWSER_ORIGIN, ClusterBackplane, ClusterProbeClient, LoopbackBackplane, MAX_CLIENT_SEVERITY, REDIS_RT_CHANNEL, RESERVED_SYSTEM_PREFIXES, Realtime, RealtimeAction, RealtimeBroadcast, RealtimeChannel, RealtimeController, RealtimeHub, RealtimeInbound, RealtimeService, RedisBackplane, SLOW_CONSUMER_BYTES, ServerRealtimeSocket, WsConnectionTransport, buildOwnHealth, buildRealtimeHealth, clusterProbeHealth, clusterProbeInstance, clusterProbeRequestEnrich, createRealtimeAdminApi, createRedisServiceTransport, createSyslogUplinkHandler, realtime_default as default, defineRealtimeConfig, getBackplaneDriver, getDeclaredBroadcastPrefixes, getRealtimeHub, isReservedSystemChannel, listBackplaneDrivers, mergeClusterHealth, processIpcTransport, processProbeTransport, realtimeConfigJsonSchema, registerBackplaneDriver, resolveBackplaneOriginId, resolveRedisChannel, serverSocket, setClusterProbeClient };
+export { ANONYMOUS_REALTIME_TOKEN, ANONYMOUS_SUBSCRIBER_IDENTITY, BROWSER_ORIGIN, ChannelFrame, ClusterBackplane, ClusterProbeClient, ContractRealtimeController, ContractRealtimeControllerBase, ContractRealtimeControllerStrict, LoopbackBackplane, MAX_CLIENT_SEVERITY, REDIS_RT_CHANNEL, RESERVED_SYSTEM_PREFIXES, Realtime, RealtimeAction, RealtimeBroadcast, RealtimeChannel, RealtimeController, RealtimeHub, RealtimeInbound, RealtimePolicy, RealtimeService, RedisBackplane, SLOW_CONSUMER_BYTES, ServerRealtimeSocket, WsConnectionTransport, buildOwnHealth, buildRealtimeHealth, clusterProbeHealth, clusterProbeInstance, clusterProbeRequestEnrich, createRealtimeAdminApi, createRedisServiceTransport, createSyslogUplinkHandler, realtime_default as default, defineRealtimeConfig, getBackplaneDriver, getDeclaredBroadcastPrefixes, getRealtimeHub, isReservedSystemChannel, listBackplaneDrivers, mergeClusterHealth, openBackplaneEnvelope, processIpcTransport, processProbeTransport, realtimeConfigJsonSchema, registerBackplaneDriver, resolveBackplaneOriginId, resolveRedisBytesChannel, resolveRedisChannel, sealBackplaneEnvelope, serverSocket, setClusterProbeClient };

package/dist/nodefony/config/config.js

@@ -1,3 +1,4 @@
+import { realtimeConnectSource } from "../src/service/publicOrigin.js";
 import { z } from "zod";
 // nodefony/config/config.ts
 /**
@@ -50,10 +51,16 @@ const clientLogsSchema = z.strictObject({
 const csrfSchema = z.strictObject({ checkOrigin: checkOriginSchema.default(() => checkOriginSchema.parse({})) }).describe("Protections CSRF natives realtime (origin check upgrade WS).");
 const realtimeConfigSchema = z.strictObject({
 	enabled: z.boolean().default(true).describe("Active le module realtime au boot. Recommandation prod : true. false = module chargé mais inerte (registry, mais aucun hub/listener actif)."),
+	codec: z.enum(["json", "cbor"]).default("json").describe("Codec binaire des frames, accordé aux clients qui l'offrent (ADR-0022 §2). `json` (défaut) : JSON-RPC texte seul, le fil d'avant les codecs. `cbor` : le serveur charge le codec CBOR (RFC 8949) au démarrage et l'accorde à tout client qui offre `nodefony.jsonrpc.cbor.v1` ; les autres restent en texte, avec la convention d'octets `$bytes`. Les octets d'une charge voyagent alors sans base64, et toute trame binaire d'une connexion CBOR est une frame : le flux brut (`onRealtimeBinary`, `sendBinaryToClient`) n'y sert plus. Env : `NF_REALTIME_CODEC` — `NF_REALTIME_CODEC=json` remet le fil en texte pour le lire dans le navigateur, une exception de débogage : en texte, la taille des trames et la contre-pression changent.").meta({ env: "NF_REALTIME_CODEC" }),
 	backplane: backplaneSchema.default(() => backplaneSchema.parse({})),
 	cluster: clusterSchema.default(() => clusterSchema.parse({})),
 	slowConsumer: slowConsumerSchema.default(() => slowConsumerSchema.parse({})),
 	limits: limitsSchema.default(() => limitsSchema.parse({})),
+	authenticateTimeoutMs: z.number().int().positive().max(2147483647).default(1e4).describe("Délai (ms) de l'authentification à la poignée de main WebSocket. Dépassé, la connexion est fermée en 1013 (« try again later ») : le client recule puis revient, et une identité arrivée après coup est ignorée (`authenticateTimedOutTotal`). Jamais 4001 : un refus définitif arrêterait un client légitime à chaque panne de base. Défaut 10000 : l'authentification relit souvent une session en base ou une clé distante ; 10 s couvrent une base chargée, et au-delà retenir la connexion ne l'authentifierait pas plus vite — elle occuperait seulement une place."),
+	allowTimeoutMs: z.number().int().positive().max(2147483647).default(5e3).describe("Délai (ms) de la règle d'admission `allow` d'un canal, compté depuis la réception du `subscribe`, attente en file comprise. Dépassé, l'abonné reçoit `realtime:denied` motif `unavailable` et réessaie ; un verdict arrivé après coup est ignoré, jamais une admission. Le minuteur n'est armé que si `allow` rend une promesse. Défaut 5000 : une lecture en base saine répond en millisecondes, 5 s couvrent une base chargée sans laisser un écran vide au-delà de ce qu'un humain attend."),
+	maxPendingAllowsPerConnection: z.number().int().positive().default(8).describe("Appels de `allow` en vol pour UNE connexion. Au-delà, la demande d'abonnement ATTEND son tour (jamais refusée : le rejeu au `welcome` renvoie tous les canaux d'un coup). Défaut 8 : assez pour ouvrir plusieurs canaux en parallèle, assez peu pour qu'une connexion ne monopolise pas le pool de connexions à la base (souvent 10)."),
+	maxPendingAllowsTotal: z.number().int().positive().default(512).describe("Appels de `allow` en vol pour TOUT l'exemplaire. Au-delà, la demande reçoit `unavailable` sans appel (`allowSaturatedTotal`). Défaut 512 : à ce niveau la base est déjà l'étranglement ; empiler davantage d'appels n'admettrait personne plus vite et retarderait la reprise."),
+	publicOrigin: z.string().refine((value) => realtimeConnectSource(value) !== null, { message: "publicOrigin : une origine nue est attendue — schéma ws, wss, http ou https, hôte, port facultatif ; ni chemin, ni joker (ex. `wss://rt.example.com`)." }).optional().describe("Origine où la socket est servie quand ce n'est PAS celle de la page (autre domaine, autre port), par ex. `wss://rt.example.com`. Le module la déclare lui-même dans `connect-src` de la politique de contenu ; sans elle, le navigateur bloque la connexion. Inutile quand la socket est sur l'origine de la page (cas courant) : `connect-src 'self'` la couvre déjà. `https://` est accepté et déclaré en `wss://`. Ne dit pas qui peut OUVRIR la socket : c'est `csrf.checkOrigin.allowList`. Env : `NF_REALTIME_PUBLIC_ORIGIN` (l'origine distingue des déploiements).").meta({ env: "NF_REALTIME_PUBLIC_ORIGIN" }),
 	csrf: csrfSchema.default(() => csrfSchema.parse({})),
 	clientLogs: clientLogsSchema.default(() => clientLogsSchema.parse({}))
 }).describe("Configuration de @nodefony/realtime.");

package/dist/nodefony/decorators/realtimeDecorators.js

@@ -1,4 +1,5 @@
 import { isCallable, isRecord } from "../src/guards.js";
+import { BootConfigurationError, Injector } from "nodefony";
 import "reflect-metadata";
 // nodefony/decorators/realtimeDecorators.ts
 /** Clés de métadonnées posées sur le constructor de la classe controller. */
@@ -20,26 +21,77 @@ function readMetadataMap(key, ctor) {
 function isStringArray(value) {
 	return Array.isArray(value) && value.every((v) => typeof v === "string");
 }
-/** Vrai si la valeur a la forme d'une {@link IChannelPolicy}. */
-function isChannelPolicy(value) {
-	if (!isRecord(value)) return false;
-	const { authenticated, roles, scopes } = value;
-	return (authenticated === void 0 || typeof authenticated === "boolean") && (roles === void 0 || isStringArray(roles)) && (scopes === void 0 || isStringArray(scopes));
+/**
+* Clés qu'une politique de canal peut porter — toute autre est refusée : une
+* faute de frappe (`role`, `alow`) dans une règle de sécurité ne s'ignore pas.
+*/
+const POLICY_KEYS = /* @__PURE__ */ new Set([
+	"authenticated",
+	"roles",
+	"scopes",
+	"allow",
+	"anonymous"
+]);
+/**
+* `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.
+*/
+function isAdmissionClass(allow) {
+	return Injector.isInjectable(allow);
 }
-/** Vrai si chaque entrée du registre est une {@link IChannelPolicy}. */
-function isPolicyMap(map) {
-	for (const name in map) if (!isChannelPolicy(map[name])) return false;
-	return true;
+/**
+* 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`.
+*/
+function channelPolicyDefect(value) {
+	if (!isRecord(value)) return "la politique n'est pas un objet";
+	for (const key of Object.keys(value)) if (!POLICY_KEYS.has(key)) return `clé inconnue « ${key} » (clés admises : ${[...POLICY_KEYS].join(", ")})`;
+	const { authenticated, roles, scopes, allow, anonymous } = value;
+	if (authenticated !== void 0 && typeof authenticated !== "boolean") return "« authenticated » doit être un booléen";
+	if (roles !== void 0 && !isStringArray(roles)) return "« roles » doit être un tableau de chaînes";
+	if (scopes !== void 0 && !isStringArray(scopes)) return "« scopes » doit être un tableau de chaînes";
+	if (anonymous !== void 0 && typeof anonymous !== "boolean") return "« anonymous » doit être un booléen";
+	if (allow === void 0) return anonymous === void 0 ? null : "« anonymous » n'a de sens qu'avec « allow »";
+	if (typeof allow !== "function") return "« allow » doit être une fonction ou une classe @injectable";
+	if (anonymous === true && authenticated === true) return "« anonymous: true » contredit « authenticated: true »";
+	const proto = Reflect.get(allow, "prototype");
+	if (!Injector.isInjectable(allow) && isRecord(proto) && typeof proto.allow === "function") return `« allow » est une classe (${allow.name}) sans @injectable`;
+	return null;
+}
+/**
+* Exige que chaque entrée du registre soit une politique recevable — sinon le démarrage s'arrête en nommant la classe, le canal et le défaut.
+*
+* Une politique illisible ne se laisse jamais tomber : sans elle, le canal
+* s'ouvrirait à qui la politique fermait (fail-closed).
+*/
+function assertPolicyMap(owner, map) {
+	for (const name in map) {
+		const defect = channelPolicyDefect(map[name]);
+		if (defect !== null) throw new BootConfigurationError(`${owner} : politique du canal temps réel « ${name} » refusée — ${defect}`);
+	}
 }
 /** Méthode de l'instance que désigne une entrée de registre, ou `undefined`. */
 function methodOf(instance, prop) {
 	return typeof prop === "string" || typeof prop === "symbol" ? Reflect.get(instance, prop) : void 0;
 }
+/** La politique porte-t-elle au moins une clé propre non `undefined` ? */
+function hasDefinedKey(policy) {
+	for (const key of Object.keys(policy)) if (Reflect.get(policy, key) !== void 0) return true;
+	return false;
+}
 /** Libération d'un canal dont la fabrique décorée n'en a rendu aucune. */
 const NO_DISPOSE = () => {};
 /** Enregistre (idempotent) une politique non vide sous son nom de canal/méthode. */
 function definePolicy(ctor, name, policy) {
-	if (!policy || policy.authenticated === void 0 && policy.roles === void 0 && policy.scopes === void 0) return;
+	if (!policy || !hasDefinedKey(policy)) return;
 	const map = { ...readMetadataMap(POLICIES_KEY, ctor) };
 	map[name] = policy;
 	Reflect.defineMetadata(POLICIES_KEY, map, ctor);
@@ -112,6 +164,39 @@ function RealtimeAction(method, policy) {
 	};
 }
 /**
+* 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> { … }
+*/
+function RealtimePolicy(policies) {
+	return function(target) {
+		for (const [name, policy] of Object.entries(policies)) definePolicy(target, name, policy);
+	};
+}
+/**
 * 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
 * un `dispose: () => void` (la base le mémorise et l'appelle au dernier
@@ -228,19 +313,40 @@ function getRealtimeInbound(instance) {
 	return out;
 }
 /**
-* 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.
 */
-function getRealtimeChannelPolicies(instance) {
-	const map = readMetadataMap(POLICIES_KEY, instance.constructor);
+function declaresAction(ctor, name) {
+	const map = readMetadataMap(ACTIONS_KEY, ctor);
+	return map !== void 0 && Object.prototype.hasOwnProperty.call(map, name);
+}
+/**
+* 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.
+*/
+function getChannelPoliciesOf(ctor) {
+	const map = readMetadataMap(POLICIES_KEY, ctor);
 	if (map === void 0) return null;
-	if (!isPolicyMap(map)) throw new TypeError(`${instance.constructor.name} : politique de canal temps réel illisible`);
+	assertPolicyMap(typeof ctor === "function" ? ctor.name : "(contrôleur)", map);
 	return map;
 }
 /**
+* 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.
+*/
+function getRealtimeChannelPolicies(instance) {
+	return getChannelPoliciesOf(instance.constructor);
+}
+/**
 * Préfixes de canaux **broadcast** déclarés statiquement, tous controllers
 * confondus. Rempli à l'IMPORT des classes (le décorateur s'exécute au
 * chargement du module), donc connu **avant** tout trafic. `Set` : la
@@ -287,4 +393,4 @@ function getDeclaredBroadcastPrefixes() {
 function applyDeclaredBroadcastPrefixes(hub) {
 	for (const prefix of declaredBroadcastPrefixes) hub.markBroadcastChannel(prefix);
 }
-export { DEFAULT_ACTION_POLICY, RealtimeAction, RealtimeBroadcast, RealtimeChannel, RealtimeInbound, applyDeclaredBroadcastPrefixes, getDeclaredBroadcastPrefixes, getRealtimeActions, getRealtimeChannelPolicies, getRealtimeChannels, getRealtimeInbound };
+export { DEFAULT_ACTION_POLICY, RealtimeAction, RealtimeBroadcast, RealtimeChannel, RealtimeInbound, RealtimePolicy, applyDeclaredBroadcastPrefixes, channelPolicyDefect, declaresAction, getChannelPoliciesOf, getDeclaredBroadcastPrefixes, getRealtimeActions, getRealtimeChannelPolicies, getRealtimeChannels, getRealtimeInbound, isAdmissionClass };

package/dist/nodefony/interfaces/IRealtimeConnection.js

@@ -0,0 +1 @@
+export {};

package/dist/nodefony/src/backplane/ClusterBackplane.js

@@ -1,5 +1,5 @@
 import resolveBackplaneOriginId from "./originId.js";
-import { CLUSTER_RT_KIND } from "nodefony";
+import { CLUSTER_IPC_ADVANCED, CLUSTER_IPC_SERIALIZATION_ENV, CLUSTER_RT_KIND } from "nodefony";
 // nodefony/src/backplane/ClusterBackplane.ts
 /**
 * Transport de production : `process.send` (émission) + `process.on("message")`
@@ -13,6 +13,9 @@ const processIpcTransport = {
 	},
 	onReceive(cb) {
 		process.on("message", (msg) => cb(msg));
+	},
+	carriesBytes() {
+		return process.channel !== void 0 && process.env[CLUSTER_IPC_SERIALIZATION_ENV] === CLUSTER_IPC_ADVANCED;
 	}
 };
 /**
@@ -51,14 +54,24 @@ var ClusterBackplane = class ClusterBackplane {
 	#transport;
 	#handler = null;
 	#started = false;
+	/**
+	* Récepteur posé sur le transport — une fois pour la vie de l'instance : le
+	* transport de production (`process.on("message")`) ne sait pas le retirer, et
+	* le reposer à chaque redémarrage doublerait chaque message reçu.
+	*/
+	#listening = false;
+	/** Vrai une fois {@link enableBytes} constaté que le canal porte les octets. */
+	#bytes = false;
 	constructor(transport = processIpcTransport, originId = resolveBackplaneOriginId()) {
 		this.#transport = transport;
 		this.originId = originId;
 	}
-	/** Branche la réception IPC. Idempotent. */
+	/** Branche la réception IPC. Idempotent, et redémarrable après {@link stop}. */
 	start() {
 		if (this.#started) return;
 		this.#started = true;
+		if (this.#listening) return;
+		this.#listening = true;
 		this.#transport.onReceive((msg) => this.#ingress(msg));
 	}
 	/**
@@ -77,8 +90,19 @@ var ClusterBackplane = class ClusterBackplane {
 	onMessage(handler) {
 		this.#handler = handler;
 	}
+	/**
+	* Les octets traversent l'IPC tels quels quand le canal est en clonage
+	* structuré : aucun codec n'est appliqué, l'argument est ignoré.
+	*
+	* @returns `true` si le transport constate un canal `advanced`.
+	*/
+	enableBytes() {
+		this.#bytes = this.#transport.carriesBytes?.() === true;
+		return this.#bytes;
+	}
 	/** Tri + anti-echo + délégation au handler. Robuste : ignore tout message non-realtime. */
 	#ingress(msg) {
+		if (!this.#started) return;
 		if (!isEnvelope(msg)) return;
 		if (msg.originId === this.originId) return;
 		this.#handler?.({
@@ -87,7 +111,10 @@ var ClusterBackplane = class ClusterBackplane {
 			originId: msg.originId
 		});
 	}
-	/** Détache le handler. Le listener du transport prod (`process`) survit au process. */
+	/**
+	* Coupe la réception et détache le handler. Le récepteur du transport survit
+	* (`process` ne le retire pas) mais ne livre plus rien jusqu'au prochain {@link start}.
+	*/
 	stop() {
 		this.#handler = null;
 		this.#started = false;
@@ -97,7 +124,8 @@ var ClusterBackplane = class ClusterBackplane {
 			driver: ClusterBackplane.driver,
 			kind: "ipc",
 			originId: this.originId,
-			crossPod: false
+			crossPod: false,
+			...this.#bytes && { bytes: true }
 		};
 	}
 };