Merge pull request #282 from autoscrape-labs/docs/private-proxy-interception

Docs/private proxy interception

Author: thalissonvs

public/docs/features.md

@@ -1331,6 +1331,40 @@ asyncio.run(iframe_interaction())
 
 Intercept and modify network requests before they're sent:
 
+!!! note "Private proxy + request interception (Fetch)"
+    When using a private/authenticated proxy, Pydoll enables Fetch at the Browser level to handle the proxy authentication challenge during the first navigation and may change its state. To avoid domain conflicts with your Tab-level interception, enable Fetch at the Tab level only after the first navigation completes.
+
+    Recommended pattern:
+
+    ```python
+    import asyncio
+    from pydoll.browser.chromium import Chrome
+    from pydoll.browser.options import ChromiumOptions
+
+    async def main():
+        options = ChromiumOptions()
+        options.add_argument('--proxy-server=username:password@host:port')
+
+        async with Chrome(options=options) as browser:
+            tab = await browser.start()
+
+            # 1) Trigger proxy auth at Browser level first
+            await tab.go_to('https://example.com')
+
+            # 2) Then enable Tab-level Fetch interception safely
+            await tab.enable_fetch_events()
+
+            async def on_paused(event):
+                await tab.continue_request(event['params']['requestId'])
+
+            await tab.on('Fetch.requestPaused', on_paused)
+
+            # 3) Proceed with your navigations/interception
+            await tab.go_to('https://example.com/next')
+
+    asyncio.run(main())
+    ```
+
 ### Basic Request Modification
 
 ```python

public/docs/zh/features.md

@@ -1346,6 +1346,40 @@ asyncio.run(iframe_interaction())
 
 在网络请求发送之前拦截并修改它们：
 
+!!! 信息 "私有代理 + 请求拦截（Fetch）"
+    当使用带认证的私有代理时，Pydoll 会在浏览器（Browser）级别启用 Fetch 以处理首次导航过程中的代理认证挑战，其状态变化可能会影响页面（Tab）级别的拦截。为避免域冲突，请在首次导航完成后再在 Tab 级别启用 Fetch 拦截。
+
+    推荐用法：
+
+    ```python
+    import asyncio
+    from pydoll.browser.chromium import Chrome
+    from pydoll.browser.options import ChromiumOptions
+
+    async def main():
+        options = ChromiumOptions()
+        options.add_argument('--proxy-server=username:password@host:port')
+
+        async with Chrome(options=options) as browser:
+            tab = await browser.start()
+
+            # 1) 先进行一次导航，触发浏览器级别的代理认证
+            await tab.go_to('https://example.com')
+
+            # 2) 然后在 Tab 级别安全地启用 Fetch 拦截
+            await tab.enable_fetch_events()
+
+            async def on_paused(event):
+                await tab.continue_request(event['params']['requestId'])
+
+            await tab.on('Fetch.requestPaused', on_paused)
+
+            # 3) 继续你的导航/拦截逻辑
+            await tab.go_to('https://example.com/next')
+
+    asyncio.run(main())
+    ```
+
 ### 简单请求修改例子
 
 ```python

pydoll/browser/chromium/base.py

@@ -656,22 +656,24 @@ async def _configure_proxy(
         self, private_proxy: bool, proxy_credentials: tuple[Optional[str], Optional[str]]
     ):
         """Setup proxy authentication handling if needed."""
-        if private_proxy:
-            await self.enable_fetch_events(handle_auth_requests=True)
-            await self.on(
-                FetchEvent.REQUEST_PAUSED,
-                self._continue_request_callback,
-                temporary=True,
-            )
-            await self.on(
-                FetchEvent.AUTH_REQUIRED,
-                partial(
-                    self._continue_request_with_auth_callback,
-                    proxy_username=proxy_credentials[0],
-                    proxy_password=proxy_credentials[1],
-                ),
-                temporary=True,
-            )
+        if not private_proxy:
+            return
+
+        await self.enable_fetch_events(handle_auth_requests=True)
+        await self.on(
+            FetchEvent.REQUEST_PAUSED,
+            self._continue_request_callback,
+            temporary=True,
+        )
+        await self.on(
+            FetchEvent.AUTH_REQUIRED,
+            partial(
+                self._continue_request_with_auth_callback,
+                proxy_username=proxy_credentials[0],
+                proxy_password=proxy_credentials[1],
+            ),
+            temporary=True,
+        )
 
     @staticmethod
     def _is_valid_tab(target: TargetInfo) -> bool: