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.
import http from "node:http"; http.createServer((req, res) => { console.log(req.method, req.url, req.headers["user-agent"]); res.end(); });
Try it
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.
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
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 anerrorlistener or usetry/catcharoundfor 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 enablesjoinDuplicateHeaders.
Usage notes
- Header names in
req.headersare always lowercase: usereq.headers["content-type"], neverreq.headers["Content-Type"]. req.urlis not a full URL and is not decoded. Parse it withnew 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.remoteAddressis the direct peer. Behind a proxy it is the proxy; the real client is inX-Forwarded-For, which can be forged unless the proxy is trusted.- On the client side,
res.statusCodeandres.headersdescribe the server's answer; consume orresume()the stream even if you do not need the body.