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.

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

Add declarativeNetRequest #22644

Merged
merged 43 commits into from
Feb 14, 2023
Merged

Add declarativeNetRequest #22644

merged 43 commits into from
Feb 14, 2023

Conversation

rebloor
Copy link
Contributor

@rebloor rebloor commented Nov 30, 2022

Description

Adding the declarativeNetRequest API.

  • types
  • properties
  • functions and events
  • manifest keys & permissions
  • narrative
  • function code examples

@rebloor rebloor added the Content:WebExt WebExtensions docs label Nov 30, 2022
@rebloor rebloor requested review from rpl and Rob--W November 30, 2022 22:07
@rebloor rebloor self-assigned this Nov 30, 2022
@github-actions github-actions bot added the Content:Other Any docs not covered by another "Content:" label label Nov 30, 2022
Copy link
Member

@Rob--W Rob--W left a comment

Choose a reason for hiding this comment

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

Here is an initial review pass.

General notes:

  • Drop the MV3 mention; as the API is going to be available to MV2 too. In Chrome/Safari there are no MV restrictions.
  • Drop the Edge/Chromium boilerplate at the end of all articles.

Specific note: the structure of this draft seems copied from Chromium's documentation at https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/ . That structure is not great, as it is auto-generated from Chromium's implementation at https://source.chromium.org/chromium/chromium/src/+/main:extensions/common/api/declarative_net_request.idl , which includes many single-use types. Documentation would be more readable when these single-use types are merged with the method that "imports" the type definition.

@rebloor
Copy link
Contributor Author

rebloor commented Dec 8, 2022

@Rob--W "Documentation would be more readable when these single-use types are merged with the method that "imports" the type definition." As explained elsewhere, this is what I believe I've already done - can you provide more specific examples?

@rebloor rebloor requested a review from Rob--W December 9, 2022 03:37
@github-actions
Copy link
Contributor

github-actions bot commented Dec 9, 2022

Preview URLs (34 pages)
Flaws (48)

Note! 3 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request
Title: declarative_net_request
Flaw count: 1

  • bad_bcd_queries:
    • No BCD data for query: webextensions.manifest.declarative_net_request

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest
Title: declarativeNetRequest
Flaw count: 5

  • broken_links:
    • Can't resolve /docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions
    • Can't resolve /docs/Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request
    • Can't resolve /docs/Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request
    • Can't resolve /docs/Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request
  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/testMatchOutcome
