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

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

@@ -0,0 +1,42 @@
+/**
+ * Une route montée, vue par le contrôle des routes de contrat : son chemin
+ * complet, les méthodes qu'elle accepte et les schémas qu'elle valide.
+ */
+export interface IMountedBridgeRoute {
+    /** Chemin complet, préfixe du contrôleur compris (`/chat/send`). */
+    readonly path: string;
+    /** Méthodes acceptées, en capitales ; `undefined` = toutes. */
+    readonly methods: ReadonlySet<string> | undefined;
+    /** Schémas d'entrée de l'action (`schema` de la route), ou `null`. */
+    readonly schema: {
+        readonly body?: unknown;
+        readonly query?: unknown;
+        readonly params?: unknown;
+    } | null;
+}
+/**
+ * Lit la table `serverRoutes` qu'une classe de contrôleur déclare en statique —
+ * `null` quand elle n'en déclare pas (aucun contrôle).
+ *
+ * @param ctor - la classe du contrôleur.
+ * @returns la table, ou `null`.
+ * @throws BootConfigurationError si la table n'est pas un objet.
+ */
+export declare function readContractRoutes(ctor: object): Record<string, unknown> | null;
+/**
+ * Vérifie, au démarrage, que chaque route du contrat est SERVIE par le pont :
+ * une route montée au même chemin, qui accepte le verbe par la socket, et dont
+ * les schémas sont LES MÊMES OBJETS que ceux que la table déclare. Coût nul par
+ * requête : la vérification n'a lieu qu'une fois.
+ *
+ * Sans elle, un contrat qui type `chat.post("/chat/send", …)` compilerait
+ * contre une route absente, servie en HTTP seulement, ou validant un autre
+ * schéma — et l'erreur n'apparaîtrait qu'au premier appel.
+ *
+ * @param owner - nom de la classe qui déclare la table (pour le message).
+ * @param table - la table `serverRoutes` (`"<VERBE> <chemin>"` → `{ body?, query? }`).
+ * @param mounted - les routes montées.
+ * @throws BootConfigurationError à la première entrée qui n'est pas servie ;
+ *   le message nomme la classe, l'entrée et la cause.
+ */
+export declare function assertContractRoutes(owner: string, table: Record<string, unknown>, mounted: readonly IMountedBridgeRoute[]): void;

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

@@ -23,3 +23,9 @@
 export declare function deniedDetail(env: string | undefined | null, detail: string): {
     detail?: string;
 };
+/**
+ * Le détail d'un refus part-il au client dans ce mode ? Hors production seulement — la règle de {@link deniedDetail}, lue AVANT de rédiger la phrase : en production, aucune chaîne n'est composée pour être jetée.
+ *
+ * @param env - le mode du kernel serveur, s'il est connu ; une absence vaut production.
+ */
+export declare function explainsDenials(env: string | undefined | null): boolean;

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

@@ -0,0 +1,70 @@
+import type { IJsonRpcNotification, IJsonRpcRequest } from "nodefony";
+import type { IRealtimeConnectionState } from "../../interfaces/IRealtimeConnectionState.js";
+import type { RealtimeHub } from "./RealtimeHub.js";
+/**
+ * Verdicts du verrou retenus par connexion, au plus (ADR-0022 §6, décision 1 ter).
+ *
+ * Borne la table qu'un client remplit en poussant sur des canaux entrants : au-delà,
+ * le verrou est consulté à chaque trame, il n'est jamais contourné. Une admission
+ * par `allow` n'y est pas soumise — elle est déjà bornée par le plafond de canaux
+ * de la connexion.
+ */
+export declare const MAX_RETAINED_FRAME_VERDICTS = 64;
+/**
+ * Admet les trames entrantes d'un canal que sa règle `allow` vient d'ouvrir à la connexion.
+ *
+ * Pas de plafond propre : le nombre de canaux ouverts l'est déjà. Sans effet si le
+ * canal n'accepte pas d'entrée client.
+ *
+ * @param state - état de la connexion.
+ * @param channel - canal ouvert par `allow`.
+ */
+export declare function admitByRule(state: IRealtimeConnectionState, channel: string): void;
+/**
+ * Retire TOUTE admission d'un canal à la connexion — marque de sa règle ET verdict retenu du verrou — quand le serveur l'en éjecte ou le termine (ADR-0022 §6 décision 3).
+ *
+ * Plus fort que {@link releaseRuleAdmission}, qui garde le verdict du verrou :
+ * après une éjection, une trame entrante sur ce canal repasse par le verrou.
+ *
+ * @param state - état de la connexion.
+ * @param channel - canal dont la connexion est retirée.
+ */
+export declare function revokeAdmission(state: IRealtimeConnectionState, channel: string): void;
+/**
+ * Retire l'admission d'un canal à la fin de son abonnement — celle de sa règle
+ * `allow`, que rien ne justifie plus. Un verdict du verrou, lui, ne tient qu'à
+ * l'identité et survit au désabonnement.
+ *
+ * @param state - état de la connexion.
+ * @param channel - canal quitté.
+ */
+export declare function releaseRuleAdmission(state: IRealtimeConnectionState, channel: string): void;
+/**
+ * Oublie les verdicts du verrou retenus par la connexion — leur politique vient
+ * de changer. Les admissions par `allow` restent : elles valent autant que
+ * l'abonnement qui les porte.
+ *
+ * @param state - état de la connexion.
+ */
+export declare function dropRetainedVerdicts(state: IRealtimeConnectionState): void;
+/**
+ * Juge une trame entrante que la connexion n'a pas admise d'office (ADR-0022 §6, décision 1 ter).
+ *
+ * Dans l'ordre :
+ * - une REQUÊTE (action, `api.request`) passe par le verrou, toujours ;
+ * - `ping` et `unsubscribe` passent sans règle ;
+ * - `subscribe` passe par le verrou (`allow` est jugé après, à l'ouverture) ;
+ * - un nom hérité du prototype de la table entrante est refusé ;
+ * - un canal entrant à `allow` que l'abonnement n'a pas admis est refusé ;
+ * - un canal entrant à politique fixe passe par le verrou, dont le « oui » est retenu ;
+ * - toute autre notification passe par le verrou.
+ *
+ * Le premier test du contrôleur (`admitted[method] === true`) a déjà écarté les trames
+ * admises : rien ici n'est sur le chemin d'une trame chaude.
+ *
+ * @param state - état de la connexion.
+ * @param frame - trame déjà classée par le pair.
+ * @param hub - hub qui porte le verrou et les règles.
+ * @returns `true` si la trame peut être distribuée.
+ */
+export declare function gateFrame(state: IRealtimeConnectionState, frame: IJsonRpcRequest | IJsonRpcNotification, hub: RealtimeHub): boolean;

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

@@ -21,3 +21,10 @@
  * @returns la trame JSON-RPC 2.0 prête à écrire sur le transport.
  */
 export declare function subscribedAckFrame(channel: string): string;
+/**
+ * Sérialise `realtime:subscribed { channel, imposed: true }` — l'acquittement d'un abonnement imposé par le serveur.
+ *
+ * @param channel - le canal imposé (échappé par `JSON.stringify`).
+ * @returns la trame JSON-RPC 2.0 prête à écrire sur le transport.
+ */
+export declare function imposedSubscribedAckFrame(channel: string): string;

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

