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


[Documentation](../../../) › [Référence d'API](../../) › [`@nodefony/realtime`](../) › racine

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

### Classes (2)

#### `Realtime`

```ts
class Realtime extends Module<IRealtimeConfig>
```

- `static critical: boolean` — Module optionnel : un échec de son boot ne tue jamais le process (résilience Ph.3).
- `constructor(kernel: Kernel)`
- `configSchema(): unknown` — JSON Schema de la config realtime → data plane admin (config riche Studio).
- `onKernelRegister(): Promise<this>` — Validation Zod de la config racine merge au boot (convention figée 2026-05-28, cf [[feedback_config_validation_zod]]) — via le builder `defineRealtimeConfig` (source unique `nodefony/config/config.ts` …
- `onKernelBoot(): Promise<this>` — Phase `onBoot` (avant le `mountAll` de framework dans `onReady`) — enregistre le producteur admin de la **socket Nodefony** (`/nodefony/realtime/api/*`) sur le broker `framework/AdminBroker`.
- `onKernelReady(): Promise<this>` — Phase `onReady` — inscrit au hub les politiques de canal de TOUS les contrôleurs temps réel connus, et résout leurs classes d'admission, avant que le moindre serveur n'écoute.

#### `default`

```ts
class Realtime extends Module<IRealtimeConfig>
```

- `static critical: boolean` — Module optionnel : un échec de son boot ne tue jamais le process (résilience Ph.3).
- `constructor(kernel: Kernel)`
- `configSchema(): unknown` — JSON Schema de la config realtime → data plane admin (config riche Studio).
- `onKernelRegister(): Promise<this>` — Validation Zod de la config racine merge au boot (convention figée 2026-05-28, cf [[feedback_config_validation_zod]]) — via le builder `defineRealtimeConfig` (source unique `nodefony/config/config.ts` …
- `onKernelBoot(): Promise<this>` — Phase `onBoot` (avant le `mountAll` de framework dans `onReady`) — enregistre le producteur admin de la **socket Nodefony** (`/nodefony/realtime/api/*`) sur le broker `framework/AdminBroker`.
- `onKernelReady(): Promise<this>` — Phase `onReady` — inscrit au hub les politiques de canal de TOUS les contrôleurs temps réel connus, et résout leurs classes d'admission, avant que le moindre serveur n'écoute.

### Constantes (1)

#### `BROWSER_ORIGIN`

```ts
const BROWSER_ORIGIN = "browser"
```

`moduleName` porté par une entrée de journal venue d'un NAVIGATEUR.

### Interfaces (6)

#### `IBackplaneInfo`

```ts
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) ?
- `sealRejectedTotal?: number` — Messages reçus du bus dont le sceau est refusé — unité : un message reçu d'un exemplaire, jeté parce que son sceau ne se vérifie pas (ADR-0021 S6, S9).
- `queue?: IBackplaneQueueInfo` — État de la **file d'envoi** vers le bus (octets en vol, seuil, jetés).
- `bytes?: boolean` — Les octets d'une charge traversent-ils le bus intacts (`IBackplane.enableBytes`) ?

#### `IChannelPolicy`

```ts
interface IChannelPolicy
```

Politique d'autorisation d'un canal temps réel — ce qu'il faut satisfaire pour s'y abonner (`subscribe`) ou y pousser (canal entrant), déclarée par `@RealtimeChannel(nom, politique)`.

- `readonly authenticated?: boolean` — Exige une connexion authentifiée (jeton non anonyme).
- `readonly roles?: readonly string[]` — Un de ces rôles suffit (évalué AVEC la hiérarchie de rôles, côté sécurité).
- `readonly scopes?: readonly string[]` — Un de ces scopes suffit (axe API : JWT, clé d'API ; une session n'en porte pas).
- `readonly allow?: ChannelAllow` — Règle d'admission PAR ABONNÉ, demandée une fois au `subscribe` après les exigences ci-dessus : une flèche qui ne lit que ses arguments, ou une classe `@injectable` résolue au démarrage (contrat : `ICh …
- `readonly anonymous?: boolean` — Un canal à `allow` refuse l'anonyme d'office ; `true` le lui présente (`who.id === null`).

#### `IRealtimeChannelStat`

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

```ts
interface IRealtimeClusterHealth
```

Vue **POD agrégée** de la socket (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; localOnlyTotal: number; connectionCount: number; bytesSentTotal: number; …` — Totaux pod (sommes des scalaires ; backpressure max = pire worker).

#### `IRealtimeHealth`

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

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

- `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.
- `localOnlyTotal: number` — Publications restées sur CE serveur alors qu'un bus est branché — canal non déclaré diffusable (`@RealtimeBroadcast`) — monotone ; toujours 0 sans bus.
- `systemFloorDeniedTotal: number` — Abonnements clients REFUSÉS par le plancher des canaux de plateforme — monotone.
- `sealRejectedTotal: number` — Messages du bus REFUSÉS parce que leur sceau ne se vérifie pas — monotone, unité : un message reçu d'un exemplaire.
- `frameRateRejectedTotal: number` — Trames entrantes ÉCARTÉES par la borne de débit, avant tout décodage — monotone, unité : une trame reçue.
- `allowTimedOutTotal: number` — Appels d'`allow` restés SANS RÉPONSE dans `allowTimeoutMs` — monotone, unité : un appel d'`allow`.
- `allowSaturatedTotal: number` — Demandes d'abonnement rendues `unavailable` SANS appel d'`allow` — monotone, unité : une demande.
- `authenticateTimedOutTotal: number` — Poignées de main fermées en `1013` faute d'authentification dans `authenticateTimeoutMs` — monotone, unité : une poignée de main.
- `binaryDiscardedTotal: number` — Trames BINAIRES reçues et écartées faute de lecteur — monotone, unité : une trame reçue.
- `malformedDiscardedTotal: number` — Trames reçues et écartées parce qu'illisibles par le codec de la connexion — JSON invalide, CBOR tronqué — monotone, unité : une trame reçue.
- `connectionCount: number` — Connexions realtime vivantes.
- `bytesSentTotal: number` — Somme cumulée des octets envoyés, toutes connexions, fermées comprises (monotone).
- `messagesSentTotal: number` — Somme cumulée des frames envoyées, toutes connexions, fermées comprises (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).

---

[← Toutes les références d'API](../../)