Title: declarativeNetRequest.testMatchOutcome
Flaw count: 2

  • broken_links:
    • Can't resolve /docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest#testing
  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.testMatchOutcome

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/setExtensionActionOptions
Title: declarativeNetRequest.setExtensionActionOptions
Flaw count: 1

  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.setExtensionActionOptions

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/updateDynamicRules
Title: declarativeNetRequest.updateDynamicRules
Flaw count: 1

  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.updateDynamicRules

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/RuleCondition
Title: declarativeNetRequest.RuleCondition
Flaw count: 2

  • broken_links:
    • Can't resolve /docs/Web/API/URL
  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.RuleCondition

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/SESSION_RULESET_ID
Title: declarativeNetRequest.SESSION_RULESET_ID
Flaw count: 1

  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.SESSION_RULESET_ID

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/MAX_NUMBER_OF_REGEX_RULES
Title: declarativeNetRequest.MAX_NUMBER_OF_REGEX_RULES
Flaw count: 1

  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.MAX_NUMBER_OF_REGEX_RULES

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/DYNAMIC_RULESET_ID
Title: declarativeNetRequest.DYNAMIC_RULESET_ID
Flaw count: 1

  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.DYNAMIC_RULESET_ID

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/GUARANTEED_MINIMUM_STATIC_RULES
Title: declarativeNetRequest.GUARANTEED_MINIMUM_STATIC_RULES
Flaw count: 1

  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.GUARANTEED_MINIMUM_STATIC_RULES

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/ResourceType
Title: declarativeNetRequest.ResourceType
Flaw count: 1

  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.ResourceType

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/getEnabledRulesets
Title: declarativeNetRequest.getEnabledRulesets
Flaw count: 1

  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.getEnabledRulesets

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/URLTransform
Title: declarativeNetRequest.URLTransform
Flaw count: 1

  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.URLTransform

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/onRuleMatchedDebug
Title: declarativeNetRequest.onRuleMatchedDebug
Flaw count: 2

  • broken_links:
    • Can't resolve /docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest#testing
  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.onRuleMatchedDebug

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/RuleAction
Title: declarativeNetRequest.RuleAction
Flaw count: 3

  • broken_links:
    • Can't resolve /docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions
    • Can't resolve /docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest#permissions
  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.RuleAction

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/ModifyHeaderInfo
Title: declarativeNetRequest.ModifyHeaderInfo
Flaw count: 2

  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.RuleAction.requestHeaders
    • No BCD data for query: webextensions.api.declarativeNetRequest.RuleAction.responseHeaders

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/getSessionRules
Title: declarativeNetRequest.getSessionRules
Flaw count: 1

  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.getSessionRules

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/Redirect
Title: declarativeNetRequest.Redirect
Flaw count: 1

  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.Redirect

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/MAX_NUMBER_OF_STATIC_RULESETS
Title: declarativeNetRequest.MAX_NUMBER_OF_STATIC_RULESETS
Flaw count: 2

  • broken_links:
    • Can't resolve /docs/Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request
  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.MAX_NUMBER_OF_STATIC_RULESETS

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/getAvailableStaticRuleCount
Title: declarativeNetRequest.getAvailableStaticRuleCount
Flaw count: 1

  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.getAvailableStaticRuleCount

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/GETMATCHEDRULES_QUOTA_INTERVAL
Title: declarativeNetRequest.GETMATCHEDRULES_QUOTA_INTERVAL
Flaw count: 1

  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.GETMATCHEDRULES_QUOTA_INTERVAL

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/Rule
Title: declarativeNetRequest.Rule
Flaw count: 3

  • broken_links:
    • Can't resolve /docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest#rules
    • Can't resolve /docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest#matching_precedents
  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.Rule

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES
Title: declarativeNetRequest.MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES
Flaw count: 1

  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/getDynamicRules
Title: declarativeNetRequest.getAvailableStaticRuleCount
Flaw count: 1

  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.getDynamicRules

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/MatchedRule
Title: declarativeNetRequest.MatchedRule
Flaw count: 3

  • broken_links:
    • Can't resolve /docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest#rulesets
    • Can't resolve /docs/Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request
  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.MatchedRule

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL
Title: declarativeNetRequest.MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL
Flaw count: 1

  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/updateSessionRules
Title: declarativeNetRequest.updateSessionRules
Flaw count: 1

  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.updateSessionRules

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/MAX_NUMBER_OF_ENABLED_STATIC_RULESETS
Title: declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS
Flaw count: 2

  • broken_links:
    • Can't resolve /docs/Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request
  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/isRegexSupported
Title: declarativeNetRequest.isRegexSupported
Flaw count: 1

  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.isRegexSupported

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/updateEnabledRulesets
Title: declarativeNetRequest.updateEnabledRulesets
Flaw count: 2

  • broken_links:
    • Can't resolve /docs/Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request
  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.updateEnabledRulesets

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/getMatchedRules
Title: declarativeNetRequest.getMatchedRules
Flaw count: 1

  • bad_bcd_queries:
    • No BCD data for query: webextensions.api.declarativeNetRequest.getMatchedRules
External URLs (7)

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest
Title: declarativeNetRequest


URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/RuleCondition
Title: declarativeNetRequest.RuleCondition


URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/ResourceType
Title: declarativeNetRequest.ResourceType


URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/webRequest/ResourceType
Title: webRequest.ResourceType

(comment last updated: 2023-02-12 17:46:20)

