Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท HTTP, HTTPS, net, TLS, dgram and dns

Node.js http.IncomingMessage class

Reference for http.IncomingMessage: req.method, url, headers, rawHeaders, httpVersion, reading the body as a stream, and the client-side response fields.

http.IncomingMessage represents a message that arrived over HTTP. On a server it is the req argument of the request listener: what the client sent. On a client it is the response object you get from http.request() or http.get(). The same class serves both, so some properties only make sense on one side.

It is a Readable stream: the headers are already parsed when you receive it, but the body arrives as chunks you read with events, for await, or helpers such as stream/consumers. If you ignore the body of a request, drain it with req.resume() so the connection can be reused.

NODE
import http from "node:http";

http.createServer((req, res) => {
  console.log(req.method, req.url, req.headers["user-agent"]);
  res.end();
});

Try it

Node.js Inspecting a request

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Reading a request body

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
class http.IncomingMessage extends stream.Readable
Property Description
req.method Request method in upper case, such as "GET". Server only.
req.url Path and query string, such as "/a?x=1". Server only.
req.headers Parsed headers, names in lower case, values as strings. Repeated headers are joined with , (set-cookie stays an array).
req.headersDistinct Like headers, but every value is an array.
req.rawHeaders Alternating names and values exactly as received, with original casing.
req.httpVersion "1.1" or "1.0" as a string.
req.socket The underlying net.Socket; req.socket.remoteAddress is the client address.
req.complete true once the whole message was received and parsed.
req.trailers, req.rawTrailers Trailing headers, available after the body ends.
req.statusCode, req.statusMessage The status line. Client responses only.
Method Description
req.setTimeout(ms, callback?) Sets the socket timeout.
req.destroy(error?) Destroys the request and its socket.

Errors and edge cases:

  • If the client disconnects mid-body, the stream is destroyed with an error (typically ECONNRESET), so attach an error listener or use try/catch around for await.
  • Duplicate headers other than a few special ones (such as content-type, host, authorization) are joined; for singleton headers the first value is kept and the rest dropped, unless the server enables joinDuplicateHeaders.

Usage notes

  • Header names in req.headers are always lowercase: use req.headers["content-type"], never req.headers["Content-Type"].
  • req.url is not a full URL and is not decoded. Parse it with new URL(req.url, "http://localhost"); never use string splitting on user input.
  • The body is only read once. There is no req.body; frameworks add it by reading the stream for you.
  • Limit the body size when you collect it, or a client can send gigabytes. Count bytes and destroy the request when they exceed your limit.
  • req.socket.remoteAddress is the direct peer. Behind a proxy it is the proxy; the real client is in X-Forwarded-For, which can be forged unless the proxy is trusted.
  • On the client side, res.statusCode and res.headers describe the server's answer; consume or resume() the stream even if you do not need the body.