Add copyPipedHeaders option to control automatic header copying from piped streams

Fixes #1863

Author: sindresorhus

documentation/2-options.md

@@ -523,6 +523,57 @@ Therefore this option has no effect when using HTTP/2.
 #### **Note:**
 > - The [RFC 7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) doesn't specify any particular behavior for the GET method having a payload, therefore it's considered an [**anti-pattern**](https://en.wikipedia.org/wiki/Anti-pattern).
 
+### `copyPipedHeaders`
+
+**Type: `boolean`**\
+**Default: `true`**
+
+Automatically copy headers from piped streams.
+
+When piping a request into a Got stream (e.g., `request.pipe(got.stream(url))`), this controls whether headers from the source stream are automatically merged into the Got request headers.
+
+**Note:** Piped headers overwrite any explicitly set headers with the same name. To override this, either set `copyPipedHeaders` to `false` and manually copy safe headers, or use a `beforeRequest` hook to force specific header values after piping.
+
+Useful for proxy scenarios, but you may want to disable this to filter out headers like `Host`, `Connection`, `Authorization`, etc.
+
+**Example: Disable automatic header copying and manually copy only safe headers**
+
+```js
+import got from 'got';
+import {pipeline} from 'node:stream/promises';
+
+server.get('/proxy', async (request, response) => {
+	const gotStream = got.stream('https://example.com', {
+		copyPipedHeaders: false,
+		headers: {
+			'user-agent': request.headers['user-agent'],
+			'accept': request.headers['accept'],
+			// Explicitly NOT copying host, connection, authorization, etc.
+		}
+	});
+
+	await pipeline(request, gotStream, response);
+});
+```
+
+**Example: Override piped headers using beforeRequest hook**
+
+```js
+import got from 'got';
+
+const gotStream = got.stream('https://example.com', {
+	hooks: {
+		beforeRequest: [
+			options => {
+				// Force specific header values after piping
+				options.headers.host = 'example.com';
+				delete options.headers.authorization;
+			}
+		]
+	}
+});
+```
+
 ### `timeout`
 
 **Type: `object`**

source/core/index.ts

@@ -243,8 +243,8 @@ export default class Request extends Duplex implements RequestEvents<Request> {
 		this._stopRetry = noop;
 		this._requestId = generateRequestId();
 
-		this.on('pipe', (source: any) => {
-			if (source?.headers) {
+		this.on('pipe', (source: NodeJS.ReadableStream & {headers?: Record<string, string | string[] | undefined>}) => {
+			if (this.options.copyPipedHeaders && source?.headers) {
 				Object.assign(this.options.headers, source.headers);
 			}
 		});

source/core/options.ts

@@ -1025,6 +1025,7 @@ const defaultInternals: Options['_internals'] = {
 	password: '',
 	http2: false,
 	allowGetBody: false,
+	copyPipedHeaders: true,
 	headers: {
 		'user-agent': 'got (https://github.com/sindresorhus/got)',
 	},
@@ -2283,6 +2284,65 @@ export default class Options {
 		this._internals.allowGetBody = value;
 	}
 
+	/**
+	Automatically copy headers from piped streams.
+
+	When piping a request into a Got stream (e.g., `request.pipe(got.stream(url))`), this controls whether headers from the source stream are automatically merged into the Got request headers.
+
+	Note: Piped headers overwrite any explicitly set headers with the same name. To override this, either set `copyPipedHeaders` to `false` and manually copy safe headers, or use a `beforeRequest` hook to force specific header values after piping.
+
+	Useful for proxy scenarios, but you may want to disable this to filter out headers like `Host`, `Connection`, `Authorization`, etc.
+
+	@default true
+
+	@example
+	```
+	import got from 'got';
+	import {pipeline} from 'node:stream/promises';
+
+	// Disable automatic header copying and manually copy only safe headers
+	server.get('/proxy', async (request, response) => {
+		const gotStream = got.stream('https://example.com', {
+			copyPipedHeaders: false,
+			headers: {
+				'user-agent': request.headers['user-agent'],
+				'accept': request.headers['accept'],
+				// Explicitly NOT copying host, connection, authorization, etc.
+			}
+		});
+
+		await pipeline(request, gotStream, response);
+	});
+	```
+
+	@example
+	```
+	import got from 'got';
+
+	// Override piped headers using beforeRequest hook
+	const gotStream = got.stream('https://example.com', {
+		hooks: {
+			beforeRequest: [
+				options => {
+					// Force specific header values after piping
+					options.headers.host = 'example.com';
+					delete options.headers.authorization;
+				}
+			]
+		}
+	});
+	```
+	*/
+	get copyPipedHeaders(): boolean {
+		return this._internals.copyPipedHeaders;
+	}
+
+	set copyPipedHeaders(value: boolean) {
+		assert.boolean(value);
+
+		this._internals.copyPipedHeaders = value;
+	}
+
 	/**
 	Request headers.
 

test/stream.ts

@@ -247,6 +247,49 @@ test('piping server request to Got proxies also headers', withServer, async (t,
 	t.is(foo, 'bar');
 });
 
+test('piping server request to Got does not proxy headers when copyPipedHeaders is false', withServer, async (t, server, got) => {
+	server.get('/', headersHandler);
+	server.get('/proxy', async (request, response) => {
+		await streamPipeline(
+			request,
+			got.stream('', {copyPipedHeaders: false}),
+			response,
+		);
+	});
+
+	const headers: Record<string, string> = await got('proxy', {
+		headers: {
+			foo: 'bar',
+		},
+	}).json();
+	t.is(headers.foo, undefined);
+	t.truthy(headers['user-agent']); // Got's default user-agent should still be present
+});
+
+test('piped headers overwrite explicitly set headers when copyPipedHeaders is true', withServer, async (t, server, got) => {
+	server.get('/', headersHandler);
+	server.get('/proxy', async (request, response) => {
+		await streamPipeline(
+			request,
+			got.stream('', {
+				copyPipedHeaders: true,
+				headers: {
+					'x-custom': 'explicit-value',
+				},
+			}),
+			response,
+		);
+	});
+
+	const headers: Record<string, string> = await got('proxy', {
+		headers: {
+			'x-custom': 'piped-value',
+		},
+	}).json();
+	// Piped header should overwrite explicit header
+	t.is(headers['x-custom'], 'piped-value');
+});
+
 test('skips proxying headers after server has sent them already', withServer, async (t, server, got) => {
 	server.get('/', defaultHandler);
 	server.get('/proxy', async (_request, response) => {