Connection tuning
Connection pools, HTTP/1.1, IP families and the local address.
The defaults suit most uses. These options matter when you send many requests to the same hosts or need to control how connections are opened.
Connection pool
transportOptions controls the session's keep-alive pool:
const session = new Session({
transportOptions: {
maxIdleConnsPerHost: 10, // keep up to 10 warm connections per host
maxConnsPerHost: 20, // never open more than 20 at once per host
idleConnTimeout: 90 * 1e9, // nanoseconds: close idle connections after 90 s
},
});| Option | Effect |
|---|---|
maxIdleConns | Idle keep-alive connections kept across all hosts. |
maxIdleConnsPerHost | Idle keep-alive connections kept per host. |
maxConnsPerHost | Total connections (idle + active) per host; extra requests wait for a free one. |
idleConnTimeout | How long an idle connection stays open, in nanoseconds (90 * 1e9 = 90 s). |
disableKeepAlives | Open a new connection for every request. |
disableCompression | Don't request or decode gzip/deflate automatically. |
maxResponseHeaderBytes | Limit on response header size. 0 uses the default. |
readBufferSize / writeBufferSize | Socket buffer sizes in bytes. 0 uses the default (about 4 KB). |
Fields you leave out keep their defaults. See TransportOptions.
Forcing HTTP/1.1
forceHttp1: true skips HTTP/2, e.g. for servers or proxies with broken HTTP/2 support:
const http1 = new Session({ forceHttp1: true });
const res = await http1.get("https://httpbin.org/get");
console.log(res.usedProtocol); // HTTP/1.1A browser profile normally negotiates HTTP/2, so forcing HTTP/1.1 makes the connection look less like that browser.
IPv4 or IPv6 only
const ipv4Only = new Session({ disableIPV6: true });disableIPV4: true does the opposite.
Local address
On a machine with several network interfaces or IPs, localAddress picks the source address for outgoing connections:
const session = new Session({ localAddress: "192.0.2.10:0" });It takes host:port; port 0 lets the OS choose.
Writing the body to a file
streamOutputPath writes each response body to a file, in blocks of streamOutputBlockSize bytes (default 1024), followed by streamOutputEOFSymbol if you set one. The file is appended to, not overwritten.
The body then goes only to the file: res.body is an empty string. Status, headers and cookies are returned as usual.
const session = new Session({
streamOutputPath: "./download.bin",
streamOutputEOFSymbol: "<EOF>",
});
const res = await session.get("https://httpbin.org/base64/aGVsbG8gd29ybGQ=");
// res.body === "", download.bin contains "hello world<EOF>"