--- title: "Référence d'API — @nodefony/realtime — interfaces" source: docs/api/realtime/interfaces.md url: https://nodefony.github.io/nodefony-core/docs/api/realtime/interfaces/ --- [Documentation](../../../) › [Référence d'API](../../) › [`@nodefony/realtime`](../) › interfaces > Générée depuis les déclarations de types publiées de `@nodefony/realtime` **10.0.0-beta.6** : exactement ce que reçoit une application qui l'installe. Cette page n'existe dans aucun dépôt — pour la corriger, on corrige le TSDoc du code. ## `@nodefony/realtime` `import { … } from "@nodefony/realtime"` — 19 symboles. ### Interfaces (12) #### `IBackplane` ```ts interface IBackplane ``` Contrat d'un backplane realtime. Implémentation **stateless du point de vue métier** (l'état des canaux vit dans le hub) ; le backplane ne porte que le transport vers les pairs + son identité. - `readonly originId: string` — Identité stable de CE pair (process/pod). - `start(): void | Promise` — Démarre le transport vers les pairs (connexion IPC/Redis, abonnements). - `publish(channel: string, payload: unknown): void` — Propage une publication locale aux **autres** pairs. - `onMessage(handler: BackplaneHandler): void` — Enregistre le handler d'ingress (messages venus des autres pairs, echo déjà filtré). - `enableBytes?(codec: IFrameCodec): boolean` — Arme le transport des **octets** (ADR-0021 S6) : après un `true`, une charge qui est ou contient un `Uint8Array` traverse `publish` intacte jusqu'aux autres pairs. - `stop(): void | Promise` — Arrête le transport et libère les ressources (connexions, listeners). - `describe(): IBackplaneInfo` — Carte d'identité du backplane (driver, transport, origine, cross-pod, canal). #### `IBackplaneMessage` ```ts interface IBackplaneMessage ``` Message transporté entre pairs par le backplane. Sérialisé une fois à l'émission (IPC `structuredClone` / Redis JSON) ; le `payload` doit donc être structurellement clonable / sérialisable (pas de fonction, pas de cycle). - `channel: string` — Canal logique (mêmes noms que côté hub, suffixe de cadence `:` inclus). - `payload: unknown` — Charge applicative diffusée sur le canal. - `originId: string` — Identité du pair **émetteur** — sert l'anti-echo (cf `IBackplane.originId`). #### `IClientLogsLimits` ```ts interface IClientLogsLimits ``` Bornes de la réception des journaux remontés par un navigateur. - `readonly maxEntriesPerBatch: number` — Entrées retenues par lot reçu ; le surplus est ignoré. - `readonly maxEntriesPerWindow: number` — Entrées retenues par fenêtre et par connexion. - `readonly windowMs: number` — Durée de la fenêtre de débit, en ms. - `readonly maxStringLength: number` — Longueur maximale d'une chaîne acceptée (message, pile). #### `ICompiledRealtimeMatcher` ```ts interface ICompiledRealtimeMatcher ``` Forme compilée d'un matcher — utilisé en interne par le hub (cache de la RegExp compilée + host lowercase). Pas destiné à l'API publique. - `readonly pattern: RegExp` - `readonly host?: string` - `match(handshake: IRealtimeHandshake): boolean` — Le matcher capture-t-il ce handshake ? #### `IRealtimeAuthenticator` ```ts interface IRealtimeAuthenticator ``` Stratégie d'authentification au handshake WebSocket — équivalent realtime du pattern `IAuthenticator` côté HTTP de `@nodefony/security`. - `readonly name: string` — Nom logique (référencé dans les matchers, ex. - `supports(handshake: IRealtimeHandshake): boolean` — Peut-on extraire un credential de cette requête upgrade ? - `authenticate(handshake: IRealtimeHandshake): Promise` — Valide le credential et renvoie un token AUTHENTIFIÉ. - `onSuccess?(handshake: IRealtimeHandshake, token: IRealtimeToken): void` — Hook succès — appelé APRÈS pose du token sur le peer, AVANT le welcome JSON-RPC. - `onFailure?(handshake: IRealtimeHandshake, error: Error): void` — Hook échec — appelé APRÈS qu'`authenticate` a throw, AVANT la fermeture de la socket (code 4001). #### `IRealtimeAuthenticatorMatcher` ```ts interface IRealtimeAuthenticatorMatcher ``` Sélecteur d'une zone WS protégée — équivalent realtime de `ISecuredArea` côté HTTP de `@nodefony/security` (pattern URL + vhost optionnel). - `readonly pattern: string | RegExp` — Pattern d'URL (path) — string compilé en RegExp (escape complet) OU RegExp fournie telle quelle. - `readonly host?: string` — Vhost (Host header) optionnel — match exact (insensible à la casse). #### `IRealtimeConnProbe` ```ts interface IRealtimeConnProbe ``` Vue d'UNE connexion realtime pour la sonde (backpressure = risque #1). - `readonly readyState: number` — État du transport (0..3, aligné `WebSocket.readyState`). - `readonly bufferedAmount: number` — Octets en file d'envoi NON encore drainés vers le réseau (`ws.bufferedAmount`). - `readonly bytesSent: number` — Cumul d'octets envoyés à cette connexion (monotone). - `readonly messagesSent: number` — Cumul de frames envoyées à cette connexion (monotone). - `readonly dropped: number` — Cumul de frames JETÉES par back-pressure sur cette connexion (monotone) : drop latest-wins (`bufferedAmount ≥` seuil DROP) + la frame en cours quand on coupe un slow-consumer (`close 1013`). - `readonly binaryDiscarded?: number` — Cumul de trames BINAIRES reçues et écartées faute de lecteur (monotone) : connexion texte sans `onRealtimeBinary`. - `readonly malformedDiscarded?: number` — Cumul de trames reçues et écartées parce qu'illisibles par le codec de la connexion (monotone). #### `IRealtimeConnection` ```ts interface IRealtimeConnection ``` Une connexion temps réel servie par CE processus — la poignée qu'un gestionnaire `@RealtimeInbound` reçoit, et que les gestes du hub sur les membres d'un canal désignent (`RealtimeHub.subscribeConnection`, `RealtimeHub.evictConnection`, `RealtimeHub.channelMembers`). - `readonly userId: string | null` — Identifiant du compte connecté (`RealtimeIdentity.id`) — la clé des canaux personnels et de `RealtimeHub.evictUser`, qui l'atteint sur tous les exemplaires ; `null` pour l'anonyme (qu'aucun ordre par … - `readonly open: boolean` — `false` une fois la socket fermée : la poignée ne désigne plus rien. #### `IRealtimeConnectionState` ```ts interface IRealtimeConnectionState ``` État du protocole temps réel d'UNE connexion WebSocket — posé au welcome, et relu à chaque frame jusqu'à la fermeture. - `welcomed: boolean` — `realtime:welcome` émis : la poignée de main ne se rejoue pas. - `peer: JsonRpcPeer` — Le pair JSON-RPC de la connexion, sous son contrat effacé. - `transport: WsConnectionTransport` — Le transport qui relie le pair à la socket (contre-pression, sonde). - `binaryCodec: IFrameCodec | null` — Le codec BINAIRE accordé à cette connexion au handshake (ADR-0022 §2), `null` pour une connexion restée en texte. - `channels: Map` — Canal → sink de CETTE connexion auprès du hub partagé, pour s'en désabonner. - `inbound: Record | null` — Canaux full-duplex qui acceptent une entrée client ; `null` s'il n'y en a aucun. - `admission: ConnectionAdmission | null` — File d'admission aux canaux à `allow` — `null` tant que la connexion n'a demandé aucun de ces canaux (la plupart ne le font jamais). - `admitted: Record | null` — Canaux entrants dont les trames passent sans le verrou : ouverts par `allow`, ou dont le verrou a déjà dit oui (ADR-0022 §6, décision 1 ter). - `retained: string[] | null` — Ceux de `admitted` que le VERROU a admis — au plus 64, vidés quand une politique arrive après coup. - `connection: RealtimeConnection | null` — Poignée publique de la connexion (membre d'un canal, argument des gestionnaires `@RealtimeInbound`) — `null` jusqu'au premier abonnement ou à la première trame entrante qui la demande. #### `IRealtimeController` ```ts interface IRealtimeController ``` IRealtimeController — contrat d'un contrôleur temps réel SERVEUR (endpoint WS JSON-RPC 2.0). Le protocole (discrimination, dispatch, actions, pending, pub/sub, cleanup) est porté par `RealtimeController` via un `JsonRpcPeer` PAR connexion ; le contrôleur concret ne fournit QUE ses providers de canaux. - `createRealtimeChannel(channel: string, publish: RealtimePublish): () => void | null` — Crée le provider d'un canal au `subscribe` (démarre listener/ticker, pousse via `publish`) et renvoie son `dispose` (appelé au `unsubscribe` ET à la fermeture). #### `IRealtimeHandshake` ```ts interface IRealtimeHandshake ``` Données de handshake WebSocket — DTO minimal passé à un `IRealtimeAuthenticator` pour qu'il extraie un credential et valide l'identité, SANS coupler ce module à `@nodefony/http` runtime. - `readonly headers: Readonly>` — En-têtes de la requête upgrade (clés en lowercase RFC 9110 §5.1). - `readonly cookies: ReadonlyMap` — Cookies parsés depuis `Cookie:` (vide si en-tête absent ou mal formé). - `readonly url: string` — URL de l'upgrade (pathname + query string), ex. - `readonly remoteAddress: string` — IP du client (déjà extraite — derrière proxy : voir `trust proxy`). - `readonly origin?: string` — Origin RFC 6455 §10.2 — `undefined` si en-tête absent (clients non-browser). - `readonly protocols: readonly string[]` — Sous-protocoles annoncés (`Sec-WebSocket-Protocol`). #### `IRealtimeToken` ```ts interface IRealtimeToken ``` Jeton realtime — surface MINIMALE de l'identité d'une connexion WebSocket. - `readonly type: string` — Type du token (`"anonymous"`, `"jwt"`, `"apikey"`, …) — discriminator stable. - `getUserIdentifier(): string` — Identifiant logique de l'utilisateur (`"anonymous"`, `"user-42"`, …). - `isAuthenticated(): boolean` — `true` si l'authentification a réussi (≠ anonyme). - `getRoles(): string[]` — Rôles **plats** (sans hiérarchie résolue) — utilisés par les voters P6. - `getScopes(): string[]` — Scopes accordés (clés API / OAuth) — axe **distinct** des rôles RBAC. - `getAttribute(key: string): T` — Lecture d'un attribut arbitraire (claims JWT, `tenantId`, providerId…). - `isValid?(nowMs?: number): boolean | Promise` — Re-valide l'identité À L'USAGE (Zero Trust) : `true` si le token est encore légitime, `false` s'il est PÉRIMÉ (session détruite, ou un AUTRE compte s'est connecté depuis sur la même socket partagée). - `status?(nowMs?: number): TokenStatus | Promise` — La CAUSE de l'état de l'identité, quand elle est connaissable : `active`, `expired` (jeton porteur arrivé à `exp`) ou `revoked` (révoqué l'emporte sur expiré). - `confirmAccount?(): Promise` — Le COMPTE qui a ouvert la socket existe-t-il toujours, actif, et est-ce bien le même ? - `getIdentity?(): ISubscriberIdentity` — Identité d'ADMISSION de la connexion — la donnée plate que reçoit la règle `allow` d'un canal, construite UNE fois et gelée. ### Types (7) #### `BackplaneHandler` ```ts type BackplaneHandler = (msg: IBackplaneMessage) => void ``` Handler d'ingress : reçoit un message publié par un **autre** pair. L'echo du pair courant a déjà été filtré par l'implémentation → le handler peut réinjecter sans condition (mais en fan-out **local only**). #### `ContractRealtimePublish` ```ts type ContractRealtimePublish = >>(channel: K, payload: EventPayload, K> & object) => void ``` Publie sur un canal DÉCLARÉ par le contrat `C` : le nom est l'un des canaux de `serverToClient`, la charge est celle qu'il déclare. Une faute de frappe dans le nom ou dans la charge ne compile pas. #### `RealtimeActionHandler` ```ts type RealtimeActionHandler = { handle(params: unknown): unknown; }["handle"] ``` Handler d'action RPC tel que la table de `realtimeActions()` le range. Signature de MÉTHODE (paramètre comparé de façon bivariante) : une table typée par le contrat, dont chaque handler attend sa forme, remplace ainsi la table permissive de la base. #### `RealtimeInboundHandler` ```ts type RealtimeInboundHandler = (params: unknown, reply: (payload: unknown) => void, connection: IRealtimeConnection) => void ``` Handler d'un message ENTRANT sur un canal full-duplex (client → serveur). C'est le seam des backings entrants (SIP, bridge) : le client `publish(channel, payload)` ; si le contrôleur a déclaré ce canal dans `realtimeInbound()`, le handler est appelé. #### `RealtimeInboundHandlers` ```ts type RealtimeInboundHandlers = { [K in EventNames]?: TypedRealtimeInboundHandler, K extends keyof Emit ? Emit[K] : unknown>; } ``` Table des entrées client d'un contrôleur : un handler par canal de `Listen`, chacun facultatif — accepter une entrée reste un choix explicite, canal par canal (par défaut, un client ne peut rien pousser). `Listen` non déclaré : n'importe quel nom, `params: unknown`. #### `RealtimePublish` ```ts type RealtimePublish = (channel: string, payload?: object) => void ``` Publie une charge sur un canal (notification serveur→client) — forme LIBRE : tout nom, toute charge objet. Sous un contrat, préférer `ContractRealtimePublish`. #### `TypedRealtimeInboundHandler` ```ts type TypedRealtimeInboundHandler = { handle(params: P, reply: (payload: R) => void, connection: IRealtimeConnection): void; }["handle"] ``` Handler d'entrée TYPÉ par le contrat : `params` est ce que le client a émis sur ce canal, lu par `Jsonify` ; `reply` pousse la charge que le serveur émet sur le même canal. Les paramètres restent NON FIABLES : le type n'est pas une validation. --- [← Toutes les références d'API](../../)