docs.rodeo

MDN Web Docs mirror

declarativeNetRequest

{{AddonSidebar}} 

This API enables extensions to specify conditions and actions that describe how network requests should be handled. These declarative rules enable the browser to evaluate and modify network requests without notifying extensions about individual network requests.

Permissions

To use this API, an extension must request the "declarativeNetRequest" or "declarativeNetRequestWithHostAccess" permission in its manifest.json file.

The "declarativeNetRequest" permission allows extensions to block and upgrade requests without any host permissions. Host permissions are required if the extension wants to redirect requests or modify headers on requests or when the "declarativeNetRequestWithHostAccess" permission is used instead of the "declarativeNetRequest" permission. To act on requests in these cases, host permissions are required for the request URL. For all requests, except for navigation requests (i.e., resource type main_frame and sub_frame), host permissions are also required for the request’s initiator. The initiator of a request is usually the document or worker that triggered the request.

Some requests are restricted and cannot be matched by extensions. These include privileged browser requests, requests to or from restricted domains, and requests from other extensions.

The "declarativeNetRequestFeedback" permission is required to use {{WebExtAPIRef("declarativeNetRequest.getMatchedRules","getMatchedRules")}}  and {{WebExtAPIRef("declarativeNetRequest.onRuleMatchedDebug","onRuleMatchedDebug")}}  as they return information on declarative rules matched. See Testing for more information.

Rules

The declarative rules are defined by four fields:

[!NOTE] A redirect action does not redirect the request, and the request continues as usual when:

This is an example rule that blocks all script requests originating from "foo.com" to any URL with "abc" as a substring:

{
  "id": 1,
  "priority": 1,
  "action": { "type": "block" },
  "condition": {
    "urlFilter": "abc",
    "initiatorDomains": ["foo.com"],
    "resourceTypes": ["script"]
  }
}

The urlFilter field of a rule condition is used to specify the pattern matched against the request URL. See {{WebExtAPIRef("declarativeNetRequest.RuleCondition","RuleCondition")}}  for details. Some examples of URL filters are:

urlFilter Matches Does not match
"abc" https://abcd.com
https://example.com/abcd		 https://ab.com
"abc*d" https://abcd.com
https://example.com/abcxyzd		 https://abc.com
"||a.example.com" https://a.example.com/
https://b.a.example.com/xyz		 https://example.com/
"|https*" https://example.com http://example.com/
http://https.com

Rulesets

Rules are organized into rulesets:

[!NOTE] Errors and warnings about invalid static rules are only displayed during testing. Invalid static rules in permanently installed extensions are ignored. Therefore, it’s important to verify that your static rulesets are valid by testing.

Limits

Static ruleset limits

An extension can:

Dynamic and session-scoped rules

The number of dynamic and session-scoped rules an extension can add is limited to:

Matching precedence

When the browser evaluates how to handle requests, it checks each extension’s rules that have a condition that matches the request and chooses the one to consider applying as follows:

  1. the rule priority, where 1 is the lowest priority (and rules default to 1 where priority is not set).
    If this doesn’t result in one rule to apply:
  2. the rule action, in the following order of precedence:
    1. “allow” which means any other remaining rules are ignored.
    2. “allowAllRequests” (for main_frame and sub_frame resourceTypes only) has the same effect as allow but also applies to future subresource loads in the document (including descendant frames) generated from the request.
    3. “block” cancels the request.
    4. “upgradeScheme” upgrades the scheme of the request.
    5. “redirect” redirects the request.
    6. “modifyHeaders” rewrites request or response headers or both.

[!NOTE] When multiple matching rules have the same rule priority and rule action type, the outcome can be ambiguous when the matched action support additional properties. These properties can result in outcomes that cannot be combined. For example:

To control the order in which actions are applied, assign distinct priority values to rules whose order of precedence is important.

[!NOTE] After rule priority and rule action, Firefox considers the ruleset the rule belongs to, in this order of precedence: session > dynamic > session rulesets. This cannot be relied upon across browsers, see WECG issue 280.

If only one extension provides a rule for the request, that rule is applied. However, where more than one extension has a matching rule, the browser chooses the one to apply in this order of precedence:

  1. “block”
  2. “redirect” and “upgradeScheme”
  3. “allow” and “allowAllRequests”

If the request was not blocked or redirected, the matching modifyHeaders actions are applied, as documented in {{WebExtAPIRef("declarativeNetRequest.ModifyHeaderInfo")}} .

Testing

{{WebExtAPIRef("declarativeNetRequest.testMatchOutcome","testMatchOutcome")}} , {{WebExtAPIRef("declarativeNetRequest.getMatchedRules","getMatchedRules")}} , and {{WebExtAPIRef("declarativeNetRequest.onRuleMatchedDebug","onRuleMatchedDebug")}}  are available to assist with testing rules and rulesets. These APIs require the "declarativeNetRequestFeedback" permissions. In addition:

Comparison with the webRequest API

Types

Properties

Functions

Events

{{WebExtExamples("h2")}} 

Browser compatibility

{{Compat}} 

In this article

View on MDN