feat: Add support for configurable maxHeaderSize in HTTP requests (#1511)

parthverma1 · web-flow · commit 5d1950d2a966 · 2025-05-15T09:55:34.000+05:30
* Add support for configurable maxHeaderSize in HTTP requests

This introduces the `maxHeaderSize` option for limiting HTTP header size in Node.js HTTP/1 requests. It includes implementation, tests for various scenarios, and updates to documentation. The feature is ignored for HTTP/2 where header sizing is not configurable.

* refactor: remove dependency on 'http' module for maxHeaderSize

* chore: update default maxHeaderSize to 128KB

Increase the default `maxHeaderSize` from 16KB to 128KB to align with updated requirements and prevent potential header size limitations. Adjusted related test cases to reflect the new default configuration.
diff --git a/README.md b/README.md
@@ -97,6 +97,9 @@ runner.run(collection, {
         // Maximum allowed response size in bytes (only supported on Node, ignored in the browser)
         maxResponseSize: 1000000,
 
+        // Maximum allowed header size in bytes (only supported on Node HTTP/1, ignored in the browser and when using HTTP/2)
+        maxHeaderSize: 1000000,
+
         // HTTP Protocol version to use. Valid options are http1, http2, and auto (only supported on Node, ignored in the browser)
         protocolVersion: 'http1',
 
@@ -125,7 +128,7 @@ runner.run(collection, {
         implicitTraceHeader: true,
 
         // Add system headers to all requests which cannot be overridden or disabled
-        systemHeaders: { 'User-Agent': 'PostmanRuntime' }
+        systemHeaders: { 'User-Agent': 'PostmanRuntime' },
 
         // Extend well known "root" CAs with the extra certificates in file. The file should consist of one or more trusted certificates in PEM format. (only supported on Node, ignored in the browser)
         extendedRootCA: 'path/to/extra/CA/certs.pem',
diff --git a/lib/requester/core.js b/lib/requester/core.js
@@ -407,6 +407,7 @@ module.exports = {
      * @param defaultOpts.implicitTraceHeader
      * @param defaultOpts.removeRefererHeaderOnRedirect
      * @param defaultOpts.timings
+     * @param defaultOpts.maxHeaderSize
      * @param protocolProfileBehavior
      * @returns {{}}
      */
@@ -419,6 +420,7 @@ module.exports = {
             self = this,
             bodyParams,
             useWhatWGUrlParser = defaultOpts.useWhatWGUrlParser,
+            maxHeaderSize = defaultOpts.maxHeaderSize,
             disableUrlEncoding = protocolProfileBehavior.disableUrlEncoding,
             disabledSystemHeaders = protocolProfileBehavior.disabledSystemHeaders || {},
             // the system headers provided in requester configuration
@@ -457,6 +459,7 @@ module.exports = {
         options.extraCA = defaultOpts.extendedRootCA;
         options.ignoreProxyEnvironmentVariables = defaultOpts.ignoreProxyEnvironmentVariables;
         options.agentIdleTimeout = defaultOpts.agentIdleTimeout;
+        options.maxHeaderSize = maxHeaderSize;
 
         // Disable encoding of URL in postman-request in order to use pre-encoded URL object returned from
         // toNodeUrl() function of postman-url-encoder
diff --git a/lib/requester/requester-pool.js b/lib/requester/requester-pool.js
@@ -37,7 +37,8 @@ RequesterPool = function (options, callback) {
         systemHeaders: _.get(options, 'requester.systemHeaders', {}),
         removeRefererHeaderOnRedirect: _.get(options, 'requester.removeRefererHeaderOnRedirect'),
         ignoreProxyEnvironmentVariables: _.get(options, 'ignoreProxyEnvironmentVariables'),
-        network: _.get(options, 'network', {})
+        network: _.get(options, 'network', {}),
+        maxHeaderSize: _.get(options, 'requester.maxHeaderSize', 131072) // 128KB
     });
 
     // create a cookie jar if one is not provided
diff --git a/test/fixtures/servers/_servers.js b/test/fixtures/servers/_servers.js
@@ -707,7 +707,9 @@ function createHTTP2Server (opts) {
         options[option] = fs.readFileSync(options[option]);
     });
 
-    server = http2.createSecureServer(options, function (req, res) {
+    server = http2.createSecureServer(options);
+
+    server.on('request', (req, res) => {
         server.emit(req.url, req, res);
     });
 
diff --git a/test/fixtures/servers/dynamicHeadersHTTP1.js b/test/fixtures/servers/dynamicHeadersHTTP1.js
@@ -0,0 +1,14 @@
+const server = require('./_servers'),
+    httpServer = server.createHTTPServer();
+
+
+httpServer.on('request', function (req, res) {
+    const headerSizeInBytes = parseInt(req.url.split('/').at(-1), 10);
+    let headers = { header: 'a'.repeat(headerSizeInBytes - 6 - 2 - 2) };
+
+    res.writeHead(200, headers);
+    res.end('Headers sent dynamically based on the URL.');
+});
+
+
+module.exports = httpServer;
diff --git a/test/fixtures/servers/dynamicHeadersHTTP2.js b/test/fixtures/servers/dynamicHeadersHTTP2.js
@@ -0,0 +1,15 @@
+const server = require('./_servers'),
+    httpServer = server.createHTTP2Server();
+
+
+httpServer.on('request', (req, res) => {
+    const headerSizeInBytes = parseInt(req.url.split('/').at(-1), 10);
+
+    let headers = { header: 'a'.repeat(headerSizeInBytes - 6 - 2 - 2) };
+
+    res.writeHead(200, headers);
+    res.end('Headers sent dynamically based on the URL.');
+});
+
+
+module.exports = httpServer;
diff --git a/test/integration/requester-spec/maxHeaderSize.test.js b/test/integration/requester-spec/maxHeaderSize.test.js
@@ -0,0 +1,165 @@
+const expect = require('chai').expect,
+    IS_NODE = typeof window === 'undefined';
+
+(IS_NODE ? describe : describe.skip)('Requester Spec: maxHeaderSize', function () {
+    let testrun,
+        BASE_URL_HTTP1,
+        BASE_URL_HTTP2;
+
+    before(function (done) {
+        BASE_URL_HTTP1 = global.servers.dynamicHeadersHTTP1;
+        BASE_URL_HTTP2 = global.servers.dynamicHeadersHTTP2;
+        done();
+    });
+
+    describe('HTTP/1: with maxHeaderSize: undefined (default)', function () {
+        before(function (done) {
+            this.run({
+                collection: {
+                    item: [{
+                        request: {
+                            url: `${BASE_URL_HTTP1}/1024`, // 1KB
+                            method: 'GET'
+                        }
+                    }]
+                }
+            }, (err, results) => {
+                testrun = results;
+                done(err);
+            });
+        });
+
+        it('should complete the request successfully', function () {
+            expect(testrun).to.be.ok;
+            const response = testrun.response.getCall(0).args[2];
+
+            expect(response).to.have.property('code', 200); // HTTP OK
+        });
+
+        it('should include the correct number of headers', function () {
+            const response = testrun.response.getCall(0).args[2];
+
+            expect(response.headers.count()).to.be.eql(5);
+        });
+    });
+
+    describe('HTTP/1: with maxHeaderSize: undefined and exceeded', function () {
+        before(function (done) {
+            this.run({
+                collection: {
+                    item: [{
+                        request: {
+                            url: `${BASE_URL_HTTP1}/132000`, // > 128KB default set
+                            method: 'GET'
+                        }
+                    }]
+                }
+            }, (err, results) => {
+                testrun = results;
+                done(err);
+            });
+        });
+
+        it('should not complete the request and throw an error', function () {
+            const error = testrun.request.getCall(0).args[0];
+
+            expect(error).to.be.ok;
+            expect(error.code).to.eql('HPE_HEADER_OVERFLOW'); // Node.js error
+        });
+    });
+
+    describe('HTTP/1: with maxHeaderSize: defined and exceeded', function () {
+        const MAX_HEADER_SIZE = 512;
+
+        before(function (done) {
+            this.run({
+                collection: {
+                    item: [{
+                        request: {
+                            url: `${BASE_URL_HTTP1}/600`, // Send 50 headers
+                            method: 'GET'
+                        }
+                    }]
+                },
+                requester: {
+                    maxHeaderSize: MAX_HEADER_SIZE // Set a limit less than required to trigger failure
+                }
+            }, (err, results) => {
+                testrun = results;
+                done(err);
+            });
+        });
+
+        it('should not complete the request and throw an error', function () {
+            const error = testrun.request.getCall(0).args[0];
+
+            expect(error).to.be.ok;
+            expect(error.code).to.eql('HPE_HEADER_OVERFLOW'); // Node.js error
+        });
+    });
+
+    describe('HTTP/1: with maxHeaderSize: defined and respected', function () {
+        const MAX_HEADER_SIZE = 8192;
+
+        before(function (done) {
+            this.run({
+                collection: {
+                    item: [{
+                        request: {
+                            url: `${BASE_URL_HTTP1}/500`, // Send 10 headers
+                            method: 'GET'
+                        }
+                    }]
+                },
+                requester: {
+                    maxHeaderSize: MAX_HEADER_SIZE // Set a limit more than required
+                }
+            }, (err, results) => {
+                testrun = results;
+                done(err);
+            });
+        });
+
+        it('should complete the request successfully', function () {
+            expect(testrun).to.be.ok;
+            const response = testrun.response.getCall(0).args[2];
+
+            expect(response).to.have.property('code', 200); // HTTP OK
+        });
+
+        it('should include the correct number of headers', function () {
+            const response = testrun.response.getCall(0).args[2];
+
+            expect(response.headers.count()).to.be.eql(5);
+        });
+    });
+
+    describe('HTTP/2: with maxHeaderSize: defined and exceeded (NO-OP)', function () {
+        before(function (done) {
+            this.run({
+                collection: {
+                    item: [{
+                        request: {
+                            url: `${BASE_URL_HTTP2}/50`, // Send 50 headers
+                            method: 'GET'
+                        }
+                    }]
+                },
+                requester: {
+                    strictSSL: false,
+                    protocolVersion: 'auto',
+                    maxHeaderSize: 10 // Set a limit less than required to trigger failure
+                }
+            }, (err, results) => {
+                testrun = results;
+                done(err);
+            });
+        });
+
+        it('should include the correct number of headers', function () {
+            const response = testrun.response.getCall(0).args[2];
+
+            expect(response.headers.count()).to.be.eql(3);
+        });
+    });
+});
