Contexte de requête (RequestContext)

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

RequestContext est une bulle invisible ouverte autour de chaque requête. Tout ce qui s’exécute dedans — ton service, ton adapter ORM, une ligne de log six couches plus bas — peut lire requestId, l’utilisateur authentifié ou le contexte transport sans qu’on les lui ait passés en argument. Deux requêtes simultanées ne se mélangent jamais. Ancré sur src/nodefony/src/runtime/RequestContext.ts.

📍 Documentation › Cœur — @nodefony/core › Contexte de requête

🧠 Le modèle mental — une bulle, pas une variable globale#

Une variable globale serait partagée par toutes les requêtes en vol : à 200 requêtes par seconde, la valeur écrite par l’une serait lue par l’autre. Un argument passé de main en main serait correct, mais il faudrait le faire traverser chaque signature de l’application.

RequestContext prend la troisième voie : Node attache un stockage à la chaîne d’exécution asynchrone. Chaque requête ouvre sa propre bulle ; tout ce qu’elle appelle hérite de la sienne, et d’aucune autre.

Trois idées portent toute la page :

1. On lit, on ne transporte pas. Aucun paramètre requestId ne traverse tes signatures.
2. La bulle a des bords nets. Elle se referme à la fin de la requête ; en dehors, tout rend undefined — jamais une valeur d’une autre requête.
3. Ce qui sort de la chaîne asynchrone sort de la bulle. Un écouteur qui se déclenche plus tard n’y est plus, sauf à l’y avoir explicitement rattaché. C’est le piège de la page.

📖 Lexique#

Qu’est-ce qu’un contexte de requête — et pourquoi le threader à la main ne tient pas#

Un serveur traite N requêtes en même temps dans un seul processus. Chacune a des données qui la caractérisent : son identifiant de corrélation, l’utilisateur authentifié, la trace distribuée. Ces données sont utiles partout, et particulièrement loin du point d’entrée — dans la ligne de log d’un repository, tout en bas.

La solution évidente — passer la valeur en argument — se dégrade en trois temps :

1. Elle contamine les signatures. save(dto) devient save(dto, requestId), puis save(dto, requestId, userId). Ces paramètres n’ont rien à voir avec le métier de la fonction.
2. Elle est virale. Un besoin nouveau (ajouter traceparent) oblige à retoucher toutes les signatures intermédiaires, y compris celles qui ne s’en servent pas — elles ne font que transmettre.
3. Elle s’arrête au code que tu possèdes. Un adapter ORM, une bibliothèque tierce ou le logger ne peuvent pas recevoir ton argument. Ce sont pourtant eux qui produisent les lignes qu’on veut corréler.

Le contexte de requête inverse la charge : la valeur est déposée à l’entrée et lue à la demande, par qui en a besoin, sans intermédiaire. Le prix à payer est une lecture implicite : rien dans la signature d’une fonction ne dit qu’elle dépend du contexte. La suite de cette page dit exactement où la bulle existe, et où elle n’existe plus.

La vision Nodefony#

RequestContext est une façade statique au-dessus d’une instance unique d’AsyncLocalStorage par processus (^{RequestContext.ts:115}). Quatre décisions de conception en découlent.

• Allocation paresseuse. L’instance n’est créée qu’au premier run() — le getter privé RequestContext.als (^{RequestContext.ts:118}). Importer la classe sans jamais ouvrir de bulle (bundle client, script CLI, test unitaire) ne coûte rien.
• Lecture à sortie rapide. RequestContext.get() (^{RequestContext.ts:131}) rend undefined sans toucher à l’ALS quand aucune bulle n’a jamais été ouverte. Le cas « pas de requête » est gratuit.
• Forme ouverte. RequestContextPayload (^{RequestContext.ts:37}) déclare les clés connues puis laisse une signature d’index : un module ajoute les siennes sans modifier le cœur. C’est ainsi que le module de sécurité y dépose son jeton complet, sans que le cœur connaisse son type.
• Un seul mécanisme pour HTTP et WebSocket. La même bulle est ouverte des deux côtés — c’est ce qui permet à un décorateur de sécurité ou à un adapter ORM d’être écrit une fois et de marcher sur les deux transports.

Le compromis assumé : le cœur type user et context en unknown (^{RequestContext.ts:65}). Le paquet nodefony ne connaît ni @nodefony/security, ni @nodefony/http — le typage précis serait une dépendance circulaire. Le consommateur rétrécit lui-même, ou passe par les helpers typés des couches au-dessus (@CurrentUser, Controller.context).

🚀 Démarrage rapide#

Lire le contexte depuis un service — rien à câbler#

Dans une app générée par nodefony create app, la bulle est déjà ouverte autour de chaque requête par le serveur HTTP. Ton code n’a qu’à lire.

// nodefony/services/InvoiceService.ts
import { RequestContext, Service } from "nodefony";

export class InvoiceService extends Service {
  pay(ref: string, amount: number): void {
    // Aucun argument de contexte dans la signature : la valeur vient de la
    // bulle de LA requête en cours. `undefined` si on appelle hors requête.
    const requestId = RequestContext.getRequestId() ?? "hors-requête";

    // `user` est posé par le firewall APRÈS authentification. Typé `unknown`
    // par le cœur (il ne connaît pas les types de la sécurité) → on rétrécit.
    const user = RequestContext.getUser() as { username?: string } | undefined;

    this.log(
      `[${requestId}] ${user?.username ?? "anonyme"} paie ${ref}`,
      "INFO",
    );

    // Raccourci quand seul l'identifiant compte (audit, clé d'idempotence).
    const userId: string | undefined = RequestContext.getUserId();
    if (userId === undefined) {
      this.log("paiement anonyme — aucune zone n'a authentifié", "WARNING");
    }
  }
}

Ouvrir sa propre bulle — un job hors requête#

Un traitement planifié, un worker, une commande CLI : aucune bulle n’est ouverte pour eux. En ouvrir une rend leurs logs corrélables exactement comme ceux d’une requête.

// nodefony/services/NightlyJob.ts
import { Nodefony, RequestContext, Service } from "nodefony";

export class NightlyJob extends Service {
  async run(): Promise<void> {
    // `run()` RENVOIE ce que renvoie la fonction — ici la promesse du corps.
    // Ne pas oublier le `await` : sans lui, la bulle se referme… mais le
    // travail continue, et les logs suivants perdent le requestId.
    await RequestContext.run(
      { requestId: `job-${Nodefony.generateId()}` },
      async () => {
        this.log("début du recalcul", "INFO");
        await this.recompute();
        this.log("fin du recalcul", "INFO"); // même requestId que ci-dessus
      },
    );
  }

  private async recompute(): Promise<void> {
    // Six couches plus bas, la lecture marche toujours.
    this.log(`en cours (${RequestContext.getRequestId()})`, "DEBUG");
  }
}

Mesurer une opération sans coûter un centime en production#

Le patron officiel pour brancher un observateur : lire le buffer une fois, dans la bulle, puis ne plus jamais relire l’ALS. C’est exactement ce que font les adapters ORM livrés.

// nodefony/services/measured.ts
import { RequestContext } from "nodefony";
import type { IProfilerQuery } from "nodefony";

export async function measured<T>(
  label: string,
  exec: () => Promise<T>,
): Promise<T> {
  // On capture la RÉFÉRENCE du buffer TANT QU'ON EST dans la bulle.
  const buffer = RequestContext.get()?.queries;

  // Buffer absent = production, ou profiler éteint → ni mesure, ni allocation.
  if (!buffer) return exec();

  const startMs = performance.now();
  const result = await exec();

  const entry: IProfilerQuery = {
    sql: label,
    startMs,
    durationMs: performance.now() - startMs,
  };
  // On pousse dans la référence capturée — surtout PAS une relecture de l'ALS :
  // après un `await` traversant un pool, elle peut être perdue.
  buffer.push(entry);

  return result;
}

Ce qu’on observe#

npx nodefony development

INFO    invoice     : [b1f2c3d4-…] alice paie INV-42
DEBUG   drizzle     : select * from invoices where id = ?   (1.4 ms)
INFO    http        : GET /api/invoices/INV-42 200 — 12 ms

Les trois lignes portent le même requestId, bien qu’aucune ne se le soit transmis : le journal le capte tout seul dans la bulle via Pdu.requestIdProvider (^Pdu.ts:212), branché sur RequestContext.getRequestId par le barrel du cœur (^{src/nodefony/src/index.ts:864}). C’est ce qui rend la trace complète d’un appel rejouable — voir Journalisation.

🧰 API publique#

Neuf membres statiques, tous sûrs hors bulle (aucun ne lève). Les signatures exactes vivent dans le graphe TSDoc (.ai/symbols.json) ; ce qui suit est l’usage.

❗ Important

set() hors bulle ne lève pas — il ne fait rien. C’est délibéré (le même code doit tourner en requête et en script), mais ça veut dire qu’une écriture peut se perdre en silence. Si l’écriture est critique, teste RequestContext.get() d’abord.

Le payload — une forme ouverte#

RequestContextPayload (^{RequestContext.ts:37}) déclare les clés que le cœur connaît, puis autorise les autres par une signature d’index. Chaque couche y dépose ce qui la concerne.

Les couches supérieures exposent ces clés sous une forme typée, à préférer quand elle existe :

🔌 Où la bulle est ouverte#

Quatre points d’ouverture, tous dans le cœur du serveur — ton code n’a jamais à ouvrir de bulle pour une requête. Le trajet complet d’une requête (phases, ordre des hooks, teardown) est décrit dans Le pipeline d’une requête ; ici, seulement qui ouvre quoi.

<!-- prettier-ignore -->

Deux points méritent d’être connus.

La bulle WebSocket survit aux trames. Une trame arrive dans un tick d’event-loop bien postérieur à la poignée de main : elle serait hors bulle. WebsocketContext.connect() (^{WebsocketContext.ts:230}) branche donc message, close et error à travers AsyncResource.bind (^{WebsocketContext.ts:243}) — la bulle est photographiée au branchement, donc depuis l’intérieur, et restaurée à chaque appel.

Le pont WS-RPC rouvre une bulle par invocation. Le contexte WebSocket vit pour toute la connexion ; y accumuler le corps, la clé d’idempotence ou les phases d’une trame produirait un mélange entre trames concurrentes de la même socket. Une bulle par invocation supprime le problème par construction.

🔬 Le seam profiler ORM — gratuit en production#

C’est l’usage le plus subtil du payload, et le patron à copier pour tout observateur.

Le serveur alloue queries (^{RequestContext.ts:57}) uniquement quand le profiler est actif, c’est-à-dire en développement (^{http-kernel.ts:1297}). En production, la clé est simplement absente. Cette absence est le signal : les adapters ORM n’ont aucun réglage à lire.

Deux lectures possibles, et elles ne sont pas équivalentes :

• RequestContext.isProfiling() (^{RequestContext.ts:179}) + RequestContext.pushQuery() (^{RequestContext.ts:189}) — le chemin simple, quand tout se passe dans la bulle.
• capturer la référence du buffer une fois (RequestContext.get()?.queries) puis pousser dedans — le chemin robuste, celui des adapters livrés : DrizzleRepository.#prof() (^{DrizzleRepository.ts:330}) et MongooseRepository.#prof() (^{MongooseRepository.ts:79}).

⚠️ Attention

Ne relis jamais l’ALS après un await qui traverse un pool. Un pilote de base de données peut rendre la main depuis sa propre file d’attente : ton code reprend alors dans une chaîne asynchrone détachée, où isProfiling() vaut false et où pushQuery() ne fait rien — sans la moindre erreur. La mesure disparaît en silence. Capturer la référence avant l’await supprime la dépendance à l’ALS pour la suite de l’opération.

Contrat de sécurité qui accompagne ce seam : un adapter qui pousse du SQL doit d’abord le masquer si le texte peut contenir un identifiant de connexion. Le SQL paramétré (avec ?, comme celui de Drizzle) est déjà sans secret ; du SQL interpolé ne l’est pas.

Isolation — deux requêtes ne se mélangent jamais#

La garantie vient de Node lui-même : l’ALS propage le store le long de la chaîne d’exécution asynchrone. Deux appels concurrents à run() créent deux stores distincts ; un await à l’intérieur de l’un ne fait jamais basculer sur l’autre.

Ce que ça implique concrètement :

• Entre requêtes : aucun partage. La bulle de A est invisible depuis B, même si A et B s’entrelacent sur des dizaines de await.
• À l’intérieur d’une requête : le payload est un seul objet, partagé par référence. C’est ce qui permet au firewall d’appeler set("user", …) en milieu de pipeline (^{firewall.ts:774}) et de rendre l’identité visible à tout ce qui tourne déjà dans la même bulle, sans rien rouvrir.
• Après run() : la bulle est refermée. get() rend de nouveau undefined — pas la valeur précédente.

Ces trois propriétés sont exercées par la suite de tests (voir plus bas), dont un cas qui fait tourner deux bulles concurrentes avec des await entrelacés et vérifie qu’aucune ne voit l’autre.

⚡ Performance & mémoire#

RequestContext est sur le chemin de chaque requête. Ce qui rend son coût acceptable :

• Rien tant que rien n’est ouvert. L’instance d’ALS n’existe qu’après le premier run() (^{RequestContext.ts:118}), et get() court-circuite sur une comparaison à null tant qu’aucune bulle n’a été ouverte (^{RequestContext.ts:131}).
• Une seule allocation par requête : l’objet payload. Il est construit au point d’entrée avec les champs déjà connus, pas enrichi au fil de l’eau.
• Le buffer ORM est null en production. Pas de tableau alloué « au cas où » ; l’absence de la clé suffit à éteindre toute la chaîne de mesure.
• Les raccourcis ne réallouent rien : getRequestId(), getUser(), getUserId() sont une lecture de store suivie d’un accès de propriété.

Sur les chiffres, la page reste factuelle : la TSDoc du code annonce ~50-100 ns par run() sur Node 22+ pour l’entrée dans le scope (^{RequestContext.ts:115}), et le même ordre de grandeur pour la lecture du requestId par le journal (^Pdu.ts:200), contre ~5 ns quand le fournisseur n’est pas branché. Il n’existe pas de banc dédié à RequestContext dans le dépôt : ces valeurs sont des ordres de grandeur documentés au code, pas une mesure rejouable. Le coût réel se constate en bout de chaîne, par le gate mémoire du pipeline (skill nodefony-check-memory-health).

⚠️ Attention

Le vrai risque mémoire n’est pas la bulle, c’est ce qui la retient. Un AsyncResource.bind posé sur un écouteur à vie longue garde le payload — donc l’utilisateur, donc le contexte transport — accessible tant que l’écouteur existe. Lier à la bulle uniquement ce qui meurt avec la requête ou la connexion.

🔐 Sécurité — l’identité vit dans la bulle#

Après authentification, le firewall dépose dans le payload l’utilisateur (^{firewall.ts:628}) et le jeton complet — rôles, périmètres, attributs (^{firewall.ts:632}). Quatre conséquences à assumer.

