@nodefony/realtime 10.0.0-alpha.1

package/dist/types/nodefony/src/server/welcomeEnv.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Le mode d'exécution annoncé — ou non — dans `realtime:welcome`.
+ *
+ * Le client ne dispose sinon que d'`import.meta.env.DEV`, qui dit le mode du
+ * BUNDLE : une application bâtie pour la production mais servie par un serveur
+ * de développement (banc, cluster local, image essayée sur le poste) restait
+ * muette dans la console alors qu'on avait tout intérêt à la faire parler.
+ *
+ * ⚠️ **En production, le champ est ABSENT** — et c'est la raison d'être de cette
+ * fonction, isolée pour être éprouvée dans les deux sens. Ce n'est pas un
+ * réglage que le client lit, c'est une permission de parler dans la console de
+ * quelqu'un : on ne l'accorde pas par défaut, et une absence vaut production,
+ * jamais l'inverse.
+ *
+ * @param env - le mode du kernel serveur (`kernel.environment`), s'il est connu.
+ * @returns le fragment à étaler dans le welcome : `{ env }` hors production,
+ *   sinon un objet vide.
+ */
+export declare function welcomeEnv(env: string | undefined | null): {
+    env?: string;
+};

package/dist/types/nodefony/src/service/RealtimeService.d.ts

