The http module: servers, clients, and streams

req is a Readable, res is a Writable

http.createServer((req, res) => …) hands you two stream objects, and the single most common beginner mistake is forgetting that. req is an IncomingMessage — a Readable stream of the request body, decorated with req.method, req.url, and req.headers. The headers are parsed and present immediately, but the body is not buffered for you: it arrives as stream chunks, and if you never read them, you never get the body (and the socket can stall). res is a ServerResponse — a Writable stream. You start it with res.writeHead(status, headers), push bytes with res.write(chunk), and finish with res.end().

Because the body is a stream, you consume it with stream idioms, not by reaching for a magic .body property:

import { createServer } from "node:http";

const server = createServer(async (req, res) => {
  if (req.method === "POST") {
    let body = "";
    // req is async-iterable: each chunk is a Buffer
    for await (const chunk of req) {
      body += chunk;            // (see the size-cap warning below)
    }
    res.writeHead(200, { "content-type": "application/json" });
    res.end(JSON.stringify({ received: body.length }));
    return;
  }
  res.writeHead(405).end();
});

server.listen(3000);

The equivalent event API — req.on("data", chunk => …) then req.on("end", …) — does the same thing; for await is just the modern surface over it. Either way, also handle req.on("error", …) and the 'aborted'/'close' case: a client that disconnects mid-upload fires an error on the request stream, and an unhandled stream 'error' event crashes the process.

Backpressure: write() can say “stop”

When you send a large or unknown-length response, you cannot just blast res.write() in a loop. res.write() returns a boolean: true means the chunk was flushed to the kernel socket buffer; false means it was queued in your process’s memory because the buffer is full. Ignoring that false and continuing to write is how a single slow client makes your Node heap balloon — you keep buffering data the network can’t drain yet. The contract is: when write() returns false, stop and wait for the 'drain' event before writing more.

// Manual backpressure — only continue when the buffer has room
function writeChunk(res, chunk, next) {
  if (res.write(chunk)) {
    next();                       // buffer had room, keep going
  } else {
    res.once("drain", next);      // wait until it empties
  }
}

In practice you almost never write that loop by hand. If your source is itself a stream — a file, an upstream response, a transform — pipe it and let Node manage backpressure end to end:

import { createReadStream } from "node:fs";
// pipeline propagates backpressure AND forwards errors to one place
import { pipeline } from "node:stream/promises";

await pipeline(createReadStream("./big.csv"), res);

When the body length is unknown (a stream with no content-length), Node switches the response to chunked transfer encoding automatically, sending each write() as its own framed chunk terminated by a zero-length chunk at end().

The client, the Agent, and keep-alive

When you call a downstream service thousands of times per second, connection setup cost adds up fast — and that’s exactly what the Agent is designed to eliminate. The same module is also an HTTP client: http.request(options, cb) returns a writable request stream, and http.get is the shorthand that calls req.end() for you. The response arrives as another IncomingMessage you must drain.

import { request } from "node:http";

const req = request("http://api.internal/users/1", (res) => {
  let data = "";
  res.on("data", (c) => (data += c));   // you MUST consume the response
  res.on("end", () => console.log(res.statusCode, data));
});
req.on("error", console.error);          // network errors land here
req.end();

Behind every client request is an Agent that pools sockets. The point of pooling is keep-alive: reusing a live TCP connection across requests skips a fresh TCP handshake (~1 RTT) and, on HTTPS, a full TLS handshake on top — a large per-request saving when you call the same host repeatedly. The global agent enables keepAlive by default since Node 19; before that you opted in with new Agent({ keepAlive: true }). The knob that bites under load is maxSockets — the cap on concurrent connections the agent opens per host. It defaults to Infinity, so an unbounded fan-out can open thousands of sockets at once and exhaust ports or overwhelm the upstream; set a sane maxSockets when you call a single dependency hard.

Timeouts and body limits: what http does NOT do for you

This is the senior part, and it is all about what http omits. Raw http will, by default, let a client take its time and send a body of any size. Both are denial-of-service vectors. The timeout knobs that bound a slow client are server properties:

The hook is exactly the gap requestTimeout and headersTimeout close: a Slowloris attack drips headers or body slowly to hold sockets open. With the default 300 s requestTimeout and the 60 s headersTimeout, a half-open socket is reclaimed instead of leaking forever — but if you read req.socket.setTimeout(0) or disable these on a hand-rolled server, you reopen the door.

The other omission is body size. There is no built-in limit: for await (const chunk of req) body += chunk will happily accumulate a multi-gigabyte upload into your heap and OOM-kill the process. You must cap it yourself (this is one of the main things express.json({ limit }) or body-parser do for you):

const MAX = 1_000_000; // 1 MB
let size = 0, chunks = [];
for await (const chunk of req) {
  size += chunk.length;
  if (size > MAX) {
    res.writeHead(413).end("payload too large"); // 413 Payload Too Large
    req.destroy();                                // stop reading, free the socket
    return;
  }
  chunks.push(chunk);
}