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


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

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

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

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

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

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

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

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

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

```ts
interface RpcTracedResult<T = unknown>
```

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

- `result: T`
- `meta?: RpcMeta`

### Types (5)

#### `FrameAuditReason`

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

```ts
type JsonRpcErrorObject = IJsonRpcErrorObject
```

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

#### `JsonRpcPeerOptions`

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

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

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

#### `RpcNotificationHandler`

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