Hooks React — nodefony/react

stablenodefony (cœur)mis à jour 2026-07-19

Le subpath nodefony/react branche un composant React sur la socket Nodefony sans une ligne de glue : un fournisseur au-dessus de l’arbre, puis des hooks ciblés qui s’abonnent au montage et se débranchent au démontage. Ils ne gèrent que l’abonnement — ouvrir et maintenir la connexion reste le travail du client, décrit dans Client isomorphe. Ancré sur src/nodefony/src/client/react/index.ts.

📍 Documentation › Cœur — @nodefony/core › Hooks React

🧠 Le modèle mental — une prise, N composants branchés dessus#

Un composant React vit et meurt au gré de la navigation. Une socket, elle, doit rester ouverte. Le binding tient les deux bouts : le fil est unique et long, les branchements sont nombreux et courts.

Trois idées portent toute la page :

1. Les hooks s’abonnent, ils ne connectent pas. socket.connect() est appelé une fois par l’app ; monter ou démonter un écran ne ferme jamais la socket.
2. Le comptage de références vit dans le client, pas dans React. Dix composants sur le même canal = un subscribe sur le fil ; le unsubscribe part au dernier qui se démonte.
3. Un hook = une responsabilité. Il n’y a pas de god-hook qui re-rend tout l’écran à chaque message : on compose exactement ce que la vue affiche.

📖 Lexique#

Qu’est-ce qu’un binding React — et pourquoi pas un simple useEffect#

Brancher une socket sur React « à la main » tient en dix lignes… qu’on réécrit dans chaque composant, et qui contiennent toutes le même bug. Trois pièges reviennent systématiquement.

• Le désabonnement qui coupe le voisin. Deux composants écoutent "metrics" ; le premier se démonte, envoie unsubscribe, et le second cesse silencieusement de recevoir.
• Le ré-abonnement en boucle. Le handler est recréé à chaque rendu, il entre dans les dépendances de l’effet, l’effet se rejoue, l’abonnement se refait — à chaque frappe au clavier.
• La fuite au démontage. L’écouteur reste attaché à un composant mort, qui continue d’appeler setState et de retenir tout son arbre en mémoire.

Le binding existe pour que ces trois cas soient traités une fois, au bon endroit, et prouvés.

La vision Nodefony#

