recursal/MDN huggingface dataset:
menus.removeAll()
=================

Removes all menu items added by the extension.

For compatibility with other browsers, Firefox makes this method available via the `contextMenus` namespace as well as the `menus` namespace.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let removing = browser.menus.removeAll()
```

### Parameters

None.

### Return value

A `Promise` that will be fulfilled with no arguments when all items have been removed.

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

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

Examples
--------

This example adds two menu items. When the user clicks the item labeled "Remove all!", the extension removes both items using `removeAll()`.


```js
function onRemoved() {
  console.log("items removed successfully");
}

browser.menus.create({
  id: "click-me",
  title: "Click me!",
  contexts: ["all"],
});

browser.menus.create({
  id: "remove-all",
  title: "Remove all!",
  contexts: ["all"],
});

browser.menus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === "remove-all") {
    let removing = browser.menus.removeAll();
    removing.then(onRemoved);
  }
});
```


**Note:** This API is based on Chromium's `chrome.contextMenus` API. This documentation is derived from `context_menus.json` in the Chromium code.
identity.getRedirectURL()
=========================

Generates a URL that you can use as a redirect URL.

The URL is derived from your extension's ID, so if you use this function you should probably set your extension's ID explicitly using the `browser_specific_settings` key (otherwise, each time you temporarily install the extension, you'll get a different redirect URL).

See Getting a redirect URL for more information on redirect URLs.

Syntax
------


```js
let redirectURL = browser.identity.getRedirectURL()
```

### Parameters

None.

### Return value

A string containing a redirect URL value.

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

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

Examples
--------

Get the redirect URL:


```js
let redirectURL = browser.identity.getRedirectURL();
```

### Example extensions

* google-userinfo

**Note:** This API is based on Chromium's `identity` API.
webRequest.CertificateInfo
==========================

An object describing a single X.509 certificate.

The `SecurityInfo` object returned from the `webRequest.getSecurityInfo()` API includes a `certificates` property which is an array of these objects.

Type
----

Values of this type are objects. They contain the following properties:

`fingerprint`

`Object`. An object with the following properties:

`sha1`

`String`. SHA-1 hash of the certificate's DER encoding.

`sha256`

`String`. SHA-256 hash of the certificate's DER encoding.


`isBuiltInRoot`

`Boolean`. `true` if the certificate is one of the trust roots installed in the browser, `false` otherwise.

`issuer`

`String`. Name of the organization that issued this certificate, represented as a Distinguished Name and formatted as a comma-separated list of Relative Distinguished Names, each of the form "type=value".

For example: "CN=DigiCert SHA2 Secure Server CA,O=DigiCert Inc,C=US".

`rawDER`

`Array` of `Number`. If `webRequest.getSecurityInfo()` was called with the `rawDER` option present and set to `true`, this will contain the DER encoding of the certificate.

`serialNumber`

`String`. The certificate's serial number.

`subject`

`String`. Name of the organization that issued this certificate, represented as a Distinguished Name and formatted as a comma-separated list of Relative Distinguished Names, each of the form "type=value".

For example: "CN=\*.cdn.mozilla.net,O=Mozilla Corporation,L=Mountain View,ST=California,C=US".

`subjectPublicKeyInfoDigest`

`Object`. An object containing the following properties:

`sha256`

`String`. Base64 encoded SHA-256 hash of the DER-encoded public key info.


`validity`

`Object`. Validity period for the certificate. An object containing the following properties:

`start`

`Number`. The start of the certificate's validity period, in milliseconds since the epoch.

`end`

`Number`. The end of the certificate's validity period, in milliseconds since the epoch.


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

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

This type is a string, which represents the context in which a resource was fetched in a web request.

It's used to filter the requests you listen to using the webRequest API. For example: you can listen to requests only for images, or only for scripts.

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.

`websocket`

Requests initiating a connection to a server through the WebSocket 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.

**Note:** This API is based on Chromium's `chrome.webRequest` API. This documentation is derived from `web_request.json` in the Chromium code.
webRequest.RequestFilter
========================

An object describing filters to apply to webRequest events.

Type
----

Values of this type are objects. They contain the following properties:

`urls`

`array` of `string`. An array of match patterns. The listener will only be called for requests whose targets match any of the given patterns. Only requests made using HTTP or HTTPS will trigger events, other protocols (such as data: and file:) supported by pattern matching do not trigger events. `view-source:` requests may be matched based on its inner URL.

`types` Optional

`array` of ``webRequest.ResourceType``. A list of resource types (for example, stylesheets, images, scripts). The listener will only be called for requests for resources which are one of the given types.

`tabId` Optional

`integer`. The listener will only be called for requests from the `tab` identified by this ID.

`windowId` Optional

`integer`. The listener will only be called for requests from the `window` identified by this ID.

`incognito` Optional

`boolean`. If provided, requests that do not match the incognito state (`true` or `false`) will be filtered out.

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

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

**Note:** This API is based on Chromium's `chrome.webRequest` API. This documentation is derived from `web_request.json` in the Chromium code.
webRequest.BlockingResponse
===========================

An object of this type is returned by event listeners that have set `"blocking"` in their `extraInfoSpec` argument.

By setting particular properties in `BlockingResponse`, the listener can modify network requests.

Note that you can't set all this object's properties in every listener: the properties you can set are dependent on the event that triggered this listener, as detailed below.

Type
----

Values of this type are objects. They contain the following properties:

`authCredentials` Optional

`object`. If set, the request is made using the given credentials. You can only set this property in `onAuthRequired`. The `authCredentials` property is an object with the following properties:

`username`

`string`. Username to supply.

`password`

`string`. Password to supply.


`cancel` Optional

`boolean`. If `true`, the request is cancelled. You can only set this property in `onBeforeRequest`, `onBeforeSendHeaders`, `onHeadersReceived`, and `onAuthRequired`.

`redirectUrl` Optional

`string`. This is a URL, and if set, the original request is redirected to that URL. You can only set this property in `onBeforeRequest` or `onHeadersReceived`.

Redirections to non-HTTP schemes such as data: are allowed, but they are not currently supported (Firefox bug 707624). Redirects use the same request method as the original request unless initiated from `onHeadersReceived` stage, in which case the redirect uses the GET method.

If an extension wants to redirect a public (e.g. HTTPS) URL to an extension page, the extension's manifest.json file must contain a web\_accessible\_resources key that lists the URL for the extension page.

`requestHeaders` Optional

`webRequest.HttpHeaders`. This is an `HttpHeaders` object, an array in which each object represents a header. If set, the request is made with these headers rather than the original headers. You can only set this property in `onBeforeSendHeaders` .

`responseHeaders` Optional

`webRequest.HttpHeaders`. This is an `HttpHeaders` object, an array in which each object represents a header. If set, the server is assumed to have responded with these response headers instead of the originals. You can only set this property in `onHeadersReceived`. If multiple extensions attempt to set the same header (for example, `Content-Security-Policy`), only one of the changes will be successful.

`upgradeToSecure` Optional

`boolean`. If set to `true` and the original request is an HTTP request, this will prevent the original request from being sent and instead make a secure (HTTPS) request. If any extension returns `redirectUrl` in `onBeforeRequest`, then `upgradeToSecure` will be ignored for that request. You can only set this property in `onBeforeRequest`.

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

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

**Note:** This API is based on Chromium's `chrome.webRequest` API. This documentation is derived from `web_request.json` in the Chromium code.
webRequest.handlerBehaviorChanged()
===================================

This function can be used to ensure that event listeners are applied correctly when pages are in the browser's in-memory cache. If the browser has loaded a page, and the page is reloaded, the browser may reload the page from its in-memory cache, and in this case, events will not be triggered for the request.

Suppose an extension's job is to block web requests against a pattern, and the following scenario happens:

* The user loads a page that includes a particular request, and the pattern permits the request.
* The resource is loaded and cached in memory.
* The extension's patterns are updated, in such a way that the resource would no longer be permitted.
* The user reloads the page.

Because the page will be reloaded from the memory cache, the listener may not be called again, and the request will be loaded despite the extension's new policy.

The `handlerBehaviorChanged()` function is designed to address this problem. It flushes the in-memory cache, so that page reloads will trigger event listeners.

Because `handlerBehaviorChanged()` flushes the cache, it can be expensive and bad for performance. The webRequest module defines a read-only property `MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES`: making more calls than this number in 10 minutes will have no effect.

The implementation of caching, hence the need for this function, varies from one browser to another, so in some browsers this function does nothing.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let flushingCache = browser.webRequest.handlerBehaviorChanged()
```

