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

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
@@ -112,6 +145,10 @@ import { registerBackplaneDriver } from "@nodefony/realtime";
 registerBackplaneDriver("nats", (config) => new MyNatsBackplane(config));
 ```
 
+Un bus fourni par l'application (service `realtimeBackplane`) s'arrête à la charge de
+l'application : `await shutdownRealtime(getRealtimeHub(), bus)` dans son `onTerminate`, pour que
+la fin de la présence parte avant la sortie du processus.
+
 Détail des réglages : [`docs/configuration.md`](./docs/configuration.md).
 
 ## API
@@ -129,6 +166,11 @@ 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 |
+| `shutdownRealtime` / `BACKPLANE_STOP_TIMEOUT_MS` | fn / const | Arrêt propre : fin de la présence annoncée aux pairs, puis arrêt du bus en laissant partir ce qui est émis (borné). Appelé par le module pour le bus qu'il crée ; à appeler soi-même pour un bus fourni (`realtimeBackplane`) |
+| `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 +247,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.158.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.158.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,32 @@ 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 { BACKPLANE_STOP_TIMEOUT_MS, shutdownRealtime } from "./nodefony/src/server/realtimeShutdown.js";
+import __decorate from "./_virtual/_@oxc-project_runtime@0.158.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 { DEFAULT_PRESENCE_MAX_NAMED, PRESENCE_WINDOW_MS } from "./nodefony/src/server/channelPresence.js";
+import { BackplaneEcho, openBackplaneEnvelope, sealBackplaneEnvelope } from "./nodefony/src/backplane/envelope.js";
+import { BackplanePublishQueue, DEFAULT_MAX_QUEUE_BYTES } from "./nodefony/src/backplane/publishQueue.js";
+import { BackplaneIngress } from "./nodefony/src/backplane/ingress.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 +74,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)
 	});
@@ -75,6 +84,8 @@ let Realtime = class Realtime extends Module {
 	static critical = false;
 	/** Rôle topologique du process, capté à `onCluster` (défaut mono-process). */
 	#clusterRole = "MONO";
+	/** Bus créé PAR ce module (registre de pilotes) — à lui de l'arrêter ; `null` s'il est fourni par l'application ou absent. */
+	#ownedBackplane = null;
 	constructor(kernel) {
 		super("realtime", kernel, import.meta.url, config);
 		kernel.once("onCluster", (role) => {
@@ -123,10 +134,64 @@ let Realtime = class Realtime extends Module {
 			getRealtimeHub().refreshIdentity(event.identifier);
 		});
 		await this.#wireBackplane();
+		this.kernel?.once("onTerminate", async () => {
+			const stopped = await shutdownRealtime(getRealtimeHub(), this.#ownedBackplane);
+			this.#ownedBackplane = null;
+			if (!stopped) this.log(`realtime backplane : arrêt non terminé en ${BACKPLANE_STOP_TIMEOUT_MS} ms (bus injoignable ?) — la fin de la présence peut ne pas avoir atteint les autres serveurs, qui oublieront celui-ci au délai d'oubli`, "WARNING");
+		});
 		this.#wireClusterProbe(this.#clusterRole);
 		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 +211,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) {
@@ -172,8 +240,19 @@ let Realtime = class Realtime extends Module {
 			return;
 		}
 		hub.setBackplane(backplane);
+		this.#ownedBackplane = 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 +299,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, BACKPLANE_STOP_TIMEOUT_MS, BROWSER_ORIGIN, BackplaneEcho, BackplaneIngress, BackplanePublishQueue, ChannelFrame, ClusterBackplane, ClusterProbeClient, ContractRealtimeController, ContractRealtimeControllerBase, ContractRealtimeControllerStrict, DEFAULT_MAX_QUEUE_BYTES, DEFAULT_PRESENCE_MAX_NAMED, LoopbackBackplane, MAX_CLIENT_SEVERITY, PRESENCE_WINDOW_MS, 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, shutdownRealtime };

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.");