@@ -0,0 +1,167 @@
+import { Service, Module, type JsonRpcPeer } from "nodefony";
+import { type RealtimeHub, type ChannelFactory, type ChannelSink, type FrameAuthorizer } from "../server/RealtimeHub.js";
+import type { IBackplane } from "../../interfaces/IBackplane.js";
+import type { IRealtimeProbe } from "../../interfaces/IRealtimeProbe.js";
+import type { IRealtimeConfig } from "../../config/defineModuleConfig.js";
+import type { IRealtimeAuthenticator } from "../../interfaces/IRealtimeAuthenticator.js";
+import type { IRealtimeAuthenticatorMatcher } from "../../interfaces/IRealtimeAuthenticatorMatcher.js";
+import type { IRealtimeToken } from "../../interfaces/IRealtimeToken.js";
+import type { IChannelPolicy } from "../../interfaces/IChannelPolicy.js";
+/**
+ * Façade DI publique de la **socket Nodefony** côté serveur.
+ *
+ * Wrapper mince autour du singleton {@link RealtimeHub} : expose
+ * `publish`/`subscribe`/`probe` à travers le container DI, applique au boot le
+ * backplane custom éventuel (config `backplane.instance` OU service DI nommé
+ * `realtimeBackplane`), expose la config gelée pour Studio / introspection.
+ *
+ * Ce service ne **remplace pas** le hub singleton (consommé par les
+ * controllers, l'admin API et les WS handlers via `getRealtimeHub()`) ; il en
+ * est l'API stable consommable côté userland. La Module class garde la main
+ * sur le wiring `ClusterBackplane` (lié au lifecycle `onCluster` kernel,
+ * pré-`onPreBoot`) — orthogonal au backplane custom userland.
+ *
+ * @example
+ * ```ts
+ * class MyService extends Service {
+ *   constructor(public module: Module) {
+ *     super(...);
+ *     this.realtime = this.get<RealtimeService>("realtimeService");
+ *   }
+ *   notify(payload: unknown) {
+ *     this.realtime?.publish("my-app:event", payload);
+ *   }
+ * }
+ * ```
+ */
+declare class RealtimeService extends Service {
+    #private;
+    module: Module;
+    constructor(module: Module);
+    /**
+     * Initialise le service au moment où le Module l'enregistre via `addService`
+     * (phase `onPreBoot`). Pose la config validée + applique l'éventuel backplane
+     * custom userland. Idempotent.
+     *
+     * Source du backplane custom (priorité décroissante) :
+     *  1. `realtimeConfig.backplane.instance` posée par la Module class via le
+     *     container (mode "config typée" : `defineRealtimeConfig({}, { backplane })`)
+     *  2. Service DI nommé `realtimeBackplane` (mode "userland enregistre une
+     *     instance dans son module via container.set")
+     *
+     * Si aucun n'est fourni → le hub reste avec son backplane par défaut (null =
+     * Loopback implicite, ou ClusterBackplane si le worker IPC a déjà été câblé
+     * par la Module class). Aucun warn — c'est le cas commun.
+     */
+    init(_module: Module): Promise<this>;
+    /** Configuration realtime gelée (lue par Studio / introspection). */
+    getConfig(): IRealtimeConfig;
+    /** Hub singleton (broker fan-out canaux PARTAGÉS du process courant). */
+    getHub(): RealtimeHub;
+    /** Backplane actuellement branché sur le hub (ou null = Loopback implicite). */
+    getBackplane(): IBackplane | null;
+    /**
+     * Publie une charge sur un canal — fan-out local + propagation backplane si
+     * canal broadcast. Délégué à `RealtimeHub.publish`.
+     */
+    publish(channel: string, payload: unknown): void;
+    /**
+     * Abonne un sink à un canal partagé — factory invoquée au 1ᵉʳ abonné, dispose
+     * appelé au dernier désabonné. Délégué à `RealtimeHub.subscribe`.
+     *
+     * @returns `true` si abonné, `false` si la factory a refusé (canal inconnu).
+     */
+    subscribe(channel: string, sink: ChannelSink, factory: ChannelFactory): boolean;
+    /**
+     * Désabonne un sink — appelle `dispose` du provider partagé au dernier abonné.
+     * Délégué à `RealtimeHub.unsubscribe`. No-op si non abonné.
+     */
+    unsubscribe(channel: string, sink: ChannelSink): void;
+    /**
+     * Enregistre la factory d'un **canal système** (plateforme) — délégué à
+     * {@link RealtimeHub.registerSystemChannel}. Un module bas niveau
+     * (`@nodefony/security` → `nodefony:audit`) déclare au boot comment produire le
+     * provider, sans qu'aucun `RealtimeController` ne le connaisse ; tout endpoint
+     * le sert alors (lazy : créé au 1ᵉʳ abonné, disposé au dernier).
+     */
+    registerSystemChannel(channel: string, factory: ChannelFactory): void;
+    /**
+     * Namespaces de canaux **réservés à la plateforme** — la liste que le hub ferme
+     * lui-même en l'absence de module de sécurité.
+     *
+     * Exposée pour qu'un module de sécurité y attache ses politiques **sans
+     * redéclarer la liste** : deux inventaires auraient divergé au premier namespace
+     * ajouté, et la divergence serait passée inaperçue (un namespace neuf resterait
+     * simplement sans politique). Ici, le hub possède la liste, la sécurité possède
+     * les rôles.
+     */
+    reservedSystemPrefixes(): readonly string[];
+    /** Snapshot d'observabilité du hub local (consommé par `/nodefony/realtime/api/health`). */
+    probe(): IRealtimeProbe;
+    /**
+     * Marque un préfixe de canal comme **broadcast** (cross-process via le
+     * backplane). Sans appel, tout canal reste instance-local. Délégué à
+     * `RealtimeHub.markBroadcastChannel`.
+     */
+    markBroadcastChannel(prefix: string): void;
+    /**
+     * **Seam #2/#3 (P13 → P6)** — enregistre un authenticator pour les
+     * handshakes WS dont l'URL matche `matcher`. Ordre d'enregistrement
+     * préservé (1ʳᵉ match capture). Cold path (boot via P6/userland).
+     *
+     * @example
+     * ```ts
+     * // À brancher par @nodefony/security (P6) au boot, depuis les areas
+     * // de `defineSecurityConfig()` filtrées sur `realtime: true`.
+     * realtimeService.useAuthenticator(
+     *   { pattern: "/admin/", host: "admin.example.com" },
+     *   jwtRealtimeAuthenticator,
+     * );
+     * ```
+     */
+    useAuthenticator(matcher: IRealtimeAuthenticatorMatcher, authenticator: IRealtimeAuthenticator): void;
+    /**
+     * **Seam #1 (P13 → P6)** — pose le verrou de frame (hot-path `beforeDispatch`).
+     * `null` retire la politique. À brancher 1× au boot par `@nodefony/security`
+     * depuis les zones `realtime: true`. L'authorizer lit le token déjà résolu au
+     * handshake (0 lecture base par frame). Délégué à `RealtimeHub.setFrameAuthorizer`.
+     *
+     * `options.silentProbe` porte la MÊME décision sans rapporter de refus : elle
+     * répond « ce visiteur pourrait-il s'abonner ici ? » pour l'annonce des canaux
+     * du `realtime:welcome`, qui interroge N canaux par connexion sans que
+     * personne n'ait rien demandé. Elle se pose par CE MÊME appel pour qu'aucun
+     * câblage ne puisse poser l'un sans l'autre.
+     *
+     * @example
+     * ```ts
+     * // @nodefony/security au boot :
+     * realtimeService.setFrameAuthorizer((frame, token) => {
+     *   // api.request {path} ≤ GET {path} : zone protégée → exige authentifié
+     *   return isFrameAllowed(frame, token);
+     * });
+     * ```
+     */
+    setFrameAuthorizer(authorizer: FrameAuthorizer | null, options?: {
+        readonly silentProbe?: FrameAuthorizer | null;
+    }): void;
+    /**
+     * **Seam #1b** — politique d'autorisation déclarée pour un canal/méthode
+     * (`@RealtimeChannel`/`@RealtimeInbound` avec opts), agrégée par le hub au
+     * handshake. Lu par `@nodefony/security` au moment de la frame `subscribe`/
+     * inbound pour appliquer rôles/scopes. `null` = aucune politique métier (le
+     * canal est alors soumis à la seule politique plateforme de security).
+     *
+     * @param channel - nom EXACT du canal ou de la méthode inbound.
+     * @returns la politique déclarée, ou `null`.
+     */
+    resolveChannelPolicy(channel: string): IChannelPolicy | null;
+    /**
+     * Renvoie le token associé à un peer (posé au handshake par le hub). Jamais
+     * `null` (Zero Trust : `ANONYMOUS_REALTIME_TOKEN` si aucun authenticator n'a
+     * capturé la connexion). Lookup O(1) via WeakMap interne. Branchement P6 :
+     * voters / `@IsGranted` realtime lisent l'identité par cette méthode.
+     */
+    getTokenForPeer(peer: JsonRpcPeer): IRealtimeToken;
+}
+export default RealtimeService;
+export { RealtimeService };

