@nodefony/realtime 10.0.0-alpha.1

package/README.md

@@ -0,0 +1,207 @@
+# @nodefony/realtime
+
+Couche realtime serveur Nodefony — **la Socket Nodefony** : hub WebSocket fan-out, protocole
+JSON-RPC 2.0 (peer isomorphe partagé avec le client du cœur) et backplane cluster interchangeable
+(`loopback`, `cluster` IPC, `redis`) ouvert aux drivers écrits par l'application.
+
+> 📖 **La doc complète est dans [`docs/`](./docs/)** — vulgarisée, avec analogies physiques,
+> schémas et exemples. Lis-la dans Studio (`/nodefony/documentation` → section Realtime) pour le
+> rendu Mermaid + admonitions + blocs de code copiables.
+
+## Installation
+
+Workspace npm — déjà inclus dans `nodefony-core`. Dans une application, le module se déclare dans
+le manifeste `modules` de `nodefony.config.ts` :
+
+```typescript
+import { defineConfig, use } from "nodefony";
+
+export default defineConfig(() => ({
+  modules: [
+    "@nodefony/http",
+    "@nodefony/framework",
+    use("@nodefony/realtime", { backplane: { driver: "loopback" } }),
+  ],
+}));
+```
+
+## Usage côté client
+
+Le client navigateur **n'est pas dans ce module** : il vit dans le cœur, importable sans dépendre
+du serveur (isomorphisme). Le subpath est **`nodefony/client`**.
+
+```typescript
+import { RealtimeClient } from "nodefony/client";
+
+const socket = RealtimeClient.shared({ url: "wss://app.com/realtime" });
+
+await socket.subscribe("chat:room");
+socket.on("chat:room", (msg) => console.log(msg));
+
+// RPC bidirectionnel
+const pong = await socket.request("nodefony:kernel:ping");
+```
+
+En React, les hooks sont sous `nodefony/react` (`useNodefony`, `useNodefonyChannel`…).
+
+## Usage côté serveur
+
+Un controller realtime est un controller Nodefony ordinaire qui étend la classe abstraite
+`RealtimeController`. Le protocole (poignée de main, découpage des frames, abonnements, nettoyage)
+est porté par la base ; le controller ne déclare que son métier.
+
+```typescript
+import { controller, route } from "@nodefony/framework";
+import {
+  RealtimeController,
+  RealtimeChannel,
+  RealtimeInbound,
+} from "@nodefony/realtime";
+import type { RealtimePublish } from "@nodefony/realtime";
+import type { ContextType } from "@nodefony/http";
+
+@controller("/chat")
+class ChatController extends RealtimeController {
+  constructor(context: ContextType) {
+    super("chat", context);
+  }
+
+  /** La porte : l'URL WebSocket que le navigateur ouvre. */
+  @route("chat-realtime", {
+    path: "/realtime",
+    requirements: { methods: ["WEBSOCKET"] },
+  })
+  async realtime(message: string | Buffer | null): Promise<void> {
+    this.handleRealtime(message);
+  }
+
+  /** Un canal sortant : appelé au PREMIER abonné, rend sa fonction de nettoyage. */
+  @RealtimeChannel("chat:room", { authenticated: true })
+  room(_channel: string, _publish: RealtimePublish): () => void {
+    return () => {};
+  }
+
+  /** Un canal entrant : le client pousse vers le serveur. Rien n'est ouvert par défaut. */
+  @RealtimeInbound("chat:send", { authenticated: true })
+  onSend(params: unknown, reply: (payload: unknown) => void): void {
+    // `params` vient du réseau : le valider avant toute chose.
+    reply({ ok: true });
+  }
+}
+```
+
+Les trois décorateurs prennent `(nom, policy?)` — la politique déclare qui a le droit
+(`authenticated`, `roles`). Une action sans politique reste fermée par défaut.
+
+Recette complète (salon, présence, historique, upload) : [`docs/cookbook-chat.md`](./docs/cookbook-chat.md).
+
+## Backplane
+
+Le backplane est le fond de panier qui relie les pods entre eux. Trois drivers sont livrés avec le
+module, et le registre est ouvert : une application peut brancher le sien.
+
+| Driver              | Usage                                                            |
+| ------------------- | ---------------------------------------------------------------- |
+| `loopback` (défaut) | mono-process — aucun transport, fan-out local                    |
+| `cluster`           | multi-worker sur une machine (IPC Node, `nodefony cluster -w N`) |
+| `redis`             | multi-hôte (pub/sub cross-pod, enveloppe scellée HMAC)           |
+
+```typescript
+import { registerBackplaneDriver } from "@nodefony/realtime";
+
+registerBackplaneDriver("nats", (config) => new MyNatsBackplane(config));
+```
+
+Détail des réglages : [`docs/configuration.md`](./docs/configuration.md).
+
+## API
+
+<!-- prettier-ignore -->
+| Symbole | Type | Rôle |
+| --- | --- | --- |
+| `RealtimeController` | class | Base abstraite des controllers WebSocket |
+| `RealtimeHub` / `getRealtimeHub` | class / fn | Broker fan-out serveur |
+| `RealtimeService` | class | Service injectable (authenticators, cycle de vie) |
+| `ServerRealtimeSocket` / `serverSocket` | class / fn | Façade « la socket » côté serveur |
+| `@RealtimeChannel` / `@RealtimeInbound` / `@RealtimeAction` | decorators | Canal sortant · canal entrant · action RPC |
+| `@RealtimeBroadcast` | decorator | Déclare les préfixes propagés au cluster |
+| `defineRealtimeConfig` / `realtimeConfigJsonSchema` | functions | Builder de config + JSON Schema (Studio) |
+| `LoopbackBackplane` / `ClusterBackplane` / `RedisBackplane` | classes | Les 3 drivers natifs |
+| `registerBackplaneDriver` / `getBackplaneDriver` / `listBackplaneDrivers` | functions | Registre ouvert de drivers |
+| `IBackplane` | interface | Contrat d'un fond de panier |
+| `IRealtimeAuthenticator` / `IRealtimeToken` / `IRealtimeHandshake` | interfaces | Seams sécurité du handshake |
+| `ANONYMOUS_REALTIME_TOKEN` | const | Jeton anonyme gelé — fallback Zero Trust |
+
+## Tester un controller — `@nodefony/realtime/testing`
+
+Un controller temps réel s'éprouve **sans serveur ni navigateur**. Le harnais le monte sur
+une fausse connexion et parle son protocole : il envoie les frames JSON-RPC qu'un client
+enverrait, et rend celles qui sortent.
+
+```ts
+import { describe, it, expect, afterEach } from "vitest";
+import { getRealtimeHub } from "@nodefony/realtime";
+import { createRealtimeHarness } from "@nodefony/realtime/testing";
+import ChatController from "../nodefony/controllers/ChatController";
+
+describe("ChatController — socket", () => {
+  afterEach(() => getRealtimeHub().clear());
+
+  it("pousse sur son canal, et répond à son action", async () => {
+    const h = createRealtimeHarness((ctx) => new ChatController(ctx));
+    await h.connect(); // handshake → realtime:welcome
+    await h.subscribe("chat:ticker");
+    expect(h.messages("chat:ticker")).not.toHaveLength(0);
+    expect(await h.call("chat:ping")).toEqual({ pong: true });
+    h.dispose(); // dispose les providers + vide le hub
+  });
+});
+```
+
+Pour éprouver un canal ou une action **protégés**, il faut les deux : l'identité qu'un
+authenticator aurait résolue, et le verrou de frame que `@nodefony/security` pose au boot.
+Sans verrou, une `policy` déclarée n'est appliquée par personne — c'est vrai en test comme
+en production, `@nodefony/realtime` ne connaissant pas `@nodefony/security`.
+
+```ts
+const h = createRealtimeHarness((ctx) => new ChatController(ctx), {
+  identity: monToken, // IRealtimeToken
+  frameAuthorizer: buildFrameAuthorizer(firewall, {
+    // @nodefony/security
+    channelResolver: getRealtimeHub(),
+    systemRules: DEFAULT_SYSTEM_RULES,
+  }),
+});
+await h.connect();
+await h.subscribe("chat:admin");
+expect(h.denials().map((d) => d.channel)).toEqual(["chat:admin"]); // refusé
+```
+
+| Membre                                      | Rôle                                                            |
+| ------------------------------------------- | --------------------------------------------------------------- |
+| `connect()`                                 | Handshake ; rend le `realtime:welcome`, jette s'il n'arrive pas |
+| `subscribe(c)` / `unsubscribe(c)`           | Demande / rend un canal                                         |
+| `call(m, p?)` / `notify(m, p?)` / `send(f)` | Action RPC · notification entrante · frame brute                |
+| `messages(c)` / `denials()` / `received`    | Ce qui est sorti : par canal · refus · toutes les frames        |
+| `closes` / `notices`                        | Fermetures serveur (4003…) · avertissements de plateforme       |
+| `close()` / `dispose()`                     | Ferme la socket · ferme puis remet le hub à zéro                |
+
+`nodefony create controller --kind realtime` pose ce test à côté du controller qu'il génère.
+
+## Doc complète
+
+| Page                                               | Description                                   |
+| -------------------------------------------------- | --------------------------------------------- |
+| [`docs/index.md`](./docs/index.md)                 | Vue d'ensemble + promesse DX                  |
+| [`docs/vocabulaire.md`](./docs/vocabulaire.md)     | 12 mots avec analogies physiques              |
+| [`docs/architecture.md`](./docs/architecture.md)   | Pile 5 étages + trajet d'une frame en cluster |
+| [`docs/protocole.md`](./docs/protocole.md)         | Grammaire des frames, codes d'erreur réels    |
+| [`docs/actions.md`](./docs/actions.md)             | RPC : appeler et savoir si ça a marché        |
+| [`docs/configuration.md`](./docs/configuration.md) | Les 3 backplanes + driver custom              |
+| [`docs/securite.md`](./docs/securite.md)           | Autorisation des canaux, zones, plafonds      |
+| [`docs/observabilite.md`](./docs/observabilite.md) | Sonde, canaux de santé, écrans                |
+| [`docs/cookbook-chat.md`](./docs/cookbook-chat.md) | Exemple de chat de bout en bout               |
+
+## Licence
+
+CeCILL-B — Christophe CAMENSULI.

