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

stable

Documentation › Référence d’API › @nodefony/realtime › server

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" — 18 symboles.

Classes (3)#

RealtimeController#

abstract class RealtimeController<Emit extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap> extends Controller implements IRealtimeController

RealtimeController — base d’un endpoint WebSocket temps réel SERVEUR (JSON-RPC 2.0).

• static scope: ControllerScope — Une instance PAR CONNEXION, par construction — le défaut singleton des contrôleurs ne s’applique pas ici.
• static assertScope(): void — Refuse qu’une sous-classe se déclare singleton — au démarrage (Router.setController), et au constructeur pour qui construit par new hors du routeur (harnais de test).
• constructor(name: string, context: ContextType)
• createRealtimeChannel(_channel: string, _publish: RealtimePublish): () => void | null — Crée le provider d’un canal (listener/ticker → publish) et renvoie son dispose.
• protected realtimeActions(): Record<string, RpcActionHandler> — Actions RPC exposées (requête→réponse).
• protected realtimeChannels(): string[] — Canaux annoncés au handshake.
• protected realtimeBroadcastChannels(): string[] — Préfixes de canaux broadcast (cross-process) de cet endpoint.
• protected realtimeInbound(): Record<string, RealtimeInboundHandler> — Canaux FULL-DUPLEX acceptant une entrée client (method = nom du canal).
• protected realtimeApiRequest(): boolean — Opt-in du pont API (une action, deux transports) : true → la connexion expose la méthode RPC api.request {path} qui re-route le path porté par le message vers l’action controller correspondant …
• protected handleRealtime(message: string | Buffer | null): void — Point d’entrée à appeler depuis la route WS du contrôleur.
• protected onRealtimeBinary?(data: Uint8Array): void — Lit les trames BINAIRES de cette connexion — le point d’extension d’un protocole binaire écrit par l’application, à côté du JSON-RPC ; pendant serveur de NodefonySocket.onBinary.
• protected requestClient<K extends ActionNames<Actions>>(method: K, params?: ActionParams<Actions, K>, timeoutMs?: number): Promise<ActionResult<Actions, K>> — 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.
• protected notifyClient<K extends EventNames<Emit>>(method: K, params?: EventPayload<Emit, K>): void — Notification CIBLÉE serveur→client (sans réponse) vers CETTE connexion, hors canal pub/sub — pendant fire-and-forget de requestClient.
• protected sendBinaryToClient(data: Uint8Array): boolean — Émet une trame BINAIRE vers CETTE connexion, sans la sérialiser — pendant sortant de onRealtimeBinary, et de NodefonySocket.sendBinary côté client.

RealtimeHub#

class RealtimeHub

RealtimeHub — broker temps réel PAR INSTANCE (1 pod = 1 process = 1 hub local).

