Le pipeline d'une requête (HTTP et WebSocket)

stablemis à jour 2026-07-19

Entre l’octet reçu par la socket et l’octet renvoyé au client, une requête traverse une suite d’étapes ordonnées et nommées. Cette page te dit exactement dans quel ordre passent le parsing, le routage, la sécurité, ton contrôleur et la fin de réponse — et pourquoi une connexion WebSocket traverse le même moteur. Tout est ancré sur src/packages/@nodefony/http/nodefony/service/http-kernel.ts et nodefony/src/context/.

📍 Documentation › Pipeline de requête

🧠 Le modèle mental — un seul moteur, deux portes d’entrée#

Ailleurs, le web (requête → réponse) et le temps réel (connexion → messages) sont deux piles séparées : deux routages, deux sessions, deux façons de vérifier un droit. Le coût caché, c’est la divergence — une règle corrigée d’un côté, oubliée de l’autre.

Nodefony fait entrer les deux par des portes différentes, puis les fait converger sur un contexte commun, un routeur commun et un firewall commun. Écrire du temps réel redevient aussi banal qu’écrire une route web.

📖 Lexique#

Qu’est-ce qu’un pipeline de requête#

Un serveur ne fait pas « une » chose quand une requête arrive : il en fait une dizaine, dans un ordre qui n’est pas négociable. Décoder les en-têtes avant de router. Router avant d’authentifier — sinon on ne sait pas quelle politique appliquer. Authentifier avant d’exécuter — sinon la protection arrive trop tard.

Le pipeline, c’est ce contrat d’ordre rendu explicite. Il répond à trois questions que tout développeur finit par se poser :

1. Où brancher mon code pour qu’il voie ce dont il a besoin (l’utilisateur ? le corps parsé ?).
2. Pourquoi telle étape n’a pas eu lieu (mon firewall sur un fichier statique, par exemple).
3. Comment relier entre eux tous les logs d’une même requête.

La vision Nodefony — un contexte, deux transports#

HttpContext (^{HttpContext.ts:82}) et WebsocketContext (^{WebsocketContext.ts:83}) héritent de la même base Context (^{Context.ts:158}). Cette base porte tout ce qui définit « une requête en cours » : requestId, session, user, resolver, sessionIntent, le nonce CSP, les jetons CSRF, le traceparent et la trace de décision du firewall (^{Context.ts:184}).

Conséquence directe : un contrôleur ne sait pas — et n’a pas besoin de savoir — sur quel transport il répond. HTTP/1.1, TLS, HTTP/2 et WebSocket convergent tous vers router.resolve(context) puis vers la même instance de contrôleur.

Trois décisions structurent le reste.

1. Le rejet coûte moins cher que l’acceptation. Probes de santé, rate-limit et cap de connexions sont traités avant toute allocation de contexte, de scope DI ou de bulle ALS (HttpKernel.onHttpRequest(), ^{http-kernel.ts:944}). Un flood est refusé au prix d’une recherche dans une Map.

2. Le routage précède le parsing. Router.resolve() (^{router.ts:230}) est appelé avant de lire le corps de la requête (^{http-kernel.ts:1181}). C’est ce qui permet à une action de recevoir le flux brut plutôt qu’un corps déjà chargé en mémoire — et ce qui évite de payer le disque sur une route qui n’est pas un fichier.

3. Tout tourne dans une bulle. RequestContext.run() (^{RequestContext.ts:126}) ouvre un AsyncLocalStorage autour de la suite du pipeline. Chaque saut asynchrone en aval — log, requête ORM, décorateur de sécurité — retrouve requestId, traceparent et le contexte, sans qu’on les passe en paramètre.

❗ Important

Le contexte WebSocket vit pour toute la connexion, pas pour une trame. Son requestId est donc stable du handshake à la fermeture (^{WebsocketContext.ts:139}) — c’est la clé qui relie entre eux tous les messages d’une même socket.

🚀 Démarrage rapide#

Vue depuis une application générée par nodefony create app. Objectif : un contrôleur qui observe son propre passage dans le pipeline, en HTTP et en WebSocket.

1. Le contrôleur qui se regarde passer#

// nodefony/controllers/PipelineController.ts — complet, compile tel quel
import { Controller, controller, Get, route } from "@nodefony/framework";
import { Context } from "@nodefony/http";
import type { HttpContext, WebsocketContext } from "@nodefony/http";
import { RequestContext } from "nodefony";

@controller("/pipeline")
class PipelineController extends Controller {
  constructor(context: Context) {
    super("PipelineController", context);
  }

  // `initialize()` fait partie de la RÉSOLUTION : il tourne AVANT la session
  // et AVANT le firewall. N'y suppose jamais un utilisateur authentifié.
  async initialize(): Promise<this> {
    this.log(`résolution de ${this.route?.name}`, "DEBUG");
    return this;
  }

  @Get("/trace")
  async trace() {
    const ctx = this.context as HttpContext;
    // Ce hook tourne APRÈS le dernier octet envoyé — hors du chemin de réponse,
    // donc sans rien ajouter à la latence vue par le client.
    ctx.onAfterResponse(() => {
      this.log(`fin de requête ${ctx.requestId}`, "INFO");
    });
    return {
      // Exactement la valeur de l'en-tête `x-request-id` de la réponse.
      requestId: ctx.requestId,
      // Même valeur, lue depuis la bulle ALS : rien à porter sur `this`.
      depuisAls: RequestContext.getRequestId(),
      // Les étapes déjà chronométrées à cet instant.
      phases: ctx.phases.map((p) => p.name),
    };
  }

  // MÊME contrôleur, MÊME contexte de base : seule la déclaration change.
  @route("pipeline-ws", {
    path: "/ws",
    requirements: { methods: ["WEBSOCKET"] },
  })
  async ws(message: string | Buffer | null) {
    const ctx = this.context as WebsocketContext;
    // message === null → on est au HANDSHAKE ; sinon c'est une trame reçue.
    return this.renderJson({
      etape: message === null ? "handshake" : "trame",
      // Stable pour TOUTE la connexion — la clé de corrélation d'une socket.
      requestId: ctx.requestId,
      depuisAls: RequestContext.getRequestId(),
    });
  }
}

export default PipelineController;

(Wiring : @controllers([PipelineController]) dans le module de l’app — nodefony create controller le fait pour toi.)

2. Ce qu’on observe#

# HTTP — l'identifiant de corrélation est réfléchi dans la réponse
curl -si http://localhost:5151/pipeline/trace | grep -i x-request-id
# x-request-id: 6f1c…

curl -s http://localhost:5151/pipeline/trace
# {"requestId":"6f1c…","depuisAls":"6f1c…","phases":["resolve","parse","initialize"]}

depuisAls vaut toujours requestId : c’est la preuve que la bulle ALS est ouverte autour de ton action. Dans les logs du serveur, la même valeur apparaît sur chaque ligne émise pendant la requête.

3. Le même contrôleur, en WebSocket#

# Handshake puis une trame, sur la MÊME route déclarée plus haut
npx wscat -c ws://localhost:5151/pipeline/ws
# < {"etape":"handshake","requestId":"a3d0…","depuisAls":"a3d0…"}
# > ping
# < {"etape":"trame","requestId":"a3d0…","depuisAls":"a3d0…"}

Le requestId ne change pas entre le handshake et la trame : le contexte WebSocket vit pour toute la connexion.

🏗️ Le trajet HTTP, de l’octet reçu à l’octet renvoyé#

Le tableau ci-dessous est la même séquence, avec ce qui devient vrai à chaque étape.

Trois ordres qui surprennent (et pourquoi ils sont ainsi)#

Le routage passe avant le parsing du corps. Le match d’une route n’utilise que la méthode et l’URL : il est donc « pur ». En le hissant avant le parse (^{http-kernel.ts:1181}), le kernel peut décider de ne pas charger le corps quand l’action veut le flux brut — plus de pic mémoire sur un gros téléversement. Le résolveur est ensuite réutilisé, jamais recalculé (^{http-kernel.ts:666}).

Le statique est un repli, pas un préambule. Le kernel tente la route d’abord ; ce n’est que faute de route qu’il essaie le disque (^{http-kernel.ts:1200}). Une route d’API ne paie donc plus le stat de serve-static. Corollaire important : un fichier servi court-circuite tout ce qui suit — voir la mise en situation dédiée.

Ton contrôleur n’est instancié qu’une fois la requête autorisée. L’étape 14 se contente de MATCHER la route — prepareFrontController() (^{http-kernel.ts:767}) pose sessionIntent et bypassFirewall, que le point session et le firewall lisent juste après, et rien de plus. La construction de l’instance et l’appel d’initialize() exécutent du code utilisateur et résolvent des dépendances : ils vivent dans Resolver.executeAction(), après la garde @IsGranted (^{Resolver.ts:327}), donc après CSRF, session et firewall. Un 403 court-circuite l’instanciation — c’est ce qui rend la garde réellement Zero Trust, et non un contrôle posé sur un objet déjà construit.

Du retour d’action à l’octet#

La valeur que retourne ton action n’est pas envoyée telle quelle : Resolver.returnController() (^{Resolver.ts:697}) la normalise.

🔌 Le trajet WebSocket — handshake, trames, fermeture#

Un handshake WebSocket est une requête HTTP GET avec Upgrade. C’est pourquoi il traverse les mêmes gardes — mais son contexte, lui, survit à la poignée de main.

Ce que les deux trajets partagent, et ce qui diffère#

<!-- prettier-ignore -->

💡 Astuce

Le AsyncResource.bind() posé sur les listeners close/message (^{WebsocketContext.ts:243}) est ce qui fait que la bulle ALS survit aux trames : elles arrivent à des tours de boucle d’événements ultérieurs, hors de la bulle d’origine. Sans ce bind, un log émis au message n’aurait plus de requestId.

⚙️ Mises en situation#

Situation 1 — « je veux exécuter du code avant chaque requête »#

Le besoin : mesurer, enrichir, refuser — avant que ton contrôleur ne soit choisi. Il n’y a pas de « middleware » à empiler : il y a des points d’accroche nommés sur le kernel HTTP, que tu branches une fois, au boot du module.

// dans le module de ton app — hook onKernelReady : tout est construit
override async onKernelReady(): Promise<this> {
  const httpKernel = this.get<HttpKernel>("HttpKernel");
  // Tiré AVANT le routage, à chaque requête HTTP (et au handshake WS).
  httpKernel?.on("beforeResolve", (context: ContextType) => {
    this.log(`entrée ${context.method} ${context.url}`, "INFO");
  });
  return this;
}

Choisir son point d’accroche en cinq secondes :

⚠️ Attention

Sur le chemin HTTP, trois de ces événements ne sont émis que s’ils ont un abonné (listenerCount : ^{http-kernel.ts:1030}, :1280, :1421). C’est délibéré — sans abonné, zéro microtâche par requête. Cela ne change rien pour toi : abonne-toi, et ils partent.

Situation 2 — « pourquoi mon hook n’est pas appelé sur les fichiers statiques ? »#

Le symptôme : ton beforeResolve (ou ton firewall) voit passer /api/users, mais jamais /img/logo.png. Ce n’est pas un bug : c’est l’ordre.

Le service statique est un repli du 404, tenté juste après le routage (^{http-kernel.ts:1200}). Quand il sert un fichier, il termine la réponse lui-même — la suite du pipeline n’est jamais atteinte.

Ce qui en découle, et qu’il faut savoir : un fichier statique n’est pas protégé par le firewall. Un actif qui doit être privé ne se sert pas depuis le dossier public — il se sert par une route, derrière une zone protégée, en flux depuis ton contrôleur.

L’inverse est vrai aussi, et c’est une bonne nouvelle : les en-têtes de sécurité, eux, sont posés avant le repli statique (^{firewall.ts:835} appelé en ^{http-kernel.ts:1193}) — donc présents sur un fichier comme sur une réponse d’API.

Situation 3 — « mon erreur ne remonte pas comme je crois »#

Le besoin : comprendre ce que voit le client quand ton action lève une exception. La réponse dépend du transport, et Nodefony fait la traduction pour toi.

Côté HTTP, HttpKernel.onError() (^{http-kernel.ts:874}) délègue à un rendu remplaçable : le statut est normalisé (une erreur sans code devient 500), les en-têtes sont posés, puis le corps est rendu — sauf si le client est déjà parti ou si l’envoi a commencé (^{http-kernel.ts:773}). Tu peux substituer ton propre rendu via HttpKernel.setErrorRenderer() (^{http-kernel.ts:854}), par exemple pour émettre du application/problem+json.

Côté WebSocket, il n’existe pas de « statut » : il faut un code de fermeture valide, et la plage est piégeuse (0-999 refusé, 1004/1005/1006/1015 réservés non émissibles). toWsCloseCode() (^{WebsocketContext.ts:55}) fait la traduction une fois pour toutes :

En pratique : une action qui lève une erreur « 403 » produit un close 1008 propre côté client, sans que tu aies à connaître la table des codes.

Un dernier cas, visible dans les logs et souvent mal lu : le 499. Ce n’est pas une erreur de ton code — c’est le client qui a coupé avant d’avoir sa réponse. Le kernel l’enregistre pour l’observabilité seulement, jamais sur le fil (la socket est déjà morte, ^{http-kernel.ts:1103}).

Situation 4 — « comment corréler tous les logs d’une même requête »#

Le besoin : dans un fichier de logs qui mélange 200 requêtes concurrentes, retrouver les lignes d’une seule. La clé est le requestId, et tu n’as rien à câbler.

À la construction du contexte, requestId reçoit un UUID (^{Context.ts:244}). Il est ensuite :

1. propagé à tout l’asynchrone via la bulle ALS (^{http-kernel.ts:1151}) ;
2. posé sur chaque ligne de log émise pendant la requête (Context.log(), ^{Context.ts:442}) ;
3. réfléchi au client dans l’en-tête x-request-id de la réponse (^{Response.ts:433}) ;
4. stable pour toute une connexion WebSocket, handshake et trames compris.

Depuis n’importe quel service, sans porter le contexte :

import { RequestContext } from "nodefony";

const id = RequestContext.getRequestId(); // undefined hors requête

Si le client (ou ta passerelle) envoie déjà un X-Request-Id, Nodefony l’adopte — mais seulement après validation : sanitizeRequestId() (^{requestId.ts:38}) n’accepte que 128 caractères d’un alphabet sûr. Une valeur exotique est rejetée, pas nettoyée, et l’UUID serveur est conservé. La raison est concrète : cette valeur repart dans un en-tête et dans les logs — un CR/LF accepté ici serait une injection de logs.

Pour relier ta requête à une trace distribuée, l’en-tête W3C traceparent suit le même chemin : honoré s’il arrive, généré sinon (^{http-kernel.ts:1304}), et réfléchi dans la réponse (^{Response.ts:386}).

🔐 Où s’insèrent les défenses#

Chaque défense a une place précise dans l’ordre — et cette place est sa politique. Cette page dit où ; les pages dédiées disent comment.

Détails : Firewall · CSRF · CORS · En-têtes · Sessions · Idempotence.

📜 Normes appliquées#

⚡ Performance & mémoire#

Le pipeline est le chemin le plus chaud du framework : ce qui y est alloué l’est par requête. La règle appliquée partout est la même — ne rien allouer tant que personne ne le lit.

• Rejeter avant d’allouer : probes, rate-limit et cap de connexions WS tranchent avant le contexte, le scope DI et l’ALS (^{http-kernel.ts:848}, :865, :1368).
• Un seul listener de fin de réponse : once("close") remplace l’ancien couple finish/close avec ses deux removeListener (^{http-kernel.ts:1238}).
• Hooks tirés seulement s’ils ont un abonné : listenerCount avant fireAsync (^{http-kernel.ts:1030}, :1280, :1421) — zéro microtâche sur une app sans module de sécurité.
• Allocation paresseuse systématique : le nonce CSP n’est calculé qu’à la première lecture (^{Context.ts:192}), le signal d’abandon qu’au premier accès (^{Context.ts:402}), la liste des hooks d’après-réponse qu’au premier enregistrement (^{Context.ts:367}).
• Chronométrage désactivé par défaut en production : sans lui, phases est un tableau gelé partagé et phaseStart/phaseEnd sont des no-ops (^{Context.ts:435}).
• Le délai d’inactivité est armé par socket, pas par requête — HttpContext.setTimeout() (^{HttpContext.ts:282}) : en keep-alive, ré-armer un minuteur à chaque requête coûtait pour une valeur constante.
• Session paresseuse : ni intention de route ni cookie entrant → aucune session, aucune écriture (^{http-kernel.ts:1014}).

