WebRequest.jsm

The WebRequest module provides an API to add event listeners for the various stages of making an HTTP request. The event listener receives detailed information about the request, and can modify or cancel the request.

You can use this API to implement a content policy in an add-on (for example, an ad or script blocker). Previously you would use nsIContentPolicy for this, but in multiprocess Firefox you can't use nsIContentPolicy in the chrome process. More generally, you can also use this API instead of HTTP request observers. You can use WebRequest.jsm in either the chrome or content processes.

The WebRequest API is modeled on Chrome's webRequest extension API, which makes it easier to write cross-browser add-on code. There are some differences between this API and Chrome's, though: see Chrome incompatibilities for the details.

Usage

To import WebRequest, use code like:

let {WebRequest} = Cu.import("resource://gre/modules/WebRequest.jsm", {});

The WebRequest object has the following properties, each of which corresponds to a specific stage in executing a web request:

• onBeforeRequest
• onBeforeSendHeaders
• onSendHeaders
• onHeadersReceived
• onResponseStarted
• onCompleted

Each of these objects defines two functions:

• addListener(callback, filter, opt_extraInfoSpec)
• removeListener(callback)

Adding listeners

Use addListener to add a listener to a particular event. It takes one mandatory argument and two optional arguments, as detailed below.

Some examples of using addListener().

To remove a listener for an event, call removeListener on the event in question, passing it the listener to remove.

Filtering

The filter argument is the second argument to addListener(). If you don't pass filter, then the listener is invoked for every web request the browser makes that triggers that particular event.

filter is an object that may contain up to two properties: urls and types.

To specify match patterns, first import the "MatchPattern.jsm" module, then construct a MatchPattern. The MatchPattern constructor accepts:

• either: a string defining a single pattern
• or: an array of such strings

Cu.import("resource://gre/modules/MatchPattern.jsm");
let pattern = new MatchPattern("https:/developer.mozilla.org/*");

Cu.import("resource://gre/modules/MatchPattern.jsm");
let pattern = new MatchPattern(["https://mozorg.cdn.mozilla.net/*",
                                "https://mdn.mozillademos.org/*",
                                "https://developer.cdn.mozilla.net/*"]);

See the match patterns article for details on the syntax of the strings you supply. If you supply an array of strings, then a URL matches if it matches any of the strings.

See some examples of using filter.

Modifying & canceling requests

You can use the WebRequest API to modify and cancel network requests. What exactly you're able to do to a network request depends on the stage at which you have intercepted the request: that is, the WebRequest event that your listener is attached to. For example, it obviously doesn't make sense to cancel a network request after it has completed.

The general approach to modifying and canceling requests is this:

• first, pass an array containing the string "blocking" as the third argument to your addListener() call. This tells the browser to wait for your event listener to return before continuing with the request.
• next, return an object from the listener that contains instructions for what the browser should do with this request.

There are four things you can do with a request:

• cancel it
• redirect it
• modify request headers
• modify response headers.

To perform one of these operations, include a property with the appropriate name in the object returned from the listener, and assign it the desired value, as detailed in the table below:

See some examples of canceling, redirecting, and modifying request headers.

Events

The events exported by WebRequest.jsm are triggered at the various stages of making a request.

This section describes the stage corresponding to each event. It also documents two data structures that vary from one event to another:

• the opt_extraInfoSpec argument to addListener()
• the properties of the argument passed to the listener.

onBeforeRequest

This event is triggered when a request is about to be made, and before headers are available. This is a good place to listen if you want to cancel the request.

opt_extraInfoSpec values

Listener argument

onBeforeSendHeaders

This event is triggered before sending any HTTP data, but after all HTTP headers are available. This is a good place to listen if you want to modify HTTP headers.

opt_extraInfoSpec values

Listener argument

onSendHeaders

Triggered just before sending headers. If you modified headers in onBeforeSendHeaders, you'll see the modified version here. Note that you can't pass "blocking" for this event, so you can't modify or cancel the request from this event: it's informational only.

opt_extraInfoSpec values

Listener argument

onHeadersReceived

Triggered once response headers have been received. You can use this event to modify HTTP response headers.

opt_extraInfoSpec values

Listener argument

onResponseStarted

Triggered once the browser has started to receive the response body. Note that you can't pass "blocking" for this event, so you can't modify or cancel the request from this event: it's informational only.

opt_extraInfoSpec values

Listener argument

onCompleted

Triggered when the response has been received. Note that you can't pass "blocking" for this event, so you can't modify or cancel the request from this event: it's informational only.

opt_extraInfoSpec values

Listener argument

Types

Resource types

The resource type string identifies the kind of resource being fetched. It's used in two places: filtering requests by type, and as the type property of the argument passed to the listener.

The following types are supported:

HTTP headers

HTTPs headers are represented as objects with two properties, name and value:

Chrome incompatibilities

Although this API is modeled on Chrome's webRequest extension API, there are some differences. We're working on addressing them, though.

• filtering by windowId and tabId is not supported.
• the onAuthRequired, onBeforeRedirect, and onErrorOccurred events are not supported.
• the "requestBody" instruction in opt_extraInfoSpec is not supported.
• redirection is not allowed in onBeforeRequest or onHeadersReceived, but is allowed in onBeforeSendHeaders. See bug 1176092.
• handlerBehaviorChanged() is not supported.
• requestId is not included in the argument passed to the listener.

Examples

Basic examples

This example just logs the URL for every request initiated:

let {WebRequest} = Cu.import("resource://gre/modules/WebRequest.jsm", {});
WebRequest.onBeforeRequest.addListener(logURL);
function logURL(e) {
  console.log("Loading: " + e.url);
}

Filtering

This example logs URLs for requests under "https://developer.mozilla.org/":

let {WebRequest} = Cu.import("resource://gre/modules/WebRequest.jsm", {});
Cu.import("resource://gre/modules/MatchPattern.jsm");
let pattern = new MatchPattern("https:/developer.mozilla.org/*");
WebRequest.onBeforeRequest.addListener(logURL, {urls: pattern});
function logURL(e) {
  console.log("Loading: " + e.url);
}

This listener will be invoked for requests matching any of the three patterns, where the resource type is "stylesheet" or "image":

let {WebRequest} = Cu.import("resource://gre/modules/WebRequest.jsm", {});
Cu.import("resource://gre/modules/MatchPattern.jsm");
let pattern = new MatchPattern(["https://mozorg.cdn.mozilla.net/*",
                                "https://mdn.mozillademos.org/*",
                                "https://developer.cdn.mozilla.net/*"]);
WebRequest.onBeforeRequest.addListener(listener, {
                                         urls: pattern,
                                         types: ["image", "stylesheet"]
                                       });
function listener(e) {
  console.log("Matched: " + e.url);
}

Canceling

This example cancels requests to load content from "http://example.org/":

let {WebRequest} = Cu.import("resource://gre/modules/WebRequest.jsm", {});
Cu.import("resource://gre/modules/MatchPattern.jsm");
let pattern = new MatchPattern("http://example.org/*");
WebRequest.onBeforeRequest.addListener(cancelRequest,
                                       {urls: pattern},
                                       ["blocking"]);
function cancelRequest(e) {
  console.log("Canceling: " + e.url);
  return {cancel: true};
}

This code cancels requests for images that are made to URLs under "https://mdn.mozillademos.org/":

let {WebRequest} = Cu.import("resource://gre/modules/WebRequest.jsm", {});
Cu.import("resource://gre/modules/MatchPattern.jsm");
let pattern = new MatchPattern("https://mdn.mozillademos.org/*");
WebRequest.onBeforeRequest.addListener(cancelImages,
                                       {
                                         urls: pattern,
                                         types: ["image"]
                                       },
                                       ["blocking"]);
function cancelImages(e) {
  console.log("Canceling: " + e.url);
  return {cancel: true};
}

Redirecting

This code replaces, by redirection, all network requests for images that are made to URLs under "https://mdn.mozillademos.org/":

let {WebRequest} = Cu.import("resource://gre/modules/WebRequest.jsm", {});
Cu.import("resource://gre/modules/MatchPattern.jsm");
let pattern = new MatchPattern("https://mdn.mozillademos.org/*");
WebRequest.onBeforeSendHeaders.addListener(redirect,
                                           {
                                             urls: pattern,
                                             types: ["image"]
                                           },
                                           ["blocking"]);
function redirect(e) {
  console.log("Redirecting: " + e.url);
  return {redirectUrl: "https://38.media.tumblr.com/tumblr_ldbj01lZiP1qe0eclo1_500.gif"}; }

Modifying headers

This code changes the User Agent header so the browser identifies itself as IE 11, but only when visiting pages under "http://useragentstring.com/":

let {WebRequest} = Cu.import("resource://gre/modules/WebRequest.jsm", {});
Cu.import("resource://gre/modules/MatchPattern.jsm");
let pattern = new MatchPattern("http://useragentstring.com/*");
let ua = "Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; AS; rv:11.0) like Gecko";
WebRequest.onBeforeSendHeaders.addListener(changeUserAgent,
                                           {
                                             urls: pattern
                                           },
                                           ["blocking", "requestHeaders"]);
function changeUserAgent(e) {
  for (let header of e.requestHeaders) {
    if (header.name == "User-Agent") {
      header.value = ua;
    }
  }
  return {requestHeaders: e.requestHeaders};
}