Cadence adaptative et contre-pression — quand un client ne suit plus

stable@nodefony/realtimemis à jour 2026-10-07

Un serveur temps réel produit souvent plus vite qu’un client ne consomme. Nodefony y répond par deux étages indépendants : le client ralentit lui-même la cadence des canaux d’état qu’il écoute (AIMD), et le transport refuse d’empiler au-delà d’un seuil, puis coupe un client qui n’absorbe plus rien (contre-pression, fermeture 1013). Aucun code ne relie les deux : c’est la mesure qui les fait se rencontrer. Cette page explique chaque étage, montre leurs courbes calculées par le vrai code, et dit où les observer en production.

📍 Documentation › @nodefony/realtime › Cadence et contre-pression

🧠 Schéma général#

Deux étages, deux endroits du code, deux signaux. Les sondes, qui les observent, viennent plus bas.

• Étage 1 — la cadence adaptative, côté client : il mesure l’écart entre deux trames et se réabonne à une cadence plus lente ou plus rapide. Ce réabonnement retourne au hub, qui démarre (ou rejoint) le ticker de la nouvelle cadence : le serveur ne fait qu’honorer le nom du canal.
• Étage 2 — la contre-pression, côté serveur, trame par trame : au-delà de la file permise, la trame est jetée ; un client qui refuse plus qu’il n’accepte finit fermé.
• Les sondes comptent les clients lents et les refus, sans rien décider.

📖 Lexique#

Qu’est-ce que le problème, concrètement ?#

L’image : un robinet qui remplit un verre. Si le robinet coule plus vite que l’on boit, le verre déborde. On peut fermer un peu le robinet (c’est le rôle de la cadence adaptative), et il faut de toute façon un trop-plein qui empêche l’inondation (c’est la contre-pression).

En temps réel, le « verre » est la file d’envoi de la socket côté serveur. Un client lent — réseau mobile, onglet en arrière-plan, machine saturée — la laisse grossir. Sans garde :

• la mémoire du serveur gonfle, un client à la fois ;
• la latence explose : le client lit des valeurs vieilles de plusieurs secondes ;
• un broadcast() amplifie le problème : un seul client lent retient une diffusion entière ;
• au bout, le processus tombe à court de mémoire, et tous les clients le paient.

❗ Important

Ce n’est pas une question de débit réseau mesuré. Nodefony ne mesure jamais la bande passante d’un client : le client observe les intervalles d’arrivée des trames, le serveur observe sa file d’envoi. Ce sont deux mesures locales, simples et sans coût, qui suffisent.

La vision Nodefony — deux étages qui ne se parlent pas#

Nodefony empile deux mécanismes qui ne partagent aucun code et aucun message. Chacun agit sur ce qu’il voit lui-même :

Le point qui fait comprendre tout le reste : la contre-pression jette des trames, donc elle allonge les écarts que le client mesure ; le client y voit une famine et ralentit ; le serveur produit moins pour lui ; la file se vide. Personne n’a programmé ce dialogue : il découle de la mesure. Voir Comment les deux étages se rencontrent.

ℹ️ Note

Ni l’un ni l’autre n’appartient à JSON-RPC. Le protocole transporte des requêtes, des réponses et des notifications ; la notion de canal, de cadence et de file est propre à Nodefony. Le standard JSON-RPC 2.0 n’en dit rien, et Nodefony n’y ajoute aucun champ.

🚀 Démarrage rapide#

Le besoin vécu : ton tableau de bord affiche la charge du serveur, publiée chaque seconde. Sur le réseau d’un client en déplacement, l’écran prend du retard et la mémoire du serveur grossit. Tu veux que chaque écran tienne la cadence qu’il peut, et que le serveur ne retienne jamais un client mort.

Le contrôleur — fichier créé#

Le serveur publie à la cadence que le nom du canal demande, bornée pour se protéger. Le décorateur @RealtimeChannel ne reconnaît que des noms exacts : une famille cadencée (atelier:load, atelier:load:2000, …) passe donc par la surcharge de createRealtimeChannel(), la voie que le framework prévoit pour elle.

// modules/atelier/nodefony/controllers/AtelierController.ts
import { performance } from "node:perf_hooks";
import { controller, route } from "@nodefony/framework";
import { RealtimeController } from "@nodefony/realtime";
import type { RealtimePublish } from "@nodefony/realtime";
import type { ContextType } from "@nodefony/http";
import { isRateChannel, parseRate } from "nodefony";