@@ -0,0 +1,19 @@
+import type { RealtimeIdentity } from "nodefony";
+import type { IRealtimeToken } from "../../interfaces/IRealtimeToken.js";
+/**
+ * Vue PUBLIQUE de l'identité d'une connexion, annoncée au client par `realtime:welcome` — tirée de l'identité d'admission quand le jeton en produit une.
+ *
+ * Un objet NEUF, champ par champ, et jamais l'identité d'admission elle-même :
+ * celle-ci porte `issuer` et `account`, qui restent au serveur — la sérialiser
+ * telle quelle les enverrait au client (ADR-0021 §S10 point 1). Les tableaux
+ * de rôles et de scopes, eux, sont repris par RÉFÉRENCE : gelés une fois à la
+ * construction de l'identité, ils ne se recopient pas.
+ *
+ * Un jeton sans `getIdentity` (authentificateur tiers) annonce `id: null` : son
+ * identifiant stable n'est pas connu, et le déduire du login serait le défaut
+ * même que `id` corrige.
+ *
+ * @param token - jeton figé à la poignée de main.
+ * @returns l'identité à placer dans le `welcome`.
+ */
+export declare function welcomeIdentityOf(token: IRealtimeToken): RealtimeIdentity;

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

@@ -1,4 +1,4 @@
-import { Service, Module, type JsonRpcPeer } from "nodefony";
+import { Service, Module, type IFrameCodec, 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";
@@ -58,13 +58,21 @@ declare class RealtimeService extends Service {
     getConfig(): IRealtimeConfig;
     /** Hub singleton (broker fan-out canaux PARTAGÉS du process courant). */
     getHub(): RealtimeHub;
+    /**
+     * Le codec texte des connexions socket, lu PAR NOM par le REST du plan
+     * d'administration (`AdminApiController`, framework ne dépend pas de realtime) :
+     * les octets d'une réponse `GET` y prennent la même forme que sur la socket.
+     */
+    get textFrameCodec(): IFrameCodec;
     /** 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`.
+     *
+     * @throws TypeError si la charge est un scalaire ou `null` (cf `isRealtimePayload`).
      */
-    publish(channel: string, payload: unknown): void;
+    publish(channel: string, payload?: object): void;
     /**
      * Abonne un sink à un canal partagé — factory invoquée au 1ᵉʳ abonné, dispose
      * appelé au dernier désabonné. Délégué à `RealtimeHub.subscribe`.

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

@@ -0,0 +1,19 @@
+/**
+ * Schémas qu'accepte `realtime.publicOrigin` : celui de la socket (`ws:`,
+ * `wss:`) ou celui de l'hôte qui la sert (`http:`, `https:`), ramené au
+ * premier.
+ */
+export declare const REALTIME_ORIGIN_PROTOCOLS: readonly string[];
+/**
+ * Rend la source `connect-src` qui autorise la socket servie à `publicOrigin`,
+ * toujours sous son schéma de socket.
+ *
+ * Une source `wss://hôte` couvre `wss:` ET `https:` du même hôte (CSP Level 3,
+ * « scheme-part match ») ; une source `https://hôte` ne couvrirait PAS la
+ * socket. D'où la conversion `https:` → `wss:`, `http:` → `ws:`.
+ *
+ * @param publicOrigin - origine nue où la socket est servie
+ * @returns la source à déclarer (`wss://rt.example.com:8443`), ou `null` si la
+ *   valeur n'est pas une origine nue d'un schéma accepté
+ */
+export declare function realtimeConnectSource(publicOrigin: string): string | null;

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

@@ -1,4 +1,4 @@
-import { type IRealtimeTransport } from "nodefony";
+import { type IRealtimeTransport, type RealtimeFrameData, type RealtimeOutboundData } from "nodefony";
 import { type WsBackpressurePolicy } from "@nodefony/http";
 import type { IRealtimeConnProbe } from "../../interfaces/IRealtimeProbe.js";
 /**
@@ -16,29 +16,6 @@ export interface RawWsConnection {
      */
     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;
@@ -57,7 +34,7 @@ export declare class WsConnectionTransport implements IRealtimeTransport, IRealt
         closeAfterDrops?: number;
     });
     connect(): void;
