DNR: Clarify precedence order across browsers.

[Rob--W]

Description

The currently documented order is not cross-browser, see w3c/webextensions#280. Therefore, drop that part of the documentation and replace it with guidance on how to create stable rules.

Motivation

People following the documentation with the expectation of having the same browser across browsers will be disappointed. The documentation should offer guidance to have consistent behavior across browsers.

Additional details

The documentation currently lists 4 ways of affecting the outcome. Only the first two are kept, as these are also documented in Chrome's documentation (https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#implementation-matching-algorithm). The other two (ruleset and rule ID) are not documented in Chrome, and cannot be relied upon. Therefore that part has been removed in favor of a note to emphasize the risk of having ambiguous outcomes, along with recommendations to resolve this.

Related issues and pull requests

• Inconsistency: session and dynamic DNR rules are applied with differing priorities across browsers w3c/webextensions#280

[github-actions]

Preview URLs

• /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest

Flaws (3)

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest
Title: declarativeNetRequest
Flaw count: 3

• broken_links:
  • Can't resolve /docs/Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request
  • Can't resolve /docs/Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request
  • Can't resolve /docs/Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request

External URLs (1)

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest
Title: declarativeNetRequest

• Inconsistency: session and dynamic DNR rules are applied with differing priorities across browsers w3c/webextensions#280 (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2023-05-16 14:19:00)

[rpl]

@Rob--W I just took a quick look to this PR, the content looks good from a technical perspective, but I have a thought about the terminology currently used to describe the issue that I'd like to pass by you (described in the inline comment below), let me know wdyt.

[rpl]

@Rob--W I'm wondering if instead of using the terms problem / no problem we may consider using the terms ambiguous / non-ambiguous instead, e.g.

Note: When there are multiple matching rules with the same rule priority and rule action type, the outcome of the rules evaluation is going to be potentially ambiguous when the matched action support additional properties. For example:

• "block" action rules: when multiple rules with the "block" action are matching, there wouldn't be any ambiguity because all "block" actions would result in the same outcome.
• "redirect" action rules: on the contrary when multiple with the "redirect" action are matching, the url each of the rules would be redirecting the request to may be different and that would make the outcome to become ambiguous, and so all but one of the matching "redirect" rules are going to be ignored. Note that it is still possible, ...
• "modifyHeaders" action rules: multiple rules with the "modifyHeaders" action are non-ambiguous if they all touch a different header and ambiguous if they touch the exact same header (as also explained at {{WebExtAPIRef("declarativeNetRequest.ModifyHeaderInfo")}}). The evaluation order of "modifyHeaders" is therefore important.

...

Not necessarily with this exact wording, but the idea was to make it more immediately clear what I meant with considering using the term "ambiguous/non-ambiguous" instead of "problem/no problem".

[Rob--W]

FYI: the dnr-redirect-url example at mdn/webextensions-examples#526 demonstrates the difference between Firefox and Chrome. They now behave identically, but when "priority" is removed from redirect-rules.json, the behavior differs.

[rpl]

lgtm