docs: clarify headers propagation to redirects (#20572)

References #20501.

docs/src/api/class-requestoptions.md

@@ -91,7 +91,7 @@ this request body.
 * since: v1.18
 - returns: <[RequestOptions]>
 
-Sets an HTTP header to the request.
+Sets an HTTP header to the request. This header will apply to the fetched request as well as any redirects initiated by it.
 
 ### param: RequestOptions.setHeader.name
 * since: v1.18

docs/src/api/class-route.md

@@ -100,6 +100,10 @@ await page.RouteAsync("**/*", route =>
 });
 ```
 
+**Details**
+
+Note that any overrides such as [`option: url`] or [`option: headers`] only apply to the request being routed. If this request results in a redirect, overrides will not be applied to the new redirected request. If you want to propagate a header through redirects, use the combination of [`method: Route.fetch`] and [`method: Route.fulfill`] instead.
+
 ### option: Route.continue.url
 * since: v1.8
 - `url` <[string]>
@@ -482,6 +486,10 @@ await page.RouteAsync("https://dog.ceo/api/breeds/list/all", async route =>
 });
 ```
 
+**Details**
+
+Note that [`option: headers`] option will apply to the fetched request as well as any redirects initiated by it. If you want to only apply [`option: headers`] to the original request, but not to redirects, look into [`method: Route.continue`] instead.
+
 ### option: Route.fetch.url
 * since: v1.29
 - `url` <[string]>

docs/src/api/params.md

@@ -339,7 +339,7 @@ Optional request parameters.
 * langs: js, python, csharp
 - `headers` <[Object]<[string], [string]>>
 
-Allows to set HTTP headers.
+Allows to set HTTP headers. These headers will apply to the fetched request as well as any redirects initiated by it.
 
 ## js-python-csharp-fetch-option-timeout
 * langs: js, python, csharp

packages/playwright-core/types/types.d.ts

@@ -14526,7 +14526,8 @@ export interface APIRequestContext {
     form?: { [key: string]: string|number|boolean; };
 
     /**
-     * Allows to set HTTP headers.
+     * Allows to set HTTP headers. These headers will apply to the fetched request as well as any redirects initiated by
+     * it.
      */
     headers?: { [key: string]: string; };
 
@@ -14655,7 +14656,8 @@ export interface APIRequestContext {
     form?: { [key: string]: string|number|boolean; };
 
     /**
-     * Allows to set HTTP headers.
+     * Allows to set HTTP headers. These headers will apply to the fetched request as well as any redirects initiated by
+     * it.
      */
     headers?: { [key: string]: string; };
 
@@ -14754,7 +14756,8 @@ export interface APIRequestContext {
     form?: { [key: string]: string|number|boolean; };
 
     /**
-     * Allows to set HTTP headers.
+     * Allows to set HTTP headers. These headers will apply to the fetched request as well as any redirects initiated by
+     * it.
      */
     headers?: { [key: string]: string; };
 
@@ -14833,7 +14836,8 @@ export interface APIRequestContext {
     form?: { [key: string]: string|number|boolean; };
 
     /**
-     * Allows to set HTTP headers.
+     * Allows to set HTTP headers. These headers will apply to the fetched request as well as any redirects initiated by
+     * it.
      */
     headers?: { [key: string]: string; };
 
@@ -14912,7 +14916,8 @@ export interface APIRequestContext {
     form?: { [key: string]: string|number|boolean; };
 
     /**
-     * Allows to set HTTP headers.
+     * Allows to set HTTP headers. These headers will apply to the fetched request as well as any redirects initiated by
+     * it.
      */
     headers?: { [key: string]: string; };
 
@@ -15042,7 +15047,8 @@ export interface APIRequestContext {
     form?: { [key: string]: string|number|boolean; };
 
     /**
-     * Allows to set HTTP headers.
+     * Allows to set HTTP headers. These headers will apply to the fetched request as well as any redirects initiated by
+     * it.
      */
     headers?: { [key: string]: string; };
 
@@ -15121,7 +15127,8 @@ export interface APIRequestContext {
     form?: { [key: string]: string|number|boolean; };
 
     /**
-     * Allows to set HTTP headers.
+     * Allows to set HTTP headers. These headers will apply to the fetched request as well as any redirects initiated by
+     * it.
      */
     headers?: { [key: string]: string; };
 
@@ -17789,6 +17796,13 @@ export interface Route {
    * });
    * ```
    *
+   * **Details**
+   *
+   * Note that any overrides such as `url` or `headers` only apply to the request being routed. If this request results
+   * in a redirect, overrides will not be applied to the new redirected request. If you want to propagate a header
+   * through redirects, use the combination of
+   * [route.fetch([options])](https://playwright.dev/docs/api/class-route#route-fetch) and
+   * [route.fulfill([options])](https://playwright.dev/docs/api/class-route#route-fulfill) instead.
    * @param options
    */
   continue(options?: {
@@ -17916,6 +17930,11 @@ export interface Route {
    * });
    * ```
    *
+   * **Details**
+   *
+   * Note that `headers` option will apply to the fetched request as well as any redirects initiated by it. If you want
+   * to only apply `headers` to the original request, but not to redirects, look into
+   * [route.continue([options])](https://playwright.dev/docs/api/class-route#route-continue) instead.
    * @param options
    */
   fetch(options?: {