@rebloor rebloor marked this pull request as ready for review December 13, 2022 22:12
@rebloor rebloor requested a review from a team as a code owner December 13, 2022 22:12
@rebloor rebloor requested a review from Rob--W February 1, 2023 18:10
Copy link
Member

@Rob--W Rob--W left a comment

Choose a reason for hiding this comment

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

(Only replied to comments and the context around the comments, haven't done a full review yet)


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

Choose a reason for hiding this comment

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

Yes.


{{AddonSidebar()}}

The resource type of a request.
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
The resource type of a request.
The resource type of a request. Comparable to {{WebExtAPIRef('webRequest.ResourceType')}}.

The set of supported types is at https://searchfox.org/mozilla-central/rev/9dfda5ccb0fc42d7666a54b1caf1af6525e49694/toolkit/components/extensions/schemas/declarative_net_request.json#71-93 and https://source.chromium.org/chromium/chromium/src/+/main:extensions/common/api/declarative_net_request.idl;l=12-28;drc=b141211e0c65628cf86a68a37d92377186560560

I'll also suggest some deletions below of obsolete types. Please double-check that the content here and the BCD is accurate.

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 So, comparing those lists it seems that quite a number of these items are supported in Chrome:
image
How can we check what is supported in Safari?

Copy link
Member

Choose a reason for hiding this comment

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

I have asked an Apple engineer about the support state. Let's be concerned with what we know (Chrome and Firefox), and correct support information about Apple in a follow-up PR if needed.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I've updated the BCD

Copy link
Member

Choose a reason for hiding this comment

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

I got an answer back from @xeenon . Safari's list of supported ResourceTypes is:

"font"
"image"
"main_frame"
"media"
"other"
"ping"
"script"
"stylesheet"
"sub_frame"
"websocket"
"xmlhttprequest"


{{AddonSidebar()}}

The resource type of a request.
Copy link
Member

Choose a reason for hiding this comment

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

I have asked an Apple engineer about the support state. Let's be concerned with what we know (Chrome and Firefox), and correct support information about Apple in a follow-up PR if needed.

Copy link
Member

@Rob--W Rob--W left a comment

Choose a reason for hiding this comment

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

I did another full pass over the content and it generally looks good.

I added several suggested edits, to add content, improve the accuracy, fix broken links, minor formatting improvements. Feel free to edit my suggested edit before committing the changes as you see fit.


{{AddonSidebar()}}

The resource type of a request.
Copy link
Member

Choose a reason for hiding this comment

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

I got an answer back from @xeenon . Safari's list of supported ResourceTypes is:

"font"
"image"
"main_frame"
"media"
"other"
"ping"
"script"
"stylesheet"
"sub_frame"
"websocket"
"xmlhttprequest"

Comment on lines 28 to 31
- `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"`.
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
- `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"`.
- `requestHeaders` {{optional_inline}}
- : {{WebExtAPIRef("declarativeNetRequest.ModifyHeaderInfo")}}. The request headers to modify for the request. Only valid if the action `type` is `"modifyHeaders"`.
- `redirect` {{optional_inline}}
- : {{WebExtAPIRef("declarativeNetRequest.ModifyHeaderInfo")}}. The response headers to modify for the request. Only valid if the action `type` is `"modifyHeaders"`.

Copy link
Member

@Rob--W Rob--W left a comment

Choose a reason for hiding this comment

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

I did a final pass over every detail of the PR and added some final suggested edits. After these, the PR can be merged. Since it's a matter of just committing the suggested edits and there is not much to discuss about it, I'll approve the PR so it does not need another round of review.

Copy link
Member

@Rob--W Rob--W left a comment

Choose a reason for hiding this comment

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

Since it's a matter of just committing the suggested edits and there is not much to discuss about it, I'll approve the PR so it does not need another round of review.

Now actually marking as approved - but don't forget to commit the suggested edits!

Copy link
Member

@Rob--W Rob--W left a comment

Choose a reason for hiding this comment

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

Thanks for all your work on this Richard!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Content:Other Any docs not covered by another "Content:" label Content:WebExt WebExtensions docs
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants