declarativeNetRequest

To use this API, an extension must request the "declarativeNetRequest" or "declarativeNetRequestWithHostAccess" permissions 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 a request or modify headers on a request. The "declarativeNetRequestWithHostAccess" permission requires host permissions to the request URL and initiator to act on a request.

The "declarativeNetRequestFeedback" permission is required to use getMatchedRules and 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 precedents for details on how priority affects which rules are applied.
• condition – The condition under which this rule is triggered.
• action – The action to take when the rule is matched. Rules can do one of these things:
  • block a network request.
  • redirect a network request.
  • modify headers from a network request.
  • prevent another matching rule from being applied.

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",
    "domains" : ["foo.com"],
    "resourceTypes" : ["script"]
  }
}

The urlFilter field of a rule condition is used to specify the pattern matched against the request URL. See RuleCondition for details. Some examples of URL filters are:

Rules are organized into rulesets:

• static rulesets: collections of rules defined with the "declarative_net_request" manifest key and stored in the extension. An extension can enable and disable static rulesets using 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.
• dynamic ruleset: rules added or removed using updateDynamicRules. These rules persist across sessions and extension updates.
• session ruleset: rules added or removed using updateSessionRules. These rules do not persist across browser sessions.

An extension can:

• specify static rulesets as part of the "declarative_net_request" manifest key up to the value of MAX_NUMBER_OF_STATIC_RULESETS.
• enable static rulesets up to at least the value of GUARANTEED_MINIMUM_STATIC_RULES, and the number of enabled static rulesets must not exceed the value of [MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. In addition, 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 and should instead use 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 the value of MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES.

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 and response headers. If this doesn't result in one rule to apply:
3. the ruleset the rule belongs to, in this order of precedence:
   1. session
   2. dynamic
   3. static If this doesn't result in one rule to apply:
4. the order of the rule in the ruleset, determined as the lowest value rule ID.

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 declarativeNetRequest.ModifyHeaderInfo.

testMatchOutcome, getmatchedrules, and onRuleMatchedDebug are available to assist with testing rules and rulesets. These APIs require the "declarativeNetRequestFeedback" permissions. In addition:

• in Chrome, these APIs are only available to unpacked extensions.
• in Firefox, these APIs are only available after setting the extensions.dnr.feedback preference to true. Set this preference using about:config or the --pref flag of the web-ext CLI tool.

• The declarativeNetRequest API evaluates network requests in the browser itself. This makes it more performant than the webRequest API, where each network request is evaluated in JavaScript in the extension process.
• Because the requests are not intercepted by the extension process, declarativeNetRequest removes the need for extensions to have a background page.
• Unlike the webRequest API, blocking or upgrading requests using the declarativeNetRequest API requires no host permissions when used with the declarativeNetRequest permission.
• The declarativeNetRequest API provides better privacy to users because extensions do not read the network requests made on the user's behalf.
• (Chrome only:) Unlike the webRequest API, any images or iframes blocked using the declarativeNetRequest API are automatically collapsed in the DOM.
• While deciding whether a request is to be blocked or redirected, the declarativeNetRequest API is given priority over the webRequest API because it allows for synchronous interception. Similarly, any headers removed through declarativeNetRequest API are not made visible to web request extensions.
• The webRequest API is more flexible than the declarativeNetRequest API because it allows extensions to evaluate a request programmatically.

declarativeNetRequest.MatchedRule

Details of a matched rule.

declarativeNetRequest.ModifyHeaderInfo

The request or response headers to modify for the request.

declarativeNetRequest.Redirect

Details of how the redirect should be performed. Only valid for redirect rules.

declarativeNetRequest.ResourceType

The resource type of a request.

declarativeNetRequest.Rule

An object containing details of a rule.

declarativeNetRequest.RuleAction

An object defining the action to take if a rule is matched.

declarativeNetRequest.RuleCondition

An object defining the condition under which a rule is triggered.

declarativeNetRequest.URLTransform

An object containing details of a URL transformation to perform for a redirect action.

declarativeNetRequest.DYNAMIC_RULESET_ID

Ruleset ID for the dynamic rules added by the extension.

declarativeNetRequest.GETMATCHEDRULES_QUOTA_INTERVAL

The time interval within which declarativeNetRequest.MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL declarativeNetRequest.getMatchedRules calls can be made.

declarativeNetRequest.GUARANTEED_MINIMUM_STATIC_RULES

The minimum number of static rules guaranteed to an extension across its enabled static rulesets.

declarativeNetRequest.MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

The number of times declarativeNetRequest.getMatchedRules can be called within a period of declarativeNetRequest.GETMATCHEDRULES_QUOTA_INTERVAL.

declarativeNetRequest.MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES

The maximum number of combined dynamic and session scoped rules an extension can add.

declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

The maximum number of static rulesets an extension can enable.

declarativeNetRequest.MAX_NUMBER_OF_REGEX_RULES

The maximum number of regular expression rules that an extension can add.

declarativeNetRequest.MAX_NUMBER_OF_STATIC_RULESETS

The maximum number of static rulesets an extension can specify as part of the declarative_net_request.rule_resources manifest key.

declarativeNetRequest.SESSION_RULESET_ID

The ruleset ID for the session-scoped rules added by the extension.

declarativeNetRequest.getAvailableStaticRuleCount()

Returns the number of static rules an extension can enable before the global static rule limit is reached.

declarativeNetRequest.getDynamicRules()

Returns the set of dynamic rules for the extension.

declarativeNetRequest.getEnabledRulesets()

Returns the IDs for the set of enabled static rulesets.

declarativeNetRequest.getMatchedRules()

Returns all the rules matched for the extension.

declarativeNetRequest.getSessionRules()

Returns the set of session scoped rules for the extension.

declarativeNetRequest.isRegexSupported()

Checks if a regular expression is supported as a declarativeNetRequest.RuleCondition.regexFilter rule condition.

declarativeNetRequest.setExtensionActionOptions()

Configures how the action count for tabs are handled.

declarativeNetRequest.testMatchOutcome()

Checks if any of the extension's declarativeNetRequest rules would match a hypothetical request.

declarativeNetRequest.updateDynamicRules()

Modifies the active set of dynamic rules for the extension.

declarativeNetRequest.updateEnabledRulesets()

Updates the set of active static rulesets for the extension.

declarativeNetRequest.updateSessionRules()

Modifies the set of session scoped rules for the extension.

declarativeNetRequest.onRuleMatchedDebug

Fired when a rule is matched with a request when debugging an extension with the "declarativeNetRequestFeedback" permission.