1. Tout ce qui tourne dans la bulle peut lire l’identité. Y compris du code que tu appelles sans l’avoir écrit. C’est la contrepartie de la commodité : le payload n’est pas un coffre-fort. On y met une identité déjà vérifiée, jamais un authentifiant (mot de passe, secret brut).
2. Lire l’identité n’est pas autoriser. getUser() rend unknown : c’est un transport, pas une décision. L’autorisation passe par le firewall et ses décorateurs, qui lisent le jeton (^{Resolver.ts:579}) et refusent en fail-closed lorsqu’aucune identité n’a été résolue.
3. Une identité de WebSocket peut vieillir. La bulle de connexion porte l’identité captée à la poignée de main, et la connexion peut durer des heures — alors que la session, elle, peut être révoquée entre-temps. C’est pourquoi le pont WS-RPC revalide l’identité à chaque invocation avant d’ouvrir sa bulle — RequestContext.run() (^{RequestContext.ts:126}) — et refuse en cas de doute, au lieu de faire confiance à la valeur capturée à la connexion. La même logique vaut pour ton code : ne mets pas en cache un getUser() au-delà d’une invocation.
4. Rien ne fuit entre requêtes, mais tout fuit hors de la bulle si on l’en sort. Ranger un RequestContext.get() dans une variable de module, un cache applicatif ou une fermeture à vie longue, c’est exposer l’identité d’un utilisateur au traitement d’un autre.

⚠️ Pièges#

Le premier est de loin le plus fréquent, et il ne produit aucune erreur — juste des valeurs undefined qui apparaissent tard.

🛑 Prudence

La règle à retenir. Tout écouteur branché dans la bulle mais déclenché plus tard (message, close, finish, une minuterie, un hook d’après-réponse) et qui doit lire le contexte doit être enveloppé dans AsyncResource.bind() au moment du branchement. Sinon il s’exécute dans un autre tick d’event-loop, hors bulle, et tout rend undefined.

C’est ainsi que le framework le fait pour toi aux deux endroits qui comptent : les événements de socket dans WebsocketContext.connect() (^{WebsocketContext.ts:243}) et les rappels d’après-réponse dans Context.onAfterResponse() (^{Context.ts:445}). Si tu branches ton écouteur sur une socket ou une minuterie, la règle est à toi de l’appliquer.

🧪 Tests & couverture#

La brique est couverte par une suite unitaire, src/nodefony/src/tests/RequestContext.test.ts. Elle exerce trois familles :

• Les bords de la bulle : get() hors scope, exposition du payload à l’intérieur, valeur de retour de run(), survie à un await, fermeture après run().
• La mutation : set() visible immédiatement via get(), et set() hors scope traité comme un no-op sans exception.
• L’isolation et le seam profiler : deux bulles concurrentes aux await entrelacés qui ne se mélangent pas ; isProfiling() faux sans buffer et hors scope avec pushQuery() inerte ; pushQuery() qui remplit bien le buffer fourni.

Ce qui n’est pas couvert ici, et qu’il faut savoir — la surface transverse de RequestContext est bien plus large que sa suite unitaire :

• Aucun test unitaire de getContext() dans cette suite, alors que c’est le chemin des contrôleurs sans état.
• La propagation réelle par le serveur (HTTP, poignée de main WebSocket, trames, après-réponse) n’est pas exercée ici : elle relève des suites d’intégration de @nodefony/http, qui couvrent la bulle WS et les rappels d’après-réponse.
• Aucun test d’attaque (*.attack.test.ts) sur le cloisonnement de l’identité entre bulles concurrentes — le scénario « la requête B lit l’utilisateur de A » mériterait d’être exercé comme invariant. Voir le skill nodefony-security-review.
• Aucun banc de charge ni de mémoire dédié : le coût de l’ALS se constate en bout de pipeline (skills nodefony-load-test et nodefony-check-memory-health).

Couverture : npm run coverage dans src/nodefony. Les chiffres exacts vivent dans le rapport vitest, jamais figés ici.

🔗 Pour aller plus loin#

• ⬆️ Retour au hub : @nodefony/core — vue d’ensemble · Toute la documentation
• 🧭 Pages sœurs : Service et événements — la classe de base qui expose log() · Journalisation — où le requestId est capté et rejoué · Kernel et modules — le boot qui câble tout ça · Client isomorphe — le bundle navigateur, où l’ALS n’existe pas · Hooks React
• Le trajet complet d’une requête, phase par phase → Le pipeline d’une requête
• Le scope d’injection par requête, à ne pas confondre avec la bulle → Injection et portées
• Qui pose l’utilisateur et le jeton dans le payload → Firewall
• L’identité côté temps réel, revalidée par trame → Sécurité du temps réel