• subscribeClient(channel: string, sink: ChannelSink, factory: ChannelFactory, serialize?: ChannelSerializer): boolean — Abonnement demandé par une connexion cliente — même chose que subscribe, plus le plancher des canaux de plateforme.
• subscribe(channel: string, sink: ChannelSink, factory: ChannelFactory, serialize?: ChannelSerializer): boolean — Abonne un consommateur qui répond du canal : il apporte la factory, donc la réponse à « ce canal existe-t-il, et qui le produit ?
• listen(channel: string, sink: ChannelSink): void — Écoute passive — un service du serveur reçoit ce qui passe sur un canal sans prétendre le produire.
• isChannelOwned(channel: string): boolean — Le canal a-t-il un propriétaire (une fabrique a fourni son provider) ?
• unsubscribe(channel: string, sink: ChannelSink): void — Désabonne une connexion d’un canal.
• publish(channel: string, payload: unknown): void — Publie une charge sur un canal : fan-out local + propagation conditionnelle au IBackplane (autres workers/pods).
• publishLocal(channel: string, payload: unknown): void — Fan-out d’une charge aux seuls abonnés locaux d’un canal (process courant).
• markBroadcastChannel(prefix: string): void — Déclare un préfixe de canal broadcast : ses publications traversent le IBackplane (cross-process).
• setBackplane(backplane: IBackplane): IBackplane — Branche le IBackplane cross-process (cluster IPC, Redis…) et câble son ingress (#admitFromBackplane) : un message reçu d’un autre pair est réinjecté en fan-out local uniquement (publishLocal …
• get backplane(): IBackplane | null — Backplane cross-process branché, ou null en mono-process (lecture/tests/sonde).
• subscriberCount(channel: string): number — Nombre d’abonnés locaux d’un canal (observabilité / tests).
• registerConnection(conn: IRealtimeConnProbe): void — Inscrit une connexion au registre de la sonde (au handshake).
• unregisterConnection(conn: IRealtimeConnProbe): void — Retire une connexion du registre de la sonde (au close).
• registerRevocable(entry: IRevocableConnection): void — Inscrit une connexion à identité RÉVOCABLE au registre de re-validation (F4, revue 0.6).
• unregisterRevocable(entry: IRevocableConnection): void — Retire une connexion du registre de révocation (au close).
• revalidateRevocable(): Promise<void> — Re-valide toutes les connexions révocables et ferme (4001) celles dont l’identité est morte : session détruite ou passée à un autre compte, jeton expiré ou révoqué.
• refreshIdentity(identifier: string): number — Ferme tout de suite les connexions qui ont figé cette identité — ses droits ont changé (IDENTITY_CHANGED_EVENT).
• recordInbound(): void — Compte une frame entrante full-duplex (canaux gated SIP/bridge).
• probe(): IRealtimeProbe — Snapshot d’auto-observabilité de la socket (per-instance).
• get activeChannels(): string[] — Canaux actifs (≥ 1 abonné).
• useAuthenticator(matcher: IRealtimeAuthenticatorMatcher, authenticator: IRealtimeAuthenticator): void — Seam #2 (P13 → P6) — enregistre un authenticator pour les handshakes WS dont l’URL matche matcher.
• resolveAuthenticator(handshake: IRealtimeHandshake): IRealtimeAuthenticator | null — Résout l’authenticator capturant ce handshake (1ʳᵉ matcher qui matche), ou null si aucun (le RealtimeController posera un token anonyme).
• setOriginGuard(guard: OriginGuard | null): void — Seam #4 (P13 → P6) — pose la politique Origin (RFC 6455 §10.2).
• checkOrigin(origin: string): boolean — Vérifie qu’une origin est autorisée (politique CSRF).
• setMaxChannelsPerConnection(max: number | null): void — F6a (revue 0.6) — plafond de canaux par connexion (anti-OOM).
• get maxChannelsPerConnection(): number | null — Plafond courant de canaux par connexion (null = illimité).
• setSlowConsumerBytes(bytes: number): void — F9 (revue 0.6) — pose le seuil de comptage des consommateurs lents (probe()).
• setTokenForPeer(peer: JsonRpcPeer, token: IRealtimeToken): void — Associe un token au peer (posé par RealtimeController.onHandshake() après succès authenticator.authenticate() ou fallback anonyme).
• getTokenForPeer(peer: JsonRpcPeer): IRealtimeToken — Renvoie le token associé au peer, ou ANONYMOUS_REALTIME_TOKEN si aucun (cas Zero Trust : la lecture ne renvoie JAMAIS null — slot #6 audit lookup garanti, voters P6 ne se posent jamais la question …
• setFrameAuthorizer(authorizer: FrameAuthorizer | null, options?: { readonly silentProbe?: FrameAuthorizer | null; }): void — Seam #1 (P13 → P6) — pose le verrou de frame (cf FrameAuthorizer).
• hasFrameAuthorizer(): boolean — Un verrou de frame est-il posé ?
• onPlatformNotice(notify: (message: string, severity: "WARNING" | "INFO") => void): void — Branche l’alerte du plancher système — tirée une seule fois, au premier canal de plateforme refusé faute de module de sécurité.
• isClosedBySystemFloor(channel: string): boolean — Ce canal serait-il fermé par le plancher système ?
• hasUnenforcedChannelPolicies(): boolean — F1 (revue 0.6) — des politiques de canal sont-elles DÉCLARÉES (@RealtimeChannel avec roles/scopes/authenticated) sans frameAuthorizer pour les faire respecter ?
• registerChannelPolicy(name: string, policy: IChannelPolicy): void — Seam #1b — déclare la politique d’autorisation d’un canal/méthode (@RealtimeChannel/@RealtimeInbound avec opts).
• static readonly MAX_PATTERN_WILDCARDS = 3 — Nombre maximum de * dans un motif.
• resolveChannelPolicy(name: string): IChannelPolicy | null — Politique déclarée pour ce canal/méthode, ou null si aucune.
• hasChannelPolicies(): boolean — Des politiques de canal sont-elles déclarées (au moins une) ?
• noticeUnguardedDynamicChannel(channel: string): void — Avertit — une seule fois — qu’un canal servi par une fabrique DYNAMIQUE n’est couvert par aucune politique déclarée, alors que d’autres canaux du module en portent une.
• registerSystemChannel(channel: string, factory: ChannelFactory): void — Enregistre la factory d’un canal système (plateforme) — un module bas niveau (ex.
• setClientLogsLimits(limits: IClientLogsLimits | null): void — Ouvre (ou referme) la réception des journaux du navigateur, avec ses bornes.
• get clientLogsLimits(): IClientLogsLimits | null — Bornes en vigueur, ou null si le canal montant est fermé.
• runAuthorizer(frame: unknown, peer: JsonRpcPeer): boolean
• probeChannel(channel: string, peer: JsonRpcPeer): boolean — Ce peer pourrait-il s’abonner à ce canal ?
• get registeredAuthenticators(): ReadonlyArray<IRealtimeAuthenticator> — Authenticators enregistrés (debug / tests).
• clear(): void — Dispose tous les providers et vide le hub (arrêt process / reset de test).

ServerRealtimeSocket#

class ServerRealtimeSocket<Emit extends EventsMap = DefaultEventsMap, Listen extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap> implements IRealtimeSocket<Emit, Listen>

L4 — façade serveur « la socket Nodefony ». Un handle SERVEUR qui implémente le contrat ISOMORPHE IRealtimeSocket au-dessus du RealtimeHub : un service back code comme une page front (publish / subscribe / on / channel) — il tient UN handle, ignore le fan-out et le backplane.

• constructor(hub?: import("./RealtimeHub").RealtimeHub)
• publish<K extends string>(channel: K, payload?: K extends EventNames<Emit> ? EventPayload<Emit, K> : unknown): void — Émet sur un canal — fan-out aux abonnés via le hub (+ backplane si broadcast).
• subscribe(channel: EventNames<Listen> | (string & {})): void — S’abonne (ref-compté) à un canal pour le RECEVOIR.
• unsubscribe(channel: EventNames<Listen> | (string & {})): void — Désabonne (ref-compté) : coupe le sink du hub au DERNIER consommateur.
• on<K extends string>(channel: K, handler: K extends EventNames<Listen> ? (payload: EventPayload<Listen, K>) => void : RealtimeHandler): () => void — Branche un handler de réception sur un canal.
• off<K extends string>(channel: K, handler: K extends EventNames<Listen> ? (payload: EventPayload<Listen, K>) => void : RealtimeHandler): void — Retire un handler d’un canal — même frontière que on.
• request<K extends string, T = unknown>(_method: K, _params?: ContractParams<Actions, K>, _timeoutMs?: number): Promise<ContractResult<Actions, K, T>> — Non supporté : rejette toujours.
• channel(name: string): IRealtimeChannel — Vue par-canal (IRealtimeChannel) — fine liaison sur les primitives.
• getStats(): IChannelStats[] — Snapshot des compteurs par canal (refs internes — à LIRE).
• getChannelStats(channel: string): IChannelStats — Compteurs d’un canal précis ou undefined.
• get subscribedChannels(): string[] — Canaux actuellement abonnés (≥ 1 consommateur).

Fonctions (6)#

buildOwnHealth#

function buildOwnHealth(): IRealtimeHealth

buildRealtimeHealth#

function buildRealtimeHealth(): Promise<IRealtimeHealth | IRealtimeClusterHealth>

Construit la santé de la socket servie par l’endpoint/le canal nodefony:socket : la vue POD agrégée si la sonde cluster est branchée et a reçu un snapshot du master (Phase 4c, push), sinon la vue per-instance (mono-process, sonde désactivée, ou cold start). Lecture pure, jamais throw. Async pour matcher la signature des tickers broker.

createRealtimeAdminApi#

function createRealtimeAdminApi(): IAdminApi

Construit le producteur IAdminApi de la socket (namespace "realtime").

createSyslogUplinkHandler#

function createSyslogUplinkHandler(opts: SyslogUplinkHandlerOptions): RealtimeInboundHandler

Fabrique le handler du canal montant des journaux.

getRealtimeHub#

function getRealtimeHub(): RealtimeHub

Renvoie le hub realtime du process (singleton lazy).

serverSocket#

function serverSocket<Emit extends EventsMap = DefaultEventsMap, Listen extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap>(): ServerRealtimeSocket<Emit, Listen, Actions>

Crée un handle serveur (ServerRealtimeSocket) sur le hub courant.

Constantes (5)#

ANONYMOUS_REALTIME_TOKEN#

const ANONYMOUS_REALTIME_TOKEN: IRealtimeToken

Token realtime ANONYME — fallback Zero Trust quand aucun matcher IRealtimeAuthenticatorMatcher ne capture le handshake.

MAX_CLIENT_SEVERITY#

const MAX_CLIENT_SEVERITY = 3

Sévérité la plus grave qu’un client puisse obtenir (3 = ERROR). Au-dessus vivent CRITIC, ALERT et EMERGENCY — des niveaux d’exploitation qu’un onglet ne décide pas.

RESERVED_SYSTEM_PREFIXES#

const RESERVED_SYSTEM_PREFIXES: readonly [ "nodefony:" ]

Namespace de canaux RÉSERVÉ À LA PLATEFORME — un seul préfixe, nodefony:.

SLOW_CONSUMER_BYTES#

const SLOW_CONSUMER_BYTES: number

Seuil d’alerte slow-consumer (octets de bufferedAmount). Au-delà, la connexion est comptée comme « lente » par la sonde (PAS encore de drop/close — la sonde MESURE avant qu’on optimise : stringify unique → seuil de drop → coalescing). 1 MiB = websocket.maxPayload par défaut : une file qui dépasse une frame max pleine est déjà anormale pour des canaux d’ÉTAT (latest-wins).

isReservedSystemChannel#

const isReservedSystemChannel: typeof isPlatformChannel

Le canal appartient-il au namespace réservé à la plateforme ?

Interfaces (1)#

SyslogUplinkHandlerOptions#

interface SyslogUplinkHandlerOptions

• syslog: Syslog — Le journal du pod où réinjecter.
• maxEntriesPerBatch?: number — Entrées retenues par lot.
• maxEntriesPerWindow?: number — Entrées retenues par fenêtre et par connexion.
• windowMs?: number — Durée de la fenêtre de débit, en ms.
• maxStringLength?: number — Longueur maximale d’une chaîne acceptée.
• maxRequestIdLength?: number — Longueur maximale d’un requestId accepté.

Types (3)#

ChannelFactory#

type ChannelFactory = (channel: string, publish: RealtimePublish) => () => void | null

Fabrique le provider PARTAGÉ d’un canal (listener/ticker qui pousse via publish). Appelée UNE fois, au 1ᵉʳ abonné. Renvoie son dispose (appelé au dernier désabonné) ou null si le canal est inconnu. Le provider doit capturer des deps long-lived (kernel/syslog/broker, valeurs simples) — JAMAIS la connexion qui a déclenché la création (elle peut fermer alors que le provider partagé survit).

ChannelSink#

type ChannelSink = (payload: unknown, serialized?: string) => void

Sink d’un canal : pousse une charge vers UNE connexion abonnée (son peer.notify). 1 sink = 1 connexion. Le hub fan-out la charge à tous les sinks d’un canal.

ClientSeverity#

type ClientSeverity = 3 | 4 | 5 | 6 | 7

Les seules sévérités qu’une entrée cliente peut porter, une fois plafonnée.

← Toutes les références d’API