files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md
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.
To use this API, an extension must request the "declarativeNetRequest" or "declarativeNetRequestWithHostAccess" permission in its manifest.json file. The "declarativeNetRequest" permission is shown to users in permission prompts, the "declarativeNetRequestWithHostAccess" is not.
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.
The declarative rules are defined by four fields:
id – An ID that uniquely identifies a rule within a ruleset. Mandatory and should be >= 1.priority – The rule priority. When specified, it should be >= 1. Defaults to 1. See Matching precedence for details on how priority affects which rules are applied.condition – The {{WebExtAPIRef("declarativeNetRequest.RuleCondition","condition")}} under which this rule is triggered.action – The {{WebExtAPIRef("declarativeNetRequest.RuleAction","action")}} to take when the rule is matched. Rules can do one of these things:
[!NOTE] A redirect action does not redirect the request, and the request continues as usual when:
- the action does not change the request.
- the redirect URL is invalid (e.g., the value of {{WebExtAPIRef("declarativeNetRequest.redirect","redirect.regexSubstitution")}} is not a valid URL).
This is an example rule that blocks all script requests originating from "example.com" to any URL with "abc" as a substring:
{
"id": 1,
"priority": 1,
"action": { "type": "block" },
"condition": {
"urlFilter": "abc",
"initiatorDomains": ["example.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:
Rules are organized into rulesets:
"declarative_net_request" manifest key and stored in the extension. An extension can enable and disable static rulesets using {{WebExtAPIRef("declarativeNetRequest.updateEnabledRulesets","updateEnabledRulesets")}}. The set of enabled static rulesets is persisted across sessions but not across extension updates. The static rulesets enabled on extension installation and update are determined by the content of the "declarative_net_request" manifest key.[!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.
An extension can:
"declarative_net_request" manifest key up to the value of {{WebExtAPIRef("declarativeNetRequest.MAX_NUMBER_OF_STATIC_RULESETS","MAX_NUMBER_OF_STATIC_RULESETS")}}."declarative_net_request" manifest key or programmatically) so that the number of rules (enabled or disabled) they contain doesn't exceed the value of {{WebExtAPIRef("declarativeNetRequest.GUARANTEED_MINIMUM_STATIC_RULES","GUARANTEED_MINIMUM_STATIC_RULES")}} and the number of enable static rulesets doesn't exceed the value of {{WebExtAPIRef("declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS","MAX_NUMBER_OF_ENABLED_STATIC_RULESETS")}}.
[!NOTE] The number of rules in enabled static rulesets for all extensions must not exceed the global limit. Extensions shouldn't depend on the global limit having a specific value; instead, they should use {{WebExtAPIRef("declarativeNetRequest.getAvailableStaticRuleCount","getAvailableStaticRuleCount")}} to find the number of additional rules they can enable.
The number of dynamic and session-scoped rules an extension can add is limited to:
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:
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:
the rule action, in the following order of precedence:
[!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:
- The "block" action does not support additional properties, and therefore there is no ambiguity: all matching "block" actions would result in the same outcome.
- The "redirect" action redirects a request to one destination. When multiple "redirect" actions match, all but one "redirect" action is ignored. It is still possible to redirect repeatedly when the redirected request matches another rule condition.
- Multiple "modifyHeaders" actions can be applied independently when they touch different headers. The result is ambiguous when they touch the same header, because some combination of operations are not allowed (as explained at {{WebExtAPIRef("declarativeNetRequest.ModifyHeaderInfo")}}). The evaluation order of "modifyHeaders" actions is therefore important.
To control the order in which actions are applied, assign distinct
priorityvalues 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 > static 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:
If the request was not blocked or redirected, the matching modifyHeaders actions are applied, as documented in {{WebExtAPIRef("declarativeNetRequest.ModifyHeaderInfo")}}.
{{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:
extensions.dnr.feedback preference to true. Set this preference using about:config or the --pref flag of the web-ext CLI tool.declarativeNetRequest permission.rule.condition.excludedResponseHeaders array or rule.condition.responseHeaders array.declarative_net_request.rule_resources manifest key.declarativeNetRequest.RuleCondition.regexFilter rule condition.declarativeNetRequest rules would match a hypothetical request.{{WebExtExamples("h2")}}
{{Compat}}
<!-- // Copyright 2015 The Chromium Authors. All rights reserved. // // Redistribution and use in source and binary forms, with or without // modification, are permitted provided that the following conditions are // met: // // * Redistributions of source code must retain the above copyright // notice, this list of conditions and the following disclaimer. // * Redistributions in binary form must reproduce the above // copyright notice, this list of conditions and the following disclaimer // in the documentation and/or other materials provided with the // distribution. // * Neither the name of Google Inc. nor the names of its // contributors may be used to endorse or promote products derived from // this software without specific prior written permission. // // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -->