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

stable

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

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

import { … } from "nodefony" — 14 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>)
• get codec(): IFrameCodec — Codec de la connexion — celui qui encode les émissions (sortie write) et relit l’entrée (decode).
• set codec(codec: IFrameCodec) — Codec de la connexion — celui qui encode les émissions (sortie write) et relit l’entrée (decode).
• decode(data: string | Uint8Array): unknown — Relit une trame reçue avec le codec courant — la frame rendue se confie ensuite à receive.
• register<K extends ActionNames<Actions>>(method: K, handler: TypedRpcActionHandler<Actions, K>): void — Expose une action (requête entrante method+id → result).
• registerHandler(method: string, handler: RpcActionHandler): void — Expose une action sous un nom quelconque — la forme non typée de JsonRpcPeer.register, pour qui tient le peer sans son contrat (la socket client, qui le type par ses propres signatures).
• 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.
• requestTracedAs<A extends ActionsMap, K extends ActionNames<A>>(method: K, params?: ActionParams<A, K>, timeoutMs?: number): Promise<RpcTracedResult<ActionResult<A, K>>> — Requête SORTANTE tracée typée par un contrat que l’APPELANT déclare — requestAs qui garde la méta serveur, comme requestTraced.
• 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)

Interfaces (6)#

IJsonRpcFrameSink#

interface IJsonRpcFrameSink

Sortie d’un pair qui laisse la SÉRIALISATION à son transport : il reçoit la frame en objet. Forme historique, conservée pour les transports qui ne parlent pas de codec (relais en mémoire, tests).

• send: (frame: unknown) => boolean | void — Envoie une frame sérialisable sur le transport (le peer ignore le transport).
• write?: never
• admit?: never
• codec?: never

IJsonRpcPeerHooks#

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

Crochets d’un pair JSON-RPC, communs aux deux formes de sortie.

• 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étail JAMAIS renvoyé au pair (journalisé ici) : un handler qui lève, une réponse ou une notification que le codec ne sait pas encoder.
• beforeDispatch?: (frame: IJsonRpcRequest | IJsonRpcNotification, 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).

IJsonRpcWireSink#

interface IJsonRpcWireSink

Sortie d’un pair qui SÉRIALISE lui-même, avec son codec courant (ADR-0022 §4, ligne (i) : les codecs vivent dans le pair partagé, jamais dans le client ni dans le contrôleur). Le transport ne reçoit que des données prêtes pour le fil.

• write: (data: string | Uint8Array<ArrayBuffer>, frame: unknown) => boolean | void — Écrit une frame DÉJÀ encodée sur le transport.
• admit?: () => boolean — Contre-pression AVANT l’encodage : false → la frame n’est ni encodée ni écrite, et compte comme non émise.
• codec?: IFrameCodec — Codec du début de connexion — le texte nodefony.jsonrpc.v1 par défaut, celui de l’accueil.
• send?: never

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

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

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

JsonRpcPeerOptions#

type JsonRpcPeerOptions<Emit extends EventsMap = DefaultEventsMap, Listen extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap> = IJsonRpcPeerHooks<Emit, Listen, Actions> & (IJsonRpcFrameSink | IJsonRpcWireSink)

Options d’un JsonRpcPeer : ses crochets, et UNE sortie — send (le transport sérialise) ou write (le pair encode avec son codec).

RpcActionHandler#

type RpcActionHandler = { handle(params: unknown): unknown; }["handle"]

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é.

← Toutes les références d’API