/** Le canal de base, partagé avec le client. */
export const ATELIER_LOAD = "atelier:load";

/** Le serveur garde la main : jamais plus vite que 250 ms, jamais plus lent que 60 s. */
const BOUNDS = { default: 1000, min: 250, max: 60000 };

@controller("/atelier")
class AtelierController extends RealtimeController {
  constructor(context: ContextType) {
    super("atelier", context);
  }

  @route("atelier-realtime", {
    path: "/realtime",
    requirements: { methods: ["WEBSOCKET"] },
  })
  async realtime(message: string | Buffer | null): Promise<void> {
    this.handleRealtime(message);
  }

  /**
   * Sert `atelier:load` ET ses variantes `atelier:load:<ms>`.
   *
   * Le hub appelle cette fabrique au PREMIER abonné d'un canal et garde sa
   * fonction de nettoyage pour le DERNIER : un seul ticker par cadence, partagé
   * par tous ses abonnés. Il survit à la connexion qui l'a créé — il ne doit
   * donc rien capturer de `this.context`.
   */
  override createRealtimeChannel(
    channel: string,
    publish: RealtimePublish,
  ): (() => void) | null {
    if (!isRateChannel(channel, ATELIER_LOAD)) return null;
    const ms = parseRate(channel, ATELIER_LOAD, BOUNDS);
    // Utilisation de la boucle d'événements depuis le tick précédent, de 0 à 1 :
    // une mesure que Node tient déjà, identique sur Linux, macOS et Windows.
    let since = performance.eventLoopUtilization();
    const timer = setInterval(() => {
      const delta = performance.eventLoopUtilization(since);
      since = performance.eventLoopUtilization();
      publish(channel, { ts: Date.now(), load: delta.utilization });
    }, ms);
    timer.unref(); // le ticker ne retient pas l'arrêt du processus
    return () => clearInterval(timer);
  }
}

export default AtelierController;

Le client — fichier créé#

Le hook s’abonne à 1 s et laisse l’AIMD reculer ou remonter. Il rend la cadence effective, à afficher en badge.

// frontend/src/useAtelierLoad.ts
import { useNodefonyAdaptiveChannelData } from "nodefony/react";

export interface AtelierLoad {
  ts: number;
  load: number;
}

/** La charge de l'atelier, à la cadence que CE client peut tenir. */
export function useAtelierLoad(): { load: number | null; everyMs: number } {
  const { data, intervalMs } = useNodefonyAdaptiveChannelData<AtelierLoad>(
    "atelier:load",
    1000,
  );
  return { load: data?.load ?? null, everyMs: intervalMs };
}

La configuration — fichier modifié#

Deux réglages, et le second est celui qu’on oublie :

• la contre-pression est déjà active avec ses défauts ; on ne la règle que pour la serrer, et sur les deux serveurs WebSocket ;
• la garde du canal se pose par préfixe : une règle sur atelier: couvre atelier:load et toutes ses cadences. Une politique posée sur le nom exact atelier:load laisserait atelier:load:2000 ouvert à n’importe qui.

// nodefony/config/http.ts — le fragment du module, importé par le manifeste
import type { IHttpConfigInput } from "@nodefony/http";

export const httpConfig = () =>
  ({
    websocket: { maxBackpressure: 1048576, backpressureCloseAfterDrops: 200 },
    websocketSecure: {
      maxBackpressure: 1048576,
      backpressureCloseAfterDrops: 200,
    },
  }) satisfies IHttpConfigInput;

// nodefony.config.ts — extrait
import { defineConfig, use } from "nodefony";
import { httpConfig } from "./nodefony/config/http";

export default defineConfig(() => ({
  modules: [
    use("@nodefony/http", httpConfig()),
    "@nodefony/framework",
    use("@nodefony/security", {
      // Préfixe : garde atelier:load ET atelier:load:2000, atelier:load:4000…
      realtimeChannels: [{ pattern: "atelier:", authenticated: true }],
    }),
    use("@nodefony/realtime", { backplane: { driver: "loopback" } }),
    "@mon-app/atelier",
  ],
}));

