Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add declarativeNetRequest #22644

Merged
merged 43 commits into from
Feb 14, 2023
Merged

Add declarativeNetRequest #22644

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
43 commits
Select commit Hold shift + click to select a range
59611bd
Add declarativeNetRequest
rebloor Nov 30, 2022
b73189a
Added properties
rebloor Dec 2, 2022
0aef595
Add functions and events
rebloor Dec 5, 2022
d5750c5
Added manifest and permissions details
rebloor Dec 6, 2022
1005f78
Added API narrative + corrections
rebloor Dec 8, 2022
fd67a1e
Function > Method, deleted unused DomainType
rebloor Dec 8, 2022
6f75ef7
Merge branch 'main' into add-declarativeNetRequest
rebloor Dec 8, 2022
ac598a6
Suggestions from review
rebloor Dec 9, 2022
1b0d933
Removed references to MV3 and source boilerplate note
rebloor Dec 9, 2022
4b60d4e
Minor feedback updates
rebloor Dec 9, 2022
a8e4706
Dropping RequestMethod
rebloor Dec 9, 2022
d0a72a4
UpdateRuleOptions moved to updateDynamicRules and updateSessionRules
rebloor Dec 9, 2022
eef29ca
Merge branch 'main' into add-declarativeNetRequest
rebloor Dec 9, 2022
75928fc
correct folder name
rebloor Dec 9, 2022
47195a4
Merge branch 'main' into add-declarativeNetRequest
rebloor Dec 12, 2022
61d5928
testing + rule scope clarifications
rebloor Dec 12, 2022
fa603c0
Merge branch 'main' into add-declarativeNetRequest
rebloor Dec 13, 2022
4ea4944
nested type to additional object
rebloor Dec 15, 2022
c9fec37
Suggestions from review
rebloor Jan 25, 2023
1ad44ac
Deleted redundant files
rebloor Jan 26, 2023
e20426f
Tweaks to rules content
rebloor Jan 26, 2023
c18b1e8
Added extensionId to MatchedRule
rebloor Jan 27, 2023
2966fcf
Suggestions from review
rebloor Jan 30, 2023
d91086d
Added `options` & `includeOtherExtensions` to `testMatchOutcome`
rebloor Jan 30, 2023
346a58f
Merge branch 'main' into add-declarativeNetRequest
rebloor Feb 1, 2023
2133a45
Fix markdown issues
rebloor Feb 1, 2023
aac62de
Enable testing details links
rebloor Feb 1, 2023
453b060
RuleCondition feedback
rebloor Feb 1, 2023
75a53f3
Added details of types to ResourceType
rebloor Feb 1, 2023
15552f0
MatchedRule.rulesetId return value clarification
rebloor Feb 1, 2023
e52fd1d
Removed xbl from ResourceType in webRequest & declarativeNetRequest
rebloor Feb 3, 2023
d36fb76
Moved modify header precedence details
rebloor Feb 5, 2023
3769bbd
Apply suggestions from review
rebloor Feb 6, 2023
415f04f
Merge branch 'main' into add-declarativeNetRequest
rebloor Feb 6, 2023
524c495
Correct list markdown
rebloor Feb 7, 2023
dc0e5c5
Note about ModifyHeaderInfo.operation limitations
rebloor Feb 8, 2023
b6a0f4b
ModifyHeaderInfo BCD added to RuleAction
rebloor Feb 8, 2023
b236295
typo `redirect` to `responseHeaders`
rebloor Feb 10, 2023
a70ccae
Apply suggestions from review
rebloor Feb 10, 2023
2789805
BCD for ModifyHeaderInfo represented by RuleAction.requestHeaders & R…
rebloor Feb 12, 2023
98c2f98
Merge branch 'main' into add-declarativeNetRequest
rebloor Feb 12, 2023
7173fd6
Apply suggestions from review
rebloor Feb 12, 2023
3f5d857
Testing required preference comment
rebloor Feb 12, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Added manifest and permissions details
  • Loading branch information
@rebloor
rebloor committed Dec 6, 2022
commit d5750c535efaaab8fead2042154f4740d9d63509
11 changes: 6 additions & 5 deletions files/en-us/mozilla/add-ons/webextensions/api/declarativeNetRequest/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
rebloor marked this conversation as resolved.
Show resolved Hide resolved

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This "declarativeNetRequestFeedback" permission and its associated APIs are unavailable by default: In Chrome, "declarativeNetRequestFeedback" is only available to unpacked extensions. In Firefox, these features are only available if the "extensions.dnr.feedback" preference is set to true in about:config.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Rob--W Should this be documented here or in the BCD? BCD I would have thought.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is too much information for BCD and would fit better here (I suppose as a specific subsection of the main permissions section). BCD usually describes experimental flags and prefs, but in this case it is not an experimental flag, but an intentionally obscure way to make an API available for debugging purposes only. The features are never going to be available without the explicit steps that enable the functionality tied to this declarativeNetRequestFeedback permission, and it it crucial information that needs to be featured prominently.

I'll include 2 suggested edits in my review feedback today to address this.


> **Note:** This API is available in Manifest V3 or higher.

## Rules
Rob--W marked this conversation as resolved.
Show resolved Hide resolved

## Types

- {{WebExtAPIRef("declarativeNetRequest.DomainType")}}
Expand Down
2 changes: 1 addition & 1 deletion ...lla/add-ons/webextensions/api/declarativeNetRequest/onrulematcheddebug/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
95 changes: 95 additions & 0 deletions ...us/mozilla/add-ons/webextensions/manifest.json/declarative_net_request/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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}}

<table class="fullwidth-table standard-table">
<tbody>
<tr>
<th scope="row">Type</th>
<td><code>Object</code></td>
</tr>
<tr>
<th scope="row">Mandatory</th>
<td>No</td>
</tr>
<tr>
<th scope="row">Manifest version</th>
<td>3</td>
</tr>
<tr>
<th scope="row">Example</th>
<td>
<pre class="brush: json">
"declarative_net_request" : {
"rule_resources" : [{
"id": "ruleset",
"enabled": true,
"path": "rules.json"
}]
}</pre
>
</td>
</tr>
</tbody>
</table>

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:

<table class="fullwidth-table standard-table">
<thead>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>"id"</code></td>
<td><code>String</code></td>
<td>A non-empty string uniquely identifying the ruleset. IDs beginning with '_' are reserved for internal use.</td>
</tr>
<tr>
<td><code>"enabled"</code></td>
<td><code>Boolean</code></td>
<td>Whether the ruleset is enabled by default.</td>
</tr>
<tr>
<td><code>"path"</code></td>
<td><code>String</code></td>
<td>The path of the JSON ruleset relative to the extension directory. See the <a href="/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest#rules">Rules</a> section of the `declarativeNetRequest` API for information on the content of the ruleset JSON file.</td>
</tr>
</tbody>
</table>

## 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}}
77 changes: 39 additions & 38 deletions files/en-us/mozilla/add-ons/webextensions/manifest.json/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
rebloor marked this conversation as resolved.
Show resolved Hide resolved
- [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

Expand Down
5 changes: 4 additions & 1 deletion files/en-us/mozilla/add-ons/webextensions/manifest.json/permissions/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand All @@ -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`
Expand Down