Référence d'API — nodefony — realtime

stable

Documentation › Référence d’API › nodefony › realtime

Générée depuis les déclarations de types publiées de nodefony 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#

import { … } from "nodefony" — 54 symboles.

Classes (3)#

JsonRpcPeer#

class JsonRpcPeer<Emit extends EventsMap = DefaultEventsMap, Listen extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap> implements IRealtimePeer<Emit, Actions>

• constructor(opts: JsonRpcPeerOptions<Emit, Listen, Actions>)
• register<K extends ActionNames<Actions>>(method: K, handler: TypedRpcActionHandler<Actions, K>): void — Expose une action (requête entrante method+id → result).
• unregister(method: ActionNames<Actions>): void — Retire une action.
• get methods(): string[] — Liste des actions exposées (pour annoncer au handshake, découverte côté pair).
• request<K extends ActionNames<Actions>>(method: K, params?: ActionParams<Actions, K>, timeoutMs?: number): Promise<ActionResult<Actions, K>> — Requête SORTANTE — Promise résolue avec le result (rejette sur error/timeout).
• requestAs<A extends ActionsMap, K extends ActionNames<A>>(method: K, params?: ActionParams<A, K>, timeoutMs?: number): Promise<ActionResult<A, K>> — Requête SORTANTE typée par un contrat que l’APPELANT déclare — pour qui tient ce pair sous son contrat effacé et connaît celui de son interlocuteur.
• requestTraced<K extends ActionNames<Actions>>(method: K, params?: ActionParams<Actions, K>, timeoutMs?: number): Promise<RpcTracedResult<ActionResult<Actions, K>>> — Requête SORTANTE tracée — rend { result, meta } au lieu du result nu.
• static buildNotification(method: string, params?: unknown): JsonRpcNotification — Frame d’une notification sortante — source unique de sa forme.
• notify<K extends EventNames<Emit>>(method: K, params?: EventPayload<Emit, K>): boolean — Notification SORTANTE (pas de réponse attendue).
• receive(msg: unknown): JsonRpcFrameKind — Ingestion d’une frame ENTRANTE déjà parsée → classe (request/notification/ response) et route.
• dispose(reason?: string): void — Annule tous les pending (fermeture du transport).

RpcEnvelope#

class RpcEnvelope<T = unknown>

Réponse d’un handler qui veut JOINDRE des métadonnées serveur à son résultat.

• readonly result: T
• readonly meta: RpcMeta
• constructor(result: T, meta: RpcMeta)

RpcError#

class RpcError extends Error

Erreur RPC applicative — l’exception VOLONTAIRE au principe « throw → -32603 générique » : un handler qui rejette avec une RpcError choisit explicitement d’exposer code/message/data au pair (404 d’un path invoqué, 403 d’un voter…). Tout autre throw reste opaque (Zero Trust).

• readonly name = "RpcError"
• readonly data?: unknown
• constructor(message: string, code?: number, data?: unknown)

Fonctions (6)#

expectType#

function expectType<T>(_value: T): void

Assertion type compile-time : expectType<T>(value) échoue à la compilation si value n’est pas assignable à T. 0 coût runtime (fonction vide).

isPlatformChannel#

function isPlatformChannel(name: string): boolean

Le nom désigne-t-il une surface de la plateforme (canal OU méthode) ?

isRateChannel#

function isRateChannel(channel: string, base: string): boolean

Vrai si channel est le canal de base nu OU une de ses variantes cadencées base:<ms>.

parseRate#

function parseRate(channel: string, base: string, bounds: RateBounds): number

Résout la cadence (ms) d’un canal cadencé connu, côté serveur. Le serveur connaît la base qu’il vient de matcher ; ce helper en extrait le suffixe :<ms>, borne dans bounds et retombe sur bounds.default pour le canal de base nu ou un suffixe invalide.

rateChannel#

function rateChannel(base: string, intervalMs?: number, defaultMs?: number): string

Construit le nom d’un canal cadencé à partir de sa base et de la cadence demandée.

startsWithCI#

function startsWithCI(s: string, prefix: string): boolean

s commence-t-il par prefix, insensible à la casse et sans allocation ?

Constantes (7)#

IDENTITY_REFRESH_CLOSE_CODE#

const IDENTITY_REFRESH_CLOSE_CODE = 4005

Code de fermeture WebSocket privé (plage 4000-4999, RFC 6455 §7.4.2) : les droits de l’identité ont changé, la connexion est fermée pour que le client se RECONNECTE avec son identité à jour. À distinguer de 4001 (identité morte), après lequel le client ne se reconnecte pas.

NODEFONY_CHANNEL_NAMESPACE#

const NODEFONY_CHANNEL_NAMESPACE = "nodefony:"

Marque des surfaces de plateforme sur la socket. Un canal qui commence par ce préfixe décrit le serveur, jamais le métier de l’application.

PLATFORM_CHANNELS#

const PLATFORM_CHANNELS: { readonly syslog: "nodefony:syslog"; readonly audit: "nodefony:audit"; readonly dashboard: "nodefony:dashboard"; readonly supervision: "nodefony:supervision"; readonly debugbar: "nodefony:debugbar"; readonly socket: "nodefony:socket"; readonly ormHealth: "nodefony:orm:health"; readonly ormFlow: "nodefony:orm:flow"; readonly ormRich: "nodefony:orm:rich"; readonly scaffoldJ …

Canaux de diffusion de la plateforme (le serveur pousse, les écrans regardent).

PLATFORM_EVENTS#

const PLATFORM_EVENTS: { readonly hmr: "nodefony:hmr"; readonly debugbarSelect: "nodefony:debugbar:select"; }

Événements DOM de la plateforme (window), dans le même espace de nommage.

PLATFORM_INBOUND#

const PLATFORM_INBOUND: { readonly syslogUplink: "nodefony:syslog:uplink"; }

Canaux MONTANTS de la plateforme (le navigateur pousse, le pod reçoit).

PLATFORM_METHODS#

const PLATFORM_METHODS: { readonly ping: "nodefony:kernel:ping"; readonly gc: "nodefony:kernel:gc"; readonly scaffoldPreview: "nodefony:scaffold:preview"; readonly scaffoldRun: "nodefony:scaffold:run"; readonly scaffoldCancel: "nodefony:scaffold:cancel"; }

Méthodes RPC de la plateforme (le client demande, le serveur répond).

TransportState#

const TransportState: { readonly CONNECTING: 0; readonly OPEN: 1; readonly CLOSING: 2; readonly CLOSED: 3; }

États d’un transport — alignés sur les constantes WebSocket.

Interfaces (15)#

DefaultActionsMap#

interface DefaultActionsMap

Défaut permissif pour ActionsMap (rétro-compat).

• [method: string]: { in?: unknown; out: unknown; }

DefaultEventsMap#

interface DefaultEventsMap

Défaut permissif pour EventsMap — toute clé string, payload unknown. Code instancié sans paramétrage (new JsonRpcPeer(opts)) → comportement pré-types-partagés inchangé. Sécurité rétro-compat 100%.

• [event: string]: unknown

IChannelStats#

interface IChannelStats

Compteurs d’un canal — génériques, calculés au point d’arrivée des frames donc fiables et réutilisables par toute app. (NodefonySocket.MessageStats en est l’alias.)

• method: string — Méthode JSON-RPC == nom du canal pub/sub.
• msgCount: number — Total de notifications reçues sur ce canal.
• lastMessage: number | null — Timestamp (ms) de la dernière notification, null si aucune.
• rate: number — Débit instantané (msg/s), échantillonné 1×/s.
• series: number[] — Historique du débit (VU-mètre) — fenêtre glissante.

IRealtimeChannel#

interface IRealtimeChannel

Handle d’UN canal — vue par-canal d’un sous-flux duplex multiplexé sur la IRealtimeSocket. Forme naturelle des canaux à état (un appel SIP, une connexion bridgée) : il porte son nom, sa nature et son cycle de vie. C’est le point d’accroche des couches à venir (codec de protocole, cadence AIMD, politique drop|coalesce|batch) — elles enrichiront ce handle SANS retoucher la socket.

• readonly name: string — Nom du canal (clé de multiplexage == method JSON-RPC des notifications).
• readonly kind?: string — Nature du backing serveur (pubsub | protocol | bridge | proxy | …), annoncée par le serveur.
• on(handler: RealtimeHandler): () => void — Branche un handler de réception sur ce canal.
• send(payload?: unknown): void — Émet sur ce canal (duplex, one-way).
• open(): void — Ouvre le flux : subscribe ref-compté (demande au pair de pousser).
• close(): void — Ferme : unsubscribe ref-compté + retire les handlers branchés via ce handle.

IRealtimeDenied#

interface IRealtimeDenied

Payload de la notification système realtime:denied — poussée par le serveur quand une frame subscribe/inbound est REFUSÉE par le verrou d’autorisation (P6). Rend le refus OBSERVABLE côté client (une notification, contrairement à une requête, serait sinon droppée en silence → le client resterait aveugle).

• channel: string — Canal (ou méthode inbound) refusé(e).
• reason: RealtimeDeniedReason — Motif générique (cf RealtimeDeniedReason) — jamais le détail de la policy.
• detail?: string — Ce qui s’est passé, en clair — hors production UNIQUEMENT.

IRealtimePeer#

interface IRealtimePeer<Emit extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap>

• request<K extends ActionNames<Actions>>(method: K, params?: ActionParams<Actions, K>, timeoutMs?: number): Promise<ActionResult<Actions, K>> — Requête sortante → Promise du result (rejette sur error/timeout).
• notify<K extends EventNames<Emit>>(method: K, params?: EventPayload<Emit, K>): void — Notification sortante (pas de réponse).
• register<K extends ActionNames<Actions>>(method: K, handler: TypedRpcActionHandler<Actions, K>): void — Expose une action appelable par le pair (requête entrante → result).
• unregister(method: ActionNames<Actions>): void — Retire une action.
• receive(frame: unknown): JsonRpcFrameKind — Ingestion d’une frame ENTRANTE (déjà parsée) → classe + route.
• readonly methods: string[] — Actions exposées (découverte).
• dispose(reason?: string): void — Annule les requêtes en attente (fermeture transport).

IRealtimeSocket#

interface IRealtimeSocket<Emit extends EventsMap = DefaultEventsMap, Listen extends EventsMap = DefaultEventsMap>

Contrat de « la socket Nodefony » — voir le bloc de tête du fichier. Implémenté par NodefonySocket (front) et, à terme, par une façade serveur au-dessus du hub.

• subscribe(channel: EventNames<Listen> | (string & {})): void — S’abonne à un canal (ref-compté) : émet la demande au pair UNIQUEMENT au 1ᵉʳ consommateur ; ré-émise automatiquement à chaque (re)connexion.
• unsubscribe(channel: EventNames<Listen> | (string & {})): void — Désabonne un consommateur (ref-compté) : coupe le flux réseau au DERNIER.
• on<K extends string>(channel: K, handler: K extends EventNames<Listen> ? (payload: EventPayload<Listen, K>) => void : RealtimeHandler): () => void — Branche un handler sur un canal (réception).
• off<K extends string>(channel: K, handler: K extends EventNames<Listen> ? (payload: EventPayload<Listen, K>) => void : RealtimeHandler): void — Retire un handler d’un canal.
• publish<K extends string>(channel: K, payload?: K extends EventNames<Emit> ? EventPayload<Emit, K> : unknown): void — Émet sur un canal (one-way, pas de réponse).
• channel(name: string): IRealtimeChannel — Vue par-canal — voir IRealtimeChannel.
• getStats(): IChannelStats[] — Snapshot des compteurs par canal (refs internes — à LIRE, pas à muter).
• getChannelStats(channel: string): IChannelStats — Compteurs d’un canal précis (== method JSON-RPC) ou undefined.
• readonly subscribedChannels: string[] — Canaux actuellement abonnés (≥ 1 consommateur).

IRealtimeSubscribed#

interface IRealtimeSubscribed

Payload de la notification système realtime:subscribed — poussée par le serveur quand un subscribe est ACCEPTÉ, y compris pour un canal que la connexion suivait déjà (sans quoi un subscribe réémis attendrait un acquittement qui ne vient jamais).

• channel: string — Canal dont l’abonnement est désormais effectif sur cette connexion.

IRealtimeTransport#

interface IRealtimeTransport

• connect(): void — Ouvre le transport (asynchrone — l’ouverture effective est signalée par onOpen).
• send(raw: RealtimeOutboundData): void — Envoie une frame brute (texte sérialisé ou octets).
• close(code?: number, reason?: string): void — Ferme le transport (déclenche onClose).
• readonly readyState: number — État courant (0…3, cf TransportState).
• onOpen(cb: () => void): void — Branche le handler d’ouverture (le owner relance subscribe/heartbeat).
• onMessage(cb: (raw: RealtimeFrameData) => void): void — Branche le pump entrant : appelé pour CHAQUE frame brute reçue, texte ou binaire — jamais filtrée ici (cf RealtimeFrameData).
• onClose(cb: (code: number, reason: string) => void): void — Branche la fermeture (le owner relance le backoff ou nettoie).
• onError(cb: (err: unknown) => void): void — Branche les erreurs transport (la fermeture qui suit gère le reconnect).

IRealtimeWelcome#

interface IRealtimeWelcome

Payload de la notification système realtime:welcome — 1ʳᵉ frame poussée par le serveur juste après le handshake. Annonce le protocole, les canaux/actions découvrables de l’endpoint et l’RealtimeIdentity résolue de la connexion. Cold path (1×/connexion).

• ts: number — Timestamp serveur (ms epoch).
• protocol: string — Étiquette de protocole ("jsonrpc-2.0").
• channels: string[] — Canaux pub/sub annoncés par l’endpoint (découverte).
• methods: string[] — Actions RPC exposées par l’endpoint (découverte).
• identity: RealtimeIdentity — Identité résolue de CETTE connexion (cf RealtimeIdentity).
• env?: string — Mode d’exécution du serveur — posé UNIQUEMENT hors production.
• subscriptionAcks?: boolean — Le serveur ACQUITTE chaque abonnement accepté (realtime:subscribed, cf IRealtimeSubscribed).

JsonRpcPeerOptions#

interface JsonRpcPeerOptions<Emit extends EventsMap = DefaultEventsMap, Listen extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap>

• send: (frame: unknown) => boolean | void — Envoie une frame sérialisable sur le transport (le peer ignore le transport).
• onNotification?: RpcNotificationHandler<Listen> — Notifications entrantes (method sans id) : pub/sub côté client, subscribe/unsubscribe côté serveur.
• onError?: (context: string, err: unknown) => void — Erreur interne d’un handler — détail JAMAIS renvoyé au pair (loggé ici).
• beforeDispatch?: (frame: unknown, peer: IRealtimePeer<Emit, Actions>) => boolean — Seam sécurité 1/5 (P13 → P6) — gate beforeDispatch appelé AVANT le dispatch d’une frame entrante (request ET notification — pas les responses, passives).
• onFrameAudit?: (reason: FrameAuditReason, frame: unknown, peer: IRealtimePeer<Emit, Actions>) => void — Seam audit 5/5 (P13 → P6.14) — fire-and-forget sur évènements protocolaires notables (cf FrameAuditReason).

RateBounds#

interface RateBounds

Bornes de cadence d’un canal cadencé (toutes en millisecondes).

• readonly default: number — Cadence par défaut — celle du canal de base nu (sans suffixe).
• readonly min: number — Borne basse (cadence minimale autorisée, anti-DoS event-loop).
• readonly max: number — Borne haute (cadence maximale autorisée).

RealtimeIdentity#

interface RealtimeIdentity

Identité d’une connexion temps réel, telle que résolue par le serveur au handshake (token neutre IRealtimeToken côté back) et annoncée au client dans la notification système realtime:welcome.

• type: string — Type de token résolu ("anonymous", "session", "jwt", …) — discriminator.
• authenticated: boolean — false pour un visiteur anonyme (Zero Trust : toujours présent, jamais null).
• userIdentifier: string — Identifiant logique du porteur ("anonymous", "user-42", …).
• roles: string[] — Rôles plats (RBAC, sans hiérarchie résolue) — ["ROLE_ANONYMOUS"] si anonyme.
• scopes: string[] — Scopes accordés (clés API / OAuth) — [] en session BFF web.

RpcMeta#

interface RpcMeta

Métadonnées serveur d’une réponse RPC — transportées À CÔTÉ du result, jamais dedans (le result d’api.request doit rester identique à ce que rendrait la même route en REST : « snapshot ≡ GET REST » par construction).

• requestId?: string — Identifiant du profil de CETTE invocation (<connexion>.<n° de frame>).
• [key: string]: unknown

RpcTracedResult#

interface RpcTracedResult<T = unknown>

Résultat d’un appel sortant tracé : la valeur + la méta serveur.

• result: T
• meta?: RpcMeta

Types (23)#

ActionNames#

type ActionNames<M extends ActionsMap> = [ LiteralKeys<M> ] extends [ never ] ? string : LiteralKeys<M>

Nom valide dans une ActionsMap — même règle que EventNames.

ActionParams#

type ActionParams<M extends ActionsMap, K extends keyof M> = "in" extends keyof M[K] ? M[K] extends { in?: infer I; } ? I : undefined : undefined

Paramètres entrants d’une RPC, lus sur le in de la déclaration.

ActionResult#

type ActionResult<M extends ActionsMap, K extends keyof M> = M[K]["out"]

Résultat attendu d’une RPC (out).

ActionsMap#

type ActionsMap = Record<string, { in?: unknown; out: unknown; }>

Map des RPC — nom de méthode → { in: paramètres, out: résultat }.

ContractActionNames#

type ContractActionNames<M extends ActionsMap> = LiteralKeys<M>

Noms d’actions RÉELLEMENT déclarés par le contrat — never quand la map n’en déclare aucune (DefaultActionsMap).

ContractParams#

type ContractParams<M extends ActionsMap, K> = K extends ContractActionNames<M> ? ActionParams<M, K & keyof M> : unknown

params d’une RPC : dictés par le contrat quand K lui appartient, libres sinon. Règle UNIQUE — IRealtimeSocket, NodefonySocket et ServerRealtimeSocket la partagent au lieu de la recopier.

ContractResult#

type ContractResult<M extends ActionsMap, K, T> = K extends ContractActionNames<M> ? ActionResult<M, K & keyof M> : T

Résultat d’une RPC : dicté par le contrat quand K lui appartient, sinon le T que l’appelant demande. Pendant de ContractParams.

EventNames#

type EventNames<M extends EventsMap> = [ LiteralKeys<M> ] extends [ never ] ? string : LiteralKeys<M>

Nom valide dans une EventsMap.

EventPayload#

type EventPayload<M extends EventsMap, K extends keyof M> = M[K]

Payload typé d’un canal.

EventsMap#

type EventsMap = Record<string, unknown>

Map des canaux pub/sub — nom de canal → forme du payload.

FrameAuditReason#

type FrameAuditReason = "invalid" | "denied" | "method_not_found" | "internal_error"

Motif d’un évènement audit protocolaire (consommé par P6.14 AuditEventEntity) : - invalid : frame non conforme JSON-RPC 2.0 (cf classifyJsonRpcFrame : lot, jsonrpc≠“2.0”, id null/objet/booléen, method non chaîne, réponse sans result ni error valide). - denied : frame entrante refusée par beforeDispatch (Zero Trust realtime — voter P6 a dit non). - method_not_found : requête entrante pour une action non enregistrée (-32601 envoyée). - internal_error : handler d’action a throw (-32603 envoyée, détail loggé via onError — Zero Trust : pas renvoyé au pair).

JsonRpcErrorObject#

type JsonRpcErrorObject = IJsonRpcErrorObject

Erreur JSON-RPC 2.0 (objet error d’une réponse).

PlatformChannel#

type PlatformChannel = (typeof PLATFORM_CHANNELS)[keyof typeof PLATFORM_CHANNELS]

Nom d’un canal de plateforme (valeur de PLATFORM_CHANNELS).

PlatformInboundChannel#

type PlatformInboundChannel = (typeof PLATFORM_INBOUND)[keyof typeof PLATFORM_INBOUND]

Nom d’un canal montant de plateforme (valeur de PLATFORM_INBOUND).

PlatformMethod#

type PlatformMethod = (typeof PLATFORM_METHODS)[keyof typeof PLATFORM_METHODS]

Nom d’une méthode RPC de plateforme (valeur de PLATFORM_METHODS).

RealtimeFrameData#

type RealtimeFrameData = string | Uint8Array<ArrayBuffer>

Une frame brute telle que le transport la reçoit : du texte, ou des octets.

RealtimeHandler#

type RealtimeHandler = { handle(...args: unknown[]): void; }["handle"]

Handler d’un canal pub/sub — reçoit le params de la notification (ou (method, params) sur "*").

RealtimeOutboundData#

type RealtimeOutboundData = RealtimeFrameData

Ce qu’un transport accepte d’émettre : une frame texte déjà sérialisée, ou des octets tels quels — le même type qu’en réception (cf RealtimeFrameData).

RealtimeTransportFactory#

type RealtimeTransportFactory = (url: string) => IRealtimeTransport

Fabrique d’un transport pour une URL — injectable (tests, transports alternatifs).

RpcActionHandler#

type RpcActionHandler = (params: unknown) => unknown

Handler d’une action (requête→réponse). Sync ou async ; throw → -32603.

RpcNotificationHandler#

type RpcNotificationHandler<Listen extends EventsMap = DefaultEventsMap> = <K extends EventNames<Listen>>(method: K, params: EventPayload<Listen, K>) => void

Handler des notifications entrantes (pas de réponse). Paramétrable par Listen (map des notifications REÇUES par ce peer). Défaut permissif → comportement pré-types-partagés inchangé.

TransportStateValue#

type TransportStateValue = (typeof TransportState)[keyof typeof TransportState]

TypedRpcActionHandler#

type TypedRpcActionHandler<M extends ActionsMap, K extends keyof M & string> = (params: ActionParams<M, K>) => ActionResult<M, K> | Promise<ActionResult<M, K>>

Handler typé pour une RPC entrante (côté qui expose via register). Sync ou async — JSON-RPC 2.0 §5.1 : throw → réponse -32603 internal_error.

← Toutes les références d’API