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.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#

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é).
• 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<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).

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).

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).

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).
• 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#

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#

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<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.
• 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<string, boolean> | 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#

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).

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).
• status?(nowMs?: number): TokenStatus | Promise<TokenStatus> — 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<boolean> — 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#

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#

type ContractRealtimePublish<C extends IRealtimeContract> = <K extends EventNames<ContractServerEmit<C>>>(channel: K, payload: EventPayload<ContractServerEmit<C>, 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#

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#

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#

type RealtimeInboundHandlers<Listen extends EventsMap, Emit extends EventsMap> = { [K in EventNames<Listen>]?: TypedRealtimeInboundHandler<EventPayload<Listen, K>, 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#

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#

type TypedRealtimeInboundHandler<P, R> = { 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