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

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

@@ -1,8 +1,25 @@
-import { type RpcActionHandler, type EventsMap, type ActionsMap, type DefaultEventsMap, type DefaultActionsMap, type EventNames, type EventPayload, type ActionNames, type ActionParams, type ActionResult } from "nodefony";
+import { type EventsMap, type ActionsMap, type DefaultEventsMap, type DefaultActionsMap, type EventNames, type EventPayload, type ActionNames, type ActionParams, type ActionResult } from "nodefony";
 import type { ContextType } from "@nodefony/http";
 import { Controller } from "@nodefony/framework";
 import type { ControllerScope } from "@nodefony/framework";
-import type { IRealtimeController, RealtimePublish, RealtimeInboundHandler } from "../../interfaces/IRealtimeController.js";
+import type { IRealtimeController, RealtimePublish, RealtimeInboundHandlers, RealtimeActionHandler } from "../../interfaces/IRealtimeController.js";
+/**
+ * Préfixe de la ligne `ERROR` écrite quand la poignée de main lève (socket fermée
+ * en 1011). Le harnais de test la relit pour citer l'exception : le client, lui,
+ * ne reçoit que « internal error » — rien d'interne ne sort par la socket.
+ */
+export declare const HANDSHAKE_FAILED_LOG = "WS realtime handshake failed";
+/**
+ * L'attente d'un `Retry-After` (RFC 9110 §10.2.3), en secondes : un délai
+ * (`120`) tel quel, une date HTTP ramenée à l'écart avec `now` (jamais
+ * négatif). Une valeur illisible, ou absente, ne dit rien : `null`.
+ *
+ * @param value - l'en-tête posé par l'action, s'il l'a été
+ * @param now - l'instant de référence d'une date HTTP, en ms (défaut : l'horloge,
+ *   lue seulement pour une date)
+ * @returns les secondes à attendre, ou `null`
+ */
+export declare function retryAfterSeconds(value: string | undefined, now?: number): number | null;
 /**
  * RealtimeController — base d'un endpoint WebSocket temps réel SERVEUR (JSON-RPC 2.0).
  *
@@ -25,7 +42,7 @@ import type { IRealtimeController, RealtimePublish, RealtimeInboundHandler } fro
  * créé au 1ᵉʳ abonné, `dispose()` au dernier (`unsubscribe` ou `onFinish`). Le dispatch
  * d'action n'est payé que sur une requête `id`. C'est aussi le seam du backplane Redis.
  */
-export declare abstract class RealtimeController<Emit extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap> extends Controller implements IRealtimeController {
+export declare abstract class RealtimeController<Emit extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap, Listen extends EventsMap = DefaultEventsMap> extends Controller implements IRealtimeController {
     #private;
     /**
      * Une instance PAR CONNEXION, par construction — le défaut `singleton` des
@@ -72,7 +89,7 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      */
     createRealtimeChannel(_channel: string, _publish: RealtimePublish): (() => void) | null;
     /** Actions RPC exposées (requête→réponse). À surcharger ; défaut : aucune. */
-    protected realtimeActions(): Record<string, RpcActionHandler>;
+    protected realtimeActions(): Record<string, RealtimeActionHandler>;
     /** Canaux annoncés au handshake. À surcharger ; défaut : aucun. */
     protected realtimeChannels(): string[];
     /**
@@ -88,13 +105,16 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      * surcharger ; défaut : **aucun** (sûr — un client ne peut rien pousser au serveur
      * tant qu'un canal n'est pas explicitement déclaré ici). Seam des backings entrants
      * (SIP, bridge). Cf {@link RealtimeInboundHandler} (params NON FIABLES).
+     *
+     * Typée par `Listen` (ce que le client émet, 3ᵉ générique) : un canal hors de
+     * la carte ne compile pas, et chaque handler reçoit la forme de SON canal.
      */
-    protected realtimeInbound(): Record<string, RealtimeInboundHandler>;
+    protected realtimeInbound(): RealtimeInboundHandlers<Listen, Emit>;
     /**
      * Opt-in du **pont API** (une action, deux transports) : `true` → la
      * connexion expose la méthode RPC `api.request {path}` qui re-route le path
      * porté par le message vers l'action controller correspondante — la MÊME
-     * action que le GET REST (`socket.request("/nodefony/kernel/api/modules")`
+     * action que le GET REST (`socket.get("/nodefony/kernel/api/modules")`
      * côté client). Le pont n'atteint QUE les routes déclarant le transport
      * `WEBSOCKET` dans leurs `methods` (zéro bypass : une action dit à quels
      * transports elle répond). À surcharger ; défaut : `false` — aucune surface
@@ -120,7 +140,7 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      * `NodefonySocket.replaySubscriptions` et les deux cas « la fenêtre où le serveur
      * écoute (welcome) » de `NodefonySocketCoverage.test.ts`.
      */
-    protected handleRealtime(message: string | Buffer | null): void;
+    protected handleRealtime(message: string | Uint8Array | null): void;
     /**
      * Lit les trames BINAIRES de cette connexion — le point d'extension d'un
      * protocole binaire écrit par l'application, à côté du JSON-RPC ; pendant
@@ -128,7 +148,7 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      *
      * Le protocole temps réel est du JSON-RPC texte : il ne sait pas à quel canal
      * une trame binaire appartient. Sans cette méthode, une trame binaire est
-     * écartée, comptée (`binaryDiscarded` de la sonde de connexion) et journalisée
+     * écartée, comptée (`binaryDiscardedTotal` de la sonde du hub) et journalisée
      * une fois par connexion. La surcharger la reçoit telle quelle, octets exacts,
      * en `Uint8Array` — le type que livre aussi `NodefonySocket.onBinary` dans le
      * navigateur : un décodeur s'écrit une fois pour les deux côtés. À l'exécution
@@ -140,6 +160,10 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      * et le pare-feu. L'identité se lit par `RequestContext.getAuthenticatedUser()`,
      * et toute décision d'accès sur une trame binaire appartient à l'application.
      *
+     * ⚠️ Connexions TEXTE seulement : une connexion qui a négocié un codec binaire
+     * (configuration `codec: "cbor"`) lit toute trame binaire comme une frame du
+     * codec, et cette méthode n'y est jamais appelée (ADR-0022 §2).
+     *
      * ⚠️ Un `DataView` se construit sur `data.buffer` AVEC `data.byteOffset` et
      * `data.byteLength` : un `Buffer` issu du pool de Node ne commence pas à 0.
      *
@@ -183,10 +207,20 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      * client. Même contre-pression que les frames JSON-RPC.
      *
      * @param data - les octets à émettre (`Uint8Array`, donc un `Buffer` aussi).
-     * @returns `false` si le handshake n'est pas terminé, la connexion fermée ou
-     *   la trame jetée par la contre-pression.
+     * Sur une connexion qui a négocié un codec BINAIRE, refusé (ADR-0022 §2) : le
+     * client y lirait ces octets comme une frame du codec. Des octets passent
+     * alors par un canal, avec ses portes.
+     *
+     * @returns `false` si le handshake n'est pas terminé, la connexion fermée, la
+     *   trame jetée par la contre-pression, ou la connexion en codec binaire.
      */
     protected sendBinaryToClient(data: Uint8Array): boolean;
+    /**
+     * Journalise, une fois par connexion, le flux brut refusé sous codec binaire.
+     *
+     * @param state - l'état de la connexion.
+     */
+    private noticeRawBinaryUnderCodec;
     /**
      * État realtime de CETTE connexion, `undefined` avant le welcome — pour les
      * chemins FROIDS (requête sortante, binaire). `notifyClient` et la réception
@@ -207,6 +241,8 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      * Échecs (close WebSocket, codes plage applicative RFC 6455 §7.4.2) :
      *  - Origin refusée    → code 4003 (`forbidden`).
      *  - `authenticate` throw → code 4001 (`unauthorized`).
+     *  - `authenticate` sans réponse dans `authenticateTimeoutMs` → code 1013
+     *    (`try again later`, ADR-0021 §S11) : le client recule puis revient.
      */
     private onHandshake;
     /**
@@ -222,8 +258,69 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      * par connexion).
      */
     private acknowledgeSubscription;
-    /** Abonne la connexion à un canal via le hub partagé (idempotent par connexion). */
+    /**
+     * Poignée publique de la connexion, créée au premier besoin (abonnement, trame entrante) puis gardée sur son état.
+     *
+     * Cold path : une fois par connexion. Les deux fermetures la relient à CE
+     * contrôleur, dont les fabriques servent ses canaux.
+     */
+    private connectionOf;
+    /**
+     * Abonnement imposé par le serveur (`RealtimeHub.subscribeConnection`) — la politique fixe par le verrou des trames, puis le chemin d'un `subscribe` du client, `allow` compris (ADR-0022 §6 décision 2).
+     *
+     * Le verdict est rendu à l'appelant par `RealtimeConnection.settleImposed` :
+     * à l'acquittement ({@link acknowledgeSubscription}) ou au refus
+     * ({@link refuseChannel}) — qui n'envoie alors rien au client, qui n'a rien
+     * demandé.
+     */
+    private imposeChannel;
+    /**
+     * Met fin à l'abonnement de la connexion à un canal, sur décision du serveur, et le lui notifie (`realtime:closed`).
+     *
+     * Même chemin que l'`unsubscribe` du client (hub ET état de la connexion),
+     * jamais un second : retirer le seul sink du hub laisserait l'entrée de la
+     * connexion, et le `subscribe` suivant serait acquitté sans rien rouvrir.
+     * Retire aussi la marque « admise » et le verdict retenu de ce canal.
+     *
+     * @returns `false` si la connexion n'est pas abonnée à ce canal.
+     */
+    private endChannel;
+    /**
+     * Retire la connexion d'un canal : hub, état de la connexion, admission de sa règle — le chemin UNIQUE d'une sortie, demandée par le client ou décidée par le serveur.
+     *
+     * @returns `false` si la connexion n'était pas abonnée.
+     */
+    private leaveChannel;
+    /**
+     * Refus d'un abonnement : rendu à l'appelant serveur s'il s'agit d'une imposition, au client sinon — et aux deux quand le client avait aussi demandé ce canal.
+     */
+    private refuseChannel;
+    /**
+     * Abonne la connexion à un canal via le hub partagé (idempotent par connexion).
+     *
+     * Un canal dont la politique déclare `allow` passe d'abord par la file
+     * d'admission de la connexion ; tout autre canal s'ouvre tout de suite, sans
+     * rien lire de plus qu'aujourd'hui (une recherche de politique au `subscribe`,
+     * trame de contrôle rare).
+     */
     private startChannel;
+    /**
+     * Soumet l'abonnement à la règle `allow` du canal — APRÈS le verrou des trames, qui a déjà jugé `authenticated`/`roles`/`scopes` (ADR-0022 §6, décision 1 ter, moment 2).
+     *
+     * `allow` s'applique même sans module de sécurité : il ne fait que retirer
+     * des abonnés, jamais en ajouter — l'ignorer ouvrirait `user:<id>` à tous.
+     * La file de la connexion n'est créée qu'à son premier canal à `allow`.
+     */
+    private admitChannel;
+    /**
+     * Rend un refus d'abonnement observable (`realtime:denied`) — le détail ne part qu'hors production.
+     *
+     * @param detail - phrase pour le développeur ; `undefined` quand l'appelant
+     *   ne l'a pas rédigée (production).
+     */
+    private denyChannel;
+    /** Ouvre l'abonnement au hub et l'acquitte — canal sans `allow`, ou admis par sa règle. */
+    private openChannel;
     /**
      * Enveloppe des actions `@RealtimeAction` dont un paramètre est décoré
      * (`@Body`, `@CurrentUser`…) : l'action reçoit ses arguments comme une route,
@@ -260,7 +357,8 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      * mutualisé tant que Ph.6 n'a pas tranché).
      *
      * Erreurs → {@link RpcError} (`data.status` = statut HTTP équivalent) :
-     * `-32602` params invalides, 404 path inconnu, 408 timeout d'action…
+     * `-32602` params invalides, 404 path inconnu, 408 timeout d'action… Un
+     * `Retry-After` posé par l'action part en `data.retryAfter` (secondes).
      * Tout autre throw de l'action reste opaque (`-32603`, Zero Trust).
      */
     private invokeApiRequest;