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


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

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

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

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

```ts
function buildOwnHealth(): IRealtimeHealth
```

#### `buildRealtimeHealth`

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

```ts
function createRealtimeAdminApi(): IAdminApi
```

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

#### `createSyslogUplinkHandler`

```ts
function createSyslogUplinkHandler(opts: SyslogUplinkHandlerOptions): RealtimeInboundHandler
```

Fabrique le handler du canal montant des journaux.

#### `getRealtimeHub`

```ts
function getRealtimeHub(): RealtimeHub
```

Renvoie le hub realtime du process (singleton lazy).

#### `serverSocket`

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

```ts
const ANONYMOUS_REALTIME_TOKEN: IRealtimeToken
```

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

#### `MAX_CLIENT_SEVERITY`

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

```ts
const RESERVED_SYSTEM_PREFIXES: readonly [ "nodefony:" ]
```

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

#### `SLOW_CONSUMER_BYTES`

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

```ts
const isReservedSystemChannel: typeof isPlatformChannel
```

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

### Interfaces (1)

#### `SyslogUplinkHandlerOptions`

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

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

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

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