-    send(raw: string): void;
+    send(raw: RealtimeOutboundData): void;
     /**
      * Émet des octets tels quels — trame binaire RFC 6455, hors JSON-RPC (#617).
      * Même contre-pression (`decideSend`, la règle unique) et mêmes compteurs que
@@ -73,13 +50,13 @@ export declare class WsConnectionTransport implements IRealtimeTransport, IRealt
      * Compte une trame ENTRANTE écartée et rend le cumul de sa nature — `1` dit
      * « première », le seul instant où l'appelant journalise.
      *
-     * @param kind - `binary` (sans lecteur) ou `malformed` (texte non JSON).
+     * @param kind - `binary` (sans lecteur) ou `malformed` (illisible par le codec).
      * @returns le cumul de cette nature, après incrément.
      */
     discard(kind: "binary" | "malformed"): number;
     /** Cumul de trames BINAIRES reçues et écartées faute de lecteur — monotone. */
     get binaryDiscarded(): number;
-    /** Cumul de trames TEXTE reçues et écartées parce que non JSON — monotone. */
+    /** Cumul de trames reçues et écartées parce qu'illisibles par le codec de la connexion — monotone. */
     get malformedDiscarded(): number;
     close(code?: number, reason?: string): void;
     get readyState(): number;
@@ -92,11 +69,20 @@ export declare class WsConnectionTransport implements IRealtimeTransport, IRealt
     /** Cumul de frames jetées par back-pressure (drop + close slow-consumer) — monotone. */
     get dropped(): number;
     onOpen(): void;
-    onMessage(cb: (raw: string) => void): void;
+    onMessage(cb: (raw: RealtimeFrameData) => 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;
+    /**
+     * Pump entrant : le pipeline framework pousse ici chaque frame reçue — texte,
+     * ou octets d'une connexion qui a négocié un codec binaire (ADR-0022 §2).
+     *
+     * Une vue sur un `SharedArrayBuffer` n'est pas une trame : `ws` livre
+     * toujours un `Buffer` sur un `ArrayBuffer`, le type de Node l'admet
+     * seulement. Elle est comptée comme illisible, jamais transmise au pair.
+     *
+     * @param raw - la trame telle que reçue.
+     */
+    feed(raw: string | Uint8Array): void;
     /** Fermeture : appelée par le owner sur `onFinish` (close WS). */
     fireClose(code?: number, reason?: string): void;
 }

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

