diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/dynamic_ruleset_id/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/dynamic_ruleset_id/index.md new file mode 100644 index 000000000000000..8b82d49c7be6f01 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/dynamic_ruleset_id/index.md @@ -0,0 +1,57 @@ +--- +title: declarativeNetRequest.DYNAMIC_RULESET_ID +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/DYNAMIC_RULESET_ID +tags: + - DYNAMIC_RULESET_ID + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Property + - declarativeNetRequest + - DYNAMIC_RULESET_ID +browser-compat: webextensions.api.declarativeNetRequest.DYNAMIC_RULESET_ID +--- + +{{AddonSidebar()}} + +Ruleset ID for the dynamic rules added by the extension using {{WebExtAPIRef("declarativeNetRequest.updateDynamicRules","updateDynamicRules")}}. + +Its value is `"_dynamic"`. + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getavailablestaticrulecount/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getavailablestaticrulecount/index.md new file mode 100644 index 000000000000000..d9ddac07efcd508 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getavailablestaticrulecount/index.md @@ -0,0 +1,70 @@ +--- +title: declarativeNetRequest.getAvailableStaticRuleCount +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/getAvailableStaticRuleCount +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Method + - declarativeNetRequest + - getAvailableStaticRuleCount +browser-compat: webextensions.api.declarativeNetRequest.getAvailableStaticRuleCount +--- + +{{AddonSidebar()}} + +Returns the number of static rules that can be activated before the global static rule limit is reached. + +## Syntax + +```js-nolint +let count = await browser.declarativeNetRequest.getAvailableStaticRuleCount(); +``` + +### Parameters + +This function takes no parameters. + +### Return value + +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) fulfilled with a number that indicates how many static rules can enable before the global static rule limit is reached. If the request fails, the promise is rejected with an error message. + +## Examples + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getdynamicrules/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getdynamicrules/index.md new file mode 100644 index 000000000000000..848df8646426be5 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getdynamicrules/index.md @@ -0,0 +1,70 @@ +--- +title: declarativeNetRequest.getAvailableStaticRuleCount +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/getDynamicRules +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Method + - declarativeNetRequest + - getDynamicRules +browser-compat: webextensions.api.declarativeNetRequest.getDynamicRules +--- + +{{AddonSidebar()}} + +Returns the set of dynamic rules for the extension. + +## Syntax + +```js-nolint +let gettingDynamicRules = browser.declarativeNetRequest.getDynamicRules(); +``` + +### Parameters + +This function takes no parameters. + +### Return value + +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) is fulfilled with an array of {{WebExtAPIRef("declarativeNetRequest.Rule")}} objects. Each of these represents a rule that belongs to the extension. If no rules are active, the array is empty. If the request fails, the promise is rejected with an error message. + +## Examples + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getenabledrulesets/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getenabledrulesets/index.md new file mode 100644 index 000000000000000..968d48b12bbe145 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getenabledrulesets/index.md @@ -0,0 +1,70 @@ +--- +title: declarativeNetRequest.getEnabledRulesets +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/getEnabledRulesets +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Method + - declarativeNetRequest + - getEnabledRulesets +browser-compat: webextensions.api.declarativeNetRequest.getEnabledRulesets +--- + +{{AddonSidebar()}} + +Returns the IDs for the set of activated static rulesets. + +## Syntax + +```js-nolint +let rulesetIds = await browser.declarativeNetRequest.getEnabledRulesets(); +``` + +### Parameters + +This function takes no parameters. + +### Return value + +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) fulfilled with an array of string containing static rulesets IDs. If no rules are active, the array is empty. If the request fails, the promise is rejected with an error message. + +## Examples + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getmatchedrules/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getmatchedrules/index.md new file mode 100644 index 000000000000000..f0683e6adeaf61c --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getmatchedrules/index.md @@ -0,0 +1,87 @@ +--- +title: declarativeNetRequest.getMatchedRules +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/getMatchedRules +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Method + - declarativeNetRequest + - getMatchedRules +browser-compat: webextensions.api.declarativeNetRequest.getMatchedRules +--- + +{{AddonSidebar()}} + +Returns all the rules matched for the extension. Callers can filter the list of matched rules by specifying a `filter`. This method is only available to extensions with the `"declarativeNetRequestFeedback"` permission or that have the `"activeTab"` permission granted for the `tabId` specified in `filter`. Rules not associated with an active document that were matched more than five minutes ago are returned. + +## Syntax + +```js-nolint +let gettingMatchedRules = browser.declarativeNetRequest.getMatchedRules( + filter // object +); +``` + +### Parameters + +- `filter` {{optional_inline}} + + - : An object to filter the list of matched rules. + - `minTimeStamp` {{optional_inline}} + - : A `number`. If specified, only matches rules after the specified timestamp. + - `tabId` {{optional_inline}} + - : A `number`. If specified, only matches rules for the specified tab. Matches rules not associated with any active tab if set to `-1`. + +### Return value + +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that fulfills with an object with these properties: + +- `rule` + - : {{WebExtAPIRef("declarativeNetRequest.MatchedRule")}}. Details of a matched rule. +- `tabId` + - : `number` The `tabId` of the tab the request originated from if the tab is still active. Otherwise, `-1`. +- `timeStamp` + - : `number` The time the rule was matched. Timestamps correspond to the Javascript convention for times, i.e. the number of milliseconds since the epoch. + +If no rules are matched, the object is empty. If the request fail, the promise is rejected with an error message + +## Examples + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getmatchedrules_quota_interval/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getmatchedrules_quota_interval/index.md new file mode 100644 index 000000000000000..42d0aa68ce28140 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getmatchedrules_quota_interval/index.md @@ -0,0 +1,57 @@ +--- +title: declarativeNetRequest.GETMATCHEDRULES_QUOTA_INTERVAL +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/GETMATCHEDRULES_QUOTA_INTERVAL +tags: + - GETMATCHEDRULES_QUOTA_INTERVAL + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Property + - declarativeNetRequest + - GETMATCHEDRULES_QUOTA_INTERVAL +browser-compat: webextensions.api.declarativeNetRequest.GETMATCHEDRULES_QUOTA_INTERVAL +--- + +{{AddonSidebar()}} + +The time interval within which {{WebExtAPIRef("declarativeNetRequest.MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL")}} {{WebExtAPIRef("declarativeNetRequest.getMatchedRules")}} calls can be made, specified in minutes. Additional calls fail immediately and result in a promise rejection. Calls associated with a user gesture are exempt from the quota. + +Its value is `10`. + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getsessionrules/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getsessionrules/index.md new file mode 100644 index 000000000000000..2b7793a47119b46 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getsessionrules/index.md @@ -0,0 +1,70 @@ +--- +title: declarativeNetRequest.getSessionRules +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/getSessionRules +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Method + - declarativeNetRequest + - getSessionRules +browser-compat: webextensions.api.declarativeNetRequest.getSessionRules +--- + +{{AddonSidebar()}} + +Returns the active set of session scoped rules for the extension. + +## Syntax + +```js-nolint +let sessionRules = await browser.declarativeNetRequest.getSessionRules(); +``` + +### Parameters + +This function takes no parameters. + +### Return value + +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) fulfilled with an array of {{WebExtAPIRef("declarativeNetRequest.Rule")}} objects. If no rules are active, the object is empty. If the request fails, the promise is rejected with an error message + +## Examples + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/guaranteed_minimum_static_rules/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/guaranteed_minimum_static_rules/index.md new file mode 100644 index 000000000000000..a4b34b8b640db84 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/guaranteed_minimum_static_rules/index.md @@ -0,0 +1,57 @@ +--- +title: declarativeNetRequest.GUARANTEED_MINIMUM_STATIC_RULES +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/GUARANTEED_MINIMUM_STATIC_RULES +tags: + - GUARANTEED_MINIMUM_STATIC_RULES + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Property + - declarativeNetRequest + - GUARANTEED_MINIMUM_STATIC_RULES +browser-compat: webextensions.api.declarativeNetRequest.GUARANTEED_MINIMUM_STATIC_RULES +--- + +{{AddonSidebar()}} + +The minimum number of static rules guaranteed to an extension across its enabled static rulesets. Any rules above this limit are count towards the global static rule limit. + +Its value is `30000` on Chrome. + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md new file mode 100644 index 000000000000000..ac1127ae263d5c0 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md @@ -0,0 +1,262 @@ +--- +title: declarativeNetRequest +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest +tags: + - API + - Add-ons + - Extensions + - Interface + - Reference + - WebExtensions + - declarativeNetRequest +browser-compat: webextensions.api.declarativeNetRequest +--- + +{{AddonSidebar}} + +This API enables extensions to obtain information about and modify declarative rules that block or modify network requests. The use of declarative rules means that extensions don't intercept and view the content of requests, providing more privacy. + +## Permissions + +To use this API, an extension must request the `"declarativeNetRequest"` or `"declarativeNetRequestWithHostAccess"` [permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) in its [`manifest.json`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json) file. + +The `"declarativeNetRequest"` permission allows extensions to block and upgrade requests without any [host permissions](/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#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 {{WebExtAPIRef("declarativeNetRequest.getMatchedRules","getMatchedRules")}} and {{WebExtAPIRef("declarativeNetRequest.onRuleMatchedDebug","onRuleMatchedDebug")}} as they return information on declarative rules matched. See [Testing](#testing) for more information. + +## Rules + +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](#matching_precedents) 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: + - 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: + +```json +{ + "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 {{WebExtAPIRef("declarativeNetRequest.RuleCondition","RuleCondition")}} for details. Some examples of URL filters are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
urlFilterMatchesDoes 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.comhttp://example.com/
http://https.com
+ +## Rulesets + +Rules are organized into rulesets: + +- **static rulesets**: collections of rules defined with the [`"declarative_net_request"`](/docs/Mozilla/Add-ons/WebExtensions/manifest.json/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. +- **dynamic ruleset**: rules added or removed using {{WebExtAPIRef("declarativeNetRequest.updateDynamicRules","updateDynamicRules")}}. These rules persist across sessions and extension updates. +- **session ruleset**: rules added or removed using {{WebExtAPIRef("declarativeNetRequest.updateSessionRules","updateSessionRules")}}. These rules do not persist across browser sessions. + +> **Note:** +> Errors and warnings about invalid static rules are only displayed during [testing](#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: + +- specify static rulesets as part of the [`"declarative_net_request"`](/docs/Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request) manifest key up to the value of {{WebExtAPIRef("declarativeNetRequest.MAX_NUMBER_OF_STATIC_RULESETS","MAX_NUMBER_OF_STATIC_RULESETS")}}. +- enable static rulesets up to at least the value of {{WebExtAPIRef("declarativeNetRequest.GUARANTEED_MINIMUM_STATIC_RULES","GUARANTEED_MINIMUM_STATIC_RULES")}}, and the number of enabled static rulesets must not exceed the value of [{{WebExtAPIRef("declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS","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 {{WebExtAPIRef("declarativeNetRequest.getAvailableStaticRuleCount","getAvailableStaticRuleCount")}} to find the number of additional rules they can enable. + +### Dynamic and session-scoped rules + +The number of dynamic and session-scoped rules an extension can add is limited to the value of {{WebExtAPIRef("declarativeNetRequest.MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES","MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES")}}. + +## Matching precedents + +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 {{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](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/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](https://extensionworkshop.com/documentation/develop/web-ext-command-reference/#pref). + +## Comparison with the webRequest API + +- 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. + +## Types + +- {{WebExtAPIRef("declarativeNetRequest.MatchedRule")}} + - : Details of a matched rule. +- {{WebExtAPIRef("declarativeNetRequest.ModifyHeaderInfo")}} + - : The request or response headers to modify for the request. +- {{WebExtAPIRef("declarativeNetRequest.Redirect")}} + - : Details of how the redirect should be performed. Only valid for redirect rules. +- {{WebExtAPIRef("declarativeNetRequest.ResourceType")}} + - : The resource type of a request. +- {{WebExtAPIRef("declarativeNetRequest.Rule")}} + - : An object containing details of a rule. +- {{WebExtAPIRef("declarativeNetRequest.RuleAction")}} + - : An object defining the action to take if a rule is matched. +- {{WebExtAPIRef("declarativeNetRequest.RuleCondition")}} + - : An object defining the condition under which a rule is triggered. +- {{WebExtAPIRef("declarativeNetRequest.URLTransform")}} + - : An object containing details of a URL transformation to perform for a redirect action. + +## Properties + +- {{WebExtAPIRef("declarativeNetRequest.DYNAMIC_RULESET_ID")}} + - : Ruleset ID for the dynamic rules added by the extension. +- {{WebExtAPIRef("declarativeNetRequest.GETMATCHEDRULES_QUOTA_INTERVAL")}} + - : The time interval within which {{WebExtAPIRef("declarativeNetRequest.MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL")}} {{WebExtAPIRef("declarativeNetRequest.getMatchedRules")}} calls can be made. +- {{WebExtAPIRef("declarativeNetRequest.GUARANTEED_MINIMUM_STATIC_RULES")}} + - : The minimum number of static rules guaranteed to an extension across its enabled static rulesets. +- {{WebExtAPIRef("declarativeNetRequest.MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL")}} + - : The number of times {{WebExtAPIRef("declarativeNetRequest.getMatchedRules")}} can be called within a period of {{WebExtAPIRef("declarativeNetRequest.GETMATCHEDRULES_QUOTA_INTERVAL")}}. +- {{WebExtAPIRef("declarativeNetRequest.MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES")}} + - : The maximum number of combined dynamic and session scoped rules an extension can add. +- {{WebExtAPIRef("declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS")}} + - : The maximum number of static rulesets an extension can enable. +- {{WebExtAPIRef("declarativeNetRequest.MAX_NUMBER_OF_REGEX_RULES")}} + - : The maximum number of regular expression rules that an extension can add. +- {{WebExtAPIRef("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`](/docs/Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request) manifest key. +- {{WebExtAPIRef("declarativeNetRequest.SESSION_RULESET_ID")}} + - : The ruleset ID for the session-scoped rules added by the extension. + +## Functions + +- {{WebExtAPIRef("declarativeNetRequest.getAvailableStaticRuleCount()")}} + - : Returns the number of static rules an extension can enable before the global static rule limit is reached. +- {{WebExtAPIRef("declarativeNetRequest.getDynamicRules()")}} + - : Returns the set of dynamic rules for the extension. +- {{WebExtAPIRef("declarativeNetRequest.getEnabledRulesets()")}} + - : Returns the IDs for the set of enabled static rulesets. +- {{WebExtAPIRef("declarativeNetRequest.getMatchedRules()")}} + - : Returns all the rules matched for the extension. +- {{WebExtAPIRef("declarativeNetRequest.getSessionRules()")}} + - : Returns the set of session scoped rules for the extension. +- {{WebExtAPIRef("declarativeNetRequest.isRegexSupported()")}} + - : Checks if a regular expression is supported as a {{WebExtAPIRef("declarativeNetRequest.RuleCondition")}}`.regexFilter` rule condition. +- {{WebExtAPIRef("declarativeNetRequest.setExtensionActionOptions()")}} + - : Configures how the action count for tabs are handled. +- {{WebExtAPIRef("declarativeNetRequest.testMatchOutcome()")}} + - : Checks if any of the extension's `declarativeNetRequest` rules would match a hypothetical request. +- {{WebExtAPIRef("declarativeNetRequest.updateDynamicRules()")}} + - : Modifies the active set of dynamic rules for the extension. +- {{WebExtAPIRef("declarativeNetRequest.updateEnabledRulesets()")}} + - : Updates the set of active static rulesets for the extension. +- {{WebExtAPIRef("declarativeNetRequest.updateSessionRules()")}} + - : Modifies the set of session scoped rules for the extension. + +## Events + +- {{WebExtAPIRef("declarativeNetRequest.onRuleMatchedDebug")}} + - : Fired when a rule is matched with a request when debugging an extension with the "declarativeNetRequestFeedback" permission. + +{{WebExtExamples("h2")}} + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/isregexsupported/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/isregexsupported/index.md new file mode 100644 index 000000000000000..bb2b96662ca6323 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/isregexsupported/index.md @@ -0,0 +1,87 @@ +--- +title: declarativeNetRequest.isRegexSupported +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/isRegexSupported +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Method + - declarativeNetRequest + - isRegexSupported +browser-compat: webextensions.api.declarativeNetRequest.isRegexSupported +--- + +{{AddonSidebar()}} + +Checks if a regular expression is supported as a {{WebExtAPIRef("declarativeNetRequest.RuleCondition")}}`.regexFilter` rule condition. + +## Syntax + +```js-nolint +let count = browser.declarativeNetRequest.isRegexSupported( + regexOptions // object +); +``` + +### Parameters + +- `regexOptions` + + - : An object containing the regular expression to check. + - `isCaseSensitive` {{optional_inline}} + - : `boolean` Whether the regex specified is case sensitive. Default is `true`. + - `regex` + - : `string` The regular expresson to check. + - `requireCapturing` {{optional_inline}} + - : `boolean` Whether the regex specified requires capturing. Capturing is only required for redirect rules that specify a regexSubstition action. The default is false. + +### Return value + +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that fulfills with an object with these properties: + +- `isSupported` + - : `boolean` Whether the regular expression is supported. +- `reason` {{optional_inline}} + - : `string` Specifies the reason why the regular expression is not supported. Possible values are `"syntaxError"` and `"memoryLimitExceeded"`. Only provided if `isSupported` is false. + +If the request fails, the promise is rejected with an error message. + +## Examples + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/matchedrule/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/matchedrule/index.md new file mode 100644 index 000000000000000..8e631e176fb10cd --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/matchedrule/index.md @@ -0,0 +1,66 @@ +--- +title: declarativeNetRequest.MatchedRule +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/MatchedRule +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Type + - declarativeNetRequest + - MatchedRule +browser-compat: webextensions.api.declarativeNetRequest.MatchedRule +--- + +{{AddonSidebar()}} + +An object describing the matched rule. This type may be returned by the {{WebExtAPIRef("declarativeNetRequest.getMatchedRules")}} or {{WebExtAPIRef("declarativeNetRequest.testMatchOutcome")}} methods, or observed through the {{WebExtAPIRef("declarativeNetRequest.onRuleMatchedDebug")}} event. + +## Type + +Values of this type are objects. They contain these properties: + +- `extensionId` + - : A `string`. The ID of the extension, if this rule belongs to a different extension. This property is only available when used with {{WebExtAPIRef("declarativeNetRequest.testMatchOutcome")}}, with the `includeOtherExtensions` option set to `true`. +- `ruleId` + - : A `number`. The matching rule's ID. +- `rulesetId` + - : A `string`. The ID of the [ruleset](/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest#rulesets) this rule belongs to. The value returned is: + - For a rule originating from the set of static rules, the value specified in the "id" key of the ruleset in the [`declarative_net_request.rule_resources` manifest key](/docs/Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request). + - For a rule originating from the set of dynamic rules, the value defined in {{WebExtAPIRef("declarativeNetRequest.DYNAMIC_RULESET_ID")}}, i.e., `"_dynamic"`. + - For a rule originating from the set of session rules, the value defined in {{WebExtAPIRef("declarativeNetRequest.SESSION_RULESET_ID")}}, i.e., `"_session"`. + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/max_getmatchedrules_calls_per_interval/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/max_getmatchedrules_calls_per_interval/index.md new file mode 100644 index 000000000000000..f779c4c31ad63cc --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/max_getmatchedrules_calls_per_interval/index.md @@ -0,0 +1,57 @@ +--- +title: declarativeNetRequest.MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL +tags: + - MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Property + - declarativeNetRequest + - MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL +browser-compat: webextensions.api.declarativeNetRequest.MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL +--- + +{{AddonSidebar()}} + +The number of times {{WebExtAPIRef("declarativeNetRequest.getMatchedRules")}} can be called within a period of {{WebExtAPIRef("declarativeNetRequest.GETMATCHEDRULES_QUOTA_INTERVAL")}}. + +Its value is `20`. + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/max_number_of_dynamic_and_session_rules/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/max_number_of_dynamic_and_session_rules/index.md new file mode 100644 index 000000000000000..0fc8c28d0116b12 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/max_number_of_dynamic_and_session_rules/index.md @@ -0,0 +1,61 @@ +--- +title: declarativeNetRequest.MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES +tags: + - MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Property + - declarativeNetRequest + - MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES +browser-compat: webextensions.api.declarativeNetRequest.MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES +--- + +{{AddonSidebar()}} + +The maximum number of combined dynamic and session scoped rules an extension can add. + +In Chrome, this limit is enforced for the combination of dynamic and session scoped rules. + +In Firefox, each ruleset has its own quota. + +Its value is `5000`. + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/max_number_of_enabled_static_rulesets/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/max_number_of_enabled_static_rulesets/index.md new file mode 100644 index 000000000000000..eb420bf64d530e3 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/max_number_of_enabled_static_rulesets/index.md @@ -0,0 +1,59 @@ +--- +title: declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/MAX_NUMBER_OF_ENABLED_STATIC_RULESETS +tags: + - MAX_NUMBER_OF_ENABLED_STATIC_RULESETS + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Property + - declarativeNetRequest + - MAX_NUMBER_OF_ENABLED_STATIC_RULESETS +browser-compat: webextensions.api.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS +--- + +{{AddonSidebar()}} + +The maximum number of static rulesets an extension can have enabled, i.e., the number of values in the [`declarative_net_request.rule_resources`](/docs/Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request) manifest key with `"enabled"` set to `true`. Static rulesets exceeding the limit are ignored. + +An extension can change the number of enabled rulesets using the {{WebExtAPIRef("declarativeNetRequest.updateEnabledRulesets", "updateEnabledRulesets")}} method. + +Its value is `10`. + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/max_number_of_regex_rules/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/max_number_of_regex_rules/index.md new file mode 100644 index 000000000000000..09aa0ee3fdaafe2 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/max_number_of_regex_rules/index.md @@ -0,0 +1,62 @@ +--- +title: declarativeNetRequest.MAX_NUMBER_OF_REGEX_RULES +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/MAX_NUMBER_OF_REGEX_RULES +tags: + - MAX_NUMBER_OF_REGEX_RULES + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Property + - declarativeNetRequest + - MAX_NUMBER_OF_REGEX_RULES +browser-compat: webextensions.api.declarativeNetRequest.MAX_NUMBER_OF_REGEX_RULES +--- + +{{AddonSidebar()}} + +```suggestion +The maximum number of regular expression rules that an extension can add. + +In Chrome, its value is 1000, and this limit is evaluated separately for the set of dynamic and session rules, and those specified in the rule resources file. + +In Firefox, this limit is evaluated separately per ruleset. + +In Safari, there is no separate limit on the number of `regexFilter` rules. + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/max_number_of_static_rulesets/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/max_number_of_static_rulesets/index.md new file mode 100644 index 000000000000000..b78597dc3f50413 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/max_number_of_static_rulesets/index.md @@ -0,0 +1,57 @@ +--- +title: declarativeNetRequest.MAX_NUMBER_OF_STATIC_RULESETS +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/MAX_NUMBER_OF_STATIC_RULESETS +tags: + - MAX_NUMBER_OF_STATIC_RULESETS + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Property + - declarativeNetRequest + - MAX_NUMBER_OF_STATIC_RULESETS +browser-compat: webextensions.api.declarativeNetRequest.MAX_NUMBER_OF_STATIC_RULESETS +--- + +{{AddonSidebar()}} + +The maximum number of static rulesets an extension can specify as part of the [`declarative_net_request.rule_resources`](/docs/Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request) manifest key. + +Its value is `50`. + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/modifyheaderinfo/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/modifyheaderinfo/index.md new file mode 100644 index 000000000000000..b2622cb202f616c --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/modifyheaderinfo/index.md @@ -0,0 +1,103 @@ +--- +title: declarativeNetRequest.ModifyHeaderInfo +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/ModifyHeaderInfo +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Type + - declarativeNetRequest + - ModifyHeaderInfo +browser-compat: + - webextensions.api.declarativeNetRequest.RuleAction.requestHeaders + - webextensions.api.declarativeNetRequest.RuleAction.responseHeaders +--- + +{{AddonSidebar()}} + +The request or response header to modify for a request, declared in the `rule.action.requestHeaders` array or `rule.action.responseHeaders` array for rules whose {{WebExtAPIRef("declarativeNetRequest.RuleAction", "rule.action")}}`.type` is "modifyHeaders". + +Each object describes one header modification. To modify multiple headers, multiple objects can be specified in these arrays, or across multiple rules. + +Matching `modifyHeaders` rules are applied in the order described at [Matching precedents](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest#matching_precedents). +Within each extension, all `modifyHeaders` rules with a priority lower than or equal to matching `allow` or `allowAllRequests` rules are ignored. + +If multiple `modifyHeaders` rules specify the same header, the resulting modification for the header is determined based on the priority of each rule and the operations specified: + +- If a rule has been appended to a header, then lower-priority rules can only append to that header. `set` and `remove` operations are not permitted. +- If a rule has set a header, lower priority rules cannot modify the header except for `append` rules from the same extension. +- If a rule has removed a header, lower priority rules cannot modify the header. + +## Type + +Values of this type are objects. They contain these properties: + +- `header` + - : A `string`. The name of the header to be modified. +- `operation` + - : A `string`. The operation to be performed on a header. Possible values are `"append"`, `"set"`, and `"remove"`. +- `value` {{optional_inline}} + - : A `string`. The new value for the header. Must be specified for append and set operations. Not allowed for the "remove" operation. + +## Header limits + +In Chrome, `"append"` is supported for the following request headers: + +- `Accept` +- `Accept-Encoding` +- `Accept-Language` +- `Access-Control-Request-Headers` +- `Cache-Control` +- `Connection` +- `Content-Language` +- `Cookie` +- `Forwarded` +- `If-Match` +- `If-None-Match` +- `Keep-Alive` +- `Range` +- `Te` +- `Trailer` +- `Transfer-Encoding` +- `Upgrade` +- `Via` +- `Want-Digest` +- `X-Forwarded-For` + +In Firefox, the extension needs host permissions for the new value of the `Host` header. + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/onrulematcheddebug/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/onrulematcheddebug/index.md new file mode 100644 index 000000000000000..b1820707189cabe --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/onrulematcheddebug/index.md @@ -0,0 +1,110 @@ +--- +title: declarativeNetRequest.onRuleMatchedDebug +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/onRuleMatchedDebug +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Event + - declarativeNetRequest + - onRuleMatchedDebug +browser-compat: webextensions.api.declarativeNetRequest.onRuleMatchedDebug +--- + +{{AddonSidebar()}} + +Fired when a rule is matched with a request. Only available extensions with the `"declarativeNetRequestFeedback"` permission, as this is intended for debugging purposes only. See [Testing](/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest#testing) for details on how testing is enabled in each browser. + +## Syntax + +```js-nolint +browser.declarativeNetRequest.onRuleMatchedDebug.addListener(listener) +browser.declarativeNetRequest.onRuleMatchedDebug.removeListener(listener) +browser.declarativeNetRequest.onRuleMatchedDebug.hasListener(listener) +``` + +Events have three functions: + +- `addListener(listener)` + - : Adds a listener to this event. +- `removeListener(listener)` + - : Stop listening to this event. The `listener` argument is the listener to remove. +- `hasListener(listener)` + - : Check whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise. + +## addListener syntax + +### Parameters + +- `callback` + + - : Function that is called when this event occurs. The function is passed these arguments: + + - `request` + + - : An object containing information about the request the rule matched. + - `documentId` {{optional_inline}} + - : A `string`. The unique identifier for the frame's document, if this request is for a frame. + - `documentLifecycle` {{optional_inline}} + - : A `string`. The lifecycle of the frame's document, if this request is for a frame. Possible values are: `"prerender"`, `"active"`, `"cached"`, or `"pending_deletion"`. + - `frameId` + - : A `number`. The value `0` indicates that the request happens in the main frame. A positive value indicates the ID of a subframe where the request happens. If the document of a (sub-)frame is loaded (type is `main_frame` or `sub_frame`), `frameId` indicates this frame's ID, not the outer frame's ID. Frame IDs are unique within a tab. + - `frameType` {{optional_inline}} + - : A `string`. The type of the frame, if this request is for a frame. Possible values are: `"outermost_frame"`, `"fenced_frame"`, or `"sub_frame"`. + - `initiator` {{optional_inline}} + - : A `string`. The origin where the request was initiated. This does not change through redirects. The string 'null' is used if this is an opaque origin. + - `method` + - : A `string`. A standard HTTP method. + - `parentDocumentId` {{optional_inline}} + - : A `string`. The unique identifier for the frame's parent document, if this request is for a frame and has a parent. + - `parentFrameId` + - : A `number`. The ID of the frame that wraps the frame which sent the request. Set to `-1` if there is no parent frame. + - `requestId` + - : A `string`. The ID of the request. Request IDs are unique within a browser session. + - `tabId` + - : A `number`. The ID of the tab in which the request takes place. Set to `-1` if the request is not related to a tab. + - `type` + - : {{WebExtAPIRef("declarativeNetRequest.ResourceType", "ResourceType")}}. The resource type of the request. + - `url` + - : A `string`. The URL of the request. + + - `rule` + - : {{WebExtAPIRef("declarativeNetRequest.MatchedRule", "MatchedRule")}}. Details of a matched rule. + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/redirect/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/redirect/index.md new file mode 100644 index 000000000000000..c2ab0568a0c6993 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/redirect/index.md @@ -0,0 +1,65 @@ +--- +title: declarativeNetRequest.Redirect +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/Redirect +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Type + - declarativeNetRequest + - Redirect +browser-compat: webextensions.api.declarativeNetRequest.Redirect +--- + +{{AddonSidebar()}} + +Details describing how a redirect should be performed. Only valid for redirect rules. + +## Type + +Values of this type are objects. They contain these properties: + +- `extensionPath` {{optional_inline}} + - : A `string`. The path relative to the extension directory. Should start with '/'. +- `regexSubstitution` {{optional_inline}} + - : A `string`. The substitution pattern for rules that specify a `regexFilter`. The first match of `regexFilter` within the URL is replaced with this pattern. Within `regexSubstitution`, backslash-escaped digits (`\1` to `\9`) are used to insert the corresponding capture groups. `\0` refers to the entire matching text. +- `transform` {{optional_inline}} + - : {{WebExtAPIRef("declarativeNetRequest.URLTransform")}}. The URL transformations to perform. +- `url` {{optional_inline}} + - : A `string`. The redirect URL. Redirects to JavaScript URLs are not allowed. + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/resourcetype/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/resourcetype/index.md new file mode 100644 index 000000000000000..c0cf1017806a1d8 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/resourcetype/index.md @@ -0,0 +1,109 @@ +--- +title: declarativeNetRequest.ResourceType +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/ResourceType +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Type + - declarativeNetRequest + - ResourceType +browser-compat: webextensions.api.declarativeNetRequest.ResourceType +--- + +{{AddonSidebar()}} + +The resource type of a request. Comparable to {{WebExtAPIRef('webRequest.ResourceType')}}. + +## Type + +Values of this type are strings. Possible values are: + +- `beacon` + - : Requests sent through the [Beacon API](/en-US/docs/Web/API/Beacon_API). +- `csp_report` + - : Requests sent to the {{CSP("report-uri")}} given in the {{HTTPHeader("Content-Security-Policy")}} header, when an attempt to violate the policy is detected. +- `font` + - : Web fonts loaded for a {{cssxref("@font-face")}} CSS rule. +- `image` + - : Resources loaded to be rendered as image, except for `imageset` on browsers that support that type (see browser compatibility below). +- `imageset` + - : Images loaded by a {{HTMLElement("picture")}} element or given in an `` element's {{htmlattrxref("srcset", "img")}} attribute. +- `main_frame` + - : Top-level documents loaded into a tab. +- `media` + - : Resources loaded by a {{HTMLElement("video")}} or {{HTMLElement("audio")}} element. +- `object` + + - : Resources loaded by an {{HTMLElement("object")}} or {{HTMLElement("embed")}} element. + + Browsers that don't have a dedicated `object_subrequest` type (see browser compatibility below), also label subsequent requests sent by the plugin as `object`. + +- `object_subrequest` + - : Requests sent by plugins. +- `ping` + + - : Requests sent to the URL given in a hyperlink's {{htmlattrxref("ping", "a")}} attribute, when the hyperlink is followed. + + Browsers that don't have a dedicated `beacon` type (see browser compatibility below), also label requests sent through the Beacon API as `ping`. + +- `script` + - : Code that is loaded to be executed by a {{HTMLElement("script")}} element or running in a [Worker](/en-US/docs/Web/API/Web_Workers_API). +- `speculative` + - : In a speculative connection, the browser has determined that a request to a URI may be coming soon, so it starts a TCP and/or TLS handshake immediately, so it is ready more quickly when the resource is actually requested. Note that this type of connection does not provide valid tab information, so request details such as `tabId`, `frameId`, `parentFrameId`, etc. are inaccurate. +- `stylesheet` + - : [CSS](/en-US/docs/Web/CSS) stylesheets loaded to describe the representation of a document. +- `sub_frame` + - : Documents loaded into an {{HTMLElement("iframe")}} or {{HTMLElement("frame")}} element. +- `web_manifest` + - : [Web App Manifests](/en-US/docs/Web/Manifest) loaded for websites that can be installed to the homescreen. +- `webbundle` + - : Requests initiating a connection to a server through a Web Bundle or [packaged website](https://github.com/WICG/webpackage). +- `websocket` + - : Requests initiating a connection to a server through the [WebSocket API](/en-US/docs/Web/API/WebSockets_API). +- `webtransport` + - : Requests initiating a connection to a server through the [WebTransport API](/en-US/docs/Web/API/WebTransport_API). +- `xml_dtd` + - : [DTDs](/en-US/docs/Glossary/Doctype) loaded for an XML document. +- `xmlhttprequest` + - : Requests sent by an {{domxref("XMLHttpRequest")}} object or through the [Fetch API](/en-US/docs/Web/API/Fetch_API). +- `xslt` + - : [XSLT](/en-US/docs/Web/XSLT) stylesheets loaded for transforming an XML document. +- `other` + - : Resources that aren't covered by any other available type. + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/rule/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/rule/index.md new file mode 100644 index 000000000000000..74cba0ed46d03be --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/rule/index.md @@ -0,0 +1,67 @@ +--- +title: declarativeNetRequest.Rule +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/Rule +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Type + - declarativeNetRequest + - Rule +browser-compat: webextensions.api.declarativeNetRequest.Rule +--- + +{{AddonSidebar()}} + +The object describing the actions to take for matching requests. These can be specified in the static rule resources linked by the [manifest.json's `declarative_net_request` key](Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request), or more dynamically through the {{WebExtAPIRef("declarativeNetRequest.updateDynamicRules")}} or {{WebExtAPIRef("declarativeNetRequest.updateSessionRules")}} methods. + +See [Rules](/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest#rules) on the API overview page for more information about rules. + +## Type + +Values of this type are objects. They contain these properties: + +- `action` + - : {{WebExtAPIRef("declarativeNetRequest.RuleAction")}}. The action to take if this rule is matched. +- `condition` + - : {{WebExtAPIRef("declarativeNetRequest.RuleCondition")}}. The condition under which this rule is triggered. +- `id` + - : `number`. An ID that uniquely identifies a rule within a ruleset. Mandatory and should be >= 1. +- `priority` {{optional_inline}} + - : `number`. Rule priority. Defaults to 1. When specified, should be >= 1. See [Matching precedents](/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest#matching_precedents) for details on how priority affects which rules are applied. + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/ruleaction/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/ruleaction/index.md new file mode 100644 index 000000000000000..97155e96d6ae799 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/ruleaction/index.md @@ -0,0 +1,65 @@ +--- +title: declarativeNetRequest.RuleAction +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/RuleAction +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Type + - declarativeNetRequest + - RuleAction +browser-compat: webextensions.api.declarativeNetRequest.RuleAction +--- + +{{AddonSidebar()}} + +Details of the action to take if a rule is matched. + +## Type + +Values of this type are objects. They contain these properties: + +- `redirect` {{optional_inline}} + - : {{WebExtAPIRef("declarativeNetRequest.Redirect")}}. Describes how the redirect should be performed. Only valid for redirect rules. +- `requestHeaders` {{optional_inline}} + - : {{WebExtAPIRef("declarativeNetRequest.ModifyHeaderInfo")}}. The request headers to modify for the request. Only valid if `RuleActionType` is `"modifyHeaders"`. +- `responseHeaders` {{optional_inline}} + - : {{WebExtAPIRef("declarativeNetRequest.ModifyHeaderInfo")}}. The response headers to modify for the request. Only valid if `RuleActionType` is `"modifyHeaders"`. +- `type` {{optional_inline}} + - : A `string`. The type of action to perform. Possible values are `"block"`, `"redirect"`, `"allow"`, `"upgradeScheme"`, `"modifyHeaders"`, and `"allowAllRequests"`. The use of the `"redirect"` and `"modifyHeaders"` actions require [host permissions](/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions) for the request and request initiator. The "block" and "upgradeScheme" actions also require host permissions unless the "declarativeNetRequest" permission is specified. Without these permissions, matching rules are ignored. See [Permissions at declarativeNetRequest](/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest#permissions). for more information. + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/rulecondition/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/rulecondition/index.md new file mode 100644 index 000000000000000..996f3e4f0221323 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/rulecondition/index.md @@ -0,0 +1,114 @@ +--- +title: declarativeNetRequest.RuleCondition +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/RuleCondition +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Type + - declarativeNetRequest + - RuleCondition +browser-compat: webextensions.api.declarativeNetRequest.RuleCondition +--- + +{{AddonSidebar()}} + +Details of the condition that determines whether a rule matches a request. + +## Type + +Values of this type are objects. They contain these properties: + +- `domainType` {{optional_inline}} + - : A `string`. Specifies whether the network request is first-party or third-party to the domain from where it originated. If omitted, all requests are accepted. Possible values are `"firstParty"` and `"thirdParty"`. +- `domains` {{deprecated_inline}} {{optional_inline}} + - : An array of `string`. Use [`initiatorDomains`](#initiatordomains) instead. The rule only matches network requests originating from this list of domains. +- `excludedDomains` {{deprecated_inline}} {{optional_inline}} + - : An array of `string`. Use [`excludedInitiatorDomains`](#excludedinitiatordomains) instead. The rule does not match network requests originating from this list of domains. +- `initiatorDomains` {{optional_inline}} + - : An array of `string`. The rule only matches network requests originating from this list of domains. If the list is omitted, the rule is applied to requests from all domains. An empty list is not allowed. A [canonical domain](#canonical_domain) should be used. This matches against the request initiator and not the request URL. +- `excludedInitiatorDomains` {{optional_inline}} + - : An array of `string`. The rule does not match network requests originating from this list of domains. If the list is empty or omitted, no domains are excluded. This takes precedence over `initiatorDomains`. A [canonical domain](# whocanonical_domain) should be used. This matches against the request initiator and not the request URL. +- `isUrlFilterCaseSensitive` {{optional_inline}} + - : A `boolean`. Whether the [`urlFilter`](#urlfilter) or [`regexFilter`](#regexfilter) (whichever is specified) is case sensitive. Default is true in (older) versions of Chrome and Safari, and false in Firefox. There is consensus on defaulting to `true` across browsers in [WECG issue 269](https://github.com/w3c/webextensions/issues/269). +- `regexFilter` {{optional_inline}} + - : A `string`. Regular expression to match against the network request URL. Note that: + - The supported format is not stable and varies across browsers, see ["Regular expressions in DNR API (regexFilter)" in WECG issue 344](https://github.com/w3c/webextensions/issues/344) for details. + - Only one of [`urlFilter`](#urlfilter) or [`regexFilter`](#regexfilter) can be specified. + - The [`regexFilter`](#regexfilter) must be composed of only ASCII characters. This is matched against a URL where the host is encoded in the [punycode](https://en.wikipedia.org/wiki/Punycode) format (in case of internationalized domains) and any other non-ascii characters are URL encoded in utf-8. +- `requestDomains` {{optional_inline}} + - : An array of `string`. The rule only matches network requests when the domain matches one from this list. If the list is omitted, the rule is applied to requests from all domains. An empty list is not allowed. A [canonical domain](#canonical_domain) should be used. +- `excludedRequestDomains` {{optional_inline}} + - : An array of `string`. The rule does not match network requests when the domains matches one from this list. If the list is empty or omitted, no domains are excluded. This takes precedence over `requestDomains`. A [canonical domain](#canonical_domain) should be used. +- `requestMethods` {{optional_inline}} + - : An array of `string`. List of HTTP request methods that the rule matches. An empty list is not allowed. Specifying a `requestMethods` rule condition also excludes non-HTTP(s) requests, whereas specifying [`excludedRequestMethods`](#excludedpequestmethods) does not. +- `excludedRequestMethods` {{optional_inline}} + - : An array of `string`. List of request methods that the rule does not match on. Only one of [`requestMethods`](#requestmethods) and `excludedRequestMethods` should be specified. If neither of them is specified, all request methods are matched. +- `resourceTypes` {{optional_inline}} + - : An array of {{WebExtAPIRef("declarativeNetRequest.ResourceType")}}. List of resource types that the rule matches with. An empty list is not allowed. This must be specified for `"allowAllRequests"` rules and may only include the `"sub_frame"` and `"main_frame"` resource types. +- `excludedResourceTypes` {{optional_inline}} + - : An array of {{WebExtAPIRef("declarativeNetRequest.ResourceType")}}. List of resource types that the rule does not match on. Only one of [`resourceTypes`](#resourcetypes) and `excludedResourceTypes` should be specified. If neither of them is specified, all resource types except `"main_frame"` are blocked. +- `tabIds` {{optional_inline}} + - : An array of `number`. List of {{WebExtAPIRef("tabs.Tab")}}.`id` that the rule should match. An ID of {{WebExtAPIRef("tabs.TAB_ID_NONE")}} matches requests that don't originate from a tab. An empty list is not allowed. Only supported for session-scoped rules. +- `excludedTabIds` {{optional_inline}} + - : An array of `number`. List of {{WebExtAPIRef("tabs.Tab")}}.`id` that the rule should not match. An ID of {{WebExtAPIRef("tabs.TAB_ID_NONE")}} excludes requests that do not originate from a tab. Only supported for session-scoped rules. +- `urlFilter` {{optional_inline}} + - : A `string`. The pattern that is matched against the network request URL. Supported constructs: + - '*' : Wildcard: Matches any number of characters. + - '|' : Left or right anchor: If used at either end of the pattern, specifies the beginning or end of the URL respectively. + - '||' : Domain name anchor: If used at the beginning of the pattern, specifies the start of a (sub-)domain of the URL. + - '^' : Separator character: This matches anything except a letter, a digit. or one of _, -, ., or %. The last `^` may also match the end of the URL instead of a separator character. + `urlFilter` is composed of the following parts: (optional left/domain name anchor) + pattern + (optional right anchor). + If omitted, all URLs are matched. An empty string is not allowed. + A pattern beginning with ||* is not allowed. Use * instead. + Note that: + - Only one of `urlFilter` or [`regexFilter`](#regexfilter) can be specified. + - The `urlFilter` must be composed of only ASCII characters. This is matched against a URL where the host is encoded in the [punycode](https://en.wikipedia.org/wiki/Punycode) format (in case of internationalized domains) and any other non-ASCII characters are URL encoded in utf-8. For example, when the request URL is `http://abc.рф?q=ф`, the `urlFilter` is matched against the URL `http://abc.xn--p1ai/?q=%D1%84`. + +### Canonical domain + +Domains specified in `initiatorDomains`, `excludedinitiatorDomains`, `requestDomains`, or `excludedRequestDomains` should comply with the following: + +- Sub-domains such as "a.example.com" are allowed. +- The entries must consist of only _lowercase_ ASCII characters. +- Use [Punycode](https://en.wikipedia.org/wiki/Punycode) encoding for internationalized domains. +- IPv4 addresses must be represented as 4 numbers separated by a dot. +- IPv6 addresses should be represented in their canonical form, wrapped in brackets. + +To programmatically generate the canonical domain for a URL, use the [URL API](/docs/Web/API/URL) and read its `hostname` property, i.e., `new URL(url).hostname`. + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/session_ruleset_id/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/session_ruleset_id/index.md new file mode 100644 index 000000000000000..1c163e447c9090a --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/session_ruleset_id/index.md @@ -0,0 +1,57 @@ +--- +title: declarativeNetRequest.SESSION_RULESET_ID +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/SESSION_RULESET_ID +tags: + - SESSION_RULESET_ID + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Property + - declarativeNetRequest + - SESSION_RULESET_ID +browser-compat: webextensions.api.declarativeNetRequest.SESSION_RULESET_ID +--- + +{{AddonSidebar()}} + +The ruleset ID for the session-scoped rules added by the extension. + +Its value is `"_session"`. + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/setextensionactionoptions/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/setextensionactionoptions/index.md new file mode 100644 index 000000000000000..f02e4d1dc5e4028 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/setextensionactionoptions/index.md @@ -0,0 +1,87 @@ +--- +title: declarativeNetRequest.setExtensionActionOptions +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/setExtensionActionOptions +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Method + - declarativeNetRequest + - setExtensionActionOptions +browser-compat: webextensions.api.declarativeNetRequest.setExtensionActionOptions +--- + +{{AddonSidebar()}} + +Configures whether the action count for tabs is displayed as the extension action's badge text and provides a way for the action count to be incremented. + +## Syntax + +```js-nolint +let count = browser.declarativeNetRequest.setExtensionActionOptions( + extensionActionOptions, // object +); +``` + +### Parameters + +- `extensionActionOptions` + + - : An object containing the configuration details for the action count for tabs. + - `displayActionCountAsBadgeText` {{optional_inline}} + - : `boolean` Whether to automatically display the action count for a page as the extension's badge text. This preference persists across sessions. + - `tabUpdate` {{optional_inline}} + - : `object`. Details of how the tab's action count should be adjusted. See the [tabUpdate](#tabupdate_2) section for more details. + +## Additional objects + +### tabUpdate + +- `increment` + - : `number` The amount to increment the tab's action count by. Negative values decrement the count. +- `tabId` + - : `number` The tab to update the action count for. + +### Return value + +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that fulfills with no arguments. If the request fails, the promise is rejected with an error message. + +## Examples + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/testmatchoutcome/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/testmatchoutcome/index.md new file mode 100644 index 000000000000000..0d41d3fb188b8b7 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/testmatchoutcome/index.md @@ -0,0 +1,96 @@ +--- +title: declarativeNetRequest.testMatchOutcome +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/testMatchOutcome +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Method + - declarativeNetRequest + - testMatchOutcome +browser-compat: webextensions.api.declarativeNetRequest.testMatchOutcome +--- + +{{AddonSidebar()}} + +Checks if any of the extension's `declarativeNetRequest` rules would match a hypothetical request. Only available while testing, as this is intended to be used during extension development. See [Testing](/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest#testing) for details on how testing is enabled in each browser. + +## Syntax + +```js-nolint +let result = await browser.declarativeNetRequest.testMatchOutcome( + request, // object + options // optional object +); +``` + +### Parameters + +- `request` + + - : The details of the request to test. + - `initiator` {{optional_inline}} + - : A `string`. The initiator URL (if any) for the hypothetical request. + - `method` {{optional_inline}} + - : A `string`. The standard (lower case) HTTP method of the hypothetical request. Defaults to `"get"` for HTTP requests and is ignored for non-HTTP requests. + - `tabId` {{optional_inline}} + - : A `number`. The ID of the tab the hypothetical request takes place in. Does not need to correspond to a real tab ID. Default is `-1`, meaning that the request isn't related to a tab. + - `type` + - : {{WebExtAPIRef("declarativeNetRequest.ResourceType")}}. The resource type of the hypothetical request. + - `url` + - : A `string`. The URL of the hypothetical request. + +- `options` {{optional_inline}} + + - : Details of options for the request. + - `includeOtherExtensions` {{optional_inline}} + - : A `boolean`. Whether matching rules from other extensions are included in `matchedRules`. When rules from other extensions match, the resulting `matchedRule` has an `extensionId` property. Defaults to `false`. + +### Return value + +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that fulfills with an object with these properties: + +- `matchedRules` + - : {{WebExtAPIRef("declarativeNetRequest.MatchedRule")}}. Details of the rules (if any) that match the hypothetical request. + +If no rules match, the `matchedRules` array is empty. If the request fails, the promise is rejected with an error message. + +## Examples + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/updatedynamicrules/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/updatedynamicrules/index.md new file mode 100644 index 000000000000000..f138582bd5c715d --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/updatedynamicrules/index.md @@ -0,0 +1,83 @@ +--- +title: declarativeNetRequest.updateDynamicRules +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/updateDynamicRules +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Method + - declarativeNetRequest + - updateDynamicRules +browser-compat: webextensions.api.declarativeNetRequest.updateDynamicRules +--- + +{{AddonSidebar()}} + +Modifies the set of dynamic rules for the extension. The rules with IDs listed in `options.removeRuleIds` are first removed, and then the rules given in `options.addRules` are added. Note that: + +- This update happens as an atomic operation: either all specified rules are added and removed, or an error is returned. +- These rules are persisted across browser sessions and across extension updates. +- Static rules specified as part of the extension package can not be removed using this function. +- {{WebExtAPIRef("declarativeNetRequest.MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES")}} is the maximum number of dynamic and session rules an extension can add. + +## Syntax + +```js-nolint +let updatedRules = browser.declarativeNetRequest.updateDynamicRules( + options // object +); +``` + +### Parameters + +- `options` + + - : An object containing details of the rules to add or delete from the dynamic rules. + - `addRules` {{optional_inline}} + - : An array of {{WebExtAPIRef("declarativeNetRequest.Rule")}}. Details of the rules to add. + - `removeRuleIds` {{optional_inline}} + - : An array of `number`. IDs of the rules to remove. Any invalid IDs are ignored. + +### Return value + +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) If the request was successful, the promise is fulfilled with no arguments. If the request fails, the promise is rejected with an error message. + +## Examples + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/updateenabledrulesets/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/updateenabledrulesets/index.md new file mode 100644 index 000000000000000..ea077a1bea208ba --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/updateenabledrulesets/index.md @@ -0,0 +1,78 @@ +--- +title: declarativeNetRequest.updateEnabledRulesets +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/updateEnabledRulesets +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Method + - declarativeNetRequest + - updateEnabledRulesets +browser-compat: webextensions.api.declarativeNetRequest.updateEnabledRulesets +--- + +{{AddonSidebar()}} + +Updates the extension's set of static rulesets. The rulesets with IDs listed in `options.disableRulesetIds` are first deactivated, and then the rulesets listed in `options.enableRulesetIds` are activated. Note that the set of enabled static rulesets persists across sessions but not across extension updates, i.e. the [`declarative_net_request.rule_resources` manifest key](/docs/Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request) determines the set of enabled static rulesets on each extension update. + +## Syntax + +```js-nolint +let updatedRulesets = browser.declarativeNetRequest.updateEnabledRulesets( + options // object +); +``` + +### Parameters + +- `options` + + - : An object detailing the rulesets to activate or deactivate in the extension's static rulesets. + - `disableRulesetIds` {{optional_inline}} + - : An array of `string`. IDs of static Rulesets to deactivated. + - `enableRulesetIds` {{optional_inline}} + - : An array of `string`. IDs of static Rulesets to activated. + +### Return value + +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) If the request was successful, the promise is fulfilled with no arguments. If the request fails, the promise is rejected with an error message. + +## Examples + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/updatesessionrules/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/updatesessionrules/index.md new file mode 100644 index 000000000000000..d3b7918f972af4a --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/updatesessionrules/index.md @@ -0,0 +1,82 @@ +--- +title: declarativeNetRequest.updateSessionRules +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/updateSessionRules +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Method + - declarativeNetRequest + - updateSessionRules +browser-compat: webextensions.api.declarativeNetRequest.updateSessionRules +--- + +{{AddonSidebar()}} + +Modifies the set of scoped rules for the extension. The rules with IDs listed in `options.removeRuleIds` are first removed, and then the rules given in `options.addRules` are added. Note that: + +- This update happens as an atomic operation: either all specified rules are added and removed, or an error is returned. +- These rules are not persisted across browser sessions. +- {{WebExtAPIRef("declarativeNetRequest.MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES","MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES")}} is the maximum number of dynamic and session rules an extension can add. + +## Syntax + +```js-nolint +let updatedRuleset = browser.declarativeNetRequest.updateSessionRules( + options // object +); +``` + +### Parameters + +- `options` + + - : An object containing details of the rules to add or delete from the dynamic rules. + - `addRules` {{optional_inline}} + - : An array of {{WebExtAPIRef("declarativeNetRequest.Rule")}}. Details of the rules to add. + - `removeRuleIds` {{optional_inline}} + - : An array of `number`. IDs of the rules to remove. Any invalid IDs are ignored. + +### Return value + +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) If the request was successful, the promise is fulfilled with no arguments. If the request fails, the promise is rejected with an error message. + +## Examples + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/urltransform/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/urltransform/index.md new file mode 100644 index 000000000000000..3a58c99a5b7ebe2 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/urltransform/index.md @@ -0,0 +1,89 @@ +--- +title: declarativeNetRequest.URLTransform +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/URLTransform +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Type + - declarativeNetRequest + - URLTransform +browser-compat: webextensions.api.declarativeNetRequest.URLTransform +--- + +{{AddonSidebar()}} + +Details describing a URL transformation to perform for a redirect rule. This object can be specified at {{WebExtAPIRef("declarativeNetRequest.RuleAction", "rule.action")}}.redirect.transform. + +## Type + +Values of this type are objects. They contain these properties: + +- `fragment` {{optional_inline}} + - : A `string`. The new fragment for the request. Should be either empty, in which case the existing fragment is cleared; or should begin with '#'. +- `host` {{optional_inline}} + - : A `string`. The new host name for the request. +- `password` {{optional_inline}} + - : A `string`. The new password for the request. +- `path` {{optional_inline}} + - : A `string`. The new path for the request. If empty, the existing path is cleared. +- `port` {{optional_inline}} + - : A `string`. The new port for the request. If empty, the existing port is cleared. +- `query` {{optional_inline}} + - : A `string`. The new query for the request. Should be either empty, in which case the existing query is cleared; or should begin with '?'. +- `queryTransform` {{optional_inline}} + + - : An object describing how to add, remove, or replace query key-value pairs. Cannot be specified if 'query' is specified. + - `addOrReplaceParams` {{optional_inline}} + + - : An object describing the list of query key-value pairs to be added or replaced. + - `key` + - : A `string`. The key value. + - `replaceOnly` {{optional_inline}} + - : A `boolean`. If true, the query key is replaced only if it's already present. Otherwise, the key is also added if it's missing. Defaults to false. + - `value` + - : A `string`. The value value. + + - `removeParams` {{optional_inline}} + - : A `string`. The list of query keys to be removed. + +- `scheme` {{optional_inline}} + - : A `string`. The new scheme for the request. Allowed values are `"http"`, `"https"`, and the scheme of the extension, for example, "moz-extension" in Firefox or "chrome-extension" in Chrome. When the extension scheme is used, the `host` must be specified to generate a meaningful redirection target. +- `username` {{optional_inline}} + - : A `string`. The new username for the request. + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/resourcetype/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/resourcetype/index.md index 0933b0291657224..798d0a6a7d96b72 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/resourcetype/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/resourcetype/index.md @@ -64,8 +64,6 @@ Values of this type are strings. Possible values are: - : [Web App Manifests](/en-US/docs/Web/Manifest) loaded for websites that can be installed to the homescreen. - `websocket` - : Requests initiating a connection to a server through the [WebSocket API](/en-US/docs/Web/API/WebSockets_API). -- `xbl` - - : [XBL](/en-US/docs/Mozilla/Tech/XBL) bindings loaded to extend the behavior of elements in a document. - `xml_dtd` - : [DTDs](/en-US/docs/Glossary/Doctype) loaded for an XML document. - `xmlhttprequest` diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/declarative_net_request/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/declarative_net_request/index.md new file mode 100644 index 000000000000000..7c18c4ef5c92bd7 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/declarative_net_request/index.md @@ -0,0 +1,95 @@ +--- +title: declarative_net_request +slug: Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request +tags: + - Add-ons + - Extensions + - WebExtensions +browser-compat: webextensions.manifest.declarative_net_request +--- + +{{AddonSidebar}} + + + + + + + + + + + + + + + + + + + + +
TypeObject
MandatoryNo
Manifest version2
Example + 
+"declarative_net_request" : {
+  "rule_resources" : [{
+    "id": "ruleset",
+    "enabled": true,
+    "path": "rules.json"
+  }]
+}
+
+ +Specify static rulesets for use with {{WebExtAPIRef("declarativeNetRequest")}}. + +## Syntax + +The `"declarative_net_request"` key is an object that must contain the `"rule_resources"` property, an array that must include at least one object with these properties: + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
"id"StringA non-empty string uniquely identifying the ruleset. IDs beginning with '_' are reserved for internal use.
"enabled"BooleanWhether the ruleset is enabled by default.
"path"StringThe path of the JSON ruleset relative to the extension directory. See the Rules section of the `declarativeNetRequest` API for information on the content of the ruleset JSON file.
+ +## Example + +```json +"declarative_net_request" : { + "rule_resources" : [{ + "id": "ruleset_1", + "enabled": true, + "path": "rules_1.json" + }, { + "id": "ruleset_2", + "enabled": false, + "path": "rules_2.json" + }] +} +``` + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/index.md index e9bb7ad4e35a639..a1c74bcfd1be43f 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/index.md @@ -22,47 +22,48 @@ It is a [JSON](/en-US/docs/Glossary/JSON)-formatted file, with one exception: it ## List of manifest.json keys -These are the `manifest.json` keys and the manifest versions they are supported in: +These are the `manifest.json` keys; these keys are available in Manifest V2 and above unless otherwise noted: - [action](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/action) (Manifest V3 and above) -- [author](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/author) (Manifest V2 and above) -- [background](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/background) (Manifest V2 and above) -- [browser_action](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action) (Manifest V2) -- [browser_specific_settings](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings) (Manifest V2 and above) -- [chrome_settings_overrides](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/chrome_settings_overrides) (Manifest V2 and above) -- [chrome_url_overrides](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/chrome_url_overrides) (Manifest V2 and above) -- [commands](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/commands) (Manifest V2 and above) -- [content_scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts) (Manifest V2 and above) -- [content_security_policy](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_security_policy) (Manifest V2 and above) -- [default_locale](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/default_locale) (Manifest V2 and above) -- [description](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/description) (Manifest V2 and above) -- [developer](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/developer) (Manifest V2 and above) -- [devtools_page](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/devtools_page) (Manifest V2 and above) -- [dictionaries](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/dictionaries) (Manifest V2 and above) -- [externally_connectable](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/externally_connectable) (Manifest V2 and above) -- [homepage_url](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/homepage_url) (Manifest V2 and above) +- [author](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/author) +- [background](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/background) +- [browser_action](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action) (Manifest V2 only) +- [browser_specific_settings](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings) +- [chrome_settings_overrides](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/chrome_settings_overrides) +- [chrome_url_overrides](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/chrome_url_overrides) +- [commands](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/commands) +- [content_scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts) +- [content_security_policy](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_security_policy) +- [declarative_net_request](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request) +- [default_locale](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/default_locale) +- [description](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/description) +- [developer](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/developer) +- [devtools_page](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/devtools_page) +- [dictionaries](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/dictionaries) +- [externally_connectable](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/externally_connectable) +- [homepage_url](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/homepage_url) - [host_permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/host_permissions) (Manifest V3 and above) -- [icons](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/icons) (Manifest V2 and above) -- [incognito](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/incognito) (Manifest V2 and above) -- [manifest_version](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/manifest_version) (Manifest V2 and above) -- [name](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/name) (Manifest V2 and above) -- [offline_enabled](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/offline_enabled) (Manifest V2 and above) -- [omnibox](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/omnibox) (Manifest V2 and above) -- [optional_permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions) (Manifest V2 and above) -- [options_page](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/options_page) (Manifest V2 and above) -- [options_ui](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/options_ui) (Manifest V2 and above) -- [page_action](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/page_action) (Manifest V2) -- [permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) (Manifest V2 and above) -- [protocol_handlers](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/protocol_handlers) (Manifest V2 and above) -- [short_name](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/short_name) (Manifest V2 and above) -- [sidebar_action](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/sidebar_action) (Manifest V2 and above) -- [storage](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/storage) (Manifest V2 and above) -- [theme](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/theme) (Manifest V2 and above) -- [theme_experiment](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/theme_experiment) (Manifest V2 and above) -- [user_scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/user_scripts) (Manifest V2) -- [version](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/version) (Manifest V2 and above) -- [version_name](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/version_name) (Manifest V2 and above) -- [web_accessible_resources](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/web_accessible_resources) (Manifest V2 and above) +- [icons](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/icons) +- [incognito](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/incognito) +- [manifest_version](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/manifest_version) +- [name](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/name) +- [offline_enabled](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/offline_enabled) +- [omnibox](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/omnibox) +- [optional_permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions) +- [options_page](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/options_page) +- [options_ui](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/options_ui) +- [page_action](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/page_action) (Manifest V2 only in Chrome) +- [permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) +- [protocol_handlers](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/protocol_handlers) +- [short_name](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/short_name) +- [sidebar_action](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/sidebar_action) +- [storage](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/storage) +- [theme](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/theme) +- [theme_experiment](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/theme_experiment) +- [user_scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/user_scripts) (Manifest V2 only) +- [version](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/version) +- [version_name](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/version_name) +- [web_accessible_resources](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/web_accessible_resources) ### Notes about manifest.json keys diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/permissions/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/permissions/index.md index 90da64a5e09affd..673156b3e03240f 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/permissions/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/permissions/index.md @@ -84,7 +84,7 @@ browser.extension.getURL(""); API permissions are specified as keywords, and each keyword names a [WebExtension API](/en-US/docs/Mozilla/Add-ons/WebExtensions/API) that the extension would like to use. -The following keywords are currently available: +These permissions are available in Manifest V2 and above unless otherwise noted: - `activeTab` - `alarms` @@ -100,6 +100,9 @@ The following keywords are currently available: - `contextualIdentities` - `cookies` - `debugger` +- `declarativeNetRequest` +- `declarativeNetRequestFeedback` +- `declarativeNetRequestWithHostAccess` - `dns` - `downloads` - `downloads.open`