package/dist/_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js

@@ -0,0 +1,9 @@
+//#region \0@oxc-project+runtime@0.148.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);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+export { __decorate as default };

package/dist/_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js

@@ -0,0 +1,6 @@
+//#region \0@oxc-project+runtime@0.148.0/helpers/esm/decorateMetadata.js
+function __decorateMetadata(k, v) {
+	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+//#endregion
+export { __decorateMetadata as default };

package/dist/index.js

@@ -0,0 +1,218 @@
+import config from "./nodefony/config/config.js";
+import { defineRealtimeConfig, realtimeConfigJsonSchema } from "./nodefony/config/defineModuleConfig.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 { ServerRealtimeSocket, serverSocket } from "./nodefony/src/server/ServerRealtimeSocket.js";
+import { REDIS_RT_CHANNEL, RedisBackplane, createRedisServiceTransport, resolveRedisChannel } from "./nodefony/src/backplane/RedisBackplane.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 { buildOwnHealth, buildRealtimeHealth, createRealtimeAdminApi } from "./nodefony/src/server/RealtimeAdminApi.js";
+import __decorateMetadata from "./_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
+import __decorate from "./_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
+import { Kernel, Module, services, withTimeout } from "nodefony";
+//#region index.ts
+/**
+* @nodefony/realtime — Couche realtime serveur Nodefony.
+*
+* Ce module porte le hub WebSocket (broker fan-out), le protocole JSON-RPC 2.0
+* (peer isomorphe partagé avec le client core) et le backplane cluster. Trois
+* drivers natifs : `loopback` (mono-process), `cluster` (IPC Node) et `redis`
+* (multi-hôte) ; le registre `backplaneRegistry` est ouvert aux drivers écrits
+* par l'application.
+*
+* Le wiring cluster (`onCluster` → branchement `ClusterBackplane` IPC +
+* `ClusterProbeClient`) vit dans le hook du Module class ci-dessous. Le client
+* isomorphe n'est PAS ici : il vit dans le cœur, subpath `nodefony/client`
+* (décision figée — pas de package navigateur).
+*
+* Lire `docs/index.md` pour la vue d'ensemble vulgarisée.
+*
+* Voir aussi :
+*  - CLAUDE.md  — décisions d'archi figées + 5 seams sécurité
+*  - MEMORY.md  — internals IA
+*  - README.md  — usage humain
+*  - docs/      — doc dev vulgarisée
+*/
+/**
+* Délai max (ms) d'attente du `backplane.start()` au boot avant de basculer en
+* hub local (fail-soft). Garde anti-gel : un transport réseau qui pend ne doit
+* pas bloquer la montée des serveurs. Cf `Realtime.#startWithTimeout`.
+*/
+const BACKPLANE_START_TIMEOUT_MS = 5e3;
+registerBackplaneDriver(LoopbackBackplane.driver, () => null);
+registerBackplaneDriver(ClusterBackplane.driver, (ctx) => ctx.role === "WORKER" && process.env.NF_CLUSTER === "1" ? new ClusterBackplane(processIpcTransport, ctx.originId) : null);
+registerBackplaneDriver(RedisBackplane.driver, (ctx) => {
+	const redisService = ctx.module.kernel?.container?.get("redis");
+	if (!redisService) {
+		ctx.module.log(`driver "${RedisBackplane.driver}" : module @nodefony/redis absent (non listé dans @modules) — RealtimeHub reste local`, "WARNING");
+		return null;
+	}
+	const publisher = redisService.getClient("publish");
+	const subscriber = redisService.getClient("subscribe");
+	if (!publisher || !subscriber) {
+		ctx.module.log(`driver "${RedisBackplane.driver}" : connexions Redis publish/subscribe indisponibles — RealtimeHub reste local`, "WARNING");
+		return null;
+	}
+	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, {
+		maxQueueBytes: ctx.config.backplane.maxQueueBytes,
+		onNotice: (message, severity) => ctx.module.log(message, severity)
+	});
+});
+let Realtime = class Realtime extends Module {
+	/** Module optionnel : un échec de son boot ne tue jamais le process (résilience Ph.3). */
+	static critical = false;
+	/** Rôle topologique du process, capté à `onCluster` (défaut mono-process). */
+	#clusterRole = "MONO";
+	constructor(kernel) {
+		super("realtime", kernel, import.meta.url, config);
+		kernel.once("onCluster", (role) => {
+			this.#clusterRole = role;
+		});
+	}
+	/** JSON Schema de la config realtime → data plane admin (config riche Studio). */
+	configSchema() {
+		return realtimeConfigJsonSchema();
+	}
+	/**
+	* Validation Zod de la config racine merge au boot (convention figée 2026-05-28,
+	* cf [[feedback_config_validation_zod]]) — via le builder `defineRealtimeConfig`
+	* (source unique `nodefony/config/config.ts`). Plante propre avec messages clairs
+	* si la config (defaults + `module.options`) n'est pas conforme au schéma — évite
+	* tous les `undefined.x` silencieux en runtime.
+	*
+	* La config validée + gelée est exposée au container sous `realtimeConfig` pour
+	* que le `RealtimeService` (instancié à `onPreBoot` via `@services`) la consomme
+	* sans dupliquer la validation.
+	*/
+	async onKernelRegister() {
+		const validated = defineRealtimeConfig(this.options ?? {});
+		this.options = validated;
+		return this;
+	}
+	/**
+	* Phase `onBoot` (avant le `mountAll` de framework dans `onReady`) — enregistre
+	* le producteur admin de la **socket Nodefony** (`/nodefony/realtime/api/*`)
+	* sur le broker `framework/AdminBroker`. Auto-observabilité du `RealtimeHub`.
+	*
+	* ⚠️ Ne PAS déplacer dans `onKernelReady` : framework fait `broker.mountAll()`
+	* dans SON `onKernelReady` ; les modules listés APRÈS framework dans `@modules()`
+	* (cas de @nodefony/realtime) verraient leur `register` rejeté avec
+	* « AdminBroker: register("realtime") après mountAll — routes figées ».
+	* `onKernelBoot` court donc avant et garantit l'ordre.
+	*/
+	async onKernelBoot() {
+		if (!this.config.enabled) {
+			this.log("realtime enabled:false → boot inerte (ni admin API ni backplane ni sonde)", "INFO");
+			return this;
+		}
+		const broker = this.kernel?.container?.get("adminBroker");
+		if (broker && !broker.has("realtime")) broker.register(createRealtimeAdminApi());
+		await this.#wireBackplane();
+		this.#wireClusterProbe(this.#clusterRole);
+		return this;
+	}
+	/**
+	* 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
+	* renvoie `null` = inactif dans ce contexte → hub local).
+	*
+	* Phase `onKernelBoot` : après l'`initialize` des services (`onPreBoot`, donc
+	* un éventuel `RedisService` a ouvert ses connexions) et avant le trafic
+	* (`onReady` → `mountAll`). On `await start()` AVANT `setBackplane` pour
+	* garantir l'abonnement effectif (le `start()` interne de `setBackplane` est
+	* alors un no-op idempotent) — un driver async (Redis) perdrait sinon les
+	* premiers messages (setBackplane appelle start en fire-and-forget).
+	*
+	* No-op si un backplane custom est déjà posé (instance config / service DI
+	* `realtimeBackplane`, branché par `RealtimeService.initialize`). Warn fail-soft
+	* si le driver déclaré est inconnu du registre.
+	*/
+	async #wireBackplane() {
+		const config = this.config;
+		const hub = getRealtimeHub();
+		if (hub.backplane !== null) return;
+		const driverName = config.backplane.driver;
+		const factory = getBackplaneDriver(driverName);
+		if (!factory) {
+			this.log(`backplane driver "${driverName}" inconnu du registre (disponibles : ${listBackplaneDrivers().join(", ")}) — RealtimeHub reste local`, "WARNING");
+			return;
+		}
+		const backplane = await factory({
+			module: this,
+			originId: resolveBackplaneOriginId(),
+			role: this.#clusterRole,
+			config
+		});
+		if (!backplane) {
+			this.log(`realtime backplane  driver=${driverName} kind=local cross-pod=no (hub local)`, "INFO");
+			return;
+		}
+		try {
+			await this.#startWithTimeout(backplane, BACKPLANE_START_TIMEOUT_MS);
+		} catch (e) {
+			this.log(`realtime backplane driver=${driverName} indisponible (${e.message}) — fallback hub LOCAL, boot poursuivi (pas de fan-out cross-pod)`, "WARNING");
+			return;
+		}
+		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");
+	}
+	/**
+	* `backplane.start()` borné par un **timeout** — un driver réseau (Redis/Kafka)
+	* dont la connexion pend (serveur injoignable, file offline node-redis) ne doit
+	* jamais geler le boot.
+	*
+	* Délègue la garde au util générique du core {@link withTimeout} (timer `unref`
+	* + cleanup `finally` + filet anti-`unhandledRejection` si `start()` rejette
+	* après que le timeout a gagné la course). Spécificité realtime conservée ici :
+	* au timeout/échec, un `stop()` **best-effort** pour ne pas laisser une
+	* connexion à demi-ouverte derrière.
+	*
+	* @param backplane - driver à démarrer.
+	* @param ms - délai max avant de considérer le `start()` en échec.
+	* @throws si `start()` rejette ou dépasse `ms`.
+	*/
+	async #startWithTimeout(backplane, ms) {
+		try {
+			await withTimeout(Promise.resolve(backplane.start()), ms, "realtime backplane start");
+		} catch (e) {
+			Promise.resolve(backplane.stop()).catch(() => {});
+			throw e;
+		}
+	}
+	/**
+	* Branche les composants cluster du process en worker de `nodefony cluster` (repéré
+	* par l'env `NF_CLUSTER=1` posée côté master) : le {@link ClusterBackplane}
+	* (fan-out realtime cross-process) ET le {@link ClusterProbeClient} (sonde agrégée
+	* pod, Phase 4c).
+	*
+	* No-op si rôle MASTER, mono-process, ou worker `staging`/`preprod` legacy. La sonde
+	* est en plus gardée par `NF_CLUSTER_PROBE` (≠ "0") → **bypass total** quand
+	* désactivée : pas de client, donc 0 timer / 0 listener / 0 IPC, et l'endpoint santé
+	* sert la vue per-instance. Le backplane (realtime) reste indépendant de la sonde.
+	* Idempotent.
+	*/
+	#wireClusterProbe(role) {
+		if (role !== "WORKER" || process.env.NF_CLUSTER !== "1") return;
+		if (this.config.cluster.probe.enabled && process.env.NF_CLUSTER_PROBE !== "0") {
+			setClusterProbeClient(new ClusterProbeClient()).start(buildOwnHealth);
+			this.log("RealtimeHub: ClusterProbeClient branché (sonde pod)", "INFO");
+		}
+	}
+};
+Realtime = __decorate([services([RealtimeService]), __decorateMetadata("design:paramtypes", [typeof Kernel === "undefined" ? Object : Kernel])], Realtime);
+var realtime_default = Realtime;
+//#endregion
+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 };

package/dist/nodefony/config/config.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+//#region nodefony/config/config.ts
+/**
+* @nodefony/realtime — CONFIGURATION DU MODULE (schéma Zod = source unique).
+*
+* ⭐ TL;DR : CE SCHÉMA EST LA CONFIG. Chaque `.default(...)` = la valeur d'usine ;
+* changer un défaut du module = ÉDITER ICI (et nulle part ailleurs). L'app, elle,
+* surcharge via `use("@nodefony/...", { … })` dans SON `nodefony.config.ts`.
+*
+* RÈGLE D'OR (ADR-0006) : ce fichier porte le **schéma Zod commenté** (type +
+* validation + défaut + doc) ET matérialise les défauts via `parse({})`. Aucune
+* valeur n'est re-tapée ailleurs. Le builder (`defineModuleConfig.ts` →
+* `defineRealtimeConfig`) importe le schéma D'ICI (nœud bas : ce fichier
+* n'importe que `zod` → pas de cycle).
+*
+* Validé au boot du Module class (hook `onKernelRegister`) → plante propre avec
+* messages clairs si la config est invalide, pas d'`undefined.x` silencieux en
+* runtime. Les seams sécurité (areas WS, authenticator, origin, auditOnFrame)
+* vivent dans les sous-schémas `csrf`/`limits` ci-dessous.
+*
+* ⚠️ NE PAS éditer les défauts matérialisés en bas de fichier : modifier les
+* `.default(...)` du schéma. La fusion + validation finale est faite dans
+* `index.ts` au hook `onKernelRegister` (via `defineRealtimeConfig`).
+*/
+const probeSchema = z.strictObject({ enabled: z.boolean().default(true).describe("Branche le ClusterProbeClient (sonde agrégée pod, Phase 4c) en worker `nodefony cluster`. true = sonde active (timer + IPC). false = bypass total (0 timer / 0 listener / 0 IPC, l'endpoint santé sert la vue per-instance). Override env : NF_CLUSTER_PROBE=0 force la désactivation.") }).describe("Sonde agrégée pod (Phase 4c).");
+const backplaneSchema = z.strictObject({
+	driver: z.string().default("loopback").describe("Nom du driver IBackplane, résolu dans le registre de drivers (`listBackplaneDrivers()`) — PAS d'enum en dur ici : la liste réelle est la source de vérité du registre, ouverte aux drivers custom utilisateur (`registerBackplaneDriver(name, factory)`). Natifs : `loopback` (mono, hub local sans IPC), `cluster` (IPC workers `nodefony cluster`, actif si NF_CLUSTER=1), `redis` (multi-host pub/sub). Driver inconnu au boot → warn fail-soft, le hub reste local."),
+	namespace: z.string().min(1).regex(/^[\w.-]+$/).optional().describe("Cloison logique du transport partagé (drivers cross-pod : redis, futur kafka) — suffixe le canal pub/sub (`nodefony:realtime:<ns>`). Le `database` Redis ne cloisonnant PAS le pub/sub, deux apps sur un Redis mutualisé SANS namespace se parleraient (cross-talk). Défaut : dérivé du nom d'app (`kernel.projectName`). À poser EXPLICITEMENT quand deux déploiements de la même app (staging/prod) partagent un Redis. Caractères : alphanumériques, `_`, `.`, `-`. Env : `NF_REALTIME_BACKPLANE_NAMESPACE` (prioritaire — le namespace distingue des DÉPLOIEMENTS, il n'a pas à être figé dans le code)."),
+	secret: z.string().min(32).optional().describe("Secret de SCELLEMENT des messages du backplane, partagé par tous les pods de l'app (drivers à transport PARTAGÉ : redis, futurs drivers cross-host). Un bus pub/sub n'authentifie PAS l'émetteur : sans ce secret, quiconque écrit dans le Redis (autre app d'un Redis mutualisé, credential fuité, SSRF) publie sur les canaux de TOUS les pods. Posé, chaque message porte un HMAC-SHA256 et l'ingress devient fail-closed strict (non scellé ou mal scellé = ignoré, aucun downgrade). Sans lui, le boot ALERTE et le bus reste ouvert. Inutile pour `cluster` (IPC master↔workers : aucun tiers ne peut y écrire). Env : `NF_REALTIME_BACKPLANE_SECRET`. Minimum 32 caractères.").meta({ secret: true }),
+	maxQueueBytes: z.number().int().nonnegative().default(1 << 23).describe("Seuil d'octets PUBLIÉS mais pas encore acquittés par le bus, au-delà duquel les publications suivantes sont JETÉES (drivers à transport réseau : redis, drivers cross-host userland). Un `publish` de backplane est fire-and-forget : quand le bus ne draine plus, la file interne du client réseau grossit sans limite (583 MB observés sous rafale sur le banc multi-pods). Même doctrine que le back-pressure WS : on sacrifie du fan-out cross-pod pour tenir la mémoire du pod, jamais en silence (compteurs `backplane.queue` dans la sonde + Studio, alerte au franchissement). Défaut 8 MiB, soit trois ordres de grandeur au-dessus d'un régime sain (bus acquitté en quelques ms). `0` = illimité (opt-out explicite : la mémoire n'est alors bornée par rien).")
+}).describe("Driver IBackplane (fan-out cluster realtime cross-process).");
+const clusterSchema = z.strictObject({ probe: probeSchema.default(() => probeSchema.parse({})) }).describe("Comportement spécifique au mode cluster (worker IPC).");
+const slowConsumerSchema = z.strictObject({ bytes: z.number().int().positive().default(1 << 20).describe("Seuil de `bufferedAmount` (octets) au-dessus duquel une connexion WS est comptée comme `slowConsumer` dans la sonde RealtimeHub (métrique d'observabilité). Défaut : 1 MiB (1<<20). À augmenter pour clients lents tolérés (IoT, mobile faible bande), à diminuer pour un signalement plus précoce. N.B. : ce seuil pilote UNIQUEMENT le COMPTAGE de la sonde — l'ACTION de back-pressure (drop/close de frames) se règle sur le SERVEUR WebSocket, côté @nodefony/http : `websocket.maxBackpressure` / `.backpressurePolicy` / `.backpressureCloseAfterDrops`.") }).describe("Détection des consommateurs lents (métrique de la sonde WS).");
+const limitsSchema = z.strictObject({ maxChannelsPerConnection: z.number().int().positive().nullable().default(256).describe("Plafond de canaux qu'UNE connexion peut ouvrir (subscribe). Chaque canal ouvert = 1 ticker hub + 1 provider + 1 entrée Map côté connexion → sans borne, un socket peut subscribe à N canaux jusqu'à l'OOM. Au-delà du plafond, le subscribe est REFUSÉ (le canal n'est pas ouvert) et le client reçoit `realtime:denied` (motif `limit`). GARDE anti-OOM, PAS une bride : sous le seuil le multiplexage N-canaux reste libre. `null` = illimité (opt-out explicite, à réserver aux déploiements maîtrisés). Défaut 256.") }).describe("Bornes de ressources par connexion (anti-DoS/OOM).");
+const checkOriginSchema = z.strictObject({
+	enabled: z.boolean().default(false).describe("Active le contrôle de l'en-tête `Origin` (RFC 6455 §10.2) à l'upgrade WebSocket. Défense CSRF native (les cookies sont envoyés en cross-origin même avec `SameSite=Lax`/`Strict` selon le contexte). Défaut : false (rétro-compat). Activation recommandée dès qu'un authenticator pose un cookie de session/JWT. Si `allowList` est vide quand `enabled=true`, TOUTE origin est refusée (échec fermé)."),
+	allowList: z.array(z.string()).default([]).describe("Liste des origines acceptées (match EXACT, scheme+host+port, ex. `https://app.example.com`). Wildcards NON supportés (durcissement vs CORS `Access-Control-Allow-Origin: *`). Inclure les origines de dev si nécessaire (`http://localhost:5151`). Origines absentes (clients non-browser, mobile natif) → traitées selon `allowMissingOrigin`."),
+	allowMissingOrigin: z.boolean().default(false).describe("Accepter une upgrade sans en-tête `Origin` (clients non-browser, ex. mobile natif, tests). `false` (défaut) = refus, `true` = accepte. À `true` UNIQUEMENT si l'authenticator vérifie un credential fort (JWT signé, API key) — sans Origin ET sans authenticator = brèche CSRF.")
+}).describe("Contrôle Origin RFC 6455 §10.2 (défense CSRF native à l'upgrade WS).");
+const clientLogsSchema = z.strictObject({
+	enabled: z.boolean().default(false).describe("Accepte les journaux remontés par les navigateurs sur le canal `nodefony:syslog:uplink`, et les réinjecte dans le journal du pod (origine forcée `browser`). Permet de recouper une erreur survenue dans la page avec la requête HTTP qui l'a précédée, par le même `requestId`. Défaut : false — c'est une surface d'écriture, elle s'ouvre sur décision, jamais par héritage. Le canal reste soumis au plancher du namespace plateforme : une connexion ANONYME ne peut rien pousser, quelle que soit cette valeur."),
+	maxEntriesPerBatch: z.number().int().positive().default(50).describe("Entrées retenues par lot reçu. Le surplus est ignoré en silence — borner le lot évite qu'un seul message n'occupe l'event-loop."),
+	maxEntriesPerWindow: z.number().int().positive().default(300).describe("Entrées retenues par fenêtre et PAR CONNEXION. Au-delà, le reste du lot est jeté. Par connexion et non globalement : sinon un onglet bavard muselle tous les autres."),
+	windowMs: z.number().int().positive().default(1e4).describe("Durée de la fenêtre de débit, en ms."),
+	maxStringLength: z.number().int().positive().default(4096).describe("Longueur maximale d'une chaîne acceptée (message, pile). Le client tronque déjà ; le serveur ne le croit pas sur parole.")
+}).describe("Réception des journaux du navigateur (canal montant).");
+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)."),
+	backplane: backplaneSchema.default(() => backplaneSchema.parse({})),
+	cluster: clusterSchema.default(() => clusterSchema.parse({})),
+	slowConsumer: slowConsumerSchema.default(() => slowConsumerSchema.parse({})),
+	limits: limitsSchema.default(() => limitsSchema.parse({})),
+	csrf: csrfSchema.default(() => csrfSchema.parse({})),
+	clientLogs: clientLogsSchema.default(() => clientLogsSchema.parse({}))
+}).describe("Configuration de @nodefony/realtime.");
+/**
+* Défauts du module, matérialisés depuis le schéma (source unique). Toujours
+* valides par construction ; passés au `super(..., config)` du Module class.
+*/
+const config = realtimeConfigSchema.parse({});
+//#endregion
+export { config as default, realtimeConfigSchema };

package/dist/nodefony/config/defineModuleConfig.js

@@ -0,0 +1,60 @@
+import { realtimeConfigSchema } from "./config.js";
+import { parseModuleConfig } from "nodefony";
+import { z } from "zod";
+//#region nodefony/config/defineModuleConfig.ts
+/**
+* Builder type-safe de la configuration de `@nodefony/realtime`.
+*
+* ⭐ TL;DR : MACHINERIE DE BOOT — on n'édite (presque) jamais ce fichier. Même
+* pattern que `nodefony.config.ts` ↔ `defineConfig()` du core : `config.ts` PORTE
+* la config (schéma + défauts), `define<X>Config()` la VALIDE au boot (parse +
+* env + freeze) et publie le JSON Schema Studio.
+*
+* Principes (alignés sur `defineSecurityConfig`) :
+* - **Source unique** : `./config.ts` (Zod). Le builder VALIDE + GÈLE, ne dévie pas.
+* - **Auto-documenté + introspectable** : chaque champ Zod porte `.describe()` →
+*   {@link realtimeConfigJsonSchema} produit un JSON Schema qu'un formulaire
+*   Studio (futur) consommera pour générer son UI d'édition.
+* - **Backplane custom** : instance `IBackplane` userland (NATS, Pulsar…) passée
+*   via le 2ᵉ argument — **hors** schéma sérialisable (les classes n'ont rien à
+*   faire dans un JSON Schema Studio). L'instance, si fournie, prend précédence
+*   sur `driver` côté service ; ce dernier reste source d'introspection/UI.
+*
+* **Layering d'environnement** (convention-frère avec `REDIS_*` de
+* `@nodefony/redis`) : `NF_REALTIME_DRIVER` surcharge le driver backplane
+* APRÈS le parse (schéma pur, déterministe). Indispensable en déploiement
+* (k8s/Docker : `NF_REALTIME_DRIVER=redis`) et fiable quel que soit le
+* timing du merge `module-realtime` côté app (cf chantier ordering config).
+*
+* @param config - configuration brute (sections omises = défauts sûrs).
+* @param options.backplane - instance `IBackplane` custom (override le driver à
+*   l'init du `RealtimeService`). Non sérialisable → exclue du JSON Schema.
+* @returns config gelée prête pour `RealtimeService`.
+* @throws ZodError si invalide.
+*/
+function defineRealtimeConfig(config = {}, options = {}) {
+	const parsed = parseModuleConfig(realtimeConfigSchema, config, "@nodefony/realtime");
+	const driver = process.env.NF_REALTIME_DRIVER || parsed.backplane.driver;
+	const secret = process.env.NF_REALTIME_BACKPLANE_SECRET || parsed.backplane.secret;
+	const namespace = process.env.NF_REALTIME_BACKPLANE_NAMESPACE || parsed.backplane.namespace;
+	const out = {
+		...parsed,
+		backplane: {
+			...parsed.backplane,
+			driver,
+			secret,
+			namespace,
+			instance: options.backplane
+		}
+	};
+	return Object.freeze(out);
+}
+/**
+* JSON Schema introspectable de la config realtime — destiné au formulaire
+* d'édition Studio (futur). N'inclut PAS `backplane.instance` (non sérialisable).
+*/
+function realtimeConfigJsonSchema() {
+	return z.toJSONSchema(realtimeConfigSchema);
+}
+//#endregion
+export { defineRealtimeConfig, realtimeConfigJsonSchema };