Les seuils sont tenus par le gate mémoire (memory.test.ts, skill nodefony-check-memory-health) et les bancs de charge (tests/load/**, skill nodefony-load-test). Un dépassement est bloquant, pas indicatif.

📡 Observabilité — Studio#

• Suivi de requête : le profileur collecte un instantané par requête au teardown (^{http-kernel.ts:1053}) — phases chronométrées, requêtes ORM, décision du firewall. Actif en développement seulement (null en production → zéro allocation).
• Profil par trame WebSocket : une connexion vit longtemps, donc chaque trame porte son propre profil, identifié <requestId de la connexion>.<n° de trame> (WebsocketContext.beginFrame(), ^{WebsocketContext.ts:423}).
• Journal d’accès : format remplaçable via HttpKernel.setRequestLogger() (^{http-kernel.ts:866}) — JSON d’audit, ligne lisible, ou le tien.
• Détail phase par phase dans les logs : opt-in timing.verbose (Context.logPhasesVerbose(), ^{Context.ts:623}).

⚠️ Pièges#

🧪 Tests & couverture#

Le pipeline est le chemin le plus éprouvé du dépôt — les chiffres exacts vivent dans la carte de l’aperçu (régénérée par gen-counters.mjs depuis vitest, jamais figée ici) :

• unitaires — wsCloseCode (la table RFC 6455), requestId (l’assainissement Zero Trust), Profiler, RequestLogger, PrettyRequestLogger, ErrorRenderer, trace (traceparent W3C), trustProxy, clientError ;
• intégration — httpKernel (le pipeline de bout en bout), static, errors, headers, health, host-misdirected (le 421), client-abort-499, timeout-abort, abort-cleanup, auto-json, body-limit, bodyStream, forward, traceparent, timing, request-context et request-context-ws (la bulle ALS), after-response et after-response-als, security-hooks (les points d’accroche), lifecycle-als, lifecycle-init-crash ;
• WebSocket — websocket, websocket-protocol, websocket-limits, websocket-fragmentation, websocket-origin (anti-CSWSH), websocket-session, websocket-w3c, websocket-binary-broadcast, websocket-trace-logging ;
• attaque — ws-data-plane-attack (le plan de données WebSocket en conditions hostiles) ;
• charge et mémoire — als-load, session-load, stream-load, ws-connections-load, ws-latency-load, ws-messages-load, plus le gate memory.test.ts. C’est le différenciateur temps réel : il est éprouvé sous charge, pas seulement en unitaire.

Ce qui manque aujourd’hui, et qu’il faut savoir : il n’existe pas de banc d’attaque dédié au pipeline HTTP lui-même (les cas hostiles sont couverts indirectement par resilience et par les bancs des briques de sécurité).

Skills utiles : nodefony-check-memory-health (gate mémoire), nodefony-load-test (charge et dimensionnement), nodefony-security-review (revue de sécurité).

Couverture : npm run coverage dans @nodefony/http.

🔗 Pour aller plus loin#

• ⬆️ Retour : Toute la documentation

• 🧭 Pages sœurs : Vue d’ensemble · Cycle de boot du Kernel · Injection & portées · Configuration

• Ce qui se passe avant la première requête → Cycle de boot du Kernel

• Le scope DI ouvert et libéré par requête → Injection & portées

• Serveurs, contextes et transports en détail → Le module HTTP — hub

• Routeur, contrôleurs et décorateurs → Le framework — hub

• Zones, authentification, autorisation → Firewall

• Sessions, cookies et stockage → Sessions

• Rejouer une mutation sans double effet → Idempotence

• La socket Nodefony, au-dessus de ce pipeline → Socket Nodefony