Content-Length

Utilisation

L’en-tête Content-Length communique la taille exacte, en octets, du corps du message HTTP. Les clients s’appuient sur cette valeur pour savoir quand une réponse a été intégralement reçue, ce qui rend la connexion disponible pour être réutilisée dans les connexions persistantes de HTTP/1.1.

Lorsqu’un serveur envoie une réponse dont la taille du corps est connue, l’en-tête Content-Length permet au client d’allouer la bonne quantité de mémoire et d’afficher des indicateurs de progression exacts pendant les téléchargements. Un écart entre la longueur déclarée et la taille réelle du corps signale un transfert tronqué ou corrompu.

Cet en-tête est mutuellement exclusif avec le Transfer-Encoding chunked. Lorsqu’un serveur diffuse une réponse de taille inconnue, l’encodage par fragments remplace une longueur de contenu fixe. Avec HTTP/2 et HTTP/3, le découpage en trames gère les limites de message au niveau du protocole, mais Content-Length reste valide pour valider la taille du corps.

La valeur est un unique entier positif ou nul représentant le nombre d’octets contenus dans le corps du message.

Exemple

Un serveur renvoie une réponse JSON de 3 495 octets. Le client lit exactement 3 495 octets avant de considérer le message comme complet.

Content-Length: 3495

Une requête POST envoie un corps de formulaire. L’en-tête Content-Length indique au serveur combien d’octets attendre dans le corps de la requête.

POST /submit HTTP/1.1
Host: example.re
Content-Type: application/x-www-form-urlencoded
Content-Length: 27

field=value&other=something

Une réponse utilisant l’encodage de transfert par fragments omet entièrement l’en-tête Content-Length. L’en-tête Transfer-Encoding prévaut.

Transfer-Encoding: chunked

Dépannage

Les échecs de transfert et les erreurs de connexion découlent souvent d’une valeur de Content-Length incorrecte ou contradictoire.

Transfert interrompu ou téléchargement partiel. Le client reçoit moins d’octets que ce que déclare Content-Length et signale une réponse tronquée. Causes fréquentes : le serveur d’origine ferme la connexion prématurément, un délai d’expiration de proxy coupe le transfert, ou le serveur calcule mal la taille du corps. Exécutez curl -v https://example.re/file et comparez la valeur de l’en-tête Content-Length avec le nombre d’octets réellement reçus (indiqué dans le récapitulatif de transfert). Un écart confirme le problème.

Encodage par fragments et Content-Length tous deux présents. Envoyer à la fois Transfer-Encoding: chunked et Content-Length dans la même réponse viole la spécification HTTP. Les clients doivent ignorer Content-Length lorsque Transfer-Encoding est présent, mais toutes les implémentations ne respectent pas cette règle. Supprimez Content-Length lorsque vous utilisez l’encodage par fragments. Dans nginx, l’encodage par fragments est appliqué automatiquement quand la taille du corps est inconnue, et nginx omet alors Content-Length. Le code applicatif ou l’intergiciel personnalisé qui définit les deux en-têtes doit être corrigé.

Content-Length erroné après modification du corps par un intergiciel. Un intergiciel qui injecte du contenu (scripts d’analyse, jetons de sécurité, barres d’outils de débogage) modifie la taille du corps sans mettre à jour Content-Length. Le navigateur tronque alors le contenu visible ou attend des octets qui n’arrivent jamais. Déplacez le calcul de Content-Length à l’étape finale, une fois toutes les modifications du corps terminées. Dans Express.js, l’intergiciel compression s’en charge automatiquement. Dans les montages personnalisés, supprimez Content-Length et appuyez-vous plutôt sur l’encodage par fragments.

Une réponse HEAD porte un Content-Length incorrect. Une réponse HEAD doit inclure le même Content-Length que porterait la réponse GET correspondante, mais sans corps. Certains frameworks génèrent des réponses HEAD avec un Content-Length de 0 ou omettent complètement l’en-tête. Vérifiez en comparant curl -I https://example.re/resource (HEAD) avec curl -s -o /dev/null -w ’%{size_download}’ https://example.re/resource (taille du corps en GET). Des valeurs discordantes cassent les gestionnaires de téléchargement et les proxys de cache qui s’appuient sur HEAD pour déterminer la taille d’une ressource.

Diagnostiquer les problèmes de Content-Length avec curl. Exécutez curl -v https://example.re/resource pour voir l’en-tête Content-Length et le nombre d’octets transférés dans la sortie détaillée. La ligne Content-Length: N indique la taille déclarée. À la fin, bytes received indique le transfert réel. Ajoutez -o /dev/null pour écarter le corps et vous concentrer sur les en-têtes. Pour les réponses compressées, rappelez-vous que Content-Length reflète la taille compressée, et non la taille d’origine.