Référence d'API — @nodefony/realtime — interfaces

stable

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#

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<void> — 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<void> — 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#

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#

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 :<ms> inclus).
• payload: unknown — Charge applicative diffusée sur le canal.
• originId: string — Identité du pair émetteur — sert l’anti-echo (cf IBackplane.originId).

IChannelPolicy#

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#

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#

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#

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<IRealtimeToken> — 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#

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#

interface IRealtimeChannelStat

Stat per-canal du hub (fan-out).

• channel: string — Nom du canal (suffixe :<ms> 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#

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#

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#

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<string, ChannelSink> — Canal → sink de CETTE connexion auprès du hub partagé, pour s’en désabonner.
• inbound: Record<string, RealtimeInboundHandler> | null — Canaux full-duplex qui acceptent une entrée client ; null s’il n’y en a aucun.

IRealtimeController#

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#

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<Record<string, string | string[]>> — En-têtes de la requête upgrade (clés en lowercase RFC 9110 §5.1).
• readonly cookies: ReadonlyMap<string, string> — 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#

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#

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#

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<T = unknown>(key: string): T — Lecture d’un attribut arbitraire (claims JWT, tenantId, providerId…).
• isValid?(nowMs?: number): boolean | Promise<boolean> — 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<boolean> — Le COMPTE qui a ouvert la socket existe-t-il toujours, actif, et est-ce bien le même ?

Types (3)#

BackplaneHandler#

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#

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#

type RealtimePublish = (channel: string, payload: unknown) => void

Publie une charge sur un canal (notification serveur→client).

← Toutes les références d’API