@@ -0,0 +1,66 @@
+import type { IBackplane } from "../interfaces/IBackplane.js";
+/**
+ * Lanceur de tests de l'appelant — le sous-ensemble que la suite emploie.
+ *
+ * Formes compatibles telles quelles : `{ describe, it }` de vitest, de
+ * `node:test` et de `bun:test`.
+ */
+export interface IConformanceRunner {
+    /** Ouvre un groupe de cas. */
+    describe(name: string, body: () => void): unknown;
+    /** Déclare un cas asynchrone ; un rejet le fait échouer. */
+    it(name: string, body: () => Promise<void>): unknown;
+}
+/**
+ * Réglages de {@link runBackplaneConformance}.
+ */
+export interface IBackplaneConformanceOptions extends IConformanceRunner {
+    /**
+     * Le driver scelle-t-il ses messages (`sealBackplaneEnvelope`) ? Défaut `true`.
+     * `false` n'est admis que pour un driver dont le bus ne quitte pas la machine :
+     * un driver qui se déclare `crossPod` sans sceller fait échouer la suite.
+     */
+    sealed?: boolean;
+    /**
+     * Silence attendu, en millisecondes, avant de conclure qu'un message n'arrivera
+     * PAS (refus, rejeu, écho). Défaut 100 ; à relever pour un bus lent.
+     */
+    quietMs?: number;
+    /** Délai maximal d'arrivée d'un message attendu, en millisecondes. Défaut 2 000. */
+    timeoutMs?: number;
+}
+/**
+ * Fabrique d'un pair du driver, relié au MÊME bus que les autres pairs de la suite.
+ *
+ * Appelée plusieurs fois par cas : chaque appel rend un nouveau pair, d'`originId`
+ * propre, non démarré (la suite appelle `start` et `stop`).
+ *
+ * @param secret - secret du sceau, ou `null` pour un bus nu.
+ */
+export type BackplanePeerFactory = (secret: string | null) => IBackplane | Promise<IBackplane>;
+/** Noms des cas — stables : un test négatif les désigne. */
+export declare const BACKPLANE_CONFORMANCE_CASES: {
+    readonly fanout: "diffusion : chaque pair reçoit TOUT, l'émetteur ne reçoit pas son écho";
+    readonly order: "ordre par émetteur : les publications d'un pair arrivent dans l'ordre";
+    readonly noReplay: "pas de rejeu : un pair démarré après une publication ne la reçoit pas";
+    readonly seal: "sceau : un message non scellé ou mal scellé est refusé";
+    readonly control: "ordres de contrôle : le canal de contrôle traverse intact";
+    readonly reserved: "espace réservé : refusé et compté à l'entrée du hub, la diffusion passe sans revenir";
+    readonly replaceHandler: "onMessage remplace le handler précédent";
+    readonly stop: "stop coupe la réception, et se rappelle sans erreur";
+};
+/**
+ * Déclare la suite de conformité d'un driver de backplane auprès du lanceur de
+ * tests de l'appelant.
+ *
+ * Vérifie, sur plusieurs pairs reliés au même bus : la diffusion à TOUS les pairs
+ * sans écho, l'ordre par émetteur, l'absence de rejeu au démarrage, le sceau
+ * (message non scellé ou mal scellé refusé), le transport des ordres de contrôle,
+ * le refus de l'espace réservé à l'entrée du hub, le remplacement du handler et
+ * l'arrêt.
+ *
+ * @param name - nom du driver, affiché dans le rapport.
+ * @param makePeer - fabrique d'un pair relié au bus commun.
+ * @param options - le lanceur (`describe`, `it`) et les réglages.
+ */
+export declare function runBackplaneConformance(name: string, makePeer: BackplanePeerFactory, options: IBackplaneConformanceOptions): void;

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

@@ -29,7 +29,7 @@
  *
  * @packageDocumentation
  */
-import { type IRealtimeDenied } from "nodefony";
+import { type IChannelAdmission, 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";
@@ -102,6 +102,16 @@ export interface IRealtimeHarnessOptions {
      * ainsi qu'on éprouve un fan-out.
      */
     readonly resetHub?: boolean;
+    /**
+     * Les classes d'admission du controller (`@RealtimeChannel(nom, { allow:
+     * MaClasse })`), déjà construites avec leurs services. En production, le
+     * démarrage les résout dans le conteneur ; le harnais n'a pas de noyau, et
+     * sans elles une politique qui désigne une classe est REFUSÉE à la poignée de
+     * main. Les passer ici les inscrit par le même chemin que le démarrage, gardes
+     * comprises (`@injectable`, singleton, méthode `allow`). Le test construit
+     * ainsi l'admission avec le MÊME service que le controller.
+     */
+    readonly admissions?: readonly IChannelAdmission[];
 }
 /**
  * Vue de test d'un controller temps réel connecté : ce qu'il a reçu, ce qu'il a
@@ -174,3 +184,4 @@ export interface IRealtimeHarness<C extends RealtimeController> {
  * @returns le harnais, prêt pour `connect()`.
  */
 export declare function createRealtimeHarness<C extends RealtimeController>(create: (context: ContextType) => C, options?: IRealtimeHarnessOptions): IRealtimeHarness<C>;
+export { runBackplaneConformance, BACKPLANE_CONFORMANCE_CASES, type BackplanePeerFactory, type IBackplaneConformanceOptions, type IConformanceRunner, } from "./backplaneConformance.js";