Skip to content

docs(proposal): Firefox-based stealth option for browser helper #5847

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
feder-cr wants to merge 1 commit into
base: v2
Choose a base branch
from
+33 −0
Draft

docs(proposal): Firefox-based stealth option for browser helper #5847

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions docs/invisible-firefox-helper-proposal.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Firefox-based stealth option for browser helper (proposal)

> Status: Draft proposal
> Created: 2026-05-26
> Tracking discussion: TBD

## Overview

Optional Firefox-based stealth choice for `PLAYWRIGHT_BROWSER_TYPE`, parallel to the existing `chromium` and `firefox` values added in PR #5250. Selected via config, no change to defaults.

## Motivation

CloakBrowser is already wired into `app/helper/browser.py` as the Chromium-stealth path. Private trackers and some media-info sources historically work better when contacted by a Firefox UA, and a few have started rate-limiting CloakBrowser's Chromium UA pattern. A Firefox-stealth option lets operators pick the engine that fits each tracker without changing helper code.

## Proposed change

Add `invisible_firefox` as a third valid value for `PLAYWRIGHT_BROWSER_TYPE`. When selected, `PlaywrightHelper` resolves to `invisible_playwright` (https://github.com/feder-cr/invisible_playwright) which drives a patched Firefox 150 binary (https://github.com/feder-cr/invisible_firefox, MPL-2, same license as Firefox upstream). Fingerprint patches at the C++ source level so there are no JS shims to detect.

Drop-in compatible with the existing `BrowserContext` / `BrowserPage` / `BrowserElement` protocols in `app/helper/browser.py`. Optional dependency, only imported when the value is selected.

## Out of scope

No change to existing `chromium` or `firefox` values. No change to CloakBrowser path. No change to defaults.

## Maintenance

Issues against the backend route to feder-cr/invisible_playwright. Only ask of this repo would be the resolver branch in `PlaywrightHelper.__init__` plus a config docstring update.
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot May 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

In app/helper/browser.py, PlaywrightHelper currently hardcodes the use of cloakbrowser (via self.__launch_cloakbrowser_context) in both action and get_page_source methods, completely ignoring self.browser_type.

Therefore, simply adding a resolver branch in PlaywrightHelper.__init__ will not be sufficient. The execution methods (action and get_page_source) will also need to be refactored to dynamically select and launch the appropriate browser context (e.g., standard Playwright, CloakBrowser, or invisible_playwright) based on self.browser_type or self.__browser_emulation().

Please update the proposal to reflect these required changes in the browser helper execution flow.

Suggested change
Issues against the backend route to feder-cr/invisible_playwright. Only ask of this repo would be the resolver branch in `PlaywrightHelper.__init__` plus a config docstring update.
Issues against the backend route to feder-cr/invisible_playwright. The implementation would require updating the resolver in PlaywrightHelper and refactoring its execution methods (action and get_page_source) to dynamically route to the correct browser context launcher based on self.browser_type, along with a config docstring update.


---

## 简介

为 `PLAYWRIGHT_BROWSER_TYPE` 增加可选的 Firefox 隐身后端，与 PR #5250 增加的 `chromium` 和 `firefox` 选项并行。通过配置开启，不影响默认行为。详细方案见上方英文部分。