Upload & corps de requête — multipart, JSON, bornes de payload

stable@nodefony/httpmis à jour 2026-07-21

Ce qui arrive après le ? de l’URL : le corps d’une requête POST/PUT/PATCH/DELETE. Selon son Content-Type, Nodefony le parse de quatre façons — JSON, formulaire urlencodé, XML, ou multipart (les fichiers uploadés) — et le pose là où ton contrôleur le lit. Cette page décrit ce parsing, comment on accède aux champs et aux fichiers, l’API d’un fichier uploadé (nom, taille, mimetype, move), et les deux budgets de taille qui protègent le processus d’un corps trop gros. Chaque fait est ancré sur le code.

📍 Documentation › @nodefony/http › Upload & corps de requête

🧠 Le modèle mental — un corps, quatre parsers, deux budgets#

Le corps d’une requête n’est jamais interprété par le serveur ni par le routeur : c’est HttpRequest qui, selon le Content-Type, choisit un parser et remplit deux emplacements que ton contrôleur consomme — queryPost (les champs) et queryFile (les fichiers).

Trois idées portent tout le reste :

1. Le Content-Type décide, pas la méthode. parseRequest() (^{context/http/Request.ts:429}) aiguille vers ParserJson / ParserQs / ParserXml / busboy / parser brut selon l’en-tête.
2. Seul le multipart écrit sur disque. Les fichiers sont streamés au fil de l’eau vers un fichier temporaire (parseMultipart(), ^{context/http/Request.ts:499}) — jamais bufferisés en RAM. JSON / urlencoded / XML restent en mémoire (petits corps).
3. Deux budgets distincts, jamais confondus. Le corps non-multipart est borné par maxBodySize (défaut 1 MiB) ; le multipart a ses propres limites busboy (maxFileSize, maxTotalFileSize, défaut 500 MB). Régler l’un ne change rien à l’autre — c’est le piège n° 1.

📖 Lexique#

Qu’est-ce qu’un upload, ici ?#

Imagine un guichet de dépôt. Le client arrive avec une enveloppe (Content-Type) : dedans, soit un formulaire à plat (JSON, urlencodé, XML) que le guichetier recopie sur une fiche en mémoire, soit un colis (multipart) qu’il pose directement dans une consigne (le disque) sans jamais le tenir à bout de bras. Dans les deux cas, ton contrôleur ne voit pas l’enveloppe : il reçoit la fiche (queryPost) et le bordereau de consigne (queryFile).

Concrètement, la couche a quatre responsabilités, et rien d’autre :

1. Choisir le parser d’après le Content-Type.
2. Décoder les champs (JSON, urlencoded, XML) → queryPost, lus par @Body().
3. Streamer les fichiers multipart vers le disque, sans pic RAM → queryFile, lus par @UploadedFiles().
4. Borner la taille — rejeter en 413 un corps qui menace la mémoire ou le disque.

Le routage, le firewall, le contrôleur viennent après : ils reçoivent un corps déjà parsé et déjà borné.

La vision Nodefony#

Trois choix structurent l’implémentation, et chacun a une raison de sécurité ou de performance.

Le multipart ne touche jamais la RAM. Là où l’ancien chemin bufferisait le corps entier, busboy lit le flux et écrit chaque fichier au fil de l’eau dans le dossier temporaire (streamMultipart(), ^{context/http/Request.ts:537}). Un upload de 1 Go ne coûte donc pas 1 Go de heap — seuls les petits champs texte restent en mémoire. C’est ce qui rend un endpoint d’upload public tenable.

Le nom du fichier temporaire n’est jamais celui du client. Chaque fichier reçu est écrit sous un nom randomUUID() + extension d’origine (^{context/http/Request.ts:594}) : un nom malveillant (../../etc/passwd) ne peut pas influencer le chemin d’écriture. Le nom d’origine est conservé en métadonnée (filename), pas dans le chemin.

Deux budgets, secure-by-default. Le corps non-multipart est plafonné à 1 MiB par défaut (maxBodySize, ^{http/nodefony/config/config.ts:1005}) — un POST JSON géant est rejeté avant d’être bufferisé. Le multipart, lui, a ses propres bornes busboy (par fichier, cumul, nombre) qui coupent le flux et nettoient les temporaires déjà posés au moindre dépassement (^{context/http/Request.ts:481}).

❗ Important

@nodefony/http ne peut pas importer @nodefony/framework (cycle). Les décorateurs (@Body, @UploadedFiles…) vivent donc dans @nodefony/framework, mais ils lisent les emplacements (queryPost, queryFile) remplis par @nodefony/http. Une page, deux modules — c’est le prix du découplage.

🚀 Démarrage rapide#

Dans une application générée par nodefony create app, le parsing du corps est déjà branché : tu n’écris que tes bornes (si les défauts ne conviennent pas) et le contrôleur qui reçoit l’upload.

1. Les bornes de payload#

Réglées sur le module @nodefony/http, colocalisées dans le manifeste via use(). Toutes ces clés sont facultatives : ce sont les défauts du schéma, écrits ici pour les rendre visibles et les resserrer.

// nodefony.config.ts — bornes de payload de l'application
export default defineConfig(() => ({
  modules: [
    use("@nodefony/http", {
      // Corps NON-multipart (JSON, urlencoded, XML, brut) : 1 MiB par défaut.
      // Au-delà → 413 « Content Too Large ». 0 = illimité.
      maxBodySize: 1_048_576,
      upload: {
        // Chaque fichier (busboy limits.fileSize) — dépassement → 413.
        maxFileSize: 10 * 1024 * 1024, // 10 MiB
        // Cumul de TOUS les fichiers d'une même requête (compteur Nodefony).
        maxTotalFileSize: 30 * 1024 * 1024, // 30 MiB
        maxFiles: 10, // nombre de fichiers — anti-DoS
        // Intégrité optionnelle : hash calculé PENDANT le stream (0 relecture).
        hashAlgorithm: "sha256",
      },
    }),
    "@nodefony/framework",
  ],
}));

2. Le contrôleur qui reçoit l’upload#

Le pipeline a déjà streamé les fichiers sur disque et parsé les champs texte. Le contrôleur les lit par paramètres décorés — @UploadedFiles() pour les fichiers, @Body("champ") pour un champ — puis déplace chaque fichier vers son emplacement définitif.

// nodefony/controller/UploadController.ts — reçoit un upload multipart
import {
  Controller,
  controller,
  Post,
  Body,
  UploadedFiles,
} from "@nodefony/framework";
import type { ContextType, IUploadedFile } from "@nodefony/http";
import path from "node:path";

@controller("/avatars")
class UploadController extends Controller {
  constructor(context: ContextType) {
    super("UploadController", context);
  }

  // multipart/form-data : les fichiers arrivent DÉJÀ écrits en temp (streaming
  // busboy), les champs texte via @Body(). @UploadedFile() donnerait le premier.
  @Post("/")
  async upload(
    @UploadedFiles() files: IUploadedFile[] | undefined,
    @Body("label") label: string | undefined,
  ) {
    const saved: Array<{ name: string; size: number }> = [];
    for (const file of files ?? []) {
      // SÉCURITÉ : le temp est nommé par un UUID (jamais le nom client). Pour la
      // DESTINATION, on impose NOTRE nom — jamais file.filename brut (traversal).
      const safeName = `${Date.now()}-${path.basename(file.filename)}`;
      const dest = path.resolve("/var/app/uploads", safeName);
      await file.moveAsync(dest); // variante non bloquante (recommandée)
      saved.push({ name: file.filename, size: file.size });
    }
    return this.renderJson({ label: label ?? null, files: saved });
  }
}

export default UploadController;

3. Vérifier depuis le terminal#

# multipart : un champ texte + un fichier, sur le port TLS
curl -k -F "label=profil" -F "file=@./photo.png" https://127.0.0.1:5152/avatars/
# {"label":"profil","files":[{"name":"photo.png","size":12345}]}

# corps JSON non-multipart > maxBodySize (1 MiB) → rejet avant lecture
curl -k -X POST -H "content-type: application/json" \
     --data-binary @big.json https://127.0.0.1:5152/avatars/
# HTTP/2 413  (Request body too large)

🏗️ Architecture interne — le trajet d’un corps multipart#

Une requête multipart traverse HttpRequest → busboy → disque → UploadService, puis atterrit dans le contrôleur avec queryFile/queryPost déjà remplis.

Les points d’implémentation qui expliquent des comportements surprenants :

1. L’aiguillage lit le Content-Type, pas la méthode — parseRequest() (^{context/http/Request.ts:292}). PATCH porte un corps comme POST/PUT : il figure dans la table des méthodes parsées (^{context/http/Request.ts:63}) — l’oubli laissait tout PATCH avec un corps vide.
2. Le multipart draine sur un finish, après flush de tous les writes — streamMultipart() (^{context/http/Request.ts:537}) accumule les Promise d’écriture disque et ne résout { fields, files } qu’une fois tous les fichiers fermés (^{context/http/Request.ts:538}).
3. Une limite dépassée nettoie les temporaires déjà posés — abort() (^{context/http/Request.ts:557}) délie le flux, détruit les write-streams ouverts et unlink les temp déjà écrits (^{context/http/Request.ts:568}) avant de rejeter en 413 : pas d’orphelins sur le disque.
4. Les autres formats drainent AVANT de concaténer — la base Parser.parse() attend end (^{context/http/parser.ts:111}) avant Buffer.concat : sans ce drain, ParserQs/ParserXml lisaient un corps partiel → queryPost vide (bug de régression, cf tests).
5. Un multipart sans boundary exploitable ne crashe pas — new Busboy() lève synchroniquement ; c’est rattrapé et on bascule sur le Parser brut (^{context/http/Request.ts:375}).

⚙️ Configuration — deux budgets, jamais confondus#

C’est la distinction la plus utile de cette page. Le multipart n’écoute pas maxBodySize ; le non-multipart n’écoute pas upload.*.

Corps non-multipart — maxBodySize#

Deux rideaux, tous deux runtimeMutable (éditable à chaud) : un pré-check sur Content-Length qui rejette avant de lire (enforceBodyLimit(), ^{context/http/Request.ts:296}), puis un compteur en streaming qui coupe le socket si le corps déborde sans Content-Length honnête — chunked ou menteur (Parser.write(), ^{context/http/parser.ts:33}, dépassement ^{context/http/parser.ts:44}). Champ maxBodySize du schéma : ^{config/config.ts:1005}.

Fichiers multipart — upload.*#

Table dérivée de uploadSchema (^{config/config.ts:144}). Toutes les bornes sont runtimeMutable.

⚠️ Attention

uploadDir vide est résolu au boot sur le répertoire temporaire du kernel par le builder de config (^{defineModuleConfig.ts:43}) : un défaut vide n’est jamais un chemin vide en runtime. Ne dérérérence jamais le kernel au top-level d’un config.ts — c’est la raison du champ marqué kernelDerived.

🧰 API — accéder aux champs et aux fichiers#

Depuis un contrôleur, deux surfaces équivalentes : les décorateurs de paramètre (déclaratif, recommandé) et les getters de Controller (impératif). Les signatures exactes vivent dans .ai/symbols.json — jamais recopiées ici.

Les décorateurs @UploadedFile / @UploadedFiles sont des fabriques de paramètre (^{routerDecorators.ts:1240}), exportées par @nodefony/framework ; leurs interfaces IUploadedFile / IParsedUploadFile viennent de @nodefony/http (^{interfaces/IUpload.ts:49}, ^{interfaces/IUpload.ts:7}).

Un fichier uploadé — UploadedFile#

Chaque entrée de queryFile est un UploadedFile (^{service/upload/upload-service.ts:96}), déjà écrit sur disque. Ses membres utiles :

move/moveAsync acceptent un fichier cible ou un dossier existant : sur un dossier, la destination est bâtie avec filename — d’où l’avertissement de sécurité ci-dessous.