Ce qu’on observe#

# La sonde du hub, sans WebSocket : clients lents et refus cumulés.
curl -sk https://127.0.0.1:5152/nodefony/realtime/api/health | jq '.backpressure'

🏗️ Étage 1 — la cadence adaptative (AIMD)#

La cadence vit dans le nom du canal#

Un canal d’état cadencé s’appelle base (cadence par défaut) ou base:<ms> (cadence explicite). Le client fabrique le nom avec rateChannel() (channelRate.ts#rateChannel), le serveur le relit et le borne avec parseRate() (channelRate.ts#parseRate). Une même fonction pour les deux bords : la convention ne peut pas diverger.

Conséquences voulues :

• 1 canal = 1 cadence = 1 ticker. Deux clients à 2 s partagent base:2000 ; un troisième à 4 s ouvre base:4000. Le hub compte les abonnés et arrête le ticker au dernier.
• Le serveur garde la main. Un client qui demande base:10 obtient la borne basse : Studio borne ses statistiques à 250 ms minimum (RATE_BOUNDS, StudioRealtimeController.ts#RATE_BOUNDS).
• Aucun message de contrôle : changer de cadence, c’est changer d’abonnement. Le protocole reste celui des canaux, rien de plus.

⚠️ Attention

Une politique de canal posée sur le nom exact ne garde pas ses cadences. Le registre des politiques s’indexe par nom : protéger atelier:load laisse atelier:load:2000 ouvert, et le hub le signale par un avertissement. Garder une famille cadencée, c’est poser une règle par préfixe (realtimeChannels, configuration de @nodefony/security) ou par motif (atelier:load:*).

Ce que le client mesure#

À chaque trame reçue, AdaptiveRate.noteFrame() (AdaptiveRate.ts#AdaptiveRate.noteFrame) compare l’écart depuis la trame précédente à la cadence courante. Trois zones, et une seule décision par trame :

Les seuils et la fenêtre sont des options (starvationFactor, healthyFactor, recoveryWindow), avec ces défauts (AdaptiveRate.ts#AdaptiveRate.constructor).

💡 Astuce

La bande morte est ce qui empêche l’oscillation : un réseau « moyen » ne fait ni monter ni descendre la cadence. Sans elle, un écart de 1,5 fois la cadence ferait basculer l’écran toutes les quelques secondes.

Ralentir vite, accélérer prudemment#

• L’échelle est géométrique : de la cadence désirée, doublée jusqu’à 60 s par défaut — 1 s, 2 s, 4 s, 8 s, …, 60 s (deriveLadder(), AdaptiveRate.ts#deriveLadder). Une échelle sur mesure se passe par l’option ladder.
• Ralentir = monter d’un cran (×2) dès la première famine. Plusieurs famines successives doublent plusieurs fois : c’est ce qui rend la décroissance multiplicative.
• Accélérer = descendre d’un seul cran après quatre écarts sains consécutifs. La reprise est lente par construction.
• Après chaque changement, la mesure repart de zéro : la première trame du nouveau canal ne sert que de référence.
• Famine totale : si plus aucune trame n’arrive, noteFrame() ne serait jamais appelé. Un chien de garde, réarmé à chaque cadence, appelle checkStarvation() (AdaptiveRate.ts#AdaptiveRate.checkStarvation) et ralentit quand même.

Changer de cadence sans trou#

L’image : on change de voie sur l’autoroute en s’insérant dans la nouvelle avant de quitter l’ancienne, jamais l’inverse. bindAdaptiveChannel() (AdaptiveRate.ts#bindAdaptiveChannel) fait pareil : il s’abonne au nouveau canal, puis quitte l’ancien, dans le même geste (applyDecision(), AdaptiveRate.ts#bindAdaptiveChannel).

Le gestionnaire de l’écran reçoit les trames des deux canaux sans interruption : la page ne voit qu’un flux dont la cadence change.

La courbe — le vrai code, sur un scénario#

Le scénario : cadence désirée 1 s ; de 20 s à 70 s, le client met 4,5 s à absorber chaque trame (réseau saturé), puis redevient rapide. La courbe est calculée en faisant tourner AdaptiveRate lui-même ; un test la rejoue et échoue si le code ne la produit plus (voir Tests).

Ce que la courbe raconte, décision par décision :

La tentative de 55 s n’est pas un défaut : c’est ainsi qu’AIMD découvre que le réseau s’est rétabli. Il sonde prudemment, recule s’il s’est trompé, et ne le paie que de quelques secondes.

Réservé aux canaux d’état#

⚠️ Attention

N’active jamais la cadence adaptative sur un canal d’événements. Ralentir un canal d’état perd des valeurs intermédiaires sans conséquence : la température de 10 h 00 min 03 s est remplacée par celle de 10 h 00 min 04 s. Sur un flux d’événements (ORDER_CREATED, PAYMENT_RECEIVED, lignes de journal), chaque message compte : ces canaux se regroupent (le pont syslog de Studio coalesce), ils ne se déciment pas.

🏗️ Étage 2 — la contre-pression du transport#

La file d’envoi et le seuil#

Quand le serveur envoie une trame, la socket l’accepte et la place dans sa file d’envoi : bufferedAmount compte les octets qui attendent le réseau. Un client qui ne lit plus fait grossir cette file sans fin. Nodefony la plafonne à maxBackpressure, 4 Mio par défaut (@nodefony/http/nodefony/config/config.ts#websocketSchema).

La décision est prise trame par trame, par une seule fonction : decideSend() (wsBackpressure.ts#decideSend). Elle sert à la fois le send()/broadcast() d’un contexte WebSocket de @nodefony/http et chaque connexion temps réel (WsConnectionTransport.send(), WsConnectionTransport.ts#WsConnectionTransport.send). Une seule règle, deux usages.

Sous le seuil, le chemin est nominal : une lecture de bufferedAmount, aucune allocation. Le coût n’apparaît que pour un client déjà en difficulté.

Le solde de refus — pourquoi pas un second seuil, pourquoi pas une série#

Deux idées naturelles échouent, et le code dit pourquoi :

• Un second seuil d’octets (« fermer à 8 Mio ») serait inatteignable : une fois qu’on jette, plus rien n’alimente la file, qui plafonne au premier seuil. Mesuré : 4000 trames poussées à un client qui ne lit pas, 3 servies, aucune fermeture.
• Une série de refus consécutifs, remise à zéro au premier envoi, ne fermerait jamais un client bloqué : sa file oscille autour du seuil (refus, un peu de vidage, un envoi, refus…), et chaque envoi effacerait la série.

D’où le solde : +1 par refus, −1 par envoi. Un pic passager redescend tout seul ; un client qui refuse plus qu’il n’accepte monte jusqu’au seuil de fermeture. C’est _nfDropStreak, tenu sur la socket elle-même.

Les courbes — le vrai code, sur deux clients#

Le scénario : le serveur pousse 100 trames de 32 Kio par seconde ; le client vide sa file à 8 Mo/s, puis tombe à 1 Mo/s à partir de 2 s. Défauts de production : seuil 4 Mio, refus, fermeture à un solde de 1000. Les valeurs sont calculées par decideSend() lui-même.

La file d’envoi plafonne au seuil — la contre-pression tient la mémoire, quelle que soit la durée :

Le solde distingue un client mort d’un pic passager. Deux clients, même début : ils ralentissent à 2 s. Le premier ne se rétablit jamais, le second se rétablit à 9 s.

• Client mort (bleu) : le solde monte d’environ 39 par seconde, l’écart entre les refus et les envois. Il atteint 1000 à 29,5 s : fermeture 1013, après 1781 trames refusées et 1166 envoyées.
• Pic passager (orange) : le solde monte jusqu’à 201, puis redescend d’une unité par envoi, donc très vite : à 12 s il est revenu à 0. Aucune fermeture.

drop ou close — choisir en situation#

⚠️ Attention

drop ne trie pas les trames. Au-delà du seuil, decideSend() jette la trame qui se présente, quelle qu’elle soit : valeur d’un canal d’état, événement métier, ou réponse à une requête RPC. Une requête dont la réponse a été jetée expire côté client. La contre-pression protège le serveur ; elle ne garantit la livraison de rien. Un flux où chaque message compte a besoin d’un accusé de réception et d’une reprise applicatifs, ou de la politique close.

Ce que voit le client#

Le client n’apprend jamais les seuils : il ne reçoit que leur effet.

• Une trame jetée n’existe pas pour lui : il voit seulement un écart plus long entre deux trames.
• Une fermeture arrive avec le code 1013. Il le classe transitoire : ce n’est pas un des codes définitifs (FATAL_CLOSE_CODES, notice.ts#FATAL_CLOSE_CODES), donc isReconnectableCloseCode() (notice.ts#isReconnectableCloseCode) répond oui, et il se reconnecte avec une attente croissante.

🔌 Comment les deux étages se rencontrent#

Aucune ligne de code ne relie la contre-pression du serveur à la cadence du client. Ils se rencontrent par la mesure :

Une seule trame jetée sur un canal cadencé suffit à doubler l’écart mesuré, donc à faire ralentir le client. La contre-pression envoie un signal au client sans lui envoyer un seul octet.

📡 Les sondes — voir le mécanisme en production#

Les sondes observent, elles ne décident rien. Elles répondent à « mes clients suivent-ils ? » sans activer de trace.

Ce que la sonde du hub expose#

RealtimeHub.probe() (RealtimeHub.ts#RealtimeHub.probe) parcourt les connexions et rend un bloc backpressure :

❗ Important

slowConsumer.bytes compte, il ne freine pas. C’est le réglage de la sonde (@nodefony/realtime), pas de la contre-pression (@nodefony/http). Le baisser fait apparaître plus de clients lents dans les écrans, sans en couper aucun.

Où la lire#

• Par HTTP, sans WebSocket : GET /nodefony/realtime/api/health, rôle d’administration requis.
• En flux, sur le canal de santé nodefony:socket ; il est lui-même cadencé (nodefony:socket:<ms>).
• Dans Studio : l’écran Cluster affiche les clients lents et la pire file, par instance.
• Côté client : la cadence effective est rendue par le hook (intervalMs), et Studio permet de basculer la cadence adaptative de ses tableaux de bord depuis le panneau temps réel (désactivée par défaut).

Le détail champ par champ et le flux de santé : Observabilité de la socket.

⚙️ Configuration#

❗ Important

Deux serveurs, deux sections : websocket (ws://) et websocketSecure (wss://). Régler l’un ne règle pas l’autre. Une application servie en wss qui ne règle que websocket garde les défauts, sans que rien ne le signale.

La table complète des réglages du module et leurs schémas : Configuration.

📜 Normes appliquées#

⚠️ Pièges#

🧪 Tests#

Deux bancs complètent, hors des suites (skill nodefony-load-test) :

• ws-backpressure-e2e.mjs — la contre-pression sur une vraie socket, file remplie par le noyau, mesure côté serveur ;
• aimd-demo.mjs — la cadence adaptative, lisible pas à pas, sur une horloge contrôlée.

Ce qui manque : aucun test ne fait jouer ensemble un vrai serveur qui jette et un vrai client qui ralentit. La rencontre des deux étages décrite plus haut découle de leur conception, elle n’est pas éprouvée de bout en bout.

cd src/nodefony && npx vitest run src/tests/AdaptiveRate.test.ts src/tests/channelRate.test.ts
cd src/packages/@nodefony/realtime && npm test
cd src/packages/@nodefony/http && npx vitest run nodefony/tests/unit/wsBackpressure.test.ts

Ce qu’il faut retenir#

1. La cadence adaptative est décidée par le client, canal d’état par canal d’état, en mesurant l’écart entre trames ; elle se traduit par un réabonnement à base:<ms>.
2. La contre-pression est décidée par le serveur, trame par trame, sur la file d’envoi ; elle jette au-delà de 4 Mio et ferme en 1013 quand le solde de refus atteint 1000.
3. Les deux se rencontrent par la mesure : une trame jetée allonge un écart, et le client ralentit.
4. Les sondes comptent (clients lents, refus) sans rien décider.
5. Rien de tout cela ne garantit la livraison : un flux où chaque message compte a besoin de sa propre reprise.

🔗 Pour aller plus loin#

• ⬆️ Retour au hub : @nodefony/realtime — la socket Nodefony · Toute la documentation
• Observabilité de la socket — la sonde champ par champ, les canaux de santé, les écrans
• Configuration — la table complète des réglages, dont la contre-pression
• Protocole — le format des trames et les codes d’erreur
• Vocabulaire — la socket, le hub, le canal, le fan-out