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

stable

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

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

ClusterBackplane#

class ClusterBackplane implements IBackplane

Backplane IPC cross-process (Phase 3) — implémentation worker-side du port IBackplane dans un cluster Node natif, où les workers ne se parlent qu’à travers le master-gateway (un worker ne peut envoyer qu’au master via IPC).

• static readonly driver = "cluster" — Nom du driver — source unique du littéral (registre + config).
• readonly originId: string — Identité stable de CE pair (process/pod).
• constructor(transport?: IClusterBackplaneTransport, originId?: string)
• start(): void — Branche la réception IPC.
• publish(channel: string, payload: unknown): void — Propage une publication locale aux autres pairs via le master.
• onMessage(handler: BackplaneHandler): void — Un seul handler d’ingress ; un appel ultérieur remplace le précédent.
• stop(): void — Détache le handler.
• describe(): IBackplaneInfo — Carte d’identité du backplane (driver, transport, origine, cross-pod, canal).

LoopbackBackplane#

class LoopbackBackplane implements IBackplane

Backplane mono-process no-op — implémentation de RÉFÉRENCE du port IBackplane quand il n’existe aucun pair (1 process = 1 pod).

• static readonly driver = "loopback" — Nom du driver — source unique du littéral (registre + config).
• readonly originId: string — Identité stable de CE pair (process/pod).
• constructor(originId?: string)
• start(): 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 — Arrête le transport et libère les ressources (connexions, listeners).
• describe(): IBackplaneInfo — Carte d’identité du backplane (driver, transport, origine, cross-pod, canal).

RedisBackplane#

class RedisBackplane implements IBackplane

Backplane Redis pub/sub (P13.5) — implémentation du port IBackplane pour le fan-out realtime cross-pod (multi-host), là où le ClusterBackplane ne couvrait que les workers d’un même pod (IPC). Drop-in : le hub ne change pas, seul le driver branché change.

• static readonly driver = "redis" — Nom du driver — source unique du littéral (registre + config).
• readonly originId: string — Identité stable de CE pair (process/pod).
• constructor(transport: IRedisBackplaneTransport, originId?: string, redisChannel?: string, secret?: string | null, options?: IRedisBackplaneOptions)
• start(): Promise<void> — Abonne au canal Redis dédié.
• publish(channel: string, payload: unknown): void — Propage une publication locale aux autres pods via Redis.
• onMessage(handler: BackplaneHandler): void — Un seul handler d’ingress ; un appel ultérieur remplace le précédent.
• stop(): Promise<void> — Désabonne du canal Redis et détache le handler.
• describe(): IBackplaneInfo — Carte d’identité du backplane (driver, transport, origine, cross-pod, canal).

Fonctions (6)#

createRedisServiceTransport#

function createRedisServiceTransport(publisher: IRedisPublisher, subscriber: IRedisSubscriber): IRedisBackplaneTransport

getBackplaneDriver#

function getBackplaneDriver(name: string): BackplaneFactory

Fabrique d’un driver par nom, ou undefined si inconnu.

listBackplaneDrivers#

function listBackplaneDrivers(): string[]

Noms des drivers enregistrés (introspection / Studio / tests).

registerBackplaneDriver#

function registerBackplaneDriver(name: string, factory: BackplaneFactory): void

Enregistre (ou remplace) la fabrique d’un driver backplane. Appelé par les drivers natifs au chargement du module, et par l’utilisateur pour ses drivers custom (NATS, Pulsar, RabbitMQ…).

resolveBackplaneOriginId#

function resolveBackplaneOriginId(): string

Résout l’identifiant d’origine d’un backplane — l’étiquette que l’anti-écho compare pour jeter les messages qui reviennent à leur émetteur.

resolveRedisChannel#

function resolveRedisChannel(namespace?: string): string

Construit le canal pub/sub effectif : nodefony:realtime:<namespace>, ou la base seule si aucun namespace n’est résolu (compat mono-app). Deux déploiements de la MÊME app sur un Redis partagé (staging + prod) ont le même nom dérivé → y poser un backplane.namespace EXPLICITE distinct.

Constantes (2)#

REDIS_RT_CHANNEL#

const REDIS_RT_CHANNEL = "nodefony:realtime"

BASE du canal Redis dédié transportant les enveloppes realtime entre pods. Un seul canal pub/sub par app (les canaux logiques voyagent DANS l’enveloppe, comme le channel IPC du ClusterBackplane) → 1 SUBSCRIBE au boot, pas de (dés)abonnement Redis dynamique par canal applicatif.

processIpcTransport#

const processIpcTransport: IClusterBackplaneTransport

Transport de production : process.send (émission) + process.on("message") (réception). Standalone — utilisable tel quel. En vrai câblage cluster (Phase 3c), un transport branché sur l’event kernel onMessage (déjà alimenté par Kernel.initCluster) est préféré pour éviter un 2ᵉ listener + le log par message.

Interfaces (6)#

ClusterBackplaneEnvelope#

interface ClusterBackplaneEnvelope extends IBackplaneMessage

Enveloppe IPC d’une publication realtime = IBackplaneMessage + discriminant. Sérialisée une fois par process.send/worker.send (structuredClone IPC) → le payload doit rester structurellement clonable (cf contrat IBackplane).

• readonly kind: typeof CLUSTER_RT_KIND

IBackplaneFactoryContext#

interface IBackplaneFactoryContext

Contexte passé à une fabrique de backplane : tout ce dont un driver peut avoir besoin pour se construire (accès kernel/container/log via le Module, identité du pair, rôle dans la topologie, config validée). Une fabrique ne démarre PAS le backplane (start() est appelé par le wiring) — elle le construit ou renvoie null (driver inactif dans ce contexte, ex. loopback / cluster hors worker → le hub reste local).

• readonly module: Module — Module realtime — accès container/kernel/log.
• readonly originId: string — Identité stable de ce pair (process/pod).
• readonly role: "MASTER" | "WORKER" | "MONO" — Rôle du process dans la topologie de lancement.
• readonly config: IRealtimeConfig — Config realtime validée + gelée.

IClusterBackplaneTransport#

interface IClusterBackplaneTransport

Transport IPC du backplane cluster — abstrait process.send / la réception des messages relayés par le master, derrière un seam injectable (même pattern que IClusterRuntime côté ClusterManager). Permet de prouver le routage + l’anti-echo sans forker de process réel.

• send(env: ClusterBackplaneEnvelope): void — Émet une enveloppe vers le master (worker → master).
• onReceive(cb: (msg: unknown) => void): void — Enregistre le récepteur des messages IPC venus du master (master → worker).

IRedisBackplaneTransport#

interface IRedisBackplaneTransport

Transport pub/sub du backplane Redis — abstrait PUBLISH / SUBSCRIBE derrière un seam injectable (même pattern que IClusterBackplaneTransport). Permet de prouver le routage + l’anti-echo sans Redis (bus en mémoire dans les tests), et de ne PAS coupler @nodefony/realtime à la lib redis ni au module @nodefony/redis (cf createRedisServiceTransport, le seul point couplé).

• publish(channel: string, message: string): void | Promise<unknown> — Publie un message sérialisé sur le canal Redis.
• subscribe(channel: string, onMessage: (message: string) => void): void | Promise<void> — Abonne au canal Redis.
• unsubscribe(channel: string): void | Promise<void> — Désabonne du canal Redis et libère le listener associé.

IRedisPublisher#

interface IRedisPublisher

Client Redis publisher — surface structurelle minimale (compatible RedisClientType v5). Typage structurel volontaire : évite d’ajouter redis en dépendance de @nodefony/realtime.

• publish(channel: string, message: string): unknown

IRedisSubscriber#

interface IRedisSubscriber

Client Redis subscriber dédié — surface structurelle minimale (compatible RedisClientType v5). Un client abonné ne peut plus émettre de commandes normales (protocole Redis) → publisher et subscriber sont 2 connexions distinctes (cf @nodefony/redis : connexions publish / subscribe).

• subscribe(channel: string, listener: (message: string, channel: string) => unknown): unknown
• unsubscribe(channel: string, listener?: (message: string, channel: string) => unknown): unknown

Types (1)#

BackplaneFactory#

type BackplaneFactory = (ctx: IBackplaneFactoryContext) => IBackplane | null | Promise<IBackplane | null>

Fabrique d’un backplane pour un driver donné. Retourne l’instance à brancher, ou null si le driver est inactif dans ce contexte (mono-process, mauvais rôle, infra absente — le wiring laisse alors le hub local). Peut être async (ex. lecture d’un service dont l’init est asynchrone).

← Toutes les références d’API