recursal/MDN huggingface dataset:
declarativeNetRequest.onRuleMatchedDebug
========================================

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 for details on how testing is enabled in each browser.

Syntax
------


```js
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

`listener`

The function called when this event occurs. The function is passed these arguments:

`request`

An object containing information about the request the rule matched.

`documentId` Optional

A `string`. The unique identifier for the frame's document, if this request is for a frame.

`documentLifecycle` Optional

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

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

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

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`. The resource type of the request.

`url`

A `string`. The URL of the request.


`rule`

`MatchedRule`. Details of a matched rule.


Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.GUARANTEED\_MINIMUM\_STATIC\_RULES
========================================================

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.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.testMatchOutcome
======================================

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 for details on how testing is enabled in each browser.

Syntax
------


```js
let result = await browser.declarativeNetRequest.testMatchOutcome(
    request,                // object
    options                 // optional object
);
```

### Parameters

`request`

The details of the request to test.

`initiator` Optional

A `string`. The initiator URL (if any) for the hypothetical request.

`method` Optional

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

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`

`declarativeNetRequest.ResourceType`. The resource type of the hypothetical request.

`url`

A `string`. The URL of the hypothetical request.


`options` Optional

Details of options for the request.

`includeOtherExtensions` Optional

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` that fulfills with an object with these properties:

`matchedRules`

`declarativeNetRequest.MatchedRule`. Details of the rules (if any) that match the hypothetical request.

If no rules match, the `matchedRules` array is empty. If the request fails, the promise is rejected with an error message.

Examples
--------

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.DYNAMIC\_RULESET\_ID
==========================================

Ruleset ID for the dynamic rules added by the extension using `updateDynamicRules`.

Its value is `"_dynamic"`.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.MAX\_NUMBER\_OF\_DYNAMIC\_AND\_SESSION\_RULES
===================================================================

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`.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.MAX\_NUMBER\_OF\_ENABLED\_STATIC\_RULESETS
================================================================

The maximum number of static rulesets an extension can have enabled, i.e., the number of values in the `declarative_net_request.rule_resources` 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 `updateEnabledRulesets` method.

Its value is `10`.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.MatchedRule
=================================

An object describing the matched rule. This type may be returned by the `declarativeNetRequest.getMatchedRules` or `declarativeNetRequest.testMatchOutcome` methods, or observed through the `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 `declarativeNetRequest.testMatchOutcome`, with the `includeOtherExtensions` option set to `true`.

`ruleId`

A `number`. The matching rule's ID.

`rulesetId`

A `string`. The ID of the ruleset 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.
* For a rule originating from the set of dynamic rules, the value defined in `declarativeNetRequest.DYNAMIC_RULESET_ID`, i.e., `"_dynamic"`.
* For a rule originating from the set of session rules, the value defined in `declarativeNetRequest.SESSION_RULESET_ID`, i.e., `"_session"`.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.ResourceType
==================================

The resource type of a request. Comparable to `webRequest.ResourceType`.

Type
----

Values of this type are strings. Possible values are:

`beacon`

Requests sent through the Beacon API.

`csp_report`

Requests sent to the `report-uri` given in the `Content-Security-Policy` header, when an attempt to violate the policy is detected.

`font`

Web fonts loaded for a `@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 `<picture>` element or given in an `<img>` element's `srcset` attribute.

`main_frame`

Top-level documents loaded into a tab.

`media`

Resources loaded by a `<video>` or `<audio>` element.

`object`

Resources loaded by an `<object>` or `<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 `ping` 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 `<script>` element or running in a Worker.

`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 stylesheets loaded to describe the representation of a document.

`sub_frame`

Documents loaded into an `<iframe>` or `<frame>` element.

`web_manifest`

Web App Manifests 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.

`websocket`

Requests initiating a connection to a server through the WebSocket API.

`webtransport`

Requests initiating a connection to a server through the WebTransport API.

`xml_dtd`

DTDs loaded for an XML document.

`xmlhttprequest`

Requests sent by an `XMLHttpRequest` object or through the Fetch API.

`xslt`

XSLT stylesheets loaded for transforming an XML document.

`other`

Resources that aren't covered by any other available type.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.getDynamicRules
=====================================

Returns the set of dynamic rules for the extension.

Syntax
------


```js
let gettingDynamicRules = browser.declarativeNetRequest.getDynamicRules();
```

### Parameters

This function takes no parameters.

### Return value

A `Promise` is fulfilled with an array of `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
--------

### Example extensions

* dnr-dynamic-with-options
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.setExtensionActionOptions
===============================================

Configures whether the action count for tabs is displayed as the extension action's badge text and provides a way for the action count to be incremented.

Syntax
------


```js
let count = browser.declarativeNetRequest.setExtensionActionOptions(
    extensionActionOptions, // object
);
```

### Parameters

`extensionActionOptions`

An object containing the configuration details for the action count for tabs.

`displayActionCountAsBadgeText` Optional

`boolean` Whether to automatically display the action count for a page as the extension's badge text. This preference persists across sessions.

`tabUpdate` Optional

`object`. Details of how the tab's action count should be adjusted. See the tabUpdate section for more details.


Additional objects
------------------

### tabUpdate

`increment`