package/dist/types/nodefony/src/transport/WsConnectionTransport.d.ts

@@ -0,0 +1,78 @@
+import { type IRealtimeTransport } from "nodefony";
+import { type WsBackpressurePolicy } from "@nodefony/http";
+import type { IRealtimeConnProbe } from "../../interfaces/IRealtimeProbe.js";
+/**
+ * Connexion ws brute, typée structurellement (évite d'importer le package `ws`).
+ * `ctx.connection` (WebsocketContext) la fournit.
+ */
+export interface RawWsConnection {
+    send(data: string, cb?: (err?: Error) => void): void;
+    close(code?: number, reason?: string): void;
+    readonly readyState: number;
+    /**
+     * Octets en file d'envoi non drainés (`ws.bufferedAmount`). Optionnel : absent
+     * des connexions mockées en test → la sonde lit `0`. Sur une vraie socket `ws`,
+     * c'est le signal du blocker mémoire #1 (slow-consumer).
+     */
+    readonly bufferedAmount?: number;
+}
+/**
+ * Contre-pression WS — **la règle vit dans `@nodefony/http`**, ce transport ne
+ * fait que l'appliquer (`decideSend`). Deux implémentations de la même
+ * protection avaient déjà divergé en silence : 4 MiB côté `http`, 1 MiB ici.
+ *
+ * Réglage = config du serveur WebSocket (`websocket.maxBackpressure`,
+ * `.backpressurePolicy`, `.backpressureCloseAfterDrops`) — une seule source pour
+ * `send`/`broadcast` HTTP **et** pour le realtime.
+ *
+ * ⚠️ NE PAS confondre avec `slowConsumer.bytes` (config realtime) : celle-ci ne
+ * règle QUE le seuil de COMPTAGE de la sonde, jamais l'action.
+ */
+/**
+ * WsConnectionTransport — transport {@link IRealtimeTransport} CÔTÉ SERVEUR :
+ * wrap d'une connexion `ws` (1 par client connecté). Pendant serveur du
+ * `BrowserWsTransport` → la connexion serveur compose le MÊME `JsonRpcPeer` que
+ * le client (symétrie isomorphe).
+ *
+ * Particularité serveur : l'inbound n'est PAS piloté par un event socket mais par
+ * le **pipeline framework** (la route WS appelle `feed(raw)` à chaque message) ;
+ * la fermeture est signalée par `fireClose()` (hook `onFinish` du Context). Le
+ * `connect`/`onOpen` sont des no-op (la connexion est déjà ouverte au handshake).
+ */
+export declare class WsConnectionTransport implements IRealtimeTransport, IRealtimeConnProbe {
+    private readonly conn;
+    private _onMessage;
+    private _onClose;
+    private _bytesSent;
+    private _messagesSent;
+    private _dropped;
+    private readonly _max;
+    private readonly _policy;
+    private readonly _closeAfterDrops;
+    constructor(conn: RawWsConnection, limits?: {
+        max?: number;
+        policy?: WsBackpressurePolicy;
+        closeAfterDrops?: number;
+    });
+    connect(): void;
+    send(raw: string): void;
+    close(code?: number, reason?: string): void;
+    get readyState(): number;
+    /** Octets en file d'envoi non drainés (`ws.bufferedAmount`) — risque #1. `0` si mock. */
+    get bufferedAmount(): number;
+    /** Cumul d'octets envoyés sur cette connexion (monotone). */
+    get bytesSent(): number;
+    /** Cumul de frames envoyées sur cette connexion (monotone). */
+    get messagesSent(): number;
+    /** Cumul de frames jetées par back-pressure (drop + close slow-consumer) — monotone. */
+    get dropped(): number;
+    onOpen(): void;
+    onMessage(cb: (raw: string) => void): void;
+    onClose(cb: (code: number, reason: string) => void): void;
+    onError(): void;
+    /** Pump entrant : le pipeline framework pousse ici chaque message reçu. */
+    feed(raw: string): void;
+    /** Fermeture : appelée par le owner sur `onFinish` (close WS). */
+    fireClose(code?: number, reason?: string): void;
+}
+export default WsConnectionTransport;

