feat: ability to send headers via ws connection to browser in node.js environment (#9314)

**What kind of change does this PR introduce?**

I have browsers pool in some cloud. I want that only users with access
will be able to connect to them. So they must provide token through
headers. But puppeteer does not allow to send headers when connected to
browser by ws connection. So I added this feature.

Closes #7218

docs/api/puppeteer.connectoptions.headers.md

@@ -0,0 +1,19 @@
+---
+sidebar_label: ConnectOptions.headers
+---
+
+# ConnectOptions.headers property
+
+Headers to use for the web socket connection.
+
+#### Signature:
+
+```typescript
+interface ConnectOptions {
+  headers?: Record<string, string>;
+}
+```
+
+## Remarks
+
+Only works in the Node.js environment.

docs/api/puppeteer.connectoptions.md

@@ -15,7 +15,8 @@ export interface ConnectOptions extends BrowserConnectOptions
 ## Properties
 
 | Property                                                              | Modifiers | Type                                                      | Description                                                     | Default |
-| --------------------------------------------------------------------- | --------- | --------------------------------------------------------- | ----------------- | ------- |
+| --------------------------------------------------------------------- | --------- | --------------------------------------------------------- | --------------------------------------------------------------- | ------- |
 | [browserURL?](./puppeteer.connectoptions.browserurl.md)               |           | string                                                    | <i>(Optional)</i>                                               |         |
 | [browserWSEndpoint?](./puppeteer.connectoptions.browserwsendpoint.md) |           | string                                                    | <i>(Optional)</i>                                               |         |
+| [headers?](./puppeteer.connectoptions.headers.md)                     |           | Record&lt;string, string&gt;                              | <i>(Optional)</i> Headers to use for the web socket connection. |         |
 | [transport?](./puppeteer.connectoptions.transport.md)                 |           | [ConnectionTransport](./puppeteer.connectiontransport.md) | <i>(Optional)</i>                                               |         |

packages/puppeteer-core/src/common/BrowserConnector.ts

@@ -24,6 +24,8 @@ import {Connection} from './Connection.js';
 import {ConnectionTransport} from './ConnectionTransport.js';
 import {getFetch} from './fetch.js';
 import {Viewport} from './PuppeteerViewport.js';
+
+import type {ConnectOptions} from './Puppeteer.js';
 /**
  * Generic browser options that can be passed when launching any browser or when
  * connecting to an existing browser instance.
@@ -73,11 +75,7 @@ const getWebSocketTransportClass = async () => {
  * @internal
  */
 export async function _connectToCDPBrowser(
-  options: BrowserConnectOptions & {
-    browserWSEndpoint?: string;
-    browserURL?: string;
-    transport?: ConnectionTransport;
-  }
+  options: BrowserConnectOptions & ConnectOptions
 ): Promise<CDPBrowser> {
   const {
     browserWSEndpoint,
@@ -85,6 +83,7 @@ export async function _connectToCDPBrowser(
     ignoreHTTPSErrors = false,
     defaultViewport = {width: 800, height: 600},
     transport,
+    headers = {},
     slowMo = 0,
     targetFilter,
     _isPageTarget: isPageTarget,
@@ -102,7 +101,7 @@ export async function _connectToCDPBrowser(
   } else if (browserWSEndpoint) {
     const WebSocketClass = await getWebSocketTransportClass();
     const connectionTransport: ConnectionTransport =
-      await WebSocketClass.create(browserWSEndpoint);
+      await WebSocketClass.create(browserWSEndpoint, headers);
     connection = new Connection(browserWSEndpoint, connectionTransport, slowMo);
   } else if (browserURL) {
     const connectionURL = await getWSEndpoint(browserURL);

packages/puppeteer-core/src/common/NodeWebSocketTransport.ts

@@ -21,7 +21,10 @@ import {packageVersion} from '../generated/version.js';
  * @internal
  */
 export class NodeWebSocketTransport implements ConnectionTransport {
-  static create(url: string): Promise<NodeWebSocketTransport> {
+  static create(
+    url: string,
+    headers?: Record<string, string>
+  ): Promise<NodeWebSocketTransport> {
     return new Promise((resolve, reject) => {
       const ws = new NodeWebSocket(url, [], {
         followRedirects: true,
@@ -29,6 +32,7 @@ export class NodeWebSocketTransport implements ConnectionTransport {
         maxPayload: 256 * 1024 * 1024, // 256Mb
         headers: {
           'User-Agent': `Puppeteer ${packageVersion}`,
+          ...headers,
         },
       });
 

packages/puppeteer-core/src/common/Puppeteer.ts

@@ -42,6 +42,12 @@ export interface ConnectOptions extends BrowserConnectOptions {
   browserWSEndpoint?: string;
   browserURL?: string;
   transport?: ConnectionTransport;
+  /**
+   * Headers to use for the web socket connection.
+   * @remarks
+   * Only works in the Node.js environment.
+   */
+  headers?: Record<string, string>;
 }
 
 /**