From 59611bd3d2541a4eb379f535b9d679e11394f7f4 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Thu, 1 Dec 2022 11:04:11 +1300 Subject: [PATCH 01/36] Add declarativeNetRequest --- .../declarativeNetRequest/domaintype/index.md | 60 +++++++ .../getavailablestaticrulecount/index.md | 101 ++++++++++++ .../getdynamicrules/index.md | 101 ++++++++++++ .../getmatchedrules/index.md | 90 +++++++++++ .../guaranteed_minimum_static_rules/index.md | 59 +++++++ .../api/declarativeNetRequest/index.md | 151 ++++++++++++++++++ .../isregexsupported/index.md | 80 ++++++++++ .../isregexsupportedresult/index.md | 65 ++++++++ .../matchedrule/index.md | 65 ++++++++ .../modifyheaderinfo/index.md | 67 ++++++++ .../onrulematcheddebug/index.md | 116 ++++++++++++++ .../declarativeNetRequest/redirect/index.md | 69 ++++++++ .../requestmethod/index.md | 60 +++++++ .../resourcetype/index.md | 60 +++++++ .../api/declarativeNetRequest/rule/index.md | 69 ++++++++ .../declarativeNetRequest/ruleaction/index.md | 69 ++++++++ .../rulecondition/index.md | 119 ++++++++++++++ .../declarativeNetRequest/ruleset/index.md | 67 ++++++++ .../setextensionactionoptions/index.md | 85 ++++++++++ .../testmatchoutcome/index.md | 92 +++++++++++ .../updateenabledrulesets/index.md | 80 ++++++++++ .../updateruleoptions/index.md | 65 ++++++++ .../urltransform/index.md | 93 +++++++++++ 23 files changed, 1883 insertions(+) create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/domaintype/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/getavailablestaticrulecount/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/getdynamicrules/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/getmatchedrules/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/guaranteed_minimum_static_rules/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/isregexsupported/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/isregexsupportedresult/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/matchedrule/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/modifyheaderinfo/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/onrulematcheddebug/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/redirect/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/requestmethod/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/resourcetype/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/rule/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/ruleaction/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/rulecondition/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/ruleset/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/setextensionactionoptions/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/testmatchoutcome/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updateenabledrulesets/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updateruleoptions/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/urltransform/index.md diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/domaintype/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/domaintype/index.md new file mode 100644 index 000000000000000..dbc5fed05e338e5 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/domaintype/index.md @@ -0,0 +1,60 @@ +--- +title: declarativeNetRequest.DomainType +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/DomainType +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Type + - declarativeNetRequest + - DomainType +browser-compat: webextensions.api.declarativeNetRequest.DomainType +--- + +{{AddonSidebar()}} + +Describes whether the request is first or third party to the frame it originated in. A request is a first-party request if it has the same domain (e[TLD](/docs/Glossary/TLD)+1) as the frame that the request originated in. + +## Type + +Values of this type are strings. Possible values are `"firstParty"` and `"thirdParty"`. + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#type-DomainType) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + 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..6daaebfbdef7733 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/getavailablestaticrulecount/index.md @@ -0,0 +1,101 @@ +--- +title: declarativeNetRequest.getAvailableStaticRuleCount +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/getAvailableStaticRuleCount +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Function + - declarativeNetRequest + - getAvailableStaticRuleCount +browser-compat: webextensions.api.declarativeNetRequest.getAvailableStaticRuleCount +--- + +{{AddonSidebar()}} + +Returns the number of static rules that can be enabled before the global static rule limit is reached. + +> **Note:** This API is available in Manifest V3 or higher. + +## Syntax + +```js-nolint +let count = 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. + +## Examples + +The following example uses the `getTargetElement` method to get the element referred to by the `info.targetElementId` property and then removes it. + +```js +browser.menus.create({ + title: "Remove element", + documentUrlPatterns: ["*://*/*"], + contexts: [ + "audio", + "editable", + "frame", + "image", + "link", + "page", + "password", + "video", + ], + onclick(info, tab) { + browser.tabs.executeScript(tab.id, { + frameId: info.frameId, + code: `browser.menus.getTargetElement(${info.targetElementId}).remove();`, + }); + }, +}); +``` + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#event-onRuleMatchedDebug) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + 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..eb3627307d2d359 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/getdynamicrules/index.md @@ -0,0 +1,101 @@ +--- +title: declarativeNetRequest.getAvailableStaticRuleCount +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/getDynamicRules +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Function + - declarativeNetRequest + - getDynamicRules +browser-compat: webextensions.api.declarativeNetRequest.getDynamicRules +--- + +{{AddonSidebar()}} + +Returns the current set of dynamic rules for the extension. + +> **Note:** This API is available in Manifest V3 or higher. + +## Syntax + +```js-nolint +let count = 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 [`Rule`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/alarms/Alarm) objects. Each of these represents a rule that belongs to the extension. If no rules are active, the array is empty. + +## Examples + +The following example uses the `getTargetElement` method to get the element referred to by the `info.targetElementId` property and then removes it. + +```js +browser.menus.create({ + title: "Remove element", + documentUrlPatterns: ["*://*/*"], + contexts: [ + "audio", + "editable", + "frame", + "image", + "link", + "page", + "password", + "video", + ], + onclick(info, tab) { + browser.tabs.executeScript(tab.id, { + frameId: info.frameId, + code: `browser.menus.getTargetElement(${info.targetElementId}).remove();`, + }); + }, +}); +``` + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#event-onRuleMatchedDebug) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + 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..1c89dc6627d1d46 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/getmatchedrules/index.md @@ -0,0 +1,90 @@ +--- +title: declarativeNetRequest.getMatchedRules +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/getMatchedRules +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Function + - declarativeNetRequest + - getMatchedRules +browser-compat: webextensions.api.declarativeNetRequest.getMatchedRules +--- + +{{AddonSidebar()}} + +Returns all the rules matched for the extension. Callers can optionally 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. + +> **Note:** This API is available in Manifest V3 or higher. + +## Syntax + +```js-nolint +let count = browser.declarativeNetRequest.getMatchedRules(); +``` + +### 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: + +- `rulesMatchedInfo` + + - : An object containing the rules matching the specified filter. + - `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. + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#event-onRuleMatchedDebug) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + 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..31785443ddfe928 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/guaranteed_minimum_static_rules/index.md @@ -0,0 +1,59 @@ +--- +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}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#property-GUARANTEED_MINIMUM_STATIC_RULES) API. + + 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..b23abd4fd62f5ae --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/index.md @@ -0,0 +1,151 @@ +--- +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 block or modify network requests by specifying declarative rules. The use of declarative rules means that the extension doesn't intercept and view the content of requests, providing more privacy. + +To use this API, an extension must request the "declarativeNetRequest" or "the "declarativeNetRequestWithHostAccess" [permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) in its [`manifest.json`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json) file. + +todo + +declarativeNetRequestFeedback +host permissions + +> **Note:** This API is available in Manifest V3 or higher. + +## Types + +- {{WebExtAPIRef("declarativeNetRequest.DomainType")}} + - : Indicates whether a request is first or third party to the frame that it originated in. +- {{WebExtAPIRef("declarativeNetRequest.MatchedRule")}} + - : Details of a matched rule. +- {{WebExtAPIRef("declarativeNetRequest.ModifyHeaderInfo")}} + - : The request headers to modify for the request. +- {{WebExtAPIRef("declarativeNetRequest.Redirect")}} + - : Details of how the redirect should be performed. Only valid for redirect rules. +- {{WebExtAPIRef("declarativeNetRequest.RequestMethod")}} + - : The HTTP request method of a network request. +- {{WebExtAPIRef("declarativeNetRequest.ResourceType")}} + - : The resource type of a request. +- {{WebExtAPIRef("declarativeNetRequest.Rule")}} + - : An object containing details of a dynamic 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.Ruleset")}} + - : An object containing details of a static ruleset. +- {{WebExtAPIRef("declarativeNetRequest.UpdateRuleOptions")}} + - : An object containing lists of rules to add or delete. +- {{WebExtAPIRef("declarativeNetRequest.URLTransform")}} + - : An object containing details of a URL transformation to perform. + +## Properties + +- {{WebExtAPIRef("declarativeNetRequest.GUARANTEED_MINIMUM_STATIC_RULES")}} + - : Returns the number of static rules an extension can enable before the global static rule limit is reached. + +Todo + +- DYNAMIC_RULESET_ID +- GETMATCHEDRULES_QUOTA_INTERVAL +- GUARANTEED_MINIMUM_STATIC_RULES +- MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL +- MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES +- MAX_NUMBER_OF_ENABLED_STATIC_RULESETS +- MAX_NUMBER_OF_REGEX_RULES +- MAX_NUMBER_OF_STATIC_RULESETS +- SESSION_RULESET_ID + +## 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 ... + +Todo + +- getEnabledRulesets + +- {{WebExtAPIRef("declarativeNetRequest.getMatchedRules()")}} + - : Returns all the rules matched for the extension. + +Todo + +- getSessionRules + +- {{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. + +Todo + +- updateDynamicRules + +- {{WebExtAPIRef("declarativeNetRequest.updateEnabledRulesets()")}} + - : Activates or deactivates [static rulesets](). + +Todo + +-e updateSessionRulest + +## Events + +- {{WebExtAPIRef("declarativeNetRequest.onRuleMatchedDebug")}} + - : Fired when a rule is matched with a request when debugging a temporarily installed extension with the "declarativeNetRequestFeedback" permission. + +{{WebExtExamples("h2")}} + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + 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..92016f2f18638ca --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/isregexsupported/index.md @@ -0,0 +1,80 @@ +--- +title: declarativeNetRequest.isRegexSupported +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/isRegexSupported +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Function + - declarativeNetRequest + - isRegexSupported +browser-compat: webextensions.api.declarativeNetRequest.isRegexSupported +--- + +{{AddonSidebar()}} + +Checks if a regular expression is supported as a {{WebExtAPIRef("declarativeNetRequest.RuleCondition")}}`.regexFilter` rule condition. + +> **Note:** This API is available in Manifest V3 or higher. + +## Syntax + +```js-nolint +let count = browser.declarativeNetRequest.isRegexSupported(); +``` + +### Parameters + +### Return value + +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that fulfills with an …. + +- `isRegexSupportedResult` + + - : An object containing details about why the regular expression is or is not supported. + - `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. + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#method-isRegexSupported) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/isregexsupportedresult/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/isregexsupportedresult/index.md new file mode 100644 index 000000000000000..6250064720c5753 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/isregexsupportedresult/index.md @@ -0,0 +1,65 @@ +--- +title: declarativeNetRequest.IsRegexSupportedResult +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/IsRegexSupportedResult +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Type + - declarativeNetRequest + - IsRegexSupportedResult +browser-compat: webextensions.api.declarativeNetRequest.IsRegexSupportedResult +--- + +{{AddonSidebar()}} + +This describes the possible operations for a "modifyHeaders" rule. + +## Type + +Values of this type are objects. They contain 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. + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#type-IsRegexSupportedResult) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + 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..bfa762bd3e39f40 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/matchedrule/index.md @@ -0,0 +1,65 @@ +--- +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()}} + +Details of the rules matching a filter. + +## Type + +Values of this type are objects. They contain these properties: + +- `ruleId` + - : A `number`. The matching rule's ID. +- `rulesetId` + - : A `string`. The ID of the {{WebExtAPIRef("declarativeNetRequest.Ruleset","Ruleset")}} this rule belongs to. For a rule originating from the set of dynamic rules, the value is `"_dynamic"`. + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#type-MatchedRule) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + 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..b090992268fbeeb --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/modifyheaderinfo/index.md @@ -0,0 +1,67 @@ +--- +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.ModifyHeaderInfo +--- + +{{AddonSidebar()}} + +The request headers to modify for a request. + +## 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. + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#type-ModifyHeaderInfo) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + 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..3a254d55bb60b0b --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/onrulematcheddebug/index.md @@ -0,0 +1,116 @@ +--- +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 for [temporarily loaded extensions](https://extensionworkshop.com/documentation/develop/temporary-installation-in-firefox/) with the "declarativeNetRequestFeedback" permission, as this is intended for debugging purposes only. + +> **Note:** This API is available in Manifest V3 or higher. + +## 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` + - : [`ResourceType`](/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/ResourceType). The resource type of the request. + - `url` + - : A `string`. The URL of the request. + + - `rule` + - : [`MatchedRule`](/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/MatchedRule). Details of a matched rule. + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#event-onRuleMatchedDebug) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + 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..b5922a150d5650d --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/redirect/index.md @@ -0,0 +1,69 @@ +--- +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}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#type-Redirect) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/requestmethod/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/requestmethod/index.md new file mode 100644 index 000000000000000..a130ec1d60afb61 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/requestmethod/index.md @@ -0,0 +1,60 @@ +--- +title: declarativeNetRequest.RequestMethod +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/RequestMethod +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Type + - declarativeNetRequest + - RequestMethod +browser-compat: webextensions.api.declarativeNetRequest.RequestMethod +--- + +{{AddonSidebar()}} + +The possible HTTP request methods of a network request. + +## Type + +Values of this type are strings. Possible values are: `"connect"`, `"delete"`, `"get"`, `"head"`, `"options"`, `"patch"`, `"post"`, and `"put"`. + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#type-RequestMethod) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + 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..1b9f2c8d15450aa --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/resourcetype/index.md @@ -0,0 +1,60 @@ +--- +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. + +## Type + +Values of this type are strings. Possible values are: `"main_frame"`, `"sub_frame"`, `"stylesheet"`, `"script"`, `"image"`, `"font"`, `"object"`, `"xmlhttprequest"`, `"ping"`, `"csp_report"`, `"media"`, `"websocket"`, `"webtransport"`, `"webbundle"`, and `"other"`. + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#type-ResourceType) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + 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..e11d1b6d4048f4d --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/rule/index.md @@ -0,0 +1,69 @@ +--- +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 details of a dynamic ruleset. + +## 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. Mandatory and should be >= 1. +- `priority` {{optional_inline}} + - : `number`. Rule priority. Defaults to 1. When specified, should be >= 1. + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#type-Rule) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + 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..33606decb4fa989 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/ruleaction/index.md @@ -0,0 +1,69 @@ +--- +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"`. +- `redirect` {{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"`. + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#type-RuleAction) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + 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..3e37a4447677a61 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/rulecondition/index.md @@ -0,0 +1,119 @@ +--- +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 action to take if a rule is matched. + +## 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. +- `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`. Note that: + - Sub-domains such as "a.example.com" are allowed. + - The entries must consist of only ASCII characters. + - Use [punycode](https://en.wikipedia.org/wiki/Punycode) encoding for internationalized domains. + - This matches against the request initiator and not the request URL. +- `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`. Note that: + - Sub-domains such as "a.example.com" are allowed. + - The entries must consist of only ASCII characters. + - Use [punycode](https://en.wikipedia.org/wiki/Punycode) encoding for internationalized domains. +- `excludedRequestMethods` {{optional_inline}} + - : An array of {{WebExtAPIRef("declarativeNetRequest.RequestMethod")}}. 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. +- `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. +- `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. +- `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. Note that: + - Sub-domains such as "a.example.com" are allowed. + - The entries must consist of only ASCII characters. + - Use [punycode](https://en.wikipedia.org/wiki/Punycode) encoding for internationalized domains. + - 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. +- `regexFilter` {{optional_inline}} + - : A `string`. Regular expression to match against the network request URL. This follows the RE2 syntax. Note that: + - 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. Note that: + - Sub-domains such as "a.example.com" are allowed. + - The entries must consist of only ASCII characters. + - Use [punycode](https://en.wikipedia.org/wiki/Punycode) encoding for internationalized domains. +- `requestMethods` {{optional_inline}} + - : An array of {{WebExtAPIRef("declarativeNetRequest.RequestMethod")}}. 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. +- `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. +- `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. +- `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 %. This also matchet the end of the URL. + `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`. + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#type-RuleCondition) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/ruleset/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/ruleset/index.md new file mode 100644 index 000000000000000..5dc0aabcc43a560 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/ruleset/index.md @@ -0,0 +1,67 @@ +--- +title: declarativeNetRequest.Ruleset +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/Ruleset +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Type + - declarativeNetRequest + - Ruleset +browser-compat: webextensions.api.declarativeNetRequest.Ruleset +--- + +{{AddonSidebar()}} + +Details of a static ruleset. + +## Type + +Values of this type are objects. They contain these properties: + +- `enabled` + - : `boolean`. Whether the ruleset is enabled by default. +- `id` + - : `string`. A non-empty string that uniquely identifies the ruleset. IDs beginning with '_' are reserved for internal use. +- `path` + - : `string`. The path of the JSON ruleset relative to the extension directory. + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#type-Ruleset) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + 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..477cf914d229bfc --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/setextensionactionoptions/index.md @@ -0,0 +1,85 @@ +--- +title: declarativeNetRequest.setExtensionActionOptions +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/setExtensionActionOptions +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Function + - declarativeNetRequest + - setExtensionActionOptions +browser-compat: webextensions.api.declarativeNetRequest.setExtensionActionOptions +--- + +{{AddonSidebar()}} + +Configures if the action count for tabs should be displayed as the extension action's badge text and provides a way for that action count to be incremented. + +> **Note:** This API is available in Manifest V3 or higher. + +## Syntax + +```js-nolint +let count = browser.declarativeNetRequest.setExtensionActionOptions(); +``` + +### 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}} + + - : An object containing aetails of how the tab's action count should be adjusted. + - `increment` + - : `number` The amount to increment the tab's action count by. Negative values decrement the count. + - `tabId` 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 an …. + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#method-setExtensionActionOptions) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + 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..6bf6511470c6def --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/testmatchoutcome/index.md @@ -0,0 +1,92 @@ +--- +title: declarativeNetRequest.testMatchOutcome +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/testMatchOutcome +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Function + - 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 for [temporarily loaded extensions](https://extensionworkshop.com/documentation/develop/temporary-installation-in-firefox/), as this is only intended to be used during extension development. + +> **Note:** This API is available in Manifest V3 or higher. + +## Syntax + +```js-nolint +let count = browser.declarativeNetRequest.testMatchOutcome(); +``` + +### Parameters + +- `testMatchRequestDetails,` + + - : An object containing the match rules to test. + - `initiator` {{optional_inline}} + - : A `string`. The initiator URL (if any) for the hypothetical request. + - `method` {{optional_inline}} + - : {{WebExtAPIRef("declarativeNetRequest.RequestMethod")}}. Standard 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. + +### Return value + +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that fulfills with an object with these properties: + +- `testMatchOutcomeResult` + + - : An object containing the rules the matching test. + - `matchedRules` + - : {{WebExtAPIRef("declarativeNetRequest.MatchedRule")}}. Details of the rules (if any) that match the hypothetical request. + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#event-onRuleMatchedDebug) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + 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..8697ba089af69d4 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updateenabledrulesets/index.md @@ -0,0 +1,80 @@ +--- +title: declarativeNetRequest.updateEnabledRulesets +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/updateEnabledRulesets +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Function + - declarativeNetRequest + - updateEnabledRulesets +browser-compat: webextensions.api.declarativeNetRequest.updateEnabledRulesets +--- + +{{AddonSidebar()}} + +Activate or deactivate [static rulesets](). + +> **Note:** This API is available in Manifest V3 or higher. + +## Syntax + +```js-nolint +let count = browser.declarativeNetRequest.updateEnabledRulesets(); +``` + +### Parameters + +- `updateRulesetOptions` + + - : An object containing the IDs of rulesets to activate or deactivate. + - `disableRulesetIds` {{optional_inline}} + - : An array of `string`. The list of IDs corresponding to the static rulesets to deactivate. + - `enableRulesetIds` {{optional_inline}} + - : An array of `string`. The list of IDs corresponding to the static rulesets to activate. + +### Return value + +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that fulfills with an void. + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#method-updateEnabledRulesets) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updateruleoptions/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updateruleoptions/index.md new file mode 100644 index 000000000000000..3ea6ce78bc527ea --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updateruleoptions/index.md @@ -0,0 +1,65 @@ +--- +title: declarativeNetRequest.UpdateRuleOptions +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/UpdateRuleOptions +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Type + - declarativeNetRequest + - UpdateRuleOptions +browser-compat: webextensions.api.declarativeNetRequest.UpdateRuleOptions +--- + +{{AddonSidebar()}} + +Details of the rules to add or delete from session or dynamic rules. + +## Type + +Values of this type are objects. They contain these properties: + +- `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. + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#type-UpdateRuleOptions) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + 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..14732b4c1b603a1 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/urltransform/index.md @@ -0,0 +1,93 @@ +--- +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. + +## 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 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. + - `addOrReplaceParams` {{optional_inline}} + + - : An object describing the list of query key-value pairs to be added or replaced. + - `key` {{optional_inline}} + - : 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` {{optional_inline}} + - : 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"`, `"ftp"` and `"chrome-extension"`. +- `username` {{optional_inline}} + - : A `string`. The new username for the request. + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#type-URLTransform) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + From b73189a5ec06c83bd524b8ec5f2436a410037fb5 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Sat, 3 Dec 2022 03:47:14 +1300 Subject: [PATCH 02/36] Added properties --- .../dynamic_ruleset_id/index.md | 59 +++++++++++++++++++ .../getmatchedrules_quota_interval/index.md | 59 +++++++++++++++++++ .../api/declarativeNetRequest/index.md | 32 +++++----- .../index.md | 59 +++++++++++++++++++ .../index.md | 59 +++++++++++++++++++ .../index.md | 59 +++++++++++++++++++ .../max_number_of_regex_rules/index.md | 59 +++++++++++++++++++ .../max_number_of_static_rulesets/index.md | 59 +++++++++++++++++++ .../session_ruleset_id/index.md | 59 +++++++++++++++++++ .../updateenabledrulesets/index.md | 15 ++--- 10 files changed, 496 insertions(+), 23 deletions(-) create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/dynamic_ruleset_id/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/getmatchedrules_quota_interval/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/max_getmatchedrules_calls_per_interval/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/max_number_of_dynamic_and_session_rules/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/max_number_of_enabled_static_rulesets/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/max_number_of_regex_rules/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/max_number_of_static_rulesets/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/session_ruleset_id/index.md 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..81f099be3f92b3c --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/dynamic_ruleset_id/index.md @@ -0,0 +1,59 @@ +--- +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. + +Its value is `"_dynamic"`. + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#property-DYNAMIC_RULESET_ID) API. + + 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..5fc92642f4563df --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/getmatchedrules_quota_interval/index.md @@ -0,0 +1,59 @@ +--- +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 set {{WebExtAPIRef("runtime.lastError")}}. {{WebExtAPIRef("declarativeNetRequest.getMatchedRules")}} calls associated with a user gesture are exempt from the quota. + +Its value is `10`. + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#property-GETMATCHEDRULES_QUOTA_INTERVAL) API. + + 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 index b23abd4fd62f5ae..64a580a3d307c52 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/index.md @@ -54,20 +54,24 @@ host permissions ## 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")}} - - : Returns the number of static rules an extension can enable before the global static rule limit is reached. - -Todo - -- DYNAMIC_RULESET_ID -- GETMATCHEDRULES_QUOTA_INTERVAL -- GUARANTEED_MINIMUM_STATIC_RULES -- MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL -- MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES -- MAX_NUMBER_OF_ENABLED_STATIC_RULESETS -- MAX_NUMBER_OF_REGEX_RULES -- MAX_NUMBER_OF_STATIC_RULESETS -- SESSION_RULESET_ID + - : 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 [`"rule_resources"`](/docs/Mozilla/Add-ons/WebExtensions/manifest.json/rule_resources) manifest key. +- {{WebExtAPIRef("declarativeNetRequest.SESSION_RULESET_ID")}} + - : The ruleset ID for the session-scoped rules added by the extension. ## Functions @@ -103,7 +107,7 @@ Todo Todo --e updateSessionRulest +- updateSessionRulest ## Events 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..27cd34e335a1d78 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/max_getmatchedrules_calls_per_interval/index.md @@ -0,0 +1,59 @@ +--- +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}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#property-MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL) API. + + 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..0a5a8ea8326d06d --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/max_number_of_dynamic_and_session_rules/index.md @@ -0,0 +1,59 @@ +--- +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. + +Its value is `5000`. + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#property-MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES) API. + + 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..b31648829526cb9 --- /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. + +Its value is `10`. + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#property-MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) API. + + 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..9087148d5768fc7 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/max_number_of_regex_rules/index.md @@ -0,0 +1,59 @@ +--- +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()}} + +The maximum number of regular expression rules that an extension can add. This limit is evaluated separately for the set of dynamic rules and those specified in the rule resources file. + +Its value is `1000`. + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#property-MAX_NUMBER_OF_REGEX_RULES) API. + + 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..6fe6fb23c1bbdb7 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/max_number_of_static_rulesets/index.md @@ -0,0 +1,59 @@ +--- +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 [`"rule_resources"`](/docs/Mozilla/Add-ons/WebExtensions/manifest.json/rule_resources) manifest key. + +Its value is `50`. + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#property-MAX_NUMBER_OF_STATIC_RULESETS) API. + + 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..ab32de361da2837 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/session_ruleset_id/index.md @@ -0,0 +1,59 @@ +--- +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}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#property-SESSION_RULESET_ID) API. + + 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 index 8697ba089af69d4..ee497734c1d40ea 100644 --- 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 @@ -22,22 +22,19 @@ Activate or deactivate [static rulesets](). ## Syntax ```js-nolint -let count = browser.declarativeNetRequest.updateEnabledRulesets(); +let updatedRulesets = browser.declarativeNetRequest.updateEnabledRulesets( + options // object +); ``` ### Parameters -- `updateRulesetOptions` - - - : An object containing the IDs of rulesets to activate or deactivate. - - `disableRulesetIds` {{optional_inline}} - - : An array of `string`. The list of IDs corresponding to the static rulesets to deactivate. - - `enableRulesetIds` {{optional_inline}} - - : An array of `string`. The list of IDs corresponding to the static rulesets to activate. +- `options` + - : {{WebExtAPIRef("declarativeNetRequest.UpdateRuleOptions")}}. Details of the rules to add or delete from session or dynamic rules. ### Return value -A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that fulfills with an void. +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 failed, the promise is rejected with an error message. {{WebExtExamples}} From 0aef595e766827b5936432cc49d2b420efe03eed Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Tue, 6 Dec 2022 10:56:27 +1300 Subject: [PATCH 03/36] Add functions and events --- .../getavailablestaticrulecount/index.md | 31 +------ .../getdynamicrules/index.md | 33 +------- .../getenabledrulesets/index.md | 76 +++++++++++++++++ .../getmatchedrules/index.md | 25 +++--- .../getsessionrules/index.md | 76 +++++++++++++++++ .../api/declarativeNetRequest/index.md | 31 +++---- .../isregexsupported/index.md | 29 +++++-- .../setextensionactionoptions/index.md | 8 +- .../testmatchoutcome/index.md | 17 ++-- .../updatedynamicrules/index.md | 84 +++++++++++++++++++ .../updateenabledrulesets/index.md | 13 ++- .../updatesessionruleset/index.md | 83 ++++++++++++++++++ 12 files changed, 396 insertions(+), 110 deletions(-) create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/getenabledrulesets/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/getsessionrules/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updatedynamicrules/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updatesessionruleset/index.md 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 index 6daaebfbdef7733..31bb3005de0c31e 100644 --- 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 @@ -15,7 +15,7 @@ browser-compat: webextensions.api.declarativeNetRequest.getAvailableStaticRuleCo {{AddonSidebar()}} -Returns the number of static rules that can be enabled before the global static rule limit is reached. +Returns the number of static rules that can be activated before the global static rule limit is reached. > **Note:** This API is available in Manifest V3 or higher. @@ -31,42 +31,17 @@ 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. +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 -The following example uses the `getTargetElement` method to get the element referred to by the `info.targetElementId` property and then removes it. - -```js -browser.menus.create({ - title: "Remove element", - documentUrlPatterns: ["*://*/*"], - contexts: [ - "audio", - "editable", - "frame", - "image", - "link", - "page", - "password", - "video", - ], - onclick(info, tab) { - browser.tabs.executeScript(tab.id, { - frameId: info.frameId, - code: `browser.menus.getTargetElement(${info.targetElementId}).remove();`, - }); - }, -}); -``` - {{WebExtExamples}} ## Browser compatibility {{Compat}} -> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#event-onRuleMatchedDebug) API. +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#method-getAvailableStaticRuleCount) API. > > Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. 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 index eb3627307d2d359..2c8639fe85810ec 100644 --- 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 @@ -15,14 +15,14 @@ browser-compat: webextensions.api.declarativeNetRequest.getDynamicRules {{AddonSidebar()}} -Returns the current set of dynamic rules for the extension. +Returns the set of dynamic rules for the extension. > **Note:** This API is available in Manifest V3 or higher. ## Syntax ```js-nolint -let count = browser.declarativeNetRequest.getDynamicRules(); +let gettingDynamicRules = browser.declarativeNetRequest.getDynamicRules(); ``` ### Parameters @@ -31,42 +31,17 @@ This function takes no parameters. ### Return value -A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) is fulfilled with an array of [`Rule`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/alarms/Alarm) objects. Each of these represents a rule that belongs to the extension. If no rules are active, the array is empty. +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 -The following example uses the `getTargetElement` method to get the element referred to by the `info.targetElementId` property and then removes it. - -```js -browser.menus.create({ - title: "Remove element", - documentUrlPatterns: ["*://*/*"], - contexts: [ - "audio", - "editable", - "frame", - "image", - "link", - "page", - "password", - "video", - ], - onclick(info, tab) { - browser.tabs.executeScript(tab.id, { - frameId: info.frameId, - code: `browser.menus.getTargetElement(${info.targetElementId}).remove();`, - }); - }, -}); -``` - {{WebExtExamples}} ## Browser compatibility {{Compat}} -> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#event-onRuleMatchedDebug) API. +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#method-getDynamicRules) API. > > Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. 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..1cf0036514cf13f --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/getenabledrulesets/index.md @@ -0,0 +1,76 @@ +--- +title: declarativeNetRequest.getEnabledRulesets +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/getEnabledRulesets +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Function + - declarativeNetRequest + - getEnabledRulesets +browser-compat: webextensions.api.declarativeNetRequest.getEnabledRulesets +--- + +{{AddonSidebar()}} + +Returns the IDs for the set of activated static rulesets. + +> **Note:** This API is available in Manifest V3 or higher. + +## Syntax + +```js-nolint +let rulesetIds = 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}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#method-getEnabledRulesets) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + 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 index 1c89dc6627d1d46..47d205e87766b00 100644 --- 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 @@ -15,14 +15,16 @@ browser-compat: webextensions.api.declarativeNetRequest.getMatchedRules {{AddonSidebar()}} -Returns all the rules matched for the extension. Callers can optionally 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. +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. > **Note:** This API is available in Manifest V3 or higher. ## Syntax ```js-nolint -let count = browser.declarativeNetRequest.getMatchedRules(); +let gettingMatchedRules = browser.declarativeNetRequest.getMatchedRules( + filter // object +); ``` ### Parameters @@ -39,15 +41,16 @@ let count = browser.declarativeNetRequest.getMatchedRules(); A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that fulfills with an object with these properties: -- `rulesMatchedInfo` +- `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. - - : An object containing the rules matching the specified filter. - - `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}} @@ -55,7 +58,7 @@ A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that {{Compat}} -> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#event-onRuleMatchedDebug) API. +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#method-getMatchedRules) API. > > Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. 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..0b2f0ada4668977 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/getsessionrules/index.md @@ -0,0 +1,76 @@ +--- +title: declarativeNetRequest.getSessionRules +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/getSessionRules +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Function + - declarativeNetRequest + - getSessionRules +browser-compat: webextensions.api.declarativeNetRequest.getSessionRules +--- + +{{AddonSidebar()}} + +Returns the active set of session scoped rules for the extension. + +> **Note:** This API is available in Manifest V3 or higher. + +## Syntax + +```js-nolint +let sessionScopedRules = 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}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#method-getSessionRules) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + 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 index 64a580a3d307c52..16747b97d1bbe21 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/index.md @@ -78,36 +78,25 @@ host permissions - {{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 ... - -Todo - -- getEnabledRulesets - + - : 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. - -Todo - -- getSessionRules - +- {{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. - -Todo - -- updateDynamicRules - +- {{WebExtAPIRef("declarativeNetRequest.updateDynamicRules()")}} + - : Modifies the active set of dynamic rules for the extension. - {{WebExtAPIRef("declarativeNetRequest.updateEnabledRulesets()")}} - - : Activates or deactivates [static rulesets](). - -Todo - -- updateSessionRulest + - : Updates the set of active static rulesets for the extension. +- {{WebExtAPIRef("declarativeNetRequest.updateSessionRuleset()")}} + - : Modifies the set of session scoped rules for the extension. ## Events 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 index 92016f2f18638ca..25a69d996adabb1 100644 --- 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 @@ -22,22 +22,35 @@ Checks if a regular expression is supported as a {{WebExtAPIRef("declarativeNetR ## Syntax ```js-nolint -let count = browser.declarativeNetRequest.isRegexSupported(); +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 …. +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. -- `isRegexSupportedResult` +If the request fails, the promise is rejected with an error message. - - : An object containing details about why the regular expression is or is not supported. - - `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. +## Examples {{WebExtExamples}} 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 index 477cf914d229bfc..a33e60f4941a10d 100644 --- 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 @@ -15,7 +15,7 @@ browser-compat: webextensions.api.declarativeNetRequest.setExtensionActionOption {{AddonSidebar()}} -Configures if the action count for tabs should be displayed as the extension action's badge text and provides a way for that action count to be incremented. +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. > **Note:** This API is available in Manifest V3 or higher. @@ -37,12 +37,14 @@ let count = browser.declarativeNetRequest.setExtensionActionOptions(); - : An object containing aetails of how the tab's action count should be adjusted. - `increment` - : `number` The amount to increment the tab's action count by. Negative values decrement the count. - - `tabId` tabId + - `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 an …. +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}} 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 index 6bf6511470c6def..96046b1e3d88667 100644 --- 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 @@ -15,19 +15,21 @@ browser-compat: webextensions.api.declarativeNetRequest.testMatchOutcome {{AddonSidebar()}} -Checks if any of the extension's `declarativeNetRequest` rules would match a hypothetical request. Only available for [temporarily loaded extensions](https://extensionworkshop.com/documentation/develop/temporary-installation-in-firefox/), as this is only intended to be used during extension development. +Checks if any of the extension's `declarativeNetRequest` rules would match a hypothetical request. Only available for [temporarily loaded extensions](https://extensionworkshop.com/documentation/develop/temporary-installation-in-firefox/), as this is intended to be used during extension development. > **Note:** This API is available in Manifest V3 or higher. ## Syntax ```js-nolint -let count = browser.declarativeNetRequest.testMatchOutcome(); +let count = browser.declarativeNetRequest.testMatchOutcome( + rules // array +); ``` ### Parameters -- `testMatchRequestDetails,` +- `testMatchRequestDetails` - : An object containing the match rules to test. - `initiator` {{optional_inline}} @@ -45,11 +47,12 @@ let count = browser.declarativeNetRequest.testMatchOutcome(); A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that fulfills with an object with these properties: -- `testMatchOutcomeResult` +- `matchedRules` + - : {{WebExtAPIRef("declarativeNetRequest.MatchedRule")}}. Details of the rules (if any) that match the hypothetical request. - - : An object containing the rules the matching test. - - `matchedRules` - - : {{WebExtAPIRef("declarativeNetRequest.MatchedRule")}}. Details of the rules (if any) that match the hypothetical request. +If no rules match, the object is empty. If the request fails, the promise is rejected with an error message. + +## Examples {{WebExtExamples}} 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..a65a5a288f25ab5 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updatedynamicrules/index.md @@ -0,0 +1,84 @@ +--- +title: declarativeNetRequest.updateDynamicRules +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/updateDynamicRules +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Function + - 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. + +> **Note:** This API is available in Manifest V3 or higher. + +## Syntax + +```js-nolint +let updatedRules = browser.declarativeNetRequest.updateDynamicRules( + options // object +); +``` + +### Parameters + +- `options` + - : {{WebExtAPIRef("declarativeNetRequest.UpdateRuleOptions")}}. Details of the rules to add or delete from the dynamic rules. + +### 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}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#method-updateDynamicRules) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + 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 index ee497734c1d40ea..610c58aa8d22136 100644 --- 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 @@ -15,7 +15,7 @@ browser-compat: webextensions.api.declarativeNetRequest.updateEnabledRulesets {{AddonSidebar()}} -Activate or deactivate [static rulesets](). +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 `rule_resources` manifest key determines the set of enabled static rulesets on each extension update. > **Note:** This API is available in Manifest V3 or higher. @@ -30,11 +30,18 @@ let updatedRulesets = browser.declarativeNetRequest.updateEnabledRulesets( ### Parameters - `options` - - : {{WebExtAPIRef("declarativeNetRequest.UpdateRuleOptions")}}. Details of the rules to add or delete from session or dynamic rules. + + - : 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 failed, the promise is rejected with an error message. +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}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updatesessionruleset/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updatesessionruleset/index.md new file mode 100644 index 000000000000000..bd763ba1a23329d --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updatesessionruleset/index.md @@ -0,0 +1,83 @@ +--- +title: declarativeNetRequest.updateSessionRuleset +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/updateSessionRuleset +tags: + - API + - Add-ons + - Extensions + - Reference + - WebExtensions + - Function + - declarativeNetRequest + - updateSessionRulest +browser-compat: webextensions.api.declarativeNetRequest.updateSessionRuleset +--- + +{{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 and are backed in memory. +- {{WebExtAPIRef("declarativeNetRequest.MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES")}} is the maximum number of dynamic and session rules an extension can add. + +> **Note:** This API is available in Manifest V3 or higher. + +## Syntax + +```js-nolint +let updatedRuleset = browser.declarativeNetRequest.updateSessionRuleset( + options // object +); +``` + +### Parameters + +- `options` + - : {{WebExtAPIRef("declarativeNetRequest.UpdateRuleOptions")}}. Details of the rules to add or delete from the session rules. + +### 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}} + +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#method-updateSessionRuleset) API. +> +> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. + + From d5750c535efaaab8fead2042154f4740d9d63509 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Wed, 7 Dec 2022 11:59:08 +1300 Subject: [PATCH 04/36] Added manifest and permissions details --- .../api/declarativeNetRequest/index.md | 11 ++- .../onrulematcheddebug/index.md | 2 +- .../declarative_net_request/index.md | 95 +++++++++++++++++++ .../webextensions/manifest.json/index.md | 77 +++++++-------- .../manifest.json/permissions/index.md | 5 +- 5 files changed, 145 insertions(+), 45 deletions(-) create mode 100644 files/en-us/mozilla/add-ons/webextensions/manifest.json/declarative_net_request/index.md 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 index 16747b97d1bbe21..2e4565d261bcf4a 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/index.md @@ -14,17 +14,18 @@ browser-compat: webextensions.api.declarativeNetRequest {{AddonSidebar}} -This API enables extensions to block or modify network requests by specifying declarative rules. The use of declarative rules means that the extension doesn't intercept and view the content of requests, providing more privacy. +This API enables extensions to block or modify network requests using declarative rules. The use of declarative rules means that the extension doesn't intercept and view the content of requests, providing more privacy. -To use this API, an extension must request the "declarativeNetRequest" or "the "declarativeNetRequestWithHostAccess" [permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) in its [`manifest.json`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json) file. +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. -todo +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. -declarativeNetRequestFeedback -host permissions +The `"declarativeNetRequestFeedback"` permission is required to use {{WebExtAPIRef("declarativeNetRequest.getmatchedrules","getmatchedrules")}} and {{WebExtAPIRef("declarativeNetRequest.onRuleMatchedDebug","onRuleMatchedDebug")}} as they return information on declarative rules matched. > **Note:** This API is available in Manifest V3 or higher. +## Rules + ## Types - {{WebExtAPIRef("declarativeNetRequest.DomainType")}} 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 index 3a254d55bb60b0b..7e5fd8f7b7d8aac 100644 --- 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 @@ -15,7 +15,7 @@ browser-compat: webextensions.api.declarativeNetRequest.onRuleMatchedDebug {{AddonSidebar()}} -Fired when a rule is matched with a request. Only available for [temporarily loaded extensions](https://extensionworkshop.com/documentation/develop/temporary-installation-in-firefox/) with the "declarativeNetRequestFeedback" permission, as this is intended for debugging purposes only. +Fired when a rule is matched with a request. Only available for [temporarily loaded extensions](https://extensionworkshop.com/documentation/develop/temporary-installation-in-firefox/) with the `"declarativeNetRequestFeedback"` permission, as this is intended for debugging purposes only. > **Note:** This API is available in Manifest V3 or higher. 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..61ea0758a5b519b --- /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 version3
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..6b969118d04630a 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) (Manifest V3 and above) +- [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) +- [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..5cb6525664aeb64 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` (Manifest V3 and above) +- `declarativeNetRequestFeedback` (Manifest V3 and above) +- `declarativeNetRequestWithHostAccess` (Manifest V3 and above) - `dns` - `downloads` - `downloads.open` From 1005f78bc816c91cc2bb3d9908b4f4cc127d9671 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Thu, 8 Dec 2022 23:01:30 +1300 Subject: [PATCH 05/36] Added API narrative + corrections --- .../api/declarativeNetRequest/index.md | 282 +++++++++++++++++- .../index.md | 14 +- 2 files changed, 286 insertions(+), 10 deletions(-) rename files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/{updatesessionruleset => updatesessionrules}/index.md (91%) 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 index 2e4565d261bcf4a..47ce0784daa588f 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/index.md @@ -14,11 +14,11 @@ browser-compat: webextensions.api.declarativeNetRequest {{AddonSidebar}} -This API enables extensions to block or modify network requests using declarative rules. The use of declarative rules means that the extension doesn't intercept and view the content of requests, providing more privacy. +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. 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. 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 `"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. @@ -26,6 +26,282 @@ The `"declarativeNetRequestFeedback"` permission is required to use {{WebExtAPIR ## Rules +The declarative rules are defined by four fields: + +- `id` – An ID that uniquely identifies a rule. 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 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. + - prevent a request from getting blocked by negating any matching blocked rules. + - redirect a network request. + - modify headers from a network request. + +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; they are backed in memory by the browser. + +> **Note:** +> Errors and warnings about invalid static rules are only displayed for [temporarily loaded extensions](https://extensionworkshop.com/documentation/develop/temporary-installation-in-firefox/). Invalid static rules in permanently installed extensions are ignored. Therefore, it's important to verify that your static rulesets are valid by testing with a temporarily loaded version of your extension. + +## 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 + +Before a request is sent, each extension is queried for an action to take. In order of precedence, these actions are: + +1. Actions that block requests of type `block`. +2. Actions that redirect requests of type `redirect` or `upgradeScheme`. +3. Actions that allow requests of type `allow` or `allowAllRequests`. + +If more than one extension returns an action, the extension whose action has the highest precedence gets priority. If more than one extension returns an action with the same priority, the most recently installed extension gets priority. + +When an extension is queried for how to handle a request, the matching rule with the highest `priority` is returned. If more than one matching rule has the highest `priority`, the tie is broken based on the action type, in this order of precedence: + +1. `allow` +2. `allowAllRequests` +3. `block` +4. `upgradeScheme` +5. `redirect` + +If the request is not blocked or redirected, the matching `modifyHeaders` rules are evaluated, with the most recently installed extensions getting priority. Within each extension, all `modifyHeaders` rules with a priority lower than 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 further modify the header, except for `append` rules from the same extension. +- If a rule has removed a header, lower priority rules cannot further modify the header. + +## 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, resulting in less memory consumption. +- 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. +- 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. + +## Example + +### manifest.json + +```json +{ + "name": "declarativeNetRequest extension", + "version": "1", + "declarative_net_request": { + "rule_resources": [{ + "id": "ruleset_1", + "enabled": true, + "path": "rules.json" + }] + }, + "permissions": [ + "*://*.google.com/*", + "*://*.abcd.com/*", + "*://*.example.com/*", + "https://*.xyz.com/*", + "*://*.headers.com/*", + "declarativeNetRequest" + ], + "manifest_version": 2 +} +``` + +### rules.json + +```json +[ + { + "id": 1, + "priority": 1, + "action": { "type": "block" }, + "condition": {"urlFilter": "google.com", "resourceTypes": ["main_frame"] } + }, + { + "id": 2, + "priority": 1, + "action": { "type": "allow" }, + "condition": { "urlFilter": "google.com/123", "resourceTypes": ["main_frame"] } + }, + { + "id": 3, + "priority": 2, + "action": { "type": "block" }, + "condition": { "urlFilter": "google.com/12345", "resourceTypes": ["main_frame"] } + }, + { + "id": 4, + "priority": 1, + "action": { "type": "redirect", "redirect": { "url": "https://example.com" } }, + "condition": { "urlFilter": "google.com", "resourceTypes": ["main_frame"] } + }, + { + "id": 5, + "priority": 1, + "action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } }, + "condition": { "urlFilter": "abcd.com", "resourceTypes": ["main_frame"] } + }, + { + "id": 6, + "priority": 1, + "action": { + "type": "redirect", + "redirect": { + "transform": { "scheme": "https", "host": "new.example.com" } + } + }, + "condition": { "urlFilter": "||example.com", "resourceTypes": ["main_frame"] } + }, + { + "id": 7, + "priority": 1, + "action": { + "type": "redirect", + "redirect": { + "regexSubstitution": "https://\\1.xyz.com/" + } + }, + "condition": { + "regexFilter": "^https://www\\.(abc|def)\\.xyz\\.com/", + "resourceTypes": [ + "main_frame" + ] + } + }, + { + "id" : 8, + "priority": 2, + "action" : { + "type" : "allowAllRequests" + }, + "condition" : { + "urlFilter" : "||b.com/path", + "resourceTypes" : ["sub_frame"] + } + }, + { + "id" : 9, + "priority": 1, + "action" : { + "type" : "block" + }, + "condition" : { + "urlFilter" : "script.js", + "resourceTypes" : ["script"] + } + }, + { + "id": 10, + "priority": 2, + "action": { + "type": "modifyHeaders", + "responseHeaders": [ + { "header": "h1", "operation": "remove" }, + { "header": "h2", "operation": "set", "value": "v2" }, + { "header": "h3", "operation": "append", "value": "v3" } + ] + }, + "condition": { "urlFilter": "headers.com/123", "resourceTypes": ["main_frame"] } + }, + { + "id": 11, + "priority": 1, + "action": { + "type": "modifyHeaders", + "responseHeaders": [ + { "header": "h1", "operation": "set", "value": "v4" }, + { "header": "h2", "operation": "append", "value": "v5" }, + { "header": "h3", "operation": "append", "value": "v6" } + ] + }, + "condition": { "urlFilter": "headers.com/12345", "resourceTypes": ["main_frame"] } + }, +] +``` + +To illustrate how this rule set affects requests, consider: + +- navigation to `"https://google.com"`. Rules with ID (1) and (4) match. The request iw blocked because blocking rules have higher priority than redirect rules when the `"priority"` is the same. +- navigation to `"https://google.com/1234"`. Rules with ID (1), (2), and (4) match. Because the request has a matching `allow` rule and no higher priority rules, the request is not blocked nor redirected and continues to `"https://google.com/1234"`. +- navigation to `"https://google.com/12345"` Rules with ID (1), (2), (3), and (4) match. The request is blocked because rule (3) has the highest priority, overriding all other matching rules. +- navigation to `"https://abcd.com"`. The rule with ID (5) matches. Since rule (5) specifies an extension path, the request is redirected to `"chrome-extension://EXTENSION_ID/a.jpg"`. +- navigation to `"http://example.com/path"`. The rule with ID (6) matches. Since rule (6) specifies a URL transform, the request is redirected to `"https://new.example.com/path"`. +- a navigation to `"https://www.abc.xyz.com/path"`. The rule with ID (7) matches. The request is redirected to `"https://abc.xyz.com/path"`. +- this request hierarchy: + - (main-frame request) + - (sub-frame request, matches the rule with ID (8)) + - (sub-frame request, matches the rule with ID (8)) + - (script request, matches the rules with IDs (8, 9) but (8) has higher priority) + - (script request, matches the rules with IDs (8, 9) but (8) has higher priority) + - (sub-frame request) + - (script request, matches the rule with ID (9)) All requests in green will be allow-listed due to rule with ID (8) and not be evaluated by the extensions' ruleset. Requests in red are blocked due to rule with ID (9). +- navigation to `"https://headers.com/12345"` with response headers `{ "h1": "initial_1", "h2": "initial_2" }`. Rules with ID (10) and (11) match. The request has its response headers modified to `{ "h2": "v2", "h2": "v5", "h3": "v3", "h3": "v6" }`. Header `h1` is removed by (10), `h2` is set by (10) then appended by (11), and `h3` is appended by (10) and (11). + ## Types - {{WebExtAPIRef("declarativeNetRequest.DomainType")}} @@ -96,7 +372,7 @@ The `"declarativeNetRequestFeedback"` permission is required to use {{WebExtAPIR - : 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.updateSessionRuleset()")}} +- {{WebExtAPIRef("declarativeNetRequest.updateSessionRules()")}} - : Modifies the set of session scoped rules for the extension. ## Events diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updatesessionruleset/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updatesessionrules/index.md similarity index 91% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updatesessionruleset/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updatesessionrules/index.md index bd763ba1a23329d..b9f354e7e07af0c 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updatesessionruleset/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updatesessionrules/index.md @@ -1,6 +1,6 @@ --- -title: declarativeNetRequest.updateSessionRuleset -slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/updateSessionRuleset +title: declarativeNetRequest.updateSessionRules +slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/updateSessionRules tags: - API - Add-ons @@ -9,8 +9,8 @@ tags: - WebExtensions - Function - declarativeNetRequest - - updateSessionRulest -browser-compat: webextensions.api.declarativeNetRequest.updateSessionRuleset + - updateSessionRules +browser-compat: webextensions.api.declarativeNetRequest.updateSessionRules --- {{AddonSidebar()}} @@ -19,14 +19,14 @@ Modifies the set of scoped rules for the extension. The rules with IDs listed in - 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 and are backed in memory. -- {{WebExtAPIRef("declarativeNetRequest.MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES")}} is the maximum number of dynamic and session rules an extension can add. +- {{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. > **Note:** This API is available in Manifest V3 or higher. ## Syntax ```js-nolint -let updatedRuleset = browser.declarativeNetRequest.updateSessionRuleset( +let updatedRuleset = browser.declarativeNetRequest.updateSessionRules( options // object ); ``` @@ -48,7 +48,7 @@ A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) If th {{Compat}} -> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#method-updateSessionRuleset) API. +> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#method-updateSessionRules) API. > > Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. From fd67a1ef8d45bab604fe21f00c87907384b6c4ee Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Fri, 9 Dec 2022 12:36:57 +1300 Subject: [PATCH 06/36] Function > Method, deleted unused DomainType --- .../declarativeNetRequest/domaintype/index.md | 60 ------------------- .../getavailablestaticrulecount/index.md | 2 +- .../getdynamicrules/index.md | 2 +- .../getenabledrulesets/index.md | 2 +- .../getmatchedrules/index.md | 2 +- .../getsessionrules/index.md | 2 +- .../isregexsupported/index.md | 2 +- .../setextensionactionoptions/index.md | 2 +- .../testmatchoutcome/index.md | 2 +- .../updatedynamicrules/index.md | 2 +- .../updateenabledrulesets/index.md | 2 +- .../updatesessionrules/index.md | 2 +- 12 files changed, 11 insertions(+), 71 deletions(-) delete mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/domaintype/index.md diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/domaintype/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/domaintype/index.md deleted file mode 100644 index dbc5fed05e338e5..000000000000000 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/domaintype/index.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: declarativeNetRequest.DomainType -slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/DomainType -tags: - - API - - Add-ons - - Extensions - - Reference - - WebExtensions - - Type - - declarativeNetRequest - - DomainType -browser-compat: webextensions.api.declarativeNetRequest.DomainType ---- - -{{AddonSidebar()}} - -Describes whether the request is first or third party to the frame it originated in. A request is a first-party request if it has the same domain (e[TLD](/docs/Glossary/TLD)+1) as the frame that the request originated in. - -## Type - -Values of this type are strings. Possible values are `"firstParty"` and `"thirdParty"`. - -## Browser compatibility - -{{Compat}} - -> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#type-DomainType) API. -> -> Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License. - - 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 index 31bb3005de0c31e..e812a02a739d619 100644 --- 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 @@ -7,7 +7,7 @@ tags: - Extensions - Reference - WebExtensions - - Function + - Method - declarativeNetRequest - getAvailableStaticRuleCount browser-compat: webextensions.api.declarativeNetRequest.getAvailableStaticRuleCount 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 index 2c8639fe85810ec..2325472e63e3978 100644 --- 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 @@ -7,7 +7,7 @@ tags: - Extensions - Reference - WebExtensions - - Function + - Method - declarativeNetRequest - getDynamicRules browser-compat: webextensions.api.declarativeNetRequest.getDynamicRules 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 index 1cf0036514cf13f..00b4f916c797fe3 100644 --- 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 @@ -7,7 +7,7 @@ tags: - Extensions - Reference - WebExtensions - - Function + - Method - declarativeNetRequest - getEnabledRulesets browser-compat: webextensions.api.declarativeNetRequest.getEnabledRulesets 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 index 47d205e87766b00..ebc27d72fdcab37 100644 --- 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 @@ -7,7 +7,7 @@ tags: - Extensions - Reference - WebExtensions - - Function + - Method - declarativeNetRequest - getMatchedRules browser-compat: webextensions.api.declarativeNetRequest.getMatchedRules 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 index 0b2f0ada4668977..edd5862b7ac1781 100644 --- 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 @@ -7,7 +7,7 @@ tags: - Extensions - Reference - WebExtensions - - Function + - Method - declarativeNetRequest - getSessionRules browser-compat: webextensions.api.declarativeNetRequest.getSessionRules 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 index 25a69d996adabb1..92e603f8f2c3b85 100644 --- 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 @@ -7,7 +7,7 @@ tags: - Extensions - Reference - WebExtensions - - Function + - Method - declarativeNetRequest - isRegexSupported browser-compat: webextensions.api.declarativeNetRequest.isRegexSupported 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 index a33e60f4941a10d..a3435d2df544f8d 100644 --- 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 @@ -7,7 +7,7 @@ tags: - Extensions - Reference - WebExtensions - - Function + - Method - declarativeNetRequest - setExtensionActionOptions browser-compat: webextensions.api.declarativeNetRequest.setExtensionActionOptions 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 index 96046b1e3d88667..d83c8b0b603433d 100644 --- 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 @@ -7,7 +7,7 @@ tags: - Extensions - Reference - WebExtensions - - Function + - Method - declarativeNetRequest - testMatchOutcome browser-compat: webextensions.api.declarativeNetRequest.testMatchOutcome 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 index a65a5a288f25ab5..8ab724a64d566ed 100644 --- 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 @@ -7,7 +7,7 @@ tags: - Extensions - Reference - WebExtensions - - Function + - Method - declarativeNetRequest - updateDynamicRules browser-compat: webextensions.api.declarativeNetRequest.updateDynamicRules 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 index 610c58aa8d22136..8bb161a6d5a15c7 100644 --- 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 @@ -7,7 +7,7 @@ tags: - Extensions - Reference - WebExtensions - - Function + - Method - declarativeNetRequest - updateEnabledRulesets browser-compat: webextensions.api.declarativeNetRequest.updateEnabledRulesets 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 index b9f354e7e07af0c..303b874b9b6ea11 100644 --- 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 @@ -7,7 +7,7 @@ tags: - Extensions - Reference - WebExtensions - - Function + - Method - declarativeNetRequest - updateSessionRules browser-compat: webextensions.api.declarativeNetRequest.updateSessionRules From ac598a6d940f977a782edb059a72632a89481fcb Mon Sep 17 00:00:00 2001 From: rebloor Date: Fri, 9 Dec 2022 14:16:44 +1300 Subject: [PATCH 07/36] Suggestions from review Co-authored-by: Rob Wu --- .../declarativeNetRequest/getavailablestaticrulecount/index.md | 2 +- .../api/declarativeNetRequest/getenabledrulesets/index.md | 2 +- .../api/declarativeNetRequest/getsessionrules/index.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) 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 index e812a02a739d619..c08f2e70a7e59da 100644 --- 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 @@ -22,7 +22,7 @@ Returns the number of static rules that can be activated before the global stati ## Syntax ```js-nolint -let count = browser.declarativeNetRequest.getAvailableStaticRuleCount(); +let count = await browser.declarativeNetRequest.getAvailableStaticRuleCount(); ``` ### Parameters 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 index 00b4f916c797fe3..a052a6c04aac94a 100644 --- 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 @@ -22,7 +22,7 @@ Returns the IDs for the set of activated static rulesets. ## Syntax ```js-nolint -let rulesetIds = browser.declarativeNetRequest.getEnabledRulesets(); +let rulesetIds = await browser.declarativeNetRequest.getEnabledRulesets(); ``` ### Parameters 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 index edd5862b7ac1781..d4f6a845d35ede7 100644 --- 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 @@ -22,7 +22,7 @@ Returns the active set of session scoped rules for the extension. ## Syntax ```js-nolint -let sessionScopedRules = browser.declarativeNetRequest.getSessionRules(); +let sessionRules = await browser.declarativeNetRequest.getSessionRules(); ``` ### Parameters From 1b0d9332e50a810021e811d084ae1e003d2f7d83 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Fri, 9 Dec 2022 15:05:44 +1300 Subject: [PATCH 08/36] Removed references to MV3 and source boilerplate note --- .../api/declarativeNetRequest/dynamic_ruleset_id/index.md | 2 -- .../getavailablestaticrulecount/index.md | 6 ------ .../api/declarativeNetRequest/getdynamicrules/index.md | 6 ------ .../api/declarativeNetRequest/getenabledrulesets/index.md | 6 ------ .../api/declarativeNetRequest/getmatchedrules/index.md | 6 ------ .../getmatchedrules_quota_interval/index.md | 2 -- .../api/declarativeNetRequest/getsessionrules/index.md | 6 ------ .../guaranteed_minimum_static_rules/index.md | 2 -- .../webextensions/api/declarativeNetRequest/index.md | 6 ------ .../api/declarativeNetRequest/isregexsupported/index.md | 6 ------ .../declarativeNetRequest/isregexsupportedresult/index.md | 4 ---- .../api/declarativeNetRequest/matchedrule/index.md | 4 ---- .../max_getmatchedrules_calls_per_interval/index.md | 2 -- .../max_number_of_dynamic_and_session_rules/index.md | 2 -- .../max_number_of_enabled_static_rulesets/index.md | 2 -- .../max_number_of_regex_rules/index.md | 2 -- .../max_number_of_static_rulesets/index.md | 2 -- .../api/declarativeNetRequest/modifyheaderinfo/index.md | 4 ---- .../api/declarativeNetRequest/onrulematcheddebug/index.md | 6 ------ .../api/declarativeNetRequest/redirect/index.md | 4 ---- .../api/declarativeNetRequest/requestmethod/index.md | 4 ---- .../api/declarativeNetRequest/resourcetype/index.md | 4 ---- .../webextensions/api/declarativeNetRequest/rule/index.md | 4 ---- .../api/declarativeNetRequest/ruleaction/index.md | 4 ---- .../api/declarativeNetRequest/rulecondition/index.md | 4 ---- .../api/declarativeNetRequest/ruleset/index.md | 4 ---- .../api/declarativeNetRequest/session_ruleset_id/index.md | 2 -- .../setextensionactionoptions/index.md | 6 ------ .../api/declarativeNetRequest/testmatchoutcome/index.md | 6 ------ .../api/declarativeNetRequest/updatedynamicrules/index.md | 6 ------ .../declarativeNetRequest/updateenabledrulesets/index.md | 6 ------ .../api/declarativeNetRequest/updateruleoptions/index.md | 4 ---- .../api/declarativeNetRequest/updatesessionrules/index.md | 6 ------ .../api/declarativeNetRequest/urltransform/index.md | 4 ---- .../manifest.json/declarative_net_request/index.md | 2 +- .../mozilla/add-ons/webextensions/manifest.json/index.md | 2 +- .../webextensions/manifest.json/permissions/index.md | 6 +++--- 37 files changed, 5 insertions(+), 149 deletions(-) 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 index 81f099be3f92b3c..5e7fbd143853646 100644 --- 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 @@ -26,8 +26,6 @@ Its value is `"_dynamic"`. {{Compat}} -> **Note:** This API is based on Chromium's [`chrome.declarativeNetRequest`](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#property-DYNAMIC_RULESET_ID) API. - 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 index 0171dbb67519c8a..ad0d4dc72346a1f 100644 --- 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 @@ -39,7 +39,7 @@ Values of this type are objects. They contain these properties: - The entries must consist of only ASCII characters. - Use [punycode](https://en.wikipedia.org/wiki/Punycode) encoding for internationalized domains. - `excludedRequestMethods` {{optional_inline}} - - : An array of {{WebExtAPIRef("declarativeNetRequest.RequestMethod")}}. 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. + - : 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. - `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. - `excludedTabIds` {{optional_inline}} @@ -62,7 +62,7 @@ Values of this type are objects. They contain these properties: - The entries must consist of only ASCII characters. - Use [punycode](https://en.wikipedia.org/wiki/Punycode) encoding for internationalized domains. - `requestMethods` {{optional_inline}} - - : An array of {{WebExtAPIRef("declarativeNetRequest.RequestMethod")}}. 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. + - : 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. - `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. - `tabIds` {{optional_inline}} 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 index cffd073ccdbdbb7..c09b9f949fb953d 100644 --- 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 @@ -33,7 +33,7 @@ let count = browser.declarativeNetRequest.testMatchOutcome( - `initiator` {{optional_inline}} - : A `string`. The initiator URL (if any) for the hypothetical request. - `method` {{optional_inline}} - - : {{WebExtAPIRef("declarativeNetRequest.RequestMethod")}}. Standard HTTP method of the hypothetical request. Defaults to `"get"` for HTTP requests and is ignored for non-HTTP requests. + - : {A `string`. The ttandard 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` From d0a72a4a61d08a69c8a12eddc7478d4d90abefeb Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Fri, 9 Dec 2022 16:32:46 +1300 Subject: [PATCH 11/36] UpdateRuleOptions moved to updateDynamicRules and updateSessionRules --- .../api/declarativeNetRequest/index.md | 2 - .../updatedynamicrules/index.md | 7 ++- .../updateruleoptions/index.md | 61 ------------------- .../updatesessionrules/index.md | 7 ++- 4 files changed, 12 insertions(+), 65 deletions(-) delete mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updateruleoptions/index.md 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 index 0537774655f4ad9..5ae21fb5ad6f8be 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/index.md @@ -320,8 +320,6 @@ To illustrate how this rule set affects requests, consider: - : An object defining the condition under which a rule is triggered. - {{WebExtAPIRef("declarativeNetRequest.Ruleset")}} - : An object containing details of a static ruleset. -- {{WebExtAPIRef("declarativeNetRequest.UpdateRuleOptions")}} - - : An object containing lists of rules to add or delete. - {{WebExtAPIRef("declarativeNetRequest.URLTransform")}} - : An object containing details of a URL transformation to perform. 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 index d60bdcf367758e4..2ce254f8d303c86 100644 --- 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 @@ -33,7 +33,12 @@ let updatedRules = browser.declarativeNetRequest.updateDynamicRules( ### Parameters - `options` - - : {{WebExtAPIRef("declarativeNetRequest.UpdateRuleOptions")}}. Details of the rules to add or delete from the dynamic rules. + + - : 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 diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updateruleoptions/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updateruleoptions/index.md deleted file mode 100644 index 5909e8bff8403c0..000000000000000 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updateruleoptions/index.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: declarativeNetRequest.UpdateRuleOptions -slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/UpdateRuleOptions -tags: - - API - - Add-ons - - Extensions - - Reference - - WebExtensions - - Type - - declarativeNetRequest - - UpdateRuleOptions -browser-compat: webextensions.api.declarativeNetRequest.UpdateRuleOptions ---- - -{{AddonSidebar()}} - -Details of the rules to add or delete from session or dynamic rules. - -## Type - -Values of this type are objects. They contain these properties: - -- `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. - -## 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 index cacb813944de4cf..500f36d2d0e0b2f 100644 --- 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 @@ -32,7 +32,12 @@ let updatedRuleset = browser.declarativeNetRequest.updateSessionRules( ### Parameters - `options` - - : {{WebExtAPIRef("declarativeNetRequest.UpdateRuleOptions")}}. Details of the rules to add or delete from the session rules. + + - : 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 From 75928fc64b0e40b0e05665732055160790eecaf7 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Sat, 10 Dec 2022 04:56:07 +1300 Subject: [PATCH 12/36] correct folder name --- .../dynamic_ruleset_id/index.md | 0 .../getavailablestaticrulecount/index.md | 0 .../getdynamicrules/index.md | 0 .../getenabledrulesets/index.md | 0 .../getmatchedrules/index.md | 0 .../getmatchedrules_quota_interval/index.md | 0 .../getsessionrules/index.md | 0 .../guaranteed_minimum_static_rules/index.md | 0 .../api/{declarativeNetRequest => declarativenetrequest}/index.md | 0 .../isregexsupported/index.md | 0 .../isregexsupportedresult/index.md | 0 .../matchedrule/index.md | 0 .../max_getmatchedrules_calls_per_interval/index.md | 0 .../max_number_of_dynamic_and_session_rules/index.md | 0 .../max_number_of_enabled_static_rulesets/index.md | 0 .../max_number_of_regex_rules/index.md | 0 .../max_number_of_static_rulesets/index.md | 0 .../modifyheaderinfo/index.md | 0 .../onrulematcheddebug/index.md | 0 .../redirect/index.md | 0 .../resourcetype/index.md | 0 .../rule/index.md | 0 .../ruleaction/index.md | 0 .../rulecondition/index.md | 0 .../ruleset/index.md | 0 .../session_ruleset_id/index.md | 0 .../setextensionactionoptions/index.md | 0 .../testmatchoutcome/index.md | 0 .../updatedynamicrules/index.md | 0 .../updateenabledrulesets/index.md | 0 .../updatesessionrules/index.md | 0 .../urltransform/index.md | 0 32 files changed, 0 insertions(+), 0 deletions(-) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/dynamic_ruleset_id/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/getavailablestaticrulecount/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/getdynamicrules/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/getenabledrulesets/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/getmatchedrules/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/getmatchedrules_quota_interval/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/getsessionrules/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/guaranteed_minimum_static_rules/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/isregexsupported/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/isregexsupportedresult/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/matchedrule/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/max_getmatchedrules_calls_per_interval/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/max_number_of_dynamic_and_session_rules/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/max_number_of_enabled_static_rulesets/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/max_number_of_regex_rules/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/max_number_of_static_rulesets/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/modifyheaderinfo/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/onrulematcheddebug/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/redirect/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/resourcetype/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/rule/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/ruleaction/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/rulecondition/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/ruleset/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/session_ruleset_id/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/setextensionactionoptions/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/testmatchoutcome/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/updatedynamicrules/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/updateenabledrulesets/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/updatesessionrules/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/api/{declarativeNetRequest => declarativenetrequest}/urltransform/index.md (100%) 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/dynamic_ruleset_id/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/dynamic_ruleset_id/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/getavailablestaticrulecount/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getavailablestaticrulecount/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/getdynamicrules/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getdynamicrules/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/getenabledrulesets/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getenabledrulesets/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/getmatchedrules/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getmatchedrules/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/getmatchedrules_quota_interval/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getmatchedrules_quota_interval/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/getsessionrules/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getsessionrules/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/guaranteed_minimum_static_rules/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/guaranteed_minimum_static_rules/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/isregexsupported/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/isregexsupported/index.md diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/isregexsupportedresult/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/isregexsupportedresult/index.md similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/isregexsupportedresult/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/isregexsupportedresult/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/matchedrule/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/matchedrule/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/max_getmatchedrules_calls_per_interval/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/max_getmatchedrules_calls_per_interval/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/max_number_of_dynamic_and_session_rules/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/max_number_of_dynamic_and_session_rules/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/max_number_of_enabled_static_rulesets/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/max_number_of_enabled_static_rulesets/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/max_number_of_regex_rules/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/max_number_of_regex_rules/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/max_number_of_static_rulesets/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/max_number_of_static_rulesets/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/modifyheaderinfo/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/modifyheaderinfo/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/onrulematcheddebug/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/onrulematcheddebug/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/redirect/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/redirect/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/resourcetype/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/resourcetype/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/rule/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/rule/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/ruleaction/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/ruleaction/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/rulecondition/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/rulecondition/index.md diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/ruleset/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/ruleset/index.md similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/ruleset/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/ruleset/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/session_ruleset_id/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/session_ruleset_id/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/setextensionactionoptions/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/setextensionactionoptions/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/testmatchoutcome/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/testmatchoutcome/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updatedynamicrules/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/updatedynamicrules/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updateenabledrulesets/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/updateenabledrulesets/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/updatesessionrules/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/updatesessionrules/index.md 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 similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/urltransform/index.md rename to files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/urltransform/index.md From 61d5928d8a7d91c452f1bedf25ce99aa9065c576 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Tue, 13 Dec 2022 12:16:14 +1300 Subject: [PATCH 13/36] testing + rule scope clarifications --- .../webextensions/api/declarativenetrequest/index.md | 12 +++++++++--- .../onrulematcheddebug/index.md | 2 +- .../declarativenetrequest/testmatchoutcome/index.md | 4 ++-- .../updatesessionrules/index.md | 2 +- 4 files changed, 13 insertions(+), 7 deletions(-) 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 index 5ae21fb5ad6f8be..d121e61d39e2cf8 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md @@ -91,10 +91,10 @@ 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; they are backed in memory by the browser. +- **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 for [temporarily loaded extensions](https://extensionworkshop.com/documentation/develop/temporary-installation-in-firefox/). Invalid static rules in permanently installed extensions are ignored. Therefore, it's important to verify that your static rulesets are valid by testing with a temporarily loaded version of your extension. +> 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 @@ -135,6 +135,12 @@ If multiple `modifyHeaders` rules specify the same header, the resulting modific - If a rule has set a header, lower priority rules cannot further modify the header, except for `append` rules from the same extension. - If a rule has removed a header, lower priority rules cannot further modify the header. +## Testing + +{{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. + ## 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. @@ -372,7 +378,7 @@ To illustrate how this rule set affects requests, consider: ## Events - {{WebExtAPIRef("declarativeNetRequest.onRuleMatchedDebug")}} - - : Fired when a rule is matched with a request when debugging a temporarily installed extension with the "declarativeNetRequestFeedback" permission. + - : Fired when a rule is matched with a request when debugging an extension with the "declarativeNetRequestFeedback" permission. {{WebExtExamples("h2")}} 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 index e2600f75c9427ac..dbdb5a4d12fab32 100644 --- 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 @@ -15,7 +15,7 @@ browser-compat: webextensions.api.declarativeNetRequest.onRuleMatchedDebug {{AddonSidebar()}} -Fired when a rule is matched with a request. Only available for [temporarily loaded extensions](https://extensionworkshop.com/documentation/develop/temporary-installation-in-firefox/) with the `"declarativeNetRequestFeedback"` permission, as this is intended for debugging purposes only. +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 [Browser compatibility](#browser-compatibility) for details on how testing is enabled in each browser. ## Syntax 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 index c09b9f949fb953d..94d0332165a6694 100644 --- 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 @@ -15,7 +15,7 @@ browser-compat: webextensions.api.declarativeNetRequest.testMatchOutcome {{AddonSidebar()}} -Checks if any of the extension's `declarativeNetRequest` rules would match a hypothetical request. Only available for [temporarily loaded extensions](https://extensionworkshop.com/documentation/develop/temporary-installation-in-firefox/), as this is intended to be used during extension development. +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 [Browser compatibility](#browser-compatibility) for details on how testing is enabled in each browser. ## Syntax @@ -33,7 +33,7 @@ let count = browser.declarativeNetRequest.testMatchOutcome( - `initiator` {{optional_inline}} - : A `string`. The initiator URL (if any) for the hypothetical request. - `method` {{optional_inline}} - - : {A `string`. The ttandard HTTP method of the hypothetical request. Defaults to `"get"` for HTTP requests and is ignored for non-HTTP requests. + - : A `string`. The standard 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` 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 index 500f36d2d0e0b2f..d3b7918f972af4a 100644 --- 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 @@ -18,7 +18,7 @@ browser-compat: webextensions.api.declarativeNetRequest.updateSessionRules 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 and are backed in memory. +- 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 From 4ea4944209d2f8867652991ebb3ed232e1cf917c Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Fri, 16 Dec 2022 11:24:28 +1300 Subject: [PATCH 14/36] nested type to additional object --- .../setextensionactionoptions/index.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) 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 index ff623ff7d58e76a..9a79734693ce900 100644 --- 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 @@ -31,12 +31,16 @@ let count = browser.declarativeNetRequest.setExtensionActionOptions(); - `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. - - : An object containing aetails of how the tab's action count should be adjusted. - - `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. +## 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 From c9fec37c6c14f4f0dc511b702d30c0870b081903 Mon Sep 17 00:00:00 2001 From: rebloor Date: Thu, 26 Jan 2023 12:04:23 +1300 Subject: [PATCH 15/36] Suggestions from review Co-authored-by: Rob Wu --- .../api/declarativenetrequest/index.md | 172 +----------------- .../matchedrule/index.md | 3 +- .../max_number_of_regex_rules/index.md | 2 +- .../modifyheaderinfo/index.md | 8 +- .../api/declarativenetrequest/rule/index.md | 4 +- .../declarativenetrequest/ruleaction/index.md | 2 +- .../rulecondition/index.md | 9 +- .../testmatchoutcome/index.md | 13 +- .../updateenabledrulesets/index.md | 2 +- .../urltransform/index.md | 10 +- 10 files changed, 37 insertions(+), 188 deletions(-) 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 index d121e61d39e2cf8..a1646e693cc3f18 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md @@ -22,7 +22,7 @@ To use this API, an extension must request the `"declarativeNetRequest"` or `"de 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. +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 @@ -137,183 +137,27 @@ If multiple `modifyHeaders` rules specify the same header, the resulting modific ## Testing -{{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: + +{{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. ## 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, resulting in less memory consumption. +- 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. -- Unlike the webRequest API, any images or iframes blocked using the declarativeNetRequest API are automatically collapsed in the DOM. +- (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. -## Example - -### manifest.json - -```json -{ - "name": "declarativeNetRequest extension", - "version": "1", - "declarative_net_request": { - "rule_resources": [{ - "id": "ruleset_1", - "enabled": true, - "path": "rules.json" - }] - }, - "permissions": [ - "*://*.google.com/*", - "*://*.abcd.com/*", - "*://*.example.com/*", - "https://*.xyz.com/*", - "*://*.headers.com/*", - "declarativeNetRequest" - ], - "manifest_version": 2 -} -``` - -### rules.json - -```json -[ - { - "id": 1, - "priority": 1, - "action": { "type": "block" }, - "condition": {"urlFilter": "google.com", "resourceTypes": ["main_frame"] } - }, - { - "id": 2, - "priority": 1, - "action": { "type": "allow" }, - "condition": { "urlFilter": "google.com/123", "resourceTypes": ["main_frame"] } - }, - { - "id": 3, - "priority": 2, - "action": { "type": "block" }, - "condition": { "urlFilter": "google.com/12345", "resourceTypes": ["main_frame"] } - }, - { - "id": 4, - "priority": 1, - "action": { "type": "redirect", "redirect": { "url": "https://example.com" } }, - "condition": { "urlFilter": "google.com", "resourceTypes": ["main_frame"] } - }, - { - "id": 5, - "priority": 1, - "action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } }, - "condition": { "urlFilter": "abcd.com", "resourceTypes": ["main_frame"] } - }, - { - "id": 6, - "priority": 1, - "action": { - "type": "redirect", - "redirect": { - "transform": { "scheme": "https", "host": "new.example.com" } - } - }, - "condition": { "urlFilter": "||example.com", "resourceTypes": ["main_frame"] } - }, - { - "id": 7, - "priority": 1, - "action": { - "type": "redirect", - "redirect": { - "regexSubstitution": "https://\\1.xyz.com/" - } - }, - "condition": { - "regexFilter": "^https://www\\.(abc|def)\\.xyz\\.com/", - "resourceTypes": [ - "main_frame" - ] - } - }, - { - "id" : 8, - "priority": 2, - "action" : { - "type" : "allowAllRequests" - }, - "condition" : { - "urlFilter" : "||b.com/path", - "resourceTypes" : ["sub_frame"] - } - }, - { - "id" : 9, - "priority": 1, - "action" : { - "type" : "block" - }, - "condition" : { - "urlFilter" : "script.js", - "resourceTypes" : ["script"] - } - }, - { - "id": 10, - "priority": 2, - "action": { - "type": "modifyHeaders", - "responseHeaders": [ - { "header": "h1", "operation": "remove" }, - { "header": "h2", "operation": "set", "value": "v2" }, - { "header": "h3", "operation": "append", "value": "v3" } - ] - }, - "condition": { "urlFilter": "headers.com/123", "resourceTypes": ["main_frame"] } - }, - { - "id": 11, - "priority": 1, - "action": { - "type": "modifyHeaders", - "responseHeaders": [ - { "header": "h1", "operation": "set", "value": "v4" }, - { "header": "h2", "operation": "append", "value": "v5" }, - { "header": "h3", "operation": "append", "value": "v6" } - ] - }, - "condition": { "urlFilter": "headers.com/12345", "resourceTypes": ["main_frame"] } - }, -] -``` - -To illustrate how this rule set affects requests, consider: - -- navigation to `"https://google.com"`. Rules with ID (1) and (4) match. The request iw blocked because blocking rules have higher priority than redirect rules when the `"priority"` is the same. -- navigation to `"https://google.com/1234"`. Rules with ID (1), (2), and (4) match. Because the request has a matching `allow` rule and no higher priority rules, the request is not blocked nor redirected and continues to `"https://google.com/1234"`. -- navigation to `"https://google.com/12345"` Rules with ID (1), (2), (3), and (4) match. The request is blocked because rule (3) has the highest priority, overriding all other matching rules. -- navigation to `"https://abcd.com"`. The rule with ID (5) matches. Since rule (5) specifies an extension path, the request is redirected to `"chrome-extension://EXTENSION_ID/a.jpg"`. -- navigation to `"http://example.com/path"`. The rule with ID (6) matches. Since rule (6) specifies a URL transform, the request is redirected to `"https://new.example.com/path"`. -- a navigation to `"https://www.abc.xyz.com/path"`. The rule with ID (7) matches. The request is redirected to `"https://abc.xyz.com/path"`. -- this request hierarchy: - - (main-frame request) - - (sub-frame request, matches the rule with ID (8)) - - (sub-frame request, matches the rule with ID (8)) - - (script request, matches the rules with IDs (8, 9) but (8) has higher priority) - - (script request, matches the rules with IDs (8, 9) but (8) has higher priority) - - (sub-frame request) - - (script request, matches the rule with ID (9)) All requests in green will be allow-listed due to rule with ID (8) and not be evaluated by the extensions' ruleset. Requests in red are blocked due to rule with ID (9). -- navigation to `"https://headers.com/12345"` with response headers `{ "h1": "initial_1", "h2": "initial_2" }`. Rules with ID (10) and (11) match. The request has its response headers modified to `{ "h2": "v2", "h2": "v5", "h3": "v3", "h3": "v6" }`. Header `h1` is removed by (10), `h2` is set by (10) then appended by (11), and `h3` is appended by (10) and (11). - ## Types - {{WebExtAPIRef("declarativeNetRequest.MatchedRule")}} - : Details of a matched rule. - {{WebExtAPIRef("declarativeNetRequest.ModifyHeaderInfo")}} - - : The request headers to modify for the request. + - : 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")}} @@ -324,10 +168,8 @@ To illustrate how this rule set affects requests, consider: - : 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.Ruleset")}} - - : An object containing details of a static ruleset. - {{WebExtAPIRef("declarativeNetRequest.URLTransform")}} - - : An object containing details of a URL transformation to perform. + - : An object containing details of a URL transformation to perform for a redirect action. ## Properties 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 index 49dc5b91f53d5e6..815610ad2243169 100644 --- 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 @@ -15,7 +15,8 @@ browser-compat: webextensions.api.declarativeNetRequest.MatchedRule {{AddonSidebar()}} -Details of the rules matching a filter. +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 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 index b19d47d17f30301..e82e842e6da8816 100644 --- 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 @@ -18,7 +18,7 @@ browser-compat: webextensions.api.declarativeNetRequest.MAX_NUMBER_OF_REGEX_RULE The maximum number of regular expression rules that an extension can add. This limit is evaluated separately for the set of dynamic rules and those specified in the rule resources file. -Its value is `1000`. +Its value is `1000` in Chrome. {{WebExtExamples}} 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 index 7887e6bca5c09ce..1a93c11118a55e0 100644 --- 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 @@ -15,7 +15,11 @@ browser-compat: webextensions.api.declarativeNetRequest.ModifyHeaderInfo {{AddonSidebar()}} -The request headers to modify for a request. +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 even across multiple rules. More than one extension may modify headers, provided that the specific header has not been modified before by another extension. + +A header may be modified only once, with one exception. The "append" operation can be executed again if the previous operation is "set" or "append". ## Type @@ -26,7 +30,7 @@ Values of this type are objects. They contain these properties: - `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. + - : A `string`. The new value for the header. Must be specified for append and set operations. Not allowed for the "remove" operation. ## Browser compatibility 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 index c8f57470ef5a380..cb9dbcbec0cccd4 100644 --- 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 @@ -15,7 +15,7 @@ browser-compat: webextensions.api.declarativeNetRequest.Rule {{AddonSidebar()}} -The details of a dynamic ruleset. +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. ## Type @@ -26,7 +26,7 @@ Values of this type are objects. They contain these properties: - `condition` - : {{WebExtAPIRef("declarativeNetRequest.RuleCondition")}}. The condition under which this rule is triggered. - `id` - - : `number`. An ID that uniquely identifies a rule. Mandatory and should be >= 1. + - : `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. 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 index 3abf4f28c9b35f5..56b32207167f8fa 100644 --- 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 @@ -28,7 +28,7 @@ Values of this type are objects. They contain these properties: - `redirect` {{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"`. + - : 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 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 index ad0d4dc72346a1f..e509c0d7e361e93 100644 --- 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 @@ -15,7 +15,7 @@ browser-compat: webextensions.api.declarativeNetRequest.RuleCondition {{AddonSidebar()}} -Details of the action to take if a rule is matched. +Details of the condition that determines whether a rule matches a request. ## Type @@ -51,9 +51,10 @@ Values of this type are objects. They contain these properties: - Use [punycode](https://en.wikipedia.org/wiki/Punycode) encoding for internationalized domains. - 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. + - : 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. This follows the RE2 syntax. Note that: + - : 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}} @@ -72,7 +73,7 @@ Values of this type are objects. They contain these properties: - '*' : 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 %. This also matchet the end 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. 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 index 94d0332165a6694..75be51a4c19cce9 100644 --- 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 @@ -20,20 +20,21 @@ Checks if any of the extension's `declarativeNetRequest` rules would match a hyp ## Syntax ```js-nolint -let count = browser.declarativeNetRequest.testMatchOutcome( - rules // array +let result = await browser.declarativeNetRequest.testMatchOutcome( + request, // object + options // optional object ); ``` ### Parameters -- `testMatchRequestDetails` +- `request` - - : An object containing the match rules to test. + - : 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 HTTP method of the hypothetical request. Defaults to `"get"` for HTTP requests and is ignored for non-HTTP requests. + - : 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` @@ -48,7 +49,7 @@ A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that - `matchedRules` - : {{WebExtAPIRef("declarativeNetRequest.MatchedRule")}}. Details of the rules (if any) that match the hypothetical request. -If no rules match, the object is empty. If the request fails, the promise is rejected with an error message. +If no rules match, the `matchedRules` array is empty. If the request fails, the promise is rejected with an error message. ## Examples 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 index 40225867f34a3be..ea077a1bea208ba 100644 --- 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 @@ -15,7 +15,7 @@ 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 `rule_resources` manifest key determines the set of enabled static rulesets on each extension update. +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 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 index bfbb59a93201033..346921d99d09a83 100644 --- 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 @@ -15,7 +15,7 @@ browser-compat: webextensions.api.declarativeNetRequest.URLTransform {{AddonSidebar()}} -Details describing a URL transformation to perform. +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 @@ -35,22 +35,22 @@ Values of this type are objects. They contain these properties: - : 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. + - : 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` {{optional_inline}} + - `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` {{optional_inline}} + - `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"`, `"ftp"` and `"chrome-extension"`. + - : 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. From 1ad44acd2d6f92a705a118df74bd73e739e9b5eb Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Thu, 26 Jan 2023 14:58:15 +1300 Subject: [PATCH 16/36] Deleted redundant files --- .../isregexsupportedresult/index.md | 61 ------------------ .../declarativenetrequest/ruleset/index.md | 63 ------------------- 2 files changed, 124 deletions(-) delete mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/isregexsupportedresult/index.md delete mode 100644 files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/ruleset/index.md diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/isregexsupportedresult/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/isregexsupportedresult/index.md deleted file mode 100644 index 92902ddd58864bb..000000000000000 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/isregexsupportedresult/index.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: declarativeNetRequest.IsRegexSupportedResult -slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/IsRegexSupportedResult -tags: - - API - - Add-ons - - Extensions - - Reference - - WebExtensions - - Type - - declarativeNetRequest - - IsRegexSupportedResult -browser-compat: webextensions.api.declarativeNetRequest.IsRegexSupportedResult ---- - -{{AddonSidebar()}} - -This describes the possible operations for a "modifyHeaders" rule. - -## Type - -Values of this type are objects. They contain 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. - -## Browser compatibility - -{{Compat}} - - diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/ruleset/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/ruleset/index.md deleted file mode 100644 index 60d0166445ff922..000000000000000 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/ruleset/index.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: declarativeNetRequest.Ruleset -slug: Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/Ruleset -tags: - - API - - Add-ons - - Extensions - - Reference - - WebExtensions - - Type - - declarativeNetRequest - - Ruleset -browser-compat: webextensions.api.declarativeNetRequest.Ruleset ---- - -{{AddonSidebar()}} - -Details of a static ruleset. - -## Type - -Values of this type are objects. They contain these properties: - -- `enabled` - - : `boolean`. Whether the ruleset is enabled by default. -- `id` - - : `string`. A non-empty string that uniquely identifies the ruleset. IDs beginning with '_' are reserved for internal use. -- `path` - - : `string`. The path of the JSON ruleset relative to the extension directory. - -## Browser compatibility - -{{Compat}} - - From e20426f8cd4ea787a23fc29b7ffec1e7fb8bf1de Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Thu, 26 Jan 2023 16:00:59 +1300 Subject: [PATCH 17/36] Tweaks to rules content --- .../add-ons/webextensions/api/declarativenetrequest/index.md | 3 +-- .../webextensions/api/declarativenetrequest/rule/index.md | 4 +++- 2 files changed, 4 insertions(+), 3 deletions(-) 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 index a1646e693cc3f18..f045e966439e1b0 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md @@ -29,7 +29,7 @@ The `"declarativeNetRequestFeedback"` permission is required to use {{WebExtAPIR The declarative rules are defined by four fields: - `id` – An ID that uniquely identifies a rule. 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. +- `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 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. @@ -137,7 +137,6 @@ If multiple `modifyHeaders` rules specify the same header, the resulting modific ## 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. 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 index cb9dbcbec0cccd4..74cba0ed46d03be 100644 --- 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 @@ -17,6 +17,8 @@ browser-compat: webextensions.api.declarativeNetRequest.Rule 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: @@ -28,7 +30,7 @@ Values of this type are objects. They contain these properties: - `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. + - : `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 From c18b1e8a34e88f95c39c16fdd36cf986a87c648e Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Sat, 28 Jan 2023 06:43:18 +1300 Subject: [PATCH 18/36] Added extensionId to MatchedRule --- .../api/declarativenetrequest/matchedrule/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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 index 815610ad2243169..9b3f0a0aaea8bd2 100644 --- 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 @@ -17,11 +17,12 @@ browser-compat: webextensions.api.declarativeNetRequest.MatchedRule 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` From 2966fcf4006f7439435ca9add7f5259a19048601 Mon Sep 17 00:00:00 2001 From: rebloor Date: Mon, 30 Jan 2023 21:25:24 +1300 Subject: [PATCH 19/36] Suggestions from review Co-authored-by: Rob Wu --- .../api/declarativenetrequest/urltransform/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 346921d99d09a83..3a58c99a5b7ebe2 100644 --- 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 @@ -24,7 +24,7 @@ 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 for the request. + - : A `string`. The new host name for the request. - `password` {{optional_inline}} - : A `string`. The new password for the request. - `path` {{optional_inline}} From d91086dc4963a2a577e1621da0a0fba61b3ec70a Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Mon, 30 Jan 2023 21:59:32 +1300 Subject: [PATCH 20/36] Added `options` & `includeOtherExtensions` to `testMatchOutcome` --- .../api/declarativenetrequest/testmatchoutcome/index.md | 6 ++++++ 1 file changed, 6 insertions(+) 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 index 75be51a4c19cce9..ad5e31c36fc141a 100644 --- 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 @@ -42,6 +42,12 @@ let result = await browser.declarativeNetRequest.testMatchOutcome( - `url` - : A `string`. The URL of the hypothetical request. +- `options` + + - : 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: From 2133a450b0db77f1fa1b98b34882d13254b6ed9f Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Wed, 1 Feb 2023 14:08:36 +1300 Subject: [PATCH 21/36] Fix markdown issues --- .../webextensions/api/declarativenetrequest/ruleaction/index.md | 2 +- .../api/declarativenetrequest/rulecondition/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) 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 index 56b32207167f8fa..84ca218773dff87 100644 --- 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 @@ -28,7 +28,7 @@ Values of this type are objects. They contain these properties: - `redirect` {{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. + - : 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 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 index e509c0d7e361e93..d4f06536468e880 100644 --- 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 @@ -54,7 +54,7 @@ Values of this type are objects. They contain these properties: - : 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. + - 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}} From aac62de646d18dee738142945c0ccf96f5015f64 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Wed, 1 Feb 2023 14:18:43 +1300 Subject: [PATCH 22/36] Enable testing details links --- .../api/declarativenetrequest/onrulematcheddebug/index.md | 2 +- .../api/declarativenetrequest/testmatchoutcome/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) 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 index dbdb5a4d12fab32..cc0d83a2b0d2559 100644 --- 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 @@ -15,7 +15,7 @@ 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 [Browser compatibility](#browser-compatibility) for details on how testing is enabled in each browser. +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 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 index ad5e31c36fc141a..ad269474fbbf5e9 100644 --- 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 @@ -15,7 +15,7 @@ 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 [Browser compatibility](#browser-compatibility) for details on how testing is enabled in each browser. +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 From 453b0605a299bc781297867b54f30c1d1f60a507 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Wed, 1 Feb 2023 14:55:53 +1300 Subject: [PATCH 23/36] RuleCondition feedback --- .../rulecondition/index.md | 50 +++++++++---------- 1 file changed, 24 insertions(+), 26 deletions(-) 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 index d4f06536468e880..996f3e4f0221323 100644 --- 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 @@ -27,29 +27,10 @@ Values of this type are objects. They contain these properties: - : 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. -- `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`. Note that: - - Sub-domains such as "a.example.com" are allowed. - - The entries must consist of only ASCII characters. - - Use [punycode](https://en.wikipedia.org/wiki/Punycode) encoding for internationalized domains. - - This matches against the request initiator and not the request URL. -- `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`. Note that: - - Sub-domains such as "a.example.com" are allowed. - - The entries must consist of only ASCII characters. - - Use [punycode](https://en.wikipedia.org/wiki/Punycode) encoding for internationalized domains. -- `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. -- `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. -- `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. - `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. Note that: - - Sub-domains such as "a.example.com" are allowed. - - The entries must consist of only ASCII characters. - - Use [punycode](https://en.wikipedia.org/wiki/Punycode) encoding for internationalized domains. - - This matches against the request initiator and not the request URL. + - : 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}} @@ -58,16 +39,21 @@ Values of this type are objects. They contain these properties: - 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. Note that: - - Sub-domains such as "a.example.com" are allowed. - - The entries must consist of only ASCII characters. - - Use [punycode](https://en.wikipedia.org/wiki/Punycode) encoding for internationalized domains. + - : 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. @@ -81,6 +67,18 @@ Values of this type are objects. They contain these properties: - 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}} From 75a53f347325b50627e90624490a422a31ed1fa6 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Wed, 1 Feb 2023 15:12:58 +1300 Subject: [PATCH 24/36] Added details of types to ResourceType --- .../resourcetype/index.md | 57 ++++++++++++++++++- 1 file changed, 56 insertions(+), 1 deletion(-) 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 index fa63cdd5145cde6..18d0dbfb643a4df 100644 --- 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 @@ -19,7 +19,62 @@ The resource type of a request. ## Type -Values of this type are strings. Possible values are: `"main_frame"`, `"sub_frame"`, `"stylesheet"`, `"script"`, `"image"`, `"font"`, `"object"`, `"xmlhttprequest"`, `"ping"`, `"csp_report"`, `"media"`, `"websocket"`, `"webtransport"`, `"webbundle"`, and `"other"`. +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). +- `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` + - : 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 From 15552f0454660bddb00643a4f4970e8cf5351a3d Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Thu, 2 Feb 2023 06:19:42 +1300 Subject: [PATCH 25/36] MatchedRule.rulesetId return value clarification --- .../api/declarativenetrequest/matchedrule/index.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index 9b3f0a0aaea8bd2..d16f6d5b5e77349 100644 --- 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 @@ -26,7 +26,9 @@ Values of this type are objects. They contain these properties: - `ruleId` - : A `number`. The matching rule's ID. - `rulesetId` - - : A `string`. The ID of the {{WebExtAPIRef("declarativeNetRequest.Ruleset","Ruleset")}} this rule belongs to. For a rule originating from the set of dynamic rules, the value is `"_dynamic"`. + - : 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 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 From e52fd1de4d0f2484f741f85dc972e3ecf1bd126e Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Sat, 4 Feb 2023 06:31:29 +1300 Subject: [PATCH 26/36] Removed xbl from ResourceType in webRequest & declarativeNetRequest --- .../api/declarativenetrequest/resourcetype/index.md | 2 -- .../add-ons/webextensions/api/webrequest/resourcetype/index.md | 2 -- 2 files changed, 4 deletions(-) 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 index 18d0dbfb643a4df..d6941adf27e2072 100644 --- 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 @@ -65,8 +65,6 @@ Values of this type are strings. Possible values are: - : 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). -- `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/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` From d36fb76409ae4d99f2756b386892cbf00d001e15 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Mon, 6 Feb 2023 04:40:03 +1300 Subject: [PATCH 27/36] Moved modify header precedence details --- .../webextensions/api/declarativenetrequest/index.md | 8 -------- .../declarativenetrequest/modifyheaderinfo/index.md | 12 ++++++++++-- 2 files changed, 10 insertions(+), 10 deletions(-) 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 index f045e966439e1b0..7fa7246a9b92abb 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md @@ -127,14 +127,6 @@ When an extension is queried for how to handle a request, the matching rule with 4. `upgradeScheme` 5. `redirect` -If the request is not blocked or redirected, the matching `modifyHeaders` rules are evaluated, with the most recently installed extensions getting priority. Within each extension, all `modifyHeaders` rules with a priority lower than 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 further modify the header, except for `append` rules from the same extension. -- If a rule has removed a header, lower priority rules cannot further modify the header. - ## 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: 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 index 1a93c11118a55e0..aa0d0710c759f73 100644 --- 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 @@ -17,9 +17,17 @@ browser-compat: webextensions.api.declarativeNetRequest.ModifyHeaderInfo 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 even across multiple rules. More than one extension may modify headers, provided that the specific header has not been modified before by another extension. +Each object describes one header modification. To modify multiple headers, multiple objects can be specified in these arrays, or across multiple rules. -A header may be modified only once, with one exception. The "append" operation can be executed again if the previous operation is "set" or "append". +More than one extension may include rules that request the modification of a header. When this occurs: + +- If the request is not blocked or redirected, the most recently installed extension gets priority. Within each extension, all `modifyHeaders` rules with a priority lower than 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 From 3769bbd4ca563c77873467824f001ff3bf571a9d Mon Sep 17 00:00:00 2001 From: rebloor Date: Tue, 7 Feb 2023 12:07:42 +1300 Subject: [PATCH 28/36] Apply suggestions from review Co-authored-by: Rob Wu --- .../api/declarativenetrequest/index.md | 39 ++++++++++++------- .../modifyheaderinfo/index.md | 13 +++---- .../resourcetype/index.md | 2 +- 3 files changed, 31 insertions(+), 23 deletions(-) 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 index 7fa7246a9b92abb..636819928c8623f 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md @@ -111,21 +111,30 @@ The number of dynamic and session-scoped rules an extension can add is limited t ## Matching precedents -Before a request is sent, each extension is queried for an action to take. In order of precedence, these actions are: - -1. Actions that block requests of type `block`. -2. Actions that redirect requests of type `redirect` or `upgradeScheme`. -3. Actions that allow requests of type `allow` or `allowAllRequests`. - -If more than one extension returns an action, the extension whose action has the highest precedence gets priority. If more than one extension returns an action with the same priority, the most recently installed extension gets priority. - -When an extension is queried for how to handle a request, the matching rule with the highest `priority` is returned. If more than one matching rule has the highest `priority`, the tie is broken based on the action type, in this order of precedence: - -1. `allow` -2. `allowAllRequests` -3. `block` -4. `upgradeScheme` -5. `redirect` +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 highest 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 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 index aa0d0710c759f73..2b0f7020e71e3fa 100644 --- 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 @@ -19,15 +19,14 @@ The request or response header to modify for a request, declared in the `rule.ac Each object describes one header modification. To modify multiple headers, multiple objects can be specified in these arrays, or across multiple rules. -More than one extension may include rules that request the modification of a header. When this occurs: +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 the request is not blocked or redirected, the most recently installed extension gets priority. Within each extension, all `modifyHeaders` rules with a priority lower than 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 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. +- 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 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 index d6941adf27e2072..c0cf1017806a1d8 100644 --- 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 @@ -15,7 +15,7 @@ browser-compat: webextensions.api.declarativeNetRequest.ResourceType {{AddonSidebar()}} -The resource type of a request. +The resource type of a request. Comparable to {{WebExtAPIRef('webRequest.ResourceType')}}. ## Type From 524c495265b43bd47e64510272099d598dff5254 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Tue, 7 Feb 2023 14:25:01 +1300 Subject: [PATCH 29/36] Correct list markdown --- .../api/declarativenetrequest/index.md | 22 ++++++++++--------- 1 file changed, 12 insertions(+), 10 deletions(-) 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 index 636819928c8623f..be4fd7e3148a60e 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md @@ -112,24 +112,26 @@ The number of dynamic and session-scoped rules an extension can add is limited t ## 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 highest 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. + 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: + 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" From dc0e5c55a8a3849c32f13740d68b23021a7e648f Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Wed, 8 Feb 2023 16:09:56 +1300 Subject: [PATCH 30/36] Note about ModifyHeaderInfo.operation limitations --- .../modifyheaderinfo/index.md | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) 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 index 2b0f7020e71e3fa..b45bb251cb4e60a 100644 --- 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 @@ -36,6 +36,29 @@ Values of this type are objects. They contain these properties: - : 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"`. + + 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. - `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. From b6a0f4b4eccf12d23aba2efc9dd2ba59c43a0118 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Thu, 9 Feb 2023 12:04:51 +1300 Subject: [PATCH 31/36] ModifyHeaderInfo BCD added to RuleAction --- .../api/declarativenetrequest/ruleaction/index.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index 84ca218773dff87..daa6b307e0b5a34 100644 --- 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 @@ -10,7 +10,9 @@ tags: - Type - declarativeNetRequest - RuleAction -browser-compat: webextensions.api.declarativeNetRequest.RuleAction +browser-compat: + - webextensions.api.declarativeNetRequest.RuleAction + - webextensions.api.declarativeNetRequest.ModifyHeaderInfo --- {{AddonSidebar()}} From b236295b3b9701e072247c344443007e5260ced0 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Sat, 11 Feb 2023 05:20:41 +1300 Subject: [PATCH 32/36] typo `redirect` to `responseHeaders` --- .../webextensions/api/declarativenetrequest/ruleaction/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index daa6b307e0b5a34..63b3fae79a3c319 100644 --- 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 @@ -27,7 +27,7 @@ Values of this type are objects. They contain these properties: - : {{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"`. -- `redirect` {{optional_inline}} +- `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. From a70ccae29c7a99e07ff872578515e11e1db144bc Mon Sep 17 00:00:00 2001 From: rebloor Date: Sat, 11 Feb 2023 06:35:30 +1300 Subject: [PATCH 33/36] Apply suggestions from review Co-authored-by: Rob Wu --- .../api/declarativenetrequest/index.md | 8 +-- .../matchedrule/index.md | 1 + .../index.md | 4 ++ .../index.md | 4 +- .../max_number_of_regex_rules/index.md | 9 +++- .../max_number_of_static_rulesets/index.md | 2 +- .../modifyheaderinfo/index.md | 50 +++++++++++-------- .../setextensionactionoptions/index.md | 2 +- 8 files changed, 49 insertions(+), 31 deletions(-) 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 index be4fd7e3148a60e..f92ded3ed22cfc7 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md @@ -28,14 +28,14 @@ The `"declarativeNetRequestFeedback"` permission is required to use {{WebExtAPIR The declarative rules are defined by four fields: -- `id` – An ID that uniquely identifies a rule. Mandatory and should be >= 1. +- `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 condition under which this rule is triggered. -- `action` – The action to take when the rule is matched. Rules can do one of these things: +- `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. - - prevent a request from getting blocked by negating any matching blocked rules. - 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: 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 index d16f6d5b5e77349..8e631e176fb10cd 100644 --- 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 @@ -27,6 +27,7 @@ Values of this type are objects. They contain these properties: - : 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"`. 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 index a4b4f776eb9ed15..0fc8c28d0116b12 100644 --- 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 @@ -18,6 +18,10 @@ browser-compat: webextensions.api.declarativeNetRequest.MAX_NUMBER_OF_DYNAMIC_AN 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}} 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 index 0db7055611457b4..ac6df697efd295d 100644 --- 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 @@ -16,7 +16,9 @@ browser-compat: webextensions.api.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_ST {{AddonSidebar()}} -The maximum number of static `Rulesets` an extension can have enabled. +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`. 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 index e82e842e6da8816..09aa0ee3fdaafe2 100644 --- 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 @@ -16,9 +16,14 @@ browser-compat: webextensions.api.declarativeNetRequest.MAX_NUMBER_OF_REGEX_RULE {{AddonSidebar()}} -The maximum number of regular expression rules that an extension can add. This limit is evaluated separately for the set of dynamic rules and those specified in the rule resources file. +```suggestion +The maximum number of regular expression rules that an extension can add. -Its value is `1000` in Chrome. +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}} 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 index 8406adb87120135..f5e976e10fae120 100644 --- 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 @@ -16,7 +16,7 @@ browser-compat: webextensions.api.declarativeNetRequest.MAX_NUMBER_OF_STATIC_RUL {{AddonSidebar()}} -The maximum number of static `Rulesets` an extension can specify as part of the [`"rule_resources"`](/docs/Mozilla/Add-ons/WebExtensions/manifest.json/rule_resources) manifest key. +The maximum number of static rulesets an extension can specify as part of the [`"rule_resources"`](/docs/Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request) manifest key. Its value is `50`. 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 index b45bb251cb4e60a..fb3d71f5b0659b7 100644 --- 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 @@ -37,30 +37,36 @@ Values of this type are objects. They contain these properties: - `operation` - : A `string`. The operation to be performed on a header. Possible values are `"append"`, `"set"`, and `"remove"`. - 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. - `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 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 index 9a79734693ce900..65fec7a8d9b6102 100644 --- 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 @@ -31,7 +31,7 @@ let count = browser.declarativeNetRequest.setExtensionActionOptions(); - `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. + - : `object`. Details of how the tab's action count should be adjusted. See the [tabUpdate](#tabupdate_2) section for more details. ## Additional objects From 2789805ff878d6cab1d93c2731c2bcb8ac86fb63 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Mon, 13 Feb 2023 04:51:27 +1300 Subject: [PATCH 34/36] BCD for ModifyHeaderInfo represented by RuleAction.requestHeaders & RuleAction.responseHeaders Corrected markdown issues in ModifyHeaderInfo --- .../modifyheaderinfo/index.md | 48 +++++++++---------- .../declarativenetrequest/ruleaction/index.md | 4 +- 2 files changed, 25 insertions(+), 27 deletions(-) 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 index fb3d71f5b0659b7..b2622cb202f616c 100644 --- 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 @@ -10,7 +10,9 @@ tags: - Type - declarativeNetRequest - ModifyHeaderInfo -browser-compat: webextensions.api.declarativeNetRequest.ModifyHeaderInfo +browser-compat: + - webextensions.api.declarativeNetRequest.RuleAction.requestHeaders + - webextensions.api.declarativeNetRequest.RuleAction.responseHeaders --- {{AddonSidebar()}} @@ -36,38 +38,36 @@ Values of this type are objects. They contain these properties: - : 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` +- `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/ruleaction/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/ruleaction/index.md index 63b3fae79a3c319..97155e96d6ae799 100644 --- 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 @@ -10,9 +10,7 @@ tags: - Type - declarativeNetRequest - RuleAction -browser-compat: - - webextensions.api.declarativeNetRequest.RuleAction - - webextensions.api.declarativeNetRequest.ModifyHeaderInfo +browser-compat: webextensions.api.declarativeNetRequest.RuleAction --- {{AddonSidebar()}} From 7173fd62d14623a746f1f2a6d7fb4acc1cdbddb1 Mon Sep 17 00:00:00 2001 From: rebloor Date: Mon, 13 Feb 2023 06:18:05 +1300 Subject: [PATCH 35/36] Apply suggestions from review Co-authored-by: Rob Wu --- .../webextensions/api/declarativenetrequest/index.md | 8 ++++---- .../api/declarativenetrequest/isregexsupported/index.md | 4 ++-- .../max_number_of_enabled_static_rulesets/index.md | 2 +- .../max_number_of_static_rulesets/index.md | 2 +- .../api/declarativenetrequest/onrulematcheddebug/index.md | 4 ++-- .../setextensionactionoptions/index.md | 4 +++- .../api/declarativenetrequest/testmatchoutcome/index.md | 2 +- .../api/declarativenetrequest/updatedynamicrules/index.md | 2 +- .../mozilla/add-ons/webextensions/manifest.json/index.md | 2 +- 9 files changed, 16 insertions(+), 14 deletions(-) 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 index f92ded3ed22cfc7..7fa59ef7d29704e 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md @@ -113,7 +113,7 @@ The number of dynamic and session-scoped rules an extension can add is limited t 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 highest priority (and rules default to 1 where priority is not set) +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. @@ -165,7 +165,7 @@ If the request was not blocked or redirected, the matching `modifyHeaders` actio - {{WebExtAPIRef("declarativeNetRequest.ResourceType")}} - : The resource type of a request. - {{WebExtAPIRef("declarativeNetRequest.Rule")}} - - : An object containing details of a dynamic 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")}} @@ -186,11 +186,11 @@ If the request was not blocked or redirected, the matching `modifyHeaders` actio - {{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. + - : 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 [`"rule_resources"`](/docs/Mozilla/Add-ons/WebExtensions/manifest.json/rule_resources) manifest key. + - : 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. 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 index eb4e287317a2da7..bb2b96662ca6323 100644 --- 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 @@ -21,13 +21,13 @@ Checks if a regular expression is supported as a {{WebExtAPIRef("declarativeNetR ```js-nolint let count = browser.declarativeNetRequest.isRegexSupported( - RegexOptions // object + regexOptions // object ); ``` ### Parameters -- `RegexOptions` +- `regexOptions` - : An object containing the regular expression to check. - `isCaseSensitive` {{optional_inline}} 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 index ac6df697efd295d..eb420bf64d530e3 100644 --- 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 @@ -18,7 +18,7 @@ browser-compat: webextensions.api.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_ST 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. +An extension can change the number of enabled rulesets using the {{WebExtAPIRef("declarativeNetRequest.updateEnabledRulesets", "updateEnabledRulesets")}} method. Its value is `10`. 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 index f5e976e10fae120..b78597dc3f50413 100644 --- 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 @@ -16,7 +16,7 @@ browser-compat: webextensions.api.declarativeNetRequest.MAX_NUMBER_OF_STATIC_RUL {{AddonSidebar()}} -The maximum number of static rulesets an extension can specify as part of the [`"rule_resources"`](/docs/Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request) manifest key. +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`. 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 index cc0d83a2b0d2559..b1820707189cabe 100644 --- 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 @@ -66,12 +66,12 @@ Events have three functions: - `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` - - : [`ResourceType`](/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/ResourceType). The resource type of the request. + - : {{WebExtAPIRef("declarativeNetRequest.ResourceType", "ResourceType")}}. The resource type of the request. - `url` - : A `string`. The URL of the request. - `rule` - - : [`MatchedRule`](/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/MatchedRule). Details of a matched rule. + - : {{WebExtAPIRef("declarativeNetRequest.MatchedRule", "MatchedRule")}}. Details of a matched rule. {{WebExtExamples}} 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 index 65fec7a8d9b6102..f02e4d1dc5e4028 100644 --- 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 @@ -20,7 +20,9 @@ Configures whether the action count for tabs is displayed as the extension actio ## Syntax ```js-nolint -let count = browser.declarativeNetRequest.setExtensionActionOptions(); +let count = browser.declarativeNetRequest.setExtensionActionOptions( + extensionActionOptions, // object +); ``` ### Parameters 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 index ad269474fbbf5e9..0d41d3fb188b8b7 100644 --- 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 @@ -42,7 +42,7 @@ let result = await browser.declarativeNetRequest.testMatchOutcome( - `url` - : A `string`. The URL of the hypothetical request. -- `options` +- `options` {{optional_inline}} - : Details of options for the request. - `includeOtherExtensions` {{optional_inline}} 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 index 2ce254f8d303c86..f138582bd5c715d 100644 --- 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 @@ -15,7 +15,7 @@ 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: +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. 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 926da382940f9b4..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 @@ -52,7 +52,7 @@ These are the `manifest.json` keys; these keys are available in Manifest V2 and - [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) +- [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) From 3f5d857ab013f16bb4b41f9a349d5fc39d2b3d0d Mon Sep 17 00:00:00 2001 From: rebloor Date: Mon, 13 Feb 2023 06:44:31 +1300 Subject: [PATCH 36/36] Testing required preference comment --- .../add-ons/webextensions/api/declarativenetrequest/index.md | 1 + 1 file changed, 1 insertion(+) 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 index 7fa59ef7d29704e..ac1127ae263d5c0 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md @@ -143,6 +143,7 @@ If the request was not blocked or redirected, the matching `modifyHeaders` actio {{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