---
title: "Référence d'API — @nodefony/realtime — backplane"
source: docs/api/realtime/backplane.md
url: https://nodefony.github.io/nodefony-core/docs/api/realtime/backplane/
---


[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`

```ts
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`

```ts
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`

```ts
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`

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

#### `getBackplaneDriver`

```ts
function getBackplaneDriver(name: string): BackplaneFactory
```

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

#### `listBackplaneDrivers`

```ts
function listBackplaneDrivers(): string[]
```

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

#### `registerBackplaneDriver`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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](../../)