Gros upload sans pic mémoire — @Body({ stream: true })#

Pour piper directement un très gros corps (vidéo, backup) vers le disque ou S3 sans passer par busboy ni par la RAM, @Body({ stream: true }) court-circuite le parse et injecte l’IncomingMessage brut (un Readable). Le pipeline sait le sauter en amont via routeExpectsBodyStream() (^{routerDecorators.ts:1365}), mémoïsé sur la route.

// fragment — le contrôleur pipe le flux lui-même (0 parse, 0 pic RAM)
@Post("/backup")
async backup(@Body({ stream: true }) body: NodeJS.ReadableStream) {
  await pipeline(body, createWriteStream("/var/app/backup.tar")); // node:stream/promises
  return this.renderJson({ ok: true });
}

🔐 Sécurité#

L’upload est une surface d’attaque classique : nom de fichier hostile, saturation disque/RAM, contenu piégé. Les défenses en place, et ce qui reste à ta charge.

<!-- prettier-ignore -->

⚠️ Attention

Path traversal sur la destination. move(dir) / moveAsync(dir) vers un dossier construit le chemin final avec file.filename — le nom client (^{service/upload/upload-service.ts:197}). Un nom ../../etc/cron.d/x s’échapperait du dossier. Le framework protège le chemin du temporaire, pas celui que tu choisis. Règle : passe une cible complète que tu contrôles, ou assainis toujours avec path.basename(file.filename) — exactement le safeName du Démarrage rapide.

⚡ Performance & mémoire#

Le parsing du corps est sur le chemin de chaque requête écrivante — les choix visibles dans le code :

• Multipart en flux pur — plus de double-bufferisation : busboy écrit sur disque au fil de l’eau, seuls les champs texte restent en mémoire (^{context/http/Request.ts:400}).
• Rejet AVANT lecture — le pré-check Content-Length renvoie 413 sans lire un octet (^{context/http/Request.ts:400}) ; le compteur streaming libère immédiatement la RAM déjà bufferisée au dépassement (^{context/http/parser.ts:43}).
• stat non bloquant — UploadedFile.create() résout les stats du fichier en async (^{service/upload/upload-service.ts:130}), plus de lstatSync par fichier uploadé.
• Listeners jumeaux nettoyés — le drain de fin de corps retire ses écouteurs end/error/overflow à la main (once n’auto-détache que celui qui fire) (^{context/http/parser.ts:88}).
• Hash opt-in — hashAlgorithm: false par défaut : zéro coût CPU tant que l’intégrité n’est pas demandée.

Rejouer une charge d’upload : skill nodefony-load-test. Gate mémoire avant tout commit touchant le pipeline : npm run test:memory (skill nodefony-check-memory-health).

📜 Normes appliquées#

⚠️ Pièges#

🧪 Tests & couverture#

Les chiffres exacts vivent dans la carte de tests de cette page (régénérée depuis vitest, jamais figés dans le Markdown).

Ce qui manque aujourd’hui : pas de banc de charge dédié à l’upload (le streaming multipart n’est exercé que fonctionnellement), pas de test d’attaque (*.attack.test.ts) sur le path traversal de move() dans un dossier, et les bornes maxFiles / maxFields / maxFieldsSize ne sont pas couvertes individuellement (seules maxFileSize et maxTotalFileSize le sont).

Suites : npm test (unitaires), npm run test:integration (serveur requis). Couverture : npm run coverage dans @nodefony/http — le pourcentage vit dans le rapport vitest, jamais figé ici. Skills associés : nodefony-load-test, nodefony-check-memory-health, nodefony-security-review.

🔗 Pour aller plus loin#

• ⬆️ Retour au hub : @nodefony/http — vue du module · Toute la documentation
• 🧭 Pages sœurs : Serveurs · Sessions
• Bornes de payload globales et transport → Serveurs § Bornes de payload
• Le pipeline qui reçoit ce corps parsé → pipeline-requete
• Routage, contrôleurs et décorateurs @Body/@UploadedFiles → @nodefony/framework
• Configuration d’application (defineConfig, use) → configuration