`number` The amount to increment the tab's action count by. Negative values decrement the count.

`tabId`

`number` The tab to update the action count for.

### Return value

A `Promise` that fulfills with no arguments. If the request fails, the promise is rejected with an error message.

Examples
--------

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.getAvailableStaticRuleCount
=================================================

Returns the number of static rules that can be activated before the global static rule limit is reached.

Syntax
------


```js
let count = await browser.declarativeNetRequest.getAvailableStaticRuleCount();
```

### Parameters

This function takes no parameters.

### Return value

A `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
--------

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.MAX\_NUMBER\_OF\_STATIC\_RULESETS
=======================================================

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

Its value is `50`.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.SESSION\_RULESET\_ID
==========================================

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

Its value is `"_session"`.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.getSessionRules
=====================================

Returns the active set of session scoped rules for the extension.

Syntax
------


```js
let sessionRules = await browser.declarativeNetRequest.getSessionRules();
```

### Parameters

This function takes no parameters.

### Return value

A `Promise` fulfilled with an array of `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
--------

### Example extensions

* dnr-dynamic-with-options
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.Redirect
==============================

Details describing how a redirect should be performed, as the `redirect` property of a `RuleAction`. Only valid for redirect rules.

**Note:**
 A redirect action does not redirect the request, and the request continues as usual when:


* the action does not change the request.
* the redirect URL is invalid (e.g., the value of `redirect.regexSubstitution` is not a valid URL).

Type
----

Values of this type are objects. They contain these properties:

`extensionPath` Optional

A `string`. The path relative to the extension directory. Should start with '/'. The initiator of the request can only follow the redirect when the resource is listed in `web_accessible_resources`.

`regexSubstitution` Optional

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

`declarativeNetRequest.URLTransform`. The URL transformations to perform.

`url` Optional

A `string`. The redirect URL. Redirects to JavaScript URLs are not allowed.

Example extensions
------------------

* dnr-redirect-url
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.getMatchedRules
=====================================

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 not returned.

Syntax
------


```js
let gettingMatchedRules = browser.declarativeNetRequest.getMatchedRules(
    filter                // object
);
```

### Parameters

`filter` Optional

An object to filter the list of matched rules.

`minTimeStamp` Optional

A `number`. If specified, only matches rules after the specified timestamp.

`tabId` Optional

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` that fulfills with an object with these properties:

`rule`

`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
--------

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.getEnabledRulesets
========================================

Returns the IDs for the set of activated static rulesets.

Syntax
------


```js
let rulesetIds = await browser.declarativeNetRequest.getEnabledRulesets();
```

### Parameters

This function takes no parameters.

### Return value

A `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
--------

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.isRegexSupported
======================================

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

Syntax
------


```js
let count = browser.declarativeNetRequest.isRegexSupported(
    regexOptions                // object
);
```

### Parameters

`regexOptions`

An object containing the regular expression to check.

`isCaseSensitive` Optional

`boolean` Whether the regex specified is case sensitive. Default is `true`.

`regex`

`string` The regular expression to check.

`requireCapturing` Optional

`boolean` Whether the regex specified requires capturing. Capturing is only required for redirect rules that specify a regexSubstitution action. The default is false.


### Return value

A `Promise` that fulfills with an object with these properties:

`isSupported`

`boolean` Whether the regular expression is supported.

`reason` Optional

`string` Specifies the reason why the regular expression is not supported. Possible values are `"syntaxError"` and `"memoryLimitExceeded"`. Only provided if `isSupported` is false.

If the request fails, the promise is rejected with an error message.

Examples
--------

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
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, or more dynamically through the `declarativeNetRequest.updateDynamicRules` or `declarativeNetRequest.updateSessionRules` methods.

See Rules on the API overview page for more information about rules.

Type
----

Values of this type are objects. They contain these properties:

`action`

`declarativeNetRequest.RuleAction`. The action to take if this rule is matched.

`condition`

`declarativeNetRequest.RuleCondition`. The condition under which this rule is triggered.

`id`

`number`. An ID that uniquely identifies a rule within a ruleset. Mandatory and should be >= 1.

`priority` Optional

`number`. Rule priority. Defaults to 1. When specified, should be >= 1. See Matching precedents for details on how priority affects which rules are applied.

Example extensions
------------------

* dnr-block-only
* dnr-dynamic-with-options
* dnr-redirect-url
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.updateEnabledRulesets
===========================================

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 determines the set of enabled static rulesets on each extension update.

Syntax
------


```js
let updatedRulesets = browser.declarativeNetRequest.updateEnabledRulesets(
    options                // object
);
```

### Parameters

`options`

An object detailing the rulesets to activate or deactivate in the extension's static rulesets.

`disableRulesetIds` Optional

An array of `string`. IDs of static Rulesets to deactivated.

`enableRulesetIds` Optional

An array of `string`. IDs of static Rulesets to activated.


### Return value

A `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
--------

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.MAX\_NUMBER\_OF\_REGEX\_RULES
===================================================

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

In Chrome, its value is 1000, and this limit is evaluated separately for the set of dynamic and session rules, and those specified in the rule resources file.

In Firefox, this limit is evaluated separately per ruleset.

In Safari, there is no separate limit on the number of `regexFilter` rules.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.