1868551 - Consider removing withPendingBrowser (or documenting its purpose more clearly)

Status: NEW

(WebExtensions :: General, task, P3)

Description

[Rob Wu [:robwu]]

The withPendingBrowser method was introduced in bug 1378990, to make sure that the permissions.request() handler can render a permission prompt on the right window. Secondarily, the browser is also used to maintain a queue of permission prompts, so that only one is shown at a time (this used to be a window-specific queue until it was changed in bug 1613796).

The current implementation has had a history of bugs (some still unresolved), where permissions.request() does not work, whenever the browser cannot be located (bug 1763915, bug 1433292, bug 1432083, bug 1493396): without withPendingBrowser, the permissions.request() handler falls back to the <browser> of the context, which is null in the case of a background script.

The issues above are desktop-specific. On Android, this issue does not happen because the code responsible for showing a prompt (GeckoViewWebExtension.js) does not rely on the browser sent from the implementation in ext-permissions.js.

We should either clarify that withPendingBrowser supports the permissions.request() API and that it is desktop-only in the withPendingBrowser function definition, or simplify the implementation by removing the logic (and fall back to the current active tab instead of trying to keep track of pendingBrowser).
Currently, the only uses of withPendingBrowser are as follows (desktop-only!):

• browserAction.onClicked (action.onClicked in MV3) (the tab that was active when the button was clicked).
• pageAction.onClicked (the tab that was active when the button was clicked).
• menus.onClicked (usually the tab that was active when the menu was clicked; except when a context menu on a tab is used, in which case the prompt is associated with that tab - if hidden the prompt is not shown).

In practice, the "pending browser" is usually the same as the active tab of the top-level window.

In the worst case, the impact of dropping the browser tracking is that the permission prompt is anchored to an unrelated tab instead of the tab that was originally clicked. But as the prompt can only be triggered by user interaction, and the prompt appears shortly after the user action, the risk of the user getting confused is minimal.