@nodefony/realtime 10.0.0-alpha.1

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

@@ -0,0 +1,165 @@
+import { type RpcActionHandler, type EventsMap, type ActionsMap, type DefaultEventsMap, type DefaultActionsMap, type EventNames, type EventPayload, type ActionNames, type ActionParams, type ActionResult } from "nodefony";
+import { Controller } from "@nodefony/framework";
+import type { IRealtimeController, RealtimePublish, RealtimeInboundHandler } from "../../interfaces/IRealtimeController.js";
+/**
+ * RealtimeController — base d'un endpoint WebSocket temps réel SERVEUR (JSON-RPC 2.0).
+ *
+ * Factorise TOUT le protocole (handshake/welcome, discrimination request/notification/
+ * response via {@link JsonRpcPeer}, actions `result`/`error`, pub/sub par canal, cleanup)
+ * — écrit UNE fois, partagé par tous les modules. Un contrôleur concret ne déclare que
+ * son métier : {@link createRealtimeChannel} (providers de canaux) + {@link realtimeActions}.
+ *
+ * Chaque connexion compose un `JsonRpcPeer` (le MÊME que `RealtimeClient` côté navigateur
+ * — symétrie isomorphe) branché sur un {@link WsConnectionTransport}.
+ *
+ * Usage : le sous-classe garde sa route WS et délègue —
+ * ```ts
+ * @route("ws", { path: "/realtime", requirements: { methods: ["WEBSOCKET"] } })
+ * async realtime(message: string | Buffer | null) { this.handleRealtime(message); }
+ * ```
+ *
+ * Perf : les canaux sont **partagés** via {@link RealtimeHub} (1 provider/canal/pod, pas
+ * 1 par connexion) ; chaque connexion n'ajoute/retire qu'un *sink* (fan-out). Provider
+ * 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 {
+    /**
+     * Map des factories de canaux EXACT, lue depuis les décorateurs `@RealtimeChannel`
+     * au handshake (cold-path) et mémoïsée par instance. `null` = pas de décorateur
+     * sur cette classe → la base court-circuite la lecture metadata par frame.
+     */
+    private _decoratedChannels;
+    /**
+     * Crée le provider d'un canal (listener/ticker → `publish`) et renvoie son `dispose`.
+     * `null` si le canal est inconnu — la base ne souscrit pas.
+     *
+     * **Deux façons de déclarer un canal** (coexistent sans casse) :
+     *  1. **Décorateur `@RealtimeChannel(name)`** sur une méthode (match EXACT, déclaratif).
+     *  2. **Override de cette méthode** (pattern/regex, suffixe `:<ms>`, drill `@<pid>`).
+     *
+     * La base CONSULTE D'ABORD les décorateurs ; si aucun match, elle appelle
+     * cette méthode (fallback). Défaut : `null`. Un controller qui n'utilise QUE
+     * des décorateurs peut donc se passer d'override.
+     */
+    createRealtimeChannel(_channel: string, _publish: RealtimePublish): (() => void) | null;
+    /** Actions RPC exposées (requête→réponse). À surcharger ; défaut : aucune. */
+    protected realtimeActions(): Record<string, RpcActionHandler>;
+    /** Canaux annoncés au handshake. À surcharger ; défaut : aucun. */
+    protected realtimeChannels(): string[];
+    /**
+     * Préfixes de canaux **broadcast** (cross-process) de cet endpoint. À surcharger ;
+     * défaut : **aucun** → tous les canaux restent **instance-local** (observabilité,
+     * état du pod). Un canal listé ici traverse le {@link IBackplane} (cluster IPC /
+     * Redis) : chat, présence, notifications… Cf {@link RealtimeHub.markBroadcastChannel}
+     * (défaut sûr : pas de fuite cross-pod de données per-instance sans intention explicite).
+     */
+    protected realtimeBroadcastChannels(): string[];
+    /**
+     * Canaux FULL-DUPLEX acceptant une entrée client (`method` = nom du canal). À
+     * 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).
+     */
+    protected realtimeInbound(): Record<string, RealtimeInboundHandler>;
+    /**
+     * Opt-in du **pont API** (« API souveraine », POC Ph.3) : `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")`
+     * 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
+     * d'invocation ajoutée à un hub sans intention explicite.
+     */
+    protected realtimeApiRequest(): boolean;
+    /**
+     * Point d'entrée à appeler depuis la route WS du contrôleur. `message === null`
+     * = handshake (1ʳᵉ invocation) ; sinon = frame entrante.
+     *
+     * Le handshake est désormais ASYNC (seams sécu #2/#4 : origin check + run
+     * d'authenticator au handshake). Les frames texte entrantes pendant
+     * l'authentification sont DROP silencieusement — le transport JSON-RPC n'est pas
+     * encore branché, il n'existe donc AUCUN canal pour porter un refus. Le silence
+     * est structurel, pas un choix : c'est au client d'attendre `realtime:welcome`
+     * avant de pousser.
+     *
+     * ⚠️ Cette phrase a longtemps ajouté « ce que `RealtimeClient` fait nativement ».
+     * C'était FAUX : le client rejouait ses abonnements dès l'ouverture de la socket,
+     * si bien qu'un `subscribe` posé avant le démarrage et TOUS ceux d'après une
+     * reconnexion étaient perdus ici même, sans un mot des deux côtés. Un contrat écrit
+     * d'un seul côté du fil n'est pas tenu ; il l'est désormais par
+     * `RealtimeClient.replaySubscriptions` et les deux cas « la fenêtre où le serveur
+     * écoute (welcome) » de `RealtimeClientCoverage.test.ts`.
+     */
+    protected handleRealtime(message: string | Buffer | null): void;
+    /**
+     * **L1 — duplex serveur→client.** Émet une REQUÊTE vers le client de CETTE
+     * connexion (sur une action qu'il a exposée via `client.register(...)`) et attend
+     * sa réponse. Possible depuis L0 : le client compose le même `JsonRpcPeer`, il
+     * est donc un *callee* (avant L0 : `-32601` systématique).
+     *
+     * Usages : confirmation d'action (le serveur demande au client de valider),
+     * invalidation de cache poussée AVEC accusé, health applicatif serveur→client.
+     * Pour une notification sans réponse → {@link notifyClient} (ou un canal pub/sub).
+     *
+     * @returns le `result` du handler client ; rejette sur erreur applicative
+     *   ({@link RpcError} `code`/`data` préservés), méthode inconnue (`-32601`),
+     *   timeout, ou connexion fermée (`dispose`).
+     * @throws (rejet) si le handshake n'est pas terminé (aucun peer encore).
+     */
+    protected requestClient<K extends ActionNames<Actions>>(method: K, params?: ActionParams<Actions, K>, timeoutMs?: number): Promise<ActionResult<Actions, K>>;
+    /**
+     * Notification CIBLÉE serveur→client (sans réponse) vers CETTE connexion, hors
+     * canal pub/sub — pendant *fire-and-forget* de {@link requestClient}. Pour un
+     * fan-out à N abonnés, préférer un canal (`publish` via le hub). No-op si le
+     * handshake n'est pas terminé.
+     */
+    protected notifyClient<K extends EventNames<Emit>>(method: K, params?: EventPayload<Emit, K>): void;
+    /**
+     * Handshake : seams sécurité #4 (Origin RFC 6455 §10.2) + #2 (authenticator
+     * réseau) PUIS crée peer+transport, enregistre les actions, welcome + cleanup.
+     *
+     * Pipeline (cold path, 1× par connexion) :
+     *  1. Origin check via `hub.checkOrigin()` (bypass si `csrf.checkOrigin.enabled=false`).
+     *  2. Resolve authenticator via `hub.resolveAuthenticator(handshake)` (matchers
+     *     ordonnés, 1ʳᵉ qui matche capture) → `authenticate()` async.
+     *  3. Aucun match OU `enabled=false` → `ANONYMOUS_REALTIME_TOKEN`.
+     *  4. Pose le token sur `hub.peer → token` (lookup voters P6 hot-path).
+     *
+     * Échecs (close WebSocket, codes plage applicative RFC 6455 §7.4.2) :
+     *  - Origin refusée    → code 4003 (`forbidden`).
+     *  - `authenticate` throw → code 4001 (`unauthorized`).
+     */
+    private onHandshake;
+    /**
+     * Notifications entrantes : pub/sub (subscribe/unsubscribe), heartbeat (ping), puis
+     * canaux FULL-DUPLEX déclarés (entrée client → handler `realtimeInbound`).
+     */
+    private onRealtimeNotification;
+    /** Abonne la connexion à un canal via le hub partagé (idempotent par connexion). */
+    private startChannel;
+    /**
+     * Handler de la méthode RPC `api.request {path}` — le **pont API souverain**
+     * (POC Ph.3) : résout le path porté par le message via le Router
+     * (`cleanPathOverride` — l'URL de la connexion n'est jamais mutée) puis
+     * exécute l'action SANS la rendre (`executeAction`) : la valeur nue est
+     * enveloppée `{id, result}` par le peer — snapshot ≡ GET REST par
+     * construction.
+     *
+     * Query : le `?…` du path invoqué est parsé ici (paires plates, clés répétées
+     * → array — sémantique `qs` plate) et porté par `resolver.queryOverride`
+     * (per-invocation : zéro bleed entre requêtes concurrentes de la même
+     * socket). Limitation POC assumée : syntaxe nested `a[b]=c` non supportée
+     * par le pont (doc §11 — le parse complet du transport HTTP n'est pas
+     * 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…
+     * Tout autre throw de l'action reste opaque (`-32603`, Zero Trust).
+     */
+    private invokeApiRequest;
+    /** Désabonne la connexion d'un canal (le hub dispose le provider au dernier abonné). */
+    private stopChannel;
+}
+export default RealtimeController;