--- 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.5** : 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"` — 20 symboles. ### Interfaces (17) #### `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é). - `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). #### `IBackplaneInfo` ```ts interface IBackplaneInfo ``` **Carte d'identité** d'un backplane — descripteur de DONNÉE (pas un log) décrivant l'état du fond de panier. Source unique alimentant trois sorties cohérentes : la ligne stdout au boot, le champ `backplane` de la sonde (`/api/health`) et la vue Studio. Réutilisable par les tests / un agent IA sans dupliquer la connaissance « c'est quoi ce backplane ». - `driver: string` — Nom du driver (clé du registre). - `kind: string` — Nature du transport. - `originId: string` — Identité de CE pair (process/pod). - `crossPod: boolean` — `true` si le fan-out franchit les frontières de pod (multi-host). - `channel?: string` — Canal/topic de transport, si applicable (canal Redis, topic Kafka). - `sealed?: boolean` — Les messages sont-ils **scellés** (authenticité de l'émetteur vérifiée) ? - `queue?: IBackplaneQueueInfo` — État de la **file d'envoi** vers le bus (octets en vol, seuil, jetés). #### `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`). #### `IChannelPolicy` ```ts interface IChannelPolicy ``` Politique d'autorisation d'un **canal** WebSocket — exigences à satisfaire pour s'y abonner (`subscribe`) ou y pousser (canal inbound full-duplex). - `readonly authenticated?: boolean` — Exige une connexion authentifiée (token non anonyme). - `readonly roles?: readonly string[]` — Un de ces rôles suffit (évalué AVEC la hiérarchie de rôles, côté security). - `readonly scopes?: readonly string[]` — Un de ces scopes suffit (axe API : JWT/clé API ; session BFF n'en porte pas). #### `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). #### `IRealtimeChannelStat` ```ts interface IRealtimeChannelStat ``` Stat per-canal du hub (fan-out). - `channel: string` — Nom du canal (suffixe `:` de granularité inclus). - `subscribers: number` — Abonnés locaux vivants (sinks) — instantané. - `messages: number` — Publications cumulées sur ce canal (monotone) → débit dérivé côté lecteur. #### `IRealtimeClusterHealth` ```ts interface IRealtimeClusterHealth ``` Vue **POD agrégée** de la socket (Phase 4c, mode cluster) — la santé de TOUS les workers du pod consolidée. Servie par n'importe quel worker via l'endpoint santé quand le master pousse le snapshot agrégé (sinon on retombe sur `IRealtimeHealth` per-instance). - `cluster: true` — Discriminant : vue agrégée multi-worker (≠ `IRealtimeHealth` per-instance). - `ts: number` — Horodatage du snapshot agrégé (ms epoch). - `instanceCount: number` — Nombre de workers présents dans l'agrégat. - `instances: IRealtimeHealth[]` — Santé par worker (détail per-instance pour le drill-down). - `totals: { channelCount: number; publishTotal: number; fanoutTotal: number; inboundTotal: number; ingressRejectedTotal: number; connectionCount: number; bytesSentTotal: number; messagesSentTotal: numbe …` — Totaux pod (sommes des scalaires ; backpressure max = pire worker). #### `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`). #### `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). - `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. #### `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`). #### `IRealtimeHealth` ```ts interface IRealtimeHealth extends IRealtimeProbe ``` Snapshot enrichi de l'identité d'instance — santé per-instance d'un worker/pod. - `instanceId: string` — Identifiant de CE process/pod (per-instance). - `process?: IProcessHealth` — Santé PROCESS du worker (CPU/mém/event-loop) — additif : la grille « salle des machines » de la vue pod lit `instances[].process` par worker. - `rich?: IProcessRich` — Sonde process **riche** (GC/heap-spaces/handles/ELU active-idle/ctx-switches) — présente UNIQUEMENT pendant un drill-down de CE worker (Phase 2 : le master a envoyé `nf:probe:enrich` à ce pid). - `orm?: IOrmLeanHealth` — Santé ORM **lean** du worker (connecteurs/requêtes/erreurs/latence EWMA) — additif, comme `process`. - `errors?: IInstanceErrorHealth` — Compteurs d'erreurs Syslog du worker (ERROR/CRITIC cumulés) — additif. - `backplaneDrivers?: string[]` — Drivers de backplane **enregistrés dans ce process** (clés du registre ouvert : natifs + ceux qu'une application a ajoutés par `registerBackplaneDriver`). - `ormRich?: unknown` — Diagnostic ORM **riche** du worker (par connecteur : ping/latence/stockage/pool + flux requêtes) — blob OPAQUE `{ health, flow }` produit par le driver, présent UNIQUEMENT pendant un drill ORM de CE w … #### `IRealtimeProbe` ```ts interface IRealtimeProbe ``` Snapshot PUR du hub (sans identité process) — ce que renvoie `RealtimeHub.probe`. Per-instance/pod (cloud-native) ; l'agrégat multi-pod = backplane Redis / Prometheus (P13). - `ts: number` — Horodatage du snapshot (ms epoch) — base du calcul de débit côté lecteur. - `channels: IRealtimeChannelStat[]` — Canaux actifs (≥ 1 abonné) avec abonnés + publications cumulées. - `channelCount: number` — Nombre de canaux actifs (= 1 provider/canal/pod). - `publishTotal: number` — Appels `publish` cumulés (monotone). - `fanoutTotal: number` — Livraisons cumulées (`publish` × abonnés) — vrai coût de fan-out (monotone). - `inboundTotal: number` — Frames entrantes full-duplex cumulées (canaux gated SIP/bridge) (monotone). - `ingressRejectedTotal: number` — Messages d'ingress backplane REFUSÉS (canal non déclaré broadcast) — monotone. - `systemFloorDeniedTotal: number` — Abonnements clients REFUSÉS par le plancher des canaux de plateforme — monotone. - `connectionCount: number` — Connexions realtime vivantes. - `bytesSentTotal: number` — Somme cumulée des octets envoyés, toutes connexions (monotone). - `messagesSentTotal: number` — Somme cumulée des frames envoyées, toutes connexions (monotone). - `backpressure: { maxBufferedAmount: number; totalBufferedAmount: number; slowConsumers: number; drops: number; }` — Backpressure agrégée (instantanée) — risque #1. - `backplane?: IBackplaneInfo` — Carte d'identité du backplane effectif (driver, transport, cross-pod, canal). #### `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). - `confirmAccount?(): Promise` — Le COMPTE qui a ouvert la socket existe-t-il toujours, actif, et est-ce bien le même ? ### Types (3) #### `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**). #### `RealtimeInboundHandler` ```ts type RealtimeInboundHandler = (params: unknown, reply: (payload: unknown) => void) => 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é. #### `RealtimePublish` ```ts type RealtimePublish = (channel: string, payload: unknown) => void ``` Publie une charge sur un canal (notification serveur→client). --- [← Toutes les références d'API](../../)