Le parti pris est de mettre l’intelligence sous React, pas dedans. Le comptage de références et le ré-abonnement après coupure vivent dans NodefonySocket.subscribe() (client/realtime/NodefonySocket.ts#NodefonySocket.subscribe) et NodefonySocket.unsubscribe() (client/realtime/NodefonySocket.ts#NodefonySocket.unsubscribe), au-dessus d’une carte _subscriptions (client/realtime/NodefonySocket.ts#NodefonySocket._subscriptions).

Conséquence directe : cette autorité est partagée. Les hooks et un store applicatif (MobX, Zustand, Redux) peuvent tenir le même canal sans se marcher dessus — chacun compte pour un.

Le binding lui-même reste volontairement pauvre. Il ne fait que trois choses :

1. Publier le client dans le contexte React — NodefonyProvider (client/react/index.ts#NodefonyProvider) au-dessus d’un NodefonyContext (client/react/index.ts#NodefonyContext).
2. Capturer les handlers par référence — handlerRef (client/react/index.ts#useNodefonyChannel) : un handler redéfini à chaque rendu ne re-déclenche jamais l’abonnement, donc aucun useCallback requis.
3. Lire l’état sans tearing — useNodefonyState() (client/react/index.ts#useNodefonyState) passe par useSyncExternalStore, qui garantit une valeur cohérente en rendu concurrent.

Le fichier n’écrit aucun JSX : le fournisseur est construit par createElement. C’est ce qui permet au cœur nodefony d’être bâti sans transformation JSX, tout en livrant des hooks React.

Le compromis assumé : les hooks ne pilotent pas la connexion. Ils n’appellent ni connect() ni disconnect(). Un écran ne peut donc pas couper le temps réel du reste de l’application. C’est le fournisseur qui ouvre la connexion, une fois, quand tu lui donnes une adresse.

🚀 Démarrage rapide#

1. Le fournisseur, au-dessus de l’arbre#

Donne-lui l’adresse du serveur temps réel : il fabrique la socket et la connecte.

// frontend/src/main.tsx
import { createRoot } from "react-dom/client";
import { NodefonyProvider } from "nodefony/react";
import { Shell } from "./Shell";

createRoot(document.getElementById("root")!).render(
  <NodefonyProvider url="/api/live/realtime">
    <Shell />
  </NodefonyProvider>,
);

C’est tout le câblage : deux concepts, ce fournisseur et un hook. L’URL est relative, donc résolue contre la page — ws:// en http, wss:// en https. Une application générée par nodefony create app monte /api/live/realtime ; la console d’administration, /nodefony/studio/api/realtime.

❗ Important

Il n’y a pas d’adresse par défaut. Sans url ni client, le client refuse de démarrer avec un message qui nomme la route attendue. C’est délibéré : la route dépend de ton application, pas du framework, et une adresse devinée donnait une socket qui ne se connecte jamais et se contente de retenter — sans un mot.

Deux fournisseurs qui reçoivent la même URL partagent la même socket : une seule connexion WebSocket pour toute la page, quel que soit le nombre d’écrans montés.

2. Quand l’application possède son cycle de connexion#

Passe client au lieu de url. Le fournisseur ne touche alors ni à connect() ni à disconnect() : c’est toi qui décides. C’est le cas de la console d’administration, qui re-négocie sa socket à chaque changement d’identité (anti-élévation de privilège).

// frontend/src/realtime.ts — LA socket de l'application.
import { NodefonySocket } from "nodefony/client";

// `shared` réutilise l'instance existante pour une même URL : le shell, un widget
// et la barre de debug ouvrent UNE socket, pas trois.
export const socket = NodefonySocket.shared({
  url: "/api/live/realtime", // relative → ws:// ou wss:// selon la page
  autoReconnect: true,
});

/** À appeler une seule fois, au démarrage de l'app. */
export async function startRealtime(): Promise<void> {
  await socket.connect();
}

// frontend/src/main.tsx
import { NodefonyProvider } from "nodefony/react";
import { socket, startRealtime } from "./realtime";

void startRealtime(); // la connexion s'ouvre ici, et nulle part ailleurs

createRoot(document.getElementById("root")!).render(
  <NodefonyProvider client={socket}>
    <Shell />
  </NodefonyProvider>,
);

❗ Important

Importe NodefonySocket depuis nodefony/client, pas depuis "nodefony". Le point d’entrée racine n’expose le client qu’à travers la condition d’export browser : sans customConditions: ["browser"] dans le tsconfig.json, TypeScript lit les types serveur et répond has no exported member 'NodefonySocket'. Le subpath nodefony/client, lui, résout partout.

Après une connexion (ou une déconnexion), c’est toi qui relances la socket. L’identité d’une socket est celle de son handshake ; se connecter dans un formulaire ne la change pas. Deux cas :

• la socket a été refusée (point d’entrée protégé, visiteur anonyme) : refus au handshake (401/403, constaté par la sonde du client), état "error", et le client ne retente pas de lui-même — sinon un anonyme martèlerait le serveur. socket.retryNow() (client/realtime/NodefonySocket.ts#NodefonySocket.retryNow) rouvre immédiatement ;
• la socket était ouverte en anonyme : retryNow() ne fait rien sur une socket connectée. socket.disconnect() puis await socket.connect() renégocient le handshake avec la nouvelle session.

// frontend/src/login.ts — après un POST de connexion réussi
import { NodefonySocket } from "nodefony/client";

// Même URL → la MÊME instance que celle de `realtime.ts`, pas une seconde socket.
const socket = NodefonySocket.shared({ url: "/api/live/realtime" });

export async function afterLogin(): Promise<void> {
  if (socket.state === "error") {
    socket.retryNow(); // refusée avant le login : on rouvre
    return;
  }
  socket.disconnect(); // ouverte en anonyme : on renégocie l'identité
  await socket.connect();
}

useNodefonyIdentity() et useNodefonyState() suivent d’eux-mêmes : aucun composant n’a à être remonté.

Et quand l’application a un noyau client#

Passe kernel : le fournisseur prend la socket que le noyau a composée, sans toucher à son cycle (c’est le noyau qui l’ouvre, au démarrage ou au login), et rend le noyau lisible par useNodefonyKernel() dans tout le sous-arbre. kernel l’emporte sur client et url. Le noyau lui-même est décrit dans le client isomorphe.

const kernel = new NodefonyKernel({ realtime: { url: "/api/live/realtime" } });
void kernel.boot();

createRoot(el).render(
  <NodefonyProvider kernel={kernel}>
    <App />
  </NodefonyProvider>,
);

3. Un hook métier, bâti sur les hooks Nodefony#

C’est la forme recommandée : les hooks Nodefony restent bas niveau, ton hook porte le vocabulaire de ton domaine.

// frontend/src/useRoomPresence.ts
import { useNodefonyChannelData, useNodefonyState } from "nodefony/react";

export interface Presence {
  online: number;
  typing: string[];
}

/** Présence d'un salon : `null` tant qu'aucune trame n'est arrivée. */
export function useRoomPresence(room: string): {
  presence: Presence | null;
  live: boolean;
} {
  const live = useNodefonyState() === "connected";
  // Le nom du canal dépend de `room` → l'abonnement suit le changement de salon.
  const presence = useNodefonyChannelData<Presence>(`chat:${room}:presence`);
  return { presence, live };
}

4. L’écran qui consomme#

// frontend/src/RoomHeader.tsx
import { useRoomPresence } from "./useRoomPresence";

export function RoomHeader({ room }: { room: string }) {
  const { presence, live } = useRoomPresence(room);

  if (!live) return <p>Temps réel indisponible…</p>;
  if (!presence) return <p>Connexion au salon…</p>;
  return <p>{presence.online} personnes en ligne</p>;
}

Ce qu’on observe#

Sur le fil, un montage produit exactement deux échanges — l’accueil, puis la demande d’abonnement :

← {"jsonrpc":"2.0","method":"realtime:welcome","params":{"identity":{"authenticated":false,…}}}
→ {"jsonrpc":"2.0","method":"subscribe","params":{"channel":"chat:general:presence"}}
← {"jsonrpc":"2.0","method":"chat:general:presence","params":{"online":3,"typing":[]}}

Au démontage du dernier consommateur du canal, et seulement à ce moment :

→ {"jsonrpc":"2.0","method":"unsubscribe","params":{"channel":"chat:general:presence"}}

Ces trames se lisent en direct dans la console temps réel de Studio (/nodefony/hub).

🧰 Les hooks#

Quinze hooks et un fournisseur. La colonne re-rend quand est celle qui compte : c’est elle qui décide du coût de ton écran.

const socket = useNodefony();
const ask = () => void socket.request("chat:ask", { prompt });

function Deconnexion() {
  const kernel = useNodefonyKernel();
  const identite = useNodefonyKernelIdentity();
  if (!kernel || !identite) return null;
  return (
    <button onClick={() => kernel.setIdentity(null)}>
      Quitter {identite.key}
    </button>
  );
}

useNodefonyChannel("orders:new", (payload) => {
  playSound();
  queue.push(payload);
});

const stats = useNodefonyChannelData<Stats>("nodefony:dashboard");
if (!stats) return <p>en attente…</p>;

const intervalMs = useNodefonyAdaptiveChannel(
  "nodefony:orm:health",
  (payload) => setHealth(payload as Health),
  1000, // cadence désirée, la plus fine
);

useNodefonyAdaptiveChannelData<T>() — dernière valeur et cadence#

La composition des deux précédents : { data, intervalMs }. C’est le primitif des tuiles de supervision — une valeur à afficher, une cadence à annoncer.

const { data, intervalMs } = useNodefonyAdaptiveChannelData<Health>(
  "nodefony:orm:health",
  2000,
);

// Dans le shell de l'app, UNE fois — sinon chaque incident lève N toasts.
useNodefonyNotifications((notice) =>
  toast({ type: notice.level, message: notice.message }),
);

Fabriquer un nom de canal cadencé#

Le subpath réexporte la convention de nommage partagée avec le serveur (client/react/index.ts) — pas un hook, mais utile au même endroit :

Le point important : un canal = une cadence = un compteur de références. nodefony:orm:health:2000 et nodefony:orm:health:5000 sont deux flux distincts, jamais réconciliés.

🔑 La connexion — useNodefonyLogin()#

import { useState } from "react";
import { useNodefonyLogin } from "nodefony/react";

export function Login() {
  const { state, flow } = useNodefonyLogin();
  const [user, setUser] = useState("");
  const [pass, setPass] = useState("");
  const [code, setCode] = useState("");

  if (state.step === "authenticated")
    return <p>Bonjour {state.user?.identifier}</p>;
  if (state.step === "mfa") {
    return (
      <form
        onSubmit={(e) => {
          e.preventDefault();
          void flow.submitMfaCode(code);
        }}
      >
        <input
          value={code}
          onChange={(e) => setCode(e.target.value)}
          autoComplete="one-time-code"
        />
        <button disabled={state.pending}>Valider</button>
      </form>
    );
  }
  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        void flow.login(user, pass);
      }}
    >
      <input
        value={user}
        onChange={(e) => setUser(e.target.value)}
        autoComplete="username"
      />
      <input
        type="password"
        value={pass}
        onChange={(e) => setPass(e.target.value)}
      />
      <button disabled={state.pending}>Se connecter</button>
      {state.error && <p role="alert">{state.error.kind}</p>}
    </form>
  );
}

Le déroulé est créé UNE fois par composant (les options sont lues au premier rendu), et l’état passe par useSyncExternalStore : aucun rendu perdu, aucun abonnement laissé au démontage.

Les règles (étapes, code TOTP, blocage après trop d’essais, échecs classés, fournisseurs, passkey) vivent dans NodefonyLogin (nodefony/client) ; cette liaison ne fait que relayer son état. Le modèle complet, l’état champ par champ et ce que la classe ne fait pas : page Le client isomorphe, section NodefonyLogin.

🏗️ Cycle de vie d’un abonnement#

Le trajet complet, du montage au démontage#

Le nettoyage retire d’abord le handler, puis décrémente le compteur (client/react/index.ts#NodefonyProviderProps.url). L’ordre importe : un message en vol ne peut plus atteindre un composant démonté.

Ce qui survit à une coupure#

Après une perte de connexion, le client se reconnecte avec un délai croissant et rejoue tous les abonnements encore comptés (client/realtime/NodefonySocket.ts#NodefonySocket.mutate). Un composant monté avant la coupure retrouve son flux sans une ligne de code — et sans même savoir qu’il y a eu coupure.

Corollaire utile : s’abonner avant que la socket ne soit ouverte est sûr. Le compteur est posé, la notification partira à l’ouverture.

Le détail de la boucle de reconnexion, des codes de fermeture définitifs et du battement de cœur vit dans Client isomorphe — pas ici.

Le double montage de StrictMode#

En développement, React monte, démonte, puis remonte chaque composant. Le binding n’a aucun traitement particulier pour ce cas : il est simplement symétrique.

À retenir :

• Aucune fuite — le compteur revient exactement à sa valeur, l’écouteur est retiré.
• Un aller-retour visible sur le fil, uniquement en développement. Il disparaît en production, où React ne double pas le montage.
• Si un autre consommateur tient déjà le canal (un store, un autre écran), le compteur ne redescend jamais à zéro : rien du tout ne passe sur le fil.
• L’état local repart de zéro : un useNodefonyChannelData réaffiche null jusqu’à la trame suivante. Sur un canal lent, l’écran semble « vide » plus longtemps en développement qu’en production.

⚡ Temps réel « calme » — ne pas faire clignoter l’écran#

Un flux temps réel naïf produit un écran qui tremble : chiffres qui sautent, listes qui se réordonnent, texte illisible. La responsabilité est partagée entre la lib et ton composant.

Ce que les hooks font pour toi#

• La cadence s’adapte à la charge. Le régulateur AIMD ralentit le canal sous pression et réaccélère par paliers, avec une bande morte qui empêche l’oscillation (client/realtime/AdaptiveRate.ts#bindAdaptiveChannel).
• Le journal arrive par lots, pas ligne à ligne. Le pont serveur regroupe les entrées d’une fenêtre en une seule trame et compte les omissions — createSyslogBridge() (realtime/providers.ts#createSyslogBridge). useNodefonySyslog() consomme ce format nativement.
• L’état ne re-rend qu’aux transitions. useNodefonyState() compare un snapshot primitif ; un flux dense sur une connexion stable ne provoque aucun rendu supplémentaire.
• Les tampons sont bornés. 500 lignes de journal, 50 notices, 32 points de série : la mémoire d’un écran laissé ouvert une nuit reste plate.
• Le ré-abonnement n’est pas déclenché par un changement de handler, donc le simple fait de re-rendre ne rejoue jamais l’effet.

Ce qui reste à ta charge#

• Descendre le hook au plus près de ce qui change. Un useNodefonyChannelData dans une page entière re-rend la page entière ; dans un composant de trois lignes, il ne re-rend que ces trois lignes.

• Mémoïser le calcul dérivé, jamais le handler :

  const series = useNodefonyChannelData<Point[]>("metrics:cpu");
  const path = React.useMemo(() => toSvgPath(series ?? []), [series]);
  

• Donner une clé stable aux listes. Un index de tableau sur un flux qui s’évince par le haut remonte l’arbre entier à chaque lot — utilise l’identifiant de la ligne.

• Choisir la bonne cadence. Un affichage humain n’a pas besoin de plus de 1 à 2 mises à jour par seconde ; demander 100 ms coûte cher des deux côtés du fil pour un résultat illisible.

• Amortir l’affichage, pas le flux. Pour un compteur nerveux, arrondis ou lisse la valeur au rendu plutôt que de jeter des trames.

🔐 Rôles et identité côté client — ergonomie, jamais garantie#

useNodefonyIdentity() rend des rôles et des scopes, et le subpath nodefony/roles fournit de quoi les tester : hasRole() (client/roles/roles.ts#hasRole), hasAnyRole(), hasAllRoles(), et RoleSet (client/roles/roles.ts#RoleSet) pour des contrôles répétés en temps constant.

Leur seul usage légitime est l’ergonomie :

• masquer une entrée de menu qui mènerait à un écran refusé ;
• griser un bouton dont l’action serait rejetée ;
• afficher un écran de connexion au lieu d’un tableau vide.

🛑 Prudence

Un contrôle de rôle côté navigateur n’est pas une mesure de sécurité. Les rôles arrivent dans une trame, et une trame se falsifie. L’autorité est entièrement serveur : le pare-feu décide, et un refus revient explicitement en realtime:denied, qu’on capte via onDenied() (client/realtime/NodefonySocket.ts#NodefonySocket.onDenied) pour réagir canal par canal. Ne protège jamais une donnée en te contentant de ne pas afficher le composant qui l’affiche.

La règle pratique : cache pour le confort, refuse au serveur. Voir la sécurité du temps réel pour la moitié qui fait autorité.

📡 Observabilité — Studio#

Studio est le consommateur de référence de ces hooks, et sert de banc d’essai visuel :

• Console temps réel (/nodefony/hub) — les trames dans les deux sens, abonnements compris. La page la plus utile pour vérifier qu’un hook s’abonne à ce qu’on croit, et une seule fois.
• Jumeau vivant (/nodefony/twin) — la topologie animée par les mêmes canaux.
• Journal (/nodefony/logs) — le flux nodefony:syslog en direct.

Ce que ces écrans montrent, une app tierce l’obtient avec les mêmes hooks : rien n’est réservé à Studio.

⚠️ Pièges (symptôme → cause → correction)#

🧪 Tests & couverture#

Il faut être précis sur ce qui est prouvé, parce que le partage n’est pas intuitif : la logique testée est celle du client, pas celle des hooks.

Ce qui est couvert — les invariants dont les hooks dépendent entièrement :

• Le comptage de références : un seul subscribe pour N consommateurs, unsubscribe au dernier seulement, et le rejeu complet des abonnements après reconnexion.
• Le dispatch : ordre d’ingestion de l’accueil puis des handlers, isolation des exceptions de handler, canal générique.
• L’identité : présence après accueil, anonyme jamais null, remise à zéro au disconnect().
• Les notices : interprétation des codes de fermeture, distinction transitoire/définitif, refus de canal.
• Le transport et le ping : ouverture, fermeture, mesure d’aller-retour.
• Les rôles : hasRole, hasAnyRole, hasAllRoles, RoleSet.

Ce qui manque, et qu’il faut savoir avant de s’appuyer sur cette page :

• Les hooks de canal ne sont pas exercés en rendu. Seuls NodefonyProvider et useNodefony sont montés réellement (NodefonyProvider.test.ts, jsdom : une socket par URL, cycle d’une socket fournie respecté). Aucune suite ne monte un composant qui utilise useNodefonyChannel* : le cycle montage/démontage, le comportement en StrictMode et l’absence de re-rendu superflu restent raisonnés sur le code.
• Cinq hooks n’ont aucun consommateur dans le dépôt : useNodefonyIdentity, useNodefonyChannelStats, useNodefonySyslog, useNodefonyNotifications et useNodefonyNoticeLog. C’est précisément là que se logent les deux défauts signalés plus haut — un code que personne n’exécute n’est pas un code prouvé.
• Aucun banc de charge côté interface : le coût d’un flux dense sur un arbre React n’est pas mesuré.

Couverture : npm run coverage dans src/nodefony.

🔗 Pour aller plus loin#

• ⬆️ Retour au hub : @nodefony/core — vue d’ensemble · Toute la documentation
• 🧭 Pages sœurs : Client isomorphe — la socket, le transport, la reconnexion, les rôles · Journalisation — la forme d’une entrée de journal · Service · Contexte de requête · Kernel
• Le vocabulaire commun aux deux bords du fil → Vocabulaire de la socket
• Le module serveur qui pousse les canaux → @nodefony/realtime
• Un chat complet, du contrôleur à l’écran React → Cookbook chat
• Qui sert et reconstruit ton interface → @nodefony/frontend
• Qui décide vraiment des droits → Sécurité du temps réel