### Parameters

None.

### Return value

A `Promise` that will be fulfilled with no arguments, when the operation has completed.

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

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

Examples
--------

In the following snippet, we flush the in-memory cache via a call to `handlerBehaviorChanged()`, and report this action by logging an appropriate message to the console.


```js
function onFlushed() {
  console.log(`In-memory cache flushed`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

let flushingCache = browser.webRequest.handlerBehaviorChanged();
flushingCache.then(onFlushed, onError);
```


**Note:** This API is based on Chromium's `chrome.webRequest` API. This documentation is derived from `web_request.json` in the Chromium code.
webRequest.MAX\_HANDLER\_BEHAVIOR\_CHANGED\_CALLS\_PER\_10\_MINUTES
===================================================================

The maximum number of times that ``handlerBehaviorChanged()`` can be called in a 10 minute period.

This property is read-only.

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

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

**Note:** This API is based on Chromium's `chrome.webRequest` API. This documentation is derived from `web_request.json` in the Chromium code.
webRequest.HttpHeaders
======================

An array of HTTP headers. Each header is represented as an object with two properties: `name` and either `value` or `binaryValue`.

Type
----

An `array` of `object`s. Each object has the following properties:

`name`

`string`. Name of the HTTP header.

`value` Optional

`string`. Value of the HTTP header if it can be represented by UTF-8. Either this property or `binaryValue` must be present.

`binaryValue` Optional

`array` of `integer`. Value of the HTTP header if it cannot be represented by UTF-8, represented as bytes (0..255). Either this property or `value` must be present.

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

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

**Note:** This API is based on Chromium's `chrome.webRequest` API. This documentation is derived from `web_request.json` in the Chromium code.
webRequest.UploadData
=====================

Contains data uploaded in a URL request.

Type
----

Values of this type are objects. They contain the following properties:

`bytes` Optional

`any`. An ArrayBuffer with a copy of the data.

`file` Optional

`string`. A string with the file's path and name.

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

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

**Note:** This API is based on Chromium's `chrome.webRequest` API. This documentation is derived from `web_request.json` in the Chromium code.
webRequest.StreamFilter.disconnect()
====================================

Disconnects the filter from the request. After this, the browser will continue to process the response, but no more filter events will fire, and no more filter function calls will have any effect. Note the difference between this function and `close()`. With `disconnect()`, the browser will continue to process any further response data, but it won't be accessible through the filter. With `close()`, the browser will ignore any response data that hasn't already been passed through to the rendering engine.

You should always call `disconnect()` or `close()` once you don't need to interact with the response any further.

You can't call this function until after the `onstart` event has fired.

Syntax
------


```js
filter.disconnect()
```

### Parameters

None.

### Return value

None.

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

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

Examples
--------

This example will prepend "preface text" to the response body. It then disconnects, so the original response body will load normally:


```js
function listener(details) {
  let filter = browser.webRequest.filterResponseData(details.requestId);

  filter.onstart = (event) => {
    console.log("started");
    let encoder = new TextEncoder();
    filter.write(encoder.encode("preface text"));
    filter.disconnect();
  };
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  { urls: ["https://example.org/"], types: ["main\_frame"] },
  ["blocking"],
);
```
webRequest.StreamFilter.error
=============================

A string that will contain an error message after the `onerror` event has fired.

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

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

Examples
--------

This example adds an `onerror` listener which logs the value of `error`.


```js
function listener(details) {
  let filter = browser.webRequest.filterResponseData("12345");

  filter.onerror = (event) => {
    console.log(`Error: ${filter.error}`);
  };

  //return {}; // not needed
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  { urls: ["<all\_urls>"], types: ["main\_frame"] },
  ["blocking"],
);
```
webRequest.StreamFilter.resume()
================================

Resumes a request that was previously suspended through a call to `suspend()`.

You can't call this function until after the `onstart` event has fired.

Syntax
------


```js
StreamFilter.resume()
```

### Parameters

None.

### Return value

None.

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

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

Examples
--------

This example uses suspend/resume to delay a web request.


```js
function listener(details) {
  let filter = browser.webRequest.filterResponseData(details.requestId);

  filter.onstart = (event) => {
    filter.suspend();

    setTimeout(() => {
      filter.resume();
      filter.disconnect();
    }, 1000);
  };
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  { urls: ["https://example.org/"], types: ["main\_frame"] },
  ["blocking"],
);
```
webRequest.StreamFilter.onstart
===============================

An event handler that will be called when the stream is opened and is about to begin delivering data. From this point on, the extension may use filter functions like `write()`, `disconnect()`, or `close()`.

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

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

Examples
--------

This example will replace the page content with "replacement text":


```js
function listener(details) {
  let filter = browser.webRequest.filterResponseData(details.requestId);

  filter.onstart = (event) => {
    console.log("started");
    let encoder = new TextEncoder();
    filter.write(encoder.encode("replacement content"));
    filter.close();
  };
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  { urls: ["https://example.org/"], types: ["main\_frame"] },
  ["blocking"],
);
```
webRequest.StreamFilter.close()
===============================

Closes the request. After this is called, no further response data will be passed to the browser's rendering engine and no more filter events will be given to the extension.

Note the difference between this function and `disconnect()`. With `disconnect()`, the browser will continue to process any further response data, but it won't be accessible through the filter. With `close()`, the browser will ignore any response data that hasn't already been passed through to the rendering engine.

You should always call `close()` or `disconnect()` once you don't need to interact with the response any further.

You can't call this function until after the `onstart` event has fired.

Syntax
------


```js
filter.close()
```

### Parameters

None.

### Return value

None.

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

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

Examples
--------

This example will replace the page content with "replacement text":


```js
function listener(details) {
  let filter = browser.webRequest.filterResponseData(details.requestId);

  filter.onstart = (event) => {
    console.log("started");
    let encoder = new TextEncoder();
    filter.write(encoder.encode("replacement content"));
    filter.close();
  };
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  { urls: ["https://example.org/"], types: ["main\_frame"] },
  ["blocking"],
);
```
webRequest.StreamFilter.onerror
===============================

An event handler that will be called when an error occurs. This is most often because an invalid request ID was passed into `webRequest.filterResponseData()`.

After this event is fired, the `webRequest.StreamFilter.error` property will contain a message giving more information about the error.

Note that this event is **not** triggered for network errors.

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

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

Examples
--------

This example adds an `onerror` listener which logs the value of `webRequest.StreamFilter.error`.


```js
function listener(details) {
  // This example seems not useful because,
  // an extension would use "details.requestId"
  let filter = browser.webRequest.filterResponseData("12345");

  filter.onerror = (event) => {
    console.log(`Error: ${filter.error}`);
  };
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  { urls: ["<all\_urls>"], types: ["main\_frame"] },
  ["blocking"],
);
```


This example uses no `"blocking"`.


```js
function listener(details) {
  let filter = browser.webRequest.filterResponseData(details.requestId);

  filter.onerror = (event) => {
    console.log(`Error: ${filter.error}`); // Error: Invalid request ID
  };
}

browser.webRequest.onBeforeRequest.addListener(listener, {
  urls: ["<all\_urls>"],
  types: ["main\_frame"],
});
```