package/dist/types/nodefony/testing/index.d.ts

@@ -0,0 +1,169 @@
+/**
+ * `@nodefony/realtime/testing` — **harnais de test d'un controller temps réel**.
+ *
+ * Écrire un test de socket demandait jusqu'ici une centaine de lignes de
+ * plomberie FRAMEWORK avant la première assertion : un faux `ContextType` qui ne
+ * fournit que ce que la base touche, un pont vers `handleRealtime` (qui est
+ * `protected`), la remise à zéro du hub — singleton par process — entre deux
+ * cas, et la pose d'une identité au handshake. Cette plomberie se périme au
+ * premier changement de signature de la base ; recopiée dans chaque application,
+ * elle y aurait vieilli sans que personne ne le sache. Elle vit donc ICI, avec
+ * le code dont elle dépend.
+ *
+ * Le harnais pilote le **côté serveur** : il injecte des frames JSON-RPC 2.0
+ * telles qu'un client les enverrait, et lit celles qui sortent. Il n'embarque
+ * PAS `RealtimeClient` — le client est un artefact navigateur du cœur, et le
+ * tirer ici le ferait entrer dans le paquet serveur publié. Ce qu'on veut
+ * prouver d'un controller (ses canaux, ses actions, son plein-duplex, son
+ * nettoyage) s'observe entièrement aux frames.
+ *
+ * ```ts
+ * import { createRealtimeHarness } from "@nodefony/realtime/testing";
+ *
+ * const h = createRealtimeHarness((ctx) => new ChatController(ctx));
+ * await h.connect();
+ * await h.subscribe("chat:ticker");
+ * expect(h.messages("chat:ticker")).to.have.length.greaterThan(0);
+ * h.dispose();
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type { IRealtimeDenied } from "nodefony";
+import type { ContextType } from "@nodefony/http";
+import type { RealtimeController } from "../src/server/RealtimeController.js";
+import { type RealtimeHub, type FrameAuthorizer } from "../src/server/RealtimeHub.js";
+import type { IRealtimeToken } from "../interfaces/IRealtimeToken.js";
+/**
+ * Frame JSON-RPC 2.0 telle qu'elle circule sur la socket, dans les deux sens.
+ *
+ * Volontairement permissive : un test lit `method`, `params`, `result` ou
+ * `error` selon ce qu'il éprouve, et le harnais ne présume pas de la forme du
+ * métier transporté.
+ */
+export interface IRealtimeFrame {
+    readonly jsonrpc?: string;
+    readonly id?: number | string;
+    readonly method?: string;
+    readonly params?: unknown;
+    readonly result?: unknown;
+    readonly error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+/** Fermeture demandée par le serveur (code RFC 6455 + raison). */
+export interface IHarnessClose {
+    readonly code?: number;
+    readonly reason?: string;
+}
+/**
+ * Refus d'abonnement notifié au client (`realtime:denied`) — le contrat de
+ * protocole lui-même, en lecture seule. Le recopier ici le ferait diverger : un
+ * motif ajouté au protocole doit apparaître dans le banc sans qu'on y pense.
+ */
+export type IHarnessDenied = Readonly<IRealtimeDenied>;
+/** Écart au décor par défaut du harnais. */
+export interface IRealtimeHarnessOptions {
+    /**
+     * URL de la connexion, telle que la verraient les matchers d'authenticator
+     * (seam #3). Défaut `/realtime`.
+     */
+    readonly url?: string;
+    /** `Origin` du handshake — ce que juge la politique CSRF (seam #4). Défaut `""`. */
+    readonly origin?: string;
+    /** En-têtes de la requête d'upgrade. */
+    readonly headers?: Record<string, string | undefined>;
+    /** Cookies de la requête d'upgrade, à la forme du contexte HTTP. */
+    readonly cookies?: Record<string, {
+        value: string;
+    }>;
+    /**
+     * Identité posée au handshake (seam #2). Sans elle, la base pose le token
+     * anonyme — c'est le repli Zero Trust, et c'est ce qu'il faut pour éprouver
+     * qu'un canal refuse un visiteur non identifié.
+     */
+    readonly identity?: IRealtimeToken;
+    /**
+     * Verrou de frame (seam #1). Neutre par construction : `@nodefony/realtime`
+     * ne connaît pas `@nodefony/security`. Une application qui charge la sécurité
+     * passe ici son `buildFrameAuthorizer(...)` pour éprouver une politique de
+     * canal ou une action gardée par rôle — sans lui, une `policy` déclarée n'est
+     * appliquée par personne, exactement comme au runtime.
+     */
+    readonly frameAuthorizer?: FrameAuthorizer;
+    /**
+     * Remet le hub à zéro à la création (défaut `true`). Le hub est un singleton
+     * par process : sans ce reset, un canal ouvert par un cas précédent fausse le
+     * suivant. Passer `false` pour monter deux connexions sur le MÊME hub — c'est
+     * ainsi qu'on éprouve un fan-out.
+     */
+    readonly resetHub?: boolean;
+}
+/**
+ * Vue de test d'un controller temps réel connecté : ce qu'il a reçu, ce qu'il a
+ * émis, et de quoi le piloter frame par frame.
+ *
+ * @typeParam C - le type du controller éprouvé, rendu tel quel par `controller`.
+ */
+export interface IRealtimeHarness<C extends RealtimeController> {
+    /** L'instance éprouvée, du type rendu par la fabrique. */
+    readonly controller: C;
+    /** Le hub du process — pour poser une politique de canal ou lire une sonde. */
+    readonly hub: RealtimeHub;
+    /** Toutes les frames sorties, dans l'ordre d'émission. */
+    readonly received: readonly IRealtimeFrame[];
+    /** Les fermetures demandées par le serveur (un refus d'Origin y laisse 4003). */
+    readonly closes: readonly IHarnessClose[];
+    /**
+     * Les avertissements de plateforme émis DEPUIS le handshake — dont celui qui
+     * dit qu'un canal servi dynamiquement ne porte aucune politique.
+     */
+    readonly notices: readonly string[];
+    /**
+     * Ouvre la socket (message `null` → `realtime:welcome`).
+     *
+     * @returns la frame de bienvenue — elle annonce les canaux, les méthodes et
+     *   l'identité retenue.
+     * @throws Si aucun welcome n'arrive (Origin refusée, authentification en
+     *   échec) : lire `closes` pour en connaître la cause.
+     */
+    connect(): Promise<IRealtimeFrame>;
+    /** Demande un canal, comme le ferait un client. */
+    subscribe(channel: string): Promise<void>;
+    /** Rend un canal — le provider est disposé au dernier abonné. */
+    unsubscribe(channel: string): Promise<void>;
+    /**
+     * Appelle une action (requête → réponse), appariée par identifiant.
+     *
+     * @returns le `result` de l'action.
+     * @throws L'erreur JSON-RPC rendue, ou un délai dépassé si rien ne répond.
+     */
+    call<T = unknown>(method: string, params?: unknown): Promise<T>;
+    /** Envoie une notification cliente (plein-duplex entrant). */
+    notify(method: string, params?: unknown): Promise<void>;
+    /** Injecte une frame brute — pour éprouver un protocole malformé. */
+    send(frame: Record<string, unknown>): Promise<void>;
+    /** Les charges utiles reçues sur un canal, dans l'ordre. */
+    messages(channel: string): readonly unknown[];
+    /** Les refus d'abonnement notifiés (`realtime:denied`). */
+    denials(): readonly IHarnessDenied[];
+    /** Ferme la socket côté client : la base dispose alors tous ses providers. */
+    close(): void;
+    /** `close()` puis remise à zéro du hub. À appeler en fin de cas. */
+    dispose(): void;
+}
+/**
+ * Monte un controller temps réel sur une fausse connexion et rend de quoi le
+ * piloter.
+ *
+ * La fabrique reçoit le contexte à passer au constructeur : c'est la seule
+ * chose que le harnais ne peut pas deviner, puisque le nom du service et les
+ * dépendances injectées appartiennent au controller.
+ *
+ * @param create  - construit le controller à partir du contexte fourni.
+ * @param options - écarts au décor par défaut (identité, Origin, verrou…).
+ * @returns le harnais, prêt pour `connect()`.
+ */
+export declare function createRealtimeHarness<C extends RealtimeController>(create: (context: ContextType) => C, options?: IRealtimeHarnessOptions): IRealtimeHarness<C>;